pgc-transport 6.0.0__tar.gz

pgc_transport-6.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_transport-6.0.0/NOTICE

@@ -0,0 +1,11 @@
+PGC — Protocol-Governed Computing
+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_transport-6.0.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: pgc-transport
+Version: 6.0.0
+Summary: Protocol-Governed Computing — domain-neutral transport boundary engine (canonical contracts, generic resolver, protocol adapters)
+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/protocol_transport
+Keywords: protocol-governed-computing,pgc,transport,ingress,egress,http,gateway
+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
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# protocol_transport
+
+**The PGC transport boundary engine** — a domain-neutral, protocol-neutral governed
+boundary between external interaction protocols (HTTP, RPC, CLI) and a PGC execution
+universe.
+
+It knows *how* to transport. It declares nothing about *what* is transported: every route,
+operation, and workflow binding arrives as configuration the engine is **pointed at**, never
+hardcoded. The domain/platform declares what may be transported.
+
+> **Semantic authority:** [`TRANSPORT_STANDARD_V0.md`](TRANSPORT_STANDARD_V0.md)
+> (Phase-1 frozen). Read it first. For working in this repo, see
+> [`CLAUDE.md`](CLAUDE.md).
+
+---
+
+## The invariant
+
+> Many external protocols may bind to one **Operation Identity**; one Operation Identity
+> resolves to one governed PGC invocation contract; the external protocol is replaceable,
+> while the governed interaction remains stable.
+
+```
+HTTP / RPC / CLI
+      │            (external protocol)
+      ▼
+  Protocol Adapter        ─ translates wire ↔ Canonical Transport Request/Response (owns no domain meaning)
+      ▼
+  Operation Identity      ─ stable public name (e.g. collatz.compute); NEVER a workflow id
+      ▼
+  TI  → handler → TE      ─ ingress contract → invocation → egress classification
+      ▼
+  Canonical Response      ─ protocol-neutral { outcome, result_class, result, evidence, errors }
+      ▼
+  Response Projection     ─ adapter maps Result Class → HTTP status / RPC error / CLI exit
+```
+
+`TI`/`TE` and the workflows they bind to are **domain-governed and live outside this repo**
+(in the platform/domain surface). This repo is only the engine.
+
+---
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `contracts/` | Canonical, protocol-neutral interop objects — `TRANSPORT_REQUEST_V0`, `TRANSPORT_RESPONSE_V0` |
+| `pgc_transport/request.py` | The Canonical Transport Request every adapter builds. No protocol in it. |
+| `pgc_transport/resolver/` | The generic resolution engine: `operation → TI → handler → TE → Canonical Response`. Zero domain knowledge. |
+| `pgc_transport/adapters/http/` | HTTP mechanics: static mounts, the External Protocol Binding table (data), Response Projection |
+| `pgc_transport/adapters/cli/` | The `pgc_transport` command: one request from the command line, and the HTTP adapter's launcher |
+| `TRANSPORT_STANDARD_V0.md` | The frozen semantic model |
+| `run_http.sh` | Domain-neutral launcher (env-provisioned; names no workload) |
+
+---
+
+## The acid test
+
+The engine holds **no domain knowledge**. Grep `pgc_transport/` for any workload
+or field name (`collatz`, `number`, `steps`, a route literal) and you find nothing. Everything
+domain-specific is data the engine is pointed at:
+
+- **operations** (`TI`/`TE` declarations) via `PGC_OPERATIONS_ROOTS`
+- **routes → operations** via the External Protocol Binding JSON (`PGC_HTTP_BINDINGS`)
+- **static content** via `PGC_STATIC_MOUNTS`
+
+Adding an operation is additive — a new `TI`/`TE` pair plus a binding line — with **no engine
+change**.
+
+---
+
+## Running
+
+`run_http.sh` is generic and requires the environment to point it at roots. A concrete
+composition (the platform reference surface) lives at
+`conformance_workloads/workloads/collatz/client/serve.sh`, which supplies every `PGC_*` variable and execs this
+launcher:
+
+```bash
+./conformance_workloads/workloads/collatz/client/serve.sh      # serves the reference surface on :8000
+```
+
+Installed as `pgc-transport`, the same boundary is the `pgc_transport` command. It is pointed at a
+snapshot and an instance root, like the HTTP adapter:
+
+```bash
+export PGC_SNAPSHOT_ROOT=snapshot PGC_DATA_ROOT=data
+pgc_transport call collatz.compute '{"number": 27}'    # prints the Canonical Transport Response
+pgc_transport http                                     # serves the HTTP adapter, as run_http.sh does
+```
+
+`call` exits with the adapter's projection of the Result Class: `0` SUCCESS, `1` VIOLATION, `3`
+UNAUTHORIZED, `4` NOT_FOUND, `5` OPERATION_NOT_FOUND, `6` EXECUTION_FAILURE. `2` means the
+invocation itself was malformed and never reached the boundary.
+
+See [`CLAUDE.md`](CLAUDE.md) for the full configuration surface and architectural rules.
+
+---
+
+## Layer position
+
+```
+external world  →  transport (adapter → resolver)  →  runtime (executes)  →  transport (TE → adapter)  →  external world
+```
+
+The engine's only cross-repo dependency is the runtime **execution interface**
+(`runtime.api.invoke_workflow`) — it never imports the compiler, protocol, or any domain.

pgc_transport-6.0.0/README.md

@@ -0,0 +1,107 @@
+# protocol_transport
+
+**The PGC transport boundary engine** — a domain-neutral, protocol-neutral governed
+boundary between external interaction protocols (HTTP, RPC, CLI) and a PGC execution
+universe.
+
+It knows *how* to transport. It declares nothing about *what* is transported: every route,
+operation, and workflow binding arrives as configuration the engine is **pointed at**, never
+hardcoded. The domain/platform declares what may be transported.
+
+> **Semantic authority:** [`TRANSPORT_STANDARD_V0.md`](TRANSPORT_STANDARD_V0.md)
+> (Phase-1 frozen). Read it first. For working in this repo, see
+> [`CLAUDE.md`](CLAUDE.md).
+
+---
+
+## The invariant
+
+> Many external protocols may bind to one **Operation Identity**; one Operation Identity
+> resolves to one governed PGC invocation contract; the external protocol is replaceable,
+> while the governed interaction remains stable.
+
+```
+HTTP / RPC / CLI
+      │            (external protocol)
+      ▼
+  Protocol Adapter        ─ translates wire ↔ Canonical Transport Request/Response (owns no domain meaning)
+      ▼
+  Operation Identity      ─ stable public name (e.g. collatz.compute); NEVER a workflow id
+      ▼
+  TI  → handler → TE      ─ ingress contract → invocation → egress classification
+      ▼
+  Canonical Response      ─ protocol-neutral { outcome, result_class, result, evidence, errors }
+      ▼
+  Response Projection     ─ adapter maps Result Class → HTTP status / RPC error / CLI exit
+```
+
+`TI`/`TE` and the workflows they bind to are **domain-governed and live outside this repo**
+(in the platform/domain surface). This repo is only the engine.
+
+---
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `contracts/` | Canonical, protocol-neutral interop objects — `TRANSPORT_REQUEST_V0`, `TRANSPORT_RESPONSE_V0` |
+| `pgc_transport/request.py` | The Canonical Transport Request every adapter builds. No protocol in it. |
+| `pgc_transport/resolver/` | The generic resolution engine: `operation → TI → handler → TE → Canonical Response`. Zero domain knowledge. |
+| `pgc_transport/adapters/http/` | HTTP mechanics: static mounts, the External Protocol Binding table (data), Response Projection |
+| `pgc_transport/adapters/cli/` | The `pgc_transport` command: one request from the command line, and the HTTP adapter's launcher |
+| `TRANSPORT_STANDARD_V0.md` | The frozen semantic model |
+| `run_http.sh` | Domain-neutral launcher (env-provisioned; names no workload) |
+
+---
+
+## The acid test
+
+The engine holds **no domain knowledge**. Grep `pgc_transport/` for any workload
+or field name (`collatz`, `number`, `steps`, a route literal) and you find nothing. Everything
+domain-specific is data the engine is pointed at:
+
+- **operations** (`TI`/`TE` declarations) via `PGC_OPERATIONS_ROOTS`
+- **routes → operations** via the External Protocol Binding JSON (`PGC_HTTP_BINDINGS`)
+- **static content** via `PGC_STATIC_MOUNTS`
+
+Adding an operation is additive — a new `TI`/`TE` pair plus a binding line — with **no engine
+change**.
+
+---
+
+## Running
+
+`run_http.sh` is generic and requires the environment to point it at roots. A concrete
+composition (the platform reference surface) lives at
+`conformance_workloads/workloads/collatz/client/serve.sh`, which supplies every `PGC_*` variable and execs this
+launcher:
+
+```bash
+./conformance_workloads/workloads/collatz/client/serve.sh      # serves the reference surface on :8000
+```
+
+Installed as `pgc-transport`, the same boundary is the `pgc_transport` command. It is pointed at a
+snapshot and an instance root, like the HTTP adapter:
+
+```bash
+export PGC_SNAPSHOT_ROOT=snapshot PGC_DATA_ROOT=data
+pgc_transport call collatz.compute '{"number": 27}'    # prints the Canonical Transport Response
+pgc_transport http                                     # serves the HTTP adapter, as run_http.sh does
+```
+
+`call` exits with the adapter's projection of the Result Class: `0` SUCCESS, `1` VIOLATION, `3`
+UNAUTHORIZED, `4` NOT_FOUND, `5` OPERATION_NOT_FOUND, `6` EXECUTION_FAILURE. `2` means the
+invocation itself was malformed and never reached the boundary.
+
+See [`CLAUDE.md`](CLAUDE.md) for the full configuration surface and architectural rules.
+
+---
+
+## Layer position
+
+```
+external world  →  transport (adapter → resolver)  →  runtime (executes)  →  transport (TE → adapter)  →  external world
+```
+
+The engine's only cross-repo dependency is the runtime **execution interface**
+(`runtime.api.invoke_workflow`) — it never imports the compiler, protocol, or any domain.

pgc_transport-6.0.0/pgc_transport/__init__.py

@@ -0,0 +1 @@
+"""PGC transport boundary: the protocol-neutral resolver and its protocol adapters."""

pgc_transport-6.0.0/pgc_transport/adapters/__init__.py

@@ -0,0 +1 @@
+"""Protocol adapters (Layer 2) — thin, non-authorial boundary translators."""

pgc_transport-6.0.0/pgc_transport/adapters/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line protocol adapter."""

pgc_transport-6.0.0/pgc_transport/adapters/cli/main.py

@@ -0,0 +1,99 @@
+"""Command-line Protocol Adapter — the `pgc_transport` command.
+
+Layer 2 (Transport Standard V0), the command-line counterpart of the HTTP adapter:
+
+    pgc_transport call <operation> '<input as JSON>'
+        Translate one invocation into a Canonical Transport Request, hand it to the
+        protocol-neutral resolver, and print the Canonical Transport Response as JSON. The
+        exit status is this adapter's Response Projection (§7, RESPONSE_PROJECTION_EXTERNAL):
+        the Result-Class → exit-status table lives HERE, never in a TE.
+
+    pgc_transport http
+        Serve the HTTP adapter (`pgc_transport.adapters.http.server`), configured exactly as `run_http.sh`
+        configures it.
+
+Both are POINTED at everything through the environment (ADAPTER_NON_AUTHORIAL):
+    PGC_SNAPSHOT_ROOT   the assembled snapshot the boundary is read from
+    PGC_DATA_ROOT       the instance root execution writes traces and stored state under
+plus, for `http`, the variables `run_http.sh` documents. Nothing here names a workload,
+an operation or a field: the operation is whatever the caller names, and the snapshot's TI
+alone decides whether to admit its input.
+
+Stdlib only.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from pgc_transport.request import to_canonical_request
+from pgc_transport.resolver.registry import load_registry
+from pgc_transport.resolver.resolver import resolve
+
+# Response Projection (adapter-owned; §7). Result Class -> exit status. Distinct statuses keep
+# the classes apart for a caller that cannot read the body; the body carries the class itself.
+_EXIT_STATUS = {
+    "SUCCESS": 0,
+    "VIOLATION": 1,
+    "UNAUTHORIZED": 3,
+    "NOT_FOUND": 4,
+    "OPERATION_NOT_FOUND": 5,
+    "EXECUTION_FAILURE": 6,
+}
+_USAGE = 2   # as argparse uses it: the invocation never reached the boundary
+
+
+def _refuse(message: str) -> None:
+    print(f"pgc_transport: {message}", file=sys.stderr)
+    raise SystemExit(_USAGE)
+
+
+def _required_env(name: str) -> str:
+    value = os.environ.get(name)
+    if not value:
+        _refuse(f"{name} is not set. The adapter reads nothing it is not pointed at.")
+    return value
+
+
+def _call(operation: str, raw_input: str) -> int:
+    try:
+        canonical_input = json.loads(raw_input)
+    except json.JSONDecodeError as exc:
+        _refuse(f"the input is not JSON: {exc}")
+    if not isinstance(canonical_input, dict):
+        _refuse("the input must be a JSON object")
+
+    snapshot_root = _required_env("PGC_SNAPSHOT_ROOT")
+    data_root = _required_env("PGC_DATA_ROOT")
+    registry = load_registry(Path(snapshot_root))
+    response = resolve(to_canonical_request(operation, canonical_input), registry,
+                       data_root=data_root, snapshot_root=snapshot_root)
+    json.dump(response, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return _EXIT_STATUS.get(response["result_class"], _EXIT_STATUS["EXECUTION_FAILURE"])
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="pgc_transport",
+        description="The PGC transport boundary, from the command line.")
+    commands = parser.add_subparsers(dest="command", required=True, metavar="<command>")
+    call = commands.add_parser("call", help="send one request through the boundary")
+    call.add_argument("operation", help="the Operation Identity, e.g. one a TI in the snapshot declares")
+    call.add_argument("input", nargs="?", default="{}", help="the operation's input, a JSON object")
+    commands.add_parser("http", help="serve the HTTP adapter")
+    args = parser.parse_args(argv)
+
+    if args.command == "call":
+        return _call(args.operation, args.input)
+    # Imported only when asked for: the HTTP adapter reads its configuration at import.
+    from pgc_transport.adapters.http import server
+    server.main()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pgc_transport-6.0.0/pgc_transport/adapters/http/__init__.py

@@ -0,0 +1 @@
+"""HTTP protocol adapter (cut #1)."""

pgc_transport-6.0.0/pgc_transport/adapters/http/binding.py

@@ -0,0 +1,81 @@
+"""External Protocol Binding (HTTP) — adapter-owned config, NOT a PGC artifact (Patch 2).
+
+The binding is **data**: a table of entries loaded from a JSON file the adapter is pointed at.
+It maps an HTTP protocol selector (method + route) to an Operation Identity. It is deliberately
+*not* imperative routing logic, so it can later be promoted to a governed `XB_` artifact with no
+change to the transport engine.
+
+Two entry forms coexist, both governed — an operation resolves only if a matching TI/TE pair is
+registered in the snapshot:
+
+    fixed operation      {"method", "path", "operation"}
+    operation in body    {"method", "path", "operation_in_body": true, "namespace": "…"}
+
+The second form exists because a catalog of many sibling identities would otherwise need one
+route each. **The namespace is an ADMISSION CONSTRAINT, not a dispatcher.** The adapter checks
+that the submitted identity falls inside the declared namespace and does nothing else with it:
+the value is passed through as an Operation Identity and resolved through the same governed
+registry as a fixed operation, against its own TI/TE pair. Branching on operation semantics here
+is forbidden (`ADAPTER_NON_AUTHORIAL`) — that would make the adapter an RPC router.
+
+This module contains no workload knowledge — the concrete routes, operations and namespaces live
+entirely in the JSON data file.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, NamedTuple
+
+
+class Binding(NamedTuple):
+    """One bound route. Exactly one of `operation` / `namespace` is meaningful."""
+
+    operation: str | None       # fixed form: the identity this route always carries
+    namespace: str | None       # in-body form: the namespace an identity must fall inside
+
+
+class AdmissionError(ValueError):
+    """The submitted identity is absent or outside the namespace this route admits."""
+
+
+def load_bindings(path: Path) -> dict[tuple[str, str], Binding]:
+    """Load the HTTP binding table → {(METHOD, path): Binding}."""
+    data = json.loads(path.read_text(encoding="utf-8"))
+    table: dict[tuple[str, str], Binding] = {}
+    for entry in data.get("bindings", []):
+        key = (entry["method"].upper(), entry["path"])
+        if key in table:
+            raise ValueError(f"duplicate HTTP binding for {key}")
+        if entry.get("operation_in_body"):
+            namespace = entry.get("namespace")
+            if not namespace:
+                raise ValueError(f"binding {key} declares operation_in_body without a namespace")
+            table[key] = Binding(operation=None, namespace=namespace)
+        else:
+            table[key] = Binding(operation=entry["operation"], namespace=None)
+    return table
+
+
+def select_operation(binding: Binding, body: dict[str, Any]) -> tuple[str, dict[str, Any]]:
+    """Determine (Operation Identity, canonical input) for a bound route.
+
+    Fixed form: the route carries the identity and the whole body IS the input.
+    In-body form: the body carries `operation` plus its `params`, and the identity is admitted
+    iff it falls inside the route's declared namespace. The check is textual containment — the
+    adapter neither knows nor asks what the identity means.
+    """
+    if binding.operation is not None:
+        return binding.operation, body
+
+    operation = body.get("operation")
+    if not isinstance(operation, str) or not operation:
+        raise AdmissionError("request body declares no operation identity")
+    if not operation.startswith(binding.namespace or ""):
+        raise AdmissionError(
+            f"operation '{operation}' is outside the namespace "
+            f"'{binding.namespace}' admitted by this route"
+        )
+    params = body.get("params")
+    return operation, params if isinstance(params, dict) else {}
+