|
| 1 | +# Contract projection and output-economy spike |
| 2 | + |
| 3 | +Issues: #1185, #1186 |
| 4 | + |
| 5 | +This report keeps the two experiments bounded: one typed command family for executable contract |
| 6 | +projection and one opt-in response family for digest expansion. |
| 7 | + |
| 8 | +## Selection evidence |
| 9 | + |
| 10 | +### Executable contract: typed system navigation |
| 11 | + |
| 12 | +Selected commands: |
| 13 | + |
| 14 | +- `home` |
| 15 | +- `back` |
| 16 | +- `rotate` |
| 17 | +- `app-switcher` |
| 18 | +- `tv-remote` |
| 19 | + |
| 20 | +These commands already have closed neutral results in `src/contracts/navigation.ts`, typed |
| 21 | +`CommandResultMap` entries, executable definitions, Node client methods, and MCP output schemas. |
| 22 | +They do not overlap the broad-return client methods being changed under #1183. |
| 23 | + |
| 24 | +The baseline has three independent command-to-surface declarations per selected command: |
| 25 | + |
| 26 | +1. the facet's client-method mapping; |
| 27 | +2. the public client method signature; |
| 28 | +3. the keyed MCP output-schema entry. |
| 29 | + |
| 30 | +That is 15 independent projection declarations around five executable definitions. The spike will |
| 31 | +make each executable definition the single command-to-client/MCP projection declaration and derive |
| 32 | +the client surface and MCP schema map from those five definitions. Success is five declarations |
| 33 | +instead of 15, without changing CLI, daemon, client, or MCP behavior. |
| 34 | + |
| 35 | +The experiment stops at these five commands. It must not continue if it needs generated source, a |
| 36 | +schema DSL, a new dependency, a parallel registry, a new import back-edge, weaker parity checks, |
| 37 | +more hand-authored declarations, or a measurable cold-start or bundle regression. |
| 38 | + |
| 39 | +### Digest response: network observations |
| 40 | + |
| 41 | +Deterministic representative payloads rank the unregistered candidates as follows: |
| 42 | + |
| 43 | +| Family | Default bytes | Conservative digest estimate | Reduction | Selection | |
| 44 | +|---|---:|---:|---:|---| |
| 45 | +| network (`include=all`) | 26,371 | 1,665 | 24,706 (93.7%) | selected | |
| 46 | +| events | 7,686 | 3,375 | 4,311 (56.1%) | rejected | |
| 47 | +| debug symbols | 4,804 | 2,054 | 2,750 (57.2%) | rejected | |
| 48 | +| recording | 3,132 | 2,427 | 705 (22.5%) | rejected | |
| 49 | + |
| 50 | +The network estimate removes only repeated payload material from each entry (`headers`, |
| 51 | +`requestHeaders`, `responseHeaders`, `requestBody`, `responseBody`, and `raw`). It retains every |
| 52 | +entry and its method, URL, status, timestamp, duration, packet ID, and source line, plus top-level |
| 53 | +path/state/backend/include, limits, scan counts, notes, and additive fields. |
| 54 | + |
| 55 | +The other candidates require less conservative compromises: |
| 56 | + |
| 57 | +- event `details` can contain refs, error identity, request logs, and recovery data; |
| 58 | +- debug frames and matched images are the diagnostic evidence; |
| 59 | +- recording chunks and artifacts are retrieval handles. |
| 60 | + |
| 61 | +The existing routine-workflow oracle remains the actionability floor: 2,276 total bytes across |
| 62 | +seven commands, zero fallback observations, exactly one retry, and all in-session recovery handles |
| 63 | +preserved. The network addition must keep those measurements unchanged and separately prove that a |
| 64 | +failed request remains identifiable and actionable from the digest. |
| 65 | + |
| 66 | +## Measurement plan |
| 67 | + |
| 68 | +- Declaration count: count independent selected-command projection declarations before and after. |
| 69 | +- Runtime: compare median cold imports of the MCP command-tool projection at the merge base and |
| 70 | + spike head. |
| 71 | +- Bundle: compare `pnpm size` raw/gzip totals and relevant chunks at the merge base and spike head. |
| 72 | +- Dependencies: run the layering/back-edge gate and verify no package dependency changes. |
| 73 | +- Output economy: commit default and digest bytes, then assert default byte identity, retained |
| 74 | + request identity/recovery notes, and unchanged routine-workflow fallback/retry counts. |
| 75 | + |
| 76 | +The merge-base size baseline is 1,659,106 raw JS bytes, 529,658 gzip bytes, and 636,721 tarball |
| 77 | +bytes on Node 24.13.0. |
| 78 | + |
| 79 | +## Contract projection results (#1185) |
| 80 | + |
| 81 | +The five selected navigation commands now carry one colocated projection declaration each in |
| 82 | +`src/commands/system/navigation-projection.ts` (`NAVIGATION_COMMAND_PROJECTIONS`): client-method name, public option |
| 83 | +shape, closed result type, and MCP `outputSchema`. The family builder derives `clientCommandMethods` |
| 84 | +from those projections, `AgentDeviceCommandClient` derives the five navigation methods via |
| 85 | +`ProjectedNavigationCommandClient`, and `COMMAND_OUTPUT_SCHEMAS` spreads the projected schemas. |
| 86 | + |
| 87 | +- Declarations: 15 -> 5 (10 fewer). Removed the per-command facet `clientMethod`, the hand-written |
| 88 | + client method signature, and the hand-authored MCP schema entry. |
| 89 | +- Behavior: CLI, daemon, client runtime, and MCP output schemas unchanged (unit/client/MCP tests pass). |
| 90 | +- Bundle: +773 B raw JS, +146 B gzip, +620 B tarball; no material chunk regression, no dependency change. |
| 91 | +- Runtime: CLI --version 20.3 ms / --help 39.5 ms median (20 runs); no cold-start regression. |
| 92 | +- Layering/Fallow: green; no new value back-edge (type-only import from client, value import only |
| 93 | + from the already-command-importing MCP schema map). |
| 94 | + |
| 95 | +Recommendation: #1185 should CONTINUE incrementally, one already-typed closed-contract family at a |
| 96 | +time, re-measuring declarations and bundle each step and stopping on any stop condition. |
| 97 | + |
| 98 | +## Digest expansion results (#1186) |
| 99 | + |
| 100 | +Added one conservative, opt-in `network` response view in `src/daemon/response-views.ts` |
| 101 | +(registered as `RESPONSE_VIEWS.network`). It acts ONLY at `responseLevel: 'digest'`; `default` |
| 102 | +and `full` return the same object reference, so the default wire shape stays byte-identical |
| 103 | +(Maestro `.ad` recompare safe) and live metrics remain informational. |
| 104 | + |
| 105 | +Transformation: the entire top-level dump (`path`, `exists`, `active`, `state`, `backend`, |
| 106 | +`include`, `scannedLines`, `matchedLines`, `limits`, `notes`, and any additive fields) is |
| 107 | +preserved, EVERY entry is preserved (none dropped, capped, or reordered), and only the verbose |
| 108 | +per-entry payload fields are removed: `headers`, `requestHeaders`, `responseHeaders`, |
| 109 | +`requestBody`, `responseBody`, `raw`. Each entry keeps its actionable identity — `method`, `url`, |
| 110 | +`status`, `timestamp`, `durationMs`, `packetId`, `line`, and any additive fields such as |
| 111 | +`metadata`. |
| 112 | + |
| 113 | +Measured on the deterministic `selection.network` fixture (`network ... --include all`, 8 entries): |
| 114 | + |
| 115 | +- Output bytes: 26,371 -> 1,665 (24,706 fewer / 93.7% reduction). |
| 116 | +- Entries preserved: 8 -> 8 (no follow-up refetch needed; identity intact). |
| 117 | +- Follow-up actionability: the failed POST keeps method/url/status/packetId/duration/timestamp and |
| 118 | + the top-level recovery note, so the retry path is unchanged (no extra follow-up calls implied). |
| 119 | +- Fallback observations: 0 (routine-workflow oracle unchanged). |
| 120 | +- Retries: 1 (routine-workflow oracle unchanged). |
| 121 | +- Recovery/session fields: preserved (routine-workflow oracle unchanged). |
| 122 | + |
| 123 | +Defaults are unchanged; the digest is strictly opt-in via a non-default response level. Residual |
| 124 | +risk: the dropped-field set is intentionally specific to the known verbose network payload fields; |
| 125 | +if a backend introduces a new large per-entry field it would remain until added to the drop list |
| 126 | +(safe by default — unknown fields are preserved, never silently narrowed). |
0 commit comments