Skip to content

Commit 9299ebf

Browse files
committed
docs(adr): merge ADR 0003 into the ADR 0008 descriptor decision
Restructure pilot for #3744. Rewrite ADR 0008 as one accepted current decision covering the descriptor root, derived projections, domain-owned surfaces, the daemon facet, completeness guards, and the process boundary. Correct the claims the 2026-10-16 amendment already fixed: the facet is optional with generic/default fallback, and the public-projection boundary is an ownership constraint, not type enforcement. Do not restore the removed descriptor-owns-all-Input/Result claim; #2294 retired it. Replace ADR 0003 with a short redirect that preserves its accepted decision identity. Update the ADR index rows and the cross-ADR citations in ADRs 0009, 0014, and 0019. Repoint the stale Phase 1 step citations in batch-policy.ts, command-result.ts, and daemon-command-registry.ts, and the migration-era comments in registry.ts and owner-files.ts, at the new named sections. Comment-only source changes; no runtime behavior change.
1 parent eef1a3f commit 9299ebf

12 files changed

Lines changed: 104 additions & 274 deletions
Lines changed: 24 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -1,132 +1,27 @@
1-
# ADR 0003: Daemon Command Registry
1+
# ADR 0003: Daemon Command Registry (redirect)
22

33
## Status
44

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

Comments
 (0)