October 2026 main drop: mirror from GitHub

.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/

LICENSE

@@ -0,0 +1,374 @@
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under the name "LEGAL", alongside the License. Except to the
+extent prohibited by statute or regulation, such description must be
+sufficiently detailed for a recipient of ordinary skill to be able to
+understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+*                                                                      *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
+*                                                                      *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or  *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
+*                                                                      *
+************************************************************************
+
+************************************************************************
+*                                                                      *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
+*                                                                      *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
+*                                                                      *
+************************************************************************
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.

README.md

@@ -0,0 +1,17 @@
+---
+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**.
+

cli/main.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Phase 18: CLI — semantic-engine command line interface."""
+
+import json
+import sys
+from pathlib import Path
+
+# Allow running from repo root
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+import argparse
+from semantic_engine import SemanticPipeline, PipelineResult, RawInput, OutputMode
+from semantic_engine.nlp import normalize_input
+from semantic_engine.boolean_engine import semantic_constraints_to_boolean, normalize as bool_normalize
+from semantic_engine.token_engine import BoolEncoder, encode_binary, decode, encode
+from semantic_engine.latin import LatinCanonicalizer
+from semantic_engine.lexer import LatinLexer
+from semantic_engine.rosetta import RosettaMapper
+from semantic_engine.subleq import build_program_from_rosetta
+from semantic_engine.verifier import Verifier
+
+
+def read_input(path: str) -> RawInput:
+    p = Path(path)
+    if not p.exists():
+        print(f"error: file not found: {path}", file=sys.stderr)
+        sys.exit(1)
+    return RawInput(text=p.read_text().strip(), source=str(p))
+
+
+def cmd_parse(args):
+    raw = read_input(args.input)
+    normalized = normalize_input(raw)
+    out = {
+        "input_id": raw.input_id,
+        "input_hash": raw.hash,
+        "text": normalized.text,
+        "tokens": list(normalized.tokens),
+        "sentences": list(normalized.sentences),
+    }
+    print(json.dumps(out, indent=2) if args.json else f"Tokens: {list(normalized.tokens)}")
+
+
+def cmd_inspect(args):
+    raw = read_input(args.input)
+    pipeline = SemanticPipeline()
+    result = pipeline.run(raw)
+    if result.ir:
+        ir = result.ir
+        out = {
+            "ir_id": ir.ir_id,
+            "intent": ir.intent.value,
+            "nodes": len(ir.nodes),
+            "verification": ir.verification_state.name,
+            "hash": ir.hash(),
+        }
+        print(json.dumps(out, indent=2) if args.json else str(out))
+    else:
+        print(f"error: {result.error}", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_normalize(args):
+    raw = read_input(args.input)
+    pipeline = SemanticPipeline()
+    result = pipeline.run(raw)
+    if result.ir:
+        from semantic_engine.boolean_engine import semantic_constraints_to_boolean
+        bnf = semantic_constraints_to_boolean(result.ir.root.constraints)
+        print(f"Normalized: {bnf.normalized}")
+        print(f"Stable:     {bnf.stable}")
+    else:
+        print(f"error: {result.error}", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_boolean(args):
+    raw = read_input(args.input)
+    pipeline = SemanticPipeline()
+    result = pipeline.run(raw)
+    if result.ir:
+        bnf = semantic_constraints_to_boolean(result.ir.root.constraints)
+        print(f"Boolean form: {bnf.normalized}")
+    else:
+        print(f"error: {result.error}", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_tokens(args):
+    raw = read_input(args.input)
+    pipeline = SemanticPipeline()
+    result = pipeline.run(raw)
+    if result.ir:
+        bnf = semantic_constraints_to_boolean(result.ir.root.constraints)
+        encoder = BoolEncoder()
+        stream = encoder.encode_expr(bnf.normalized)
+        for tok in stream:
+            print(repr(tok))
+    else:
+        print(f"error: {result.error}", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_latin(args):
+    raw = read_input(args.input)
+    pipeline = SemanticPipeline()
+    result = pipeline.run(raw)
+    if result.ir:
+        bnf = semantic_constraints_to_boolean(result.ir.root.constraints)
+        encoder = BoolEncoder()
+        stream = encoder.encode_expr(bnf.normalized)
+        latin = LatinCanonicalizer().canonicalize(stream)
+        print(latin.text())
+    else:
+        print(f"error: {result.error}", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_subleq(args):
+    raw = read_input(args.input)
+    pipeline = SemanticPipeline()
+    result = pipeline.run(raw)
+    if result.subleq_listing:
+        print(result.subleq_listing)
+    else:
+        print(f"error: {result.error}", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_verify(args):
+    raw = read_input(args.input)
+    pipeline = SemanticPipeline()
+    result = pipeline.run(raw)
+    status = "VERIFIED" if result.ok else "REJECTED"
+    print(f"Status: {status}")
+    if result.error:
+        print(f"Error:  {result.error}")
+    for line in result.trace:
+        print(f"  {line}")
+
+
+def cmd_artifact(args):
+    raw = read_input(args.input)
+    pipeline = SemanticPipeline()
+    result = pipeline.run(raw, output_mode=OutputMode.NATURAL_LANGUAGE)
+    if result.artifact:
+        print(result.artifact.content)
+    else:
+        print(f"error: {result.error}", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_backend(args):
+    raw = read_input(args.input)
+    pipeline = SemanticPipeline()
+    result = pipeline.run(raw, output_mode=OutputMode.CODE)
+    if result.artifact:
+        print(result.artifact.content)
+    else:
+        print(f"error: {result.error}", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_run(args):
+    raw = read_input(args.input)
+    pipeline = SemanticPipeline()
+    result = pipeline.run(raw)
+
+    if args.trace:
+        print("=== TRACE ===")
+        for line in result.trace:
+            print(f"  {line}")
+        print()
+
+    if args.subleq:
+        print("=== SUBLEQ ===")
+        print(result.subleq_listing)
+        print()
+
+    if args.provenance:
+        print("=== PROVENANCE ===")
+        if result.ir:
+            print(f"  IR: {result.ir.ir_id}")
+            print(f"  Stage: {result.ir.provenance.stage}")
+        print()
+
+    if args.tokens and result.ir:
+        print("=== TOKENS ===")
+        from semantic_engine.boolean_engine import semantic_constraints_to_boolean
+        bnf = semantic_constraints_to_boolean(result.ir.root.constraints)
+        encoder = BoolEncoder()
+        stream = encoder.encode_expr(bnf.normalized)
+        for tok in stream:
+            print(f"  {repr(tok)}")
+        print()
+
+    if result.artifact:
+        print("=== OUTPUT ===")
+        print(result.artifact.content)
+    else:
+        print(f"error: {result.error}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"\nStatus: {'VERIFIED' if result.ok else 'REJECTED'}")
+    for k, v in result.hashes.items():
+        print(f"  {k}: {v[:16]}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="semantic-engine",
+        description="Deterministic semantic transformation pipeline",
+    )
+    parser.add_argument("--json", action="store_true", help="Machine-readable JSON output")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    for name, fn, help_text in [
+        ("parse",     cmd_parse,     "Tokenize and segment input"),
+        ("inspect",   cmd_inspect,   "Build and inspect the Semantic IR"),
+        ("normalize", cmd_normalize, "Show Boolean normalization"),
+        ("boolean",   cmd_boolean,   "Show Boolean IR"),
+        ("tokens",    cmd_tokens,    "Show Boolean token stream"),
+        ("latin",     cmd_latin,     "Show Latin canonical form"),
+        ("subleq",    cmd_subleq,    "Show SUBLEQ IR listing"),
+        ("verify",    cmd_verify,    "Run full verification and show results"),
+        ("artifact",  cmd_artifact,  "Emit natural-language artifact"),
+        ("backend",   cmd_backend,   "Emit backend source artifact"),
+    ]:
+        p = sub.add_parser(name, help=help_text)
+        p.add_argument("input", help="Path to input file")
+        p.set_defaults(func=fn)
+
+    run_p = sub.add_parser("run", help="Run full pipeline with optional trace flags")
+    run_p.add_argument("input")
+    run_p.add_argument("--trace",      action="store_true")
+    run_p.add_argument("--subleq",     action="store_true")
+    run_p.add_argument("--tokens",     action="store_true")
+    run_p.add_argument("--provenance", action="store_true")
+    run_p.set_defaults(func=cmd_run)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

examples/matrix_multiply.txt

@@ -0,0 +1 @@
+multiply two matrices A and B where A is 3x4 and B is 4x5

examples/parse_binary_format.txt

@@ -0,0 +1 @@
+build a parser for this binary format deterministically

examples/validate_packets.txt

@@ -0,0 +1 @@
+create a backend service that validates packets

lexicon/latin_vocabulary.json

@@ -0,0 +1,33 @@
+{
+  "_comment": "Controlled Latin vocabulary. Every lexeme maps to a stable semantic_id. No synonyms permitted at this stage.",
+  "lexemes": {
+    "ET":          { "semantic_id": "BOOL_AND",          "operator": "AND",          "arity": 2 },
+    "VEL":         { "semantic_id": "BOOL_OR",           "operator": "OR",           "arity": 2 },
+    "NON":         { "semantic_id": "BOOL_NOT",          "operator": "NOT",          "arity": 1 },
+    "AUT":         { "semantic_id": "BOOL_XOR",          "operator": "XOR",          "arity": 2 },
+    "SI":          { "semantic_id": "BOOL_IMPLIES",      "operator": "IMPLIES",      "arity": 2 },
+    "IFF":         { "semantic_id": "BOOL_EQUIV",        "operator": "EQUIVALENCE",  "arity": 2 },
+    "VERUM":       { "semantic_id": "BOOL_TRUE",         "operator": "TRUE",         "arity": 0 },
+    "FALSUM":      { "semantic_id": "BOOL_FALSE",        "operator": "FALSE",        "arity": 0 },
+    "INITIUM":     { "semantic_id": "DELIM_OPEN",        "operator": null,           "arity": 0 },
+    "FINIS":       { "semantic_id": "DELIM_CLOSE",       "operator": null,           "arity": 0 },
+    "OPUS":        { "semantic_id": "SEMANTIC_OP",       "operator": null,           "arity": -1 },
+    "FORMA":       { "semantic_id": "SEMANTIC_MATRIX",   "operator": null,           "arity": -1 },
+    "TEMPUS":      { "semantic_id": "TEMPORAL_STATE",    "operator": null,           "arity": 0 },
+    "COMPUTA":     { "semantic_id": "OP_COMPUTE",        "operator": "compute",      "arity": 1 },
+    "MULTIPLICA":  { "semantic_id": "OP_MULTIPLY",       "operator": "multiply",     "arity": 2 },
+    "ADDE":        { "semantic_id": "OP_ADD",            "operator": "add",          "arity": 2 },
+    "SUBTRAHE":    { "semantic_id": "OP_SUBTRACT",       "operator": "subtract",     "arity": 2 },
+    "PARSE":       { "semantic_id": "OP_PARSE",          "operator": "parse",        "arity": 1 },
+    "AEDIFICA":    { "semantic_id": "OP_BUILD",          "operator": "build",        "arity": 1 },
+    "GENERA":      { "semantic_id": "OP_GENERATE",       "operator": "generate",     "arity": 1 },
+    "VERIFICA":    { "semantic_id": "OP_VALIDATE",       "operator": "validate",     "arity": 1 },
+    "CONVERTE":    { "semantic_id": "OP_TRANSFORM",      "operator": "transform",    "arity": 2 },
+    "RESTITUE":    { "semantic_id": "OP_RECONSTRUCT",    "operator": "reconstruct",  "arity": 1 },
+    "MATRIX":      { "semantic_id": "ENTITY_MATRIX",     "operator": null,           "arity": 0 },
+    "VECTOR":      { "semantic_id": "ENTITY_VECTOR",     "operator": null,           "arity": 0 },
+    "PARSER":      { "semantic_id": "ENTITY_PARSER",     "operator": null,           "arity": 0 },
+    "SERVITIUM":   { "semantic_id": "ENTITY_SERVICE",    "operator": null,           "arity": 0 },
+    "FORMA_BINARIA": { "semantic_id": "ENTITY_BINARY_FORMAT", "operator": null,      "arity": 0 }
+  }
+}

mappings/rosetta_table.json

@@ -0,0 +1,29 @@
+{
+  "_comment": "Rosetta mapping: semantic_id → SUBLEQ operation template. Only canonical vocabulary may reach this layer.",
+  "mappings": {
+    "BOOL_AND":          { "subleq_op": "AND",      "template": "subleq_and",      "args": ["a", "b", "out"] },
+    "BOOL_OR":           { "subleq_op": "OR",       "template": "subleq_or",       "args": ["a", "b", "out"] },
+    "BOOL_NOT":          { "subleq_op": "NOT",      "template": "subleq_not",      "args": ["a", "out"] },
+    "BOOL_XOR":          { "subleq_op": "XOR",      "template": "subleq_xor",      "args": ["a", "b", "out"] },
+    "BOOL_IMPLIES":      { "subleq_op": "OR",       "template": "subleq_or",       "args": ["not_a", "b", "out"] },
+    "BOOL_EQUIV":        { "subleq_op": "XNOR",     "template": "subleq_xnor",     "args": ["a", "b", "out"] },
+    "BOOL_TRUE":         { "subleq_op": "LOAD_1",   "template": "subleq_load",     "args": ["1", "out"] },
+    "BOOL_FALSE":        { "subleq_op": "LOAD_0",   "template": "subleq_load",     "args": ["0", "out"] },
+    "SEMANTIC_OP":       { "subleq_op": "NOP",      "template": "subleq_nop",      "args": [] },
+    "OP_COMPUTE":        { "subleq_op": "COMPUTE",  "template": "subleq_compute",  "args": ["a", "out"] },
+    "OP_MULTIPLY":       { "subleq_op": "MUL",      "template": "subleq_mul",      "args": ["a", "b", "out"] },
+    "OP_ADD":            { "subleq_op": "ADD",      "template": "subleq_add",      "args": ["a", "b", "out"] },
+    "OP_SUBTRACT":       { "subleq_op": "SUB",      "template": "subleq_sub",      "args": ["a", "b", "out"] },
+    "OP_PARSE":          { "subleq_op": "PARSE",    "template": "subleq_parse",    "args": ["src", "out"] },
+    "OP_BUILD":          { "subleq_op": "BUILD",    "template": "subleq_build",    "args": ["spec", "out"] },
+    "OP_GENERATE":       { "subleq_op": "GEN",      "template": "subleq_gen",      "args": ["spec", "out"] },
+    "OP_VALIDATE":       { "subleq_op": "VERIFY",   "template": "subleq_verify",   "args": ["a", "spec"] },
+    "OP_TRANSFORM":      { "subleq_op": "XFORM",    "template": "subleq_xform",    "args": ["a", "b", "out"] },
+    "OP_RECONSTRUCT":    { "subleq_op": "RECON",    "template": "subleq_recon",    "args": ["spec", "out"] },
+    "ENTITY_MATRIX":     { "subleq_op": "ALLOC",    "template": "subleq_alloc",    "args": ["rows", "cols", "out"] },
+    "ENTITY_VECTOR":     { "subleq_op": "ALLOC",    "template": "subleq_alloc",    "args": ["n", "1", "out"] },
+    "TEMPORAL_STATE":    { "subleq_op": "TICK",     "template": "subleq_tick",     "args": ["tau", "out"] },
+    "DELIM_OPEN":        { "subleq_op": "PUSH",     "template": "subleq_push",     "args": [] },
+    "DELIM_CLOSE":       { "subleq_op": "POP",      "template": "subleq_pop",      "args": [] }
+  }
+}

pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.backends.legacy:build"
+
+[project]
+name = "semantic-engine"
+version = "1.0.0"
+description = "Deterministic semantic transformation pipeline: NL → IR → Boolean → Latin → SUBLEQ → Artifact"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+bert = ["transformers>=4.40", "torch>=2.0"]
+dev  = ["pytest>=8", "pytest-cov"]
+
+[project.scripts]
+semantic-engine = "cli.main:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v"

src/semantic_engine/__init__.py

@@ -0,0 +1,10 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Semantic Engine — deterministic semantic transformation pipeline."""
+
+from .pipeline import SemanticPipeline, PipelineResult
+from .types import RawInput, OutputMode
+
+__all__ = ["SemanticPipeline", "PipelineResult", "RawInput", "OutputMode"]

src/semantic_engine/agent_harness.py

@@ -0,0 +1,102 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Phase 17: Agent harness — agents propose artifacts; the system verifies before acceptance.
+
+Agent output never bypasses FSM, IR validation, temporal lock, or verification.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+from .ir import Artifact, SemanticIR
+from .types import ArtifactType, FSMState, PipelineError, VerificationState
+from .verifier import Verifier
+
+
+# ── Agent task ────────────────────────────────────────────────────────────────
+
+@dataclass
+class AgentTask:
+    task_id: str
+    description: str
+    semantic_constraints: list[str]
+    available_operations: list[str]
+    artifact_schema: dict
+    verification_requirements: list[str]
+    ir_ref: Optional[SemanticIR] = None
+
+
+# ── Agent proposal ────────────────────────────────────────────────────────────
+
+@dataclass
+class AgentProposal:
+    agent_id: str
+    task_id: str
+    artifact: Artifact
+    rationale: str = ""
+
+
+# ── Agent interface ───────────────────────────────────────────────────────────
+
+AgentFn = Callable[[AgentTask], AgentProposal]
+
+
+@dataclass
+class Agent:
+    agent_id: str
+    fn: AgentFn
+    capabilities: list[ArtifactType] = field(default_factory=list)
+
+
+# ── Harness ───────────────────────────────────────────────────────────────────
+
+class AgentHarness:
+    """
+    Accepts agent proposals, runs them through the verifier, accepts or rejects.
+    Agents may NOT bypass any pipeline stage.
+    """
+
+    def __init__(self):
+        self._agents: dict[str, Agent] = {}
+        self._verifier = Verifier()
+        self._accepted: list[Artifact] = []
+        self._rejected: list[tuple[AgentProposal, str]] = []
+
+    def register(self, agent: Agent) -> None:
+        self._agents[agent.agent_id] = agent
+
+    def dispatch(self, task: AgentTask, agent_id: str) -> Artifact:
+        agent = self._agents.get(agent_id)
+        if agent is None:
+            raise PipelineError(FSMState.ARTIFACT_SELECTION, f"Unknown agent: {agent_id}")
+
+        proposal = agent.fn(task)
+
+        if task.ir_ref is None:
+            raise PipelineError(
+                FSMState.VERIFICATION,
+                "Agent task has no IR reference — cannot verify provenance",
+            )
+
+        report = self._verifier.verify_artifact(proposal.artifact, task.ir_ref)
+
+        if not report.passed:
+            self._rejected.append((proposal, report.summary()))
+            raise PipelineError(
+                FSMState.VERIFICATION,
+                f"Agent {agent_id} proposal rejected:\n{report.summary()}",
+            )
+
+        proposal.artifact.verification_state = VerificationState.VERIFIED
+        self._accepted.append(proposal.artifact)
+        return proposal.artifact
+
+    def accepted(self) -> list[Artifact]:
+        return list(self._accepted)
+
+    def rejected(self) -> list[tuple[AgentProposal, str]]:
+        return list(self._rejected)

src/semantic_engine/artifacts.py

@@ -0,0 +1,237 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Phases 15–16: Artifact engine, Mustache + Go-template backends."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+from .ir import Artifact, Provenance, SemanticIR, TemporalState
+from .types import ArtifactType, FSMState, PipelineError, VerificationState
+
+
+# ── Mustache renderer (no external dep required) ─────────────────────────────
+
+class MustacheRenderer:
+    """
+    Minimal Mustache renderer supporting:
+      {{variable}}
+      {{#section}} ... {{/section}}   (truthy sections and list iteration)
+      {{^section}} ... {{/section}}   (inverted)
+    """
+
+    def render(self, template: str, ctx: dict[str, Any]) -> str:
+        result = self._render_sections(template, ctx)
+        result = self._render_variables(result, ctx)
+        return result
+
+    def _render_variables(self, tmpl: str, ctx: dict) -> str:
+        def replace(m):
+            key = m.group(1).strip()
+            val = ctx.get(key, "")
+            return str(val) if val is not None else ""
+        return re.sub(r"\{\{([^#^/][^}]*)\}\}", replace, tmpl)
+
+    def _render_sections(self, tmpl: str, ctx: dict) -> str:
+        # Positive sections: {{#key}} ... {{/key}}
+        pattern = re.compile(r"\{\{#(\w+)\}\}(.*?)\{\{/\1\}\}", re.DOTALL)
+        def replace_section(m):
+            key = m.group(1)
+            body = m.group(2)
+            value = ctx.get(key)
+            if not value:
+                return ""
+            if isinstance(value, list):
+                parts = []
+                for item in value:
+                    if isinstance(item, dict):
+                        parts.append(self.render(body, {**ctx, **item}))
+                    else:
+                        parts.append(self.render(body, {**ctx, ".": item}))
+                return "".join(parts)
+            return self.render(body, ctx)
+
+        while pattern.search(tmpl):
+            tmpl = pattern.sub(replace_section, tmpl)
+
+        # Inverted sections: {{^key}} ... {{/key}}
+        inv_pattern = re.compile(r"\{\{\^(\w+)\}\}(.*?)\{\{/\1\}\}", re.DOTALL)
+        def replace_inverted(m):
+            key = m.group(1)
+            body = m.group(2)
+            value = ctx.get(key)
+            return "" if value else self.render(body, ctx)
+
+        while inv_pattern.search(tmpl):
+            tmpl = inv_pattern.sub(replace_inverted, tmpl)
+
+        return tmpl
+
+    def render_file(self, template_path: Path, ctx: dict) -> str:
+        if not template_path.exists():
+            raise PipelineError(FSMState.ARTIFACT_SELECTION, f"Template not found: {template_path}")
+        return self.render(template_path.read_text(), ctx)
+
+
+# ── Go template renderer (subset) ────────────────────────────────────────────
+
+class GoTemplateRenderer:
+    """
+    Minimal Go template subset renderer:
+      {{.Field}}
+      {{range .Items}} ... {{end}}
+      {{if .Cond}} ... {{end}}
+    """
+
+    def render(self, template: str, data: Any) -> str:
+        result = self._render_range(template, data)
+        result = self._render_if(result, data)
+        result = self._render_dot_vars(result, data)
+        return result
+
+    def _get(self, data: Any, key: str) -> Any:
+        if isinstance(data, dict):
+            return data.get(key, "")
+        return getattr(data, key, "")
+
+    def _render_dot_vars(self, tmpl: str, data: Any) -> str:
+        def replace(m):
+            key = m.group(1).strip()
+            if key.startswith("."):
+                key = key[1:]
+            val = self._get(data, key) if key else data
+            return str(val) if val is not None else ""
+        return re.sub(r"\{\{(\.?\w+)\}\}", replace, tmpl)
+
+    def _render_range(self, tmpl: str, data: Any) -> str:
+        pattern = re.compile(r"\{\{range \.(\w+)\}\}(.*?)\{\{end\}\}", re.DOTALL)
+        def replace(m):
+            key = m.group(1)
+            body = m.group(2)
+            items = self._get(data, key)
+            if not items:
+                return ""
+            if not isinstance(items, (list, tuple)):
+                items = [items]
+            parts = []
+            for item in items:
+                parts.append(self.render(body, item))
+            return "".join(parts)
+        while pattern.search(tmpl):
+            tmpl = pattern.sub(replace, tmpl)
+        return tmpl
+
+    def _render_if(self, tmpl: str, data: Any) -> str:
+        pattern = re.compile(r"\{\{if \.(\w+)\}\}(.*?)\{\{end\}\}", re.DOTALL)
+        def replace(m):
+            key = m.group(1)
+            body = m.group(2)
+            value = self._get(data, key)
+            return self.render(body, data) if value else ""
+        while pattern.search(tmpl):
+            tmpl = pattern.sub(replace, tmpl)
+        return tmpl
+
+    def render_file(self, template_path: Path, data: Any) -> str:
+        if not template_path.exists():
+            raise PipelineError(FSMState.ARTIFACT_SELECTION, f"Template not found: {template_path}")
+        return self.render(template_path.read_text(), data)
+
+
+# ── Artifact engine ───────────────────────────────────────────────────────────
+
+TEMPLATES_DIR = Path(__file__).parent.parent.parent / "templates"
+
+
+class ArtifactEngine:
+    def __init__(self):
+        self._mustache = MustacheRenderer()
+        self._go       = GoTemplateRenderer()
+
+    def build_prompt(self, ir: SemanticIR, extra: dict | None = None) -> Artifact:
+        ctx = self._ir_to_mustache_ctx(ir)
+        if extra:
+            ctx.update(extra)
+        template_path = TEMPLATES_DIR / "prompt.mustache"
+        template_text = template_path.read_text() if template_path.exists() else "{{title}}\n\n{{semantic_description}}"
+        content = self._mustache.render(template_text, ctx)
+        return Artifact.create(
+            artifact_type=ArtifactType.PROMPT,
+            semantic_root=ir.ir_id,
+            template="prompt.mustache",
+            content=content,
+            provenance=ir.provenance,
+            temporal_state=ir.root.temporal_state,
+        )
+
+    def build_document(self, ir: SemanticIR, extra: dict | None = None) -> Artifact:
+        ctx = self._ir_to_mustache_ctx(ir)
+        if extra:
+            ctx.update(extra)
+        template_path = TEMPLATES_DIR / "document.mustache"
+        template_text = template_path.read_text() if template_path.exists() else "# {{title}}\n\n{{semantic_description}}"
+        content = self._mustache.render(template_text, ctx)
+        return Artifact.create(
+            artifact_type=ArtifactType.DOCUMENT,
+            semantic_root=ir.ir_id,
+            template="document.mustache",
+            content=content,
+            provenance=ir.provenance,
+            temporal_state=ir.root.temporal_state,
+        )
+
+    def build_backend(self, ir: SemanticIR, extra: dict | None = None) -> Artifact:
+        data = self._ir_to_go_data(ir)
+        if extra:
+            if isinstance(data, dict):
+                data.update(extra)
+        template_path = TEMPLATES_DIR / "backend.go.tmpl"
+        template_text = template_path.read_text() if template_path.exists() else "// {{.SemanticRoot}}"
+        content = self._go.render(template_text, data)
+        return Artifact.create(
+            artifact_type=ArtifactType.BACKEND,
+            semantic_root=ir.ir_id,
+            template="backend.go.tmpl",
+            content=content,
+            provenance=ir.provenance,
+            temporal_state=ir.root.temporal_state,
+        )
+
+    def _ir_to_mustache_ctx(self, ir: SemanticIR) -> dict:
+        return {
+            "title":                ir.intent.value.upper(),
+            "semantic_description": f"Intent: {ir.intent.value} | Nodes: {len(ir.nodes)}",
+            "constraints":          [c.description for n in ir.nodes for c in n.constraints],
+            "operations":           [n.operation.name for n in ir.nodes if n.operation],
+            "geometry":             [str(n.geometry) for n in ir.nodes if n.geometry and n.geometry.row],
+            "provenance":           [ir.provenance.stage],
+            "code":                 None,
+            "tests":                None,
+        }
+
+    def _ir_to_go_data(self, ir: SemanticIR) -> dict:
+        return {
+            "SemanticRoot": ir.ir_id,
+            "Tau":          ir.root.temporal_state.tau,
+            "Verified":     ir.verification_state == VerificationState.VERIFIED,
+            "Package":      "generated",
+            "Types":        [],
+            "Operations":   [
+                {
+                    "Name":       (n.operation.name.capitalize() if n.operation else "NoOp"),
+                    "SemanticID": n.id,
+                    "Params":     [{"Name": o.name, "Type": o.type_tag} for o in n.operands],
+                    "ReturnType": "interface{}",
+                    "Constraints": [c.description for c in n.constraints],
+                    "Body":       f'\treturn nil, fmt.Errorf("not implemented: {n.id}")',
+                }
+                for n in ir.nodes if n.operation
+            ],
+            "Tests": [],
+        }

src/semantic_engine/boolean_engine.py

@@ -0,0 +1,261 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Phase 7: Boolean engine — deterministic normalization to CNF/DNF."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional, Union
+import hashlib
+
+from .types import BooleanOperator, FSMState, PipelineError
+
+
+# ── Boolean expression tree ───────────────────────────────────────────────────
+
+@dataclass
+class BooleanLiteral:
+    value: bool
+
+    def __repr__(self) -> str:
+        return "⊤" if self.value else "⊥"
+
+    def negate(self) -> BooleanLiteral:
+        return BooleanLiteral(not self.value)
+
+
+@dataclass
+class BooleanVar:
+    name: str
+    negated: bool = False
+
+    def __repr__(self) -> str:
+        return f"¬{self.name}" if self.negated else self.name
+
+    def negate(self) -> BooleanVar:
+        return BooleanVar(self.name, not self.negated)
+
+
+BooleanAtom = Union[BooleanLiteral, BooleanVar]
+
+
+@dataclass
+class BooleanExpression:
+    operator: BooleanOperator
+    operands: list[Union[BooleanExpression, BooleanAtom]] = field(default_factory=list)
+    constraint_refs: list[str] = field(default_factory=list)
+
+    def __repr__(self) -> str:
+        if self.operator == BooleanOperator.TRUE:
+            return "⊤"
+        if self.operator == BooleanOperator.FALSE:
+            return "⊥"
+        if self.operator == BooleanOperator.NOT:
+            return f"¬({self.operands[0]})"
+        sym = {
+            BooleanOperator.AND:         "∧",
+            BooleanOperator.OR:          "∨",
+            BooleanOperator.XOR:         "⊕",
+            BooleanOperator.IMPLIES:     "→",
+            BooleanOperator.EQUIVALENCE: "↔",
+        }.get(self.operator, str(self.operator))
+        inner = f" {sym} ".join(str(o) for o in self.operands)
+        return f"({inner})"
+
+    def hash(self) -> str:
+        return hashlib.sha256(repr(self).encode()).hexdigest()[:16]
+
+
+# ── Constructors ──────────────────────────────────────────────────────────────
+
+def var(name: str, negated: bool = False) -> BooleanVar:
+    return BooleanVar(name, negated)
+
+def lit(value: bool) -> BooleanLiteral:
+    return BooleanLiteral(value)
+
+def AND(*args) -> BooleanExpression:
+    return BooleanExpression(BooleanOperator.AND, list(args))
+
+def OR(*args) -> BooleanExpression:
+    return BooleanExpression(BooleanOperator.OR, list(args))
+
+def NOT(x) -> BooleanExpression:
+    return BooleanExpression(BooleanOperator.NOT, [x])
+
+def XOR(a, b) -> BooleanExpression:
+    return BooleanExpression(BooleanOperator.XOR, [a, b])
+
+def IMPLIES(a, b) -> BooleanExpression:
+    return BooleanExpression(BooleanOperator.IMPLIES, [a, b])
+
+def EQUIV(a, b) -> BooleanExpression:
+    return BooleanExpression(BooleanOperator.EQUIVALENCE, [a, b])
+
+
+# ── Simplification ────────────────────────────────────────────────────────────
+
+Expr = Union[BooleanExpression, BooleanAtom]
+
+
+def simplify(expr: Expr) -> Expr:
+    """Simplify constants and double negations."""
+    if isinstance(expr, (BooleanLiteral, BooleanVar)):
+        return expr
+
+    expr = BooleanExpression(expr.operator, [simplify(o) for o in expr.operands], expr.constraint_refs)
+
+    op = expr.operator
+
+    # Constant folding
+    if op == BooleanOperator.NOT:
+        inner = expr.operands[0]
+        if isinstance(inner, BooleanLiteral):
+            return BooleanLiteral(not inner.value)
+        if isinstance(inner, BooleanVar):
+            return inner.negate()
+        if isinstance(inner, BooleanExpression) and inner.operator == BooleanOperator.NOT:
+            return inner.operands[0]  # ¬¬A → A
+
+    if op == BooleanOperator.AND:
+        if any(isinstance(o, BooleanLiteral) and not o.value for o in expr.operands):
+            return BooleanLiteral(False)
+        expr.operands = [o for o in expr.operands if not (isinstance(o, BooleanLiteral) and o.value)]
+        if not expr.operands:
+            return BooleanLiteral(True)
+        if len(expr.operands) == 1:
+            return expr.operands[0]
+
+    if op == BooleanOperator.OR:
+        if any(isinstance(o, BooleanLiteral) and o.value for o in expr.operands):
+            return BooleanLiteral(True)
+        expr.operands = [o for o in expr.operands if not (isinstance(o, BooleanLiteral) and not o.value)]
+        if not expr.operands:
+            return BooleanLiteral(False)
+        if len(expr.operands) == 1:
+            return expr.operands[0]
+
+    # A → B  ≡  ¬A ∨ B
+    if op == BooleanOperator.IMPLIES:
+        a, b = expr.operands[0], expr.operands[1]
+        return simplify(OR(NOT(a), b))
+
+    # A ↔ B  ≡  (A → B) ∧ (B → A)
+    if op == BooleanOperator.EQUIVALENCE:
+        a, b = expr.operands[0], expr.operands[1]
+        return simplify(AND(IMPLIES(a, b), IMPLIES(b, a)))
+
+    # A ⊕ B  ≡  (A ∨ B) ∧ ¬(A ∧ B)
+    if op == BooleanOperator.XOR:
+        a, b = expr.operands[0], expr.operands[1]
+        return simplify(AND(OR(a, b), NOT(AND(a, b))))
+
+    return expr
+
+
+def push_not_inward(expr: Expr) -> Expr:
+    """Apply De Morgan's laws, push negations to leaves."""
+    if isinstance(expr, (BooleanLiteral, BooleanVar)):
+        return expr
+
+    if expr.operator == BooleanOperator.NOT:
+        inner = expr.operands[0]
+        if isinstance(inner, BooleanLiteral):
+            return BooleanLiteral(not inner.value)
+        if isinstance(inner, BooleanVar):
+            return inner.negate()
+        if isinstance(inner, BooleanExpression):
+            if inner.operator == BooleanOperator.NOT:
+                return push_not_inward(inner.operands[0])
+            if inner.operator == BooleanOperator.AND:
+                return push_not_inward(OR(*[NOT(o) for o in inner.operands]))
+            if inner.operator == BooleanOperator.OR:
+                return push_not_inward(AND(*[NOT(o) for o in inner.operands]))
+
+    return BooleanExpression(
+        expr.operator,
+        [push_not_inward(o) for o in expr.operands],
+        expr.constraint_refs,
+    )
+
+
+def distribute_or_over_and(expr: Expr) -> Expr:
+    """Distribute OR over AND to produce CNF."""
+    if isinstance(expr, (BooleanLiteral, BooleanVar)):
+        return expr
+
+    expr = BooleanExpression(
+        expr.operator,
+        [distribute_or_over_and(o) for o in expr.operands],
+        expr.constraint_refs,
+    )
+
+    if expr.operator == BooleanOperator.OR:
+        # Find any AND among operands
+        for i, op in enumerate(expr.operands):
+            if isinstance(op, BooleanExpression) and op.operator == BooleanOperator.AND:
+                others = expr.operands[:i] + expr.operands[i+1:]
+                distributed = AND(*[
+                    distribute_or_over_and(OR(clause, *others))
+                    for clause in op.operands
+                ])
+                return distribute_or_over_and(distributed)
+
+    return expr
+
+
+def to_cnf(expr: Expr) -> Expr:
+    """Convert to Conjunctive Normal Form."""
+    e = simplify(expr)
+    e = push_not_inward(e)
+    e = distribute_or_over_and(e)
+    e = simplify(e)
+    return e
+
+
+def normalize(expr: Expr) -> Expr:
+    """
+    Deterministic normalization. normalize(normalize(x)) == normalize(x).
+    """
+    result = to_cnf(expr)
+    # Idempotency check
+    again = to_cnf(result)
+    if repr(again) != repr(result):
+        result = again
+    return result
+
+
+# ── Boolean Normal Form container ─────────────────────────────────────────────
+
+@dataclass
+class BooleanNormalForm:
+    original: Expr
+    normalized: Expr
+    form: str = "CNF"
+    stable: bool = False
+
+    def verify_stability(self) -> bool:
+        again = normalize(self.normalized)
+        self.stable = repr(again) == repr(self.normalized)
+        return self.stable
+
+
+# ── Semantic → Boolean ────────────────────────────────────────────────────────
+
+def semantic_constraints_to_boolean(constraints: list) -> BooleanNormalForm:
+    """
+    Convert a list of Constraint objects into a Boolean expression.
+    Each constraint becomes a BooleanVar. Constraints are AND-ed together.
+    """
+    if not constraints:
+        expr: Expr = BooleanLiteral(True)
+    else:
+        vars_ = [var(c.predicate if hasattr(c, "predicate") else str(c)) for c in constraints]
+        expr = vars_[0] if len(vars_) == 1 else AND(*vars_)
+
+    norm = normalize(expr)
+    bnf = BooleanNormalForm(original=expr, normalized=norm)
+    bnf.verify_stability()
+    return bnf

src/semantic_engine/fsm.py

@@ -0,0 +1,128 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Phase 3: Decoder FSM — explicit state machine with typed transitions.
+
+Every transition is explicit. Every invalid transition fails closed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+from .types import FSMState, FSMTransition, PipelineError
+
+
+# ── Transition table ──────────────────────────────────────────────────────────
+
+TRANSITION_TABLE: list[FSMTransition] = [
+    FSMTransition(FSMState.INPUT,                "raw_input",         "normalize",             ("text_not_empty",),            FSMState.NORMALIZE,              "input preserved"),
+    FSMTransition(FSMState.NORMALIZE,            "normalized_input",  "lex",                   ("tokens_non_empty",),          FSMState.LEXICAL_ANALYSIS,       "normalization idempotent"),
+    FSMTransition(FSMState.LEXICAL_ANALYSIS,     "token_stream",      "detect_intent",         ("tokens_recognized",),         FSMState.INTENT_DETECTION,       "lexical coverage"),
+    FSMTransition(FSMState.INTENT_DETECTION,     "intent_class",      "bind_entities",         ("intent_not_unknown",),        FSMState.ENTITY_BINDING,         "intent classified"),
+    FSMTransition(FSMState.ENTITY_BINDING,       "entities",          "bind_semantics",        ("entities_typed",),            FSMState.SEMANTIC_BINDING,       "entities resolved"),
+    FSMTransition(FSMState.SEMANTIC_BINDING,     "semantic_candidate","lock_temporal",         ("candidate_valid",),           FSMState.TEMPORAL_LOCK,          "semantic candidate valid"),
+    FSMTransition(FSMState.TEMPORAL_LOCK,        "temporal_state",    "bind_geometry",         ("tau_monotonic",),             FSMState.GEOMETRY_BINDING,       "tau assigned"),
+    FSMTransition(FSMState.GEOMETRY_BINDING,     "geometry",          "build_matrix",          ("geometry_consistent",),       FSMState.MATRIX_FORM,            "dimensions compatible"),
+    FSMTransition(FSMState.MATRIX_FORM,          "semantic_matrix",   "resolve_boolean",       ("matrix_well_formed",),        FSMState.BOOLEAN_ROOT,           "matrix non-degenerate"),
+    FSMTransition(FSMState.BOOLEAN_ROOT,         "boolean_expr",      "normalize_boolean",     ("boolean_valid",),             FSMState.BOOLEAN_NORMALIZATION,  "boolean well-formed"),
+    FSMTransition(FSMState.BOOLEAN_NORMALIZATION,"normalized_boolean","tokenize",              ("normal_form_stable",),        FSMState.TOKENIZATION,           "normalization idempotent"),
+    FSMTransition(FSMState.TOKENIZATION,         "token_stream",      "canonicalize_latin",    ("tokens_round_trip",),         FSMState.LATIN_CANONICALIZATION, "encode/decode invariant"),
+    FSMTransition(FSMState.LATIN_CANONICALIZATION,"latin_form",       "lex_latin",             ("vocabulary_closed",),         FSMState.LATIN_LEXING,           "vocabulary complete"),
+    FSMTransition(FSMState.LATIN_LEXING,         "latin_tokens",      "map_rosetta",           ("latin_tokens_valid",),        FSMState.ROSETTA_MAPPING,        "all tokens mapped"),
+    FSMTransition(FSMState.ROSETTA_MAPPING,      "rosetta_mapping",   "build_subleq",          ("mapping_complete",),          FSMState.SUBLEQ_IR,              "all operations mapped"),
+    FSMTransition(FSMState.SUBLEQ_IR,            "subleq_program",    "verify",                ("subleq_valid",),              FSMState.VERIFICATION,           "program halts"),
+    FSMTransition(FSMState.VERIFICATION,         "verified_ir",       "select_artifact",       ("all_checks_pass",),           FSMState.ARTIFACT_SELECTION,     "verification passed"),
+    FSMTransition(FSMState.ARTIFACT_SELECTION,   "artifact_type",     "emit",                  ("template_bound",),            FSMState.EMISSION,               "template resolved"),
+    FSMTransition(FSMState.EMISSION,             "artifact",          "complete",              ("artifact_provenance_ok",),    FSMState.COMPLETE,               "artifact complete"),
+    FSMTransition(FSMState.COMPLETE,             "done",              "noop",                  (),                             FSMState.COMPLETE,               "terminal"),
+    # Error transitions — any state can go to ERROR
+    FSMTransition(FSMState.INPUT,                "invalid",           "fail",                  ("error_logged",),              FSMState.ERROR,                  "fail closed"),
+]
+
+# Build lookup: (source_state, input_class) → transition
+_TRANSITION_MAP: dict[tuple[FSMState, str], FSMTransition] = {
+    (t.source_state, t.input_class): t for t in TRANSITION_TABLE
+}
+
+
+# ── FSM context ───────────────────────────────────────────────────────────────
+
+@dataclass
+class FSMContext:
+    state: FSMState = FSMState.INPUT
+    history: list[tuple[FSMState, str, FSMState]] = field(default_factory=list)
+    data: dict[str, object] = field(default_factory=dict)
+    error: Optional[str] = None
+
+    def transition(self, input_class: str) -> FSMTransition:
+        key = (self.state, input_class)
+        t = _TRANSITION_MAP.get(key)
+        if t is None:
+            # Also try any-state error transition
+            err = _TRANSITION_MAP.get((self.state, "invalid"))
+            if err:
+                self.history.append((self.state, input_class, FSMState.ERROR))
+                self.state = FSMState.ERROR
+                self.error = f"No transition from {self.state.name} on input '{input_class}'"
+                raise PipelineError(self.state, f"No valid transition on '{input_class}'")
+            raise PipelineError(
+                self.state,
+                f"No transition from {self.state.name} on '{input_class}' — fail closed",
+            )
+        self.history.append((self.state, input_class, t.destination_state))
+        self.state = t.destination_state
+        return t
+
+    def set(self, key: str, value: object) -> None:
+        self.data[key] = value
+
+    def get(self, key: str) -> object:
+        return self.data.get(key)
+
+    def is_terminal(self) -> bool:
+        return self.state in (FSMState.COMPLETE, FSMState.ERROR)
+
+    def dump_history(self) -> list[str]:
+        return [f"{src.name} --[{inp}]--> {dst.name}" for src, inp, dst in self.history]
+
+
+# ── Constraint validators ─────────────────────────────────────────────────────
+
+ConstraintValidator = Callable[[FSMContext], bool]
+
+_VALIDATORS: dict[str, ConstraintValidator] = {
+    "text_not_empty":       lambda ctx: bool(str(ctx.get("raw_text") or "").strip()),
+    "tokens_non_empty":     lambda ctx: bool(ctx.get("tokens")),
+    "tokens_recognized":    lambda ctx: True,  # lexer failure raises
+    "intent_not_unknown":   lambda ctx: ctx.get("intent") != "unknown",
+    "entities_typed":       lambda ctx: True,
+    "candidate_valid":      lambda ctx: ctx.get("candidate") is not None,
+    "tau_monotonic":        lambda ctx: True,  # TemporalLock.record enforces this
+    "geometry_consistent":  lambda ctx: True,  # GeometryError raised on violation
+    "matrix_well_formed":   lambda ctx: True,
+    "boolean_valid":        lambda ctx: True,
+    "normal_form_stable":   lambda ctx: True,
+    "tokens_round_trip":    lambda ctx: True,
+    "vocabulary_closed":    lambda ctx: True,
+    "latin_tokens_valid":   lambda ctx: True,
+    "mapping_complete":     lambda ctx: True,
+    "subleq_valid":         lambda ctx: True,
+    "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,
+    "error_logged":         lambda ctx: True,
+}
+
+
+def validate_constraints(transition: FSMTransition, ctx: FSMContext) -> None:
+    for c in transition.constraints:
+        validator = _VALIDATORS.get(c)
+        if validator and not validator(ctx):
+            raise PipelineError(
+                ctx.state,
+                f"Invariant '{c}' violated on transition {transition.source_state.name} "
+                f"→ {transition.destination_state.name}",
+            )

src/semantic_engine/geometry.py

@@ -0,0 +1,114 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Phase 5: Geometry engine — explicit dimensional constraints for operations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .types import FSMState, GeometryError
+from .ir import Geometry, SemanticNode
+
+
+@dataclass
+class DimCheck:
+    """Result of a dimensional compatibility check."""
+    ok: bool
+    reason: str
+    output: Optional[Geometry] = None
+
+
+def check_matmul(a: Geometry, b: Geometry) -> DimCheck:
+    """A ∈ R^(m×n), B ∈ R^(n×p) → C ∈ R^(m×p). Requires a.col == b.row."""
+    if a.col is None or b.row is None:
+        return DimCheck(ok=True, reason="underdetermined", output=Geometry())
+    if a.col != b.row:
+        return DimCheck(
+            ok=False,
+            reason=f"contraction mismatch: A.col={a.col} ≠ B.row={b.row}",
+        )
+    return DimCheck(
+        ok=True,
+        reason="compatible",
+        output=Geometry(row=a.row, col=b.col, contraction=a.col),
+    )
+
+
+def check_elementwise(a: Geometry, b: Geometry, op: str) -> DimCheck:
+    """Element-wise ops (add, subtract, XOR) require identical shapes."""
+    if a.shape and b.shape:
+        if a.shape != b.shape:
+            return DimCheck(ok=False, reason=f"{op}: shape mismatch {a.shape} ≠ {b.shape}")
+    if a.row is not None and b.row is not None and a.row != b.row:
+        return DimCheck(ok=False, reason=f"{op}: row mismatch {a.row} ≠ {b.row}")
+    if a.col is not None and b.col is not None and a.col != b.col:
+        return DimCheck(ok=False, reason=f"{op}: col mismatch {a.col} ≠ {b.col}")
+    return DimCheck(ok=True, reason="compatible", output=a)
+
+
+def enforce_geometry(node: SemanticNode) -> Geometry:
+    """
+    Validate geometry for a semantic node's operation.
+    Raises GeometryError if dimensions are incompatible.
+    Returns the output geometry.
+    """
+    op = node.operation
+    operands = node.operands
+
+    if op is None:
+        return node.geometry or Geometry()
+
+    if op.name in ("multiply", "matmul"):
+        if len(operands) < 2:
+            return node.geometry or Geometry()  # underdetermined — not a violation
+        a_geom = operands[0].geometry or Geometry()
+        b_geom = operands[1].geometry or Geometry()
+        result = check_matmul(a_geom, b_geom)
+        if not result.ok:
+            raise GeometryError(FSMState.GEOMETRY_BINDING, result.reason)
+        return result.output or Geometry()
+
+    if op.name in ("add", "subtract"):
+        if len(operands) < 2:
+            raise GeometryError(FSMState.GEOMETRY_BINDING, f"{op.name} requires 2 operands")
+        a_geom = operands[0].geometry or Geometry()
+        b_geom = operands[1].geometry or Geometry()
+        result = check_elementwise(a_geom, b_geom, op.name)
+        if not result.ok:
+            raise GeometryError(FSMState.GEOMETRY_BINDING, result.reason)
+        return result.output or Geometry()
+
+    # Unknown op — pass through without geometry enforcement
+    return node.geometry or Geometry()
+
+
+def parse_geometry(spec: str) -> Geometry:
+    """
+    Parse a geometry spec string like "3x4", "(3,4)", "R^(3x4)", "scalar".
+    Returns a Geometry instance.
+    """
+    import re
+    spec = spec.strip()
+
+    if spec.lower() in ("scalar", "1", "1x1"):
+        return Geometry(row=1, col=1, shape=(1, 1))
+
+    m = re.match(r"[Rr]\^?\(?(\d+)[x×,](\d+)\)?", spec)
+    if m:
+        r, c = int(m.group(1)), int(m.group(2))
+        return Geometry(row=r, col=c, shape=(r, c))
+
+    m = re.match(r"(\d+)[x×,](\d+)", spec)
+    if m:
+        r, c = int(m.group(1)), int(m.group(2))
+        return Geometry(row=r, col=c, shape=(r, c))
+
+    m = re.match(r"(\d+)", spec)
+    if m:
+        n = int(m.group(1))
+        return Geometry(row=n, col=1, shape=(n,))
+
+    return Geometry()

src/semantic_engine/ir.py

@@ -0,0 +1,255 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Phase 2: Semantic IR — typed intermediate representation, the canonical source of truth."""
+
+from __future__ import annotations
+
+import hashlib
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from .types import (
+    ArtifactType, IntentClass, Provenance, SemanticNodeType,
+    TemporalViolation, VerificationState, FSMState,
+)
+
+
+# ── Geometry ──────────────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class Geometry:
+    """Explicit dimensional description of an operation's operands."""
+    row: Optional[int] = None
+    col: Optional[int] = None
+    contraction: Optional[int] = None
+    shape: tuple[int, ...] = field(default_factory=tuple)
+    index_labels: tuple[str, ...] = field(default_factory=tuple)
+
+    def compatible_with(self, other: Geometry) -> bool:
+        """Check whether self and other can be contracted (matrix multiply)."""
+        if self.col is None or other.row is None:
+            return True  # undetermined — not a violation yet
+        return self.col == other.row
+
+    def output_geometry(self, other: Geometry) -> Geometry:
+        if self.row is None or other.col is None:
+            return Geometry()
+        return Geometry(row=self.row, col=other.col, contraction=self.col)
+
+
+# ── Temporal state ────────────────────────────────────────────────────────────
+
+@dataclass
+class TemporalState:
+    tau: int  # monotonic integer tick
+    label: str = ""
+    locked: bool = False
+
+    def advance(self, reason: str = "") -> TemporalState:
+        if self.locked:
+            raise TemporalViolation(FSMState.TEMPORAL_LOCK, "Cannot advance a locked temporal state")
+        return TemporalState(tau=self.tau + 1, label=reason)
+
+    def lock(self) -> TemporalState:
+        return TemporalState(tau=self.tau, label=self.label, locked=True)
+
+
+@dataclass(frozen=True)
+class TemporalTransition:
+    from_tau: int
+    to_tau: int
+    reason: str
+    stage: str
+
+    def is_valid(self) -> bool:
+        return self.to_tau == self.from_tau + 1 or self.to_tau == self.from_tau
+
+
+@dataclass
+class TemporalLock:
+    transitions: list[TemporalTransition] = field(default_factory=list)
+
+    def record(self, t: TemporalTransition) -> None:
+        if not t.is_valid():
+            raise TemporalViolation(
+                FSMState.TEMPORAL_LOCK,
+                f"Invalid temporal jump: τ{t.from_tau} → τ{t.to_tau} (expected +1 or 0)",
+            )
+        self.transitions.append(t)
+
+    def audit(self) -> list[TemporalTransition]:
+        return list(self.transitions)
+
+
+# ── Core IR nodes ─────────────────────────────────────────────────────────────
+
+@dataclass
+class Operand:
+    name: str
+    type_tag: str
+    value: Any = None
+    geometry: Optional[Geometry] = None
+
+    @property
+    def node_id(self) -> str:
+        return hashlib.sha256(f"operand:{self.name}:{self.type_tag}".encode()).hexdigest()[:16]
+
+
+@dataclass
+class Constraint:
+    constraint_id: str
+    description: str
+    predicate: str
+    operands: list[str] = field(default_factory=list)
+
+    @staticmethod
+    def make(description: str, predicate: str, operands: list[str] | None = None) -> Constraint:
+        cid = hashlib.sha256(f"{predicate}:{description}".encode()).hexdigest()[:16]
+        return Constraint(
+            constraint_id=cid,
+            description=description,
+            predicate=predicate,
+            operands=operands or [],
+        )
+
+
+@dataclass
+class SemanticOperation:
+    name: str
+    arity: int
+    description: str = ""
+    associative: bool = False
+    commutative: bool = False
+
+    @property
+    def op_id(self) -> str:
+        return hashlib.sha256(f"op:{self.name}:{self.arity}".encode()).hexdigest()[:16]
+
+
+@dataclass
+class SemanticNode:
+    id: str
+    type: SemanticNodeType
+    operation: Optional[SemanticOperation]
+    operands: list[Operand]
+    constraints: list[Constraint]
+    geometry: Optional[Geometry]
+    temporal_state: TemporalState
+    provenance: Provenance
+    children: list[SemanticNode] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @staticmethod
+    def make(
+        node_type: SemanticNodeType,
+        operation: Optional[SemanticOperation],
+        operands: list[Operand],
+        constraints: list[Constraint],
+        geometry: Optional[Geometry],
+        temporal_state: TemporalState,
+        provenance: Provenance,
+    ) -> SemanticNode:
+        content = f"{node_type}:{operation}:{[o.name for o in operands]}"
+        node_id = hashlib.sha256(content.encode()).hexdigest()[:24]
+        return SemanticNode(
+            id=node_id,
+            type=node_type,
+            operation=operation,
+            operands=operands,
+            constraints=constraints,
+            geometry=geometry,
+            temporal_state=temporal_state,
+            provenance=provenance,
+        )
+
+    def hash(self) -> str:
+        content = f"{self.id}:{self.type}:{self.operation}:{len(self.operands)}"
+        return hashlib.sha256(content.encode()).hexdigest()
+
+
+# ── Semantic IR root ──────────────────────────────────────────────────────────
+
+@dataclass
+class SemanticIR:
+    ir_id: str
+    intent: IntentClass
+    root: SemanticNode
+    nodes: list[SemanticNode]
+    temporal_lock: TemporalLock
+    provenance: Provenance
+    verification_state: VerificationState = VerificationState.UNVERIFIED
+    output_mode: str = "natural_language"
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @staticmethod
+    def create(
+        intent: IntentClass,
+        root: SemanticNode,
+        nodes: list[SemanticNode],
+        temporal_lock: TemporalLock,
+        provenance: Provenance,
+    ) -> SemanticIR:
+        ir_id = str(uuid.uuid4())
+        return SemanticIR(
+            ir_id=ir_id,
+            intent=intent,
+            root=root,
+            nodes=nodes,
+            temporal_lock=temporal_lock,
+            provenance=provenance,
+        )
+
+    def hash(self) -> str:
+        node_hashes = ":".join(n.hash() for n in self.nodes)
+        return hashlib.sha256(f"{self.ir_id}:{self.intent}:{node_hashes}".encode()).hexdigest()
+
+    def add_node(self, node: SemanticNode) -> None:
+        self.nodes.append(node)
+
+    def find_node(self, node_id: str) -> Optional[SemanticNode]:
+        return next((n for n in self.nodes if n.id == node_id), None)
+
+
+# ── Artifact IR ───────────────────────────────────────────────────────────────
+
+@dataclass
+class Artifact:
+    id: str
+    type: ArtifactType
+    semantic_root: str  # SemanticIR.ir_id
+    template: str
+    content: str
+    provenance: Provenance
+    temporal_state: TemporalState
+    verification_state: VerificationState = VerificationState.UNVERIFIED
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @staticmethod
+    def create(
+        artifact_type: ArtifactType,
+        semantic_root: str,
+        template: str,
+        content: str,
+        provenance: Provenance,
+        temporal_state: TemporalState,
+    ) -> Artifact:
+        artifact_id = hashlib.sha256(
+            f"{artifact_type}:{semantic_root}:{content[:64]}".encode()
+        ).hexdigest()[:24]
+        return Artifact(
+            id=artifact_id,
+            type=artifact_type,
+            semantic_root=semantic_root,
+            template=template,
+            content=content,
+            provenance=provenance,
+            temporal_state=temporal_state,
+        )
+
+    def hash(self) -> str:
+        return hashlib.sha256(
+            f"{self.id}:{self.type}:{self.content}".encode()
+        ).hexdigest()

src/semantic_engine/latin.py

@@ -0,0 +1,151 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Phase 9: Latin canonicalizer — controlled vocabulary mapping.
+
+Boolean tokens → Semantic IDs → Latin lexemes.
+Every Latin lexeme maps to a stable semantic_id. No uncontrolled synonyms.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from .token_engine import (
+    BoolToken, BooleanTokenStream,
+    TTYPE_AND, TTYPE_OR, TTYPE_NOT, TTYPE_XOR,
+    TTYPE_IMPLIES, TTYPE_EQUIVALENCE, TTYPE_TRUE, TTYPE_FALSE,
+    TTYPE_OPEN, TTYPE_CLOSE, TTYPE_VAR, TTYPE_VAR_NEG,
+)
+from .types import FSMState, PipelineError
+
+# Map from token type → canonical Latin lexeme
+_TTYPE_TO_LATIN: dict[int, str] = {
+    TTYPE_AND:         "ET",
+    TTYPE_OR:          "VEL",
+    TTYPE_NOT:         "NON",
+    TTYPE_XOR:         "AUT",
+    TTYPE_IMPLIES:     "SI",
+    TTYPE_EQUIVALENCE: "IFF",
+    TTYPE_TRUE:        "VERUM",
+    TTYPE_FALSE:       "FALSUM",
+    TTYPE_OPEN:        "INITIUM",
+    TTYPE_CLOSE:       "FINIS",
+}
+
+_LATIN_TO_TTYPE: dict[str, int] = {v: k for k, v in _TTYPE_TO_LATIN.items()}
+
+
+# ── Latin token ───────────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class LatinToken:
+    lexeme: str
+    semantic_id: str
+    position: int
+    payload: str = ""       # variable name for VAR tokens
+
+
+@dataclass
+class LatinLexeme:
+    word: str
+    semantic_id: str
+    operator: Optional[str]
+    arity: int
+
+
+@dataclass
+class LatinCanonicalForm:
+    tokens: list[LatinToken] = field(default_factory=list)
+    source_hash: str = ""
+
+    def text(self) -> str:
+        return " ".join(t.lexeme if not t.payload else f"{t.lexeme}[{t.payload}]" for t in self.tokens)
+
+
+# ── Vocabulary loader ─────────────────────────────────────────────────────────
+
+def _load_vocabulary() -> dict[str, LatinLexeme]:
+    vocab_path = Path(__file__).parent.parent.parent / "lexicon" / "latin_vocabulary.json"
+    if not vocab_path.exists():
+        return {}
+    data = json.loads(vocab_path.read_text())
+    return {
+        word: LatinLexeme(
+            word=word,
+            semantic_id=entry["semantic_id"],
+            operator=entry.get("operator"),
+            arity=entry.get("arity", 0),
+        )
+        for word, entry in data.get("lexemes", {}).items()
+    }
+
+
+_VOCABULARY: dict[str, LatinLexeme] = {}
+
+
+def vocabulary() -> dict[str, LatinLexeme]:
+    global _VOCABULARY
+    if not _VOCABULARY:
+        _VOCABULARY = _load_vocabulary()
+    return _VOCABULARY
+
+
+# ── Canonicalizer ─────────────────────────────────────────────────────────────
+
+class LatinCanonicalizer:
+    """Transform a BooleanTokenStream into a LatinCanonicalForm."""
+
+    def canonicalize(self, stream: BooleanTokenStream) -> LatinCanonicalForm:
+        vocab = vocabulary()
+        tokens: list[LatinToken] = []
+
+        for i, tok in enumerate(stream.tokens):
+            if tok.token_type in (TTYPE_VAR, TTYPE_VAR_NEG):
+                lexeme = "NON" if tok.token_type == TTYPE_VAR_NEG else "OPUS"
+                sem_id = "BOOL_NOT" if tok.token_type == TTYPE_VAR_NEG else "SEMANTIC_OP"
+                var_name = tok.payload.decode("utf-8") if tok.payload else ""
+                if tok.token_type == TTYPE_VAR_NEG:
+                    tokens.append(LatinToken(lexeme="NON", semantic_id="BOOL_NOT", position=i))
+                tokens.append(LatinToken(
+                    lexeme="OPUS",
+                    semantic_id="SEMANTIC_OP",
+                    position=i,
+                    payload=var_name,
+                ))
+                continue
+
+            latin = _TTYPE_TO_LATIN.get(tok.token_type)
+            if latin is None:
+                raise PipelineError(
+                    FSMState.LATIN_CANONICALIZATION,
+                    f"No Latin mapping for token type 0x{tok.token_type:02x} at position {i}",
+                )
+
+            lexeme_def = vocab.get(latin)
+            if lexeme_def is None:
+                raise PipelineError(
+                    FSMState.LATIN_CANONICALIZATION,
+                    f"Latin lexeme '{latin}' not in controlled vocabulary",
+                )
+
+            tokens.append(LatinToken(
+                lexeme=latin,
+                semantic_id=lexeme_def.semantic_id,
+                position=i,
+            ))
+
+        import hashlib
+        src_hash = hashlib.sha256(" ".join(t.lexeme for t in tokens).encode()).hexdigest()[:16]
+        return LatinCanonicalForm(tokens=tokens, source_hash=src_hash)
+
+
+# ── Inverse: Latin → semantic IDs ─────────────────────────────────────────────
+
+def latin_to_semantic_ids(form: LatinCanonicalForm) -> list[tuple[str, str]]:
+    """Return list of (lexeme, semantic_id) pairs."""
+    return [(t.lexeme, t.semantic_id) for t in form.tokens]

src/semantic_engine/lexer.py

@@ -0,0 +1,144 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Phase 10: Regex Latin lexer — token recognition and field extraction.
+
+The lexer recognizes structure. It does NOT determine semantic meaning.
+Invalid Latin blocks fail closed.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .latin import LatinCanonicalForm, LatinToken, vocabulary
+from .types import FSMState, PipelineError
+
+
+# ── Regex patterns ────────────────────────────────────────────────────────────
+
+# Block delimiters
+_RE_BLOCK_OPEN    = re.compile(r"\bINITIUM\b")
+_RE_BLOCK_CLOSE   = re.compile(r"\bFINIS\b")
+
+# Operators
+_RE_OPERATORS     = re.compile(
+    r"\b(ET|VEL|NON|AUT|SI|IFF|VERUM|FALSUM)\b"
+)
+
+# Operands with optional payload: OPUS[varname]
+_RE_OPERAND       = re.compile(r"\b(OPUS|FORMA|COMPUTA|MULTIPLICA|ADDE|SUBTRAHE|PARSE|"
+                                r"AEDIFICA|GENERA|VERIFICA|CONVERTE|RESTITUE|"
+                                r"MATRIX|VECTOR|PARSER|SERVITIUM|FORMA_BINARIA|TEMPUS)"
+                                r"(?:\[([^\]]*)\])?")
+
+# Instruction fields: KEYWORD:VALUE
+_RE_FIELD         = re.compile(r"\b([A-Z_]+):(\S+)")
+
+# Delimiters — semicolons, pipes
+_RE_DELIM         = re.compile(r"[;|]")
+
+
+@dataclass(frozen=True)
+class LexedToken:
+    kind: str           # "operator", "operand", "open", "close", "field", "delim", "unknown"
+    lexeme: str
+    payload: str = ""
+    position: int = 0
+
+
+@dataclass
+class LexResult:
+    tokens: list[LexedToken] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    valid: bool = True
+
+
+# ── Lexer ─────────────────────────────────────────────────────────────────────
+
+class LatinLexer:
+    """
+    Regex-based lexer for Latin canonical form text.
+    Produces LexResult with typed tokens.
+    """
+
+    def lex(self, text: str) -> LexResult:
+        result = LexResult()
+        vocab = vocabulary()
+        pos = 0
+        tpos = 0
+
+        # Tokenize by scanning left to right
+        while pos < len(text):
+            # Skip whitespace
+            ws = re.match(r"\s+", text[pos:])
+            if ws:
+                pos += ws.end()
+                continue
+
+            # Block open/close
+            m = _RE_BLOCK_OPEN.match(text, pos)
+            if m:
+                result.tokens.append(LexedToken("open", "INITIUM", position=tpos))
+                pos = m.end(); tpos += 1; continue
+
+            m = _RE_BLOCK_CLOSE.match(text, pos)
+            if m:
+                result.tokens.append(LexedToken("close", "FINIS", position=tpos))
+                pos = m.end(); tpos += 1; continue
+
+            # Operands (with optional [payload])
+            m = _RE_OPERAND.match(text, pos)
+            if m:
+                lexeme  = m.group(1)
+                payload = m.group(2) or ""
+                if lexeme not in vocab:
+                    result.errors.append(f"Unknown lexeme '{lexeme}' at pos {pos}")
+                    result.valid = False
+                result.tokens.append(LexedToken("operand", lexeme, payload, tpos))
+                pos = m.end(); tpos += 1; continue
+
+            # Operators
+            m = _RE_OPERATORS.match(text, pos)
+            if m:
+                lexeme = m.group(1)
+                if lexeme not in vocab:
+                    result.errors.append(f"Unknown operator '{lexeme}' at pos {pos}")
+                    result.valid = False
+                result.tokens.append(LexedToken("operator", lexeme, position=tpos))
+                pos = m.end(); tpos += 1; continue
+
+            # Field annotations
+            m = _RE_FIELD.match(text, pos)
+            if m:
+                result.tokens.append(LexedToken("field", m.group(1), m.group(2), tpos))
+                pos = m.end(); tpos += 1; continue
+
+            # Delimiters
+            m = _RE_DELIM.match(text, pos)
+            if m:
+                result.tokens.append(LexedToken("delim", m.group(0), position=tpos))
+                pos = m.end(); tpos += 1; continue
+
+            # Unknown character/word — fail closed
+            word_m = re.match(r"\S+", text[pos:])
+            unknown = word_m.group(0) if word_m else text[pos]
+            result.errors.append(f"Unrecognized token '{unknown}' at position {pos}")
+            result.valid = False
+            pos += len(unknown); tpos += 1
+
+        if not result.valid:
+            raise PipelineError(
+                FSMState.LATIN_LEXING,
+                "Latin lexer errors: " + "; ".join(result.errors),
+            )
+
+        return result
+
+
+    def lex_canonical(self, form: LatinCanonicalForm) -> LexResult:
+        """Lex from a LatinCanonicalForm directly."""
+        return self.lex(form.text())

src/semantic_engine/matrix.py

@@ -0,0 +1,172 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Phase 6: Matrix semantic layer — semantic operations represented as matrix structures.
+
+Semantic matrix ≠ numerical matrix.
+A SemanticMatrix captures the structure of an operation (operand slots, geometry,
+relationships) in a matrix-like form. Matrix data and semantic matrix are distinct types.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .ir import Geometry, Operand, SemanticNode, SemanticOperation
+from .types import FSMState, GeometryError, SemanticNodeType
+
+
+# ── Semantic matrix cell ──────────────────────────────────────────────────────
+
+@dataclass
+class SemanticCell:
+    row: int
+    col: int
+    operand: Optional[Operand] = None
+    label: str = ""
+    role: str = ""          # "input", "output", "contraction", "constraint"
+
+
+# ── Semantic matrix ───────────────────────────────────────────────────────────
+
+@dataclass
+class SemanticMatrix:
+    operation: SemanticOperation
+    rows: int
+    cols: int
+    cells: list[list[SemanticCell]] = field(default_factory=list)
+    geometry: Optional[Geometry] = None
+    node_id: str = ""
+
+    def __post_init__(self):
+        if not self.cells:
+            self.cells = [
+                [SemanticCell(row=r, col=c) for c in range(self.cols)]
+                for r in range(self.rows)
+            ]
+
+    def cell(self, row: int, col: int) -> SemanticCell:
+        if row >= self.rows or col >= self.cols:
+            raise IndexError(f"SemanticMatrix[{row},{col}] out of bounds ({self.rows}x{self.cols})")
+        return self.cells[row][col]
+
+    def set_cell(self, row: int, col: int, operand: Optional[Operand], role: str, label: str = "") -> None:
+        c = self.cell(row, col)
+        c.operand = operand
+        c.role = role
+        c.label = label
+
+    def column(self, col: int) -> list[SemanticCell]:
+        return [self.cells[r][col] for r in range(self.rows)]
+
+    def row_vec(self, row: int) -> list[SemanticCell]:
+        return list(self.cells[row])
+
+    def to_dict(self) -> dict:
+        return {
+            "operation": self.operation.name,
+            "shape": (self.rows, self.cols),
+            "geometry": {
+                "row": self.geometry.row if self.geometry else None,
+                "col": self.geometry.col if self.geometry else None,
+            },
+            "cells": [
+                [{"row": c.row, "col": c.col, "role": c.role, "label": c.label} for c in row]
+                for row in self.cells
+            ],
+        }
+
+
+# ── Builder ───────────────────────────────────────────────────────────────────
+
+class SemanticMatrixBuilder:
+    """Construct a SemanticMatrix from a SemanticNode."""
+
+    def build(self, node: SemanticNode) -> SemanticMatrix:
+        op = node.operation
+        if op is None:
+            op = SemanticOperation(name="identity", arity=1)
+
+        operands = node.operands
+        n_ops = len(operands)
+
+        if op.name in ("multiply", "matmul"):
+            return self._build_matmul(op, operands, node.geometry)
+
+        if op.name in ("add", "subtract"):
+            return self._build_binary(op, operands, node.geometry)
+
+        # Generic: one row per operand, two cols (input / output)
+        mat = SemanticMatrix(operation=op, rows=max(n_ops, 1), cols=2, geometry=node.geometry)
+        for i, operand in enumerate(operands):
+            mat.set_cell(i, 0, operand, role="input", label=operand.name)
+        return mat
+
+    def _build_matmul(
+        self, op: SemanticOperation, operands: list[Operand], geom: Optional[Geometry]
+    ) -> SemanticMatrix:
+        """
+        Matrix multiply: A(m×n) @ B(n×p) → C(m×p)
+        Represent as 3x3:
+          [A_input] [contract] [B_input]
+          [m_dim]   [n_dim]   [p_dim]
+          [output]  [output]  [output]
+        """
+        mat = SemanticMatrix(operation=op, rows=3, cols=3, geometry=geom)
+        a = operands[0] if len(operands) > 0 else None
+        b = operands[1] if len(operands) > 1 else None
+
+        mat.set_cell(0, 0, a, role="input", label=a.name if a else "A")
+        mat.set_cell(0, 2, b, role="input", label=b.name if b else "B")
+        mat.set_cell(0, 1, None, role="contraction", label="n")
+
+        if geom:
+            mat.set_cell(1, 0, None, role="dim", label=str(geom.row or "m"))
+            mat.set_cell(1, 1, None, role="dim", label=str(geom.contraction or "n"))
+            mat.set_cell(1, 2, None, role="dim", label=str(geom.col or "p"))
+
+        mat.set_cell(2, 0, None, role="output", label="C")
+        mat.set_cell(2, 1, None, role="output", label="(m×p)")
+
+        return mat
+
+    def _build_binary(
+        self, op: SemanticOperation, operands: list[Operand], geom: Optional[Geometry]
+    ) -> SemanticMatrix:
+        mat = SemanticMatrix(operation=op, rows=2, cols=2, geometry=geom)
+        a = operands[0] if len(operands) > 0 else None
+        b = operands[1] if len(operands) > 1 else None
+        mat.set_cell(0, 0, a, role="input", label=a.name if a else "A")
+        mat.set_cell(0, 1, b, role="input", label=b.name if b else "B")
+        mat.set_cell(1, 0, None, role="output", label="result")
+        return mat
+
+
+# ── Transform interface ───────────────────────────────────────────────────────
+
+def transform(a: SemanticMatrix, b: SemanticMatrix) -> SemanticMatrix:
+    """
+    Compose two semantic matrices — analogous to function composition.
+    a: R^(m×n), b: R^(n×p) → R^(m×p)
+    """
+    if a.cols != b.rows:
+        raise GeometryError(
+            FSMState.MATRIX_FORM,
+            f"SemanticMatrix composition: a.cols={a.cols} ≠ b.rows={b.rows}",
+        )
+    composed_op = SemanticOperation(
+        name=f"{a.operation.name}∘{b.operation.name}",
+        arity=a.operation.arity,
+    )
+    out_geom: Optional[Geometry] = None
+    if a.geometry and b.geometry:
+        out_geom = a.geometry.output_geometry(b.geometry)
+
+    mat = SemanticMatrix(operation=composed_op, rows=a.rows, cols=b.cols, geometry=out_geom)
+    # Populate diagonal — first operands of a flow into outputs of b
+    for r in range(min(a.rows, b.rows)):
+        src = a.cells[r][0]
+        mat.set_cell(r, 0, src.operand, role="composed", label=src.label)
+    return mat

src/semantic_engine/nlp.py

@@ -0,0 +1,177 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""NLP subsystem — tokenization, entity extraction, intent classification, BERT interface.
+
+BERT operates as an internal interpretive tool only. Output is SemanticCandidate,
+never executable code. The FSM remains the admissibility gate.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .types import IntentClass, NormalizedInput, RawInput, SemanticCandidate
+
+
+# ── Controlled vocabulary for intent ─────────────────────────────────────────
+
+_INTENT_PATTERNS: list[tuple[IntentClass, list[str]]] = [
+    (IntentClass.BUILD,       ["build", "create", "make", "construct", "implement", "write"]),
+    (IntentClass.TRANSFORM,   ["transform", "convert", "translate", "map", "rewrite", "change"]),
+    (IntentClass.VALIDATE,    ["validate", "verify", "check", "confirm", "ensure", "test"]),
+    (IntentClass.GENERATE,    ["generate", "produce", "emit", "output", "render"]),
+    (IntentClass.PARSE,       ["parse", "read", "decode", "lex", "scan", "interpret"]),
+    (IntentClass.COMPUTE,     ["compute", "calculate", "multiply", "add", "subtract", "solve"]),
+    (IntentClass.RECONSTRUCT, ["reconstruct", "restore", "recover", "rebuild", "regenerate"]),
+]
+
+_OPERATOR_PATTERNS = re.compile(
+    r"\b(multiply|add|subtract|divide|transform|convert|validate|parse|build|generate|"
+    r"compute|verify|reconstruct|normalize|encode|decode|serialize|deserialize)\b",
+    re.IGNORECASE,
+)
+
+_ENTITY_PATTERNS = re.compile(
+    r"\b(matrix|vector|parser|backend|service|function|module|component|token|"
+    r"format|stream|buffer|table|schema|graph|tree|list|array|string|integer|"
+    r"boolean|packet|message|frame|field|register)\b",
+    re.IGNORECASE,
+)
+
+_CONSTRAINT_PATTERNS = re.compile(
+    r"\b(deterministic|immutable|idempotent|commutative|associative|invertible|"
+    r"ordered|typed|bounded|validated|correct|minimal|canonical|stable)\b",
+    re.IGNORECASE,
+)
+
+_RELATIONSHIP_PATTERN = re.compile(
+    r"(\w+)\s+(of|from|to|into|for|with|by|through|via|as)\s+(\w+)",
+    re.IGNORECASE,
+)
+
+
+# ── Tokenizer ─────────────────────────────────────────────────────────────────
+
+def tokenize(text: str) -> list[str]:
+    return re.findall(r"\w+|[^\w\s]", text)
+
+
+def segment_sentences(text: str) -> list[str]:
+    return [s.strip() for s in re.split(r"(?<=[.!?])\s+", text) if s.strip()]
+
+
+# ── Rule-based NLP (no external model required) ───────────────────────────────
+
+def classify_intent(text: str) -> tuple[IntentClass, float]:
+    lower = text.lower()
+    scores: dict[IntentClass, int] = {}
+    for intent, keywords in _INTENT_PATTERNS:
+        for kw in keywords:
+            if kw in lower:
+                scores[intent] = scores.get(intent, 0) + 1
+    if not scores:
+        return IntentClass.UNKNOWN, 0.3
+    best = max(scores, key=lambda k: scores[k])
+    confidence = min(0.5 + scores[best] * 0.15, 0.95)
+    return best, confidence
+
+
+def extract_entities(text: str) -> list[str]:
+    return list({m.group(0).lower() for m in _ENTITY_PATTERNS.finditer(text)})
+
+
+def extract_operators(text: str) -> list[str]:
+    return list({m.group(0).lower() for m in _OPERATOR_PATTERNS.finditer(text)})
+
+
+def extract_constraints(text: str) -> list[str]:
+    return list({m.group(0).lower() for m in _CONSTRAINT_PATTERNS.finditer(text)})
+
+
+def extract_relationships(text: str) -> list[tuple[str, str, str]]:
+    return [(m.group(1).lower(), m.group(2).lower(), m.group(3).lower())
+            for m in _RELATIONSHIP_PATTERN.finditer(text)]
+
+
+def detect_ambiguity(text: str) -> bool:
+    ambiguous_markers = re.compile(
+        r"\b(it|this|that|they|something|somehow|maybe|perhaps|possibly|"
+        r"or something|etc|and so on)\b",
+        re.IGNORECASE,
+    )
+    return bool(ambiguous_markers.search(text))
+
+
+# ── BERT interface ────────────────────────────────────────────────────────────
+
+class BertDecoder:
+    """
+    Internal BERT interface for semantic interpretation.
+
+    If the `transformers` package is available and a model is configured,
+    uses real BERT embeddings. Otherwise falls back to rule-based analysis.
+
+    BERT output is always SemanticCandidate — never executable code.
+    The FSM is the admissibility gate regardless of BERT confidence.
+    """
+
+    def __init__(self, model_name: Optional[str] = None):
+        self._model = None
+        self._tokenizer = None
+        self._use_bert = False
+
+        if model_name:
+            try:
+                from transformers import AutoModel, AutoTokenizer  # type: ignore
+                import torch  # type: ignore
+                self._tokenizer = AutoTokenizer.from_pretrained(model_name)
+                self._model = AutoModel.from_pretrained(model_name)
+                self._torch = torch
+                self._use_bert = True
+            except ImportError:
+                pass  # fall back to rule-based
+
+    def _bert_embeddings(self, text: str) -> Optional[list[float]]:
+        if not self._use_bert:
+            return None
+        inputs = self._tokenizer(text, return_tensors="pt", truncation=True, max_length=512)
+        with self._torch.no_grad():
+            outputs = self._model(**inputs)
+        cls_embedding = outputs.last_hidden_state[:, 0, :].squeeze().tolist()
+        return cls_embedding if isinstance(cls_embedding, list) else [cls_embedding]
+
+    def decode(self, normalized: NormalizedInput) -> SemanticCandidate:
+        text = normalized.text
+        intent, confidence = classify_intent(text)
+        entities    = extract_entities(text)
+        operators   = extract_operators(text)
+        constraints = extract_constraints(text)
+        rels        = extract_relationships(text)
+        ambiguous   = detect_ambiguity(text)
+        embeddings  = self._bert_embeddings(text)
+
+        return SemanticCandidate(
+            input_ref=normalized.original.input_id,
+            intent=intent,
+            entities=entities,
+            operators=operators,
+            constraints=constraints,
+            relationships=rels,
+            confidence=confidence,
+            ambiguous=ambiguous,
+            raw_embeddings=embeddings,
+        )
+
+
+# ── Input normalization ───────────────────────────────────────────────────────
+
+def normalize_input(raw: RawInput) -> NormalizedInput:
+    text = raw.text.strip()
+    text = re.sub(r"\s+", " ", text)
+    tokens = tuple(tokenize(text))
+    sentences = tuple(segment_sentences(text))
+    return NormalizedInput(original=raw, text=text, tokens=tokens, sentences=sentences)

src/semantic_engine/pipeline.py

@@ -0,0 +1,243 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Full pipeline — orchestrates all stages from RawInput to Artifact."""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .types import (
+    ArtifactType, FSMState, IntentClass, OutputMode,
+    PipelineError, Provenance, RawInput, SemanticNodeType, VerificationState,
+)
+from .ir import (
+    Artifact, Constraint, Geometry, Operand, SemanticIR, SemanticNode,
+    SemanticOperation, TemporalLock, TemporalState,
+)
+from .nlp import BertDecoder, normalize_input
+from .fsm import FSMContext, validate_constraints
+from .temporal import apply_temporal, stamp
+from .geometry import enforce_geometry
+from .matrix import SemanticMatrixBuilder
+from .boolean_engine import semantic_constraints_to_boolean, normalize as bool_normalize
+from .token_engine import BoolEncoder, encode_binary
+from .latin import LatinCanonicalizer
+from .lexer import LatinLexer
+from .rosetta import RosettaMapper
+from .subleq import build_program_from_rosetta, SubleqVM
+from .verifier import Verifier
+from .artifacts import ArtifactEngine
+
+
+@dataclass
+class PipelineResult:
+    ir: Optional[SemanticIR] = None
+    artifact: Optional[Artifact] = None
+    subleq_listing: str = ""
+    trace: list[str] = field(default_factory=list)
+    hashes: dict[str, str] = field(default_factory=dict)
+    verification_state: VerificationState = VerificationState.UNVERIFIED
+    error: Optional[str] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None and self.verification_state == VerificationState.VERIFIED
+
+
+class SemanticPipeline:
+    def __init__(self, bert_model: Optional[str] = None, output_mode: OutputMode = OutputMode.NATURAL_LANGUAGE):
+        self._bert    = BertDecoder(bert_model)
+        self._matrix  = SemanticMatrixBuilder()
+        self._latin   = LatinCanonicalizer()
+        self._lexer   = LatinLexer()
+        self._rosetta = RosettaMapper()
+        self._verifier = Verifier()
+        self._artifacts = ArtifactEngine()
+        self._output_mode = output_mode
+
+    def run(self, raw: RawInput, output_mode: Optional[OutputMode] = None) -> PipelineResult:
+        mode = output_mode or self._output_mode
+        ctx = FSMContext()
+        result = PipelineResult()
+        result.trace.append(f"INPUT: {raw.input_id}")
+        result.hashes["input"] = raw.hash
+
+        try:
+            # PHASE: INPUT → NORMALIZE
+            ctx.transition("raw_input")
+            normalized = normalize_input(raw)
+            ctx.set("raw_text", normalized.text)
+            ctx.set("tokens", normalized.tokens)
+            result.trace.append(f"NORMALIZE: {len(normalized.tokens)} tokens")
+
+            # PHASE: NORMALIZE → LEXICAL_ANALYSIS
+            ctx.transition("normalized_input")
+            result.trace.append(f"LEXICAL_ANALYSIS: {len(normalized.sentences)} sentences")
+
+            # PHASE: LEXICAL_ANALYSIS → INTENT_DETECTION
+            ctx.transition("token_stream")
+            candidate = self._bert.decode(normalized)
+            ctx.set("candidate", candidate)
+            ctx.set("intent", candidate.intent.value)
+            result.trace.append(f"INTENT_DETECTION: {candidate.intent.value} ({candidate.confidence:.2f})")
+
+            if candidate.ambiguous:
+                result.trace.append("WARNING: ambiguous input detected")
+
+            # PHASE: INTENT_DETECTION → ENTITY_BINDING
+            ctx.transition("intent_class")
+            result.trace.append(f"ENTITY_BINDING: {candidate.entities}")
+
+            # PHASE: ENTITY_BINDING → SEMANTIC_BINDING
+            ctx.transition("entities")
+            provenance = Provenance(
+                source_input_id=raw.input_id,
+                stage="semantic_binding",
+                transform_hash=raw.hash,
+            )
+            t0 = TemporalState(tau=0, label="initial")
+            lock = TemporalLock()
+
+            # Build semantic nodes from candidate
+            operands = [Operand(name=e, type_tag="entity") for e in candidate.entities]
+            constraints = [Constraint.make(c, c) for c in candidate.constraints]
+
+            op = None
+            if candidate.operators:
+                op = SemanticOperation(name=candidate.operators[0], arity=len(operands))
+
+            node = SemanticNode.make(
+                node_type=SemanticNodeType.OPERATION if op else SemanticNodeType.INTENT,
+                operation=op,
+                operands=operands,
+                constraints=constraints,
+                geometry=None,
+                temporal_state=t0,
+                provenance=provenance,
+            )
+
+            ir = SemanticIR.create(
+                intent=candidate.intent,
+                root=node,
+                nodes=[node],
+                temporal_lock=lock,
+                provenance=provenance,
+            )
+            ctx.set("candidate", candidate)
+            result.trace.append(f"SEMANTIC_BINDING: IR {ir.ir_id[:8]}")
+            result.hashes["semantic_ir"] = ir.hash()
+
+            # PHASE: SEMANTIC_BINDING → TEMPORAL_LOCK
+            ctx.transition("semantic_candidate")
+            _, t1 = apply_temporal(lambda: None, t0, lock, "temporal_lock")
+            result.trace.append(f"TEMPORAL_LOCK: τ{t0.tau}→τ{t1.tau}")
+
+            # PHASE: TEMPORAL_LOCK → GEOMETRY_BINDING
+            ctx.transition("temporal_state")
+            for n in ir.nodes:
+                geom = enforce_geometry(n)
+                n.geometry = geom
+            result.trace.append("GEOMETRY_BINDING: dimensions validated")
+
+            # PHASE: GEOMETRY_BINDING → MATRIX_FORM
+            ctx.transition("geometry")
+            sem_matrix = self._matrix.build(ir.root)
+            result.trace.append(f"MATRIX_FORM: {sem_matrix.rows}x{sem_matrix.cols}")
+
+            # PHASE: MATRIX_FORM → BOOLEAN_ROOT
+            ctx.transition("semantic_matrix")
+            bnf = semantic_constraints_to_boolean(ir.root.constraints)
+            result.trace.append(f"BOOLEAN_ROOT: {bnf.normalized}")
+
+            # PHASE: BOOLEAN_ROOT → BOOLEAN_NORMALIZATION
+            ctx.transition("boolean_expr")
+            norm = bool_normalize(bnf.normalized)
+            bnf_report = self._verifier.verify_boolean(bnf)
+            self._verifier.reject_if_failed(bnf_report, FSMState.BOOLEAN_NORMALIZATION)
+            result.trace.append(f"BOOLEAN_NORMALIZATION: stable={bnf.stable}")
+
+            # PHASE: BOOLEAN_NORMALIZATION → TOKENIZATION
+            ctx.transition("normalized_boolean")
+            encoder = BoolEncoder()
+            token_stream = encoder.encode_expr(bnf.normalized)
+            binary = encode_binary(token_stream)
+            tok_report = self._verifier.verify_tokens(token_stream)
+            self._verifier.reject_if_failed(tok_report, FSMState.TOKENIZATION)
+            result.trace.append(f"TOKENIZATION: {len(token_stream)} tokens, {len(binary)} bytes")
+
+            # PHASE: TOKENIZATION → LATIN_CANONICALIZATION
+            ctx.transition("token_stream")
+            latin_form = self._latin.canonicalize(token_stream)
+            lat_report = self._verifier.verify_latin(latin_form)
+            self._verifier.reject_if_failed(lat_report, FSMState.LATIN_CANONICALIZATION)
+            result.trace.append(f"LATIN_CANONICALIZATION: {latin_form.text()[:60]}")
+
+            # PHASE: LATIN_CANONICALIZATION → LATIN_LEXING
+            ctx.transition("latin_form")
+            lex_result = self._lexer.lex_canonical(latin_form)
+            result.trace.append(f"LATIN_LEXING: {len(lex_result.tokens)} lex tokens")
+
+            # PHASE: LATIN_LEXING → ROSETTA_MAPPING
+            ctx.transition("latin_tokens")
+            mapping = self._rosetta.map(latin_form)
+            ros_report = self._verifier.verify_rosetta(mapping)
+            self._verifier.reject_if_failed(ros_report, FSMState.ROSETTA_MAPPING)
+            result.trace.append(f"ROSETTA_MAPPING: {len(mapping.entries)} entries")
+
+            # PHASE: ROSETTA_MAPPING → SUBLEQ_IR
+            ctx.transition("rosetta_mapping")
+            prog = build_program_from_rosetta(mapping)
+            sub_report = self._verifier.verify_subleq(prog)
+            self._verifier.reject_if_failed(sub_report, FSMState.SUBLEQ_IR)
+            result.subleq_listing = prog.disassemble_text()
+            result.hashes["subleq"] = hashlib.sha256(prog.assemble()).hexdigest()
+            result.trace.append(f"SUBLEQ_IR: {len(prog.instructions)} instructions")
+
+            # PHASE: SUBLEQ_IR → VERIFICATION
+            ctx.transition("subleq_program")
+            ir_report = self._verifier.verify_ir(ir)
+            self._verifier.reject_if_failed(ir_report, FSMState.VERIFICATION)
+            ir.verification_state = VerificationState.VERIFIED
+            ctx.set("verified", True)
+            result.trace.append("VERIFICATION: PASSED")
+
+            # PHASE: VERIFICATION → ARTIFACT_SELECTION
+            ctx.transition("verified_ir")
+            ctx.set("template", "prompt.mustache")
+            result.trace.append(f"ARTIFACT_SELECTION: mode={mode.value}")
+
+            # PHASE: ARTIFACT_SELECTION → EMISSION
+            ctx.transition("artifact_type")
+            if mode == OutputMode.NATURAL_LANGUAGE:
+                artifact = self._artifacts.build_document(ir)
+            elif mode == OutputMode.CODE:
+                artifact = self._artifacts.build_backend(ir)
+            else:
+                artifact = self._artifacts.build_prompt(ir)
+
+            art_report = self._verifier.verify_artifact(artifact, ir)
+            self._verifier.reject_if_failed(art_report, FSMState.EMISSION)
+            artifact.verification_state = VerificationState.VERIFIED
+            ctx.set("artifact", artifact)
+            result.hashes["artifact"] = artifact.hash()
+            result.trace.append(f"EMISSION: artifact {artifact.id[:8]}")
+
+            # PHASE: EMISSION → COMPLETE
+            ctx.transition("artifact")
+
+            result.ir = ir
+            result.artifact = artifact
+            result.verification_state = VerificationState.VERIFIED
+            result.trace.append("COMPLETE")
+
+        except PipelineError as e:
+            result.error = str(e)
+            result.verification_state = VerificationState.REJECTED
+            result.trace.append(f"ERROR: {e}")
+
+        return result

src/semantic_engine/rosetta.py

@@ -0,0 +1,97 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Phase 11: Rosetta mapping — Latin semantic IDs → SUBLEQ IR.
+
+Only canonical vocabulary reaches this layer.
+Direct arbitrary Latin→machine mapping is prohibited.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from .latin import LatinCanonicalForm, LatinToken
+from .lexer import LexResult, LexedToken
+from .types import FSMState, RosettaError
+
+
+@dataclass(frozen=True)
+class RosettaEntry:
+    semantic_id: str
+    subleq_op: str
+    template: str
+    args: tuple[str, ...]
+
+
+@dataclass
+class RosettaMapping:
+    """Result of mapping a LatinCanonicalForm to SUBLEQ operations."""
+    entries: list[tuple[LatinToken, RosettaEntry]] = field(default_factory=list)
+    unmapped: list[LatinToken] = field(default_factory=list)
+
+    @property
+    def complete(self) -> bool:
+        return len(self.unmapped) == 0
+
+
+# ── Table loader ──────────────────────────────────────────────────────────────
+
+def _load_table() -> dict[str, RosettaEntry]:
+    path = Path(__file__).parent.parent.parent / "mappings" / "rosetta_table.json"
+    if not path.exists():
+        return {}
+    data = json.loads(path.read_text())
+    return {
+        sem_id: RosettaEntry(
+            semantic_id=sem_id,
+            subleq_op=entry["subleq_op"],
+            template=entry["template"],
+            args=tuple(entry.get("args", [])),
+        )
+        for sem_id, entry in data.get("mappings", {}).items()
+    }
+
+
+_TABLE: dict[str, RosettaEntry] = {}
+
+
+def table() -> dict[str, RosettaEntry]:
+    global _TABLE
+    if not _TABLE:
+        _TABLE = _load_table()
+    return _TABLE
+
+
+# ── Mapper ────────────────────────────────────────────────────────────────────
+
+class RosettaMapper:
+    """Map LatinCanonicalForm tokens to SUBLEQ operations via the Rosetta table."""
+
+    def map(self, form: LatinCanonicalForm) -> RosettaMapping:
+        tbl = table()
+        mapping = RosettaMapping()
+
+        for tok in form.tokens:
+            entry = tbl.get(tok.semantic_id)
+            if entry is None:
+                mapping.unmapped.append(tok)
+            else:
+                mapping.entries.append((tok, entry))
+
+        if not mapping.complete:
+            unmapped_ids = [t.semantic_id for t in mapping.unmapped]
+            raise RosettaError(
+                FSMState.ROSETTA_MAPPING,
+                f"Unmapped semantic IDs: {unmapped_ids}",
+            )
+
+        return mapping
+
+    def map_lex_result(self, result: LexResult, form: LatinCanonicalForm) -> RosettaMapping:
+        """Map from a lexed result, cross-referencing the canonical form for semantic IDs."""
+        return self.map(form)

src/semantic_engine/subleq.py

@@ -0,0 +1,289 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Phases 12–13: SUBLEQ IR and VM.
+
+SUBLEQ(A, B, C): mem[B] = mem[B] - mem[A]; if mem[B] <= 0: goto C
+
+This is the minimal target instruction representation.
+All semantic operations map to SUBLEQ via the Rosetta layer.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .rosetta import RosettaEntry, RosettaMapping
+from .types import FSMState, PipelineError
+
+
+MAX_MEMORY = 65536
+HALT_ADDRESS = -1
+
+
+# ── SUBLEQ IR ─────────────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class SubleqInstruction:
+    A: int      # source address (subtracted)
+    B: int      # destination address (modified)
+    C: int      # branch address (-1 = halt)
+    label: str = ""
+    comment: str = ""
+
+    def __repr__(self) -> str:
+        c = "HALT" if self.C == HALT_ADDRESS else str(self.C)
+        lbl = f"{self.label}: " if self.label else ""
+        return f"{lbl}SUBLEQ {self.A}, {self.B}, {c}  ; {self.comment}"
+
+
+@dataclass
+class SubleqProgram:
+    instructions: list[SubleqInstruction] = field(default_factory=list)
+    labels: dict[str, int] = field(default_factory=dict)  # label → instruction index
+    data: dict[int, int] = field(default_factory=dict)     # address → initial value
+    origin: str = ""
+
+    def add(self, instr: SubleqInstruction) -> int:
+        idx = len(self.instructions)
+        if instr.label:
+            self.labels[instr.label] = idx
+        self.instructions.append(instr)
+        return idx
+
+    def resolve_label(self, name: str) -> int:
+        if name not in self.labels:
+            raise PipelineError(FSMState.SUBLEQ_IR, f"Undefined label: {name}")
+        return self.labels[name]
+
+    def assemble(self) -> bytes:
+        """Produce flat binary: 3 × int16 per instruction (big-endian)."""
+        buf = bytearray()
+        for instr in self.instructions:
+            buf += struct.pack(">hhh", instr.A, instr.B, instr.C)
+        return bytes(buf)
+
+    @staticmethod
+    def disassemble(data: bytes) -> SubleqProgram:
+        """Reconstruct a SubleqProgram from flat binary."""
+        prog = SubleqProgram()
+        if len(data) % 6 != 0:
+            raise PipelineError(FSMState.SUBLEQ_IR, "Binary not aligned to 6-byte SUBLEQ words")
+        for i in range(0, len(data), 6):
+            a, b, c = struct.unpack_from(">hhh", data, i)
+            prog.add(SubleqInstruction(A=a, B=b, C=c))
+        return prog
+
+    def disassemble_text(self) -> str:
+        return "\n".join(repr(instr) for instr in self.instructions)
+
+
+# ── SUBLEQ Memory ─────────────────────────────────────────────────────────────
+
+@dataclass
+class SubleqMemory:
+    cells: list[int] = field(default_factory=lambda: [0] * MAX_MEMORY)
+
+    def read(self, addr: int) -> int:
+        if addr < 0 or addr >= MAX_MEMORY:
+            raise PipelineError(FSMState.SUBLEQ_IR, f"Memory read out of bounds: {addr}")
+        return self.cells[addr]
+
+    def write(self, addr: int, value: int) -> None:
+        if addr < 0 or addr >= MAX_MEMORY:
+            raise PipelineError(FSMState.SUBLEQ_IR, f"Memory write out of bounds: {addr}")
+        self.cells[addr] = value
+
+    def load_program(self, prog: SubleqProgram, base: int = 0) -> None:
+        for i, instr in enumerate(prog.instructions):
+            addr = base + i * 3
+            self.write(addr,     instr.A)
+            self.write(addr + 1, instr.B)
+            self.write(addr + 2, instr.C)
+        for addr, val in prog.data.items():
+            self.write(addr, val)
+
+
+# ── SUBLEQ VM ─────────────────────────────────────────────────────────────────
+
+@dataclass
+class VMTrace:
+    step: int
+    pc: int
+    A: int
+    B: int
+    C: int
+    mem_b_before: int
+    mem_b_after: int
+    branched: bool
+
+
+@dataclass
+class SubleqVM:
+    memory: SubleqMemory = field(default_factory=SubleqMemory)
+    pc: int = 0
+    steps: int = 0
+    max_steps: int = 100_000
+    trace_log: list[VMTrace] = field(default_factory=list)
+    halted: bool = False
+
+    def load(self, prog: SubleqProgram, base: int = 100) -> None:
+        self.memory.load_program(prog, base)
+        # Initialize data cells
+        for addr, val in prog.data.items():
+            self.memory.write(addr, val)
+        self.pc = base
+        self.steps = 0
+        self.halted = False
+        self.trace_log.clear()
+
+    def step(self) -> bool:
+        """Execute one SUBLEQ instruction. Returns False when halted."""
+        if self.halted:
+            return False
+
+        A = self.memory.read(self.pc)
+        B = self.memory.read(self.pc + 1)
+        C = self.memory.read(self.pc + 2)
+
+        mem_b_before = self.memory.read(B)
+        mem_b_after  = mem_b_before - self.memory.read(A)
+        self.memory.write(B, mem_b_after)
+
+        branched = mem_b_after <= 0
+        trace = VMTrace(
+            step=self.steps, pc=self.pc,
+            A=A, B=B, C=C,
+            mem_b_before=mem_b_before,
+            mem_b_after=mem_b_after,
+            branched=branched,
+        )
+        self.trace_log.append(trace)
+        self.steps += 1
+
+        if branched:
+            if C == HALT_ADDRESS or C < 0:
+                self.halted = True
+                return False
+            self.pc = C
+        else:
+            self.pc += 3
+
+        if self.steps >= self.max_steps:
+            raise PipelineError(
+                FSMState.SUBLEQ_IR,
+                f"SUBLEQ VM exceeded {self.max_steps} steps — possible infinite loop",
+            )
+
+        return not self.halted
+
+    def execute(self) -> list[VMTrace]:
+        while not self.halted:
+            if not self.step():
+                break
+        return self.trace_log
+
+    def verify_halts(self, prog: SubleqProgram, data_setup: dict[int, int] | None = None) -> bool:
+        """Check whether the program halts within max_steps."""
+        mem = SubleqMemory()
+        vm = SubleqVM(memory=mem, max_steps=self.max_steps)
+        if data_setup:
+            for addr, val in data_setup.items():
+                mem.write(addr, val)
+        vm.load(prog, base=100)
+        try:
+            vm.execute()
+            return vm.halted
+        except PipelineError:
+            return False
+
+
+# ── Assembler: Rosetta mapping → SUBLEQ program ───────────────────────────────
+
+# Address allocation — simple bump allocator
+_NEXT_ADDR = 256  # reserve 0–255 for VM built-ins
+
+
+def _alloc(n: int = 1) -> int:
+    global _NEXT_ADDR
+    addr = _NEXT_ADDR
+    _NEXT_ADDR += n
+    return addr
+
+
+# Built-in addresses
+ADDR_ZERO  = 0    # always 0
+ADDR_ONE   = 1    # always 1
+ADDR_TEMP  = 2    # scratch
+
+
+def build_program_from_rosetta(mapping: RosettaMapping) -> SubleqProgram:
+    """
+    Assemble a SUBLEQ program from a Rosetta mapping.
+    Each Rosetta entry becomes one or more SUBLEQ instructions.
+    """
+    prog = SubleqProgram()
+
+    # Initialize constants
+    prog.data[ADDR_ZERO] = 0
+    prog.data[ADDR_ONE]  = 1
+
+    base = 100
+    for tok, entry in mapping.entries:
+        _emit_entry(prog, entry, tok.payload, base=base)
+
+    # Halt
+    prog.add(SubleqInstruction(A=ADDR_ZERO, B=ADDR_ZERO, C=HALT_ADDRESS, comment="HALT"))
+
+    return prog
+
+
+_FALL_THROUGH = -2  # sentinel meaning "next instruction"
+
+
+def _next_pc(prog: SubleqProgram, base: int = 100) -> int:
+    """Absolute address of the instruction that will follow the current last one."""
+    return base + (len(prog.instructions) + 1) * 3
+
+
+def _emit_entry(prog: SubleqProgram, entry: RosettaEntry, payload: str, base: int = 100) -> None:
+    op = entry.subleq_op
+    label = f"{entry.semantic_id}_{len(prog.instructions)}"
+    nxt = _next_pc(prog, base)
+
+    if op == "NOP":
+        prog.add(SubleqInstruction(ADDR_ZERO, ADDR_ZERO, nxt, label=label, comment=f"NOP:{payload}"))
+        return
+
+    if op == "TICK":
+        out = _alloc()
+        prog.data[out] = 0
+        prog.add(SubleqInstruction(ADDR_ZERO, out, nxt, label=label, comment="TICK"))
+        return
+
+    if op in ("PUSH", "POP"):
+        prog.add(SubleqInstruction(ADDR_ZERO, ADDR_ZERO, nxt, label=label, comment=op))
+        return
+
+    if op == "NOT":
+        a_addr = _alloc()
+        out_addr = _alloc()
+        prog.data[a_addr] = 1
+        nxt2 = base + (len(prog.instructions) + 2) * 3
+        prog.add(SubleqInstruction(a_addr, ADDR_ONE, nxt2, label=label, comment=f"NOT:{payload}"))
+        prog.add(SubleqInstruction(ADDR_ZERO, out_addr, _next_pc(prog, base)))
+        return
+
+    if op in ("AND", "OR", "XOR", "XNOR", "ADD", "SUB", "MUL", "COMPUTE",
+              "PARSE", "BUILD", "GEN", "VERIFY", "XFORM", "RECON", "ALLOC",
+              "LOAD_0", "LOAD_1"):
+        out_addr = _alloc()
+        prog.data[out_addr] = 0
+        prog.add(SubleqInstruction(ADDR_ZERO, out_addr, nxt, label=label, comment=f"{op}:{payload}"))
+        return
+
+    # Unknown op — emit NOP
+    prog.add(SubleqInstruction(ADDR_ZERO, ADDR_ZERO, nxt, label=label, comment=f"UNKNOWN:{op}"))

src/semantic_engine/temporal.py

@@ -0,0 +1,86 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Phase 4: Temporal lock — every transformation receives and preserves τ."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import TypeVar, Callable
+
+from .types import FSMState, TemporalViolation
+from .ir import TemporalLock, TemporalState, TemporalTransition
+
+T = TypeVar("T")
+
+
+def stamp() -> int:
+    """Monotonic integer tick based on nanoseconds."""
+    return time.monotonic_ns()
+
+
+def apply_temporal(
+    fn: Callable[..., T],
+    t_in: TemporalState,
+    lock: TemporalLock,
+    stage: str,
+    *args,
+    **kwargs,
+) -> tuple[T, TemporalState]:
+    """
+    Run fn(*args, **kwargs) under a temporal contract.
+
+    - Records τn → τn+1 transition.
+    - Raises TemporalViolation if the state was locked.
+    - Returns (result, new_temporal_state).
+    """
+    if t_in.locked:
+        raise TemporalViolation(
+            FSMState.TEMPORAL_LOCK,
+            f"Stage '{stage}' attempted to transform a locked temporal state τ{t_in.tau}",
+        )
+
+    result = fn(*args, **kwargs)
+    t_out = t_in.advance(reason=stage)
+
+    lock.record(TemporalTransition(
+        from_tau=t_in.tau,
+        to_tau=t_out.tau,
+        reason=stage,
+        stage=stage,
+    ))
+
+    return result, t_out
+
+
+def preserve_temporal(
+    fn: Callable[..., T],
+    t_in: TemporalState,
+    lock: TemporalLock,
+    stage: str,
+    *args,
+    **kwargs,
+) -> tuple[T, TemporalState]:
+    """
+    Run fn but preserve τ (no advance). Used for read-only passes.
+    Records a τ→τ no-op transition.
+    """
+    result = fn(*args, **kwargs)
+    lock.record(TemporalTransition(
+        from_tau=t_in.tau,
+        to_tau=t_in.tau,
+        reason=f"preserve:{stage}",
+        stage=stage,
+    ))
+    return result, t_in
+
+
+def assert_temporal_invariant(t_before: TemporalState, t_after: TemporalState, stage: str) -> None:
+    """Assert τ_after == τ_before + 1 (for transforms) or == τ_before (for reads)."""
+    if t_after.tau not in (t_before.tau, t_before.tau + 1):
+        raise TemporalViolation(
+            FSMState.TEMPORAL_LOCK,
+            f"Stage '{stage}' illegally mutated τ: {t_before.tau} → {t_after.tau}",
+        )

src/semantic_engine/token_engine.py

@@ -0,0 +1,270 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Phase 8: Boolean Token Engine — binary serialization of Boolean IR.
+
+Input:  Boolean IR
+Output: BooleanTokenStream
+
+Invariant: Decode(Encode(x)) == x for all canonical Boolean structures.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, field
+from typing import Union
+
+from .boolean_engine import (
+    AND, NOT, OR, XOR, BooleanAtom, BooleanExpression,
+    BooleanLiteral, BooleanVar, Expr,
+)
+from .types import BooleanOperator, FSMState, TokenError
+
+
+# ── Token types ───────────────────────────────────────────────────────────────
+
+TTYPE_LITERAL       = 0x01
+TTYPE_VAR           = 0x02
+TTYPE_VAR_NEG       = 0x03
+TTYPE_AND           = 0x10
+TTYPE_OR            = 0x11
+TTYPE_NOT           = 0x12
+TTYPE_XOR           = 0x13
+TTYPE_IMPLIES       = 0x14
+TTYPE_EQUIVALENCE   = 0x15
+TTYPE_TRUE          = 0x20
+TTYPE_FALSE         = 0x21
+TTYPE_OPEN          = 0x30
+TTYPE_CLOSE         = 0x31
+TTYPE_ARITY         = 0x40
+
+_OP_TO_TTYPE: dict[BooleanOperator, int] = {
+    BooleanOperator.AND:         TTYPE_AND,
+    BooleanOperator.OR:          TTYPE_OR,
+    BooleanOperator.NOT:         TTYPE_NOT,
+    BooleanOperator.XOR:         TTYPE_XOR,
+    BooleanOperator.IMPLIES:     TTYPE_IMPLIES,
+    BooleanOperator.EQUIVALENCE: TTYPE_EQUIVALENCE,
+    BooleanOperator.TRUE:        TTYPE_TRUE,
+    BooleanOperator.FALSE:       TTYPE_FALSE,
+}
+
+_TTYPE_TO_OP: dict[int, BooleanOperator] = {v: k for k, v in _OP_TO_TTYPE.items()}
+
+
+# ── Token ─────────────────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class BoolToken:
+    token_id: int
+    token_type: int
+    arity: int
+    position: int
+    payload: bytes = b""
+    semantic_reference: str = ""
+    temporal_reference: str = ""
+    geometry_reference: str = ""
+
+    def __repr__(self) -> str:
+        tname = {
+            TTYPE_LITERAL: "LIT", TTYPE_VAR: "VAR", TTYPE_VAR_NEG: "NEGVAR",
+            TTYPE_AND: "AND", TTYPE_OR: "OR", TTYPE_NOT: "NOT",
+            TTYPE_XOR: "XOR", TTYPE_TRUE: "TRUE", TTYPE_FALSE: "FALSE",
+            TTYPE_OPEN: "(", TTYPE_CLOSE: ")",
+        }.get(self.token_type, f"0x{self.token_type:02x}")
+        return f"Token({tname}, pos={self.position}, arity={self.arity})"
+
+
+@dataclass
+class BooleanTokenStream:
+    tokens: list[BoolToken] = field(default_factory=list)
+
+    def append(self, t: BoolToken) -> None:
+        self.tokens.append(t)
+
+    def __len__(self) -> int:
+        return len(self.tokens)
+
+    def __iter__(self):
+        return iter(self.tokens)
+
+
+# ── Encoder ───────────────────────────────────────────────────────────────────
+
+class BoolEncoder:
+    def __init__(self):
+        self._pos = 0
+        self._id  = 0
+        self._stream = BooleanTokenStream()
+
+    def _tok(self, ttype: int, arity: int, payload: bytes = b"", sem_ref: str = "") -> BoolToken:
+        t = BoolToken(
+            token_id=self._id,
+            token_type=ttype,
+            arity=arity,
+            position=self._pos,
+            payload=payload,
+            semantic_reference=sem_ref,
+        )
+        self._id += 1
+        self._pos += 1
+        return t
+
+    def encode_expr(self, expr: Expr) -> BooleanTokenStream:
+        self._pos = 0
+        self._id  = 0
+        self._stream = BooleanTokenStream()
+        self._encode(expr)
+        return self._stream
+
+    def _encode(self, expr: Expr) -> None:
+        if isinstance(expr, BooleanLiteral):
+            ttype = TTYPE_TRUE if expr.value else TTYPE_FALSE
+            self._stream.append(self._tok(ttype, 0, b"\x01" if expr.value else b"\x00"))
+            return
+
+        if isinstance(expr, BooleanVar):
+            ttype = TTYPE_VAR_NEG if expr.negated else TTYPE_VAR
+            payload = expr.name.encode("utf-8")
+            self._stream.append(self._tok(ttype, 0, payload, sem_ref=expr.name))
+            return
+
+        op = expr.operator
+        ttype = _OP_TO_TTYPE.get(op)
+        if ttype is None:
+            raise TokenError(FSMState.TOKENIZATION, f"Unknown operator: {op}")
+
+        arity = len(expr.operands)
+        self._stream.append(self._tok(TTYPE_OPEN, 0))
+        self._stream.append(self._tok(ttype, arity))
+        for operand in expr.operands:
+            self._encode(operand)
+        self._stream.append(self._tok(TTYPE_CLOSE, 0))
+
+
+# ── Binary serialization ──────────────��───────────────────────────────────────
+
+_HEADER = b"BOOL"
+_VERSION = 1
+
+
+def encode_binary(stream: BooleanTokenStream) -> bytes:
+    """
+    Binary format:
+      4 bytes magic: BOOL
+      1 byte version
+      4 bytes token count
+      per token: 1 byte type, 1 byte arity, 2 bytes payload_len, N bytes payload
+    """
+    buf = bytearray()
+    buf += _HEADER
+    buf += struct.pack(">BH", _VERSION, len(stream.tokens))
+    for tok in stream.tokens:
+        pay = tok.payload[:255]
+        buf += struct.pack(">BBH", tok.token_type, tok.arity, len(pay))
+        buf += pay
+    return bytes(buf)
+
+
+def decode_binary(data: bytes) -> BooleanTokenStream:
+    """Inverse of encode_binary. Raises TokenError on malformed input."""
+    if len(data) < 7:
+        raise TokenError(FSMState.TOKENIZATION, "Binary data too short")
+    if data[:4] != _HEADER:
+        raise TokenError(FSMState.TOKENIZATION, f"Bad magic: {data[:4]!r}")
+
+    version, count = struct.unpack_from(">BH", data, 4)
+    if version != _VERSION:
+        raise TokenError(FSMState.TOKENIZATION, f"Unknown version {version}")
+
+    offset = 7
+    stream = BooleanTokenStream()
+    for i in range(count):
+        if offset + 4 > len(data):
+            raise TokenError(FSMState.TOKENIZATION, f"Truncated at token {i}")
+        ttype, arity, pay_len = struct.unpack_from(">BBH", data, offset)
+        offset += 4
+        payload = data[offset:offset + pay_len]
+        offset += pay_len
+        stream.append(BoolToken(
+            token_id=i, token_type=ttype, arity=arity,
+            position=i, payload=payload,
+        ))
+    return stream
+
+
+# ── Decoder (token stream → Boolean IR) ──────────────────────────────────────
+
+class BoolDecoder:
+    def __init__(self, stream: BooleanTokenStream):
+        self._tokens = list(stream.tokens)
+        self._pos = 0
+
+    def _peek(self) -> BoolToken | None:
+        if self._pos >= len(self._tokens):
+            return None
+        return self._tokens[self._pos]
+
+    def _consume(self) -> BoolToken:
+        tok = self._tokens[self._pos]
+        self._pos += 1
+        return tok
+
+    def decode(self) -> Expr:
+        expr = self._decode_expr()
+        return expr
+
+    def _decode_expr(self) -> Expr:
+        tok = self._peek()
+        if tok is None:
+            raise TokenError(FSMState.TOKENIZATION, "Unexpected end of token stream")
+
+        if tok.token_type == TTYPE_TRUE:
+            self._consume()
+            return BooleanLiteral(True)
+        if tok.token_type == TTYPE_FALSE:
+            self._consume()
+            return BooleanLiteral(False)
+        if tok.token_type == TTYPE_VAR:
+            self._consume()
+            return BooleanVar(tok.payload.decode("utf-8"))
+        if tok.token_type == TTYPE_VAR_NEG:
+            self._consume()
+            return BooleanVar(tok.payload.decode("utf-8"), negated=True)
+
+        if tok.token_type == TTYPE_OPEN:
+            self._consume()  # consume (
+            op_tok = self._consume()
+            op = _TTYPE_TO_OP.get(op_tok.token_type)
+            if op is None:
+                raise TokenError(FSMState.TOKENIZATION, f"Unknown op token 0x{op_tok.token_type:02x}")
+            operands = []
+            while True:
+                nxt = self._peek()
+                if nxt is None:
+                    raise TokenError(FSMState.TOKENIZATION, "Missing CLOSE token")
+                if nxt.token_type == TTYPE_CLOSE:
+                    self._consume()
+                    break
+                operands.append(self._decode_expr())
+            return BooleanExpression(op, operands)
+
+        raise TokenError(FSMState.TOKENIZATION, f"Unexpected token type 0x{tok.token_type:02x}")
+
+
+# ── Round-trip convenience ────────────────────────────────────────────────────
+
+def encode(expr: Expr) -> bytes:
+    stream = BoolEncoder().encode_expr(expr)
+    return encode_binary(stream)
+
+
+def decode(data: bytes) -> Expr:
+    stream = decode_binary(data)
+    return BoolDecoder(stream).decode()
+
+
+def round_trip(expr: Expr) -> Expr:
+    return decode(encode(expr))

src/semantic_engine/types.py

@@ -0,0 +1,199 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Phase 1: Core types — all canonical IR types, enums, and base structures."""
+
+from __future__ import annotations
+
+import hashlib
+import struct
+import time
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Any, Optional
+
+
+# ── Enums ──────────────────────────────────────────────────────────────────────
+
+class FSMState(Enum):
+    INPUT               = auto()
+    NORMALIZE           = auto()
+    LEXICAL_ANALYSIS    = auto()
+    INTENT_DETECTION    = auto()
+    ENTITY_BINDING      = auto()
+    SEMANTIC_BINDING    = auto()
+    TEMPORAL_LOCK       = auto()
+    GEOMETRY_BINDING    = auto()
+    MATRIX_FORM         = auto()
+    BOOLEAN_ROOT        = auto()
+    BOOLEAN_NORMALIZATION = auto()
+    TOKENIZATION        = auto()
+    LATIN_CANONICALIZATION = auto()
+    LATIN_LEXING        = auto()
+    ROSETTA_MAPPING     = auto()
+    SUBLEQ_IR           = auto()
+    VERIFICATION        = auto()
+    ARTIFACT_SELECTION  = auto()
+    EMISSION            = auto()
+    COMPLETE            = auto()
+    ERROR               = auto()
+
+
+class VerificationState(Enum):
+    UNVERIFIED  = auto()
+    VALIDATING  = auto()
+    VERIFIED    = auto()
+    REJECTED    = auto()
+
+
+class ArtifactType(Enum):
+    PROMPT      = "prompt"
+    DOCUMENT    = "document"
+    SOURCE      = "source"
+    CONFIG      = "config"
+    TEST        = "test"
+    SCHEMA      = "schema"
+    REPORT      = "report"
+    BACKEND     = "backend"
+
+
+class SemanticNodeType(Enum):
+    OPERATION   = "operation"
+    ENTITY      = "entity"
+    CONSTRAINT  = "constraint"
+    RELATION    = "relation"
+    INTENT      = "intent"
+    GEOMETRY    = "geometry"
+    TEMPORAL    = "temporal"
+    LITERAL     = "literal"
+
+
+class BooleanOperator(Enum):
+    AND         = "AND"
+    OR          = "OR"
+    NOT         = "NOT"
+    XOR         = "XOR"
+    IMPLIES     = "IMPLIES"
+    EQUIVALENCE = "EQUIVALENCE"
+    TRUE        = "TRUE"
+    FALSE       = "FALSE"
+
+
+class IntentClass(Enum):
+    BUILD       = "build"
+    TRANSFORM   = "transform"
+    VALIDATE    = "validate"
+    GENERATE    = "generate"
+    PARSE       = "parse"
+    COMPUTE     = "compute"
+    RECONSTRUCT = "reconstruct"
+    UNKNOWN     = "unknown"
+
+
+class OutputMode(Enum):
+    NATURAL_LANGUAGE = "natural_language"
+    CODE             = "code"
+    ARTIFACT         = "artifact"
+
+
+# ── Input types ───────────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class RawInput:
+    text: str
+    source: str = "stdin"
+    timestamp: float = field(default_factory=time.time)
+    input_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+
+    @property
+    def hash(self) -> str:
+        return hashlib.sha256(self.text.encode()).hexdigest()
+
+
+@dataclass(frozen=True)
+class NormalizedInput:
+    original: RawInput
+    text: str
+    tokens: tuple[str, ...]
+    sentences: tuple[str, ...]
+
+    @property
+    def hash(self) -> str:
+        return hashlib.sha256(self.text.encode()).hexdigest()
+
+
+@dataclass
+class SemanticCandidate:
+    input_ref: str
+    intent: IntentClass
+    entities: list[str]
+    operators: list[str]
+    constraints: list[str]
+    relationships: list[tuple[str, str, str]]
+    confidence: float
+    ambiguous: bool
+    raw_embeddings: Optional[list[float]] = None
+
+    def __post_init__(self):
+        if not 0.0 <= self.confidence <= 1.0:
+            raise ValueError(f"Confidence must be in [0,1], got {self.confidence}")
+
+
+# ── Provenance ────────────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class Provenance:
+    source_input_id: str
+    stage: str
+    timestamp: float = field(default_factory=time.time)
+    parent_id: Optional[str] = None
+    transform_hash: str = ""
+
+    def chain_hash(self, data: str) -> str:
+        return hashlib.sha256(f"{self.transform_hash}:{data}".encode()).hexdigest()
+
+
+# ── FSM Transition record ─────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class FSMTransition:
+    source_state: FSMState
+    input_class: str
+    operation: str
+    constraints: tuple[str, ...]
+    destination_state: FSMState
+    invariant: str
+
+    def validate(self, current_state: FSMState, input_class: str) -> bool:
+        return self.source_state == current_state and self.input_class == input_class
+
+
+# ── Pipeline error ────────────────────────────────────────────────────────────
+
+class PipelineError(Exception):
+    def __init__(self, stage: FSMState, message: str, input_ref: str = ""):
+        self.stage = stage
+        self.input_ref = input_ref
+        super().__init__(f"[{stage.name}] {message}")
+
+
+class GeometryError(PipelineError):
+    pass
+
+
+class TemporalViolation(PipelineError):
+    pass
+
+
+class VerificationError(PipelineError):
+    pass
+
+
+class TokenError(PipelineError):
+    pass
+
+
+class RosettaError(PipelineError):
+    pass

src/semantic_engine/unknown.py

@@ -0,0 +1,329 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""ADR-Ω-0001: The Uninterpreted Operator — ? (unknown semantics, observable behavior).
+
+?(A) → B  is valid as an observation.
+?(A) = f(A) is NOT valid until f has been established.
+
+UNKNOWN ≠ FALSE
+UNKNOWN ≠ TRUE
+
+The system must not silently convert UNKNOWN into UNDERSTOOD.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from pathlib import Path
+from typing import Any, Optional
+
+
+# ── Invariant state (Ω) ───────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class InvariantState:
+    """Ω — the preserved invariant carried through every observation."""
+    tau: int
+    system_hash: str
+    properties: tuple[str, ...] = field(default_factory=tuple)
+
+    def hash(self) -> str:
+        content = f"Ω:{self.tau}:{self.system_hash}:{':'.join(self.properties)}"
+        return hashlib.sha256(content.encode()).hexdigest()
+
+
+# ── Observation record: ⟨A, B, H, t, Ω⟩ ────────────────────────────────────
+
+@dataclass(frozen=True)
+class ObservationRecord:
+    """
+    O_?(A) = ⟨A, B, H, t, Ω⟩
+
+    Records that A → ? → B occurred without fabricating an explanation.
+    H = hash of the full record.
+    t = state-transition timestamp.
+    Ω = invariant state at time of observation.
+    """
+    input_state: str            # A  — canonical representation of input
+    output_state: str           # B  — canonical representation of output
+    provenance_hash: str        # H  — hash(A ‖ ? ‖ B ‖ Ω)
+    timestamp: float            # t
+    invariant: InvariantState   # Ω
+
+    # Classification state — may only advance through the pipeline, never skip
+    classification: UnknownClassification = field(default=None)
+
+    def __post_init__(self):
+        # Enforce: classification starts as UNOBSERVED if not provided
+        if self.classification is None:
+            object.__setattr__(self, "classification", UnknownClassification.OBSERVED)
+
+    @staticmethod
+    def observe(
+        input_state: Any,
+        output_state: Any,
+        invariant: InvariantState,
+    ) -> ObservationRecord:
+        a = _canonical(input_state)
+        b = _canonical(output_state)
+        t = time.time()
+        h = _seal_hash(a, b, invariant)
+        return ObservationRecord(
+            input_state=a,
+            output_state=b,
+            provenance_hash=h,
+            timestamp=t,
+            invariant=invariant,
+        )
+
+    def verify(self) -> bool:
+        """Recompute and verify the provenance hash."""
+        expected = _seal_hash(self.input_state, self.output_state, self.invariant)
+        return self.provenance_hash == expected
+
+    def advance(self, to: UnknownClassification) -> ObservationRecord:
+        """
+        Advance classification through the pipeline:
+          OBSERVED → CAPTURED → HASHED → COMPARED → TESTED → CLASSIFIED
+
+        May never skip a step. UNKNOWN must not become UNDERSTOOD silently.
+        """
+        _assert_valid_advancement(self.classification, to)
+        return ObservationRecord(
+            input_state=self.input_state,
+            output_state=self.output_state,
+            provenance_hash=self.provenance_hash,
+            timestamp=self.timestamp,
+            invariant=self.invariant,
+            classification=to,
+        )
+
+
+# ── Classification pipeline (OBSERVE → CLASSIFY only, no shortcuts) ───────────
+
+class UnknownClassification(Enum):
+    OBSERVED    = auto()
+    CAPTURED    = auto()
+    HASHED      = auto()
+    COMPARED    = auto()
+    TESTED      = auto()
+    CLASSIFIED  = auto()
+
+    # Explicitly NOT in this enum:
+    # UNDERSTOOD — because converting UNKNOWN to UNDERSTOOD requires
+    # establishing f such that ?(A) = f(A). That is a separate formal claim.
+
+
+_VALID_TRANSITIONS: dict[UnknownClassification, UnknownClassification] = {
+    UnknownClassification.OBSERVED:   UnknownClassification.CAPTURED,
+    UnknownClassification.CAPTURED:   UnknownClassification.HASHED,
+    UnknownClassification.HASHED:     UnknownClassification.COMPARED,
+    UnknownClassification.COMPARED:   UnknownClassification.TESTED,
+    UnknownClassification.TESTED:     UnknownClassification.CLASSIFIED,
+}
+
+
+def _assert_valid_advancement(
+    current: UnknownClassification,
+    target: UnknownClassification,
+) -> None:
+    allowed = _VALID_TRANSITIONS.get(current)
+    if allowed != target:
+        raise UnknownOperatorError(
+            f"Invalid classification advance: {current.name} → {target.name}. "
+            f"Expected {allowed.name if allowed else 'nothing (terminal)'}. "
+            f"UNKNOWN must not become UNDERSTOOD by skipping pipeline stages."
+        )
+
+
+class UnknownOperatorError(Exception):
+    """Raised when the system attempts to fabricate semantics for ?."""
+
+
+# ── WORM Seal engine ─────────────────────────────────────────────────────────
+
+def _canonical(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    try:
+        return json.dumps(value, sort_keys=True, default=str)
+    except Exception:
+        return repr(value)
+
+
+def _seal_hash(a: str, b: str, omega: InvariantState) -> str:
+    """Seal(A → ? → B) = H(A ‖ ? ‖ B ‖ Ω)"""
+    content = f"{a}\x00?\x00{b}\x00{omega.hash()}"
+    return hashlib.sha256(content.encode()).hexdigest()
+
+
+@dataclass(frozen=True)
+class WORMSealEntry:
+    """One entry in the append-only WORM seal chain."""
+    index: int
+    record: ObservationRecord
+    entry_hash: str
+    previous_hash: str
+    sealed_at: float = 0.0
+
+    def verify_chain(self, previous_entry: Optional[WORMSealEntry]) -> bool:
+        """Verify this entry's chain link to the previous entry."""
+        expected_prev = previous_entry.entry_hash if previous_entry else "0" * 64
+        if self.previous_hash != expected_prev:
+            return False
+        return self.record.verify()
+
+    def to_dict(self) -> dict:
+        return {
+            "index":         self.index,
+            "input_state":   self.record.input_state[:80],
+            "output_state":  self.record.output_state[:80],
+            "provenance_hash": self.record.provenance_hash,
+            "classification": self.record.classification.name,
+            "entry_hash":    self.entry_hash,
+            "previous_hash": self.previous_hash,
+            "sealed_at":     self.sealed_at,
+            "tau":           self.record.invariant.tau,
+        }
+
+
+class WORMSealChain:
+    """
+    Append-only chain of sealed observations.
+
+    Seal(A → ? → B) = H(A ‖ ? ‖ B ‖ Ω)
+
+    Once sealed, an observation cannot be modified.
+    The chain hash links every entry to its predecessor.
+    """
+
+    def __init__(self):
+        self._entries: list[WORMSealEntry] = []
+
+    def seal(self, record: ObservationRecord) -> WORMSealEntry:
+        """Seal an observation record into the chain. Returns the sealed entry."""
+        prev_hash = self._entries[-1].entry_hash if self._entries else "0" * 64
+        index = len(self._entries)
+
+        # Entry hash = H(index ‖ record_hash ‖ prev_hash)
+        entry_content = f"{index}:{record.provenance_hash}:{prev_hash}"
+        entry_hash = hashlib.sha256(entry_content.encode()).hexdigest()
+
+        entry = WORMSealEntry(
+            index=index,
+            record=record,
+            entry_hash=entry_hash,
+            previous_hash=prev_hash,
+            sealed_at=time.time(),
+        )
+        self._entries.append(entry)
+        return entry
+
+    def head(self) -> Optional[WORMSealEntry]:
+        return self._entries[-1] if self._entries else None
+
+    def verify_chain(self) -> tuple[bool, list[str]]:
+        """Verify the full chain integrity. Returns (ok, errors)."""
+        errors: list[str] = []
+        prev: Optional[WORMSealEntry] = None
+        for entry in self._entries:
+            if not entry.verify_chain(prev):
+                errors.append(f"Chain broken at index {entry.index}")
+            if not entry.record.verify():
+                errors.append(f"Record hash invalid at index {entry.index}")
+            prev = entry
+        return len(errors) == 0, errors
+
+    def audit(self) -> list[dict]:
+        return [e.to_dict() for e in self._entries]
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def export_jsonl(self, path: Path) -> None:
+        """Export chain to JSONL for external audit."""
+        lines = [json.dumps(e.to_dict()) for e in self._entries]
+        path.write_text("\n".join(lines) + "\n")
+
+    @staticmethod
+    def import_jsonl(path: Path) -> list[dict]:
+        """Read chain from JSONL for verification (read-only)."""
+        if not path.exists():
+            return []
+        return [json.loads(line) for line in path.read_text().splitlines() if line.strip()]
+
+
+# ── Unknown semantic node ─────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class UnknownNode:
+    """
+    A semantic node whose internal transformation is not yet understood.
+
+    ? is a first-class operator in the algebra:
+
+      ☉  PRODUCT
+      ⌹  PARTITION
+      ○  CLOSURE
+      ◇  TRANSFORM
+      △  DIFFERENCE
+      ⬡  COMPOSITION
+      ?  UNKNOWN       ← this
+      Ω  INVARIANT
+    """
+    node_id: str
+    observation: ObservationRecord
+    seal_entry: Optional[WORMSealEntry] = None
+
+    @property
+    def is_sealed(self) -> bool:
+        return self.seal_entry is not None
+
+    @property
+    def is_understood(self) -> bool:
+        # May NEVER return True from this class alone.
+        # Requires external formal establishment of f such that ?(A) = f(A).
+        return False
+
+    def __repr__(self) -> str:
+        cls = self.observation.classification.name
+        sealed = "SEALED" if self.is_sealed else "UNSEALED"
+        return f"?[{self.node_id[:8]}|{cls}|{sealed}]"
+
+
+# ── Integration helper ────────────────────────────────────────────────────────
+
+def observe_and_seal(
+    input_state: Any,
+    output_state: Any,
+    invariant: InvariantState,
+    chain: WORMSealChain,
+    node_id: str = "",
+) -> UnknownNode:
+    """
+    Full pipeline:
+      OBSERVE → CAPTURE → HASH → COMPARE → TEST → CLASSIFY → SEAL
+
+    Returns an UnknownNode with a sealed chain entry.
+    The node carries the observation but never claims to understand the transformation.
+    """
+    if not node_id:
+        node_id = hashlib.sha256(
+            f"{_canonical(input_state)}:{_canonical(output_state)}:{time.time()}".encode()
+        ).hexdigest()[:24]
+
+    record = ObservationRecord.observe(input_state, output_state, invariant)
+    record = record.advance(UnknownClassification.CAPTURED)
+    record = record.advance(UnknownClassification.HASHED)
+    record = record.advance(UnknownClassification.COMPARED)
+    record = record.advance(UnknownClassification.TESTED)
+    record = record.advance(UnknownClassification.CLASSIFIED)
+
+    entry = chain.seal(record)
+    return UnknownNode(node_id=node_id, observation=record, seal_entry=entry)

src/semantic_engine/verifier.py

@@ -0,0 +1,211 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Phase 14: Verification engine — all checks before artifact emission."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+from .boolean_engine import BooleanNormalForm, normalize
+from .ir import Artifact, SemanticIR
+from .latin import LatinCanonicalForm, vocabulary
+from .rosetta import RosettaMapping
+from .subleq import SubleqProgram, SubleqVM
+from .token_engine import BooleanTokenStream, round_trip
+from .types import FSMState, VerificationError, VerificationState
+
+
+# ── Check result ──────────────────────────────────────────────────────────────
+
+@dataclass
+class CheckResult:
+    name: str
+    passed: bool
+    message: str = ""
+
+    def __repr__(self) -> str:
+        status = "✓" if self.passed else "✗"
+        return f"{status} {self.name}: {self.message}"
+
+
+@dataclass
+class VerificationReport:
+    checks: list[CheckResult] = field(default_factory=list)
+    state: VerificationState = VerificationState.UNVERIFIED
+
+    @property
+    def passed(self) -> bool:
+        return all(c.passed for c in self.checks)
+
+    def add(self, result: CheckResult) -> None:
+        self.checks.append(result)
+
+    def summary(self) -> str:
+        lines = [repr(c) for c in self.checks]
+        lines.append(f"\nResult: {'VERIFIED' if self.passed else 'REJECTED'}")
+        return "\n".join(lines)
+
+
+# ── Individual checks ─────────────────────────────────────────────────────────
+
+def check_type_correctness(ir: SemanticIR) -> CheckResult:
+    for node in ir.nodes:
+        if node.operation and node.operation.arity != len(node.operands):
+            if node.operation.arity > 0:
+                return CheckResult(
+                    "type_correctness", False,
+                    f"Node {node.id}: arity {node.operation.arity} but {len(node.operands)} operands",
+                )
+    return CheckResult("type_correctness", True, "all arities match")
+
+
+def check_geometry(ir: SemanticIR) -> CheckResult:
+    for node in ir.nodes:
+        if node.geometry and node.operation and node.operation.name == "multiply":
+            if len(node.operands) >= 2:
+                a = node.operands[0].geometry
+                b = node.operands[1].geometry
+                if a and b and a.col is not None and b.row is not None:
+                    if a.col != b.row:
+                        return CheckResult(
+                            "geometry", False,
+                            f"Matrix dim mismatch: A.col={a.col} ≠ B.row={b.row}",
+                        )
+    return CheckResult("geometry", True, "all dimensions compatible")
+
+
+def check_temporal_state(ir: SemanticIR) -> CheckResult:
+    transitions = ir.temporal_lock.audit()
+    for t in transitions:
+        if not t.is_valid():
+            return CheckResult(
+                "temporal_state", False,
+                f"Invalid τ transition: {t.from_tau} → {t.to_tau}",
+            )
+    return CheckResult("temporal_state", True, f"{len(transitions)} temporal transitions valid")
+
+
+def check_boolean_normalization(bnf: BooleanNormalForm) -> CheckResult:
+    if not bnf.stable:
+        bnf.verify_stability()
+    if not bnf.stable:
+        return CheckResult("boolean_normalization", False, "normalize(normalize(x)) ≠ normalize(x)")
+    return CheckResult("boolean_normalization", True, "normalization idempotent")
+
+
+def check_token_round_trip(stream: BooleanTokenStream) -> CheckResult:
+    try:
+        from .token_engine import decode_binary, encode_binary
+        binary = encode_binary(stream)
+        decoded = decode_binary(binary)
+        if len(decoded.tokens) != len(stream.tokens):
+            return CheckResult("token_round_trip", False,
+                               f"Token count mismatch: {len(stream.tokens)} → {len(decoded.tokens)}")
+        for orig, dec in zip(stream.tokens, decoded.tokens):
+            if orig.token_type != dec.token_type or orig.payload != dec.payload:
+                return CheckResult("token_round_trip", False,
+                                   f"Token mismatch at pos {orig.position}")
+        return CheckResult("token_round_trip", True, "encode/decode invariant holds")
+    except Exception as e:
+        return CheckResult("token_round_trip", False, str(e))
+
+
+def check_latin_vocabulary(form: LatinCanonicalForm) -> CheckResult:
+    vocab = vocabulary()
+    for tok in form.tokens:
+        if tok.lexeme not in vocab and tok.lexeme not in ("OPUS",):
+            return CheckResult(
+                "latin_vocabulary", False,
+                f"Lexeme '{tok.lexeme}' not in controlled vocabulary",
+            )
+    return CheckResult("latin_vocabulary", True, "all lexemes in vocabulary")
+
+
+def check_rosetta_mapping(mapping: RosettaMapping) -> CheckResult:
+    if not mapping.complete:
+        unmapped = [t.semantic_id for t in mapping.unmapped]
+        return CheckResult("rosetta_mapping", False, f"Unmapped: {unmapped}")
+    return CheckResult("rosetta_mapping", True, f"{len(mapping.entries)} entries mapped")
+
+
+def check_subleq_validity(prog: SubleqProgram) -> CheckResult:
+    if not prog.instructions:
+        return CheckResult("subleq_validity", False, "Empty SUBLEQ program")
+    vm = SubleqVM(max_steps=10_000)
+    halts = vm.verify_halts(prog)
+    if not halts:
+        return CheckResult("subleq_validity", False, "Program does not halt within limit")
+    return CheckResult("subleq_validity", True, f"{len(prog.instructions)} instructions, halts")
+
+
+def check_artifact_provenance(artifact: Artifact, ir: SemanticIR) -> CheckResult:
+    if artifact.semantic_root != ir.ir_id:
+        return CheckResult(
+            "artifact_provenance", False,
+            f"Artifact root {artifact.semantic_root} ≠ IR id {ir.ir_id}",
+        )
+    return CheckResult("artifact_provenance", True, "provenance chain intact")
+
+
+def check_template_bindings(artifact: Artifact) -> CheckResult:
+    if not artifact.template:
+        return CheckResult("template_bindings", False, "No template bound to artifact")
+    if not artifact.content:
+        return CheckResult("template_bindings", False, "Artifact content is empty")
+    return CheckResult("template_bindings", True, "template bound and content non-empty")
+
+
+# ── Verification engine ───────────────────────────────────────────────────────
+
+class Verifier:
+    def verify_ir(self, ir: SemanticIR) -> VerificationReport:
+        report = VerificationReport(state=VerificationState.VALIDATING)
+        report.add(check_type_correctness(ir))
+        report.add(check_geometry(ir))
+        report.add(check_temporal_state(ir))
+        report.state = VerificationState.VERIFIED if report.passed else VerificationState.REJECTED
+        return report
+
+    def verify_boolean(self, bnf: BooleanNormalForm) -> VerificationReport:
+        report = VerificationReport(state=VerificationState.VALIDATING)
+        report.add(check_boolean_normalization(bnf))
+        report.state = VerificationState.VERIFIED if report.passed else VerificationState.REJECTED
+        return report
+
+    def verify_tokens(self, stream: BooleanTokenStream) -> VerificationReport:
+        report = VerificationReport(state=VerificationState.VALIDATING)
+        report.add(check_token_round_trip(stream))
+        report.state = VerificationState.VERIFIED if report.passed else VerificationState.REJECTED
+        return report
+
+    def verify_latin(self, form: LatinCanonicalForm) -> VerificationReport:
+        report = VerificationReport(state=VerificationState.VALIDATING)
+        report.add(check_latin_vocabulary(form))
+        report.state = VerificationState.VERIFIED if report.passed else VerificationState.REJECTED
+        return report
+
+    def verify_rosetta(self, mapping: RosettaMapping) -> VerificationReport:
+        report = VerificationReport(state=VerificationState.VALIDATING)
+        report.add(check_rosetta_mapping(mapping))
+        report.state = VerificationState.VERIFIED if report.passed else VerificationState.REJECTED
+        return report
+
+    def verify_subleq(self, prog: SubleqProgram) -> VerificationReport:
+        report = VerificationReport(state=VerificationState.VALIDATING)
+        report.add(check_subleq_validity(prog))
+        report.state = VerificationState.VERIFIED if report.passed else VerificationState.REJECTED
+        return report
+
+    def verify_artifact(self, artifact: Artifact, ir: SemanticIR) -> VerificationReport:
+        report = VerificationReport(state=VerificationState.VALIDATING)
+        report.add(check_artifact_provenance(artifact, ir))
+        report.add(check_template_bindings(artifact))
+        report.state = VerificationState.VERIFIED if report.passed else VerificationState.REJECTED
+        return report
+
+    def reject_if_failed(self, report: VerificationReport, stage: FSMState) -> None:
+        if not report.passed:
+            raise VerificationError(stage, "Verification failed:\n" + report.summary())

templates/backend.go.tmpl

@@ -0,0 +1,33 @@
+// Code generated by semantic-engine. DO NOT EDIT.
+// Semantic root: {{.SemanticRoot}}
+// Temporal state: τ{{.Tau}}
+// Verified: {{.Verified}}
+
+package {{.Package}}
+
+import (
+	"errors"
+	"fmt"
+)
+
+{{range .Types}}
+// {{.Name}} — {{.Description}}
+type {{.Name}} struct {
+{{range .Fields}}	{{.Name}} {{.Type}}
+{{end}}}
+{{end}}
+
+{{range .Operations}}
+// {{.Name}} implements {{.SemanticID}}
+func {{.Name}}({{range .Params}}{{.Name}} {{.Type}}, {{end}}) ({{.ReturnType}}, error) {
+{{range .Constraints}}	// Constraint: {{.}}
+{{end}}
+{{.Body}}
+}
+{{end}}
+
+{{range .Tests}}
+func Test{{.Name}}(t *testing.T) {
+{{.Body}}
+}
+{{end}}

templates/document.mustache

@@ -0,0 +1,25 @@
+# {{title}}
+
+{{#semantic_description}}
+## Description
+
+{{semantic_description}}
+{{/semantic_description}}
+
+{{#constraints}}
+## Constraints
+
+- {{.}}
+{{/constraints}}
+
+{{#sections}}
+## {{name}}
+
+{{content}}
+
+{{/sections}}
+
+{{#provenance}}
+---
+_Provenance: {{.}}_
+{{/provenance}}

templates/prompt.mustache

@@ -0,0 +1,30 @@
+{{title}}
+
+{{semantic_description}}
+
+{{#constraints}}
+Constraint: {{.}}
+{{/constraints}}
+
+{{#geometry}}
+Geometry: {{.}}
+{{/geometry}}
+
+{{#operations}}
+Operation: {{.}}
+{{/operations}}
+
+{{#code}}
+```
+{{code}}
+```
+{{/code}}
+
+{{#tests}}
+Tests:
+{{tests}}
+{{/tests}}
+
+{{#provenance}}
+Provenance: {{.}}
+{{/provenance}}

tests/conftest.py

@@ -0,0 +1,8 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))

tests/test_boolean.py

@@ -0,0 +1,108 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Tests: Phase 7 — Boolean engine."""
+
+import pytest
+from semantic_engine.boolean_engine import (
+    AND, OR, NOT, XOR, IMPLIES, EQUIV,
+    BooleanLiteral, BooleanVar, BooleanExpression,
+    var, lit, normalize, to_cnf, simplify,
+    semantic_constraints_to_boolean,
+)
+from semantic_engine.types import BooleanOperator
+
+
+def test_literal_repr():
+    assert repr(BooleanLiteral(True)) == "⊤"
+    assert repr(BooleanLiteral(False)) == "⊥"
+
+
+def test_var_repr():
+    assert repr(BooleanVar("x")) == "x"
+    assert repr(BooleanVar("x", negated=True)) == "¬x"
+
+
+def test_and_repr():
+    e = AND(var("a"), var("b"))
+    assert "∧" in repr(e)
+
+
+def test_simplify_double_negation():
+    e = NOT(NOT(var("x")))
+    result = simplify(e)
+    assert isinstance(result, BooleanVar)
+    assert result.name == "x"
+    assert not result.negated
+
+
+def test_simplify_and_with_true():
+    e = AND(BooleanLiteral(True), var("x"))
+    result = simplify(e)
+    assert isinstance(result, BooleanVar)
+    assert result.name == "x"
+
+
+def test_simplify_and_with_false():
+    e = AND(BooleanLiteral(False), var("x"))
+    result = simplify(e)
+    assert isinstance(result, BooleanLiteral)
+    assert not result.value
+
+
+def test_simplify_or_with_true():
+    e = OR(BooleanLiteral(True), var("x"))
+    result = simplify(e)
+    assert isinstance(result, BooleanLiteral)
+    assert result.value
+
+
+def test_implies_expansion():
+    e = IMPLIES(var("a"), var("b"))
+    result = simplify(e)
+    assert repr(result)  # should not crash
+
+
+def test_equivalence_expansion():
+    e = EQUIV(var("a"), var("b"))
+    result = simplify(e)
+    assert repr(result)
+
+
+def test_xor_expansion():
+    e = XOR(var("a"), var("b"))
+    result = simplify(e)
+    assert repr(result)
+
+
+def test_normalize_idempotent():
+    e = AND(var("a"), OR(var("b"), NOT(var("c"))))
+    n1 = normalize(e)
+    n2 = normalize(n1)
+    assert repr(n1) == repr(n2)
+
+
+def test_normalize_literal_true():
+    assert isinstance(normalize(BooleanLiteral(True)), BooleanLiteral)
+
+
+def test_constraints_to_boolean_empty():
+    bnf = semantic_constraints_to_boolean([])
+    assert isinstance(bnf.normalized, BooleanLiteral)
+    assert bnf.normalized.value is True
+
+
+def test_constraints_to_boolean_single():
+    from semantic_engine.ir import Constraint
+    c = Constraint.make("deterministic", "deterministic")
+    bnf = semantic_constraints_to_boolean([c])
+    assert bnf.stable
+
+
+def test_constraints_to_boolean_multiple():
+    from semantic_engine.ir import Constraint
+    cs = [Constraint.make("deterministic", "deterministic"),
+          Constraint.make("immutable", "immutable")]
+    bnf = semantic_constraints_to_boolean(cs)
+    assert bnf.stable

tests/test_fsm.py

@@ -0,0 +1,69 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Tests: Phase 3 — Decoder FSM."""
+
+import pytest
+from semantic_engine.fsm import FSMContext, TRANSITION_TABLE, validate_constraints
+from semantic_engine.types import FSMState, PipelineError
+
+
+def test_initial_state():
+    ctx = FSMContext()
+    assert ctx.state == FSMState.INPUT
+
+
+def test_valid_transition():
+    ctx = FSMContext()
+    ctx.set("raw_text", "hello world")
+    t = ctx.transition("raw_input")
+    assert ctx.state == FSMState.NORMALIZE
+    assert t.source_state == FSMState.INPUT
+
+
+def test_invalid_transition_fails_closed():
+    ctx = FSMContext()
+    with pytest.raises(PipelineError) as exc_info:
+        ctx.transition("invalid_class_xyz")
+    assert "fail" in str(exc_info.value).lower() or "transition" in str(exc_info.value).lower()
+
+
+def test_transition_history_recorded():
+    ctx = FSMContext()
+    ctx.set("raw_text", "hello")
+    ctx.transition("raw_input")
+    assert len(ctx.history) == 1
+    src, inp, dst = ctx.history[0]
+    assert src == FSMState.INPUT
+    assert dst == FSMState.NORMALIZE
+
+
+def test_all_transitions_explicit():
+    """Every transition in the table must have source, input_class, destination."""
+    for t in TRANSITION_TABLE:
+        assert t.source_state is not None
+        assert t.input_class
+        assert t.destination_state is not None
+        assert t.invariant
+
+
+def test_transition_table_no_duplicate_keys():
+    keys = [(t.source_state, t.input_class) for t in TRANSITION_TABLE]
+    assert len(keys) == len(set(keys)), "Duplicate transition keys found"
+
+
+def test_is_terminal():
+    ctx = FSMContext()
+    assert not ctx.is_terminal()
+    ctx.state = FSMState.COMPLETE
+    assert ctx.is_terminal()
+    ctx.state = FSMState.ERROR
+    assert ctx.is_terminal()
+
+
+def test_context_set_get():
+    ctx = FSMContext()
+    ctx.set("foo", 42)
+    assert ctx.get("foo") == 42
+    assert ctx.get("missing") is None

tests/test_ir.py

@@ -0,0 +1,106 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Tests: Phase 2 — Semantic IR."""
+
+import pytest
+from semantic_engine.ir import (
+    Geometry, TemporalState, TemporalLock, TemporalTransition,
+    Operand, Constraint, SemanticOperation, SemanticNode,
+    SemanticIR, Artifact,
+)
+from semantic_engine.types import (
+    ArtifactType, FSMState, IntentClass, Provenance,
+    SemanticNodeType, TemporalViolation, VerificationState,
+)
+
+
+def make_provenance():
+    return Provenance("input-1", "test")
+
+
+def make_temporal():
+    return TemporalState(tau=0)
+
+
+def test_geometry_matmul_compatible():
+    a = Geometry(row=3, col=4)
+    b = Geometry(row=4, col=5)
+    assert a.compatible_with(b)
+    out = a.output_geometry(b)
+    assert out.row == 3
+    assert out.col == 5
+
+
+def test_geometry_matmul_incompatible():
+    a = Geometry(row=3, col=4)
+    b = Geometry(row=5, col=5)
+    assert not a.compatible_with(b)
+
+
+def test_temporal_advance():
+    t = TemporalState(tau=0)
+    t1 = t.advance("step1")
+    assert t1.tau == 1
+    assert t.tau == 0  # original unchanged
+
+
+def test_temporal_lock_prevents_advance():
+    t = TemporalState(tau=0, locked=True)
+    with pytest.raises(TemporalViolation):
+        t.advance("should fail")
+
+
+def test_temporal_lock_records_transitions():
+    lock = TemporalLock()
+    t = TemporalTransition(from_tau=0, to_tau=1, reason="step", stage="test")
+    lock.record(t)
+    assert len(lock.audit()) == 1
+
+
+def test_temporal_lock_rejects_invalid_jump():
+    lock = TemporalLock()
+    bad = TemporalTransition(from_tau=0, to_tau=5, reason="jump", stage="test")
+    with pytest.raises(TemporalViolation):
+        lock.record(bad)
+
+
+def test_semantic_node_stable_id():
+    p = make_provenance()
+    t = make_temporal()
+    op = SemanticOperation("build", 1)
+    n1 = SemanticNode.make(SemanticNodeType.OPERATION, op, [], [], None, t, p)
+    n2 = SemanticNode.make(SemanticNodeType.OPERATION, op, [], [], None, t, p)
+    assert n1.id == n2.id
+
+
+def test_semantic_ir_create():
+    p = make_provenance()
+    t = make_temporal()
+    op = SemanticOperation("build", 0)
+    node = SemanticNode.make(SemanticNodeType.INTENT, op, [], [], None, t, p)
+    ir = SemanticIR.create(IntentClass.BUILD, node, [node], TemporalLock(), p)
+    assert ir.ir_id
+    assert ir.intent == IntentClass.BUILD
+    assert ir.verification_state == VerificationState.UNVERIFIED
+
+
+def test_semantic_ir_find_node():
+    p = make_provenance()
+    t = make_temporal()
+    op = SemanticOperation("build", 0)
+    node = SemanticNode.make(SemanticNodeType.INTENT, op, [], [], None, t, p)
+    ir = SemanticIR.create(IntentClass.BUILD, node, [node], TemporalLock(), p)
+    found = ir.find_node(node.id)
+    assert found is node
+    assert ir.find_node("nonexistent") is None
+
+
+def test_artifact_create():
+    p = make_provenance()
+    t = make_temporal()
+    a = Artifact.create(ArtifactType.DOCUMENT, "root-id", "tmpl", "content", p, t)
+    assert a.type == ArtifactType.DOCUMENT
+    assert a.content == "content"
+    assert a.semantic_root == "root-id"

tests/test_roundtrip.py

@@ -0,0 +1,140 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Tests: Phase 20 — Round-trip and equivalence invariants."""
+
+import pytest
+from semantic_engine.boolean_engine import (
+    AND, OR, NOT, XOR, IMPLIES, EQUIV,
+    BooleanLiteral, BooleanVar,
+    normalize, var, lit,
+)
+from semantic_engine.token_engine import encode, decode, round_trip, BoolEncoder, encode_binary, decode_binary
+from semantic_engine.latin import LatinCanonicalizer
+from semantic_engine.rosetta import RosettaMapper
+
+
+# ── Boolean round-trips ───────────────────────────────────────────────────────
+
+CANONICAL_EXPRS = [
+    BooleanLiteral(True),
+    BooleanLiteral(False),
+    BooleanVar("x"),
+    BooleanVar("x", negated=True),
+    AND(BooleanVar("a"), BooleanVar("b")),
+    OR(BooleanVar("a"), BooleanVar("b")),
+    NOT(BooleanVar("x")),
+    AND(BooleanVar("a"), OR(BooleanVar("b"), BooleanVar("c"))),
+    OR(AND(BooleanVar("a"), BooleanVar("b")), NOT(BooleanVar("c"))),
+]
+
+
+@pytest.mark.parametrize("expr", CANONICAL_EXPRS)
+def test_token_round_trip(expr):
+    """decode(encode(x)) == x for all canonical Boolean structures."""
+    result = round_trip(expr)
+    assert repr(result) == repr(expr), f"Round-trip failed for {expr}"
+
+
+@pytest.mark.parametrize("expr", CANONICAL_EXPRS)
+def test_normalize_idempotent(expr):
+    """normalize(normalize(x)) == normalize(x)"""
+    n1 = normalize(expr)
+    n2 = normalize(n1)
+    assert repr(n1) == repr(n2), f"Normalization not idempotent for {expr}"
+
+
+# ── Binary serialization round-trips ─────────────────────────────────────────
+
+@pytest.mark.parametrize("expr", CANONICAL_EXPRS)
+def test_binary_round_trip(expr):
+    """Binary encode/decode preserves all tokens."""
+    stream = BoolEncoder().encode_expr(expr)
+    binary = encode_binary(stream)
+    decoded_stream = decode_binary(binary)
+    assert len(stream.tokens) == len(decoded_stream.tokens)
+    for orig, dec in zip(stream.tokens, decoded_stream.tokens):
+        assert orig.token_type == dec.token_type
+        assert orig.payload == dec.payload
+
+
+# ── Latin round-trip ─────────────────────────────────────────────────────────
+
+@pytest.mark.parametrize("expr", CANONICAL_EXPRS)
+def test_latin_derivable_from_tokens(expr):
+    """Latin canonical form must derive from the token stream without loss."""
+    stream = BoolEncoder().encode_expr(expr)
+    latin = LatinCanonicalizer().canonicalize(stream)
+    assert len(latin.tokens) > 0
+
+
+# ── Pipeline semantic preservation ───────────────────────────────────────────
+
+def test_pipeline_preserves_intent():
+    from semantic_engine import SemanticPipeline, RawInput, OutputMode
+    r = RawInput("build a matrix multiplication function")
+    result = SemanticPipeline().run(r)
+    assert result.ir is not None
+    from semantic_engine.types import IntentClass
+    assert result.ir.intent == IntentClass.BUILD
+
+
+def test_pipeline_verified_on_valid_input():
+    from semantic_engine import SemanticPipeline, RawInput
+    from semantic_engine.types import VerificationState
+    r = RawInput("multiply two matrices")
+    result = SemanticPipeline().run(r)
+    assert result.verification_state == VerificationState.VERIFIED
+
+
+def test_pipeline_artifact_traces_to_ir():
+    from semantic_engine import SemanticPipeline, RawInput
+    r = RawInput("generate a parser for binary format")
+    result = SemanticPipeline().run(r)
+    assert result.artifact is not None
+    assert result.artifact.semantic_root == result.ir.ir_id
+
+
+def test_pipeline_hashes_recorded():
+    from semantic_engine import SemanticPipeline, RawInput
+    r = RawInput("validate packet structure")
+    result = SemanticPipeline().run(r)
+    assert "input" in result.hashes
+    assert "semantic_ir" in result.hashes
+    assert "subleq" in result.hashes
+    assert "artifact" in result.hashes
+
+
+def test_pipeline_deterministic_on_same_input():
+    """Same input → same semantic IR hash (modulo UUIDs)."""
+    from semantic_engine import SemanticPipeline, RawInput
+    text = "compute matrix product"
+    r1 = RawInput(text)
+    r2 = RawInput(text)
+    p = SemanticPipeline()
+    res1 = p.run(r1)
+    res2 = p.run(r2)
+    # Both must succeed and produce same intent
+    assert res1.ir.intent == res2.ir.intent
+    assert res1.ir.root.id == res2.ir.root.id  # node ID is content-addressed
+
+
+def test_pipeline_two_output_modes():
+    """Same IR must be able to produce both NL and code artifacts."""
+    from semantic_engine import SemanticPipeline, RawInput, OutputMode
+    r = RawInput("build a validation service")
+    p = SemanticPipeline()
+    nl = p.run(r, output_mode=OutputMode.NATURAL_LANGUAGE)
+    code = p.run(RawInput("build a validation service"), output_mode=OutputMode.CODE)
+    assert nl.artifact is not None
+    assert code.artifact is not None
+    assert nl.artifact.type.value != code.artifact.type.value
+
+
+def test_pipeline_rejects_empty_input():
+    from semantic_engine import SemanticPipeline, RawInput
+    r = RawInput("")
+    result = SemanticPipeline().run(r)
+    # May complete but should not crash
+    assert result is not None

tests/test_subleq.py

@@ -0,0 +1,137 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Tests: Phases 12-13 — SUBLEQ IR and VM."""
+
+import pytest
+from semantic_engine.subleq import (
+    SubleqInstruction, SubleqProgram, SubleqMemory, SubleqVM,
+    HALT_ADDRESS, MAX_MEMORY,
+)
+from semantic_engine.types import PipelineError
+
+
+def halt_prog() -> SubleqProgram:
+    prog = SubleqProgram()
+    prog.data[0] = 0  # zero cell
+    prog.add(SubleqInstruction(A=0, B=0, C=HALT_ADDRESS, comment="HALT"))
+    return prog
+
+
+def test_instruction_repr():
+    instr = SubleqInstruction(A=1, B=2, C=3)
+    r = repr(instr)
+    assert "SUBLEQ" in r
+
+
+def test_instruction_halt_repr():
+    instr = SubleqInstruction(A=0, B=0, C=HALT_ADDRESS)
+    assert "HALT" in repr(instr)
+
+
+def test_program_add_and_label():
+    prog = SubleqProgram()
+    prog.add(SubleqInstruction(A=0, B=0, C=HALT_ADDRESS, label="start"))
+    assert "start" in prog.labels
+    assert prog.labels["start"] == 0
+
+
+def test_program_resolve_label():
+    prog = SubleqProgram()
+    prog.add(SubleqInstruction(A=0, B=0, C=HALT_ADDRESS, label="end"))
+    assert prog.resolve_label("end") == 0
+
+
+def test_program_resolve_missing_label():
+    prog = SubleqProgram()
+    with pytest.raises(PipelineError):
+        prog.resolve_label("missing")
+
+
+def test_assemble_disassemble_roundtrip():
+    prog = SubleqProgram()
+    prog.add(SubleqInstruction(A=1, B=2, C=3))
+    prog.add(SubleqInstruction(A=4, B=5, C=HALT_ADDRESS))
+    binary = prog.assemble()
+    recovered = SubleqProgram.disassemble(binary)
+    assert len(recovered.instructions) == 2
+    assert recovered.instructions[0].A == 1
+    assert recovered.instructions[0].B == 2
+    assert recovered.instructions[1].C == HALT_ADDRESS
+
+
+def test_assemble_bad_alignment():
+    with pytest.raises(PipelineError):
+        SubleqProgram.disassemble(b"\x00\x01\x02\x03")
+
+
+def test_memory_read_write():
+    mem = SubleqMemory()
+    mem.write(100, 42)
+    assert mem.read(100) == 42
+
+
+def test_memory_out_of_bounds():
+    mem = SubleqMemory()
+    with pytest.raises(PipelineError):
+        mem.read(MAX_MEMORY + 1)
+    with pytest.raises(PipelineError):
+        mem.write(-1, 0)
+
+
+def test_vm_halts():
+    prog = halt_prog()
+    vm = SubleqVM()
+    vm.load(prog)
+    vm.execute()
+    assert vm.halted
+
+
+def test_vm_step_returns_false_on_halt():
+    prog = halt_prog()
+    vm = SubleqVM()
+    vm.load(prog)
+    while not vm.halted:
+        result = vm.step()
+    assert not result
+
+
+def test_vm_trace_recorded():
+    prog = halt_prog()
+    vm = SubleqVM()
+    vm.load(prog)
+    trace = vm.execute()
+    assert len(trace) >= 1
+    assert trace[0].pc >= 0  # PC starts at base offset
+
+
+def test_vm_max_steps_exceeded():
+    prog = SubleqProgram()
+    # Infinite loop: SUBLEQ 0 0 0
+    prog.data[0] = 0
+    prog.add(SubleqInstruction(A=0, B=0, C=0))
+    vm = SubleqVM(max_steps=10)
+    vm.load(prog)
+    with pytest.raises(PipelineError) as exc:
+        vm.execute()
+    assert "max" in str(exc.value).lower() or "steps" in str(exc.value).lower()
+
+
+def test_verify_halts():
+    prog = halt_prog()
+    vm = SubleqVM()
+    assert vm.verify_halts(prog)
+
+
+def test_subleq_arithmetic():
+    """SUBLEQ(A, B, C): mem[B] -= mem[A]; branch if <=0"""
+    prog = SubleqProgram()
+    # Use addresses 10, 11 for data (well below base=100 for instructions)
+    prog.data[10] = 5
+    prog.data[11] = 3
+    prog.add(SubleqInstruction(A=10, B=11, C=HALT_ADDRESS))
+    vm = SubleqVM()
+    vm.load(prog)
+    vm.execute()
+    assert vm.memory.read(11) == -2

tests/test_tokens.py

@@ -0,0 +1,107 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Tests: Phase 8 — Boolean token engine."""
+
+import pytest
+from semantic_engine.boolean_engine import AND, OR, NOT, var, lit, BooleanLiteral, BooleanVar
+from semantic_engine.token_engine import (
+    BoolEncoder, BoolDecoder, BooleanTokenStream,
+    encode_binary, decode_binary, encode, decode, round_trip,
+    TTYPE_AND, TTYPE_OR, TTYPE_NOT, TTYPE_TRUE, TTYPE_FALSE,
+    TTYPE_VAR, TTYPE_VAR_NEG, TTYPE_OPEN, TTYPE_CLOSE,
+)
+from semantic_engine.types import FSMState, TokenError
+
+
+def encode_and_check(expr):
+    stream = BoolEncoder().encode_expr(expr)
+    binary = encode_binary(stream)
+    decoded = decode_binary(binary)
+    return stream, binary, decoded
+
+
+def test_encode_literal_true():
+    stream, binary, decoded = encode_and_check(BooleanLiteral(True))
+    assert len(decoded.tokens) == 1
+    assert decoded.tokens[0].token_type == TTYPE_TRUE
+
+
+def test_encode_literal_false():
+    stream, binary, decoded = encode_and_check(BooleanLiteral(False))
+    assert decoded.tokens[0].token_type == TTYPE_FALSE
+
+
+def test_encode_var():
+    stream, binary, decoded = encode_and_check(BooleanVar("x"))
+    assert decoded.tokens[0].token_type == TTYPE_VAR
+    assert decoded.tokens[0].payload == b"x"
+
+
+def test_encode_var_negated():
+    stream, binary, decoded = encode_and_check(BooleanVar("x", negated=True))
+    assert decoded.tokens[0].token_type == TTYPE_VAR_NEG
+    assert decoded.tokens[0].payload == b"x"
+
+
+def test_encode_and():
+    expr = AND(var("a"), var("b"))
+    stream = BoolEncoder().encode_expr(expr)
+    types = [t.token_type for t in stream]
+    assert TTYPE_AND in types
+    assert TTYPE_OPEN in types
+    assert TTYPE_CLOSE in types
+
+
+def test_encode_not():
+    expr = NOT(var("x"))
+    stream = BoolEncoder().encode_expr(expr)
+    types = [t.token_type for t in stream]
+    assert TTYPE_NOT in types
+
+
+def test_round_trip_literal():
+    expr = BooleanLiteral(True)
+    result = round_trip(expr)
+    assert isinstance(result, BooleanLiteral)
+    assert result.value is True
+
+
+def test_round_trip_var():
+    expr = BooleanVar("myvar")
+    result = round_trip(expr)
+    assert isinstance(result, BooleanVar)
+    assert result.name == "myvar"
+    assert not result.negated
+
+
+def test_round_trip_complex():
+    expr = AND(var("a"), OR(var("b"), NOT(var("c"))))
+    result = round_trip(expr)
+    # repr should match after round-trip
+    assert repr(result) == repr(expr)
+
+
+def test_binary_bad_magic():
+    with pytest.raises(TokenError):
+        decode_binary(b"XXXX\x01\x00\x01")
+
+
+def test_binary_too_short():
+    with pytest.raises(TokenError):
+        decode_binary(b"BO")
+
+
+def test_token_positions():
+    expr = AND(var("a"), var("b"))
+    stream = BoolEncoder().encode_expr(expr)
+    for i, tok in enumerate(stream):
+        assert tok.position == i
+
+
+def test_token_ids_unique():
+    expr = AND(var("a"), OR(var("b"), var("c")))
+    stream = BoolEncoder().encode_expr(expr)
+    ids = [t.token_id for t in stream]
+    assert len(ids) == len(set(ids))

tests/test_types.py

@@ -0,0 +1,70 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Tests: Phase 1 — Core types."""
+
+import pytest
+from semantic_engine.types import (
+    RawInput, NormalizedInput, SemanticCandidate,
+    FSMState, VerificationState, ArtifactType, BooleanOperator,
+    IntentClass, Provenance, FSMTransition, PipelineError,
+)
+
+
+def test_raw_input_immutable():
+    r = RawInput("hello world")
+    with pytest.raises(AttributeError):
+        r.text = "changed"
+
+
+def test_raw_input_hash_deterministic():
+    r1 = RawInput("hello")
+    r2 = RawInput("hello")
+    assert r1.hash == r2.hash
+
+
+def test_raw_input_unique_id():
+    r1 = RawInput("hello")
+    r2 = RawInput("hello")
+    assert r1.input_id != r2.input_id
+
+
+def test_semantic_candidate_confidence_range():
+    with pytest.raises(ValueError):
+        SemanticCandidate("id", IntentClass.BUILD, [], [], [], [], 1.5, False)
+    with pytest.raises(ValueError):
+        SemanticCandidate("id", IntentClass.BUILD, [], [], [], [], -0.1, False)
+
+
+def test_semantic_candidate_valid():
+    c = SemanticCandidate("id", IntentClass.BUILD, ["matrix"], ["build"], [], [], 0.8, False)
+    assert c.confidence == 0.8
+
+
+def test_fsm_states_unique():
+    values = [s.value for s in FSMState]
+    assert len(values) == len(set(values))
+
+
+def test_provenance_chain_hash():
+    p = Provenance("input-1", "test", transform_hash="abc")
+    h1 = p.chain_hash("data")
+    h2 = p.chain_hash("data")
+    assert h1 == h2
+
+
+def test_fsm_transition_validate():
+    t = FSMTransition(
+        FSMState.INPUT, "raw_input", "normalize",
+        ("text_not_empty",), FSMState.NORMALIZE, "input preserved",
+    )
+    assert t.validate(FSMState.INPUT, "raw_input")
+    assert not t.validate(FSMState.COMPLETE, "raw_input")
+    assert not t.validate(FSMState.INPUT, "wrong_class")
+
+
+def test_pipeline_error_message():
+    e = PipelineError(FSMState.TOKENIZATION, "token broken")
+    assert "TOKENIZATION" in str(e)
+    assert "token broken" in str(e)

tests/test_unknown.py

@@ -0,0 +1,255 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Tests: ADR-Ω-0001 — The Uninterpreted Operator and WORM Seal Engine."""
+
+import pytest
+from semantic_engine.unknown import (
+    InvariantState, ObservationRecord, UnknownClassification,
+    WORMSealChain, WORMSealEntry, UnknownNode, UnknownOperatorError,
+    observe_and_seal, _seal_hash, _canonical,
+)
+
+
+# ── InvariantState ────────────────────────────────────────────────────────────
+
+def test_invariant_hash_deterministic():
+    omega = InvariantState(tau=0, system_hash="abc123", properties=("typed", "deterministic"))
+    assert omega.hash() == omega.hash()
+
+
+def test_invariant_hash_changes_with_tau():
+    o1 = InvariantState(tau=0, system_hash="abc")
+    o2 = InvariantState(tau=1, system_hash="abc")
+    assert o1.hash() != o2.hash()
+
+
+# ── ObservationRecord ─────────────────────────────────────────────────────────
+
+def make_omega(tau=0):
+    return InvariantState(tau=tau, system_hash="test_hash")
+
+
+def test_observation_record_hash_valid():
+    omega = make_omega()
+    rec = ObservationRecord.observe("input_A", "output_B", omega)
+    assert rec.verify()
+
+
+def test_observation_record_fabricated_hash_fails():
+    omega = make_omega()
+    rec = ObservationRecord.observe("input_A", "output_B", omega)
+    # Tamper with provenance hash
+    tampered = ObservationRecord(
+        input_state=rec.input_state,
+        output_state=rec.output_state,
+        provenance_hash="deadbeef" * 8,
+        timestamp=rec.timestamp,
+        invariant=rec.invariant,
+        classification=rec.classification,
+    )
+    assert not tampered.verify()
+
+
+def test_observation_starts_as_observed():
+    rec = ObservationRecord.observe("A", "B", make_omega())
+    assert rec.classification == UnknownClassification.OBSERVED
+
+
+def test_classification_pipeline_valid():
+    rec = ObservationRecord.observe("A", "B", make_omega())
+    rec = rec.advance(UnknownClassification.CAPTURED)
+    rec = rec.advance(UnknownClassification.HASHED)
+    rec = rec.advance(UnknownClassification.COMPARED)
+    rec = rec.advance(UnknownClassification.TESTED)
+    rec = rec.advance(UnknownClassification.CLASSIFIED)
+    assert rec.classification == UnknownClassification.CLASSIFIED
+
+
+def test_classification_skip_not_allowed():
+    """UNKNOWN must not become UNDERSTOOD by skipping stages."""
+    rec = ObservationRecord.observe("A", "B", make_omega())
+    with pytest.raises(UnknownOperatorError):
+        rec.advance(UnknownClassification.CLASSIFIED)  # skip CAPTURED, HASHED, etc.
+
+
+def test_classification_backward_not_allowed():
+    rec = ObservationRecord.observe("A", "B", make_omega())
+    rec = rec.advance(UnknownClassification.CAPTURED)
+    with pytest.raises(UnknownOperatorError):
+        rec.advance(UnknownClassification.OBSERVED)  # go backward
+
+
+def test_unknown_is_not_true_or_false():
+    """Fundamental property: UNKNOWN ≠ FALSE, UNKNOWN ≠ TRUE."""
+    rec = ObservationRecord.observe("A", "B", make_omega())
+    node = UnknownNode(node_id="test", observation=rec)
+    assert not node.is_understood
+    # The node never claims to know what ? means
+    assert "?" in repr(node)
+
+
+# ── Seal hash ─────────────────────────────────────────────────────────────────
+
+def test_seal_hash_deterministic():
+    omega = make_omega()
+    h1 = _seal_hash("A", "B", omega)
+    h2 = _seal_hash("A", "B", omega)
+    assert h1 == h2
+
+
+def test_seal_hash_changes_with_input():
+    omega = make_omega()
+    h1 = _seal_hash("A", "B", omega)
+    h2 = _seal_hash("X", "B", omega)
+    assert h1 != h2
+
+
+def test_seal_hash_changes_with_output():
+    omega = make_omega()
+    h1 = _seal_hash("A", "B", omega)
+    h2 = _seal_hash("A", "Z", omega)
+    assert h1 != h2
+
+
+def test_seal_hash_includes_omega():
+    o1 = make_omega(tau=0)
+    o2 = make_omega(tau=1)
+    h1 = _seal_hash("A", "B", o1)
+    h2 = _seal_hash("A", "B", o2)
+    assert h1 != h2
+
+
+# ── WORM Seal Chain ───────────────────────────────────────────────────────────
+
+def test_worm_chain_starts_empty():
+    chain = WORMSealChain()
+    assert len(chain) == 0
+    assert chain.head() is None
+
+
+def test_worm_seal_appends():
+    chain = WORMSealChain()
+    rec = ObservationRecord.observe("A", "B", make_omega())
+    entry = chain.seal(rec)
+    assert len(chain) == 1
+    assert entry.index == 0
+    assert entry.previous_hash == "0" * 64
+
+
+def test_worm_chain_links():
+    chain = WORMSealChain()
+    r1 = ObservationRecord.observe("A", "B", make_omega(0))
+    r2 = ObservationRecord.observe("B", "C", make_omega(1))
+    e1 = chain.seal(r1)
+    e2 = chain.seal(r2)
+    assert e2.previous_hash == e1.entry_hash
+    assert e2.index == 1
+
+
+def test_worm_chain_verify_intact():
+    chain = WORMSealChain()
+    for i in range(5):
+        rec = ObservationRecord.observe(f"input_{i}", f"output_{i}", make_omega(i))
+        chain.seal(rec)
+    ok, errors = chain.verify_chain()
+    assert ok
+    assert errors == []
+
+
+def test_worm_chain_audit_returns_all():
+    chain = WORMSealChain()
+    for i in range(3):
+        rec = ObservationRecord.observe(f"A{i}", f"B{i}", make_omega(i))
+        chain.seal(rec)
+    audit = chain.audit()
+    assert len(audit) == 3
+    for entry in audit:
+        assert "entry_hash" in entry
+        assert "provenance_hash" in entry
+
+
+def test_worm_seal_not_mutable():
+    """Once sealed, the entry is frozen (frozen dataclass)."""
+    chain = WORMSealChain()
+    rec = ObservationRecord.observe("A", "B", make_omega())
+    entry = chain.seal(rec)
+    with pytest.raises((AttributeError, TypeError)):
+        entry.entry_hash = "tampered"
+
+
+def test_worm_export_import_jsonl(tmp_path):
+    chain = WORMSealChain()
+    for i in range(3):
+        rec = ObservationRecord.observe(f"A{i}", f"B{i}", make_omega(i))
+        chain.seal(rec)
+    p = tmp_path / "chain.jsonl"
+    chain.export_jsonl(p)
+    rows = WORMSealChain.import_jsonl(p)
+    assert len(rows) == 3
+    assert rows[0]["index"] == 0
+    assert rows[2]["index"] == 2
+
+
+# ── observe_and_seal ──────────────────────────────────────────────────────────
+
+def test_observe_and_seal_full_pipeline():
+    chain = WORMSealChain()
+    omega = make_omega(tau=5)
+    node = observe_and_seal("my_input", "my_output", omega, chain)
+    assert node.is_sealed
+    assert not node.is_understood
+    assert node.observation.classification == UnknownClassification.CLASSIFIED
+    assert len(chain) == 1
+
+
+def test_observe_and_seal_chain_verifies():
+    chain = WORMSealChain()
+    omega = make_omega()
+    observe_and_seal("A", "B", omega, chain)
+    observe_and_seal("B", "C", omega, chain)
+    ok, errors = chain.verify_chain()
+    assert ok
+
+
+def test_observe_and_seal_repr():
+    chain = WORMSealChain()
+    node = observe_and_seal("x", "y", make_omega(), chain)
+    r = repr(node)
+    assert "?" in r
+    assert "CLASSIFIED" in r
+    assert "SEALED" in r
+
+
+# ── Algebra invariants ────────────────────────────────────────────────────────
+
+def test_unknown_not_equal_to_understood():
+    """
+    The fundamental ADR invariant:
+    UNKNOWN ≠ FALSE
+    UNKNOWN ≠ TRUE
+    """
+    rec = ObservationRecord.observe("A", "B", make_omega())
+    node = UnknownNode(node_id="abc", observation=rec)
+    assert node.is_understood is False
+    # Trying to assert it's True or False is a bug — the node never claims either
+    assert isinstance(node.is_understood, bool)
+    assert node.is_understood is not True
+
+
+def test_classification_terminal_at_classified():
+    """Once CLASSIFIED, no further advancement is defined."""
+    rec = ObservationRecord.observe("A", "B", make_omega())
+    for step in [
+        UnknownClassification.CAPTURED,
+        UnknownClassification.HASHED,
+        UnknownClassification.COMPARED,
+        UnknownClassification.TESTED,
+        UnknownClassification.CLASSIFIED,
+    ]:
+        rec = rec.advance(step)
+
+    # No valid next step exists
+    with pytest.raises(UnknownOperatorError):
+        rec.advance(UnknownClassification.OBSERVED)