From c37c2d1119adccadd033e60165c9e1a2fc24cc55 Mon Sep 17 00:00:00 2001 From: arpan Date: Mon, 14 Sep 2026 00:08:22 +0530 Subject: [PATCH] Regenerate the API reference against v0.10 items 1 to 5 19 pages, 23 lines. Line numbers moved because items 1 to 5 added code, and four signatures gained a parameter: Control.__init__ gained upstream (SPEC-v0.10 section 4.3, the surface that holds the connection is the one that can name it), protect and Control.execute gained hop, Receipt gained hop, and AuthorityResult gained hop. No page was added or removed, and that is correct rather than an omission. narrowed_dimensions and unmatched_shape live in ctrlrun.authority.__all__ and not in ctrlrun.__all__, which is where render_api.py takes its names from; contained_dimension and DIMENSIONS are in exactly the same position and have no pages either. Control.hop is a method and renders inside Control.mdx. All seven generators clean against the stack: capabilities, cli, schemas, api, cookbook, readiness, badges. Signed-off-by: arpan --- docs/reference/api/Authority.mdx | 2 +- docs/reference/api/AuthorityResult.mdx | 4 ++-- docs/reference/api/Condition.mdx | 2 +- docs/reference/api/Control.mdx | 4 ++-- docs/reference/api/Decision.mdx | 2 +- docs/reference/api/Delegation.mdx | 2 +- docs/reference/api/Event.mdx | 2 +- docs/reference/api/EventSink.mdx | 2 +- docs/reference/api/Grant.mdx | 2 +- docs/reference/api/JSONLEventSink.mdx | 2 +- docs/reference/api/Policy.mdx | 2 +- docs/reference/api/Receipt.mdx | 4 ++-- docs/reference/api/Subject.mdx | 2 +- docs/reference/api/authority-Budget.mdx | 2 +- docs/reference/api/context.mdx | 2 +- docs/reference/api/idempotency_token.mdx | 2 +- docs/reference/api/parse_conditions.mdx | 2 +- docs/reference/api/protect.mdx | 4 ++-- docs/reference/api/with_approval.mdx | 2 +- 19 files changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/reference/api/Authority.mdx b/docs/reference/api/Authority.mdx index 838591e..318a5db 100644 --- a/docs/reference/api/Authority.mdx +++ b/docs/reference/api/Authority.mdx @@ -5,7 +5,7 @@ description: "The `authority:` section, loaded and evaluable (SPEC-v0.3 §4)." {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.Authority` — class, defined at `src/ctrlrun/authority.py:1134` +`ctrlrun.Authority` — class, defined at `src/ctrlrun/authority.py:1229` ```python from ctrlrun import Authority diff --git a/docs/reference/api/AuthorityResult.mdx b/docs/reference/api/AuthorityResult.mdx index efe4e1d..e6aaee5 100644 --- a/docs/reference/api/AuthorityResult.mdx +++ b/docs/reference/api/AuthorityResult.mdx @@ -5,7 +5,7 @@ description: "What the authority axis decided, and which grant it decided on (§ {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.AuthorityResult` — class, defined at `src/ctrlrun/authority.py:619` +`ctrlrun.AuthorityResult` — class, defined at `src/ctrlrun/authority.py:621` ```python from ctrlrun import AuthorityResult @@ -14,7 +14,7 @@ from ctrlrun import AuthorityResult ```python class AuthorityResult - def __init__(passed: bool, reason: str, grant_id: str | None = None, delegation_id: str | None = None, depth: int = 0, dimension: str | None = None, missing_parent_id: str | None = None, expired_parent_id: str | None = None, depth_exceeded: int | None = None, cycle_at: str | None = None) + def __init__(passed: bool, reason: str, grant_id: str | None = None, delegation_id: str | None = None, depth: int = 0, hop: str | None = None, dimension: str | None = None, missing_parent_id: str | None = None, expired_parent_id: str | None = None, depth_exceeded: int | None = None, cycle_at: str | None = None) ``` What the authority axis decided, and which grant it decided on (§4.8). diff --git a/docs/reference/api/Condition.mdx b/docs/reference/api/Condition.mdx index 78d1465..8d591f6 100644 --- a/docs/reference/api/Condition.mdx +++ b/docs/reference/api/Condition.mdx @@ -5,7 +5,7 @@ description: "One `_: operand` test against an action's arguments {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.Condition` — class, defined at `src/ctrlrun/policy.py:371` +`ctrlrun.Condition` — class, defined at `src/ctrlrun/policy.py:398` ```python from ctrlrun import Condition diff --git a/docs/reference/api/Control.mdx b/docs/reference/api/Control.mdx index 5a3c7f0..768bd22 100644 --- a/docs/reference/api/Control.mdx +++ b/docs/reference/api/Control.mdx @@ -5,7 +5,7 @@ description: "Policy, state and evidence composed around a single action (SPEC-v {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.Control` — class, defined at `src/ctrlrun/control.py:677` +`ctrlrun.Control` — class, defined at `src/ctrlrun/control.py:825` ```python from ctrlrun import Control @@ -14,7 +14,7 @@ from ctrlrun import Control ```python class Control - def __init__(policy: Policy, store: StateStore, approvals: ApprovalProvider | None = None, *, clock: Callable[[], datetime] = _utc_now, approval_ttl: timedelta = DEFAULT_APPROVAL_TTL, lease: timedelta = DEFAULT_LEASE, sinks: Sequence[EventSink] = (), suspend_timeout: timedelta = DEFAULT_SUSPEND_TIMEOUT, identity: IdentityProvider | None = None, authority: Authority | None = None, environment: str | None = None, approver_identity: ApproverIdentity | None = None, require_approved_policy: bool = False) + def __init__(policy: Policy, store: StateStore, approvals: ApprovalProvider | None = None, *, clock: Callable[[], datetime] = _utc_now, approval_ttl: timedelta = DEFAULT_APPROVAL_TTL, lease: timedelta = DEFAULT_LEASE, sinks: Sequence[EventSink] = (), suspend_timeout: timedelta = DEFAULT_SUSPEND_TIMEOUT, identity: IdentityProvider | None = None, authority: Authority | None = None, environment: str | None = None, approver_identity: ApproverIdentity | None = None, require_approved_policy: bool = False, upstream: str | None = None) ``` Policy, state and evidence composed around a single action (SPEC-v0.1 §8). diff --git a/docs/reference/api/Decision.mdx b/docs/reference/api/Decision.mdx index c3de473..758e88a 100644 --- a/docs/reference/api/Decision.mdx +++ b/docs/reference/api/Decision.mdx @@ -5,7 +5,7 @@ description: "What may happen to an action: exactly three outcomes in v0.1 (SPEC {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.Decision` — class, defined at `src/ctrlrun/policy.py:308` +`ctrlrun.Decision` — class, defined at `src/ctrlrun/policy.py:335` ```python from ctrlrun import Decision diff --git a/docs/reference/api/Delegation.mdx b/docs/reference/api/Delegation.mdx index dfce962..b7c5bd9 100644 --- a/docs/reference/api/Delegation.mdx +++ b/docs/reference/api/Delegation.mdx @@ -5,7 +5,7 @@ description: "A grant created at runtime by a principal who already holds one (S {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.Delegation` — class, defined at `src/ctrlrun/authority.py:579` +`ctrlrun.Delegation` — class, defined at `src/ctrlrun/authority.py:581` ```python from ctrlrun import Delegation diff --git a/docs/reference/api/Event.mdx b/docs/reference/api/Event.mdx index 993749b..8c16abb 100644 --- a/docs/reference/api/Event.mdx +++ b/docs/reference/api/Event.mdx @@ -5,7 +5,7 @@ description: "One ordered step in the life of an action (SPEC-v0.1 §6.2)." {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.Event` — class, defined at `src/ctrlrun/receipt.py:297` +`ctrlrun.Event` — class, defined at `src/ctrlrun/receipt.py:305` ```python from ctrlrun import Event diff --git a/docs/reference/api/EventSink.mdx b/docs/reference/api/EventSink.mdx index ea24ea4..709fced 100644 --- a/docs/reference/api/EventSink.mdx +++ b/docs/reference/api/EventSink.mdx @@ -5,7 +5,7 @@ description: "Somewhere a copy of every `Event` and `Receipt` goes (SPEC-v0.2 § {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.EventSink` — class, defined at `src/ctrlrun/receipt.py:773` +`ctrlrun.EventSink` — class, defined at `src/ctrlrun/receipt.py:798` ```python from ctrlrun import EventSink diff --git a/docs/reference/api/Grant.mdx b/docs/reference/api/Grant.mdx index ff85c8e..da0d436 100644 --- a/docs/reference/api/Grant.mdx +++ b/docs/reference/api/Grant.mdx @@ -5,7 +5,7 @@ description: "One permission: this subject may propose these actions, under thes {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.Grant` — class, defined at `src/ctrlrun/authority.py:416` +`ctrlrun.Grant` — class, defined at `src/ctrlrun/authority.py:431` ```python from ctrlrun import Grant diff --git a/docs/reference/api/JSONLEventSink.mdx b/docs/reference/api/JSONLEventSink.mdx index deda44e..39c7af6 100644 --- a/docs/reference/api/JSONLEventSink.mdx +++ b/docs/reference/api/JSONLEventSink.mdx @@ -5,7 +5,7 @@ description: "The JSONL half of the evidence: two append-only files in one direc {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.JSONLEventSink` — class, defined at `src/ctrlrun/receipt.py:792` +`ctrlrun.JSONLEventSink` — class, defined at `src/ctrlrun/receipt.py:817` ```python from ctrlrun import JSONLEventSink diff --git a/docs/reference/api/Policy.mdx b/docs/reference/api/Policy.mdx index 8189ebd..1e5ea45 100644 --- a/docs/reference/api/Policy.mdx +++ b/docs/reference/api/Policy.mdx @@ -5,7 +5,7 @@ description: "Action-level autonomy policy: which actions may run, and under whi {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.Policy` — class, defined at `src/ctrlrun/policy.py:700` +`ctrlrun.Policy` — class, defined at `src/ctrlrun/policy.py:759` ```python from ctrlrun import Policy diff --git a/docs/reference/api/Receipt.mdx b/docs/reference/api/Receipt.mdx index 115e1b2..713bdc6 100644 --- a/docs/reference/api/Receipt.mdx +++ b/docs/reference/api/Receipt.mdx @@ -5,7 +5,7 @@ description: "Portable evidence of one action that reached a terminal state (SPE {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.Receipt` — class, defined at `src/ctrlrun/receipt.py:389` +`ctrlrun.Receipt` — class, defined at `src/ctrlrun/receipt.py:397` ```python from ctrlrun import Receipt @@ -14,7 +14,7 @@ from ctrlrun import Receipt ```python class Receipt - def __init__(receipt_id: str, action_id: str, action: str, action_hash: str, principal: Principal, resource: str | None, arguments: Mapping[str, Any], environment: str, decision: Decision, decision_reason: str, result: ReceiptResult, started_at: datetime, finished_at: datetime, approval_id: str | None = None, approver: str | None = None, effect_key: str | None = None, attempt: int = 1, error: str | None = None, execution: ReceiptResult | None = None, would_have: _WouldHave | None = None, seq: int | None = None, prev_hash: str | None = None, policy_hash: str | None = None, policy_version: str | None = None, controls: tuple[str, ...] = (), hash: str | None = None, precondition_at_request: str | None = None, precondition_at_recheck: str | None = None, approvers: tuple[VerifiedApprover, ...] = (), authority_grant_id: str | None = None, task: str | None = None, scope_hash: str | None = None, budget_charges: tuple[Mapping[str, Any], ...] = (), schema: str = RECEIPT_SCHEMA) + def __init__(receipt_id: str, action_id: str, action: str, action_hash: str, principal: Principal, resource: str | None, arguments: Mapping[str, Any], environment: str, decision: Decision, decision_reason: str, result: ReceiptResult, started_at: datetime, finished_at: datetime, approval_id: str | None = None, approver: str | None = None, effect_key: str | None = None, attempt: int = 1, error: str | None = None, execution: ReceiptResult | None = None, would_have: _WouldHave | None = None, seq: int | None = None, prev_hash: str | None = None, policy_hash: str | None = None, policy_version: str | None = None, controls: tuple[str, ...] = (), hash: str | None = None, precondition_at_request: str | None = None, precondition_at_recheck: str | None = None, approvers: tuple[VerifiedApprover, ...] = (), authority_grant_id: str | None = None, task: str | None = None, scope_hash: str | None = None, hop: str | None = None, budget_charges: tuple[Mapping[str, Any], ...] = (), schema: str = RECEIPT_SCHEMA) ``` Portable evidence of one action that reached a terminal state (SPEC-v0.1 §6.1). diff --git a/docs/reference/api/Subject.mdx b/docs/reference/api/Subject.mdx index b2c0968..00c07c1 100644 --- a/docs/reference/api/Subject.mdx +++ b/docs/reference/api/Subject.mdx @@ -5,7 +5,7 @@ description: "Who a grant is addressed to: an agent pattern, a user pattern, or {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.Subject` — class, defined at `src/ctrlrun/authority.py:320` +`ctrlrun.Subject` — class, defined at `src/ctrlrun/authority.py:335` ```python from ctrlrun import Subject diff --git a/docs/reference/api/authority-Budget.mdx b/docs/reference/api/authority-Budget.mdx index 9c41dbe..e28ed36 100644 --- a/docs/reference/api/authority-Budget.mdx +++ b/docs/reference/api/authority-Budget.mdx @@ -5,7 +5,7 @@ description: "How much, over what, in how long (SPEC-v0.9 §2.2)." {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.authority.Budget` — class, defined at `src/ctrlrun/authority.py:366` +`ctrlrun.authority.Budget` — class, defined at `src/ctrlrun/authority.py:381` ```python from ctrlrun.authority import Budget diff --git a/docs/reference/api/context.mdx b/docs/reference/api/context.mdx index ca76059..9cc2df7 100644 --- a/docs/reference/api/context.mdx +++ b/docs/reference/api/context.mdx @@ -5,7 +5,7 @@ description: "Bind the principal for calls made inside the block." {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.context` — function, defined at `src/ctrlrun/control.py:322` +`ctrlrun.context` — function, defined at `src/ctrlrun/control.py:368` ```python from ctrlrun import context diff --git a/docs/reference/api/idempotency_token.mdx b/docs/reference/api/idempotency_token.mdx index 1f7139f..c3dbb20 100644 --- a/docs/reference/api/idempotency_token.mdx +++ b/docs/reference/api/idempotency_token.mdx @@ -5,7 +5,7 @@ description: "The provider idempotency token for the attempt this executor is ru {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.idempotency_token` — function, defined at `src/ctrlrun/control.py:290` +`ctrlrun.idempotency_token` — function, defined at `src/ctrlrun/control.py:336` ```python from ctrlrun import idempotency_token diff --git a/docs/reference/api/parse_conditions.mdx b/docs/reference/api/parse_conditions.mdx index ef816d6..c9eee51 100644 --- a/docs/reference/api/parse_conditions.mdx +++ b/docs/reference/api/parse_conditions.mdx @@ -5,7 +5,7 @@ description: "Parse a `when:`-shaped mapping into conditions, keyed by the raw c {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.parse_conditions` — function, defined at `src/ctrlrun/policy.py:1248` +`ctrlrun.parse_conditions` — function, defined at `src/ctrlrun/policy.py:1326` ```python from ctrlrun import parse_conditions diff --git a/docs/reference/api/protect.mdx b/docs/reference/api/protect.mdx index 8e00624..653d65c 100644 --- a/docs/reference/api/protect.mdx +++ b/docs/reference/api/protect.mdx @@ -5,7 +5,7 @@ description: "Bind a function to an action name: every call becomes a decided, r {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.protect` — function, defined at `src/ctrlrun/control.py:4576` +`ctrlrun.protect` — function, defined at `src/ctrlrun/control.py:4902` ```python from ctrlrun import protect @@ -13,7 +13,7 @@ from ctrlrun import protect ```python -def protect(name: str, *, effect: str | None = None, resource: str | None = None, wait: bool = False, lease: timedelta | None = None, reconcile: Callable[[str], ReconcileOutcome] | None = None, reconcile_eagerly: bool = False, control: Control | None = None, preconditions: Callable[[Action], Mapping[str, Any]] | None = None, task: str | None = None, scope: Callable[[Action], Mapping[str, Any]] | None = None) -> Callable[[Callable[P, R]], Callable[P, R]] +def protect(name: str, *, effect: str | None = None, resource: str | None = None, wait: bool = False, lease: timedelta | None = None, reconcile: Callable[[str], ReconcileOutcome] | None = None, reconcile_eagerly: bool = False, control: Control | None = None, preconditions: Callable[[Action], Mapping[str, Any]] | None = None, task: str | None = None, hop: str | None = None, scope: Callable[[Action], Mapping[str, Any]] | None = None) -> Callable[[Callable[P, R]], Callable[P, R]] ``` Bind a function to an action name: every call becomes a decided, recorded Action. diff --git a/docs/reference/api/with_approval.mdx b/docs/reference/api/with_approval.mdx index de2b8cc..69bf752 100644 --- a/docs/reference/api/with_approval.mdx +++ b/docs/reference/api/with_approval.mdx @@ -5,7 +5,7 @@ description: "Present a granted approval to the calls made inside the block (SPE {/* generated by tools/docs_audit/render_api.py from the docstrings — edit the docstring, never this page */} -`ctrlrun.with_approval` — function, defined at `src/ctrlrun/control.py:345` +`ctrlrun.with_approval` — function, defined at `src/ctrlrun/control.py:391` ```python from ctrlrun import with_approval