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

package/dist/template-drift.js

@@ -18,6 +18,8 @@
  */
 import { existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
+import { collectDeclaredXrefs } from "./declared-cross-references.js";
+import { DeclaredXrefStatus } from "./declared-xref-status.js";
 export const TEMPLATE_DRIFT_SCHEMA = 'sharkcraft.template-drift/v1';
 export var TemplateDriftStatus;
 (function (TemplateDriftStatus) {
@@ -174,18 +176,32 @@ function checkBarrelTargets(projectRoot, ops) {
     }
     return issues;
 }
-function checkRelatedIds(inspection, template) {
+/**
+ * `template.related`, read from THE declared cross-reference collector (the
+ * same rows the self-config doctor reports). This used to look in knowledge
+ * and templates only, so a related construct or boundary-rule id — both real —
+ * was reported unresolved. The message keeps its `related id "<id>"` prefix:
+ * `shrk fix --template-drift` parses it.
+ */
+function checkRelatedIds(xrefs, template) {
     const issues = [];
-    for (const id of template.related ?? []) {
-        // related ids are knowledge / construct / template / playbook — try
-        // them all.
-        const knowledge = inspection.index.get(id);
-        const tmpl = inspection.templates.find((t) => t.id === id);
-        if (!knowledge && !tmpl) {
+    for (const row of xrefs.rows) {
+        if (row.sourceKind !== 'template' || row.sourceId !== template.id || row.field !== 'related')
+            continue;
+        if (row.status === DeclaredXrefStatus.Dangling) {
             issues.push({
                 severity: 'info',
                 code: 'related-id-unresolved',
-                message: `related id "${id}" not found in knowledge or template registries.`,
+                message: `related id "${row.targetId}" not found in any registry${row.didYouMean.length > 0 ? ` — did you mean "${row.didYouMean[0]}"?` : '.'}`,
+            });
+        }
+        else if (row.status === DeclaredXrefStatus.Unverified) {
+            // A cold registry is "could not look", never "does not exist" — and
+            // `fix --template-drift` must not drop an id nobody looked up.
+            issues.push({
+                severity: 'info',
+                code: 'related-id-unverified',
+                message: `related id "${row.targetId}" NOT VERIFIED — the registries were not warmed, so it could not be looked up.`,
             });
         }
     }
@@ -298,6 +314,11 @@ export function buildTemplateDriftReport(inspection, options = {}) {
     const entries = [];
     const all = inspection.templates;
     const filtered = options.templateId ? all.filter((t) => t.id === options.templateId) : all;
+    // Collected once, and only when some template actually declares `related` —
+    // the collector walks every asset, which a report with nothing to resolve
+    // should not pay for.
+    let xrefs;
+    const xrefsFor = () => (xrefs ??= collectDeclaredXrefs(inspection));
     // Build the cross-template anchor producer map ONCE so each entry
     // can look up "is anchor X declared by some template?".
     const allProduced = new Map();
@@ -325,7 +346,7 @@ export function buildTemplateDriftReport(inspection, options = {}) {
             ...checkForbiddenFragments(t, paths),
             ...checkPathConventions(inspection, paths),
             ...checkBarrelTargets(inspection.projectRoot, ops),
-            ...checkRelatedIds(inspection, t),
+            ...((t.related?.length ?? 0) > 0 ? checkRelatedIds(xrefsFor(), t) : []),
             ...checkAnchorsNonEmpty(ops),
             ...checkProducedAnchors(t, values),
             ...checkRequiredAnchors(t, allProduced),

package/dist/template-lint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template-lint.d.ts","sourceRoot":"","sources":["../src/template-lint.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACtC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AAID,wBAAgB,aAAa,CAC3B,UAAU,EAAE,qBAAqB,EACjC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAC9B,mBAAmB,CAuBrB;AA4CD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,wBAAgB,aAAa,CAC3B,UAAU,EAAE,qBAAqB,EACjC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAC9B,SAAS,mBAAmB,EAAE,CAwChC"}
+{"version":3,"file":"template-lint.d.ts","sourceRoot":"","sources":["../src/template-lint.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACtC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AAID,wBAAgB,aAAa,CAC3B,UAAU,EAAE,qBAAqB,EACjC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAC9B,mBAAmB,CA2BrB;AAgMD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,wBAAgB,aAAa,CAC3B,UAAU,EAAE,qBAAqB,EACjC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAC9B,SAAS,mBAAmB,EAAE,CAwChC"}

package/dist/template-lint.js

@@ -1,4 +1,7 @@
-import { generate, OverwriteStrategy } from '@shrkcrft/generator';
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { buildNameVariables, describeInvalidPlannedOperation, generate, OverwriteStrategy, validatePlannedOperation, } from '@shrkcrft/generator';
+import { isTemplateRemainder, TEMPLATE_REMAINDERS, TemplateRemainder, } from '@shrkcrft/templates';
 const PLACEHOLDER_RE = /\{\{\s*(\w+)\s*\}\}/g;
 export function lintTemplates(inspection, templateIds) {
     const all = inspection.templateRegistry.list();
@@ -7,7 +10,11 @@ export function lintTemplates(inspection, templateIds) {
         : all;
     const results = [];
     for (const t of targets) {
-        const issues = lintOne(t);
+        const issues = [
+            ...lintOne(t),
+            ...lintOperations(t),
+            ...lintRemainders(t, inspection.projectRoot),
+        ];
         results.push({
             templateId: t.id,
             issues,
@@ -70,6 +77,157 @@ function lintOne(t) {
     }
     return issues;
 }
+/** The sample values lint renders a template's resolvers with (the same shape `testTemplates` uses, plus name variants). */
+function sampleValues(t) {
+    const values = { ...buildNameVariables('sample') };
+    for (const v of t.variables ?? []) {
+        values[v.name] = v.examples?.[0] ?? (typeof v.default === 'string' ? v.default : undefined) ?? `sample-${v.name}`;
+    }
+    return values;
+}
+/**
+ * `invalid-operation`: render `changes()` with sample variables and check every
+ * op against the generator's own allow-list (`validatePlannedOperation` — the
+ * table `planGeneration` checks). A misspelled op (`key`/`value` for
+ * `entryKey`/`entryValue`) used to crash `gen` while lint said "clean".
+ */
+function lintOperations(t) {
+    if (typeof t.changes !== 'function')
+        return [];
+    const issues = [];
+    let changes;
+    try {
+        changes = t.changes(sampleValues(t));
+    }
+    catch (e) {
+        return [
+            {
+                templateId: t.id,
+                code: 'render-threw',
+                severity: 'warning',
+                message: `changes() threw with sample variables — its operations were NOT checked: ${e.message}`,
+            },
+        ];
+    }
+    if (!Array.isArray(changes)) {
+        return [
+            { templateId: t.id, code: 'invalid-operation', severity: 'error', message: 'changes() must return an array of { targetPath, operation }' },
+        ];
+    }
+    changes.forEach((c, i) => {
+        const change = (c ?? {});
+        const where = `change[${i}]`;
+        const shape = validatePlannedOperation(change.operation);
+        const invalid = describeInvalidPlannedOperation(shape, where) ??
+            (typeof change.targetPath !== 'string' || change.targetPath.length === 0
+                ? `${where} (${shape.kind}): missing targetPath`
+                : undefined);
+        if (invalid) {
+            issues.push({ templateId: t.id, code: 'invalid-operation', severity: 'error', message: invalid });
+        }
+        else if (shape.unknown.length > 0) {
+            issues.push({
+                templateId: t.id,
+                code: 'operation-unknown-keys',
+                severity: 'warning',
+                message: `${where} (${shape.kind}): unknown key(s) ${shape.unknown.join(', ')} are ignored by the engine`,
+            });
+        }
+    });
+    return issues;
+}
+const BUILD_CONFIG_FILE = /(?:^|\/)(?:package\.json|tsconfig[^/]*\.json|project\.json|Cargo\.toml|go\.mod|pom\.xml|build\.gradle(?:\.kts)?|[^/]+\.csproj|pyproject\.toml)$/;
+/**
+ * `template-remainder-shape` (error): `notScaffolded` / `manualSteps` use only
+ * the closed remainder vocabulary. `undeclared-remainder` (INFO only — a "new
+ * module root" is inherently heuristic and must never fail a run): a CREATE
+ * lands in a directory that does not exist yet, nothing rendered is build
+ * config, and the template declares neither `notScaffolded: ['build-config']`
+ * nor a manual step covering it.
+ */
+function lintRemainders(t, projectRoot) {
+    const issues = [];
+    const allowed = TEMPLATE_REMAINDERS.join(', ');
+    for (const v of (t.notScaffolded ?? [])) {
+        if (!isTemplateRemainder(v)) {
+            issues.push({
+                templateId: t.id,
+                code: 'template-remainder-shape',
+                severity: 'error',
+                message: `notScaffolded: unknown remainder ${JSON.stringify(v)} (allowed: ${allowed})`,
+            });
+        }
+    }
+    (t.manualSteps ?? []).forEach((s, i) => {
+        const step = (s ?? {});
+        if (typeof step.description !== 'string' || step.description.trim().length === 0) {
+            issues.push({
+                templateId: t.id,
+                code: 'template-remainder-shape',
+                severity: 'error',
+                message: `manualSteps[${i}].description must be a non-empty string`,
+            });
+        }
+        for (const c of (Array.isArray(step.covers) ? step.covers : [])) {
+            if (!isTemplateRemainder(c)) {
+                issues.push({
+                    templateId: t.id,
+                    code: 'template-remainder-shape',
+                    severity: 'error',
+                    message: `manualSteps[${i}].covers: unknown remainder ${JSON.stringify(c)} (allowed: ${allowed})`,
+                });
+            }
+        }
+    });
+    const declaresBuildConfig = (t.notScaffolded ?? []).includes(TemplateRemainder.BuildConfig) ||
+        (t.manualSteps ?? []).some((s) => (s.covers ?? []).includes(TemplateRemainder.BuildConfig));
+    if (declaresBuildConfig)
+        return issues;
+    const values = sampleValues(t);
+    const creates = [];
+    try {
+        if (typeof t.files === 'function')
+            for (const f of t.files(values))
+                creates.push(f.targetPath);
+    }
+    catch {
+        /* a throwing factory is testTemplates' finding */
+    }
+    try {
+        if (typeof t.changes === 'function') {
+            for (const c of t.changes(values))
+                if (c?.operation?.kind === 'create')
+                    creates.push(c.targetPath);
+        }
+    }
+    catch {
+        /* reported by lintOperations */
+    }
+    try {
+        if (t.targetPath !== undefined && t.content !== undefined) {
+            creates.push(typeof t.targetPath === 'function' ? t.targetPath(values) : t.targetPath);
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    const normalized = creates.filter((p) => typeof p === 'string').map((p) => p.split(nodePath.sep).join('/'));
+    if (normalized.some((p) => BUILD_CONFIG_FILE.test(p)))
+        return issues;
+    const newRoot = normalized
+        .map((p) => nodePath.dirname(p))
+        .find((d) => d !== '.' && !existsSync(nodePath.resolve(projectRoot, d)));
+    if (newRoot) {
+        issues.push({
+            templateId: t.id,
+            code: 'undeclared-remainder',
+            severity: 'info',
+            message: `this template writes files under a new module root (${newRoot}) but declares neither build config nor a covering manual step`,
+            suggestion: "Declare notScaffolded: ['build-config'] (or a manualSteps entry covering it), or emit the build config.",
+        });
+    }
+    return issues;
+}
 export function testTemplates(inspection, templateIds) {
     const all = inspection.templateRegistry.list();
     const targets = templateIds && templateIds.length > 0

package/dist/term-query.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A task/query prepared once for {@link matchTerm}: its lowercase text (for
+ * the legacy substring mode) and its normalised term sequence (for tokens
+ * mode). Build it with `prepareTermQuery`; never hand-assemble one.
+ */
+export interface ITermQuery {
+    readonly lower: string;
+    readonly terms: readonly string[];
+}
+//# sourceMappingURL=term-query.d.ts.map

package/dist/term-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"term-query.d.ts","sourceRoot":"","sources":["../src/term-query.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC"}

package/dist/term-query.js

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

package/dist/test-definitions.d.ts

@@ -15,9 +15,12 @@ export interface IAgentContractTest {
     expectedForbiddenActions?: readonly string[];
     expectedVerificationCommands?: readonly string[];
     /**
-     * Additional expectations that fail the test when the ranker /
-     * search drifts. Each field is independent; missing fields are treated
-     * as "no expectation".
+     * Each asserts the id is registered — answered by the shared reference
+     * registry (the set the kind's `list` verb prints), never a private copy.
+     * Each field is independent; missing fields are "no expectation".
+     *
+     * `expectedCommands` is a hybrid: surfaced by the packet OR resolves
+     * against the live command index (injected by the CLI).
      */
     expectedHelpers?: readonly string[];
     expectedPlaybooks?: readonly string[];

package/dist/test-definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-definitions.d.ts","sourceRoot":"","sources":["../src/test-definitions.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,YAAY,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAEjE;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,wBAAwB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,4BAA4B,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD;;;;OAIG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC1C;;;OAGG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,kBAAkB,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAE7E"}
+{"version":3,"file":"test-definitions.d.ts","sourceRoot":"","sources":["../src/test-definitions.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,YAAY,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAEjE;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IAIb,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,wBAAwB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,4BAA4B,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEjD;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC1C;;;OAGG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,kBAAkB,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAE7E"}

package/dist/test-runner.d.ts

@@ -1,10 +1,17 @@
 import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
 import { type IAgentContractTest, type IContextTest } from './test-definitions.js';
+import { type IRejectedEntry } from '@shrkcrft/core';
+import type { IContributionFileIssue } from './i-contribution-file-issue.js';
+import type { IReferenceWarmOptions } from './i-reference-warm-options.js';
 /**
- * Pre-loaded registry id snapshots used to evaluate strict agent-test
- * expectations. The sync `runAgentContractTest` is best-effort; callers
- * should `loadAgentContractRegistries` once and pass the result for
- * accurate policy/construct membership checks.
+ * Registry id snapshots.
+ *
+ * @deprecated The runners no longer keep a private id source: every existence
+ * check goes through the shared reference registry (`referenceIdExists`), the
+ * same authority `shrk <kind> list` prints — call `warmReferenceRegistries`
+ * (the CLI: `warmCliReferenceRegistries`) before running. This snapshot is kept
+ * for API compatibility; its sets are projections of that registry and
+ * `commands` is always empty (commands resolve through the injected resolver).
  */
 export interface IAgentContractRegistries {
     helpers: ReadonlySet<string>;
@@ -14,11 +21,22 @@ export interface IAgentContractRegistries {
     commands: ReadonlySet<string>;
     knowledge: ReadonlySet<string>;
 }
+/** The registry a test diagnostic consulted, so a failure names what was searched. */
+export interface ITestConsultedRegistry {
+    /** Reference kind (`rule`, `template`, …) or `command`. */
+    kind: string;
+    /** The verb that prints this registry (`shrk rules list`). */
+    listVerb: string;
+    /** How many ids it holds right now (0 for `command`, which resolves rather than lists). */
+    size: number;
+}
 export interface IContextTestDiagnostic {
     /** The missing or unexpected id. */
     id: string;
     /** Whether the entry exists in the project at all (it just didn't make the context). */
     existsInRegistry: boolean;
+    /** The registry `existsInRegistry` was answered from. */
+    consulted?: ITestConsultedRegistry;
     /** Top-ranked alternatives the ranker chose instead, with reasons. */
     topAlternatives?: {
         id: string;
@@ -46,12 +64,40 @@ export interface IAgentContractMissingDiagnostic {
     /** Which expectation slot the id was missing from. */
     kind: 'template' | 'rule' | 'pipeline' | 'forbidden-action' | 'verification-command' | 'helper' | 'playbook' | 'policy' | 'construct' | 'command' | 'knowledge' | 'must-not-include';
     existsInRegistry: boolean;
+    /**
+     * What the expectation asserts:
+     *   - `surfaced` — the ranker put it in this task's packet (order-sensitive;
+     *     may flip on an unrelated content edit);
+     *   - `exists`   — it is registered (stable).
+     */
+    assertion?: 'surfaced' | 'exists';
+    /**
+     * Why it failed:
+     *   - `unknown-id`             — not registered at all: the test can never pass;
+     *   - `not-surfaced`           — registered, but the ranker did not surface it;
+     *   - `unknown-command`        — the command string does not resolve (see `closest`);
+     *   - `unverifiable`           — the lookup could not run (registries not warmed,
+     *                                or no command index injected outside the CLI);
+     *   - `not-aggregated`         — no relevant rule contributes this action/command;
+     *   - `surfaced-but-forbidden` — `mustNotInclude`, and the ranker surfaced it.
+     */
+    code?: 'unknown-id' | 'not-surfaced' | 'unknown-command' | 'unverifiable' | 'not-aggregated' | 'surfaced-but-forbidden';
+    /** The registry the existence answer came from. */
+    consulted?: ITestConsultedRegistry;
+    /** Nearest real commands, for `unknown-command`. */
+    closest?: readonly string[];
     suggestions: readonly string[];
 }
 export interface IAgentContractTestResult {
     id: string;
     task: string;
     passed: boolean;
+    /**
+     * `pass`, `fail`, or `not-verified` when every failing expectation is one the
+     * runner could not evaluate (see diagnostic code `unverifiable`). `passed` is
+     * false for `not-verified`: an unmeasured expectation is never a pass.
+     */
+    verdict: 'pass' | 'fail' | 'not-verified';
     expectedPipeline?: string;
     actualPipelines?: readonly string[];
     missingTemplates?: readonly string[];
@@ -67,21 +113,60 @@ export interface IAgentContractTestResult {
     missingKnowledge?: readonly string[];
     /** Ids that should NOT have been surfaced but were. */
     unexpectedlyIncluded?: readonly string[];
+    /** `<kind>:<id>` expectations the runner could not evaluate. */
+    unverified?: readonly string[];
     failureSummary?: string;
     diagnostics?: readonly IAgentContractMissingDiagnostic[];
 }
+/**
+ * THE context / agent-contract test acceptance predicate (round 12, 12.1): a
+ * non-empty string `id` and a string `task` — `[]` means accepted. Tests used
+ * to load with no per-entry validation (a test without a `task` ran against
+ * `undefined`), and a file that failed to import became `[]` in silence.
+ */
+export declare function testDefinitionRejectionReasons(raw: unknown): readonly string[];
+/**
+ * Context tests WITH what did not take effect (round 12, 12.1): files that
+ * failed to import and every declared test the loader refused.
+ */
+export declare function loadContextTestsWithIssues(inspection: ISharkcraftInspection): Promise<{
+    readonly tests: readonly IContextTest[];
+    readonly entries: readonly {
+        readonly id: string;
+        readonly file: string;
+        readonly packageName?: string;
+    }[];
+    readonly issues: readonly IContributionFileIssue[];
+    readonly rejected: readonly IRejectedEntry[];
+}>;
+/** Agent-contract tests WITH what did not take effect (round 12, 12.1). */
+export declare function loadAgentContractTestsWithIssues(inspection: ISharkcraftInspection): Promise<{
+    readonly tests: readonly IAgentContractTest[];
+    readonly entries: readonly {
+        readonly id: string;
+        readonly file: string;
+        readonly packageName?: string;
+    }[];
+    readonly issues: readonly IContributionFileIssue[];
+    readonly rejected: readonly IRejectedEntry[];
+}>;
 /**
  * Load context tests from local sharkcraft config + any pack contributions.
  */
 export declare function loadContextTests(inspection: ISharkcraftInspection): Promise<IContextTest[]>;
 export declare function loadAgentContractTests(inspection: ISharkcraftInspection): Promise<IAgentContractTest[]>;
 export declare function runContextTest(inspection: ISharkcraftInspection, test: IContextTest): IContextTestResult;
-export declare function runAgentContractTest(inspection: ISharkcraftInspection, test: IAgentContractTest, registries?: IAgentContractRegistries): IAgentContractTestResult;
+export declare function runAgentContractTest(inspection: ISharkcraftInspection, test: IAgentContractTest, 
+/** @deprecated Ignored — existence resolves through the shared reference registry. */
+_registries?: IAgentContractRegistries): IAgentContractTestResult;
 /**
- * Async pre-loader for agent-contract test registries. Reads local
- * sharkcraft/policies.ts, sharkcraft/constructs.ts, sharkcraft/playbooks/
- * (and pack contributions where present). Result is sync-friendly so the
- * runner can stay sync.
+ * Warm the shared reference registry and return a snapshot of it.
+ *
+ * @deprecated Call `warmReferenceRegistries(inspection, options)` directly (the
+ * CLI: `warmCliReferenceRegistries`) — the runners read the registry itself.
+ * The snapshot is a projection of that one authority, never a second source:
+ * the old loader re-read policies / playbooks / constructs from its own file
+ * list and returned the built-in helpers only (no pack helpers).
  */
-export declare function loadAgentContractRegistries(inspection: ISharkcraftInspection): Promise<IAgentContractRegistries>;
+export declare function loadAgentContractRegistries(inspection: ISharkcraftInspection, options?: IReferenceWarmOptions): Promise<IAgentContractRegistries>;
 //# sourceMappingURL=test-runner.d.ts.map

package/dist/test-runner.d.ts.map

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