pgc-assembler 3.0.0__tar.gz → 5.0.0__tar.gz

{pgc_assembler-3.0.0/pgc_assembler.egg-info → pgc_assembler-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgc-assembler
-Version: 3.0.0
+Version: 5.0.0
 Summary: PGC snapshot assembler — composes compiled projections into a manifest-pinned executable snapshot (import package: assembler)
 Author-email: Bhash Ganti <bachipeachy@gmail.com>
 License-Expression: Apache-2.0
@@ -21,6 +21,8 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: pyyaml
+Provides-Extra: signing
+Requires-Dist: cryptography>=42; extra == "signing"
 Dynamic: license-file
 
 # snapshot_assembler
@@ -40,8 +42,10 @@ repos → protocol_compiler → each repo's compiled/ projections
 ```
 
 The platform is an ordinary member of the composition — no singleton branch. The composition
-currently assembles **seven domains**: `platform`, `workload`, `inspection`, `transformation`,
-and the business domains `ai_governance`, `blockchain` and `book_library_mgmt`.
+currently assembles **eight domains**: `platform`, `workload`, `inspection`, `transformation`,
+and the business domains `ai_governance`, `blockchain`, `book_library_mgmt` and
+`causal_language_model`. A deliberately narrower composition is assembled by naming its roots in
+`PGC_SOURCE_ROOTS`.
 
 ## Install
 
@@ -132,8 +136,18 @@ export PGC_PLATFORM_ROOT=$PWD/software_governance
 pgc            # reports what is installed and whether the anchor resolves
 ```
 
-`PGC_BUILD_ROOT` (compiled output, keeping the governance repo read-only) and `PGC_DOMAIN_ROOTS`
-(additional domains contributing their own `registry/structures`) are optional.
+`PGC_DOMAIN_ROOTS` names an additional domain contributing its own `registry/structures` — the
+directory that *directly contains* it, not the repository above it; pointing one level too high is a
+silent no-op. Where compiled output is written is declared by each build configuration
+(`output_configuration.root`), not by the environment. `PGC_SNAPSHOT_PROFILES` is the directory
+holding snapshot profiles, required by the assembler and the runtime alike. A snapshot's identity
+covers the content of the profile it claims, so the profiles a node reads must be the ones it was
+sealed against.
+
+`PGC_BUILD_ROOT` is accepted and reported and **nothing reads it**.
+
+The full sequence, with the repositories it needs, is in
+[`pgc_install`](https://github.com/protocol-governed-computing/pgc_install).
 
 **Versioning.** Two schemes, and the published version follows the second.
 
@@ -143,7 +157,7 @@ pgc            # reports what is installed and whether the anchor resolves
   cycle is tagged `release-<N>`. This is not published.
 - **Public** — `PUBLIC_VERSION`, tagged on every component repository. The platform is at **`v3`**.
 
-**The published version is the public one: `v3` is `3.0.0`.** The standard the packages implement is a
+**The published version is the public one: `v4` is `4.0.0`.** The standard the packages implement is a
 separate artifact on its own track and is not this number.
 
 The standard these packages implement is published separately: https://doi.org/10.5281/zenodo.22150616

{pgc_assembler-3.0.0 → pgc_assembler-5.0.0}/README.md

@@ -15,8 +15,10 @@ repos → protocol_compiler → each repo's compiled/ projections
 ```
 
 The platform is an ordinary member of the composition — no singleton branch. The composition
-currently assembles **seven domains**: `platform`, `workload`, `inspection`, `transformation`,
-and the business domains `ai_governance`, `blockchain` and `book_library_mgmt`.
+currently assembles **eight domains**: `platform`, `workload`, `inspection`, `transformation`,
+and the business domains `ai_governance`, `blockchain`, `book_library_mgmt` and
+`causal_language_model`. A deliberately narrower composition is assembled by naming its roots in
+`PGC_SOURCE_ROOTS`.
 
 ## Install
 
@@ -107,8 +109,18 @@ export PGC_PLATFORM_ROOT=$PWD/software_governance
 pgc            # reports what is installed and whether the anchor resolves
 ```
 
-`PGC_BUILD_ROOT` (compiled output, keeping the governance repo read-only) and `PGC_DOMAIN_ROOTS`
-(additional domains contributing their own `registry/structures`) are optional.
+`PGC_DOMAIN_ROOTS` names an additional domain contributing its own `registry/structures` — the
+directory that *directly contains* it, not the repository above it; pointing one level too high is a
+silent no-op. Where compiled output is written is declared by each build configuration
+(`output_configuration.root`), not by the environment. `PGC_SNAPSHOT_PROFILES` is the directory
+holding snapshot profiles, required by the assembler and the runtime alike. A snapshot's identity
+covers the content of the profile it claims, so the profiles a node reads must be the ones it was
+sealed against.
+
+`PGC_BUILD_ROOT` is accepted and reported and **nothing reads it**.
+
+The full sequence, with the repositories it needs, is in
+[`pgc_install`](https://github.com/protocol-governed-computing/pgc_install).
 
 **Versioning.** Two schemes, and the published version follows the second.
 
@@ -118,7 +130,7 @@ pgc            # reports what is installed and whether the anchor resolves
   cycle is tagged `release-<N>`. This is not published.
 - **Public** — `PUBLIC_VERSION`, tagged on every component repository. The platform is at **`v3`**.
 
-**The published version is the public one: `v3` is `3.0.0`.** The standard the packages implement is a
+**The published version is the public one: `v4` is `4.0.0`.** The standard the packages implement is a
 separate artifact on its own track and is not this number.
 
 The standard these packages implement is published separately: https://doi.org/10.5281/zenodo.22150616

pgc_assembler-5.0.0/VERSION

@@ -0,0 +1 @@
+17

pgc_assembler-5.0.0/assembler/VERSION

@@ -0,0 +1 @@
+17

{pgc_assembler-3.0.0 → pgc_assembler-5.0.0}/assembler/__init__.py

@@ -1,6 +1,6 @@
 """PGC Snapshot Assembler — composes compiled projections into a manifest-pinned snapshot.
 
-Contract: snapshot_assembler/doc/SNAPSHOT_ASSEMBLY_CONTRACT.md
+Contract: snapshot_assembler/CONTRACT.md
 """
 
 from pathlib import Path

{pgc_assembler-3.0.0 → pgc_assembler-5.0.0}/assembler/cli.py

@@ -22,7 +22,7 @@ import os
 import sys
 from pathlib import Path
 
-from assembler import conformance, core
+from assembler import conformance, core, signing
 
 
 def _build_parser() -> argparse.ArgumentParser:
@@ -44,9 +44,19 @@ def _build_parser() -> argparse.ArgumentParser:
              "none cannot have clause 4 of 3b §7 evaluated about it.",
     )
 
+    a.add_argument(
+        "--signing-key", metavar="PEM", default=None,
+        help="Private key authenticating the sealed snapshot's identity. The build machine "
+             "holds this and no node that executes a workflow does: a node able to sign can "
+             "mint a snapshot its peers would accept.")
+
     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")
 
+    k = subs.add_parser("keygen", help="Mint a signing keypair for a snapshot trust root")
+    k.add_argument("--private", required=True, metavar="PEM", help="Where to write the private half")
+    k.add_argument("--public", required=True, metavar="PEM", help="Where to write the public half")
+
     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")
 
@@ -58,6 +68,37 @@ def _fatal(msg: str) -> None:
     sys.exit(1)
 
 
+def _report_authentication(out_root: Path, snapshot_id: str) -> None:
+    """Report whether the snapshot is authenticated, and refuse where this party requires it.
+
+    A party holding a trust root is a party that requires one. Absent `PGC_TRUST_ROOT_PUBKEY`
+    this reports what it finds and refuses nothing: an unsigned snapshot is well-formed, and a
+    platform whose profile does not select signing must still verify. Holding an anchor is the
+    opt-in, and it lives outside the artifact being authenticated — which is also why the key
+    is read from here and never from the signature record.
+    """
+    anchor = os.environ.get("PGC_TRUST_ROOT_PUBKEY")
+    try:
+        record = signing.read_signature(out_root)
+    except signing.SignatureMalformed as exc:
+        _fatal(f"snapshot authentication: {exc}")
+
+    if not anchor:
+        state = (f"present, unchecked (signed under key {record.get('key_id', '?')})"
+                 if record else "absent")
+        print(f"[signing] {state} — set PGC_TRUST_ROOT_PUBKEY to require and check one")
+        return
+
+    if record is None:
+        _fatal("snapshot authentication: this party anchors a trust root and the snapshot "
+               "carries no signature. An unsigned snapshot is not one this party accepts.")
+    try:
+        key = signing.verify_identity(snapshot_id, record, Path(anchor))
+    except (signing.SignatureError, signing.SigningUnavailable, OSError) as exc:
+        _fatal(f"snapshot authentication: {type(exc).__name__}: {exc}")
+    print(f"[signing] AUTHENTICATED under trust root {key}")
+
+
 def main() -> None:
     args = _build_parser().parse_args()
 
@@ -88,6 +129,17 @@ def main() -> None:
         print(f"[conformance] composition: {ev['status']} "
               f"({ev['rules_evaluated']} rule(s) over {ev['artifacts_examined']} artifacts)")
 
+        # Signing follows sealing and never precedes it: what is authenticated is the identity
+        # the seal produced. A snapshot is sealed whether or not anyone signs it; a signature
+        # says who vouches for the one that was sealed.
+        if args.signing_key:
+            try:
+                record = signing.sign_identity(manifest["snapshot_id"], Path(args.signing_key))
+                path = signing.write_signature(out_root, record)
+            except (signing.SigningUnavailable, OSError, ValueError) as exc:
+                _fatal(f"signing failed: {exc}")
+            print(f"[signing] signed under key {record['key_id']} -> {path}")
+
     elif args.command == "verify":
         out_root = Path(args.out).resolve()
         try:
@@ -96,6 +148,20 @@ def main() -> None:
             _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']])}")
+        _report_authentication(out_root, manifest["snapshot_id"])
+
+    elif args.command == "keygen":
+        try:
+            private_pem, public_pem = signing.generate_keypair()
+        except signing.SigningUnavailable as exc:
+            _fatal(str(exc))
+        priv, pub = Path(args.private), Path(args.public)
+        priv.write_bytes(private_pem)
+        priv.chmod(0o600)
+        pub.write_bytes(public_pem)
+        print(f"[keygen] key_id:  {signing.key_id_from_public_pem(public_pem)}")
+        print(f"[keygen] private: {priv}  (build machine only — never on an executing node)")
+        print(f"[keygen] public:  {pub}   (each node holds this, from outside the snapshot)")
 
     elif args.command == "conform":
         out_root = Path(args.out).resolve()

{pgc_assembler-3.0.0 → pgc_assembler-5.0.0}/assembler/core.py

@@ -4,7 +4,7 @@ core.py — PGC snapshot assembly.
 Composes each domain's compiled projections (from the protocol compiler) into one
 executable snapshot + a content-derived, manifest-pinned identity.
 
-Contract: snapshot_assembler/doc/SNAPSHOT_ASSEMBLY_CONTRACT.md
+Contract: snapshot_assembler/CONTRACT.md
 
 Invariants enforced here:
   * The assembler INVENTS no per-domain identity — every hash is lifted verbatim from
@@ -182,7 +182,13 @@ def _identity_view(domains: list[dict]) -> list[dict]:
 # it is a determination ABOUT the snapshot, in the sense `3b` §7 means, and evidence rather than
 # content. That it is written inside the tree is a placement defect recorded in Task D; excluding it
 # here is what makes the tree honest about what it sealed, not a carve-out to make a check pass.
-POST_SEAL = ("conformance/",)
+# A signature is the same shape as a conformance result and joins this set for the same reason:
+# it is over `snapshot_id`, so it cannot exist before the identity does, and it records who
+# vouches for what was sealed rather than forming part of it. The placement defect noted above
+# applies to it equally — it is written inside the tree and is not of it. That is an existing
+# defect extended to a second file, not a new class of one, and not a carve-out invented to
+# admit signing: a signature that were a constituent would change the identity it signs.
+POST_SEAL = ("conformance/", "signature.json")
 
 
 def _is_post_seal(rel: str) -> bool:
@@ -190,7 +196,7 @@ def _is_post_seal(rel: str) -> bool:
 
 
 # What an attestation records rather than constitutes, per
-# `cryptographic_trust::CONSTITUTION_CRYPTOGRAPHIC_TRUST_V0`. The projection binding and the value
+# `cryptographic_trust::CONSTITUTION_CRYPTOGRAPHIC_TRUST_V1`. The projection binding and the value
 # over it are enforced by the runtime at boot and constitute the composition like any other content;
 # when the signing happened records something *about* it, is read by nothing, and changes on every
 # build. Counting it made a composition's identity a function of when it was built — two compiles of
@@ -242,16 +248,20 @@ def enumerate_constituents(out_root: Path) -> list[dict[str, str]]:
     return out
 
 
-def compute_snapshot_identity(domains: list[dict], constituents: list[dict], profile: str) -> str:
+def compute_snapshot_identity(domains: list[dict], constituents: list[dict], profile: str,
+                              profile_sha256: str) -> str:
     """The snapshot's identity, derived from content and covering every constituent (SN-2, SN-6).
 
-    Three inputs, and each is there for a stated reason:
+    Four inputs, and each is there for a stated reason:
 
       * the domains identity view — the semantic identity of what was compiled;
       * every constituent, by path and by a hash OF ITS BYTES — so that changing any carried file
         changes the identity, which is SN-2's totality clause;
       * the claimed profile — a self-description that claims a profile and does not cover the claim
-        would let the claim change without the identity changing (SN-5, SN-6).
+        would let the claim change without the identity changing (SN-5, SN-6);
+      * the claimed profile's content — the name alone let a profile be weakened, requirements
+        removed from it, without the identity of any snapshot claiming it changing. The digest is
+        taken over the profile's declaration (`profile_sha256`).
 
     Provenance is excluded and that exclusion is declared in the manifest's `identity_covers`.
     It is observational content (`3e` §5): `assembled_at` differs between two assemblies of identical
@@ -259,7 +269,8 @@ def compute_snapshot_identity(domains: list[dict], constituents: list[dict], pro
     SN-6. What SN-6 requires covered is the description's determinative content, which this is.
     """
     payload = json.dumps(
-        {"domains": _identity_view(domains), "constituents": constituents, "profile": profile},
+        {"domains": _identity_view(domains), "constituents": constituents, "profile": profile,
+         "profile_sha256": profile_sha256},
         sort_keys=True, separators=(",", ":"),
     )
     return hashlib.sha256(payload.encode("utf-8")).hexdigest()
@@ -326,6 +337,19 @@ def _profile_declaration(identity: str) -> dict[str, Any]:
         f"{root} — a claim nobody can read is not a claim (3b SN-7)")
 
 
+def profile_digest(profile: str) -> str:
+    """The digest of the claimed profile's declaration, as the identity covers it.
+
+    Taken over the `snapshot_profile` block in canonical form rather than over the file: what the
+    profile requires is its declaration, and a change to the prose around it changes nothing a
+    snapshot is checked against.
+    """
+    declared = _profile_declaration(profile)
+    return hashlib.sha256(
+        json.dumps(declared, sort_keys=True, separators=(",", ":"), default=str).encode("utf-8")
+    ).hexdigest()
+
+
 def verify_profile(out_root: Path, profile: str) -> list[str]:
     """What the claimed profile requires and the composition does not carry.
 
@@ -358,12 +382,6 @@ def verify_profile(out_root: Path, profile: str) -> list[str]:
     return unmet
 
 
-def compute_composite_hash(domains: list[dict]) -> str:
-    """sha256 over canonical-JSON of the identity view. Deterministic; timestamp-free."""
-    canonical = json.dumps(_identity_view(domains), sort_keys=True, separators=(",", ":"))
-    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
-
-
 # ---------------------------------------------------------------------------
 # Cross-domain FQDN uniqueness (per-domain vocabularies are independent address namespaces)
 # ---------------------------------------------------------------------------
@@ -521,7 +539,8 @@ def assemble(source_roots: list[Path], out_root: Path, profile: str) -> dict[str
     # `3b` §6 requires all five, with the enumeration total. It was four per domain; six top-level
     # constituents were carried and enumerated nowhere, which under §6 is undeclared content.
     constituents = enumerate_constituents(out_root)
-    snapshot_id = compute_snapshot_identity(domains, constituents, profile)
+    sealed_profile = profile_digest(profile)
+    snapshot_id = compute_snapshot_identity(domains, constituents, profile, sealed_profile)
     manifest = {
         "manifest_version": MANIFEST_VERSION,
         "snapshot_id": snapshot_id,
@@ -529,11 +548,14 @@ def assemble(source_roots: list[Path], out_root: Path, profile: str) -> dict[str
         # What the identity is taken over, declared so a party who did not build this snapshot can
         # recompute it without reading the assembler (AI-16). Provenance is excluded as observational
         # content (`3e` §5) — see compute_snapshot_identity.
-        "identity_covers": ["domains", "constituents", "profile"],
+        "identity_covers": ["domains", "constituents", "profile", "profile_sha256"],
         # Written after sealing and therefore outside what was sealed. Declared rather than silently
         # skipped, so a party recomputing the identity knows exactly what to exclude (AI-16).
         "post_seal": list(POST_SEAL),
         "profile": profile,
+        # What the claimed profile declared when this snapshot was sealed. Acceptance recomputes it
+        # from the profile as it now reads and refuses a difference.
+        "profile_sha256": sealed_profile,
         "domains": domains,
         "constituents": constituents,
         "provenance": _build_provenance(inputs, domains),
@@ -553,7 +575,9 @@ def assemble(source_roots: list[Path], out_root: Path, profile: str) -> dict[str
 # Kinds a domain build instantiates. MUST match the compiler's _inject_imported_governance
 # filter (compiler/stages/s1_extract.py): a governance invariant is imported into a domain iff
 # its applies_to_kinds intersects this set and it declares no layer/surface scope.
-_DOMAIN_INSTANTIATED = frozenset({"WF", "CC", "CS", "CT", "RB", "AC", "IN", "EV", "TI", "TE"})
+# TEST_DATA joined when transform vectors moved into the supplying domain's build
+# (conformance::CONSTITUTION_TEST_DATA_V2).
+_DOMAIN_INSTANTIATED = frozenset({"WF", "CC", "CS", "CT", "RB", "AC", "IN", "EV", "TI", "TE", "TEST_DATA"})
 
 
 def _recompute_governance_closure(out_root: Path, source_domain: str) -> tuple[str, int]:
@@ -681,7 +705,8 @@ def verify_snapshot(out_root: Path) -> dict[str, Any]:
       3. identity   — recomputed from the RECOMPUTED constituent hashes, compared to the identity
                       borne. Recomputing over recorded hashes detects a tampered manifest; only
                       recomputing over recomputed hashes detects a tampered constituent
-      4. profile    — the snapshot claims one
+      4. profile    — the snapshot claims one, and the profile it claims is the one it was sealed
+                      against: its declaration digests to the value the identity covers
 
     This previously compared recorded values to recorded values — manifest against metadata.json
     against attestation — which is transitive from construction and establishes nothing to a party
@@ -747,7 +772,20 @@ def verify_snapshot(out_root: Path) -> dict[str, Any]:
             + "; ".join(unmet[:5])
             + (f"; and {len(unmet) - 5} more" if len(unmet) > 5 else ""))
 
-    derived = compute_snapshot_identity(domains, recomputed, profile)
+    # The profile read now, not the digest the manifest carries: recomputing over the recorded value
+    # would accept a profile weakened after sealing, which is what covering its content is for.
+    sealed_profile = manifest.get("profile_sha256")
+    if not sealed_profile:
+        raise AssemblyError(
+            "manifest carries no profile_sha256 — the profile's content is not in the identity, so "
+            "a weakened profile could not be told from the one this snapshot was sealed against.")
+    current_profile = profile_digest(profile)
+    if current_profile != sealed_profile:
+        raise AssemblyError(
+            f"profile failure: {profile} now digests to {current_profile[:16]}…, and this snapshot "
+            f"was sealed against {sealed_profile[:16]}…. The profile it claims has changed since.")
+
+    derived = compute_snapshot_identity(domains, recomputed, profile, current_profile)
     borne = manifest.get("snapshot_id")
     if derived != borne:
         raise AssemblyError(
@@ -755,6 +793,17 @@ def verify_snapshot(out_root: Path) -> dict[str, Any]:
             f"{str(borne)[:16]}… (3b §7 clause 2, SN-2)."
         )
 
+    # The manifest states its identity twice. Both statements are the claim, so both are evaluated:
+    # checking one and not the other let a manifest carry two contradictory identities and be
+    # accepted — measured, not hypothesised. A self-description that disagrees with itself is not a
+    # self-description.
+    borne_composite = manifest.get("composite_hash")
+    if borne_composite != derived:
+        raise AssemblyError(
+            f"identity failure: derived {derived[:16]}… from content, snapshot's composite_hash "
+            f"bears {str(borne_composite)[:16]}… (3b §7 clause 2, SN-2)."
+        )
+
     # Copies of one identity across domains must agree (GC-12) — a composition obligation rather
     # than correspondence, and not subsumed by the four conditions above.
     _verify_copies_agree(out_root)

{pgc_assembler-3.0.0 → pgc_assembler-5.0.0}/assembler/indexes.py

@@ -35,8 +35,36 @@ SCHEMA_VERSION = "v0"
 # Shared readers over the consolidated snapshot
 # ---------------------------------------------------------------------------
 
+def _authoring_rank(doc: dict) -> int:
+    """How authoritative a canonical copy is for its identity. Higher wins.
+
+    One identity can be published by more than one domain. A domain that CONSUMES a platform
+    capability carries it as an execution binding — the compiler lifts the compiled node so the
+    capability is executable there, and the authoring stays platform-owned. Both copies are
+    canonical and both are legitimate; they are not interchangeable.
+
+    The binding copy is the authoring copy with the authored parts removed: `content_hash`,
+    `frontmatter` and the IR are identical, while `content` and `references` are empty and
+    `layer_code` names the consuming layer. So the copy that still carries authored content is the
+    authoring copy, and it is the one an identity must resolve to — `si.artifact.show` promises "the
+    published canonical artifact for an FQDN, as authored".
+
+    A binding copy also carries the `content_hash` of content it does not hold, which is the sharper
+    tell but not one to select on: a hash mismatch is a defect to report, not a discriminator.
+    """
+    return 1 if (doc.get("content") or "").strip() else 0
+
+
 def _load_canonical(out_root: Path) -> dict[str, dict]:
-    """fqdn → canonical artifact doc, across all domains (canonical/<domain>/<type>/*.json)."""
+    """fqdn → canonical artifact doc, across all domains (canonical/<domain>/<type>/*.json).
+
+    Where an identity is published more than once, the authoring copy wins (`_authoring_rank`).
+    Selecting by iteration order would resolve an identity by the alphabetical accident of its
+    consumer's domain name: `canonical/platform/` sorts before `canonical/workload/` and after
+    `canonical/blockchain/`, so last-write-wins returned the authoring copy for consumers named
+    early and the binding copy for consumers named late. Renaming a domain would then change what
+    an identity resolves to.
+    """
     canon = out_root / "canonical"
     docs: dict[str, dict] = {}
     if not canon.is_dir():
@@ -46,8 +74,12 @@ def _load_canonical(out_root: Path) -> dict[str, dict]:
             continue
         raw = json.loads(f.read_text(encoding="utf-8"))
         fqdn = raw.get("fqdn_id")
-        if fqdn and "::" in fqdn:
-            raw["_canonical_path"] = f.relative_to(out_root).as_posix()
+        if not fqdn or "::" not in fqdn:
+            continue
+        raw["_canonical_path"] = f.relative_to(out_root).as_posix()
+        held = docs.get(fqdn)
+        # Ties keep the first seen, so a sorted walk stays the tiebreak and the result is stable.
+        if held is None or _authoring_rank(raw) > _authoring_rank(held):
             docs[fqdn] = raw
     return docs
 

pgc_assembler-5.0.0/assembler/signing.py

@@ -0,0 +1,229 @@
+"""Snapshot authentication — a signature over a sealed snapshot's identity.
+
+Three things are kept apart here, and conflating any two of them defeats the purpose:
+
+    snapshot identity        `snapshot_id`, derived from what was sealed
+    snapshot authentication  a signature over that identity
+    trust anchor             a public key the verifying party holds, from outside the snapshot
+
+Verification is `Verify(K, I, sigma)` where **K comes from the node and never from the
+artifact**. A snapshot carrying the key that authenticates it is self-authenticating, which
+establishes nothing: whoever replaced the snapshot would replace the key with it. The
+`key_id` in a signature record exists only so a refusal can say *which* failure occurred —
+signed by a key this node does not anchor, versus signed badly. It MUST NOT be used to
+select a key.
+
+**What is signed is the identity, not the manifest.** The self-description sits outside the
+identity it declares, so signing the file would bind the signature to bytes the identity does
+not cover. And the record is a sidecar rather than a manifest field, because a sealed
+snapshot's manifest is written once and never rewritten.
+
+**Asymmetric by requirement, not by preference.** A profile requiring that a node able to
+verify is unable to sign rules out every shared-secret construction, whatever its strength.
+
+The dependency is an extra (`snapshot_assembler[signing]`) rather than a core requirement.
+Signing is something a profile selects; a platform whose profile does not select it should
+not acquire a cryptography dependency because the capability exists elsewhere. Absent the
+extra, this module refuses — it never degrades to an unsigned success.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+SIGNATURE_FILENAME = "signature.json"
+SIGNATURE_VERSION = "V0"
+ALGORITHM = "ed25519"
+
+# Fields recorded beside the signature that the signature does not cover. `signed_at` says
+# when signing happened; it is an accompanying fact, and covering it would make an identical
+# snapshot produce a different record on every run.
+ACCOMPANYING = ("signed_at",)
+
+
+class SigningUnavailable(RuntimeError):
+    """The signing extra is not installed. Never a reason to proceed unsigned."""
+
+
+class SignatureError(RuntimeError):
+    """Base for every refusal this module issues."""
+
+
+class SignatureAbsent(SignatureError):
+    """The snapshot carries no signature and the verifying party requires one."""
+
+
+class SignatureMalformed(SignatureError):
+    """A signature record exists and cannot be read as one."""
+
+
+class TrustRootMismatch(SignatureError):
+    """Signed by a key this party does not anchor. Distinct from a bad signature."""
+
+
+class SignatureInvalid(SignatureError):
+    """Anchored by the right key and the signature does not verify."""
+
+
+class IdentityMismatch(SignatureError):
+    """The signature authenticates an identity the snapshot does not claim."""
+
+
+def _ed25519():
+    """The primitives, or a refusal naming what to install.
+
+    Imported here rather than at module scope so that reading this module, and importing the
+    assembler at all, costs nothing when signing is not in use.
+    """
+    try:
+        from cryptography.hazmat.primitives import serialization
+        from cryptography.hazmat.primitives.asymmetric import ed25519
+    except ImportError as exc:  # pragma: no cover - exercised by absence, not by tests
+        raise SigningUnavailable(
+            "snapshot signing requires the 'signing' extra: "
+            "pip install 'snapshot-assembler[signing]'"
+        ) from exc
+    return serialization, ed25519
+
+
+def key_id(public_key_bytes: bytes) -> str:
+    """A short, stable name for a public key.
+
+    Identifies which anchor a record was produced under so that a refusal can distinguish a
+    key this party does not hold from a signature that does not verify. It is a label, never
+    a credential.
+    """
+    return hashlib.sha256(public_key_bytes).hexdigest()[:16]
+
+
+def key_id_from_public_pem(public_pem: bytes) -> str:
+    """The `key_id` of a PEM-encoded public key, for reporting at mint time."""
+    serialization, _ = _ed25519()
+    return key_id(_raw_public(serialization.load_pem_public_key(public_pem)))
+
+
+def generate_keypair() -> tuple[bytes, bytes]:
+    """A new Ed25519 pair as (private_pem, public_pem).
+
+    The private half belongs on the machine that seals snapshots and on no machine that
+    executes them: a node able to sign can mint a snapshot its peers would accept.
+    """
+    serialization, ed25519 = _ed25519()
+    private = ed25519.Ed25519PrivateKey.generate()
+    private_pem = private.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    public_pem = private.public_key().public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    return private_pem, public_pem
+
+
+def _raw_public(public_key) -> bytes:
+    serialization, _ = _ed25519()
+    return public_key.public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+
+
+def sign_identity(snapshot_id: str, private_key_path: Path) -> dict[str, Any]:
+    """Produce the signature record for a sealed snapshot's identity."""
+    serialization, _ = _ed25519()
+    private = serialization.load_pem_private_key(
+        Path(private_key_path).read_bytes(), password=None
+    )
+    signature = private.sign(snapshot_id.encode("utf-8"))
+    return {
+        "signature_version": SIGNATURE_VERSION,
+        "snapshot_id": snapshot_id,
+        "algorithm": ALGORITHM,
+        "key_id": key_id(_raw_public(private.public_key())),
+        "signature": base64.b64encode(signature).decode("ascii"),
+        "signed_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def write_signature(out_root: Path, record: dict[str, Any]) -> Path:
+    """Write the sidecar beside the manifest, leaving the manifest untouched."""
+    path = Path(out_root) / SIGNATURE_FILENAME
+    path.write_text(json.dumps(record, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return path
+
+
+def read_signature(out_root: Path) -> dict[str, Any] | None:
+    """The signature record, or None where the snapshot carries none."""
+    path = Path(out_root) / SIGNATURE_FILENAME
+    if not path.exists():
+        return None
+    try:
+        record = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise SignatureMalformed(f"{path} is not readable as JSON: {exc}") from exc
+    if not isinstance(record, dict):
+        raise SignatureMalformed(f"{path} does not carry a signature record")
+    return record
+
+
+def verify_identity(snapshot_id: str, record: dict[str, Any], public_key_path: Path) -> str:
+    """Verify a signature over a claimed identity against a party-supplied anchor.
+
+    Returns the `key_id` of the anchor on success. Raises one of this module's refusals
+    otherwise, each naming which of the four failures occurred: the record authenticates a
+    different identity, it was produced under a key this party does not anchor, the record is
+    unreadable, or it does not verify.
+
+    The anchor is the caller's. `record["key_id"]` is read only to report a mismatch.
+    """
+    serialization, ed25519 = _ed25519()
+
+    for field in ("snapshot_id", "algorithm", "signature"):
+        if field not in record:
+            raise SignatureMalformed(f"signature record carries no {field!r}")
+
+    if record["algorithm"] != ALGORITHM:
+        raise SignatureMalformed(
+            f"signature algorithm is {record['algorithm']!r}; this verifier knows {ALGORITHM!r}"
+        )
+
+    # Checked before the cryptography: a record that verifies over a different identity is
+    # valid and irrelevant, and reporting it as a bad signature would name the wrong fault.
+    if record["snapshot_id"] != snapshot_id:
+        raise IdentityMismatch(
+            f"signature authenticates {record['snapshot_id'][:16]}… and this snapshot claims "
+            f"{snapshot_id[:16]}…"
+        )
+
+    public = serialization.load_pem_public_key(Path(public_key_path).read_bytes())
+    if not isinstance(public, ed25519.Ed25519PublicKey):
+        raise SignatureMalformed(f"{public_key_path} is not an Ed25519 public key")
+    anchor = key_id(_raw_public(public))
+
+    borne = record.get("key_id")
+    if borne and borne != anchor:
+        raise TrustRootMismatch(
+            f"signed under key {borne} and this party anchors {anchor} — the signature may be "
+            f"sound and is not one this party accepts"
+        )
+
+    try:
+        signature = base64.b64decode(record["signature"], validate=True)
+    except (ValueError, TypeError) as exc:
+        raise SignatureMalformed(f"signature is not valid base64: {exc}") from exc
+
+    try:
+        public.verify(signature, snapshot_id.encode("utf-8"))
+    except Exception as exc:
+        raise SignatureInvalid(
+            f"signature over {snapshot_id[:16]}… does not verify under key {anchor}"
+        ) from exc
+
+    return anchor

{pgc_assembler-3.0.0 → pgc_assembler-5.0.0/pgc_assembler.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgc-assembler
-Version: 3.0.0
+Version: 5.0.0
 Summary: PGC snapshot assembler — composes compiled projections into a manifest-pinned executable snapshot (import package: assembler)
 Author-email: Bhash Ganti <bachipeachy@gmail.com>
 License-Expression: Apache-2.0
@@ -21,6 +21,8 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: pyyaml
+Provides-Extra: signing
+Requires-Dist: cryptography>=42; extra == "signing"
 Dynamic: license-file
 
 # snapshot_assembler
@@ -40,8 +42,10 @@ repos → protocol_compiler → each repo's compiled/ projections
 ```
 
 The platform is an ordinary member of the composition — no singleton branch. The composition
-currently assembles **seven domains**: `platform`, `workload`, `inspection`, `transformation`,
-and the business domains `ai_governance`, `blockchain` and `book_library_mgmt`.
+currently assembles **eight domains**: `platform`, `workload`, `inspection`, `transformation`,
+and the business domains `ai_governance`, `blockchain`, `book_library_mgmt` and
+`causal_language_model`. A deliberately narrower composition is assembled by naming its roots in
+`PGC_SOURCE_ROOTS`.
 
 ## Install
 
@@ -132,8 +136,18 @@ export PGC_PLATFORM_ROOT=$PWD/software_governance
 pgc            # reports what is installed and whether the anchor resolves
 ```
 
-`PGC_BUILD_ROOT` (compiled output, keeping the governance repo read-only) and `PGC_DOMAIN_ROOTS`
-(additional domains contributing their own `registry/structures`) are optional.
+`PGC_DOMAIN_ROOTS` names an additional domain contributing its own `registry/structures` — the
+directory that *directly contains* it, not the repository above it; pointing one level too high is a
+silent no-op. Where compiled output is written is declared by each build configuration
+(`output_configuration.root`), not by the environment. `PGC_SNAPSHOT_PROFILES` is the directory
+holding snapshot profiles, required by the assembler and the runtime alike. A snapshot's identity
+covers the content of the profile it claims, so the profiles a node reads must be the ones it was
+sealed against.
+
+`PGC_BUILD_ROOT` is accepted and reported and **nothing reads it**.
+
+The full sequence, with the repositories it needs, is in
+[`pgc_install`](https://github.com/protocol-governed-computing/pgc_install).
 
 **Versioning.** Two schemes, and the published version follows the second.
 
@@ -143,7 +157,7 @@ pgc            # reports what is installed and whether the anchor resolves
   cycle is tagged `release-<N>`. This is not published.
 - **Public** — `PUBLIC_VERSION`, tagged on every component repository. The platform is at **`v3`**.
 
-**The published version is the public one: `v3` is `3.0.0`.** The standard the packages implement is a
+**The published version is the public one: `v4` is `4.0.0`.** The standard the packages implement is a
 separate artifact on its own track and is not this number.
 
 The standard these packages implement is published separately: https://doi.org/10.5281/zenodo.22150616

{pgc_assembler-3.0.0 → pgc_assembler-5.0.0}/pgc_assembler.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ assembler/cli.py
 assembler/conformance.py
 assembler/core.py
 assembler/indexes.py
+assembler/signing.py
 pgc_assembler.egg-info/PKG-INFO
 pgc_assembler.egg-info/SOURCES.txt
 pgc_assembler.egg-info/dependency_links.txt

pgc_assembler-5.0.0/pgc_assembler.egg-info/requires.txt

@@ -0,0 +1,4 @@
+pyyaml
+
+[signing]
+cryptography>=42

{pgc_assembler-3.0.0 → pgc_assembler-5.0.0}/pyproject.toml

@@ -5,7 +5,7 @@ backend-path = ["."]
 
 [project]
 name = "pgc-assembler"
-version = "3.0.0"
+version = "5.0.0"
 description = "PGC snapshot assembler — composes compiled projections into a manifest-pinned executable snapshot (import package: assembler)"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -30,6 +30,13 @@ classifiers = [
 # install without this raises ModuleNotFoundError there instead of refusing.
 dependencies = ["pyyaml"]
 
+# Snapshot signing is a profile's selection, not a property of the core. A platform whose
+# profile requires authenticated snapshots installs this; one that does not should not
+# acquire a cryptography dependency because the capability exists elsewhere. Absent it,
+# assembler.signing refuses rather than degrading to an unsigned success.
+[project.optional-dependencies]
+signing = ["cryptography>=42"]
+
 [project.scripts]
 snapshot_assembler = "assembler.cli:main"
 
@@ -46,5 +53,6 @@ where = ["."]
 include = ["assembler*"]
 
 [tool.setuptools.package-data]
-# VERSION has no extension, so it must be named explicitly.
-"*" = ["*.md", "*.yaml", "*.json", "VERSION"]
+# VERSION has no extension, so it must be named explicitly. Scoped to the package
+# rather than "*" — see the note in protocol_compiler.
+"assembler" = ["VERSION"]

pgc_assembler-3.0.0/VERSION

@@ -1 +0,0 @@
-15

pgc_assembler-3.0.0/assembler/VERSION

@@ -1 +0,0 @@
-15

pgc_assembler-3.0.0/pgc_assembler.egg-info/requires.txt

@@ -1 +0,0 @@
-pyyaml