diff --git a/ARCHITECTURE_DECISIONS.md b/ARCHITECTURE_DECISIONS.md index aa3ecc1..258447e 100644 --- a/ARCHITECTURE_DECISIONS.md +++ b/ARCHITECTURE_DECISIONS.md @@ -147,6 +147,14 @@ This ledger records repository-level decisions. Feature-level decisions should m - **Decision:** Keep all shared Milestone 14 contracts strict, versioned, storage-independent, and provider neutral in `@founderos/knowledge-schema`. `createProductionProviderReadinessEvaluator` and `createDisabledProductionProviderAdapterHarness` construct the only public readiness facades in `@founderos/knowledge-engine`; each captures one approved static Transport Policy authority at configuration time, returns a frozen object, and rejects per-request authority replacement. The evaluator reuses the exact durable Milestone 12 Delivery and Milestone 13 Invocation verifier, then enforces externally supplied Authorization Decision evidence before Adapter, Credential Reference, Capability, Transport, Rate, or Cost preparation. It does not implement authentication or an authorization-decision engine. Credential handling validates only a logical, fingerprinted reference; no resolver, secret bytes, environment value, authorization header, secret read, or secret storage enters the domain or application boundary. The expected signed Transport Policy comes from the captured deterministic provider-neutral authority keyed by the exact authorized Adapter ID, fingerprint, provider family, and policy version; its single synchronous lookup exposes no URL, client, network, credential, DNS, TLS, or socket operation and is invoked only after Authorization. The caller Policy must equal that authority. Only the Milestone 13 Invocation timeout is constrained by the Transport request timeout: Milestone 13 application-attempt retry and Milestone 14 transport retry are separate controls and are reconstructed independently in Request Plan verification. The Transport policy is HTTPS-only, hostname/port allowlisted, redirect-denying, certificate-validating, size bounded, and represented only by a deterministic verified plan; configured host classification replaces live DNS checks at this milestone. Rate/Capacity and Cost/Budget admission use explicit time, bounded caller-supplied simulation state, deterministic fixture pricing, and integer minor units. Readiness and harness inputs categorically reject Circuit reset during common synchronous capture, before durable authority or policy lookup; Circuit and Health derivation preserve disabled/quarantined containment, fail closed for disabled, open, unavailable, or quarantined state, and bound half-open activity to a dry-run probe. Redaction occurs before bounded deterministic in-memory Logs, Metrics, Traces, and public errors are emitted; no external observability sink exists. Observability readiness is verified before the byte-stable redacted Request Plan is built. Twelve fixed Response Mapping fixtures produce ephemeral, independently verified Milestone 13-compatible evidence without retaining raw provider material or writing the execution Ledger. The disabled harness exposes exactly 11 validation/simulation modes, including Health evaluation, and no execution method. Both public boundaries reject raw Knowledge, Query Results, hidden Context, endpoints, credentials, callbacks, clients, executable Provider payloads, enabled Adapter state, and prebuilt low-level readiness artifacts. The final Decision can be only `not-assessed`, `not-ready`, `ready-for-dry-run`, or `disabled-by-policy`; its complete nested authority is independently recomputed. The final gate is an explicit structural stop, and the production import closure contains no DNS, TLS, socket, HTTP, provider SDK, credential resolver, environment, randomness, or implicit-clock dependency. - **Consequences:** FounderOS can prove production-provider preparation controls and deterministic fixture mapping without creating a public bypass around `invokeGovernedReasoning`, resolving a credential, persisting readiness output, or making a network call. Every public Milestone 14 wrapper rejects hidden, symbolic, accessor-backed, inherited, non-enumerable, and custom-prototype capabilities before reading wrapper values or consulting durable/configuration authority. Gate 10 constructs a private bounded in-memory observability sink, appends the already-redacted bundle exactly once, requires an exact retained snapshot, and binds strict retention evidence into the final Decision before readiness can continue. Only after that Decision verifies does its evaluator issue the exact canonical Decision/evidence pair into a private four-entry `first-issued-fifo-v1` registry; identical issuance is idempotent without refreshing FIFO order. Decision verification requires the original retention evidence, an un-evicted entry from the same evaluator instance, and deterministic reconstruction without creating a sink or emitting again. A fresh evaluator or evicted pair fails closed. No caller can supply a sink or issuance registry, full harness readiness does not duplicate emission, and the issuance authority is neither durable nor cross-process. `ready-for-dry-run` is evidence for non-executing planning only and is not production readiness or permission for live traffic. A real Provider Adapter and its credential-resolution and outbound-transport infrastructure require a later reviewed milestone and new architecture decision. Also deferred are persistence, real provider pricing synchronization, streaming, tool/function calling, Agents, Hermes, MCP, multi-provider routing or failover, authentication and authorization systems, external observability, distributed rate/circuit/credential controls, autonomous planning, and UI. +## ADR-0019: Persist verified provider-readiness evaluations without enabling provider execution + +- **Status:** Proposed +- **Date:** 2026-08-01 +- **Context:** Milestone 14 can issue and verify one deterministic non-executing provider-readiness Decision only through the configured evaluator instance while the exact Decision/evidence pair remains in its private four-entry FIFO registry. That deliberate process-local limit proves issuance but cannot provide restart-safe audit authority or demonstrate reproducibility through a fresh evaluator. Moving next to credential resolution or outbound transport would collapse persistence, secret, network, and provider risk into one boundary before readiness evidence is durably trustworthy. +- **Decision:** Specify strict, versioned, storage-independent durable readiness transaction, permanent global identity ownership, audit, commit-marker, replay-attempt, integrity, recovery, and derived-index contracts in `@founderos/knowledge-schema`. Specify `@founderos/knowledge-engine` as the owner of exact plain-data capture, Milestone 12 ledger verification, reuse of the sole Milestone 13 Delivery/Invocation authority resolver, approved Milestone 14 evaluation and same-instance registration verification, canonical package comparison, registration and replay orchestration, an engine-owned storage port, and a governed local file-backed adapter. The initialized empty ledger will have one explicit deterministic genesis complete-history commitment, zero-event head, and reserved `m15-genesis` marker; atomic installation of the byte-identical fixed marker will be its sole visibility boundary. Registration callers will request ownership, semantic-event, audit-entry, and marker IDs, and the first commit will globally own those coordinates together with its key, request, transaction, and Decision identities. Registration will atomically commit one exact verified Milestone 14 Decision, ordered gate trace, retained non-secret evidence, evaluator configuration projection, and complete Delivery/Invocation identity projection under permanent idempotency and expected-head control. An identical registration retry will repeat the governed resolver and evaluator sequence exactly once, prove exact ownership equality, and return the original without append. Replay after restart will always reconstruct at immutable `originalEvaluationTime` with a fresh approved evaluator and separately assess current admissibility at `replayEvaluatedAt`; a historical `matched` result may coexist with `authorization-expired`. A distinct replay submission records separate historical and current-admissibility evidence; append status exists only in the operation result. An exact replay retry verifies its permanently owned idempotency key and request, attempt, semantic-event, audit-entry, and marker IDs plus the complete original request fingerprint, then returns the original attempt without reassessment or append even when later events have advanced the current head. The sole ledger-head schema will bind exact latest audit-entry, semantic-event, and subject-transaction ID/fingerprint pairs; marker embedding, `readHead()`, and derived `HEAD` will use byte-identical head bytes. The canonical commit marker is computed last under the sole acyclic commitment table and archived immutably with its event. Atomic replacement of a byte-identical fixed current-marker copy is the sole authoritative visibility boundary; separate `HEAD` projections and indexes are derived and rebuildable. Integrity and recovery results will remain ephemeral, non-fingerprinted, and absent from every durable record and log. The first adapter will acquire its cooperative single-writer lock before staging and will use canonical JSON, SHA-256, no automatic stale-lock stealing, atomic same-filesystem publication, restart recovery, safe-path confinement, and fail-closed ambiguous-state handling. +- **Consequences:** FounderOS will be able to audit and independently replay-verify non-executing readiness evaluations across restart without persisting Milestone 14 evaluator-local issuance state or weakening Delivery and Invocation authority. A durable transaction remains evidence only: it cannot refresh Authorization, resolve a credential, authorize live traffic, or bypass a future execution gate. Only Credential Reference IDs and fingerprints may persist. Raw Knowledge, Query Results, hidden Context, secrets, headers, endpoints, provider bodies, clients, callbacks, functions, and executable payloads remain prohibited. The local adapter will be single-machine, same-filesystem, cooperatively locked, and vulnerable to coordinated privileged rollback or directory replacement outside its documented checks; it will not provide distributed coordination or automatic abandoned-lock recovery. Real provider adapters, credential and secret access, HTTP/DNS/TLS/socket/proxy/SDK transport, response ingestion, streaming, tools/functions, Agents, Hermes, MCP, routing, failover, distributed persistence, external observability, UI, deployment, and production enablement remain separately deferred. This ADR remains Proposed until a separately authorized implementation is complete and independently reviewed. + ## ADR template ```markdown diff --git a/DOCUMENTATION_INDEX.md b/DOCUMENTATION_INDEX.md index 0343f29..4c9b6bf 100644 --- a/DOCUMENTATION_INDEX.md +++ b/DOCUMENTATION_INDEX.md @@ -216,6 +216,24 @@ Milestone 14 is implemented by provider-neutral readiness contracts in [`@founde - [Reasoning Authorization Enforcement Boundary Specification v1.0](./docs/milestones/milestone-14/FounderOS_Reasoning_Authorization_Enforcement_Boundary_Specification_v1.0.md) - [Secure Outbound Provider Transport Policy v1.0](./docs/milestones/milestone-14/FounderOS_Secure_Outbound_Provider_Transport_Policy_v1.0.md) +### Milestone 15 — Durable Production-Provider Readiness Evaluation Ledger and Replay Verification Registry Foundation + +**Specified — not implemented.** Milestone 15 defines future durable registration and dual-time fresh-evaluator replay verification for the non-executing Milestone 14 readiness package. Historical reconstruction uses immutable original time; current admissibility uses explicit replay time. One deterministic genesis history/head/marker commitment authorizes the initialized empty ledger, and every later event preserves an immutable archived marker value. Atomic installation of the byte-identical fixed current-marker copy is the sole visibility boundary; the marker-embedded head and `readHead()` are byte-identical, while separate `HEAD` projections and indexes remain derived. Registration callers explicitly request every original-event ID, and integrity/recovery results remain ephemeral. It does not implement runtime contracts, persistence, credential resolution, provider transport, a real provider, or live-execution authority. + +- [Milestone 15 Package README v1.0](./docs/milestones/milestone-15/FounderOS_Milestone_15_Package_README_v1.0.md) +- [Durable Production-Provider Readiness Evaluation Ledger and Replay Verification Registry Foundation Specification v1.0](./docs/milestones/milestone-15/FounderOS_Milestone_15_Durable_Production_Provider_Readiness_Evaluation_Ledger_and_Replay_Verification_Registry_Foundation_Specification_v1.0.md) +- [Milestone 15 Architecture Specification v1.0](./docs/milestones/milestone-15/FounderOS_Milestone_15_Architecture_Specification_v1.0.md) +- [Durable Readiness Evaluation Transaction Contract v1.0](./docs/milestones/milestone-15/FounderOS_Durable_Readiness_Evaluation_Transaction_Contract_v1.0.md) +- [Readiness Evaluation Registration and Idempotency Contract v1.0](./docs/milestones/milestone-15/FounderOS_Readiness_Evaluation_Registration_and_Idempotency_Contract_v1.0.md) +- [Durable Readiness Evaluation Ledger Contract v1.0](./docs/milestones/milestone-15/FounderOS_Durable_Readiness_Evaluation_Ledger_Contract_v1.0.md) +- [Readiness Replay Verification Registry Contract v1.0](./docs/milestones/milestone-15/FounderOS_Readiness_Replay_Verification_Registry_Contract_v1.0.md) +- [Readiness Ledger Integrity and Recovery Specification v1.0](./docs/milestones/milestone-15/FounderOS_Readiness_Ledger_Integrity_and_Recovery_Specification_v1.0.md) +- [Local File Readiness Ledger Adapter Specification v1.0](./docs/milestones/milestone-15/FounderOS_Local_File_Readiness_Ledger_Adapter_Specification_v1.0.md) +- [Readiness Evidence Privacy and No-Execution Policy v1.0](./docs/milestones/milestone-15/FounderOS_Readiness_Evidence_Privacy_and_No_Execution_Policy_v1.0.md) +- [Milestone 15 Acceptance Criteria v1.0](./docs/milestones/milestone-15/FounderOS_Milestone_15_Acceptance_Criteria_v1.0.md) +- [Milestone 15 Verification Checklist v1.0](./docs/milestones/milestone-15/FounderOS_Milestone_15_Verification_Checklist_v1.0.md) +- [Milestone 15 Codex Implementation Prompt v1.0](./docs/milestones/milestone-15/FounderOS_Milestone_15_Codex_Implementation_Prompt_v1.0.md) + ## Repository governance - [Architecture decisions](./ARCHITECTURE_DECISIONS.md) diff --git a/docs/milestones/milestone-15/FounderOS_Durable_Readiness_Evaluation_Ledger_Contract_v1.0.md b/docs/milestones/milestone-15/FounderOS_Durable_Readiness_Evaluation_Ledger_Contract_v1.0.md new file mode 100644 index 0000000..31d6235 --- /dev/null +++ b/docs/milestones/milestone-15/FounderOS_Durable_Readiness_Evaluation_Ledger_Contract_v1.0.md @@ -0,0 +1,159 @@ +# FounderOS Durable Readiness Evaluation Ledger Contract v1.0 + +## Status + +**Specified — not implemented** + +## Purpose + +Define the storage-independent application contract for immutable readiness evaluation registrations, permanent idempotency ownership, and append-only replay verification evidence. + +## Ledger Responsibilities + +The governed ledger must support capabilities equivalent to: + +- `verifyIntegrity()`; +- `recover()`; +- `registerVerifiedReadinessEvaluation(...)`; +- `readOriginalReadinessEvaluation(transactionId)`; +- `listCommittedReadinessEvaluations()`; +- `submitReadinessReplayAttempt(...)`; +- `listReadinessReplayAttempts(transactionId)`; +- `readHead()`; +- `verifyDerivedIndexes()`; +- `rebuildDerivedIndexes()`. + +The exact interface names may change during implementation. The authority separation may not. + +## Authoritative Record Categories + +1. Canonical genesis complete-history commitment, genesis head, genesis marker archive, and fixed current marker +2. Registration request record +3. Permanent idempotency ownership record +4. Committed readiness evaluation transaction +5. Registration audit entry +6. Replay attempt record +7. Replay audit entry +8. Immutable event-local commit-marker archives and the fixed current marker + +All authoritative event records, including archived per-event marker values, are immutable and marker bounded. The fixed current-marker file is the single intentional replacement point: its verified atomic replacement activates the byte-identical archived marker value and is the sole authoritative visibility boundary (`M15-TXN-001`, `M15-TXN-002`). + +## Ledger Head + +The canonical ledger head is exactly the signed `ReadinessLedgerHeadUnsignedV1` field set from `M15-COMMIT-001` plus `ledgerHeadFingerprint`: + +- `headContractVersion`; +- `headGeneration`; +- `committedRegistrationCount`; +- `committedReplayAttemptCount`; +- `totalAuthoritativeEventCount`; +- `lastCommittedLedgerSequence`; +- `latestAuditEntryId` and `latestAuditEntryFingerprint`; +- `latestSemanticEventId` and `latestSemanticEventFingerprint`; +- `latestSubjectTransactionId` and `latestSubjectTransactionFingerprint`; +- `completeHistoryFingerprint`; +- `ledgerHeadFingerprint`. + +The initialized empty ledger uses the separate `ReadinessGenesisLedgerHeadUnsignedV1` domain with this identical key set. Its generation, counts, and sequence are zero, and all six latest-coordinate fields are exactly `null`. Registration and replay heads require every latest-coordinate field to be non-null and to identify the just-committed audit entry, semantic event, and subject transaction. The phrase `last committed event` is not a schema field or authority coordinate. + +The exact head object returned by `readHead()`, embedded in the installed marker, and written as any separately stored derived `HEAD` projection must be byte-identical. The separate `HEAD` file is a non-authoritative cache rebuildable from verified markers. + +## Genesis Authority (`M15-GENESIS-001`) + +An open/create operation returns exactly one of two valid states: `uninitialized`, with no FounderOS-created genesis component present, or `initialized-empty`, with a complete verified genesis archive and byte-identical fixed current marker. It never treats partial initialization as empty authority. + +Initialization under the cooperative writer lock: + +1. safely proves that the root is uninitialized; +2. constructs the exact canonical genesis complete-history commitment and genesis head from `M15-COMMIT-001`; +3. constructs deterministic marker ID `m15-genesis`, generation `0`, and the canonical genesis marker; +4. stages and synchronizes the complete genesis archive and temporary fixed-marker copy; +5. atomically installs the immutable genesis archive; +6. atomically replaces the fixed current marker with byte-identical bytes as the sole genesis visibility boundary; +7. synchronizes the marker directory where supported; +8. optionally publishes a byte-identical derived `HEAD` only after genesis authority exists. + +A crash before genesis staging leaves an uninitialized root. A crash during staging leaves no authority and only a classifiable staging orphan. A crash after genesis archive installation but before fixed-marker replacement leaves incomplete genesis initialization and must not be opened as empty authority; a later locked create may remove or replace it only after proving exact canonical genesis bytes and no conflicting state. A crash after fixed-marker replacement yields a valid initialized empty ledger only when the archive and fixed copy are byte-identical and independently recompute. Missing, extra, malformed, noncanonical, or fingerprint-invalid genesis components fail closed. + +The first registration requires the verified genesis head as its previous and expected head, uses ledger sequence and generation `1`, and advances every latest coordinate from `null` to the registration audit entry, registration semantic event, and original transaction. + +## Audit Entry + +Every registration or replay event has one audit entry containing: + +- audit contract version; +- ledger sequence; +- event category; +- globally unique audit-entry ID; +- semantic event ID and fingerprint; +- subject transaction ID and fingerprint; +- explicit recorded-at timestamp; +- previous ledger-head fingerprint; +- `auditEntryFingerprint`. + +Registration and replay events share one monotonically increasing sequence. + +The audit entry binds the previous ledger head, not the resulting head. Complete history and the resulting ledger head are computed after the audit-entry fingerprint. Exact fields and ordering are governed solely by `M15-COMMIT-001` in the Durable Readiness Evaluation Transaction Contract. + +## Commit Marker + +Genesis uses exactly `ReadinessGenesisCommitMarkerUnsignedV1`. Registration and replay use exactly the separate `ReadinessCommitMarkerUnsignedV1` field set, category discriminator, exclusions, dependencies, and fingerprint field in the sole `M15-COMMIT-001` table. No summary in another document adds, removes, or renames a marker field. + +The canonical marker value is computed last. Its immutable event-local archive preserves marker history and global marker-ID ownership. Commit occurs only when byte-identical canonical marker bytes are atomically installed at the fixed current-marker location. Installed components or an archived marker without that fixed current-marker activation are crash orphans, not committed history. Missing derived `HEAD` or index state after activation does not roll back the commit. + +## Read Semantics + +- Reads operate only on recovered and verified marker-bounded history. +- `readHead()` returns the exact marker-embedded head bytes, including the verified genesis head for an initialized empty ledger. +- Lists use explicit ledger sequence and deterministic tie-free ordering. +- Returned values are deeply immutable or defensive copies. +- Missing IDs return a stable absent result; corrupt state returns an integrity failure. +- Derived indexes may locate candidates but never establish authority. + +## Write Semantics + +- Every write requires a clean recovery and integrity result. +- Every write uses expected-head compare-and-swap under the writer lock. +- Registration writes one complete transaction, ownership, and audit event atomically. +- Replay writes one complete replay attempt and audit event atomically. +- Identical registration retry performs the mandated resolver/evaluator checks exactly once and returns the original without a new event or head advancement. +- Every distinct replay submission is a new explicitly identified audit event. An exact replay-submission retry is the sole exception: after verifying the current ledger, the permanent replay ownership tuple, the original attempt, and its activating marker, it returns that original attempt without append or head advancement (`M15-REPLAY-003`). +- No operation may mutate an original transaction or earlier replay attempt. + +## Integrity Expectations + +The ledger must detect: + +- broken sequence or audit-chain continuity; +- missing marker-bounded events; +- extra ambiguous installed records; +- record, transaction, request, package, ownership, or marker fingerprint failure; +- duplicate or conflicting globally owned registration idempotency keys, ownership IDs, registration-request IDs, transaction IDs, Decision IDs, registration semantic-event IDs, registration audit-entry IDs, registration marker IDs, replay idempotency keys, replay-request IDs, replay-attempt IDs, replay semantic-event IDs, replay audit-entry IDs, or replay marker IDs; +- mismatched Delivery, Invocation, configuration, gate, retention, or package bindings; +- replay references to missing original transactions; +- authoritative records containing prohibited material; +- derived indexes that disagree with authoritative replay. + +## Derived Index Model + +Permitted indexes include transaction ID, registration request ID, idempotency key, Decision ID, Invocation ID, Adapter ID, and per-transaction replay sequence. + +Each derived index snapshot contains: + +- index contract version and kind; +- source ledger-head fingerprint; +- deterministic ordered entries; +- entry count; +- generated-at evidence where operationally needed but excluded from semantic content identity; +- ordered derived-entry fingerprints; +- `derivedIndexFingerprint`. + +Every entry has `derivedIndexEntryFingerprint` over canonical lookup coordinates plus authoritative transaction and marker fingerprints. Indexes are non-authoritative. A corrupt or missing index is reported, discarded, and explicitly rebuildable only from verified history. + +## Storage Independence + +Shared ledger contracts must not expose filesystem paths, SQL concepts, provider SDKs, credentials, network clients, locks, file descriptors, or adapter-specific commit mechanics. + +## Principle + +The ledger preserves readiness evaluation evidence and replay history. It does not execute reasoning, decide authorization, resolve credentials, or send provider traffic. diff --git a/docs/milestones/milestone-15/FounderOS_Durable_Readiness_Evaluation_Transaction_Contract_v1.0.md b/docs/milestones/milestone-15/FounderOS_Durable_Readiness_Evaluation_Transaction_Contract_v1.0.md new file mode 100644 index 0000000..8d3d2bf --- /dev/null +++ b/docs/milestones/milestone-15/FounderOS_Durable_Readiness_Evaluation_Transaction_Contract_v1.0.md @@ -0,0 +1,252 @@ +# FounderOS Durable Readiness Evaluation Transaction Contract v1.0 + +## Status + +**Specified — not implemented** + +## Purpose + +Define the complete immutable authoritative transaction that records one exact verified Milestone 14 readiness evaluation. + +## Registration Request + +The registration request contains: + +- `contractVersion`; +- `registrationRequestId`; +- `transactionId`; +- `idempotencyKey`; +- `requestedOwnershipId`; +- `requestedRegistrationSemanticEventId`; +- `requestedRegistrationAuditEntryId`; +- `requestedRegistrationMarkerId`; +- exact durable Delivery and Invocation identity projection; +- exact evaluator configuration projection; +- canonical readiness-input fingerprint; +- `originalEvaluationTime`, exactly equal to the canonical Milestone 14 `evaluatedAt` used for the original package; +- optional caller-supplied canonical evaluation-package fingerprint and package; +- `submittedAt`; +- expected ledger-head fingerprint; +- registration-request fingerprint. + +The optional package can only be compared with evaluator-produced output. It is never accepted as authority by itself. + +The four caller-requested original-event IDs are the sole source of those authoritative identities. `requestedOwnershipId` becomes the ownership record's `ownershipId`; `requestedRegistrationSemanticEventId` becomes the registration event's `semanticEventId`; `requestedRegistrationAuditEntryId` becomes the registration audit entry's `auditEntryId`; and `requestedRegistrationMarkerId` becomes the registration marker's `markerId`. The request fingerprint, ownership record, transaction bindings, event, audit entry, marker, integrity and recovery verification, exact-retry comparison, and coordinate-specific conflict result all preserve these values exactly. No implementation may derive or replace them using randomness, time, process identity, filesystem state, sequence, or index state. + +## Durable Delivery and Invocation Identity Projection + +The projection contains at least: + +- Delivery transaction ID and fingerprint; +- Delivery Request ID and fingerprint; +- Delivery Envelope ID and fingerprint; +- Delivery Receipt ID and fingerprint; +- Context Package ID and fingerprint; +- Consumer ID and descriptor fingerprint; +- Invocation Request ID and fingerprint. + +The projection is derived only after complete Milestone 12 recovery and Milestone 13 authority verification. It does not persist the Delivery Ledger interface or Context Package content. + +Its canonical `authorityProjectionFingerprint` commits to every listed logical ID and fingerprint. + +## Evaluator Configuration Projection + +The projection contains: + +- configuration binding version; +- Adapter ID and fingerprint; +- provider family reference; +- Transport Policy ID, fingerprint, and version; +- observability policy version; +- readiness evaluator contract version; +- `configurationProjectionFingerprint`. + +## Canonical Evaluation Package + +The package binds: + +- package contract version; +- canonical readiness-input fingerprint; +- exact Milestone 14 Readiness Decision; +- exact ordered gate trace; +- exact retained non-secret Evidence package; +- observability retention fingerprint; +- Delivery and Invocation identity projection fingerprint; +- evaluator configuration projection fingerprint; +- immutable `originalEvaluationTime`; +- `evaluationPackageFingerprint`. + +The package must preserve the complete verified Milestone 14 artifact required for deterministic reconstruction. It must exclude runtime authority objects, sinks, registries, clients, and raw provider material. + +## Committed Transaction + +A committed readiness evaluation transaction contains: + +- transaction contract version; +- transaction ID; +- registration request and fingerprint; +- idempotency ownership record and fingerprint; +- Delivery and Invocation identity projection; +- evaluator configuration projection; +- Adapter ID and fingerprint; +- provider family reference; +- provider capability ID and fingerprint; +- Credential Reference ID and fingerprint only; +- Transport Policy ID and fingerprint; +- canonical evaluation package; +- immutable `originalEvaluationTime`; +- `submittedAt` and `committedAt`; +- `transactionFingerprint`. + +The canonical transaction fingerprint covers this semantic payload and excludes outer ledger commit coordinates. + +## Normative Commitment Domains (`M15-COMMIT-001`) + +This is the sole authoritative Milestone 15 commitment-domain table. Every other Milestone 15 document references this table and may not define a variant. Each fingerprint is lowercase SHA-256 over the FounderOS durable canonical JSON bytes of the named unsigned schema, prefixed by the exact domain tag and one `0x00` separator byte. An unsigned schema never contains its resulting fingerprint field. Every public operation-result envelope, transient result/status value, and validation report classified as ephemeral by the sole Evidence Durability Inventory in the privacy policy is deliberately absent from this table and may not receive a readiness-ledger fingerprint or commitment domain. + +| Artifact | Domain tag | Unsigned schema | Includes | Excludes | Depends on | Fingerprint field | Authority class | +| --- | --- | --- | --- | --- | --- | --- | --- | +| Genesis complete-history commitment | `founderos.m15.genesis-history.v1` | `ReadinessGenesisCompleteHistoryUnsignedV1` | `historyContractVersion = "1.0"`, `historyGeneration = 0`, `previousCompleteHistoryFingerprint = null`, `totalAuthoritativeEventCount = 0` | own fingerprint; event, audit, head, marker, time, process, random, filesystem, or index fields | literal genesis constants | `completeHistoryFingerprint` | authoritative genesis chain coordinate | +| Genesis ledger head | `founderos.m15.genesis-head.v1` | `ReadinessGenesisLedgerHeadUnsignedV1` | exact ledger-head field set; `headContractVersion = "1.0"`; generation, counts, and sequence are zero; all six latest-coordinate fields are null; canonical genesis complete-history fingerprint | own fingerprint and marker fingerprint | genesis complete-history commitment | `ledgerHeadFingerprint` | authoritative genesis projection embedded in genesis marker | +| Genesis commit marker | `founderos.m15.genesis-marker.v1` | `ReadinessGenesisCommitMarkerUnsignedV1` | `markerContractVersion = "1.0"`, `markerId = "m15-genesis"`, `markerGeneration = 0`, `markerCategory = "genesis"`; zero counts and sequence; null subject, semantic-event, and audit-entry coordinates; genesis complete-history fingerprint; exact genesis head projection/fingerprint | own fingerprint; all registration/replay fields; time, process, random, filesystem, pointer, and index fields | genesis history and head | `commitMarkerFingerprint` | canonical empty-ledger authority whose atomically installed fixed current copy is the genesis visibility boundary; immutable genesis archive is authoritative only after activation | +| Registration request | `founderos.m15.registration-request.v1` | `ReadinessRegistrationRequestUnsignedV1` | version, request ID, requested transaction, ownership, registration semantic-event, registration audit-entry, and registration marker IDs, idempotency key, complete authority/configuration projections, readiness-input fingerprint, `originalEvaluationTime`, optional complete expected package and fingerprint, submitted time, expected head | own fingerprint; evaluator, ledger, or writer objects | verified projection values | `registrationRequestFingerprint` | authoritative component | +| Evaluator configuration projection | `founderos.m15.evaluator-configuration.v1` | `ReadinessEvaluatorConfigurationProjectionUnsignedV1` | version, Adapter ID/fingerprint, provider family, Transport Policy ID/fingerprint/version, observability policy version, evaluator contract version | own fingerprint; function/object/process identity | verified configured evaluator | `configurationProjectionFingerprint` | authoritative supporting evidence | +| Durable authority projection | `founderos.m15.authority-projection.v1` | `DurableReadinessAuthorityProjectionUnsignedV1` | exact Delivery transaction, Request, Envelope, Receipt, Context Package, Consumer, and Invocation IDs/fingerprints | own fingerprint; ledger port; Context content | recovered Milestone 12 and resolved Milestone 13 authority | `authorityProjectionFingerprint` | authoritative supporting evidence | +| Evaluation package | `founderos.m15.evaluation-package.v1` | `CanonicalReadinessEvaluationPackageUnsignedV1` | version, readiness-input fingerprint, exact Decision, ordered gate trace, retained evidence, retention fingerprint, authority/configuration fingerprints, `originalEvaluationTime` | own fingerprint; evaluator-local registry or sink | verified projections and same-instance Decision verification | `evaluationPackageFingerprint` | authoritative supporting evidence | +| Ownership | `founderos.m15.idempotency-ownership.v1` | `ReadinessIdempotencyOwnershipUnsignedV1` | version, caller-requested globally unique ownership ID, key, request ID/fingerprint, requested transaction ID, Decision ID/fingerprint, requested registration semantic-event, audit-entry, and marker IDs, package/authority/configuration fingerprints, first-claim sequence and time | own fingerprint; transaction, audit, head, history, or marker fingerprints | request and verified package | `ownershipFingerprint` | authoritative component | +| Original transaction | `founderos.m15.transaction.v1` | `CommittedReadinessEvaluationTransactionUnsignedV1` | version, transaction ID, complete request and ownership, projections, package, canonical non-secret IDs/fingerprints, original/submitted/committed times | own fingerprint and all later event, audit, history, head, marker, and index fields | request, ownership, projections, package | `transactionFingerprint` | authoritative component | +| Registration semantic event | `founderos.m15.registration-semantic-event.v1` | `ReadinessSemanticEventUnsignedV1` | event version, globally unique semantic event ID, category, transaction ID/fingerprint, ownership ID/fingerprint | own fingerprint; sequence, audit, head, history, marker fields | committed transaction and ownership | `semanticEventFingerprint` | authoritative component | +| Replay request | `founderos.m15.replay-request.v1` | `ReadinessReplayRequestUnsignedV1` | version, replay idempotency key, requested replay request, attempt, semantic-event, audit-entry, and marker IDs, original transaction ID/fingerprint, supplied projections/input fingerprint, immutable `originalEvaluationTime` binding, `replayEvaluatedAt`, expected head | own fingerprint; ledger/evaluator objects | captured replay input | `replayRequestFingerprint` | authoritative supporting evidence when recorded | +| Historical comparison | `founderos.m15.historical-comparison.v1` | `ReadinessHistoricalComparisonUnsignedV1` | original/reconstructed package fingerprints, historical status, bounded differing paths and reasons | own fingerprint; raw differing values | verified reconstruction evidence | `historicalComparisonFingerprint` | authoritative replay evidence | +| Current admissibility | `founderos.m15.current-admissibility.v1` | `ReadinessCurrentAdmissibilityUnsignedV1` | original Authorization fingerprint, `replayEvaluatedAt`, current status and stable reasons | own fingerprint; replacement Authorization or changed original times | immutable original Authorization evidence | `currentAdmissibilityFingerprint` | authoritative replay evidence | +| Replay attempt | `founderos.m15.replay-attempt.v1` | `ReadinessReplayAttemptUnsignedV1` | version, globally unique attempt ID, request fingerprint, original coordinates, projections, historical comparison, current admissibility, stable evidence reasons | own fingerprint and every operation-result append status plus all later audit, history, head, marker, and index fields | replay request and both assessments | `replayAttemptFingerprint` | authoritative component after marker commit | +| Replay semantic event | `founderos.m15.replay-semantic-event.v1` | `ReadinessReplaySemanticEventUnsignedV1` | event version, globally unique event ID, category, original transaction ID/fingerprint, replay attempt ID/fingerprint | own fingerprint; sequence, audit, head, history, marker fields | replay attempt | `semanticEventFingerprint` | authoritative component | +| Audit entry | `founderos.m15.audit-entry.v1` | `ReadinessAuditEntryUnsignedV1` | audit version/ID, sequence, previous ledger-head fingerprint, semantic event ID/fingerprint, category, subject transaction ID/fingerprint, recorded time | own fingerprint; resulting ledger head; complete-history and marker fingerprints | semantic event and previous verified head | `auditEntryFingerprint` | authoritative component | +| Complete-history commitment | `founderos.m15.complete-history.v1` | `ReadinessCompleteHistoryCommitmentUnsignedV1` | previous complete-history fingerprint, audit sequence, audit-entry fingerprint, semantic-event fingerprint | own fingerprint; resulting head and marker | audit entry and semantic event | `completeHistoryFingerprint` | authoritative chain coordinate | +| Ledger head | `founderos.m15.ledger-head.v1` | `ReadinessLedgerHeadUnsignedV1` | `headContractVersion`, `headGeneration`, `committedRegistrationCount`, `committedReplayAttemptCount`, `totalAuthoritativeEventCount`, `lastCommittedLedgerSequence`, `latestAuditEntryId`, `latestAuditEntryFingerprint`, `latestSemanticEventId`, `latestSemanticEventFingerprint`, `latestSubjectTransactionId`, `latestSubjectTransactionFingerprint`, `completeHistoryFingerprint` | own fingerprint and commit-marker fingerprint | audit and complete-history commitments | `ledgerHeadFingerprint` | authoritative projection embedded in marker | +| Commit marker | `founderos.m15.commit-marker.v1` | `ReadinessCommitMarkerUnsignedV1` | marker version/ID/generation/category; committed registration, replay-attempt, and total-event counts; last committed sequence; subject transaction ID/fingerprint; semantic-event ID/fingerprint; audit-entry ID/fingerprint; complete-history fingerprint; resulting ledger-head projection/fingerprint; for `registration`, request, configuration, authority, package, ownership, transaction, and registration-event fingerprints; for `replay`, original transaction, replay request, historical comparison, current admissibility, replay attempt, and replay-event fingerprints | own fingerprint and every derived pointer/index | all prior commitments selected by the strict category discriminator | `commitMarkerFingerprint` | canonical marker value whose atomically installed fixed current copy is the visibility boundary; immutable archived copy is authoritative history only after activation | +| Derived index entry | `founderos.m15.derived-index-entry.v1` | `ReadinessDerivedIndexEntryUnsignedV1` | index kind/key, canonical logical coordinates, authoritative subject transaction fingerprint, authoritative marker fingerprint | own fingerprint; raw authority or values not required for lookup | verified marker-bounded history | `derivedIndexEntryFingerprint` | derived, non-authoritative | +| Derived index snapshot | `founderos.m15.derived-index.v1` | `ReadinessDerivedIndexUnsignedV1` | index version/kind, source marker/head fingerprints, ordered entry fingerprints, entry count | own fingerprint; generation time from semantic identity | derived entries and verified head | `derivedIndexFingerprint` | derived, non-authoritative | + +### Exact ledger-head and category rules + +`ReadinessLedgerHeadUnsignedV1` and `ReadinessGenesisLedgerHeadUnsignedV1` have exactly these keys, in schema order: + +```text +headContractVersion +headGeneration +committedRegistrationCount +committedReplayAttemptCount +totalAuthoritativeEventCount +lastCommittedLedgerSequence +latestAuditEntryId +latestAuditEntryFingerprint +latestSemanticEventId +latestSemanticEventFingerprint +latestSubjectTransactionId +latestSubjectTransactionFingerprint +completeHistoryFingerprint +``` + +`ledgerHeadFingerprint` is the sole additional key on the signed head. For genesis, `headGeneration`, all three counts, and `lastCommittedLedgerSequence` are exactly `0`; the six `latest*` fields are exactly `null`. For every registration or replay head, `headGeneration = totalAuthoritativeEventCount = lastCommittedLedgerSequence`, the three latest ID/fingerprint pairs are non-null and identify the just-committed audit entry, semantic event, and subject transaction, and counts reflect the complete marker-bounded prefix. Unknown, omitted, or category-inapplicable keys fail strict schema validation. + +The canonical unsigned genesis complete-history input is exactly: + +```json +{ + "historyContractVersion": "1.0", + "historyGeneration": 0, + "previousCompleteHistoryFingerprint": null, + "totalAuthoritativeEventCount": 0 +} +``` + +Its fingerprint is `SHA-256(UTF8("founderos.m15.genesis-history.v1") || 0x00 || canonicalJSON(unsignedGenesisHistory))`. The genesis head and genesis marker use the same formula with their exact domain tags and named unsigned schemas. Clean processes therefore derive the same complete-history, head, marker ID, marker generation, canonical bytes, and fingerprints without time, randomness, process identity, or filesystem input. + +`ReadinessGenesisCommitMarkerUnsignedV1` is a separate strict schema. Its subject transaction ID/fingerprint, semantic-event ID/fingerprint, and audit-entry ID/fingerprint are exactly `null`; registration-only and replay-only keys are absent. `ReadinessCommitMarkerUnsignedV1` accepts only `markerCategory = "registration"` or `"replay"`; every shared coordinate is non-null, and exactly the category-specific fields listed in its table row are present. A genesis object cannot validate as an event marker, and an event object cannot validate as a genesis marker. + +The genesis unsigned marker has exactly these keys, in schema order: + +```text +markerContractVersion = "1.0" +markerId = "m15-genesis" +markerGeneration = 0 +markerCategory = "genesis" +committedRegistrationCount = 0 +committedReplayAttemptCount = 0 +totalAuthoritativeEventCount = 0 +lastCommittedLedgerSequence = 0 +subjectTransactionId = null +subjectTransactionFingerprint = null +semanticEventId = null +semanticEventFingerprint = null +auditEntryId = null +auditEntryFingerprint = null +completeHistoryFingerprint +resultingLedgerHead +resultingLedgerHeadFingerprint +``` + +`commitMarkerFingerprint` is the sole additional key on the signed genesis marker. `resultingLedgerHead` is the complete signed genesis head, and `resultingLedgerHeadFingerprint` equals its `ledgerHeadFingerprint`. No event/category-specific key is nullable merely because another category does not use it; inapplicable keys are absent. + +### Normative computation order + +Initialization computes genesis complete history, genesis head, and genesis marker in that order. Registration computes registration request, evaluator configuration projection, durable authority projection, evaluation package, ownership, original transaction, registration semantic event, audit entry, complete-history commitment, ledger head, and registration marker in that order. Replay computes replay request, historical comparison, current admissibility, replay attempt, replay semantic event, audit entry, complete-history commitment, ledger head, and replay marker in that order. Derived entries and snapshots are always computed last. + +The audit entry binds the previous ledger head, not the resulting head. The resulting ledger head is computed only after the audit-entry fingerprint. The marker embeds that resulting head and is computed last. No artifact depends on its own fingerprint or on a later commitment. + +## Authoritative Visibility (`M15-TXN-001`, `M15-TXN-002`) + +Each event has one canonical commit-marker value with one globally unique marker ID. Its canonical bytes and fingerprint are stored in an immutable event-local archive and copied byte-for-byte to the fixed current-marker location. The atomically installed, fully verified fixed current-marker copy is the sole authoritative visibility boundary. The archived copy is not a second visibility boundary: before fixed-marker replacement it is an uncommitted candidate; after replacement it is immutable historical evidence for that activated event. + +The initialized empty ledger follows the same visibility rule through its separate canonical genesis marker. `markerId = "m15-genesis"` and `markerGeneration = 0` are deterministic reserved constants and may never be used by an event. The byte-identical immutable genesis archive and fixed current-marker copy are the only authoritative initialized-empty state; a genesis archive by itself is incomplete initialization, not authority. + +An unmarked transaction, ownership, replay attempt, semantic event, or audit component is not committed. After fixed current-marker installation, the embedded resulting ledger-head projection is authoritative. Any separately stored `HEAD` pointer or derived index is non-authoritative and rebuildable; its absence cannot roll back a marker-committed event. Integrity requires the installed current marker to equal the archived marker for its event and requires every earlier activated event to retain its archived marker, which preserves permanent marker-ID uniqueness without making an older marker current. + +## Permitted Decision Statuses + +The transaction may contain only Milestone 14 statuses: + +- `not-assessed`; +- `not-ready`; +- `ready-for-dry-run`; +- `disabled-by-policy`. + +No `live-ready`, `ready-for-production`, `enabled`, or equivalent status exists. + +## Transaction Invariants + +- Every nested schema and fingerprint verifies independently. +- All identity projections bind the same Delivery, Invocation, Consumer, Context Package, Adapter, capability, Credential Reference, and Transport Policy authority. +- Gate-trace order matches the Milestone 14 canonical order exactly. +- Retention evidence is exact and non-secret. +- Registration request, ownership, semantic transaction, event envelope, audit entry, and marker coordinates agree. +- Sequence, latest audit-entry fingerprint, complete-history fingerprint, and ledger-head fingerprint match the committed ledger prefix. +- The transaction is immutable after commitment. +- The first committed registration globally and permanently owns its idempotency key, ownership ID, registration request ID, transaction ID, Decision ID, registration semantic-event ID, registration audit-entry ID, and registration marker ID. +- Reuse of any owned coordinate outside the exact idempotent-retry tuple fails, even when candidate bytes are otherwise identical. +- Identical transaction replay returns the existing transaction and creates no second registration event. + +## Excluded Fields and Values + +The transaction must not contain: + +- raw Knowledge Objects or Query Results; +- hidden Context or Context Package content; +- Delivery Ledger objects or ports; +- credential values, secret bytes, environment contents, or authorization headers; +- URLs, arbitrary endpoints, or physical paths; +- provider request or response bodies; +- clients, callbacks, functions, sockets, SDK objects, or executable payloads; +- observability sinks or Milestone 14 issuance-registry state; +- caller-supplied commit markers or low-level writers. + +## Canonicalization + +Only exact plain, finite, acyclic data with enumerable own data properties is canonicalizable. Unsupported values, ambiguous Unicode or number representations, accessors, symbols, custom prototypes, and hidden fields fail before persistence. + +Fingerprints use domain-separated lowercase SHA-256 over FounderOS canonical JSON bytes. + +## Principle + +A committed transaction proves what readiness evaluation was verified and recorded. It never grants permission to resolve a credential or execute provider transport. diff --git a/docs/milestones/milestone-15/FounderOS_Local_File_Readiness_Ledger_Adapter_Specification_v1.0.md b/docs/milestones/milestone-15/FounderOS_Local_File_Readiness_Ledger_Adapter_Specification_v1.0.md new file mode 100644 index 0000000..a12b330 --- /dev/null +++ b/docs/milestones/milestone-15/FounderOS_Local_File_Readiness_Ledger_Adapter_Specification_v1.0.md @@ -0,0 +1,205 @@ +# FounderOS Local File Readiness Ledger Adapter Specification v1.0 + +## Status + +**Specified — not implemented** + +## Purpose + +Define the first replaceable local adapter that can prove Milestone 15 persistence, atomicity, recovery, replay, and path-safety semantics. + +## Runtime Root + +The adapter uses one explicit Git-ignored root, for example: + +```text +.founderos/runtime/provider-readiness-ledger/ +``` + +It must not write into `docs/`, `knowledge/`, `packages/`, `services/`, fixtures, or other canonical source trees. + +## Suggested Layout + +```text +provider-readiness-ledger/ +├── metadata.json +├── commit-head.json +├── events/ +│ ├── genesis/ # immutable canonical genesis marker archive +│ ├── registrations/ # immutable event components plus archived marker +│ └── replay-attempts/ # immutable event components plus archived marker +├── staging/ +├── quarantine/ +├── derived/ +└── writer.lock +``` + +Exact names may change during implementation, but authoritative, staging, quarantine, lock, and derived responsibilities must remain separated. + +For the version `1.0` genesis contract, the logical immutable archive location is exactly `events/genesis/commit-marker.json`, and the fixed current-marker location is exactly `commit-head.json`. Implementations may relocate the whole configured runtime root but may not vary these relative logical coordinates without a new contract version. + +## Safe Open + +Before mutation, the adapter must: + +- require an explicit bounded root path; +- reject empty, broad, root, home, or canonical-source targets; +- resolve lexical and physical confinement; +- reject traversal, symlinks, aliases, special files, and unsafe nested entries; +- reject runtime/source overlap in either direction; +- verify required directories remain physically the same around critical operations; +- reject accessor-backed or custom-prototype configuration before path access; +- normalize public errors without disclosing physical paths. + +Read-only open distinguishes `uninitialized`, `initialized-empty`, non-empty initialized, incomplete genesis initialization, and corruption. It never manufactures genesis in a read path. Explicit create is the only operation that may initialize an uninitialized root, and it must acquire the cooperative writer lock before writing genesis staging material. + +Node.js does not provide portable descriptor-relative traversal equivalent to all `openat(2)` protections. The adapter must document and test its best-effort no-follow leaf access and directory-identity rechecks without claiming hostile privileged-filesystem safety. + +## Genesis Initialization Protocol (`M15-GENESIS-001`) + +Create performs this exact sequence under the cooperative writer lock: + +1. repeat safe-open confinement and prove no active or installed FounderOS ledger component exists; +2. construct and independently recompute the exact genesis complete-history commitment, genesis head, and genesis marker from `M15-COMMIT-001`; +3. use reserved `markerId = "m15-genesis"` and `markerGeneration = 0` without time, randomness, process, or filesystem input; +4. write and synchronize the complete genesis archive plus a byte-identical temporary fixed-marker copy in staging; +5. atomically install the immutable genesis archive at the deterministic genesis location; +6. atomically replace `commit-head.json` with the temporary fixed-marker copy; this is the sole genesis visibility boundary; +7. synchronize the marker directory where supported; +8. verify archive/current-marker byte equality and independently recompute genesis history, head, marker, and fingerprints; +9. optionally publish the byte-identical derived `HEAD` projection after authority verifies; +10. release the writer lock. + +Fault behavior is deterministic: + +| Genesis interruption | Visible authority | Classification | Permitted recovery | +| --- | --- | --- | --- | +| before staging | none | uninitialized | a later explicit create may start | +| during staging | none | incomplete genesis staging | read-only open reports failure; a later locked create may discard only verified staging orphans and restart | +| after archived genesis installation but before fixed-marker installation | none | incomplete genesis installation | read-only open reports failure; a later locked create may install only byte-identical independently recomputed canonical genesis or fail closed | +| after fixed-marker installation | complete genesis only if archive/current bytes and all commitments verify | initialized empty or corrupt genesis | return the exact genesis head, or fail closed without repair | + +An archived genesis marker alone never becomes authority. A fixed genesis marker without its byte-identical archive is corruption. Event data, generation `1`, or a non-genesis marker cannot coexist with an uninitialized or initialized-empty classification. Concurrent create operations produce exactly one complete genesis state; the loser observes the verified initialized ledger and performs no mutation. + +## Cooperative Writer Lock + +- Exactly one explicit local writer lock protects mutation. +- Lock metadata uses logical process evidence and bounded timestamps without becoming ledger authority. +- A writer rechecks storage safety, recovery, integrity, and expected head after acquiring the lock. +- Lock acquisition never overrides an existing lock automatically. +- Abnormal termination may require explicit operator cleanup. +- No time threshold permits automatic lock stealing. A stale or abandoned lock blocks mutation with `operator-cleanup-required`. +- Read-only recovery and integrity verification may proceed while a stale lock exists, but must not delete the lock, quarantine or rebuild state, or perform any mutation. Operator cleanup is permitted only after independently verifying that no writer is active; cleanup removes only the cooperative lock and never alters authoritative records. +- The lock is cooperative and does not protect against a malicious privileged process. + +## Commit Protocol + +For registration or replay append: + +1. Validate and capture all public inputs before filesystem mutation. +2. Acquire the cooperative writer lock. +3. Revalidate physical directory identity and safe entries. +4. Recover and verify marker-bounded authoritative history, including the complete genesis commitment. +5. Compare the exact expected-head fingerprint. +6. Revalidate idempotency and identity conflicts under the lock. +7. Construct one complete immutable event envelope and audit entry. +8. Canonically serialize and fingerprint every authoritative record. +9. Write the complete event to a unique file or directory within staging. +10. Synchronize staged files and directories where supported. +11. Atomically rename the complete event into its deterministic immutable authoritative location on the same filesystem. +12. Synchronize the authoritative event directory where supported. +13. Construct the canonical commit marker last; write and synchronize its immutable event-local archive and a byte-identical temporary fixed current-marker copy. +14. Atomically replace the fixed current marker with that temporary copy. +15. Synchronize the marker directory where supported. +16. Optionally update a derived index after commitment. +17. Release the writer lock. + +Commit occurs only at successful atomic fixed current-marker replacement. Installed events and archived marker candidates beyond the old current marker remain uncommitted until activated by the byte-identical fixed current-marker copy. + +The atomically installed verified fixed current-marker copy is the sole authoritative visibility boundary (`M15-TXN-001`, `M15-TXN-002`). The canonical marker embeds the resulting ledger-head projection and fingerprint. Its immutable event-local archive preserves history and global marker-ID ownership but is not a second visibility boundary. Any separate `HEAD` file and every index are non-authoritative derived state. + +Unsupported directory synchronization errors may be suppressed only when explicitly documented and platform classified. Other I/O failures propagate as stable failures. + +## Expected-Head Compare-and-Swap + +Every mutation supplies the head observed during preflight. A changed generation, any count, sequence, latest audit-entry ID/fingerprint, latest semantic-event ID/fingerprint, latest subject transaction ID/fingerprint, complete-history fingerprint, or ledger-head fingerprint rejects the write without advancing the marker. + +No force, overwrite, implicit merge, or last-writer-wins behavior is permitted. + +## Crash Semantics + +- Crash before authoritative event installation leaves only staging data; recovery ignores or quarantines it. +- Crash after event installation but before marker replacement leaves an installed uncommitted orphan; the prior committed head remains authoritative. +- Crash after marker replacement requires the newly referenced complete event; absence or corruption fails recovery. +- Derived-index failure after commitment does not roll back authority; it is reported and rebuilt explicitly. +- Conflicting or ambiguous orphan state fails closed. + +## Normative Fault-Point and Lock Matrix (`M15-FS-001`) + +This is the sole normative publication-fault matrix for both original registration and replay append. “Old head” and “new head” mean complete marker-bounded authoritative prefixes. Deterministic fault injection must recover exactly one of them, never partial authority. + +| Fault point | Lock state | Authoritative files visible | Is committed? | Recovery classification | Automatic action | Operator action | Head/index behavior | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 1. Before staging | absent | old marked prefix | no new commit | clean old head | none | none | derived state remains bound to old head | +| 2. Attempted staging before lock acquisition | absent | old marked prefix; no files created by this operation | no | prohibited/unreachable operation state | reject before filesystem mutation; pre-existing staging is classified read-only only | no quarantine until a later lock is acquired and recovery, integrity, and expected-head checks pass | old head; index unchanged | +| 3. Before lock acquisition | absent or held by another writer | old marked prefix | no | clean or lock unavailable | return `lock-unavailable` if actively held | none | old head | +| 4. After lock acquisition, before integrity verification | held | old prefix | no | unverified locked state | release lock on handled failure | cleanup only after inactive-writer proof | no derived publication | +| 5. After integrity verification, before expected-head validation | held | verified old prefix | no | verified old head | release on failure | none | old head | +| 6. After expected-head validation, before ownership preparation | held | verified old prefix | no | verified old head | release on failure | none | old head | +| 7. After ownership preparation in staging | held | old prefix; staged components | no | staging orphan after interruption | later locked recovery may quarantine | cleanup only if ambiguous | old head | +| 8. After transaction component installation, before audit component installation | held | old prefix; unmarked transaction component | no | installed-uncommitted orphan | ignore as authority; later verified quarantine | required if ambiguous/conflicting | old head | +| 9. After audit component installation, before marker archive/current-copy preparation | held | old prefix; unmarked transaction and audit components | no | installed-uncommitted orphan | ignore as authority; later verified quarantine | required if ambiguous/conflicting | old head | +| 10. During archived-marker or temporary current-marker write/synchronization | held | old current marker; archived candidate or temporary current copy may exist | no unless atomic fixed-marker replacement completed | marker candidate/temporary orphan or case 11 | discard verified temporary only on later locked write; archived candidate remains an uncommitted orphan | required if ambiguous | old head unless fixed current marker verifies | +| 11. After atomic fixed current-marker installation | held | new complete marker-bounded prefix with byte-identical archived marker | yes | committed new head | verify new prefix and archive/current-marker equality | repair no authority automatically | marker-embedded new head is authority | +| 12. After marker installation, before derived `HEAD` publication | held | new committed prefix; stale/missing derived `HEAD` | yes | valid authority, derived state missing/stale | report derived state; explicit rebuild only | none normally | rebuild `HEAD` from verified markers | +| 13. During derived-index publication | held | new committed prefix; temporary/stale index | yes | valid authority, derived index missing/invalid | report separately | none normally | discard/rebuild index explicitly | +| 14. After authoritative commit, before lock release | held or abandoned | new committed prefix | yes | committed head plus existing lock | read-only verification allowed; writes blocked | cleanup only after inactive-writer proof | new head remains authoritative | +| 15. During replay component staging | held | old prefix; staged replay components | no replay commit | replay staging orphan | ignore as authority; later verified quarantine | required if ambiguous | old head | +| 16. After replay component installation, before replay marker | held | old prefix; unmarked replay components | no replay commit | installed-uncommitted replay orphan | ignore as authority; later verified quarantine | required if ambiguous/conflicting | old head | +| 17. After replay fixed current-marker installation, before derived replay-index publication | held | new replay marker-bounded prefix with byte-identical archived marker | yes | committed replay; derived index missing/stale | report separately | none normally | rebuild index from verified markers | +| 18. Interruption while lock exists | abandoned until proven otherwise | old or new complete marked prefix | determined solely by verified marker | stale-lock state plus verified prefix | no lock stealing; read-only integrity allowed | verify no active writer, then remove lock only | marker decides head; derived state separate | +| 19. Stale or abandoned lock on later write | stale or uncertain | verified marker-bounded prefix | unchanged | write blocked | return `operator-cleanup-required` | prove no active writer and remove only lock | no head/index mutation during cleanup | + +Authoritative corruption is never silently rebuilt. Unmarked installed components are never inferred committed. Missing derived `HEAD` or index state after marker installation cannot roll back a commit. + +## Immutable Names and Records + +Authoritative event locations derive from explicit ledger sequence and immutable logical identity. Existing authoritative files are opened no-follow and never edited in place. Conflicting reuse fails. + +## Derived Indexes + +Derived indexes are written outside authoritative event directories, bind the exact head fingerprint, and may be atomically replaced. Reads must not trust them without verification. They may be deleted and rebuilt only through an explicit governed operation. + +## Resource Limits + +The adapter must bound before mutation: + +- path and identifier lengths; +- event and canonical JSON byte sizes; +- nesting depth and collection counts; +- number of discovered entries; +- replay listing and index sizes; +- staging and quarantine operations. + +## Explicit Limitations + +The adapter provides: + +- single-machine persistence; +- same-filesystem atomic rename assumptions; +- cooperative single-writer locking; +- restart recovery for accidental interruption and corruption detection. + +It does not provide: + +- hostile privileged-filesystem protection; +- distributed locks or consensus; +- multi-writer database transactions; +- network-filesystem guarantees; +- replication or remote durability; +- coordinated rollback protection; +- automatic lock cleanup after abnormal termination. + +## Principle + +The local adapter proves durable non-executing readiness evidence without choosing the permanent storage technology or enabling provider transport. diff --git a/docs/milestones/milestone-15/FounderOS_Milestone_15_Acceptance_Criteria_v1.0.md b/docs/milestones/milestone-15/FounderOS_Milestone_15_Acceptance_Criteria_v1.0.md new file mode 100644 index 0000000..3fc8376 --- /dev/null +++ b/docs/milestones/milestone-15/FounderOS_Milestone_15_Acceptance_Criteria_v1.0.md @@ -0,0 +1,212 @@ +# FounderOS Milestone 15 Acceptance Criteria v1.0 + +## Status + +**Specified — not implemented** + +## Normative Requirement Catalog + +Every normative clause elsewhere in the Milestone 15 set is assigned by the machine-readable source-section ownership rules below to one or more independently testable requirements. This catalog is the stable requirement namespace used by acceptance and future executable verification. + +| Requirement ID | Normative requirement | Acceptance criterion ID | +| --- | --- | --- | +| `M15-ARCH-001` | Preserve provider-neutral strict contracts, `knowledge-engine -> knowledge-schema`, and the sole Milestone 13/14 authority path. | `M15-AC-ARCH-001` | +| `M15-SCHEMA-001` | Strict versioned schemas and canonicalization reject unknown, explicit-`undefined`, accessor-backed, symbolic, inherited, hidden, aliased, custom-prototype, executable, non-finite, or cyclic input. | `M15-AC-SCHEMA-001` | +| `M15-PKG-001` | Schema owns storage-independent contracts; engine owns orchestration and adapters; dependency direction remains `knowledge-engine -> knowledge-schema`. | `M15-AC-PKG-001` | +| `M15-REG-001` | Registration and identical retry run recovery, current governed resolution, evaluation, same-instance verification, and canonical reconstruction exactly once before commit or return. | `M15-AC-REG-001` | +| `M15-REG-002` | Caller-supplied packages are equality candidates only; missing, stale, reordered, altered, or substituted members fail before mutation. | `M15-AC-REG-002` | +| `M15-IDEM-001` | The first original registration permanently and globally owns its idempotency key, ownership ID, request ID, transaction ID, Decision ID, registration semantic-event ID, registration audit-entry ID, registration marker ID, and exact bindings; only an exact retry may return it. | `M15-AC-IDEM-001` | +| `M15-IDEM-002` | Replay idempotency key and request, attempt, semantic-event, audit-entry, and marker IDs are globally and permanently owned; exact replay retry requires the exact owned tuple and request fingerprint. | `M15-AC-IDEM-002` | +| `M15-COMMIT-001` | Every fingerprint follows the sole named, acyclic commitment-domain table in the transaction contract. | `M15-AC-COMMIT-001` | +| `M15-GENESIS-001` | Explicit canonical genesis history, head, and marker commitments define the sole initialized-empty authority and fail closed under partial initialization or corruption. | `M15-AC-GENESIS-001` | +| `M15-HEAD-001` | Genesis and event heads use one exact latest-coordinate schema; marker embedding, `readHead()`, and derived `HEAD` use byte-identical head bytes. | `M15-AC-HEAD-001` | +| `M15-TXN-001` | The verified atomically installed marker is the sole visibility boundary; its embedded head is authoritative and separate `HEAD`/indexes are derived. | `M15-AC-TXN-001` | +| `M15-TXN-002` | Each event retains one immutable archived marker value byte-identical to the value installed at the replaceable fixed current-marker location; only fixed-marker replacement activates visibility. | `M15-AC-TXN-002` | +| `M15-AUDIT-001` | Marker-bounded events, audit sequence, previous-head links, complete-history commitments, and resulting heads verify without gaps or reordering. | `M15-AC-AUDIT-001` | +| `M15-REPLAY-001` | Replay always performs historical reconstruction at `originalEvaluationTime` and separately assesses current admissibility at `replayEvaluatedAt`. | `M15-AC-REPLAY-001` | +| `M15-REPLAY-002` | Replay exposes the exact historical, current-admissibility, append, and `recorded`/`not-recorded`/`idempotent-replay-returned` operation taxonomies with stable reasons. | `M15-AC-REPLAY-002` | +| `M15-REPLAY-003` | Exact replay retry verifies permanent history and returns the original attempt without reassessment or append; its owned original expected head need not equal the later current head. | `M15-AC-REPLAY-003` | +| `M15-INTEGRITY-001` | Integrity verifies all authoritative commitments and identities, fails closed, and returns strict non-fingerprinted ephemeral results that are never persisted in authoritative, derived, or logging material. | `M15-AC-INTEGRITY-001` | +| `M15-INTEGRITY-002` | Derived `HEAD` and indexes never establish authority; missing or corrupt derived state is reported separately and rebuilt only from verified marker-bounded history. | `M15-AC-INTEGRITY-002` | +| `M15-RECOVERY-001` | Recovery deterministically yields the old or new complete marker-bounded head, never partial or silently repaired authority. | `M15-AC-RECOVERY-001` | +| `M15-FS-001` | The local adapter satisfies every row of the sole 19-point fault/lock matrix, safe-path rules, CAS, and explicit local limitations. | `M15-AC-FS-001` | +| `M15-FS-002` | Safe-open confines lexical and physical paths, rejects symlinks and unsafe entries, and performs no-follow leaf and directory-identity checks without overclaiming hostile-filesystem safety. | `M15-AC-FS-002` | +| `M15-FS-003` | Mutation acquires the cooperative lock before staging, revalidates under lock, uses expected-head CAS, never steals stale locks, and permits operator removal of only an inactive lock. | `M15-AC-FS-003` | +| `M15-PRIVACY-001` | The sole exhaustive evidence inventory distinguishes authoritative and derived durable state from every non-fingerprinted, non-persisted application/adapter operation-result envelope, transient status value, and validation report; all inputs, data, reports, errors, and indexes exclude prohibited material and physical paths. | `M15-AC-PRIVACY-001` | +| `M15-PRIVACY-002` | Every public error, integrity result, recovery result, replay record, audit event, log, and report uses logical redacted coordinates and never exposes a physical path. | `M15-AC-PRIVACY-002` | +| `M15-NET-001` | Production import closure and runtime probes prove no network, provider, Agent, Hermes, MCP, streaming, or tools/functions capability. | `M15-AC-NET-001` | +| `M15-CRED-001` | Only Credential Reference ID/fingerprint may persist; no credential resolver, secret read, value, or access path exists. | `M15-AC-CRED-001` | +| `M15-NOEXEC-001` | Stored readiness and replay evidence never grants execution authority or introduces live-ready, credential-resolution, or transport behavior. | `M15-AC-NOEXEC-001` | +| `M15-BASELINE-001` | Future implementation requires the pinned Milestone 14 predecessor, separately authorized documentation merge SHA, exact `codex/milestone-15` branch, clean worktree, and no pre-existing runtime work. | `M15-AC-BASELINE-001` | +| `M15-DOC-001` | ADR-0019 remains Proposed and Milestone 15 remains Specified — not implemented until separately reviewed implementation exists; links and versions remain consistent. | `M15-AC-DOC-001` | + +## Acceptance Criteria + +- [ ] `M15-AC-ARCH-001`: Strict versions, unknown-field rejection, storage/provider independence, package boundaries, and sole upstream authority are preserved. +- [ ] `M15-AC-SCHEMA-001`: Every prohibited JavaScript/object shape and canonical-data edge rejects deterministically before authority or mutation. +- [ ] `M15-AC-PKG-001`: Static dependency inspection proves exact package ownership and no reverse dependency. +- [ ] `M15-AC-REG-001`: First registration commits a fully verified transaction; exact retry performs the mandated checks exactly once and returns `idempotent-original-returned` without mutation. +- [ ] `M15-AC-REG-002`: Stale fingerprints, missing members, altered order/retention, and coherent substitutions reject before ownership or append. +- [ ] `M15-AC-IDEM-001`: Cross-key/request reuse of any of the eight original-registration ownership coordinates returns its stable coordinate-specific conflict; exact retry binds every caller-requested ID and never creates a second original transaction. +- [ ] `M15-AC-IDEM-002`: Replay idempotency-key and identity conflicts fail globally; only an exact retry of the complete key/five-ID/request tuple returns the original attempt without append. +- [ ] `M15-AC-COMMIT-001`: Fixtures independently recompute every row of `M15-COMMIT-001`; no artifact commits to itself or a later artifact. +- [ ] `M15-AC-GENESIS-001`: Clean processes reproduce identical genesis bytes; create exposes either no authority or one complete genesis state; every genesis crash/corruption case is classified; and first registration advances exactly from the verified genesis head. +- [ ] `M15-AC-HEAD-001`: Genesis, first-registration, and replay fixtures enforce exact keys/nullability/latest coordinates and byte equality among marker-embedded head, `readHead()`, and rebuilt derived `HEAD`. +- [ ] `M15-AC-TXN-001`: A transaction becomes visible only through a verified installed marker; missing derived `HEAD` or index after marker commit is rebuildable and does not undo authority. +- [ ] `M15-AC-TXN-002`: Every activated marker has one byte-identical immutable archive; archived candidates alone remain invisible and fixed current-marker mismatch fails closed. +- [ ] `M15-AC-AUDIT-001`: Audit, event, history, marker, count, and head coordinates verify exactly. +- [ ] `M15-AC-REPLAY-001`: Historical reconstruction never depends on current admissibility; `matched` plus `authorization-expired` is recorded and execution authority remains absent. +- [ ] `M15-AC-REPLAY-002`: Recorded outcomes append exactly one attempt; not-recorded outcomes append none and expose exactly one stable reason; idempotent replay returns an existing attempt as not-appended. +- [ ] `M15-AC-REPLAY-003`: Exact replay retry verifies the full five-ID ownership tuple and original request, returns `idempotent-replay-returned`/`not-appended`, and tolerates only later current-head advancement. +- [ ] `M15-AC-INTEGRITY-001`: Missing, corrupt, contradictory, substituted, duplicated, or privacy-invalid authority fails closed; derived-state findings remain separate; integrity/recovery outputs are never fingerprinted or persisted. +- [ ] `M15-AC-INTEGRITY-002`: Missing and corrupt derived state are independently detected, never trusted, and explicitly rebuilt to deterministic bytes from verified history. +- [ ] `M15-AC-RECOVERY-001`: Restart and injected interruption recover exactly a complete old or new marker-bounded prefix. +- [ ] `M15-AC-FS-001`: Safe-open, cooperative locking, no automatic stale-lock stealing, operator-only cleanup, atomic publication, synchronization, CAS, and all 19 fault rows pass. +- [ ] `M15-AC-FS-002`: Traversal, physical escape, symlink, special-file, unsafe-entry, overlap, no-follow, and directory-identity tests pass with path-redacted results. +- [ ] `M15-AC-FS-003`: No staging write occurs before lock acquisition; lock/CAS revalidation and stale-lock cleanup constraints hold under deterministic concurrency tests. +- [ ] `M15-AC-PRIVACY-001`: Plain-own-data validation rejects explicit `undefined`, accessors without invocation, symbols, hidden/inherited fields, custom prototypes, aliases, executable values, secrets, endpoints, and physical-path disclosure; stored-data inspection permits only inventoried authoritative/derived evidence and excludes every application/adapter operation-result envelope, transient status value, and validation report. +- [ ] `M15-AC-PRIVACY-002`: Every public result, stored record, log, and completion report passes physical-path redaction inspection. +- [ ] `M15-AC-NET-001`: Static import closure and runtime probes find no outbound or provider-execution path. +- [ ] `M15-AC-CRED-001`: Static import closure, runtime probes, and stored-data inspection find no credential access or value. +- [ ] `M15-AC-NOEXEC-001`: Status schemas, facade inspection, imports, and runtime probes expose no live-execution authority or path. +- [ ] `M15-AC-BASELINE-001`: Future implementation preflight rejects every unauthorized SHA, branch, dirty-worktree, and pre-existing-runtime case. +- [ ] `M15-AC-DOC-001`: Documentation lint verifies status, ADR, version, index, and relative-link invariants. + +## Verification Scenario Catalog + +| Scenario ID | Required result | Authoritative mutation | Requirements | +| --- | --- | --- | --- | +| `M15-SC-001` | Successful first registration | one original event | `M15-ARCH-001`, `M15-REG-001`, `M15-IDEM-001` | +| `M15-SC-002` | Exact registration retry runs authority/evaluator checks exactly once and returns original | none | `M15-REG-001`, `M15-IDEM-001` | +| `M15-SC-003` | Same idempotency key with a different request fingerprint returns `idempotency-key-conflict` | none | `M15-IDEM-001` | +| `M15-SC-004` | Exact replay retry returns original attempt; conflicting replay identities reject | none | `M15-IDEM-002` | +| `M15-SC-005` | Every commitment-table fixture recomputes byte-for-byte in normative order | none | `M15-COMMIT-001`, `M15-AUDIT-001` | +| `M15-SC-006` | Historical match plus current Authorization expiration records both statuses | one replay event | `M15-REPLAY-001`, `M15-REPLAY-002` | +| `M15-SC-007` | Current Authorization denial records `authorization-denied` | one replay event | `M15-REPLAY-001`, `M15-REPLAY-002` | +| `M15-SC-008` | Current review-required records `authorization-review-required` | one replay event | `M15-REPLAY-001`, `M15-REPLAY-002` | +| `M15-SC-009` | Current not-evaluated records `authorization-not-evaluated` | one replay event | `M15-REPLAY-001`, `M15-REPLAY-002` | +| `M15-SC-010` | Invalid Authorization evidence records `authorization-invalid-evidence` | one replay event | `M15-REPLAY-001`, `M15-REPLAY-002` | +| `M15-SC-011` | Original-time reconstruction and current-time admissibility use distinct bound timestamps | one replay event | `M15-REPLAY-001` | +| `M15-SC-012` | Valid package inequality is `mismatched` with bounded paths | one replay event | `M15-REPLAY-002` | +| `M15-SC-013` | Evaluator configuration mismatch records historical `verification-failed` | one replay event | `M15-REPLAY-002` | +| `M15-SC-014` | Delivery authority mismatch records historical `verification-failed` | one replay event | `M15-REPLAY-002` | +| `M15-SC-015` | Invocation authority mismatch records historical `verification-failed` | one replay event | `M15-REPLAY-002` | +| `M15-SC-016` | Ledger-integrity failure returns not-recorded | none | `M15-INTEGRITY-001`, `M15-REPLAY-002` | +| `M15-SC-017` | Missing original returns not-recorded | none | `M15-REPLAY-002` | +| `M15-SC-018` | Invalid replay input returns not-recorded before authority access | none | `M15-REPLAY-002`, `M15-PRIVACY-001` | +| `M15-SC-019` | Replay append failure returns not-recorded/not-appended | none | `M15-REPLAY-002` | +| `M15-SC-020` | Stale expected replay head returns `stale-expected-head`/not-recorded | none | `M15-REPLAY-002`, `M15-FS-003` | +| `M15-SC-021` | Every registration-applicable matrix row, including 1–14, 18, and 19, recovers old or new complete head | zero or one event per row | `M15-TXN-001`, `M15-RECOVERY-001`, `M15-FS-001` | +| `M15-SC-022` | Every replay-applicable matrix row, including replay-specific 15–17 and shared publication/lock rows, recovers old or new complete head | zero or one event per row | `M15-TXN-001`, `M15-RECOVERY-001`, `M15-FS-001` | +| `M15-SC-023` | Interruption with lock and stale-lock discovery block writes; operator cleanup changes only lock | none | `M15-FS-001` | +| `M15-SC-024` | Deterministic index rebuild restores exact lookups from verified history | derived only | `M15-TXN-001`, `M15-INTEGRITY-001` | +| `M15-SC-025` | Derived `HEAD` rebuild after marker commit restores exact projection | derived only | `M15-TXN-001`, `M15-RECOVERY-001` | +| `M15-SC-026` | Corrupt, missing, reordered, duplicated, partial, or coherently substituted authority fails | none | `M15-AUDIT-001`, `M15-INTEGRITY-001` | +| `M15-SC-027` | Unknown and explicit-`undefined` fields reject | none | `M15-ARCH-001`, `M15-SCHEMA-001`, `M15-PRIVACY-001` | +| `M15-SC-028` | Accessor-backed input rejects without accessor invocation | none | `M15-SCHEMA-001`, `M15-PRIVACY-001` | +| `M15-SC-029` | Symbols, hidden/inherited properties, custom prototypes, aliases, and executable input reject | none | `M15-SCHEMA-001`, `M15-PRIVACY-001` | +| `M15-SC-030` | Traversal, symlink, special file, unsafe entry, and runtime/source overlap reject | none | `M15-FS-001` | +| `M15-SC-031` | Errors and reports contain logical coordinates and no physical path | none | `M15-PRIVACY-001` | +| `M15-SC-032` | Stored-data traversal finds no prohibited or secret-like material | none | `M15-PRIVACY-001`, `M15-CRED-001` | +| `M15-SC-033` | Exact production import closure and runtime probe prove no network/provider path | none | `M15-NET-001` | +| `M15-SC-034` | Exact production import closure and runtime probe prove no credential path | none | `M15-CRED-001` | +| `M15-SC-035` | All Milestone 04–14 regression tests pass without predecessor-test loss, preserving at least the pinned 42-file and 1,038-test baseline including Milestone 14 FIFO behavior | none | `M15-ARCH-001`, `M15-REG-001`, `M15-BASELINE-001` | +| `M15-SC-036` | Exact historical reconstruction while currently admissible records `matched` plus `admissible` | one replay event | `M15-REPLAY-001`, `M15-REPLAY-002` | +| `M15-SC-037` | Same registration request ID under a different key returns `registration-request-id-conflict` | none | `M15-IDEM-001` | +| `M15-SC-038` | Same transaction ID under a different key or request returns `transaction-id-conflict` | none | `M15-IDEM-001` | +| `M15-SC-039` | Same Decision ID under a different key or request returns `decision-id-conflict` and no second original exists | none | `M15-IDEM-001` | +| `M15-SC-040` | Each stale request, transaction, Decision, authority, configuration, package, and evidence fingerprint rejects independently | none | `M15-REG-002`, `M15-COMMIT-001` | +| `M15-SC-041` | Each required transaction member missing in turn fails integrity and cannot become visible | none | `M15-REG-002`, `M15-INTEGRITY-001` | +| `M15-SC-042` | Each gate-order permutation rejects independently | none | `M15-REG-002`, `M15-INTEGRITY-001` | +| `M15-SC-043` | Each retention omission, addition, or alteration rejects independently | none | `M15-REG-002`, `M15-INTEGRITY-001` | +| `M15-SC-044` | Corrupt derived index is reported invalid, bypassed, and deterministically rebuilt | derived only | `M15-INTEGRITY-002` | +| `M15-SC-045` | Missing derived index is reported missing and deterministically rebuilt | derived only | `M15-INTEGRITY-002` | +| `M15-SC-046` | Archived/current marker byte mismatch, missing archive, or duplicate marker ID fails closed; archived candidate alone is invisible | none | `M15-TXN-001`, `M15-TXN-002`, `M15-INTEGRITY-001` | +| `M15-SC-047` | Exact replay retry after later head advancement verifies all five replay IDs and returns the original as not-appended | none | `M15-IDEM-002`, `M15-REPLAY-003` | +| `M15-SC-048` | No-follow leaf and physical directory-identity rechecks detect substitution without physical-path disclosure | none | `M15-FS-002`, `M15-PRIVACY-002` | +| `M15-SC-049` | Future implementation preflight rejects every wrong predecessor, missing/wrong merge authorization, wrong branch/base, dirty tree, and pre-existing runtime-work case | none | `M15-BASELINE-001` | +| `M15-SC-050` | ADR-0019, milestone status, document versions, index inventory, and every relative link lint clean | none | `M15-DOC-001` | +| `M15-SC-051` | Two concurrent replay writers from one observed head produce at most one commit and one stable conflict | at most one replay event | `M15-REPLAY-002`, `M15-FS-003` | +| `M15-SC-052` | Static package graph proves schema/engine ownership and no reverse dependency | none | `M15-PKG-001` | +| `M15-SC-053` | Status/facade validation rejects live-ready aliases and runtime probes reach no execution authority | none | `M15-NOEXEC-001` | +| `M15-SC-054` | Two clean processes independently produce byte-identical canonical genesis history, head, marker, and fingerprints | genesis initialization only | `M15-COMMIT-001`, `M15-GENESIS-001` | +| `M15-SC-055` | First create and interruptions before staging, during staging, after genesis archive creation, and after fixed-marker installation expose either no authority or one complete genesis state | genesis initialization only | `M15-GENESIS-001`, `M15-RECOVERY-001`, `M15-FS-001` | +| `M15-SC-056` | Missing, extra, mismatched, malformed, noncanonical, or fingerprint-invalid genesis material fails closed | none | `M15-GENESIS-001`, `M15-INTEGRITY-001` | +| `M15-SC-057` | First registration binds the verified genesis head and advances exactly to generation/sequence `1` with non-null latest coordinates | one original event | `M15-GENESIS-001`, `M15-HEAD-001`, `M15-AUDIT-001` | +| `M15-SC-058` | Genesis archive and fixed current marker are byte-identical; an archive alone is invisible | genesis initialization only | `M15-GENESIS-001`, `M15-TXN-001`, `M15-TXN-002` | +| `M15-SC-059` | Genesis, first-registration, and replay head fixtures independently recompute every exact field | none | `M15-HEAD-001`, `M15-COMMIT-001` | +| `M15-SC-060` | Missing, extra, aliased, or category-invalid ledger-head keys and wrong genesis nullability reject | none | `M15-HEAD-001`, `M15-SCHEMA-001` | +| `M15-SC-061` | Stale or substituted latest audit-entry, semantic-event, or subject-transaction coordinates fail integrity | none | `M15-HEAD-001`, `M15-INTEGRITY-001` | +| `M15-SC-062` | Marker-embedded head, public `readHead()`, and rebuilt derived `HEAD` are byte-identical | derived only | `M15-HEAD-001`, `M15-INTEGRITY-002` | +| `M15-SC-063` | Ownership ID reuse returns `ownership-id-conflict` across key, request, restart, and derived-index loss | none | `M15-IDEM-001` | +| `M15-SC-064` | Registration semantic-event ID reuse returns `registration-semantic-event-id-conflict` | none | `M15-IDEM-001` | +| `M15-SC-065` | Registration audit-entry ID reuse returns `registration-audit-entry-id-conflict` | none | `M15-IDEM-001` | +| `M15-SC-066` | Registration marker ID reuse returns `registration-marker-id-conflict` | none | `M15-IDEM-001` | +| `M15-SC-067` | Reusing any original-registration ID under a different key or request returns the coordinate-specific stable conflict | none | `M15-IDEM-001` | +| `M15-SC-068` | Reusing a key with any changed caller-requested original-registration ID returns `idempotency-key-conflict` | none | `M15-IDEM-001` | +| `M15-SC-069` | Exact registration retry binds all eight owned coordinates and survives restart and complete derived-index loss | none | `M15-IDEM-001`, `M15-REG-001` | +| `M15-SC-070` | Replay idempotency-key conflict rejects; exact key/five-ID/request retry returns the original without append | none | `M15-IDEM-002`, `M15-REPLAY-003` | +| `M15-SC-071` | Authoritative records, staging-to-install envelopes, derived state, logs, traces, metrics, and observability artifacts contain no application/adapter operation-result envelope, transient status value, or validation report | none | `M15-PRIVACY-001`, `M15-INTEGRITY-001` | +| `M15-SC-072` | Every public application/adapter result envelope and transient status is strict canonical redacted ephemeral output, while validation reports are redacted ephemeral outputs; none has a readiness-ledger fingerprint or durable copy, and a separately specified outside-ledger report is the only explicit exception | none | `M15-PRIVACY-001`, `M15-PRIVACY-002`, `M15-INTEGRITY-001` | + +## Normative Source-Section Ownership + +A **normative clause** is detected structurally, without natural-language inference: outside fenced code, it is (a) every prose sentence or table row containing the case-insensitive whole-word token `must`, `shall`, `required`, `only`, `never`, or the exact phrase `may not`; and (b) every ordered-list or unordered-list item, including its continuation lines. The deterministic documentation lint parses every Milestone 15 Markdown file, assigns each clause to the nearest preceding Markdown section heading, then uses this table. A section override replaces its document default; every non-overridden section inherits its file default. An unlisted file or a clause with no resulting requirement is a lint failure. + +| Source document | Default requirement ownership | Exact section overrides | +| --- | --- | --- | +| `FounderOS_Milestone_15_Durable_Production_Provider_Readiness_Evaluation_Ledger_and_Replay_Verification_Registry_Foundation_Specification_v1.0.md` | `M15-ARCH-001`, `M15-PKG-001`, `M15-NOEXEC-001`, `M15-DOC-001` | `Authoritative Registration Flow` -> `M15-REG-001`, `M15-REG-002`, `M15-IDEM-001`; `Authoritative Replay Flow` -> `M15-REPLAY-001`, `M15-REPLAY-002`; `Authoritative and Derived State` -> `M15-GENESIS-001`, `M15-TXN-001`, `M15-TXN-002`, `M15-INTEGRITY-002`; `Identity and Fingerprinting` -> `M15-COMMIT-001`, `M15-GENESIS-001`, `M15-HEAD-001`, `M15-IDEM-001`, `M15-IDEM-002`; `Local Adapter Boundary` -> `M15-FS-001`, `M15-FS-002`, `M15-FS-003` | +| `FounderOS_Milestone_15_Architecture_Specification_v1.0.md` | `M15-ARCH-001`, `M15-PKG-001`, `M15-NOEXEC-001` | `Evaluator Configuration Projection` -> `M15-COMMIT-001`; `Registration Boundary` -> `M15-REG-001`, `M15-REG-002`, `M15-IDEM-001`; `Replay Boundary` -> `M15-REPLAY-001`, `M15-REPLAY-002`, `M15-REPLAY-003`; `Persistence Boundary` -> `M15-GENESIS-001`, `M15-HEAD-001`, `M15-TXN-001`, `M15-TXN-002`, `M15-INTEGRITY-002`; `Transaction and Audit Ordering` -> `M15-COMMIT-001`, `M15-GENESIS-001`, `M15-HEAD-001`, `M15-AUDIT-001`; `Local Adapter Limitations` -> `M15-FS-001`, `M15-FS-002`, `M15-FS-003` | +| `FounderOS_Durable_Readiness_Evaluation_Transaction_Contract_v1.0.md` | `M15-SCHEMA-001`, `M15-PRIVACY-001`, `M15-NOEXEC-001` | `Registration Request` -> `M15-REG-002`, `M15-IDEM-001`; `Durable Delivery and Invocation Identity Projection`, `Evaluator Configuration Projection`, `Canonical Evaluation Package`, `Committed Transaction` -> `M15-COMMIT-001`; `Normative Commitment Domains`, `Exact ledger-head and category rules`, `Normative computation order` -> `M15-COMMIT-001`, `M15-GENESIS-001`, `M15-HEAD-001`; `Authoritative Visibility` -> `M15-GENESIS-001`, `M15-TXN-001`, `M15-TXN-002`; `Transaction Invariants` -> `M15-IDEM-001`, `M15-AUDIT-001`, `M15-COMMIT-001` | +| `FounderOS_Readiness_Evaluation_Registration_and_Idempotency_Contract_v1.0.md` | `M15-REG-001`, `M15-REG-002`, `M15-IDEM-001` | `Atomic Claim and Commit` -> `M15-TXN-001`, `M15-TXN-002`, `M15-FS-003`; `Required Conflict Detection` -> `M15-IDEM-001`, `M15-INTEGRITY-001`; `Ordering` -> `M15-AUDIT-001` | +| `FounderOS_Durable_Readiness_Evaluation_Ledger_Contract_v1.0.md` | `M15-ARCH-001`, `M15-PKG-001`, `M15-AUDIT-001` | `Authoritative Record Categories` -> `M15-GENESIS-001`, `M15-TXN-001`, `M15-TXN-002`; `Ledger Head` -> `M15-HEAD-001`; `Genesis Authority` -> `M15-GENESIS-001`, `M15-HEAD-001`, `M15-RECOVERY-001`; `Commit Marker`, `Write Semantics` -> `M15-TXN-001`, `M15-TXN-002`; `Integrity Expectations` -> `M15-INTEGRITY-001`, `M15-IDEM-001`, `M15-IDEM-002`; `Derived Index Model` -> `M15-INTEGRITY-002` | +| `FounderOS_Readiness_Replay_Verification_Registry_Contract_v1.0.md` | `M15-REPLAY-001`, `M15-REPLAY-002`, `M15-NOEXEC-001` | `Replay Request`, `Registry Rules` -> `M15-IDEM-002`, `M15-REPLAY-003`; `Replay Append and Operation Results` -> `M15-REPLAY-002`, `M15-REPLAY-003`; `Privacy` -> `M15-PRIVACY-001`, `M15-PRIVACY-002` | +| `FounderOS_Readiness_Ledger_Integrity_and_Recovery_Specification_v1.0.md` | `M15-INTEGRITY-001`, `M15-RECOVERY-001` | `Crash-State Classification` -> `M15-RECOVERY-001`, `M15-TXN-001`, `M15-TXN-002`; `Derived Index Recovery` -> `M15-INTEGRITY-002`; `Recovery Result`, `Integrity Result` -> `M15-PRIVACY-002`, `M15-INTEGRITY-001`; `Empty Ledger` -> `M15-GENESIS-001`, `M15-HEAD-001`, `M15-RECOVERY-001` | +| `FounderOS_Local_File_Readiness_Ledger_Adapter_Specification_v1.0.md` | `M15-FS-001`, `M15-FS-002`, `M15-FS-003` | `Safe Open`, `Runtime Root`, `Resource Limits` -> `M15-FS-002`, `M15-PRIVACY-002`; `Genesis Initialization Protocol` -> `M15-GENESIS-001`, `M15-HEAD-001`, `M15-FS-001`, `M15-RECOVERY-001`; `Cooperative Writer Lock`, `Expected-Head Compare-and-Swap` -> `M15-FS-003`; `Commit Protocol`, `Crash Semantics`, `Normative Fault-Point and Lock Matrix` -> `M15-FS-001`, `M15-TXN-001`, `M15-TXN-002`, `M15-RECOVERY-001`; `Derived Indexes` -> `M15-INTEGRITY-002` | +| `FounderOS_Readiness_Evidence_Privacy_and_No_Execution_Policy_v1.0.md` | `M15-PRIVACY-001`, `M15-NOEXEC-001` | `Evidence Durability Inventory`, `Stored-Data Inspection` -> `M15-PRIVACY-001`, `M15-PRIVACY-002`, `M15-INTEGRITY-001`; `Credential Reference Rule` -> `M15-CRED-001`; `Redaction and Errors` -> `M15-PRIVACY-002`; `Production Import Closure` -> `M15-NET-001`, `M15-CRED-001`, `M15-NOEXEC-001`; `Authorization Expiration` -> `M15-REPLAY-001`, `M15-NOEXEC-001` | +| `FounderOS_Milestone_15_Acceptance_Criteria_v1.0.md` | every requirement listed in the catalog | `Normative Source-Section Ownership`, `Normative Traceability Matrix` -> every cataloged requirement | +| `FounderOS_Milestone_15_Verification_Checklist_v1.0.md` | every requirement listed in the catalog | `Repository Preconditions` -> `M15-BASELINE-001`, `M15-DOC-001`; `Traceability Verification` -> every cataloged requirement | +| `FounderOS_Milestone_15_Package_README_v1.0.md` | `M15-DOC-001`, `M15-ARCH-001`, `M15-NOEXEC-001` | `Architecture` -> `M15-PKG-001`, `M15-GENESIS-001`, `M15-HEAD-001`, `M15-IDEM-001`, `M15-IDEM-002`, `M15-TXN-001`, `M15-TXN-002`; `Document Inventory` -> `M15-DOC-001` | +| `FounderOS_Milestone_15_Codex_Implementation_Prompt_v1.0.md` | every requirement listed in the catalog | `Authorization Precondition` -> `M15-BASELINE-001`; `Required Tests` -> every cataloged requirement; `Documentation Updates`, `Stop Condition` -> `M15-DOC-001`, `M15-NOEXEC-001` | + +The filename-to-source names above is exact and one-to-one with the 13 files in the package inventory. The override grammar is deterministic: semicolons separate override entries, `->` separates the comma-delimited exact heading list from the comma-delimited requirement-ID list, and backticks delimit IDs. Heading matching ignores the trailing parenthesized requirement-ID annotation already present on some headings but otherwise requires exact text. + +## Normative Traceability Matrix + +| Requirement ID | Acceptance criterion ID | Verification scenario ID(s) | Future test class | +| --- | --- | --- | --- | +| `M15-ARCH-001` | `M15-AC-ARCH-001` | `M15-SC-001`, `M15-SC-035` | architecture and regression | +| `M15-SCHEMA-001` | `M15-AC-SCHEMA-001` | `M15-SC-027`–`M15-SC-029` | schema/input-shape | +| `M15-PKG-001` | `M15-AC-PKG-001` | `M15-SC-052` | package dependency graph | +| `M15-REG-001` | `M15-AC-REG-001` | `M15-SC-001`, `M15-SC-002`, `M15-SC-035` | registration integration | +| `M15-REG-002` | `M15-AC-REG-002` | `M15-SC-040`–`M15-SC-043` | candidate-package rejection | +| `M15-IDEM-001` | `M15-AC-IDEM-001` | `M15-SC-001`–`M15-SC-003`, `M15-SC-037`–`M15-SC-039`, `M15-SC-063`–`M15-SC-069` | original idempotency/restart | +| `M15-IDEM-002` | `M15-AC-IDEM-002` | `M15-SC-004`, `M15-SC-047`, `M15-SC-070` | replay identity/restart | +| `M15-COMMIT-001` | `M15-AC-COMMIT-001` | `M15-SC-005`, `M15-SC-040`, `M15-SC-054`, `M15-SC-059` | canonical commitment fixtures | +| `M15-GENESIS-001` | `M15-AC-GENESIS-001` | `M15-SC-054`–`M15-SC-058` | genesis create/restart/corruption | +| `M15-HEAD-001` | `M15-AC-HEAD-001` | `M15-SC-057`, `M15-SC-059`–`M15-SC-062` | exact head schema/equality | +| `M15-TXN-001` | `M15-AC-TXN-001` | `M15-SC-021`, `M15-SC-022`, `M15-SC-025`, `M15-SC-046`, `M15-SC-058` | commit/restart | +| `M15-TXN-002` | `M15-AC-TXN-002` | `M15-SC-046`, `M15-SC-058` | marker archive/current copy | +| `M15-AUDIT-001` | `M15-AC-AUDIT-001` | `M15-SC-005`, `M15-SC-026`, `M15-SC-057` | audit corruption | +| `M15-REPLAY-001` | `M15-AC-REPLAY-001` | `M15-SC-006`–`M15-SC-011`, `M15-SC-036` | replay dual-time | +| `M15-REPLAY-002` | `M15-AC-REPLAY-002` | `M15-SC-006`–`M15-SC-020`, `M15-SC-036`, `M15-SC-051` | replay result union | +| `M15-REPLAY-003` | `M15-AC-REPLAY-003` | `M15-SC-004`, `M15-SC-047`, `M15-SC-070` | replay retry | +| `M15-INTEGRITY-001` | `M15-AC-INTEGRITY-001` | `M15-SC-016`, `M15-SC-026`, `M15-SC-041`–`M15-SC-043`, `M15-SC-046`, `M15-SC-056`, `M15-SC-061`, `M15-SC-071`, `M15-SC-072` | integrity/corruption | +| `M15-INTEGRITY-002` | `M15-AC-INTEGRITY-002` | `M15-SC-024`, `M15-SC-025`, `M15-SC-044`, `M15-SC-045`, `M15-SC-062` | derived-state verification | +| `M15-RECOVERY-001` | `M15-AC-RECOVERY-001` | `M15-SC-021`, `M15-SC-022`, `M15-SC-025`, `M15-SC-055` | restart/fault injection | +| `M15-FS-001` | `M15-AC-FS-001` | `M15-SC-021`–`M15-SC-023`, `M15-SC-055` | fault-matrix injection | +| `M15-FS-002` | `M15-AC-FS-002` | `M15-SC-030`, `M15-SC-048` | path/no-follow safety | +| `M15-FS-003` | `M15-AC-FS-003` | `M15-SC-020`, `M15-SC-023`, `M15-SC-051` | lock/CAS/concurrency | +| `M15-PRIVACY-001` | `M15-AC-PRIVACY-001` | `M15-SC-018`, `M15-SC-027`–`M15-SC-032`, `M15-SC-071` | privacy/input safety | +| `M15-PRIVACY-002` | `M15-AC-PRIVACY-002` | `M15-SC-031`, `M15-SC-048`, `M15-SC-072` | path-redaction sweep | +| `M15-NET-001` | `M15-AC-NET-001` | `M15-SC-033` | static import/runtime probe | +| `M15-CRED-001` | `M15-AC-CRED-001` | `M15-SC-032`, `M15-SC-034` | static import/runtime probe | +| `M15-NOEXEC-001` | `M15-AC-NOEXEC-001` | `M15-SC-033`, `M15-SC-053` | facade/status/runtime probe | +| `M15-BASELINE-001` | `M15-AC-BASELINE-001` | `M15-SC-049` | implementation preflight | +| `M15-DOC-001` | `M15-AC-DOC-001` | `M15-SC-050` | documentation integration lint | + +The future implementation must include deterministic traceability validation that fails on an unmapped normative clause or source file, a missing requirement/acceptance/scenario target, a scenario referencing a missing requirement, a requirement without at least one scenario, a duplicate requirement/acceptance/scenario ID, or a non-contiguous scenario catalog. + +## Definition of Done for Future Implementation + +FounderOS can atomically register, restart-recover, independently verify, and dual-time fresh-evaluator replay one exact non-executing readiness evaluation while all cataloged scenarios pass. This definition is not satisfied by the current documentation-only phase. diff --git a/docs/milestones/milestone-15/FounderOS_Milestone_15_Architecture_Specification_v1.0.md b/docs/milestones/milestone-15/FounderOS_Milestone_15_Architecture_Specification_v1.0.md new file mode 100644 index 0000000..e79dfa4 --- /dev/null +++ b/docs/milestones/milestone-15/FounderOS_Milestone_15_Architecture_Specification_v1.0.md @@ -0,0 +1,197 @@ +# FounderOS Milestone 15 Architecture Specification v1.0 + +## Status + +**Specified — not implemented** + +## Purpose + +Define package ownership, authority flow, storage boundaries, and dependency direction for the durable readiness evaluation ledger and replay verification registry. + +## Package Responsibilities + +### `@founderos/knowledge-schema` + +The shared package will own strict, versioned, storage-independent schemas and inferred types for: + +- registration requests; +- evaluator configuration projections; +- Delivery and Invocation identity projections; +- canonical evaluation packages; +- committed transactions and idempotency ownership; +- genesis commitments, audit entries, exact ledger heads, and commit markers; +- replay attempts, durable historical-comparison/current-admissibility evidence, and ephemeral operation-result schemas; +- ephemeral integrity/recovery result schemas and non-authoritative derived-index schemas. + +It must not import `knowledge-engine`, filesystem APIs, provider SDKs, credential APIs, or network APIs. + +### `@founderos/knowledge-engine` + +The service package will own: + +- safe public-input capture; +- Milestone 12 ledger recovery and integrity orchestration; +- reuse of the Milestone 13 authoritative Delivery/Invocation resolver; +- approved Milestone 14 evaluator configuration and execution; +- canonical package comparison; +- registration, replay, recovery, and integrity orchestration; +- canonical fingerprint recomputation; +- the internal ledger application port; +- the governed local file-backed adapter; +- derived-index verification and rebuilding. + +It must not expose low-level record insertion, ledger-head mutation, commit-marker construction, test-only corruption seams, credential resolution, or transport. + +Durability classification is governed solely by the Evidence Durability Inventory in the privacy policy. Defining a strict shared result schema does not make its values durable: all application/adapter operation-result envelopes and transient status metadata, including registration, replay, integrity, recovery, derived-state, initialization/open, and failed-mutation results, plus validation reports, remain non-fingerprinted and non-persisted. An embedded authoritative or derived record retains its inventory class without making the surrounding result envelope durable. + +## Dependency Direction + +```text +knowledge-engine -> knowledge-schema +``` + +Shared contracts remain storage and provider neutral. Physical persistence implements an engine-owned port. No reverse dependency is permitted. + +## Authority Graph + +```text +Verified Milestone 12 Delivery Ledger + | + v +Milestone 13 Delivery / Invocation Resolver + | + v +Approved Milestone 14 Evaluator Configuration + | + v +Canonical Milestone 14 Evaluation Package + | + v +Milestone 15 Registration Orchestrator + | + v +Governed Readiness Ledger Port + | + v +Local File Adapter (first implementation only) +``` + +The upstream Delivery and Invocation artifacts remain authoritative. Milestone 15 binds and preserves their identity; it does not replace or weaken their verification. + +## Evaluator Configuration Projection + +Functions and authority objects are not serializable authority. Each transaction instead stores a strict projection containing: + +- `configurationBindingVersion`; +- `adapterId` and `adapterFingerprint`; +- `providerFamilyReference`; +- `transportPolicyId`, `transportPolicyFingerprint`, and `transportPolicyVersion`; +- `observabilityPolicyVersion`; +- `readinessEvaluatorContractVersion`; +- `configurationProjectionFingerprint`. + +At registration and replay, a supplied approved configured evaluator must reconstruct this projection exactly. Matching the projection does not authorize transport; it proves only configuration equivalence for deterministic readiness evaluation. + +## Public Application Boundary + +The future public facade may expose capabilities equivalent to: + +```text +verifyIntegrity() +recover() +registerVerifiedReadinessEvaluation(...) +readOriginalReadinessEvaluation(transactionId) +listCommittedReadinessEvaluations() +submitReadinessReplayAttempt(...) +listReadinessReplayAttempts(transactionId) +readHead() +rebuildDerivedIndexes() +``` + +Names may be refined during implementation, but authority separation must remain. Reads return immutable values or defensive copies and use deterministic ordering. + +## Registration Boundary + +The registration facade accepts only: + +- one strict registration request containing caller-requested ownership, registration semantic-event, registration audit-entry, and registration marker IDs in addition to the request, transaction, and idempotency identities; +- a governed Milestone 12 Delivery Ledger interface; +- one approved configured Milestone 14 evaluator; +- the governed readiness-ledger port; +- explicit operation time and bounded resource policy where required. + +It does not accept raw Knowledge, Query Results, Context content, a Delivery Ledger object for persistence, low-level readiness artifacts, secrets, URLs, provider clients, callbacks, commit markers, record writers, or index writers. + +## Replay Boundary + +Replay accepts one transaction identity, a replay idempotency key and requested request/attempt/semantic-event/audit-entry/marker IDs, the exact authoritative readiness input, `replayEvaluatedAt`, a newly supplied governed Delivery Ledger, and a fresh approved evaluator whose configuration projection matches the stored projection. + +After ledger verification, the replay orchestrator must first: + +- return an exact permanently owned retry as `idempotent-replay-returned`/`not-appended` only when all five replay IDs and the complete request fingerprint match; the original expected-head coordinate must match the owned request but need not equal the later current head; +- reject every non-exact reuse of an owned replay coordinate; + +For a distinct submission, it must: + +- re-run complete upstream authority verification; +- always reconstruct the original package with the exact stored canonical input and immutable `originalEvaluationTime`, independent of current Authorization validity; +- verify newly produced retention evidence with the fresh evaluator; +- compare the complete package, including ordered gate trace; +- separately assess current admissibility from the original Authorization evidence at `replayEvaluatedAt` without altering `decidedAt`, `expiresAt`, or original evaluation time; +- append a distinct result even when comparison mismatches or verification fails, provided the ledger itself remains valid and the attempt can be safely represented; +- keep append status only in the operation result, never in the replay-attempt commitment; +- leave the original transaction byte-for-byte unchanged. + +The valid combined result `matched` plus `authorization-expired` proves historical determinism while denying current admissibility. Historical reconstruction, current admissibility, and execution authority are separate concepts; replay never provides execution authority. + +## Persistence Boundary + +Authoritative persistence begins with the explicit canonical genesis complete-history commitment, zero-event head, immutable genesis marker archive, and byte-identical fixed current marker (`M15-GENESIS-001`). Genesis uses reserved deterministic marker ID `m15-genesis`, generation `0`, zero counts/sequence, and null latest event coordinates. Atomic fixed-marker installation is the empty-ledger visibility boundary. + +Non-empty persistence contains immutable registration and replay components plus one immutable archived commit-marker value per event. The same canonical marker bytes and `commitMarkerFingerprint` are installed at the fixed current-marker location. Only successful atomic replacement of that fixed current marker activates the marker-bounded prefix and creates visibility (`M15-TXN-001`, `M15-TXN-002`). The archived copy preserves each globally unique marker ID for permanent integrity and ownership checks; it is uncommitted evidence until its byte-identical fixed current-marker copy is installed. + +The exact ledger-head schema is the sole field set in `M15-COMMIT-001`: version/generation, three counts, sequence, latest audit-entry ID/fingerprint, latest semantic-event ID/fingerprint, latest subject transaction ID/fingerprint, complete-history fingerprint, and head fingerprint. The marker-embedded head and public `readHead()` bytes are authoritative; any separately stored `HEAD` projection must be byte-identical but remains outside commit authority. Derived state may be missing or corrupt and can be rebuilt from verified marker-bounded history without rolling back a committed event. + +## Transaction and Audit Ordering + +- Every committed event has a unique monotonically increasing ledger sequence. +- Genesis has generation and sequence `0`; the first registration advances exactly from the verified genesis head to generation and sequence `1`. +- Registration transactions and replay attempts share one audit sequence. +- The sole normative commitment-domain table and acyclic order are in `FounderOS_Durable_Readiness_Evaluation_Transaction_Contract_v1.0.md` (`M15-COMMIT-001`). +- Audit entries bind the previous ledger head and semantic event; complete history and the resulting head are computed afterward; the commit marker is computed last. +- Timestamps do not define ordering. +- One expected-head compare-and-swap prevents stale writers from committing. + +## Failure Semantics + +Fail before mutation on unsafe input, invalid upstream authority, configuration mismatch, package mismatch at registration, prohibited material, or invalid expected head. + +Fail closed during recovery on missing marker-bounded records, invalid fingerprints, broken audit links, conflicting ownership, duplicate authority, incomplete transactions, or ambiguous installed state. Never truncate, rewrite, or invent authoritative history. + +Replay mismatch is valid non-authoritative evidence, not ledger corruption. Corruption of the replay record itself is ledger corruption. + +## Security Boundary + +- Registration and replay are non-executing evaluation workflows. +- Credential References remain logical identifiers and fingerprints only. +- No secret-loading or transport dependency is permitted in production import closure. +- No readiness status grants live execution. +- Stored expired Authorization evidence remains expired. +- Fresh replay cannot extend Authorization validity. +- A stored Decision cannot bypass the Milestone 13 Invocation boundary. + +## Local Adapter Limitations + +The first adapter assumes: + +- one cooperative writer on one machine; +- atomic rename within one filesystem; +- file synchronization support; +- a cooperative local administrator; +- explicit operator handling of abandoned locks. + +It does not provide distributed coordination, hostile privileged-filesystem resistance, coordinated rollback protection, replication, remote durability, or network-filesystem consensus. + +## Architecture Decision + +ADR-0019 remains **Proposed** until an implementation milestone is separately authorized, reviewed, and accepted. diff --git a/docs/milestones/milestone-15/FounderOS_Milestone_15_Codex_Implementation_Prompt_v1.0.md b/docs/milestones/milestone-15/FounderOS_Milestone_15_Codex_Implementation_Prompt_v1.0.md new file mode 100644 index 0000000..d7e05fc --- /dev/null +++ b/docs/milestones/milestone-15/FounderOS_Milestone_15_Codex_Implementation_Prompt_v1.0.md @@ -0,0 +1,378 @@ +# FounderOS Milestone 15 Codex Implementation Prompt v1.0 + +## Status + +**Specified — not implemented** + +This is a future implementation artifact. Do not execute it during the documentation-only phase. + +## Role and Mission + +You are the lead engineer responsible for implementing FounderOS Milestone 15 — Durable Production-Provider Readiness Evaluation Ledger and Replay Verification Registry Foundation. + +The objective is to make the non-executing Milestone 14 readiness evaluation durable, restart-safe, auditable, and independently replay-verifiable without adding credential access, outbound transport, a real provider, or a live-ready state. + +## Authorization Precondition + +The immutable runtime predecessor is: + +```text +MILESTONE_14_RUNTIME_BASE_SHA = a93faa29eecc37f2a08c79cda4c3075ffacfea3e +``` + +No implementation authorization may substitute a different Milestone 14 predecessor. Do not execute this prompt until the documentation PR is merged and a separate implementation authorization supplies: + +```text +AUTHORIZED_MILESTONE_15_DOCUMENTATION_MERGE_SHA +``` + +That SHA must equal local `main` and `origin/main` at execution time, descend from `MILESTONE_14_RUNTIME_BASE_SHA`, and have merge base exactly `MILESTONE_14_RUNTIME_BASE_SHA` for the reviewed Milestone 15 documentation delta. It must contain the approved documents and differ from the runtime predecessor only by their reviewed publication and repository-governance changes. + +The only authorized implementation branch name is: + +```text +codex/milestone-15 +``` + +Create or switch to it only from the separately authorized documentation merge SHA. Fail preflight if the current branch is `main`, `codex/milestone-15-specification`, or any other branch; the runtime predecessor differs; documentation merge authorization is missing; the authorized SHA differs from local or remote `main`; the branch base is unauthorized; the worktree is unclean; or unreviewed Milestone 15 runtime changes already exist. + +The separate authorization must also identify: + +- the approved repository and base branch; +- the exact authorized documentation merge SHA; +- the reviewed Milestone 15 specification set; +- permitted publication actions. + +Documentation-only authorization is insufficient. + +## Required Reading + +Before changing code, read: + +- `README.md` +- `AGENTS.md` +- `CONTRIBUTING.md` +- `ARCHITECTURE_DECISIONS.md` +- `DOCUMENTATION_INDEX.md` +- all Milestone 12 specifications under `docs/milestones/milestone-12/` +- all Milestone 13 specifications under `docs/milestones/milestone-13/` +- all Milestone 14 specifications under `docs/milestones/milestone-14/` +- all Milestone 15 specifications under `docs/milestones/milestone-15/`, excluding this prompt until the controlling contracts are understood +- existing durable Delivery and Reasoning ledger implementations and tests +- existing Milestone 14 evaluator, input-safety, authority, retention, facade, and evaluation tests + +## Architecture Constraints + +Preserve: + +```text +knowledge-engine -> knowledge-schema +``` + +`@founderos/knowledge-schema` owns strict shared contracts. `@founderos/knowledge-engine` owns verification, orchestration, application ports, canonical comparison, recovery, integrity, derived indexes, and the local adapter. + +Do not redesign Milestones 12–14 or create a second readiness evaluator. + +## Required Implementation Scope + +### Shared Contracts + +Implement strict, versioned schemas and inferred TypeScript types for: + +- readiness evaluation registration request; +- evaluator configuration projection; +- durable Delivery and Invocation identity projection; +- canonical readiness evaluation package; +- committed readiness evaluation transaction; +- permanent idempotency ownership; +- genesis complete-history commitment, genesis ledger head and marker, audit entry, exact event ledger head, and event commit marker; +- replay request, attempt, comparison, and verification result; +- integrity and recovery results; +- derived index snapshot and status; +- stable application result unions and reason codes. + +All contracts must reject unknown fields, unsupported versions, unsupported values, and noncanonical shapes. + +### Registration Orchestration + +Implement one governed registration facade that: + +1. captures exact plain own data before authority access; +2. rejects prohibited and executable material; +3. requires caller-requested ownership, registration semantic-event, registration audit-entry, and registration marker IDs and binds them into the request fingerprint; +4. recovers and verifies the readiness ledger, including explicit genesis authority; +5. recovers and verifies the supplied Milestone 12 Delivery Ledger; +6. reuses the sole Milestone 13 Delivery/Invocation authority resolver; +7. reconstructs the evaluator configuration projection; +8. evaluates through an approved configured Milestone 14 evaluator; +9. verifies the Decision with that same evaluator instance and exact retention evidence; +10. compares any supplied expected package with the evaluator-produced package; +11. claims permanent global ownership of all `M15-IDEM-001` coordinates under expected-head compare-and-swap; +12. atomically commits the complete registration transaction and audit entry; +13. stops before credential resolution or transport. + +Do not accept a prebuilt package as authority. + +An identical retry is not lookup-only. It must execute the capture-through-package-comparison sequence exactly once, reconstruct the request and package, and prove exact equality across the key, every ownership/request/transaction/Decision/registration-event coordinate, the permanent ownership record, and the original transaction. It then returns `idempotent-original-returned` without append, ownership refresh, head advancement, or Authorization extension. + +### Replay Orchestration + +Implement fresh-evaluator replay that: + +1. recovers and verifies the readiness ledger; +2. detects an exact owned replay retry by matching the replay idempotency key; requested replay request, attempt, semantic-event, audit-entry, and marker IDs; and the complete request fingerprint, then verifies and returns the original attempt as `idempotent-replay-returned` without append; its owned expected-head coordinate need not equal the later current head; +3. rejects every non-exact reuse of an owned replay coordinate; +4. reads and verifies the immutable original transaction for a distinct submission; +5. accepts a newly supplied governed Delivery Ledger and fresh approved evaluator; +6. verifies exact stored configuration and authority projections; +7. always reconstructs the exact stored canonical input at immutable `originalEvaluationTime`, independently of current admissibility; +8. verifies the fresh Decision with that evaluator and fresh retention evidence; +9. compares the complete canonical package and classifies historical status as `matched`, `mismatched`, `verification-failed`, or `not-assessed`; +10. separately evaluates original Authorization and authority evidence at explicit `replayEvaluatedAt` as `admissible`, `authorization-expired`, `authorization-denied`, `authorization-review-required`, `authorization-not-evaluated`, `authorization-invalid-evidence`, `authority-mismatch`, or `not-assessed`; +11. appends a recordable attempt, then reports operation-only `appended` after marker activation, including the valid combination `matched` plus `authorization-expired`, or returns `not-recorded`/`not-appended` with exactly one stable operation reason; +12. never stores append status inside the replay attempt; +13. never mutates the original transaction; +14. never refreshes Authorization or enables transport. + +### Governed Ledger Port + +Define an engine-owned storage port that supports verified reads, exclusive expected-head append, recovery, integrity verification, head reads, replay listing, derived-index inspection, and explicit index rebuild. + +The public package facade may expose governed application operations and the approved local adapter factory. It must not expose low-level writers, direct record insertion, commit-marker mutation, ledger-head mutation, raw index mutation, or test corruption seams. + +### Local File Adapter + +Implement one Git-ignored local adapter with: + +- explicit bounded runtime root; +- traversal, symlink, unsafe-entry, special-file, and overlap rejection; +- no-follow leaf operations where available and physical-directory identity rechecks; +- cooperative single-writer lock; +- expected-head compare-and-swap; +- canonical JSON and domain-separated SHA-256; +- immutable deterministic event locations; +- safe explicit creation of one deterministic genesis history/head/marker authority, with reserved marker ID `m15-genesis`, generation `0`, and atomic fixed-marker installation as the initialization visibility boundary; +- temporary staging, file synchronization, atomic same-filesystem rename, and directory synchronization where supported; +- immutable event-local marker archives plus a separately replaced, byte-identical authoritative fixed current marker; +- restart recovery and crash-orphan classification; +- fail-closed ambiguous recovery; +- rebuildable non-authoritative derived indexes; +- stable public errors without physical paths or secret material; +- bounded resources before mutation. + +Document and test its cooperative local limitations. Do not claim distributed or hostile-process safety. + +## Canonical Data and Fingerprints + +Reuse FounderOS canonicalization patterns where compatible. Canonical input must be finite, plain, acyclic, and composed only of enumerable own data properties. Reject accessors before invoking them, symbols, non-enumerable fields, inherited capabilities, custom prototypes, aliases that undermine capture, functions, and unsupported built-ins. + +Use lowercase SHA-256 with existing FounderOS canonical JSON. Implement exactly the artifact names, domain tags, unsigned schemas, included/excluded fields, dependency order, fingerprint fields, and authority classes in the sole normative `M15-COMMIT-001` table in the Durable Readiness Evaluation Transaction Contract. Do not create a variant table or a competing serializer/hash. Implement the sole exhaustive Evidence Durability Inventory from the privacy policy: every application/adapter operation-result envelope and transient status value, including registration, replay, append, integrity, recovery, derived-state, initialization/open, and failed-mutation results, plus validation reports, remains non-fingerprinted and non-persisted unless a separately reviewed specification outside readiness-ledger authority explicitly defines a durable validation report. + +Implement the exact ledger-head keys without aliases: `headContractVersion`, `headGeneration`, three counts, `lastCommittedLedgerSequence`, latest audit-entry ID/fingerprint, latest semantic-event ID/fingerprint, latest subject transaction ID/fingerprint, `completeHistoryFingerprint`, and `ledgerHeadFingerprint`. Genesis makes all latest coordinates null; registration and replay make all non-null. Marker-embedded head bytes, `readHead()`, and rebuilt derived `HEAD` bytes must be identical. Reject `last committed event` or other variant fields. + +The canonical marker is computed last with the resulting head embedded. Preserve one immutable event-local marker archive, then atomically install byte-identical bytes at the fixed current-marker location. Only that fixed-marker replacement is the authoritative visibility boundary (`M15-TXN-001`, `M15-TXN-002`); the archive preserves marker history and global identity but never activates an event by itself. A separate `HEAD` projection and indexes are derived and rebuildable. An unactivated component is never committed; a committed marker is never rolled back because derived publication failed. + +## Idempotency Requirements + +- First valid registration permanently owns the key. +- First valid registration globally owns the caller-requested ownership, registration semantic-event, registration audit-entry, and registration marker IDs together with the registration request ID, transaction ID, and evaluator-produced Decision ID. +- Identical registration retry returns the exact original without append. +- Conflicting key reuse fails across restart. +- Conflicting ownership, transaction, request, Decision, registration semantic-event, registration audit-entry, registration marker, replay-key, or replay-ID reuse fails with the stable coordinate-specific reason. +- Every `M15-IDEM-001` identity is globally owned even across different keys or requests, with the stable conflict reasons specified in the registration contract. +- Replay request, attempt, semantic-event, audit-entry, and marker identities are caller-bound in the replay request and globally owned. Exact retry is allowed only for the full owned tuple and complete request fingerprint, and its original expected-head coordinate need not equal the later current head (`M15-REPLAY-003`). +- Derived-index loss never frees ownership. +- Expiration never frees ownership. +- Ownership and complete registration commit atomically. + +## Required Integrity and Recovery Behavior + +Verify: + +- exact marker-bounded event set; +- sequence and audit-chain continuity; +- transaction, request, package, ownership, replay, and marker fingerprints; +- canonical genesis history, head, marker, archive/current-marker byte equality, and initialization classification; +- exact Decision, gate order, retention evidence, evaluator configuration, and Delivery/Invocation bindings; +- replay attempt references and classifications; +- counts, sequence, latest audit-entry, latest semantic-event, latest subject-transaction, head, and complete-history coordinates; +- privacy and no-execution invariants. + +Do not silently repair, truncate, skip, resign, or overwrite authoritative corruption. + +Implement every row of `M15-FS-001`, the sole 19-point fault/lock matrix. Do not steal locks by elapsed time. Under a stale lock, read-only integrity may run without mutation; writes return `operator-cleanup-required`, and operator cleanup may remove only the lock after proving no active writer. + +Report derived-index integrity separately. Rebuild indexes only through an explicit operation from valid authoritative history. + +## Privacy and No-Execution Requirements + +Reject or exclude: + +- raw Knowledge or Query Results; +- hidden Context or Context content; +- persisted Delivery Ledger objects or ports; +- credential values, secret bytes, tokens, keys, environment contents, or authorization headers; +- arbitrary URLs or endpoints; +- provider request or response bodies; +- clients, callbacks, functions, streams, SDK objects, or executable payloads; +- caller-supplied commit markers, writers, locks, or indexes; +- Agents, Hermes, MCP, or tool/function payloads. + +Persist Credential Reference ID and fingerprint only. + +Persist only the authoritative and derived members enumerated by the sole Evidence Durability Inventory. Every application/adapter operation-result envelope and transient status value, plus validation reports, is ephemeral public or validation output: do not write it into authoritative records, staging envelopes intended for installation, markers, derived state, logs, traces, metrics, or observability artifacts, and do not fingerprint it. An authoritative or derived record returned inside an ephemeral result retains its inventory class, but the envelope never permits a second durable copy. + +Production import closure must contain no HTTP, DNS, TLS, socket, proxy, provider SDK, credential resolver, environment-secret, Agent, Hermes, MCP, streaming, or tools/functions capability. + +No contract or result may express `live-ready`, production enablement, or equivalent authority. + +## Required Tests + +Implement unit, integration, restart, adapter, corruption, concurrency, and facade tests covering at least: + +- successful first registration; +- canonical genesis bytes and fingerprints across clean processes; +- safe first create and every genesis crash point before staging, during staging, after genesis archive creation, and after fixed-marker installation; +- uninitialized, initialized-empty, incomplete-genesis, and corrupt-genesis classification; +- independently recomputed genesis history, head, marker, archive/current equality, and first-registration advance from genesis; +- exact genesis, first-registration, and replay head fixtures; unknown/missing head-key rejection; substituted latest-coordinate rejection; and byte equality among marker, `readHead()`, and rebuilt `HEAD`; +- identical idempotent registration replay; +- conflicting idempotency reuse; +- duplicate Decision ID; +- duplicate transaction ID; +- duplicate registration request ID under a different key; +- duplicate Decision ID under a different request; +- duplicate ownership ID; +- duplicate registration semantic-event ID; +- duplicate registration audit-entry ID; +- duplicate registration marker ID; +- the same original-registration IDs under another key or request, the same key with changed requested IDs, and exact retry with every original coordinate; +- replay idempotency-key conflict and exact replay retry; +- stale fingerprint; +- coherent re-sign substitution; +- altered gate order; +- altered retention evidence; +- evaluator configuration mismatch; +- Delivery and Invocation mismatch; +- missing transaction component; +- crash before event installation; +- crash after event installation and before marker replacement; +- marker referencing incomplete state; +- stale expected head; +- concurrent writer conflict; +- symlink, traversal, special-file, and overlap rejection; +- corrupt authoritative record; +- missing and corrupt rebuildable indexes; +- deterministic index rebuild; +- fresh-evaluator replay match; +- fresh-evaluator replay match while currently admissible; +- replay mismatch; +- replay verification failure; +- expired Authorization during replay; +- historical match plus current Authorization expiration; +- current Authorization denial, review required, not evaluated, and invalid evidence; +- original-time reconstruction plus current-time admissibility; +- replay-ledger integrity failure, original transaction not found, and invalid replay input; +- replay append failure, stale expected replay head, and replay concurrent writer conflict; +- exact replay retry after later head advancement, with all requested replay identities verified and no append; +- lock interruption and stale lock requiring operator cleanup; +- every registration and replay row of `M15-FS-001`, including derived `HEAD` rebuild after marker commit; +- raw credential and credential-like material; +- accessor-backed, hidden, symbolic, inherited, custom-prototype, aliased, and executable input; +- stored-data privacy inspection; +- stored-data and log inspection proving no application/adapter operation-result envelope, transient status value, or validation report persists, while schema-backed public results remain canonical/redacted/non-fingerprinted and validation reports remain redacted, non-fingerprinted, and ephemeral; +- no-network import and runtime proof; +- no-credential import and runtime proof; +- deterministic repeated bytes and stable ordering; +- unknown and explicit-`undefined` fields; +- physical-path privacy in errors and reports; +- immutable marker archive/current-marker equality, missing archives, duplicate marker IDs, and archived-candidate invisibility; +- no-follow leaf and physical directory-identity substitution detection; +- every future implementation-preflight rejection case; +- ADR, status, version, index-inventory, and relative-link documentation lint; +- static package dependency-direction proof and no-execution facade/status proof; +- complete Milestone 04–14 regression preservation with no predecessor-test loss: before counting any Milestone 15 tests, at least the pinned baseline of 42 test files and 1,038 tests must execute and pass. + +Use every `M15-SC-*` scenario in the Acceptance Criteria as the minimum executable scenario catalog. Implement the exact normative-clause parser, source-section ownership grammar, and traceability rules specified there. Validation fails on an unmapped normative clause or source file, a missing requirement/acceptance/scenario target, a requirement without a scenario, a scenario referencing a missing requirement, a non-contiguous scenario catalog, or a duplicate requirement/acceptance/scenario ID. + +Use bounded temporary directories. Do not write fixtures into canonical source trees. Preserve original documents. + +## Documentation Updates + +Only after implementation matches the specification: + +- update status labels from specified to implemented where true; +- update `README.md`, package READMEs, `DOCUMENTATION_INDEX.md`, and `CHANGELOG.md` only for real behavior; +- change ADR-0019 from Proposed to Accepted only if the implementation review approves the architecture; +- document commands, local runtime root, operating limitations, and explicit exclusions. + +## Explicitly Deferred + +Do not implement: + +- real provider adapters; +- credential resolution or secret-store access; +- environment-variable secret loading; +- HTTP, DNS, TLS, sockets, proxies, SDKs, or outbound transport; +- provider dispatch or response ingestion; +- streaming; +- tools or function calling; +- Agents, Hermes, or MCP; +- provider routing or failover; +- distributed locks, ledgers, consensus, replication, or coordinated rollback protection; +- external observability; +- UI, deployment, or production enablement. + +## Implementation Order + +1. Enforce the exact runtime-predecessor, documentation-merge SHA, clean-worktree, no-preexisting-runtime-change, and `codex/milestone-15` branch preflight above. +2. Read the complete controlling documentation and implementation patterns. +3. Produce a detailed plan mapping every acceptance criterion to code and tests. +4. Implement shared contracts and focused tests. +5. Implement engine verification and registration orchestration. +6. Implement replay orchestration. +7. Implement the governed ledger port and in-memory test seam. +8. Implement the local file adapter and crash/path-safety tests. +9. Add privacy, bypass, deterministic, and import-closure tests. +10. Run focused verification after each small change. +11. Run the complete suite. +12. Perform a whole-branch architecture, security, and scope review. +13. Update only documentation justified by actual implementation. +14. Stop before publication unless separately authorized. + +## Required Verification + +Run: + +```bash +pnpm format:check +pnpm lint +pnpm build +pnpm typecheck +pnpm test +git diff --check +``` + +All gates, all 72 scenarios `M15-SC-001` through `M15-SC-072`, and all Milestone 04–14 regressions must pass. The predecessor suite must be reported separately and may not fall below 42 test files and 1,038 passing tests before any Milestone 15 tests are counted; any lower count fails verification unless a separate reviewed authorization explicitly changes the predecessor baseline. + +## Final Implementation Report + +Return: + +1. `GO` or `NOT READY`. +2. Exact base, branch, and head SHAs. +3. Implementation summary. +4. Added and modified files. +5. Contract and package-boundary review. +6. Registration, idempotency, replay, recovery, and adapter behavior. +7. Privacy and no-execution evidence. +8. Test categories and exact counts. +9. Verification-command results. +10. Architecture review findings by severity. +11. Known local-adapter limitations. +12. Explicit deferred capabilities. +13. Publication recommendation without taking unauthorized publication action. + +## Stop Condition + +Stop when the separately authorized implementation, tests, verification, and review are complete. Do not commit, push, create or merge a pull request, tag, release, deploy, begin credential work, enable transport, or begin Milestone 16 unless separately authorized. diff --git a/docs/milestones/milestone-15/FounderOS_Milestone_15_Durable_Production_Provider_Readiness_Evaluation_Ledger_and_Replay_Verification_Registry_Foundation_Specification_v1.0.md b/docs/milestones/milestone-15/FounderOS_Milestone_15_Durable_Production_Provider_Readiness_Evaluation_Ledger_and_Replay_Verification_Registry_Foundation_Specification_v1.0.md new file mode 100644 index 0000000..6408ff8 --- /dev/null +++ b/docs/milestones/milestone-15/FounderOS_Milestone_15_Durable_Production_Provider_Readiness_Evaluation_Ledger_and_Replay_Verification_Registry_Foundation_Specification_v1.0.md @@ -0,0 +1,167 @@ +# FounderOS Milestone 15 Durable Production-Provider Readiness Evaluation Ledger and Replay Verification Registry Foundation Specification v1.0 + +## Status + +**Specified — not implemented** + +## Purpose + +Define the durable, restart-safe, and independently replay-verifiable boundary for the non-executing Milestone 14 production-provider readiness evaluation. + +## Objective + +FounderOS must be able to commit one exact, independently verified Milestone 14 readiness evaluation transaction, recover it after restart, and append evidence that a fresh approved evaluator reconstructed the same canonical evaluation package from the same governed authority. + +The durable transaction is audit and verification evidence only. It is not authorization for credential access, provider transport, or live traffic. + +## Architectural Sequence + +```text +Milestone 12 Durable Delivery Ledger + | + v +Milestone 13 Governed Invocation Authority + | + v +Milestone 14 Non-Executing Readiness Evaluator + | + v +Milestone 15 Durable Readiness Evaluation Ledger + | + v +Future separately approved credential and transport boundaries +``` + +Dependency direction remains: + +```text +knowledge-engine -> knowledge-schema +``` + +## In Scope + +- Strict, versioned, storage-independent readiness-ledger contracts +- Durable registration requests and permanent idempotency ownership +- Exact Delivery, Invocation, Adapter, capability, Credential Reference, Transport Policy, Decision, gate-trace, retention, and evaluator-configuration bindings +- Immutable committed readiness evaluation transactions +- Explicit canonical genesis history/head/marker authority, hash-chained audit entries, and an authoritative fixed current marker +- Fresh-evaluator replay verification after restart +- Append-only replay attempts with separate historical reconstruction, current admissibility, and append statuses, plus distinct `recorded`/`not-recorded` operation results +- Integrity verification and deterministic recovery +- Rebuildable non-authoritative derived indexes +- One governed local file-backed adapter specification +- Canonical JSON and SHA-256 fingerprints +- Path safety, privacy, and no-execution enforcement +- Deterministic evaluation scenarios and full Milestone 04–14 regression preservation + +## Out of Scope + +- Real provider adapters or provider request dispatch +- Credential resolution, secret-store access, or environment-secret loading +- HTTP, DNS, TLS, socket, proxy, SDK, or other outbound transport +- Live-ready or production-enabled state +- Provider response ingestion +- Streaming or tools/function calling +- Agents, Hermes, or MCP +- Provider routing or failover +- Distributed ledgers, locks, coordination, replication, or rollback protection +- External observability, UI, deployment, or production enablement + +## Authoritative Registration Flow + +1. Capture and validate one exact plain-data registration request. +2. Recover the readiness ledger and verify its authoritative integrity. +3. Recover and verify the supplied Milestone 12 Delivery Ledger. +4. Resolve the exact Milestone 13 Delivery and Invocation authority. +5. Verify the supplied evaluator configuration against its canonical projection. +6. Evaluate the exact authoritative Milestone 14 input through that configured evaluator. +7. Verify the returned Decision with the same evaluator instance and original retention evidence. +8. Compare any caller-supplied evaluation package with the evaluator-produced canonical package. +9. Reject prohibited, hidden, executable, credential-bearing, endpoint-bearing, or low-level capabilities. +10. For an exact owned retry, reconstruct and verify the same request and package through the resolver and evaluator exactly once, then return the original without append or head advancement. +11. For a first registration, claim permanent global ownership of the idempotency key, caller-requested ownership ID, registration request ID, transaction ID, Decision ID, and caller-requested registration semantic-event, registration audit-entry, and registration marker IDs against the verified expected ledger head. +12. Commit one complete immutable readiness evaluation transaction atomically. +13. Advance the audit chain and authoritative commit marker. +14. Stop before credential resolution or transport. + +## Authoritative Replay Flow + +1. Recover and verify the durable readiness ledger. +2. For an exact owned retry, match the replay idempotency key; request, attempt, semantic-event, audit-entry, and marker IDs; and complete original request fingerprint, verify the original attempt and activating marker, and return `idempotent-replay-returned`/`not-appended`. Its stored expected head must match the original request but need not equal the later current head. +3. For a distinct submission, reject every owned-coordinate reuse and read the immutable original transaction. +4. Capture a newly supplied governed Delivery Ledger and a fresh approved configured evaluator. +5. Verify the stored evaluator configuration and capture supplied governed authority for reconstruction. +6. Always perform historical reconstruction at immutable `originalEvaluationTime`: evaluate the exact original canonical input through the fresh evaluator, verify its newly issued Decision and retention evidence through that evaluator instance, and compare the complete package with the stored original. +7. Separately assess current admissibility from the immutable original Authorization evidence at explicit `replayEvaluatedAt`; never replace, refresh, or extend that evidence. +8. Record separate historical-reconstruction and current-admissibility statuses in one immutable replay attempt; append status is not part of that attempt. +9. Append that replay attempt when the readiness ledger and append preconditions remain safe. +10. Return an operation-level `recorded`, `not-recorded`, or `idempotent-replay-returned` result that never claims append success after append failure. +11. Stop before credential resolution or transport. + +Historical reconstruction is independent of current admissibility (`M15-REPLAY-001`). An expired Authorization may therefore produce `historicalReconstructionStatus = matched` together with `currentAdmissibilityStatus = authorization-expired`. Replay never refreshes, extends, or replaces stored Authorization evidence and never grants execution authority. + +## Core Contracts + +Milestone 15 specifies: + +- readiness evaluation registration request; +- evaluator configuration projection; +- durable Delivery and Invocation identity projection; +- canonical readiness evaluation package; +- committed readiness evaluation transaction; +- idempotency ownership record; +- genesis complete-history commitment, genesis head and marker, audit entry, exact event ledger head, and event commit marker; +- replay attempt and replay verification result; +- integrity and recovery results; +- derived index snapshot. + +## Authoritative and Derived State + +Authoritative state begins with one explicit canonical genesis complete-history commitment, zero-event ledger head, immutable genesis marker archive, and byte-identical fixed current marker (`M15-GENESIS-001`). Non-empty authority consists only of marker-bounded, schema-valid, fingerprint-valid immutable registration transactions, idempotency ownership, audit entries, replay attempts, immutable event-local marker archives, and that fixed current marker. Each archived marker is byte-identical to the canonical marker value that activated genesis or its event; only atomic installation at the fixed current-marker location activates visibility (`M15-TXN-001`, `M15-TXN-002`). + +Derived indexes may accelerate lookup by transaction ID, Decision ID, idempotency key, Adapter ID, Invocation ID, or replay sequence. They are non-authoritative, must verify against complete replay, and may be discarded and rebuilt. Corrupt derived state must never invalidate otherwise valid authoritative history or silently replace it. + +## Identity and Fingerprinting + +- All contract versions are explicit. +- All timestamps are explicit canonical UTC instants supplied by the caller or operation boundary. +- Canonical bytes use the FounderOS strict canonical JSON rules for finite, plain, acyclic data. +- Fingerprints use lowercase SHA-256 hexadecimal output. +- Ordered arrays, including gate traces and reason codes, retain order when order is semantically meaningful. +- Every record binds its semantic category into its fingerprint domain. +- A transaction or replay-attempt fingerprint covers its semantic payload and excludes outer commit coordinates. +- All commitment tags, named unsigned schemas, included and excluded fields, authority classes, and the acyclic computation order are defined solely by the normative table in `FounderOS_Durable_Readiness_Evaluation_Transaction_Contract_v1.0.md` (`M15-COMMIT-001`). +- The exact ledger-head field set is version/generation, registration/replay/total counts, last sequence, latest audit-entry ID/fingerprint, latest semantic-event ID/fingerprint, latest subject transaction ID/fingerprint, complete-history fingerprint, and head fingerprint. Genesis makes all latest coordinates null; event heads make them non-null. Marker embedding, `readHead()`, and derived `HEAD` use byte-identical head bytes. +- The canonical marker is archived immutably per event, and its byte-identical fixed current-marker copy embeds the resulting ledger head. Only atomic fixed-marker installation is the visibility boundary. Separate `HEAD` and index files are derived only. + +## Required Invariants + +1. Registration begins only after readiness-ledger and Delivery-ledger recovery and integrity succeed. +2. Exact Milestone 13 Delivery and Invocation authority remains the sole upstream authority path. +3. Authorization is evaluated before Credential Reference or Transport planning. +4. The same Milestone 14 evaluator that produces a registration Decision must verify it before persistence. +5. A fresh evaluator is required for replay after restart; historical reconstruction always uses the original canonical input and `originalEvaluationTime`, while current admissibility uses `replayEvaluatedAt`. +6. Only canonical Milestone 14 statuses may be stored; no live-ready equivalent exists. +7. Credential material is never accepted or persisted; only validated IDs and fingerprints are recorded. +8. Original transactions are immutable; replay attempts are separate append-only evidence. +9. First valid ownership of the registration idempotency key, ownership ID, registration request ID, transaction ID, Decision ID, registration semantic-event ID, registration audit-entry ID, and registration marker ID is permanent and globally unambiguous; replay idempotency-key and five replay-ID ownership is equally permanent. +10. Reuse outside the complete exact-retry tuple fails closed, including cross-key or cross-request reuse of otherwise identical bytes. +11. Coherently re-signed substitutions fail when any authority binding differs. +12. Ambiguous, partial, reordered, missing, or corrupt authoritative state is never silently repaired. +13. Public inputs reject accessors, symbols, inherited or non-enumerable capabilities, custom prototypes, functions, clients, callbacks, URLs, and executable values before authority access or mutation. +14. No production import closure may introduce credential or network capability. +15. A durable record can never authorize provider execution. + +## Local Adapter Boundary + +The first specified adapter is cooperative, local, single-machine, and same-filesystem only. It acquires its single-writer lock before staging, uses expected-head compare-and-swap, atomic temporary-write/fsync/rename publication, immutable event records and marker archives, and a separately replaced byte-identical fixed current marker as the commit point. + +It does not claim hostile privileged-filesystem protection, distributed consensus, coordinated rollback protection, network-filesystem safety, or automatic stale-lock recovery. Abnormal process termination may require explicit operator lock cleanup. + +## Definition of Success for Future Implementation + +FounderOS can durably register and recover one exact verified Milestone 14 evaluation, independently verify every authoritative record, reproduce that evaluation with a fresh approved evaluator after restart, append immutable replay evidence, reject conflicts and unsafe material, rebuild derived indexes, preserve Milestone 04–14 behavior, and prove that no credential resolution or provider transport path exists. + +## Specification-Phase Stop + +This document defines future implementation behavior. Milestone 15 is not implemented by this documentation set. diff --git a/docs/milestones/milestone-15/FounderOS_Milestone_15_Package_README_v1.0.md b/docs/milestones/milestone-15/FounderOS_Milestone_15_Package_README_v1.0.md new file mode 100644 index 0000000..06dd828 --- /dev/null +++ b/docs/milestones/milestone-15/FounderOS_Milestone_15_Package_README_v1.0.md @@ -0,0 +1,67 @@ +# FounderOS Milestone 15 Package README v1.0 + +## Status + +**Specified — not implemented** + +## Milestone + +**Milestone 15 — Durable Production-Provider Readiness Evaluation Ledger and Replay Verification Registry Foundation** + +## Purpose + +Milestone 15 is specified to replace Milestone 14's deliberately process-local readiness-decision issuance limitation with durable transaction evidence and fresh-evaluator replay verification after restart. + +It preserves Milestone 14's structural stop before credential resolution and provider transport. A stored evaluation remains an audit artifact, not live-execution authority. + +## Architecture + +```text +Durable Delivery and Invocation Authority + | + v +Non-Executing Milestone 14 Evaluator + | + v +Verified Canonical Evaluation Package + | + v +Atomic Durable Registration Transaction + | + v +Fresh-Evaluator Replay Attempts +``` + +Replay has two independent time axes: historical reconstruction always uses immutable `originalEvaluationTime`, while current admissibility uses explicit `replayEvaluatedAt`. A historical match may therefore be recorded together with current Authorization expiration or denial. + +The ledger begins with one deterministic explicit genesis history/head/marker commitment. Genesis and each later event retain one immutable archived marker value. Atomic installation of byte-identical bytes at the fixed current-marker location is the sole authoritative visibility boundary; the archive preserves history but cannot activate visibility. The exact embedded head uses audit-entry, semantic-event, and subject-transaction coordinates; `readHead()` returns those same bytes, while separate `HEAD` projections and indexes are derived and rebuildable. Registration callers request every original-event ID, and both registration and replay idempotency keys and IDs are globally owned. The transaction contract contains the sole normative commitment-domain table, the local adapter contains the sole 19-row event fault-point matrix plus explicit genesis initialization fault behavior, and the acceptance criteria contain clause-level source ownership plus the normative requirement-to-scenario traceability matrix. + +Contracts are intended for `@founderos/knowledge-schema`; orchestration, canonical verification, ledger ports, and the local adapter are intended for `@founderos/knowledge-engine`. Dependency direction remains `knowledge-engine -> knowledge-schema`. + +## Document Inventory + +1. `FounderOS_Milestone_15_Durable_Production_Provider_Readiness_Evaluation_Ledger_and_Replay_Verification_Registry_Foundation_Specification_v1.0.md` +2. `FounderOS_Milestone_15_Architecture_Specification_v1.0.md` +3. `FounderOS_Durable_Readiness_Evaluation_Transaction_Contract_v1.0.md` +4. `FounderOS_Readiness_Evaluation_Registration_and_Idempotency_Contract_v1.0.md` +5. `FounderOS_Durable_Readiness_Evaluation_Ledger_Contract_v1.0.md` +6. `FounderOS_Readiness_Replay_Verification_Registry_Contract_v1.0.md` +7. `FounderOS_Readiness_Ledger_Integrity_and_Recovery_Specification_v1.0.md` +8. `FounderOS_Local_File_Readiness_Ledger_Adapter_Specification_v1.0.md` +9. `FounderOS_Readiness_Evidence_Privacy_and_No_Execution_Policy_v1.0.md` +10. `FounderOS_Milestone_15_Acceptance_Criteria_v1.0.md` +11. `FounderOS_Milestone_15_Verification_Checklist_v1.0.md` +12. `FounderOS_Milestone_15_Package_README_v1.0.md` +13. `FounderOS_Milestone_15_Codex_Implementation_Prompt_v1.0.md` + +The package contains 13 English Markdown documents. + +## Explicit Non-Goals + +The specification does not authorize or implement real providers, credential resolution, secret access, environment-secret loading, outbound transport, provider dispatch, response ingestion, streaming, tools/functions, Agents, Hermes, MCP, routing, failover, distributed persistence, external observability, UI, deployment, or production enablement. + +## Implementation Status + +No Milestone 15 runtime contracts, source modules, tests, fixtures, package exports, dependencies, persistence adapters, commands, or CI changes are implemented by this documentation package. + +ADR-0019 remains **Proposed** until separately authorized implementation and review. diff --git a/docs/milestones/milestone-15/FounderOS_Milestone_15_Verification_Checklist_v1.0.md b/docs/milestones/milestone-15/FounderOS_Milestone_15_Verification_Checklist_v1.0.md new file mode 100644 index 0000000..124e4c3 --- /dev/null +++ b/docs/milestones/milestone-15/FounderOS_Milestone_15_Verification_Checklist_v1.0.md @@ -0,0 +1,148 @@ +# FounderOS Milestone 15 Verification Checklist v1.0 + +## Status + +**Specified — not implemented** + +## Repository Preconditions + +- [ ] Milestone 14 is merged into `main`. +- [ ] `MILESTONE_14_RUNTIME_BASE_SHA` is exactly `a93faa29eecc37f2a08c79cda4c3075ffacfea3e`. +- [ ] A separate authorization supplies `AUTHORIZED_MILESTONE_15_DOCUMENTATION_MERGE_SHA`; it equals local `main` and `origin/main`, descends from the runtime predecessor with that predecessor as the documentation-delta merge base, and contains only the reviewed specification/governance delta. +- [ ] The future implementation branch is exactly `codex/milestone-15`, created from that authorized documentation merge SHA; `main`, the specification branch, and all other branches fail preflight. +- [ ] The worktree contains no unrelated changes. +- [ ] No unreviewed Milestone 15 runtime changes predate implementation authorization. +- [ ] ADR-0019 remains Proposed until implementation review accepts it. + +## Contract Verification + +- [ ] Every Milestone 15 contract is strict, versioned, and storage independent. +- [ ] Unknown fields and unsupported versions fail. +- [ ] Plain-own-data capture rejects accessors without invocation, symbols, hidden fields, inherited capabilities, custom prototypes, aliases, and executable values. +- [ ] Canonical JSON is finite, deterministic, acyclic, and byte stable. +- [ ] Domain-separated SHA-256 fingerprints independently recompute. +- [ ] Every fingerprint matches the exact named unsigned schema, fields, exclusions, domain tag, and order in the sole `M15-COMMIT-001` table; integrity and recovery results remain non-fingerprinted ephemeral outputs. +- [ ] Clean processes independently derive byte-identical genesis complete-history, head, marker, and fingerprint bytes without time, randomness, process, or filesystem input. +- [ ] Genesis, registration, and replay heads use the exact latest audit-entry, semantic-event, and subject-transaction ID/fingerprint fields and reject every missing, extra, aliased, or category-invalid key. +- [ ] Cross-record authority bindings are semantically verified, not accepted from coherent local re-signing. + +## Registration Verification + +- [ ] Readiness-ledger recovery and integrity precede mutation. +- [ ] Durable Delivery recovery and integrity precede evaluation. +- [ ] Exact Milestone 13 Delivery and Invocation authority resolves. +- [ ] The approved Milestone 14 evaluator produces and verifies the registration package. +- [ ] Caller package substitution, omission, addition, and reordering fail. +- [ ] Authorization precedes Credential Reference and Transport planning. +- [ ] Complete ownership, transaction, and audit evidence commits atomically. +- [ ] The registration request explicitly supplies ownership, registration semantic-event, registration audit-entry, and registration marker IDs and binds them into its fingerprint and exact-retry tuple. +- [ ] Registration stops before credential resolution and transport. + +## Idempotency and Concurrency Verification + +- [ ] First registration permanently owns its key, ownership ID, request ID, transaction ID, Decision ID, registration semantic-event ID, registration audit-entry ID, and registration marker ID. +- [ ] Identical retry returns the exact original transaction without append. +- [ ] Identical retry performs the governed resolver/evaluator/same-instance verification sequence exactly once and returns `idempotent-original-returned`. +- [ ] Conflicting reuse of any original-registration ownership coordinate fails with its stable coordinate-specific reason. +- [ ] Ownership survives process restart and derived-index loss. +- [ ] Stale expected head fails without mutation. +- [ ] Concurrent cooperative writers produce at most one valid commit. + +## Replay Verification + +- [ ] A fresh configured evaluator is used after restart. +- [ ] Stored and supplied configuration projections match exactly. +- [ ] Fresh upstream Delivery and Invocation authority verifies. +- [ ] Historical reconstruction always uses immutable `originalEvaluationTime`; current admissibility separately uses `replayEvaluatedAt` and never gates reconstruction. +- [ ] Complete package equality yields `matched`. +- [ ] Valid inequality yields `mismatched` with bounded field-path evidence. +- [ ] Invalid authority or evaluation yields `verification-failed` when append is safe. +- [ ] Historical `matched` plus current `authorization-expired` records successfully and Authorization is never refreshed. +- [ ] Current denial, review-required, not-evaluated, invalid-evidence, and authority-mismatch statuses record independently when append is safe. +- [ ] Public results distinguish historical, current-admissibility, append, and `recorded`/`not-recorded` status; every not-recorded result has exactly one stable operation reason and no attempt. +- [ ] Replay append status exists only in the ephemeral operation result, never in the pre-commit replay-attempt fingerprint domain. +- [ ] Exact replay retry binds all five replay IDs, verifies permanent history, tolerates later head advancement only through its stored expected-head exception, and returns `idempotent-replay-returned` without append. +- [ ] Replay idempotency-key ownership is global and permanent; changed bytes under the same key return `replay-idempotency-key-conflict`. +- [ ] Original transaction bytes remain unchanged after every replay attempt. +- [ ] Replay attempts order by ledger sequence and remain append-only. + +## Integrity and Recovery Verification + +- [ ] Genesis complete-history, zero-event head, deterministic marker, immutable archive, and fixed current-marker copy independently verify. +- [ ] Safe open/create distinguishes uninitialized, initialized-empty, incomplete-genesis, corrupt-genesis, and non-empty initialized roots without treating partial state as authority. +- [ ] Genesis crashes before staging, during staging, after archive creation, and after fixed-marker installation yield only the specified complete or non-authoritative states. +- [ ] The first registration advances exactly from the verified genesis head to generation and sequence `1`. +- [ ] Marker-embedded head, public `readHead()`, and rebuilt derived `HEAD` bytes are identical for genesis, registration, and replay. +- [ ] Event, audit, and marker sequence/count/head coordinates agree. +- [ ] Missing, reordered, duplicated, corrupt, partial, or contradictory authoritative evidence fails. +- [ ] Altered gate order, retention evidence, configuration, Delivery, Invocation, or Adapter authority fails. +- [ ] Pre-marker crash state leaves the prior committed prefix. +- [ ] Marker-referenced incomplete state fails closed. +- [ ] Ambiguous installed state fails closed. +- [ ] Authoritative records are never silently repaired or truncated. +- [ ] Recovery results and public errors are deterministic and path redacted. +- [ ] Global original and replay identity ownership survives restart and detects every cross-key/cross-request conflict. + +## Derived Index Verification + +- [ ] Indexes bind the exact authoritative head. +- [ ] Reads verify or bypass indexes rather than trust them. +- [ ] Missing and corrupt indexes are reported separately. +- [ ] Explicit rebuild produces deterministic bytes and exact lookups. +- [ ] Index rebuild never changes authoritative history. + +## Filesystem Safety Verification + +- [ ] Runtime root is explicit, bounded, Git-ignored, and outside canonical sources. +- [ ] Lexical traversal, physical escape, symlinks, aliases, special files, and unsafe nested entries fail. +- [ ] Runtime/source overlap fails in both directions. +- [ ] Directory identity is rechecked around critical operations. +- [ ] Immutable authoritative records are never overwritten. +- [ ] Public failures expose no physical paths. +- [ ] Resource limits fail before mutation. +- [ ] Abandoned lock behavior and operator cleanup are documented and tested. +- [ ] Every row of `M15-FS-001` is fault-injected for registration and replay as applicable and recovers only the old or new complete marker-bounded head. +- [ ] A stale lock is never stolen automatically; read-only integrity remains non-mutating, and cleanup removes only the lock after no active writer is proven. +- [ ] Marker commit followed by missing derived `HEAD` or index remains committed and rebuilds deterministically. +- [ ] Every activated event retains an immutable archived marker byte-identical to the marker value installed at the fixed current-marker location; only fixed-marker replacement activates visibility. + +## Privacy and No-Execution Verification + +- [ ] Stored-data traversal finds no raw Knowledge, Query Results, Context content, credential values, secret bytes, environment contents, headers, URLs, provider bodies, clients, callbacks, functions, or executable payloads. +- [ ] Credential References contain logical IDs and fingerprints only. +- [ ] No live-ready or equivalent status validates. +- [ ] A durable transaction cannot satisfy a provider-execution authorization boundary by itself. +- [ ] Production import closure contains no HTTP, DNS, TLS, socket, proxy, provider SDK, environment-secret, credential resolver, Agent, Hermes, MCP, streaming, or tools/functions path. +- [ ] No outbound network or credential access occurs in tests or runtime probes. +- [ ] The sole Evidence Durability Inventory is exhaustive: only its authoritative and derived members may persist. +- [ ] No authoritative record, staging-to-install envelope, derived record, log, trace, metric, or observability artifact contains an application/adapter operation-result envelope, transient status value, or validation report. +- [ ] Every public application/adapter operation-result envelope and transient status value is strict canonical redacted ephemeral output; validation reports are redacted ephemeral outputs; none is fingerprinted or persisted except through an explicitly and separately reviewed outside-ledger validation-report specification. + +## Regression Verification + +- [ ] All Milestone 04–14 tests remain green with no predecessor-test loss: at least 42 test files and 1,038 tests execute and pass before any Milestone 15 test is counted. +- [ ] New Milestone 15 unit, integration, restart, corruption, concurrency, path-safety, privacy, and no-execution tests pass. +- [ ] Existing package boundaries and public facades remain compatible. + +## Traceability Verification + +- [ ] Every normative `M15-*` requirement has one `M15-AC-*` acceptance criterion and at least one `M15-SC-*` executable scenario. +- [ ] Every scenario references only existing requirements. +- [ ] Requirement, acceptance, and scenario IDs are unique. +- [ ] Deterministic documentation/fixture lint parses every normative clause and source file/section using the acceptance-criteria ownership grammar and fails on any unmapped clause/file, missing target, non-contiguous catalog, or duplicate ID. +- [ ] All scenarios `M15-SC-001` through `M15-SC-072` execute, and the separately counted Milestone 04–14 predecessor suite preserves at least 42 files and 1,038 passing tests. + +## Required Commands + +```bash +pnpm format:check +pnpm lint +pnpm build +pnpm typecheck +pnpm test +git diff --check +``` + +## Approval Rule + +Milestone 15 is `GO` only when one exact verified readiness evaluation and all later replay attempts survive restart, independently verify, fail closed under conflict or tampering, preserve privacy and path safety, and expose no credential or provider-transport capability. diff --git a/docs/milestones/milestone-15/FounderOS_Readiness_Evaluation_Registration_and_Idempotency_Contract_v1.0.md b/docs/milestones/milestone-15/FounderOS_Readiness_Evaluation_Registration_and_Idempotency_Contract_v1.0.md new file mode 100644 index 0000000..39667f0 --- /dev/null +++ b/docs/milestones/milestone-15/FounderOS_Readiness_Evaluation_Registration_and_Idempotency_Contract_v1.0.md @@ -0,0 +1,151 @@ +# FounderOS Readiness Evaluation Registration and Idempotency Contract v1.0 + +## Status + +**Specified — not implemented** + +## Purpose + +Define the governed registration workflow and permanent ownership rules for durable production-provider readiness evaluations. + +## Registration Preconditions + +Before any mutation, the application boundary must: + +1. Capture the complete request as exact plain own data without invoking accessors. +2. Reject hidden fields, symbols, custom prototypes, executable values, credentials, endpoints, and low-level ledger capabilities. +3. Recover the readiness ledger and verify authoritative integrity. +4. Resolve existing ownership coordinates from authoritative history, but do not return through a lookup-only shortcut. +5. Recover and verify the supplied Milestone 12 Delivery Ledger. +6. Resolve the exact current Milestone 13 Delivery and Invocation authority. +7. Reconstruct and verify the evaluator configuration projection. +8. Evaluate the canonical Milestone 14 input with the approved configured evaluator exactly once. +9. Verify the Decision with that same evaluator and its exact retention evidence. +10. Reconstruct the canonical registration request and evaluation package and require exact equality with any permanent ownership and original transaction already found. +11. Require byte-equivalent canonical package equality when the caller supplies an expected package. +12. Verify the expected readiness-ledger head for a first claim; for an exact owned retry, verify the original expected-head coordinate embedded in the owned request without requiring it to equal the later current head. + +No idempotency ownership or filesystem mutation may occur before these checks pass. + +## Registration Request Identity + +The canonical registration request fingerprint binds: + +- request contract version and request ID; +- proposed transaction ID; +- idempotency key; +- caller-requested ownership ID; +- caller-requested registration semantic-event ID; +- caller-requested registration audit-entry ID; +- caller-requested registration marker ID; +- complete Delivery and Invocation identity projection; +- evaluator configuration projection; +- canonical readiness-input fingerprint; +- immutable `originalEvaluationTime`; +- optional complete expected evaluation package and its fingerprint, when supplied; +- submitted-at evidence; +- expected ledger-head fingerprint. + +## Idempotency Ownership Record + +The durable ownership record contains (`M15-IDEM-001`): + +- ownership contract version; +- globally unique ownership ID; +- idempotency key; +- registration request ID and fingerprint; +- transaction ID; +- Readiness Decision ID and fingerprint; +- registration semantic-event ID; +- registration audit-entry ID; +- registration marker ID; +- canonical evaluation-package fingerprint; +- Delivery transaction ID and fingerprint; +- Invocation Request ID and fingerprint; +- Adapter ID and fingerprint; +- evaluator configuration projection fingerprint; +- durable authority projection fingerprint; +- ownership ledger sequence; +- ownership creation timestamp; +- canonical ownership fingerprint. + +The ownership fingerprint covers only this semantic ownership payload. The enclosing registration event binds ownership and transaction fingerprints to the audit sequence and heads, avoiding circular fingerprints. + +The request is the sole source of `ownershipId`, registration `semanticEventId`, registration `auditEntryId`, and registration `markerId`. Every corresponding record must equal its `requested*Id` field byte-for-byte. These identities are never random, clock-derived, sequence-derived, process-derived, filesystem-derived, or index-derived. + +## Ownership Rules + +- The first valid registration atomically and permanently owns an unused idempotency key, caller-requested ownership ID, registration request ID, requested transaction ID, Readiness Decision ID, caller-requested registration semantic-event ID, caller-requested registration audit-entry ID, and caller-requested registration marker ID (`M15-IDEM-001`). +- Identical registration retry is not a lookup-only shortcut. It performs readiness-ledger verification, current governed authority resolution, approved evaluation, same-instance Decision verification, and canonical request/package reconstruction exactly once before returning the exact original committed transaction. +- Identical replay does not append a duplicate transaction or refresh ownership ordering. +- Exact replay compares the original canonical request bytes, including the original submitted-at and expected-head evidence; an already-owned exact request returns the original even if later replay events advanced the current ledger head. +- Exact return requires byte-identical canonical request bytes and the same key; ownership, request, transaction, registration semantic-event, registration audit-entry, and registration marker IDs; request and Decision fingerprints; authority projection; evaluator configuration projection; and complete evaluation package. +- The same Decision ID under a different key or request ID is a conflict even when bytes are otherwise identical. +- The same transaction ID under a different key or request is a conflict. +- The same request ID under a different key is a conflict. +- The same key with a different request fingerprint is a conflict. +- Reuse of an ownership, registration semantic-event, registration audit-entry, or registration marker ID under a different key, request, or requested-ID tuple is a coordinate-specific conflict even when all other bytes match. +- No second original transaction may exist for one Readiness Decision ID. +- A partial ownership record without its marker-bounded transaction is authoritative corruption. +- A transaction without its required ownership is authoritative corruption. +- Expiration of Authorization or readiness evidence never frees an idempotency key. +- Derived lookup eviction or deletion never frees authoritative ownership. + +## Canonical Package Rule + +The configured evaluator is the only source of registration-time package authority. A caller may supply an expected package solely for equality checking. Missing, extra, reordered, or substituted package members fail before ownership. + +## Atomic Claim and Commit + +Ownership and the complete registration transaction commit as one marker-bounded event. There must be no committed state in which only one exists. + +The operation must use: + +1. a cooperative writer lock; +2. expected-head compare-and-swap; +3. revalidation of existing IDs and ownership under the lock; +4. one complete staged event envelope; +5. canonical serialization and fingerprinting; +6. atomic installation and synchronization; +7. atomic fixed current-marker replacement as the commit point. + +## Registration Outcomes + +The application result is one of: + +- `committed` with the immutable original transaction; +- `idempotent-original-returned` with the exact previously committed transaction after the mandated resolver and evaluator checks; +- `rejected` with stable, redacted reason codes; +- `integrity-failed` with stable, redacted failure evidence. + +The complete application-result envelope is ephemeral, non-authoritative, non-fingerprinted, and non-persisted under the sole Evidence Durability Inventory in the privacy policy. A `committed` or `idempotent-original-returned` result may return the one authoritative transaction already governed by its marker, but the result envelope never creates or permits a second durable copy. Rejected and integrity-failed results commit no registration record. + +## Required Conflict Detection + +Fail closed on: + +- `idempotency-key-conflict`; +- `ownership-id-conflict`; +- `registration-request-id-conflict`; +- `transaction-id-conflict`; +- `decision-id-conflict`; +- `registration-semantic-event-id-conflict`; +- `registration-audit-entry-id-conflict`; +- `registration-marker-id-conflict`; +- stale expected head; +- concurrent writer state change; +- mismatched Delivery or Invocation identity; +- evaluator configuration mismatch; +- stale or forged fingerprint; +- coherent re-signing under substituted authority; +- altered gate order or retention evidence; +- missing transaction component; +- prohibited material or unsafe input shape. + +## Ordering + +Ledger sequence, not timestamp, defines ownership order. Timestamps must be explicit canonical UTC evidence and may not be used as implicit clocks. + +## Principle + +Idempotency is permanent durable governance evidence. It is neither a process-local cache nor a renewable execution lease. diff --git a/docs/milestones/milestone-15/FounderOS_Readiness_Evidence_Privacy_and_No_Execution_Policy_v1.0.md b/docs/milestones/milestone-15/FounderOS_Readiness_Evidence_Privacy_and_No_Execution_Policy_v1.0.md new file mode 100644 index 0000000..1637c61 --- /dev/null +++ b/docs/milestones/milestone-15/FounderOS_Readiness_Evidence_Privacy_and_No_Execution_Policy_v1.0.md @@ -0,0 +1,121 @@ +# FounderOS Readiness Evidence Privacy and No-Execution Policy v1.0 + +## Status + +**Specified — not implemented** + +## Purpose + +Prevent the Milestone 15 durable ledger, registration facade, replay verifier, adapter, logs, errors, and indexes from becoming a credential, context, provider-payload, or execution bypass. + +## Evidence Durability Inventory + +This section is the sole exhaustive Milestone 15 durability classification. A schema, contract, facade, adapter, test fixture, report, or implementation may not introduce another durable evidence class or persist an item classified here as ephemeral. + +| Evidence class | Exact members | Authority rule | +| --- | --- | --- | +| Authoritative durable | Marker-committed registration requests and permanent ownership records; evaluator-configuration and Delivery/Invocation authority projections; canonical evaluation packages; committed original transactions; recorded replay requests, historical comparisons, current-admissibility evidence, and replay attempts; semantic events; audit entries; genesis and event complete-history commitments; genesis and event ledger-head projections embedded in markers; immutable activated marker archives; and the byte-identical installed fixed current marker | Immutable marker-bounded ledger authority governed by `M15-COMMIT-001`; no other durable record is authoritative | +| Derived durable | Rebuildable `HEAD` projections, derived index entries, and derived index snapshots | Non-authoritative; may be discarded and rebuilt only from verified marker-bounded history | +| Ephemeral and non-persisted | Every public application/adapter operation-result envelope and transient result metadata, including registration, replay, append status, integrity, recovery, derived-state verification/rebuild, initialization/open, and failed-mutation results; validation reports, including documentation lint, traceability, verification, test, completion, and review reports, unless a separately reviewed specification outside readiness-ledger authority explicitly defines a durable report | Must not be fingerprinted or written to authoritative records, installable staging envelopes, marker archives, the fixed current marker, derived state, logs, traces, metrics, or observability artifacts; an authoritative or derived record returned inside an ephemeral envelope retains its inventory class, but the envelope creates no second durable copy | + +Authoritative durable records may contain only strict non-secret governance evidence such as: + +- contract versions; +- logical IDs and lowercase SHA-256 fingerprints; +- bounded provider family references; +- exact Milestone 14 Decision status and stable reason codes; +- ordered gate-trace evidence; +- retained redacted observability evidence; +- evaluator configuration projection; +- Delivery and Invocation identity projection; +- explicit timestamps, sequences, latest audit-entry fingerprints, ledger-head fingerprints, and marker coordinates; +- deterministic durable historical-comparison and current-admissibility evidence. + +Every ephemeral member in the inventory is a non-authoritative public or validation output. It has no fingerprint field or readiness-ledger commitment domain and is discarded after return or validation unless the table's explicit separately reviewed, outside-ledger exception applies. + +## Prohibited Material + +Every public boundary and durable representation must reject or exclude: + +- raw Knowledge Objects; +- full Query Results; +- hidden Context or Context Package content; +- Delivery Ledger objects, ports, or filesystem handles; +- credential values, secret bytes, tokens, keys, passwords, certificates, or cookies; +- environment-variable contents or environment dumps; +- authorization headers or signed provider requests; +- arbitrary URLs, endpoints, host overrides, query strings, or URL credentials; +- provider request or response bodies; +- provider-native payloads or executable response objects; +- network clients, sockets, callbacks, functions, promises, streams, or SDK instances; +- raw logs, traces, metrics, or errors containing prohibited values; +- physical filesystem paths in public results; +- caller-supplied record writers, index writers, commit markers, locks, or ledger-head mutations; +- Agents, Hermes, MCP, or tool/function-calling payloads. + +## Input Safety + +Before reading nested values or consulting authority, public inputs must be captured as exact plain, acyclic, enumerable own data properties. Reject: + +- accessors without invoking them; +- symbols; +- non-enumerable fields; +- inherited properties; +- custom prototypes; +- unsupported built-ins; +- aliases that could mutate captured state; +- functions and executable values; +- unknown fields and unsupported versions. + +Captured values are deeply immutable or defensively copied before asynchronous work or lock acquisition. + +## Credential Reference Rule + +Only the exact Milestone 14 logical Credential Reference ID and fingerprint may be persisted. Milestone 15 has no resolver interface, secret lease, environment read, secret-store client, authorization-header builder, or credential cache. + +Values that resemble credential material fail closed even if placed in an otherwise unknown or optional field. + +## No-Execution Rule + +- Registration invokes only the existing non-executing Milestone 14 evaluator. +- Replay invokes only a fresh non-executing Milestone 14 evaluator. +- No status beyond Milestone 14's dry-run and fail-closed statuses is valid. +- A committed transaction is audit evidence, not a capability or authorization token. +- No public API accepts a transport hook, provider client, endpoint, callback, or enabled Adapter. +- No durable record may be supplied directly to a future transport layer as sufficient execution authority. +- A future execution milestone must independently re-establish current authorization, credential, transport, and Invocation authority. + +## Authorization Expiration + +Persistence freezes evidence; it does not freeze validity (`M15-REPLAY-001`). Historical reconstruction always evaluates the immutable original input at `originalEvaluationTime`, even when current Authorization is expired. Separately, current admissibility evaluates the original Authorization evidence at `replayEvaluatedAt`. Expiration produces `currentAdmissibilityStatus = authorization-expired`; it does not prevent or invalidate a historical `matched` result. Replay cannot extend, refresh, replace, or renew Authorization, and neither assessment grants execution authority. + +## Redaction and Errors + +- Redaction occurs before any retained diagnostic evidence. +- Public errors use stable reason codes and logical identifiers. +- Comparison evidence reports bounded canonical field paths, not raw values. +- Physical paths, stack-derived secrets, environment values, provider bodies, and headers are excluded. +- Metrics and indexes use bounded low-cardinality logical identifiers. + +## Production Import Closure + +Future implementation verification must prove that Milestone 15 production modules contain no dependency or dynamic path for: + +- HTTP, HTTPS, DNS, TLS, sockets, proxies, or provider SDKs; +- environment-variable secret reads; +- credential or secret resolution; +- random or implicit-clock authority; +- executable provider payloads; +- Agents, Hermes, MCP, or tools/functions. + +Standard filesystem and cryptographic hashing APIs are allowed only inside the local persistence adapter and canonical fingerprint implementation. + +## Stored-Data Inspection + +Acceptance tests must inspect every authoritative record, staging envelope used by fixtures, public result, error, derived index, and observability artifact for prohibited keys and representative secret-like sentinels. + +Stored-data inspection must also prove that no authoritative record, installable staging envelope, derived record, log, trace, metric, or observability artifact contains any public operation-result envelope, transient append/status metadata, integrity-result object, recovery-result object, derived-state operation result, or validation report. Public operation, integrity, recovery, and derived-state results remain strict canonical, redacted, non-fingerprinted return values and are discarded after return; logging their whole object would create a prohibited second durable registry. + +## Principle + +Durability must increase auditability without increasing execution authority or the amount of sensitive material FounderOS can access. diff --git a/docs/milestones/milestone-15/FounderOS_Readiness_Ledger_Integrity_and_Recovery_Specification_v1.0.md b/docs/milestones/milestone-15/FounderOS_Readiness_Ledger_Integrity_and_Recovery_Specification_v1.0.md new file mode 100644 index 0000000..d1e47fc --- /dev/null +++ b/docs/milestones/milestone-15/FounderOS_Readiness_Ledger_Integrity_and_Recovery_Specification_v1.0.md @@ -0,0 +1,177 @@ +# FounderOS Readiness Ledger Integrity and Recovery Specification v1.0 + +## Status + +**Specified — not implemented** + +## Purpose + +Define deterministic restart recovery and fail-closed integrity verification for durable readiness evaluation registrations and replay attempts. + +## Recovery Sequence + +```text +Open configured ledger root safely + | + v +Validate root identity and entry safety + | + v +Read and verify commit-head marker + | + v +Load exact marker-bounded event prefix + | + v +Verify schemas, canonical bytes, and fingerprints + | + v +Replay sequences, audit chain, ownership, and bindings + | + v +Classify staging and installed crash orphans + | + v +Compare derived indexes with authoritative replay + | + v +Return deterministic recovery evidence +``` + +## Integrity Coverage + +Verification must cover: + +- canonical JSON and record fingerprints; +- canonical genesis complete-history, genesis-head, and genesis-marker bytes and fingerprints; +- registration-request and transaction fingerprints; +- permanent idempotency ownership; +- Decision ID uniqueness and authority bindings; +- exact stored Decision, ordered gate trace, retained Evidence package, and retention fingerprint; +- exact evaluator configuration projection; +- exact Delivery and Invocation identity projection; +- registration and replay sequence continuity; +- previous-head and resulting-head bindings; +- complete audit-chain continuity; +- replay reference and comparison bindings; +- global uniqueness and permanent ownership for every original-registration and replay identity defined by `M15-IDEM-001` and `M15-IDEM-002`; +- the exact genesis and event commit-marker field sets from `M15-COMMIT-001`, including counts, last sequence, subject, semantic-event, and audit-entry coordinates, resulting ledger head, and complete-history fingerprint; +- byte equality among the marker-embedded head, `readHead()`, and any rebuilt derived `HEAD` projection; +- byte equality and fingerprint equality between the installed fixed current marker and its immutable event-local archive, plus permanent uniqueness of every archived marker ID; +- authoritative record completeness; +- privacy and no-execution invariants; +- derived index equality with authoritative replay. + +## Recovery Result + +The deterministic recovery result contains: + +- result contract version; +- status: `recovered`, `empty`, or `failed`; +- committed registration count; +- committed replay-attempt count; +- permanent idempotency ownership count; +- last committed sequence; +- recovered latest audit-entry ID and fingerprint, both null for initialized empty; +- recovered latest semantic-event ID and fingerprint, both null for initialized empty; +- recovered latest subject transaction ID and fingerprint, both null for initialized empty; +- recovered complete-history fingerprint; +- authoritative marker fingerprint; +- derived-index status; +- staging-orphan count; +- installed-uncommitted-orphan count; +- stable ordered errors; + +Recovery results are strict canonical ephemeral verification outputs and are deliberately not fingerprinted. They are not ledger authority and therefore have no unsigned commitment domain or fingerprint field (`M15-INTEGRITY-001`). + +An uninitialized root returns `status = failed` with sole stable error `ledger-uninitialized`; incomplete genesis initialization returns `genesis-initialization-incomplete`; corrupt genesis returns `genesis-corrupt`. None is reported as `empty`, and none causes mutation during `recover()` or `verifyIntegrity()`. + +Public errors contain logical record coordinates, never physical paths or secret values. + +## Integrity Result + +The integrity result contains: + +- result contract version; +- status: `valid` or `invalid`; +- verified marker fingerprint; +- verified registration, replay, and total event counts; +- verified last sequence and latest audit-entry fingerprint; +- verified complete-history fingerprint; +- derived-index status reported separately; +- stable ordered findings; + +Integrity results are strict canonical ephemeral verification outputs and are deliberately not fingerprinted. They are not ledger authority and therefore have no unsigned commitment domain or fingerprint field (`M15-INTEGRITY-001`). + +Derived-index corruption alone does not make valid authoritative history invalid, but it prevents use of the index until explicit rebuild succeeds. + +## Fail-Closed Conditions + +Recovery fails on: + +- missing, malformed, unsupported, or fingerprint-invalid marker; +- missing marker-referenced event; +- extra installed event that conflicts with the committed prefix; +- incomplete registration transaction or replay attempt; +- invalid canonical bytes or fingerprint; +- broken, duplicated, or reordered sequence; +- broken audit-chain link; +- conflicting idempotency ownership; +- duplicate or conflicting globally owned registration idempotency key, ownership ID, registration request ID, transaction ID, readiness Decision ID, registration semantic-event ID, registration audit-entry ID, registration marker ID, replay idempotency key, replay request ID, replay attempt ID, replay semantic event ID, replay audit entry ID, or replay marker ID; +- mismatched Delivery, Invocation, Adapter, capability, Credential Reference, Transport Policy, evaluator configuration, gate trace, or retention binding; +- replay referencing a missing original transaction; +- prohibited secret, endpoint, path, client, callback, or executable material; +- symlink, traversal, special-file, or unsafe-entry discovery; +- ambiguous crash state. + +Authoritative corruption is never silently skipped, truncated, normalized, repaired, or overwritten. + +## Crash-State Classification + +- Temporary files wholly within staging and absent from the marker are uncommitted staging orphans. +- Fully installed events beyond the marker are uncommitted installed orphans. +- Neither category is replayed as authority. +- A later write may quarantine safely classified orphans only after successful recovery, expected-head verification, and lock acquisition. +- If an orphan conflicts with a marker-bounded identity or cannot be classified unambiguously, recovery fails. +- A marker that references a missing or incomplete event is corruption, not a pre-commit crash. +- A verified atomically installed fixed current-marker copy is the sole authoritative visibility boundary. Its byte-identical immutable event-local archive preserves the activated marker as history but never creates visibility by itself. A separately stored `HEAD` projection and every index are derived; their absence after marker commitment never rolls back the commit (`M15-TXN-001`, `M15-TXN-002`). +- Recovery classification for every interruption and lock state is governed by the single fault-point matrix `M15-FS-001` in the Local File Readiness Ledger Adapter Specification. + +## Derived Index Recovery + +Indexes are verified only after authoritative replay. Missing or corrupt indexes are reported as `missing` or `invalid`; they are not repaired implicitly during read, recovery, or integrity verification. + +Explicit rebuild must: + +1. start from valid authoritative history; +2. create deterministic index bytes; +3. bind the exact ledger-head fingerprint; +4. publish atomically through the adapter; +5. verify the installed index before reporting success. + +## Coherent Re-Signing and Substitution + +Recomputed local fingerprints do not establish semantic authority. Recovery must compare all cross-record identity and configuration bindings. A coherently re-signed transaction with a substituted Delivery, Invocation, Adapter, capability, Credential Reference, Transport Policy, gate order, or retention package fails because it no longer matches the marker-bounded ownership and upstream authority projections. + +## Empty Ledger + +The sole authoritative empty-ledger model is the explicit genesis commitment in `M15-COMMIT-001` and `M15-GENESIS-001`: + +- canonical genesis complete history uses the exact constant input and domain tag; +- the zero-event genesis head uses generation, counts, and sequence `0`, all six latest-coordinate fields `null`, and the genesis complete-history fingerprint; +- the deterministic genesis marker uses ID `m15-genesis`, generation `0`, category `genesis`, null event coordinates, and the exact embedded genesis head; +- the immutable genesis archive and fixed current-marker copy are byte-identical; +- atomic fixed-marker installation is the genesis visibility boundary. + +Safe open/create distinguishes four states: + +1. `uninitialized`: no FounderOS-created genesis or event component exists; read-only open reports uninitialized and create may initialize under the writer lock. +2. `initialized-empty`: both genesis marker copies exist, are byte-identical, independently recompute, and reference the exact canonical genesis head and history; recovery returns `empty`. +3. `incomplete-genesis-initialization`: staging or a canonical archived genesis candidate exists without a fixed marker; it is not authority. Read-only open reports failure, while a later locked create may complete only from independently verified exact canonical genesis material after classifying every orphan. +4. `corrupt-genesis`: any missing counterpart after fixed-marker visibility, extra component, byte mismatch, invalid schema/fingerprint, noncanonical constant, event data at generation `0`, or event marker using the reserved genesis ID; recovery fails closed and performs no automatic repair. + +Crash before staging preserves `uninitialized`. Crash during staging yields incomplete initialization with staging orphans only. Crash after archived genesis installation but before fixed-marker installation yields incomplete initialization with no empty-ledger authority. Crash after fixed-marker installation yields `initialized-empty` only when both copies and every genesis commitment verify. The first registration must bind the verified genesis `ledgerHeadFingerprint` as its previous and expected head and advance to generation and sequence `1`. + +## Principle + +Restart safety exists only when the exact committed prefix can be independently reconstructed without trusting process memory or derived indexes. diff --git a/docs/milestones/milestone-15/FounderOS_Readiness_Replay_Verification_Registry_Contract_v1.0.md b/docs/milestones/milestone-15/FounderOS_Readiness_Replay_Verification_Registry_Contract_v1.0.md new file mode 100644 index 0000000..66b72af --- /dev/null +++ b/docs/milestones/milestone-15/FounderOS_Readiness_Replay_Verification_Registry_Contract_v1.0.md @@ -0,0 +1,180 @@ +# FounderOS Readiness Replay Verification Registry Contract v1.0 + +## Status + +**Specified — not implemented** + +## Purpose + +Define durable, append-only evidence that a fresh approved evaluator did or did not reconstruct an original Milestone 14 readiness evaluation after restart. + +## Replay Authority + +Replay is a verification operation, not a renewal or execution operation. The immutable original transaction remains the sole recorded registration artifact. A replay attempt never modifies it and never grants provider-execution authority. + +## Replay Request + +The replay request contains: + +- replay request contract version; +- globally unique replay request ID; +- replay idempotency key; +- requested globally unique replay attempt ID; +- requested globally unique replay semantic-event ID; +- requested globally unique replay audit-entry ID; +- requested globally unique replay marker ID; +- original transaction ID and expected fingerprint; +- fresh evaluator configuration projection; +- exact authoritative readiness-input fingerprint and supplied input; +- exact governed Delivery Ledger interface for verification, never persistence; +- immutable original-transaction `originalEvaluationTime` binding; +- explicit current `replayEvaluatedAt`; +- expected ledger-head fingerprint; +- replay request fingerprint. + +## Replay Workflow + +1. Capture the request and reject unsafe or prohibited capabilities. +2. Recover and verify the readiness ledger, replay identity ownership, and marker archive/current-marker consistency. +3. If every caller-owned replay identity coordinate and the complete canonical request fingerprint exactly match one committed replay submission, verify the original attempt and its activating marker and return `idempotent-replay-returned` without reconstruction, append, ownership refresh, or head advancement. The request's original expected-head coordinate must match the owned request but need not equal the later current head. +4. Otherwise, reject any owned-coordinate reuse and read and independently verify the original transaction. +5. Capture the newly supplied Delivery Ledger and fresh approved evaluator configuration. +6. Always attempt historical reconstruction at immutable `originalEvaluationTime`: recover and verify supplied Delivery authority, resolve exact Milestone 13 authority, require the stored configuration projection, evaluate the exact original canonical input, and verify the new Decision and retention evidence through that fresh evaluator instance. +7. Compare the complete reconstructed package with the immutable original when reconstruction verifies. +8. Independently assess the original Authorization evidence at `replayEvaluatedAt`; never alter or replace its `decidedAt`, `expiresAt`, or authority. +9. Construct one replay attempt containing both assessments. +10. Append the attempt and audit evidence only when the readiness ledger and append preconditions remain safe. +11. Return `recorded` only after the replay marker commits; otherwise return `not-recorded` with no replay attempt. +12. Stop before credential resolution or transport. + +## Replay Attempt Record + +Each record contains: + +- replay contract version; +- replay idempotency key, replay request ID/fingerprint, and replay attempt ID; +- original transaction ID and fingerprint; +- original Decision ID and fingerprint; +- stored and supplied evaluator configuration projection fingerprints; +- stored and supplied Delivery/Invocation projection fingerprints; +- authoritative readiness-input fingerprint; +- `originalEvaluationTime` and `replayEvaluatedAt`; +- fresh evaluation-package fingerprint when one verifies; +- historical comparison evidence and fingerprint; +- current admissibility evidence and fingerprint; +- historical reconstruction status; +- current admissibility status; +- stable ordered reason codes; +- canonical replay-attempt fingerprint. + +The replay-attempt fingerprint covers semantic attempt evidence only and excludes all later audit, history, head, marker, and index fields. Its exact domain and computation order are defined by the sole normative commitment-domain table in `FounderOS_Durable_Readiness_Evaluation_Transaction_Contract_v1.0.md` (`M15-COMMIT-001`). + +## Historical Reconstruction Status (`M15-REPLAY-002`) + +### `matched` + +The fresh evaluator issues and verifies a complete canonical package at `originalEvaluationTime`, and its canonical bytes exactly equal the stored original. + +### `mismatched` + +Both original and fresh packages verify independently, but their canonical bytes differ. Comparison evidence identifies stable differing field paths without exposing secret or raw context values. + +### `verification-failed` + +Historical reconstruction cannot produce a fully verified package because supplied governed authority, configuration, evaluation, Decision verification, or retention evidence fails. Current Authorization expiration alone is not a historical reconstruction failure. + +### `not-assessed` + +The operation cannot safely reach historical reconstruction, for example because replay input is invalid, the readiness ledger is corrupt, or the original transaction is absent. This status is returned only in a `not-recorded` operation result and is not appended. + +## Current Admissibility Status (`M15-REPLAY-002`) + +The strict statuses are: + +- `admissible`; +- `authorization-expired`; +- `authorization-denied`; +- `authorization-review-required`; +- `authorization-not-evaluated`; +- `authorization-invalid-evidence`; +- `authority-mismatch`; +- `not-assessed`. + +Current admissibility uses only the original Authorization evidence at `replayEvaluatedAt`. It does not affect whether historical reconstruction is attempted. In particular, `historicalReconstructionStatus = matched` with `currentAdmissibilityStatus = authorization-expired` is a valid recordable result. + +## Replay Append and Operation Results (`M15-REPLAY-002`) + +Replay append status is exactly `appended` or `not-appended` and exists only in the ephemeral public operation result; it is not a field of `ReadinessReplayAttemptUnsignedV1` and cannot be circularly predicted before marker commit. The public submission result is: + +- `recorded`: contains the immutable marker-committed replay attempt and `replayAppendStatus = appended`; +- `not-recorded`: contains no replay attempt, has `replayAppendStatus = not-appended`, and contains exactly one stable operation reason. +- `idempotent-replay-returned`: contains the exact previously committed replay attempt, has `replayAppendStatus = not-appended`, performs no authoritative mutation, and is available only through the exact-retry rule in `M15-REPLAY-003`. + +The complete submission-result envelope and append status are ephemeral, non-authoritative, non-fingerprinted, and non-persisted under the sole Evidence Durability Inventory in the privacy policy. A `recorded` or `idempotent-replay-returned` result may return the one authoritative attempt already governed by its marker, but the result envelope never creates or permits a second durable copy. + +Stable `not-recorded` reasons include: + +- `invalid-replay-input`; +- `readiness-ledger-integrity-failure`; +- `original-transaction-not-found`; +- `stale-expected-head`; +- `concurrent-writer-conflict`; +- `lock-unavailable`; +- `operator-cleanup-required`; +- `append-conflict`; +- `replay-identity-conflict`; +- `replay-idempotency-key-conflict`; +- `replay-request-id-conflict`; +- `replay-attempt-id-conflict`; +- `replay-semantic-event-id-conflict`; +- `replay-audit-entry-id-conflict`; +- `replay-marker-id-conflict`; +- `append-failure`; +- `unsafe-filesystem-state`. + +When the readiness ledger, original transaction, canonical request, and append preconditions verify, evaluator configuration mismatch, Delivery or Invocation authority mismatch, package mismatch, and all current Authorization denial states are recordable replay evidence. An append failure never reports `appended` or `recorded`. + +A readiness-ledger integrity failure prevents appending a replay attempt because the ledger cannot safely commit new evidence. + +## Authorization Time Rules + +- Historical reconstruction always uses immutable `originalEvaluationTime`, exactly equal to the original Milestone 14 `evaluatedAt`. +- Current admissibility uses explicit `replayEvaluatedAt`. +- Stored `originalEvaluationTime`, Authorization `decidedAt`, authority, and expiration evidence remain immutable. +- Replay never refreshes, extends, or substitutes Authorization validity. +- Expired Authorization produces current status `authorization-expired` and never blocks historical reconstruction. +- Replay time is attempt evidence only and is never substituted into the historical package. +- A later valid external Authorization decision would be a different canonical readiness input and cannot rewrite the original transaction. + +## Comparison Rules + +Comparison covers the complete canonical evaluation package, including: + +- Decision and ordered reason codes; +- exact ordered gate trace; +- complete retained non-secret evidence; +- observability retention fingerprint; +- Delivery and Invocation identity projection; +- evaluator configuration projection; +- all nested fingerprints. + +Missing members, reordered gates, altered retention evidence, coherent re-signing under substituted authority, or different canonical bytes cannot be treated as a match. + +## Registry Rules + +- Replay attempts are immutable and append-only. +- Unsafe, credential-bearing, accessor-backed, or otherwise prohibited public input is rejected before evaluation or append and does not become replay evidence. +- The first marker-committed replay submission globally and permanently owns its replay idempotency key, replay request ID/fingerprint, replay attempt ID, replay semantic event ID, replay audit entry ID, and replay marker ID (`M15-IDEM-002`). The same key with different canonical request bytes returns `replay-idempotency-key-conflict`; the same request under a different key is not an exact retry and returns the coordinate-specific request conflict. +- Every attempt references one existing original transaction. +- Attempt ordering uses ledger sequence, not timestamps. +- An exact replay-submission retry (`M15-REPLAY-003`) returns the original replay attempt only when the replay idempotency key; replay request, attempt, semantic-event, audit-entry, and marker IDs; and complete replay-request fingerprint all match permanent history. It first verifies the current ledger and original attempt/activating marker. Its stored expected-head coordinate must match the owned request but is exempt from equality with the later current head. It performs no historical reconstruction, current-admissibility reassessment, append, ownership refresh, or head advancement. Conflicting reuse returns the coordinate-specific stable conflict reason listed above; a content or append ownership collision not reducible to one ID returns `replay-identity-conflict` or `append-conflict` respectively. +- Multiple distinct attempts may record different outcomes over time without changing the original. +- Derived per-transaction replay indexes are non-authoritative and rebuildable. + +## Privacy + +Replay evidence contains logical IDs, fingerprints, statuses, bounded reason codes, and redacted field paths only. It excludes raw Context, credentials, Authorization headers, provider bodies, endpoints, physical paths, clients, callbacks, and executable values. + +## Principle + +Fresh-evaluator replay proves reproducibility or records its failure. It never converts dry-run readiness into permission for live traffic.