# Data Model: Jobs Control Plane

## Job Provider

Represents a participant that can accept one or more long-running job types.

**Fields**:
- `providerId`: stable participant id, unique within the jobs domain.
- `pluginId`: owning plugin id or `core`.
- `label`: redaction-safe display label.
- `supportedJobTypes`: list of job type ids the provider can handle.
- `supportedActions`: subset of `enqueue`, `inspect`, `cancel`, `pause`, `resume`, `retry`, `recover`.
- `availability`: `available`, `unavailable`, `degraded`, `disabled`, or `incompatible`.
- `capacity`: provider-declared running and queued limits.
- `currentLoad`: running/queued counts visible to scheduling.
- `selectionEligible`: whether the provider can be user-selected/default for a job type.
- `recoverySupport`: provider-level summary of reload recovery support.
- `safeReason`: bounded redaction-safe reason for unavailable/degraded/incompatible state.
- `lastSeenAt`: timestamp of latest registration/status update.

**Validation rules**:
- `providerId` must be stable and unique.
- Unsupported or incompatible provider versions must not accept new jobs.
- Repeated registration for the same provider updates the record instead of creating duplicates.
- Capacity values must be non-negative and must not be exceeded by scheduler decisions.

## Job Requester

Represents a user action, plugin, or app workflow that asks for job work.

**Fields**:
- `requesterId`: stable requester id.
- `pluginId`: plugin id, `core`, or `user`.
- `kind`: `user`, `plugin`, `core-workflow`, `background`, or `compatibility`.
- `displayLabel`: redaction-safe requester label.
- `authorization`: `user-action`, `approved-continuation`, `background`, or `none`.

**Validation rules**:
- Privileged enqueue requires `user-action` or an approved continuation matching the approval scope.
- Background requesters may list/inspect but may not start privileged work without approval.

## Job Approval Scope

Represents what one explicit user approval covers.

**Fields**:
- `approvalId`: ephemeral approval id.
- `providerId`: provider covered by approval.
- `jobType`: job type covered by approval.
- `targetRef`: redaction-safe target identity.
- `requesterId`: requester covered by approval.
- `inputFingerprint`: redaction-safe fingerprint for approved inputs.
- `allowsRetry`: whether provider-declared retry attempts can reuse approval.
- `allowsContinuation`: whether provider-declared continuation attempts can reuse approval.
- `createdAt`: approval timestamp.

**Validation rules**:
- Approval cannot widen across provider, job type, target, requester, or inputs.
- Retry/continuation use is allowed only when the provider declares it and the scope still matches.

## Selected Job Provider

Represents the user-selected/default provider for a job type when multiple providers are compatible.

**Fields**:
- `jobType`: job type id.
- `providerId`: selected/default provider id.
- `source`: `user-selected`, `default`, or `request-explicit`.
- `updatedAt`: timestamp.

**Validation rules**:
- If exactly one compatible provider exists, explicit selection is not required.
- If multiple compatible providers exist, enqueue requires a selected/default/explicit provider or returns `provider-selection-required`.
- Selection must not point to unavailable or incompatible providers for new work.

## Job

Represents a user-visible unit of long-running work.

**Fields**:
- `jobId`: stable job id.
- `jobType`: conversion, import, update, preview, studio, compatibility-backed, or future typed work.
- `providerId`: provider handling the job.
- `requesterId`: requester that enqueued the job.
- `targetRef`: redaction-safe target identity.
- `state`: current lifecycle state.
- `priority`: `user-approved-interactive` or `background-maintenance`.
- `safeLabel`: redaction-safe display label.
- `progress`: latest progress snapshot.
- `attempts`: ordered job attempt ids.
- `retryable`: whether retry is currently allowed.
- `actionsAvailable`: currently valid user/requester actions.
- `createdAt`, `queuedAt`, `startedAt`, `updatedAt`, `terminalAt`: timestamps.
- `terminalOutcome`: terminal outcome when state is terminal.
- `safeReason`: bounded reason for current or terminal state.
- `bridgeSource`: compatibility bridge source when applicable.

**Validation rules**:
- `jobId` must remain stable across progress updates and supported recovery.
- State updates after terminal state are stale unless tied to a newer retry attempt.
- Queued jobs can cancel immediately and must not start later.
- Running cancellation enters `cancellation-requested` until provider terminal report.

## Job Attempt

Represents one run of a job, including retries.

**Fields**:
- `attemptId`: stable attempt id.
- `jobId`: parent job id.
- `attemptNumber`: 1-based attempt number.
- `providerId`: provider running the attempt.
- `approvalScopeId`: approval scope used for this attempt.
- `state`: attempt state.
- `startedAt`, `updatedAt`, `terminalAt`: timestamps.
- `terminalOutcome`: terminal attempt outcome.

**Validation rules**:
- Retry attempts must link to the original job.
- Retry requires terminal parent state and matching approval scope or new user approval.
- Only one active retry attempt may exist for a job at a time.

## Scheduling Policy

Represents provider capacity and ordering behavior.

**Fields**:
- `providerId`: provider whose queue is governed.
- `maxRunning`: maximum simultaneous running jobs.
- `maxQueued`: optional maximum queued jobs.
- `priorityOrder`: user-approved interactive before background/maintenance.
- `withinPriorityOrder`: FIFO.
- `blockedReason`: safe reason when queued work cannot start.

**Validation rules**:
- Running jobs must not exceed `maxRunning`.
- Background jobs cannot start ahead of queued user-approved interactive jobs for the same provider capacity.
- FIFO order applies inside each priority class unless jobs are cancelled or become invalid.

## Progress Snapshot

Represents latest progress for a job.

**Fields**:
- `mode`: `determinate`, `indeterminate`, or `step-only`.
- `percent`: number from 0 to 100 when determinate.
- `step`: redaction-safe current step id or label.
- `message`: bounded redaction-safe message.
- `updatedAt`: timestamp.

**Validation rules**:
- Determinate progress must stay in range 0..100.
- Decreasing progress is flagged unless provider marks a new step/attempt.
- Progress after terminal state is stale unless tied to a newer attempt.

## Terminal Outcome

Represents final state and reason.

**Fields**:
- `status`: `completed`, `cancelled`, `failed`, `timeout`, `provider-unavailable`, or `orphaned`.
- `category`: invalid-input, permission-denied, provider-unavailable, unsupported-operation, timeout, cancellation, external-dependency, storage, provider-failure, or unknown.
- `retryable`: boolean.
- `safeReason`: bounded redaction-safe reason.
- `resultSummary`: redaction-safe completion summary.

**Validation rules**:
- Terminal outcome must not expose raw artifacts, paths, command lines, tokens, native handles, or provider-private payloads.
- Terminal state is final for an attempt; retries create a new attempt.

## Job Diagnostic Log Entry

Represents bounded log/progress history.

**Fields**:
- `entryId`: local sequence id.
- `jobId`: associated job.
- `attemptId`: associated attempt when known.
- `kind`: `progress`, `log`, `warning`, `error`, or `event`.
- `message`: redacted bounded text.
- `timestamp`: timestamp.

**Validation rules**:
- Per-job progress/log history is capped at 50 entries or stricter support snapshot trimming.
- Entries must be redacted before export.

## Compatibility Bridge Hit

Represents legacy job-like behavior observed during migration.

**Fields**:
- `bridgeId`: stable bridge id.
- `providerId`: associated provider when known.
- `jobId`: associated job when known.
- `legacySurface`: plugin queue, status view, backend route, or compatibility status source.
- `operation`: observed operation.
- `timestamp`: timestamp.
- `safeReason`: bounded reason.

**Validation rules**:
- Bridge hits are diagnostics; they must not become a second user-visible job when a native provider describes the same logical job.

## State Transitions

```text
queued -> running
queued -> cancelled
queued -> provider-unavailable
queued -> orphaned
running -> progress-updated -> running
running -> cancellation-requested
running -> paused
running -> completed
running -> failed
running -> provider-unavailable
running -> orphaned
cancellation-requested -> cancelled
cancellation-requested -> completed
cancellation-requested -> failed
paused -> queued
paused -> running
paused -> cancelled
paused -> provider-unavailable
paused -> orphaned
failed -> retry-started -> queued
cancelled -> retry-started -> queued
completed -> terminal
provider-unavailable -> retry-started -> queued when retryable
orphaned -> retry-started -> queued when retryable
```

Terminal attempt states are `completed`, `cancelled`, `failed`, `timeout`, `provider-unavailable`, and `orphaned`. A retry creates a new attempt linked to the original job rather than mutating the prior attempt.