@opengsd/gsd-core 1.11.0 → 1.13.0

package/gsd-core/bin/lib/broken-windows.cjs

@@ -20,9 +20,9 @@
  *   ---
  *   # Broken Windows Ledger
  *   <human-readable prose>
- *   ```json
+ *   ````json
  *   [ <entries array, canonical JSON> ]
- *   ```
+ *   ````
  *
  * Frontmatter holds scalar counts (the FAST path the ship gate reads via jq
  * without parsing JSON). The JSON code block is the AUTHORITATIVE entries
@@ -56,6 +56,8 @@ exports.markWaived = markWaived;
 exports.markFixed = markFixed;
 exports.parseLedger = parseLedger;
 exports.renderLedger = renderLedger;
+exports.renderTable = renderTable;
+exports.extractTableRegion = extractTableRegion;
 exports.cmdWindowsStatus = cmdWindowsStatus;
 exports.cmdWindowsAppend = cmdWindowsAppend;
 exports.cmdWindowsWaive = cmdWindowsWaive;
@@ -84,6 +86,10 @@ exports.REASON = Object.freeze({
     WINDOWS_INVALID_ID: 'windows_invalid_id',
     WINDOWS_APPEND_MISSING_FIELD: 'windows_append_missing_field',
     WINDOWS_USAGE: 'windows_usage',
+    // #3689: the rendered markdown table disagreed with the fenced JSON (the
+    // sole source of truth) at the pre-write seam — refuse rather than silently
+    // reconcile by overwriting the operator's hand-edit or dropping a row.
+    WINDOWS_LEDGER_TABLE_DRIFT: 'windows_ledger_table_drift',
 });
 /** Allowed window kinds. Aligned with the issue's enumerated sources. */
 exports.KINDS = Object.freeze([
@@ -286,6 +292,79 @@ function markFixed(ledger, id, opts = { now: new Date().toISOString() }) {
 const JSON_FENCE_OPEN = '````json';
 const JSON_FENCE_CLOSE = '````';
 const FORBIDDEN_BACKTICK_RUN = '````';
+/**
+ * #3689: the ledger table's fixed header row literal. `renderTable` emits it
+ * on both the empty and non-empty branches; `extractTableRegion` anchors on
+ * it to bound the table region. Hoisted to one constant so the two surfaces
+ * cannot drift (see "Generative Fix Divergence" — CONTRIBUTING.md).
+ */
+const TABLE_HEADER_LINE = '| id | phase | kind | file | line | description | status | reason | recorded_at | resolved_at |';
+/**
+ * Locate the entries JSON block by CommonMark fence rules rather than a fixed
+ * literal width. Both parseJsonBlock (strict) and writeLedgerAtomic's #2893
+ * prose preservation (lenient) go through this one function so read tolerance
+ * and splice tolerance cannot drift (#3657). A backtick-only line can never
+ * occur inside a body: JSON.stringify renders strings single-line-escaped, so
+ * an inline run inside a description is never a close-fence candidate.
+ *
+ * Disambiguation (#3657 security review): an entry description may contain
+ * newlines and 3-backtick runs (append validation rejects only 4+ runs), and
+ * renderTable renders descriptions into the prose ABOVE the JSON block — so
+ * hostile or accidental text can plant a second json fence above the real
+ * one. renderLedger always emits the entries block as the FINAL fenced
+ * section, so spans are scanned in REVERSE: prefer the latest span whose
+ * entries length equals the frontmatter total_count (the real block always
+ * satisfies it — parseLedger cross-checks that invariant), else the latest
+ * span whose body is a JSON array, else the first span so corrupt bodies keep
+ * their fail-closed parse errors. A mirror planted below with identical
+ * length and identical entries is indistinguishable by construction — and
+ * harmless.
+ */
+function locateJsonBlock(raw, expectedTotal) {
+    const spans = [];
+    for (const open of raw.matchAll(/^(`{3,})json[ \t]*\r?$/gm)) {
+        const width = open[1].length;
+        const bodyStart = (open.index ?? 0) + open[0].length;
+        for (const close of raw.slice(bodyStart).matchAll(/^(`{3,})[ \t]*\r?$/gm)) {
+            if (close[1].length < width)
+                continue;
+            const bodyEnd = bodyStart + (close.index ?? 0);
+            const closeLineEnd = raw.indexOf('\n', bodyEnd);
+            spans.push({
+                bodyStart,
+                bodyEnd,
+                afterClose: closeLineEnd === -1 ? raw.length : closeLineEnd + 1,
+            });
+            break; // CommonMark: the first qualifying close ends this fence block
+        }
+    }
+    if (spans.length === 0) {
+        const sawOpen = /^(`{3,})json[ \t]*\r?$/m.test(raw);
+        return { ok: false, reason: sawOpen ? 'unterminated' : 'missing-open' };
+    }
+    const parseBody = (s) => {
+        try {
+            return JSON.parse(raw.slice(s.bodyStart, s.bodyEnd).trim());
+        }
+        catch {
+            return undefined;
+        }
+    };
+    if (expectedTotal !== undefined) {
+        for (let i = spans.length - 1; i >= 0; i--) {
+            const body = parseBody(spans[i]);
+            if (Array.isArray(body) && body.length === expectedTotal) {
+                return { ok: true, span: spans[i] };
+            }
+        }
+    }
+    for (let i = spans.length - 1; i >= 0; i--) {
+        if (Array.isArray(parseBody(spans[i]))) {
+            return { ok: true, span: spans[i] };
+        }
+    }
+    return { ok: true, span: spans[0] };
+}
 /**
  * Minimal strict frontmatter parser for flat scalar keys. Only supports the
  * shape this module emits: `key: <number|string>` per line. Throws on any
@@ -333,16 +412,14 @@ function parseFrontmatterStrict(raw) {
     }
     return out;
 }
-function parseJsonBlock(raw) {
-    const start = raw.indexOf(JSON_FENCE_OPEN);
-    if (start === -1) {
-        throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, 'Ledger missing JSON code block for entries.');
-    }
-    const end = raw.indexOf(JSON_FENCE_CLOSE, start + JSON_FENCE_OPEN.length);
-    if (end === -1) {
-        throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, 'Ledger JSON code block not terminated.');
+function parseJsonBlock(raw, expectedTotal) {
+    const span = locateJsonBlock(raw, expectedTotal);
+    if (!span.ok) {
+        throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, span.reason === 'missing-open'
+            ? 'Ledger missing JSON code block for entries.'
+            : 'Ledger JSON code block not terminated.');
     }
-    const jsonText = raw.slice(start + JSON_FENCE_OPEN.length, end).trim();
+    const jsonText = raw.slice(span.span.bodyStart, span.span.bodyEnd).trim();
     let parsed;
     try {
         parsed = JSON.parse(jsonText);
@@ -415,7 +492,7 @@ function parseLedger(raw) {
     if (typeof fm.last_updated !== 'string') {
         throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, `Ledger last_updated must be a string; got ${JSON.stringify(fm.last_updated)}.`);
     }
-    const entries = parseJsonBlock(raw);
+    const entries = parseJsonBlock(raw, typeof fm.total_count === 'number' ? fm.total_count : undefined);
     const ledger = {
         schema_version: exports.SCHEMA_VERSION,
         open_count: typeof fm.open_count === 'number' ? fm.open_count : 0,
@@ -464,13 +541,13 @@ function renderLedger(ledger) {
 function renderTable(entries) {
     if (entries.length === 0) {
         return [
-            '| id | phase | kind | file | line | description | status | reason | recorded_at | resolved_at |',
+            TABLE_HEADER_LINE,
             '|----|-------|------|------|------|-------------|--------|--------|-------------|-------------|',
             '| _(none)_ |  |  |  |  | _No windows recorded._ |  |  |  |  |',
         ].join('\n');
     }
     const rows = [
-        '| id | phase | kind | file | line | description | status | reason | recorded_at | resolved_at |',
+        TABLE_HEADER_LINE,
         '|----|-------|------|------|------|-------------|--------|--------|-------------|-------------|',
     ];
     for (const e of entries) {
@@ -491,6 +568,119 @@ function renderTable(entries) {
     }
     return rows.join('\n');
 }
+/**
+ * #3689: extract the exact markdown table region a rendered ledger emits —
+ * the text `renderTable` produced, byte-for-byte — from a raw ledger file.
+ * Used by `writeLedgerAtomic`'s drift guard to compare the on-disk table
+ * against `renderTable(<on-disk JSON entries>)` without a table parser.
+ *
+ * Locates the JSON block with the same tolerant `locateJsonBlock` helper the
+ * rest of the module uses (#3657), so a formatter-normalized 3-backtick
+ * fence still resolves. Everything before the opening fence line, with
+ * trailing blank lines dropped, is the candidate region.
+ *
+ * #3689: the region is bounded by finding the LAST occurrence of the fixed
+ * `TABLE_HEADER_LINE` literal (anchored at a line start) within that
+ * candidate text, then taking everything from there through its end — NOT
+ * by scanning backward for a contiguous run of `|`-prefixed lines. A `|`
+ * prefix scan cannot bound the region: `validateDescription` rejects only
+ * empty strings and 4-backtick runs, so a description may contain a raw
+ * `\n`, and `renderTable`'s `cell()` escapes `\` and `|` but not newlines.
+ * Such a description renders a row that physically spans multiple file
+ * lines, and the continuation line does not start with `|` — a prefix scan
+ * either truncates the table or, when the row's tail is the last pre-fence
+ * line, returns null immediately, bricking every subsequent write with
+ * `WINDOWS_LEDGER_TABLE_DRIFT` on a ledger nobody hand-edited. Anchoring on
+ * the header instead includes any such row whole, so `renderTable`
+ * regenerates byte-identical text for it and the drift comparison passes.
+ *
+ * Returns null when the JSON block cannot be located, or no header line is
+ * present.
+ *
+ * `expectedTotal` (#3689 review finding 2) is threaded straight into
+ * `locateJsonBlock` so callers with trailing prose can disambiguate the real
+ * ledger block from an unrelated fenced JSON array a user pasted below the
+ * closing fence — without it, `locateJsonBlock`'s no-hint fallback picks the
+ * LATEST array-shaped span, which is the prose block, not the ledger, and
+ * every drift comparison then binds to the wrong table/JSON pairing.
+ */
+function extractTableRegion(raw, expectedTotal) {
+    const span = locateJsonBlock(raw, expectedTotal);
+    if (!span.ok)
+        return null;
+    // bodyStart sits right before the newline (or CR) ending the opening fence
+    // line; walk back to the start of that line.
+    const fenceLineStart = raw.lastIndexOf('\n', span.span.bodyStart - 1) + 1;
+    const before = raw.slice(0, fenceLineStart).replace(/\r\n/g, '\n');
+    let trimmedEnd = before.length;
+    while (trimmedEnd > 0 && before[trimmedEnd - 1] === '\n') {
+        trimmedEnd--;
+    }
+    const candidate = before.slice(0, trimmedEnd);
+    // Find the LAST occurrence of TABLE_HEADER_LINE anchored at a line start —
+    // a plain string scan rather than a regex, since the module is a leaf
+    // (imports only node:fs/node:path) and cannot pull in the shared
+    // escapeRegex() helper for a one-off fixed-literal search.
+    let headerIndex = -1;
+    let searchFrom = candidate.length;
+    for (;;) {
+        const idx = candidate.lastIndexOf(TABLE_HEADER_LINE, searchFrom);
+        if (idx === -1)
+            break;
+        const atLineStart = idx === 0 || candidate[idx - 1] === '\n';
+        const atLineEnd = idx + TABLE_HEADER_LINE.length === candidate.length ||
+            candidate[idx + TABLE_HEADER_LINE.length] === '\n';
+        if (atLineStart && atLineEnd) {
+            headerIndex = idx;
+            break;
+        }
+        // #3689: lastIndexOf clamps a negative position into [0, length] per
+        // spec, so `searchFrom = -1` would re-search from 0 and re-find the same
+        // rejected match at idx===0 forever. Stop explicitly once there is
+        // nowhere left to search — this makes the bound strictly decrease each
+        // iteration, so the loop terminates within candidate.length steps.
+        if (idx === 0)
+            break;
+        searchFrom = idx - 1;
+    }
+    if (headerIndex === -1)
+        return null;
+    return candidate.slice(headerIndex);
+}
+/**
+ * #3689: diff two `renderTable` outputs by row id (the first cell of each
+ * data row), skipping the header + separator lines (always exactly two).
+ * A row whose line text differs between the two tables, or that is present
+ * in only one of them, contributes its id to the result — this is what lets
+ * the drift-guard error message name the specific drifted/table-only row(s)
+ * rather than just saying "the table disagrees".
+ */
+function diffTableRowIds(expectedTable, actualTable) {
+    const rowId = (line) => (line.split('|')[1] ?? '').trim();
+    const dataRows = (table) => {
+        const lines = table.split('\n');
+        const map = new Map();
+        for (let i = 2; i < lines.length; i++) {
+            const line = lines[i];
+            if (!line.startsWith('|'))
+                continue;
+            map.set(rowId(line), line);
+        }
+        return map;
+    };
+    const expectedRows = dataRows(expectedTable);
+    const actualRows = dataRows(actualTable);
+    const ids = new Set();
+    for (const [id, line] of expectedRows) {
+        if (actualRows.get(id) !== line)
+            ids.add(id);
+    }
+    for (const id of actualRows.keys()) {
+        if (!expectedRows.has(id))
+            ids.add(id);
+    }
+    return Array.from(ids).sort();
+}
 // ─── I/O entry points ──────────────────────────────────────────────────────
 function ledgerPath(cwd) {
     return node_path_1.default.join(cwd, '.planning', exports.LEDGER_FILE_NAME);
@@ -569,23 +759,111 @@ function writeLedgerAtomic(cwd, ledger) {
     // trailing prose that users may have written below the closing fence.
     // Without this, every append/waive/fixed silently destroys that prose.
     let trailingProse = '';
+    // #3689: read the pre-image once into `existing` outside the catch, rather
+    // than doing every subsequent step inside a bare try/catch, so that a
+    // WindowsError thrown by the drift guard below propagates instead of being
+    // swallowed by the ENOENT handler meant only for "no ledger yet".
+    let existing = null;
     try {
-        const existing = node_fs_1.default.readFileSync(p, 'utf8');
-        // #2893: search for the CLOSING fence starting AFTER the opening fence,
-        // mirroring parseJsonBlock — indexOf(JSON_FENCE_CLOSE) alone would match
-        // the opening fence ('````json' starts with '````').
-        const openIdx = existing.indexOf(JSON_FENCE_OPEN);
-        if (openIdx !== -1) {
-            const fenceEnd = existing.indexOf(JSON_FENCE_CLOSE, openIdx + JSON_FENCE_OPEN.length);
-            if (fenceEnd !== -1) {
-                const afterFence = existing.slice(fenceEnd + JSON_FENCE_CLOSE.length);
-                // Drop leading newlines; keep the rest as prose.
-                trailingProse = afterFence.replace(/^(?:\r?\n)+/, '');
-            }
+        existing = node_fs_1.default.readFileSync(p, 'utf8');
+    }
+    catch (e) {
+        // #1950-H2 / #3689: ENOENT is the only "no ledger yet" case — mirror
+        // readLedgerOrNull's discipline exactly. A bare catch here would let
+        // EACCES/EIO/ENOTDIR/etc. fall through as "no pre-image", silently
+        // skipping BOTH the #2893 prose preservation and the drift guard below
+        // and proceeding to overwrite an unreadable file — a guard bypassable by
+        // making the pre-image unreadable is not a guard.
+        const code = (e && typeof e === 'object' && 'code' in e)
+            ? String(e.code)
+            : '';
+        if (code !== 'ENOENT') {
+            throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, `Could not read ledger at ${p} (${code || 'unknown fs error'}): ${e.message}.`);
         }
+        // File doesn't exist yet (first write) — no prose to preserve, and
+        // nothing on disk to disagree with, so the drift guard below is skipped.
     }
-    catch {
-        // File doesn't exist yet (first write) — no prose to preserve.
+    if (existing !== null) {
+        // #3689 review finding 2 / #3689 bug discovery: both the #2893 prose
+        // span AND the drift guard below must disambiguate `locateJsonBlock`
+        // against the SAME pre-image ledger block, so this is computed ONCE,
+        // hoisted above both uses. expectedTotal MUST be derived from the
+        // PRE-IMAGE's own frontmatter (never `ledger.total_count`, which is
+        // already post-mutation — e.g. N+1 on an append): #2893 exists precisely
+        // because operators may paste prose below the closing fence, and that
+        // prose can itself contain a fenced JSON array of a different length.
+        // Passing the post-mutation total here (as a since-fixed #3689 review
+        // pass once did for the guard alone) makes locateJsonBlock's expectedTotal
+        // scan find nothing against the pre-image — no span has N+1 entries yet —
+        // so it silently falls through to the no-hint fallback, which binds to
+        // the LATEST array-shaped span: the prose block, not the ledger. Left
+        // unfixed, that means the #2893 prose-preservation span itself would
+        // resolve to the prose fence's `afterClose`, silently dropping
+        // everything between the real ledger block and the prose block —
+        // including the operator's own prose ABOVE that array — on every
+        // append. This is exactly the failure #2893 was written to prevent,
+        // reintroduced through the disambiguation hint; it is caught here by
+        // deriving the hint from the pre-image, not the post-mutation ledger,
+        // for BOTH call sites below. If the pre-image frontmatter cannot be
+        // parsed unambiguously, that is itself the ambiguous case — fail closed
+        // rather than falling back to the no-hint scan.
+        let preImageExpectedTotal;
+        try {
+            const preFm = parseFrontmatterStrict(existing);
+            if (typeof preFm.total_count !== 'number' || !Number.isInteger(preFm.total_count)) {
+                throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, `Ledger frontmatter total_count in ${p} is not an integer; refusing to write — ` +
+                    'the ledger JSON block cannot be identified unambiguously.');
+            }
+            preImageExpectedTotal = preFm.total_count;
+        }
+        catch (e) {
+            if (e instanceof WindowsError)
+                throw e;
+            throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, `Ledger frontmatter in ${p} could not be parsed (${e.message}); refusing ` +
+                'to write — the ledger JSON block cannot be identified unambiguously.');
+        }
+        // #2893: search for the CLOSING fence starting AFTER the opening fence.
+        // The span is located with the same tolerant + disambiguated fence rules
+        // parseJsonBlock uses (#3657), so a formatter-normalized 3-backtick ledger
+        // keeps its prose too — a literal-width search here would find no block
+        // and silently drop everything below the ledger on the next write. The
+        // hint passed here is `preImageExpectedTotal` (pre-image derived, see
+        // above) — NOT `ledger.total_count` — so this binds to the same span the
+        // drift guard below does.
+        const span = locateJsonBlock(existing, preImageExpectedTotal);
+        if (span.ok) {
+            const afterFence = existing.slice(span.span.afterClose);
+            // Drop leading newlines; keep the rest as prose.
+            trailingProse = afterFence.replace(/^(?:\r?\n)+/, '');
+        }
+        // #3689 review finding 2: refuse the write if the on-disk table has
+        // drifted from the on-disk JSON — the source of truth — BEFORE anything
+        // is regenerated. Baseline is the ON-DISK entries, not `ledger` (already
+        // the post-mutation state: an appended entry or a changed status);
+        // comparing against `ledger` would report drift on every legitimate
+        // write.
+        const onDiskEntries = parseJsonBlock(existing, preImageExpectedTotal);
+        const expectedTable = renderTable(onDiskEntries);
+        const actualTable = extractTableRegion(existing, preImageExpectedTotal);
+        if (actualTable === null) {
+            throw new WindowsError(exports.REASON.WINDOWS_LEDGER_TABLE_DRIFT, `Ledger table region could not be located in ${p}; refusing to write. Edit the ` +
+                'fenced JSON block directly — the sole source of truth — or delete the corrupted ' +
+                'table region and let gsd-tools regenerate it; never hand-edit the rendered table.');
+        }
+        if (actualTable !== expectedTable) {
+            const driftedIds = diffTableRowIds(expectedTable, actualTable);
+            // #3689 review finding 3: a header/separator-only drift (e.g. a
+            // hand-edited column name or mangled separator) produces no data-row
+            // diffs, so driftedIds is empty — naming nothing would read "...for
+            // row id(s): .". Say what actually differs instead.
+            const driftDescription = driftedIds.length > 0
+                ? `for row id(s): ${driftedIds.join(', ')}`
+                : "in its header or separator row (no data row differs from the expected rendering)";
+            throw new WindowsError(exports.REASON.WINDOWS_LEDGER_TABLE_DRIFT, `Ledger table in ${p} disagrees with the fenced JSON entries (the sole source of ` +
+                `truth) ${driftDescription}. Edit the fenced JSON block ` +
+                'directly, or discard the table edit and re-run the command so gsd-tools ' +
+                'regenerates the table; never hand-edit the rendered table.');
+        }
     }
     const rendered = renderLedger(ledger);
     const content = trailingProse ? `${rendered}${trailingProse}` : rendered;

package/gsd-core/bin/lib/capability-activation.cjs

@@ -105,9 +105,36 @@ function _resolveActivationValue(dotKey, config, cwd, registry) {
     const r = resolveConfigKey(dotKey, { config, cwd, registry });
     return r.found ? Boolean(r.value) : false;
 }
+/**
+ * Resolve a step's optional `pointFrom` gate (#3661): a step declaring
+ * `pointFrom: "<dotted enum key>"` is only active for ITS OWN `point` when the
+ * resolved value of that config key equals `point` exactly. This lets a
+ * capability register the same logical step at more than one loop point and
+ * have config select which registration is live — without teaching the
+ * shared `when` grammar an equality operator (`when` stays a plain boolean
+ * gate on a dotted key everywhere else).
+ *
+ * No `pointFrom` → true (unconditional; every existing step is unaffected).
+ * Present but not a non-empty string → false (malformed, mirrors `when`).
+ * Present and resolved → true only on an exact match against `point`.
+ *
+ * Single-owner precedence engine: called from both `loop-resolver.cts`
+ * (`isActive`) and `capability-state.cts` (`processHooks`) so the two
+ * consumers can never diverge on activation (see
+ * `tests/capability-precedence-parity.test.cjs`).
+ */
+function _resolvePointGate(pointFrom, point, config, cwd, registry) {
+    if (pointFrom === undefined || pointFrom === null)
+        return true;
+    if (typeof pointFrom !== 'string' || pointFrom.length === 0)
+        return false;
+    const r = resolveConfigKey(pointFrom, { config, cwd, registry });
+    return r.found && r.value === point;
+}
 module.exports = {
     _getNestedConfigValue,
     _readRawConfigKey,
     _resolveActivationValue,
+    _resolvePointGate,
     resolveConfigKey,
 };

package/gsd-core/bin/lib/capability-lock.cjs

@@ -350,10 +350,16 @@ function lockBodyToken(body) {
  * and the whole thing is a BOUNDED iterative loop.
  */
 function acquireLock(lockPath, opts) {
-    try {
-        node_fs_1.default.mkdirSync(node_path_1.default.dirname(lockPath), { recursive: true });
-    }
-    catch { /* best-effort */ }
+    // A genuine failure here (EACCES/ENOSPC/EROFS) MUST surface immediately, matching the #1884
+    // fix (0c43d853e / PR #3472) for withPlanningLock's identical shape. The prior
+    // `catch { /* best-effort */ }` swallowed it, and the subsequent `fs.openSync(lockPath, 'wx')`
+    // below then failed with ENOENT (parent dir missing) — which is NOT 'EEXIST', so the
+    // `if (code !== 'EEXIST') return null;` branch laundered a fatal filesystem error into an
+    // ordinary "lock unavailable" (null) result, indistinguishable from another live process
+    // legitimately holding the lock (#3987). `mkdirSync(recursive:true)` does not throw when the
+    // directory already exists, so the normal path (dir already present) is unaffected; only real
+    // creation failures propagate.
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(lockPath), { recursive: true });
     const maxAttempts = (opts && Number.isInteger(opts.maxAttempts) && opts.maxAttempts > 0)
         ? opts.maxAttempts
         : LOCK_MAX_ATTEMPTS;