Skip to content

Commit 81cce60

Browse files
committed
docs(adr): fix review findings in the ADR 0003/0008 pilot
Round-1 review dispositions for #3810. F1: replace the unsupported blanket claim that the layering rule forbids commands importing client. State the accepted position instead: a type-only dependency on the AgentDeviceClient facade from a command module is ratchet-bounded (R6), not shared data that must move to contracts. Keep the shared option/result vocabulary rule. F2: restore the distinct rejected alternatives from ADR 0003 with their own reasons: daemon groups in the public catalog, handler-local coverage tables, and request-local route checks. Stop attributing the rejected designs to the original accepted shape. F3: reduce the ADR 0003 redirect to accepted identity plus section links into ADR 0008; remove the restated norms and the file-merge Decision history. Remove the dated campaign detail from the ADR 0008 Status. Keep the #2294 history line: it records a real direction change.
1 parent a7a9772 commit 81cce60

2 files changed

Lines changed: 15 additions & 30 deletions

File tree

‎docs/adr/0003-daemon-command-registry.md‎

Lines changed: 4 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -2,26 +2,9 @@
22

33
## Status
44

5-
Accepted; absorbed into [ADR 0008](0008-command-descriptor-registry.md) on 2026-10-19 (#3744).
5+
Accepted; this record holds no independent decision. [ADR 0008](0008-command-descriptor-registry.md) is the authoritative record for this decision.
66

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:
7+
Read ADR 0008:
108

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.
9+
- ["Daemon ownership"](0008-command-descriptor-registry.md#daemon-ownership) — the `daemon` facet, the derived daemon registry, predicate-only access, the public-contract boundary, and the absent-facet default.
10+
- ["Rules at a glance"](0008-command-descriptor-registry.md#rules-at-a-glance) — the daemon route, request-policy, and coverage-table rules.

‎docs/adr/0008-command-descriptor-registry.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## Status
44

5-
Accepted. Absorbed ADR 0003 on 2026-10-19 (#3744).
5+
Accepted. This record absorbed [ADR 0003](0003-daemon-command-registry.md), which now redirects here.
66

77
Amended by [ADR 0019](0019-request-bound-platform-runtime.md): device capability buckets became typed runtime use joined with request-bound runtime facts. The other derived projections remain accepted.
88

@@ -24,17 +24,17 @@ Amended by [ADR 0019](0019-request-bound-platform-runtime.md): device capability
2424

2525
### One declaration site
2626

27-
Declare each command once as a `CommandDescriptor` in `packages/command-registry/src/registry.ts`. The root is synchronous: each derived view is a module-scope value. That keeps the literal-union and compile-time totality guarantees [ADR 0027](0027-descriptor-root-vs-eager-closure-budget.md) relies on.
27+
Declare each command once as a `CommandDescriptor` in `packages/command-registry/src/registry.ts`. The root is synchronous: each derived view is a module-scope value, which keeps the literal-union and compile-time totality guarantees [ADR 0027](0027-descriptor-root-vs-eager-closure-budget.md) relies on.
2828

29-
The descriptor composes facets owned by their domains: catalog identity, command-family surface hooks, the `platformExecution` declaration, the `daemon` facet, `timeoutPolicy`, batch and MCP membership, `deviceClaimPolicy`, `postActionObservation`, response data transforms, and typed-result hooks. The public catalog, the batch allowlist, the MCP exposure list, the client timeout policy, and the daemon registry are pure projections of the descriptor set.
29+
The descriptor composes facets owned by their domains: catalog identity, command-family surface hooks, the `platformExecution` declaration, the `daemon` facet, `timeoutPolicy`, batch and MCP membership, `deviceClaimPolicy`, `postActionObservation`, response data transforms, and typed-result hooks. The public catalog, the batch allowlist, the MCP exposure list, the client timeout policy, and the daemon registry are pure projections of that set.
3030

31-
Keep a narrow fact on the descriptor when more than one projection consumes it. `timeoutPolicy` replaced the two hand-maintained client timeout lists (ADR 0011). `recordingEffect` drives the daemon's recording and mutation decisions. `postActionObservation` drives `--settle` / `--verify` flags, command metadata, and tests. One descriptor trait then replaces repeated command-name lists across projections.
31+
Keep a narrow fact on the descriptor when more than one projection consumes it. `timeoutPolicy` replaced the two hand-maintained client timeout lists (ADR 0011). `recordingEffect` drives the daemon's recording and mutation decisions. `postActionObservation` drives `--settle` / `--verify` flags, command metadata, and tests.
3232

3333
### Domain-owned surfaces
3434

35-
Keep CLI grammar, input decoding, executable surface metadata, and client-backed invocation in `src/commands/**`. Keep shared option and result shapes in domain contracts under `packages/contracts/src`: the layering rule forbids `commands/` importing `client/`, so a shape both surfaces need sits below both. The client facade declares its signatures in that vocabulary. Add a type projection only when it removes real duplication across consumers.
35+
Keep CLI grammar, input decoding, executable surface metadata, and client-backed invocation in `src/commands/**`. Keep shared option and result shapes in domain contracts under `packages/contracts/src`: both surfaces need that vocabulary, so a shared shape sits below both. A type-only dependency on the `AgentDeviceClient` facade from a command module is an accepted ratchet-bounded position, not shared data that must move to contracts. The facade declares its signatures in that vocabulary. Add a type projection only when it removes real duplication across consumers.
3636

37-
The client `invoke` seam is cross-process; the daemon `execute` seam runs the platform handler inside the daemon process. Keep the two seams distinct: the process boundary is never collapsed.
37+
The client `invoke` seam is cross-process; the daemon `execute` seam runs the platform handler inside the daemon process. The process boundary is never collapsed.
3838

3939
The `platformExecution` declaration names the execution shape: `none`, `host`, `inventory`, or `device-runtime`, each with its runtime use where required. [ADR 0019](0019-request-bound-platform-runtime.md) request-bound runtime facts and facets own platform admission and execution. Do not restore the retired capability matrix or generic dispatch switch.
4040

@@ -44,7 +44,7 @@ Declare daemon route and request-policy traits in the `daemon` facet. `DaemonCom
4444

4545
`packages/daemon/src/core/daemon-command-registry.ts` derives its table through `deriveDaemonCommandDescriptors(commandDescriptors)`. Only that module exposes the named predicates, such as `getDaemonCommandRoute`, `isLeaseAdmissionExempt`, and `shouldLockSessionExecution`. A duplicate command name throws when the registry builds. Without a `daemon` facet, each predicate falls back to the `generic` route and the default request policy.
4646

47-
No public contract may derive from daemon-only traits. This is an ownership constraint, not type enforcement: the current types neither block an accidental read by a public projection nor force a compile error for a missing facet. Reviewers and the registry tests hold the boundary. `command explain` in `src/cli/command-explain.ts` may read the facet for diagnostics.
47+
No public contract may derive from daemon-only traits. This is an ownership constraint, not type enforcement: the current types neither block an accidental read by a public projection nor force a compile error for a missing facet. Reviewers and the registry tests hold the boundary. `command explain` in `src/cli/command-explain.ts` may read the facet.
4848

4949
### Completeness guards
5050

@@ -57,9 +57,11 @@ About ten hand-maintained tables once repeated command identity, route membershi
5757
## Alternatives Considered
5858

5959
- **Keep manually synchronized tables.** This avoids migration risk. However, alignment held only by convention and tests.
60-
- **Keep the hand-authored daemon table, handler coverage tables, and request-module route checks.** The original ADR 0003 shape. It preserves the ownership boundary, but keeps second sources of route and policy membership that convention must align. The `daemon` facet plus derivation preserves the boundary and deletes the tables.
60+
- **Keep the daemon groups in the public catalog file.** This keeps one file for command names. However, it mixes public command identity with daemon runtime policy and grows the catalog for internal-only decisions.
61+
- **Keep handler-local coverage tables.** Each handler would describe its routes locally. However, this creates a second source of route membership that can disagree with the router and the request-policy modules.
62+
- **Put route checks directly in request modules.** This is locally simple. However, command classification spreads across admission, locking, provider scope, replay, recording, and generic dispatch.
6163
- **Use one flat public descriptor with inline daemon fields.** This puts daemon-only policy into the public command surface, which the ownership boundary above forbids.
62-
- **Generate code at build time.** However, runtime derivation with `as const satisfies` keeps the source of truth in type-checked TypeScript and needs no generated artifacts.
64+
- **Generate code at build time.** This is valid. However, runtime derivation with `as const satisfies` keeps the source of truth in type-checked TypeScript and needs no generated artifacts.
6365
- **Project the client surface from descriptors as a phantom view type.** PR #2294 removed it: it had one consumer, and direct facade signatures preserved the published contract with less machinery.
6466

6567
## Consequences

0 commit comments

Comments
 (0)