Model card: restore full README from GitHub, add commercial license option

8accf92 verified 8 days ago

62.7 kB

	---
	license: mpl-2.0
	tags:
	- snapkitty
	- october-2026-drop
	- python
	- mustache
	- subleq
	- latin
	- boolean-logic
	- nlp
	- compiler
	- deterministic
	---

	> Mirrored from [https://github.com/SNAPKITTYWEST/semantic-engine](https://github.com/SNAPKITTYWEST/semantic-engine) at commit `b9afd82`. Part of the SnapKitty October 2026 main drop.

	README
	# Semantic Engine: Deterministic NL → IR → Boolean → Latin → SUBLEQ Pipeline

	License: MPL-2.0

	========================================================================
	SOVEREIGN LEVIATHAN NODE LICENSE
	License-ID: SL-AGPL3-001 \| Covenant-Version: 1.0
	Copyright (C) 2026 SnapKittyWest. Ahmad Ali Parr,
	Bel Esprit D'Accord Irrevocable Trust.
	========================================================================

	This work is licensed under dual license terms:

	MPL-2.0 OR GPL-3.0-or-later

	With additional Sovereign Leviathan Node License terms (AGPL-3.0 base).
	Source files are individually licensed under MPL-2.0 (file-level copyleft).
	Commercial repository — no MIT permitted.

	This file is a covered work under the GNU Affero General Public License,
	version 3, together with the Sovereign Leviathan additional terms.

	"Hark, though this node be but a spark,
	Its covenant endureth through the dark.

	Ignorantia juris non excusat."
	========================================================================

	## Table of Contents
	- [Executive Overview](#executive-overview)
	- [Project Vision](#project-vision)
	- [Core Architecture](#core-architecture)
	- [Pipeline Stages](#pipeline-stages)
	- [Pipeline Flowchart](#pipeline-flowchart)
	- [Verification Framework](#verification-framework)
	- [Boolean Engine & CNF Normalization](#boolean-engine--cnf-normalization)
	- [Token Engine & Binary Serialization](#token-engine--binary-serialization)
	- [Latin Canonical Layer](#latin-canonical-layer)
	- [SUBLEQ IR & Virtual Machine](#subleq-ir--virtual-machine)
	- [Verification Flowchart](#verification-flowchart)
	- [Agent Harness](#agent-harness)
	- [CLI Reference](#cli-reference)
	- [Building & Installation](#building--installation)
	- [Testing & Validation](#testing--validation)
	- [Implementation Architecture](#implementation-architecture)
	- [Performance & Design Constraints](#performance--design-constraints)
	- [Contributing & License](#contributing--license)

	---

	## Executive Overview

	Semantic Engine is a 20-phase, deterministic transformation pipeline that converts natural language input into formally verified SUBLEQ machine code, passing through typed IR, Boolean normalization, Latin canonicalization, and templated artifact emission. Every transformation is gated by an explicit finite state machine. Every temporal mutation is tracked. Every output is verified before acceptance.

	### What This Is

	A hand-rolled, zero-dependency semantic compiler implementing:

	- 20-State Finite State Machine: Every phase transition is explicit and typed. Invalid transitions fail closed.
	- Typed Semantic IR: Operations, operands, constraints, geometry, and temporal state — all content-addressed with SHA-256.
	- Boolean CNF Normalization: Full De Morgan, distribution, constant folding, and idempotency guarantees.
	- Binary Token Codec: `decode(encode(x)) == x` for all canonical Boolean structures.
	- Latin Controlled Vocabulary: 28 canonical lexemes, no uncontrolled synonyms, deterministic token→lexeme mapping.
	- SUBLEQ Target Machine: One-instruction computer (`mem[B] -= mem[A]; if mem[B] <= 0: goto C`), 65KB memory, bounded execution.
	- 10-Point Verification Engine: Type correctness, geometry, temporal state, Boolean stability, token round-trip, Latin vocabulary, Rosetta completeness, SUBLEQ halting, artifact provenance, template binding.
	- Agent Harness: Agents propose artifacts; the system verifies before accepting. No agent output bypasses the FSM.
	- Dual Template Backend: Mustache and Go template renderers, both hand-rolled with zero external dependencies.
	- 113 Tests: All round-trip invariants, all edge cases, all phases exercised.

	### Why This Matters

	Semantic transformation is the substrate of every compiler, every code generator, every agent framework, and every formal verification tool. The typical approach is to treat NL→code as a black box (LLM prompt, template engine, or ad-hoc regex). This project makes every stage explicit, every invariant checked, and every intermediate representation inspectable:

	- Auditability: Every transformation records provenance. Every hash chains forward. You can trace any output token back to the original input word.
	- Determinism: Same input → same IR → same Boolean form → same Latin → same SUBLEQ → same artifact. No randomness, no model variance, no hidden state.
	- Composability: Each phase is a pure function gated by the FSM. Phases can be tested, replaced, or extended independently.
	- Formal Target: SUBLEQ is Turing-complete with one instruction. If it compiles to SUBLEQ and the VM halts, the program is well-defined.

	The pipeline processes natural language at the rate of ~300 inputs/second on a single core (113 tests in 0.38s), with zero external dependencies beyond Python 3.11.

	### Semantic IR: The Central Data Structure

	The entire pipeline orbits a single typed intermediate representation. Every transformation reads from or writes to the `SemanticIR`:

	```python
	@dataclass
	class SemanticIR:
	ir_id: str # UUID, unique per pipeline run
	intent: IntentClass # BUILD, TRANSFORM, VALIDATE, ...
	root: SemanticNode # root of the semantic tree
	nodes: list[SemanticNode] # all nodes in the IR
	temporal_lock: TemporalLock # audit log of τ transitions
	provenance: Provenance # source_input_id, stage, transform_hash
	verification_state: VerificationState # UNVERIFIED → VERIFIED → REJECTED
	output_mode: str # natural_language, code, artifact
	metadata: dict[str, Any] # extensible
	```

	Each `SemanticNode` carries:
	- Operation: name, arity, commutativity, associativity
	- Operands: typed, named, with optional geometry
	- Constraints: predicate strings that become Boolean variables
	- Geometry: row/col/shape for dimensional checking
	- Temporal state: current τ value
	- Provenance: SHA-256 chain from input to current stage
	- Children: sub-nodes for recursive structures

	Every node, operation, constraint, and the IR itself produce deterministic SHA-256 hashes from their content. Two pipeline runs with the same input produce byte-identical hashes at every stage.

	### Provenance Chain

	```python
	@dataclass(frozen=True)
	class Provenance:
	source_input_id: str # ties back to RawInput.input_id
	stage: str # which pipeline phase
	timestamp: float # wall clock
	parent_id: Optional[str] # previous provenance (for chaining)
	transform_hash: str # SHA-256 of the transformation applied
	```

	The `chain_hash` method computes `SHA-256(transform_hash + ":" + data)`, extending the hash chain at each stage. This means any modification to any intermediate — even a single bit flip — produces a completely different hash at the artifact stage.

	---

	## Project Vision

	We believe semantic transformation requires:

	1. Explicit State Machines: Not implicit control flow. Every legal transition is enumerated. Every illegal transition fails closed.
	2. Temporal Accountability: Every mutation advances τ. Read-only passes preserve τ. Locked states cannot be modified.
	3. Dimensional Safety: Matrix operations carry geometry. Contraction mismatches are caught before SUBLEQ assembly.
	4. Controlled Vocabulary: No synonym drift. Latin lexemes map 1:1 to semantic IDs. The Rosetta table is the single source of truth for machine translation.
	5. Verified Emission: No artifact leaves the pipeline without passing all 10 verification checks.

	This project demonstrates that a complete NL→machine-code pipeline can be built from first principles: no frameworks, no LLM dependencies (BERT is optional), no external template engines, no runtime magic.

	---

	## Core Architecture

	```
	semantic-engine/
	├── cli/main.py # Phase 18: 11 CLI subcommands
	├── src/semantic_engine/
	│ ├── __init__.py # Public API: SemanticPipeline, PipelineResult
	│ ├── types.py # Phase 1: Enums, error hierarchy, input types
	│ ├── ir.py # Phase 2: Typed IR — nodes, geometry, temporal, artifacts
	│ ├── fsm.py # Phase 3: 20-state FSM, typed transition table
	│ ├── temporal.py # Phase 4: τ-advancing transforms, violation detection
	│ ├── geometry.py # Phase 5: Matrix dimension checking, GeometryError
	│ ├── matrix.py # Phase 6: SemanticMatrix builder, compose/transform
	│ ├── boolean_engine.py # Phase 7: CNF normalization, De Morgan, simplification
	│ ├── token_engine.py # Phase 8: Binary encode/decode, round-trip invariant
	│ ├── latin.py # Phase 9: Controlled vocabulary, token→lexeme map
	│ ├── lexer.py # Phase 10: Regex Latin lexer, fail-closed on unknowns
	│ ├── rosetta.py # Phase 11: Rosetta table, semantic_id → SUBLEQ op
	│ ├── subleq.py # Phases 12–13: SUBLEQ VM, assembler, disassembler
	│ ├── verifier.py # Phase 14: 10 independent verification checks
	│ ├── artifacts.py # Phases 15–16: Mustache + Go template renderers
	│ ├── agent_harness.py # Phase 17: Agent proposal/verify/accept loop
	│ ├── nlp.py # NLP: tokenization, intent, entity, BERT interface
	│ └── pipeline.py # Full pipeline orchestrator
	├── lexicon/latin_vocabulary.json # 28 canonical Latin lexemes
	├── mappings/rosetta_table.json # 24 semantic_id → SUBLEQ operation mappings
	├── templates/
	│ ├── prompt.mustache # Natural language artifact template
	│ ├── document.mustache # Document artifact template
	│ └── backend.go.tmpl # Go backend artifact template
	├── examples/
	│ ├── matrix_multiply.txt # "multiply two matrices A and B..."
	│ ├── parse_binary_format.txt # "build a parser for this binary format..."
	│ └── validate_packets.txt # "create a backend service that validates packets"
	├── tests/ # 113 tests across 7 test modules
	├── pyproject.toml # Python 3.11+, zero required dependencies
	└── LICENSE # MPL-2.0
	```

	4,143 lines of source (18 modules + CLI + 7 test files). Zero stubs. Zero `pass` placeholders.

	---

	## Pipeline Stages

	\| Phase \| Module \| Input \| Output \| Invariant \|
	\|-------\|--------\|-------\|--------\|-----------\|
	\| 1 \| `types.py` \| — \| Enums, error types, input structs \| Type safety via frozen dataclasses \|
	\| 2 \| `ir.py` \| — \| SemanticIR, SemanticNode, Artifact \| Content-addressed (SHA-256) \|
	\| 3 \| `fsm.py` \| `(state, input_class)` \| `FSMTransition` \| Fail-closed on missing transitions \|
	\| 4 \| `temporal.py` \| `TemporalState(τ)` \| `TemporalState(τ+1)` \| τ monotonic, locked states reject \|
	\| 5 \| `geometry.py` \| `Geometry(m×n)` \| `DimCheck` \| A.col == B.row for matmul \|
	\| 6 \| `matrix.py` \| `SemanticNode` \| `SemanticMatrix` \| Composition: a.cols == b.rows \|
	\| 7 \| `boolean_engine.py` \| Constraints \| `BooleanNormalForm` (CNF) \| normalize(normalize(x)) == normalize(x) \|
	\| 8 \| `token_engine.py` \| Boolean IR \| `BooleanTokenStream` / bytes \| decode(encode(x)) == x \|
	\| 9 \| `latin.py` \| Token stream \| `LatinCanonicalForm` \| Every token maps to exactly one Latin lexeme \|
	\| 10 \| `lexer.py` \| Latin text \| `LexResult` \| Unknown tokens fail closed \|
	\| 11 \| `rosetta.py` \| Latin form \| `RosettaMapping` \| All semantic_ids must map (no unmapped) \|
	\| 12–13 \| `subleq.py` \| Rosetta mapping \| `SubleqProgram` / VM trace \| Program halts within 10K steps \|
	\| 14 \| `verifier.py` \| All intermediates \| `VerificationReport` \| 10 independent checks, UNVERIFIED→VERIFIED→REJECTED \|
	\| 15–16 \| `artifacts.py` \| SemanticIR + template \| `Artifact` \| Mustache + Go renderers, provenance chain intact \|
	\| 17 \| `agent_harness.py` \| `AgentTask` \| Verified `Artifact` \| Agent proposals verified before acceptance \|
	\| 18 \| `cli/main.py` \| File path \| Formatted output \| 11 subcommands + trace flags \|
	\| 19–20 \| `tests/` \| — \| 113 assertions \| All round-trip invariants exercised \|

	---

	## Finite State Machine

	The FSM (`fsm.py`, 128 lines) defines exactly 21 transitions across 20 states plus an ERROR sink. Every transition is a typed record:

	```python
	@dataclass(frozen=True)
	class FSMTransition:
	source_state: FSMState # where we are
	input_class: str # what arrived
	operation: str # what to do
	constraints: tuple[str, ...] # what must hold
	destination_state: FSMState # where we go
	invariant: str # human-readable guarantee
	```

	### Complete Transition Table

	\| Source State \| Input Class \| Operation \| Destination \| Constraint \|
	\|-------------\|-------------\|-----------\|-------------\|------------\|
	\| INPUT \| raw_input \| normalize \| NORMALIZE \| text_not_empty \|
	\| NORMALIZE \| normalized_input \| lex \| LEXICAL_ANALYSIS \| tokens_non_empty \|
	\| LEXICAL_ANALYSIS \| token_stream \| detect_intent \| INTENT_DETECTION \| tokens_recognized \|
	\| INTENT_DETECTION \| intent_class \| bind_entities \| ENTITY_BINDING \| intent_not_unknown \|
	\| ENTITY_BINDING \| entities \| bind_semantics \| SEMANTIC_BINDING \| entities_typed \|
	\| SEMANTIC_BINDING \| semantic_candidate \| lock_temporal \| TEMPORAL_LOCK \| candidate_valid \|
	\| TEMPORAL_LOCK \| temporal_state \| bind_geometry \| GEOMETRY_BINDING \| tau_monotonic \|
	\| GEOMETRY_BINDING \| geometry \| build_matrix \| MATRIX_FORM \| geometry_consistent \|
	\| MATRIX_FORM \| semantic_matrix \| resolve_boolean \| BOOLEAN_ROOT \| matrix_well_formed \|
	\| BOOLEAN_ROOT \| boolean_expr \| normalize_boolean \| BOOLEAN_NORMALIZATION \| boolean_valid \|
	\| BOOLEAN_NORMALIZATION \| normalized_boolean \| tokenize \| TOKENIZATION \| normal_form_stable \|
	\| TOKENIZATION \| token_stream \| canonicalize_latin \| LATIN_CANONICALIZATION \| tokens_round_trip \|
	\| LATIN_CANONICALIZATION \| latin_form \| lex_latin \| LATIN_LEXING \| vocabulary_closed \|
	\| LATIN_LEXING \| latin_tokens \| map_rosetta \| ROSETTA_MAPPING \| latin_tokens_valid \|
	\| ROSETTA_MAPPING \| rosetta_mapping \| build_subleq \| SUBLEQ_IR \| mapping_complete \|
	\| SUBLEQ_IR \| subleq_program \| verify \| VERIFICATION \| subleq_valid \|
	\| VERIFICATION \| verified_ir \| select_artifact \| ARTIFACT_SELECTION \| all_checks_pass \|
	\| ARTIFACT_SELECTION \| artifact_type \| emit \| EMISSION \| template_bound \|
	\| EMISSION \| artifact \| complete \| COMPLETE \| artifact_provenance_ok \|
	\| COMPLETE \| done \| noop \| COMPLETE \| (terminal) \|
	\| INPUT \| invalid \| fail \| ERROR \| error_logged \|

	The transition map is indexed by `(source_state, input_class)`. Any `(state, input)` pair not in the table triggers fail-closed behavior: the FSM transitions to ERROR and raises `PipelineError`.

	### Constraint Validators

	Each constraint in the transition table maps to a validator function:

	```python
	"text_not_empty": lambda ctx: bool(str(ctx.get("raw_text")).strip())
	"tokens_non_empty": lambda ctx: bool(ctx.get("tokens"))
	"intent_not_unknown": lambda ctx: ctx.get("intent") != "unknown"
	"all_checks_pass": lambda ctx: ctx.get("verified") is True
	"template_bound": lambda ctx: ctx.get("template") is not None
	"artifact_provenance_ok": lambda ctx: ctx.get("artifact") is not None
	```

	Constraints that are enforced by exception (e.g., geometry, temporal) use pass-through validators — the corresponding module raises before the validator runs.

	### FSM Context

	The `FSMContext` carries state, history, data bag, and error:

	```python
	ctx = FSMContext() # state=INPUT
	ctx.transition("raw_input") # → NORMALIZE
	ctx.transition("normalized_input") # → LEXICAL_ANALYSIS
	# ...19 transitions later...
	ctx.transition("artifact") # → COMPLETE
	assert ctx.is_terminal() # True

	# Full audit trail
	for line in ctx.dump_history():
	print(line)
	# INPUT --[raw_input]--> NORMALIZE
	# NORMALIZE --[normalized_input]--> LEXICAL_ANALYSIS
	# ...
	```

	---

	## Pipeline Flowchart

	```
	┌─────────────────────────────────────────────────────────────────────────┐
	│ Semantic Engine Pipeline │
	│ NL Input → Semantic IR → Boolean → Latin → SUBLEQ → Artifact │
	└─────────────────────────────────────────────────────────────────────────┘

	START
	│
	▼
	┌───────────────────────────────┐
	│ RawInput(text, source, id) │
	│ SHA-256 hash computed │
	└───────────────────────────────┘
	│
	▼
	┌───────────────────────────────┐
	│ Phase 1–2: NORMALIZE │
	│ Tokenize → segment sentences │
	│ Rule-based + optional BERT │
	└───────────────────────────────┘
	│
	▼
	┌───────────────────────────────┐
	│ Phase 3–6: SEMANTIC BINDING │
	│ Intent → Entities → Constraints│
	│ Temporal lock (τ₀ → τ₁) │
	│ Geometry enforcement │
	│ SemanticMatrix construction │
	└───────────────────────────────┘
	│
	▼
	┌───────────────────────────────┐
	│ Phase 7: BOOLEAN ENGINE │
	│ Constraints → CNF expression │
	│ De Morgan + distribute OR/AND │
	│ Idempotency: f(f(x)) = f(x) │
	└───────────────────────────────┘
	│
	▼
	┌───────────────────────────────┐
	│ Phase 8: TOKEN ENGINE │
	│ Boolean IR → binary tokens │
	│ Magic: BOOL \| Version: 1 │
	│ Round-trip: decode∘encode = id │
	└───────────────────────────────┘
	│
	▼
	┌───────────────────────────────┐
	│ Phase 9–10: LATIN LAYER │
	│ Tokens → Latin lexemes │
	│ ET VEL NON AUT SI VERUM FALSUM │
	│ Regex lexer, fail-closed │
	└───────────────────────────────┘
	│
	▼
	┌───────────────────────────────┐
	│ Phase 11: ROSETTA MAPPING │
	│ semantic_id → SUBLEQ op │
	│ 24 entries, all must map │
	└───────────────────────────────┘
	│
	▼
	┌───────────────────────────────┐
	│ Phases 12–13: SUBLEQ │
	│ Assemble → flat binary │
	│ VM: 65KB memory, bounded exec │
	│ SUBLEQ(A,B,C): │
	│ mem[B] -= mem[A] │
	│ if mem[B] ≤ 0: goto C │
	└───────────────────────────────┘
	│
	▼
	┌───────────────────────────────┐
	│ Phase 14: VERIFICATION │
	│ 10 independent checks │
	│ UNVERIFIED → VERIFIED │
	│ or → REJECTED (fail closed) │
	└───────────────────────────────┘
	│
	▼
	┌───────────────────────────────┐
	│ Phases 15–17: ARTIFACT │
	│ Template selection + rendering │
	│ Mustache or Go template │
	│ Agent harness (if applicable) │
	└───────────────────────────────┘
	│
	▼
	COMPLETE
	┌──────────────────┐
	│ PipelineResult │
	│ .ir │
	│ .artifact │
	│ .subleq_listing │
	│ .trace[] │
	│ .hashes{} │
	│ .ok │
	└──────────────────┘
	```

	---

	## Verification Framework

	The Verifier runs 10 independent checks. All must pass before any artifact is emitted.

	\| # \| Check \| What It Verifies \| Failure Mode \|
	\|---\|-------\|------------------\|--------------\|
	\| 1 \| `type_correctness` \| Operation arity matches operand count \| `VerificationError` \|
	\| 2 \| `geometry` \| Matrix contraction dimensions (A.col == B.row) \| `GeometryError` \|
	\| 3 \| `temporal_state` \| All τ transitions are +1 or +0 (no jumps) \| `TemporalViolation` \|
	\| 4 \| `boolean_normalization` \| `normalize(normalize(x)) == normalize(x)` \| `VerificationError` \|
	\| 5 \| `token_round_trip` \| `decode(encode(stream)) == stream` \| `TokenError` \|
	\| 6 \| `latin_vocabulary` \| Every lexeme exists in the controlled vocabulary \| `PipelineError` \|
	\| 7 \| `rosetta_mapping` \| All semantic_ids have SUBLEQ mappings \| `RosettaError` \|
	\| 8 \| `subleq_validity` \| Program halts within 10,000 steps \| `PipelineError` \|
	\| 9 \| `artifact_provenance` \| Artifact.semantic_root == IR.ir_id \| `VerificationError` \|
	\| 10 \| `template_bindings` \| Template is bound and content is non-empty \| `VerificationError` \|

	### Verification State Machine

	```
	UNVERIFIED
	│
	▼
	VALIDATING ──── checks running
	/ \
	▼ ▼
	VERIFIED REJECTED
	│
	▼
	Artifact emitted
	```

	### Error Hierarchy

	```
	PipelineError(stage, message, input_ref)
	├── GeometryError — dimension mismatch
	├── TemporalViolation — illegal τ mutation
	├── VerificationError — check failed
	├── TokenError — binary codec failure
	└── RosettaError — unmapped semantic_id
	```

	Every error carries the FSMState where the failure occurred, enabling precise diagnostics.

	---

	## Boolean Engine & CNF Normalization

	The Boolean engine converts semantic constraints into Conjunctive Normal Form through a deterministic pipeline:

	### Expression Types

	\| Type \| Representation \| Example \|
	\|------\|---------------\|---------\|
	\| `BooleanLiteral` \| `⊤` / `⊥` \| True, False \|
	\| `BooleanVar` \| `x` / `¬x` \| Variable with optional negation \|
	\| `BooleanExpression` \| `(x ∧ y)` \| Tree of operator + operands \|

	### Operators

	\| Operator \| Symbol \| Latin Lexeme \| SUBLEQ Op \|
	\|----------\|--------\|-------------\|-----------\|
	\| AND \| ∧ \| ET \| AND \|
	\| OR \| ∨ \| VEL \| OR \|
	\| NOT \| ¬ \| NON \| NOT \|
	\| XOR \| ⊕ \| AUT \| XOR \|
	\| IMPLIES \| → \| SI \| OR(¬a, b) \|
	\| EQUIVALENCE \| ↔ \| IFF \| XNOR \|
	\| TRUE \| ⊤ \| VERUM \| LOAD_1 \|
	\| FALSE \| ⊥ \| FALSUM \| LOAD_0 \|

	### Normalization Pipeline

	1. Simplify: Constant folding, double-negation elimination (`¬¬A → A`), identity removal
	2. Push NOT inward: De Morgan's laws (`¬(A ∧ B) → ¬A ∨ ¬B`, `¬(A ∨ B) → ¬A ∧ ¬B`)
	3. Distribute OR over AND: Produce CNF (`A ∨ (B ∧ C) → (A ∨ B) ∧ (A ∨ C)`)
	4. Simplify again: Clean up redundant terms

	### Rewrite Rules

	```
	A → B ≡ ¬A ∨ B
	A ↔ B ≡ (A → B) ∧ (B → A)
	A ⊕ B ≡ (A ∨ B) ∧ ¬(A ∧ B)
	¬(A ∧ B) ≡ ¬A ∨ ¬B (De Morgan)
	¬(A ∨ B) ≡ ¬A ∧ ¬B (De Morgan)
	¬¬A ≡ A (Double negation)
	A ∧ ⊥ ≡ ⊥ (Annihilation)
	A ∨ ⊤ ≡ ⊤ (Annihilation)
	A ∧ ⊤ ≡ A (Identity)
	A ∨ ⊥ ≡ A (Identity)
	```

	### Idempotency Guarantee

	```python
	bnf = normalize(expr)
	assert repr(normalize(bnf)) == repr(bnf) # Always holds
	```

	---

	## Token Engine & Binary Serialization

	The token engine serializes Boolean IR into a compact binary format and reconstructs it losslessly.

	### Binary Format

	```
	Offset Size Field
	────── ──── ─────
	0 4 Magic: "BOOL" (0x424F4F4C)
	4 1 Version: 0x01
	5 2 Token count (big-endian uint16)
	7+ var Token records:
	1 byte token_type
	1 byte arity
	2 bytes payload_length (big-endian uint16)
	N bytes payload
	```

	### Token Type Constants

	\| ID \| Name \| Meaning \|
	\|----\|------\|---------\|
	\| `0x01` \| LITERAL \| Boolean literal (payload: `\x01`=true, `\x00`=false) \|
	\| `0x02` \| VAR \| Variable (payload: UTF-8 name) \|
	\| `0x03` \| VAR_NEG \| Negated variable \|
	\| `0x10` \| AND \| Conjunction \|
	\| `0x11` \| OR \| Disjunction \|
	\| `0x12` \| NOT \| Negation \|
	\| `0x13` \| XOR \| Exclusive or \|
	\| `0x14` \| IMPLIES \| Material conditional \|
	\| `0x15` \| EQUIVALENCE \| Biconditional \|
	\| `0x20` \| TRUE \| Verum constant \|
	\| `0x21` \| FALSE \| Falsum constant \|
	\| `0x30` \| OPEN \| Expression open \|
	\| `0x31` \| CLOSE \| Expression close \|
	\| `0x40` \| ARITY \| Arity marker \|

	### Round-Trip Invariant

	```python
	from semantic_engine.token_engine import encode, decode, round_trip

	expr = AND(var("x"), OR(var("y"), NOT(var("z"))))
	assert repr(round_trip(expr)) == repr(expr) # Always holds
	```

	This invariant is checked by the verifier at Phase 14 — no artifact can emit if the round-trip fails.

	---

	## Latin Canonical Layer

	The Latin layer provides a controlled vocabulary between Boolean tokens and SUBLEQ machine operations. Every token type maps to exactly one Latin lexeme. No uncontrolled synonyms exist.

	### Controlled Vocabulary (28 lexemes)

	\| Latin \| Semantic ID \| Operator \| Arity \|
	\|-------\|------------\|----------\|-------\|
	\| ET \| BOOL_AND \| AND \| 2 \|
	\| VEL \| BOOL_OR \| OR \| 2 \|
	\| NON \| BOOL_NOT \| NOT \| 1 \|
	\| AUT \| BOOL_XOR \| XOR \| 2 \|
	\| SI \| BOOL_IMPLIES \| IMPLIES \| 2 \|
	\| IFF \| BOOL_EQUIV \| EQUIVALENCE \| 2 \|
	\| VERUM \| BOOL_TRUE \| TRUE \| 0 \|
	\| FALSUM \| BOOL_FALSE \| FALSE \| 0 \|
	\| INITIUM \| DELIM_OPEN \| — \| 0 \|
	\| FINIS \| DELIM_CLOSE \| — \| 0 \|
	\| OPUS \| SEMANTIC_OP \| — \| var \|
	\| FORMA \| SEMANTIC_MATRIX \| — \| var \|
	\| TEMPUS \| TEMPORAL_STATE \| — \| 0 \|
	\| COMPUTA \| OP_COMPUTE \| compute \| 1 \|
	\| MULTIPLICA \| OP_MULTIPLY \| multiply \| 2 \|
	\| ADDE \| OP_ADD \| add \| 2 \|
	\| SUBTRAHE \| OP_SUBTRACT \| subtract \| 2 \|
	\| PARSE \| OP_PARSE \| parse \| 1 \|
	\| AEDIFICA \| OP_BUILD \| build \| 1 \|
	\| GENERA \| OP_GENERATE \| generate \| 1 \|
	\| VERIFICA \| OP_VALIDATE \| validate \| 1 \|
	\| CONVERTE \| OP_TRANSFORM \| transform \| 2 \|
	\| RESTITUE \| OP_RECONSTRUCT \| reconstruct \| 1 \|
	\| MATRIX \| ENTITY_MATRIX \| — \| 0 \|
	\| VECTOR \| ENTITY_VECTOR \| — \| 0 \|
	\| PARSER \| ENTITY_PARSER \| — \| 0 \|
	\| SERVITIUM \| ENTITY_SERVICE \| — \| 0 \|
	\| FORMA_BINARIA \| ENTITY_BINARY_FORMAT \| — \| 0 \|

	### Example Canonical Form

	Input: `"build a parser for this binary format deterministically"`

	Latin output: `INITIUM ET OPUS[deterministic] FINIS`

	The Latin lexer (`lexer.py`) validates the output with regex patterns and rejects any token not in the controlled vocabulary.

	---

	## SUBLEQ IR & Virtual Machine

	SUBLEQ is a one-instruction computer: `SUBLEQ A, B, C` means `mem[B] -= mem[A]; if mem[B] <= 0: goto C`.

	### Machine Specification

	\| Parameter \| Value \|
	\|-----------\|-------\|
	\| Memory \| 65,536 cells (64KB) \|
	\| Word size \| 16-bit signed integer \|
	\| Instruction format \| 3 words: A, B, C \|
	\| Binary encoding \| Big-endian, 6 bytes per instruction \|
	\| Halt condition \| Branch to address -1 \|
	\| Built-in addresses \| 0 (zero), 1 (one), 2 (temp) \|
	\| Program base \| Address 100 \|
	\| Data allocation \| Bump allocator from address 256+ \|
	\| Max steps \| 100,000 (configurable) \|

	### Rosetta → SUBLEQ Assembly

	Each Rosetta entry maps to one or more SUBLEQ instructions:

	```
	BOOL_AND → SUBLEQ 0, out, next ; AND: allocate + clear
	BOOL_NOT → SUBLEQ a, 1, next2 ; NOT: subtract from 1
	SUBLEQ 0, out, next ; store result
	TICK → SUBLEQ 0, out, next ; temporal marker
	NOP → SUBLEQ 0, 0, next ; no-op passthrough
	HALT → SUBLEQ 0, 0, -1 ; terminal
	```

	### VM Trace

	Every instruction execution records a `VMTrace`:

	```python
	@dataclass
	class VMTrace:
	step: int # execution step counter
	pc: int # program counter
	A: int # source address
	B: int # destination address
	C: int # branch address
	mem_b_before: int # mem[B] before subtraction
	mem_b_after: int # mem[B] after subtraction
	branched: bool # whether branch was taken
	```

	### SUBLEQ VM Walk-Through

	Consider a simple assembled program with 3 instructions:

	```
	Address Instruction Comment
	────── ────────────── ───────
	100 SUBLEQ 0, 256, 109 ; AND: clear cell 256
	106 SUBLEQ 0, 0, 115 ; NOP: passthrough
	112 SUBLEQ 0, 0, -1 ; HALT
	```

	Execution trace:

	\| Step \| PC \| A \| B \| C \| mem[B] before \| mem[B] after \| Branch? \|
	\|------\|----\|---\|---\|---\|---------------\|-------------\|---------\|
	\| 0 \| 100 \| 0 \| 256 \| 109 \| 0 \| 0 (0-0) \| YES (0≤0) → PC=109 \|
	\| 1 \| 106 \| 0 \| 0 \| 115 \| 0 \| 0 (0-0) \| YES (0≤0) → PC=115 \|
	\| 2 \| 112 \| 0 \| 0 \| -1 \| 0 \| 0 (0-0) \| YES (0≤0) → HALT (C=-1) \|

	The program halts in 3 steps. The verifier confirms halting and sets `subleq_validity: PASSED`.

	### Assemble / Disassemble Round-Trip

	```python
	prog = SubleqProgram()
	prog.add(SubleqInstruction(A=0, B=0, C=-1, comment="HALT"))

	# Assemble to binary: 6 bytes (3 × int16 big-endian)
	binary = prog.assemble()
	assert binary == b'\x00\x00\x00\x00\xff\xff'

	# Disassemble back
	prog2 = SubleqProgram.disassemble(binary)
	assert prog2.instructions[0].A == 0
	assert prog2.instructions[0].C == -1
	```

	### Address Allocation

	The assembler uses a bump allocator starting at address 256 (0–255 reserved for VM built-ins). Each SUBLEQ operation that needs scratch space calls `_alloc(n)` to reserve `n` contiguous cells. This ensures no two operations share memory, preventing aliasing bugs.

	### Halting Verification

	The verifier runs the SUBLEQ program in a sandboxed VM (separate memory instance, max 10K steps). If the program does not halt, verification fails and the artifact is rejected. The sandboxed VM is a completely separate `SubleqMemory` instance — it cannot affect the pipeline's state.

	---

	## Verification Flowchart

	```
	┌──────────────────────────────────────────────────────────────────────────┐
	│ Verification Engine │
	│ 10 Independent Checks — All Must Pass │
	└──────────────────────────────────────────────────────────────────────────┘

	SemanticIR
	│
	┌──────────┼───────────┐
	│ │ │
	▼ ▼ ▼
	Type Geometry Temporal
	Check Check Check
	│ │ │
	└──────────┼───────────┘
	│
	BooleanNormalForm
	│
	▼
	Normalization
	Idempotency Check
	│
	▼
	BooleanTokenStream
	│
	▼
	Round-Trip Check
	encode → decode → compare
	│
	▼
	LatinCanonicalForm
	│
	▼
	Vocabulary Check
	all lexemes in vocab?
	│
	▼
	RosettaMapping
	│
	▼
	Completeness Check
	all semantic_ids mapped?
	│
	▼
	SubleqProgram
	│
	▼
	Halting Check
	VM executes < 10K steps?
	│
	▼
	Artifact
	/ \
	▼ ▼
	Provenance Template
	Check Binding Check
	\ /
	▼ ▼
	┌──────────────────┐
	│ All 10 passed? │
	└──────────────────┘
	YES │ │ NO
	▼ ▼
	VERIFIED REJECTED
	│
	▼
	Artifact emitted
	```

	---

	## Semantic Matrix Layer

	The matrix layer (`matrix.py`, 172 lines) represents semantic operations as structured matrix forms. A `SemanticMatrix` is not a numerical matrix — it captures the structure of an operation (operand slots, geometry, relationships) in a matrix-like layout.

	### Matrix Layouts by Operation Type

	Matrix multiply (`matmul`): 3×3 layout
	```
	[A_input] [contraction] [B_input]
	[m_dim] [n_dim] [p_dim]
	[output_C] [(m×p)] [—]
	```

	Binary operation (`add`, `subtract`): 2×2 layout
	```
	[A_input] [B_input]
	[result] [—]
	```

	Generic operation: Nx2 layout (one row per operand)
	```
	[operand_1_input] [output]
	[operand_2_input] [output]
	[...] [...]
	```

	### SemanticCell

	Each cell in the matrix carries:
	```python
	@dataclass
	class SemanticCell:
	row: int # position
	col: int # position
	operand: Optional[Operand] # bound operand (if any)
	label: str # display name
	role: str # "input", "output", "contraction", "constraint", "dim"
	```

	### Matrix Composition

	Two semantic matrices can be composed (analogous to function composition):

	```python
	composed = transform(matrix_a, matrix_b)
	# Requires: a.cols == b.rows
	# Output: SemanticMatrix(rows=a.rows, cols=b.cols)
	# Operation name: "multiply∘validate"
	```

	If `a.cols != b.rows`, the composition raises `GeometryError`.

	---

	## Artifact Templates

	Phases 15–16 (`artifacts.py`, 237 lines) provide two hand-rolled template renderers — no external dependencies.

	### Mustache Renderer

	Supports:
	- `{{variable}}` — simple variable substitution
	- `{{#section}} ... {{/section}}` — truthy sections and list iteration
	- `{{^section}} ... {{/section}}` — inverted (falsy) sections

	Example template (`templates/prompt.mustache`):
	```mustache
	{{title}}

	{{semantic_description}}

	{{#constraints}}
	- Constraint: {{.}}
	{{/constraints}}

	{{#operations}}
	- Operation: {{.}}
	{{/operations}}
	```

	### Go Template Renderer

	Supports a subset of Go's `text/template`:
	- `{{.Field}}` — dot-field access
	- `{{range .Items}} ... {{end}}` — list iteration
	- `{{if .Cond}} ... {{end}}` — conditional sections

	Example template (`templates/backend.go.tmpl`):
	```go
	package {{.Package}}

	{{range .Operations}}
	func {{.Name}}({{range .Params}}{{.Name}} {{.Type}}, {{end}}) (interface{}, error) {
	{{.Body}}
	}
	{{end}}
	```

	### Artifact Types

	\| Type \| Template \| Use Case \|
	\|------\|----------\|----------\|
	\| PROMPT \| prompt.mustache \| LLM-ready natural language \|
	\| DOCUMENT \| document.mustache \| Human-readable documentation \|
	\| BACKEND \| backend.go.tmpl \| Go source code skeleton \|
	\| SOURCE \| — \| Generic source output \|
	\| CONFIG \| — \| Configuration files \|
	\| TEST \| — \| Test specifications \|
	\| SCHEMA \| — \| JSON/protocol schemas \|
	\| REPORT \| — \| Verification reports \|

	---

	## Agent Harness

	Phase 17 defines a verification-first agent interface. Agents are functions that receive an `AgentTask` and return an `AgentProposal`. The harness verifies every proposal against the SemanticIR before acceptance.

	### Agent Flow

	1. Register: `harness.register(Agent(id, fn, capabilities))`
	2. Dispatch: `harness.dispatch(task, agent_id)` → calls agent function
	3. Verify: Proposal's artifact is verified against task's IR reference
	4. Accept/Reject: Verified artifacts are accepted; failures are logged and raise `PipelineError`

	### Key Constraint

	Agent output never bypasses the FSM, IR validation, temporal lock, or verification engine. The agent is a proposal mechanism — the pipeline is the acceptance mechanism.

	---

	## CLI Reference

	```
	semantic-engine <command> <input> [--json] [--trace] [--subleq] [--tokens] [--provenance]
	```

	### Subcommands

	\| Command \| Description \|
	\|---------\|-------------\|
	\| `parse <file>` \| Tokenize and segment input \|
	\| `inspect <file>` \| Build and inspect the Semantic IR \|
	\| `normalize <file>` \| Show Boolean CNF normalization \|
	\| `boolean <file>` \| Show Boolean IR expression \|
	\| `tokens <file>` \| Show Boolean token stream \|
	\| `latin <file>` \| Show Latin canonical form \|
	\| `subleq <file>` \| Show SUBLEQ IR listing \|
	\| `verify <file>` \| Run full verification, show results \|
	\| `artifact <file>` \| Emit natural-language artifact \|
	\| `backend <file>` \| Emit Go backend source artifact \|
	\| `run <file>` \| Full pipeline with optional trace flags \|

	### Examples

	```bash
	# Parse and tokenize
	semantic-engine parse examples/matrix_multiply.txt --json

	# Full pipeline with trace
	semantic-engine run examples/matrix_multiply.txt --trace --subleq --tokens --provenance

	# Emit Go backend
	semantic-engine backend examples/validate_packets.txt

	# Verify input
	semantic-engine verify examples/parse_binary_format.txt
	```

	### Exit Codes

	\| Code \| Meaning \|
	\|------\|---------\|
	\| 0 \| Success (VERIFIED) \|
	\| 1 \| Pipeline error or REJECTED \|

	---

	## Building & Installation

	### Requirements

	- Python 3.11+ (no external dependencies required)
	- Optional: `transformers` + `torch` for BERT-based intent classification (falls back to rule-based without them)

	### Install

	```bash
	# Clone
	git clone https://github.com/SNAPKITTYWEST/semantic-engine.git
	cd semantic-engine

	# Install (editable)
	pip install -e .

	# Or install with BERT support
	pip install -e ".[bert]"

	# Or install with dev tools
	pip install -e ".[dev]"
	```

	### Run from Source

	```bash
	# Direct execution
	python cli/main.py run examples/matrix_multiply.txt --trace

	# Or via installed entry point
	semantic-engine run examples/matrix_multiply.txt --trace
	```

	### Quick Start

	```bash
	# Clone and test
	git clone https://github.com/SNAPKITTYWEST/semantic-engine.git
	cd semantic-engine
	python -m pytest tests/ -q

	# Expected output:
	# 113 passed in 0.38s

	# Run the pipeline
	echo "multiply two matrices A and B where A is 3x4 and B is 4x5" > /tmp/input.txt
	python cli/main.py run /tmp/input.txt --trace --subleq
	```

	---

	## Testing & Validation

	### Test Modules

	\| Module \| Tests \| What It Covers \|
	\|--------\|-------\|---------------\|
	\| `test_types.py` \| 9 \| Enums, RawInput hashing, NormalizedInput, error hierarchy \|
	\| `test_ir.py` \| 17 \| SemanticNode, SemanticIR, Geometry compatibility, TemporalLock \|
	\| `test_fsm.py` \| 11 \| Full state traversal, fail-closed transitions, constraint validation \|
	\| `test_boolean.py` \| 18 \| CNF normalization, De Morgan, constant folding, idempotency \|
	\| `test_tokens.py` \| 13 \| Binary encode/decode, round-trip, malformed input rejection \|
	\| `test_subleq.py` \| 15 \| VM execution, halting, assemble/disassemble, Rosetta→SUBLEQ \|
	\| `test_roundtrip.py` \| 30 \| End-to-end pipeline, all three examples, trace validation \|

	Total: 113 tests, 0.38s

	### Invariants Under Test

	- Token round-trip: `decode(encode(x)) == x` for all Boolean expression shapes
	- Boolean idempotency: `normalize(normalize(x)) == normalize(x)`
	- Temporal monotonicity: τ advances by exactly 0 or 1 per transition
	- SUBLEQ halting: Every assembled program halts within step limit
	- Provenance chain: Artifact.semantic_root == IR.ir_id
	- FSM completeness: All 20 states reachable; invalid transitions fail closed
	- Latin vocabulary closure: No lexeme outside the controlled vocabulary passes the lexer
	- Geometry consistency: Mismatched matrix dimensions raise GeometryError
	- Binary format integrity: Truncated/corrupted binary raises TokenError with precise location
	- Rosetta completeness: Unmapped semantic IDs raise RosettaError

	### Running Tests

	```bash
	# Quick
	python -m pytest tests/ -q

	# Verbose with coverage
	python -m pytest tests/ -v --tb=short

	# Single module
	python -m pytest tests/test_roundtrip.py -v
	```

	---

	## Implementation Architecture

	### Module Dependencies

	```
	┌──────────────────────┐
	│ pipeline.py │ ← orchestrator
	│ (SemanticPipeline) │
	└──────────┬───────────┘
	│ imports all phases
	┌────────────────┼────────────────────────────┐
	│ │ │ │ │ │ │ │
	▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼
	nlp fsm temporal geometry matrix boolean token latin
	│ │ │ │ │ │
	│ ▼ │ ▼ ▼ ▼
	│ ir.py ◄──────────────┘ token lexer rosetta
	│ │ engine │ │
	▼ ▼ │ │ ▼
	types.py ◄─── all modules │ │ subleq
	│ import types ▼ │ │
	│ artifacts.py │ │
	│ │ │ │
	└───────────────────────────────────┴─────────┴──────┘
	│
	▼
	verifier.py
	│
	▼
	agent_harness.py
	```

	### Key Design Decisions

	1. No inheritance hierarchy for IR nodes — composition via dataclasses, not OOP. Every node type is a `@dataclass` with explicit fields.
	2. FSM transition table is data, not code — the entire transition table is a list of `FSMTransition` records. Adding a state means adding a row, not writing a handler.
	3. Content-addressed everything — nodes, operations, constraints, artifacts all have deterministic SHA-256 hashes derived from their content.
	4. Temporal state is a value, not a side effect — `apply_temporal` returns `(result, new_τ)`. The old state is not mutated.
	5. Latin as intermediate language — Latin provides a stable, unambiguous vocabulary that humans can read and machines can map. It serves as the "Rosetta Stone" between semantic intent and machine instruction.

	---

	## NLP Subsystem & Intent Classification

	The NLP layer (`nlp.py`, 177 lines) provides the entry point for all natural language input. It operates in two modes: rule-based (zero dependencies, always available) and BERT-enhanced (optional, requires `transformers` + `torch`).

	### Rule-Based Analysis

	Intent classification uses a controlled keyword vocabulary organized by semantic class:

	\| Intent Class \| Keywords \|
	\|-------------\|----------\|
	\| BUILD \| build, create, make, construct, implement, write \|
	\| TRANSFORM \| transform, convert, translate, map, rewrite, change \|
	\| VALIDATE \| validate, verify, check, confirm, ensure, test \|
	\| GENERATE \| generate, produce, emit, output, render \|
	\| PARSE \| parse, read, decode, lex, scan, interpret \|
	\| COMPUTE \| compute, calculate, multiply, add, subtract, solve \|
	\| RECONSTRUCT \| reconstruct, restore, recover, rebuild, regenerate \|
	\| UNKNOWN \| (no keywords matched — confidence 0.3) \|

	Confidence scoring: `min(0.5 + matched_keywords × 0.15, 0.95)`. A single keyword match yields 0.65 confidence; three matches yield 0.95 (capped).

	### Entity & Operator Extraction

	Regex-based extraction for 30 entity types and 18 operator types:

	```
	Entities: matrix, vector, parser, backend, service, function, module,
	component, token, format, stream, buffer, table, schema,
	graph, tree, list, array, string, integer, boolean, packet,
	message, frame, field, register...

	Operators: multiply, add, subtract, divide, transform, convert,
	validate, parse, build, generate, compute, verify,
	reconstruct, normalize, encode, decode, serialize,
	deserialize

	Constraints: deterministic, immutable, idempotent, commutative,
	associative, invertible, ordered, typed, bounded,
	validated, correct, minimal, canonical, stable
	```

	### Relationship Extraction

	Pattern: `{subject} {preposition} {object}` where prepositions include: of, from, to, into, for, with, by, through, via, as.

	Example: `"build a parser for this binary format"` → `[("parser", "for", "binary"), ("binary", "format", ...)]`

	### Ambiguity Detection

	The pipeline detects ambiguous inputs via marker words: it, this, that, they, something, somehow, maybe, perhaps, possibly, or something, etc, and so on. Ambiguous inputs are flagged in the trace but not rejected — the FSM remains the admissibility gate.

	### BERT Interface

	When `transformers` is installed and a model name is provided, the `BertDecoder` class extracts CLS embeddings from the last hidden state. These embeddings are stored in `SemanticCandidate.raw_embeddings` for downstream use but do not override rule-based classification. BERT output is always `SemanticCandidate` — never executable code.

	```python
	pipeline = SemanticPipeline(bert_model="bert-base-uncased")
	result = pipeline.run(RawInput("multiply two matrices"))
	# .raw_embeddings populated with 768-dim float vector
	```

	---

	## Temporal Lock System

	The temporal system (`temporal.py`, 86 lines) enforces a monotonic clock over every pipeline transformation. Every mutation advances τ by exactly 1. Read-only passes preserve τ (advance by 0). Locked states reject all mutations.

	### Temporal State

	```python
	@dataclass
	class TemporalState:
	tau: int # monotonic integer tick
	label: str # reason for current state
	locked: bool # if True, advance() raises TemporalViolation
	```

	### Temporal Operations

	\| Operation \| τ Change \| Use Case \|
	\|-----------\|----------\|----------\|
	\| `apply_temporal(fn, t, lock, stage)` \| τ → τ+1 \| Mutating transformation \|
	\| `preserve_temporal(fn, t, lock, stage)` \| τ → τ \| Read-only pass \|
	\| `t.lock()` \| τ unchanged, locked=True \| Freeze state permanently \|
	\| `t.advance()` on locked state \| TemporalViolation \| Safety enforcement \|

	### Temporal Transitions

	Every temporal operation records a `TemporalTransition`:

	```python
	@dataclass(frozen=True)
	class TemporalTransition:
	from_tau: int
	to_tau: int
	reason: str
	stage: str
	```

	The `TemporalLock` validates that `to_tau ∈ {from_tau, from_tau + 1}`. Any jump greater than 1 raises `TemporalViolation`. The full audit log is available via `lock.audit()` and is checked by the verifier at Phase 14.

	### Why Temporal Locking Matters

	Without temporal accountability, transformations can silently overwrite each other, replay attacks become possible, and the provenance chain breaks. The temporal lock ensures that every mutation is sequenced, auditable, and irreversible.

	---

	## Geometry Engine

	The geometry engine (`geometry.py`, 114 lines) enforces dimensional constraints on operations before they reach the matrix or SUBLEQ layers.

	### Geometry Record

	```python
	@dataclass(frozen=True)
	class Geometry:
	row: Optional[int] # number of rows
	col: Optional[int] # number of columns
	contraction: Optional[int] # contracted dimension
	shape: tuple[int, ...] # arbitrary shape tuple
	index_labels: tuple[str, ...] # named indices
	```

	### Dimension Checking

	Matrix multiply (`check_matmul`): A ∈ R^(m×n), B ∈ R^(n×p) → C ∈ R^(m×p). Requires `A.col == B.row`.

	Element-wise (`check_elementwise`): add, subtract, XOR require identical shapes.

	Underdetermined: If either dimension is `None`, the check passes (not a violation yet — the operation may be abstract).

	### Geometry Spec Parser

	The `parse_geometry` function accepts multiple notations:

	```
	"3x4" → Geometry(row=3, col=4, shape=(3,4))
	"R^(3x4)" → Geometry(row=3, col=4, shape=(3,4))
	"(3,4)" → Geometry(row=3, col=4, shape=(3,4))
	"scalar" → Geometry(row=1, col=1, shape=(1,1))
	"5" → Geometry(row=5, col=1, shape=(5,))
	```

	### Hand-Traced Example

	Input: `"multiply two matrices A and B where A is 3x4 and B is 4x5"`

	```
	Phase 5: Geometry Binding
	A.geometry = Geometry(row=3, col=4)
	B.geometry = Geometry(row=4, col=5)
	check_matmul(A, B):
	A.col (4) == B.row (4) ✓
	output: Geometry(row=3, col=5, contraction=4)

	Phase 6: SemanticMatrix Construction
	operation: multiply (arity 2)
	matrix layout (3×3):
	[A_input] [contract=4] [B_input]
	[m=3] [n=4] [p=5]
	[output=C] [(3×5)] [—]
	```

	If the input were `"multiply A (3x4) by B (5x2)"`, Phase 5 would raise:
	```
	GeometryError: contraction mismatch: A.col=4 ≠ B.row=5
	```

	---

	## Worked Example: End-to-End Trace

	Input file: `examples/matrix_multiply.txt`
	```
	multiply two matrices A and B where A is 3x4 and B is 4x5
	```

	### Full Pipeline Trace

	```
	=== TRACE ===
	INPUT: 7a3f2b1c-...
	NORMALIZE: 13 tokens
	LEXICAL_ANALYSIS: 1 sentences
	INTENT_DETECTION: compute (0.65)
	ENTITY_BINDING: ['matrix']
	SEMANTIC_BINDING: IR a1b2c3d4
	TEMPORAL_LOCK: τ0→τ1
	GEOMETRY_BINDING: dimensions validated
	MATRIX_FORM: 2x2
	BOOLEAN_ROOT: multiply
	BOOLEAN_NORMALIZATION: stable=True
	TOKENIZATION: 3 tokens, 16 bytes
	LATIN_CANONICALIZATION: INITIUM ET OPUS[multiply] FINIS
	LATIN_LEXING: 4 lex tokens
	ROSETTA_MAPPING: 4 entries
	SUBLEQ_IR: 5 instructions
	VERIFICATION: PASSED
	ARTIFACT_SELECTION: mode=natural_language
	EMISSION: artifact e5f6a7b8
	COMPLETE

	=== SUBLEQ ===
	DELIM_OPEN_0: SUBLEQ 0, 0, 109 ; PUSH:
	BOOL_AND_1: SUBLEQ 0, 256, 115 ; AND:
	SEMANTIC_OP_2: SUBLEQ 0, 0, 121 ; NOP:multiply
	DELIM_CLOSE_3: SUBLEQ 0, 0, 127 ; POP:
	SUBLEQ 0, 0, -1 ; HALT

	=== HASHES ===
	input: a7b3c9d1e5f2...
	semantic_ir: 4f8a2b1c7d3e...
	subleq: 9c1d4e7f2a3b...
	artifact: b2c5d8e1f4a7...

	Status: VERIFIED
	```

	### What Each Hash Proves

	- input: SHA-256 of the raw text — proves the exact input
	- semantic_ir: SHA-256 of all node hashes chained — proves the IR structure
	- subleq: SHA-256 of the assembled binary — proves the machine code
	- artifact: SHA-256 of the rendered output — proves the final content

	If any bit changes at any stage, the downstream hashes change. Replay with the same input produces identical hashes.

	---

	## Performance & Design Constraints

	### Performance

	\| Metric \| Value \|
	\|--------\|-------\|
	\| Full pipeline (single input) \| ~3.4ms \|
	\| Test suite (113 tests) \| 0.38s \|
	\| Throughput (estimated) \| ~300 inputs/sec \|
	\| Memory per pipeline run \| < 1MB \|
	\| SUBLEQ VM step limit \| 100,000 (configurable) \|
	\| Binary token format overhead \| ~4 bytes/token \|
	\| Python version \| 3.11+ \|
	\| External dependencies \| 0 (BERT optional) \|

	### Design Constraints

	- Zero external dependencies for the core pipeline. `transformers` + `torch` are optional for BERT.
	- Deterministic — no random seeds, no model variance, no floating-point accumulation in the core path.
	- Fail-closed — every error condition raises a typed exception. The FSM has no implicit fallthrough.
	- Content-addressed — every intermediate can be hashed and compared. Pipeline replays produce identical output.
	- Audit trail — `PipelineResult.trace` records every phase transition. `PipelineResult.hashes` records SHA-256 at input, IR, SUBLEQ, and artifact stages.

	---

	## Contributing & License

	### How to Contribute

	1. Fork the repository
	2. Create a feature branch: `git checkout -b feature/your-feature`
	3. Write code, tests, and verify: `python -m pytest tests/ -q`
	4. Commit with semantic messages
	5. Push and create a pull request

	### Commit Message Format

	```
	<type>: <subject>

	Types: feat, fix, docs, test, refactor, perf, chore
	```

	### License Compliance

	Source files are individually licensed under MPL-2.0 (file-level copyleft).
	The project as a whole is dual-licensed under Apache-2.0 OR GPL-3.0-or-later with Sovereign Leviathan Node License terms (AGPL-3.0 base).

	Commercial repository. No MIT permitted.

	Choose the license that fits your use case:
	- Internal use: Apache-2.0 for patent protection
	- Open-source project: GPL-3.0 to propagate freedom
	- File-level modifications: MPL-2.0 requires sharing changes to covered files

	### Contributors

	- Original Design: Ahmad Ali Parr
	- Implementation: SnapKittyWest
	- License: Bel Esprit D'Accord Irrevocable Trust

	### References

	- Quine, W.V.O. (1951). Mathematical Logic. Harvard University Press.
	- Mavaddat, F., & Parhami, B. (1988). "URISC: The Ultimate Reduced Instruction Set Computer." International Journal of Electrical Engineering Education, 25(4), 327–334.
	- Tseytin, G.S. (1983). "On the Complexity of Derivation in Propositional Calculus." Studies in Constructive Mathematics and Mathematical Logic.
	- POSIX.1-2008 System Interface.

	### 💼 Commercial License

	This repository is published under MPL-2.0. Building a commercial product or service? A proprietary commercial license from Snapkitty Collective LLC lets you ship this code on terms other than MPL-2.0.

	[→ Get a commercial license](mailto:A.parr@belespritdaccord.uk?subject=Commercial%20license:%20semantic-engine) · A.parr@belespritdaccord.uk


	---

	## Type System & Enumerations

	The type system (`types.py`, 199 lines) defines all enumerations, input types, and the error hierarchy used across all 18 modules.

	### FSMState (21 values)

	```
	INPUT → NORMALIZE → LEXICAL_ANALYSIS → INTENT_DETECTION →
	ENTITY_BINDING → SEMANTIC_BINDING → TEMPORAL_LOCK →
	GEOMETRY_BINDING → MATRIX_FORM → BOOLEAN_ROOT →
	BOOLEAN_NORMALIZATION → TOKENIZATION → LATIN_CANONICALIZATION →
	LATIN_LEXING → ROSETTA_MAPPING → SUBLEQ_IR → VERIFICATION →
	ARTIFACT_SELECTION → EMISSION → COMPLETE
	↗ (from any state)
	ERROR
	```

	### IntentClass (8 values)

	BUILD, TRANSFORM, VALIDATE, GENERATE, PARSE, COMPUTE, RECONSTRUCT, UNKNOWN.

	Every input is classified into exactly one intent. UNKNOWN is valid but triggers a lower confidence score (0.3).

	### SemanticNodeType (8 values)

	OPERATION, ENTITY, CONSTRAINT, RELATION, INTENT, GEOMETRY, TEMPORAL, LITERAL.

	These types determine how the node is processed by downstream phases — operations require arity checking, entities get type-tagged, constraints become Boolean variables.

	### ArtifactType (8 values)

	PROMPT, DOCUMENT, SOURCE, CONFIG, TEST, SCHEMA, REPORT, BACKEND.

	Each type maps to a specific template and rendering strategy.

	### BooleanOperator (8 values)

	AND, OR, NOT, XOR, IMPLIES, EQUIVALENCE, TRUE, FALSE.

	These map 1:1 to Latin lexemes (ET, VEL, NON, AUT, SI, IFF, VERUM, FALSUM) and 1:1 to SUBLEQ operations via the Rosetta table.

	### Input Types

	```python
	@dataclass(frozen=True)
	class RawInput:
	text: str # the natural language input
	source: str = "stdin" # origin identifier
	timestamp: float # wall clock at creation
	input_id: str # UUID v4
	# .hash → SHA-256 of text

	@dataclass(frozen=True)
	class NormalizedInput:
	original: RawInput # back-reference
	text: str # whitespace-normalized
	tokens: tuple[str, ...] # word-level tokenization
	sentences: tuple[str, ...] # sentence segmentation
	# .hash → SHA-256 of normalized text
	```

	Both types are frozen (immutable). The `hash` property computes SHA-256 on demand for content addressing.

	### SemanticCandidate

	The bridge between NLP and the typed IR:

	```python
	@dataclass
	class SemanticCandidate:
	input_ref: str # ties back to RawInput.input_id
	intent: IntentClass # classified intent
	entities: list[str] # extracted entities
	operators: list[str] # extracted operators
	constraints: list[str] # extracted constraints
	relationships: list[tuple[str, str, str]] # subject-preposition-object triples
	confidence: float # [0.0, 1.0] — validated in __post_init__
	ambiguous: bool # whether ambiguity markers detected
	raw_embeddings: Optional[list[float]] # BERT CLS vector (if available)
	```

	The `confidence` field is validated on construction — values outside `[0.0, 1.0]` raise `ValueError`. This prevents downstream phases from operating on malformed candidates.

	---

	## Data Flow Summary

	```
	RawInput("multiply two matrices A and B where A is 3x4 and B is 4x5")
	│
	▼ normalize_input()
	NormalizedInput(tokens=("multiply","two","matrices","A","and","B",
	"where","A","is","3x4","and","B","is","4x5"),
	sentences=("multiply two matrices A and B where A is 3x4 and B is 4x5",))
	│
	▼ BertDecoder.decode()
	SemanticCandidate(intent=COMPUTE, entities=["matrix"],
	operators=["multiply"], constraints=[],
	confidence=0.65, ambiguous=False)
	│
	▼ SemanticNode.make() + SemanticIR.create()
	SemanticIR(intent=COMPUTE, nodes=[
	SemanticNode(type=OPERATION, operation=multiply/1,
	operands=[Operand("matrix","entity")],
	constraints=[], geometry=None, τ=0)
	])
	│
	▼ apply_temporal() τ₀ → τ₁
	▼ enforce_geometry() geometry validated
	▼ SemanticMatrixBuilder.build() 2×2 SemanticMatrix
	▼ semantic_constraints_to_boolean() BooleanNormalForm (CNF)
	▼ BoolEncoder.encode_expr() BooleanTokenStream → bytes
	▼ LatinCanonicalizer.canonicalize() "INITIUM ET OPUS[multiply] FINIS"
	▼ LatinLexer.lex_canonical() LexResult (4 tokens)
	▼ RosettaMapper.map() RosettaMapping (4 entries)
	▼ build_program_from_rosetta() SubleqProgram (5 instructions)
	│
	▼ Verifier: 10 checks × PASS
	│
	▼ ArtifactEngine.build_document()
	Artifact(type=DOCUMENT, content="COMPUTE\n\nIntent: compute \| Nodes: 1",
	verification_state=VERIFIED)
	│
	▼ PipelineResult(ok=True, hashes={input, semantic_ir, subleq, artifact})
	```

	Every arrow is a phase transition in the FSM. Every intermediate is hashed. Every mutation advances τ. Every output is verified.

	---

	Status: Production-ready — 20 phases, 113 tests, zero stubs
	Certification Date: 2026-09-21
	Test Count: 113 passed
	Code Quality: 4,143 lines, zero external dependencies
	License: MPL-2.0 (file) \| Apache-2.0 OR GPL-3.0-or-later (project)

	*"Hark, though this node be but a spark,
	Its covenant endureth through the dark."*