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

package/CHANGELOG.md

@@ -7,6 +7,323 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- `ResolvedConfig` is now an opaque, typed snapshot — the live `env`
+  channel is gone. Every consumer used to read environment variables with
+  the pattern `resolved.config.fieldX ?? resolved.env['FIELDX']`, which
+  spread two pieces of knowledge across ~20 call sites: the exact env-var
+  name and the precedence rule. The resolver now owns both. After this
+  change, modules read typed fields like `resolved.stackboneApiUrl`,
+  `resolved.s3Bucket`, `resolved.databaseUrl`, `resolved.requireContract`,
+  etc. — none of them touch `process.env` directly.
+
+  The resolver is the **single** seam that reads `process.env` in the
+  library. New env-driven settings go in two places: a typed field on
+  `ResolvedConfig` and the matching `config.xxx ?? env['XXX']` (or parsing
+  logic) inside `resolveConfig`. The compiler then flags every consumer
+  that needs the new field.
+
+  Runtime knobs previously read inline from `contract/contract-handshake.ts`
+  (`STACKBONE_REQUIRE_CONTRACT`, `STACKBONE_CONTRACT_TTL_MS`,
+  `STACKBONE_DEBUG`) are now resolved up-front and threaded into the per-
+  client `ContractStore`. The database singleton in
+  `surfaces/agent-local/database/shared-handle.ts` takes an explicit
+  `connectionString` parameter that `DatabaseModule` pulls off
+  `resolved.databaseUrl`; the only remaining read of
+  `STACKBONE_POSTGRES_URL` is inside `resolveConfig`.
+
+  Booleans (`STACKBONE_DEBUG=1`) and numbers (`STACKBONE_CONTRACT_TTL_MS=30000`)
+  get parsed at resolve time, so consumers receive `boolean` / `number`,
+  not raw strings — one parse, one place, no drift.
+
+  Behavioural change worth flagging: `ResolvedConfig` is a snapshot, not
+  a live view. Tests that mutated `process.env` AFTER `createClient()` to
+  exercise late-binding behaviour now need to rebuild the client (or pass
+  the new value through the config object). The new `src/config.spec.ts`
+  pins both the snapshot semantics and the deletion contract — `.env` is
+  no longer a property on `ResolvedConfig`, and reading it is both a type
+  error and a runtime `undefined`. Two integration / handshake tests
+  (`STACKBONE_REQUIRE_CONTRACT=0`, `STACKBONE_CONTRACT_TTL_MS`,
+  `STACKBONE_DEBUG=1`) now construct a fresh `ContractStore` per env-var
+  variation to keep the resolve-once contract explicit.
+
+- `SdkError.code` is now a typed catalog (`SdkErrorCode`) declared in one
+  place — `src/errors/codes.ts`. Every literal `code` value that ships on a
+  `Result<T>` envelope (and the `errorMapping.prefix` slot on the transport)
+  is now compiler-checked against the catalog, so a future PR that adds
+  `secrets_not_foud` (typo) or `ai_provdier_down` (typo) fails to build
+  instead of silently shipping past the README contract. The catalog also
+  ties `HttpClient`'s `<prefix>_<reason>` projection to `SdkErrorPrefix`, so
+  a surface that wires `errorMapping: { prefix: '<unknown>' }` no longer
+  compiles. The wire-level shape of every code is unchanged: this is a
+  type-level constraint, not a rename.
+
+  Adding a new code is a single-file edit in `src/errors/codes.ts` (either
+  a new suffix under an existing prefix, or a freestanding code under
+  `SDK_ERROR_CODES_STANDALONE`). The compiler then flags every call site
+  that needs the new literal — and the new exhaustiveness test in
+  `src/lib/http-client.spec.ts` asserts every `<prefix>_<reason>` the
+  transport can emit is still a member of the catalog so README/code drift
+  fails loudly.
+
+  Two new symbols on the public barrel (`@stackbone/sdk`):
+  - `SdkErrorCode` — the union projection of the catalog. Use it as the
+    return type when you write a helper that produces an `SdkError`, or
+    as a discriminant in a `switch` over `result.error.code`.
+  - `isSdkErrorCode(raw: string)` — runtime narrowing for wire strings
+    that come from a decoded body. Returns `true` only when `raw` is a
+    catalog member; lets the SDK widen upstream errors safely.
+
+  RAG's `toRagError(cause, message, fallbackCode)` helper now constrains
+  `fallbackCode` to `SdkErrorCode` and checks `cause.code` against the
+  catalog before reusing it. The catalog and the helper are not folded
+  into one file — the catalog is the inventory, `toRagError` stays in the
+  RAG folder as a Postgres-tagged-error classifier.
+
+- Contract gating membership is now an explicit rule, and the handshake
+  cache no longer lives in a process-wide static. Two things changed:
+  1. **Membership rule (Option B from the audit)** — a surface gates iff
+     `MODULE_CAPABILITIES` (in `@stackbone/validators`) advertises a row
+     for its module id. `MODULE_CAPABILITIES` is now the single source of
+     truth: adding a surface to gating means adding a `Capability` and a
+     `<module>: '<capability>'` row first, then wiring
+     `createModuleGate('<module>', resolved, store)` in the surface
+     constructor. The new docstring at the top of
+     `contract/capability-registry.ts` spells out the rule and the steps.
+     Today's gated set stays the same (`database`, `rag`, `queues`,
+     `events`, `secrets`, `config`, `approval`, `storage`, `ai`). The
+     four ungated surfaces (`memory`, `connections`, `prompts`,
+     `observability`) now carry a one-paragraph comment on their class
+     header documenting **why** they are not gated — either the runtime
+     does not yet exist with a defined capability (`memory`,
+     `connections`, `prompts`) or the surface stays local / talks to
+     OpenTelemetry, not the Stackbone Agent Protocol (`observability`).
+
+  2. **Per-client handshake store** — the `ContractHandshake` static
+     namespace is gone. In its place: `createContractStore()` returns a
+     `ContractStore` with three methods (`get`, `peek`, `gatingEnabled`)
+     that owns its own cache, single-flight map, TTL eviction and debug
+     bookkeeping. `StackboneClient` instantiates exactly one store per
+     instance and threads it through every gated surface via
+     `createModuleGate(module, resolved, store)`. Two clients
+     constructed in the same process no longer share handshake cache or
+     suppression-warning state — including `client.contract`, which now
+     reads from the per-client store's `peek()`.
+
+  Removed test globals (the visible sign that the cache had escaped its
+  owner): `ContractHandshake.__resetForTests` and
+  `__resetModuleGateWarningsForTests`. Specs that previously called them
+  in `beforeEach`/`afterEach` now simply construct a fresh
+  `createContractStore()` (or, for client-level coverage, a fresh
+  `createClient(...)`); state isolation is intrinsic to construction.
+  `module-gate.spec.ts` gained two coverage tests for the new shape:
+  "two gates pinned to the same store share suppression-warning state"
+  and "two gates pinned to different stores warn independently". The E2E
+  suite (`integration/handshake.spec.ts`) loses its global-reset
+  bookkeeping entirely.
+
+  Wire protocol is unchanged: `GET /api/contract` returns the same JSON
+  shape, `client.contract` exposes the same read-only `ContractResponse |
+null` getter, gate-blocked calls still return the same `Result`
+  envelope with `capability_unavailable` / `contract_version_unsupported`
+  / `contract_unreachable` codes, and the `STACKBONE_REQUIRE_CONTRACT=0`
+  / `STACKBONE_CONTRACT_TTL_MS` / `STACKBONE_DEBUG=1` escape hatches
+  behave identically. Surface constructors keep the same `gate?:
+ModuleGate` test seam — only the internal default (now backed by a
+  per-client store instead of a static singleton) changed.
+
+- The cross-surface shared-handle seam is now an explicit, documented
+  pattern on the public surfaces. Two surfaces produce a reusable
+  resource and expose it through a canonical accessor:
+  - `client.database.shared(): DrizzleClient` — process-wide Drizzle
+    handle bound to `STACKBONE_POSTGRES_URL`. Same input → same
+    instance. `client.database.raw()` stays as the creator-facing
+    escape hatch and is now documented as an alias of `shared()`.
+  - `client.ai.shared(): Result<OpenAI>` — process-wide OpenRouter
+    `OpenAI` client used by every namespace under `client.ai`. Same
+    input → same instance; reflects the `clientOverride` injected at
+    construction time. The previous private `client()` accessor folded
+    into this public name.
+
+  These accessors are the **only** way cross-surface SDK consumers
+  should reach the shared pool / OpenAI client. RAG already consumed
+  the database pool via a module-private file (`database/internal.ts`)
+  — RAG now reaches it through `client.database.shared().$client`
+  instead. The renamed `database/shared-handle.ts` keeps the singleton
+  implementation but has zero sibling-relative importers outside its
+  own folder and its own spec; cross-surface friction (memory and
+  queues will need the same handles per the consolidation ADRs) now
+  has one named extension point instead of a per-consumer escape
+  hatch.
+
+  Public API of `client.database`, `client.ai`, and `client.rag` is
+  unchanged — method signatures and `Result` envelopes match the
+  previous release. `RagModule` constructor adds a
+  `() => DatabaseModule` accessor alongside the existing
+  `() => AiModule`, mirroring the wiring `client.ts` produces; tests
+  pass both verbatim.
+
+- **BREAKING** — Control-plane facades (`client.secrets`, `client.config`,
+  `client.approval`) now surface HTTP failures with surface-specific error
+  codes instead of the generic `http_*` family. The transport (`HttpClient`)
+  absorbs response validation, status→domain remapping, and querystring
+  serialisation, so a facade method now reads as "POST to /path with body X,
+  validate against schema Y, error prefix Z" instead of a 30–80 line
+  hand-rolled pipeline per surface. Migration is mechanical: pattern-match
+  the surface prefix instead of `http_*`.
+  - 401 → `<prefix>_unauthorized` (was `http_unauthorized`).
+  - 403 → `<prefix>_forbidden` (was `http_forbidden`).
+  - 404 → `<prefix>_not_found` (was `http_not_found`).
+  - 408 → `<prefix>_timeout` (was `http_timeout`).
+  - 429 → `<prefix>_rate_limited` (was `http_rate_limited`).
+  - 5xx → `<prefix>_unavailable` (was `http_server_error`).
+  - other 4xx → `<prefix>_invalid_request` (was `http_client_error`).
+  - schema-drift on a 2xx body → `<prefix>_invalid_response`.
+
+  The raw HTTP status stays accessible at `result.error.meta.status` for
+  callers that still want to pattern-match on the wire. Endpoint-specific
+  overrides (e.g. a POST whose `409` means "already exists") are wired by
+  facades via the new `errorOverrides` option on the transport request.
+
+  Transport-level errors (`http_timeout`, `http_aborted`,
+  `http_network_error`, `http_parse_error`, `http_request_failed`,
+  `http_invalid_response`, `http_invalid_request`) keep the `http_*`
+  prefix the README documents — they are not surface-specific.
+
+  Internal cleanup: `src/lib/facade-helpers.ts` is gone (the two utilities
+  it held — `remapHttpNotFound` and `validateStringArray` — were either
+  absorbed by the transport or relocated to `lib/http-client.ts` as a
+  named export). The per-method bodies on the control-plane facades
+  shrank substantially: `secrets.get` and `config.get` lost their
+  hand-rolled `value` type-checks and remap blocks, batch endpoints
+  pushed array validation + comma-join down to the transport, and the
+  approval list endpoint dropped its `pickDefinedAsStrings` helper for
+  the transport's built-in scalar coercion. File-level line counts barely
+  move because the public type definitions dominate each facade (notably
+  on `approval.ts` where 80+ lines are interface exports), but the
+  per-method logic now reads like the design target: "POST to /path,
+  validate against schema, error prefix is X".
+
+- **BREAKING** — Platform-side observability primitives moved off the main
+  `@stackbone/sdk` barrel and into a dedicated subpath entrypoint,
+  `@stackbone/sdk/observability`. The main barrel previously exposed both the
+  handler-scoped `createStructuredLogger` (the per-invocation `Logger` the
+  runtime injects into creator handlers) and the platform/run-scoped
+  `createPlatformLogger` factory side-by-side, with no signal about which
+  belonged to which audience. Creators only ever consume the run-scoped
+  surface through `client.observability.*` (the live accessors stay on
+  `StackboneClient` unchanged); only platform/runtime tooling and integration
+  tests need to construct the primitives directly. The symbols that moved:
+  - Per-run logger — `createPlatformLogger`, `LOG_LEVELS`, `defaultRunsDir`,
+    plus the types `LogLevelName`, `LogLevelNumber`, `LogRecord`, `PinoLike`,
+    `PlatformLogger`, `PlatformLoggerMode`, `PlatformLoggerOptions`.
+  - OTel span processor — `RunStepsSpanProcessor`, `RUN_STEP_TYPES`,
+    `RUN_ID_ATTRIBUTE`, `STEP_TYPE_ATTRIBUTE`, plus the types
+    `ReadableSpanLike`, `RunStepType`, `RunStepsSpanProcessorOptions`,
+    `SpanContextLike`, `PostgresLike`.
+  - Run-cost aggregator — `aggregateRunCost`, plus the types
+    `AggregateRunCostOptions`, `AggregateRunCostResult`.
+
+  Migration is mechanical:
+
+  ```ts
+  // Before
+  import { createPlatformLogger, RunStepsSpanProcessor } from '@stackbone/sdk';
+  // After
+  import { createPlatformLogger, RunStepsSpanProcessor } from '@stackbone/sdk/observability';
+  ```
+
+  The handler-scoped `createStructuredLogger`, `Logger`, `LoggerBindings`,
+  `LogSink` and `StructuredLoggerOptions` stay on the main `@stackbone/sdk`
+  barrel: those are the surface the runtime wrapper hands to creator
+  handlers via `InvokeContext.logger`. JSONL output shape, OTLP/HTTP/JSON
+  serialisation and `~/.stackbone/dev/runs/<runId>.jsonl` paths are
+  unchanged — only the import path moved.
+
+- **BREAKING** — SDK source tree reorganised under `src/surfaces/` by **where
+  each surface's state lives** instead of "wraps SDK vs makes HTTP fetch". The
+  old `src/modules/` and `src/facades/` directories are gone. New layout:
+  - `src/surfaces/agent-local/` — state in the agent's own Postgres
+    (`database`, `rag`).
+  - `src/surfaces/external/` — managed partner SDKs the SDK wraps directly
+    (`ai`, `storage`, `observability`).
+  - `src/surfaces/control-plane/` — thin HTTP calls to the Stackbone control
+    plane (`approval`, `secrets`, `config`).
+  - `src/surfaces/pending/` — surface types are exported but the runtime is
+    not built yet (`queues`, `memory`, `prompts`, `connections`, `events`).
+
+  Subpath entrypoints (`@stackbone/sdk/db`, `@stackbone/sdk/db/testing`,
+  `@stackbone/sdk/queues/types`, `@stackbone/sdk/rag/migrations`,
+  `@stackbone/sdk/rag/schema`) keep working — only the underlying file
+  paths moved.
+
+- The five pending surfaces (`queues`, `memory`, `prompts`, `connections`,
+  `events`) now live under `src/surfaces/pending/` and are exposed as live
+  `client.X` accessors that return `not_implemented` on every method. The
+  earlier draft of this refactor dropped the accessors entirely, but MVP
+  agent code needs to be authored against the eventual contract today and
+  switch over the day the backing runtime ships — keeping the getters as
+  placeholders makes that one-line change instead of a refactor. Public
+  types continue to ship from `@stackbone/sdk` (`PublishRequest`,
+  `MemoryItem`, `MemoryHit`, `Prompt`, `CreatePromptRequest`, …) so
+  creators can keep modelling integrations. `queues` and `events` go
+  through the contract gate (they are listed in `MODULE_CAPABILITIES`);
+  `memory`, `prompts` and `connections` are intentionally ungated.
+
+- **BREAKING** — `@stackbone/sdk/db/testing` `createTestDatabase` now spins up
+  a real Postgres container via `@testcontainers/postgresql` instead of
+  carving a random schema out of a shared dev DB. Callers no longer pass a
+  `connectionString`; pass an optional `image` (defaults to
+  `pgvector/pgvector:pg17`) if you need extensions beyond pgvector. Tests are
+  self-contained: no `docker compose up` ceremony, no `STACKBONE_*_POSTGRES_URL`
+  env, no schema bookkeeping. Aligns the SDK helper with the rest of the
+  monorepo (see `apps/api/src/db/__tests__/setup-postgres.ts`). Docker must
+  be running on the host.
+
+## [0.1.0-alpha.2] - 2026-05-18
+
+### Fixed
+
+- `client.rag.ingest` (batched mode, e.g. when an `onProgress` callback or a
+  `jobWriter` is wired): every chunk batch was wrapping its INSERT in a
+  transaction that first ran `DELETE FROM rag_chunks WHERE namespace=? AND
+doc_id=?`. With N batches per document, only the rows inserted by the LAST
+  batch survived — every earlier slice was wiped by the next batch's DELETE.
+  Split the DELETE into a single `clearDocument` call before the loop;
+  `ingestDocument` now only INSERTs its slice.
+- `client.rag` error mapping: `42P01 relation does not exist` was only
+  translated to `SdkError('rag_schema_missing')` from the pipeline path.
+  `reset()`, the database-handle resolver, and `client.rag.ingestAsync`'s job
+  writer used a divergent local copy of `toRagError` that surfaced the raw
+  Postgres code instead. Consolidated all three call sites onto a shared
+  `modules/rag/errors.ts` so the schema-missing hint is consistent.
+- `RunStepsSpanProcessor.stepIdBySpanId`: spans without a `stackbone.run.id`
+  attribute leaked their reservation in the map — `buildRow` returned early
+  before the cleanup line ran. Cleanup now happens unconditionally on every
+  `onEnd`, so dropped spans no longer accumulate.
+
+### Changed
+
+- OTLP log records sent by `createPlatformLogger` now carry the actual
+  installed SDK version under `scope.version`. Previously every record was
+  tagged with a hardcoded `'0.0.1'` regardless of what was published.
+- `client.rag.reset()` invalidates the cached schema fingerprint, so the
+  first ingest after a reset re-provisions the schema without serving a
+  stale `rag_dim_mismatch`.
+- `client.rag.ingest`: `ensureSchema` now memoises the verified dimensions
+  per `Sql` instance, dropping the per-call `_rag_meta` SELECT on the hot
+  path. The `stackbone_rag_jobs` writer also collapses its
+  `ensureCollection` lookup to a single `INSERT … ON CONFLICT … RETURNING`
+  (was a `SELECT` followed by an upsert) and trims `isCancelled` to
+  `SELECT status … LIMIT 1`.
+- `OtlpLogsBody` serialisation no longer iterates `Object.entries(LOG_LEVELS)`
+  per record to map level numbers to severity text — precomputed lookup
+  table replaces the linear scan.
+- `RagModule` test seams (`sqlProvider`, `jobWriterFactory`) now flow
+  through a typed 4th constructor parameter (`RagModuleTestDeps`) instead of
+  private fields mutated via `as unknown as` casts.
+
 ## [0.1.0-alpha.1] - 2026-05-15
 
 ### BREAKING

package/README.md

@@ -13,15 +13,12 @@ Official TypeScript SDK for [Stackbone](https://stackbone.ai) — the marketplac
 - **Database** — Direct Postgres access through a lazy Drizzle ORM wrapper bound to the agent's connection string, with full type-safe queries, transactions, and `sql` template literals — Drizzle is re-exported via `@stackbone/sdk/db` so the agent's `package.json` only depends on `@stackbone/sdk`
 - **Storage** — S3-compatible object storage (Cloudflare R2 in prod, MinIO in dev) with automatic per-agent key prefixing and signed URLs
 - **AI** — Wrapper around the official `openai` SDK pointed at OpenRouter, so 300+ chat, embedding and image models are reachable through a single OpenAI-compatible API
-- **Queues** _(coming soon)_ — Cross-container HTTP push via QStash, with typed job payloads through module augmentation
 - **RAG** — Document parsing, chunking and `pgvector`-backed retrieval through a flat, ceremony-free API
-- **Memory** _(coming soon)_ — Long-term agent memory backed by mem0: ingest text or whole conversations, semantic search, per-user / per-session / per-agent scoping, GDPR delete-all, audit history and session lifecycle hooks
-- **Prompts** _(coming soon)_ — Managed prompts stored in the Stackbone control plane: fetch by name with optional version pinning, compile Mustache `{{var}}` templates against a variables map, and full CRUD so prompts can evolve without rebuilding the container
-- **Observability** _(coming soon)_ — OpenTelemetry traces and logs flushed through the platform collector
+- **Observability** — OpenTelemetry span processor + run-cost aggregator + per-run logger
 - **Approval** — Human-in-the-loop inbox: fire-and-forget approval requests, HMAC-signed decision callbacks, and an LLM tool wrapper that gates execution behind human review
-- **Secrets** — Read workspace-encrypted secrets registered in the dashboard, no client-side cache so rotations propagate immediately
+- **Secrets** — Read organization-encrypted secrets registered in the dashboard, no client-side cache so rotations propagate immediately
 - **Config** — Typed reads of dynamic per-agent configuration the user set in the dashboard
-- **Connections / Events** _(coming soon)_ — OAuth integrations (Notion, GDrive, Slack…) and a workspace event bus
+- **Coming soon (types only)** — `queues` (cross-container HTTP push via QStash), `memory` (mem0-backed long-term memory), `prompts` (managed prompts with `{{var}}` templates), `connections` (OAuth integrations) and `events` (org-wide event bus). Public types are exported from `@stackbone/sdk` today; the runtime is not wired yet, so there is no live `client.X` accessor.
 - **TypeScript-first** — Full type definitions and a uniform `Result<T>` envelope on every method (no thrown errors at the SDK boundary)
 - **Lazy initialization** — Modules and partner SDKs are constructed on first access, so env vars rotated by the control plane after `createClient()` are still picked up
 
@@ -327,7 +324,7 @@ await stackbone.rag.reset();
 
 `client.approval` exposes a **fire-and-forget** primitive: the agent issues an approval request, the call returns immediately with the `approvalId` and a `callbackUrl`, and the control plane POSTs the human's decision to the endpoint the agent registered in `onDecide`. The callback is HMAC-signed (`Stackbone-Signature: t=<unix>,v1=<hex>`) so the agent can authenticate it without storing any per-approval secret.
 
-This shape decouples waiting from the container lifecycle — the agent does not have to keep a long-poll connection alive while a human reviews, which means it survives Neon scale-to-zero and arbitrary numbers of concurrent approvals without tying up sockets.
+This shape decouples waiting from the container lifecycle — the agent does not have to keep a long-poll connection alive while a human reviews, which means it survives idle scale-to-zero and arbitrary numbers of concurrent approvals without tying up sockets.
 
 ```ts
 // 1. Issue an approval — returns immediately, the human reviews asynchronously.
@@ -432,7 +429,7 @@ The signing key for `verify()` is read from `STACKBONE_APPROVAL_SIGNING_KEY` (or
 
 ### Secrets
 
-`client.secrets` reads workspace-encrypted secrets the user registered in the dashboard. The SDK is **read-only** by design — secrets are managed in the control plane, never written from inside an agent container. There is no client-side cache: every `get()` is a network call so dashboard rotations propagate immediately.
+`client.secrets` reads organization-encrypted secrets the user registered in the dashboard. The SDK is **read-only** by design — secrets are managed in the control plane, never written from inside an agent container. There is no client-side cache: every `get()` is a network call so dashboard rotations propagate immediately.
 
 ```ts
 // Single secret — `secrets_not_found` error if the name is not registered.
@@ -468,97 +465,28 @@ const { data: cfg } = await stackbone.config.getMany<{
 }>(['reply_tone', 'max_emails']);
 ```
 
-`secrets.get` returns `secrets_not_found` (with the name in `meta`) when the secret is missing; `config.get` returns `config_not_found` symmetrically. Both `getMany` calls return whatever subset the workspace has registered — no error for missing entries.
+`secrets.get` returns `secrets_not_found` (with the name in `meta`) when the secret is missing; `config.get` returns `config_not_found` symmetrically. Both `getMany` calls return whatever subset the organization has registered — no error for missing entries.
 
-### Memory
+### Memory (pending)
 
-`client.memory` is the agent's long-term memory surface. The first iteration is a **scaffolding placeholder** — every method returns `not_implemented`. The public types and signatures defined here are stable and the contract callers can already type their integrations against. The real backend will be [mem0](https://mem0.ai) (`mem0ApiKey` / `MEM0_API_KEY`).
-
-Memories are scoped along three axes:
-
-- `'user'` — long-term, persists across sessions of a given end user. Default.
-- `'session'` — short-lived; collapsed (or dropped) when `endSession()` runs.
-- `'agent'` — shared across every user of the agent (preferences, global knowledge).
-
-```ts
-// Ingest a fact (raw text or an OpenAI-shaped conversation).
-const { data: memory } = await stackbone.memory.add(
-  'The user prefers replies in Spanish and addresses them by their last name.',
-  { userId: 'user_42', scope: 'user', metadata: { source: 'onboarding' } },
-);
-
-// Or ingest a whole conversation — the backend summarises it into facts.
-await stackbone.memory.add(
-  [
-    { role: 'user', content: 'Call me Mr. Torres please.' },
-    { role: 'assistant', content: 'Got it, Mr. Torres.' },
-  ],
-  { userId: 'user_42', sessionId: 'sess_abc', scope: 'session' },
-);
-
-// Semantic search across the user's memories.
-const { data: hits } = await stackbone.memory.search('how should I address this user?', {
-  userId: 'user_42',
-  limit: 5,
-  threshold: 0.7,
-  includeScopes: ['user', 'agent'],
-});
-```
-
-Management — read, paginate, edit and audit a single fact:
-
-```ts
-const { data: memory } = await stackbone.memory.get(memoryId);
-
-const { data: page } = await stackbone.memory.list({
-  userId: 'user_42',
-  limit: 50,
-  cursor: previousCursor,
-});
-
-await stackbone.memory.update(memoryId, {
-  content: 'The user prefers replies in Spanish.',
-  metadata: { reviewed: true },
-});
-
-const { data: events } = await stackbone.memory.history(memoryId);
-```
-
-Deletion — single fact, all data for a user (GDPR), or end-of-session collapse:
-
-```ts
-// Forget one fact.
-await stackbone.memory.delete(memoryId);
-
-// GDPR: forget everything we have on this user.
-await stackbone.memory.deleteAll({ userId: 'user_42' });
-
-// Close a session and consolidate its facts into long-term memory (default).
-const { data } = await stackbone.memory.endSession('sess_abc', { persist: true });
-// data: { sessionId, persisted }
-```
-
-> Until the mem0 integration ships, every method returns `{ data: null, error: { code: 'not_implemented', ... } }`. The shape of the responses described here is the contract callers can already write code against.
+Long-term memory is a pending surface: its public types (`AddMemoryRequest`, `MemoryItem`, `MemoryHit`, `MemoryScope`, …) are exported from `@stackbone/sdk` so creators can type their integrations today, but there is no live `client.memory` accessor yet. The mem0-backed runtime will be added in a future release and promoted into the Features list above. See the [Coming Soon](#coming-soon) section for the full pending set.
 
 ### Coming Soon
 
-The following modules are part of the public surface but currently return a `not_implemented` error. They will land iteratively as the platform rolls out:
+The following surfaces have stable public **types** (so creators can write code against them today) but no runtime yet. They live under `src/surfaces/pending/` in the SDK source and do NOT appear as `client.X` accessors — importing the types directly from `@stackbone/sdk` is the supported path while the runtime is in flight:
 
 ```ts
-// Push an HTTP job to another agent (QStash-backed under the hood).
-await stackbone.queues.publish({
-  url: 'https://agent-b.stackbone.ai/invoke',
-  body: { leadId: 42 },
-  retries: 3,
-});
-
-// Emit an event to the workspace event bus.
-await stackbone.events.emit('lead.qualified', { leadId: 42 });
-
-// List OAuth connections the user attached (Notion, GDrive, Slack…).
-const { data: connections } = await stackbone.connections.list();
+import type {
+  PublishRequest,
+  AddMemoryRequest,
+  MemoryHit,
+  Prompt,
+  CreatePromptRequest,
+} from '@stackbone/sdk';
 ```
 
+The pending surfaces are `queues` (cross-container HTTP push), `memory` (mem0-backed long-term memory), `prompts` (managed prompts with `{{var}}` templates), `connections` (OAuth integrations) and `events` (organisation event bus). When their runtime lands they will be promoted into the live `client.X` set described in the Features section above.
+
 ## Configuration
 
 `createClient` accepts a single configuration object. Every field is optional and falls back to an environment variable, which the platform injects into the agent container at boot:
@@ -571,8 +499,8 @@ const stackbone = createClient({
   stackboneApiUrl: 'https://api.stackbone.ai',
   // Stable agent identifier used as storage key prefix     → STACKBONE_AGENT_ID
   agentId: 'agent_abc123',
-  // Postgres connection string for `client.rag` / observability (escape hatch).
-  // Note: `client.database` reads `STACKBONE_POSTGRES_URL`, not this one.
+  // Postgres connection string for `client.database`, `client.rag` and the
+  // observability exporter                                  → STACKBONE_POSTGRES_URL
   databaseUrl: 'postgresql://...',
   // OpenRouter credentials                                  → OPENROUTER_API_KEY / OPENROUTER_BASE_URL
   openrouterKey: '...',
@@ -586,12 +514,13 @@ const stackbone = createClient({
   mem0BaseUrl: 'https://api.mem0.ai',
   // HMAC key for verifying approval-decision callbacks       → STACKBONE_APPROVAL_SIGNING_KEY
   approvalSigningKey: '...',
-  // Object storage credentials                              → AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / S3_ENDPOINT / S3_BUCKET
+  // Object storage credentials                              → STACKBONE_S3_ACCESS_KEY / STACKBONE_S3_SECRET_KEY / STACKBONE_S3_ENDPOINT / STACKBONE_S3_BUCKET / STACKBONE_S3_REGION
   s3: {
     accessKeyId: '...',
     secretAccessKey: '...',
     endpoint: 'https://<account>.r2.cloudflarestorage.com',
     bucket: 'stackbone-prod',
+    region: 'auto',
   },
   // OpenTelemetry exporter
   otel: {
@@ -633,18 +562,24 @@ console.log(result.data.choices[0]?.message.content);
 
 Each module ships its own stable code prefix so you can pattern-match without parsing the message:
 
-| Prefix            | Source                 | Examples                                                                                                                                                                           |
-| ----------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ai_*`            | `client.ai`            | `ai_unauthorized`, `ai_credits_exhausted`, `ai_rate_limited`, `ai_aborted`, `ai_no_image_generated`                                                                                |
-| `s3_*`            | `client.storage`       | `s3_credentials_missing`, `s3_invalid_key`, `s3_error`                                                                                                                             |
-| `rag_*`           | `client.rag`           | `rag_invalid_request`, `rag_dim_mismatch`, `rag_embedding_failed`, `rag_error`                                                                                                     |
-| `approval_*`      | `client.approval`      | `approval_invalid_request`, `approval_invalid_signature`, `approval_signature_expired`, `approval_signing_key_missing`, `approval_invalid_payload`, `approval_tool_execute_failed` |
-| `secrets_*`       | `client.secrets`       | `secrets_invalid_request`, `secrets_not_found`, `secrets_invalid_response`                                                                                                         |
-| `config_*`        | `client.config`        | `config_invalid_request`, `config_not_found`, `config_invalid_response`                                                                                                            |
-| `memory_*`        | `client.memory`        | reserved for the future mem0-backed implementation; today every method returns `not_implemented`                                                                                   |
-| `http_*`          | facade HTTP client     | `http_unauthorized`, `http_timeout`, `http_rate_limited`, `http_server_error`                                                                                                      |
-| `*_missing`       | configuration          | `database_not_configured`, `agent_id_missing`, `openrouter_key_missing`, `database_url_missing`                                                                                    |
-| `not_implemented` | stubbed module surface | returned by every "coming soon" method until it ships                                                                                                                              |
+| Prefix            | Source                 | Examples                                                                                                                                                                                                                                                                                                 |
+| ----------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ai_*`            | `client.ai`            | `ai_unauthorized`, `ai_credits_exhausted`, `ai_rate_limited`, `ai_aborted`, `ai_no_image_generated`                                                                                                                                                                                                      |
+| `s3_*`            | `client.storage`       | `s3_credentials_missing`, `s3_invalid_key`, `s3_error`                                                                                                                                                                                                                                                   |
+| `rag_*`           | `client.rag`           | `rag_invalid_request`, `rag_dim_mismatch`, `rag_embedding_failed`, `rag_error`                                                                                                                                                                                                                           |
+| `approval_*`      | `client.approval`      | `approval_invalid_request`, `approval_invalid_signature`, `approval_signature_expired`, `approval_signing_key_missing`, `approval_invalid_payload`, `approval_tool_execute_failed`, `approval_unauthorized`, `approval_forbidden`, `approval_not_found`, `approval_rate_limited`, `approval_unavailable` |
+| `secrets_*`       | `client.secrets`       | `secrets_invalid_request`, `secrets_not_found`, `secrets_invalid_response`, `secrets_unauthorized`, `secrets_forbidden`, `secrets_rate_limited`, `secrets_unavailable`                                                                                                                                   |
+| `config_*`        | `client.config`        | `config_invalid_request`, `config_not_found`, `config_invalid_response`, `config_unauthorized`, `config_forbidden`, `config_rate_limited`, `config_unavailable`                                                                                                                                          |
+| `memory_*`        | `client.memory`        | reserved for the future mem0-backed implementation; today every method returns `not_implemented`                                                                                                                                                                                                         |
+| `http_*`          | transport-level errors | `http_timeout`, `http_aborted`, `http_network_error`, `http_parse_error`, `http_request_failed` — surface-level statuses (401/403/404/429/5xx) remap to `<surface>_*` codes                                                                                                                              |
+| `database_*`      | `client.database`      | `database_not_configured` (raised when `STACKBONE_POSTGRES_URL` is unset)                                                                                                                                                                                                                                |
+| `observability_*` | `client.observability` | `observability_close_run_failed`                                                                                                                                                                                                                                                                         |
+| `contract_*`      | gated surfaces         | `contract_malformed`, `contract_unreachable`, `contract_version_unsupported` — emitted by any gated call when the contract handshake fails                                                                                                                                                               |
+| `capability_*`    | gated surfaces         | `capability_unavailable` — emitted when the negotiated contract advertises no support for the surface                                                                                                                                                                                                    |
+| `*_missing`       | configuration          | `agent_id_missing`, `openrouter_key_missing`, `database_url_missing`, `stackbone_api_url_missing`                                                                                                                                                                                                        |
+| `not_implemented` | stubbed module surface | returned by every "coming soon" method until it ships                                                                                                                                                                                                                                                    |
+
+> The canonical inventory of every code lives in `src/errors/codes.ts` as a typed catalog (`SdkErrorCode`). The table above is the human-readable summary; adding or removing a code is a single-file edit there and the compiler refuses any literal `code` value not declared in the catalog. Pattern-match against `SdkErrorCode` (exported from `@stackbone/sdk`) for full type narrowing, or call `isSdkErrorCode(raw)` to widen a wire string back into the catalog.
 
 ## TypeScript Support
 

package/db/testing/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var crypto = require('crypto');
+var postgresql = require('@testcontainers/postgresql');
 var postgresJs = require('drizzle-orm/postgres-js');
 var migrator = require('drizzle-orm/postgres-js/migrator');
 var postgres = require('postgres');
@@ -11,46 +11,14 @@ var postgres__default = /*#__PURE__*/_interopDefault(postgres);
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
-var resolveAdminUrl = /* @__PURE__ */ __name((override) => override ?? process.env["STACKBONE_TEST_POSTGRES_URL"] ?? process.env["STACKBONE_POSTGRES_URL"] ?? process.env["DATABASE_URL"] ?? "postgres://stackbone:stackbone@localhost:5432/stackbone", "resolveAdminUrl");
-var generateSchemaName = /* @__PURE__ */ __name(() => `stackbone_test_${crypto.randomBytes(8).toString("hex")}`, "generateSchemaName");
-var tagConnectionStringWithSchema = /* @__PURE__ */ __name((url, schemaName) => {
-  const u = new URL(url);
-  u.searchParams.set("schema", schemaName);
-  return u.toString();
-}, "tagConnectionStringWithSchema");
-var dropSchema = /* @__PURE__ */ __name(async (adminUrl, schemaName) => {
-  const admin = postgres__default.default(adminUrl, {
-    max: 1,
-    onnotice: /* @__PURE__ */ __name(() => void 0, "onnotice")
-  });
-  try {
-    await admin.unsafe(`DROP SCHEMA "${schemaName.replace(/"/g, '""')}" CASCADE`);
-  } finally {
-    await admin.end({
-      timeout: 5
-    });
-  }
-}, "dropSchema");
+var DEFAULT_IMAGE = "pgvector/pgvector:pg17";
 var createTestDatabase = /* @__PURE__ */ __name(async (options) => {
-  const adminUrl = resolveAdminUrl(options.connectionString);
-  const schemaName = generateSchemaName();
-  const admin = postgres__default.default(adminUrl, {
-    max: 1,
-    onnotice: /* @__PURE__ */ __name(() => void 0, "onnotice")
-  });
-  try {
-    await admin`CREATE SCHEMA ${admin(schemaName)}`;
-  } finally {
-    await admin.end({
-      timeout: 5
-    });
-  }
-  const client = postgres__default.default(adminUrl, {
+  const image = options.image ?? DEFAULT_IMAGE;
+  const container = await new postgresql.PostgreSqlContainer(image).withDatabase("stackbone_test").withUsername("stackbone").withPassword("stackbone").start();
+  const connectionString = container.getConnectionUri();
+  const client = postgres__default.default(connectionString, {
     max: 5,
-    onnotice: /* @__PURE__ */ __name(() => void 0, "onnotice"),
-    connection: {
-      search_path: schemaName
-    }
+    onnotice: /* @__PURE__ */ __name(() => void 0, "onnotice")
   });
   const db = postgresJs.drizzle(client);
   let disposed = false;
@@ -60,19 +28,20 @@ var createTestDatabase = /* @__PURE__ */ __name(async (options) => {
     await client.end({
       timeout: 5
     }).catch(() => void 0);
-    await dropSchema(adminUrl, schemaName).catch(() => void 0);
+    await container.stop({
+      timeout: 5e3
+    }).catch(() => void 0);
   }, "dispose");
   try {
     await migrator.migrate(db, {
-      migrationsFolder: options.migrationsDir,
-      migrationsSchema: schemaName
+      migrationsFolder: options.migrationsDir
     });
   } catch (err) {
     await dispose();
     throw err;
   }
   return {
-    connectionString: tagConnectionStringWithSchema(adminUrl, schemaName),
+    connectionString,
     drizzle: db,
     dispose
   };