@wildo-ai/saas-models 1.1.4 → 1.1.6

package/dist/esm/queue/jobs.shared.schemas.js

@@ -11,6 +11,8 @@
  * - Proper indexes for common query patterns
  */
 import { z } from 'zod';
+import { ModelCallAttributionInputSchema } from '../flows-actors/work-attribution.shared.schemas.js';
+import { DataMode } from '../resources/resources-config.shared.schemas.js';
 import { initZodDecorators } from '@wildo-ai/zod-decorators';
 import { WildoError_BackendSchema, RetryPolicy_BackoffType } from '../errors/errors.shared.schemas.js';
 // Ensure Zod decorators are loaded
@@ -210,9 +212,193 @@ export const QueueRetryBackoffConfigSchema = z.object({
     /** Backoff curve: `fixed` | `linear` | `exponential`. Defaults to `exponential`. */
     retryPolicy: z.enum(RetryPolicy_BackoffType).optional(),
 });
+/** @wildo_source:part:start saas.models.queue.scheduled-recovery facet:layer:shared facet:audience:app-developer */
+/** First receipt is short-lived; persisted recovery has its own policy deadline. */
+export const SCHEDULED_INITIAL_ADMISSION_MAX_AGE_MS = 5 * 60 * 1000;
+export const SCHEDULED_INITIAL_ADMISSION_FUTURE_SKEW_MS = 30 * 1000;
+/** How the handler's complete effects tolerate execution after an uncertain outcome. */
+export var ScheduledReplaySafety;
+(function (ScheduledReplaySafety) {
+    /** No automatic repetition; a failed call can already have committed effects. */
+    ScheduledReplaySafety["MANUAL"] = "manual";
+    /** All effects use stable business keys or equivalent idempotency mechanisms. */
+    ScheduledReplaySafety["IDEMPOTENT"] = "idempotent";
+    /** A backend reconciler must establish completion or safety before repetition. */
+    ScheduledReplaySafety["RECONCILE"] = "reconcile";
+})(ScheduledReplaySafety || (ScheduledReplaySafety = {}));
+/** Durable admission phase, independent from the presentation status of a job. */
+export var ScheduledExecutionPhase;
+(function (ScheduledExecutionPhase) {
+    ScheduledExecutionPhase["READY"] = "ready";
+    ScheduledExecutionPhase["RUNNING"] = "running";
+    ScheduledExecutionPhase["RECONCILING"] = "reconciling";
+    ScheduledExecutionPhase["WAITING"] = "waiting";
+    ScheduledExecutionPhase["REVIEW"] = "review";
+    ScheduledExecutionPhase["FINISHED"] = "finished";
+})(ScheduledExecutionPhase || (ScheduledExecutionPhase = {}));
+export var ScheduledReconciliationOutcome;
+(function (ScheduledReconciliationOutcome) {
+    ScheduledReconciliationOutcome["COMPLETED"] = "completed";
+    ScheduledReconciliationOutcome["SAFE_TO_RETRY"] = "safe_to_retry";
+    ScheduledReconciliationOutcome["INCONCLUSIVE"] = "inconclusive";
+})(ScheduledReconciliationOutcome || (ScheduledReconciliationOutcome = {}));
+/** Operator decisions are distinct from evidence returned by a handler's reconciler. */
+export var ScheduledReviewOutcome;
+(function (ScheduledReviewOutcome) {
+    ScheduledReviewOutcome["CONFIRM_COMPLETED"] = "confirm_completed";
+    ScheduledReviewOutcome["RETRY"] = "retry";
+    ScheduledReviewOutcome["ABANDON"] = "abandon";
+})(ScheduledReviewOutcome || (ScheduledReviewOutcome = {}));
+/** A declaration is a contract, not a mechanism that makes side effects idempotent. */
+export const ScheduledRecoveryPolicySchema = z.object({
+    contractVersion: z.string().min(1).default('1'),
+    replaySafety: z.enum(ScheduledReplaySafety).default(ScheduledReplaySafety.MANUAL),
+    retryReportedFailures: z.boolean().default(false),
+    /** Total admissions, including reconciliation; initial execution consumes one. */
+    maxAttempts: z.number().int().min(1).max(100).default(1),
+    /** Elapsed horizon from first authenticated receipt, never extended by recovery. */
+    maxRecoveryMs: z.number().int().min(1000).max(30 * 24 * 60 * 60 * 1000).default(24 * 60 * 60 * 1000),
+    /** Heartbeat lease: expiry means contact was lost, not that the old worker stopped. */
+    leaseMs: z.number().int().min(3000).max(60 * 60 * 1000).default(60000),
+    backoff: QueueRetryBackoffConfigSchema.optional(),
+    jitterRatio: z.number().min(0).max(1).default(0.2),
+}).superRefine((policy, ctx) => {
+    if (policy.retryReportedFailures && policy.replaySafety === ScheduledReplaySafety.MANUAL) {
+        ctx.addIssue({ code: 'custom', path: ['retryReportedFailures'], message: 'Automatic retry requires idempotent effects or reconciliation.' });
+    }
+});
+export function normalizeScheduledRecoveryPolicy(policy) {
+    return ScheduledRecoveryPolicySchema.parse(policy ?? {});
+}
+/** Finite, application-owned evidence policy. No policy means no long-term projection. */
+export const ScheduledEvidencePolicySchema = z.object({
+    policyRef: z.string().trim().min(1).max(160),
+    /** Absolute expiry is completion plus this duration, never the date an archive retry succeeds. */
+    retainForMs: z.number().int().min(86400000).max(3650 * 86400000),
+    /** Only these top-level scalar result fields may enter retained evidence. */
+    resultFields: z.array(z.string().regex(/^[A-Za-z][A-Za-z0-9_]*$/).max(80)).max(32),
+    /** Selected boolean flag identifying deferred business work independently from invocation success. */
+    deferredField: z.string().min(1).optional(),
+}).superRefine((policy, ctx) => {
+    if (new Set(policy.resultFields).size !== policy.resultFields.length)
+        ctx.addIssue({ code: 'custom', message: 'Evidence result fields must be unique' });
+    if (policy.deferredField && !policy.resultFields.includes(policy.deferredField)) {
+        ctx.addIssue({ code: 'custom', path: ['deferredField'], message: 'Deferred flag must be a selected result field' });
+    }
+});
+export var ScheduledEvidenceSource;
+(function (ScheduledEvidenceSource) {
+    ScheduledEvidenceSource["EXECUTION"] = "execution";
+    ScheduledEvidenceSource["RECONCILIATION"] = "reconciliation";
+    ScheduledEvidenceSource["OPERATOR_CONFIRMATION"] = "operator_confirmation";
+    ScheduledEvidenceSource["ABANDONMENT"] = "abandonment";
+})(ScheduledEvidenceSource || (ScheduledEvidenceSource = {}));
+export var ScheduledEvidenceResultStatus;
+(function (ScheduledEvidenceResultStatus) {
+    ScheduledEvidenceResultStatus["CAPTURED"] = "captured";
+    ScheduledEvidenceResultStatus["UNAVAILABLE"] = "unavailable";
+})(ScheduledEvidenceResultStatus || (ScheduledEvidenceResultStatus = {}));
+/**
+ * Bounded projection, not arbitrary job input, output or exception text.
+ *
+ * `applicationId` is the application RECORD id (`applications._id`), projected from the job row it
+ * describes — never the platform id the wire payload carried. The coverage report refuses a record
+ * whose value differs from its scope, so a copy of this field retained under the wrong id is not
+ * merely stale: it makes every window that reaches it fail (the follow-up migration of #1296).
+ */
+const ScheduledRunEvidenceFieldsSchema = z.object({
+    jobId: z.uuid(), applicationId: z.string().min(1), queueName: z.string().min(1),
+    jobType: z.enum(JobType), batchRef: z.string().optional(), operationPathKey: z.string().optional(), minionName: z.string().optional(),
+    scheduledAt: z.date().optional(), publishedAt: z.date(), startedAt: z.date().optional(), completedAt: z.date(), expiresAt: z.date(),
+    invocationStatus: z.enum(JobExecutionStatus), source: z.enum(ScheduledEvidenceSource),
+    attemptCount: z.number().int().nonnegative(), policy: ScheduledEvidencePolicySchema,
+    resultStatus: z.enum(ScheduledEvidenceResultStatus), deferred: z.boolean().optional(),
+    results: z.record(z.string(), z.union([z.string().max(512), z.number().finite(), z.boolean(), z.null()])),
+});
+export const ScheduledRunEvidenceSchema = ScheduledRunEvidenceFieldsSchema.superRefine((evidence, ctx) => {
+    const targetCount = [evidence.batchRef, evidence.operationPathKey, evidence.minionName].filter(value => value !== undefined).length;
+    if (targetCount !== 1 || (evidence.jobType === JobType.MINION_TICK ? !evidence.minionName
+        : evidence.jobType !== JobType.SCHEDULED_CRON || !(evidence.batchRef || evidence.operationPathKey))) {
+        ctx.addIssue({ code: 'custom', message: 'Evidence requires exactly one scheduled batch, operation or minion target' });
+    }
+    const expectedStatus = evidence.source === ScheduledEvidenceSource.ABANDONMENT ? JobExecutionStatus.FAILED : JobExecutionStatus.COMPLETED;
+    if (evidence.invocationStatus !== expectedStatus) {
+        ctx.addIssue({ code: 'custom', path: ['invocationStatus'], message: 'Terminal outcome must agree with evidence source' });
+    }
+    if (evidence.expiresAt.getTime() !== evidence.completedAt.getTime() + evidence.policy.retainForMs) {
+        ctx.addIssue({ code: 'custom', path: ['expiresAt'], message: 'Evidence expiry must follow the captured policy and original completion' });
+    }
+    const fields = Object.keys(evidence.results);
+    if (fields.some(field => !evidence.policy.resultFields.includes(field))) {
+        ctx.addIssue({ code: 'custom', path: ['results'], message: 'Only policy-selected result fields may be retained' });
+    }
+    if (evidence.resultStatus === ScheduledEvidenceResultStatus.CAPTURED && evidence.policy.resultFields.some(field => !Object.hasOwn(evidence.results, field))) {
+        ctx.addIssue({ code: 'custom', path: ['resultStatus'], message: 'Captured evidence requires every selected field' });
+    }
+    const selectedDeferred = evidence.policy.deferredField ? evidence.results[evidence.policy.deferredField] : undefined;
+    if (evidence.deferred !== (typeof selectedDeferred === 'boolean' ? selectedDeferred : undefined)
+        || (evidence.resultStatus === ScheduledEvidenceResultStatus.CAPTURED && evidence.policy.deferredField && typeof selectedDeferred !== 'boolean')) {
+        ctx.addIssue({ code: 'custom', path: ['deferred'], message: 'Deferral must agree with the selected boolean result' });
+    }
+});
+/** @wildo_source:part:end saas.models.queue.scheduled-recovery */
+/** Persisted inside JobExecution; trusted only after authenticated receipt and local policy resolution. */
+export const ScheduledExecutionStateSchema = z.object({
+    phase: z.enum(ScheduledExecutionPhase),
+    revision: z.number().int().nonnegative(),
+    payloadJson: z.string(),
+    policy: ScheduledRecoveryPolicySchema,
+    /** Selected once from local application policy, independent from replay safety. */
+    evidencePolicy: ScheduledEvidencePolicySchema.optional(),
+    /** Terminal-CAS projection retried by the bounded operational archive outbox. */
+    evidence: ScheduledRunEvidenceSchema.optional(),
+    evidenceArchived: z.boolean().optional(),
+    evidenceArchiveAfter: z.date().optional(),
+    deadline: z.date(),
+    nextAttemptAt: z.date(),
+    owner: z.uuid().optional(),
+    attemptCount: z.number().int().min(0).max(100),
+    /** A successful reconciliation authorizes exactly the next execution admission. */
+    reconciledSafe: z.boolean().default(false),
+    reason: z.string().optional(),
+    attempts: z.array(z.object({
+        attemptId: z.uuid(),
+        phase: z.enum(ScheduledExecutionPhase),
+        startedAt: z.date(),
+        endedAt: z.date().optional(),
+        outcome: z.string().optional(),
+    })).max(100),
+    /** Explicit operator decisions preserve the occurrence, attribution and reason. */
+    resolutions: z.array(z.object({ actor: z.string(), reason: z.string(), at: z.date(), outcome: z.enum(ScheduledReviewOutcome) })).max(100).default([]),
+});
 // ============================================================================
 // JOB PAYLOAD SCHEMA (Transport - not a resource)
 // ============================================================================
+/**
+ * Caller-selected response semantics that must survive resource-operation worker replay.
+ * This is deliberately not RepositoryOptions: transactions, authorization overrides and
+ * server-owned mutation fields are not presentation policy and must never enter this object.
+ * Unknown keys are stripped at enqueue and replay, even for structurally wider service options.
+ * Variant identity is already carried by operationPathJson; page/filter/sort remain input data.
+ */
+export const JobResourceResponseOptionsSchema = z.object({
+    /** Preserve the repository's real pagination envelope rather than returning a raw array. */
+    paginated: z.boolean().optional(),
+    /** Preserve the caller's requested population/data shape. */
+    dataMode: z.enum(DataMode).optional(),
+    /** Preserve an explicit request to omit signed file URL population. */
+    populateFiles: z.boolean().optional(),
+});
+/**
+ * Accepted mutation preconditions travel independently from response presentation.
+ * Dropping either value makes worker execution accept writes the inline request rejects.
+ * This whitelist intentionally excludes transactions and authorization overrides; unknown
+ * keys are stripped at publication and replay. Zero is a valid expected version.
+ */
+export const JobResourceMutationPreconditionsSchema = z.object({
+    ifMatchVersion: z.number().int().nonnegative().optional(),
+    fieldTimestamps: z.record(z.string(), z.number().positive()).optional(),
+});
 /**
  * Job payload for queue transport.
  *
@@ -229,7 +415,16 @@ export const JobPayloadSchema = z.object({
     /** Type of job being executed */
     jobType: z.enum(JobTypeValues),
     // === Application Routing ===
-    /** Application ID for queue name construction */
+    /**
+     * The PLATFORM's id for the application — the value queue names are built from, the value the
+     * crontabs-manager signs into a scheduled message, and the value a consumer verifies a message
+     * against before accepting it. It is an ADDRESS on the wire.
+     *
+     * It is NOT the application record id (`applications._id`) and must never be copied into a row:
+     * `JobExecution.applicationId` and `JobPayloadStorage.applicationId` are stamped by the backend's
+     * tracker and payload store from the canonical identity. Copying this wire value into those rows is
+     * what anchored 13,532 Wonder Todos rows to an id no scope predicate matches (fixed 2026-09-18).
+     */
     applicationId: z.string(),
     // === Operation Identification ===
     /** Primary key for lookup/matching (required for RESOURCE_OPERATION) */
@@ -238,6 +433,12 @@ export const JobPayloadSchema = z.object({
     operationPathJson: z.string().optional(),
     /** Custom batch reference (required for CUSTOM_BATCH) */
     batchRef: z.string().optional(),
+    /** Local minion target; checked before receipt is admitted. */
+    minionName: z.string().optional(),
+    /** Response policy only; absent retains ordinary internal-service defaults. */
+    resourceResponseOptions: JobResourceResponseOptionsSchema.optional(),
+    /** Optimistic-locking and CRDT guards accepted by the initiating request. */
+    resourceMutationPreconditions: JobResourceMutationPreconditionsSchema.optional(),
     // === Execution Data ===
     // EITHER inline OR storage reference (mutually exclusive)
     /** JSON-stringified input data for small payloads (<100KB) */
@@ -246,6 +447,20 @@ export const JobPayloadSchema = z.object({
     inputPayloadStorageId: z.uuid().optional(),
     /** Resource ID for READ/UPDATE/DELETE operations */
     inputId: z.string().optional(),
+    /**
+     * The rows a BULK operation targets, resolved before the job was enqueued.
+     *
+     * `inputId` cannot carry them — it is one id — so a bulk operation sent to the background lane
+     * used to arrive at the worker with NO target at all: the selector is stripped from `inputData`
+     * once the service has read it, and a single-id field has nowhere to put an array. The worker
+     * then replayed a targetless write (#1461).
+     *
+     * Mutually exclusive with `inputId` by construction: the enqueue splits one target into whichever
+     * field can hold it. The worker runs the bulk PER ROW from this list, so each row gets the
+     * single-row operation's own semantics — pre-image, `enabledCondition`, one audit record, one
+     * resource-room sync event — and the job's result reports what happened to each.
+     */
+    inputIds: z.array(z.string().min(1)).min(1).optional(),
     // === Execution Context ===
     /**
      * Serialized execution context (reconstructed on worker side).
@@ -270,12 +485,17 @@ export const JobPayloadSchema = z.object({
      * durable broker delay queue before redelivery — see `QueueRetryBackoffConfig`.
      */
     retryConfig: QueueRetryBackoffConfigSchema.optional(),
-    /** Job execution timeout in milliseconds */
+    /** Reply-wait policy carried with the job. The executor does not enforce this as an execution deadline;
+     * fire-and-forget jobs have no waiting caller to time out. */
     timeoutMs: z.number().int().min(1000).default(300000),
     // === Timing ===
     /** When the job was created */
     createdAt: z.date(),
-    /** When the job should be executed (for delayed jobs) */
+    /**
+     * Intended execution instant for delayed jobs or the authenticated scheduled instant of a cron occurrence.
+     * Distinct from publication/receipt time. New manual cron invocations omit it; historical absence
+     * can also mean the occurrence time was not retained and must not be treated as proof of a manual run.
+     */
     scheduledAt: z.date().optional(),
     // === RPC Support ===
     /**
@@ -298,6 +518,17 @@ export const JobPayloadSchema = z.object({
      * originating request (e.g. some system-enqueued work), in which case the worker mints a fresh id.
      */
     originCorrelationId: z.string().optional(),
+    /**
+     * The WORK FRAME the job was enqueued inside (#1598 review F14): tenant, case, execution and task, so a
+     * model call the worker makes is attributed to the same unit of work as the request that enqueued it. The
+     * worker reopens the frame from this field in the same step that adopts `originCorrelationId`, at both
+     * consumers (the operations lane and the domain lane).
+     *
+     * ENGINE-WRITTEN, never client-supplied: the enqueue path copies it from the ambient frame, and no request
+     * DTO carries it. Re-deriving attribution in the worker from the job's own arguments was rejected, because
+     * every job type would have to know how.
+     */
+    attribution: ModelCallAttributionInputSchema.optional(),
     // === Domain Routing ===
     /** Domain category for domain-specific routing (e.g., 'email', 'agents') */
     domainCategory: z.string().optional(),
@@ -328,11 +559,17 @@ export const JobPayloadStorageSchema = z.object({
     /** Storage ID (used in JobPayload.inputPayloadStorageId) */
     storageId: z.uuid().isUnique({ scope: 'global', sparse: false }),
     // === Application Context ===
-    /** Application that owns this payload */
+    /**
+     * The application RECORD id (`applications._id`) — the APPLICATION resource scope's key, stamped by
+     * the backend's payload store from the canonical identity and the only id it reads a payload back
+     * under. Never `JobPayload.applicationId`, which is the platform's wire address.
+     */
     applicationId: z.string().isDBIndexed().isBackendOnly(),
     // === Content (sensitive, backend-only) ===
     /** JSON-stringified payload - contains actual job data */
     payloadJson: z.string().isBackendOnly(),
+    /** Query metadata for an opt-in run projection; selected results live only in payloadJson. */
+    scheduledEvidence: ScheduledRunEvidenceFieldsSchema.omit({ results: true }).isBackendOnly().optional(),
     /** Size of the payload in bytes */
     payloadSizeBytes: z.number().int().positive().isBackendOnly(),
     // === Compression (internal implementation detail) ===
@@ -361,6 +598,77 @@ export const JobPayloadStorageSchema = z.object({
  *
  * This is NOT a resource schema (used for RabbitMQ message transport)
  */
+/**
+ * What a caller is told when a resource operation was ACCEPTED rather than performed.
+ *
+ * A background or fire-and-forget runtime answers the request before the write happens, so the
+ * response is an acknowledgement — and a surface that reads it as a result would report success for
+ * work that has not run. The two members are not interchangeable: `QUEUED` means the job is on the
+ * queue, `PROCESSING` means a worker has it, and a caller polling or explaining the state to a
+ * person needs the difference.
+ */
+export var ResourceOperation_BackgroundAcceptanceStatus;
+(function (ResourceOperation_BackgroundAcceptanceStatus) {
+    ResourceOperation_BackgroundAcceptanceStatus["QUEUED"] = "queued";
+    ResourceOperation_BackgroundAcceptanceStatus["PROCESSING"] = "processing";
+})(ResourceOperation_BackgroundAcceptanceStatus || (ResourceOperation_BackgroundAcceptanceStatus = {}));
+/**
+ * The acknowledgement a non-awaited runtime answers with.
+ *
+ * Deliberately carries NO message: a response that reaches a person's screen must be worded from
+ * the label tree, in their language, by the surface that shows it. This used to include the English
+ * sentence "Job has been queued for background processing", which the action bar surfaced verbatim
+ * as a success toast — display text invented on the server
+ * (`.claude/rules/display-text-comes-from-i18n.md`), and a claim of success for a write that had
+ * not happened.
+ */
+export const ResourceOperationBackgroundAcceptanceSchema = z.object({
+    jobId: z.string().min(1),
+    status: z.enum(ResourceOperation_BackgroundAcceptanceStatus),
+});
+/**
+ * Read a background acceptance out of an operation result, or `undefined` when the result is an
+ * ordinary answer.
+ *
+ * One reader, so the frontend and any other consumer cannot disagree about what "this has not run
+ * yet" looks like on the wire.
+ */
+export function readBackgroundAcceptance(result) {
+    const parsed = ResourceOperationBackgroundAcceptanceSchema.safeParse(result);
+    return parsed.success ? parsed.data : undefined;
+}
+/**
+ * What a background BULK job did to each row it was given.
+ *
+ * An asynchronous batch may PARTIALLY succeed, and when it does it must say which items failed
+ * (spec-cite: Google AIP-234, "Batch update" — a synchronous batch update must be atomic, while a
+ * long-running one reports per-item errors; https://google.aip.dev/234). A row count cannot answer
+ * that: one refused row and one row that matched nothing look identical.
+ *
+ * A failure carries the error's REFERENCE rather than its message. The reference is what a client
+ * branches on and what a locale turns into words; a message would be the server guessing at the
+ * reader's language.
+ */
+export const BulkJobItemFailureSchema = z.object({
+    /** The row that was refused. */
+    resourceId: z.string().min(1),
+    /** The refusal's client-branchable reference. */
+    customMessageReference: z.string().optional(),
+    /** The refusal's category, so a caller can tell an authorization refusal from a validation one. */
+    errorType: z.string().optional(),
+});
+/**
+ * The result a background BULK job answers with.
+ *
+ * `attemptedCount` is what the job was GIVEN, not what the selection matched when the person chose:
+ * rows can leave the population between the two, and this number is the one the run can vouch for.
+ */
+export const BulkJobPerRowResultSchema = z.object({
+    attemptedCount: z.number().int().min(0),
+    succeededCount: z.number().int().min(0),
+    failedCount: z.number().int().min(0),
+    failures: z.array(BulkJobItemFailureSchema),
+});
 export const JobResultSchema = z.object({
     /** Job identifier */
     jobId: z.uuid(),
@@ -398,7 +706,7 @@ export const JOB_EXECUTION_TTL_SECONDS = 30 * 24 * 60 * 60; // 30 days
  * - Internal system resource for job lifecycle tracking
  * - Queryable fields (jobId, status, organizationId, userId) are exposed
  * - Sensitive/internal fields are marked .isBackendOnly()
- * - TTL: Documents are automatically deleted 30 days after creation
+ * - TTL: ordinary history expires after 30 days; scheduled claims only after a terminal outcome
  * - Proper indexes for dashboard/monitoring queries
  */
 export const JobExecutionSchema = z.object({
@@ -409,7 +717,12 @@ export const JobExecutionSchema = z.object({
     // === Job Identity (exposed for queries) ===
     /** Unique job identifier */
     jobId: z.uuid().isUnique({ scope: 'global', sparse: false }),
-    /** Application that owns this job */
+    /**
+     * The application RECORD id (`applications._id`) — the APPLICATION resource scope's key. Stamped by
+     * the backend's job tracker from the canonical identity at the moment the wire payload becomes a
+     * row, and the only id its recovery and evidence scans filter on. Never copied from
+     * `JobPayload.applicationId`, which is the platform's wire address and a different value.
+     */
     applicationId: z.string().isDBIndexed(),
     // === What Was Executed (exposed for filtering) ===
     /** Type of job */
@@ -443,7 +756,7 @@ export const JobExecutionSchema = z.object({
     lastRetryAt: z.date().optional(),
     // === Timing (exposed for performance monitoring) ===
     /**
-     * When the job record was created. TTL cleanup after 30 days.
+     * When the job record was created. Cleanup is governed separately by expiresAt.
      *
      * `.default(() => new Date())` is REQUIRED, not decorative: this is a
      * system-managed timestamp that the create pipeline strips from the input
@@ -452,11 +765,14 @@ export const JobExecutionSchema = z.object({
      * now-`undefined` value → `new Date(undefined)` = Invalid Date → the create
      * FATALs with `createdAt: expected date, received Date`. The default supplies
      * a valid Date when the field is absent, matching the canonical timestamp
-     * pattern (`z.date().default(() => new Date())` on todos/tasks/etc.). TTL must
-     * stay BEFORE `.default()` — its allowed types are `[ZodDate, ZodOptional]`,
-     * not `ZodDefault`.
+     * pattern (`z.date().default(() => new Date())` on todos/tasks/etc.). The separate expiresAt field carries the cleanup deadline.
      */
-    createdAt: z.date().ttl({ expireAfterSeconds: JOB_EXECUTION_TTL_SECONDS }).default(() => new Date()),
+    createdAt: z.date().default(() => new Date()),
+    /** Ordinary history expires after 30 days; unfinished scheduled claims have no expiry. */
+    expiresAt: z.date().ttl({ expireAfterSeconds: 0 }).optional(),
+    /** Durable scheduled ownership and recovery contract. Legacy queue writers must not mutate these rows. */
+    scheduledState: ScheduledExecutionStateSchema.isBackendOnly().optional(),
+    minionName: z.string().optional(),
     /** When the job was published to queue */
     queuedAt: z.date().optional(),
     /** When worker started processing */