Add docs/WORKFLOW.md

0e9e120 verified 5 days ago

preview code

Raw

History Blame Contribute Delete

11.5 kB

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:

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:

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:

pipeline = ["input", "memory", "retrieval", "transform", "constraint", "proof", "output"]
(the execution order — this IS the executable artifact)
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

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:

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

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()

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:

{
  "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:

{
  "proof_hash": "...",
  "contract_hash": "...",
  "ssm_state": [...],
  "worm_seal": "...",
  "injection_vector": [...],
  "llm_reply": "..."
}

Where Does the DAG Enter?

The DAG enters at three points:

Specification: ConstraintGraph.xml defines the DAG structure (which node types, which edges)
Compilation: constraint_graph_svg.py applies Kahn's algorithm to the XML → produces the execution order
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.