You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 81cce60
Browse filesBrowse the repository at this point in the historyBrowse files
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.
Copy file name to clipboardExpand all lines: docs/adr/0003-daemon-command-registry.md
+4-21Lines changed: 4 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,26 +2,9 @@
2
2
3
3
## Status
4
4
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.
6
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:
7
+
Read ADR 0008:
10
8
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.
Copy file name to clipboardExpand all lines: docs/adr/0008-command-descriptor-registry.md
+11-9Lines changed: 11 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
## Status
4
4
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.
6
6
7
7
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.
8
8
@@ -24,17 +24,17 @@ Amended by [ADR 0019](0019-request-bound-platform-runtime.md): device capability
24
24
25
25
### One declaration site
26
26
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.
28
28
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.
30
30
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.
32
32
33
33
### Domain-owned surfaces
34
34
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.
36
36
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.
38
38
39
39
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.
40
40
@@ -44,7 +44,7 @@ Declare daemon route and request-policy traits in the `daemon` facet. `DaemonCom
44
44
45
45
`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.
46
46
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.
48
48
49
49
### Completeness guards
50
50
@@ -57,9 +57,11 @@ About ten hand-maintained tables once repeated command identity, route membershi
57
57
## Alternatives Considered
58
58
59
59
-**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.
61
63
-**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.
63
65
-**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.
0 commit comments