docs/XML_METADATA.md

# SnapKitty XML and Metadata Architecture

---

## XML Inventory

SnapKitty uses XML in six distinct roles. These are not collapsed.

### XML-001: ConstraintGraph (DAG Specification)

**Path:** `carry-agent/logic/constraint-graph.xml`  
**Schema:** Custom — `<ConstraintGraph>` root with TypedSymbols, BooleanConstraints, RefinementPredicates, DAGNodes, TransformationRules, ProofConditions  
**Purpose:** Machine-readable specification of a constraint DAG  
**Role:** Intermediate representation — not configuration, not documentation

**Structure:**
```xml
<ConstraintGraph>
  <TypedSymbols>          <!-- emoji-typed named symbols -->
  <BooleanConstraints>    <!-- logical constraints including entropy <= 0.20 -->
  <RefinementPredicates>  <!-- per-symbol behavioral predicates -->
  <DAGNodes>              <!-- nodes with emoji labels + directed edges -->
  <TransformationRules>   <!-- input → output transform rules -->
  <ProofConditions>       <!-- formal proof obligations -->
</ConstraintGraph>
```

**Key example:**
```xml
<Constraint id="C4" expression="AND(entropy(S1) &lt;= 0.20, entropy(S2) &lt;= 0.20, entropy(S3) &lt;= 0.20)"/>
```

**Consumed by:**
- `sovereign-xml-compiler/constraint_graph_svg.py` → SVG + executable pipeline dict
- `xslt/constraint-dsl-to-rust.xsl` → Rust source code

**Metadata type:** EXECUTABLE — the `BooleanConstraints` directly control what the generated Rust `validity_predicate` checks.

---

### XML-002: HyperKittyConstraintDSL (Full System Specification)

**Path:** Generated at runtime; parsed by `sovereign-shadow-compiler/hyperkitty_dsl/parser.py`  
**Schema:** `<HyperKittyConstraintDSL version="...">` with Meta, GlyphTable, Nodes, Edges, Constraints, Invariants, EntropyBound  
**Purpose:** Complete behavioral specification of a HyperKitty pipeline stage  
**Role:** Specification + intermediate representation + code-generation input

**Key field:**
```python
@dataclass
class HKEntropyBound:
    metric: str      # e.g., "shannon_nats"
    formula: str     # e.g., "H(X)"
    bound: float     # parsed from "H <= 0.20" → 0.20
```

**Consumed by:**
- Python parser → `HKNode`, `HKEdge`, `HKConstraint`, `HKEntropyBound` objects → runtime
- XSLT transform → Rust code with `validity_predicate(entry.entropy_nats <= 0.20)`

**Metadata type:** EXECUTABLE — `HKEntropyBound.bound` is the runtime threshold, not documentation.

---

### XML-003: XSLT Transforms (Code Generation)

**Paths:** `xslt/*.xsl`  
**Role:** Meta-programs — transform XML specifications into target code

| Transform | Input | Output |
|-----------|-------|--------|
| `constraint-dsl-to-rust.xsl` | `HyperKittyConstraintDSL` XML | Rust: Agent struct, UniverseLedger, `validity_predicate` |
| `agent-dsl-a.xsl` | `AGENT_MSG` XML | Dispatch XML with proof verification (checks 64-char proof field) |
| `agent-dsl-b.xsl` | `AGENT_MSG` XML | Second-pass dispatch transform |
| `qlg-to-rust.xsl` | QLG spec XML | Rust: routing certificate generation, witness vector selection |
| `sla-to-rust.xsl` | `SymbolicLedgerAlgebra` XML | Rust: Lambda type with balance axiom iota=-delta, omega invariant, `ENTROPY_NATS` constant |
| `generate-readme.xsl` | graph/spec XML | Markdown README documentation |
| `generate-site.xsl` | browser XML | HTML site pages |

**Generated `validity_predicate` (from constraint-dsl-to-rust.xsl):**
```rust
pub fn validity_predicate(entry: &JournalEntry) -> bool {
    entry.delta_a + entry.delta_e == entry.delta_l + entry.delta_r
    && entry.entropy_nats <= 0.20
    && entry.proof_valid
}
```

The `0.20` entropy bound is embedded at code generation time from the XML spec. Changing the XML changes the generated code.

---

### XML-004: Higher-Order Contract (HOC) — Lean 4 Type Signatures in XML

**Path:** `seb/verification/lean4/SEB_CHAIN_DETERMINISM_INVARIANT.xml`  
**Schema:** `<SEB_CHAIN_DETERMINISM_INVARIANT version="..." status="VERIFIED">` with HOC, TypeSignature (CDATA), Parameters, Returns, Preconditions, Postconditions  
**Purpose:** Machine-readable formal contract that bridges XML spec and Lean 4 proof  
**Role:** Polyglot specification — drives both documentation and formal verification

**The TypeSignature field contains a dependent type theory expression:**
```xml
<TypeSignature>
<![CDATA[
ChainDeterminism :
  (PayloadSeq : List Payload) ->
  (GenesisTip : Commitment) ->
  (CommitmentFn : Commitment -> Payload -> Commitment) ->
  Sigma (CommitmentSeq : List Commitment) .
    (head CommitmentSeq = GenesisTip) /\
    (forall (i : Fin ...) . step i = CommitmentFn step(i-1) payload(i)) /\
    (forall OtherSeq . valid OtherSeq -> OtherSeq = CommitmentSeq)
]]>
</TypeSignature>
```

This is the same property proved in Lean 4. The XML records the formal statement; the Lean file contains the proof. Status="VERIFIED" is metadata.

**Metadata type:** EXECUTABLE at the verification level — the TypeSignature can be extracted and fed into a Lean 4 elaborator.

---

### XML-005: ConstraintGraph SVG (Visualization + Pipeline)

**Path:** `sovereign-xml-compiler/examples/constraint_graph.xml`  
**Schema:** `<graph>` with `<node id="..." type="..."/>` and `<edge from="..." to="..."/>`  
**Purpose:** Visual representation of the constraint DAG

**Compiled by** `constraint_graph_svg.py`:
1. Parses XML → node list + edge list
2. Validates: raises ValueError if cycle detected (DAG enforcement)
3. `_topological_sort()` — Kahn's algorithm
4. `_render_svg()` — SVG with node boxes + edge arrows
5. Returns both SVG string AND `{ "pipeline": [...sorted node ids...] }` dict

The pipeline dict is immediately executable — it IS the execution order.

---

### XML-006: System Prompt Template (Executable Metadata)

**Path:** `bob-ide/artifacts/bridges/xml-compiler-skeletons/sovereign_prompt.xml`  
**Schema:** `<system_prompt>` with `<identity>`, `<logic_gates>`, `<execution_flow>`  
**Purpose:** Template for generating agent system prompts  
**Role:** Meta-program template — `{{IDENTITY}}`, `{{GATE_N_NAME}}` are substitution variables

**Metadata type:** EXECUTABLE when instantiated — the `<logic_gates>` become the agent's behavioral constraints; the `<execution_flow>` becomes the agent's procedure.

---

## Metadata Architecture: Descriptive vs. Executable

The distinction is non-trivial in SnapKitty:

### Descriptive Metadata (describes, does not control execution)

| Metadata | Where | Content |
|----------|-------|---------|
| `version="1.0"` attributes | XML files | Version tracking only |
| `status="VERIFIED"` | HOC files | Human-readable status |
| `description` text in HOC | XML | Documentation |
| HF model card frontmatter (`license:`, `tags:`) | README.md | Search/discovery |
| WORM chain `label` field | JSON events | Human-readable event description |

### Executable Metadata (controls computation)

| Metadata | Where | How it controls execution |
|----------|-------|--------------------------|
| `HKEntropyBound.bound = 0.20` | XML → Python | Runtime entropy threshold in `ConstraintPass.validate()` |
| `BooleanConstraint expression="..."` | XML | Becomes `validity_predicate` in generated Rust |
| `ENTROPY_NATS` constant in sla-to-rust.xsl | XML → Rust | Compiled into generated code as literal |
| `NodeType` in `<node type="Proof">` | XML | Determines position in pipeline execution order (Kahn's) |
| `proof` field length check in agent-dsl-a.xsl | XML → dispatch XML | Blocks dispatch if proof is not 64 chars |
| `HKNode.type` | XML → Python | Determines which constraint is applied to this node |
| `ICP-DAG node STATE` | MUMPS global | Controls AUTHORIZE/EXECUTE/HALT decision |

**Key principle:** In SnapKitty, metadata is not merely descriptive if it participates in a transformation chain that produces executable code or runtime decisions. The `HKEntropyBound.bound` is the canonical example — it is a number in an XML file that ends up as a literal in generated Rust code and as a runtime threshold in the Python constraint pass.

---

## XML → DAG Generation

The `constraint_graph_svg.py` compiler is the clearest example of XML driving DAG generation:

```
<graph>                         (XML specification)
  <node id="input" type="Input"/>
  <node id="proof" type="Proof"/>
  <edge from="input" to="proof"/>
</graph>
          ↓
  _parse_graph_xml()             (Python parser)
          ↓
  _topological_sort()            (Kahn's algorithm)
          ↓
  { "pipeline": ["input", "proof"] }   (executable pipeline dict)
          +
  SVG visualization              (rendered graph)
```

The same XML produces both the visualization AND the executable execution order. This is the core of SnapKitty's XML architecture: one spec, multiple outputs.

---

## What Role Does Metadata Play?

**Short answer:** In SnapKitty, metadata drives both the specification and the execution. A single XML file can simultaneously:

1. Specify the DAG structure (nodes, edges, types)
2. Embed formal invariants (entropy bounds, balance axioms)
3. Generate Rust source code (via XSLT)
4. Drive Python runtime objects (via parser)
5. Produce SVG visualization (via constraint_graph_svg.py)
6. Provide formal type signatures for Lean 4 (via HOC CDATA blocks)
7. Document the system (via generate-readme.xsl)

This is the SnapKitty specification pattern: **XML as polyglot specification**.