dominus-sdk-nodejs 11.0.5 → 11.0.7

package/docs/routes-services.md

@@ -1,80 +1,85 @@
-# Routes, Services, and Endpoints Assessment
-
-This assessment is derived from all public namespace methods under `src/namespaces/` and their configured routes in SDK request calls.
-
-Audited commands: **~450** (hand-counted) across **27** top-level namespace files in `src/namespaces/`. The Service Matrix below lists **29** namespace surfaces because it expands dotted sub-namespaces (e.g. `ai.*` and `auth.*`) into their own rows, so the surface count is intentionally higher than the file count, not a typo. These totals are hand-maintained — re-derive from source before quoting.
-
-## Service Matrix
-
-| Service | Commands | Namespaces | Distinct Route Expressions | Notes |
-|---|---:|---|---:|---|
-| `guardian` | 146 | dominus.auth | 146 | HTTP API routes via Dominus client. |
-| `agent-runtime` | 53 | dominus.ai, dominus.ai.artifacts, dominus.ai.rag, dominus.ai.results, dominus.ai.tools, dominus.ai.workflow | 51 | HTTP API routes via Dominus client. |
-| `workflow-manager` | 38 | dominus.workflow | 36 | HTTP API routes via Dominus client. |
-| `authority` | 33 | dominus.authority | 33 | Hard-cut app/org/env Authority surface. |
-| `platform-worker` | 16 | dominus.platform | 16 | Gateway `/svc/platform/*` group/repository policy surface; policy helpers accept actor attribution headers. |
-| `coder-runtime` | 11 | dominus.coder | 11 | Gateway `/svc/coder/*` run lifecycle surface; launch requires exactly one workflow or pipeline recipe ref. |
-| `browser-worker` | 11 | dominus.browser | 10 | Authenticated `/svc/browser/*` browser automation primitive; Cloudflare Browser Run default, Browserbase fallback. |
-| `portal-worker` | 22 | dominus.portal | 22 | HTTP API routes via Dominus client. |
-| `db-worker` | 20 | dominus.db, dominus.ddl | 19 | HTTP API routes via Dominus client. |
-| `smith` | 15 | dominus.ddl | 15 | HTTP API routes via Dominus client. |
-| `b2-worker` | 14 | dominus.files | 14 | HTTP API routes via Dominus client. |
-| `redis-worker` | 14 | dominus.redis | 14 | HTTP API routes via Dominus client. |
-| `logs-worker` | 9 | dominus.logs | 4 | HTTP API routes via Dominus client; tail filters include `machine_id`. |
-| `scribe` | 7 | dominus.secure | 7 | HTTP API routes via Dominus client. |
-| `job-worker` | 8 | dominus.jobs | 6 | HTTP API routes via Dominus client. |
-| `artifact-worker` | 6 | dominus.artifacts | 6 | HTTP API routes via Dominus client. |
-| `stash-worker` managed tables | 6 | dominus.stash.tables | 6 | Typed self/group table routes through the authenticated gateway. |
-| `admin-worker` | 5 | dominus.admin, dominus.files | 5 | HTTP API routes via Dominus client. |
-| `warden` | 4 | dominus.secrets | 1 | Selected-scope grant semantics live in this group. |
-| `courier-worker` | 5 | dominus.courier | 2 | HTTP API routes via Dominus client. |
-| `gateway-local` | 4 | dominus.auth, dominus.health | 3 | Gateway `/health`, `/v1/ping`, and `/jwt/jwks` helpers. |
-| `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. |
-| `retired-stt` | 0 | (retired) | 0 | Legacy streaming STT namespace/routes are removed in hard cutover. |
-
-## Route Prefix Mapping
-
-| Prefix | Primary Namespace(s) | Expected Backend |
-|---|---|---|
-| `/api/warden/*` | secrets | `warden` |
-| `/api/guardian/*` | auth | `guardian` |
-| `/api/authority/*` | authority | `authority` |
-| `/api/platform/*` and `/svc/platform/*` | platform | `platform-worker` |
-| `/api/coder/*` and `/svc/coder/*` | coder | `coder-runtime` |
-| `/api/browser/*` | browser | `browser-worker` |
-| `/api/portal/*` | portal | `portal-worker` |
-| `/api/database/* and /api/provision/*` | db, ddl (builder + provisioning) | `db-worker` |
-| `/api/scribe/*` | secure, open | `scribe` |
-| `/api/smith/*` | ddl | `smith` |
-| `/api/redis/*` | redis | `redis-worker` |
-| `/api/b2/*` | files | `b2-worker` |
-| `/api/courier/*` | courier | `courier-worker` |
-| `/api/logs/*` | logs | `logs-worker` |
-| `/health`, `/v1/ping` | health | `gateway-local` |
-| `/api/admin/*` | admin | `admin-worker` |
-| `/api/sync/*` | sync | `sync-worker` |
-| `/api/job/*` | jobs | `job-worker` |
-| `/api/processor/*` | processor | `processor-service` |
-| `/api/artifact/*` | artifacts | `artifact-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` |
-| `/api/agent/stt` | ai.stt | `agent-runtime` |
-
-## Local and Helper Operations
-
-- `dominus.auth.validateJwt` performs local payload checks and expiry validation; it is not a full remote introspection endpoint.
-- `dominus.auth.getJwks` fetches and caches public signing keys from `/jwt/jwks`.
-- `dominus.health.check` uses direct `fetch` to the gateway `/health` route for low-level availability checks.
-- `dominus.ai.stt` sends binary audio to `POST /api/agent/stt` for batch transcription.
-- `dominus.authority.*` uses the cutover `appSlug` / `env` / `targetOrgId` / `targetAppSlug` / `targetEnv` vocabulary; `contextResolve()` and `mintSelectedScopeJwt()` now send the canonical `org_id` / `app_slug` / `env` and `target_org_id` / `target_env` wire payloads expected by live gateway routes.
-- `dominus.browser.*` routes through `/api/browser/*` with `useGateway: true`, producing authenticated gateway paths under `/svc/browser/*`. Browser run metadata remains worker runtime state; Artifact V2 is only for sanitized result/capture payloads.
-- `dominus.platform.*` and `dominus.coder.*` call `/svc/platform/*` and `/svc/coder/*` through `gatewayFetch`. Policy/Coder helpers accept actor context and forward it as `X-Actor-Type` / `X-Actor-Id`; `dominus.coder.ensureRun()` requires exactly one of `workflowRecipeRef` or `pipelineRecipeRef`.
-- Convenience wrappers like `dominus.courier.sendWelcome` delegate to core routes (for example `/api/courier/send`).
-
-## 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.
-- The exhaustive per-command listing with params/returns/routes is documented in [usage-reference.md](./usage-reference.md).
+# Routes, Services, and Endpoints Assessment
+
+This assessment is derived from all public namespace methods under `src/namespaces/` and their configured routes in SDK request calls.
+
+Audited commands: **~450** (hand-counted) across **27** top-level namespace files in `src/namespaces/`. The Service Matrix below lists **29** namespace surfaces because it expands dotted sub-namespaces (e.g. `ai.*` and `auth.*`) into their own rows, so the surface count is intentionally higher than the file count, not a typo. These totals are hand-maintained — re-derive from source before quoting.
+
+## Service Matrix
+
+| Service | Commands | Namespaces | Distinct Route Expressions | Notes |
+|---|---:|---|---:|---|
+| `guardian` | 146 | dominus.auth | 146 | HTTP API routes via Dominus client. |
+| `agent-runtime` | 53 | dominus.ai, dominus.ai.artifacts, dominus.ai.rag, dominus.ai.results, dominus.ai.tools, dominus.ai.workflow | 51 | HTTP API routes via Dominus client. |
+| `workflow-manager` | 38 | dominus.workflow | 36 | HTTP API routes via Dominus client. |
+| `authority` | 33 | dominus.authority | 33 | Hard-cut app/org/env Authority surface. |
+| `platform-worker` | 16 | dominus.platform | 16 | Gateway `/svc/platform/*` group/repository policy surface; policy helpers accept actor attribution headers. |
+| `coder-runtime` | 11 | dominus.coder | 11 | Gateway `/svc/coder/*` run lifecycle surface; launch requires exactly one workflow or pipeline recipe ref. |
+| `browser-worker` | 11 | dominus.browser | 10 | Authenticated `/svc/browser/*` browser automation primitive; Cloudflare Browser Run default, Browserbase fallback. |
+| `portal-worker` | 22 | dominus.portal | 22 | HTTP API routes via Dominus client. |
+| `db-worker` | 20 | dominus.db, dominus.ddl | 19 | HTTP API routes via Dominus client. |
+| `smith` | 15 | dominus.ddl | 15 | HTTP API routes via Dominus client. |
+| `b2-worker` | 14 | dominus.files | 14 | HTTP API routes via Dominus client. |
+| `redis-worker` | 14 | dominus.redis | 14 | HTTP API routes via Dominus client. |
+| `logs-worker` | 9 | dominus.logs | 4 | HTTP API routes via Dominus client; tail filters include `machine_id`. |
+| `scribe` | 7 | dominus.secure | 7 | HTTP API routes via Dominus client. |
+| `job-worker` | 8 | dominus.jobs | 6 | HTTP API routes via Dominus client. |
+| `artifact-worker` | 6 | dominus.artifacts | 6 | HTTP API routes via Dominus client. |
+| `stash-worker` managed tables | 6 | dominus.stash.tables | 6 | Typed self/group table routes through the authenticated gateway. |
+| `admin-worker` | 5 | dominus.admin, dominus.files | 5 | HTTP API routes via Dominus client. |
+| `warden` | 4 | dominus.secrets | 1 | Selected-scope grant semantics live in this group. |
+| `courier-worker` | 5 | dominus.courier | 2 | HTTP API routes via Dominus client. |
+| `gateway-local` | 4 | dominus.auth, dominus.health | 3 | Gateway `/health`, `/v1/ping`, and `/jwt/jwks` helpers. |
+| `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
+
+| Prefix | Primary Namespace(s) | Expected Backend |
+|---|---|---|
+| `/api/warden/*` | secrets | `warden` |
+| `/api/guardian/*` | auth | `guardian` |
+| `/api/authority/*` | authority | `authority` |
+| `/api/platform/*` and `/svc/platform/*` | platform | `platform-worker` |
+| `/api/coder/*` and `/svc/coder/*` | coder | `coder-runtime` |
+| `/api/browser/*` | browser | `browser-worker` |
+| `/api/portal/*` | portal | `portal-worker` |
+| `/api/database/* and /api/provision/*` | db, ddl (builder + provisioning) | `db-worker` |
+| `/api/scribe/*` | secure, open | `scribe` |
+| `/api/smith/*` | ddl | `smith` |
+| `/api/redis/*` | redis | `redis-worker` |
+| `/api/b2/*` | files | `b2-worker` |
+| `/api/courier/*` | courier | `courier-worker` |
+| `/api/logs/*` | logs | `logs-worker` |
+| `/health`, `/v1/ping` | health | `gateway-local` |
+| `/api/admin/*` | admin | `admin-worker` |
+| `/api/sync/*` | sync | `sync-worker` |
+| `/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` |
+| `/api/agent/stt` | ai.stt | `agent-runtime` |
+
+## Local and Helper Operations
+
+- `dominus.auth.validateJwt` performs local payload checks and expiry validation; it is not a full remote introspection endpoint.
+- `dominus.auth.getJwks` fetches and caches public signing keys from `/jwt/jwks`.
+- `dominus.health.check` uses direct `fetch` to the gateway `/health` route for low-level availability checks.
+- `dominus.ai.stt` sends binary audio to `POST /api/agent/stt` for batch transcription.
+- `dominus.authority.*` uses the cutover `appSlug` / `env` / `targetOrgId` / `targetAppSlug` / `targetEnv` vocabulary; `contextResolve()` and `mintSelectedScopeJwt()` now send the canonical `org_id` / `app_slug` / `env` and `target_org_id` / `target_env` wire payloads expected by live gateway routes.
+- `dominus.browser.*` routes through `/api/browser/*` with `useGateway: true`, producing authenticated gateway paths under `/svc/browser/*`. Browser run metadata remains worker runtime state; Artifact V2 is only for sanitized result/capture payloads.
+- `dominus.platform.*` and `dominus.coder.*` call `/svc/platform/*` and `/svc/coder/*` through `gatewayFetch`. Policy/Coder helpers accept actor context and forward it as `X-Actor-Type` / `X-Actor-Id`; `dominus.coder.ensureRun()` requires exactly one of `workflowRecipeRef` or `pipelineRecipeRef`.
+- Convenience wrappers like `dominus.courier.sendWelcome` delegate to core routes (for example `/api/courier/send`).
+
+## 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).