balladeer 1.0.17 → 1.0.18

package/dist/commands/anchor.d.ts

@@ -0,0 +1,127 @@
+import { type AnchorBudget } from "../anchor-budget.js";
+import { anchoringLines, type AnchorRun } from "../anchoring.js";
+import { connectionAnchorsClient, type AnchoredPromise, type AnchorsClient } from "../anchors-client.js";
+import { type PromiseAnchors } from "../anchors-schema.js";
+import { type BehaviorMap, type BehaviorMapMeaning } from "../behavior-map-schema.js";
+import { type HeadlessAgentOptions, type HeadlessAgentResult, type HeadlessClient, type LoginCheck } from "../headless-agent.js";
+import { type PromiseReader } from "../promise-meaning.js";
+import { type RepositoryGraph } from "../risk/graph-cache.js";
+import { ANCHOR_USAGE } from "./anchor-usage.js";
+import { type StoredMap } from "./map.js";
+export { anchoringLines, connectionAnchorsClient };
+/**
+ * `balladeer anchor`, and the anchoring step the push check runs before it
+ * selects what to judge.
+ *
+ * Both read the repository's agreed promises and their current anchors from
+ * Balladeer, build the repository graph at the commit from this laptop's
+ * cache, and bring every promise's anchors current within today's budget (see
+ * `../anchoring.ts`). A behavior map for a promise's current meaning still
+ * wins over its anchors when promises are selected.
+ */
+export type AnchorStage = Readonly<{
+    available: true;
+    promises: readonly AnchoredPromise[];
+    /** Maps in this checkout for their promise's current meaning, by promise id. */
+    currentMaps: ReadonlyMap<string, BehaviorMap>;
+    repository?: RepositoryGraph;
+    run?: AnchorRun;
+}> | Readonly<{
+    available: false;
+    /** Why the anchors could not be read, for a line when one is said. */
+    reason: string;
+    /**
+     * Anchors do not apply here at all: this laptop has no connection for
+     * the repository, or its server has no anchors route yet. Neither is
+     * worth a line of its own; everything works from maps, as before.
+     */
+    unsupported: boolean;
+}>;
+export type AnchorStageInput = Readonly<{
+    root: string;
+    head: string;
+    environment: NodeJS.ProcessEnv;
+    maps: readonly StoredMap[];
+    client: AnchorsClient | undefined;
+    /** Why there is no client, when there is none. */
+    clientMissing?: string;
+    reader: PromiseReader | undefined;
+    login: () => Promise<LoginCheck | undefined>;
+    now: () => Date;
+    deadline?: number;
+    signal?: AbortSignal;
+    concurrency?: number;
+    scratch?: string;
+    force?: ReadonlySet<string>;
+    only?: ReadonlySet<string>;
+    budget?: AnchorBudget;
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+    /** Replaces the graph build, for tests. */
+    graph?: (root: string, head: string) => RepositoryGraph;
+}>;
+/** Every parsed map whose meaning is the promise's current one, by promise id. */
+export declare function currentMapsFor(maps: readonly StoredMap[], promises: readonly AnchoredPromise[]): Map<string, BehaviorMap>;
+/** Read the anchors, and bring them current. Never throws for anything the server or a call does. */
+export declare function anchorStage(input: AnchorStageInput): Promise<AnchorStage>;
+/**
+ * Anchors in the shape the risk scorer reads, so a promise selected by its
+ * anchors is ordered by the same rule as a mapped one: its entry points and
+ * symbols as core, its linked tests, its resources, and the meaning's excerpt
+ * when it was read, which is what the scorer compares a change's words with.
+ */
+export declare function anchorsAsMap(anchors: PromiseAnchors, meaning?: BehaviorMapMeaning): BehaviorMap;
+/**
+ * What a judge is handed where a promise has anchors and no map: the anchors
+ * still in the code, the linked tests the graph gives at head, and the files
+ * one import step from the anchor files.
+ */
+export type JudgeAnchors = Readonly<{
+    anchors: PromiseAnchors;
+    linkedTests: readonly {
+        file: string;
+    }[];
+    neighborhood: readonly string[];
+}>;
+/** A promise's anchors as the judge receives them, read off the graph at the judged commit. */
+export declare function judgeAnchors(anchors: PromiseAnchors, repository: RepositoryGraph): JudgeAnchors;
+/**
+ * The promises a change edits an anchor file of (an entry point's or a
+ * symbol's file), from each promise's anchor files. Nothing further: no file
+ * that merely imports or is imported by an anchor file.
+ */
+export declare function anchoredByChange(anchorFilesOf: ReadonlyMap<string, readonly string[]>, changed: readonly string[]): string[];
+export type AnchorArguments = Readonly<{
+    promiseId?: string;
+    all: boolean;
+    json: boolean;
+    repo?: string;
+    client: HeadlessClient | "auto";
+    repository?: string;
+    controlPlane: string;
+}>;
+export { ANCHOR_USAGE };
+export declare function parseAnchorArguments(argv: readonly string[]): AnchorArguments;
+export type AnchorDependencies = Readonly<{
+    client?: AnchorsClient;
+    reader?: PromiseReader;
+    resolveLogin?: (requested: HeadlessClient | "auto") => Promise<LoginCheck | undefined>;
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+    now?: () => Date;
+    graph?: (root: string, head: string) => RepositoryGraph;
+    scratch?: string;
+}>;
+/** `balladeer anchor`, from arguments already parsed. */
+export declare function runAnchor(options: Readonly<{
+    args: AnchorArguments;
+    cwd: string;
+    environment: NodeJS.ProcessEnv;
+    write: (text: string) => void;
+    error: (text: string) => void;
+    deps?: AnchorDependencies;
+}>): Promise<number>;
+export declare function anchorCommand(argv: readonly string[], io: Readonly<{
+    cwd: string;
+    environment: NodeJS.ProcessEnv;
+    write: (text: string) => void;
+    error: (text: string) => void;
+}>): Promise<number>;

package/dist/commands/anchor.js

@@ -0,0 +1,303 @@
+import { join, resolve } from "node:path";
+import { anchorBudget } from "../anchor-budget.js";
+import { anchoringLines, bringAnchorsCurrent, linkedTestsFor, neighborhood, } from "../anchoring.js";
+import { connectionAnchorsClient, } from "../anchors-client.js";
+import { anchorFiles } from "../anchors-schema.js";
+import { BEHAVIOR_MAP_DIRECTORY, BEHAVIOR_MAP_SCHEMA_VERSION, } from "../behavior-map-schema.js";
+import { repositoryRoot } from "../git.js";
+import { resolveClient, } from "../headless-agent.js";
+import { connectionReader } from "../promise-meaning.js";
+import { buildRepositoryGraph } from "../risk/graph-cache.js";
+import { resolveCommit } from "../scratch-worktree.js";
+import { normalizeControlPlane, StoreError } from "../store.js";
+import { DEFAULT_CONTROL_PLANE } from "../wire.js";
+import { ANCHOR_USAGE } from "./anchor-usage.js";
+import { readBehaviorMaps } from "./map.js";
+// What the push check loads from here once a push is its to judge.
+export { anchoringLines, connectionAnchorsClient };
+/** Every parsed map whose meaning is the promise's current one, by promise id. */
+export function currentMapsFor(maps, promises) {
+    const digests = new Map(promises.map((promise) => [promise.promiseId, promise.semanticDigest]));
+    const current = new Map();
+    for (const entry of maps)
+        if (entry.map !== undefined && digests.get(entry.promiseId) === entry.map.semanticDigest)
+            current.set(entry.promiseId, entry.map);
+    return current;
+}
+/** Read the anchors, and bring them current. Never throws for anything the server or a call does. */
+export async function anchorStage(input) {
+    if (input.client === undefined)
+        return {
+            available: false,
+            reason: input.clientMissing ?? "there is no Balladeer connection for this repository",
+            unsupported: true,
+        };
+    const listed = await input.client.list();
+    if (!listed.ok)
+        return { available: false, reason: listed.reason, unsupported: listed.unsupported === true };
+    const promises = listed.promises;
+    const currentMaps = currentMapsFor(input.maps, promises);
+    if (promises.length === 0)
+        return { available: true, promises, currentMaps };
+    let repository;
+    try {
+        repository = (input.graph ??
+            ((root, head) => buildRepositoryGraph({ root, rev: head, environment: input.environment })))(input.root, input.head);
+    }
+    catch (error) {
+        return {
+            available: false,
+            reason: `the repository could not be read at ${input.head.slice(0, 12)}: ${error.message}`,
+            unsupported: false,
+        };
+    }
+    const run = await bringAnchorsCurrent({
+        promises,
+        currentMaps,
+        repository,
+        client: input.client,
+        reader: input.reader,
+        login: input.login,
+        budget: input.budget ?? anchorBudget(input.environment, input.now),
+        environment: input.environment,
+        now: input.now,
+        repositoryKey: repository.root,
+        ...(input.force === undefined ? {} : { force: input.force }),
+        ...(input.only === undefined ? {} : { only: input.only }),
+        ...(input.deadline === undefined ? {} : { deadline: input.deadline }),
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+        ...(input.concurrency === undefined ? {} : { concurrency: input.concurrency }),
+        ...(input.scratch === undefined ? {} : { scratch: input.scratch }),
+        ...(input.runAgent === undefined ? {} : { runAgent: input.runAgent }),
+    });
+    repository.save();
+    return { available: true, promises, currentMaps, repository, run };
+}
+/**
+ * Anchors in the shape the risk scorer reads, so a promise selected by its
+ * anchors is ordered by the same rule as a mapped one: its entry points and
+ * symbols as core, its linked tests, its resources, and the meaning's excerpt
+ * when it was read, which is what the scorer compares a change's words with.
+ */
+export function anchorsAsMap(anchors, meaning) {
+    return {
+        schemaVersion: BEHAVIOR_MAP_SCHEMA_VERSION,
+        promiseId: anchors.promiseId,
+        semanticDigest: anchors.semanticDigest,
+        mappedAt: {
+            sha: anchors.anchoredAt.sha,
+            at: anchors.anchoredAt.at,
+            client: anchors.anchoredAt.client ?? "claude",
+            model: anchors.anchoredAt.model ?? "",
+        },
+        entryPoints: anchors.entryPoints.map((entry) => ({ ...entry, note: "" })),
+        symbols: anchors.symbols.map((symbol) => ({ ...symbol, role: "core" })),
+        resources: [...anchors.resources],
+        linkedTests: anchors.linkedTests.map((test) => ({ file: test.file, name: "", cases: [] })),
+        sinks: [],
+        confidence: 0,
+        notes: "",
+        ...(meaning === undefined ? {} : { meaning }),
+    };
+}
+/** A promise's anchors as the judge receives them, read off the graph at the judged commit. */
+export function judgeAnchors(anchors, repository) {
+    const files = anchorFiles(anchors);
+    return {
+        anchors,
+        linkedTests: linkedTestsFor(repository.graph, files),
+        neighborhood: neighborhood(repository.graph, files),
+    };
+}
+/**
+ * The promises a change edits an anchor file of (an entry point's or a
+ * symbol's file), from each promise's anchor files. Nothing further: no file
+ * that merely imports or is imported by an anchor file.
+ */
+export function anchoredByChange(anchorFilesOf, changed) {
+    const edited = new Set(changed);
+    const selected = [];
+    for (const [promiseId, files] of anchorFilesOf)
+        if (files.some((file) => edited.has(file)))
+            selected.push(promiseId);
+    return selected.sort();
+}
+export { ANCHOR_USAGE };
+export function parseAnchorArguments(argv) {
+    const args = [...argv];
+    const positional = [];
+    let all = false;
+    let json = false;
+    let repo;
+    let repository;
+    let controlPlane;
+    let client = "auto";
+    const value = (flag, inline) => {
+        const next = inline ?? args.shift();
+        if (next === undefined || next === "")
+            throw new StoreError("usage", `${flag} needs a value.`);
+        return next;
+    };
+    while (args.length > 0) {
+        const arg = args.shift();
+        if (!arg.startsWith("--")) {
+            positional.push(arg);
+            continue;
+        }
+        const [name, ...rest] = arg.split("=");
+        const inline = rest.length > 0 ? rest.join("=") : undefined;
+        if (name === "--all")
+            all = true;
+        else if (name === "--json")
+            json = true;
+        else if (name === "--repo")
+            repo = value(name, inline);
+        else if (name === "--repository")
+            repository = value(name, inline);
+        else if (name === "--control-plane")
+            controlPlane = value(name, inline);
+        else if (name === "--client") {
+            const requested = value(name, inline);
+            if (requested !== "auto" && requested !== "claude" && requested !== "codex")
+                throw new StoreError("usage", "--client needs auto, claude or codex.");
+            client = requested;
+        }
+        else
+            throw new StoreError("usage", `Unknown option ${arg} for anchor.`);
+    }
+    if (positional.length > 1)
+        throw new StoreError("usage", "anchor takes at most one promise id.");
+    const promiseId = positional[0];
+    if (promiseId !== undefined && all)
+        throw new StoreError("usage", "Name one promise or pass --all, not both.");
+    if (promiseId !== undefined && !/^prom_[a-z0-9]{8,64}$/.test(promiseId))
+        throw new StoreError("usage", `"${promiseId}" is not a promise id.`);
+    const chosen = controlPlane ?? process.env.BALLADEER_CONTROL_PLANE?.trim() ?? DEFAULT_CONTROL_PLANE;
+    return {
+        ...(promiseId === undefined ? {} : { promiseId }),
+        all: promiseId === undefined,
+        json,
+        ...(repo === undefined ? {} : { repo }),
+        client,
+        ...(repository === undefined ? {} : { repository }),
+        controlPlane: normalizeControlPlane(chosen),
+    };
+}
+function count(n, one, many) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+function describeOutcome(outcome, anchors) {
+    const name = `${outcome.title} (${outcome.promiseId})`;
+    const shape = anchors === undefined
+        ? ""
+        : `: ${count(anchors.entryPoints.length, "entry point", "entry points")}, ${count(anchors.symbols.length, "symbol", "symbols")}, ${count(anchors.linkedTests.length, "linked test", "linked tests")}`;
+    switch (outcome.status) {
+        case "current":
+            return `already anchored: ${name}${shape}`;
+        case "anchored":
+            return `anchored${outcome.again === true ? " again" : ""}: ${name}${shape}`;
+        case "seeded":
+            return `anchored from its behavior map: ${name}${shape}`;
+        case "stale":
+            return `not anchored again: ${name}; some of its anchored code is gone, and what is left is used${outcome.reason ? ` (${outcome.reason})` : ""}`;
+        default:
+            return `not anchored: ${name}: ${outcome.reason ?? outcome.status}`;
+    }
+}
+/** `balladeer anchor`, from arguments already parsed. */
+export async function runAnchor(options) {
+    const { args } = options;
+    const deps = options.deps ?? {};
+    const now = deps.now ?? (() => new Date());
+    const fail = (reason, message) => {
+        if (args.json) {
+            const step = { step: "error", reason, message, changed: false, exitCode: 4 };
+            options.write(`${JSON.stringify(step)}\n`);
+        }
+        else
+            options.error(`${message}\n`);
+        return 4;
+    };
+    const root = args.repo !== undefined ? resolve(options.cwd, args.repo) : await repositoryRoot(options.cwd);
+    if (root === undefined)
+        return fail("not_a_repository", "This is not a git repository, so there is nothing to anchor.");
+    const head = await resolveCommit(root, "HEAD");
+    if (head === undefined)
+        return fail("no_head", "This repository has no commit yet, so there is nothing to anchor.");
+    const connection = {
+        environment: options.environment,
+        controlPlane: args.controlPlane,
+        cwd: root,
+        ...(args.repository === undefined ? {} : { repository: args.repository }),
+    };
+    let client = deps.client;
+    if (client === undefined) {
+        const found = connectionAnchorsClient(connection);
+        if (!found.ok)
+            return fail("no_connection", `There is no Balladeer connection for this repository on this laptop, so nothing was anchored: ${found.reason}`);
+        client = found.client;
+    }
+    let reader = deps.reader;
+    if (reader === undefined) {
+        const found = connectionReader(connection);
+        if (found.ok)
+            reader = found.reader;
+    }
+    let login;
+    const stage = await anchorStage({
+        root,
+        head,
+        environment: options.environment,
+        maps: readBehaviorMaps(join(root, BEHAVIOR_MAP_DIRECTORY)),
+        client,
+        reader,
+        login: () => (login ??= (deps.resolveLogin ??
+            ((requested) => resolveClient(requested, { env: options.environment, cwd: root })))(args.client)),
+        now,
+        ...(args.promiseId === undefined
+            ? {}
+            : { force: new Set([args.promiseId]), only: new Set([args.promiseId]) }),
+        ...(deps.runAgent === undefined ? {} : { runAgent: deps.runAgent }),
+        ...(deps.graph === undefined ? {} : { graph: deps.graph }),
+        ...(deps.scratch === undefined ? {} : { scratch: deps.scratch }),
+    });
+    if (!stage.available)
+        return fail("anchors_unavailable", `Nothing was anchored: ${stage.reason}.`);
+    if (args.promiseId !== undefined && !stage.promises.some((p) => p.promiseId === args.promiseId))
+        return fail("not_agreed_here", `${args.promiseId} is not an agreed promise of this repository, so it was not anchored.`);
+    const outcomes = (stage.run?.outcomes ?? []).filter((outcome) => args.promiseId === undefined || outcome.promiseId === args.promiseId);
+    const anchors = stage.run?.anchors ?? new Map();
+    if (args.json) {
+        for (const outcome of outcomes)
+            options.write(`${JSON.stringify({
+                step: "anchor",
+                promiseId: outcome.promiseId,
+                status: outcome.status,
+                ...(outcome.reason === undefined ? {} : { reason: outcome.reason }),
+                ...(outcome.recorded === undefined ? {} : { recorded: outcome.recorded }),
+                ...(anchors.has(outcome.promiseId) ? { anchors: anchors.get(outcome.promiseId) } : {}),
+            })}\n`);
+    }
+    else {
+        if (stage.promises.length === 0)
+            options.write("This repository has no agreed promise yet, so there is nothing to anchor.\n");
+        for (const outcome of outcomes)
+            options.write(`${describeOutcome(outcome, anchors.get(outcome.promiseId))}\n`);
+        if (stage.run !== undefined)
+            for (const line of anchoringLines(stage.run, { push: false }))
+                options.write(`${line}\n`);
+    }
+    const unanchored = outcomes.filter((outcome) => !["current", "anchored", "seeded"].includes(outcome.status));
+    return unanchored.length > 0 ? 1 : 0;
+}
+export async function anchorCommand(argv, io) {
+    let args;
+    try {
+        args = parseAnchorArguments(argv);
+    }
+    catch (error) {
+        io.error(`${error instanceof Error ? error.message : String(error)}\n\n${ANCHOR_USAGE}`);
+        return 4;
+    }
+    return runAnchor({ args, ...io });
+}

package/dist/commands/judge.d.ts

@@ -1,9 +1,13 @@
+import type { AnchorBudget } from "../anchor-budget.js";
+import type { AnchorsClient } from "../anchors-client.js";
 import { type BehaviorMap } from "../behavior-map-schema.js";
 import { type HeadlessAgentOptions, type HeadlessAgentResult, type HeadlessClient, type LoginCheck } from "../headless-agent.js";
 import { type HookHost, type MergeTarget } from "../judge-hook.js";
 import { type PromiseDocument, type PromiseReader } from "../promise-meaning.js";
+import type { RepositoryGraph } from "../risk/graph-cache.js";
 import { type CarriedFile } from "../scratch-worktree.js";
 import type { Features } from "../risk/contract.js";
+import type { AnchorStage, JudgeAnchors } from "./anchor.js";
 /**
  * `balladeer judge`: for a change about to leave this machine, ask the person's
  * own coding agent, one promise at a time, whether the change keeps it.
@@ -109,6 +113,8 @@ export type JudgeVerdict = {
     };
     briefRevision: string;
     mapUsed: boolean;
+    /** The judge was handed the promise's anchors and their neighborhood, where it had no map. */
+    anchorsUsed?: boolean;
     linkedTestRun: {
         file: string;
         outcome: "pass" | "fail" | "error" | "none";
@@ -213,10 +219,13 @@ type JudgeAnswer = Readonly<{
 export declare const NEXT_STEP_LIMIT = 500;
 /** The judge's final JSON, read strictly enough that a malformed answer is not a verdict. */
 export declare function readJudgeAnswer(json: Record<string, unknown> | undefined): JudgeAnswer | undefined;
+export type { JudgeAnchors } from "./anchor.js";
 export type JudgePromiseInput = Readonly<{
     root: string;
     promise: PromiseDocument;
     map?: BehaviorMap;
+    /** Handed only when there is no map. */
+    anchors?: JudgeAnchors;
     base: string;
     head: string;
     changedFiles: readonly string[];
@@ -265,7 +274,7 @@ export type JudgeArguments = Readonly<{
     repository?: string;
     controlPlane: string;
 }>;
-export declare const JUDGE_USAGE = "  npx -y balladeer@latest judge [--promises <id,id>] [--top <k>] [--base <ref>] [--head <ref>]\n                  [--report-only | --block] [--wait] [--json] [--client auto|claude|codex]\n                  [--from-file <promise.json> [--map <map.json>]]\n                  [--hook claude|codex|git] [--install-hook [claude|codex|git]]\n                  [--push-check on|off]\n      Judge whether this change keeps the promises it could break, one promise\n      at a time, on your own Claude Code or Codex login. A break counts only\n      with a command that fails with the change and passes without it, and\n      this command runs it both ways itself; anything unproven is \"could not\n      tell\". Report mode prints one line per promise and never stops anything;\n      --block exits 2 on a reproduced break, and when judges are still running\n      at the time limit it holds the push rather than letting it through.\n      --wait runs without the time limit. Promises come from --promises, else\n      from `balladeer risk`: every promise whose own code or tests the\n      change edits, or with \"select\": \"ranked\" in .continuity/judge.json the\n      top of its ranking and a small random sample; else every mapped\n      promise; plus that file's alwaysJudge. Verdicts are kept in\n      .continuity/judge-log/, which git ignores. --install-hook adds the push\n      hook to .claude/settings.json and .codex/hooks.json, before and after\n      each shell command: report mode judges after a push has landed, so the\n      push never waits, and block mode judges before it. With git it writes\n      .git/hooks/pre-push, which judges before the push in both modes. With\n      \"offers\": true in .continuity/judge.json, the push hook also reads the\n      change for rules no promise records and offers at most three to\n      whoever is pushing; it records nothing and never holds a push (see\n      `balladeer offers`). Setup also writes the same pair of entries at\n      each host's user scope, running `judge --hook <host> --user-scope`,\n      so the check runs in every connected repository with mapped promises\n      and says nothing anywhere else; a checkout with its own entry keeps\n      the check to that entry. --push-check off turns the user-scope check\n      off on this laptop, and --push-check on turns it back on.\n";
+export declare const JUDGE_USAGE = "  npx -y balladeer@latest judge [--promises <id,id>] [--top <k>] [--base <ref>] [--head <ref>]\n                  [--report-only | --block] [--wait] [--json] [--client auto|claude|codex]\n                  [--from-file <promise.json> [--map <map.json>]]\n                  [--hook claude|codex|git] [--install-hook [claude|codex|git]]\n                  [--push-check on|off]\n      Judge whether this change keeps the promises it could break, one promise\n      at a time, on your own Claude Code or Codex login. A break counts only\n      with a command that fails with the change and passes without it, and\n      this command runs it both ways itself; anything unproven is \"could not\n      tell\". Report mode prints one line per promise and never stops anything;\n      --block exits 2 on a reproduced break, and when judges are still running\n      at the time limit it holds the push rather than letting it through.\n      --wait runs without the time limit. Promises come from --promises, else\n      every agreed promise whose anchored code the change edits, and every\n      promise with a behavior map whose own code or tests it edits (with\n      \"select\": \"ranked\" in .continuity/judge.json, the top of the maps'\n      ranking and a small random sample); plus that file's alwaysJudge. A\n      promise with no anchors yet is anchored first, by one small call on\n      your own login (see `balladeer anchor`), at most 20 a day on this\n      laptop, and a line says what that cost. Verdicts are kept in\n      .continuity/judge-log/, which git ignores. --install-hook adds the push\n      hook to .claude/settings.json and .codex/hooks.json, before and after\n      each shell command: report mode judges after a push has landed, so the\n      push never waits, and block mode judges before it. With git it writes\n      .git/hooks/pre-push, which judges before the push in both modes. With\n      \"offers\": true in .continuity/judge.json, the push hook also reads the\n      change for rules no promise records and offers at most three to\n      whoever is pushing; it records nothing and never holds a push (see\n      `balladeer offers`). Setup also writes the same pair of entries at\n      each host's user scope, running `judge --hook <host> --user-scope`,\n      so the check runs in every connected repository with agreed promises\n      and says nothing anywhere else; a checkout with its own entry keeps\n      the check to that entry. --push-check off turns the user-scope check\n      off on this laptop, and --push-check on turns it back on.\n";
 export declare function parseJudgeArguments(argv: readonly string[]): JudgeArguments;
 /**
  * The subset of `balladeer-risk/v1` this command reads: enough to order the
@@ -290,28 +299,39 @@ export declare function defaultBase(root: string, head: string): Promise<string
 export declare function changedFiles(root: string, base: string, head: string): Promise<string[]>;
 export type Selection = Readonly<{
     promiseId: string;
-    why: "file" | "named" | "risk" | "sample" | "mapped" | "always";
+    why: "file" | "named" | "risk" | "anchored" | "sample" | "mapped" | "always";
 }>;
 /**
- * Which promises to judge: named ones, else from the risk report, else every
- * mapped promise; then `alwaysJudge`.
+ * Which promises to judge: named ones; else the promises the change selects
+ * by their anchors and by their maps; then `alwaysJudge`.
  *
- * From the risk report, in the order `balladeer risk` lists it (how directly
- * the change reaches each promise, then score, then evidence, then id; a score
- * alone ties at 1 and falls to the alphabet):
+ * By anchors (`anchored`, chosen before this from the files the change edits):
+ * every promise one of whose anchor files (an entry point's or a symbol's
+ * file) the change edits, with no widening by import distance. The
+ * measurement of 1 October 2026 found that widening multiplied the promises
+ * selected and caught nothing more.
  *
- * - "direct" takes every promise whose own code or tests the change edits
- *   (directness tier 3), and nothing else. The first live evaluation found
- *   that this selects about 1.8 promises a change and included the broken one
- *   in 17 of 17 cases. Only a `--top` given by hand caps it.
- * - "ranked" takes the top k with a score above zero, plus a random sample
- *   below that line. The sample is what keeps a ranking honest: a break found
- *   below the line is a miss the ranking made, counted rather than never seen.
+ * By maps, from the risk report, in the order `balladeer risk` lists it (how
+ * directly the change reaches each promise, then score, then evidence, then
+ * id; a score alone ties at 1 and falls to the alphabet):
+ *
+ * - "direct" takes every mapped promise whose own code or tests the change
+ *   edits (directness tier 3), and nothing else. Only a `--top` given by hand
+ *   caps it, and it caps anchored and mapped promises together.
+ * - "ranked" takes the top k mapped promises with a score above zero, plus a
+ *   random sample below that line. The sample is what keeps a ranking honest:
+ *   a break found below the line is a miss the ranking made, counted rather
+ *   than never seen. Anchored promises are taken too, before the sample.
+ *
+ * Without a risk report, every mapped promise. Anchored and mapped promises
+ * are listed together in the report's order, and one the report does not
+ * list comes after those it does.
  */
 export declare function selectPromises(input: Readonly<{
     named?: readonly string[];
     risk?: readonly RiskEntry[];
     mapped: readonly string[];
+    anchored?: readonly string[];
     config: JudgeConfig;
     topK?: number;
     random: () => number;
@@ -364,9 +384,19 @@ export declare function verdictLine(verdict: JudgeVerdict, title: string, contex
 export type JudgeDependencies = Readonly<{
     runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
     resolveLogin?: (requested: HeadlessClient | "auto", prefer?: HeadlessClient) => Promise<LoginCheck | undefined>;
-    riskReport?: (root: string, base: string, head: string) => Promise<readonly RiskEntry[] | undefined>;
+    riskReport?: (root: string, base: string, head: string, 
+    /** The maps in use and, in a map's shape, the anchors of the promises they select. */
+    maps: readonly BehaviorMap[]) => Promise<readonly RiskEntry[] | undefined>;
     /** `null` means "no connection", without trying to find one. */
     reader?: PromiseReader | null;
+    /** The anchors route; `null` means none, without trying to find one. */
+    anchors?: AnchorsClient | null;
+    /** The anchoring call, when it is not the person's own agent. */
+    anchorAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+    /** The repository graph at a commit, when it is not built from this laptop's cache. */
+    graph?: (root: string, head: string) => RepositoryGraph;
+    /** Today's anchoring budget, when it is not this laptop's own. */
+    anchorBudget?: AnchorBudget;
     random?: () => number;
     now?: () => Date;
     stdin?: () => Promise<string>;
@@ -394,17 +424,22 @@ export type JudgeRunOptions = Readonly<{
 }>;
 /** What `--push-check off` and `--push-check on` say. */
 export declare const PUSH_CHECK_OFF_LINE = "The push check is off on this laptop: after a push it now says nothing, in every repository. A repository's own entry from `balladeer judge --install-hook` still runs. Turn it back on with `balladeer judge --push-check on`.";
-export declare const PUSH_CHECK_ON_LINE = "The push check is back on for this laptop: after a push in a connected repository whose promises have behavior maps, it reports what the push may have broken, and it never holds the push.";
+export declare const PUSH_CHECK_ON_LINE = "The push check is back on for this laptop: after a push in a connected repository with agreed promises, it reports what the push may have broken, and it never holds the push.";
 /**
  * Whether the push check's user-scope entry has this push to itself, decided
  * before anything is started or fetched: the entry runs on every shell command
  * in every folder on the laptop, and most folders have nothing to judge. It
  * stands aside, saying nothing, when the laptop turned the check off, the
- * folder is in no checkout, the checkout has the push check's own project
+ * folder is in no checkout, or the checkout has the push check's own project
  * entry for this host (that entry owns the check there, so a push is judged
- * once), or no promise here has a behavior map. Only then is the connection
- * looked for, which reads the checkout's remotes, and a checkout this laptop
- * has not connected is left alone too.
+ * once). Only then is the connection looked for, which reads the checkout's
+ * remotes, and a checkout this laptop has not connected is left alone too.
+ *
+ * A connected checkout is not left alone for having no behavior map: since
+ * promise anchors (approved 30 September 2026), its agreed promises are
+ * anchored and checked without one. Whether it has any agreed promise is the
+ * server's to say, after the push, and with none (and no map) the entry still
+ * says nothing.
  */
 export declare function userScopeTakesThePush(input: {
     cwd: string;
@@ -412,6 +447,20 @@ export declare function userScopeTakesThePush(input: {
     environment: NodeJS.ProcessEnv;
     connected: (root: string) => boolean;
 }): boolean;
+/**
+ * The one line said when nothing was selected, and its code: no agreed
+ * promise here; nothing anchored or mapped (with why, when the anchors could
+ * not be read); or nothing the change touches.
+ */
+export declare function nothingSelected(input: Readonly<{
+    stage: AnchorStage | undefined;
+    maps: number;
+    anchors: number;
+    push: boolean;
+}>): {
+    reason: string;
+    message: string;
+};
 /** `balladeer judge`, from arguments already parsed. */
 /**
  * The line an answer opens with when the command makes a commit before it
@@ -427,4 +476,3 @@ export declare function judgeCommand(argv: readonly string[], io: Readonly<{
     write: (text: string) => void;
     error: (text: string) => void;
 }>): Promise<number>;
-export {};