@gmickel/gno 1.20.0 → 1.22.0

package/src/publish/export-service.ts

@@ -8,7 +8,7 @@ import type { Collection } from "../config/types";
 import type { DocumentRow, StorePort, TagRow } from "../store/types";
 
 import { parseRef } from "../core/ref-parser";
-import { parseFrontmatter } from "../ingestion/frontmatter";
+import { parseFrontmatter, stripFrontmatter } from "../ingestion/frontmatter";
 import { getContentBatch } from "../store/content-batch";
 import {
   buildEncryptedPublishArtifact,
@@ -186,11 +186,11 @@ async function exportCollectionArtifact(
     if (isPublishDisabledByFrontmatter(rawMarkdown)) {
       continue;
     }
+    const frontmatter = parseFrontmatter(rawMarkdown).metadata;
     const sanitized = sanitizeObsidianMarkdown(rawMarkdown);
     warnings.push(...sanitized.warnings);
-    const markdown = sanitized.markdown;
+    const markdown = stripFrontmatter(sanitized.markdown);
     const tags = tagsByDocId.get(doc.id) ?? [];
-    const frontmatter = parseFrontmatter(markdown).metadata;
     const title = deriveExportedTitle(doc);
     notes.push({
       markdown,
@@ -240,7 +240,6 @@ async function exportCollectionArtifact(
       encryptedPayload: encrypted.encryptedPayload,
       routeSlug,
       secretToken: encrypted.secretToken,
-      source: collection.name,
       sourceType: "collection",
     });
   }
@@ -249,7 +248,6 @@ async function exportCollectionArtifact(
     homeNoteSlug: chooseHomeNoteSlug(notes),
     notes,
     routeSlug,
-    source: collection.name,
     sourceType: "collection",
     summary,
     title,
@@ -274,11 +272,11 @@ async function exportDocumentArtifact(
       `Refused to export: ${doc.uri} has publish: false in frontmatter`
     );
   }
+  const frontmatter = parseFrontmatter(rawMarkdown).metadata;
   const sanitized = sanitizeObsidianMarkdown(rawMarkdown);
   warnings.push(...sanitized.warnings);
-  const markdown = sanitized.markdown;
+  const markdown = stripFrontmatter(sanitized.markdown);
   const tags = await loadDocumentTags(store, doc);
-  const frontmatter = parseFrontmatter(markdown).metadata;
   const title = options.title ?? deriveExportedTitle(doc);
   const summary =
     options.summary ?? deriveExportedSummary(markdown, frontmatter);
@@ -315,7 +313,6 @@ async function exportDocumentArtifact(
       encryptedPayload: encrypted.encryptedPayload,
       routeSlug,
       secretToken: encrypted.secretToken,
-      source: doc.uri,
       sourceType: "note",
     });
   }
@@ -331,7 +328,6 @@ async function exportDocumentArtifact(
       },
     ],
     routeSlug,
-    source: doc.uri,
     sourceType: "note",
     summary,
     title,

package/src/publish/metadata.ts

@@ -0,0 +1,195 @@
+/**
+ * Reader-safe publish metadata projection.
+ *
+ * @module src/publish/metadata
+ */
+
+import type { DocumentRow, TagRow } from "../store/types";
+
+const ALLOWED_FRONTMATTER_METADATA_KEYS = new Set([
+  "audience",
+  "canonical",
+  "canonicalUrl",
+  "canonicalURL",
+  "coverAlt",
+  "coverImage",
+  "icon",
+  "image",
+  "layout",
+  "publishedAt",
+  "readingTime",
+  "series",
+  "seriesOrder",
+  "status",
+  "subtitle",
+  "theme",
+  "topic",
+  "topics",
+]);
+
+const PUBLIC_URL_METADATA_KEYS = new Set([
+  "canonical",
+  "canonicalUrl",
+  "canonicalURL",
+  "coverImage",
+  "image",
+]);
+
+const FORBIDDEN_URI_TOKEN_PATTERN =
+  /(?:^|[^a-z0-9+.-])(?:file:(?:\/\/)?|gno:\/\/)/iu;
+const LOCAL_PATH_TOKEN_PATTERN =
+  /(?:^|[\s([{"'=,:;])(?:~[/\\]|[a-z]:[/\\]|\\\\[^\\/\s]+[/\\]|\/(?:Applications|bin|dev|etc|home|Library|mnt|opt|private|proc|root|srv|sys|System|tmp|Users|usr|var|Volumes)(?:[/\\]|$))/iu;
+const LOCAL_HOSTNAME_SUFFIX_PATTERN =
+  /(?:^|\.)(?:home|internal|lan|local|localhost)$/iu;
+
+const containsLocalReference = (value: string): boolean =>
+  FORBIDDEN_URI_TOKEN_PATTERN.test(value) ||
+  LOCAL_PATH_TOKEN_PATTERN.test(value);
+
+const isNonPublicIpv4 = (hostname: string): boolean => {
+  if (!/^\d{1,3}(?:\.\d{1,3}){3}$/u.test(hostname)) return false;
+  const octets = hostname.split(".").map(Number);
+  if (octets.some((octet) => octet > 255)) return true;
+  const [first = 0, second = 0, third = 0] = octets;
+  return (
+    first === 0 ||
+    first === 10 ||
+    first === 127 ||
+    first >= 224 ||
+    (first === 100 && second >= 64 && second <= 127) ||
+    (first === 169 && second === 254) ||
+    (first === 172 && second >= 16 && second <= 31) ||
+    (first === 192 && second === 0 && third === 0) ||
+    (first === 192 && second === 0 && third === 2) ||
+    (first === 192 && second === 168) ||
+    (first === 198 && (second === 18 || second === 19)) ||
+    (first === 198 && second === 51 && third === 100) ||
+    (first === 203 && second === 0 && third === 113)
+  );
+};
+
+const isNonPublicIpv6 = (hostname: string): boolean => {
+  const normalized = hostname.replace(/^\[|\]$/gu, "").toLowerCase();
+  if (!normalized.includes(":")) return false;
+  return (
+    normalized === "::" ||
+    normalized.startsWith("::") ||
+    normalized.startsWith("fc") ||
+    normalized.startsWith("fd") ||
+    /^fe[89ab]/u.test(normalized) ||
+    normalized.startsWith("ff") ||
+    normalized.startsWith("2001:db8:")
+  );
+};
+
+const isPublicHttpUrl = (value: string): boolean => {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+
+  if (
+    (url.protocol !== "http:" && url.protocol !== "https:") ||
+    url.username.length > 0 ||
+    url.password.length > 0
+  ) {
+    return false;
+  }
+
+  const hostname = url.hostname.replace(/\.$/u, "").toLowerCase();
+  if (
+    hostname.length === 0 ||
+    LOCAL_HOSTNAME_SUFFIX_PATTERN.test(hostname) ||
+    isNonPublicIpv4(hostname) ||
+    isNonPublicIpv6(hostname)
+  ) {
+    return false;
+  }
+
+  const isIpLiteral =
+    hostname.includes(":") || /^\d+(?:\.\d+){3}$/u.test(hostname);
+  return isIpLiteral || hostname.includes(".");
+};
+
+const isSafeMetadataValue = (key: string, value: string): boolean => {
+  if (containsLocalReference(value)) {
+    return false;
+  }
+  if (
+    PUBLIC_URL_METADATA_KEYS.has(key) ||
+    (key === "icon" && /^https?:\/\//iu.test(value))
+  ) {
+    return isPublicHttpUrl(value);
+  }
+  return true;
+};
+
+const filterReaderSafeMetadata = (
+  metadata: Record<string, string | string[]>
+): Record<string, string | string[]> => {
+  const result: Record<string, string | string[]> = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (typeof value === "string") {
+      if (isSafeMetadataValue(key, value)) {
+        result[key] = value;
+      }
+      continue;
+    }
+
+    const safeValues = value.filter((entry) => isSafeMetadataValue(key, entry));
+    if (safeValues.length > 0) {
+      result[key] = safeValues;
+    }
+  }
+  return result;
+};
+
+export const buildExportedMetadata = (
+  doc: Pick<
+    DocumentRow,
+    "author" | "categories" | "contentType" | "frontmatterDate" | "languageHint"
+  >,
+  parsedFrontmatter: Record<string, unknown>,
+  tags: TagRow[]
+): Record<string, string | string[]> => {
+  const metadata: Record<string, string | string[]> = {};
+
+  if (doc.author) metadata.author = doc.author;
+  if (doc.contentType) metadata.contentType = doc.contentType;
+  if (doc.languageHint) metadata.language = doc.languageHint;
+  if (doc.frontmatterDate) metadata.date = doc.frontmatterDate;
+  if (doc.categories?.length) metadata.categories = doc.categories;
+
+  const tagValues = tags.map((tag) => tag.tag);
+  if (tagValues.length) metadata.tags = tagValues;
+
+  for (const [key, value] of Object.entries(parsedFrontmatter)) {
+    if (
+      key === "tags" ||
+      key === "title" ||
+      key === "summary" ||
+      !ALLOWED_FRONTMATTER_METADATA_KEYS.has(key)
+    ) {
+      continue;
+    }
+    if (
+      typeof value === "string" &&
+      value.trim() &&
+      isSafeMetadataValue(key, value.trim())
+    ) {
+      metadata[key] = value.trim();
+      continue;
+    }
+    if (Array.isArray(value)) {
+      const cleaned = value
+        .filter((entry): entry is string => typeof entry === "string")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0 && isSafeMetadataValue(key, entry));
+      if (cleaned.length > 0) metadata[key] = cleaned;
+    }
+  }
+
+  return filterReaderSafeMetadata(metadata);
+};

package/src/sdk/client.ts

@@ -40,6 +40,11 @@ import type {
   GnoRenameNoteOptions,
   GnoUpdateOptions,
   GnoVectorSearchOptions,
+  KnowledgeChangesResult,
+  KnowledgeDiffResult,
+  KnowledgeImpactInput,
+  KnowledgeImpactResult,
+  ListKnowledgeChangesInput,
 } from "./types";
 
 import {
@@ -84,6 +89,12 @@ import {
   planRenameRefactor,
 } from "../core/file-refactors";
 import { resolveEffectiveIndex } from "../core/indexed-reference";
+import {
+  analyzeKnowledgeImpact,
+  getKnowledgeDiff,
+  listKnowledgeChanges,
+  type KnowledgeDeltaServiceResult,
+} from "../core/knowledge-delta";
 import { resolveNoteCreatePlan } from "../core/note-creation";
 import { resolveNotePreset } from "../core/note-presets";
 import { RetrievalTraceManagementService } from "../core/retrieval-trace-management";
@@ -174,6 +185,11 @@ function unwrapTraceStore<T>(result: StoreResult<T>): T {
   });
 }
 
+function unwrapKnowledgeDelta<T>(result: KnowledgeDeltaServiceResult<T>): T {
+  if (result.success) return result.data;
+  throw sdkError(result.isValidation ? "VALIDATION" : "STORE", result.error);
+}
+
 async function resolveClientState(
   options: GnoClientInitOptions = {}
 ): Promise<OpenedClientState> {
@@ -1067,6 +1083,32 @@ class GnoClientImpl implements GnoClient {
     };
   }
 
+  async changes(
+    options: ListKnowledgeChangesInput = {}
+  ): Promise<KnowledgeChangesResult> {
+    this.assertOpen();
+    return unwrapKnowledgeDelta(
+      await listKnowledgeChanges(this.store, options)
+    );
+  }
+
+  async diff(ref: string, changeId?: string): Promise<KnowledgeDiffResult> {
+    this.assertOpen();
+    return unwrapKnowledgeDelta(
+      await getKnowledgeDiff(this.store, ref, changeId)
+    );
+  }
+
+  async impact(
+    ref: string,
+    options: KnowledgeImpactInput = {}
+  ): Promise<KnowledgeImpactResult> {
+    this.assertOpen();
+    return unwrapKnowledgeDelta(
+      await analyzeKnowledgeImpact(this.store, ref, options)
+    );
+  }
+
   async status(): Promise<IndexStatus> {
     this.assertOpen();
     return unwrapStore(

package/src/sdk/index.ts

@@ -54,6 +54,13 @@ export type {
   GnoSkippedDocument,
   GnoUpdateOptions,
   GnoVectorSearchOptions,
+  KnowledgeChange,
+  KnowledgeChangesResult,
+  KnowledgeDiffResult,
+  KnowledgeImpactEvidenceStep,
+  KnowledgeImpactInput,
+  KnowledgeImpactResult,
+  ListKnowledgeChangesInput,
 } from "./types";
 export {
   ContextCapsuleContractError,

package/src/sdk/types.ts

@@ -17,6 +17,13 @@ import type {
 } from "../core/context-capsule";
 import type { ContextEvidenceErrorCode } from "../core/context-evidence";
 import type { ContextVerifierErrorCode } from "../core/context-verifier";
+import type {
+  KnowledgeChangesResult,
+  KnowledgeDiffResult,
+  KnowledgeImpactInput,
+  KnowledgeImpactResult,
+  ListKnowledgeChangesInput,
+} from "../core/knowledge-delta";
 import type { NoteCollisionPolicy } from "../core/note-creation";
 import type { NotePresetId } from "../core/note-presets";
 import type {
@@ -52,6 +59,15 @@ export type {
   SyncResult,
 };
 export type { AskOptions, HybridSearchOptions } from "../pipeline/types";
+export type {
+  KnowledgeChange,
+  KnowledgeChangesResult,
+  KnowledgeDiffResult,
+  KnowledgeImpactEvidenceStep,
+  KnowledgeImpactInput,
+  KnowledgeImpactResult,
+  ListKnowledgeChangesInput,
+} from "../core/knowledge-delta";
 export type { Collection, Config as GnoConfig, Context } from "../config/types";
 export type { GetResponse as GnoGetResult } from "../cli/commands/get";
 export type {
@@ -233,6 +249,12 @@ export interface GnoClient {
   list(
     options?: GnoListOptions
   ): Promise<import("../cli/commands/ls").LsResponse>;
+  changes(options?: ListKnowledgeChangesInput): Promise<KnowledgeChangesResult>;
+  diff(ref: string, changeId?: string): Promise<KnowledgeDiffResult>;
+  impact(
+    ref: string,
+    options?: KnowledgeImpactInput
+  ): Promise<KnowledgeImpactResult>;
   status(): Promise<IndexStatus>;
   listRetrievalTraces(
     options?: RetrievalTraceListRequest

package/src/serve/doc-events.ts

@@ -1,6 +1,6 @@
 export type DocumentEventOrigin = "watcher" | "save" | "create";
 
-export interface DocumentEvent {
+export interface DocumentChangedEvent {
   type: "document-changed";
   uri: string;
   collection: string;
@@ -9,6 +9,17 @@ export interface DocumentEvent {
   changedAt: string;
 }
 
+export interface CapsuleReverifiedEvent {
+  type: "capsule-reverified";
+  registrationId: string;
+  capsuleId: string;
+  operationStatus: "completed" | "failed";
+  affectedQuestionState: "unaffected" | "affected" | "unknown";
+  changedAt: string;
+}
+
+export type DocumentEvent = DocumentChangedEvent | CapsuleReverifiedEvent;
+
 export interface DocumentEventBusState {
   connectedClients: number;
   retryMs: number;

package/src/serve/resident-runtime.ts

@@ -31,6 +31,7 @@ import {
   isInitialized,
   loadConfig,
 } from "../config";
+import { SavedCapsuleReverificationScheduler } from "../core/capsule-reverification-scheduler";
 import { acquireWriteLock } from "../core/file-lock";
 import { JobManager } from "../core/job-manager";
 import { recordContentMutation } from "../core/mutation-generations";
@@ -94,6 +95,7 @@ export interface ResidentRuntime {
   readonly toolMutex: Mutex;
   readonly readerGate: ReaderGate;
   readonly jobManager: JobManager;
+  readonly capsuleReverificationScheduler: SavedCapsuleReverificationScheduler;
   readonly modelManager: ModelManager;
   readonly mcpContext: ToolContext;
   readonly generations: ResidentGeneration;
@@ -266,6 +268,8 @@ export async function startResidentRuntime(
   ctxHolder.current.scheduler = scheduler;
   ctxHolder.current.eventBus = options.eventBus ?? null;
 
+  let capsuleReverificationScheduler: SavedCapsuleReverificationScheduler | null =
+    null;
   const watchService = (
     deps.watchServiceFactory ??
     ((watchOptions) => new DefaultCollectionWatchService(watchOptions))
@@ -282,6 +286,10 @@ export async function startResidentRuntime(
         });
         options.watchCallbacks?.onSyncComplete?.(event);
       },
+      onSettled: () => {
+        capsuleReverificationScheduler?.notifySyncSettled();
+        options.watchCallbacks?.onSettled?.();
+      },
     },
     syncOptions: withContentTypeRules({}, initialConfig),
   });
@@ -312,6 +320,17 @@ export async function startResidentRuntime(
   const backgroundWork = new ResidentBackgroundWork(
     () => !disposed && admission.accepting
   );
+  capsuleReverificationScheduler = new SavedCapsuleReverificationScheduler({
+    deps: {
+      store,
+      get config() {
+        return ctxHolder.config;
+      },
+      indexName: canonicalizeIndexName(options.index ?? DEFAULT_INDEX_NAME),
+      notify: (event) => options.eventBus?.emit(event),
+    },
+    startBackgroundWork: (operation) => backgroundWork.start(operation),
+  });
 
   const mcpContext = createToolContext({
     store,
@@ -355,6 +374,7 @@ export async function startResidentRuntime(
     toolMutex,
     readerGate,
     jobManager,
+    capsuleReverificationScheduler,
     modelManager,
     mcpContext,
     generations,
@@ -453,6 +473,7 @@ export async function startResidentRuntime(
         syncOptions.triggerEmbed === false
           ? null
           : await scheduler.triggerNow();
+      capsuleReverificationScheduler.notifySyncSettled();
       return { syncResult, embedResult };
     },
     async dispose() {
@@ -466,6 +487,7 @@ export async function startResidentRuntime(
       );
       if (deadlineReached) shutdownState = "deadline";
       await backgroundWork.cancelAndDrain();
+      await capsuleReverificationScheduler.dispose();
       await jobManager.shutdown().catch(() => undefined);
       await Promise.allSettled([
         Promise.resolve().then(() => watchService.dispose()),

package/src/serve/routes/api.ts

@@ -160,6 +160,7 @@ import {
   withRetrievalTraceHeader,
 } from "../retrieval-trace";
 import { buildAppStatus, type StatusBuildDeps } from "../status";
+import { handleChanges, handleDiff, handleImpact } from "./changes";
 
 /** Mutable context holder for hot-reloading presets */
 export interface ContextHolder {
@@ -5122,6 +5123,18 @@ export async function routeApi(
     );
   }
 
+  if (path === "/api/changes" && req.method === "GET") {
+    return handleChanges(store, url);
+  }
+
+  if (path === "/api/diff" && req.method === "GET") {
+    return handleDiff(store, url);
+  }
+
+  if (path === "/api/impact" && req.method === "GET") {
+    return handleImpact(store, url);
+  }
+
   // Unknown API route
   if (path.startsWith("/api/")) {
     return errorResponse("NOT_FOUND", `Unknown API endpoint: ${path}`, 404);

package/src/serve/routes/changes.ts

@@ -0,0 +1,102 @@
+/** Read-only REST handlers for knowledge change, diff, and impact services. */
+
+import type { KnowledgeImpactInput } from "../../core/knowledge-delta";
+import type { StorePort } from "../../store/types";
+
+import {
+  analyzeKnowledgeImpact,
+  getKnowledgeDiff,
+  listKnowledgeChanges,
+} from "../../core/knowledge-delta";
+
+const errorResponse = (
+  code: "VALIDATION" | "RUNTIME",
+  message: string
+): Response =>
+  Response.json(
+    { error: { code, message } },
+    { status: code === "VALIDATION" ? 400 : 500 }
+  );
+
+const parsePositiveInt = (
+  url: URL,
+  name: string
+): number | undefined | Response => {
+  const raw = url.searchParams.get(name);
+  if (raw === null) return;
+  if (!/^\d+$/.test(raw)) {
+    return errorResponse("VALIDATION", `${name} must be a positive integer`);
+  }
+  const value = Number(raw);
+  return Number.isSafeInteger(value) && value > 0
+    ? value
+    : errorResponse("VALIDATION", `${name} must be a positive integer`);
+};
+
+export async function handleChanges(
+  store: StorePort,
+  url: URL
+): Promise<Response> {
+  const limit = parsePositiveInt(url, "limit");
+  if (limit instanceof Response) return limit;
+  const result = await listKnowledgeChanges(store, {
+    since: url.searchParams.get("since") ?? undefined,
+    collection: url.searchParams.get("collection") ?? undefined,
+    limit,
+  });
+  if (!result.success) {
+    return errorResponse(
+      result.isValidation ? "VALIDATION" : "RUNTIME",
+      result.error
+    );
+  }
+  return Response.json(result.data);
+}
+
+export async function handleDiff(
+  store: StorePort,
+  url: URL
+): Promise<Response> {
+  const ref = url.searchParams.get("ref")?.trim();
+  if (!ref) return errorResponse("VALIDATION", "ref is required");
+  const result = await getKnowledgeDiff(
+    store,
+    ref,
+    url.searchParams.get("change") ?? undefined
+  );
+  if (!result.success) {
+    return errorResponse(
+      result.isValidation ? "VALIDATION" : "RUNTIME",
+      result.error
+    );
+  }
+  return Response.json(result.data);
+}
+
+export async function handleImpact(
+  store: StorePort,
+  url: URL
+): Promise<Response> {
+  const ref = url.searchParams.get("ref")?.trim();
+  if (!ref) return errorResponse("VALIDATION", "ref is required");
+  const input: KnowledgeImpactInput = {};
+  for (const [queryName, inputName] of [
+    ["maxDepth", "maxDepth"],
+    ["maxNodes", "maxNodes"],
+    ["maxEdges", "maxEdges"],
+    ["frontierLimit", "frontierLimit"],
+    ["visitedLimit", "visitedLimit"],
+  ] as const) {
+    const value = parsePositiveInt(url, queryName);
+    if (value instanceof Response) return value;
+    if (value !== undefined) input[inputName] = value;
+  }
+  const result = await analyzeKnowledgeImpact(store, ref, input);
+  if (!result.success) {
+    return errorResponse(
+      result.isValidation ? "VALIDATION" : "RUNTIME",
+      result.error
+    );
+  }
+  return Response.json(result.data);
+}

package/src/serve/server.ts

@@ -69,6 +69,7 @@ import {
   handleUpdateDoc,
   handleVerifyConnector,
 } from "./routes/api";
+import { handleChanges, handleDiff, handleImpact } from "./routes/changes";
 import { handleGraph, handleGraphQuery } from "./routes/graph";
 import {
   handleDocBacklinks,
@@ -968,6 +969,39 @@ export async function startServer(
             );
           },
         },
+        "/api/changes": {
+          GET: async (req: Request) => {
+            const url = new URL(req.url);
+            return withSecurityHeaders(
+              await handleResidentRead(runtime as ResidentRuntime, req, () =>
+                handleChanges(store, url)
+              ),
+              isDev
+            );
+          },
+        },
+        "/api/diff": {
+          GET: async (req: Request) => {
+            const url = new URL(req.url);
+            return withSecurityHeaders(
+              await handleResidentRead(runtime as ResidentRuntime, req, () =>
+                handleDiff(store, url)
+              ),
+              isDev
+            );
+          },
+        },
+        "/api/impact": {
+          GET: async (req: Request) => {
+            const url = new URL(req.url);
+            return withSecurityHeaders(
+              await handleResidentRead(runtime as ResidentRuntime, req, () =>
+                handleImpact(store, url)
+              ),
+              isDev
+            );
+          },
+        },
       },
     });
   } catch (e) {

package/src/serve/watch-service.ts

@@ -31,6 +31,8 @@ export interface CollectionWatchCallbacks {
     relPaths: string[];
     error: unknown;
   }) => void;
+  /** Fires after all watcher syncs and queued paths have settled. */
+  onSettled?: () => void;
 }
 
 interface CollectionWatchServiceOptions {
@@ -236,6 +238,13 @@ export class CollectionWatchService {
       const remaining = this.#pendingByCollection.get(collectionName);
       if (remaining && remaining.size > 0) {
         void this.#flushCollection(collectionName);
+      } else if (
+        this.#syncing.size === 0 &&
+        ![...this.#pendingByCollection.values()].some(
+          (relPaths) => relPaths.size > 0
+        )
+      ) {
+        this.#callbacks?.onSettled?.();
       }
     }
   }