balladeer 1.0.16 → 1.0.18

package/dist/anchors-client.d.ts

@@ -0,0 +1,62 @@
+import { type PromiseAnchors } from "./anchors-schema.js";
+import type { StoredAgent } from "./store.js";
+/**
+ * `/api/promise-anchors`, reached with this repository's agent connection the
+ * way `/api/agent-guidance` is: the stored bearer, the workspace and
+ * repository in the query, the same origin as the connection. It is not an
+ * MCP tool, so no agent's tool list grows for it.
+ *
+ * `list` reads every agreed promise of the repository with its current
+ * anchors; `record` sends one anchors document, checked against the data
+ * boundary before it leaves the laptop. Neither throws.
+ */
+export declare const PROMISE_ANCHORS_PATH = "/api/promise-anchors";
+export type AnchoredPromise = Readonly<{
+    promiseId: string;
+    semanticDigest: string;
+    title: string;
+    /** The promise's current anchors, or null when it has none for its current meaning. */
+    anchors: PromiseAnchors | null;
+}>;
+export type AnchorsList = Readonly<{
+    ok: true;
+    promises: readonly AnchoredPromise[];
+    /** Anchors the server sent that this command could not accept, each read as none. */
+    refused: number;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+    /** The server answered that it has no such route: an older server. */
+    unsupported?: boolean;
+}>;
+export type AnchorsRecord = Readonly<{
+    ok: true;
+    alreadyRecorded: boolean;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+    status?: number;
+}>;
+export type AnchorsClient = Readonly<{
+    list(): Promise<AnchorsList>;
+    record(anchors: PromiseAnchors): Promise<AnchorsRecord>;
+}>;
+/** The anchors route for one stored connection. */
+export declare function anchorsClientFor(agent: StoredAgent, options?: Readonly<{
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}>): AnchorsClient;
+/** The anchors route for the repository a folder is in, or the reason there is none. */
+export declare function connectionAnchorsClient(input: Readonly<{
+    environment: NodeJS.ProcessEnv;
+    controlPlane: string;
+    cwd: string;
+    repository?: string;
+    fetchImpl?: typeof fetch;
+}>): {
+    ok: true;
+    client: AnchorsClient;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/anchors-client.js

@@ -0,0 +1,197 @@
+import { checkPromiseAnchors, isPromiseAnchorId } from "./anchors-schema.js";
+import { noteServerVersion } from "./currency.js";
+import { agentEndpoint } from "./guidance.js";
+import { connectionAgent } from "./promise-meaning.js";
+import { CLIENT_HEADER, CLIENT_HEADER_VALUE } from "./wire.js";
+/**
+ * `/api/promise-anchors`, reached with this repository's agent connection the
+ * way `/api/agent-guidance` is: the stored bearer, the workspace and
+ * repository in the query, the same origin as the connection. It is not an
+ * MCP tool, so no agent's tool list grows for it.
+ *
+ * `list` reads every agreed promise of the repository with its current
+ * anchors; `record` sends one anchors document, checked against the data
+ * boundary before it leaves the laptop. Neither throws.
+ */
+export const PROMISE_ANCHORS_PATH = "/api/promise-anchors";
+const MAX_LIST_BYTES = 8 * 1024 * 1024;
+const MAX_REPLY_BYTES = 64 * 1024;
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+async function boundedText(response, limit) {
+    const declared = Number(response.headers.get("content-length") ?? 0);
+    if (declared > limit)
+        throw new Error("too_large");
+    const reader = response.body?.getReader();
+    if (!reader)
+        return "";
+    const parts = [];
+    let bytes = 0;
+    try {
+        for (;;) {
+            const part = await reader.read();
+            if (part.done)
+                break;
+            bytes += part.value.byteLength;
+            if (bytes > limit)
+                throw new Error("too_large");
+            parts.push(part.value);
+        }
+        return Buffer.concat(parts).toString("utf8");
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+}
+function refusalReason(status, body) {
+    const message = body !== null &&
+        typeof body === "object" &&
+        typeof body.message === "string"
+        ? body.message.replace(/\s+/g, " ").trim().slice(0, 200)
+        : "";
+    const said = message === "" ? "" : `: ${message}`;
+    if (status === 401 || status === 403)
+        return `Balladeer refused this repository's agent connection${said}`;
+    if (status === 404)
+        return `Balladeer has no agreed, current promise by that id in this repository${said}`;
+    if (status === 409)
+        return `the promise's meaning changed since it was read${said}`;
+    if (status === 413)
+        return "the anchors were larger than Balladeer takes";
+    if (status === 426)
+        return "this copy of the Balladeer command is too old for the server";
+    if (status === 400)
+        return `Balladeer refused the anchors${said}`;
+    return `Balladeer answered ${status}${said}`;
+}
+/** The anchors route for one stored connection. */
+export function anchorsClientFor(agent, options = {}) {
+    const send = async (init, limit) => {
+        let url;
+        try {
+            url = agentEndpoint(agent, PROMISE_ANCHORS_PATH);
+        }
+        catch {
+            return {
+                error: "this repository's stored connection does not name a Balladeer server it can use",
+            };
+        }
+        const abort = new AbortController();
+        const timer = setTimeout(() => abort.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        try {
+            const response = await (options.fetchImpl ?? fetch)(url, {
+                ...init,
+                redirect: "manual",
+                signal: abort.signal,
+                headers: {
+                    authorization: `Bearer ${agent.token}`,
+                    [CLIENT_HEADER]: CLIENT_HEADER_VALUE,
+                    accept: "application/json",
+                    ...(init.body === undefined ? {} : { "content-type": "application/json" }),
+                },
+            });
+            noteServerVersion(response.headers);
+            const text = await boundedText(response, limit);
+            let body;
+            try {
+                body = text === "" ? undefined : JSON.parse(text);
+            }
+            catch {
+                body = undefined;
+            }
+            return { status: response.status, body };
+        }
+        catch (error) {
+            return {
+                error: abort.signal.aborted
+                    ? `Balladeer did not answer within ${Math.round((options.timeoutMs ?? DEFAULT_TIMEOUT_MS) / 1000)} seconds`
+                    : error.message === "too_large"
+                        ? "Balladeer's answer was larger than this command reads"
+                        : `Balladeer could not be reached at ${agent.controlPlane}`,
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    return {
+        async list() {
+            const answer = await send({ method: "GET" }, MAX_LIST_BYTES);
+            if ("error" in answer)
+                return { ok: false, reason: answer.error };
+            if (answer.status === 404 || answer.status === 405)
+                return {
+                    ok: false,
+                    unsupported: true,
+                    reason: "this Balladeer server does not keep promise anchors yet",
+                };
+            if (answer.status !== 200)
+                return { ok: false, reason: refusalReason(answer.status, answer.body) };
+            const rows = answer.body?.promises;
+            if (!Array.isArray(rows))
+                return { ok: false, reason: "Balladeer's answer listed no promises" };
+            const promises = [];
+            let refused = 0;
+            for (const row of rows) {
+                if (row === null || typeof row !== "object")
+                    continue;
+                const { promiseId, semanticDigest, title, anchors } = row;
+                if (!isPromiseAnchorId(promiseId))
+                    continue;
+                if (typeof semanticDigest !== "string" || !DIGEST.test(semanticDigest))
+                    continue;
+                let current = null;
+                if (anchors !== null && anchors !== undefined) {
+                    const checked = checkPromiseAnchors(anchors);
+                    // Anchors for another promise or an older meaning are not this promise's current ones.
+                    if (checked.ok &&
+                        checked.value.promiseId === promiseId &&
+                        checked.value.semanticDigest === semanticDigest)
+                        current = checked.value;
+                    else
+                        refused += 1;
+                }
+                promises.push({
+                    promiseId,
+                    semanticDigest,
+                    title: typeof title === "string" && title.trim() !== ""
+                        ? title.trim().slice(0, 200)
+                        : promiseId,
+                    anchors: current,
+                });
+            }
+            return { ok: true, promises, refused };
+        },
+        async record(anchors) {
+            const checked = checkPromiseAnchors(anchors);
+            if (!checked.ok)
+                return {
+                    ok: false,
+                    reason: `not sent, because they fail the data boundary: ${checked.problems.slice(0, 3).join("; ")}`,
+                };
+            const answer = await send({ method: "POST", body: JSON.stringify(checked.value) }, MAX_REPLY_BYTES);
+            if ("error" in answer)
+                return { ok: false, reason: answer.error };
+            if (answer.status === 200 || answer.status === 201)
+                return {
+                    ok: true,
+                    alreadyRecorded: answer.body?.alreadyRecorded === true,
+                };
+            return {
+                ok: false,
+                status: answer.status,
+                reason: refusalReason(answer.status, answer.body),
+            };
+        },
+    };
+}
+/** The anchors route for the repository a folder is in, or the reason there is none. */
+export function connectionAnchorsClient(input) {
+    const found = connectionAgent(input);
+    if (!found.ok)
+        return found;
+    return {
+        ok: true,
+        client: anchorsClientFor(found.agent, input.fetchImpl === undefined ? {} : { fetchImpl: input.fetchImpl }),
+    };
+}

package/dist/anchors-schema.d.ts

@@ -0,0 +1,85 @@
+import { type BehaviorMapEntryPoint, type BehaviorMapResource, type BehaviorMapSymbol } from "./behavior-map-schema.js";
+/**
+ * `balladeer-promise-anchors/v1`, as `docs/agentic-testing/anchors.md` spells
+ * it: where an agreed promise's behavior lives in a repository, as paths and
+ * names only.
+ *
+ * This is the command's own check of the data boundary, run before anything is
+ * sent. The server runs the same rules and refuses anything else, so a document
+ * this refuses would be refused there too; checking here means a refusal is
+ * explained on the laptop, and nothing that is not a path or a name ever leaves
+ * it. Each rule is its own named check below, so a test can show that every one
+ * of them is load-bearing.
+ */
+export declare const PROMISE_ANCHORS_SCHEMA_VERSION = "balladeer-promise-anchors/v1";
+export declare const ANCHOR_BRIEF_SOURCE = "anchor-brief/v3";
+export declare const BEHAVIOR_MAP_SOURCE = "behavior-map";
+export declare const ANCHOR_SOURCES: readonly ["anchor-brief/v3", "behavior-map"];
+export type AnchorSource = (typeof ANCHOR_SOURCES)[number];
+export declare const ANCHOR_LIMITS: {
+    readonly entryPoints: 12;
+    readonly symbols: 24;
+    readonly resources: 20;
+    readonly linkedTests: 20;
+    readonly path: 400;
+    readonly name: 200;
+};
+export type AnchorEntryPoint = Readonly<Omit<BehaviorMapEntryPoint, "note">>;
+export type AnchorSymbol = Readonly<Omit<BehaviorMapSymbol, "role">>;
+export type AnchorResource = Readonly<BehaviorMapResource>;
+export type AnchorLinkedTest = Readonly<{
+    file: string;
+}>;
+export type PromiseAnchors = Readonly<{
+    schemaVersion: typeof PROMISE_ANCHORS_SCHEMA_VERSION;
+    promiseId: string;
+    semanticDigest: string;
+    anchoredAt: Readonly<{
+        sha: string;
+        at: string;
+        source: AnchorSource;
+        client: "claude" | "codex" | null;
+        model: string | null;
+    }>;
+    entryPoints: readonly AnchorEntryPoint[];
+    symbols: readonly AnchorSymbol[];
+    resources: readonly AnchorResource[];
+    linkedTests: readonly AnchorLinkedTest[];
+}>;
+export type AnchorsCheck = Readonly<{
+    ok: true;
+    value: PromiseAnchors;
+}> | Readonly<{
+    ok: false;
+    problems: readonly string[];
+}>;
+/** Every pattern rule by name, for the parity test against the server's copy. */
+export declare const ANCHOR_RULES: {
+    readonly promiseId: RegExp;
+    readonly digest: RegExp;
+    readonly sha: RegExp;
+    readonly instant: RegExp;
+    readonly model: RegExp;
+    readonly pathCharacters: RegExp;
+    readonly pathSpacing: RegExp;
+    readonly symbolName: RegExp;
+    readonly resourceWhitespace: RegExp;
+    readonly resourceQuotes: RegExp;
+    readonly resourcePunctuation: RegExp;
+    readonly controlCharacters: RegExp;
+};
+/** A repository-relative path with forward slashes, inside the repository, at most 400 characters. */
+export declare function isAnchorPath(value: unknown): value is string;
+/** An identifier, optionally dotted, at most 200 characters. */
+export declare function isAnchorSymbol(value: unknown): value is string;
+/** A table, route, flag or other resource name: no whitespace, quotes or code punctuation. */
+export declare function isAnchorResourceName(value: unknown): value is string;
+export declare function isPromiseAnchorId(value: unknown): value is string;
+/**
+ * A whole anchors document, checked against the contract and the data
+ * boundary. Problems name the field and the rule, never the value, so a
+ * refusal never repeats what it refused.
+ */
+export declare function checkPromiseAnchors(value: unknown): AnchorsCheck;
+/** The files a promise is selected by: its entry points' and its symbols' files. */
+export declare function anchorFiles(anchors: PromiseAnchors): string[];

package/dist/anchors-schema.js

@@ -0,0 +1,246 @@
+import { ENTRY_POINT_KINDS, RESOURCE_ACCESS, RESOURCE_KINDS, SYMBOL_KINDS, } from "./behavior-map-schema.js";
+/**
+ * `balladeer-promise-anchors/v1`, as `docs/agentic-testing/anchors.md` spells
+ * it: where an agreed promise's behavior lives in a repository, as paths and
+ * names only.
+ *
+ * This is the command's own check of the data boundary, run before anything is
+ * sent. The server runs the same rules and refuses anything else, so a document
+ * this refuses would be refused there too; checking here means a refusal is
+ * explained on the laptop, and nothing that is not a path or a name ever leaves
+ * it. Each rule is its own named check below, so a test can show that every one
+ * of them is load-bearing.
+ */
+export const PROMISE_ANCHORS_SCHEMA_VERSION = "balladeer-promise-anchors/v1";
+export const ANCHOR_BRIEF_SOURCE = "anchor-brief/v3";
+export const BEHAVIOR_MAP_SOURCE = "behavior-map";
+export const ANCHOR_SOURCES = [ANCHOR_BRIEF_SOURCE, BEHAVIOR_MAP_SOURCE];
+export const ANCHOR_LIMITS = {
+    entryPoints: 12,
+    symbols: 24,
+    resources: 20,
+    linkedTests: 20,
+    path: 400,
+    name: 200,
+};
+// The rules, written exactly as the server writes them
+// (`packages/service/src/promise-anchors.ts`); `tests/cli/anchors-parity.test.ts`
+// holds the two copies to the same text and the same answers.
+/** `prom_` ids as Balladeer issues them. */
+const PROMISE_ID_RULE = /^prom_[a-z0-9]{8,64}$/;
+const DIGEST_RULE = /^sha256:[0-9a-f]{64}$/;
+const SHA_RULE = /^[0-9a-f]{40}$/;
+const INSTANT_RULE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+const MODEL_RULE = /^[A-Za-z0-9][A-Za-z0-9._:/@+[\]-]{0,127}$/;
+/** The characters file paths use: letters, digits, `_ - . / @ ( ) [ ] + ~ $` and spaces. */
+const PATH_CHARACTERS_RULE = /^[A-Za-z0-9_\-./@()[\]+~$ ]+$/;
+/** Spaces only one at a time, and only between other characters. */
+const PATH_SPACING_RULE = /^ | {2}| $/;
+/** An identifier, optionally dotted (`Class.method`). */
+const SYMBOL_RULE = /^[A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)*$/;
+/** What a resource name may not hold: whitespace, quotes, backticks, `;`, `=`, `<`, `>`. */
+const RESOURCE_WHITESPACE_RULE = /\s/;
+const RESOURCE_QUOTE_RULE = /['"`]/;
+const RESOURCE_PUNCTUATION_RULE = /[;=<>]/;
+const RESOURCE_CONTROL_RULE = /[\u0000-\u001f\u007f]/;
+/** Every pattern rule by name, for the parity test against the server's copy. */
+export const ANCHOR_RULES = {
+    promiseId: PROMISE_ID_RULE,
+    digest: DIGEST_RULE,
+    sha: SHA_RULE,
+    instant: INSTANT_RULE,
+    model: MODEL_RULE,
+    pathCharacters: PATH_CHARACTERS_RULE,
+    pathSpacing: PATH_SPACING_RULE,
+    symbolName: SYMBOL_RULE,
+    resourceWhitespace: RESOURCE_WHITESPACE_RULE,
+    resourceQuotes: RESOURCE_QUOTE_RULE,
+    resourcePunctuation: RESOURCE_PUNCTUATION_RULE,
+    controlCharacters: RESOURCE_CONTROL_RULE,
+};
+const isText = (value) => typeof value === "string";
+/** A repository-relative path with forward slashes, inside the repository, at most 400 characters. */
+export function isAnchorPath(value) {
+    if (!isText(value))
+        return false;
+    if (value.length > ANCHOR_LIMITS.path)
+        return false;
+    // Also refuses the empty string.
+    if (!PATH_CHARACTERS_RULE.test(value))
+        return false;
+    if (PATH_SPACING_RULE.test(value))
+        return false;
+    // An absolute path, a doubled slash and a trailing slash each leave an empty segment.
+    if (value.split("/").some((segment) => segment === ""))
+        return false;
+    if (value.split("/").some((segment) => segment === ".."))
+        return false;
+    return true;
+}
+/** An identifier, optionally dotted, at most 200 characters. */
+export function isAnchorSymbol(value) {
+    if (!isText(value))
+        return false;
+    if (value.length > ANCHOR_LIMITS.name)
+        return false;
+    return SYMBOL_RULE.test(value);
+}
+/** A table, route, flag or other resource name: no whitespace, quotes or code punctuation. */
+export function isAnchorResourceName(value) {
+    if (!isText(value))
+        return false;
+    if (value.length < 1)
+        return false;
+    if (value.length > ANCHOR_LIMITS.name)
+        return false;
+    if (RESOURCE_WHITESPACE_RULE.test(value))
+        return false;
+    if (RESOURCE_QUOTE_RULE.test(value))
+        return false;
+    if (RESOURCE_PUNCTUATION_RULE.test(value))
+        return false;
+    if (RESOURCE_CONTROL_RULE.test(value))
+        return false;
+    return true;
+}
+export function isPromiseAnchorId(value) {
+    return isText(value) && PROMISE_ID_RULE.test(value);
+}
+function isInstant(value) {
+    return isText(value) && INSTANT_RULE.test(value) && !Number.isNaN(Date.parse(value));
+}
+function isModel(value) {
+    return isText(value) && MODEL_RULE.test(value);
+}
+function oneOf(values) {
+    return (value) => isText(value) && values.includes(value);
+}
+const isEntryKind = oneOf(ENTRY_POINT_KINDS);
+const isSymbolKind = oneOf(SYMBOL_KINDS);
+const isResourceKind = oneOf(RESOURCE_KINDS);
+const isResourceAccess = oneOf(RESOURCE_ACCESS);
+const isSource = oneOf(ANCHOR_SOURCES);
+const isClient = oneOf(["claude", "codex"]);
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Exactly these keys and no others, so no free-text field can ride along. */
+function hasExactKeys(value, keys) {
+    const present = Object.keys(value).sort();
+    const wanted = [...keys].sort();
+    return present.length === wanted.length && present.every((key, index) => key === wanted[index]);
+}
+/**
+ * A whole anchors document, checked against the contract and the data
+ * boundary. Problems name the field and the rule, never the value, so a
+ * refusal never repeats what it refused.
+ */
+export function checkPromiseAnchors(value) {
+    const problems = [];
+    const fail = (at, rule) => problems.push(`${at} ${rule}`);
+    if (!isRecord(value))
+        return { ok: false, problems: ["the document is not an object"] };
+    if (!hasExactKeys(value, [
+        "schemaVersion",
+        "promiseId",
+        "semanticDigest",
+        "anchoredAt",
+        "entryPoints",
+        "symbols",
+        "resources",
+        "linkedTests",
+    ]))
+        fail("the document", "has fields the contract does not define, or lacks one");
+    if (value.schemaVersion !== PROMISE_ANCHORS_SCHEMA_VERSION)
+        fail("schemaVersion", `is not ${PROMISE_ANCHORS_SCHEMA_VERSION}`);
+    if (!isPromiseAnchorId(value.promiseId))
+        fail("promiseId", "is not a prom_ id");
+    if (!isText(value.semanticDigest) || !DIGEST_RULE.test(value.semanticDigest))
+        fail("semanticDigest", "is not sha256: and 64 hex characters");
+    const anchoredAt = value.anchoredAt;
+    if (!isRecord(anchoredAt))
+        fail("anchoredAt", "is not an object");
+    else {
+        if (!hasExactKeys(anchoredAt, ["sha", "at", "source", "client", "model"]))
+            fail("anchoredAt", "has fields the contract does not define, or lacks one");
+        if (!isText(anchoredAt.sha) || !SHA_RULE.test(anchoredAt.sha))
+            fail("anchoredAt.sha", "is not a 40-character commit sha");
+        if (!isInstant(anchoredAt.at))
+            fail("anchoredAt.at", "is not an ISO 8601 instant");
+        if (!isSource(anchoredAt.source))
+            fail("anchoredAt.source", "is not a known source");
+        if (anchoredAt.source === BEHAVIOR_MAP_SOURCE) {
+            if (anchoredAt.client !== null)
+                fail("anchoredAt.client", "must be null for a map");
+            if (anchoredAt.model !== null)
+                fail("anchoredAt.model", "must be null for a map");
+        }
+        else {
+            if (!isClient(anchoredAt.client))
+                fail("anchoredAt.client", "is not claude or codex");
+            if (!isModel(anchoredAt.model))
+                fail("anchoredAt.model", "is not a model name");
+        }
+    }
+    const list = (key, keys, check) => {
+        const items = value[key];
+        if (!Array.isArray(items)) {
+            fail(key, "is not a list");
+            return 0;
+        }
+        if (items.length > ANCHOR_LIMITS[key])
+            fail(key, `has more than ${ANCHOR_LIMITS[key]} entries`);
+        items.forEach((item, index) => {
+            const at = `${key}[${index}]`;
+            if (!isRecord(item))
+                return fail(at, "is not an object");
+            if (!hasExactKeys(item, keys))
+                fail(at, "has fields the contract does not define, or lacks one");
+            check(item, at);
+        });
+        return items.length;
+    };
+    const entryPoints = list("entryPoints", ["file", "symbol", "kind"], (item, at) => {
+        if (!isAnchorPath(item.file))
+            fail(`${at}.file`, "is not a repository path");
+        if (!isAnchorSymbol(item.symbol))
+            fail(`${at}.symbol`, "is not a symbol name");
+        if (!isEntryKind(item.kind))
+            fail(`${at}.kind`, "is not an entry point kind");
+    });
+    const symbols = list("symbols", ["file", "name", "kind"], (item, at) => {
+        if (!isAnchorPath(item.file))
+            fail(`${at}.file`, "is not a repository path");
+        if (!isAnchorSymbol(item.name))
+            fail(`${at}.name`, "is not a symbol name");
+        if (!isSymbolKind(item.kind))
+            fail(`${at}.kind`, "is not a symbol kind");
+    });
+    list("resources", ["kind", "name", "access"], (item, at) => {
+        if (!isResourceKind(item.kind))
+            fail(`${at}.kind`, "is not a resource kind");
+        if (!isAnchorResourceName(item.name))
+            fail(`${at}.name`, "is not a resource name");
+        if (!isResourceAccess(item.access))
+            fail(`${at}.access`, "is not a resource access");
+    });
+    list("linkedTests", ["file"], (item, at) => {
+        if (!isAnchorPath(item.file))
+            fail(`${at}.file`, "is not a repository path");
+    });
+    // A document that names no anchor file could never select its promise.
+    if (entryPoints + symbols === 0)
+        fail("the document", "names no entry point and no symbol");
+    return problems.length === 0
+        ? { ok: true, value: value }
+        : { ok: false, problems };
+}
+/** The files a promise is selected by: its entry points' and its symbols' files. */
+export function anchorFiles(anchors) {
+    return [
+        ...new Set([
+            ...anchors.entryPoints.map((entry) => entry.file),
+            ...anchors.symbols.map((symbol) => symbol.file),
+        ]),
+    ].sort();
+}

package/dist/cli.d.ts

@@ -33,7 +33,7 @@ type Parsed = Readonly<{
      */
     repositories: readonly string[];
     hook: "codex" | "claude" | undefined;
-    event: "SessionStart" | "UserPromptSubmit" | "SubagentStart" | undefined;
+    event: "SessionStart" | "UserPromptSubmit" | "SubagentStart" | "PostToolUse" | undefined;
     owner: string | undefined;
     /** `check-seals --install-hook`: write the optional pre-push hook. */
     installHook: boolean;