@cspeach/cli 1.1.14 → 1.1.16

package/dist/register/baseline.js

@@ -0,0 +1,106 @@
+/**
+ * The baseline: every custom object in scope, pulled from the SAP object
+ * directory (TADIR) by program code. It is the denominator of the whole
+ * Project Register, so it is never written by the model and never trusted
+ * without a control total.
+ *
+ * Rules, each learned on the live S4H pull of 2026-09-18 (spec §4.2):
+ *   - One query per package, `DEVCLASS = '<pkg>'`. The ADT data-preview dialect
+ *     rejects IN-lists and more than one LIKE, and a long IN-list was seen to
+ *     return `[]` with NO error — an empty answer is not evidence of nothing.
+ *   - Control totals first (`COUNT(*) … GROUP BY DEVCLASS`). Pulled rows must
+ *     equal the control total for that package or the pull fails loudly.
+ *   - Only code-bearing object types count. A plain Z-star pull is mostly gateway
+ *     registrations (IWSG/IWOM) and other generated entries.
+ *   - Local ($TMP) and generated (GENFLAG) objects are set aside and counted,
+ *     not silently dropped.
+ */
+export const CODE_OBJECT_TYPES = [
+    'PROG', 'CLAS', 'INTF', 'FUGR', 'TABL', 'DTEL', 'DOMA', 'TTYP', 'VIEW', 'SHLP',
+    'DDLS', 'BDEF', 'SRVD', 'SRVB', 'DDLX', 'DCLS', 'ENHO', 'MSAG', 'TRAN', 'SFPF', 'SFPI', 'SSFO',
+];
+export const LOCAL_PACKAGE = '$TMP';
+export class BaselineError extends Error {
+}
+/** Package names are interpolated into SQL, so they are checked, not escaped. */
+const PACKAGE_RE = /^[A-Z0-9_/$]{1,30}$/;
+const PREFIX_RE = /^[A-Z/][A-Z0-9_/]{0,29}$/;
+const clean = (v) => (v ?? '').trim();
+/**
+ * Customer packages with their object counts — the list the lead picks the
+ * scope from, and the control totals for the pull. `$TMP` is reported with the
+ * rest; whether it is in scope is the lead's call (default: no).
+ */
+export async function listCustomPackages(sql, prefixes = ['Z', 'Y']) {
+    const out = new Map();
+    for (const prefix of prefixes) {
+        if (!PREFIX_RE.test(prefix))
+            throw new BaselineError(`Not a valid name prefix: ${prefix}`);
+        const res = await sql(`SELECT DEVCLASS, COUNT(*) AS CNT FROM TADIR WHERE PGMID = 'R3TR' AND DELFLAG = ' ' AND DEVCLASS LIKE '${prefix}%' GROUP BY DEVCLASS`, 10000);
+        for (const row of res.rows)
+            out.set(clean(row.DEVCLASS), { package: clean(row.DEVCLASS), objects: Number(clean(row.CNT)) });
+        const local = await sql(`SELECT COUNT(*) AS CNT FROM TADIR WHERE PGMID = 'R3TR' AND DELFLAG = ' ' AND DEVCLASS = '${LOCAL_PACKAGE}' AND OBJ_NAME LIKE '${prefix}%'`, 10);
+        const n = Number(clean(local.rows[0]?.CNT) || 0);
+        if (n) {
+            const tmp = out.get(LOCAL_PACKAGE) ?? { package: LOCAL_PACKAGE, objects: 0, byPrefix: {} };
+            tmp.objects += n;
+            tmp.byPrefix[prefix] = n;
+            out.set(LOCAL_PACKAGE, tmp);
+        }
+    }
+    return [...out.values()].sort((a, b) => a.package.localeCompare(b.package));
+}
+export async function pullBaseline(sql, opts) {
+    const types = new Set((opts.objectTypes ?? CODE_OBJECT_TYPES).map((t) => t.toUpperCase()));
+    const objects = [];
+    const setAside = { generated: 0, otherTypes: 0 };
+    const perPackage = [];
+    const seen = new Set();
+    for (const { package: pkg, objects: expected, byPrefix } of opts.packages) {
+        if (!PACKAGE_RE.test(pkg))
+            throw new BaselineError(`Not a valid package name: ${pkg}`);
+        const select = `SELECT OBJECT, OBJ_NAME, DEVCLASS, AUTHOR, GENFLAG, CREATED_ON FROM TADIR WHERE PGMID = 'R3TR' AND DELFLAG = ' ' AND DEVCLASS = '${pkg}'`;
+        const res = { rows: [] };
+        if (byPrefix) {
+            for (const [prefix, n] of Object.entries(byPrefix)) {
+                if (!PREFIX_RE.test(prefix))
+                    throw new BaselineError(`Not a valid name prefix: ${prefix}`);
+                res.rows.push(...(await sql(`${select} AND OBJ_NAME LIKE '${prefix}%'`, n + 50)).rows);
+            }
+        }
+        else {
+            res.rows.push(...(await sql(select, expected + 50)).rows);
+        }
+        if (res.rows.length !== expected) {
+            throw new BaselineError(`Package ${pkg}: the system counted ${expected} objects but the pull returned ${res.rows.length}. `
+                + 'The baseline was NOT written. A wrong denominator would make every progress number wrong; run init again, '
+                + 'and if this repeats, pull this package on its own.');
+        }
+        let kept = 0;
+        for (const row of res.rows) {
+            const type = clean(row.OBJECT).toUpperCase();
+            const name = clean(row.OBJ_NAME).toUpperCase();
+            if (!types.has(type)) {
+                setAside.otherTypes += 1;
+                continue;
+            }
+            if (clean(row.GENFLAG) && !opts.includeGenerated) {
+                setAside.generated += 1;
+                continue;
+            }
+            const key = `${type}|${name}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            objects.push({
+                type, name, package: clean(row.DEVCLASS),
+                ...(clean(row.AUTHOR) ? { author: clean(row.AUTHOR) } : {}),
+                ...(clean(row.CREATED_ON) ? { createdOn: clean(row.CREATED_ON) } : {}),
+            });
+            kept += 1;
+        }
+        perPackage.push({ package: pkg, pulled: res.rows.length, kept });
+    }
+    objects.sort((a, b) => a.package.localeCompare(b.package) || a.type.localeCompare(b.type) || a.name.localeCompare(b.name));
+    return { objects, setAside, perPackage };
+}

package/dist/register/measure.js

@@ -0,0 +1,380 @@
+/**
+ * Measuring: an ATC run turned into a measurement record (step 2, "Proof").
+ *
+ * Four rules, each the difference between proof and a nice-looking number:
+ *   · Rows come from the SCOPE — the baseline cut by a lane or by packages —
+ *     never from the findings. An object the run covered and found nothing in
+ *     gets `findings: []`: that row is what "clean" IS.
+ *   · An object the run did NOT cover — its chunk was refused, its type has no
+ *     ADT url, or the worklist never named it — gets NO row. It stays "not
+ *     measured". A wrong "clean" is worse than a missing measurement.
+ *   · Findings are never summed across objects. One finding in a shared include
+ *     is reported under EVERY object that uses it (see `attributedBy:
+ *     'single-run'` in sap-client), so a call-level total would be a number
+ *     nobody can defend. Per object, the counts are right.
+ *   · Nothing measured → nothing written.
+ *
+ * Program code only. No model tool reaches this file, and the SAP call arrives
+ * as a capability so this layer never imports the SAP client.
+ */
+import { laneMatcher, normalizeKey, normalizeRuleId, objectKey, ruleAliasesFromAtc, ruleIdFromAtc, UNNAMED_FINDING, } from '@cspeach/register-core';
+import { readBaseline, readProjectFile, RegisterError } from './store.js';
+import { writeRecord } from './records.js';
+/* ── Measuring ──────────────────────────────────────────────────────────── */
+/**
+ * Whether an object the worklist never named may be written as clean.
+ *
+ * FALSE, AND IT STAYS FALSE. This is settled, not pending.
+ *
+ * The 2026-09-20 capture answered it (`sap-client/test/fixtures/README.md`,
+ * answer 1): SAP LISTS EVERY OBJECT A CHECK RUN COVERED. An object it found
+ * nothing in comes back listed, with an empty findings element — that is what
+ * clean looks like, and it is `evidence: 'listed'`. An object the worklist
+ * never names was not checked at all: the variant has no check for its type.
+ *
+ * So a silence is not a weak yes, it is a no. `absent` gets no row, is counted
+ * under `absent`, and stays "not measured". `measure()` still takes
+ * `absentMeansClean` because the FILE import path offers it — a person who
+ * exported only the findings can say their file's silence means clean, and the
+ * row they get says so.
+ */
+export const ABSENT_MEANS_CLEAN = false;
+export function scopeLabel(scope) {
+    if (scope.kind === 'lane')
+        return `lane:${scope.id.trim()}`;
+    // Trimmed: the label is written into the record and two runs of the same
+    // packages, typed with and without a space, have to read as the same scope.
+    if (scope.kind === 'packages')
+        return `packages:${scope.patterns.map((p) => p.trim()).join(',')}`;
+    return 'all';
+}
+const toRegex = (pattern) => new RegExp(`^${pattern.trim().replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`, 'i');
+export function scopeObjects(baseline, lanes, scope) {
+    if (scope.kind === 'all')
+        return baseline;
+    if (scope.kind === 'lane') {
+        const lane = lanes.find((l) => l.id.toLowerCase() === scope.id.toLowerCase());
+        if (!lane)
+            throw new RegisterError(`There is no lane "${scope.id}". Lanes: ${lanes.map((l) => l.id).join(', ') || 'none yet'}.`);
+        const match = laneMatcher([lane]);
+        return baseline.filter((o) => match(o).length > 0);
+    }
+    const patterns = scope.patterns.map(toRegex);
+    return baseline.filter((o) => patterns.some((re) => re.test(o.package)));
+}
+const NOT_RELEASED = /\b(?:not released|unreleased|non-released)\b/i;
+// The two quote characters are written as \x27 and \x22 on purpose: the word
+// tripwire (`team-words.test.ts`) reads this file as text and cannot tell a
+// regex from a string, so a bare quote here would blind it for the rest of the
+// file. Same pattern, no quote characters in the source.
+const NAMED = /\b(?:table|view|class|interface|function module|function|object|api|type)\s+[\x27\x22]?([^\s\x27\x22,.;:()]+)/gi;
+// Case-sensitive on purpose: SAP writes object names in capitals, prose is not.
+// A leading `/NAMESPACE/` is part of the name (`/ACME/CL_TAX`).
+const SAP_NAME = /^\/?[A-Z][A-Z0-9_]*(?:\/[A-Z0-9_]+)*$/;
+/**
+ * Words the pattern above can capture that are ABAP grammar, not an object:
+ * `type REF TO`, `TYPE TABLE OF`, `API CDS view I_PRODUCT`. Taking one of these
+ * would put a source token in the record and name the rule after nothing.
+ */
+const NOT_A_NAME = new Set(['TABLE', 'VIEW', 'REF', 'CDS', 'TYPE', 'OF', 'TO', 'API', 'OBJECT', 'CLASS', 'INTERFACE', 'FUNCTION', 'MODULE', 'DATA', 'FIELD', 'STRUCTURE']);
+function apiNameIn(text) {
+    for (const m of text.matchAll(NAMED)) {
+        const name = m[1];
+        if (name.length < 3 || name.length > 40)
+            continue;
+        if (NOT_A_NAME.has(name.replace(/^\//, '').toUpperCase()))
+            continue;
+        if (SAP_NAME.test(name))
+            return name;
+    }
+    return null;
+}
+/**
+ * D7: in a clean-core team project an unreleased-API finding is named by the
+ * API (`UNRELEASED_API:VBAK`), but ONLY when the finding's own text names it.
+ * No name → null → the ordinary ATC rule id stands, so a finding is never lost.
+ *
+ * The TITLE is read first: it is where SAP names the API, while the long text
+ * can quote source code and would otherwise hand a token like `TABLE` to the
+ * record. The wording is STILL ASSUMED: the 2026-09-20 capture ran DEFAULT and
+ * S4HANA_READINESS_2022 only, and neither produced an unreleased-API finding
+ * (README answer 9, still open). This function is the only place that wording
+ * is read, and it must be re-checked against a clean-core variant run.
+ */
+export function unreleasedApiRule(f) {
+    const title = f.messageTitle ?? '';
+    const body = f.messageText ?? '';
+    if (!NOT_RELEASED.test(`${title} ${body}`))
+        return null;
+    const name = apiNameIn(title) ?? apiNameIn(body);
+    return name ? `UNRELEASED_API:${name}` : null;
+}
+/**
+ * SAP writes some check names as `ID / text` — `SLIN_DB / SELECT without ORDER
+ * BY`. A claim recorded by a developer may name either half, so both halves are
+ * kept as aliases: a fix claim and the finding it is about have to be able to
+ * meet, whichever half the person had in front of them.
+ */
+function halvesOf(src) {
+    const out = [];
+    for (const text of [src.checkId, src.messageId, src.category, src.messageTitle]) {
+        if (typeof text !== 'string' || !text.includes(' / '))
+            continue;
+        for (const half of text.split(' / ')) {
+            const id = normalizeRuleId(half);
+            if (id)
+                out.push(id);
+        }
+    }
+    return out;
+}
+/**
+ * Rows from a run's findings, one per object it covered.
+ *
+ * A ref may say HOW the run knew about the object. When it does, a row with no
+ * findings carries that word on: `listed` (the worklist named it and reported
+ * nothing) or `absent` (the row says clean only because somebody said silence
+ * means clean). A row WITH findings carries none — the findings are its
+ * evidence — and a ref that says nothing leaves the row exactly as it was, which
+ * is what the file importer relies on: it labels its own rows afterwards.
+ *
+ * Without this the day `ABSENT_MEANS_CLEAN` flips is the day the label is lost:
+ * `coverage.absent` goes to 0, an absent-clean row renders a plain "Clean", and
+ * nothing anywhere says that nothing actually looked at the object.
+ */
+export function findingsToRows(measured, findings, projectType) {
+    const byKey = new Map();
+    const evidenceOf = new Map();
+    for (const o of measured) {
+        const key = objectKey(o.type, o.name);
+        byKey.set(key, []);
+        // `listed` outranks `absent`: one sighting of the object beats a silence.
+        if (o.evidence && !(o.evidence === 'absent' && evidenceOf.get(key) === 'listed'))
+            evidenceOf.set(key, o.evidence);
+    }
+    for (const f of findings) {
+        // A finding whose key is not even text belongs to no object we asked for.
+        const list = typeof f?.key === 'string' ? byKey.get(normalizeKey(f.key)) : undefined;
+        if (!list)
+            continue; // a finding for an object that was not measured is never written
+        const atcRule = ruleIdFromAtc(f);
+        const api = projectType === 'clean-core' ? unreleasedApiRule(f) : null;
+        // A finding nobody can name still counts: dropping it would make the object look cleaner than it is.
+        const rule = api ?? (atcRule || UNNAMED_FINDING);
+        const aliases = [...new Set([...(api && atcRule ? [atcRule] : []), ...ruleAliasesFromAtc(f), ...halvesOf(f)])]
+            .filter((a) => a !== rule)
+            // F1: nothing BARE beside a qualified name. Half of `<check>:<message>` is
+            // a name other rules answer to — every message of one check carries that
+            // check's GUID, and more than one check uses a message id of `SELECT` —
+            // and a shared name is how two findings become one. `halvesOf` splits
+            // `ID / text` names, so it lands here too.
+            .filter((a) => !(rule.includes(':') && !a.includes(':')));
+        // The RULE was named above, from `f` alone. What is written as the message
+        // is a separate question, and `displayMessage` — when a caller built one —
+        // answers it without ever having been near the id.
+        const title = (f.displayMessage ?? f.messageTitle ?? '').trim();
+        list.push({
+            rule,
+            ...(aliases.length ? { aliases } : {}),
+            ...(f.priority ? { severity: String(f.priority) } : {}),
+            ...(f.line ? { line: f.line } : {}),
+            // The title only. The long text can quote source, and the record promises: no source code.
+            ...(title ? { message: title.slice(0, 200) } : {}),
+        });
+    }
+    return [...byKey.entries()].map(([key, list]) => {
+        const evidence = list.length ? undefined : evidenceOf.get(key);
+        return { key, findings: list, ...(evidence ? { evidence } : {}) };
+    });
+}
+/** A chunk never attempted: the run stopped before it, or there was no budget left to split it. */
+const NEVER_RAN = new Set(['not-run']);
+/** The only words that mean the CALL ended early. Anything else is not a stop. */
+const STOPPED_BY = new Set(['aborted', 'deadline', 'connection']);
+/**
+ * As many absent keys as a caller could ever want to name. A whole estate can be
+ * absent — 20,000 keys the caller will print five of — so the list stops here
+ * and `absent` remains the count. Generous enough that the filtered subsets a
+ * caller really prints (objects with findings, objects with a claim) are whole
+ * on any real team project.
+ */
+const MAX_ABSENT_NAMES = 2000;
+/**
+ * Anything that means "no row" beats anything that means "row", and the most
+ * specific reason wins among the ones that mean no row. So an object the answer
+ * calls measured AND failed is failed; one that is `not-run` and also in the
+ * failed list is still `not-run`, because that is the truer sentence to print.
+ */
+const BUCKETS = ['measured', 'absent', 'failed', 'notRun', 'unsupported'];
+const ANSWER_UNREADABLE = 'The check run gave an answer CSPeach could not read. Nothing was written.';
+/** A measurement needs a variant name; this one is a run nothing could be compared with. */
+const NO_VARIANT = 'This check run was given no ATC check variant name, so nothing it measured could be compared. Nothing was written.';
+/** The same sentence `cspeach team refresh` prints, so there is only one of it. */
+export const variantMismatchMessage = (ours, asked) => `This team project measures with ${ours}. A run with ${asked} cannot be compared with it, so it was not started. `
+    + 'To run it anyway — the record is kept, but not counted — add --force-variant';
+export const noVariantYetMessage = (lead) => `This team project has no ATC check variant yet. The lead (${lead}) sets it once: cspeach team refresh --all --variant <NAME>`;
+/**
+ * D6, the second lock. `refresh` settles the variant before it ever connects;
+ * this repeats the ruling for every other caller, because a record written with
+ * a blank variant is counted by the picture as though it were comparable.
+ *
+ * The team project file on DISK decides, not the copy in hand: the lead's first
+ * run writes the name there and measures in the same breath.
+ */
+function settleVariant(input) {
+    const asked = (input.variant ?? '').trim();
+    if (!asked)
+        throw new RegisterError(NO_VARIANT);
+    const onDisk = readProjectFile(input.joined.projectDir);
+    const ours = (onDisk.atcVariant ?? input.project.atcVariant ?? '').trim();
+    if (!ours) {
+        if (!input.forceVariant)
+            throw new RegisterError(noVariantYetMessage(onDisk.lead?.name ?? input.project.lead.name));
+        return asked;
+    }
+    // The team project's own name, in the capitals SAP writes check variants in.
+    // The file on disk can be hand-edited, and a lower-case name must not be what
+    // goes down the wire or into a record the picture compares with.
+    if (ours.toUpperCase() === asked.toUpperCase())
+        return ours.toUpperCase();
+    if (!input.forceVariant)
+        throw new RegisterError(variantMismatchMessage(ours.toUpperCase(), asked.toUpperCase()));
+    return asked;
+}
+const refKey = (o) => {
+    const r = o;
+    return r && typeof r.type === 'string' && typeof r.name === 'string' ? objectKey(r.type, r.name) : '';
+};
+const list = (v) => (Array.isArray(v) ? v : []);
+/** An answer that is not an outcome is a refusal in words, never a stack trace. */
+function readOutcome(answer) {
+    const o = answer;
+    if (!o || typeof o !== 'object'
+        || !Array.isArray(o.measured) || !Array.isArray(o.failed) || !Array.isArray(o.unsupported)
+        || !Array.isArray(o.findings) || !Array.isArray(o.chunks)) {
+        throw new RegisterError(ANSWER_UNREADABLE);
+    }
+    return o;
+}
+export async function measure(input) {
+    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.
+    const seen = new Set();
+    const inScope = scopeObjects(input.baseline, input.lanes, input.scope)
+        .filter((o) => { const k = objectKey(o.type, o.name); return seen.has(k) ? false : (seen.add(k), true); });
+    if (!inScope.length)
+        throw new RegisterError(`Nothing in this team project matches ${label}.`);
+    const absentMeansClean = input.absentMeansClean ?? ABSENT_MEANS_CLEAN;
+    const variant = settleVariant(input); // before SAP is touched
+    const outcome = readOutcome(await input.atc.runSet(inScope.map((o) => ({ type: o.type, name: o.name })), variant, {
+        ...(input.chunkSize ? { chunkSize: input.chunkSize } : {}),
+        ...(input.oneByOne === false ? { maxSingleRuns: 0 } : {}),
+        ...(input.signal ? { signal: input.signal } : {}),
+        ...(input.maxTotalMs ? { maxTotalMs: input.maxTotalMs } : {}),
+        ...(input.onProgress ? { onProgress: input.onProgress } : {}),
+    }));
+    // Everything the answer says about an object is collected, and the object is
+    // then read the safe way round. Nothing here depends on the order it arrives in.
+    const claims = new Map();
+    for (const o of inScope)
+        claims.set(objectKey(o.type, o.name), new Set());
+    const claim = (key, b) => { claims.get(key)?.add(b); }; // an object nobody asked for is never counted
+    for (const m of outcome.measured)
+        claim(refKey(m), m?.evidence === 'listed' || absentMeansClean ? 'measured' : 'absent');
+    for (const u of outcome.unsupported)
+        claim(refKey(u), 'unsupported');
+    for (const c of outcome.chunks) {
+        if (c?.status !== 'refused' || c.superseded)
+            continue;
+        for (const o of list(c.asked))
+            claim(refKey(o), NEVER_RAN.has(c.reason ?? '') ? 'notRun' : 'failed');
+    }
+    for (const f of outcome.failed)
+        claim(refKey(f), 'failed');
+    // A row is a promise about an object of THIS team project, checked against the
+    // baseline on disk — the one `writeRecord` will check it against a moment later.
+    const known = new Set(readBaseline(input.joined.projectDir).map((o) => objectKey(o.type, o.name)));
+    const refusedRows = [];
+    for (const key of claims.keys()) {
+        if (known.has(key))
+            continue;
+        claim(key, 'failed');
+        refusedRows.push(key);
+    }
+    const bucketOf = (key) => {
+        const said = claims.get(key) ?? new Set();
+        for (let i = BUCKETS.length - 1; i >= 0; i -= 1)
+            if (said.has(BUCKETS[i]))
+                return BUCKETS[i];
+        return 'failed'; // asked for, and the answer said nothing about it
+    };
+    const buckets = new Map([...claims.keys()].map((k) => [k, bucketOf(k)]));
+    const tally = (b) => [...buckets.values()].filter((v) => v === b).length;
+    const coverageNow = () => ({
+        asked: inScope.length, measured: tally('measured'), absent: tally('absent'),
+        failed: tally('failed'), unsupported: tally('unsupported'), notRun: tally('notRun'),
+    });
+    // How the run knew about each object, the safe way round: one sighting beats
+    // a silence, whatever order the answer listed them in.
+    const evidenceOf = new Map();
+    for (const m of outcome.measured) {
+        const key = refKey(m);
+        if (!key)
+            continue;
+        const said = m?.evidence === 'listed' ? 'listed' : 'absent';
+        if (!(said === 'absent' && evidenceOf.get(key) === 'listed'))
+            evidenceOf.set(key, said);
+    }
+    // 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)) } : {}) }));
+    const coverage = coverageNow();
+    const refusedChunks = outcome.chunks
+        .filter((c) => c?.status === 'refused' && !c.superseded)
+        .map((c) => ({ index: c.index, reason: c.reason ?? 'error', ...(c.detail ? { detail: c.detail } : {}), objects: list(c.asked).length }));
+    const keysInScope = inScope.map((o) => objectKey(o.type, o.name));
+    const unsupportedNames = keysInScope.filter((k) => buckets.get(k) === 'unsupported');
+    const absentNames = keysInScope.filter((k) => buckets.get(k) === 'absent').slice(0, MAX_ABSENT_NAMES);
+    // Only the three words this layer knows. Anything else is not a stop.
+    const stoppedBy = STOPPED_BY.has(outcome.stopped) ? outcome.stopped : undefined;
+    // A whole number of findings or nothing: a `'2'` or a −1 out of an answer
+    // CSPeach did not write must not become a sentence about the customer's ATC
+    // screen. F3.
+    const merged = outcome.duplicatesMerged;
+    const duplicates = typeof merged === 'number' && Number.isInteger(merged) && merged > 0 ? merged : 0;
+    const counts = {
+        ...coverage, unsupportedNames, absentNames, scope: label, refusedChunks,
+        ...(duplicates ? { duplicateFindingsMerged: duplicates } : {}),
+        ...(stoppedBy ? { stoppedBy } : {}),
+    };
+    if (!rowRefs.length)
+        return { ...counts, file: null, withFindings: 0, refusedRows };
+    const rows = findingsToRows(rowRefs, outcome.findings, 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 } : {}),
+        // M5: `coverage` is the run's own account, written in the one call that
+        // writes the record. A row `writeRecord` refuses — the baseline changed
+        // underneath the run — is only known once it returns, and rewriting the file
+        // to correct one count would mean two writes for a race. The RETURNED counts
+        // below are recomputed after the refusal and are the ones a caller prints.
+        extra: {
+            atcVariant: variant, scope: label, basis: 'system', coverage,
+            ...(duplicates ? { duplicateFindingsMerged: duplicates } : {}),
+        },
+    });
+    // `measured` is a promise about the rows in that file. Everything named here
+    // was in the baseline a moment ago, so this only bites if the team project
+    // folder changed underneath the run — and then the counts say so.
+    for (const key of res.refused) {
+        const k = normalizeKey(key) || key;
+        claim(k, 'failed');
+        buckets.set(k, 'failed');
+        refusedRows.push(key);
+    }
+    return {
+        ...counts, ...coverageNow(), file: res.file, refusedRows,
+        withFindings: rows.filter((r) => r.findings.length > 0).length,
+    };
+}

package/dist/register/records.js

@@ -0,0 +1,159 @@
+/**
+ * Writing this laptop's records (spec §4.4).
+ *
+ * A record is an export: fixed program code, fixed format, small readable JSON.
+ * The model has no tool that reaches this code or the outbox. Rows are checked
+ * against the baseline before anything is written — an object the project does
+ * not contain is refused and named, which is also the guard against a
+ * model-written detail file inventing objects.
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { classificationFromCcaDetail, fromCcaDetailKey, normalizeKey, normalizeRuleId, objectKey, } from '@cspeach/register-core';
+import { defaultRand, readBaseline } from './store.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)));
+    const kept = [];
+    const refused = [];
+    for (const row of rows) {
+        const key = normalizeKey(row.key);
+        if (known.has(key))
+            kept.push({ ...row, key });
+        else
+            refused.push(row.key);
+    }
+    if (!kept.length)
+        return { file: null, written: 0, refused };
+    const now = opts.now ?? new Date();
+    const recordId = (opts.rand ?? defaultRand)(6);
+    const stamp = now.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+    const dir = opts.dir ?? path.join(joined.outboxDir, 'writers', joined.writerId, 'records');
+    fs.mkdirSync(dir, { recursive: true });
+    // `basename`: a record is written into the folder it was written for, and a
+    // name carrying `..` can never walk out of it.
+    const file = path.join(dir, opts.fileName ? path.basename(opts.fileName) : `${stamp}-${recordType}-${recordId.slice(0, 4)}.json`);
+    const record = {
+        kind: 'record', formatVersion: 1, recordId, projectId: joined.projectId, recordType,
+        at: now.toISOString(), by: { name: by.name, writer: joined.writerId },
+        ...(opts.source ? { source: opts.source } : {}),
+        ...(opts.extra ?? {}),
+        rows: kept,
+    };
+    // Write whole, then rename: a sync tool must never pick up half a record.
+    fs.writeFileSync(`${file}.tmp`, `${JSON.stringify(record, null, 2)}\n`);
+    try {
+        fs.renameSync(`${file}.tmp`, file);
+    }
+    catch (e) {
+        // The rename can be refused — a folder standing where the file goes, a sync
+        // tool holding the name, a read-only share. The caller is told, and the
+        // half-written file goes: a stray `.json.tmp` in a folder the whole team
+        // syncs is a record nobody wrote, counted by the next reader as a file it
+        // could not read. Best effort, because the reason the rename failed may
+        // well be the reason this fails too — and the error the caller gets must be
+        // the real one.
+        try {
+            fs.unlinkSync(`${file}.tmp`);
+        }
+        catch { /* nothing more can be done about it here */ }
+        throw e;
+    }
+    return { file, written: kept.length, refused };
+}
+/**
+ * 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
+ * first; the envelope rows are the fallback. `UNKNOWN` is no decision.
+ */
+export function decisionRowsFromCca(content, projectRoot) {
+    const rows = new Map();
+    const detail = path.join(projectRoot, path.dirname(content.detailPath ?? ''), 'objects.json');
+    if (content.detailPath && fs.existsSync(detail)) {
+        try {
+            const objects = JSON.parse(fs.readFileSync(detail, 'utf8'));
+            for (const [detailKey, o] of Object.entries(objects ?? {})) {
+                const key = fromCcaDetailKey(detailKey);
+                const cls = classificationFromCcaDetail(o?.classification?.primary)
+                    ?? classificationFromCcaDetail(o?.technicalReadiness?.status);
+                if (!key || !cls)
+                    continue;
+                const confidence = String(o?.classification?.confidence ?? '').toLowerCase();
+                rows.set(key, {
+                    key, classification: cls,
+                    ...(['high', 'medium', 'low'].includes(confidence) ? { confidence: confidence } : {}),
+                    ...(typeof o?.classification?.evidence === 'string' ? { reason: o.classification.evidence.slice(0, 300) } : {}),
+                });
+            }
+        }
+        catch { /* a detail file the model left unparseable: fall back to the envelope rows */ }
+    }
+    for (const c of content.classifications ?? []) {
+        const key = objectKey(c.objectType, c.objectName);
+        // A human-reviewed envelope row outranks the detail file's first pass.
+        rows.set(key, { key, classification: c.classification, confidence: c.confidence });
+    }
+    return [...rows.values()];
+}
+/**
+ * Fix rows from a saved upgrade-progress. Its rows carry an object NAME but no
+ * type, so the name is resolved against the baseline; a name that matches two
+ * object types is refused rather than guessed.
+ */
+export function fixRowsFromUpgradeProgress(content, baseline) {
+    const byName = new Map();
+    for (const o of baseline) {
+        const name = o.name.toUpperCase();
+        byName.set(name, [...(byName.get(name) ?? []), objectKey(o.type, o.name)]);
+    }
+    const rows = [];
+    const ambiguous = [];
+    for (const f of content.fixes ?? []) {
+        const status = String(f.status).toLowerCase();
+        if (!FIX_STATUSES.has(status))
+            continue;
+        const keys = byName.get(String(f.objectName).trim().toUpperCase()) ?? [];
+        if (keys.length > 1) {
+            ambiguous.push(f.objectName);
+            continue;
+        }
+        // The same function a measurement's rule goes through (register-core rules.ts),
+        // so a claim and the finding it is about can meet. A row with no rule names
+        // nothing a measurement could ever confirm, so it is not written.
+        const rule = normalizeRuleId(f.finding);
+        if (!rule)
+            continue;
+        rows.push({
+            // Unknown names keep a placeholder key so writeRecord refuses and names them.
+            key: keys[0] ?? `?|${f.objectName}`, rule, status, findingId: f.id,
+            ...(content.transport ? { transport: content.transport } : {}),
+        });
+    }
+    return { rows, ambiguous };
+}
+/**
+ * Called after every successful envelope save. Does nothing unless this laptop
+ * has joined a project; never throws (a record is a by-product, a save is not).
+ */
+export function recordFromEnvelope(env, savedPath, joined, by, projectRoot, 
+/** The clock and the ids. Tests only: real saves take the wall clock and random bytes. */
+opts = {}) {
+    if (!joined)
+        return null;
+    const source = { file: path.basename(savedPath), sha256: '', skill: env.source?.skill };
+    try {
+        source.sha256 = createHash('sha256').update(fs.readFileSync(savedPath)).digest('hex');
+    }
+    catch { /* source checksum is a nicety */ }
+    if (env.artefactType === 'cca-assessment') {
+        const rows = decisionRowsFromCca(env.content, projectRoot);
+        return writeRecord(joined, 'decision', rows, by, { source, ...opts });
+    }
+    if (env.artefactType === 'upgrade-progress') {
+        const { rows, ambiguous } = fixRowsFromUpgradeProgress(env.content, readBaseline(joined.projectDir));
+        const res = writeRecord(joined, 'fix', rows, by, { source, ...opts });
+        return { ...res, refused: [...res.refused, ...ambiguous.map((n) => `${n} (name matches more than one object type)`)] };
+    }
+    return null;
+}