pgc-assembler 2.0.0__py3-none-any.whl

assembler/VERSION

@@ -0,0 +1 @@
+14

assembler/__init__.py

@@ -0,0 +1,27 @@
+"""PGC Snapshot Assembler — composes compiled projections into a manifest-pinned snapshot.
+
+Contract: snapshot_assembler/doc/SNAPSHOT_ASSEMBLY_CONTRACT.md
+"""
+
+from pathlib import Path
+
+
+def _release() -> str:
+    """The composition's release ordinal, read from the repo's single version declaration.
+
+    PGC versions the *composition*, not each repo independently: all repos are released together
+    and the governance closure forces lockstep, so a monotonic integer names which composition a
+    repo belongs to. `VERSION` is the sole declaration — pyproject derives it, and so does this.
+    Never restate it as a literal; two statements of one fact is how they drift apart.
+    """
+    # Source tree and editable installs: the repo-root VERSION is authoritative.
+    declared = Path(__file__).resolve().parent.parent / "VERSION"
+    if declared.is_file():
+        return declared.read_text(encoding="utf-8").strip()
+    # Installed wheel: no repo root. The ordinal is staged into the package at
+    # build time by _build_hook.py — a build artifact, not a second declaration.
+    return (Path(__file__).resolve().parent / "VERSION").read_text(encoding="utf-8").strip()
+
+
+ASSEMBLER_VERSION = _release()   # derived from VERSION — never edited here
+MANIFEST_VERSION = "v0"

assembler/cli.py

@@ -0,0 +1,112 @@
+"""
+cli.py — PGC snapshot assembler CLI.
+
+    assemble   — compose compiled projections into the assembled snapshot + manifest,
+                 then run Composition Conformance over the result
+    verify     — verify an assembled snapshot against its manifest (root of trust)
+    conform    — run Composition Conformance alone against an assembled snapshot
+
+Assembly and Composition Conformance are distinct lifecycle phases, not one step: the assembler
+composes and proves identity; the conformance phase proves governance properties of the
+composition. `assemble` runs both because an unproven snapshot should never be left on disk
+looking finished — but each is separately invocable, and neither implements the other.
+
+Paths are explicit or resolved from documented sibling defaults. No cwd guessing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from assembler import conformance, core
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="snapshot_assembler", description="PGC snapshot assembler")
+    subs = p.add_subparsers(dest="command", required=True)
+
+    a = subs.add_parser("assemble", help="Compose compiled projections into the assembled snapshot")
+    a.add_argument(
+        "--source", action="append", required=True, metavar="COMPILED_ROOT",
+        help="A compiler compiled/ root (repeatable). e.g. .../software_governance/snapshot/compiled",
+    )
+    a.add_argument(
+        "--out", required=True, metavar="SNAPSHOT_DIR",
+        help="Assembled snapshot output dir (the product). e.g. .../protocol-governed-computing/snapshot",
+    )
+    a.add_argument(
+        "--profile", default=os.environ.get("PGC_SNAPSHOT_PROFILE", ""), metavar="PROFILE_IDENTITY",
+        help="The profile identity this snapshot claims (3b SN-5). Required; a snapshot that claims "
+             "none cannot have clause 4 of 3b §7 evaluated about it.",
+    )
+
+    v = subs.add_parser("verify", help="Verify an assembled snapshot against its manifest")
+    v.add_argument("--out", required=True, metavar="SNAPSHOT_DIR", help="Assembled snapshot dir to verify")
+
+    c = subs.add_parser("conform", help="Run Composition Conformance against an assembled snapshot")
+    c.add_argument("--out", required=True, metavar="SNAPSHOT_DIR", help="Assembled snapshot dir to check")
+
+    return p
+
+
+def _fatal(msg: str) -> None:
+    print(f"[assembler] Error: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def main() -> None:
+    args = _build_parser().parse_args()
+
+    if args.command == "assemble":
+        source_roots = [Path(s).resolve() for s in args.source]
+        out_root = Path(args.out).resolve()
+        for s in source_roots:
+            if not s.is_dir():
+                _fatal(f"source root is not a directory: {s}")
+        try:
+            manifest = core.assemble(source_roots, out_root, args.profile)
+            core.verify_snapshot(out_root)  # round-trip self-check
+        except core.AssemblyError as exc:
+            _fatal(str(exc))
+
+        doms = [d["domain"] for d in manifest["domains"]]
+        print(f"[assembler] Assembled {len(doms)} domain(s): {', '.join(doms)}")
+        print(f"[assembler] snapshot_id: {manifest['snapshot_id']}")
+        print(f"[assembler] out:         {out_root}")
+        print(f"[assembler] manifest:    {out_root / 'manifest.json'}")
+        print("[assembler] round-trip verify: OK")
+
+        # Composition Conformance — a separate phase over the composed snapshot.
+        try:
+            ev = conformance.check_composition(out_root)
+        except conformance.ConformanceError as exc:
+            _fatal(str(exc))
+        print(f"[conformance] composition: {ev['status']} "
+              f"({ev['rules_evaluated']} rule(s) over {ev['artifacts_examined']} artifacts)")
+
+    elif args.command == "verify":
+        out_root = Path(args.out).resolve()
+        try:
+            manifest = core.verify_snapshot(out_root)
+        except core.AssemblyError as exc:
+            _fatal(str(exc))
+        print(f"[assembler] VERIFIED  snapshot_id={manifest['snapshot_id']}")
+        print(f"[assembler] domains: {json.dumps([d['domain'] for d in manifest['domains']])}")
+
+    elif args.command == "conform":
+        out_root = Path(args.out).resolve()
+        try:
+            ev = conformance.check_composition(out_root)
+        except conformance.ConformanceError as exc:
+            _fatal(str(exc))
+        print(f"[conformance] {ev['status']}  snapshot_id={ev['snapshot_id']}")
+        for f in ev["findings"]:
+            print(f"  {f['status']:<7} {f['invariant']:<58} {f['message']}")
+
+
+if __name__ == "__main__":
+    main()

assembler/conformance.py

@@ -0,0 +1,246 @@
+"""
+conformance.py — Composition Conformance: the lifecycle phase after assembly.
+
+    compiler → verified domain → assembler → composed snapshot
+        → COMPOSITION CONFORMANCE → attested snapshot
+
+A domain is verified in isolation, against the governance surface it imported. Properties that
+only exist once independently-governed domains are composed have no earlier enforcement point:
+the compiler sees one domain at a time and never holds a snapshot, and the assembler is a
+composition *engine* — it proves identity and integrity, not governance. This phase proves
+properties **of the composition**.
+
+Remit (the permanent home for this class of check):
+  * evaluate snapshot-scoped invariants          [implemented]
+  * verify profile uniqueness                    [implemented — via declared composition_check]
+  * verify cross-domain uniqueness               [remit, not yet declared]
+  * verify implementation resolvability          [remit, not yet declared]
+  * verify composition contracts                 [remit, not yet declared]
+  * emit composition evidence                    [implemented]
+  * fail hard                                    [implemented]
+
+Two boundaries this module must keep:
+
+  1. **No dependency on the compiler.** Rules are read from the assembled snapshot's own canonical
+     invariants, never from the compiler's handler registry. The phase is a peer of the compiler,
+     not a client of it.
+  2. **No implementation semantics in the declaration.** An invariant declares a language-neutral
+     `composition_check` — a selector plus a cardinality rule. It does not name a handler, module,
+     or callable. Evaluating a declaration is this module's job; *being* one is the artifact's.
+
+Admission is by declaration: an invariant participates iff it declares
+`assert_projection.composition_check`. Nothing here enumerates which invariants exist.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from assembler import ASSEMBLER_VERSION
+
+CONFORMANCE_VERSION = "v0"
+
+# Cardinality rules this phase can evaluate. Extending the vocabulary is a declaration act in
+# SCHEMA_INVARIANT_V0 plus one entry here — never a special case inside an evaluator.
+_CARDINALITY = {
+    "exactly_one": lambda n: n == 1,
+    "at_least_one": lambda n: n >= 1,
+    "at_most_one": lambda n: n <= 1,
+    "none": lambda n: n == 0,
+}
+
+# What each rule requires, phrased for a diagnostic. A rule whose violation message described a
+# different rule would send a reader looking for the wrong defect.
+_REQUIREMENT = {
+    "exactly_one": "exactly one is required",
+    "at_least_one": "at least one is required",
+    "at_most_one": "at most one may be present",
+    "none": "none may be present",
+}
+
+
+class ConformanceError(RuntimeError):
+    """Raised when the composed snapshot violates a composition-scoped invariant. Fail hard."""
+
+
+@dataclass(frozen=True)
+class Finding:
+    invariant: str
+    subject: str
+    rule: str
+    status: str          # PASSED | FAILED
+    examined: int        # artifacts the selector matched — recorded so a vacuous check is visible
+    matched: list[str]   # fqdn_ids of the matched artifacts
+    message: str
+
+
+def _read_json(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ConformanceError(f"unreadable snapshot artifact {path}: {exc}") from exc
+
+
+# ---------------------------------------------------------------------------
+# Rule discovery — declared, never enumerated
+# ---------------------------------------------------------------------------
+
+def _canonical_artifacts(out_root: Path) -> list[dict]:
+    """Every canonical artifact in the composed snapshot, across all domains."""
+    canonical = out_root / "canonical"
+    if not canonical.is_dir():
+        raise ConformanceError(f"no canonical/ in snapshot: {out_root}")
+    return [_read_json(p) for p in sorted(canonical.glob("*/*/*.json"))
+            if p.name != "metadata.json"]
+
+
+def _composition_rules(artifacts: list[dict]) -> list[tuple[str, dict]]:
+    """(invariant_fqdn, composition_check) for every invariant declaring one.
+
+    Read from the assembled snapshot itself, so the rules enforced are exactly the rules the
+    composition carries — a domain cannot be checked against governance it did not compile under.
+    """
+    rules = []
+    for a in artifacts:
+        if a.get("artifact_type") != "INVARIANT":
+            continue
+        proj = (a.get("frontmatter", {}) or {}).get("assert_projection", {}) or {}
+        check = proj.get("composition_check")
+        if check:
+            rules.append((a.get("fqdn_id", a.get("artifact_code", "?")), check))
+    return sorted(rules)
+
+
+# ---------------------------------------------------------------------------
+# Evaluation
+# ---------------------------------------------------------------------------
+
+def _declared(frontmatter: dict, path: str) -> Any:
+    """Read a declaration field by dotted path — `status`, or `handler.kind`.
+
+    A generalization of exact-match, not a special case: a single-segment path is the flat lookup
+    it always was. Nested declarations are ordinary structure in an artifact, and a selector that
+    could only reach the top level would force rules to be phrased against naming conventions
+    instead of against what an artifact actually declares.
+
+    A path that does not resolve yields None, which matches nothing — absence is not equality.
+    """
+    node: Any = frontmatter
+    for segment in path.split("."):
+        if not isinstance(node, dict):
+            return None
+        node = node.get(segment)
+    return node
+
+
+def _matches(artifact: dict, selector: dict) -> bool:
+    """All declared selector fields must match. Unknown fields are a hard failure, not a pass."""
+    for field, expected in selector.items():
+        if field == "namespace":
+            if artifact.get("namespace") != expected:
+                return False
+        elif field == "artifact_type":
+            if artifact.get("artifact_type") != expected:
+                return False
+        elif field == "artifact_code_prefix":
+            if not str(artifact.get("artifact_code", "")).startswith(expected):
+                return False
+        elif field == "where":
+            fm = artifact.get("frontmatter", {}) or {}
+            for key, value in expected.items():
+                if _declared(fm, key) != value:
+                    return False
+        else:
+            raise ConformanceError(
+                f"unknown composition_check selector field {field!r} — the declaration is admissible "
+                f"only if every field has an evaluator (no silent skip)"
+            )
+    return True
+
+
+def _evaluate(invariant: str, check: dict, artifacts: list[dict]) -> Finding:
+    rule = check.get("rule")
+    predicate = _CARDINALITY.get(rule)
+    if predicate is None:
+        raise ConformanceError(
+            f"{invariant}: unknown composition_check rule {rule!r} "
+            f"(known: {', '.join(sorted(_CARDINALITY))})"
+        )
+    selector = check.get("selector") or {}
+    if not selector:
+        raise ConformanceError(f"{invariant}: composition_check declares an empty selector")
+
+    matched = sorted(a.get("fqdn_id", a.get("artifact_code", "?"))
+                     for a in artifacts if _matches(a, selector))
+    subject = check.get("subject", "artifact")
+    ok = predicate(len(matched))
+    if ok:
+        message = f"{rule}: found {len(matched)} {subject}"
+    elif len(matched) == 0:
+        message = (f"{rule} violated: no {subject} found in the composed snapshot. "
+                   f"The composition declares none; {_REQUIREMENT[rule]}.")
+    else:
+        plural = subject if subject.endswith("s") else f"{subject}s"
+        message = (f"{rule} violated: {len(matched)} competing {plural} in the composed snapshot "
+                   f"— {', '.join(matched)}. Independently-governed domains have each declared one; "
+                   f"exactly one may be active across the whole composition.")
+    return Finding(
+        invariant=invariant, subject=subject, rule=rule,
+        status="PASSED" if ok else "FAILED",
+        examined=len(matched), matched=matched, message=message,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Phase entry point
+# ---------------------------------------------------------------------------
+
+def check_composition(out_root: Path) -> dict[str, Any]:
+    """Run Composition Conformance over an assembled snapshot.
+
+    Emits composition evidence to `conformance/composition.json` and raises ConformanceError on
+    any violation. Evidence is written before raising: a failed composition must leave a record
+    of *why* it failed, not just a non-zero exit.
+    """
+    artifacts = _canonical_artifacts(out_root)
+    rules = _composition_rules(artifacts)
+    findings = [_evaluate(fqdn, check, artifacts) for fqdn, check in rules]
+    failed = [f for f in findings if f.status == "FAILED"]
+
+    manifest_path = out_root / "manifest.json"
+    manifest = _read_json(manifest_path) if manifest_path.is_file() else {}
+
+    evidence = {
+        "conformance_version": CONFORMANCE_VERSION,
+        "assembler_version": ASSEMBLER_VERSION,
+        "phase": "composition_conformance",
+        "snapshot_id": manifest.get("snapshot_id"),
+        "domains": [d.get("domain") for d in manifest.get("domains", [])],
+        "artifacts_examined": len(artifacts),
+        "rules_evaluated": len(findings),
+        "status": "FAILED" if failed else "PASSED",
+        "findings": [
+            {
+                "invariant": f.invariant, "subject": f.subject, "rule": f.rule,
+                "status": f.status, "examined": f.examined,
+                "matched": f.matched, "message": f.message,
+            }
+            for f in findings
+        ],
+        "checked_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    out_dir = out_root / "conformance"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    (out_dir / "composition.json").write_text(json.dumps(evidence, indent=2) + "\n", encoding="utf-8")
+
+    if failed:
+        detail = "\n".join(f"  [{f.invariant}] {f.message}" for f in failed)
+        raise ConformanceError(
+            f"composition conformance FAILED — {len(failed)} of {len(findings)} "
+            f"composition-scoped invariant(s) violated:\n{detail}"
+        )
+    return evidence