dominus-sdk-nodejs 11.0.6 → 11.0.8

package/dist/refs/resolve.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Ref transport — the resolver seam that turns a parsed ref into a resolved,
+ * service-native receipt.
+ *
+ * `resolve()` owns transport and owns NO judgment: it asks the owning service
+ * for the answer and passes the response back unmodified as a discriminated
+ * receipt. It never re-derives tier, scope, or backend selection — those
+ * decisions belong to the services (enforced by E1). `parse()` is used only to
+ * pick the answering service and reject garbage; for `ar://` the original ref
+ * string crosses the wire verbatim and is never decomposed (enforced by E2).
+ *
+ * `recipe://` transport borrows the `/svc/stash/compose` fall-through contract:
+ * probe the Stash lane first, and on a typed `stash.not_found.*` or
+ * `stash.forbidden.scope_not_allowed` miss, fall through to the recipe-worker
+ * route. Every other `stash.*` error aborts and propagates unmodified — the
+ * overlay never reclassifies an upstream failure (the `SharedNeonClient.query()`
+ * anti-pattern this seam refuses to repeat). Backend selection is keyed on
+ * `err.code`, never on HTTP status.
+ */
+import type { DominusClient } from '../lib/client.js';
+import type { KernelRef } from './grammar.js';
+import type { ResolvedRef } from './types.js';
+/** Call-site options for {@link RefResolver.resolve}. */
+export interface ResolveOptions {
+    /** Stash-lane read scope; consumed by the `recipe://` arm (no default). */
+    env?: string;
+}
+export declare class RefResolver {
+    private client;
+    constructor(client: DominusClient);
+    /**
+     * Parse a ref into its discriminated {@link KernelRef} with no I/O.
+     * Delegates to the pure grammar module (`src/refs/grammar.ts`); the
+     * resolver owns transport, not grammar.
+     */
+    parse(ref: string): KernelRef;
+    resolve(ref: string, options?: ResolveOptions): Promise<ResolvedRef>;
+    private resolveArtifact;
+    private resolveRecipe;
+    private resolveRecipeWorker;
+}
+/**
+ * The two typed legs that may fall through to the recipe-worker route. Keyed on
+ * `err.code`, never HTTP status — a 403-coded `scope_not_allowed` falls through
+ * while a 401-coded auth failure aborts. Exported so `RecipesNamespace.get`
+ * reuses the same predicate instead of maintaining a second copy.
+ */
+export declare function isFallThrough(err: unknown): boolean;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/refs/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/refs/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,cAAc,CAAC;AAEzD,OAAO,KAAK,EAA4B,WAAW,EAA0B,MAAM,YAAY,CAAC;AAEhG,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAKD,qBAAa,WAAW;IACV,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAEzC;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS;IAIvB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;YAkBhE,eAAe;YAgBf,aAAa;YA2Cb,mBAAmB;CAclC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAInD"}

package/dist/refs/resolve.js

@@ -0,0 +1,129 @@
+/**
+ * Ref transport — the resolver seam that turns a parsed ref into a resolved,
+ * service-native receipt.
+ *
+ * `resolve()` owns transport and owns NO judgment: it asks the owning service
+ * for the answer and passes the response back unmodified as a discriminated
+ * receipt. It never re-derives tier, scope, or backend selection — those
+ * decisions belong to the services (enforced by E1). `parse()` is used only to
+ * pick the answering service and reject garbage; for `ar://` the original ref
+ * string crosses the wire verbatim and is never decomposed (enforced by E2).
+ *
+ * `recipe://` transport borrows the `/svc/stash/compose` fall-through contract:
+ * probe the Stash lane first, and on a typed `stash.not_found.*` or
+ * `stash.forbidden.scope_not_allowed` miss, fall through to the recipe-worker
+ * route. Every other `stash.*` error aborts and propagates unmodified — the
+ * overlay never reclassifies an upstream failure (the `SharedNeonClient.query()`
+ * anti-pattern this seam refuses to repeat). Backend selection is keyed on
+ * `err.code`, never on HTTP status.
+ */
+import { DominusError, ValidationError } from '../lib/errors.js';
+import { parse as parseGrammar, routeFor } from './grammar.js';
+export class RefResolver {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Parse a ref into its discriminated {@link KernelRef} with no I/O.
+     * Delegates to the pure grammar module (`src/refs/grammar.ts`); the
+     * resolver owns transport, not grammar.
+     */
+    parse(ref) {
+        return parseGrammar(ref);
+    }
+    async resolve(ref, options = {}) {
+        const parsed = parseGrammar(ref);
+        if (parsed.scheme === 'ar') {
+            return this.resolveArtifact(parsed.ref);
+        }
+        if (parsed.scheme === 'unresolvable') {
+            throw new DominusError(`No route for ${parsed.attemptedScheme}:// refs: ${parsed.missingContract} (owner: ${parsed.owningService})`, 400, { code: 'ref.scheme.unresolvable', category: 'validation' });
+        }
+        return this.resolveRecipe(parsed, ref, options);
+    }
+    async resolveArtifact(ref) {
+        const receipt = await this.client.request({
+            endpoint: '/api/artifact/v2/retrieve',
+            method: 'POST',
+            body: { ref },
+            useGateway: true,
+        });
+        return {
+            source: 'artifact',
+            ref,
+            payload: receipt.data ?? '',
+            receipt,
+        };
+    }
+    async resolveRecipe(parsed, ref, options) {
+        const env = options.env;
+        if (env === undefined || env === '') {
+            throw new ValidationError('recipe:// stash-lane reads require an explicit env', 400, {
+                code: 'ref.env.required',
+                category: 'validation',
+            });
+        }
+        const version = toStashVersion(parsed.version);
+        try {
+            const response = await this.client.request({
+                endpoint: '/svc/stash/get',
+                method: 'POST',
+                body: {
+                    env,
+                    kind: parsed.type,
+                    scope: 'self',
+                    key: parsed.name,
+                    ...(version !== undefined ? { version } : {}),
+                },
+                useGateway: true,
+            });
+            return {
+                source: 'stash',
+                ref,
+                payload: response.value,
+                receipt: response,
+            };
+        }
+        catch (err) {
+            if (isFallThrough(err)) {
+                return this.resolveRecipeWorker(parsed, ref);
+            }
+            throw err;
+        }
+    }
+    async resolveRecipeWorker(parsed, ref) {
+        const resolved = await this.client.request({
+            endpoint: `/api/recipe/recipes/${routeFor(parsed)}`,
+            method: 'GET',
+            useGateway: true,
+        });
+        return {
+            source: 'recipe-worker',
+            ref,
+            payload: resolved.body,
+            receipt: resolved.metadata,
+        };
+    }
+}
+/**
+ * The two typed legs that may fall through to the recipe-worker route. Keyed on
+ * `err.code`, never HTTP status — a 403-coded `scope_not_allowed` falls through
+ * while a 401-coded auth failure aborts. Exported so `RecipesNamespace.get`
+ * reuses the same predicate instead of maintaining a second copy.
+ */
+export function isFallThrough(err) {
+    if (!(err instanceof DominusError))
+        return false;
+    const code = err.code ?? '';
+    return code.startsWith('stash.not_found.') || code === 'stash.forbidden.scope_not_allowed';
+}
+/** Map a `recipe://` version token to the stash version selector. */
+function toStashVersion(version) {
+    if (version === undefined || version === 'head' || version === 'latest') {
+        return version;
+    }
+    const numeric = version.startsWith('v') ? version.slice(1) : version;
+    return Number(numeric);
+}
+//# sourceMappingURL=resolve.js.map

package/dist/refs/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/refs/resolve.ts"],"names":[],"mappings":"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"}

package/dist/refs/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Ref receipt types — the public return contract of the ref resolver seam.
+ *
+ * `ResolvedRef` is discriminated on `source` (the answering service). Each
+ * variant carries that service's own response as its `receipt`, unmodified —
+ * provenance is passed through, never normalized, never synthesized. Because
+ * `owner` exists on the recipe-worker variant (it is a field of the worker's
+ * own `RecipeMetadata`) and does NOT exist on the stash variant, an empty
+ * owner (`owner: ''`) is unrepresentable at compile time. E4 proves this.
+ *
+ * Shared across variants: `ref`, `source`, and `payload` only. No provenance
+ * field (tier, scope, owner, backend) is shared across variants.
+ */
+import type { RecipeMetadata } from '../namespaces/recipes.js';
+/** The `/svc/artifact/v2/retrieve` response (artifact-worker V2 retrieve). */
+export interface ArtifactRetrieveResponse {
+    resolved_ref: string | null;
+    head_ref: string | null;
+    snapshot_ref: string | null;
+    version: number | null;
+    data: string | null;
+    content_type: string | null;
+    storage_type: 'redis' | 'b2' | null;
+    size_bytes: number | null;
+    expires_at: string | null;
+}
+/**
+ * The fields `/svc/stash/get` actually returns (stash-worker pointer-text
+ * `get`). `scope_resolved` is the worker's own `tierMeta(...)` expansion.
+ */
+export interface StashResolutionReceipt {
+    resolved_tier: string;
+    source_scope: string;
+    scope_resolved: Record<string, unknown>;
+    scope_hash: string;
+    value_hash: string;
+    version: number;
+}
+/** A resolved ref, keyed on the answering service. */
+export type ResolvedRef = {
+    source: 'artifact';
+    ref: string;
+    payload: string;
+    receipt: ArtifactRetrieveResponse;
+} | {
+    source: 'recipe-worker';
+    ref: string;
+    payload: string;
+    receipt: RecipeMetadata;
+} | {
+    source: 'stash';
+    ref: string;
+    payload: unknown;
+    receipt: StashResolutionReceipt;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/refs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/refs/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,8EAA8E;AAC9E,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI,CAAC;IACpC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sDAAsD;AACtD,MAAM,MAAM,WAAW,GACnB;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,wBAAwB,CAAA;CAAE,GACvF;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,GAClF;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,sBAAsB,CAAA;CAAE,CAAC"}

package/dist/refs/types.js

@@ -0,0 +1,15 @@
+/**
+ * Ref receipt types — the public return contract of the ref resolver seam.
+ *
+ * `ResolvedRef` is discriminated on `source` (the answering service). Each
+ * variant carries that service's own response as its `receipt`, unmodified —
+ * provenance is passed through, never normalized, never synthesized. Because
+ * `owner` exists on the recipe-worker variant (it is a field of the worker's
+ * own `RecipeMetadata`) and does NOT exist on the stash variant, an empty
+ * owner (`owner: ''`) is unrepresentable at compile time. E4 proves this.
+ *
+ * Shared across variants: `ref`, `source`, and `payload` only. No provenance
+ * field (tier, scope, owner, backend) is shared across variants.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/refs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/refs/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/docs/agent-guide/2026-08-25-2103-sdk-nodejs/00-reading-order.md

@@ -0,0 +1,42 @@
+# Dominus SDK for Node.js — reading order
+
+Snapshot: 2026-08-25-2103, production source commit `4f7b377`, SDK v11.0.7.
+
+## Read first
+
+1. `README.md` — package usage, Quick Start, workflow lifecycle.
+2. `docs/agent-guide/2026-08-25-2103-sdk-nodejs/01-purpose-and-boundaries.md`
+3. `docs/agent-guide/2026-08-25-2103-sdk-nodejs/02-repo-map-and-entrypoints.md`
+4. `docs/agent-guide/2026-08-25-2103-sdk-nodejs/03-api-surface.md`
+5. `docs/agent-guide/2026-08-25-2103-sdk-nodejs/10-agent-playbook.md`
+
+## Source files to open only for specific task types
+
+| Task | File |
+|---|---|
+| Public surface / namespace wiring | `src/index.ts` |
+| Request lifecycle, auth, retries, streaming/binary | `src/lib/client.ts` |
+| Error hierarchy and endpoint-typed errors | `src/lib/errors.ts` |
+| Env resolution / gateway config | `src/lib/config.ts` |
+| JWT cache / circuit breaker | `src/lib/cache.ts` |
+| `recipe://` / `ar://` ref resolution | `src/refs/resolve.ts`, `src/refs/types.ts` |
+| Wire contracts (node envelope, projections, session) | `src/contract/*.ts`, `src/contracts/versioned-storage.ts` |
+| Release + CI | `.github/workflows/publish-*.yml`, `tests.yml` |
+
+## Docs that are stale or superseded
+
+- `docs/agent-guide/2026-06-27-0849-sdk-orient/` — v6.6.0-era pack; superseded by
+  the 2026-08-04 pack and this snapshot. Kept for historical context.
+- `docs/agent-guide/2026-08-04-sdk-nodejs/` — partial pack (00/01/03/10 only);
+  superseded by this snapshot.
+- `docs/architecture.md`, `docs/routes-services.md`, `docs/usage-reference.md` —
+  still useful but aging; verify claims against `src/` before trusting a route,
+  namespace, or behavior fact. `docs/architecture.md` §10 "no committed tests"
+  claim was already corrected in the 2026-06-27 pack (`tests/` is committed).
+
+## Atlas and audit to consult
+
+- Atlas: `docs/atlas/2026-08-04-sdk-nodejs-truthmap.md`,
+  `docs/atlas/2026-08-04-sdk-nodejs-proof-ladder.md`,
+  `docs/atlas/2026-08-04-sdk-nodejs-blockers.md`.
+- Latest cleanup audit: `docs/janitor/2026-08-25-2103-sdk-nodejs-cleanup-audit.md`.

package/docs/agent-guide/2026-08-25-2103-sdk-nodejs/01-purpose-and-boundaries.md

@@ -0,0 +1,45 @@
+# Purpose and boundaries
+
+## Main purpose
+
+`dominus-sdk-nodejs` is the TypeScript/ESM SDK for the Dominus gateway-first
+platform. It exposes a singleton `dominus` (from `src/index.ts`) with
+namespace-based APIs for auth, data, storage, AI/runtime, workflow execution,
+job processing, and platform administration. It is published to the npm
+registry as `dominus-sdk-nodejs` (v11.0.7 at snapshot time).
+
+## What the repo owns
+
+- SDK client and transport: `src/lib/client.ts` (HTTP/base64 protocol, JWT
+  mint/cache, SSE streaming, binary IO).
+- Namespace facades: `src/namespaces/*.ts` (28 files), each wired as a `public
+  readonly` property on the `dominus` singleton in `src/index.ts`.
+- Error hierarchy and endpoint-typed errors: `src/lib/errors.ts`.
+- Ref resolver seam (`recipe://`, `ar://`): `src/refs/*`.
+- Wire-contract module: `src/contract/*` and `src/contracts/versioned-storage.ts`.
+- Committed test suite: `tests/` (35 `.test.js` files + type tests; HEAD commit
+  `4f7b377` reports 179 tests green).
+
+## What it explicitly does not own
+
+- Worker implementations (gateway, authority, logs, stash, artifact, etc.).
+  The SDK only calls their `/svc/*` or `/api/*` routes through the gateway.
+- The Dominus platform kernel or deploy lanes of other repos.
+- `dist/` — generated build output (`npm run build`), not a design source.
+
+## Boundary
+
+- This is a library repo (npm package), not a deployed service. It crosses
+  Dominus platform contracts (gateway routes, worker wire shapes) so
+  contract-sensitive changes belong to `dominus-expert` review.
+
+## Runtime / deployment class
+
+- Node.js `>=18`, ESM (`"type": "module"`), single export entry
+  `exports["."] → dist/index.js`.
+- Released by pushing to `production` (see `07-operations-release-and-live-proof.md`).
+
+## PHI / secrets / safety
+
+- Never write PHI, secrets, credentials, raw reports, or response bodies into
+  docs. `DOMINUS_TOKEN` is a PSK; treat it as secret.

package/docs/agent-guide/2026-08-25-2103-sdk-nodejs/02-repo-map-and-entrypoints.md

@@ -0,0 +1,36 @@
+# Repo map and entrypoints
+
+## Directory map
+
+| Path | Purpose |
+|---|---|
+| `src/index.ts` | Public surface: `dominus` singleton, namespace wiring, root shortcuts, error re-exports, crypto helpers |
+| `src/lib/` | Transport + support: `client.ts`, `cache.ts`, `errors.ts`, `config.ts`, `console-capture.ts`, `conversation-format.ts`, `crypto.ts`, `page-rules.ts`, `recovery-action.ts`, `schema-builder.ts`, `trace.ts`, `user-session.ts` |
+| `src/namespaces/` | 28 service facades, one file per namespace (see `03-api-surface.md`) |
+| `src/refs/` | Ref resolver seam: `grammar.ts`, `resolve.ts`, `types.ts` (`recipe://`, `ar://`, receipt types) |
+| `src/contract/` | Wire-contract module: `index.ts`, `node-envelope.ts`, `node-projections.ts`, `session.ts` |
+| `src/contracts/` | `versioned-storage.ts` — versioned storage contract |
+| `tests/` | Committed tests: 35 `*.test.js` files, `*.typecheck.ts` compile tests, `src/` + `tests/` fixture subdirs |
+| `.github/workflows/` | `tests.yml` (PR + production push), `publish-development.yml`, `publish-staging.yml`, `publish-production.yml` |
+| `docs/` | `architecture.md`, `routes-services.md`, `usage-reference.md`, `migration-error-base.md`, `workflow-hard-cut-release.md`, `atlas/`, `agent-guide/`, `janitor/`, `plans/` |
+| `dist/` | Build output (generated, gitignored — never a design source) |
+| `node_modules/` | Dependencies (gitignored) |
+| `_worktrees/` | Linked git worktrees (untracked user scratch — do not touch) |
+
+## Entrypoints
+
+- **Package entry**: `src/index.ts` → built to `dist/index.js` /
+  `dist/index.d.ts`; imported as `import { dominus } from 'dominus-sdk-nodejs'`.
+  No subpath exports.
+- **Test entry**: `npm test` runs `npm run build && npm run test:types && node
+  --test tests/*.test.js`; type tests via `tsc -p tsconfig.type-tests.json`.
+- **Build/typecheck**: `npm run build` (`tsc`), `npm run typecheck` /
+  `npm run lint` (`tsc --noEmit`).
+- **CI**: `.github/workflows/tests.yml` (Node 20, `npm ci`, `npm test`) on
+  PR + push to `production`.
+- **Publish**: `.github/workflows/publish-production.yml` on push to
+  `production` (npm publish with NPM_TOKEN + trusted-publishing fallback).
+
+## Generated / scratch directories to avoid
+
+- `dist/` (build output), `node_modules/` (deps), `_worktrees/` (user worktrees).

package/docs/agent-guide/2026-08-25-2103-sdk-nodejs/03-api-surface.md

@@ -0,0 +1,59 @@
+# API surface
+
+Public surface is the `dominus` singleton exported from `src/index.ts`. Root
+shortcuts and namespace properties are wired there. Re-exported errors and
+crypto helpers are also part of the package surface.
+
+## Root-level shortcuts (on `dominus`)
+
+Secrets: `get`, `upsert`. DB: `listTables`, `queryTable`, `insertRow` (see the
+docblock in `src/index.ts`). These map to the `secrets` / `db` namespaces.
+
+## Namespaces (`src/namespaces/`, 28 files)
+
+| Namespace | File | Notes |
+|---|---|---|
+| secrets | `secrets.ts` | Secret presence/preview; root-level `get`/`upsert` shortcuts |
+| db | `db.ts` | DB queries/tables/rows |
+| redis | `redis.ts` | Redis get/set/keys/streams |
+| files | `files.ts` | File upload/download (category-scoped) |
+| auth | `auth.ts` | Auth users |
+| ddl | `ddl.ts` | Table DDL |
+| logs | `logs.ts` | `ingest`/`ingestBatch` (writes swallow), `tail`/`query` (reads propagate) |
+| portal | `portal.ts` | Portal sessions, `sendInvite` |
+| courier | `courier.ts` | Email sends |
+| health | `health.ts` | Health check |
+| secure | `secure.ts` | Secure-table access with audit (`query`, `reason`, `actor`) |
+| admin | `admin.ts` | Admin surfaces |
+| ai | `ai.ts` | Batch speech-to-text via `/api/agent/stt` on agent-runtime |
+| workflow | `workflow.ts` | Authority-backed `workflow.ensure` lifecycle |
+| jobs | `jobs.ts` | Job processing |
+| processor | `processor.ts` | Processor runs |
+| artifacts | `artifacts.ts` | Artifact V2 (`ar://` addressed) |
+| authority | `authority.ts` | Runs, timelines, verdicts, schedules, deploy registry |
+| browser | `browser.ts` | Browser automation; must use `/api/browser/*` with `useGateway: true` |
+| deployer | `deployer.ts` | Deploy records |
+| warden | `warden.ts` | Warden/credential surfaces |
+| stash | `stash.ts` | Primary storage surface: pointer-text get/put, versioned items, bookmarks, watchers |
+| stash-tables | `stash-tables.ts` | Stash managed tables |
+| recipes | `recipes.ts` | Recipe publish/get/list/validate |
+| platform | `platform.ts` | Platform groups/repos/policy decisions |
+| coder | `coder.ts` | Coder Runtime runs |
+| publisher | `publisher.ts` | Publisher channel pins/artifacts/builds |
+
+## Non-namespace public surface
+
+- `src/refs/resolve.ts` → `RefResolver` for `recipe://` and `ar://` refs;
+  receipt types in `src/refs/types.ts`.
+- Error exports from `src/index.ts`: `DominusError`, `AuthenticationError`,
+  `AuthorizationError`, `NotFoundError`, `ValidationError`, `ConflictError`,
+  `ServiceError`, `ConnectionError`, `TimeoutError`, `SecureTableError`, etc.
+- Crypto helpers: `hashPassword`, `hashPsk`, `generateToken`.
+- `DominusError.recoveryAction` accessor (recovery-action.ts) for D6 guidance.
+
+## Transport contract
+
+Namespace methods normalize input, then call `this.client.request` /
+`streamRequest` / `binaryUpload` / `binaryDownload` in `src/lib/client.ts`.
+Gateway-first route transforms and typed error/wire contracts live in
+`src/contract/*` and `src/contracts/versioned-storage.ts`.

package/docs/agent-guide/2026-08-25-2103-sdk-nodejs/04-data-state-and-storage.md

@@ -0,0 +1,36 @@
+# Data, state, and storage
+
+This SDK is a client library: it holds no server-side database of its own. All
+persistent state lives in platform services reached through the gateway.
+
+## In-process state (owned by this repo)
+
+| Surface | File | Notes |
+|---|---|---|
+| `dominusCache` | `src/lib/cache.ts` | In-process encrypted cache; encryption key set from `DOMINUS_TOKEN` at import. Backs the service-JWT cache and circuit-breaker helpers. |
+| Service-JWT cache | `src/lib/client.ts` / `cache.ts` | Minted service JWT cached 55 min (`JWT_CACHE_TTL = 3300000`), refreshed 5 min before expiry via `ensureValidJwt` mutex. `mintServiceJwt({ forceRefresh: true })` is the cache-bypass hook. |
+| Page-rules cache | `src/lib/page-rules.ts` | Portal JWT / page-access local cache |
+| User-session cache | `src/lib/user-session.ts` | Portal session local cache |
+
+## Platform storage surfaces the SDK talks to
+
+- **`dominus.stash.*`** — the primary storage surface. Pointer-text
+  `get`/`put`, versioned items, bookmarks, watchers, scope/role resolution
+  (`src/namespaces/stash.ts`, `stash-tables.ts`).
+- **Building blocks** — `redis`, `db`, `files`, `artifacts` are lower-level
+  building blocks underneath the stash facade (`docs/architecture.md` §2a).
+
+## State-safety rules
+
+- Reads propagate; only *writes* swallow. `logs.ingest` / `ingestBatch` catch
+  and fall back to local logging on purpose; `logs.tail` and every other read
+  must let the error throw (v11.0.0 breaking change). Do not re-add a catch to
+  a read.
+- Ref resolution receipts preserve the answering service's own response,
+  unmodified (`src/refs/types.ts`). No provenance field is shared across
+  variants.
+
+## Migrations
+
+None — this is a library. Schema/DDL lives behind `dominus.ddl.*` /
+`dominus.db.*` for platform tables, not in this repo.

package/docs/agent-guide/2026-08-25-2103-sdk-nodejs/05-integrations-and-runtime.md

@@ -0,0 +1,36 @@
+# Integrations and runtime
+
+## Runtime
+
+- Node.js `>=18`, ESM (`"type": "module"`).
+- Single export entry: `package.json` → `exports["."]` → `dist/index.js`.
+
+## Environment variables (by category, no secret values)
+
+| Category | Variable | Resolved in |
+|---|---|---|
+| Auth (PSK) | `DOMINUS_TOKEN` | `src/lib/config.ts`; used to set the cache encryption key at import |
+| Scope | `DOMINUS_PROJECT` | project-scope selection for gateway calls |
+| Gateway | `DOMINUS_GATEWAY_URL` (and related) | `src/lib/config.ts` gateway/proxy config |
+
+## External services / platform integrations
+
+- **Gateway** — the SDK mints a service JWT from `DOMINUS_TOKEN` (PSK) via the
+  gateway `/jwt/mint` route, then calls gateway `/svc/*` routes. Route
+  transforms and wire contracts are defined in namespace code + `src/contract/*`.
+- **Service-JWT lifetime** — `dominus-jwt-worker` `JWT_EXPIRY_SECONDS = 3600`
+  (1 hour); SDK cache TTL is 55 min with a 5-min refresh window. Do not regress
+  this TTL without first raising the jwt-worker expiry.
+- **Browser automation** — `dominus.browser.*` must use SDK `/api/browser/*`
+  paths with `useGateway: true`, which the gateway exposes as authenticated
+  `/svc/browser/*`. Never point SDK methods at worker-local `/runs/*` routes
+  directly.
+- **AI/STT** — `dominus.ai.stt` → `/api/agent/stt` on agent-runtime (no legacy
+  WebSocket STT path). Not server-only-Node.
+
+## Cross-repo / domain boundary
+
+- This repo crosses Dominus platform contracts (gateway routes, worker wire
+  shapes). Contract-sensitive findings route to `dominus-expert`.
+- CareBridge product surfaces (portal, courier) are thin client calls; product
+  behavior is backend-owned.

package/docs/agent-guide/2026-08-25-2103-sdk-nodejs/06-workflows-commands-and-ci.md

@@ -0,0 +1,45 @@
+# Workflows, commands, and CI
+
+All commands are defined in `package.json` `scripts`.
+
+## Commands
+
+| Command | Script | What it runs |
+|---|---|---|
+| Install | `npm ci` / `npm install` | Install deps (`bcryptjs`, `jose`; dev: `typescript`, `@types/node`, `@types/bcryptjs`) |
+| Build | `npm run build` | `tsc` → `dist/` |
+| Typecheck | `npm run typecheck` | `tsc --noEmit` |
+| Type tests | `npm run test:types` | `tsc -p tsconfig.type-tests.json` |
+| Lint | `npm run lint` | `tsc --noEmit` (typecheck) |
+| Test | `npm test` | `npm run build && npm run test:types && node --test tests/*.test.js` |
+| Clean | `npm run clean` | `rm -rf dist` |
+
+## Fast local validation
+
+```bash
+npm run build && npm run lint
+```
+
+## Full validation
+
+```bash
+npm test
+```
+
+HEAD commit `4f7b377` reports 179 tests green (35 `.test.js` files + type
+tests). `tests/` also contains `src/` and `tests/` fixture subdirs used by the
+runtime tests.
+
+## CI workflows
+
+| Workflow | Trigger | Signal |
+|---|---|---|
+| `tests.yml` | PR + push to `production` | Node 20, `npm ci`, `npm test` |
+| `publish-development.yml` | push to `development` | npm publish (development lane) |
+| `publish-staging.yml` | push to `staging` | npm publish (staging lane) |
+| `publish-production.yml` | push to `production` | `npm run build` + `npm test`, then npm publish with `NPM_TOKEN` (GitHub Environment `production`) and a trusted-publishing fallback; skips if the version already exists |
+
+## Known flaky / slow checks
+
+None reported at snapshot time. `npm test` includes a build, so expect it to be
+slower than a pure runtime test run.

package/docs/agent-guide/2026-08-25-2103-sdk-nodejs/07-operations-release-and-live-proof.md

@@ -0,0 +1,43 @@
+# Operations, release, and live proof
+
+## Deployment lane
+
+This is a library, not a deployed service. "Deploy" is npm publication gated
+by git branch:
+
+- Push to `production` → `.github/workflows/publish-production.yml` → build +
+  test, then `npm publish` (requires GitHub Environment `production` with
+  `NPM_TOKEN`). Falls back to `--provenance` trusted publishing if the token
+  publish fails, and skips when the version is already on the registry.
+- `development` / `staging` lanes use `publish-development.yml` /
+  `publish-staging.yml` respectively.
+
+## Release files and version rules
+
+- `package.json` `version` is the canonical release version (11.0.7 at
+  snapshot time).
+- `CHANGELOG.md` documents per-version behavior changes (e.g. v11.0.0 breaking:
+  `logs.tail` reads propagate errors).
+- Version bumps are deliberate commits on the branch (HEAD `4f7b377` bumps
+  11.0.6 → 11.0.7).
+- Release metadata should not be hand-set to a version already present on the
+  npm registry (the publish workflow guards this).
+
+## Live proof
+
+- `npm view dominus-sdk-nodejs@<version>` against the npm registry confirms a
+  published release.
+- Package install: `npm install dominus-sdk-nodejs` and import
+  `import { dominus } from 'dominus-sdk-nodejs'`.
+
+## Rollback / recovery
+
+- Fix-forward: a corrected version bump + push to `production`.
+- Cache recovery: `mintServiceJwt({ forceRefresh: true })` drops a rejected
+  cached JWT and mints fresh (key-rotation recovery).
+
+## What counts as done
+
+- `npm run build` + `npm run lint` + `npm test` green locally.
+- For releases: version bumped in `package.json` + `CHANGELOG.md` entry, push to
+  `production`, publish workflow completes or reports already-published.