@gmickel/gno 2.7.1 → 2.8.0

package/src/core/audit-links.ts

@@ -6,9 +6,16 @@ import type {
 } from "../store/sqlite/graph-link-resolver";
 import type { AuditFindingDraft, AuditRuleContribution } from "./audit";
 
-import { compareAuditCodeUnits, compareAuditFindingDrafts } from "./audit";
+import { isTraversableResolution } from "../store/sqlite/graph-link-resolver";
+import {
+  AUDIT_MAX_EVIDENCE_DETAIL_CHARS,
+  compareAuditCodeUnits,
+  compareAuditFindingDrafts,
+} from "./audit";
 
-export const LINK_AUDIT_RULE_VERSION = "1.0" as const;
+/** 1.1: workspace-wide resolution and reference/resolution/scope evidence. */
+export const LINK_AUDIT_RULE_VERSION = "1.1" as const;
+/** Default per-rule cap; runs pass the effective `maxFindings` instead. */
 export const LINK_AUDIT_MAX_FINDINGS_PER_RULE = 1000;
 
 export interface AuditOrphanPolicy {
@@ -16,23 +23,123 @@ export interface AuditOrphanPolicy {
   ignorePathPrefixes: readonly string[];
   /** Mirrored duplicate rows are excluded from orphan claims by default. */
   ignoreMirrorDuplicates?: boolean;
+  /** Effective per-rule cap; defaults to LINK_AUDIT_MAX_FINDINGS_PER_RULE. */
+  maxFindingsPerRule?: number;
 }
 
 const boundedFindings = (
-  findings: readonly AuditFindingDraft[]
+  findings: readonly AuditFindingDraft[],
+  maxFindingsPerRule: number
 ): AuditFindingDraft[] =>
-  [...findings]
-    .sort(compareAuditFindingDrafts)
-    .slice(0, LINK_AUDIT_MAX_FINDINGS_PER_RULE);
+  [...findings].sort(compareAuditFindingDrafts).slice(0, maxFindingsPerRule);
 
 const lineLocation = (line: number, column: number): string =>
   `L${line}:C${column}`;
 
-const linkFinding = (
+type LinkReferenceKind =
+  | "wiki-name"
+  | "wiki-path"
+  | "explicit-collection"
+  | "markdown";
+
+const referenceKind = (
   link: AuditLinkSnapshot["links"][number]
+): LinkReferenceKind =>
+  link.linkType === "markdown"
+    ? "markdown"
+    : link.explicitCollection === true
+      ? "explicit-collection"
+      : link.targetRef.includes("/")
+        ? "wiki-path"
+        : "wiki-name";
+
+interface CandidateEvidence {
+  /** Canonical-path-ordered tied candidates visible in the audit scope. */
+  uris: string[];
+  /** Candidates outside the requested collection scope (identity withheld). */
+  withheld: number;
+  truncated: boolean;
+}
+
+const linkFinding = (
+  link: AuditLinkSnapshot["links"][number],
+  context: {
+    documents: ReadonlyMap<number, AuditLinkSnapshotDocument>;
+    scope: ReadonlySet<string> | null;
+  },
+  onEvidenceTruncated: () => void
 ): AuditFindingDraft => {
   const ambiguous = (link.resolved?.matchCount ?? 0) > 1;
   const target = `${link.targetCollection}:${link.targetRef}`;
+  const kind = referenceKind(link);
+  const tied = (link.resolved?.candidates ?? []).map((candidate) =>
+    context.documents.get(candidate.id)
+  );
+  const visible = tied.filter(
+    (document): document is AuditLinkSnapshotDocument =>
+      document !== undefined &&
+      (context.scope === null || context.scope.has(document.collection))
+  );
+  // Scope describes every tied candidate; withheld ones are only counted.
+  const resolvedScope = !ambiguous
+    ? null
+    : link.explicitCollection === true
+      ? "explicit-collection"
+      : tied.some(
+            (document) =>
+              document !== undefined &&
+              document.collection !== link.sourceCollection
+          )
+        ? "cross-collection"
+        : "same-collection";
+  const base = {
+    anchor: link.targetAnchor,
+    endColumn: link.endCol,
+    endLine: link.endLine,
+    linkType: link.linkType,
+    matchCount: link.resolved?.matchCount ?? 0,
+    matchRank: link.resolved?.matchRank ?? null,
+    normalizedTarget: link.targetRefNorm,
+    referenceKind: kind,
+    resolutionStatus: ambiguous ? "ambiguous" : "unresolved",
+    resolvedScope,
+  };
+  // Candidate URIs are added while the detail stays within the evidence
+  // bound, so a long tie is reported as truncated rather than silently cut.
+  const candidates: CandidateEvidence = {
+    uris: [],
+    withheld: tied.length - visible.length,
+    truncated: false,
+  };
+  const render = (): string =>
+    JSON.stringify(
+      tied.length > 0
+        ? {
+            ...base,
+            candidateCount: tied.length,
+            candidates: candidates.uris,
+            ...(candidates.withheld > 0
+              ? { candidatesWithheld: candidates.withheld }
+              : {}),
+            ...(candidates.truncated ? { candidatesTruncated: true } : {}),
+          }
+        : base
+    );
+  for (const document of visible) {
+    candidates.uris.push(document.uri);
+    if (Array.from(render()).length > AUDIT_MAX_EVIDENCE_DETAIL_CHARS) {
+      candidates.uris.pop();
+      candidates.truncated = true;
+      break;
+    }
+  }
+  if (
+    candidates.truncated &&
+    Array.from(render()).length > AUDIT_MAX_EVIDENCE_DETAIL_CHARS
+  ) {
+    candidates.uris.pop();
+  }
+  if (candidates.truncated) onEvidenceTruncated();
   return {
     subject: link.sourceUri,
     location: lineLocation(link.startLine, link.startCol),
@@ -46,19 +153,15 @@ const linkFinding = (
         summary: target,
         uri: link.sourceUri,
         path: link.sourceRelPath,
-        detail: JSON.stringify({
-          anchor: link.targetAnchor,
-          endColumn: link.endCol,
-          endLine: link.endLine,
-          linkType: link.linkType,
-          matchCount: link.resolved?.matchCount ?? 0,
-          matchRank: link.resolved?.matchRank ?? null,
-          normalizedTarget: link.targetRefNorm,
-        }),
+        detail: render(),
       },
     ],
     guidance: ambiguous
-      ? ["Use an explicit collection-relative target path"]
+      ? [
+          tied.length > 0
+            ? "Use a longer path such as [[Folder/Note]] to pick one target"
+            : "Use an explicit collection-relative target path",
+        ]
       : ["Create the target or correct the local link"],
   };
 };
@@ -112,20 +215,36 @@ export const evaluateLinkAudit = (
   const auditedDocumentIds = new Set(
     snapshot.auditedDocumentIds ?? snapshot.documents.map(({ id }) => id)
   );
+  let evidenceTruncated = false;
+  const findingContext = {
+    documents: new Map(snapshot.documents.map((doc) => [doc.id, doc])),
+    scope: snapshot.scopeCollections
+      ? new Set(snapshot.scopeCollections)
+      : null,
+  };
+  const finding = (link: AuditLinkSnapshot["links"][number]) =>
+    linkFinding(link, findingContext, () => {
+      evidenceTruncated = true;
+    });
   for (const link of snapshot.links) {
     const sourceAudited = auditedDocumentIds.has(link.sourceId);
     if (!link.resolved) {
-      if (sourceAudited) unresolved.push(linkFinding(link));
+      if (sourceAudited) unresolved.push(finding(link));
       continue;
     }
-    if (sourceAudited) connected.add(link.sourceId);
-    if (auditedDocumentIds.has(link.resolved.targetId)) {
-      connected.add(link.resolved.targetId);
+    // A tied workspace link is not a resolved link: it connects nothing.
+    if (isTraversableResolution(link.resolved)) {
+      if (sourceAudited) connected.add(link.sourceId);
+      if (auditedDocumentIds.has(link.resolved.targetId)) {
+        connected.add(link.resolved.targetId);
+      }
     }
     if (sourceAudited && link.resolved.matchCount > 1) {
-      ambiguous.push(linkFinding(link));
+      ambiguous.push(finding(link));
     }
   }
+  const maxFindingsPerRule =
+    policy.maxFindingsPerRule ?? LINK_AUDIT_MAX_FINDINGS_PER_RULE;
   const roots = new Set(normalizedPrefixes(policy.rootUris));
   const ignorePrefixes = normalizedPrefixes(policy.ignorePathPrefixes);
   const mirroredIds = duplicateMirrorIds(
@@ -179,7 +298,7 @@ export const evaluateLinkAudit = (
       message: partial
         ? "Local target scan was truncated"
         : `${unresolved.length} unresolved or broken local links`,
-      findings: boundedFindings(unresolved),
+      findings: boundedFindings(unresolved, maxFindingsPerRule),
       findingCount: unresolved.length,
       skipReason: partial ? "snapshot_truncated" : null,
     },
@@ -187,11 +306,12 @@ export const evaluateLinkAudit = (
       ...common,
       ruleId: "links.ambiguous-targets",
       category: "links",
+      evidenceTruncated,
       status: statusFor(ambiguous),
       message: partial
         ? "Ambiguous target scan was truncated"
         : `${ambiguous.length} ambiguous local links`,
-      findings: boundedFindings(ambiguous),
+      findings: boundedFindings(ambiguous, maxFindingsPerRule),
       findingCount: ambiguous.length,
       skipReason: partial ? "snapshot_truncated" : null,
     },
@@ -203,7 +323,7 @@ export const evaluateLinkAudit = (
       message: partial
         ? "Orphan scan was truncated"
         : `${orphanFindings.length} policy-defined orphan documents`,
-      findings: boundedFindings(orphanFindings),
+      findings: boundedFindings(orphanFindings, maxFindingsPerRule),
       findingCount: orphanFindings.length,
       skipReason: partial ? "snapshot_truncated" : null,
     },

package/src/core/audit-provenance.ts

@@ -11,6 +11,7 @@ import {
   validateDeclaredRecordProvenance,
 } from "./record-metadata";
 
+/** Default per-rule cap; runs pass the effective `maxFindings` instead. */
 export const PROVENANCE_AUDIT_MAX_FINDINGS_PER_RULE = 1000;
 
 export interface AuditProvenanceDocument {
@@ -87,7 +88,7 @@ const memoryFinding = (
  */
 export const evaluateMemoryRecordAudit = (
   documents: readonly AuditProvenanceDocument[],
-  options: { truncated?: boolean } = {}
+  options: { truncated?: boolean; maxFindingsPerRule?: number } = {}
 ): AuditRuleContribution => {
   const findings: AuditFindingDraft[] = [];
   let managedDocuments = 0;
@@ -129,7 +130,10 @@ export const evaluateMemoryRecordAudit = (
           : managedDocuments === 0
             ? "No memory-managed collections in scope"
             : `${managedDocuments} managed memory record(s) satisfy the contract`,
-    findings: findings.slice(0, PROVENANCE_AUDIT_MAX_FINDINGS_PER_RULE),
+    findings: findings.slice(
+      0,
+      options.maxFindingsPerRule ?? PROVENANCE_AUDIT_MAX_FINDINGS_PER_RULE
+    ),
     findingCount: findings.length,
     examinedCount: managedDocuments,
     skipReason: truncated
@@ -145,7 +149,7 @@ export const evaluateMemoryRecordAudit = (
 /** Missing provenance is completeness evidence, never a truth judgment. */
 export const evaluateProvenanceAudit = (
   documents: readonly AuditProvenanceDocument[],
-  options: { truncated?: boolean } = {}
+  options: { truncated?: boolean; maxFindingsPerRule?: number } = {}
 ): AuditRuleContribution[] => {
   const captureFindings: AuditFindingDraft[] = [];
   const recordFindings: AuditFindingDraft[] = [];
@@ -217,7 +221,10 @@ export const evaluateProvenanceAudit = (
           : `${findings.length} declared provenance completeness issues`,
     findings: [...findings]
       .sort(compareAuditFindingDrafts)
-      .slice(0, PROVENANCE_AUDIT_MAX_FINDINGS_PER_RULE),
+      .slice(
+        0,
+        options.maxFindingsPerRule ?? PROVENANCE_AUDIT_MAX_FINDINGS_PER_RULE
+      ),
     findingCount: findings.length,
     examinedCount: documents.length,
     skipReason: truncated

package/src/core/audit-workspace.ts

@@ -9,6 +9,7 @@ import type { DocumentRow } from "../store/types";
 import type {
   AuditCategory,
   AuditFingerprints,
+  AuditMaxFindings,
   AuditRunResult,
   AuditScope,
 } from "./audit";
@@ -26,6 +27,7 @@ import {
   AUDIT_RULE_SET_VERSION,
   canonicalAuditJson,
   hashAuditCanonical,
+  resolveAuditMaxFindings,
   runAudit,
 } from "./audit";
 import { evaluateFreshnessAudit } from "./audit-freshness";
@@ -55,7 +57,7 @@ export interface WorkspaceAuditOptions {
   collectionFilters?: readonly string[];
   pathFilters?: readonly string[];
   tagFilters?: readonly string[];
-  maxFindings?: number;
+  maxFindings?: AuditMaxFindings;
   agePolicy?: AuditFreshnessOptions["agePolicy"];
   orphanRoots?: readonly string[];
   orphanIgnorePrefixes?: readonly string[];
@@ -347,7 +349,8 @@ const filterLinkSnapshot = (
   snapshot: AuditLinkSnapshot,
   selectedIds: ReadonlySet<number>,
   selectedDocuments: readonly DocumentRow[],
-  selectionTruncated: boolean
+  selectionTruncated: boolean,
+  scopeCollections: readonly string[]
 ): AuditLinkSnapshot => {
   const links = snapshot.links.filter(
     (link) =>
@@ -362,6 +365,9 @@ const filterLinkSnapshot = (
     // Preserve graph-wide documents as duplicate-mirror evidence while the
     // explicit id set prevents findings outside the requested audit scope.
     auditedDocumentIds: [...selectedIds],
+    ...(scopeCollections.length > 0
+      ? { scopeCollections: [...scopeCollections] }
+      : {}),
     links,
     totals: { documents: selectedDocuments.length, links: outgoingTotal },
     truncated: {
@@ -429,7 +435,8 @@ const loadWorkspaceSnapshot = async (
       rawLinks,
       selectedIds,
       selected.documents,
-      selected.truncated
+      selected.truncated,
+      filters.collections
     ),
     truncated: selected.truncated,
   };
@@ -596,6 +603,12 @@ export const runWorkspaceAudit = async (
     snapshots.set(attempt, pending);
     return pending;
   };
+  // Per-family caps follow the effective report cap; runAudit rejects an
+  // invalid value before any rule runs.
+  const resolvedMaxFindings = resolveAuditMaxFindings(options.maxFindings);
+  const maxFindingsPerRule = resolvedMaxFindings.ok
+    ? resolvedMaxFindings.limit
+    : 0;
   const result = await runAudit({
     scope,
     capabilities: {
@@ -645,6 +658,7 @@ export const runWorkspaceAudit = async (
             ...evaluateLinkAudit(snapshot.links, {
               rootUris: options.orphanRoots ?? [],
               ignorePathPrefixes: options.orphanIgnorePrefixes ?? [],
+              maxFindingsPerRule,
             })
           );
           await options.onProgress?.({
@@ -657,7 +671,7 @@ export const runWorkspaceAudit = async (
           contributions.push(
             ...evaluateProvenanceAudit(
               snapshot.documents.map(({ provenance }) => provenance),
-              { truncated: snapshot.truncated }
+              { truncated: snapshot.truncated, maxFindingsPerRule }
             )
           );
           await options.onProgress?.({
@@ -674,6 +688,7 @@ export const runWorkspaceAudit = async (
                 now: options.now ?? new Date(),
                 agePolicy: options.agePolicy,
                 truncated: snapshot.truncated,
+                maxFindingsPerRule,
               }
             )
           );

package/src/core/audit.ts

@@ -6,6 +6,7 @@ import type {
   AuditFinding,
   AuditFingerprints,
   AuditForbiddenStoreMethod,
+  AuditMaxFindings,
   AuditReport,
   AuditReportStatus,
   AuditRuleContribution,
@@ -24,6 +25,9 @@ import {
   AUDIT_DEFAULT_MAX_FINDINGS,
   AUDIT_FORBIDDEN_STORE_METHODS,
   AUDIT_MAX_CODE_CHARS,
+  AUDIT_MAX_EVIDENCE_DETAIL_CHARS,
+  AUDIT_MAX_EVIDENCE_PER_FINDING,
+  AUDIT_MAX_FINDINGS_ALL,
   AUDIT_MAX_FINDINGS_LIMIT,
   AUDIT_MAX_IDENTIFIER_CHARS,
   AUDIT_MAX_MESSAGE_CHARS,
@@ -127,23 +131,61 @@ export const normalizeAuditScope = (
   };
 };
 
-const resolveMaxFindings = (
-  value: number | undefined
-): { ok: true; maxFindings: number } | { ok: false; error: string } => {
+export const AUDIT_MAX_FINDINGS_RANGE_MESSAGE = `maxFindings must be an integer between 1 and ${AUDIT_MAX_FINDINGS_LIMIT}, or "${AUDIT_MAX_FINDINGS_ALL}"`;
+
+/**
+ * Validate `maxFindings`. `limit` is the effective numeric cap (Infinity for
+ * `all`); `reported` is the value echoed in the report's truncation block.
+ */
+export const resolveAuditMaxFindings = (
+  value: AuditMaxFindings | undefined
+):
+  | { ok: true; limit: number; reported: AuditMaxFindings }
+  | { ok: false; error: string } => {
+  if (value === AUDIT_MAX_FINDINGS_ALL) {
+    return {
+      ok: true,
+      limit: Number.POSITIVE_INFINITY,
+      reported: AUDIT_MAX_FINDINGS_ALL,
+    };
+  }
   const maxFindings = value ?? AUDIT_DEFAULT_MAX_FINDINGS;
   if (
     !Number.isSafeInteger(maxFindings) ||
     maxFindings < 1 ||
     maxFindings > AUDIT_MAX_FINDINGS_LIMIT
   ) {
-    return {
-      ok: false,
-      error: `maxFindings must be an integer between 1 and ${AUDIT_MAX_FINDINGS_LIMIT}`,
-    };
+    return { ok: false, error: AUDIT_MAX_FINDINGS_RANGE_MESSAGE };
+  }
+  return { ok: true, limit: maxFindings, reported: maxFindings };
+};
+
+/** Parse a CLI `--max-findings` value: a positive integer or `all`. */
+export const parseAuditMaxFindingsInput = (
+  raw: string
+): AuditMaxFindings | undefined => {
+  const value = raw.trim();
+  if (value.toLowerCase() === AUDIT_MAX_FINDINGS_ALL) {
+    return AUDIT_MAX_FINDINGS_ALL;
   }
-  return { ok: true, maxFindings };
+  if (!/^\d+$/.test(value)) return undefined;
+  const parsed = Number(value);
+  return resolveAuditMaxFindings(parsed).ok ? parsed : undefined;
 };
 
+const draftEvidenceTruncated = (contribution: AuditRuleContribution): boolean =>
+  contribution.evidenceTruncated === true ||
+  (contribution.findings ?? []).some(
+    (draft) =>
+      draft.evidence.length > AUDIT_MAX_EVIDENCE_PER_FINDING ||
+      draft.evidence.some(
+        (item) =>
+          item.detail !== undefined &&
+          Array.from(normalizeAuditText(item.detail)).length >
+            AUDIT_MAX_EVIDENCE_DETAIL_CHARS
+      )
+  );
+
 const fingerprintsEqual = (
   left: AuditFingerprints,
   right: AuditFingerprints
@@ -231,7 +273,8 @@ const buildReportFromRules = (input: {
   versions: AuditVersions;
   rules: AuditRuleResult[];
   status: AuditReportStatus;
-  maxFindings: number;
+  maxFindings: { limit: number; reported: AuditMaxFindings };
+  evidenceTruncated: boolean;
   startedAt: string;
   completedAt: string;
   snapshotMs: number;
@@ -261,9 +304,9 @@ const buildReportFromRules = (input: {
     (sum, rule) => sum + rule.findingCount,
     0
   );
-  const truncated = exactFindingCount > input.maxFindings;
+  const truncated = exactFindingCount > input.maxFindings.limit;
   const returnedFindings = truncated
-    ? uniqueFindings.slice(0, input.maxFindings)
+    ? uniqueFindings.slice(0, input.maxFindings.limit)
     : uniqueFindings;
   const returnedFindingIds = new Set(
     returnedFindings.map((finding) => finding.id)
@@ -308,7 +351,11 @@ const buildReportFromRules = (input: {
     },
     truncation: {
       findingsTruncated: truncated,
-      maxFindings: input.maxFindings,
+      maxFindings: input.maxFindings.reported,
+      snapshotTruncated: rules.some(
+        (rule) => rule.skipReason === "snapshot_truncated"
+      ),
+      evidenceTruncated: input.evidenceTruncated,
     },
     timing: {
       snapshotMs: Math.max(0, Math.round(input.snapshotMs)),
@@ -329,7 +376,7 @@ export async function runAudit(input: AuditRunInput): Promise<AuditRunResult> {
   if (!scopeResult.ok) {
     return { ok: false, exit: "invalid", error: scopeResult.error };
   }
-  const maxFindingsResult = resolveMaxFindings(input.maxFindings);
+  const maxFindingsResult = resolveAuditMaxFindings(input.maxFindings);
   if (!maxFindingsResult.ok) {
     return { ok: false, exit: "invalid", error: maxFindingsResult.error };
   }
@@ -355,6 +402,7 @@ export async function runAudit(input: AuditRunInput): Promise<AuditRunResult> {
   let snapshotMs = 0;
   let rulesMs = 0;
   let lastRules: AuditRuleResult[] = [];
+  let lastEvidenceTruncated = false;
   let lastFingerprints: AuditFingerprints | null = null;
   let snapshotChanged = false;
   let failed = false;
@@ -405,6 +453,7 @@ export async function runAudit(input: AuditRunInput): Promise<AuditRunResult> {
     try {
       const contributions = await collectContributions(input.rules, ruleCtx);
       lastRules = contributions.map(materializeRule);
+      lastEvidenceTruncated = contributions.some(draftEvidenceTruncated);
     } catch (cause) {
       if (input.signal?.aborted) {
         lastRules = [cancellationRule()];
@@ -453,6 +502,7 @@ export async function runAudit(input: AuditRunInput): Promise<AuditRunResult> {
     }
     // Discard rule results from a drifted attempt; retry with a fresh snapshot.
     lastRules = [];
+    lastEvidenceTruncated = false;
   }
 
   const completedAt = clock();
@@ -484,7 +534,8 @@ export async function runAudit(input: AuditRunInput): Promise<AuditRunResult> {
         },
       ],
       status: "failed",
-      maxFindings: maxFindingsResult.maxFindings,
+      maxFindings: maxFindingsResult,
+      evidenceTruncated: false,
       startedAt: runStartedAt.toISOString(),
       completedAt: completedAt.toISOString(),
       snapshotMs,
@@ -531,7 +582,8 @@ export async function runAudit(input: AuditRunInput): Promise<AuditRunResult> {
             rules: rulesForReport,
             snapshotChanged: false,
           }),
-    maxFindings: maxFindingsResult.maxFindings,
+    maxFindings: maxFindingsResult,
+    evidenceTruncated: lastEvidenceTruncated,
     startedAt: runStartedAt.toISOString(),
     completedAt: completedAt.toISOString(),
     snapshotMs,

package/src/core/context-compiler.ts

@@ -355,6 +355,9 @@ export const planContextEvidence = async <T, P>(
       await deps.retrieve({
         query,
         collection,
+        // The primary search is partitioned per collection; graph expansion
+        // may bridge between the requested collections, never beyond them.
+        ...(collections.length > 0 ? { graphCollections: collections } : {}),
         noExpand: true,
         queryModes,
         tagsAll: input.tagsAll,

package/src/core/context-evidence.ts

@@ -40,6 +40,7 @@ import {
 import { planContextEvidence } from "./context-compiler";
 import { projectContextEvidenceMetadata } from "./context-evidence-metadata";
 import { createEgressLineage, resolveEgressLineage } from "./egress-provenance";
+import { linkResolutionFingerprintInput } from "./link-workspace";
 import { projectRecordEvidenceMetadata } from "./record-metadata";
 import {
   extractInclusiveLines,
@@ -205,6 +206,13 @@ const canonicalIndexSnapshot = (
     ),
 });
 
+const linkResolutionEntry = (
+  rows: Parameters<typeof linkResolutionFingerprintInput>[0]
+): { linkResolution?: ReturnType<typeof linkResolutionFingerprintInput> } => {
+  const linkResolution = linkResolutionFingerprintInput(rows);
+  return linkResolution ? { linkResolution } : {};
+};
+
 /** Capture one strict, content-free index/context snapshot before or after work. */
 export const captureContextEvidenceSnapshot = async (
   store: ContextEvidenceStore,
@@ -284,6 +292,9 @@ export const captureContextEvidenceSnapshot = async (
     indexFingerprint: hashJson({
       snapshots: indexSnapshots,
       egressLineage,
+      // Link workspace membership decides graph neighbours; a membership or
+      // resolver change is index drift. Absent without any workspace.
+      ...linkResolutionEntry(collectionRows),
     }),
   };
 };

package/src/core/graph-edge-confidence.ts

@@ -17,8 +17,30 @@ export const GRAPH_EDGE_CONFIDENCE_RANK: Record<GraphEdgeConfidence, number> = {
 export function classifyResolvedGraphEdge(
   linkType: "wiki" | "markdown",
   matchRank: number | null,
-  matchCount: number | null
+  matchCount: number | null,
+  /** Workspace resolution reason; semantic, independent of legacy ranks. */
+  reason?: string
 ): { confidence: GraphEdgeConfidence; audit: GraphEdgeAudit } {
+  if (linkType === "wiki" && reason !== undefined && reason !== "title") {
+    switch (reason) {
+      case "workspace-path":
+      case "collection-path":
+        return {
+          confidence: "explicit",
+          audit: { resolution: "exact-path", matchCount: 1 },
+        };
+      case "exact-name":
+        return {
+          confidence: "explicit",
+          audit: { resolution: "exact-name", matchCount: 1 },
+        };
+      default:
+        return {
+          confidence: "inferred",
+          audit: { resolution: "tie-break", matchCount: 1 },
+        };
+    }
+  }
   if (linkType === "markdown") {
     return {
       confidence: "explicit",

package/src/core/host-paths.ts

@@ -22,6 +22,7 @@ export const OWNER_CONFIG_PATH_FIELDS: ReadonlySet<string> = new Set([
   "configPath",
   "dbPath",
   "path",
+  "workspaceRoot",
 ]);
 
 const isPlainObject = (value: object): boolean => {

package/src/core/knowledge-impact.ts

@@ -41,6 +41,12 @@ export interface KnowledgeImpactResult {
 }
 
 export interface KnowledgeImpactInput {
+  /**
+   * Collection scope: only documents in these collections are traversed or
+   * returned, and a document outside them is never used as a bridge.
+   * Omitted or empty means every indexed collection.
+   */
+  collections?: string[];
   maxDepth?: number;
   maxNodes?: number;
   maxEdges?: number;
@@ -118,8 +124,30 @@ export async function analyzeKnowledgeImpact(
       isValidation: true,
     };
   }
+  const scope = [...new Set(input.collections ?? [])].sort();
+  if (scope.length > 0) {
+    const known = await store.getCollections();
+    if (!known.ok) return { success: false, error: known.error.message };
+    const names = new Set(known.value.map((row) => row.name));
+    const missing = scope.find((name) => !names.has(name));
+    if (missing) {
+      return {
+        success: false,
+        error: `Collection not found: ${missing}`,
+        isValidation: true,
+      };
+    }
+    if (!scope.includes(resolved.doc.collection)) {
+      return {
+        success: false,
+        error: `Document is outside the requested collections: ${ref}`,
+        isValidation: true,
+      };
+    }
+  }
   const traversal = await store.queryGraphTraversal(resolved.doc.id, {
     direction: "in",
+    ...(scope.length > 0 ? { collections: scope } : {}),
     maxDepth: values.maxDepth,
     maxNodes: values.maxNodes,
     frontierLimit: values.frontierLimit,