Expand description
Portable contracts for task orchestration, resumable workflows and worker delivery.
Submission, leases, durable settlement, completion callbacks, workflow events, child tasks and retention describe transactional operations. They provide no persistence or transport by themselves. Adapters must apply the full operation before acknowledging it and preserve replay and ownership semantics.
See the delivery contract and workflow contract.
Structs§
- Accepted
Settlement - AckResult
- Acquire
Command - Acquire
Options - A wait preference and the enclosing local exchange deadline. Neither is part of durable acquisition identity; only the nonzero wait preference is sent over a transport. Every caller must keep its original deadline across probes.
- Acquisition
Key - Acquisition
Queue - Application
Error - Application error identifiers are user-defined, unlike worker error kinds.
- Assignment
- Attempt
Ref - Attempt
Snapshot - Authority
- Current authority sampled for this response; never replay a cached TTL.
- Claim
Command - The session, consumer, and sequence identify one claim operation. Its exact dispatch binding is immutable even if the exchange outcome is unknown.
- Claim
Reply - Every successful disposition consumes the claim sequence and is persisted with its exact command. Receipts survive subsequent consumer-cursor updates.
- Completion
Delivery Result - Completion
Destination - Operator-configured immutable binding. Core does not interpret transport settings.
- Completion
Event - Compact reference-only CloudEvent: no application result copy and no platform
data. Event identity and bytes remain unchanged across retries and manual redelivery. - Completion
Lease - Completion
Retry Command - Completion
Subscribe Command - Completion
Subscription - Consumer
Cursor - Compact replay state: only the latest completed poll per consumer is retained.
- Dispatch
Ref - One readiness generation. Retransmission preserves this identity; a retry made eligible by the lifecycle advances the generation.
- Dispatch
Route - External routing binds a logical queue to a stable opaque destination alias. Provider URLs, credentials, and SDK options belong in adapter configuration.
- History
Event - Persist with the accompanying records. Per-task ordering is assigned under the same task lock; heartbeat renewals do not append history rows.
- Lease
- Lease
Owner - Local
Result Command - Local
Result Receipt - Local
Step Record - Publication
Completion - Publication
Lease - A bounded publication reservation. It contains no task execution authority.
- Publish
Result - Published
Dispatch - Publication identity remains unchanged across uncertain send retries. A deliberate repair publication gets a new identity for the same generation.
- Queue
Delivery - Individual-ack delivery model. A stream checkpoint requires a separate port; implementations must not disguise prefix commits as arbitrary receipt deletes.
- Queue
Limits - Configured transport bounds. These advertise capacities, not ordering, scheduling, deduplication, durability, or exactly-once execution promises.
- Recorded
History Event - Recovery
Progress - Committed progress from one bounded recovery operation.
- Renew
Command - Resolved
Workflow Child - Retention
Policy - Applies to terminal executions and the latest terminal callback activity. Existing retiring records continue physical collection under any later policy.
- Retention
Preview - Bounded age candidates only; protective references can defer collection.
- Retention
Progress - One bounded transaction. Zero removed rows does not mean the database has no retained records: protection, cursor rotation, or a new retirement can occur.
- Retry
Policy - Fixed-delay retry policy, including the initial attempt in
max_attempts. - Scope
- Settle
Command - Settle
Reply - Settlement
Receipt - Submit
Command - Submit
Task - A request to create one logical task, before assigning run or attempt IDs.
- Task
Filters - Exact metadata filters. Submission bounds are inclusive from, exclusive until.
- Task
List Query - One bounded read. Cursors bind the scope and filters, but allow a new page size.
- Task
Page - A coherent committed view for this read; later pages use later read snapshots.
- Task
Position - Immutable seek key, ordered by submission time and then UTF-8 task ID bytes.
- Task
Result - One coherent task observation. Pending is distinct from successful JSON null.
- Task
Snapshot - Transaction-loaded scheduling record. Inputs and the descriptor are immutable.
- Task
Status - Scheduling metadata without application input, output, or package payloads.
- Trace
Context - Origin and processing contexts have the same wire format but different lifetimes.
- Worker
Session - Sessions are issued by the service and never recreated by acquisition. Unknown/expired session IDs are rejected even after old cursor deletion.
- Workflow
Activation Context - Frozen activation inputs and checkpoint, plus the current committed journal. New child completions do not mutate the frozen input batch or revision.
- Workflow
Child Command - Workflow
Decision - Workflow
Event - The sender’s original JSON CloudEvent. This is an external event profile, without required Ledgence execution identifiers. Routing authority comes from the command’s scope/workflow/key, never from event extension attributes.
- Workflow
Event Command - Workflow
Event Receipt - Durable acceptance, not a promise that a controller has processed the event.
accepted_atis immutable across reconciliation and comes from store time. - Workflow
Progress - Workflow
Result - Workflow
Snapshot - Workflow
Subworkflow Result - Workflow
Task Result - Workflow
Work
Enums§
- Acquire
Reply - Acquisition
Completion - Internal provenance prevents replayed assignments from implying more backlog.
- Acquisition
Hint - Hints carry identities only. They never grant execution authority or cache a reply. A rescan follows notification subscription/reconnection.
- Acquisition
Probe - Attempt
Report - Attempt
State - Claim
Disposition - Completion
Delivery Outcome - Completion
State - Completion
Target - Contract
Error - Expected operation rejection or an adapter failure. Backend errors must not be translated into successful empty acquisitions or lost ownership.
- Publication
Outcome - Quiescence
- Required invocation cleanup is done; a healthy warm process may still exist.
- Renew
Intent - Task
Failure - Task
Outcome - Terminal scheduling outcome. Cancellation never attributes an earlier attempt.
- Task
State - Transition
Reason - Workflow
Action - Workflow
Child Kind - Workflow
Child Result - Legacy task inputs retain their wire shape. Workflow inputs have an explicit kind and workflow outcome. Both variants reject mixed or unknown fields.
- Workflow
Outcome - Workflow
State - Workflow
Wait - A single named rendezvous. Keys are one-shot across a workflow, so callbacks from an earlier iteration cannot accidentally satisfy a later wait.
- Workflow
Wake - Immutable next-activation input selected under workflow authority. At an event deadline, only store acceptance strictly before the deadline wins.
- Workflow
Work Source - A controller task finishing is not its workflow finishing. Non-completion work carries no fabricated public task identity.
Constants§
- CLAIM_
REPLY_ MAX_ BYTES - Claim responses can contain a complete assignment and its application data.
- CLEANUP_
GRACE_ MS - COMPLETION_
COMMAND_ MAX_ BYTES - COMPLETION_
EVENT_ MAX_ BYTES - COMPLETION_
LEASE_ MS - COMPLETION_
MAX_ ATTEMPTS - COMPLETION_
MAX_ GENERATION - COMPLETION_
MAX_ RETRY_ DELAY_ MS - COMPLETION_
STATUS_ MAX_ BYTES - CONTROL_
REQUEST_ TIMEOUT_ MS - DISPATCH_
MAX_ BYTES - Complete broker-record/claim-command limit, including JSON whitespace. These envelopes contain identifiers only; application payloads remain in task state.
- LEASE_
DURATION_ MS - Initial server limits. All times are milliseconds; none is a concurrency knob.
- LEASE_
SAFETY_ MARGIN_ MS - LONG_
POLL_ WAIT_ MS - MAX_
COMPLETION_ BATCH - MAX_
COMPLETION_ SUBSCRIPTIONS - MAX_
PUBLICATION_ BATCH - Maximum records leased or completed in one maintenance operation.
- MAX_
RECOVERY_ BATCH - Maximum number of task candidates shortlisted by one recovery operation.
- MAX_
RETENTION_ BATCH - MIN_
RETENTION_ MS - QUEUE_
RECEIPT_ MAX_ BYTES - Upper bound for an opaque receipt copied into the shared handoff coordinator. Receipts remain transport handles; they never identify execution authority.
- RENEW_
INTERVAL_ MS - SESSION_
VALIDITY_ MS - SETTLEMENT_
MAX_ BYTES - SUBMISSION_
DATA_ MAX_ BYTES - Maximum compact JSON encoding of the application-owned submission data.
- SUBMISSION_
MAX_ BYTES - Maximum incoming request bytes and normalized submission bytes (2 MiB).
- TASK_
CURSOR_ MAX_ BYTES - TASK_
LIST_ DEFAULT_ LIMIT - TASK_
LIST_ MAX_ LIMIT - TASK_
PAGE_ MAX_ BYTES - TASK_
STATUS_ MAX_ BYTES - Maximum encoded compact status response, excluding HTTP headers.
- TERMINAL_
RETENTION_ MS - WORKFLOW_
CHECKPOINT_ MAX_ BYTES - WORKFLOW_
CONTEXT_ MAX_ BYTES - WORKFLOW_
DECISION_ MAX_ BYTES - WORKFLOW_
EVENT_ COMMAND_ MAX_ BYTES - WORKFLOW_
EVENT_ MAX_ BYTES - WORKFLOW_
INPUTS_ MAX_ BYTES - WORKFLOW_
LOCAL_ LEDGER_ MAX_ BYTES - WORKFLOW_
LOCAL_ RECORD_ MAX_ BYTES - WORKFLOW_
MAX_ COMMANDS - WORKFLOW_
MAX_ DELAY_ MS - Relative waits are bounded to 365 days. Zero means immediately eligible.
- WORKFLOW_
MAX_ DEPTH - Root depth is zero. This bounds cancellation paths without a tree-wide lock.
- WORKFLOW_
MAX_ LIVE_ SUBWORKFLOWS - Limits simultaneous owned subworkflows, not retained historical child keys.
- WORKFLOW_
MAX_ LOCAL_ STEPS - WORKFLOW_
MAX_ PENDING_ EVENTS - WORKFLOW_
MAX_ WORK_ BATCH - WORKFLOW_
PENDING_ EVENTS_ MAX_ BYTES - WORKFLOW_
RUNTIME_ SCHEMA - WORKFLOW_
VERSION
Traits§
- AckQueue
- Receive and individually acknowledge transport records. The coordinator bounds records, bytes, and receipt sizes; these do not create additional execution concurrency. SDK prefetch/buffers must also have documented bounds.
- Acquisition
Wake - Optional adapter-to-service wake port. Implementations must return promptly without network I/O and bound retained interests. Periodic fallback remains necessary even when a transport delivers these hints.
- Completion
Sender - Completion
Service - Subscriber-facing operations. Accepted subscriptions survive caller disconnection.
- Completion
Store - Atomic registration and terminal hooks share the execution row lock. Delivery leasing only locks subscription rows; it must never lock executions afterward.
- Dispatch
Intent Store - Maintenance of durable delivery obligations. Implementations commit intent creation/invalidation atomically with the corresponding task transition. Publishing is external I/O and must never run while a state transaction is held. Finite leases and retry/repair delays are backend policy, not execution concurrency settings. Unknown operation outcomes are safe to retry.
- Dispatch
Publisher - Publish compact dispatch references. Implementations obey both their declared limits and the enclosing deadline. They must bound response bytes before allocation where the transport permits it. Partial responses are per item; absent, malformed, duplicate, or unexpected identities are never confirmation.
- Recovery
Store - Internal maintenance boundary, independent of worker/client delivery calls.
- Retention
Store - Task
Service - Service boundary implemented by future transport adapters. A successful mutation reply is permitted only after durable transactional acceptance.
- Task
Store - Persistence boundary for complete single-task lifecycle operations.
- Workflow
Service - Client and interactive-worker operations. Unsupported implementations must reject explicitly instead of silently submitting an ordinary task.
- Workflow
Store - Optional workflow persistence over the same transactional authority as the application’s task store. Implementations must atomically create tasks and dispatch obligations, append terminal completion work with task finalization, and apply checkpoints/child bindings/waits with their scheduling obligations. Separate, non-atomic task and workflow backends do not satisfy this port.
Functions§
- canonical_
json_ bytes - Deterministically encode an already validated JSON value for comparison.
- completion_
event_ id - completion_
result_ ref - decode_
completion_ correlation - decode_
unique_ json - Decode a bounded JSON command without losing duplicate keys or large integers.
- encode_
completion_ correlation - Encode the rare accepted business strings excluded by CloudEvents metadata.
- validate_
task_ output - Controller results include a platform decision envelope around application values. Ordinary task output retains its depth-64 contract; registered activations allow metadata depth 96 before the coordinator validates each application value and the exact decision shape. The lifecycle core verifies the report’s activation identity against the acquired task before acceptance.
- validate_
text - Identifier/reference text stored in indexed platform columns.
- validate_
workflow_ error - validate_
workflow_ lineage - Nested lineage is paired and immutable. Roots/legacy runs omit both fields.
Type Aliases§
- Contract
Future - Result
- Timestamp
- UTC milliseconds since the Unix epoch, supplied by the authoritative store.
- Workflow
Task Command - Compatibility name for the original task-only command contract.