Add docs/WORKFLOW.md

docs/WORKFLOW.md

@@ -0,0 +1,322 @@
+# 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.