docs/WORKFLOW.md

# SnapKitty Workflow

**Complete specification-to-execution trace. Every step names an actual file.**

---

## The Actual Workflow

```
HyperKittyConstraintDSL.xml   (specification)
           │
           ├──────────────────────────────────────────────────┐
           ↓                                                   ↓
   xslt/constraint-dsl-to-rust.xsl               hyperkitty_dsl/parser.py
   (XSLT transform)                               (Python parser)
           │                                                   │
           ↓                                                   ↓
   Rust source code                           HKGraph { nodes, edges,
   - Agent struct                               constraints, entropy_bound }
   - UniverseLedger.step()                                     │
   - validity_predicate(                                       ↓
       entropy_nats <= 0.20                    constraint_graph_svg.py
       proof_valid)                            - Kahn's topological sort
           │                                  - pipeline dict (execution order)
           ↓                                  - SVG visualization
   cargo build                                                  │
           │                                                   │
           └──────────────────────┬────────────────────────────┘
                                  ↓
                    SovereignEntropyEngine
                    (entropy vector per token)
                                  │
                                  ↓
                    ConstraintPass.validate(entropy)
                    (entropy <= 0.20 gate)
                                  │
                          pass? ──┤── fail? → HALT
                                  ↓
                    MachineCodeSelector.select(entropy, result)
                    (maps entropy to x86-64 op)
                                  │
                                  ↓
                    SovereignVM.run(program)
                                  │
                                  ↓
                    WORM seal (SHA-256 append-only)
                                  │
                                  ↓
                          Result + receipt
```

---

## Phase-by-Phase Trace

### Phase 1: Specification

**Input:** XML file in one of three schemas:
- `ConstraintGraph` (nodes, edges, DAG structure)
- `HyperKittyConstraintDSL` (full pipeline spec with agents, glyphs, entropy bounds)
- `SymbolicLedgerAlgebra` / `QLGFamily` (algebraic type specifications)

**Files produced:** XML file on disk

**Deterministic:** Yes (manually authored)

**Validated:** Not yet — validation happens at next stage

---

### Phase 2: Meta-Program Execution

**Input:** XML specification file

**Transformation A (XSLT):**
```
xslt/constraint-dsl-to-rust.xsl + HyperKittyConstraintDSL.xml
       → [xsltproc or Saxon]
       → UniverseLedger.rs  (Rust source, AUTO-GENERATED comment)
```

The generated `validity_predicate`:
```rust
pub fn validity_predicate(entry: &JournalEntry) -> bool {
    entry.delta_a + entry.delta_e == entry.delta_l + entry.delta_r   // balance
    && entry.entropy_nats <= 0.20                                     // entropy bound
    && entry.proof_valid                                               // proof gate
}
```

The `0.20` comes from `<EntropyBound>` in the XML. Changing the XML changes the generated code.

**Transformation B (Python):**
```
hyperkitty_dsl/parser.py + HyperKittyConstraintDSL.xml
       → HKGraph { nodes, edges, constraints, entropy_bound=0.20 }
```

**Transformation C (XSLT → C header):**
```
generated/generate-native-config.xsl + QUANTUM-KITTY XML
       → native/include/hyperkitty/generated_config.h
         /* GENERATED FILE — do not edit by hand */
```

**Validated:** Yes (XSLT structural validation, entropy bound preservation baked in)

**Deterministic:** Yes (pure XSLT transforms)

---

### Phase 3: DAG Construction

**Input:** XML graph → Python parser output

**Program:** `sovereign-xml-compiler/constraint_graph_svg.py`

**Transformation:**
```python
nodes, edges = _parse_graph_xml(xml_source)
pipeline = _topological_sort(nodes, edges)   # Kahn's algorithm
# Raises ValueError if cycle detected
svg = _render_svg(nodes, edges, pipeline)
```

**Output:**
1. `pipeline = ["input", "memory", "retrieval", "transform", "constraint", "proof", "output"]`  
   (the execution order — this IS the executable artifact)
2. SVG visualization file

**Validated:** Cycle detection (raises if not a DAG)

**Deterministic:** Yes

---

### Phase 4: Entropy-Based Compilation

**Input:** String tokens (agent operations, kernel names)

**Program:** `sovereign-shadow-compiler/engine/entropy_engine.py`

```python
engine = SovereignEntropyEngine(kernel_map)
entropy_vector = engine.calculate_entropy_vector(tokens)
# entropy_vector: List[complex] — one value per token
```

The entropy vector encodes the input as complex activations over a sparse shadow tree seeded with phase angles `exp(2πi · idx/n)`.

**Validated:**
```python
constraint = ConstraintPass()
result = constraint.validate(entropy)  # checks each |e| <= threshold
```

**Deterministic:** Yes (same input, same phase angles, same output)

---

### Phase 5: Machine Code Selection

**Input:** Entropy vector + constraint result

**Program:** `sovereign-shadow-compiler/codegen/selector.py`

```python
op = selector.select(entropy, result)
# maps abs(entropy.real) % len(KERNEL_MAP) → x86-64 opcode name
kernel_bytes = selector.emit(op)
# returns raw bytes for the selected operation
```

**KERNEL_MAP:** operations like `MOV`, `LOOP`, `HALT`

**Output:** x86-64 byte sequence + operation name

---

### Phase 6: VM Execution

**Input:** Machine program `[{"op": "MOV", "reg": "RDI", "imm": n}, {"op": "LOOP", ...}, {"op": "HALT"}]`

**Program:** `sovereign-shadow-compiler/vm/sovereign_vm.py`

**Output:** `vm_result` dict

---

### Phase 7: WORM Sealing

**Program:** `bob-orchestrator/core/bob.mjs` `worm.seal()`

```javascript
const raw = JSON.stringify({ label, payload, meta, ts, prev })
const seal = createHash('sha256').update(raw).digest('hex')
// prev = SHA-256 of previous event (or quantum seed hash for genesis)
```

**Six distinct WORM ledgers exist:**
| Ledger | Path | Records |
|--------|------|---------|
| Quantum swarm | `bob-orchestrator/data/quantum-swarm-worm.jsonl` | ANU seed + swarm collapse events |
| Tool API | `bob-orchestrator/data/tool-api-worm.jsonl` | Tool invocations |
| BOB FSM | `DEVFLOW-FINANCE/packages/sovereign-router/.bob-worm.jsonl` | Phase-by-phase execution + output hashes |
| Execution | `backend/.worm/execution-ledger.jsonl` | Every bash command + allowlist verdict |
| AVR kernel | `sov-kernel-monster/avr_cold_boot_ledger.jsonl` | QATAAUM cycle invariants |
| Agda proofs | `sov-kernel-monster/PHASE_3_WORM_ATTESTATION.jsonl` | Proof discharge events |

---

## BOB sovereignStep: Complete Trace

This is the most complete single-pipeline trace in the codebase.

**Input:**
```json
{
  "agentId": "...",
  "task": "verify_claim",
  "input": "...",
  "lean4Theorem": "...",
  "adaContractText": "..."
}
```

**Step 0:** ANU QRNG batch → `_quantumSeed` buffer (32 bytes)

**Step 1:** METATRON gate (`metatron.mjs`) → `permitted: true/false`  
If `false`: immediate return, no WORM entry written

**Step 2:** `SHA-256(lean4Theorem)` → `proof_hash`  
Theorem < 10 chars → freeze

**Step 3:** `SHA-256(adaContractText)` → `contract_hash`  
ORACLE class → read-only (gateAdvance returns false)

**Step 4:** `worm.seal('BOB_STEP:{task}', step)` → step seal

**Step 5:** SSM injection vector construction (Float32Array[2048]):
```
dims   0–255:   proof_hash bytes → [-1,1]
dims 256–511:   contract_hash bytes → [-1,1]
dims 512–767:   step WORM seal bytes → [-1,1]
dims 768–2047:  ANU quantum seed bytes, 50/50 blended with METATRON cage
```

**Step 6:** Ada gate check (`ada.gateAdvance(class, injectionValid)`)

**Step 7:** SSM state update:
```
h(t) = 0.9·h(t-1) + 0.1·x_input + inject_norm·0.01
```

**Step 8:** LLM call (Ollama, optional — continues if offline)

**Step 9:** `worm.seal('BOB_STEP_COMPLETE:{task}', result)` → final seal

**Return:**
```json
{
  "proof_hash": "...",
  "contract_hash": "...",
  "ssm_state": [...],
  "worm_seal": "...",
  "injection_vector": [...],
  "llm_reply": "..."
}
```

---

## Where Does the DAG Enter?

The DAG enters at three points:

1. **Specification:** `ConstraintGraph.xml` defines the DAG structure (which node types, which edges)
2. **Compilation:** `constraint_graph_svg.py` applies Kahn's algorithm to the XML → produces the execution order
3. **Governance:** `ICP-DAG.m` enforces that no execution happens without an authorized decision in the governance DAG

The compilation output (pipeline list) becomes the execution order for the Python constraint evaluator.

---

## Where Does SUBLEQ Enter?

Currently: independently. The SUBLEQ attention mechanism (`j-matrix-twin/subleq_attention.ijs`, `DEVFLOW-FINANCE/snapkitty-wasm/src/subleq_vm.rs`) is not yet wired into the main BOB workflow or the XSLT code generation pipeline. It exists as a separate experimental track.

**The missing integration point:** The SUBLEQ VM could replace the LLM call at Step 8 — activation vectors → SUBLEQ routing → context selection, feeding into the SSM state. This is the proposed architectural connection, not yet implemented.

---

## Reproducibility

| Component | Reproducible? | What's needed |
|-----------|:-------------:|---------------|
| SSM computation | ✓ | `proof_hash`, `contract_hash`, `worm_seal`, `quantum_seed` (logged) |
| XSLT code generation | ✓ | XML spec file + Saxon/xsltproc |
| Constraint validation | ✓ | entropy vector (deterministic from input) |
| BOB FSM phases | ✓ (hashes only) | `master_hex` + input — output hashes logged, not raw output |
| WORM chain | ✓ | All inputs logged; chain is deterministic |
| LLM replies | ✗ | Temperature and PRNG seed not logged |
| ANU QRNG seed | ✓ | `master_hex` recorded in quantum-swarm-worm.jsonl |
| Quantum swarm temps | partial | `master_hex` logged; HKDF derivation deterministic from it |

**To reproduce a BOB step:** provide `master_hex` + input + `lean4Theorem` + `adaContractText` + prior agent state. The LLM reply will differ.

---

## Specification → Program Separation

SnapKitty does separate **what** from **how**, but the boundary is:

| Layer | What | Where |
|-------|------|-------|
| XML spec | Declares DAG structure, entropy bound, constraint expressions | `ConstraintGraph.xml`, `HyperKittyConstraintDSL.xml` |
| XSLT | Transforms declaration → implementation | `xslt/*.xsl` |
| Python parser | Turns declaration into runtime objects | `hyperkitty_dsl/parser.py` |
| Rust implementation | Compiled from generated source | `cargo build` |
| VM execution | Runs the selected machine code | `sovereign_vm.py` |

The separation is real but incomplete: the XSLT and Python parser both consume the same XML, but they produce independent outputs (Rust source vs. Python objects) that are not yet connected at runtime.