Publish immutable remote commits

docs/internal/artifacts.md

@@ -102,10 +102,9 @@ restore, status and validation checks, and previous-cache planning.
 
 Core helpers:
 
-- `LoadCurrentRunPointer`
-- `LoadCurrentManifest`
 - `LoadCurrentState`
 - `ValidateCurrentStateIdentity`
+- `RemoteCommitManifest` and `CurrentCommitPointer`
 
 Typed missing-state errors:
 
@@ -133,6 +132,12 @@ Caller policy is intentionally outside artifacts helpers:
 - spool/cache paths;
 - S3 session/run/current-state key layout.
 
+New publication creates run-scoped immutable objects, including
+`runs/{run_id}/commit.json` and `runs/{run_id}/session-manifest.json`. The sole
+mutable selector is `current/commit-pointer.json`; readers verify its selected
+commit and declared object generations/checksums. Legacy current-pair loading
+is confined to `current_state_legacy.go` for migration only.
+
 Campaign, session, and Narratio run IDs are validated as portable opaque
 segments at configuration and artifact boundaries before they can be used in a
 workspace or S3 namespace. Previous-artifact destinations remain typed,

docs/internal/stage-publish.md

@@ -16,8 +16,8 @@ Upload run/session outputs to object storage and atomically advance remote curre
 
 - uploaded invocation record and selected publish outputs;
 - uploaded durable previous-session cache files when present;
-- updated remote current manifest; and
-- remote current-run commit marker, written last.
+- immutable run-scoped commit manifest; and
+- current commit pointer, written last.
 
 Exact remote placement and the operator workflow belong in
 [Operations](../operations.md#publish-workflow).
@@ -40,7 +40,10 @@ Exact remote placement and the operator workflow belong in
 - selected artifact filter applies to configured artifact sources only.
 - locked outputs are skipped intentionally (including required ones).
 - optional missing outputs are skipped; required missing unlocked outputs fail.
-- writes remote current manifest before current run pointer.
+- creates one complete immutable source-to-destination mapping before upload;
+- uploads and verifies every declared immutable object and the commit manifest;
+- updates `current/commit-pointer.json` exactly once, last; and
+- does not write the legacy `current/manifest.json` or `current/run_id.txt` pair.
 
 ## Metadata Signals
 
@@ -51,12 +54,13 @@ Includes counts/lists for:
 - skipped optional outputs
 - skipped unselected outputs
 - locked outputs
-- current-state key paths
-- `current_pointer_written`
+- remote commit and current-pointer key paths
 
 ## Invariants
 
-- `current/run_id.txt` is the remote commit marker and is written last.
+- `current/commit-pointer.json` is the remote commit marker and is written last.
+- run files, selected outputs, previous-cache files, and the committed session
+  manifest are all declared by an immutable commit under the run prefix.
 - run and previous uploads contain only manifest-declared regular files opened
   from verified descriptors; symlinks, special files, replacement races, and
   undeclared entries are rejected or ignored before uploads begin.

docs/internal/workspace.md

@@ -55,7 +55,8 @@ lock only while their context remains active, and report a release failure.
 Automatic post-publish cleanup:
 
 - only runs when publish actually executed and succeeded;
-- requires `uploaded=true` and `current_pointer_written=true` metadata;
+- requires `uploaded=true`, a remote commit key, and a current commit-pointer
+  key in publish metadata;
 - consumes the resolved cleanup policy described in
   [Configuration](../config.md);
 - refuses unsafe deletes (root delete, out-of-root delete, and symlinked

docs/operations.md

@@ -200,13 +200,15 @@ Publish commit model:
 
 - uploads eligible run files under `{session_prefix}/runs/{run_id}/`, excluding
   audio and the run-local Notarius staging bundle;
-- uploads configured published outputs, including only explicitly configured
-  extraction lanes;
-- uploads `previous/**` cache files when present;
-- writes `current/manifest.json`;
-- writes `current/run_id.txt` last.
+- uploads configured published outputs and `previous/**` cache files into the
+  same immutable run scope, including only explicitly configured extraction
+  lanes;
+- writes `{session_prefix}/runs/{run_id}/commit.json` after all declared
+  immutable objects are uploaded and verified; and
+- writes `{session_prefix}/current/commit-pointer.json` once, last.
 
-`current/run_id.txt` is the remote current-state commit marker.
+`current/commit-pointer.json` is the remote current-state commit marker. It
+selects exactly one immutable commit, which declares the complete object set.
 
 ## Remote Commit Migration
 
@@ -217,10 +219,10 @@ commit by version, checksum, size, and storage generation; committed artifacts
 are also checksum- and generation-bound. Readers accept this contract now and
 strictly reject mismatched or unknown data.
 
-The publish workflow above remains the legacy writer until its planned cutover.
 Legacy reads are limited to a coherent `current/manifest.json` and
-`current/run_id.txt` pair; a torn pair is rejected. New remote commit state does
-not carry local `current_pointer_written` metadata.
+`current/run_id.txt` pair; a torn pair is rejected. New publication does not
+write that pair and remote commit state does not carry local
+`current_pointer_written` metadata.
 
 ## Publish Locks
 

docs/policy/architecture.md

@@ -167,13 +167,13 @@ contracts belong under [Integrations](../integrations/).
 ## Publish Commit Boundary
 
 Publish has one explicit remote commit boundary. A remote run becomes current
-only after Narratio has successfully uploaded the run record, required published
-outputs, `current/manifest.json`, and finally `current/run_id.txt`.
+only after Narratio has successfully uploaded its immutable run-scoped objects,
+the immutable commit manifest, and finally the current commit pointer.
 
-`current/run_id.txt` is the commit marker and must be written last. Failed,
-incomplete, skipped, or uncommitted publish attempts must not be presented as
-current remote state. Publish locks remain authoritative and are not bypassed by
-a forced run.
+`current/commit-pointer.json` is the sole mutable selector and must be written
+exactly once, last. Failed, incomplete, skipped, or uncommitted publish attempts
+must not be presented as current remote state. Publish locks remain authoritative
+and are not bypassed by a forced run.
 
 Automatic local cleanup is permitted only after a successful publish commit,
 only when explicitly configured, and only through the path-safety guardrails.

docs/roadmap/implementation.md

@@ -29,7 +29,7 @@ All stages are pending when this plan is created.
 | 11 | Make manifest and run identity singular | COR-001, TST-006 | Completed |
 | 12 | Centralize handled terminal-failure persistence | RSK-001, TST-002, SIM-001, COM-001 | Completed |
 | 13 | Introduce the immutable remote-commit model and legacy boundary | ARC-003 | Completed |
-| 14 | Publish through immutable commits and canonical mappings | COR-004, COR-011, DUP-002, TST-004 | Pending |
+| 14 | Publish through immutable commits and canonical mappings | COR-004, COR-011, DUP-002, TST-004 | Completed |
 | 15 | Make remote locks generation-safe and harden pagination | RSK-005, RSK-014 | Pending |
 | 16 | Persist retryable post-commit cleanup state | COR-006, COR-007 | Pending |
 | 17 | Bind restore/status to a committed snapshot and reject conflicts | COR-008, COR-009, TST-005 | Pending |