Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
146 lines (106 loc) · 7.17 KB

ARCHITECTURE.md

File metadata and controls

146 lines (106 loc) · 7.17 KB
Raw

TORIS — Architecture Decisions Log

ADR-001: Layer 0 module boundaries

relation_types.py is pure: it defines the typed relation set T and all relations between types (symmetry, CONTRA, D_type, Ω composition). It imports only constants. It has no knowledge of concepts or fields.

concept_state.py depends on relation_types only. relator.py depends on both. The Relator↔ConceptState cycle is broken by importing Relator under typing.TYPE_CHECKING in concept_state.py and relying on from __future__ import annotations (string annotations, no runtime eval).

Why: keeps the algebra independently testable and prevents the higher layers (field, engine, goal) from leaking back into the primitives.

ADR-002: ConceptState is a distribution, never a coordinate

ConceptState stores Π as Dict[RelationType, float] always projected onto the probability simplex by _normalize. There is no array of coordinates anywhere. The context update is the Bayesian rule of MATH_SPEC §2.2, exposed both as a pure preview (goal_warped_roles) and an in-place mutation (update_role_distribution). This directly satisfies the TORIS spec §1.1: "Represent concepts as probability distributions over relational roles."

ADR-003: Relators carry identity and are mutable

σ, κ, ε mutate during plasticity (Layers 4–5), so Relator is a mutable dataclass with an auto-assigned rid. Edge identity for set operations in the surprise metric (Layer 1) will key on (src_id, tgt_id), exposed as Relator.edge — not on the Relator object — so a relator stays trackable as its strength changes.

...

ADR-004: Composition accumulates surprise additively

Relator.compose follows MATH_SPEC §1.2 exactly: composed strength from the Ω rule, κ = min of the two, ε = ε₁ + ε₂. Additive surprise encodes that longer chains are inherently more uncertain — the basis for the sparse-generalization uncertainty bound (MATH_SPEC §6).

ADR-005: Fast Surprise Dynamics (FSD) Complexity Reduction

The surprise computation pipeline is optimized from O(n²) to O(n log n) using two complementary techniques:

  1. TFSA (Fast Surprise Approximation): Exploits the IEEE 754 log-encoding of floats to approximate 1/sqrt(κ) (the surprise potential) using the Carmack-Walsh constant and a single Newton-Raphson refinement step. This reduces the local surprise estimate to O(1) per relator.
  2. Continuous Wave Propagation: Replaces discrete threshold-gating with a coupled sine oscillator system (RK4 integration) over detected relational loops. This captures the "standing wave of tension" produced by contradictions, activating more relators in loops than discrete propagation would.

Why: Enables the system to scale to dense fields (n > 1000) without quadratic slowdown and provides richer, non-linear surprise dynamics in recursive structures.

ADR-006: Analytic Surprise Functional (ASF) — Layer 7

Layer 7 replaces edge-scanning with analytic function evaluation in complex salience space, reducing the inner loop from O(n log n) to O(1) for smooth fields.

Key decisions:

  1. Pole injection for productive contradictions — Contradictions with type- distance ≥ 0.65 (CONTRA pairs) inject an explicit Res/(κ − κ_C) term into F(κ). This makes productive contradictions appear as genuine poles detectable by TASF's detect_poles scan, matching §10.2.4 ("PRODUCTIVE contradiction = pole in F(κ)").

  2. One-loop running coupling — α_S(κ) uses the exact QCD one-loop solution α_ref / (1 + α_ref·b0·log(κ)) with κ_ref = 1.0 and α_ref = s0/(1+s0) ∈ (0,1). This guarantees: (a) well-conditioned β-function fit, (b) moderate α values, (c) exact satisfaction of d log α / d log κ = −b0·α.

  3. OPE coefficients calibrated to tau physics suppression — C₀=1, C₂=0.1, C₄=0.01 match the hierarchical suppression seen in tau hadronic width calculations where non-perturbative contributions are suppressed by 1/s² factors.

  4. Michel Alert threshold 0.05 (not 0.3%) — The tau-physics Michel bounds are at the 0.3% level. For TORIS inference chains that are far less constrained, 5% thresholds are appropriate. Deviation D-20 logged.

ADR-007 — Layer 9: Exact Surprise Architecture

Date: 2026-06-07 Status: ACCEPTED

Context

Layer 9 implements certified exact surprise computation via analytic number theory: Rademacher exact series, Eisenstein modular forms, and Harmonic Maass shadow completion.

Decisions

  1. Rademacher series (rademacher.py)

    • bessel_I_3_2(x) implemented analytically: sqrt(2/πx)·(cosh(x)/x − sinh(x)/x²).
    • Error bound: C_F·exp(−π√(2d/3)/N) where C_F = max(1, |S_N|). Conservative but certified.
    • TAU_INDEX maps 12 RelationTypes to integers 1–12 for the TORIS Kloosterman sum.

  2. Dual Weighting Theorem (eisenstein.py)

    • d ≤ d_crit=5: empirical weights (0.6/0.3/0.1) — optimal for shallow relational reasoning.
    • d > 5: Eisenstein weights (1/6, 1/3, 1/2) — modular form structure governs deep inference.
    • Crossover is a phase transition, not a continuous interpolation.

  3. Harmonic Maass shadow (maass_completion.py)

    • Productive contradictions → cusp forms g_C(z) = σ_a·σ_b·exp(2πi·τ_diff·z).
    • Eichler integral computed via scipy.integrate.quad on real contour.
    • CompleteResult: delta_S_complete = delta_S_mock + delta_S_shadow.

  4. Partition congruence suppression (complete_surprise.py)

    • d ≡ 4 (mod 5), d ≡ 5 (mod 7), d ≡ 6 (mod 11) → ΔS = 0 (Ramanujan congruences).

  5. Regime routing (UnifiedSurprise)

    • SUPPRESSED: congruence depths → 0
    • FAST: d ≤ d_crit, Q(G) > 0.01 → Layer 6 TFSA
    • STANDARD: d ≤ d_crit, Q(G) ≤ 0.01 → TASF + shadow
    • DEEP: d > d_crit → Rademacher exact + shadow

Rationale

The exact series provides certified bounds for deep-chain inference where perturbative (OPE) methods lose accuracy. Shadow completion ensures productive contradictions contribute their full topological weight rather than being lost in the mock-modular part.

ADR-007 — Layer 8: Ramanujan Extension (June 2026)

Decision: Import four mathematical structures from Ramanujan's Collected Papers into TORIS as Layer 8 primitives.

Rationale:

  1. Circle method gives O(1)-per-depth surprise computation vs O(|E|^d) brute-force.
  2. Partition congruences provide exact suppression of entire depth classes — no approximation, no compute.
  3. Rapidly convergent 1/π series enables auto-switching goal warp: 3 terms when coherent, full iteration otherwise.
  4. Rogers-Ramanujan product gives closed-form field entropy and critical point detection.

Deviations:

  • Z_F(κ) is approximated via DFS chain enumeration (capped at 5000 nodes) rather than symbolic computation. Documented in DEVIATIONS.md §D-20.
  • ramanujan_3term truncates at n_terms active subgoals rather than using the literal Ramanujan series coefficients for the subgoal correction. The fast convergence property holds for coherent manifolds by the same argument. Documented in DEVIATIONS.md §D-21.

Consequence: All 231 tests pass. Experiments 11, 12, 13 pass. /toris-audit clean.