@yagni-app/code 0.3.2 → 0.3.3

package/dist/extension/pipeline/checker.js

@@ -0,0 +1,238 @@
+/**
+ * PURE checker-side helpers for the implement diamond (spec decisions 5-7).
+ *
+ * The checker itself is deterministic and lives in `verify.ts` (the per-workstream
+ * scoped typecheck plus the one full `makeRunVerify` on the merged tree). What is
+ * left is the reading of its verdict, and that is all pure text math:
+ *
+ *  - {@link checkerFindings} unions the scoped + full findings into one deduped list.
+ *  - {@link composeSynthesizerInput} turns the fan handoff plus the checker's
+ *    verdict into the synthesizer's `{previous}`.
+ *  - {@link attributeFindings} routes each finding to the workstream whose claims
+ *    cover its file; anything unattributable is the synthesizer's (or, on the
+ *    single-writer path, the one builder's).
+ *  - {@link parseOpenFindings} reads the synthesizer's own "## Open findings"
+ *    section, because decision 7 lets the summary report defects the deterministic
+ *    checker cannot see.
+ *  - {@link composeResidue} names what is still open when the fix cap is reached,
+ *    so `reviewInput` hands the review loop the truth rather than a clean-looking
+ *    summary.
+ *
+ * No I/O, no model calls: the orchestrator owns the children, this module owns the
+ * reading, exactly the split `findings.ts` and `fanout.ts` already use.
+ */
+import { claimCovers } from "./fanout.js";
+/** Cap on how many open findings are ever carried into a prompt or the residue. */
+const MAX_CARRIED_FINDINGS = 25;
+const key = (f) => `${f.file ?? ""}:${f.line ?? ""}:${f.message}`;
+/** Union findings in first-seen order, deduped by file + line + message. */
+export function mergeFindings(...groups) {
+    const seen = new Set();
+    const out = [];
+    for (const group of groups) {
+        for (const f of group) {
+            const k = key(f);
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            out.push(f);
+        }
+    }
+    return out;
+}
+/** Every defect this checker pass found: the scoped typechecks plus the full verify. */
+export function checkerFindings(report) {
+    return mergeFindings(report.scoped.flatMap((s) => s.findings), report.verify?.findings ?? []);
+}
+/** One finding as a line a builder can act on (mirrors the review loop's handoff shape). */
+export function renderFindings(findings) {
+    return findings
+        .slice(0, MAX_CARRIED_FINDINGS)
+        .map((f) => {
+        const loc = f.file ? `${f.file}${f.line != null ? `:${f.line}` : ""}` : "";
+        return `${f.severity} | ${loc} | ${f.message}`;
+    })
+        .join("\n");
+}
+/** One workstream's scoped-typecheck line, stating honestly whether it ran. */
+function scopedLine(s) {
+    if (!s.ran)
+        return `- ${s.name}: not checked (${s.reason ?? "no scoped build check"})`;
+    if (s.findings.length === 0)
+        return `- ${s.name}: clean (${s.command ?? "check"})`;
+    return `- ${s.name}: ${s.findings.length} finding${s.findings.length === 1 ? "" : "s"} (${s.command ?? "check"})`;
+}
+/** The full verify's one-line verdict, including the fail-open case. */
+function verifyLine(verify) {
+    if (!verify)
+        return "The full verify did not run on this pass.";
+    if (!verify.ran)
+        return `The full verify did not produce a verdict: ${verify.reason ?? "it could not run"}.`;
+    const label = verify.command ? ` (${verify.command})` : "";
+    if (verify.ok)
+        return `The full verify passed${label}.`;
+    return `The full verify failed${label}: ${verify.findings.length} finding${verify.findings.length === 1 ? "" : "s"}.`;
+}
+/**
+ * The synthesizer's `{previous}`: the fan's own handoff (which already names each
+ * workstream, its claims, and any out-of-claim edits) plus the checker's verdict,
+ * with a broken workstream attributed BY NAME so the reconciler knows where to look.
+ */
+export function composeSynthesizerInput(handoff, report) {
+    const parts = [handoff];
+    if (report.scoped.length > 0) {
+        parts.push(["## Checker: scoped typecheck per workstream", ...report.scoped.map(scopedLine)].join("\n"));
+    }
+    parts.push(`## Checker: full verify on the merged tree\n${verifyLine(report.verify)}`);
+    const findings = checkerFindings(report);
+    if (findings.length > 0) {
+        parts.push(`## Checker findings\n${renderFindings(findings)}`);
+    }
+    return parts.join("\n\n");
+}
+/** The workstream whose claims cover this finding's file, if exactly one does. */
+function ownerOf(finding, workstreams) {
+    const file = finding.file?.trim();
+    if (!file)
+        return undefined;
+    return workstreams.find((w) => w.files.some((claim) => claimCovers(claim, file)));
+}
+/**
+ * Route findings to the builders that can fix them: a finding whose file sits under
+ * a workstream's claims goes to that workstream (at its original tier), and anything
+ * else - no file, a file outside every claim, a seam between two workstreams - is
+ * unattributable and belongs to the synthesizer. With no workstreams (the
+ * single-writer path) everything is unassigned, which is exactly right: there is one
+ * builder and it owns the whole tree.
+ */
+export function attributeFindings(findings, workstreams) {
+    const assigned = [];
+    const unassigned = [];
+    for (const finding of findings) {
+        const owner = ownerOf(finding, workstreams);
+        if (!owner) {
+            unassigned.push(finding);
+            continue;
+        }
+        const existing = assigned.find((a) => a.workstream.name === owner.name);
+        if (existing)
+            existing.findings.push(finding);
+        else
+            assigned.push({ workstream: owner, findings: [finding] });
+    }
+    return { assigned, unassigned };
+}
+/** A heading line, at any depth: `## Open findings`. */
+const HEADING = /^#{1,6}\s+(.*)$/;
+/** `path/to/file.ts` or `path/to/file.ts:42` — a path token, not prose. */
+const PATH_SHAPE = /^[\w./@-]+\.[A-Za-z]{1,5}(?::\d+)?$/;
+/**
+ * The first path-shaped token in a synthesizer's finding line (backticked first,
+ * since that is how the persona writes paths), with any `:line` suffix dropped so
+ * it compares against claim prefixes. Undefined when the line names no file, which
+ * makes the finding unattributable and therefore the synthesizer's own.
+ */
+function pathIn(line) {
+    const quoted = [...line.matchAll(/`([^`]+)`/g)].map((m) => m[1].trim());
+    for (const token of [...quoted, ...line.split(/[\s,;()[\]]+/)]) {
+        const clean = token.replace(/[.,;:]+$/, "");
+        if (clean.includes("/") && PATH_SHAPE.test(clean))
+            return clean.replace(/:\d+$/, "");
+    }
+    return undefined;
+}
+/**
+ * The synthesizer's own "## Open findings" section (its persona output contract),
+ * as findings the fix loop can act on. "none" is a real answer and returns nothing;
+ * an absent section returns nothing too, because a summary that never claimed a
+ * defect is not evidence of one. Deliberately forgiving about the prose: what the
+ * loop needs is the line and, where the synthesizer named one, the file.
+ */
+export function parseOpenFindings(summary) {
+    const lines = summary.split("\n");
+    const start = lines.findIndex((l) => {
+        const m = l.trim().match(HEADING);
+        return m ? /^open findings\b/i.test(m[1].trim()) : false;
+    });
+    if (start < 0)
+        return [];
+    const body = [];
+    for (const raw of lines.slice(start + 1)) {
+        if (HEADING.test(raw.trim()))
+            break;
+        const line = raw.trim().replace(/^[-*]\s+/, "").trim();
+        if (line)
+            body.push(line);
+    }
+    if (body.length === 0)
+        return [];
+    if (body.length === 1 && /^none\b/i.test(body[0].replace(/[.*_`]/g, "")))
+        return [];
+    return body.slice(0, MAX_CARRIED_FINDINGS).map((line) => {
+        const file = pathIn(line);
+        const finding = {
+            severity: "critical",
+            lens: "does_it_hold",
+            message: `synthesizer: ${line}`,
+        };
+        if (file)
+            finding.file = file;
+        return finding;
+    });
+}
+/**
+ * The same "## Open findings" section {@link parseOpenFindings} reads, REMOVED
+ * from a summary (heading and body, up to the next heading of any depth).
+ *
+ * A fix turn that only re-engaged builders never re-runs the synthesizer, so its
+ * summary stays the handoff verbatim. Once those defects are answered and the
+ * re-check is clean, leaving the section in place would hand the review loop a
+ * document that names open defects in one paragraph and calls the final check
+ * clean in the next. Everything else the synthesizer wrote is untouched: this
+ * drops only the section the fix loop has since resolved.
+ */
+export function stripOpenFindings(summary) {
+    const lines = summary.split("\n");
+    const start = lines.findIndex((l) => {
+        const m = l.trim().match(HEADING);
+        return m ? /^open findings\b/i.test(m[1].trim()) : false;
+    });
+    if (start < 0)
+        return summary;
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        if (HEADING.test(lines[i].trim())) {
+            end = i;
+            break;
+        }
+    }
+    return [...lines.slice(0, start), ...lines.slice(end)].join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
+}
+/**
+ * What `reviewInput` says when the fix loop ran and then came back clean: the
+ * reviewers should know the candidate was repaired inside the implement stage, not
+ * that it was right first time. Absent when no fix turn ran, which keeps a
+ * clean-on-the-first-check run byte-identical to today's handoff.
+ */
+export function composeFixNote(turns) {
+    return [
+        "## Verification",
+        `${turns} fix pass${turns === 1 ? "" : "es"} ran inside the implement stage. The final check came back clean.`,
+    ].join("\n");
+}
+/**
+ * What `reviewInput` says when the fix cap is reached with defects still open
+ * (spec decision 7): named, not hidden, so the review loop picks them up knowing
+ * the implement stage already spent its turns on them.
+ */
+export function composeResidue(findings, turns) {
+    const header = turns === 0
+        ? "## Open findings from verification"
+        : `## Open findings after ${turns} fix pass${turns === 1 ? "" : "es"}`;
+    return [
+        header,
+        "Verification still reports these. They were not resolved inside the implement stage:",
+        renderFindings(findings),
+    ].join("\n");
+}
+//# sourceMappingURL=checker.js.map

package/dist/extension/pipeline/fanout.d.ts

@@ -0,0 +1,116 @@
+/**
+ * PURE partition contract for the implement diamond — the analogue of
+ * `findings.ts` for the fan-out orchestrator's output.
+ *
+ * `parsePartition` reads the orchestrator child's fenced ```partition JSON block
+ * and validates it against the contract (spec "Partition contract"): mode legal,
+ * width in {2,4,8} with a matching workstream count, per-workstream tier legal
+ * (absent defaults to `standard`), every workstream named + tasked with at least
+ * one file claim, and claims pairwise DISJOINT across workstreams.
+ *
+ * Two failure kinds, deliberately distinct because the pipeline treats them
+ * differently:
+ *  - SOFT (`hard: false`): malformed block, illegal field, missing reason. The
+ *    caller gets one cheap-tier format re-ask and then degrades to single-writer.
+ *    A partition is never guessed.
+ *  - HARD (`hard: true`): overlapping claims. Two writers on one file is the one
+ *    thing the design refuses to discover at merge time, so it fails the stage at
+ *    partition time with the colliding paths and workstreams named. The caller
+ *    (orchestrator) raises it as a `PipelineStageError`; keeping the throw out of
+ *    here keeps this module pure and free of an import cycle.
+ *
+ * `auditClaims` is the post-fan check: claims are path PREFIXES (a directory
+ * claims its whole subtree), so a file a builder legitimately created inside its
+ * claimed directory is in-claim, and anything else is named as a violation for
+ * the synthesizer to reconcile.
+ */
+import type { FanoutMode } from "./types.js";
+/** The tiers a workstream may run on: load-bearing work standard, mechanical work efficient. */
+export type WorkstreamTier = "standard" | "efficient";
+/**
+ * The `go.fanout` knob's environment surface (spec decision 8), named the way
+ * `YAGNI_GO_TIER_CAP` is (see tierCap.ts): a run-wide /go setting an eval or
+ * benchmark lane pins from the outside. `always` forces the diamond attempt;
+ * unset (everywhere else) leaves the partitioner's own conservative verdict as
+ * the only thing that decides.
+ */
+export declare const FANOUT_MODE_ENV = "YAGNI_GO_FANOUT";
+/**
+ * Parse a raw env value into a mode. Unset, empty, or unrecognized all yield
+ * undefined so a caller can warn about a typo; {@link resolveFanoutMode} is what
+ * turns that into the safe `auto` default. A typo must never pin a lane.
+ */
+export declare function parseFanoutMode(raw: string | undefined): FanoutMode | undefined;
+/** The run's fan-out mode from an environment. Defaults to `auto`. */
+export declare function resolveFanoutMode(env: NodeJS.ProcessEnv): FanoutMode;
+/** The only legal fan widths (execution concurrency is capped separately by the session). */
+export declare const PARTITION_WIDTHS: readonly [2, 4, 8];
+export type PartitionWidth = (typeof PARTITION_WIDTHS)[number];
+/** One workstream: a named, tasked builder with a disjoint set of prefix claims. */
+export interface PartitionWorkstream {
+    name: string;
+    task: string;
+    /** Normalized, deduped path prefixes; a directory claim covers its subtree. */
+    files: string[];
+    tier: WorkstreamTier;
+}
+/** The orchestrator's verdict: fan into workstreams, or run today's single writer. */
+export interface PartitionDecision {
+    mode: "fan" | "single";
+    /** Fan only; always equals `workstreams.length`. */
+    width?: PartitionWidth;
+    /** Always present: why this width, or why single-writer. */
+    reason: string;
+    /** Fan only. */
+    workstreams?: PartitionWorkstream[];
+}
+/** One pair of colliding claims across two workstreams. */
+export interface ClaimCollision {
+    path: string;
+    otherPath: string;
+    workstreams: [string, string];
+}
+/**
+ * Parse outcome. `ok: false` splits into the re-askable soft rejection and the
+ * hard overlap error (see the module comment).
+ */
+export type PartitionParse = {
+    ok: true;
+    decision: PartitionDecision;
+} | {
+    ok: false;
+    hard: false;
+    reason: string;
+} | {
+    ok: false;
+    hard: true;
+    reason: string;
+    collisions: ClaimCollision[];
+};
+/** Extract the inner text of a fenced ```partition block, if present. */
+export declare function extractPartitionBlock(raw: string): string | null;
+/**
+ * Normalize a claim or changed path for prefix comparison: trim, convert
+ * backslashes, collapse doubled slashes, drop interior `.` segments, a leading
+ * `./`, and trailing slashes. Purely lexical — no filesystem access. Without
+ * the collapse, `packages//backend` and `packages/./backend` pass disjointness
+ * against `packages/backend` while claiming the same directory — the exact
+ * two-writers-one-file outcome the partition-time hard error exists to prevent.
+ */
+export declare function normalizeClaimPath(path: string): string;
+/** True when `claim` is the path itself or a directory containing it. */
+export declare function claimCovers(claim: string, path: string): boolean;
+/**
+ * Parse the orchestrator's raw output into a {@link PartitionDecision}. Never
+ * throws: an unusable block is a soft rejection (re-ask, then single-writer) and
+ * overlapping claims are the hard rejection the caller turns into a stage error.
+ */
+export declare function parsePartition(raw: string): PartitionParse;
+/**
+ * Post-fan claim audit: the changed paths not covered by any workstream's claims,
+ * normalized, deduped, in first-seen order. Claims are prefixes, so a file created
+ * under a claimed directory is in-claim; anything else is a named violation the
+ * synthesizer reconciles.
+ */
+export declare function auditClaims(changedPaths: string[], workstreams: PartitionWorkstream[]): string[];
+//# sourceMappingURL=fanout.d.ts.map

package/dist/extension/pipeline/fanout.js

@@ -0,0 +1,248 @@
+/**
+ * PURE partition contract for the implement diamond — the analogue of
+ * `findings.ts` for the fan-out orchestrator's output.
+ *
+ * `parsePartition` reads the orchestrator child's fenced ```partition JSON block
+ * and validates it against the contract (spec "Partition contract"): mode legal,
+ * width in {2,4,8} with a matching workstream count, per-workstream tier legal
+ * (absent defaults to `standard`), every workstream named + tasked with at least
+ * one file claim, and claims pairwise DISJOINT across workstreams.
+ *
+ * Two failure kinds, deliberately distinct because the pipeline treats them
+ * differently:
+ *  - SOFT (`hard: false`): malformed block, illegal field, missing reason. The
+ *    caller gets one cheap-tier format re-ask and then degrades to single-writer.
+ *    A partition is never guessed.
+ *  - HARD (`hard: true`): overlapping claims. Two writers on one file is the one
+ *    thing the design refuses to discover at merge time, so it fails the stage at
+ *    partition time with the colliding paths and workstreams named. The caller
+ *    (orchestrator) raises it as a `PipelineStageError`; keeping the throw out of
+ *    here keeps this module pure and free of an import cycle.
+ *
+ * `auditClaims` is the post-fan check: claims are path PREFIXES (a directory
+ * claims its whole subtree), so a file a builder legitimately created inside its
+ * claimed directory is in-claim, and anything else is named as a violation for
+ * the synthesizer to reconcile.
+ */
+/**
+ * The `go.fanout` knob's environment surface (spec decision 8), named the way
+ * `YAGNI_GO_TIER_CAP` is (see tierCap.ts): a run-wide /go setting an eval or
+ * benchmark lane pins from the outside. `always` forces the diamond attempt;
+ * unset (everywhere else) leaves the partitioner's own conservative verdict as
+ * the only thing that decides.
+ */
+export const FANOUT_MODE_ENV = "YAGNI_GO_FANOUT";
+/**
+ * Parse a raw env value into a mode. Unset, empty, or unrecognized all yield
+ * undefined so a caller can warn about a typo; {@link resolveFanoutMode} is what
+ * turns that into the safe `auto` default. A typo must never pin a lane.
+ */
+export function parseFanoutMode(raw) {
+    const normalized = raw?.trim().toLowerCase();
+    if (normalized === "auto" || normalized === "always")
+        return normalized;
+    return undefined;
+}
+/** The run's fan-out mode from an environment. Defaults to `auto`. */
+export function resolveFanoutMode(env) {
+    return parseFanoutMode(env[FANOUT_MODE_ENV]) ?? "auto";
+}
+/** The only legal fan widths (execution concurrency is capped separately by the session). */
+export const PARTITION_WIDTHS = [2, 4, 8];
+const TIERS = ["standard", "efficient"];
+function soft(reason) {
+    return { ok: false, hard: false, reason };
+}
+/** Extract the inner text of a fenced ```partition block, if present. */
+export function extractPartitionBlock(raw) {
+    const m = raw.match(/```partition[^\n]*\n([\s\S]*?)```/i);
+    return m ? m[1] : null;
+}
+/**
+ * Normalize a claim or changed path for prefix comparison: trim, convert
+ * backslashes, collapse doubled slashes, drop interior `.` segments, a leading
+ * `./`, and trailing slashes. Purely lexical — no filesystem access. Without
+ * the collapse, `packages//backend` and `packages/./backend` pass disjointness
+ * against `packages/backend` while claiming the same directory — the exact
+ * two-writers-one-file outcome the partition-time hard error exists to prevent.
+ */
+export function normalizeClaimPath(path) {
+    return path
+        .trim()
+        .replace(/\\/g, "/")
+        .split("/")
+        .filter((segment) => segment.length > 0 && segment !== ".")
+        .join("/");
+}
+/** True when `claim` is the path itself or a directory containing it. */
+export function claimCovers(claim, path) {
+    const c = normalizeClaimPath(claim);
+    const p = normalizeClaimPath(path);
+    if (!c || !p)
+        return false;
+    return p === c || p.startsWith(`${c}/`);
+}
+/** Reject claims that escape the repo, are absolute, or claim everything. */
+function claimIsLegal(claim) {
+    if (!claim || claim === "." || claim.startsWith("/") || claim.startsWith("\\"))
+        return false;
+    return !normalizeClaimPath(claim).split("/").includes("..");
+}
+function readWorkstream(value, index) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return `workstream ${index + 1} is not an object`;
+    }
+    const obj = value;
+    const name = typeof obj.name === "string" ? obj.name.trim() : "";
+    if (!name)
+        return `workstream ${index + 1} has no name`;
+    const task = typeof obj.task === "string" ? obj.task.trim() : "";
+    if (!task)
+        return `workstream "${name}" has no task`;
+    if (!Array.isArray(obj.files))
+        return `workstream "${name}" has no file claims`;
+    const files = [];
+    for (const entry of obj.files) {
+        if (typeof entry !== "string")
+            return `workstream "${name}" has a non-string file claim`;
+        // Legality reads the RAW entry: normalization collapses the leading `/`
+        // (and `\`) markers legality has to see.
+        const claim = normalizeClaimPath(entry);
+        if (!claim || !claimIsLegal(entry.trim())) {
+            return `workstream "${name}" has an illegal file claim: ${entry}`;
+        }
+        if (!files.includes(claim))
+            files.push(claim);
+    }
+    if (files.length === 0)
+        return `workstream "${name}" has no file claims`;
+    let tier = "standard";
+    if (obj.tier !== undefined) {
+        if (typeof obj.tier !== "string" || !TIERS.includes(obj.tier)) {
+            return `workstream "${name}" has an illegal tier: ${String(obj.tier)}`;
+        }
+        tier = obj.tier;
+    }
+    return { name, task, files, tier };
+}
+/**
+ * Find every pair of claims that collide across two workstreams. Prefix nesting
+ * counts: a workstream claiming `packages/backend/src` collides with a sibling
+ * claiming `packages/backend/src/routes/x.ts`.
+ */
+function findCollisions(workstreams) {
+    const collisions = [];
+    for (let i = 0; i < workstreams.length; i += 1) {
+        for (let j = i + 1; j < workstreams.length; j += 1) {
+            for (const a of workstreams[i].files) {
+                for (const b of workstreams[j].files) {
+                    if (claimCovers(a, b) || claimCovers(b, a)) {
+                        collisions.push({
+                            path: a,
+                            otherPath: b,
+                            workstreams: [workstreams[i].name, workstreams[j].name],
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return collisions;
+}
+function collisionReason(collisions) {
+    const parts = collisions.map((c) => c.path === c.otherPath
+        ? `${c.path} claimed by both ${c.workstreams[0]} and ${c.workstreams[1]}`
+        : `${c.path} (${c.workstreams[0]}) contains ${c.otherPath} (${c.workstreams[1]})`);
+    return `Overlapping file claims: ${parts.join("; ")}`;
+}
+/** Pull the JSON payload out of a partition fence, a json fence, or bare output. */
+function extractPayload(raw) {
+    const partition = extractPartitionBlock(raw);
+    if (partition !== null)
+        return partition.trim();
+    const json = raw.match(/```json[^\n]*\n([\s\S]*?)```/i);
+    if (json)
+        return json[1].trim();
+    const trimmed = raw.trim();
+    return trimmed.startsWith("{") ? trimmed : null;
+}
+/**
+ * Parse the orchestrator's raw output into a {@link PartitionDecision}. Never
+ * throws: an unusable block is a soft rejection (re-ask, then single-writer) and
+ * overlapping claims are the hard rejection the caller turns into a stage error.
+ */
+export function parsePartition(raw) {
+    if (!raw || !raw.trim())
+        return soft("empty partition output");
+    const payload = extractPayload(raw);
+    if (payload === null)
+        return soft("no ```partition block in the output");
+    let parsed;
+    try {
+        parsed = JSON.parse(payload);
+    }
+    catch {
+        return soft("the partition block is not valid JSON");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return soft("the partition block is not a JSON object");
+    }
+    const obj = parsed;
+    const mode = obj.mode;
+    if (mode !== "fan" && mode !== "single") {
+        return soft(`illegal partition mode: ${String(mode)}`);
+    }
+    const reason = typeof obj.reason === "string" ? obj.reason.trim() : "";
+    if (!reason)
+        return soft("the partition block has no reason");
+    if (mode === "single")
+        return { ok: true, decision: { mode: "single", reason } };
+    const width = obj.width;
+    if (typeof width !== "number" || !PARTITION_WIDTHS.includes(width)) {
+        return soft(`illegal fan width: ${String(width)}`);
+    }
+    if (!Array.isArray(obj.workstreams))
+        return soft("a fan partition has no workstreams");
+    const workstreams = [];
+    for (const [index, entry] of obj.workstreams.entries()) {
+        const read = readWorkstream(entry, index);
+        if (typeof read === "string")
+            return soft(read);
+        if (workstreams.some((w) => w.name === read.name)) {
+            return soft(`duplicate workstream name: ${read.name}`);
+        }
+        workstreams.push(read);
+    }
+    if (workstreams.length !== width) {
+        return soft(`fan width ${width} does not match ${workstreams.length} workstreams`);
+    }
+    const collisions = findCollisions(workstreams);
+    if (collisions.length > 0) {
+        return { ok: false, hard: true, reason: collisionReason(collisions), collisions };
+    }
+    return {
+        ok: true,
+        decision: { mode: "fan", width: width, reason, workstreams },
+    };
+}
+/**
+ * Post-fan claim audit: the changed paths not covered by any workstream's claims,
+ * normalized, deduped, in first-seen order. Claims are prefixes, so a file created
+ * under a claimed directory is in-claim; anything else is a named violation the
+ * synthesizer reconciles.
+ */
+export function auditClaims(changedPaths, workstreams) {
+    const claims = workstreams.flatMap((w) => w.files);
+    const violations = [];
+    for (const raw of changedPaths) {
+        const path = normalizeClaimPath(raw);
+        if (!path)
+            continue;
+        if (claims.some((claim) => claimCovers(claim, path)))
+            continue;
+        if (!violations.includes(path))
+            violations.push(path);
+    }
+    return violations;
+}
+//# sourceMappingURL=fanout.js.map

package/dist/extension/pipeline/fanoutBeats.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The implement diamond's RECORDING thread: pipeline progress in, run-session
+ * stage beats out (spec "Recording and the run surface").
+ *
+ * The pipeline already says everything the run surface needs — the partition
+ * verdict, each builder starting and finishing, each bounded fix turn — on the
+ * `onProgress` channel. This folds that stream into the additive
+ * `fanout` / `children` / `fixTurns` payloads on `POST /runs/:id/stages`, so the
+ * web run surface can render per-workstream rows without the pipeline growing a
+ * second reporting path.
+ *
+ * PURE and I/O-free, like `findings.ts` and `fanout.ts`: `apply` returns the beat
+ * to send (or null when the signal is not the diamond's), and the caller decides
+ * whether to POST it. Two properties are load-bearing:
+ *
+ *  1. **Recorded states only.** A child row exists only once its `stage_start`
+ *     arrives, and it is `failed` only when the pipeline said the child died.
+ *     There is no invented "pending", and no tick nobody earned.
+ *  2. **Every beat is a copy.** The roster keeps mutating as children finish, so
+ *     a beat already handed to the (async, fail-soft) session must never change
+ *     underneath it.
+ */
+import type { StageArgs } from "./runSession.js";
+import type { PipelineProgress } from "./types.js";
+/** Folds the diamond's progress signals into the stage beats that record them. */
+export interface FanoutBeats {
+    /** The beat this signal produces, or null when it is not the diamond's. */
+    apply(p: PipelineProgress): StageArgs | null;
+}
+export declare function makeFanoutBeats(): FanoutBeats;
+//# sourceMappingURL=fanoutBeats.d.ts.map