@inflexa-ai/harness 0.1.1

package/dist/providers/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Provider seam — shared AI SDK-backed types.
+ *
+ * The harness talks to LLMs and embedding models through narrow,
+ * vendor-neutral interfaces. Every call carries an `AgentSession`; billing
+ * attribution is resolved lazily at the provider wire boundary.
+ */
+import type { FinishReason, LanguageModel, ModelMessage, ToolSet } from "ai";
+import type { ProviderOptions } from "@ai-sdk/provider-utils";
+import type { ResultAsync } from "neverthrow";
+import type { AgentSession } from "../auth/types.js";
+import type { ProviderError } from "./errors.js";
+export type { FinishReason, LanguageModel, ModelMessage, ProviderOptions, ToolSet };
+export interface ProviderCapabilities {
+    readonly toolCalling: boolean;
+}
+export interface ChatRequest {
+    readonly system: string;
+    readonly messages: readonly ModelMessage[];
+    readonly tools: ToolSet;
+    readonly toolChoice?: "auto" | "none" | "required" | {
+        readonly type: "tool";
+        readonly toolName: string;
+    };
+    readonly providerOptions?: ProviderOptions;
+}
+export interface ChatResponse {
+    readonly message: Extract<ModelMessage, {
+        role: "assistant";
+    }>;
+    readonly finishReason: FinishReason;
+    readonly rawFinishReason?: string;
+}
+export type ChatStreamEvent = {
+    readonly type: "text-delta";
+    readonly text: string;
+} | {
+    readonly type: "done";
+    readonly response: ChatResponse;
+};
+export interface AgentChat {
+    readonly capabilities: ProviderCapabilities;
+    chat(req: ChatRequest, session: AgentSession, signal?: AbortSignal): ResultAsync<ChatResponse, ProviderError>;
+}
+export interface ChatProvider extends AgentChat {
+    chatStream(req: ChatRequest, session: AgentSession, signal?: AbortSignal): AsyncIterable<ChatStreamEvent>;
+}
+export interface EmbeddingProvider {
+    /**
+     * Width of every vector `embed` returns. The write-side index paths create
+     * each per-analysis pgvector index at exactly this width (`ensureSearchIndex`),
+     * so the provider — not a harness constant — is the single source of the
+     * dimension. A provider advertising a width its model does not emit fails at
+     * the vector upsert, not here.
+     */
+    readonly dimensions: number;
+    embed(texts: readonly string[], session: AgentSession): ResultAsync<number[][], ProviderError>;
+}
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;

package/dist/providers/types.js

@@ -0,0 +1,8 @@
+/**
+ * Provider seam — shared AI SDK-backed types.
+ *
+ * The harness talks to LLMs and embedding models through narrow,
+ * vendor-neutral interfaces. Every call carries an `AgentSession`; billing
+ * attribution is resolved lazily at the provider wire boundary.
+ */
+export {};

package/dist/runtime/assemble.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `assembleCoreRuntime` — the one host-neutral assembly point.
+ *
+ * Collapses the two halves of composition into a single call: it registers the
+ * durable workflows with the DBOS engine AND builds the conversation agent over
+ * the registered callables. Both an embedder's cloud root and the cloud-free
+ * root drive the same body, supplying their own seam realizations — the wiring
+ * order here is the single source of truth for both.
+ *
+ * Registration order is load-bearing. The child sandbox-step workflow registers
+ * first because the parent's child dispatch closes over its registered callable;
+ * `buildExecuteAnalysis` therefore receives that callable rather than a
+ * pre-built deps bundle. Every workflow lands under one `launchDbos`
+ * `applicationVersion` stamp because all registration happens in this one call,
+ * before launch — a blue/green drain treats them as a single cohort.
+ */
+import { type ConversationAgentDeps } from "../agents/conversation-agent.js";
+import type { ResourcePolicy } from "../config/resource-limits.js";
+import type { AgentDefinition } from "../loop/types.js";
+import { type ExecuteAnalysisDeps, type ExecuteAnalysisInput, type ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
+import { type SandboxStepDeps, type SandboxStepInput, type SandboxStepResult } from "../workflows/sandbox-step.js";
+import { type ExecuteTargetAssessmentDeps, type ExecuteTargetAssessmentInput, type ExecuteTargetAssessmentResult } from "../workflows/execute-target-assessment.js";
+import { type DataProfileDeps, type DataProfileWorkflowInput } from "../tasks/data-profile.js";
+import { type EphemeralDeps, type EphemeralResult, type EphemeralWorkflowInput } from "../execution/ephemeral-runner.js";
+/** Registered child sandbox-step callable the parent's child dispatch closes over. */
+export type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxStepResult>;
+/**
+ * Deps bundles for the five durable workflows. `executeAnalysis` is a builder
+ * because its `sandboxStepCallable` is the registered sandbox-step callable,
+ * which does not exist until registration runs inside `assembleCoreRuntime`.
+ */
+export interface CoreWorkflowDeps {
+    readonly sandboxStep: SandboxStepDeps;
+    readonly buildExecuteAnalysis: (sandboxStep: SandboxStepCallable) => ExecuteAnalysisDeps;
+    readonly executeTargetAssessment: ExecuteTargetAssessmentDeps;
+    readonly dataProfile: DataProfileDeps;
+    readonly ephemeral: Omit<EphemeralDeps, "resourcePolicy">;
+}
+/** The registered, callable workflow handles. */
+export interface RegisteredWorkflows {
+    readonly executeAnalysis: (input: ExecuteAnalysisInput) => Promise<ExecuteAnalysisResult>;
+    readonly sandboxStep: SandboxStepCallable;
+    readonly executeTargetAssessment: (input: ExecuteTargetAssessmentInput) => Promise<ExecuteTargetAssessmentResult>;
+    readonly dataProfile: (input: DataProfileWorkflowInput) => Promise<void>;
+    readonly ephemeral: (input: EphemeralWorkflowInput) => Promise<EphemeralResult>;
+}
+/**
+ * Conversation-agent deps minus the two workflow callables and the resource
+ * policy — `assembleCoreRuntime` supplies those itself so a caller cannot wire
+ * a stale callable or a policy that diverges from the one the workflows see.
+ */
+export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "ephemeralWorkflow" | "resourcePolicy">;
+export interface CoreRuntimeDeps {
+    readonly conversation: ConversationAssemblyDeps;
+    readonly workflows: CoreWorkflowDeps;
+    /**
+     * Host resource policy — per-step ceilings, machine budget, ephemeral
+     * sizing. One supply point: assembly distributes it to the planner tools,
+     * `execute_plan` (budget snapshot into workflow input), and the ephemeral
+     * runner. Absent, every consumer keeps its legacy behavior.
+     */
+    readonly resourcePolicy?: ResourcePolicy;
+}
+export interface CoreRuntime {
+    readonly conversationAgent: AgentDefinition;
+    readonly workflows: RegisteredWorkflows;
+}
+export declare function assembleCoreRuntime(deps: CoreRuntimeDeps): CoreRuntime;

package/dist/runtime/assemble.js

@@ -0,0 +1,46 @@
+/**
+ * `assembleCoreRuntime` — the one host-neutral assembly point.
+ *
+ * Collapses the two halves of composition into a single call: it registers the
+ * durable workflows with the DBOS engine AND builds the conversation agent over
+ * the registered callables. Both an embedder's cloud root and the cloud-free
+ * root drive the same body, supplying their own seam realizations — the wiring
+ * order here is the single source of truth for both.
+ *
+ * Registration order is load-bearing. The child sandbox-step workflow registers
+ * first because the parent's child dispatch closes over its registered callable;
+ * `buildExecuteAnalysis` therefore receives that callable rather than a
+ * pre-built deps bundle. Every workflow lands under one `launchDbos`
+ * `applicationVersion` stamp because all registration happens in this one call,
+ * before launch — a blue/green drain treats them as a single cohort.
+ */
+import { createConversationAgent } from "../agents/conversation-agent.js";
+import { registerExecuteAnalysis } from "../workflows/execute-analysis.js";
+import { registerSandboxStep } from "../workflows/sandbox-step.js";
+import { registerExecuteTargetAssessment, } from "../workflows/execute-target-assessment.js";
+import { registerDataProfileWorkflow } from "../tasks/data-profile.js";
+import { registerEphemeralWorkflow } from "../execution/ephemeral-runner.js";
+export function assembleCoreRuntime(deps) {
+    const { conversation, workflows: wf, resourcePolicy } = deps;
+    const sandboxStep = registerSandboxStep(wf.sandboxStep);
+    const executeAnalysis = registerExecuteAnalysis(wf.buildExecuteAnalysis(sandboxStep));
+    const executeTargetAssessment = registerExecuteTargetAssessment(wf.executeTargetAssessment);
+    const dataProfile = registerDataProfileWorkflow(wf.dataProfile);
+    const ephemeral = registerEphemeralWorkflow({ ...wf.ephemeral, resourcePolicy });
+    const conversationAgent = createConversationAgent({
+        ...conversation,
+        executeAnalysisWorkflow: executeAnalysis,
+        ephemeralWorkflow: ephemeral,
+        resourcePolicy,
+    });
+    return {
+        conversationAgent,
+        workflows: {
+            executeAnalysis,
+            sandboxStep,
+            executeTargetAssessment,
+            dataProfile,
+            ephemeral,
+        },
+    };
+}

package/dist/runtime/boot.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `bootHarness` — the harness-owned boot sequence.
+ *
+ * `assembleCoreRuntime` stays sync and pure (it is the register-before-launch
+ * cohort SOT, driven by tests on `passthroughStep`). `bootHarness` wraps it with
+ * the ordered, effectful boot steps every host must run in the same order, and
+ * returns a `shutdown` handle the embedder wires to its process signals. The
+ * ordering is load-bearing and runs cheapest-failure-first:
+ *
+ *   1. `initTelemetry()` — before any tracer/meter is read. Injected; defaults
+ *      to a no-op so a library host never acquires process-wide telemetry (or a
+ *      console banner) it did not ask for. An embedder that wants harness OTel
+ *      passes `initOtel` / `shutdownOtel` here.
+ *   2. `validateAgentSkills(skillsDir, SANDBOX_AGENT_META)` — pure fs stat, zero
+ *      external deps. A `meta.skills` typo or a `skillsDir` / image drift dies in
+ *      milliseconds, before any Postgres or DBOS cost is paid (agent-skill-assignment).
+ *   3. `initCortexState(pool)` — app tables must exist before launch; recovery
+ *      queries them on the first step.
+ *   4. `assertConnectionBudget(...)` — needs the live pool; gates launch so a
+ *      misconfigured pool fails loudly at boot, not under load.
+ *   5. `assembleCoreRuntime(core)` — registers the durable-workflow cohort and
+ *      builds the conversation agent (register-before-launch invariant).
+ *   6. `beforeLaunch()` — embedder hook for host-specific pre-launch work that
+ *      must attach before DBOS launch re-emits events (scheduled sweeps, an
+ *      ephemeral-workflow reap, an agent-switch install). Runs after registration
+ *      so it may close over the registered callables.
+ *   7. `launchDbos(...)` — the last registration-dependent step.
+ *
+ * Boot-step errors PROPAGATE (the embedder's composition root catches them and
+ * releases whatever it acquired). Only `shutdown` swallows per-step failures —
+ * once shutdown starts, exiting takes precedence (see `runShutdownSequence`).
+ */
+import type { Pool } from "pg";
+import type pino from "pino";
+import { type CoreRuntime, type CoreRuntimeDeps } from "./assemble.js";
+import { type ConnectionBudgetConfig } from "./connection-budget.js";
+import { type DbosConfig } from "./dbos.js";
+export interface BootHarnessDeps {
+    /** Everything `assembleCoreRuntime` needs (workflow + conversation deps, resource policy). */
+    readonly core: CoreRuntimeDeps;
+    /** App `pg.Pool` — used for state init, the connection-budget guard, and closed on shutdown. */
+    readonly pool: Pool;
+    /** Skills root; validated against the harness-owned agent catalog before launch. */
+    readonly skillsDir: string;
+    /** DBOS launch config (carries the stable `executorId`). */
+    readonly dbos: DbosConfig;
+    /** Connection-budget guard config. */
+    readonly connectionBudget: ConnectionBudgetConfig;
+    readonly logger: pino.Logger;
+    /**
+     * Host-specific work that must run AFTER workflow registration and BEFORE
+     * DBOS launch (scheduled sweeps, ephemeral reap, agent-switch install). The
+     * booted runtime is not returned until after launch, so this hook captures
+     * whatever it needs from the embedder's own composition root.
+     */
+    readonly beforeLaunch?: () => void | Promise<void>;
+    /** Telemetry init. Default no-op; pass `initOtel` to enable harness OTel. */
+    readonly initTelemetry?: () => void;
+    /** Shutdown-time telemetry flush. Default no-op; pass `shutdownOtel` to match. */
+    readonly shutdownTelemetry?: () => Promise<void>;
+    /** HTTP drain at shutdown. Default no-op — a library host owns no server. */
+    readonly closeHttpServer?: () => Promise<void>;
+    /** Logger flush at shutdown. Default no-op. */
+    readonly flushLogger?: () => Promise<void>;
+    /** Process exit at shutdown. Default no-op — the embedder owns process lifecycle. */
+    readonly exit?: (code: number) => void;
+}
+export interface BootedHarness {
+    readonly runtime: CoreRuntime;
+    /** Runs the graceful-shutdown sequence in durability order. Wire to SIGTERM/SIGINT. */
+    readonly shutdown: (signal: string) => Promise<void>;
+}
+export declare function bootHarness(deps: BootHarnessDeps): Promise<BootedHarness>;

package/dist/runtime/boot.js

@@ -0,0 +1,65 @@
+/**
+ * `bootHarness` — the harness-owned boot sequence.
+ *
+ * `assembleCoreRuntime` stays sync and pure (it is the register-before-launch
+ * cohort SOT, driven by tests on `passthroughStep`). `bootHarness` wraps it with
+ * the ordered, effectful boot steps every host must run in the same order, and
+ * returns a `shutdown` handle the embedder wires to its process signals. The
+ * ordering is load-bearing and runs cheapest-failure-first:
+ *
+ *   1. `initTelemetry()` — before any tracer/meter is read. Injected; defaults
+ *      to a no-op so a library host never acquires process-wide telemetry (or a
+ *      console banner) it did not ask for. An embedder that wants harness OTel
+ *      passes `initOtel` / `shutdownOtel` here.
+ *   2. `validateAgentSkills(skillsDir, SANDBOX_AGENT_META)` — pure fs stat, zero
+ *      external deps. A `meta.skills` typo or a `skillsDir` / image drift dies in
+ *      milliseconds, before any Postgres or DBOS cost is paid (agent-skill-assignment).
+ *   3. `initCortexState(pool)` — app tables must exist before launch; recovery
+ *      queries them on the first step.
+ *   4. `assertConnectionBudget(...)` — needs the live pool; gates launch so a
+ *      misconfigured pool fails loudly at boot, not under load.
+ *   5. `assembleCoreRuntime(core)` — registers the durable-workflow cohort and
+ *      builds the conversation agent (register-before-launch invariant).
+ *   6. `beforeLaunch()` — embedder hook for host-specific pre-launch work that
+ *      must attach before DBOS launch re-emits events (scheduled sweeps, an
+ *      ephemeral-workflow reap, an agent-switch install). Runs after registration
+ *      so it may close over the registered callables.
+ *   7. `launchDbos(...)` — the last registration-dependent step.
+ *
+ * Boot-step errors PROPAGATE (the embedder's composition root catches them and
+ * releases whatever it acquired). Only `shutdown` swallows per-step failures —
+ * once shutdown starts, exiting takes precedence (see `runShutdownSequence`).
+ */
+import { SANDBOX_AGENT_META } from "../agents/sandbox/index.js";
+import { validateAgentSkills } from "../agents/sandbox/validate-skills.js";
+import { initCortexState } from "../state/init.js";
+import { assembleCoreRuntime } from "./assemble.js";
+import { assertConnectionBudget } from "./connection-budget.js";
+import { launchDbos, shutdownDbos } from "./dbos.js";
+import { markDraining } from "./lifecycle.js";
+import { runShutdownSequence } from "./shutdown.js";
+const noop = () => { };
+const noopAsync = () => Promise.resolve();
+export async function bootHarness(deps) {
+    const { core, pool, skillsDir, logger } = deps;
+    (deps.initTelemetry ?? noop)();
+    validateAgentSkills(skillsDir, SANDBOX_AGENT_META);
+    await initCortexState(pool);
+    await assertConnectionBudget({ pool, logger, config: deps.connectionBudget });
+    const runtime = assembleCoreRuntime(core);
+    await deps.beforeLaunch?.();
+    await launchDbos({ config: deps.dbos, logger });
+    logger.info({ executorId: deps.dbos.executorId }, "[boot] harness booted");
+    const shutdown = (signal) => runShutdownSequence({
+        signal,
+        logger,
+        markDraining,
+        closeHttpServer: deps.closeHttpServer ?? noopAsync,
+        shutdownDbos: () => shutdownDbos({ logger }),
+        closePool: () => pool.end(),
+        flushLogger: deps.flushLogger ?? noopAsync,
+        shutdownOtel: deps.shutdownTelemetry ?? noopAsync,
+        exit: deps.exit ?? noop,
+    });
+    return { runtime, shutdown };
+}

package/dist/runtime/connection-budget.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Boot-time Postgres connection-budget guard.
+ *
+ * Cortex runs two pools per pod against the same Postgres cluster (see the postgres-storage-backend spec):
+ * the application pool (`lib/storage.ts::createPool()`, sized via the optional
+ * `DB_POOL_MAX`) and the DBOS system-DB pool (`runtime/dbos.ts`, sized via
+ * `DBOS_SYSTEM_POOL_SIZE`). This guard asserts a single pod's footprint fits
+ * inside `max_connections` — it catches gross misconfiguration (a pool larger
+ * than the cluster can serve) without the pod needing to know the fleet size.
+ *
+ * Fleet-level capacity is intentionally NOT asserted here. A pod cannot learn
+ * the live replica count at boot (the Deployment's `spec.replicas` is not
+ * exposed via the downward API, and under an HPA it varies), so a fleet-wide
+ * assertion would either give false confidence or fail spuriously. The fleet
+ * budget is enforced where it belongs: size `max_connections` for the replica
+ * ceiling, or front Postgres with a pooler (RDS Proxy / PgBouncer) so N
+ * replicas multiplex onto a bounded set of backend connections. This guard
+ * logs the supported-replica headroom as guidance for that sizing.
+ *
+ * Runs after `launchDbos` and before the HTTP listener accepts traffic so a
+ * misconfigured pod fails boot loudly instead of degrading under load.
+ */
+import type { Pool } from "pg";
+import type pino from "pino";
+/**
+ * Narrow config slice the budget guard reads — only the optional app-pool
+ * size override. Composition roots map `Env.DB_POOL_MAX` onto this.
+ */
+export interface ConnectionBudgetConfig {
+    readonly poolMax?: string;
+}
+export interface AssertConnectionBudgetOptions {
+    pool: Pool;
+    logger: pino.Logger;
+    config: ConnectionBudgetConfig;
+}
+/**
+ * Verify a single pod's pool footprint fits inside pg `max_connections`.
+ * Throws on shortfall — the caller must abort boot. Returns the per-pod
+ * footprint and the replica headroom it implies so callers can log it.
+ */
+export declare function assertConnectionBudget({ pool, logger, config }: AssertConnectionBudgetOptions): Promise<{
+    maxConnections: number;
+    appPoolSize: number;
+    dbosPoolSize: number;
+    podFootprint: number;
+    supportedReplicas: number;
+}>;

package/dist/runtime/connection-budget.js

@@ -0,0 +1,57 @@
+/**
+ * Boot-time Postgres connection-budget guard.
+ *
+ * Cortex runs two pools per pod against the same Postgres cluster (see the postgres-storage-backend spec):
+ * the application pool (`lib/storage.ts::createPool()`, sized via the optional
+ * `DB_POOL_MAX`) and the DBOS system-DB pool (`runtime/dbos.ts`, sized via
+ * `DBOS_SYSTEM_POOL_SIZE`). This guard asserts a single pod's footprint fits
+ * inside `max_connections` — it catches gross misconfiguration (a pool larger
+ * than the cluster can serve) without the pod needing to know the fleet size.
+ *
+ * Fleet-level capacity is intentionally NOT asserted here. A pod cannot learn
+ * the live replica count at boot (the Deployment's `spec.replicas` is not
+ * exposed via the downward API, and under an HPA it varies), so a fleet-wide
+ * assertion would either give false confidence or fail spuriously. The fleet
+ * budget is enforced where it belongs: size `max_connections` for the replica
+ * ceiling, or front Postgres with a pooler (RDS Proxy / PgBouncer) so N
+ * replicas multiplex onto a bounded set of backend connections. This guard
+ * logs the supported-replica headroom as guidance for that sizing.
+ *
+ * Runs after `launchDbos` and before the HTTP listener accepts traffic so a
+ * misconfigured pod fails boot loudly instead of degrading under load.
+ */
+import { DBOS_SYSTEM_POOL_SIZE, resolveAppPoolSize, SAFETY_MARGIN } from "./pools.js";
+/**
+ * Verify a single pod's pool footprint fits inside pg `max_connections`.
+ * Throws on shortfall — the caller must abort boot. Returns the per-pod
+ * footprint and the replica headroom it implies so callers can log it.
+ */
+export async function assertConnectionBudget({ pool, logger, config }) {
+    const appPoolSize = resolveAppPoolSize(config.poolMax);
+    const dbosPoolSize = DBOS_SYSTEM_POOL_SIZE;
+    const podFootprint = appPoolSize + dbosPoolSize;
+    const { rows } = await pool.query("SELECT current_setting('max_connections') AS max");
+    const maxConnections = parseInt(rows[0].max, 10);
+    if (podFootprint + SAFETY_MARGIN > maxConnections) {
+        throw new Error(`FATAL: pg max_connections (${maxConnections}) cannot hold one pod's pool footprint ` +
+            `(${podFootprint}) = app=${appPoolSize} + dbos=${dbosPoolSize}, plus margin=${SAFETY_MARGIN}. ` +
+            `Lower DB_POOL_MAX or raise max_connections.`);
+    }
+    const supportedReplicas = Math.floor((maxConnections - SAFETY_MARGIN) / podFootprint);
+    logger.info({
+        maxConnections,
+        appPoolSize,
+        dbosPoolSize,
+        podFootprint,
+        safetyMargin: SAFETY_MARGIN,
+        supportedReplicas,
+    }, `[boot] postgres connection budget OK — this cluster's max_connections ` +
+        `supports ~${supportedReplicas} cortex replicas; size replicas/pooler accordingly`);
+    return {
+        maxConnections,
+        appPoolSize,
+        dbosPoolSize,
+        podFootprint,
+        supportedReplicas,
+    };
+}

package/dist/runtime/dbos.d.ts

@@ -0,0 +1,94 @@
+/**
+ * DBOS Transact bootstrap.
+ *
+ * This is the only module that imports `@dbos-inc/dbos-sdk` directly. The
+ * agent loop and routes depend on the `RunStep` shape (`harness/loop/types.ts`),
+ * so DBOS stays swappable and the chat path never reaches into the workflow
+ * runtime. `harness/loop/run-step.ts` wraps `DBOS.runStep` for the durable
+ * variant; nothing else here.
+ *
+ * Launch is dormant — this change registers no workflows. The durability seam
+ * exists; the engine is running; nothing is durable yet.
+ *
+ * See `openspec/changes/harness-dbos-runtime`.
+ */
+import type pino from "pino";
+import type { Pool } from "pg";
+/**
+ * Narrow config slice the DBOS bootstrap reads. Composition roots map their
+ * validated `Env` onto this and pass the executor id in (the harness reads no env).
+ */
+export interface DbosConfig {
+    readonly dbHost: string;
+    readonly dbPort: string;
+    readonly dbName: string;
+    readonly dbUser: string;
+    readonly dbPassword: string;
+    readonly dbSslMode: "disable" | "require" | "verify-ca" | "verify-full";
+    readonly appName: string;
+    readonly applicationVersion?: string;
+    readonly adminPort: string;
+    /** Stable per-pod executor id (e.g. `process.env.HOSTNAME ?? "local-dev"`). */
+    readonly executorId: string;
+    /**
+     * SDK log verbosity (winston levels; the SDK's own default is `info`).
+     * Interactive embedders pass `warn` so the launch banner and migration
+     * chatter don't interleave with their own command output; the server root
+     * omits it and keeps the informative default.
+     */
+    readonly logLevel?: string;
+}
+interface State {
+    launched: boolean;
+    recoveryStarted: boolean;
+}
+/**
+ * Launch DBOS. Idempotent — a second call is a no-op so tests that drive
+ * the harness twice (or accidentally double-import) don't re-launch.
+ *
+ * Order is load-bearing: `setConfig` must precede `launch`, and `launch`
+ * must resolve before the HTTP listener accepts traffic (otherwise the
+ * readiness probe could 200 against a runtime that can't own workflows).
+ */
+export declare function launchDbos({ config, logger }: {
+    config: DbosConfig;
+    logger: pino.Logger;
+}): Promise<void>;
+/**
+ * Shut DBOS down. In-flight workflows are marked recoverable so another
+ * replica (or this pod on restart) can adopt them. Never throws — the
+ * outer shutdown sequence must close the pg.Pool and flush exporters even
+ * if DBOS shutdown fails.
+ *
+ * Must run after HTTP has drained (so no inbound request is orphaned) and
+ * before the application pool closes (DBOS needs the system DB).
+ */
+export declare function shutdownDbos({ logger }: {
+    logger: pino.Logger;
+}): Promise<void>;
+/**
+ * Cancel any `ephemeral:`-prefixed PENDING workflow this executor owns —
+ * called BEFORE `launchDbos`, whose recovery would otherwise re-dispatch them.
+ *
+ * Ephemeral runs are turn-scoped: a run whose pod died mid-flight has no live
+ * awaiter and must never re-execute. DBOS has no "zero recovery" knob, and
+ * `launch()` starts recovery itself, so there is no post-launch window to
+ * cancel from — the only race-free point is a direct system-DB UPDATE before
+ * launch. A CANCELLED row is excluded from the recovery query (which selects
+ * `status='PENDING'`). The `dbos.workflow_status` coupling is the price of
+ * pre-launch timing, and this is the sole module that owns DBOS. The system
+ * DB is the same database as the app pool, so the pool reaches it directly.
+ */
+export declare function sweepEphemeralWorkflows({ pool, logger, executorId, }: {
+    pool: Pool;
+    logger: pino.Logger;
+    /** Stable per-pod executor id — must match `launchDbos`'s `executorId`. */
+    executorId: string;
+}): Promise<void>;
+/** Snapshot of DBOS lifecycle state — read by the readiness probe. */
+export declare function dbosState(): State;
+/** Test hook: force-reset state without calling DBOS. Test-only. */
+export declare function __resetDbosStateForTest(): void;
+/** Test hook: mark launched without calling DBOS. Test-only. */
+export declare function __setDbosStateForTest(next: Partial<State>): void;
+export {};