artifacts/a11oy-uds/docs/ARCHITECTURE.md

a11oy — Architecture & Formulas

The payload ships two TypeScript runtime packages — @a11oy/core and @a11oy/connection — plus a per-file provenance manifest. This document states, with primary-source citations, every formula the runtime implements.

All math below is implemented verbatim in the shipped JavaScript. File paths refer to locations inside the deployed /opt/a11oy/ tree (and to the TypeScript sources under artifacts/a11oy/packages/).

---

1. Tetrad Field (@a11oy/connection)

Source: Wald, General Relativity (1984), §3.4 (tetrad / vierbein formalism); Penrose & Rindler, Spinors and Space-Time vol. 1 (1984), §3.1.

A tetrad is an orthonormal frame field $e_a{}^\mu$ on a manifold. For governance policy the four legs are fixed:

index	leg	unit
0	capability_tier	tier
1	data_sensitivity	sensitivityLevel
2	action_reversibility	reversibilityScore
3	blast_radius	affectedUserCount

By construction the frame is orthonormal, so the metric in tetrad indices is $\eta = \mathrm{diag}(1,1,1,1)$ and the inner product collapses to

$$⟨a,b⟩=\sum _{i=0}^3{a}_i{b}_i,\parallel a\parallel =\sqrt{⟨a,a⟩}\mathrm{.}\backslash langle\; a,\; b\; \backslash rangle\; =\; \backslash sum\_\{i=0\}^\{3\}\; a\_i\; b\_i,\; \backslash qquad\; \backslash lVert\; a\; \backslash rVert\; =\; \backslash sqrt\{\backslash langle\; a,\; a\; \backslash rangle\}.$$

Implementation: tetradInner, tetradNorm in a11oy-connection/tetrad_field.js. Every decision the policy head emits is first projected onto this frame so the downstream complementarity check has a well-defined basis.

---

2. Fisher Information Manifold (@a11oy/core/geometry)

Source: Fisher (1925), "Theory of Statistical Estimation", Proc. Cambridge Phil. Soc. 22:700–725; Amari & Nagaoka (2000), Methods of Information Geometry, AMS Translations 191.

Agent credences are treated as points on a Fisher manifold (a Riemannian manifold whose metric is the Fisher information matrix). Two distributions $p, q$ are "distinguishable enough" when their Fisher–Rao distance exceeds the admit threshold.

For a categorical distribution the diagonal Fisher information matrix is

$$F_{ii}(p)=\frac{1}{p_i}\mathrm{.}F\_\{ii\}(p)\; =\; \backslash frac\{1\}\{p\_i\}.$$

The Fisher–Rao distance for discrete distributions is

$$d_{\text{FR}}(p,q)=2\arccos \text{\hspace{0.17em}⁣}({\sum }_i\sqrt{p_i{q}_i}),d_{\text{FR}}\in [0,\pi ]\mathrm{.}d\_\{\backslash text\{FR\}\}(p,\; q)\; \backslash ;=\backslash ;\; 2\; \backslash ,\; \backslash arccos\backslash !\backslash Bigl(\backslash textstyle\backslash sum\_i\; \backslash sqrt\{p\_i\; \backslash ,\; q\_i\}\backslash Bigr),\; \backslash qquad\; d\_\{\backslash text\{FR\}\}\; \backslash in\; [0,\; \backslash pi].$$

The inner term $\sum_i \sqrt{p_i q_i}$ is the Bhattacharyya coefficient, clamped to $[-1, 1]$ before $\arccos$ for numerical stability.

Implementation: fisherRaoDistance, fisherDiagonal, normalize in a11oy-core/geometry/fisher_manifold.js.

---

3. Bohr Complementarity Engine (@a11oy/core/quantum) — GRAFT 1

Source: Bohr (1928), "The Quantum Postulate and the Recent Development of Atomic Theory", Nature 121:580–590; Bohr (1949), "Discussion with Einstein on Epistemological Problems in Atomic Physics", in Schilpp (ed.), Albert Einstein: Philosopher-Scientist, Open Court.

Every governance decision is emitted as a ComplementaryDecisionPayload with exactly two complementary frames. Over the rolling sample window the empirical standard-deviation product must satisfy

$${\sigma }_A\cdot {\sigma }_B\ge \text{COMPLEMENTARITY\_FLOOR}=0.25,\backslash sigma\_A\; \backslash cdot\; \backslash sigma\_B\; \backslash ;\backslash ge\backslash ;\; \backslash text\{COMPLEMENTARITY\backslash \_FLOOR\}\; =\; 0.25,$$

the discrete-policy analogue of Heisenberg's $\sigma_x \sigma_p \ge \hbar/2$. A degenerate (deterministic) frame-pair yields $\sigma_A = 0$ or $\sigma_B = 0$ and the check fails.

The 12 canonical frame-pairs are chosen so the joint observable algebra is non-commutative — measuring sharply along axis A blurs axis B:

id	axis A	axis B
FP-01	capability_tier	data_sensitivity
FP-02	action_reversibility	blast_radius
FP-03	agent_age_days	capability_tier
FP-04	dual_spirit_light	dual_spirit_darkness
FP-05	pesher_admit	pesher_deny
FP-06	reviewer_quorum	time_to_decision
FP-07	fisher_distance	tetrad_norm
FP-08	metatron_capability_witness	watcher_dual_use_vector
FP-09	physiognomy_light_share	physiognomy_darkness_share
FP-10	primary_tablet_root	secondary_tablet_root
FP-11	povm_admit_amplitude	povm_deny_amplitude
FP-12	ks18_witness_value	daruan_rotation_angle

Implementation: emitDecision, checkComplementarity, FRAME_PAIRS, fromTetrad in a11oy-core/quantum/bohr_complementarity_engine.js. Doctrine §1.1 invariant: payload.frames.length === 2 is enforced at construction and the check throws if violated.

---

4. Kochen–Specker 18-Vector Contextuality Witness (@a11oy/core/quantum) — GRAFT 2

Source: Cabello, A., Estebaranz, J. M., & García-Alcaine, G. (1996), "Bell-Kochen-Specker theorem: A proof with 18 vectors", Physics Letters A 212(4), 183–187. arXiv:quant-ph/9706009.

The 18-vector / 9-context construction proves that no non-contextual hidden-variable model can reproduce all quantum predictions on a 4-dimensional Hilbert space. We use it as a contextuality witness for the a11oy policy head: if the rolling sequence of yes/no governance answers admits a non-contextual hidden-variable assignment, the witness flags BOHR_ANOMALOUS — the policy head has collapsed into a classical deterministic rule and is no longer providing dual-framed reasoning.

Vectors

The 18 vectors $v_0, \dots, v_{17} \in \mathbb{R}^4$ (Cabello et al. 1996, Table 1) are bundled verbatim in a11oy-core/quantum/kochen_specker_18.js as KS18_VECTORS.

Contexts

Nine four-element mutually-orthogonal contexts (indices into KS18_VECTORS):

ctx	indices	ctx	indices
0	${0,1,2,3}$	5	${11,12,13,14}$
1	${3,4,5,6}$	6	${13,14,15,16}$
2	${5,6,7,8}$	7	${15,16,17,0}$
3	${7,8,9,10}$	8	${17,0,1,2}$
4	${9,10,11,12}$

Each vector appears in exactly two contexts.

Witness rule

Search for an assignment $f : {0,\dots,17} \to {0,1}$ such that

$$\mathrm{\forall }\text{ context }C:\sum _{i\in C}f(i)=1.\backslash forall\; \backslash text\{\; context\; \}\; C:\; \backslash quad\; \backslash sum\_\{i\; \backslash in\; C\}\; f(i)\; =\; 1.$$

Cabello et al. prove no such assignment exists. Therefore:

• evaluate returns { contextual: true, reason: 'NO_NON_CONTEXTUAL_MODEL_FITS_OBSERVATIONS' } when the search exhausts without success — the desired state.
• evaluate returns { contextual: false, reason: 'BOHR_ANOMALOUS_NON_CONTEXTUAL_FIT_EXISTS', example } when the search finds an assignment consistent with the observed answers — the policy head has collapsed and the example is returned as evidence.

Implementation: evaluate, KS18_VECTORS, KS18_CONTEXTS, KochenSpecker18Witness in a11oy-core/quantum/kochen_specker_18.js.

---

5. POVM Verdict Semantics (@a11oy/core/quantum) — GRAFT 3

Source: Preskill, J. (2015), Quantum Information (Physics 219 / CS 219 lecture notes), Caltech, Chapter 3 §3.1 (POVMs). https://www.preskill.caltech.edu/ph219/chap3_15.pdf

Binary ${accept, reject}$ verdicts are replaced by a positive-operator-valued measure: a finite collection of positive-semidefinite operators ${E_i}$ on the policy state space satisfying the completeness theorem

$$\sum _i{E}_i=I,0\le E_i\le I\mathrm{.}\backslash sum\_i\; E\_i\; =\; I,\; \backslash qquad\; 0\; \backslash le\; E\_i\; \backslash le\; I.$$

Each $E_i$ corresponds to a distinct admission outcome:

'admit' | 'admit_throttled' | 'admit_witnessed' | 'deny' | 'escalate'

The probability of outcome $i$ on policy state $\rho$ is the Born rule $\Pr(i) = \mathrm{Tr}(E_i \rho)$. The shipped implementation restricts to diagonal effects in the policy basis (full off-diagonal POVMs are out of scope for v0.1); this reduces the trace to a dot product.

makePOVM validates completeness with tolerance $10^{-9}$ and throws POVMSetError if $\sum_i E_i \ne I$ — the operational equivalent of the Lean theorem povm_completeness referenced in the doctrine.

Implementation: makePOVM, isComplete, probability, argmaxOutcome, POVMSetError in a11oy-core/quantum/povm.js.

---

Composition

The four formulas compose into a single governance step:

1. Frame the decision. makeTetrad(...) produces a TetradFrame over the four governance legs (this is the orthonormal basis).
2. Project onto a complementary pair. fromTetrad(pair, frame) extracts $(v_A, v_B)$ for one of the 12 canonical frame-pairs and emits a ComplementaryDecisionPayload via emitDecision.
3. Bind credences to the Fisher manifold. fisherRaoDistance(p, q) is used to gate "distinguishable enough" admissions. fisherDiagonal(p) supplies the local metric for credence updates.
4. Apply the POVM. argmaxOutcome(povm, ρ) selects the admission outcome from the completeness-validated effect set.
5. Bound the policy head. The rolling decision window is passed to checkComplementarity (σ-product floor) and to KochenSpecker18Witness.evaluate (contextuality witness). If either fails, the policy head is flagged and the decision is escalated.

Every step is pure, deterministic, and side-effect-free — the package ships no I/O, no network, no global state. It is designed to be linked into a host process (sidecar, lambda, or worker) that supplies inputs and consumes outputs.

---

File map (deployed)

/opt/a11oy/
├── core/
│   ├── geometry/fisher_manifold.{js,d.ts}
│   ├── quantum/bohr_complementarity_engine.{js,d.ts}
│   ├── quantum/kochen_specker_18.{js,d.ts}
│   ├── quantum/povm.{js,d.ts}
│   ├── index.{js,d.ts}
│   └── package.json
├── connection/
│   ├── tetrad_field.{js,d.ts}
│   ├── index.{js,d.ts}
│   └── package.json
└── MANIFEST.json

MANIFEST.json carries the per-file SHA-256 digest, byte size, build timestamp, and source git SHA — see SECURITY.md for the full provenance chain.