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

package/dist/commands/registrations.command.js

@@ -11,9 +11,17 @@
  *   shrk registrations preview <id> [--var key=value ...] [--json]
  */
 import * as nodePath from 'node:path';
-import { inspectSharkcraft, listRegistrationHints, listRegistrationHintIssues, getRegistrationHint, previewRegistrationHint, } from '@shrkcrft/inspector';
+import { assetDoctorProposedExit, ContributionKind, inspectSharkcraft, listRegistrationHints, buildRegistrationHintDoctorReport, getRegistrationHint, previewRegistrationHint, settledUnitStates, } from '@shrkcrft/inspector';
+import { formatCoverage } from '@shrkcrft/core';
+import { PositionalMode } from "../dispatch/positional-mode.js";
+import { ALLOW_EMPTY_FLAG, allowEmptyValve } from "../gates/allow-empty.js";
+import { assetDoctorFailingUnits } from "../gates/asset-doctor-failing-units.js";
+import { assetDoctorFailureLine } from "../gates/asset-doctor-failure-line.js";
+import { settleVerdict } from "../gates/settle-verdict.js";
+import { verdictLine } from "../gates/verdict-line.js";
 import { flagBool, flagString, flagVars, resolveCwd, } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
+import { writeRejectedEntriesNote } from "../output/rejected-entries-note.js";
 import { savePlanToFile, signPlan } from '@shrkcrft/generator';
 const REGISTRATION_HINT_SYNTHETIC_TEMPLATE = '__registration-hint__';
 const registrationsListCommand = {
@@ -25,8 +33,11 @@ const registrationsListCommand = {
         const source = flagString(args, 'source');
         const all = await listRegistrationHints(inspection);
         const filtered = source ? all.filter((e) => e.source === source) : all;
+        // A hint its loader refused is named, never silently absent (round 12, 12.1).
+        const note = { ...(source ? { source } : {}), next: 'shrk registrations doctor' };
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson(filtered) + '\n');
+            await writeRejectedEntriesNote(inspection, [ContributionKind.RegistrationHint], { ...note, json: true });
             return 0;
         }
         process.stdout.write(header(`Registration hints (${filtered.length})`));
@@ -36,6 +47,7 @@ const registrationsListCommand = {
         if (filtered.length === 0) {
             process.stdout.write('  (no registration hints contributed — packs add them via registrationHintFiles[])\n');
         }
+        await writeRejectedEntriesNote(inspection, [ContributionKind.RegistrationHint], note);
         return 0;
     },
 };
@@ -87,24 +99,99 @@ const registrationsGetCommand = {
 };
 const registrationsDoctorCommand = {
     name: 'doctor',
-    description: 'Validate registration hint registries (local + pack).',
-    usage: 'shrk registrations doctor [--json]',
+    description: 'Validate registration hints (local + pack): load issues, and every hint’s discovery against the live tree — verified / ambiguous / dead / unverified. Exit 0 pass · 1 errors · 2 a dead or capped discovery.',
+    usage: 'shrk registrations doctor [--json] [--strict] [--fail-on-dead-units] [--allow-empty]',
+    booleanFlags: new Set(['json', 'strict', 'fail-on-dead-units', ALLOW_EMPTY_FLAG]),
     async run(args) {
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
-        const issues = await listRegistrationHintIssues(inspection);
+        // THE discovery authority — the same candidate set `preview` acts on.
+        const report = await buildRegistrationHintDoctorReport(inspection);
+        const errors = report.issues.filter((i) => i.severity === 'error').length;
+        const warnings = report.issues.filter((i) => i.severity === 'warning').length;
+        // THE asset-doctor proposal (round 13): errors, warnings under --strict, and
+        // every settled selector unit THE --fail-on-dead-units predicate fails (a
+        // dead one, or a stale LOCAL expectEmpty marker — a pack's is INFO).
+        const proposed = assetDoctorProposedExit({ errors, warnings, units: report.liveness.units }, { strict: flagBool(args, 'strict'), failOnDeadUnits: flagBool(args, 'fail-on-dead-units') });
+        // No hint declared examined nothing: NOT VERIFIED (2) — the answer the
+        // helper / checks / conventions / templates doctors give an empty input,
+        // never a 0 that reads as "every hint verified" — unless `--allow-empty`
+        // accepts it (printed). Added here, not in the inspector report, so the
+        // self-config doctor (which folds these findings) is not vetoed by a repo
+        // that simply declares no hints.
+        const coverage = report.totals.hints === 0
+            ? [
+                ...report.coverage,
+                {
+                    unit: 'registration hints',
+                    expected: 0,
+                    examined: 0,
+                    reason: 'no registration hints declared',
+                    ...allowEmptyValve(args, 0),
+                },
+            ]
+            : report.coverage;
+        const settled = settleVerdict(proposed, coverage);
+        // THE units that fail this run (round 13 review) — printed and in --json,
+        // so a 1 from --fail-on-dead-units is never silent about why.
+        const failing = assetDoctorFailingUnits(report.liveness.units, {
+            failOnDeadUnits: flagBool(args, 'fail-on-dead-units'),
+            strict: flagBool(args, 'strict'),
+        });
         if (flagBool(args, 'json')) {
-            process.stdout.write(asJson({ issues }) + '\n');
-            return issues.some((i) => i.severity === 'error') ? 1 : 0;
+            process.stdout.write(asJson({
+                issues: report.issues,
+                failingUnits: failing.map((u) => ({ list: u.list, unit: u.unit, state: u.state, message: u.message })),
+                hints: report.hints,
+                totals: report.totals,
+                coverage,
+                deadUnits: report.deadUnits,
+                units: settledUnitStates([report.liveness]),
+                exitCode: settled.exit,
+                verdict: settled.verdict,
+                shortfalls: settled.shortfalls,
+                accepted: settled.accepted,
+            }) + '\n');
+            return settled.exit;
         }
-        process.stdout.write(header(`Registration hint doctor (${issues.length} issue(s))`));
-        if (issues.length === 0) {
-            process.stdout.write('  OK\n');
-            return 0;
+        const t = report.totals;
+        // Never "N issues" alone: 0 issues must not read as "N hints verified".
+        process.stdout.write(header(`Registration hint doctor — ${t.hints} hint(s): ${t.verified} verified · ${t.ambiguous} ambiguous · ${t.dead} dead · ${t.unverified} unverified${t.intendedEmpty > 0 ? ` · ${t.intendedEmpty} intended-empty` : ''}`));
+        // The status column fits every status the doctor prints — `intended-empty`
+        // (14 wide) overflowed the old 11-wide column into the id (round 13, K11).
+        const statusWidth = Math.max(11, ...report.hints.map((h) => h.status.length));
+        for (const h of report.hints) {
+            process.stdout.write(`  ${h.status.padEnd(statusWidth)} ${h.id.padEnd(36)} ${h.discovery} (${h.candidates} candidate(s))\n`);
+        }
+        for (const c of report.coverage)
+            process.stdout.write(`  coverage    ${formatCoverage(c)}\n`);
+        if (report.issues.length > 0) {
+            process.stdout.write(`\nIssues (${report.issues.length}):\n`);
+            for (const i of report.issues) {
+                process.stdout.write(`  ${i.severity.toUpperCase().padEnd(7)} ${i.code.padEnd(30)} ${i.message}\n`);
+            }
         }
-        for (const i of issues) {
-            process.stdout.write(`  ${i.severity.toUpperCase().padEnd(7)} ${i.code.padEnd(28)} ${i.message}\n`);
+        // A stale LOCAL expectEmpty marker withholds the ✓ (a pack's is INFO: the
+        // consumer cannot edit it); an intended-empty one is accepted, printed below.
+        const staleLocal = report.liveness.wentLive.filter((u) => u.mark?.packageName === undefined).length;
+        const clean = t.hints === 0
+            ? 'No registration hints declared — nothing to verify.'
+            : warnings > 0
+                ? `No blocking registration-hint issues — ${warnings} warning(s) reported above.`
+                : staleLocal > 0
+                    ? `No blocking registration-hint issues — ${staleLocal} expectEmpty marker(s) went live (listed above; remove the markers).`
+                    : `Every hint's discovery resolves (${t.verified} verified, ${t.ambiguous} ambiguous${t.intendedEmpty > 0 ? `, ${t.intendedEmpty} intended empty` : ''}). ✓`;
+        const line = verdictLine(settled, clean);
+        if (line)
+            process.stdout.write('\n' + line + '\n');
+        // Round 13 review: a 1 from --fail-on-dead-units names its units — the
+        // doctor printed only INFO issue lines, and `verdictLine` prints nothing
+        // for a 1 without a shortfall.
+        if (settled.exit === 1) {
+            const failure = assetDoctorFailureLine('registration-hint doctor', failing);
+            if (failure)
+                process.stdout.write('\n' + failure + '\n');
         }
-        return issues.some((i) => i.severity === 'error') ? 1 : 0;
+        return settled.exit;
     },
 };
 const registrationsPreviewCommand = {
@@ -281,6 +368,44 @@ export const registrationsCommand = {
     name: 'registrations',
     description: 'Inspect/preview/plan pack-contributed registration hints (downstream registration steps for generated constructs).',
     usage: 'shrk registrations <list|get|doctor|preview|plan> ...',
+    // Declared (round 11 review): the dispatcher guard refuses an unknown verb
+    // with the closest one, and the declared walk reaches `registrations doctor`
+    // — a verdict verb, so a bad flag there exits 3, labelled with its own path.
+    positionals: PositionalMode.None,
+    subverbs: [
+        {
+            name: registrationsListCommand.name,
+            description: registrationsListCommand.description,
+            usage: registrationsListCommand.usage,
+            positionals: PositionalMode.None,
+        },
+        {
+            name: registrationsGetCommand.name,
+            description: registrationsGetCommand.description,
+            usage: registrationsGetCommand.usage,
+            positionals: PositionalMode.Free,
+        },
+        {
+            name: registrationsDoctorCommand.name,
+            description: registrationsDoctorCommand.description,
+            usage: registrationsDoctorCommand.usage,
+            positionals: PositionalMode.None,
+        },
+        {
+            name: registrationsPreviewCommand.name,
+            description: registrationsPreviewCommand.description,
+            usage: registrationsPreviewCommand.usage,
+            positionals: PositionalMode.Free,
+        },
+        {
+            name: registrationsPlanCommand.name,
+            description: registrationsPlanCommand.description,
+            usage: registrationsPlanCommand.usage,
+            positionals: PositionalMode.Free,
+        },
+    ],
+    // The group parses every subverb's argv, so the subverbs' boolean flags live here too.
+    booleanFlags: new Set(['json', 'strict', 'fail-on-dead-units', ALLOW_EMPTY_FLAG]),
     async run(args) {
         const sub = args.positional[0];
         const rest = { ...args, positional: args.positional.slice(1) };

package/dist/commands/registry-lifecycle-run.d.ts

@@ -0,0 +1,14 @@
+import { type ParsedArgs } from '../command-registry.js';
+/** The two verbs this body answers for — the gate envelope's `verb`. */
+type RegistryLifecycleVerb = 'check registry-lifecycle' | 'registry lifecycle';
+/** The flag grammar both verbs share (one usage line, one allowlist). */
+export declare const REGISTRY_LIFECYCLE_FLAGS_USAGE = "[--scope <dir>] [--changed-only] [--since <ref>] [--limit <n>] [--offset <n>] [--budget-ms <n>] [--allow-empty] [--json]";
+/**
+ * Run a lifecycle scan for `verb`. `options.signal` is the in-process test seam
+ * for SIGTERM / SIGINT: aborting it prints the partial report and exits `2`.
+ */
+export declare function runRegistryLifecycle(args: ParsedArgs, verb: RegistryLifecycleVerb, options?: {
+    readonly signal?: AbortSignal;
+}): Promise<number>;
+export {};
+//# sourceMappingURL=registry-lifecycle-run.d.ts.map

package/dist/commands/registry-lifecycle-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-lifecycle-run.d.ts","sourceRoot":"","sources":["../../src/commands/registry-lifecycle-run.ts"],"names":[],"mappings":"AA0BA,OAAO,EAML,KAAK,UAAU,EAChB,MAAM,wBAAwB,CAAC;AAShC,wEAAwE;AACxE,KAAK,qBAAqB,GAAG,0BAA0B,GAAG,oBAAoB,CAAC;AAE/E,yEAAyE;AACzE,eAAO,MAAM,8BAA8B,6HACiF,CAAC;AA6L7H;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,qBAAqB,EAC3B,OAAO,GAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAC9C,OAAO,CAAC,MAAM,CAAC,CA6HjB"}

package/dist/commands/registry-lifecycle-run.js

@@ -0,0 +1,336 @@
+/**
+ * The ONE body behind `shrk check registry-lifecycle` and `shrk registry
+ * lifecycle`.
+ *
+ * The two verbs used to carry copy-pasted bodies with two copies of the exit
+ * ternary — both of which forgot the file cap, so a scan that examined 2000 of
+ * 2103 candidates printed `missing removers 0` and exited 0 while a real
+ * violation sat in the 103 it never read. Now both delegate here, the engine
+ * owns the coverage records, and the exit is settled through the gate envelope
+ * like every other verdict verb:
+ *
+ *   - a missing remover → `1` (a violation in the examined scope is real);
+ *   - a cap, an expired budget, a signal, an over-budget / unreadable file,
+ *     nothing in scope, or no registrations → `2`, with the continuation
+ *     (`--offset <n>`) that actually reaches the remainder;
+ *   - otherwise `0`;
+ *   - a malformed flag → `3` with the usage line.
+ */
+import { renderRegistryLifecycleReportText, resolveChangedFiles, resolveProjectConfig, runRegistryLifecycleScan, } from '@shrkcrft/inspector';
+import { ERROR_CODES } from '@shrkcrft/core';
+import { firstUnknownFlag, flagBool, flagString, resolveCwd, spellFlagAsTyped, } from "../command-registry.js";
+import { GLOBAL_FLAGS } from "../dispatch/global-flags.js";
+import { ExitCode } from "../exit-codes.js";
+import { asJson } from "../output/format-output.js";
+import { buildGateEnvelope } from "../gates/gate-envelope.js";
+import { ALLOW_EMPTY_FLAG, allowEmptyValve } from "../gates/allow-empty.js";
+import { verdictLine } from "../gates/verdict-line.js";
+import { planeVerdictForExit } from "../gates/plane-verdict.js";
+/** The flag grammar both verbs share (one usage line, one allowlist). */
+export const REGISTRY_LIFECYCLE_FLAGS_USAGE = '[--scope <dir>] [--changed-only] [--since <ref>] [--limit <n>] [--offset <n>] [--budget-ms <n>] [--allow-empty] [--json]';
+/**
+ * Every flag the verbs honour, plus every dispatcher global (THE list in
+ * dispatch/global-flags.ts), which may reach the handler; anything else is a
+ * typo that would otherwise read as a satisfied request.
+ */
+const KNOWN_FLAGS = new Set([
+    'json',
+    'scope',
+    'changed-only',
+    'since',
+    'limit',
+    'offset',
+    'budget-ms',
+    ALLOW_EMPTY_FLAG,
+    ...GLOBAL_FLAGS,
+]);
+function usage(verb) {
+    return `Usage: shrk ${verb} ${REGISTRY_LIFECYCLE_FLAGS_USAGE}`;
+}
+/**
+ * A non-negative integer flag. `undefined` when absent; an error string when
+ * present but not an integer ≥ 0 (a bare `--limit`, `--limit abc`, `--limit -1`).
+ */
+function intFlag(args, name) {
+    if (!args.flags.has(name))
+        return undefined;
+    const raw = args.flags.get(name);
+    if (typeof raw !== 'string' || !/^\d+$/.test(raw.trim())) {
+        return { error: `--${name} needs a non-negative integer (got ${typeof raw === 'string' ? `"${raw}"` : 'no value'})` };
+    }
+    return Number(raw.trim());
+}
+/** One argument, shell-safe — a path with a space still pastes as one word. */
+function shellArg(value) {
+    return /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** The command a continuation re-runs: this verb plus every scoping flag the user passed. */
+function continuationCommand(verb, args) {
+    const parts = [`shrk ${verb}`];
+    // main.ts lifts a global `--cwd` into `args.globalCwd` before the handler
+    // runs (resolveCwd reads it there), so reading the flag alone dropped it —
+    // and a continuation pasted from another directory paged the wrong root.
+    const cwd = flagString(args, 'cwd') ?? args.globalCwd;
+    if (cwd)
+        parts.push(`--cwd ${shellArg(cwd)}`);
+    const scope = flagString(args, 'scope');
+    if (scope)
+        parts.push(`--scope ${shellArg(scope)}`);
+    if (flagBool(args, 'changed-only'))
+        parts.push('--changed-only');
+    const since = flagString(args, 'since');
+    if (since)
+        parts.push(`--since ${shellArg(since)}`);
+    const limit = flagString(args, 'limit');
+    if (limit)
+        parts.push(`--limit ${limit}`);
+    const budget = flagString(args, 'budget-ms');
+    if (budget)
+        parts.push(`--budget-ms ${budget}`);
+    return parts.join(' ');
+}
+/** The one rule result: the lifecycle rule, judged over the registrations it found. */
+function lifecycleRule(report, coverage) {
+    return {
+        id: 'registry-lifecycle',
+        type: 'lifecycle',
+        status: report.missingRemovers.length > 0 ? 'failed' : 'passed',
+        severity: 'error',
+        counts: {
+            candidates: report.totalFiles,
+            filesScanned: report.filesScanned,
+            registersFound: report.registersFound,
+            matchedPairs: report.matchedPairs.length,
+            missingRemovers: report.missingRemovers.length,
+            oneShotBootstrap: report.oneShotBootstrap.length,
+            ignored: report.ignored.length,
+            overBudgetFiles: report.overBudgetFiles.length,
+        },
+        violations: report.missingRemovers.map((m) => ({
+            id: m.registerName,
+            file: m.file,
+            line: m.line,
+            message: `no ${m.expectedRemoverNames.slice(0, 3).join(' / ')}`,
+            hint: m.suggestion,
+        })),
+        coverage,
+    };
+}
+/**
+ * The config-load row. An EXISTING sharkcraft.config.ts that failed to load
+ * means the configured skip set was never applied: errored (never
+ * `evaluated`), and its engine-owned coverage — 1 config file expected, 0
+ * examined — settles a clean run to 2. `--allow-empty` cannot waive it
+ * (expected is 1, not 0).
+ */
+function configRule(coverage) {
+    return {
+        id: 'config',
+        type: 'lifecycle',
+        status: 'error',
+        severity: 'error',
+        counts: {},
+        violations: [],
+        error: `sharkcraft.config.ts ${coverage.reason ?? 'failed to load'}`,
+        coverage,
+    };
+}
+/**
+ * Install SIGTERM / SIGINT handlers that abort the scan for the duration of the
+ * run. The JS thread yields between files, so a kill prints the partial report
+ * (and the `--offset` that continues it) instead of zero bytes.
+ */
+function trapSignals(controller) {
+    const onSignal = () => controller.abort();
+    process.once('SIGTERM', onSignal);
+    process.once('SIGINT', onSignal);
+    return () => {
+        process.off('SIGTERM', onSignal);
+        process.off('SIGINT', onSignal);
+    };
+}
+/** Settle first, render second — one envelope for text and `--json`. */
+function settle(verb, report, args) {
+    const proposed = report.missingRemovers.length > 0 ? ExitCode.Failure : ExitCode.VerifiedPass;
+    const rules = [
+        lifecycleRule(report, {
+            ...report.registrationCoverage,
+            ...allowEmptyValve(args, report.registrationCoverage.expected),
+        }),
+        ...(report.configCoverage ? [configRule(report.configCoverage)] : []),
+    ];
+    const run = { ...report.coverage, ...allowEmptyValve(args, report.coverage.expected) };
+    // Two literals, not one variable: the contract lock reads the literal FIRST
+    // argument of every envelope build and asserts it is a registered verdict verb.
+    return verb === 'registry lifecycle'
+        ? buildGateEnvelope('registry lifecycle', proposed, rules, run)
+        : buildGateEnvelope('check registry-lifecycle', proposed, rules, run);
+}
+/** The clean sentence — printed only through `verdictLine`, i.e. only at a settled 0. */
+function cleanSentence(report) {
+    const window = report.offset > 0
+        ? ` (candidates ${report.offset + 1}–${report.totalFiles} of ${report.totalFiles}; earlier ones were not examined in this run)`
+        : '';
+    return (`No missing removers — ${report.registersFound} register* declaration(s) judged across ` +
+        `${report.filesScanned} file(s)${window}. ✓`);
+}
+/**
+ * The `--json` reason for the SETTLED verdict, derived from the envelope —
+ * never the engine's pre-settlement one, which paired `verdict: 'pass'` (an
+ * `--allow-empty` acceptance) with a not-verified reason.
+ *
+ *   - exit 0: the acceptance lines, or nothing;
+ *   - exit 1: the engine's failure reason, plus any `also not verified: …`;
+ *   - exit 2: the shortfalls.
+ */
+function settledReason(env, report) {
+    if (env.exit === ExitCode.VerifiedPass)
+        return env.accepted.length > 0 ? env.accepted.join('; ') : undefined;
+    if (env.exit === ExitCode.Failure) {
+        const parts = [
+            ...(report.verdict === 'fail' && report.verdictReason ? [report.verdictReason] : []),
+            ...(env.shortfalls.length > 0 ? [`also not verified: ${env.shortfalls.join('; ')}`] : []),
+        ];
+        return parts.length > 0 ? parts.join('; ') : undefined;
+    }
+    return env.shortfalls.length > 0 ? env.shortfalls.join('; ') : undefined;
+}
+/** True when every shortfall is an empty scope (so `--allow-empty` would clear it). */
+function onlyEmptyShortfalls(report) {
+    // A config that failed to load is never an empty scope: --allow-empty cannot clear it.
+    if (report.configCoverage)
+        return false;
+    const c = report.coverage;
+    if (c.capped)
+        return false;
+    const filesEmptyOrFull = c.expected === 0 || c.examined >= c.expected;
+    return filesEmptyOrFull && (c.expected === 0 || report.registrationCoverage.expected === 0);
+}
+/**
+ * Run a lifecycle scan for `verb`. `options.signal` is the in-process test seam
+ * for SIGTERM / SIGINT: aborting it prints the partial report and exits `2`.
+ */
+export async function runRegistryLifecycle(args, verb, options = {}) {
+    const json = flagBool(args, 'json');
+    const badFlag = (error) => {
+        process.stderr.write(`${error}\n${usage(verb)}\n`);
+        return ExitCode.UsageError;
+    };
+    // `--offset -1`: the parser reads `-1` as a flag of its own and leaves
+    // `--offset` valueless. Report the malformed VALUE — what `intFlag` promises —
+    // never an unknown `--1`.
+    for (const name of ['limit', 'offset', 'budget-ms']) {
+        const at = args.flags.get(name) === true ? (args.argv ?? []).indexOf(`--${name}`) : -1;
+        const next = at >= 0 ? args.argv?.[at + 1] : undefined;
+        if (next !== undefined && /^-\d/.test(next)) {
+            return badFlag(`--${name} needs a non-negative integer (got "${next}")`);
+        }
+    }
+    const unknown = firstUnknownFlag(args, KNOWN_FLAGS);
+    if (unknown !== undefined) {
+        process.stderr.write(`unknown option '${spellFlagAsTyped(unknown, args.argv)}'\n${usage(verb)}\n`);
+        return ExitCode.UsageError;
+    }
+    const limit = intFlag(args, 'limit');
+    if (typeof limit === 'object')
+        return badFlag(limit.error);
+    const offset = intFlag(args, 'offset');
+    if (typeof offset === 'object')
+        return badFlag(offset.error);
+    const budgetMs = intFlag(args, 'budget-ms');
+    if (typeof budgetMs === 'object')
+        return badFlag(budgetMs.error);
+    const cwd = resolveCwd(args);
+    const scope = flagString(args, 'scope');
+    const changedOnly = flagBool(args, 'changed-only');
+    const since = flagString(args, 'since');
+    // `--changed-only` scopes the scan to the diff (tracked + untracked), so it
+    // runs inline in seconds; the full-tree walk is bounded by the budget.
+    let files;
+    if (changedOnly || since) {
+        const changed = resolveChangedFiles({
+            projectRoot: cwd,
+            ...(since ? { since } : {}),
+            ...(changedOnly && !since ? { includeWorktree: true } : {}),
+        });
+        files = changed.files;
+    }
+    // The full-tree walk honours the project's skip-dir config (skipDirsAdd
+    // extends the defaults; skipDirs replaces them and is warned about).
+    let skipDirs;
+    let skipDirsAdd;
+    let configLoadError;
+    if (files === undefined) {
+        const loaded = await resolveProjectConfig(cwd);
+        if (loaded.ok) {
+            skipDirs = loaded.value.config.registryLifecycle?.skipDirs;
+            skipDirsAdd = loaded.value.config.registryLifecycle?.skipDirsAdd;
+        }
+        else if (loaded.error.code !== ERROR_CODES.SHARKCRAFT_FOLDER_NOT_FOUND) {
+            // A config that EXISTS but failed to load is not "no config": the
+            // configured skip set was never applied. The engine records it as a
+            // coverage shortfall, so the run can never settle to 0 over a scope the
+            // project did not ask for.
+            const fullPath = loaded.error.details?.['fullPath'];
+            configLoadError = { file: typeof fullPath === 'string' ? fullPath : null, message: loaded.error.message };
+        }
+        // Only the slow full-tree path needs the heartbeat (JSON keeps stdout clean).
+        if (!json) {
+            process.stderr.write('⏳ Scanning source for register*/remove* symmetry (bounded by a wall-clock budget)…\n');
+        }
+    }
+    const controller = new AbortController();
+    const forward = () => controller.abort();
+    if (options.signal?.aborted)
+        controller.abort();
+    else
+        options.signal?.addEventListener('abort', forward, { once: true });
+    const release = trapSignals(controller);
+    let report;
+    try {
+        report = await runRegistryLifecycleScan({
+            projectRoot: cwd,
+            ...(files !== undefined ? { files } : {}),
+            ...(scope ? { scope } : {}),
+            ...(skipDirs ? { skipDirs } : {}),
+            ...(skipDirsAdd ? { skipDirsAdd } : {}),
+            ...(limit !== undefined ? { limit } : {}),
+            ...(offset !== undefined ? { offset } : {}),
+            ...(budgetMs !== undefined ? { budgetMs } : {}),
+            ...(configLoadError ? { configLoadError } : {}),
+        }, { signal: controller.signal });
+    }
+    finally {
+        release();
+        options.signal?.removeEventListener('abort', forward);
+    }
+    // An offset past the last candidate is a typo'd continuation, not an empty
+    // scope: refusing it keeps `--allow-empty` from printing ✓ over "candidates
+    // 2103–2102 of 2102". Only once the walk completed — before that,
+    // `totalFiles` is a lower bound.
+    if (offset !== undefined && offset > 0 && report.walkComplete && offset >= report.totalFiles) {
+        return badFlag(`--offset ${offset} is past the last candidate (${report.totalFiles} candidate(s) in scope)`);
+    }
+    const env = settle(verb, report, args);
+    const exit = env.exit;
+    if (json) {
+        process.stdout.write(asJson({
+            ...report,
+            verdict: planeVerdictForExit(exit),
+            // The reason for the SETTLED verdict (omitted when there is none) —
+            // never the engine's pre-settlement one.
+            verdictReason: settledReason(env, report),
+            exitCode: exit,
+            gate: env,
+        }) + '\n');
+        return exit;
+    }
+    process.stdout.write(renderRegistryLifecycleReportText(report, { command: continuationCommand(verb, args) }));
+    const lead = exit === ExitCode.NotVerified && onlyEmptyShortfalls(report)
+        ? 'Nothing to judge in scope. Pass --allow-empty to accept an empty scope explicitly.'
+        : undefined;
+    const line = verdictLine(env, cleanSentence(report), lead);
+    if (line)
+        process.stdout.write(`\n${line}\n`);
+    return exit;
+}

package/dist/commands/registry.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.command.d.ts","sourceRoot":"","sources":["../../src/commands/registry.command.ts"],"names":[],"mappings":"AA8BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAQhC,eAAO,MAAM,wBAAwB,EAAE,eA8CtC,CAAC;AAkMF,eAAO,MAAM,eAAe,EAAE,eA0C7B,CAAC"}
+{"version":3,"file":"registry.command.d.ts","sourceRoot":"","sources":["../../src/commands/registry.command.ts"],"names":[],"mappings":"AAwCA,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgBhC,eAAO,MAAM,wBAAwB,EAAE,eAUtC,CAAC;AA+ZF,eAAO,MAAM,eAAe,EAAE,eA6D7B,CAAC"}