# Jobs API
URL: /runtime/api/jobs



# Jobs API [#jobs-api]

Import from `@taucad/runtime/job`. Jobs bind an immutable input revision and admitted provider configuration to a durable `JobReference`; provider execution is separate from submission and query surfaces.

## Submission and projection [#submission-and-projection]

`JobSubmitInput` selects `JobProviderIdentity`, a `JobRevision`, literal `JobInput` files, `JobConfigurationInput`, and a caller-retained `submissionKey`. Explicit RFC 6901 presence pointers distinguish an omitted field from a supplied value. `parseJobSubmitInput` checks an untrusted submission before admission. `JobSubmitOutcome` includes the key and host identity needed to reconcile a lost reply; do not resubmit under a new key solely because the first response was lost.

`JobEffectiveConfiguration` is the immutable admitted configuration. `JobSnapshot` projects `JobLifecycleState` from durable facts; it is not an editable record. `JobValidationIssue` identifies invalid submitted fields. `reduceJobSnapshot` folds `JobAcceptedEvent` and subsequent `JobLifecycleEvent` values into a projection; `JobProjectionEvent` names its public event union. The host, not provider progress callbacks, owns lifecycle transitions.

## Provider descriptor and execution [#provider-descriptor-and-execution]

`defineJobProvider` attaches a trusted `JobProviderDefinition` to a callable `JobProviderFactory`. Its serializable `JobProviderDescriptor` (also exposed as `JobProviderRegistration`) declares id, kind/version, configuration manifest, result schema, capability requirements, artifacts, recovery policy, queries, and commands. `JobArtifactDeclaration` bounds each artifact role and media type. `JobRecoveryDescriptor` chooses restart from sealed input, checkpoint, or reconciliation of an external effect.

The `/plugin` type `ExpandPluginJobs` preserves the job provider tuple when a runtime combines plugin factories.

Execution receives `JobProviderExecuteInput` and fenced `JobProviderAttemptServices`: a rooted workspace, abort signal, attempt identity, progress/log methods, artifact publication, and conditional checkpoint publication. `JobProgressUpdate` and `JobLogEntry` are bounded observations, not lifecycle authority. `publishArtifact` returns an immutable `JobPublishedArtifact`; checkpoint-capable providers pass `JobCheckpointPublication` and may resume with `JobProviderResumeContext`.

## Provider extensions [#provider-extensions]

`defineJobQuery` preserves the correlated schemas and handler type of a read-only `JobQueryDefinition`. `defineJobCommand` does the same for a stateful `JobCommandDefinition`. Their serializable `JobExtensionDescriptor` and `JobCommandDescriptor` advertise names and schemas. A command declares `JobCommandReplayPolicy`: `replay-safe`, `reconcile-required`, or `non-replayable`. Choose a policy that matches what the provider can prove after a crash; a retry cannot invent success.

## Related [#related]

* [Configuration API](/runtime/api/configuration)
* [Host admission API](/runtime/api/host)
* [Runtime architecture](/runtime/concepts/architecture)