@cspeach/cli 1.1.29 → 1.1.31

package/dist/register/findings.js

@@ -0,0 +1,82 @@
+/**
+ * Rule by rule, what the runs found in each object — the detail the register
+ * itself keeps only as counts. Read from the same measurement records, with the
+ * register's own two rules: only the team project's check variant counts, and
+ * live evidence outranks file evidence, per object.
+ *
+ * Used by `cspeach team fixed` (which rules are open now) and by the read-only
+ * team_findings tool (what a triage proposes from). No source code is in here:
+ * a record carries a rule id and a message title, nothing more.
+ */
+import { normalizeKey, normalizeRuleId, UNNAMED_FINDING } from '@cspeach/register-core';
+import { shown } from './atc-file.js';
+import { collectRecords, readProjectFile } from './store.js';
+/** Re-exported for the read-only team_findings tool: the one cleaning, a longer cap. */
+export { shownUpTo } from './atc-file.js';
+const variantKey = (v) => (typeof v === 'string' ? v.trim().toUpperCase() : '');
+const basisOf = (v) => {
+    if (v === undefined || v === null)
+        return 'system';
+    const w = String(v).trim().toLowerCase();
+    return w === '' || w === 'system' ? 'system' : 'file';
+};
+export function findingsByObject(projectDir, outboxDir, opts = {}) {
+    const project = readProjectFile(projectDir);
+    const ours = variantKey(project.atcVariant);
+    const records = [
+        ...collectRecords(projectDir).records,
+        ...(outboxDir && outboxDir !== projectDir ? collectRecords(outboxDir).records : []),
+    ];
+    const runs = records
+        .filter((r) => r?.kind === 'record' && r.recordType === 'measurement' && r.projectId === project.projectId
+        && typeof r.recordId === 'string' && Number.isFinite(Date.parse(r.at)) && Array.isArray(r.rows))
+        .filter((r) => { const theirs = variantKey(r.atcVariant); return !(theirs && ours && theirs !== ours); })
+        .map((r) => ({ ...r, at: new Date(r.at).toISOString() }))
+        .sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : a.recordId < b.recordId ? -1 : a.recordId > b.recordId ? 1 : 0));
+    const seenIds = new Set();
+    const byKey = new Map();
+    for (const r of runs) {
+        if (seenIds.has(r.recordId))
+            continue; // a sync tool's "(1)" copy
+        seenIds.add(r.recordId);
+        for (const row of r.rows) {
+            if (typeof row?.key !== 'string' || !Array.isArray(row.findings))
+                continue;
+            const key = normalizeKey(row.key);
+            const list = byKey.get(key) ?? [];
+            let seen = list.find((s) => s.recordId === r.recordId);
+            if (!seen) {
+                seen = { at: r.at, recordId: r.recordId, basis: basisOf(r.basis), rules: new Map() };
+                list.push(seen);
+            }
+            for (const f of row.findings) {
+                const named = !!f && typeof f === 'object';
+                const rule = (named ? normalizeRuleId(f.rule) : typeof f === 'string' ? normalizeRuleId(f) : '') || UNNAMED_FINDING;
+                // `shown()`: the title was written on another laptop or came out of a
+                // handed-over file, and it goes to a terminal and to the model's tools.
+                const message = named && typeof f.message === 'string' ? shown(f.message) : '';
+                const had = seen.rules.get(rule);
+                const line = opts.lines && named && Number.isInteger(f.line) && f.line > 0 ? f.line : undefined;
+                if (had) {
+                    had.count += 1;
+                    if (!had.message && message)
+                        had.message = message;
+                    if (line !== undefined && (had.line === undefined || line < had.line))
+                        had.line = line;
+                }
+                else
+                    seen.rules.set(rule, { rule, message, count: 1, ...(line !== undefined ? { line } : {}) });
+            }
+            byKey.set(key, list);
+        }
+    }
+    const out = new Map();
+    for (const [key, list] of byKey) {
+        const driving = list.some((s) => s.basis === 'system') ? list.filter((s) => s.basis === 'system') : list;
+        const first = driving[0] ?? null;
+        const last = driving[driving.length - 1] ?? null;
+        const rules = (s) => (s ? [...s.rules.values()].sort((a, b) => (a.rule < b.rule ? -1 : a.rule > b.rule ? 1 : 0)) : []);
+        out.set(key, { key, baselineAt: first?.at ?? null, baseline: rules(first), latestAt: last?.at ?? null, latest: rules(last) });
+    }
+    return out;
+}

package/dist/register/measure.js

@@ -39,6 +39,8 @@ import { writeRecord } from './records.js';
  * row they get says so.
  */
 export const ABSENT_MEANS_CLEAN = false;
+/** R-1: how many silent objects one measurement checks again, one run each. */
+export const MAX_SECOND_PASS = 200;
 export function scopeLabel(scope) {
     if (scope.kind === 'lane')
         return `lane:${scope.id.trim()}`;
@@ -257,6 +259,7 @@ function readOutcome(answer) {
     return o;
 }
 export async function measure(input) {
+    const started = Date.now();
     const label = scopeLabel(input.scope);
     // One object, one row, however often the baseline names it: a case-twin would
     // otherwise be asked for twice and counted twice.
@@ -326,6 +329,60 @@ export async function measure(input) {
         if (!(said === 'absent' && evidenceOf.get(key) === 'listed'))
             evidenceOf.set(key, said);
     }
+    // ── R-1: the objects the run did not list, each checked again on its own ──
+    let secondPass;
+    let notChecked = new Set();
+    let ownFindings = [];
+    if (input.confirmAbsent && !absentMeansClean && !outcome.stopped && !input.signal?.aborted) {
+        const silent = inScope.filter((o) => buckets.get(objectKey(o.type, o.name)) === 'absent');
+        if (silent.length) {
+            const toRun = silent.slice(0, Math.max(0, input.secondPassCap ?? MAX_SECOND_PASS));
+            const skipped = silent.slice(toRun.length).map((o) => objectKey(o.type, o.name));
+            const left = input.maxTotalMs ? input.maxTotalMs - (Date.now() - started) : undefined;
+            if (toRun.length && (left === undefined || left > 0)) {
+                const again = readOutcome(await input.atc.runSet(toRun.map((o) => ({ type: o.type, name: o.name })), variant, {
+                    chunkSize: 1, maxSingleRuns: 0,
+                    ...(input.signal ? { signal: input.signal } : {}),
+                    ...(left !== undefined ? { maxTotalMs: left } : {}),
+                    ...(input.onProgress ? { onProgress: input.onProgress } : {}),
+                }));
+                const asked = new Set(toRun.map((o) => objectKey(o.type, o.name)));
+                // Only a run that LISTED the object counts. A refused or cut-short own run
+                // leaves it exactly where the first run left it: absent, no row.
+                const seen = new Set(again.measured.filter((m) => m?.evidence === 'listed').map(refKey).filter((k) => asked.has(k)));
+                for (const key of seen) {
+                    claims.get(key)?.delete('absent');
+                    claim(key, 'measured');
+                    buckets.set(key, 'measured');
+                    evidenceOf.set(key, 'listed');
+                }
+                ownFindings = again.findings.filter((f) => typeof f?.key === 'string' && seen.has(normalizeKey(f.key)));
+                // An own run that FINISHED and still did not list the object is the
+                // variant's silence, said twice. Anything else — refused, never reached —
+                // was not checked again, and nothing may be said about why.
+                const didNotFinish = new Set([
+                    ...again.failed.map(refKey),
+                    ...again.chunks.filter((c) => c?.status === 'refused' && !c.superseded).flatMap((c) => list(c.asked).map(refKey)),
+                ]);
+                const silentAgain = new Set(again.measured.filter((m) => m?.evidence !== 'listed').map(refKey)
+                    .filter((k) => asked.has(k) && !seen.has(k) && !didNotFinish.has(k)));
+                const unreached = [...asked].filter((k) => !seen.has(k) && !silentAgain.has(k));
+                const stopped = STOPPED_BY.has(again.stopped) ? again.stopped
+                    : input.signal?.aborted ? 'aborted' : undefined;
+                notChecked = new Set([...unreached, ...skipped]);
+                secondPass = {
+                    asked: toRun.length, listed: seen.size, skipped: skipped.length,
+                    ...(skipped.length ? { skippedBy: 'cap' } : {}),
+                    ...(unreached.length ? { notChecked: unreached.length } : {}),
+                    ...(stopped ? { stopped } : {}),
+                };
+            }
+            else {
+                notChecked = new Set(silent.map((o) => objectKey(o.type, o.name)));
+                secondPass = { asked: 0, listed: 0, skipped: silent.length, skippedBy: toRun.length ? 'time' : 'cap' };
+            }
+        }
+    }
     // Row order follows the scope, so two runs of the same lane read the same way.
     const rowRefs = inScope.filter((o) => buckets.get(objectKey(o.type, o.name)) === 'measured')
         .map((o) => ({ type: o.type, name: o.name, ...(evidenceOf.get(objectKey(o.type, o.name)) ? { evidence: evidenceOf.get(objectKey(o.type, o.name)) } : {}) }));
@@ -347,10 +404,11 @@ export async function measure(input) {
         ...coverage, unsupportedNames, absentNames, scope: label, refusedChunks,
         ...(duplicates ? { duplicateFindingsMerged: duplicates } : {}),
         ...(stoppedBy ? { stoppedBy } : {}),
+        ...(secondPass ? { secondPass, notCheckedNames: keysInScope.filter((k) => notChecked.has(k)).slice(0, MAX_ABSENT_NAMES) } : {}),
     };
     if (!rowRefs.length)
         return { ...counts, file: null, withFindings: 0, refusedRows };
-    const rows = findingsToRows(rowRefs, outcome.findings, input.project.type);
+    const rows = findingsToRows(rowRefs, [...outcome.findings, ...ownFindings], input.project.type);
     const res = writeRecord(input.joined, 'measurement', rows, input.by, {
         ...(input.now ? { now: input.now } : {}), ...(input.dir ? { dir: input.dir } : {}),
         ...(input.fileName ? { fileName: input.fileName } : {}), ...(input.rand ? { rand: input.rand } : {}),
@@ -361,6 +419,7 @@ export async function measure(input) {
         // below are recomputed after the refusal and are the ones a caller prints.
         extra: {
             atcVariant: variant, scope: label, basis: 'system', coverage,
+            ...(secondPass ? { secondPass } : {}),
             ...(duplicates ? { duplicateFindingsMerged: duplicates } : {}),
         },
     });

package/dist/register/offer.js

@@ -0,0 +1,125 @@
+/**
+ * The line CSPeach prints after it activated, and verified, an object of the
+ * team project this laptop has joined (spec §4.3).
+ *
+ * 1.1.31 (owner, 2026-10-07: "why would developers claim it when CSPeach is
+ * working?"): when CSPeach itself wrote the object's source in this session,
+ * the fix is recorded for the developer — the claim covers every rule open at
+ * the object's last measurement, with the transport the write used. A claim is
+ * still not proof: only the next measurement moves it to verified.
+ * An object CSPeach activated but did not write (someone changed it in Eclipse
+ * or SE80) only gets the one-line offer; the developer claims that one.
+ */
+import { objectKey } from '@cspeach/register-core';
+import { activeProject, readBaseline } from './store.js';
+import { findingsByObject } from './findings.js';
+import { writeRecord } from './records.js';
+import { regenerateWorkingList } from './workbooks.js';
+/** The source-writing tools, and the argument that names the object each one wrote. */
+const SOURCE_WRITES = {
+    sap_set_source: 'name',
+    sap_update_method: 'class_name',
+    sap_set_class_include: 'className',
+};
+/**
+ * Objects whose source CSPeach wrote successfully in this session (upper-case
+ * name → the transport the write used, '' when none is known).
+ */
+export function cspeachWritesThisSession(toolCalls) {
+    const out = new Map();
+    for (const c of toolCalls ?? []) {
+        if (!c.completed || c.is_error)
+            continue;
+        const field = SOURCE_WRITES[c.tool];
+        if (!field)
+            continue;
+        const args = (c.args ?? {});
+        const name = String(args[field] ?? '').trim().toUpperCase();
+        if (!name)
+            continue;
+        let transport = typeof args['transport'] === 'string' ? args['transport'] : '';
+        try {
+            // sap_set_source / sap_update_method report the request they used as transport_used.
+            const r = JSON.parse(c.result);
+            if (typeof r?.transport_used === 'string' && r.transport_used)
+                transport = r.transport_used;
+            else if (typeof r?.transport === 'string' && r.transport)
+                transport = r.transport;
+        }
+        catch { /* a plain-text result carries no transport */ }
+        out.set(name, transport.trim().toUpperCase());
+    }
+    return out;
+}
+/** Fixes this process already recorded (a write that activated, then an explicit activate, record once). */
+const recordedThisRun = new Set();
+/** Tests only. */
+export function resetRecordedFixes() { recordedThisRun.clear(); }
+export function teamFixOffers(objects, opts = {}) {
+    // A guided journey is on (journey/flow.ts): the same records, in solo words.
+    const solo = opts.wording === 'journey';
+    try {
+        const joined = activeProject();
+        if (!joined)
+            return [];
+        const baseline = readBaseline(joined.projectDir);
+        const byKey = new Map(baseline.map((o) => [objectKey(o.type, o.name), o]));
+        const byName = new Map();
+        for (const o of baseline)
+            byName.set(o.name.toUpperCase(), [...(byName.get(o.name.toUpperCase()) ?? []), o]);
+        const lines = [];
+        const done = new Set();
+        for (const o of objects) {
+            const type = String(o?.type ?? '').split('/')[0].trim().toUpperCase();
+            const name = String(o?.name ?? '').trim().toUpperCase();
+            const same = byName.get(name) ?? [];
+            const hit = byKey.get(objectKey(type, name)) ?? (same.length === 1 ? same[0] : undefined);
+            if (!hit)
+                continue;
+            const key = objectKey(hit.type, hit.name);
+            if (done.has(key))
+                continue;
+            done.add(key);
+            const label = `${hit.type.toUpperCase()} ${hit.name.toUpperCase()}`;
+            const transport = opts.written?.get(hit.name.toUpperCase());
+            if (transport === undefined) {
+                lines.push(solo
+                    ? `${label} is one of your objects, but CSPeach did not write it, so no fix was recorded.`
+                    : `This object is in your team project. Mark it fixed? cspeach team fixed ${label}`);
+                continue;
+            }
+            const runKey = `${joined.projectId}|${key}|${transport}`;
+            if (recordedThisRun.has(runKey))
+                continue;
+            const f = findingsByObject(joined.projectDir, joined.outboxDir).get(key);
+            if (!f?.latestAt) {
+                lines.push(solo
+                    ? `${label} has not been checked yet, so no fix was recorded. The next check looks at it.`
+                    : `${label} has not been measured yet, so no fix was recorded. Run cspeach team refresh to measure it.`);
+                continue;
+            }
+            if (!f.latest.length) {
+                lines.push(solo
+                    ? `${label} had nothing open at its last check, so no fix was recorded. The next check looks at it.`
+                    : `${label} had nothing open at its last measurement, so no fix was recorded. The next cspeach team refresh checks it.`);
+                continue;
+            }
+            // The name this person records under in this team project, as team verbs use it.
+            const who = opts.who ?? joined.name ?? process.env['CSPEACH_AUTHOR_NAME'] ?? process.env['USER'] ?? process.env['USERNAME'] ?? 'consultant';
+            const res = writeRecord(joined, 'fix', f.latest.map((r) => ({ key, rule: r.rule, status: 'fixed', ...(transport ? { transport } : {}) })), { name: who });
+            if (!res.file)
+                continue;
+            recordedThisRun.add(runKey);
+            const by = `✓ Recorded: ${label} fixed by CSPeach${transport ? ` in ${transport}` : ''}.`;
+            lines.push(solo ? `${by} Not yet checked — the next check proves it.` : `${by} A claim is not proof — the next cspeach team refresh checks it.`);
+            try {
+                regenerateWorkingList(joined, who);
+            }
+            catch { /* the record is kept; the list catches up on the next run */ }
+        }
+        return lines;
+    }
+    catch {
+        return []; // a folder halfway through a sync must never touch an activation
+    }
+}

package/dist/register/picture.js

@@ -0,0 +1,25 @@
+import path from 'node:path';
+import { buildRegister, narrowedLanes } from '@cspeach/register-core';
+import { collectRecords, readBaseline, readEstate, readLanes, readProjectFile } from './store.js';
+export function registerFor(projectDir, outboxDir) {
+    const project = readProjectFile(projectDir);
+    const collected = collectRecords(projectDir);
+    // This laptop's own outbox counts too, so a developer sees their work before
+    // handing it in. It is also the one way this picture can legitimately differ
+    // from the team project page's, so `status` says out loud when it counted them.
+    const own = outboxDir && path.resolve(outboxDir) !== path.resolve(projectDir) ? collectRecords(outboxDir) : { records: [], unreadable: 0, files: 0 };
+    const baseline = readBaseline(projectDir);
+    const lanes = readLanes(projectDir);
+    // The newest discovery, when the folder holds one: the estate around the team project.
+    const estate = readEstate(projectDir)?.estate;
+    const register = buildRegister({
+        project, baseline, lanes, records: [...collected.records, ...own.records], ...(estate !== undefined ? { estate } : {}),
+    });
+    return {
+        register, files: collected.files + own.files,
+        unreadable: collected.unreadable + own.unreadable, ownFiles: own.files,
+        // F2: a lanes.json written before names began to narrow packages holds
+        // fewer objects now. The lead is told, not left to work it out from a count.
+        narrowed: narrowedLanes(lanes, baseline),
+    };
+}

package/dist/register/plan-import.js

@@ -0,0 +1,325 @@
+/**
+ * The Plan sheet, read back (spec 2026-10-06 §8). `team report` writes it; the
+ * lead edits the five columns before the dash in Excel; `team plan import`
+ * reads it here, compares it with what the export said and what the plan says
+ * now, and hands back the changes as the rows of ONE `excel` plan record.
+ *
+ * Read the strict way:
+ *  - the header row is matched by column name (any case, trimmed), unknown columns ignored;
+ *  - rows are matched by Type + Object, never by position; blank rows ignored;
+ *  - a cell is a change only when it differs from what the export wrote AND from
+ *    what the plan says now, so a cell the lead never touched never undoes
+ *    someone else's newer change;
+ *  - a change to a field a newer plan, decision or ruling record touched is a
+ *    clash: shown with both values and skipped, never overwritten;
+ *  - the fact columns after the dash are compared with the export and never read.
+ *
+ * Pure: buffer and register in, rows and counts out. Nothing is written here.
+ */
+import { normalizeKey, objectKey, planRows, PLAN_COLUMNS, } from '@cspeach/register-core';
+import { readSheets } from '../tools/filesystem/extract-xlsx.js';
+import { RegisterError } from './store.js';
+import { EXPORT_STAMP } from './workbooks.js';
+export const NOT_A_PLAN_SHEET = 'This is not a Plan sheet CSPeach wrote.';
+const MAX_NOTE = 300;
+const STAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+const SERIAL = /^\d{5}(\.\d+)?$/;
+/** Excel's day zero for serial dates (the 1900 system, after its leap-year bug). */
+const EXCEL_EPOCH = Date.UTC(1899, 11, 30);
+const DASH = PLAN_COLUMNS.indexOf('—');
+const FACT_COLUMNS = PLAN_COLUMNS.slice(DASH + 1);
+const lower = (s) => s.trim().toLowerCase();
+const CANONICAL = new Map(PLAN_COLUMNS.map((c) => [lower(c), c]));
+/**
+ * The Plan sheet and the export stamp of a workbook `team report` wrote.
+ * Throws the one sentence for anything else: not an .xlsx, no Plan sheet, no
+ * stamp in the Read me, or a Plan sheet without Object and Type columns.
+ */
+export function readPlanSheet(buffer) {
+    let sheets;
+    try {
+        sheets = readSheets(buffer);
+    }
+    catch {
+        throw new RegisterError(NOT_A_PLAN_SHEET);
+    }
+    const plan = sheets.find((s) => lower(s.name) === 'plan');
+    const readMe = sheets.find((s) => lower(s.name) === 'read me');
+    const stampCell = readMe?.rows.flat().find((c) => lower(c).startsWith(lower(EXPORT_STAMP)));
+    const exportStamp = stampCell ? stampCell.trim().slice(EXPORT_STAMP.length).trim() : '';
+    if (!plan || !STAMP.test(exportStamp) || Number.isNaN(Date.parse(exportStamp)))
+        throw new RegisterError(NOT_A_PLAN_SHEET);
+    const at = plan.rows.findIndex((r) => r.some((c) => c.trim() !== ''));
+    const header = at === -1 ? [] : plan.rows[at].map((c) => c.trim());
+    // Column name → index; the first column of a name wins, names it does not know are ignored.
+    const index = new Map();
+    header.forEach((name, i) => {
+        const canonical = CANONICAL.get(lower(name));
+        if (canonical && !index.has(canonical))
+            index.set(canonical, i);
+    });
+    if (!index.has('Object') || !index.has('Type'))
+        throw new RegisterError(NOT_A_PLAN_SHEET);
+    const rows = [];
+    for (const raw of plan.rows.slice(at + 1)) {
+        const row = {};
+        for (const [name, i] of index)
+            row[name] = (raw[i] ?? '').trim();
+        if (Object.values(row).every((v) => v === ''))
+            continue;
+        rows.push(row);
+    }
+    return { exportStamp, header, rows };
+}
+// ── cells ────────────────────────────────────────────────────────────────────
+/** 1–5 (also `2.0`, ` 2 `), `defer` in any case, '' = blank, undefined = unreadable. */
+function priorityCell(cell) {
+    const v = cell.trim();
+    if (!v)
+        return '';
+    if (lower(v) === 'defer')
+        return 'defer';
+    const m = /^([1-5])(?:\.0+)?$/.exec(v);
+    return m ? Number(m[1]) : undefined;
+}
+/** A real day as YYYY-MM-DD, or an Excel serial (46000 → 2025-12-09); '' = blank; undefined = unreadable. */
+function dateCell(cell) {
+    const v = cell.trim();
+    if (!v)
+        return '';
+    if (DAY.test(v)) {
+        const d = new Date(`${v}T00:00:00Z`);
+        return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === v ? v : undefined;
+    }
+    if (SERIAL.test(v))
+        return new Date(EXCEL_EPOCH + Math.floor(Number(v)) * 86_400_000).toISOString().slice(0, 10);
+    return undefined;
+}
+function scopeCell(cell) {
+    const v = lower(cell);
+    if (!v)
+        return '';
+    // `1`/`0`: a cell Excel saved as a boolean reads back as a number.
+    if (v === 'yes' || v === 'y' || v === 'true' || v === '1')
+        return true;
+    if (v === 'no' || v === 'n' || v === 'false' || v === '0')
+        return false;
+    return undefined;
+}
+/** A lane id from `Owner (id)` (as exported), an owner name or a lane id, any case. '' = blank; undefined = unknown. */
+function laneCell(cell, register, current) {
+    const v = cell.trim();
+    if (!v)
+        return '';
+    const byId = (id) => register.lanes.find((l) => lower(l.id) === lower(id))?.id;
+    const label = /^(.*)\(([^()]+)\)\s*$/.exec(v);
+    if (label) {
+        const id = byId(label[2]);
+        if (id && lower(register.lanes.find((l) => l.id === id).owner) === lower(label[1]))
+            return id;
+    }
+    const id = byId(v);
+    if (id)
+        return id;
+    const owned = register.lanes.filter((l) => lower(l.owner) === lower(v));
+    if (owned.length === 1)
+        return owned[0].id;
+    // An owner of several lanes: the lane the object is in now, if it is one of them.
+    if (owned.length > 1 && owned.some((l) => l.id === current))
+        return current;
+    return undefined;
+}
+// ── values the plan holds for an object ─────────────────────────────────────
+const manualOf = (o) => {
+    const e = o.priority.effective;
+    return e.source === 'set by hand' || e.source === 'Excel plan' ? e.band : null;
+};
+const laneLabel = (register, id) => {
+    const l = id ? register.lanes.find((x) => x.id === id) : undefined;
+    return l ? `${l.owner} (${l.id})` : 'no lane';
+};
+const shownValue = (v) => (v === '' ? 'blank' : v);
+/** The cell as the fact columns compare it: trimmed, and a number read as a number (3 = "3" = "3.0"). */
+function sameFact(a, b) {
+    const x = a === null || a === undefined ? '' : String(a).trim();
+    const y = b === null || b === undefined ? '' : String(b).trim();
+    if (x === y)
+        return true;
+    return x !== '' && y !== '' && Number.isFinite(Number(x)) && Number(x) === Number(y);
+}
+/** field → newest (by, at) of a plan, decision or ruling record newer than the export, per object. */
+function newerTouches(records, stamp) {
+    const out = new Map();
+    const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+    for (const r of records) {
+        if (!isObj(r) || typeof r.at !== 'string' || !(r.at > stamp) || !Array.isArray(r.rows))
+            continue;
+        const by = isObj(r.by) && typeof r.by.name === 'string' ? r.by.name : 'someone';
+        for (const row of r.rows) {
+            if (!isObj(row) || typeof row.key !== 'string')
+                continue;
+            const key = normalizeKey(row.key);
+            if (!key)
+                continue;
+            const fields = [];
+            if (r.recordType === 'decision' || r.recordType === 'ruling')
+                fields.push('Priority');
+            else if (r.recordType === 'plan') {
+                const a = r.action;
+                if (a === 'priority' || (a === 'excel' && 'priority' in row))
+                    fields.push('Priority');
+                if (a === 'assign' || (a === 'excel' && 'lane' in row))
+                    fields.push('Lane');
+                if (a === 'scope' || (a === 'excel' && 'inScope' in row))
+                    fields.push('In scope');
+                if ((a === 'note' || a === 'excel') && 'targetDate' in row)
+                    fields.push('Target date');
+                if ((a === 'note' || a === 'excel') && 'note' in row)
+                    fields.push('Note');
+            }
+            for (const f of fields) {
+                const byField = out.get(key) ?? new Map();
+                const had = byField.get(f);
+                if (!had || r.at > had.at)
+                    byField.set(f, { by, at: r.at });
+                out.set(key, byField);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The changes the sheet asks for. `register` is the plan now; `exported` the
+ * plan as the export saw it (built from the records up to the export stamp),
+ * the current one when not given; `records` every record the folder holds, for
+ * the clashes.
+ */
+export function diffPlan(sheet, register, records, opts = {}) {
+    const exported = opts.exported ?? register;
+    const now = new Map(register.objects.map((o) => [o.key, o]));
+    const then = new Map(exported.objects.map((o) => [o.key, o]));
+    const exportedFacts = new Map();
+    for (const row of planRows(exported)) {
+        exportedFacts.set(objectKey(String(row[1]), String(row[0])), Object.fromEntries(PLAN_COLUMNS.map((c, i) => [c, row[i]])));
+    }
+    const touched = newerTouches(records, sheet.exportStamp);
+    const counts = {
+        priorities: 0, moves: 0, scope: 0, notes: 0, unchanged: 0, notInTeamProject: 0, clashes: 0, factEditsIgnored: 0, unknownLanes: 0, unreadableCells: 0, blankCells: 0,
+    };
+    const out = { rows: [], counts, clashes: [], unknownLanes: [], exportStamp: sheet.exportStamp };
+    const seen = new Set();
+    for (const cells of sheet.rows) {
+        if (Object.values(cells).every((v) => !v || !v.trim()))
+            continue; // a blank row says nothing
+        const type = cells.Type ?? '';
+        const name = cells.Object ?? '';
+        const key = type && name ? objectKey(type, name) : '';
+        const o = key ? now.get(key) : undefined;
+        if (!o) {
+            counts.notInTeamProject += 1;
+            continue;
+        }
+        if (seen.has(key))
+            continue; // the first row of an object counts
+        seen.add(key);
+        const was = then.get(key) ?? o;
+        const row = { key };
+        let unreadable = 0;
+        let blank = 0;
+        let clashed = 0;
+        let unknownLane = false;
+        /** A change the lead made in the sheet: skipped when a newer record touched the same field. */
+        const change = (field, sheetText, nowText, apply) => {
+            const newer = touched.get(key)?.get(field);
+            if (newer) {
+                out.clashes.push({ key, field, sheet: shownValue(sheetText), now: shownValue(nowText), by: newer.by, at: newer.at });
+                clashed += 1;
+                return;
+            }
+            apply();
+        };
+        if ('Priority' in cells) {
+            const v = priorityCell(cells.Priority);
+            if (v === undefined)
+                unreadable += 1;
+            else {
+                const desired = v === '' ? null : v;
+                if (desired !== manualOf(was) && desired !== manualOf(o)) {
+                    change('Priority', cells.Priority, String(o.priority.effective.band), () => { row.priority = desired; counts.priorities += 1; });
+                }
+            }
+        }
+        if ('Lane' in cells) {
+            const v = laneCell(cells.Lane, register, o.lane);
+            const exportedCell = laneLabel(exported, was.lane);
+            if (v === undefined) {
+                // A label the export wrote for a lane removed since is not the lead's edit.
+                if (!sameFact(cells.Lane, exportedCell)) {
+                    unknownLane = true;
+                    out.unknownLanes.push({ key, lane: cells.Lane });
+                }
+            }
+            else if (v === '') {
+                // Blank gives an object the lead moved back to the lane patterns; a pattern lane has nothing to give back.
+                if (was.laneFrom === 'assigned' && o.laneFrom === 'assigned') {
+                    change('Lane', '', laneLabel(register, o.lane), () => { row.lane = null; counts.moves += 1; });
+                }
+                else if (was.laneFrom !== 'assigned' && o.laneFrom !== 'assigned' && o.lane !== null) {
+                    blank += 1; // a lane from the patterns: blank cannot take it away
+                }
+            }
+            else if (v !== was.lane && v !== o.lane) {
+                change('Lane', cells.Lane, laneLabel(register, o.lane), () => { row.lane = v; counts.moves += 1; });
+            }
+        }
+        if ('In scope' in cells) {
+            const v = scopeCell(cells['In scope']);
+            if (v === undefined)
+                unreadable += 1;
+            else if (v === '')
+                blank += 1; // in scope is yes or no, never nothing
+            else if (v !== was.inScope && v !== o.inScope) {
+                change('In scope', cells['In scope'], o.inScope ? 'yes' : 'no', () => { row.inScope = v; counts.scope += 1; });
+            }
+        }
+        let noted = false;
+        if ('Target date' in cells) {
+            const v = dateCell(cells['Target date']);
+            const before = was.plan.targetDate ?? '';
+            const current = o.plan.targetDate ?? '';
+            if (v === undefined)
+                unreadable += 1;
+            else if (v !== before && v !== current) {
+                change('Target date', cells['Target date'], current, () => { row.targetDate = v; noted = true; });
+            }
+        }
+        if ('Note' in cells) {
+            const v = cells.Note;
+            const before = was.plan.note ?? '';
+            const current = o.plan.note ?? '';
+            if (v.length > MAX_NOTE)
+                unreadable += 1;
+            else if (v !== before && v !== current) {
+                change('Note', v, current, () => { row.note = v; noted = true; });
+            }
+        }
+        if (noted)
+            counts.notes += 1;
+        const facts = exportedFacts.get(key);
+        for (const f of FACT_COLUMNS)
+            if (f in cells && facts && !sameFact(cells[f], facts[f]))
+                counts.factEditsIgnored += 1;
+        counts.unreadableCells += unreadable;
+        counts.blankCells += blank;
+        counts.clashes += clashed;
+        if (unknownLane)
+            counts.unknownLanes += 1;
+        const accepted = Object.keys(row).length > 1;
+        if (accepted)
+            out.rows.push(row);
+        else if (!unreadable && !blank && !clashed && !unknownLane)
+            counts.unchanged += 1;
+    }
+    return out;
+}