nexus-ai-pro 2.12.0 → 2.14.0

package/API_STABILITY.md

@@ -41,6 +41,61 @@ Both are covered by this policy:
 Deep imports into `dist`, `dist-cjs`, or `src` are not supported. Import only from `nexus-ai-pro` or
 one of its explicit subpaths.
 
+## 2.14 stage (2.14.0)
+
+Everything 2.14 adds is stable from the start and additive, unless this section says otherwise.
+
+New and stable:
+- `nexus-ai-pro/policy`: `parsePolicy()`, `applyPolicy()`, `comparePolicies()`, `checkPolicyChange()`,
+  `providerGate()`, `policyHash()`, `PolicyError`, `Policy`, `PolicyDocument`, `PolicyAccess`,
+  `PolicyRouting`, `PolicyBudgets`, `PolicyResidency`, `PolicyCredentials`, `PolicyIssue`,
+  `ApplyPolicyOptions`, `PolicyChange`, `PolicyChangeKind`, and `PolicyCheck`;
+- `LifecycleConfig.providers` and `policy`, `ProviderGate`, `PolicyReference`,
+  `OperationDescriptor.policy`, `AuditLogEvent.policy`, and `OperationLifecycle.access()`;
+- the `nexus policy check` command, its flags, its exit codes, and its `--json` output;
+- `nexus-ai-pro/evaluate/emulate`: `emulatedTools()`, `EmulatedToolsOptions`, `EmulatorClient`,
+  `EmulatedToolCall`, `EmulatedResult`, `EmulationStore`, `MemoryEmulationStore`, `EmulationError`, and
+  `emulationKey()`. What the emulator is told may be reworded in a minor release; a store's keys never
+  change within a major;
+- `CallResidency.refusal()`, optional, and the optional `model` its `allows()`, `place()`, and
+  `check()` take;
+- `OperationLifecycle.callContext()`, the optional `OperationLifecycleLike.callContext`, and
+  `ContinuedCallContext`;
+- `tenantId` on `BatchSubmitRequest`, `EmbeddingBatchSubmitRequest`, `MediaReadRequest`,
+  `MediaDescribeRequest`, `MediaAnswerRequest`, `TranscriptionRequest`, `SpeechRequest`, and every
+  telephony request that takes a `signal`; `MediaCallContext.tenantId` and `credential`;
+  `RealtimeSessionConfig.credential`; the optional context the OpenAI voice adapter and the Twilio and
+  Telnyx adapters take on each method that calls their API.
+
+The kinds `comparePolicies()` gives a change may be refined in a minor release: a change found to widen
+what a tenant may reach is reported as `widened` from then on, so a check may start to ask for an
+acknowledgment it did not ask for before. A check never stops asking for one it asked for.
+
+## 2.13 stage (2.13.0)
+
+Everything 2.13 adds is stable from the start and additive, unless this section says otherwise.
+
+New and stable:
+- `nexus-ai-pro/server/regions`: `regionalGateway()`, `RegionalGateway`, `RegionalGatewayOptions`,
+  `RegionTarget`, `RegionHealth`, and `RegionHealthOptions`;
+- `RunManagerOptions.region` and `residency`, as `AgentServerOptions` carries them; `ThreadRecord.region`,
+  `RunRecord.region`, and `ReplicaReport.region`; a regional server's ids start with its region;
+- `nexus-ai-pro/residency`: `residency()`, `Residency`, `ResidencyOptions`, `RegionRule`,
+  `RegionDefinition`, `ResidencyPolicy`, `ResidencyDecision`, `ResidencyTarget`, `ResidencyPlacement`,
+  `CallResidency`, `ResidencyError`, `regionalTraceStore()`, `RegionalTraceStore`,
+  `RegionalTraceStoreOptions`, `regionalAssetStore()`, and `RegionalAssetStoreOptions`;
+- `LifecycleConfig.residency`, `ProviderCallContext.residency`, and `ImageRequestBase.tenantId`;
+- `nexus-ai-pro/credentials`: `tenantCredentials()`, `TenantCredentials`, `TenantCredentialsOptions`,
+  `TenantCredentialStats`, `CredentialError`, `parseSecret()`, `credentialRequest()`, `SecretSource`,
+  `awsSecrets()`, `gcpSecrets()`, `azureSecrets()`, `vaultSecrets()`, `envSecrets()`,
+  `memorySecrets()`, `MemorySecrets`, `AwsSecretsClient`, `GcpSecretsClient`, `AzureSecretsClient`,
+  and `VaultSecretsOptions`;
+- `LifecycleConfig.credentials`, `CredentialResolver`, `CredentialRequest`, and `ProviderCredential`;
+  `ProviderCallContext.tenantId` and `credential`; `OperationTicket.refreshCredential()` and
+  `scrub()`;
+- `OpenAIProviderConfig.credentialHeader`, `EmbeddingRequest.tenantId`, and
+  `EmbeddingProviderError.attempts`.
+
 ## 2.12 stage (2.12.0)
 
 Everything 2.12 adds is stable from the start and additive, unless this section says otherwise.

package/CHANGELOG.md

@@ -4,6 +4,115 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [2.14.0] - 2026-10-19
+
+Policy you can review, evaluation without side effects, and credentials per tenant in every family.
+
+### Added
+
+- **Policy you can review.** `nexus-ai-pro/policy` reads guardrails, routing, budgets, residency, and
+  credentials from one versioned file. `parsePolicy()` validates it as the client starts, naming every
+  issue; `applyPolicy()` turns it into the client's configuration; and every operation and audit event
+  records the policy's name, version, and content hash. `nexus policy check` compares a version with
+  the one before it, a file or `git:<ref>`, and fails the build on a change that widens what a tenant
+  may reach (a region, a provider, a model, a budget, lowered guardrails, a shared key) until it is
+  acknowledged in the file or with `--accept`, and on content changed without a new version.
+- **Per-tenant routing rules.** `LifecycleConfig.providers` takes a `ProviderGate` that admits or
+  refuses each provider and model an operation would reach, checked wherever residency is: a refused
+  provider is refused with an `OperationDeniedError` naming the rule before anything is sent, a
+  completion's refused attempt is dropped from its route, and an embedding never falls back to a
+  refused model. `providerGate()` builds one from a policy's routing rules, with `*` wildcards.
+- **Evaluation without side effects.** `emulatedTools()`, on the new `nexus-ai-pro/evaluate/emulate`,
+  returns an agent's tools answered by a model playing each one, told the tool, its result schema, a
+  scenario, real calls, and the run's earlier calls, and never run, so an evaluation of an agent that
+  charges cards or writes to a database sends nothing. Answers are kept by tool, arguments, scenario,
+  and call, and replayed, so a suite runs the same answers in CI without a model; tools that change
+  nothing can run for real.
+- **Credentials per tenant in every family.** Video, media understanding, completion and embedding
+  batches, voice, telephony, and realtime sessions send the tenant's key, resolved by
+  `LifecycleConfig.credentials`, in place of the configured one, as completions, embeddings, and images
+  have since 2.13. Each takes `tenantId` on its requests. A video job's or a batch's ref records its
+  tenant, so `status()`, `resume()`, `cancel()`, and `download()` use the tenant's key and regions from
+  any process, through the new `OperationLifecycle.callContext()`. A Twilio tenant's calls go out on its
+  subaccount; an OpenAI SIP call keeps its project's key.
+- `ai.lifecycle.access()` returns the `CallResidency` an operation would get, and
+  `CallResidency.refusal()` says why a provider would be refused once placed on its twin; `allows()`,
+  `place()`, and `check()` take the model as well.
+
+### Fixed
+
+- `VideoManager.start()` and the calls on a video ref, and `EmbeddingBatchManager.start()` and the
+  calls on its refs, ran outside the client's residency policy; they are held to the tenant's regions
+  now. A durable video generation ran its operation without its tenant, so a tenant's budget and rate
+  limit did not apply to it.
+
+## [2.13.0] - 2026-10-19
+
+Regions and residency, and credentials per tenant.
+
+### Added
+
+- **Agent servers across regions.** `regionalGateway()`, on the new `nexus-ai-pro/server/regions`, sits
+  in front of one agent server per region. A thread or run goes to the region its id names and waits
+  there while that region is down, since its data is there and nowhere else; new work goes to the
+  tenant's home region and fails over only to another region the tenant may reach; a tenant that may
+  reach no region served is refused with a 403 naming the rule. Regions are checked through their
+  `/health`, marked down by failed requests, and taken out by an operator with `markDown()`. An agent
+  server given `region` stamps it on its threads, runs, ids, replica report, and health, and, given
+  `residency`, refuses tenants that may not reach it.
+- **Residency: each tenant's requests and data kept in its regions.** `residency()`, on the new
+  `nexus-ai-pro/residency`, says which regions each tenant may reach (a map, or a function over the
+  tenant's record), which providers run in each region, and each provider's twin inside a region.
+  `LifecycleConfig.residency` applies it to every family: a completion or stream, its fallbacks and
+  its context summary included, is sent to the provider routing chose when that runs inside the
+  tenant's regions and to its twin there when not; an embedding never falls back outside them; and a
+  provider anything would reach outside them is refused with a `ResidencyError` naming the rule,
+  before anything is sent. `regionalTraceStore()` and `regionalAssetStore()` write each tenant's
+  traces, every run of a trace together, and assets in its home region, and read them only from its
+  regions.
+- **Credentials per tenant.** `LifecycleConfig.credentials` resolves each provider's key per tenant,
+  when a call is made, in every family that runs through the lifecycle: completions, streams,
+  embeddings, and images send it in place of the configured key. `tenantCredentials()`, on the new
+  `nexus-ai-pro/credentials`, reads it from a secret source, cached for `cacheMs`, shared by
+  concurrent calls, carried by the last key while the source is down for up to `staleMs`, and
+  refusing a tenant with no key unless told to fall back. Sources for AWS Secrets Manager, Google
+  Secret Manager, Azure Key Vault, HashiCorp Vault, the environment, and memory, each over the
+  vendor's own client with no dependency.
+- A completion or stream whose provider refuses its credential is resolved again and made once more
+  on the new key; in any other family, the next operation reads the key again. Every key and header
+  value an operation resolves is removed from the errors it raises, before an audit event, a log,
+  a trace, or the health report sees them.
+- `ProviderCallContext.residency`, the operation's `CallResidency`; `ImageRequestBase.tenantId`; and
+  an agent server's trace root records its run's tenant as `metadata.nexus.tenant`.
+- `ProviderCallContext.tenantId` and `credential()`; `OperationTicket.refreshCredential()` and
+  `scrub()`; `OpenAIProviderConfig.credentialHeader`; `EmbeddingRequest.tenantId`; and
+  `EmbeddingProviderError.attempts`, each attempt's error.
+
+### Proof
+
+- `tests/regions.test.ts`: the proof that closes 2.13. Three regions, each an agent server with its own
+  state, traces, and provider, behind a gateway, with every tenant's key from one secret manager. A run
+  of four model calls has its key rotated and revoked after the second; the third and fourth are
+  answered on the new key. Then the EU tenant's home region goes down: its new work fails over to the
+  other EU region, its thread waits for its own, a tenant held to that region waits too, and nothing
+  of either reaches the US: no thread, run, trace, or provider call. Without region ids, the server's
+  check, a thread's region kept, new work held to the tenant's regions, failover, checks, the
+  operator's mark, or the gateway's own refusal, a test fails.
+- `tests/residency.test.ts`: against a provider server per region, a tenant pinned to the EU is
+  answered by the EU twin of the provider routing chose, completions and streams alike, and nothing
+  of it reaches the US; a provider with no twin there is refused with the rule, nothing sent; an
+  embedding whose EU provider fails never falls back to the US; an image provider outside the regions
+  is refused; and each tenant's traces and assets land in its home region and are read only from its
+  regions. Without placement, twins, the decision, the routed check, the fallback filter, the image
+  check, traces kept together, the tenant view, the asset home, or the rule checks, a test fails.
+- `tests/tenant-credentials.test.ts`: against a provider of the test's own that takes only live keys,
+  each tenant's calls carry its own key through completions, streams, and embeddings; in a run of five
+  calls whose key is rotated and revoked after the second, the third is answered on the new key and
+  every call after uses it; a key the provider quotes in its refusal reaches no error, stack, cause,
+  audit event, log, trace, or health report. Without the call's credential, the refresh, its limit,
+  either scrub, an adapter's use of the key, the cache's expiry, its single read, its stale key, or
+  its refusal, a test fails.
+
 ## [2.12.0] - 2026-10-18
 
 Observability that loses nothing, and media you can evaluate.
@@ -2879,7 +2988,9 @@ shared policy vocabulary is in place for a future release that revisits this.
 - URL fetching rejects unsafe private-network targets and limits response reads.
 - CLI and audit findings no longer disclose detected secret values.
 
-[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.12.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.14.0...HEAD
+[2.14.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.13.0...v2.14.0
+[2.13.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.12.0...v2.13.0
 [2.12.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.11.0...v2.12.0
 [2.11.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.10.0...v2.11.0
 [2.10.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.9.0...v2.10.0

package/README.md

@@ -141,7 +141,7 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [MCP](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/mcp.md) | Borrowing tools from MCP servers, a registry of many, and serving your own |
 | [Agent protocols](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/protocols.md) | Serving an agent to user interfaces over AG-UI, to other agents over A2A, and to code editors over ACP, and calling remote agents as tools |
 | [Traces](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/tracing.md) | Run trees, queries, feedback, comparison, and alerts |
-| [Evaluation](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/evaluation.md) | Datasets, evaluators, experiments, comparisons with a verdict, review queues, LLM judges |
+| [Evaluation](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/evaluation.md) | Datasets, evaluators, experiments, comparisons with a verdict, review queues, LLM judges, and tools emulated by a model so an evaluation sends nothing |
 | [Context hub](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/context-hub.md) | Prompts, instructions, tools, and skills versioned together, promoted through gates, and moved between projects |
 | [Insights](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/insights.md) | Failing and slow runs clustered, regressions between time windows, and evaluated fix proposals |
 | [Prompts](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/prompts.md) | Typed templates, content versions, gated promotion, rollback, A/B splits, serving through outages |
@@ -167,6 +167,8 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [Agent server](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/server.md) | Self-hosted HTTP server for assistants: threads, durable runs, resumable streams, cron, a worker queue, and metrics |
 | [Deployments](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/deployments.md) | Revisions and canaries with automatic rollback, autoscaling on Kubernetes and Helm, and per-tenant limits |
 | [Tenancy](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/tenancy.md) | One tenant model: a tenant's view of every store, tenant graph runs, and the isolation suite |
+| [Policy](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/policy.md) | Guardrails, routing, budgets, residency, and credentials as one versioned file, validated as the client starts, checked by `nexus policy check` in CI, and recorded on every operation |
+| [Regions and credentials](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/regions.md) | Agent servers across regions behind a gateway, residency rules that keep each tenant's requests, traces, and assets in its regions, and each tenant's provider keys from a secret manager |
 | [Workflows](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/workflows.md) | Ready-made chains and domain workflows |
 | [Command line](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/cli.md) | The `nexus` command |
 | [Packaging and install weight](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/packaging.md) | Every entry point and what it costs |
@@ -307,14 +309,22 @@ Shipped so far:
 - 2.12 observability that loses nothing, and media you can evaluate: spans spooled through a collector
   outage, OTLP over gRPC, deployment evaluation that reads each run's whole trace, evaluators that
   read and judge images, documents, audio, and video, a catalog of every stored asset, and automation
-  rules that roll a canary back when a score falls.
+  rules that roll a canary back when a score falls;
+- 2.13 regions and residency, and credentials per tenant: agent servers across regions behind a
+  gateway that fails over only within a tenant's regions, residency rules that keep each tenant's
+  provider calls, traces, and assets in its regions, and each tenant's provider keys from a secret
+  manager, rotated without a restart and kept out of every error;
+- 2.14 policy you can review, and evaluation without side effects: guardrails, routing, budgets,
+  residency, and credentials as one versioned file that `nexus policy check` compares with the version
+  before it in CI and every operation records, tools emulated by a model so an evaluation sends
+  nothing, and each tenant's key in every family.
 
 Upgrading from 1.x: `npx nexus migrate src --write` moves your imports, and
 [MIGRATING.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/MIGRATING.md) covers the rest.
-Next, 2.13 runs agents across regions, keeps each tenant's requests and data in the region they
-require, and resolves provider keys per tenant from a secret manager. Pinecone, images, the Gemini
-embedding batch tier, media understanding, video, Gemini Live, SIP, and both phone providers graduate
-once the live workflow passes against each. The
+Next, 2.15 publishes a compatibility record for community adapters: the contract suite each passed,
+against which version, with its benchmark, on one page. Pinecone, images, the Gemini embedding batch
+tier, media understanding, video, Gemini Live, SIP, and both phone providers graduate once the live
+workflow passes against each. The
 [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists what comes after, in the order
 applications ask for it.
 

package/dist/batch/anthropic.js

@@ -127,13 +127,15 @@ export class AnthropicBatchProvider {
     async send(path, init, context) {
         const fetchImpl = this.options.fetch ?? fetch;
         const baseUrl = (this.options.baseUrl || 'https://api.anthropic.com/v1').replace(/\/$/, '');
+        const credential = await context.credential?.(this.info.name);
         const response = await fetchImpl(`${baseUrl}${path}`, {
             ...init,
             headers: {
-                'x-api-key': this.options.apiKey,
+                'x-api-key': credential?.apiKey ?? this.options.apiKey,
                 'anthropic-version': this.options.version ?? '2023-06-01',
                 'content-type': 'application/json',
                 ...this.options.headers,
+                ...credential?.headers,
                 ...(init.headers ?? {}),
             },
             signal: context.signal,

package/dist/batch/manager.d.ts

@@ -60,6 +60,11 @@ export declare class BatchManager {
     status(ref: BatchJobRef): Promise<BatchJobState>;
     /** Cancels a batch. Throws when the provider cannot cancel. */
     cancel(ref: BatchJobRef): Promise<BatchJobState>;
+    /**
+     * A call on a batch outside its operation, as the tenant its ref records, or `tenantId` for a ref
+     * made before refs recorded one: with the tenant's key, inside its regions.
+     */
+    private continuing;
     private collect;
     /**
      * Prices a finished batch at the provider's discounted rate.

package/dist/batch/manager.js

@@ -2,6 +2,7 @@ import { OperationRunner } from '../operations/runner.js';
 import { estimateCost } from '../optimizer/cost.js';
 import { DEFAULT_CURRENCY } from '../optimizer/cost.js';
 import { generateRequestId } from '../utils/ids.js';
+import { continuing } from '../lifecycle/continue.js';
 import { withLifecycle } from '../lifecycle/run.js';
 import { BatchCapabilityError, BatchProviderNotFoundError, BatchValidationError } from './errors.js';
 import { pollUntilSettled } from './poll.js';
@@ -46,6 +47,7 @@ export class BatchManager {
             operation: 'batch.submit',
             requestId,
             provider: providerName,
+            ...(request.tenantId !== undefined ? { tenantId: request.tenantId } : {}),
             metadata: { items: request.items.length },
         }, {
             signal: operation.signal,
@@ -60,7 +62,7 @@ export class BatchManager {
             };
             let ref = operation.previousHeartbeat?.batchRef;
             if (!ref) {
-                ref = await provider.submit(request, context);
+                ref = withTenant(await provider.submit(request, context), request.tenantId);
                 await operation.heartbeat({ batchRef: ref });
             }
             operation.report({ completed: 0, total: request.items.length, message: `submitted as ${ref.id}` });
@@ -77,34 +79,41 @@ export class BatchManager {
         const provider = this.providers.get(ref.provider);
         if (!provider)
             throw new BatchProviderNotFoundError(ref.provider);
-        const context = {
+        return this.continuing('batch.collect', ref, options.tenantId, (continued) => this.collect(provider, ref, options, undefined, {
+            ...continued,
             requestId: generateRequestId(),
             signal: options.signal ?? new AbortController().signal,
             attempt: 1,
-        };
-        return this.collect(provider, ref, options, undefined, context);
+        }));
     }
     async status(ref) {
         const provider = this.providers.get(ref.provider);
         if (!provider)
             throw new BatchProviderNotFoundError(ref.provider);
-        return provider.poll(ref, {
+        return this.continuing('batch.status', ref, undefined, (continued) => provider.poll(ref, {
+            ...continued,
             requestId: generateRequestId(),
             signal: new AbortController().signal,
             attempt: 1,
-        });
+        }));
     }
     async cancel(ref) {
         const provider = this.providers.get(ref.provider);
         if (!provider)
             throw new BatchProviderNotFoundError(ref.provider);
-        if (!provider.cancel)
+        const cancel = provider.cancel;
+        if (!cancel)
             throw new BatchCapabilityError(ref.provider, 'cancel');
-        return provider.cancel(ref, {
+        return this.continuing('batch.cancel', ref, undefined, (continued) => cancel.call(provider, ref, {
+            ...continued,
             requestId: generateRequestId(),
             signal: new AbortController().signal,
             attempt: 1,
-        });
+        }));
+    }
+    continuing(operation, ref, tenantId, call) {
+        const tenant = tenantOf(ref) ?? tenantId;
+        return continuing(this.runtime.lifecycle, { family: 'batch', operation, provider: ref.provider, ...(tenant !== undefined ? { tenantId: tenant } : {}) }, call);
     }
     async collect(provider, ref, request, operation, context) {
         const state = await pollUntilSettled(() => provider.poll(ref, context), {
@@ -230,3 +239,10 @@ function sumUsage(items) {
     }
     return { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens };
 }
+function withTenant(ref, tenantId) {
+    return tenantId === undefined ? ref : { ...ref, metadata: { ...ref.metadata, batch: { tenantId } } };
+}
+function tenantOf(ref) {
+    const notes = ref.metadata?.batch;
+    return typeof notes?.tenantId === 'string' ? notes.tenantId : undefined;
+}

package/dist/batch/openai-client.js

@@ -84,10 +84,12 @@ export class OpenAIBatchClient {
     async send(path, init, context) {
         const fetchImpl = this.options.fetch ?? fetch;
         const baseUrl = (this.options.baseUrl || 'https://api.openai.com/v1').replace(/\/$/, '');
+        const credential = await context.credential?.('openai');
         const headers = {
-            authorization: `Bearer ${this.options.apiKey}`,
+            authorization: `Bearer ${credential?.apiKey ?? this.options.apiKey}`,
             ...(this.options.organization ? { 'openai-organization': this.options.organization } : {}),
             ...this.options.headers,
+            ...credential?.headers,
             ...(init.headers ?? {}),
         };
         const response = await fetchImpl(`${baseUrl}${path}`, { ...init, headers, signal: context.signal });

package/dist/cli/policy.d.ts

@@ -0,0 +1,10 @@
+import { type ParsedArgs } from './args.js';
+/**
+ * `nexus policy check <policy.json> [--base <file>|git:<ref>] [--accept path,path] [--json]`.
+ *
+ * Validates the policy, and, given the version it replaces, lists every change: each that widens what
+ * a tenant may reach, or that needs a reviewer's eye, must be acknowledged in the file's
+ * `acknowledged` or with `--accept`, and content that changed must come with a new version. Exits 1
+ * when the policy is not valid or a change is not acknowledged.
+ */
+export declare function runPolicyCommand(subcommand: string | undefined, args: ParsedArgs): Promise<void>;

package/dist/cli/policy.js

@@ -0,0 +1,116 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { checkPolicyChange, PolicyError, parsePolicy } from '../policy/index.js';
+import { CliUsageError, flagBool, listFlag, printTable, stringFlag, writeJson } from './args.js';
+const run = promisify(execFile);
+export async function runPolicyCommand(subcommand, args) {
+    if (subcommand !== 'check')
+        throw new CliUsageError(`Unknown policy command "${subcommand ?? ''}". Use check.`);
+    const [file] = args.positionals;
+    if (!file)
+        throw new CliUsageError('nexus policy check needs a policy file: nexus policy check policy.json [--base git:main].');
+    const json = flagBool(args.flags, 'json');
+    const base = stringFlag(args.flags, 'base');
+    const after = parse(await readFile(file, 'utf8'), file, json);
+    if (!after)
+        return;
+    if (base === undefined) {
+        report(json, { policy: after.reference, valid: true }, `${describe(after)} is valid.`);
+        return;
+    }
+    const text = await readBase(base, file);
+    if (text === undefined) {
+        report(json, { policy: after.reference, valid: true, base: null }, `${describe(after)} is valid. ${base} has no policy at ${file}: nothing to compare.`);
+        return;
+    }
+    const before = parse(text, base, json);
+    if (!before)
+        return;
+    const check = checkPolicyChange(before.document, after.document, { accept: listFlag(args.flags, 'accept') ?? [] });
+    if (!check.ok)
+        process.exitCode = 1;
+    if (json) {
+        writeJson({ policy: after.reference, valid: true, base: before.reference, ...check });
+        return;
+    }
+    console.log(`${describe(after)} is valid. Compared with ${before.name}@${before.version} from ${base}:`);
+    if (check.changes.length === 0)
+        console.log('No changes.');
+    else {
+        const pending = new Set(check.unacknowledged);
+        printTable(check.changes.map((change) => ({
+            kind: change.kind,
+            path: change.path,
+            review: change.kind === 'narrowed' ? '' : pending.has(change) ? 'NOT ACKNOWLEDGED' : 'acknowledged',
+            summary: change.summary,
+        })), ['kind', 'path', 'review', 'summary']);
+    }
+    if (check.versionUnchanged) {
+        console.log('');
+        console.log(`The content changed, but the version is still ${after.version}: raise it.`);
+    }
+    if (check.unacknowledged.length > 0) {
+        const paths = check.unacknowledged.map((change) => change.path);
+        console.log('');
+        console.log(`${paths.length} change${paths.length === 1 ? '' : 's'} need${paths.length === 1 ? 's' : ''} acknowledging: add ${paths.map((item) => `"${item}"`).join(', ')} to "acknowledged" in ${file}, or pass --accept ${paths.join(',')}.`);
+    }
+}
+function parse(text, source, json) {
+    try {
+        return parsePolicy(text);
+    }
+    catch (error) {
+        if (!(error instanceof PolicyError))
+            throw error;
+        process.exitCode = 1;
+        if (json)
+            writeJson({ source, valid: false, issues: error.issues });
+        else {
+            console.log(`${source} is not a valid policy:`);
+            for (const issue of error.issues)
+                console.log(`  ${issue.path || '(document)'}: ${issue.message}`);
+        }
+        return undefined;
+    }
+}
+async function readBase(base, file) {
+    if (!base.startsWith('git:'))
+        return readFile(base, 'utf8');
+    const ref = base.slice(4);
+    if (!ref)
+        throw new CliUsageError('--base git: needs a ref, such as git:main or git:HEAD~1.');
+    const git = async (args) => {
+        try {
+            return (await run('git', args, { cwd: path.dirname(path.resolve(file)), maxBuffer: 16 * 1024 * 1024 })).stdout;
+        }
+        catch (error) {
+            const stderr = String(error.stderr ?? '').trim();
+            throw new Error(stderr || error.message);
+        }
+    };
+    try {
+        await git(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+    }
+    catch (error) {
+        throw new Error(`git has no commit ${ref} where ${file} is: ${error.message || 'unknown ref'}`);
+    }
+    const object = `${ref}:./${path.basename(file)}`;
+    try {
+        await git(['cat-file', '-e', object]);
+    }
+    catch {
+        return undefined;
+    }
+    return git(['show', object]);
+}
+function describe(policy) {
+    return `Policy ${policy.name}@${policy.version} (sha256 ${policy.hash.slice(0, 12)})`;
+}
+function report(json, value, text) {
+    if (json)
+        writeJson(value);
+    else
+        console.log(text);
+}

package/dist/cli.js

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
-import process from 'node:process';
+import { readdir, readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
+import process from 'node:process';
 import { pathToFileURL } from 'node:url';
-import { readdir, readFile, stat } from 'node:fs/promises';
-import { EvalRunner } from './evals/runner.js';
+import { CliUsageError, flagBool, isRecord, numberFlag, parseArgs, printTable, stringFlag, writeJson, } from './cli/args.js';
 import { NexusAI } from './core/nexus.js';
-import { listKnownModels, listModelsForProvider, getModelCapabilities } from './models/registry.js';
+import { EvalRunner } from './evals/runner.js';
+import { getModelCapabilities, listKnownModels, listModelsForProvider } from './models/registry.js';
+import { TokenOptimizer } from './optimizer/index.js';
 import { SecurityPipeline } from './security/index.js';
 import { redactSensitiveText } from './security/output-guard.js';
 import { UploadScanner } from './security/upload-scanner.js';
-import { TokenOptimizer } from './optimizer/index.js';
-import { CliUsageError, flagBool, isRecord, numberFlag, parseArgs, printTable, stringFlag, writeJson, } from './cli/args.js';
 const DEFAULT_SCAN_MAX_BYTES = 1_000_000;
 const IGNORED_DIRS = new Set(['.git', 'node_modules', 'dist', 'coverage', '.next', '.turbo']);
 async function main() {
@@ -78,6 +78,12 @@ async function main() {
             await runDeployCommand(subcommand, { positionals: args, flags: parsed.flags });
             return;
         }
+        case 'policy': {
+            const [subcommand, ...args] = parsed.positionals;
+            const { runPolicyCommand } = await import('./cli/policy.js');
+            await runPolicyCommand(subcommand, { positionals: args, flags: parsed.flags });
+            return;
+        }
         case 'optimize':
             await runOptimize(parsed);
             return;
@@ -431,6 +437,7 @@ Usage:
   nexus deploy canary <assistant> <revision> <percent> --url <server> [--reason r] [--version n]
   nexus deploy promote <assistant> <revision> --url <server> [--reason r] [--version n]
   nexus deploy rollback <assistant> [--to revision] --url <server> [--reason r] [--version n]
+  nexus policy check <policy.json> [--base <policy.json>|git:<ref>] [--accept path,path] [--json]
   nexus optimize [request.json|prompt.txt] [--model gpt-5-mini] [--max-input-tokens 4000] [--densify] [--json]
 
 Eval files can export { cases, client } or { cases, config }. JSON cases may use "expected", "contains", and "match": "includes" | "exact" | "regex".
@@ -442,7 +449,8 @@ Database modules for "db status" and "db migrate" export { client }, and optiona
 "doctor" exits 1 when a check fails, or with --strict when one warns. Its module exports any of { database, client, redis, operations, ai, deployment, close }.
 "deploy" reads NEXUS_SERVER_URL and NEXUS_SERVER_TOKEN when --url and --token are not given.
 "migrate" moves 1.x root imports to their 2.0 subpaths and reports removed options; --check exits 1 while any remain.
-"graph lint" reads a compiled graph's shape and exits 1 on an error finding, or on a warning with --strict.`);
+"graph lint" reads a compiled graph's shape and exits 1 on an error finding, or on a warning with --strict.
+"policy check" exits 1 when the policy is not valid, or, against --base, when a change that widens what a tenant may reach is not acknowledged.`);
 }
 main().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);

package/dist/core/lifecycle.d.ts

@@ -1,8 +1,9 @@
-import type { RateLimitConfig } from '../types/config.js';
-import type { ProviderHealthOutcome, LifecycleConfig, LifecycleStage, OperationDescriptor, OperationLifecycleLike, OperationResultInfo, OperationStartOptions, OperationTicket, ProviderCallContext } from '../types/lifecycle.js';
 import type { AuditLogger } from '../ops/audit-logger.js';
 import type { MetricsCollector } from '../ops/metrics.js';
 import { type RateLimiter } from '../ops/rate-limiter.js';
+import type { RateLimitConfig } from '../types/config.js';
+import type { ContinuedCallContext, LifecycleConfig, LifecycleStage, OperationDescriptor, OperationLifecycleLike, OperationResultInfo, OperationStartOptions, OperationTicket, ProviderCallContext, ProviderGate, ProviderHealthOutcome } from '../types/lifecycle.js';
+import type { CallResidency, ResidencyDecision, ResidencyPolicy } from '../types/residency.js';
 /** Every lifecycle stage, in the order an operation passes through them. */
 export declare const LIFECYCLE_STAGES: readonly LifecycleStage[];
 /** Raised when `lifecycle.authorize` refuses an operation, before any provider is called. */
@@ -104,6 +105,21 @@ export declare class OperationLifecycle implements OperationLifecycleLike {
     }, plan: OperationPlan<T>, options?: OperationStartOptions & {
         audit?: Record<string, unknown>;
     }): Promise<T>;
+    /**
+     * What a provider call that continues an operation admitted earlier is given, such as a video job
+     * polled after a restart or a batch collected by another worker: its tenant's credentials, resolved
+     * as `start()` resolves them, its residency, and a `scrub()` that keeps them out of its errors.
+     * Nothing is authorized, budgeted, or audited: the operation it continues was.
+     */
+    callContext(input: Omit<OperationDescriptor, 'requestId'> & {
+        requestId?: string;
+    }): Promise<ContinuedCallContext>;
+    /**
+     * Which providers and models an operation may reach, under the residency policy and the provider
+     * gate, or `undefined` when there is neither: what `start()` gives each operation's context, for
+     * code that decides outside one.
+     */
+    access(descriptor: Pick<OperationDescriptor, 'tenantId'> & Partial<OperationDescriptor>): Promise<CallResidency | undefined>;
     /**
      * Reports how a provider answered a call a family made itself, such as a realtime connection, to the
      * client's provider health and circuit breaker.
@@ -114,3 +130,10 @@ export declare class OperationLifecycle implements OperationLifecycleLike {
     private checkRateLimit;
     private authorize;
 }
+/** An operation's residency, as the families that call providers check it. */
+export declare function callResidency(policy: ResidencyPolicy, decision: CallResidency['decision']): CallResidency;
+/**
+ * What an operation may reach: the providers its residency policy allows, and among them those the
+ * provider gate admits, model by model.
+ */
+export declare function callAccess(descriptor: OperationDescriptor | undefined, policy: ResidencyPolicy | undefined, decision: ResidencyDecision | undefined, gate: ProviderGate | undefined): CallResidency;