balladeer 1.0.15 → 1.0.16

package/README.md

@@ -206,6 +206,8 @@ your own branch protection.
 | `npx -y balladeer@latest discover`     | File a whole catalog, up to ten promises from one file, behind one review link   |
 | `npx -y balladeer@latest touch-map`    | Record which files each promise's verifier runs, on this machine only            |
 | `npx -y balladeer@latest affected`     | Say which promises the files you name touch, out of that record                  |
+| `npx -y balladeer@latest risk`         | Rank the promises a change could put at risk, on this machine only               |
+| `npx -y balladeer@latest offers`       | Read a change for up to three rules no promise records, and record nothing       |
 | `npx -y balladeer@latest session`      | Print the id for this piece of work, and the line to write into the commit       |
 | `npx -y balladeer@latest mcp`          | Forward one MCP session over stdio using this repository's connection            |
 | `npx -y balladeer@latest explain`      | What Balladeer can and cannot see, where to watch it, and what leaving costs     |

package/dist/behavior-map-schema.d.ts

@@ -0,0 +1,107 @@
+/**
+ * `balladeer-behavior-map/v1`, as `docs/agentic-testing/contracts.md` spells it.
+ *
+ * Written without a schema library on purpose. The published command carries
+ * exactly one reviewed runtime dependency (`tests/packaging/cli-package.test.ts`
+ * holds it there), so the shape is checked by hand here, with the field names
+ * copied from the contract. It is the one reader of maps: `balladeer map` writes
+ * through it and the risk ranking (`risk/`) reads through it, so a field added
+ * here reaches both, and `tests/risk/contract.test.ts` round-trips a full map.
+ */
+export declare const BEHAVIOR_MAP_SCHEMA_VERSION = "balladeer-behavior-map/v1";
+export declare const BEHAVIOR_MAP_DIRECTORY = ".continuity/behavior-maps";
+export declare const ENTRY_POINT_KINDS: readonly ["route", "command", "ui", "job", "event", "function"];
+export declare const SYMBOL_KINDS: readonly ["function", "class", "method", "const", "type", "module"];
+export declare const SYMBOL_ROLES: readonly ["core", "supporting"];
+export declare const RESOURCE_KINDS: readonly ["table", "column", "route", "flag", "env", "queue", "event", "outbound", "file", "config"];
+export declare const RESOURCE_ACCESS: readonly ["read", "write", "both", "call"];
+/** Positions in the agreed meaning: `passing-1`, `failing-2`, `refactor-1`. */
+export declare const CASE_ID: RegExp;
+export type BehaviorMapEntryPoint = {
+    file: string;
+    symbol: string;
+    kind: (typeof ENTRY_POINT_KINDS)[number];
+    note: string;
+};
+export type BehaviorMapSymbol = {
+    file: string;
+    name: string;
+    kind: (typeof SYMBOL_KINDS)[number];
+    role: (typeof SYMBOL_ROLES)[number];
+};
+export type BehaviorMapResource = {
+    kind: (typeof RESOURCE_KINDS)[number];
+    name: string;
+    access: (typeof RESOURCE_ACCESS)[number];
+};
+export type BehaviorMapLinkedTest = {
+    file: string;
+    name: string;
+    cases: string[];
+};
+export type BehaviorMapSink = {
+    caseId: string;
+    effect: string;
+    resources: string[];
+    /** `file#symbol`. */
+    symbols: string[];
+};
+/**
+ * The part of the agreed meaning a scorer needs without asking the server:
+ * the contract addendum of 28 September. `surfaces` is the promise's own scope
+ * surfaces, which the scope-only baseline reads.
+ */
+export type BehaviorMapMeaning = {
+    title: string;
+    observableOutcome: string;
+    failingExamples: {
+        id: string;
+        text: string;
+    }[];
+    nonGoals: string[];
+    surfaces?: string[];
+};
+export type BehaviorMap = {
+    schemaVersion: typeof BEHAVIOR_MAP_SCHEMA_VERSION;
+    promiseId: string;
+    semanticDigest: string;
+    mappedAt: {
+        sha: string;
+        at: string;
+        client: "claude" | "codex";
+        model: string;
+    };
+    entryPoints: BehaviorMapEntryPoint[];
+    symbols: BehaviorMapSymbol[];
+    resources: BehaviorMapResource[];
+    linkedTests: BehaviorMapLinkedTest[];
+    sinks: BehaviorMapSink[];
+    confidence: number;
+    notes: string;
+    meaning?: BehaviorMapMeaning;
+};
+/** Ceilings, so a map stays a small file a person can read in a review. */
+export declare const MAP_LIMITS: {
+    readonly entryPoints: 20;
+    readonly symbols: 60;
+    readonly resources: 40;
+    readonly linkedTests: 20;
+    readonly sinks: 20;
+    readonly text: 2000;
+    readonly name: 400;
+};
+export type ParseResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    errors: string[];
+};
+/** Promise ids: `prom_` ids from Balladeer, and the evaluation harness's own ids. */
+export declare const PROMISE_ID: RegExp;
+/** A whole map, checked against the contract. Unknown fields are refused. */
+export declare function parseBehaviorMap(value: unknown): ParseResult<BehaviorMap>;
+/** Every file a map names: the derived `files` field, which is never stored. */
+export declare function mapFiles(map: BehaviorMap): string[];
+/** The map as it is written to disk: two-space JSON and a final newline. */
+export declare function serializeBehaviorMap(map: BehaviorMap): string;

package/dist/behavior-map-schema.js

@@ -0,0 +1,232 @@
+/**
+ * `balladeer-behavior-map/v1`, as `docs/agentic-testing/contracts.md` spells it.
+ *
+ * Written without a schema library on purpose. The published command carries
+ * exactly one reviewed runtime dependency (`tests/packaging/cli-package.test.ts`
+ * holds it there), so the shape is checked by hand here, with the field names
+ * copied from the contract. It is the one reader of maps: `balladeer map` writes
+ * through it and the risk ranking (`risk/`) reads through it, so a field added
+ * here reaches both, and `tests/risk/contract.test.ts` round-trips a full map.
+ */
+export const BEHAVIOR_MAP_SCHEMA_VERSION = "balladeer-behavior-map/v1";
+export const BEHAVIOR_MAP_DIRECTORY = ".continuity/behavior-maps";
+export const ENTRY_POINT_KINDS = ["route", "command", "ui", "job", "event", "function"];
+export const SYMBOL_KINDS = ["function", "class", "method", "const", "type", "module"];
+export const SYMBOL_ROLES = ["core", "supporting"];
+export const RESOURCE_KINDS = [
+    "table",
+    "column",
+    "route",
+    "flag",
+    "env",
+    "queue",
+    "event",
+    "outbound",
+    "file",
+    "config",
+];
+export const RESOURCE_ACCESS = ["read", "write", "both", "call"];
+/** Positions in the agreed meaning: `passing-1`, `failing-2`, `refactor-1`. */
+export const CASE_ID = /^(passing|failing|refactor)-[1-9][0-9]{0,2}$/;
+/** Ceilings, so a map stays a small file a person can read in a review. */
+export const MAP_LIMITS = {
+    entryPoints: 20,
+    symbols: 60,
+    resources: 40,
+    linkedTests: 20,
+    sinks: 20,
+    text: 2000,
+    name: 400,
+};
+const text = (max, allowEmpty = true) => (value, at, errors) => {
+    if (typeof value !== "string") {
+        errors.push(`${at} must be a string`);
+        return undefined;
+    }
+    if (!allowEmpty && value.trim() === "") {
+        errors.push(`${at} must not be empty`);
+        return undefined;
+    }
+    if (value.length > max) {
+        errors.push(`${at} is longer than ${max} characters`);
+        return undefined;
+    }
+    return value;
+};
+const oneOf = (values) => (value, at, errors) => {
+    if (typeof value === "string" && values.includes(value))
+        return value;
+    errors.push(`${at} must be one of ${values.join(", ")}`);
+    return undefined;
+};
+/** Repository-relative, forward slashes, inside the repository. */
+const repositoryPath = (value, at, errors) => {
+    const path = text(MAP_LIMITS.name, false)(value, at, errors);
+    if (path === undefined)
+        return undefined;
+    if (path.startsWith("/") ||
+        path.includes("\\") ||
+        /^[A-Za-z]:/.test(path) ||
+        path.split("/").some((part) => part === "..")) {
+        errors.push(`${at} must be a repository-relative path with forward slashes`);
+        return undefined;
+    }
+    return path;
+};
+const listOf = (item, max) => (value, at, errors) => {
+    if (!Array.isArray(value)) {
+        errors.push(`${at} must be a list`);
+        return undefined;
+    }
+    if (value.length > max) {
+        errors.push(`${at} has more than ${max} entries`);
+        return undefined;
+    }
+    const out = [];
+    let failed = false;
+    value.forEach((entry, index) => {
+        const checked = item(entry, `${at}[${index}]`, errors);
+        if (checked === undefined)
+            failed = true;
+        else
+            out.push(checked);
+    });
+    return failed ? undefined : out;
+};
+const record = (fields, optional = []) => (value, at, errors) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        errors.push(`${at} must be an object`);
+        return undefined;
+    }
+    const input = value;
+    const unknown = Object.keys(input).filter((key) => !(key in fields));
+    if (unknown.length > 0) {
+        errors.push(`${at} has fields the contract does not define: ${unknown.join(", ")}`);
+        return undefined;
+    }
+    const out = {};
+    let failed = false;
+    for (const key of Object.keys(fields)) {
+        if (!(key in input) || input[key] === undefined) {
+            if (optional.includes(key))
+                continue;
+            errors.push(`${at}.${key} is missing`);
+            failed = true;
+            continue;
+        }
+        const checked = fields[key](input[key], `${at}.${key}`, errors);
+        if (checked === undefined)
+            failed = true;
+        else
+            out[key] = checked;
+    }
+    return failed ? undefined : out;
+};
+const caseId = (value, at, errors) => {
+    if (typeof value === "string" && CASE_ID.test(value))
+        return value;
+    errors.push(`${at} must be a case id such as passing-1 or failing-2`);
+    return undefined;
+};
+const fileSymbol = (value, at, errors) => {
+    const reference = text(MAP_LIMITS.name, false)(value, at, errors);
+    if (reference === undefined)
+        return undefined;
+    const hash = reference.indexOf("#");
+    if (hash <= 0 || hash === reference.length - 1) {
+        errors.push(`${at} must be file#symbol`);
+        return undefined;
+    }
+    return repositoryPath(reference.slice(0, hash), at, errors) === undefined ? undefined : reference;
+};
+const confidence = (value, at, errors) => {
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1)
+        return value;
+    errors.push(`${at} must be a number from 0 to 1`);
+    return undefined;
+};
+const SHA = /^[0-9a-f]{40}$/;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+/** Promise ids: `prom_` ids from Balladeer, and the evaluation harness's own ids. */
+export const PROMISE_ID = /^[A-Za-z0-9_.-]{1,128}$/;
+const pattern = (regex, description) => (value, at, errors) => {
+    if (typeof value === "string" && regex.test(value))
+        return value;
+    errors.push(`${at} must be ${description}`);
+    return undefined;
+};
+const isoInstant = (value, at, errors) => {
+    if (typeof value === "string" && !Number.isNaN(Date.parse(value)))
+        return value;
+    errors.push(`${at} must be an ISO timestamp`);
+    return undefined;
+};
+const meaningChecker = record({
+    title: text(MAP_LIMITS.text, false),
+    observableOutcome: text(16_000, false),
+    failingExamples: listOf(record({ id: caseId, text: text(8000, false) }), MAP_LIMITS.sinks),
+    nonGoals: listOf(text(MAP_LIMITS.text), 40),
+    surfaces: listOf(text(MAP_LIMITS.name, false), 40),
+}, ["surfaces"]);
+const mapChecker = record({
+    schemaVersion: oneOf([BEHAVIOR_MAP_SCHEMA_VERSION]),
+    promiseId: pattern(PROMISE_ID, "a promise id"),
+    semanticDigest: pattern(DIGEST, "sha256: followed by 64 hex characters"),
+    mappedAt: record({
+        sha: pattern(SHA, "a 40-character commit sha"),
+        at: isoInstant,
+        client: oneOf(["claude", "codex"]),
+        model: text(MAP_LIMITS.name),
+    }),
+    entryPoints: listOf(record({
+        file: repositoryPath,
+        symbol: text(MAP_LIMITS.name, false),
+        kind: oneOf(ENTRY_POINT_KINDS),
+        note: text(MAP_LIMITS.text),
+    }), MAP_LIMITS.entryPoints),
+    symbols: listOf(record({
+        file: repositoryPath,
+        name: text(MAP_LIMITS.name, false),
+        kind: oneOf(SYMBOL_KINDS),
+        role: oneOf(SYMBOL_ROLES),
+    }), MAP_LIMITS.symbols),
+    resources: listOf(record({
+        kind: oneOf(RESOURCE_KINDS),
+        name: text(MAP_LIMITS.name, false),
+        access: oneOf(RESOURCE_ACCESS),
+    }), MAP_LIMITS.resources),
+    linkedTests: listOf(record({
+        file: repositoryPath,
+        name: text(MAP_LIMITS.name),
+        cases: listOf(caseId, 40),
+    }), MAP_LIMITS.linkedTests),
+    sinks: listOf(record({
+        caseId,
+        effect: text(MAP_LIMITS.text, false),
+        resources: listOf(text(MAP_LIMITS.name, false), 20),
+        symbols: listOf(fileSymbol, 20),
+    }), MAP_LIMITS.sinks),
+    confidence,
+    notes: text(MAP_LIMITS.text),
+    meaning: meaningChecker,
+}, ["meaning"]);
+/** A whole map, checked against the contract. Unknown fields are refused. */
+export function parseBehaviorMap(value) {
+    const errors = [];
+    const map = mapChecker(value, "map", errors);
+    return map === undefined ? { ok: false, errors } : { ok: true, value: map };
+}
+/** Every file a map names: the derived `files` field, which is never stored. */
+export function mapFiles(map) {
+    return [
+        ...new Set([
+            ...map.entryPoints.map((entry) => entry.file),
+            ...map.symbols.map((entry) => entry.file),
+            ...map.linkedTests.map((entry) => entry.file),
+        ]),
+    ].sort();
+}
+/** The map as it is written to disk: two-space JSON and a final newline. */
+export function serializeBehaviorMap(map) {
+    return `${JSON.stringify(map, null, 2)}\n`;
+}

package/dist/cli.d.ts

@@ -45,6 +45,11 @@ type Parsed = Readonly<{
     again: boolean;
     /** `check-seals --runner`: where the pinned runner is, when it has moved. */
     runner: string | undefined;
+    /** `risk --base` and `--head`: the two ends of the change. */
+    base: string | undefined;
+    head: string | undefined;
+    /** `risk --maps`: where the behavior maps are, when not in the checkout. */
+    maps: string | undefined;
     createWorkspace: string | undefined;
     /** Everything that was not a flag: the addresses `invite` sends to. */
     positional: readonly string[];

package/dist/cli.js

@@ -9,10 +9,14 @@ import { runDiscover } from "./commands/discover.js";
 import { runExplain } from "./commands/explain.js";
 import { parseRole, runInvite } from "./commands/invite.js";
 import { runGuidance } from "./commands/guidance.js";
+import { JUDGE_USAGE, judgeCommand } from "./commands/judge.js";
+import { MAP_USAGE, mapCommand } from "./commands/map.js";
+import { OFFERS_USAGE, offersCommand } from "./commands/offers.js";
 import { runMcp } from "./commands/mcp.js";
 import { runPrepare } from "./commands/prepare.js";
 import { runPropose } from "./commands/propose.js";
 import { runRepositories } from "./commands/repositories.js";
+import { runRisk } from "./commands/risk.js";
 import { CREATE_WORKSPACE_MAX_LENGTH, runSetup } from "./commands/setup.js";
 import { runSession } from "./commands/session.js";
 import { runStatus } from "./commands/status.js";
@@ -155,6 +159,17 @@ const USAGE = `balladeer ${CLI_VERSION}
       answer whose verifier has changed since the map was built. It reads one
       local file and contacts nothing.
 
+${MAP_USAGE}
+${JUDGE_USAGE}
+${OFFERS_USAGE}
+  ${CLI_INVOCATION} risk [--base <ref>] [--head <ref>] [--json] [--maps <dir>]
+      Rank the promises this change could put at risk, with the evidence for
+      each: a mapped function or test it changes, a table, route or file it
+      shares, what imports what, and what its commit messages say. It reads
+      the behavior maps in .continuity/behavior-maps/ and the change from git,
+      from the merge base with this branch's upstream (else origin/main) to
+      HEAD unless named. Runs offline; nothing is sent. --json prints the report.
+
   ${CLI_INVOCATION} session [--new] [--record] [--repo owner/name] [--repository <uuid>] [--json]
                     [--control-plane <url>]
       Print the id for this piece of work, and the one line to write into the
@@ -211,6 +226,9 @@ export function parseArguments(argv) {
     let record = false;
     let again = false;
     let runner;
+    let base;
+    let head;
+    let maps;
     let controlPlane;
     let repo;
     let file;
@@ -229,6 +247,9 @@ export function parseArguments(argv) {
         "--role": "contributor, viewer, or administrator",
         "--client": "codex or claude",
         "--runner": "a path to the pinned runner's cli.js",
+        "--base": "a git ref",
+        "--head": "a git ref",
+        "--maps": "a directory of behavior maps",
     };
     const value = (flag, inline) => {
         const next = inline ?? args.shift();
@@ -270,6 +291,12 @@ export function parseArguments(argv) {
             record = true;
         else if (name === "--runner")
             runner = value("--runner", inline);
+        else if (name === "--base")
+            base = value("--base", inline);
+        else if (name === "--head")
+            head = value("--head", inline);
+        else if (name === "--maps")
+            maps = value("--maps", inline);
         else if (name === "--wait")
             wait = true;
         else if (name === "--no-open")
@@ -380,6 +407,8 @@ export function parseArguments(argv) {
     }
     if (hook !== undefined && command !== "guidance")
         throw new StoreError("usage", "--hook belongs to guidance.");
+    if ((base !== undefined || head !== undefined || maps !== undefined) && command !== "risk")
+        throw new StoreError("usage", "--base, --head and --maps belong to risk.");
     if (event !== undefined && command !== "guidance")
         throw new StoreError("usage", "--event belongs to guidance.");
     const chosen = controlPlane ?? process.env.BALLADEER_CONTROL_PLANE?.trim() ?? DEFAULT_CONTROL_PLANE;
@@ -407,6 +436,9 @@ export function parseArguments(argv) {
         record,
         again,
         runner,
+        base,
+        head,
+        maps,
         createWorkspace,
         positional,
         role,
@@ -414,6 +446,20 @@ export function parseArguments(argv) {
     };
 }
 export async function main(argv) {
+    // `map`, `judge` and `offers` read their own flags: `--hook`, `--repo` and
+    // `--install-hook` mean something different there, and `judge --hook` runs
+    // inside a coding host where a stderr nag would reach the agent.
+    if (argv[0] === "map" || argv[0] === "judge" || argv[0] === "offers") {
+        const io = {
+            cwd: process.cwd(),
+            environment: process.env,
+            write: (text) => void process.stdout.write(text),
+            error: (text) => void process.stderr.write(text),
+        };
+        if (argv[0] === "offers")
+            return offersCommand(argv.slice(1), io);
+        return argv[0] === "map" ? mapCommand(argv.slice(1), io) : judgeCommand(argv.slice(1), io);
+    }
     let parsed;
     try {
         parsed = parseArguments(argv);
@@ -654,6 +700,15 @@ async function dispatch(parsed, write) {
                 cwd: process.cwd(),
                 write,
             });
+        case "risk":
+            return runRisk({
+                json: parsed.json,
+                ...(parsed.base === undefined ? {} : { base: parsed.base }),
+                ...(parsed.head === undefined ? {} : { head: parsed.head }),
+                ...(parsed.maps === undefined ? {} : { maps: parsed.maps }),
+                cwd: process.cwd(),
+                write,
+            });
         case "affected":
             return runAffected({
                 json: parsed.json,