feat(api): define v1 control-plane contract

2026-07-16 10:58:05 +08:00
parent aa3c3f9803
commit a86970d33b
14 changed files with 3234 additions and 4 deletions
@@ -0,0 +1,79 @@
+import type { ProblemDetails } from './errors.js';
+import type { PageEnvelope, PageQuery } from './instances.js';
+
+export const JOB_STATUSES = [
+  'queued',
+  'running',
+  'cancelling',
+  'succeeded',
+  'partially-succeeded',
+  'failed',
+  'cancelled',
+  'unknown-result',
+] as const;
+export const JOB_TERMINAL_STATUSES = [
+  'succeeded',
+  'partially-succeeded',
+  'failed',
+  'cancelled',
+  'unknown-result',
+] as const;
+export const ATTEMPT_STATUSES = [
+  'running',
+  'succeeded',
+  'failed',
+  'cancelled',
+  'unknown-result',
+] as const;
+export const JOB_ITEM_TERMINAL_STATES = [
+  'succeeded',
+  'failed',
+  'skipped',
+  'cancelled',
+  'unknown-result',
+] as const;
+export type JobStatus = (typeof JOB_STATUSES)[number];
+export type JobTerminalStatus = (typeof JOB_TERMINAL_STATUSES)[number];
+export type AttemptStatus = (typeof ATTEMPT_STATUSES)[number];
+export type JobItemTerminalState = (typeof JOB_ITEM_TERMINAL_STATES)[number];
+
+/** Each item reaches an independent terminal state and may carry its own redacted error. */
+export interface JobItem {
+  readonly id: string;
+  readonly targetId: string;
+  readonly state: JobItemTerminalState;
+  readonly sourceJobItemId?: string;
+  readonly error?: ProblemDetails;
+}
+/** Attempt results are immutable. User retry creates a new Job and independent Attempt. */
+export interface Attempt {
+  readonly id: string;
+  readonly state: AttemptStatus;
+  readonly startedAt: string;
+  readonly finishedAt?: string;
+}
+/** Terminal Jobs, JobItems, Attempts, and events are immutable; retry creates a new lineage Job. */
+export interface Job {
+  readonly id: string;
+  readonly operationId: string;
+  readonly status: JobStatus;
+  readonly retryOfJobId?: string;
+  readonly rootJobId: string;
+  readonly items: readonly JobItem[];
+  readonly attempts: readonly Attempt[];
+  readonly createdAt: string;
+}
+export interface JobFilters {
+  readonly status?: JobStatus;
+  readonly operationId?: string;
+  readonly rootJobId?: string;
+  readonly instanceId?: string;
+}
+export type JobPageQuery = PageQuery<'createdAt' | 'status' | 'operationId'> & JobFilters;
+export type JobPage = PageEnvelope<Job>;
+
+export interface RetryJobRequest {
+  readonly itemIds: readonly string[];
+  readonly preparationId: string;
+  readonly confirmationToken: string;
+}