@gmickel/gno 1.32.0 → 1.34.0

package/src/core/capture.ts

@@ -176,6 +176,70 @@ const CAPTURE_SOURCE_STRING_KEYS = new Set([
   "externalId",
 ]);
 
+export const CAPTURE_PROVENANCE_REQUIRED_FIELDS = [
+  "kind",
+  "capturedAt",
+] as const;
+
+export interface CaptureProvenanceIssue {
+  field: string;
+  reason: "missing" | "invalid";
+}
+
+/** Validate only fields declared by the CaptureSource contract. */
+export const validateDeclaredCaptureProvenance = (
+  source: Partial<CaptureSource>
+): CaptureProvenanceIssue[] => {
+  const issues: CaptureProvenanceIssue[] = [];
+  if (!source.kind) issues.push({ field: "source.kind", reason: "missing" });
+  else if (!VALID_SOURCE_KINDS.has(source.kind))
+    issues.push({ field: "source.kind", reason: "invalid" });
+  const capturedAt = source.capturedAt as unknown;
+  if (capturedAt === undefined || capturedAt === null || capturedAt === "")
+    issues.push({ field: "source.capturedAt", reason: "missing" });
+  else if (
+    typeof capturedAt !== "string" ||
+    Number.isNaN(new Date(capturedAt).getTime())
+  )
+    issues.push({ field: "source.capturedAt", reason: "invalid" });
+  for (const field of ["observedAt", "publishedAt"] as const) {
+    const value = source[field];
+    if (value === undefined) continue;
+    if (typeof value !== "string" || Number.isNaN(new Date(value).getTime())) {
+      issues.push({ field: `source.${field}`, reason: "invalid" });
+    }
+  }
+  for (const field of URL_SOURCE_FIELDS) {
+    const value = source[field as keyof CaptureSource];
+    if (value === undefined) continue;
+    if (typeof value !== "string") {
+      issues.push({ field: `source.${field}`, reason: "invalid" });
+      continue;
+    }
+    try {
+      new URL(value);
+    } catch {
+      issues.push({ field: `source.${field}`, reason: "invalid" });
+    }
+  }
+  for (const field of CAPTURE_SOURCE_STRING_KEYS) {
+    if (URL_SOURCE_FIELDS.has(field) || field === "publishedAt") continue;
+    const value = source[field as keyof CaptureSource];
+    if (value !== undefined && value !== null && typeof value !== "string") {
+      issues.push({ field: `source.${field}`, reason: "invalid" });
+    }
+  }
+  if (
+    source.browserClip !== undefined &&
+    !browserClipProvenanceSchema.safeParse(source.browserClip).success
+  ) {
+    issues.push({ field: "source.browserClip", reason: "invalid" });
+  }
+  return issues.sort((left, right) =>
+    left.field < right.field ? -1 : left.field > right.field ? 1 : 0
+  );
+};
+
 function normalizeContentForHash(content: string): string {
   return content.replace(/\r\n/g, "\n").trim();
 }
@@ -468,11 +532,35 @@ function shouldSkipNestedFrontmatterLine(line: string): boolean {
   return line.startsWith("  ") || line.trim() === "";
 }
 
+const parseFrontmatterScalar = (rawValue: string): unknown => {
+  try {
+    return (Bun.YAML.parse(`value: ${rawValue}`) as { value?: unknown }).value;
+  } catch {
+    return stripYamlString(rawValue);
+  }
+};
+
 export function extractCaptureSourceFromFrontmatter(
   content: string
 ): Partial<CaptureSource> {
   const { lines } = splitFrontmatter(content);
   const source: Partial<CaptureSource> = {};
+  let parsedSourceMapping = false;
+  try {
+    const parsed = Bun.YAML.parse(lines.join("\n")) as { source?: unknown };
+    if (
+      parsed.source !== null &&
+      typeof parsed.source === "object" &&
+      !Array.isArray(parsed.source)
+    ) {
+      parsedSourceMapping = true;
+      for (const [key, value] of Object.entries(parsed.source)) {
+        source[key as keyof CaptureSource] = value as never;
+      }
+    }
+  } catch {
+    // Invalid YAML falls through to the declaration-preserving parser below.
+  }
   for (let index = 0; index < lines.length; index += 1) {
     const line = lines[index];
     if (line === undefined) {
@@ -505,6 +593,30 @@ export function extractCaptureSourceFromFrontmatter(
     if (key !== "source") {
       continue;
     }
+    if (parsedSourceMapping) {
+      continue;
+    }
+    if (rawValue) {
+      try {
+        const parsed = Bun.YAML.parse(`source: ${rawValue}`) as {
+          source?: unknown;
+        };
+        if (
+          parsed.source !== null &&
+          typeof parsed.source === "object" &&
+          !Array.isArray(parsed.source)
+        ) {
+          for (const [nestedKey, nestedValue] of Object.entries(
+            parsed.source
+          )) {
+            source[nestedKey as keyof CaptureSource] = nestedValue as never;
+          }
+        }
+      } catch {
+        // Invalid inline YAML remains declaration-visible to the audit.
+      }
+      continue;
+    }
     for (
       let nestedIndex = index + 1;
       nestedIndex < lines.length;
@@ -527,19 +639,100 @@ export function extractCaptureSourceFromFrontmatter(
           try {
             const parsed = JSON.parse(nestedValue) as unknown;
             const provenance = browserClipProvenanceSchema.safeParse(parsed);
-            if (provenance.success) source.browserClip = provenance.data;
+            // Retain invalid declarations so provenance audits can report them.
+            // Runtime consumers only inspect known fields via optional chaining.
+            source.browserClip = provenance.success
+              ? provenance.data
+              : (parsed as BrowserClipProvenance);
           } catch {
-            // Ignore malformed optional browser provenance.
+            source.browserClip = {} as BrowserClipProvenance;
           }
           continue;
         }
-        source[nestedKey] = stripYamlString(nestedValue) as never;
+        source[nestedKey] = parseFrontmatterScalar(nestedValue) as never;
       }
     }
   }
   return source;
 }
 
+/** Whether a note explicitly declares the CaptureSource frontmatter contract. */
+export const hasDeclaredCaptureSource = (content: string): boolean => {
+  const { lines } = splitFrontmatter(content);
+  const captureKeys = new Set<string>([
+    "kind",
+    "capturedAt",
+    "url",
+    "docid",
+    "uri",
+    "mime",
+    "ext",
+    "title",
+    "author",
+    "canonicalUrl",
+    "site",
+    "publishedAt",
+    "observedAt",
+    "externalId",
+    "browserClip",
+  ]);
+  try {
+    const parsed = Bun.YAML.parse(lines.join("\n")) as { source?: unknown };
+    if (
+      parsed.source !== null &&
+      typeof parsed.source === "object" &&
+      !Array.isArray(parsed.source)
+    ) {
+      const keys = Object.keys(parsed.source);
+      if (keys.length === 0 || keys.some((key) => captureKeys.has(key))) {
+        return true;
+      }
+    }
+  } catch {
+    // Fall through to the declaration-preserving line parser below.
+  }
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (line === undefined) continue;
+    const inlineSource = /^source\s*:\s*(\{.*\})\s*$/u.exec(line)?.[1];
+    if (inlineSource !== undefined) {
+      if (/^\{\s*\}$/u.test(inlineSource)) return true;
+      try {
+        const parsed = Bun.YAML.parse(`source: ${inlineSource}`) as {
+          source?: unknown;
+        };
+        if (
+          parsed.source !== null &&
+          typeof parsed.source === "object" &&
+          !Array.isArray(parsed.source) &&
+          Object.keys(parsed.source).some((key) => captureKeys.has(key))
+        ) {
+          return true;
+        }
+      } catch {
+        return true;
+      }
+      continue;
+    }
+    if (!/^source\s*:\s*$/u.test(line)) continue;
+    for (
+      let nestedIndex = index + 1;
+      nestedIndex < lines.length;
+      nestedIndex += 1
+    ) {
+      const nested = lines[nestedIndex];
+      if (!nested?.startsWith("  ")) break;
+      const colonIndex = nested.indexOf(":");
+      if (colonIndex <= 0) continue;
+      const nestedKey = nested
+        .slice(0, colonIndex)
+        .trim() as keyof CaptureSource;
+      if (captureKeys.has(nestedKey)) return true;
+    }
+  }
+  return false;
+};
+
 function sourceFrontmatterLines(source: CaptureSource): string[] {
   const lines = ["source:"];
   for (const [key, value] of Object.entries(source)) {

package/src/core/document-capabilities.ts

@@ -12,10 +12,14 @@ export interface DocumentCapabilities {
   reason?: string;
 }
 
-const EDITABLE_EXTENSIONS = new Set([
+export const MARKDOWN_SOURCE_EXTENSIONS: ReadonlySet<string> = new Set([
   ".md",
   ".markdown",
   ".mdx",
+]);
+
+const EDITABLE_EXTENSIONS = new Set([
+  ...MARKDOWN_SOURCE_EXTENSIONS,
   ".txt",
   ".text",
 ]);
@@ -57,7 +61,7 @@ export function getDocumentCapabilities(input: {
   }
   const editable =
     EDITABLE_EXTENSIONS.has(ext) || isTextLikeMime(input.sourceMime);
-  const tagsWriteback = ext === ".md" || ext === ".markdown" || ext === ".mdx";
+  const tagsWriteback = MARKDOWN_SOURCE_EXTENSIONS.has(ext);
 
   if (editable) {
     return {
@@ -89,12 +93,9 @@ export function deriveEditableCopyRelPath(
   const baseName = parsed.name || "copy";
   const existing = new Set(existingRelPaths);
 
-  const baseCandidate =
-    parsed.ext.toLowerCase() === ".md" ||
-    parsed.ext.toLowerCase() === ".markdown" ||
-    parsed.ext.toLowerCase() === ".mdx"
-      ? `${prefix}${baseName}.copy.md`
-      : `${prefix}${baseName}.md`;
+  const baseCandidate = MARKDOWN_SOURCE_EXTENSIONS.has(parsed.ext.toLowerCase())
+    ? `${prefix}${baseName}.copy.md`
+    : `${prefix}${baseName}.md`;
 
   if (!existing.has(baseCandidate)) {
     return baseCandidate;

package/src/core/record-metadata.ts

@@ -21,6 +21,39 @@ interface RecordMetadataSource {
   recordAdapterFingerprint?: string | null;
 }
 
+export const RECORD_PROVENANCE_REQUIRED_FIELDS = [
+  "recordKey",
+  "recordSourceLocator",
+  "converterId",
+  "converterVersion",
+  "recordAdapterFingerprint",
+] as const;
+
+export interface RecordProvenanceIssue {
+  field: (typeof RECORD_PROVENANCE_REQUIRED_FIELDS)[number];
+  reason: "missing";
+}
+
+/** Generic converter identity alone does not declare a logical-record contract. */
+export const hasDeclaredRecordProvenance = (
+  source: RecordMetadataSource
+): boolean =>
+  source.recordKey != null ||
+  source.recordSourceLocator != null ||
+  source.recordAdapterFingerprint != null ||
+  source.recordMetadata != null ||
+  source.recordAnchors != null;
+
+/** Validate completeness only when logical-record provenance is declared. */
+export const validateDeclaredRecordProvenance = (
+  source: RecordMetadataSource
+): RecordProvenanceIssue[] => {
+  if (!hasDeclaredRecordProvenance(source)) return [];
+  return RECORD_PROVENANCE_REQUIRED_FIELDS.filter(
+    (field) => !source[field]
+  ).map((field) => ({ field, reason: "missing" as const }));
+};
+
 /** Project only bounded, collection-relative logical-record provenance. */
 export const projectRecordEvidenceMetadata = (
   source: RecordMetadataSource

package/src/ingestion/strip.ts

@@ -3,7 +3,7 @@
  *
  * Identifies regions to exclude from link/tag extraction:
  * - YAML frontmatter
- * - Fenced code blocks
+ * - Fenced code blocks (CommonMark backtick and tilde fences)
  * - Inline code
  * - HTML comments
  *
@@ -39,15 +39,153 @@ export interface ExcludedRange {
 /** Frontmatter at start of file (YAML between --- delimiters) */
 const FRONTMATTER_REGEX = /^---\r?\n[\s\S]*?(?:\r?\n)?---(?:\r?\n|$)/;
 
-/** Fenced code blocks (``` with optional language) */
-const FENCED_CODE_REGEX = /^```[^\n]*\n[\s\S]*?^```/gm;
+/** CommonMark fence opener: 0–3 spaces, then 3+ backticks or tildes + info. */
+const FENCE_OPEN_REGEX = /^ {0,3}(`{3,}|~{3,})(.*)$/u;
 
-/** Inline code (backticks, non-greedy) */
-const INLINE_CODE_REGEX = /`[^`\n]+`/g;
+/** CommonMark fence closer: matching character, length ≥ opener, trailing space/tabs only. */
+const FENCE_CLOSE_REGEX = /^ {0,3}(`{3,}|~{3,})[\t ]*$/u;
 
 /** HTML comments */
 const HTML_COMMENT_REGEX = /<!--[\s\S]*?-->/g;
 
+interface OpenFence {
+  marker: "`" | "~";
+  length: number;
+  start: number;
+}
+
+/**
+ * Collect CommonMark fenced code ranges (backtick and tilde). A closer must
+ * use the same character and be at least as long as the opener; when omitted,
+ * CommonMark extends the fenced block through end of input.
+ */
+const collectFencedCodeRanges = (markdown: string): ExcludedRange[] => {
+  const ranges: ExcludedRange[] = [];
+  let offset = 0;
+  let open: OpenFence | null = null;
+
+  while (offset <= markdown.length) {
+    const nextNl = markdown.indexOf("\n", offset);
+    const lineEnd = nextNl === -1 ? markdown.length : nextNl;
+    const rawLine = markdown.slice(offset, lineEnd);
+    const logical = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+
+    if (open) {
+      const closeRun = FENCE_CLOSE_REGEX.exec(logical)?.[1];
+      if (
+        closeRun &&
+        closeRun[0] === open.marker &&
+        closeRun.length >= open.length
+      ) {
+        const end = nextNl === -1 ? markdown.length : nextNl + 1;
+        ranges.push({ start: open.start, end, kind: "fenced_code" });
+        open = null;
+      }
+    } else {
+      const openMatch = FENCE_OPEN_REGEX.exec(logical);
+      const run = openMatch?.[1];
+      const suffix = openMatch?.[2] ?? "";
+      // Backtick info strings cannot contain backticks (CommonMark).
+      if (run && !(run[0] === "`" && suffix.includes("`"))) {
+        open = {
+          marker: run[0] as OpenFence["marker"],
+          length: run.length,
+          start: offset,
+        };
+      }
+    }
+
+    if (nextNl === -1) break;
+    offset = nextNl + 1;
+  }
+
+  if (open) {
+    ranges.push({
+      start: open.start,
+      end: markdown.length,
+      kind: "fenced_code",
+    });
+  }
+
+  return ranges;
+};
+
+interface BacktickRun {
+  end: number;
+  length: number;
+  start: number;
+}
+
+/** CommonMark code spans close only on a backtick run of equal length. */
+const collectInlineCodeRanges = (
+  markdown: string,
+  excludedRanges: ExcludedRange[]
+): ExcludedRange[] => {
+  const runs: BacktickRun[] = [];
+  let cursor = 0;
+  let excludedIndex = 0;
+  while (cursor < markdown.length) {
+    while (
+      excludedRanges[excludedIndex] &&
+      excludedRanges[excludedIndex]!.end <= cursor
+    ) {
+      excludedIndex += 1;
+    }
+    const excluded = excludedRanges[excludedIndex];
+    if (excluded && cursor >= excluded.start && cursor < excluded.end) {
+      cursor = excluded.end;
+      continue;
+    }
+    if (markdown[cursor] !== "`") {
+      cursor += 1;
+      continue;
+    }
+    const start = cursor;
+    while (markdown[cursor] === "`") cursor += 1;
+    let backslashes = 0;
+    for (let i = start - 1; i >= 0 && markdown[i] === "\\"; i -= 1) {
+      backslashes += 1;
+    }
+    if (backslashes % 2 === 0) {
+      runs.push({ start, end: cursor, length: cursor - start });
+    }
+  }
+
+  const nextMatchingRun = Array.from<number | undefined>({
+    length: runs.length,
+  });
+  const latestByLength = new Map<number, number>();
+  for (let index = runs.length - 1; index >= 0; index -= 1) {
+    const run = runs[index];
+    if (!run) continue;
+    nextMatchingRun[index] = latestByLength.get(run.length);
+    latestByLength.set(run.length, index);
+  }
+
+  const ranges: ExcludedRange[] = [];
+  let index = 0;
+  while (index < runs.length) {
+    const closeIndex = nextMatchingRun[index];
+    const opener = runs[index];
+    if (closeIndex === undefined || !opener) {
+      index += 1;
+      continue;
+    }
+    const closer = runs[closeIndex];
+    if (!closer) {
+      index += 1;
+      continue;
+    }
+    ranges.push({
+      start: opener.start,
+      end: closer.end,
+      kind: "inline_code",
+    });
+    index = closeIndex + 1;
+  }
+  return ranges;
+};
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Main Functions
 // ─────────────────────────────────────────────────────────────────────────────
@@ -70,29 +208,12 @@ export function getExcludedRanges(markdown: string): ExcludedRange[] {
     });
   }
 
-  // 2. Fenced code blocks
-  FENCED_CODE_REGEX.lastIndex = 0;
-  let match: RegExpExecArray | null;
-  while ((match = FENCED_CODE_REGEX.exec(markdown)) !== null) {
-    ranges.push({
-      start: match.index,
-      end: match.index + match[0].length,
-      kind: "fenced_code",
-    });
-  }
-
-  // 3. Inline code
-  INLINE_CODE_REGEX.lastIndex = 0;
-  while ((match = INLINE_CODE_REGEX.exec(markdown)) !== null) {
-    ranges.push({
-      start: match.index,
-      end: match.index + match[0].length,
-      kind: "inline_code",
-    });
-  }
+  // 2. Fenced code blocks (backtick + tilde, CommonMark matching rules)
+  ranges.push(...collectFencedCodeRanges(markdown));
 
-  // 4. HTML comments
+  // 3. HTML comments
   HTML_COMMENT_REGEX.lastIndex = 0;
+  let match: RegExpExecArray | null;
   while ((match = HTML_COMMENT_REGEX.exec(markdown)) !== null) {
     ranges.push({
       start: match.index,
@@ -101,6 +222,11 @@ export function getExcludedRanges(markdown: string): ExcludedRange[] {
     });
   }
 
+  // 4. Inline code. Pair delimiters only in visible prose so unmatched
+  // backticks inside already-excluded blocks cannot consume later content.
+  ranges.sort((a, b) => a.start - b.start);
+  ranges.push(...collectInlineCodeRanges(markdown, ranges));
+
   // Sort by start position for efficient lookup
   ranges.sort((a, b) => a.start - b.start);
 

package/src/mcp/http-egress.ts

@@ -17,6 +17,7 @@ import { evaluateEgressPolicy } from "../core/egress-policy";
 export const MCP_HTTP_EGRESS_TOOLS = {
   gno_add_collection: "metadata",
   gno_ask: "capsule",
+  gno_audit: "metadata",
   gno_backlinks: "metadata",
   gno_capture: "metadata",
   gno_changes: "metadata",
@@ -125,6 +126,13 @@ const requestedCollections = (
   const names = new Set<string>();
   const direct = args.collection;
   if (typeof direct === "string") names.add(direct.trim().toLowerCase());
+  if (record?.name === "gno_audit" && Array.isArray(args.collections)) {
+    for (const value of args.collections) {
+      if (typeof value !== "string") continue;
+      const normalized = value.trim().toLowerCase();
+      if (normalized) names.add(normalized);
+    }
+  }
   for (const key of ["ref", "target", "from", "to", "root", "uri"]) {
     const collection = collectionFromRef(args[key]);
     if (collection) names.add(collection);

package/src/mcp/tools/audit.ts

@@ -0,0 +1,97 @@
+/** MCP gno_audit read-only knowledge-integrity tool. */
+
+import { z } from "zod";
+
+import type { AuditCategory, AuditReport } from "../../core/audit";
+import type { ToolContext } from "../server";
+
+import { AUDIT_CATEGORIES } from "../../core/audit";
+import { runWorkspaceAudit } from "../../core/audit-workspace";
+import { normalizeTag, validateTag } from "../../core/tags";
+import { normalizeCollectionName } from "../../core/validation";
+import { runTool, type ToolResult } from "./index";
+
+export const auditInputSchema = z
+  .object({
+    category: z
+      .enum(["links", "provenance", "freshness", "all"])
+      .default("all"),
+    collections: z.array(z.string().min(1)).max(256).default([]),
+    paths: z.array(z.string().min(1)).max(256).default([]),
+    tags: z.array(z.string().min(1)).max(256).default([]),
+    maxFindings: z.number().int().min(1).max(1000).default(100),
+    maxAgeDays: z.number().int().min(1).optional(),
+    orphanRoots: z.array(z.string().min(1)).max(256).default([]),
+    orphanIgnorePrefixes: z.array(z.string().min(1)).max(256).default([]),
+  })
+  .strict();
+
+export type AuditMcpInput = z.infer<typeof auditInputSchema>;
+
+export const AUDIT_MCP_ANNOTATIONS = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const;
+
+const categoriesFor = (category: AuditMcpInput["category"]): AuditCategory[] =>
+  category === "all" ? [...AUDIT_CATEGORIES] : [category];
+
+const formatAudit = (report: AuditReport): string =>
+  [
+    `Audit: ${report.status}`,
+    `Categories: ${report.scope.categories.join(", ")}`,
+    `Rules: ${report.counts.rules.total}`,
+    `Findings: ${report.counts.findings.total} (${report.counts.findings.returned} returned)`,
+    ...report.findings.map(
+      (finding) =>
+        `[${finding.severity}] ${finding.ruleId}: ${finding.subject}${finding.location ? ` ${finding.location}` : ""} — ${finding.message}`
+    ),
+  ].join("\n");
+
+export const handleAudit = (
+  input: AuditMcpInput,
+  ctx: ToolContext,
+  signal?: AbortSignal
+): Promise<ToolResult> =>
+  runTool(
+    ctx,
+    "gno_audit",
+    async () => {
+      const normalizedCollections = input.collections.map(
+        normalizeCollectionName
+      );
+      const normalizedTags = input.tags.map(normalizeTag);
+      const invalidTag = normalizedTags.find((tag) => !validateTag(tag));
+      if (invalidTag) throw new Error(`Invalid tag: "${invalidTag}"`);
+      const missingCollection = normalizedCollections.find(
+        (name) =>
+          !ctx.collections.some((collection) => collection.name === name)
+      );
+      if (missingCollection) {
+        throw new Error(`Collection not found: ${missingCollection}`);
+      }
+      const result = await runWorkspaceAudit({
+        store: ctx.store,
+        config: ctx.config,
+        collections: ctx.collections,
+        indexName: ctx.indexName,
+        categories: categoriesFor(input.category),
+        collectionFilters: normalizedCollections,
+        pathFilters: input.paths,
+        tagFilters: normalizedTags,
+        maxFindings: input.maxFindings,
+        agePolicy:
+          input.maxAgeDays === undefined
+            ? undefined
+            : { maxAgeDays: input.maxAgeDays },
+        orphanRoots: input.orphanRoots,
+        orphanIgnorePrefixes: input.orphanIgnorePrefixes,
+        signal,
+      });
+      if (!result.ok) throw new Error(result.error);
+      return result.report;
+    },
+    formatAudit
+  );

package/src/mcp/tools/index.ts

@@ -20,6 +20,7 @@ import { RETRIEVAL_TRACE_METADATA } from "../../core/retrieval-trace-session";
 import { normalizeTag } from "../../core/tags";
 import { handleAddCollection } from "./add-collection";
 import { askInputSchema, handleAsk } from "./ask";
+import { AUDIT_MCP_ANNOTATIONS, auditInputSchema, handleAudit } from "./audit";
 import { handleCapture } from "./capture";
 import {
   changesInputSchema,
@@ -130,6 +131,8 @@ export const MCP_TOOL_DESCRIPTIONS = {
     "Create or resolve a durable SectionTargetV1 against one indexed document. action=create needs ref plus exactly one of anchor|line; action=resolve needs ref plus target. Exact/recovered include citation (uri, anchor, title, inclusive lines, fingerprint); ambiguous/stale/missing omit citation and are not safe to navigate or cite. Read-only — does not write or persist targets. Follow navigable ranges with gno_get fromLine/lineCount.",
   status:
     "Get index health: collection count, document count, chunk count, embedding backlog, and per-collection stats. Check first when vector/hybrid results look stale or unavailable.",
+  audit:
+    "Run deterministic, offline, read-only integrity audits for links, declared provenance completeness, and source/index freshness. Returns stable bounded findings and explicit partial/unavailable states; never repairs or mutates the workspace.",
   context:
     "Compile one deterministic, budgeted, extractive evidence Capsule with exact line spans, coverage gaps, omissions, provenance, and verification fingerprints. Raw search/get tools remain available for manual retrieval.",
   contextVerify:
@@ -1090,6 +1093,16 @@ export function registerTools(server: McpServer, ctx: ToolContext): void {
     (args) => handleStatus(args, ctx)
   );
 
+  server.registerTool(
+    "gno_audit",
+    {
+      description: MCP_TOOL_DESCRIPTIONS.audit,
+      inputSchema: auditInputSchema,
+      annotations: AUDIT_MCP_ANNOTATIONS,
+    },
+    (args, extra) => handleAudit(args, ctx, extra.signal)
+  );
+
   server.registerTool(
     "gno_egress_policy_get",
     {