balladeer 1.0.14 → 1.0.16

package/dist/promise-meaning.d.ts

@@ -0,0 +1,126 @@
+import { type BehaviorMapMeaning } from "./behavior-map-schema.js";
+/**
+ * One promise's agreed meaning, the way the map builder and the judge read it.
+ *
+ * It comes from one of two places. With this repository's agent connection it
+ * is `get_promise`'s own answer. Without one, it is a file holding that same
+ * shape, which is how the evaluation harness hands over promises it wrote for
+ * public repositories that have never heard of Balladeer. A sealed package's
+ * `promise` object is accepted too, because it carries the same meaning under
+ * slightly different keys and this repository's own promises live that way.
+ */
+export type PromiseExample = Readonly<{
+    label: string;
+    setup: string;
+    expectedOutcome: string;
+    saidWords?: string;
+}>;
+export type PromiseMeaning = Readonly<{
+    title: string;
+    observableOutcome: string;
+    nonGoals: readonly string[];
+    passingExamples: readonly PromiseExample[];
+    failingExamples: readonly PromiseExample[];
+    refactorExamples?: readonly PromiseExample[];
+    scope?: Readonly<{
+        surfaces?: readonly string[];
+        labels?: readonly string[];
+    }>;
+    [field: string]: unknown;
+}>;
+export type PromiseDocument = Readonly<{
+    promiseId: string;
+    title: string;
+    semanticDigest: string;
+    meaning: PromiseMeaning;
+}>;
+/** Deterministic JSON with sorted keys, the form Balladeer digests a meaning in. */
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256Digest(value: unknown): string;
+/**
+ * The promise a file or a tool answer describes, or the reason it describes
+ * none. The meaning is kept whole, every field as it came, because the judge is
+ * handed it verbatim; only the fields this command reads are checked.
+ */
+export declare function normalizePromise(value: unknown): {
+    ok: true;
+    promise: PromiseDocument;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function readPromiseFile(path: string): {
+    ok: true;
+    promise: PromiseDocument;
+} | {
+    ok: false;
+    reason: string;
+};
+/** One failing case as a sentence, which is what the scorer compares a change against. */
+export declare function exampleText(example: PromiseExample): string;
+/** The excerpt a map carries so the scorer never needs the server. */
+export declare function meaningExcerpt(promise: PromiseDocument): BehaviorMapMeaning;
+/**
+ * A promise rebuilt from a map's excerpt, for a judge that has no connection
+ * and no file. It carries no passing cases, and the judge brief says so.
+ */
+export declare function promiseFromExcerpt(promiseId: string, semanticDigest: string, excerpt: BehaviorMapMeaning): PromiseDocument;
+/** Case ids in the order the meaning lists them. */
+export declare function caseIds(promise: PromiseDocument): {
+    passing: string[];
+    failing: string[];
+    refactor: string[];
+};
+export type PromiseReader = Readonly<{
+    get(promiseId: string): Promise<{
+        ok: true;
+        promise: PromiseDocument;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /**
+     * Every agreed promise's id, page after page. With `max`, at most that many,
+     * and `more` says whether the index held further ids beyond them.
+     */
+    list(options?: Readonly<{
+        max?: number;
+    }>): Promise<{
+        ok: true;
+        ids: string[];
+        more?: boolean;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+}>;
+/**
+ * What to tell a person when the server refuses the unattended read because it
+ * is older than this command, or nothing when the refusal is about anything
+ * else.
+ *
+ * The command reaches people before the server that understands it can: a
+ * server that has never heard of `unattended` refuses the whole read, and its
+ * own words for that are about a key nobody typed. The read is never retried
+ * without the field, because a read that counts as the person having seen the
+ * promise would silence what they are still to be told about it. So the person
+ * is told what happened and what works meanwhile.
+ */
+export declare function olderServerRefusal(text: string): string | undefined;
+/**
+ * This repository's agent connection as a reader of promises, or the reason
+ * there is none. Reading is all it does: `get_promise` and `list_promises`,
+ * the same two reads an agent in this repository makes.
+ */
+export declare function connectionReader(input: Readonly<{
+    environment: NodeJS.ProcessEnv;
+    controlPlane: string;
+    cwd: string;
+    repository?: string;
+}>): {
+    ok: true;
+    reader: PromiseReader;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/promise-meaning.js

@@ -0,0 +1,292 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { callAgentTool, selectAgent } from "./agent.js";
+import { PROMISE_ID } from "./behavior-map-schema.js";
+import { repositoryHints } from "./repository.js";
+import { readCredentials } from "./store.js";
+/** Deterministic JSON with sorted keys, the form Balladeer digests a meaning in. */
+export function canonicalJson(value) {
+    const canonical = (item) => {
+        if (Array.isArray(item))
+            return item.map(canonical);
+        if (item !== null && typeof item === "object") {
+            const out = {};
+            for (const key of Object.keys(item).sort()) {
+                const child = item[key];
+                if (child !== undefined)
+                    out[key] = canonical(child);
+            }
+            return out;
+        }
+        return item;
+    };
+    return JSON.stringify(canonical(value));
+}
+export function sha256Digest(value) {
+    return `sha256:${createHash("sha256").update(canonicalJson(value), "utf8").digest("hex")}`;
+}
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+function examples(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = [];
+    for (const entry of value) {
+        if (entry === null || typeof entry !== "object")
+            return undefined;
+        const row = entry;
+        if (typeof row.setup !== "string" || typeof row.expectedOutcome !== "string")
+            return undefined;
+        out.push({
+            label: typeof row.label === "string" ? row.label : "",
+            setup: row.setup,
+            expectedOutcome: row.expectedOutcome,
+            ...(typeof row.saidWords === "string" ? { saidWords: row.saidWords } : {}),
+        });
+    }
+    return out;
+}
+/**
+ * The promise a file or a tool answer describes, or the reason it describes
+ * none. The meaning is kept whole, every field as it came, because the judge is
+ * handed it verbatim; only the fields this command reads are checked.
+ */
+export function normalizePromise(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return { ok: false, reason: "it is not a JSON object" };
+    const input = value;
+    if (input.found === false)
+        return {
+            ok: false,
+            reason: typeof input.reason === "string" ? input.reason : "Balladeer has no such promise",
+        };
+    let promiseId;
+    let digest;
+    let meaning;
+    const packaged = input.promise;
+    if (packaged !== null &&
+        typeof packaged === "object" &&
+        !Array.isArray(packaged) &&
+        input.meaning === undefined) {
+        // A sealed package: the meaning's fields sit beside the id, owner and digest.
+        const rest = { ...packaged };
+        promiseId = rest.id;
+        digest = rest.semanticDigest;
+        delete rest.id;
+        delete rest.ownerId;
+        delete rest.semanticDigest;
+        meaning = rest;
+    }
+    else {
+        if (input.meaning === null || typeof input.meaning !== "object" || Array.isArray(input.meaning))
+            return { ok: false, reason: "it carries no meaning object" };
+        promiseId = input.promiseId ?? input.id;
+        digest = input.semanticDigest;
+        meaning = input.meaning;
+    }
+    if (typeof promiseId !== "string" || !PROMISE_ID.test(promiseId))
+        return { ok: false, reason: "it names no usable promise id" };
+    const passing = examples(meaning.passingExamples);
+    const failing = examples(meaning.failingExamples);
+    if (typeof meaning.title !== "string" || meaning.title.trim() === "")
+        return { ok: false, reason: "its meaning has no title" };
+    if (typeof meaning.observableOutcome !== "string")
+        return { ok: false, reason: "its meaning has no observable outcome" };
+    if (passing === undefined || failing === undefined)
+        return { ok: false, reason: "its meaning's passing and failing cases are unreadable" };
+    const nonGoals = Array.isArray(meaning.nonGoals)
+        ? meaning.nonGoals.filter((goal) => typeof goal === "string")
+        : [];
+    const semanticDigest = typeof digest === "string" && DIGEST.test(digest) ? digest : sha256Digest(meaning);
+    const title = typeof input.title === "string" && input.title.trim() !== "" ? input.title : meaning.title;
+    const refactor = examples(meaning.refactorExamples);
+    return {
+        ok: true,
+        promise: {
+            promiseId,
+            title,
+            semanticDigest,
+            meaning: {
+                ...meaning,
+                title: meaning.title,
+                observableOutcome: meaning.observableOutcome,
+                nonGoals,
+                passingExamples: passing,
+                failingExamples: failing,
+                ...(refactor === undefined ? {} : { refactorExamples: refactor }),
+            },
+        },
+    };
+}
+export function readPromiseFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `${path} could not be read: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: `${path} is not JSON` };
+    }
+    const normalized = normalizePromise(value);
+    return normalized.ok
+        ? normalized
+        : { ok: false, reason: `${path} does not hold a promise: ${normalized.reason}` };
+}
+/** One failing case as a sentence, which is what the scorer compares a change against. */
+export function exampleText(example) {
+    const label = example.label.trim();
+    return `${label ? `${label}: ` : ""}${example.setup.trim()} Then: ${example.expectedOutcome.trim()}`;
+}
+/** The excerpt a map carries so the scorer never needs the server. */
+export function meaningExcerpt(promise) {
+    const surfaces = promise.meaning.scope?.surfaces?.filter((surface) => typeof surface === "string" && surface.trim() !== "");
+    return {
+        title: promise.meaning.title,
+        observableOutcome: promise.meaning.observableOutcome,
+        failingExamples: promise.meaning.failingExamples.map((example, index) => ({
+            id: `failing-${index + 1}`,
+            text: exampleText(example),
+        })),
+        nonGoals: [...promise.meaning.nonGoals],
+        ...(surfaces !== undefined && surfaces.length > 0 ? { surfaces } : {}),
+    };
+}
+/**
+ * A promise rebuilt from a map's excerpt, for a judge that has no connection
+ * and no file. It carries no passing cases, and the judge brief says so.
+ */
+export function promiseFromExcerpt(promiseId, semanticDigest, excerpt) {
+    return {
+        promiseId,
+        title: excerpt.title,
+        semanticDigest,
+        meaning: {
+            title: excerpt.title,
+            observableOutcome: excerpt.observableOutcome,
+            nonGoals: excerpt.nonGoals,
+            passingExamples: [],
+            failingExamples: excerpt.failingExamples.map((example) => ({
+                label: example.id,
+                setup: example.text,
+                expectedOutcome: "",
+            })),
+        },
+    };
+}
+/** Case ids in the order the meaning lists them. */
+export function caseIds(promise) {
+    return {
+        passing: promise.meaning.passingExamples.map((_, index) => `passing-${index + 1}`),
+        failing: promise.meaning.failingExamples.map((_, index) => `failing-${index + 1}`),
+        refactor: (promise.meaning.refactorExamples ?? []).map((_, index) => `refactor-${index + 1}`),
+    };
+}
+/** How many index pages one listing reads before it stops and says there was more. */
+const LIST_PAGES = 20;
+/**
+ * What to tell a person when the server refuses the unattended read because it
+ * is older than this command, or nothing when the refusal is about anything
+ * else.
+ *
+ * The command reaches people before the server that understands it can: a
+ * server that has never heard of `unattended` refuses the whole read, and its
+ * own words for that are about a key nobody typed. The read is never retried
+ * without the field, because a read that counts as the person having seen the
+ * promise would silence what they are still to be told about it. So the person
+ * is told what happened and what works meanwhile.
+ */
+export function olderServerRefusal(text) {
+    if (!/\bunattended\b/.test(text) || !/unrecognized|unknown|unexpected|invalid/i.test(text))
+        return undefined;
+    return ("This Balladeer server is older than this command. It cannot yet read a promise for a " +
+        "program without counting that as you having seen it, so nothing was read. This works once " +
+        "the server is updated; until then, hand the promise over as a file with --from-file.");
+}
+/**
+ * This repository's agent connection as a reader of promises, or the reason
+ * there is none. Reading is all it does: `get_promise` and `list_promises`,
+ * the same two reads an agent in this repository makes.
+ */
+export function connectionReader(input) {
+    let agent;
+    try {
+        const credentials = readCredentials(input.environment);
+        const selection = selectAgent(credentials.agents, input.controlPlane, input.repository, repositoryHints(input.cwd));
+        if (selection.kind === "refused")
+            return { ok: false, reason: selection.reason };
+        agent = selection.agent;
+    }
+    catch (error) {
+        return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+    const refusal = (kind) => kind === "unreachable"
+        ? `Balladeer could not be reached at ${input.controlPlane}`
+        : kind === "unauthorized"
+            ? "Balladeer refused this repository's agent connection"
+            : kind === "client_too_old"
+                ? "this copy of the Balladeer command is too old for the server"
+                : "Balladeer could not answer";
+    return {
+        ok: true,
+        reader: {
+            async get(promiseId) {
+                // Unattended: a program reading on the agent's behalf. The server
+                // then leaves the person's "seen" bookkeeping untouched.
+                const call = await callAgentTool(agent, "get_promise", { promiseId, unattended: true });
+                if (call.kind === "tool_refusal")
+                    return { ok: false, reason: olderServerRefusal(call.text) ?? call.text };
+                if (call.kind !== "result")
+                    return { ok: false, reason: refusal(call.kind) };
+                return normalizePromise(call.structured);
+            },
+            async list(options) {
+                const max = options?.max ?? Number.POSITIVE_INFINITY;
+                const ids = [];
+                const seen = new Set();
+                let cursor;
+                let more = false;
+                for (let page = 0;; page += 1) {
+                    if (page >= LIST_PAGES || ids.length >= max) {
+                        // Stopped with the index still offering a next page.
+                        more = cursor !== undefined;
+                        break;
+                    }
+                    const call = await callAgentTool(agent, "list_promises", {
+                        limit: 100,
+                        ...(cursor === undefined ? {} : { cursor }),
+                    });
+                    if (call.kind === "tool_refusal")
+                        return { ok: false, reason: call.text };
+                    if (call.kind !== "result")
+                        return { ok: false, reason: refusal(call.kind) };
+                    const structured = call.structured;
+                    for (const row of Array.isArray(structured.promises) ? structured.promises : []) {
+                        const id = row?.promiseId;
+                        if (typeof id === "string" && PROMISE_ID.test(id) && !seen.has(id)) {
+                            seen.add(id);
+                            ids.push(id);
+                        }
+                    }
+                    const next = structured.nextCursor;
+                    // A cursor handed back unchanged would page the same rows forever.
+                    if (typeof next !== "string" || next === "" || next === cursor) {
+                        cursor = undefined;
+                        break;
+                    }
+                    cursor = next;
+                }
+                if (ids.length > max)
+                    return { ok: true, ids: ids.slice(0, max), more: true };
+                return { ok: true, ids, more };
+            },
+        },
+    };
+}

package/dist/risk/contract.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The change extraction (`balladeer-change-extraction/v1`) and the risk report
+ * (`balladeer-risk/v1`), as `docs/agentic-testing/contracts.md` spells them,
+ * with the additions recorded under "Contract notes" on that page.
+ *
+ * Plain types rather than a schema library: the published command carries one
+ * reviewed runtime dependency and no other. `validate.ts` checks both shapes by
+ * hand, and the behavior map's own shape and checker are in
+ * `../behavior-map-schema.ts`, shared with `balladeer map`.
+ */
+export type { BehaviorMap, BehaviorMapEntryPoint, BehaviorMapLinkedTest, BehaviorMapMeaning, BehaviorMapResource, BehaviorMapSink, BehaviorMapSymbol, } from "../behavior-map-schema.js";
+export declare const CHANGE_EXTRACTION_SCHEMA_VERSION = "balladeer-change-extraction/v1";
+export declare const RISK_REPORT_SCHEMA_VERSION = "balladeer-risk/v1";
+export declare const RESOURCE_KINDS: readonly ["table", "column", "route", "flag", "env", "queue", "event", "outbound", "file", "config"];
+export type ResourceKind = (typeof RESOURCE_KINDS)[number];
+export declare const SYMBOL_KINDS: readonly ["function", "class", "method", "const", "type", "module"];
+export type SymbolKind = (typeof SYMBOL_KINDS)[number];
+export declare const LANGUAGES: readonly ["ts", "tsx", "js", "py", "go", "rb", "java", "kt", "rs", "other"];
+export type Language = (typeof LANGUAGES)[number];
+export type Hunk = {
+    oldStart: number;
+    oldLines: number;
+    newStart: number;
+    newLines: number;
+};
+export declare const SYMBOL_CHANGES: readonly ["added", "modified", "deleted"];
+export type ChangedSymbol = {
+    name: string;
+    kind: SymbolKind;
+    change: (typeof SYMBOL_CHANGES)[number];
+};
+/**
+ * `added`: the file names the resource at head and nowhere at base (new reach).
+ * `removed`: it named it at base and nowhere at head. `touched`: a changed
+ * line, or the body of a changed function, names a resource the file already
+ * named.
+ */
+export declare const RESOURCE_CHANGES: readonly ["added", "removed", "touched"];
+export type ChangedResource = {
+    kind: ResourceKind;
+    name: string;
+    change: (typeof RESOURCE_CHANGES)[number];
+};
+/** Which reader found the symbols: the repository's own TypeScript compiler, or a pattern. */
+export declare const SYMBOL_EXTRACTORS: readonly ["typescript", "regex"];
+export type SymbolExtractor = (typeof SYMBOL_EXTRACTORS)[number];
+export declare const FILE_STATUSES: readonly ["added", "modified", "deleted", "renamed"];
+export type ChangedFile = {
+    path: string;
+    status: (typeof FILE_STATUSES)[number];
+    oldPath: string | null;
+    language: Language;
+    isTest: boolean;
+    hunks: Hunk[];
+    symbolsChanged: ChangedSymbol[];
+    identifiersAdded: string[];
+    identifiersRemoved: string[];
+    resources: ChangedResource[];
+    guardDeletions: {
+        line: number;
+        text: string;
+    }[];
+    constantChanges: {
+        name: string;
+        from: string;
+        to: string;
+    }[];
+    /** Absent when no symbols were read, for a binary or an oversized file. */
+    symbolExtractor?: SymbolExtractor;
+};
+export declare const DELTA_KINDS: readonly ["behavior", "refactor", "removal", "addition", "config", "schema", "test"];
+export type Delta = {
+    text: string;
+    files: string[];
+    kind: (typeof DELTA_KINDS)[number];
+};
+export declare const INTENT_SOURCES: readonly ["description", "commits", "model"];
+export type Intent = {
+    summary: string;
+    source: (typeof INTENT_SOURCES)[number];
+};
+export type ChangeExtraction = {
+    schemaVersion: typeof CHANGE_EXTRACTION_SCHEMA_VERSION;
+    base: string;
+    head: string;
+    files: ChangedFile[];
+    deltas?: Delta[];
+    intent?: Intent;
+};
+export declare const SIGNALS: readonly ["symbol_hit", "graph_forward", "graph_reverse", "resource", "linked_test_changed", "sink_reach", "delta_similarity", "intent_clash", "prior_break", "churn"];
+export type Signal = (typeof SIGNALS)[number];
+export declare const BANDS: readonly ["high", "medium", "low", "none", "unmapped"];
+export type Band = (typeof BANDS)[number];
+/**
+ * The four fields the contract names are always present, empty when they do
+ * not apply. `caseId` and `detail` are additions: the case a sink or a
+ * similarity points at, and a short qualifier such as `deleted`,
+ * `assertion_removed` or `distance:2`.
+ */
+export type Evidence = {
+    file: string;
+    symbol: string;
+    resource: string;
+    delta: string;
+    caseId?: string;
+    detail?: string;
+};
+export type Reason = {
+    signal: Signal;
+    weight: number;
+    evidence: Evidence;
+};
+export type Features = {
+    symbol_hit: number;
+    graph_forward_distance: number | null;
+    graph_reverse_distance: number | null;
+    resource_overlap: number;
+    linked_test_changed: number;
+    sink_reach: number;
+    delta_similarity: number;
+    intent_clash: number;
+    prior_break: number;
+    churn: number;
+};
+export type PromiseRisk = {
+    promiseId: string;
+    title?: string;
+    score: number;
+    band: Band;
+    reasons: Reason[];
+    features: Features;
+};
+export type Baselines = {
+    scope_only: string[];
+    import_closure: string[];
+    all: string[];
+    random: string[];
+};
+export type RiskReport = {
+    schemaVersion: typeof RISK_REPORT_SCHEMA_VERSION;
+    base: string;
+    head: string;
+    promises: PromiseRisk[];
+    baselines: Baselines;
+};

package/dist/risk/contract.js

@@ -0,0 +1,74 @@
+/**
+ * The change extraction (`balladeer-change-extraction/v1`) and the risk report
+ * (`balladeer-risk/v1`), as `docs/agentic-testing/contracts.md` spells them,
+ * with the additions recorded under "Contract notes" on that page.
+ *
+ * Plain types rather than a schema library: the published command carries one
+ * reviewed runtime dependency and no other. `validate.ts` checks both shapes by
+ * hand, and the behavior map's own shape and checker are in
+ * `../behavior-map-schema.ts`, shared with `balladeer map`.
+ */
+export const CHANGE_EXTRACTION_SCHEMA_VERSION = "balladeer-change-extraction/v1";
+export const RISK_REPORT_SCHEMA_VERSION = "balladeer-risk/v1";
+export const RESOURCE_KINDS = [
+    "table",
+    "column",
+    "route",
+    "flag",
+    "env",
+    "queue",
+    "event",
+    "outbound",
+    "file",
+    "config",
+];
+export const SYMBOL_KINDS = ["function", "class", "method", "const", "type", "module"];
+export const LANGUAGES = [
+    "ts",
+    "tsx",
+    "js",
+    "py",
+    "go",
+    "rb",
+    "java",
+    "kt",
+    "rs",
+    "other",
+];
+export const SYMBOL_CHANGES = ["added", "modified", "deleted"];
+/**
+ * `added`: the file names the resource at head and nowhere at base (new reach).
+ * `removed`: it named it at base and nowhere at head. `touched`: a changed
+ * line, or the body of a changed function, names a resource the file already
+ * named.
+ */
+export const RESOURCE_CHANGES = ["added", "removed", "touched"];
+/** Which reader found the symbols: the repository's own TypeScript compiler, or a pattern. */
+export const SYMBOL_EXTRACTORS = ["typescript", "regex"];
+export const FILE_STATUSES = ["added", "modified", "deleted", "renamed"];
+export const DELTA_KINDS = [
+    "behavior",
+    "refactor",
+    "removal",
+    "addition",
+    "config",
+    "schema",
+    "test",
+];
+export const INTENT_SOURCES = ["description", "commits", "model"];
+// ---------------------------------------------------------------------------
+// Risk report (`balladeer-risk/v1`)
+// ---------------------------------------------------------------------------
+export const SIGNALS = [
+    "symbol_hit",
+    "graph_forward",
+    "graph_reverse",
+    "resource",
+    "linked_test_changed",
+    "sink_reach",
+    "delta_similarity",
+    "intent_clash",
+    "prior_break",
+    "churn",
+];
+export const BANDS = ["high", "medium", "low", "none", "unmapped"];

package/dist/risk/describe.d.ts

@@ -0,0 +1,7 @@
+import type { Reason } from "./contract.js";
+/**
+ * One reason as a person reads it: what in the change, and why it matters to
+ * the promise. Evidence only, never a verdict: a reason says where to look, and
+ * a judge says whether the promise still holds.
+ */
+export declare function describeReason(reason: Reason): string;