@adminiumjs/adminium 0.1.0-rc.1

package/dist/jobs/llm-run.js

@@ -0,0 +1,225 @@
+/**
+ * `llm-run` job handler — the direct-API path as an `adminium_jobs` job
+ * (06-llm-assist.md §7.5, §10.2 step 3, acceptance #6).
+ *
+ * Given a run id, it: parses the run's persisted `prompt_text` back into the
+ * per-chunk `system`/`user` messages (byte-identical to what the BYO export
+ * shows — §1 invariant 1), moves the run `draft → running`, resolves the active
+ * provider client (decrypted key — see `llm/provider-resolver.ts`), drives the
+ * repair loop in `llm/direct-runner.ts`, and persists the terminal run through
+ * T07's run-service (`validated` with the merged response + token usage +
+ * duration, or `failed` with the preserved error list). A cancel aborts the run
+ * to `discarded`.
+ *
+ * Direct-only (§9): a BYO run must never reach here — its intake is T07's
+ * `run-service.receiveResponse`, and it records NO provider/model. The handler
+ * guards on `mode === 'provider'`.
+ *
+ * Progress rides the existing jobs realtime channel (`jobs:<jobId>`, gated to the
+ * job owner or `system:jobs:read` — i.e. Admin+): the worker republishes every
+ * `ctx.progress()` there. Nothing here logs or emits the API key.
+ */
+import { BYO_SYSTEM_MARKER, BYO_USER_MARKER, } from '@adminium/llm';
+import {} from '@adminium/meta';
+import { z } from 'zod';
+import { runDirectPath, } from '../llm/direct-runner.js';
+import { createRunService, CHUNK_SEPARATOR } from '../llm/run-service.js';
+/** Job kind for the direct-API enrichment runner. */
+export const LLM_RUN_KIND = 'llm-run';
+/** Payload: the run to execute. `userId` follows the jobs owner convention (§3). */
+export const llmRunPayloadSchema = z.object({
+    runId: z.string().min(1),
+    userId: z.string().optional(),
+});
+/**
+ * Register the `llm-run` handler (mirrors `registerNoopProgressHandler`). Wire it
+ * where the registry is built (`jobs/register.ts`) with a production
+ * {@link ResolveRun}, or register it on a custom registry in tests.
+ */
+export function registerLlmRunHandler(registry, deps) {
+    const runService = deps.runService ?? createRunService({ meta: deps.meta });
+    const now = deps.now ?? Date.now;
+    registry.registerJobHandler(LLM_RUN_KIND, llmRunPayloadSchema, async (payload, ctx) => {
+        await executeLlmRun(payload, ctx, { runService, resolve: deps.resolve, now });
+        return { runId: payload.runId };
+    });
+}
+async function executeLlmRun(payload, ctx, deps) {
+    const { runService, resolve, now } = deps;
+    const existing = await runService.getRun(payload.runId);
+    if (existing === null) {
+        throw new Error(`llm-run: run not found: ${payload.runId}`);
+    }
+    // Direct-only: BYO intake is T07's receiveResponse; it records no provider (§9).
+    if (existing.mode !== 'provider') {
+        throw new Error(`llm-run requires a provider run; ${existing.id} is mode "${existing.mode}"`);
+    }
+    if (existing.promptText === null || existing.promptText.length === 0) {
+        await runService.markFailed(existing.id, {
+            errors: [providerRunError('config', 'run has no stored prompt to send')],
+        });
+        return;
+    }
+    const chunks = parsePromptChunks(existing.promptText);
+    // draft → running. A non-draft run (retry/concurrent worker) is left alone.
+    let run;
+    try {
+        run = await runService.markRunning(existing.id);
+    }
+    catch {
+        ctx.log('llm-run: run not startable, skipping', { status: existing.status });
+        return;
+    }
+    const startedAt = now();
+    try {
+        const resolved = await resolve(run);
+        const outcome = await runDirectPath({
+            chunks,
+            client: resolved.client,
+            model: resolved.model,
+            provider: resolved.provider,
+            maxTokens: resolved.maxTokens,
+            maxTokensCeiling: resolved.maxTokensCeiling,
+            validate: resolved.validate,
+            signal: ctx.signal,
+            onProgress: (event) => {
+                emitProgress(ctx, event);
+            },
+            onChunkComplete: async (received) => {
+                await runService.recordChunkProgress(run.id, received);
+            },
+        });
+        const durationMs = now() - startedAt;
+        if (outcome.status === 'cancelled') {
+            // Cooperative cancel → discard the run; the worker marks the job cancelled.
+            await safeDiscard(runService, run.id);
+            ctx.log('llm-run: cancelled', { runId: run.id });
+            return;
+        }
+        if (outcome.status === 'failed') {
+            await runService.markFailed(run.id, {
+                errors: outcome.errors,
+                tokensIn: outcome.tokensIn,
+                tokensOut: outcome.tokensOut,
+                durationMs,
+            });
+            ctx.log('llm-run: failed', { runId: run.id, errors: outcome.errors.length });
+            return;
+        }
+        await runService.recordDirectResult(run.id, {
+            response: outcome.response,
+            chunksReceived: outcome.chunksReceived,
+            tokensIn: outcome.tokensIn,
+            tokensOut: outcome.tokensOut,
+            durationMs,
+            validationErrors: outcome.errors.length > 0 ? outcome.errors : null,
+        });
+        ctx.log('llm-run: validated', {
+            runId: run.id,
+            tokensIn: outcome.tokensIn,
+            tokensOut: outcome.tokensOut,
+        });
+    }
+    catch (error) {
+        // resolve() / persistence failure. Deterministic (no key, wrong config) so a
+        // job retry would not help — fail the run and let the job complete.
+        if (ctx.signal.aborted) {
+            await safeDiscard(runService, run.id);
+            return;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        await runService.markFailed(run.id, {
+            errors: [providerRunError('config', message)],
+            durationMs: now() - startedAt,
+        });
+        ctx.log('llm-run: errored before completion', { runId: run.id });
+    }
+}
+/** Discard without throwing if the run already reached a terminal state. */
+async function safeDiscard(runService, runId) {
+    try {
+        await runService.discard(runId);
+    }
+    catch {
+        // Already terminal (e.g. finalized just before the cancel landed) — ignore.
+    }
+}
+/**
+ * Split a persisted `prompt_text` blob back into per-chunk direct-path messages.
+ * `prompt_text` is `chunk.byo` joined by {@link CHUNK_SEPARATOR}; each chunk is
+ * `=== SYSTEM ===\n<system>\n\n=== USER ===\n<user>` (the §1 invariant-1 form), so
+ * the `system`/`user` recovered here are byte-identical to what was built.
+ */
+export function parsePromptChunks(promptText) {
+    const parts = promptText.split(CHUNK_SEPARATOR);
+    const total = parts.length;
+    return parts.map((part, index) => {
+        const { system, user } = splitByo(part);
+        return { index: index + 1, total, system, user };
+    });
+}
+function splitByo(byo) {
+    const systemPrefix = `${BYO_SYSTEM_MARKER}\n`;
+    const userSeparator = `\n\n${BYO_USER_MARKER}\n`;
+    const body = byo.startsWith(systemPrefix) ? byo.slice(systemPrefix.length) : byo;
+    const at = body.indexOf(userSeparator);
+    if (at === -1) {
+        throw new Error('llm-run: prompt chunk is missing its "=== USER ===" divider');
+    }
+    return { system: body.slice(0, at), user: body.slice(at + userSeparator.length) };
+}
+function providerRunError(code, message) {
+    return { kind: 'provider', provider: 'unknown', code, message };
+}
+const NON_DONE_PCT_CAP = 99;
+/**
+ * Map a {@link RunnerPhase} to a `ctx.progress()` call (published on `jobs:<id>`).
+ * The percentage advances roughly with chunk position; `done` lands on 100.
+ */
+function emitProgress(ctx, event) {
+    switch (event.phase) {
+        case 'building':
+            ctx.progress(2, { step: 'building', message: 'Building prompt' });
+            return;
+        case 'sending':
+            ctx.progress(chunkPct(event.chunk, event.total, 0.1), {
+                step: 'sending',
+                message: `Sending to ${event.provider}/${event.model}`,
+            });
+            return;
+        case 'validating':
+            ctx.progress(chunkPct(event.chunk, event.total, 0.6), {
+                step: 'validating',
+                message: 'Validating response',
+            });
+            return;
+        case 'truncation-retry':
+            ctx.progress(chunkPct(event.chunk, event.total, 0.4), {
+                step: 'truncation-retry',
+                message: `Reply truncated — retrying with a higher token limit (${event.maxTokens})`,
+            });
+            return;
+        case 'repairing':
+            ctx.progress(chunkPct(event.chunk, event.total, 0.5), {
+                step: 'repairing',
+                message: `Repairing (${event.attempt}/${event.maxAttempts})`,
+            });
+            return;
+        case 'chunk-done':
+            ctx.progress(chunkPct(event.chunk, event.total, 1), {
+                step: 'chunk-done',
+                message: `Chunk ${event.chunk} of ${event.total} validated`,
+            });
+            return;
+        case 'done':
+            ctx.progress(100, { step: 'done', message: `Done: ${event.suggestions} suggestions` });
+            return;
+    }
+}
+/** A monotonic-ish percentage: 5–95 across chunks, `fraction` within a chunk. */
+function chunkPct(chunk, total, fraction) {
+    const span = 90 / Math.max(1, total);
+    const pct = 5 + (chunk - 1) * span + span * fraction;
+    return Math.min(NON_DONE_PCT_CAP, Math.max(0, Math.round(pct)));
+}
+//# sourceMappingURL=llm-run.js.map

package/dist/jobs/llm-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-run.js","sourceRoot":"","sources":["../../src/jobs/llm-run.ts"],"names":[],"mappings":"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"}

package/dist/jobs/register.d.ts

@@ -0,0 +1,90 @@
+/**
+ * One-call wiring for jobs + realtime (M2-T07): builds the hub, handler
+ * registry (with the demo `noop-progress` handler), polling worker and croner
+ * scheduler, registers `@fastify/websocket` + `GET /ws`, the SSE fallback and
+ * the `routes/jobs` resource under `/api/v1`, and hooks start/drain into the
+ * Fastify lifecycle.
+ *
+ * INTEGRATION POINT — `app.ts` (or the auth agent's extension hook) calls
+ *
+ *   await registerJobsAndRealtime(app, {
+ *     meta,
+ *     resolveUser: (req) => req.user ?? null,          // auth plugin
+ *     can: (user, permission) => app.rbac.can(user, permission), // rbac plugin
+ *   });
+ *
+ * AFTER the auth plugin is registered, so `resolveUser` can lean on
+ * `request.user`. This module deliberately does not touch `app.ts` or
+ * `plugins/auth.ts` (owned by the auth agent this wave).
+ */
+import type { FastifyInstance } from 'fastify';
+import { type EnqueueJobInput, type Job, type MetaDb } from '@adminium/meta';
+import { RealtimeHub } from '../realtime/hub.js';
+import { type RealtimeGatewayDeps } from '../realtime/ws.js';
+import type { ConnectionManager } from '../connections/manager.js';
+import type { FileStorage } from '../files/storage.js';
+import { type ResolveRun } from './llm-run.js';
+import { type JobRegistry } from './registry.js';
+import { JobScheduler } from './scheduler.js';
+import { JobWorker } from './worker.js';
+export interface JobsAndRealtimeOptions {
+    meta: MetaDb;
+    /** Session resolution — wire to the auth plugin's `request.user`. */
+    resolveUser: RealtimeGatewayDeps['resolveUser'];
+    /** RBAC check — wire to the rbac plugin. */
+    can: RealtimeGatewayDeps['can'];
+    /** Custom registry (tests/extensions); default: fresh + `noop-progress`. */
+    registry?: JobRegistry | undefined;
+    /**
+     * Wire the direct-API LLM enrichment runner (`llm-run` kind, 06-llm-assist.md
+     * §7.5). When supplied, the handler is registered on the registry (unless a
+     * custom registry already carries it). `resolve` turns a run into a live
+     * provider client with the decrypted key — build it with
+     * `createProviderResolver` (`llm/provider-resolver.ts`).
+     */
+    llm?: {
+        resolve: ResolveRun;
+    } | undefined;
+    /**
+     * Wire the M7-T07 data-io runners (`export-run` / `import-run`). When
+     * supplied, both handlers are registered on the registry (unless a custom
+     * registry already carries them). `manager`/`storage` are the same
+     * instances the exports/imports routes receive in compose.
+     */
+    dataIo?: {
+        manager: ConnectionManager;
+        storage: FileStorage;
+    } | undefined;
+    /** Worker tuning knobs. */
+    worker?: {
+        concurrency?: number | undefined;
+        pollIntervalMs?: number | undefined;
+        workerId?: string | undefined;
+        backoffBaseMs?: number | undefined;
+        backoffMaxMs?: number | undefined;
+    } | undefined;
+    /** Start the worker poll loop on `onReady`; default true. */
+    startWorker?: boolean | undefined;
+    /** Start the scheduler on `onReady`; default true. */
+    startScheduler?: boolean | undefined;
+    /** Route mount prefix; default {@link API_PREFIX}. */
+    apiPrefix?: string | undefined;
+}
+export interface JobsAndRealtime {
+    hub: RealtimeHub;
+    registry: JobRegistry;
+    worker: JobWorker;
+    scheduler: JobScheduler;
+    /** Programmatic enqueue for other plugins (08 §2 `app.jobs.enqueue`). */
+    enqueue(input: EnqueueJobInput): Promise<Job>;
+}
+declare module 'fastify' {
+    interface FastifyInstance {
+        /** Set by `registerJobsAndRealtime` (jobs/register.ts). */
+        jobs: JobsAndRealtime;
+        /** The realtime hub; publish server-side events here. */
+        realtime: RealtimeHub;
+    }
+}
+export declare function registerJobsAndRealtime(app: FastifyInstance, opts: JobsAndRealtimeOptions): Promise<JobsAndRealtime>;
+//# sourceMappingURL=register.d.ts.map

package/dist/jobs/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/jobs/register.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,EAAY,KAAK,eAAe,EAAE,KAAK,GAAG,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAIvF,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvD,OAAO,EAAuC,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAEpF,OAAO,EAAkD,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AACjG,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,WAAW,EAAE,mBAAmB,CAAC,aAAa,CAAC,CAAC;IAChD,4CAA4C;IAC5C,GAAG,EAAE,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACnC;;;;;;OAMG;IACH,GAAG,CAAC,EACA;QACE,OAAO,EAAE,UAAU,CAAC;KACrB,GACD,SAAS,CAAC;IACd;;;;;OAKG;IACH,MAAM,CAAC,EACH;QACE,OAAO,EAAE,iBAAiB,CAAC;QAC3B,OAAO,EAAE,WAAW,CAAC;KACtB,GACD,SAAS,CAAC;IACd,2BAA2B;IAC3B,MAAM,CAAC,EACH;QACE,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACjC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC9B,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACnC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KACnC,GACD,SAAS,CAAC;IACd,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAClC,sDAAsD;IACtD,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,WAAW,CAAC;IACjB,QAAQ,EAAE,WAAW,CAAC;IACtB,MAAM,EAAE,SAAS,CAAC;IAClB,SAAS,EAAE,YAAY,CAAC;IACxB,yEAAyE;IACzE,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CAC/C;AAED,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,eAAe;QACvB,2DAA2D;QAC3D,IAAI,EAAE,eAAe,CAAC;QACtB,yDAAyD;QACzD,QAAQ,EAAE,WAAW,CAAC;KACvB;CACF;AAED,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,eAAe,CAAC,CAiG1B"}

package/dist/jobs/register.js

@@ -0,0 +1,121 @@
+/**
+ * One-call wiring for jobs + realtime (M2-T07): builds the hub, handler
+ * registry (with the demo `noop-progress` handler), polling worker and croner
+ * scheduler, registers `@fastify/websocket` + `GET /ws`, the SSE fallback and
+ * the `routes/jobs` resource under `/api/v1`, and hooks start/drain into the
+ * Fastify lifecycle.
+ *
+ * INTEGRATION POINT — `app.ts` (or the auth agent's extension hook) calls
+ *
+ *   await registerJobsAndRealtime(app, {
+ *     meta,
+ *     resolveUser: (req) => req.user ?? null,          // auth plugin
+ *     can: (user, permission) => app.rbac.can(user, permission), // rbac plugin
+ *   });
+ *
+ * AFTER the auth plugin is registered, so `resolveUser` can lean on
+ * `request.user`. This module deliberately does not touch `app.ts` or
+ * `plugins/auth.ts` (owned by the auth agent this wave).
+ */
+import websocket from '@fastify/websocket';
+import { jobsRepo } from '@adminium/meta';
+import { API_PREFIX } from '../routes/index.js';
+import { jobOwnerId, jobsRoutes } from '../routes/jobs/index.js';
+import { RealtimeHub } from '../realtime/hub.js';
+import { registerSseRoute } from '../realtime/sse.js';
+import { registerWsRoute } from '../realtime/ws.js';
+import { EXPORT_RUN_KIND, registerExportRunHandler } from './export-run.js';
+import { IMPORT_RUN_KIND, registerImportRunHandler } from './import-run.js';
+import { LLM_RUN_KIND, registerLlmRunHandler } from './llm-run.js';
+import { REPORT_RUN_KIND, registerReportRunHandler } from './report-run.js';
+import { createJobRegistry, registerNoopProgressHandler } from './registry.js';
+import { JobScheduler } from './scheduler.js';
+import { JobWorker } from './worker.js';
+export async function registerJobsAndRealtime(app, opts) {
+    const { meta } = opts;
+    const jobs = jobsRepo(meta);
+    let registry = opts.registry;
+    if (registry === undefined) {
+        registry = createJobRegistry();
+        registerNoopProgressHandler(registry);
+    }
+    if (opts.llm !== undefined && !registry.has(LLM_RUN_KIND)) {
+        registerLlmRunHandler(registry, { meta, resolve: opts.llm.resolve });
+    }
+    const hub = new RealtimeHub();
+    if (opts.dataIo !== undefined) {
+        const { manager, storage } = opts.dataIo;
+        if (!registry.has(EXPORT_RUN_KIND)) {
+            registerExportRunHandler(registry, { meta, manager, storage });
+        }
+        if (!registry.has(IMPORT_RUN_KIND)) {
+            registerImportRunHandler(registry, { meta, manager, storage, hub });
+        }
+        // report-run rides the SAME option: it drives the export-run handler
+        // through this registry (jobs/report-run.ts), so it is only meaningful
+        // where the data-io pipeline is wired.
+        if (!registry.has(REPORT_RUN_KIND)) {
+            registerReportRunHandler(registry, { meta, registry, hub });
+        }
+    }
+    const worker = new JobWorker({
+        meta,
+        registry,
+        hub,
+        logger: app.log,
+        concurrency: opts.worker?.concurrency,
+        pollIntervalMs: opts.worker?.pollIntervalMs,
+        workerId: opts.worker?.workerId,
+        backoffBaseMs: opts.worker?.backoffBaseMs,
+        backoffMaxMs: opts.worker?.backoffMaxMs,
+    });
+    const scheduler = new JobScheduler({ jobs, logger: app.log });
+    const gatewayDeps = {
+        hub,
+        resolveUser: opts.resolveUser,
+        can: opts.can,
+        // Job owners may follow their own jobs:<id> channel (§3 topics table).
+        getJobOwner: async (jobId) => jobOwnerId(await jobs.findById(jobId)),
+    };
+    await app.register(websocket, {
+        options: { maxPayload: 64 * 1024 },
+    });
+    registerWsRoute(app, gatewayDeps);
+    await app.register(async (api) => {
+        registerSseRoute(api, gatewayDeps);
+        await api.register(jobsRoutes({
+            meta,
+            registry,
+            worker,
+            hub,
+            resolveUser: opts.resolveUser,
+            can: opts.can,
+        }));
+    }, { prefix: opts.apiPrefix ?? API_PREFIX });
+    const facade = {
+        hub,
+        registry,
+        worker,
+        scheduler,
+        enqueue: async (input) => await jobs.enqueue(input),
+    };
+    if (!app.hasDecorator('jobs'))
+        app.decorate('jobs', facade);
+    if (!app.hasDecorator('realtime'))
+        app.decorate('realtime', hub);
+    app.addHook('onReady', async () => {
+        if (opts.startWorker ?? true)
+            worker.start();
+        if (opts.startScheduler ?? true)
+            scheduler.start();
+    });
+    // Graceful shutdown (08 §6.10): stop ticking, drain in-flight jobs, drop
+    // realtime subscriptions (WS sockets are closed by @fastify/websocket).
+    app.addHook('onClose', async () => {
+        scheduler.stop();
+        await worker.stop();
+        hub.close();
+    });
+    return facade;
+}
+//# sourceMappingURL=register.js.map

package/dist/jobs/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/jobs/register.ts"],"names":[],"mappings":"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"}

package/dist/jobs/registry.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Typed job-handler registry (08-server-api.md §2.17 job kinds, M2-T07).
+ * Each kind pairs a Zod payload schema with an async handler; the worker
+ * parses the stored payload against the schema before every run (the queue
+ * row is `json` — 07-meta-store.md §3.12 "Zod-validated by the worker").
+ */
+import { z, type ZodType } from 'zod';
+/** Last reported progress of a job (08 §3 `progress` event data). */
+export interface JobProgress {
+    /** Integer 0–100. */
+    pct: number;
+    step?: string | undefined;
+    message?: string | undefined;
+}
+/** Per-run context handed to a handler alongside its parsed payload. */
+export interface JobHandlerContext {
+    jobId: string;
+    kind: string;
+    /** 1-based attempt number (equals the row's `attempts` after claim). */
+    attempt: number;
+    maxAttempts: number;
+    /**
+     * Cooperative cancellation (08 §2.17): aborted by `POST /jobs/:id/cancel`
+     * and by worker drain timeouts. Handlers check it between batches.
+     */
+    signal: AbortSignal;
+    /** Report progress: persisted by the worker and published on `jobs:<id>`. */
+    progress(pct: number, info?: {
+        step?: string;
+        message?: string;
+    }): void;
+    /** Structured log line under the worker's logger, tagged with the job id. */
+    log(message: string, data?: Record<string, unknown>): void;
+}
+/** A job handler: parsed payload in, optional result out (result unused in M2). */
+export type JobHandler<T> = (payload: T, ctx: JobHandlerContext) => Promise<unknown> | unknown;
+export interface RegisteredJobHandler {
+    kind: string;
+    schema: ZodType<unknown>;
+    handler: JobHandler<never>;
+    /** Run the handler with an already-`schema`-parsed payload. */
+    run(parsedPayload: unknown, ctx: JobHandlerContext): Promise<unknown>;
+}
+/** Creates an isolated registry (one per server; fresh per test). */
+export declare function createJobRegistry(): {
+    /** Register `handler` for `kind`; duplicate kinds are a programmer error. */
+    registerJobHandler<T>(kind: string, schema: ZodType<T>, handler: JobHandler<T>): void;
+    has(kind: string): boolean;
+    get(kind: string): RegisteredJobHandler | undefined;
+    kinds(): string[];
+};
+export type JobRegistry = ReturnType<typeof createJobRegistry>;
+/** Kind of the built-in demo/progress-exercise handler. */
+export declare const NOOP_PROGRESS_KIND = "noop-progress";
+/**
+ * Payload of `noop-progress`: walks progress 0→100 in `steps` increments.
+ * `failAttempts` makes the first N attempts throw (retry/backoff demos);
+ * `stepDelayMs` spaces the steps out (cancellation demos).
+ */
+export declare const noopProgressPayloadSchema: z.ZodObject<{
+    steps: z.ZodDefault<z.ZodNumber>;
+    stepDelayMs: z.ZodDefault<z.ZodNumber>;
+    failAttempts: z.ZodDefault<z.ZodNumber>;
+    userId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type NoopProgressPayload = z.infer<typeof noopProgressPayloadSchema>;
+/** Thrown by handlers that notice `ctx.signal` mid-run. */
+export declare class JobCancelledError extends Error {
+    readonly name = "JobCancelledError";
+    constructor(jobId: string);
+}
+/** Registers the demo `noop-progress` handler (tests, dev demos). */
+export declare function registerNoopProgressHandler(registry: JobRegistry): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/jobs/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/jobs/registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,CAAC,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAEtC,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,qBAAqB;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAED,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,EAAE,WAAW,CAAC;IACpB,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACxE,6EAA6E;IAC7E,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC5D;AAED,mFAAmF;AACnF,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAE/F,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB,OAAO,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IAC3B,+DAA+D;IAC/D,GAAG,CAAC,aAAa,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACvE;AAED,qEAAqE;AACrE,wBAAgB,iBAAiB;IAI7B,6EAA6E;uBAC1D,CAAC,QAAQ,MAAM,UAAU,OAAO,CAAC,CAAC,CAAC,WAAW,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;cAe3E,MAAM,GAAG,OAAO;cAIhB,MAAM,GAAG,oBAAoB,GAAG,SAAS;aAI1C,MAAM,EAAE;EAIpB;AAED,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAI/D,2DAA2D;AAC3D,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;;;;iBAMpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,2DAA2D;AAC3D,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAkB,IAAI,uBAAuB;gBAEjC,KAAK,EAAE,MAAM;CAG1B;AAED,qEAAqE;AACrE,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAavE"}

package/dist/jobs/registry.js

@@ -0,0 +1,78 @@
+/**
+ * Typed job-handler registry (08-server-api.md §2.17 job kinds, M2-T07).
+ * Each kind pairs a Zod payload schema with an async handler; the worker
+ * parses the stored payload against the schema before every run (the queue
+ * row is `json` — 07-meta-store.md §3.12 "Zod-validated by the worker").
+ */
+import { setTimeout as sleep } from 'node:timers/promises';
+import { z } from 'zod';
+/** Creates an isolated registry (one per server; fresh per test). */
+export function createJobRegistry() {
+    const handlers = new Map();
+    return {
+        /** Register `handler` for `kind`; duplicate kinds are a programmer error. */
+        registerJobHandler(kind, schema, handler) {
+            if (kind.length === 0 || kind.length > 60) {
+                throw new Error(`job kind must be 1–60 chars, got "${kind}"`);
+            }
+            if (handlers.has(kind)) {
+                throw new Error(`job handler for kind "${kind}" is already registered`);
+            }
+            handlers.set(kind, {
+                kind,
+                schema,
+                handler: handler,
+                run: async (parsedPayload, ctx) => await handler(parsedPayload, ctx),
+            });
+        },
+        has(kind) {
+            return handlers.has(kind);
+        },
+        get(kind) {
+            return handlers.get(kind);
+        },
+        kinds() {
+            return [...handlers.keys()];
+        },
+    };
+}
+// --- demo handler ----------------------------------------------------------------
+/** Kind of the built-in demo/progress-exercise handler. */
+export const NOOP_PROGRESS_KIND = 'noop-progress';
+/**
+ * Payload of `noop-progress`: walks progress 0→100 in `steps` increments.
+ * `failAttempts` makes the first N attempts throw (retry/backoff demos);
+ * `stepDelayMs` spaces the steps out (cancellation demos).
+ */
+export const noopProgressPayloadSchema = z.object({
+    steps: z.number().int().min(1).max(100).default(4),
+    stepDelayMs: z.number().int().min(0).max(60_000).default(0),
+    failAttempts: z.number().int().min(0).max(100).default(0),
+    /** Owner convention: `payload.userId` marks the enqueuing user. */
+    userId: z.string().optional(),
+});
+/** Thrown by handlers that notice `ctx.signal` mid-run. */
+export class JobCancelledError extends Error {
+    name = 'JobCancelledError';
+    constructor(jobId) {
+        super(`job ${jobId} cancelled`);
+    }
+}
+/** Registers the demo `noop-progress` handler (tests, dev demos). */
+export function registerNoopProgressHandler(registry) {
+    registry.registerJobHandler(NOOP_PROGRESS_KIND, noopProgressPayloadSchema, async (payload, ctx) => {
+        if (ctx.attempt <= payload.failAttempts) {
+            throw new Error(`noop-progress simulated failure (attempt ${ctx.attempt})`);
+        }
+        for (let step = 0; step <= payload.steps; step += 1) {
+            if (ctx.signal.aborted)
+                throw new JobCancelledError(ctx.jobId);
+            const pct = Math.round((step / payload.steps) * 100);
+            ctx.progress(pct, { step: `step-${step}`, message: `${step} of ${payload.steps} steps done` });
+            if (payload.stepDelayMs > 0 && step < payload.steps)
+                await sleep(payload.stepDelayMs);
+        }
+        return { steps: payload.steps };
+    });
+}
+//# sourceMappingURL=registry.js.map

package/dist/jobs/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/jobs/registry.ts"],"names":[],"mappings":"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"}