feat(knowledge-registry): implement durable snapshot registry

.gitignore

@@ -9,3 +9,4 @@ node_modules/
 .pnpm-store/
 *.log
 migration-report.json
+.founderos/runtime/

ARCHITECTURE_DECISIONS.md

@@ -98,6 +98,15 @@ This ledger records repository-level decisions. Feature-level decisions should m
 - **Decision:** Preserve the Milestone 07 snapshot contract and content-derived identity, and carry Milestone 08 per-object content fingerprints in separate comparison evidence. Bind that evidence to the canonical validated Knowledge Object payload, and have the engine verify its metadata, whole-object, and non-metadata content digests against the snapshot descriptor before comparison or workflow progression. Immutable snapshots advance through validated lifecycle operations and human-approved governed change sets. Same-identity comparison is a valid no-op, while workflow initialization requires a material governed change. Review and activation states are reachable only through the workflow, which binds immutable approval or rejection evidence to the proposed snapshot and change set. Successful activation atomically returns the previous baseline as superseded and the proposal as active. `@founderos/knowledge-schema` owns the contracts; `@founderos/knowledge-engine` owns pure orchestration over them.
 - **Consequences:** Snapshot compatibility, lifecycle history, comparison evidence, review decisions, and activation outcomes are reproducible, immutable, and independently testable. Callers must supply valid snapshots, separate matching comparison evidence, transition evidence, an active baseline lifecycle, and a validated proposed lifecycle; no state is retained between calls. Durable workflow storage, authorization, notifications, automatic synchronization or activation, background processing, and audit integrations remain deferred.
 
+## ADR-0013: Persist governed snapshot state through ordered atomic audit envelopes
+
+- **Status:** Accepted
+- **Date:** 2026-07-28
+- **Context:** Milestone 08 produces immutable snapshot, lifecycle, change-set, review-decision, and activation evidence in memory. Milestone 09 must make that evidence durable and independently recoverable without coupling shared contracts to a filesystem, database, vendor transaction model, or retrieval technology. The first activation also has no active baseline, while the Milestone 08 governed change-set contract requires one.
+- **Decision:** Keep strict, versioned, storage-independent durable registry contracts in `@founderos/knowledge-schema`, while `@founderos/knowledge-engine` owns canonical serialization, fingerprint recomputation, replay, integrity verification, and governed orchestration. The governed facade depends on an engine-internal storage/writer port for verified reads, exclusive atomic envelope append, recovery, integrity, and derived-index operations; filesystem locks, fault hooks, and physical persistence remain local-adapter concerns. Store governance history as explicitly sequenced, fingerprint-linked, append-only audit records in complete immutable transaction envelopes. For the local adapter, installing an envelope is preparation rather than commitment: stage the complete envelope on the runtime filesystem, flush its file, atomically install it under a deterministic immutable name, and flush the committed-envelope directory before preparing the commit head. The authoritative commit point is atomic replacement of one fixed, separately canonicalized and fingerprinted commit-head marker after its file is flushed. That marker binds the complete committed transaction count, record count, audit sequence, record-chain head, full-history integrity fingerprint, and last-envelope identity. Flush the marker directory after replacement; suppress only explicitly unsupported directory-sync errors and propagate real I/O failures. Envelopes wholly beyond the marker are uncommitted crash orphans, never replay inputs, and are quarantined before a later write. Scope the initial adapter to one explicit cooperative local writer and use optimistic compare-and-swap against recovered active-snapshot identity for activation. Recover state only by verifying the strict marker, its exact marker-bounded envelope set, and complete replay; reject corrupted, missing, reordered, incomplete, contradictory, or coordinate-mismatched history, and derive active state from verified activations. Any cached active pointer or summary index is non-authoritative and rebuildable. Model the no-baseline first activation with a separate versioned bootstrap change-set evidence contract rather than weakening the Milestone 08 change-set. Assume atomic same-filesystem rename, file flush support, explicit operator handling of crash-orphaned writer locks, and a cooperative single-writer/local-administrator threat model. Node.js lacks portable descriptor-relative `openat(2)` traversal, so the adapter rechecks physical directory identity around critical operations and uses no-follow leaf reads, but does not claim protection from a malicious privileged process concurrently replacing directory ancestors between checks.
+- **Consequences:** Registration, lifecycle, decision, and activation history can be verified and recovered without process memory; activation effects become all-or-nothing, stale writers fail without committed changes, and deletion of a valid committed suffix is detected while the trusted marker remains. A crash before marker replacement leaves the prior committed state plus an ignorable envelope orphan; a crash after marker replacement requires the newly referenced envelope and exact full-history coordinate. The local marker and unkeyed fingerprints detect accidental corruption and partial deletion, not a coordinated privileged rollback that replaces or re-signs both the marker and the matching complete history, or deletes all local evidence. Shared contracts remain portable and preserve Milestone 07 and 08 identities and governance evidence, but the first adapter is cooperative local single-writer only. Database adapters, distributed locks and transactions, hostile local concurrency guarantees, remote coordination, replication, object stores, automatic synchronization, and background event processing remain deferred and require a later architecture decision.
+- **Integrity clarification:** Snapshot registrations persist a durable canonical-JSON projection of the manifest and logical reference, whose SHA-256 commitment is independently recomputed without changing the Milestone 07 snapshot-v1 identity. The strict finite, plain, acyclic serializer is scoped to that commitment; Milestone 07 and 08 fingerprints retain their historical byte behavior, including omission of `undefined` object properties and prior array handling. Before cloning, the shared verifier requires a plain raw durable record and a valid own enumerable data-property discriminator; snapshot registrations then validate their original raw manifest evidence. This prevents cloning from flattening discriminator accessors, unsupported evidence prototypes, or nested accessors into apparently valid records. Its approved `ready` or `migrated` entries must exactly match the snapshot object descriptors by identity, type, source path, and source hash. Public mutations capture immutable invocation-time input before asynchronous lock acquisition. Recovery reports exact registration, lifecycle-transition, decision, and activation evidence counts for success or the verified failure prefix. An earlier semantic replay failure and its progress take precedence over a later missing marker-referenced tail. Recovery and integrity compare the derived index against their exact authoritative replay, report its health separately, never repair it implicitly, and normalize filesystem-result errors without physical paths. Post-open storage-safety failures become stable structured results, while initial configuration and path errors remain open failures; direct index inspection and rebuild normalize authoritative-read and derived-write failures the same way.
+
 ## ADR template
 
 ```markdown

CHANGELOG.md

@@ -24,3 +24,13 @@ All notable changes to FounderOS will be documented here.
 - Validated in-memory candidate provider, deterministic repository access, and repository-backed query execution.
 - Approved-corpus candidate source, immutable repository snapshots, corpus-backed repository initialization, and deterministic change detection.
 - Governed immutable snapshot lifecycle, deterministic comparison and change sets, and human-controlled approval/activation readiness.
+- Strict storage-independent durable-registry, audit-envelope, activation, recovery, integrity, and derived-index contracts.
+- Governed local file-backed snapshot registration, lifecycle and decision history, atomic activation audit persistence, restart recovery, integrity verification, and rebuildable active-index support.
+- Independently verifiable canonical-JSON manifest commitments bound one-to-one to snapshot object descriptors, synchronous immutable mutation capture, exact recovery evidence counts, public derived-index consistency reporting, and machine-independent filesystem failure results and index-operation errors.
+- Dedicated strict manifest commitment hashing with byte-compatible Milestone 07 and 08 fingerprints, plus pre-clone raw record-discriminator and manifest-evidence validation in both registration facades.
+- Descriptor-stable governed mutation capture, ECMAScript-private registry internals, and raw-before-normalization fingerprint verification for durable records, envelopes, and derived indexes.
+- Null-prototype mutation capture with reserved `__proto__` rejection, plus canonical primitive-leaf enforcement and stable serializer-failure normalization for durable integrity verification.
+- Path-free post-open storage-safety integrity and recovery results, with semantic replay failures preserving exact verified-prefix progress ahead of missing-tail coordinate failures.
+- Descriptor-only raw error locations that never invoke accessors, plus an adapter-neutral governed storage/writer port proven by an in-memory lifecycle-through-activation integration.
+- Builder-only omission of schema-valid explicit `undefined` object properties preserves Milestone 07/08 change-set compatibility without weakening strict persisted-record verification.
+- Bidirectional runtime/source-root overlap rejection prevents a registry runtime from containing canonical source trees and runs before filesystem mutation.

DOCUMENTATION_INDEX.md

@@ -103,6 +103,21 @@ The documents below are the official FounderOS v1.0 bootstrap specification, org
 - [Milestone 08 Verification Checklist v1.0](./docs/milestones/milestone-08/FounderOS_Milestone_08_Verification_Checklist_v1.0.md)
 - [Milestone 08 Codex Execution Prompt v1.0](./docs/milestones/milestone-08/FounderOS_Milestone_08_Codex_Execution_Prompt_v1.0.md)
 
+### Milestone 09 — Durable Snapshot Registry and Activation Audit Foundation
+
+- [Milestone 09 Package README v1.0](./docs/milestones/milestone-09/FounderOS_Milestone_09_Package_README_v1.0.md)
+- [Durable Snapshot Registry and Activation Audit Foundation Specification v1.0](./docs/milestones/milestone-09/FounderOS_Milestone_09_Durable_Snapshot_Registry_and_Activation_Audit_Foundation_Specification_v1.0.md)
+- [Durable Snapshot Registry Contract v1.0](./docs/milestones/milestone-09/FounderOS_Durable_Snapshot_Registry_Contract_v1.0.md)
+- [Durable Lifecycle Transition Record Specification v1.0](./docs/milestones/milestone-09/FounderOS_Durable_Lifecycle_Transition_Record_Specification_v1.0.md)
+- [Activation Audit Record Contract v1.0](./docs/milestones/milestone-09/FounderOS_Activation_Audit_Record_Contract_v1.0.md)
+- [Durable Activation Audit Store Architecture v1.0](./docs/milestones/milestone-09/FounderOS_Durable_Activation_Audit_Store_Architecture_v1.0.md)
+- [Atomic Snapshot Activation Transaction Semantics v1.0](./docs/milestones/milestone-09/FounderOS_Atomic_Snapshot_Activation_Transaction_Semantics_v1.0.md)
+- [Snapshot Registry Recovery and Integrity Verification Specification v1.0](./docs/milestones/milestone-09/FounderOS_Snapshot_Registry_Recovery_and_Integrity_Verification_Specification_v1.0.md)
+- [Local File-Backed Snapshot Registry Adapter Specification v1.0](./docs/milestones/milestone-09/FounderOS_Local_File_Backed_Snapshot_Registry_Adapter_Specification_v1.0.md)
+- [Milestone 09 Acceptance Criteria v1.0](./docs/milestones/milestone-09/FounderOS_Milestone_09_Acceptance_Criteria_v1.0.md)
+- [Milestone 09 Verification Checklist v1.0](./docs/milestones/milestone-09/FounderOS_Milestone_09_Verification_Checklist_v1.0.md)
+- [Milestone 09 Codex Execution Prompt v1.0](./docs/milestones/milestone-09/FounderOS_Milestone_09_Codex_Execution_Prompt_v1.0.md)
+
 ## Repository governance
 
 - [Architecture decisions](./ARCHITECTURE_DECISIONS.md)

README.md

@@ -2,7 +2,7 @@
 
 FounderOS is an AI-native operating system for founder decision-making, organizational memory, and governed AI-assisted execution. This repository is a documentation-first TypeScript monorepo.
 
-The repository currently provides the governed KnowledgeOS schema, ingestion, migration, corpus-backed repository snapshots, deterministic comparison and governed change sets, human-controlled snapshot review and activation readiness, and deterministic query foundations. It does **not** implement persistence, automatic activation or synchronization, semantic retrieval, Hermes, an agent runtime, MCP connectors, or a user interface.
+The repository currently provides the governed KnowledgeOS schema, ingestion, migration, corpus-backed repository snapshots, deterministic comparison and governed change sets, human-controlled snapshot review, a local durable snapshot registry and activation audit trail, restart recovery and integrity verification, and deterministic query foundations. It does **not** implement a general-purpose application database, distributed or remote persistence, automatic activation or synchronization, semantic retrieval, Hermes, an agent runtime, MCP connectors, or a user interface.
 
 ## Architecture at a glance
 
@@ -20,12 +20,12 @@ The official specifications are indexed in [DOCUMENTATION_INDEX.md](./DOCUMENTAT
 
 ## Implemented foundations
 
-- [`@founderos/knowledge-schema`](./packages/knowledge-schema/README.md) provides strict runtime schemas and inferred TypeScript contracts for KnowledgeOS metadata, objects, migration, queries, candidate sources, repository snapshots, lifecycle records, governed change sets, approval workflows, and results.
-- [`@founderos/knowledge-engine`](./services/knowledge-engine/README.md) provides read-only ingestion, manifest-controlled Priority 1 corpus migration, corpus-backed repository initialization, deterministic snapshots, governed comparison and change sets, human-controlled review/approval/activation readiness, and exact filtering with preserved source provenance.
+- [`@founderos/knowledge-schema`](./packages/knowledge-schema/README.md) provides strict runtime schemas and inferred TypeScript contracts for KnowledgeOS metadata, objects, migration, queries, candidate sources, repository snapshots, lifecycle records, governed change sets, approval workflows, canonical-JSON manifest commitments bound to snapshot object descriptors, durable audit records and envelopes, activation, recovery, integrity, and derived indexes.
+- [`@founderos/knowledge-engine`](./services/knowledge-engine/README.md) provides read-only ingestion, manifest-controlled Priority 1 corpus migration, corpus-backed repository initialization, deterministic snapshots, governed comparison and change sets, human-controlled review and approval, governed durable activation, local append-only audit persistence, restart recovery and integrity verification, and exact filtering with preserved source provenance.
 - [`specs/knowledge-templates`](./specs/knowledge-templates) provides valid Markdown templates for all seven KnowledgeOS object types.
 - [`knowledge/migration-manifest.yaml`](./knowledge/migration-manifest.yaml) binds the eight canonical FounderOS Priority 1 documents to reviewed object identities, logical destinations, metadata, and source hashes.
 
-Corpus refresh execution, vault watching, durable persistence, automatic synchronization or activation, semantic retrieval, embeddings, ranking, graph storage, agent behavior, connectors, and interfaces remain unimplemented.
+Automatic corpus refresh, vault watching, background synchronization or activation, database and distributed adapters, remote coordination and replication, semantic retrieval, embeddings, ranking, graph storage, agent behavior, connectors, and interfaces remain unimplemented. Milestone 09 persistence is deliberately limited to an explicit, Git-ignored, cooperative single-writer local runtime; see the [knowledge-engine durability documentation](./services/knowledge-engine/README.md#milestone-09-durable-registry) before operating it.
 
 ## Repository layout
 

docs/milestones/milestone-09/FounderOS_Activation_Audit_Record_Contract_v1.0.md

@@ -0,0 +1,54 @@
+# FounderOS Activation Audit Record Contract v1.0
+
+## Purpose
+
+Define the durable evidence generated when an approved snapshot becomes the active KnowledgeOS state.
+
+## Activation Audit Record
+
+The record should include:
+
+- Record schema version
+- Activation ID
+- Transaction ID
+- Candidate snapshot ID
+- Previous active snapshot ID, if any
+- Expected active snapshot ID used as a concurrency precondition
+- Approval decision ID
+- Change-set ID
+- Activation actor
+- Activation reason
+- Activation timestamp
+- Candidate snapshot fingerprint
+- Previous snapshot fingerprint, if any
+- Resulting active snapshot ID
+- Resulting lifecycle transitions
+- Previous audit record fingerprint
+- Canonical record fingerprint
+
+## Required Preconditions
+
+Activation must fail unless:
+
+- The candidate snapshot is registered.
+- The candidate is approved.
+- The referenced approval decision is valid.
+- The referenced change set matches the candidate and baseline snapshots.
+- The expected active snapshot matches recovered active state.
+- The candidate is not already superseded or archived.
+- All evidence fingerprints verify.
+
+## Audit Guarantees
+
+The record must prove:
+
+- Which snapshot became active
+- Which snapshot was superseded
+- Who approved and activated it
+- Why activation occurred
+- Which exact content fingerprints were involved
+- Whether concurrency preconditions were satisfied
+
+## Principle
+
+Activation is a governed transaction with durable evidence, not a simple pointer update.

docs/milestones/milestone-09/FounderOS_Atomic_Snapshot_Activation_Transaction_Semantics_v1.0.md

@@ -0,0 +1,56 @@
+# FounderOS Atomic Snapshot Activation Transaction Semantics v1.0
+
+## Purpose
+
+Define all-or-nothing activation behavior for governed KnowledgeOS snapshots.
+
+## Transaction Inputs
+
+An activation transaction requires:
+
+- Candidate snapshot
+- Current active snapshot, if any
+- Expected active snapshot precondition
+- Approved change set
+- Approval decision
+- Activation actor and reason
+
+## Atomic Effects
+
+A successful activation transaction must commit these effects together:
+
+1. Record candidate transition to Active.
+2. Record previous active snapshot transition to Superseded, when applicable.
+3. Persist activation audit evidence.
+4. Advance the audit chain.
+5. Make the new active state recoverable.
+
+No partial effect may be externally visible as committed.
+
+## Concurrency Rule
+
+Use optimistic compare-and-swap semantics:
+
+```text
+expectedActiveSnapshotId == recoveredActiveSnapshotId
+```
+
+If the condition fails, activation must abort without committed state changes.
+
+## Idempotency
+
+Replaying the same transaction ID with the same canonical payload should return the original committed result.
+
+Reusing the transaction ID with a different payload must fail.
+
+## Crash Safety
+
+The adapter must ensure that interruption:
+
+- Before commit leaves no committed activation.
+- After commit yields a fully recoverable activation.
+- Never produces two active snapshots.
+
+## Principle
+
+There must be exactly one governed active knowledge state after every committed activation transaction.