From a4ef34aa565ffaaac68dc6b2ac67a216bd4561cf Mon Sep 17 00:00:00 2001 From: ExatronOmega Date: Sun, 14 Jun 2026 13:59:41 +0200 Subject: [PATCH] docs: full document-truth pass across MVP and boundary docs Align public documentation with current code truths for runtime admission, receipt binding, SCLite/replay integration, architecture, and operator workflows so docs no longer overclaim design-only APIs or understate shipped surfaces. --- docs/ADMISSION_POLICY.md | 9 +- docs/API_BOUNDARY.md | 16 +- docs/ARCHITECTURE.md | 166 +++++++++++++++--- docs/DOMAIN_PROFILE_CONTRACT.md | 9 +- docs/EVENT_MODEL.md | 4 +- docs/GOVERNED_RUNTIME_MVP_RUNBOOK.md | 22 ++- ...GUARDED_FRESH_RUNTIME_ADMISSION_EXAMPLE.md | 6 +- docs/INSPECT_ONLY_ADMISSION_WORKFLOW.md | 15 +- docs/ORCHESTRATOR_MODEL.md | 4 +- docs/RECEIPT_BINDING.md | 43 +++-- docs/ROADMAP.md | 9 +- docs/RUNTIME_ADMISSION.md | 92 ++++++---- docs/SCLITE_INTEGRATION.md | 21 ++- docs/SECURITY_INTEGRATION.md | 4 +- docs/STATE_MACHINE.md | 22 ++- docs/VALIDATION.md | 14 ++ 16 files changed, 347 insertions(+), 109 deletions(-) diff --git a/docs/ADMISSION_POLICY.md b/docs/ADMISSION_POLICY.md index 49b51c5..796aa65 100644 --- a/docs/ADMISSION_POLICY.md +++ b/docs/ADMISSION_POLICY.md @@ -39,9 +39,12 @@ and concrete execution. The canonical runtime admission contract lives in [RUNTIME_ADMISSION.md](RUNTIME_ADMISSION.md). The initial `RuntimeAdmissionResult` record is the bounded admission decision surface. The -`compose_runtime_admission_result()` helper populates it from policy, ticket, -trust, SCLite guarded verification, replay freshness, runner-profile, and -receipt-obligation signals without making intent an execution authority. +`compose_runtime_admission_result()` helper populates it from host-supplied +policy, ticket, trust, SCLite guarded verification, replay freshness, +runner-profile, and receipt-obligation summaries without making intent an +execution authority. The helper composes summaries only; it does not verify +SCLite tickets or record replay state. Guarded/replay blockers apply when the +host sets `runtime_consumable=True`. ## Audit ledger port diff --git a/docs/API_BOUNDARY.md b/docs/API_BOUNDARY.md index 7b6c722..fe1d85e 100644 --- a/docs/API_BOUNDARY.md +++ b/docs/API_BOUNDARY.md @@ -4,8 +4,8 @@ GovEngine owns reusable governed-execution services. Its public surface should s The top-level export stability classification lives in [API_STABILITY_MATRIX.md](API_STABILITY_MATRIX.md). It covers the current `govengine.__all__` surface and is guarded by tests so new public exports require an explicit stability decision. -`govengine.surfaces.public_surface_index()` is the tested machine-readable map of the current alpha public surface set. It contains the neutral artifact-governance core, planning contracts, admission/policy contracts, evidence review, domain-profile SDK, runtime contract proofs, and controlled-execution core. The published `0.12.0-alpha` line removes the prior Ravenclaw-derived optional security facade; domain security behavior belongs in the host runtime. -`govengine.boundary.kernel_boundary_report()` is the tested machine-readable 0.2 boundary report. It combines the kernel/profile/runtime/SCLite ownership contract, known domain-profile contracts such as Ravenclaw, and the current public surface index. +`govengine.surfaces.public_surface_index()` is the tested machine-readable map of the current alpha public surface set. It contains the neutral artifact-governance core, planning contracts, admission/policy contracts, evidence review, domain-profile SDK, runtime contract proofs, and controlled-execution core. The published `0.12.2a0` (`0.12.2-alpha`) line removes the prior Ravenclaw-derived optional security facade; domain security behavior belongs in the host runtime. +`govengine.boundary.kernel_boundary_report()` is the tested machine-readable boundary report (schema `v0.1`). It combines the kernel/profile/runtime/SCLite ownership contract, known domain-profile contracts such as Ravenclaw, and the current public surface index. `govengine.boundary.validate_domain_profile_conformance()` checks that a domain profile does not claim forbidden ownership and consumes only known GovEngine/SCLite surfaces. `govengine.orchestration.validate_orchestration_step()` checks deterministic orchestration handoff records without granting agent-loop, scheduler, UI, carrier, credential, or live-execution authority. `govengine.events.validate_event_envelope()` checks transport-neutral governance event metadata without accepting raw prompts, credentials, live commands, carrier payloads, or scheduling claims. @@ -14,7 +14,7 @@ The top-level export stability classification lives in [API_STABILITY_MATRIX.md] `govengine.control.validate_control_decision()` checks deterministic between-step control decisions and delegates legal state changes to the state machine without accepting raw prompts, commands, schedulers, runtime storage, delivery, or live-execution claims. `govengine.runtime_shell.validate_runtime_snapshot()` checks host-provided control actions, queue snapshots, runtime snapshots, and scheduler-tick metadata without accepting raw prompts, commands, storage, schedules, credentials, carrier payloads, or live-execution claims. `govengine.planning.validate_task_contract()` and `validate_plan_intent_contract()` check neutral planner-to-runtime handoff shapes without accepting raw targets, raw prompts, commands, storage, schedules, credentials, carrier payloads, or live-execution claims. -`govengine.admission.validate_admission_decision()`, `validate_policy_decision()`, `validate_approval_request()`, `validate_audit_record()`, `validate_audit_ledger_entry()`, `validate_audit_ledger_append_result()`, `validate_audit_ledger_verification_result()`, and `validate_runtime_admission_result()` check neutral runtime gate and audit-ledger port records without accepting raw targets, raw prompts, commands, storage, schedules, credentials, carrier payloads, or live-execution claims. +`govengine.admission.validate_admission_decision()`, `validate_policy_decision()`, `validate_approval_request()`, `validate_audit_record()`, `validate_audit_ledger_entry()`, `validate_audit_ledger_append_result()`, `validate_audit_ledger_verification_result()`, `validate_runtime_admission_result()`, `compose_runtime_admission_result()`, and `validate_runtime_admission_proof_inputs()` check neutral runtime gate and audit-ledger port records without accepting raw targets, raw prompts, commands, storage, schedules, credentials, carrier payloads, or live-execution claims. `compose_runtime_admission_result()` composes host-supplied summaries; it does not verify SCLite tickets or record replay state. `govengine.execution.supervision.validate_supervised_runner_request()`, `validate_runner_receipt_for_request()`, and `validate_runner_receipt_binding()` check approved-spec runner supervision, @@ -42,6 +42,7 @@ Neutral core modules: - `govengine.signing` - `govengine.deconfliction` - `govengine.state_index` +- `govengine.state_machine` - `govengine.state_store` - `govengine.replay` @@ -126,7 +127,7 @@ GovEngine owns: - `govengine.scope_ports` — neutral scope-port protocol and host extraction helper used by controlled-execution contracts. - `govengine.state_store` — neutral JSON state helper primitives. - `govengine.replay` — guarded SCLite root replay records, claim-once replay-store port contracts, and fresh/replayed decisions over host-supplied state without HMAC verification, key storage, runtime storage ownership, production database ownership, or replay policy beyond the supplied store. -- `govengine.sclite_*` — explicit integration seams with SCLite, including descriptor/status/transition mapping that delegates lifecycle verification and review-bundle verdicts to SCLite. +- `govengine.sclite_contracts` — explicit integration seams with SCLite, including descriptor/status/transition mapping that delegates lifecycle verification and review-bundle verdicts to SCLite. ## Consumes @@ -194,9 +195,10 @@ admission contract described in bounded blockers, next actions, and artifact references. `compose_runtime_admission_result()` populates it from bounded gate evidence for hosts and reviewers; the record does not grant live execution authority by -itself. `normalize_admission_artifact_refs()` is an alpha helper for bounded -review references and existing digest strings only; it does not compute content -digests and does not claim SCLite canonicalization authority. +itself. After an allowed admission is composed, hosts may call +`validate_runtime_admission_proof_inputs()` to check that expected proof-input +summaries are present. That helper does not verify SCLite artifacts or replay +persistence. The operator-facing path that ties admission, trust ports, guarded SCLite verification, replay freshness, runner profile, receipt obligation, and diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 6e69258..0a2d3ce 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -11,8 +11,9 @@ For the current extraction, the host/domain runtime is Ravenclaw. A future infra ## Governed-runtime MVP chain The current MVP path is documented for operators in -[GOVERNED_RUNTIME_MVP_RUNBOOK.md](GOVERNED_RUNTIME_MVP_RUNBOOK.md). The short -form is: +[GOVERNED_RUNTIME_MVP_RUNBOOK.md](GOVERNED_RUNTIME_MVP_RUNBOOK.md). The full +integration order and non-claims are in +[SECURITY_INTEGRATION.md](SECURITY_INTEGRATION.md). The short form is: ```text intent @@ -23,14 +24,44 @@ intent -> runner profile -> receipt obligation -> RuntimeAdmissionResult - -> bounded request/receipt/evidence references + -> GovRunnerRequest + -> GovRunnerReceipt + -> validate_runner_receipt_binding() + -> validate_evidence_review_chain() + -> bounded audit / review references ``` +`compose_runtime_admission_result()` composes host-supplied gate summaries into +`RuntimeAdmissionResult`. It does not validate SCLite tickets, verify +signatures, record replay state, or execute live work. Runtime admission +composition requires an allowed runner profile and a receipt obligation; +concrete runner receipts are validated later with +`validate_runner_receipt_binding()`. Guarded/replay blockers apply during +composition only when the host sets `runtime_consumable=True`. + GovEngine owns the neutral mechanics that compose and validate this chain. It does not own domain policy meaning, operator approval workflow, production identity or keys, raw evidence storage, SCLite proof authority, or live backend execution. +## Public surface map + +The tested public surface registry in `govengine.surfaces` currently exposes +seven neutral surfaces. Additional alpha exports such as `govengine.api`, +`govengine.context`, `govengine.roles`, and `govengine.execution_backend` exist +outside that registry. See also [API_BOUNDARY.md](API_BOUNDARY.md) and +[API_STABILITY_MATRIX.md](API_STABILITY_MATRIX.md). + +| Surface | Primary modules | +| --- | --- | +| `artifact_governance_core` | `govengine.core`, `govengine.boundary`, `govengine.sclite_contracts`, `govengine.lifecycle`, `govengine.signing`, `govengine.replay`, `govengine.deconfliction`, `govengine.state_index`, `govengine.state_machine`, `govengine.state_store` | +| `planning_contracts_core` | `govengine.planning` | +| `admission_policy_core` | `govengine.admission` | +| `evidence_review_core` | `govengine.review` | +| `domain_profile_sdk` | `govengine.profiles` | +| `runtime_contract_proofs` | `govengine.contract_proofs` | +| `controlled_execution_core` | `govengine.execution.*`, `govengine.ooda`, `govengine.orchestration`, `govengine.events`, `govengine.control`, `govengine.runtime_shell`, `govengine.scope_ports`, `govengine.contracts.execution` | + ## Layers ### 0. Kernel/profile boundary layer @@ -56,8 +87,22 @@ Purpose: - validate neutral admission, policy-decision, approval, audit, evidence, and review records; +- compose and validate `RuntimeAdmissionResult` through + `compose_runtime_admission_result()`, `validate_runtime_admission_result()`, + `validate_runtime_admission_proof_inputs()`, and bounded public summaries; +- expose `AuditLedgerPort` and a development-only `JsonlAuditLedgerAdapter` for + hash-chained audit append/read/verify without production database ownership; +- validate receipt-bounded evidence and review reference chains through + `validate_evidence_review_chain()`; - keep security-domain policy meaning and evidence taxonomy in the host runtime. +`validate_runtime_admission_result()` checks record shape and consistency; it +does not by itself enforce receipt obligation on arbitrary stored records the way +`compose_runtime_admission_result()` does. + +See [RUNTIME_ADMISSION.md](RUNTIME_ADMISSION.md) and +[EVIDENCE_REVIEW.md](EVIDENCE_REVIEW.md). + ### 2. Contract layer Modules: @@ -74,7 +119,29 @@ Purpose: Lifecycle artifact projection from a host runtime payload is host-owned; Ravenclaw implements its projection outside this kernel. -### 3. Execution helper / runner protocol layer +See [SCLITE_INTEGRATION.md](SCLITE_INTEGRATION.md). + +### 3. Replay, signing, and trust bridge layer + +Modules: + +- `govengine.replay` +- `govengine.signing` + +Purpose: + +- record guarded SCLite root freshness through host-supplied JSON state, + `ReplayClaimStore`, or development-only in-memory adapters; +- compose SCLite guarded-strict verification with replay recording through + `verify_guard_and_record_replay()`; +- provide GovEngine-owned record digests, signed-record envelopes, and + host-provided signer/verifier/trust ports, plus deterministic demo ports for + fixtures only. + +GovEngine does not own SCLite Kernel Guard HMAC verification, PKI, KMS, key +storage, or production replay persistence. + +### 4. Execution helper / runner protocol layer Modules: @@ -84,20 +151,33 @@ Modules: - `govengine.execution.command_shape` - `govengine.execution.runner` - `govengine.execution.runner_protocol` +- `govengine.execution.gate` +- `govengine.execution.supervision` - `govengine.execution_backend` Purpose: - expose stable API result/error envelopes for hard boundaries; - validate approved execution specs; -- check execution-ticket presence/shape; +- check execution-ticket presence/shape through host-facing ticket-gate helpers; - normalize command shape and target observations; - assemble dry-run result envelopes; -- define the carrier-neutral runner request/receipt protocol a host adapter can honor. - -Important: live subprocess execution is not owned by GovEngine yet. The runner protocol prepares and records bounded execution shape; host adapters still own concrete IO/subprocess behavior. - -### 4. Host context and scope-port layer +- define the carrier-neutral runner request/receipt protocol a host adapter can honor; +- gate controlled execution through `ExecutionGate` and default `DryRunRunner`; +- validate supervised runner requests, receipts, and receipt bindings through + `validate_runner_receipt_binding()`; +- evaluate optional local subprocess runner readiness through + `LocalSubprocessRunnerReadiness` while keeping the local runner at + `not_applicable` by default. + +`govengine.execution_backend` is a port-only contract with no shipped live +backend. Important: live subprocess execution is not owned by GovEngine. The +runner protocol prepares and records bounded execution shape; host adapters +still own concrete IO/subprocess behavior. See +[RUNNER_SUPERVISION.md](RUNNER_SUPERVISION.md) and +[LOCAL_SUBPROCESS_RUNNER_DECISION.md](LOCAL_SUBPROCESS_RUNNER_DECISION.md). + +### 5. Host context and scope-port layer Modules: @@ -113,20 +193,59 @@ Purpose: - avoid hard dependencies on Ravenclaw internals; - support standalone import and package testing. -### 5. OODA safety/control layer +### 6. Planning, profile, and proof contract layer -Module: +Modules: + +- `govengine.planning` +- `govengine.profiles` +- `govengine.contract_proofs` + +Purpose: + +- validate neutral planner-to-runtime handoff contracts without owning a planner + implementation; +- declare contract-only domain profiles and conformance reports for Ravenclaw and + Tecrax fixture paths; +- provide public-safe multi-profile proof fixtures over existing GovEngine + contracts. + +These surfaces are metadata and validation only. They do not add scheduling, +carrier adapters, credentials, or live execution authority. + +### 7. OODA, orchestration, and runtime-shell control layer + +Modules: - `govengine.ooda` +- `govengine.orchestration` +- `govengine.events` +- `govengine.control` +- `govengine.runtime_shell` Purpose: - observe normalized execution telemetry and operator-control events; - orient observations against approved specs, execution tickets, policy decisions, scope, budgets, and host state; - decide whether the next step should continue, pause, abort, cooldown, degrade to dry-run, or require owner review; -- act by returning deterministic control decisions to the host runner/adapter. +- expose deterministic orchestration handoff records, governance event envelopes, run-state transitions, between-step control decisions, and host runtime-shell projections without owning schedulers, queues, storage, credentials, or live execution. + +GovEngine provides reusable deterministic contracts here. Host runtimes such as +Ravenclaw still own wiring those contracts into live control loops. + +## Operator surfaces + +GovEngine also ships read-only operator helpers that validate bounded records +without executing work: + +- `scripts/inspect_runtime_admission.py` — inspect `RuntimeAdmissionResult` + records; +- `scripts/verify_runner_receipt_binding.py` — verify admission/ticket/request/ + receipt binding references; +- `scripts/verify_audit_ledger.py` — verify development JSONL audit-ledger + chains. -This layer converts Ravenclaw's existing scattered controls — stop/pause, host health gates, cooldowns, runtime decisions, and anomaly/replay checks — into a reusable GovEngine contract. It is policy-first, deterministic by default, and carrier-neutral. +These scripts are inspection and verification tools, not execution backends. ## Boundary rule @@ -140,10 +259,15 @@ forbidden: GovEngine -> Logdash/OpenClaw/MCP/A2A adapters ## Current maturity -The package currently covers dry-run-safe helpers and neutral contract gates. -The published `0.12.2-alpha` line keeps the governed-runtime kernel MVP honest: -canonical runtime admission, host-provided trust ports, receipt/evidence -binding, audit/replay ports, inspect-only admission review, and runner safety -documentation are alpha surfaces, not production execution claims. GovEngine is -not a complete orchestrator, scheduler, supervisor stack, subprocess runner, or -product shell and does not claim production execution safety on its own. +The package currently covers dry-run-safe helpers and neutral contract gates in +kernel in alpha form. Source on `main` already includes the governed-runtime MVP +and roadmap-hardening surfaces described above; the last PyPI publish remains +`govengine==0.12.2a0` (`0.12.2-alpha`), with newer work recorded under +`Unreleased` in `CHANGELOG.md` until the next alpha release. + +Those alpha surfaces — canonical runtime admission, host-provided trust ports, +receipt/evidence binding, audit/replay ports, inspect-only admission review, +read-only operator verifiers, and runner safety documentation — are not +production execution claims. GovEngine is not a complete orchestrator, +scheduler, supervisor stack, subprocess runner, or product shell and does not +claim production execution safety on its own. diff --git a/docs/DOMAIN_PROFILE_CONTRACT.md b/docs/DOMAIN_PROFILE_CONTRACT.md index f2e1cf5..49f248b 100644 --- a/docs/DOMAIN_PROFILE_CONTRACT.md +++ b/docs/DOMAIN_PROFILE_CONTRACT.md @@ -2,7 +2,12 @@ A domain profile contract is the host-facing declaration that lets a runtime consume GovEngine without moving domain semantics into the kernel. -GovEngine `0.8.x` also exposes `govengine.profiles`, a minimal contract-only SDK around this boundary. The SDK provides `DomainProfile`, resource/task/stage registries, capability, runner, policy-hook, evidence-rule declarations, fixture Ravenclaw/Tecrax profiles, and `ProfileConformanceReport`. These declarations remain data and validation shapes; they do not implement adapters, credentials, product UX, domain taxonomy, or live execution. +GovEngine also exposes `govengine.profiles`, a minimal contract-only SDK around +this boundary. The SDK provides `DomainProfile`, resource/task/stage registries, +capability, runner, policy-hook, evidence-rule declarations, fixture +Ravenclaw/Tecrax profiles, and `ProfileConformanceReport`. These declarations +remain data and validation shapes; they do not implement adapters, credentials, +product UX, domain taxonomy, or live execution. ## Contract Shape @@ -49,7 +54,7 @@ These remain outside profile ownership even when a profile has runtime code that ## Ravenclaw Compatibility -The built-in Ravenclaw profile contract identifies Ravenclaw as a security-research host profile. It owns campaign/runtime semantics and Logdash/operator workflow language, while consuming neutral GovEngine admission-policy and controlled-execution surfaces plus SCLite review bundles. +The built-in Ravenclaw profile contract identifies Ravenclaw as a security-research host profile. It owns campaign/runtime semantics and Logdash/operator workflow language, while consuming neutral GovEngine admission-policy, evidence-review, and controlled-execution surfaces plus SCLite review bundles. The `ravenclaw_security_profile()` SDK fixture is narrower than Ravenclaw itself: it declares security-research resource types, task families, planning stages, policy hooks, dry-run runner profile, and receipt-bounded evidence expectations. It does not make GovEngine own Ravenclaw finding taxonomy, Logdash, campaign UX, or target-test authorization. diff --git a/docs/EVENT_MODEL.md b/docs/EVENT_MODEL.md index 92362db..0e16561 100644 --- a/docs/EVENT_MODEL.md +++ b/docs/EVENT_MODEL.md @@ -36,4 +36,6 @@ The runtime owns event-loop liveness, queues, schedules, transports, UI, credent ## Release Use -Before 0.2, event docs, public exports, surface metadata, and tests should agree that events are compact governance metadata only. Runtime scheduling, carrier delivery, credential handling, and live execution stay outside GovEngine. +Event docs, public exports, surface metadata, and tests agree that events are +compact governance metadata only. Runtime scheduling, carrier delivery, +credential handling, and live execution stay outside GovEngine. diff --git a/docs/GOVERNED_RUNTIME_MVP_RUNBOOK.md b/docs/GOVERNED_RUNTIME_MVP_RUNBOOK.md index 3f7c715..8a3c8dc 100644 --- a/docs/GOVERNED_RUNTIME_MVP_RUNBOOK.md +++ b/docs/GOVERNED_RUNTIME_MVP_RUNBOOK.md @@ -29,9 +29,15 @@ intent -> RuntimeAdmissionResult -> GovRunnerRequest -> GovRunnerReceipt + -> validate_runner_receipt_binding() + -> validate_evidence_review_chain() -> bounded evidence/review references ``` +`compose_runtime_admission_result()` composes host-supplied gate summaries; it +does not verify SCLite tickets, record replay state, or execute work. For +runtime-consumable guarded/replay blockers, pass `runtime_consumable=True`. + `RuntimeAdmissionResult` is the canonical machine-readable decision. It carries status, `allowed`, reason code, blockers, required next actions, gate inputs, and bounded artifact references. A result can describe eligibility; it does not @@ -56,13 +62,16 @@ execute anything by itself. blocked unless a future host adapter satisfies the runner safety checklist. 8. Require a receipt obligation that binds admission, ticket, request, receipt, status, and bounded output/evidence references. -9. Compose or inspect `RuntimeAdmissionResult`. +9. Compose or inspect `RuntimeAdmissionResult`. For allowed admissions, optionally + call `validate_runtime_admission_proof_inputs()` to confirm expected + proof-input summaries are present. 10. If the result is blocked, follow `required_next_actions` instead of trying to execute. 11. If the result is allowed for dry-run, create a bounded runner request and require a receipt. -12. Qualify evidence/review references against the receipt/admission chain - without storing raw evidence in GovEngine. +12. Validate receipt binding with `validate_runner_receipt_binding()` and qualify + evidence/review references with `validate_evidence_review_chain()` without + storing raw evidence in GovEngine. ## Inspect-Only Workflow @@ -74,6 +83,13 @@ target contact, subprocesses, or live execution authority. The contract is documented in [INSPECT_ONLY_ADMISSION_WORKFLOW.md](INSPECT_ONLY_ADMISSION_WORKFLOW.md). +Operator verifiers: + +- `scripts/inspect_runtime_admission.py` — inspect admission records; +- `scripts/verify_runner_receipt_binding.py` — verify admission/ticket/request/ + receipt binding references; +- `scripts/verify_audit_ledger.py` — verify development JSONL audit chains. + ## Audit and Replay GovEngine exposes neutral audit/replay ports: diff --git a/docs/GUARDED_FRESH_RUNTIME_ADMISSION_EXAMPLE.md b/docs/GUARDED_FRESH_RUNTIME_ADMISSION_EXAMPLE.md index 2c91d9e..da5b710 100644 --- a/docs/GUARDED_FRESH_RUNTIME_ADMISSION_EXAMPLE.md +++ b/docs/GUARDED_FRESH_RUNTIME_ADMISSION_EXAMPLE.md @@ -15,7 +15,8 @@ The example does not execute a backend and does not require credentials. ## Inputs -The host supplies bounded gate summaries: +The host supplies bounded gate summaries with `runtime_consumable=True` when +guarded/replay outcomes should block admission: - a prepared execution contract status and digest; - a host-owned policy decision; @@ -28,6 +29,9 @@ The host supplies bounded gate summaries: SCLite owns guarded verification and ticket semantics. GovEngine records replay freshness and composes the runtime admission result from bounded signals. +`compose_runtime_admission_result()` does not verify SCLite artifacts or record +replay persistence; obtain guarded/replay summaries first (for example via +`verify_guard_and_record_replay()`), then compose admission. ## Expected Result diff --git a/docs/INSPECT_ONLY_ADMISSION_WORKFLOW.md b/docs/INSPECT_ONLY_ADMISSION_WORKFLOW.md index be7b2d7..0188182 100644 --- a/docs/INSPECT_ONLY_ADMISSION_WORKFLOW.md +++ b/docs/INSPECT_ONLY_ADMISSION_WORKFLOW.md @@ -47,7 +47,9 @@ Supported inspect-only flags: - `--format text` for compact human output (default); - `--format json` for bounded machine-readable output; -- `--show-artifact-refs` to include already-bounded references and digests. +- `--show-artifact-refs` to include already-bounded references and digests; +- `--max-bytes N` to reject oversized input files before parsing (default + bounded limit). No flag may grant execution authority. No future flag may grant execution authority. @@ -82,8 +84,8 @@ The inspect workflow must: `validate_runtime_admission_result()`; 3. rely on the admission validator to reject forbidden raw fields; 4. preserve ordered blockers and required next actions; -5. report missing or disabled receipt obligation as a blocker, not as an - implicit approval; +5. report missing or disabled receipt obligation in the summary without treating + inspect output as execution permission; 6. treat `allowed=True` as informational only, not as execution permission; 7. state explicitly that no execution was performed. @@ -132,8 +134,6 @@ Standalone tests in `tests/test_admission_contracts.py` prove: - output states that execution was not performed; - no live backend is imported or invoked. -## Implementation Status - The inspect-only surface is implemented as: ```bash @@ -141,5 +141,6 @@ python scripts/inspect_runtime_admission.py path/to/runtime-admission.json ``` The script validates a single JSON `RuntimeAdmissionResult`, emits compact text -by default, supports bounded JSON output, exits with code 2 for malformed or -unsafe inputs, and always reports `execution: not performed`. +by default, supports bounded JSON output, rejects oversized inputs via +`--max-bytes`, exits with code 2 for malformed or unsafe inputs, and always +reports `execution: not performed`. diff --git a/docs/ORCHESTRATOR_MODEL.md b/docs/ORCHESTRATOR_MODEL.md index 6f170c2..973542a 100644 --- a/docs/ORCHESTRATOR_MODEL.md +++ b/docs/ORCHESTRATOR_MODEL.md @@ -74,4 +74,6 @@ OODA decisions answer whether the next step should continue, pause, abort, cool ## Release Use -Before 0.2, public API, boundary docs, and tests should agree that orchestration is deterministic control metadata only. Runtime scheduling, UI, adapters, credentials, and live execution must remain outside GovEngine. +Public API, boundary docs, and tests agree that orchestration is deterministic +control metadata only. Runtime scheduling, UI, adapters, credentials, and live +execution must remain outside GovEngine. diff --git a/docs/RECEIPT_BINDING.md b/docs/RECEIPT_BINDING.md index de053a0..7148d82 100644 --- a/docs/RECEIPT_BINDING.md +++ b/docs/RECEIPT_BINDING.md @@ -1,9 +1,10 @@ # Receipt Binding Design GovEngine runner receipts must be bindable to the runtime admission decision and -the execution ticket they claim to satisfy. This design defines the neutral -binding shape for later implementation. It does not add live execution -authority. +the execution ticket they claim to satisfy. `GovRunnerReceiptBinding` and +`validate_runner_receipt_binding()` implement the neutral binding shape. This +surface does not add live execution authority and does not grant execution +permission by itself. ```text Intent is not execution authority. @@ -13,6 +14,11 @@ A receipt without admission and ticket bindings is not runtime evidence. ## Purpose +Receipt binding is separate from receipt obligation at admission composition +time. `compose_runtime_admission_result()` requires a receipt obligation before +admission can allow controlled runner work; `validate_runner_receipt_binding()` +validates the concrete receipt after the host adapter has produced one. + Receipt binding makes the post-run record reviewable without moving host-owned runner behavior, raw evidence storage, or SCLite proof authority into GovEngine. A host runtime should be able to verify that a receipt belongs to one @@ -28,16 +34,14 @@ RuntimeAdmissionResult ## Required Binding Fields -Future receipt-binding records should carry these bounded fields: +`GovRunnerReceiptBinding` carries these bounded fields: - `admission_id`: the `RuntimeAdmissionResult` identifier. - `admission_digest`: the GovEngine-owned digest for the admission record when available. -- `admission_ref`: optional bounded path, URI, or artifact reference. - `ticket_id`: the SCLite execution ticket identifier or host ticket id. - `ticket_digest`: the ticket digest or bounded SCLite ticket artifact digest when available. -- `ticket_ref`: optional bounded ticket artifact reference. - `request_id`: the `GovRunnerRequest` identifier. - `request_digest`: a GovEngine-owned digest for the runner request record when available. @@ -50,15 +54,15 @@ Future receipt-binding records should carry these bounded fields: - `runner_profile`: the admitted runner profile, including dry-run/live posture. - `output_digests`: bounded stdout/stderr or artifact digests, never raw output. - `evidence_refs`: bounded downstream evidence or review artifact references. -- `control_decisions`: compact OODA/control decision summaries when present. -The binding record may carry timestamps or lease references only as -host-provided bounded metadata. Hosts own clocks, leases, persistence, raw logs, -and retention policy. +`control_decisions` on a receipt may carry compact OODA/control summaries as +host metadata; they are not part of binding validation. The binding record may +carry timestamps or lease references only as host-provided bounded metadata. +Hosts own clocks, leases, persistence, raw logs, and retention policy. ## Verification Rules -A receipt-binding verifier should fail closed when: +`validate_runner_receipt_binding()` fails closed when: - the receipt omits `admission_id` or `admission_digest` after admission binding is required; @@ -79,11 +83,11 @@ evidence storage and do not replace SCLite review bundles. ## Compatibility With Current Receipts `GovRunnerReceipt` records `status`, `request_id`, `source`, `reason_code`, -step results, and compact control decisions. It can now carry an optional -bounded `binding` envelope with admission, ticket, request, receipt, output -digest, and evidence references. Receipts without binding remain valid for -current dry-run/default-safe execution helpers, but later verifier work should -require binding before treating a receipt as runtime evidence. +step results, and compact control decisions. It can carry an optional bounded +`binding` envelope with admission, ticket, request, receipt, output digest, and +evidence references. Receipts without binding remain valid for current +dry-run/default-safe execution helpers, but verifier work should require binding +before treating a receipt as runtime evidence. Receipt binding is additive: @@ -102,7 +106,7 @@ and GovEngine-owned record digests for admission, request, and receipt records. SCLite owns ticket schema, guarded verification, artifact-chain verification, canonicalization, lifecycle proof, and review-bundle authority. GovEngine may -store bounded SCLite ticket ids, refs, and digests but must not duplicate SCLite +store bounded SCLite ticket ids and digests but must not duplicate SCLite verification. Hosts own raw evidence, redaction, clocks, persistence, live runner behavior, @@ -116,7 +120,7 @@ minimal admission/ticket/request/receipt verifier. The verifier compares GovEngine-owned admission, request, and receipt digests when records or expected digests are supplied, and compares SCLite/host ticket digests only as bounded references. It does not canonicalize SCLite tickets, store raw evidence, or -enable live execution. Evidence/review helpers should then verify +enable live execution. Evidence/review helpers then verify admission -> request -> receipt -> evidence references without storing raw evidence. @@ -124,3 +128,6 @@ evidence. evidence claims and review-result references. It uses receipt ids/digests, admission ids/digests, and receipt status bounds; it does not store raw evidence and does not duplicate SCLite review-bundle verdict authority. + +Read-only operator verification is available through +`scripts/verify_runner_receipt_binding.py`. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index dcd2fef..b7c2eda 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -188,13 +188,14 @@ Definition of done: Status: implemented in `0.3.0` as the initial `govengine.runtime_shell` surface. The implementation adds neutral control actions, queue snapshots, -runtime snapshots, and scheduler-tick metadata while leaving persistence, -queue mutation, scheduler loops, carrier delivery, credentials, UI, and live -execution to host runtimes. +runtime snapshots, and scheduler-tick metadata validators while leaving +persistence, queue mutation, scheduler loops, carrier delivery, credentials, +UI, and live execution to host runtimes. GovEngine does not ship `EventStore`, +`WorkQueue`, or other storage-backed queue implementations in this surface. Goal: introduce a deterministic orchestration shell without making GovEngine an LLM agent loop. -Historical 0.3.x work items: +Historical 0.3.x design targets (not all implemented as concrete types): - `GovEvent`, `EventEnvelope`, `EventStore` protocol; - `GovState`, `GovRunState`, `StateStore` protocol; diff --git a/docs/RUNTIME_ADMISSION.md b/docs/RUNTIME_ADMISSION.md index 32e9eba..32e055c 100644 --- a/docs/RUNTIME_ADMISSION.md +++ b/docs/RUNTIME_ADMISSION.md @@ -63,14 +63,17 @@ to: - `allowed`: boolean, true only when all required gates pass. - `reason_code`: deterministic machine-readable reason for the top-level decision. -- `blockers`: ordered blocker codes such as `missing_policy_decision`, - `execution_ticket_invalid`, `trust_decision_missing`, - `guarded_strict_required`, `replay_not_fresh`, - `runner_profile_missing`, or `receipt_required`. -- `required_next_actions`: ordered action codes such as `evaluate_policy`, - `issue_execution_ticket`, `verify_trust`, `verify_sclite_guarded_strict`, - `claim_replay_freshness`, `select_runner_profile`, or - `bind_runner_receipt`. +- `blockers`: ordered blocker codes emitted by the current runtime composition + path, including `missing_or_invalid_policy_decision`, `policy_denied`, + `missing_or_invalid_execution_ticket`, `invalid_execution_ticket`, + `missing_or_invalid_trust_decision`, `missing_prepared_execution_contract`, + `missing_or_invalid_kernel_guard`, `missing_or_replayed_guarded_root`, + `missing_runner_profile`, `runner_profile_not_allowed`, + `live_backend_disabled`, and `receipt_obligation_required`. +- `required_next_actions`: ordered action codes such as `obtain_policy_decision`, + `approve_execution_ticket`, `verify_trust_decision`, + `verify_guarded_strict_bundle`, `record_guard_replay_freshness`, + `select_allowed_runner_profile`, and `require_runner_receipt_obligation`. - `inputs`: bounded summaries of each input gate. - `artifact_refs`: bounded paths, ids, or digests. This should never carry raw prompts, credentials, live command output, private target data, or raw @@ -94,23 +97,46 @@ receipts, replay claims, audit entries, or live execution authority. ## Gate Semantics -The result is fail-closed: +`compose_runtime_admission_result()` is fail-closed and consumes host-supplied +gate summaries. It does not call SCLite verification, ticket-gate helpers, or +trust verifiers directly. +When `runtime_consumable=True`, guarded-strict and replay-freshness summaries +participate in the admission decision. When `runtime_consumable=False`, +guarded/replay failures do not block admission composition and review-only bundles +can remain distinct from runtime-consumable posture. + +The result is fail-closed for missing or invalid host-supplied summaries: + +- missing prepared execution contract blocks; - missing policy blocks; -- denied, unknown, deferred, or approval-required policy blocks unless the - status is explicitly `needs_review` or `dry_run_only`; +- missing or invalid policy blocks; +- denied, deferred, approval-required, dry-run-only, or record-only policy + outcomes yield policy-specific blockers and usually keep `allowed=False`; - missing or invalid execution ticket blocks runtime-consumable work; -- missing or failed trust decision blocks when trust is required; -- runtime-consumable SCLite artifacts require guarded-strict verification; -- replayed or stale guarded roots block require-fresh runtime admission; -- missing runner profile blocks; -- live runner profiles block unless a future host profile explicitly enables - them after runner safety prerequisites exist; -- missing receipt obligation blocks controlled runner requests. +- missing or invalid trust decision blocks when trust is required; +- runtime-consumable bundles require guarded-strict verification and replay + freshness when `runtime_consumable=True`; +- missing or disallowed runner profile blocks; +- live runner profiles block when `live=True` unless the host explicitly enables + `live_backend_enabled` on the profile; +- missing receipt obligation blocks admission composition; +- missing or disabled receipt obligation blocks admission composition with + `receipt_obligation_required`. + +`status` values such as `dry_run_only` or `needs_review` can coexist with +`allowed=False`. Only `status=allowed` with `allowed=True` means all required +composition gates passed. Dry-run remains the default safe posture. A dry-run admission can be allowed only -when the required policy, ticket, trust, guarded/replay, runner-profile, and -receipt-obligation rules for that dry-run profile are satisfied. +when the required policy, ticket, trust, guarded/replay (if runtime-consumable), +runner-profile, and receipt-obligation rules for that dry-run profile are +satisfied. + +After admission composition, hosts may call +`validate_runtime_admission_proof_inputs()` on an already-allowed record to +check that expected proof-input summaries and references are present. That helper +does not verify SCLite artifacts, signatures, or replay persistence. ## Boundary Rules @@ -130,20 +156,24 @@ ports needed by host runtimes. ## Relationship To Existing Modules -The implementation composes the existing surfaces instead of replacing -them: +The implementation composes host-supplied summaries from existing surfaces +instead of replacing them: -- `govengine.admission` for policy/admission/approval/audit record shapes; -- `govengine.execution.ticket_gate` for execution-ticket checks; +- `govengine.admission` for policy/admission/approval/audit record shapes and + runtime admission composition; +- `govengine.execution.gate` for prerequisite and guarded/replay blocker + evaluation inside `compose_runtime_admission_result()`; +- `govengine.execution.ticket_gate` for host-side execution-ticket checks before + summaries are composed; - `govengine.signing` for signature/trust decisions, host verifier ports, and deterministic GovEngine-owned admission/receipt record digests and signed record envelopes; -- `govengine.signing` key-resolver and trust-store ports for host-owned signer - key references and trust-anchor decisions; -- `govengine.replay` for guarded SCLite replay freshness; +- `govengine.replay` for guarded SCLite replay freshness summaries and + `verify_guard_and_record_replay()`; - `govengine.execution.runner_protocol` and `govengine.execution.supervision` - for runner request, receipt, and profile boundaries; -- `govengine.review` for later receipt/evidence review binding. + for runner request, receipt, and `validate_runner_receipt_binding()`; +- `govengine.review` for receipt-bounded evidence/review reference checks through + `validate_evidence_review_chain()`. ## Implementation Status And Next Tasks @@ -174,7 +204,9 @@ Delivered on current `main` (CHANGELOG `Unreleased` until the next PyPI alpha): guarded-strict composition helpers; 11. `scripts/inspect_runtime_admission.py` implements the inspect-only operator workflow; -12. focused negative tests cover missing policy, ticket, trust, replay, +12. `scripts/verify_runner_receipt_binding.py` and + `scripts/verify_audit_ledger.py` provide read-only operator verifiers; +13. focused negative tests cover missing policy, ticket, trust, replay, runner-profile, and receipt-obligation blockers in admission composition. Remaining work: diff --git a/docs/SCLITE_INTEGRATION.md b/docs/SCLITE_INTEGRATION.md index bad01e2..d690e7b 100644 --- a/docs/SCLITE_INTEGRATION.md +++ b/docs/SCLITE_INTEGRATION.md @@ -88,15 +88,34 @@ Replay-store responsibilities are split deliberately: - Hosts own atomic production persistence, locking, transaction isolation, multi-process concurrency, retention, deletion policy, and recovery. -Runtime-consumable artifacts should use this posture: +Runtime-consumable artifacts should use this posture with +`runtime_consumable=True` on the admission composition inputs: ```text strict lifecycle pass kernel_guard_hmac_v1 pass in SCLite replay fresh in GovEngine policy/ticket/trust gates pass +runtime_consumable=True for guarded/replay blockers ``` +`compose_runtime_admission_result()` consumes bounded gate summaries. It does +not call SCLite verification or record replay state itself. Hosts should obtain +guarded-strict and replay summaries first — for example through +`verify_guard_and_record_replay()` — and then pass those summaries into +admission composition. + +GovEngine exposes two replay models: + +- `ReplayClaimStore` — host-owned claim-once replay freshness port with a + development-only in-memory adapter; +- `verify_guard_and_record_replay()` — calls SCLite guarded-strict verification, + then records replay freshness through a host `GovStateStore` or compatible + adapter and returns one runtime decision. + +These are complementary: SCLite verifies guarded bundles; GovEngine records +whether a guarded root or payload has already been consumed for runtime work. + A deterministic dry-run example for this path is documented in [GUARDED_FRESH_RUNTIME_ADMISSION_EXAMPLE.md](GUARDED_FRESH_RUNTIME_ADMISSION_EXAMPLE.md). The operator sequence that combines those checks with trust ports, runner diff --git a/docs/SECURITY_INTEGRATION.md b/docs/SECURITY_INTEGRATION.md index 2b73972..729bf7c 100644 --- a/docs/SECURITY_INTEGRATION.md +++ b/docs/SECURITY_INTEGRATION.md @@ -12,7 +12,9 @@ Runtime-consuming hosts should evaluate the security path in this order: 2. GovEngine replay freshness for the guarded root or guarded payload. 3. Host trust decision for signer, signature, and trust-anchor status. 4. Execution ticket gate for ticket status and scope binding. -5. Runtime admission composition through `RuntimeAdmissionResult`. +5. Runtime admission composition through `compose_runtime_admission_result()` + with host-supplied gate summaries (`runtime_consumable=True` when guarded/ + replay should block). 6. Runner request creation from an approved execution spec. 7. Runner receipt binding for admission, ticket, request, and receipt refs. 8. Evidence and review records bounded by receipt status. diff --git a/docs/STATE_MACHINE.md b/docs/STATE_MACHINE.md index 8455198..9fa0632 100644 --- a/docs/STATE_MACHINE.md +++ b/docs/STATE_MACHINE.md @@ -57,12 +57,16 @@ Events describe what happened. State transitions describe how the neutral run st ## Release Use -For 0.2, state-machine docs, public exports, surface metadata, and tests agree -that state transitions are deterministic metadata only. Runtime persistence, -queueing, scheduling, credentials, and live execution stay outside GovEngine. - -For 0.3, higher-level host lifecycle actions and queue/runtime projections live -in `govengine.runtime_shell` rather than expanding `GovRunState` into a host -state store. This keeps the state machine narrow while giving hosts a neutral -shape for `start`, `pause`, `resume`, `stop`, `cancel`, `replan`, and -`cooldown` control records. +State-machine docs, public exports, surface metadata, and tests agree that state +transitions are deterministic metadata only. Runtime persistence, queueing, +scheduling, credentials, and live execution stay outside GovEngine. + +GovEngine uses two related but distinct state vocabularies: + +- `GovRunState` / `StateTransition` in `govengine.state_machine` — narrow + governed-run progression metadata; +- `RUNTIME_STATES` / host lifecycle actions in `govengine.runtime_shell` — + higher-level control projections such as `start`, `pause`, and `cooldown`. + +Hosts map their own persistence and process control onto these neutral shapes. +GovEngine validates records; it does not own a host state store. diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md index 0bdd7fc..bcf92fd 100644 --- a/docs/VALIDATION.md +++ b/docs/VALIDATION.md @@ -2,6 +2,20 @@ GovEngine validation is local and public-safe. It does not run live targets. +## CI vs local gates + +GitHub Actions (`.github/workflows/pytest.yml`) runs public-truth validation, +alpha readiness, full pytest across supported Python versions, package dry-run +build, `twine check`, wheel install, and isolated `pip check`. Treat branch or +PR CI as required merge evidence. + +Local-only gates that CI does not fully replace: + +- `ruff check .` +- `git diff --check` +- `scripts/validate_clean_package_install.py` with a disposable venv and + coordinated SCLite source when validating release readiness + ## Local package gate ```bash