pgc-inspector 2.0.0__tar.gz

pgc_inspector-2.0.0/LICENSE

@@ -0,0 +1,67 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+Copyright 2026 Bhash Ganti aka Bachi
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+
+------------------------
+FULL LICENSE TEXT BELOW
+------------------------
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+   "Licensor" shall mean the copyright owner.
+   "Legal Entity" shall mean the union of the acting entity and all other
+   entities that control, are controlled by, or are under common control.
+   "You" shall mean an individual or Legal Entity exercising permissions.
+   "Source" form shall mean the preferred form for making modifications.
+   "Object" form shall mean any form resulting from mechanical transformation.
+   "Work" shall mean the work of authorship.
+   "Derivative Works" shall mean any work based on the Work.
+   "Contribution" shall mean any work intentionally submitted.
+   "Contributor" shall mean Licensor and any individual submitting Contributions.
+
+2. Grant of Copyright License.
+   Each Contributor grants You a perpetual, worldwide, non-exclusive,
+   no-charge, royalty-free copyright license.
+
+3. Grant of Patent License.
+   Each Contributor grants a patent license to make, use, sell, etc.
+
+4. Redistribution.
+   You may reproduce and distribute copies provided that:
+   - You include a copy of this License
+   - You retain notices
+   - You state modifications
+   - You include NOTICE file if present
+
+5. Submission of Contributions.
+   Contributions are under this License unless stated otherwise.
+
+6. Trademarks.
+   This License does not grant trademark rights.
+
+7. Disclaimer of Warranty.
+   Provided "AS IS", without warranties.
+
+8. Limitation of Liability.
+   No liability for damages.
+
+9. Accepting Warranty or Additional Liability.
+   You may offer support/warranty on your own behalf only.

pgc_inspector-2.0.0/NOTICE

@@ -0,0 +1,11 @@
+PGS — Protocol-Governed Systems
+Copyright 2026 Bhash Ganti aka Bachi
+
+This project introduces a protocol-first execution model in which:
+
+- Behavior is declared in protocol artifacts
+- Execution is performed by a deterministic runtime
+- Capability implementations are bound at compile time
+- Governance is enforced through invariants and assertions
+
+Extensibility is achieved by declaration, not refactor.

pgc_inspector-2.0.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: pgc-inspector
+Version: 2.0.0
+Summary: PGC snapshot inspector — read-only query surface over compiled projections and sealed snapshots (command: si)
+Author-email: Bhash Ganti <bachipeachy@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://omnibachi.org/
+Project-URL: Repository, https://github.com/protocol-governed-computing/snapshot_inspector
+Project-URL: Standard, https://doi.org/10.5281/zenodo.22150616
+Keywords: protocol-governed-computing,pgc,inspection,snapshot,registry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# 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
+
+```bash
+pip install pgc-inspector
+```
+
+Once installed:
+
+```bash
+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
+
+```python
+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
+
+| Operation | Kind | Params | |
+|---|---|---|---|
+| `si.snapshot.summary` | READ | — | identity, domains, counts by kind |
+| `si.snapshot.topology` | READ | — | domain → subdomain → workflow map |
+| `si.snapshot.validate` | QUERY | `strict?` | integrity + closure; every check reports `examined` |
+| `si.artifact.list` | READ | `kind?` `domain?` | the artifact catalog |
+| `si.artifact.show` | READ | `artifact` | the published canonical artifact |
+| `si.artifact.indexed` | READ | `artifact` | index membership (absence is SUCCESS) |
+| `si.artifact.refs` | QUERY | `artifact` `transitive?` | consumers and dependencies |
+| `si.topology.impact` | QUERY | `artifact` | transitive consumer closure |
+| `si.store.list` | READ | `domain?` | declared stores, owners, paths |
+| `si.store.show` | READ | `store` | one store's declarations and bindings |
+| `si.store.consumers` | READ | `store` | workflows and CCs reaching a store |
+| `si.vocab.search` | READ | `term` | matching vocabulary identities |
+| `si.vocab.resolve` | READ | `artifact` \| `address`+`domain` | identity ↔ per-domain address |
+| `si.behavior_logic.list` | READ | — | workflows carrying a published graph |
+| `si.behavior_logic.show` | READ | `wf` | one workflow's execution graph |
+| `si.rule_set.list` | READ | `artifact?` | every artifact carrying a sealed rule set, and the rule identifiers it declares |
+| `si.catalog` | READ | — | every operation this inspector answers |
+
+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
+
+| Class | Meaning | Phase |
+|---|---|---|
+| `SNAPSHOT_READ` | project **published** snapshot material | 2a |
+| `SNAPSHOT_QUERY` | **derive** a result by traversing/evaluating snapshot state | 2b |
+
+## CLI
+
+```bash
+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)
+
+```bash
+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)
+
+```bash
+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
+
+| Package | Repository | Role |
+|---|---|---|
+| `pgc-compiler` | `protocol_compiler` | declarations → compiled projections |
+| `pgc-assembler` | `snapshot_assembler` | projections → sealed snapshot |
+| `pgc-runtime` | `protocol_runtime` | snapshot → governed execution |
+| `pgc-inspector` | `snapshot_inspector` | snapshot → read-only inspection |
+| `pgc-transformation` | `transformation` | change request → protocol artifacts |
+| `pgc-governance` | `software_governance` | the governance surface and its capability implementations |
+| `pgc-workloads` | `conformance_workloads` | the workloads that make conformance observable |
+| `pgc-domains` | `business_domains` | the business domain implementations the composed snapshot binds |
+
+`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.
+
+```bash
+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

pgc_inspector-2.0.0/README.md

@@ -0,0 +1,199 @@
+# 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
+
+```bash
+pip install pgc-inspector
+```
+
+Once installed:
+
+```bash
+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
+
+```python
+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
+
+| Operation | Kind | Params | |
+|---|---|---|---|
+| `si.snapshot.summary` | READ | — | identity, domains, counts by kind |
+| `si.snapshot.topology` | READ | — | domain → subdomain → workflow map |
+| `si.snapshot.validate` | QUERY | `strict?` | integrity + closure; every check reports `examined` |
+| `si.artifact.list` | READ | `kind?` `domain?` | the artifact catalog |
+| `si.artifact.show` | READ | `artifact` | the published canonical artifact |
+| `si.artifact.indexed` | READ | `artifact` | index membership (absence is SUCCESS) |
+| `si.artifact.refs` | QUERY | `artifact` `transitive?` | consumers and dependencies |
+| `si.topology.impact` | QUERY | `artifact` | transitive consumer closure |
+| `si.store.list` | READ | `domain?` | declared stores, owners, paths |
+| `si.store.show` | READ | `store` | one store's declarations and bindings |
+| `si.store.consumers` | READ | `store` | workflows and CCs reaching a store |
+| `si.vocab.search` | READ | `term` | matching vocabulary identities |
+| `si.vocab.resolve` | READ | `artifact` \| `address`+`domain` | identity ↔ per-domain address |
+| `si.behavior_logic.list` | READ | — | workflows carrying a published graph |
+| `si.behavior_logic.show` | READ | `wf` | one workflow's execution graph |
+| `si.rule_set.list` | READ | `artifact?` | every artifact carrying a sealed rule set, and the rule identifiers it declares |
+| `si.catalog` | READ | — | every operation this inspector answers |
+
+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
+
+| Class | Meaning | Phase |
+|---|---|---|
+| `SNAPSHOT_READ` | project **published** snapshot material | 2a |
+| `SNAPSHOT_QUERY` | **derive** a result by traversing/evaluating snapshot state | 2b |
+
+## CLI
+
+```bash
+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)
+
+```bash
+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)
+
+```bash
+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
+
+| Package | Repository | Role |
+|---|---|---|
+| `pgc-compiler` | `protocol_compiler` | declarations → compiled projections |
+| `pgc-assembler` | `snapshot_assembler` | projections → sealed snapshot |
+| `pgc-runtime` | `protocol_runtime` | snapshot → governed execution |
+| `pgc-inspector` | `snapshot_inspector` | snapshot → read-only inspection |
+| `pgc-transformation` | `transformation` | change request → protocol artifacts |
+| `pgc-governance` | `software_governance` | the governance surface and its capability implementations |
+| `pgc-workloads` | `conformance_workloads` | the workloads that make conformance observable |
+| `pgc-domains` | `business_domains` | the business domain implementations the composed snapshot binds |
+
+`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.
+
+```bash
+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

pgc_inspector-2.0.0/inspector/__init__.py

@@ -0,0 +1,17 @@
+"""snapshot_inspector — read-only inspection over assembled PGC snapshots.
+
+A first-class toolchain component, symmetric with the compiler / assembler / 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)
+
+CONSUMER-NEUTRAL: the transport SNAPSHOT_READ/SNAPSHOT_QUERY handlers are one consumer; a `si`
+CLI, CI gates (validate/violations), and change-management dossiers are others. The API makes
+no web/transport assumptions.
+
+Inspection never mutates and never executes. Phase 2a projects PUBLISHED snapshot material;
+Phase 2b derives governed queries (refs/deps/impact/validation) over it.
+"""

pgc_inspector-2.0.0/inspector/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m inspector` → the `si` CLI, so the tool runs without being installed."""
+import sys
+
+from inspector.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

pgc_inspector-2.0.0/inspector/api.py

@@ -0,0 +1,94 @@
+"""inspector.api — the single programmatic entry point for snapshot inspection.
+
+    query(operation, params, snapshot_root)  -> (status, payload)
+    operations(snapshot_root)                -> the published catalog
+    operation_kind(operation, snapshot_root) -> the handler kind a boundary routes it by
+
+`status` ∈ {"SUCCESS", "NOT_FOUND"}; raises on internal error. This mirrors
+`runtime.api.run_workflow`'s `(status, surface)` so any boundary (e.g. the transport
+SNAPSHOT_READ handler) can treat execution and inspection uniformly.
+
+**The snapshot declares the operation set.** Every operation, its accepted parameters, its handler
+kind and the implementation that answers it are read from the snapshot's compiled `inspection::` TI
+artifacts (`inspector.catalog`); `inspector.registry` supplies implementations and declares no
+metadata. So an inspector pointed at a snapshot answers exactly what that snapshot declares — two
+snapshots may legitimately offer different operations, and neither is what the code privately
+believes.
+
+A missing REQUIRED parameter is NOT_FOUND, not a raise: the caller asked a well-formed question the
+snapshot cannot answer as posed. An operation the snapshot does not declare raises, because no
+amount of parameters would make it answerable here — that is a caller defect, not a result.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from inspector.catalog import load_catalog
+from inspector.kinds import CATEGORIES
+from inspector.snapshot import Snapshot
+
+
+def _resolve(operation: str, snapshot: Snapshot):
+    catalog = load_catalog(snapshot)
+    op = catalog.get(operation)
+    if op is None:
+        raise KeyError(
+            f"snapshot at {snapshot.root} declares no inspection operation {operation!r}"
+        )
+    return op
+
+
+def query(
+    operation: str,
+    params: dict[str, Any],
+    snapshot_root: str | Path,
+) -> tuple[str, dict[str, Any]]:
+    """Answer an inspection Operation Identity over the assembled snapshot at `snapshot_root`."""
+    snapshot = Snapshot(Path(snapshot_root))
+    op = _resolve(operation, snapshot)
+
+    params = params or {}
+    missing = [p for p in op.required if params.get(p) in (None, "")]
+    if missing:
+        return "NOT_FOUND", {
+            "operation": operation,
+            "reason": f"missing required parameter(s): {', '.join(missing)}",
+            "params": list(op.params),
+        }
+
+    return op.handler(snapshot, params)
+
+
+def operation_kind(operation: str, snapshot_root: str | Path) -> str:
+    """The handler kind (`SNAPSHOT_READ` / `SNAPSHOT_QUERY`) a boundary routes this operation by."""
+    return _resolve(operation, Snapshot(Path(snapshot_root))).kind
+
+
+def operations(snapshot_root: str | Path) -> list[dict[str, Any]]:
+    """The inspection catalog — every operation the snapshot declares, in category then identity order.
+
+    Published so a client's menu is what the SNAPSHOT offers. There is no second list: the CLI's
+    commands and the surface's launcher are both built from this, and this is built from the
+    compiled contracts.
+    """
+    snapshot = Snapshot(Path(snapshot_root))
+    return [
+        {
+            "operation": op.identity,
+            "kind": op.kind,
+            "category": op.category,
+            "label": op.label,
+            "params": list(op.params),
+            "required": list(op.required),
+            "flags": list(op.flags),
+            "summary": op.summary,
+            "implementation": op.implementation,
+        }
+        for op in load_catalog(snapshot).values()
+    ]
+
+
+def categories() -> tuple[str, ...]:
+    """The catalog groupings, in presentation order."""
+    return CATEGORIES