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 7b1fc3b
Browse filesBrowse the repository at this point in the historyBrowse files
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.
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
+
309
348
### Deferred
310
349
311
350
The refactor is substantively done; these follow-ups are intentionally deferred, not lost:
0 commit comments