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

package/dist/reference-content-check.d.ts

@@ -0,0 +1,32 @@
+import { type IAssetReference } from '@shrkcrft/core';
+import { ReferenceFailure } from './reference-failure.js';
+/** The outcome of one content or count assertion. */
+export interface IReferenceAssertionResult {
+    readonly ok: boolean;
+    /** True when the assertion could not be evaluated at all — nothing was proved. */
+    readonly unverifiable?: boolean;
+    readonly failure?: ReferenceFailure;
+    readonly expected?: string | number;
+    readonly actual?: string | number;
+    readonly message: string;
+}
+/** Whether `ref` carries a `contains` / `matches` assertion. */
+export declare function hasContentAssertion(ref: IAssetReference): boolean;
+/**
+ * Check `ref.contains` / `ref.matches` against its target. `span` narrows the
+ * read to a pinned symbol's declaration. Returns `null` when the reference
+ * carries no content assertion.
+ */
+export declare function checkReferenceContent(projectRoot: string, ref: IAssetReference, span?: {
+    start: number;
+    end: number;
+}): IReferenceAssertionResult | null;
+/**
+ * Re-derive `ref.count` through the extraction authority and compare it to the
+ * claimed number. Returns `null` when the reference declares no count.
+ *
+ * A source that matched 0 files never measured anything, so it is unverifiable
+ * — never a pass, even for `expected: 0`.
+ */
+export declare function checkReferenceCount(projectRoot: string, ref: IAssetReference, excludeDirs?: readonly string[]): IReferenceAssertionResult | null;
+//# sourceMappingURL=reference-content-check.d.ts.map

package/dist/reference-content-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-content-check.d.ts","sourceRoot":"","sources":["../src/reference-content-check.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAwB,KAAK,eAAe,EAAsB,MAAM,gBAAgB,CAAC;AAChG,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,qDAAqD;AACrD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,kFAAkF;IAClF,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAaD,gEAAgE;AAChE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAEjE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,eAAe,EACpB,IAAI,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACpC,yBAAyB,GAAG,IAAI,CAoDlC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,eAAe,EACpB,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,yBAAyB,GAAG,IAAI,CAqClC"}

package/dist/reference-content-check.js

@@ -0,0 +1,143 @@
+/**
+ * Content assertions on a declared reference: `contains` / `matches` (read the
+ * target's text) and `count` (re-derive a number the asset claims).
+ *
+ * Existence is the weakest proxy for what an asset claims — a file survives a
+ * rename-inside refactor untouched while every statement about its contents
+ * goes false. These turn prose claims into checks WITHOUT a new parser:
+ *
+ *   - `contains` / `matches` read the file (or the pinned symbol's declaration
+ *     span), zoned through the ONE lexical-zone authority (`blankOutsideZone`),
+ *     so `scan: 'code'` means here exactly what it means on the policy plane;
+ *   - `count` is measured by the ONE extraction authority (`inspectSource`), so
+ *     it gets every extractor, glob and zone the gate planes have.
+ *
+ * Every result reports what was found beside what was expected, so the fix is a
+ * one-token edit.
+ */
+import { readFileSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { blankOutsideZone, inspectSource } from '@shrkcrft/boundaries';
+import { validateWiringSource } from '@shrkcrft/core';
+import { ReferenceFailure } from "./reference-failure.js";
+const SHOWN_LITERAL = 60;
+function shown(s) {
+    const one = s.replace(/\s+/g, ' ');
+    return one.length > SHOWN_LITERAL ? `${one.slice(0, SHOWN_LITERAL)}…` : one;
+}
+function unverifiable(message) {
+    return { ok: false, unverifiable: true, failure: ReferenceFailure.Unverifiable, message };
+}
+/** Whether `ref` carries a `contains` / `matches` assertion. */
+export function hasContentAssertion(ref) {
+    return ref.contains !== undefined || ref.matches !== undefined;
+}
+/**
+ * Check `ref.contains` / `ref.matches` against its target. `span` narrows the
+ * read to a pinned symbol's declaration. Returns `null` when the reference
+ * carries no content assertion.
+ */
+export function checkReferenceContent(projectRoot, ref, span) {
+    if (!hasContentAssertion(ref))
+        return null;
+    if (!ref.path)
+        return unverifiable('contains/matches needs a `path` to read — pin the file.');
+    const abs = nodePath.join(projectRoot, ref.path);
+    let text;
+    try {
+        if (statSync(abs).isDirectory()) {
+            return unverifiable(`contains/matches cannot read a directory (${ref.path}) — assert on it with \`count\`.`);
+        }
+        text = readFileSync(abs, 'utf8');
+    }
+    catch {
+        return unverifiable(`could not read ${ref.path}.`);
+    }
+    const zone = ref.scan ?? 'all';
+    // Zone the WHOLE file, then slice: lexing from mid-declaration could start
+    // inside a string and invert every zone after it.
+    const zoned = blankOutsideZone(text, zone).content;
+    const scoped = span ? zoned.slice(span.start, span.end) : zoned;
+    const where = span && ref.symbol ? `the \`${ref.symbol}\` declaration in ${ref.path}` : ref.path;
+    const zoneNote = zone === 'all' ? '' : ` (scan: ${zone})`;
+    const held = [];
+    if (ref.contains !== undefined) {
+        if (!scoped.includes(ref.contains)) {
+            return {
+                ok: false,
+                failure: ReferenceFailure.ContentMismatch,
+                expected: `contains "${shown(ref.contains)}"`,
+                actual: 'not found',
+                message: `${where} no longer contains "${shown(ref.contains)}"${zoneNote}.`,
+            };
+        }
+        held.push(`contains "${shown(ref.contains)}"`);
+    }
+    if (ref.matches !== undefined) {
+        let re;
+        try {
+            re = new RegExp(ref.matches, 'm');
+        }
+        catch (e) {
+            return unverifiable(`matches /${ref.matches}/ does not compile: ${e.message}`);
+        }
+        if (!re.test(scoped)) {
+            return {
+                ok: false,
+                failure: ReferenceFailure.ContentMismatch,
+                expected: `matches /${ref.matches}/`,
+                actual: 'no match',
+                message: `${where} no longer matches /${ref.matches}/${zoneNote}.`,
+            };
+        }
+        held.push(`matches /${ref.matches}/`);
+    }
+    return { ok: true, message: `${where} still ${held.join(' and ')}${zoneNote}.` };
+}
+/**
+ * Re-derive `ref.count` through the extraction authority and compare it to the
+ * claimed number. Returns `null` when the reference declares no count.
+ *
+ * A source that matched 0 files never measured anything, so it is unverifiable
+ * — never a pass, even for `expected: 0`.
+ */
+export function checkReferenceCount(projectRoot, ref, excludeDirs = []) {
+    const count = ref.count;
+    if (!count)
+        return null;
+    const source = count.source;
+    if (!source || typeof source !== 'object')
+        return unverifiable('count.source is missing.');
+    if (source.$use !== undefined) {
+        return unverifiable('count.source uses `$use`, which a reference does not resolve — inline the selector.');
+    }
+    const problem = validateWiringSource(source);
+    if (problem)
+        return unverifiable(`count.source ${problem}.`);
+    const res = inspectSource(projectRoot, source, excludeDirs);
+    if (res.error)
+        return unverifiable(`count.source could not be evaluated: ${res.error}`);
+    if (res.filesScanned === 0) {
+        return unverifiable(`count.source matched 0 files (${(source.files ?? []).join(', ')}) — the count was never measured` +
+            (res.hint ? ` (${res.hint})` : '') +
+            '.');
+    }
+    const measure = count.measure ?? 'ids';
+    const actual = measure === 'sites' ? res.sites.length : res.ids.length;
+    const basis = `${measure} across ${res.filesScanned} file(s)`;
+    if (actual === count.expected) {
+        return {
+            ok: true,
+            expected: count.expected,
+            actual,
+            message: `count ${actual} = expected ${count.expected} (${basis}).`,
+        };
+    }
+    return {
+        ok: false,
+        failure: ReferenceFailure.CountMismatch,
+        expected: count.expected,
+        actual,
+        message: `count ${actual} ≠ expected ${count.expected} (${basis}) — set expected: ${actual}.`,
+    };
+}

package/dist/reference-failure.d.ts

@@ -0,0 +1,31 @@
+/**
+ * WHY a reference check did not pass — additive to its `outcome`.
+ *
+ * `outcome` (ok / stale / missing / unknown) is kept for back-compat, but it
+ * conflated unrelated failures: a missing FILE reference read `stale` while a
+ * symbol pinned to a missing file read `missing`, and nothing separated "the
+ * path is gone" from "the path is there but the thing inside it is not". Each
+ * failure mode can be failed on separately (`--fail-on path-missing`).
+ */
+export declare enum ReferenceFailure {
+    /** The file / directory (or a symbol's pinned file) does not exist. */
+    PathMissing = "path-missing",
+    /** The path exists, but the symbol / member it pins does not. */
+    AnchorMissing = "anchor-missing",
+    /** The target exists but no longer `contains` / `matches` what the asset claims. */
+    ContentMismatch = "content-mismatch",
+    /** A declared `count` re-derived to a different number. */
+    CountMismatch = "count-mismatch",
+    /** An id-keyed reference (template, playbook, policy, …) is not registered. */
+    IdUnregistered = "id-unregistered",
+    /** The check could not run — nothing was proved either way. */
+    Unverifiable = "unverifiable",
+    /**
+     * The reference itself is malformed — a kind outside the vocabulary, or the
+     * field its kind cannot be checked without (`path`, `symbol`, `id`) is
+     * missing. Nothing was checked, and unlike `unverifiable` (a well-formed
+     * `url` the check deliberately never fetches) the author can fix it.
+     */
+    Malformed = "malformed"
+}
+//# sourceMappingURL=reference-failure.d.ts.map

package/dist/reference-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-failure.d.ts","sourceRoot":"","sources":["../src/reference-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,oBAAY,gBAAgB;IAC1B,uEAAuE;IACvE,WAAW,iBAAiB;IAC5B,iEAAiE;IACjE,aAAa,mBAAmB;IAChC,oFAAoF;IACpF,eAAe,qBAAqB;IACpC,2DAA2D;IAC3D,aAAa,mBAAmB;IAChC,+EAA+E;IAC/E,cAAc,oBAAoB;IAClC,+DAA+D;IAC/D,YAAY,iBAAiB;IAC7B;;;;;OAKG;IACH,SAAS,cAAc;CACxB"}

package/dist/reference-failure.js

@@ -0,0 +1,31 @@
+/**
+ * WHY a reference check did not pass — additive to its `outcome`.
+ *
+ * `outcome` (ok / stale / missing / unknown) is kept for back-compat, but it
+ * conflated unrelated failures: a missing FILE reference read `stale` while a
+ * symbol pinned to a missing file read `missing`, and nothing separated "the
+ * path is gone" from "the path is there but the thing inside it is not". Each
+ * failure mode can be failed on separately (`--fail-on path-missing`).
+ */
+export var ReferenceFailure;
+(function (ReferenceFailure) {
+    /** The file / directory (or a symbol's pinned file) does not exist. */
+    ReferenceFailure["PathMissing"] = "path-missing";
+    /** The path exists, but the symbol / member it pins does not. */
+    ReferenceFailure["AnchorMissing"] = "anchor-missing";
+    /** The target exists but no longer `contains` / `matches` what the asset claims. */
+    ReferenceFailure["ContentMismatch"] = "content-mismatch";
+    /** A declared `count` re-derived to a different number. */
+    ReferenceFailure["CountMismatch"] = "count-mismatch";
+    /** An id-keyed reference (template, playbook, policy, …) is not registered. */
+    ReferenceFailure["IdUnregistered"] = "id-unregistered";
+    /** The check could not run — nothing was proved either way. */
+    ReferenceFailure["Unverifiable"] = "unverifiable";
+    /**
+     * The reference itself is malformed — a kind outside the vocabulary, or the
+     * field its kind cannot be checked without (`path`, `symbol`, `id`) is
+     * missing. Nothing was checked, and unlike `unverifiable` (a well-formed
+     * `url` the check deliberately never fetches) the author can fix it.
+     */
+    ReferenceFailure["Malformed"] = "malformed";
+})(ReferenceFailure || (ReferenceFailure = {}));

package/dist/reference-id-status.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Tri-state answer to "is this id registered?".
+ *
+ * A boolean cannot say "I could not look": a lookup known to be unable to
+ * answer (the command index was not injected, outside the CLI) collapsed to
+ * either `true` (every `shrk …` string "existed") or `false` (every correct
+ * command was "missing"). `Unverifiable` is the third answer, and every consumer
+ * reports it as NOT VERIFIED — never as a pass and never as a finding.
+ */
+export declare enum ReferenceIdStatus {
+    Exists = "exists",
+    Missing = "missing",
+    Unverifiable = "unverifiable"
+}
+//# sourceMappingURL=reference-id-status.d.ts.map

package/dist/reference-id-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-id-status.d.ts","sourceRoot":"","sources":["../src/reference-id-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,oBAAY,iBAAiB;IAC3B,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,YAAY,iBAAiB;CAC9B"}

package/dist/reference-id-status.js

@@ -0,0 +1,15 @@
+/**
+ * Tri-state answer to "is this id registered?".
+ *
+ * A boolean cannot say "I could not look": a lookup known to be unable to
+ * answer (the command index was not injected, outside the CLI) collapsed to
+ * either `true` (every `shrk …` string "existed") or `false` (every correct
+ * command was "missing"). `Unverifiable` is the third answer, and every consumer
+ * reports it as NOT VERIFIED — never as a pass and never as a finding.
+ */
+export var ReferenceIdStatus;
+(function (ReferenceIdStatus) {
+    ReferenceIdStatus["Exists"] = "exists";
+    ReferenceIdStatus["Missing"] = "missing";
+    ReferenceIdStatus["Unverifiable"] = "unverifiable";
+})(ReferenceIdStatus || (ReferenceIdStatus = {}));

package/dist/reference-kind-declarations.d.ts

@@ -0,0 +1,42 @@
+/**
+ * THE declaration table: for every kind THE id resolver answers for, how its
+ * ids come to exist.
+ *
+ * Round 12 (12.3): a registration hint's `discovery.profileIds` resolved
+ * against a kind the consumer could not see how to fill, so the self-config
+ * doctor sat at NOT VERIFIED (exit 2) forever. The loud skip was right; what
+ * was missing is a guarantee that every referenceable kind is DECLARABLE. This
+ * table is that guarantee's data:
+ *
+ *   - `Record<IdReferenceKind, …>` — a kind added to `ALL_ID_REFERENCE_KINDS`
+ *     without a row is a compile error;
+ *   - the r76 declarability lock declares one id through EVERY path of every
+ *     row (a real pack under node_modules for a pack key) and proves the
+ *     resolver lists it, so a row cannot name a path that fills nothing;
+ *   - it has real consumers, so it cannot drift into a doc-only list: the
+ *     doctor's loud-skip reason names how to fill an empty kind, its
+ *     `*-missing` findings print `listVerb` as `next:`, and `shrk profiles
+ *     list` renders its empty state from here.
+ */
+import type { IReferenceKindDeclaration } from './i-reference-kind-declaration.js';
+import type { IdReferenceKind, ReferenceKind } from './reference-registry.js';
+export declare const REFERENCE_KIND_DECLARATIONS: Readonly<Record<IdReferenceKind, IReferenceKindDeclaration>>;
+/**
+ * Every way `kind` can be filled, as display strings — `builtin`, `pack key
+ * <key>`, `config key <key>`, then local files — or `[]` for a kind with no
+ * row (`command`, `file`, … are not id registries).
+ */
+export declare function referenceKindDeclarationPaths(kind: ReferenceKind): readonly string[];
+/**
+ * THE declarability answer: can ANY declaration (builtin, config key, local
+ * file, pack key) fill `kind`'s registry? A reference to a kind for which this
+ * is false can never resolve — the contributions report files it as
+ * `undeclarable-kind`, never as a fixable empty registry. The r76 lock keeps
+ * it true for every kind the resolver lists.
+ */
+export declare function isReferenceKindDeclarable(kind: ReferenceKind): boolean;
+/** `pack key migrationProfileFiles · sharkcraft/migration-profiles.ts` — the one wording every surface prints. */
+export declare function formatReferenceKindDeclaration(kind: ReferenceKind): string;
+/** The command that shows `kind`'s ids (its `listVerb`), or `undefined` for a kind with no row. */
+export declare function referenceKindListVerb(kind: ReferenceKind): string | undefined;
+//# sourceMappingURL=reference-kind-declarations.d.ts.map

package/dist/reference-kind-declarations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-kind-declarations.d.ts","sourceRoot":"","sources":["../src/reference-kind-declarations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AACnF,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE9E,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,yBAAyB,CAAC,CAsGjG,CAAC;AAQL;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,MAAM,EAAE,CASpF;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAEtE;AAED,kHAAkH;AAClH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAG1E;AAED,mGAAmG;AACnG,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAE7E"}

package/dist/reference-kind-declarations.js

@@ -0,0 +1,142 @@
+export const REFERENCE_KIND_DECLARATIONS = Object.freeze({
+    template: {
+        listVerb: 'shrk templates list',
+        configKeys: ['templateFiles'],
+        localFiles: ['sharkcraft/templates.ts', 'sharkcraft/knowledge/templates.ts'],
+        packKeys: ['templateFiles'],
+    },
+    pipeline: {
+        listVerb: 'shrk pipelines list',
+        configKeys: ['pipelineFiles'],
+        localFiles: ['sharkcraft/pipelines.ts', 'sharkcraft/knowledge/pipelines.ts'],
+        packKeys: ['pipelineFiles'],
+    },
+    playbook: {
+        listVerb: 'shrk playbooks list',
+        configKeys: ['playbookFiles'],
+        localFiles: ['sharkcraft/playbooks.ts', 'sharkcraft/playbooks/index.ts'],
+        packKeys: ['playbookFiles'],
+    },
+    policy: {
+        listVerb: 'shrk policy list',
+        localFiles: ['sharkcraft/policies.ts'],
+        packKeys: ['policyCheckFiles'],
+    },
+    construct: {
+        listVerb: 'shrk constructs list',
+        localFiles: ['sharkcraft/constructs.ts', 'sharkcraft/constructs.js', 'sharkcraft/constructs/index.ts'],
+        packKeys: ['constructFiles'],
+    },
+    helper: {
+        // The built-in HELPERS table ships empty — helpers are declared, not builtin.
+        listVerb: 'shrk helper list',
+        localFiles: ['sharkcraft/helpers.ts', 'sharkcraft/helpers/index.ts'],
+        packKeys: ['helperFiles'],
+    },
+    'boundary-rule': {
+        // `sharkcraft/boundaries.ts` is NOT read unless `boundaryFiles` lists it.
+        listVerb: 'shrk boundaries list',
+        configKeys: ['boundaryFiles'],
+        packKeys: ['boundaryFiles'],
+    },
+    'path-convention': {
+        listVerb: 'shrk paths list',
+        configKeys: ['pathFiles'],
+        localFiles: ['sharkcraft/paths.ts', 'sharkcraft/knowledge/paths.ts'],
+        packKeys: ['pathFiles', 'pathConventionFiles'],
+    },
+    rule: {
+        listVerb: 'shrk rules list',
+        configKeys: ['ruleFiles'],
+        localFiles: ['sharkcraft/rules.ts', 'sharkcraft/knowledge/rules.ts'],
+        packKeys: ['ruleFiles'],
+    },
+    knowledge: {
+        listVerb: 'shrk knowledge list',
+        configKeys: ['knowledgeFiles', 'docsFiles'],
+        localFiles: ['sharkcraft/knowledge.ts', 'sharkcraft/knowledge/index.ts'],
+        packKeys: ['knowledgeFiles', 'docsFiles'],
+    },
+    decision: {
+        listVerb: 'shrk self-config resolve <id>',
+        localFiles: ['sharkcraft/decisions.ts', 'sharkcraft/decisions/*.md', 'docs/adr/*.md'],
+        packKeys: ['decisionFiles'],
+    },
+    convention: {
+        listVerb: 'shrk conventions list',
+        configKeys: ['conventionFiles'],
+        localFiles: ['sharkcraft/conventions.ts', 'sharkcraft/conventions/index.ts'],
+        packKeys: ['conventionFiles'],
+    },
+    'contract-template': {
+        listVerb: 'shrk contract template list',
+        localFiles: ['sharkcraft/contract-templates.ts', 'sharkcraft/contract-templates/index.ts'],
+        packKeys: ['contractTemplateFiles'],
+    },
+    'migration-profile': {
+        listVerb: 'shrk profiles list --kind migration',
+        localFiles: ['sharkcraft/migration-profiles.ts', 'sharkcraft/migration-profiles/index.ts'],
+        packKeys: ['migrationProfileFiles'],
+    },
+    'workspace-profile': {
+        // THE WorkspaceProfile vocabulary (@shrkcrft/workspace) — never empty.
+        listVerb: 'shrk profiles list --kind workspace',
+        builtin: true,
+    },
+    'routing-hint': {
+        listVerb: 'shrk self-config resolve <id>',
+        configKeys: ['taskRoutingHintFiles'],
+        localFiles: ['sharkcraft/task-routing-hints.ts', 'sharkcraft/task-routing-hints/index.ts'],
+        packKeys: ['taskRoutingHintFiles'],
+    },
+    'registration-hint': {
+        listVerb: 'shrk registrations list',
+        localFiles: ['sharkcraft/registration-hints.ts', 'sharkcraft/registration-hints/index.ts'],
+        packKeys: ['registrationHintFiles'],
+    },
+    'scaffold-pattern': {
+        listVerb: 'shrk scaffolds list',
+        localFiles: ['sharkcraft/scaffold-patterns.ts'],
+        packKeys: ['scaffoldPatternFiles'],
+    },
+});
+function declarationOf(kind) {
+    return Object.prototype.hasOwnProperty.call(REFERENCE_KIND_DECLARATIONS, kind)
+        ? REFERENCE_KIND_DECLARATIONS[kind]
+        : undefined;
+}
+/**
+ * Every way `kind` can be filled, as display strings — `builtin`, `pack key
+ * <key>`, `config key <key>`, then local files — or `[]` for a kind with no
+ * row (`command`, `file`, … are not id registries).
+ */
+export function referenceKindDeclarationPaths(kind) {
+    const d = declarationOf(kind);
+    if (!d)
+        return [];
+    return [
+        ...(d.builtin ? ['builtin (always populated)'] : []),
+        ...(d.packKeys ?? []).map((k) => `pack key ${k}`),
+        ...(d.configKeys ?? []).map((k) => `config key ${String(k)}`),
+        ...(d.localFiles ?? []),
+    ];
+}
+/**
+ * THE declarability answer: can ANY declaration (builtin, config key, local
+ * file, pack key) fill `kind`'s registry? A reference to a kind for which this
+ * is false can never resolve — the contributions report files it as
+ * `undeclarable-kind`, never as a fixable empty registry. The r76 lock keeps
+ * it true for every kind the resolver lists.
+ */
+export function isReferenceKindDeclarable(kind) {
+    return referenceKindDeclarationPaths(kind).length > 0;
+}
+/** `pack key migrationProfileFiles · sharkcraft/migration-profiles.ts` — the one wording every surface prints. */
+export function formatReferenceKindDeclaration(kind) {
+    const paths = referenceKindDeclarationPaths(kind);
+    return paths.length > 0 ? paths.join(' · ') : 'nothing — no builtin, config key, local file or pack key declares it';
+}
+/** The command that shows `kind`'s ids (its `listVerb`), or `undefined` for a kind with no row. */
+export function referenceKindListVerb(kind) {
+    return declarationOf(kind)?.listVerb;
+}

package/dist/reference-lookup.d.ts

@@ -3,6 +3,12 @@ import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
 /**
  * Adapt a SharkCraft inspection to the {@link IReferenceLookup} contract the
  * preset reference resolver expects. Pure read-through; no state.
+ *
+ * A projection of THE reference registry, never a second id authority: it
+ * used to build its template / pipeline sets from `inspection.templates` /
+ * `inspection.pipelines` rather than the registries `templates list` and
+ * `pipelines list` read — two answers to "does this id exist?" that agreed
+ * only while nobody filtered one of them.
  */
 export declare function inspectionReferenceLookup(inspection: ISharkcraftInspection): IReferenceLookup;
 //# sourceMappingURL=reference-lookup.d.ts.map

package/dist/reference-lookup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reference-lookup.d.ts","sourceRoot":"","sources":["../src/reference-lookup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,qBAAqB,GAChC,gBAAgB,CAalB"}
+{"version":3,"file":"reference-lookup.d.ts","sourceRoot":"","sources":["../src/reference-lookup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,qBAAqB,GAChC,gBAAgB,CAclB"}

package/dist/reference-lookup.js

@@ -1,13 +1,21 @@
+import { referenceIdsFor } from "./reference-registry.js";
 /**
  * Adapt a SharkCraft inspection to the {@link IReferenceLookup} contract the
  * preset reference resolver expects. Pure read-through; no state.
+ *
+ * A projection of THE reference registry, never a second id authority: it
+ * used to build its template / pipeline sets from `inspection.templates` /
+ * `inspection.pipelines` rather than the registries `templates list` and
+ * `pipelines list` read — two answers to "does this id exist?" that agreed
+ * only while nobody filtered one of them.
  */
 export function inspectionReferenceLookup(inspection) {
-    const knowledgeIds = new Set(inspection.knowledgeEntries.map((e) => e.id));
-    const ruleIds = new Set(inspection.ruleService.list().map((r) => r.id));
-    const pathIds = new Set(inspection.pathService.list().map((p) => p.id));
-    const templateIds = new Set(inspection.templates.map((t) => t.id));
-    const pipelineIds = new Set(inspection.pipelines.map((p) => p.id));
+    const ids = (kind) => new Set(referenceIdsFor(inspection, kind));
+    const knowledgeIds = ids('knowledge');
+    const ruleIds = ids('rule');
+    const pathIds = ids('path-convention');
+    const templateIds = ids('template');
+    const pipelineIds = ids('pipeline');
     return {
         hasKnowledge: (id) => knowledgeIds.has(id),
         hasRule: (id) => ruleIds.has(id),