zk-credits 0.2.0 → 0.2.2

package/dist/responses-bridge.js

@@ -0,0 +1,328 @@
+import { randomUUID } from 'node:crypto';
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function hasOnlyKeys(value, allowed) {
+    return Object.keys(value).every((key) => allowed.includes(key));
+}
+function textContent(value) {
+    if (typeof value === 'string')
+        return value;
+    if (!Array.isArray(value))
+        return undefined;
+    const parts = [];
+    for (const part of value) {
+        if (!isRecord(part) || !hasOnlyKeys(part, ['type', 'text'])
+            || (part.type !== 'input_text' && part.type !== 'output_text')
+            || typeof part.text !== 'string')
+            return undefined;
+        parts.push({ type: 'text', text: part.text });
+    }
+    return parts.length === 1 ? parts[0].text : parts;
+}
+function responseInputMessages(input) {
+    if (typeof input === 'string')
+        return [{ role: 'user', content: input }];
+    if (!Array.isArray(input))
+        return undefined;
+    const messages = [];
+    for (const item of input) {
+        if (!isRecord(item) || typeof item.type !== 'string')
+            return undefined;
+        if (item.type === 'message') {
+            if (!hasOnlyKeys(item, ['type', 'id', 'role', 'content'])
+                || (item.id !== undefined && typeof item.id !== 'string')
+                || !['system', 'developer', 'user', 'assistant'].includes(String(item.role)))
+                return undefined;
+            const content = textContent(item.content);
+            if (content === undefined)
+                return undefined;
+            messages.push({ role: item.role, content });
+            continue;
+        }
+        if (item.type === 'function_call') {
+            if (!hasOnlyKeys(item, ['type', 'id', 'status', 'call_id', 'name', 'arguments'])
+                || typeof item.call_id !== 'string' || typeof item.name !== 'string'
+                || typeof item.arguments !== 'string'
+                || (item.id !== undefined && typeof item.id !== 'string')
+                || (item.status !== undefined && typeof item.status !== 'string'))
+                return undefined;
+            messages.push({
+                role: 'assistant',
+                content: null,
+                tool_calls: [{ id: item.call_id, type: 'function', function: { name: item.name, arguments: item.arguments } }],
+            });
+            continue;
+        }
+        if (item.type === 'function_call_output') {
+            if (!hasOnlyKeys(item, ['type', 'id', 'status', 'call_id', 'output'])
+                || typeof item.call_id !== 'string' || typeof item.output !== 'string'
+                || (item.id !== undefined && typeof item.id !== 'string')
+                || (item.status !== undefined && typeof item.status !== 'string'))
+                return undefined;
+            messages.push({ role: 'tool', tool_call_id: item.call_id, content: item.output });
+            continue;
+        }
+        return undefined;
+    }
+    return messages;
+}
+function responseTools(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const tools = [];
+    for (const tool of value) {
+        if (!isRecord(tool) || typeof tool.type !== 'string')
+            return undefined;
+        if (tool.type === 'function') {
+            if (!hasOnlyKeys(tool, ['type', 'name', 'description', 'parameters', 'strict'])
+                || typeof tool.name !== 'string' || tool.name.length === 0
+                || (tool.description !== undefined && typeof tool.description !== 'string')
+                || (tool.parameters !== undefined && !isRecord(tool.parameters))
+                || (tool.strict !== undefined && typeof tool.strict !== 'boolean'))
+                return undefined;
+            const definition = { name: tool.name };
+            if (tool.description !== undefined)
+                definition.description = tool.description;
+            if (tool.parameters !== undefined)
+                definition.parameters = tool.parameters;
+            if (tool.strict !== undefined)
+                definition.strict = tool.strict;
+            tools.push({ type: 'function', function: definition });
+            continue;
+        }
+        // Codex includes these tool declarations in each Responses request. The
+        // fixed service class has no web-search executor and accepts only direct
+        // function tools, so validate their known shape and drop them.
+        if (tool.type === 'web_search') {
+            if (!hasOnlyKeys(tool, ['type', 'external_web_access'])
+                || (tool.external_web_access !== undefined && typeof tool.external_web_access !== 'boolean'))
+                return undefined;
+            continue;
+        }
+        if (tool.type === 'namespace') {
+            if (!hasOnlyKeys(tool, ['type', 'name', 'description', 'tools'])
+                || typeof tool.name !== 'string'
+                || (tool.description !== undefined && typeof tool.description !== 'string')
+                || !Array.isArray(tool.tools)
+                || tool.tools.some((nested) => !isRecord(nested) || nested.type !== 'function' || typeof nested.name !== 'string'))
+                return undefined;
+            continue;
+        }
+        return undefined;
+    }
+    return tools;
+}
+function translatedToolChoice(value) {
+    if (value === 'none' || value === 'auto' || value === 'required')
+        return value;
+    if (!isRecord(value) || value.type !== 'function' || !hasOnlyKeys(value, ['type', 'name'])
+        || typeof value.name !== 'string')
+        return undefined;
+    return { type: 'function', function: { name: value.name } };
+}
+/** Converts the small Responses surface emitted by Codex into the fixed Chat Completions request. */
+export function translateResponsesRequest(body) {
+    if (!isRecord(body))
+        return { ok: false, error: 'invalid_request_body' };
+    const allowed = [
+        'model', 'instructions', 'input', 'stream', 'tools', 'tool_choice', 'max_output_tokens',
+        'parallel_tool_calls', 'store', 'client_metadata', 'prompt_cache_key', 'include', 'reasoning',
+        'temperature', 'top_p', 'stop', 'seed', 'presence_penalty', 'frequency_penalty', 'logit_bias',
+    ];
+    if (!hasOnlyKeys(body, allowed))
+        return { ok: false, error: 'unsupported_request_field' };
+    if (typeof body.model !== 'string' || body.model.length === 0)
+        return { ok: false, error: 'model_required' };
+    if (body.stream !== true)
+        return { ok: false, error: 'streaming_required' };
+    if (body.store !== undefined && body.store !== false)
+        return { ok: false, error: 'stored_responses_unsupported' };
+    if (body.instructions !== undefined && typeof body.instructions !== 'string')
+        return { ok: false, error: 'invalid_instructions' };
+    if (body.prompt_cache_key !== undefined && typeof body.prompt_cache_key !== 'string')
+        return { ok: false, error: 'invalid_prompt_cache_key' };
+    if (body.client_metadata !== undefined
+        && (!isRecord(body.client_metadata) || Object.values(body.client_metadata).some((value) => typeof value !== 'string'))) {
+        return { ok: false, error: 'invalid_client_metadata' };
+    }
+    if (body.include !== undefined
+        && (!Array.isArray(body.include) || body.include.some((value) => value !== 'reasoning.encrypted_content'))) {
+        return { ok: false, error: 'unsupported_include' };
+    }
+    if (body.reasoning !== undefined
+        && (!isRecord(body.reasoning) || !hasOnlyKeys(body.reasoning, ['summary'])
+            || (body.reasoning.summary !== undefined && !['auto', 'concise', 'detailed'].includes(String(body.reasoning.summary))))) {
+        return { ok: false, error: 'unsupported_reasoning_controls' };
+    }
+    if (body.parallel_tool_calls !== undefined && typeof body.parallel_tool_calls !== 'boolean') {
+        return { ok: false, error: 'invalid_parallel_tool_calls' };
+    }
+    const messages = [];
+    if (body.instructions !== undefined)
+        messages.push({ role: 'developer', content: body.instructions });
+    const inputMessages = responseInputMessages(body.input);
+    if (!inputMessages)
+        return { ok: false, error: 'unsupported_input_item' };
+    messages.push(...inputMessages);
+    // The incoming stream:true is a Codex wire contract. The gateway service
+    // class fixes stream=false in its normalized provider request.
+    const chatRequest = { model: body.model, messages };
+    if (body.tools !== undefined) {
+        const tools = responseTools(body.tools);
+        if (!tools)
+            return { ok: false, error: 'unsupported_tool' };
+        if (tools.length)
+            chatRequest.tools = tools;
+    }
+    if (body.tool_choice !== undefined) {
+        const toolChoice = translatedToolChoice(body.tool_choice);
+        if (toolChoice === undefined)
+            return { ok: false, error: 'invalid_tool_choice' };
+        chatRequest.tool_choice = toolChoice;
+    }
+    if (body.max_output_tokens !== undefined) {
+        if (!Number.isInteger(body.max_output_tokens) || body.max_output_tokens <= 0) {
+            return { ok: false, error: 'invalid_max_output_tokens' };
+        }
+        chatRequest.max_completion_tokens = body.max_output_tokens;
+    }
+    if (body.parallel_tool_calls !== undefined)
+        chatRequest.parallel_tool_calls = body.parallel_tool_calls;
+    for (const key of ['temperature', 'top_p', 'stop', 'seed', 'presence_penalty', 'frequency_penalty', 'logit_bias']) {
+        if (body[key] !== undefined)
+            chatRequest[key] = body[key];
+    }
+    return { ok: true, chatRequest, responseModel: body.model };
+}
+function usageFor(chat) {
+    if (!isRecord(chat.usage))
+        return null;
+    const promptTokens = chat.usage.prompt_tokens;
+    const completionTokens = chat.usage.completion_tokens;
+    const totalTokens = chat.usage.total_tokens;
+    if (![promptTokens, completionTokens, totalTokens].every((value) => Number.isInteger(value) && value >= 0))
+        return null;
+    return {
+        input_tokens: promptTokens,
+        output_tokens: completionTokens,
+        total_tokens: totalTokens,
+    };
+}
+/** Builds the Responses SSE event sequence from one committed Chat Completions result. */
+export function responsesEventStream(chatValue, model) {
+    if (!isRecord(chatValue) || !Array.isArray(chatValue.choices) || !isRecord(chatValue.choices[0])) {
+        throw new Error('Gateway returned an invalid chat completion');
+    }
+    const choice = chatValue.choices[0];
+    if (!isRecord(choice.message))
+        throw new Error('Gateway returned an invalid chat message');
+    const message = choice.message;
+    const responseSuffix = randomUUID().replaceAll('-', '');
+    const responseId = `resp_${responseSuffix}`;
+    const events = [];
+    let sequence = 0;
+    const add = (event, data) => {
+        events.push({ event, data: { ...data, sequence_number: sequence++ } });
+    };
+    const createdAt = Number.isInteger(chatValue.created) ? chatValue.created : Math.floor(Date.now() / 1000);
+    const usage = usageFor(chatValue);
+    const base = {
+        id: responseId,
+        object: 'response',
+        created_at: createdAt,
+        status: 'in_progress',
+        completed_at: null,
+        error: null,
+        incomplete_details: null,
+        model,
+        output: [],
+        parallel_tool_calls: true,
+        metadata: {},
+        usage: null,
+    };
+    add('response.created', { type: 'response.created', response: base });
+    add('response.in_progress', { type: 'response.in_progress', response: base });
+    const output = [];
+    const text = message.content;
+    const refusal = message.refusal;
+    if (text !== null && text !== undefined && typeof text !== 'string') {
+        throw new Error('Gateway returned an unsupported chat content value');
+    }
+    if (refusal !== undefined && typeof refusal !== 'string')
+        throw new Error('Gateway returned an invalid refusal value');
+    if (typeof text === 'string' || typeof refusal === 'string') {
+        const itemId = `msg_${randomUUID().replaceAll('-', '')}`;
+        const isRefusal = typeof refusal === 'string';
+        const part = isRefusal
+            ? { type: 'refusal', refusal }
+            : { type: 'output_text', text: text ?? '', annotations: [] };
+        const item = { id: itemId, type: 'message', status: 'completed', role: 'assistant', content: [part] };
+        add('response.output_item.added', {
+            type: 'response.output_item.added', output_index: output.length,
+            item: { id: itemId, type: 'message', status: 'in_progress', role: 'assistant', content: [] },
+        });
+        add('response.content_part.added', {
+            type: 'response.content_part.added', output_index: output.length, content_index: 0,
+            part: isRefusal ? { type: 'refusal', refusal: '' } : { type: 'output_text', text: '', annotations: [] },
+        });
+        if (isRefusal) {
+            add('response.refusal.delta', { type: 'response.refusal.delta', item_id: itemId, output_index: output.length, content_index: 0, delta: refusal });
+            add('response.refusal.done', { type: 'response.refusal.done', item_id: itemId, output_index: output.length, content_index: 0, refusal });
+        }
+        else {
+            add('response.output_text.delta', { type: 'response.output_text.delta', item_id: itemId, output_index: output.length, content_index: 0, delta: text });
+            add('response.output_text.done', { type: 'response.output_text.done', item_id: itemId, output_index: output.length, content_index: 0, text });
+        }
+        add('response.content_part.done', { type: 'response.content_part.done', output_index: output.length, content_index: 0, part });
+        add('response.output_item.done', { type: 'response.output_item.done', output_index: output.length, item });
+        output.push(item);
+    }
+    if (message.tool_calls !== undefined) {
+        if (!Array.isArray(message.tool_calls))
+            throw new Error('Gateway returned invalid tool calls');
+        for (const callValue of message.tool_calls) {
+            if (!isRecord(callValue) || callValue.type !== 'function' || !isRecord(callValue.function)
+                || typeof callValue.function.name !== 'string' || typeof callValue.function.arguments !== 'string') {
+                throw new Error('Gateway returned an invalid function call');
+            }
+            const callId = typeof callValue.id === 'string' ? callValue.id : `call_${randomUUID().replaceAll('-', '')}`;
+            const itemId = `fc_${randomUUID().replaceAll('-', '')}`;
+            const item = {
+                id: itemId,
+                type: 'function_call',
+                status: 'completed',
+                call_id: callId,
+                name: callValue.function.name,
+                arguments: callValue.function.arguments,
+            };
+            add('response.output_item.added', {
+                type: 'response.output_item.added', output_index: output.length,
+                item: { ...item, status: 'in_progress', arguments: '' },
+            });
+            add('response.function_call_arguments.delta', {
+                type: 'response.function_call_arguments.delta', item_id: itemId, output_index: output.length,
+                delta: callValue.function.arguments,
+            });
+            add('response.function_call_arguments.done', {
+                type: 'response.function_call_arguments.done', item_id: itemId, output_index: output.length,
+                arguments: callValue.function.arguments,
+            });
+            add('response.output_item.done', { type: 'response.output_item.done', output_index: output.length, item });
+            output.push(item);
+        }
+    }
+    const incomplete = choice.finish_reason === 'length';
+    const final = {
+        ...base,
+        status: incomplete ? 'incomplete' : 'completed',
+        completed_at: Math.floor(Date.now() / 1000),
+        incomplete_details: incomplete ? { reason: 'max_output_tokens' } : null,
+        output,
+        ...(usage ? { usage } : {}),
+    };
+    add(incomplete ? 'response.incomplete' : 'response.completed', {
+        type: incomplete ? 'response.incomplete' : 'response.completed', response: final,
+    });
+    return events.map(({ event, data }) => `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`).join('');
+}

package/dist/setup-config.d.ts

@@ -0,0 +1,36 @@
+import { type CircuitManifest } from './artifact-bundle.js';
+export type SetupWitnessSource = {
+    kind: 'file';
+    path: string;
+} | {
+    kind: 'base-events';
+    rpcUrl: string;
+    contractAddress: string;
+    deploymentBlock?: string;
+    confirmations?: string;
+};
+export interface SetupConfig {
+    version: 1;
+    artifactDirectory: string;
+    witness: SetupWitnessSource;
+}
+export interface ResolveSetupInputsOptions {
+    environment: NodeJS.ProcessEnv;
+    homeDirectory: string;
+    stateDirectory: string;
+    configPath: string;
+    manifest: CircuitManifest;
+    /** Must prove this source resolves a valid witness for the activated credential. */
+    validateWitness(source: SetupWitnessSource): Promise<void>;
+    /** Called only when more than one valid local candidate exists. */
+    chooseCandidate?(kind: 'proving bundle' | 'witness file', candidates: readonly string[]): Promise<string>;
+    workingDirectory?: string;
+}
+/** Finds only known local locations and validates both sources before setup continues. */
+export declare function resolveSetupInputs(options: ResolveSetupInputsOptions): Promise<SetupConfig>;
+/** Reads the operator-local setup config. Missing config is normal on first run. */
+export declare function readSetupConfig(path: string): Promise<SetupConfig | undefined>;
+/** Atomically writes paths and witness configuration with owner-only permissions. */
+export declare function writeSetupConfig(path: string, config: SetupConfig): Promise<void>;
+/** Applies saved paths to a process environment while preserving explicit overrides. */
+export declare function applySetupConfig(environment: NodeJS.ProcessEnv, config: SetupConfig): void;

package/dist/setup-config.js

@@ -0,0 +1,320 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { resolvePinnedArtifactBundle } from './artifact-bundle.js';
+const WITNESS_FILENAMES = new Set([
+    'base-tree.json',
+    'base-sepolia-tree.json',
+    'base-tree-artifact.json',
+    'public-tree.json',
+    'base-witness.json',
+    'zk-credits-witness.json',
+    'witness.json',
+    'tree.json',
+]);
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function absolutePath(value, label) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error('Setup configuration ' + label + ' is required');
+    }
+    return resolve(value);
+}
+function optionalUnsignedString(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !/^\d+$/u.test(value)) {
+        throw new Error('Local setup config ' + label + ' must be a non-negative integer');
+    }
+    return value;
+}
+function parseSetupConfig(value) {
+    if (!isRecord(value) || value.version !== 1 || !isRecord(value.witness)) {
+        throw new Error('Local setup config is malformed; remove ~/.zk-credits/config.json and run setup again.');
+    }
+    const artifactDirectory = absolutePath(value.artifactDirectory, 'artifactDirectory');
+    const witnessValue = value.witness;
+    let witness;
+    if (witnessValue.kind === 'file') {
+        witness = { kind: 'file', path: absolutePath(witnessValue.path, 'witness.path') };
+    }
+    else if (witnessValue.kind === 'base-events') {
+        if (typeof witnessValue.rpcUrl !== 'string' || !/^https?:\/\//u.test(witnessValue.rpcUrl)) {
+            throw new Error('Local setup config has an invalid Base RPC URL');
+        }
+        if (typeof witnessValue.contractAddress !== 'string' || !/^0x[0-9a-fA-F]{40}$/u.test(witnessValue.contractAddress)) {
+            throw new Error('Local setup config has an invalid Base bond contract address');
+        }
+        const deploymentBlock = optionalUnsignedString(witnessValue.deploymentBlock, 'deploymentBlock');
+        const confirmations = optionalUnsignedString(witnessValue.confirmations, 'confirmations');
+        witness = {
+            kind: 'base-events',
+            rpcUrl: witnessValue.rpcUrl,
+            contractAddress: witnessValue.contractAddress,
+            ...(deploymentBlock === undefined ? {} : { deploymentBlock }),
+            ...(confirmations === undefined ? {} : { confirmations }),
+        };
+    }
+    else {
+        throw new Error('Local setup config has an unknown witness source');
+    }
+    return { version: 1, artifactDirectory, witness };
+}
+function optionalEnvironmentInteger(environment, name) {
+    const value = environment[name]?.trim();
+    if (!value)
+        return undefined;
+    if (!/^\d+$/u.test(value))
+        throw new Error(name + ' must be a non-negative integer');
+    return value;
+}
+async function candidateDirectories(homeDirectory, stateDirectory) {
+    const roots = [
+        join(stateDirectory, 'artifacts', 'base-sepolia'),
+        join(homeDirectory, '.zk-credits', 'artifacts', 'base-sepolia'),
+        join(homeDirectory, 'Downloads'),
+    ];
+    const candidates = [...roots];
+    for (const root of roots) {
+        let entries;
+        try {
+            entries = await readdir(root, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory())
+                candidates.push(join(root, entry.name));
+        }
+    }
+    return [...new Set(candidates.map((path) => resolve(path)))];
+}
+async function chooseOne(kind, candidates, chooseCandidate) {
+    if (candidates.length === 1)
+        return candidates[0];
+    if (!chooseCandidate) {
+        const variable = kind === 'proving bundle' ? 'ZK_CREDITS_ARTIFACT_DIR' : 'ZK_CREDITS_WITNESS_PATH';
+        throw new Error('Found more than one valid ' + kind + '; set ' + variable + ' to choose one.');
+    }
+    const selected = await chooseCandidate(kind, candidates);
+    if (!candidates.includes(resolve(selected))) {
+        throw new Error('The selected ' + kind + ' is not one of the validated local candidates');
+    }
+    return resolve(selected);
+}
+async function resolveArtifactDirectory(options, saved) {
+    const explicit = options.environment.ZK_CREDITS_ARTIFACT_DIR?.trim();
+    const candidates = explicit
+        ? [resolve(options.workingDirectory ?? process.cwd(), explicit)]
+        : [
+            ...(saved ? [saved.artifactDirectory] : []),
+            ...await candidateDirectories(options.homeDirectory, options.stateDirectory),
+        ];
+    const valid = new Map();
+    let explicitError;
+    for (const candidate of candidates) {
+        try {
+            const bundle = await resolvePinnedArtifactBundle({
+                artifactDirectory: candidate,
+                manifest: options.manifest,
+            });
+            let identity = resolve(bundle.directory);
+            try {
+                identity = await realpath(bundle.directory);
+            }
+            catch { /* resolve already validated the directory */ }
+            valid.set(identity, bundle.directory);
+        }
+        catch (error) {
+            if (explicit)
+                explicitError = error;
+        }
+    }
+    if (explicit && valid.size === 0) {
+        const reason = explicitError instanceof Error ? ' ' + explicitError.message : '';
+        throw new Error('The configured proving bundle at ' + explicit + ' failed its pinned checks.' + reason);
+    }
+    if (valid.size === 0) {
+        throw new Error('Could not find a valid pinned proving bundle. Extract the bundle from your pilot contact into ~/.zk-credits/artifacts/base-sepolia or ~/Downloads, or set ZK_CREDITS_ARTIFACT_DIR.');
+    }
+    const selected = await chooseOne('proving bundle', [...valid.values()], options.chooseCandidate);
+    return resolve(selected);
+}
+function eventSourceFromEnvironment(environment) {
+    const rpcUrl = environment.BASE_RPC_URL?.trim();
+    const contractAddress = environment.BASE_PRIVATE_CREDIT_BOND_ADDRESS?.trim();
+    if (!rpcUrl || !contractAddress)
+        return undefined;
+    const deploymentBlock = optionalEnvironmentInteger(environment, 'BASE_DEPLOYMENT_BLOCK');
+    const confirmations = optionalEnvironmentInteger(environment, 'BASE_CONFIRMATIONS');
+    return {
+        kind: 'base-events',
+        rpcUrl,
+        contractAddress,
+        ...(deploymentBlock === undefined ? {} : { deploymentBlock }),
+        ...(confirmations === undefined ? {} : { confirmations }),
+    };
+}
+function witnessCandidates(homeDirectory, stateDirectory) {
+    const roots = [
+        join(stateDirectory, 'witnesses'),
+        join(stateDirectory, 'witness'),
+        join(homeDirectory, '.zk-credits', 'witnesses'),
+        join(homeDirectory, 'Downloads'),
+    ];
+    return [...new Set(roots.flatMap((root) => [...WITNESS_FILENAMES].map((name) => resolve(root, name))))];
+}
+async function resolveWitnessSource(options, saved) {
+    const environment = options.environment;
+    const explicitPath = environment.ZK_CREDITS_WITNESS_PATH?.trim();
+    if (explicitPath) {
+        const source = {
+            kind: 'file',
+            path: resolve(options.workingDirectory ?? process.cwd(), explicitPath),
+        };
+        try {
+            await options.validateWitness(source);
+            return source;
+        }
+        catch (error) {
+            const reason = error instanceof Error ? ' ' + error.message : '';
+            throw new Error('The configured Base witness at ' + explicitPath + ' failed validation.' + reason);
+        }
+    }
+    const environmentSource = eventSourceFromEnvironment(environment);
+    if (environmentSource) {
+        try {
+            await options.validateWitness(environmentSource);
+            return environmentSource;
+        }
+        catch (error) {
+            const reason = error instanceof Error ? ' ' + error.message : '';
+            throw new Error('Base event witness sync failed.' + reason);
+        }
+    }
+    if (saved?.witness.kind === 'base-events') {
+        try {
+            await options.validateWitness(saved.witness);
+            return saved.witness;
+        }
+        catch (error) {
+            const reason = error instanceof Error ? ' ' + error.message : '';
+            throw new Error('Saved Base event witness source failed validation.' + reason);
+        }
+    }
+    if (saved?.witness.kind === 'file') {
+        try {
+            await options.validateWitness(saved.witness);
+            return saved.witness;
+        }
+        catch {
+            // A saved local witness can become stale for a different activated credential.
+        }
+    }
+    const valid = [];
+    for (const path of witnessCandidates(options.homeDirectory, options.stateDirectory)) {
+        try {
+            const info = await lstat(path);
+            if (!info.isFile())
+                continue;
+            const source = { kind: 'file', path };
+            await options.validateWitness(source);
+            valid.push(path);
+        }
+        catch {
+            // Ignore absent, unrelated, and non-resolving local files while searching.
+        }
+    }
+    if (valid.length > 0) {
+        return { kind: 'file', path: await chooseOne('witness file', valid, options.chooseCandidate) };
+    }
+    throw new Error('Could not find a public Base witness for this credential. Put base-tree.json or witness.json in ~/.zk-credits/witnesses or ~/Downloads, set ZK_CREDITS_WITNESS_PATH, or configure BASE_RPC_URL and BASE_PRIVATE_CREDIT_BOND_ADDRESS.');
+}
+/** Finds only known local locations and validates both sources before setup continues. */
+export async function resolveSetupInputs(options) {
+    const saved = await readSetupConfig(options.configPath);
+    const artifactDirectory = await resolveArtifactDirectory(options, saved);
+    const witness = await resolveWitnessSource(options, saved);
+    return { version: 1, artifactDirectory, witness };
+}
+/** Reads the operator-local setup config. Missing config is normal on first run. */
+export async function readSetupConfig(path) {
+    let raw;
+    try {
+        const info = await lstat(path);
+        if (!info.isFile())
+            throw new Error('Local setup config must be a regular file');
+        raw = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    try {
+        return parseSetupConfig(JSON.parse(raw));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new Error('Local setup config is not valid JSON; remove ~/.zk-credits/config.json and run setup again.');
+        }
+        throw error;
+    }
+}
+/** Atomically writes paths and witness configuration with owner-only permissions. */
+export async function writeSetupConfig(path, config) {
+    const normalized = parseSetupConfig(config);
+    const directory = dirname(resolve(path));
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const destination = resolve(path);
+    try {
+        const existing = await lstat(destination);
+        if (existing.isSymbolicLink())
+            throw new Error('Local setup config cannot be a symbolic link');
+    }
+    catch (error) {
+        if (!(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT'))
+            throw error;
+    }
+    const temporary = join(directory, '.config-' + randomUUID() + '.tmp');
+    try {
+        const file = await open(temporary, 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(normalized, null, 2) + '\n', 'utf8');
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, destination);
+        await chmod(destination, 0o600);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** Applies saved paths to a process environment while preserving explicit overrides. */
+export function applySetupConfig(environment, config) {
+    if (!environment.ZK_CREDITS_ARTIFACT_DIR?.trim()) {
+        environment.ZK_CREDITS_ARTIFACT_DIR = config.artifactDirectory;
+    }
+    if (config.witness.kind === 'file') {
+        if (!environment.ZK_CREDITS_WITNESS_PATH?.trim()) {
+            environment.ZK_CREDITS_WITNESS_PATH = config.witness.path;
+        }
+        return;
+    }
+    if (!environment.BASE_RPC_URL?.trim())
+        environment.BASE_RPC_URL = config.witness.rpcUrl;
+    if (!environment.BASE_PRIVATE_CREDIT_BOND_ADDRESS?.trim()) {
+        environment.BASE_PRIVATE_CREDIT_BOND_ADDRESS = config.witness.contractAddress;
+    }
+    if (!environment.BASE_DEPLOYMENT_BLOCK?.trim() && config.witness.deploymentBlock !== undefined) {
+        environment.BASE_DEPLOYMENT_BLOCK = config.witness.deploymentBlock;
+    }
+    if (!environment.BASE_CONFIRMATIONS?.trim() && config.witness.confirmations !== undefined) {
+        environment.BASE_CONFIRMATIONS = config.witness.confirmations;
+    }
+}