@shrkcrft/boundaries 0.1.0-alpha.23 → 0.1.0-alpha.24

package/dist/index.d.ts

@@ -7,7 +7,10 @@ export * from './evaluate/evaluate-boundaries.js';
 export * from './scan/tsconfig-aliases.js';
 export * from './wiring/evaluate-wiring.js';
 export * from './wiring/scan-wiring-files.js';
+export * from './wiring/explain-wiring.js';
 export * from './wiring/registry-query.js';
+export * from './wiring/registration-graph.js';
+export * from './wiring/trace-literal.js';
 export * from './policy/extract-templates.js';
 export * from './policy/evaluate-policy.js';
 export * from './policy/run-policy.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,mCAAmC,CAAC;AAClD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,mCAAmC,CAAC;AAClD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -7,7 +7,10 @@ export * from "./evaluate/evaluate-boundaries.js";
 export * from "./scan/tsconfig-aliases.js";
 export * from "./wiring/evaluate-wiring.js";
 export * from "./wiring/scan-wiring-files.js";
+export * from "./wiring/explain-wiring.js";
 export * from "./wiring/registry-query.js";
+export * from "./wiring/registration-graph.js";
+export * from "./wiring/trace-literal.js";
 export * from "./policy/extract-templates.js";
 export * from "./policy/evaluate-policy.js";
 export * from "./policy/run-policy.js";

package/dist/wiring/explain-wiring.d.ts

@@ -0,0 +1,53 @@
+import type { IWiringRule } from '@shrkcrft/core';
+import { type IWiringTokenSite } from './evaluate-wiring.js';
+export declare const WIRING_EXPLAIN_SCHEMA: "sharkcraft.wiring-explain/v1";
+/** One side (declared or registered) of a wiring rule, as extracted from the tree. */
+export interface IWiringSideExplain {
+    /** Every capture site (token + file:line), stable-sorted by (file, line). */
+    readonly sites: readonly IWiringTokenSite[];
+    /** Distinct membership-key count (mirrors the gate's `declared/registered N`). */
+    readonly distinctCount: number;
+    /** Files scanned for this side (after glob resolution). */
+    readonly filesScanned: number;
+    /** Misconfiguration (bad regex / no capture group / bad source), if any. */
+    readonly error?: string;
+}
+/**
+ * The full intermediate output of evaluating ONE wiring rule against the live
+ * tree: the declared set and the registered set each source extracted (with
+ * file:line), plus the set-difference and verdict — the thing {@link
+ * evaluateWiring} computes internally but only emits as counts + violations.
+ */
+export interface IWiringExplain {
+    readonly schema: typeof WIRING_EXPLAIN_SCHEMA;
+    readonly ruleId: string;
+    readonly description?: string;
+    readonly mode: 'subset' | 'parity';
+    readonly groupBy?: 'dir' | 'package';
+    readonly severity: 'error' | 'warning';
+    readonly declared: IWiringSideExplain;
+    readonly registered: IWiringSideExplain;
+    /** Declared tokens absent from the registered set (the `declared-missing` diff). */
+    readonly declaredNotRegistered: readonly IWiringTokenSite[];
+    /** Registered tokens absent from the declared set (parity-only `registered-missing`). */
+    readonly registeredNotDeclared: readonly IWiringTokenSite[];
+    readonly verdict: 'pass' | 'errors' | 'warnings';
+    /** Rule-level misconfiguration messages (engine degrades gracefully). */
+    readonly diagnostics: readonly string[];
+}
+export interface IExplainWiringOptions {
+    /** Project-relative directories to prune from the walk. */
+    readonly excludeDirs?: readonly string[];
+}
+/**
+ * Dry-run a single wiring rule against the live tree and return what each side
+ * extracted (declared set, registered set, the set-difference, the verdict) —
+ * WITHOUT writing config. Powers `wiring explain <ruleId>`, `wiring test
+ * <candidate>`, and `check wiring --explain <ruleId>`: the author can SEE the
+ * alias-resolved cross-file set-difference the gate computes before committing
+ * a rule. The diff/verdict reuse {@link evaluateWiring} so they match the gate
+ * exactly (incl. `groupBy` membership); the full per-site lists are extracted
+ * with the shared {@link collectSourceSites}. Never throws.
+ */
+export declare function explainWiring(projectRoot: string, rule: IWiringRule, options?: IExplainWiringOptions): IWiringExplain;
+//# sourceMappingURL=explain-wiring.d.ts.map

package/dist/wiring/explain-wiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain-wiring.d.ts","sourceRoot":"","sources":["../../src/wiring/explain-wiring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,gBAAgB,CAAC;AAGjE,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,qBAAqB,EAAG,8BAAuC,CAAC;AAE7E,sFAAsF;AACtF,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5C,kFAAkF;IAClF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,qBAAqB,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,oFAAoF;IACpF,QAAQ,CAAC,qBAAqB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5D,yFAAyF;IACzF,QAAQ,CAAC,qBAAqB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;IACjD,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,qBAAqB;IACpC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAYD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,WAAW,EACjB,OAAO,GAAE,qBAA0B,GAClC,cAAc,CAmEhB"}

package/dist/wiring/explain-wiring.js

@@ -0,0 +1,81 @@
+import { matchesAny } from "../scan/glob.js";
+import { readMatchingFiles } from "../util/walk-files.js";
+import { collectSourceSites, evaluateWiring, } from "./evaluate-wiring.js";
+export const WIRING_EXPLAIN_SCHEMA = 'sharkcraft.wiring-explain/v1';
+function registeredSources(reg) {
+    return Array.isArray(reg) ? reg : [reg];
+}
+function sortSites(sites) {
+    return [...sites].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.token.localeCompare(b.token));
+}
+/**
+ * Dry-run a single wiring rule against the live tree and return what each side
+ * extracted (declared set, registered set, the set-difference, the verdict) —
+ * WITHOUT writing config. Powers `wiring explain <ruleId>`, `wiring test
+ * <candidate>`, and `check wiring --explain <ruleId>`: the author can SEE the
+ * alias-resolved cross-file set-difference the gate computes before committing
+ * a rule. The diff/verdict reuse {@link evaluateWiring} so they match the gate
+ * exactly (incl. `groupBy` membership); the full per-site lists are extracted
+ * with the shared {@link collectSourceSites}. Never throws.
+ */
+export function explainWiring(projectRoot, rule, options = {}) {
+    const regSources = registeredSources(rule.registered);
+    const allGlobs = [
+        ...new Set([...rule.declared.files, ...regSources.flatMap((s) => [...s.files])]),
+    ];
+    const cache = readMatchingFiles(projectRoot, allGlobs, new Set(options.excludeDirs ?? []));
+    const entries = [...cache.entries()].map(([path, content]) => ({
+        path,
+        content,
+    }));
+    const filesFor = (source) => entries.filter((f) => matchesAny(f.path, source.files));
+    // Declared side — full sites.
+    const declaredFiles = filesFor(rule.declared);
+    const declaredRes = collectSourceSites(rule.declared, declaredFiles);
+    // Registered side — union of every source, full sites.
+    const registeredFiles = new Set();
+    const registeredSites = [];
+    let registeredError;
+    for (const source of regSources) {
+        const files = filesFor(source);
+        for (const f of files)
+            registeredFiles.add(f.path);
+        const res = collectSourceSites(source, files);
+        if (res.error && !registeredError)
+            registeredError = res.error;
+        registeredSites.push(...res.sites);
+    }
+    // Canonical diff + counts + verdict from the gate engine (same groupBy logic).
+    const report = evaluateWiring([rule], filesFor);
+    const ruleResult = report.rules[0];
+    const declaredNotRegistered = sortSites((ruleResult?.violations ?? [])
+        .filter((v) => v.direction === 'declared-missing')
+        .map((v) => ({ token: v.token, file: v.file, line: v.line })));
+    const registeredNotDeclared = sortSites((ruleResult?.violations ?? [])
+        .filter((v) => v.direction === 'registered-missing')
+        .map((v) => ({ token: v.token, file: v.file, line: v.line })));
+    return {
+        schema: WIRING_EXPLAIN_SCHEMA,
+        ruleId: rule.id,
+        ...(rule.description ? { description: rule.description } : {}),
+        mode: rule.mode === 'parity' ? 'parity' : 'subset',
+        ...(rule.groupBy ? { groupBy: rule.groupBy } : {}),
+        severity: rule.severity ?? 'error',
+        declared: {
+            sites: sortSites(declaredRes.sites),
+            distinctCount: ruleResult?.declaredCount ?? 0,
+            filesScanned: declaredFiles.length,
+            ...(declaredRes.error ? { error: declaredRes.error } : {}),
+        },
+        registered: {
+            sites: sortSites(registeredSites),
+            distinctCount: ruleResult?.registeredCount ?? 0,
+            filesScanned: registeredFiles.size,
+            ...(registeredError ? { error: registeredError } : {}),
+        },
+        declaredNotRegistered,
+        registeredNotDeclared,
+        verdict: report.verdict,
+        diagnostics: report.diagnostics,
+    };
+}

package/dist/wiring/registration-graph.d.ts

@@ -0,0 +1,92 @@
+import type { IRegistrationIdiom } from '@shrkcrft/core';
+export declare const REGISTRATION_GRAPH_SCHEMA: "sharkcraft.registration-graph/v1";
+/** A token role-site: which idiom + file:line it was found at. */
+export interface IRegistrationSite {
+    readonly idiom: string;
+    readonly file: string;
+    readonly line: number;
+}
+/** One token in the registration graph and the three roles it plays. */
+export interface IRegistrationNode {
+    readonly token: string;
+    /** Sites where the token is DECLARED (token/provider definition). */
+    readonly declared: readonly IRegistrationSite[];
+    /** Sites where the token is PROVIDED / REGISTERED into a composition. */
+    readonly provided: readonly IRegistrationSite[];
+    /** Sites where the token is CONSUMED / INJECTED. */
+    readonly consumed: readonly IRegistrationSite[];
+}
+/**
+ * The registration / DI graph: a peer to the import graph extracted from the
+ * declared idiom shapes, keyed by token. Distinct edge kinds (declared /
+ * provided / consumed) so the runtime-wiring questions imports can't answer
+ * become deterministic queries.
+ */
+export interface IRegistrationGraph {
+    readonly schema: typeof REGISTRATION_GRAPH_SCHEMA;
+    /** Idiom names that contributed to this graph. */
+    readonly idioms: readonly string[];
+    /** Every distinct token, sorted, with its role-sites. */
+    readonly tokens: readonly IRegistrationNode[];
+    /** Misconfiguration messages (bad regex / no capture group / bad source). */
+    readonly diagnostics: readonly string[];
+}
+export interface IBuildRegistrationGraphOptions {
+    /** Project-relative directories to prune from the walk. */
+    readonly excludeDirs?: readonly string[];
+}
+/**
+ * Build the registration/DI graph from the declared idioms. For each idiom the
+ * three roles (declared / provided / consumed) are extracted with the shared
+ * alias-aware {@link collectSourceSites}, then bucketed by token across every
+ * idiom. Pure-engine output; the only IO is a single read-only tree walk over
+ * the union of all idiom globs. Never throws — a misconfigured source becomes a
+ * diagnostic.
+ */
+export declare function buildRegistrationGraph(projectRoot: string, idioms: readonly IRegistrationIdiom[], options?: IBuildRegistrationGraphOptions): IRegistrationGraph;
+/**
+ * A cheap content-signature of the exact files {@link buildRegistrationGraph}
+ * would read for these idioms: the sorted `relpath:mtimeMs:size` of every matched
+ * file, hashed. Because it reflects the graph's ACTUAL data source (a live tree
+ * walk) rather than the unrelated code-graph index, it is the correct key for any
+ * persisted registration-graph cache — a source edit shifts the signature even
+ * when no reindex has run, so a stale wiring verdict is impossible. Walk-and-stat
+ * only (no file reads), so it stays far cheaper than a full build. Never throws.
+ */
+export declare function registrationGraphSignature(projectRoot: string, idioms: readonly IRegistrationIdiom[], options?: IBuildRegistrationGraphOptions): string;
+/** A token's full registration chain, with role presence flags. */
+export interface IRegistrationChain extends IRegistrationNode {
+    readonly isDeclared: boolean;
+    readonly isProvided: boolean;
+    readonly isConsumed: boolean;
+}
+/**
+ * `wiring chain <token>` — the declared → provided → consumed hops of one token
+ * with file:line at each, or `undefined` if the token is unknown to the graph.
+ */
+export declare function registrationChain(graph: IRegistrationGraph, token: string): IRegistrationChain | undefined;
+/** A token declared or injected but never provided — silently absent at runtime. */
+export interface IUnprovidedToken {
+    readonly token: string;
+    readonly declared: readonly IRegistrationSite[];
+    readonly consumed: readonly IRegistrationSite[];
+}
+/**
+ * `wiring unprovided` — tokens that are DECLARED or CONSUMED but have ZERO
+ * provided sites. This is the silent-at-runtime class: typecheck/AOT-green, but
+ * the provider is never registered (or the injected token has no provider
+ * anywhere), so it resolves to undefined at runtime. The thing imports can't see.
+ */
+export declare function registrationUnprovided(graph: IRegistrationGraph): readonly IUnprovidedToken[];
+/** A token provided/registered that nothing consumes — a dead registration. */
+export interface IOrphanRegistration {
+    readonly token: string;
+    readonly provided: readonly IRegistrationSite[];
+}
+/**
+ * `wiring orphans` — tokens that ARE provided/registered but have ZERO consumed
+ * sites: a provider/registration nothing injects (a build-clean no-op, or a
+ * sign the consumer was renamed/removed).
+ */
+export declare function registrationOrphans(graph: IRegistrationGraph): readonly IOrphanRegistration[];
+//# sourceMappingURL=registration-graph.d.ts.map

package/dist/wiring/registration-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration-graph.d.ts","sourceRoot":"","sources":["../../src/wiring/registration-graph.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAiB,MAAM,gBAAgB,CAAC;AAKxE,eAAO,MAAM,yBAAyB,EAAG,kCAA2C,CAAC;AAErF,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACjD;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,OAAO,yBAAyB,CAAC;IAClD,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC9C,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,8BAA8B;IAC7C,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAiBD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,kBAAkB,EAAE,EACrC,OAAO,GAAE,8BAAmC,GAC3C,kBAAkB,CAqDpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,kBAAkB,EAAE,EACrC,OAAO,GAAE,8BAAmC,GAC3C,MAAM,CAiBR;AAED,mEAAmE;AACnE,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,kBAAkB,EACzB,KAAK,EAAE,MAAM,GACZ,kBAAkB,GAAG,SAAS,CAShC;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACjD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,kBAAkB,GAAG,SAAS,gBAAgB,EAAE,CAI7F;AAED,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACjD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,SAAS,mBAAmB,EAAE,CAI7F"}

package/dist/wiring/registration-graph.js

@@ -0,0 +1,124 @@
+import { createHash } from 'node:crypto';
+import { statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { matchesAny } from "../scan/glob.js";
+import { readMatchingFiles, walkMatching } from "../util/walk-files.js";
+import { collectSourceSites } from "./evaluate-wiring.js";
+export const REGISTRATION_GRAPH_SCHEMA = 'sharkcraft.registration-graph/v1';
+function sortSites(sites) {
+    return [...sites].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.idiom.localeCompare(b.idiom));
+}
+/** Union (deduped) of every glob any role of any idiom references. */
+function registrationGlobs(idioms) {
+    return [
+        ...new Set(idioms.flatMap((i) => [...i.declared.files, ...i.provided.files, ...i.consumed.files])),
+    ];
+}
+/**
+ * Build the registration/DI graph from the declared idioms. For each idiom the
+ * three roles (declared / provided / consumed) are extracted with the shared
+ * alias-aware {@link collectSourceSites}, then bucketed by token across every
+ * idiom. Pure-engine output; the only IO is a single read-only tree walk over
+ * the union of all idiom globs. Never throws — a misconfigured source becomes a
+ * diagnostic.
+ */
+export function buildRegistrationGraph(projectRoot, idioms, options = {}) {
+    const cache = readMatchingFiles(projectRoot, registrationGlobs(idioms), new Set(options.excludeDirs ?? []));
+    const entries = [...cache.entries()].map(([path, content]) => ({
+        path,
+        content,
+    }));
+    const filesFor = (source) => entries.filter((f) => matchesAny(f.path, source.files));
+    const declared = new Map();
+    const provided = new Map();
+    const consumed = new Map();
+    const diagnostics = [];
+    const harvest = (idiom, role, source, into) => {
+        const res = collectSourceSites(source, filesFor(source));
+        if (res.error)
+            diagnostics.push(`idiom "${idiom}" ${role}: ${res.error}`);
+        for (const s of res.sites) {
+            const list = into.get(s.token) ?? [];
+            list.push({ idiom, file: s.file, line: s.line });
+            into.set(s.token, list);
+        }
+    };
+    for (const idiom of idioms) {
+        harvest(idiom.name, 'declared', idiom.declared, declared);
+        harvest(idiom.name, 'provided', idiom.provided, provided);
+        harvest(idiom.name, 'consumed', idiom.consumed, consumed);
+    }
+    const tokenSet = new Set([...declared.keys(), ...provided.keys(), ...consumed.keys()]);
+    const tokens = [...tokenSet].sort().map((token) => ({
+        token,
+        declared: sortSites(declared.get(token) ?? []),
+        provided: sortSites(provided.get(token) ?? []),
+        consumed: sortSites(consumed.get(token) ?? []),
+    }));
+    return {
+        schema: REGISTRATION_GRAPH_SCHEMA,
+        idioms: idioms.map((i) => i.name),
+        tokens,
+        diagnostics,
+    };
+}
+/**
+ * A cheap content-signature of the exact files {@link buildRegistrationGraph}
+ * would read for these idioms: the sorted `relpath:mtimeMs:size` of every matched
+ * file, hashed. Because it reflects the graph's ACTUAL data source (a live tree
+ * walk) rather than the unrelated code-graph index, it is the correct key for any
+ * persisted registration-graph cache — a source edit shifts the signature even
+ * when no reindex has run, so a stale wiring verdict is impossible. Walk-and-stat
+ * only (no file reads), so it stays far cheaper than a full build. Never throws.
+ */
+export function registrationGraphSignature(projectRoot, idioms, options = {}) {
+    const files = walkMatching(projectRoot, registrationGlobs(idioms), new Set(options.excludeDirs ?? [])).sort();
+    const parts = [];
+    for (const rel of files) {
+        try {
+            const st = statSync(nodePath.join(projectRoot, rel));
+            parts.push(`${rel}:${st.mtimeMs}:${st.size}`);
+        }
+        catch {
+            // Unreadable / racing delete — omit; a real content change still shifts
+            // the hash via the surviving entries (and via this file's disappearance).
+        }
+    }
+    return createHash('sha1').update(parts.join('\n')).digest('hex').slice(0, 16);
+}
+/**
+ * `wiring chain <token>` — the declared → provided → consumed hops of one token
+ * with file:line at each, or `undefined` if the token is unknown to the graph.
+ */
+export function registrationChain(graph, token) {
+    const node = graph.tokens.find((t) => t.token === token);
+    if (!node)
+        return undefined;
+    return {
+        ...node,
+        isDeclared: node.declared.length > 0,
+        isProvided: node.provided.length > 0,
+        isConsumed: node.consumed.length > 0,
+    };
+}
+/**
+ * `wiring unprovided` — tokens that are DECLARED or CONSUMED but have ZERO
+ * provided sites. This is the silent-at-runtime class: typecheck/AOT-green, but
+ * the provider is never registered (or the injected token has no provider
+ * anywhere), so it resolves to undefined at runtime. The thing imports can't see.
+ */
+export function registrationUnprovided(graph) {
+    return graph.tokens
+        .filter((t) => t.provided.length === 0 && (t.declared.length > 0 || t.consumed.length > 0))
+        .map((t) => ({ token: t.token, declared: t.declared, consumed: t.consumed }));
+}
+/**
+ * `wiring orphans` — tokens that ARE provided/registered but have ZERO consumed
+ * sites: a provider/registration nothing injects (a build-clean no-op, or a
+ * sign the consumer was renamed/removed).
+ */
+export function registrationOrphans(graph) {
+    return graph.tokens
+        .filter((t) => t.provided.length > 0 && t.consumed.length === 0)
+        .map((t) => ({ token: t.token, provided: t.provided }));
+}

package/dist/wiring/trace-literal.d.ts

@@ -0,0 +1,60 @@
+export declare const TRACE_SCHEMA: "sharkcraft.trace/v1";
+/** Default source globs scanned when `trace` is given no `--glob`. */
+export declare const TRACE_DEFAULT_GLOBS: readonly string[];
+/**
+ * How a literal occurrence relates to the cross-fence contract — the direction
+ * grep can't give you:
+ *  - `declare`  — a canonical definition (`const X = 'lit'`, `kind: 'lit'`, an enum value).
+ *  - `register` — added to a collection / mapping (`register('lit')`, an array element, `{ 'lit': … }`).
+ *  - `consume`  — compared / switched / handled (`=== 'lit'`, `case 'lit':`).
+ *  - `reference`— an occurrence we can't confidently classify (still reported, with context).
+ */
+export declare enum TraceRole {
+    Declare = "declare",
+    Register = "register",
+    Consume = "consume",
+    Reference = "reference"
+}
+/** One occurrence of the traced literal (or a const aliased to it). */
+export interface ITraceSite {
+    readonly file: string;
+    readonly line: number;
+    readonly role: TraceRole;
+    /** The trimmed source line, for context. */
+    readonly text: string;
+    /** Set when this site reached the literal through a `const NAME = 'literal'` alias. */
+    readonly viaAlias?: string;
+}
+export interface ITraceReport {
+    readonly schema: typeof TRACE_SCHEMA;
+    readonly literal: string;
+    readonly total: number;
+    /** Distinct files the literal (or an alias) was found in. */
+    readonly files: number;
+    /** Sites grouped by role, each group sorted by (file, line). */
+    readonly byRole: Readonly<Record<TraceRole, readonly ITraceSite[]>>;
+    /** Const names found bound to the literal (`const NAME = 'literal'`), if any. */
+    readonly aliases: readonly string[];
+}
+export interface ITraceOptions {
+    /** Override the default source globs. */
+    readonly globs?: readonly string[];
+    /** Project-relative directories to prune from the walk. */
+    readonly excludeDirs?: readonly string[];
+    /**
+     * Resolve `const NAME = 'literal'` bindings and also classify uses of NAME
+     * (flagged `viaAlias`). On by default — it is the cross-fence value over grep.
+     */
+    readonly resolveAliases?: boolean;
+}
+/**
+ * Trace every declare → register → consume site of an EXACT string literal
+ * across the tree, classifying each occurrence with a direction. Generalizes
+ * `registry where` to any cross-fence string contract (a kind slug, permission
+ * id, route key, data key) WITHOUT a pre-declared registry — point it at any
+ * literal and get the chain grep can't: direction + role + layer-spanning
+ * grouping, plus (by default) the const-alias bindings of the literal and their
+ * use-sites. Pure-engine; the only IO is one read-only tree walk. Never throws.
+ */
+export declare function traceLiteral(projectRoot: string, literal: string, options?: ITraceOptions): ITraceReport;
+//# sourceMappingURL=trace-literal.d.ts.map

package/dist/wiring/trace-literal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-literal.d.ts","sourceRoot":"","sources":["../../src/wiring/trace-literal.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,EAAG,qBAA8B,CAAC;AAE3D,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAShD,CAAC;AAEF;;;;;;;GAOG;AACH,oBAAY,SAAS;IACnB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,SAAS,cAAc;CACxB;AAED,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,YAAY,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,UAAU,EAAE,CAAC,CAAC,CAAC;IACpE,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AAmED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAkB,GAC1B,YAAY,CAqFd"}

package/dist/wiring/trace-literal.js

@@ -0,0 +1,187 @@
+import { readMatchingFiles } from "../util/walk-files.js";
+export const TRACE_SCHEMA = 'sharkcraft.trace/v1';
+/** Default source globs scanned when `trace` is given no `--glob`. */
+export const TRACE_DEFAULT_GLOBS = [
+    '**/*.ts',
+    '**/*.tsx',
+    '**/*.mts',
+    '**/*.cts',
+    '**/*.js',
+    '**/*.jsx',
+    '**/*.mjs',
+    '**/*.cjs',
+];
+/**
+ * How a literal occurrence relates to the cross-fence contract — the direction
+ * grep can't give you:
+ *  - `declare`  — a canonical definition (`const X = 'lit'`, `kind: 'lit'`, an enum value).
+ *  - `register` — added to a collection / mapping (`register('lit')`, an array element, `{ 'lit': … }`).
+ *  - `consume`  — compared / switched / handled (`=== 'lit'`, `case 'lit':`).
+ *  - `reference`— an occurrence we can't confidently classify (still reported, with context).
+ */
+export var TraceRole;
+(function (TraceRole) {
+    TraceRole["Declare"] = "declare";
+    TraceRole["Register"] = "register";
+    TraceRole["Consume"] = "consume";
+    TraceRole["Reference"] = "reference";
+})(TraceRole || (TraceRole = {}));
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function lineStarts(content) {
+    const starts = [0];
+    for (let i = 0; i < content.length; i += 1) {
+        if (content[i] === '\n')
+            starts.push(i + 1);
+    }
+    return starts;
+}
+/** 1-based line for a character offset, given precomputed line-start offsets. */
+function lineAt(starts, offset) {
+    // Binary search for the greatest start <= offset.
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (starts[mid] <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo + 1;
+}
+function lineText(content, starts, line) {
+    const start = starts[line - 1] ?? 0;
+    const nl = content.indexOf('\n', start);
+    return content.slice(start, nl === -1 ? content.length : nl);
+}
+/**
+ * Heuristic declare-vs-register-vs-consume classifier from the text immediately
+ * around the occurrence. High-precision rules first; anything unmatched stays
+ * `reference` (reported, never silently dropped). Deterministic.
+ */
+function classifyRole(before, after) {
+    const b = before.replace(/\s+$/, '');
+    const a = after.replace(/^\s+/, '');
+    // switch/case handler.
+    if (/\bcase$/.test(b) && a.startsWith(':'))
+        return TraceRole.Consume;
+    // equality / inequality comparison on either side.
+    if (/(===|!==|==|!=)$/.test(b) || /^(===|!==|==|!=)/.test(a))
+        return TraceRole.Consume;
+    // object / map key mapping: `{ 'lit': … }` or `, 'lit': …`.
+    if (a.startsWith(':') && /[{,]$/.test(b))
+        return TraceRole.Register;
+    // registration-ish call: register('lit'), provide('lit'), on('lit'), .set('lit', …).
+    if (/\b(register|provide|add|use|on|handle|bind|emit|dispatch|listen|subscribe|define)\w*\($/i.test(b)) {
+        return TraceRole.Register;
+    }
+    if (/\.\s*set\($/.test(b))
+        return TraceRole.Register;
+    // array element: the literal directly follows `[` or `,`.
+    if (/[[,]$/.test(b))
+        return TraceRole.Register;
+    // canonical binding: const/let/var X = 'lit'.
+    if (/\b(?:const|let|var)\s+[\w$]+\s*=$/.test(b))
+        return TraceRole.Declare;
+    // definition-ish object property: `kind: 'lit'`, `id = 'lit'`, etc.
+    if (/\b(kind|type|id|name|slug|key|tag|code|token|permission|route|event|action|channel|topic|status|provide|providerToken)\s*[:=]$/i.test(b)) {
+        return TraceRole.Declare;
+    }
+    return TraceRole.Reference;
+}
+/** A const name is alias-resolvable only if Pascal/SCREAMING-cased (low collision risk). */
+const ALIAS_NAME = /^[A-Z][\w$]*$/;
+/**
+ * Trace every declare → register → consume site of an EXACT string literal
+ * across the tree, classifying each occurrence with a direction. Generalizes
+ * `registry where` to any cross-fence string contract (a kind slug, permission
+ * id, route key, data key) WITHOUT a pre-declared registry — point it at any
+ * literal and get the chain grep can't: direction + role + layer-spanning
+ * grouping, plus (by default) the const-alias bindings of the literal and their
+ * use-sites. Pure-engine; the only IO is one read-only tree walk. Never throws.
+ */
+export function traceLiteral(projectRoot, literal, options = {}) {
+    const globs = options.globs && options.globs.length > 0 ? options.globs : TRACE_DEFAULT_GLOBS;
+    const exclude = new Set(options.excludeDirs ?? []);
+    const cache = readMatchingFiles(projectRoot, globs, exclude);
+    const sites = [];
+    const aliasNames = new Set();
+    // Exact quoted-literal match: the closing quote immediately follows, so the
+    // quoted CONTENT equals the literal (not a substring of a longer string).
+    const litRe = new RegExp(`(['"\`])${escapeRegex(literal)}\\1`, 'g');
+    for (const [file, content] of cache) {
+        const starts = lineStarts(content);
+        litRe.lastIndex = 0;
+        let m;
+        while ((m = litRe.exec(content)) !== null) {
+            if (m.index === litRe.lastIndex)
+                litRe.lastIndex += 1;
+            const line = lineAt(starts, m.index);
+            const text = lineText(content, starts, line);
+            const col = m.index - (starts[line - 1] ?? 0);
+            const before = text.slice(0, col);
+            const after = text.slice(col + m[0].length);
+            const role = classifyRole(before, after);
+            sites.push({ file, line, role, text: text.trim() });
+            // Capture a const alias bound to this literal for the second pass.
+            const bind = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=$/.exec(before.replace(/\s+$/, ''));
+            if (bind && ALIAS_NAME.test(bind[1]))
+                aliasNames.add(bind[1]);
+        }
+    }
+    // Second pass: classify uses of any const aliased to the literal.
+    const resolveAliases = options.resolveAliases !== false;
+    if (resolveAliases && aliasNames.size > 0) {
+        for (const name of aliasNames) {
+            // The lookbehind excludes `.` as well as word chars/`$`: a genuine use of
+            // the top-level const alias is never dot-prefixed, whereas `Enum.NAME` /
+            // `obj.NAME` is a member/enum accessor that merely shares the alias's name
+            // and must NOT be counted as a use of the traced literal (over-match).
+            const useRe = new RegExp(`(?<![\\w$.])${escapeRegex(name)}(?![\\w$])`, 'g');
+            for (const [file, content] of cache) {
+                const starts = lineStarts(content);
+                useRe.lastIndex = 0;
+                let m;
+                while ((m = useRe.exec(content)) !== null) {
+                    const line = lineAt(starts, m.index);
+                    const text = lineText(content, starts, line);
+                    const col = m.index - (starts[line - 1] ?? 0);
+                    const before = text.slice(0, col);
+                    const after = text.slice(col + name.length);
+                    // Skip ONLY the binding occurrence itself (`const NAME = …`) — it's
+                    // already counted as a literal Declare site. Keying on the exact
+                    // `const NAME` position (not the whole line) means a genuine alias use
+                    // that merely SHARES a line with some literal is still reported.
+                    if (/\b(?:const|let|var)\s+$/.test(before))
+                        continue;
+                    const role = classifyRole(before, after);
+                    sites.push({ file, line, role, text: text.trim(), viaAlias: name });
+                }
+            }
+        }
+    }
+    const sortSites = (xs) => [...xs].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+    const byRole = {
+        [TraceRole.Declare]: [],
+        [TraceRole.Register]: [],
+        [TraceRole.Consume]: [],
+        [TraceRole.Reference]: [],
+    };
+    for (const s of sites)
+        byRole[s.role].push(s);
+    return {
+        schema: TRACE_SCHEMA,
+        literal,
+        total: sites.length,
+        files: new Set(sites.map((s) => s.file)).size,
+        byRole: {
+            [TraceRole.Declare]: sortSites(byRole[TraceRole.Declare]),
+            [TraceRole.Register]: sortSites(byRole[TraceRole.Register]),
+            [TraceRole.Consume]: sortSites(byRole[TraceRole.Consume]),
+            [TraceRole.Reference]: sortSites(byRole[TraceRole.Reference]),
+        },
+        aliases: [...aliasNames].sort(),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/boundaries",
-  "version": "0.1.0-alpha.23",
+  "version": "0.1.0-alpha.24",
   "description": "SharkCraft boundary rules: detect when a repository violates its own architecture (forbidden imports across folder/package/layer boundaries).",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -43,7 +43,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.23"
+    "@shrkcrft/core": "^0.1.0-alpha.24"
   },
   "publishConfig": {
     "access": "public"