@vibesdotdev/workers 0.0.0-stage → 1.0.0-rc.2

package/dist/docs/workers.queues.docs.descriptor.js

@@ -0,0 +1,356 @@
+// src/docs/workers.queues.md
+var workers_queues_default = `---
+title: Workers Queues
+summary: Job queues, scheduling, retry logic, and backoff strategies
+tags: [workers, queues, scheduling, retry, backoff, jobs]
+parent: workers
+order: 3
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+id: workers.queues
+---
+
+Workers queues provide reliable job processing with retry, scheduling, and event support. Every backend implements the same \`QueueAdapter\` interface, so a worker can run over an in-memory queue in tests, a Unix-socket IPC queue in local development, or a host-contributed queue in a hosted runtime without changing handler code.
+
+## Queue adapter interface
+
+The canonical contract lives in \`@vibesdotdev/workers/core/queue-adapter\` (exported as \`QueueAdapter\`). Required methods are always present; the optional methods (\`?\`) are implemented only by backends that support them.
+
+\`\`\`ts
+import { jobWriteGuard } from '@vibesdotdev/workers/core/queue-adapter';
+import type {
+  QueueAdapter,
+  Job,
+  EnqueueOptions,
+  JobStatus,
+  QueueMetrics,
+  Cancellation,
+  JobWriteGuard,
+  JobRetryOptions,
+  JobMutationStamp,
+  JobExecutionClaim,
+  KeyedClaimOptions,
+  KeyedClaimReceipt
+} from '@vibesdotdev/workers/core/queue-adapter';
+
+// QueueAdapter<TJob, TResult> (abridged — see source for full signatures):
+interface QueueAdapter<TJob = unknown, TResult = unknown> {
+  // Lifecycle
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+
+  // Job operations
+  enqueue(data: TJob, options?: EnqueueOptions): Promise<string>;
+  dequeue(options?: { jobTypes?: string[] }): Promise<Job<TJob> | null>;
+  getJob(jobId: string): Promise<Job<TJob> | null>;
+  // Every write names the admission it was issued for; a stale producer is refused.
+  updateJob(jobId: string, update: JobUpdate, guard: JobWriteGuard): Promise<JobMutationStamp>;
+  renewExecution(jobId: string, claim: JobExecutionClaim): Promise<void>;
+  releaseExecution(jobId: string, claim: JobExecutionClaim): Promise<void>;
+  cancelJob(jobId: string, cancellation: Cancellation): Promise<boolean>;
+  // Readmission names the generation the caller actually observed.
+  retryJob(jobId: string, options: JobRetryOptions): Promise<string>;
+  // Keyed claim — present exactly when the adapter descriptor declares keyedClaims
+  claimKeyed?(data: TJob, options: KeyedClaimOptions): Promise<KeyedClaimReceipt<TJob>>;
+
+  // Status & inspection
+  getStatus(jobId: string): Promise<JobStatus>;
+  listJobs(state?: JobState, options?: { limit?: number; offset?: number; dataEquals?: Record<string, string>; omit?: Array<'result' | 'progress'> }): Promise<Job<TJob>[]>;
+  getMetrics(): Promise<QueueMetrics>;
+
+  // Events (optional) — an event is an issued write too, so it carries the guard
+  broadcastEvent?(jobId: string, event: string, guard: JobWriteGuard, data?: JobEvent['data']): Promise<void>;
+  subscribeToEvents?(jobId: string, handler: (event: JobEvent) => void): () => void;
+
+  // Scheduling (optional)
+  scheduleRepeatable?(name: string, data: TJob, options: EnqueueOptions): Promise<string>;
+  removeSchedule?(name: string, repeat: RepeatOptions): Promise<boolean>;
+  getSchedules?(): Promise<ScheduleInfo[]>;
+  restoreArchivedSchedules?(queueName: string, ids?: readonly string[]): Promise<number>;
+  runDueSchedules?(): Promise<number>;
+}
+\`\`\`
+
+Key types:
+
+- \`listJobs\` answers newest first: \`createdAt\` descending, then \`id\` descending among jobs created in the same instant, so offset pages neither skip nor repeat a job. \`dataEquals\` keeps only jobs whose data object carries every named top-level field with exactly that string value (a run's jobs by its root id, say), and it selects before \`offset\`/\`limit\` cut the page, so a short page ends the selection. \`omit\` leaves \`result\` and/or \`progress\` out of every listed row; read the job (\`getJob\`) for them. Over the worker socket a large result crosses in pages, so \`getJob\` and \`listJobs\` still answer it whole.
+- \`Job<TJob>\` carries the payload under \`.data\` (not \`.payload\`) plus \`id\`, \`status\`, \`attemptsMade\`, \`createdAt\`, and optional \`progress\`/\`result\`/\`error\`/\`metadata\`.
+- \`JobStatus\` / \`JobState\` are the union \`'delayed' | 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled'\`.
+- \`QueueMetrics\` is \`{ waiting, active, completed, failed }\` — use \`getMetrics()\` for depth, not a dedicated \`getQueueDepth()\`.
+- \`subscribeToEvents\` returns an unsubscribe function (\`() => void\`).
+- \`JobWriteGuard\` is \`{ generation, claimToken, expectedStatus }\` — the admission a write was issued for. \`updateJob\` and \`broadcastEvent\` require it. \`updateJob\` answers with \`JobMutationStamp\` \`{ generation, revision, status }\`, while \`broadcastEvent\` returns \`Promise<void>\`.
+- \`JobRetryOptions\` always requires the observed \`expectedGeneration\`. Optional \`expectedRevision\` and \`expectedStatus\` bind the retry to that same observation; any supplied value that no longer matches is refused with \`CONFLICT\`. Optional \`delay\` requests a wait in milliseconds before the retried job becomes available. Readmission is refused while execution ownership is held or unknown.
+
+## Keyed claims and cancellation
+
+WorkerAdapterRequirementsSchema covers every declared adapter capability.
+Selection matches each supplied value, including crossHardware, keyedClaims, and
+coalescedEnqueue. A preferred adapter that lacks a requested capability is
+skipped. If no adapter qualifies, Workers returns the typed unavailable
+refusal. Composed selection proof is in
+src/client/__tests__/adapter-requirements.test.ts.
+
+Keyed claims are an optional queue capability. The memory, IPC, and database adapters declare <code>keyedClaims</code>; the database descriptor declares <code>keyedClaims: true</code>, and <code>DatabaseQueueAdapter</code> implements <code>claimKeyed</code> against the shared storage record. A claim is decided by its queue owner, preserving the key's generation and physical queue partition. The database implementation is covered by <code>src/adapters/database/__tests__/database-queue.test.ts</code>; the client and IPC proofs are in <code>src/client/__tests__/keyed-claim.test.ts</code> and <code>src/adapters/ipc/store/__tests__/durable-store.test.ts</code>.
+
+Cancellation uses the canonical <code>CancellationSchema</code>. Invocation records require a kernel runtime actor and reason; system records carry an explicit source and reason. <code>QueueAdapter.cancelJob(jobId, cancellation)</code> requires the record, while <code>WorkersClient.cancelJob(jobId, { reason })</code> derives the actor from its runtime scope. Missing actor or reason is refused before mutation with INVALID_INPUT / cancel-actor-required or cancel-reason-required. Queue rows and the job ledger preserve provenance; historical rows without it remain without it. Proof: <code>src/client/__tests__/cancellation/</code>, <code>src/adapters/database/__tests__/database-queue.test.ts</code>, and <code>src/runtime/ledger/__tests__/job-ledger.test.ts</code>.
+
+## Queue backends
+
+### Memory adapter (testing)
+
+In-memory queues for unit tests use <code>MemoryRuntimeAdapter</code> directly. Pass the owning runtime as the second argument; its lifecycle owns the queue store provided by <code>workers.memory-queues</code>. <code>MemoryClientAdapter</code> is the client-side counterpart; both are exported from <code>@vibesdotdev/workers/adapters/memory</code>.
+
+\`\`\`ts
+import { createTestRuntime } from '@vibesdotdev/testing/node/runtime';
+import workersPlugin from '@vibesdotdev/workers/common.plugin';
+import { MemoryRuntimeAdapter } from '@vibesdotdev/workers/adapters/memory';
+
+const host = await createTestRuntime({ binding: 'owned', plugins: [workersPlugin] });
+const adapter = new MemoryRuntimeAdapter('test-queue', host.runtime);
+await adapter.connect();
+try {
+  // Enqueue (queue name is fixed at construction; enqueue takes data + options)
+  const jobId = await adapter.enqueue({ message: 'hello' });
+
+  // Inspect depth via metrics
+  const metrics = await adapter.getMetrics();
+  // metrics.waiting === 1
+
+  // Dequeue (worker-side). A dequeue and an update both need a live owner,
+  // so they happen before the runtime is disposed.
+  const job = await adapter.dequeue();
+  if (job) {
+    // The guard is the admission this runner holds: the job's own generation,
+    // its claim token, and the status it must still be in.
+    await adapter.updateJob(job.id, { status: 'completed', result: job.data }, jobWriteGuard(job));
+  }
+} finally {
+  await adapter.disconnect();
+  await host.cleanup();
+}
+\`\`\`
+
+### IPC adapter (consumer)
+
+Unix-socket-based queues for local development. Use \`createIPCAdapter\` (a re-export of \`createIPCProvider\`), which returns a \`BunIPCAdapter\`. The queue name and mode are set at construction.
+
+\`\`\`ts
+import { createIPCAdapter } from '@vibesdotdev/workers/adapters/ipc';
+
+const adapter = createIPCAdapter({
+  queueName: 'bridge-stt',
+  mode: 'client',           // 'server' (default) or 'client'
+  socketPath: '/path/to/vibes-worker.sock'
+});
+
+await adapter.connect();
+
+// Enqueue a job (data first, options second)
+const jobId = await adapter.enqueue(
+  { audio: audioBase64, format: 'wav' },
+  { priority: 5 }
+);
+
+// Worker-side: dequeue and report completion
+const job = await adapter.dequeue();
+if (job) {
+  await adapter.updateJob(job.id, { status: 'completed', result: { text: '...' } }, jobWriteGuard(job));
+}
+\`\`\`
+
+### Provider adapters (cloud)
+
+Hosted queue transports are contributed by provider plugins. The host composes the plugin that owns its transport and bindings; application code continues to call WorkersClient and declares adapter requirements by capability.
+
+## Enqueue options
+
+\`EnqueueOptions\` (from \`@vibesdotdev/workers/core/queue-adapter\`) controls priority, retries, and backoff:
+
+\`\`\`ts
+interface EnqueueOptions {
+  jobId?: string;        // Use a caller-supplied id instead of a generated UUID
+  priority?: number;     // Higher number = processed earlier (where supported)
+  delay?: number;        // Delay before the job becomes available (ms)
+  attempts?: number;     // Max attempts before the job is marked failed
+  backoff?: number | { type: 'fixed' | 'exponential'; delay: number };
+  repeat?: RepeatOptions;
+}
+\`\`\`
+
+Backoff supports two strategies — \`fixed\` and \`exponential\`. \`BaseQueueAdapter.calculateRetryDelay()\` computes the delay for exponential backoff as \`delay * 2^(attempt - 1)\`:
+
+\`\`\`ts
+// Retry up to 5 times with exponential backoff: 1s, 2s, 4s, 8s
+await adapter.enqueue(payload, {
+  attempts: 5,
+  backoff: { type: 'exponential', delay: 1000 }
+});
+
+// Fixed 5s delay between attempts
+await adapter.enqueue(payload, {
+  attempts: 3,
+  backoff: { type: 'fixed', delay: 5000 }
+});
+\`\`\`
+
+## Scheduling
+
+The IPC schedule store and its corruption-diagnostic state are runtime-owned. The workers.ipc-schedules client scopes that state to the composing runtime and its lifecycle; there is no module-level schedule cache.
+
+### Scheduler service
+
+\`SchedulerService\` polls registered queues (and, optionally, a database of schedule records) and triggers due jobs. Its config requires a \`getQueues\` factory; the DB-backed path and distributed locking are opt-in.
+
+\`SchedulerService\` lives in \`src/scheduler/service.ts\`. It is an internal runtime service — it is not part of the package's public \`exports\`, so it is constructed by the worker runtime rather than imported by application code:
+
+\`\`\`ts
+// Internal to @vibesdotdev/workers (not a public export):
+// import { SchedulerService } from '../scheduler/service.ts';
+
+const scheduler = new SchedulerService({
+  runtime,                                  // the handed VibesRuntime; its lifecycle owns the tick
+  getQueues: () => [sttQueue, ttsQueue],   // QueueAdapter[]
+  pollIntervalMs: 60_000,                   // default 60s
+
+  // Optional DB-backed schedules
+  getDueSchedules: async () => loadDueSchedules(),
+  updateSchedule: async (id, updates) => saveSchedule(id, updates),
+
+  // Optional multi-instance safety
+  acquireLock: async (key) => tryLock(key),
+  releaseLock: async (key, token) => unlock(key, token)
+});
+
+await scheduler.start();   // runs the first tick before resolving
+const status = scheduler.getStatus();  // { running, pollIntervalMs, totalTriggered, ... }
+await scheduler.stop();
+\`\`\`
+
+> The \`@vibesdotdev/workers/core/schedule-manager\` entrypoint is a separate, public abstraction: it exports the \`BaseScheduleManager\` abstract class and the \`ScheduleConfig\` type. It does **not** export \`SchedulerService\`.
+
+### Scheduler configuration
+
+The \`workers\` config manifest (\`WorkersConfigSchema\`) holds the user-configurable settings. Workers reads it through the config owner's client; there are no environment switches.
+
+\`\`\`ts
+import { readWorkersConfig } from '@vibesdotdev/workers/config/read';
+
+const settings = await readWorkersConfig(runtime);
+// {
+//   scheduler: {
+//     enabled: true, pollIntervalMs: 60000,
+//     archive: { enabled: false, afterDays: 30 }
+//   },
+//   flow: { defaultWaitTimeoutMs: 28800000 },
+//   client: { jobTimeoutMs: 2700000 },
+//   schedules: { '<job id>': { enabled: boolean } }
+// }
+\`\`\`
+
+### Persisted IPC schedules and archive policy
+
+The IPC adapter validates the entire persisted schedule array, executable cron expressions in their stored timezone, timezone names, and each stored queue option through StoredScheduleArraySchema before reading or writing. A pattern is executable only when cron-parser can produce its next run in the stored timezone — the same parse a tick performs. A malformed record earns the value-free workers-schedules-corrupt refusal, and a tick refuses the whole store before any of its schedules is enqueued, so a malformed record is never enqueued on repeat. Corrupt
+data remains untouched and is refused with INVALID_INPUT /
+workers-schedules-corrupt without exposing stored values. The runtime-owned
+diagnostic state reports unchanged corruption once and checks again when the
+file changes, so a repaired file resumes scheduling.
+
+Disabled and completed schedule definitions and their job payloads stay in
+active storage by default. scheduler.archive.enabled defaults to false, and
+scheduler.archive.afterDays defaults to 30. When enabled, aged records are
+copied to a separately validated archive before they leave active storage. The
+WorkersClient.restoreArchivedSchedules(queueName, ids?) restores them through
+the queue adapter and its RPC surface, and drops the archive copy only once
+active storage is confirmed to hold the record.
+
+Proof is in src/adapters/ipc/__tests__/schedules.test.ts and
+src/__tests__/worker-runtime-scheduler-config.test.ts.
+### Cron and interval schedules
+
+Recurring schedules are expressed via \`RepeatOptions\`, which supports cron patterns (parsed with \`cron-parser\`, IANA timezone aware) or fixed intervals:
+
+\`\`\`ts
+import type { RepeatOptions } from '@vibesdotdev/workers/core/queue-adapter';
+
+const daily: RepeatOptions = { cron: '0 3 * * *', tz: 'UTC' };   // daily at 03:00
+const everyMinute: RepeatOptions = { every: 60_000 };            // every 60s
+
+// On backends that implement it:
+await adapter.scheduleRepeatable?.('daily-cleanup', { task: 'db-prune' }, {
+  repeat: daily
+});
+\`\`\`
+
+## Job events
+
+Backends that implement events expose \`broadcastEvent\` / \`subscribeToEvents\`. \`subscribeToEvents\` returns an unsubscribe function and delivers \`JobEvent\` values (\`{ jobId, event, data?, timestamp }\`).
+
+\`\`\`ts
+const unsubscribe = adapter.subscribeToEvents?.(jobId, (event) => {
+  console.log(\`Job \${event.jobId}: \${event.event}\`);
+  if (event.event === 'completed' || event.event === 'failed') {
+    unsubscribe?.();
+  }
+});
+
+// Producer side — the same admission guard the writer holds
+await adapter.broadcastEvent?.(jobId, 'progress', guard, { percent: 50 });
+\`\`\`
+
+## CLI
+
+Job and worker management is available under \`vibes workers\`:
+
+\`\`\`bash
+# List and inspect workers
+vibes workers list
+vibes workers info <worker-id>
+
+# Run a job (input as JSON, optional target hardware)
+vibes workers jobs run text-generation --input '{"prompt":"..."}'
+vibes workers jobs run image-generation cloud --async
+
+# List jobs for a worker (optionally filter by status)
+vibes workers jobs list <worker-id> --status pending --limit 50
+
+# Inspect a single job
+vibes workers jobs info <job-id> --json
+
+# Cancel a pending or processing job; terminal jobs report their existing state
+vibes workers jobs cancel <job-id> 'reason for cancellation'
+
+# Watch a job until terminal state, with health/progress snapshots
+vibes workers jobs watch <job-id> --interval 5000
+\`\`\`
+
+:::card{title="See also"}
+- [\`workers.kinds\`](workers.kinds) — Worker/job/flow kinds
+- [\`workers.bindings\`](workers.bindings) — Environment bindings
+- [\`pm.tasks\`](pm.tasks) — Task scheduling
+:::
+`;
+
+// src/docs/workers.queues.docs.descriptor.ts
+var descriptor = {
+  kind: "docs/topic",
+  id: "workers.queues",
+  title: "Workers Queues",
+  summary: "Job queues, scheduling, retry logic, and backoff strategies",
+  body: {
+    type: "markdown",
+    sourceType: "raw",
+    source: workers_queues_default
+  },
+  parent: "workers",
+  order: 3,
+  tags: ["workers", "queues", "scheduling", "retry", "backoff", "jobs"],
+  surfaces: ["cli", "web", "in-app"],
+  hardware: ["consumer", "cloud"],
+  enabled: true
+};
+var workers_queues_docs_descriptor_default = descriptor;
+export {
+  workers_queues_docs_descriptor_default as default
+};
+
+//# debugId=E0E82087116381DB64756E2164756E21

package/dist/docs/workers.queues.docs.descriptor.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../src/docs/workers.queues.docs.descriptor.ts"],
+  "sourcesContent": [
+    "import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';\nimport markdown from './workers.queues.md' with { type: 'text' };\n\nconst descriptor: DocsTopicDescriptor = {\n\tkind: 'docs/topic',\n\tid: 'workers.queues',\n\ttitle: 'Workers Queues',\n\tsummary: 'Job queues, scheduling, retry logic, and backoff strategies',\n\tbody: {\n\t\ttype: 'markdown',\n\t\tsourceType: 'raw',\n\t\tsource: markdown\n\t},\n\tparent: 'workers',\n\torder: 3,\n\ttags: ['workers', 'queues', 'scheduling', 'retry', 'backoff', 'jobs'],\n\tsurfaces: ['cli', 'web', 'in-app'],\n\thardware: ['consumer', 'cloud'],\n\tenabled: true\n};\n\nexport default descriptor;\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGA,IAAM,aAAkC;AAAA,EACvC,MAAM;AAAA,EACN,IAAI;AAAA,EACJ,OAAO;AAAA,EACP,SAAS;AAAA,EACT,MAAM;AAAA,IACL,MAAM;AAAA,IACN,YAAY;AAAA,IACZ,QAAQ;AAAA,EACT;AAAA,EACA,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,MAAM,CAAC,WAAW,UAAU,cAAc,SAAS,WAAW,MAAM;AAAA,EACpE,UAAU,CAAC,OAAO,OAAO,QAAQ;AAAA,EACjC,UAAU,CAAC,YAAY,OAAO;AAAA,EAC9B,SAAS;AACV;AAEA,IAAe;",
+  "debugId": "E0E82087116381DB64756E2164756E21",
+  "names": []
+}

package/dist/execution/implementation-generation.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The implementation generation of a resolved `workers/job` implementation:
+ * the value the runner stamps on an admitted envelope
+ * (`AdmittedJobExecutionEnvelope.implementationGeneration`) and the value an
+ * execution host compares it with before it starts a producer. One reader, so
+ * both sides name a generation the same way.
+ *
+ * Its source is the runner custodian's (Comet) to name. Until it is named,
+ * the reader refuses typed, so no run proceeds on a stand-in value.
+ */
+import { type VibesRuntime } from '@vibesdotdev/kernel';
+import type { JobImplementation } from '@vibesdotdev/kernel/kinds';
+export declare function readJobImplementationGeneration(_runtime: VibesRuntime, implementation: JobImplementation): Promise<string>;
+//# sourceMappingURL=implementation-generation.d.ts.map

package/dist/execution/implementation-generation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"implementation-generation.d.ts","sourceRoot":"","sources":["../../src/execution/implementation-generation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE,wBAAsB,+BAA+B,CAAC,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAIhI"}

package/dist/execution/implementation-generation.js

@@ -0,0 +1,17 @@
+/**
+ * The implementation generation of a resolved `workers/job` implementation:
+ * the value the runner stamps on an admitted envelope
+ * (`AdmittedJobExecutionEnvelope.implementationGeneration`) and the value an
+ * execution host compares it with before it starts a producer. One reader, so
+ * both sides name a generation the same way.
+ *
+ * Its source is the runner custodian's (Comet) to name. Until it is named,
+ * the reader refuses typed, so no run proceeds on a stand-in value.
+ */
+import { CapabilityError } from '@vibesdotdev/kernel';
+export async function readJobImplementationGeneration(_runtime, implementation) {
+    throw new CapabilityError('The job implementation generation has no declared source yet.', 'UNAVAILABLE', {
+        reason: 'job-implementation-generation-unavailable', retryable: false, details: { jobType: implementation.id }
+    });
+}
+//# sourceMappingURL=implementation-generation.js.map

package/dist/execution/implementation-generation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"implementation-generation.js","sourceRoot":"","sources":["../../src/execution/implementation-generation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,eAAe,EAAqB,MAAM,qBAAqB,CAAC;AAGzE,MAAM,CAAC,KAAK,UAAU,+BAA+B,CAAC,QAAsB,EAAE,cAAiC;IAC9G,MAAM,IAAI,eAAe,CAAC,+DAA+D,EAAE,aAAa,EAAE;QACzG,MAAM,EAAE,2CAA2C,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,cAAc,CAAC,EAAE,EAAE;KAC9G,CAAC,CAAC;AACJ,CAAC"}

package/dist/execution/thread-host.descriptor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The worker_thread job execution host's descriptor (`runtime/job-execution-host`):
+ * the runner resolves it by a job's declared isolation, `worker_thread`, and
+ * it contains the producer's JavaScript in a native thread, not the native
+ * descendants the producer starts. The implementation is `./thread-host.impl.ts`.
+ */
+import { type JobExecutionHostDescriptor } from '@vibesdotdev/kernel/kinds';
+export declare const workerThreadJobExecutionHostDescriptor: JobExecutionHostDescriptor;
+//# sourceMappingURL=thread-host.descriptor.d.ts.map

package/dist/execution/thread-host.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-host.descriptor.d.ts","sourceRoot":"","sources":["../../src/execution/thread-host.descriptor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAA2B,KAAK,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AAErG,eAAO,MAAM,sCAAsC,EAAE,0BAQpD,CAAC"}

package/dist/execution/thread-host.descriptor.js

@@ -0,0 +1,17 @@
+/**
+ * The worker_thread job execution host's descriptor (`runtime/job-execution-host`):
+ * the runner resolves it by a job's declared isolation, `worker_thread`, and
+ * it contains the producer's JavaScript in a native thread, not the native
+ * descendants the producer starts. The implementation is `./thread-host.impl.ts`.
+ */
+import { JOB_EXECUTION_HOST_KIND } from '@vibesdotdev/kernel/kinds';
+export const workerThreadJobExecutionHostDescriptor = {
+    kind: JOB_EXECUTION_HOST_KIND,
+    id: 'worker_thread',
+    containment: 'thread',
+    name: 'Worker thread job execution host',
+    description: "Runs a job's handler in a native thread of a bounded pool, off the runner's own thread",
+    enabled: true,
+    hardware: ['consumer']
+};
+//# sourceMappingURL=thread-host.descriptor.js.map

package/dist/execution/thread-host.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-host.descriptor.js","sourceRoot":"","sources":["../../src/execution/thread-host.descriptor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,uBAAuB,EAAmC,MAAM,2BAA2B,CAAC;AAErG,MAAM,CAAC,MAAM,sCAAsC,GAA+B;IACjF,IAAI,EAAE,uBAAuB;IAC7B,EAAE,EAAE,eAAe;IACnB,WAAW,EAAE,QAAQ;IACrB,IAAI,EAAE,kCAAkC;IACxC,WAAW,EAAE,wFAAwF;IACrG,OAAO,EAAE,IAAI;IACb,QAAQ,EAAE,CAAC,UAAU,CAAC;CACtB,CAAC"}

package/dist/execution/thread-host.impl.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The worker_thread job execution host (`runtime/job-execution-host`, id
+ * `worker_thread`): descriptor `./thread-host.descriptor.ts`, thread program
+ * `./thread-host.program.ts`, wire `./thread-host.schemas.ts`. Threads come
+ * from the selected `runtime/plugin-host` (captureRuntimeThreadBoot,
+ * spawnRuntimeThread, terminate and exit); this host opens no thread itself.
+ *
+ * Pool. Native threads are bounded by the workers config's
+ * `execution.thread.threads`, apart from the runners' logical slots, and
+ * each multiplexes many live async producers. A run goes to a live
+ * incarnation that carries no producer; otherwise the host starts a thread
+ * while under the bound; otherwise it goes to the live incarnation carrying
+ * the fewest producers. When every incarnation is draining and the bound is
+ * reached, it waits for one to exit. A thread that one producer blocks
+ * synchronously delays the others it carries: that is the bound, stated.
+ *
+ * Start. `run` resolves when the thread reports `started`: it resolved the
+ * implementation at the envelope's generation and is about to call the
+ * handler. A run the thread settles without starting, or whose thread exits
+ * or never boots first, rejects `run` typed; nothing ran, so it has no
+ * witness. A generation the thread cannot run drains that incarnation, and
+ * the run starts once more on a fresh one.
+ *
+ * Retirement. `producer-settled` comes only from the thread's `settled`
+ * report for that run on that incarnation: the handler and every context call
+ * it issued settled. `native-exited` comes only from the thread's exit, for
+ * every producer that incarnation carried. Nothing else retires a run: not a
+ * deadline, an unheard call, or an abort acknowledgement.
+ *
+ * Abort. The run's signal (the runner's deadline and cancellation) is
+ * delivered to the producer's own signal, and `abortDelivered` resolves when
+ * the thread reports that delivery. A started producer that has not settled
+ * `execution.thread.abortGraceMs` after its abort was requested (or after it
+ * started, when the abort came first) ends with its thread: the host
+ * terminates the incarnation, and every producer on it retires
+ * `native-exited`. A run not yet started never ends its thread: the thread
+ * refuses that start once it reads the abort.
+ *
+ * Disposal. The host aborts every run, drains idle threads, waits up to the
+ * abort grace for every thread to exit, then terminates what remains.
+ */
+import { type KindContext, type RuntimeDescriptor, type VibesRuntime } from '@vibesdotdev/kernel';
+import type { JobExecutionContextPort, JobExecutionHost, JobExecutionRun } from '@vibesdotdev/kernel/kinds';
+import { type AdmittedJobExecutionEnvelope } from '@vibesdotdev/kernel/schemas/job-execution';
+export default class WorkerThreadJobExecutionHost implements JobExecutionHost {
+    private readonly runtime;
+    private readonly incarnations;
+    private readonly capacityWaiters;
+    private disposal?;
+    private disposing;
+    private options?;
+    constructor(_descriptor: RuntimeDescriptor, context: KindContext<VibesRuntime>);
+    run(envelopeInput: AdmittedJobExecutionEnvelope, context: JobExecutionContextPort, signal: AbortSignal): Promise<JobExecutionRun>;
+    private answers;
+    private start;
+    /** Choose the incarnation a run goes to (the module comment's pool rule). */
+    private place;
+    private capacityFreed;
+    private freeCapacity;
+    /** Start one incarnation: it counts against the bound from now, and its boot runs behind `job`. */
+    private launch;
+    private boot;
+    /** The job-context root this host serves one incarnation (`JOB_THREAD_CONTEXT_ROOT_METHODS`). */
+    private contextRoot;
+    private witnessOf;
+    /** Perform one context operation on the run's parent port; its outcome crosses back as `complete`. */
+    private perform;
+    /** Post one job-root call; an unheard one is still delivered, a refused one is a diagnostic. */
+    private post;
+    private settled;
+    private afterRunLeft;
+    /**
+     * The parent's cancellation for one run: deliver it, and end the thread if
+     * a started producer outlives the grace. A run not yet started is never a
+     * reason to end its thread: the thread refuses its start once it reads the
+     * abort, and the producers it already carries are not this run's to end.
+     */
+    private requestAbort;
+    private armGrace;
+    /** End an incarnation natively; its exit retires every producer it carried. */
+    private terminate;
+    /** The native owner reported the incarnation's exit: every producer it carried retires `native-exited`. */
+    private exited;
+    /** Register this host's disposal once: it owns the threads it started. */
+    private ensureDisposal;
+    private dispose;
+}
+//# sourceMappingURL=thread-host.impl.d.ts.map

package/dist/execution/thread-host.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-host.impl.d.ts","sourceRoot":"","sources":["../../src/execution/thread-host.impl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAGH,OAAO,EASN,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAM5G,OAAO,EAKN,KAAK,4BAA4B,EAIjC,MAAM,2CAA2C,CAAC;AA0EnD,MAAM,CAAC,OAAO,OAAO,4BAA6B,YAAW,gBAAgB;IAC5E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgC;IAC7D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IACzD,OAAO,CAAC,QAAQ,CAAC,CAAgB;IACjC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAC,CAAoB;gBAExB,WAAW,EAAE,iBAAiB,EAAE,OAAO,EAAE,WAAW,CAAC,YAAY,CAAC;IASxE,GAAG,CAAC,aAAa,EAAE,4BAA4B,EAAE,OAAO,EAAE,uBAAuB,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;IAuBvI,OAAO,CAAC,OAAO;YAID,KAAK;IAqDnB,6EAA6E;YAC/D,KAAK;IAqBnB,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,YAAY;IAOpB,mGAAmG;IACnG,OAAO,CAAC,MAAM;YAcA,IAAI;IA2DlB,iGAAiG;IACjG,OAAO,CAAC,WAAW;IA0CnB,OAAO,CAAC,SAAS;IAOjB,sGAAsG;YACxF,OAAO;IAgBrB,gGAAgG;YAClF,IAAI;IASlB,OAAO,CAAC,OAAO;IAsBf,OAAO,CAAC,YAAY;IAIpB;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,QAAQ;IAQhB,+EAA+E;YACjE,SAAS;IAavB,2GAA2G;IAC3G,OAAO,CAAC,MAAM;IAmCd,0EAA0E;IAC1E,OAAO,CAAC,cAAc;YASR,OAAO;CAoBrB"}