@crvouga/atlas 1.20.0 → 1.22.0

package/dist/critics/src/registry.d.ts

@@ -0,0 +1,125 @@
+import { z } from 'zod/v4';
+import { type Critic } from './contract.js';
+/** The configuration of one critic. `type` chooses what it is. */
+export declare const CriticConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"uiclip">;
+    checkpoint: z.ZodObject<{
+        path: z.ZodString;
+        sha256: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$loose>, z.ZodObject<{
+    type: z.ZodLiteral<"llm">;
+    provider: z.ZodDefault<z.ZodEnum<{
+        "openai-compatible": "openai-compatible";
+        anthropic: "anthropic";
+        gemini: "gemini";
+    }>>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    model: z.ZodString;
+    rubric: z.ZodOptional<z.ZodString>;
+    rubricFile: z.ZodOptional<z.ZodString>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>, z.ZodObject<{
+    type: z.ZodLiteral<"module">;
+    module: z.ZodString;
+    export: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>], "type">;
+/** The configuration file: which server, and the critics by name. */
+export declare const CriticsConfigSchema: z.ZodObject<{
+    server: z.ZodOptional<z.ZodObject<{
+        url: z.ZodOptional<z.ZodString>;
+        project: z.ZodOptional<z.ZodString>;
+        token: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    spool: z.ZodOptional<z.ZodString>;
+    critics: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"uiclip">;
+        checkpoint: z.ZodObject<{
+            path: z.ZodString;
+            sha256: z.ZodString;
+            url: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"llm">;
+        provider: z.ZodDefault<z.ZodEnum<{
+            "openai-compatible": "openai-compatible";
+            anthropic: "anthropic";
+            gemini: "gemini";
+        }>>;
+        baseUrl: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodOptional<z.ZodString>;
+        model: z.ZodString;
+        rubric: z.ZodOptional<z.ZodString>;
+        rubricFile: z.ZodOptional<z.ZodString>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"module">;
+        module: z.ZodString;
+        export: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>], "type">>>;
+}, z.core.$loose>;
+/** The configuration file as read. */
+export type CriticsConfig = z.output<typeof CriticsConfigSchema>;
+/** The configuration of one critic. */
+export type CriticConfig = z.output<typeof CriticConfigSchema>;
+/** A configuration and where it came from; `file` is null when there is none, and every critic is then absent. */
+export type LoadedConfig = {
+    readonly config: CriticsConfig;
+    readonly file: string | null;
+    readonly directory: string;
+};
+/** The name of the configuration file a project commits. */
+export declare const CONFIG_FILE = "atlas.critics.json";
+/**
+ * Reads the critics configuration. With no `file`, `atlas.critics.json` in `cwd`, which may be absent (no critics are then
+ * configured). A file that was named and is missing, is not JSON, contains a literal credential, or has the wrong shape is an error that
+ * says where and never repeats a credential.
+ */
+export declare function loadCriticsConfig(cwd: string, file?: string): Promise<LoadedConfig>;
+/** What a critic's `inspect` found about one aspect: fine, a warning, or a problem with how to fix it. */
+export type Inspection = {
+    /** For example `model-file`, `credential`, `provider`, `module`. */
+    readonly aspect: string;
+    readonly status: 'ok' | 'warning' | 'problem';
+    readonly detail: string;
+    readonly fix?: string;
+};
+/** What `setup` did for a critic. */
+export type SetupReport = {
+    readonly ok: true;
+    readonly details: readonly string[];
+};
+/** A critic built from configuration, with what a command needs around it. */
+export type BuiltCritic = {
+    readonly name: string;
+    readonly type: CriticConfig['type'];
+    readonly critic: Critic;
+    /** The credentials this critic holds, for redaction. */
+    readonly secrets: readonly string[];
+    /** Finds what is wrong before a run, one finding per aspect. Never calls the model. */
+    inspect(): Promise<Inspection[]>;
+    /** Provisions what the critic needs (a verified checkpoint) or checks its credentials. */
+    setup(): Promise<SetupReport>;
+    /** Opens what a run needs (a model session) so a problem is found before any image is judged. */
+    ready(): Promise<void>;
+};
+/** What building a critic may use besides the file system: the environment, `fetch` and module loading. Tests pass fakes. */
+export type RegistryIo = {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly fetch?: typeof fetch;
+    readonly importModule?: (name: string) => Promise<unknown>;
+};
+/**
+ * Builds the critic `name` of a configuration. Throws, naming the problem, for a name that is not configured, a credential
+ * reference that cannot be resolved, or a module that cannot be loaded.
+ *
+ * @param loaded the configuration and its directory.
+ * @param name the critic's name in the configuration.
+ */
+export declare function buildCritic(loaded: LoadedConfig, name: string, io?: RegistryIo): Promise<BuiltCritic>;

package/dist/critics/src/registry.js

@@ -0,0 +1,203 @@
+/**
+ * @module Configured critics
+ *
+ * Reads the critics a project configured (`atlas.critics.json`) and builds them: the built-in UIClip critic, the LLM
+ * critic over a provider, or a critic of the project's own (a module whose default export is a `defineCritic` result). The
+ * configuration names a credential by reference (`env:NAME`, `file:PATH`) and never contains one, so it can be committed;
+ * a configuration with a literal credential is refused before anything is built. Credentials are resolved when a critic is
+ * built for a run and never stored.
+ *
+ * Every built critic can say what is wrong with it (`inspect`) so `atlas critic doctor` reports each problem on its own
+ * with how to fix it, and how to provision itself (`setup`).
+ *
+ * @see docs/critics.md#configuring-critics
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { z } from 'zod/v4';
+import { defineCritic } from './contract.js';
+import { assertNoLiteralCredentials, createRedactor, resolveCredential } from './credentials.js';
+import { ANTHROPIC_API_VERSION, anthropicProvider, createLlmCritic, geminiProvider, openAiCompatibleProvider } from './llm.js';
+import { createUiclipCritic, MissingDependencyError, setupUiclip, verifyCheckpoint } from './uiclip.js';
+const CheckpointConfig = z.object({
+    path: z.string().min(1).describe('Where the checkpoint file lives, relative to the configuration file'),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/, 'the SHA-256 the checkpoint must have: 64 lowercase hex digits').describe('The pinned SHA-256 of the checkpoint'),
+    url: z.string().url().optional().describe('Where `atlas critic setup` may download it from (https). Inference never downloads')
+});
+/** The configuration of one critic. `type` chooses what it is. */
+export const CriticConfigSchema = z.discriminatedUnion('type', [
+    z.looseObject({ type: z.literal('uiclip'), checkpoint: CheckpointConfig }),
+    z.looseObject({
+        type: z.literal('llm'),
+        provider: z.enum(['openai-compatible', 'anthropic', 'gemini']).default('openai-compatible').describe('`openai-compatible`: any server that speaks chat completions (needs baseUrl). `anthropic`: the Messages API. `gemini`: the Gemini API. All over plain fetch, with no SDK'),
+        baseUrl: z.string().url().optional().describe('For example https://llm.example.com/v1; required for `openai-compatible`. `anthropic` and `gemini` default to their own hosts. Images are sent to this host'),
+        apiKey: z.string().optional().describe('A reference to the key: `env:NAME` or `file:PATH`. Never the key. Required for `anthropic` and `gemini`'),
+        model: z.string().min(1),
+        rubric: z.string().optional().describe('What to look for, as text; recorded as a hash'),
+        rubricFile: z.string().optional().describe('Or a file holding the rubric, relative to the configuration file'),
+        temperature: z.number().min(0).max(2).optional(),
+        maxTokens: z.number().int().positive().optional(),
+        version: z.string().min(1).optional().describe('Change it when the rubric or prompt changes meaning, so critiques are made again')
+    }),
+    z.looseObject({ type: z.literal('module'), module: z.string().min(1).describe('A TypeScript or JavaScript file, relative to the configuration file, whose default export is a critic (`defineCritic`)'), export: z.string().optional().describe('The export to use instead of the default') })
+]);
+/** The configuration file: which server, and the critics by name. */
+export const CriticsConfigSchema = z.looseObject({
+    server: z.looseObject({
+        url: z.string().optional().describe('The Atlas server'),
+        project: z.string().optional(),
+        token: z.string().optional().describe('A reference to the token: `env:NAME` or `file:PATH`. Never the token')
+    }).optional(),
+    spool: z.string().optional().describe('Where critiques that could not be sent are kept, relative to the configuration file. Default .atlas/critic-spool'),
+    critics: z.record(z.string().regex(/^[a-z0-9][a-z0-9.-]*$/, 'a critic name is lowercase letters, digits, "-" and "."'), CriticConfigSchema).default({})
+});
+/** The name of the configuration file a project commits. */
+export const CONFIG_FILE = 'atlas.critics.json';
+/**
+ * Reads the critics configuration. With no `file`, `atlas.critics.json` in `cwd`, which may be absent (no critics are then
+ * configured). A file that was named and is missing, is not JSON, contains a literal credential, or has the wrong shape is an error that
+ * says where and never repeats a credential.
+ */
+export async function loadCriticsConfig(cwd, file) {
+    const target = path.resolve(cwd, file ?? CONFIG_FILE);
+    let text;
+    try {
+        text = await readFile(target, 'utf8');
+    }
+    catch {
+        if (file)
+            throw new Error(`The critics configuration ${file} cannot be read`);
+        return { config: CriticsConfigSchema.parse({}), file: null, directory: cwd };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${path.relative(cwd, target) || target} is not JSON`);
+    }
+    assertNoLiteralCredentials(raw);
+    const parsed = CriticsConfigSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new Error(`${path.relative(cwd, target) || target} is not a critics configuration: ${parsed.error.issues.slice(0, 3).map(issue => `${issue.path.join('.') || '(root)'}: ${issue.message}`).join('; ')}`);
+    return { config: parsed.data, file: target, directory: path.dirname(target) };
+}
+/**
+ * Builds the critic `name` of a configuration. Throws, naming the problem, for a name that is not configured, a credential
+ * reference that cannot be resolved, or a module that cannot be loaded.
+ *
+ * @param loaded the configuration and its directory.
+ * @param name the critic's name in the configuration.
+ */
+export async function buildCritic(loaded, name, io = {}) {
+    const entry = loaded.config.critics[name];
+    if (!entry)
+        throw new Error(`No critic named "${name}" is configured${loaded.file ? ` in ${path.basename(loaded.file)}` : ` (there is no ${CONFIG_FILE})`}. Configured: ${Object.keys(loaded.config.critics).join(', ') || 'none'}`);
+    const resolve = (relative) => path.resolve(loaded.directory, relative);
+    const env = io.env ?? process.env;
+    if (entry.type === 'uiclip') {
+        const checkpoint = { path: resolve(entry.checkpoint.path), sha256: entry.checkpoint.sha256, ...(entry.checkpoint.url ? { url: entry.checkpoint.url } : {}) };
+        const critic = createUiclipCritic({ checkpoint, name, ...(io.importModule ? { modules: { importModule: io.importModule } } : {}) });
+        const load = io.importModule ?? ((module) => import(module));
+        return {
+            name, type: 'uiclip', critic, secrets: [],
+            async inspect() {
+                const found = [];
+                try {
+                    await verifyCheckpoint(checkpoint);
+                    found.push({ aspect: 'model-file', status: 'ok', detail: `The checkpoint ${entry.checkpoint.path} matches its pinned checksum` });
+                }
+                catch (error) {
+                    found.push({ aspect: 'model-file', status: 'problem', detail: error instanceof Error ? error.message : String(error), fix: `Run \`atlas critic setup ${name}\`, or put the checkpoint at ${entry.checkpoint.path}` });
+                }
+                for (const dependency of ['onnxruntime-node', 'sharp']) {
+                    try {
+                        await load(dependency);
+                        found.push({ aspect: dependency, status: 'ok', detail: `${dependency} is installed` });
+                    }
+                    catch {
+                        found.push({ aspect: dependency, status: 'problem', detail: new MissingDependencyError(dependency, 'The UIClip critic').message, fix: `bun add ${dependency}` });
+                    }
+                }
+                return found;
+            },
+            async setup() {
+                const result = await setupUiclip(checkpoint, io.fetch ? { fetch: io.fetch } : {});
+                return { ok: true, details: [`${result.downloaded ? 'Downloaded' : 'Found'} the checkpoint at ${entry.checkpoint.path}`, `Verified its SHA-256 ${result.sha256}`, 'Inference never downloads anything'] };
+            },
+            ready: () => critic.ready()
+        };
+    }
+    if (entry.type === 'llm') {
+        const key = entry.apiKey ? await resolveCredential(entry.apiKey, { env }) : undefined;
+        const secrets = key ? [key] : [];
+        const redact = createRedactor(secrets);
+        const rubric = entry.rubricFile ? await readFile(resolve(entry.rubricFile), 'utf8').catch(() => { throw new Error(`The rubric file ${entry.rubricFile} cannot be read`); }) : entry.rubric;
+        const transport = io.fetch ? { fetch: io.fetch } : {};
+        let provider;
+        if (entry.provider === 'anthropic' || entry.provider === 'gemini') {
+            if (!key)
+                throw new Error(`The critic "${name}" uses the ${entry.provider} provider, which needs an apiKey: set it to a reference such as env:SOME_API_KEY`);
+            provider = (entry.provider === 'anthropic' ? anthropicProvider : geminiProvider)({ apiKey: key, ...(entry.baseUrl ? { baseUrl: entry.baseUrl } : {}), ...transport });
+        }
+        else {
+            if (!entry.baseUrl)
+                throw new Error(`The critic "${name}" uses the openai-compatible provider, which needs a baseUrl such as https://llm.example.com/v1`);
+            provider = openAiCompatibleProvider({ baseUrl: entry.baseUrl, ...(key ? { apiKey: key } : {}), ...transport });
+        }
+        const critic = createLlmCritic({ provider, model: entry.model, name, ...(rubric ? { rubric } : {}), ...(entry.temperature === undefined ? {} : { temperature: entry.temperature }), ...(entry.maxTokens === undefined ? {} : { maxTokens: entry.maxTokens }), ...(entry.version ? { version: entry.version } : {}) });
+        const doFetch = io.fetch ?? fetch;
+        return {
+            name, type: 'llm', critic, secrets,
+            async inspect() {
+                const found = [];
+                found.push(entry.apiKey ? { aspect: 'credential', status: 'ok', detail: `${entry.apiKey} is set` } : { aspect: 'credential', status: 'warning', detail: 'No apiKey is configured: only a server that needs none will answer', fix: 'Set apiKey to a reference such as env:SOME_API_KEY' });
+                // A cheap authenticated listing per provider: it checks the host answers and the credential is accepted, and never sends an image.
+                const host = `https://${provider.sendsImagesTo}`;
+                const probe = entry.provider === 'anthropic' ? { url: `${entry.baseUrl?.replace(/\/+$/, '') ?? host}/v1/models`, headers: { 'x-api-key': key, 'anthropic-version': ANTHROPIC_API_VERSION } }
+                    : entry.provider === 'gemini' ? { url: `${entry.baseUrl?.replace(/\/+$/, '') ?? host}/v1beta/models`, headers: { 'x-goog-api-key': key } }
+                        : { url: `${entry.baseUrl.replace(/\/+$/, '')}/models`, headers: key ? { authorization: `Bearer ${key}` } : {} };
+                try {
+                    const response = await doFetch(probe.url, { headers: probe.headers, signal: AbortSignal.timeout(5_000) });
+                    await response.body?.cancel();
+                    if (response.status === 401 || response.status === 403)
+                        found.push({ aspect: 'provider', status: 'problem', detail: `${provider.sendsImagesTo} rejected the credential (${response.status})`, fix: `Check the key that ${entry.apiKey ?? 'apiKey'} names` });
+                    else if (response.status >= 500)
+                        found.push({ aspect: 'provider', status: 'problem', detail: `${provider.sendsImagesTo} answered ${response.status}`, fix: 'Try again later, or check the provider status' });
+                    else
+                        found.push({ aspect: 'provider', status: 'ok', detail: `${provider.sendsImagesTo} is reachable` });
+                }
+                catch (error) {
+                    found.push({ aspect: 'provider', status: 'problem', detail: redact(`${provider.sendsImagesTo} is not reachable (${error instanceof Error ? error.name : 'error'})`), fix: `Check ${entry.baseUrl ? `baseUrl (${entry.baseUrl})` : 'the network'}` });
+                }
+                return found;
+            },
+            async setup() {
+                return { ok: true, details: [entry.apiKey ? `The credential ${entry.apiKey} is set` : 'No credential is configured', `Images would be sent to ${provider.sendsImagesTo}`] };
+            },
+            async ready() { }
+        };
+    }
+    const file = resolve(entry.module);
+    const load = io.importModule ? () => io.importModule(pathToFileURL(file).href) : () => import(pathToFileURL(file).href);
+    let module;
+    try {
+        module = await load();
+    }
+    catch (error) {
+        throw new Error(`The module ${entry.module} of critic "${name}" cannot be loaded: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`);
+    }
+    const exported = module[entry.export ?? 'default'];
+    if (!exported || typeof exported.evaluate !== 'function' || typeof exported.describe !== 'function')
+        throw new Error(`The module ${entry.module} has no critic as its ${entry.export ?? 'default'} export: use defineCritic`);
+    if (exported.name !== name)
+        throw new Error(`The module ${entry.module} exports a critic named "${exported.name}" but it is configured as "${name}": the names must agree, because the name is the producer of its layers`);
+    const critic = defineCritic(exported);
+    return {
+        name, type: 'module', critic, secrets: [],
+        async inspect() { return [{ aspect: 'module', status: 'ok', detail: `${entry.module} exports the critic "${critic.name}"` }]; },
+        async setup() { await critic.setup?.(); return { ok: true, details: [critic.setup ? `Ran the setup of ${critic.name}` : `${critic.name} needs no setup`] }; },
+        async ready() { }
+    };
+}

package/dist/critics/src/spool.d.ts

@@ -0,0 +1,32 @@
+import type { ObjectStore } from '../../reports/src/object-store.js';
+/** A store that spools what it cannot send. */
+export type SpoolingStore = ObjectStore & {
+    /** How many objects this store has written to the spool since it was made. */
+    readonly spooled: () => number;
+};
+/** How many objects wait in a spool directory. */
+export declare function pendingInSpool(dir: string): Promise<number>;
+/**
+ * Wraps `inner` so that a `put` that cannot reach the server is written to `dir` instead of throwing. After the first such
+ * failure the rest of the run goes straight to the spool (it does not wait through every retry again), and `head` answers
+ * "not there". Reads are not spooled. A refusal from the server still throws.
+ *
+ * @param inner the store a run publishes to.
+ * @param dir the spool directory; created when first needed.
+ */
+export declare function spoolingStore(inner: ObjectStore, dir: string): SpoolingStore;
+/** What {@link flushSpool} did. */
+export type SpoolFlush = {
+    /** Objects sent and removed from the spool. */
+    readonly sent: number;
+    /** Objects still waiting (the server is still away, or refused one). */
+    readonly remaining: number;
+    /** Why sending stopped, with no credential in it; absent when everything was sent. */
+    readonly error?: string;
+};
+/**
+ * Sends what an earlier run could not, in the order it was written, and removes each object once the server has it. Stops at the
+ * first failure and leaves the rest, so the order a layer needs (its files, then the layer, then its catalog entry) is kept. A
+ * spool that is empty or missing is not an error.
+ */
+export declare function flushSpool(inner: ObjectStore, dir: string): Promise<SpoolFlush>;

package/dist/critics/src/spool.js

@@ -0,0 +1,129 @@
+/**
+ * @module Spooling unsent critiques
+ *
+ * A critic that has finished judging must not lose its work because the server went away. `spoolingStore` wraps the store
+ * a run publishes to: when the server cannot be reached (a network error, a 5xx, a rate limit that did not clear) the
+ * objects of the layer are written to a local directory instead of failing, and the next invocation sends them with
+ * `flushSpool`, byte for byte what was written, in the order they were written. A layer is content-addressed and the store
+ * protocol is idempotent, so sending one that did arrive is harmless and nothing is duplicated. A refusal (401, 403, 409,
+ * 413, 422) is not spooled: it will not pass by waiting, and the caller must hear it.
+ *
+ * What is spooled is only what would have been published (a layer, its files and its catalog entry): never a credential.
+ *
+ * @see docs/critics.md#when-the-server-goes-away
+ */
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { AtlasHttpError } from '../../reports/src/http-store.js';
+import { sha256Hex } from '../../reports/src/sigv4.js';
+/** Whether an error says the server is away or overloaded, as opposed to saying no. */
+function isAbsence(error) {
+    return error instanceof AtlasHttpError ? error.retryable || error.status === null : true;
+}
+async function entries(dir) {
+    try {
+        return (await readdir(dir)).filter(name => name.endsWith('.json')).sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** How many objects wait in a spool directory. */
+export async function pendingInSpool(dir) {
+    return (await entries(dir)).length;
+}
+/**
+ * Wraps `inner` so that a `put` that cannot reach the server is written to `dir` instead of throwing. After the first such
+ * failure the rest of the run goes straight to the spool (it does not wait through every retry again), and `head` answers
+ * "not there". Reads are not spooled. A refusal from the server still throws.
+ *
+ * @param inner the store a run publishes to.
+ * @param dir the spool directory; created when first needed.
+ */
+export function spoolingStore(inner, dir) {
+    let away = false;
+    let count = 0;
+    let sequence;
+    const next = async () => {
+        sequence ??= entries(dir).then(names => (names.length ? Number.parseInt(names[names.length - 1].split('-')[0], 10) + 1 : 1));
+        const value = await sequence;
+        sequence = Promise.resolve(value + 1);
+        return value;
+    };
+    async function spool(key, bytes, contentType) {
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        const id = (await sha256Hex(key)).slice(0, 16);
+        // The same object spooled twice is one file: nothing is duplicated.
+        if ((await entries(dir)).some(name => name.endsWith(`-${id}.json`)))
+            return;
+        const name = `${String(await next()).padStart(8, '0')}-${id}.json`;
+        const body = { key, contentType, base64: Buffer.from(bytes).toString('base64') };
+        await writeFile(path.join(dir, `${name}.tmp`), JSON.stringify(body), { mode: 0o600 });
+        await rename(path.join(dir, `${name}.tmp`), path.join(dir, name));
+        count += 1;
+    }
+    const store = {
+        spooled: () => count,
+        get: key => inner.get(key),
+        async put(key, bytes, contentType) {
+            if (!away) {
+                try {
+                    await inner.put(key, bytes, contentType);
+                    return;
+                }
+                catch (error) {
+                    if (!isAbsence(error))
+                        throw error;
+                    away = true;
+                }
+            }
+            await spool(key, bytes, contentType);
+        },
+        async head(key) {
+            if (away)
+                return false;
+            try {
+                return await inner.head(key);
+            }
+            catch (error) {
+                if (!isAbsence(error))
+                    throw error;
+                away = true;
+                return false;
+            }
+        },
+        delete: key => inner.delete(key),
+        deleteMany: keys => inner.deleteMany(keys),
+        getUri: key => inner.getUri(key),
+        listKeys: prefix => inner.listKeys(prefix),
+        withPrefix: prefix => inner.withPrefix(prefix)
+    };
+    return store;
+}
+/**
+ * Sends what an earlier run could not, in the order it was written, and removes each object once the server has it. Stops at the
+ * first failure and leaves the rest, so the order a layer needs (its files, then the layer, then its catalog entry) is kept. A
+ * spool that is empty or missing is not an error.
+ */
+export async function flushSpool(inner, dir) {
+    const names = await entries(dir);
+    let sent = 0;
+    for (const name of names) {
+        let item;
+        try {
+            item = JSON.parse(await readFile(path.join(dir, name), 'utf8'));
+        }
+        catch {
+            return { sent, remaining: names.length - sent, error: `The spooled file ${name} cannot be read; it was left in place` };
+        }
+        try {
+            await inner.put(item.key, Uint8Array.from(Buffer.from(item.base64, 'base64')), item.contentType);
+        }
+        catch (error) {
+            return { sent, remaining: names.length - sent, error: error instanceof Error ? error.message : String(error) };
+        }
+        await rm(path.join(dir, name), { force: true });
+        sent += 1;
+    }
+    return { sent, remaining: 0 };
+}

package/dist/critics/src/uiclip.d.ts

@@ -0,0 +1,82 @@
+import { type Critic } from './contract.js';
+/** The version of this adapter's own logic, recorded in every critique. The checkpoint is part of the identity too (through `model.id`). */
+export declare const UICLIP_VERSION = "1.0.0";
+/** A pinned checkpoint: where it lives on disk, the SHA-256 it must have, and, optionally, where `setupUiclip` may fetch it from. */
+export type UiclipCheckpoint = {
+    /** The file on disk. */
+    readonly path: string;
+    /** Lowercase hex SHA-256 the file must have. Required: an unpinned checkpoint is refused. */
+    readonly sha256: string;
+    /** Where `setupUiclip` may download it from when the file is missing. Never used by inference. */
+    readonly url?: string;
+};
+/** Something that scores one image: the model behind the critic. */
+export type UiclipRuntime = {
+    /** The score for the image bytes; higher is better. Must be finite and deterministic for the same bytes. */
+    score(image: Uint8Array, signal: AbortSignal): Promise<number>;
+    /** Frees the session. */
+    close?(): Promise<void>;
+};
+/** Thrown when an optional dependency a runtime needs is not installed. The message names it and says how to install it. */
+export declare class MissingDependencyError extends Error {
+    readonly dependency: string;
+    /** @param dependency the package that is missing. */
+    constructor(dependency: string, purpose: string);
+}
+/**
+ * Checks a file against a pinned SHA-256. Returns the hash it has. Throws when the file is missing or its hash differs, naming
+ * both hashes, so a corrupted or swapped model is an error and never silently used.
+ */
+export declare function verifyCheckpoint(checkpoint: Pick<UiclipCheckpoint, 'path' | 'sha256'>): Promise<string>;
+/** What {@link setupUiclip} did. */
+export type UiclipSetup = {
+    /** The file that was verified. */
+    readonly path: string;
+    /** Its SHA-256, equal to the pin. */
+    readonly sha256: string;
+    /** True when it was fetched now; false when it was already there. */
+    readonly downloaded: boolean;
+};
+/**
+ * Provisions the checkpoint: uses the file when it is there, else downloads it from `checkpoint.url` (to a temporary file, hashing as
+ * it arrives), and in both cases verifies the pinned SHA-256. A download whose hash differs is deleted and is an error; an
+ * existing file whose hash differs is an error and is left alone. This is the only place anything is downloaded.
+ *
+ * @param checkpoint the pinned checkpoint.
+ * @param options.fetch for tests; default `fetch`.
+ * @param options.signal cancels the download.
+ */
+export declare function setupUiclip(checkpoint: UiclipCheckpoint, options?: {
+    readonly fetch?: typeof fetch;
+    readonly signal?: AbortSignal;
+}): Promise<UiclipSetup>;
+/** The modules a runtime imports, so a test can replace them. */
+export type UiclipModules = {
+    readonly importModule?: (name: string) => Promise<unknown>;
+};
+/**
+ * Opens an ONNX Runtime session on a verified checkpoint and scores images with it: the image is resized to 224 by 224 and
+ * normalised as CLIP does, and the first output's first value is the score. The checkpoint's hash is verified first and a
+ * mismatch is an error. Needs the optional `onnxruntime-node` and `sharp`; the error names the missing one. Nothing is
+ * downloaded. The graph and score head are those of the checkpoint you pinned; this has not been validated against any particular
+ * checkpoint, so measure it on your own examples (`calibrate`) before reading its scores.
+ */
+export declare function loadOnnxRuntime(checkpoint: Pick<UiclipCheckpoint, 'path' | 'sha256'>, modules?: UiclipModules): Promise<UiclipRuntime>;
+/**
+ * The UIClip critic: judges each image with a runtime and reports the score and nothing else (a score is a valid critique; it
+ * has no findings). Deterministic for a deterministic runtime. Its identity includes the checkpoint hash, so a different
+ * checkpoint is judged again. The runtime is created once, on the first image.
+ *
+ * @param options.checkpoint the pinned checkpoint. Its hash is the model id.
+ * @param options.runtime a runtime, or a function that makes one. Default: {@link loadOnnxRuntime} on the checkpoint.
+ * @example
+ * const critic = createUiclipCritic({ checkpoint: { path: '.atlas/uiclip.onnx', sha256 }, runtime: { score: async () => 0.5 } });
+ */
+export declare function createUiclipCritic(options: {
+    readonly checkpoint: Pick<UiclipCheckpoint, 'path' | 'sha256'>;
+    readonly runtime?: UiclipRuntime | (() => Promise<UiclipRuntime>);
+    readonly name?: string;
+    readonly modules?: UiclipModules;
+}): Critic & {
+    ready(): Promise<void>;
+};