* fix(#2789): scope the emitted-drift ack to the diff that introduced it Every input to `diffEmitted` is base-relative -- `baseline` vs `current`, `changedPaths` from `git diff base...HEAD` -- except the ack set, which was read absolutely, from the working tree only. A differential machine consulting a non-differential input. So `staleAcks` asks exactly one question, "did a delta consume you?", and that cannot distinguish an ack that never explained anything (an authoring mistake) from one whose ripple is now absorbed into the base (the ack's SUCCESS condition). After merge an ack is in the second state but reports as the first. The trigger is ordinary. Actions sets GITHUB_BASE_REF on pull_request events only, so a push to `next` falls through to origin/next -- the very commit under test. Both sides build identical content, no deltas remain, and every live ack is reported stale. PR #2768 acked a deliberate 40866 -> 42020 byte growth, was green on its own lane, and reddened `next` the moment it merged. It also reds every PR branching off the poisoned base, and since publish-emitted-baseline is gated on the test job, it blocked baseline publication too. Give the ack the base side it was missing. `diffEmitted` now takes `baseAck` -- the same document at the base ref, via `readAckFileAtRef`. An entry already present there is SPENT: it may no longer consume a delta and is never reported stale, only surfaced as `spentAcks` for tidying. An entry new or reworded in this diff stays live, and if nothing consumes it that genuinely fails, with blame on the author who just wrote it. This closes a hazard the IMPLEMENTATION named but could not prevent -- a leftover ack silently pre-clearing the next ripple on its path. (ADR-2719 §3 asserted only that TOUCHING the file is the alarm; its residual-risk list never covered pre-clearing, and §3 now carries an amendment.) Verified against the two-PR laundering sequence -- land an innocuous ack, then change the artifact -- which passed silently before and now fails on both the hash pass and the size ratchet. Three things the design has to get right, each of which was wrong first: - A read failure on the base document THROWS; only absence-at-the-ref returns null. Returning null on error LOOKS armed (every entry stays live) but a live entry's defining power is that it CONSUMES a delta, so null is armed on the staleness axis and DISARMED on consumption -- silently the whole pre-#2789 gate. `git show` cannot tell absence from fault, so absence is established with `ls-tree`. - Re-arming a spent ack costs actual PROSE. Internal whitespace and the zero-width family collapse, and `runtime` is not compared: a doubled space, an invisible character, or a decorative field would otherwise re-arm an ack whose justification still describes the previous ripple, showing a reviewer nothing. - `baseAck` is REQUIRED once an ack declares entries -- omission is an error, not a silent "inherit nothing" -- so a dropped argument fails loudly instead of quietly restoring this bug with the suite green. Because a corrupt document ON THE BASE is expensive (the loud base-side failure reds every ack-carrying PR), scripts/lint-emitted-drift-ack.cjs blocks one from landing. It is standalone rather than importing parseAck -- scripts/ ships in the npm package and tests/ does not -- so a parity test runs both surfaces over one corpus and fails on divergence; it caught one immediately, a `null` document, now classed as policy rather than schema. Deadlock is separately foreclosed: a tree carrying no ack never reads the base, so the PR that DELETES a corrupt file still lands. `readAckFileAtRef` takes an injected git runner so all four branches are tested deterministically; it never executes in the remote runner, where the real-tree test skips for want of a base ref. It also refuses an option-shaped ref, since execFileSync's array form stops shell metacharacters but not git's own option parsing. Rejected: skipping the differential when base == HEAD. It treats the symptom, costs real coverage on the push-to-next lane, and does nothing about the downstream PRs the same flaw was reddening. Deletes the now-spent tests/emitted-drift-ack.json, and updates the CONTEXT.md canon and ADR-2719 §3: presence is no longer the alarm -- a LIVE entry is, and a spent one is inert. Closes #2789 * chore(#2789): backfill changeset PR number
This commit is contained in:
@@ -45,6 +45,28 @@ const ACK_VERSION = 1;
|
||||
*/
|
||||
const ACK_FILE = 'tests/emitted-drift-ack.json';
|
||||
|
||||
/**
|
||||
* Distinguishes "caller omitted the base side" from "caller said there is none".
|
||||
*
|
||||
* A plain `null` default cannot tell those apart, and the difference is the whole point:
|
||||
* omission would silently mean "inherit nothing", which is precisely how a dropped
|
||||
* argument would restore #2768 with every unit test still green.
|
||||
*/
|
||||
const BASE_ACK_OMITTED = Symbol('baseAck omitted');
|
||||
|
||||
/**
|
||||
* Characters that render as nothing: soft hyphen, the zero-width family, word joiner,
|
||||
* BOM. Stripped before reasons are compared, so an invisible edit cannot re-arm a spent
|
||||
* acknowledgment. Spelled as codepoints on purpose — a literal character class here
|
||||
* would be invisible in review, which is the exact failure being defended against.
|
||||
*/
|
||||
const INVISIBLE = new RegExp(
|
||||
`[${[0x00AD, 0x200B, 0x200C, 0x200D, 0x2060, 0xFEFF]
|
||||
.map((c) => `\\u${c.toString(16).toUpperCase().padStart(4, '0')}`)
|
||||
.join('')}]`,
|
||||
'g',
|
||||
);
|
||||
|
||||
/**
|
||||
* A brand-new workflow/agent file — absent from the baseline, present now — must
|
||||
* still stay under the Codex `project_doc_max_bytes` anchor (ADR-1610 Decision
|
||||
@@ -89,7 +111,11 @@ const NEW_FILE_CAP = 32768;
|
||||
* One document, one file, one paste.
|
||||
*/
|
||||
function ackDocument(entries) {
|
||||
const paths = {};
|
||||
// Null-prototype: `key` comes from repo/emitted paths, so a file literally named
|
||||
// `__proto__` would otherwise SET THE PROTOTYPE instead of a property, and
|
||||
// `JSON.stringify` would then emit `"paths":{}` — a remediation document that silently
|
||||
// teaches the contributor to acknowledge nothing.
|
||||
const paths = Object.create(null);
|
||||
for (const { key, reason } of entries) paths[key] = { reason };
|
||||
return JSON.stringify({ version: ACK_VERSION, paths });
|
||||
}
|
||||
@@ -121,8 +147,13 @@ const REMEDIATION = Object.freeze({
|
||||
rippleReason: '<why this ripple is deliberate>',
|
||||
growthReason: '<why this growth is deliberate>',
|
||||
staleAckFix:
|
||||
`Delete those entries from ${ACK_FILE}. If that leaves no entries, delete the file `
|
||||
+ 'itself — its PRESENCE is the alarm, so an empty one signals nothing.',
|
||||
`Delete those entries from ${ACK_FILE}, or correct them to name the ripple you `
|
||||
+ 'actually made. If that leaves no entries, delete the file itself — an empty one '
|
||||
+ 'signals nothing.',
|
||||
spentAckNote:
|
||||
'These are inert, NOT a failure: the base already carries them, so their ripple is '
|
||||
+ `absorbed and they can no longer clear anything. Delete them from ${ACK_FILE} `
|
||||
+ 'whenever convenient.',
|
||||
ackDocument,
|
||||
});
|
||||
|
||||
@@ -197,18 +228,42 @@ function parseAck(doc, { source = 'emitted-drift-ack.json' } = {}) {
|
||||
/**
|
||||
* The conservation law.
|
||||
*
|
||||
* ── Ack lifecycle: an ack is scoped to the diff that introduced it (#2789) ───
|
||||
*
|
||||
* Every other input here is BASE-RELATIVE — `baseline` vs `current`, `changedPaths` from
|
||||
* `git diff base...HEAD`. `ack` was the one ABSOLUTE input, read only from the working
|
||||
* tree, and that mismatch was a real defect: `staleAcks` asks only "did a delta consume
|
||||
* you?", which cannot tell "you never explained anything" (an authoring mistake) from
|
||||
* "your ripple is now absorbed into the base" (the ack's SUCCESS condition). Merging an
|
||||
* ack therefore made it look like a mistake, reddening `next` and every PR branching off
|
||||
* it (#2768).
|
||||
*
|
||||
* `baseAck` supplies the missing side. An entry already present at the base is SPENT: it
|
||||
* is not part of this diff, so it may no longer consume a delta and is never reported
|
||||
* stale. Making it inert is also what finally closes ADR-2719's own named hazard — a
|
||||
* leftover ack used to SILENTLY pre-clear the next ripple on its path; now that ripple
|
||||
* must be explained on its own terms. Spent entries are still reported (`spentAcks`) so
|
||||
* they can be tidied, but they gate nothing.
|
||||
*
|
||||
* `baseAck` is REQUIRED whenever `ack` is present — omitting it is an error, never a
|
||||
* silent "nothing inherited". Same discipline as `changedPaths` above: a caller that
|
||||
* cannot supply the base side must say `null` deliberately, so that dropping the
|
||||
* argument fails loudly instead of quietly restoring #2768.
|
||||
*
|
||||
* @param {object} opts
|
||||
* @param {object} opts.baseline { [runtime]: { [rel]: hash } } at `next` HEAD
|
||||
* @param {object} opts.current { [runtime]: { [rel]: hash } } at PR HEAD
|
||||
* @param {string[]} opts.changedPaths repo paths the PR changed (git diff --name-only)
|
||||
* @param {object} [opts.ack] parsed emitted-drift-ack.json document (or null)
|
||||
* @param {object} opts.baseAck the same document AT THE BASE REF (or null when
|
||||
* absent there). Required once `ack` is non-null.
|
||||
* @param {object} [opts.sizeBaseline] { [name]: bytes } workflow/agent sizes at next
|
||||
* @param {object} [opts.sizeCurrent] { [name]: bytes } workflow/agent sizes at PR HEAD
|
||||
*
|
||||
* @returns {{
|
||||
* moved: number, attributed: Array, unattributable: Array, acked: Array,
|
||||
* removed: Array, grown: Array, shrunk: Array, newFileCapExceeded: Array,
|
||||
* staleAcks: string[], errors: string[], ok: boolean
|
||||
* staleAcks: string[], spentAcks: string[], errors: string[], ok: boolean
|
||||
* }}
|
||||
*/
|
||||
function diffEmitted({
|
||||
@@ -216,6 +271,7 @@ function diffEmitted({
|
||||
current,
|
||||
changedPaths,
|
||||
ack = null,
|
||||
baseAck = BASE_ACK_OMITTED,
|
||||
sizeBaseline = null,
|
||||
sizeCurrent = null,
|
||||
} = {}) {
|
||||
@@ -242,14 +298,77 @@ function diffEmitted({
|
||||
// manifest came back malformed, so the crash replaced the one message that would
|
||||
// have explained the infrastructure problem (#2778).
|
||||
moved: 0, attributed: [], unattributable: [], acked: [], removed: [],
|
||||
grown: [], shrunk: [], newFileCapExceeded: [], staleAcks: [], errors, ok: false,
|
||||
grown: [], shrunk: [], newFileCapExceeded: [], staleAcks: [], spentAcks: [],
|
||||
errors, ok: false,
|
||||
};
|
||||
}
|
||||
|
||||
const changedSet = new Set(changedPaths);
|
||||
const { entries: ackEntries, errors: ackErrors } = parseAck(ack);
|
||||
const { entries: declaredAcks, errors: ackErrors } = parseAck(ack);
|
||||
errors.push(...ackErrors);
|
||||
|
||||
// Keyed on DECLARED ENTRIES, not on the document being non-null. `{}`, `{version:1}`
|
||||
// and `{paths:{}}` all carry zero acks and `parseAck` calls them legal, so demanding a
|
||||
// base side for them would fail a document the module elsewhere accepts. Protection is
|
||||
// undiminished: an entry is the only thing that can be misclassified as spent or live,
|
||||
// so the error still fires in exactly the situation where dropping `baseAck` would
|
||||
// reintroduce #2768.
|
||||
if (declaredAcks.size > 0 && baseAck === BASE_ACK_OMITTED) {
|
||||
errors.push(
|
||||
`${ACK_FILE}: baseAck was not supplied. The base side is not optional — without it `
|
||||
+ 'a merged ack is indistinguishable from one that never explained anything, which '
|
||||
+ 'is exactly the defect this parameter exists to close (#2789). Pass the document '
|
||||
+ 'read at the base ref, or an explicit null when it is absent there.',
|
||||
);
|
||||
}
|
||||
|
||||
// Base-side SCHEMA errors are deliberately discarded, not surfaced. The base's validity
|
||||
// is not this diff's to answer for, and a document we cannot read simply inherits
|
||||
// nothing — which is the ARMED reading, since every entry then stays live and gated.
|
||||
const resolvedBaseAck = baseAck === BASE_ACK_OMITTED ? null : baseAck;
|
||||
const { entries: baseAcks } = parseAck(resolvedBaseAck);
|
||||
|
||||
/**
|
||||
* Spent == the base already carries this entry's REASON, compared on prose alone.
|
||||
*
|
||||
* Re-arming a spent ack is legitimate — it is how a contributor says "this is a NEW
|
||||
* ripple, and here is why" — but it must cost an actual explanation, because the
|
||||
* reason is the entire artifact a reviewer reads. So the comparison is deliberately
|
||||
* insensitive to everything that is not prose:
|
||||
*
|
||||
* - INTERNAL whitespace collapses. `parseAck` only trims the ends, so without this a
|
||||
* doubled space re-arms an ack whose justification still describes the PREVIOUS
|
||||
* ripple, and the ack file's diff shows a reviewer nothing new.
|
||||
* - `runtime` is NOT compared. Nothing else in this module reads it (lookups key on
|
||||
* `rel` alone), so including it would make an undocumented, schema-absent field the
|
||||
* one thing that re-arms an ack — `+ "runtime": "claude"` beside a byte-identical
|
||||
* reason, carrying no explanation at all.
|
||||
*
|
||||
* Both directions were live re-arm paths for a genuinely unattributable ripple.
|
||||
*/
|
||||
// `\s` covers NBSP and the ideographic space but NOT the zero-width family, so without
|
||||
// this a U+200B (or a soft hyphen) re-arms a spent ack while being literally invisible
|
||||
// in the diff — the purest form of "no new explanation". Stripped before the whitespace
|
||||
// collapse so a zero-width char cannot glue two words into a different-looking string.
|
||||
// Zero-information re-arm defence. `\s` covers NBSP and the ideographic space but NOT
|
||||
// the zero-width family, so without this a U+200B or a soft hyphen re-arms a spent ack
|
||||
// while being literally INVISIBLE in the diff — the purest form of "no new
|
||||
// explanation". Built from codepoints rather than literal characters, because a
|
||||
// literal class would itself be unreviewable in this file.
|
||||
const prose = (reason) => reason.replace(INVISIBLE, '').replace(/\s+/g, ' ').trim();
|
||||
const isSpent = (rel, entry) => {
|
||||
const prior = baseAcks.get(rel);
|
||||
return prior !== undefined && prose(prior.reason) === prose(entry.reason);
|
||||
};
|
||||
|
||||
const ackEntries = new Map();
|
||||
const spentAcks = [];
|
||||
for (const [rel, entry] of declaredAcks) {
|
||||
if (isSpent(rel, entry)) spentAcks.push(rel);
|
||||
else ackEntries.set(rel, entry);
|
||||
}
|
||||
spentAcks.sort();
|
||||
|
||||
const attributed = [];
|
||||
const unattributable = [];
|
||||
const acked = [];
|
||||
@@ -388,6 +507,7 @@ function diffEmitted({
|
||||
shrunk,
|
||||
newFileCapExceeded,
|
||||
staleAcks,
|
||||
spentAcks,
|
||||
errors,
|
||||
ok,
|
||||
};
|
||||
@@ -456,6 +576,24 @@ function buildReport(result, { sampleLimit = 20 } = {}) {
|
||||
});
|
||||
}
|
||||
|
||||
// Modelled here, not only rendered, so it can be asserted on identity like every other
|
||||
// block — this file's stated contract is that `formatReport` is a pure rendering of
|
||||
// this IR, and a section that exists only in prose would have to be tested by raw text
|
||||
// matching, which CONTRIBUTING.md prohibits.
|
||||
//
|
||||
// Gated on `!result.ok` to KEEP that contract true. Spent acks are the one block whose
|
||||
// emit-condition could drift from the renderer's, since a passing run must render
|
||||
// nothing at all; without this, a JSON reporter built on the IR would announce spent
|
||||
// acks for a green run while the text reporter stayed silent.
|
||||
if (!result.ok && result.spentAcks && result.spentAcks.length) {
|
||||
blocks.push({
|
||||
kind: 'spent-acks',
|
||||
count: result.spentAcks.length,
|
||||
items: result.spentAcks.slice(0, sampleLimit),
|
||||
fix: REMEDIATION.spentAckNote,
|
||||
});
|
||||
}
|
||||
|
||||
// ONE ack set for the whole report, not one per branch. A report can trip the hash
|
||||
// branch and the size branch at once, and two complete documents each reading as "the
|
||||
// file to create" invites pasting the second over the first — losing an acknowledgment
|
||||
@@ -526,13 +664,26 @@ function formatReport(result, { sampleLimit = 20 } = {}) {
|
||||
|
||||
if (result.staleAcks.length) {
|
||||
parts.push(
|
||||
`${result.staleAcks.length} stale acknowledgment(s) — the ripple they explained is gone, ` +
|
||||
'so they must be deleted (an ack that outlives its ripple pre-clears the next one):\n ' +
|
||||
`${result.staleAcks.length} stale acknowledgment(s) — written or reworded in THIS diff, ` +
|
||||
'but nothing here needed them, so they explain nothing:\n ' +
|
||||
result.staleAcks.slice(0, sampleLimit).join('\n ') +
|
||||
`\n\n${REMEDIATION.staleAckFix}`,
|
||||
);
|
||||
}
|
||||
|
||||
// Informational, never gating, and rendered ONLY alongside a real failure. Spent
|
||||
// entries are inert housekeeping, not a demand — surfacing them when a contributor is
|
||||
// already in the file is free, but emitting them for an otherwise-clean run would make
|
||||
// `formatReport` return prose for an `ok` result, which this module's callers read as
|
||||
// "there is something wrong".
|
||||
const spent = (result.spentAcks || []).slice(0, sampleLimit);
|
||||
if (spent.length && !result.ok) {
|
||||
parts.push(
|
||||
`${result.spentAcks.length} spent acknowledgment(s):\n ` + spent.join('\n ') +
|
||||
`\n\n${REMEDIATION.spentAckNote}`,
|
||||
);
|
||||
}
|
||||
|
||||
// The remedy, once, at the end — one file, one document, one paste.
|
||||
const { ackable } = buildReport(result, { sampleLimit });
|
||||
if (ackable.length) {
|
||||
|
||||
Reference in New Issue
Block a user