theokit 0.4.0-beta.0 → 0.4.0

package/dist/generate-DT4IIAHF.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/cli/commands/generate.ts"],"sourcesContent":["/* eslint-disable security/detect-non-literal-fs-filename --\n * CLI `theo generate`. Writes scaffolded files under `cwd` + a generator\n * name from CLI args. Build-time tool. No HTTP input.\n */\nimport { existsSync, mkdirSync, writeFileSync } from 'node:fs'\nimport { resolve, dirname } from 'node:path'\n\nexport const VALID_TYPES = ['route', 'action', 'page', 'ws'] as const\nexport type GeneratorType = (typeof VALID_TYPES)[number]\n\nexport interface GenerateOptions {\n  cwd: string\n  type: string\n  name: string\n}\n\nexport type GenerateStatus =\n  | 'created'\n  | 'already_exists'\n  | 'invalid_kind'\n  | 'invalid_name'\n  | 'not_a_project'\n\nexport interface GenerateResult {\n  status: GenerateStatus\n  filePath?: string\n  kind?: GeneratorType\n  name?: string\n  message?: string\n}\n\nfunction toKebabCase(name: string): boolean {\n  return /^[a-z][a-z0-9/-]*$/.test(name)\n}\n\n/**\n * Reserved JS identifier names that conflict with object prototype machinery\n * or would shadow built-in module shapes if used as action/route names.\n * Mirrors action-scan's RESERVED_NAMES (T1.4).\n */\nconst RESERVED_BASENAMES = new Set([\n  'index',\n  'constructor',\n  '__proto__',\n  'prototype',\n  'hasOwnProperty',\n])\n\n/**\n * Validate that a name segment doesn't hit the reserved-identifier list.\n * Checks the BASENAME (last `/` segment) — nested `admin/constructor` still\n * rejected because the file `constructor.ts` would be the conflict.\n */\nfunction hasReservedSegment(name: string): boolean {\n  const basename = name.includes('/') ? (name.split('/').pop() ?? name) : name\n  return RESERVED_BASENAMES.has(basename)\n}\n\n/**\n * EC-4: validate that resolving `targetSubpath` under `cwd` stays inside `cwd`.\n * Returns `true` when path is safe (stays inside), `false` when it escapes via\n * `..`, absolute path, null byte, or similar traversal vector.\n */\nfunction isPathInside(cwd: string, targetSubpath: string): boolean {\n  if (targetSubpath.includes('\\x00')) return false\n  if (targetSubpath.startsWith('/') || targetSubpath.startsWith('\\\\')) return false\n  const resolved = resolve(cwd, targetSubpath)\n  const cwdResolved = resolve(cwd)\n  const sep = process.platform === 'win32' ? '\\\\' : '/'\n  return resolved === cwdResolved || resolved.startsWith(cwdResolved + sep)\n}\n\nfunction toPascalCase(name: string): string {\n  return name\n    .split(/[-/]/)\n    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))\n    .join('')\n}\n\nfunction toCamelCase(name: string): string {\n  const pascal = toPascalCase(name)\n  return pascal.charAt(0).toLowerCase() + pascal.slice(1)\n}\n\nfunction generateRouteTemplate(name: string): string {\n  return [\n    `import { defineRoute } from 'theokit/server'`,\n    `import { z } from 'zod'`,\n    ``,\n    `export const GET = defineRoute({`,\n    `  handler: ({ ctx }) => {`,\n    `    return { message: 'TODO: implement ${name} GET' }`,\n    `  },`,\n    `})`,\n    ``,\n  ].join('\\n')\n}\n\nfunction generateActionTemplate(name: string): string {\n  const camel = toCamelCase(name)\n  return [\n    `import { defineAction } from 'theokit/server'`,\n    `import { z } from 'zod'`,\n    ``,\n    `export const ${camel} = defineAction({`,\n    `  input: z.object({}),`,\n    `  handler: ({ input, ctx }) => {`,\n    `    return { message: 'TODO: implement ${name}' }`,\n    `  },`,\n    `})`,\n    ``,\n  ].join('\\n')\n}\n\n/**\n * Co-located test template for `theokit generate action <name>` (T5.2 +\n * plan Q4 cenário 1: roundtrip serialize). Skeleton uses vitest BDD shape\n * per testing.md.\n */\nfunction resolveTemplate(\n  cwd: string,\n  type: GeneratorType,\n  name: string,\n): { filePath: string; content: string } | null {\n  switch (type) {\n    case 'route':\n      return {\n        filePath: resolve(cwd, 'server/routes', `${name}.ts`),\n        content: generateRouteTemplate(name),\n      }\n    case 'action':\n      return {\n        filePath: resolve(cwd, 'server/actions', `${name}.ts`),\n        content: generateActionTemplate(name),\n      }\n    case 'page':\n      return { filePath: resolve(cwd, `app/${name}/page.tsx`), content: generatePageTemplate(name) }\n    case 'ws':\n      return {\n        filePath: resolve(cwd, 'server/ws', `${name}.ts`),\n        content: generateWsTemplate(name),\n      }\n    default:\n      return null\n  }\n}\n\nfunction generateActionTestTemplate(name: string): string {\n  const camel = toCamelCase(name)\n  return [\n    `import { describe, it, expect } from 'vitest'`,\n    ``,\n    `import { ${camel} } from './${name.split('/').pop()}.js'`,\n    ``,\n    `describe('${name} action', () => {`,\n    `  it('should accept a valid input shape', () => {`,\n    `    expect(${camel}.input).toBeDefined()`,\n    `    expect(typeof ${camel}.handler).toBe('function')`,\n    `  })`,\n    ``,\n    `  it('should reject invalid input via zod schema', () => {`,\n    `    const parsed = ${camel}.input.safeParse({ __invalid: true })`,\n    `    // Empty object schema accepts {}; tighten this assertion when adding fields.`,\n    `    expect(parsed.success).toBe(true)`,\n    `  })`,\n    `})`,\n    ``,\n  ].join('\\n')\n}\n\nfunction generatePageTemplate(name: string): string {\n  const pascal = toPascalCase(name)\n  return [`export default function ${pascal}Page() {`, `  return <h1>${pascal}</h1>`, `}`, ``].join(\n    '\\n',\n  )\n}\n\nfunction generateWsTemplate(_name: string): string {\n  return [\n    `import { defineWebSocket } from 'theokit/server'`,\n    ``,\n    `export default defineWebSocket({`,\n    `  onMessage(ws, data) {`,\n    `    ws.send(\\`echo: \\${data}\\`)`,\n    `  },`,\n    `})`,\n    ``,\n  ].join('\\n')\n}\n\n/**\n * Programmatic generate. Returns a structured result instead of throwing —\n * Studio (`theokit_generate` tool) consumes this directly. The CLI wrapper\n * below maps the structured result to console output + exit code semantics.\n */\n// eslint-disable-next-line @typescript-eslint/require-await\nexport async function generate(opts: GenerateOptions): Promise<GenerateResult> {\n  const { cwd, type, name } = opts\n\n  if (!existsSync(resolve(cwd, 'theo.config.ts')) && !existsSync(resolve(cwd, 'theo.config.js'))) {\n    return {\n      status: 'not_a_project',\n      message: 'Not a Theo project. cwd has no theo.config.ts or theo.config.js',\n    }\n  }\n\n  if (!VALID_TYPES.includes(type as GeneratorType)) {\n    return {\n      status: 'invalid_kind',\n      message: `Invalid generator type \"${type}\". Available: ${VALID_TYPES.join(', ')}`,\n    }\n  }\n\n  if (!name || !toKebabCase(name)) {\n    return {\n      status: 'invalid_name',\n      message: `Invalid name \"${name}\". Use kebab-case: lowercase letters, numbers, hyphens.`,\n    }\n  }\n\n  // EC-2-related: reject reserved JS identifier basenames (would shadow\n  // built-in prototype machinery in virtual module emit or scan).\n  if (hasReservedSegment(name)) {\n    return {\n      status: 'invalid_name',\n      message: `Reserved name \"${name}\" — basename collides with built-in identifier (index/constructor/__proto__/prototype/hasOwnProperty).`,\n    }\n  }\n\n  const resolved = resolveTemplate(cwd, type as GeneratorType, name)\n  if (resolved === null) {\n    return { status: 'invalid_kind', message: `Unknown type: ${type}` }\n  }\n  const { filePath, content } = resolved\n\n  // EC-4: confirm the resolved filePath stays inside cwd. `toKebabCase`\n  // already rejects most traversal vectors but a defense-in-depth check\n  // against `..` slipping in via valid-looking segments is cheap.\n  const relativeFromCwd = filePath.startsWith(resolve(cwd))\n    ? filePath.slice(resolve(cwd).length + 1)\n    : filePath\n  if (!isPathInside(cwd, relativeFromCwd)) {\n    return {\n      status: 'invalid_name',\n      message: `Path traversal denied: \"${name}\" would escape project root.`,\n    }\n  }\n\n  if (existsSync(filePath)) {\n    return { status: 'already_exists', filePath, kind: type as GeneratorType, name }\n  }\n\n  mkdirSync(dirname(filePath), { recursive: true })\n  writeFileSync(filePath, content)\n\n  // T5.2 + plan Q4: emit co-located test file alongside actions (only\n  // for action type; routes/pages/ws keep prior single-file behavior).\n  // Skip if existing test file present (preserve user-customized tests).\n  if (type === 'action') {\n    const testPath = filePath.replace(/\\.ts$/, '.test.ts')\n    if (!existsSync(testPath)) {\n      writeFileSync(testPath, generateActionTestTemplate(name))\n    }\n  }\n\n  return { status: 'created', filePath, kind: type as GeneratorType, name }\n}\n\n/**\n * CLI entry point — preserves the original surface (throws + console.log).\n * Wraps the programmatic `generate` function.\n */\nexport async function generateCommand(type: string, name: string): Promise<void> {\n  const result = await generate({ cwd: process.cwd(), type, name })\n  switch (result.status) {\n    case 'not_a_project':\n      throw new Error('Not a Theo project. Run this from a project root with theo.config.ts')\n    case 'invalid_kind':\n      throw new Error(result.message ?? 'Invalid kind')\n    case 'invalid_name':\n      throw new Error(\n        `Invalid name \"${name}\". Use kebab-case: lowercase letters, numbers, hyphens. Example: my-route`,\n      )\n    case 'already_exists':\n      console.log(`\\n  ⚠ ${result.filePath} already exists. Skipping.\\n`)\n      return\n    case 'created':\n      console.log(`\\n  ✓ Created ${type}: ${result.filePath}\\n`)\n      return\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index-li83Swxa.d.ts

@@ -1,506 +0,0 @@
-import { S as ServerConfig, a as PostgresDatabaseConfig, P as PoolLike, d as StorageConfig, b as RedisServerConfig, R as RedisLike, c as StorageAdapter } from './storage-types-DtIVejC1.js';
-
-/**
- * Neutral `JobBackend` interface per ADR-0002.
- *
- * Implementations ship in core:
- *   - `InMemoryJobBackend` (T2.2) — dev + tests; no external deps
- *   - `PostgresJobBackend` (T3.1) — production; requires `pg` peer dep
- *
- * Community packages (`@theokit/jobs-redis`, `@theokit/jobs-sqs`, etc.)
- * implement this same interface to plug in alternate substrates without
- * modifying TheoKit core.
- */
-interface JobEnqueueInput {
-    /** The job name (matches a `defineJob` declaration). */
-    name: string;
-    /** Validated input (already passed through Zod or equivalent at the queue-client layer). */
-    input: unknown;
-    /** Optional idempotency key for at-most-once dispatch within TTL. */
-    idempotencyKey?: string;
-    /** Optional delay before the job becomes available for dispatch. */
-    delaySeconds?: number;
-    /** W3C Trace Context propagation per ADR/R0.5.9. */
-    traceparent?: string;
-    /** Maximum dispatch attempts (read from JobDefinition by the queue client). */
-    maxAttempts?: number;
-}
-interface JobLease {
-    readonly jobId: string;
-    readonly name: string;
-    readonly input: unknown;
-    readonly attempts: number;
-    readonly maxAttempts: number;
-    readonly traceparent?: string;
-    readonly lockExpiresAt: Date;
-}
-interface JobBackend {
-    /** Human-readable name for logging (e.g., "memory", "postgres"). */
-    readonly name: string;
-    /** Persist a job for later dispatch. Returns the generated jobId. */
-    enqueue(input: JobEnqueueInput): Promise<{
-        jobId: string;
-    }>;
-    /** Worker loop polls for the next available leases. */
-    dequeue(opts: {
-        batchSize?: number;
-        lockSeconds?: number;
-    }): Promise<JobLease[]>;
-    /** Mark a job complete (success). */
-    ack(jobId: string): Promise<void>;
-    /** Mark a job failed; backend decides retry vs DLQ via attempts. */
-    nack(jobId: string, opts: {
-        error: string;
-        nonRetryable?: boolean;
-    }): Promise<void>;
-    /** Optional: return existing jobId if `key` was enqueued within `ttlSeconds`. */
-    idempotency?(key: string, ttlSeconds: number): Promise<{
-        jobId: string;
-    } | null>;
-}
-/**
- * Thrown from a job handler to opt out of retry policy. The backend MUST
- * nack with `nonRetryable: true` and permanently remove the job.
- */
-declare class NonRetryableError extends Error {
-    readonly code = "NON_RETRYABLE";
-    constructor(message: string);
-}
-
-/**
- * Job primitive types (R0.5.5-9).
- *
- * @see docs/adr/0002-job-backend-interface-neutral-contract.md
- * @see docs/adr/0003-enqueue-returns-void-transactional-outbox.md
- */
-/**
- * Type registry for jobs. Users extend via module augmentation:
- *
- * ```ts
- * declare module 'theokit/server' {
- *   interface JobRegistry {
- *     'process-document': { documentId: string }
- *     'send-email': { to: string; subject: string }
- *   }
- * }
- * ```
- *
- * Once augmented, `ctx.queue.enqueue<'process-document'>(...)` gets full
- * type inference on the `input` argument.
- */
-interface JobRegistry {
-}
-interface JobContext<TInput = unknown> {
-    /** W3C trace_id propagated from the originating request or cron. */
-    readonly traceId: string;
-    /** The job's input, type-narrowed per JobRegistry entry. */
-    readonly input: TInput;
-    /** Abort signal triggered when the worker stops or lease times out. */
-    readonly signal: AbortSignal;
-    /** Attempt number (1-indexed). */
-    readonly attempt: number;
-}
-interface JobOptions<TInput = unknown> {
-    /** Optional Zod schema (or any `.parse(value)`-shaped object) for input validation. */
-    input?: {
-        parse: (value: unknown) => TInput;
-    };
-    /** Maximum dispatch attempts (default 1 — no retry surprise per ADR-0003). */
-    maxAttempts?: number;
-    /** Handler. Returns `void` per ADR-0003 — no workflow API. */
-    handler: (ctx: JobContext<TInput>) => Promise<void> | void;
-}
-interface JobDefinition<TInput = unknown> {
-    readonly name: string;
-    readonly maxAttempts: number;
-    readonly hasInputSchema: boolean;
-    readonly handler: (ctx: JobContext<TInput>) => Promise<void> | void;
-    readonly inputSchema?: {
-        parse: (value: unknown) => TInput;
-    };
-}
-
-/**
- * Declare a background job. Pure identity helper — no registration side
- * effect; the build-time scanner (T2.3) discovers definitions by walking
- * `server/jobs/` and emits `.theo/jobs.json`.
- *
- * Per ADR-0003, handler returns `void` (or `Promise<void>`); no workflow
- * API. To run another job after this one, call `ctx.queue.enqueue` from
- * the handler.
- *
- * @example
- * ```ts
- * // server/jobs/process-document.ts
- * import { defineJob } from 'theokit/server'
- * import { z } from 'zod'
- *
- * export default defineJob('process-document', {
- *   input: z.object({ documentId: z.string() }),
- *   maxAttempts: 3,
- *   async handler({ input, traceId }) {
- *     // process input.documentId
- *   },
- * })
- * ```
- */
-declare function defineJob<TInput = unknown>(name: string, options: JobOptions<TInput>): JobDefinition<TInput>;
-
-/**
- * Thrown when a plugin or middleware decorates `ctx.<key>` with a value
- * that the framework would also like to inject (e.g., `ctx.queue` from
- * the jobs backend wiring).
- *
- * Per EC-202 of system-100-percent-functional-plan: silent override is a
- * latent bug class. Fail loud so the conflict surfaces immediately.
- */
-declare class DuplicateContextKeyError extends Error {
-    readonly key: string;
-    readonly code = "DUPLICATE_CONTEXT_KEY";
-    constructor(key: string, opts?: {
-        reason?: string;
-    });
-}
-
-/**
- * In-memory job backend for dev + tests + single-instance prototypes.
- *
- * Zero external dependencies. Storage is two Maps:
- *   - `pending: Map<jobId, PendingEntry>` — all enqueued jobs (locked or not)
- *   - `idempotencyMap: Map<key, { jobId; expiresAt }>` — dedup window
- *
- * Per ADR-0002: this is one of two first-party backends shipped in core.
- * Production deploys plug in PostgresJobBackend (T3.1).
- *
- * EC-104 (jobs-crons-webhooks-cost-tracking-plan): registers a
- * `process.on('beforeExit')` handler that clears pending dispatch timers
- * and logs a warning with the dropped count. Failure mode is visible,
- * not silent. `destroy()` removes the listener for test isolation.
- */
-interface InMemoryJobBackendOptions {
-    /** Maximum pending entries before oldest is dropped + warning logged. */
-    maxPending?: number;
-}
-declare class InMemoryJobBackend implements JobBackend {
-    #private;
-    readonly name = "memory";
-    constructor(opts?: InMemoryJobBackendOptions);
-    enqueue(input: JobEnqueueInput): Promise<{
-        jobId: string;
-    }>;
-    dequeue(opts: {
-        batchSize?: number;
-        lockSeconds?: number;
-    }): Promise<JobLease[]>;
-    ack(jobId: string): Promise<void>;
-    nack(jobId: string, opts: {
-        error: string;
-        nonRetryable?: boolean;
-    }): Promise<void>;
-    idempotency(key: string, ttlSeconds: number): Promise<{
-        jobId: string;
-    } | null>;
-    /**
-     * Remove the beforeExit listener and clear all pending timers.
-     * Idempotent — safe to call multiple times. Use in test teardown to
-     * avoid leaking listeners across vitest test files.
-     */
-    destroy(): void;
-    /** EC-104 test hook — invokes the shutdown handler synchronously. */
-    triggerBeforeExitForTest(): void;
-}
-
-/**
- * StorageManager — per-process singleton coordinating pluggable storage
- * adapters (Postgres pools, Redis clients, in-memory adapters).
- *
- * Architectural decisions: see ADR-0007 (docs/adr/0007-storage-manager-singleton.md).
- *
- * Lifecycle:
- *   1. `getStorageManager()` returns the singleton (D1).
- *   2. `configure(storageConfig)` honored once per process (D3). Second call
- *      warns and is ignored.
- *   3. `usePostgres(dbName, factory)` / `useRedis(serverName, factory)`
- *      lazily create + cache (D2). Factory invoked exactly once per name.
- *   4. `register(adapter)` opts the adapter into the SIGTERM drain (D6).
- *   5. `dispose()` drains in parallel — adapters + pools + Redis (D5).
- *      Idempotent. Adapter errors logged + swallowed (do not block shutdown).
- *
- * Test seam: `__resetForTests()` resets state. Test files MUST call it from
- * `beforeEach` to avoid pollution across `it` blocks (EC-3).
- */
-
-type PostgresFactory = (server: ServerConfig, db: PostgresDatabaseConfig) => PoolLike;
-type RedisFactory = (config: RedisServerConfig) => RedisLike;
-declare class StorageManager {
-    #private;
-    /**
-     * Apply the storage config block from `theo.config.ts`. Second call warns
-     * and is ignored (D3). Reset only via `__resetForTests()`.
-     */
-    configure(config: StorageConfig): void;
-    /**
-     * Generic cache + factory for ANY client (MySQL, Mongo, Turso, DynamoDB, …).
-     * Returns the cached client OR invokes the factory and caches its return.
-     *
-     * EC-1 FIX: cache-hit check uses `Map.has(name)`, NOT `cached !== undefined`.
-     * Factories returning `null` or `undefined` are valid (lazy connect, stubs);
-     * the `!== undefined` check would re-invoke the factory infinitely for
-     * undefined returns AND silently cache `null` cast as `T`.
-     *
-     * EC-2 (documented type hole): `useStorage<A>('x', fA)` followed by
-     * `useStorage<B>('x', fB)` returns the cached A cast as B. Same trade-off
-     * as `Map<string, unknown>` — caller is responsible for using unique names
-     * per type.
-     *
-     * Lifecycle: generic clients are NOT auto-drained by `dispose()`. Call
-     * `manager.register({ name, dispose })` separately to participate.
-     *
-     * Reserved name prefixes (do NOT use): `__pg:`, `__redis:`, `__unstorage:`,
-     * `__db0:` — these are used internally by the typed helpers.
-     */
-    useStorage<T>(name: string, factory: () => T): T;
-    /**
-     * Return a Postgres pool for the named database. Lazy + cached. Factory
-     * invoked exactly once per `dbName` (D2).
-     *
-     * Throws if:
-     *   - manager is disposed
-     *   - `dbName` is not in `config.databases`
-     *   - the referenced server is not in `config.servers` (EC-2: deferred
-     *     cross-field validation surfaces here, not at configure time)
-     */
-    usePostgres(dbName: string, factory: PostgresFactory): PoolLike;
-    /**
-     * Return a Redis client for the named server. Lazy + cached. Factory
-     * invoked exactly once per `serverName`.
-     */
-    useRedis(serverName: string, factory: RedisFactory): RedisLike;
-    /**
-     * Register an adapter for graceful shutdown coordination (D6).
-     *
-     * EC-4: throws if the manager is already disposed — prevents silent
-     * leaks in test seams that reset+reuse the manager.
-     */
-    register(adapter: StorageAdapter): void;
-    /**
-     * Drain in parallel — registered adapters, then PG pools, then Redis
-     * clients. Idempotent (D5). Errors per resource are logged and swallowed
-     * — they do NOT prevent shutdown of the remaining resources.
-     *
-     * Caller must wrap in a timeout if a bound is needed (EC-7: documented).
-     * In production, `start.ts` wraps the whole shutdown sequence in a 25 s
-     * force-exit timer.
-     */
-    dispose(): Promise<void>;
-    /** @internal Testing seam — resets state so a single test file can re-use the singleton across `it` blocks (EC-3). */
-    __resetForTests(): void;
-    /** @internal Introspection helper for tests. */
-    __isConfiguredForTests(): boolean;
-    /** @internal Introspection helper for tests. */
-    __isDisposedForTests(): boolean;
-}
-declare function getStorageManager(): StorageManager;
-/** @internal Drops the module-level singleton — used by tests that need a fresh manager. */
-declare function __resetSingletonForTests(): void;
-
-interface PostgresJobBackendOptions {
-    pool: PoolLike;
-    /** Table name override (default `theokit_jobs`). */
-    tableName?: string;
-}
-declare class PostgresJobBackend implements JobBackend {
-    #private;
-    readonly name = "postgres";
-    constructor(opts: PostgresJobBackendOptions);
-    /**
-     * T2.1 — Construct a `PostgresJobBackend` using a pool managed by the
-     * shared `StorageManager`. The manager caches the pool per `dbName`, so
-     * repeated calls (in the same process) re-use the same connection pool.
-     *
-     * Equivalent to:
-     *   ```ts
-     *   const pool = manager.usePostgres(dbName, factory)
-     *   new PostgresJobBackend({ pool, ...options })
-     *   ```
-     *
-     * Errors thrown by the manager (unknown dbName, dangling server reference,
-     * manager already disposed) propagate to the caller with actionable text.
-     *
-     * @see ADR-0007
-     */
-    static fromStorageManager(manager: StorageManager, dbName: string, factory: PostgresFactory, options?: Omit<PostgresJobBackendOptions, 'pool'>): PostgresJobBackend;
-    /**
-     * Create or upgrade the schema. Idempotent (uses IF NOT EXISTS).
-     * Call once at process start; safe to re-run on every deploy.
-     */
-    migrate(): Promise<void>;
-    enqueue(input: JobEnqueueInput): Promise<{
-        jobId: string;
-    }>;
-    dequeue(opts: {
-        batchSize?: number;
-        lockSeconds?: number;
-    }): Promise<JobLease[]>;
-    ack(jobId: string): Promise<void>;
-    nack(jobId: string, opts: {
-        error: string;
-        nonRetryable?: boolean;
-    }): Promise<void>;
-    idempotency(key: string, _ttlSeconds: number): Promise<{
-        jobId: string;
-    } | null>;
-}
-
-/**
- * Transactional outbox buffer for `ctx.queue.enqueue` (T2.5).
- *
- * Lifecycle (wired in `http/execute.ts` by T2.5 integration step):
- *   1. Request handler invoked → create per-request outbox.
- *   2. Handler calls `ctx.queue.enqueue(...)` → outbox.push(entry).
- *   3a. Response committed (`res.on('finish')` + statusCode < 400) →
- *       outbox.flush(backend.enqueue).
- *   3b. Response errors (statusCode >= 400, handler throws, `res.on('close')`
- *       without finish) → outbox.discard().
- *
- * Invariants:
- *   - Outbox NEVER dispatches before commit. Backend.enqueue is NEVER
- *     called on the request hot path.
- *   - Handler throws → ZERO jobs dispatched. KEY guarantee from ADR-0003.
- *
- * EC-107: when `backend.enqueue` throws DURING flush (after response
- * committed), we log + continue. The response is already gone; partial
- * dispatch is better than zero. Each failure goes to `onError` (default:
- * `console.warn`).
- */
-interface OutboxFlushOptions {
-    /**
-     * Called once per failed entry. Default: `console.warn` with the
-     * entry name (NOT input — privacy). Throw nothing back to caller —
-     * flush always completes.
-     */
-    onError?: (entryName: string, errorMessage: string) => void;
-}
-interface Outbox {
-    push(entry: JobEnqueueInput): void;
-    drain(): JobEnqueueInput[];
-    discard(): void;
-    size(): number;
-    /**
-     * Dispatch all buffered entries via `dispatcher`. Returns after all
-     * entries attempted. Per-entry failures invoke `opts.onError` (or
-     * default warn) and do NOT abort the loop.
-     */
-    flush(dispatcher: (entry: JobEnqueueInput) => Promise<unknown>, opts?: OutboxFlushOptions): Promise<void>;
-}
-declare function createOutbox(): Outbox;
-
-/**
- * Options forwarded to `backend.enqueue` at outbox flush time.
- */
-interface EnqueueOptions {
-    /** Optional idempotency key for at-most-once dispatch within TTL. */
-    idempotencyKey?: string;
-    /** Optional delay before the job becomes available. */
-    delaySeconds?: number;
-}
-/**
- * Typed queue client. Per ADR-0003, `enqueue` returns `void` and buffers
- * to the per-request outbox. `enqueueWithId` is the log-correlation
- * variant that resolves to `{ jobId }` AFTER the outbox flushes.
- *
- * Type inference: `JobName extends keyof JobRegistry`. Users extend the
- * `JobRegistry` interface via module augmentation (see `job-types.ts`).
- * Without augmentation, all enqueue calls compile-error with "Type X is
- * not assignable to type never" — documented in EC-110 as a known onboarding
- * friction.
- */
-interface QueueClient {
-    /** Buffer a job to the outbox. Returns void (fire-and-forget). */
-    enqueue<JobName extends keyof JobRegistry>(name: JobName, input: JobRegistry[JobName], opts?: EnqueueOptions): void;
-    /**
-     * Buffer a job AND return a Promise that resolves with the jobId
-     * AFTER the outbox flushes (i.e., after the response commits). NOT a
-     * handle to await the job result — there is no result API.
-     */
-    enqueueWithId<JobName extends keyof JobRegistry>(name: JobName, input: JobRegistry[JobName], opts?: EnqueueOptions): Promise<{
-        jobId: string;
-    }>;
-}
-interface CreateQueueClientOptions {
-    /** W3C traceparent to propagate to enqueued jobs. */
-    traceparent?: string;
-}
-/**
- * Create a per-request queue client wired to a backend + outbox.
- *
- * The backend is referenced only to resolve `enqueueWithId` jobIds at
- * flush time — `enqueue` itself does NOT call backend on the hot path
- * (transactional outbox guarantee per ADR-0003).
- */
-declare function createQueueClient(backend: JobBackend, outbox: Outbox, opts?: CreateQueueClientOptions): QueueClient;
-/**
- * Outbox dispatcher that bridges enqueueWithId's hidden promise channel
- * (`__resolveJobId` / `__rejectJobId`) to the backend.enqueue result.
- *
- * Use this when the request lifecycle hooks call `outbox.flush(...)`.
- */
-declare function createOutboxDispatcher(backend: JobBackend): (entry: JobEnqueueInput) => Promise<unknown>;
-
-/**
- * Job runner — pulls leases from a backend and invokes the matching
- * handler. Each invocation wires up `JobContext` with:
- *   - `traceId` extracted from the lease's `traceparent` header (W3C
- *     Trace Context per R0.5.9), OR a fresh generated trace_id when
- *     the upstream had no traceparent OR it was malformed.
- *   - `attempt` from the lease.
- *   - `signal` that aborts when the lease times out.
- *
- * `tick()` runs one dequeue+dispatch cycle and returns when all leases
- * have been ack'd or nack'd. Production deploys call `tick()` in a loop
- * with backoff (the loop is outside this module's scope).
- *
- * EC-6 (trace continuity edge): when a lease has no traceparent OR a
- * malformed one, the handler still gets a valid traceId (generated) —
- * never null/undefined. The job MAY itself enqueue child jobs that
- * continue the new trace_id.
- */
-interface JobRunner {
-    /** Run one dequeue+dispatch cycle. */
-    tick(opts?: {
-        batchSize?: number;
-        lockSeconds?: number;
-    }): Promise<number>;
-}
-declare function createJobRunner(backend: JobBackend, definitions: readonly JobDefinition[]): JobRunner;
-
-interface JobNode {
-    readonly name: string;
-    readonly filePath: string;
-    readonly maxAttempts: number;
-    readonly hasInputSchema: boolean;
-}
-declare class DuplicateJobNameError extends Error {
-    readonly jobName: string;
-    readonly filePaths: readonly string[];
-    readonly code = "DUPLICATE_JOB_NAME";
-    constructor(jobName: string, filePaths: readonly string[]);
-}
-declare function scanJobs(jobsDir: string): Promise<JobNode[]>;
-
-declare const JOB_MANIFEST_SCHEMA_VERSION: 1;
-interface JobManifestEntry {
-    readonly name: string;
-    readonly filePath: string;
-    readonly maxAttempts: number;
-    readonly hasInputSchema: boolean;
-}
-interface JobManifest {
-    readonly schemaVersion: typeof JOB_MANIFEST_SCHEMA_VERSION;
-    readonly generatedAt: string;
-    readonly jobs: readonly JobManifestEntry[];
-}
-declare function buildJobManifest(nodes: readonly JobNode[], projectRoot?: string): JobManifest;
-declare function writeJobManifest(path: string, input: readonly JobNode[] | JobManifest, projectRoot?: string): void;
-
-export { DuplicateContextKeyError as D, type EnqueueOptions as E, InMemoryJobBackend as I, type JobBackend as J, NonRetryableError as N, type Outbox as O, type PostgresFactory as P, type QueueClient as Q, type RedisFactory as R, StorageManager as S, __resetSingletonForTests as _, DuplicateJobNameError as a, type InMemoryJobBackendOptions as b, JOB_MANIFEST_SCHEMA_VERSION as c, type JobContext as d, type JobDefinition as e, type JobEnqueueInput as f, type JobLease as g, type JobManifest as h, type JobManifestEntry as i, type JobNode as j, type JobOptions as k, type JobRegistry as l, type JobRunner as m, type OutboxFlushOptions as n, PostgresJobBackend as o, type PostgresJobBackendOptions as p, buildJobManifest as q, createJobRunner as r, createOutbox as s, createOutboxDispatcher as t, createQueueClient as u, defineJob as v, getStorageManager as w, scanJobs as x, writeJobManifest as y };