Skip to content

Commit 7b1fc3b

Browse files
authored
docs: architecture principles mapped to enforcing gates and open ledgers (#1428)
* docs: map architecture principles to their enforcing gates and ledgers in CONTEXT.md Writes down the rule → gate → ledger mapping (dependency rule → layering R1-R3/spine + R6 ratchet; acyclicity → R4 + depgraph tolerated-cycle report; policy×detail → the two registries + leak guard + transport seam; information hiding → R7; boundaries-are-earned with the #1409/platform-descriptor evidence; component metrics as observatory data per #1423) so contributors and agents get the why behind the guards they hit, in one place. * review: scope principle claims to actual enforcement; mark depgraph as proposed P1: the section referenced scripts/depgraph/ as present and #1410 as kept — that PR is open and this tree has no depgraph directory. Both the acyclicity and component-metrics bullets now name it as proposed (#1410), not landed. P2: enforcement claims scoped to the concrete guards: publicPlatformString gates one serialized-output DTO class, runnerProvider is one adopted seam, R7 covers SessionState only, and boundaries-are-earned plus stable-interface testing are labeled norms (gated only at the test-only-DI-seam slice). The intro now says explicitly that bullets distinguish gate, ledger, and norm.
1 parent 2d1d706 commit 7b1fc3b

1 file changed

Lines changed: 39 additions & 0 deletions

File tree

‎CONTEXT.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -306,6 +306,45 @@ The perfect-shape refactor is complete and merged. Its end-state:
306306
- Agent-cost. Responses carry a cost block and MCP `outputSchema`, rendered through a leveled
307307
`ResponseView`.
308308

309+
### Principles and their gates
310+
311+
The architecture rules this repo runs on are Clean-Architecture-shaped. Some are fully
312+
gate-enforced, some carry an open ledger that only shrinks, and some are norms with local evidence
313+
but no gate yet — each bullet below says which. When judging a design change, argue from the rule;
314+
when landing it, satisfy the gate where one exists.
315+
316+
- **Dependency Rule** (source dependencies point toward policy; details depend on abstractions).
317+
Gate: layering R1–R3 import direction plus the ranked spine's no-back-edges check
318+
(`scripts/layering/check.ts`). #1405's "shared contracts below their consumers" is dependency
319+
inversion stated as a merge gate. Ledger: `TYPE_INVERSION_BASELINE` — type-only inversions where
320+
types still flow the wrong way; the ratchet only tightens, and the long-term target is zero.
321+
- **Acyclic components.** Gate: R4 bans value-import cycles globally. Type-only and dynamic-import
322+
cycles are deliberately tolerated by the gate; a report surfacing them as data is proposed in
323+
#1410 (the analysis half of the graph tooling, kept after the #1409 viewer was rejected) and is
324+
not landed yet.
325+
- **Policy × detail boundaries on demonstrated axes of change.** The two registries are the two
326+
demonstrated axes: `CommandDescriptor` (what the system does) × `PlatformPlugin` (how a device
327+
does it), ADR 0008/0009. Boundary-crossing enforcement is narrower than the principle: the
328+
apple-platform leak guard (`publicPlatformString`, provider-integration suite) gates one specific
329+
DTO class — internal `apple` never reaching serialized public output — and the injectable Apple
330+
runner transport (`runnerProvider`, #1389) is one adopted seam, not a rule covering every
331+
boundary. Wider DTO/seam coverage is direction, not current enforcement.
332+
- **Information hiding.** Gate: R7 — every `SessionState` field is classified and every write must
333+
occur inside its declared owner. Encapsulation of the one shared mutable object, enforced
334+
per-field. This covers `SessionState`; other shared state has no equivalent gate today.
335+
- **Boundaries are earned, not speculative.** Norm with local evidence, not a gate: the platform
336+
descriptor layer (~600 LOC of boundary nobody needed) was deleted, and the depgraph viewer
337+
(#1409) was closed unmerged. A new abstraction layer needs a demonstrated second consumer or
338+
axis of change. The one gated slice of this norm is tests: CI forbids test-only DI seams — a
339+
missing seam gets added as a real one or not at all.
340+
- **Tests couple to stable interfaces.** Norm (see [Testing Principles](#testing-principles))
341+
backed by the test-only-DI-seam gate above; broader test-strength enforcement is planned, not
342+
present — tracked under [#1412](https://github.com/callstack/agent-device/issues/1412).
343+
- **Component metrics are observatory data, never gates.** Instability/abstractness per zone is a
344+
proposal ([#1423](https://github.com/callstack/agent-device/issues/1423), building on #1410's
345+
graph model) to locate concrete, high-fan-in modules worth pinning harder — explicitly never a
346+
CI threshold.
347+
309348
### Deferred
310349

311350
The refactor is substantively done; these follow-ups are intentionally deferred, not lost:

0 commit comments

Comments
 (0)