105 lines
7.2 KiB
Markdown
105 lines
7.2 KiB
Markdown
## 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
|