ADR 0019: resolve the platform-runtime package-size checkpoint

[thymikee]

Context

ADR 0019 checkpoint PR #1703 records revise: the substrate and complete devices, logs, and network cutovers pass their architecture, parity, lifetime, laziness, startup, and coupling gates, but the published package exceeds every hard +3% size threshold. Broader command migration remains prohibited.

Controlled same-host comparison from 44c298d7f to 99f5af1b7:

Metric	Baseline	Checkpoint	Change	Excess beyond +3%
Raw JavaScript	2,036,067 B	2,121,980 B	+4.22%	24,831 B
Gzipped JavaScript	659,646 B	690,882 B	+4.74%	11,447 B
npm tarball	797,027 B	851,261 B	+6.80%	30,324 B
npm unpacked	2,781,186 B	2,913,110 B	+4.74%	48,489 B

Slice attribution identifies logs as the main increase: inventory +10,398/+4,581 raw/gzip, logs +69,775/+23,407, network +5,740/+3,248. Source-map review found no duplicate module emission. The obvious private Limrun declaration cleanup saves unpacked/compressed declaration bytes but cannot close the raw/gzip gaps.

Decision required

Choose and document an architecture-honest distribution/budget direction, for example:

• make platform/provider runtime implementations optional install-time packages or otherwise exclude unselected implementations from the core published artifact; or
• accept a reviewed replacement size budget based on measured distribution/startup cost and explain why the previous +3% threshold is no longer the right constraint.

Do not satisfy the checkpoint by removing frozen platform/provider behavior, weakening exact recovery, making implementations eager, or silently loosening thresholds.

Acceptance criteria

• The packaging/budget decision is recorded in ADR 0019 or a superseding ADR.
• Six-family/provider parity, fail-closed ownership, exact recovery, and metadata-eager/implementation-lazy loading remain intact.
• Clean same-host base/head runs use pnpm build and node scripts/size-report.mjs --startup-runs 15.
• Every package/startup metric passes the accepted reviewed bound.
• ADR 0019 checkpoint is rerun and its Status changes from revise to continue or stop.
• No broader command migration starts before that result.

Umbrella: #1696. Implementation stack: #1699 → #1701 → #1702 → #1703.

[thymikee]

Decision: revise the budget, with conditions

The +3% threshold predates the durable-capture lifecycle scope. Investigation (module-level source-map attribution, base 44c298d7f vs head d73bdb4) confirms the growth is real new code, not duplication or forgotten deletions: ~30 kB one-time substrate (contracts + runtime seams), the rest per-family implementations and the durable lifecycle. Zero duplicate module emission across chunks; all legacy devices/logs/network implementations were removed. Startup medians are flat, so the cost is distribution bytes only.

Record the accepted rationale in ADR 0019 exactly as: capture-pipeline reliability (fenced ownership, exact recovery — the failure class seen in #1117, #1384, #1246), new durable cloud log streaming (baseline Limrun could only tail), and a reusable durable-capture substrate. Do not describe it as a new observability layer — CLI-observable logs behavior is at parity with baseline, and the checkpoint record must stay honest.

Required before the checkpoint rerun

Cleanup package (~800–900 net source lines, ~10–15 kB raw JS + ~20 kB declarations). All items verified against the stack head; the specific shapes are detailed in the review comment on #1701:

1. Canonical device identity (deviceIdentity/deviceIdentityKey/sameDeviceIdentity) in packages/kernel/src/device.ts; collapse the 5 duplicate encoders and all 9 optional-field projection blocks. factsMatchBindingIdentity stays separate (different input shape, no id).
2. createPidScopedAppLogRuntimeOwner(config) in contracts. Android and HarmonyOS become ~30–40-line declarations (−250 net). Apple stays custom — no PID-scoped model, per-device backend, async command build. Skip a network-runtime factory (~70 recoverable lines, not worth it).
3. Delete isManagedAppLogCommand — write-time it can only SIGKILL our own just-spawned child on an unlisted command shape; read-time it's tautological after exact startTime+command equality.
4. Plan-declared requirements: requiresAppSession on LogsRuntimePlan, one dispatcher guard (deletes 6 duplicated appBundleId checks); fold the requireRuntimeBinding throw into bindDevice (deletes all 8 call sites, incl. 3 discarded results).
5. Fix the limrun.d.ts leak at its root: LimrunRuntime's daemon-internal loadRuntime(): Promise<PlatformRuntimeOwner> is re-exported through public src/sdk/limrun.ts, so dts bundling inlines the whole AppLog type closure (+15.5 kB). Split the provider-module handle off the public class; only platform-runtime-gateway.ts consumes it. Trim the contracts façade 36→26 exports: delete DurableResourceFacet (zero implementers) and AppLogDescriptorCodec + the other zero-consumer types.
6. P1 — assertNoRetainedLegacyMarker() checks the retained set's global size, so one stuck legacy marker on device A blocks logs start on every device until daemon restart. Scope by device identity key. Move both module-global ledgers into a daemon-owned AppLogCleanupLedger instantiated beside sessionStore, with a bounded TTL on undurableCleanupBlocks.
7. Lifecycle 5→2 persisted states (open | completed, phase detail as metadata): 'completing' is written 3x and read 0x; the only persisted-lifecycle branches anywhere are === 'completed'. Also drops the two-phase adoption write and the starting-as-tombstone hack; the fail-closed decode gets stricter. Needs a one-paragraph ADR 0019 §5 amendment — fencing, fail-closed decode, and cleanup-only recovery are untouched.
8. Teardown: convert to an options object with appLog: 'run' | 'already-settled'. Do not delete the skip flag — sessionStore.set replaces the session object, teardown holds a stale reference, and removing the flag double-invokes cleanup on a disposed resource.
9. Minor: fix the quadratic freezeJsonValue re-validation; merge app-log-live-handle-core.ts into its only caller.

After the checkpoint

Extract the daemon-side fence/envelope/transition/ledger core as DurableCaptureResource and migrate recordings onto it as the next slice — the resource with the actual field-failure record (#1117, the moov finalization bug). That is what converts the substrate cost into covered ground.

Validation: standard per-unit gates, then clean same-host base/head pnpm build + node scripts/size-report.mjs --startup-runs 15; record the post-cleanup numbers as the reviewed bound and rerun the ADR 0019 checkpoint.

[thymikee]

Post-cleanup cumulative measurement

The #1701 revision package is now published at e99da3680, including the placement correction: implementation mechanics moved to the new private @agent-device/capture-kit; contracts retains pure types/plans and has a planted-red implementation-drift ratchet.

Clean same-toolchain measurements remain cumulative from the original ADR checkpoint baseline 44c298d7f, not from the now-merged devices base:

Metric	44c298d7f	e99da3680	Cumulative delta
JS raw	2,036,067	2,120,117	+84,050 (+4.128%)
JS gzip	659,646	689,797	+30,151 (+4.571%)
npm tarball	797,027	823,385	+26,358 (+3.307%)
npm unpacked	2,781,186	2,866,441	+85,255 (+3.065%)

The cleanup precondition is complete and the original +3% bound still fails honestly, so the decision remains revise. Rationale is unchanged: fenced/exact capture reliability, durable cloud log streaming, and reusable durable-capture substrate; this is not a new observability layer. The revised bound and ADR checkpoint must use these cumulative figures so rebasing the remaining stack cannot launder the denominator.

Implementation validation at e99da3680: required affected gate passed before push; 778 files / 6,363 tests, 89.95% changed-line coverage, package/declaration smoke, typecheck, layering, fallow, provider integration, and replay compatibility green. GitHub checks are now running on the exact head.

[thymikee]

Final post-rebase checkpoint measurement, preserving the decision comment's original-baseline rule:

• baseline: 44c298d
• merged devices: c06bed9
• final logs: 1887953
• final network/checkpoint production head: 1bdd382

Same-host 15-run report after the full stack was rebased onto current main:

Metric	Original baseline	Final cumulative head	Change
Raw JavaScript	2,036,067 B	2,131,689 B	+95,622 B (+4.696%)
Gzipped JavaScript	659,646 B	695,134 B	+35,488 B (+5.380%)
npm tarball	797,027 B	826,761 B	+29,734 B (+3.731%)
npm unpacked	2,781,186 B	2,878,492 B	+97,306 B (+3.499%)

Startup medians improved: CLI --version 94.5 ms to 47.4 ms; CLI --help 91.2 ms to 72.0 ms.

These are the authoritative revised cumulative checkpoint bounds; the smaller per-PR deltas after #1699 merged are not the budget denominator. The rationale remains the decision already recorded here: capture reliability, durable cloud log streaming, and reusable substrate—not a new observability layer. Future command units do not inherit this headroom; recordings onto DurableCaptureResource remains the next post-checkpoint direction.