@gmickel/gno 2.7.1 → 2.8.1

package/src/core/audit-contract.ts

@@ -11,8 +11,11 @@ export const AUDIT_RULE_SET_VERSION = "1.0" as const;
 
 /** Default returned finding cap; totals remain exact when truncated. */
 export const AUDIT_DEFAULT_MAX_FINDINGS = 100;
-/** Hard upper bound for `--max-findings` / MCP maxFindings. */
-export const AUDIT_MAX_FINDINGS_LIMIT = 1000;
+/** Hard numeric upper bound for `--max-findings` / MCP maxFindings. */
+export const AUDIT_MAX_FINDINGS_LIMIT = 100_000;
+/** Returns every finding of the bounded audit snapshot. */
+export const AUDIT_MAX_FINDINGS_ALL = "all" as const;
+export type AuditMaxFindings = number | typeof AUDIT_MAX_FINDINGS_ALL;
 export const AUDIT_MAX_EVIDENCE_PER_FINDING = 8;
 export const AUDIT_MAX_GUIDANCE_PER_FINDING = 4;
 export const AUDIT_MAX_EVIDENCE_DETAIL_CHARS = 512;
@@ -201,7 +204,14 @@ export interface AuditCounts {
 
 export interface AuditTruncation {
   findingsTruncated: boolean;
-  maxFindings: number;
+  maxFindings: AuditMaxFindings;
+  /**
+   * The bounded audit snapshot (documents or links) was cut; finding totals
+   * cover the snapshot only and are not complete-index totals.
+   */
+  snapshotTruncated: boolean;
+  /** Evidence items, candidate lists or evidence detail text were clipped. */
+  evidenceTruncated: boolean;
 }
 
 export interface AuditTiming {
@@ -255,6 +265,8 @@ export interface AuditRuleContribution {
   findings?: AuditFindingDraft[];
   /** Exact findings before any evaluator-side payload cap. */
   findingCount?: number;
+  /** Evaluator clipped evidence (for example a long tied-candidate list). */
+  evidenceTruncated?: boolean;
   examinedCount?: number;
   durationMs?: number;
   skipReason?: string | null;
@@ -283,7 +295,7 @@ export interface AuditRunInput {
   capabilities: AuditCapabilitySnapshot;
   captureFingerprints: AuditFingerprintCapture;
   rules: readonly AuditRuleEvaluator[];
-  maxFindings?: number;
+  maxFindings?: AuditMaxFindings;
   maxAttempts?: number;
   gnoVersion?: string;
   clock?: () => Date;

package/src/core/audit-freshness.ts

@@ -33,6 +33,8 @@ export interface AuditFreshnessOptions {
   now: Date;
   agePolicy?: AuditAgePolicy;
   truncated?: boolean;
+  /** Effective per-rule cap; defaults to FRESHNESS_AUDIT_MAX_FINDINGS_PER_RULE. */
+  maxFindingsPerRule?: number;
 }
 
 const finding = (input: {
@@ -68,6 +70,7 @@ const rule = (input: {
   skipped?: boolean;
   message: string;
   reason?: string;
+  maxFindingsPerRule?: number;
 }): AuditRuleContribution => ({
   ruleId: input.ruleId,
   category: "freshness",
@@ -83,7 +86,10 @@ const rule = (input: {
   message: input.message,
   findings: [...input.findings]
     .sort(compareAuditFindingDrafts)
-    .slice(0, FRESHNESS_AUDIT_MAX_FINDINGS_PER_RULE),
+    .slice(
+      0,
+      input.maxFindingsPerRule ?? FRESHNESS_AUDIT_MAX_FINDINGS_PER_RULE
+    ),
   findingCount: input.findings.length,
   examinedCount: input.examinedCount,
   skipReason: input.reason ?? null,
@@ -186,6 +192,7 @@ export const evaluateFreshnessAudit = (
       : undefined;
   return [
     rule({
+      maxFindingsPerRule: options.maxFindingsPerRule,
       ruleId: "freshness.source-readable",
       findings: unavailable,
       examinedCount: documents.length,
@@ -197,6 +204,7 @@ export const evaluateFreshnessAudit = (
       reason,
     }),
     rule({
+      maxFindingsPerRule: options.maxFindingsPerRule,
       ruleId: "freshness.source-index-drift",
       findings: drift,
       examinedCount: byteComparableCount,
@@ -207,6 +215,7 @@ export const evaluateFreshnessAudit = (
       reason,
     }),
     rule({
+      maxFindingsPerRule: options.maxFindingsPerRule,
       ruleId: "freshness.index-revision",
       findings: staleRevision,
       examinedCount: documents.length,
@@ -217,6 +226,7 @@ export const evaluateFreshnessAudit = (
       reason,
     }),
     rule({
+      maxFindingsPerRule: options.maxFindingsPerRule,
       ruleId: "freshness.configured-age-signal",
       findings: ageSignals,
       examinedCount: documents.length,

package/src/core/audit-links.ts

@@ -6,9 +6,19 @@ 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.
+ * 1.2: `links.outside-index` for workspace files that are not indexed.
+ */
+export const LINK_AUDIT_RULE_VERSION = "1.2" 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 +26,148 @@ 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 outsideIndex = !ambiguous && link.outsideIndex === true;
   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"
+      : outsideIndex
+        ? "outside-index"
+        : "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();
+  if (outsideIndex) {
+    return {
+      subject: link.sourceUri,
+      location: lineLocation(link.startLine, link.startCol),
+      severity: "info",
+      message: `Link target exists outside the index: ${target}`,
+      evidence: [
+        {
+          kind: "outside-index-target",
+          summary: target,
+          uri: link.sourceUri,
+          path: link.sourceRelPath,
+          detail: render(),
+        },
+      ],
+      guidance: [
+        "No action needed; index the target's folder to add it to the link graph",
+      ],
+    };
+  }
   return {
     subject: link.sourceUri,
     location: lineLocation(link.startLine, link.startCol),
@@ -46,19 +181,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"],
   };
 };
@@ -107,25 +238,46 @@ export const evaluateLinkAudit = (
   policy: AuditOrphanPolicy
 ): AuditRuleContribution[] => {
   const unresolved: AuditFindingDraft[] = [];
+  const outsideIndex: AuditFindingDraft[] = [];
   const ambiguous: AuditFindingDraft[] = [];
   const connected = new Set<number>();
   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) {
+        (link.outsideIndex === true ? outsideIndex : 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 +331,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 +339,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,10 +356,29 @@ 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,
     },
+    {
+      // Informational: Obsidian resolves these links, so they never fail
+      // the audit. Info findings keep the rule passing.
+      ...common,
+      ruleId: "links.outside-index",
+      category: "links",
+      status: partial ? ("inconclusive" as const) : ("pass" as const),
+      message: [
+        partial
+          ? "Outside-index scan was truncated"
+          : `${outsideIndex.length} links point to existing files outside the index`,
+        ...(snapshot.outsideIndexDiagnostic
+          ? [snapshot.outsideIndexDiagnostic]
+          : []),
+      ].join("; "),
+      findings: boundedFindings(outsideIndex, maxFindingsPerRule),
+      findingCount: outsideIndex.length,
+      skipReason: partial ? "snapshot_truncated" : null,
+    },
     {
       ...common,
       ruleId: "links.parser-boundary",

package/src/core/audit-outside-index.ts

@@ -0,0 +1,215 @@
+/**
+ * Existence-only classification of unresolved workspace wiki links whose
+ * target is a file inside the link workspace that is not an indexed document
+ * (an attachment, or a note in an unindexed or excluded folder). Obsidian
+ * resolves such links, so the link audit reports them as `outside-index`
+ * instead of unresolved. Only file names are listed: no file is opened,
+ * indexed, or returned, and no graph edge is created.
+ *
+ * @module src/core/audit-outside-index
+ */
+
+import type { Database } from "bun:sqlite";
+
+// node:fs/promises readdir/realpath/stat: directory enumeration and symlink
+// resolution; Bun has no equivalent that can skip an unreadable folder
+// instead of failing the scan.
+import { readdir, realpath, stat } from "node:fs/promises";
+// node:path join: platform path algebra; no Bun equivalent.
+import { join } from "node:path";
+
+import type { AuditLinkSnapshot } from "../store/sqlite/graph-link-resolver";
+
+import {
+  createWorkspaceFileMatcher,
+  loadLinkWorkspaceMemberships,
+} from "../store/sqlite/workspace-link-resolver";
+import { pathContains, placeDocument } from "./link-workspace";
+
+/** Upper bound of files listed per workspace; beyond it the listing is partial. */
+export const WORKSPACE_FILE_LISTING_MAX_FILES = 200_000;
+
+export interface WorkspaceFileListing {
+  /** Workspace-relative POSIX paths (NFC) of every non-hidden file. */
+  files: string[];
+  /** False when a folder could not be read or the file bound was reached. */
+  complete: boolean;
+}
+
+interface WorkspaceDirectoryEntry {
+  name: string;
+  isFile(): boolean;
+  isDirectory(): boolean;
+  isSymbolicLink(): boolean;
+}
+
+/** Filesystem reads the listing needs; injectable for tests. */
+export interface WorkspaceFileSystem {
+  readDirectory(path: string): Promise<WorkspaceDirectoryEntry[]>;
+  realPath(path: string): Promise<string>;
+  isRegularFile(path: string): Promise<boolean>;
+}
+
+const nodeWorkspaceFileSystem: WorkspaceFileSystem = {
+  readDirectory: (path) => readdir(path, { withFileTypes: true }),
+  realPath: (path) => realpath(path),
+  isRegularFile: async (path) => (await stat(path)).isFile(),
+};
+
+/** A symlink target that does not exist (or loops) is not a file, not an error. */
+const MISSING_TARGET_CODES = new Set(["ENOENT", "ENOTDIR", "ELOOP"]);
+
+/**
+ * A symlink counts as a file only when it resolves to an existing regular
+ * file inside the workspace. Dangling links, links to folders and links that
+ * leave the workspace are not files. Other errors are reported as such.
+ */
+const symlinkIsWorkspaceFile = async (
+  fs: WorkspaceFileSystem,
+  realRoot: string,
+  path: string
+): Promise<"file" | "not-file" | "error"> => {
+  try {
+    const target = await fs.realPath(path);
+    if (!pathContains(realRoot, target)) return "not-file";
+    return (await fs.isRegularFile(target)) ? "file" : "not-file";
+  } catch (cause) {
+    const code = (cause as NodeJS.ErrnoException | undefined)?.code;
+    return code !== undefined && MISSING_TARGET_CODES.has(code)
+      ? "not-file"
+      : "error";
+  }
+};
+
+/**
+ * List every file below a workspace root once. Hidden files and folders
+ * (`.obsidian`, `.trash`, `.git`) are skipped, as Obsidian does; symlinked
+ * folders are not descended. Filesystem calls use the names as stored on
+ * disk; only the returned paths are NFC-normalized for matching. An
+ * unreadable folder is skipped and marks the listing incomplete, so links
+ * into it stay unresolved.
+ */
+export const listWorkspaceFiles = async (
+  root: string,
+  options: {
+    maxFiles?: number;
+    signal?: AbortSignal;
+    fileSystem?: WorkspaceFileSystem;
+  } = {}
+): Promise<WorkspaceFileListing> => {
+  const maxFiles = options.maxFiles ?? WORKSPACE_FILE_LISTING_MAX_FILES;
+  const fs = options.fileSystem ?? nodeWorkspaceFileSystem;
+  const files: string[] = [];
+  let complete = true;
+  let realRoot: string;
+  try {
+    realRoot = await fs.realPath(root);
+  } catch {
+    return { files, complete: false };
+  }
+  // Each folder keeps its on-disk segments; matching uses the NFC path.
+  const queue: string[][] = [[]];
+  for (let head = 0; head < queue.length; head += 1) {
+    options.signal?.throwIfAborted();
+    const segments = queue[head] as string[];
+    let entries;
+    try {
+      entries = await fs.readDirectory(join(root, ...segments));
+    } catch {
+      complete = false;
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const entrySegments = [...segments, entry.name];
+      let isFile = entry.isFile();
+      if (entry.isDirectory()) {
+        queue.push(entrySegments);
+        continue;
+      }
+      if (entry.isSymbolicLink()) {
+        const kind = await symlinkIsWorkspaceFile(
+          fs,
+          realRoot,
+          join(root, ...entrySegments)
+        );
+        if (kind === "error") complete = false;
+        isFile = kind === "file";
+      }
+      if (!isFile) continue;
+      if (files.length >= maxFiles) return { files, complete: false };
+      files.push(entrySegments.join("/").normalize("NFC"));
+    }
+  }
+  return { files, complete };
+};
+
+/**
+ * Mark unresolved plain wiki links of audited documents inside a link
+ * workspace whose target exists as a workspace file. Each involved workspace
+ * is listed once per call. A failed or partial listing never marks a link
+ * that is not in it; the snapshot then carries one diagnostic.
+ */
+export const markOutsideIndexLinks = async (
+  db: Database,
+  snapshot: AuditLinkSnapshot,
+  options: { maxFiles?: number; signal?: AbortSignal } = {}
+): Promise<AuditLinkSnapshot> => {
+  const audited = snapshot.auditedDocumentIds
+    ? new Set(snapshot.auditedDocumentIds)
+    : null;
+  const candidates = snapshot.links
+    .map((link, index) => ({ link, index }))
+    .filter(
+      ({ link }) =>
+        link.resolved === null &&
+        link.linkType === "wiki" &&
+        link.explicitCollection !== true &&
+        (audited === null || audited.has(link.sourceId))
+    );
+  if (candidates.length === 0) return snapshot;
+  const memberships = loadLinkWorkspaceMemberships(db);
+  const documentRelPaths = new Map(
+    snapshot.documents.map((document) => [document.id, document.relPath])
+  );
+  const placed = candidates.flatMap(({ link, index }) => {
+    const placement = placeDocument(
+      memberships.get(link.sourceCollection),
+      documentRelPaths.get(link.sourceId) ?? link.sourceRelPath
+    );
+    return placement.key === null
+      ? []
+      : [{ link, index, key: placement.key, sourcePath: placement.path }];
+  });
+  if (placed.length === 0) return snapshot;
+  const matchers = new Map<
+    string,
+    ReturnType<typeof createWorkspaceFileMatcher>
+  >();
+  const maxFiles = options.maxFiles ?? WORKSPACE_FILE_LISTING_MAX_FILES;
+  let incomplete = 0;
+  for (const key of new Set(placed.map((entry) => entry.key))) {
+    const listing = await listWorkspaceFiles(key, {
+      maxFiles,
+      signal: options.signal,
+    });
+    if (!listing.complete) incomplete += 1;
+    matchers.set(key, createWorkspaceFileMatcher(listing.files));
+  }
+  const links = [...snapshot.links];
+  for (const entry of placed) {
+    const matches = matchers.get(entry.key);
+    if (matches?.(entry.link.targetRefNorm, entry.sourcePath)) {
+      links[entry.index] = { ...entry.link, outsideIndex: true };
+    }
+  }
+  return {
+    ...snapshot,
+    links,
+    ...(incomplete > 0
+      ? {
+          outsideIndexDiagnostic: `The file listing of ${incomplete} link workspace${incomplete === 1 ? " was" : "s were"} incomplete (an unreadable folder or link, or more than ${maxFiles} files); links to files it missed stay unresolved`,
+        }
+      : {}),
+  };
+};

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