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:**
```python
# 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:**
```python
# 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.