Crate ledgence_orchestration_api 

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

AcceptedSettlement

AckResult

AcquireCommand

AcquireOptions

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.

AcquisitionKey

AcquisitionQueue

ApplicationError

Application error identifiers are user-defined, unlike worker error kinds.

Assignment

AttemptRef

AttemptSnapshot

Authority

Current authority sampled for this response; never replay a cached TTL.

ClaimCommand

The session, consumer, and sequence identify one claim operation. Its exact dispatch binding is immutable even if the exchange outcome is unknown.

ClaimReply

Every successful disposition consumes the claim sequence and is persisted with its exact command. Receipts survive subsequent consumer-cursor updates.

CompletionDeliveryResult

CompletionDestination

Operator-configured immutable binding. Core does not interpret transport settings.

CompletionEvent

Compact reference-only CloudEvent: no application result copy and no platform data. Event identity and bytes remain unchanged across retries and manual redelivery.

CompletionLease

CompletionRetryCommand

CompletionSubscribeCommand

CompletionSubscription

ConsumerCursor

Compact replay state: only the latest completed poll per consumer is retained.

DispatchRef

One readiness generation. Retransmission preserves this identity; a retry made eligible by the lifecycle advances the generation.

DispatchRoute

External routing binds a logical queue to a stable opaque destination alias. Provider URLs, credentials, and SDK options belong in adapter configuration.

HistoryEvent

Persist with the accompanying records. Per-task ordering is assigned under the same task lock; heartbeat renewals do not append history rows.

Lease

LeaseOwner

LocalResultCommand

LocalResultReceipt

LocalStepRecord

PublicationCompletion

PublicationLease

A bounded publication reservation. It contains no task execution authority.

PublishResult

PublishedDispatch

Publication identity remains unchanged across uncertain send retries. A deliberate repair publication gets a new identity for the same generation.

QueueDelivery

Individual-ack delivery model. A stream checkpoint requires a separate port; implementations must not disguise prefix commits as arbitrary receipt deletes.

QueueLimits

Configured transport bounds. These advertise capacities, not ordering, scheduling, deduplication, durability, or exactly-once execution promises.

RecordedHistoryEvent

RecoveryProgress

Committed progress from one bounded recovery operation.

RenewCommand

ResolvedWorkflowChild

RetentionPolicy

Applies to terminal executions and the latest terminal callback activity. Existing retiring records continue physical collection under any later policy.

RetentionPreview

Bounded age candidates only; protective references can defer collection.

RetentionProgress

One bounded transaction. Zero removed rows does not mean the database has no retained records: protection, cursor rotation, or a new retirement can occur.

RetryPolicy

Fixed-delay retry policy, including the initial attempt in max_attempts.

Scope

SettleCommand

SettleReply

SettlementReceipt

SubmitCommand

SubmitTask

A request to create one logical task, before assigning run or attempt IDs.

TaskFilters

Exact metadata filters. Submission bounds are inclusive from, exclusive until.

TaskListQuery

One bounded read. Cursors bind the scope and filters, but allow a new page size.

TaskPage

A coherent committed view for this read; later pages use later read snapshots.

TaskPosition

Immutable seek key, ordered by submission time and then UTF-8 task ID bytes.

TaskResult

One coherent task observation. Pending is distinct from successful JSON null.

TaskSnapshot

Transaction-loaded scheduling record. Inputs and the descriptor are immutable.

TaskStatus

Scheduling metadata without application input, output, or package payloads.

TraceContext

Origin and processing contexts have the same wire format but different lifetimes.

WorkerSession

Sessions are issued by the service and never recreated by acquisition. Unknown/expired session IDs are rejected even after old cursor deletion.

WorkflowActivationContext

Frozen activation inputs and checkpoint, plus the current committed journal. New child completions do not mutate the frozen input batch or revision.

WorkflowChildCommand

WorkflowDecision

WorkflowEvent

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.

WorkflowEventCommand

WorkflowEventReceipt

Durable acceptance, not a promise that a controller has processed the event. accepted_at is immutable across reconciliation and comes from store time.

WorkflowProgress

WorkflowResult

WorkflowSnapshot

WorkflowSubworkflowResult

WorkflowTaskResult

WorkflowWork

Enums

AcquireReply

AcquisitionCompletion

Internal provenance prevents replayed assignments from implying more backlog.

AcquisitionHint

Hints carry identities only. They never grant execution authority or cache a reply. A rescan follows notification subscription/reconnection.

AcquisitionProbe

AttemptReport

AttemptState

ClaimDisposition

CompletionDeliveryOutcome

CompletionState

CompletionTarget

ContractError

Expected operation rejection or an adapter failure. Backend errors must not be translated into successful empty acquisitions or lost ownership.

PublicationOutcome

Quiescence

Required invocation cleanup is done; a healthy warm process may still exist.

RenewIntent

TaskFailure

TaskOutcome

Terminal scheduling outcome. Cancellation never attributes an earlier attempt.

TaskState

TransitionReason

WorkflowAction

WorkflowChildKind

WorkflowChildResult

Legacy task inputs retain their wire shape. Workflow inputs have an explicit kind and workflow outcome. Both variants reject mixed or unknown fields.

WorkflowOutcome

WorkflowState

WorkflowWait

A single named rendezvous. Keys are one-shot across a workflow, so callbacks from an earlier iteration cannot accidentally satisfy a later wait.

WorkflowWake

Immutable next-activation input selected under workflow authority. At an event deadline, only store acceptance strictly before the deadline wins.

WorkflowWorkSource

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.

AcquisitionWake

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.

CompletionSender

CompletionService

Subscriber-facing operations. Accepted subscriptions survive caller disconnection.

CompletionStore

Atomic registration and terminal hooks share the execution row lock. Delivery leasing only locks subscription rows; it must never lock executions afterward.

DispatchIntentStore

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.

DispatchPublisher

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.

RecoveryStore

Internal maintenance boundary, independent of worker/client delivery calls.

RetentionStore

TaskService

Service boundary implemented by future transport adapters. A successful mutation reply is permitted only after durable transactional acceptance.

TaskStore

Persistence boundary for complete single-task lifecycle operations.

WorkflowService

Client and interactive-worker operations. Unsupported implementations must reject explicitly instead of silently submitting an ordinary task.

WorkflowStore

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

ContractFuture

Result

Timestamp

UTC milliseconds since the Unix epoch, supplied by the authoritative store.

WorkflowTaskCommand

Compatibility name for the original task-only command contract.