From 07bd64c89f13b02d79d66bffd88689139be6bd3d Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Oct 2026 09:59:37 +0000 Subject: [PATCH] docs(devpath): say what the merge-driver comments mean now that system-context.mdx has a generated register Claude-Session: https://claude.ai/code/session_01JQwxbaFpnMwgpCgneKe2qS Co-authored-by: Claude --- .gitattributes | 30 +++++++++++++++++++----------- scripts/git-merge-regen.mjs | 19 +++++++++++++------ scripts/regen-artifacts.mjs | 35 +++++++++++++++++++++++++---------- 3 files changed, 57 insertions(+), 27 deletions(-) diff --git a/.gitattributes b/.gitattributes index 6535aa494c5..e9249761624 100644 --- a/.gitattributes +++ b/.gitattributes @@ -95,17 +95,25 @@ # the three hottest artifacts; each gate sums its shards when it reads them. # # The elevation census page (`content/docs/permissions/system-context.mdx`) was -# routed here from #13646 to #22927 and is not any more: nothing on it is -# generated. It joined as a `file:line` anchor table whose correct merged values -# were on NEITHER side of a conflict, became a MIXED row when #14064 measured that -# a whole-side deferral dropped its hand-written prose (`mixed: 'line-anchors'`), -# lost its line numbers to `path#symbol` anchors at #15921, and lost its last -# generated half — the census totals — to #22927's ruling. It text-merges like -# its prose neighbours now. ⚠️ What still catches a merge that leaves it wrong is -# `scripts/check-system-context-census.mjs`, which re-derives the census from the -# tree on every PR in the required `Lint & Repo Gates` job: a read no row anchors, -# or an anchor that no longer resolves. The `mixed` field and its comparator stay -# for the next mixed artifact (scripts/regen-artifacts.mjs, scripts/git-merge-regen.mjs). +# routed here from #13646 to #22927 and is not any more. It joined as a `file:line` +# anchor table whose correct merged values were on NEITHER side of a conflict, +# became a MIXED row when #14064 measured that a whole-side deferral dropped its +# hand-written prose (`mixed: 'line-anchors'`), lost its line numbers to +# `path#symbol` anchors at #15921, and lost its census totals to #22927's ruling, +# which took this row and `gen:system-context-census` with them. #26442 gave it a +# generated half again: the site register between its BEGIN/END GENERATED +# markers, rebuilt by `node scripts/check-system-context-census.mjs --write`. It +# stays unrouted, as `tenant-audit-census.mdx` beside it (a generated region that +# `node scripts/tenant-audit-census.mjs --write` rebuilds) always has: both are +# MIXED pages that git text-merges, so neither side's prose is dropped, and the +# register carries one line per symbol and no total, so two read-adding branches +# merge apart. ⚠️ What catches a merge that leaves a region wrong is that page's +# gate, which holds the region equal to its `--write` output on every PR in the +# required `Lint & Repo Gates` job (`scripts/check-system-context-census.mjs`, +# `scripts/check-tenant-audit-census.mjs`). Why neither is routed is recorded in +# NOT_DRIVER_MANAGED's `content/docs/permissions/**` entry; the `mixed` field and +# its comparator stay for the next mixed artifact (scripts/regen-artifacts.mjs, +# scripts/git-merge-regen.mjs). # # #13731 enumerated this file's blind spot and closed it: `check:merge-driver` now diff --git a/scripts/git-merge-regen.mjs b/scripts/git-merge-regen.mjs index 7e67dba0dbe..3b58c1d141e 100755 --- a/scripts/git-merge-regen.mjs +++ b/scripts/git-merge-regen.mjs @@ -174,9 +174,15 @@ const DECLARED_WATCH_HINTS = [ */ const MIXED_COMPARATORS = Object.freeze({ /** - * Equal modulo `file:line` anchor numbers. The generated half of - * `content/docs/permissions/system-context.mdx` is exactly those numbers: - * `check-system-context-census.mjs --fix` rewrites them and touches nothing else. + * Equal modulo `file:line` anchor numbers. Written for + * `content/docs/permissions/system-context.mdx`, whose generated half was those + * numbers until #15921 made its anchors `path#symbol`; on that page it is now the + * identity (`scripts/doc-line-anchors.mjs` header), and the census `--fix` that + * re-anchored them is retired. No row names it today: the page left this driver + * at #22927, and the site register #26442 generated on it since lives between + * markers this comparator does not blank (`check-system-context-census.mjs + * --write` rebuilds it). Kept for the next `file:line` mixed artifact; a + * marker-region page would need a comparator of its own. */ 'line-anchors': blankAnchorLineNumbers, }); @@ -298,9 +304,10 @@ function readSide(file) { * Two shapes are lossless, and they are the ones the comparator can PROVE: * * 1. THEIRS differs from the ANCESTOR only in the generated half. Then theirs - * contributes nothing but numbers `--fix` will re-derive from the merged tree, - * and dropping it drops nothing. This is the common case by a wide margin — - * 24 of the last 25 main commits to `system-context.mdx`. + * contributes nothing but what the row's `gen:` re-derives from the merged + * tree, and dropping it drops nothing. It was the common case by a wide margin + * when `system-context.mdx` was the routed page this was written for — 24 of + * its last 25 main commits, measured then. * 2. THEIRS and OURS agree once the generated half is blanked. Then whatever * hand-written change theirs carries, ours carries too, so keeping ours keeps * it. (Two branches landing the same doc edit, or one rebased onto the other.) diff --git a/scripts/regen-artifacts.mjs b/scripts/regen-artifacts.mjs index 2eca3b1cab4..f8f780305db 100644 --- a/scripts/regen-artifacts.mjs +++ b/scripts/regen-artifacts.mjs @@ -54,8 +54,9 @@ export const ROOT_OWNER = '@objectstack/spec-monorepo'; * `mixed` is the third answer those two lists could not express. A file can be * mixed AND still belong here, when the generated half is unreachable by any text * merge (`content/docs/permissions/system-context.mdx` was the measured case, routed - * from #13646 until #22927 retired the census totals that were its last generated - * half; no row carries `mixed` today) — but + * from #13646 until #22927 retired its census totals; the site register #26442 has + * since generated on it is left to text-merge, for the reasons its + * `NOT_DRIVER_MANAGED` entry records; no row carries `mixed` today) — but * then "defer" is only correct for the merges where the discarded side changed * nothing but the generated half. The value NAMES that equivalence, and * `git-merge-regen.mjs` holds the mapping from the name to the comparator; an @@ -237,10 +238,12 @@ export const REGEN_ARTIFACTS = Object.freeze([ // row with `mixed: 'line-anchors'` (#14064 measured a whole-side deferral dropping // its prose). Its generated half was its `file:line` anchors until #15921 made // them `path#symbol`, then its census totals until #22927's ruling took those off - // the page with `gen:system-context-census`. Nothing on it is generated, so it is - // no artifact and has no row; it text-merges like the prose around it, and - // `check:system-context-census` still re-derives the census on every PR. The - // measurements this row carried are in `git log -p scripts/regen-artifacts.mjs`. + // the page with `gen:system-context-census`. #26442 then generated its site + // register (`check-system-context-census.mjs --write`), so it is MIXED again and + // still has no row: its `NOT_DRIVER_MANAGED` entry (`content/docs/permissions/**`) + // records why, and `check:system-context-census` holds the register to the tree + // on every PR. The measurements this row carried are in + // `git log -p scripts/regen-artifacts.mjs`. // #13335 / #13731. The per-skill reference index — one row per `packages/spec` // source module, rendered whole by `gen:skill-refs`. Nine tracked files today, @@ -418,12 +421,24 @@ export const NOT_DRIVER_MANAGED = Object.freeze([ path: 'content/docs/permissions/**', why: 'the DIRECTORY is not what #13646 routed, and recording that is the point of this ledger. ' - + 'Its pages are hand-written permissions prose. One — `system-context.mdx` — was routed as a ' - + 'MIXED file from #13646 until #22927 retired the census totals that were its last generated ' - + 'half; it is plain prose now and is routed nowhere. Routing the tree the way its sibling ' + + 'Its pages are hand-written permissions prose, and two of them are MIXED: hand-written prose ' + + 'around one generated region between BEGIN/END GENERATED markers. `system-context.mdx` was ' + + 'routed as a MIXED file from #13646 until #22927 retired its census totals, and has carried a ' + + 'generated site register since #26442 (`node scripts/check-system-context-census.mjs ' + + '--write`); `tenant-audit-census.mdx` carries the census region `node ' + + 'scripts/tenant-audit-census.mjs --write` rebuilds. NEITHER is routed, re-weighed at #26535: ' + + 'a whole-side deferral would drop the other side\'s prose; the `mixed` escape would buy nothing, ' + + 'since its one comparator, `line-anchors`, blanks `file:line` digits and is the identity on ' + + 'both pages (measured), so every real edit would still take the driver\'s text-merge limb; a ' + + 'row needs a `gen:` script its owner manifest declares, and neither page has one; and the ' + + 'driver runs only in a local merge, never in GitHub\'s server-side one or the queue\'s. What ' + + 'keeps them right is their gates, which hold each region equal to its `--write` output on ' + + 'every PR and queue build in the required `Lint & Repo Gates` job, so a text merge that ' + + 'leaves a region wrong is red, never silent; and the register carries one line per symbol and ' + + 'no total, so two read-adding branches text-merge apart. Routing the tree the way its sibling ' + '`content/docs/references/**` is routed reads as symmetry and is not: that sibling is ' + 'generated whole, this one would defer every prose page to OURS and lose the other side\'s ' - + 'edits silently. Should a generated page arrive here, route that FILE and leave its ' + + 'edits silently. Should a page generated WHOLE arrive here, route that FILE and leave its ' + 'neighbours to text-merge, which is correct for prose and always was.', }, // ── #13731: the remaining generators, one recorded disposition each ──────────