@shiyuphan/follow-me 0.6.0 → 0.8.0

package/dist/src/coverage.js

@@ -0,0 +1,411 @@
+import { realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { isRepoPath, isSha, tipStartOf } from "./diff.js";
+import { GitError, pathsChanged } from "./git.js";
+import { isFields } from "./plan.js";
+/** lcov input that cannot be read, with the 1-based line it fails on. */
+export class LcovError extends Error {
+    name = "LcovError";
+    line;
+    constructor(line, reason) {
+        super(`lcov line ${line}: ${reason}`);
+        this.line = line;
+    }
+}
+const RECORD = /^([A-Z][A-Z0-9_]*):(.*)$/;
+const DA = /^([1-9][0-9]*),([0-9]+)(?:,.*)?$/;
+const BRDA = /^([1-9][0-9]*),([^,]+),(.+),(-|[0-9]+)$/;
+/**
+ * Reads lcov's tracefile format: TN names the test of the records after it, SF opens a file, DA
+ * and BRDA give line and branch hits, end_of_record closes it. Other records are skipped.
+ */
+export function parseLcov(text) {
+    const records = [];
+    let test = null;
+    let open = null;
+    const close = () => {
+        if (open !== null)
+            records.push(open);
+        open = null;
+    };
+    const rows = text.split("\n");
+    for (const [i, raw] of rows.entries()) {
+        const n = i + 1;
+        const row = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+        if (row.trim() === "")
+            continue;
+        if (row === "end_of_record") {
+            close();
+            continue;
+        }
+        const m = RECORD.exec(row);
+        if (m === null)
+            throw new LcovError(n, `"${row.slice(0, 60)}" is not an lcov record`);
+        const [, key = "", value = ""] = m;
+        if (key === "TN") {
+            test = value.trim() === "" ? null : value.trim();
+            continue;
+        }
+        if (key === "SF") {
+            close();
+            if (value === "")
+                throw new LcovError(n, "SF needs a path");
+            open = { path: value, test, lines: new Map(), branches: new Map() };
+            continue;
+        }
+        if (key !== "DA" && key !== "BRDA")
+            continue;
+        if (open === null)
+            throw new LcovError(n, `${key} comes before any SF`);
+        if (key === "DA") {
+            const da = DA.exec(value);
+            if (da === null)
+                throw new LcovError(n, `DA needs <line>,<hits>, got "${value}"`);
+            const line = Number(da[1]);
+            open.lines.set(line, (open.lines.get(line) ?? 0) + Number(da[2]));
+            continue;
+        }
+        const br = BRDA.exec(value);
+        if (br === null) {
+            throw new LcovError(n, `BRDA needs <line>,<block>,<branch>,<taken>, got "${value}"`);
+        }
+        const line = Number(br[1]);
+        const id = `${br[2]},${br[3]}`;
+        const taken = br[4] !== "-" && Number(br[4]) > 0;
+        const branches = open.branches.get(line) ?? new Map();
+        branches.set(id, (branches.get(id) ?? false) || taken);
+        open.branches.set(line, branches);
+    }
+    close();
+    if (records.length === 0)
+        throw new LcovError(rows.length, "no SF record; is this lcov?");
+    return records;
+}
+/**
+ * Where an lcov path is at the tip: absolute, or relative to cwd and failing that to the root,
+ * symlinks resolved, then relative to the root. Null outside the repo or for a file the tip lacks.
+ */
+export function tipPlacer(root, cwd, atTip) {
+    const real = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return p;
+        }
+    };
+    const tops = [root, real(root)];
+    return (raw) => {
+        const tried = isAbsolute(raw) ? [raw] : [resolve(cwd, raw), resolve(root, raw)];
+        for (const abs of tried.flatMap((p) => [p, real(p)])) {
+            for (const top of tops) {
+                const rel = relative(top, abs);
+                if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
+                    continue;
+                const path = Buffer.from(rel.split(sep).join("/"), "utf8").toString("latin1");
+                if (isRepoPath(path) && atTip.has(path))
+                    return path;
+            }
+        }
+        return null;
+    };
+}
+/** Sums hits and joins branches over records of the same file; drops what `place` rejects. */
+export function runOf(records, place) {
+    const lines = new Map();
+    const branches = new Map();
+    const tests = new Map();
+    for (const record of records) {
+        const path = place(record.path);
+        if (path === null)
+            continue;
+        const hits = lines.get(path) ?? new Map();
+        for (const [line, n] of record.lines)
+            hits.set(line, (hits.get(line) ?? 0) + n);
+        lines.set(path, hits);
+        const joined = branches.get(path) ?? new Map();
+        for (const [line, ids] of record.branches) {
+            const on = joined.get(line) ?? new Map();
+            for (const [id, taken] of ids)
+                on.set(id, (on.get(id) ?? false) || taken);
+            joined.set(line, on);
+        }
+        branches.set(path, joined);
+        if (record.test === null)
+            continue;
+        const ran = tests.get(record.test) ?? new Map();
+        const set = ran.get(path) ?? new Set();
+        for (const [line, n] of record.lines)
+            if (n > 0)
+                set.add(line);
+        ran.set(path, set);
+        tests.set(record.test, ran);
+    }
+    const files = new Map();
+    for (const [path, hits] of lines) {
+        const counted = new Map();
+        for (const [line, ids] of branches.get(path) ?? []) {
+            counted.set(line, [[...ids.values()].filter(Boolean).length, ids.size]);
+        }
+        files.set(path, { lines: sorted(hits), branches: sorted(counted) });
+    }
+    return {
+        files,
+        tests: new Map([...tests].map(([id, ran]) => [
+            id,
+            new Map([...ran].map(([path, set]) => [path, [...set].sort((a, b) => a - b)])),
+        ])),
+    };
+}
+function sorted(map) {
+    return new Map([...map].sort(([a], [b]) => a - b));
+}
+/** The lines of each file with at least one hit. */
+function hitLines(files) {
+    return new Map([...files].map(([path, f]) => [path, [...f.lines].flatMap(([l, n]) => (n > 0 ? [l] : []))]));
+}
+/**
+ * Per-test runs only add: a line keeps the larger count, so they never inflate an aggregate run
+ * of the same suite, and running the same test twice changes nothing.
+ */
+function mergeMax(a, b) {
+    const out = new Map(a);
+    for (const [path, f] of b) {
+        const had = out.get(path);
+        if (had === undefined) {
+            out.set(path, f);
+            continue;
+        }
+        const lines = new Map(had.lines);
+        for (const [l, n] of f.lines)
+            lines.set(l, Math.max(n, lines.get(l) ?? 0));
+        const branches = new Map(had.branches);
+        for (const [l, [taken, total]] of f.branches) {
+            const [t, n] = branches.get(l) ?? [0, 0];
+            branches.set(l, [Math.max(taken, t), Math.max(total, n)]);
+        }
+        out.set(path, { lines: sorted(lines), branches: sorted(branches) });
+    }
+    return out;
+}
+/** How many tip lines a test outside the branch's changes carries for the page's peek. */
+export const PREVIEW_LINES = 8;
+/**
+ * The coverage after this run. A plain run replaces everything, its TN blocks becoming its tests.
+ * A named test's run adds to what is already there for the same tip, and starts over otherwise.
+ */
+export function recordRun(prior, run, at) {
+    const { tip, takenAt, test } = at;
+    if (test === undefined) {
+        const tests = new Map([...run.tests].map(([id, lines]) => [id, { lines }]));
+        return { tip, takenAt, files: run.files, tests };
+    }
+    const base = prior !== null && prior.tip === tip ? prior : null;
+    const tests = new Map(base?.tests ?? []);
+    const entry = {
+        ...(test.at === undefined ? {} : { at: test.at }),
+        ...(test.preview === undefined ? {} : { preview: test.preview }),
+        lines: hitLines(run.files),
+    };
+    tests.set(test.id, entry);
+    const files = base === null ? run.files : mergeMax(base.files, run.files);
+    return { tip, takenAt, files, tests };
+}
+/**
+ * Per file, the branch's added rows that lcov calls executable, and how many ran. Every added
+ * row is a tip line, which is where the run was taken. Files without such rows are left out.
+ */
+export function changedLines(units, files) {
+    const out = new Map();
+    for (const unit of units.values()) {
+        if (unit.kind !== "hunk")
+            continue;
+        const file = files.get(unit.path);
+        if (file === undefined)
+            continue;
+        let line = tipStartOf(unit, units);
+        let { covered, executable } = out.get(unit.path) ?? { covered: 0, executable: 0 };
+        for (const row of unit.body) {
+            const hits = row.op === "+" ? file.lines.get(line) : undefined;
+            if (hits !== undefined) {
+                executable += 1;
+                if (hits > 0)
+                    covered += 1;
+            }
+            if (row.op !== "-")
+                line += 1;
+        }
+        if (executable > 0)
+            out.set(unit.path, { covered, executable });
+    }
+    return out;
+}
+export function totalOf(tallies) {
+    let covered = 0;
+    let executable = 0;
+    for (const t of tallies) {
+        covered += t.covered;
+        executable += t.executable;
+    }
+    return { covered, executable };
+}
+/**
+ * Covered files whose content at `tip` differs from where the run was taken, in file order.
+ * When the run's commit is gone from the repo, every file is stale.
+ */
+export async function staleFiles(repo, coverage, tip) {
+    if (coverage.tip === tip)
+        return [];
+    let changed;
+    try {
+        changed = await pathsChanged(repo, coverage.tip, tip);
+    }
+    catch (error) {
+        if (!(error instanceof GitError))
+            throw error;
+        changed = new Set(coverage.files.keys());
+    }
+    return [...coverage.files.keys()].filter((p) => changed.has(p));
+}
+/** The files whose coverage still describes the tip. */
+export function freshFiles(coverage, stale) {
+    const gone = new Set(stale);
+    return new Map([...coverage.files].filter(([path]) => !gone.has(path)));
+}
+export function serializeCoverage(c) {
+    const files = Object.fromEntries([...c.files].map(([path, f]) => [
+        path,
+        {
+            lines: Object.fromEntries(f.lines),
+            ...(f.branches.size === 0 ? {} : { branches: Object.fromEntries(f.branches) }),
+        },
+    ]));
+    const tests = Object.fromEntries([...c.tests].map(([id, t]) => [
+        id,
+        {
+            ...(t.at === undefined ? {} : { at: t.at }),
+            ...(t.preview === undefined ? {} : { preview: [...t.preview] }),
+            lines: Object.fromEntries([...t.lines].map(([p, ls]) => [p, [...ls]])),
+        },
+    ]));
+    return { tip: c.tip, takenAt: c.takenAt, files, ...(c.tests.size === 0 ? {} : { tests }) };
+}
+const LINE_KEY = /^[1-9][0-9]*$/;
+function isCount(v) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 0;
+}
+function isLine(v) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 1;
+}
+function entries(v) {
+    return isFields(v) ? Object.entries(v) : null;
+}
+/** A { path, start, end } with 1 <= start <= end, or null. */
+export function parseLoc(v) {
+    if (!isFields(v))
+        return null;
+    const { path, start, end } = v;
+    if (typeof path !== "string" || !isRepoPath(path) || !isLine(start) || !isLine(end))
+        return null;
+    return end < start ? null : { path, start, end };
+}
+/** Like parseLoc, for argv: "path:line" or "path:start-end", the path placed like lcov's. */
+export function parseLocArg(raw, place) {
+    const m = /^(.+):([1-9][0-9]*)(?:-([1-9][0-9]*))?$/.exec(raw);
+    if (m === null)
+        return `--at ${raw} is not <path>:<line> or <path>:<start>-<end>`;
+    const path = place(m[1] ?? "");
+    if (path === null)
+        return `--at ${raw} names no file of the branch tip`;
+    const start = Number(m[2]);
+    const end = m[3] === undefined ? start : Number(m[3]);
+    return end < start ? `--at ${raw} runs backwards` : { path, start, end };
+}
+function parseFile(v) {
+    if (!isFields(v))
+        return "a file is not an object";
+    const lines = entries(v.lines);
+    if (lines === null)
+        return "lines is not an object";
+    const hits = new Map();
+    for (const [key, n] of lines) {
+        if (!LINE_KEY.test(key) || !isCount(n))
+            return `line ${key} has no hit count`;
+        hits.set(Number(key), n);
+    }
+    const branchEntries = entries(v.branches ?? {});
+    if (branchEntries === null)
+        return "branches is not an object";
+    const branches = new Map();
+    for (const [key, pair] of branchEntries) {
+        if (!LINE_KEY.test(key) || !Array.isArray(pair) || pair.length !== 2) {
+            return `branches of line ${key} are not [taken, total]`;
+        }
+        const [taken, total] = pair;
+        if (!isCount(taken) || !isCount(total) || taken > total) {
+            return `branches of line ${key} are not [taken, total]`;
+        }
+        branches.set(Number(key), [taken, total]);
+    }
+    return { lines: sorted(hits), branches: sorted(branches) };
+}
+function parseTest(v) {
+    if (!isFields(v))
+        return "a test is not an object";
+    const at = v.at === undefined ? undefined : parseLoc(v.at);
+    if (at === null)
+        return "at is not a { path, start, end }";
+    const preview = v.preview;
+    if (preview !== undefined &&
+        !(Array.isArray(preview) && preview.every((l) => typeof l === "string"))) {
+        return "preview is not a list of lines";
+    }
+    const lineEntries = entries(v.lines);
+    if (lineEntries === null)
+        return "lines is not an object";
+    const lines = new Map();
+    for (const [path, list] of lineEntries) {
+        if (!isRepoPath(path) || !Array.isArray(list) || !list.every(isLine)) {
+            return `lines of ${path} are not line numbers`;
+        }
+        lines.set(path, list);
+    }
+    return {
+        ...(at === undefined ? {} : { at }),
+        ...(preview === undefined ? {} : { preview: preview.filter((l) => typeof l === "string") }),
+        lines,
+    };
+}
+/** The one place coverage.json becomes a Coverage. */
+export function parseCoverage(v) {
+    if (!isFields(v))
+        return "not an object";
+    const { tip, takenAt } = v;
+    if (typeof tip !== "string" || !isSha(tip))
+        return "tip is not an object id";
+    if (typeof takenAt !== "string")
+        return "takenAt is not a time";
+    const fileEntries = entries(v.files);
+    if (fileEntries === null)
+        return "files is not an object";
+    const files = new Map();
+    for (const [path, raw] of fileEntries) {
+        if (!isRepoPath(path))
+            return "a file has no path";
+        const file = parseFile(raw);
+        if (typeof file === "string")
+            return `${path}: ${file}`;
+        files.set(path, file);
+    }
+    const testEntries = entries(v.tests ?? {});
+    if (testEntries === null)
+        return "tests is not an object";
+    const tests = new Map();
+    for (const [id, raw] of testEntries) {
+        const test = parseTest(raw);
+        if (typeof test === "string")
+            return `test ${id}: ${test}`;
+        tests.set(id, test);
+    }
+    return { tip, takenAt, files, tests };
+}

package/dist/src/git.js

@@ -132,6 +132,24 @@ export async function blobsAt(repo, commit, paths) {
     const blobs = await catBatch(repo, paths.map((p) => `${commit}:${p}`));
     return new Map(paths.map((p, i) => [p, blobs[i] ?? ""]));
 }
+function pathList(out) {
+    return new Set(out
+        .toString("latin1")
+        .split("\0")
+        .filter((p) => isRepoPath(p)));
+}
+/** Every file path in the commit's tree. */
+export async function pathsAt(repo, commit) {
+    return pathList(await git(repo, ["ls-tree", "-r", "-z", "--name-only", commit]));
+}
+/**
+ * Paths whose content differs between the commit and `to`: another commit, or with null the
+ * working tree and index. Untracked files are not listed.
+ */
+export async function pathsChanged(repo, from, to) {
+    const target = to === null ? [] : [to];
+    return pathList(await git(repo, ["diff", "--name-only", "-z", ...DIFF_FLAGS, from, ...target, "--"]));
+}
 /**
  * Lines of the commit's tree, not the working tree, that match any of the POSIX extended
  * patterns, in files matching the pathspecs. Binary files are skipped.

package/dist/src/host.js

@@ -320,6 +320,29 @@ export async function fetchComments(port, summary) {
     }
     return out;
 }
+/**
+ * Offers accepted during the hosted review, on this version or a carried one, whose comment has no
+ * reply from the agent yet, oldest first.
+ */
+export async function fetchWaitingOffers(port, summary) {
+    const state = await call(port, "GET", `${summary.url}api/state`);
+    if (!isFields(state))
+        throw new RegistrationError("the server sent no state");
+    const comments = Array.isArray(state["comments"]) ? state["comments"] : [];
+    const carried = Array.isArray(state["carried"]) ? state["carried"] : [];
+    const said = [
+        ...comments.map((raw) => parseComment(raw)),
+        ...carried.map((raw) => {
+            const c = parseCarried(raw);
+            return typeof c === "string" ? c : c.comment;
+        }),
+    ];
+    return said
+        .flatMap((c) => (typeof c === "string" ? [] : [c]))
+        .filter((c) => !(c.replies ?? []).some((r) => r.author === "agent"))
+        .sort((a, b) => a.createdAt.localeCompare(b.createdAt))
+        .flatMap((c) => (c.offer === undefined ? [] : [{ offer: c.offer, comment: c.id }]));
+}
 /** One long poll of the session's event log: what happened after `since`, or nothing at timeout. */
 export async function pollEvents(port, summary, since, timeoutMs) {
     const path = `${summary.url}api/events?since=${since}&timeout=${timeoutMs}`;
@@ -373,6 +396,10 @@ export async function postComment(port, summary, comment) {
     }
     return id;
 }
+/** Tells the hosted page that coverage.json changed, so it reloads its marks. */
+export async function postCoverage(port, summary) {
+    await call(port, "POST", `${summary.url}api/coverage`);
+}
 /** The consolidated report of the hosted session as it stands. */
 export async function fetchReport(port, summary, format = "markdown") {
     const res = await fetch(`${sessionUrl(port, summary)}api/report?format=${format}`);

package/dist/src/plan.js

@@ -10,6 +10,12 @@ export function isCommentId(s) {
 export function isConcernId(s) {
     return typeof s === "string" && /^k_[0-9a-f]{8}$/.test(s);
 }
+export function isOfferId(s) {
+    return typeof s === "string" && /^o_[0-9a-f]{8}$/.test(s);
+}
+/** At most this many offers in one commit and in the whole plan; most plans need none. */
+export const OFFERS_PER_COMMIT = 1;
+export const OFFERS_PER_PLAN = 3;
 export function isPlanVersion(n) {
     return typeof n === "number" && Number.isInteger(n) && n >= 1;
 }
@@ -29,6 +35,10 @@ export function isSeverity(s) {
 function isConcernKind(s) {
     return CONCERN_KINDS.some((x) => x === s);
 }
+const OFFER_KINDS = ["state-machine", "sequence", "diagram"];
+function isOfferKind(s) {
+    return OFFER_KINDS.some((x) => x === s);
+}
 /** Narrows to an object whose named fields are still unknown, which holds for any object. */
 export function isFields(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
@@ -123,7 +133,47 @@ function parseConcerns(v, onUnit) {
     }
     return out;
 }
-/** The optional narration, diagram and concerns of a commit or unit entry, or what is wrong. */
+/** An offer is { kind, label }; the label names the thing to draw. */
+function parseOffer(v) {
+    if (!isFields(v))
+        return "expected an object";
+    if (!isOfferKind(v.kind))
+        return `kind: expected one of ${OFFER_KINDS.join(", ")}`;
+    if (typeof v.label !== "string" || v.label.trim() === "") {
+        return 'label: expected what to draw, like "Draw UploadButton as a state machine"';
+    }
+    return { kind: v.kind, label: v.label };
+}
+/** A stored offer as validation placed it: with its id and its unit. */
+export function parsePlacedOffer(v) {
+    if (!isFields(v))
+        return "expected an object";
+    if (!isOfferId(v.id))
+        return "id: expected an offer id";
+    if (v.unit !== undefined && !(typeof v.unit === "string" && isUnitId(v.unit))) {
+        return "unit: expected a unit id";
+    }
+    const offer = parseOffer(v);
+    if (typeof offer === "string")
+        return offer;
+    return { ...offer, id: v.id, ...(v.unit === undefined ? {} : { unit: v.unit }) };
+}
+/** Absent, null and [] all mean no offers. */
+function parseOffers(v) {
+    if (v === undefined || v === null)
+        return [];
+    if (!isArray(v))
+        return "expected an array";
+    const out = [];
+    for (const [i, raw] of v.entries()) {
+        const offer = parseOffer(raw);
+        if (typeof offer === "string")
+            return `[${i}]: ${offer}`;
+        out.push(offer);
+    }
+    return out;
+}
+/** The optional narration, diagram, concerns and offers of a commit or unit entry, or what is wrong. */
 function parseExtras(v, onUnit) {
     const narration = parseText(v.narration);
     if (narration === INVALID)
@@ -137,7 +187,13 @@ function parseExtras(v, onUnit) {
     const concerns = parseConcerns(v.concerns, onUnit);
     if (typeof concerns === "string")
         return { field: "concerns", error: concerns };
-    return withExtras(narration, diagram, concerns);
+    const offers = parseOffers(v.offers);
+    if (typeof offers === "string")
+        return { field: "offers", error: offers };
+    return {
+        ...withExtras(narration, diagram, concerns),
+        ...(offers.length === 0 ? {} : { offers }),
+    };
 }
 function withText(narration, diagram) {
     return {
@@ -160,15 +216,21 @@ function serializeExtras(x) {
     return {
         ...withText(x.narration ?? null, x.diagram ?? null),
         ...(x.concerns === undefined ? {} : { concerns: x.concerns.map(serializeConcern) }),
+        ...(x.offers === undefined
+            ? {}
+            : { offers: x.offers.map((o) => ({ kind: o.kind, label: o.label })) }),
     };
 }
-/** A unit entry is "h_x:0-3" or { "unit": "h_x:0-3", "narration", "diagram", "concerns" }. */
+/**
+ * A unit entry is "h_x:0-3" or { "unit": "h_x:0-3", "narration", "diagram", "concerns", "offers" }.
+ */
 function parseUnitEntry(u) {
     if (typeof u === "string")
         return parseUnitRef(u);
-    if (!isFields(u) || typeof u.unit !== "string") {
+    if (!isFields(u) ||
+        typeof u.unit !== "string") {
         return {
-            error: 'expected a unit ref string or { "unit", "narration", "diagram", "concerns" }',
+            error: 'expected a unit ref string or { "unit", "narration", "diagram", "concerns", "offers" }',
         };
     }
     const ref = parseUnitRef(u.unit);
@@ -298,7 +360,10 @@ export function serializePlanFile(file) {
             message: c.message,
             ...(c.section === undefined ? {} : { section: c.section }),
             ...serializeExtras(c),
-            units: c.units.map((ref) => ref.narration === undefined && ref.diagram === undefined && ref.concerns === undefined
+            units: c.units.map((ref) => ref.narration === undefined &&
+                ref.diagram === undefined &&
+                ref.concerns === undefined &&
+                ref.offers === undefined
                 ? formatUnitRef(ref)
                 : { unit: formatUnitRef(ref), ...serializeExtras(ref) }),
         })),
@@ -547,8 +612,51 @@ function placeConcerns(diff, file, claims, issues) {
     }
     return placedPerCommit;
 }
+/** "o_" + 8 hex over the unit and the label: stable while the offer stays at its place. */
+function deriveOfferId(unit, o) {
+    const hex = createHash("sha256")
+        .update(`offer\0${unit ?? ""}\0${o.label}`)
+        .digest("hex")
+        .slice(0, 8);
+    const id = `o_${hex}`;
+    if (!isOfferId(id))
+        throw new Error(`sha256 produced ${id}`);
+    return id;
+}
+/** Gives every offer its id: the commit's own first, then those of its unit refs in order. */
+function placeOffers(file, issues) {
+    const ids = new Set();
+    return file.commits.map((commit, k) => {
+        const placed = [];
+        const add = (o, unit) => {
+            const id = deriveOfferId(unit, o);
+            if (ids.has(id)) {
+                issues.push({ kind: "bad-offer", commit: k, reason: `${id} repeats another offer` });
+                return;
+            }
+            ids.add(id);
+            placed.push({ ...o, id, ...(unit === null ? {} : { unit }) });
+        };
+        for (const o of commit.offers ?? [])
+            add(o, null);
+        for (const ref of commit.units)
+            for (const o of ref.offers ?? [])
+                add(o, ref.unit);
+        return placed;
+    });
+}
+/** At most OFFERS_PER_COMMIT in a commit, its units' included, and OFFERS_PER_PLAN in all. */
+function offerLimits(file) {
+    const counts = file.commits.map((c) => (c.offers ?? []).length + c.units.reduce((n, r) => n + (r.offers ?? []).length, 0));
+    const issues = counts.flatMap((count, commit) => count > OFFERS_PER_COMMIT ? [{ kind: "too-many-offers", commit, count }] : []);
+    const total = counts.reduce((a, b) => a + b, 0);
+    if (total > OFFERS_PER_PLAN)
+        issues.push({ kind: "too-many-offers", commit: null, count: total });
+    return issues;
+}
 function project(diff, file, claims, issues) {
     const concerns = placeConcerns(diff, file, claims, issues);
+    const offers = placeOffers(file, issues);
     const { stateAt, tipOf } = projector(diff, claims.owners);
     const present = new Map();
     for (const f of diff.textFiles.values())
@@ -560,6 +668,7 @@ function project(diff, file, claims, issues) {
     const commits = file.commits.map((commit, k) => {
         const refs = claims.resolved[k] ?? [];
         const mine = concerns[k] ?? [];
+        const offered = offers[k] ?? [];
         const touched = [...new Set(refs.flatMap((r) => diff.units.get(r.unit)?.path ?? []))].sort();
         const changes = touched.map((path) => {
             const state = stateAt(path, k);
@@ -591,6 +700,7 @@ function project(diff, file, claims, issues) {
             ...(commit.section === undefined ? {} : { section: commit.section }),
             ...withText(commit.narration ?? null, commit.diagram ?? null),
             ...(mine.length === 0 ? {} : { concerns: mine }),
+            ...(offered.length === 0 ? {} : { offers: offered }),
             refs,
             changes,
         };
@@ -655,6 +765,7 @@ export function validatePlan(diff, draft, opts = {}) {
         if (c.units.length === 0)
             issues.push({ kind: "empty-commit", commit: k });
     });
+    issues.push(...offerLimits(file));
     const assignment = [];
     const claims = claim(diff, file, assignment);
     issues.push(...assignment);
@@ -677,6 +788,17 @@ export function validatePlan(diff, draft, opts = {}) {
         if (length > LONG_TITLE)
             warnings.push({ kind: "long-title", commit, length });
     });
+    // Sections read top-down: story, steps, details, wiring. A later section never comes back.
+    let reached = null;
+    file.commits.forEach((c, commit) => {
+        if (c.section === undefined)
+            return;
+        if (reached !== null && SECTIONS.indexOf(c.section) < SECTIONS.indexOf(reached)) {
+            warnings.push({ kind: "section-order", commit, section: c.section, after: reached });
+        }
+        else
+            reached = c.section;
+    });
     const asked = new Map(review?.comments.map((c) => [c.id, c.kind === "question"]));
     for (const r of file.responses) {
         const isQuestion = asked.get(r.comment);