@stackbone/sdk 0.1.0-alpha.2 → 0.1.0-alpha.4

package/index.d.cts

@@ -1,14 +1,21 @@
-import { ContractResponse } from '@stackbone/validators';
+import { PublishJobResponse, ScheduleJobResponse, UnscheduleJobResponse, ListSchedulesResponse, ContractResponse } from '@stackbone/validators';
+import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+import { Sql } from 'postgres';
+import { IngestJobWriter, IngestRequest, IngestResponse, RagIngestProgress, DeleteOptions, DeleteResponse, RetrieveRequest, RetrieveHit, ChunkOptions, ParseInput, ParseOptions } from '@stackbone/rag-core';
+export { ChunkOptions, ChunkStrategy, DeleteOptions, DeleteResponse, IngestChunk, IngestRequest, IngestRequestAutoEmbed, IngestRequestPrecomputed, IngestResponse, ParseInput, ParseOptions, RagIngestProgress, RetrieveHit, RetrieveRequest, RetrieveRequestAutoEmbed, RetrieveRequestPrecomputed } from '@stackbone/rag-core';
 import OpenAI from 'openai';
 import { ChatCompletionCreateParamsStreaming, ChatCompletionChunk, ChatCompletionCreateParamsNonStreaming, ChatCompletion, EmbeddingCreateParams, CreateEmbeddingResponse, ChatCompletionMessageParam } from 'openai/resources';
 import { Stream } from 'openai/streaming';
-import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
-import { Sql } from 'postgres';
 import { S3Client } from '@aws-sdk/client-s3';
+import { z } from 'zod';
+export { z } from 'zod';
+import { SecretCipher } from '@stackbone/crypto';
 
 /**
  * Optional overrides accepted by `createClient`. All fields are optional;
- * modules fall back to the corresponding upstream env var on first access.
+ * the resolver applies the precedence rule (`config.xxx` first, env var
+ * fallback) and produces a fully typed `ResolvedConfig` so downstream
+ * modules never have to know the env-var names or the order of precedence.
  */
 interface ClientConfig {
     /** Ed25519 JWT signed by the control plane. Falls back to `STACKBONE_AGENT_JWT`. */
@@ -24,11 +31,17 @@ interface ClientConfig {
      * every SDK consumer that talks to the agent's Postgres.
      */
     databaseUrl?: string;
+    /**
+     * Per-agent encryption key (base64, 32 bytes) used to decrypt the agent's
+     * own application secrets read directly from `stackbone_platform.secrets`.
+     * Falls back to `STACKBONE_SECRET_KEY` — the per-agent key the saga/harness
+     * inject into the runtime env. This is the ONLY new env channel the
+     * agent-owned-secrets split adds; the deliberate no-generic-env-channel
+     * stance is preserved.
+     */
+    secretKey?: string;
     openrouterKey?: string;
     openrouterBaseUrl?: string;
-    qstashToken?: string;
-    qstashCurrentSigningKey?: string;
-    qstashNextSigningKey?: string;
     llamaParseApiKey?: string;
     /** mem0 API key for the long-term memory backend (`client.memory`). Falls back to `MEM0_API_KEY`. */
     mem0ApiKey?: string;
@@ -86,22 +99,277 @@ interface ClientConfig {
     protocolRequired?: number;
 }
 /**
- * `env` is a live reference to `process.env` (not a snapshot) so tests that
- * mutate the environment between `createClient()` and the first module access
- * still observe the new values via the lazy initialisers.
+ * Fully-resolved, typed snapshot the SDK consumes. The resolver is the **only**
+ * place in the library that touches `process.env`; every downstream module
+ * reads from typed fields here instead of consulting the environment itself.
+ *
+ * Precedence rule: `config.xxx` (passed to `createClient`) wins over
+ * `process.env['XXX']`. Required env vars surface as `string | undefined` —
+ * the resolver never throws when a var is missing; whether a missing value
+ * is fatal is a per-surface decision (some error at construction, others
+ * lazily on first use).
+ *
+ * Construction is a snapshot. Tests that mutated `process.env` between
+ * `createClient()` and the first module access used to observe the new value
+ * through the old `env` channel; they now pass overrides via `createClient`
+ * or rebuild a new `ResolvedConfig` after mutating `process.env`. Snapshot
+ * semantics make the SDK easier to reason about — one read, one source.
+ *
+ * Note: there is intentionally no `env` channel. Reading
+ * `resolved.env['SOMETHING']` is a type error. Adding a new env-driven
+ * setting means adding a typed field here and resolving it in
+ * `resolveConfig`.
  */
 interface ResolvedConfig {
-    config: Readonly<ClientConfig>;
-    env: NodeJS.ProcessEnv;
+    /** The frozen creator-supplied options (untouched, for debug introspection). */
+    readonly config: Readonly<ClientConfig>;
+    /** Resolved from `config.stackboneApiUrl` ?? `STACKBONE_API_URL`. */
+    readonly stackboneApiUrl: string | undefined;
+    /** Resolved from `config.agentJwt` ?? `STACKBONE_AGENT_JWT`. */
+    readonly agentJwt: string | undefined;
+    /** Resolved from `config.installationId` ?? `STACKBONE_INSTALLATION_ID`. */
+    readonly installationId: string | undefined;
+    /** Resolved from `config.approvalSigningKey` ?? `STACKBONE_APPROVAL_SIGNING_KEY`. */
+    readonly approvalSigningKey: string | undefined;
+    /** Resolved from `config.agentId` ?? `STACKBONE_AGENT_ID`. */
+    readonly agentId: string | undefined;
+    /** Resolved from `config.databaseUrl` ?? `STACKBONE_POSTGRES_URL`. Shared by `client.database`, `client.rag`, and the platform observability hooks in `@stackbone/sdk/observability`. */
+    readonly databaseUrl: string | undefined;
+    /**
+     * Resolved from `config.secretKey` ?? `STACKBONE_SECRET_KEY`. The per-agent
+     * base64 encryption key `client.secrets` uses to decrypt rows read straight
+     * out of `stackbone_platform.secrets`.
+     */
+    readonly secretKey: string | undefined;
+    /** Resolved from `config.openrouterKey` ?? `OPENROUTER_API_KEY`. */
+    readonly openrouterKey: string | undefined;
+    /** Resolved from `config.openrouterBaseUrl` ?? `OPENROUTER_BASE_URL`. `undefined` means use the OpenRouter default. */
+    readonly openrouterBaseUrl: string | undefined;
+    /** Resolved from `config.s3.accessKeyId` ?? `STACKBONE_S3_ACCESS_KEY`. */
+    readonly s3AccessKeyId: string | undefined;
+    /** Resolved from `config.s3.secretAccessKey` ?? `STACKBONE_S3_SECRET_KEY`. */
+    readonly s3SecretAccessKey: string | undefined;
+    /** Resolved from `config.s3.endpoint` ?? `STACKBONE_S3_ENDPOINT`. */
+    readonly s3Endpoint: string | undefined;
+    /** Resolved from `config.s3.bucket` ?? `STACKBONE_S3_BUCKET`. */
+    readonly s3Bucket: string | undefined;
+    /** Resolved from `config.s3.region` ?? `STACKBONE_S3_REGION` ?? `'auto'`. Always defined. */
+    readonly s3Region: string;
+    /** Resolved from `config.otel.exporterOtlpEndpoint` ?? `OTEL_EXPORTER_OTLP_ENDPOINT`. */
+    readonly otelExporterOtlpEndpoint: string | undefined;
+    /**
+     * `true` unless `STACKBONE_REQUIRE_CONTRACT=0` is set. Consulted by the
+     * contract gate to decide whether a `capability_unavailable` /
+     * `contract_version_unsupported` error becomes a hard failure or a logged
+     * warning (escape-hatch path).
+     */
+    readonly requireContract: boolean;
+    /**
+     * Parsed `STACKBONE_CONTRACT_TTL_MS`. `undefined` (default) means cached
+     * handshakes never expire within the process lifetime; a positive integer
+     * caps the cache entry's `expiresAt`.
+     */
+    readonly contractTtlMs: number | undefined;
+    /**
+     * `true` only when `STACKBONE_DEBUG=1` is set. Consulted by the handshake
+     * to emit a one-shot debug line per (store, baseUrl) tuple after a
+     * successful negotiation.
+     */
+    readonly debug: boolean;
+    /**
+     * Embedding model parsed by the CLI from `agent.yaml.rag.embeddingModel`
+     * and forwarded as `config.rag.embeddingModel`. Same value, surfaced
+     * directly so consumers don't reach through the nested object.
+     */
+    readonly ragEmbeddingModel: string | undefined;
+    /**
+     * Forwarded from `config.protocolRequired`. The CLI sources it from
+     * `agent.yaml.protocol.required`; there is no env-var fallback today.
+     */
+    readonly protocolRequired: number | undefined;
 }
 
+/**
+ * The single source of truth for every `code` an `SdkError` may carry on the
+ * `Result` envelope returned from a public SDK method. The README contract
+ * (and every creator who pattern-matches on `result.error.code`) is driven by
+ * this catalog — adding a new code means editing this file, and **only** this
+ * file. The compiler then refuses to ship any `SdkError({ code: '<unknown>' })`
+ * downstream.
+ *
+ * Shape:
+ *   - `SDK_ERROR_CODE_PREFIXES` declares each prefix family and the suffixes
+ *     it owns. `<prefix>` + `_<reason>` is the wire-level code.
+ *   - `SDK_ERROR_CODES_STANDALONE` declares the freestanding codes that don't
+ *     follow the `<prefix>_<reason>` rule (`not_implemented`, the various
+ *     `*_missing` setup-bug codes, the `capability_*` / `contract_*` shapes).
+ *   - `SdkErrorCode` is the union projected from both. Pass it to `err({...})`
+ *     and the constructor rejects any literal that isn't in this catalog.
+ *
+ * Stability contract: the wire-level shape of every code in this catalog is
+ * part of the README's public error table. Codes are added behind a minor;
+ * codes are removed behind a major and the CHANGELOG. Spelling tweaks (even
+ * typos) wait for a major — fix the catalog and the call site together.
+ */
+/**
+ * Prefix families. Each entry maps a `<prefix>` to the tuple of `<reason>`
+ * suffixes the SDK can emit under it. Two-step structure (object of tuples)
+ * is what powers the typed projection at the bottom of this file: the
+ * `as const` makes both the prefix names and the suffix strings into literal
+ * types so `SdkErrorCode` collapses to a finite string union.
+ */
+declare const SDK_ERROR_CODE_PREFIXES: {
+    /**
+     * `client.ai` — wraps the OpenAI SDK pointed at OpenRouter. Status codes
+     * come from `codeForStatus` in `ai.ts` plus the fetch-error mapper.
+     */
+    readonly ai: readonly ["aborted", "credits_exhausted", "forbidden", "moderation_blocked", "network_error", "no_image_generated", "provider_error", "rate_limited", "timeout", "unauthorized", "validation_error"];
+    /**
+     * `client.storage` — wraps `@aws-sdk/client-s3` against R2/MinIO. Most
+     * failures collapse into `s3_error` with the AWS metadata on `meta`; the
+     * specific codes below are the early validation paths.
+     */
+    readonly s3: readonly ["bucket_missing", "credentials_missing", "empty_response", "error", "invalid_argument", "invalid_key"];
+    /**
+     * `client.rag` — the agent-local retrieval pipeline. `invalid_request` is
+     * the validation rail; the rest map specific Postgres / embedder failures
+     * the README documents.
+     */
+    readonly rag: readonly ["dim_mismatch", "embedding_failed", "embedding_model_unsupported", "error", "ingest_cancelled", "invalid_request", "job_insert_failed", "jobs_error", "schema_missing"];
+    /**
+     * `client.approval` — AGENT-LOCAL DB facade plus the HMAC verify helper.
+     * The request/cancel/get/list codes (`persist_failed`, `cancel_failed`,
+     * `unavailable`) come from the direct write/read against
+     * `stackbone_platform.approvals`; the verify-specific codes
+     * (`invalid_signature`, etc.) are emitted locally.
+     */
+    readonly approval: readonly ["cancel_failed", "forbidden", "invalid_payload", "invalid_request", "invalid_response", "invalid_signature", "not_found", "persist_failed", "rate_limited", "signature_expired", "signing_key_missing", "timeout", "tool_execute_failed", "unauthorized", "unavailable"];
+    /**
+     * `client.secrets` — AGENT-LOCAL facade. Reads `stackbone_platform.secrets`
+     * over the shared `client.database` pool and decrypts with the per-agent
+     * key. `not_configured` covers a missing `STACKBONE_SECRET_KEY`;
+     * `decrypt_failed` covers a key/envelope mismatch; `unavailable` covers a
+     * failed DB read.
+     */
+    readonly secrets: readonly ["already_exists", "decrypt_failed", "forbidden", "invalid_request", "invalid_response", "not_configured", "not_found", "rate_limited", "timeout", "unauthorized", "unavailable"];
+    /**
+     * `client.config` — AGENT-LOCAL facade, reads the singleton
+     * `stackbone_platform.agent_config` row over the shared `client.database`
+     * pool.
+     */
+    readonly config: readonly ["forbidden", "invalid_request", "invalid_response", "not_found", "rate_limited", "timeout", "unauthorized", "unavailable"];
+    /**
+     * `client.queues` — the agent → control plane job-enqueue surface. Every
+     * method (`publish`, `schedule`, `unschedule`, `listSchedules`) POSTs/GETs
+     * the BullMQ dispatcher endpoints over `HttpClient`, so the full
+     * status→domain remap (`queues_unauthorized`, `queues_not_found`,
+     * `queues_unavailable`, …) is in play. The agent never touches Redis — it
+     * only calls these endpoints.
+     */
+    readonly queues: readonly ["forbidden", "invalid_request", "invalid_response", "not_found", "rate_limited", "timeout", "unauthorized", "unavailable"];
+    /**
+     * `client.prompts` — AGENT-LOCAL facade. Reads
+     * `stackbone_platform.prompts` / `prompt_versions` over the shared
+     * `client.database` pool and compiles templates with the local
+     * `@stackbone/prompt-compiler` (Mustache subset). `not_configured` covers a
+     * missing prompts schema (the `42P01` "run `stackbone db migrate up`" hint);
+     * `not_found` covers an absent / soft-deleted key; `missing_var` is the
+     * compile-time diagnostic when a `{{var}}` has no value; `unavailable`
+     * covers a failed DB read; `already_exists` covers a duplicate `create`.
+     */
+    readonly prompts: readonly ["already_exists", "invalid_request", "missing_var", "not_configured", "not_found", "unavailable"];
+    /**
+     * `client.memory` — reserved. The README documents the prefix; today the
+     * pending surface returns `not_implemented` for every method so no
+     * `memory_*` codes are emitted yet. Kept as an empty bucket so the
+     * catalog matches the README table verbatim.
+     */
+    readonly memory: readonly string[];
+    /**
+     * Transport-level error family — `HttpClient` emits these when no
+     * facade-specific `errorMapping.prefix` is configured, or when the
+     * failure is pre-/post-HTTP (DNS, abort, body parse).
+     */
+    readonly http: readonly ["aborted", "client_error", "forbidden", "invalid_request", "invalid_response", "network_error", "not_found", "parse_error", "rate_limited", "request_failed", "server_error", "timeout", "unauthorized"];
+    /**
+     * `client.database` (and its cross-surface consumers) — the setup-bug
+     * surface stays under one prefix so creators can pattern-match on
+     * `database_*` regardless of whether the failure came from the database
+     * module, RAG, or the observability run-cost hook.
+     */
+    readonly database: readonly ["not_configured"];
+    /**
+     * Observability — the run-cost rollup hook in `@stackbone/sdk/observability`
+     * (wired by the runtime, not a creator surface) emits this when its post-run
+     * Postgres write fails; everything else either returns ok or surfaces through
+     * the `database_*` family above.
+     */
+    readonly observability: readonly ["close_run_failed"];
+    /**
+     * Contract handshake / gating family — emitted by the per-client
+     * `ContractStore` and consumed by every gated facade as a hard error.
+     * Documented for creators in the gating section of the SDK ADRs.
+     */
+    readonly contract: readonly ["malformed", "unreachable", "version_unsupported"];
+    /**
+     * Capability gating family — the single code is the table-driven block
+     * the gate returns when the negotiated contract lacks the required
+     * capability. The shape lives in `@stackbone/validators`; the SDK widens
+     * it into `SdkError` verbatim.
+     */
+    readonly capability: readonly ["unavailable"];
+};
+/**
+ * Freestanding codes — they don't follow the `<prefix>_<reason>` rule, so
+ * they live as full literals here. Two families:
+ *
+ *   - `not_implemented` for the pending surfaces' stubbed methods.
+ *   - `*_missing` for the setup-bug rail every facade checks before its
+ *     first network call (`STACKBONE_API_URL`, `STACKBONE_AGENT_ID`,
+ *     `OPENROUTER_API_KEY`, `STACKBONE_POSTGRES_URL`).
+ */
+declare const SDK_ERROR_CODES_STANDALONE: readonly ["agent_id_missing", "database_url_missing", "not_implemented", "openrouter_key_missing", "stackbone_api_url_missing"];
+/**
+ * Type-level projection: `<prefix>_<reason>` for every entry of
+ * `SDK_ERROR_CODE_PREFIXES`, plus the standalone codes. The trick is the
+ * second mapped-tuple step: `(typeof SDK_ERROR_CODE_PREFIXES)[P][number]`
+ * collapses the tuple to the union of its suffixes, then template-string
+ * inference builds the full code.
+ */
+type Prefix = keyof typeof SDK_ERROR_CODE_PREFIXES;
+type PrefixedCode<P extends Prefix = Prefix> = {
+    [K in P]: `${K}_${(typeof SDK_ERROR_CODE_PREFIXES)[K][number]}`;
+}[P];
+type SdkErrorCode = PrefixedCode | (typeof SDK_ERROR_CODES_STANDALONE)[number];
+/**
+ * Type guard for callers that receive a raw string from the wire (e.g. a
+ * decoded JSON body) and want to narrow it to the catalog. Returns false
+ * for any unknown code so the caller can decide whether to re-throw,
+ * fall back, or surface the raw string.
+ */
+declare function isSdkErrorCode(code: string): code is SdkErrorCode;
+/**
+ * Prefix names exposed as a tuple for the `errorMapping.prefix` slot on
+ * `HttpClient.request`. Statically tying the transport's prefix to the
+ * catalog keeps `<prefix>_<reason>` emissions inside `SdkErrorCode` —
+ * adding a new prefix means adding it here AND a `<prefix>_invalid_request`
+ * / `<prefix>_invalid_response` / standard status-mapped suffix to the
+ * catalog above.
+ */
+type SdkErrorPrefix = Prefix;
+
 /**
  * Uniform error envelope returned by every SDK method. `cause` and `meta` are
  * optional escape hatches so wrappers can attach upstream errors / context
  * without breaking the public shape.
+ *
+ * `code` is typed against the catalog declared in `errors/codes.ts` — the
+ * compiler refuses any literal that isn't part of the documented inventory.
+ * Adding a new code is a single-file edit there; ALL throw sites then update
+ * automatically through the union.
  */
 interface SdkError {
-    code: string;
+    code: SdkErrorCode;
     message: string;
     cause?: unknown;
     meta?: Record<string, unknown>;
@@ -126,55 +394,117 @@ type Result<T> = {
  * `Result<T>` of the method.
  *
  * Test seam — every gated module exposes an optional `gate` constructor
- * argument that defaults to `createModuleGate(<id>, resolved)`. Specs inject
- * a stub returning a synthetic `Result<undefined>` to exercise the gating
- * paths (ok / `contract_version_unsupported` / `capability_unavailable` /
- * `contract_unreachable`) without driving a real handshake.
+ * argument that defaults to `createModuleGate(<id>, resolved, store)`. Specs
+ * inject a stub returning a synthetic `Result<undefined>` to exercise the
+ * gating paths (ok / `contract_version_unsupported` / `capability_unavailable`
+ * / `contract_unreachable`) without driving a real handshake.
  */
 type ModuleGate = () => Promise<Result<undefined>>;
 
-/** Subset of `RequestInit['body']` we serialize without modification. */
-type SerializedBody = NonNullable<RequestInit['body']>;
-interface RequestOptions$1 extends Omit<RequestInit, 'body' | 'signal'> {
-    params?: Record<string, string>;
-    body?: SerializedBody | Record<string, unknown> | unknown[] | null;
-    signal?: AbortSignal;
-    /** Allow retrying non-idempotent requests (POST, PATCH). Off by default to prevent duplicate writes. */
-    idempotent?: boolean;
-}
-interface HttpClientOptions {
-    /** Default 30_000. Set to 0 to disable. */
-    timeout?: number;
-    /** Default 3. Set to 0 to disable. */
-    retryCount?: number;
-    /** Initial backoff in ms; doubles each attempt with ±15% jitter. Default 500. */
-    retryDelay?: number;
-    /** Override the global fetch (useful for tests). */
-    fetch?: typeof fetch;
-}
 /**
- * Shared HTTP client used by the control-plane facades (approval, secrets,
- * connections, config, events). Wraps `fetch` with timeout, exponential
- * backoff with jitter, idempotent-only retries, and a uniform Result
- * envelope so facades never throw at the SDK boundary.
+ * Public surface a creator can use through `client.database`. We pin it to the
+ * `postgres-js` Drizzle wrapper because that is the only driver `@stackbone/sdk`
+ * ships and the only one `STACKBONE_POSTGRES_URL` is contracted to point at.
  *
- * Reads `STACKBONE_API_URL` and `STACKBONE_AGENT_JWT` lazily on every request so
- * env-var rotation is picked up without restarting the client.
+ * Re-exporting Drizzle's own type instead of inventing a structural alias keeps
+ * the surface 1:1 with what `drizzle-orm` documents and what `@stackbone/sdk/db`
+ * re-exports — so types flow end to end without translation.
  */
-declare class HttpClient {
-    private readonly resolved;
-    private readonly timeout;
-    private readonly retryCount;
-    private readonly retryDelay;
-    private readonly fetchImpl;
-    constructor(resolved: ResolvedConfig, options?: HttpClientOptions);
-    get<T>(path: string, options?: RequestOptions$1): Promise<Result<T>>;
-    post<T>(path: string, body?: RequestOptions$1['body'], options?: RequestOptions$1): Promise<Result<T>>;
-    put<T>(path: string, body?: RequestOptions$1['body'], options?: RequestOptions$1): Promise<Result<T>>;
-    patch<T>(path: string, body?: RequestOptions$1['body'], options?: RequestOptions$1): Promise<Result<T>>;
-    delete<T>(path: string, options?: RequestOptions$1): Promise<Result<T>>;
-    request<T>(method: string, path: string, options?: RequestOptions$1): Promise<Result<T>>;
-    private computeBackoff;
+type DrizzleClient = PostgresJsDatabase<Record<string, never>> & {
+    $client: Sql;
+};
+
+/**
+ * `client.database` is a lazy wrapper over a `drizzle()` instance bound to
+ * the resolved `databaseUrl` (config first, then `STACKBONE_POSTGRES_URL`
+ * at `resolveConfig` time). The underlying postgres-js connection and the
+ * Drizzle facade are constructed on the first method call so partner SDKs
+ * only pay the cost when the agent actually touches the database.
+ *
+ * Native Drizzle methods (`select`, `insert`, `update`, `delete`, `transaction`,
+ * `execute`) are exposed verbatim — we explicitly avoid wrapping them in a
+ * Result envelope here. Drizzle already throws on misuse and returns typed rows
+ * on success; mirroring its API keeps the contract identical to what the
+ * `@stackbone/sdk/db` re-exports document, so creators write idiomatic Drizzle.
+ *
+ * Missing `STACKBONE_POSTGRES_URL` raises `SdkError('database_not_configured')`
+ * with an actionable hint that points to `stackbone dev`. This is a creator
+ * setup bug, not something the agent's code can recover from at runtime.
+ *
+ * Methods are declared with their full Drizzle generic signatures (rather than
+ * `(...args) => Drizzle[k](...args)` arrow properties) so the inferred row
+ * types from `pgTable(...)` flow end-to-end into the caller, which is the
+ * promise the `@stackbone/sdk/db` re-export makes.
+ *
+ * The actual `postgres()` pool and the Drizzle handle are owned by the
+ * module-internal singleton in `./shared-handle.ts`. The shared handle is
+ * exposed to other SDK surfaces (RAG today, memory / queues tomorrow)
+ * through the `shared()` method below — the **canonical accessor** of
+ * the SDK's shared-handles pattern. Same instance every call → one pool
+ * per agent process. See `shared-handle.spec.ts` for the invariant.
+ */
+declare class DatabaseModule {
+    private readonly _gate;
+    private readonly _databaseUrl;
+    constructor(resolved: ResolvedConfig, 
+    /**
+     * Test seam — see `ModuleGate`. Defaults to the lazy contract gate.
+     * The gate is awaited at the terminal `await` of every Drizzle chain
+     * (`select/insert/update/delete/execute/transaction`); when it returns
+     * an error, a tagged `GateBlockedError` is thrown so callers see the
+     * same `Error & { code, message, meta }` surface as the existing
+     * `database_not_configured` setup-bug.
+     */
+    gate?: ModuleGate);
+    /**
+     * Escape hatch — returns Drizzle's relational query builder verbatim. The
+     * contract gate does NOT fire here because the surface is a synchronous
+     * accessor; the user can still bypass the gate via `client.database.raw()`
+     * for the same reason. Audit: `query` and `raw()` are intentionally
+     * ungated escape hatches; the standard `select/insert/update/delete/
+     * execute/transaction` path is fully gated.
+     */
+    get query(): DrizzleClient['query'];
+    select: DrizzleClient['select'];
+    insert: DrizzleClient['insert'];
+    update: DrizzleClient['update'];
+    delete: DrizzleClient['delete'];
+    execute: DrizzleClient['execute'];
+    transaction: DrizzleClient['transaction'];
+    /**
+     * Canonical accessor for the **shared-handles pattern**. Returns the
+     * process-wide Drizzle handle backing `client.database`. Cross-surface
+     * SDK consumers (RAG today, memory / queues tomorrow) call this — never
+     * the implementation-detail singleton in `./shared-handle.ts` — to
+     * ensure they share the one `postgres()` pool the agent process owns
+     * against `STACKBONE_POSTGRES_URL`.
+     *
+     * Contract: same input → same instance. Calling `shared()` twice in the
+     * same process returns the same reference; the underlying postgres-js
+     * `Sql` is reachable as `shared().$client` for callers (e.g. RAG) that
+     * need the template-tag function instead of the Drizzle facade.
+     *
+     * Like `raw()`, this is a synchronous accessor and intentionally does
+     * NOT consult the contract gate — surfaces that gate behaviour gate it
+     * at their own call sites (`pipeline.ingest`, etc.), not at handle
+     * acquisition. Configuration errors (`database_not_configured`) throw
+     * with the same tagged `Error` shape every other `client.database`
+     * surface uses.
+     */
+    shared(): DrizzleClient;
+    /**
+     * Escape hatch for **creator** callers that want the raw Drizzle handle
+     * (e.g. to pass it to a library that expects `PostgresJsDatabase`).
+     * Functionally identical to `shared()` — both return the same singleton
+     * and trigger the same lazy initialisation — but kept under a distinct
+     * name because the audiences differ: `shared()` is consumed by other
+     * SDK surfaces and documents the cross-surface contract; `raw()` is
+     * documented as the creator's escape hatch out of the structured
+     * `select/insert/...` surface. Reading either intentionally does NOT
+     * consult the contract gate; the caller is opting out of the SDK's
+     * structured surface.
+     */
+    raw(): DrizzleClient;
 }
 
 interface ApprovalToolSpec<I, O> {
@@ -289,147 +619,151 @@ interface ApprovalListResult<T = unknown> {
     items: ApprovalRecord<T>[];
     nextCursor?: string;
 }
+/**
+ * `client.approval` — AGENT-LOCAL. The HITL pause is recorded directly in the
+ * agent's own `stackbone_platform.approvals` table over the shared
+ * `client.database` pool; there is no control-plane POST anymore. The RESUME
+ * half stays Studio-driven: a human decides in Studio, the control plane signs
+ * an HMAC callback to `callbackUrl`, and the agent reconciles it with
+ * `verify()` (local crypto — see `verify.ts`).
+ *
+ * The write populates only the columns the cloud `create()` used to set
+ * (topic/payload/callback_url/idempotency_key/fallback/metadata/timeout_at;
+ * `schema` was sourced from a DTO field the SDK options object does not carry,
+ * so it stays NULL). `workspace_id`/`agent_id`/`run_id` stay NULL exactly as
+ * they were on the control-plane path — the idempotency `ON CONFLICT` relies on
+ * `workspace_id` being NULL with `NULLS NOT DISTINCT` (migration 0008).
+ */
 declare class ApprovalFacade {
     private readonly _resolved;
-    private readonly _http;
-    private readonly _gate;
-    constructor(_resolved: ResolvedConfig, _http: HttpClient, 
-    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
-    gate?: ModuleGate);
+    /** Lazy accessor for `client.database` — reaches the shared `Sql` via `.shared().$client`. */
+    private readonly _getDatabase;
+    constructor(_resolved: ResolvedConfig, 
+    /** Lazy accessor for `client.database` — reaches the shared `Sql` via `.shared().$client`. */
+    _getDatabase: () => DatabaseModule);
     request<T = unknown>(options: ApprovalRequestOptions<T>): Promise<Result<ApprovalRequest>>;
     cancel(approvalId: string, reason?: string): Promise<Result<void>>;
     get<T = unknown>(approvalId: string): Promise<Result<ApprovalRecord<T>>>;
     list<T = unknown>(options?: ApprovalListOptions): Promise<Result<ApprovalListResult<T>>>;
     /**
-     * Local crypto verification — does not touch the datapath, so it is NOT
-     * gated by the contract handshake. Auditing rule: a method gates iff it
-     * issues an HTTP request to the configured baseUrl.
+     * Local crypto verification — does not touch the database, so it has the same
+     * shape it had on the control-plane surface. Auditing rule: a method gates
+     * iff it issues a datapath call; this one never does.
      */
     verify<T = unknown>(request: Request, options?: VerifyOptions): Promise<Result<Decision<T>>>;
     /**
-     * Pure factory — returns an `ApprovalTool` whose `invoke()` ultimately
-     * calls back into `ApprovalFacade.request`, so the gate fires there. Not
-     * gated here.
+     * Pure factory — returns an `ApprovalTool` whose `invoke()` ultimately calls
+     * back into `ApprovalFacade.request`.
      */
     tool<I, O>(spec: ApprovalToolSpec<I, O>): ApprovalTool<I, O>;
+    private sql;
 }
 
 declare class ConfigFacade {
-    private readonly _http;
-    private readonly _gate;
-    constructor(resolved: ResolvedConfig, _http: HttpClient, 
-    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
-    gate?: ModuleGate);
+    private readonly _resolved;
+    /** Lazy accessor for `client.database` — see `SecretsFacade`. */
+    private readonly _getDatabase;
+    constructor(_resolved: ResolvedConfig, 
+    /** Lazy accessor for `client.database` — see `SecretsFacade`. */
+    _getDatabase: () => DatabaseModule);
     get<T = unknown>(key: string): Promise<Result<T>>;
     /**
      * Keys absent from the agent's config come back as omissions in the
-     * response — the returned map only contains entries the control plane
-     * actually has, so callers must access fields with `?.` (the return type
-     * is `Partial<T>`).
+     * response — the returned map only contains entries the agent DB actually
+     * has, so callers must access fields with `?.` (the return type is
+     * `Partial<T>`).
      */
     getMany<T extends Record<string, unknown> = Record<string, unknown>>(keys: string[]): Promise<Result<Partial<T>>>;
-}
-
-/** OAuth connections (Notion, GDrive, Slack…). */
-declare class ConnectionsFacade {
-    private readonly _resolved;
-    private readonly _http;
-    constructor(_resolved: ResolvedConfig, _http: HttpClient);
-    list(): Promise<Result<readonly never[]>>;
-}
-
-/** Emit events to the organization event bus. */
-declare class EventsFacade {
-    private readonly _http;
-    private readonly _gate;
-    constructor(resolved: ResolvedConfig, _http: HttpClient, 
-    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
-    gate?: ModuleGate);
-    emit(_name: string, _payload: unknown): Promise<Result<void>>;
+    private loadPayload;
+    private sql;
 }
 
 /**
- * A prompt managed by the Stackbone control plane. Templates are plain strings
- * with Mustache-style `{{var}}` placeholders — no conditionals or loops.
+ * A prompt's current/active state. Key-based (workspace-unique). `template` is
+ * the current version's content; `version` is the live version number.
  */
 interface Prompt {
+    key: string;
     name: string;
+    description: string | null;
+    /** The current version's content. */
     template: string;
-    /** Monotonically increasing per `name`. The first `create` produces version `1`. */
+    /** The live version number. The first `create` produces version `1`. */
     version: number;
-    /** Variable names parsed from the template. */
-    variables?: readonly string[];
-    metadata?: Record<string, unknown>;
+    /** `{{var}}` names referenced by the current version. */
+    variables: readonly string[];
+    metadata: Record<string, unknown> | null;
     /** ISO 8601 UTC timestamp. */
     createdAt: string;
     updatedAt: string;
 }
 interface GetPromptOptions {
-    /** Pin a specific version. Omitted -> latest. */
+    /** Pin a specific version. Omitted -> current/latest. */
     version?: number;
 }
 interface ListPromptsOptions {
     /** 1..100. Default 50. */
     limit?: number;
-    cursor?: string;
 }
 interface ListPromptsResult {
-    /** Latest version of each prompt. */
+    /** Current version of each (non-deleted) prompt. */
     items: readonly Prompt[];
-    nextCursor?: string;
 }
 interface CreatePromptRequest {
+    key: string;
     name: string;
+    /** The version-1 content. */
     template: string;
+    description?: string;
     metadata?: Record<string, unknown>;
 }
 interface UpdatePromptOptions {
-    /** New template. Bumps `version` by one. */
+    /** New content. Appends a new immutable version. */
     template?: string;
-    /** Shallow-merged onto the existing metadata. */
+    name?: string;
+    description?: string | null;
+    /** Replaces the prompt-head metadata. */
     metadata?: Record<string, unknown>;
 }
 interface DeletePromptOptions {
-    /** Delete a specific version. Omitted -> delete every version under `name`. */
+    /** Reserved for future per-version deletes; ignored today (soft-deletes the key). */
     version?: number;
 }
 interface DeletePromptResult {
-    name: string;
-    /** Number of versions actually removed. */
+    key: string;
+    /** Number of prompt heads soft-deleted (0 or 1). */
     deleted: number;
 }
-/**
- * `client.prompts` — managed prompts for the agent. Prompts live outside the
- * code so creators can edit, version and A/B test them without rebuilding the
- * container. The first iteration is a scaffolding placeholder: every method
- * returns `not_implemented`. The real backend will be the Stackbone control
- * plane and the public surface defined here is the contract callers can
- * already type against.
- */
-declare class PromptsFacade {
-    private readonly _http;
-    constructor(_resolved: ResolvedConfig, _http: HttpClient);
-    get(_name: string, _options?: GetPromptOptions): Promise<Result<Prompt>>;
-    compile(_name: string, _variables: Record<string, unknown>, _options?: GetPromptOptions): Promise<Result<string>>;
-    list(_options?: ListPromptsOptions): Promise<Result<ListPromptsResult>>;
-    create(_request: CreatePromptRequest): Promise<Result<Prompt>>;
-    update(_name: string, _options: UpdatePromptOptions): Promise<Result<Prompt>>;
-    delete(_name: string, _options?: DeletePromptOptions): Promise<Result<DeletePromptResult>>;
+interface CompilePromptResult {
+    /** The rendered string. */
+    output: string;
+    /** The version the compile ran against. */
+    version: number;
 }
-
-declare class SecretsFacade {
-    private readonly _http;
-    private readonly _gate;
-    constructor(resolved: ResolvedConfig, _http: HttpClient, 
-    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
-    gate?: ModuleGate);
-    get(name: string): Promise<Result<string>>;
+declare class PromptsFacade {
+    private readonly _resolved;
     /**
-     * Names absent from the organization come back as omissions in the response —
-     * the returned map only contains entries the control plane actually has.
-     * Callers that need "all-or-nothing" semantics should diff the keys.
+     * Lazy accessor for `client.database`. The facade pulls the shared
+     * `postgres-js` `Sql` via `getDatabase().shared().$client` — never
+     * reaching into a sibling module's implementation file.
      */
-    getMany(names: string[]): Promise<Result<Record<string, string>>>;
+    private readonly _getDatabase;
+    constructor(_resolved: ResolvedConfig, 
+    /**
+     * Lazy accessor for `client.database`. The facade pulls the shared
+     * `postgres-js` `Sql` via `getDatabase().shared().$client` — never
+     * reaching into a sibling module's implementation file.
+     */
+    _getDatabase: () => DatabaseModule);
+    get(key: string, options?: GetPromptOptions): Promise<Result<Prompt>>;
+    compile(key: string, variables: Record<string, unknown>, options?: GetPromptOptions): Promise<Result<CompilePromptResult>>;
+    list(options?: ListPromptsOptions): Promise<Result<ListPromptsResult>>;
+    create(request: CreatePromptRequest): Promise<Result<Prompt>>;
+    update(key: string, options: UpdatePromptOptions): Promise<Result<Prompt>>;
+    delete(key: string, _options?: DeletePromptOptions): Promise<Result<DeletePromptResult>>;
+    private sql;
+    private mapReadError;
+    private mapWriteError;
 }
 
 /**
@@ -451,7 +785,14 @@ declare class SecretsFacade {
  *
  * Test override: pass `clientOverride` to inject a pre-built `OpenAI`
  * instance (or a stand-in) instead of letting the module build one. The
- * override flows to all four namespaces — `models.list()` included.
+ * override flows to all four namespaces — `models.list()` included —
+ * and to the cross-surface `shared()` accessor.
+ *
+ * Shared-handles pattern: `shared(): Result<OpenAI>` is the canonical
+ * accessor cross-surface SDK consumers (RAG today, memory tomorrow) use
+ * to reach the single OpenRouter client. Same instance every call; one
+ * credential, one base URL, one retry policy, one error shape. See
+ * README + CHANGELOG.
  */
 declare class AiModule {
     private readonly _resolved;
@@ -470,20 +811,40 @@ declare class AiModule {
     get embeddings(): EmbeddingsNamespace;
     get images(): ImagesNamespace;
     get models(): ModelsNamespace;
-    private client;
+    /**
+     * Canonical accessor for the **shared-handles pattern** on the AI
+     * surface. Returns the lazily-constructed OpenRouter-flavoured `OpenAI`
+     * client backing `client.ai`. Cross-surface SDK consumers (RAG today,
+     * memory tomorrow) call this — never instantiate a parallel `OpenAI`
+     * client — to keep credential resolution, base-URL routing, retry /
+     * timeout policy, and token accounting on a single instance.
+     *
+     * Contract: same input → same instance. Calling `shared()` twice in
+     * the same process (with the same `ResolvedConfig`) returns the same
+     * reference. The Result envelope surfaces `openrouter_key_missing`
+     * when `OPENROUTER_API_KEY` is unset, matching the rest of the
+     * `client.ai.*` API; the gate is intentionally NOT consulted here
+     * (surfaces that gate behaviour gate it at their own call sites).
+     *
+     * The constructor's `clientOverride` flows through this accessor too,
+     * so tests that inject a fake `OpenAI` see consistent behaviour across
+     * `chat / embeddings / images / models` and any cross-surface
+     * consumer.
+     */
+    shared(): Result<OpenAI>;
 }
 declare class ChatCompletionsNamespace {
     private readonly _getClient;
     private readonly _gate;
     constructor(_getClient: () => Result<OpenAI>, _gate: ModuleGate);
-    create(params: ChatCompletionCreateParamsStreaming, options?: RequestOptions): Promise<Result<Stream<ChatCompletionChunk>>>;
-    create(params: ChatCompletionCreateParamsNonStreaming, options?: RequestOptions): Promise<Result<ChatCompletion>>;
+    create(params: ChatCompletionCreateParamsStreaming, options?: RequestOptions$1): Promise<Result<Stream<ChatCompletionChunk>>>;
+    create(params: ChatCompletionCreateParamsNonStreaming, options?: RequestOptions$1): Promise<Result<ChatCompletion>>;
 }
 declare class EmbeddingsNamespace {
     private readonly _getClient;
     private readonly _gate;
     constructor(_getClient: () => Result<OpenAI>, _gate: ModuleGate);
-    create(params: EmbeddingCreateParams, options?: RequestOptions): Promise<Result<CreateEmbeddingResponse>>;
+    create(params: EmbeddingCreateParams, options?: RequestOptions$1): Promise<Result<CreateEmbeddingResponse>>;
 }
 interface ImageGenerateParams {
     model: string;
@@ -520,7 +881,7 @@ declare class ImagesNamespace {
      * empty success — surfacing the failure to the caller instead of
      * silently producing zero images.
      */
-    generate(params: ImageGenerateParams, options?: RequestOptions): Promise<Result<ImagesResponse>>;
+    generate(params: ImageGenerateParams, options?: RequestOptions$1): Promise<Result<ImagesResponse>>;
 }
 interface OpenRouterModel {
     id: string;
@@ -550,87 +911,273 @@ declare class ModelsNamespace {
      * the namespaces — and any `clientOverride` injected for tests applies
      * here too.
      */
-    list(options?: RequestOptions): Promise<Result<ModelsListResponse>>;
+    list(options?: RequestOptions$1): Promise<Result<ModelsListResponse>>;
 }
-interface RequestOptions {
+interface RequestOptions$1 {
     signal?: AbortSignal;
 }
 
 /**
- * Public surface a creator can use through `client.database`. We pin it to the
- * `postgres-js` Drizzle wrapper because that is the only driver `@stackbone/sdk`
- * ships and the only one `STACKBONE_POSTGRES_URL` is contracted to point at.
- *
- * Re-exporting Drizzle's own type instead of inventing a structural alias keeps
- * the surface 1:1 with what `drizzle-orm` documents and what `@stackbone/sdk/db`
- * re-exports — so types flow end to end without translation.
+ * Handle returned by `client.rag.ingestAsync`. The job id is allocated
+ * synchronously against `stackbone_rag_jobs` so the caller can track / cancel
+ * the work via the `/api/rag/jobs/:jobId/*` surface; `events` is a streaming
+ * channel of progress events (ADR §D9 shape); `result` settles when the
+ * pipeline finishes (or fails / is cancelled).
  */
-type DrizzleClient = PostgresJsDatabase<Record<string, never>> & {
-    $client: Sql;
-};
-
+interface IngestAsyncHandle {
+    jobId: string;
+    events: AsyncIterable<RagIngestProgress>;
+    result: Promise<Result<IngestResponse>>;
+}
 /**
- * `client.database` is a lazy wrapper over a `drizzle()` instance bound to
- * `STACKBONE_POSTGRES_URL`. The underlying postgres-js connection and the
- * Drizzle facade are constructed on the first method call so env vars rotated
- * post-`createClient()` are still honoured.
+ * `client.rag` — `pgvector`-backed retrieval. Two shapes per write/read:
+ * pass `model` to let the SDK embed for you; pass embeddings precomputed for
+ * provider/dimension/batching control.
  *
- * Native Drizzle methods (`select`, `insert`, `update`, `delete`, `transaction`,
- * `execute`) are exposed verbatim — we explicitly avoid wrapping them in a
- * Result envelope here. Drizzle already throws on misuse and returns typed rows
- * on success; mirroring its API keeps the contract identical to what the
- * `@stackbone/sdk/db` re-exports document, so creators write idiomatic Drizzle.
+ * Implementation note: `RagModule` is a thin facade over `RagPipeline`. The
+ * pipeline owns parse → chunk → embed → persist; the facade resolves the
+ * shared `client.database` pool, builds an `Embedder` on demand, and maps
+ * configuration errors. See ADR `2026-05-10-rag-consolidation-on-client-database`.
  *
- * Missing `STACKBONE_POSTGRES_URL` raises `SdkError('database_not_configured')`
- * with an actionable hint that points to `stackbone dev`. This is a creator
- * setup bug, not something the agent's code can recover from at runtime.
- *
- * Methods are declared with their full Drizzle generic signatures (rather than
- * `(...args) => Drizzle[k](...args)` arrow properties) so the inferred row
- * types from `pgTable(...)` flow end-to-end into the caller, which is the
- * promise the `@stackbone/sdk/db` re-export makes.
+ * Connection ownership: this module never opens its own postgres pool. It
+ * reaches the underlying `postgres-js` `Sql` through the **shared-handles
+ * pattern** — `client.database.shared().$client` — so an agent that
+ * touches both surfaces still opens exactly one connection pool against
+ * `STACKBONE_POSTGRES_URL`. RAG is the canonical first cross-surface
+ * consumer; memory and queues will adopt the same accessor when they
+ * land.
  *
- * The actual `postgres()` pool and the Drizzle handle are owned by the
- * module-internal singleton in `./internal.ts`. `client.database` and any
- * other internal SDK module that imports `getDatabaseHandle` therefore share
- * one pool per agent process — see `internal.spec.ts` for the invariant.
+ * Schema readiness: the canonical schema (`stackbone_platform.rag_*`) is
+ * provisioned by the platform migrator, present on every install. When an
+ * operation still hits `42P01 relation does not exist`, the pipeline returns
+ * `SdkError('rag_schema_missing')` with an actionable hint.
  */
-declare class DatabaseModule {
+/**
+ * Test-only seams accepted by `RagModule`. Production callers leave these
+ * unset — they are injected by `ingest-async.spec.ts` to substitute the
+ * shared-pool lookup and the SQL-backed job writer.
+ */
+interface RagModuleTestDeps {
+    /**
+     * Replaces the `client.database.shared().$client` lookup used by
+     * `ingestAsync`. Tests can plug a fake `Sql` here without standing up
+     * the database surface.
+     */
+    sqlProvider?: () => Result<Sql>;
+    /** Builds an `IngestJobWriter` from the resolved SQL. Defaults to `createSqlJobWriter`. */
+    jobWriterFactory?: (sql: Sql) => IngestJobWriter;
+}
+declare class RagModule {
     private readonly _resolved;
+    /**
+     * Lazy accessor for `client.database`. RAG calls `getDatabase().shared()`
+     * to reach the process-wide Drizzle handle (and its `$client` Sql) via
+     * the shared-handles pattern — never reaches into a sibling module's
+     * implementation file.
+     */
+    private readonly _getDatabase;
+    /**
+     * Lazy accessor for `client.ai`. RAG calls `getAi()` for the embeddings
+     * namespace; the `Embedder` adapter reaches the shared OpenAI client
+     * through the same `client.ai.embeddings.create` public surface, so
+     * RAG never instantiates a parallel `OpenAI` client.
+     */
+    private readonly _getAi;
     private readonly _gate;
+    private readonly _testSqlOverride?;
+    private readonly _testJobWriterFactory?;
     constructor(_resolved: ResolvedConfig, 
     /**
-     * Test seam — see `ModuleGate`. Defaults to the lazy contract gate.
-     * The gate is awaited at the terminal `await` of every Drizzle chain
-     * (`select/insert/update/delete/execute/transaction`); when it returns
-     * an error, a tagged `GateBlockedError` is thrown so callers see the
-     * same `Error & { code, message, meta }` surface as the existing
-     * `database_not_configured` setup-bug.
+     * Lazy accessor for `client.database`. RAG calls `getDatabase().shared()`
+     * to reach the process-wide Drizzle handle (and its `$client` Sql) via
+     * the shared-handles pattern — never reaches into a sibling module's
+     * implementation file.
+     */
+    _getDatabase: () => DatabaseModule, 
+    /**
+     * Lazy accessor for `client.ai`. RAG calls `getAi()` for the embeddings
+     * namespace; the `Embedder` adapter reaches the shared OpenAI client
+     * through the same `client.ai.embeddings.create` public surface, so
+     * RAG never instantiates a parallel `OpenAI` client.
+     */
+    _getAi: () => AiModule, 
+    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
+    gate?: ModuleGate, testDeps?: RagModuleTestDeps);
+    ingest(request: IngestRequest): Promise<Result<IngestResponse>>;
+    /**
+     * Asynchronous ingest. Allocates a `stackbone_rag_jobs` row, returns the
+     * job id immediately, and exposes both an `AsyncIterable` of streaming
+     * progress events and the final `Result` so callers can `await` either
+     * surface — typical webhook handlers consume `events` and ignore `result`,
+     * tests `await result` directly. Cancellation is observed by flipping the
+     * row's status (e.g. via `POST /api/rag/jobs/:jobId/cancel`); the worker
+     * polls between chunk batches and bails out with `rag_ingest_cancelled`.
+     *
+     * Connection ownership: the `IngestJobWriter` is bound to the same SQL
+     * pulled off the shared `client.database.shared()` handle, so a single
+     * agent that issues `ingestAsync` and `client.database.select` in
+     * flight still opens exactly one pool against
+     * `STACKBONE_POSTGRES_URL`.
+     */
+    ingestAsync(request: IngestRequest): Promise<Result<IngestAsyncHandle>>;
+    delete(ids: string | string[], options?: DeleteOptions): Promise<Result<DeleteResponse>>;
+    deleteWhere(filter: Record<string, unknown>, options?: DeleteOptions): Promise<Result<DeleteResponse>>;
+    retrieve(request: RetrieveRequest): Promise<Result<RetrieveHit[]>>;
+    /**
+     * Drops the legacy ad-hoc RAG tables (`rag_chunks` / `_rag_meta`) that
+     * pre-feature-30 agents provisioned on first ingest. Kept for backwards
+     * compatibility so an old agent can clean those up after upgrading. The
+     * canonical RAG schema (`stackbone_platform.rag_*`) is owned by the platform
+     * migrator — this method never touches it.
+     */
+    reset(): Promise<Result<void>>;
+    /**
+     * Pure helper — exposed verbatim from the chunker. No DB, no AI, no
+     * datapath traffic, so it is intentionally NOT gated.
+     */
+    chunk(text: string, options?: ChunkOptions): string[];
+    /**
+     * Pure helper — exposed verbatim from the parser. No DB, no AI, no
+     * datapath traffic, so it is intentionally NOT gated.
+     */
+    parse(input: ParseInput, options?: ParseOptions): Promise<string>;
+    /**
+     * Resolves the postgres-js `Sql` to use for this operation. Goes through
+     * the **shared-handles pattern** — `client.database.shared().$client` —
+     * to pull the postgres-js template-tag function off the same Drizzle
+     * handle the rest of the SDK uses. Single pool per agent process.
+     * Future cross-module transaction propagation plugs a tx-bound `Sql`
+     * into the pipeline at the same call site, replacing the pool-bound
+     * one without touching the rest of RAG.
+     *
+     * Configuration errors (`STACKBONE_POSTGRES_URL` unset) flow up as a
+     * `Result.err` with the same `database_not_configured` shape
+     * `client.database` raises, instead of throwing through the public
+     * surface.
+     */
+    private sql;
+    private withPipeline;
+}
+
+declare class SecretsFacade {
+    private readonly _resolved;
+    /**
+     * Lazy accessor for `client.database`. The facade pulls the shared
+     * `postgres-js` `Sql` via `getDatabase().shared().$client` — never
+     * reaching into a sibling module's implementation file.
+     */
+    private readonly _getDatabase;
+    private _cipher?;
+    constructor(_resolved: ResolvedConfig, 
+    /**
+     * Lazy accessor for `client.database`. The facade pulls the shared
+     * `postgres-js` `Sql` via `getDatabase().shared().$client` — never
+     * reaching into a sibling module's implementation file.
+     */
+    _getDatabase: () => DatabaseModule);
+    get(name: string): Promise<Result<string>>;
+    /**
+     * Names absent from the agent come back as omissions in the response — the
+     * returned map only contains entries the agent DB actually has. Callers that
+     * need "all-or-nothing" semantics should diff the keys.
      */
+    getMany(names: string[]): Promise<Result<Record<string, string>>>;
+    private cipher;
+    private sql;
+}
+
+interface StorageObject {
+    key: string;
+    size: number;
+    lastModified?: Date;
+    etag?: string;
+}
+interface UploadOptions {
+    contentType?: string;
+    metadata?: Record<string, string>;
+}
+interface ListOptions {
+    prefix?: string;
+    /** Maximum number of objects to return per page. Must be > 0. */
+    limit?: number;
+    cursor?: string;
+}
+interface SignedUrlOptions {
+    /** Seconds until the URL expires. Defaults to 3600 (1h). */
+    expiresIn?: number;
+    /** Only honoured by `getSignedUploadUrl` — pinned into the signature so the uploader must send a matching `Content-Type`. */
+    contentType?: string;
+}
+interface SignedUrl {
+    url: string;
+    expiresAt: Date;
+}
+type StorageBody = Blob | Uint8Array | string;
+interface S3Settings {
+    client: S3Client;
+    endpoint: string;
+    bucket: string;
+    agentId: string;
+}
+/**
+ * Public surface behind `client.storage`. Wraps `@aws-sdk/client-s3` against
+ * R2 (prod) or MinIO (dev). Exposes a bucket-scoped API via `from(bucket)`.
+ *
+ * Multi-tenancy: every key is prefixed with `agentId/bucket/` before hitting
+ * S3. Credentials are scoped to the agent's physical bucket (env `S3_BUCKET`),
+ * and the `bucket` argument is a logical namespace the agent uses to organise
+ * its own objects. The full prefixed key is an internal detail — public
+ * methods accept and return the user-facing key (without prefix). Metadata
+ * tracking in `_storage_objects` (Neon) is out-of-scope for this iteration.
+ *
+ * Memory note: `download()` materialises the whole object as a `Blob` in
+ * memory. For agents that need to stream large objects, prefer
+ * `getSignedDownloadUrl()` and `fetch()` the URL directly to consume the
+ * stream incrementally.
+ */
+declare class StorageModule {
+    private readonly _resolved;
+    private _s3;
+    private readonly _gate;
+    constructor(_resolved: ResolvedConfig, 
+    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
     gate?: ModuleGate);
+    from(bucket: string): StorageBucket;
+    private settings;
+}
+declare class StorageBucket {
+    private readonly bucketName;
+    private readonly resolveSettings;
+    private readonly gate;
+    constructor(bucketName: string, resolveSettings: () => Result<S3Settings>, gate: ModuleGate);
+    upload(key: string, body: StorageBody, options?: UploadOptions): Promise<Result<{
+        key: string;
+        etag?: string;
+    }>>;
+    download(key: string): Promise<Result<Blob>>;
+    list(options?: ListOptions): Promise<Result<{
+        objects: readonly StorageObject[];
+        nextCursor?: string;
+    }>>;
+    remove(key: string): Promise<Result<{
+        key: string;
+    }>>;
     /**
-     * Escape hatch — returns Drizzle's relational query builder verbatim. The
-     * contract gate does NOT fire here because the surface is a synchronous
-     * accessor; the user can still bypass the gate via `client.database.raw()`
-     * for the same reason. Audit: `query` and `raw()` are intentionally
-     * ungated escape hatches; the standard `select/insert/update/delete/
-     * execute/transaction` path is fully gated.
+     * Returns the canonical S3-style URL for an object. Pure URL-builder — no
+     * S3 round-trip — so this method intentionally bypasses the contract gate.
+     * Whether the URL is publicly fetchable depends on the bucket policy; for
+     * private buckets, use `getSignedDownloadUrl` instead.
      */
-    get query(): DrizzleClient['query'];
-    select: DrizzleClient['select'];
-    insert: DrizzleClient['insert'];
-    update: DrizzleClient['update'];
-    delete: DrizzleClient['delete'];
-    execute: DrizzleClient['execute'];
-    transaction: DrizzleClient['transaction'];
+    getPublicUrl(key: string): Result<string>;
+    getSignedUploadUrl(key: string, options?: SignedUrlOptions): Promise<Result<SignedUrl>>;
+    getSignedDownloadUrl(key: string, options?: SignedUrlOptions): Promise<Result<SignedUrl>>;
+    private signUrl;
     /**
-     * Escape hatch for callers that want the raw Drizzle handle (e.g. to pass
-     * it to a library that expects `PostgresJsDatabase`). Reading this property
-     * triggers the same lazy initialisation as any other method but
-     * intentionally does NOT consult the contract gate — the surface is sync
-     * and the caller is opting out of the SDK's structured surface.
+     * Resolves S3 settings, validates the user key, and prefixes it with
+     * `${agentId}/${bucketName}/`. Rejects path-traversal segments (`..`) so a
+     * caller-controlled key cannot escape the agent's namespace.
      */
-    raw(): DrizzleClient;
+    private resolve;
 }
 
 /**
@@ -727,9 +1274,14 @@ interface EndSessionResult {
  * scaffolding placeholder: every method returns `not_implemented`. The real
  * backend will be mem0 (`mem0ApiKey` / `MEM0_API_KEY`) and the public surface
  * defined here is the contract callers can already type against.
+ *
+ * Contract gating: not gated. Memory targets mem0 (a non-Stackbone partner),
+ * so there is no Stackbone Agent Protocol capability to assert against. No
+ * entry in `MODULE_CAPABILITIES` per the rule documented in
+ * `contract/capability-registry.ts`. When/if the runtime moves to a
+ * Stackbone-served backend we add the capability and wire the gate.
  */
 declare class MemoryModule {
-    private readonly _resolved;
     constructor(_resolved: ResolvedConfig);
     add(_content: MemoryContent, _request: AddMemoryRequest): Promise<Result<MemoryItem>>;
     search(_query: string, _options?: SearchMemoryOptions): Promise<Result<readonly MemoryHit[]>>;
@@ -746,628 +1298,285 @@ declare class MemoryModule {
     endSession(_sessionId: string, _options?: EndSessionOptions): Promise<Result<EndSessionResult>>;
 }
 
-declare const RUN_STEP_TYPES: readonly ["agent", "llm_call", "db_query", "http_fetch", "queue_publish", "hitl_pause", "tool_call", "rag_query", "storage_op"];
-type RunStepType = (typeof RUN_STEP_TYPES)[number];
-declare const STEP_TYPE_ATTRIBUTE = "stackbone.step.type";
-declare const RUN_ID_ATTRIBUTE = "stackbone.run.id";
+/** Subset of `RequestInit['body']` we serialize without modification. */
+type SerializedBody = NonNullable<RequestInit['body']>;
 /**
- * Minimal duck-typed view of an OpenTelemetry `ReadableSpan`. We mirror the
- * shape the OTel SDK exposes on `@opentelemetry/sdk-trace-base` rather than
- * importing the package so `@stackbone/sdk` doesn't pull the OTel runtime into
- * every agent that doesn't enable Studio. Agents wire the processor with
- * `provider.addSpanProcessor(new RunStepsSpanProcessor(...))` and the
- * structural match satisfies TypeScript.
+ * Per-status overrides facades attach when an HTTP status carries a
+ * non-canonical meaning for the endpoint — e.g. a `POST` whose `409` means
+ * "already exists" instead of the default "conflict". Keys are HTTP statuses,
+ * values are domain codes the transport should surface verbatim (no prefix
+ * concatenation — the override is the final code).
+ *
+ * The value is typed against the catalog (`SdkErrorCode`) so an endpoint
+ * cannot smuggle a wire code that isn't in the documented inventory.
  */
-interface SpanContextLike {
-    spanId: string;
-    traceId: string;
-}
-interface ReadableSpanLike {
-    spanContext(): SpanContextLike;
-    parentSpanContext?: SpanContextLike | undefined;
-    parentSpanId?: string | undefined;
-    name: string;
-    attributes: Record<string, unknown>;
-    status?: {
-        code: number;
-        message?: string;
-    } | undefined;
-    startTime?: [number, number] | undefined;
-    endTime?: [number, number] | undefined;
-    duration?: [number, number] | undefined;
-}
-interface PostgresLike {
-    unsafe(query: string, params?: unknown[]): Promise<unknown>;
-    end?(): Promise<void>;
-}
-interface RunStepsSpanProcessorOptions {
+type ErrorOverrides = Record<number, SdkErrorCode>;
+/**
+ * Tells the transport how to remap HTTP status codes onto the surface's
+ * domain code prefix. `404 → '<prefix>_not_found'`, `401 → '<prefix>_unauthorized'`,
+ * etc. Endpoint-specific overrides win over the canonical mapping.
+ *
+ * `prefix` is constrained to `SdkErrorPrefix` (the catalog's prefix tuple) so
+ * an unknown surface name doesn't compile — keeps the wire codes the
+ * transport emits inside the typed inventory.
+ */
+interface ErrorMapping {
+    /** Prefix concatenated with `_not_found`, `_unauthorized`, …. Required for any domain remap. */
+    prefix: SdkErrorPrefix;
+    /** Per-status final code that overrides the canonical mapping. */
+    overrides?: ErrorOverrides;
+}
+interface RequestOptions extends Omit<RequestInit, 'body' | 'signal'> {
+    /** Scalar query params. `undefined` values are dropped, others get coerced via `String()`. */
+    params?: Record<string, string | number | boolean | undefined>;
     /**
-     * Postgres connection string of the install (local emulator at :5433 in
-     * dev, Neon TCP/HTTP URL in cloud). Falls back to `DATABASE_URL`.
+     * Repeated string-array params validated and serialised by the transport.
+     * Empty arrays / blank elements reject upstream with `<prefix>_invalid_request`
+     * (falls back to `http_invalid_request` when no `errorMapping` is set). Each
+     * array is joined with `,` to match the canonical control-plane shape.
      */
-    connectionString?: string | undefined;
-    /** Flush trigger by buffer size. Defaults to 50. */
-    flushBatchSize?: number | undefined;
-    /** Flush trigger by elapsed time (ms). Defaults to 500. */
-    flushIntervalMs?: number | undefined;
-    /** Override how a span maps to a step type. */
-    resolveStepType?: ((span: ReadableSpanLike) => RunStepType) | undefined;
-    /** Test seam — inject a postgres-js-compatible client. */
-    sql?: PostgresLike | undefined;
-    /** Test seam — deterministic UUID generator. */
-    newId?: (() => string) | undefined;
+    arrayParams?: Record<string, readonly string[]>;
+    body?: SerializedBody | Record<string, unknown> | unknown[] | null;
+    signal?: AbortSignal;
+    /** Allow retrying non-idempotent requests (POST, PATCH). Off by default to prevent duplicate writes. */
+    idempotent?: boolean;
 }
 /**
- * Materialises every OTel span produced by the agent into a row of
- * `stackbone_platform.run_steps`. Designed to coexist with the OTLP exporter:
- * cloud builds register both processors so Postgres feeds Studio (paridad
- * con local) and Tempo feeds Platform Ops with retention/aggregation. If a
- * write fails the processor logs to stderr and keeps accepting spans —
- * observability is never load-bearing for agent execution.
+ * Shape every facade method ideally collapses into: "POST to /path with this
+ * body, validate against this schema, surface errors as `<prefix>_*`". The
+ * transport handles validation, HTTP→domain remapping, querystring assembly
+ * and the `Result` envelope so facades stay tiny orchestrators.
  *
- * Spec: docs/arquitectura/specs/stackbone-agent-protocol-v1.md §6.3
- * ADR:  docs/arquitectura/decisiones/2026-05-03-stackbone-studio-datapath-y-scope-mvp.md §D9
+ * `arrayParams` keys default to `errorMapping.prefix` for the validation
+ * error code (e.g. an empty `names: []` becomes `secrets_invalid_request`).
  */
-declare class RunStepsSpanProcessor {
-    private readonly buffer;
-    private readonly stepIdBySpanId;
-    private readonly batchSize;
-    private readonly intervalMs;
-    private readonly resolveStepType;
-    private readonly newId;
-    private readonly connectionString;
-    private readonly ownsSql;
-    private sql;
-    private timer;
-    private inFlight;
-    constructor(options?: RunStepsSpanProcessorOptions);
-    onStart(span: ReadableSpanLike): void;
-    onEnd(span: ReadableSpanLike): void;
-    forceFlush(): Promise<void>;
-    shutdown(): Promise<void>;
-    private buildRow;
-    private armTimer;
-    private disarmTimer;
-    private flush;
-    private ensureSql;
-    private writeBatch;
-}
-
-interface AggregateRunCostOptions {
-    sql: PostgresLike;
-}
-interface AggregateRunCostResult {
-    costEstimatedUsd: number;
-}
-declare function aggregateRunCost(runId: string, options: AggregateRunCostOptions): Promise<AggregateRunCostResult>;
-
-declare const LOG_LEVELS: {
-    readonly trace: 10;
-    readonly debug: 20;
-    readonly info: 30;
-    readonly warn: 40;
-    readonly error: 50;
-    readonly fatal: 60;
-};
-type LogLevelName = keyof typeof LOG_LEVELS;
-type LogLevelNumber = (typeof LOG_LEVELS)[LogLevelName];
-interface LogRecord {
-    /** Pino-style numeric level. */
-    level: LogLevelNumber;
-    /** Epoch milliseconds. Pino uses `time` as a number. */
-    time: number;
-    msg: string;
-    run_id: string;
-    trace_id?: string;
-    installation_id?: string;
-    agent_id?: string;
-    [key: string]: unknown;
-}
-interface PlatformLoggerOptions {
-    runId: string;
-    installationId?: string | undefined;
-    agentId?: string | undefined;
+interface TransportRequest<T> extends RequestOptions {
+    method: string;
+    path: string;
     /**
-     * When set (cloud), logs are batched and POSTed to `<endpoint>/v1/logs` as
-     * OTLP/HTTP/JSON. When unset (local), logs are appended to
-     * `<runsDir>/<runId>.jsonl`. Falls back to `OTEL_EXPORTER_OTLP_ENDPOINT`.
+     * Zod schema (or any object with a `.safeParse()` method) the parsed body
+     * must validate against. On failure the transport surfaces
+     * `<prefix>_invalid_response` (or `http_invalid_response` if no prefix is
+     * configured) with the schema issues attached to `meta.issues`.
      */
-    otelEndpoint?: string | undefined;
-    /** Local-only: directory where JSONL files live. Defaults to `~/.stackbone/dev/runs`. */
-    runsDir?: string | undefined;
-    /** Cloud-only: extra OTel resource attributes to send with every batch. */
-    resourceAttributes?: Record<string, string> | undefined;
-    /** Cloud-only: HTTP timeout per OTLP POST in ms. Defaults to 5_000. */
-    httpTimeoutMs?: number | undefined;
-    /** Flush trigger by buffer size. Defaults to 50. */
-    flushBatchSize?: number | undefined;
-    /** Flush trigger by elapsed time (ms). Defaults to 1_000. */
-    flushIntervalMs?: number | undefined;
-    /** Test seam — fetch implementation. Defaults to global `fetch`. */
-    fetchImpl?: typeof fetch | undefined;
-    /** Test seam — `fs.appendFile`-shaped sink the local destination uses. */
-    appendFileImpl?: ((path: string, data: string) => Promise<void>) | undefined;
-    /** Test seam — `fs.mkdir`-shaped helper the local destination uses. */
-    mkdirImpl?: ((path: string) => Promise<void>) | undefined;
-    /** Test seam — clock for `time` field. Defaults to `Date.now`. */
-    now?: (() => number) | undefined;
-    /** Override mode resolution (skips the env detection). */
-    mode?: PlatformLoggerMode | undefined;
-}
-type PlatformLoggerMode = 'local' | 'cloud';
-interface PinoLike {
-    trace(msgOrObj: unknown, msg?: string): void;
-    debug(msgOrObj: unknown, msg?: string): void;
-    info(msgOrObj: unknown, msg?: string): void;
-    warn(msgOrObj: unknown, msg?: string): void;
-    error(msgOrObj: unknown, msg?: string): void;
-    fatal(msgOrObj: unknown, msg?: string): void;
-}
-interface PlatformLogger extends PinoLike {
-    readonly mode: PlatformLoggerMode;
-    /** Bind extra fields and return a child logger sharing the same destination. */
-    child(bindings: Record<string, unknown>): PlatformLogger;
-    /** Force-flush pending writes (close file handle or POST OTLP batch). */
-    flush(): Promise<void>;
-    /** Stop accepting writes and release resources. */
-    close(): Promise<void>;
+    responseSchema?: ResponseSchema<T>;
+    /** HTTP→domain remapping. Omit to let `http_*` codes flow through unchanged. */
+    errorMapping?: ErrorMapping;
 }
 /**
- * Creates a Pino-aligned logger that writes JSONL to disk in local mode and
- * batches OTLP/HTTP/JSON log records to an OTel collector in cloud mode. Mode
- * is resolved from `OTEL_EXPORTER_OTLP_ENDPOINT` or the explicit override.
+ * Minimal contract the transport needs from a schema — `safeParse`. Compatible
+ * with Zod (`z.object(…).safeParse(value)`) and any hand-rolled validator that
+ * follows the same shape. Avoids leaking Zod's full surface into the transport
+ * signature.
  */
-declare function createPlatformLogger(options: PlatformLoggerOptions): PlatformLogger;
-declare function defaultRunsDir(): string;
-
-declare class ObservabilityModule {
-    private readonly _resolved;
-    private _processor?;
-    private readonly _loggers;
-    private _sql;
-    private _sqlResolved;
-    constructor(_resolved: ResolvedConfig);
-    /**
-     * Singleton SpanProcessor that the agent registers in its OTel
-     * TracerProvider. Coexists with the OTLP exporter — cloud builds wire
-     * both so Postgres feeds Studio (paridad con local) and Tempo feeds
-     * Platform Ops.
-     */
-    spanProcessor(options?: RunStepsSpanProcessorOptions): RunStepsSpanProcessor;
-    flush(): Promise<Result<void>>;
+interface ResponseSchema<T> {
+    safeParse(input: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            issues: unknown;
+        };
+    };
+}
+interface HttpClientOptions {
+    /** Default 30_000. Set to 0 to disable. */
+    timeout?: number;
+    /** Default 3. Set to 0 to disable. */
+    retryCount?: number;
+    /** Initial backoff in ms; doubles each attempt with ±15% jitter. Default 500. */
+    retryDelay?: number;
+    /** Override the global fetch (useful for tests). */
+    fetch?: typeof fetch;
+}
+/**
+ * Shared HTTP client used by every facade that talks to the Stackbone
+ * control plane. Wraps `fetch` with timeout, exponential backoff with jitter,
+ * idempotent-only retries, response validation (Zod-compatible schemas) and
+ * a uniform `Result` envelope so facades never throw at the SDK boundary.
+ *
+ * Each facade tells the transport its error prefix (`'secrets'`, `'config'`,
+ * `'approval'`) so 404/401/403/429/5xx remap to surface-specific codes —
+ * `secrets_not_found`, `approval_unauthorized`, etc. Endpoint-specific
+ * remaps (e.g. `409 → 'secrets_already_exists'`) flow through
+ * `errorMapping.overrides`. Transport-level failures (network, timeout,
+ * parse) keep the `http_*` prefix the README contract documents.
+ *
+ * Reads `STACKBONE_API_URL` and `STACKBONE_AGENT_JWT` lazily on every request so
+ * env-var rotation is picked up without restarting the client.
+ */
+declare class HttpClient {
+    private readonly resolved;
+    private readonly timeout;
+    private readonly retryCount;
+    private readonly retryDelay;
+    private readonly fetchImpl;
+    constructor(resolved: ResolvedConfig, options?: HttpClientOptions);
     /**
-     * Per-run structured logger. In local mode (no `OTEL_EXPORTER_OTLP_ENDPOINT`)
-     * appends JSONL to `~/.stackbone/dev/runs/<runId>.jsonl`; in cloud mode batches
-     * OTLP/HTTP/JSON log records to the collector. Cached by `runId` so the
-     * file handle / buffered timer stays stable across repeated calls inside
-     * the same run.
+     * Convenience for `request({ method: 'GET', path, ... })`. Kept so legacy
+     * callers (tests, pending facades) keep compiling — the deep work happens
+     * in `request()`.
      */
-    logger(options: {
-        runId: string;
-    } & Partial<PlatformLoggerOptions>): PlatformLogger;
-    /** Closes the per-run logger (flushes the JSONL file or the OTLP buffer). */
-    closeLogger(runId: string): Promise<void>;
+    get<T>(path: string, options?: RequestOptions): Promise<Result<T>>;
+    post<T>(path: string, body?: RequestOptions['body'], options?: RequestOptions): Promise<Result<T>>;
+    put<T>(path: string, body?: RequestOptions['body'], options?: RequestOptions): Promise<Result<T>>;
+    patch<T>(path: string, body?: RequestOptions['body'], options?: RequestOptions): Promise<Result<T>>;
+    delete<T>(path: string, options?: RequestOptions): Promise<Result<T>>;
     /**
-     * Hook the agent calls when a run finishes. Sums `cost_usd` from every
-     * `llm_call` span of the run and writes the total to
-     * `stackbone_platform.runs.cost_estimated_usd`. Errors are folded into the
-     * Result envelope so the agent's run cleanup never aborts on a flaky
-     * Postgres call — the cost is decorative metadata, not load-bearing.
+     * The transport entry point every facade should target. Handles base-URL
+     * resolution, header injection, body/querystring serialisation, retry +
+     * timeout, response validation and HTTP→domain error remapping.
      */
-    closeRun(runId: string): Promise<Result<AggregateRunCostResult>>;
-    private resolveSql;
+    request<T>(req: TransportRequest<T>): Promise<Result<T>>;
+    private computeBackoff;
 }
 
+/**
+ * Enqueue a one-shot (or deferred) job. The opaque `payload` is whatever the
+ * agent's `receive` handler expects — the core never inspects it.
+ */
 interface PublishRequest {
-    url: string;
-    body: unknown;
+    /** Opaque job name (e.g. `send-email`). Surfaced in the Studio inspector. */
+    name: string;
+    /** Opaque job payload — JSON-serialisable; the core forwards it untouched. */
+    payload: unknown;
+    /** Per-job override of the platform retry default. Omitted → platform default. */
     retries?: number;
+    /** Deferred delivery in milliseconds. Omitted / 0 → immediate. */
     delay?: number;
+    /** Idempotency hint — a duplicate publish with the same key collapses to one job. */
     deduplicationId?: string;
-    headers?: Record<string, string>;
 }
-declare class QueuesModule {
-    private readonly _gate;
-    constructor(resolved: ResolvedConfig, 
-    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
-    gate?: ModuleGate);
-    publish(_request: PublishRequest): Promise<Result<{
-        messageId: string;
-    }>>;
-}
-
-type ChunkStrategy = 'recursive' | 'sentence';
-interface ChunkOptions {
-    /** Splitter algorithm. Default `recursive`. */
-    strategy?: ChunkStrategy;
-    /** Target characters per chunk. Default 512. */
-    size?: number;
-    /** Characters of overlap between consecutive chunks. Default 64. */
-    overlap?: number;
-}
-
-type RagIngestProgress = {
-    type: 'started';
-    jobId: string;
-    totalChunks: number;
-} | {
-    type: 'progress';
-    jobId: string;
-    processedChunks: number;
-    totalChunks: number;
-    currentDocument?: {
-        source: string;
-        ordinal: number;
-    };
-} | {
-    type: 'completed';
-    jobId: string;
-    totalChunks: number;
-} | {
-    type: 'failed';
-    jobId: string;
-    error: string;
-};
-interface IngestJobStartArgs {
-    collection: string;
-    source: string;
-    totalChunks: number;
-}
-interface IngestJobProgressArgs {
-    jobId: string;
-    processedChunks: number;
-    totalChunks: number;
-    currentDocument?: {
-        source: string;
-        ordinal: number;
-    };
-}
-interface IngestJobCompleteArgs {
-    jobId: string;
-    totalChunks: number;
-}
-interface IngestJobFailArgs {
-    jobId: string;
-    error: string;
-}
-interface IngestJobWriter {
-    /**
-     * Allocates a `stackbone_rag_jobs` row in `running` state and returns its
-     * id. Caller is expected to surface this id to the user before any
-     * progress event fires so a `client.rag.ingestAsync` consumer can
-     * immediately address the job (e.g. `POST /api/rag/jobs/:jobId/cancel`).
-     */
-    start(args: IngestJobStartArgs): Promise<Result<{
-        jobId: string;
-    }>>;
-    /** Idempotent — last write wins on `progress` jsonb. */
-    progress(args: IngestJobProgressArgs): Promise<void>;
-    /** Marks the row terminal (status='succeeded'). */
-    complete(args: IngestJobCompleteArgs): Promise<void>;
-    /** Marks the row terminal (status='failed') and stores the error message. */
-    fail(args: IngestJobFailArgs): Promise<void>;
-    /**
-     * Polled between chunk batches. Returning `true` makes the pipeline abort
-     * with `rag_ingest_cancelled`, leaving the row in whatever terminal state
-     * the writer transitions it to next (typically `cancelled`).
-     */
-    isCancelled(args: {
-        jobId: string;
-    }): Promise<boolean>;
-}
-
-interface ParseOptions {
-    /** MIME type override. If omitted, the parser sniffs the input (Blob.type or PDF magic bytes). */
-    mime?: string;
-}
-type ParseInput = Blob | string | Uint8Array | ArrayBuffer;
-
-interface IngestChunk {
-    content: string;
-    embedding: number[];
-}
-interface IngestRequestBase {
-    /** Document identifier — re-ingesting with the same `id` replaces all its chunks atomically. */
-    id: string;
-    metadata?: Record<string, unknown>;
-    /** Logical namespace for separation. Default `'default'`. */
-    namespace?: string;
-    /**
-     * Canonical collection name used by the `stackbone_rag_jobs` writer (F07)
-     * to bind the row to a `stackbone_rag_collections` parent. Optional for
-     * back-compat with pre-F07 callers — when absent, no job row is written
-     * and progress is delivered only via `onProgress` (if any).
-     */
-    collection?: string;
-    /**
-     * Optional sink for streaming progress events. Fired in addition to (and
-     * before) the matching `IngestJobWriter` call so synchronous `ingest`
-     * consumers can observe progress without paying the SQL writer cost.
-     */
-    onProgress?: (event: RagIngestProgress) => void | Promise<void>;
-}
-interface IngestRequestPrecomputed extends IngestRequestBase {
-    chunks: IngestChunk[];
-}
-interface IngestRequestAutoEmbed extends IngestRequestBase {
-    chunks: string[];
-    /** Embedding model id. When set, the pipeline calls the configured Embedder. */
-    model: string;
-    /**
-     * Items per embeddings request. Consumed by the facade when it builds the
-     * `Embedder`; ignored by the pipeline itself (the embedder is fully
-     * configured at construction time).
-     */
-    batchSize?: number;
-}
-type IngestRequest = IngestRequestPrecomputed | IngestRequestAutoEmbed;
-interface IngestResponse {
-    id: string;
-    chunks: number;
-}
-interface DeleteOptions {
-    namespace?: string;
-}
-interface DeleteResponse {
-    deleted: number;
-}
-interface RetrieveRequestBase {
-    topK?: number;
-    filter?: Record<string, unknown>;
-    namespace?: string;
-    includeContent?: boolean;
-    includeMetadata?: boolean;
-}
-interface RetrieveRequestPrecomputed extends RetrieveRequestBase {
-    embedding: number[];
-}
-interface RetrieveRequestAutoEmbed extends RetrieveRequestBase {
-    text: string;
-    /** Must match the model used at ingest time. */
-    model: string;
-}
-type RetrieveRequest = RetrieveRequestPrecomputed | RetrieveRequestAutoEmbed;
-interface RetrieveHit {
-    id: string;
-    chunkIdx: number;
-    content?: string;
-    metadata?: Record<string, unknown>;
-    score: number;
+/** Register / update a dynamic per-installation cron schedule. */
+interface ScheduleRequest {
+    /** Schedule name, unique per install. Re-scheduling the same name updates it in place. */
+    name: string;
+    /** Opaque payload delivered on every fire. */
+    payload: unknown;
+    /** Cron expression evaluated by the dispatcher. */
+    cron: string;
+    /** IANA timezone the cron pattern runs in. Defaults to UTC. */
+    tz?: string;
+    /** Per-job override of the platform retry default. */
+    retries?: number;
 }
-
-/**
- * Handle returned by `client.rag.ingestAsync`. The job id is allocated
- * synchronously against `stackbone_rag_jobs` so the caller can track / cancel
- * the work via the `/api/rag/jobs/:jobId/*` surface; `events` is a streaming
- * channel of progress events (ADR §D9 shape); `result` settles when the
- * pipeline finishes (or fails / is cancelled).
- */
-interface IngestAsyncHandle {
-    jobId: string;
-    events: AsyncIterable<RagIngestProgress>;
-    result: Promise<Result<IngestResponse>>;
+/** Cancel a previously registered schedule by name. */
+interface UnscheduleRequest {
+    name: string;
 }
 /**
- * `client.rag` — `pgvector`-backed retrieval. Two shapes per write/read:
- * pass `model` to let the SDK embed for you; pass embeddings precomputed for
- * provider/dimension/batching control.
+ * `client.queues` — the agent's handle on the BullMQ-backed job system. The
+ * agent never touches Redis: each method makes an authenticated call to the
+ * control plane (the dispatcher owns the queue + the clock).
  *
- * Implementation note: `RagModule` is a thin facade over `RagPipeline`. The
- * pipeline owns parse → chunk → embed → persist; the facade resolves the
- * shared `client.database` pool, builds an `Embedder` on demand, and maps
- * configuration errors. See ADR `2026-05-10-rag-consolidation-on-client-database`.
+ * - `publish` enqueues a one-shot job (optionally deferred via `delay`, with a
+ *   per-job `retries` override and an optional `deduplicationId`).
+ * - `schedule` / `unschedule` manage dynamic per-user cron schedules.
+ * - `listSchedules` lists the install's active schedules.
  *
- * Connection ownership: this module never opens its own postgres pool. It
- * pulls the underlying `postgres-js` `Sql` from the shared
- * `getDatabaseHandle()` exposed by `client.database`, so an agent that
- * touches both surfaces still opens exactly one connection pool against
- * `STACKBONE_POSTGRES_URL`.
+ * Authentication reuses the existing `STACKBONE_AGENT_JWT` channel injected at
+ * provisioning (the `HttpClient` attaches the bearer + install header), so the
+ * core scopes every enqueue to the agent's own install.
  *
- * Schema readiness: starting with feature 30, the canonical schema is
- * installed by the CLI (`stackbone db migrate add-rag` + `migrate up`). When
- * an operation hits `42P01 relation does not exist`, the pipeline returns
- * `SdkError('rag_schema_missing')` with an actionable hint.
+ * Contract gating: every method awaits the `queues.jobs` module gate before
+ * touching the network, so a stale datapath / missing capability surfaces as
+ * a gating error rather than a failed POST.
  */
-/**
- * Test-only seams accepted by `RagModule`. Production callers leave these
- * unset — they are injected by `ingest-async.spec.ts` to substitute the
- * shared-pool lookup and the SQL-backed job writer.
- */
-interface RagModuleTestDeps {
-    /** Replaces the lazy `getDatabaseHandle()` lookup used by `ingestAsync`. */
-    sqlProvider?: () => Result<Sql>;
-    /** Builds an `IngestJobWriter` from the resolved SQL. Defaults to `createSqlJobWriter`. */
-    jobWriterFactory?: (sql: Sql) => IngestJobWriter;
-}
-declare class RagModule {
-    private readonly _resolved;
-    private readonly _getAi;
+declare class QueuesModule {
+    private readonly _http;
     private readonly _gate;
-    private readonly _testSqlOverride?;
-    private readonly _testJobWriterFactory?;
-    constructor(_resolved: ResolvedConfig, _getAi: () => AiModule, 
+    constructor(resolved: ResolvedConfig, _http: HttpClient, 
     /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
-    gate?: ModuleGate, testDeps?: RagModuleTestDeps);
-    ingest(request: IngestRequest): Promise<Result<IngestResponse>>;
-    /**
-     * Asynchronous ingest. Allocates a `stackbone_rag_jobs` row, returns the
-     * job id immediately, and exposes both an `AsyncIterable` of streaming
-     * progress events and the final `Result` so callers can `await` either
-     * surface — typical webhook handlers consume `events` and ignore `result`,
-     * tests `await result` directly. Cancellation is observed by flipping the
-     * row's status (e.g. via `POST /api/rag/jobs/:jobId/cancel`); the worker
-     * polls between chunk batches and bails out with `rag_ingest_cancelled`.
-     *
-     * Connection ownership: the `IngestJobWriter` is bound to the same SQL
-     * pulled off the shared `client.database` handle, so a single agent that
-     * issues `ingestAsync` and `client.database.select` in flight still opens
-     * exactly one pool against `STACKBONE_POSTGRES_URL`.
-     */
-    ingestAsync(request: IngestRequest): Promise<Result<IngestAsyncHandle>>;
-    delete(ids: string | string[], options?: DeleteOptions): Promise<Result<DeleteResponse>>;
-    deleteWhere(filter: Record<string, unknown>, options?: DeleteOptions): Promise<Result<DeleteResponse>>;
-    retrieve(request: RetrieveRequest): Promise<Result<RetrieveHit[]>>;
-    /**
-     * Drops the legacy ad-hoc RAG schema. Kept for backwards compatibility with
-     * pre-feature-30 agents whose tables were provisioned by `ensureSchema` on
-     * first call. The canonical RAG schema (feature 30) is owned by the CLI and
-     * removed via `stackbone db migrate` flows, not by this method.
-     */
-    reset(): Promise<Result<void>>;
-    /**
-     * Pure helper — exposed verbatim from the chunker. No DB, no AI, no
-     * datapath traffic, so it is intentionally NOT gated.
-     */
-    chunk(text: string, options?: ChunkOptions): string[];
-    /**
-     * Pure helper — exposed verbatim from the parser. No DB, no AI, no
-     * datapath traffic, so it is intentionally NOT gated.
-     */
-    parse(input: ParseInput, options?: ParseOptions): Promise<string>;
-    /**
-     * Resolves the postgres-js `Sql` to use for this operation. Pulls `$client`
-     * off the shared Drizzle handle (single pool per agent process). Slice F03's
-     * NOTE about cross-module transaction propagation lives here: this is the
-     * seam where a future `database.transaction` integration plugs a tx-bound
-     * `Sql` into the pipeline instead of the pool-bound one.
-     *
-     * Configuration errors (`STACKBONE_POSTGRES_URL` unset) flow up as a
-     * `Result.err` with the same `database_not_configured` shape `client.database`
-     * raises, instead of throwing through the public surface.
-     */
-    private sql;
-    private withPipeline;
+    gate?: ModuleGate);
+    publish(request: PublishRequest): Promise<Result<PublishJobResponse>>;
+    schedule(request: ScheduleRequest): Promise<Result<ScheduleJobResponse>>;
+    unschedule(request: UnscheduleRequest): Promise<Result<UnscheduleJobResponse>>;
+    listSchedules(): Promise<Result<ListSchedulesResponse>>;
 }
 
-interface StorageObject {
-    key: string;
-    size: number;
-    lastModified?: Date;
-    etag?: string;
-}
-interface UploadOptions {
-    contentType?: string;
-    metadata?: Record<string, string>;
-}
-interface ListOptions {
-    prefix?: string;
-    /** Maximum number of objects to return per page. Must be > 0. */
-    limit?: number;
-    cursor?: string;
-}
-interface SignedUrlOptions {
-    /** Seconds until the URL expires. Defaults to 3600 (1h). */
-    expiresIn?: number;
-    /** Only honoured by `getSignedUploadUrl` — pinned into the signature so the uploader must send a matching `Content-Type`. */
-    contentType?: string;
-}
-interface SignedUrl {
-    url: string;
-    expiresAt: Date;
-}
-type StorageBody = Blob | Uint8Array | string;
-interface S3Settings {
-    client: S3Client;
-    endpoint: string;
-    bucket: string;
-    agentId: string;
-}
 /**
- * Public surface behind `client.storage`. Wraps `@aws-sdk/client-s3` against
- * R2 (prod) or MinIO (dev). Exposes a bucket-scoped API via `from(bucket)`.
+ * The live agent surfaces exposed to the creator's code through a single
+ * `createClient()` entry point. The folder layout under `src/surfaces/`
+ * groups each surface by where its state lives:
  *
- * Multi-tenancy: every key is prefixed with `agentId/bucket/` before hitting
- * S3. Credentials are scoped to the agent's physical bucket (env `S3_BUCKET`),
- * and the `bucket` argument is a logical namespace the agent uses to organise
- * its own objects. The full prefixed key is an internal detail — public
- * methods accept and return the user-facing key (without prefix). Metadata
- * tracking in `_storage_objects` (Neon) is out-of-scope for this iteration.
+ * - `surfaces/agent-local/` — Postgres branch owned by the agent
+ *   (`database`, `rag`, `secrets`, `config`, `approval`). `secrets`,
+ *   `config` and `approval` moved here from the control plane: the agent now
+ *   reads its secrets/config and records HITL pauses directly against its own
+ *   `stackbone_platform.*` tables (decrypting secrets with the per-agent key),
+ *   with no control-plane round-trip. The approval RESUME callback stays
+ *   Studio-signed and is reconciled locally by `approval.verify()`.
+ * - `surfaces/external/` — managed partner SDKs the SDK wraps directly
+ *   (`ai` / OpenRouter, `storage` / S3 + R2 / MinIO). Observability is not a
+ *   creator surface: agent code observes runs through the handler-scoped
+ *   `ctx.logger` (and plain `console.*`, which the wrapper captures and
+ *   correlates), while the platform primitives live in the
+ *   `@stackbone/sdk/observability` subpath the runtime wires directly.
+ * - `surfaces/control-plane/` — thin HTTP calls to Stackbone's control
+ *   plane (none today after secrets/config/approval moved agent-local).
+ * - `surfaces/pending/` — public surface is stable but the runtime is
+ *   not built yet. They are wired as live `client.X` accessors so MVP
+ *   agent code can be authored against the eventual contract today; each
+ *   method returns `Result<{ error: { code: "not_implemented" } }>` until
+ *   the backing runtime ships. Today: queues, memory.
  *
- * Memory note: `download()` materialises the whole object as a `Blob` in
- * memory. For agents that need to stream large objects, prefer
- * `getSignedDownloadUrl()` and `fetch()` the URL directly to consume the
- * stream incrementally.
- */
-declare class StorageModule {
-    private readonly _resolved;
-    private _s3;
-    private readonly _gate;
-    constructor(_resolved: ResolvedConfig, 
-    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
-    gate?: ModuleGate);
-    from(bucket: string): StorageBucket;
-    private settings;
-}
-declare class StorageBucket {
-    private readonly bucketName;
-    private readonly resolveSettings;
-    private readonly gate;
-    constructor(bucketName: string, resolveSettings: () => Result<S3Settings>, gate: ModuleGate);
-    upload(key: string, body: StorageBody, options?: UploadOptions): Promise<Result<{
-        key: string;
-        etag?: string;
-    }>>;
-    download(key: string): Promise<Result<Blob>>;
-    list(options?: ListOptions): Promise<Result<{
-        objects: readonly StorageObject[];
-        nextCursor?: string;
-    }>>;
-    remove(key: string): Promise<Result<{
-        key: string;
-    }>>;
-    /**
-     * Returns the canonical S3-style URL for an object. Pure URL-builder — no
-     * S3 round-trip — so this method intentionally bypasses the contract gate.
-     * Whether the URL is publicly fetchable depends on the bucket policy; for
-     * private buckets, use `getSignedDownloadUrl` instead.
-     */
-    getPublicUrl(key: string): Result<string>;
-    getSignedUploadUrl(key: string, options?: SignedUrlOptions): Promise<Result<SignedUrl>>;
-    getSignedDownloadUrl(key: string, options?: SignedUrlOptions): Promise<Result<SignedUrl>>;
-    private signUrl;
-    /**
-     * Resolves S3 settings, validates the user key, and prefixes it with
-     * `${agentId}/${bucketName}/`. Rejects path-traversal segments (`..`) so a
-     * caller-controlled key cannot escape the agent's namespace.
-     */
-    private resolve;
-}
-
-/**
- * Each accessor builds its module on first access and caches it — env vars
- * and partner SDK init costs are paid only when the agent actually touches
- * that surface.
+ * Each accessor builds its surface on first access and caches it — env
+ * vars and partner SDK init costs are paid only when the agent actually
+ * touches that surface.
+ *
+ * Capability gating: every surface listed in `MODULE_CAPABILITIES` builds
+ * its `ModuleGate` against the per-client `ContractStore` owned by this
+ * instance — two clients constructed in the same process do NOT share
+ * handshake cache or suppression-warning state. See
+ * `contract/capability-registry.ts` for the membership rule.
  */
 declare class StackboneClient {
     private readonly resolved;
     private _database?;
     private _storage?;
     private _ai?;
-    private _queues?;
     private _rag?;
-    private _memory?;
-    private _observability?;
     private _approval?;
     private _secrets?;
-    private _connections?;
     private _config?;
-    private _events?;
+    private _queues?;
+    private _memory?;
     private _prompts?;
     private _httpClient?;
+    private readonly _contractStore;
     constructor(resolved: ResolvedConfig);
     private http;
     get database(): DatabaseModule;
     get storage(): StorageModule;
     get ai(): AiModule;
-    get queues(): QueuesModule;
     get rag(): RagModule;
-    get memory(): MemoryModule;
-    get observability(): ObservabilityModule;
     get approval(): ApprovalFacade;
     get secrets(): SecretsFacade;
-    get connections(): ConnectionsFacade;
     get config(): ConfigFacade;
-    get events(): EventsFacade;
+    /**
+     * Live surface — the agent's handle on the BullMQ-backed job system.
+     * `publish` / `schedule` / `unschedule` / `listSchedules` make authenticated
+     * calls to the control-plane dispatcher (`/api/v1/agent/queues/*`); the
+     * agent never touches Redis. Gated against `queues.jobs` so the
+     * handshake-blocked / capability-missing paths are exercised the same way
+     * as the other gated surfaces.
+     */
+    get queues(): QueuesModule;
+    /**
+     * Pending surface — runtime not built. Every method returns
+     * `not_implemented`. Mem0 is a third-party integration, not a Stackbone
+     * Agent Protocol capability, so this surface is intentionally not gated.
+     */
+    get memory(): MemoryModule;
+    /**
+     * Live agent-local surface — reads prompts from `stackbone_platform.prompts`
+     * in the agent DB over the shared `client.database` pool and compiles
+     * templates with the local `@stackbone/prompt-compiler`. Constructed with
+     * the same `(resolved, () => this.database)` shape as `secrets`/`config`;
+     * like them it is NOT wired to the control-plane handshake gate (it talks to
+     * the agent's own tables, not a control-plane datapath).
+     */
     get prompts(): PromptsFacade;
     /**
      * Read-only view of the most recently resolved Stackbone Agent Protocol
@@ -1375,9 +1584,466 @@ declare class StackboneClient {
      * handshake has resolved successfully (the handshake fires lazily on the
      * first gated module call — slices #4/#5). Synchronous, never throws,
      * performs no fetches.
+     *
+     * Backed by this client's own `ContractStore`, so two `StackboneClient`
+     * instances see independent `client.contract` views even when they point
+     * at the same baseUrl.
      */
     get contract(): ContractResponse | null;
 }
 declare function createClient(config?: ClientConfig): StackboneClient;
 
-export { type AddMemoryRequest, type AggregateRunCostOptions, type AggregateRunCostResult, type ApprovalListOptions, type ApprovalListResult, type ApprovalRecord, type ApprovalRequest, type ApprovalRequestOptions, type ApprovalStatus, type ApprovalTool, type ApprovalToolSpec, type ApprovalTopic, type ApproverInfo, type ChunkOptions, type ChunkStrategy, type ClientConfig, type CreatePromptRequest, type Decision, type DecisionStatus, type DeleteAllMemoryRequest, type DeleteOptions, type DeletePromptOptions, type DeletePromptResult, type DeleteResponse, type EndSessionOptions, type EndSessionResult, type GeneratedImage, type GetPromptOptions, type ImageGenerateParams, type ImagesResponse, type IngestAsyncHandle, type IngestChunk, type IngestRequest, type IngestRequestAutoEmbed, type IngestRequestPrecomputed, type IngestResponse, LOG_LEVELS, type ListMemoryRequest, type ListMemoryResult, type ListOptions, type ListPromptsOptions, type ListPromptsResult, type LogLevelName, type LogLevelNumber, type LogRecord, type MemoryContent, type MemoryHistoryEntry, type MemoryHistoryEvent, type MemoryHit, type MemoryItem, type MemoryScope, type ModelsListResponse, type OpenRouterModel, type ParseInput, type ParseOptions, type PinoLike, type PlatformLogger, type PlatformLoggerMode, type PlatformLoggerOptions, type PostgresLike, type Prompt, type PublishRequest, RUN_ID_ATTRIBUTE, RUN_STEP_TYPES, type RagIngestProgress, type ReadableSpanLike, type Result, type RetrieveHit, type RetrieveRequest, type RetrieveRequestAutoEmbed, type RetrieveRequestPrecomputed, type RunStepType, RunStepsSpanProcessor, type RunStepsSpanProcessorOptions, STEP_TYPE_ATTRIBUTE, type SdkError, type SearchMemoryOptions, type SignedUrl, type SignedUrlOptions, type SpanContextLike, StackboneClient, type StorageBody, type StorageObject, type UpdateMemoryOptions, type UpdatePromptOptions, type UploadOptions, type VerifyOptions, aggregateRunCost, createClient, createPlatformLogger, defaultRunsDir };
+/**
+ * Structured fields the wrapper, an upstream consumer, or a handler can
+ * attach to a single log line. Values are `unknown` because the wrapper
+ * does not enforce a schema — the destination decides how to serialise
+ * each value.
+ */
+type LoggerBindings = Record<string, unknown>;
+/**
+ * The handler-facing logger. Every method takes a human-readable message
+ * plus an optional bag of structured fields the destination merges with
+ * the bindings already set by the wrapper (typically `invocationId` and
+ * `runId`).
+ *
+ * F5 wired the binding contract only; F6 replaces the stub implementation
+ * with the JSON/STACKBONE_MODE-aware variant. Keeping the surface here
+ * (instead of in the CLI) lets the SDK ship a typed seam creators can
+ * reference from their own tests.
+ */
+interface Logger {
+    /** Fine-grained diagnostic information. */
+    debug(msg: string, meta?: LoggerBindings): void;
+    /** Routine progress information. */
+    info(msg: string, meta?: LoggerBindings): void;
+    /** Recoverable problem the handler still resolved. */
+    warn(msg: string, meta?: LoggerBindings): void;
+    /** Unrecoverable failure the handler is about to report. */
+    error(msg: string, meta?: LoggerBindings): void;
+    /**
+     * Returns a new logger that merges `bindings` into every subsequent
+     * log line. The original logger is left untouched.
+     */
+    child(bindings: LoggerBindings): Logger;
+}
+/**
+ * Minimal writable surface the structured logger drains into. Both
+ * `process.stdout` and arbitrary test doubles satisfy it — every consumer
+ * only needs `write(string): unknown`.
+ */
+interface LogSink {
+    write(chunk: string): unknown;
+}
+interface StructuredLoggerOptions {
+    /** Output stream. Defaults to `process.stdout` for production use. */
+    stream?: LogSink;
+    /** Initial bindings every line inherits (e.g. process-wide metadata). */
+    bindings?: LoggerBindings;
+    /** Clock seam for the `ts` field. Defaults to `() => new Date()`. */
+    now?: () => Date;
+}
+/**
+ * Builds a structured `Logger` that emits one NDJSON line per call. Output
+ * shape is fixed by the wrapper PRD: `{ ts, level, msg, ...bindings,
+ * ...meta }`. The wrapper layers extra fields on top via `child()`
+ * (`invocationId`, `runId`, `latencyMs`, `status`).
+ */
+declare const createStructuredLogger: (opts?: StructuredLoggerOptions) => Logger;
+
+/**
+ * The data the wrapper hands to the creator's `run` function. F5 widens the
+ * shape from F1's bare `{ input }` to the full per-invocation context:
+ *
+ *   - `signal` is a fresh `AbortSignal` per invocation. The wrapper aborts
+ *     it when the deadline expires; the handler is expected to honour it
+ *     on cancellable work (fetches, DB queries, model calls).
+ *   - `invocationId` / `runId` come straight from the parsed envelope.
+ *   - `client` is the **same** `StackboneClient` instance for every
+ *     invocation in the process, so sub-modules can keep their internal
+ *     pools warm.
+ *   - `logger` is a child of the wrapper's structured logger already
+ *     bound to `invocationId` and `runId`, so the handler does not have to
+ *     pass them on every line. The actual JSON format lands in F6.
+ */
+interface InvokeContext<I extends z.ZodType> {
+    input: z.infer<I>;
+    signal: AbortSignal;
+    invocationId: string;
+    runId: string;
+    client: StackboneClient;
+    logger: Logger;
+}
+/**
+ * The synchronous `invoke` capability. Mirrors the wrapper's three HTTP verbs
+ * (`/invoke`, `/health`, `/schema`): `invoke` is the only request path, its
+ * `output` is the `/invoke` response body, and its schemas drive `/schema`.
+ *
+ * The fields are deliberately enumerated (no `[k: string]: unknown` escape
+ * hatch) so the precise type the creator gets from `defineAgent` rejects
+ * unknown keys on the block at compile time.
+ */
+interface InvokeCapability<I extends z.ZodType, O extends z.ZodType> {
+    /** Zod schema for the parsed `/invoke` request body. */
+    input: I;
+    /** Zod schema for the `/invoke` response body. */
+    output: O;
+    /** Creator-supplied handler. Returns either the parsed output or a promise of it. */
+    run: (ctx: InvokeContext<I>) => z.infer<O> | Promise<z.infer<O>>;
+    /** Optional per-invocation timeout in milliseconds. */
+    timeoutMs?: number;
+}
+/**
+ * A named **job handler** — a sibling of `invoke` at the top level of the spec,
+ * reached asynchronously via `client.queues.publish({ name })` (the BullMQ
+ * dispatcher pushes the job back to `/invoke` with that name; the wrapper routes
+ * it here instead of to `invoke.run`).
+ *
+ * Same shape as `invoke` with one difference: `output` is **optional**. A job is
+ * fire-and-forget — the dispatcher only checks the 2xx, the return value is
+ * journalled, not delivered to a caller. Declaring `output` self-validates the
+ * job's result; omitting it lets `run` return anything (or nothing).
+ */
+interface JobCapability<I extends z.ZodType, O extends z.ZodType = z.ZodType> {
+    /** Zod schema for the job payload (`publish`'s `payload`, revalidated here). */
+    input: I;
+    /** Optional Zod schema for the job's return value. Validated + journalled, never returned. */
+    output?: O;
+    /** Creator-supplied job handler. May return nothing — the result is not delivered. */
+    run: (ctx: InvokeContext<I>) => z.infer<O> | void | Promise<z.infer<O> | void>;
+    /** Optional per-job timeout in milliseconds. */
+    timeoutMs?: number;
+}
+/**
+ * Loose, non-generic view of a single capability (invoke or a job handler).
+ * The wrapper / `loadSpec` read the spec through this — the precise per-handler
+ * typing lives on the value `defineAgent` returns to the creator, not here.
+ *
+ * `run` is a method signature (not an arrow property) on purpose: it makes the
+ * parameter bivariant so every concrete `InvokeCapability` / `JobCapability`
+ * (whose `run` is typed against its own narrow input) is assignable to it, which
+ * is what lets `AgentSpec` carry a string index signature of capabilities.
+ */
+interface AnyCapability {
+    input: z.ZodType;
+    output?: z.ZodType | undefined;
+    run(ctx: InvokeContext<z.ZodType>): unknown;
+    timeoutMs?: number | undefined;
+}
+/**
+ * The declarative shape every Stackbone agent returns from `src/index.ts`, as
+ * the wrapper / `loadSpec` consume it: the **loose runtime view**. Every
+ * capability — `invoke` and each named job handler — is an `AnyCapability`
+ * (`output` optional, `run` loose). `invoke` is required; the string index
+ * carries the job handlers, reached by name through the BullMQ dispatcher.
+ *
+ * The precise per-handler typing (each `ctx.input` inferred, `invoke.output`
+ * required) lives on the value `defineAgent` returns, which is assignable to
+ * this. At runtime `invoke.output` is always present — the spec seed forces it —
+ * so the wrapper reads it behind a small guard.
+ */
+interface AgentSpec {
+    /** The synchronous entry: the `/invoke` response + the `GET /schema` source. */
+    invoke: AnyCapability;
+    /** Named job handlers, reached via `client.queues.publish({ name })`. */
+    [name: string]: AnyCapability;
+}
+/**
+ * Top-level keys the platform owns. A job handler may not use these names.
+ * Only `invoke` for now; the contract adds `health` / `schema` / `events` /
+ * `schedules` here if/when they become declarable capabilities (see the named
+ * job handlers ADR).
+ */
+declare const RESERVED_HANDLER_NAMES: readonly ["invoke"];
+/**
+ * Hard ceiling on any capability's `timeoutMs`. The platform saga kills the
+ * Machine before the wrapper would time out at higher values, so a creator
+ * declaring a 10-minute timeout would publish a contract the runtime cannot
+ * keep. Surface that conflict at boot instead of as a mysterious mid-invocation
+ * SIGKILL in production.
+ */
+declare const INVOKE_TIMEOUT_HARD_CAP_MS = 300000;
+/**
+ * One handler block, generic **directly** on its input Zod schema `I`. `input: I`
+ * is a single-level type parameter (not a nested indexed access like
+ * `S['input']`), which is the shape TypeScript can invert when reading the spec
+ * literal back — so every handler's `ctx.input` is inferred from its own schema.
+ * `output` stays loose (`z.ZodType`) and `run`'s return is `unknown`: a handler's
+ * result is validated against `output` at runtime (the wrapper), not at the type
+ * layer, so output inference is not needed for the contract to hold.
+ */
+type HandlerBlock<I extends z.ZodType> = {
+    input: I;
+    output?: z.ZodType;
+    run: (ctx: InvokeContext<I>) => unknown | Promise<unknown>;
+    timeoutMs?: number;
+};
+/**
+ * Per-key precise shape of the spec the creator writes. `T` maps each handler
+ * name to its **input** schema; `[K in keyof T]: HandlerBlock<T[K]>` is a
+ * homomorphic mapped type whose value (`input: T[K]`) is a single-level access,
+ * so TypeScript infers `T` back from the literal and keeps the concrete key
+ * names. The `& { invoke: ... }` arm makes `invoke` required and forces its
+ * `output` to be present (a job's `output` is optional).
+ */
+type AgentSpecParam<T extends Record<string, z.ZodType>> = {
+    [K in keyof T]: HandlerBlock<T[K]>;
+} & {
+    invoke: {
+        input: z.ZodType;
+        output: z.ZodType;
+    };
+};
+/**
+ * Anchor + guard for `defineAgent`:
+ *
+ * 1. **Inference anchor** — each handler (`invoke` and every named job) infers
+ *    its own `ctx.input` from its `input` schema. The creator never repeats a
+ *    type.
+ * 2. **Boot-time invariant** — `invoke` is required; every other top-level key
+ *    must be a valid handler object reached via `client.queues.publish({ name })`.
+ *    The TypeScript signature already shapes this; the runtime guard is the
+ *    safety net for creators forcing a shape through `as any`.
+ *
+ * Returns the spec verbatim so callers can `export default defineAgent({...})`
+ * and the wrapper can read the same object back through dynamic import.
+ */
+declare function defineAgent<T extends Record<string, z.ZodType>>(spec: AgentSpecParam<T>): {
+    [K in keyof T]: HandlerBlock<T[K]>;
+};
+
+interface InvocationContext {
+    /** The envelope's `invocationId` — surfaced on log lines as `trace_id`. */
+    readonly invocationId: string;
+    /** The run this invoke belongs to — surfaced on log lines as `run_id`. */
+    readonly runId: string;
+    /**
+     * The handler this invoke routed to — `invoke` for a direct entry or the
+     * named job handler (e.g. `demo-log-job`) the dispatcher delivered to.
+     * Surfaced on log lines as `handler` so the Studio logs trail can tell which
+     * entrypoint emitted each line. Optional so a caller that binds a context
+     * without routing info (older tests, lifecycle hooks) still type-checks.
+     */
+    readonly handler?: string;
+}
+/**
+ * Runs `fn` with `context` bound as the active invocation. The context stays
+ * available to every synchronous and asynchronous continuation rooted in this
+ * call (i.e. across `await`s inside `fn`). Returns whatever `fn` returns.
+ */
+declare function runWithInvocationContext<T>(context: InvocationContext, fn: () => T): T;
+/**
+ * Returns the active invocation context, or `undefined` when called outside any
+ * invoke (process boot, lifecycle events, tests that don't set one up).
+ */
+declare function getInvocationContext(): InvocationContext | undefined;
+
+/** The subset of the global `console` this bridge replaces. */
+interface ConsoleLike {
+    log: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+}
+interface InstallConsoleCaptureOptions {
+    /** Console object to patch. Defaults to the global `console`. Test seam. */
+    console?: ConsoleLike;
+    /** Sink for `log` / `info` / `debug`. Defaults to `process.stdout`. Test seam. */
+    stdout?: LogSink;
+    /** Sink for `warn` / `error`. Defaults to `process.stderr`. Test seam. */
+    stderr?: LogSink;
+    /** Clock for the `ts` field. Defaults to `() => new Date()`. Test seam. */
+    now?: () => Date;
+}
+/**
+ * Replaces `console.log/info/debug/warn/error` so that, while an invocation
+ * context is active, each call is re-emitted as a structured log line carrying
+ * `run_id` / `trace_id`. Returns a function that restores the originals.
+ * Calling it twice on the same console is a no-op (returns a no-op restore).
+ */
+declare function installInvocationConsoleCapture(options?: InstallConsoleCaptureOptions): () => void;
+
+declare const STORED_TO_SDK_ENV: Readonly<Record<string, string>>;
+/** Encrypted envelope row as stored in `stackbone_platform.secrets`. */
+interface SystemSecretRow {
+    name: string;
+    version: string;
+    nonce: Buffer | Uint8Array;
+    ciphertext: Buffer | Uint8Array;
+}
+/**
+ * Maps the `is_system` rows to the SDK env names, decrypting ONLY the rows that
+ * have a known mapping, then derives two env-only channels. Existing values are
+ * never overwritten (an explicit container/Machine override always wins). The
+ * SDK env names this call populated are returned (sorted) so the caller can log
+ * an observable, value-free "what got rehydrated" line — values are never
+ * logged. Shared by both the cloud neon reader and the postgres-js reader so
+ * they cannot drift on the mapping.
+ *
+ * Decryption is lazy on purpose: an unmapped stored row is skipped WITHOUT
+ * decrypting it, so a non-envelope row (e.g. a probe row a stubbed query
+ * returns) never throws. The two derived channels:
+ *   - `STACKBONE_POSTGRES_URL` from `databaseUrl` (the SDK's `client.database`
+ *     reads this name; the cloud harness's own Neon driver keeps `DATABASE_URL`).
+ *   - `STACKBONE_APPROVAL_SIGNING_KEY` from `HMAC_SECRET` so the SDK's approval
+ *     callback verifier reconciles with the signer (which signs with the same
+ *     boot-bundle HMAC).
+ */
+declare function rehydrateSystemSecretsRows(env: NodeJS.ProcessEnv, rows: readonly SystemSecretRow[], cipher: SecretCipher, databaseUrl: string): string[];
+/**
+ * Reads the `is_system` rows from `stackbone_platform.secrets`. Injectable so
+ * tests run against a stub without a real Postgres; production opens a
+ * short-lived `postgres-js` connection (see `loadSystemSecretsIntoEnv`).
+ */
+type SystemSecretsReader = () => Promise<SystemSecretRow[]>;
+interface LoadSystemSecretsArgs {
+    /** Connection string for the agent's Postgres (`STACKBONE_POSTGRES_URL`). */
+    readonly databaseUrl: string;
+    /** Per-agent base64 key the rows are decrypted with (`STACKBONE_SECRET_KEY`). */
+    readonly secretKey: string;
+    /** Target env to populate. Defaults to `process.env`. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Override the row reader (tests inject a stub). */
+    readonly reader?: SystemSecretsReader;
+}
+/**
+ * Reads every `is_system` row from the agent's Postgres via `postgres-js`,
+ * decrypts each with the per-agent key, and rehydrates them into `env` under
+ * the SDK's expected names. Used by the `stackbone dev` emulator and the
+ * self-host runtime entry to give the agent the same credentials the cloud
+ * harness rehydrates — without depending on a Neon HTTP endpoint, which local
+ * dev does not have.
+ */
+declare function loadSystemSecretsIntoEnv(args: LoadSystemSecretsArgs): Promise<string[]>;
+
+/**
+ * Reserved error codes. Order is intentional: keep them flat (string) so
+ * the envelope JSON stays trivial to inspect.
+ *
+ * F2 owns `VALIDATION_ERROR` and `HANDLER_ERROR`. `TIMEOUT_ERROR` is
+ * declared here so the collision check is stable across slices — the F5
+ * timeout slice will start emitting it without needing to amend the
+ * envelope contract.
+ */
+declare const RESERVED_ERROR_CODES: readonly ["VALIDATION_ERROR", "HANDLER_ERROR", "TIMEOUT_ERROR"];
+type ReservedErrorCode = (typeof RESERVED_ERROR_CODES)[number];
+/**
+ * HTTP header carrying `invocationId` so the dispatcher can correlate
+ * requests without parsing the JSON body.
+ */
+declare const INVOCATION_ID_HEADER = "X-Stackbone-Invocation-Id";
+/**
+ * HTTP header carrying `runId` so the dispatcher can correlate requests
+ * across approval callbacks, log lookups, and trace spans without parsing
+ * the JSON body.
+ */
+declare const RUN_ID_HEADER = "X-Stackbone-Run-Id";
+/**
+ * Envelope a client (the platform dispatcher, the local emulator, or a
+ * curl smoke test) sends to `POST /invoke`. `payload` is unknown at this
+ * layer — the wrapper revalidates it against `spec.invoke.input` before
+ * handing it to the creator's `run`.
+ */
+declare const invokeRequestSchema: z.ZodObject<{
+    invocationId: z.ZodString;
+    runId: z.ZodString;
+    payload: z.ZodUnknown;
+}, z.core.$strip>;
+type InvokeRequest = z.infer<typeof invokeRequestSchema>;
+/**
+ * Error portion of a failure envelope. `issues` mirrors Zod's `ZodIssue[]`
+ * shape verbatim so the dispatcher can render the same field-level paths
+ * an SDK consumer would see locally.
+ */
+interface InvokeEnvelopeError {
+    code: string;
+    message: string;
+    issues?: z.ZodIssue[];
+}
+/**
+ * Success envelope returned by `/invoke`. `TResult` is left generic so the
+ * wrapper can wrap the parsed output without paying for an extra type
+ * assertion at the call site.
+ */
+interface InvokeSuccessEnvelope<TResult = unknown> {
+    invocationId: string;
+    runId: string;
+    result: TResult;
+}
+/**
+ * Failure envelope returned by `/invoke`. Keeps `invocationId` and `runId`
+ * at the top level so a client can correlate a 4xx/5xx with the request
+ * without inspecting `error.issues`.
+ */
+interface InvokeErrorEnvelope {
+    invocationId: string;
+    runId: string;
+    error: InvokeEnvelopeError;
+}
+type InvokeResponse<TResult = unknown> = InvokeSuccessEnvelope<TResult> | InvokeErrorEnvelope;
+/**
+ * True when `code` is one of the reserved tokens the wrapper owns. Used by
+ * the duck-typed error path: a creator that throws an error tagged with a
+ * reserved code falls back to `HANDLER_ERROR` so reserved codes always
+ * mean what the platform expects.
+ */
+declare const isReservedErrorCode: (code: string) => code is ReservedErrorCode;
+
+/**
+ * Which half of the contract the diagnostic belongs to. The wrapper's error
+ * message names the half so the creator can find the offending field
+ * immediately ("input.user.email", not just "user.email").
+ */
+type SchemaHalf = 'input' | 'output';
+/**
+ * Constructs the wrapper either rejects outright or warns about. Listed
+ * verbatim so a future ADR can extend the union without changing the type
+ * shape downstream consumers rely on.
+ */
+type FatalConstruct = 'transform' | 'preprocess' | 'coerce';
+type WarnConstruct = 'refine' | 'lazy';
+interface SchemaDiagnostic<Construct extends string> {
+    half: SchemaHalf;
+    /** Dotted JSON pointer-ish path: `email`, `user.address.street`, `items[]`. */
+    path: string;
+    construct: Construct;
+}
+interface AgentSchemaPair {
+    input: z.ZodType;
+    output: z.ZodType;
+}
+interface SchemaIntrospectionResult {
+    fatal: SchemaDiagnostic<FatalConstruct>[];
+    warnings: SchemaDiagnostic<WarnConstruct>[];
+    schemas: {
+        input: JsonSchemaDocument;
+        output: JsonSchemaDocument;
+    };
+}
+/**
+ * JSON Schema 2020-12 document. We intentionally keep this loose — Zod's
+ * `toJSONSchema` returns an arbitrary structure and the wrapper only needs
+ * to serialise it verbatim to the catalog. A future ADR can tighten this
+ * to a generated type once the catalog has a real consumer.
+ */
+interface JsonSchemaDocument {
+    $schema?: string;
+    type?: string | string[];
+    properties?: Record<string, JsonSchemaDocument>;
+    required?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Walks the agent's input/output schemas, classifies offending constructs,
+ * and emits the JSON Schema 2020-12 documents the wrapper serves from
+ * `GET /schema`. The function never throws — the caller decides what to do
+ * with the fatal list.
+ *
+ * Derivation runs through Zod's native `z.toJSONSchema`. We pass
+ * `unrepresentable: 'any'` so a `.refine()`-bearing string still surfaces as
+ * a string (the catalog drops the constraint, the wrapper still runs it at
+ * invoke time).
+ */
+declare const analyzeAgentSchemas: (pair: AgentSchemaPair) => SchemaIntrospectionResult;
+
+export { type AddMemoryRequest, type AgentSchemaPair, type AgentSpec, type AnyCapability, type ApprovalListOptions, type ApprovalListResult, type ApprovalRecord, type ApprovalRequest, type ApprovalRequestOptions, type ApprovalStatus, type ApprovalTool, type ApprovalToolSpec, type ApprovalTopic, type ApproverInfo, type ClientConfig, type CompilePromptResult, type ConsoleLike, type CreatePromptRequest, type Decision, type DecisionStatus, type DeleteAllMemoryRequest, type DeletePromptOptions, type DeletePromptResult, type EndSessionOptions, type EndSessionResult, type FatalConstruct, type GeneratedImage, type GetPromptOptions, INVOCATION_ID_HEADER, INVOKE_TIMEOUT_HARD_CAP_MS, type ImageGenerateParams, type ImagesResponse, type IngestAsyncHandle, type InstallConsoleCaptureOptions, type InvocationContext, type InvokeCapability, type InvokeContext, type InvokeEnvelopeError, type InvokeErrorEnvelope, type InvokeRequest, type InvokeResponse, type InvokeSuccessEnvelope, type JobCapability, type JsonSchemaDocument, type ListMemoryRequest, type ListMemoryResult, type ListOptions, type ListPromptsOptions, type ListPromptsResult, type LoadSystemSecretsArgs, type LogSink, type Logger, type LoggerBindings, type MemoryContent, type MemoryHistoryEntry, type MemoryHistoryEvent, type MemoryHit, type MemoryItem, type MemoryScope, type ModelsListResponse, type OpenRouterModel, type Prompt, type PublishRequest, RESERVED_ERROR_CODES, RESERVED_HANDLER_NAMES, RUN_ID_HEADER, type ReservedErrorCode, type Result, STORED_TO_SDK_ENV, type ScheduleRequest, type SchemaDiagnostic, type SchemaHalf, type SchemaIntrospectionResult, type SdkError, type SdkErrorCode, type SearchMemoryOptions, type SignedUrl, type SignedUrlOptions, StackboneClient, type StorageBody, type StorageObject, type StructuredLoggerOptions, type SystemSecretRow, type SystemSecretsReader, type UnscheduleRequest, type UpdateMemoryOptions, type UpdatePromptOptions, type UploadOptions, type VerifyOptions, type WarnConstruct, analyzeAgentSchemas, createClient, createStructuredLogger, defineAgent, getInvocationContext, installInvocationConsoleCapture, invokeRequestSchema, isReservedErrorCode, isSdkErrorCode, loadSystemSecretsIntoEnv, rehydrateSystemSecretsRows, runWithInvocationContext };