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

package/CHANGELOG.md

@@ -7,6 +7,280 @@ 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
@@ -14,7 +288,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `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
+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.

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** _(surface defined; runtime pending)_ — 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** _(surface defined; runtime pending)_ — 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** — 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 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** — OAuth integrations (Notion, GDrive, Slack…) and an organization 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
 
@@ -470,95 +467,26 @@ const { data: cfg } = await stackbone.config.getMany<{
 
 `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 organization 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:
@@ -634,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
   };

package/db/testing/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../libs/sdk/src/db/testing/index.ts"],"names":["resolveAdminUrl","override","process","env","generateSchemaName","randomBytes","toString","tagConnectionStringWithSchema","url","schemaName","u","URL","searchParams","set","dropSchema","adminUrl","admin","postgres","max","onnotice","undefined","unsafe","replace","end","timeout","createTestDatabase","options","connectionString","client","connection","search_path","db","drizzle","disposed","dispose","catch","migrate","migrationsFolder","migrationsDir","migrationsSchema","err"],"mappings":"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","file":"index.cjs","sourcesContent":["// Public API for `@stackbone/sdk/db/testing`.\n//\n// `createTestDatabase` provisions an ephemeral, randomly-named Postgres schema\n// inside a shared developer database (the docker-compose `stackbone-postgres`\n// container in dev, or whatever Postgres the consumer points at via env or\n// `connectionString`) and applies a drizzle-kit-shaped migrations folder\n// against it. Returns a ready-to-query Drizzle instance plus a `dispose()`\n// that drops the schema and closes the pool — guaranteeing that two parallel\n// tests neither bleed rows nor leak schemas after the suite ends.\n//\n// Why a schema instead of a fresh database or a testcontainer:\n//   - Schema creation is ~milliseconds (CREATE DATABASE on Postgres takes a\n//     real lock and copies template1).\n//   - One pre-pulled Postgres image (the dev compose container) avoids the\n//     per-suite testcontainer boot cost (~3-5s) on every `nx test`.\n//   - `search_path` isolation keeps every creator's migration SQL — which\n//     references unqualified table names — applying to the throwaway schema\n//     without rewriting their `.sql` files.\n//\n// Why not reuse `apps/cli/src/dev/db-migrator.ts`:\n//   - That module owns the platform's advisory-lock + `__stackbone_migrations__`\n//     journal table, which is shared across the whole DB and explicitly NOT\n//     scoped to a schema. Tests run inside their own schema, so the standard\n//     drizzle migrator (`drizzle-orm/postgres-js/migrator`) with\n//     `migrationsSchema` pointed at the throwaway schema is the right primitive.\n\nimport { randomBytes } from 'node:crypto';\nimport { drizzle, type PostgresJsDatabase } from 'drizzle-orm/postgres-js';\nimport { migrate } from 'drizzle-orm/postgres-js/migrator';\nimport postgres, { type Sql } from 'postgres';\n\n/** Inputs for `createTestDatabase`. */\nexport interface CreateTestDatabaseOptions {\n  /**\n   * Drizzle-kit-shaped migrations directory: `meta/_journal.json` plus one\n   * `<tag>.sql` file per entry. Required — the helper applies the migrations\n   * before returning so the first query a test runs already sees the schema.\n   */\n  migrationsDir: string;\n  /**\n   * Optional Postgres URL pointing at the shared dev DB. Falls back, in order,\n   * to:\n   *   1. `STACKBONE_TEST_POSTGRES_URL` (preferred — lets CI override\n   *      independently of the agent's runtime URL).\n   *   2. `STACKBONE_POSTGRES_URL` (the env var the rest of the SDK reads).\n   *   3. `DATABASE_URL` (the env var loaded by `node --env-file=.env`).\n   *   4. `postgres://stackbone:stackbone@localhost:5432/stackbone` (the\n   *      docker-compose default — the same DB `pnpm db:migrate` hits).\n   */\n  connectionString?: string;\n}\n\n/** Result of `createTestDatabase`. */\nexport interface TestDatabase {\n  /**\n   * Postgres URL pinned to the throwaway schema via the `?schema=<name>` query\n   * parameter. Useful for sub-processes (drizzle-kit studio, a worker) that\n   * need to share the same isolation.\n   */\n  connectionString: string;\n  /** Drizzle handle bound to the throwaway schema, ready to query. */\n  drizzle: PostgresJsDatabase<Record<string, never>>;\n  /**\n   * Tears the test DB down: closes the pool, then drops the schema with\n   * CASCADE so dependent tables/indexes/sequences vanish in one statement.\n   * Idempotent — calling it twice is a no-op.\n   */\n  dispose: () => Promise<void>;\n}\n\n/**\n * Resolves the admin Postgres URL. See `connectionString` on\n * `CreateTestDatabaseOptions` for the env-fallback chain.\n */\nconst resolveAdminUrl = (override?: string): string =>\n  override ??\n  process.env['STACKBONE_TEST_POSTGRES_URL'] ??\n  process.env['STACKBONE_POSTGRES_URL'] ??\n  process.env['DATABASE_URL'] ??\n  'postgres://stackbone:stackbone@localhost:5432/stackbone';\n\n/**\n * Generates a random schema name short enough to fit Postgres's 63-char\n * identifier limit while still being unique across parallel workers.\n */\nconst generateSchemaName = (): string => `stackbone_test_${randomBytes(8).toString('hex')}`;\n\n/**\n * Encodes a `?schema=<name>` query parameter into the URL so callers (and\n * sub-processes) can opt into the same isolation by reading their own URL.\n * Metadata for the caller — libpq itself does not honour it.\n */\nconst tagConnectionStringWithSchema = (url: string, schemaName: string): string => {\n  const u = new URL(url);\n  u.searchParams.set('schema', schemaName);\n  return u.toString();\n};\n\n/** Drops the throwaway schema via a one-shot admin connection. */\nconst dropSchema = async (adminUrl: string, schemaName: string): Promise<void> => {\n  const admin = postgres(adminUrl, { max: 1, onnotice: () => undefined });\n  try {\n    await admin.unsafe(`DROP SCHEMA \"${schemaName.replace(/\"/g, '\"\"')}\" CASCADE`);\n  } finally {\n    await admin.end({ timeout: 5 });\n  }\n};\n\n/**\n * Provisions an ephemeral, randomly-named schema inside the shared dev\n * Postgres, applies the supplied migrations directory against it, and hands\n * back a Drizzle instance + `dispose()` for tear-down. See module header for\n * design rationale.\n */\nexport const createTestDatabase = async (\n  options: CreateTestDatabaseOptions,\n): Promise<TestDatabase> => {\n  const adminUrl = resolveAdminUrl(options.connectionString);\n  const schemaName = generateSchemaName();\n\n  // Step 1 — admin client to bootstrap the schema. Tiny pool because we only\n  // run one DDL statement before tearing the connection down.\n  const admin = postgres(adminUrl, { max: 1, onnotice: () => undefined });\n  try {\n    await admin`CREATE SCHEMA ${admin(schemaName)}`;\n  } finally {\n    await admin.end({ timeout: 5 });\n  }\n\n  // Step 2 — scoped client. `search_path` is set at connection time so every\n  // statement (DDL from the migrations and the consumer's own queries) lands\n  // inside the throwaway schema without qualifying table names.\n  const client: Sql = postgres(adminUrl, {\n    max: 5,\n    onnotice: () => undefined,\n    connection: { search_path: schemaName },\n  });\n  const db = drizzle(client);\n\n  let disposed = false;\n  const dispose = async (): Promise<void> => {\n    if (disposed) return;\n    disposed = true;\n    await client.end({ timeout: 5 }).catch(() => undefined);\n    await dropSchema(adminUrl, schemaName).catch(() => undefined);\n  };\n\n  // Step 3 — apply migrations. `migrationsSchema` keeps Drizzle's journal\n  // table inside the throwaway schema too, so the schema-drop in `dispose`\n  // wipes both creator-owned tables and Drizzle's own bookkeeping in one\n  // statement. On failure, dispose so a broken fixture does not leak a\n  // half-bootstrapped schema for the rest of the suite.\n  try {\n    await migrate(db, {\n      migrationsFolder: options.migrationsDir,\n      migrationsSchema: schemaName,\n    });\n  } catch (err) {\n    await dispose();\n    throw err;\n  }\n\n  return {\n    connectionString: tagConnectionStringWithSchema(adminUrl, schemaName),\n    drizzle: db,\n    dispose,\n  };\n};\n"]}
+{"version":3,"sources":["../../../../../libs/sdk/src/db/testing/index.ts"],"names":["DEFAULT_IMAGE","createTestDatabase","options","image","container","PostgreSqlContainer","withDatabase","withUsername","withPassword","start","connectionString","getConnectionUri","client","postgres","max","onnotice","undefined","db","drizzle","disposed","dispose","end","timeout","catch","stop","migrate","migrationsFolder","migrationsDir","err"],"mappings":";;;;;;;;;;;;;AAoDA,IAAMA,aAAAA,GAAgB,wBAAA;AAOf,IAAMC,kBAAAA,iCACXC,OAAAA,KAAAA;AAEA,EAAA,MAAMC,KAAAA,GAAQD,QAAQC,KAAAA,IAASH,aAAAA;AAE/B,EAAA,MAAMI,SAAAA,GAAwC,MAAM,IAAIC,8BAAAA,CAAoBF,KAAAA,CAAAA,CACzEG,YAAAA,CAAa,gBAAA,CAAA,CACbC,aAAa,WAAA,CAAA,CACbC,YAAAA,CAAa,WAAA,EACbC,KAAAA,EAAK;AAER,EAAA,MAAMC,gBAAAA,GAAmBN,UAAUO,gBAAAA,EAAgB;AACnD,EAAA,MAAMC,MAAAA,GAAcC,0BAASH,gBAAAA,EAAkB;IAAEI,GAAAA,EAAK,CAAA;AAAGC,IAAAA,QAAAA,+BAAgBC,MAAAA,EAAN,UAAA;GAAgB,CAAA;AACnF,EAAA,MAAMC,EAAAA,GAAKC,mBAAQN,MAAAA,CAAAA;AAEnB,EAAA,IAAIO,QAAAA,GAAW,KAAA;AACf,EAAA,MAAMC,0BAAU,MAAA,CAAA,YAAA;AACd,IAAA,IAAID,QAAAA,EAAU;AACdA,IAAAA,QAAAA,GAAW,IAAA;AACX,IAAA,MAAMP,OAAOS,GAAAA,CAAI;MAAEC,OAAAA,EAAS;KAAE,CAAA,CAAGC,KAAAA,CAAM,MAAMP,MAAAA,CAAAA;AAC7C,IAAA,MAAMZ,UAAUoB,IAAAA,CAAK;MAAEF,OAAAA,EAAS;KAAK,CAAA,CAAGC,KAAAA,CAAM,MAAMP,MAAAA,CAAAA;EACtD,CAAA,EALgB,SAAA,CAAA;AAOhB,EAAA,IAAI;AACF,IAAA,MAAMS,iBAAQR,EAAAA,EAAI;AAAES,MAAAA,gBAAAA,EAAkBxB,OAAAA,CAAQyB;KAAc,CAAA;AAC9D,EAAA,CAAA,CAAA,OAASC,GAAAA,EAAK;AACZ,IAAA,MAAMR,OAAAA,EAAAA;AACN,IAAA,MAAMQ,GAAAA;AACR,EAAA;AAEA,EAAA,OAAO;AAAElB,IAAAA,gBAAAA;IAAkBQ,OAAAA,EAASD,EAAAA;AAAIG,IAAAA;AAAQ,GAAA;AAClD,CAAA,EA/BkC,oBAAA","file":"index.cjs","sourcesContent":["// Public API for `@stackbone/sdk/db/testing`.\n//\n// `createTestDatabase` spins up an ephemeral Postgres container via\n// `@testcontainers/postgresql`, applies a drizzle-kit-shaped migrations folder\n// against it and hands back a ready-to-query Drizzle instance plus a\n// `dispose()` that stops the container. Every call gets its own container, so\n// parallel tests never bleed rows nor share state.\n//\n// Why testcontainers instead of a shared dev DB:\n//   - One self-contained primitive: `pnpm test` just works, no\n//     `docker compose up` ceremony required of contributors or CI.\n//   - True isolation per suite — schemas inside a shared DB still share the\n//     server's stats, locks and configuration; containers do not.\n//   - Aligns with the rest of the Stackbone monorepo (see\n//     `apps/api/src/db/__tests__/setup-postgres.ts`).\n\nimport { PostgreSqlContainer, type StartedPostgreSqlContainer } from '@testcontainers/postgresql';\nimport { drizzle, type PostgresJsDatabase } from 'drizzle-orm/postgres-js';\nimport { migrate } from 'drizzle-orm/postgres-js/migrator';\nimport postgres, { type Sql } from 'postgres';\n\n/** Inputs for `createTestDatabase`. */\nexport interface CreateTestDatabaseOptions {\n  /**\n   * Drizzle-kit-shaped migrations directory: `meta/_journal.json` plus one\n   * `<tag>.sql` file per entry. Required — the helper applies the migrations\n   * before returning so the first query a test runs already sees the schema.\n   */\n  migrationsDir: string;\n  /**\n   * Postgres image to spin up. Defaults to `pgvector/pgvector:pg17` so RAG\n   * and AI starters that need the `vector` extension work out of the box.\n   * Override with `postgres:17` for a vanilla minimum-footprint container,\n   * or with a custom tag (e.g. `stackbone/postgres:local`) when the test\n   * suite needs the bundled `pgmq` / `pg_cron` extensions.\n   */\n  image?: string;\n}\n\n/** Result of `createTestDatabase`. */\nexport interface TestDatabase {\n  /** Postgres URL of the running container, ready for sub-processes. */\n  connectionString: string;\n  /** Drizzle handle bound to the container's database, ready to query. */\n  drizzle: PostgresJsDatabase<Record<string, never>>;\n  /**\n   * Tears the test DB down: closes the pool and stops the container.\n   * Idempotent — calling it twice is a no-op.\n   */\n  dispose: () => Promise<void>;\n}\n\nconst DEFAULT_IMAGE = 'pgvector/pgvector:pg17';\n\n/**\n * Spins up an ephemeral Postgres container, applies the supplied migrations\n * directory against it, and hands back a Drizzle instance + `dispose()` for\n * tear-down. See module header for design rationale.\n */\nexport const createTestDatabase = async (\n  options: CreateTestDatabaseOptions,\n): Promise<TestDatabase> => {\n  const image = options.image ?? DEFAULT_IMAGE;\n\n  const container: StartedPostgreSqlContainer = await new PostgreSqlContainer(image)\n    .withDatabase('stackbone_test')\n    .withUsername('stackbone')\n    .withPassword('stackbone')\n    .start();\n\n  const connectionString = container.getConnectionUri();\n  const client: Sql = postgres(connectionString, { max: 5, onnotice: () => undefined });\n  const db = drizzle(client);\n\n  let disposed = false;\n  const dispose = async (): Promise<void> => {\n    if (disposed) return;\n    disposed = true;\n    await client.end({ timeout: 5 }).catch(() => undefined);\n    await container.stop({ timeout: 5000 }).catch(() => undefined);\n  };\n\n  try {\n    await migrate(db, { migrationsFolder: options.migrationsDir });\n  } catch (err) {\n    await dispose();\n    throw err;\n  }\n\n  return { connectionString, drizzle: db, dispose };\n};\n"]}