From f84624b1e9b83f928debdbe65a5a1576b999ee34 Mon Sep 17 00:00:00 2001 From: Erik Date: Sat, 25 Jul 2026 19:16:30 +0200 Subject: [PATCH] docs(runtime): close J1 contract gate Record the exact-binary connected lifecycle/reconnect acceptance, synchronized active pointers, rollback, and durable evidence before session ownership moves in J2. --- AGENTS.md | 14 +++- CLAUDE.md | 14 +++- docs/ISSUES.md | 4 +- docs/architecture/acdream-architecture.md | 5 +- docs/plans/2026-04-11-roadmap.md | 9 ++- docs/plans/2026-05-12-milestones.md | 11 ++- .../2026-07-24-modern-runtime-architecture.md | 7 +- .../2026-07-25-modern-runtime-slice-j.md | 28 +++++++- ...7-25-slice-j1-runtime-contract-closeout.md | 70 +++++++++++++++++++ 9 files changed, 146 insertions(+), 16 deletions(-) create mode 100644 docs/research/2026-07-25-slice-j1-runtime-contract-closeout.md diff --git a/AGENTS.md b/AGENTS.md index 6661957d..711e3ab9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -192,8 +192,17 @@ cutover rollback is is `git revert 82f8d4f82e24ad85042ac3e25c4f6464bebce758`. Slice J0 is complete at `b632672e`: `AcDream.Runtime` now provides the enforced presentation-independent assembly boundary without moving gameplay behavior. -Four dependency guards pass. J1 is active. J0's rollback is +Four dependency guards pass. J1 is complete at `854d9e9c`: borrowed runtime +views, typed synchronous commands, ordered deltas, the instance clock, +generation/lifecycle contracts, and teardown acknowledgements project the same +canonical App owners without a mirror or extra frame. Runtime tests pass 13/13, +App tests pass 3,838/3 skips, the complete Release suite passes 8,424/5 skips, +and the exact-binary seven-checkpoint connected lifecycle/reconnect gate passes +with graceful exits. J2 session lifetime and ordered transport extraction is +active. J0's rollback is `git revert b632672e5ccabfb44c551e08f1c411ab2669c44a`. +J1's rollback is +`git revert 854d9e9cd13092bd5aaa3cf025d73eeb4600e9f8`. Slice H's retained UI/frame, bounded-light, and pooled/borrowed/direct network work is complete; the exact seven-checkpoint connected lifecycle/reconnect gate passes. Slice I is closed in @@ -209,7 +218,8 @@ the portal-warmup corrections. Evidence: `docs/research/2026-07-25-slice-i4-flat-bsp-differential.md` and `docs/research/2026-07-25-slice-i5-dual-collision-shadow.md` and `docs/research/2026-07-25-slice-i6-flat-production-cutover.md` and -`docs/research/2026-07-25-slice-i7-closeout.md`. +`docs/research/2026-07-25-slice-i7-closeout.md` and +`docs/research/2026-07-25-slice-j1-runtime-contract-closeout.md`. **Structural prerequisite before new M4 subsystem work:** all eight behavior-preserving `GameWindow` decomposition slices and the automated diff --git a/CLAUDE.md b/CLAUDE.md index 72e67d51..fdb75948 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -190,8 +190,17 @@ cutover rollback is is `git revert 82f8d4f82e24ad85042ac3e25c4f6464bebce758`. Slice J0 is complete at `b632672e`: `AcDream.Runtime` now provides the enforced presentation-independent assembly boundary without moving gameplay behavior. -Four dependency guards pass. J1 is active. J0's rollback is +Four dependency guards pass. J1 is complete at `854d9e9c`: borrowed runtime +views, typed synchronous commands, ordered deltas, the instance clock, +generation/lifecycle contracts, and teardown acknowledgements project the same +canonical App owners without a mirror or extra frame. Runtime tests pass 13/13, +App tests pass 3,838/3 skips, the complete Release suite passes 8,424/5 skips, +and the exact-binary seven-checkpoint connected lifecycle/reconnect gate passes +with graceful exits. J2 session lifetime and ordered transport extraction is +active. J0's rollback is `git revert b632672e5ccabfb44c551e08f1c411ab2669c44a`. +J1's rollback is +`git revert 854d9e9cd13092bd5aaa3cf025d73eeb4600e9f8`. Slice H's retained UI/frame, bounded-light, and pooled/borrowed/direct network work is complete; the exact seven-checkpoint connected lifecycle/reconnect gate passes. Slice I is closed in @@ -207,7 +216,8 @@ the portal-warmup corrections. Evidence: `docs/research/2026-07-25-slice-i4-flat-bsp-differential.md` and `docs/research/2026-07-25-slice-i5-dual-collision-shadow.md` and `docs/research/2026-07-25-slice-i6-flat-production-cutover.md` and -`docs/research/2026-07-25-slice-i7-closeout.md`. +`docs/research/2026-07-25-slice-i7-closeout.md` and +`docs/research/2026-07-25-slice-j1-runtime-contract-closeout.md`. **Structural prerequisite before new M4 subsystem work:** all eight behavior-preserving `GameWindow` decomposition slices and the automated diff --git a/docs/ISSUES.md b/docs/ISSUES.md index ff89058c..bbe97e72 100644 --- a/docs/ISSUES.md +++ b/docs/ISSUES.md @@ -63,7 +63,9 @@ What does NOT go here: production parsed collision graphs after exact flat differential and user collision acceptance; 8,413 Release tests / 5 skips and both exact-binary connected routes pass with `0/0/0` graph residency. J0's enforced - presentation-independent project boundary is live and J1 is active from + presentation-independent project boundary and J1's borrowed + view/command/event/lifecycle contract are live; J2 session lifetime and + ordered transport extraction is active from [`plans/2026-07-25-modern-runtime-slice-j.md`](plans/2026-07-25-modern-runtime-slice-j.md). The [documentation map](README.md) defines how this tactical ledger relates to diff --git a/docs/architecture/acdream-architecture.md b/docs/architecture/acdream-architecture.md index cf590d75..72d8302b 100644 --- a/docs/architecture/acdream-architecture.md +++ b/docs/architecture/acdream-architecture.md @@ -204,7 +204,10 @@ src/ Messages/ -> done (CreateObject, MoveToState, etc.) AcDream.Runtime/ presentation-independent client kernel boundary - RuntimeAssemblyMarker.cs -> J0 dependency boundary; J1 contracts active + RuntimeAssemblyMarker.cs -> J0 dependency boundary + GameRuntime*.cs -> J1 borrowed views, synchronous commands, + ordered deltas, clock, generation + teardown + -> J2 session lifetime and ordered transport extraction active -> may reference Core, Core.Net, Content, and Plugin.Abstractions only -> must never reference App, UI, Silk.NET, OpenAL, Arch, or ImGui diff --git a/docs/plans/2026-04-11-roadmap.md b/docs/plans/2026-04-11-roadmap.md index 3328b099..b4d8b63f 100644 --- a/docs/plans/2026-04-11-roadmap.md +++ b/docs/plans/2026-04-11-roadmap.md @@ -1673,14 +1673,19 @@ port in any phase — no separate listing here. > skips plus both exact-binary connected routes; every stable checkpoint > reports `0/0/0` graph residency while flat assets remain populated. J0 > established the presentation-independent Runtime boundary with four enforced -> dependency guards; J1 is now active. +> dependency guards. J1 now provides borrowed views, typed press-time commands, +> ordered deltas, an instance clock, generation/lifecycle state, and teardown +> acknowledgements over the same canonical owners. Its 13 Runtime tests, 3,838 +> App tests / 3 skips, 8,424-test / 5-skip complete Release suite, and exact- +> binary seven-checkpoint lifecycle/reconnect gate pass with graceful exits. +> J2 is now active. > The historical exact cutover > rollback remains > `git revert ef1d263337997bb030eadb7b8e71d73dc659907a`. Slice H is complete: > retained UI/frame work, exact bounded light selection, and > pooled/borrowed/direct network I/O pass 8,292 Release tests / 5 skips and the > connected lifecycle/reconnect gate. Slice I is closed in -> [its detailed plan](2026-07-25-modern-runtime-slice-i.md); Slice J1 executes +> [its detailed plan](2026-07-25-modern-runtime-slice-i.md); Slice J2 executes > from [its lifetime-group plan](2026-07-25-modern-runtime-slice-j.md). **Spec:** `docs/superpowers/specs/2026-07-05-modern-pipeline-design.md` (the diff --git a/docs/plans/2026-05-12-milestones.md b/docs/plans/2026-05-12-milestones.md index e8e03a46..441e0631 100644 --- a/docs/plans/2026-05-12-milestones.md +++ b/docs/plans/2026-05-12-milestones.md @@ -147,9 +147,14 @@ Following user collision acceptance, `82f8d4f8` removed every production parsed collision graph. Slice I7 passes 8,413 Release tests / 5 skips and both exact-binary connected lifecycle/reconnect and nine-stop routes; parsed graph residency is `0/0/0` at every stable checkpoint and teardown converges. Slice I -is complete. Slice J0 established and enforced the presentation-independent -`AcDream.Runtime` boundary without moving behavior; J1 is active under -[`2026-07-25-modern-runtime-slice-j.md`](2026-07-25-modern-runtime-slice-j.md). + is complete. Slice J0 established and enforced the presentation-independent + `AcDream.Runtime` boundary. J1 added borrowed views, typed synchronous + commands, ordered events, an instance clock, generation/lifecycle contracts, + and teardown acknowledgements without moving a canonical owner. Runtime + tests pass 13/13, App tests pass 3,838/3 skips, the full Release suite passes + 8,424/5 skips, and the exact-binary seven-checkpoint connected gate exits + gracefully. J2 session lifetime and ordered transport extraction is active under + [`2026-07-25-modern-runtime-slice-j.md`](2026-07-25-modern-runtime-slice-j.md). Slice-I closeout evidence is [`../research/2026-07-25-slice-i7-closeout.md`](../research/2026-07-25-slice-i7-closeout.md). The historical exact G4 visual rollback remains diff --git a/docs/plans/2026-07-24-modern-runtime-architecture.md b/docs/plans/2026-07-24-modern-runtime-architecture.md index fe65880b..6407760e 100644 --- a/docs/plans/2026-07-24-modern-runtime-architecture.md +++ b/docs/plans/2026-07-24-modern-runtime-architecture.md @@ -5,8 +5,9 @@ **Status:** Slices A–I are complete. Flat-authoritative collision, zero- allocation resolve scratch, parsed-graph removal, connected correctness/ lifetime acceptance, and Slice-I closeout landed 2026-07-25. Slices F–L were -explicitly approved 2026-07-24. Slice J0's dependency-boundary preparation is -complete without moving gameplay owners; J1 is the active execution point. +explicitly approved 2026-07-24. Slice J0–J1 established the enforced Runtime +boundary and the borrowed view/command/event seam without moving canonical +gameplay owners; J2 is the active execution point. **Scope:** Reconcile and sequence the existing Modern Pipeline (`MP`) and Linux/headless (`LH`) tracks using the 2026-07-24 connected performance audit. @@ -1271,7 +1272,7 @@ honest metrics + committed baselines (A — exit criteria block C) -> delta GPU submission (G) -> residual frame cleanup (H-a, H-b, H-c) -> flat collision assets (I — COMPLETE) - -> presentation-independent runtime (J — CURRENT at J1) + -> presentation-independent runtime (J — CURRENT at J2) -> Linux/headless/multi-session (K) -> evidence-gated GPU jobs (L) ``` diff --git a/docs/plans/2026-07-25-modern-runtime-slice-j.md b/docs/plans/2026-07-25-modern-runtime-slice-j.md index d170a1c9..4d713f29 100644 --- a/docs/plans/2026-07-25-modern-runtime-slice-j.md +++ b/docs/plans/2026-07-25-modern-runtime-slice-j.md @@ -1,7 +1,7 @@ # Modern runtime Slice J — presentation-independent runtime -**Status:** J0 COMPLETE — lifetime plan, project boundary, and dependency -guards; Slice I is closed and J1 is ACTIVE +**Status:** J0–J1 COMPLETE — lifetime boundary plus borrowed view, command, +event, clock, generation, and teardown contracts; J2 is ACTIVE **Parent:** `2026-07-24-modern-runtime-architecture.md`, Slice J **Authorization:** the user approved Slices F–L, including the otherwise-frozen Slice J gameplay-owner moves, on 2026-07-24 @@ -103,6 +103,8 @@ git revert b632672e5ccabfb44c551e08f1c411ab2669c44a ### J1 — read, command, event, clock, and lifecycle contracts +**Completed 2026-07-25 at `854d9e9c`.** + - Define `IGameRuntimeView`, typed command interfaces, ordered event/delta records, instance clock, lifecycle states, generation tokens, and teardown acknowledgements. @@ -117,6 +119,28 @@ Gate: adapter and direct-host traces are identical over deterministic session, entity, inventory, chat, movement, and portal fixtures; no canonical owner has moved yet. +Result: + +- `AcDream.Runtime` owns immutable borrowed-view contracts, typed commands, + ordered deltas, an instance clock, generation tokens, lifecycle snapshots, + and retryable teardown acknowledgements. +- Focused App adapters borrow the current canonical owners. They create no + second GUID map, state store, command queue, or frame boundary. +- Startup plus press-time selection, movement, and combat input now traverse + the typed command seam synchronously and still mutate the exact same owners. +- Runtime tests pass 13/13, App tests pass 3,838 with three skips, and the + complete Release solution passes 8,424 tests with five skips. +- The exact-binary connected gate at + `logs/connected-world-gate-20260725-190953/report.json` passed six capped + world checkpoints plus a fresh uncapped reconnect. Both processes exited + gracefully with no failures. + +Exact rollback: + +```text +git revert 854d9e9cd13092bd5aaa3cf025d73eeb4600e9f8 +``` + ### J2 — session lifetime and ordered transport group - Remove App presentation dependencies from `LiveSessionController`, diff --git a/docs/research/2026-07-25-slice-j1-runtime-contract-closeout.md b/docs/research/2026-07-25-slice-j1-runtime-contract-closeout.md new file mode 100644 index 00000000..936a18d1 --- /dev/null +++ b/docs/research/2026-07-25-slice-j1-runtime-contract-closeout.md @@ -0,0 +1,70 @@ +# Modern runtime Slice J1 closeout + +## Result + +Slice J1 is complete at production commit +`854d9e9cd13092bd5aaa3cf025d73eeb4600e9f8`. + +`AcDream.Runtime` now defines the presentation-independent seams required +before ownership moves: + +- borrowed immutable entity, inventory, chat, movement, and portal views; +- generation-gated typed session, selection, combat, movement, chat, and + portal commands; +- ordered typed deltas and normalized parity traces; +- an instance-scoped frame/simulation clock; +- lifecycle snapshots, generation tokens, and retryable teardown + acknowledgements. + +The App implementation is deliberately an adapter over current canonical +owners. It does not copy mutable collections, add a command queue, own a +second GUID map, or add a frame of input latency. Startup and press-time input +reach the same session, selection, movement, and combat owners synchronously. +No gameplay owner moved in J1. + +## Automated acceptance + +At the production commit: + +- Runtime contract tests: 13 passed; +- App tests: 3,838 passed / 3 skipped; +- complete Release solution: 8,424 passed / 5 skipped; +- Release solution build: pass. + +The tests cover clock normalization/freeze and instance isolation, generation +and teardown semantics, event-sequencer isolation, trace normalization, +connected start through the adapter, borrowed live entity/inventory/chat/ +portal views, same-owner command mutation, ordered domain traces, stale +generation rejection, and complete stop acknowledgement. + +## Connected lifecycle acceptance + +Raw evidence: +`logs/connected-world-gate-20260725-190953/report.json`. + +Result: PASS on the exact production commit. + +- Capped process: login plus Aerlinthe, Rynthid, Facility Hub, Holtburg after + dungeon, and Aerlinthe revisit all completed. +- Fresh uncapped process: reconnect completed. +- Seven of seven checkpoints passed. +- Both processes exited gracefully with exit code zero. +- No gate failure was recorded. +- The only warning was 25 expected world-edge landblock misses. + +This connected run proves that routing the startup command through the J1 seam +did not alter live connection, world traversal, replacement, or shutdown +behavior. + +## Exact rollback + +```text +git revert 854d9e9cd13092bd5aaa3cf025d73eeb4600e9f8 +``` + +J0 remains independently reversible with: + +```text +git revert b632672e5ccabfb44c551e08f1c411ab2669c44a +``` +