dominus-sdk-nodejs 11.0.6 → 11.0.8

package/docs/agent-guide/2026-08-25-2103-sdk-nodejs/08-security-privacy-and-secrets.md

@@ -0,0 +1,42 @@
+# Security, privacy, and secrets
+
+## Auth boundaries
+
+- Service auth: `DOMINUS_TOKEN` (PSK) → minted service JWT from gateway
+  `/jwt/mint`, cached 55 min (`JWT_CACHE_TTL = 3300000`), refreshed 5 min
+  before expiry via the in-process mutex in `ensureValidJwt`
+  (`src/lib/client.ts`).
+- Namespace methods may use a caller-provided user JWT (`userToken` option)
+  where backend semantics require it (e.g. portal / user-scoped calls).
+- Identity families are distinct: service token, service JWT, portal user JWT,
+  client JWT, and selected-scope operator token are not interchangeable.
+
+## Secret / config resolution surfaces
+
+- `DOMINUS_TOKEN` is read at import in `src/index.ts` and used to set the
+  `dominusCache` encryption key.
+- Secret values live in `src/lib/config.ts` env resolution. Never log or paste
+  `DOMINUS_TOKEN`, user tokens, or secret values.
+- `dominus.secrets.*` exposes presence/preview surfaces that avoid returning
+  secret values; `admin` surfaces use persisted root-role patterns.
+
+## Error handling security notes
+
+- Every error thrown from `getServiceJwt` carries `endpoint='/jwt/mint'` so
+  downstream consumers (Summit etc.) can classify by `DominusError.endpoint`.
+- Service-side 401s (anything that's not `/portal/auth/*`) must NOT be
+  laundered into user-session expiry by callers (kernel rule in
+  `dominus-platform/docs/DOMINUS_CRITICAL_PATTERNS.md` §1).
+
+## PHI / sensitive-data rules
+
+- Never write PHI, secrets, credentials, cookies, raw reports, DICOM bytes,
+  screenshots, HARs, or raw response bodies into docs.
+- Log writes (`logs.ingest` / `ingestBatch`) swallow on purpose — a log write
+  must never break the caller. Log reads (`logs.tail`, `logs.query`) propagate
+  errors so a broken query is not indistinguishable from an empty result.
+
+## What must never be logged, pasted, or written into docs
+
+- `DOMINUS_TOKEN`, user tokens, secrets from `stash`/`secrets`/`warden`,
+  raw gateway response bodies containing PHI.

package/docs/agent-guide/2026-08-25-2103-sdk-nodejs/09-known-risks-and-debt.md

@@ -0,0 +1,37 @@
+# Known risks and debt
+
+## Stale or inconsistent docs (fixed in this pass)
+
+- `docs/agent-guide/current.md` pointed at the 2026-06-27 snapshot while
+  `INDEX.md` pointed at 2026-08-04 — inconsistent; updated to this snapshot.
+- `CLAUDE.md` pointed at `2026-06-27-0849-sdk-orient/` and its old audit while
+  README pointed at 2026-08-04 — updated to this snapshot.
+- `docs/agent-guide/2026-06-27-0849-sdk-orient/` and
+  `2026-08-04-sdk-nodejs/` (partial: only 00/01/03/10) are retained as history.
+
+## Aging docs to verify against source
+
+- `docs/architecture.md`, `docs/routes-services.md`, `docs/usage-reference.md`
+  — authored over time; verify route/namespace/behavior claims against `src/`
+  before trusting. The v6.6.0-era claim "no committed tests" is already
+  superseded (`tests/` is committed).
+
+## Fragile / slow checks
+
+- `npm test` includes a full `tsc` build, so it is slower than a pure runtime
+  run; type tests require `tsconfig.type-tests.json`.
+
+## Cleanup candidates (deferred)
+
+- `dist/` and `node_modules/` are gitignored generated residue — safe to clean
+  (`npm run clean` for `dist/`) but deferred under dirty-tree policy (untracked
+  `_worktrees/` present in the checkout).
+- `_worktrees/s4-contract` and `_worktrees/t2-sdk-docs` are linked git
+  worktrees registered with the repo but untracked from the main tree; they are
+  user work and must not be touched without approval.
+
+## Known blockers / links
+
+- See `docs/janitor/2026-08-25-2103-sdk-nodejs-cleanup-audit.md` for the full
+  drift and approval queue.
+- `docs/atlas/2026-08-04-sdk-nodejs-blockers.md` for the prior blocker record.

package/docs/agent-guide/2026-08-25-2103-sdk-nodejs/10-agent-playbook.md

@@ -0,0 +1,51 @@
+# Agent playbook
+
+## If you are changing X, read Y first
+
+| If you are changing… | Read first |
+|---|---|
+| A namespace method | `src/namespaces/<name>.ts` + the wiring in `src/index.ts`; keep methods thin, transport via `this.client.request` / `streamRequest` / `binaryUpload` / `binaryDownload` |
+| The transport / request lifecycle | `src/lib/client.ts`; preserve the base64 request protocol, legacy base64 response envelopes, JWT caching, and retry behavior |
+| Errors | `src/lib/errors.ts`; new throws on service-auth paths must pass the `endpoint` argument |
+| `recipe://` / `ar://` refs | `src/refs/resolve.ts`, `src/refs/types.ts`; receipts preserve the answering service's response unmodified |
+| Wire contracts | `src/contract/*.ts`, `src/contracts/versioned-storage.ts` |
+| Public surface | `src/index.ts`; add new namespace/type exports there and update `docs/usage-reference.md`, `docs/routes-services.md` |
+| Browser automation | `src/namespaces/browser.ts`; use `/api/browser/*` with `useGateway: true`, never worker-local `/runs/*` |
+
+## If validation fails, try Z
+
+1. `npm run build` first — `dist/` must compile before `npm test`.
+2. Check env: `DOMINUS_TOKEN` and `DOMINUS_PROJECT` must be set before the SDK
+   singleton is imported for live calls; type/tests should not require them.
+3. `npm run lint` (`tsc --noEmit`) to isolate type errors from runtime errors.
+4. If runtime tests fail on environment-dependent calls, report that explicitly
+   in change notes rather than hiding it.
+
+## Common traps
+
+- **Reads must throw, writes must swallow.** Never add a `catch { return [] }`
+  to a read (`logs.tail`, `logs.query`, or any non-ingest call). `ingest` /
+  `ingestBatch` swallow on purpose.
+- **Do not regress the JWT TTL.** SDK caches the service JWT for 55 min
+  (`JWT_CACHE_TTL = 3300000`) against a 1-hour jwt-worker expiry. Use
+  `mintServiceJwt({ forceRefresh: true })` for cache-bypass, not direct
+  `dominusCache` poking.
+- **Do not use `dist/` for design decisions** — `src/` is the source of truth.
+- **Do not point browser methods at `/runs/*` directly.**
+- **Do not launder service-side 401s into user-session expiry** (kernel rule).
+
+## Which Kyle skill to use
+
+| Need | Skill |
+|---|---|
+| Repo docs / cleanup / janitor | `kyle-janitor` |
+| Truth maps / atlas | `kyle-atlas` |
+| Behavior bug | `kyle-diagnose` / `kyle-fix` |
+| Dominus platform contract changes | `dominus-expert` |
+
+## Handoff expectations
+
+- Never commit/push from janitor or docs work in this repo unless explicitly
+  asked; leave changes uncommitted for review.
+- When docs expose stale platform truth, route the finding to `kyle-atlas` or
+  `dominus-expert` rather than rewriting worker-owned facts inline.

package/docs/agent-guide/INDEX.md

@@ -1,14 +1,25 @@
 # Agent Guide Index
 
-Last updated: 2026-08-04 local
-Current snapshot: `2026-08-04-sdk-nodejs/00-reading-order.md`
+Last updated: 2026-08-25 21:03 local
+Current snapshot: `2026-08-25-2103-sdk-nodejs/00-reading-order.md`
+
+## Use This When
+
+Working in `dominus-sdk-nodejs`: changing a namespace, transport, error, ref
+resolution, or release flow; adding public surface; or validating a change.
+The published package entry point and `src/` remain authoritative.
 
 ## Read Order
 
-1. `2026-08-04-sdk-nodejs/00-reading-order.md`
-2. `2026-08-04-sdk-nodejs/01-purpose-and-boundaries.md`
-3. `2026-08-04-sdk-nodejs/03-api-surface.md`
-4. `2026-08-04-sdk-nodejs/10-agent-playbook.md`
+1. `2026-08-25-2103-sdk-nodejs/00-reading-order.md`
+2. `2026-08-25-2103-sdk-nodejs/01-purpose-and-boundaries.md`
+3. `2026-08-25-2103-sdk-nodejs/03-api-surface.md`
+4. `2026-08-25-2103-sdk-nodejs/10-agent-playbook.md`
+
+## Snapshot History
 
-The published package entry point and `src/` remain authoritative. Historical
-guide packs are retained for prior release context.
+| Snapshot | Reason | Notes |
+|---|---|---|
+| `2026-08-25-2103-sdk-nodejs` | Current | v11.0.7 at `4f7b377`; 28 namespaces, full 00–10 pack |
+| `2026-08-04-sdk-nodejs` | Prior | Partial pack (00/01/03/10); v10.x-era truth |
+| `2026-06-27-0849-sdk-orient` | Historical | v6.6.0-era orientation pack; superseded |

package/docs/agent-guide/current.md

@@ -1,19 +1,20 @@
 # Current Agent-Guide Snapshot
 
-Latest snapshot: `2026-06-27-0849-sdk-orient/00-reading-order.md`
+Latest snapshot: `2026-08-25-2103-sdk-nodejs/00-reading-order.md`
 
-Generated 2026-06-27 from SDK v6.6.0 (`package.json`) on branch `production`.
+Generated 2026-08-25 from SDK v11.0.7 (`package.json`) on branch `production`
+at commit `4f7b377`.
 
 ## Top Five Facts To Refresh Before Editing
 
-1. **Version + changelog.** Confirm `package.json` `version` and the top of
-   `CHANGELOG.md`; this pack was written at `6.6.0`.
-2. **Namespace count.** `src/namespaces/` had 27 files, each wired as a
+1. **Version + changelog.** `package.json` `version` is `11.0.7`; the top of
+   `CHANGELOG.md` is the current behavior record (v11.0.0 breaking:
+   `logs.tail` reads propagate errors).
+2. **Namespace count.** `src/namespaces/` has 28 files, each wired as a
    `public readonly` property in `src/index.ts`. Re-count before claiming a
    surface is missing.
-3. **Tests exist.** `tests/` has 24 test files run by `npm test`. The older
-   claim in `docs/architecture.md` §10 / `CLAUDE.md` ("no committed tests") was
-   stale and is corrected in this pass.
+3. **Tests exist and are current.** `tests/` has 35 `.test.js` files plus type
+   tests; HEAD `4f7b377` reports 179 tests green via `npm test`.
 4. **Storage rule.** `dominus.stash.*` is the primary storage surface;
    `redis`/`db`/`files`/`artifacts` are building blocks (see
    `docs/architecture.md` §2a).

package/docs/atlas/INDEX.md

@@ -1,6 +1,10 @@
 # Atlas Index
 
-Last updated: 2026-08-04 local
+Last updated: 2026-08-25 local
+
+Read first: the current agent-guide pack
+`docs/agent-guide/2026-08-25-2103-sdk-nodejs/00-reading-order.md` and the latest
+cleanup audit `docs/janitor/2026-08-25-2103-sdk-nodejs-cleanup-audit.md`.
 
 Latest snapshot:
 [truthmap](2026-08-04-sdk-nodejs-truthmap.md),

package/docs/janitor/2026-08-25-2103-sdk-nodejs-cleanup-audit.md

@@ -0,0 +1,112 @@
+# Janitor Cleanup Audit: dominus-sdk-nodejs
+
+Generated: 2026-08-25 21:03 local
+Target repo: `C:\developer\codingroot\repos\dominus_active\dominus-sdk-nodejs`
+Git root: same as target repo
+Branch/status: `production` @ `4f7b377`; working tree has untracked
+`_worktrees/` (linked git worktrees) → **dirty_limited** per janitor wave
+policy: docs-only writes, no broad generated cleanup, no edits to user work.
+
+## Summary
+
+Created a fresh source-backed agent-guide snapshot (v11.0.7, commit `4f7b377`),
+wired it into the repo read path (README, CLAUDE.md, agent-guide INDEX/current,
+atlas INDEX), and fixed stale pointer drift (CLAUDE.md and current.md were
+pointing at the 2026-06-27 snapshot). No generated cleanup was applied because
+the checkout is dirty (untracked `_worktrees/`); cleanup candidates are queued
+for approval.
+
+## Executive Actions Applied
+
+| Action | Path | Why safe | Verification |
+|---|---|---|---|
+| New agent-guide snapshot | `docs/agent-guide/2026-08-25-2103-sdk-nodejs/` (00–10) | Source-backed from `src/`, `package.json`, workflows, CHANGELOG | `git diff --check`; paths verified against repo listing |
+| Re-point current.md | `docs/agent-guide/current.md` | Was stale (June snapshot) | Consistent with INDEX.md |
+| Re-point CLAUDE.md | `CLAUDE.md` | Was stale (June snapshot/audit) | Consistent with README |
+| Re-point README.md | `README.md` | Pointer line only | Points to new snapshot + audit |
+| Update atlas index | `docs/atlas/INDEX.md` | Add read-first surfaces | Points to new snapshot + audit |
+
+## Docs Written
+
+| File | Purpose | Source-backed by |
+|---|---|---|
+| `docs/agent-guide/2026-08-25-2103-sdk-nodejs/00-reading-order.md` | Read order + stale-doc map | `package.json`, `src/`, workflows |
+| `.../01-purpose-and-boundaries.md` | Purpose, ownership, boundary | `src/index.ts`, `package.json` |
+| `.../02-repo-map-and-entrypoints.md` | Directory + entrypoint map | repo listing, `package.json` scripts |
+| `.../03-api-surface.md` | Namespace/API table | `src/namespaces/*`, `src/index.ts` |
+| `.../04-data-state-and-storage.md` | State surfaces + safety rules | `src/lib/cache.ts`, `client.ts`, CHANGELOG v11.0.0 |
+| `.../05-integrations-and-runtime.md` | Gateway/auth/env integrations | `src/lib/client.ts`, `config.ts`, CLAUDE.md |
+| `.../06-workflows-commands-and-ci.md` | Commands + CI map | `package.json`, `.github/workflows/*` |
+| `.../07-operations-release-and-live-proof.md` | Release lane + live proof | `.github/workflows/publish-production.yml` |
+| `.../08-security-privacy-and-secrets.md` | Auth/secrets/PHI rules | `src/lib/client.ts`, `errors.ts` |
+| `.../09-known-risks-and-debt.md` | Stale docs, cleanup candidates | current repo state |
+| `.../10-agent-playbook.md` | Task→read-first, traps, skills | CLAUDE.md, `src/` |
+| `docs/agent-guide/INDEX.md` | Current snapshot pointer + history | snapshot set |
+| `docs/agent-guide/current.md` | Latest snapshot + top-5 facts | `package.json`, `src/namespaces/` |
+| `docs/janitor/2026-08-25-2103-sdk-nodejs-cleanup-audit.md` | This audit | this run |
+
+## Drift Findings
+
+| Finding | Evidence | Risk | Recommendation | Approval needed |
+|---|---|---|---|---|
+| `CLAUDE.md` pointed at 2026-06-27 snapshot/audit | `git show` of file | Agents orient from stale v6.6-era pack | Re-point (done) | No |
+| `current.md` pointed at 2026-06-27 while INDEX pointed at 2026-08-04 | read both | Confusing read path | Re-point (done) | No |
+| `docs/architecture.md` / `routes-services.md` / `usage-reference.md` aging | last edits precede 08-04 pack | Stale route/behavior claims | Verify against `src/` in a later pass | No |
+| `dist/` + `node_modules/` generated residue | `.gitignore` | Disk noise only | `npm run clean` for `dist/`; `npm ci`/reinstall for `node_modules` | Yes (dirty tree) |
+
+## Stale Or Conflicting Docs
+
+| Doc | Problem | Stronger source | Proposed action |
+|---|---|---|---|
+| `docs/agent-guide/2026-06-27-0849-sdk-orient/` | v6.6.0-era, superseded | current snapshot | Retain as history |
+| `docs/agent-guide/2026-08-04-sdk-nodejs/` | Partial (00/01/03/10 only) | current snapshot | Retain as history |
+
+## Orphan / Generated / Scratch Candidates
+
+| Path | Evidence | Proposed action | Safe now? |
+|---|---|---|---|
+| `dist/` | gitignored build output (`npm run clean`) | Remove | No (dirty tree) |
+| `node_modules/` | gitignored deps | Remove/reinstall | No (dirty tree) |
+| `_worktrees/` | linked git worktrees (untracked) | Leave alone — user work | No (never) |
+
+## Auto-Cleanup Performed
+
+None. The working tree has untracked `_worktrees/`, so per janitor dirty-tree
+policy broad generated cleanup was skipped entirely. `dist/` and
+`node_modules/` remain untouched.
+
+## Expert Review Queue
+
+| Candidate | Why expert should view it first | Suggested expert | First review question |
+|---|---|---|---|
+| `_worktrees/s4-contract`, `_worktrees/t2-sdk-docs` | Linked git worktrees owned by kteam/cu lanes; removal or archival affects in-flight work | `dominus-expert` | Are these worktree branches still active, and should any be merged/cleaned? |
+| Gateway/worker wire-contract claims in aging docs | Crosses Dominus platform contracts | `dominus-expert` | Do `docs/routes-services.md` / `architecture.md` still match `/svc/*` reality? |
+
+## Worktree / Branch / Plan Residue
+
+| Item | Evidence | Proposed action | Owner |
+|---|---|---|---|
+| `_worktrees/s4-contract` | `git worktree list` — branch `kteam/dominus-onboarding-build/item4-invite` @ `6ec0e7b` | Leave; queue for expert | kteam |
+| `_worktrees/t2-sdk-docs` | `git worktree list` — branch `cu/t2-sdk-docs-node-20260818` @ `b794fb0` | Leave; queue for expert | cu |
+| Local branches (`codex/*`, `cu/*`, `kteam/*`, `s4-contract`) | `git branch -a` | Keep; not this run's call to prune | lane owners |
+
+## Approval Queue
+
+- [ ] `dist/` removal (`npm run clean`) — generated build residue — verify `npm run build` regenerates.
+- [ ] `node_modules/` removal/reinstall — generated deps — verify `npm ci` + `npm test` green.
+- [ ] Worktree pruning/archival for `_worktrees/s4-contract` and `_worktrees/t2-sdk-docs` — in-flight lane work — verify branch status first.
+
+## Not Touching
+
+- `_worktrees/` — untracked user work; hard rule.
+- `docs/plans/` — historical plans.
+- Any tracked source or CI file.
+- Previous agent-guide snapshots and janitor audits.
+
+## Follow-Up Skills
+
+| Need | Skill | First action |
+|---|---|---|
+| Verify aging platform docs against source | `kyle-atlas` | Re-run truthmap for `docs/routes-services.md` / `architecture.md` |
+| Confirm worktree lane status | `dominus-expert` | Inspect kteam/cu branches |
+| Refresh knowledge for this repo | `kyle-learn` | Move durable facts to `.claude/knowledge` |

package/docs/routes-services.md

@@ -32,6 +32,7 @@ Audited commands: **~450** (hand-counted) across **27** top-level namespace file
 | `processor-service` | 3 | dominus.processor | 3 | HTTP API routes via Dominus client. |
 | `sync-worker` | 2 | dominus.sync | 2 | HTTP API routes via Dominus client. |
 | `local-jwt` | 1 | dominus.auth | 1 | Local JWT parsing/validation helpers in auth namespace. |
+| `ref-resolver` | 2 | dominus.refs | 3 | `ar://` → artifact-worker V2 retrieve; `recipe://` → stash `get` probe with recipe-worker fall-through. |
 | `retired-stt` | 0 | (retired) | 0 | Legacy streaming STT namespace/routes are removed in hard cutover. |
 
 ## Route Prefix Mapping
@@ -58,6 +59,9 @@ Audited commands: **~450** (hand-counted) across **27** top-level namespace file
 | `/api/job/*` | jobs | `job-worker` |
 | `/api/processor/*` | processor | `processor-service` |
 | `/api/artifact/*` | artifacts | `artifact-worker` |
+| `/api/artifact/v2/retrieve` | refs (ar:// lane) | `artifact-worker` |
+| `/svc/stash/get` | refs (recipe:// stash lane) | `stash-worker` |
+| `/api/recipe/recipes/*` | refs (recipe:// fall-through lane) | `recipe-worker` |
 | `/svc/stash/tables/*` | stash.tables | `stash-worker` |
 | `/api/rag/*, /api/agent/*, /api/llm/*, /api/results/*, /api/orchestration/*, /api/session/*` | ai, ai.rag, ai.tools, ai.workflow, ai.results | `agent-runtime` |
 | `/api/workflow/*` | workflow | `workflow-manager` |
@@ -77,4 +81,5 @@ Audited commands: **~450** (hand-counted) across **27** top-level namespace file
 ## Coverage Notes
 
 - Gateway routing is enabled per method via `useGateway: true` in namespace implementations; direct calls still target `/api/*` and are transformed by the client when gateway mode is on.
+- `dominus.refs.resolve` is the two-lane ref overlay: `ar://` refs cross the wire verbatim to `POST /api/artifact/v2/retrieve`; `recipe://` refs probe `POST /svc/stash/get` and fall through to `GET /api/recipe/recipes/{type}/{name}` on a typed `stash.not_found.*` / `stash.forbidden.scope_not_allowed` miss. `dominus.refs.parse` is local grammar with no I/O.
 - The exhaustive per-command listing with params/returns/routes is documented in [usage-reference.md](./usage-reference.md).

package/docs/usage-reference.md

@@ -696,3 +696,18 @@ Legacy-named helpers still exist for stable call sites; they **call `POST /api/a
 | `dominus.artifacts.unwatchV2` | `options: Pick<V2WatchOptions, 'watcherName'> & V2ArtifactSelectorOptions` | `Promise<Record<string, unknown>>` | `POST /api/artifact/v2/unwatch` | Remove a watcher. |
 | `dominus.artifacts.listV2` | `options?: V2ListArtifactOptions` | `Promise<Record<string, unknown>>` | `POST /api/artifact/v2/list` | List addressed artifact heads. |
 | `dominus.artifacts.deleteV2` | `options: V2DeleteArtifactOptions` | `Promise<Record<string, unknown>>` | `POST /api/artifact/v2/delete` | Delete or tombstone an addressed artifact selector. |
+
+## dominus.refs
+
+Source: `src/refs/resolve.ts` (RefResolver)
+
+The `dominus.refs` namespace is the ref resolver overlay. It resolves `ar://` and
+`recipe://` refs to service-native receipts; `stash://`, `warden://`, and `wf://`
+throw `ref.scheme.unresolvable` naming the missing contract and its owning service.
+`parse` is pure grammar with no I/O; `resolve` performs transport and returns a
+`ResolvedRef` discriminated on the answering service (`source`).
+
+| Command | Params | Returns | Route | What it does |
+|---|---|---|---|---|
+| `dominus.refs.parse` | `ref: string` | `KernelRef` | *(local, no I/O)* | Parse a ref into its discriminated `KernelRef` (ar / recipe / unresolvable). |
+| `dominus.refs.resolve` | `ref: string, options?: ResolveOptions` | `Promise<ResolvedRef>` | `POST /api/artifact/v2/retrieve` (ar://) · `POST /svc/stash/get` → `GET /api/recipe/recipes/{type}/{name}` (recipe://) | Resolve a ref to its service-native receipt; `ar://` crosses the wire verbatim, `recipe://` probes the stash lane and falls through to recipe-worker on a typed miss. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dominus-sdk-nodejs",
-  "version": "11.0.6",
+  "version": "11.0.8",
   "description": "Node.js SDK for the Dominus gateway-first platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",