|
1 | | -# ADR 0003: Daemon Command Registry |
| 1 | +# ADR 0003: Daemon Command Registry (redirect) |
2 | 2 |
|
3 | 3 | ## Status |
4 | 4 |
|
5 | | -Accepted. Amended 2026-10-16: invariants 3 and 4 now describe the shipped derivation (#906, #907). |
6 | | - |
7 | | -## Rules at a glance |
8 | | - |
9 | | -- Keep public command identity in `packages/command-registry/src/catalog.ts` and public input/output contracts in `src/commands/**`. |
10 | | -- Declare daemon route ownership and request-policy traits in the separately typed `daemon` facet of the descriptor registry. |
11 | | -- Derive the daemon registry from that facet. Expose request-policy predicates only through the daemon registry. |
12 | | -- Request modules consume named predicates from the registry. They do not recreate command string sets. |
13 | | -- Handler modules own execution logic only. They do not export duplicate coverage tables to prove route membership. |
14 | | -- The daemon registry must not define CLI grammar, Node.js client options, MCP schemas, user-facing help, or platform capability support. |
15 | | -- Preserve all four invariants in the 2026-06 update. |
16 | | -- Do not derive a public contract from daemon traits. A diagnostic display, such as `command explain`, may read them. |
17 | | -- A command without a `daemon` facet uses the `generic` route with default request policy. |
18 | | - |
19 | | -## Context |
20 | | - |
21 | | -Daemon request behavior depends on traits outside the public command surface: |
22 | | - |
23 | | -- Which handler route owns a command. |
24 | | -- Whether tenant lease admission applies. |
25 | | -- Whether session execution should lock. |
26 | | -- Whether selector validation applies. |
27 | | -- Whether replay can run an action in the current session scope. |
28 | | -- Whether invalid recordings block the request. |
29 | | -- Whether Android blocking-dialog recovery applies. |
30 | | -- How request-scoped providers resolve a device. |
31 | | - |
32 | | -Previously, `src/command-catalog.ts`, request-policy modules, and handler-local coverage tables each held some of these traits. |
33 | | -Thus, `src/command-catalog.ts` contained daemon-only behavior beside public command identity. |
34 | | -Duplicate command sets required alignment by convention. |
35 | | - |
36 | | -## Decision |
37 | | - |
38 | | -Keep public command identity in `packages/command-registry/src/catalog.ts`. |
39 | | -Keep public input/output contracts in `src/commands/**`. |
40 | | - |
41 | | -Declare command route ownership and request-policy traits in the `daemon` facet in `packages/command-registry/src/registry.ts`. |
42 | | -`DaemonCommandDescriptor` in `packages/command-registry/src/daemon-command-descriptor.ts` types that separate facet. |
43 | | -`packages/daemon/src/core/daemon-command-registry.ts` derives its table through `deriveDaemonCommandDescriptors(commandDescriptors)`. |
44 | | -Request modules consume predicate functions from the registry. |
45 | | -They do not recreate command string sets. |
46 | | -Handler modules own execution logic only. |
47 | | -They do not export duplicate coverage tables to prove route membership. |
48 | | - |
49 | | -The daemon registry is internal-only. |
50 | | -It must not define: |
51 | | - |
52 | | -- CLI grammar. |
53 | | -- Node.js client options. |
54 | | -- MCP schemas. |
55 | | -- User-facing help. |
56 | | -- Platform capability support. |
57 | | - |
58 | | -The command contract, projection, help, and capability modules retain these responsibilities. |
59 | | - |
60 | | -## Alternatives Considered |
61 | | - |
62 | | -- **Keep daemon groups in `src/command-catalog.ts`.** This retains one file for command names. |
63 | | - However, it mixes public command identity with daemon runtime policy. |
64 | | - It also increases catalog size for internal-only route decisions. |
65 | | -- **Keep handler-local coverage tables.** Each handler describes its routes locally. |
66 | | - However, this creates a second source of route membership that can disagree with the router and request-policy modules. |
67 | | -- **Put route checks directly in request modules.** This is locally simple. |
68 | | - However, command classification becomes distributed across admission, locking, provider scope, replay, recording, and generic dispatch. |
69 | | - |
70 | | -## Consequences |
71 | | - |
72 | | -When a daemon-handled command is added or moved, update its `daemon` facet in `packages/command-registry/src/registry.ts`. |
73 | | -The daemon registry derives its table from those declarations. |
74 | | -The registry tests pin the trait decisions. |
75 | | -Provider-backed integration scenarios verify important request-policy behavior through the real daemon request path. |
76 | | - |
77 | | -The registry file is intentionally a dense internal contract. |
78 | | -Its interface should remain small. |
79 | | -Callers ask daemon-policy questions through named predicates. |
80 | | -They do not read or mutate command sets. |
81 | | - |
82 | | -`AGENTS.md` should contain only the operating rule and relevant file pointers for agents. |
83 | | -This ADR owns the rationale. |
84 | | -Thus, future changes do not require readers to infer the rationale from agent instructions. |
85 | | - |
86 | | -## Update (2026-06): single-declaration / derivation model |
87 | | - |
88 | | -The implemented `CommandDescriptor` direction in [ADR 0008](0008-command-descriptor-registry.md) unifies a command's declarations at one registration site. |
89 | | -It derives these surfaces from that site: |
90 | | - |
91 | | -- Public catalog. |
92 | | -- Capability matrix. |
93 | | -- CLI/MCP projections. |
94 | | -- Batch allowlist. |
95 | | -- Daemon registry. |
96 | | - |
97 | | -Its purpose is to remove the drift between these tables. |
98 | | -Registry tests pin the derived tables. |
99 | | - |
100 | | -**This ADR's decision remains accepted.** |
101 | | -Its boundary concerns ownership and the predicate interface, not the physical file that contains a trait. |
102 | | -“Separate source of truth” means separate ownership and exposure through named predicates. |
103 | | -That property remains true for a projected or derived backing table. |
104 | | -A derived daemon registry is therefore permitted **only if** it preserves all these invariants: |
105 | | - |
106 | | -1. **Daemon-owned declaration.** The separately typed `daemon` facet in `packages/command-registry/src/registry.ts` declares route and request-policy traits. |
107 | | - `DaemonCommandDescriptor` in `packages/command-registry/src/daemon-command-descriptor.ts` owns its type. |
108 | | - The registration composes that facet. |
109 | | - The public command contract in `src/commands/**` or `packages/command-registry/src/catalog.ts` must never contain these traits as inline fields. |
110 | | - A registration call may be co-located with public declarations. |
111 | | - Ownership of daemon policy must remain separate from the public surface. |
112 | | - See Alternatives, “Keep daemon groups in `src/command-catalog.ts`”. |
113 | | -2. **Predicate interface unchanged.** Consumers continue to use named predicates such as `getDaemonCommandRoute`, `isLeaseAdmissionExempt`, and `shouldLockSessionExecution`. |
114 | | - Only the daemon registry exposes these predicates. |
115 | | - Derivation changes table construction, not table access. |
116 | | -3. **No daemon traits in public contracts.** CLI grammar, Node.js client options, MCP schemas, user-facing help, and capability support must not derive from daemon-only traits. |
117 | | - A diagnostic display may read the `daemon` facet. `command explain` in `src/cli/command-explain.ts` displays routes and request-policy traits this way. |
118 | | -4. **One declaration per command.** Each command has at most one `daemon` facet, at its registration in the descriptor registry. |
119 | | - No second table declares the same traits. This replaces alignment by convention, and it justifies derivation instead of a separate hand-authored table. |
120 | | - A command without a `daemon` facet uses the `generic` route with default request policy. The daemon registry tests pin the derived table. |
121 | | - |
122 | | -A single flat public descriptor that exposes daemon fields in public views is **not** permitted. |
123 | | -This would combine daemon policy with a public command registry, which this ADR rejects. |
124 | | -Compose facets owned by their domains. |
125 | | -Derive the registry from those facets. |
126 | | -PR #906 introduced the descriptor and proved parity. |
127 | | -PR #907 made the derivation live and deleted the hand-authored table. |
128 | | -The daemon registry tests pin route and request-policy decisions. |
129 | | - |
130 | | -**Amendment 2026-10-16.** The 2026-06 text required types to stop every public projection from reading daemon traits, and required a compile error for a missing daemon trait. |
131 | | -The shipped derivation does neither: `CommandDescriptorBase.daemon` is optional (`packages/command-registry/src/types.ts`), and a command without a facet gets the `generic` route. |
132 | | -Invariants 3 and 4 now state the property that matters and that the code holds: no public contract derives from daemon traits, and no second table declares them. |
| 5 | +Accepted; absorbed into [ADR 0008](0008-command-descriptor-registry.md) on 2026-10-19 (#3744). |
| 6 | + |
| 7 | +This record no longer holds an independent decision. The daemon-command |
| 8 | +registry decision stated here merged into ADR 0008, which now states the |
| 9 | +current truth. Read ADR 0008 for: |
| 10 | + |
| 11 | +- The separately typed `daemon` facet as the single declaration of daemon |
| 12 | + route and request-policy traits, and the derived daemon registry. |
| 13 | +- The predicate-only access boundary: only |
| 14 | + `packages/daemon/src/core/daemon-command-registry.ts` exposes named |
| 15 | + request-policy predicates; request modules and handlers do not recreate |
| 16 | + command sets or route coverage tables. |
| 17 | +- The public-projection boundary: no public contract derives from daemon-only |
| 18 | + traits; a diagnostic display such as `command explain` may show them. This |
| 19 | + is an ownership constraint, not type enforcement. |
| 20 | +- The missing-facet default: a command without a `daemon` facet uses the |
| 21 | + `generic` route and the default request policy, with no compile error. |
| 22 | + |
| 23 | +## Decision history |
| 24 | + |
| 25 | +- 2026-10-19 — The #3744 ADR restructure merged this record into ADR 0008. The |
| 26 | + accepted decisions did not change; ADR 0008 absorbed the corrected |
| 27 | + 2026-10-16 invariants. |
0 commit comments