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

package/dist/reference-registry.d.ts

@@ -0,0 +1,210 @@
+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.
+ *
+ * `knowledge-stale` already answered "does this id exist?" per kind, one
+ * private `*Exists` helper at a time. The doc-reference linter needs the same
+ * answer AND the candidate LIST (to suggest what the author meant), so the
+ * lookup moves here and both consume it. Two implementations of "which
+ * template ids exist" would eventually disagree, and the one nobody runs would
+ * be the wrong one.
+ *
+ * Every list is read defensively off the inspection: these registries are
+ * populated by different layers and a repo may legitimately have none of a
+ * given kind, which must read as "no candidates", never as a crash.
+ */
+/**
+ * Kinds a DOC reference may resolve against.
+ *
+ * A superset of `KnowledgeReferenceKind`: `pipeline` is a real registry that
+ * prose cites constantly (`the spine pipelines (engine.feature-dev, …)`) but
+ * that a knowledge entry has never had a structured reference kind for. The
+ * doc plane owns its own list rather than widening the knowledge contract for
+ * a need only this surface has.
+ */
+export type DocReferenceKind = KnowledgeReferenceKind | 'pipeline';
+/**
+ * EVERY kind this engine can answer "does this id exist?" for.
+ *
+ * A superset of `DocReferenceKind`: the self-config doctor cross-references
+ * kinds prose never cites (a decision record, a scaffold pattern, a routing
+ * hint). It used to answer for them from its OWN lookup sets, built from its
+ * own sources — so "one definition of does-this-id-exist" was a doc claim, not
+ * a property of the code, and the two answers agreed only by coincidence. They
+ * did not always: `sharkcraft.mcp-read-only` is a declared policy that the
+ * doctor's pack-only policy set reported as unknown.
+ *
+ * `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' | 'workspace-profile' | 'routing-hint' | 'registration-hint' | 'scaffold-pattern';
+/**
+ * Every kind that resolves against a registry of ids.
+ *
+ * `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 ["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.
+ *
+ * Call this once, from the async layer that owns the inspection, before
+ * 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, options?: IReferenceWarmOptions): Promise<void>;
+/**
+ * Every registered id of `kind`, for existence checks and for suggesting what
+ * an unresolved token might have meant.
+ *
+ * **The invariant:** each kind reads the SAME source its `list` verb reads.
+ * `template` goes through `templateRegistry` because that is what `shrk
+ * templates list` prints — not the `templates` array it happens to be built
+ * from today, which would agree only until someone filters one of them.
+ */
+export declare function referenceIdsFor(inspection: ISharkcraftInspection, kind: ReferenceKind): readonly string[];
+/**
+ * Kinds among `kinds` whose registry is EMPTY in this repo.
+ *
+ * This is the generalisation of the bug that prompted it: resolving against an
+ * empty registry cannot succeed, so every id checked against it is reported
+ * wrong — a gate confidently flagging CORRECT usage, which is the fastest way
+ * 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` — `true` only for
+ * {@link ReferenceIdStatus.Exists}.
+ *
+ * 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;
+/**
+ * The union of candidate ids across `kinds`, deduped and sorted.
+ *
+ * A doc token is checked against several registries at once (a `nge.foo` might
+ * be a template OR a playbook), so the suggester needs one pool rather than
+ * per-kind lists that would each propose their own nearest miss.
+ */
+export declare function referenceIdPool(inspection: ISharkcraftInspection, kinds: readonly ReferenceKind[]): readonly string[];
+/**
+ * Whether `id` is registered under ANY kind.
+ *
+ * For cross-references that do not name a kind — a search-tuning entry boosts
+ * "some id", a decision record relates to "some id". That union used to be
+ * hand-written as a chain of `lookups.x.has(id) || lookups.y.has(id) || …`,
+ * which is a list that silently goes stale: it omitted policies, decisions and
+ * scaffold patterns, so seven of shrk's own correctly-registered ids were
+ * reported unknown. Reading the kind list means adding a kind widens the union
+ * automatically.
+ */
+export declare function referenceIdExistsInAnyKind(inspection: ISharkcraftInspection, id: string): boolean;
+/**
+ * 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

@@ -0,0 +1 @@
+{"version":3,"file":"reference-registry.d.ts","sourceRoot":"","sources":["../src/reference-registry.ts"],"names":[],"mappings":"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"}

package/dist/reference-registry.js

@@ -0,0 +1,395 @@
+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, loadTsDecisions } from "./decision-records.js";
+import { listAllHelpers } from "./helper-catalog.js";
+import { listMigrationProfilesFromPacks } from "./migration-profile-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 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',
+    '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',
+];
+function listIds(reg) {
+    if (!reg || typeof reg.list !== 'function')
+        return [];
+    return (reg.list() ?? []).map((r) => r.id);
+}
+/**
+ * Kinds whose ids only exist after an ASYNC load.
+ *
+ * The resolver is synchronous — a doc linter walks lines, and a lookup set is
+ * built once — so these are read from a snapshot that {@link
+ * warmReferenceRegistries} fills. An unwarmed snapshot is empty, which reads as
+ * "no such id" for every id; {@link emptyReferenceKinds} is the safety net for
+ * when a caller forgets.
+ */
+const CACHE_BACKED_KINDS = [
+    'playbook',
+    'construct',
+    'policy',
+    'helper',
+    'convention',
+    'contract-template',
+    'migration-profile',
+    '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();
+    }
+    catch {
+        // A registry that will not load is its OWN surface's problem to report.
+        // Resolution must degrade to "no candidates", never to a crash — but never
+        // silently to "your id is wrong" either, which is what the empty-kind guard
+        // is for.
+        return [];
+    }
+}
+/**
+ * Populate the snapshot the synchronous accessors read.
+ *
+ * Call this once, from the async layer that owns the inspection, before
+ * 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, 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([
+        // 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)),
+        safeIds(async () => (await listTaskRoutingHints(inspection)).map((e) => e.hint.id)),
+        safeIds(async () => (await listRegistrationHints(inspection)).map((e) => e.hint.id)),
+        safeIds(async () => (await loadScaffoldPatternsFromInspection(inspection)).patterns.map((e) => e.pattern.id)),
+    ]);
+    ASYNC_IDS.set(inspection.projectRoot, new Map([
+        // 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],
+        ['routing-hint', routingHints],
+        ['registration-hint', registrationHints],
+        ['scaffold-pattern', scaffoldPatterns],
+    ]));
+}
+function asyncIds(inspection, kind) {
+    return ASYNC_IDS.get(inspection.projectRoot)?.get(kind) ?? [];
+}
+/**
+ * Every registered id of `kind`, for existence checks and for suggesting what
+ * an unresolved token might have meant.
+ *
+ * **The invariant:** each kind reads the SAME source its `list` verb reads.
+ * `template` goes through `templateRegistry` because that is what `shrk
+ * templates list` prints — not the `templates` array it happens to be built
+ * from today, which would agree only until someone filters one of them.
+ */
+export function referenceIdsFor(inspection, kind) {
+    switch (kind) {
+        case 'template':
+            return listIds(inspection.templateRegistry);
+        case 'pipeline':
+            return listIds(inspection.pipelineRegistry);
+        case 'rule':
+            return listIds(inspection.ruleService);
+        case 'boundary-rule':
+            return listIds(inspection.boundaryRegistry);
+        case 'path-convention':
+            return listIds(inspection.pathService);
+        case 'knowledge':
+            return inspection.knowledgeEntries.map((k) => k.id);
+        case 'decision':
+            try {
+                return listDecisions(inspection).map((d) => d.id);
+            }
+            catch {
+                return [];
+            }
+        case 'playbook':
+            return listPlaybooks(inspection).map((p) => p.id);
+        case 'construct':
+            return listConstructs(inspection).map((c) => c.id);
+        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':
+        case 'migration-profile':
+        case 'routing-hint':
+        case 'registration-hint':
+        case 'scaffold-pattern':
+            return asyncIds(inspection, kind);
+        case 'command':
+            // 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
+            // registries; they resolve against the filesystem or not at all.
+            return [];
+    }
+}
+/**
+ * Kinds among `kinds` whose registry is EMPTY in this repo.
+ *
+ * This is the generalisation of the bug that prompted it: resolving against an
+ * empty registry cannot succeed, so every id checked against it is reported
+ * wrong — a gate confidently flagging CORRECT usage, which is the fastest way
+ * 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'
+        ? !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` — `true` only for
+ * {@link ReferenceIdStatus.Exists}.
+ *
+ * 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) {
+    return referenceIdStatus(inspection, kind, id) === ReferenceIdStatus.Exists;
+}
+/**
+ * The union of candidate ids across `kinds`, deduped and sorted.
+ *
+ * A doc token is checked against several registries at once (a `nge.foo` might
+ * be a template OR a playbook), so the suggester needs one pool rather than
+ * per-kind lists that would each propose their own nearest miss.
+ */
+export function referenceIdPool(inspection, kinds) {
+    const pool = new Set();
+    for (const kind of kinds) {
+        for (const id of referenceIdsFor(inspection, kind))
+            pool.add(id);
+    }
+    return [...pool].sort();
+}
+/**
+ * Whether `id` is registered under ANY kind.
+ *
+ * For cross-references that do not name a kind — a search-tuning entry boosts
+ * "some id", a decision record relates to "some id". That union used to be
+ * hand-written as a chain of `lookups.x.has(id) || lookups.y.has(id) || …`,
+ * which is a list that silently goes stale: it omitted policies, decisions and
+ * scaffold patterns, so seven of shrk's own correctly-registered ids were
+ * reported unknown. Reading the kind list means adding a kind widens the union
+ * automatically.
+ */
+export function referenceIdExistsInAnyKind(inspection, id) {
+    return ALL_ID_REFERENCE_KINDS.some((kind) => referenceIdsFor(inspection, kind).includes(id));
+}
+/**
+ * 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 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