diff --git a/docs/ARCHITECTURE_DECISIONS.md b/docs/ARCHITECTURE_DECISIONS.md index c366951..18adbd8 100644 --- a/docs/ARCHITECTURE_DECISIONS.md +++ b/docs/ARCHITECTURE_DECISIONS.md @@ -661,6 +661,20 @@ guard/resource binding, durable attempt identity, sealed artifact-manifest digest, and actual terminal outcome. Product-storage schema metadata is not a registered receipt/control-plane schema change. +The proposed `CandidateAttemptStore/v1` is registered control-plane receipt +storage, not product storage. `AttemptRecord` would bind `id`, protocol and +tuple digests, `issued|executing|sealed|finalized` state, authenticated project +and area, E/S/A sets, frozen definition/input digests, guard and lease bindings, +artifact-manifest digest, observed terminal, process fence, and timestamps. +`ResultRecord` would bind `attemptId`, `PASS|FAIL|INCOMPLETE`, attributable +outcome proof, seal digest, and optional `receiptId`; `UNKNOWN` has no +`ResultRecord` and remains nonfinalized guarded evidence. A separately reviewed +and owner-authorized Kernel provisioner—not a source check, candidate engine, +or adapter—would have to create the store under a qualified registered receipt +schema. Until then, missing or incompatible storage refuses; it is not silently +created, migrated, or activated. `ReceiptAdapter/v1` opens an already-compatible +registered schema and performs DML only. + The Kernel would derive a native candidate context from the registered manifest/root, registered area, and exact clean managed candidate, rather than accepting caller paths, manifests, database handles, receipt adapters, commits, @@ -683,30 +697,43 @@ manifest/root, and XDG state. It may return a permanently nonpromotable relabeled into registered receipt storage, and Integration, Backlog, and Delivery would not consume it as a gate result. +That fixture nonpromotion does not make every source subject unusable. A future +explicitly reviewed candidate-source result may satisfy a prelanding integration +requirement for its exact unlanded subject; requiring an independently +authenticated post-landing operational subject for that same prelanding +condition would be circular. Operational gates still require their own +independently authenticated operational-runtime subject. + The proposed worker transport is an adapter-created opaque fresh single-use attempt with a dedicated artifact directory. The worker would receive only a verified immutable snapshot, frozen definition, bounded arguments, an explicit environment allowlist, and per-attempt `HOME`, `TMPDIR`, and XDG homes; it would receive neither registered root/manifest/database locations nor provider -credential variables. The adapter-owned collector would accept regular files -only below the attempt directory, reject links and traversal, and seal a hashed -artifact manifest. +credential variables. It would receive no registered root, manifest, database, +adapter identity, writable receipt path, or migration capability. A process +fence would record direct-child and process-group observation; cancellation +alone is `UNKNOWN`. The adapter-created attempt directory would yield only a +write-once `ArtifactManifestV1`: canonical sorted relative paths, SHA-256, and +byte lengths for regular files. Links, traversal, special files, overwrite, or +post-seal digest drift would refuse. -The proposed lifecycle is durable guarded-attempt creation, execution over one -opaque worker transport, adapter observation of an actual terminal outcome, -manifest sealing, and an atomic compare-and-swap transaction that consumes the -attempt while persisting its sealed result record after full tuple -revalidation. A fully revalidated `PASS` inserts its registered receipt in that -same transaction; proven non-PASS terminal evidence is atomically retained for -observability but cannot qualify a passing gate. No consumed attempt persists -without its associated receipt or terminal-evidence record. `PASS`, `FAIL`, and -proven `INCOMPLETE` stay distinct. A non-proven interruption, cancellation, or -ambiguous commit is `UNKNOWN`: it creates no receipt, is not consumed-and-lost, -and retains sealed evidence and guards for exact-identity reconciliation without -replay or automatic release. A proven terminal failure is not `UNKNOWN`; where -it has durable evidence and no live descendants, existing policy may scope its -cleanup without creating a new automatic-release authority. Consumed or replayed -identifiers fail closed. +`FinalizeV1` would require exact tuple, active guard/lease bindings, +process-fence evidence, and sealed `ArtifactManifestV1`. One `BEGIN IMMEDIATE` +compare-and-swap transaction would finalize only the matching sealed open +attempt, insert `ResultRecord`, and insert a PASS receipt in that same +transaction only for PASS. Duplicate, wrong-tuple, inactive-binding, nonsealed, +or finalized attempts fail closed; no durable finalization exists without its +PASS receipt or non-PASS result record. + +`PASS`, `FAIL`, and proven `INCOMPLETE` remain distinct terminal evidence; +non-PASS is durable observable evidence but cannot pass a gate. Error, signal, +timeout, ENOBUFS, malformed transport, drift, and zero-exit mutation are +INCOMPLETE only when proven. Unproven interruption, cancellation, ambiguous +commit, or uncertain persistence is `UNKNOWN`: no terminal ResultRecord, no +receipt, no replay/retry/release, and retained evidence, guards, leases, and +resources for exact-identity reconciliation. A proven FAIL or INCOMPLETE with +durable attribution and no live descendants may take only existing-policy scoped +cleanup, separately recorded from receipt eligibility; it never becomes PASS. These withheld capabilities are an authority boundary, not an OS filesystem sandbox. They stop the proposed interfaces from granting registered-root or diff --git a/docs/PORTABLE_AGENT_FLEET_SPEC.md b/docs/PORTABLE_AGENT_FLEET_SPEC.md index fa4322f..4dbd2fa 100644 --- a/docs/PORTABLE_AGENT_FLEET_SPEC.md +++ b/docs/PORTABLE_AGENT_FLEET_SPEC.md @@ -2006,6 +2006,29 @@ binding, durable attempt identity, sealed artifact-manifest digest, and actual terminal outcome. Product-storage metadata must never be interpreted as a control-plane migration request. +#### Proposed `CandidateAttemptStore/v1` and result records + +`CandidateAttemptStore/v1` would be registered control-plane receipt storage, +not product storage. Its `AttemptRecord` would contain: `id`, +`protocolVersion`, `tupleDigest`, state (`issued`, `executing`, `sealed`, or +`finalized`), authenticated project and area, the E digest set, tagged S union, +the A digest/schema set, frozen definition and input digests, guard and lease +bindings, `artifactManifestDigest`, observed terminal state, `processFence`, and +created/finalized timestamps. The proposed state machine is only +`issued -> executing -> sealed -> finalized`; a final state never reopens. + +The proposed `ResultRecord` would contain `attemptId`, terminal +`PASS|FAIL|INCOMPLETE`, attributable outcome proof, seal digest, and optional +`receiptId`. `UNKNOWN` has no `ResultRecord` and remains nonfinalized attempt +evidence with its guards. The missing store is not created by a source check, +candidate engine, or receipt adapter. A future Kernel-approved provisioner +would need separately reviewed receipt-schema qualification and explicit owner +authorization to create it; that future provisioner is distinct from this +proposal and is not a live migration or activation. `ReceiptAdapter/v1` would +open only an already-compatible registered receipt schema and perform DML only; +missing or incompatible storage must refuse before execution without adapter +DDL, migration, relabeling, or root redirection. + The registered-root authenticator, rather than a caller, would derive the registered area, project/install identity, clean managed subject, exact product commit, and root binding. The initial proposed CLI therefore accepts no caller @@ -2045,29 +2068,37 @@ frozen definition, the bounded command arguments, and an explicit environment allowlist. The proposed baseline gives it per-attempt `HOME`, `TMPDIR`, `XDG_CACHE_HOME`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `XDG_STATE_HOME`, a dedicated artifact directory, and no inherited registered-state locations or -provider credential variables. The adapter-owned collector accepts only -regular artifacts beneath that attempt directory, refuses path traversal and -links, and hashes a sealed manifest. +provider credential variables. It receives no registered root, manifest, +database, adapter identity, writable receipt path, or migration capability. A +proposed process fence records direct-child and process-group observation; +cancellation alone is not terminal proof. The adapter-owned collector accepts +only an `ArtifactManifestV1` of canonically sorted relative paths, SHA-256, and +byte lengths for regular files beneath its adapter-created attempt directory. +Links, traversal, special files, overwrite, post-seal digest drift, or a +noncanonical manifest refuse. The sealed manifest is write-once adapter +evidence, not worker-controlled receipt storage. -The proposed lifecycle is: durable guarded attempt creation; one worker -transport; execution; adapter-observed proven terminal outcome; manifest -sealing; then one atomic compare-and-swap finalization that consumes the attempt -and persists its sealed result record after full tuple revalidation. A fully -revalidated `PASS` inserts its registered receipt in that same action; a proven -non-PASS atomically persists its terminal evidence record, which cannot satisfy -a passing receipt or gate. There is never a durable consumed attempt without its -corresponding receipt or terminal-evidence record. `PASS`, `FAIL`, and proven -`INCOMPLETE` are distinct terminal outcomes. `FAIL` and `INCOMPLETE` remain -observable durable evidence. Error, signal, timeout, ENOBUFS, -malformed transport, input/subject drift, and zero-exit mutation are -`INCOMPLETE` when proven; interruption, cancellation, or an ambiguous commit -without a proven terminal outcome is `UNKNOWN`. `UNKNOWN` creates no receipt, -does not consume-and-lose the attempt, and retains sealed evidence plus existing -resource/worktree guards for exact-identity reconciliation without replay. -Cancellation and `UNKNOWN` permit neither automatic replay nor release. A -proven terminal failure is not `UNKNOWN`; with durable evidence and no live -descendants, it may enter existing-policy scoped cleanup, not a newly authorized -automatic release. Consumed or replayed attempt identifiers fail closed. +`FinalizeV1` would require the exact tuple, active guard and lease bindings, +process-fence evidence, and a sealed `ArtifactManifestV1`. It would use one +`BEGIN IMMEDIATE` compare-and-swap transaction to move only that sealed open +attempt to `finalized`, insert its `ResultRecord`, and, for `PASS`, insert its +receipt in the same transaction. A duplicate, wrong tuple, inactive/mismatched +guard or lease, nonsealed attempt, or already-finalized attempt fails closed. +There is never a durable consumed/finalized attempt without the corresponding +PASS receipt or non-PASS result record. + +`PASS`, `FAIL`, and proven `INCOMPLETE` are distinct terminal outcomes. `FAIL` +and `INCOMPLETE` remain observable durable evidence even though neither is +receipt-eligible for a passing gate. Error, signal, timeout, ENOBUFS, malformed +transport, input/subject drift, and zero-exit mutation are `INCOMPLETE` only +when proven. Interruption, cancellation, ambiguous commit, or uncertain +persistence without proven terminal outcome is `UNKNOWN`: it has no terminal +`ResultRecord`, retains sealed evidence, guards, leases, and resources for +exact-identity reconciliation, and permits no replay, retry, or release. A +proven `FAIL` or `INCOMPLETE` with durable attribution and no live descendants +may perform only existing-policy scoped cleanup, recorded separately from +receipt eligibility; it never becomes `PASS`. Consumed or replayed attempt IDs +fail closed. Withholding those handles and capabilities is an **authority boundary**, not an operating-system filesystem sandbox. It prevents an authorized interface @@ -2172,11 +2203,13 @@ protection or credential isolation is defense in depth when available. **Status: proposed design contribution only.** This interpretation does not modify the preceding integration requirements or authorize a new check, receipt, command, landing, or policy decision. If a future implementation -accepts a candidate-source result, it would be eligible only for the exact -unlanded commit and the complete proposed tuple in section 18; it would remain -distinct from an installed operational result and would require a fresh -operational run wherever that subject is required. Fixture attestations remain -nonpromotable and cannot satisfy an integration requirement. +accepts an explicitly reviewed candidate-source result, it could feed a +prelanding integration requirement only for the exact unlanded commit and the +complete proposed tuple in section 18. This does not require a post-landing +operational subject to prove that prelanding condition, which would be circular. +Operational gates remain distinct and require their own independently +authenticated operational-runtime subject. Fixture attestations are always +nonpromotable and cannot satisfy any integration requirement. The current registered schema/engine guard remains authoritative: the observed Project Kernel reservation candidate `be1ae951` initializes `ControlPlane`,