@shrkcrft/inspector 0.1.0-alpha.29 → 0.1.0-alpha.31

package/dist/registry-lifecycle.js

@@ -8,15 +8,28 @@
  * Ignored: generated files (.generated.*, .d.ts), files containing
  * `@shrkcrft lifecycle-ignore <reason>`. Sites with `@shrkcrft lifecycle-managed-by <name>`
  * are reported under `ignored` with the managed-by reference.
+ *
+ * Bounded, and honest about the bound (round 11):
+ *   - candidates are SORTED by project-relative path, so `offset` / `limit`
+ *     page through them deterministically and `nextOffset` always reaches the
+ *     remainder a cap, the budget or a signal left unexamined;
+ *   - the wall-clock budget is checked between files AND inside each file
+ *     (after the strip, after the declaration scan, before every register), so
+ *     one pathological file cannot run past it unbounded. A file over its own
+ *     sub-budget is abandoned whole and NAMED in `overBudgetFiles`;
+ *   - every per-file step is linear — no two newline-spanning quantifiers
+ *     touch in any pattern that runs on the blanked buffer, and the remover
+ *     lookup is one pass per file instead of one regex per candidate name;
+ *   - the report carries engine-owned coverage (`files`, `registrations`), and
+ *     {@link registryLifecycleVerdict} reads nothing else.
  */
-import { readdirSync, readFileSync } from 'node:fs';
-import { extname, join, relative } from 'node:path';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { extname, join, relative, sep } from 'node:path';
+import { coverageShortfall } from '@shrkcrft/core';
 /**
  * Default directories the walk skips — build artefacts + non-source trees that
- * inflate the scan without owning runtime lifecycle. This is the DEFAULT only;
- * a repo that genuinely registers code under `tools/`, a non-standard root, etc.
- * can override the set via config (`registryLifecycle.skipDirs`) / the engine's
- * `skipDirs` input, so a hardcoded exclusion never silently blinds the check.
+ * inflate the scan without owning runtime lifecycle. Extend it with
+ * `registryLifecycle.skipDirsAdd`; replace it with `registryLifecycle.skipDirs`.
  */
 export const DEFAULT_REGISTRY_LIFECYCLE_SKIP_DIRS = Object.freeze([
     'node_modules',
@@ -36,52 +49,102 @@ export const DEFAULT_REGISTRY_LIFECYCLE_SKIP_DIRS = Object.freeze([
     '.agents',
     '.github',
 ]);
+/**
+ * The dependency / VCS-adjacent / build-output defaults. A replacing
+ * `skipDirs` list that omits one of these makes the scan read vendored or
+ * generated code — four false positives from one added exclusion, measured —
+ * so dropping one is always reported. (`.git` & co. stay skipped by the
+ * dot-entry rule regardless.)
+ */
+export const CORE_REGISTRY_LIFECYCLE_SKIP_DIRS = Object.freeze([
+    'node_modules',
+    'dist',
+    'build',
+    'out',
+    'coverage',
+    '.sharkcraft',
+]);
 const SCAN_EXTENSIONS = new Set(['.ts', '.tsx']);
-/** Skip pathological single files — a 200 KB command file has no registry to pair. */
+/**
+ * Skip pathological single files — named in `excludedFiles.oversized` AND
+ * counted UNEXAMINED in the files coverage: a cap is never a deliberate
+ * narrowing (round 11 review: subtracting them from `expected` let a missing
+ * remover inside a 361 KB file settle to a clean ✓). The boundaries reader's
+ * rule (`readScopeCoverage`: over-cap = unread = a shortfall) — one rule.
+ */
 const MAX_SCAN_FILE_BYTES = 256 * 1024;
-/** Hard wall-clock budget so the scan fails loud (partial flush) instead of hanging. */
+/** How the files coverage names the size cap. */
+const LIFECYCLE_READ_CAP = `${MAX_SCAN_FILE_BYTES / 1024} KB`;
+/** Wall-clock budget for a whole run. */
 const DEFAULT_BUDGET_MS = 15_000;
-function isGeneratedFile(file, content) {
-    if (file.endsWith('.d.ts'))
-        return true;
-    if (/\.generated\.(ts|tsx)$/.test(file))
-        return true;
-    if (/^\/\/ @generated\b/m.test(content))
-        return true;
-    return false;
+/** Default file cap. */
+const DEFAULT_LIMIT = 2000;
+/** Labels named in a coverage record's `unexamined`. */
+const UNEXAMINED_SHOWN = 20;
+/**
+ * THE skip-dir authority: the engine, the CLI and `shrk doctor` all call this.
+ * `skipDirsAdd` extends; `skipDirs` replaces; a replacement that drops a core
+ * default is reported in `droppedDefaults`.
+ */
+export function resolveRegistryLifecycleSkipDirs(input) {
+    const base = input.skipDirs ?? DEFAULT_REGISTRY_LIFECYCLE_SKIP_DIRS;
+    const effective = [...new Set([...base, ...(input.skipDirsAdd ?? [])])].sort();
+    const kept = new Set(effective);
+    const droppedDefaults = CORE_REGISTRY_LIFECYCLE_SKIP_DIRS.filter((d) => !kept.has(d));
+    return { effective, droppedDefaults };
+}
+/** The warning a replacing skip list that drops core defaults earns. One wording, scan and doctor. */
+export function registryLifecycleSkipDirsWarning(droppedDefaults) {
+    return (`registryLifecycle.skipDirs replaces the defaults and drops: ${droppedDefaults.join(', ')} — ` +
+        'use skipDirsAdd to extend the default skip set instead');
 }
-function walk(dir, projectRoot, out, skipDirs, deadline) {
-    // The wall-clock budget must bound the TREE WALK too, not only the per-file
-    // scan loop — a pathological tree could otherwise eat the whole budget before
-    // the loop's deadline check ever runs (a25 §2.5). Bail the walk on expiry;
-    // partial candidates flow through and the caller flags timedOut.
-    if (deadline !== undefined && Date.now() > deadline)
-        return;
+function isGeneratedPath(file) {
+    return file.endsWith('.d.ts') || /\.generated\.(ts|tsx)$/.test(file);
+}
+function isGeneratedContent(content) {
+    return /^\/\/ @generated\b/m.test(content);
+}
+function toPosix(p) {
+    return sep === '/' ? p : p.split(sep).join('/');
+}
+function comparePaths(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function isMissing(e) {
+    return e?.code === 'ENOENT';
+}
+/** Walk for candidates. Returns `false` when the budget expired before the walk finished. */
+function walkCandidates(dir, out, skipDirs, expired) {
+    // The budget bounds DISCOVERY too, not only the per-file loop — a
+    // pathological tree could otherwise eat the whole budget first (a25 §2.5).
+    if (expired())
+        return false;
     let entries;
     try {
         entries = readdirSync(dir, { withFileTypes: true });
     }
     catch {
-        return;
+        return true;
     }
     for (const e of entries) {
-        if (deadline !== undefined && Date.now() > deadline)
-            return;
+        if (expired())
+            return false;
         if (skipDirs.has(e.name))
             continue;
-        if (e.name.startsWith('.') && e.name !== '.sharkcraft') {
-            // skip hidden dotfiles
-            if (e.name !== '.')
-                continue;
-        }
+        // Hidden entries stay out, except `.sharkcraft` (skipped by default, but a
+        // replacing skip list makes it scannable — and is warned about).
+        if (e.name.startsWith('.') && e.name !== '.sharkcraft')
+            continue;
         const abs = join(dir, e.name);
         if (e.isDirectory()) {
-            walk(abs, projectRoot, out, skipDirs, deadline);
+            if (!walkCandidates(abs, out, skipDirs, expired))
+                return false;
         }
         else if (e.isFile() && SCAN_EXTENSIONS.has(extname(e.name))) {
             out.push(abs);
         }
     }
+    return true;
 }
 const REGISTER_PATTERNS = Object.freeze([
     // export function registerX(
@@ -108,6 +171,29 @@ const ACCUMULATION_RE = /\.(?:set|add|push)\s*\(|\[[^\]]+\]\s*=[^=]/;
 // A teardown-shaped API somewhere in the file — evidence the file is in the
 // business of removing things, so a missing per-register remover is suspicious.
 const TEARDOWN_RE = /\b(?:remove|unregister|clear|dispose|unsubscribe)\w*\s*\(|\boff\s*\(/i;
+/**
+ * Every callable site `name(` / `name = (` in the blanked code, in ONE pass.
+ *
+ * Replaces a whole-file regex compiled once PER CANDIDATE NAME whose third
+ * alternative, `(?:public|private|protected)?\s*(?:async\s+)?NAME\s*\(`, could
+ * start at every offset of a blank run and cost O(run) there: O(run²) per
+ * blanked comment, times six candidate names, times every register — 16 s for
+ * one 51 KB file. Anchored on `\b` + an identifier, no whitespace quantifier
+ * can start a match, so this is linear. It also reports the NAME's offset, so
+ * `removerLine` is the method's own line (the old match began at the blank run).
+ */
+const CALLABLE_SITE_RE = /\b([A-Za-z_$][\w$]*)\s*(?:=\s*)?\(/g;
+/**
+ * Every pattern this module runs on a blanked buffer, for the linearity lock
+ * (`r75-registry-lifecycle-scan.test.ts`): each must stay fast on a 64 KiB
+ * blank run and clean under `findBlankRunHazards`.
+ */
+export const REGISTRY_LIFECYCLE_PATTERNS = Object.freeze({
+    register: REGISTER_PATTERNS,
+    accumulation: ACCUMULATION_RE,
+    teardown: TEARDOWN_RE,
+    callableSite: CALLABLE_SITE_RE,
+});
 /**
  * Blank out comments and string / template-literal bodies (preserving newlines
  * so line numbers stay accurate) before scanning for `register*` declarations.
@@ -240,14 +326,29 @@ function findRegistersInFile(content, lineStarts) {
         re.lastIndex = 0;
         while ((m = re.exec(content)) !== null) {
             const name = m[1];
-            if (seen.has(`${name}@${m.index}`))
+            // The NAME's offset, not the match start: the method pattern begins at
+            // the preceding `\n`, which used to report the line ABOVE the declaration.
+            const at = m.index + m[0].indexOf(name);
+            if (seen.has(`${name}@${at}`))
                 continue;
-            seen.add(`${name}@${m.index}`);
-            out.push({ name, line: lineAtOffset(lineStarts, m.index) });
+            seen.add(`${name}@${at}`);
+            out.push({ name, line: lineAtOffset(lineStarts, at) });
         }
     }
     return out;
 }
+/** First offset of every callable name in the file — built once, looked up per register. */
+function indexCallableSites(code) {
+    const first = new Map();
+    CALLABLE_SITE_RE.lastIndex = 0;
+    let m;
+    while ((m = CALLABLE_SITE_RE.exec(code)) !== null) {
+        const name = m[1];
+        if (!first.has(name))
+            first.set(name, m.index);
+    }
+    return first;
+}
 function findIgnoreAnnotations(content, registerName) {
     const ignoreRe = new RegExp(`@shrkcrft\\s+lifecycle-ignore(?:\\s+([^\\n]+))?[\\s\\S]{0,200}?\\b${registerName}\\b`, 'm');
     const managedRe = new RegExp(`@shrkcrft\\s+lifecycle-managed-by\\s+([\\w.-]+)[\\s\\S]{0,200}?\\b${registerName}\\b`, 'm');
@@ -274,88 +375,142 @@ function expectedRemoverNames(registerName) {
         `${stem}Off`,
     ];
 }
-function findRemoverInContent(content, candidates, lineStarts) {
-    for (const name of candidates) {
-        const re = new RegExp(`(?:export\\s+)?(?:async\\s+)?function\\s+${name}\\s*\\(|\\b${name}\\s*=\\s*\\(|(?:public|private|protected)?\\s*(?:async\\s+)?${name}\\s*\\(`);
-        const m = content.match(re);
-        if (m && typeof m.index === 'number') {
-            return { name, line: lineAtOffset(lineStarts, m.index) };
-        }
-    }
-    return null;
-}
-export function buildRegistryLifecycleReport(input) {
+/**
+ * Create a scan: discover and sort the candidates, then judge them one
+ * {@link IRegistryLifecycleScan.step} at a time. The sync report builder and
+ * the signal-aware async runner both drive this — one loop, not two.
+ */
+export function createRegistryLifecycleScan(input) {
     const { projectRoot } = input;
+    const clock = input.now ?? (() => Date.now());
     const scope = input.scope && input.scope.length > 0 ? input.scope : undefined;
     const changedOnly = input.files !== undefined;
-    const deadline = Date.now() + (input.budgetMs ?? DEFAULT_BUDGET_MS);
-    const limit = input.limit ?? 2000;
-    const skipDirs = new Set(input.skipDirs ?? DEFAULT_REGISTRY_LIFECYCLE_SKIP_DIRS);
-    // Candidate files: either the explicit changed set (bypassing the walk) or a
-    // bounded tree walk. The changed set resolves relative paths under the root
-    // and keeps only scannable extensions.
+    const budgetMs = input.budgetMs ?? DEFAULT_BUDGET_MS;
+    const perFileBudgetMs = input.perFileBudgetMs ?? Math.max(1000, Math.floor(budgetMs / 4));
+    const rawLimit = input.limit ?? DEFAULT_LIMIT;
+    const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.floor(rawLimit) : 0;
+    const requestedOffset = Math.max(0, Math.floor(input.offset ?? 0));
+    const skip = resolveRegistryLifecycleSkipDirs({
+        ...(input.skipDirs ? { skipDirs: input.skipDirs } : {}),
+        ...(input.skipDirsAdd ? { skipDirsAdd: input.skipDirsAdd } : {}),
+    });
+    const warnings = [];
+    if (input.skipDirs !== undefined && skip.droppedDefaults.length > 0) {
+        warnings.push(registryLifecycleSkipDirsWarning(skip.droppedDefaults));
+    }
+    // An existing config that failed to load: the configured skip set was never
+    // applied, so this walk is NOT the scope the project asked for. Loud (a
+    // warning line) AND settled (a coverage record the verdict reads).
+    const loadError = input.configLoadError;
+    const configCoverage = loadError
+        ? {
+            unit: 'config files',
+            expected: 1,
+            examined: 0,
+            ...(loadError.file ? { unexamined: [loadError.file], unexaminedTotal: 1 } : {}),
+            reason: 'failed to load, so registryLifecycle.skipDirs / skipDirsAdd were not applied (the scan used the default skip set)',
+        }
+        : undefined;
+    if (loadError) {
+        warnings.push('sharkcraft.config.ts failed to load — registryLifecycle.skipDirs / skipDirsAdd not applied, so this scan ' +
+            `used the default skip set (${loadError.message}). Run \`shrk doctor\`.`);
+    }
+    const deadline = clock('start') + budgetMs;
+    const walkRoot = changedOnly ? projectRoot : scope ? join(projectRoot, scope) : projectRoot;
+    const rel = (abs) => toPosix(relative(projectRoot, abs));
+    // Candidates, SORTED by project-relative path: without a stable order a
+    // continuation cannot be derived (readdir order is not one).
     let files;
+    let walkComplete = true;
     if (input.files !== undefined) {
-        files = input.files
+        const abs = input.files
             .map((f) => (f.startsWith('/') ? f : join(projectRoot, f)))
             .filter((f) => SCAN_EXTENSIONS.has(extname(f)));
+        files = [...new Set(abs)];
     }
     else {
-        const walkRoot = scope ? join(projectRoot, scope) : projectRoot;
         files = [];
-        walk(walkRoot, projectRoot, files, skipDirs, deadline);
+        walkComplete = walkCandidates(walkRoot, files, new Set(skip.effective), () => clock('walk') >= deadline);
     }
-    const scanFiles = files.slice(0, limit);
+    const relOf = new Map(files.map((f) => [f, rel(f)]));
+    files.sort((a, b) => comparePaths(relOf.get(a), relOf.get(b)));
+    const start = Math.min(requestedOffset, files.length);
+    const end = limit > 0 ? Math.min(files.length, start + limit) : files.length;
+    let cursor = start;
+    let finished = false;
+    let timedOut = !walkComplete;
+    let filesScanned = 0;
+    let registersFound = 0;
+    let generated = 0;
+    let missingCount = 0;
+    const oversized = [];
+    const unreadable = [];
+    const overBudget = [];
     const matchedPairs = [];
     const missingRemovers = [];
     const oneShotBootstrap = [];
     const ignored = [];
-    let registersFound = 0;
-    // The tree walk itself is now deadline-bounded (a25 §2.5), so an exhausted
-    // budget can leave `scanFiles` empty and the per-file loop below would never
-    // run to set the flag. Seed it from the deadline so a walk-level timeout is
-    // reported (NOT-verified `2`) rather than read as a clean zero-registration pass.
-    let timedOut = Date.now() > deadline;
-    let filesScanned = 0;
-    for (const file of scanFiles) {
-        // Hard wall-clock budget checked between files — the scan is synchronous, so
-        // a Date.now() deadline is the only interruption point. Flush partial results.
-        if (Date.now() > deadline) {
-            timedOut = true;
-            break;
+    function judgeFile(abs, file, fileStart) {
+        if (isGeneratedPath(abs))
+            return { kind: 'generated' };
+        let size;
+        try {
+            size = statSync(abs).size;
+        }
+        catch (e) {
+            return { kind: isMissing(e) ? 'missing' : 'unreadable' };
         }
+        if (size > MAX_SCAN_FILE_BYTES)
+            return { kind: 'oversized' };
         let content;
         try {
-            content = readFileSync(file, 'utf8');
+            content = readFileSync(abs, 'utf8');
         }
-        catch {
-            continue;
+        catch (e) {
+            return { kind: isMissing(e) ? 'missing' : 'unreadable' };
         }
-        // Per-file size cap: a huge file (a big command/aggregate module) is a
-        // catastrophic-backtracking / quadratic hazard and never holds a registry
-        // that owes a remover. Skip it rather than let one file wedge the scan.
-        if (content.length > MAX_SCAN_FILE_BYTES)
-            continue;
-        if (isGeneratedFile(file, content))
-            continue;
-        filesScanned += 1;
+        if (isGeneratedContent(content))
+            return { kind: 'generated' };
+        const fileDeadline = Math.min(deadline, fileStart + perFileBudgetMs);
+        const abandon = (phase, t, registersSeen) => ({
+            kind: 'over-budget',
+            entry: {
+                file,
+                phase,
+                deadline: t >= deadline ? 'run' : 'file',
+                elapsedMs: Math.max(0, t - fileStart),
+                registersSeen,
+            },
+        });
         // Scan declarations on code with comments/strings blanked out; keep the raw
         // content only for the comment-based @shrkcrft annotations.
         const code = stripCommentsAndLiterals(content);
+        let t = clock('strip');
+        if (t >= fileDeadline)
+            return abandon('strip', t, 0);
         const lineStarts = buildLineStarts(code);
         const registers = findRegistersInFile(code, lineStarts);
+        t = clock('registers');
+        if (t >= fileDeadline)
+            return abandon('registers', t, registers.length);
         // Per-file lifecycle evidence: only a file that BOTH accumulates removable
         // state AND has a teardown-shaped API plausibly owes a per-register remover.
-        const hasAccumulation = ACCUMULATION_RE.test(code);
-        const hasTeardown = TEARDOWN_RE.test(code);
-        const ownsLifecycle = hasAccumulation && hasTeardown;
+        const ownsLifecycle = ACCUMULATION_RE.test(code) && TEARDOWN_RE.test(code);
+        const sites = registers.length > 0 ? indexCallableSites(code) : new Map();
+        const annotated = content.includes('@shrkcrft');
+        const pairs = [];
+        const missing = [];
+        const oneShot = [];
+        const ign = [];
         for (const reg of registers) {
-            registersFound += 1;
-            const ann = findIgnoreAnnotations(content, reg.name);
+            t = clock('register');
+            if (t >= fileDeadline)
+                return abandon('removers', t, registers.length);
+            const ann = annotated ? findIgnoreAnnotations(content, reg.name) : { ignore: false };
             if (ann.ignore) {
-                ignored.push({
+                ign.push({
                     registerName: reg.name,
-                    file: relative(projectRoot, file),
+                    file,
                     line: reg.line,
                     reason: ann.reason ?? 'ignored',
                     ...(ann.managedBy ? { managedBy: ann.managedBy } : {}),
@@ -363,88 +518,323 @@ export function buildRegistryLifecycleReport(input) {
                 continue;
             }
             const candidates = expectedRemoverNames(reg.name);
-            const remover = findRemoverInContent(code, candidates, lineStarts);
-            if (remover) {
-                matchedPairs.push({
+            // Candidate PRIORITY order is preserved: the first expected name with a
+            // callable site wins, exactly as the per-name loop it replaces.
+            const removerName = candidates.find((n) => sites.has(n));
+            if (removerName !== undefined) {
+                pairs.push({
                     registerName: reg.name,
-                    removerName: remover.name,
-                    file: relative(projectRoot, file),
+                    removerName,
+                    file,
                     registerLine: reg.line,
-                    removerLine: remover.line,
+                    removerLine: lineAtOffset(lineStarts, sites.get(removerName)),
                 });
             }
             else if (ownsLifecycle) {
-                missingRemovers.push({
+                missing.push({
                     registerName: reg.name,
                     expectedRemoverNames: candidates,
-                    file: relative(projectRoot, file),
+                    file,
                     line: reg.line,
                     suggestion: `Add ${candidates[0]}() / ${candidates[1]}() / ${candidates[2]}() — or annotate with \`@shrkcrft lifecycle-ignore <reason>\` / \`@shrkcrft lifecycle-managed-by <name>\` if cleanup is owned elsewhere.`,
                 });
             }
             else {
                 // No teardown-shaped API in the file → one-shot / bootstrap registration.
-                oneShotBootstrap.push({
+                oneShot.push({
                     registerName: reg.name,
-                    file: relative(projectRoot, file),
+                    file,
                     line: reg.line,
                     reason: 'no teardown-shaped API in file — treated as one-shot bootstrap',
                 });
             }
         }
+        return { kind: 'judged', registers: registers.length, pairs, missing, oneShot, ignored: ign };
+    }
+    function step() {
+        if (finished)
+            return false;
+        if (cursor >= end) {
+            finished = true;
+            return false;
+        }
+        const fileStart = clock('file');
+        if (fileStart >= deadline) {
+            timedOut = true;
+            finished = true;
+            return false;
+        }
+        const abs = files[cursor];
+        const outcome = judgeFile(abs, relOf.get(abs), fileStart);
+        switch (outcome.kind) {
+            case 'generated':
+                generated += 1;
+                break;
+            case 'missing':
+                missingCount += 1;
+                break;
+            case 'oversized':
+                oversized.push(relOf.get(abs));
+                break;
+            case 'unreadable':
+                unreadable.push(relOf.get(abs));
+                break;
+            case 'over-budget':
+                overBudget.push(outcome.entry);
+                if (outcome.entry.deadline === 'run') {
+                    // The RUN's deadline expired inside this file: stop, and leave the
+                    // cursor ON it so `--offset <nextOffset>` re-scans it.
+                    timedOut = true;
+                    finished = true;
+                    return false;
+                }
+                break;
+            case 'judged':
+                filesScanned += 1;
+                registersFound += outcome.registers;
+                matchedPairs.push(...outcome.pairs);
+                missingRemovers.push(...outcome.missing);
+                oneShotBootstrap.push(...outcome.oneShot);
+                ignored.push(...outcome.ignored);
+                break;
+        }
+        cursor += 1;
+        return true;
+    }
+    function snapshot(options = {}) {
+        const interrupted = options.interrupted === true && cursor < end;
+        const nextOffset = walkComplete && cursor < files.length ? cursor : undefined;
+        const truncated = !walkComplete || cursor < files.length;
+        // Deliberate narrowing only: a generated file, and one deleted mid-walk.
+        // An over-cap file stays EXPECTED and is named unexamined below.
+        const excludedCount = generated + missingCount;
+        const expected = Math.max(0, files.length - start - excludedCount);
+        const fileOverBudget = overBudget.filter((o) => o.deadline === 'file').map((o) => o.file);
+        const remaining = files.slice(cursor).map((f) => relOf.get(f));
+        const unexaminedAll = [...new Set([...fileOverBudget, ...unreadable, ...oversized, ...remaining])];
+        const reason = coverageReason({
+            walkComplete,
+            interrupted,
+            timedOut,
+            capped: truncated,
+            budgetMs,
+            limit,
+            perFileBudgetMs,
+            cursor,
+            processed: cursor - start,
+            overBudgetCount: fileOverBudget.length,
+            unreadableCount: unreadable.length,
+            oversizedCount: oversized.length,
+        });
+        const coverage = {
+            unit: 'files',
+            expected,
+            examined: filesScanned,
+            root: walkRoot,
+            ...(truncated ? { capped: true } : {}),
+            ...(unexaminedAll.length > 0
+                ? { unexamined: unexaminedAll.slice(0, UNEXAMINED_SHOWN), unexaminedTotal: unexaminedAll.length }
+                : {}),
+            ...(reason ? { reason } : {}),
+        };
+        const registrationCoverage = {
+            unit: 'registrations',
+            expected: registersFound,
+            examined: registersFound,
+            root: walkRoot,
+            ...(registersFound === 0 ? { reason: 'no register* declaration in the examined files' } : {}),
+        };
+        const recommendations = [];
+        if (missingRemovers.length > 0) {
+            recommendations.push(`Run \`shrk check registry-lifecycle --json\` and add the matching remover(s), or document why not via a \`@shrkcrft lifecycle-ignore\` / \`@shrkcrft lifecycle-managed-by\` annotation.`);
+        }
+        const settled = registryLifecycleVerdict({
+            missingRemovers,
+            coverage,
+            registrationCoverage,
+            ...(configCoverage ? { configCoverage } : {}),
+        });
+        return {
+            schema: 'sharkcraft.registry-lifecycle/v1',
+            filesScanned,
+            totalFiles: files.length,
+            truncated,
+            timedOut,
+            interrupted,
+            walkComplete,
+            changedOnly,
+            ...(scope ? { scope } : {}),
+            offset: start,
+            limit,
+            budgetMs,
+            perFileBudgetMs,
+            candidatesExamined: cursor - start,
+            ...(nextOffset !== undefined ? { nextOffset } : {}),
+            excludedFiles: { generated, missing: missingCount, oversized: [...oversized] },
+            unreadableFiles: [...unreadable],
+            overBudgetFiles: [...overBudget],
+            skipDirs: skip.effective,
+            droppedDefaultSkipDirs: skip.droppedDefaults,
+            warnings: [...warnings],
+            registersFound,
+            matchedPairs: [...matchedPairs],
+            missingRemovers: [...missingRemovers],
+            oneShotBootstrap: [...oneShotBootstrap],
+            ignored: [...ignored],
+            recommendations,
+            coverage,
+            registrationCoverage,
+            ...(configCoverage ? { configCoverage } : {}),
+            verdict: settled.verdict,
+            ...(settled.reason !== undefined ? { verdictReason: settled.reason } : {}),
+        };
+    }
+    return { step, snapshot };
+}
+/** Why the files coverage fell short — the continuation lives here, so the verdict line carries it. */
+function coverageReason(s) {
+    if (!s.walkComplete) {
+        return `the ${s.budgetMs} ms wall-clock budget expired during the tree walk, before every candidate was found; narrow with --scope <dir> or raise --budget-ms`;
+    }
+    if (s.interrupted)
+        return `interrupted by a signal after ${s.processed} candidate(s); continue with --offset ${s.cursor}`;
+    if (s.timedOut) {
+        return `the ${s.budgetMs} ms wall-clock budget expired after ${s.processed} candidate(s); continue with --offset ${s.cursor}, or raise --budget-ms`;
+    }
+    if (s.capped)
+        return `--limit ${s.limit} reached; continue with --offset ${s.cursor} (or --limit 0 for an uncapped run)`;
+    const parts = [];
+    if (s.overBudgetCount > 0)
+        parts.push(`over the per-file budget (${s.perFileBudgetMs} ms) and never judged`);
+    if (s.unreadableCount > 0)
+        parts.push('unreadable');
+    if (s.oversizedCount > 0)
+        parts.push(`over the ${LIFECYCLE_READ_CAP} lifecycle read cap, so never judged`);
+    if (parts.length === 0)
+        return undefined;
+    // The budget remedy only reaches what a budget stopped; an over-cap file is
+    // never judged whatever the budget.
+    const remedy = s.overBudgetCount > 0 || s.unreadableCount > 0 ? ' — raise --budget-ms or narrow with --scope <dir>' : '';
+    return `${parts.join(' or ')}${remedy}`;
+}
+/**
+ * THE lifecycle verdict. Both CLI verbs settle the same coverage records
+ * through `buildGateEnvelope`, and the MCP tool reads this — every surface
+ * answers from `coverageShortfall`, never a re-derived ternary.
+ *
+ *   - a missing remover in the examined scope → `fail` (a real violation is
+ *     real however much of the tree was examined);
+ *   - otherwise any coverage shortfall (a config that failed to load, a cap,
+ *     an expired budget, a signal, an over-budget or unreadable file, nothing
+ *     in scope, no registrations) → `not-verified`, with the shortfall as the
+ *     reason;
+ *   - otherwise `pass`.
+ */
+export function registryLifecycleVerdict(report) {
+    if (report.missingRemovers.length > 0) {
+        return {
+            verdict: 'fail',
+            reason: `${report.missingRemovers.length} register* declaration(s) with no matching remover`,
+        };
     }
-    const recommendations = [];
-    if (missingRemovers.length > 0) {
-        recommendations.push(`Run \`shrk check registry-lifecycle --json\` and add the matching remover(s), or document why not via a \`@shrkcrft lifecycle-ignore\` / \`@shrkcrft lifecycle-managed-by\` annotation.`);
-    }
-    return {
-        schema: 'sharkcraft.registry-lifecycle/v1',
-        filesScanned,
-        totalFiles: files.length,
-        truncated: files.length > scanFiles.length || timedOut,
-        timedOut,
-        changedOnly,
-        ...(scope ? { scope } : {}),
-        registersFound,
-        matchedPairs,
-        missingRemovers,
-        oneShotBootstrap,
-        ignored,
-        recommendations,
-    };
+    // The config shortfall FIRST: when the configured scope was never applied,
+    // every other count describes the wrong scope.
+    const gap = (report.configCoverage ? coverageShortfall(report.configCoverage) : undefined) ??
+        coverageShortfall(report.coverage) ??
+        coverageShortfall(report.registrationCoverage);
+    if (gap !== undefined)
+        return { verdict: 'not-verified', reason: gap };
+    return { verdict: 'pass' };
 }
-export function renderRegistryLifecycleReportText(report) {
+/** Synchronous scan: drives {@link createRegistryLifecycleScan} to the end. */
+export function buildRegistryLifecycleReport(input) {
+    const scan = createRegistryLifecycleScan(input);
+    while (scan.step()) {
+        // one candidate per step — the budget is checked inside each
+    }
+    return scan.snapshot();
+}
+/**
+ * Signal-aware scan: the same {@link IRegistryLifecycleScan.step}, yielding to
+ * the event loop between files so a SIGTERM / SIGINT handler can run. An
+ * aborted run returns the partial report with `interrupted: true` and a
+ * `nextOffset` that continues it. Latency is bounded by one (linear) file.
+ */
+export async function runRegistryLifecycleScan(input, options = {}) {
+    const scan = createRegistryLifecycleScan(input);
+    for (;;) {
+        if (options.signal?.aborted)
+            return scan.snapshot({ interrupted: true });
+        if (!scan.step())
+            return scan.snapshot();
+        await new Promise((resolve) => setImmediate(resolve));
+    }
+}
+export function renderRegistryLifecycleReportText(report, options = {}) {
+    const command = options.command ?? 'shrk check registry-lifecycle';
     const lines = [];
     lines.push('=== Registry lifecycle ===');
     if (report.scope)
         lines.push(`  scope             ${report.scope}`);
     if (report.changedOnly)
         lines.push('  scope             changed-only');
-    // Loud skip: a changed diff that touches no scannable file was NOT verified —
-    // never let "scanned nothing" read as a clean pass.
-    if (report.changedOnly && report.filesScanned === 0) {
-        lines.push('');
-        lines.push('  ! 0 files in the changed scope — lifecycle NOT verified (this is not a pass).');
-        return lines.join('\n') + '\n';
-    }
-    if (report.timedOut) {
-        lines.push(`  ! wall-clock budget hit — scanned ${report.filesScanned}/${report.totalFiles} before flushing partial results (re-run with --scope <dir> to finish).`);
-    }
-    lines.push(`  files scanned     ${report.filesScanned}` +
-        (report.truncated && !report.timedOut
-            ? ` ! capped (${report.totalFiles} candidates — re-run with --scope <dir> for the rest)`
-            : ''));
+    lines.push(`  candidates        ${report.totalFiles}` + (report.offset > 0 ? ` (this run starts at offset ${report.offset})` : ''));
+    lines.push(`  files scanned     ${report.filesScanned} of ${report.coverage.expected}`);
     lines.push(`  registers found   ${report.registersFound}`);
     lines.push(`  matched pairs     ${report.matchedPairs.length}`);
     lines.push(`  missing removers  ${report.missingRemovers.length}`);
     lines.push(`  one-shot bootstrap ${report.oneShotBootstrap.length}`);
     lines.push(`  ignored           ${report.ignored.length}`);
-    // Zero registrations in scope means nothing was actually checked — say so
-    // loudly so it never reads as the green "all removers present" pass (the exit
-    // code is NOT-verified `2` to match; a25 §1 / §2.5).
-    if (report.registersFound === 0 && !report.timedOut) {
+    const ex = report.excludedFiles;
+    if (ex.generated + ex.missing > 0) {
+        const parts = [];
+        if (ex.generated > 0)
+            parts.push(`${ex.generated} generated`);
+        if (ex.missing > 0)
+            parts.push(`${ex.missing} deleted`);
+        lines.push(`  excluded          ${parts.join(', ')}`);
+    }
+    // An over-cap file is UNEXAMINED (it is in the coverage's expected scope),
+    // never "excluded": listed with the other files that were never judged.
+    for (const o of ex.oversized.slice(0, 20)) {
+        lines.push(`  ! over read cap   ${o} — over the ${LIFECYCLE_READ_CAP} lifecycle read cap, never judged`);
+    }
+    for (const o of report.overBudgetFiles) {
+        lines.push(`  ! over budget     ${o.file} — ${o.phase} phase, ${o.elapsedMs} ms (${o.deadline === 'run' ? "the run's budget" : `the ${report.perFileBudgetMs} ms per-file budget`}); ${o.registersSeen} register(s) seen, none judged`);
+    }
+    for (const u of report.unreadableFiles.slice(0, 20))
+        lines.push(`  ! unreadable      ${u}`);
+    for (const w of report.warnings)
+        lines.push(`  ! ${w}`);
+    // Scope facts — what was NOT examined and how to reach it. The verdict line
+    // itself is the caller's (the CLI settles it through the gate envelope).
+    const remainingCount = report.totalFiles - (report.offset + report.candidatesExamined);
+    const resume = report.nextOffset !== undefined ? `${command} --offset ${report.nextOffset}` : undefined;
+    if (report.coverage.expected === 0 && report.walkComplete) {
+        lines.push('');
+        lines.push(report.changedOnly
+            ? '  ! 0 files in the changed scope — nothing to judge.'
+            : '  ! 0 candidate files in scope — nothing to judge.');
+    }
+    else if (report.registersFound === 0 && report.filesScanned > 0 && !report.truncated) {
+        lines.push('');
+        lines.push('  ! 0 register* declarations in the examined files — nothing to judge.');
+    }
+    if (!report.walkComplete) {
+        lines.push('');
+        lines.push(`  ! wall-clock budget (${report.budgetMs} ms) expired during the tree walk — ${report.totalFiles} candidate(s) found so far; narrow with --scope <dir> or raise --budget-ms.`);
+    }
+    else if (report.interrupted && resume) {
+        lines.push('');
+        lines.push(`  ! INTERRUPTED — partial results (scanned ${report.filesScanned}/${report.coverage.expected}); continue with ${resume}`);
+    }
+    else if (report.timedOut && resume) {
+        lines.push('');
+        lines.push(`  ! wall-clock budget (${report.budgetMs} ms) hit — scanned ${report.filesScanned}/${report.coverage.expected}; continue with ${resume} (or raise --budget-ms)`);
+    }
+    else if (resume) {
         lines.push('');
-        lines.push('  ! 0 registrations found in scope — lifecycle NOT verified (this is not a pass).');
+        lines.push(`  ! capped — scanned ${report.candidatesExamined} of ${report.totalFiles - report.offset} candidate files (cap --limit ${report.limit}); ${remainingCount} unexamined. Continue: ${resume}   (or --limit 0 for an uncapped run)`);
     }
     lines.push('');
     if (report.missingRemovers.length > 0) {