balladeer 1.0.16 → 1.0.18

package/dist/anchor-budget.d.ts

@@ -0,0 +1,40 @@
+/**
+ * How many anchoring calls this laptop may still start today, kept in
+ * Balladeer's config home.
+ *
+ * Every anchoring call runs on the person's own subscription, so the push
+ * check spends at most this many a day, whatever the repository: 20 by
+ * default, or `BALLADEER_ANCHOR_DAILY_BUDGET` (a whole number from 0 to 500)
+ * when the person sets it. A call counts when it starts, so a call that ran
+ * into its cap or failed has still been spent. The day is the laptop's own
+ * calendar day.
+ *
+ * The same file remembers which promises a call already came back empty or
+ * capped for today, so a promise nothing on the list realizes is not asked
+ * about again on every push. It never leaves the laptop.
+ */
+export declare const ANCHOR_BUDGET_FILE = "anchor-budget.json";
+export declare const DEFAULT_DAILY_ANCHORINGS = 20;
+export declare const ANCHOR_BUDGET_VARIABLE = "BALLADEER_ANCHOR_DAILY_BUDGET";
+export type AnchorBudget = Readonly<{
+    /** Calls allowed a day on this laptop. */
+    limit: number;
+    /** Calls still allowed today. */
+    remaining(): number;
+    /** Take one call from today's budget, or say there is none left. */
+    take(): boolean;
+    /** Whether a call for this promise and meaning already came back empty or capped today. */
+    settledToday(key: string): "empty" | "capped" | undefined;
+    /** Remember that today's call for this promise and meaning came back empty or capped. */
+    settle(key: string, outcome: "empty" | "capped"): void;
+}>;
+/** The laptop's own calendar day, as YYYY-MM-DD. */
+export declare function localDay(now: Date): string;
+/** The daily limit: the person's setting when it is a whole number from 0 to 500, else 20. */
+export declare function dailyAnchorLimit(environment: NodeJS.ProcessEnv): number;
+export declare function anchorBudgetPath(environment: NodeJS.ProcessEnv): string;
+/**
+ * This laptop's budget for today. Each change is read from and written back to
+ * the file at once, so two pushes in two repositories share one budget.
+ */
+export declare function anchorBudget(environment: NodeJS.ProcessEnv, now: () => Date): AnchorBudget;

package/dist/anchor-budget.js

@@ -0,0 +1,110 @@
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { configHome } from "./store.js";
+/**
+ * How many anchoring calls this laptop may still start today, kept in
+ * Balladeer's config home.
+ *
+ * Every anchoring call runs on the person's own subscription, so the push
+ * check spends at most this many a day, whatever the repository: 20 by
+ * default, or `BALLADEER_ANCHOR_DAILY_BUDGET` (a whole number from 0 to 500)
+ * when the person sets it. A call counts when it starts, so a call that ran
+ * into its cap or failed has still been spent. The day is the laptop's own
+ * calendar day.
+ *
+ * The same file remembers which promises a call already came back empty or
+ * capped for today, so a promise nothing on the list realizes is not asked
+ * about again on every push. It never leaves the laptop.
+ */
+export const ANCHOR_BUDGET_FILE = "anchor-budget.json";
+export const DEFAULT_DAILY_ANCHORINGS = 20;
+export const ANCHOR_BUDGET_VARIABLE = "BALLADEER_ANCHOR_DAILY_BUDGET";
+/** The laptop's own calendar day, as YYYY-MM-DD. */
+export function localDay(now) {
+    const pad = (value) => String(value).padStart(2, "0");
+    return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+/** The daily limit: the person's setting when it is a whole number from 0 to 500, else 20. */
+export function dailyAnchorLimit(environment) {
+    const raw = environment[ANCHOR_BUDGET_VARIABLE]?.trim();
+    if (raw === undefined || raw === "")
+        return DEFAULT_DAILY_ANCHORINGS;
+    const value = Number(raw);
+    return Number.isInteger(value) && value >= 0 && value <= 500 ? value : DEFAULT_DAILY_ANCHORINGS;
+}
+export function anchorBudgetPath(environment) {
+    return join(configHome(environment), ANCHOR_BUDGET_FILE);
+}
+function read(path, day) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed?.day === day &&
+            typeof parsed.used === "number" &&
+            Number.isInteger(parsed.used) &&
+            parsed.used >= 0) {
+            const settled = {};
+            if (parsed.settled !== null && typeof parsed.settled === "object")
+                for (const [key, value] of Object.entries(parsed.settled))
+                    if (value === "empty" || value === "capped")
+                        settled[key] = value;
+            return { day, used: parsed.used, settled };
+        }
+    }
+    catch {
+        /* Missing or unreadable: a new day. */
+    }
+    return { day, used: 0, settled: {} };
+}
+function write(path, value) {
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        const temporary = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+        try {
+            writeFileSync(temporary, `${JSON.stringify(value)}\n`, { flag: "wx", mode: 0o600 });
+            renameSync(temporary, path);
+        }
+        finally {
+            try {
+                unlinkSync(temporary);
+            }
+            catch {
+                /* Renamed, or never written. */
+            }
+        }
+    }
+    catch {
+        /* A budget that cannot be written is spent in memory only, for this run. */
+    }
+}
+/**
+ * This laptop's budget for today. Each change is read from and written back to
+ * the file at once, so two pushes in two repositories share one budget.
+ */
+export function anchorBudget(environment, now) {
+    const path = anchorBudgetPath(environment);
+    const limit = dailyAnchorLimit(environment);
+    // What this run spent, in case the file cannot be written: never fewer than that.
+    let spent = { day: "", used: 0 };
+    const current = () => {
+        const state = read(path, localDay(now()));
+        return spent.day === state.day ? { ...state, used: Math.max(state.used, spent.used) } : state;
+    };
+    return {
+        limit,
+        remaining: () => Math.max(0, limit - current().used),
+        take: () => {
+            const state = current();
+            if (state.used >= limit)
+                return false;
+            spent = { day: state.day, used: state.used + 1 };
+            write(path, { ...state, used: state.used + 1 });
+            return true;
+        },
+        settledToday: (key) => current().settled[key],
+        settle: (key, outcome) => {
+            const state = current();
+            write(path, { ...state, settled: { ...state.settled, [key]: outcome } });
+        },
+    };
+}

package/dist/anchoring.d.ts

@@ -0,0 +1,241 @@
+import type { AnchorBudget } from "./anchor-budget.js";
+import { type AnchorEntryPoint, type AnchorSymbol, type PromiseAnchors } from "./anchors-schema.js";
+import type { AnchoredPromise, 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 { PromiseMeaning, PromiseReader } from "./promise-meaning.js";
+import { type ExportedName, type RepositoryGraph } from "./risk/graph-cache.js";
+import type { ImportGraph } from "./risk/import-graph.js";
+import { type Idf } from "./risk/text.js";
+/**
+ * Promise anchors on the laptop: where an agreed promise's behavior lives,
+ * written by one small call on the person's own Claude Code or Codex, or cut
+ * from a behavior map, and shared through the server with every teammate.
+ *
+ * The call is `anchor-brief/v3`, frozen on 1 October 2026 after the
+ * measurement in `docs/agentic-testing/evidence/20261001/anchors-measurement.md`.
+ * The index, the shortlist and the brief below are
+ * `scripts/agentic-eval/anchors-fresh.ts` at v3, word for word. They were tuned
+ * on the seventeen in-window cases, so any change to them is a new revision
+ * with a label of its own, measured before it ships; never edit v3 in place.
+ */
+export declare const ANCHOR_BRIEF_REVISION = "anchor-brief/v3";
+/**
+ * Each anchoring call's caps. The measured calls wrote at most 1,157 output
+ * tokens and took at most 9.3 seconds; one runaway call in 291 wrote 128,690.
+ * A call that reaches either cap leaves its promise unanchored.
+ */
+export declare const ANCHOR_CALL_CAPS: {
+    readonly outputTokens: 8000;
+    readonly wallMs: 60000;
+};
+export type IndexEntry = Readonly<{
+    file: string;
+    names: readonly ExportedName[];
+    words: ReadonlySet<string>;
+}>;
+export type AnchorIndex = Readonly<{
+    sha: string;
+    entries: readonly IndexEntry[];
+    idf: Idf;
+}>;
+/** Every non-test source file the graph knows, with the top-level names it exports. */
+export declare function anchorIndex(repository: RepositoryGraph): AnchorIndex;
+type BriefExample = {
+    label?: string;
+    setup?: string;
+    expectedOutcome?: string;
+};
+type BriefMeaning = {
+    title: string;
+    observableOutcome: string;
+    passingExamples: BriefExample[];
+    failingExamples: BriefExample[];
+    nonGoals: string[];
+};
+/**
+ * The promise as the measured brief showed it: title, outcome, the cases'
+ * label, setup and outcome, and the non-goals. Nothing else of the meaning is
+ * read, so what the model sees is what was measured.
+ */
+export declare function briefMeaning(meaning: PromiseMeaning): BriefMeaning;
+/** The files whose path and names share the most weighted words with the promise. */
+export declare function shortlist(index: AnchorIndex, meaning: BriefMeaning): IndexEntry[];
+/** `anchor-brief/v3`, word for word. */
+export declare function anchorBrief(meaning: BriefMeaning, candidates: readonly IndexEntry[]): string;
+/**
+ * The first complete JSON value in a model's answer, fenced or bare, as the
+ * measurement read it. Undefined when there is none.
+ */
+export declare function firstJsonValue(answer: string): unknown;
+export type Picks = Readonly<{
+    entryPoints: AnchorEntryPoint[];
+    symbols: AnchorSymbol[];
+    /** What the model named that was not kept, as `entry file#name` or `symbol file#name`. */
+    dropped: string[];
+}>;
+/**
+ * What the model picked, kept only when its file is on the shortlist and its
+ * name is declared or exported in that file, and only when both pass the data
+ * boundary. Anything else is dropped. The measurement kept any name in a
+ * listed file; a name the file does not declare would read as gone on the next
+ * push, so it is dropped here instead (2 of the 1,268 measured picks).
+ */
+export declare function readPicks(raw: unknown, candidates: readonly IndexEntry[], declared: (file: string) => ReadonlySet<string> | undefined): Picks;
+/** Linked tests, from the graph: test files that import an anchor file directly. */
+export declare function linkedTestsFor(graph: ImportGraph, files: Iterable<string>): {
+    file: string;
+}[];
+/**
+ * Files one import step from the anchor files, either way: what they import
+ * and what imports them, tests left out (linked tests are listed apart). This
+ * is the judge's neighborhood: where to look next if the behavior reaches
+ * further than the anchors.
+ */
+export declare function neighborhood(graph: ImportGraph, files: readonly string[], limit?: number): string[];
+/**
+ * Anchors cut from a behavior map, with no model: its entry points, its core
+ * symbols, its resources and its linked tests, each kept only when it passes
+ * the data boundary, up to the contract's limits. A map's notes are not
+ * carried. Undefined when nothing anchorable is left.
+ */
+export declare function seedFromMap(map: BehaviorMap, at: Date): PromiseAnchors | undefined;
+export type GoneCheck = Readonly<{
+    /** The anchors with every gone entry point, symbol and linked test taken out. */
+    surviving: PromiseAnchors;
+    /** What has gone, as `file#name` or a linked test's file. */
+    gone: readonly string[];
+}>;
+/**
+ * Which anchors have gone at a commit, read off the graph with no model: an
+ * entry point or symbol whose file is not in the tree, or whose name its file
+ * no longer declares. A file the graph does not read (another language, from a
+ * map) is checked for being there only.
+ */
+export declare function goneAnchors(anchors: PromiseAnchors, repository: RepositoryGraph): GoneCheck;
+export type AnchorCall = Readonly<{
+    status: "anchored";
+    anchors: PromiseAnchors;
+    tokens: number;
+    dropped: readonly string[];
+    ms: number;
+}> | Readonly<{
+    status: "empty";
+    tokens: number;
+    dropped: readonly string[];
+}> | Readonly<{
+    status: "capped" | "failed" | "stopped";
+    reason: string;
+    tokens: number;
+}>;
+/**
+ * One promise anchored by one headless call: no tools, in an empty folder,
+ * with an output-token cap and a time limit. Only picks from the shortlist are
+ * kept, linked tests come from the graph, and the result is checked against
+ * the data boundary before anyone sees it.
+ */
+export declare function anchorWithCall(input: Readonly<{
+    promiseId: string;
+    semanticDigest: string;
+    meaning: PromiseMeaning;
+    repository: RepositoryGraph;
+    index: AnchorIndex;
+    login: LoginCheck;
+    environment: NodeJS.ProcessEnv;
+    now: () => Date;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    scratch?: string;
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+}>): Promise<AnchorCall>;
+/** The model name as the contract carries it, or `unknown` when the run did not say. */
+export declare function anchorModelName(model: string | undefined): string;
+export type AnchorStatus = 
+/** Its current anchors stand, all of them still in the code. */
+"current"
+/** Anchored now by a call. */
+ | "anchored"
+/** Anchored now from its behavior map, with no call. */
+ | "seeded"
+/** Some of its anchors have gone and it was not anchored again; judged on what is left. */
+ | "stale" | "budget" | "capped" | "failed" | "empty"
+/** A call came back empty or capped earlier today, so it was not asked again. */
+ | "settled" | "no_login" | "unreadable"
+/** The push check ran out of time before its turn. */
+ | "time";
+export type AnchorOutcome = Readonly<{
+    promiseId: string;
+    title: string;
+    status: AnchorStatus;
+    /** Anchored again because code it was anchored to had gone. */
+    again?: boolean;
+    /** For anchored, seeded: whether the server kept them. Absent when not sent. */
+    recorded?: boolean;
+    recordReason?: string;
+    reason?: string;
+    tokens?: number;
+}>;
+export type AnchorRun = Readonly<{
+    /** Each promise's anchors to judge on now: current, fresh, or what is left of stale ones. */
+    anchors: ReadonlyMap<string, PromiseAnchors>;
+    /**
+     * Each promise's anchor files to select it by: those of its anchors as
+     * Balladeer kept them, gone ones included, and those of any fresh ones. A
+     * change that deletes or moves an anchor file edits it, so the promise is
+     * selected even though that anchor has gone at the change's head.
+     */
+    selectBy: ReadonlyMap<string, readonly string[]>;
+    outcomes: readonly AnchorOutcome[];
+    /** Tokens the calls spent. */
+    tokens: number;
+    client?: HeadlessClient;
+    budget: AnchorBudget;
+}>;
+export type AnchorRunInput = Readonly<{
+    promises: readonly AnchoredPromise[];
+    /** Promise ids to anchor anew whatever they have now (`balladeer anchor <promise>`). */
+    force?: ReadonlySet<string>;
+    /** Only these promises are anchored when given; the others keep what they have. */
+    only?: ReadonlySet<string>;
+    /** Each promise's behavior map when this checkout has one for its current meaning. */
+    currentMaps: ReadonlyMap<string, BehaviorMap>;
+    repository: RepositoryGraph;
+    client: AnchorsClient;
+    reader: PromiseReader | undefined;
+    login: () => Promise<LoginCheck | undefined>;
+    budget: AnchorBudget;
+    environment: NodeJS.ProcessEnv;
+    now: () => Date;
+    /** No new call starts after this instant (milliseconds since the epoch). */
+    deadline?: number;
+    signal?: AbortSignal;
+    concurrency?: number;
+    scratch?: string;
+    /** A key for this repository, so "came back empty today" is remembered per repository. */
+    repositoryKey: string;
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+}>;
+/**
+ * Every agreed promise brought to current anchors as far as today's budget
+ * and the time allow: kept when current, cut from a current map with no model,
+ * else anchored by a call; anchors whose code has gone are anchored again, and
+ * judged on what is left of them meanwhile. A promise left unanchored says why.
+ */
+export declare function bringAnchorsCurrent(input: AnchorRunInput): Promise<AnchorRun>;
+/**
+ * What anchoring did, in at most four lines a person reads in one go: what
+ * was anchored and what it cost with what is left of today's budget; what was
+ * left unanchored, so not checked, and why; what is checked on part of its
+ * anchors; and anchors not shared with the team. Nothing when anchoring had
+ * nothing to do.
+ *
+ * From the push check (`push`), a promise left unanchored that the push
+ * selected anyway (by an anchor file it moved or deleted) is not listed as
+ * unchecked, because it was judged; from `balladeer anchor` there is no push,
+ * and the lines say what the push check can do instead.
+ */
+export declare function anchoringLines(run: AnchorRun, context?: Readonly<{
+    push: boolean;
+    judged?: ReadonlySet<string>;
+}>): string[];
+export {};