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

package/dist/pack-contributions-inventory.js

@@ -6,18 +6,29 @@
  *   - one row per detected collision — the conflicts
  *
  * Both outputs are deterministic and read-only.
+ *
+ * Honesty contract (round 11): an id the inventory could only SCRAPE is never
+ * reported as a healthy contribution. A file the module loader cannot import is
+ * a load failure — its scraped ids are `validation: 'error'` and the file is an
+ * `invalid-contribution` error conflict. A regex id from a kind whose loader
+ * returned nothing for that file is a `warning`. Every text/markdown render
+ * prints the extraction mode, so a fallback is never invisible.
+ *
+ * Round 12 (12.1e): EVERY loader-backed slot is a kind and is listed
+ * structurally (registration hints, presets, boundaries, scaffold patterns,
+ * constructs + facets, search tuning, decisions, policy checks, feedback rules,
+ * tests, delegate recipes, framework extractors and the gate planes were
+ * scraped by regex, or not listed at all), and an entry its loader REFUSED is
+ * in `rejections` — a scraped id matching one is `error` "rejected by the
+ * loader", never the `ok` a regex id of an unloaded kind used to get.
  */
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
-// Structural loaders used to replace regex-fallback noise per kind.
-import { HELPERS } from "./helper-registry.js";
-import { listConventions } from "./convention-registry.js";
-import { listPackHelpers } from "./pack-helper-registry.js";
-import { listTaskRoutingHints } from "./task-routing-hint-registry.js";
-import { listRegistrationHints } from "./registration-hint-registry.js";
-import { listPlaybooks } from "./playbook-registry.js";
-import { loadAllContractTemplates } from "./contract-template-registry.js";
-import { listMigrationProfilesFromPacks } from "./migration-profile-registry.js";
+import { CONTRIBUTION_FILE_KEYS } from '@shrkcrft/plugin-api';
+import { collectContributionLoadFailures, collectContributionRejections, collectRegistryOutcomes, formatEntryRejection, } from "./contribution-load-failures.js";
+import { ContributionKind } from "./contribution-kind.js";
+import { describePackAssetFreshness, detectPackAssetFreshness } from "./pack-asset-freshness.js";
+export { ContributionKind } from "./contribution-kind.js";
 export const PACK_CONTRIBUTIONS_INVENTORY_SCHEMA = 'sharkcraft.pack-contributions-inventory/v1';
 export var ContributionSource;
 (function (ContributionSource) {
@@ -26,32 +37,6 @@ export var ContributionSource;
     ContributionSource["Pack"] = "pack";
     ContributionSource["Fixture"] = "fixture";
 })(ContributionSource || (ContributionSource = {}));
-export var ContributionKind;
-(function (ContributionKind) {
-    ContributionKind["Knowledge"] = "knowledge";
-    ContributionKind["Rule"] = "rule";
-    ContributionKind["Path"] = "path";
-    ContributionKind["PathConvention"] = "path-convention";
-    ContributionKind["Template"] = "template";
-    ContributionKind["Pipeline"] = "pipeline";
-    ContributionKind["Preset"] = "preset";
-    ContributionKind["Boundary"] = "boundary";
-    ContributionKind["ScaffoldPattern"] = "scaffold-pattern";
-    ContributionKind["Policy"] = "policy";
-    ContributionKind["Construct"] = "construct";
-    ContributionKind["Playbook"] = "playbook";
-    ContributionKind["SearchTuning"] = "search-tuning";
-    ContributionKind["FeedbackRule"] = "feedback-rule";
-    ContributionKind["Decision"] = "decision";
-    ContributionKind["ContractTemplate"] = "contract-template";
-    ContributionKind["MigrationProfile"] = "migration-profile";
-    ContributionKind["ContextTest"] = "context-test";
-    ContributionKind["AgentTest"] = "agent-test";
-    ContributionKind["Helper"] = "helper";
-    ContributionKind["TaskRoutingHint"] = "task-routing-hint";
-    ContributionKind["Convention"] = "convention";
-    ContributionKind["Docs"] = "docs";
-})(ContributionKind || (ContributionKind = {}));
 export var ConflictKind;
 (function (ConflictKind) {
     ConflictKind["DuplicateIdSameKind"] = "duplicate-id-same-kind";
@@ -64,7 +49,12 @@ export var ConflictKind;
     ConflictKind["IncompatibleSchema"] = "incompatible-schema";
     ConflictKind["MissingLoader"] = "missing-loader";
 })(ConflictKind || (ConflictKind = {}));
-const KIND_TO_SLOT = {
+/**
+ * THE contribution kind → manifest slot table. A `Record` over the enum: a kind
+ * without a slot is a compile error, and the r76 census holds every
+ * loader-backed `CONTRIBUTION_FILE_KEYS` slot to exactly one kind here.
+ */
+export const CONTRIBUTION_KIND_SLOT = Object.freeze({
     [ContributionKind.Knowledge]: 'knowledgeFiles',
     [ContributionKind.Rule]: 'ruleFiles',
     [ContributionKind.Path]: 'pathFiles',
@@ -76,6 +66,7 @@ const KIND_TO_SLOT = {
     [ContributionKind.ScaffoldPattern]: 'scaffoldPatternFiles',
     [ContributionKind.Policy]: 'policyCheckFiles',
     [ContributionKind.Construct]: 'constructFiles',
+    [ContributionKind.ConstructFacet]: 'constructFacetFiles',
     [ContributionKind.Playbook]: 'playbookFiles',
     [ContributionKind.SearchTuning]: 'searchTuningFiles',
     [ContributionKind.FeedbackRule]: 'feedbackRuleFiles',
@@ -86,8 +77,35 @@ const KIND_TO_SLOT = {
     [ContributionKind.AgentTest]: 'agentTestFiles',
     [ContributionKind.Helper]: 'helperFiles',
     [ContributionKind.TaskRoutingHint]: 'taskRoutingHintFiles',
+    [ContributionKind.RegistrationHint]: 'registrationHintFiles',
     [ContributionKind.Convention]: 'conventionFiles',
     [ContributionKind.Docs]: 'docsFiles',
+    [ContributionKind.DelegateRecipe]: 'delegateRecipeFiles',
+    [ContributionKind.FrameworkExtractor]: 'frameworkExtractorFiles',
+    [ContributionKind.WiringRule]: 'wiringRuleFiles',
+    [ContributionKind.Registry]: 'registryFiles',
+    [ContributionKind.RegistrationIdiom]: 'registrationGraphFiles',
+    [ContributionKind.PolicyRule]: 'policyRuleFiles',
+    [ContributionKind.ReusePrimitive]: 'reusePrimitiveFiles',
+    [ContributionKind.Baseline]: 'baselineFiles',
+    [ContributionKind.GeneratedArtifact]: 'generatedArtifactFiles',
+    [ContributionKind.DocReference]: 'docReferenceFiles',
+});
+/** The contribution kind a manifest slot's files are loaded as, or `undefined` for a slot no loader reads. */
+export function contributionKindForSlot(slot) {
+    for (const [kind, s] of Object.entries(CONTRIBUTION_KIND_SLOT))
+        if (s === slot)
+            return kind;
+    return undefined;
+}
+/**
+ * A slot whose files are loaded under a DIFFERENT kind: `pathConventionFiles`
+ * feed the path loader, `docsFiles` the markdown knowledge loader. A file the
+ * other kind handled structurally is handled for this slot too.
+ */
+const ALSO_HANDLED_BY = {
+    [ContributionKind.PathConvention]: [ContributionKind.Path],
+    [ContributionKind.Docs]: [ContributionKind.Knowledge],
 };
 function safeRead(file) {
     try {
@@ -99,9 +117,9 @@ function safeRead(file) {
 }
 /**
  * Lightweight static extractor — looks for `id: '...'` and `title: '...'`
- * occurrences inside a contribution file. This works without importing the
- * file (the engine already has dedicated loaders that do this; the inventory
- * is intentionally a fast surface-level reporter that doesn't re-run them).
+ * occurrences inside a contribution file. Used ONLY where no loader answered
+ * for a file; its ids are tagged `regex-fallback` and never reported as a
+ * verified contribution.
  */
 function extractIdsFromFile(content) {
     const entries = [];
@@ -135,21 +153,25 @@ function buildContribFileEntries(inspection) {
             { kind: ContributionKind.Pipeline, relCandidates: ['pipelines.ts'] },
             { kind: ContributionKind.ScaffoldPattern, relCandidates: ['scaffold-patterns.ts'] },
             { kind: ContributionKind.Policy, relCandidates: ['policies.ts'] },
+            { kind: ContributionKind.Construct, relCandidates: ['constructs.ts'] },
+            { kind: ContributionKind.ConstructFacet, relCandidates: ['construct-facets.ts'] },
             { kind: ContributionKind.Playbook, relCandidates: ['playbooks.ts'] },
             { kind: ContributionKind.SearchTuning, relCandidates: ['search-tuning.ts'] },
             { kind: ContributionKind.FeedbackRule, relCandidates: ['feedback-rules.ts'] },
             { kind: ContributionKind.Decision, relCandidates: ['decisions.ts'] },
+            { kind: ContributionKind.ContextTest, relCandidates: ['context-tests.ts'] },
             { kind: ContributionKind.AgentTest, relCandidates: ['agent-tests.ts'] },
             { kind: ContributionKind.ContractTemplate, relCandidates: ['contract-templates.ts'] },
             { kind: ContributionKind.MigrationProfile, relCandidates: ['migration-profiles.ts'] },
             { kind: ContributionKind.Helper, relCandidates: ['helpers.ts'] },
             { kind: ContributionKind.TaskRoutingHint, relCandidates: ['task-routing-hints.ts'] },
+            { kind: ContributionKind.RegistrationHint, relCandidates: ['registration-hints.ts'] },
             { kind: ContributionKind.Convention, relCandidates: ['conventions.ts'] },
         ];
         for (const c of localConventions) {
             const files = c.relCandidates
                 .map((rel) => nodePath.join(dir, rel))
-                .filter((abs) => existsSync(abs));
+                .filter((abs) => safeRead(abs) !== null);
             if (files.length > 0) {
                 out.push({ kind: c.kind, files, source: ContributionSource.Local });
             }
@@ -159,11 +181,11 @@ function buildContribFileEntries(inspection) {
     for (const pack of inspection.packs.validPacks ?? []) {
         const contributions = (pack.manifest?.contributions ?? {});
         for (const kind of Object.values(ContributionKind)) {
-            const slot = KIND_TO_SLOT[kind];
+            const slot = CONTRIBUTION_KIND_SLOT[kind];
             const rels = contributions[slot];
             if (!rels || rels.length === 0)
                 continue;
-            const abs = rels.map((rel) => nodePath.resolve(pack.packageRoot, rel)).filter((f) => existsSync(f));
+            const abs = rels.map((rel) => nodePath.resolve(pack.packageRoot, rel)).filter((f) => safeRead(f) !== null);
             out.push({
                 kind,
                 packageName: pack.packageName,
@@ -175,16 +197,33 @@ function buildContribFileEntries(inspection) {
     }
     return out;
 }
+/**
+ * Where a registry `sourceFile` lives, as a project-relative path. Registries
+ * report a PACK-relative path for pack entries and a PROJECT-relative one for
+ * local entries; resolving either against `process.cwd()` (as this used to)
+ * made the inventory cwd-dependent and broke nested-id suppression.
+ */
+function sourceFileResolver(inspection) {
+    const projectRoot = inspection.projectRoot;
+    const packRoots = new Map();
+    for (const p of inspection.packs.validPacks ?? [])
+        packRoots.set(p.packageName, p.packageRoot);
+    return (file, packageName) => {
+        const abs = nodePath.isAbsolute(file)
+            ? file
+            : nodePath.resolve((packageName && packRoots.get(packageName)) || projectRoot, file);
+        return nodePath.relative(projectRoot, abs) || abs;
+    };
+}
 async function loadStructuralEntries(inspection) {
     const byKindAndFile = new Map();
     const structuralFiles = new Map();
     const structuralIds = new Map();
-    const projectRoot = inspection.projectRoot;
-    const rel = (abs) => abs ? nodePath.relative(projectRoot, abs) || abs : undefined;
+    const toRel = sourceFileResolver(inspection);
     const record = (kind, file, entry) => {
         if (!file)
             return;
-        const relPath = rel(file);
+        const relPath = toRel(file, entry.packageName);
         const kindKey = kind;
         let m = byKindAndFile.get(kindKey);
         if (!m) {
@@ -213,12 +252,16 @@ async function loadStructuralEntries(inspection) {
         const pkg = entry.packageName ?? '__local__';
         idSet.add(`${pkg}:${entry.id}`);
     };
+    /** Source attribution for an inspection-backed id (knowledge/rule/path/template/pipeline/preset/boundary). */
+    const attribution = (src) => src?.type === 'pack'
+        ? { source: ContributionSource.Pack, ...(src.packageName ? { packageName: src.packageName } : {}) }
+        : { source: ContributionSource.Local };
     // Knowledge / rules / paths / templates / pipelines come from inspection.
     for (const k of inspection.knowledgeEntries) {
         record(ContributionKind.Knowledge, k.source?.origin, {
             id: k.id,
             ...(k.title ? { title: k.title } : {}),
-            source: ContributionSource.Local,
+            ...attribution(inspection.entrySources.get(k.id)),
         });
     }
     try {
@@ -227,7 +270,7 @@ async function loadStructuralEntries(inspection) {
             record(ContributionKind.Rule, r.source?.origin, {
                 id: r.id,
                 ...(r.title ? { title: r.title } : {}),
-                source: ContributionSource.Local,
+                ...attribution(inspection.entrySources.get(r.id)),
             });
         }
     }
@@ -240,7 +283,7 @@ async function loadStructuralEntries(inspection) {
             record(ContributionKind.Path, p.source?.origin, {
                 id: p.id,
                 ...(p.title ? { title: p.title } : {}),
-                source: ContributionSource.Local,
+                ...attribution(inspection.entrySources.get(p.id)),
             });
         }
     }
@@ -250,10 +293,11 @@ async function loadStructuralEntries(inspection) {
     try {
         const templates = inspection.templateRegistry?.list?.() ?? [];
         for (const t of templates) {
-            record(ContributionKind.Template, t.source?.origin, {
+            const src = inspection.templateSources.get(t.id);
+            record(ContributionKind.Template, src?.file, {
                 id: t.id,
                 ...(t.description ? { title: t.description } : {}),
-                source: ContributionSource.Local,
+                ...attribution(src),
             });
         }
     }
@@ -263,151 +307,77 @@ async function loadStructuralEntries(inspection) {
     try {
         const pipelines = inspection.pipelineRegistry?.list?.() ?? [];
         for (const p of pipelines) {
-            record(ContributionKind.Pipeline, p.source?.origin, {
-                id: p.id,
-                ...(p.title ? { title: p.title } : {}),
-                source: ContributionSource.Local,
-            });
-        }
-    }
-    catch {
-        // ignore
-    }
-    // Playbooks — these were a major source of nested step.id false positives.
-    try {
-        const playbooks = await listPlaybooks(inspection);
-        for (const p of playbooks) {
-            record(ContributionKind.Playbook, p.sourceFile, {
+            const src = inspection.pipelineSources.get(p.id);
+            record(ContributionKind.Pipeline, src?.file ?? p.source?.origin, {
                 id: p.id,
                 ...(p.title ? { title: p.title } : {}),
-                source: p.source === 'pack' ? ContributionSource.Pack : ContributionSource.Local,
-                ...(p.packageName ? { packageName: p.packageName } : {}),
-            });
-        }
-    }
-    catch {
-        // ignore
-    }
-    // Conventions, helpers, routing hints, registration hints, contract templates,
-    // migration profiles — all loader-backed today.
-    try {
-        const entries = await listConventions(inspection);
-        for (const e of entries) {
-            record(ContributionKind.Convention, e.sourceFile, {
-                id: e.convention.id,
-                ...(e.convention.title
-                    ? { title: e.convention.title }
-                    : {}),
-                source: e.source === 'pack'
-                    ? ContributionSource.Pack
-                    : ContributionSource.Local,
-                ...(e.packageName ? { packageName: e.packageName } : {}),
+                ...attribution(src),
             });
         }
     }
     catch {
         // ignore
     }
+    // Presets and boundary rules: inspection-time registries with a source map.
+    // A built-in preset is not a contribution (its source file reads `builtin`).
     try {
-        const builtIns = HELPERS;
-        for (const h of builtIns) {
-            // Built-in helpers don't have a file; skip the structural mapping.
-            void h;
-        }
-        const packHelpers = await listPackHelpers(inspection);
-        for (const e of packHelpers) {
-            record(ContributionKind.Helper, e.sourceFile, {
-                id: e.helper.id,
-                ...(e.helper.description
-                    ? { title: e.helper.description }
-                    : {}),
-                source: ContributionSource.Pack,
-                ...(e.packageName ? { packageName: e.packageName } : {}),
-            });
-        }
-    }
-    catch {
-        // ignore
-    }
-    try {
-        const entries = await listTaskRoutingHints(inspection);
-        for (const e of entries) {
-            record(ContributionKind.TaskRoutingHint, e.sourceFile, {
-                id: e.hint.id,
-                ...(e.hint.title ? { title: e.hint.title } : {}),
-                source: e.source === 'pack'
-                    ? ContributionSource.Pack
-                    : ContributionSource.Local,
-                ...(e.packageName ? { packageName: e.packageName } : {}),
-            });
+        for (const p of inspection.presetRegistry?.list?.() ?? []) {
+            const src = inspection.presetSources.get(p.id);
+            if (!src?.file || src.file === 'builtin')
+                continue;
+            record(ContributionKind.Preset, src.file, { id: p.id, ...(p.title ? { title: p.title } : {}), ...attribution(src) });
         }
     }
     catch {
         // ignore
     }
-    // Registration hints don't have a dedicated `ContributionKind` today — they
-    // ship through templates' metadata + the registration-hint registry — so
-    // we deliberately skip them in the structural map. The self-config doctor
-    // surfaces broken registration-hint refs via its own check.
-    await Promise.resolve();
-    void listRegistrationHints;
     try {
-        const pair = await loadAllContractTemplates(inspection);
-        for (const e of pair.entries) {
-            record(ContributionKind.ContractTemplate, e.sourceFile, {
-                id: e.template.id,
-                ...(e.template.title
-                    ? { title: e.template.title }
-                    : {}),
-                source: e.source === 'pack'
-                    ? ContributionSource.Pack
-                    : ContributionSource.Local,
-                ...(e.packageName ? { packageName: e.packageName } : {}),
-            });
+        for (const r of inspection.boundaryRegistry?.list?.() ?? []) {
+            const src = inspection.boundarySources.get(r.id);
+            if (!src?.file)
+                continue;
+            record(ContributionKind.Boundary, src.file, { id: r.id, ...(r.title ? { title: r.title } : {}), ...attribution(src) });
         }
     }
     catch {
         // ignore
     }
-    try {
-        const profiles = await listMigrationProfilesFromPacks(inspection);
-        for (const p of profiles) {
-            record(ContributionKind.MigrationProfile, p.sourceFile, {
-                id: p.id,
-                ...(p.title ? { title: p.title } : {}),
-                source: ContributionSource.Pack,
-                ...(p.packageName ? { packageName: p.packageName } : {}),
-            });
-        }
-    }
-    catch {
-        // ignore
+    // Every REGISTRY kind — helpers, conventions, routing / registration hints,
+    // contract templates, migration profiles, scaffold patterns, playbooks,
+    // constructs + facets, search tuning, decisions, policy checks, feedback
+    // rules, tests, delegate recipes, framework extractors, the gate planes — in
+    // ONE run of THE registry-outcome table, which also reports what each loader
+    // refused and which files failed to load.
+    const outcomes = await collectRegistryOutcomes(inspection);
+    for (const a of outcomes.accepted) {
+        record(a.kind, a.file, {
+            id: a.id,
+            ...(a.title ? { title: a.title } : {}),
+            source: a.packageName ? ContributionSource.Pack : ContributionSource.Local,
+            ...(a.packageName ? { packageName: a.packageName } : {}),
+        });
     }
     return {
         byKindAndFile: byKindAndFile,
         structuralFiles: structuralFiles,
         structuralIds: structuralIds,
+        loadFailures: outcomes.loadFailures,
+        rejections: outcomes.rejections,
     };
 }
 /**
- * Build the inventory. Read-only. Never imports pack code beyond the
- * registry loaders that already do.
- *
- * Structural-first extraction. For kinds with a dedicated loader, the
- * inventory uses the loader's authoritative ids and **suppresses the
- * regex fallback** for those same source files. This eliminates the
- * nested-step-id false positives that previously produced duplicate /
- * conflict noise.
+ * Build the inventory WITHOUT consulting the structural loaders — a regex-only
+ * compatibility wrapper. Every regex id is marked `warning`
+ * ("unverified: loader not consulted") unless the inspection-time loader
+ * already imported that file cleanly; known load failures are still `error`.
+ * Prefer {@link buildPackContributionsInventoryAsync}.
  */
 export function buildPackContributionsInventory(inspection) {
     return buildPackContributionsInventorySync(inspection, null);
 }
 /**
- * Async variant that loads structural per-kind entries first.
- *
- * Production callers should prefer this over the sync wrapper since it
- * provides the noise-free output. The sync wrapper exists for backward
- * compatibility with callers that haven't been awaited yet.
+ * The inventory with structural per-kind entries loaded first — the
+ * noise-free, honest variant every surface should use.
  */
 export async function buildPackContributionsInventoryAsync(inspection) {
     const structural = await loadStructuralEntries(inspection);
@@ -416,13 +386,53 @@ export async function buildPackContributionsInventoryAsync(inspection) {
 function buildPackContributionsInventorySync(inspection, structural) {
     const entriesByKind = {};
     const entries = [];
+    const conflicts = [];
     const fileGroups = buildContribFileEntries(inspection);
+    const failures = collectContributionLoadFailures(inspection, structural?.loadFailures ?? []);
+    // THE rejection channel: inspection-time loaders ∪ registry loaders.
+    const rejections = collectContributionRejections(inspection, structural?.rejections ?? []);
+    const rejectedIdsByFile = new Map();
+    for (const r of rejections) {
+        if (r.entryId === undefined)
+            continue;
+        const m = rejectedIdsByFile.get(r.file) ?? new Map();
+        if (!m.has(r.entryId))
+            m.set(r.entryId, r);
+        rejectedIdsByFile.set(r.file, m);
+    }
+    // THE files a loader READ, per kind (async only): every file it accepted an
+    // entry from AND every file it refused an entry of. The regex never runs on
+    // a file its loader already judged — a file whose every entry was rejected
+    // used to be scraped, its refused ids counted as contributions (`By kind`,
+    // `totals`, the header) and grouped across packs into a false error-level
+    // duplicate (round 12 review, A-2).
+    const judgedFiles = new Map();
+    if (structural) {
+        for (const [kindKey, files] of structural.structuralFiles)
+            judgedFiles.set(kindKey, new Set(files));
+        for (const r of rejections) {
+            const rel = nodePath.relative(inspection.projectRoot, r.file) || r.file;
+            const set = judgedFiles.get(r.kind) ?? new Set();
+            set.add(rel);
+            judgedFiles.set(r.kind, set);
+        }
+    }
+    const scrapedByFile = new Map();
+    const failedFilesReported = new Set();
+    // Files the inspection-time loaders imported cleanly (used by the sync wrapper).
+    const loadedOk = new Set((inspection.loaderDiagnostics ?? [])
+        .filter((d) => d.status === 'ok')
+        .map((d) => nodePath.resolve(d.filePath)));
+    const push = (entry) => {
+        (entriesByKind[entry.kind] ??= []).push(entry);
+        entries.push(entry);
+    };
     // First, emit structural entries (authoritative ids).
     if (structural) {
         for (const [kindKey, files] of structural.byKindAndFile) {
             for (const [relPath, list] of files) {
                 for (const s of list) {
-                    const entry = {
+                    push({
                         kind: kindKey,
                         id: s.id,
                         ...(s.title ? { title: s.title } : {}),
@@ -432,51 +442,68 @@ function buildPackContributionsInventorySync(inspection, structural) {
                         validation: 'ok',
                         extractionMode: 'structural',
                         confidence: 'high',
-                    };
-                    (entriesByKind[kindKey] ??= []).push(entry);
-                    entries.push(entry);
+                    });
                 }
             }
         }
     }
     const ingestFile = (group, file) => {
-        const rel = nodePath.relative(inspection.projectRoot, file) || file;
-        // Skip regex extraction when the structural loader already covered
-        // this (kind, file) pair. Otherwise nested step.id / anchor.id / sub-object
-        // ids re-appear as top-level contribution ids, producing duplicate noise.
-        const handled = structural?.structuralFiles.get(group.kind)?.has(rel);
-        if (handled)
+        const abs = nodePath.resolve(file);
+        const rel = nodePath.relative(inspection.projectRoot, abs) || abs;
+        // Skip regex extraction when a loader already READ this (kind, file) pair
+        // — accepted or refused an entry of it. Otherwise nested step.id /
+        // anchor.id / sub-object ids re-appear as top-level contribution ids, and a
+        // fully-rejected file's refused ids read as contributions.
+        const handledKinds = [group.kind, ...(ALSO_HANDLED_BY[group.kind] ?? [])];
+        if (handledKinds.some((k) => judgedFiles.get(k)?.has(rel)))
             return;
+        const failure = failures.get(abs);
+        const src = {
+            source: group.source,
+            ...(group.packageName ? { packageName: group.packageName } : {}),
+            sourceFile: rel,
+        };
+        if (failure && !failedFilesReported.has(abs)) {
+            failedFilesReported.add(abs);
+            conflicts.push({
+                kind: ConflictKind.InvalidContribution,
+                contributionKind: group.kind,
+                id: rel,
+                sources: [src],
+                severity: 'error',
+                message: `${rel} failed to load (${failure.message}) — nothing in it takes effect; any id listed for it was scraped by regex.`,
+                nextCommand: group.packageRoot
+                    ? `shrk packs release-check ${nodePath.relative(inspection.projectRoot, group.packageRoot) || '.'}`
+                    : 'shrk doctor',
+            });
+        }
         const content = safeRead(file);
         if (content === null) {
-            const entry = {
+            push({
                 kind: group.kind,
                 id: rel,
-                source: group.source,
-                ...(group.packageName ? { packageName: group.packageName } : {}),
-                sourceFile: rel,
+                ...src,
                 validation: 'error',
                 validationMessage: 'file unreadable',
-            };
-            (entriesByKind[group.kind] ??= []).push(entry);
-            entries.push(entry);
+            });
             return;
         }
         const extracted = extractIdsFromFile(content);
+        const rejectedHere = rejectedIdsByFile.get(abs);
         if (extracted.length === 0) {
-            const entry = {
+            push({
                 kind: group.kind,
                 id: rel,
-                source: group.source,
-                ...(group.packageName ? { packageName: group.packageName } : {}),
-                sourceFile: rel,
-                validation: 'warning',
-                validationMessage: 'no `id:` extracted; loader may still see entries',
+                ...src,
+                validation: failure || rejectedHere ? 'error' : 'warning',
+                validationMessage: failure
+                    ? `file failed to load (${failure.message})`
+                    : rejectedHere
+                        ? 'every entry the file declares was rejected by its loader (see rejections)'
+                        : 'no `id:` extracted; loader may still see entries',
                 extractionMode: 'file-only',
                 confidence: 'low',
-            };
-            (entriesByKind[group.kind] ??= []).push(entry);
-            entries.push(entry);
+            });
             return;
         }
         // Skip regex entries whose (kind, packageName||local, id) triple
@@ -488,24 +515,48 @@ function buildPackContributionsInventorySync(inspection, structural) {
         for (const ex of extracted) {
             if (idsHandled && idsHandled.has(`${groupPkg}:${ex.id}`))
                 continue;
-            const entry = {
+            const rejection = rejectedHere?.get(ex.id);
+            let validation;
+            let validationMessage;
+            if (failure) {
+                validation = 'error';
+                validationMessage = `file failed to load (${failure.message}); id scraped by regex — this contribution does NOT take effect`;
+                (scrapedByFile.get(abs) ?? scrapedByFile.set(abs, []).get(abs)).push(ex.id);
+            }
+            else if (rejection) {
+                // The loader read this entry and REFUSED it — never `ok`, never merely
+                // unverified. With the loaders consulted it is in `rejections`, and a
+                // refused id is no contribution row at all (round 12 review, A-2).
+                if (structural)
+                    continue;
+                validation = 'error';
+                validationMessage = `rejected by the ${rejection.kind} loader — ${rejection.reasons.join('; ')}; this contribution does NOT take effect`;
+            }
+            else if (!structural) {
+                validation = loadedOk.has(abs) ? 'ok' : 'warning';
+                validationMessage = loadedOk.has(abs)
+                    ? undefined
+                    : 'unverified: loader not consulted (use the async inventory)';
+            }
+            else {
+                // Every kind is loader-backed (round 12): a regex id means the loader
+                // returned no entry for it — unverified, never `ok`.
+                validation = 'warning';
+                validationMessage = 'regex-derived; the loader returned no entries for this file';
+            }
+            push({
                 kind: group.kind,
                 id: ex.id,
                 ...(ex.title ? { title: ex.title } : {}),
-                source: group.source,
-                ...(group.packageName ? { packageName: group.packageName } : {}),
-                sourceFile: rel,
-                validation: 'ok',
+                ...src,
+                validation,
+                ...(validationMessage ? { validationMessage } : {}),
                 // Regex-based id extraction can pick up nested step.id / anchor.id /
                 // ref.id values. Tag these entries clearly so the conflict detector
-                // downgrades same-file collisions to info. The structural loader is
-                // preferred where available; this fallback fires only for kinds
-                // without a dedicated registry.
+                // downgrades same-file collisions to info.
                 extractionMode: 'regex-fallback',
-                confidence: 'medium',
-            };
-            (entriesByKind[group.kind] ??= []).push(entry);
-            entries.push(entry);
+                confidence: failure ? 'low' : 'medium',
+            });
         }
     };
     for (const group of fileGroups) {
@@ -515,10 +566,14 @@ function buildPackContributionsInventorySync(inspection, structural) {
     const totals = {};
     for (const [kind, list] of Object.entries(entriesByKind))
         totals[kind] = list.length;
-    const conflicts = [];
     for (const [kind, list] of Object.entries(entriesByKind)) {
         const byId = new Map();
         for (const e of list) {
+            // An id that does not take effect — scraped from a file that failed to
+            // load, or refused by its loader — cannot collide at runtime: its own
+            // load failure / rejection is already the error (round 12 review, A-2).
+            if (e.validation === 'error')
+                continue;
             const arr = byId.get(e.id) ?? [];
             arr.push(e);
             byId.set(e.id, arr);
@@ -534,34 +589,27 @@ function buildPackContributionsInventorySync(inspection, structural) {
             // (informational; the loader behavior is documented per-kind).
             const hasLocal = arr.some((e) => e.source === ContributionSource.Local);
             const hasPack = arr.some((e) => e.source === ContributionSource.Pack);
+            const sources = arr.map((e) => {
+                const s = {
+                    source: e.source,
+                };
+                if (e.packageName)
+                    s.packageName = e.packageName;
+                if (e.sourceFile)
+                    s.sourceFile = e.sourceFile;
+                return s;
+            });
             if (hasLocal && hasPack) {
                 conflicts.push({
                     kind: ConflictKind.ShadowedPackConfig,
                     contributionKind: kind,
                     id,
-                    sources: arr.map((e) => {
-                        const src = {
-                            source: e.source,
-                        };
-                        if (e.packageName)
-                            src.packageName = e.packageName;
-                        if (e.sourceFile)
-                            src.sourceFile = e.sourceFile;
-                        return src;
-                    }),
+                    sources,
                     severity: 'info',
                     message: `Local "${kind}" "${id}" shadows pack contribution. Local entries win on duplicate ids.`,
                 });
             }
             else {
-                // Downgrade conflicts that come from a single source file
-                // when ALL participating entries are regex-fallback extractions.
-                // These are almost certainly nested `id:` fields (e.g.
-                // playbook.steps[].id, pipeline.steps[].id) masquerading as
-                // separate top-level contribution ids.
-                const allRegexFallback = arr.every((e) => e.extractionMode === 'regex-fallback');
-                const sourceFiles = new Set(arr.map((e) => e.sourceFile).filter((s) => Boolean(s)));
-                const singleSourceFile = sourceFiles.size === 1;
                 // Self-acknowledged false positive: when ALL participating entries come
                 // from a SINGLE source file via regex fallback, the "duplicate" is
                 // almost certainly nested `id:` fields (playbook.steps[].id /
@@ -569,22 +617,15 @@ function buildPackContributionsInventorySync(inspection, structural) {
                 // contribution ids. Don't emit noise for it — a genuine duplicate would
                 // span multiple files or include a non-regex-fallback entry and still
                 // surface as an error below.
-                if (allRegexFallback && singleSourceFile)
+                const allRegexFallback = arr.every((e) => e.extractionMode === 'regex-fallback');
+                const sourceFiles = new Set(arr.map((e) => e.sourceFile).filter((s) => Boolean(s)));
+                if (allRegexFallback && sourceFiles.size === 1)
                     continue;
                 conflicts.push({
                     kind: conflictKind,
                     contributionKind: kind,
                     id,
-                    sources: arr.map((e) => {
-                        const src = {
-                            source: e.source,
-                        };
-                        if (e.packageName)
-                            src.packageName = e.packageName;
-                        if (e.sourceFile)
-                            src.sourceFile = e.sourceFile;
-                        return src;
-                    }),
+                    sources,
                     severity: 'error',
                     message: `Duplicate "${kind}" id "${id}" loaded from ${arr.length} sources.`,
                     nextCommand: `shrk packs contributions --json | jq '.entries[] | select(.id=="${id}" and .kind=="${kind}")'`,
@@ -592,59 +633,41 @@ function buildPackContributionsInventorySync(inspection, structural) {
             }
         }
     }
-    // Stale-signature warning: surfaced as a conflict so a single doctor view
-    // can highlight unsigned-by-secret manifests.
+    // Stale-signature: read from THE pack-asset freshness authority (content
+    // digests recorded at sign time), never from mtimes. Dev-signed packs are
+    // re-staled by every local build and load fine locally, so their divergence
+    // is not a conflict (mirrors pack-signature-status's dev downgrade).
     for (const pack of inspection.packs.validPacks ?? []) {
-        const sig = pack.manifest?.signature;
-        if (!sig)
+        if (!pack.manifest?.signature)
             continue;
-        // Dev-signed packs are re-staled by every local build and load fine
-        // locally, so suppress the stale-signature conflict for them (mirrors the
-        // dev-aware downgrade in pack-signature-status.ts). Production signed packs
-        // still surface as stale.
-        if (sig.dev === true)
+        const freshness = detectPackAssetFreshness(pack);
+        if (freshness.signature.state !== 'diverged' || freshness.signature.dev)
             continue;
-        // The loader already validates HMAC strictly; we only surface stale
-        // when the manifest content has obviously been edited without re-signing.
-        // Heuristic: signature timestamp older than any contribution file mtime.
-        let staleSummary = null;
-        try {
-            const sigMs = new Date(sig.signedAt).getTime();
-            const contributions = pack.manifest?.contributions ?? {};
-            for (const slot of Object.values(KIND_TO_SLOT)) {
-                const rels = contributions[slot] ?? [];
-                for (const rel of rels) {
-                    const abs = nodePath.resolve(pack.packageRoot, rel);
-                    try {
-                        const stat = statSync(abs);
-                        if (stat.mtimeMs > sigMs + 1000) {
-                            staleSummary = `${rel} (mtime ${new Date(stat.mtimeMs).toISOString()}) is newer than signature (${sig.signedAt})`;
-                            break;
-                        }
-                    }
-                    catch {
-                        continue;
-                    }
-                }
-                if (staleSummary)
-                    break;
-            }
-        }
-        catch {
-            // ignore
-        }
-        if (staleSummary) {
-            conflicts.push({
-                kind: ConflictKind.StaleSignature,
-                contributionKind: ContributionKind.Docs,
-                id: pack.packageName,
-                sources: [{ source: ContributionSource.Pack, packageName: pack.packageName, sourceFile: pack.packageRoot }],
-                severity: 'warning',
-                message: `Pack ${pack.packageName} signature is stale: ${staleSummary}`,
-                nextCommand: `SHARKCRAFT_PACK_SECRET=<secret> shrk packs sign ${nodePath.relative(inspection.projectRoot, pack.packageRoot)}`,
-            });
-        }
+        conflicts.push({
+            kind: ConflictKind.StaleSignature,
+            contributionKind: ContributionKind.Docs,
+            id: pack.packageName,
+            sources: [{ source: ContributionSource.Pack, packageName: pack.packageName, sourceFile: pack.packageRoot }],
+            severity: 'warning',
+            message: describePackAssetFreshness(freshness).signature ?? `Pack ${pack.packageName} signature is stale.`,
+            nextCommand: `SHARKCRAFT_PACK_SECRET=<secret> shrk packs sign ${nodePath.relative(inspection.projectRoot, pack.packageRoot)}`,
+        });
     }
+    const extractionTotals = {
+        structural: entries.filter((e) => e.extractionMode === 'structural').length,
+        regexFallback: entries.filter((e) => e.extractionMode === 'regex-fallback').length,
+        fileOnly: entries.filter((e) => e.extractionMode === 'file-only').length,
+        rejected: rejections.length,
+    };
+    const loadFailures = [...failures.values()]
+        .map((f) => ({
+        file: nodePath.relative(inspection.projectRoot, f.file) || f.file,
+        kind: f.kind,
+        ...(f.packageName ? { packageName: f.packageName } : {}),
+        message: f.message,
+        scrapedIds: [...(scrapedByFile.get(f.file) ?? [])],
+    }))
+        .sort((a, b) => a.file.localeCompare(b.file));
     return {
         schema: PACK_CONTRIBUTIONS_INVENTORY_SCHEMA,
         generatedAt: new Date().toISOString(),
@@ -659,20 +682,93 @@ function buildPackContributionsInventorySync(inspection, structural) {
             root: p.packageRoot,
             signaturePresent: Boolean(p.manifest?.signature),
         })),
+        extractionTotals,
+        loadFailures,
+        rejections: rejections.map((r) => ({
+            file: nodePath.relative(inspection.projectRoot, r.file) || r.file,
+            kind: r.kind,
+            ...(r.packageName ? { packageName: r.packageName } : {}),
+            index: r.index,
+            ...(r.exportName ? { exportName: r.exportName } : {}),
+            ...(r.entryId !== undefined ? { entryId: r.entryId } : {}),
+            reasons: r.reasons,
+            cause: r.cause,
+        })),
+        mode: structural ? 'async' : 'sync',
     };
 }
+/** Per-kind extraction-mode counts over `entries` (so a filtered view renders its own numbers). */
+function modeCountsByKind(entries) {
+    const out = new Map();
+    for (const e of entries) {
+        const c = out.get(e.kind) ?? { total: 0, structural: 0, regexFallback: 0, fileOnly: 0 };
+        c.total += 1;
+        if (e.extractionMode === 'structural')
+            c.structural += 1;
+        else if (e.extractionMode === 'regex-fallback')
+            c.regexFallback += 1;
+        else if (e.extractionMode === 'file-only')
+            c.fileOnly += 1;
+        out.set(e.kind, c);
+    }
+    return out;
+}
+function modeClause(c) {
+    const parts = [];
+    if (c.structural > 0)
+        parts.push(`structural ${c.structural}`);
+    if (c.regexFallback > 0)
+        parts.push(`regex-fallback ${c.regexFallback}`);
+    if (c.fileOnly > 0)
+        parts.push(`file-only ${c.fileOnly}`);
+    return parts.length > 0 ? `(${parts.join(' · ')})` : '';
+}
+function extractionLine(entries, rejected) {
+    const s = entries.filter((e) => e.extractionMode === 'structural').length;
+    const r = entries.filter((e) => e.extractionMode === 'regex-fallback').length;
+    const f = entries.filter((e) => e.extractionMode === 'file-only').length;
+    return `${s} structural · ${r} regex-fallback (unverified) · ${f} file-only${rejected > 0 ? ` · ${rejected} REJECTED` : ''}`;
+}
 export function renderInventoryText(inv) {
     const lines = [];
+    const rejections = inv.rejections ?? [];
     lines.push(`=== Pack contributions inventory (${inv.entries.length} entries) ===`);
     lines.push(`  generatedAt   ${inv.generatedAt}`);
     lines.push(`  packs         ${inv.packs.length}`);
     for (const p of inv.packs)
         lines.push(`    • ${p.name}@${p.version} (sig: ${p.signaturePresent ? 'present' : 'absent'})`);
+    lines.push(`  extraction    ${extractionLine(inv.entries, rejections.length)}`);
+    if (inv.mode === 'sync')
+        lines.push('  mode          sync — loaders NOT consulted; regex ids are unverified');
     lines.push('');
     lines.push(`By kind:`);
-    for (const [k, n] of Object.entries(inv.totals).sort())
-        lines.push(`  ${k.padEnd(28)} ${n}`);
+    const byKind = modeCountsByKind(inv.entries);
+    for (const k of [...byKind.keys()].sort()) {
+        const c = byKind.get(k);
+        lines.push(`  ${k.padEnd(28)} ${String(c.total).padStart(4)}  ${modeClause(c)}`.trimEnd());
+    }
     lines.push('');
+    const failures = inv.loadFailures ?? [];
+    if (failures.length > 0) {
+        lines.push(`Load failures (${failures.length}):`);
+        for (const f of failures) {
+            lines.push(`  ✗ ${f.file}  [${f.kind}${f.packageName ? `, ${f.packageName}` : ''}] — ${f.message}`);
+            lines.push(`      regex-scraped ids NOT loaded: ${f.scrapedIds.length > 0 ? f.scrapedIds.join(', ') : '(none)'}`);
+        }
+        lines.push('');
+    }
+    if (rejections.length > 0) {
+        lines.push(`Rejected entries (${rejections.length}) — refused by their loader, NOT in effect:`);
+        let lastFile = '';
+        for (const r of rejections) {
+            if (r.file !== lastFile) {
+                lines.push(`  ✗ ${r.file}  [${r.kind}${r.packageName ? `, ${r.packageName}` : ''}]`);
+                lastFile = r.file;
+            }
+            lines.push(`      ${formatEntryRejection(r)}`);
+        }
+        lines.push('');
+    }
     if (inv.conflicts.length > 0) {
         lines.push(`Conflicts (${inv.conflicts.length}):`);
         for (const c of inv.conflicts.slice(0, 50)) {
@@ -688,6 +784,7 @@ export function renderInventoryText(inv) {
 }
 export function renderInventoryMarkdown(inv) {
     const lines = [];
+    const rejections = inv.rejections ?? [];
     lines.push('# Pack contributions inventory');
     lines.push('');
     lines.push(`- generatedAt: ${inv.generatedAt}`);
@@ -695,12 +792,43 @@ export function renderInventoryMarkdown(inv) {
     for (const p of inv.packs) {
         lines.push(`  - **${p.name}** \`${p.version}\` (signature ${p.signaturePresent ? 'present' : 'absent'})`);
     }
+    lines.push(`- extraction: ${extractionLine(inv.entries, rejections.length)}`);
+    if (inv.mode === 'sync')
+        lines.push('- mode: sync — loaders NOT consulted; regex ids are unverified');
     lines.push('');
     lines.push('## By kind');
-    lines.push('| Kind | Count |');
-    lines.push('| --- | --- |');
-    for (const [k, n] of Object.entries(inv.totals).sort())
-        lines.push(`| \`${k}\` | ${n} |`);
+    lines.push('| Kind | Count | Structural | Regex-fallback | File-only |');
+    lines.push('| --- | --- | --- | --- | --- |');
+    const byKind = modeCountsByKind(inv.entries);
+    for (const k of [...byKind.keys()].sort()) {
+        const c = byKind.get(k);
+        lines.push(`| \`${k}\` | ${c.total} | ${c.structural} | ${c.regexFallback} | ${c.fileOnly} |`);
+    }
+    lines.push('');
+    lines.push('## Load failures');
+    const failures = inv.loadFailures ?? [];
+    if (failures.length === 0) {
+        lines.push('None.');
+    }
+    else {
+        lines.push('| File | Kind | Pack | Error | Regex-scraped ids NOT loaded |');
+        lines.push('| --- | --- | --- | --- | --- |');
+        for (const f of failures) {
+            lines.push(`| \`${f.file}\` | ${f.kind} | ${f.packageName ?? ''} | ${f.message} | ${f.scrapedIds.join(', ')} |`);
+        }
+    }
+    lines.push('');
+    lines.push('## Rejected entries');
+    if (rejections.length === 0) {
+        lines.push('None.');
+    }
+    else {
+        lines.push('| File | Kind | Pack | Entry | Reasons |');
+        lines.push('| --- | --- | --- | --- | --- |');
+        for (const r of rejections) {
+            lines.push(`| \`${r.file}\` | ${r.kind} | ${r.packageName ?? ''} | ${r.entryId !== undefined ? `\`${r.entryId}\`` : '(no id)'} ${r.exportName ?? ''}[${r.index}] | ${r.reasons.join('; ')} |`);
+        }
+    }
     lines.push('');
     lines.push('## Conflicts');
     if (inv.conflicts.length === 0) {
@@ -718,3 +846,32 @@ export function renderInventoryMarkdown(inv) {
 export function selectConflicts(inv) {
     return inv.conflicts;
 }
+/**
+ * Per contribution kind, a pack's declared FILES, ACCEPTED entries and
+ * REJECTED entries — THE projection of this inventory that `packs list`,
+ * `packs get` and MCP `list_packs` / `get_pack` print (round 12, 12.1b), so
+ * a partially-loaded file never looks like a fully-loaded one and every
+ * surface counts what `packs contributions` counts. A kind with nothing
+ * declared, accepted or rejected is absent.
+ */
+export function packEntryCounts(inv, pack) {
+    const out = {};
+    const row = (kind) => (out[kind] ??= { files: 0, accepted: 0, rejected: 0 });
+    for (const slot of CONTRIBUTION_FILE_KEYS) {
+        const n = pack.contributionCounts[slot] ?? 0;
+        if (n === 0)
+            continue;
+        row(contributionKindForSlot(slot) ?? slot).files += n;
+    }
+    for (const e of inv?.entries ?? []) {
+        if (e.packageName !== pack.packageName || e.extractionMode !== 'structural')
+            continue;
+        row(e.kind).accepted += 1;
+    }
+    for (const r of inv?.rejections ?? []) {
+        if (r.packageName !== pack.packageName)
+            continue;
+        row(r.kind).rejected += 1;
+    }
+    return out;
+}