snapshot_inspector

Read-only inspection over assembled PGC snapshots. A first-class toolchain component, symmetric with the compiler, assembler, and runtime — each owns one phase of the snapshot lifecycle:

protocol_compiler    source      → compiled projections
snapshot_assembler   projections → assembled snapshot
protocol_runtime     snapshot    → execution
snapshot_inspector   snapshot    → inspection      (this repo)

It reads the assembled snapshot (the final product) and answers inspection queries over it. It never mutates and never executes.

Install

pip install pgc-inspector

Once installed:

si --help

Consumers

Inspection is consumer-neutral. inspector.api.query(...) serves:

• the transport SNAPSHOT_READ / SNAPSHOT_QUERY handlers (the Inspection Surface),
• the si CLI,
• CI gates (validate / violations),
• change-management dossiers (impact / refs / deps).

API

from inspector.api import query

status, payload = query(
    "si.artifact.show",
    {"artifact": "workload::WF_COLLATZ_CONJECTURE_V0"},
    snapshot_root="/path/to/snapshot",
)
# status ∈ {"SUCCESS", "NOT_FOUND"}

Callers pass an Operation Identity; the inspector resolves it internally (never an RPC of projection functions). See CLAUDE.md for the architectural rules.

operations(snapshot_root) publishes the catalog — every operation with its handler kind, category, parameters, summary and declared implementation. It is read from the snapshot's inspection:: TI artifacts, so a client's menu is what that snapshot offers, not what the code privately believes. There is no second list anywhere.

Operations

A missing required parameter returns NOT_FOUND — a well-formed question the snapshot cannot answer as posed. An unregistered operation raises: no snapshot could ever answer it.

Query classes

CLI

export PGC_SNAPSHOT_ROOT=../snapshot          # or pass --snapshot PATH

si operations                                  # the catalog
si snapshot summary
si artifact show workload::WF_COLLATZ_CONJECTURE_V0
si artifact refs capability_side_effects::CS_MUTABLE_JSON_V0 --transitive
si store consumers LICENSE_REGISTRY
si snapshot validate --strict                  # CI gate: exit 1 if invalid
si artifact list --kind RB --json

Every command is generated from the catalog — registering an operation is the only way to add one, so the CLI can never answer something the API cannot. Snapshot resolution: --snapshot, then $PGC_SNAPSHOT_ROOT, then ./snapshot. Exit codes: 0 SUCCESS, 1 NOT_FOUND (or an invalid snapshot under --strict), 2 usage or snapshot error. Stdlib argparse — nothing to install.

Inspection Surface (browser)

client/serve.sh          # :8001 — needs an assembled snapshot

One of two out-of-box reference implementations. Collatz demonstrates that a governed workflow executes; this demonstrates what a governed snapshot contains.

The surface opens on a launcher listing every operation, grouped by category — fetched via si.catalog, so the menu is exactly what the boundary can answer. Choosing an entry opens an independent window: concurrent (several of the same operation with different parameters is the point), movable, click-to-raise, individually closable. Nothing is ever disabled or queued behind another window.

Every window's content arrives from one POST /si carrying an Operation Identity. The client selects, fetches, formats, filters and navigates; it derives no PGC relationship. Clicking an FQDN opens a new governed request for it — navigation, not a closure the browser worked out.

The inspection:: tool domain

This repo also hosts the domain that declares the boundary: registry/ (build config) and transport/ (32 TI/TE artifacts), compiled by protocol_compiler/compile_domain.sh . and composed into the snapshot like any other domain. A tool domain declares capabilities about a snapshot rather than within one; it consumes the assembled snapshot as the runtime does, which makes it a peer of the runtime, not part of the normative platform.

The contracts are the authority. Each TI declares its operation's identity, kind, input contract, presentation and — as a capability transform does — the {module, callable} that answers it. inspector.registry holds implementations and no metadata; the operation set comes from the snapshot.

scripts/author_transport_contracts.py is the authoring aid that writes the .md artifacts from one complete declaration per operation. Nothing consults it at run time: delete it and the inspector keeps working from the compiled contracts. Re-run it, then recompile the domain, after changing any declaration.

Run (standalone)

PYTHONPATH=. python3 -m inspector operations               # CLI without installing
PYTHONPATH=. python3 -c "from inspector.api import query; \
  print(query('si.artifact.show', {'artifact':'workload::WF_COLLATZ_CONJECTURE_V0'}, '../snapshot'))"

PYTHONPATH=. python3 scripts/testbed/test_inspector.py     # behaviour contract

The package family

pip install pgc brings in the whole family.

Installing the toolchain is one of two steps. The compiler resolves the governance surface from PGC_PLATFORM_ROOT — fail-hard, cwd-independent, zero inference — so the declarations come from a repository you point at, never from a wheel. A registry inside a package would be a second governance surface competing with the repository's, and a build could then be governed by a stale copy.

git clone https://github.com/protocol-governed-computing/software_governance
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.

Versioning. Two schemes, and the published version follows the second.

• Internal — each repository's VERSION file, a monotonic composition ordinal. PGC versions the composition rather than each repo: they release together and the governance closure forces lockstep, so the ordinal names which composition a repo belongs to. Development happens on dev/<N> and each cycle is tagged release-<N>. This is not published.
• Public — PUBLIC_VERSION, tagged on every component repository. The platform is at v2.

The published version is the public one: v2 is 2.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