@cspeach/cli 1.1.30 → 1.1.31

package/dist/register/findings.js

@@ -20,7 +20,7 @@ const basisOf = (v) => {
     const w = String(v).trim().toLowerCase();
     return w === '' || w === 'system' ? 'system' : 'file';
 };
-export function findingsByObject(projectDir, outboxDir) {
+export function findingsByObject(projectDir, outboxDir, opts = {}) {
     const project = readProjectFile(projectDir);
     const ours = variantKey(project.atcVariant);
     const records = [
@@ -56,13 +56,16 @@ export function findingsByObject(projectDir, outboxDir) {
                 // 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 });
+                    seen.rules.set(rule, { rule, message, count: 1, ...(line !== undefined ? { line } : {}) });
             }
             byKey.set(key, list);
         }

package/dist/register/offer.js

@@ -1,12 +1,63 @@
 /**
- * The one line CSPeach prints after it activated, and verified, an object of
- * the team project this laptop has joined (spec §4.3). It records nothing:
- * "CSPeach activated it" and "the developer says it is fixed" are two different
- * sentences, and only the second is a claim.
+ * 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';
-export function teamFixOffers(objects) {
+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)
@@ -17,15 +68,56 @@ export function teamFixOffers(objects) {
         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)
-                lines.push(`This object is in your team project. Mark it fixed? cspeach team fixed ${hit.type.toUpperCase()} ${hit.name.toUpperCase()}`);
+            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 [...new Set(lines)];
+        return lines;
     }
     catch {
         return []; // a folder halfway through a sync must never touch an activation

package/dist/register/picture.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { buildRegister, narrowedLanes } from '@cspeach/register-core';
-import { collectRecords, readBaseline, readLanes, readProjectFile } from './store.js';
+import { collectRecords, readBaseline, readEstate, readLanes, readProjectFile } from './store.js';
 export function registerFor(projectDir, outboxDir) {
     const project = readProjectFile(projectDir);
     const collected = collectRecords(projectDir);
@@ -10,7 +10,11 @@ export function registerFor(projectDir, outboxDir) {
     const own = outboxDir && path.resolve(outboxDir) !== path.resolve(projectDir) ? collectRecords(outboxDir) : { records: [], unreadable: 0, files: 0 };
     const baseline = readBaseline(projectDir);
     const lanes = readLanes(projectDir);
-    const register = buildRegister({ project, baseline, lanes, records: [...collected.records, ...own.records] });
+    // 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,

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;
+}

package/dist/register/records.js

@@ -13,6 +13,7 @@ import path from 'node:path';
 import { classificationFromCcaDetail, fromCcaDetailKey, normalizeKey, normalizeRuleId, objectKey, } from '@cspeach/register-core';
 import { defaultRand, readBaseline } from './store.js';
 import { safeDetailRel, resolveDetailFileSync } from '../projects/detail-path.js';
+import { writeWhole } from './write-whole.js';
 const FIX_STATUSES = new Set(['fixed', 'skipped', 'failed', 'pending']);
 export function writeRecord(joined, recordType, rows, by, opts = {}) {
     const known = new Set(readBaseline(joined.projectDir).map((o) => objectKey(o.type, o.name)));
@@ -63,6 +64,30 @@ export function writeRecord(joined, recordType, rows, by, opts = {}) {
     }
     return { file, written: kept.length, refused };
 }
+/** `20261007T080000Z`: the ISO time without dashes, colons or milliseconds, as every record file name carries it. */
+export const fileStamp = (now) => now.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+/**
+ * A record the LEAD writes into one of the lead's own folders (`plan/`,
+ * `baseline/`), whose rows may be empty — a plan header says everything in
+ * its header fields. The caller has already decided which rows belong; this
+ * only writes, whole then renamed. Never under `writers/`.
+ */
+export function writeLeadRecord(dir, projectId, recordType, header, rows, by, opts = {}) {
+    const now = opts.now ?? new Date();
+    const recordId = (opts.rand ?? defaultRand)(6);
+    const name = opts.fileName ? path.basename(opts.fileName) : `${fileStamp(now)}-${recordType}-${recordId.slice(0, 4)}.json`;
+    const file = path.join(dir, name);
+    const own = {
+        kind: 'record', formatVersion: 1, recordId, projectId, recordType,
+        at: now.toISOString(), by: { name: by.name, writer: by.writer },
+    };
+    // A header field never stands in for one of the record's own fields.
+    const extra = Object.fromEntries(Object.entries(header).filter(([k]) => !(k in own) && k !== 'rows'));
+    const record = { ...own, ...extra, rows: [...rows] };
+    writeWhole(file, `${JSON.stringify(record, null, 2)}
+`);
+    return { file, recordId };
+}
 /**
  * Decisions from a saved CCA assessment. The full list lives in the detail
  * file's `objects.json` (the envelope table stops at 50 rows), so that is read