dominus-sdk-nodejs 11.0.3 → 11.0.5

package/docs/plans/2026-08-04-pending-work-fruition-summary.md

@@ -1,46 +1,46 @@
-# Pending work fruition summary: dominus-sdk-nodejs
-
-Generated: 2026-08-04 local. This note analyzes existing linked work without
-changing it.
-
-## What is present
-
-The repository has four local linked worktrees around two related themes. The
-timeline contract v9 line adds a target query filter and retires the older
-company query option. The secret-presence-grid v10 lines add safe presence
-data, persisted root-role exposure, and preview code-point counting; reconciled
-and release branches carry the latest versions of that work. The main checkout
-was not modified and the current production snapshot is separate from those
-feature branches.
-
-## Likely path to completion
-
-1. Compare the timeline and secret-presence branches with current `production`
-   and choose one coherent SDK contract candidate. Preserve backward
-   compatibility only where the server contract still requires it.
-2. Trace the timeline query change through Authority methods, generated/public
-   types, tests, and README examples; confirm the retired company option is
-   absent where intended and target filtering is consistently shaped.
-3. Trace the secret-presence change through admin/secrets namespaces, preview
-   counting, root-role projections, public types, and server endpoints. Keep
-   all responses value-safe and avoid implying secret availability from
-   indeterminate provider state.
-4. Run build, type tests, the full Node test suite, and focused contract tests
-   on the reconciled candidate. Then bump the package version once for the
-   actual release candidate and verify the new version is absent from the
-   registry.
-5. Push the exact `production` candidate and use the publish workflow plus
-   registry/version verification to establish package completion. Pair that
-   with downstream Gateway/worker contract proof where the SDK behavior is
-   load-bearing.
-
-## Open questions
-
-- Whether timeline v9 and secret-presence v10 should ship together or as two
-  independently versioned SDK releases.
-- Whether persisted root-role data is already available in every targeted
-  server environment or needs a typed unavailable state in the SDK.
-- Which release branch is canonical among the reconciled and release worktrees.
-
-These questions are intentionally left for contract/release review; the
-existing implementation remains untouched.
+# Pending work fruition summary: dominus-sdk-nodejs
+
+Generated: 2026-08-04 local. This note analyzes existing linked work without
+changing it.
+
+## What is present
+
+The repository has four local linked worktrees around two related themes. The
+timeline contract v9 line adds a target query filter and retires the older
+company query option. The secret-presence-grid v10 lines add safe presence
+data, persisted root-role exposure, and preview code-point counting; reconciled
+and release branches carry the latest versions of that work. The main checkout
+was not modified and the current production snapshot is separate from those
+feature branches.
+
+## Likely path to completion
+
+1. Compare the timeline and secret-presence branches with current `production`
+   and choose one coherent SDK contract candidate. Preserve backward
+   compatibility only where the server contract still requires it.
+2. Trace the timeline query change through Authority methods, generated/public
+   types, tests, and README examples; confirm the retired company option is
+   absent where intended and target filtering is consistently shaped.
+3. Trace the secret-presence change through admin/secrets namespaces, preview
+   counting, root-role projections, public types, and server endpoints. Keep
+   all responses value-safe and avoid implying secret availability from
+   indeterminate provider state.
+4. Run build, type tests, the full Node test suite, and focused contract tests
+   on the reconciled candidate. Then bump the package version once for the
+   actual release candidate and verify the new version is absent from the
+   registry.
+5. Push the exact `production` candidate and use the publish workflow plus
+   registry/version verification to establish package completion. Pair that
+   with downstream Gateway/worker contract proof where the SDK behavior is
+   load-bearing.
+
+## Open questions
+
+- Whether timeline v9 and secret-presence v10 should ship together or as two
+  independently versioned SDK releases.
+- Whether persisted root-role data is already available in every targeted
+  server environment or needs a typed unavailable state in the SDK.
+- Which release branch is canonical among the reconciled and release worktrees.
+
+These questions are intentionally left for contract/release review; the
+existing implementation remains untouched.

package/docs/routes-services.md

@@ -1,80 +1,80 @@
-# 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. |
+| `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).