toolroll 0.9.36 → 0.9.37

package/dist/contracts/project-knowledge.js

@@ -0,0 +1,93 @@
+/**
+ * Project knowledge (project-knowledge.ts): one schema for the saved knowledge (instructions and references, every
+ * revision in `knowledge_change` and the current one in `project_knowledge`), and for the selection a run is given and
+ * keeps (`knowledge_snapshot`). The rules JSON Schema cannot state — UTF-8 byte limits, control characters, secrets,
+ * the selection's total size — run in plain code when knowledge is written. A saved payload's digest is checked
+ * against its stored bytes before it is parsed, and it is upgraded only in memory: stored bytes are never rewritten.
+ */
+import { z } from "zod";
+import { limited, readVersioned, versioned } from "./contract.js";
+import { decisionLineSchema } from "./project-memory.js";
+/** How many references a project keeps, and how many a run is given. Text limits live in TEXT_LIMITS. */
+export const KNOWLEDGE_COUNTS = { references: 12, selected: 3, decisions: 8 };
+const written = limited;
+const saved = () => z.string();
+const referenceShape = (text) => ({
+    id: z.string(),
+    title: text("reference title", "knowledgeTitleBytes"),
+    content: text("reference text", "knowledgeReferenceBytes"),
+    /** A committed .md or .txt file the text was read from, at `sourceRevision` with blob `sourceSha`; null for a note. */
+    path: text("reference path", "knowledgePathBytes").nullable(),
+    sourceSha: z.string().nullable(),
+    sourceRevision: z.string().nullable(),
+});
+const knowledgeShape = (text) => ({
+    instructions: text("instructions", "knowledgeInstructionsBytes"),
+    references: z.array(z.strictObject(referenceShape(text))).max(KNOWLEDGE_COUNTS.references),
+});
+export const KNOWLEDGE_VERSION = 1;
+/** Knowledge as it is written. */
+export const knowledgeSchema = versioned(KNOWLEDGE_VERSION, knowledgeShape(written));
+/** Knowledge as it is read back. */
+export const savedKnowledgeSchema = versioned(KNOWLEDGE_VERSION, knowledgeShape(saved));
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function pick(body, fields) {
+    const out = {};
+    for (const field of fields)
+        if (Object.prototype.hasOwnProperty.call(body, field))
+            out[field] = body[field];
+    return out;
+}
+const REFERENCE_FIELDS = Object.keys(referenceShape(saved));
+/**
+ * Knowledge saved before it carried `version` (through 0.9.36: `{instructions, references}`), as version 1. Its
+ * readers took the fields they knew, so this keeps exactly those; values are never rewritten.
+ */
+export function upgradeKnowledgeV0(body) {
+    const references = body["references"];
+    return {
+        version: KNOWLEDGE_VERSION,
+        ...pick(body, ["instructions"]),
+        ...(references === undefined ? {} : { references: Array.isArray(references) ? references.map(one => (isRecord(one) ? pick(one, REFERENCE_FIELDS) : one)) : references }),
+    };
+}
+export const KNOWLEDGE_UPGRADES = { 0: upgradeKnowledgeV0 };
+/** Read saved knowledge: version 1 as itself, an unversioned one upgraded, a newer one refused plainly. */
+export function readKnowledge(input) {
+    const read = readVersioned(savedKnowledgeSchema, input, KNOWLEDGE_UPGRADES);
+    if (!read.ok)
+        return read;
+    const { version: _version, ...knowledge } = read.value;
+    return { ok: true, value: knowledge };
+}
+/** What a person drafts on the Knowledge page or the CLI; each action reads the fields it needs. */
+export const knowledgeDraftSchema = z.strictObject({
+    instructions: z.string().optional(),
+    title: z.string().optional(),
+    content: z.string().optional(),
+    path: z.string().optional(),
+    id: z.string().optional(),
+});
+/** A source a run was not given, and why. */
+export const knowledgeOmissionSchema = z.strictObject({ title: z.string(), reason: z.string() });
+const selectionShape = (text) => ({
+    revision: z.int().min(0),
+    instructions: text("instructions", "knowledgeInstructionsBytes"),
+    references: z.array(z.strictObject(referenceShape(text))).max(KNOWLEDGE_COUNTS.references),
+    omitted: z.array(knowledgeOmissionSchema),
+    /** The run whose selection a reviewer inherited; null for a selection of its own. */
+    inheritedFrom: z.int().nullable(),
+    /** Settled decisions, one line each; absent when there are none. */
+    decisions: z.array(decisionLineSchema).max(KNOWLEDGE_COUNTS.decisions).optional(),
+    /** Source excerpts from the crew's checkout (repository-context.ts owns their shape); absent when not captured. */
+    repository: z.looseObject({}).optional(),
+});
+export const KNOWLEDGE_SELECTION_VERSION = 1;
+/** The selection a run is given, as it is frozen. The keys are in the order a selection has always been written. */
+export const knowledgeSelectionSchema = versioned(KNOWLEDGE_SELECTION_VERSION, selectionShape(written));
+/** A frozen selection as it is read back. */
+export const savedKnowledgeSelectionSchema = versioned(KNOWLEDGE_SELECTION_VERSION, selectionShape(saved));
+/** Read a frozen selection: version 1 (every selection ever frozen) as itself, a newer one refused plainly. */
+export function readKnowledgeSelection(input) {
+    return readVersioned(savedKnowledgeSelectionSchema, input);
+}

package/dist/contracts/project-memory.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Project memory's decisions (project-memory.ts): one schema for a decision as its row reads, the record its history
+ * keeps, the change a person or the lead drafts, and the one line a brief carries. The rules JSON Schema cannot state —
+ * UTF-8 byte limits, blank text, control characters and secrets — run in plain code (`clean`) when a decision is
+ * written; a row is read as it was written, and its digest is checked against the row before anything trusts it.
+ */
+import { z } from "zod";
+export declare const DECISION_STATUSES: readonly ["active", "superseded", "retired"];
+export declare const DECISION_SOURCES: readonly ["conversation", "task", "result", "manual", "backward-pass"];
+/** A decision as it is recorded, in the order its digest lists the fields. */
+export declare const decisionRecordSchema: z.ZodObject<{
+    repo: z.ZodString;
+    revision: z.ZodInt;
+    claim: z.ZodString;
+    why: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        retired: "retired";
+        superseded: "superseded";
+    }>;
+    supersedes: z.ZodNullable<z.ZodInt>;
+    decidedBy: z.ZodString;
+    decidedAt: z.ZodString;
+    sourceKind: z.ZodEnum<{
+        "backward-pass": "backward-pass";
+        conversation: "conversation";
+        manual: "manual";
+        result: "result";
+        task: "task";
+    }>;
+    sourceRef: z.ZodNullable<z.ZodString>;
+    recordedBy: z.ZodString;
+}, z.core.$strict>;
+/** A decision as its row reads. */
+export declare const decisionSchema: z.ZodObject<{
+    repo: z.ZodString;
+    revision: z.ZodInt;
+    claim: z.ZodString;
+    why: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        retired: "retired";
+        superseded: "superseded";
+    }>;
+    supersedes: z.ZodNullable<z.ZodInt>;
+    decidedBy: z.ZodString;
+    decidedAt: z.ZodString;
+    sourceKind: z.ZodEnum<{
+        "backward-pass": "backward-pass";
+        conversation: "conversation";
+        manual: "manual";
+        result: "result";
+        task: "task";
+    }>;
+    sourceRef: z.ZodNullable<z.ZodString>;
+    recordedBy: z.ZodString;
+    id: z.ZodInt;
+}, z.core.$strict>;
+export type Decision = z.infer<typeof decisionSchema>;
+export type DecisionRecord = z.infer<typeof decisionRecordSchema>;
+/** What a person or the lead asks to record; only the choice and its reason are required. */
+export declare const decisionDraftSchema: z.ZodObject<{
+    claim: z.ZodString;
+    why: z.ZodString;
+    decidedBy: z.ZodOptional<z.ZodString>;
+    decidedAt: z.ZodOptional<z.ZodString>;
+    sourceKind: z.ZodOptional<z.ZodEnum<{
+        "backward-pass": "backward-pass";
+        conversation: "conversation";
+        manual: "manual";
+        result: "result";
+        task: "task";
+    }>>;
+    sourceRef: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    supersedes: z.ZodOptional<z.ZodNullable<z.ZodInt>>;
+}, z.core.$strict>;
+export type DecisionDraft = z.infer<typeof decisionDraftSchema>;
+/** One decision in a brief: its id, the choice and when; the why loads on demand by id. */
+export declare const decisionLineSchema: z.ZodObject<{
+    id: z.ZodInt;
+    claim: z.ZodString;
+    decidedAt: z.ZodString;
+}, z.core.$strict>;
+export type DecisionLine = z.infer<typeof decisionLineSchema>;
+export declare const DECISION_CHANGE_VERSION = 1;
+/**
+ * One entry of a decision's history (`decision_change.payload`): the record when it was made, or the reason its status
+ * changed. Entries written before this carried `version` are the same shapes without it; nothing reads them back.
+ */
+export declare const decisionChangeSchema: z.ZodUnion<readonly [z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    repo: z.ZodString;
+    revision: z.ZodInt;
+    claim: z.ZodString;
+    why: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        retired: "retired";
+        superseded: "superseded";
+    }>;
+    supersedes: z.ZodNullable<z.ZodInt>;
+    decidedBy: z.ZodString;
+    decidedAt: z.ZodString;
+    sourceKind: z.ZodEnum<{
+        "backward-pass": "backward-pass";
+        conversation: "conversation";
+        manual: "manual";
+        result: "result";
+        task: "task";
+    }>;
+    sourceRef: z.ZodNullable<z.ZodString>;
+    recordedBy: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    reason: z.ZodString;
+}, z.core.$strict>]>;
+export type DecisionChange = z.infer<typeof decisionChangeSchema>;

package/dist/contracts/project-memory.js

@@ -0,0 +1,51 @@
+/**
+ * Project memory's decisions (project-memory.ts): one schema for a decision as its row reads, the record its history
+ * keeps, the change a person or the lead drafts, and the one line a brief carries. The rules JSON Schema cannot state —
+ * UTF-8 byte limits, blank text, control characters and secrets — run in plain code (`clean`) when a decision is
+ * written; a row is read as it was written, and its digest is checked against the row before anything trusts it.
+ */
+import { z } from "zod";
+import { limited, versioned } from "./contract.js";
+export const DECISION_STATUSES = ["active", "superseded", "retired"];
+export const DECISION_SOURCES = ["conversation", "task", "result", "manual", "backward-pass"];
+const written = limited;
+const saved = () => z.string();
+const recordShape = (text) => ({
+    repo: z.string(),
+    revision: z.int().min(1),
+    claim: text("decision", "decisionClaimBytes"),
+    why: text("reason", "decisionWhyBytes"),
+    status: z.enum(DECISION_STATUSES),
+    supersedes: z.int().nullable(),
+    // An omitted draft author defaults to the account name, which has never had the explicit author's byte limit.
+    decidedBy: z.string(),
+    decidedAt: z.string(),
+    sourceKind: z.enum(DECISION_SOURCES),
+    sourceRef: text("source", "decisionSourceBytes").nullable(),
+    recordedBy: z.string(),
+});
+/** A decision as it is recorded, in the order its digest lists the fields. */
+export const decisionRecordSchema = z.strictObject(recordShape(written));
+/** A decision as its row reads. */
+export const decisionSchema = z.strictObject({ id: z.int(), ...recordShape(saved) });
+/** What a person or the lead asks to record; only the choice and its reason are required. */
+export const decisionDraftSchema = z.strictObject({
+    claim: z.string(),
+    why: z.string(),
+    decidedBy: z.string().optional(),
+    decidedAt: z.string().optional(),
+    sourceKind: z.enum(DECISION_SOURCES).optional(),
+    sourceRef: z.string().nullable().optional(),
+    supersedes: z.int().nullable().optional(),
+});
+/** One decision in a brief: its id, the choice and when; the why loads on demand by id. */
+export const decisionLineSchema = z.strictObject({ id: z.int(), claim: z.string(), decidedAt: z.string() });
+export const DECISION_CHANGE_VERSION = 1;
+/**
+ * One entry of a decision's history (`decision_change.payload`): the record when it was made, or the reason its status
+ * changed. Entries written before this carried `version` are the same shapes without it; nothing reads them back.
+ */
+export const decisionChangeSchema = z.union([
+    versioned(DECISION_CHANGE_VERSION, recordShape(written)),
+    versioned(DECISION_CHANGE_VERSION, { reason: limited("reason", "decisionRetireBytes") }),
+]);

package/dist/contracts/project-skills.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Project skills (project-skills.ts): one schema for a skill package (`skill_package`), a project's selection of
+ * versions (`project_skill_change`), and the versions a run is pinned to (`skill_snapshot`, and the snapshot a reviewer
+ * reads). The rules JSON Schema cannot state — UTF-8 byte limits, base64, path safety, YAML metadata, secrets, the
+ * selection's total size — run in plain code (`validateSkill`, `changeSkills`) when a skill is imported or chosen.
+ *
+ * Two payloads carry no envelope, on purpose. A package is content-addressed: its digest is its version, so the same
+ * folder imported before and after this contract is the same version. A selection maps skill names to versions, and
+ * `version` is itself a valid skill name, so a key there would collide with one; an older runtime also reads every
+ * value in it as a choice. Both are read exactly as they have always been written.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** How many files a package holds, how many versions a project enables and a person's library keeps. Text limits live
+ * in TEXT_LIMITS. */
+export declare const SKILL_COUNTS: {
+    readonly files: 64;
+    readonly enabled: 8;
+    readonly library: 100;
+};
+/** Every skill limit by its long-standing name: the counts above and the byte limits from TEXT_LIMITS. */
+export declare const SKILL_LIMITS: {
+    readonly files: 64;
+    readonly packageBytes: number;
+    readonly fileBytes: number;
+    readonly bodyBytes: number;
+    readonly enabled: 8;
+    readonly selectionBytes: number;
+};
+/** A skill name: lowercase words joined by hyphens. */
+export declare const SKILL_NAME: RegExp;
+export declare const skillFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    base64: z.ZodString;
+}, z.core.$strict>;
+/** A package as it is imported. */
+export declare const skillPackageSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    source: z.ZodString;
+    requirements: z.ZodString;
+    warnings: z.ZodArray<z.ZodString>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        base64: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** A package as it is read back. */
+export declare const savedSkillPackageSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    source: z.ZodString;
+    requirements: z.ZodString;
+    warnings: z.ZodArray<z.ZodString>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        base64: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** A package with its version (the digest of its bytes). */
+export declare const savedSkillSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    source: z.ZodString;
+    requirements: z.ZodString;
+    warnings: z.ZodArray<z.ZodString>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        base64: z.ZodString;
+    }, z.core.$strict>>;
+    sha: z.ZodString;
+}, z.core.$strict>;
+export type SkillFile = z.infer<typeof skillFileSchema>;
+export type SkillPackage = z.infer<typeof skillPackageSchema>;
+export type SavedSkill = z.infer<typeof savedSkillSchema>;
+/** One skill's chosen version, and whether it is on. */
+export declare const skillChoiceSchema: z.ZodObject<{
+    sha: z.ZodString;
+    enabled: z.ZodBoolean;
+}, z.core.$strict>;
+/** A project's selection: each skill name and its chosen version. */
+export declare const skillSelectionSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    sha: z.ZodString;
+    enabled: z.ZodBoolean;
+}, z.core.$strict>>;
+export type SkillChoice = z.infer<typeof skillChoiceSchema>;
+export type SkillSelection = z.infer<typeof skillSelectionSchema>;
+export declare const SKILLS_SNAPSHOT_VERSION = 1;
+/** The versions a run is pinned to, as frozen: the packages by digest. */
+export declare const savedSkillsSnapshotSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    revision: z.ZodInt;
+    identity: z.ZodString;
+    inheritedFrom: z.ZodNullable<z.ZodInt>;
+    test: z.ZodBoolean;
+    packageShas: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/** The same snapshot with each package read, as a run and its reviewer get it. */
+export declare const skillsSnapshotSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    revision: z.ZodInt;
+    identity: z.ZodString;
+    inheritedFrom: z.ZodNullable<z.ZodInt>;
+    test: z.ZodBoolean;
+    packages: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        source: z.ZodString;
+        requirements: z.ZodString;
+        warnings: z.ZodArray<z.ZodString>;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            base64: z.ZodString;
+        }, z.core.$strict>>;
+        sha: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SavedSkillsSnapshot = z.infer<typeof savedSkillsSnapshotSchema>;
+export type SkillsSnapshot = z.infer<typeof skillsSnapshotSchema>;
+/** Read a frozen snapshot: version 1 (every snapshot ever frozen) as itself, a newer one refused plainly. */
+export declare function readSkillsSnapshotPayload(input: unknown): ContractResult<SavedSkillsSnapshot>;

package/dist/contracts/project-skills.js

@@ -0,0 +1,76 @@
+/**
+ * Project skills (project-skills.ts): one schema for a skill package (`skill_package`), a project's selection of
+ * versions (`project_skill_change`), and the versions a run is pinned to (`skill_snapshot`, and the snapshot a reviewer
+ * reads). The rules JSON Schema cannot state — UTF-8 byte limits, base64, path safety, YAML metadata, secrets, the
+ * selection's total size — run in plain code (`validateSkill`, `changeSkills`) when a skill is imported or chosen.
+ *
+ * Two payloads carry no envelope, on purpose. A package is content-addressed: its digest is its version, so the same
+ * folder imported before and after this contract is the same version. A selection maps skill names to versions, and
+ * `version` is itself a valid skill name, so a key there would collide with one; an older runtime also reads every
+ * value in it as a choice. Both are read exactly as they have always been written.
+ */
+import { z } from "zod";
+import { TEXT_LIMITS } from "../text-limits.js";
+import { limited, readVersioned, versioned } from "./contract.js";
+/** How many files a package holds, how many versions a project enables and a person's library keeps. Text limits live
+ * in TEXT_LIMITS. */
+export const SKILL_COUNTS = { files: 64, enabled: 8, library: 100 };
+/** Every skill limit by its long-standing name: the counts above and the byte limits from TEXT_LIMITS. */
+export const SKILL_LIMITS = {
+    files: SKILL_COUNTS.files,
+    packageBytes: TEXT_LIMITS.skillPackageBytes,
+    fileBytes: TEXT_LIMITS.skillFileBytes,
+    bodyBytes: TEXT_LIMITS.skillBodyBytes,
+    enabled: SKILL_COUNTS.enabled,
+    selectionBytes: TEXT_LIMITS.skillSelectionBytes,
+};
+const written = limited;
+const saved = () => z.string();
+/** A skill name: lowercase words joined by hyphens. */
+export const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const fileShape = (text) => ({
+    /** Relative to the skill folder; no hidden parts, `.` or `..`. */
+    path: text("file path", "skillPath"),
+    /** The file's bytes, base64 (each at most TEXT_LIMITS.skillFileBytes once decoded). */
+    base64: z.string(),
+});
+const packageShape = (text) => ({
+    name: text("skill name", "skillNameBytes").regex(SKILL_NAME),
+    description: text("description", "skillDescriptionBytes"),
+    /** Where it was imported from: an uploaded folder or a GitHub folder pinned to a commit. */
+    source: text("source", "skillSourceBytes"),
+    /** SKILL.md's `compatibility`, or empty. */
+    requirements: text("requirements", "skillRequirementsBytes"),
+    warnings: z.array(z.string()),
+    files: z.array(z.strictObject(fileShape(text))).min(1).max(SKILL_COUNTS.files),
+});
+export const skillFileSchema = z.strictObject(fileShape(written));
+/** A package as it is imported. */
+export const skillPackageSchema = z.strictObject(packageShape(written));
+/** A package as it is read back. */
+export const savedSkillPackageSchema = z.strictObject(packageShape(saved));
+/** A package with its version (the digest of its bytes). */
+export const savedSkillSchema = z.strictObject({ ...packageShape(saved), sha: z.string() });
+/** One skill's chosen version, and whether it is on. */
+export const skillChoiceSchema = z.strictObject({ sha: z.string(), enabled: z.boolean() });
+/** A project's selection: each skill name and its chosen version. */
+export const skillSelectionSchema = z.record(z.string(), skillChoiceSchema);
+const snapshotFacts = {
+    /** The selection revision the versions came from; 0 for none. */
+    revision: z.int().min(0),
+    /** The project identity they were chosen under, or `unconfigured`. */
+    identity: z.string(),
+    /** The run a reviewer or later attempt inherited them from. */
+    inheritedFrom: z.int().nullable(),
+    /** A skill test: the one package is the version under test. */
+    test: z.boolean(),
+};
+export const SKILLS_SNAPSHOT_VERSION = 1;
+/** The versions a run is pinned to, as frozen: the packages by digest. */
+export const savedSkillsSnapshotSchema = versioned(SKILLS_SNAPSHOT_VERSION, { ...snapshotFacts, packageShas: z.array(z.string()) });
+/** The same snapshot with each package read, as a run and its reviewer get it. */
+export const skillsSnapshotSchema = versioned(SKILLS_SNAPSHOT_VERSION, { ...snapshotFacts, packages: z.array(savedSkillSchema) });
+/** Read a frozen snapshot: version 1 (every snapshot ever frozen) as itself, a newer one refused plainly. */
+export function readSkillsSnapshotPayload(input) {
+    return readVersioned(savedSkillsSnapshotSchema, input);
+}

package/dist/contracts/review-findings.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The automatic build review's findings (build-review.ts): one schema for the reply a reviewer gives, the `findings`
+ * a Claude reviewer's `--json-schema` describes (provider.ts, inside the review channel it shares with evidence
+ * reviews), and what `build_review.findings_json` keeps. `parseBuildFindings` (reviewer.ts) reads a reply through it;
+ * a saved row is the same payload, written by `settle` after that read.
+ *
+ * As before, controls and runs of whitespace collapse to one space before text limits are checked. Unknown keys
+ * are ignored in both the review envelope and each finding.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+export declare const FINDING_SEVERITIES: readonly ["HIGH", "MEDIUM", "LOW"];
+export type FindingSeverity = (typeof FINDING_SEVERITIES)[number];
+/** How many findings one review may raise. */
+export declare const FINDINGS_MAX = 40;
+/** One finding: how bad, where (a path and the closest line), and how it fails, in one sentence. */
+export declare const buildFindingSchema: z.ZodObject<{
+    severity: z.ZodEnum<{
+        HIGH: "HIGH";
+        LOW: "LOW";
+        MEDIUM: "MEDIUM";
+    }>;
+    file: z.ZodString;
+    line: z.ZodNumber;
+    scenario: z.ZodString;
+}, z.core.$strip>;
+export type BuildFinding = z.infer<typeof buildFindingSchema>;
+export declare const FINDINGS_VERSION = 1;
+export declare const buildFindingsSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    findings: z.ZodArray<z.ZodObject<{
+        severity: z.ZodEnum<{
+            HIGH: "HIGH";
+            LOW: "LOW";
+            MEDIUM: "MEDIUM";
+        }>;
+        file: z.ZodString;
+        line: z.ZodNumber;
+        scenario: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BuildFindings = z.infer<typeof buildFindingsSchema>;
+/** The `findings` a reviewer's structured reply may carry (provider.ts's review channel), from the same schema. */
+export declare const FINDINGS_MODEL_SCHEMA: Readonly<Record<string, unknown>>;
+/** Read a findings payload: version 1 as itself, a newer one refused plainly, anything else by path. */
+export declare function readBuildFindings(input: unknown): ContractResult<BuildFindings>;

package/dist/contracts/review-findings.js

@@ -0,0 +1,48 @@
+/**
+ * The automatic build review's findings (build-review.ts): one schema for the reply a reviewer gives, the `findings`
+ * a Claude reviewer's `--json-schema` describes (provider.ts, inside the review channel it shares with evidence
+ * reviews), and what `build_review.findings_json` keeps. `parseBuildFindings` (reviewer.ts) reads a reply through it;
+ * a saved row is the same payload, written by `settle` after that read.
+ *
+ * As before, controls and runs of whitespace collapse to one space before text limits are checked. Unknown keys
+ * are ignored in both the review envelope and each finding.
+ */
+import { z } from "zod";
+import { TEXT_LIMITS } from "../text-limits.js";
+import { limited, readVersioned, toModelSchema, versioned } from "./contract.js";
+export const FINDING_SEVERITIES = ["HIGH", "MEDIUM", "LOW"];
+/** How many findings one review may raise. */
+export const FINDINGS_MAX = 40;
+/** One finding: how bad, where (a path and the closest line), and how it fails, in one sentence. */
+export const buildFindingSchema = z.object({
+    severity: z.enum(FINDING_SEVERITIES),
+    file: limited("file", "reviewPath").min(1).describe(`file: at most ${TEXT_LIMITS.reviewPath} characters, on one line.`),
+    line: z.number().min(1).multipleOf(1),
+    scenario: limited("scenario", "reviewNote").min(1).describe(`scenario: at most ${TEXT_LIMITS.reviewNote} characters, on one line.`),
+});
+export const FINDINGS_VERSION = 1;
+export const buildFindingsSchema = versioned(FINDINGS_VERSION, {
+    findings: z.array(buildFindingSchema).max(FINDINGS_MAX),
+}).strip();
+/** The `findings` a reviewer's structured reply may carry (provider.ts's review channel), from the same schema. */
+export const FINDINGS_MODEL_SCHEMA = toModelSchema(buildFindingsSchema.shape.findings);
+/** Read a findings payload: version 1 as itself, a newer one refused plainly, anything else by path. */
+export function readBuildFindings(input) {
+    if (typeof input === "object" && input !== null && !Array.isArray(input)) {
+        const body = input;
+        if (Array.isArray(body["findings"])) {
+            input = { ...body, findings: body["findings"].map(entry => {
+                    if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+                        return entry;
+                    const finding = { ...entry };
+                    for (const key of ["file", "scenario"]) {
+                        const text = finding[key];
+                        if (typeof text === "string")
+                            finding[key] = text.replace(/[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]+/g, " ").replace(/\s+/g, " ").trim();
+                    }
+                    return finding;
+                }) };
+        }
+    }
+    return readVersioned(buildFindingsSchema, input);
+}