From b299e3738e73043650453ad8008dcc6576822619 Mon Sep 17 00:00:00 2001 From: Erik Date: Mon, 27 Jul 2026 07:39:56 +0200 Subject: [PATCH] docs: close modern runtime slice K1 --- AGENTS.md | 14 ++- CLAUDE.md | 14 ++- docs/architecture/acdream-architecture.md | 5 +- docs/plans/2026-04-11-roadmap.md | 21 ++-- docs/plans/2026-05-12-milestones.md | 10 +- .../2026-07-26-modern-runtime-slice-k.md | 18 +++- ...-07-27-slice-k1-single-session-headless.md | 100 ++++++++++++++++++ 7 files changed, 164 insertions(+), 18 deletions(-) create mode 100644 docs/research/2026-07-27-slice-k1-single-session-headless.md diff --git a/AGENTS.md b/AGENTS.md index d69cdda9..4c925b67 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -354,8 +354,13 @@ Linux headless/multi-session implementation is active. K0 completed at `aada8a37`: `AcDream.Headless` references only Runtime, strict no-connect validation and dependency/loaded-assembly guards pass, and the local Ubuntu closure passes 600 Core.Net, 119 Content, 395 Runtime, and 12 Headless tests. -K1 portable paths, redacted credentials, and the production single-session -host are active. +K1 completed at `f8cb840f`: portable XDG/Windows paths, strict config, +redacted credentials, direct Runtime command/entity/portal routes, and the +production single-session host pass the same real ACE connect, portal, +graceful-reconnect, and terminal-teardown gate on Windows and Linux/WSL. +Runtime tests pass 402/402, Headless tests pass 25/25, the complete Windows +Release suite passes 8,728/5 skips, and K2 absolute-deadline scheduler plus +typed bot-command parity is active. J0's rollback is `git revert b632672e5ccabfb44c551e08f1c411ab2669c44a`. J1's rollback is @@ -414,6 +419,8 @@ J8's rollback is `git revert a9a822f206cc6021bc099988144488f3bd7c397b`. K0's rollback is `git revert aada8a37c1e933f9f0a3f41dc4f05615b01023bc`. +K1's rollback is +`git revert f8cb840fb15b27f61afa5c33cad6c4dba8584949`. 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 @@ -443,7 +450,8 @@ closeout is `docs/research/2026-07-26-slice-j7-game-runtime-root-cutover.md`; J8/Slice-J closeout is `docs/research/2026-07-27-slice-j8-no-window-closeout.md`; K0 closeout is -`docs/research/2026-07-27-slice-k0-portability-boundary.md`; Slice K executes +`docs/research/2026-07-27-slice-k0-portability-boundary.md`; K1 closeout is +`docs/research/2026-07-27-slice-k1-single-session-headless.md`; Slice K executes from `docs/plans/2026-07-26-modern-runtime-slice-k.md`. The exact G4 visual rollback is `git revert ef1d263337997bb030eadb7b8e71d73dc659907a`; do not revert G3 or diff --git a/CLAUDE.md b/CLAUDE.md index 10cd6f99..3e9e6362 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -352,8 +352,13 @@ Linux headless/multi-session implementation is active. K0 completed at `aada8a37`: `AcDream.Headless` references only Runtime, strict no-connect validation and dependency/loaded-assembly guards pass, and the local Ubuntu closure passes 600 Core.Net, 119 Content, 395 Runtime, and 12 Headless tests. -K1 portable paths, redacted credentials, and the production single-session -host are active. +K1 completed at `f8cb840f`: portable XDG/Windows paths, strict config, +redacted credentials, direct Runtime command/entity/portal routes, and the +production single-session host pass the same real ACE connect, portal, +graceful-reconnect, and terminal-teardown gate on Windows and Linux/WSL. +Runtime tests pass 402/402, Headless tests pass 25/25, the complete Windows +Release suite passes 8,728/5 skips, and K2 absolute-deadline scheduler plus +typed bot-command parity is active. J0's rollback is `git revert b632672e5ccabfb44c551e08f1c411ab2669c44a`. J1's rollback is @@ -412,6 +417,8 @@ J8's rollback is `git revert a9a822f206cc6021bc099988144488f3bd7c397b`. K0's rollback is `git revert aada8a37c1e933f9f0a3f41dc4f05615b01023bc`. +K1's rollback is +`git revert f8cb840fb15b27f61afa5c33cad6c4dba8584949`. 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 @@ -441,7 +448,8 @@ closeout is `docs/research/2026-07-26-slice-j7-game-runtime-root-cutover.md`; J8/Slice-J closeout is `docs/research/2026-07-27-slice-j8-no-window-closeout.md`; K0 closeout is -`docs/research/2026-07-27-slice-k0-portability-boundary.md`; Slice K executes +`docs/research/2026-07-27-slice-k0-portability-boundary.md`; K1 closeout is +`docs/research/2026-07-27-slice-k1-single-session-headless.md`; Slice K executes from `docs/plans/2026-07-26-modern-runtime-slice-k.md`. The exact G4 visual rollback is `git revert ef1d263337997bb030eadb7b8e71d73dc659907a`; do not revert G3 or diff --git a/docs/architecture/acdream-architecture.md b/docs/architecture/acdream-architecture.md index 9cb9d27c..1aea9ce5 100644 --- a/docs/architecture/acdream-architecture.md +++ b/docs/architecture/acdream-architecture.md @@ -249,8 +249,11 @@ src/ AcDream.Headless/ Linux/Windows no-window production host Program.cs -> CLI entry only Configuration/ -> strict versioned process/session config + Credentials/ -> redacted env/stdin/owner-only-file providers + Hosting/ -> one GameRuntime/session/lease/policy lifetime + Policies/ -> typed Runtime-view/command consumers -> references Runtime only; no presentation/backend package - -> K0 complete; K1 single-session host active + -> K0/K1 complete; K2 scheduler and full bot-command parity active AcDream.Plugin.Abstractions/ Layer 5: plugin interfaces IAcDreamPlugin.cs -> done diff --git a/docs/plans/2026-04-11-roadmap.md b/docs/plans/2026-04-11-roadmap.md index 643032ec..831ca2d7 100644 --- a/docs/plans/2026-04-11-roadmap.md +++ b/docs/plans/2026-04-11-roadmap.md @@ -1,6 +1,6 @@ # acdream — strategic roadmap -**Status:** Living document. Updated 2026-07-27. **M3 landed; M4 is active.** M3's retail casting/UI, R6 locomotion/collision/projectile/teleport/radar rebaseline, deterministic fresh-login/portal world lifecycle, and final two-client portal observer flow are user-gated. All eight slices of the behavior-preserving ownership campaign in [`docs/architecture/code-structure.md`](../architecture/code-structure.md), their automated closeout, and the user's connected visual matrix are complete. Modern Runtime J3 canonical entity/object lifetime and J4 gameplay-state ownership are closed at `89e6b207`; J5.1 canonical selection/combat/target-mode ownership is closed at `b298f99f`, J5.2 interaction transactions at `f5f7b417`, J5.3 combat/magic intent at `20df9d15`, J5.4 local movement/outbound cadence at `aa3f4a60`, J5.5 per-session physics/remote simulation at `7e6033d0`, J5.6 projectile simulation at `2aee3356`, and J5.7 combined simulation closeout at `cdee7a4b`. J6.1 world-environment ownership is closed at `902076c0`; J6.2 canonical reveal generation and typed destination readiness is closed at `a6860d55` plus `acb845d8`; J6.3 exact F751/Position destination correlation is closed at `6a063a27`; J6.4 exact graphical-host acknowledgement and owner cleanup is closed at `18d17d8b`. J7's one graphical `GameRuntime` root is closed at `ce41efb9`, including the user's 2026-07-27 exact post-cutover visual acceptance. J8 closed Slice J at `a9a822f2` with one shared graphical/no-window root and generation-reset transaction. Slice K Linux headless/multi-session work is active; K0's tested no-presentation Windows/Linux boundary closed at `aada8a37` and K1 is active. Issue #225's lifestone/particle alpha comparison remains a separate rendering visual gate. +**Status:** Living document. Updated 2026-07-27. **M3 landed; M4 is active.** M3's retail casting/UI, R6 locomotion/collision/projectile/teleport/radar rebaseline, deterministic fresh-login/portal world lifecycle, and final two-client portal observer flow are user-gated. All eight slices of the behavior-preserving ownership campaign in [`docs/architecture/code-structure.md`](../architecture/code-structure.md), their automated closeout, and the user's connected visual matrix are complete. Modern Runtime J3 canonical entity/object lifetime and J4 gameplay-state ownership are closed at `89e6b207`; J5.1 canonical selection/combat/target-mode ownership is closed at `b298f99f`, J5.2 interaction transactions at `f5f7b417`, J5.3 combat/magic intent at `20df9d15`, J5.4 local movement/outbound cadence at `aa3f4a60`, J5.5 per-session physics/remote simulation at `7e6033d0`, J5.6 projectile simulation at `2aee3356`, and J5.7 combined simulation closeout at `cdee7a4b`. J6.1 world-environment ownership is closed at `902076c0`; J6.2 canonical reveal generation and typed destination readiness is closed at `a6860d55` plus `acb845d8`; J6.3 exact F751/Position destination correlation is closed at `6a063a27`; J6.4 exact graphical-host acknowledgement and owner cleanup is closed at `18d17d8b`. J7's one graphical `GameRuntime` root is closed at `ce41efb9`, including the user's 2026-07-27 exact post-cutover visual acceptance. J8 closed Slice J at `a9a822f2` with one shared graphical/no-window root and generation-reset transaction. Slice K Linux headless/multi-session work is active; K0's tested no-presentation Windows/Linux boundary closed at `aada8a37`, K1's real portable single-session host closed at `f8cb840f`, and K2 scheduler/bot-command parity is active. Issue #225's lifestone/particle alpha comparison remains a separate rendering visual gate. **Purpose:** One source of truth for where the project is and where it's going. Every observed defect or missing feature has a named phase that owns it; when something looks wrong in-game, look here to find the phase that'll address it. Implementation details live in per-phase specs under `docs/superpowers/specs/`, not in this file. --- @@ -1800,7 +1800,12 @@ port in any phase — no separate listing here. > exact post-cutover visual matrix on 2026-07-27. J8 closed Slice J at > `a9a822f2`: 395 Runtime tests, 3,731 App tests / 3 skips, 8,696 complete- > solution tests / 5 skips, lifecycle/reconnect, and canonical nine-stop gates -> pass. Slice K Linux headless/multi-session implementation is active. +> pass. Slice K Linux headless/multi-session implementation is active. K0's +> portable no-presentation boundary closed at `aada8a37`; K1's production +> single-session Windows/Linux host closed at `f8cb840f` after both platforms +> completed the same real ACE connect, portal, graceful reconnect, and terminal +> teardown gate. K2's absolute-deadline scheduler and full typed bot-command +> parity are active. > The historical exact cutover > rollback remains > `git revert ef1d263337997bb030eadb7b8e71d73dc659907a`. Slice H is complete: @@ -1841,13 +1846,13 @@ hitch and follows. --- -### Track LH — Linux and headless automation (future; user-directed 2026-07-19) +### Track LH — Linux and headless automation (active; user-directed 2026-07-19) -> **PARKED / FUTURE — not part of active M3.** Preserve this direction for -> deliberate architectural work after the current gameplay and UI milestones: -> a graphical Linux client, configurable retail-rooted distance LOD, and a true -> Linux headless host capable of running roughly 30 automated clients with -> minimal CPU and memory use. +> **PROMOTED TO ACTIVE MODERN RUNTIME SLICES K/L.** Slice K now executes the +> no-window Linux host and approximately 30-session target from +> [`2026-07-26-modern-runtime-slice-k.md`](2026-07-26-modern-runtime-slice-k.md); +> Slice L executes the graphical Linux/platform work. K0/K1 are complete and +> K2 is active. The historical LH rows below remain the stable outcome map. The governing architectural rule is that a game session must not be a hidden `GameWindow`. Authentication, networking, world state, movement, inventory, diff --git a/docs/plans/2026-05-12-milestones.md b/docs/plans/2026-05-12-milestones.md index 862f4961..9b44a299 100644 --- a/docs/plans/2026-05-12-milestones.md +++ b/docs/plans/2026-05-12-milestones.md @@ -284,8 +284,14 @@ residency is `0/0/0` at every stable checkpoint and teardown converges. Slice I dependency boundary, strict no-connect validation, and Windows/Ubuntu CI. Local Ubuntu gates pass 600 Core.Net, 119 Content, 395 Runtime, and 12 Headless tests; the Windows Release solution passes 8,708 tests / 5 skips. - K1 portable paths, credentials, and the production single-session host are - active. + K1 completed at `f8cb840f`: portable XDG/Windows paths, strict versioned + config, redacted credentials, the direct Runtime command/entity/portal + routes, and the production single-session host passed the same real ACE + connect/portal/graceful-reconnect/teardown gate on Windows and Linux/WSL. + The complete Windows Release suite passes 8,728 tests / 5 skips; the Linux + portable closure passes 600 Core.Net, 119 Content, 402 Runtime, and 25 + Headless tests. K2's absolute-deadline scheduler and complete typed bot API + parity are active. Slice-I closeout evidence is [`../research/2026-07-25-slice-i7-closeout.md`](../research/2026-07-25-slice-i7-closeout.md). Slice-J2 closeout evidence is diff --git a/docs/plans/2026-07-26-modern-runtime-slice-k.md b/docs/plans/2026-07-26-modern-runtime-slice-k.md index 4793ed67..9e3f17c4 100644 --- a/docs/plans/2026-07-26-modern-runtime-slice-k.md +++ b/docs/plans/2026-07-26-modern-runtime-slice-k.md @@ -1,6 +1,6 @@ # Modern runtime Slice K — Linux headless and multi-session host -**Status:** K0 COMPLETE; K1 ACTIVE 2026-07-27 +**Status:** K0–K1 COMPLETE; K2 ACTIVE 2026-07-27 **Parent:** `2026-07-24-modern-runtime-architecture.md`, Slice K **Authorization:** the user approved Slices F–L on 2026-07-24 **Purpose:** run efficient automated clients on Linux without a display, GPU, @@ -235,6 +235,22 @@ configuration validation without a graphical/audio/native-window dependency. ### K1 — portable config, credentials, and single-session CLI +**Complete at `f8cb840f`.** The strict versioned configuration, XDG/Windows +path owner, redacted environment/stdin/owner-only-file credentials, typed +direct Runtime command route, canonical presentation-free inbound entity and +portal route, production single-session host, deterministic exit codes, +Ctrl+C/SIGTERM cancellation, and retryable teardown transaction are live. +The explicit `lifecycle-smoke` policy proves connect, enter, inbound state, +chat, lifestone recall, portal completion/LoginComplete, graceful stop, +reconnect, second-generation materialization, and terminal convergence. + +Windows and Linux/WSL both passed that sequence against the same local ACE +server. ACE retains its account/session index for roughly two seconds after +confirming CharacterLogOff, so K1 gives the retiring production connection a +one-time 2.5-second quiescence suffix before replacement. This is not a +steady-state scheduler sleep; K2 replaces it with an absolute-deadline +scheduler transition. + - Implement portable paths and versioned strict config. - Implement redacted credential providers. - Compose one `GameRuntime`, one `LiveSessionHost`, one command adapter, one diff --git a/docs/research/2026-07-27-slice-k1-single-session-headless.md b/docs/research/2026-07-27-slice-k1-single-session-headless.md new file mode 100644 index 00000000..3fb7268e --- /dev/null +++ b/docs/research/2026-07-27-slice-k1-single-session-headless.md @@ -0,0 +1,100 @@ +# Slice K1 — portable single-session headless closeout + +**Date:** 2026-07-27 +**Implementation:** `f8cb840fb15b27f61afa5c33cad6c4dba8584949` +**Status:** COMPLETE + +## Outcome + +`AcDream.Headless` is now a production, presentation-free Windows/Linux host +for one real ACE session. It constructs the same canonical `GameRuntime` used +by the graphical client and adds no bot-specific world model. + +The host owns one runtime, one host lease, one `LiveSessionHost`, one direct +typed command adapter, one policy subscription, one erasable credential, and +one retryable teardown cursor. Runtime owns the character, entity/object, +inventory, communication, action, physics, environment, and portal state. + +## Shipped mechanisms + +- Strict version-1 JSON configuration with rejected unknown fields. +- Windows special-folder and Linux XDG config/data/cache paths with normalized + command-line overrides. +- Environment, standard-input, and credential-file providers. Linux file + credentials reject symlinks and require owner-read with no group/other + permissions. Passwords are not accepted on the command line or emitted in + diagnostics. +- Character selection by active index, GUID, or case-insensitive name. +- `run` and `validate` CLI modes, stable exit codes, Ctrl+C, and Unix SIGTERM. +- `DirectGameRuntimeCommandAdapter` with generation-gated routes. K1 supports + session lifecycle, Say/Tell, and the four recall commands; K2 completes the + remaining typed gameplay commands through this same adapter. +- `RuntimeLiveEntitySessionController`, which commits inbound create/update/ + delete/pickup and portal state directly into Runtime without App, UI, + rendering, audio, or a parallel GUID map. +- Exact headless portal readiness/materialization/host acknowledgements and + LoginComplete. A no-window host has no graphical resource debt to await. +- Structured JSON lifecycle/resource/failure diagnostics containing only + exception types and redacted credential identities. +- `idle` policy and explicit `lifecycle-smoke` connected-gate policy. + +## Reconnect finding + +ACE confirms CharacterLogOff before its account/session index releases the +retiring socket. Reconnecting about 350 ms later causes ACE to evict the old +session and reject the replacement as Account In Use; the index disappears +about two seconds later. + +K1 therefore performs an explicit stop, verifies the complete teardown +acknowledgement, and gives production reconnect a one-time 2.5-second +quiescence suffix. Injected deterministic tests use zero delay. This is a +connection-lifecycle boundary, not a steady scheduler loop. K2 moves the wait +to the monotonic absolute-deadline scheduler. + +## Automated gates + +- Windows Runtime: 402/402. +- Windows Headless: 25/25. +- Windows complete Release solution: 8,728 passed / 5 intentional skips. +- Ubuntu/WSL portable closure: + - Core.Net 600/600 + - Content 119/119 + - Runtime 402/402 + - Headless 25/25 +- Linux-only credential permission and symlink gates pass. +- Dependency and loaded-assembly guards continue to prove no App, UI, Silk, + ImGui, OpenAL, or graphical backend is loaded. + +## Connected gates + +Both Windows and Linux/WSL connected to the local ACE server and completed: + +1. authenticate and select the configured character; +2. enter world and receive the CreateObject stream; +3. issue harmless local speech; +4. send lifestone recall; +5. accept the exact teleport destination; +6. complete Runtime reveal, host acknowledgements, and LoginComplete; +7. request and confirm graceful logout; +8. reconnect after ACE quiescence; +9. enter the second generation; +10. gracefully stop and converge every Runtime ownership ledger. + +Both processes exited with code zero. No presentation assembly or device was +loaded. + +## K2 carry + +- Replace K1's 15 ms single-session loop and one-time blocking reconnect suffix + with one monotonic absolute-deadline scheduler. +- Complete the remaining typed movement, selection, interaction, combat, + magic, inventory, character, and social operations on the existing adapter. +- Serialize each session's accepted inbound turn and compare graphical versus + headless packet order/cadence. +- Preserve one runtime and one mutable owner graph per session. + +## Rollback + +```text +git revert f8cb840fb15b27f61afa5c33cad6c4dba8584949 +```