toolroll 0.5.0

package/dist/planner-source.d.ts

@@ -0,0 +1,251 @@
+/**
+ * The planner's SOURCE: exactly what was filed for a task at the moment a
+ * planning attempt starts — the scope's goal, exclusions, touches, and the
+ * whole rubric (ids, statements, evidence kinds, advisory how), its
+ * execution terms, the revision brief when the task revises reviewed work,
+ * and the operator's earlier answers — captured losslessly as quoted data.
+ *
+ * Filed intent is DATA, never authorization: nothing here approves, and a
+ * planner reading it gains no authority it did not already have. What it
+ * gains is the operator's actual words, so a short title can no longer
+ * become a title-derived guess that silently drops the UI evidence, the
+ * exclusions, or a criterion somebody wrote down (contract handoff plan,
+ * task 1).
+ *
+ * Three facts ride the same record:
+ *
+ *   identity   `sourceDigest` — a digest over the CONTRACT part (scope
+ *              digest and terms, task-level terms, the revision brief's
+ *              artifact and hash). The planner run is stamped with it, a
+ *              same-session correction inherits it through its parent, a
+ *              resumed decision re-derives it, and the plan ingestion
+ *              re-derives it INSIDE its transaction: a source that moved
+ *              while the planner ran refuses the draft rather than
+ *              overwriting the newer terms.
+ *   bounds     one explicit byte cap on the whole quoted record. Over it,
+ *              the attempt refuses in words BEFORE any provider spend —
+ *              a brief that silently trimmed a criterion would be the very
+ *              loss this module exists to prevent.
+ *   changes    `contractChangesOf` — the mechanical additions, changes,
+ *              and removals between the filed terms and what a planner
+ *              drafted. A plan that changes filed terms must SAY so with an
+ *              explicit amendment; the approval shows every change either
+ *              way and binds exactly the terms the operator accepts.
+ *
+ * Pure primitives plus one store-reading assembler. No spawning, no
+ * transactions of its own: the fenced finalizers in claim.ts seal.
+ */
+import type { Store } from "./store.js";
+import type { AcceptanceCriterion, EvidenceKind, Scope } from "./scope.js";
+import type { QualityMode } from "./quality.js";
+import type { RiskLevel } from "./phase-routing.js";
+export declare const PLANNER_SOURCE_VERSION = 1;
+export declare const PLANNER_SOURCE_LIMITS: {
+    /** The whole recorded source before lossless prompt fencing. Equal to
+     * the evidence cap for its artifact kind, so a recorded source is never
+     * truncated: what the record holds is exactly what the planner read. */
+    readonly bytes: number;
+    /** A planner's amendment note: why the filed contract must change. */
+    readonly amendment: 1000;
+    /** Earlier answers quoted into the brief. */
+    readonly answers: 5;
+};
+/** The four contract fields a planner may propose to amend. */
+export type ContractTerms = {
+    goal: string;
+    outOfScope: string | null;
+    touches: string[];
+    acceptance: AcceptanceCriterion[];
+};
+export type PlannerContractScope = ContractTerms & {
+    /** The filed row's digest — the exact bytes the terms carry today. */
+    digest: string;
+    terms: {
+        riskLevel: RiskLevel;
+        qualityMode: QualityMode;
+        budgetMicrousd: number | null;
+        /** The resolved build agent, when the filing resolved one. */
+        agent: {
+            provider: string;
+            model: string;
+        } | null;
+        profile: Scope["profile"];
+        routeJson: string | null;
+        chainJson: string | null;
+        profileState: "resolved" | "unresolved" | null;
+        unresolvedReason: string | null;
+    };
+    /** A scope the planner is asked about is never approved (requestPlan
+     * refuses that), but it may have been approved once and then rewritten
+     * — the operator's earlier yes is context worth quoting. */
+    approval: {
+        state: "none" | "changed";
+        approvedDigest: string | null;
+        approvedBy: string | null;
+    };
+    proposedVia: "mate" | "coordinator" | "scout" | null;
+};
+export type PlannerContract = {
+    /** null: no scope was filed — the title is the only filed intent, and
+     * the planner drafts the contract from scratch (the legacy road). */
+    scope: PlannerContractScope | null;
+    task: {
+        id: string;
+        title: string;
+        repo: string | null;
+        routeOverrides: import("./store.js").TaskRef["routeOverrides"];
+        agentPin: {
+            provider: string | null;
+            model: string | null;
+        };
+        planPin: {
+            provider: string | null;
+            model: string | null;
+        };
+        deliverable: "branch" | "report";
+        riskLevel: RiskLevel | null;
+        qualityMode: QualityMode | null;
+        permissionMode: string | null;
+    };
+    /** The revision brief this task builds against, by artifact identity
+     * and hash (the content is quoted separately, from a verified read). */
+    revision: {
+        of: string;
+        briefArtifact: number;
+        briefSha256: string;
+    } | null;
+};
+export type PlannerAnswer = {
+    question: string;
+    choice: string;
+    note: string | null;
+};
+export type PlannerSource = {
+    version: typeof PLANNER_SOURCE_VERSION;
+    taskId: string;
+    title: string;
+    contract: PlannerContract;
+    /** sha256 over the canonical contract — the source identity. */
+    sourceDigest: string;
+    /** The verified brief text, when `contract.revision` names one. */
+    revisionBrief: string | null;
+    answers: PlannerAnswer[];
+};
+/** Stable JSON for hashing and equality only — no filling, no trimming. */
+export declare function canonicalContractJson(value: unknown): string;
+export declare function plannerSourceDigest(contract: PlannerContract): string;
+/**
+ * The contract part, read from the store alone — no file I/O — so the plan
+ * ingestion can re-derive it inside its own transaction and compare
+ * digests. The revision brief enters by artifact id and sha256: the row
+ * is immutable, and the hash is what a verified read proves against.
+ */
+export declare function plannerContractOf(store: Store, taskId: string): {
+    ok: true;
+    contract: PlannerContract;
+} | {
+    ok: false;
+    reason: "no-task" | "revision-brief";
+    message: string;
+};
+export type PlannerSourceResult = {
+    ok: true;
+    source: PlannerSource;
+    bytes: number;
+} | {
+    ok: false;
+    reason: "no-task" | "revision-brief" | "oversized";
+    message: string;
+};
+/**
+ * Everything a planning attempt is given, assembled once per attempt from
+ * the store and the verified evidence root, and measured against the byte
+ * cap BEFORE anything is leased or spent. A brief that cannot be read is a
+ * refusal in words (the builder's rule for the same artifact), never a
+ * plan drafted without half its contract.
+ */
+export declare function plannerSourceOf(store: Store, root: string, taskId: string, answers: readonly PlannerAnswer[]): PlannerSourceResult;
+/**
+ * The dispatch diagnosis's read of the same gate, from the store alone:
+ * why the next pass would refuse to plan this task before spending — the
+ * revision brief unreadable, or the filed request over the byte cap. The
+ * size is a floor (the brief's stored bytes, before JSON quoting), so a
+ * "yes" here is certain and the dispatch refusal itself stays the exact
+ * word. Null when nothing here stands in the way.
+ */
+export declare function plannerSourceProblemOf(store: Store, taskId: string): string | null;
+/** The exact bytes recorded as evidence; prompt fencing preserves the JSON value. */
+export declare function encodePlannerSource(source: PlannerSource): Buffer;
+/** Read a recorded source back; null when the bytes are not one. */
+export declare function decodePlannerSource(content: Buffer): PlannerSource | null;
+export type ContractChange = {
+    field: "goal";
+    kind: "changed";
+    before: string;
+    after: string;
+} | {
+    field: "outOfScope";
+    kind: "added" | "removed" | "changed";
+    before: string | null;
+    after: string | null;
+} | {
+    field: "touches";
+    kind: "added" | "removed";
+    path: string;
+} | {
+    field: "acceptance";
+    kind: "added" | "removed" | "changed";
+    id: string;
+    before: {
+        statement: string;
+        evidence: EvidenceKind[];
+        how: string | null;
+    } | null;
+    after: {
+        statement: string;
+        evidence: EvidenceKind[];
+        how: string | null;
+    } | null;
+    /** For `changed`: which parts moved. `how` is advisory and unsigned,
+     * but a planner rewriting it is still a change the operator sees. */
+    moved: ("statement" | "evidence" | "how")[];
+};
+/**
+ * Every addition, change, and removal between the filed contract and a
+ * proposed one. Whitespace at the ends and touch/evidence order do not
+ * count (the scope digest ignores them too); everything else does,
+ * including the advisory `how`, because the operator wrote it.
+ */
+export declare function contractChangesOf(filed: ContractTerms, proposed: ContractTerms): ContractChange[];
+/** One line per change, for terminals, notifications, and validation messages. */
+export declare function describeContractChanges(changes: readonly ContractChange[]): string[];
+/**
+ * The ingestion record written beside the plan document: the filed terms
+ * the attempt started from, what the planner proposed, the explicit
+ * amendment (or its absence), and the mechanical changes between the two.
+ * The task and approval views read this to show what the yes would accept.
+ */
+export type PlanContractRecord = {
+    version: typeof PLANNER_SOURCE_VERSION;
+    sourceDigest: string;
+    /** The recorded source artifact of the same run, when the write succeeded. */
+    sourceArtifact: number | null;
+    filed: ContractTerms | null;
+    /** What landed as the scope row. A view proves the record is still the
+     * CURRENT draft by comparing these terms to the row — an operator's
+     * later edit makes the record history, not a claim about the row. */
+    proposed: ContractTerms;
+    amendment: string | null;
+    changes: ContractChange[];
+};
+export declare function encodePlanContractRecord(record: PlanContractRecord): Buffer;
+export declare function decodePlanContractRecord(content: Buffer): PlanContractRecord | null;
+/**
+ * One line, prefixed, with nothing that can end the block or start a new
+ * rule — the builder's fence, applied to the planner's quoted source. The
+ * source is quoted as pretty-printed JSON, so every control character an
+ * operator's text carries arrives as a visible JSON escape: lossless, and
+ * still one physical line per JSON line.
+ */
+export declare function fenceSourceLine(text: string): string;
+export declare function plannerSourceBlock(source: PlannerSource): string[];