pgc-governance 2.0.0__tar.gz

pgc_governance-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_governance-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_governance-2.0.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: pgc-governance
+Version: 2.0.0
+Summary: PGC governance surface — the registry of governed artifacts and the capability implementations a sealed snapshot binds at execution
+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/software_governance
+Project-URL: Standard, https://doi.org/10.5281/zenodo.22150616
+Keywords: protocol-governed-computing,governance,authorization,sdlc
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Compilers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# software_governance
+
+**The normative platform surface — what a conforming PGC system is allowed to be.**
+
+Every governed behavior in a PGC composition resolves, eventually, against a declaration in this
+repository. It holds the constitutions, invariants, structures, schemas, surface contracts,
+reserved vocabulary, and the neutral capability transforms and side effects that no single domain
+owns and every domain depends on.
+
+It is **declaration first**: constitutions, invariants, structures, schemas and vocabulary that
+the sibling toolchain reads. It also carries the capability transform and side-effect
+implementation modules a sealed snapshot binds by fully qualified module path at execution —
+the only executable code here, and it exists because a snapshot names it.
+
+## Install
+
+```bash
+pip install pgc-governance
+```
+
+This package carries declarations and the implementation modules a sealed
+snapshot binds at execution. It provides no command of its own — the toolchain
+packages read it.
+
+## Where it fits
+
+A composition is assembled from repositories that each own one concern:
+
+```
+software_governance    the normative surface every composition rests on   (this repo)
+conformance_workloads  workloads that prove conformance
+business_domains       domains built on the surface
+
+protocol_compiler      source      → compiled projections
+snapshot_assembler     projections → assembled snapshot
+protocol_runtime       snapshot    → execution
+snapshot_inspector     snapshot    → inspection
+```
+
+This repo is the **floor** of that stack. A domain does not import it — a domain *resolves against*
+it, and the compiler is what performs the resolution. If a reference in any domain fails to resolve,
+either the platform is missing an artifact or the domain leaked one it should have declared itself.
+
+**A platform is a composition, never a repository.** A Profiled Normative Platform is this surface
+plus selected workloads plus an optional business domain, per a conformance profile. There are as
+many platforms as there are profiles.
+
+## What it holds
+
+| Path | Contents |
+|------|----------|
+| `registry/<namespace>/` | The governance surface, one directory per namespace — `actor`, `artifact`, `authority`, `conformance`, `execution`, `governance`, `lifecycle`, `structure`, `transport`, `vocabulary` and others. Each holds its own constitutions, invariants, structures, surface contracts and reserved vocabulary |
+| `registry/schema/` | `SCHEMA_*.json` — the declaration substrate, not a namespace of its own |
+| `capability_transforms/registry/` | Neutral, domain-agnostic capability transform declarations |
+| `capability_side_effects/registry/` | Neutral capability side-effect declarations |
+| `doc/` | The surface map, the governance doctrine, and the rulings that settled contested questions |
+
+Artifacts declare namespaces of the form `fb.<concern>` — `structure::STRUCTURE_IDENTITY_V0`,
+`authority::…`. **`fb` is a federation boundary**: a declaration that a distinct governance
+authority has jurisdiction over a named set of protocol semantics. It is not a folder, a package, or
+a deployment unit — see `registry/federation/constitutions/CONSTITUTION_FEDERATION_BOUNDARY_V0.md`.
+Domains declare their own namespaces (`blockchain::`, `book_library_mgmt::`) and never declare into a
+platform boundary.
+
+## What binds a contributor
+
+**Identity is declared, not located.** An artifact's namespace comes from the `fqdn:` key in its own
+`## Machine` block, never from the directory it sits in. The registry is organised one directory per
+namespace, so the correspondence is currently one-to-one — a navigation convenience, not the source
+of identity. A file may move without changing what the artifact *is*.
+
+**No code, ever.** Normative declarations only: `.md` protocol source and `.json` schemas. A
+directory that would hold `.py` does not belong in this repository. The compiler, assembler, runtime
+and inspector that read this surface are siblings, and none of them is vendored here.
+
+**Immutable within a spec version.** A domain extends the platform by adding artifacts in its own
+namespace; it never modifies one here. A behavior change is a new version, never an in-place edit.
+
+**A namespace is an ownership boundary.** Create one only for a first-class concern that can evolve
+independently and owns a coherent contract — never because several artifacts happen to reference the
+same artifact kind.
+
+## How completeness is verified
+
+The surface is complete and self-supporting **iff the external compiler compiles it to a closed
+snapshot** — every reference resolves, zero unresolved FQDNs. Nothing inside this repository can
+establish that, which is the point: the engine is pointed *at* the surface and never lives inside it.
+
+```bash
+protocol_compiler/compile.sh <this repo>
+```
+
+Then diff the resulting closure against `doc/GOVERNANCE_SURFACE_MAP.md` §6. An unresolved reference
+is either a missing platform artifact or a leaked domain reference — resolved by adding the former
+or moving the latter into the domain that owns it.
+
+## License
+
+See `LICENSE` and `NOTICE`.
+
+---
+
+## 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_governance-2.0.0/README.md

@@ -0,0 +1,143 @@
+# software_governance
+
+**The normative platform surface — what a conforming PGC system is allowed to be.**
+
+Every governed behavior in a PGC composition resolves, eventually, against a declaration in this
+repository. It holds the constitutions, invariants, structures, schemas, surface contracts,
+reserved vocabulary, and the neutral capability transforms and side effects that no single domain
+owns and every domain depends on.
+
+It is **declaration first**: constitutions, invariants, structures, schemas and vocabulary that
+the sibling toolchain reads. It also carries the capability transform and side-effect
+implementation modules a sealed snapshot binds by fully qualified module path at execution —
+the only executable code here, and it exists because a snapshot names it.
+
+## Install
+
+```bash
+pip install pgc-governance
+```
+
+This package carries declarations and the implementation modules a sealed
+snapshot binds at execution. It provides no command of its own — the toolchain
+packages read it.
+
+## Where it fits
+
+A composition is assembled from repositories that each own one concern:
+
+```
+software_governance    the normative surface every composition rests on   (this repo)
+conformance_workloads  workloads that prove conformance
+business_domains       domains built on the surface
+
+protocol_compiler      source      → compiled projections
+snapshot_assembler     projections → assembled snapshot
+protocol_runtime       snapshot    → execution
+snapshot_inspector     snapshot    → inspection
+```
+
+This repo is the **floor** of that stack. A domain does not import it — a domain *resolves against*
+it, and the compiler is what performs the resolution. If a reference in any domain fails to resolve,
+either the platform is missing an artifact or the domain leaked one it should have declared itself.
+
+**A platform is a composition, never a repository.** A Profiled Normative Platform is this surface
+plus selected workloads plus an optional business domain, per a conformance profile. There are as
+many platforms as there are profiles.
+
+## What it holds
+
+| Path | Contents |
+|------|----------|
+| `registry/<namespace>/` | The governance surface, one directory per namespace — `actor`, `artifact`, `authority`, `conformance`, `execution`, `governance`, `lifecycle`, `structure`, `transport`, `vocabulary` and others. Each holds its own constitutions, invariants, structures, surface contracts and reserved vocabulary |
+| `registry/schema/` | `SCHEMA_*.json` — the declaration substrate, not a namespace of its own |
+| `capability_transforms/registry/` | Neutral, domain-agnostic capability transform declarations |
+| `capability_side_effects/registry/` | Neutral capability side-effect declarations |
+| `doc/` | The surface map, the governance doctrine, and the rulings that settled contested questions |
+
+Artifacts declare namespaces of the form `fb.<concern>` — `structure::STRUCTURE_IDENTITY_V0`,
+`authority::…`. **`fb` is a federation boundary**: a declaration that a distinct governance
+authority has jurisdiction over a named set of protocol semantics. It is not a folder, a package, or
+a deployment unit — see `registry/federation/constitutions/CONSTITUTION_FEDERATION_BOUNDARY_V0.md`.
+Domains declare their own namespaces (`blockchain::`, `book_library_mgmt::`) and never declare into a
+platform boundary.
+
+## What binds a contributor
+
+**Identity is declared, not located.** An artifact's namespace comes from the `fqdn:` key in its own
+`## Machine` block, never from the directory it sits in. The registry is organised one directory per
+namespace, so the correspondence is currently one-to-one — a navigation convenience, not the source
+of identity. A file may move without changing what the artifact *is*.
+
+**No code, ever.** Normative declarations only: `.md` protocol source and `.json` schemas. A
+directory that would hold `.py` does not belong in this repository. The compiler, assembler, runtime
+and inspector that read this surface are siblings, and none of them is vendored here.
+
+**Immutable within a spec version.** A domain extends the platform by adding artifacts in its own
+namespace; it never modifies one here. A behavior change is a new version, never an in-place edit.
+
+**A namespace is an ownership boundary.** Create one only for a first-class concern that can evolve
+independently and owns a coherent contract — never because several artifacts happen to reference the
+same artifact kind.
+
+## How completeness is verified
+
+The surface is complete and self-supporting **iff the external compiler compiles it to a closed
+snapshot** — every reference resolves, zero unresolved FQDNs. Nothing inside this repository can
+establish that, which is the point: the engine is pointed *at* the surface and never lives inside it.
+
+```bash
+protocol_compiler/compile.sh <this repo>
+```
+
+Then diff the resulting closure against `doc/GOVERNANCE_SURFACE_MAP.md` §6. An unresolved reference
+is either a missing platform artifact or a leaked domain reference — resolved by adding the former
+or moving the latter into the domain that owns it.
+
+## License
+
+See `LICENSE` and `NOTICE`.
+
+---
+
+## 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_governance-2.0.0/capability_side_effects/implementation/CS_APPENDONLY_JSONL_V0/__init__.py

@@ -0,0 +1,7 @@
+"""CS_APPENDONLY_JSONL_V0 package exports."""
+
+from capability_side_effects.implementation.CS_APPENDONLY_JSONL_V0.runtime import (
+    AppendOnlyJsonlRuntime,
+)
+
+__all__ = ["AppendOnlyJsonlRuntime"]

pgc_governance-2.0.0/capability_side_effects/implementation/CS_APPENDONLY_JSONL_V0/capability.json

@@ -0,0 +1,33 @@
+{
+  "cs_code": "CS_APPENDONLY_JSONL_V0",
+  "version": "v0",
+
+  "kind": "CS",
+  "side_effect_type": "persistent",
+
+  "supported_capability_contracts": [
+    "CC_APPEND_RECORD_V0"
+  ],
+
+  "description": "Append-only JSONL persistence with ordered event history.",
+
+  "durability": "persistent",
+  "idempotent": false,
+  "replay_policy": "append_once",
+
+  "guarantees": [
+    "append_only",
+    "ordered",
+    "jsonl_format",
+    "durable_across_restarts"
+  ],
+
+  "non_guarantees": [
+    "mutation",
+    "overwrite",
+    "random_access",
+    "deletion",
+    "key_addressability",
+    "exactly_once_delivery"
+  ]
+}

pgc_governance-2.0.0/capability_side_effects/implementation/CS_APPENDONLY_JSONL_V0/errors.py

@@ -0,0 +1,22 @@
+"""
+errors.py — Canonical error types for CS_APPENDONLY_JSONL_V0.
+
+These errors represent contract-level failures, not implementation details.
+They are surfaced to CEP via host.py.
+"""
+
+
+class AppendOnlyJsonlError(Exception):
+    """Base class for all CS_APPENDONLY_JSONL_V0 errors."""
+
+
+class InvalidRecord(AppendOnlyJsonlError):
+    """Raised when a record fails validation."""
+
+
+class StorageCorrupt(AppendOnlyJsonlError):
+    """Raised when persisted data cannot be read or parsed safely."""
+
+
+class StorageUnavailable(AppendOnlyJsonlError):
+    """Raised when the backend cannot be accessed or written."""

pgc_governance-2.0.0/capability_side_effects/implementation/CS_APPENDONLY_JSONL_V0/impl/executor.py

@@ -0,0 +1,127 @@
+"""
+executor.py — Capability semantics for CS_APPENDONLY_JSONL_V0.
+
+Entity-based storage resolution:
+- Paths resolved from STRUCTURE using store entity metadata
+- storage_structure_artifact injected by RuntimeLoader from the RB's storage_structure reference
+- module_data_root injected by RuntimeLoader from workflow context
+- __pgs_store_entity__ injected per-operation by capability_pipeline from CC step store: field
+"""
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict
+
+
+class AppendOnlyJsonlEngine:
+    """
+    Implements append-only JSONL semantics with entity-based path resolution.
+    Storage paths are declared in STRUCTURE, not in RB policy.
+    """
+
+    def __init__(self, config: Dict[str, Any]):
+        self._storage_structure = config.get("storage_structure_artifact")
+        if not self._storage_structure:
+            raise ValueError(
+                "CS_APPENDONLY_JSONL_V0 requires storage_structure_artifact in config. "
+                "RuntimeLoader must inject it from the RB storage_structure reference."
+            )
+
+        self._module_data_root = config.get("module_data_root")
+        if not self._module_data_root:
+            raise ValueError(
+                "CS_APPENDONLY_JSONL_V0 requires module_data_root in config. "
+                "RuntimeLoader must inject it from workflow context."
+            )
+
+        core = self._storage_structure.get("frontmatter", {}).get("core", {})
+        self._entity_storage_map = core.get("entity_stores", {})
+        if not self._entity_storage_map:
+            raise ValueError("STRUCTURE artifact missing entity_stores")
+
+    def _resolve_storage_path(self, payload: Dict[str, Any]) -> Path:
+        """
+        Resolve storage path from STRUCTURE using store entity metadata.
+
+        PROTOCOL: Store entity is injected by capability_pipeline from CC step metadata.
+        """
+        store_entity = payload.get("__pgs_store_entity__")
+        if not store_entity:
+            raise ValueError(
+                "PROTOCOL VIOLATION: Missing __pgs_store_entity__ in payload. "
+                "CC step must declare store: field for entity-based storage."
+            )
+
+        entity_config = self._entity_storage_map.get(store_entity)
+        if not entity_config:
+            raise ValueError(
+                f"PROTOCOL VIOLATION: Entity '{store_entity}' not found in STRUCTURE entity_stores. "
+                f"Available entities: {list(self._entity_storage_map.keys())}"
+            )
+
+        subpath = entity_config.get("path")
+        if not subpath:
+            raise ValueError(
+                f"PROTOCOL VIOLATION: Entity '{store_entity}' missing 'path' in STRUCTURE. "
+                "Storage topology must declare paths for all entities."
+            )
+
+        return Path(self._module_data_root) / subpath
+
+    def append(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Append a record to the log."""
+        path = self._resolve_storage_path(payload)
+
+        sequence_counter = 0
+        if path.exists():
+            with open(path) as f:
+                sequence_counter = sum(1 for _ in f)
+
+        record = payload.get("record")
+        stream_id = payload.get("stream_id")
+        actor_id = payload.get("actor_id")
+
+        timestamp = datetime.utcnow().isoformat()
+        record_id = f"{timestamp}_{sequence_counter:06d}"
+        sequence_number = sequence_counter + 1
+
+        log_entry = {
+            "record_id": record_id,
+            "sequence_number": sequence_number,
+            "timestamp": timestamp,
+            "actor_id": actor_id,
+            "stream_id": stream_id,
+            "record": record,
+        }
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "a") as f:
+            f.write(json.dumps(log_entry) + "\n")
+
+        return {
+            "result_status": "SUCCESS",
+            "record_id": record_id,
+            "sequence_number": sequence_number,
+        }
+
+    def read_all(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Read all entries from the log, optionally filtered by stream_id."""
+        path = self._resolve_storage_path(payload)
+        stream_id = payload.get("stream_id")
+        entries = []
+
+        if path.exists():
+            with open(path) as f:
+                for line in f:
+                    entry = json.loads(line)
+                    if stream_id is None or entry.get("stream_id") == stream_id:
+                        entries.append(entry)
+
+        return {"result_status": "SUCCESS", "entries": entries}
+
+    def get_all(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """GET_ALL — the contract-declared operation name for reading the whole log. The runtime host
+        dispatches `getattr(engine, op.lower())`, so the GET_ALL contract op resolves here; delegates to
+        the read_all implementation."""
+        return self.read_all(payload)

pgc_governance-2.0.0/capability_side_effects/implementation/CS_APPENDONLY_JSONL_V0/operations.json

@@ -0,0 +1,48 @@
+{
+  "cs_code": "CS_APPENDONLY_JSONL_V0",
+  "version": "v0",
+  "category": "storage",
+  "description": "Append-only JSONL persistence with ordered event history.",
+
+  "operations": {
+    "APPEND": {
+      "summary": "Append a record to the end of the log",
+      "input": ["record", "stream_id", "actor_id"],
+      "output": ["result_status", "record_id", "sequence_number"],
+      "handler": "append",
+      "idempotent": false,
+      "result_status_values": ["SUCCESS", "VIOLATION", "BACKEND_ERROR"],
+      "notes": "NOT idempotent - each call creates a new entry"
+    },
+
+    "GET_ALL": {
+      "summary": "Retrieve all records from the log",
+      "input": ["stream_id"],
+      "output": ["result_status", "entries"],
+      "handler": "read_all",
+      "idempotent": true,
+      "result_status_values": ["SUCCESS", "BACKEND_ERROR"],
+      "notes": "Returns array of all entries in append order"
+    },
+
+    "GET_RANGE": {
+      "summary": "Retrieve records within a sequence range",
+      "input": ["start_sequence", "end_sequence", "stream_id"],
+      "output": ["result_status", "entries"],
+      "handler": "read_range",
+      "idempotent": true,
+      "result_status_values": ["SUCCESS", "VIOLATION", "BACKEND_ERROR"],
+      "notes": "Inclusive range [start, end]"
+    },
+
+    "GET_SINCE": {
+      "summary": "Retrieve all records after a given timestamp",
+      "input": ["timestamp", "stream_id"],
+      "output": ["result_status", "entries"],
+      "handler": "read_since",
+      "idempotent": true,
+      "result_status_values": ["SUCCESS", "VIOLATION", "BACKEND_ERROR"],
+      "notes": "Useful for tailing logs and incremental reads"
+    }
+  }
+}