Metadata-Version: 2.5
Name: gove-zone
Version: 1.0.0rc2
Summary: Minimal governed agent runtime — fail-closed governance, receipts, audit chain for AI agent tool calls.
Project-URL: Homepage, https://acgs.ai
Project-URL: Documentation, https://acgs.ai
Project-URL: Repository, https://github.com/acgs-ai/gove-zone
Project-URL: Issues, https://github.com/acgs-ai/gove-zone/issues
Author: Gove Zone Contributors
License: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,audit,governance,policy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Provides-Extra: crypto
Requires-Dist: cryptography>=42; extra == 'crypto'
Provides-Extra: dev
Requires-Dist: cryptography>=42; extra == 'dev'
Requires-Dist: jsonschema>=4; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1; extra == 'langchain'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.28.1; extra == 'mcp'
Provides-Extra: schema
Requires-Dist: pydantic>=2.0; extra == 'schema'
Provides-Extra: semantica
Requires-Dist: semantica>=0.6.5; extra == 'semantica'
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == 'yaml'
Description-Content-Type: text/markdown

# gove-zone

**Receipt-gated runtime governance for AI-agent side effects.**

> For every execution path wired through gove-zone: **no valid Decision
> Receipt, no side effect.**

gove-zone is the ACGS project's standalone, receipt-gated enforcement
kernel. It evaluates a
proposed action before execution, records the decision, and requires a governed
executor to verify the resulting receipt before a side effect can run. It is an
enforcement layer for agents, MCP tools, workflows, CI jobs, and custom
executors—not an agent framework or a sandbox.

> **Current source metadata:** version `1.0.0rc2`, with a Beta classifier.
> The candidate history still requires release reconciliation. These checked-in
> values do not prove that this version was tagged, published on PyPI, deployed
> to production, certified, or independently assured.

## Prove the invariant locally

Prerequisites: Python 3.11+, `uv`, a source checkout, and Bash on Linux/macOS;
on Windows, use WSL or Git Bash for the commands shown. Environment setup may
download dependencies; after they are installed, the proof itself requires no
agent host, production credential, or external service.

From the repository root:

```bash
uv run gove-zone smoke
uv run --extra crypto python \
  examples/receipt-gated-execution/demo.py
```

The smoke command proves that a safe action is allowed, a sensitive-path write
is denied before execution, and the local audit chain verifies. The signed demo
also exercises missing, tampered, expired, mismatched, and cross-tenant
receipts. Both commands exit non-zero if their assertions fail.

Use `--audit <path>` with `gove-zone smoke` to retain the smoke JSONL as
point-in-time evidence.

## How execution is gated

```text
Proposed action
  → policy decision (or fail-closed DENY)
  → append audit event and issue Decision Receipt
  → governed executor verifies receipt and execution context
  → valid ALLOW/TRANSFORM side effect, or fail-closed block
```

The proposer does not authorize itself. The receipt binds the actor, action,
exact arguments, tenant, policy evidence, and execution context. A missing,
invalid, expired, or mismatched receipt is rejected. A valid receipt is
single-use only when every relevant executor shares a configured
`ReceiptConsumptionLedger`; receipt verification is otherwise stateless.

### Runtime tool-call shapes

`gove_zone.integration` normalizes dependency-free runtime hook payloads
before hashing: Claude/Codex-style `{tool_name, tool_input}`, MCP-style
`{method: "tools/call", params: {name, arguments}}`, function-call-style
`{type: "function_call", name, arguments}`, OpenAI Responses-style
`{output: [{type: "function_call", name, arguments}]}`, OpenAI Chat-style
`{tool_calls: [{function: {name, arguments}}]}`, LangChain-style
`{tool_calls: [{name, args}]}`, and multi-call batches of those shapes.
Recognized batches with unparseable child calls fail closed as
`runtime.malformed_batch` instead of being treated as unknown tools. The
`gove-zone gate` CLI applies the same normalization behind reviewed
`--policy-bundle` rules.

## When to use it

Use gove-zone when you need:

- a policy decision before a specific tool call executes;
- a fail-closed boundary when governance cannot decide or record evidence;
- machine-verifiable Decision Receipts bound to exact arguments and context;
- hash-chained, tamper-evident local audit evidence and offline chain/event
  verification;
- proposer/validator separation and tenant isolation; or
- optional Ed25519-authenticated receipts.

It does not provide:

- planning or agent orchestration;
- a turnkey human-approval queue or UI;
- a complete IAM, PKI, key-rotation, or revocation service;
- containment against a fully compromised issuer or execution host;
- immutable/WORM audit storage; or
- production, compliance, or regulatory certification.

Use authentication, authorization, sandboxing, key custody, external audit
anchoring, and operational monitoring alongside this kernel.

## Install

### Source checkout

From the repository root:

```bash
uv sync --extra crypto
uv run gove-zone doctor
uv run gove-zone smoke
```

The repository root is the package root; `uv sync` installs the package and
its extras directly — no workspace scoping required.

### Verified PyPI release

Do not infer PyPI availability from the checked-in version. Only after a release
manager has independently verified a published version, install that exact
version in a clean environment:

```bash
python -m venv .venv
# Activate .venv for your shell, then replace VERIFIED_VERSION below.
python -m pip install --isolated --no-cache-dir \
  --index-url https://pypi.org/simple \
  "gove-zone[crypto]==VERIFIED_VERSION"
gove-zone doctor
gove-zone smoke
```

The release runbook is `docs/RELEASING.md`; the repository-wide readiness
report is `../../docs/gove-zone-pypi-readiness.md`.

## Distribution surface

| Component | Shipped surface |
|---|---|
| `gove_zone` | Decisions, policies, receipts, governed execution, audit, replay, signing, adapters, evaluation, and CLI support |
| `mcp_gateway` | MCP gateway binding included in the wheel |
| Console scripts | `gove-zone`, `gove-zone-api`, and `acgs` |
| Optional extras | `crypto` for Ed25519 support; development extras are defined in package metadata |
| Python | `>=3.11` |
| Audit store | Append-oriented, hash-chained local JSONL with POSIX `fcntl` and Windows `msvcrt` locking paths |

The public SemVer surface is defined in `docs/API_STABILITY.md`. Before a
stable `1.0.0`, the project must finish reconciling that contract with both
wheel packages, all console scripts, and the public API fixture.

## Security-critical deployment contract

- **Use the governed boundary.** Integrate through
  `execute_with_receipt`, `GovernedExecutor`, or a documented adapter that
  reaches the same verification gate. A direct `DecisionReceipt.verify()` call
  is not a complete execution boundary.
- **Configure trusted signatures.** Receipt issuance signs only with an explicit
  signer. Governed executor gates separately require trusted verification by
  default. Without a configured matching verifier, the gate raises before
  calling the tool. Development-only unsigned mode is an explicit opt-out; it
  is not a production default.
- **Configure one-time consumption when required.** Share a
  `ReceiptConsumptionLedger` across every executor that must reject replay.
- **Anchor audit state externally.** The local hash chain detects internal
  edits, but truncating a suffix can leave a consistent prefix. Store the
  expected event count or final hash outside the local file.
- **Retain replay inputs intentionally.** Audit-only replay verifies chain/event
  integrity and policy-version consistency. Re-deriving a decision requires the
  original raw-call side store plus the matching original policy bundle; the
  side store is opt-in because it retains sensitive arguments.
- **Keep secrets out of policy reasons.** Human-readable reasons can reach
  rejection envelopes and audit evidence.
- **Validate each target platform.** Lock implementations have platform-specific
  test coverage, but that is not production deployment evidence.

## Documentation in the source tree

| Goal | Path |
|---|---|
| Architecture | `ARCHITECTURE.md` |
| Security boundary | `SECURITY.md` and `docs/threat-model.md` |
| Governed execution | `docs/governed-execution.md` |
| Decision Receipts | `docs/decision-receipts.md` |
| Audit evidence | `docs/audit-evidence.md` |
| Policy bundles | `docs/policy-bundles.md` |
| Workflow receipt chains | `docs/workflow-receipt-chain.md` |
| Plan-level governance | `docs/plan-level-governance.md` |
| Game-day incident-evidence drill | `docs/gameday-runbook.md` |
| API stability | `docs/API_STABILITY.md` |
| Release process | `docs/RELEASING.md` |
| Changelog | `CHANGELOG.md` |

The project website is <https://acgs.ai/>. Public source and issue-tracker links
must be resolved as part of the release decision while this repository remains
private.

## Development checks

From the repository root:

```bash
uv run python -m pytest tests --import-mode=importlib -q
(cd  && bash scripts/release_check.sh)
```

For documentation changes, also run:

```bash
uv run python -m pytest tests/docs --import-mode=importlib -q
make lint-docs
```

## License

Apache-2.0.
