7.2 KiB
ADDED Requirements
Requirement: Platform persists approved bounded execution input
Platform SHALL authorize config/file operations against server ownership, plugin permissions, endpoint ownership, selected runtime binding, declared logical target, and scoped input/artifact reference before creating a Job. Approved bounded bytes, workspace profile, expected version/checksum, and read limit SHALL persist with the Job and SHALL remain private from user Job DTOs.
Scenario: Approved config survives Platform restart
- WHEN a reviewed config write is queued and Platform restarts before Run claims it
- THEN the same approved content, logical ref, expected version/checksum, and workspace scope remain available to the fenced Run assignment
Scenario: Cross-owner or wrong-endpoint dispatch is attempted
- WHEN a caller lacks server authority or a Job/ref belongs to another server or endpoint
- THEN Platform rejects the request without persisting or dispatching execution input
Requirement: Workspace resolution prevents boundary escape
Run SHALL map the Platform-approved server ID and profile key into a private workspace and SHALL reject absolute paths, traversal, backslashes, symlinked components, symlink targets, reserved state/action targets, non-directory parents, device files, FIFOs, sockets, and any path outside the selected scope.
Scenario: Traversal or absolute target is submitted
- WHEN a config/file Job contains a traversal, absolute, or otherwise invalid logical target
- THEN Platform or Run rejects it before filesystem access
Scenario: Symlink escapes workspace
- WHEN any parent or final target is a symlink that resolves inside or outside the workspace
- THEN Run rejects the operation and leaves the referenced file unchanged
Scenario: Device or special file is targeted
- WHEN a read or write resolves to a device, FIFO, socket, or other non-regular file
- THEN Run rejects the operation without opening the special file
Requirement: Config and file writes are atomic compare-and-swap operations
Run SHALL enforce bounded input, compare the current controlled version/checksum to the expected values, write an owner-only temporary regular file in the verified target directory, fsync and atomically rename it, and persist updated version/checksum metadata only after success.
Scenario: Atomic write succeeds
- WHEN expected version/checksum match and the approved input is valid
- THEN readers observe either the complete old content or complete new content and Run returns the incremented version, checksum, size, and safe audit summary
Scenario: Expected version conflicts
- WHEN the current controlled version differs from
expectedVersion - THEN Run returns a typed conflict and does not replace the file or metadata
Scenario: Expected checksum conflicts
- WHEN the current file checksum differs from
expectedChecksum - THEN Run returns a typed conflict and leaves content/version unchanged
Scenario: Write is cancelled before rename
- WHEN cancellation or attempt invalidation is observed before atomic commit
- THEN Run removes the temporary file and leaves the prior target/version unchanged
Requirement: Reads are bounded and typed
Run SHALL read only regular contained files, enforce the assignment's maximum before and during I/O, compute SHA-256, and return a typed result with private bounded content plus safe version/checksum/size/audit metadata.
Scenario: Bounded read succeeds
- WHEN a contained regular file is no larger than the approved limit
- THEN Run returns its exact bounded content privately and reports matching checksum, size, and controlled version
Scenario: File exceeds read limit
- WHEN file metadata or streamed bytes exceed the approved limit
- THEN Run fails with a bounded size error and does not return partial content
Requirement: Terminal config results update durable Platform state
Platform SHALL validate typed result/capability consistency after existing fencing, persist the safe result, and only then project a successful config write into the server's durable config content, checksum, version, and update time. Failed, cancelled, stale, or conflicting results MUST NOT mutate config state.
Scenario: Config write result is accepted
- WHEN the current fenced attempt returns a successful config result matching its approved content checksum and next version
- THEN Platform updates the server config and authorized config reads return the new content/version/checksum
Scenario: Stale config result arrives
- WHEN a stale attempt, invalid signature/session, wrong endpoint, or cancelled attempt returns a config result
- THEN Platform rejects it and preserves the prior config content/version/checksum
Requirement: AI suggestions remain review-before-write
AI-assisted configuration SHALL continue to produce a reviewable diff and MUST NOT dispatch a config write until an authorized user approves that diff with the current expected version/checksum.
Scenario: AI suggestion is generated
- WHEN AI proposes configuration content
- THEN Platform and platform_web show a reviewable diff without creating a Run write Job
Scenario: User approves suggestion
- WHEN an authorized user approves the current diff
- THEN Platform persists the approved input and dispatches it through the normal fenced config Job path
Requirement: User projections remain credential-free
Platform and platform_web SHALL expose only authorized process/config/file state, version, checksum, size, conflict/error classification, and bounded audit summary, and MUST NOT expose approved private Job content, raw AI keys, Run tokens, leases/hashes, secret refs, host paths, PID, sockets, or credentials.
Scenario: Authorized result is rendered
- WHEN an authorized user views config or operation history
- THEN platform_web renders safe typed metadata using existing theme surfaces and existing 401/403 handling
Scenario: Plugin requests a file operation
- WHEN a plugin page submits a declared scoped file request
- THEN it receives only the Platform-owned Job/safe result projection and no direct Run or workspace information
Requirement: Config/file traffic remains channel-isolated
Config/file execution SHALL use bounded Job payloads and MUST NOT carry log batches or artifact chunks. Slow config/file I/O MUST NOT block control heartbeat, Job acknowledgement/result, or the independent log/artifact routes.
Scenario: File execution blocks
- WHEN a file executor is deliberately blocked
- THEN control heartbeat and unrelated Job acknowledgement/result requests continue within their own deadlines
Requirement: Roadmap boundary remains explicit
Completion of this capability MUST NOT be reported as readiness for durable logs/artifacts/metrics/backups, remote adapters, dependency installation, Run self-update, client-manager lifecycle, production scaling/alerts/plugin lifecycle, or real AI-provider integration.
Scenario: Change is handed off
- WHEN implementation and verification complete
- THEN the handoff identifies those later-route capabilities as not implemented by this change