dominus-sdk-nodejs 11.0.5 → 11.0.7

package/dist/refs/grammar.js

@@ -0,0 +1,179 @@
+/**
+ * Ref grammar — the single Node-side definition of every ref scheme's grammar.
+ *
+ * `parse()` owns grammar and does NO I/O: no network, no client, no env. Scope,
+ * tier, authorization, and existence are validated by the owning services, never
+ * here. `routeFor()` is the serialization inverse used by the transport layer
+ * (and by the E3 round-trip totality property) to rebuild a recipe route path.
+ *
+ * Schemes:
+ *   - `ar://{group}/{owner}/{environment}/{kind}/{artifactKey}[@vN]`  (5-segment v2)
+ *   - `ar://{projectSlug}/{environment}/{namespace}/{artifactKey}[@vN]` (4-segment legacy)
+ *   - `recipe://{type}/{name}[@{vN|N|head|latest}][?tier={tier}]`
+ *   - `stash://`, `warden://`, `wf://` parse to an `unresolvable` variant carrying
+ *     the missing service-owned contract and its owning service.
+ *
+ * Invalid grammar throws `ref.grammar.invalid`.
+ */
+import { DominusError, ValidationError } from '../lib/errors.js';
+const AR_PREFIX = 'ar://';
+const RECIPE_PREFIX = 'recipe://';
+/** `type`/`name` charset, mirrors `dominus-recipe-worker/src/routes/recipes.ts` `assertName`. */
+const RECIPE_NAME_CHARSET = /^[a-z][a-z0-9_-]{0,127}$/;
+/** `ar://` version suffix is `@vN` only (mirrors `parseArtifactRef`). */
+const AR_VERSION_SUFFIX_RE = /^v\d+$/;
+const UNRESOLVABLE = {
+    stash: {
+        missingContract: 'no server-owned stash:// grammar; only the kind registry knows which scope axes a kind requires',
+        owningService: 'stash-worker',
+    },
+    warden: {
+        missingContract: "admin-only (allowed_systems: ['admin']) and no published grammar",
+        owningService: 'warden',
+    },
+    wf: {
+        missingContract: 'Execution plane',
+        owningService: 'Authority / workflow-manager',
+    },
+};
+function grammarInvalid(detail) {
+    throw new ValidationError(`Invalid ref: ${detail}`, 400, {
+        code: 'ref.grammar.invalid',
+        category: 'validation',
+    });
+}
+/** `head`, `latest`, or a positive integer (`vN` / bare `N`) — mirrors the recipe route. */
+function isValidRecipeVersion(raw) {
+    if (raw === 'head' || raw === 'latest') {
+        return true;
+    }
+    const numeric = raw.startsWith('v') ? raw.slice(1) : raw;
+    if (!/^\d+$/.test(numeric)) {
+        return false;
+    }
+    const value = Number(numeric);
+    return Number.isInteger(value) && value >= 1;
+}
+function parseAr(input) {
+    const raw = input.slice(AR_PREFIX.length);
+    if (!raw) {
+        return grammarInvalid('ar:// ref has no path');
+    }
+    // Optional `@vN` version suffix, split on the first `@` (mirrors parseArtifactRef).
+    let path = raw;
+    const atIndex = raw.indexOf('@');
+    if (atIndex !== -1) {
+        const suffix = raw.slice(atIndex + 1);
+        if (!AR_VERSION_SUFFIX_RE.test(suffix)) {
+            return grammarInvalid(`ar:// version suffix "@${suffix}" must be @vN`);
+        }
+        path = raw.slice(0, atIndex);
+    }
+    const segments = path.split('/');
+    if (segments.length !== 5 && segments.length !== 4) {
+        return grammarInvalid(`ar:// ref must have 5 (v2) or 4 (legacy) segments, got ${segments.length}`);
+    }
+    if (segments.some((segment) => segment === '')) {
+        return grammarInvalid('ar:// ref has an empty segment');
+    }
+    return { scheme: 'ar', ref: input };
+}
+function parseRecipe(input) {
+    let rest = input.slice(RECIPE_PREFIX.length);
+    if (!rest) {
+        return grammarInvalid('recipe:// ref has no path');
+    }
+    // Optional `?tier=` query, passed through verbatim.
+    let tier;
+    const queryIndex = rest.indexOf('?');
+    if (queryIndex !== -1) {
+        const query = rest.slice(queryIndex + 1);
+        rest = rest.slice(0, queryIndex);
+        if (!query.startsWith('tier=') || query.length === 'tier='.length) {
+            return grammarInvalid(`recipe:// query must be "?tier=<value>", got "${query}"`);
+        }
+        tier = query.slice('tier='.length);
+    }
+    // Optional version suffix `@vN | @N | @head | @latest`.
+    let version;
+    const atIndex = rest.indexOf('@');
+    if (atIndex !== -1) {
+        version = rest.slice(atIndex + 1);
+        rest = rest.slice(0, atIndex);
+        if (!isValidRecipeVersion(version)) {
+            return grammarInvalid(`recipe:// version "@${version}" is not @vN, @N, @head, or @latest`);
+        }
+    }
+    const slashIndex = rest.indexOf('/');
+    if (slashIndex === -1) {
+        return grammarInvalid('recipe:// ref must be {type}/{name}');
+    }
+    const type = rest.slice(0, slashIndex);
+    const name = rest.slice(slashIndex + 1);
+    if (!RECIPE_NAME_CHARSET.test(type)) {
+        return grammarInvalid(`recipe:// type "${type}" must match ${RECIPE_NAME_CHARSET}`);
+    }
+    if (!RECIPE_NAME_CHARSET.test(name)) {
+        return grammarInvalid(`recipe:// name "${name}" must match ${RECIPE_NAME_CHARSET}`);
+    }
+    const result = { scheme: 'recipe', type, name };
+    if (version !== undefined) {
+        result.version = version;
+    }
+    if (tier !== undefined) {
+        result.tier = tier;
+    }
+    return result;
+}
+/**
+ * Parse a ref into a discriminated `KernelRef`. Pure and total over the scheme:
+ * valid `ar://` / `recipe://` refs parse to their variants, `stash://` /
+ * `warden://` / `wf://` parse to `unresolvable`, and anything else throws
+ * `ref.grammar.invalid`.
+ */
+export function parse(ref) {
+    const input = String(ref);
+    if (!input) {
+        return grammarInvalid('ref is empty');
+    }
+    if (input.startsWith(AR_PREFIX)) {
+        return parseAr(input);
+    }
+    if (input.startsWith(RECIPE_PREFIX)) {
+        return parseRecipe(input);
+    }
+    if (input.startsWith('stash://')) {
+        return { scheme: 'unresolvable', attemptedScheme: 'stash', ...UNRESOLVABLE.stash };
+    }
+    if (input.startsWith('warden://')) {
+        return { scheme: 'unresolvable', attemptedScheme: 'warden', ...UNRESOLVABLE.warden };
+    }
+    if (input.startsWith('wf://')) {
+        return { scheme: 'unresolvable', attemptedScheme: 'wf', ...UNRESOLVABLE.wf };
+    }
+    return grammarInvalid(`unsupported scheme in "${input}"`);
+}
+/**
+ * Rebuild the route path for a parsed ref. For `recipe://` this is the path-shaped
+ * route `{type}/{name}[@{version}][?tier={tier}]`; for `ar://` it is the original
+ * string (never decomposed).
+ */
+export function routeFor(ref) {
+    switch (ref.scheme) {
+        case 'ar':
+            return ref.ref;
+        case 'recipe': {
+            let path = `${ref.type}/${ref.name}`;
+            if (ref.version !== undefined) {
+                path += `@${ref.version}`;
+            }
+            if (ref.tier !== undefined) {
+                path += `?tier=${ref.tier}`;
+            }
+            return path;
+        }
+        case 'unresolvable':
+            throw new DominusError(`No route for ${ref.attemptedScheme}:// refs: ${ref.missingContract} (owner: ${ref.owningService})`, 400, { code: 'ref.scheme.unresolvable', category: 'validation' });
+    }
+}
+//# sourceMappingURL=grammar.js.map

package/dist/refs/grammar.js.map

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

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-06-27-0849-sdk-orient/00-reading-order.md

@@ -1,35 +1,35 @@
-# 00 Reading Order
-
-Snapshot: 2026-06-27-0849-sdk-orient. Source-backed at SDK v6.6.0, branch
-`production`. Code is authority; this guide is a map.
-
-## Read These First (docs)
-
-1. This pack, in INDEX order.
-2. `docs/architecture.md` — request lifecycle, layering, Two-Layer Storage Rule.
-3. `docs/routes-services.md` — service/endpoint matrix and route-prefix mapping.
-4. `docs/usage-reference.md` — exhaustive per-command reference (large; grep it,
-   do not read top-to-bottom).
-5. `CLAUDE.md` — repo conventions and the public-API change checklist.
-
-## Open Source Only For Specific Tasks
-
-- Changing a namespace command → the one file in `src/namespaces/<name>.ts`.
-- Transport / auth / retries / streaming / binary → `src/lib/client.ts`.
-- New public type or root shortcut → `src/index.ts`.
-- Env / gateway resolution → `src/lib/config.ts`.
-- Error classification → `src/lib/errors.ts`.
-
-## Stale / Dangerous
-
-- `docs/architecture.md` §10 and `CLAUDE.md` Validation note previously said "no
-  committed automated tests". STALE — `tests/` has 24 files run by `npm test`.
-  Corrected in this pass; if you see the old claim re-appear, fix it.
-- `dist/` is generated build output (gitignored). Never use it for design
-  decisions or treat it as source.
-
-## Related Surfaces
-
-- Janitor cleanup audit:
-  `docs/janitor/2026-06-27-0849-sdk-orient-cleanup-audit.md`.
-- No `docs/atlas/` exists yet; run `kyle-atlas` if truth scatters.
+# 00 Reading Order
+
+Snapshot: 2026-06-27-0849-sdk-orient. Source-backed at SDK v6.6.0, branch
+`production`. Code is authority; this guide is a map.
+
+## Read These First (docs)
+
+1. This pack, in INDEX order.
+2. `docs/architecture.md` — request lifecycle, layering, Two-Layer Storage Rule.
+3. `docs/routes-services.md` — service/endpoint matrix and route-prefix mapping.
+4. `docs/usage-reference.md` — exhaustive per-command reference (large; grep it,
+   do not read top-to-bottom).
+5. `CLAUDE.md` — repo conventions and the public-API change checklist.
+
+## Open Source Only For Specific Tasks
+
+- Changing a namespace command → the one file in `src/namespaces/<name>.ts`.
+- Transport / auth / retries / streaming / binary → `src/lib/client.ts`.
+- New public type or root shortcut → `src/index.ts`.
+- Env / gateway resolution → `src/lib/config.ts`.
+- Error classification → `src/lib/errors.ts`.
+
+## Stale / Dangerous
+
+- `docs/architecture.md` §10 and `CLAUDE.md` Validation note previously said "no
+  committed automated tests". STALE — `tests/` has 24 files run by `npm test`.
+  Corrected in this pass; if you see the old claim re-appear, fix it.
+- `dist/` is generated build output (gitignored). Never use it for design
+  decisions or treat it as source.
+
+## Related Surfaces
+
+- Janitor cleanup audit:
+  `docs/janitor/2026-06-27-0849-sdk-orient-cleanup-audit.md`.
+- No `docs/atlas/` exists yet; run `kyle-atlas` if truth scatters.

package/docs/agent-guide/2026-06-27-0849-sdk-orient/01-purpose-and-boundaries.md

@@ -1,48 +1,48 @@
-# 01 Purpose And Boundaries
-
-## Purpose
-
-`dominus-sdk-nodejs` is the TypeScript/ESM client SDK for the Dominus
-gateway-first platform (`package.json` `description`). It exposes a singleton
-`dominus` (`src/index.ts`) with namespace-based APIs for auth, data, storage,
-AI/runtime, workflow execution, jobs, and platform administration. Application
-code uses this SDK rather than calling gateway routes directly.
-
-## What This Repo Owns
-
-- The public client surface: namespaces (`src/namespaces/*.ts`), root shortcuts,
-  and exported types/utilities (`src/index.ts`).
-- The request/transport contract: base64 wire protocol, JWT mint+cache, retries,
-  circuit breaker, SSE streaming, binary upload/download (`src/lib/client.ts`).
-- Ergonomic parameter normalization and the mapping from SDK calls to `/api/*`
-  routes that the gateway transforms to `/svc/*`.
-
-## What It Does Not Own
-
-- Backend behavior or route definitions — those live in the individual Dominus
-  workers (gateway, guardian, authority, workflow-manager, agent-runtime, etc.).
-  This SDK only describes how to call them.
-- Kernel contracts (identity families, error envelope, deployment lanes). It
-  must conform to them, not define them.
-
-## Dominus/CareBridge Boundary
-
-This is a Dominus platform repo (`dominus_active/`). It is product-agnostic: it
-carries the platform client, not CareBridge product logic. Per workspace policy,
-project↔gateway calls use this SDK with project identity; never forward user or
-machine JWTs to admin-only planes.
-
-## Runtime / Deployment Class
-
-- Published npm library (`name: dominus-sdk-nodejs`), single export entry
-  (`dist/index.js` / `dist/index.d.ts`); no subpath exports.
-- ESM only (`"type": "module"`), Node `>=18` (`engines`).
-- Released by pushing to the `production` branch (npm publish). Per workspace
-  convention this repo's production branch is `production`, NOT
-  `dominus-production`.
-
-## PHI / Secrets / Safety
-
-- Service auth is a PSK in `DOMINUS_TOKEN`, exchanged for a short-lived JWT.
-- Never write PHI, secrets, tokens, cookies, or raw response bodies into these
-  docs or into logs.
+# 01 Purpose And Boundaries
+
+## Purpose
+
+`dominus-sdk-nodejs` is the TypeScript/ESM client SDK for the Dominus
+gateway-first platform (`package.json` `description`). It exposes a singleton
+`dominus` (`src/index.ts`) with namespace-based APIs for auth, data, storage,
+AI/runtime, workflow execution, jobs, and platform administration. Application
+code uses this SDK rather than calling gateway routes directly.
+
+## What This Repo Owns
+
+- The public client surface: namespaces (`src/namespaces/*.ts`), root shortcuts,
+  and exported types/utilities (`src/index.ts`).
+- The request/transport contract: base64 wire protocol, JWT mint+cache, retries,
+  circuit breaker, SSE streaming, binary upload/download (`src/lib/client.ts`).
+- Ergonomic parameter normalization and the mapping from SDK calls to `/api/*`
+  routes that the gateway transforms to `/svc/*`.
+
+## What It Does Not Own
+
+- Backend behavior or route definitions — those live in the individual Dominus
+  workers (gateway, guardian, authority, workflow-manager, agent-runtime, etc.).
+  This SDK only describes how to call them.
+- Kernel contracts (identity families, error envelope, deployment lanes). It
+  must conform to them, not define them.
+
+## Dominus/CareBridge Boundary
+
+This is a Dominus platform repo (`dominus_active/`). It is product-agnostic: it
+carries the platform client, not CareBridge product logic. Per workspace policy,
+project↔gateway calls use this SDK with project identity; never forward user or
+machine JWTs to admin-only planes.
+
+## Runtime / Deployment Class
+
+- Published npm library (`name: dominus-sdk-nodejs`), single export entry
+  (`dist/index.js` / `dist/index.d.ts`); no subpath exports.
+- ESM only (`"type": "module"`), Node `>=18` (`engines`).
+- Released by pushing to the `production` branch (npm publish). Per workspace
+  convention this repo's production branch is `production`, NOT
+  `dominus-production`.
+
+## PHI / Secrets / Safety
+
+- Service auth is a PSK in `DOMINUS_TOKEN`, exchanged for a short-lived JWT.
+- Never write PHI, secrets, tokens, cookies, or raw response bodies into these
+  docs or into logs.