Migrate lock commands to independent objects

This commit is contained in:
2026-09-05 13:11:11 +00:00
parent 4bc33773fa
commit 610eaefb27
13 changed files with 368 additions and 156 deletions

View File

@@ -281,7 +281,8 @@ execution; the preview does not predict output identities.
narratio session validate <session_id> [...common config flags]
```
Read-only preflight checks for config validity, required inputs, audio mode, previous-session requirements, publish outputs, and effective locks.
Read-only preflight checks for config validity, required inputs, audio mode,
previous-session requirements, publish outputs, and independent remote locks.
### `session status`
@@ -290,7 +291,10 @@ narratio session status <session_id> [...common config flags]
```
Prints local manifest state and, when storage is available, status for the
pointer-selected remote commit and its declared published outputs.
pointer-selected remote commit and its declared published outputs. Current
publish metadata reports `published`, `carried_locked`, `locked_unpublished`,
`optional_missing`, and `unselected`; carried output lines include the run
derived from their exact declared key.
### `session init`
@@ -348,7 +352,8 @@ narratio session artifacts <session_id> [--remote] [...common config flags]
Lists effective built-in, configured Scriptorium, and configured extraction
sources; reports planned, available, unavailable, and published state without
reading payload bodies; and includes publish rules, lock state, and optional
remote published-state availability.
remote published-state availability. Remote inspection uses exact commit
declarations and displays the five current publish outcomes when recorded.
### `session locks`
@@ -360,12 +365,14 @@ narratio session locks remove <session_id> <source> [...common config flags]
Behavior:
- list mode reports the effective merge of static and remote locks;
- add/remove mutate only remote locks;
- static locks from pipeline config cannot be removed by CLI commands.
- list mode validates and reports independent remote locks sorted by source;
- add creates one lock and reports an existing lock unless `--force` is used;
- `--force` performs one generation-matched replacement and reports a
concurrent change for operator retry; and
- remove is idempotent and reports when the source was not locked.
See [Operations: Publish Locks](./operations.md#publish-locks) for lock storage
and precedence.
and publication behavior.
## `--artifacts` Selection Rules

View File

@@ -345,10 +345,11 @@ outcome changes also stale affected downstream stages, while an identical
repeated `notarius_disabled` self-skip does not repeatedly invalidate them.
Publish reuse additionally tracks enabled/run-upload behavior, normalized
output rules, static locks, and remote backend/bucket/region/endpoint/root
identity. Credential environment names, local workspace placement, and run IDs
are excluded. Regardless of semantic reuse evidence, executing publish still
revalidates mutable remote locks immediately before commit selection.
output rules, the currently supported configured lock field, and remote
backend/bucket/region/endpoint/root identity. Credential environment names,
local workspace placement, and run IDs are excluded. Regardless of semantic
reuse evidence, executing publish reads independent remote locks directly and
rechecks initially unlocked sources before commit selection.
## Publish Workflow
@@ -399,24 +400,27 @@ local `current_pointer_written` metadata.
## Publish Locks
Lock sources:
Each mutable lock is an independent strict JSON object at
`{session_prefix}/locks/{sha256(source)}.lock`. The lowercase digest is computed
from the exact canonical source. Listing validates every object in that
reserved prefix and reports locks sorted by source.
- static locks in `pipeline.publish.locks`
- mutable remote locks in `{session_prefix}/locks.yml`
Operational rules:
Effective lock rules:
- static and remote locks are merged;
- static locks win on source collisions;
- locked outputs are intentional skips;
- lock add/remove commands mutate only remote lock state through generation-bound
conditional writes. A command retries a bounded number of concurrent
conflicts while its invocation context remains active, so it never replaces a
different lock-document generation; and
- a publish re-reads remote locks immediately before it writes the current
commit pointer. A lock committed before that recheck prevents selecting the
new snapshot, even though its already-uploaded immutable objects may remain
available for a later retry.
- add uses conditional creation and reports an existing lock;
- add with `--force` observes the current generation and attempts one
generation-matched replacement. A concurrent change is reported for an
explicit operator retry;
- remove is idempotent and reports whether a lock was present;
- the initial publish lock snapshot controls output planning. A locked source
carries its exact declaration from the prior current commit when available;
a never-published locked source remains absent even when required;
- carried bytes are not copied. Publish verifies the prior object's exact key,
size, and generation without downloading it; and
- after immutable uploads and the immutable commit, publish re-reads every
initially unlocked participating source. A newly added lock prevents the
current pointer from advancing, although the immutable attempt may remain.
A removed initial lock may conservatively cause one carry.
Examples:

View File

@@ -289,7 +289,7 @@ locked-source work, and exactly one pointer write. Run
## Stage 8 — Migrate Commands And Inspection
**Status:** Pending
**Status:** Completed
### Goal