@contractspec/lib.jobs 1.57.0 → 1.59.0

package/dist/node/index.js

@@ -0,0 +1,1368 @@
+// src/contracts/index.ts
+import { ScalarTypeEnum, defineSchemaModel } from "@contractspec/lib.schema";
+import { defineCommand, defineQuery } from "@contractspec/lib.contracts";
+var OWNERS = ["platform.jobs"];
+var JobModel = defineSchemaModel({
+  name: "Job",
+  description: "Represents a background job",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    type: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    version: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    payload: { type: ScalarTypeEnum.JSON(), isOptional: false },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    priority: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    attempts: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    maxRetries: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    scheduledAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    startedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    completedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    lastError: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+var ScheduledJobModel = defineSchemaModel({
+  name: "ScheduledJob",
+  description: "Represents a scheduled/recurring job",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    cronExpression: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    timezone: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    jobType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    enabled: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    lastRunAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    nextRunAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var QueueStatsModel = defineSchemaModel({
+  name: "QueueStats",
+  description: "Job queue statistics",
+  fields: {
+    pending: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    running: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    completed: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    failed: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    deadLetter: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false }
+  }
+});
+var EnqueueJobInput = defineSchemaModel({
+  name: "EnqueueJobInput",
+  description: "Input for enqueuing a new job",
+  fields: {
+    type: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    payload: { type: ScalarTypeEnum.JSON(), isOptional: false },
+    delaySeconds: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    dedupeKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    maxRetries: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    priority: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    timeoutMs: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
+  }
+});
+var GetJobInput = defineSchemaModel({
+  name: "GetJobInput",
+  description: "Input for getting a job by ID",
+  fields: {
+    jobId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var CancelJobInput = defineSchemaModel({
+  name: "CancelJobInput",
+  description: "Input for cancelling a job",
+  fields: {
+    jobId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var CancelJobOutput = defineSchemaModel({
+  name: "CancelJobOutput",
+  description: "Output for cancel job operation",
+  fields: {
+    success: { type: ScalarTypeEnum.Boolean(), isOptional: false }
+  }
+});
+var CreateScheduledJobInput = defineSchemaModel({
+  name: "CreateScheduledJobInput",
+  description: "Input for creating a scheduled job",
+  fields: {
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    cronExpression: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    timezone: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    jobType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    payload: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    maxRetries: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    enabled: { type: ScalarTypeEnum.Boolean(), isOptional: true }
+  }
+});
+var ListScheduledJobsOutput = defineSchemaModel({
+  name: "ListScheduledJobsOutput",
+  description: "Output for listing scheduled jobs",
+  fields: {
+    schedules: { type: ScheduledJobModel, isArray: true, isOptional: false }
+  }
+});
+var ToggleScheduledJobInput = defineSchemaModel({
+  name: "ToggleScheduledJobInput",
+  description: "Input for toggling a scheduled job",
+  fields: {
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    enabled: { type: ScalarTypeEnum.Boolean(), isOptional: false }
+  }
+});
+var JobEnqueuedPayload = defineSchemaModel({
+  name: "JobEnqueuedPayload",
+  description: "Payload for job.enqueued event",
+  fields: {
+    jobId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    type: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    priority: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    scheduledAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    tenantId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    enqueuedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var JobCancelledPayload = defineSchemaModel({
+  name: "JobCancelledPayload",
+  description: "Payload for job.cancelled event",
+  fields: {
+    jobId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var EnqueueJobContract = defineCommand({
+  meta: {
+    key: "jobs.enqueue",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["jobs", "enqueue"],
+    description: "Enqueue a background job for async processing.",
+    goal: "Allow services to offload work to background processing.",
+    context: "Called by any service that needs async processing."
+  },
+  io: {
+    input: EnqueueJobInput,
+    output: JobModel
+  },
+  policy: {
+    auth: "user"
+  },
+  sideEffects: {
+    emits: [
+      {
+        key: "job.enqueued",
+        version: "1.0.0",
+        when: "Job is enqueued",
+        payload: JobEnqueuedPayload
+      }
+    ]
+  }
+});
+var GetJobContract = defineQuery({
+  meta: {
+    key: "jobs.get",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["jobs", "get"],
+    description: "Get a job by ID.",
+    goal: "Check job status and result.",
+    context: "Called to poll job status or retrieve results."
+  },
+  io: {
+    input: GetJobInput,
+    output: JobModel
+  },
+  policy: {
+    auth: "user"
+  }
+});
+var CancelJobContract = defineCommand({
+  meta: {
+    key: "jobs.cancel",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["jobs", "cancel"],
+    description: "Cancel a pending job.",
+    goal: "Allow cancellation of jobs that are no longer needed.",
+    context: "Only pending jobs can be cancelled."
+  },
+  io: {
+    input: CancelJobInput,
+    output: CancelJobOutput,
+    errors: {
+      JOB_NOT_FOUND: {
+        description: "Job does not exist",
+        http: 404,
+        gqlCode: "JOB_NOT_FOUND",
+        when: "Job ID is invalid"
+      },
+      JOB_NOT_PENDING: {
+        description: "Job is not in pending state",
+        http: 409,
+        gqlCode: "JOB_NOT_PENDING",
+        when: "Job has already started or completed"
+      }
+    }
+  },
+  policy: {
+    auth: "user"
+  },
+  sideEffects: {
+    emits: [
+      {
+        key: "job.cancelled",
+        version: "1.0.0",
+        when: "Job is cancelled",
+        payload: JobCancelledPayload
+      }
+    ]
+  }
+});
+var GetQueueStatsContract = defineQuery({
+  meta: {
+    key: "jobs.stats",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["jobs", "stats", "admin"],
+    description: "Get job queue statistics.",
+    goal: "Monitor queue health and backlog.",
+    context: "Admin dashboard monitoring."
+  },
+  io: {
+    input: null,
+    output: QueueStatsModel
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var CreateScheduledJobContract = defineCommand({
+  meta: {
+    key: "jobs.schedule.create",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["jobs", "schedule", "create"],
+    description: "Create a scheduled/recurring job.",
+    goal: "Set up recurring background tasks.",
+    context: "Admin configuration for periodic tasks."
+  },
+  io: {
+    input: CreateScheduledJobInput,
+    output: ScheduledJobModel
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var ListScheduledJobsContract = defineQuery({
+  meta: {
+    key: "jobs.schedule.list",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["jobs", "schedule", "list"],
+    description: "List all scheduled jobs.",
+    goal: "View configured recurring tasks.",
+    context: "Admin dashboard."
+  },
+  io: {
+    input: null,
+    output: ListScheduledJobsOutput
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var ToggleScheduledJobContract = defineCommand({
+  meta: {
+    key: "jobs.schedule.toggle",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["jobs", "schedule", "toggle"],
+    description: "Enable or disable a scheduled job.",
+    goal: "Control when recurring tasks run.",
+    context: "Admin control over scheduled tasks."
+  },
+  io: {
+    input: ToggleScheduledJobInput,
+    output: ScheduledJobModel
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+
+// src/entities/index.ts
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index
+} from "@contractspec/lib.schema";
+var JobStatusEnum = defineEntityEnum({
+  name: "JobStatus",
+  values: [
+    "PENDING",
+    "RUNNING",
+    "COMPLETED",
+    "FAILED",
+    "CANCELLED",
+    "DEAD_LETTER"
+  ],
+  schema: "lssm_jobs",
+  description: "Status of a background job."
+});
+var JobEntity = defineEntity({
+  name: "Job",
+  description: "A background job for async processing.",
+  schema: "lssm_jobs",
+  map: "job",
+  fields: {
+    id: field.id({ description: "Unique job identifier" }),
+    type: field.string({ description: "Job type identifier" }),
+    version: field.int({ default: 1, description: "Job type version" }),
+    payload: field.json({ description: "Job payload data" }),
+    status: field.enum("JobStatus", { default: "PENDING" }),
+    priority: field.int({ default: 0, description: "Higher = more urgent" }),
+    attempts: field.int({
+      default: 0,
+      description: "Number of execution attempts"
+    }),
+    maxRetries: field.int({
+      default: 3,
+      description: "Maximum retry attempts"
+    }),
+    lastError: field.string({
+      isOptional: true,
+      description: "Last error message"
+    }),
+    lastErrorStack: field.string({
+      isOptional: true,
+      description: "Last error stack trace"
+    }),
+    scheduledAt: field.dateTime({
+      isOptional: true,
+      description: "When job should be processed"
+    }),
+    startedAt: field.dateTime({
+      isOptional: true,
+      description: "When processing started"
+    }),
+    completedAt: field.dateTime({
+      isOptional: true,
+      description: "When processing completed"
+    }),
+    timeoutAt: field.dateTime({
+      isOptional: true,
+      description: "Job timeout deadline"
+    }),
+    dedupeKey: field.string({
+      isOptional: true,
+      description: "Key for deduplication"
+    }),
+    tenantId: field.string({
+      isOptional: true,
+      description: "Tenant/org context"
+    }),
+    userId: field.string({
+      isOptional: true,
+      description: "User who enqueued"
+    }),
+    traceId: field.string({
+      isOptional: true,
+      description: "Distributed trace ID"
+    }),
+    metadata: field.json({
+      isOptional: true,
+      description: "Additional metadata"
+    }),
+    result: field.json({ isOptional: true, description: "Job result data" }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    scheduledJob: field.belongsTo("ScheduledJob", ["scheduledJobId"], ["id"]),
+    scheduledJobId: field.string({ isOptional: true }),
+    executions: field.hasMany("JobExecution")
+  },
+  indexes: [
+    index.on(["status", "scheduledAt"]),
+    index.on(["type", "status"]),
+    index.on(["tenantId", "status"]),
+    index.unique(["dedupeKey"], { name: "job_dedupe_key_unique" })
+  ],
+  enums: [JobStatusEnum]
+});
+var ScheduledJobEntity = defineEntity({
+  name: "ScheduledJob",
+  description: "A scheduled/recurring job definition.",
+  schema: "lssm_jobs",
+  map: "scheduled_job",
+  fields: {
+    id: field.id(),
+    name: field.string({ isUnique: true, description: "Unique schedule name" }),
+    description: field.string({ isOptional: true }),
+    cronExpression: field.string({
+      description: "Cron expression for scheduling"
+    }),
+    timezone: field.string({
+      default: '"UTC"',
+      description: "Timezone for cron evaluation"
+    }),
+    jobType: field.string({ description: "Job type to create" }),
+    jobVersion: field.int({ default: 1 }),
+    payload: field.json({
+      isOptional: true,
+      description: "Default payload for created jobs"
+    }),
+    maxRetries: field.int({ default: 3 }),
+    timeoutMs: field.int({
+      isOptional: true,
+      description: "Job timeout in milliseconds"
+    }),
+    enabled: field.boolean({ default: true }),
+    lastRunAt: field.dateTime({ isOptional: true }),
+    nextRunAt: field.dateTime({ isOptional: true }),
+    tenantId: field.string({ isOptional: true }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    jobs: field.hasMany("Job")
+  },
+  indexes: [index.on(["enabled", "nextRunAt"])]
+});
+var JobExecutionEntity = defineEntity({
+  name: "JobExecution",
+  description: "A single execution attempt of a job.",
+  schema: "lssm_jobs",
+  map: "job_execution",
+  fields: {
+    id: field.id(),
+    jobId: field.foreignKey(),
+    attemptNumber: field.int({ description: "Which attempt this is" }),
+    startedAt: field.dateTime(),
+    completedAt: field.dateTime({ isOptional: true }),
+    durationMs: field.int({ isOptional: true }),
+    success: field.boolean({ isOptional: true }),
+    error: field.string({ isOptional: true }),
+    errorStack: field.string({ isOptional: true }),
+    result: field.json({ isOptional: true }),
+    workerId: field.string({
+      isOptional: true,
+      description: "ID of worker that processed"
+    }),
+    job: field.belongsTo("Job", ["jobId"], ["id"], { onDelete: "Cascade" })
+  },
+  indexes: [index.on(["jobId", "attemptNumber"])]
+});
+var jobEntities = [JobEntity, ScheduledJobEntity, JobExecutionEntity];
+var jobsSchemaContribution = {
+  moduleId: "@contractspec/lib.jobs",
+  entities: jobEntities,
+  enums: [JobStatusEnum]
+};
+
+// src/events.ts
+import { ScalarTypeEnum as ScalarTypeEnum2, defineSchemaModel as defineSchemaModel2 } from "@contractspec/lib.schema";
+import { defineEvent, StabilityEnum } from "@contractspec/lib.contracts";
+var JobEnqueuedPayload2 = defineSchemaModel2({
+  name: "JobEnqueuedEventPayload",
+  description: "Payload when a job is added to the queue",
+  fields: {
+    jobId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    type: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    priority: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    scheduledAt: { type: ScalarTypeEnum2.DateTime(), isOptional: true },
+    tenantId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    enqueuedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var JobStartedPayload = defineSchemaModel2({
+  name: "JobStartedEventPayload",
+  description: "Payload when a job starts processing",
+  fields: {
+    jobId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    type: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    attempt: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    startedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var JobCompletedPayload = defineSchemaModel2({
+  name: "JobCompletedEventPayload",
+  description: "Payload when a job completes successfully",
+  fields: {
+    jobId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    type: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    attempt: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    durationMs: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    completedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var JobFailedPayload = defineSchemaModel2({
+  name: "JobFailedEventPayload",
+  description: "Payload when a job attempt fails",
+  fields: {
+    jobId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    type: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    attempt: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    error: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    willRetry: { type: ScalarTypeEnum2.Boolean(), isOptional: false },
+    failedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var JobRetryingPayload = defineSchemaModel2({
+  name: "JobRetryingEventPayload",
+  description: "Payload when a job is scheduled for retry",
+  fields: {
+    jobId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    type: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    attempt: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    nextAttemptAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false },
+    backoffMs: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false }
+  }
+});
+var JobDeadLetteredPayload = defineSchemaModel2({
+  name: "JobDeadLetteredEventPayload",
+  description: "Payload when a job is moved to dead letter queue",
+  fields: {
+    jobId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    type: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    attempts: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    lastError: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    deadLetteredAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var JobCancelledPayload2 = defineSchemaModel2({
+  name: "JobCancelledEventPayload",
+  description: "Payload when a job is cancelled",
+  fields: {
+    jobId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    type: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    cancelledBy: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    cancelledAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var ScheduledJobTriggeredPayload = defineSchemaModel2({
+  name: "ScheduledJobTriggeredEventPayload",
+  description: "Payload when a scheduled job is triggered",
+  fields: {
+    scheduleName: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    jobId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    jobType: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    triggeredAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false },
+    nextRunAt: { type: ScalarTypeEnum2.DateTime(), isOptional: true }
+  }
+});
+var JobEnqueuedEvent = defineEvent({
+  meta: {
+    key: "job.enqueued",
+    version: "1.0.0",
+    description: "A job has been added to the queue.",
+    stability: StabilityEnum.Stable,
+    owners: ["@contractspec.libs.jobs"],
+    tags: ["job-queue", "lifecycle"]
+  },
+  payload: JobEnqueuedPayload2
+});
+var JobStartedEvent = defineEvent({
+  meta: {
+    key: "job.started",
+    version: "1.0.0",
+    description: "A job has started processing.",
+    stability: StabilityEnum.Stable,
+    owners: ["@contractspec.libs.jobs"],
+    tags: ["job-queue", "lifecycle"]
+  },
+  payload: JobStartedPayload
+});
+var JobCompletedEvent = defineEvent({
+  meta: {
+    key: "job.completed",
+    version: "1.0.0",
+    description: "A job has completed successfully.",
+    stability: StabilityEnum.Stable,
+    owners: ["@contractspec.libs.jobs"],
+    tags: ["job-queue", "lifecycle"]
+  },
+  payload: JobCompletedPayload
+});
+var JobFailedEvent = defineEvent({
+  meta: {
+    key: "job.failed",
+    version: "1.0.0",
+    description: "A job attempt has failed.",
+    stability: StabilityEnum.Stable,
+    owners: ["@contractspec.libs.jobs"],
+    tags: ["job-queue", "lifecycle", "error"]
+  },
+  payload: JobFailedPayload
+});
+var JobRetryingEvent = defineEvent({
+  meta: {
+    key: "job.retrying",
+    version: "1.0.0",
+    description: "A job is being scheduled for retry.",
+    stability: StabilityEnum.Stable,
+    owners: ["@contractspec.libs.jobs"],
+    tags: ["job-queue", "lifecycle", "retry"]
+  },
+  payload: JobRetryingPayload
+});
+var JobDeadLetteredEvent = defineEvent({
+  meta: {
+    key: "job.dead_lettered",
+    version: "1.0.0",
+    description: "A job has exhausted all retries and moved to dead letter queue.",
+    stability: StabilityEnum.Stable,
+    owners: ["@contractspec.libs.jobs"],
+    tags: ["job-queue", "lifecycle", "error"]
+  },
+  payload: JobDeadLetteredPayload
+});
+var JobCancelledEvent = defineEvent({
+  meta: {
+    key: "job.cancelled",
+    version: "1.0.0",
+    description: "A job has been cancelled.",
+    stability: StabilityEnum.Stable,
+    owners: ["@contractspec.libs.jobs"],
+    tags: ["job-queue", "lifecycle"]
+  },
+  payload: JobCancelledPayload2
+});
+var ScheduledJobTriggeredEvent = defineEvent({
+  meta: {
+    key: "scheduler.job_triggered",
+    version: "1.0.0",
+    description: "A scheduled job has been triggered.",
+    stability: StabilityEnum.Stable,
+    owners: ["@contractspec.libs.jobs"],
+    tags: ["job-queue", "scheduler"]
+  },
+  payload: ScheduledJobTriggeredPayload
+});
+var JobEvents = {
+  JobEnqueuedEvent,
+  JobStartedEvent,
+  JobCompletedEvent,
+  JobFailedEvent,
+  JobRetryingEvent,
+  JobDeadLetteredEvent,
+  JobCancelledEvent,
+  ScheduledJobTriggeredEvent
+};
+
+// src/handlers/gmail-sync-handler.ts
+function createGmailSyncHandler(adapter) {
+  return async (job) => {
+    await adapter.syncThreads(job.payload);
+  };
+}
+
+// src/handlers/ping-job.ts
+import * as z from "zod";
+var PING_JOB_TYPE = "core.ping";
+var PingPayloadSchema = z.object({});
+var pingJob = {
+  type: PING_JOB_TYPE,
+  schema: PingPayloadSchema,
+  handler: async (_payload, _job) => {}
+};
+
+// src/handlers/storage-document-handler.ts
+function createStorageDocumentHandler(storage, adapter) {
+  return async (job) => {
+    const object2 = await storage.getObject({
+      bucket: job.payload.bucket,
+      key: job.payload.key
+    });
+    if (!object2) {
+      throw new Error(`Object ${job.payload.bucket}/${job.payload.key} not found`);
+    }
+    await adapter.ingestObject(object2);
+  };
+}
+
+// src/queue/register-defined-job.ts
+function registerDefinedJob(queue, def) {
+  const wrapped = async (job) => {
+    const payload = def.schema.parse(job.payload);
+    const typedJob = {
+      ...job,
+      payload
+    };
+    await def.handler(payload, typedJob);
+  };
+  queue.register(def.type, wrapped);
+}
+// src/handlers/index.ts
+function registerAllJobs(queue) {
+  registerDefinedJob(queue, pingJob);
+}
+
+// src/queue/types.ts
+export * from "@contractspec/lib.contracts/jobs/queue";
+import {
+  calculateBackoff,
+  DEFAULT_RETRY_POLICY
+} from "@contractspec/lib.contracts/jobs/queue";
+
+// src/queue/memory-queue.ts
+import { randomUUID } from "node:crypto";
+class MemoryJobQueue {
+  jobs = new Map;
+  handlers = new Map;
+  timer;
+  activeCount = 0;
+  pollIntervalMs;
+  concurrency;
+  retryPolicy;
+  constructor(options = {}) {
+    this.pollIntervalMs = options.pollIntervalMs ?? 200;
+    this.concurrency = options.concurrency ?? 5;
+    this.retryPolicy = options.retryPolicy ?? DEFAULT_RETRY_POLICY;
+  }
+  async enqueue(jobType, payload, options = {}) {
+    if (options.dedupeKey) {
+      const existing = Array.from(this.jobs.values()).find((j) => j.dedupeKey === options.dedupeKey && j.status === "pending");
+      if (existing) {
+        return existing;
+      }
+    }
+    const now = new Date;
+    const scheduledAt = options.delaySeconds ? new Date(now.getTime() + options.delaySeconds * 1000) : now;
+    const job = {
+      id: randomUUID(),
+      type: jobType,
+      version: "1.0.0",
+      payload,
+      status: "pending",
+      priority: options.priority ?? 0,
+      attempts: 0,
+      maxRetries: options.maxRetries ?? this.retryPolicy.maxRetries,
+      createdAt: now,
+      updatedAt: now,
+      scheduledAt,
+      dedupeKey: options.dedupeKey,
+      tenantId: options.tenantId,
+      userId: options.userId,
+      traceId: options.traceId,
+      metadata: options.metadata
+    };
+    if (options.timeoutMs) {
+      job.timeoutAt = new Date(now.getTime() + options.timeoutMs);
+    }
+    this.jobs.set(job.id, job);
+    return job;
+  }
+  register(jobType, handler) {
+    this.handlers.set(jobType, handler);
+  }
+  start() {
+    if (this.timer)
+      return;
+    this.timer = setInterval(() => {
+      this.processNext();
+    }, this.pollIntervalMs);
+  }
+  async stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+    while (this.activeCount > 0) {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+  }
+  async getJob(jobId) {
+    return this.jobs.get(jobId) ?? null;
+  }
+  async cancelJob(jobId) {
+    const job = this.jobs.get(jobId);
+    if (!job || job.status !== "pending") {
+      return false;
+    }
+    job.status = "cancelled";
+    job.updatedAt = new Date;
+    return true;
+  }
+  async getStats() {
+    const stats = {
+      pending: 0,
+      running: 0,
+      completed: 0,
+      failed: 0,
+      deadLetter: 0
+    };
+    for (const job of this.jobs.values()) {
+      switch (job.status) {
+        case "pending":
+          stats.pending++;
+          break;
+        case "running":
+          stats.running++;
+          break;
+        case "completed":
+          stats.completed++;
+          break;
+        case "failed":
+          stats.failed++;
+          break;
+        case "dead_letter":
+          stats.deadLetter++;
+          break;
+      }
+    }
+    return stats;
+  }
+  async processNext() {
+    if (this.activeCount >= this.concurrency)
+      return;
+    const now = new Date;
+    const pendingJobs = Array.from(this.jobs.values()).filter((j) => j.status === "pending" && (!j.scheduledAt || j.scheduledAt <= now)).sort((a, b) => {
+      if (a.priority !== b.priority) {
+        return b.priority - a.priority;
+      }
+      return (a.scheduledAt?.getTime() ?? 0) - (b.scheduledAt?.getTime() ?? 0);
+    });
+    const job = pendingJobs[0];
+    if (!job)
+      return;
+    const handler = this.handlers.get(job.type);
+    if (!handler)
+      return;
+    this.activeCount++;
+    job.status = "running";
+    job.startedAt = new Date;
+    job.updatedAt = new Date;
+    job.attempts += 1;
+    try {
+      const result = await handler(job);
+      job.status = "completed";
+      job.completedAt = new Date;
+      job.result = result;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      job.lastError = errorMessage;
+      if (job.attempts >= job.maxRetries) {
+        job.status = "dead_letter";
+      } else {
+        const backoff = calculateBackoff(job.attempts, this.retryPolicy);
+        job.status = "pending";
+        job.scheduledAt = new Date(Date.now() + backoff);
+      }
+    } finally {
+      job.updatedAt = new Date;
+      this.activeCount--;
+    }
+  }
+}
+
+// src/queue/scaleway-sqs-queue.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+import {
+  DeleteMessageCommand,
+  ReceiveMessageCommand,
+  SendMessageCommand,
+  SQSClient
+} from "@aws-sdk/client-sqs";
+class ScalewaySqsJobQueue {
+  sqs;
+  queueUrl;
+  waitTimeSeconds;
+  maxNumberOfMessages;
+  visibilityTimeoutSeconds;
+  handlers = new Map;
+  logger;
+  running = false;
+  constructor(config) {
+    this.logger = config.logger;
+    const accessKeyId = config.credentials?.accessKeyId ?? process.env.SCALEWAY_ACCESS_KEY_QUEUE;
+    const secretAccessKey = config.credentials?.secretAccessKey ?? process.env.SCALEWAY_SECRET_KEY_QUEUE;
+    if (!accessKeyId || !secretAccessKey) {
+      throw new Error("Missing SCALEWAY_ACCESS_KEY_QUEUE / SCALEWAY_SECRET_KEY_QUEUE in env");
+    }
+    const region = config.region ?? process.env.SCALEWAY_REGION ?? "par";
+    const endpoint = config.endpoint ?? "https://sqs.mnq.fr-par.scaleway.com";
+    this.sqs = new SQSClient({
+      region,
+      endpoint,
+      credentials: {
+        accessKeyId,
+        secretAccessKey
+      }
+    });
+    this.queueUrl = config.queueUrl;
+    this.waitTimeSeconds = config.waitTimeSeconds ?? 20;
+    this.maxNumberOfMessages = config.maxNumberOfMessages ?? 5;
+    this.visibilityTimeoutSeconds = config.visibilityTimeoutSeconds ?? 60;
+  }
+  async enqueue(jobType, payload, options = {}) {
+    const id = randomUUID2();
+    const now = new Date;
+    const scheduledAt = options.delaySeconds ? new Date(now.getTime() + options.delaySeconds * 1000) : now;
+    const envelope = {
+      id,
+      type: jobType,
+      payload
+    };
+    await this.sqs.send(new SendMessageCommand({
+      QueueUrl: this.queueUrl,
+      MessageBody: JSON.stringify(envelope),
+      DelaySeconds: options.delaySeconds ?? 0
+    }));
+    return {
+      id,
+      type: jobType,
+      version: "1.0.0",
+      payload,
+      status: "pending",
+      priority: options.priority ?? 0,
+      attempts: 0,
+      maxRetries: options.maxRetries ?? DEFAULT_RETRY_POLICY.maxRetries,
+      createdAt: now,
+      updatedAt: now,
+      scheduledAt,
+      dedupeKey: options.dedupeKey,
+      tenantId: options.tenantId,
+      userId: options.userId,
+      traceId: options.traceId,
+      metadata: options.metadata
+    };
+  }
+  register(jobType, handler) {
+    if (this.handlers.has(jobType)) {
+      throw new Error(`Handler already registered for job type "${jobType}"`);
+    }
+    this.handlers.set(jobType, handler);
+  }
+  start() {
+    if (this.running)
+      return;
+    this.running = true;
+    this.pollLoop().catch((error) => {
+      this.logger?.error?.("jobs.queue.scaleway_sqs.poll_loop_fatal", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      this.running = false;
+    });
+  }
+  async stop() {
+    this.running = false;
+  }
+  async pollLoop() {
+    this.logger?.info?.("jobs.queue.scaleway_sqs.started", {
+      queueUrl: this.queueUrl
+    });
+    while (this.running) {
+      try {
+        const res = await this.sqs.send(new ReceiveMessageCommand({
+          QueueUrl: this.queueUrl,
+          MaxNumberOfMessages: this.maxNumberOfMessages,
+          WaitTimeSeconds: this.waitTimeSeconds,
+          VisibilityTimeout: this.visibilityTimeoutSeconds,
+          MessageSystemAttributeNames: ["ApproximateReceiveCount"]
+        }));
+        const messages = res.Messages ?? [];
+        if (messages.length === 0) {
+          continue;
+        }
+        for (const msg of messages) {
+          if (!msg.Body || !msg.ReceiptHandle) {
+            this.logger?.warn?.("jobs.queue.scaleway_sqs.invalid_message", {
+              messageId: msg.MessageId,
+              reason: "missing_body_or_receipt"
+            });
+            continue;
+          }
+          let envelope;
+          try {
+            envelope = JSON.parse(msg.Body);
+          } catch (err) {
+            this.logger?.warn?.("jobs.queue.scaleway_sqs.parse_failed", {
+              messageId: msg.MessageId,
+              error: err instanceof Error ? err.message : String(err)
+            });
+            await this.deleteMessage(msg.ReceiptHandle);
+            continue;
+          }
+          const handler = this.handlers.get(envelope.type);
+          if (!handler) {
+            this.logger?.warn?.("jobs.queue.scaleway_sqs.missing_handler", {
+              jobType: envelope.type,
+              messageId: msg.MessageId
+            });
+            await this.deleteMessage(msg.ReceiptHandle);
+            continue;
+          }
+          const now = new Date;
+          const attempts = parseInt(msg.Attributes?.ApproximateReceiveCount ?? "1", 10);
+          const job = {
+            id: envelope.id,
+            type: envelope.type,
+            version: "1.0.0",
+            payload: envelope.payload,
+            status: "pending",
+            priority: 0,
+            attempts,
+            maxRetries: DEFAULT_RETRY_POLICY.maxRetries,
+            createdAt: now,
+            updatedAt: now
+          };
+          job.status = "running";
+          job.updatedAt = new Date;
+          try {
+            await handler(job);
+            job.status = "completed";
+            job.updatedAt = new Date;
+            await this.deleteMessage(msg.ReceiptHandle);
+          } catch (err) {
+            job.status = "failed";
+            job.lastError = err instanceof Error ? err.message : "Unknown job error";
+            job.updatedAt = new Date;
+            this.logger?.error?.("jobs.queue.scaleway_sqs.job_failed", {
+              jobType: job.type,
+              jobId: job.id,
+              error: err instanceof Error ? err.message : String(err)
+            });
+          }
+        }
+      } catch (err) {
+        this.logger?.error?.("jobs.queue.scaleway_sqs.poll_error", {
+          error: err instanceof Error ? err.message : String(err)
+        });
+        await this.sleep(5000);
+      }
+    }
+    this.logger?.info?.("jobs.queue.scaleway_sqs.stopped", {
+      queueUrl: this.queueUrl
+    });
+  }
+  async deleteMessage(receiptHandle) {
+    try {
+      await this.sqs.send(new DeleteMessageCommand({
+        QueueUrl: this.queueUrl,
+        ReceiptHandle: receiptHandle
+      }));
+    } catch (err) {
+      this.logger?.warn?.("jobs.queue.scaleway_sqs.delete_failed", {
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  async sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+// src/queue/gcp-cloud-tasks.ts
+import { randomUUID as randomUUID3 } from "node:crypto";
+class GcpCloudTasksQueue {
+  options;
+  handlers = new Map;
+  constructor(options) {
+    this.options = options;
+  }
+  async enqueue(jobType, payload, options = {}) {
+    const now = new Date;
+    const enqueueTime = options.delaySeconds != null ? { seconds: Math.floor(Date.now() / 1000) + options.delaySeconds } : undefined;
+    const body = Buffer.from(JSON.stringify({
+      id: randomUUID3(),
+      type: jobType,
+      payload
+    }), "utf-8");
+    await this.options.client.createTask({
+      parent: `projects/${this.options.projectId}/locations/${this.options.location}/queues/${this.options.queue}`,
+      task: {
+        httpRequest: {
+          httpMethod: "POST",
+          url: this.options.resolveUrl(jobType),
+          body,
+          headers: { "Content-Type": "application/json" },
+          oidcToken: this.options.serviceAccountEmail ? { serviceAccountEmail: this.options.serviceAccountEmail } : undefined
+        },
+        scheduleTime: enqueueTime
+      }
+    });
+    return {
+      id: randomUUID3(),
+      type: jobType,
+      version: "1.0.0",
+      payload,
+      status: "pending",
+      priority: options.priority ?? 0,
+      attempts: 0,
+      maxRetries: options.maxRetries ?? DEFAULT_RETRY_POLICY.maxRetries,
+      createdAt: now,
+      updatedAt: now,
+      scheduledAt: options.delaySeconds ? new Date(now.getTime() + options.delaySeconds * 1000) : now,
+      dedupeKey: options.dedupeKey,
+      tenantId: options.tenantId,
+      userId: options.userId,
+      traceId: options.traceId,
+      metadata: options.metadata
+    };
+  }
+  register(jobType, handler) {
+    this.handlers.set(jobType, handler);
+  }
+  start() {}
+  async stop() {
+    this.handlers.clear();
+  }
+}
+
+// src/queue/gcp-pubsub.ts
+import { randomUUID as randomUUID4 } from "node:crypto";
+class GcpPubSubQueue {
+  options;
+  handlers = new Map;
+  constructor(options) {
+    this.options = options;
+  }
+  async enqueue(jobType, payload, options = {}) {
+    const now = new Date;
+    await this.options.client.topic(this.options.topicName).publishMessage({
+      data: Buffer.from(JSON.stringify({
+        id: randomUUID4(),
+        type: jobType,
+        payload
+      }), "utf-8")
+    });
+    return {
+      id: randomUUID4(),
+      type: jobType,
+      version: "1.0.0",
+      payload,
+      status: "pending",
+      priority: options.priority ?? 0,
+      attempts: 0,
+      maxRetries: options.maxRetries ?? DEFAULT_RETRY_POLICY.maxRetries,
+      createdAt: now,
+      updatedAt: now,
+      scheduledAt: options.delaySeconds ? new Date(now.getTime() + options.delaySeconds * 1000) : now,
+      dedupeKey: options.dedupeKey,
+      tenantId: options.tenantId,
+      userId: options.userId,
+      traceId: options.traceId,
+      metadata: options.metadata
+    };
+  }
+  register(jobType, handler) {
+    this.handlers.set(jobType, handler);
+  }
+  start() {}
+  async stop() {
+    this.handlers.clear();
+  }
+}
+// src/scheduler/index.ts
+function getNextCronRun(cronExpression, after = new Date) {
+  try {
+    const parts = cronExpression.trim().split(/\s+/);
+    if (parts.length !== 5) {
+      console.warn(`Invalid cron expression: ${cronExpression}`);
+      return null;
+    }
+    const minute = parts[0];
+    const hour = parts[1];
+    const dayOfMonth = parts[2];
+    const month = parts[3];
+    const next = new Date(after);
+    next.setSeconds(0);
+    next.setMilliseconds(0);
+    if (minute && hour && minute !== "*" && hour !== "*" && dayOfMonth === "*" && month === "*") {
+      const targetMinute = Number.parseInt(minute, 10);
+      const targetHour = Number.parseInt(hour, 10);
+      next.setHours(targetHour, targetMinute, 0, 0);
+      if (next <= after) {
+        next.setDate(next.getDate() + 1);
+      }
+      return next;
+    }
+    next.setMinutes(next.getMinutes() + 1);
+    return next;
+  } catch {
+    return null;
+  }
+}
+
+class JobScheduler {
+  queue;
+  schedules = new Map;
+  timer;
+  checkIntervalMs;
+  constructor(queue2, options = {}) {
+    this.queue = queue2;
+    this.checkIntervalMs = options.checkIntervalMs ?? 60000;
+  }
+  schedule(config) {
+    const nextRun = config.enabled !== false ? getNextCronRun(config.cronExpression) : null;
+    this.schedules.set(config.name, {
+      ...config,
+      enabled: config.enabled ?? true,
+      nextRun,
+      lastRun: null
+    });
+  }
+  unschedule(name) {
+    return this.schedules.delete(name);
+  }
+  enable(name) {
+    const schedule = this.schedules.get(name);
+    if (!schedule)
+      return false;
+    schedule.enabled = true;
+    schedule.nextRun = getNextCronRun(schedule.cronExpression);
+    return true;
+  }
+  disable(name) {
+    const schedule = this.schedules.get(name);
+    if (!schedule)
+      return false;
+    schedule.enabled = false;
+    schedule.nextRun = null;
+    return true;
+  }
+  getSchedules() {
+    return Array.from(this.schedules.values());
+  }
+  getSchedule(name) {
+    return this.schedules.get(name);
+  }
+  start() {
+    if (this.timer)
+      return;
+    this.checkSchedules();
+    this.timer = setInterval(() => {
+      this.checkSchedules();
+    }, this.checkIntervalMs);
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+  }
+  async checkSchedules() {
+    const now = new Date;
+    for (const schedule of this.schedules.values()) {
+      if (!schedule.enabled || !schedule.nextRun)
+        continue;
+      if (schedule.nextRun <= now) {
+        try {
+          const payload = typeof schedule.payload === "function" ? await schedule.payload() : schedule.payload;
+          await this.queue.enqueue(schedule.jobType, payload, schedule.options);
+          schedule.lastRun = now;
+          schedule.nextRun = getNextCronRun(schedule.cronExpression, now);
+        } catch (error) {
+          console.error(`Failed to enqueue scheduled job ${schedule.name}:`, error);
+        }
+      }
+    }
+  }
+}
+function createScheduler(queue2, options) {
+  return new JobScheduler(queue2, options);
+}
+function defineSchedule(config) {
+  return config;
+}
+
+// src/jobs.feature.ts
+import { defineFeature } from "@contractspec/lib.contracts";
+var JobsFeature = defineFeature({
+  meta: {
+    key: "jobs",
+    title: "Background Jobs",
+    description: "Background job processing, scheduling, and queue management",
+    domain: "platform",
+    owners: ["@platform.jobs"],
+    tags: ["jobs", "queue", "background", "scheduler"],
+    stability: "stable",
+    version: "1.0.0"
+  },
+  operations: [
+    { key: "jobs.enqueue", version: "1.0.0" },
+    { key: "jobs.cancel", version: "1.0.0" },
+    { key: "jobs.get", version: "1.0.0" },
+    { key: "jobs.stats", version: "1.0.0" },
+    { key: "jobs.schedule.create", version: "1.0.0" },
+    { key: "jobs.schedule.toggle", version: "1.0.0" },
+    { key: "jobs.schedule.list", version: "1.0.0" }
+  ],
+  events: [
+    { key: "job.enqueued", version: "1.0.0" },
+    { key: "job.started", version: "1.0.0" },
+    { key: "job.completed", version: "1.0.0" },
+    { key: "job.failed", version: "1.0.0" },
+    { key: "job.retrying", version: "1.0.0" },
+    { key: "job.dead_lettered", version: "1.0.0" },
+    { key: "job.cancelled", version: "1.0.0" },
+    { key: "scheduler.job_triggered", version: "1.0.0" }
+  ],
+  presentations: [],
+  opToPresentation: [],
+  presentationsTargets: [],
+  capabilities: {
+    provides: [
+      { key: "jobs", version: "1.0.0" },
+      { key: "scheduler", version: "1.0.0" }
+    ],
+    requires: []
+  }
+});
+export {
+  registerDefinedJob,
+  registerAllJobs,
+  pingJob,
+  jobsSchemaContribution,
+  jobEntities,
+  defineSchedule,
+  createStorageDocumentHandler,
+  createScheduler,
+  createGmailSyncHandler,
+  calculateBackoff,
+  ToggleScheduledJobContract,
+  ScheduledJobTriggeredEvent,
+  ScheduledJobModel,
+  ScheduledJobEntity,
+  ScalewaySqsJobQueue,
+  QueueStatsModel,
+  PingPayloadSchema,
+  PING_JOB_TYPE,
+  MemoryJobQueue,
+  ListScheduledJobsContract,
+  JobsFeature,
+  JobStatusEnum,
+  JobStartedEvent,
+  JobScheduler,
+  JobRetryingEvent,
+  JobModel,
+  JobFailedEvent,
+  JobExecutionEntity,
+  JobEvents,
+  JobEntity,
+  JobEnqueuedEvent,
+  JobDeadLetteredEvent,
+  JobCompletedEvent,
+  JobCancelledEvent,
+  GetQueueStatsContract,
+  GetJobContract,
+  GcpPubSubQueue,
+  GcpCloudTasksQueue,
+  EnqueueJobContract,
+  DEFAULT_RETRY_POLICY,
+  CreateScheduledJobContract,
+  CancelJobContract
+};