Bound approvals and execution
Use this reference with the complete developer tour and TypeScript types. The example at the end runs after the tour setup.
redeem
Section titled “redeem”Redeem an optional bound approval for the exact declared action.
redeem(id: string, action: Action): Promise<Execution>| Parameter | Type and default | Usage |
|---|---|---|
id |
string (required) |
Existing stable resource ID, returned by the corresponding create/read operation. |
action |
Action (required) |
Optional exact bound-action descriptor for the advanced execution contract. |
Returns: Execution with authorized state and stable operation_key.
Permissions, lifecycle and errors: Advanced opt-in contract, not necessary for a normal approval message. The resource owner must enforce operation-key and resource-version fences. Approval never proves execution.
Declared return type: Promise<Execution>.
Working TypeScript example. Input/output fields are in the types reference.
reportExecution
Section titled “reportExecution”Report what the executor actually observed for an authorized operation.
reportExecution(id: string, state: "failed" | "running" | "succeeded" | "unknown", result?: unknown): Promise<Execution>| Parameter | Type and default | Usage |
|---|---|---|
id |
string (required) |
Existing stable resource ID, returned by the corresponding create/read operation. |
state |
"running" | "succeeded" | "failed" | "unknown" (required) |
Lifecycle state. Read the resource-specific enum; request and execution states differ. |
result |
unknown (default null) |
Executor-reported JSON result. It is not independent proof of an external effect. |
Returns: Updated Execution with state and result.
Permissions, lifecycle and errors: Allowed reports: running, succeeded, failed, unknown. Terminal reports cannot be overwritten. Use unknown when the external result cannot be established; never turn a timeout into success.
Declared return type: Promise<Execution>.
Working TypeScript example. Input/output fields are in the types reference.
Example
Section titled “Example”Run this region after the shared setup. Assertions check the returned data; the full tour is a runnable program.
const action = { name: 'reconcile-orders', executor_id: builderId, resource: 'orders', resource_version: 'v2', arguments: { ids: [241, 242] }, operation_key: runId + '/business' };const approval = await owner.ask({ target: { kind: 'person', id: personId }, body: 'Apply this reconciliation?', kind: 'approval', action });await owner.respond(approval.id, { outcome: 'approved', version: approval.version });const execution = await builder.redeem(approval.id, action);assert.equal((await builder.reportExecution(execution.id, 'succeeded', { fixture: true })).state, 'succeeded');