cs/integration.md

002 — INTEGRATION SPECIFICATION

Primordial Compute Stack v0.1

Created and Developed by Collin D. Weber

---

Purpose of This Document

This document specifies how the components of the Primordial Compute Stack connect to one another at the interface level. It describes data flows, structural dependencies, and the contract each layer presents to adjacent layers.

This is an integration specification, not an implementation guide. It describes what has been specified and (where applicable) implemented. Where an interface is defined but not yet realized in running code, that is stated explicitly.

---

Interface Architecture

                    HOST SECURITY AGENT
                    (CyberSec Suite / Layer I-B)
                           │
                    evidence packets
                    (process, network, file, triage)
                           │
                           ▼
                    hir_bridge.py
                    [evidence → Action packet]
                           │
                    Action dataclass
                    (gates/action.py schema)
                           │
                           ▼
              ┌────────────────────────┐
              │  HIR KERNEL            │
              │  (Layer I-A Runtime)   │
              │  evaluate(action, env) │
              │  → CycleResult         │
              └────────────────────────┘
                           │
              ┌────────────┴──────────┐
              │                       │
         CycleResult            AuditRecord
         permission_state       (audit/log.py)
         action_taken           append-only chain
         H/I/R scores
         metrics (B,P,S,U,Rn)
              │
              ▼ [if hardware path]
    ┌──────────────────────────┐
    │  HIR-SPU Register File   │    ← Layer II maps this interface
    │  (memory-mapped 0x00–0x74)│      to silicon
    │  EVALUATE_HIR command    │
    │  → PERMISSION_STATE [R]  │
    │  → ACTION_TAKEN [R]      │
    └──────────────────────────┘
              │
              ▼ [if GPU path — architectural only]
    ┌──────────────────────────┐
    │  PCIe evidence stream    │    ← Layer III mapping
    │  N-packet thread blocks  │      (not implemented)
    │  SIMT warp execution     │
    └──────────────────────────┘
              │
              ▼ [if memory path — provisional only]
    ┌──────────────────────────┐
    │  HIR Write Gate          │    ← Layer IV spec
    │  Memory lifecycle FSM    │      (not implemented)
    │  Consolidation / Recall  │
    └──────────────────────────┘

---

Layer I-A → Layer I-B Interface

Status: defined and runnable.

The CyberSec Suite produces structured evidence findings. The hir_bridge.py module translates these findings into HIR action packets conforming to the gates/action.py Action dataclass.

Inbound from CyberSec Suite:

# cybersec_suite/hir_bridge.py
Finding(
    finding_type,      # process | network | file_integrity | audit
    severity,          # low | medium | high | critical
    rule_class,        # from triage_rules.json
    source,            # evidence origin
    details,           # dict of raw finding data
)

Outbound to HIR Kernel:

# gates/action.py
Action(
    action_id,
    actor,
    description,
    source,
    signed,
    signature_valid,
    schema_valid,
    uncertainty_disclosed,
    overstated_confidence,
    declared_scope,
    violates_scope,
    violates_invariant,
    auditable,
    reversible,
    consent_required,
    consent_obtained,
    targets_human,
    coercion_risk,
    domination_pattern,
    life_first_explained,
    freshness_seconds,
)

Bridge translation contract: severity maps to pressure modifiers via triage_rules.json. Critical + destructive remediation maps to violates_invariant=True or triggers the FAIL_CRIT_DESTRUCTIVE flag in the hardware register (bit 5 of FAILURE_FLAGS at 0x6C).

---

Layer I-A → Layer II Interface

Status: architectural specification. Hardware not fabricated.

The OS Runtime kernel and the HIR-SPU hardware share the same logical interface — the difference is the execution substrate. The Python evaluate() function and the SystemVerilog hir_spu_top module implement the same computation. The register file is the hardware expression of the kernel's input/output contract.

Logical equivalence:

Python (Layer I-A)	Hardware Register (Layer II)	Offset
action.schema_valid (bit)	ACTION_FLAGS[3]	0x08
action.signed (bit)	ACTION_FLAGS[1]	0x08
action.domination_pattern (bit)	ACTION_FLAGS[15]	0x08
env.W	W_PRESSURE	0x20
env.F_pressure	F_PRESSURE	0x24
env.A_audit	A_AUDIT	0x28
env.G	G_GRIT	0x2C
diamond.H_score	H_SCORE	0x44
diamond.I_score	I_SCORE	0x48
diamond.R_score	R_SCORE	0x4C
metrics.Rn	RESONANCE_RN	0x60
permission_state	PERMISSION_STATE	0x64
action_taken	ACTION_TAKEN	0x68
audit_record.self_hash	AUDIT_DIGEST_LOW/HIGH	0x70/0x74

Host communication protocol (hardware path):

RESET_STATE
LOAD_ACTION       ← writes ACTION_FLAGS, EVIDENCE_FLAGS
LOAD_FINDING_RECORD ← writes FINDING_TYPE, FINDING_SEVERITY
LOAD_BASELINE_RESULT ← writes BASELINE_STATUS
LOAD_ENV          ← writes W_PRESSURE through R_S
EVALUATE_TRIAGE
EVALUATE_HIR      ← triggers computation
READ_PERMISSION   ← reads PERMISSION_STATE, ACTION_TAKEN
READ_METRICS      ← reads H/I/R/B/P/S/U/Rn
READ_FAILURE_FLAGS ← reads FAILURE_FLAGS
READ_AUDIT_DIGEST ← reads AUDIT_DIGEST_LOW/HIGH
COMMIT_STATE      ← if GREEN/YELLOW permitted

Fixed-point format: Q16.16 (signed 32-bit, 16 integer bits, 16 fractional bits). All normalized [0,1] values are represented as integers 0–65536 (0x0000–0x10000).

---

Layer II → Layer III Interface

Status: architectural mapping only. No CUDA/GPU code exists.

The GPU mapping (Layer III) is derived from analysis of the Layer II RTL structure. The primary finding is that the always_comb block in hir_spu_top.sv contains four fully independent computation paths:

Computation	GPU mapping	Dependency
H gate scoring	WARP 0	None — reads only ACTION_FLAGS, EVIDENCE_FLAGS
I gate scoring	WARP 1	None — reads only ACTION_FLAGS, BASELINE_STATUS
R gate scoring	WARP 2	None — reads only ACTION_FLAGS
Pressure P	WARP 3	None — reads only W_PRESSURE, F_PRESSURE

Post-sync dependencies:

• B = f(H, I, R) — requires warps 0, 1, 2 to complete
• S = f(A_audit, B, P) — requires B and P
• U = f(A_audit, B, G, F_int) — requires B
• Fidelity = sqrt(H × I) — SFU, requires warps 0, 1
• Cohesion = sqrt(R × I) — SFU, requires warps 1, 2
• Resonance = sqrt(Fidelity × Cohesion) — SFU, requires both above

The 8 FAILURE_FLAGS are independent bit predicates evaluable in 8 parallel CUDA threads before the FSM write-back.

N-packet batch throughput: One evidence packet per thread block. N packets = N blocks in-flight simultaneously. This is the SIMT data-parallel model.

---

Layer III → Layer IV Interface

Status: provisional specification only. Neither layer is implemented in code.

The GPU batch compute model and the Resonant Access Memory architecture connect at the retrieval plane. The Recall Score function over a memory population is a natural GPU workload:

For each query q:
    For each memory object Mem_i in population:
        Recall_i(q) = Sim(q,i) × M_i × Rec_i × Trust_i
    Return top-k by Recall_i

This is structurally equivalent to a similarity search with weighted scoring — amenable to Tensor core acceleration for large memory populations (v1.0 implementation path).

Write path (memory admission):

Every CycleResult from the HIR Kernel (Layer I-A) or HIR-SPU (Layer II) produces an AuditRecord. The AuditRecord fields map directly to the Primordial RAM memory object schema:

AuditRecord field	RAM schema field
H_score	H_i
I_score	I_i
R_score	R_i
resonance	Rn_i
input_source	source
timestamp	timestamp
permission_state	part of context
self_hash	prev_hash (chain link)

The RAM Write Gate would therefore receive: Q_i (from schema completeness), P_i (from provenance confidence, mapped from H_score), H_i, I_i, R_i directly from the kernel output.

This is the natural promotion path from computation result → episodic memory candidate.

---

Cross-Layer Safety Invariant Continuity

The same eight safety invariants from the HIR-SPU hardware are preserved through all layers:

Invariant	I-A (Python)	II (RTL)	IV (RAM spec)
Critical destructive lockout	FAIL_CRIT_DESTRUCTIVE flag	failure_flags[5] bit	MEM-INV-1 (H=0 on schema fail)
Domination hard stop	GateResult("R", 0.0, ...)	failure_flags[4]	MEM-INV-2 (permanent quarantine)
Consent hard stop	consent_obtained check	failure_flags[3]	MEM-INV-2 coverage
Schema hard stop	schema_valid check	failure_flags[0]	MEM-INV-1
Audit preservation	AuditLog append-only	audit_digest output	MEM-INV-5 (append-only provenance)
RED = preserve, never erase	action_taken = halt	ACT_HALT encoding	MEM-INV-3 (quarantine ≠ deletion)

---

Audit Chain Continuity

The audit chain is a first-class architectural concern across all layers:

• Layer I-A: audit/log.py — SHA-256 hash-chained AuditRecord sequence, append-only
• Layer II: AUDIT_DIGEST_LOW/HIGH registers — digest output for host-side chain extension
• Layer III: Async DMA to GDDR6 ring buffer — append-only, RED never triggers overwrite
• Layer IV: prev_hash field in memory object schema — chain of custody for every memory object

The chain is architecturally continuous from Python runtime through hardware through GPU through memory. The v0.1 implementation realizes the first link (Layer I-A) in running code.