Declare the packages/examples census subtree check-system-context-census actually reads#14323

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
baozhoutao merged 1 commit into from
Sep 2, 2026
+138 −2
Merged

Declare the packages/examples census subtree check-system-context-census actually reads #14323

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 124 additions & 1 deletion scripts/check-system-context-census.mjs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -113,6 +113,13 @@
* change over a population that never moved (#13490). `fixAnchors` carries the two
* measured occurrences and why the union is the safer shape.
*
* ⇒ So the repair for a line-shift red is `--fix` and never a hand-edited line
* number, and the repairing PR should state that `--fix` REFUSED ZERO files. That
* sentence is what separates a pure re-anchor from a population change that
* happened to be shifted at the same time: the refusal is the gate's only signal
* that a site arrived or vanished, and a `--fix` run reporting refusals leaves
* rows a human still has to write.
*
* ## Refusals, never quiet passes (#4690)
*
* A page that cannot be read, a census with no sites, zero anchors found, a corpus
Expand DownExpand Up@@ -157,12 +164,70 @@ import { join } from 'node:path';
import { fileURLToPath } from 'node:url';

import { isEntrypoint } from './invoked-as.mjs';
import { runCensus, siteKeys } from './isystem-census.mjs';
import { CORPUS_ROOTS, runCensus, siteKeys } from './isystem-census.mjs';
import { extractLineAnchors, extractPathCitations, resolveAnchorFile } from './doc-line-anchors.mjs';

const ROOT = join(fileURLToPath(new URL('.', import.meta.url)), '..');
export const PAGE = 'content/docs/permissions/system-context.mdx';

/**
* ── The population this gate READS, declared where the dispatch tool looks ───
*
* `extractWatchHints` in `scripts/pm/dispatch-gates.mjs` reads a gate's module
* body for path literals and treats them as the population that gate watches.
* This gate spelled 29 of them -- the page, the four colliding declarations, the
* `NON_READ_ANCHORS` citations -- and every one of them names an ARTIFACT it
* maintains. Its real population is the corpus `isystem-census.mjs` walks:
* `CORPUS_ROOTS`, today 109 elevation read sites in 20 packages across 45 files
* held by 145 anchors.
*
* ⭐ The failure that produced this declaration is not a missed red. It is a
* GREEN that was true and insufficient. A diff that merely SHIFTS a cited line
* -- an added import, a widened docblock -- reds this gate in CI while the
* derivation places it in the `silent` bucket, which reads as a clearance and is
* not: "this gate names paths, none of them yours" is the same sentence for a
* gate that cannot see your diff and for one whose whole verdict turns on it.
* Measured three times in one night on three unrelated PRs; each cost a CI lap
* plus a repair dispatch, and each dev had honestly run its derived families.
*
* ## Why the subtree and not the 45 cited files
*
* A roster of the files that carry a read site TODAY can never name the file
* that grows one TOMORROW -- and a NEW read site is precisely the finding this
* gate exists for (POPULATION, check B above, the mandatory half). A narrow
* declaration would derive green for the one case that most needs the lead, so
* it re-introduces this defect wearing the shape of a fix.
*
* ## The cost of the wide form, measured rather than asserted (at a39b02a6b)
*
* Families derived per probe path, before -> after this declaration:
*
* packages/lint/src/authoring-rules.ts 19 -> 20
* packages/plugins/plugin-auth/src/auth-plugin.ts 22 -> 23
* packages/metadata-protocol/src/protocol.ts 21 -> 22
* packages/spec/src/data/object.zod.ts 42 -> 42 (already named)
* examples/app-crm/package.json 17 -> 18
* content/docs/permissions/access-matrix.mdx 30 -> 30 (unchanged)
* scripts/check-nul-bytes.mjs 14 -> 14 (unchanged)
* .github/workflows/lint.yml 23 -> 23 (unchanged)
*
* So the price is ONE family, on cards under the two subtrees only, against a
* gate that runs in about 3s and is run by CI on every PR regardless. What the
* lead buys is the CI lap it replaces.
*
* ## Provenance, never a lookup key
*
* Nothing here reads this array: `collectCorpus` walks `CORPUS_ROOTS`, and the
* glob form would name directories that do not exist. The self-test derives both
* directions FROM `CORPUS_ROOTS` rather than re-spelling the roots, so a corpus
* root added or dropped reddens here instead of silently outrunning the
* declaration. It has to be written out as a literal array: assembling it from
* `CORPUS_ROOTS` at runtime would put it out of reach of the very text scan it
* exists for -- identical runtime value, zero hints extracted, the defect
* preserved behind a tidier line (`check-watch-hint-literal` holds this shape).
*/
const ROOT_DIR_WATCH_HINTS = ['packages/**', 'examples/**'];

/**
* ⛔ SHRINK-ONLY. Anchors the page writes that are deliberately NOT elevation read
* sites. `needle` must appear on exactly ONE line of `file`; that line is where the
Expand DownExpand Up@@ -1561,6 +1626,64 @@ function selfTest() {
t('WIRING: lint.yml runs the --self-test leg too', lintYml.includes(`node ${SELF} --self-test`));
}

// ── POPULATION DECLARATION: what the dispatch derivation is told this gate reads ──
//
// Nothing in this file can ENFORCE these: `ROOT_DIR_WATCH_HINTS` is read by
// another tool entirely (`extractWatchHints` in `scripts/pm/dispatch-gates.mjs`),
// so a stale or wrong declaration runs green here forever and pays itself out as
// a dev dispatched on a `packages/` card with this gate absent from the brief --
// the exact round this declaration was added to end. Both directions are derived
// from `CORPUS_ROOTS`, never re-spelled: a corpus root added or dropped there has
// to move this declaration or fail here.
const declaredRoots = ROOT_DIR_WATCH_HINTS.map((h) => h.replace(/\/\*+$/, ''));
t(
'POPULATION DECLARATION: every root the census walks is declared',
CORPUS_ROOTS.every((r) => ROOT_DIR_WATCH_HINTS.includes(`${r}/**`)),
JSON.stringify({ CORPUS_ROOTS, ROOT_DIR_WATCH_HINTS })
);
t(
'POPULATION DECLARATION: and it declares no root the census does not walk (a declaration that can '
+ 'drift from the walk is worse than none -- it replaces a silent gate with a lying one)',
declaredRoots.every((r) => CORPUS_ROOTS.includes(r)),
JSON.stringify(declaredRoots)
);
t(
'POPULATION DECLARATION: each declared literal carries a separator -- a bare root word is refused as '
+ 'too generic by the consumer and would reach nothing',
ROOT_DIR_WATCH_HINTS.every((h) => h.includes('/'))
);
t(
'POPULATION DECLARATION: the repo root is NOT declared -- naming it would put this gate in every '
+ "card's brief to reach the two subtrees whose edits can turn it red",
!declaredRoots.some((r) => r === '' || r === '.')
);
t(
'POPULATION DECLARATION: the declared form is NOT the walk root itself (provenance, never a lookup '
+ 'key -- the glob form handed to the census would name directories that do not exist)',
!CORPUS_ROOTS.some((r) => ROOT_DIR_WATCH_HINTS.includes(r))
);
// The literal SPELLING is the whole mechanism: the consumer scans source text,
// so `CORPUS_ROOTS.map((r) => `${r}/**`)` would keep the runtime value, keep
// every assertion above green, and contribute ZERO hints. `check-watch-hint-literal`
// owns that rule fleet-wide; this pin is the own-source half, statement-scoped so
// a second mention in prose or in a neighbouring assertion cannot satisfy it.
let ownSource = null;
try {
ownSource = readFileSync(join(ROOT, SELF), 'utf8');
} catch (err) {
t('POPULATION DECLARATION: this gate can read its own source', false, err.code ?? err.message);
}
if (ownSource !== null) {
const declSites = [...ownSource.matchAll(/\bconst\s+ROOT_DIR_WATCH_HINTS\s*=\s*([^;]*);/g)];
t(
'POPULATION DECLARATION: declared exactly once, as an array of quoted literals the text scan can read',
declSites.length === 1 &&
ROOT_DIR_WATCH_HINTS.every((h) => declSites[0][1].includes(`'${h}'`)) &&
!/[A-Za-z_$][\w$]*\s*\./.test(declSites[0][1]),
JSON.stringify(declSites.map((d) => d[1].replace(/\s+/g, ' ')))
);
}

process.stdout.write(
failures === 0
? '\ncheck-system-context-census --self-test: all cases passed\n'
Expand Down
15 changes: 14 additions & 1 deletion scripts/isystem-census.mjs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -136,9 +136,22 @@ export function isTestPath(relPath) {
return /\.(test|spec)\./.test(relPath) || /(^|\/)(tests|__tests__|qa)\//.test(relPath);
}

/**
* The subtrees this census walks -- the REAL population of every number it
* reports and of the gate that holds the page to them.
*
* Named rather than spelled inline because a second reader needs it: the gate
* declares this population to the dispatch derivation, and a declaration that
* can drift from the walk is worse than none. `check-system-context-census.mjs`
* derives its `ROOT_DIR_WATCH_HINTS` from this constant in both directions, so
* a root added or removed here reddens that gate's self-test instead of quietly
* widening the census past what any card is told about.
*/
export const CORPUS_ROOTS = ['packages', 'examples'];

/** Every tracked, non-dist TypeScript file of the corpus -- tests included. */
export function collectCorpus(root = ROOT) {
return execFileSync('git', ['-C', root, 'ls-files', 'packages', 'examples'], {
return execFileSync('git', ['-C', root, 'ls-files', ...CORPUS_ROOTS], {
encoding: 'utf8',
maxBuffer: 1 << 28,
})
Expand Down
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
Declare the packages/examples census subtree check-system-context-census actually reads#14323

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

baozhoutao
merged 1 commit into

from

Sep 2, 2026

+138

−2

 Merged


Declare the packages/examples census subtree check-system-context-census actually reads
#14323
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


125 changes: 124 additions & 1 deletion
scripts/check-system-context-census.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -113,6 +113,13 @@
 * change over a population that never moved (#13490). `fixAnchors` carries the two
 * measured occurrences and why the union is the safer shape.
 *
 * ⇒ So the repair for a line-shift red is `--fix` and never a hand-edited line
 * number, and the repairing PR should state that `--fix` REFUSED ZERO files. That
 * sentence is what separates a pure re-anchor from a population change that
 * happened to be shifted at the same time: the refusal is the gate's only signal
 * that a site arrived or vanished, and a `--fix` run reporting refusals leaves
 * rows a human still has to write.
 *
 * ## Refusals, never quiet passes (#4690)
 *
 * A page that cannot be read, a census with no sites, zero anchors found, a corpus
Expand DownExpand Up@@ -157,12 +164,70 @@ import { join } from 'node:path';
import { fileURLToPath } from 'node:url';

import { isEntrypoint } from './invoked-as.mjs';
import { runCensus, siteKeys } from './isystem-census.mjs';
import { CORPUS_ROOTS, runCensus, siteKeys } from './isystem-census.mjs';
import { extractLineAnchors, extractPathCitations, resolveAnchorFile } from './doc-line-anchors.mjs';

const ROOT = join(fileURLToPath(new URL('.', import.meta.url)), '..');
export const PAGE = 'content/docs/permissions/system-context.mdx';

/**
 * ── The population this gate READS, declared where the dispatch tool looks ───
 *
 * `extractWatchHints` in `scripts/pm/dispatch-gates.mjs` reads a gate's module
 * body for path literals and treats them as the population that gate watches.
 * This gate spelled 29 of them -- the page, the four colliding declarations, the
 * `NON_READ_ANCHORS` citations -- and every one of them names an ARTIFACT it
 * maintains. Its real population is the corpus `isystem-census.mjs` walks:
 * `CORPUS_ROOTS`, today 109 elevation read sites in 20 packages across 45 files
 * held by 145 anchors.
 *
 * ⭐ The failure that produced this declaration is not a missed red. It is a
 * GREEN that was true and insufficient. A diff that merely SHIFTS a cited line
 * -- an added import, a widened docblock -- reds this gate in CI while the
 * derivation places it in the `silent` bucket, which reads as a clearance and is
 * not: "this gate names paths, none of them yours" is the same sentence for a
 * gate that cannot see your diff and for one whose whole verdict turns on it.
 * Measured three times in one night on three unrelated PRs; each cost a CI lap
 * plus a repair dispatch, and each dev had honestly run its derived families.
 *
 * ## Why the subtree and not the 45 cited files
 *
 * A roster of the files that carry a read site TODAY can never name the file
 * that grows one TOMORROW -- and a NEW read site is precisely the finding this
 * gate exists for (POPULATION, check B above, the mandatory half). A narrow
 * declaration would derive green for the one case that most needs the lead, so
 * it re-introduces this defect wearing the shape of a fix.
 *
 * ## The cost of the wide form, measured rather than asserted (at a39b02a6b)
 *
 * Families derived per probe path, before -> after this declaration:
 *
 * packages/lint/src/authoring-rules.ts 19 -> 20
 * packages/plugins/plugin-auth/src/auth-plugin.ts 22 -> 23
 * packages/metadata-protocol/src/protocol.ts 21 -> 22
 * packages/spec/src/data/object.zod.ts 42 -> 42 (already named)
 * examples/app-crm/package.json 17 -> 18
 * content/docs/permissions/access-matrix.mdx 30 -> 30 (unchanged)
 * scripts/check-nul-bytes.mjs 14 -> 14 (unchanged)
 * .github/workflows/lint.yml 23 -> 23 (unchanged)
 *
 * So the price is ONE family, on cards under the two subtrees only, against a
 * gate that runs in about 3s and is run by CI on every PR regardless. What the
 * lead buys is the CI lap it replaces.
 *
 * ## Provenance, never a lookup key
 *
 * Nothing here reads this array: `collectCorpus` walks `CORPUS_ROOTS`, and the
 * glob form would name directories that do not exist. The self-test derives both
 * directions FROM `CORPUS_ROOTS` rather than re-spelling the roots, so a corpus
 * root added or dropped reddens here instead of silently outrunning the
 * declaration. It has to be written out as a literal array: assembling it from
 * `CORPUS_ROOTS` at runtime would put it out of reach of the very text scan it
 * exists for -- identical runtime value, zero hints extracted, the defect
 * preserved behind a tidier line (`check-watch-hint-literal` holds this shape).
 */
const ROOT_DIR_WATCH_HINTS = ['packages/**', 'examples/**'];

/**
 * ⛔ SHRINK-ONLY. Anchors the page writes that are deliberately NOT elevation read
 * sites. `needle` must appear on exactly ONE line of `file`; that line is where the
Expand DownExpand Up@@ -1561,6 +1626,64 @@ function selfTest() {
 t('WIRING: lint.yml runs the --self-test leg too', lintYml.includes(`node ${SELF} --self-test`));
 }

 // ── POPULATION DECLARATION: what the dispatch derivation is told this gate reads ──
 //
 // Nothing in this file can ENFORCE these: `ROOT_DIR_WATCH_HINTS` is read by
 // another tool entirely (`extractWatchHints` in `scripts/pm/dispatch-gates.mjs`),
 // so a stale or wrong declaration runs green here forever and pays itself out as
 // a dev dispatched on a `packages/` card with this gate absent from the brief --
 // the exact round this declaration was added to end. Both directions are derived
 // from `CORPUS_ROOTS`, never re-spelled: a corpus root added or dropped there has
 // to move this declaration or fail here.
 const declaredRoots = ROOT_DIR_WATCH_HINTS.map((h) => h.replace(/\/\*+$/, ''));
 t(
 'POPULATION DECLARATION: every root the census walks is declared',
 CORPUS_ROOTS.every((r) => ROOT_DIR_WATCH_HINTS.includes(`${r}/**`)),
 JSON.stringify({ CORPUS_ROOTS, ROOT_DIR_WATCH_HINTS })
 );
 t(
 'POPULATION DECLARATION: and it declares no root the census does not walk (a declaration that can '
 + 'drift from the walk is worse than none -- it replaces a silent gate with a lying one)',
 declaredRoots.every((r) => CORPUS_ROOTS.includes(r)),
 JSON.stringify(declaredRoots)
 );
 t(
 'POPULATION DECLARATION: each declared literal carries a separator -- a bare root word is refused as '
 + 'too generic by the consumer and would reach nothing',
 ROOT_DIR_WATCH_HINTS.every((h) => h.includes('/'))
 );
 t(
 'POPULATION DECLARATION: the repo root is NOT declared -- naming it would put this gate in every '
 + "card's brief to reach the two subtrees whose edits can turn it red",
 !declaredRoots.some((r) => r === '' || r === '.')
 );
 t(
 'POPULATION DECLARATION: the declared form is NOT the walk root itself (provenance, never a lookup '
 + 'key -- the glob form handed to the census would name directories that do not exist)',
 !CORPUS_ROOTS.some((r) => ROOT_DIR_WATCH_HINTS.includes(r))
 );
 // The literal SPELLING is the whole mechanism: the consumer scans source text,
 // so `CORPUS_ROOTS.map((r) => `${r}/**`)` would keep the runtime value, keep
 // every assertion above green, and contribute ZERO hints. `check-watch-hint-literal`
 // owns that rule fleet-wide; this pin is the own-source half, statement-scoped so
 // a second mention in prose or in a neighbouring assertion cannot satisfy it.
 let ownSource = null;
 try {
 ownSource = readFileSync(join(ROOT, SELF), 'utf8');
 } catch (err) {
 t('POPULATION DECLARATION: this gate can read its own source', false, err.code ?? err.message);
 }
 if (ownSource !== null) {
 const declSites = [...ownSource.matchAll(/\bconst\s+ROOT_DIR_WATCH_HINTS\s*=\s*([^;]*);/g)];
 t(
 'POPULATION DECLARATION: declared exactly once, as an array of quoted literals the text scan can read',
 declSites.length === 1 &&
 ROOT_DIR_WATCH_HINTS.every((h) => declSites[0][1].includes(`'${h}'`)) &&
 !/[A-Za-z_$][\w$]*\s*\./.test(declSites[0][1]),
 JSON.stringify(declSites.map((d) => d[1].replace(/\s+/g, ' ')))
 );
 }

 process.stdout.write(
 failures === 0
 ? '\ncheck-system-context-census --self-test: all cases passed\n'
Expand Down

15 changes: 14 additions & 1 deletion
scripts/isystem-census.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -136,9 +136,22 @@ export function isTestPath(relPath) {
 return /\.(test|spec)\./.test(relPath) || /(^|\/)(tests|__tests__|qa)\//.test(relPath);
}

/**
 * The subtrees this census walks -- the REAL population of every number it
 * reports and of the gate that holds the page to them.
 *
 * Named rather than spelled inline because a second reader needs it: the gate
 * declares this population to the dispatch derivation, and a declaration that
 * can drift from the walk is worse than none. `check-system-context-census.mjs`
 * derives its `ROOT_DIR_WATCH_HINTS` from this constant in both directions, so
 * a root added or removed here reddens that gate's self-test instead of quietly
 * widening the census past what any card is told about.
 */
export const CORPUS_ROOTS = ['packages', 'examples'];

/** Every tracked, non-dist TypeScript file of the corpus -- tests included. */
export function collectCorpus(root = ROOT) {
 return execFileSync('git', ['-C', root, 'ls-files', 'packages', 'examples'], {
 return execFileSync('git', ['-C', root, 'ls-files', ...CORPUS_ROOTS], {
 encoding: 'utf8',
 maxBuffer: 1 << 28,
 })
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Declare the packages/examples census subtree check-system-context-census actually reads#14323

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

baozhoutao
merged 1 commit into

from

Sep 2, 2026

+138

−2

 Merged


Declare the packages/examples census subtree check-system-context-census actually reads
#14323
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


125 changes: 124 additions & 1 deletion
scripts/check-system-context-census.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -113,6 +113,13 @@
 * change over a population that never moved (#13490). `fixAnchors` carries the two
 * measured occurrences and why the union is the safer shape.
 *
 * ⇒ So the repair for a line-shift red is `--fix` and never a hand-edited line
 * number, and the repairing PR should state that `--fix` REFUSED ZERO files. That
 * sentence is what separates a pure re-anchor from a population change that
 * happened to be shifted at the same time: the refusal is the gate's only signal
 * that a site arrived or vanished, and a `--fix` run reporting refusals leaves
 * rows a human still has to write.
 *
 * ## Refusals, never quiet passes (#4690)
 *
 * A page that cannot be read, a census with no sites, zero anchors found, a corpus
Expand DownExpand Up@@ -157,12 +164,70 @@ import { join } from 'node:path';
import { fileURLToPath } from 'node:url';

import { isEntrypoint } from './invoked-as.mjs';
import { runCensus, siteKeys } from './isystem-census.mjs';
import { CORPUS_ROOTS, runCensus, siteKeys } from './isystem-census.mjs';
import { extractLineAnchors, extractPathCitations, resolveAnchorFile } from './doc-line-anchors.mjs';

const ROOT = join(fileURLToPath(new URL('.', import.meta.url)), '..');
export const PAGE = 'content/docs/permissions/system-context.mdx';

/**
 * ── The population this gate READS, declared where the dispatch tool looks ───
 *
 * `extractWatchHints` in `scripts/pm/dispatch-gates.mjs` reads a gate's module
 * body for path literals and treats them as the population that gate watches.
 * This gate spelled 29 of them -- the page, the four colliding declarations, the
 * `NON_READ_ANCHORS` citations -- and every one of them names an ARTIFACT it
 * maintains. Its real population is the corpus `isystem-census.mjs` walks:
 * `CORPUS_ROOTS`, today 109 elevation read sites in 20 packages across 45 files
 * held by 145 anchors.
 *
 * ⭐ The failure that produced this declaration is not a missed red. It is a
 * GREEN that was true and insufficient. A diff that merely SHIFTS a cited line
 * -- an added import, a widened docblock -- reds this gate in CI while the
 * derivation places it in the `silent` bucket, which reads as a clearance and is
 * not: "this gate names paths, none of them yours" is the same sentence for a
 * gate that cannot see your diff and for one whose whole verdict turns on it.
 * Measured three times in one night on three unrelated PRs; each cost a CI lap
 * plus a repair dispatch, and each dev had honestly run its derived families.
 *
 * ## Why the subtree and not the 45 cited files
 *
 * A roster of the files that carry a read site TODAY can never name the file
 * that grows one TOMORROW -- and a NEW read site is precisely the finding this
 * gate exists for (POPULATION, check B above, the mandatory half). A narrow
 * declaration would derive green for the one case that most needs the lead, so
 * it re-introduces this defect wearing the shape of a fix.
 *
 * ## The cost of the wide form, measured rather than asserted (at a39b02a6b)
 *
 * Families derived per probe path, before -> after this declaration:
 *
 * packages/lint/src/authoring-rules.ts 19 -> 20
 * packages/plugins/plugin-auth/src/auth-plugin.ts 22 -> 23
 * packages/metadata-protocol/src/protocol.ts 21 -> 22
 * packages/spec/src/data/object.zod.ts 42 -> 42 (already named)
 * examples/app-crm/package.json 17 -> 18
 * content/docs/permissions/access-matrix.mdx 30 -> 30 (unchanged)
 * scripts/check-nul-bytes.mjs 14 -> 14 (unchanged)
 * .github/workflows/lint.yml 23 -> 23 (unchanged)
 *
 * So the price is ONE family, on cards under the two subtrees only, against a
 * gate that runs in about 3s and is run by CI on every PR regardless. What the
 * lead buys is the CI lap it replaces.
 *
 * ## Provenance, never a lookup key
 *
 * Nothing here reads this array: `collectCorpus` walks `CORPUS_ROOTS`, and the
 * glob form would name directories that do not exist. The self-test derives both
 * directions FROM `CORPUS_ROOTS` rather than re-spelling the roots, so a corpus
 * root added or dropped reddens here instead of silently outrunning the
 * declaration. It has to be written out as a literal array: assembling it from
 * `CORPUS_ROOTS` at runtime would put it out of reach of the very text scan it
 * exists for -- identical runtime value, zero hints extracted, the defect
 * preserved behind a tidier line (`check-watch-hint-literal` holds this shape).
 */
const ROOT_DIR_WATCH_HINTS = ['packages/**', 'examples/**'];

/**
 * ⛔ SHRINK-ONLY. Anchors the page writes that are deliberately NOT elevation read
 * sites. `needle` must appear on exactly ONE line of `file`; that line is where the
Expand DownExpand Up@@ -1561,6 +1626,64 @@ function selfTest() {
 t('WIRING: lint.yml runs the --self-test leg too', lintYml.includes(`node ${SELF} --self-test`));
 }

 // ── POPULATION DECLARATION: what the dispatch derivation is told this gate reads ──
 //
 // Nothing in this file can ENFORCE these: `ROOT_DIR_WATCH_HINTS` is read by
 // another tool entirely (`extractWatchHints` in `scripts/pm/dispatch-gates.mjs`),
 // so a stale or wrong declaration runs green here forever and pays itself out as
 // a dev dispatched on a `packages/` card with this gate absent from the brief --
 // the exact round this declaration was added to end. Both directions are derived
 // from `CORPUS_ROOTS`, never re-spelled: a corpus root added or dropped there has
 // to move this declaration or fail here.
 const declaredRoots = ROOT_DIR_WATCH_HINTS.map((h) => h.replace(/\/\*+$/, ''));
 t(
 'POPULATION DECLARATION: every root the census walks is declared',
 CORPUS_ROOTS.every((r) => ROOT_DIR_WATCH_HINTS.includes(`${r}/**`)),
 JSON.stringify({ CORPUS_ROOTS, ROOT_DIR_WATCH_HINTS })
 );
 t(
 'POPULATION DECLARATION: and it declares no root the census does not walk (a declaration that can '
 + 'drift from the walk is worse than none -- it replaces a silent gate with a lying one)',
 declaredRoots.every((r) => CORPUS_ROOTS.includes(r)),
 JSON.stringify(declaredRoots)
 );
 t(
 'POPULATION DECLARATION: each declared literal carries a separator -- a bare root word is refused as '
 + 'too generic by the consumer and would reach nothing',
 ROOT_DIR_WATCH_HINTS.every((h) => h.includes('/'))
 );
 t(
 'POPULATION DECLARATION: the repo root is NOT declared -- naming it would put this gate in every '
 + "card's brief to reach the two subtrees whose edits can turn it red",
 !declaredRoots.some((r) => r === '' || r === '.')
 );
 t(
 'POPULATION DECLARATION: the declared form is NOT the walk root itself (provenance, never a lookup '
 + 'key -- the glob form handed to the census would name directories that do not exist)',
 !CORPUS_ROOTS.some((r) => ROOT_DIR_WATCH_HINTS.includes(r))
 );
 // The literal SPELLING is the whole mechanism: the consumer scans source text,
 // so `CORPUS_ROOTS.map((r) => `${r}/**`)` would keep the runtime value, keep
 // every assertion above green, and contribute ZERO hints. `check-watch-hint-literal`
 // owns that rule fleet-wide; this pin is the own-source half, statement-scoped so
 // a second mention in prose or in a neighbouring assertion cannot satisfy it.
 let ownSource = null;
 try {
 ownSource = readFileSync(join(ROOT, SELF), 'utf8');
 } catch (err) {
 t('POPULATION DECLARATION: this gate can read its own source', false, err.code ?? err.message);
 }
 if (ownSource !== null) {
 const declSites = [...ownSource.matchAll(/\bconst\s+ROOT_DIR_WATCH_HINTS\s*=\s*([^;]*);/g)];
 t(
 'POPULATION DECLARATION: declared exactly once, as an array of quoted literals the text scan can read',
 declSites.length === 1 &&
 ROOT_DIR_WATCH_HINTS.every((h) => declSites[0][1].includes(`'${h}'`)) &&
 !/[A-Za-z_$][\w$]*\s*\./.test(declSites[0][1]),
 JSON.stringify(declSites.map((d) => d[1].replace(/\s+/g, ' ')))
 );
 }

 process.stdout.write(
 failures === 0
 ? '\ncheck-system-context-census --self-test: all cases passed\n'
Expand Down

15 changes: 14 additions & 1 deletion
scripts/isystem-census.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -136,9 +136,22 @@ export function isTestPath(relPath) {
 return /\.(test|spec)\./.test(relPath) || /(^|\/)(tests|__tests__|qa)\//.test(relPath);
}

/**
 * The subtrees this census walks -- the REAL population of every number it
 * reports and of the gate that holds the page to them.
 *
 * Named rather than spelled inline because a second reader needs it: the gate
 * declares this population to the dispatch derivation, and a declaration that
 * can drift from the walk is worse than none. `check-system-context-census.mjs`
 * derives its `ROOT_DIR_WATCH_HINTS` from this constant in both directions, so
 * a root added or removed here reddens that gate's self-test instead of quietly
 * widening the census past what any card is told about.
 */
export const CORPUS_ROOTS = ['packages', 'examples'];

/** Every tracked, non-dist TypeScript file of the corpus -- tests included. */
export function collectCorpus(root = ROOT) {
 return execFileSync('git', ['-C', root, 'ls-files', 'packages', 'examples'], {
 return execFileSync('git', ['-C', root, 'ls-files', ...CORPUS_ROOTS], {
 encoding: 'utf8',
 maxBuffer: 1 << 28,
 })
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Declare the packages/examples census subtree check-system-context-census actually reads#14323

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

baozhoutao
merged 1 commit into

from

Sep 2, 2026

+138

−2

 Merged


Declare the packages/examples census subtree check-system-context-census actually reads
#14323
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


125 changes: 124 additions & 1 deletion
scripts/check-system-context-census.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -113,6 +113,13 @@
 * change over a population that never moved (#13490). `fixAnchors` carries the two
 * measured occurrences and why the union is the safer shape.
 *
 * ⇒ So the repair for a line-shift red is `--fix` and never a hand-edited line
 * number, and the repairing PR should state that `--fix` REFUSED ZERO files. That
 * sentence is what separates a pure re-anchor from a population change that
 * happened to be shifted at the same time: the refusal is the gate's only signal
 * that a site arrived or vanished, and a `--fix` run reporting refusals leaves
 * rows a human still has to write.
 *
 * ## Refusals, never quiet passes (#4690)
 *
 * A page that cannot be read, a census with no sites, zero anchors found, a corpus
Expand DownExpand Up@@ -157,12 +164,70 @@ import { join } from 'node:path';
import { fileURLToPath } from 'node:url';

import { isEntrypoint } from './invoked-as.mjs';
import { runCensus, siteKeys } from './isystem-census.mjs';
import { CORPUS_ROOTS, runCensus, siteKeys } from './isystem-census.mjs';
import { extractLineAnchors, extractPathCitations, resolveAnchorFile } from './doc-line-anchors.mjs';

const ROOT = join(fileURLToPath(new URL('.', import.meta.url)), '..');
export const PAGE = 'content/docs/permissions/system-context.mdx';

/**
 * ── The population this gate READS, declared where the dispatch tool looks ───
 *
 * `extractWatchHints` in `scripts/pm/dispatch-gates.mjs` reads a gate's module
 * body for path literals and treats them as the population that gate watches.
 * This gate spelled 29 of them -- the page, the four colliding declarations, the
 * `NON_READ_ANCHORS` citations -- and every one of them names an ARTIFACT it
 * maintains. Its real population is the corpus `isystem-census.mjs` walks:
 * `CORPUS_ROOTS`, today 109 elevation read sites in 20 packages across 45 files
 * held by 145 anchors.
 *
 * ⭐ The failure that produced this declaration is not a missed red. It is a
 * GREEN that was true and insufficient. A diff that merely SHIFTS a cited line
 * -- an added import, a widened docblock -- reds this gate in CI while the
 * derivation places it in the `silent` bucket, which reads as a clearance and is
 * not: "this gate names paths, none of them yours" is the same sentence for a
 * gate that cannot see your diff and for one whose whole verdict turns on it.
 * Measured three times in one night on three unrelated PRs; each cost a CI lap
 * plus a repair dispatch, and each dev had honestly run its derived families.
 *
 * ## Why the subtree and not the 45 cited files
 *
 * A roster of the files that carry a read site TODAY can never name the file
 * that grows one TOMORROW -- and a NEW read site is precisely the finding this
 * gate exists for (POPULATION, check B above, the mandatory half). A narrow
 * declaration would derive green for the one case that most needs the lead, so
 * it re-introduces this defect wearing the shape of a fix.
 *
 * ## The cost of the wide form, measured rather than asserted (at a39b02a6b)
 *
 * Families derived per probe path, before -> after this declaration:
 *
 * packages/lint/src/authoring-rules.ts 19 -> 20
 * packages/plugins/plugin-auth/src/auth-plugin.ts 22 -> 23
 * packages/metadata-protocol/src/protocol.ts 21 -> 22
 * packages/spec/src/data/object.zod.ts 42 -> 42 (already named)
 * examples/app-crm/package.json 17 -> 18
 * content/docs/permissions/access-matrix.mdx 30 -> 30 (unchanged)
 * scripts/check-nul-bytes.mjs 14 -> 14 (unchanged)
 * .github/workflows/lint.yml 23 -> 23 (unchanged)
 *
 * So the price is ONE family, on cards under the two subtrees only, against a
 * gate that runs in about 3s and is run by CI on every PR regardless. What the
 * lead buys is the CI lap it replaces.
 *
 * ## Provenance, never a lookup key
 *
 * Nothing here reads this array: `collectCorpus` walks `CORPUS_ROOTS`, and the
 * glob form would name directories that do not exist. The self-test derives both
 * directions FROM `CORPUS_ROOTS` rather than re-spelling the roots, so a corpus
 * root added or dropped reddens here instead of silently outrunning the
 * declaration. It has to be written out as a literal array: assembling it from
 * `CORPUS_ROOTS` at runtime would put it out of reach of the very text scan it
 * exists for -- identical runtime value, zero hints extracted, the defect
 * preserved behind a tidier line (`check-watch-hint-literal` holds this shape).
 */
const ROOT_DIR_WATCH_HINTS = ['packages/**', 'examples/**'];

/**
 * ⛔ SHRINK-ONLY. Anchors the page writes that are deliberately NOT elevation read
 * sites. `needle` must appear on exactly ONE line of `file`; that line is where the
Expand DownExpand Up@@ -1561,6 +1626,64 @@ function selfTest() {
 t('WIRING: lint.yml runs the --self-test leg too', lintYml.includes(`node ${SELF} --self-test`));
 }

 // ── POPULATION DECLARATION: what the dispatch derivation is told this gate reads ──
 //
 // Nothing in this file can ENFORCE these: `ROOT_DIR_WATCH_HINTS` is read by
 // another tool entirely (`extractWatchHints` in `scripts/pm/dispatch-gates.mjs`),
 // so a stale or wrong declaration runs green here forever and pays itself out as
 // a dev dispatched on a `packages/` card with this gate absent from the brief --
 // the exact round this declaration was added to end. Both directions are derived
 // from `CORPUS_ROOTS`, never re-spelled: a corpus root added or dropped there has
 // to move this declaration or fail here.
 const declaredRoots = ROOT_DIR_WATCH_HINTS.map((h) => h.replace(/\/\*+$/, ''));
 t(
 'POPULATION DECLARATION: every root the census walks is declared',
 CORPUS_ROOTS.every((r) => ROOT_DIR_WATCH_HINTS.includes(`${r}/**`)),
 JSON.stringify({ CORPUS_ROOTS, ROOT_DIR_WATCH_HINTS })
 );
 t(
 'POPULATION DECLARATION: and it declares no root the census does not walk (a declaration that can '
 + 'drift from the walk is worse than none -- it replaces a silent gate with a lying one)',
 declaredRoots.every((r) => CORPUS_ROOTS.includes(r)),
 JSON.stringify(declaredRoots)
 );
 t(
 'POPULATION DECLARATION: each declared literal carries a separator -- a bare root word is refused as '
 + 'too generic by the consumer and would reach nothing',
 ROOT_DIR_WATCH_HINTS.every((h) => h.includes('/'))
 );
 t(
 'POPULATION DECLARATION: the repo root is NOT declared -- naming it would put this gate in every '
 + "card's brief to reach the two subtrees whose edits can turn it red",
 !declaredRoots.some((r) => r === '' || r === '.')
 );
 t(
 'POPULATION DECLARATION: the declared form is NOT the walk root itself (provenance, never a lookup '
 + 'key -- the glob form handed to the census would name directories that do not exist)',
 !CORPUS_ROOTS.some((r) => ROOT_DIR_WATCH_HINTS.includes(r))
 );
 // The literal SPELLING is the whole mechanism: the consumer scans source text,
 // so `CORPUS_ROOTS.map((r) => `${r}/**`)` would keep the runtime value, keep
 // every assertion above green, and contribute ZERO hints. `check-watch-hint-literal`
 // owns that rule fleet-wide; this pin is the own-source half, statement-scoped so
 // a second mention in prose or in a neighbouring assertion cannot satisfy it.
 let ownSource = null;
 try {
 ownSource = readFileSync(join(ROOT, SELF), 'utf8');
 } catch (err) {
 t('POPULATION DECLARATION: this gate can read its own source', false, err.code ?? err.message);
 }
 if (ownSource !== null) {
 const declSites = [...ownSource.matchAll(/\bconst\s+ROOT_DIR_WATCH_HINTS\s*=\s*([^;]*);/g)];
 t(
 'POPULATION DECLARATION: declared exactly once, as an array of quoted literals the text scan can read',
 declSites.length === 1 &&
 ROOT_DIR_WATCH_HINTS.every((h) => declSites[0][1].includes(`'${h}'`)) &&
 !/[A-Za-z_$][\w$]*\s*\./.test(declSites[0][1]),
 JSON.stringify(declSites.map((d) => d[1].replace(/\s+/g, ' ')))
 );
 }

 process.stdout.write(
 failures === 0
 ? '\ncheck-system-context-census --self-test: all cases passed\n'
Expand Down

15 changes: 14 additions & 1 deletion
scripts/isystem-census.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -136,9 +136,22 @@ export function isTestPath(relPath) {
 return /\.(test|spec)\./.test(relPath) || /(^|\/)(tests|__tests__|qa)\//.test(relPath);
}

/**
 * The subtrees this census walks -- the REAL population of every number it
 * reports and of the gate that holds the page to them.
 *
 * Named rather than spelled inline because a second reader needs it: the gate
 * declares this population to the dispatch derivation, and a declaration that
 * can drift from the walk is worse than none. `check-system-context-census.mjs`
 * derives its `ROOT_DIR_WATCH_HINTS` from this constant in both directions, so
 * a root added or removed here reddens that gate's self-test instead of quietly
 * widening the census past what any card is told about.
 */
export const CORPUS_ROOTS = ['packages', 'examples'];

/** Every tracked, non-dist TypeScript file of the corpus -- tests included. */
export function collectCorpus(root = ROOT) {
 return execFileSync('git', ['-C', root, 'ls-files', 'packages', 'examples'], {
 return execFileSync('git', ['-C', root, 'ls-files', ...CORPUS_ROOTS], {
 encoding: 'utf8',
 maxBuffer: 1 << 28,
 })
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
Declare the packages/examples census subtree check-system-context-census actually reads#14323

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

baozhoutao
merged 1 commit into

from

Sep 2, 2026

+138

−2

 Merged


Declare the packages/examples census subtree check-system-context-census actually reads
#14323
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


125 changes: 124 additions & 1 deletion
scripts/check-system-context-census.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -113,6 +113,13 @@
 * change over a population that never moved (#13490). `fixAnchors` carries the two
 * measured occurrences and why the union is the safer shape.
 *
 * ⇒ So the repair for a line-shift red is `--fix` and never a hand-edited line
 * number, and the repairing PR should state that `--fix` REFUSED ZERO files. That
 * sentence is what separates a pure re-anchor from a population change that
 * happened to be shifted at the same time: the refusal is the gate's only signal
 * that a site arrived or vanished, and a `--fix` run reporting refusals leaves
 * rows a human still has to write.
 *
 * ## Refusals, never quiet passes (#4690)
 *
 * A page that cannot be read, a census with no sites, zero anchors found, a corpus
Expand DownExpand Up@@ -157,12 +164,70 @@ import { join } from 'node:path';
import { fileURLToPath } from 'node:url';

import { isEntrypoint } from './invoked-as.mjs';
import { runCensus, siteKeys } from './isystem-census.mjs';
import { CORPUS_ROOTS, runCensus, siteKeys } from './isystem-census.mjs';
import { extractLineAnchors, extractPathCitations, resolveAnchorFile } from './doc-line-anchors.mjs';

const ROOT = join(fileURLToPath(new URL('.', import.meta.url)), '..');
export const PAGE = 'content/docs/permissions/system-context.mdx';

/**
 * ── The population this gate READS, declared where the dispatch tool looks ───
 *
 * `extractWatchHints` in `scripts/pm/dispatch-gates.mjs` reads a gate's module
 * body for path literals and treats them as the population that gate watches.
 * This gate spelled 29 of them -- the page, the four colliding declarations, the
 * `NON_READ_ANCHORS` citations -- and every one of them names an ARTIFACT it
 * maintains. Its real population is the corpus `isystem-census.mjs` walks:
 * `CORPUS_ROOTS`, today 109 elevation read sites in 20 packages across 45 files
 * held by 145 anchors.
 *
 * ⭐ The failure that produced this declaration is not a missed red. It is a
 * GREEN that was true and insufficient. A diff that merely SHIFTS a cited line
 * -- an added import, a widened docblock -- reds this gate in CI while the
 * derivation places it in the `silent` bucket, which reads as a clearance and is
 * not: "this gate names paths, none of them yours" is the same sentence for a
 * gate that cannot see your diff and for one whose whole verdict turns on it.
 * Measured three times in one night on three unrelated PRs; each cost a CI lap
 * plus a repair dispatch, and each dev had honestly run its derived families.
 *
 * ## Why the subtree and not the 45 cited files
 *
 * A roster of the files that carry a read site TODAY can never name the file
 * that grows one TOMORROW -- and a NEW read site is precisely the finding this
 * gate exists for (POPULATION, check B above, the mandatory half). A narrow
 * declaration would derive green for the one case that most needs the lead, so
 * it re-introduces this defect wearing the shape of a fix.
 *
 * ## The cost of the wide form, measured rather than asserted (at a39b02a6b)
 *
 * Families derived per probe path, before -> after this declaration:
 *
 * packages/lint/src/authoring-rules.ts 19 -> 20
 * packages/plugins/plugin-auth/src/auth-plugin.ts 22 -> 23
 * packages/metadata-protocol/src/protocol.ts 21 -> 22
 * packages/spec/src/data/object.zod.ts 42 -> 42 (already named)
 * examples/app-crm/package.json 17 -> 18
 * content/docs/permissions/access-matrix.mdx 30 -> 30 (unchanged)
 * scripts/check-nul-bytes.mjs 14 -> 14 (unchanged)
 * .github/workflows/lint.yml 23 -> 23 (unchanged)
 *
 * So the price is ONE family, on cards under the two subtrees only, against a
 * gate that runs in about 3s and is run by CI on every PR regardless. What the
 * lead buys is the CI lap it replaces.
 *
 * ## Provenance, never a lookup key
 *
 * Nothing here reads this array: `collectCorpus` walks `CORPUS_ROOTS`, and the
 * glob form would name directories that do not exist. The self-test derives both
 * directions FROM `CORPUS_ROOTS` rather than re-spelling the roots, so a corpus
 * root added or dropped reddens here instead of silently outrunning the
 * declaration. It has to be written out as a literal array: assembling it from
 * `CORPUS_ROOTS` at runtime would put it out of reach of the very text scan it
 * exists for -- identical runtime value, zero hints extracted, the defect
 * preserved behind a tidier line (`check-watch-hint-literal` holds this shape).
 */
const ROOT_DIR_WATCH_HINTS = ['packages/**', 'examples/**'];

/**
 * ⛔ SHRINK-ONLY. Anchors the page writes that are deliberately NOT elevation read
 * sites. `needle` must appear on exactly ONE line of `file`; that line is where the
Expand DownExpand Up@@ -1561,6 +1626,64 @@ function selfTest() {
 t('WIRING: lint.yml runs the --self-test leg too', lintYml.includes(`node ${SELF} --self-test`));
 }

 // ── POPULATION DECLARATION: what the dispatch derivation is told this gate reads ──
 //
 // Nothing in this file can ENFORCE these: `ROOT_DIR_WATCH_HINTS` is read by
 // another tool entirely (`extractWatchHints` in `scripts/pm/dispatch-gates.mjs`),
 // so a stale or wrong declaration runs green here forever and pays itself out as
 // a dev dispatched on a `packages/` card with this gate absent from the brief --
 // the exact round this declaration was added to end. Both directions are derived
 // from `CORPUS_ROOTS`, never re-spelled: a corpus root added or dropped there has
 // to move this declaration or fail here.
 const declaredRoots = ROOT_DIR_WATCH_HINTS.map((h) => h.replace(/\/\*+$/, ''));
 t(
 'POPULATION DECLARATION: every root the census walks is declared',
 CORPUS_ROOTS.every((r) => ROOT_DIR_WATCH_HINTS.includes(`${r}/**`)),
 JSON.stringify({ CORPUS_ROOTS, ROOT_DIR_WATCH_HINTS })
 );
 t(
 'POPULATION DECLARATION: and it declares no root the census does not walk (a declaration that can '
 + 'drift from the walk is worse than none -- it replaces a silent gate with a lying one)',
 declaredRoots.every((r) => CORPUS_ROOTS.includes(r)),
 JSON.stringify(declaredRoots)
 );
 t(
 'POPULATION DECLARATION: each declared literal carries a separator -- a bare root word is refused as '
 + 'too generic by the consumer and would reach nothing',
 ROOT_DIR_WATCH_HINTS.every((h) => h.includes('/'))
 );
 t(
 'POPULATION DECLARATION: the repo root is NOT declared -- naming it would put this gate in every '
 + "card's brief to reach the two subtrees whose edits can turn it red",
 !declaredRoots.some((r) => r === '' || r === '.')
 );
 t(
 'POPULATION DECLARATION: the declared form is NOT the walk root itself (provenance, never a lookup '
 + 'key -- the glob form handed to the census would name directories that do not exist)',
 !CORPUS_ROOTS.some((r) => ROOT_DIR_WATCH_HINTS.includes(r))
 );
 // The literal SPELLING is the whole mechanism: the consumer scans source text,
 // so `CORPUS_ROOTS.map((r) => `${r}/**`)` would keep the runtime value, keep
 // every assertion above green, and contribute ZERO hints. `check-watch-hint-literal`
 // owns that rule fleet-wide; this pin is the own-source half, statement-scoped so
 // a second mention in prose or in a neighbouring assertion cannot satisfy it.
 let ownSource = null;
 try {
 ownSource = readFileSync(join(ROOT, SELF), 'utf8');
 } catch (err) {
 t('POPULATION DECLARATION: this gate can read its own source', false, err.code ?? err.message);
 }
 if (ownSource !== null) {
 const declSites = [...ownSource.matchAll(/\bconst\s+ROOT_DIR_WATCH_HINTS\s*=\s*([^;]*);/g)];
 t(
 'POPULATION DECLARATION: declared exactly once, as an array of quoted literals the text scan can read',
 declSites.length === 1 &&
 ROOT_DIR_WATCH_HINTS.every((h) => declSites[0][1].includes(`'${h}'`)) &&
 !/[A-Za-z_$][\w$]*\s*\./.test(declSites[0][1]),
 JSON.stringify(declSites.map((d) => d[1].replace(/\s+/g, ' ')))
 );
 }

 process.stdout.write(
 failures === 0
 ? '\ncheck-system-context-census --self-test: all cases passed\n'
Expand Down

15 changes: 14 additions & 1 deletion
scripts/isystem-census.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -136,9 +136,22 @@ export function isTestPath(relPath) {
 return /\.(test|spec)\./.test(relPath) || /(^|\/)(tests|__tests__|qa)\//.test(relPath);
}

/**
 * The subtrees this census walks -- the REAL population of every number it
 * reports and of the gate that holds the page to them.
 *
 * Named rather than spelled inline because a second reader needs it: the gate
 * declares this population to the dispatch derivation, and a declaration that
 * can drift from the walk is worse than none. `check-system-context-census.mjs`
 * derives its `ROOT_DIR_WATCH_HINTS` from this constant in both directions, so
 * a root added or removed here reddens that gate's self-test instead of quietly
 * widening the census past what any card is told about.
 */
export const CORPUS_ROOTS = ['packages', 'examples'];

/** Every tracked, non-dist TypeScript file of the corpus -- tests included. */
export function collectCorpus(root = ROOT) {
 return execFileSync('git', ['-C', root, 'ls-files', 'packages', 'examples'], {
 return execFileSync('git', ['-C', root, 'ls-files', ...CORPUS_ROOTS], {
 encoding: 'utf8',
 maxBuffer: 1 << 28,
 })
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Declare the packages/examples census subtree check-system-context-census actually reads#14323

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

baozhoutao
merged 1 commit into

from

Sep 2, 2026

+138

−2

 Merged


Declare the packages/examples census subtree check-system-context-census actually reads
#14323
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


125 changes: 124 additions & 1 deletion
scripts/check-system-context-census.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -113,6 +113,13 @@
 * change over a population that never moved (#13490). `fixAnchors` carries the two
 * measured occurrences and why the union is the safer shape.
 *
 * ⇒ So the repair for a line-shift red is `--fix` and never a hand-edited line
 * number, and the repairing PR should state that `--fix` REFUSED ZERO files. That
 * sentence is what separates a pure re-anchor from a population change that
 * happened to be shifted at the same time: the refusal is the gate's only signal
 * that a site arrived or vanished, and a `--fix` run reporting refusals leaves
 * rows a human still has to write.
 *
 * ## Refusals, never quiet passes (#4690)
 *
 * A page that cannot be read, a census with no sites, zero anchors found, a corpus
Expand DownExpand Up@@ -157,12 +164,70 @@ import { join } from 'node:path';
import { fileURLToPath } from 'node:url';

import { isEntrypoint } from './invoked-as.mjs';
import { runCensus, siteKeys } from './isystem-census.mjs';
import { CORPUS_ROOTS, runCensus, siteKeys } from './isystem-census.mjs';
import { extractLineAnchors, extractPathCitations, resolveAnchorFile } from './doc-line-anchors.mjs';

const ROOT = join(fileURLToPath(new URL('.', import.meta.url)), '..');
export const PAGE = 'content/docs/permissions/system-context.mdx';

/**
 * ── The population this gate READS, declared where the dispatch tool looks ───
 *
 * `extractWatchHints` in `scripts/pm/dispatch-gates.mjs` reads a gate's module
 * body for path literals and treats them as the population that gate watches.
 * This gate spelled 29 of them -- the page, the four colliding declarations, the
 * `NON_READ_ANCHORS` citations -- and every one of them names an ARTIFACT it
 * maintains. Its real population is the corpus `isystem-census.mjs` walks:
 * `CORPUS_ROOTS`, today 109 elevation read sites in 20 packages across 45 files
 * held by 145 anchors.
 *
 * ⭐ The failure that produced this declaration is not a missed red. It is a
 * GREEN that was true and insufficient. A diff that merely SHIFTS a cited line
 * -- an added import, a widened docblock -- reds this gate in CI while the
 * derivation places it in the `silent` bucket, which reads as a clearance and is
 * not: "this gate names paths, none of them yours" is the same sentence for a
 * gate that cannot see your diff and for one whose whole verdict turns on it.
 * Measured three times in one night on three unrelated PRs; each cost a CI lap
 * plus a repair dispatch, and each dev had honestly run its derived families.
 *
 * ## Why the subtree and not the 45 cited files
 *
 * A roster of the files that carry a read site TODAY can never name the file
 * that grows one TOMORROW -- and a NEW read site is precisely the finding this
 * gate exists for (POPULATION, check B above, the mandatory half). A narrow
 * declaration would derive green for the one case that most needs the lead, so
 * it re-introduces this defect wearing the shape of a fix.
 *
 * ## The cost of the wide form, measured rather than asserted (at a39b02a6b)
 *
 * Families derived per probe path, before -> after this declaration:
 *
 * packages/lint/src/authoring-rules.ts 19 -> 20
 * packages/plugins/plugin-auth/src/auth-plugin.ts 22 -> 23
 * packages/metadata-protocol/src/protocol.ts 21 -> 22
 * packages/spec/src/data/object.zod.ts 42 -> 42 (already named)
 * examples/app-crm/package.json 17 -> 18
 * content/docs/permissions/access-matrix.mdx 30 -> 30 (unchanged)
 * scripts/check-nul-bytes.mjs 14 -> 14 (unchanged)
 * .github/workflows/lint.yml 23 -> 23 (unchanged)
 *
 * So the price is ONE family, on cards under the two subtrees only, against a
 * gate that runs in about 3s and is run by CI on every PR regardless. What the
 * lead buys is the CI lap it replaces.
 *
 * ## Provenance, never a lookup key
 *
 * Nothing here reads this array: `collectCorpus` walks `CORPUS_ROOTS`, and the
 * glob form would name directories that do not exist. The self-test derives both
 * directions FROM `CORPUS_ROOTS` rather than re-spelling the roots, so a corpus
 * root added or dropped reddens here instead of silently outrunning the
 * declaration. It has to be written out as a literal array: assembling it from
 * `CORPUS_ROOTS` at runtime would put it out of reach of the very text scan it
 * exists for -- identical runtime value, zero hints extracted, the defect
 * preserved behind a tidier line (`check-watch-hint-literal` holds this shape).
 */
const ROOT_DIR_WATCH_HINTS = ['packages/**', 'examples/**'];

/**
 * ⛔ SHRINK-ONLY. Anchors the page writes that are deliberately NOT elevation read
 * sites. `needle` must appear on exactly ONE line of `file`; that line is where the
Expand DownExpand Up@@ -1561,6 +1626,64 @@ function selfTest() {
 t('WIRING: lint.yml runs the --self-test leg too', lintYml.includes(`node ${SELF} --self-test`));
 }

 // ── POPULATION DECLARATION: what the dispatch derivation is told this gate reads ──
 //
 // Nothing in this file can ENFORCE these: `ROOT_DIR_WATCH_HINTS` is read by
 // another tool entirely (`extractWatchHints` in `scripts/pm/dispatch-gates.mjs`),
 // so a stale or wrong declaration runs green here forever and pays itself out as
 // a dev dispatched on a `packages/` card with this gate absent from the brief --
 // the exact round this declaration was added to end. Both directions are derived
 // from `CORPUS_ROOTS`, never re-spelled: a corpus root added or dropped there has
 // to move this declaration or fail here.
 const declaredRoots = ROOT_DIR_WATCH_HINTS.map((h) => h.replace(/\/\*+$/, ''));
 t(
 'POPULATION DECLARATION: every root the census walks is declared',
 CORPUS_ROOTS.every((r) => ROOT_DIR_WATCH_HINTS.includes(`${r}/**`)),
 JSON.stringify({ CORPUS_ROOTS, ROOT_DIR_WATCH_HINTS })
 );
 t(
 'POPULATION DECLARATION: and it declares no root the census does not walk (a declaration that can '
 + 'drift from the walk is worse than none -- it replaces a silent gate with a lying one)',
 declaredRoots.every((r) => CORPUS_ROOTS.includes(r)),
 JSON.stringify(declaredRoots)
 );
 t(
 'POPULATION DECLARATION: each declared literal carries a separator -- a bare root word is refused as '
 + 'too generic by the consumer and would reach nothing',
 ROOT_DIR_WATCH_HINTS.every((h) => h.includes('/'))
 );
 t(
 'POPULATION DECLARATION: the repo root is NOT declared -- naming it would put this gate in every '
 + "card's brief to reach the two subtrees whose edits can turn it red",
 !declaredRoots.some((r) => r === '' || r === '.')
 );
 t(
 'POPULATION DECLARATION: the declared form is NOT the walk root itself (provenance, never a lookup '
 + 'key -- the glob form handed to the census would name directories that do not exist)',
 !CORPUS_ROOTS.some((r) => ROOT_DIR_WATCH_HINTS.includes(r))
 );
 // The literal SPELLING is the whole mechanism: the consumer scans source text,
 // so `CORPUS_ROOTS.map((r) => `${r}/**`)` would keep the runtime value, keep
 // every assertion above green, and contribute ZERO hints. `check-watch-hint-literal`
 // owns that rule fleet-wide; this pin is the own-source half, statement-scoped so
 // a second mention in prose or in a neighbouring assertion cannot satisfy it.
 let ownSource = null;
 try {
 ownSource = readFileSync(join(ROOT, SELF), 'utf8');
 } catch (err) {
 t('POPULATION DECLARATION: this gate can read its own source', false, err.code ?? err.message);
 }
 if (ownSource !== null) {
 const declSites = [...ownSource.matchAll(/\bconst\s+ROOT_DIR_WATCH_HINTS\s*=\s*([^;]*);/g)];
 t(
 'POPULATION DECLARATION: declared exactly once, as an array of quoted literals the text scan can read',
 declSites.length === 1 &&
 ROOT_DIR_WATCH_HINTS.every((h) => declSites[0][1].includes(`'${h}'`)) &&
 !/[A-Za-z_$][\w$]*\s*\./.test(declSites[0][1]),
 JSON.stringify(declSites.map((d) => d[1].replace(/\s+/g, ' ')))
 );
 }

 process.stdout.write(
 failures === 0
 ? '\ncheck-system-context-census --self-test: all cases passed\n'
Expand Down

15 changes: 14 additions & 1 deletion
scripts/isystem-census.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -136,9 +136,22 @@ export function isTestPath(relPath) {
 return /\.(test|spec)\./.test(relPath) || /(^|\/)(tests|__tests__|qa)\//.test(relPath);
}

/**
 * The subtrees this census walks -- the REAL population of every number it
 * reports and of the gate that holds the page to them.
 *
 * Named rather than spelled inline because a second reader needs it: the gate
 * declares this population to the dispatch derivation, and a declaration that
 * can drift from the walk is worse than none. `check-system-context-census.mjs`
 * derives its `ROOT_DIR_WATCH_HINTS` from this constant in both directions, so
 * a root added or removed here reddens that gate's self-test instead of quietly
 * widening the census past what any card is told about.
 */
export const CORPUS_ROOTS = ['packages', 'examples'];

/** Every tracked, non-dist TypeScript file of the corpus -- tests included. */
export function collectCorpus(root = ROOT) {
 return execFileSync('git', ['-C', root, 'ls-files', 'packages', 'examples'], {
 return execFileSync('git', ['-C', root, 'ls-files', ...CORPUS_ROOTS], {
 encoding: 'utf8',
 maxBuffer: 1 << 28,
 })
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Declare the packages/examples census subtree check-system-context-census actually reads#14323

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

baozhoutao
merged 1 commit into

from

Sep 2, 2026

+138

−2

 Merged


Declare the packages/examples census subtree check-system-context-census actually reads
#14323
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


125 changes: 124 additions & 1 deletion
scripts/check-system-context-census.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -113,6 +113,13 @@
 * change over a population that never moved (#13490). `fixAnchors` carries the two
 * measured occurrences and why the union is the safer shape.
 *
 * ⇒ So the repair for a line-shift red is `--fix` and never a hand-edited line
 * number, and the repairing PR should state that `--fix` REFUSED ZERO files. That
 * sentence is what separates a pure re-anchor from a population change that
 * happened to be shifted at the same time: the refusal is the gate's only signal
 * that a site arrived or vanished, and a `--fix` run reporting refusals leaves
 * rows a human still has to write.
 *
 * ## Refusals, never quiet passes (#4690)
 *
 * A page that cannot be read, a census with no sites, zero anchors found, a corpus
Expand DownExpand Up@@ -157,12 +164,70 @@ import { join } from 'node:path';
import { fileURLToPath } from 'node:url';

import { isEntrypoint } from './invoked-as.mjs';
import { runCensus, siteKeys } from './isystem-census.mjs';
import { CORPUS_ROOTS, runCensus, siteKeys } from './isystem-census.mjs';
import { extractLineAnchors, extractPathCitations, resolveAnchorFile } from './doc-line-anchors.mjs';

const ROOT = join(fileURLToPath(new URL('.', import.meta.url)), '..');
export const PAGE = 'content/docs/permissions/system-context.mdx';

/**
 * ── The population this gate READS, declared where the dispatch tool looks ───
 *
 * `extractWatchHints` in `scripts/pm/dispatch-gates.mjs` reads a gate's module
 * body for path literals and treats them as the population that gate watches.
 * This gate spelled 29 of them -- the page, the four colliding declarations, the
 * `NON_READ_ANCHORS` citations -- and every one of them names an ARTIFACT it
 * maintains. Its real population is the corpus `isystem-census.mjs` walks:
 * `CORPUS_ROOTS`, today 109 elevation read sites in 20 packages across 45 files
 * held by 145 anchors.
 *
 * ⭐ The failure that produced this declaration is not a missed red. It is a
 * GREEN that was true and insufficient. A diff that merely SHIFTS a cited line
 * -- an added import, a widened docblock -- reds this gate in CI while the
 * derivation places it in the `silent` bucket, which reads as a clearance and is
 * not: "this gate names paths, none of them yours" is the same sentence for a
 * gate that cannot see your diff and for one whose whole verdict turns on it.
 * Measured three times in one night on three unrelated PRs; each cost a CI lap
 * plus a repair dispatch, and each dev had honestly run its derived families.
 *
 * ## Why the subtree and not the 45 cited files
 *
 * A roster of the files that carry a read site TODAY can never name the file
 * that grows one TOMORROW -- and a NEW read site is precisely the finding this
 * gate exists for (POPULATION, check B above, the mandatory half). A narrow
 * declaration would derive green for the one case that most needs the lead, so
 * it re-introduces this defect wearing the shape of a fix.
 *
 * ## The cost of the wide form, measured rather than asserted (at a39b02a6b)
 *
 * Families derived per probe path, before -> after this declaration:
 *
 * packages/lint/src/authoring-rules.ts 19 -> 20
 * packages/plugins/plugin-auth/src/auth-plugin.ts 22 -> 23
 * packages/metadata-protocol/src/protocol.ts 21 -> 22
 * packages/spec/src/data/object.zod.ts 42 -> 42 (already named)
 * examples/app-crm/package.json 17 -> 18
 * content/docs/permissions/access-matrix.mdx 30 -> 30 (unchanged)
 * scripts/check-nul-bytes.mjs 14 -> 14 (unchanged)
 * .github/workflows/lint.yml 23 -> 23 (unchanged)
 *
 * So the price is ONE family, on cards under the two subtrees only, against a
 * gate that runs in about 3s and is run by CI on every PR regardless. What the
 * lead buys is the CI lap it replaces.
 *
 * ## Provenance, never a lookup key
 *
 * Nothing here reads this array: `collectCorpus` walks `CORPUS_ROOTS`, and the
 * glob form would name directories that do not exist. The self-test derives both
 * directions FROM `CORPUS_ROOTS` rather than re-spelling the roots, so a corpus
 * root added or dropped reddens here instead of silently outrunning the
 * declaration. It has to be written out as a literal array: assembling it from
 * `CORPUS_ROOTS` at runtime would put it out of reach of the very text scan it
 * exists for -- identical runtime value, zero hints extracted, the defect
 * preserved behind a tidier line (`check-watch-hint-literal` holds this shape).
 */
const ROOT_DIR_WATCH_HINTS = ['packages/**', 'examples/**'];

/**
 * ⛔ SHRINK-ONLY. Anchors the page writes that are deliberately NOT elevation read
 * sites. `needle` must appear on exactly ONE line of `file`; that line is where the
Expand DownExpand Up@@ -1561,6 +1626,64 @@ function selfTest() {
 t('WIRING: lint.yml runs the --self-test leg too', lintYml.includes(`node ${SELF} --self-test`));
 }

 // ── POPULATION DECLARATION: what the dispatch derivation is told this gate reads ──
 //
 // Nothing in this file can ENFORCE these: `ROOT_DIR_WATCH_HINTS` is read by
 // another tool entirely (`extractWatchHints` in `scripts/pm/dispatch-gates.mjs`),
 // so a stale or wrong declaration runs green here forever and pays itself out as
 // a dev dispatched on a `packages/` card with this gate absent from the brief --
 // the exact round this declaration was added to end. Both directions are derived
 // from `CORPUS_ROOTS`, never re-spelled: a corpus root added or dropped there has
 // to move this declaration or fail here.
 const declaredRoots = ROOT_DIR_WATCH_HINTS.map((h) => h.replace(/\/\*+$/, ''));
 t(
 'POPULATION DECLARATION: every root the census walks is declared',
 CORPUS_ROOTS.every((r) => ROOT_DIR_WATCH_HINTS.includes(`${r}/**`)),
 JSON.stringify({ CORPUS_ROOTS, ROOT_DIR_WATCH_HINTS })
 );
 t(
 'POPULATION DECLARATION: and it declares no root the census does not walk (a declaration that can '
 + 'drift from the walk is worse than none -- it replaces a silent gate with a lying one)',
 declaredRoots.every((r) => CORPUS_ROOTS.includes(r)),
 JSON.stringify(declaredRoots)
 );
 t(
 'POPULATION DECLARATION: each declared literal carries a separator -- a bare root word is refused as '
 + 'too generic by the consumer and would reach nothing',
 ROOT_DIR_WATCH_HINTS.every((h) => h.includes('/'))
 );
 t(
 'POPULATION DECLARATION: the repo root is NOT declared -- naming it would put this gate in every '
 + "card's brief to reach the two subtrees whose edits can turn it red",
 !declaredRoots.some((r) => r === '' || r === '.')
 );
 t(
 'POPULATION DECLARATION: the declared form is NOT the walk root itself (provenance, never a lookup '
 + 'key -- the glob form handed to the census would name directories that do not exist)',
 !CORPUS_ROOTS.some((r) => ROOT_DIR_WATCH_HINTS.includes(r))
 );
 // The literal SPELLING is the whole mechanism: the consumer scans source text,
 // so `CORPUS_ROOTS.map((r) => `${r}/**`)` would keep the runtime value, keep
 // every assertion above green, and contribute ZERO hints. `check-watch-hint-literal`
 // owns that rule fleet-wide; this pin is the own-source half, statement-scoped so
 // a second mention in prose or in a neighbouring assertion cannot satisfy it.
 let ownSource = null;
 try {
 ownSource = readFileSync(join(ROOT, SELF), 'utf8');
 } catch (err) {
 t('POPULATION DECLARATION: this gate can read its own source', false, err.code ?? err.message);
 }
 if (ownSource !== null) {
 const declSites = [...ownSource.matchAll(/\bconst\s+ROOT_DIR_WATCH_HINTS\s*=\s*([^;]*);/g)];
 t(
 'POPULATION DECLARATION: declared exactly once, as an array of quoted literals the text scan can read',
 declSites.length === 1 &&
 ROOT_DIR_WATCH_HINTS.every((h) => declSites[0][1].includes(`'${h}'`)) &&
 !/[A-Za-z_$][\w$]*\s*\./.test(declSites[0][1]),
 JSON.stringify(declSites.map((d) => d[1].replace(/\s+/g, ' ')))
 );
 }

 process.stdout.write(
 failures === 0
 ? '\ncheck-system-context-census --self-test: all cases passed\n'
Expand Down

15 changes: 14 additions & 1 deletion
scripts/isystem-census.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -136,9 +136,22 @@ export function isTestPath(relPath) {
 return /\.(test|spec)\./.test(relPath) || /(^|\/)(tests|__tests__|qa)\//.test(relPath);
}

/**
 * The subtrees this census walks -- the REAL population of every number it
 * reports and of the gate that holds the page to them.
 *
 * Named rather than spelled inline because a second reader needs it: the gate
 * declares this population to the dispatch derivation, and a declaration that
 * can drift from the walk is worse than none. `check-system-context-census.mjs`
 * derives its `ROOT_DIR_WATCH_HINTS` from this constant in both directions, so
 * a root added or removed here reddens that gate's self-test instead of quietly
 * widening the census past what any card is told about.
 */
export const CORPUS_ROOTS = ['packages', 'examples'];

/** Every tracked, non-dist TypeScript file of the corpus -- tests included. */
export function collectCorpus(root = ROOT) {
 return execFileSync('git', ['-C', root, 'ls-files', 'packages', 'examples'], {
 return execFileSync('git', ['-C', root, 'ls-files', ...CORPUS_ROOTS], {
 encoding: 'utf8',
 maxBuffer: 1 << 28,
 })
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
Declare the packages/examples census subtree check-system-context-census actually reads#14323

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

baozhoutao
merged 1 commit into

from

Sep 2, 2026

+138

−2

 Merged


Declare the packages/examples census subtree check-system-context-census actually reads
#14323
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


125 changes: 124 additions & 1 deletion
scripts/check-system-context-census.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -113,6 +113,13 @@
 * change over a population that never moved (#13490). `fixAnchors` carries the two
 * measured occurrences and why the union is the safer shape.
 *
 * ⇒ So the repair for a line-shift red is `--fix` and never a hand-edited line
 * number, and the repairing PR should state that `--fix` REFUSED ZERO files. That
 * sentence is what separates a pure re-anchor from a population change that
 * happened to be shifted at the same time: the refusal is the gate's only signal
 * that a site arrived or vanished, and a `--fix` run reporting refusals leaves
 * rows a human still has to write.
 *
 * ## Refusals, never quiet passes (#4690)
 *
 * A page that cannot be read, a census with no sites, zero anchors found, a corpus
Expand DownExpand Up@@ -157,12 +164,70 @@ import { join } from 'node:path';
import { fileURLToPath } from 'node:url';

import { isEntrypoint } from './invoked-as.mjs';
import { runCensus, siteKeys } from './isystem-census.mjs';
import { CORPUS_ROOTS, runCensus, siteKeys } from './isystem-census.mjs';
import { extractLineAnchors, extractPathCitations, resolveAnchorFile } from './doc-line-anchors.mjs';

const ROOT = join(fileURLToPath(new URL('.', import.meta.url)), '..');
export const PAGE = 'content/docs/permissions/system-context.mdx';

/**
 * ── The population this gate READS, declared where the dispatch tool looks ───
 *
 * `extractWatchHints` in `scripts/pm/dispatch-gates.mjs` reads a gate's module
 * body for path literals and treats them as the population that gate watches.
 * This gate spelled 29 of them -- the page, the four colliding declarations, the
 * `NON_READ_ANCHORS` citations -- and every one of them names an ARTIFACT it
 * maintains. Its real population is the corpus `isystem-census.mjs` walks:
 * `CORPUS_ROOTS`, today 109 elevation read sites in 20 packages across 45 files
 * held by 145 anchors.
 *
 * ⭐ The failure that produced this declaration is not a missed red. It is a
 * GREEN that was true and insufficient. A diff that merely SHIFTS a cited line
 * -- an added import, a widened docblock -- reds this gate in CI while the
 * derivation places it in the `silent` bucket, which reads as a clearance and is
 * not: "this gate names paths, none of them yours" is the same sentence for a
 * gate that cannot see your diff and for one whose whole verdict turns on it.
 * Measured three times in one night on three unrelated PRs; each cost a CI lap
 * plus a repair dispatch, and each dev had honestly run its derived families.
 *
 * ## Why the subtree and not the 45 cited files
 *
 * A roster of the files that carry a read site TODAY can never name the file
 * that grows one TOMORROW -- and a NEW read site is precisely the finding this
 * gate exists for (POPULATION, check B above, the mandatory half). A narrow
 * declaration would derive green for the one case that most needs the lead, so
 * it re-introduces this defect wearing the shape of a fix.
 *
 * ## The cost of the wide form, measured rather than asserted (at a39b02a6b)
 *
 * Families derived per probe path, before -> after this declaration:
 *
 * packages/lint/src/authoring-rules.ts 19 -> 20
 * packages/plugins/plugin-auth/src/auth-plugin.ts 22 -> 23
 * packages/metadata-protocol/src/protocol.ts 21 -> 22
 * packages/spec/src/data/object.zod.ts 42 -> 42 (already named)
 * examples/app-crm/package.json 17 -> 18
 * content/docs/permissions/access-matrix.mdx 30 -> 30 (unchanged)
 * scripts/check-nul-bytes.mjs 14 -> 14 (unchanged)
 * .github/workflows/lint.yml 23 -> 23 (unchanged)
 *
 * So the price is ONE family, on cards under the two subtrees only, against a
 * gate that runs in about 3s and is run by CI on every PR regardless. What the
 * lead buys is the CI lap it replaces.
 *
 * ## Provenance, never a lookup key
 *
 * Nothing here reads this array: `collectCorpus` walks `CORPUS_ROOTS`, and the
 * glob form would name directories that do not exist. The self-test derives both
 * directions FROM `CORPUS_ROOTS` rather than re-spelling the roots, so a corpus
 * root added or dropped reddens here instead of silently outrunning the
 * declaration. It has to be written out as a literal array: assembling it from
 * `CORPUS_ROOTS` at runtime would put it out of reach of the very text scan it
 * exists for -- identical runtime value, zero hints extracted, the defect
 * preserved behind a tidier line (`check-watch-hint-literal` holds this shape).
 */
const ROOT_DIR_WATCH_HINTS = ['packages/**', 'examples/**'];

/**
 * ⛔ SHRINK-ONLY. Anchors the page writes that are deliberately NOT elevation read
 * sites. `needle` must appear on exactly ONE line of `file`; that line is where the
Expand DownExpand Up@@ -1561,6 +1626,64 @@ function selfTest() {
 t('WIRING: lint.yml runs the --self-test leg too', lintYml.includes(`node ${SELF} --self-test`));
 }

 // ── POPULATION DECLARATION: what the dispatch derivation is told this gate reads ──
 //
 // Nothing in this file can ENFORCE these: `ROOT_DIR_WATCH_HINTS` is read by
 // another tool entirely (`extractWatchHints` in `scripts/pm/dispatch-gates.mjs`),
 // so a stale or wrong declaration runs green here forever and pays itself out as
 // a dev dispatched on a `packages/` card with this gate absent from the brief --
 // the exact round this declaration was added to end. Both directions are derived
 // from `CORPUS_ROOTS`, never re-spelled: a corpus root added or dropped there has
 // to move this declaration or fail here.
 const declaredRoots = ROOT_DIR_WATCH_HINTS.map((h) => h.replace(/\/\*+$/, ''));
 t(
 'POPULATION DECLARATION: every root the census walks is declared',
 CORPUS_ROOTS.every((r) => ROOT_DIR_WATCH_HINTS.includes(`${r}/**`)),
 JSON.stringify({ CORPUS_ROOTS, ROOT_DIR_WATCH_HINTS })
 );
 t(
 'POPULATION DECLARATION: and it declares no root the census does not walk (a declaration that can '
 + 'drift from the walk is worse than none -- it replaces a silent gate with a lying one)',
 declaredRoots.every((r) => CORPUS_ROOTS.includes(r)),
 JSON.stringify(declaredRoots)
 );
 t(
 'POPULATION DECLARATION: each declared literal carries a separator -- a bare root word is refused as '
 + 'too generic by the consumer and would reach nothing',
 ROOT_DIR_WATCH_HINTS.every((h) => h.includes('/'))
 );
 t(
 'POPULATION DECLARATION: the repo root is NOT declared -- naming it would put this gate in every '
 + "card's brief to reach the two subtrees whose edits can turn it red",
 !declaredRoots.some((r) => r === '' || r === '.')
 );
 t(
 'POPULATION DECLARATION: the declared form is NOT the walk root itself (provenance, never a lookup '
 + 'key -- the glob form handed to the census would name directories that do not exist)',
 !CORPUS_ROOTS.some((r) => ROOT_DIR_WATCH_HINTS.includes(r))
 );
 // The literal SPELLING is the whole mechanism: the consumer scans source text,
 // so `CORPUS_ROOTS.map((r) => `${r}/**`)` would keep the runtime value, keep
 // every assertion above green, and contribute ZERO hints. `check-watch-hint-literal`
 // owns that rule fleet-wide; this pin is the own-source half, statement-scoped so
 // a second mention in prose or in a neighbouring assertion cannot satisfy it.
 let ownSource = null;
 try {
 ownSource = readFileSync(join(ROOT, SELF), 'utf8');
 } catch (err) {
 t('POPULATION DECLARATION: this gate can read its own source', false, err.code ?? err.message);
 }
 if (ownSource !== null) {
 const declSites = [...ownSource.matchAll(/\bconst\s+ROOT_DIR_WATCH_HINTS\s*=\s*([^;]*);/g)];
 t(
 'POPULATION DECLARATION: declared exactly once, as an array of quoted literals the text scan can read',
 declSites.length === 1 &&
 ROOT_DIR_WATCH_HINTS.every((h) => declSites[0][1].includes(`'${h}'`)) &&
 !/[A-Za-z_$][\w$]*\s*\./.test(declSites[0][1]),
 JSON.stringify(declSites.map((d) => d[1].replace(/\s+/g, ' ')))
 );
 }

 process.stdout.write(
 failures === 0
 ? '\ncheck-system-context-census --self-test: all cases passed\n'
Expand Down

15 changes: 14 additions & 1 deletion
scripts/isystem-census.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -136,9 +136,22 @@ export function isTestPath(relPath) {
 return /\.(test|spec)\./.test(relPath) || /(^|\/)(tests|__tests__|qa)\//.test(relPath);
}

/**
 * The subtrees this census walks -- the REAL population of every number it
 * reports and of the gate that holds the page to them.
 *
 * Named rather than spelled inline because a second reader needs it: the gate
 * declares this population to the dispatch derivation, and a declaration that
 * can drift from the walk is worse than none. `check-system-context-census.mjs`
 * derives its `ROOT_DIR_WATCH_HINTS` from this constant in both directions, so
 * a root added or removed here reddens that gate's self-test instead of quietly
 * widening the census past what any card is told about.
 */
export const CORPUS_ROOTS = ['packages', 'examples'];

/** Every tracked, non-dist TypeScript file of the corpus -- tests included. */
export function collectCorpus(root = ROOT) {
 return execFileSync('git', ['-C', root, 'ls-files', 'packages', 'examples'], {
 return execFileSync('git', ['-C', root, 'ls-files', ...CORPUS_ROOTS], {
 encoding: 'utf8',
 maxBuffer: 1 << 28,
 })
Expand Down
Loading