nexus-ai-pro 2.13.0 → 2.14.0

package/API_STABILITY.md

@@ -41,6 +41,36 @@ 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.

package/CHANGELOG.md

@@ -4,6 +4,48 @@ 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.
@@ -2946,7 +2988,8 @@ 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.13.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

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,7 @@ 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 |
@@ -312,14 +313,18 @@ Shipped so far:
 - 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.
+  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.14 makes policy a reviewed file, checked by the command line before it ships, brings
-per-tenant keys to every family, and lets an evaluation run an agent over emulated tools with nothing
-sent. 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,9 +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 { CallResidency, ResidencyPolicy } from '../types/residency.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. */
@@ -105,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.
@@ -117,3 +132,8 @@ export declare class OperationLifecycle implements OperationLifecycleLike {
 }
 /** 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;

package/dist/core/lifecycle.js

@@ -41,7 +41,12 @@ export class OperationLifecycle {
         this.runtime = runtime;
     }
     async start(input, options = {}) {
-        const descriptor = { ...input, requestId: input.requestId?.trim() || generateRequestId() };
+        const policyReference = this.runtime.config?.policy;
+        const descriptor = {
+            ...input,
+            requestId: input.requestId?.trim() || generateRequestId(),
+            ...(policyReference && !input.policy ? { policy: policyReference } : {}),
+        };
         const startedAt = Date.now();
         const timeoutMs = options.timeoutMs ?? this.runtime.timeoutMs;
         const deadline = timeoutMs !== undefined && Number.isFinite(timeoutMs) && timeoutMs > 0 ? startedAt + timeoutMs : undefined;
@@ -64,11 +69,11 @@ export class OperationLifecycle {
             await this.runtime.metrics?.recordRequest(labelsOf(descriptor));
             await this.checkRateLimit(descriptor);
             await this.authorize(descriptor);
-            const policy = this.runtime.config?.residency;
-            if (policy) {
-                context.residency = callResidency(policy, await policy.regionsFor(descriptor.tenantId));
+            const access = await this.access(descriptor);
+            if (access) {
+                context.residency = access;
                 if (descriptor.provider)
-                    context.residency.check(descriptor.provider);
+                    access.check(descriptor.provider, descriptor.model);
             }
         }
         catch (error) {
@@ -87,7 +92,7 @@ export class OperationLifecycle {
             await plan.resolveAssets?.(ticket.context);
             const routed = await plan.route?.();
             if (routed?.provider) {
-                ticket.context.residency?.check(routed.provider);
+                ticket.context.residency?.check(routed.provider, routed.model ?? ticket.descriptor.model);
                 ticket.descriptor.provider = routed.provider;
             }
             if (routed?.model)
@@ -106,6 +111,26 @@ export class OperationLifecycle {
             throw error;
         }
     }
+    async callContext(input) {
+        const descriptor = { ...input, requestId: input.requestId?.trim() || generateRequestId() };
+        const credentials = this.runtime.config?.credentials
+            ? new CallCredentials(this.runtime.config.credentials, descriptor)
+            : undefined;
+        const residency = await this.access(descriptor);
+        return {
+            ...(descriptor.tenantId !== undefined ? { tenantId: descriptor.tenantId } : {}),
+            ...(credentials ? { credential: (provider) => credentials.resolve(provider) } : {}),
+            ...(residency ? { residency } : {}),
+            scrub: (error) => (credentials ? scrubSecrets(error, credentials.secrets) : error),
+        };
+    }
+    async access(descriptor) {
+        const policy = this.runtime.config?.residency;
+        const gate = this.runtime.config?.providers;
+        if (!policy && !gate)
+            return undefined;
+        return callAccess(descriptor, policy, policy ? await policy.regionsFor(descriptor.tenantId) : undefined, gate);
+    }
     reportHealth(provider, outcome) {
         const health = this.runtime.providerHealth;
         if (!health || !provider)
@@ -124,7 +149,9 @@ export class OperationLifecycle {
             !config?.budget &&
             !config?.hooks &&
             !config?.credentials &&
-            !config?.residency);
+            !config?.residency &&
+            !config?.providers &&
+            !config?.policy);
     }
     async checkRateLimit(descriptor) {
         const { rateLimiter, rateLimit } = this.runtime;
@@ -160,13 +187,48 @@ export class OperationLifecycle {
     }
 }
 export function callResidency(policy, decision) {
+    return callAccess(undefined, policy, decision, undefined);
+}
+export function callAccess(descriptor, policy, decision, gate) {
+    const resolved = decision ?? { rule: 'any region' };
+    const admits = (provider, model) => !gate || !descriptor || gate.check(descriptor, provider, model) === true;
+    const resident = (provider) => !policy || policy.allows(policy.regionOf(provider), resolved);
+    const checkResidency = (provider) => {
+        if (!policy)
+            return;
+        const region = policy.regionOf(provider);
+        policy.check({ kind: 'provider', name: provider, ...(region ? { region } : {}) }, resolved);
+    };
+    const checkGate = (provider, model) => {
+        if (!gate || !descriptor)
+            return;
+        const verdict = gate.check(descriptor, provider, model);
+        if (verdict !== true)
+            throw new OperationDeniedError(descriptor, verdict);
+    };
     return {
-        decision,
-        allows: (provider) => policy.allows(policy.regionOf(provider), decision),
-        place: (provider) => policy.place(provider, decision),
-        check: (provider) => {
-            const region = policy.regionOf(provider);
-            policy.check({ kind: 'provider', name: provider, ...(region ? { region } : {}) }, decision);
+        decision: resolved,
+        allows: (provider, model) => resident(provider) && admits(provider, model),
+        place: (provider, model) => {
+            const placed = policy ? policy.place(provider, resolved) : { provider };
+            return placed && admits(placed.provider, model) ? placed : undefined;
+        },
+        check: (provider, model) => {
+            checkResidency(provider);
+            checkGate(provider, model);
+        },
+        refusal: (provider, model) => {
+            try {
+                const placed = policy ? policy.place(provider, resolved) : { provider };
+                if (!placed)
+                    checkResidency(provider);
+                else
+                    checkGate(placed.provider, model);
+                return undefined;
+            }
+            catch (error) {
+                return error;
+            }
         },
     };
 }
@@ -320,6 +382,7 @@ class Ticket {
             model: this.descriptor.model,
             provider: this.descriptor.provider,
             timestamp: new Date().toISOString(),
+            ...(this.descriptor.policy ? { policy: this.descriptor.policy } : {}),
             ...(this.descriptor.metadata || metadata ? { metadata: { ...this.descriptor.metadata, ...metadata } } : {}),
         });
     }