theokit 0.12.0 → 0.13.0

package/dist/server/jobs/index.d.ts

@@ -0,0 +1,348 @@
+import { J as JobBackend, a as JobEnqueueInput, b as JobLease } from '../../job-backend-CgC8Xf33.js';
+export { N as NonRetryableError } from '../../job-backend-CgC8Xf33.js';
+import { S as StorageManager, P as PostgresFactory } from '../../storage-manager-C4jsO0Tp.js';
+import { a as PoolLike } from '../../storage-types-DsDTCPbp.js';
+
+/**
+ * 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 `.theokit/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;
+}
+
+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, DuplicateJobNameError, type EnqueueOptions, InMemoryJobBackend, type InMemoryJobBackendOptions, JOB_MANIFEST_SCHEMA_VERSION, JobBackend, type JobContext, type JobDefinition, JobEnqueueInput, JobLease, type JobManifest, type JobManifestEntry, type JobNode, type JobOptions, type JobRegistry, type JobRunner, type Outbox, type OutboxFlushOptions, PoolLike, PostgresJobBackend, type PostgresJobBackendOptions, type QueueClient, buildJobManifest, createJobRunner, createOutbox, createOutboxDispatcher, createQueueClient, defineJob, scanJobs, writeJobManifest };

package/dist/server/observability/index.d.ts

@@ -0,0 +1,324 @@
+export { a as AuditEvent, A as AuditLogger, J as JsonStdoutSink, c as createNoOpLogger, s as safeAudit } from '../../audit-log-BQWM5YLG.js';
+import { IncomingMessage } from 'node:http';
+
+/**
+ * Request log primitive (T6.2 of architecture-review-remediation-plan).
+ *
+ * Split out from `logger.ts` per PV-12 (SRP) — the file previously mixed
+ * 3 concerns (factory, warnOnce, request log). This module owns ONLY the
+ * `logRequest` flow + the devtools broadcast best-effort forwarder.
+ *
+ * Public API surface is unchanged — `logger.ts` re-exports `logRequest`
+ * + `RequestLog` + `LoggerFn` for backward compat.
+ */
+
+interface RequestLog {
+    level: string;
+    method: string;
+    url: string;
+    status: number;
+    duration: number;
+    requestId: string;
+    timestamp: string;
+}
+type LoggerFn = (log: RequestLog) => void;
+declare function logRequest(info: Omit<RequestLog, 'level' | 'timestamp'>, customLogger?: LoggerFn, req?: IncomingMessage): void;
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+interface StructuredLog {
+    level: string;
+    msg: string;
+    timestamp: string;
+    [key: string]: unknown;
+}
+interface TheoLogger {
+    debug(msg: string, context?: Record<string, unknown>): void;
+    info(msg: string, context?: Record<string, unknown>): void;
+    warn(msg: string, context?: Record<string, unknown>): void;
+    error(msg: string, context?: Record<string, unknown>): void;
+    child(context: Record<string, unknown>): TheoLogger;
+}
+declare function createLogger(options?: {
+    level?: LogLevel;
+    output?: (log: StructuredLog) => void;
+    context?: Record<string, unknown>;
+}): TheoLogger;
+/**
+ * Reset internal state. Test-only export — do not call from production.
+ */
+declare function _resetWarnOnceForTests(): void;
+/**
+ * Emit a structured warning ONCE per key. Subsequent calls with the same
+ * key are suppressed. Used for cutover-style warnings (e.g. CSRF warn)
+ * that would otherwise flood logs under load.
+ *
+ * Convention: key is `<event>:<method>:<path>` — see callers in csrf.ts.
+ *
+ * EC-2: payload may contain circular references. Wrap `JSON.stringify`
+ * in try/catch so a malformed payload doesn't crash the request handler.
+ */
+declare function warnOnce(key: string, payload: Record<string, unknown>): void;
+
+declare function levenshtein(a: string, b: string): number;
+declare function findSuggestion(input: string, candidates: string[], maxDistance?: number): string | null;
+
+/**
+ * ObservabilityAdapter — interface contract for all observability backends.
+ *
+ * Per ADR D455: framework adapter owns request/response spans.
+ * SDK adapter owns agent/tool/LLM spans. Both can emit to the same backend.
+ *
+ * Per ADR D456: implementations can be lightweight (50 LoC OTLP serializer)
+ * or full OTel SDK wrappers via defineObservabilityAdapter().
+ */
+interface SpanAttributes {
+    [key: string]: string | number | boolean | undefined;
+}
+/** Handle to an active span — setAttribute, setStatus, end. */
+interface SpanHandle {
+    /** Set a key-value attribute on this span. */
+    setAttribute(key: string, value: string | number | boolean): void;
+    /** Set the span's status (ok, error). */
+    setStatus(status: 'ok' | 'error', message?: string): void;
+    /** End the span (records duration). Idempotent — second call is a no-op. */
+    end(): void;
+}
+/** Core adapter interface. Every observability backend implements this. */
+interface ObservabilityAdapter {
+    /** Human-readable adapter name (e.g., 'console', 'theo-cloud', 'noop'). */
+    readonly name: string;
+    /** Start a new span. Returns a handle to set attributes and end it. */
+    startSpan(name: string, attributes?: SpanAttributes): SpanHandle;
+    /** Increment a counter metric. */
+    counter(name: string, value: number, attributes?: SpanAttributes): void;
+    /** Record a histogram value (e.g., duration, size). */
+    histogram(name: string, value: number, attributes?: SpanAttributes): void;
+    /** Emit a structured log. */
+    log(level: 'debug' | 'info' | 'warn' | 'error', message: string, attributes?: SpanAttributes): void;
+    /** Flush any buffered telemetry (async — may involve I/O). */
+    flush(): Promise<void>;
+    /** Shutdown the adapter (flush + release resources). Idempotent. */
+    shutdown(): Promise<void>;
+}
+
+/**
+ * NoopObservabilityAdapter — silent fallback.
+ *
+ * All methods are no-ops. Never throws, never blocks.
+ * Used as the default when no other adapter is configured.
+ * EC-2: startSpan after shutdown returns a noop span (no crash).
+ */
+
+declare class NoopObservabilityAdapter implements ObservabilityAdapter {
+    readonly name = "noop";
+    private isShutdown;
+    startSpan(_name: string, _attributes?: SpanAttributes): SpanHandle;
+    counter(_name: string, _value: number, _attributes?: SpanAttributes): void;
+    histogram(_name: string, _value: number, _attributes?: SpanAttributes): void;
+    log(_level: 'debug' | 'info' | 'warn' | 'error', _message: string, _attributes?: SpanAttributes): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+/**
+ * ConsoleObservabilityAdapter — dev-mode console output.
+ *
+ * Emits JSON-structured lines to a configurable writer (default: process.stderr).
+ * Inspired by Hono middleware timing pattern.
+ */
+
+interface ConsoleAdapterOptions {
+    /** Writer function — defaults to process.stderr.write. */
+    write?: (line: string) => void;
+}
+declare class ConsoleObservabilityAdapter implements ObservabilityAdapter {
+    readonly name = "console";
+    private write;
+    private isShutdown;
+    private spans;
+    constructor(options?: ConsoleAdapterOptions);
+    startSpan(name: string, attributes?: SpanAttributes): SpanHandle;
+    counter(name: string, value: number, attributes?: SpanAttributes): void;
+    histogram(name: string, value: number, attributes?: SpanAttributes): void;
+    log(level: 'debug' | 'info' | 'warn' | 'error', message: string, attributes?: SpanAttributes): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    private emitSpan;
+    private emit;
+}
+
+/**
+ * TheoCloudObservabilityAdapter — OTLP/HTTP batched export for TheoCloud.
+ *
+ * Zero-config via env vars (THEO_CLOUD_INGEST_URL, THEO_CLOUD_API_KEY).
+ * Batches spans and flushes via native fetch() POST.
+ *
+ * EC-1: flush failure logs warning, does NOT throw, does NOT retry (KISS).
+ * EC-2: startSpan after shutdown returns noop span.
+ */
+
+interface TheoCloudAdapterOptions {
+    /** TheoCloud ingest endpoint URL. */
+    ingestUrl: string;
+    /** TheoCloud API key for authentication. */
+    token: string;
+    /** Flush interval in ms (default: 5000). */
+    flushIntervalMs?: number;
+    /** Mock fetch for testing (never in production). */
+    _mockFetch?: typeof globalThis.fetch;
+}
+declare class TheoCloudObservabilityAdapter implements ObservabilityAdapter {
+    readonly name = "theo-cloud";
+    private pendingSpans;
+    private isShutdown;
+    private readonly opts;
+    constructor(options: TheoCloudAdapterOptions);
+    startSpan(name: string, attributes?: SpanAttributes): SpanHandle;
+    counter(_name: string, _value: number, _attributes?: SpanAttributes): void;
+    histogram(_name: string, _value: number, _attributes?: SpanAttributes): void;
+    log(_level: 'debug' | 'info' | 'warn' | 'error', _message: string, _attributes?: SpanAttributes): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Adapter registry — resolves the active observability adapter.
+ *
+ * Per ADR D457 (v1.1) priority chain:
+ *   1. Explicit config (theo.config.ts observability.provider) — ALWAYS wins
+ *   2. THEO_CLOUD_INGEST_URL env → theo-cloud adapter
+ *   3. NODE_ENV=development → console adapter
+ *   4. Fallback → noop adapter
+ */
+
+interface ResolveAdapterOptions {
+    env: Record<string, string | undefined>;
+    config?: {
+        provider?: ObservabilityAdapter;
+    };
+}
+/**
+ * Resolve the observability adapter from config + env.
+ * Called once at boot — returns the active adapter for the process lifetime.
+ */
+declare function resolveAdapter(options: ResolveAdapterOptions): ObservabilityAdapter;
+
+/**
+ * Auto-instrumentation middleware — creates spans for every HTTP request.
+ *
+ * Registers as a standard TheoKit plugin via existing hook system.
+ * No changes to plugin-runner needed.
+ *
+ * Per blueprint Pattern 2 (Hono middleware timing):
+ * - onRequest: start span with method + path
+ * - onResponse: end span with status + duration
+ * - onError: set span status to error
+ */
+
+interface PluginContext {
+    requestId: string;
+    request: {
+        method: string;
+        url: string;
+    };
+    response?: {
+        statusCode: number;
+    };
+}
+interface ObservabilityPlugin {
+    name: string;
+    onRequest(ctx: PluginContext): Promise<void>;
+    onResponse(ctx: PluginContext): Promise<void>;
+    onError(ctx: PluginContext & {
+        error: unknown;
+    }): Promise<void>;
+}
+/**
+ * Create an observability plugin that auto-instruments HTTP requests.
+ *
+ * EC-5: For SSE responses, span ends on response close, not headers sent.
+ * The caller should invoke onResponse when the stream actually closes.
+ */
+declare function createObservabilityPlugin(adapter: ObservabilityAdapter): ObservabilityPlugin;
+
+/**
+ * defineObservabilityAdapter() — public API for custom adapters.
+ *
+ * The escape hatch for self-host users who want Datadog, Grafana, Honeycomb, etc.
+ * Validates the adapter shape and returns a typed ObservabilityAdapter.
+ *
+ * @example
+ * ```ts
+ * const datadogAdapter = defineObservabilityAdapter({
+ *   name: 'datadog',
+ *   startSpan: (name, attrs) => { ... },
+ *   counter: (name, value) => { ... },
+ *   histogram: (name, value) => { ... },
+ *   log: (level, message) => { ... },
+ *   flush: async () => { ... },
+ *   shutdown: async () => { ... },
+ * })
+ *
+ * // theo.config.ts
+ * export default defineConfig({
+ *   observability: { provider: datadogAdapter },
+ * })
+ * ```
+ */
+
+interface DefineAdapterConfig {
+    name: string;
+    startSpan(name: string, attributes?: SpanAttributes): SpanHandle;
+    counter(name: string, value: number, attributes?: SpanAttributes): void;
+    histogram(name: string, value: number, attributes?: SpanAttributes): void;
+    log(level: 'debug' | 'info' | 'warn' | 'error', message: string, attributes?: SpanAttributes): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+declare function defineObservabilityAdapter(config: DefineAdapterConfig): ObservabilityAdapter;
+
+/**
+ * SpanHandle implementation — records timing + attributes.
+ *
+ * Used by console and theo-cloud adapters. Noop adapter uses NoopSpan.
+ */
+
+interface SpanData {
+    name: string;
+    attributes: Record<string, string | number | boolean>;
+    status: 'ok' | 'error';
+    statusMessage?: string;
+    startTimeMs: number;
+    endTimeMs?: number;
+    durationMs?: number;
+}
+declare class SpanImpl implements SpanHandle {
+    private readonly data;
+    private ended;
+    constructor(name: string, attributes?: SpanAttributes);
+    setAttribute(key: string, value: string | number | boolean): void;
+    setStatus(status: 'ok' | 'error', message?: string): void;
+    end(): void;
+    /** Read-only access to span data (for adapters to export). */
+    getData(): SpanData;
+    isEnded(): boolean;
+}
+/** Noop span — used by NoopAdapter and post-shutdown fallback (EC-2). */
+declare class NoopSpan implements SpanHandle {
+    setAttribute(): void;
+    setStatus(): void;
+    end(): void;
+}
+
+/**
+ * Lightweight OTLP JSON serializer — ~50 LoC, no @opentelemetry/* dependency.
+ *
+ * Per ADR D456: in-house serializer for the theo-cloud adapter.
+ * Produces valid ExportTraceServiceRequest JSON (OTLP v1.0).
+ * Pinned to OTLP JSON v1.0 (stable since 2023).
+ */
+
+/** Convert SpanData[] to OTLP JSON bytes (Uint8Array). */
+declare function serializeSpansToOtlp(spans: SpanData[], serviceName?: string): Uint8Array;
+
+export { ConsoleObservabilityAdapter, type LogLevel, type LoggerFn, NoopObservabilityAdapter, NoopSpan, type ObservabilityAdapter, type RequestLog, type SpanAttributes, type SpanHandle, SpanImpl, type StructuredLog, TheoCloudObservabilityAdapter, type TheoLogger, _resetWarnOnceForTests, createLogger, createObservabilityPlugin, defineObservabilityAdapter, findSuggestion, levenshtein, logRequest, resolveAdapter, serializeSpansToOtlp, warnOnce };

package/dist/server/plugins/index.d.ts

@@ -0,0 +1,17 @@
+import { P as PluginRunner } from '../../plugin-runner-BGBkzgi0.js';
+export { D as DuplicateDecorationError, a as DuplicatePluginError } from '../../plugin-runner-BGBkzgi0.js';
+import '../../plugin-types-DNJGxr4Z.js';
+import 'node:http';
+
+declare class InvalidPluginShapeError extends Error {
+    constructor(index: number, reason: string);
+}
+/**
+ * Build a PluginRunner from a list of plugins typically declared in
+ * `theo.config.ts` under the `plugins` field. Returns `undefined` when no
+ * plugins are configured so callers can pass `undefined` to `executeRoute`
+ * and preserve the zero-overhead path.
+ */
+declare function createPluginRunnerFromConfig(plugins: unknown): Promise<PluginRunner | undefined>;
+
+export { InvalidPluginShapeError, PluginRunner, createPluginRunnerFromConfig };