@astrosheep/keiyaku 1.0.0 → 1.0.2

package/build/config/settings.js

@@ -3,8 +3,181 @@ import * as path from "node:path";
 import { z } from "zod";
 import { isErrnoException } from "../errno.js";
 import { FlowError } from "../flow-error.js";
-import { SETTINGS_FILE, } from "../keiyaku.js";
+import { CLAUDE_SETTING_SOURCES, SETTINGS_FILE, } from "../keiyaku.js";
 import { getKeiyakuHome } from "./env.js";
+const tomlValueSchema = z.lazy(() => z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.array(tomlValueSchema),
+    z.record(z.string(), tomlValueSchema),
+]));
+const structuredTomlValueSchema = z.record(z.string(), tomlValueSchema);
+const executableSchema = z.string().superRefine((value, ctx) => {
+    if (value.length === 0 || /\s/.test(value) || value.includes("\"") || value.includes("'")) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "must be a single program name token with no spaces or quotes.",
+        });
+    }
+});
+const nonblankOptionalString = z
+    .string()
+    .refine((value) => value.trim().length > 0, { message: "must not be blank." })
+    .optional();
+const providerCommonFields = {
+    description: nonblankOptionalString,
+};
+const CODEX_SDK_FORBIDDEN_THREAD_OPTIONS_KEYS = [
+    "model",
+    "modelReasoningEffort",
+    "sandboxMode",
+    "networkAccessEnabled",
+    "webSearchMode",
+    "approvalPolicy",
+    "workingDirectory",
+    "skipGitRepoCheck",
+];
+const FORBIDDEN_CONFIG_KEYS = [
+    "model",
+    "model_reasoning_effort",
+    "sandbox_mode",
+    "sandbox_workspace_write",
+    "web_search",
+    "approval_policy",
+];
+function isConfigKeyForbidden(key) {
+    // Exact match for model, model_reasoning_effort, sandbox_mode, web_search, approval_policy
+    if (FORBIDDEN_CONFIG_KEYS.includes(key))
+        return true;
+    // sandbox_workspace_write also rejects dotted subkeys from adapter-native TOML flattening
+    if (key.startsWith("sandbox_workspace_write."))
+        return true;
+    return false;
+}
+const claudeSettingSourceSchema = z.enum(CLAUDE_SETTING_SOURCES);
+const writableRootItemSchema = z.string().superRefine((value, ctx) => {
+    if (value.length === 0) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "must not be empty." });
+        return;
+    }
+    if (value.startsWith("~")) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "must not begin with tilde." });
+        return;
+    }
+    if (value.includes("\0")) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "must not contain NUL byte." });
+        return;
+    }
+    if (/\$[A-Za-z_]/.test(value) || /\$\{/.test(value)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "must not contain environment variable references." });
+        return;
+    }
+});
+export const providerInstanceSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("codex-sdk"),
+        ...providerCommonFields,
+        executable: executableSchema.optional(),
+        profile: z.string().optional(),
+        config: structuredTomlValueSchema.optional(),
+        threadOptions: structuredTomlValueSchema.optional(),
+    })
+        .strict()
+        .superRefine((data, ctx) => {
+        if (data.threadOptions) {
+            for (const key of CODEX_SDK_FORBIDDEN_THREAD_OPTIONS_KEYS) {
+                if (key in data.threadOptions) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ["threadOptions", key],
+                        message: `"${key}" is owned by the Akuma or Keiyaku execution, not this provider instance`,
+                    });
+                }
+            }
+        }
+        if (data.config) {
+            for (const key of Object.keys(data.config)) {
+                if (isConfigKeyForbidden(key)) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ["config", key],
+                        message: `"${key}" is owned by the Akuma or Keiyaku execution, not this provider instance`,
+                    });
+                }
+            }
+        }
+    }),
+    z
+        .object({
+        kind: z.literal("codex-app-server"),
+        ...providerCommonFields,
+        executable: executableSchema.optional(),
+        profile: z.string().optional(),
+        config: structuredTomlValueSchema.optional(),
+        writableRoots: z.array(writableRootItemSchema).optional(),
+    })
+        .strict()
+        .superRefine((data, ctx) => {
+        if (data.config) {
+            for (const key of Object.keys(data.config)) {
+                if (isConfigKeyForbidden(key)) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ["config", key],
+                        message: `"${key}" is owned by the Akuma or Keiyaku execution, not this provider instance`,
+                    });
+                }
+            }
+        }
+    }),
+    z
+        .object({
+        kind: z.literal("claude-agent-sdk"),
+        ...providerCommonFields,
+        executable: executableSchema.optional(),
+        settingSources: z.array(claudeSettingSourceSchema).optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("opencode-sdk"),
+        ...providerCommonFields,
+        executable: executableSchema.optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("pi"),
+        ...providerCommonFields,
+    })
+        .strict(),
+]);
+const PROVIDER_INSTANCE_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+export const providerInstanceNameSchema = z
+    .string()
+    .max(64, "must contain at most 64 characters.")
+    .regex(PROVIDER_INSTANCE_NAME_PATTERN, "must match ^[a-z0-9][a-z0-9-]*$.");
+export const BUILTIN_PROVIDER_INSTANCE_CANDIDATES = {
+    "codex-sdk": { name: "codex-sdk", source: "builtin", instance: { kind: "codex-sdk", executable: "codex" } },
+    "codex-app-server": {
+        name: "codex-app-server",
+        source: "builtin",
+        instance: { kind: "codex-app-server", executable: "codex" },
+    },
+    "claude-agent-sdk": {
+        name: "claude-agent-sdk",
+        source: "builtin",
+        instance: { kind: "claude-agent-sdk", executable: "claude", settingSources: ["project"] },
+    },
+    "opencode-sdk": {
+        name: "opencode-sdk",
+        source: "builtin",
+        instance: { kind: "opencode-sdk", executable: "opencode" },
+    },
+    pi: { name: "pi", source: "builtin", instance: { kind: "pi" } },
+};
 const AGENT_NAME_PATTERN = /^[a-zA-Z0-9]+(?:[.-][a-zA-Z0-9]+)*$/;
 export const agentNameSchema = z
     .string()
@@ -52,13 +225,46 @@ const gateSchema = z
     commands: z.array(gateCommandSchema).optional(),
 })
     .strict();
-const KNOWN_SETTINGS_KNOBS = ["default", "reviewer", "gate", "defaultBranch"];
+const KNOWN_SETTINGS_KNOBS = ["default", "reviewer", "gate", "defaultBranch", "worktreeBootstrap"];
+const KNOWN_SETTINGS_ROOT_KEYS = [...KNOWN_SETTINGS_KNOBS, "providers"];
+const WORKTREE_BOOTSTRAP_DEFAULT_TIMEOUT_MS = 300_000;
+const WORKTREE_BOOTSTRAP_MIN_TIMEOUT_MS = 1;
+const WORKTREE_BOOTSTRAP_MAX_TIMEOUT_MS = 3_600_000;
+export const worktreeBootstrapSchema = z
+    .object({
+    command: z
+        .array(z.string())
+        .min(1, "command must be a nonempty argv array.")
+        .superRefine((items, ctx) => {
+        items.forEach((item, index) => {
+            if (item.trim().length === 0) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [index],
+                    message: "command items must be nonempty after trimming.",
+                });
+            }
+        });
+    }),
+    timeoutMs: z
+        .number()
+        .int("timeoutMs must be an integer.")
+        .min(WORKTREE_BOOTSTRAP_MIN_TIMEOUT_MS, `timeoutMs must be >= ${WORKTREE_BOOTSTRAP_MIN_TIMEOUT_MS}.`)
+        .max(WORKTREE_BOOTSTRAP_MAX_TIMEOUT_MS, `timeoutMs must be <= ${WORKTREE_BOOTSTRAP_MAX_TIMEOUT_MS}.`)
+        .optional(),
+})
+    .strict()
+    .transform((value) => ({
+    command: value.command,
+    timeoutMs: value.timeoutMs ?? WORKTREE_BOOTSTRAP_DEFAULT_TIMEOUT_MS,
+}));
 const settingsSchema = z
     .object({
     default: agentNameSchema.optional(),
     reviewer: agentNameSchema.optional(),
     gate: gateSchema.optional(),
     defaultBranch: optionalTrimmedString(),
+    worktreeBootstrap: worktreeBootstrapSchema.optional(),
 })
     .strict();
 const knobSchemas = {
@@ -66,6 +272,7 @@ const knobSchemas = {
     reviewer: agentNameSchema,
     gate: gateSchema,
     defaultBranch: optionalTrimmedString(),
+    worktreeBootstrap: worktreeBootstrapSchema,
 };
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -108,27 +315,102 @@ async function readSettingsSource(filePath) {
         return { found: true, raw: undefined, parseError: reason };
     }
 }
-function collectSourceDiseases(source, read) {
+function builtinProviderInstanceCatalog() {
+    return { selected: { ...BUILTIN_PROVIDER_INSTANCE_CANDIDATES }, shadows: [] };
+}
+function formatProviderInstanceIssues(name, error) {
+    return error.issues
+        .map((issue) => {
+        const suffix = issue.path.length === 0 ? "" : `.${issue.path.join(".")}`;
+        return `providers.${name}${suffix}: ${issue.message}`;
+    })
+        .join("; ");
+}
+function collectProviderCandidates(source, rawProviders) {
+    if (!isPlainObject(rawProviders)) {
+        return {
+            candidates: [],
+            disease: { source: source === "project" ? "local" : "global", knob: "providers", reason: "providers: must be a JSON object" },
+        };
+    }
+    const candidates = [];
+    for (const [name, rawInstance] of Object.entries(rawProviders)) {
+        const nameResult = providerInstanceNameSchema.safeParse(name);
+        if (!nameResult.success) {
+            candidates.push({
+                name,
+                source,
+                reason: formatProviderInstanceIssues(name, nameResult.error),
+            });
+            continue;
+        }
+        const instanceResult = providerInstanceSchema.safeParse(rawInstance);
+        if (!instanceResult.success) {
+            candidates.push({
+                name,
+                source,
+                reason: formatProviderInstanceIssues(name, instanceResult.error),
+            });
+            continue;
+        }
+        const instance = instanceResult.data;
+        if (instance.kind === "codex-app-server" && instance.writableRoots !== undefined && source === "global") {
+            let relativeIndex;
+            for (let i = 0; i < instance.writableRoots.length; i++) {
+                if (!path.posix.isAbsolute(instance.writableRoots[i])) {
+                    relativeIndex = i;
+                    break;
+                }
+            }
+            if (relativeIndex !== undefined) {
+                candidates.push({
+                    name,
+                    source,
+                    reason: `providers.${name}.writableRoots.${relativeIndex}: writableRoots item must be an absolute path for global provider instances`,
+                });
+                continue;
+            }
+        }
+        candidates.push({ name, source, instance: instanceResult.data });
+    }
+    return { candidates };
+}
+function mergeProviderCandidates(catalog, candidates) {
+    const selected = { ...catalog.selected };
+    const shadows = [...catalog.shadows];
+    for (const candidate of candidates) {
+        const prior = selected[candidate.name];
+        if (prior !== undefined) {
+            shadows.push({ name: candidate.name, source: prior.source, shadowedBy: candidate.source });
+        }
+        selected[candidate.name] = candidate;
+    }
+    return { selected, shadows };
+}
+function collectSourceDiseases(source, providerSource, read) {
     if (!read.found) {
-        return { partial: {}, diseases: [] };
+        return { partial: {}, diseases: [], providerCandidates: [] };
     }
     if (read.parseError !== undefined) {
         return {
             partial: {},
             diseases: [{ source, reason: `settings root is unreadable (${read.parseError})` }],
+            providerCandidates: [],
         };
     }
     if (!isPlainObject(read.raw)) {
         return {
             partial: {},
             diseases: [{ source, reason: "settings root must be a JSON object" }],
+            providerCandidates: [],
         };
     }
     const diseases = [];
     const partial = {};
+    let providerCandidates = [];
     const raw = read.raw;
     for (const key of Object.keys(raw)) {
-        if (!KNOWN_SETTINGS_KNOBS.includes(key)) {
+        if (!KNOWN_SETTINGS_ROOT_KEYS.includes(key)) {
             diseases.push({
                 source,
                 knob: key,
@@ -138,9 +420,25 @@ function collectSourceDiseases(source, read) {
             });
         }
     }
+    if ("providers" in raw) {
+        const collectedProviders = collectProviderCandidates(providerSource, raw.providers);
+        providerCandidates = collectedProviders.candidates;
+        if (collectedProviders.disease !== undefined)
+            diseases.push(collectedProviders.disease);
+    }
     for (const knob of KNOWN_SETTINGS_KNOBS) {
         if (!(knob in raw))
             continue;
+        // worktreeBootstrap is project-layer only. Global/user presence is a named
+        // disease and never contributes execution authority.
+        if (knob === "worktreeBootstrap" && source === "global") {
+            diseases.push({
+                source,
+                knob,
+                reason: "worktreeBootstrap is project-only and never supplies a value from global settings",
+            });
+            continue;
+        }
         const schema = knobSchemas[knob];
         const result = schema.safeParse(raw[knob]);
         if (!result.success) {
@@ -155,18 +453,29 @@ function collectSourceDiseases(source, read) {
             continue;
         partial[knob] = result.data;
     }
-    return { partial, diseases };
+    return { partial, diseases, providerCandidates };
 }
 function mergeSettingsKnobs(base, override) {
-    const mergedRaw = deepMerge(base, override);
-    if (!isPlainObject(mergedRaw))
-        return { ...override };
+    // worktreeBootstrap is whole-value project authority; never field-merge it.
+    const { worktreeBootstrap: baseBootstrap, ...baseRest } = base;
+    const { worktreeBootstrap: overrideBootstrap, ...overrideRest } = override;
+    const mergedRaw = deepMerge(baseRest, overrideRest);
+    if (!isPlainObject(mergedRaw)) {
+        return overrideBootstrap !== undefined
+            ? { ...override, worktreeBootstrap: overrideBootstrap }
+            : { ...override };
+    }
     const merged = {};
     for (const knob of KNOWN_SETTINGS_KNOBS) {
+        if (knob === "worktreeBootstrap")
+            continue;
         if (knob in mergedRaw) {
             merged[knob] = mergedRaw[knob];
         }
     }
+    const bootstrap = overrideBootstrap ?? baseBootstrap;
+    if (bootstrap !== undefined)
+        merged.worktreeBootstrap = bootstrap;
     return merged;
 }
 export function findSettingsDiseasesForKnob(diseases, knob) {
@@ -210,17 +519,21 @@ export async function loadKeiyakuSettings(cwd) {
         return {
             knobs: null,
             diseases: [{ source: "local", reason: `settings root is unreadable (${reason})` }],
+            providerInstances: builtinProviderInstanceCatalog(),
         };
     }
-    const globalCollected = collectSourceDiseases("global", globalRead);
-    const localCollected = collectSourceDiseases("local", localRead);
+    const globalCollected = collectSourceDiseases("global", "global", globalRead);
+    const localCollected = collectSourceDiseases("local", "project", localRead);
     const diseases = [...globalCollected.diseases, ...localCollected.diseases];
+    let providerInstances = builtinProviderInstanceCatalog();
+    providerInstances = mergeProviderCandidates(providerInstances, globalCollected.providerCandidates);
+    providerInstances = mergeProviderCandidates(providerInstances, localCollected.providerCandidates);
     let knobs = null;
     if (globalRead.found || localRead.found) {
         knobs = mergeSettingsKnobs(globalCollected.partial, localCollected.partial);
     }
     // Empty object still means "settings files were present"; callers treat null as absent files.
-    return { knobs, diseases };
+    return { knobs, diseases, providerInstances };
 }
 export function resolveDefaultAgentName(settings) {
     return settings?.default ?? "akuma-codex";

package/build/core/addressing.js

@@ -0,0 +1,224 @@
+import * as path from "node:path";
+import { FlowError } from "../flow-error.js";
+import { listContractIds, readLedger } from "./ledger.js";
+import { stableRepoRoot } from "./worktree-path.js";
+import { deriveContractState, isTerminalState, } from "./status.js";
+function normalizeAddressQuery(raw) {
+    const value = raw.startsWith("@") ? raw.slice(1) : raw;
+    if (!value.trim()) {
+        throw new FlowError("EMPTY_PARAM", "contract address cannot be empty");
+    }
+    return value.trim();
+}
+const ADDRESS_CARRIER = Symbol.for("keiyaku.address-carrier");
+class AddressedFlowError extends FlowError {
+    [ADDRESS_CARRIER];
+    constructor(error, carrier) {
+        super(error.code, error.message, {
+            cause: error,
+            hints: error.hints,
+            review: error.review,
+        });
+        this.name = error.name;
+        this[ADDRESS_CARRIER] = carrier;
+    }
+}
+class AddressedError extends Error {
+    [ADDRESS_CARRIER];
+    constructor(error, carrier) {
+        super(error instanceof Error ? error.message : String(error), { cause: error });
+        this.name = error instanceof Error ? error.name : "Error";
+        this[ADDRESS_CARRIER] = carrier;
+    }
+}
+export function attachAddressCarrier(error, carrier) {
+    if (addressCarrierFromError(error))
+        return error;
+    return error instanceof FlowError
+        ? new AddressedFlowError(error, carrier)
+        : new AddressedError(error, carrier);
+}
+export function addressCarrierFromError(error) {
+    const seen = new Set();
+    let current = error;
+    while (((typeof current === "object" && current !== null) || typeof current === "function") && !seen.has(current)) {
+        seen.add(current);
+        if (current instanceof AddressResolutionError)
+            return current.attempt;
+        const addressed = current;
+        if (addressed[ADDRESS_CARRIER])
+            return addressed[ADDRESS_CARRIER];
+        current = addressed.cause;
+    }
+    return undefined;
+}
+export async function withResolvedAddress(address, operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        throw attachAddressCarrier(error, address);
+    }
+}
+export function buildResolutionAttempt(input) {
+    return {
+        repo: input.repo,
+        workdir: path.resolve(input.workdir),
+        expected: "commission",
+        ...(input.spelling ? { spelling: input.spelling } : {}),
+        candidates: [...(input.candidates ?? [])],
+        inference: [...(input.inference ?? [])],
+    };
+}
+export class AddressResolutionError extends FlowError {
+    attempt;
+    constructor(code, message, attempt, options) {
+        super(code, message, options);
+        this.name = "AddressResolutionError";
+        this.attempt = attempt;
+    }
+}
+function contractSlug(contractId) {
+    const separator = contractId.indexOf(".");
+    return separator > 0 ? contractId.slice(0, separator) : contractId;
+}
+async function commissionAddressCandidates(cwd) {
+    const ids = await listContractIds(cwd);
+    const ledgers = await Promise.all(ids.map(async (contractId) => readLedger(cwd, contractId)));
+    return ledgers.flatMap((ledger) => {
+        if (!ledger)
+            return [];
+        const bind = ledger.entries.find((entry) => entry.kind === "bind");
+        if (!bind || bind.contract !== ledger.contractId)
+            return [];
+        const lifecycle = deriveContractState(ledger.entries);
+        return [{
+                contractId: ledger.contractId,
+                bind,
+                active: lifecycle.state !== "corrupt" && !isTerminalState(lifecycle),
+                lifecycle,
+            }];
+    });
+}
+function matchCommissionAddress(query, candidates) {
+    return candidates.flatMap((candidate) => {
+        const matches = [];
+        if (candidate.contractId === query)
+            matches.push({ ...candidate, spelling: "id" });
+        if (contractSlug(candidate.contractId) === query)
+            matches.push({ ...candidate, spelling: "slug" });
+        if (candidate.active && candidate.bind.data.place === query) {
+            matches.push({ ...candidate, spelling: "place" });
+        }
+        return matches;
+    });
+}
+function attemptCandidates(candidates) {
+    return candidates.map((candidate) => ({
+        commissionId: candidate.contractId,
+        place: candidate.bind.data.place ?? null,
+        name: candidate.bind.data.name,
+        objective: candidate.bind.data.objective,
+        lifecycle: candidate.lifecycle,
+        target: { branch: candidate.bind.data.target },
+    }));
+}
+function formatAmbiguousCandidate(query, candidate) {
+    const label = candidate.matchedBy ?? "candidate";
+    return `${label} @${query}: ${candidate.name} · ${candidate.objective} · commission ${candidate.commissionId}`;
+}
+async function resolvedRepository(cwd) {
+    return { kind: "repository", stableRoot: await stableRepoRoot(cwd) };
+}
+function buildResolvedAddress(input) {
+    return {
+        repo: input.repo,
+        workdir: input.workdir,
+        binding: { kind: "commission", commissionId: input.candidate.contractId },
+        spelling: { asTyped: input.asTyped, source: input.source, matchedBy: input.matchedBy },
+        place: { display: input.candidate.bind.data.place ?? null },
+        lifecycle: input.candidate.lifecycle,
+        target: { branch: input.candidate.bind.data.target },
+        inference: input.inference,
+    };
+}
+export function buildUncommissionedAddress(input) {
+    return {
+        repo: input.repo,
+        workdir: path.resolve(input.workdir),
+        binding: { kind: input.binding },
+        inference: [...(input.inference ?? [])],
+    };
+}
+export async function resolveUncommissionedRepositoryAddress(input) {
+    const repo = await resolvedRepository(input.repoCwd);
+    return buildUncommissionedAddress({
+        repo,
+        workdir: input.workdir,
+        binding: input.binding,
+        inference: input.inference,
+    });
+}
+export async function resolveContractAddress(cwd, raw, source = raw?.startsWith("@") ? "at-address" : "explicit-flag") {
+    const workdir = path.resolve(cwd);
+    const repo = await resolvedRepository(cwd);
+    const candidates = await commissionAddressCandidates(repo.stableRoot);
+    if (raw === undefined) {
+        const operable = candidates.filter((candidate) => candidate.active);
+        const attempt = {
+            repo,
+            workdir,
+            expected: "commission",
+            candidates: attemptCandidates(operable),
+            inference: ["consulted active commission ledgers"],
+        };
+        if (operable.length === 1) {
+            const candidate = operable[0];
+            return buildResolvedAddress({
+                repo,
+                workdir,
+                candidate,
+                matchedBy: "id",
+                asTyped: `@${candidate.contractId}`,
+                source: "sole-active",
+                inference: attempt.inference,
+            });
+        }
+        throw new AddressResolutionError(operable.length === 0 ? "EMPTY_PARAM" : "CONTRACT_AMBIGUOUS", operable.length === 0
+            ? "no active commission found; pass @place, @slug, full @commission-id, or --contract <addr>"
+            : "multiple active commissions found; pass @place, @slug, full @commission-id, or --contract <addr>", attempt);
+    }
+    const query = normalizeAddressQuery(raw);
+    const matches = matchCommissionAddress(query, candidates);
+    const attempt = {
+        repo,
+        workdir,
+        expected: "commission",
+        spelling: { asTyped: source === "at-address" ? `@${query}` : query, source },
+        candidates: matches.map((candidate) => ({
+            commissionId: candidate.contractId,
+            matchedBy: candidate.spelling,
+            place: candidate.bind.data.place ?? null,
+            name: candidate.bind.data.name,
+            objective: candidate.bind.data.objective,
+            lifecycle: candidate.lifecycle,
+            target: { branch: candidate.bind.data.target },
+        })),
+        inference: [],
+    };
+    if (matches.length === 1) {
+        return buildResolvedAddress({
+            repo,
+            workdir,
+            candidate: matches[0],
+            matchedBy: matches[0].spelling,
+            asTyped: attempt.spelling.asTyped,
+            source,
+            inference: [],
+        });
+    }
+    if (matches.length === 0) {
+        throw new AddressResolutionError("EMPTY_PARAM", `unknown contract address @${query}`, attempt);
+    }
+    throw new AddressResolutionError("CONTRACT_AMBIGUOUS", `contract address @${query} is ambiguous: ${attempt.candidates.map((candidate) => formatAmbiguousCandidate(query, candidate)).join("; ")}; use a full @commission-id`, attempt);
+}