pgc-compiler 2.0.0__py3-none-any.whl

compiler/diagnostics/determination.py

@@ -0,0 +1,148 @@
+"""Construction determination records — evidence that a determination was made, including refusals.
+
+`3e` §3.1: for any determination, its evidence must be sufficient to establish which closure applied,
+which rules that closure supplied, what each predicate yielded, what the dominant consequence was,
+and that the resulting state is what that consequence permitted.
+
+Construction previously produced none. A refused build wrote a diagnostic to stderr and exited 1, so
+the determination *this candidate set is inadmissible under this closure* — the exact subject of
+`3e` §3.3 — left no checkable record anywhere. Admissions were evidenced by their output; refusals
+by nothing, which is EV-3 and EN-12 breached in the direction that matters, since a system recording
+what it permitted and not what it refused has a record of its work proceeding rather than of its
+governance operating.
+
+**A record is not usable output.** `4a` GC-6 forbids a refused construction producing usable output,
+and `1c` AI-8 states the boundary exactly: after refusal the governed state is as though the proposal
+had not been made, *"except for the evidence that it was refused."* The realization's own technique
+table lists "a failed build writing nothing" as serving AI-8; that technique overshot the property it
+served, and this is the correction.
+
+Records are written outside the compiled output tree. Nothing reads them — they are evidence, and
+`3e` §3.2 makes evidence output only.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+
+RECORD_VERSION = "v0"
+
+
+def _root() -> Path:
+    """Where determination records are written — outside the compiled output tree.
+
+    `PGC_SNAPSHOT_ROOT` is set per build by the runners; the compiled projections live under
+    `<root>/compiled`, so records sit beside them rather than within them. A record inside the output
+    would be output, and GC-6 is about what a refused construction leaves behind.
+    """
+    root = os.environ.get("PGC_SNAPSHOT_ROOT")
+    if not root:
+        # No fallback. A relative default would write the record wherever the process happened to be
+        # standing — which put it inside the assembled snapshot the first time this ran, where it
+        # would have become undeclared content at acceptance. An unlocatable evidence root is a
+        # refusal to write, reported, not a guess.
+        raise RuntimeError(
+            "PGC_SNAPSHOT_ROOT is not set — there is no declared root to write the determination "
+            "record to, and a relative default would place evidence by accident."
+        )
+    return Path(root) / "determinations"
+
+
+def _closure(state: Any) -> dict[str, Any]:
+    """Which closure applied — `3e` §3.1 point 1."""
+    meta = dict(getattr(state, "stage_metadata", {}) or {})
+    closure = dict(meta.get("governance_closure") or {})
+    return {
+        # The closure enumerated. `rules_supplied` and `predicate_results` name every governing
+        # element that applied and by what invariant identity — that enumeration is what establishes
+        # point 1; the hash below is a compact identifier for the same set, present only where a
+        # closure was imported. The platform IS the governance surface and imports none, so it
+        # carries no hash and its closure is established by the enumeration alone.
+        "authorized_namespaces": list(meta.get("authorized_namespaces", []) or []),
+        "imported_governance": closure or None,
+    }
+
+
+def _rules_and_predicates(state: Any) -> tuple[list[str], list[dict[str, Any]]]:
+    """Which rules the closure supplied, and what each predicate yielded — points 2 and 3.
+
+    `assertion_coverage` is what `s4_govern` already records per derived assertion. It is lifted
+    rather than recomputed: a second derivation of one fact is two facts.
+    """
+    coverage = list((getattr(state, "stage_metadata", {}) or {}).get("assertion_coverage", []) or [])
+    supplied = sorted({c.get("assert_code", "") for c in coverage if c.get("assert_code")})
+    yielded = [
+        {
+            "rule": c.get("assert_code"),
+            "invariant": c.get("fqdn_id"),
+            "result": c.get("status"),
+            "violations": c.get("violations", 0),
+            "imported": c.get("imported", False),
+        }
+        for c in coverage
+    ]
+    return supplied, yielded
+
+
+def write(state: Any, structure: str, consequence: str, failed_at: str | None = None) -> Path | None:
+    """Write the determination record for one construction. Returns its path, or None if unwritable.
+
+    `consequence` is ADMITTED or REFUSED. Both are written, and written the same way: EV-3 requires
+    refusals evidenced as fully as admissions, and a record shape that differed between them would
+    make the two incomparable — which is how a system ends up able to show what it permitted and not
+    what it refused.
+    """
+    supplied, yielded = _rules_and_predicates(state)
+    errors = list(getattr(state, "errors", []) or [])
+    materialized = list(getattr(state, "materialized_paths", []) or [])
+
+    record = {
+        "record_version": RECORD_VERSION,
+        "record_type": "construction_determination",
+        "consequence": consequence,
+        # 1 — which closure applied
+        "closure": _closure(state),
+        # 2 — which rules that closure supplied
+        "rules_supplied": supplied,
+        # 3 — what each predicate yielded
+        "predicate_results": yielded,
+        # what was proposed
+        "proposed": {
+            "structure": structure,
+            "candidates": len(getattr(state, "graph", None).nodes) if getattr(state, "graph", None) else None,
+        },
+        # 4 — the dominant consequence, and its grounds
+        "grounds": [
+            {
+                "code": getattr(e, "code", None).value if hasattr(getattr(e, "code", None), "value") else str(getattr(e, "code", "")),
+                "phase": getattr(e, "phase", None),
+                "fqdn_id": getattr(e, "fqdn_id", None),
+                "message": getattr(e, "message", ""),
+            }
+            for e in errors
+        ],
+        # 5 — that the resulting state is what the consequence permitted
+        "resulting_state": {
+            "failed_at": failed_at,
+            "materialized_count": len(materialized),
+            "nothing_proceeded": consequence == "REFUSED" and not materialized,
+        },
+        # Observational content, declared as such (`3e` §5): it may differ between two determinations
+        # over the same inputs and no determination may depend on it.
+        "observational": {"determined_at_ns": time.time_ns()},
+    }
+
+    try:
+        root = _root()
+        root.mkdir(parents=True, exist_ok=True)
+        path = root / f"{structure}.{consequence.lower()}.json"
+        path.write_text(json.dumps(record, indent=2, sort_keys=False) + "\n", encoding="utf-8")
+        return path
+    except (OSError, RuntimeError):
+        # Evidence that cannot be written is a finding, not a reason to fail the determination it
+        # records — the determination already happened. Surfaced by the caller, never swallowed.
+        return None

compiler/diagnostics/machine_block_health.py

@@ -0,0 +1,199 @@
+"""Machine-block health — does the compiler consume the machine-block keys artifacts declare?
+
+A heuristic, post-successful-build diagnostic. For each compiled artifact whose kind is NOT
+already closed by schema conformance, it flattens the machine block to leaf keys and checks
+whether each leaf name appears as a string literal in the compiler source. A leaf with no
+detected consumer is a *candidate* — not proof — of an unconsumed declaration.
+
+Scope rule (principled, not an arbitrary list): the diagnostic applies only to artifact kinds
+whose machine-block consumption is NOT already closed by `additionalProperties: false` schema
+conformance. For schema-closed kinds an unconsumed key cannot silently survive, so a census
+adds only noise.
+
+Disposition (Machine Block §11): a top-level field with no detected compiler consumer is split
+by its kind's disposition. On a DECLARATIVE kind (STRUCTURE, VOCAB, … — inert definitions the
+topology references), such a field is *preserved* declared policy carried into the snapshot for
+downstream/runtime reference; that is a legitimate disposition, not a defect.
+
+A field on an EXECUTABLE kind may also be preserved, but only by NAMING its consumer in
+`_DOWNSTREAM_CONSUMERS`. Boundary contracts (TI/TE) are the standing case: the compiler seals
+them and the transport engine or the inspector interprets them, and the compiler cannot import
+either — so the scan structurally cannot see those consumers. Everything else on an EXECUTABLE
+kind is a genuine *candidate unconsumed*.
+
+Severity: WARNING only, and only for genuine candidates. It never fails the build, changes
+runtime behavior, or asserts a conformance rule. The authoritative rule is the compiler's actual
+behavior (and, where it applies, schema closure). A candidate means exactly: "this machine-block
+key has no detected compiler consumer" — the source-inspection method cannot prove a key unused.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterable
+
+from compiler.governance_engine.artifact_kinds import REGISTRY, DECLARATIVE
+
+_LITERAL = re.compile(r"""['"]([A-Za-z_][A-Za-z0-9_]*)['"]""")
+
+# Keys on an EXECUTABLE kind whose consumer is, BY ARCHITECTURE, outside the compiler.
+#
+# A boundary contract is a declaration the compiler seals and another component interprets. The
+# compiler cannot import that component — purity forbids it — so the source scan structurally
+# cannot see the consumer, and the key reads as unconsumed however live it is. Declaring it here
+# keeps the census honest: a false candidate teaches a reader to ignore the warning, and a
+# genuinely dead key then hides among the ones they have learned to skip.
+#
+# Each entry NAMES its consumer, so the claim is checkable rather than a blanket exemption. A key
+# that no component reads must not be listed — that is the finding the census exists to surface.
+_DOWNSTREAM_CONSUMERS: dict[tuple[str, str], str] = {
+    ("TE", "evidence_policy"): "consumed by the transport resolver (resolver/resolver.py)",
+    ("TI", "catalog"): "consumed by snapshot_inspector (inspector/catalog.py)",
+    ("WF", "subdomain"): "consumed by snapshot_assembler (assembler/indexes.py)",
+}
+
+_DECLARATIVE_POLICY = "declarative policy, no compiler consumer"
+
+
+@dataclass
+class KindReport:
+    consumed: set[str] = field(default_factory=set)
+    unconsumed: set[str] = field(default_factory=set)
+    preserved: dict[str, str] = field(default_factory=dict)   # key → why it is not a candidate
+
+
+@dataclass
+class HealthReport:
+    by_kind: dict[str, KindReport] = field(default_factory=dict)
+
+    @property
+    def examined(self) -> int:
+        return sum(len(k.consumed) + len(k.unconsumed) + len(k.preserved)
+                   for k in self.by_kind.values())
+
+    @property
+    def candidate_unconsumed(self) -> int:
+        return sum(len(k.unconsumed) for k in self.by_kind.values())
+
+    @property
+    def preserved_total(self) -> int:
+        return sum(len(k.preserved) for k in self.by_kind.values())
+
+    @property
+    def has_candidates(self) -> bool:
+        return self.candidate_unconsumed > 0
+
+
+def _source_literals(compiler_src: Path) -> set[str]:
+    """Every quoted identifier appearing anywhere in the compiler source (its consumption surface).
+
+    This module is excluded from its own scan. Its literals name keys in order to CLASSIFY them,
+    never to consume them — counting those would let the census answer its own question, reporting
+    a key as compiler-consumed on the strength of the table that says it is consumed elsewhere.
+    """
+    out: set[str] = set()
+    for py in compiler_src.rglob("*.py"):
+        if "__pycache__" in py.parts:
+            continue
+        if py.resolve() == Path(__file__).resolve():
+            continue
+        try:
+            out.update(_LITERAL.findall(py.read_text(encoding="utf-8", errors="ignore")))
+        except OSError:
+            continue
+    return out
+
+
+def _declared_fields(fm: Any) -> Iterable[str]:
+    """The top-level declared fields of a machine block.
+
+    Deliberately top-level only: the health question is whether the compiler consumes the
+    *fields an artifact declares*. A field's internal shape (nested data — layer names, paths,
+    enum values) is that field's own business, read structurally rather than by literal key
+    name, and flattening into it produces heuristic noise, not signal. (frontmatter is a
+    MappingProxyType, so accept any Mapping.)
+    """
+    if isinstance(fm, Mapping):
+        for k in fm.keys():
+            yield str(k)
+
+
+def check(nodes: Iterable[Any], schema_closed_prefixes: set[str], compiler_src: Path) -> HealthReport:
+    """Build the health report over compiled graph nodes."""
+    literals = _source_literals(compiler_src)
+    # Fail safe: a real compiler source has thousands of literals. If the scan finds far fewer,
+    # source is not introspectable (e.g. installed without .py) and every field would falsely
+    # read as unconsumed — so report nothing rather than a spurious alarm.
+    if len(literals) < 200:
+        return HealthReport(by_kind={})
+    by_kind: dict[str, KindReport] = defaultdict(KindReport)
+    for node in nodes:
+        code = getattr(node, "artifact_code", "") or ""
+        prefix = code.split("_", 1)[0]
+        if not prefix or prefix in schema_closed_prefixes:
+            continue  # schema-closed kinds are already guaranteed; skip
+        # imported artifacts were authored elsewhere — not this build's declaration surface
+        if (getattr(node, "metadata", None) or {}).get("imported"):
+            continue
+        descriptor = REGISTRY.descriptor(prefix)
+        is_declarative = descriptor is not None and descriptor.disposition == DECLARATIVE
+        fm = getattr(node, "frontmatter", None) or {}
+        for leaf in set(_declared_fields(fm)):
+            # A DECLARED disposition outranks the heuristic scan: if the key is known to be
+            # consumed outside the compiler, an incidental literal match inside it proves nothing.
+            if (prefix, leaf) in _DOWNSTREAM_CONSUMERS:
+                by_kind[prefix].preserved[leaf] = _DOWNSTREAM_CONSUMERS[(prefix, leaf)]
+            elif leaf in literals:
+                by_kind[prefix].consumed.add(leaf)
+            elif is_declarative:
+                # Machine Block §11: declared policy/reference data on a declarative kind, carried
+                # into the snapshot but not compiler-consumed — a legitimate *preserved* disposition.
+                by_kind[prefix].preserved[leaf] = _DECLARATIVE_POLICY
+            else:
+                by_kind[prefix].unconsumed.add(leaf)
+    return HealthReport(by_kind=dict(by_kind))
+
+
+def format_report(report: HealthReport, verbose: bool) -> list[str]:
+    """Render the diagnostic. Empty list = print nothing (clean, non-verbose)."""
+    if not report.by_kind:
+        return []
+    if not verbose:
+        if not report.has_candidates:
+            return []
+        n = report.candidate_unconsumed
+        return [f"⚠ Machine-block health: {n} candidate unconsumed key(s). "
+                f"Run with --verbose for details."]
+
+    lines = ["", "Machine-block health", "─" * 20]
+    consumed_total = 0
+    for kind in sorted(report.by_kind):
+        r = report.by_kind[kind]
+        consumed_total += len(r.consumed)
+        lines.append(f"Kind: {kind}")
+        for k in sorted(r.consumed):
+            lines.append(f"  ✓ {k}")
+        for k in sorted(r.preserved):
+            lines.append(f"  ○ {k}  (preserved — {r.preserved[k]})")
+        for k in sorted(r.unconsumed):
+            lines.append(f"  ⚠ {k}  (no detected compiler consumer)")
+    lines += [
+        "",
+        "Summary:",
+        f"  machine-block keys examined:  {report.examined}",
+        f"  consumed:                     {consumed_total}",
+        f"  preserved:                    {report.preserved_total}",
+        f"  candidate unconsumed:         {report.candidate_unconsumed}",
+        "",
+        "NOTE: census results are heuristic diagnostics. They do not affect compilation",
+        "      success, runtime behavior, or conformance. 'Preserved' fields either carry",
+        "      declared policy on a declarative kind (Machine Block §11) or name a consumer",
+        "      outside the compiler, which the source scan cannot see. A 'candidate' is a key",
+        "      on an executable kind with no consumer detected or declared anywhere — the",
+        "      strongest signal this census can give, though still not proof of disuse.",
+    ]
+    return lines

compiler/governance/__init__.py

@@ -0,0 +1,6 @@
+"""
+Governance integration.
+
+Graph legality enforcement — structural rules applied to the Graph.
+Used by S4 GOVERN to validate topology against constitutional constraints.
+"""

compiler/governance_engine/artifact_kinds.py

@@ -0,0 +1,221 @@
+"""ArtifactKindRegistry — the single source of truth for artifact-kind metadata.
+
+The compiler owns *how to process* artifact kinds; it must not scatter *what kinds exist* across a
+handful of disconnected dictionaries. This module replaces five maps that had drifted apart
+(`_TYPE_TO_KIND`, `_GOVERNANCE_PREFIXES`, the directory `type_map`, `INDEX_SECTION_BY_KIND`, and the
+per-build `artifact_types` whitelist) with one `ArtifactKindDescriptor` per type-prefix.
+
+Every consumer asks the registry a question instead of indexing a raw map:
+
+    registry.descriptor("ENTITY").materialization_directory   # "entities"
+    registry.node_kind("ENTITY")                              # "GOVERNANCE"
+    registry.canonical_type("GOVERNANCE", "ENTITY_BLOCK_V0")  # "ENTITY"
+
+Disposition separates the two axes `NodeKind` was conflating:
+  * EXECUTABLE  — participates in the execution topology (WF/CC/CT/CS/IN/RB/EV/AC/TI/TE)
+  * DECLARATIVE — inert definition the topology references (ENTITY/STRUCTURE/SCHEMA/CONSTITUTION/…)
+
+`node_kind` is a *string* (the `NodeKind` value), so this governance-layer module never imports the
+compiler's enum (dependency layering: compiler ← governance). The compiler maps the string to its
+`NodeKind` at its own boundary.
+
+This is `BuiltInArtifactRegistry` — the substrate bootstrap, exactly as a C compiler ships built-in
+lexical grammar. Step 4 promotes it to a governed protocol artifact: a `CompiledArtifactRegistry`
+loads the same `ArtifactKindDescriptor`s from the protocol surface, and *nothing downstream changes*
+— consumers still ask the registry the same questions. The descriptor fields below ARE that registry's
+schema, revealed by the first entity integration.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+EXECUTABLE = "EXECUTABLE"
+DECLARATIVE = "DECLARATIVE"
+
+# Governance Ontology (spec fragment 03) — both axes are CLOSED per ontology version.
+# §4 primary Semantic Category: exactly one per kind.
+DEFINITIONAL, NORMATIVE, CONTRACTUAL = "Definitional", "Normative", "Contractual"
+OPERATIONAL, PARTICIPATORY, EVIDENTIAL = "Operational", "Participatory", "Evidential"
+SEMANTIC_CATEGORIES = (DEFINITIONAL, NORMATIVE, CONTRACTUAL, OPERATIONAL, PARTICIPATORY, EVIDENTIAL)
+# §6 provenance: how the element came to exist. Semantic, not physical.
+AUTHORED, DERIVED, PRODUCED = "authored", "derived", "produced"
+PROVENANCES = (AUTHORED, DERIVED, PRODUCED)
+# §7 runtime disposition is a CATEGORY CONTRACT property, never stored per kind — it is derived
+# from the category so the two can never disagree. Distinct from the `disposition` field below,
+# which answers a different question (topology participation).
+_RUNTIME_DISPOSITION = {
+    DEFINITIONAL:  "not executable",
+    NORMATIVE:     "not executable",
+    CONTRACTUAL:   "not independently executable",
+    OPERATIONAL:   "executable",
+    PARTICIPATORY: "participates in execution",
+    EVIDENTIAL:    "produced by execution",
+}
+
+
+@dataclass(frozen=True)
+class ArtifactKindDescriptor:
+    """Everything the pipeline needs to know about one artifact kind. One object, not five maps."""
+    prefix: str                         # the artifact-code type token, e.g. "ENTITY", "CC", "STRUCTURE"
+    node_kind: str                      # NodeKind value (string): the topology classification
+    disposition: str                    # EXECUTABLE | DECLARATIVE — TOPOLOGY PARTICIPATION only.
+                                        # Not ontology §7 runtime disposition (see runtime_disposition).
+    materialization_directory: str | None = None   # output dir under artifacts/, or None if not materialized here
+    index_section: str | None = None    # kind_index section for this kind, or None if not indexed
+    canonical_keeps_prefix: bool = True # in canonical projection: keep this prefix vs collapse to node_kind
+    artifact_kind: str | None = None    # canonical in-block discriminator (Kind Vocabulary); None = not yet authorized
+    semantic_category: str | None = None  # Governance Ontology §4 primary category; None = kind not authorized
+    provenance: str | None = None         # Governance Ontology §6 provenance; None = kind not authorized
+
+    @property
+    def inspectable_source(self) -> bool:
+        return self.index_section is not None
+
+    @property
+    def runtime_disposition(self) -> str | None:
+        """Ontology §7 runtime disposition — derived from the category, never stored.
+
+        Distinct from `disposition`: a CAPABILITY_CONTRACT participates in the execution
+        topology (disposition == EXECUTABLE) yet is "not independently executable" (§7).
+        """
+        return _RUNTIME_DISPOSITION.get(self.semantic_category)
+
+
+def _d(prefix, node_kind, disposition, directory=None, index_section=None, keeps_prefix=True, ak=None,
+       category=None, provenance=None):
+    return ArtifactKindDescriptor(prefix, node_kind, disposition, directory, index_section, keeps_prefix, ak,
+                                  category, provenance)
+
+
+# The complete built-in table. Values are the EXACT union of the five legacy maps, so the registry is
+# behavior-identical. EXECUTABLE kinds keep their prefix in canonical (node_kind == prefix); DECLARATIVE
+# kinds that ride NodeKind.GOVERNANCE keep their prefix only when listed (the old _GOVERNANCE_PREFIXES),
+# else they collapse to "GOVERNANCE".
+_DESCRIPTORS: tuple[ArtifactKindDescriptor, ...] = (
+    # EXECUTABLE — execution topology
+    _d("WF", "WF", EXECUTABLE, "workflows", "workflows", ak="WORKFLOW",
+       category=OPERATIONAL, provenance=AUTHORED),
+    _d("CC", "CC", EXECUTABLE, "capability_contracts", "capability_contracts", ak="CAPABILITY_CONTRACT",
+       category=CONTRACTUAL, provenance=AUTHORED),
+    _d("CT", "CT", EXECUTABLE, "capability_transforms", "capability_transforms", ak="CAPABILITY_TRANSFORM",
+       category=OPERATIONAL, provenance=AUTHORED),
+    _d("CS", "CS", EXECUTABLE, "capability_side_effects", "capability_side_effects", ak="CAPABILITY_SIDE_EFFECT",
+       category=OPERATIONAL, provenance=AUTHORED),
+    _d("IN", "IN", EXECUTABLE, "intents", "intents", ak="INTENT",
+       category=OPERATIONAL, provenance=AUTHORED),
+    _d("TI", "TI", EXECUTABLE, "ingress_intents", ak="TRANSPORT_INGRESS",
+       category=CONTRACTUAL, provenance=AUTHORED),
+    _d("TE", "TE", EXECUTABLE, "transport/egress", ak="TRANSPORT_EGRESS",
+       category=CONTRACTUAL, provenance=AUTHORED),
+    _d("RB", "RB", EXECUTABLE, "runtime_bindings", "runtime_bindings", ak="RUNTIME_BINDING",
+       category=OPERATIONAL, provenance=AUTHORED),
+    # EVENT: the *kind* is an authored declaration of an event type (schema + trigger). The
+    # produced elements — event occurrences and trace records — belong to the runtime evidence
+    # model, not the artifact-kind ontology, so no kind carries provenance `produced`.
+    _d("EV", "EV", EXECUTABLE, "events", ak="EVENT",
+       category=EVIDENTIAL, provenance=AUTHORED),
+    _d("AC", "AC", EXECUTABLE, "actors", ak="ACTOR",
+       category=PARTICIPATORY, provenance=AUTHORED),
+    # DECLARATIVE — own NodeKind
+    _d("ASSERT", "ASSERT", DECLARATIVE, "assertions", ak="ASSERT",
+       category=NORMATIVE, provenance=DERIVED),
+    _d("TEST_DATA", "TEST_DATA", DECLARATIVE),
+    # DECLARATIVE — ride NodeKind.GOVERNANCE, keep their prefix (old _GOVERNANCE_PREFIXES)
+    _d("INVARIANT", "GOVERNANCE", DECLARATIVE, "invariants", ak="INVARIANT",
+       category=NORMATIVE, provenance=AUTHORED),
+    _d("VOCAB", "GOVERNANCE", DECLARATIVE, "vocabulary", ak="VOCABULARY",
+       category=DEFINITIONAL, provenance=AUTHORED),
+    _d("CONSTITUTION", "GOVERNANCE", DECLARATIVE, "concerns", ak="CONSTITUTION",
+       category=NORMATIVE, provenance=AUTHORED),
+    _d("SCHEMA", "GOVERNANCE", DECLARATIVE, "schemas"),
+    _d("STRUCTURE", "GOVERNANCE", DECLARATIVE, "structures", ak="STRUCTURE",
+       category=DEFINITIONAL, provenance=AUTHORED),
+    _d("SURFACE", "GOVERNANCE", DECLARATIVE, "surface_contracts", ak="SURFACE_CONTRACT",
+       category=CONTRACTUAL, provenance=AUTHORED),
+    _d("ENTITY", "GOVERNANCE", DECLARATIVE, "entities", "entities", ak="ENTITY"),
+    # DECLARATIVE — ride NodeKind.GOVERNANCE, collapse to "GOVERNANCE" in canonical (not in old prefixes)
+    _d("LAYER", "GOVERNANCE", DECLARATIVE, keeps_prefix=False),
+    _d("GOVERNANCE", "GOVERNANCE", DECLARATIVE, keeps_prefix=False),
+)
+
+
+class BuiltInArtifactRegistry:
+    """The substrate bootstrap registry. Step 4 swaps in a CompiledArtifactRegistry with the same API."""
+
+    def __init__(self, descriptors: tuple[ArtifactKindDescriptor, ...] = _DESCRIPTORS):
+        self._by_prefix = {d.prefix: d for d in descriptors}
+        # Authoritative index: canonical artifact_kind -> descriptor (Machine Block §6).
+        self._by_kind = {d.artifact_kind: d for d in descriptors if d.artifact_kind}
+
+    def descriptor(self, prefix: str) -> ArtifactKindDescriptor | None:
+        return self._by_prefix.get(prefix)
+
+    def descriptor_for_kind(self, artifact_kind: str) -> ArtifactKindDescriptor | None:
+        """Resolve a descriptor by its canonical `artifact_kind` — the authoritative discriminator."""
+        return self._by_kind.get(artifact_kind)
+
+    def node_kind_for_kind(self, artifact_kind: str) -> str | None:
+        """NodeKind (string) for a canonical `artifact_kind`; None if the kind is unknown."""
+        d = self._by_kind.get(artifact_kind)
+        return d.node_kind if d else None
+
+    def known(self, prefix: str) -> bool:
+        return prefix in self._by_prefix
+
+    def node_kind(self, prefix: str) -> str | None:
+        d = self._by_prefix.get(prefix)
+        return d.node_kind if d else None
+
+    def directory(self, prefix: str) -> str:
+        """Output directory for a type prefix. Raises ValueError (legacy contract) if unmapped."""
+        d = self._by_prefix.get(prefix)
+        if d is None or d.materialization_directory is None:
+            valid = sorted(p for p, x in self._by_prefix.items() if x.materialization_directory)
+            raise ValueError(f"Unknown artifact type prefix: {prefix}\nValid prefixes: {', '.join(valid)}")
+        return d.materialization_directory
+
+    def semantic_category(self, artifact_kind: str) -> str | None:
+        """Governance Ontology §4 primary category for a canonical `artifact_kind`."""
+        d = self._by_kind.get(artifact_kind)
+        return d.semantic_category if d else None
+
+    def provenance(self, artifact_kind: str) -> str | None:
+        """Governance Ontology §6 provenance for a canonical `artifact_kind`."""
+        d = self._by_kind.get(artifact_kind)
+        return d.provenance if d else None
+
+    def runtime_disposition(self, artifact_kind: str) -> str | None:
+        """Ontology §7 runtime disposition for a canonical `artifact_kind`."""
+        d = self._by_kind.get(artifact_kind)
+        return d.runtime_disposition if d else None
+
+    def ontology_coverage(self) -> dict[str, tuple[str | None, str | None]]:
+        """Every authorized kind → (category, provenance). Ontology §11 conformance input."""
+        return {k: (d.semantic_category, d.provenance) for k, d in sorted(self._by_kind.items())}
+
+    def index_section(self, prefix: str) -> str | None:
+        d = self._by_prefix.get(prefix)
+        return d.index_section if d else None
+
+    def index_sections(self) -> dict[str, str]:
+        """Prefix → kind_index section, for every indexed kind."""
+        return {p: d.index_section for p, d in self._by_prefix.items() if d.index_section}
+
+    def canonical_type(self, node_kind: str, artifact_code: str) -> str:
+        """The artifact_type written into the canonical projection (replaces _resolve_artifact_type).
+
+        Non-GOVERNANCE node kinds: the node_kind IS the prefix. GOVERNANCE node kinds: keep the code's
+        prefix when the descriptor says so (old _GOVERNANCE_PREFIXES), else collapse to "GOVERNANCE".
+        """
+        if node_kind != "GOVERNANCE":
+            return node_kind
+        for d in self._by_prefix.values():
+            if d.node_kind == "GOVERNANCE" and d.canonical_keeps_prefix \
+                    and artifact_code.startswith(d.prefix + "_"):
+                return d.prefix
+        return node_kind
+
+
+# The process-wide built-in registry. Import this; never re-create raw maps.
+REGISTRY = BuiltInArtifactRegistry()