From 25b8ddd78898e5a944a542449ff24178eecb9245 Mon Sep 17 00:00:00 2001
From: Claude <jack@objectstack.ai>
Date: Fri, 21 Aug 2026 16:10:18 +0000
Subject: [PATCH] =?UTF-8?q?feat(gate):=20GENERATED=5FCOVERED=20=E2=80=94?=
 =?UTF-8?q?=20a=20tsconfig=20include=20rooted=20in=20a=20generated=20path?=
 =?UTF-8?q?=20must=20be=20produced=20by=20the=20typecheck=20script,=20or?=
 =?UTF-8?q?=20declared=20as=20deliberately=20not=20produced?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DdCnBGcHeufjrq7drTD3wt
---
 scripts/check-type-check-coverage.mjs | 665 +++++++++++++++++++++++++-
 1 file changed, 650 insertions(+), 15 deletions(-)

diff --git a/scripts/check-type-check-coverage.mjs b/scripts/check-type-check-coverage.mjs
index f927234cc3..7f46147fef 100644
--- a/scripts/check-type-check-coverage.mjs
+++ b/scripts/check-type-check-coverage.mjs
@@ -123,6 +123,47 @@
 //               invariant kept the two apart -- 54 root configs, 11 files in a
 //               source directory. The exclusion is argued in full, both ways,
 //               on UNCHECKED_SOURCE_DEBT below.
+//   GENERATED_COVERED
+//               a tsconfig `include` entry rooted in a GENERATED path -- one the
+//               repo's own ignore rules say is not checked in -- is either
+//               produced by the package's own `typecheck` script BEFORE tsc
+//               runs, or carries a row in GENERATED_INCLUDE_ROOTS below saying
+//               it is deliberately not produced, and why (#10880).
+//
+//               One notch further along than REAL, and the distance is the
+//               whole point. REAL asks whether the script invokes tsc at all;
+//               this asks whether the PROGRAM tsc gets is the one the config
+//               advertises. `apps/docs/tsconfig.json` includes
+//               `.next/types/**/*.ts`, written by `next typegen`, and the wired
+//               script was a bare `tsc --noEmit`: measured on main @ 7d483e1e5f
+//               with `.next` deleted, it exited 0 having compiled none of the
+//               generated route types (`tsc --listFiles` 1225 -> 1231 once
+//               typegen ran, the difference including a 160-line `validator.ts`
+//               that checks 13 route entry points). An ablation gave a layout a
+//               `params` shape its route cannot supply: the bare script stayed
+//               at exit 0 / 0 errors and the typegen'd one failed TS2344.
+//               COVERED, REAL, TESTS_COVERED, SOURCES_COVERED and RUNNABLE all
+//               passed the whole time, because every one of them is a question
+//               about files that EXIST.
+//
+//               The failure DIRECTION is what makes this an invariant rather
+//               than a lint. An absent generated directory makes tsc read GREEN
+//               over files that were never in the program -- silence that looks
+//               exactly like success. Every other way of getting the same
+//               config wrong (a stale directory, a generator that fails) ends
+//               in a red somebody reads.
+//
+//               "Declared, and deliberately NOT generated" has to be a passing
+//               state, because deleting the offending glob is not available as
+//               a repair: Next owns that array and `writeConfigurationDefaults`
+//               re-adds `.next/dev/types/**/*.ts` on the next `next dev` /
+//               `next build` (#10879 measured it by running that routine
+//               against a narrowed copy -- the glob came straight back and the
+//               file was rewritten). A guard that only accepted "generated by
+//               the script" would leave the honest answer unsayable and push
+//               the next author toward a narrowing Next undoes. So a row may
+//               declare no generator at all -- with a reason, which is the part
+//               a human reviews and the part nothing mechanical can supply.
 //   PINS_CHECKED
 //               a test file containing a `@ts-expect-error` directive sits
 //               inside a tsc program, or is listed in PHANTOM_PIN_DEBT below.
@@ -399,6 +440,7 @@ const PIN_ISSUE = 'https://github.com/objectstack-ai/objectstack/issues/5286';
 // finding later used ("the directory was never INCLUDED by anything"), which is
 // why the remedy names a file rather than describing a shape (#10756).
 const SPEC_SCRIPTS_PRECEDENT = 'packages/spec/tsconfig.scripts.json';
+const GENERATED_INCLUDE_ISSUE = 'https://github.com/objectstack-ai/objectstack/issues/10880';
 
 // A path in the root program whose edits move the `@objectstack/spec-monorepo`
 // count below, declared as a bare, whole-literal path so the dispatch
@@ -1042,6 +1084,67 @@ const UNCHECKED_SOURCE_DEBT = {
   'packages/services/service-realtime/scripts': '`i18n-extract.config.ts`, 3 x TS2883. See #10868.',
 };
 
+/**
+ * GENERATED_COVERED's declared table (#10880) -- the generated `include` roots
+ * this workspace's tsconfigs name, each paired with the command that produces
+ * it, so the framework-specific knowledge sits in DATA and the invariant stays
+ * a question about scripts.
+ *
+ * Keyed by the root PACKAGE-RELATIVE (`.next/types`, not
+ * `apps/docs/.next/types`), so one row holds for every Next app the workspace
+ * ever gains rather than for the one that seeded it.
+ *
+ * Two row kinds, and the second is why this is a table rather than a hard-coded
+ * `next typegen` test:
+ *
+ *   generator: '<command>'   the `typecheck` script must run it, and must run
+ *                            it BEFORE tsc. Enforced.
+ *   generator: null          nothing a typecheck runs produces this, ON
+ *                            PURPOSE. `why` then has to carry the argument
+ *                            that its absence cannot make the check read
+ *                            green -- the one claim here nothing mechanical
+ *                            can check, which is exactly why it is written
+ *                            down where a reviewer reads it rather than
+ *                            inferred.
+ *
+ * NOT a debt ledger, and deliberately not closed the way DEBT and
+ * UNCHECKED_SOURCE_DEBT are: a `generator` row is durable knowledge about a
+ * correct config, not a hole waiting to be filled. It is still RECONCILED in
+ * the other direction -- a row no `include` names any more is dead knowledge
+ * and has to go.
+ *
+ * The generator claims below are read out of next@16.3.1, the version
+ * `apps/docs` resolves (`dist/cli/next-typegen.js`), not inferred from the
+ * command name.
+ */
+const GENERATED_INCLUDE_ROOTS = {
+  'next-env.d.ts': {
+    generator: 'next typegen',
+    why: 'Written by `writeAppTypeDeclarations`, which `next typegen` reaches through '
+      + '`verifyAndRunTypeScript` (`dist/cli/next-typegen.js` -> `dist/lib/verify-typescript-setup.js`) '
+      + 'before it generates a route type. Gitignored (`next-env.d.ts`, root .gitignore), so in a clean '
+      + 'checkout the entry names nothing until that command has run.',
+  },
+  '.next/types': {
+    generator: 'next typegen',
+    why: 'The route types themselves: `next typegen` writes `<distDir>/types/routes.d.ts`, '
+      + '`validator.ts`, `cache-life.d.ts` and `root-params.d.ts` into exactly this directory '
+      + '(`dist/cli/next-typegen.js`). This is the root #10880 was filed about -- a bare `tsc --noEmit` '
+      + 'read green over its absence and an ablation proved the missing files were load-bearing.',
+  },
+  '.next/dev/types': {
+    generator: null,
+    why: 'Written only by `next dev`, and a typecheck must NOT run a dev server to satisfy a glob. Its '
+      + "absence cannot make this check read green: it holds no route entry point of its own -- Next's "
+      + 'own build-mode type check FILTERS this directory out of the program (`getDevTypesPath`, '
+      + '`lib/typescript/runTypeCheck.js`) "to prevent stale dev types from causing errors when routes '
+      + 'have been deleted since the last dev session", so what it can produce locally is a false RED, '
+      + 'never a false green (remedy: `rm -rf apps/docs/.next`). The glob cannot be deleted either -- '
+      + '`writeConfigurationDefaults` re-adds it on the next `next dev` / `next build` (#10879). '
+      + 'Declared, and deliberately not generated.',
+  },
+};
+
 /**
  * The `packages:` globs from pnpm-workspace.yaml. Blank lines and comments are
  * skipped rather than treated as the end of the list: stopping early would
@@ -1078,6 +1181,23 @@ function workspaceGlobs() {
  *
  * @returns {{file: string, roots: string[], excludesTests: boolean}}
  */
+/**
+ * The fixed path prefix of an `include` glob -- everything before the first
+ * wildcard, with a trailing slash dropped (`src/**\/*` -> `src`,
+ * `.next/types/**\/*.ts` -> `.next/types`, `**\/*.ts` -> `''`, i.e. the whole
+ * package). A literal entry with no wildcard at all IS its own root
+ * (`next-env.d.ts`).
+ *
+ * Extracted rather than inlined twice because two invariants now read it and
+ * they must agree: TESTS_COVERED/SOURCES_COVERED decide what a program reads
+ * from these prefixes, and GENERATED_COVERED asks whether the same prefix is
+ * checked in. Two copies of this three-operation expression would be two
+ * chances to answer the same question differently (#10880).
+ */
+function includeRoot(glob) {
+  return glob.split('*')[0].replace(/\/$/, '');
+}
+
 function readTsconfig(dir, file) {
   const raw = readFileSync(join(ROOT, dir, file), 'utf8').replace(/^\s*\/\/.*$/gm, '');
   let parsed;
@@ -1087,13 +1207,20 @@ function readTsconfig(dir, file) {
     throw new Error(`${dir}/${file} is not parseable, so its test coverage cannot be judged`, { cause });
   }
   const include = parsed.include ?? null;
-  const roots = Array.isArray(include) && include.length > 0
-    ? [...new Set(include.map((g) => g.split('*')[0].replace(/\/$/, '')).filter((p) => !p.includes('..')))]
+  const declared = Array.isArray(include) ? include.filter((g) => typeof g === 'string') : [];
+  const roots = declared.length > 0
+    ? [...new Set(declared.map(includeRoot).filter((p) => !p.includes('..')))]
     : [''];
   const exclude = parsed.exclude ?? [];
   return {
     file,
     roots,
+    // The `include` array AS AUTHORED, which `roots` cannot stand in for: it is
+    // deduped and star-stripped, so it can no longer say WHICH glob promised a
+    // given root. GENERATED_COVERED quotes the entry back at the author
+    // (#10880), and a message naming `.next/types` where the file says
+    // `.next/types/**/*.ts` sends them looking for a line that is not there.
+    includes: declared,
     excludesTests: exclude.some((pattern) => TEST_GLOB.test(pattern)),
     // The NON-test exclusions, as path prefixes, for SOURCES_COVERED (#10756).
     // TESTS_COVERED never needed these -- an `exclude` that hides a test file
@@ -1117,26 +1244,157 @@ function configCovers(config, rel) {
 }
 
 /**
- * Which tsconfig files does the `typecheck` script actually put in front of
- * tsc? Expanded through same-package `pnpm <script>` / `npm run <script>`
- * indirection, because a package that splits the work across two scripts is
- * still running both. A bare `tsc` reads `tsconfig.json`, so any mention of tsc
- * credits the default config; every other config must be NAMED (`-p
- * tsconfig.test.json`), which is what keeps a decorative sibling config from
- * reading as coverage (#5286).
+ * The `typecheck` script, plus every same-package script it delegates to, as a
+ * list of the script bodies in visit order.
+ *
+ * A LIST rather than the joined blob it used to build, because the two readers
+ * want different things from it. `configsNamedByTypecheck` only ever asked
+ * "does this text mention X" and a blob answers that; GENERATED_COVERED also
+ * asks "does X run BEFORE tsc", and that is only decidable INSIDE one script
+ * body, where text order is shell order. Across bodies the concatenation order
+ * is visit order, which has nothing to do with execution order --
+ * `typecheck: 'pnpm gen && tsc'` + `gen: 'next typegen'` joins to `... tsc ...
+ * next typegen` while running the generator first, so a blob would red a
+ * correct config. Keeping the bodies apart is what lets that case ABSTAIN
+ * instead (#10880).
  */
-function configsNamedByTypecheck(scripts) {
+function typecheckScriptChain(scripts) {
   const visited = new Set();
-  let text = '';
+  const chain = [];
   const visit = (name, depth) => {
     if (depth > 4 || visited.has(name) || typeof scripts[name] !== 'string') return;
     visited.add(name);
-    text += ` ${scripts[name]}`;
+    chain.push(scripts[name]);
     for (const m of scripts[name].matchAll(/\b(?:pnpm(?:\s+run)?|npm\s+run|yarn(?:\s+run)?)\s+([\w:.-]+)/g)) {
       visit(m[1], depth + 1);
     }
   };
   visit('typecheck', 0);
+  return chain;
+}
+
+/**
+ * A declared generator command as a pattern that matches it in a script body:
+ * tokens in order, any run of whitespace between them, and a word boundary at
+ * each end that has one. `next typegen` must not be found inside
+ * `prenext typegen`, and `next    typegen` in a script is the same command.
+ *
+ * Built FROM the declared string rather than stored as a regex, so
+ * GENERATED_INCLUDE_ROOTS stays a table of commands a reader can copy into a
+ * shell (#10880).
+ */
+function commandPattern(command) {
+  const trimmed = command.trim();
+  const body = trimmed.split(/\s+/).map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('\\s+');
+  return new RegExp(`${/^\w/.test(trimmed) ? '\\b' : ''}${body}${/\w$/.test(trimmed) ? '\\b' : ''}`);
+}
+
+/**
+ * Does this `typecheck` chain run `command`, and run it before tsc?
+ *
+ *   'missing'  no body mentions it -- the generated directory is whatever an
+ *              earlier build left behind, and nothing at all in a clean
+ *              checkout.
+ *   'after'    a body runs it AFTER its own tsc, so the program tsc read was
+ *              still the pre-generator one. Reported ONLY from inside a single
+ *              body, where text order is shell order.
+ *   'ok'       runs it, and nothing proves it runs late.
+ *
+ * The abstention is deliberate and is the difference between a guard and a
+ * false red: a generator reached through `pnpm <script>` indirection has no
+ * knowable position relative to a tsc in a different body, so this answers
+ * 'ok' there rather than guessing. Under-reporting one ordering is the safe
+ * direction; the missing-command half, which is the measured defect, is not
+ * affected by it.
+ */
+function generatorVerdict(chain, command) {
+  const pattern = commandPattern(command);
+  let seen = false;
+  for (const body of chain) {
+    const m = pattern.exec(body);
+    if (!m) continue;
+    seen = true;
+    const tsc = body.search(/\btsc\b/);
+    if (tsc === -1) continue; // different body: order is not decidable, abstain
+    if (m.index < tsc) return 'ok'; // decided, in the one place order is real
+  }
+  if (!seen) return 'missing';
+  return chain.some((body) => {
+    const m = pattern.exec(body);
+    const tsc = body.search(/\btsc\b/);
+    return m !== null && tsc !== -1 && m.index > tsc;
+  })
+    ? 'after'
+    : 'ok';
+}
+
+/**
+ * Which of these repo-relative paths does git consider IGNORED -- i.e. which
+ * are not checked in, and therefore exist only because something produced them?
+ *
+ * One batched `check-ignore` for the whole workspace rather than one call per
+ * root: the structural pass is the sub-second half of this gate and 100-odd
+ * spawns would end that.
+ *
+ * Three properties this rests on, each chosen over an alternative:
+ *
+ *   * The ignore RULES are checked in, so the verdict is a property of the
+ *     tree rather than of the machine. `core.excludesFile` is emptied on the
+ *     command line for the same reason -- a developer's global ignore list
+ *     must not be able to change what CI's gate concludes. (`.git/info/exclude`
+ *     is per-clone and cannot be neutralised this way; a fresh CI checkout has
+ *     none.)
+ *   * The INDEX is consulted (no `--no-index`): a path that is tracked reads
+ *     as not-ignored even when a rule matches it, which is the right answer --
+ *     a force-added directory IS present in a clean checkout.
+ *   * Existence is never consulted, so the verdict does not depend on whether
+ *     anybody has run a build here. That is what makes this invariant mean the
+ *     same thing locally and in CI.
+ *
+ * A git that cannot answer is a THROW, never an empty set: reading a failed
+ * spawn as "nothing here is generated" would retire the invariant silently,
+ * which is the failure mode this whole file is about. Requiring git is already
+ * this repo's convention for a gate (check-nul-bytes, check-closing-keyword-parity).
+ *
+ * The self-test does NOT call this -- its fixtures state which entries are
+ * generated, so the battery stays hermetic and instant. What guards this
+ * function on the real tree is the RECONCILED half of GENERATED_COVERED: if
+ * this ever silently answered "nothing is generated", every row in
+ * GENERATED_INCLUDE_ROOTS would immediately be a row no `include` names, and
+ * the gate goes red naming all three. A broken detector cannot be a quiet one.
+ */
+function gitIgnoredPaths(rels) {
+  if (rels.length === 0) return new Set();
+  const res = spawnSync('git', ['-c', 'core.excludesFile=', 'check-ignore', '--stdin', '-z'], {
+    cwd: ROOT,
+    input: rels.map((r) => `${r}\0`).join(''),
+    encoding: 'utf8',
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (res.error) {
+    throw new Error(`git check-ignore could not run, so GENERATED_COVERED cannot be judged`, { cause: res.error });
+  }
+  // 0 = some path is ignored, 1 = none is. Anything else (128: not a git
+  // checkout, bad option) is a failed MEASUREMENT, not a clean tree.
+  if (res.status !== 0 && res.status !== 1) {
+    throw new Error(
+      `git check-ignore exited ${res.status}, so GENERATED_COVERED cannot be judged: ${String(res.stderr).trim()}`,
+    );
+  }
+  return new Set(res.stdout.split('\0').filter(Boolean));
+}
+
+/**
+ * Which tsconfig files does the `typecheck` script actually put in front of
+ * tsc? Expanded through same-package `pnpm <script>` / `npm run <script>`
+ * indirection, because a package that splits the work across two scripts is
+ * still running both. A bare `tsc` reads `tsconfig.json`, so any mention of tsc
+ * credits the default config; every other config must be NAMED (`-p
+ * tsconfig.test.json`), which is what keeps a decorative sibling config from
+ * reading as coverage (#5286).
+ */
+function configsNamedByTypecheck(scripts) {
+  const text = typecheckScriptChain(scripts).map((s) => ` ${s}`).join('');
   const named = new Set();
   for (const m of text.matchAll(/tsconfig[\w.-]*\.json/g)) named.add(m[0]);
   if (/\btsc\b/.test(text)) named.add('tsconfig.json');
@@ -1295,11 +1553,31 @@ function testCoverage(dir, scripts) {
     }
   }
 
+  // GENERATED_COVERED's candidates (#10880): every `include` entry of every
+  // config the `typecheck` script INVOKES, with the glob kept beside its root.
+  // Scoped exactly like SOURCES_COVERED above and for the same two reasons --
+  // a package with no `typecheck` script makes no coverage claim to falsify,
+  // and the question this invariant asks ("does the script run the generator")
+  // has no subject there. Which of these roots are actually generated is not
+  // decided here: that is one batched git call in `workspacePackages`, because
+  // it is a question about the repo rather than about this package.
+  const declaredIncludes = scripts.typecheck === undefined
+    ? []
+    : invoked.flatMap((config) =>
+      (config.includes ?? [])
+        .map((glob) => ({ config: config.file, glob, root: includeRoot(glob) }))
+        .filter((entry) => entry.root !== '' && !entry.root.includes('..')));
+
   return {
     hidesTests: hiddenTests.length > 0,
     testFiles: hiddenTests.length,
     hiddenTests,
     pinFiles: pinFiles.sort(),
+    declaredIncludes,
+    // The script bodies GENERATED_COVERED asks "does this run the generator,
+    // and before tsc" of. Carried on the package so `evaluate` stays a pure
+    // function of observations, the way every other invariant here is tested.
+    typecheckChain: typecheckScriptChain(scripts),
     // Repo-relative, one entry per top-level directory, with the file count
     // DERIVED on this run and never written down anywhere -- #5826's ruling for
     // the test layer applies here for the same reason.
@@ -1327,7 +1605,7 @@ function workspacePackages() {
       if (existsSync(join(ROOT, c, 'package.json'))) dirs.push(c);
     }
   }
-  return dirs.sort().map((dir) => {
+  const packages = dirs.sort().map((dir) => {
     const manifest = JSON.parse(readFileSync(join(ROOT, dir, 'package.json'), 'utf8'));
     return {
       name: manifest.name ?? dir,
@@ -1337,6 +1615,27 @@ function workspacePackages() {
       ...testCoverage(dir, manifest.scripts ?? {}),
     };
   });
+
+  // GENERATED_COVERED's observation half (#10880), in ONE git call for the
+  // whole workspace: of the `include` roots the typecheck scripts put in front
+  // of tsc, which are not checked in? Measured on main @ 7c02a4529c: 101 roots,
+  // of which 3 -- all in `apps/docs` -- are generated.
+  //
+  // The workspace ROOT package is not in this list and so is not asked. Its own
+  // `typecheck:root` config is judged by `evaluate`'s root branch, which has no
+  // observation of this kind; giving it one would mean walking the entire repo
+  // through `testCoverage`. No root-level `include` names a generated path
+  // today (same measurement), and this is the limit rather than an oversight.
+  const roots = new Set();
+  for (const pkg of packages) {
+    for (const entry of pkg.declaredIncludes ?? []) roots.add(posix.join(pkg.dir, entry.root));
+  }
+  const generated = gitIgnoredPaths([...roots].sort());
+  for (const pkg of packages) {
+    pkg.generatedIncludes = (pkg.declaredIncludes ?? [])
+      .filter((entry) => generated.has(posix.join(pkg.dir, entry.root)));
+  }
+  return packages;
 }
 
 // ---------------------------------------------------------------------------
@@ -1606,6 +1905,68 @@ function evaluate(packages, root, state) {
       }
     }
 
+    // GENERATED_COVERED (#10880). An `include` entry rooted in a path the repo
+    // does not check in: the program tsc gets is only as complete as whatever
+    // produced that path, and a missing one is SILENT -- the check exits 0
+    // having compiled none of it. Scoped by the observation half to packages
+    // that declare a `typecheck` script, exactly as SOURCES_COVERED is.
+    for (const { config, glob, root } of pkg.generatedIncludes ?? []) {
+      const where = `${pkg.name} (${pkg.dir}/${config})`;
+      if (!Object.hasOwn(state.generatedRoots, root)) {
+        problems.push(
+          `${where}: \`include\` names "${glob}", rooted in \`${root}\` -- a path the repo's own ignore ` +
+            `rules say is NOT checked in, so it is empty until something produces it -- and no row in ` +
+            `GENERATED_INCLUDE_ROOTS in ${SELF} says what does. tsc then reports green over a program ` +
+            `missing every file that glob promised, which is the one failure COVERED, REAL and RUNNABLE ` +
+            `all pass through (${GENERATED_INCLUDE_ISSUE}). Add a row naming the command the \`typecheck\` ` +
+            `script has to run first -- or, if nothing a typecheck runs should produce it, a row with ` +
+            `\`generator: null\` and the argument for why its absence cannot make this check read green. ` +
+            `⛔ Deleting the glob is not automatically the repair: a framework that writes the config ` +
+            `back (Next's \`writeConfigurationDefaults\`) will re-add it.`,
+        );
+        continue;
+      }
+      const row = state.generatedRoots[root] ?? {};
+      const declares = row.generator === null || (typeof row.generator === 'string' && row.generator.trim() !== '');
+      if (!declares) {
+        problems.push(
+          `GENERATED_INCLUDE_ROOTS["${root}"] in ${SELF} declares no generator -- give it the command ` +
+            `that produces the directory, or \`generator: null\` to say out loud that nothing a typecheck ` +
+            `runs produces it. A row with the key missing would read as the second answer while nobody ` +
+            `ever decided it.`,
+        );
+        continue;
+      }
+      if (!String(row.why ?? '').trim()) {
+        problems.push(
+          `GENERATED_INCLUDE_ROOTS["${root}"] in ${SELF} has no reason -- say what writes this path and ` +
+            `why the \`typecheck\` script's relationship to it is the right one. For a \`generator: null\` ` +
+            `row that reason is the whole guard: nothing mechanical can check that an ungenerated ` +
+            `directory's absence cannot make tsc read green.`,
+        );
+        continue;
+      }
+      if (row.generator === null) continue; // declared, and deliberately not generated
+      const verdict = generatorVerdict(pkg.typecheckChain ?? [], row.generator);
+      if (verdict === 'missing') {
+        problems.push(
+          `${where}: \`include\` names "${glob}", which nothing checked in provides -- ` +
+            `GENERATED_INCLUDE_ROOTS says \`${row.generator}\` writes it -- and this package's ` +
+            `\`typecheck\` script never runs that command ("${script ?? ''}"). So tsc compiles whatever an ` +
+            `earlier build happened to leave in \`${root}\`, and in a clean checkout it compiles nothing ` +
+            `from there and still exits 0 (${GENERATED_INCLUDE_ISSUE}). Put \`${row.generator}\` in the ` +
+            `\`typecheck\` script ahead of tsc.`,
+        );
+      } else if (verdict === 'after') {
+        problems.push(
+          `${where}: the \`typecheck\` script runs \`${row.generator}\` -- which is what writes "${glob}" -- ` +
+            `AFTER tsc in the same command ("${script ?? ''}"), so the program tsc read was still the one ` +
+            `from before the generator ran, and the files that glob promises were checked by nothing ` +
+            `(${GENERATED_INCLUDE_ISSUE}). Move it in front: \`${row.generator} && tsc --noEmit\`.`,
+        );
+      }
+    }
+
     if (script !== undefined) {
       // REAL: the script must put tsc in front of the package's sources.
       if (!/\btsc\b/.test(script)) {
@@ -1756,6 +2117,24 @@ function evaluate(packages, root, state) {
     }
   }
 
+  // RECONCILED for GENERATED_COVERED (#10880). This table is knowledge rather
+  // than debt -- a `generator` row describes a config that is RIGHT -- but
+  // knowledge about an `include` entry nobody has any more is just as stale as
+  // a debt entry for a repaired directory, and it is worse than inert: the next
+  // author reads it as evidence that the shape is still in use. A row survives
+  // exactly as long as some typecheck-invoked config names its root.
+  const generatedSeen = new Set(packages.flatMap((p) => (p.generatedIncludes ?? []).map((g) => g.root)));
+  for (const root of Object.keys(state.generatedRoots)) {
+    if (!generatedSeen.has(root)) {
+      problems.push(
+        `GENERATED_INCLUDE_ROOTS entry for "${root}" is named by no \`include\` that any package's ` +
+          `\`typecheck\` script invokes (the glob is gone, the path is checked in now, or the package ` +
+          `stopped declaring \`typecheck\`) -- delete it from ${SELF}. That is the ratchet: this table ` +
+          `only ever describes live configs.`,
+      );
+    }
+  }
+
   // COMPOSITION (#10722). Runs over the ledger objects rather than over live
   // packages: a note contradicting its own field is wrong whether or not the
   // package it names still exists, and the reconciliation above already fails
@@ -1833,6 +2212,31 @@ function uncheckedSourceLayer(packages, ledger) {
   return { dirs, files };
 }
 
+/**
+ * The generated layer's headline figures (#10880), derived on every run like
+ * the two layers above it -- this gate has already asked git which roots are
+ * generated and already read the table, so writing any of it down would be a
+ * second source of truth for a fact it holds.
+ *
+ * Only printed after the verdict is clean, so every entry counted here has a
+ * row: `produced` and `ungenerated` therefore sum to `entries`.
+ *
+ * @returns {{entries: number, packages: number, produced: number, ungenerated: number}}
+ */
+function generatedIncludeLayer(packages, table) {
+  let entries = 0;
+  let withEntries = 0;
+  let produced = 0;
+  for (const pkg of packages) {
+    const found = pkg.generatedIncludes ?? [];
+    if (found.length === 0) continue;
+    withEntries++;
+    entries += found.length;
+    produced += found.filter((g) => typeof table[g.root]?.generator === 'string').length;
+  }
+  return { entries, packages: withEntries, produced, ungenerated: entries - produced };
+}
+
 // ---------------------------------------------------------------------------
 // MEASURED -- the re-measure half (#5278).
 //
@@ -2864,6 +3268,7 @@ function observed() {
       testDebt: TEST_DEBT,
       phantomPins: PHANTOM_PIN_DEBT,
       uncheckedSources: UNCHECKED_SOURCE_DEBT,
+      generatedRoots: GENERATED_INCLUDE_ROOTS,
       turboHasTask: Object.hasOwn(turbo.tasks ?? {}, 'typecheck'),
       ciInvokesTask: /turbo run typecheck/.test(lintYml),
       ciInvokesRoot: /typecheck:root/.test(lintYml),
@@ -2883,7 +3288,15 @@ function selfTest() {
     name: 'root',
     scripts: { typecheck: 'turbo run typecheck', 'typecheck:root': 'tsc --noEmit' },
   };
-  const okState = { debt: {}, exempt: {}, testDebt: {}, phantomPins: {}, uncheckedSources: {}, turboHasTask: true, ciInvokesTask: true, ciInvokesRoot: true };
+  const okState = { debt: {}, exempt: {}, testDebt: {}, phantomPins: {}, uncheckedSources: {}, generatedRoots: {}, turboHasTask: true, ciInvokesTask: true, ciInvokesRoot: true };
+  // GENERATED_COVERED's fixtures (#10880). A LITERAL fixture, never the real
+  // workspace: `apps/docs` is correct today (#10879 put `next typegen` in its
+  // script), so a self-test that leaned on the real tree would assert only that
+  // a repaired package stays repaired -- and would go quiet the day somebody
+  // deletes the app. The negative controls below are what make this invariant
+  // able to fail at all.
+  const nextTypes = { config: 'tsconfig.json', glob: '.next/types/**/*.ts', root: '.next/types' };
+  const typegenRow = { '.next/types': { generator: 'next typegen', why: 'route types' } };
   const cases = [
     {
       label: 'covered package passes',
@@ -2975,6 +3388,136 @@ function selfTest() {
       state: { ...okState, debt: { a: { errors: 4 } } },
       expect: [],
     },
+    {
+      // The measured defect, as it stood before #10879: the script invokes tsc
+      // (REAL passes), every file that exists is in a program (TESTS_COVERED
+      // and SOURCES_COVERED pass), and the program is missing an entire
+      // generated directory the config promised.
+      label: 'a generated `include` root with no declared row fails GENERATED_COVERED',
+      packages: [
+        pkg('a', {
+          scripts: { typecheck: 'tsc --noEmit' },
+          typecheckChain: ['tsc --noEmit'],
+          generatedIncludes: [nextTypes],
+        }),
+      ],
+      root: okRoot,
+      state: okState,
+      expect: [/`include` names "\.next\/types\/\*\*\/\*\.ts".*no row in\s+GENERATED_INCLUDE_ROOTS/s],
+    },
+    {
+      label: 'a declared generator the typecheck script runs before tsc passes',
+      packages: [
+        pkg('a', {
+          scripts: { typecheck: 'next typegen && tsc --noEmit' },
+          typecheckChain: ['next typegen && tsc --noEmit'],
+          generatedIncludes: [nextTypes],
+        }),
+      ],
+      root: okRoot,
+      state: { ...okState, generatedRoots: typegenRow },
+      expect: [],
+    },
+    {
+      // The negative control for the row above: same table, same include, and
+      // the one thing that differs is the command the script runs.
+      label: 'a declared generator the script never runs fails',
+      packages: [
+        pkg('a', {
+          scripts: { typecheck: 'tsc --noEmit' },
+          typecheckChain: ['tsc --noEmit'],
+          generatedIncludes: [nextTypes],
+        }),
+      ],
+      root: okRoot,
+      state: { ...okState, generatedRoots: typegenRow },
+      expect: [/never runs that command/],
+    },
+    {
+      // Order is the half a blob of script text could not answer. Same command,
+      // same config, and the program tsc reads is still the pre-generator one.
+      label: 'a generator that runs AFTER tsc in the same command fails',
+      packages: [
+        pkg('a', {
+          scripts: { typecheck: 'tsc --noEmit && next typegen' },
+          typecheckChain: ['tsc --noEmit && next typegen'],
+          generatedIncludes: [nextTypes],
+        }),
+      ],
+      root: okRoot,
+      state: { ...okState, generatedRoots: typegenRow },
+      expect: [/AFTER tsc in the same command/],
+    },
+    {
+      // `.next/dev/types`: the state the card said had to be sayable. Deleting
+      // the glob is not the repair -- Next writes it back -- so "declared, and
+      // deliberately not generated" has to pass.
+      label: 'a row declaring the root deliberately ungenerated passes',
+      packages: [
+        pkg('a', {
+          scripts: { typecheck: 'next typegen && tsc --noEmit' },
+          typecheckChain: ['next typegen && tsc --noEmit'],
+          generatedIncludes: [{ config: 'tsconfig.json', glob: '.next/dev/types/**/*.ts', root: '.next/dev/types' }],
+        }),
+      ],
+      root: okRoot,
+      state: {
+        ...okState,
+        generatedRoots: { '.next/dev/types': { generator: null, why: 'written only by `next dev`; absence is a false red at worst' } },
+      },
+      expect: [],
+    },
+    {
+      label: 'an ungenerated row without a reason fails -- the reason IS the guard there',
+      packages: [
+        pkg('a', {
+          scripts: { typecheck: 'tsc --noEmit' },
+          typecheckChain: ['tsc --noEmit'],
+          generatedIncludes: [nextTypes],
+        }),
+      ],
+      root: okRoot,
+      state: { ...okState, generatedRoots: { '.next/types': { generator: null, why: '  ' } } },
+      expect: [/GENERATED_INCLUDE_ROOTS\["\.next\/types"\] in .*has no reason/],
+    },
+    {
+      // A row that simply omits the key must not read as `generator: null`:
+      // that would let the strict half be switched off by a typo.
+      label: 'a row that declares no generator at all fails rather than defaulting to ungenerated',
+      packages: [
+        pkg('a', {
+          scripts: { typecheck: 'tsc --noEmit' },
+          typecheckChain: ['tsc --noEmit'],
+          generatedIncludes: [nextTypes],
+        }),
+      ],
+      root: okRoot,
+      state: { ...okState, generatedRoots: { '.next/types': { why: 'route types' } } },
+      expect: [/declares no generator/],
+    },
+    {
+      label: 'a GENERATED_INCLUDE_ROOTS row no `include` names any more fails RECONCILED',
+      packages: [pkg('a', { scripts: { typecheck: 'tsc --noEmit' }, generatedIncludes: [] })],
+      root: okRoot,
+      state: { ...okState, generatedRoots: typegenRow },
+      expect: [/GENERATED_INCLUDE_ROOTS entry for "\.next\/types" is named by no `include`/],
+    },
+    {
+      // The quiet half. 100 of the workspace's 101 include roots are ordinary
+      // checked-in source and this invariant must have nothing to say about
+      // them, or it becomes the thing nobody can keep green.
+      label: 'include roots that are checked-in source are not this invariant\'s business',
+      packages: [
+        pkg('a', {
+          scripts: { typecheck: 'tsc --noEmit' },
+          typecheckChain: ['tsc --noEmit'],
+          generatedIncludes: [],
+        }),
+      ],
+      root: okRoot,
+      state: okState,
+      expect: [],
+    },
     {
       label: 'a pin in a file no tsc program compiles fails PINS_CHECKED',
       packages: [
@@ -3390,6 +3933,87 @@ function selfTest() {
     }
   }
 
+  // GENERATED_COVERED's three observation helpers (#10880). Between them they
+  // decide WHICH include entry is asked about and whether the script answers
+  // it, so each is pinned where a wrong answer would be silent.
+  const includeRootCases = [
+    { label: 'a directory glob roots at the directory', glob: '.next/types/**/*.ts', expect: '.next/types' },
+    { label: 'the ordinary source glob', glob: 'src/**/*', expect: 'src' },
+    { label: 'a whole-package glob has the empty root', glob: '**/*.ts', expect: '' },
+    { label: 'a literal file IS its own root', glob: 'next-env.d.ts', expect: 'next-env.d.ts' },
+    { label: 'a trailing slash is not part of the root', glob: 'src/', expect: 'src' },
+    { label: 'a single star roots the same way a double one does', glob: '.next/types/*.ts', expect: '.next/types' },
+  ];
+  for (const c of includeRootCases) {
+    const got = includeRoot(c.glob);
+    if (got !== c.expect) failures.push(`includeRoot — ${c.label}: expected ${JSON.stringify(c.expect)}, got ${JSON.stringify(got)}`);
+  }
+
+  const chainCases = [
+    { label: 'the typecheck body is the chain', scripts: { typecheck: 'next typegen && tsc --noEmit' }, expect: ['next typegen && tsc --noEmit'] },
+    {
+      label: 'delegated bodies are kept SEPARATE, which is what makes order decidable',
+      scripts: { typecheck: 'pnpm gen && tsc --noEmit', gen: 'next typegen' },
+      expect: ['pnpm gen && tsc --noEmit', 'next typegen'],
+    },
+    { label: 'no typecheck script is an empty chain', scripts: { build: 'tsup' }, expect: [] },
+  ];
+  for (const c of chainCases) {
+    const got = typecheckScriptChain(c.scripts);
+    if (JSON.stringify(got) !== JSON.stringify(c.expect)) {
+      failures.push(`typecheckScriptChain — ${c.label}: expected ${JSON.stringify(c.expect)}, got ${JSON.stringify(got)}`);
+    }
+  }
+
+  const generatorCases = [
+    { label: 'generator before tsc in one body', chain: ['next typegen && tsc --noEmit'], expect: 'ok' },
+    { label: 'the measured defect: tsc alone', chain: ['tsc --noEmit'], expect: 'missing' },
+    { label: 'generator after tsc in one body', chain: ['tsc --noEmit && next typegen'], expect: 'after' },
+    { label: 'the real apps/docs shape, with a third command in front', chain: ['fumadocs-mdx && next typegen && tsc --noEmit'], expect: 'ok' },
+    {
+      // The abstention. Text order across bodies is VISIT order, not shell
+      // order -- `pnpm gen && tsc` runs the generator first while the chain
+      // lists it second, so an order verdict here would be a false red on a
+      // correct config.
+      label: 'a generator reached through indirection is present, and its order is not guessed at',
+      chain: ['pnpm gen && tsc --noEmit', 'next typegen'],
+      expect: 'ok',
+    },
+    { label: 'extra whitespace is the same command', chain: ['next   typegen && tsc'], expect: 'ok' },
+    { label: 'a command that merely CONTAINS the name is not it', chain: ['prenext typegen && tsc'], expect: 'missing' },
+    { label: 'a body that runs the generator and no tsc at all still counts as running it', chain: ['next typegen'], expect: 'ok' },
+    { label: 'nothing at all', chain: [], expect: 'missing' },
+  ];
+  for (const c of generatorCases) {
+    const got = generatorVerdict(c.chain, 'next typegen');
+    if (got !== c.expect) failures.push(`generatorVerdict — ${c.label}: expected ${c.expect}, got ${got}`);
+  }
+
+  // The generated layer's summary arithmetic. `produced` + `ungenerated` must
+  // equal `entries` or the line printed on a green run is telling the reader
+  // about a state the verdict already forbade.
+  const layerCases = [
+    {
+      label: 'one produced and one ungenerated entry in one package',
+      packages: [pkg('a', { generatedIncludes: [{ root: '.next/types' }, { root: '.next/dev/types' }] })],
+      table: { '.next/types': { generator: 'next typegen' }, '.next/dev/types': { generator: null } },
+      expect: { entries: 2, packages: 1, produced: 1, ungenerated: 1 },
+    },
+    {
+      label: 'packages with no generated include are not counted as packages',
+      packages: [pkg('a', { generatedIncludes: [] }), pkg('b', { generatedIncludes: [{ root: '.next/types' }] })],
+      table: { '.next/types': { generator: 'next typegen' } },
+      expect: { entries: 1, packages: 1, produced: 1, ungenerated: 0 },
+    },
+    { label: 'a workspace with none', packages: [pkg('a')], table: {}, expect: { entries: 0, packages: 0, produced: 0, ungenerated: 0 } },
+  ];
+  for (const c of layerCases) {
+    const got = generatedIncludeLayer(c.packages, c.table);
+    if (JSON.stringify(got) !== JSON.stringify(c.expect)) {
+      failures.push(`generatedIncludeLayer — ${c.label}: expected ${JSON.stringify(c.expect)}, got ${JSON.stringify(got)}`);
+    }
+  }
+
   // The summary's hidden-file figure (#5826). It used to be the sum of a
   // hand-written `tests` field, which nothing reconciled -- so the third case
   // below is the whole issue in one line: the same ledger, one more test file,
@@ -4179,7 +4803,8 @@ function selfTest() {
   console.log(
     `✓ check:type-check-coverage --self-test — ${cases.length} semantic case(s) + ` +
       `${namedCases.length + coverCases.length + unreadCases.length + accountedCases.length
-        + derivedCases.length + sourceCandidateCases.length} observation case(s) + ` +
+        + derivedCases.length + sourceCandidateCases.length + includeRootCases.length
+        + chainCases.length + generatorCases.length + layerCases.length} observation case(s) + ` +
       `${driftCases.length + countCases.length + projectCases.length + setupErrorCases.length} re-measure case(s) + ` +
       `${typeEntryCases.length + closureCases.length + staleCases.length + sourceFileCases.length} ` +
       `built-closure case(s) + ` +
@@ -4209,6 +4834,7 @@ const testDebtErrors = Object.values(TEST_DEBT).reduce((sum, e) => sum + (e.erro
 // number here the gate already knows (#5826).
 const testDebtFiles = hiddenTestFiles(packages, TEST_DEBT);
 const sourceLayer = uncheckedSourceLayer(packages, UNCHECKED_SOURCE_DEBT);
+const generatedLayer = generatedIncludeLayer(packages, GENERATED_INCLUDE_ROOTS);
 const declaredStale = [...Object.entries(DEBT), ...Object.entries(TEST_DEBT)]
   .filter(([, entry]) => typeof entry?.compositionAt === 'number');
 // Both numbers, always. Reporting only the src figure is how the first pass of
@@ -4226,6 +4852,15 @@ console.log(
     `\n  source layer: ${sourceLayer.dirs} directory(ies) of non-test source in ` +
     `${Object.keys(UNCHECKED_SOURCE_DEBT).length} ledgered entr(y/ies) sit outside every tsc program ` +
     `their package's own \`typecheck\` runs (${sourceLayer.files} files as counted by this run).` +
+    // The FOURTH layer (#10880), printed for the reason the other two are: an
+    // `include` entry pointing at a directory nothing produces is invisible in
+    // every count above, because those are all questions about files that
+    // exist. Both halves are reported -- an ungenerated row is a standing
+    // decision, and a decision nobody can see is the half that rots.
+    `\n  generated layer: ${generatedLayer.entries} \`include\` entr(ies) across ` +
+    `${generatedLayer.packages} package(s) name a path this repo does not check in -- ` +
+    `${generatedLayer.produced} produced by their own \`typecheck\` before tsc, ` +
+    `${generatedLayer.ungenerated} declared deliberately ungenerated in GENERATED_INCLUDE_ROOTS.` +
     // Printed on a GREEN run, for the same reason the surplus is (#6376): a
     // declared-stale composition is honest but it is still drift, and a
     // declaration nobody can see is the half that does the damage. Zero is the