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

package/dist/reference-registry.d.ts

@@ -1,4 +1,8 @@
 import type { KnowledgeReferenceKind } from '@shrkcrft/knowledge';
+import type { ICommandResolution } from './i-command-resolution.js';
+import type { ICommandResolveOptions } from './i-command-resolve-options.js';
+import type { IReferenceWarmOptions } from './i-reference-warm-options.js';
+import { ReferenceIdStatus } from './reference-id-status.js';
 import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
 /**
  * The id sets a knowledge/doc reference can resolve against.
@@ -38,15 +42,35 @@ export type DocReferenceKind = KnowledgeReferenceKind | 'pipeline';
  * `docReferences[].resolvesAs` is unchanged — it still accepts exactly the
  * `DocReferenceKind`s. Widening the RESOLVER is not widening the config.
  */
-export type ReferenceKind = DocReferenceKind | 'knowledge' | 'rule' | 'decision' | 'convention' | 'contract-template' | 'migration-profile' | 'routing-hint' | 'registration-hint' | 'scaffold-pattern';
+export type ReferenceKind = DocReferenceKind | 'knowledge' | 'rule' | 'decision' | 'convention' | 'contract-template' | 'migration-profile' | 'workspace-profile' | 'routing-hint' | 'registration-hint' | 'scaffold-pattern';
 /**
  * Every kind that resolves against a registry of ids.
  *
- * `command` is deliberately absent: the catalog lives in the CLI package,
- * ABOVE this layer, so it resolves by shape instead of by list. `file` /
- * `directory` / `symbol` / `package` / `url` are not id registries at all.
+ * `command` is deliberately absent: the command index lives in the CLI
+ * package, ABOVE this layer, so it resolves through the resolver the CLI
+ * injects ({@link resolveCommandReference}) — never by shape, and never by a
+ * list this layer cannot see. `file` / `directory` / `symbol` / `package` /
+ * `url` are not id registries at all.
+ *
+ * **List order is SPECIFICITY.** A rule and a path convention are knowledge
+ * entries filtered by type, so `knowledge` is a SUPERSET of both and must come
+ * after them: {@link referenceKindsOf} returns kinds in this order, so its first
+ * element names the most specific registry. With `knowledge` listed first,
+ * every rule id used to report `knowledge` as "the" kind it resolved as.
+ *
+ * **Every kind here is DECLARABLE** (round 12): `REFERENCE_KIND_DECLARATIONS`
+ * is a `Record<IdReferenceKind, …>`, so a kind added here without a row saying
+ * how its ids come to exist is a compile error, and the r76 declarability lock
+ * proves every path in that row fills this resolver. `workspace-profile` is
+ * the builtin WorkspaceProfile vocabulary — the applicability filters'
+ * `profileIds` resolve against it (they were bound to `migration-profile`, a
+ * readiness registry, and sat at NOT VERIFIED forever).
  */
-export declare const ALL_ID_REFERENCE_KINDS: readonly ReferenceKind[];
+export declare const ALL_ID_REFERENCE_KINDS: readonly ["template", "pipeline", "playbook", "policy", "construct", "helper", "boundary-rule", "path-convention", "rule", "knowledge", "decision", "convention", "contract-template", "migration-profile", "workspace-profile", "routing-hint", "registration-hint", "scaffold-pattern"];
+/** A kind that resolves against a registry of ids — a member of {@link ALL_ID_REFERENCE_KINDS}. */
+export type IdReferenceKind = (typeof ALL_ID_REFERENCE_KINDS)[number];
+/** The loud-skip message every consumer prints for an un-injected command index. */
+export declare const COMMAND_INDEX_NOT_INJECTED = "command index not injected \u2014 NOT VERIFIED";
 /**
  * Populate the snapshot the synchronous accessors read.
  *
@@ -54,8 +78,12 @@ export declare const ALL_ID_REFERENCE_KINDS: readonly ReferenceKind[];
  * resolving anything. Without it a correct playbook — or convention, or
  * scaffold pattern — resolves to nothing, which is exactly how a correct id got
  * reported as an error twice.
+ *
+ * `options.commandResolver` is the CLI's command-string resolver (the command
+ * index lives above this layer). Without one, every `command` reference is
+ * `Unverifiable` — see {@link resolveCommandReference}.
  */
-export declare function warmReferenceRegistries(inspection: ISharkcraftInspection): Promise<void>;
+export declare function warmReferenceRegistries(inspection: ISharkcraftInspection, options?: IReferenceWarmOptions): Promise<void>;
 /**
  * Every registered id of `kind`, for existence checks and for suggesting what
  * an unresolved token might have meant.
@@ -75,16 +103,68 @@ export declare function referenceIdsFor(inspection: ISharkcraftInspection, kind:
  * to get a gate switched off. Emptiness is repo-dependent (a project may simply
  * have no playbooks), so it cannot be a config-time error; the caller surfaces
  * it as a loud refusal at run time instead.
+ *
+ * `command` has no list; it can resolve exactly when a resolver was injected.
+ * Without one it is reported here — nothing could resolve, so every command
+ * would be reported wrong (or, before round 11, every `shrk …` string right).
  */
 export declare function emptyReferenceKinds(inspection: ISharkcraftInspection, kinds: readonly ReferenceKind[]): readonly ReferenceKind[];
+/** True when the CLI injected its command resolver for this inspection. */
+export declare function hasCommandResolver(inspection: ISharkcraftInspection): boolean;
+/**
+ * True once {@link warmReferenceRegistries} ran for this inspection's root.
+ *
+ * The cache-backed kinds read EMPTY until then, so a consumer that resolves
+ * them (a test runner checking `expectedPlaybooks`) can report "could not look"
+ * instead of "your correct id does not exist".
+ */
+export declare function isReferenceCacheWarm(inspection: ISharkcraftInspection): boolean;
+/** Ok / PrefixOnly / NotShrk: the string resolves (or is not ours to judge). */
+export declare function isCommandResolved(resolution: ICommandResolution): boolean;
+/**
+ * THE function every consumer calls to resolve a command string: knowledge
+ * `command` references and anchors, the self-config doctor's command probes,
+ * agent-test `expectedCommands`, the query resolver.
+ *
+ * The command index lives in the CLI, above this layer, so the answer comes
+ * from the resolver the CLI injected via `warmReferenceRegistries(inspection,
+ * { commandResolver })`. Without one the answer is `Unverified` — the string
+ * was NOT checked. It used to be `id.startsWith('shrk ')`, which certified
+ * every `shrk …` string (including three dead ones in shrk's own knowledge) as
+ * a real command, forever.
+ */
+export declare function resolveCommandReference(inspection: ISharkcraftInspection, raw: string, options?: ICommandResolveOptions): ICommandResolution;
+/**
+ * THE reading of a `command` REFERENCE — a knowledge `command` reference or
+ * anchor, an agent test's `expectedCommands`, the `command` reference kind.
+ *
+ * Such a string names a shrk command, so a bare form is read as one: `doctor`
+ * resolves, `frobnicate` is an unknown verb (see {@link ICommandResolveOptions}).
+ * knowledge-stale, the self-config doctor's reference probes and the agent-test
+ * runner all call THIS — they used to normalise the same string three ways
+ * (`frobnicate` was `ok` in one, `not-shrk` in another and `unknown-verb` in
+ * the third). Free shell text (a playbook step) goes through
+ * {@link resolveCommandReference} without the assumption.
+ */
+export declare function resolveShrkCommandReference(inspection: ISharkcraftInspection, command: string): ICommandResolution;
+/**
+ * Tri-state existence: `Exists` / `Missing` / `Unverifiable`.
+ *
+ * For `command`: Ok, PrefixOnly and NotShrk are `Exists`; every Unknown* is
+ * `Missing`; no injected resolver is `Unverifiable` (report it as NOT VERIFIED,
+ * never as Ok). Read as a command REFERENCE ({@link resolveShrkCommandReference}).
+ * Every other kind is `Exists` / `Missing` against its registry.
+ */
+export declare function referenceIdStatus(inspection: ISharkcraftInspection, kind: ReferenceKind, id: string): ReferenceIdStatus;
 /** True when `kind`'s ids come from an async-populated cache. */
 export declare function isCacheBackedKind(kind: ReferenceKind): boolean;
 /**
- * Whether `id` is registered under `kind`.
+ * Whether `id` is registered under `kind` — `true` only for
+ * {@link ReferenceIdStatus.Exists}.
  *
- * `command` keeps its historical permissiveness: the catalog is not always
- * populated, and a repo citing `shrk gen …` should not be told its own CLI
- * does not exist because an optional catalog was absent.
+ * For `command` this is `false` when no resolver was injected: an unverifiable
+ * command is not an existing one. A caller that must tell "missing" from
+ * "could not look" reads {@link referenceIdStatus} instead.
  */
 export declare function referenceIdExists(inspection: ISharkcraftInspection, kind: ReferenceKind, id: string): boolean;
 /**
@@ -107,6 +187,24 @@ export declare function referenceIdPool(inspection: ISharkcraftInspection, kinds
  * automatically.
  */
 export declare function referenceIdExistsInAnyKind(inspection: ISharkcraftInspection, id: string): boolean;
-/** The kind that accepted `id`, or `undefined` — for "resolved as what?" output. */
+/**
+ * EVERY kind whose registry lists `id`, most specific first (the order of
+ * {@link ALL_ID_REFERENCE_KINDS}) — empty when nothing does.
+ *
+ * Ids carry no namespace prefix, so one id can legitimately live in several
+ * registries: a rule is also a knowledge entry, and a template may share an id
+ * with a construct. "Which namespace did this resolve into?" therefore has a
+ * LIST as its honest answer; {@link referenceKindOf} is its first element.
+ */
+export declare function referenceKindsOf(inspection: ISharkcraftInspection, id: string): readonly ReferenceKind[];
+/** The most specific kind that accepted `id`, or `undefined` — for "resolved as what?" output. */
 export declare function referenceKindOf(inspection: ISharkcraftInspection, id: string): ReferenceKind | undefined;
+/**
+ * One-shot projection of {@link referenceIdsFor} over every kind, for O(1)
+ * membership when a caller resolves many ids at once (the declared
+ * cross-reference collector walks every asset). Not a second source: each set
+ * is built from `referenceIdsFor`, so list ≡ resolve still holds per kind.
+ * Snapshot semantics — rebuild it after a warm.
+ */
+export declare function referenceIdSets(inspection: ISharkcraftInspection): ReadonlyMap<ReferenceKind, ReadonlySet<string>>;
 //# sourceMappingURL=reference-registry.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"reference-registry.d.ts","sourceRoot":"","sources":["../src/reference-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAalE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,sBAAsB,GAAG,UAAU,CAAC;AAEnE;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,GACrB,gBAAgB,GAChB,WAAW,GACX,MAAM,GACN,UAAU,GACV,YAAY,GACZ,mBAAmB,GACnB,mBAAmB,GACnB,cAAc,GACd,mBAAmB,GACnB,kBAAkB,CAAC;AAEvB;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,aAAa,EAkB1D,CAAC;AAiDF;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwC9F;AAMD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,qBAAqB,EACjC,IAAI,EAAE,aAAa,GAClB,SAAS,MAAM,EAAE,CA6CnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,SAAS,aAAa,EAAE,GAC9B,SAAS,aAAa,EAAE,CAI1B;AAED,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAE9D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,qBAAqB,EACjC,IAAI,EAAE,aAAa,EACnB,EAAE,EAAE,MAAM,GACT,OAAO,CAOT;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,SAAS,aAAa,EAAE,GAC9B,SAAS,MAAM,EAAE,CAMnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,qBAAqB,EACjC,EAAE,EAAE,MAAM,GACT,OAAO,CAET;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAC7B,UAAU,EAAE,qBAAqB,EACjC,EAAE,EAAE,MAAM,GACT,aAAa,GAAG,SAAS,CAE3B"}
+{"version":3,"file":"reference-registry.d.ts","sourceRoot":"","sources":["../src/reference-registry.ts"],"names":[],"mappings":"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"}

package/dist/reference-registry.js

@@ -1,21 +1,39 @@
+import { CommandResolutionStatus } from "./command-resolution-status.js";
+import { ReferenceIdStatus } from "./reference-id-status.js";
 import { listConstructs, warmConstructCache } from "./construct-registry.js";
 import { listConventions } from "./convention-registry.js";
 import { loadAllContractTemplates } from "./contract-template-registry.js";
-import { listDecisions } from "./decision-records.js";
-import { HELPERS } from "./helper-registry.js";
+import { listDecisions, loadTsDecisions } from "./decision-records.js";
+import { listAllHelpers } from "./helper-catalog.js";
 import { listMigrationProfilesFromPacks } from "./migration-profile-registry.js";
-import { listPackHelpers } from "./pack-helper-registry.js";
 import { listPlaybooks, warmPlaybookCache } from "./playbook-registry.js";
 import { listPolicyIds, warmPolicyCache } from "./policy-registry.js";
+import { listWorkspaceProfileEntries } from "./profile-registry.js";
 import { listRegistrationHints } from "./registration-hint-registry.js";
 import { loadScaffoldPatternsFromInspection } from "./scaffold-patterns.js";
 import { listTaskRoutingHints } from "./task-routing-hint-registry.js";
 /**
  * Every kind that resolves against a registry of ids.
  *
- * `command` is deliberately absent: the catalog lives in the CLI package,
- * ABOVE this layer, so it resolves by shape instead of by list. `file` /
- * `directory` / `symbol` / `package` / `url` are not id registries at all.
+ * `command` is deliberately absent: the command index lives in the CLI
+ * package, ABOVE this layer, so it resolves through the resolver the CLI
+ * injects ({@link resolveCommandReference}) — never by shape, and never by a
+ * list this layer cannot see. `file` / `directory` / `symbol` / `package` /
+ * `url` are not id registries at all.
+ *
+ * **List order is SPECIFICITY.** A rule and a path convention are knowledge
+ * entries filtered by type, so `knowledge` is a SUPERSET of both and must come
+ * after them: {@link referenceKindsOf} returns kinds in this order, so its first
+ * element names the most specific registry. With `knowledge` listed first,
+ * every rule id used to report `knowledge` as "the" kind it resolved as.
+ *
+ * **Every kind here is DECLARABLE** (round 12): `REFERENCE_KIND_DECLARATIONS`
+ * is a `Record<IdReferenceKind, …>`, so a kind added here without a row saying
+ * how its ids come to exist is a compile error, and the r76 declarability lock
+ * proves every path in that row fills this resolver. `workspace-profile` is
+ * the builtin WorkspaceProfile vocabulary — the applicability filters'
+ * `profileIds` resolve against it (they were bound to `migration-profile`, a
+ * readiness registry, and sat at NOT VERIFIED forever).
  */
 export const ALL_ID_REFERENCE_KINDS = [
     'template',
@@ -26,12 +44,13 @@ export const ALL_ID_REFERENCE_KINDS = [
     'helper',
     'boundary-rule',
     'path-convention',
-    'knowledge',
     'rule',
+    'knowledge',
     'decision',
     'convention',
     'contract-template',
     'migration-profile',
+    'workspace-profile',
     'routing-hint',
     'registration-hint',
     'scaffold-pattern',
@@ -61,9 +80,28 @@ const CACHE_BACKED_KINDS = [
     'routing-hint',
     'registration-hint',
     'scaffold-pattern',
+    // TS decisions (`sharkcraft/decisions.ts`, pack `decisionFiles`) reach the
+    // sync `listDecisions` only after the warm loads them, so an unwarmed lookup
+    // of a declared decision reads "missing" — a cache-backed kind, covered by
+    // the same "could not look" safety net (round 12 review, R12-DOC-5).
+    'decision',
 ];
 /** Snapshot of the async-loaded kinds, per project root. */
 const ASYNC_IDS = new Map();
+/**
+ * The injected command resolver, per inspection OBJECT.
+ *
+ * Keyed by the inspection rather than the project root so a resolver injected
+ * for one run can never leak into an unrelated inspection of the same root —
+ * an engine call that was never given one must stay `Unverifiable`. A later
+ * warm WITHOUT a resolver (an inner engine call re-warming the same
+ * inspection) keeps the one already injected.
+ */
+const COMMAND_RESOLVERS = new WeakMap();
+/** The command-REFERENCE reading: a bare command-word head names a shrk verb. */
+const SHRK_COMMAND_REFERENCE = Object.freeze({ assumeShrk: true });
+/** The loud-skip message every consumer prints for an un-injected command index. */
+export const COMMAND_INDEX_NOT_INJECTED = 'command index not injected — NOT VERIFIED';
 async function safeIds(load) {
     try {
         return await load();
@@ -83,15 +121,26 @@ async function safeIds(load) {
  * resolving anything. Without it a correct playbook — or convention, or
  * scaffold pattern — resolves to nothing, which is exactly how a correct id got
  * reported as an error twice.
+ *
+ * `options.commandResolver` is the CLI's command-string resolver (the command
+ * index lives above this layer). Without one, every `command` reference is
+ * `Unverifiable` — see {@link resolveCommandReference}.
  */
-export async function warmReferenceRegistries(inspection) {
+export async function warmReferenceRegistries(inspection, options = {}) {
+    if (options.commandResolver)
+        COMMAND_RESOLVERS.set(inspection, options.commandResolver);
     await Promise.all([
         warmPlaybookCache(inspection),
         warmConstructCache(inspection),
         warmPolicyCache(inspection),
+        // TS decisions (`sharkcraft/decisions.ts`, pack `decisionFiles`) reach the
+        // sync `listDecisions` only through this cache. Unwarmed, a declared
+        // decision resolved as nothing — the r76 declarability lock found it.
+        loadTsDecisions(inspection).catch(() => []),
     ]);
     const [packHelpers, conventions, contractTemplates, migrationProfiles, routingHints, registrationHints, scaffoldPatterns,] = await Promise.all([
-        safeIds(async () => (await listPackHelpers(inspection)).map((e) => e.helper.id)),
+        // THE helper catalog — the same list `shrk helper list` prints.
+        safeIds(async () => (await listAllHelpers(inspection)).entries.map((h) => h.id)),
         safeIds(async () => (await listConventions(inspection)).map((e) => e.convention.id)),
         safeIds(async () => (await loadAllContractTemplates(inspection)).entries.map((e) => e.template.id)),
         safeIds(async () => (await listMigrationProfilesFromPacks(inspection)).map((p) => p.id)),
@@ -100,10 +149,11 @@ export async function warmReferenceRegistries(inspection) {
         safeIds(async () => (await loadScaffoldPatternsFromInspection(inspection)).patterns.map((e) => e.pattern.id)),
     ]);
     ASYNC_IDS.set(inspection.projectRoot, new Map([
-        // Built-in helpers need no load; pack-contributed ones do. The doc
-        // resolver used to see only the built-ins (an empty frozen array) while
-        // the doctor saw both — a live divergence between the two paths.
-        ['helper', [...HELPERS.map((h) => h.id), ...packHelpers]],
+        // Built-ins ∪ pack/local helpers, from the one catalog `helper
+        // list|get|plan` read — so list ≡ resolve by construction. (The doc
+        // resolver used to see only the built-ins while the doctor saw both,
+        // and `helper get` saw neither.)
+        ['helper', packHelpers],
         ['convention', conventions],
         ['contract-template', contractTemplates],
         ['migration-profile', migrationProfiles],
@@ -152,6 +202,11 @@ export function referenceIdsFor(inspection, kind) {
         case 'policy':
             // Declarations only — `evaluatePolicy` is the one that RUNS them.
             return listPolicyIds(inspection);
+        case 'workspace-profile':
+            // THE builtin WorkspaceProfile vocabulary — the same function `shrk
+            // profiles list --kind workspace` prints, so list ≡ resolve by
+            // construction. Sync and never empty: it can never loud-skip.
+            return listWorkspaceProfileEntries(inspection).map((e) => e.id);
         case 'helper':
         case 'convention':
         case 'contract-template':
@@ -161,9 +216,10 @@ export function referenceIdsFor(inspection, kind) {
         case 'scaffold-pattern':
             return asyncIds(inspection, kind);
         case 'command':
-            // The command catalog lives in the CLI package, ABOVE this layer, so it
-            // cannot be imported here. `referenceIdExists` keeps the permissive
-            // shape check instead of pretending to a list it cannot see.
+            // The command index lives in the CLI package, ABOVE this layer, so it
+            // cannot be listed here. Existence goes through the injected resolver
+            // (`resolveCommandReference`) — never through a list this layer cannot
+            // see, and never through the shape of the string.
             return [];
         default:
             // `file` / `directory` / `symbol` / `package` / `url` are not id
@@ -180,29 +236,104 @@ export function referenceIdsFor(inspection, kind) {
  * to get a gate switched off. Emptiness is repo-dependent (a project may simply
  * have no playbooks), so it cannot be a config-time error; the caller surfaces
  * it as a loud refusal at run time instead.
+ *
+ * `command` has no list; it can resolve exactly when a resolver was injected.
+ * Without one it is reported here — nothing could resolve, so every command
+ * would be reported wrong (or, before round 11, every `shrk …` string right).
  */
 export function emptyReferenceKinds(inspection, kinds) {
-    return kinds.filter((kind) => kind !== 'command' && referenceIdsFor(inspection, kind).length === 0);
+    return kinds.filter((kind) => kind === 'command'
+        ? !hasCommandResolver(inspection)
+        : referenceIdsFor(inspection, kind).length === 0);
+}
+/** True when the CLI injected its command resolver for this inspection. */
+export function hasCommandResolver(inspection) {
+    return COMMAND_RESOLVERS.has(inspection);
+}
+/**
+ * True once {@link warmReferenceRegistries} ran for this inspection's root.
+ *
+ * The cache-backed kinds read EMPTY until then, so a consumer that resolves
+ * them (a test runner checking `expectedPlaybooks`) can report "could not look"
+ * instead of "your correct id does not exist".
+ */
+export function isReferenceCacheWarm(inspection) {
+    return ASYNC_IDS.has(inspection.projectRoot);
+}
+/** Ok / PrefixOnly / NotShrk: the string resolves (or is not ours to judge). */
+export function isCommandResolved(resolution) {
+    return (resolution.status === CommandResolutionStatus.Ok ||
+        resolution.status === CommandResolutionStatus.PrefixOnly ||
+        resolution.status === CommandResolutionStatus.NotShrk);
+}
+/**
+ * THE function every consumer calls to resolve a command string: knowledge
+ * `command` references and anchors, the self-config doctor's command probes,
+ * agent-test `expectedCommands`, the query resolver.
+ *
+ * The command index lives in the CLI, above this layer, so the answer comes
+ * from the resolver the CLI injected via `warmReferenceRegistries(inspection,
+ * { commandResolver })`. Without one the answer is `Unverified` — the string
+ * was NOT checked. It used to be `id.startsWith('shrk ')`, which certified
+ * every `shrk …` string (including three dead ones in shrk's own knowledge) as
+ * a real command, forever.
+ */
+export function resolveCommandReference(inspection, raw, options = {}) {
+    const resolver = COMMAND_RESOLVERS.get(inspection);
+    if (!resolver) {
+        return { status: CommandResolutionStatus.Unverified, reason: COMMAND_INDEX_NOT_INJECTED };
+    }
+    return resolver(raw, options);
+}
+/**
+ * THE reading of a `command` REFERENCE — a knowledge `command` reference or
+ * anchor, an agent test's `expectedCommands`, the `command` reference kind.
+ *
+ * Such a string names a shrk command, so a bare form is read as one: `doctor`
+ * resolves, `frobnicate` is an unknown verb (see {@link ICommandResolveOptions}).
+ * knowledge-stale, the self-config doctor's reference probes and the agent-test
+ * runner all call THIS — they used to normalise the same string three ways
+ * (`frobnicate` was `ok` in one, `not-shrk` in another and `unknown-verb` in
+ * the third). Free shell text (a playbook step) goes through
+ * {@link resolveCommandReference} without the assumption.
+ */
+export function resolveShrkCommandReference(inspection, command) {
+    return resolveCommandReference(inspection, command, SHRK_COMMAND_REFERENCE);
+}
+/**
+ * Tri-state existence: `Exists` / `Missing` / `Unverifiable`.
+ *
+ * For `command`: Ok, PrefixOnly and NotShrk are `Exists`; every Unknown* is
+ * `Missing`; no injected resolver is `Unverifiable` (report it as NOT VERIFIED,
+ * never as Ok). Read as a command REFERENCE ({@link resolveShrkCommandReference}).
+ * Every other kind is `Exists` / `Missing` against its registry.
+ */
+export function referenceIdStatus(inspection, kind, id) {
+    if (kind === 'command') {
+        const resolution = resolveShrkCommandReference(inspection, id);
+        if (resolution.status === CommandResolutionStatus.Unverified) {
+            return ReferenceIdStatus.Unverifiable;
+        }
+        return isCommandResolved(resolution) ? ReferenceIdStatus.Exists : ReferenceIdStatus.Missing;
+    }
+    return referenceIdsFor(inspection, kind).includes(id)
+        ? ReferenceIdStatus.Exists
+        : ReferenceIdStatus.Missing;
 }
 /** True when `kind`'s ids come from an async-populated cache. */
 export function isCacheBackedKind(kind) {
     return CACHE_BACKED_KINDS.includes(kind);
 }
 /**
- * Whether `id` is registered under `kind`.
+ * Whether `id` is registered under `kind` — `true` only for
+ * {@link ReferenceIdStatus.Exists}.
  *
- * `command` keeps its historical permissiveness: the catalog is not always
- * populated, and a repo citing `shrk gen …` should not be told its own CLI
- * does not exist because an optional catalog was absent.
+ * For `command` this is `false` when no resolver was injected: an unverifiable
+ * command is not an existing one. A caller that must tell "missing" from
+ * "could not look" reads {@link referenceIdStatus} instead.
  */
 export function referenceIdExists(inspection, kind, id) {
-    if (kind === 'command') {
-        const catalog = inspection.commandCatalog;
-        if (Array.isArray(catalog) && catalog.some((c) => c.id === id))
-            return true;
-        return id.startsWith('shrk ') || id.startsWith('bun ');
-    }
-    return referenceIdsFor(inspection, kind).includes(id);
+    return referenceIdStatus(inspection, kind, id) === ReferenceIdStatus.Exists;
 }
 /**
  * The union of candidate ids across `kinds`, deduped and sorted.
@@ -233,7 +364,32 @@ export function referenceIdPool(inspection, kinds) {
 export function referenceIdExistsInAnyKind(inspection, id) {
     return ALL_ID_REFERENCE_KINDS.some((kind) => referenceIdsFor(inspection, kind).includes(id));
 }
-/** The kind that accepted `id`, or `undefined` — for "resolved as what?" output. */
+/**
+ * EVERY kind whose registry lists `id`, most specific first (the order of
+ * {@link ALL_ID_REFERENCE_KINDS}) — empty when nothing does.
+ *
+ * Ids carry no namespace prefix, so one id can legitimately live in several
+ * registries: a rule is also a knowledge entry, and a template may share an id
+ * with a construct. "Which namespace did this resolve into?" therefore has a
+ * LIST as its honest answer; {@link referenceKindOf} is its first element.
+ */
+export function referenceKindsOf(inspection, id) {
+    return ALL_ID_REFERENCE_KINDS.filter((kind) => referenceIdsFor(inspection, kind).includes(id));
+}
+/** The most specific kind that accepted `id`, or `undefined` — for "resolved as what?" output. */
 export function referenceKindOf(inspection, id) {
-    return ALL_ID_REFERENCE_KINDS.find((kind) => referenceIdsFor(inspection, kind).includes(id));
+    return referenceKindsOf(inspection, id)[0];
+}
+/**
+ * One-shot projection of {@link referenceIdsFor} over every kind, for O(1)
+ * membership when a caller resolves many ids at once (the declared
+ * cross-reference collector walks every asset). Not a second source: each set
+ * is built from `referenceIdsFor`, so list ≡ resolve still holds per kind.
+ * Snapshot semantics — rebuild it after a warm.
+ */
+export function referenceIdSets(inspection) {
+    const out = new Map();
+    for (const kind of ALL_ID_REFERENCE_KINDS)
+        out.set(kind, new Set(referenceIdsFor(inspection, kind)));
+    return out;
 }

package/dist/reference-subject.d.ts

@@ -0,0 +1,20 @@
+import type { IAssetReference } from '@shrkcrft/core';
+import type { IKnowledgeAnchor } from '@shrkcrft/knowledge';
+import type { ReferenceAssetKind } from './reference-asset-kind.js';
+/**
+ * Anything the staleness sweep verifies references for: a knowledge entry, a
+ * boundary rule, or a declared policy check. The sweep's per-subject loop is
+ * written once against this shape, so every asset kind is checked by the same
+ * reference checker — never a second one that drifts.
+ */
+export interface IReferenceSubject {
+    readonly assetKind: ReferenceAssetKind;
+    readonly id: string;
+    /** Where it is declared, relative to the project root, when known. */
+    readonly source?: string;
+    /** Knowledge `type`, for knowledge subjects. */
+    readonly type?: string;
+    readonly references: readonly IAssetReference[];
+    readonly anchors?: readonly IKnowledgeAnchor[];
+}
+//# sourceMappingURL=reference-subject.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reference-subject.d.ts","sourceRoot":"","sources":["../src/reference-subject.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,gDAAgD;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAChD"}

package/dist/reference-subject.js

@@ -0,0 +1 @@
+export {};

package/dist/registration-hint-discovery-status.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What a registration hint's discovery found on the live file system — the
+ * same answer `registrations preview` acts on.
+ *
+ * A doctor's "0 issues" used to be read as "every hint verified", while glob
+ * discovery was never checked at all: the hints whose author was LEAST sure of
+ * the target got the LEAST verification.
+ */
+export declare enum RegistrationHintDiscoveryStatus {
+    /** Exactly one target file (a fixed `targetFile` that exists, or a glob matching one file). */
+    Verified = "verified",
+    /** A glob matched more than one file — preview refuses to guess. */
+    Ambiguous = "ambiguous",
+    /** No file: a missing fixed target, a glob matching nothing, or no discovery at all. */
+    Dead = "dead",
+    /** The discovery walk hit its directory cap, so the candidate set is incomplete. */
+    Unverified = "unverified",
+    /**
+     * No file yet, and every selector that matched nothing is marked
+     * `{ pattern, expectEmpty: true }` (round 13): the hint targets what the
+     * adopting app does not have yet — accepted (printed), never `dead`.
+     */
+    IntendedEmpty = "intended-empty"
+}
+//# sourceMappingURL=registration-hint-discovery-status.d.ts.map

package/dist/registration-hint-discovery-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration-hint-discovery-status.d.ts","sourceRoot":"","sources":["../src/registration-hint-discovery-status.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,oBAAY,+BAA+B;IACzC,+FAA+F;IAC/F,QAAQ,aAAa;IACrB,oEAAoE;IACpE,SAAS,cAAc;IACvB,wFAAwF;IACxF,IAAI,SAAS;IACb,oFAAoF;IACpF,UAAU,eAAe;IACzB;;;;OAIG;IACH,aAAa,mBAAmB;CACjC"}

package/dist/registration-hint-discovery-status.js

@@ -0,0 +1,25 @@
+/**
+ * What a registration hint's discovery found on the live file system — the
+ * same answer `registrations preview` acts on.
+ *
+ * A doctor's "0 issues" used to be read as "every hint verified", while glob
+ * discovery was never checked at all: the hints whose author was LEAST sure of
+ * the target got the LEAST verification.
+ */
+export var RegistrationHintDiscoveryStatus;
+(function (RegistrationHintDiscoveryStatus) {
+    /** Exactly one target file (a fixed `targetFile` that exists, or a glob matching one file). */
+    RegistrationHintDiscoveryStatus["Verified"] = "verified";
+    /** A glob matched more than one file — preview refuses to guess. */
+    RegistrationHintDiscoveryStatus["Ambiguous"] = "ambiguous";
+    /** No file: a missing fixed target, a glob matching nothing, or no discovery at all. */
+    RegistrationHintDiscoveryStatus["Dead"] = "dead";
+    /** The discovery walk hit its directory cap, so the candidate set is incomplete. */
+    RegistrationHintDiscoveryStatus["Unverified"] = "unverified";
+    /**
+     * No file yet, and every selector that matched nothing is marked
+     * `{ pattern, expectEmpty: true }` (round 13): the hint targets what the
+     * adopting app does not have yet — accepted (printed), never `dead`.
+     */
+    RegistrationHintDiscoveryStatus["IntendedEmpty"] = "intended-empty";
+})(RegistrationHintDiscoveryStatus || (RegistrationHintDiscoveryStatus = {}));