docs: propose daemon module boundaries

[thymikee]

Summary

Propose an incremental daemon modularity architecture centered on narrow capability ports, daemon-owned adapters, and module façades for native replay, Maestro, and replay-test.

Adds measurable R7/R9/import-boundary migration ratchets, documents benefits and tradeoffs, and includes executable design probes. The revised session probe carries one private tagged aggregate through replay repair, operation-keyed platform close, failed publication, retry, and commit via separate replay and publication capability projections. Issue #1478 is now the explicit implementation handoff, with a do-not-implement warning beside the illustrative state sketch. Nine files are touched; there are no production-source or command-behavior changes.

Validation

Both boundary prototypes, formatting, typecheck, lint, tooling, layering, dependency graph, Fallow, build, and smoke gates pass. The complete unit suite passes with one worker: 523 files and 4,664 tests. The default parallel aggregate run hit seven known host-contention/global-cache flakes; all seven passed in focused isolation before the bounded complete run. Runtime device verification does not apply because this PR changes architecture documentation and throwaway design probes only.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-29 10:52 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.87 MB	1.87 MB	0 B
JS gzip	598.8 kB	598.8 kB	0 B
npm tarball	714.5 kB	714.6 kB	+45 B
npm unpacked	2.50 MB	2.50 MB	+252 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	26.7 ms	28.2 ms	+1.4 ms
CLI --help	57.9 ms	58.6 ms	+0.6 ms

Top changed chunks: no changes in the largest emitted chunks.

[thymikee]

Design blocker — The proposed ScriptPublicationState cannot preserve the repair close/commit transaction it claims to consolidate. Its repair variant omits the persisted output target and force authorization, committed state, and repairPlatformCloseReceipt. Today, after platform close succeeds, the receipt is stored before atomic publication; if publication fails, retry reuses that receipt rather than dispatching platform close again. explicit-close { platformCloseSucceeded } is an input event, not durable retry state, so the proposed aggregate either loses idempotency or leaves hidden parallel state behind. Model the explicit repair phases and durable fields—including target/force, close receipt, committed/abort state—state where they live, and pin the failure/retry transitions in the prototype before treating this as a migration target. Exact-head prototype and layering checks are green, but the design is not ready.

[thymikee]

Implementation handoff: #1478. It captures the post-review interface decisions, compatibility constraints, dependency-ordered worker briefs, STOP conditions, success metrics, and Phase 7 docs cleanup. Where it differs, #1478 supersedes the proposal's provisional TypeScript sketches and unanswered grilling section; the proposal's rationale, ADR constraints, measurements, tradeoffs, and probes remain the design context. No files in this reviewed seven-artifact PR were changed.

[thymikee]

Architecture blocker: #1478 contains the corrected implementation handoff, but this PR’s checked-in docs still present the incompatible ScriptPublicationState / explicit-close { platformCloseSucceeded } sketches as the revised recommendation, and the session probe claims repair completion without modeling durable close/publication retry state. A PR comment does not supersede versioned guidance. Replace/remove those sketches and adjust/remove the probe, or prominently mark the exact sections as superseded by #1478 with an explicit do-not-implement warning. Exact-head checks are green; #1478 remains unimplemented residual risk.

[thymikee]

Re-reviewed exact head ef1a71af: the prior architecture blocker is resolved. The proposal now makes #1478 authoritative, preserves durable target/per-target force state, capability-owned close sequencing, operation-keyed receipts, explicit terminal states, persist-before-publish ordering, same-key retry suppression/different-key redispatch, and failure-preserving retry semantics; the probes exercise the shared aggregate across failure and retry. No code/design finding remains. I am not applying ready-for-human because iOS Smoke is currently red: the fixture E2E timed out waiting for ‘Automation lab’ while the app remained on its home/Gesture surface. Targeted runner XCTest passed 10/10 and every other check is green, so this looks unrelated to the docs/prototype delta, but it still needs a rerun or owner CI disposition.