nexus-ai-pro 2.4.0 → 2.5.0

package/dist/version.js

@@ -1 +1 @@
-export const NEXUS_VERSION = '2.4.0';
+export const NEXUS_VERSION = '2.5.0';

package/dist-cjs/context-hub/hub.d.ts

@@ -2,6 +2,7 @@ import type { GateResult } from '../prompts/errors.js';
 import type { PromptRegistry } from '../prompts/registry.js';
 import type { PromptHistoryEntry, PromptLabel, PromptStore, PromptVersion, RenderedPrompt, RenderOptions } from '../types/prompts.js';
 import { type ContextDiff } from './diff.js';
+import { type ContextKeyring, type ContextSignature, type ContextSigner } from './signing.js';
 /** A prompt a bundle uses, pinned to one content version of the prompt registry. */
 export interface ContextPromptPin {
     /** The prompt's name in the registry. */
@@ -61,6 +62,8 @@ export interface ContextBundle extends ContextBundleDefinition {
     author?: string;
     /** The version that was newest before it. */
     parent?: string;
+    /** Signatures over its content and its pinned prompts' content. Not part of the version. */
+    signatures?: ContextSignature[];
 }
 /** Which bundle version is being used, as experiments and traces record it. */
 export interface ContextReference {
@@ -125,9 +128,33 @@ export interface ContextHubOptions {
     gates?: Record<string, readonly ContextPromotionGate[]>;
     /** Called after every recorded change. */
     onChange?: (entry: ContextHistoryEntry) => void | Promise<void>;
+    /**
+     * Signs every new version, over its content and its pinned prompts' content, so another hub can
+     * check where it came from. Signing a bundle that pins prompts needs `prompts`.
+     */
+    signer?: ContextSigner;
+    /**
+     * The keys whose signatures this hub trusts, for `verify()`, and for `requireSignature`. A signature
+     * by a key the keyring does not hold is kept, but never trusted.
+     */
+    keyring?: ContextKeyring;
+    /**
+     * Refuses any bundle without a valid signature by a key in `keyring`: on import, and whenever a
+     * version is served through `resolve()` or `renderPrompt()`.
+     */
+    requireSignature?: boolean;
     /** Replaces the system clock, for tests. */
     now?: () => Date;
 }
+/** What `ContextHub.verify()` found. */
+export interface ContextVerification {
+    /** Whether a key in the keyring signed exactly this content. */
+    trusted: boolean;
+    /** The digest the content has now. */
+    digest: string;
+    /** The signature that verified, when one did. */
+    signature?: ContextSignature;
+}
 /** Base class for context hub errors, each with a stable `code`. */
 export declare class ContextHubError extends Error {
     /** Stable code, such as `CONTEXT_NOT_FOUND`. */
@@ -160,6 +187,18 @@ export declare class ContextPromotionError extends ContextHubError {
     /** Every gate's verdict. */
     results: GateResult[]);
 }
+/** Raised when a bundle has no signature the hub trusts, or its signatures do not match its content. */
+export declare class ContextSignatureError extends ContextHubError {
+    /** The bundle. */
+    readonly bundle: string;
+    /** The version. */
+    readonly version: string;
+    constructor(
+    /** The bundle. */
+    bundle: string, 
+    /** The version. */
+    version: string, reason: string);
+}
 /** Raised when a bundle definition, a pin, or an import is invalid. */
 export declare class ContextDefinitionError extends ContextHubError {
     constructor(message: string);
@@ -182,6 +221,8 @@ export declare class ContextHub {
     /** Where versions, labels, and history live. */
     readonly store: PromptStore;
     private readonly now;
+    /** Versions already verified as trusted, which never change. */
+    private readonly trusted;
     constructor(options?: ContextHubOptions);
     /**
      * Commits a bundle and returns its version. Unchanged content returns the existing version and
@@ -193,8 +234,15 @@ export declare class ContextHub {
         author?: string;
         label?: string | readonly string[];
     }): Promise<ContextBundle>;
+    private commitSigned;
     /** A version by content version, label, or `latest`, the default. Throws `ContextNotFoundError` when there is none. */
     get(name: string, ref?: string): Promise<ContextBundle>;
+    /**
+     * Whether a key in the hub's keyring signed exactly this bundle's content, and its pinned prompts'
+     * content as the prompt registry holds them. A version's answer never changes, so it is checked
+     * once.
+     */
+    verify(bundle: ContextBundle): Promise<ContextVerification>;
     /** A version with the reference experiments and traces record for it. */
     resolve(name: string, ref?: string): Promise<{
         bundle: ContextBundle;
@@ -262,6 +310,11 @@ export declare class ContextHub {
         label?: string | readonly string[];
         by?: string;
     }): Promise<ContextBundle>;
+    /** Refuses a bundle without a trusted signature, when the hub requires one. */
+    private assertTrusted;
+    private check;
+    /** What a signature over this bundle covers, with its pinned prompts read from the registry. */
+    private signedContent;
     private read;
     private pointer;
     private record;

package/dist-cjs/context-hub/hub.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ContextHub = exports.ContextDefinitionError = exports.ContextPromotionError = exports.ContextConflictError = exports.ContextNotFoundError = exports.ContextHubError = void 0;
+exports.ContextHub = exports.ContextDefinitionError = exports.ContextSignatureError = exports.ContextPromotionError = exports.ContextConflictError = exports.ContextNotFoundError = exports.ContextHubError = void 0;
 exports.contextVersion = contextVersion;
 const memory_js_1 = require("../prompts/memory.js");
 const version_js_1 = require("../prompts/version.js");
 const diff_js_1 = require("./diff.js");
+const signing_js_1 = require("./signing.js");
 class ContextHubError extends Error {
     code;
     constructor(message, code) {
@@ -44,6 +45,17 @@ class ContextPromotionError extends ContextHubError {
     }
 }
 exports.ContextPromotionError = ContextPromotionError;
+class ContextSignatureError extends ContextHubError {
+    bundle;
+    version;
+    constructor(bundle, version, reason) {
+        super(`Context bundle "${bundle}" ${version}: ${reason}`, 'CONTEXT_SIGNATURE');
+        this.bundle = bundle;
+        this.version = version;
+        this.name = 'ContextSignatureError';
+    }
+}
+exports.ContextSignatureError = ContextSignatureError;
 class ContextDefinitionError extends ContextHubError {
     constructor(message) {
         super(message, 'CONTEXT_DEFINITION_ERROR');
@@ -72,12 +84,19 @@ class ContextHub {
     options;
     store;
     now;
+    trusted = new Map();
     constructor(options = {}) {
         this.options = options;
+        if (options.requireSignature && !options.keyring) {
+            throw new TypeError('requireSignature needs a keyring of the keys the hub trusts');
+        }
         this.store = options.store ?? new memory_js_1.MemoryPromptStore();
         this.now = options.now ?? (() => new Date());
     }
     async commit(definition, options = {}) {
+        return this.commitSigned(definition, options, []);
+    }
+    async commitSigned(definition, options, inherited) {
         validate(definition);
         if (this.options.prompts) {
             for (const [role, pin] of Object.entries(definition.prompts ?? {})) {
@@ -101,6 +120,13 @@ class ContextHub {
                 ...(options.author === undefined ? {} : { author: options.author }),
                 ...(newest ? { parent: newest.version } : {}),
             };
+            const signatures = [...inherited];
+            if (this.options.signer) {
+                const digest = await (0, signing_js_1.contextDigest)(await this.signedContent(definition));
+                signatures.push(await (0, signing_js_1.signDigest)(this.options.signer, digest, this.now()));
+            }
+            if (signatures.length > 0)
+                stored.signatures = signatures;
             await this.store.saveVersion(toStored(stored));
             await this.record({ name: definition.name, action: 'commit', version: id, by: options.author });
         }
@@ -127,8 +153,19 @@ class ContextHub {
             throw new ContextNotFoundError(name, ref);
         return found;
     }
+    async verify(bundle) {
+        const key = `${bundle.name}@${bundle.version}`;
+        let pending = this.trusted.get(key);
+        if (!pending) {
+            pending = this.check(bundle, await this.signedContent(bundle));
+            this.trusted.set(key, pending);
+            pending.catch(() => this.trusted.delete(key));
+        }
+        return pending;
+    }
     async resolve(name, ref = 'latest') {
         const bundle = await this.get(name, ref);
+        await this.assertTrusted(bundle);
         return {
             bundle,
             reference: {
@@ -142,6 +179,7 @@ class ContextHub {
         const registry = this.options.prompts;
         if (!registry)
             throw new ContextDefinitionError('Rendering a pinned prompt needs the hub to have a prompt registry');
+        await this.assertTrusted(bundle);
         const pin = bundle.prompts?.[role];
         if (!pin)
             throw new ContextNotFoundError(bundle.name, `prompt role "${role}"`);
@@ -268,15 +306,52 @@ class ContextHub {
                 throw new ContextDefinitionError(`Prompt ${prompt.name} was exported as ${version} but its content is ${committed.version}`);
             }
         }
-        const { version, createdAt: _createdAt, parent: _parent, message, author, ...definition } = exported.bundle;
+        const { version, createdAt: _createdAt, parent: _parent, message, author, signatures = [], ...definition } = exported.bundle;
         if ((await contextVersion(definition)) !== version) {
             throw new ContextDefinitionError(`Bundle ${definition.name} was exported as ${version} but its content has changed`);
         }
-        return this.commit(definition, {
+        const digest = await (0, signing_js_1.contextDigest)(signedContentOf(definition, exportedPrompts(exported)));
+        const claims = signatures.filter((signature) => signature?.digest === digest);
+        if (this.options.requireSignature && this.options.keyring) {
+            const signed = await (0, signing_js_1.verifiedBy)(this.options.keyring, digest, claims);
+            if (!signed) {
+                throw new ContextSignatureError(definition.name, version, signatures.length > 0
+                    ? 'no signature verifies against its content with a trusted key'
+                    : 'it is not signed, and this hub requires a signature');
+            }
+        }
+        return this.commitSigned(definition, {
             message: message ?? 'imported',
             ...((options.by ?? author) === undefined ? {} : { author: options.by ?? author }),
             ...(options.label === undefined ? {} : { label: options.label }),
-        });
+        }, claims);
+    }
+    async assertTrusted(bundle) {
+        if (!this.options.requireSignature)
+            return;
+        const verification = await this.verify(bundle);
+        if (!verification.trusted) {
+            throw new ContextSignatureError(bundle.name, bundle.version, bundle.signatures?.length
+                ? 'no signature verifies against its content with a trusted key'
+                : 'it is not signed, and this hub requires a signature');
+        }
+    }
+    async check(bundle, content) {
+        const digest = await (0, signing_js_1.contextDigest)(content);
+        const signature = this.options.keyring
+            ? await (0, signing_js_1.verifiedBy)(this.options.keyring, digest, bundle.signatures)
+            : undefined;
+        return { trusted: signature !== undefined, digest, ...(signature ? { signature } : {}) };
+    }
+    async signedContent(definition) {
+        const pins = Object.entries(definition.prompts ?? {});
+        if (pins.length > 0 && !this.options.prompts) {
+            throw new ContextDefinitionError(`Bundle "${definition.name}" pins prompts; signing or verifying it needs the hub to have a prompt registry`);
+        }
+        const prompts = [];
+        for (const [, pin] of pins)
+            prompts.push(await this.options.prompts.get(pin.name, pin.version));
+        return signedContentOf(definition, prompts);
     }
     async read(name, version) {
         const stored = await this.store.getVersion(name, version);
@@ -314,6 +389,37 @@ function validate(definition) {
         }
     }
 }
+function signedContentOf(definition, prompts) {
+    const byPin = new Map(prompts.map((prompt) => [`${prompt.name}@${prompt.version}`, prompt]));
+    const pinned = {};
+    for (const [role, pin] of Object.entries(definition.prompts ?? {})) {
+        const prompt = byPin.get(`${pin.name}@${pin.version}`);
+        if (!prompt)
+            throw new ContextDefinitionError(`Bundle "${definition.name}" pins ${role} to ${pin.name}@${pin.version}, which is not at hand`);
+        pinned[role] = {
+            name: prompt.name,
+            messages: prompt.messages,
+            partials: prompt.partials,
+            config: prompt.config,
+            defaults: prompt.defaults,
+        };
+    }
+    return {
+        bundle: {
+            name: definition.name,
+            description: definition.description,
+            prompts: definition.prompts,
+            instructions: definition.instructions,
+            tools: definition.tools,
+            skills: definition.skills,
+            config: definition.config,
+        },
+        prompts: pinned,
+    };
+}
+function exportedPrompts(exported) {
+    return exported.prompts;
+}
 function toStored(bundle) {
     return { ...bundle, messages: [], variables: [] };
 }

package/dist-cjs/context-hub/index.d.ts

@@ -4,8 +4,9 @@ import type { Dataset, DatasetExample, Evaluator, Experiment } from '../types/ev
 import type { ToolDefinition } from '../types/messages.js';
 import type { ContextBundle, ContextPromotionGate } from './hub.js';
 export { type ContextChange, type ContextDiff, diffContexts, formatContextDiff } from './diff.js';
-export { type ContextBundle, type ContextBundleDefinition, type ContextBundleExport, ContextConflictError, ContextDefinitionError, type ContextHistoryEntry, ContextHub, ContextHubError, type ContextHubOptions, type ContextLabel, ContextNotFoundError, type ContextPromotionContext, ContextPromotionError, type ContextPromotionGate, type ContextPromotionResult, type ContextPromptPin, type ContextReference, type ContextSkill, type ContextTool, contextVersion, } from './hub.js';
+export { type ContextBundle, type ContextBundleDefinition, type ContextBundleExport, ContextConflictError, ContextDefinitionError, type ContextHistoryEntry, ContextHub, ContextHubError, type ContextHubOptions, type ContextLabel, ContextNotFoundError, type ContextPromotionContext, ContextPromotionError, type ContextPromotionGate, ContextSignatureError, type ContextVerification, type ContextPromotionResult, type ContextPromptPin, type ContextReference, type ContextSkill, type ContextTool, contextVersion, } from './hub.js';
 export type { ExperimentGateOptions } from '../prompts/gates.js';
+export { type ContextCryptoKey, type ContextJsonWebKey, type ContextKeyring, type ContextSignature, type ContextSignedContent, type ContextSigner, type ContextSigningKey, contextDigest, ed25519Keyring, ed25519Signer, generateContextKey, } from './signing.js';
 /**
  * A bundle's instructions joined into one system text, in the order the bundle lists them, or only
  * the ones named in `include`, in that order.

package/dist-cjs/context-hub/index.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.contextVersion = exports.ContextPromotionError = exports.ContextNotFoundError = exports.ContextHubError = exports.ContextHub = exports.ContextDefinitionError = exports.ContextConflictError = exports.formatContextDiff = exports.diffContexts = void 0;
+exports.generateContextKey = exports.ed25519Signer = exports.ed25519Keyring = exports.contextDigest = exports.contextVersion = exports.ContextSignatureError = exports.ContextPromotionError = exports.ContextNotFoundError = exports.ContextHubError = exports.ContextHub = exports.ContextDefinitionError = exports.ContextConflictError = exports.formatContextDiff = exports.diffContexts = void 0;
 exports.contextInstructions = contextInstructions;
 exports.bindTools = bindTools;
 exports.evaluateContext = evaluateContext;
@@ -51,7 +51,13 @@ Object.defineProperty(exports, "ContextHub", { enumerable: true, get: function (
 Object.defineProperty(exports, "ContextHubError", { enumerable: true, get: function () { return hub_js_1.ContextHubError; } });
 Object.defineProperty(exports, "ContextNotFoundError", { enumerable: true, get: function () { return hub_js_1.ContextNotFoundError; } });
 Object.defineProperty(exports, "ContextPromotionError", { enumerable: true, get: function () { return hub_js_1.ContextPromotionError; } });
+Object.defineProperty(exports, "ContextSignatureError", { enumerable: true, get: function () { return hub_js_1.ContextSignatureError; } });
 Object.defineProperty(exports, "contextVersion", { enumerable: true, get: function () { return hub_js_1.contextVersion; } });
+var signing_js_1 = require("./signing.js");
+Object.defineProperty(exports, "contextDigest", { enumerable: true, get: function () { return signing_js_1.contextDigest; } });
+Object.defineProperty(exports, "ed25519Keyring", { enumerable: true, get: function () { return signing_js_1.ed25519Keyring; } });
+Object.defineProperty(exports, "ed25519Signer", { enumerable: true, get: function () { return signing_js_1.ed25519Signer; } });
+Object.defineProperty(exports, "generateContextKey", { enumerable: true, get: function () { return signing_js_1.generateContextKey; } });
 function contextInstructions(bundle, options = {}) {
     const names = options.include ?? Object.keys(bundle.instructions ?? {});
     return names

package/dist-cjs/context-hub/signing.d.ts

@@ -0,0 +1,95 @@
+import type { PromptDefinition } from '../types/prompts.js';
+/** A JSON Web Key, as Web Crypto exports one. */
+export interface ContextJsonWebKey {
+    /** The key type: `OKP` for Ed25519. */
+    kty?: string;
+    /** The curve: `Ed25519`. */
+    crv?: string;
+    /** The public key, in base64url. */
+    x?: string;
+    /** The private key, in base64url, on a private key only. */
+    d?: string;
+    /** Anything else the exporter wrote. */
+    [field: string]: unknown;
+}
+/** A Web Crypto key, as `crypto.subtle` returns one. Any runtime's `CryptoKey` is one. */
+export interface ContextCryptoKey {
+    /** Its algorithm. */
+    readonly algorithm: unknown;
+    /** What it may do. */
+    readonly usages: readonly string[];
+}
+/** One signature on a bundle version. Stored with it, and carried by its export. */
+export interface ContextSignature {
+    /** The id of the key that signed, which a keyring looks up. */
+    keyId: string;
+    /** Always `Ed25519`. */
+    algorithm: 'Ed25519';
+    /**
+     * What was signed: `sha256:` and the full SHA-256, in hex, of the bundle's content and the content
+     * of every prompt it pins. A bundle's version is only the first 12 hex digits, enough to name a
+     * version but not to stand behind a signature.
+     */
+    digest: string;
+    /** The signature over the digest, in base64url. */
+    signature: string;
+    /** ISO-8601 time it was signed. */
+    signedAt: string;
+}
+/** Signs bundle digests with a private key, under a key id. */
+export interface ContextSigner {
+    /** The key's id, recorded on each signature so a keyring finds the public key. */
+    keyId: string;
+    /** Signs bytes. */
+    sign(data: Uint8Array): Promise<Uint8Array> | Uint8Array;
+}
+/** Verifies signatures by key id. A signature by a key the keyring does not hold never verifies. */
+export interface ContextKeyring {
+    /** Whether `signature` is `keyId`'s signature over `data`. */
+    verify(keyId: string, data: Uint8Array, signature: Uint8Array): Promise<boolean> | boolean;
+}
+/** A new signing key, with both halves as JSON Web Keys to keep in a secret store. */
+export interface ContextSigningKey {
+    /** The key's id. */
+    keyId: string;
+    /** Signs with the new key. */
+    signer: ContextSigner;
+    /** The public half, for every keyring that should trust it. */
+    publicKey: ContextJsonWebKey;
+    /** The private half. Keep it where the signer runs, and nowhere else. */
+    privateKey: ContextJsonWebKey;
+}
+/**
+ * Creates an Ed25519 signing key through Web Crypto, so on any runtime. The key id defaults to the
+ * first 16 hex digits of the public key's SHA-256, which is stable for the key and names nothing
+ * else.
+ */
+export declare function generateContextKey(keyId?: string): Promise<ContextSigningKey>;
+/** A signer from an Ed25519 private key, as a JSON Web Key or a Web Crypto key. */
+export declare function ed25519Signer(keyId: string, privateKey: ContextJsonWebKey | ContextCryptoKey): Promise<ContextSigner>;
+/** A keyring of trusted Ed25519 public keys, by key id. */
+export declare function ed25519Keyring(keys: Record<string, ContextJsonWebKey | ContextCryptoKey>): Promise<ContextKeyring>;
+/** What a bundle signature covers: the bundle's versioned content, and its pinned prompts' content. */
+export interface ContextSignedContent {
+    /** The bundle's name and the content its version covers. */
+    bundle: {
+        name: string;
+        description?: string;
+        prompts?: Record<string, {
+            name: string;
+            version: string;
+        }>;
+        instructions?: Record<string, string>;
+        tools?: unknown;
+        skills?: unknown;
+        config?: Record<string, unknown>;
+    };
+    /** Each pinned prompt's content, by role: what its own version covers. */
+    prompts: Record<string, Pick<PromptDefinition, 'name' | 'messages' | 'partials' | 'config' | 'defaults'>>;
+}
+/** The digest a signature covers, as `sha256:` and 64 hex digits. */
+export declare function contextDigest(content: ContextSignedContent): Promise<string>;
+/** Signs a digest. */
+export declare function signDigest(signer: ContextSigner, digest: string, at: Date): Promise<ContextSignature>;
+/** The first signature that is a trusted key's signature over exactly this digest, if any. */
+export declare function verifiedBy(keyring: ContextKeyring, digest: string, signatures?: readonly ContextSignature[]): Promise<ContextSignature | undefined>;

package/dist-cjs/context-hub/signing.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateContextKey = generateContextKey;
+exports.ed25519Signer = ed25519Signer;
+exports.ed25519Keyring = ed25519Keyring;
+exports.contextDigest = contextDigest;
+exports.signDigest = signDigest;
+exports.verifiedBy = verifiedBy;
+const version_js_1 = require("../prompts/version.js");
+const base64_js_1 = require("../utils/base64.js");
+const subtle = () => globalThis.crypto.subtle;
+const ED25519 = { name: 'Ed25519' };
+async function generateContextKey(keyId) {
+    const pair = await subtle().generateKey(ED25519, true, ['sign', 'verify']);
+    const publicKey = await subtle().exportKey('jwk', pair.publicKey);
+    const privateKey = await subtle().exportKey('jwk', pair.privateKey);
+    const id = keyId ?? (await keyIdOf(publicKey));
+    return { keyId: id, signer: await ed25519Signer(id, pair.privateKey), publicKey, privateKey };
+}
+async function ed25519Signer(keyId, privateKey) {
+    const key = isCryptoKey(privateKey)
+        ? privateKey
+        : await subtle().importKey('jwk', privateKey, ED25519, false, ['sign']);
+    return { keyId, sign: async (data) => new Uint8Array(await subtle().sign(ED25519, key, data)) };
+}
+async function ed25519Keyring(keys) {
+    const imported = new Map();
+    for (const [keyId, key] of Object.entries(keys)) {
+        imported.set(keyId, isCryptoKey(key) ? key : await subtle().importKey('jwk', key, ED25519, false, ['verify']));
+    }
+    return {
+        async verify(keyId, data, signature) {
+            const key = imported.get(keyId);
+            if (!key)
+                return false;
+            try {
+                return await subtle().verify(ED25519, key, signature, data);
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+async function contextDigest(content) {
+    const text = (0, version_js_1.canonicalJson)({ format: 'nexus-context-signature', formatVersion: 1, ...content });
+    const digest = await subtle().digest('SHA-256', new TextEncoder().encode(text));
+    return `sha256:${hexOf(new Uint8Array(digest))}`;
+}
+async function signDigest(signer, digest, at) {
+    const signature = await signer.sign(new TextEncoder().encode(digest));
+    return {
+        keyId: signer.keyId,
+        algorithm: 'Ed25519',
+        digest,
+        signature: toBase64Url(signature),
+        signedAt: at.toISOString(),
+    };
+}
+async function verifiedBy(keyring, digest, signatures = []) {
+    const data = new TextEncoder().encode(digest);
+    for (const signature of signatures) {
+        if (signature?.algorithm !== 'Ed25519' || signature.digest !== digest)
+            continue;
+        let bytes;
+        try {
+            bytes = fromBase64Url(signature.signature);
+        }
+        catch {
+            continue;
+        }
+        if (await keyring.verify(signature.keyId, data, bytes))
+            return signature;
+    }
+    return undefined;
+}
+async function keyIdOf(publicKey) {
+    const digest = await subtle().digest('SHA-256', new TextEncoder().encode(String(publicKey.x)));
+    return hexOf(new Uint8Array(digest).subarray(0, 8));
+}
+function hexOf(bytes) {
+    let hex = '';
+    for (const byte of bytes)
+        hex += byte.toString(16).padStart(2, '0');
+    return hex;
+}
+function isCryptoKey(value) {
+    return typeof value.algorithm === 'object' && Array.isArray(value.usages);
+}
+function toBase64Url(bytes) {
+    return (0, base64_js_1.encodeBase64)(bytes).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function fromBase64Url(text) {
+    const padded = text.replace(/-/g, '+').replace(/_/g, '/');
+    return (0, base64_js_1.decodeBase64)(padded + '='.repeat((4 - (padded.length % 4)) % 4));
+}

package/dist-cjs/doctor/index.d.ts

@@ -42,8 +42,10 @@ export interface DoctorDeployment {
     replicas: number;
     /**
      * The stores and shared state it uses, by any name: a checkpointer, the operation store, the
-     * server's state, tenant usage, a rate-limit store, a circuit store, a cache. Each is reported when
-     * it keeps its state in process memory, where each replica would see only its own.
+     * server's state, tenant usage, a rate-limit store, a circuit store, a cache, a tracer. Each is
+     * reported when it keeps its state in process memory, where each replica would see only its own,
+     * and when it lacks an opt-in setting a deployment needs: a Redis operation store without its
+     * dispatch index, or a tracer writing to a persistent store without incremental tracing.
      */
     stores?: Record<string, unknown>;
 }

package/dist-cjs/doctor/index.js

@@ -93,6 +93,7 @@ async function diagnose(options = {}) {
     await run('queue', 'Operation queue and leases', () => queueCheck(options.operations, now(), options.maxQueueAgeMs));
     await run('health', 'Provider health', () => healthCheck(options.ai));
     await run('topology', 'Settings that only work in one process', () => topologyCheck(options.deployment));
+    await run('settings', 'Opt-in settings a deployment needs', () => settingsCheck(options.deployment));
     const failures = checks.filter((check) => check.status === 'fail').length;
     const warnings = checks.filter((check) => check.status === 'warn').length;
     return { checks, ok: failures === 0, failures, warnings };
@@ -274,3 +275,31 @@ function topologyCheck(deployment) {
         hint: 'Use the Redis, Postgres, or SQLite adapter for each, or run one replica.',
     };
 }
+function settingsCheck(deployment) {
+    const stores = Object.entries(deployment?.stores ?? {});
+    if (stores.length === 0)
+        return { status: 'skip', detail: 'No stores described.' };
+    const findings = [];
+    const hints = new Set();
+    for (const [name, value] of stores) {
+        const kind = kindOf(value);
+        if (kind === 'RedisOperationStore' && value.indexed === false) {
+            findings.push(`${name} is a RedisOperationStore without index: true, so finding queued work reads every record and a long queue slows every claim`);
+            hints.add('Give the Redis operation store index: true once every worker sharing its prefix runs 2.2 or later, then call reindex() once.');
+        }
+        if (kind === 'Tracer') {
+            const tracer = value;
+            const store = kindOf(tracer.store);
+            if (tracer.incremental === false && store && store !== 'MemoryTraceStore') {
+                findings.push(`${name} writes to a ${store} without incremental, so a trace is written when its root finishes and a replica that dies mid-run loses it`);
+                hints.add('Create the Tracer with incremental: true, and close what a dead process left with closeAbandonedRuns().');
+            }
+        }
+    }
+    if (findings.length === 0)
+        return { status: 'ok', detail: 'No store lacks a setting a deployment needs.' };
+    return { status: 'warn', detail: `${findings.join('; ')}.`, hint: [...hints].join(' ') };
+}
+function kindOf(value) {
+    return value?.constructor?.name;
+}