|
2 | 2 |
|
3 | 3 | ## Status |
4 | 4 |
|
5 | | -Completed (2026-08-27). Accepted for staged adoption on 2026-08-09, with a successful checkpoint on |
6 | | -2026-08-10 and broader-migration governance added on 2026-08-11. The historical checkpoint and |
7 | | -per-unit evidence in sections 7–10 explain how the transition was kept shippable; they no longer |
8 | | -authorize or schedule migration work. |
| 5 | +Completed (2026-08-27). Accepted on 2026-08-09. Completed process history is retained in git history. |
9 | 6 |
|
10 | 7 | Amended 2026-08-26 while closing the Wave 6 residue: `host` covers host-scoped platform work through |
11 | 8 | a narrow neutral typed service, not diagnostics alone. Host diagnostics, daemon-owner resource |
@@ -72,9 +69,6 @@ recreate the old root path. |
72 | 69 | host-scoped platform work through a neutral typed domain service: diagnostics, owner cleanup, or |
73 | 70 | managed tooling. The command binds no device runtime as its own execution shape, and any |
74 | 71 | device-runtime leg rides another command's declared use. |
75 | | -- During adoption, the first real slices paused for an explicit continue/revise/stop checkpoint. |
76 | | - Later units were move-dominated: platform mechanics left root `src/` for platform packages and |
77 | | - exceptional shipped-size growth required an individual justification. |
78 | 72 | - Evidence is tiered by what a unit imports: request-scoped device units prove facts, operations, |
79 | 73 | and parity cells; only durable-resource units carry the section 4–5 lifecycle evidence. |
80 | 74 | - A handler binds once with its execution use. Admission, `capabilities`, and doctor questions use |
@@ -573,204 +567,10 @@ shrinks the cycle lowers the zone ceilings in the same change rather than leavin |
573 | 567 |
|
574 | 568 | ### 7. Adoption checkpoint (historical) |
575 | 569 |
|
576 | | -No command migration beyond the metadata/package substrate and complete `devices`, `logs`, and |
577 | | -`network` command cutovers began until this ADR's Status recorded **continue**. `network` was included |
578 | | -because it consumes the app-log resource. Daemon-owned generic session teardown may invoke the |
579 | | -neutral app-log handle's forced-disposal contract without changing `close`'s legacy platform adapter; |
580 | | -the `logs` unit proves that path through `close`. If `close`, `open`, or another command instead must |
581 | | -bind a runtime or select app-log platform behavior, its full unit must be named in Status before the |
582 | | -substrate lands. `logs` is the deliberate first descriptor/reattachment pilot, not merely a |
583 | | -request-lifetime handle exercise. |
584 | | - |
585 | | -Before the substrate lands, the tracking issue records and reviews the exact commands, thresholds, |
586 | | -scenario denominator, and scoped counts used below. The same measures are reported from the clean |
587 | | -committed checkpoint tree. |
588 | | - |
589 | | -The checkpoint records exactly one outcome: |
590 | | - |
591 | | -- **continue**: every hard evidence item passes and broader command migration may proceed; |
592 | | -- **revise**: amend the contracts/ADR, rerun the checkpoint, and begin no further command migration; or |
593 | | -- **stop**: abandon broader migration; already-landed command units remain coherent or are retired by |
594 | | - a separate explicit decision. |
595 | | - |
596 | | -Any failed hard item requires **revise** or **stop**; recording evidence of the failure is not |
597 | | -evidence for **continue**. |
598 | | - |
599 | | -Evidence must cover: |
600 | | - |
601 | | -- one platform-execution path, an unchanged ADR 0003 route/policy projection, and zero old capability |
602 | | - closures, tags/maps, or concrete daemon platform imports for each migrated command; |
603 | | -- package direction and the absence of daemon request/session/command types in platform packages; |
604 | | -- independent package builds/declarations, metadata-eager/implementation-lazy loading, and reviewed |
605 | | - startup/build/package thresholds; |
606 | | -- typed runtime-use narrowing and a planted-red narrowing-gate violation; |
607 | | -- six-family runtime ownership, six local inventory sources, provider inventory sources, and |
608 | | - independently enumerated leaf/device/provider support parity and scenario counts; |
609 | | -- provider-first fail-closed behavior plus unique restart-stable exact-owner references; |
610 | | -- rollback after every partial bind acquisition and published-binding disposal without |
611 | | - persistent-helper shutdown; |
612 | | -- descriptor persistence and exact-owner recovery after loss of a process-local handle, including |
613 | | - validated decoding, resumed control for reattachable cells, executable descriptor-only cleanup, |
614 | | - and explicit cleanup-only/version-unreattachable behavior; |
615 | | -- pending-handle cleanup across every start/persist/adopt/transfer gap, durable-handle transfer, |
616 | | - serialized or native-atomic fencing, idempotent teardown, and operation/cleanup error precedence; |
617 | | -- semantic/provider/device parity for `devices`, `logs`, and `network`; |
618 | | -- unchanged-or-lower R7/R10, type-cycle, and external-daemon-type ratchets; and |
619 | | -- numeric before/after daemon platform import, branch, and tag counts with a strict net decrease. |
620 | | - |
621 | | -The seam is revised or stopped before broader migration if a platform package needs root/daemon or |
622 | | -sibling-platform imports; a command needs old/new or provider/local execution fallback; runtime |
623 | | -facets degenerate into tags, command switches, or opaque execution payloads; leaf/provider facts |
624 | | -require default fallthrough; `SessionState` names/exposes concrete platform/provider types or raw |
625 | | -mechanics rather than the permitted neutral live handle; a persisted record bypasses the validated |
626 | | -neutral envelope or facet-owned descriptor codec, or contains raw live mechanics; implementation |
627 | | -laziness cannot be preserved; R7/R10/type-cycle pressure grows; or the landed slices add more daemon |
628 | | -platform ownership than they remove. |
629 | | - |
630 | | -#### Checkpoint result: continue under the revised cumulative budget (2026-08-10) |
631 | | - |
632 | | -The final checkpoint compares `44c298d7f3a0ef84bc47f34c54d88b6c9eeb0df2` with stack head |
633 | | -`457fafe6399a95a4ddbfac57f02b3a7fe4157a54` on the same host and toolchain. Merged `devices` |
634 | | -`c06bed9f773a27ae0a02cb012570def2f2d0b90e` is part of that range; rebasing the remaining PRs onto it |
635 | | -does not reset the denominator. The earlier `99f5af1b7` checkpoint missed a stale owned-marker wedge, |
636 | | -Apple scoped-provider bypass, Android optional-recovery loss, and absolute network line-number |
637 | | -regression. The later cleanup review found a cross-device retained-marker wedge, a manual-recovery |
638 | | -hint that remained blocked until daemon restart, and an Android app-log stream that stayed pinned to |
639 | | -the pre-relaunch app PID. Each correction was observed red before its focused test passed; the final |
640 | | -admission test proves removal of the matching retained marker permits a second start in the same |
641 | | -daemon process. On exact final logs head `188795386`, a controlled Android relaunch moved the app from |
642 | | -PID 10952 to 11455, rotated the durable logcat marker to PID 11455, and retained both before/after |
643 | | -canaries plus the new process output in one `app.log`. Guarded daemon/dead-child recovery separately |
644 | | -terminalized the manifest and allowed a clean second start. |
645 | | - |
646 | | -The required revision package is complete: |
647 | | - |
648 | | -- `@agent-device/capture-kit` is the private durable-capture implementation package. Contracts keeps |
649 | | - pure runtime types and plan models; capture-kit owns process/recovery/live-handle mechanics, |
650 | | - envelope/descriptor codecs, and network parsers. The dependency order is |
651 | | - `kernel < contracts < capture-kit < platform/provider/daemon`. A planted-red gate rejects process, |
652 | | - filesystem, or timer mechanics drifting into contracts. The package is wired into affected-check |
653 | | - selection, the layering test enumeration, and the workspace typecheck project list. |
654 | | -- Canonical kernel device identity replaces the duplicate encoders while facts-shape validation stays |
655 | | - separate. The bounded Android/Harmony PID owner factory lives in capture-kit; Apple and Limrun stay |
656 | | - custom, there is no network factory, and all loaders retain their lazy boundary. The managed-command |
657 | | - allowlist, unused façade exports, public Limrun runtime-module declaration leak, quadratic JSON walk, |
658 | | - and duplicate lifecycle/reconnect mechanics are gone. The temporary Android implementation files |
659 | | - introduced by the devices PR are also absent from contracts at this checkpoint. |
660 | | -- Plan-declared app-session requirements replace repeated handler guards. Persisted durable lifecycle |
661 | | - is `open | completed`, with transient phase retained as metadata. A daemon-owned admission ledger |
662 | | - scopes decodable evidence by device identity, rechecks manually removed legacy markers, bounds |
663 | | - undurable blocks, and remains subordinate to the durable manifest. Discriminated teardown settles |
664 | | - app-log state, re-reads the replaced session record, then runs generic teardown, avoiding the stale |
665 | | - reference and double-cleanup path. |
666 | | - |
667 | | -The final gates passed: |
668 | | - |
669 | | -- `pnpm check:affected --run` at `457fafe63` passed 799 test files / 6,424 tests with 2,097/2,401 |
670 | | - changed executable lines covered (87.34%), plus format, lint, typecheck, build/declarations, |
671 | | - published-package clean install, fallow, provider integration, replay compatibility, and |
672 | | - integration-progress checks. |
673 | | -- `pnpm check:layering` passed 131 structural/model tests and scanned 1,157 production source files. |
674 | | - R11 owns 17 workspace packages behind 39 exported subpaths with no root back-imports; R13 keeps six |
675 | | - private implementation-lazy platform packages above capture-kit behind one canonical composition |
676 | | - root and its single private provider-composition implementation submodule; the historical R14 |
677 | | - and R15 rules retained one typed route for `logs` and `network` with no legacy route. |
678 | | -- Six local inventory/runtime owners, all enumerated Apple leaf/kind cells, and the production |
679 | | - BrowserStack, AWS Device Farm, and Limrun provider modes remain covered. Provider ownership and |
680 | | - inventory are fail-closed; exact-owner recovery and provider-authoritative tests prove there is no |
681 | | - provider-to-local fallback. Durable tests cover every start/persist/adopt gap, exact-owner recovery, |
682 | | - cleanup-only and descriptor-only cleanup, fencing, idempotence, and primary-error precedence. |
683 | | -- R7/R10 remain at 23 writer-owned `SessionState` fields and 29 owner claims, with all 34 fields |
684 | | - classified. The largest type cycle is 46 against the 47-file ceiling, and the two external |
685 | | - production `daemon/types.ts` importers are unchanged. Checkpoint-owned `logs`/`network` platform |
686 | | - decision lines remain zero. |
687 | | - |
688 | | -Issue 1704 revised the budget for this checkpoint for three explicit reasons: capture-pipeline |
689 | | -reliability through fenced ownership and exact recovery, durable cloud log streaming that did not |
690 | | -exist in the baseline, and a reusable durable-capture substrate. This is not a new observability |
691 | | -layer: the CLI-observable `logs` behavior remains parity work. The budget stays cumulative from |
692 | | -`44c298d7f`; the exact clean post-revision measurement is the reviewed upper bound for this checkpoint, |
693 | | -not a reusable allowance for future units: |
694 | | - |
695 | | -| Metric | Original baseline | Revised cumulative bound / checkpoint | Change | |
696 | | -| ------------------ | ----------------: | ------------------------------------: | ------------------: | |
697 | | -| Raw JavaScript | 2,036,067 B | 2,131,689 B | +95,622 B (+4.696%) | |
698 | | -| Gzipped JavaScript | 659,646 B | 695,134 B | +35,488 B (+5.380%) | |
699 | | -| npm tarball | 797,027 B | 826,761 B | +29,734 B (+3.731%) | |
700 | | -| npm unpacked | 2,781,186 B | 2,878,492 B | +97,306 B (+3.499%) | |
701 | | - |
702 | | -The controlled 15-run startup medians showed no regression (`--version` 94.5 ms to 47.4 ms; |
703 | | -`--help` 91.2 ms to 72.0 ms). Module-level source-map inspection found no duplicate implementation |
704 | | -emission; the distribution cost is the accepted reliability/cloud/substrate decision above. Future |
705 | | -units must define and review their own cumulative budget rather than inheriting this headroom. |
706 | | - |
707 | | -The recordings command unit has its own reviewed budget (2026-08-11). The cumulative denominator |
708 | | -remains the original `44c298d7f` baseline; rebasing onto the completed checkpoint does not reset it. |
709 | | -The immediate stack-base delta from durable-capture head `e3b0956b` is reported separately so the |
710 | | -cost of this command unit stays visible. The exact #1724 head that reproduces this table is recorded |
711 | | -in the acceptance comment before readiness. The increase pays for runtime-owned screen-recording |
712 | | -transports, fenced artifact finalization and cross-daemon recovery, and provider parity. It is not |
713 | | -unused checkpoint headroom and is not an allowance for a later command: |
714 | | - |
715 | | -| Metric | Original baseline | Recording bound | Cumulative change | Recording-only change | |
716 | | -| ------------------ | ----------------: | --------------: | -------------------: | --------------------: | |
717 | | -| Raw JavaScript | 2,036,067 B | 2,166,159 B | +130,092 B (+6.389%) | +32,026 B (+1.501%) | |
718 | | -| Gzipped JavaScript | 659,646 B | 708,776 B | +49,130 B (+7.448%) | +12,902 B (+1.854%) | |
719 | | -| npm tarball | 797,027 B | 836,426 B | +39,399 B (+4.943%) | +8,987 B (+1.086%) | |
720 | | -| npm unpacked | 2,781,186 B | 2,913,430 B | +132,244 B (+4.755%) | +32,494 B (+1.128%) | |
721 | | - |
722 | | -These bounds admit only the completed recordings cutover. Every subsequent command unit must define |
723 | | -and review both its original-baseline cumulative bound and its immediate stack-base delta. |
724 | | - |
725 | | -The tracking issue owns command order, PR/file lists, test-only compatibility fixtures, exact |
726 | | -benchmark commands and thresholds, raw evidence, and reviewers. Temporary fixtures never authorize |
727 | | -a production bridge, duplicate route, or recorded package back-import. After the checkpoint, this |
728 | | -ADR's status records its outcome; it does not retain a migration diary. |
| 570 | +The completed checkpoint procedures and results are retained in git history. |
729 | 571 |
|
730 | 572 | ### 8. Broader migration was move-dominated and evidence-tiered |
731 | 573 |
|
732 | | -The checkpoint and recordings budgets paid for machinery that later units reuse; they are not a |
733 | | -precedent for growth. Every post-checkpoint unit still defines its original-baseline cumulative |
734 | | -bound and immediate stack-base delta, but the default expectation inverts: a unit relocates |
735 | | -existing platform mechanics from root `src/` into platform packages and deletes superseded daemon |
736 | | -code, so its shipped-size delta trends to zero or negative. The unit's review reports root bytes |
737 | | -removed against package bytes added; net growth is exceptional and each contributing addition is |
738 | | -named and justified individually. Contract modules stay vocabulary-thin under the existing |
739 | | -capture-kit rule; per-unit type inflation is size growth and is reviewed as such. |
740 | | - |
741 | | -#### W5 Android family accounting (PR #2117) |
742 | | - |
743 | | -The W5 exact-head size report at `9fa2778` against `437465f37` reported these rounded CI values: |
744 | | - |
745 | | -| Metric | Original baseline | W5 head | W5 delta | |
746 | | -| ------------------ | ----------------: | ------: | -------: | |
747 | | -| Raw JavaScript | 2.48 MB | 2.49 MB | +8.2 kB | |
748 | | -| Gzipped JavaScript | 835.0 kB | 831.2 kB | -3.9 kB | |
749 | | -| npm tarball | 958.5 kB | 959.6 kB | +1.1 kB | |
750 | | -| npm unpacked | 3.32 MB | 3.33 MB | +9.0 kB | |
751 | | - |
752 | | -At source level, the moved Android production tree accounts for 456,492 B removed from |
753 | | -`src/platforms/android` versus 475,413 B in changed package targets, a +18,921 B relocation |
754 | | -delta; the new root host/facade seam adds 19,978 B. The published +9.0 kB unpacked result is the |
755 | | -package result, not a source-byte estimate. The increase is attributable to the named `mechanics` |
756 | | -closure, the injected root host composition, and preserving deferred helper loading while root |
757 | | -chunks are removed or repartitioned. The largest packed increase is the mechanics chunk; it is |
758 | | -offset by deletion or shrinkage of the superseded root Android chunks. |
759 | | - |
760 | | -A smaller design that retained root re-export shims, a broad barrel, or ambient filesystem/process |
761 | | -access would reduce gross source movement but violate this ADR's package-closure, |
762 | | -no-compatibility-shim, named-facet, host-injection, and implementation-lazy constraints. This is |
763 | | -exceptional W5 accounting, not reusable checkpoint headroom; after rebasing on #2116, the |
764 | | -combined-family CI size result remains the authoritative current measurement. |
765 | | - |
766 | | -Raw per-unit parity, planted-red, and size evidence belongs in #1739 and its PRs; this ADR retains |
767 | | -the decision, the evidence tiers, and the rule that each unit must justify exceptional growth |
768 | | -without treating checkpoint budget as an allowance. |
769 | | - |
770 | | -A command surface deprecated for the next major was deleted rather than migrated. Where a public |
771 | | -surface was narrowed, the narrowing merged first so the migration denominator was the surviving |
772 | | -surface only. |
773 | | - |
774 | 574 | Evidence requirements followed what a unit imported, in two tiers. A **request-scoped device unit** |
775 | 575 | used facts and operations only and proved its typed declaration and every fact cell. A |
776 | 576 | **durable-resource unit** additionally carried the full section 4–5 lifecycle evidence. These tiers |
|
0 commit comments