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

package/dist/construct-registry.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { importModuleViaLoader } from '@shrkcrft/core';
+import { importModuleViaLoader, readContributionExport, RejectionCause, } from '@shrkcrft/core';
 export const CONSTRUCT_REGISTRY_SCHEMA = 'sharkcraft.construct-registry/v1';
 const CACHE = new Map();
 function readJsonOrEmpty(file) {
@@ -13,16 +13,41 @@ function readJsonOrEmpty(file) {
         return null;
     }
 }
-async function importDefault(file) {
-    const mod = (await importModuleViaLoader(file));
-    const def = mod.default;
-    if (Array.isArray(def))
-        return def;
-    if (def && typeof def === 'object')
-        return [def];
-    if (Array.isArray(mod.constructs))
-        return mod.constructs;
-    return [];
+async function importList(file) {
+    return readContributionExport(await importModuleViaLoader(file), { namedKeys: ['constructs'] });
+}
+function firstLine(s) {
+    return (s.split('\n')[0] ?? s).trim();
+}
+/**
+ * THE construct acceptance predicate (round 12, 12.1 / 12.1d): a non-empty
+ * string `id` and a string `type` — `[]` means accepted. An id-less construct
+ * used to be dropped silently, and one without `type` was ACCEPTED and then
+ * crashed `constructs list` (`c.type.padEnd`).
+ */
+export function constructRejectionReasons(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return ['(entry): must be an object'];
+    const c = raw;
+    const out = [];
+    if (typeof c.id !== 'string' || c.id.length === 0)
+        out.push('id: must be a non-empty string');
+    if (typeof c.type !== 'string' || c.type.length === 0)
+        out.push('type: must be a non-empty string');
+    return out;
+}
+/**
+ * THE construct-facet SHAPE predicate: `id`, `constructId`, `kind`, `value`,
+ * each a string — `[]` means the shape is accepted. (A well-shaped facet whose
+ * `constructId` names no loaded construct is refused at fold time.)
+ */
+export function constructFacetRejectionReasons(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return ['(entry): must be an object'];
+    const f = raw;
+    return ['id', 'constructId', 'kind', 'value']
+        .filter((k) => typeof f[k] !== 'string')
+        .map((k) => `${k}: must be a string`);
 }
 function localConstructFiles(inspection) {
     const out = [];
@@ -35,11 +60,9 @@ function localConstructFiles(inspection) {
         if (existsSync(full))
             out.push(full);
     }
-    const cfg = inspection.config;
-    if (cfg?.constructFiles) {
-        for (const rel of cfg.constructFiles)
-            out.push(nodePath.join(dir, rel));
-    }
+    // More construct files come from pack manifests (`constructFiles`, loaded
+    // below; docs/constructs.md) — there is no local-config key for them; the
+    // strict config schema rejects one, so a local read here could never run.
     return out;
 }
 function localFacetFiles(inspection) {
@@ -53,49 +76,101 @@ function localFacetFiles(inspection) {
         if (existsSync(full))
             out.push(full);
     }
-    const cfg = inspection.config;
-    if (cfg?.constructFacetFiles) {
-        for (const rel of cfg.constructFacetFiles)
-            out.push(nodePath.join(dir, rel));
-    }
+    // Same for facets: pack manifests carry `constructFacetFiles`; local config
+    // has no such key.
     return out;
 }
-export async function loadConstructs(inspection) {
+/**
+ * Load every local and pack construct (and fold loose facets into them), with
+ * what did not take effect: files that failed to import (they used to be
+ * swallowed — `catch { /* ignore *\/ }` — so a broken `constructs.ts` read as a
+ * smaller registry), and every declared construct / facet the loader refused
+ * (round 12, 12.1).
+ */
+export async function loadConstructsWithIssues(inspection) {
     const cacheKey = `${inspection.projectRoot}:${inspection.packs.validPacks
         .map((p) => p.packageName + '@' + p.packageVersion)
         .join(',')}`;
     const cached = CACHE.get(inspection.projectRoot);
-    if (cached && cached.cacheKey === cacheKey)
-        return cached.list;
+    if (cached && cached.cacheKey === cacheKey) {
+        return {
+            constructs: cached.list,
+            facets: cached.facets,
+            issues: cached.issues,
+            rejected: cached.rejected,
+            facetIssues: cached.facetIssues,
+            facetRejected: cached.facetRejected,
+        };
+    }
     const out = [];
-    // Local definitions.
-    for (const file of localConstructFiles(inspection)) {
+    const constructIssues = [];
+    const constructRejected = [];
+    const facetIssues = [];
+    const facetRejected = [];
+    // Construct files and facet files are two contribution kinds: each keeps its own issues / refusals.
+    let issues = constructIssues;
+    let rejected = constructRejected;
+    const rel = (file) => nodePath.relative(inspection.projectRoot, file) || file;
+    const load = async (file, packageName) => {
         try {
-            const list = await importDefault(file);
-            for (const c of list) {
-                if (!c?.id)
-                    continue;
-                const entry = { ...c, source: 'local' };
-                entry.sourceFile = nodePath.relative(inspection.projectRoot, file);
-                out.push(entry);
-            }
+            return await importList(file);
         }
-        catch {
-            /* ignore — packs are best-effort */
+        catch (e) {
+            issues.push({
+                severity: 'warning',
+                code: 'load-failed',
+                message: `${packageName ? `Pack ${packageName} (${rel(file)})` : `Failed to load ${rel(file)}`}: ${firstLine(e.message ?? String(e))}`,
+                source: file,
+                ...(packageName ? { packageName } : {}),
+            });
+            return null;
         }
+    };
+    const reject = (exp, file, i, raw, reasons, cause = RejectionCause.Invalid) => {
+        const id = raw && typeof raw === 'object' ? raw.id : undefined;
+        rejected.push({
+            file,
+            index: exp.single ? -1 : i,
+            ...(exp.exportName ? { exportName: exp.exportName } : {}),
+            ...(typeof id === 'string' && id.length > 0 ? { entryId: id } : {}),
+            reasons,
+            cause,
+        });
+    };
+    const ingestConstructs = (exp, file, origin) => {
+        exp.items.forEach((c, i) => {
+            const reasons = constructRejectionReasons(c);
+            if (reasons.length > 0) {
+                reject(exp, file, i, c, reasons);
+                return;
+            }
+            out.push({ ...c, ...origin });
+        });
+    };
+    // Local definitions.
+    for (const file of localConstructFiles(inspection)) {
+        const exp = await load(file);
+        if (exp)
+            ingestConstructs(exp, file, { source: 'local', sourceFile: rel(file) });
     }
     // Standalone facet files (folded into matching constructs).
     const looseFacets = [];
-    for (const file of localFacetFiles(inspection)) {
-        try {
-            const list = await importDefault(file);
-            for (const f of list) {
-                looseFacets.push(f);
+    const ingestFacets = (exp, file, packageName) => {
+        exp.items.forEach((f, i) => {
+            const reasons = constructFacetRejectionReasons(f);
+            if (reasons.length > 0) {
+                reject(exp, file, i, f, reasons);
+                return;
             }
-        }
-        catch {
-            /* ignore */
-        }
+            looseFacets.push({ facet: f, exp, file, index: i, ...(packageName ? { packageName } : {}) });
+        });
+    };
+    issues = facetIssues;
+    rejected = facetRejected;
+    for (const file of localFacetFiles(inspection)) {
+        const exp = await load(file);
+        if (exp)
+            ingestFacets(exp, file);
     }
     // Pack contributions.
     for (const pack of inspection.packs.validPacks ?? []) {
@@ -103,59 +178,88 @@ export async function loadConstructs(inspection) {
         const packRoot = pack.packageRoot;
         if (!packRoot)
             continue;
-        for (const rel of contributions.constructFiles ?? []) {
-            const file = nodePath.resolve(packRoot, rel);
-            if (!existsSync(file))
+        issues = constructIssues;
+        rejected = constructRejected;
+        for (const r of contributions.constructFiles ?? []) {
+            const file = nodePath.resolve(packRoot, r);
+            if (!existsSync(file)) {
+                issues.push({
+                    severity: 'warning',
+                    code: 'missing-file',
+                    message: `Pack ${pack.packageName} declares ${r} but the file is missing.`,
+                    source: file,
+                    packageName: pack.packageName,
+                });
                 continue;
-            try {
-                const list = await importDefault(file);
-                for (const c of list) {
-                    if (!c?.id)
-                        continue;
-                    out.push({
-                        ...c,
-                        source: 'pack',
-                        packageName: pack.packageName,
-                        sourceFile: rel,
-                    });
-                }
-            }
-            catch {
-                /* ignore */
             }
+            const exp = await load(file, pack.packageName);
+            if (exp)
+                ingestConstructs(exp, file, { source: 'pack', packageName: pack.packageName, sourceFile: r });
         }
-        for (const rel of contributions.constructFacetFiles ?? []) {
-            const file = nodePath.resolve(packRoot, rel);
-            if (!existsSync(file))
+        issues = facetIssues;
+        rejected = facetRejected;
+        for (const r of contributions.constructFacetFiles ?? []) {
+            const file = nodePath.resolve(packRoot, r);
+            if (!existsSync(file)) {
+                issues.push({
+                    severity: 'warning',
+                    code: 'missing-file',
+                    message: `Pack ${pack.packageName} declares ${r} but the file is missing.`,
+                    source: file,
+                    packageName: pack.packageName,
+                });
                 continue;
-            try {
-                const list = await importDefault(file);
-                for (const f of list)
-                    looseFacets.push(f);
-            }
-            catch {
-                /* ignore */
             }
+            const exp = await load(file, pack.packageName);
+            if (exp)
+                ingestFacets(exp, file, pack.packageName);
         }
     }
-    // Fold loose facets into their target construct.
-    for (const f of looseFacets) {
+    // Fold loose facets into their target construct. A facet whose target is
+    // not loaded never takes effect — refused, never silently dropped.
+    issues = facetIssues;
+    rejected = facetRejected;
+    const facets = [];
+    for (const { facet: f, exp, file, index, packageName } of looseFacets) {
         const target = out.find((c) => c.id === f.constructId);
-        if (!target)
+        if (!target) {
+            reject(exp, file, index, f, [`constructId: no construct "${f.constructId}" is loaded`]);
             continue;
-        const facets = (target.facets ?? {});
-        const list = facets[f.kind] ?? [];
+        }
+        const byKind = (target.facets ?? {});
+        const list = byKind[f.kind] ?? [];
         list.push({
             id: f.id,
             value: f.value,
             ...(f.description ? { description: f.description } : {}),
             ...(f.source ? { source: f.source } : {}),
+            // Dropping it here would silently turn a declared id back into free text.
+            ...(f.resolvesAs ? { resolvesAs: f.resolvesAs } : {}),
         });
-        facets[f.kind] = list;
-        target.facets = facets;
+        byKind[f.kind] = list;
+        target.facets = byKind;
+        facets.push({ id: f.id, constructId: f.constructId, file, ...(packageName ? { packageName } : {}) });
     }
-    CACHE.set(inspection.projectRoot, { cacheKey, list: out });
-    return out;
+    CACHE.set(inspection.projectRoot, {
+        cacheKey,
+        list: out,
+        facets,
+        issues: constructIssues,
+        rejected: constructRejected,
+        facetIssues,
+        facetRejected,
+    });
+    return {
+        constructs: out,
+        facets,
+        issues: constructIssues,
+        rejected: constructRejected,
+        facetIssues,
+        facetRejected,
+    };
+}
+export async function loadConstructs(inspection) {
+    return (await loadConstructsWithIssues(inspection)).constructs;
 }
 /** Synchronous accessor — falls back to a snapshot cached from the last
  *  async load. Used by search-index which needs to be sync-friendly. */

package/dist/context-tuning.d.ts

@@ -5,6 +5,10 @@ import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
  * (taskHint) boost only, scaled for the context score range; ambient boostTags
  * are intentionally ignored here. Returns undefined when no tuning is loaded so
  * buildContext skips the re-rank entirely.
+ *
+ * The document id comes from THE search-document codec and the trigger tokens
+ * from THE tuning tokenizer, so a key or trigger that fires in `shrk search`
+ * fires here too (a hyphenated `changed-only` trigger used to fire only there).
  */
 export declare function contextTuningBoostFor(inspection: ISharkcraftInspection, task: string): ((entry: {
     readonly id: string;

package/dist/context-tuning.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-tuning.d.ts","sourceRoot":"","sources":["../src/context-tuning.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAYvE;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,qBAAqB,EACjC,IAAI,EAAE,MAAM,GAEV,CAAC,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,KAAK,MAAM,CAAC,GACxG,SAAS,CAoBZ"}
+{"version":3,"file":"context-tuning.d.ts","sourceRoot":"","sources":["../src/context-tuning.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAcvE;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,qBAAqB,EACjC,IAAI,EAAE,MAAM,GAEV,CAAC,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,KAAK,MAAM,CAAC,GACxG,SAAS,CAiBZ"}

package/dist/context-tuning.js

@@ -1,4 +1,6 @@
 import { listSearchTuning, tuningBoostFor } from "./search-tuning-registry.js";
+import { searchDocumentId, searchKindForPrefix } from "./search-document-id.js";
+import { tuningQueryTokens } from "./tuning-query-tokens.js";
 // Context relevance scores are on a large scale (priority × weights, ~100–190),
 // so the pack's small ambient boostTags (±2–3) are noise there. The meaningful
 // signal for "this entry must surface" is a TASK-SPECIFIC taskHint boost
@@ -13,20 +15,21 @@ const TASK_HINT_SCALE = 100;
  * (taskHint) boost only, scaled for the context score range; ambient boostTags
  * are intentionally ignored here. Returns undefined when no tuning is loaded so
  * buildContext skips the re-rank entirely.
+ *
+ * The document id comes from THE search-document codec and the trigger tokens
+ * from THE tuning tokenizer, so a key or trigger that fires in `shrk search`
+ * fires here too (a hyphenated `changed-only` trigger used to fire only there).
  */
 export function contextTuningBoostFor(inspection, task) {
     const tuning = listSearchTuning(inspection);
     if (tuning.length === 0)
         return undefined;
-    const tokens = task
-        .toLowerCase()
-        .split(/[^a-z0-9]+/)
-        .filter((t) => t.length > 1);
+    const tokens = tuningQueryTokens(task);
     return (entry) => {
-        const isRule = String(entry.type).toLowerCase() === 'rule';
+        const prefix = String(entry.type).toLowerCase() === 'rule' ? 'rule' : 'knowledge';
         const doc = {
-            id: `${isRule ? 'rule' : 'knowledge'}:${entry.id}`,
-            kind: isRule ? 'rule' : 'knowledge',
+            id: searchDocumentId(prefix, entry.id),
+            kind: searchKindForPrefix(prefix) ?? prefix,
             ...(entry.tags ? { tags: entry.tags } : {}),
             source: 'local',
         };

package/dist/contract-template-registry.d.ts

@@ -1,5 +1,6 @@
 import { type IAgentContractTemplate } from './agent-contract-templates.js';
 import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+import { type IRejectedEntry } from '@shrkcrft/core';
 export declare const CONTRACT_TEMPLATE_REGISTRY_SCHEMA = "sharkcraft.contract-template-registry/v1";
 export declare enum ContractTemplateSource {
     Builtin = "builtin",
@@ -19,9 +20,18 @@ export interface IContractTemplateRegistryIssue {
     readonly templateId?: string;
     readonly source?: string;
 }
+/**
+ * THE contract-template acceptance predicate (round 12, 12.1): one
+ * `<field>: <message>` per failing field — `[]` means accepted. It used to be a
+ * boolean, and a refused template read `Invalid contract template at <file>;
+ * skipped.` with no id and no field.
+ */
+export declare function contractTemplateRejectionReasons(raw: unknown): readonly string[];
 export declare function loadAllContractTemplates(inspection: ISharkcraftInspection): Promise<{
     entries: readonly IContractTemplateEntry[];
     issues: readonly IContractTemplateRegistryIssue[];
+    /** Every declared template the loader refused — invalid or a duplicate id (round 12, 12.1). */
+    rejected: readonly IRejectedEntry[];
 }>;
 export declare function listAllContractTemplates(inspection: ISharkcraftInspection): Promise<readonly IAgentContractTemplate[]>;
 export declare function clearContractTemplateRegistryCache(projectRoot?: string): void;

package/dist/contract-template-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract-template-registry.d.ts","sourceRoot":"","sources":["../src/contract-template-registry.ts"],"names":[],"mappings":"AAMA,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAGvE,eAAO,MAAM,iCAAiC,6CAA6C,CAAC;AAE5F,oBAAY,sBAAsB;IAChC,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,IAAI,SAAS;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AA+CD,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC;IACT,OAAO,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAC3C,MAAM,EAAE,SAAS,8BAA8B,EAAE,CAAC;CACnD,CAAC,CAkGD;AAED,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,SAAS,sBAAsB,EAAE,CAAC,CAG5C;AAED,wBAAgB,kCAAkC,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAG7E"}
+{"version":3,"file":"contract-template-registry.d.ts","sourceRoot":"","sources":["../src/contract-template-registry.ts"],"names":[],"mappings":"AAMA,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AAExB,eAAO,MAAM,iCAAiC,6CAA6C,CAAC;AAE5F,oBAAY,sBAAsB;IAChC,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,IAAI,SAAS;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AA6BD;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAWhF;AAED,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC;IACT,OAAO,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAC3C,MAAM,EAAE,SAAS,8BAA8B,EAAE,CAAC;IAClD,+FAA+F;IAC/F,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;CACrC,CAAC,CAmID;AAED,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,SAAS,sBAAsB,EAAE,CAAC,CAG5C;AAED,wBAAgB,kCAAkC,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAG7E"}

package/dist/contract-template-registry.js

@@ -5,7 +5,7 @@
 import { existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { ALL_CONTRACT_TEMPLATES, AGENT_CONTRACT_TEMPLATE_SCHEMA, } from "./agent-contract-templates.js";
-import { importModuleViaLoader } from '@shrkcrft/core';
+import { importModuleViaLoader, readContributionExport, RejectionCause, } from '@shrkcrft/core';
 export const CONTRACT_TEMPLATE_REGISTRY_SCHEMA = 'sharkcraft.contract-template-registry/v1';
 export var ContractTemplateSource;
 (function (ContractTemplateSource) {
@@ -14,15 +14,8 @@ export var ContractTemplateSource;
     ContractTemplateSource["Pack"] = "pack";
 })(ContractTemplateSource || (ContractTemplateSource = {}));
 const CACHE = new Map();
-async function importDefault(file) {
-    const mod = (await importModuleViaLoader(file));
-    if (Array.isArray(mod.default))
-        return mod.default;
-    if (mod.default && typeof mod.default === 'object')
-        return [mod.default];
-    if (Array.isArray(mod.contractTemplates))
-        return mod.contractTemplates;
-    return [];
+async function importTemplates(file) {
+    return readContributionExport(await importModuleViaLoader(file), { namedKeys: ['contractTemplates'] });
 }
 function localFiles(inspection) {
     const out = [];
@@ -34,20 +27,32 @@ function localFiles(inspection) {
         if (existsSync(full))
             out.push(full);
     }
-    const cfg = inspection.config;
-    for (const rel of cfg?.contractTemplateFiles ?? []) {
-        out.push(nodePath.isAbsolute(rel) ? rel : nodePath.join(dir, rel));
-    }
+    // More template files come from pack manifests (`contractTemplateFiles`,
+    // loaded below) — there is no local-config key for them; the strict config
+    // schema rejects one, so a local read here could never be reached.
     return out;
 }
-function isValidTemplate(raw) {
-    if (!raw || typeof raw !== 'object')
-        return false;
+/**
+ * THE contract-template acceptance predicate (round 12, 12.1): one
+ * `<field>: <message>` per failing field — `[]` means accepted. It used to be a
+ * boolean, and a refused template read `Invalid contract template at <file>;
+ * skipped.` with no id and no field.
+ */
+export function contractTemplateRejectionReasons(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return ['(entry): must be an object'];
     const o = raw;
-    return (typeof o.id === 'string' &&
-        typeof o.title === 'string' &&
-        (o.schema === AGENT_CONTRACT_TEMPLATE_SCHEMA || o.schema === undefined) &&
-        Array.isArray(o.defaultForbiddenFilesDetailed));
+    const out = [];
+    if (typeof o.id !== 'string')
+        out.push('id: must be a string');
+    if (typeof o.title !== 'string')
+        out.push('title: must be a string');
+    if (!(o.schema === AGENT_CONTRACT_TEMPLATE_SCHEMA || o.schema === undefined)) {
+        out.push(`schema: must be "${AGENT_CONTRACT_TEMPLATE_SCHEMA}" or unset`);
+    }
+    if (!Array.isArray(o.defaultForbiddenFilesDetailed))
+        out.push('defaultForbiddenFilesDetailed: must be an array');
+    return out;
 }
 export async function loadAllContractTemplates(inspection) {
     const cacheKey = `${inspection.projectRoot}:${(inspection.packs.validPacks ?? [])
@@ -55,19 +60,26 @@ export async function loadAllContractTemplates(inspection) {
         .join(',')}`;
     const cached = CACHE.get(inspection.projectRoot);
     if (cached && cached.cacheKey === cacheKey) {
-        return { entries: cached.entries, issues: cached.issues };
+        return { entries: cached.entries, issues: cached.issues, rejected: cached.rejected };
     }
     const seen = new Map();
     const entries = [];
     const issues = [];
-    const ingest = (raw, source, packageName, sourceFile) => {
-        if (!isValidTemplate(raw)) {
+    const rejected = [];
+    const ingest = (raw, source, packageName, sourceFile, at) => {
+        const rawId = raw && typeof raw === 'object' ? raw.id : undefined;
+        const id = typeof rawId === 'string' ? rawId : undefined;
+        const reasons = contractTemplateRejectionReasons(raw);
+        if (reasons.length > 0) {
             issues.push({
                 severity: 'warning',
                 code: 'invalid-template',
-                message: `Invalid contract template at ${sourceFile ?? source}; skipped.`,
+                message: `Invalid contract template${id ? ` "${id}"` : ''} at ${sourceFile ?? source}${at ? ` (${at.exportName ?? 'default'}[${at.index}])` : ''}; skipped — ${reasons.join('; ')}.`,
+                ...(id ? { templateId: id } : {}),
                 source: sourceFile,
             });
+            if (at)
+                rejected.push({ ...at, ...(id ? { entryId: id } : {}), reasons, cause: RejectionCause.Invalid });
             return;
         }
         const tpl = raw;
@@ -80,6 +92,16 @@ export async function loadAllContractTemplates(inspection) {
                 templateId: tpl.id,
                 source: sourceFile,
             });
+            if (at) {
+                rejected.push({
+                    ...at,
+                    entryId: tpl.id,
+                    reasons: [
+                        `id: "${tpl.id}" is already declared by ${existing.source}${existing.sourceFile ? ` (${existing.sourceFile})` : ''}`,
+                    ],
+                    cause: RejectionCause.DuplicateId,
+                });
+            }
             return;
         }
         const entry = {
@@ -91,15 +113,21 @@ export async function loadAllContractTemplates(inspection) {
         seen.set(tpl.id, entry);
         entries.push(entry);
     };
+    const ingestAll = (exp, file, source, packageName, sourceFile) => {
+        exp.items.forEach((raw, i) => ingest(raw, source, packageName, sourceFile, {
+            file,
+            index: exp.single ? -1 : i,
+            ...(exp.exportName ? { exportName: exp.exportName } : {}),
+        }));
+    };
     for (const t of ALL_CONTRACT_TEMPLATES) {
         ingest(t, ContractTemplateSource.Builtin, undefined, undefined);
     }
     for (const file of localFiles(inspection)) {
         try {
-            const list = await importDefault(file);
+            const exp = await importTemplates(file);
             const rel = nodePath.relative(inspection.projectRoot, file) || file;
-            for (const raw of list)
-                ingest(raw, ContractTemplateSource.Local, undefined, rel);
+            ingestAll(exp, file, ContractTemplateSource.Local, undefined, rel);
         }
         catch (e) {
             issues.push({
@@ -124,9 +152,7 @@ export async function loadAllContractTemplates(inspection) {
                 continue;
             }
             try {
-                const list = await importDefault(file);
-                for (const raw of list)
-                    ingest(raw, ContractTemplateSource.Pack, pack.packageName, rel);
+                ingestAll(await importTemplates(file), file, ContractTemplateSource.Pack, pack.packageName, rel);
             }
             catch (e) {
                 issues.push({
@@ -138,8 +164,8 @@ export async function loadAllContractTemplates(inspection) {
             }
         }
     }
-    CACHE.set(inspection.projectRoot, { cacheKey, entries, issues });
-    return { entries, issues };
+    CACHE.set(inspection.projectRoot, { cacheKey, entries, issues, rejected });
+    return { entries, issues, rejected };
 }
 export async function listAllContractTemplates(inspection) {
     const { entries } = await loadAllContractTemplates(inspection);

package/dist/contribution-kind.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Every contribution kind the engine loads — one per manifest contribution
+ * slot that has a loader (`CONTRIBUTION_FILE_KEYS`, @shrkcrft/plugin-api), plus
+ * `path-convention` / `docs`, whose slots feed the path / knowledge loaders.
+ *
+ * Round 12 (12.1e): the inventory knew only the knowledge family and six
+ * registries, so a registration hint, a gate-plane rule, a delegate recipe or
+ * a construct facet contributed by a pack appeared on no contributions surface
+ * — and neither did a rejected one. Every loader-backed slot now has a kind
+ * (the inventory's `KIND_TO_SLOT` is a `Record` over this enum, so a kind
+ * without a slot is a compile error, and an r76 lock holds every loader-backed
+ * slot to a kind).
+ */
+export declare enum ContributionKind {
+    Knowledge = "knowledge",
+    Rule = "rule",
+    Path = "path",
+    PathConvention = "path-convention",
+    Template = "template",
+    Pipeline = "pipeline",
+    Preset = "preset",
+    Boundary = "boundary",
+    ScaffoldPattern = "scaffold-pattern",
+    Policy = "policy",
+    Construct = "construct",
+    ConstructFacet = "construct-facet",
+    Playbook = "playbook",
+    SearchTuning = "search-tuning",
+    FeedbackRule = "feedback-rule",
+    Decision = "decision",
+    ContractTemplate = "contract-template",
+    MigrationProfile = "migration-profile",
+    ContextTest = "context-test",
+    AgentTest = "agent-test",
+    Helper = "helper",
+    TaskRoutingHint = "task-routing-hint",
+    RegistrationHint = "registration-hint",
+    Convention = "convention",
+    Docs = "docs",
+    DelegateRecipe = "delegate-recipe",
+    FrameworkExtractor = "framework-extractor",
+    WiringRule = "wiring-rule",
+    Registry = "registry",
+    RegistrationIdiom = "registration-idiom",
+    PolicyRule = "policy-rule",
+    ReusePrimitive = "reuse-primitive",
+    Baseline = "baseline",
+    GeneratedArtifact = "generated-artifact",
+    /** `docReferenceFiles` — the prose doc-reference plane (round 13: a declared slot). */
+    DocReference = "doc-reference"
+}
+//# sourceMappingURL=contribution-kind.d.ts.map

package/dist/contribution-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contribution-kind.d.ts","sourceRoot":"","sources":["../src/contribution-kind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,oBAAY,gBAAgB;IAC1B,SAAS,cAAc;IACvB,IAAI,SAAS;IACb,IAAI,SAAS;IACb,cAAc,oBAAoB;IAClC,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,eAAe,qBAAqB;IACpC,MAAM,WAAW;IACjB,SAAS,cAAc;IACvB,cAAc,oBAAoB;IAClC,QAAQ,aAAa;IACrB,YAAY,kBAAkB;IAC9B,YAAY,kBAAkB;IAC9B,QAAQ,aAAa;IACrB,gBAAgB,sBAAsB;IACtC,gBAAgB,sBAAsB;IACtC,WAAW,iBAAiB;IAC5B,SAAS,eAAe;IACxB,MAAM,WAAW;IACjB,eAAe,sBAAsB;IACrC,gBAAgB,sBAAsB;IACtC,UAAU,eAAe;IACzB,IAAI,SAAS;IACb,cAAc,oBAAoB;IAClC,kBAAkB,wBAAwB;IAC1C,UAAU,gBAAgB;IAC1B,QAAQ,aAAa;IACrB,iBAAiB,uBAAuB;IACxC,UAAU,gBAAgB;IAC1B,cAAc,oBAAoB;IAClC,QAAQ,aAAa;IACrB,iBAAiB,uBAAuB;IACxC,uFAAuF;IACvF,YAAY,kBAAkB;CAC/B"}