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:
<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:
<Constraint id="C4" expression="AND(entropy(S1) <= 0.20, entropy(S2) <= 0.20, entropy(S3) <= 0.20)"/>
Consumed by:
sovereign-xml-compiler/constraint_graph_svg.py→ SVG + executable pipeline dictxslt/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:
@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,HKEntropyBoundobjects → 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):
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:
<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:
- Parses XML → node list + edge list
- Validates: raises ValueError if cycle detected (DAG enforcement)
_topological_sort()— Kahn's algorithm_render_svg()— SVG with node boxes + edge arrows- 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:
- Specify the DAG structure (nodes, edges, types)
- Embed formal invariants (entropy bounds, balance axioms)
- Generate Rust source code (via XSLT)
- Drive Python runtime objects (via parser)
- Produce SVG visualization (via constraint_graph_svg.py)
- Provide formal type signatures for Lean 4 (via HOC CDATA blocks)
- Document the system (via generate-readme.xsl)
This is the SnapKitty specification pattern: XML as polyglot specification.