@stackbone/sdk 0.1.0-alpha.1 → 0.1.0-alpha.3

package/index.d.cts

@@ -1,14 +1,19 @@
 import { ContractResponse } from '@stackbone/validators';
+import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+import { Sql } from 'postgres';
 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 { RunStepsSpanProcessorOptions, RunStepsSpanProcessor, PlatformLoggerOptions, PlatformLogger, AggregateRunCostResult } from './observability/index.cjs';
 import { S3Client } from '@aws-sdk/client-s3';
+import { z } from 'zod';
+export { z } from 'zod';
 
 /**
  * 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`. */
@@ -86,22 +91,245 @@ 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 `client.observability`. */
+    readonly databaseUrl: 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` — control-plane facade plus the HMAC verify helper.
+     * The transport-driven codes (`unauthorized`, `forbidden`, ...) come from
+     * `HttpClient`'s status→domain remap with `prefix: 'approval'`; the
+     * verify-specific codes (`invalid_signature`, etc.) are emitted locally.
+     */
+    readonly approval: readonly ["forbidden", "invalid_payload", "invalid_request", "invalid_response", "invalid_signature", "not_found", "rate_limited", "signature_expired", "signing_key_missing", "timeout", "tool_execute_failed", "unauthorized", "unavailable"];
+    /**
+     * `client.secrets` — control-plane facade. Almost entirely transport-
+     * driven (HttpClient remap with `prefix: 'secrets'`); the local codes are
+     * the request-shape rail.
+     */
+    readonly secrets: readonly ["already_exists", "forbidden", "invalid_request", "invalid_response", "not_found", "rate_limited", "timeout", "unauthorized", "unavailable"];
+    /**
+     * `client.config` — symmetric to `secrets`, points at `/api/config`.
+     */
+    readonly config: readonly ["forbidden", "invalid_request", "invalid_response", "not_found", "rate_limited", "timeout", "unauthorized", "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"];
+    /**
+     * `client.observability` — only the run-cost rollup emits a domain code
+     * today; 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,364 +354,198 @@ 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;
+};
 
-interface ApprovalToolSpec<I, O> {
-    name: string;
-    description: string;
-    parameters: Record<string, unknown>;
-    needsApproval?: boolean | ((input: I) => boolean | Promise<boolean>);
+/**
+ * `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, 
     /**
-     * Maps the LLM input to the approval request fields. `topic` and `payload`
-     * default to the tool name and the raw input respectively when omitted;
-     * `onDecide` must always be supplied so the control plane knows where to
-     * deliver the eventual decision.
+     * 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.
      */
-    toRequest: (input: I) => Omit<ApprovalRequestOptions<I>, 'payload' | 'topic'> & Partial<Pick<ApprovalRequestOptions<I>, 'payload' | 'topic'>>;
-    execute: (input: I) => Promise<O> | O;
+    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 OpenAIToolSpec {
-    type: 'function';
-    function: {
-        name: string;
-        description: string;
-        parameters: Record<string, unknown>;
+
+/**
+ * Public surface behind `client.ai`. Wraps the official `openai` SDK with a
+ * `baseURL` override pointing to OpenRouter, so 300+ models are reachable
+ * with a single, OpenAI-compatible API.
+ *
+ * Lazy: the underlying `OpenAI` client is built on the first method call
+ * (or the first time a sub-namespace is touched) so env vars mutated after
+ * `createClient()` are still picked up — same pattern as `DatabaseModule`.
+ *
+ * Error model: every method returns `Result<T>`. Upstream `APIError`s are
+ * mapped to `SdkError` with stable `ai_*` codes. For streaming, the
+ * `Result` envelope only covers connection establishment; once the stream
+ * is open, mid-flight errors propagate through the iterator — callers must
+ * wrap their `for await` loop in `try/catch`. Aborts via `signal.abort()`
+ * surface as `ai_aborted` in non-streaming requests; in streaming, the
+ * iterator simply terminates (the upstream SDK swallows the abort).
+ *
+ * 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 —
+ * 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;
+    private _openai;
+    private _chat;
+    private _embeddings;
+    private _images;
+    private _models;
+    private readonly _gate;
+    constructor(_resolved: ResolvedConfig, clientOverride?: OpenAI, 
+    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
+    gate?: ModuleGate);
+    get chat(): {
+        completions: ChatCompletionsNamespace;
     };
+    get embeddings(): EmbeddingsNamespace;
+    get images(): ImagesNamespace;
+    get models(): ModelsNamespace;
+    /**
+     * 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>;
 }
-type ToolInvokeResult<O> = {
-    status: 'pending';
-    approvalId: string;
-    expiresAt: string;
-} | {
-    status: 'ok';
-    result: O;
-};
-interface ApprovalTool<I, O> {
-    name: string;
-    description: string;
-    parameters: Record<string, unknown>;
-    openaiSpec(): OpenAIToolSpec;
-    invoke(input: I): Promise<Result<ToolInvokeResult<O>>>;
+declare class ChatCompletionsNamespace {
+    private readonly _getClient;
+    private readonly _gate;
+    constructor(_getClient: () => Result<OpenAI>, _gate: ModuleGate);
+    create(params: ChatCompletionCreateParamsStreaming, options?: RequestOptions$1): Promise<Result<Stream<ChatCompletionChunk>>>;
+    create(params: ChatCompletionCreateParamsNonStreaming, options?: RequestOptions$1): Promise<Result<ChatCompletion>>;
 }
-
-interface VerifyOptions {
-    /** Override the signing key resolved from `STACKBONE_APPROVAL_SIGNING_KEY` / `approvalSigningKey`. */
-    signingKey?: string;
-    /** Reject signatures whose timestamp is older than this (seconds). Default 300. */
-    toleranceSeconds?: number;
-    /** Inject a clock for tests. Defaults to `Date.now`. */
-    now?: () => number;
-}
-
-type ApprovalTopic = string;
-declare const DECISION_STATUSES: readonly ["approved", "rejected", "timed_out", "cancelled"];
-type DecisionStatus = (typeof DECISION_STATUSES)[number];
-type ApprovalStatus = 'pending' | DecisionStatus;
-type Decision<T = unknown> = {
-    status: 'approved' | 'rejected';
-    payload: T;
-    approver: ApproverInfo;
-    decidedAt: string;
-    reason?: string;
-} | {
-    status: 'timed_out';
-    decidedAt: string;
-} | {
-    status: 'cancelled';
-    decidedAt: string;
-    reason?: string;
-};
-interface ApproverInfo {
-    id: string;
-    email: string;
-    name?: string;
-}
-interface ApprovalRequestOptions<T = unknown> {
-    topic: ApprovalTopic;
-    payload: T;
-    title?: string;
-    description?: string;
-    /** Path on the agent the control plane will POST the decision to (resolved against the agent's public URL server-side). */
-    onDecide: string;
-    /** ISO 8601 duration (`'24h'`) or milliseconds. Default 24h. */
-    timeout?: string | number;
-    onTimeout?: 'reject' | 'approve' | 'ignore';
-    approver?: string;
-    /** Same `(topic, idempotencyKey)` returns the same `approvalId` instead of creating a new one. */
-    idempotencyKey?: string;
-    metadata?: Record<string, unknown>;
-}
-interface ApprovalRequest {
-    approvalId: string;
-    status: 'pending';
-    callbackUrl: string;
-    expiresAt: string;
-}
-interface ApprovalRecord<T = unknown> {
-    approvalId: string;
-    topic: ApprovalTopic;
-    status: ApprovalStatus;
-    payload: T;
-    decision?: Decision<T>;
-    createdAt: string;
-    expiresAt: string;
-    metadata?: Record<string, unknown>;
-}
-interface ApprovalListOptions {
-    status?: ApprovalStatus;
-    topic?: ApprovalTopic;
-    cursor?: string;
-    /** 1..100. Default 50. */
-    limit?: number;
-}
-interface ApprovalListResult<T = unknown> {
-    items: ApprovalRecord<T>[];
-    nextCursor?: string;
-}
-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);
-    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.
-     */
-    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.
-     */
-    tool<I, O>(spec: ApprovalToolSpec<I, O>): ApprovalTool<I, O>;
-}
-
-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);
-    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>`).
-     */
-    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 workspace 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>>;
-}
-
-/**
- * A prompt managed by the Stackbone control plane. Templates are plain strings
- * with Mustache-style `{{var}}` placeholders — no conditionals or loops.
- */
-interface Prompt {
-    name: string;
-    template: string;
-    /** Monotonically increasing per `name`. The first `create` produces version `1`. */
-    version: number;
-    /** Variable names parsed from the template. */
-    variables?: readonly string[];
-    metadata?: Record<string, unknown>;
-    /** ISO 8601 UTC timestamp. */
-    createdAt: string;
-    updatedAt: string;
-}
-interface GetPromptOptions {
-    /** Pin a specific version. Omitted -> latest. */
-    version?: number;
-}
-interface ListPromptsOptions {
-    /** 1..100. Default 50. */
-    limit?: number;
-    cursor?: string;
-}
-interface ListPromptsResult {
-    /** Latest version of each prompt. */
-    items: readonly Prompt[];
-    nextCursor?: string;
-}
-interface CreatePromptRequest {
-    name: string;
-    template: string;
-    metadata?: Record<string, unknown>;
-}
-interface UpdatePromptOptions {
-    /** New template. Bumps `version` by one. */
-    template?: string;
-    /** Shallow-merged onto the existing metadata. */
-    metadata?: Record<string, unknown>;
-}
-interface DeletePromptOptions {
-    /** Delete a specific version. Omitted -> delete every version under `name`. */
-    version?: number;
-}
-interface DeletePromptResult {
-    name: string;
-    /** Number of versions actually removed. */
-    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>>;
-}
-
-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>>;
-    /**
-     * Names absent from the workspace 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.
-     */
-    getMany(names: string[]): Promise<Result<Record<string, string>>>;
-}
-
-/**
- * Public surface behind `client.ai`. Wraps the official `openai` SDK with a
- * `baseURL` override pointing to OpenRouter, so 300+ models are reachable
- * with a single, OpenAI-compatible API.
- *
- * Lazy: the underlying `OpenAI` client is built on the first method call
- * (or the first time a sub-namespace is touched) so env vars mutated after
- * `createClient()` are still picked up — same pattern as `DatabaseModule`.
- *
- * Error model: every method returns `Result<T>`. Upstream `APIError`s are
- * mapped to `SdkError` with stable `ai_*` codes. For streaming, the
- * `Result` envelope only covers connection establishment; once the stream
- * is open, mid-flight errors propagate through the iterator — callers must
- * wrap their `for await` loop in `try/catch`. Aborts via `signal.abort()`
- * surface as `ai_aborted` in non-streaming requests; in streaming, the
- * iterator simply terminates (the upstream SDK swallows the abort).
- *
- * 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.
- */
-declare class AiModule {
-    private readonly _resolved;
-    private _openai;
-    private _chat;
-    private _embeddings;
-    private _images;
-    private _models;
-    private readonly _gate;
-    constructor(_resolved: ResolvedConfig, clientOverride?: OpenAI, 
-    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
-    gate?: ModuleGate);
-    get chat(): {
-        completions: ChatCompletionsNamespace;
-    };
-    get embeddings(): EmbeddingsNamespace;
-    get images(): ImagesNamespace;
-    get models(): ModelsNamespace;
-    private client;
-}
-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>>;
-}
-declare class EmbeddingsNamespace {
-    private readonly _getClient;
-    private readonly _gate;
-    constructor(_getClient: () => Result<OpenAI>, _gate: ModuleGate);
-    create(params: EmbeddingCreateParams, options?: RequestOptions): Promise<Result<CreateEmbeddingResponse>>;
+declare class EmbeddingsNamespace {
+    private readonly _getClient;
+    private readonly _gate;
+    constructor(_getClient: () => Result<OpenAI>, _gate: ModuleGate);
+    create(params: EmbeddingCreateParams, options?: RequestOptions$1): Promise<Result<CreateEmbeddingResponse>>;
 }
 interface ImageGenerateParams {
     model: string;
@@ -520,7 +582,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,432 +612,12 @@ 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.
- */
-type DrizzleClient = PostgresJsDatabase<Record<string, never>> & {
-    $client: Sql;
-};
-
-/**
- * `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.
- *
- * 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 `./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.
- */
-declare class DatabaseModule {
-    private readonly _resolved;
-    private readonly _gate;
-    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'];
-    /**
-     * 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.
-     */
-    raw(): DrizzleClient;
-}
-
-/**
- * Where a memory lives. Default `'user'`. `'session'` is short-lived and
- * collapsed (or dropped) by `endSession()`; `'agent'` is shared across every
- * user of the agent.
- */
-type MemoryScope = 'user' | 'session' | 'agent';
-/**
- * Either raw text or an OpenAI-shaped conversation. The future mem0 backend
- * accepts both: strings ingest verbatim, message arrays are summarised into
- * one or more facts.
- */
-type MemoryContent = string | ChatCompletionMessageParam[];
-interface AddMemoryRequest {
-    userId: string;
-    /** Conversation/session bucket. Required when `scope: 'session'`. */
-    sessionId?: string;
-    /** Default `'user'`. */
-    scope?: MemoryScope;
-    metadata?: Record<string, unknown>;
-}
-interface MemoryItem {
-    id: string;
-    content: string;
-    userId: string;
-    sessionId?: string;
-    scope: MemoryScope;
-    metadata?: Record<string, unknown>;
-    /** ISO 8601 UTC timestamp. */
-    createdAt: string;
-    updatedAt: string;
-}
-interface SearchMemoryOptions {
-    userId?: string;
-    sessionId?: string;
-    /** 1..100. Default 10. */
-    limit?: number;
-    /** Minimum cosine similarity in [0, 1]. Hits below this are dropped. */
-    threshold?: number;
-    /** Metadata predicates AND-ed to the semantic match. */
-    filters?: Record<string, unknown>;
-    /** Restrict the search to a subset of scopes. Default: every scope. */
-    includeScopes?: readonly MemoryScope[];
-}
-interface MemoryHit extends MemoryItem {
-    /** Cosine similarity in [0, 1]. */
-    score: number;
-}
-interface ListMemoryRequest {
-    userId: string;
-    /** 1..100. Default 50. */
-    limit?: number;
-    cursor?: string;
-}
-interface ListMemoryResult {
-    items: readonly MemoryItem[];
-    nextCursor?: string;
-}
-interface UpdateMemoryOptions {
-    content?: string;
-    /** Shallow-merged onto the existing metadata (mem0 semantics). */
-    metadata?: Record<string, unknown>;
-}
-interface DeleteAllMemoryRequest {
-    userId: string;
-}
-type MemoryHistoryEvent = 'created' | 'updated' | 'accessed' | 'deleted';
-interface MemoryHistoryEntry {
-    id: string;
-    memoryId: string;
-    event: MemoryHistoryEvent;
-    /** ISO 8601 UTC timestamp. */
-    at: string;
-    /** Identifier of who triggered the event (user id, agent id, etc.). */
-    actor?: string;
-    /** Content snapshot before the event. Only set for `updated`/`deleted`. */
-    before?: string;
-    /** Content snapshot after the event. Only set for `created`/`updated`. */
-    after?: string;
-    metadata?: Record<string, unknown>;
-}
-interface EndSessionOptions {
-    /** Persist session-scoped facts to long-term (`'user'`) memory before closing. Default `true`. */
-    persist?: boolean;
-}
-interface EndSessionResult {
-    sessionId: string;
-    /** Number of session memories promoted to long-term storage. `0` when `persist: false`. */
-    persisted: number;
-}
-/**
- * `client.memory` — long-term memory for the agent. The first iteration is a
- * 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.
- */
-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[]>>;
-    delete(_memoryId: string): Promise<Result<{
-        id: string;
-    }>>;
-    deleteAll(_request: DeleteAllMemoryRequest): Promise<Result<{
-        deleted: number;
-    }>>;
-    get(_memoryId: string): Promise<Result<MemoryItem>>;
-    list(_request: ListMemoryRequest): Promise<Result<ListMemoryResult>>;
-    update(_memoryId: string, _options: UpdateMemoryOptions): Promise<Result<MemoryItem>>;
-    history(_memoryId: string): Promise<Result<readonly MemoryHistoryEntry[]>>;
-    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";
-/**
- * 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.
- */
-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 {
-    /**
-     * Postgres connection string of the install (local emulator at :5433 in
-     * dev, Neon TCP/HTTP URL in cloud). Falls back to `DATABASE_URL`.
-     */
-    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;
-}
-/**
- * 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.
- *
- * 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
- */
-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;
-    /**
-     * 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`.
-     */
-    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>;
-}
-/**
- * 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.
- */
-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>>;
-    /**
-     * 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.
-     */
-    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>;
-    /**
-     * 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.
-     */
-    closeRun(runId: string): Promise<Result<AggregateRunCostResult>>;
-    private resolveSql;
-}
-
-interface PublishRequest {
-    url: string;
-    body: unknown;
-    retries?: number;
-    delay?: number;
-    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`. */
@@ -1008,20 +650,67 @@ type RagIngestProgress = {
     jobId: string;
     error: string;
 };
-
-interface ParseOptions {
-    /** MIME type override. If omitted, the parser sniffs the input (Blob.type or PDF magic bytes). */
-    mime?: string;
+interface IngestJobStartArgs {
+    collection: string;
+    source: string;
+    totalChunks: number;
 }
-type ParseInput = Blob | string | Uint8Array | ArrayBuffer;
-
-interface IngestChunk {
-    content: string;
-    embedding: number[];
+interface IngestJobProgressArgs {
+    jobId: string;
+    processedChunks: number;
+    totalChunks: number;
+    currentDocument?: {
+        source: string;
+        ordinal: number;
+    };
 }
-interface IngestRequestBase {
-    /** Document identifier — re-ingesting with the same `id` replaces all its chunks atomically. */
-    id: string;
+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;
@@ -1111,23 +800,69 @@ interface IngestAsyncHandle {
  * configuration errors. See ADR `2026-05-10-rag-consolidation-on-client-database`.
  *
  * 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
+ * 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`.
+ * `STACKBONE_POSTGRES_URL`. RAG is the canonical first cross-surface
+ * consumer; memory and queues will adopt the same accessor when they
+ * land.
  *
  * 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.
  */
+/**
+ * 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;
-    constructor(_resolved: ResolvedConfig, _getAi: () => AiModule, 
+    private readonly _testSqlOverride?;
+    private readonly _testJobWriterFactory?;
+    constructor(_resolved: ResolvedConfig, 
+    /**
+     * 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);
+    gate?: ModuleGate, testDeps?: RagModuleTestDeps);
     ingest(request: IngestRequest): Promise<Result<IngestResponse>>;
     /**
      * Asynchronous ingest. Allocates a `stackbone_rag_jobs` row, returns the
@@ -1139,15 +874,12 @@ declare class RagModule {
      * 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`.
+     * 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>>;
-    /** Test-only seam — assigned by `ingest-async.spec.ts`. */
-    private _testJobWriter?;
-    /** Test-only seam — assigned by `ingest-async.spec.ts`. */
-    private _testSqlOverride?;
     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[]>>;
@@ -1169,158 +901,1071 @@ declare class RagModule {
      */
     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.
+     * 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.
+     * `Result.err` with the same `database_not_configured` shape
+     * `client.database` raises, instead of throwing through the public
+     * surface.
      */
     private sql;
     private withPipeline;
 }
 
-interface StorageObject {
-    key: string;
-    size: number;
-    lastModified?: Date;
-    etag?: string;
+/** Subset of `RequestInit['body']` we serialize without modification. */
+type SerializedBody = NonNullable<RequestInit['body']>;
+/**
+ * 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.
+ */
+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>;
+    /**
+     * 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.
+     */
+    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;
+}
+/**
+ * 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.
+ *
+ * `arrayParams` keys default to `errorMapping.prefix` for the validation
+ * error code (e.g. an empty `names: []` becomes `secrets_invalid_request`).
+ */
+interface TransportRequest<T> extends RequestOptions {
+    method: string;
+    path: string;
+    /**
+     * 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`.
+     */
+    responseSchema?: ResponseSchema<T>;
+    /** HTTP→domain remapping. Omit to let `http_*` codes flow through unchanged. */
+    errorMapping?: ErrorMapping;
+}
+/**
+ * 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.
+ */
+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);
+    /**
+     * Convenience for `request({ method: 'GET', path, ... })`. Kept so legacy
+     * callers (tests, pending facades) keep compiling — the deep work happens
+     * in `request()`.
+     */
+    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>>;
+    /**
+     * 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.
+     */
+    request<T>(req: TransportRequest<T>): Promise<Result<T>>;
+    private computeBackoff;
+}
+
+interface ApprovalToolSpec<I, O> {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    needsApproval?: boolean | ((input: I) => boolean | Promise<boolean>);
+    /**
+     * Maps the LLM input to the approval request fields. `topic` and `payload`
+     * default to the tool name and the raw input respectively when omitted;
+     * `onDecide` must always be supplied so the control plane knows where to
+     * deliver the eventual decision.
+     */
+    toRequest: (input: I) => Omit<ApprovalRequestOptions<I>, 'payload' | 'topic'> & Partial<Pick<ApprovalRequestOptions<I>, 'payload' | 'topic'>>;
+    execute: (input: I) => Promise<O> | O;
+}
+interface OpenAIToolSpec {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+type ToolInvokeResult<O> = {
+    status: 'pending';
+    approvalId: string;
+    expiresAt: string;
+} | {
+    status: 'ok';
+    result: O;
+};
+interface ApprovalTool<I, O> {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    openaiSpec(): OpenAIToolSpec;
+    invoke(input: I): Promise<Result<ToolInvokeResult<O>>>;
+}
+
+interface VerifyOptions {
+    /** Override the signing key resolved from `STACKBONE_APPROVAL_SIGNING_KEY` / `approvalSigningKey`. */
+    signingKey?: string;
+    /** Reject signatures whose timestamp is older than this (seconds). Default 300. */
+    toleranceSeconds?: number;
+    /** Inject a clock for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+
+type ApprovalTopic = string;
+declare const DECISION_STATUSES: readonly ["approved", "rejected", "timed_out", "cancelled"];
+type DecisionStatus = (typeof DECISION_STATUSES)[number];
+type ApprovalStatus = 'pending' | DecisionStatus;
+type Decision<T = unknown> = {
+    status: 'approved' | 'rejected';
+    payload: T;
+    approver: ApproverInfo;
+    decidedAt: string;
+    reason?: string;
+} | {
+    status: 'timed_out';
+    decidedAt: string;
+} | {
+    status: 'cancelled';
+    decidedAt: string;
+    reason?: string;
+};
+interface ApproverInfo {
+    id: string;
+    email: string;
+    name?: string;
+}
+interface ApprovalRequestOptions<T = unknown> {
+    topic: ApprovalTopic;
+    payload: T;
+    title?: string;
+    description?: string;
+    /** Path on the agent the control plane will POST the decision to (resolved against the agent's public URL server-side). */
+    onDecide: string;
+    /** ISO 8601 duration (`'24h'`) or milliseconds. Default 24h. */
+    timeout?: string | number;
+    onTimeout?: 'reject' | 'approve' | 'ignore';
+    approver?: string;
+    /** Same `(topic, idempotencyKey)` returns the same `approvalId` instead of creating a new one. */
+    idempotencyKey?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ApprovalRequest {
+    approvalId: string;
+    status: 'pending';
+    callbackUrl: string;
+    expiresAt: string;
+}
+interface ApprovalRecord<T = unknown> {
+    approvalId: string;
+    topic: ApprovalTopic;
+    status: ApprovalStatus;
+    payload: T;
+    decision?: Decision<T>;
+    createdAt: string;
+    expiresAt: string;
+    metadata?: Record<string, unknown>;
+}
+interface ApprovalListOptions {
+    status?: ApprovalStatus;
+    topic?: ApprovalTopic;
+    cursor?: string;
+    /** 1..100. Default 50. */
+    limit?: number;
+}
+interface ApprovalListResult<T = unknown> {
+    items: ApprovalRecord<T>[];
+    nextCursor?: string;
+}
+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);
+    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.
+     */
+    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.
+     */
+    tool<I, O>(spec: ApprovalToolSpec<I, O>): ApprovalTool<I, O>;
+}
+
+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);
+    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>`).
+     */
+    getMany<T extends Record<string, unknown> = Record<string, unknown>>(keys: string[]): Promise<Result<Partial<T>>>;
+}
+
+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>>;
+    /**
+     * 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.
+     */
+    getMany(names: string[]): Promise<Result<Record<string, string>>>;
+}
+
+/**
+ * `client.observability` — span processor + per-run JSONL/OTLP logger +
+ * run-cost rollup. Local mode writes JSONL to `~/.stackbone/dev/runs/`; cloud
+ * mode forwards OTLP/HTTP to the collector.
+ *
+ * Contract gating: not gated. Local writes touch the filesystem (no
+ * Stackbone wire surface) and cloud writes go to OpenTelemetry, not the
+ * Stackbone Agent Protocol — so there is no `Capability` to assert against.
+ * No entry in `MODULE_CAPABILITIES` per the rule documented in
+ * `contract/capability-registry.ts`.
+ */
+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>>;
+    /**
+     * 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.
+     */
+    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>;
+    /**
+     * 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.
+     */
+    closeRun(runId: string): Promise<Result<AggregateRunCostResult>>;
+    private resolveSql;
+}
+
+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;
+    }>>;
+    /**
+     * 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;
+}
+
+/**
+ * OAuth connections (Notion, GDrive, Slack…).
+ *
+ * Contract gating: not gated. The OAuth surface targets third-party
+ * providers, not the Stackbone Agent Protocol, so there is no entry in
+ * `MODULE_CAPABILITIES` (see `contract/capability-registry.ts`). When the
+ * runtime lands and a Stackbone-mediated capability shows up (e.g. control
+ * plane OAuth broker), we add the row and wire the gate.
+ */
+declare class ConnectionsFacade {
+    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>>;
+}
+
+/**
+ * Where a memory lives. Default `'user'`. `'session'` is short-lived and
+ * collapsed (or dropped) by `endSession()`; `'agent'` is shared across every
+ * user of the agent.
+ */
+type MemoryScope = 'user' | 'session' | 'agent';
+/**
+ * Either raw text or an OpenAI-shaped conversation. The future mem0 backend
+ * accepts both: strings ingest verbatim, message arrays are summarised into
+ * one or more facts.
+ */
+type MemoryContent = string | ChatCompletionMessageParam[];
+interface AddMemoryRequest {
+    userId: string;
+    /** Conversation/session bucket. Required when `scope: 'session'`. */
+    sessionId?: string;
+    /** Default `'user'`. */
+    scope?: MemoryScope;
+    metadata?: Record<string, unknown>;
+}
+interface MemoryItem {
+    id: string;
+    content: string;
+    userId: string;
+    sessionId?: string;
+    scope: MemoryScope;
+    metadata?: Record<string, unknown>;
+    /** ISO 8601 UTC timestamp. */
+    createdAt: string;
+    updatedAt: string;
+}
+interface SearchMemoryOptions {
+    userId?: string;
+    sessionId?: string;
+    /** 1..100. Default 10. */
+    limit?: number;
+    /** Minimum cosine similarity in [0, 1]. Hits below this are dropped. */
+    threshold?: number;
+    /** Metadata predicates AND-ed to the semantic match. */
+    filters?: Record<string, unknown>;
+    /** Restrict the search to a subset of scopes. Default: every scope. */
+    includeScopes?: readonly MemoryScope[];
+}
+interface MemoryHit extends MemoryItem {
+    /** Cosine similarity in [0, 1]. */
+    score: number;
+}
+interface ListMemoryRequest {
+    userId: string;
+    /** 1..100. Default 50. */
+    limit?: number;
+    cursor?: string;
+}
+interface ListMemoryResult {
+    items: readonly MemoryItem[];
+    nextCursor?: string;
+}
+interface UpdateMemoryOptions {
+    content?: string;
+    /** Shallow-merged onto the existing metadata (mem0 semantics). */
+    metadata?: Record<string, unknown>;
+}
+interface DeleteAllMemoryRequest {
+    userId: string;
+}
+type MemoryHistoryEvent = 'created' | 'updated' | 'accessed' | 'deleted';
+interface MemoryHistoryEntry {
+    id: string;
+    memoryId: string;
+    event: MemoryHistoryEvent;
+    /** ISO 8601 UTC timestamp. */
+    at: string;
+    /** Identifier of who triggered the event (user id, agent id, etc.). */
+    actor?: string;
+    /** Content snapshot before the event. Only set for `updated`/`deleted`. */
+    before?: string;
+    /** Content snapshot after the event. Only set for `created`/`updated`. */
+    after?: string;
+    metadata?: Record<string, unknown>;
+}
+interface EndSessionOptions {
+    /** Persist session-scoped facts to long-term (`'user'`) memory before closing. Default `true`. */
+    persist?: boolean;
+}
+interface EndSessionResult {
+    sessionId: string;
+    /** Number of session memories promoted to long-term storage. `0` when `persist: false`. */
+    persisted: number;
+}
+/**
+ * `client.memory` — long-term memory for the agent. The first iteration is a
+ * 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 {
+    constructor(_resolved: ResolvedConfig);
+    add(_content: MemoryContent, _request: AddMemoryRequest): Promise<Result<MemoryItem>>;
+    search(_query: string, _options?: SearchMemoryOptions): Promise<Result<readonly MemoryHit[]>>;
+    delete(_memoryId: string): Promise<Result<{
+        id: string;
+    }>>;
+    deleteAll(_request: DeleteAllMemoryRequest): Promise<Result<{
+        deleted: number;
+    }>>;
+    get(_memoryId: string): Promise<Result<MemoryItem>>;
+    list(_request: ListMemoryRequest): Promise<Result<ListMemoryResult>>;
+    update(_memoryId: string, _options: UpdateMemoryOptions): Promise<Result<MemoryItem>>;
+    history(_memoryId: string): Promise<Result<readonly MemoryHistoryEntry[]>>;
+    endSession(_sessionId: string, _options?: EndSessionOptions): Promise<Result<EndSessionResult>>;
+}
+
+/**
+ * A prompt managed by the Stackbone control plane. Templates are plain strings
+ * with Mustache-style `{{var}}` placeholders — no conditionals or loops.
+ */
+interface Prompt {
+    name: string;
+    template: string;
+    /** Monotonically increasing per `name`. The first `create` produces version `1`. */
+    version: number;
+    /** Variable names parsed from the template. */
+    variables?: readonly string[];
+    metadata?: Record<string, unknown>;
+    /** ISO 8601 UTC timestamp. */
+    createdAt: string;
+    updatedAt: string;
 }
-interface UploadOptions {
-    contentType?: string;
-    metadata?: Record<string, string>;
+interface GetPromptOptions {
+    /** Pin a specific version. Omitted -> latest. */
+    version?: number;
 }
-interface ListOptions {
-    prefix?: string;
-    /** Maximum number of objects to return per page. Must be > 0. */
+interface ListPromptsOptions {
+    /** 1..100. Default 50. */
     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 ListPromptsResult {
+    /** Latest version of each prompt. */
+    items: readonly Prompt[];
+    nextCursor?: string;
 }
-interface SignedUrl {
-    url: string;
-    expiresAt: Date;
+interface CreatePromptRequest {
+    name: string;
+    template: string;
+    metadata?: Record<string, unknown>;
 }
-type StorageBody = Blob | Uint8Array | string;
-interface S3Settings {
-    client: S3Client;
-    endpoint: string;
-    bucket: string;
-    agentId: string;
+interface UpdatePromptOptions {
+    /** New template. Bumps `version` by one. */
+    template?: string;
+    /** Shallow-merged onto the existing metadata. */
+    metadata?: Record<string, unknown>;
+}
+interface DeletePromptOptions {
+    /** Delete a specific version. Omitted -> delete every version under `name`. */
+    version?: number;
+}
+interface DeletePromptResult {
+    name: string;
+    /** Number of versions actually removed. */
+    deleted: number;
 }
 /**
- * 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.
+ * `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.
  *
- * 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.
+ * Contract gating: not gated yet. Prompts will eventually talk to the
+ * Stackbone control plane, but no `Capability` has been declared for it
+ * (no entry in `MODULE_CAPABILITIES` — see `contract/capability-registry.ts`).
+ * When the runtime lands we add the row (e.g. `prompts.read_write`) and
+ * wire the gate the same way `secrets` / `config` do.
  */
-declare class StorageModule {
-    private readonly _resolved;
-    private _s3;
+declare class PromptsFacade {
+    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 PublishRequest {
+    url: string;
+    body: unknown;
+    retries?: number;
+    delay?: number;
+    deduplicationId?: string;
+    headers?: Record<string, string>;
+}
+declare class QueuesModule {
     private readonly _gate;
-    constructor(_resolved: ResolvedConfig, 
+    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;
+    publish(_request: PublishRequest): Promise<Result<{
+        messageId: 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>>;
-    /**
-     * 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.
+ * 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:
+ *
+ * - `surfaces/agent-local/` — Postgres branch owned by the agent
+ *   (`database`, `rag`).
+ * - `surfaces/external/` — managed partner SDKs the SDK wraps directly
+ *   (`ai` / OpenRouter, `storage` / S3 + R2 / MinIO, `observability` /
+ *   OpenTelemetry).
+ * - `surfaces/control-plane/` — thin HTTP calls to Stackbone's control
+ *   plane (`approval`, `secrets`, `config`).
+ * - `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, prompts,
+ *   connections, events.
+ *
+ * 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 _queues?;
+    private _memory?;
     private _events?;
     private _prompts?;
+    private _connections?;
     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;
+    /**
+     * Pending surface — runtime not built. Every method returns
+     * `not_implemented` so MVP agent code can wire against the eventual
+     * contract today and switch over the day the backing runtime ships.
+     * Gated against `queues.pgmq` so the handshake-blocked / capability-
+     * missing paths are exercised the same way as the live 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;
+    /**
+     * Pending surface — runtime not built. Every method returns
+     * `not_implemented`. Gated against `events.bus` so handshake errors
+     * surface symmetrically with the other control-plane facades.
+     */
     get events(): EventsFacade;
+    /**
+     * Pending surface — runtime not built. Every method returns
+     * `not_implemented`. Will gate once a capability row is declared in
+     * `MODULE_CAPABILITIES`; until then it is intentionally ungated.
+     */
     get prompts(): PromptsFacade;
+    /**
+     * Pending surface — runtime not built. Returns an empty list today.
+     * Connections target third-party OAuth providers, not the Stackbone
+     * Agent Protocol, so this surface is intentionally not gated.
+     */
+    get connections(): ConnectionsFacade;
     /**
      * Read-only view of the most recently resolved Stackbone Agent Protocol
      * contract for this client's `stackboneApiUrl`. Returns `null` until a
      * 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 single `invoke` capability the creator exposes. Mirrors the wrapper's
+ * three HTTP verbs (`/invoke`, `/health`, `/schema`) — F1 lands only the
+ * invoke half; `/health` and `/schema` land in later slices.
+ *
+ * The fields are deliberately enumerated (no `[k: string]: unknown` escape
+ * hatch) so the parent `AgentSpec` can reject unknown keys at the type level
+ * via `keyof` checks downstream.
+ */
+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. Wired by a later slice. */
+    timeoutMs?: number;
+}
+/**
+ * The declarative shape every Stackbone agent returns from `src/index.ts`.
+ *
+ * `AgentSpec` is a closed object: the keys are listed explicitly so adding
+ * `{ invoke, anyOtherKey }` at the call site fails `tsc`. The corresponding
+ * runtime guard in `defineAgent` enforces the same invariant against callers
+ * that bypass the type system through `as any`.
+ *
+ * `health` and other capabilities will join `invoke` as they land — every
+ * addition is an explicit, reviewable edit to this type.
+ */
+interface AgentSpec<I extends z.ZodType, O extends z.ZodType> {
+    invoke: InvokeCapability<I, O>;
+}
+/**
+ * Hard ceiling on `invoke.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;
+/**
+ * Identity function with two jobs:
+ *
+ * 1. **Inference anchor** — pins the input/output Zod schemas so creators get
+ *    a fully typed `ctx.input` and a typed return value inside `run` without
+ *    repeating themselves.
+ * 2. **Boot-time invariant** — throws on any unknown top-level or invoke-block
+ *    key. This is the safety net for creators that force a shape through
+ *    `as any`; the type system already rejects this, but the wrapper PRD's
+ *    "impossible to break the contract from creator code" success criterion
+ *    requires the runtime check too.
+ *
+ * Returns the spec verbatim so callers can `export default defineAgent({...})`
+ * and the wrapper can read the same object back through dynamic import.
+ */
+declare const defineAgent: <I extends z.ZodType, O extends z.ZodType>(spec: AgentSpec<I, O>) => AgentSpec<I, O>;
+
+/**
+ * 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 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 FatalConstruct, type GeneratedImage, type GetPromptOptions, INVOCATION_ID_HEADER, INVOKE_TIMEOUT_HARD_CAP_MS, type ImageGenerateParams, type ImagesResponse, type IngestAsyncHandle, type IngestChunk, type IngestRequest, type IngestRequestAutoEmbed, type IngestRequestPrecomputed, type IngestResponse, type InvokeCapability, type InvokeContext, type InvokeEnvelopeError, type InvokeErrorEnvelope, type InvokeRequest, type InvokeResponse, type InvokeSuccessEnvelope, type JsonSchemaDocument, type ListMemoryRequest, type ListMemoryResult, type ListOptions, type ListPromptsOptions, type ListPromptsResult, type LogSink, type Logger, type LoggerBindings, type MemoryContent, type MemoryHistoryEntry, type MemoryHistoryEvent, type MemoryHit, type MemoryItem, type MemoryScope, type ModelsListResponse, type OpenRouterModel, type ParseInput, type ParseOptions, type Prompt, type PublishRequest, RESERVED_ERROR_CODES, RUN_ID_HEADER, type RagIngestProgress, type ReservedErrorCode, type Result, type RetrieveHit, type RetrieveRequest, type RetrieveRequestAutoEmbed, type RetrieveRequestPrecomputed, type SchemaDiagnostic, type SchemaHalf, type SchemaIntrospectionResult, type SdkError, type SdkErrorCode, type SearchMemoryOptions, type SignedUrl, type SignedUrlOptions, StackboneClient, type StorageBody, type StorageObject, type StructuredLoggerOptions, type UpdateMemoryOptions, type UpdatePromptOptions, type UploadOptions, type VerifyOptions, type WarnConstruct, analyzeAgentSchemas, createClient, createStructuredLogger, defineAgent, invokeRequestSchema, isReservedErrorCode, isSdkErrorCode };