@nathapp/nax-agent 0.1.0

package/dist/native/credentials/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The credential store, and the one place that reads its file directly.
+ *
+ * This directory is the only place in src/ permitted to import nax-ai
+ * (packages/repo-tooling/scripts/check-nax-ai-imports.ts).
+ *
+ * The store is memoised like client.ts's client: createFileCredentialStore
+ * holds a cross-process lock, and two instances over one path would each take
+ * it, turning a read-modify-write into a contended wait for no reason.
+ *
+ * US-004 assembles the chain the run reads through — the change guard (US-002)
+ * around the chained store (exec helper first, file second) — and exports
+ * `servedAuth` so a cost row can name the account a call was billed to. Its
+ * callers (client.ts:84, auth.ts:121/:204/:238) are synchronous and
+ * the configured auth reader is async, so the chain is built on the first
+ * read/modify/delete and reused for the rest of the process.
+ */
+import { type ProviderId } from "@nathapp/nax-ai";
+import type { AuthStamp } from "#src/session/session-types";
+import { type GuardedCredentialStore } from "./change-guard.ts";
+export type { GuardedCredentialStore } from "./change-guard.ts";
+/** One credential's public facts. Deliberately carries no key. */
+export interface StoredEntry {
+    providerId: string;
+    kind: "api-key" | "oauth";
+    expires?: number;
+}
+export declare function credentialFilePath(): string;
+export declare function naxCredentialStore(): GuardedCredentialStore;
+/**
+ * Clears the memo. Tests only. Dropping it drops the assembled chain with it —
+ * the guard, its exec source and the file store it wraps — and the salt memo
+ * the fingerprints are keyed by.
+ */
+export declare function _resetCredentialStore(): void;
+/**
+ * What the memoised store last observed for `providerId` — the identity a
+ * successful call was billed to. `undefined` until that provider has been read.
+ */
+export declare function servedAuth(providerId: ProviderId): AuthStamp | undefined;
+/**
+ * Is the run configured to take credentials from an exec helper?
+ *
+ * Asked by `NativeAgentAdapter.hasCredentials`, which cannot list a helper's
+ * providers: with `auth.source: "exec"` an empty credential file must not be
+ * read as "no credentials", and asking the helper there would spawn it before
+ * the run has any reason to. Read straight from the global config rather than
+ * from the store's assembly, because this is answered before the store is ever
+ * read.
+ */
+export declare function authSourceIsExec(): Promise<boolean>;
+/**
+ * Enumerate the store by reading its file.
+ *
+ * CredentialStore is read/modify/delete by design and has no list, and this is
+ * the only consumer that needs one. A parse failure throws rather than
+ * reporting an empty store: reporting empty would look exactly like "you have
+ * no credentials" for a file that is merely damaged.
+ */
+export declare function readStoredEntries(): Promise<StoredEntry[]>;

package/dist/native/credentials/index.js

@@ -0,0 +1,184 @@
+/**
+ * The credential store, and the one place that reads its file directly.
+ *
+ * This directory is the only place in src/ permitted to import nax-ai
+ * (packages/repo-tooling/scripts/check-nax-ai-imports.ts).
+ *
+ * The store is memoised like client.ts's client: createFileCredentialStore
+ * holds a cross-process lock, and two instances over one path would each take
+ * it, turning a read-modify-write into a contended wait for no reason.
+ *
+ * US-004 assembles the chain the run reads through — the change guard (US-002)
+ * around the chained store (exec helper first, file second) — and exports
+ * `servedAuth` so a cost row can name the account a call was billed to. Its
+ * callers (client.ts:84, auth.ts:121/:204/:238) are synchronous and
+ * the configured auth reader is async, so the chain is built on the first
+ * read/modify/delete and reused for the rest of the process.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createFileCredentialStore } from "@nathapp/nax-ai";
+import { credentialsConfig, NaxError } from "#src/infra/index";
+import { createChainedCredentialStore } from "./chained-store.js";
+import { createChangeGuard } from "./change-guard.js";
+import { createExecCredentialSource } from "./exec-source.js";
+import { _resetFingerprintSalt } from "./fingerprint.js";
+export function credentialFilePath() {
+    return join(credentialsConfig().configDir(), "credentials");
+}
+/**
+ * Build the chain from the global auth config: a chained store either around
+ * the exec helper (when `auth.source` is "exec") or around the file store
+ * alone, wrapped in the change guard the run reports and refuses through.
+ *
+ * The guard's `describe` reports what the chain decided — which source served
+ * the provider and, for a helper lease, the account label that source reported.
+ * The account travels beside `read`, not through it: `StoredCredential` has no
+ * field for it.
+ */
+async function assembleStore() {
+    const file = createFileCredentialStore({ path: credentialFilePath() });
+    const auth = await credentialsConfig().readAuthConfig();
+    const exec = auth.source === "exec" && auth.exec !== undefined
+        ? createExecCredentialSource({ command: auth.exec.command, timeoutMs: auth.exec.timeoutMs })
+        : undefined;
+    const chained = createChainedCredentialStore(exec === undefined ? { file } : { exec, file });
+    return createChangeGuard(chained, {
+        onChange: auth.onChange,
+        describe: (providerId) => {
+            const source = chained.sourceOf(providerId);
+            if (source === undefined)
+                return undefined;
+            const account = chained.accountOf(providerId);
+            return account === undefined ? { source } : { source, account };
+        },
+    });
+}
+/**
+ * The store handed out by `naxCredentialStore()`, with its chain deferred.
+ *
+ * Deferred because the factory must be synchronous, and kept once built because
+ * the exec source holds leases and the file store holds a cross-process lock: a
+ * `config.json` rewritten in the same directory is not re-read until
+ * `_resetCredentialStore()`.
+ */
+function lazyStore() {
+    let inner;
+    let pending;
+    function resolved() {
+        if (inner !== undefined)
+            return Promise.resolve(inner);
+        if (pending === undefined) {
+            // Dropped on failure, like a failed catalog build in client.ts: a
+            // transient read must not poison every later call in the process. `inner`
+            // is what `servedAuth` reads, so it is set as soon as the chain exists.
+            pending = assembleStore()
+                .then((guard) => {
+                inner = guard;
+                return guard;
+            })
+                .catch((err) => {
+                pending = undefined;
+                throw err;
+            });
+        }
+        return pending;
+    }
+    return {
+        read: async (providerId) => (await resolved()).read(providerId),
+        modify: async (providerId, fn) => (await resolved()).modify(providerId, fn),
+        delete: async (providerId) => (await resolved()).delete(providerId),
+        // Synchronous by contract, and there is nothing to report until the chain
+        // has built itself — which only a read, modify or delete does.
+        servedAuth: (providerId) => inner?.servedAuth(providerId),
+    };
+}
+/**
+ * The store the run reads credentials through, keyed per credential-file path
+ * and global config path: a store pinned to a stale path would write outside
+ * the temp dir a test isolated it into.
+ */
+let memo;
+function storeKey() {
+    const dir = credentialsConfig().configDir();
+    return `${join(dir, "credentials")}\u0000${join(dir, "config.json")}`;
+}
+export function naxCredentialStore() {
+    const key = storeKey();
+    if (memo === undefined || memo.key !== key) {
+        memo = { key, store: lazyStore() };
+    }
+    return memo.store;
+}
+/**
+ * Clears the memo. Tests only. Dropping it drops the assembled chain with it —
+ * the guard, its exec source and the file store it wraps — and the salt memo
+ * the fingerprints are keyed by.
+ */
+export function _resetCredentialStore() {
+    memo = undefined;
+    _resetFingerprintSalt();
+}
+/**
+ * What the memoised store last observed for `providerId` — the identity a
+ * successful call was billed to. `undefined` until that provider has been read.
+ */
+export function servedAuth(providerId) {
+    return naxCredentialStore().servedAuth(providerId);
+}
+/**
+ * Is the run configured to take credentials from an exec helper?
+ *
+ * Asked by `NativeAgentAdapter.hasCredentials`, which cannot list a helper's
+ * providers: with `auth.source: "exec"` an empty credential file must not be
+ * read as "no credentials", and asking the helper there would spawn it before
+ * the run has any reason to. Read straight from the global config rather than
+ * from the store's assembly, because this is answered before the store is ever
+ * read.
+ */
+export async function authSourceIsExec() {
+    return (await credentialsConfig().readAuthConfig()).source === "exec";
+}
+/**
+ * Enumerate the store by reading its file.
+ *
+ * CredentialStore is read/modify/delete by design and has no list, and this is
+ * the only consumer that needs one. A parse failure throws rather than
+ * reporting an empty store: reporting empty would look exactly like "you have
+ * no credentials" for a file that is merely damaged.
+ */
+export async function readStoredEntries() {
+    const path = credentialFilePath();
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new NaxError(`The credential file at ${path} could not be parsed. Refusing to read it.`, "CREDENTIAL_FILE_UNREADABLE", { stage: "credentials", path });
+    }
+    const credentials = parsed?.credentials;
+    if (credentials === undefined ||
+        credentials === null ||
+        typeof credentials !== "object" ||
+        Array.isArray(credentials)) {
+        throw new NaxError(`The credential file at ${path} could not be parsed as a credential store.`, "CREDENTIAL_FILE_UNREADABLE", { stage: "credentials", path });
+    }
+    return Object.entries(credentials)
+        .map(([providerId, value]) => {
+        const kind = value?.kind === "oauth" ? "oauth" : "api-key";
+        const entry = { providerId, kind };
+        if (kind === "oauth" && typeof value?.expires === "number")
+            entry.expires = value.expires;
+        return entry;
+    })
+        .sort((a, b) => (a.providerId < b.providerId ? -1 : a.providerId > b.providerId ? 1 : 0));
+}

package/dist/native/errors.d.ts

@@ -0,0 +1,34 @@
+/**
+ * nax-ai's typed error kinds mapped to nax's failure taxonomy.
+ *
+ * nax-ai returns a discriminated kind, so nothing here parses a message. The
+ * acpx path has to (parseAgentError); this one must not start.
+ *
+ * `category` is an observability tag only: swap behaviour comes from
+ * `failurePolicyFor(outcome)` in `src/agents/retry/failure-policy.ts`, which
+ * keys on `outcome` and never reads `category`. A kind filed under "quality" is
+ * not automatically terminal for the op — `decideSwap` consults the policy table.
+ */
+import { NaxError } from "#src/infra/index";
+import type { AdapterFailure } from "#src/session/adapter-failure";
+/** Finds a known credential-store fault without following an unbounded cause chain. */
+export declare function credentialFaultCode(protocolError: NativeProtocolError): string | undefined;
+/** The shape this module reads off a nax-ai protocol fault. Structural, never the class. */
+export interface NativeProtocolError {
+    readonly kind: string;
+    /** Seconds, when the provider signalled one. */
+    readonly retryAfter?: number;
+    readonly cause?: unknown;
+}
+/**
+ * An unrecognised kind degrades to unknown rather than throwing: a new nax-ai
+ * kind should downgrade one call, not crash the run.
+ *
+ * Takes the whole protocol error, not the bare kind: `retryAfter` is the
+ * provider's own recovery time and the retry layers need it. FAILURES is a
+ * frozen shared table, so the entry is copied rather than assigned onto.
+ */
+export declare function toAdapterFailure(protocolError: NativeProtocolError): AdapterFailure;
+export declare class NativeSessionUnsupportedError extends NaxError {
+    constructor(method: string);
+}

package/dist/native/errors.js

@@ -0,0 +1,109 @@
+/**
+ * nax-ai's typed error kinds mapped to nax's failure taxonomy.
+ *
+ * nax-ai returns a discriminated kind, so nothing here parses a message. The
+ * acpx path has to (parseAgentError); this one must not start.
+ *
+ * `category` is an observability tag only: swap behaviour comes from
+ * `failurePolicyFor(outcome)` in `src/agents/retry/failure-policy.ts`, which
+ * keys on `outcome` and never reads `category`. A kind filed under "quality" is
+ * not automatically terminal for the op — `decideSwap` consults the policy table.
+ */
+import { NaxError } from "#src/infra/index";
+const FAILURES = Object.freeze({
+    "rate-limit": {
+        message: "nax-ai rate limit exceeded",
+        category: "availability",
+        outcome: "fail-rate-limit",
+        retriable: true,
+    },
+    auth: {
+        message: "nax-ai authentication failed",
+        category: "availability",
+        outcome: "fail-auth",
+        retriable: false,
+    },
+    overloaded: {
+        message: "nax-ai service overloaded",
+        category: "availability",
+        outcome: "fail-service-down",
+        retriable: true,
+    },
+    // nax-ai already retried transport faults before the first event. Reaching
+    // here means the retries were exhausted, so the service is unreachable.
+    transport: {
+        message: "nax-ai transport retries exhausted; service unreachable",
+        category: "availability",
+        outcome: "fail-service-down",
+        retriable: true,
+    },
+    // Our request is malformed. A different agent would build the same one.
+    "bad-request": {
+        message: "request malformed; another agent would build the same one",
+        category: "quality",
+        outcome: "fail-adapter-error",
+        retriable: false,
+    },
+    // The prompt outgrew the model's window. Filed as "availability" on purpose,
+    // even though nothing is down: the request was well-formed, and the thing
+    // that could not serve it is this model's window. Another agent's window may
+    // be larger, so the swap is worth attempting -- which "quality" would refuse.
+    // Not retriable: the same agent would rebuild the same oversized request.
+    // Until the native turn loop can compact (nax#1832), the swap is the only
+    // recovery there is.
+    "context-overflow": {
+        message: "prompt exceeded the model's context window; another agent's window may be larger",
+        category: "availability",
+        outcome: "fail-adapter-error",
+        retriable: false,
+    },
+    unknown: {
+        message: "unrecognised nax-ai error kind",
+        category: "quality",
+        outcome: "fail-unknown",
+        retriable: false,
+    },
+});
+const UNKNOWN = FAILURES.unknown;
+const CREDENTIAL_FAULT_CODES = new Set([
+    "CREDENTIAL_HELPER_FAILED",
+    "CREDENTIAL_HELPER_INVALID",
+    "CREDENTIAL_CHANGED",
+    "CREDENTIAL_FILE_UNREADABLE",
+]);
+const MAX_CREDENTIAL_CAUSE_LINKS = 8;
+/** Finds a known credential-store fault without following an unbounded cause chain. */
+export function credentialFaultCode(protocolError) {
+    let current = protocolError.cause;
+    const seen = new Set();
+    for (let link = 0; link < MAX_CREDENTIAL_CAUSE_LINKS; link += 1) {
+        if (typeof current !== "object" || current === null || seen.has(current))
+            return undefined;
+        seen.add(current);
+        if (current instanceof NaxError && CREDENTIAL_FAULT_CODES.has(current.code))
+            return current.code;
+        current = "cause" in current ? current.cause : undefined;
+    }
+    return undefined;
+}
+/**
+ * An unrecognised kind degrades to unknown rather than throwing: a new nax-ai
+ * kind should downgrade one call, not crash the run.
+ *
+ * Takes the whole protocol error, not the bare kind: `retryAfter` is the
+ * provider's own recovery time and the retry layers need it. FAILURES is a
+ * frozen shared table, so the entry is copied rather than assigned onto.
+ */
+export function toAdapterFailure(protocolError) {
+    const credentialCode = credentialFaultCode(protocolError);
+    const base = credentialCode === undefined
+        ? (FAILURES[protocolError.kind] ?? UNKNOWN)
+        : { ...FAILURES.auth, message: `Credential authentication failed: ${credentialCode}` };
+    return protocolError.retryAfter === undefined ? base : { ...base, retryAfterSeconds: protocolError.retryAfter };
+}
+export class NativeSessionUnsupportedError extends NaxError {
+    constructor(method) {
+        super(`The native agent cannot ${method}: it is one-shot until Phase B adds session support. Use an acpx agent for session work.`, "NATIVE_SESSION_UNSUPPORTED", { stage: "session", method });
+        this.name = "NativeSessionUnsupportedError";
+    }
+}

package/dist/native/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The native LLM path: nax's own client, in-process, over @nathapp/nax-ai.
+ *
+ * This directory is the only place in src/ permitted to import nax-ai
+ * (packages/repo-tooling/scripts/check-nax-ai-imports.ts). nax composes it into its AgentAdapter in
+ * `src/agents/native-agent/`, so the wire library stays replaceable.
+ *
+ * The barrel re-exports only; it owns no values. NATIVE_AGENT lives in
+ * models.ts (a leaf) so session-adapter.ts can import it without a cycle back
+ * through this file — `check:import-cycles` runs against a baseline and a new
+ * cycle fails it.
+ */
+export { _adapterDeps } from "./adapter-deps.ts";
+export { AuthCancelledError, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, DEFAULT_PI_AUTH_PATH, type ImportOutcome, importPiCredentials, listStoredProviders, providersWithoutCredentials, removeStoredProvider, runLogin, } from "./auth.ts";
+export type { AuthEvent, AuthInteraction, AuthLink, AuthMethod, AuthOption, AuthPrompt, AuthResult, } from "./auth-types.ts";
+export type { NativeCatalogOverrides } from "./client.ts";
+export { type NativeCompleteContext, type NativeCompleteOptions, type NativeCompleteResult, nativeComplete, } from "./complete.ts";
+export { credentialFilePath, naxCredentialStore, type StoredEntry, servedAuth } from "./credentials/index.ts";
+export { NativeSessionUnsupportedError } from "./errors.ts";
+export { type ResolveResult, type ResolveStatus, resolveNativeId, } from "./model-resolver.ts";
+export { NATIVE_AGENT } from "./models.ts";
+export { MAX_RETAINED_TRANSCRIPTS, pruneRetainedTranscripts, } from "./session/transcript-store.ts";
+export { NativeSessionAdapter } from "./session-adapter.ts";
+export { newSessionKey } from "./session-affinity.ts";
+export { type NativeTierConfig, nativeTierProviders } from "./tier-providers.ts";

package/dist/native/index.js

@@ -0,0 +1,23 @@
+/**
+ * The native LLM path: nax's own client, in-process, over @nathapp/nax-ai.
+ *
+ * This directory is the only place in src/ permitted to import nax-ai
+ * (packages/repo-tooling/scripts/check-nax-ai-imports.ts). nax composes it into its AgentAdapter in
+ * `src/agents/native-agent/`, so the wire library stays replaceable.
+ *
+ * The barrel re-exports only; it owns no values. NATIVE_AGENT lives in
+ * models.ts (a leaf) so session-adapter.ts can import it without a cycle back
+ * through this file — `check:import-cycles` runs against a baseline and a new
+ * cycle fails it.
+ */
+export { _adapterDeps } from "./adapter-deps.js";
+export { AuthCancelledError, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, DEFAULT_PI_AUTH_PATH, importPiCredentials, listStoredProviders, providersWithoutCredentials, removeStoredProvider, runLogin, } from "./auth.js";
+export { nativeComplete, } from "./complete.js";
+export { credentialFilePath, naxCredentialStore, servedAuth } from "./credentials/index.js";
+export { NativeSessionUnsupportedError } from "./errors.js";
+export { resolveNativeId, } from "./model-resolver.js";
+export { NATIVE_AGENT } from "./models.js";
+export { MAX_RETAINED_TRANSCRIPTS, pruneRetainedTranscripts, } from "./session/transcript-store.js";
+export { NativeSessionAdapter } from "./session-adapter.js";
+export { newSessionKey } from "./session-affinity.js";
+export { nativeTierProviders } from "./tier-providers.js";

package/dist/native/model-resolver.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Native model resolver — owns the local catalog lookup for native ids.
+ *
+ * Precheck must not import nax-ai directly (packages/repo-tooling/scripts/check-nax-ai-imports.ts),
+ * so the resolver sits next to the rest of the native path. Production callers
+ * go through `resolveNativeId` (which uses the cached nax-ai client); tests
+ * bypass the function entirely and stub `_modelResolutionDeps` in
+ * `src/precheck/checks-model-resolution.ts` to drive specific outcomes without
+ * loading the bundled catalog.
+ *
+ * Three states the resolver reports:
+ *   - "resolved":     id resolves in the catalog (optionally with override data)
+ *   - "unresolved":   id is provider-qualified but absent from the catalog and
+ *                     not declared under agent.native.catalogOverrides
+ *   - "error":        the catalog itself failed to load (network, schema, …)
+ *
+ * The third state is a warning, not a blocker — a transient catalog miss
+ * should not stop a run, but it must be surfaced loudly enough to prevent the
+ * adversarial-review parse error the story exists to fix.
+ */
+import type { ProviderCatalogOverride } from "#src/config/catalog-overrides";
+export type ResolveStatus = "resolved" | "unresolved" | "error";
+export interface ResolveResult {
+    status: ResolveStatus;
+    /**
+     * When `status === "resolved"` and the matched entry declared pricing /
+     * contextWindow, the resolved values. The precheck check uses the PRESENCE
+     * of these fields to decide whether a literal pin dropped tier-configured
+     * overrides — the actual numbers do not need to flow through.
+     */
+    hasPricing?: boolean;
+    hasContextWindow?: boolean;
+}
+/**
+ * Production resolver. Builds the cached client once per override set, then
+ * calls `client.model(provider, model)` for every native id the precheck
+ * walker hands it. The bundled catalog loads once per process via
+ * `getNativeClient` (cached) so repeated calls amortise to a single load.
+ *
+ * Status mapping:
+ *   - "resolved":   id resolves from the override-aware `client.model()` call
+ *   - "error":      `getNativeClient(overrides)` rejected (catalog load
+ *                   failed — network, schema, …). AC6 requires the check
+ *                   to surface this as a warning, not a blocker, because
+ *                   a transient catalog miss should not stop a run.
+ *   - "unresolved": client built successfully but `client.model()` rejected
+ *                   for this (provider, model) pair — id absent from the
+ *                   catalog. The check emits a blocker at that site
+ *                   (AC1/AC2), because the bundled snapshot not knowing
+ *                   an id is the failure mode `nax#1983` exists to catch.
+ *
+ * The two catch arms are split so the resolver honours the AC6 contract;
+ * a single `try { … } catch { "unresolved" }` would collapse the catalog
+ * load failure into a per-id blocker and leave the "error" handlers in
+ * `checkModelResolution` permanently dead code.
+ */
+export declare function resolveNativeId(provider: string, model: string, overrides: readonly ProviderCatalogOverride[]): Promise<ResolveResult>;

package/dist/native/model-resolver.js

@@ -0,0 +1,73 @@
+/**
+ * Native model resolver — owns the local catalog lookup for native ids.
+ *
+ * Precheck must not import nax-ai directly (packages/repo-tooling/scripts/check-nax-ai-imports.ts),
+ * so the resolver sits next to the rest of the native path. Production callers
+ * go through `resolveNativeId` (which uses the cached nax-ai client); tests
+ * bypass the function entirely and stub `_modelResolutionDeps` in
+ * `src/precheck/checks-model-resolution.ts` to drive specific outcomes without
+ * loading the bundled catalog.
+ *
+ * Three states the resolver reports:
+ *   - "resolved":     id resolves in the catalog (optionally with override data)
+ *   - "unresolved":   id is provider-qualified but absent from the catalog and
+ *                     not declared under agent.native.catalogOverrides
+ *   - "error":        the catalog itself failed to load (network, schema, …)
+ *
+ * The third state is a warning, not a blocker — a transient catalog miss
+ * should not stop a run, but it must be surfaced loudly enough to prevent the
+ * adversarial-review parse error the story exists to fix.
+ */
+import { getNativeClient } from "./client.js";
+/**
+ * Production resolver. Builds the cached client once per override set, then
+ * calls `client.model(provider, model)` for every native id the precheck
+ * walker hands it. The bundled catalog loads once per process via
+ * `getNativeClient` (cached) so repeated calls amortise to a single load.
+ *
+ * Status mapping:
+ *   - "resolved":   id resolves from the override-aware `client.model()` call
+ *   - "error":      `getNativeClient(overrides)` rejected (catalog load
+ *                   failed — network, schema, …). AC6 requires the check
+ *                   to surface this as a warning, not a blocker, because
+ *                   a transient catalog miss should not stop a run.
+ *   - "unresolved": client built successfully but `client.model()` rejected
+ *                   for this (provider, model) pair — id absent from the
+ *                   catalog. The check emits a blocker at that site
+ *                   (AC1/AC2), because the bundled snapshot not knowing
+ *                   an id is the failure mode `nax#1983` exists to catch.
+ *
+ * The two catch arms are split so the resolver honours the AC6 contract;
+ * a single `try { … } catch { "unresolved" }` would collapse the catalog
+ * load failure into a per-id blocker and leave the "error" handlers in
+ * `checkModelResolution` permanently dead code.
+ */
+export async function resolveNativeId(provider, model, overrides) {
+    // The native client's `Client` type comes from nax-ai; we declare the
+    // variable as `unknown` to keep the file free of nax-ai type imports
+    // (packages/repo-tooling/scripts/check-nax-ai-imports.ts forbids it). The single property we
+    // touch (`model(provider, model)`) is what we actually need.
+    let client;
+    try {
+        // Catalog load failure — the bundled snapshot itself is unavailable
+        // (network, schema mismatch, …). Distinct from "id not in catalog":
+        // the resolver never got far enough to look anything up.
+        client = await getNativeClient(overrides);
+    }
+    catch {
+        return { status: "error" };
+    }
+    try {
+        const resolved = await client.model(provider, model);
+        return {
+            status: "resolved",
+            hasPricing: resolved.pricing !== undefined,
+            hasContextWindow: resolved.contextWindow !== undefined,
+        };
+    }
+    catch {
+        // Client built successfully but this (provider, model) is not in the
+        // catalog. Per AC1/AC2 the check emits a blocker at this site.
+        return { status: "unresolved" };
+    }
+}