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

package/dist/diagnostics/conformance.schema.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Declared Workers coverage in this host's registry, not execution/readiness.
+ */
+import * as z from 'zod/v4';
+export declare const ConformanceFailureCodeSchema: z.ZodEnum<{
+    "empty-registry": "empty-registry";
+    "job-without-loader": "job-without-loader";
+    "queue-without-worker": "queue-without-worker";
+    "worker-without-jobs": "worker-without-jobs";
+    "schedule-without-host": "schedule-without-host";
+    "flow-unresolved": "flow-unresolved";
+}>;
+export declare const ConformanceWarningCodeSchema: z.ZodEnum<{
+    "emitter-unbound": "emitter-unbound";
+}>;
+export declare const ConformanceIssueSchema: z.ZodObject<{
+    code: z.ZodUnion<readonly [z.ZodEnum<{
+        "empty-registry": "empty-registry";
+        "job-without-loader": "job-without-loader";
+        "queue-without-worker": "queue-without-worker";
+        "worker-without-jobs": "worker-without-jobs";
+        "schedule-without-host": "schedule-without-host";
+        "flow-unresolved": "flow-unresolved";
+    }>, z.ZodEnum<{
+        "emitter-unbound": "emitter-unbound";
+    }>]>;
+    subject: z.ZodString;
+    detail: z.ZodString;
+}, z.core.$strip>;
+export declare const ConformanceReportSchema: z.ZodObject<{
+    hardware: z.ZodString;
+    surface: z.ZodString;
+    counts: z.ZodObject<{
+        jobs: z.ZodNumber;
+        jobsWithLoader: z.ZodNumber;
+        backgroundJobs: z.ZodNumber;
+        queues: z.ZodNumber;
+        servedQueues: z.ZodNumber;
+        schedules: z.ZodNumber;
+        servedSchedules: z.ZodNumber;
+        workers: z.ZodNumber;
+    }, z.core.$strip>;
+    failures: z.ZodArray<z.ZodObject<{
+        code: z.ZodUnion<readonly [z.ZodEnum<{
+            "empty-registry": "empty-registry";
+            "job-without-loader": "job-without-loader";
+            "queue-without-worker": "queue-without-worker";
+            "worker-without-jobs": "worker-without-jobs";
+            "schedule-without-host": "schedule-without-host";
+            "flow-unresolved": "flow-unresolved";
+        }>, z.ZodEnum<{
+            "emitter-unbound": "emitter-unbound";
+        }>]>;
+        subject: z.ZodString;
+        detail: z.ZodString;
+    }, z.core.$strip>>;
+    warnings: z.ZodArray<z.ZodObject<{
+        code: z.ZodUnion<readonly [z.ZodEnum<{
+            "empty-registry": "empty-registry";
+            "job-without-loader": "job-without-loader";
+            "queue-without-worker": "queue-without-worker";
+            "worker-without-jobs": "worker-without-jobs";
+            "schedule-without-host": "schedule-without-host";
+            "flow-unresolved": "flow-unresolved";
+        }>, z.ZodEnum<{
+            "emitter-unbound": "emitter-unbound";
+        }>]>;
+        subject: z.ZodString;
+        detail: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ConformanceReport = z.infer<typeof ConformanceReportSchema>;
+export type ConformanceIssue = z.infer<typeof ConformanceIssueSchema>;
+//# sourceMappingURL=conformance.schema.d.ts.map

package/dist/diagnostics/conformance.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.schema.d.ts","sourceRoot":"","sources":["../../src/diagnostics/conformance.schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B,eAAO,MAAM,4BAA4B;;;;;;;EAavC,CAAC;AAEH,eAAO,MAAM,4BAA4B;;EAGvC,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;iBAIjC,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiBlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/diagnostics/conformance.schema.js

@@ -0,0 +1,46 @@
+/**
+ * Declared Workers coverage in this host's registry, not execution/readiness.
+ */
+import * as z from 'zod/v4';
+export const ConformanceFailureCodeSchema = z.enum([
+    /** No enabled jobs were examined, so this host's coverage is unmeasured. */
+    'empty-registry',
+    /** A job is declared for this hardware but has no registered loader. */
+    'job-without-loader',
+    /** A background queue has no matching declared worker on this hardware. */
+    'queue-without-worker',
+    /** A worker declares a queue that no job uses. */
+    'worker-without-jobs',
+    /** A scheduled job's queue has no matching declared worker. */
+    'schedule-without-host',
+    /** Background jobs exist but no workers/flow loader is registered here. */
+    'flow-unresolved'
+]);
+export const ConformanceWarningCodeSchema = z.enum([
+    /** No workers/usage-emitter is registered, so work on this host is not metered. */
+    'emitter-unbound'
+]);
+export const ConformanceIssueSchema = z.object({
+    code: z.union([ConformanceFailureCodeSchema, ConformanceWarningCodeSchema]),
+    subject: z.string(),
+    detail: z.string()
+});
+export const ConformanceReportSchema = z.object({
+    /** The scope the check evaluated: the host it ran in. */
+    hardware: z.string(),
+    surface: z.string(),
+    counts: z.object({
+        jobs: z.number().int(),
+        /** Registered loader count; loaders are not invoked by this reader. */
+        jobsWithLoader: z.number().int(),
+        backgroundJobs: z.number().int(),
+        queues: z.number().int(),
+        servedQueues: z.number().int(),
+        schedules: z.number().int(),
+        servedSchedules: z.number().int(),
+        workers: z.number().int()
+    }),
+    failures: z.array(ConformanceIssueSchema),
+    warnings: z.array(ConformanceIssueSchema)
+});
+//# sourceMappingURL=conformance.schema.js.map

package/dist/diagnostics/conformance.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.schema.js","sourceRoot":"","sources":["../../src/diagnostics/conformance.schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,IAAI,CAAC;IAClD,4EAA4E;IAC5E,gBAAgB;IAChB,wEAAwE;IACxE,oBAAoB;IACpB,2EAA2E;IAC3E,sBAAsB;IACtB,kDAAkD;IAClD,qBAAqB;IACrB,+DAA+D;IAC/D,uBAAuB;IACvB,2EAA2E;IAC3E,iBAAiB;CACjB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,IAAI,CAAC;IAClD,mFAAmF;IACnF,iBAAiB;CACjB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,4BAA4B,EAAE,4BAA4B,CAAC,CAAC;IAC3E,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;CAClB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,yDAAyD;IACzD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;QACtB,uEAAuE;QACvE,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;QAChC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;QAChC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;QACxB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;QAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;QAC3B,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;QACjC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;KACzB,CAAC;IACF,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC;IACzC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC;CACzC,CAAC,CAAC"}

package/dist/docs/workers.bindings.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=workers.bindings.docs.descriptor.d.ts.map

package/dist/docs/workers.bindings.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workers.bindings.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/workers.bindings.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBA0DjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

@@ -0,0 +1,61 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'workers.bindings',
+    title: 'Worker Bindings',
+    summary: 'Runtime-local worker configuration and provider-owned bindings',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: Worker Bindings
+summary: Runtime-local worker configuration and provider-owned bindings
+tags: [workers, bindings, environment, runtime, plugins]
+parent: workers
+order: 2
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+Workers owns provider-neutral job, adapter, flow, event, and result contracts. A provider package owns its binding schema, context descriptor, adapter descriptors, implementations, and worker-entry exports.
+
+## Settings
+
+Workers settings live in the \`workers\` config manifest and are read through the config owner's client with \`readWorkersConfig(runtime)\` from \`@vibesdotdev/workers/config/read\`. They are not read from environment variables. A host that cannot read them fails with the manifest id instead of guessing. Tracing follows the \`worker-runtime\` logger level.
+
+Secrets resolve through runtime secret providers; persisted configuration stores credential references, never resolved secret values.
+
+## Provider bindings
+
+Hosts select a completed provider plugin and contribute bindings through that provider's runtime-local configured plugin. They do not set a Workers process-global binding slot or construct a provider adapter directly.
+
+Hosts compose the provider plugin that owns the selected transport, binding schema, queue consumer, and runtime entrypoints. Workers consumes the provider's runtime descriptors and remains independent of its SDK and binding format.
+
+## Dispatching jobs
+
+Application code resolves the canonical client; the runtime selects an adapter from the active plugin graph.
+
+\`\`\`ts
+import { getWorkersClient } from '@vibesdotdev/workers/client';
+
+// The runtime your command, tool, job or request was handed.
+const workers = await getWorkersClient(runtime);
+const started = await workers.startJob('ai.generation.pdf-ocr.execute', input);
+const result = await workers.runJob('ai.generation.image.execute', input);
+\`\`\`
+
+:::card{title="See also"}
+- [\`workers.kinds\`](workers.kinds) — Worker/job/flow kinds
+- [\`workers.queues\`](workers.queues) — Queue management
+- [\`config.environment\`](config.environment) — Environment configuration
+:::
+`
+    },
+    parent: 'workers',
+    order: 2,
+    tags: ['workers', 'bindings', 'environment', 'runtime', 'plugins'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=workers.bindings.docs.descriptor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workers.bindings.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/workers.bindings.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,kBAAkB;IACtB,KAAK,EAAE,iBAAiB;IACxB,OAAO,EAAE,gEAAgE;IACzE,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CT;KACC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,CAAC;IAClE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/workers.graphs.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=workers.graphs.docs.descriptor.d.ts.map

package/dist/docs/workers.graphs.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workers.graphs.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/workers.graphs.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBAoEjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

@@ -0,0 +1,71 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'workers.graphs',
+    title: 'Workers Job Graphs',
+    summary: 'Run Workers jobs as a dependency graph with data edges, conditions, concurrency and failure policy',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: Workers Job Graphs
+summary: Run Workers jobs as a dependency graph with data edges, conditions, concurrency and failure policy
+tags: [workers, graphs, jobs, workflows, orchestration]
+parent: workers
+order: 4
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+id: workers.graphs
+---
+
+A job graph runs \`workers/job\` descriptors in dependency order. Each node is one job run through \`WorkersClient.runJobStreaming\`, so inline, queued and cloud dispatch stay each job's own decision: the caller enqueues and awaits without knowing which host it is on.
+
+## Definition
+
+\`\`\`ts
+const result = await workers.runGraph({
+  id: 'release',
+  concurrency: 2,
+  failurePolicy: 'skip-dependents', // 'stop' (default) | 'continue' | 'skip-dependents'
+  nodes: [
+    { id: 'build', job: 'build.package', input: { name: 'workers' } },
+    { id: 'test', job: 'test.package' },
+    { id: 'publish', job: 'publish.package' }
+  ],
+  edges: [
+    { from: 'build', to: 'test', output: 'artifactPath', input: 'artifact' },
+    { from: 'test', to: 'publish', when: { op: 'equals', path: 'passed', value: true } }
+  ]
+});
+// result.status: 'completed' | 'failed' | 'cancelled'; result.nodes[id]: { status, result?, error?, skipReason? }
+\`\`\`
+
+- **Nodes**: \`job\` is the \`workers/job\` id; \`id\` defaults to the job id and must be unique; \`input\` is static input.
+- **Edges**: \`from\` runs before \`to\`. \`output\` (dotted path into the source result) with \`input\` (dotted path into the target input) carries data. \`when\` (\`equals\`, \`not-equals\`, \`exists\`, \`truthy\`, \`falsy\` over a path of the source result) skips the target when false.
+- **Failure policy**: \`stop\` cancels running nodes and skips the rest; \`skip-dependents\` skips only the failed node's dependents; \`continue\` still runs dependents (data edges from the failed node supply nothing, conditioned edges from it do not hold).
+- **Refusals** (\`INVALID_INPUT\`, before any job starts): \`graph-invalid\`, \`graph-duplicate-node\`, \`graph-unknown-node\`, \`graph-unknown-job\`, \`graph-cycle\`, \`graph-edge-output-without-input\`. A data edge reading a missing output fails that node with \`graph-edge-output-missing\`.
+
+## Events and cancellation
+
+\`\`\`ts
+for await (const event of workers.runGraphStreaming(definition, { signal })) {
+  // node-started | node-event | node-completed | node-failed | node-cancelled | node-skipped | graph-completed
+}
+\`\`\`
+
+Aborting \`signal\` (or abandoning the iteration) cancels running node jobs and skips unstarted nodes. The \`node-event\` envelope forwards each node job’s progress and custom events. Execution overrides are validated before dispatch. JSON equality compares object content regardless of key order; carried objects are cloned before target input writes. A parent running inside a job passes \`park: context.park\` so waiting on the graph releases its queue slot.
+
+:::card{title="See also"}
+- [\`workers.kinds\`](workers.kinds) — Worker/job/flow kinds
+- [\`workers.queues\`](workers.queues) — Queues, retry and scheduling
+:::
+`
+    },
+    parent: 'workers',
+    order: 4,
+    tags: ['workers', 'graphs', 'jobs', 'workflows', 'orchestration'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=workers.graphs.docs.descriptor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workers.graphs.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/workers.graphs.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,gBAAgB;IACpB,KAAK,EAAE,oBAAoB;IAC3B,OAAO,EAAE,oGAAoG;IAC7G,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoDT;KACC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,CAAC;IACjE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/workers.kinds.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=workers.kinds.docs.descriptor.d.ts.map

package/dist/docs/workers.kinds.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workers.kinds.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/workers.kinds.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBAySjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

@@ -0,0 +1,300 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'workers.kinds',
+    title: 'Workers Kinds',
+    summary: 'Worker, job, and flow kinds with descriptors',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+id: workers.kinds
+title: Workers Kinds
+summary: Worker, job, and flow kinds with descriptors
+tags: [workers, kinds, descriptors, runtime, background-jobs]
+parent: workers
+order: 1
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+The Workers module registers four runtime kinds for background processing: \`workers/worker\`, \`workers/job\`, \`workers/flow\`, and \`workers/adapter\`. Each follows the runtime descriptor pattern — a declarative descriptor plus one or more scope-gated implementations resolved by the active runtime scope.
+
+## Runtime kinds overview
+
+Descriptors are discovered by the runtime; implementations are registered through scoped loaders. Query a kind through the standard asset query API:
+
+\`\`\`ts
+// \`runtime\` is the VibesRuntime you were handed: \`context.runtime\` in a tool, command or job, or the plugin's \`RuntimeRef\`.
+
+// Enumerate enabled worker descriptors for the current hardware
+const workers = runtime
+  .query('workers/worker')
+  .forHardware('consumer')
+  .enabled()
+  .descriptors();
+
+// Resolve the implementation for a specific worker
+const worker = await runtime
+  .query('workers/worker')
+  .withId('maintenance')
+  .resolve();
+\`\`\`
+
+The query builder supports \`withId(id)\`, \`withIds(ids)\`, \`forHardware(hw)\`, \`enabled()\`, \`filter(fn)\` (chainable) and the terminals \`descriptors()\`, \`firstDescriptor()\`, \`first()\`, and \`resolve()\`.
+
+## workers/worker kind
+
+**Long-running background processors** that consume from a queue. The kind id is \`workers/worker\`; descriptors are validated by \`WorkerDescriptorSchema\` (the shared runtime asset base plus \`queue\`, \`concurrency\`, \`handlers\`).
+
+### Example worker descriptor
+
+\`\`\`ts
+// workers/src/maintenance/maintenance.descriptor.ts
+import { createRuntimeAsset } from '@vibesdotdev/kernel';
+import type { WorkerDescriptor } from '@vibesdotdev/kernel/kinds';
+
+export const maintenanceWorkerDescriptor = createRuntimeAsset<WorkerDescriptor>({
+  kind: 'workers/worker',
+  id: 'maintenance',
+  name: 'Maintenance',
+  description: 'Database pruning, queue cleanup, and infrastructure maintenance',
+  queue: 'maintenance-jobs',
+  concurrency: 2,
+  handlers: ['maintenance.db-prune', 'maintenance.queues-clean'],
+  hardware: ['cloud', 'consumer'],
+  tags: ['maintenance', 'scheduled', 'cleanup', 'background'],
+  enabled: true
+});
+
+export default maintenanceWorkerDescriptor;
+\`\`\`
+
+### Worker implementation
+
+Worker implementations satisfy the \`WorkerImplementation\` interface. The default implementation throws until a loader is registered; concrete adapters provide the real \`start\`/\`stop\` lifecycle.
+
+\`\`\`ts
+import type { WorkerImplementation, WorkerContext } from '@vibesdotdev/kernel/kinds';
+
+export class MaintenanceWorker implements WorkerImplementation {
+  readonly id = 'maintenance';
+  readonly descriptor: WorkerDescriptor;
+
+  constructor(descriptor: WorkerDescriptor, _context: { runtime: unknown }) {
+    this.descriptor = descriptor;
+  }
+
+  getHandlerIds(): string[] {
+    return ['maintenance.db-prune', 'maintenance.queues-clean'];
+  }
+
+  canRunOnHardware(hardware: 'cloud' | 'consumer'): boolean {
+    const hw = this.descriptor.hardware as string[] | undefined;
+    return !hw || hw.length === 0 || hw.includes(hardware);
+  }
+
+  async start(_ctx?: WorkerContext): Promise<void> {
+    // adapter wiring: bind queue, register handlers
+  }
+
+  async stop(): Promise<void> {
+    // drain + release
+  }
+}
+\`\`\`
+
+## workers/job kind
+
+**Individual job handlers** executed by a worker. Descriptors are validated by \`JobDescriptorSchema\` (base + \`queue\`, \`type\`, \`isolation\`, \`retries\`, \`timeout\`, \`schedule\`, and \`schemas: { input, output }\`).
+
+\`type\` is one of \`'default' | 'progress' | 'subtask' | 'streaming' | 'scheduled'\`; \`isolation\` is one of \`'inline' | 'worker_thread' | 'subprocess'\`.
+
+### Example job descriptor
+
+\`\`\`ts
+// workers/src/maintenance/jobs/db-prune/maintenance.db-prune.descriptor.ts
+import { createRuntimeAsset } from '@vibesdotdev/kernel';
+import type { JobDescriptor } from '@vibesdotdev/kernel/kinds';
+import {
+  maintenanceDbPruneJobDataSchema,
+  maintenanceDbPruneJobResultSchema
+} from './maintenance.db-prune.schema';
+
+export const maintenanceDbPruneJobDescriptor = createRuntimeAsset<JobDescriptor>({
+  kind: 'workers/job',
+  id: 'maintenance.db-prune',
+  name: 'DB Prune',
+  description: 'Prune old activity logs and database records',
+  queue: 'maintenance-jobs',
+  type: 'scheduled',
+  isolation: 'inline',
+  retries: { maxAttempts: 2, backoff: 'exponential', delay: 5000 },
+  schemas: {
+    input: maintenanceDbPruneJobDataSchema,
+    output: maintenanceDbPruneJobResultSchema
+  },
+  hardware: ['cloud'],
+  tags: ['maintenance', 'db', 'prune'],
+  enabled: true
+});
+
+export default maintenanceDbPruneJobDescriptor;
+\`\`\`
+
+### Job implementation
+
+Job implementations satisfy \`JobImplementation<TData, TResult>\` and run via a single \`handle(context)\` method that receives a \`JobExecutionContext\`:
+
+\`\`\`ts
+// workers/src/maintenance/jobs/db-prune/maintenance.db-prune.impl.cloud.ts
+import type {
+  JobDescriptor,
+  JobExecutionContext,
+  JobImplementation
+} from '@vibesdotdev/kernel/kinds';
+import type {
+  MaintenanceDbPruneJobData,
+  MaintenanceDbPruneJobResult
+} from './maintenance.db-prune.schema';
+
+export class MaintenanceDbPruneJob
+  implements JobImplementation<MaintenanceDbPruneJobData, MaintenanceDbPruneJobResult> {
+  readonly id: string;
+  readonly descriptor: JobDescriptor;
+  readonly type = 'scheduled' as const;
+  readonly isolation = 'inline' as const;
+
+  constructor(descriptor: JobDescriptor, _context: { runtime: unknown }) {
+    this.id = descriptor.id;
+    this.descriptor = descriptor;
+  }
+
+  async handle(
+    context: JobExecutionContext<MaintenanceDbPruneJobData>
+  ): Promise<MaintenanceDbPruneJobResult> {
+    const { dryRun, activityDays } = context.data;
+    await context.events?.progress(10);
+    // ...prune work...
+    await context.events?.progress(100);
+    return { success: true, dryRun, activityLogsPruned: 0 };
+  }
+}
+
+export default MaintenanceDbPruneJob;
+\`\`\`
+
+Optional lifecycle hooks \`beforeHandle\`, \`afterHandle\`, and \`onError\` are also part of \`JobImplementation\`.
+
+## JobExecutionContext API
+
+Each job's \`handle()\` receives a \`JobExecutionContext<TData>\`:
+
+\`\`\`ts
+interface JobExecutionContext<TData = JsonObject> {
+  jobId: string;
+  data: TData;
+  attempt: number;
+  maxAttempts: number;
+  metadata?: Record<string, JsonValue>;
+  events?: JobExecutionEvents;
+  subtasks?: JobExecutionSubtasks;
+  signal?: AbortSignal;
+}
+
+interface JobExecutionEvents {
+  progress(progress: number | JsonObject): Promise<void>;
+  emit(event: string, data?: JsonObject): Promise<void>;
+  stream(data: JsonObject): Promise<void>;
+  updateMetadata(metadata: Record<string, JsonValue>): Promise<void>;
+}
+
+interface JobExecutionSubtasks {
+  spawn<TChildData extends JsonObject = JsonObject>(
+    jobType: string,
+    data: TChildData,
+    options?: JobSpawnOptions
+  ): Promise<string>; // child job id
+  wait<TResult extends JsonValue = JsonValue>(jobId: string): Promise<TResult>;
+  subscribe?(jobId: string, handler: (event: { type: string; data?: unknown }) => void): () => void;
+}
+\`\`\`
+
+\`events\` and \`subtasks\` are optional — they are only present when the active adapter supports progress streaming and subtask orchestration.
+
+## workers/flow kind
+
+The \`workers/flow\` kind exposes **outside-job dispatch** — spawning and awaiting jobs from any caller scope. It carries no descriptor-level config; routing is handled by per-scope implementations (consumer, cloud). Resolve a \`Flow\` and call its contract methods:
+
+\`\`\`ts
+// \`runtime\` is the VibesRuntime you were handed: \`context.runtime\` in a tool, command or job, or the plugin's \`RuntimeRef\`.
+// The resolved value implements the workers/flow contract shown below.
+const flow = await runtime.query('workers/flow').resolve();
+
+// Fire-and-forget
+const jobId = await flow.fire('maintenance.db-prune', { dryRun: true });
+
+// Spawn + await a result
+const childId = await flow.spawn('maintenance.db-prune', { dryRun: false, activityDays: 30 });
+const result = await flow.wait(childId);
+
+// Spawn many at once
+const ids = await flow.spawnMany([
+  { type: 'maintenance.queues-clean', data: {} },
+  { type: 'maintenance.storage-sync', data: {} }
+]);
+\`\`\`
+
+The \`Flow\` contract is \`spawn(type, data, options?)\`, \`wait(jobId)\`, \`spawnMany(jobs)\`, and \`fire(type, data, options?)\`.
+
+## Enqueuing through the workers client
+
+Most app code does not resolve adapters directly — it uses the canonical \`runtime/client\` (\`getWorkersClient(runtime)\` on the runtime the caller was handed):
+
+\`\`\`ts
+import { getWorkersClient } from '@vibesdotdev/workers/client';
+
+const client = await getWorkersClient(runtime);
+
+// Descriptor-aware dispatch (reads dispatch from the job descriptor)
+const result = await client.runJob('maintenance.db-prune', { dryRun: false, activityDays: 30 });
+
+// Direct enqueue-and-poll against a queue
+const out = await client.enqueue('maintenance-jobs', { dryRun: true }, { jobType: 'maintenance.db-prune' });
+\`\`\`
+
+## Descriptor registration
+
+Kinds and descriptors are registered through \`createRuntimePlugin\`. Implementations are wired with \`loader(id, scope?, () => import(...))\`:
+
+\`\`\`ts
+import consumerWorkers from '@vibesdotdev/workers/consumer.plugin';
+import cloudWorkers from '@vibesdotdev/workers/cloud.plugin';
+import commonWorkers from '@vibesdotdev/workers/common.plugin';
+
+// Each host composes the canonical slice it needs; consumer hosts use consumer.plugin.
+await consumerRuntime.registerPlugin(consumerWorkers);
+await cloudRuntime.registerPlugin(cloudWorkers);
+await sharedRuntime.registerPlugin(commonWorkers);
+
+// Cloud/browser hosts contribute their own workers/adapter and workers/flow
+// descriptors and loaders. The flow id is 'flow'; no built-in cloud flow exists.
+// Without that loader, background dispatch refuses UNAVAILABLE with reason
+// 'workers-flow-unavailable'. The consumer slice supplies its local flow.
+\`\`\`
+
+:::card{title="See also"}
+- [\`workers.bindings\`](workers.bindings) — Worker bindings, env vars
+- [\`workers.queues\`](workers.queues) — Job queues, scheduling
+- [\`pm.workers\`](pm.workers) — Process manager workers
+:::
+`
+    },
+    parent: 'workers',
+    order: 1,
+    tags: ['workers', 'kinds', 'descriptors', 'runtime', 'background-jobs'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=workers.kinds.docs.descriptor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workers.kinds.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/workers.kinds.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,eAAe;IACnB,KAAK,EAAE,eAAe;IACtB,OAAO,EAAE,8CAA8C;IACvD,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyRT;KACC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,iBAAiB,CAAC;IACvE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/workers.queues.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=workers.queues.docs.descriptor.d.ts.map

package/dist/docs/workers.queues.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workers.queues.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/workers.queues.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAGvE,QAAA,MAAM,UAAU,EAAE,mBAgBjB,CAAC;AAEF,eAAe,UAAU,CAAC"}