browser/openspec/changes/implement-config-write-and-file-dispatch/specs/config-write-and-file-dispatch/spec.md

ADDED Requirements

Requirement: Config diff preview is platform mediated

The platform SHALL provide a config diff preview route that compares current server config with proposed content without dispatching a write.

Scenario: Preview accepted

• WHEN an authorized operator submits proposed config content with the current config version
• THEN the platform MUST return a bounded diff and MUST NOT create a run job

Scenario: Preview rejects stale config

• WHEN proposed config content references a stale config version
• THEN the platform MUST reject the preview and MUST NOT dispatch work

Requirement: Config write approval dispatches scoped job

The platform SHALL dispatch config writes only after an explicit approval request passes validation.

Scenario: Approved config write queued

• WHEN an authorized operator approves a reviewed config diff
• THEN the platform MUST queue a bounded config.write job for the server instance and return job metadata

Scenario: Config write hides unsafe internals

• WHEN the platform dispatches a config write job
• THEN the request and response MUST NOT expose raw host paths, run credentials, direct sockets, or raw secret values

Requirement: File operation dispatch is scoped

The platform SHALL provide scoped file operation dispatch for server/plugin workflows using logical file keys or artifact refs.

Scenario: Scoped file read dispatched

• WHEN an authorized caller requests a declared logical file read
• THEN the platform MUST queue a bounded file read job with scoped target metadata

Scenario: Unsafe file target rejected

• WHEN a request includes an absolute path, parent traversal, raw credential, direct socket, or host-local secret path
• THEN the platform MUST reject the request before creating a job

Requirement: Frontend config writes use approval APIs

The frontend SHALL use platform config preview and approval APIs for config writes.

Scenario: User previews and approves config write

• WHEN a user edits config, previews the diff, and confirms approval
• THEN ServerDetailPage MUST call the approval API and render the returned platform job state

Scenario: Frontend avoids generic write job creation

• WHEN a config write is initiated from manual edit or AI suggestion
• THEN the frontend MUST NOT create a generic config.write job directly through POST /jobs