Spiral/cyc 20260919 ttz7 c 36 runtime contracts

.spiral/cycles/CYC-20260919-TTZ7C-36.md

@@ -0,0 +1,56 @@
+# Cycle: Reliable Runtime Contracts And Readable Workflows
+
+Status: Accepted. Human accepted on 2026-09-19 after cycle evaluation.
+Branch: spiral/CYC-20260919-TTZ7C-36-runtime-contracts.
+Base: a60545cc68058302d82ba5dcd1847fe722396e51 (master).
+
+Goal: correct the three demonstrated refactor regressions and make the affected
+runtime, inspection and recovery workflows easier to reason about.
+
+Plan continuity: deliberately precede the remaining randomized/soak roadmap
+work with this maintainer-requested correction. SRC-001, REQ-001, DES-001 and
+SRC-20260919-TTZ7C-18 / REQ-20260919-TTZ7C-20 remain governing durability
+direction. The accepted power-loss implementation and runtime refactor are in
+place; this cycle repairs their lifecycle boundaries before broader testing.
+
+Scope: concurrent shutdown completion; acceptance failure checks; duplicate-ID
+compatibility; same-level inspection and recovery coordinating methods;
+regression evidence; the already requested local acceptance/integration rule.
+
+Non-goals: format changes, migrations, automatic rerun, new recovery policy,
+dependency upgrades, worker-pool redesign, VM2 replacement, full rebuild or
+broader randomized/filesystem/soak testing. Keep the existing classes and public
+functions. A newly discovered regression caused by this work remains in scope.
+
+Evaluation: reproduce the failures before repair; prove runtime contracts with
+controlled interleavings and real process shutdown evidence; rerun the existing
+112-test regression suite and focused lint; review abstraction consistency and
+validate causal history. Stop at human cycle acceptance. Integration is separate.
+
+Pause/replan if fixes require a changed durability/recovery contract or new
+public/disk format. The prior review plus explicit cycle instruction satisfy
+the intent/reality checkpoint; no second confirmation is required.
+
+## Evaluation
+
+Implementation and human acceptance are complete. All 118 regression
+tests and focused lint pass. The six new tests first failed against unchanged
+product code, then passed after repair. EVD-20260919-TTZ7C-41 records the baseline,
+acceptance matrix and final implementation verification. Review confirms the
+same-level workflow changes preserve sequencing, audit and cleanup semantics.
+No scope expansion, new class, dependency or format was needed.
+
+The branch identity has been checked before each semantic commit. The existing
+AGENTS.md acceptance/integration clarification was preserved and committed here.
+Do not merge into master without separate integration authorization.
+
+## Human acceptance
+
+After reviewing the cycle outcome and its validation, the maintainer replied:
+
+> accepted
+
+This accepts the evaluated branch tip
+`061571e48c453e5f3d7086a33af0d94926b2f7ea`. The cycle is closed and ready to
+propose for integration. Integration into master is not authorized by this
+acceptance; the branch and its immutable causal history remain intact.

.spiral/cycles/CYC-20260919-TTZ7C-36.ttl

@@ -0,0 +1,19 @@
+@prefix sd: <https://muze.nl/ns/spiral-developer#> .
+@prefix dcterms: <http://purl.org/dc/terms/> .
+@prefix project: <https://github.com/simplyedit/simplystore/spiral#> .
+
+project:CYC-20260919-TTZ7C-36
+    a sd:Cycle ;
+    dcterms:identifier "CYC-20260919-TTZ7C-36" ;
+    sd:repositoryPath ".spiral/cycles/CYC-20260919-TTZ7C-36.md" ;
+    sd:status sd:Accepted ;
+    sd:derivedFrom [
+        a sd:ArtifactReference ;
+        sd:artifact project:REQ-20260919-TTZ7C-39 ;
+        sd:gitCommit "13f9b33f3fe7d7dc97ad9e3b53870764685b95bd"
+    ] ;
+    sd:transforms [
+        a sd:ArtifactReference ;
+        sd:artifact project:CYC-20260919-TTZ7C-36 ;
+        sd:gitCommit "061571e48c453e5f3d7086a33af0d94926b2f7ea"
+    ] .

.spiral/designs/DES-20260919-TTZ7C-40.md

@@ -0,0 +1,62 @@
+# Design: Complete Lifecycle Contracts
+
+Keep DES-20260919-TTZ7C-32 as the broader runtime architecture. This design adds
+explicit contracts where its refactor lost ordering and completion semantics.
+
+## Corrections
+
+Close owns one completion promise. The first call synchronously stops admission
+and starts resource closure; all subsequent calls await the same outcome,
+including rejection. A separate closeResources() holds the existing ordered
+acceptance/runner/pool/ownership cleanup. Preserve retention after storage
+failure. Do not add another server-only shutdown guard: it would mask a broken
+runtime contract for other callers. The server may safely await close from both
+signal handlers.
+
+After persisting acceptance and passing its existing fault point, check storage
+health again before queue insertion and success return. A concurrent command's
+failure may invalidate admission while an append is awaited. Retain any records
+already written; never roll back evidence or automatically rerun. Reject later
+admission through the existing failed state.
+
+Command preparation parses and validates identity, then recognizes an existing
+ID before validating a new command's name or serializing it. Move the existing
+duplicate-result branch into that position rather than adding a second lookup
+path or weakening validation of new commands.
+
+## Readability
+
+StoreInspector.inspect() coordinates path validation, inventory, command
+history, integrity, reconstruction, artifact checks and stable-snapshot/report
+creation. loadCommandHistory() groups reading log/status records, constructing
+commands and validating committed order. Prefix validity is initialized where
+reconstruction begins, after integrity/history diagnostics are available.
+
+RecoveryApplication.runApprovedCommand() coordinates freshness, selection,
+activation, execution, result assessment and commit. markCommandActive() owns
+attempt numbering, audit-before-status ordering and status serialization. Keep
+recordAttempt() as the existing audit operation. No new classes or generic
+workflow engine; no changes to ordering, reports, locks or integrity checks.
+
+## Verification and risk
+
+Reproduce regression tests before changing product code. Use controlled promise
+barriers for command execution and ownership release, test concurrent close
+success/failure, and prove rejection of admission while closing. Inject failure
+at the acceptance persistence boundaries and assert no enqueue or success,
+retained records and ownership. Verify known ID-only retries before and after
+execution while rejecting unknown incomplete commands.
+
+Use a subprocess with a command blocked on an explicit release file to deliver
+both shutdown signals before allowing completion. Observe signal handling, then
+release the command, require done status and released locks, and restart/query
+the committed state. Bound test waits and release barriers during cleanup.
+
+All existing runtime, offset, startup, ACID, crash, handler, power-loss and
+administrator/storage suites remain required. Read the final coordinator code
+as well as running lint; method length alone is not proof of useful abstraction.
+
+The observed failure is composition risk (adopted WPF-HUMAN-001-W4); verify the
+server/runtime interaction, rather than treating isolated final-state tests as
+sufficient evidence. The existing acceptance/integration clarification controls
+authority drift locally; no process-core or culture changes are required.

.spiral/designs/DES-20260919-TTZ7C-40.ttl

@@ -0,0 +1,24 @@
+@prefix sd: <https://muze.nl/ns/spiral-developer#> .
+@prefix dcterms: <http://purl.org/dc/terms/> .
+@prefix project: <https://github.com/simplyedit/simplystore/spiral#> .
+@prefix culture: <https://muze.nl/ns/spiral-developer/culture/> .
+
+project:DES-20260919-TTZ7C-40
+    a sd:Design ;
+    dcterms:identifier "DES-20260919-TTZ7C-40" ;
+    sd:repositoryPath ".spiral/designs/DES-20260919-TTZ7C-40.md" ;
+    sd:status sd:Active ;
+    sd:satisfies [
+        a sd:ArtifactReference ;
+        sd:artifact project:REQ-20260919-TTZ7C-39 ;
+        sd:gitCommit "13f9b33f3fe7d7dc97ad9e3b53870764685b95bd"
+    ] ;
+    sd:shapedBy [
+        a sd:ArtifactReference ;
+        sd:artifact culture:CUL-MUZE-001 ;
+        sd:gitCommit "9958f0e296e84169c21c02aa478ac4aae5a06a41"
+    ], [
+        a sd:ArtifactReference ;
+        sd:artifact culture:CUL-MUZE-LIB-001 ;
+        sd:gitCommit "9958f0e296e84169c21c02aa478ac4aae5a06a41"
+    ] .

.spiral/evidence/EVD-20260919-TTZ7C-41.md

@@ -0,0 +1,59 @@
+# Evidence: Runtime Contract Corrections
+
+## Baseline before product changes
+
+Test additions against the unchanged runtime at 665a97d reproduce all three
+review findings. Running node --test --test-reporter=tap test/store-runtime.mjs
+produces six passes (existing tests) and six failures (new tests):
+
+- overlapping close resolves before the active command finishes;
+- overlapping close reports success despite ownership-release failure;
+- storage failure at each of two acceptance boundaries still returns success;
+- a known ID-only retry returns 422 rather than its existing status;
+- SIGTERM followed by SIGINT exits with command status active, rather than done.
+
+The process test holds execution on an explicit release file, observes both
+signals, then checks status and ownership and restarts the store. Direct tests
+use controlled promises and real temporary log files. No product file changed
+before this baseline run. The full pre-cycle review suite passed 112 tests;
+these failures demonstrate its missing interleaving/compatibility coverage.
+
+## Final implementation verification
+
+Implementation at 5d9e81218d5a51d8d3171f7132e73c2e4bfc298a passes all 118 tests: the existing 112 plus
+six new runtime contract cases. No failures, skips or TODOs. Command:
+
+```sh
+node --test --test-reporter=tap test/store-runtime.mjs \
+  test/durability-startup.mjs test/conversion-offsets.mjs \
+  test/command-offsets.mjs test/acid-baseline.mjs \
+  test/durability-crash.mjs test/after-change-handlers.mjs \
+  test/power-loss-baseline.mjs test/storage.mjs test/admin-recovery.mjs
+```
+
+Local-server suites require socket access outside this environment's restricted
+sandbox; the run was authorized and used disposable stores. Focused ESLint passes
+for the three modified production modules and test/store-runtime.mjs. Staged
+provenance and whitespace validation passed before every semantic commit.
+
+| Criterion | Result |
+| --- | --- |
+| R1 Closure | Controlled active execution blocks both close callers. Both observe cleanup rejection; repeated close retains that failure. The real process receives SIGTERM and SIGINT before its command is released, then records done, releases ownership and restarts with the committed value. |
+| R2 Acceptance | Injected storage failure after log persistence or after accepted-status persistence rejects success and leaves the queue empty. Logged command evidence remains; subsequent admission is refused and ownership retained. |
+| R3 Compatibility | A known ID-only retry returns accepted or done status without a second append/execution. An unknown ID without a name still returns 422. |
+| R4 Readability | inspect() now lists inspection phases; prefix bookkeeping lives in reconstruction. runApprovedCommand() delegates activation numbering, audit and status serialization to markCommandActive(). No workflow order or report shape changed. |
+| R5 Preservation | Full startup, offset, ACID, crash, handler, power-loss and administrative suites pass. |
+| R6 Review boundary | The prior AGENTS.md edit is committed on the new cycle branch. Cycle acceptance and integration remain separate; master is unchanged. |
+
+Production diff: runtime +8, inspection +4, recovery +6 net lines. Three
+supporting methods clarify existing concerns; no new classes or dependencies.
+The new tests add 209 net lines, including controlled interleavings and the
+subprocess/restart proof. The failing baseline remains in Git at 959e2cd92181be07f3fe38d38328f10ba41923b3.
+
+## Evaluation limits
+
+This is evidence for the specified lifecycle contracts and preservation of the
+covered behaviors, not a new filesystem/hardware durability claim. Randomized
+and destructive soak work remains deferred under the governing roadmap.
+Human cycle acceptance is pending. Integration is not authorized by acceptance
+alone.

.spiral/evidence/EVD-20260919-TTZ7C-41.ttl

@@ -0,0 +1,19 @@
+@prefix sd: <https://muze.nl/ns/spiral-developer#> .
+@prefix dcterms: <http://purl.org/dc/terms/> .
+@prefix project: <https://github.com/simplyedit/simplystore/spiral#> .
+
+project:EVD-20260919-TTZ7C-41
+    a sd:VerificationEvidence ;
+    dcterms:identifier "EVD-20260919-TTZ7C-41" ;
+    sd:repositoryPath ".spiral/evidence/EVD-20260919-TTZ7C-41.md" ;
+    sd:status sd:Active ;
+    sd:verifies [
+        a sd:ArtifactReference ;
+        sd:artifact project:IMP-20260919-TTZ7C-33 ;
+        sd:gitCommit "5d9e81218d5a51d8d3171f7132e73c2e4bfc298a"
+    ] ;
+    sd:transforms [
+        a sd:ArtifactReference ;
+        sd:artifact project:EVD-20260919-TTZ7C-41 ;
+        sd:gitCommit "959e2cd92181be07f3fe38d38328f10ba41923b3"
+    ] .

.spiral/implementations/IMP-20260919-TTZ7C-33.md

@@ -78,3 +78,26 @@ restore candidates retain their locks and audit evidence; source ownership is
 released under the same conditions. Existing duplicate reads and later-dataset
 queries in inspection are retained to avoid mixing race or performance semantics
 into the readability refactor.
+
+## Cycle 36: complete lifecycle contracts
+
+DES-20260919-TTZ7C-40 supplements the existing architecture. All close callers
+now await one completion promise, including cleanup rejection. The server can
+await it from both signal handlers without prematurely exiting. Acceptance
+rechecks storage health after persistence and before queueing/acknowledgment.
+Command preparation recognizes an existing valid ID before applying new-command
+name requirements, restoring ID-only retry compatibility.
+
+StoreInspector groups log/status interpretation in loadCommandHistory() and
+initializes prefix validity inside reconstruction. RecoveryApplication groups
+attempt numbering, audit persistence and active-status serialization in
+markCommandActive(). The coordinating methods stay at workflow level; the order
+of checks, writes, parsing, audit and cleanup remains unchanged. No new classes
+or dependencies are introduced.
+
+The preceding implementation version added six failing regression cases before
+product changes. Those tests now pass: overlapping closure waits for execution
+and shares cleanup failure; both persistence-boundary failures reject acceptance;
+known ID-only retries return status while incomplete new commands fail; and a
+real process receiving both shutdown signals commits, unlocks and restarts.
+EVD-20260919-TTZ7C-41 preserves the baseline and records final suite results.

.spiral/implementations/IMP-20260919-TTZ7C-33.ttl

@@ -19,14 +19,23 @@ project:IMP-20260919-TTZ7C-33
         sd:artifact project:DES-20260919-TTZ7C-32 ;
         sd:gitCommit "f7ced34e7821e3aa02606c2d1abe6f1bb1c08c5b"
     ] ;
-    sd:transforms [
+    sd:implements [
+        a sd:ArtifactReference ;
+        sd:artifact project:DES-20260919-TTZ7C-40 ;
+        sd:gitCommit "665a97d1c366b4cce2b9004d6e649a389d18a2c4"
+    ] ;
+    sd:changeCausedBy [
+        a sd:ArtifactReference ;
+        sd:artifact project:EVD-20260919-TTZ7C-41 ;
+        sd:gitCommit "959e2cd92181be07f3fe38d38328f10ba41923b3"
+    ], [
         a sd:ArtifactReference ;
-        sd:artifact project:IMP-20260919-TTZ7C-26 ;
-        sd:gitCommit "e31e07c9bc8d4fc6458da1d213609dbf1aa4a7a2"
+        sd:artifact project:DES-20260919-TTZ7C-40 ;
+        sd:gitCommit "665a97d1c366b4cce2b9004d6e649a389d18a2c4"
     ] ;
     sd:transforms [
         a sd:ArtifactReference ;
         sd:artifact project:IMP-20260919-TTZ7C-33 ;
-        sd:gitCommit "f0c1616c828db6c63c84cd63dcf4c4f4324188c1"
+        sd:gitCommit "959e2cd92181be07f3fe38d38328f10ba41923b3"
     ] ;
     sd:implementationChangeKind sd:MixedChange .

.spiral/project-context.md

@@ -18,7 +18,21 @@ Project causal-graph namespace: `https://github.com/simplyedit/simplystore/spira
 
 Spiral core source: `.spiral-core/`, git submodule for `https://github.com/muze-labs/spiral-developer.git`, currently checked out at `8d4b2c738a413abd4cccca740ce958f486e5f7af`.
 
-Latest accepted Spiral cycle: `.spiral/cycles/CYC-20260919-TTZ7C-31.md` (`Readable
+Latest accepted cycle: CYC-20260919-TTZ7C-36, Reliable Runtime Contracts And Readable
+Workflows, on spiral/CYC-20260919-TTZ7C-36-runtime-contracts. The maintainer
+confirmed this cycle after independent review found three regressions in the
+accepted runtime refactor. It deliberately precedes remaining randomized/soak
+work to repair shutdown completion, storage-failure acceptance and duplicate-ID
+compatibility, and clarify inspection/recovery coordinators. Source SRC-37,
+understanding UND-38, request REQ-39 and design DES-40 use the full
+20260919-TTZ7C namespace. The maintainer accepted the evaluated branch tip
+061571e48c453e5f3d7086a33af0d94926b2f7ea on 2026-09-19. Integration is pending
+a separate decision; no cycle is active. Implementation and acceptance are complete:
+118 regression tests and focused lint pass; EVD-20260919-TTZ7C-41 records six
+new regression cases and the restored contracts. The production change adds
+18 net lines across runtime, inspection and administrative recovery.
+
+Previously accepted Spiral cycle: `.spiral/cycles/CYC-20260919-TTZ7C-31.md` (`Readable
 Store Runtime And Dependency Maintenance`), opened on
 `spiral/CYC-20260919-TTZ7C-31-runtime-boundaries` from `master` at
 `e31e07c9bc8d4fc6458da1d213609dbf1aa4a7a2`. It deliberately precedes the
@@ -27,7 +41,7 @@ exposed by the accepted durability cycle. Its source, understanding, request and
 design are `SRC-20260919-TTZ7C-28`, `UND-20260919-TTZ7C-29`,
 `REQ-20260919-TTZ7C-30` and `DES-20260919-TTZ7C-32`. The maintainer accepted the
 cycle on 2026-09-19. The accepted branch was integrated locally into `master` at
-`0d23ed0354fb9f1285d9bc3b15c0a1089583d65b`; no new cycle is active.
+`0d23ed0354fb9f1285d9bc3b15c0a1089583d65b`; the correction cycle above is accepted and awaits integration.
 
 Accepted-cycle outcome: `IMP-20260919-TTZ7C-33` moves
 opened-store state and lifecycle into one cohesive `StoreRuntime`, leaving

.spiral/requests/REQ-20260919-TTZ7C-39.md

@@ -0,0 +1,16 @@
+# Request: Correct And Clarify Runtime Boundaries
+
+Retain the accepted architecture while correcting the reviewed regressions.
+
+| Criterion | Required evidence |
+| --- | --- |
+| R1 Closure | Every overlapping/repeated close waits for the same cleanup, including any failure. SIGTERM followed by SIGINT must wait for active commands, release healthy ownership and exit successfully only after completion. |
+| R2 Acceptance | If storage fails during persistence, no new success acknowledgment or queue insertion follows. Retain written evidence, reject subsequent admission and keep ownership. |
+| R3 Compatibility | Parsed commands with a valid existing ID return the current status before new-command name validation. Incomplete new commands still return 422 and write nothing. |
+| R4 Readability | Inspection and approved-command recovery coordinators express phases at a consistent abstraction level; parsing, persistence and prefix bookkeeping belong in cohesive supporting methods. No new class hierarchy or general infrastructure. |
+| R5 Preservation | Log order, durable barriers, query publication, recovery predicates, audit reports and lock retention remain covered by existing regression suites. No disk-format or public endpoint changes. |
+| R6 Review boundary | Record the already requested AGENTS.md acceptance/integration clarification. Finish at evaluation; human acceptance and integration remain separate. |
+
+Use deterministic runtime interleavings and a real subprocess signal test in
+addition to the existing suites. Test awaited outcomes, not promise identity or
+method names. Readability needs human/code review as well as behavioral evidence.