> For the complete documentation index, see [llms.txt](https://docs.algenta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.algenta.ai/trust-and-security/governed-execution.md). # Governed execution The control statements behind every plan approval and execution — named denial codes, single-use approval binding, versioned receipts. These are control statements, not a how-to. They describe what the engine enforces on every decision-plan lifecycle, so a security reviewer can assess it without reading the source. ## The lifecycle is a state machine, not a convention A decision case moves `proposed → approved → executed` through `POST /v1/decision-cases → POST .../analysis-runs → POST .../action-plans → POST /v1/decision-plans/{id}/approve → POST /v1/decision-plans/{id}/execute`. Each transition is enforced server-side against the plan's current `lifecycle_state` — there is no client-supplied field that skips a step. ## Approval is bound to an exact plan, by hash and by a single-use nonce Proposing a plan returns a `plan_hash` and a nonce. Approving requires both, exactly: * A different `plan_hash` than the one proposed is refused as `plan_hash_mismatch` — an approval cannot be silently re-pointed at a plan that was edited after review. * A reused or wrong nonce is refused as `invalid_nonce` — nothing about the flow allows replaying an approval. * An approval past its expiry window is refused as `approval_expired`. * Two concurrent approval attempts on the same plan: exactly one succeeds, the other gets `plan_not_approvable` — a compare-and-set, not a race that both sides can win. ## Execution requires prior approval, and runs exactly once `POST /v1/decision-plans/{id}/execute` on a plan that is not `approved` is refused as `plan_not_approved` — including a plan that was already executed, so a duplicate execute call cannot run twice. This is also a compare-and-set on the `approved` state: under concurrent execute calls, exactly one wins. ## Every denial has a name, not a generic error `plan_not_approved`, `plan_hash_mismatch`, `invalid_nonce`, `approval_expired`, `plan_not_approvable` — a caller (or an integration built on the API) can distinguish *why* an operation was refused without parsing prose. See [Error codes](/http-api/errors.md) for the full, generated list of every code the server emits. ## The execution receipt is a versioned, typed contract Every execution produces an `ExecutionReceipt`: a schema-versioned (`receipt_version`) record carrying `status`, a machine-readable `code` for anything other than success, whether the condition is `retryable`, the `execution_id` (distinct from the plan — the plan is what was authorized, the execution is the act), the bound `plan_hash`, the `approval_state` at execution time, and correlation identifiers (`request_id`, W3C `trace_id`, the caller's `Idempotency-Key` if supplied). It is a real, enforced response schema — not an untyped blob a client has to parse speculatively. ## Execution policy is a content-hashed, revisioned snapshot Org-level execution policy (`GET/PATCH /v1/execution/policy`) is never edited in place. Each change produces a new snapshot: `snapshot_id` embeds a schema revision and a SHA-256 prefix of the policy's own serialized content (`content_hash`), and every snapshot records its `previous_snapshot_id`. Two snapshots with the same content hash are, by construction, the same policy — there is no way for two different policies to collide on one identifier, and no way to silently mutate a policy a decision was evaluated against. Snapshots are listed at `GET /v1/execution/policy/snapshots`. This content-hashed guarantee applies to the org's execution policy specifically. It is a distinct mechanism from the decision-plan's `plan_hash` above — a decision plan does not carry a policy snapshot reference today, and its receipt's `policy_snapshot_hash` field is `null` rather than populated with a value that is not actually a policy hash. ## What this section does not (yet) claim There is no replay-manifest mechanism today — "re-run this past execution and get a byte-identical result" is not a capability this engine exposes, and this page does not claim it is. If that changes, it will be documented here as a control statement backed by working code, the same way everything above is. ## Next steps * [Error codes](/http-api/errors.md) * [Audit and evidence](/trust-and-security/audit-and-evidence.md) * [Execution policy & safety limits](/http-api/rate-limits.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.algenta.ai/trust-and-security/governed-execution.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.