@gmickel/gno 1.20.0 → 1.21.0

package/src/core/knowledge-impact.ts

@@ -0,0 +1,202 @@
+/**
+ * Bounded, cycle-safe inbound dependency impact analysis.
+ */
+
+import type { DocEdgeRow, DocumentRow, StorePort } from "../store/types";
+import type {
+  KnowledgeDeltaServiceResult,
+  KnowledgeDocument,
+} from "./knowledge-delta";
+
+import { resolveDocRef } from "./ref-parser";
+
+export interface KnowledgeImpactEvidenceStep {
+  source: Pick<KnowledgeDocument, "id" | "uri">;
+  target: Pick<KnowledgeDocument, "id" | "uri">;
+  edgeType: string;
+  relationType: string;
+  confidence: DocEdgeRow["confidence"];
+  edgeSource: DocEdgeRow["edgeSource"];
+}
+
+export interface KnowledgeImpactResult {
+  schemaVersion: "1.0";
+  root: KnowledgeDocument;
+  impacted: Array<{
+    document: KnowledgeDocument;
+    depth: number;
+    evidencePath: KnowledgeImpactEvidenceStep[];
+  }>;
+  meta: {
+    maxDepth: number;
+    maxNodes: number;
+    maxEdges: number;
+    frontierLimit: number;
+    visitedLimit: number;
+    returnedNodes: number;
+    returnedEdges: number;
+    truncated: boolean;
+    warnings: string[];
+  };
+}
+
+export interface KnowledgeImpactInput {
+  maxDepth?: number;
+  maxNodes?: number;
+  maxEdges?: number;
+  frontierLimit?: number;
+  visitedLimit?: number;
+}
+
+const document = (row: DocumentRow): KnowledgeDocument => ({
+  id: row.docid,
+  uri: row.uri,
+  title: row.title,
+  collection: row.collection,
+  relPath: row.relPath,
+});
+
+const bounded = (
+  name: string,
+  value: number | undefined,
+  fallback: number,
+  maximum: number
+): number | { error: string } => {
+  const resolved = value ?? fallback;
+  return Number.isSafeInteger(resolved) && resolved >= 1 && resolved <= maximum
+    ? resolved
+    : { error: `${name} must be between 1 and ${maximum}` };
+};
+
+const edgeStep = (edge: DocEdgeRow): KnowledgeImpactEvidenceStep => ({
+  source: { id: edge.sourceDocid, uri: edge.sourceUri },
+  target: { id: edge.targetDocid, uri: edge.targetUri },
+  edgeType: edge.edgeType,
+  relationType: edge.relationType,
+  confidence: edge.confidence,
+  edgeSource: edge.edgeSource,
+});
+
+export async function analyzeKnowledgeImpact(
+  store: StorePort,
+  ref: string,
+  input: KnowledgeImpactInput = {}
+): Promise<KnowledgeDeltaServiceResult<KnowledgeImpactResult>> {
+  if (!ref.trim() || ref.length > 4096) {
+    return {
+      success: false,
+      error: "ref must be between 1 and 4096 characters",
+      isValidation: true,
+    };
+  }
+  const caps = {
+    maxDepth: bounded("maxDepth", input.maxDepth, 3, 6),
+    maxNodes: bounded("maxNodes", input.maxNodes, 100, 1000),
+    maxEdges: bounded("maxEdges", input.maxEdges, 250, 5000),
+    frontierLimit: bounded("frontierLimit", input.frontierLimit, 100, 1000),
+    visitedLimit: bounded("visitedLimit", input.visitedLimit, 500, 5000),
+  };
+  const invalid = Object.values(caps).find(
+    (value): value is { error: string } => typeof value === "object"
+  );
+  if (invalid) {
+    return { success: false, error: invalid.error, isValidation: true };
+  }
+  const values = caps as Record<keyof typeof caps, number>;
+  const resolved = await resolveDocRef(store, ref);
+  if ("error" in resolved) {
+    return {
+      success: false,
+      error: resolved.error,
+      isValidation: resolved.isValidation,
+    };
+  }
+  if (!resolved.doc.active) {
+    return {
+      success: false,
+      error: `Document is inactive: ${ref}`,
+      isValidation: true,
+    };
+  }
+  const traversal = await store.queryGraphTraversal(resolved.doc.id, {
+    direction: "in",
+    maxDepth: values.maxDepth,
+    maxNodes: values.maxNodes,
+    frontierLimit: values.frontierLimit,
+    visitedLimit: values.visitedLimit,
+  });
+  if (!traversal.ok) {
+    return { success: false, error: traversal.error.message };
+  }
+  const sortedEdges = [...traversal.value.edges]
+    .sort(
+      (a, b) =>
+        a.depth - b.depth ||
+        a.edge.edgeType.localeCompare(b.edge.edgeType) ||
+        a.edge.sourceUri.localeCompare(b.edge.sourceUri) ||
+        a.edge.targetUri.localeCompare(b.edge.targetUri)
+    )
+    .slice(0, values.maxEdges);
+  const incoming = new Map<string, DocEdgeRow[]>();
+  for (const { edge } of sortedEdges) {
+    const entries = incoming.get(edge.targetDocid) ?? [];
+    entries.push(edge);
+    incoming.set(edge.targetDocid, entries);
+  }
+  const paths = new Map<string, KnowledgeImpactEvidenceStep[]>([
+    [resolved.doc.docid, []],
+  ]);
+  const queue = [resolved.doc.docid];
+  for (let index = 0; index < queue.length; index += 1) {
+    const targetId = queue[index]!;
+    const targetPath = paths.get(targetId) ?? [];
+    for (const edge of incoming.get(targetId) ?? []) {
+      if (paths.has(edge.sourceDocid)) continue;
+      paths.set(edge.sourceDocid, [edgeStep(edge), ...targetPath]);
+      queue.push(edge.sourceDocid);
+    }
+  }
+  const nodesById = new Map(
+    traversal.value.nodes.map(({ doc: row }) => [row.docid, document(row)])
+  );
+  const impacted = [...paths.entries()]
+    .filter(([id]) => id !== resolved.doc.docid)
+    .map(([id, evidencePath]) => ({
+      document: nodesById.get(id)!,
+      depth: evidencePath.length,
+      evidencePath,
+    }))
+    .filter((item) => item.document)
+    .sort(
+      (a, b) =>
+        a.depth - b.depth || a.document.uri.localeCompare(b.document.uri)
+    );
+  const warnings = [...traversal.value.warnings];
+  if (traversal.value.edges.length > values.maxEdges) {
+    warnings.push("maxEdges reached");
+  }
+  const usedEdges = new Set(
+    impacted.flatMap(({ evidencePath }) =>
+      evidencePath.map(
+        (step) =>
+          `${step.source.id}\u0000${step.target.id}\u0000${step.edgeType}`
+      )
+    )
+  );
+  return {
+    success: true,
+    data: {
+      schemaVersion: "1.0",
+      root: document(resolved.doc),
+      impacted,
+      meta: {
+        ...values,
+        returnedNodes: impacted.length + 1,
+        returnedEdges: usedEdges.size,
+        truncated:
+          traversal.value.truncated || warnings.includes("maxEdges reached"),
+        warnings: [...new Set(warnings)],
+      },
+    },
+  };
+}

package/src/ingestion/sync.ts

@@ -40,6 +40,13 @@ import {
   getDefaultPipeline,
 } from "../converters/pipeline";
 import { DEFAULT_LIMITS } from "../converters/types";
+import {
+  diffDocumentStructure,
+  extractDocumentStructure,
+  isRelationMap,
+  normalizeRelationEdgeType,
+  normalizeRelationTarget,
+} from "../core/change-diff";
 import {
   normalizeMarkdownPath,
   normalizeWikiName,
@@ -83,35 +90,6 @@ const NON_RETRYABLE_CONVERSION_ERROR_CODES = new Set([
   "UNSUPPORTED",
 ]);
 
-type RelationMap = Record<string, string[]>;
-
-function isRelationMap(value: unknown): value is RelationMap {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return false;
-  }
-
-  return Object.values(value).every(
-    (targets) =>
-      Array.isArray(targets) &&
-      targets.every((target) => typeof target === "string")
-  );
-}
-
-function normalizeRelationTarget(raw: string): string {
-  const trimmed = raw.trim();
-  if (trimmed.startsWith("[[") && trimmed.endsWith("]]")) {
-    return trimmed.slice(2, -2).split("|")[0]?.trim() ?? "";
-  }
-  return trimmed;
-}
-
-function normalizeRelationEdgeType(raw: string): string {
-  return raw
-    .trim()
-    .toLowerCase()
-    .replace(/[-\s]+/g, "_");
-}
-
 function findDocByWikiRef(
   docs: DocumentRow[],
   targetRef: string,
@@ -747,7 +725,24 @@ export class SyncService {
           // Log but continue - error recording is best-effort
         }
 
-        // Upsert document with error info, explicitly clear mirrorHash
+        const hadRetrievableEvidence = Boolean(existing?.mirrorHash);
+        const structureDelta = hadRetrievableEvidence
+          ? diffDocumentStructure(
+              await this.readPreviousStructure(store, existing),
+              {
+                headings: [],
+                links: [],
+                typedEdges: [],
+                dates: {},
+              }
+            ).delta
+          : undefined;
+
+        // Upsert document with error info, explicitly clear mirrorHash. This
+        // transition is journaled only when retrievable evidence previously
+        // existed; initial/repeated error placeholders are not evidence
+        // creates. Real evidence disappearance stays in the same transaction
+        // so saved Capsule freshness checks cannot miss it.
         const upsertResult = await store.upsertDocument({
           collection: collection.name,
           relPath: entry.relPath,
@@ -761,6 +756,7 @@ export class SyncService {
           lastErrorMessage: convertResult.error.message,
           ingestVersion: INGEST_VERSION,
           contentTypeRulesFingerprint,
+          changeJournal: structureDelta ? { structureDelta } : false,
           // mirrorHash intentionally omitted (will be null)
         });
 
@@ -788,155 +784,186 @@ export class SyncService {
         mime.ext,
         contentTypeRules
       );
-
-      // 7. Upsert document - EXPLICITLY clear error fields on success
-      const docidResult = await store.upsertDocument({
-        collection: collection.name,
-        relPath: entry.relPath,
-        sourceHash,
-        sourceMime: mime.mime,
-        sourceExt: mime.ext,
-        sourceSize,
-        sourceMtime,
-        sourceCtime,
-        title: artifact.title,
-        mirrorHash: artifact.mirrorHash,
-        converterId: artifact.meta.converterId,
-        converterVersion: artifact.meta.converterVersion,
-        languageHint: artifact.languageHint ?? collection.languageHint,
-        contentType: extractedMetadata.contentType,
-        contentTypeSource: extractedMetadata.contentTypeSource,
-        categories: extractedMetadata.categories,
-        author: extractedMetadata.author,
-        frontmatterDate: extractedMetadata.frontmatterDate,
-        dateFields: extractedMetadata.dateFields,
-        contentTypeRulesFingerprint,
-        // Clear error fields on success (requires store to handle undefined → null)
-        lastErrorCode: undefined,
-        lastErrorMessage: undefined,
-        ingestVersion: INGEST_VERSION,
-      });
-
-      const { id: docId, docid } = mustOk(docidResult, "upsertDocument", {
-        collection: collection.name,
-        relPath: entry.relPath,
-      });
-
-      // 8. Upsert content (content-addressed dedupe) - CHECKED
-      const contentResult = await store.upsertContent(
-        artifact.mirrorHash,
-        artifact.markdown
+      const previousStructure = await this.readPreviousStructure(
+        store,
+        existing
       );
-      mustOk(contentResult, "upsertContent", {
-        mirrorHash: artifact.mirrorHash,
-      });
-
-      // 9. Chunk content
-      const chunks = this.chunker.chunk(
+      const nextStructure = extractDocumentStructure(
         artifact.markdown,
-        DEFAULT_CHUNK_PARAMS,
-        artifact.languageHint ?? collection.languageHint,
-        entry.relPath
+        entry.relPath,
+        extractedMetadata.dateFields
       );
+      const structureDelta = diffDocumentStructure(
+        previousStructure,
+        nextStructure
+      ).delta;
+
+      const persistSuccessfulFile = async (): Promise<FileSyncResult> => {
+        // 7. Upsert document - EXPLICITLY clear error fields on success
+        const docidResult = await store.upsertDocument({
+          collection: collection.name,
+          relPath: entry.relPath,
+          sourceHash,
+          sourceMime: mime.mime,
+          sourceExt: mime.ext,
+          sourceSize,
+          sourceMtime,
+          sourceCtime,
+          title: artifact.title,
+          mirrorHash: artifact.mirrorHash,
+          converterId: artifact.meta.converterId,
+          converterVersion: artifact.meta.converterVersion,
+          languageHint: artifact.languageHint ?? collection.languageHint,
+          contentType: extractedMetadata.contentType,
+          contentTypeSource: extractedMetadata.contentTypeSource,
+          categories: extractedMetadata.categories,
+          author: extractedMetadata.author,
+          frontmatterDate: extractedMetadata.frontmatterDate,
+          dateFields: extractedMetadata.dateFields,
+          contentTypeRulesFingerprint,
+          // Clear error fields on success (requires store to handle undefined → null)
+          lastErrorCode: undefined,
+          lastErrorMessage: undefined,
+          ingestVersion: INGEST_VERSION,
+          changeJournal: { structureDelta },
+        });
 
-      // 10. Convert to ChunkInput for store
-      const chunkInputs: ChunkInput[] = chunks.map((c) => ({
-        seq: c.seq,
-        pos: c.pos,
-        text: c.text,
-        startLine: c.startLine,
-        endLine: c.endLine,
-        language: c.language ?? undefined,
-        tokenCount: c.tokenCount ?? undefined,
-      }));
-
-      // 11. Upsert chunks - CHECKED
-      const chunksResult = await store.upsertChunks(
-        artifact.mirrorHash,
-        chunkInputs
-      );
-      mustOk(chunksResult, "upsertChunks", {
-        mirrorHash: artifact.mirrorHash,
-        chunkCount: chunkInputs.length,
-      });
+        const { id: docId, docid } = mustOk(docidResult, "upsertDocument", {
+          collection: collection.name,
+          relPath: entry.relPath,
+        });
 
-      // 12. Rebuild FTS for this hash - CHECKED
-      const ftsResult = await store.rebuildFtsForHash(artifact.mirrorHash);
-      mustOk(ftsResult, "rebuildFtsForHash", {
-        mirrorHash: artifact.mirrorHash,
-      });
+        // 8. Upsert content (content-addressed dedupe) - CHECKED
+        const contentResult = await store.upsertContent(
+          artifact.mirrorHash,
+          artifact.markdown
+        );
+        mustOk(contentResult, "upsertContent", {
+          mirrorHash: artifact.mirrorHash,
+        });
 
-      // 13. Extract and store tags from frontmatter and body hashtags
-      // Always call setDocTags to clear removed tags on re-sync
-      const extractedTags = extractTags(artifact.markdown);
-      const tagsResult = await store.setDocTags(
-        docId,
-        extractedTags,
-        "frontmatter"
-      );
-      mustOk(tagsResult, "setDocTags", {
-        docId,
-        tagCount: extractedTags.length,
-      });
+        // 9. Chunk content
+        const chunks = this.chunker.chunk(
+          artifact.markdown,
+          DEFAULT_CHUNK_PARAMS,
+          artifact.languageHint ?? collection.languageHint,
+          entry.relPath
+        );
 
-      // 14. Extract and store links (wiki and markdown links)
-      const excludedRanges = getExcludedRanges(artifact.markdown);
-      const lineOffsets = buildLineOffsets(artifact.markdown);
-      const parsedLinks = parseLinks(
-        artifact.markdown,
-        lineOffsets,
-        excludedRanges
-      );
+        // 10. Convert to ChunkInput for store
+        const chunkInputs: ChunkInput[] = chunks.map((c) => ({
+          seq: c.seq,
+          pos: c.pos,
+          text: c.text,
+          startLine: c.startLine,
+          endLine: c.endLine,
+          language: c.language ?? undefined,
+          tokenCount: c.tokenCount ?? undefined,
+        }));
+
+        // 11. Upsert chunks - CHECKED
+        const chunksResult = await store.upsertChunks(
+          artifact.mirrorHash,
+          chunkInputs
+        );
+        mustOk(chunksResult, "upsertChunks", {
+          mirrorHash: artifact.mirrorHash,
+          chunkCount: chunkInputs.length,
+        });
 
-      const linkInputs: DocLinkInput[] = [];
-      for (const link of parsedLinks) {
-        // Compute target_ref_norm based on link type
-        let targetRefNorm: string;
-        if (link.kind === "wiki") {
-          targetRefNorm = normalizeWikiName(link.targetRef);
-        } else {
-          // Markdown links with collection prefix are not supported
-          // (use wiki links for cross-collection references)
-          if (link.targetCollection) {
-            continue;
-          }
-          const resolved = normalizeMarkdownPath(link.targetRef, entry.relPath);
-          if (!resolved) {
-            // Link escapes collection root - skip silently
-            continue;
+        // 12. Rebuild FTS for this hash - CHECKED
+        const ftsResult = await store.rebuildFtsForHash(artifact.mirrorHash);
+        mustOk(ftsResult, "rebuildFtsForHash", {
+          mirrorHash: artifact.mirrorHash,
+        });
+
+        // 13. Extract and store tags from frontmatter and body hashtags
+        // Always call setDocTags to clear removed tags on re-sync
+        const extractedTags = extractTags(artifact.markdown);
+        const tagsResult = await store.setDocTags(
+          docId,
+          extractedTags,
+          "frontmatter"
+        );
+        mustOk(tagsResult, "setDocTags", {
+          docId,
+          tagCount: extractedTags.length,
+        });
+
+        // 14. Extract and store links (wiki and markdown links)
+        const excludedRanges = getExcludedRanges(artifact.markdown);
+        const lineOffsets = buildLineOffsets(artifact.markdown);
+        const parsedLinks = parseLinks(
+          artifact.markdown,
+          lineOffsets,
+          excludedRanges
+        );
+
+        const linkInputs: DocLinkInput[] = [];
+        for (const link of parsedLinks) {
+          // Compute target_ref_norm based on link type
+          let targetRefNorm: string;
+          if (link.kind === "wiki") {
+            targetRefNorm = normalizeWikiName(link.targetRef);
+          } else {
+            // Markdown links with collection prefix are not supported
+            // (use wiki links for cross-collection references)
+            if (link.targetCollection) {
+              continue;
+            }
+            const resolved = normalizeMarkdownPath(
+              link.targetRef,
+              entry.relPath
+            );
+            if (!resolved) {
+              // Link escapes collection root - skip silently
+              continue;
+            }
+            targetRefNorm = resolved;
           }
-          targetRefNorm = resolved;
+
+          linkInputs.push({
+            targetRef: link.targetRef,
+            targetRefNorm,
+            targetAnchor: link.targetAnchor,
+            targetCollection: link.targetCollection,
+            linkType: link.kind,
+            linkText: link.displayText,
+            startLine: link.startLine,
+            startCol: link.startCol,
+            endLine: link.endLine,
+            endCol: link.endCol,
+          });
         }
 
-        linkInputs.push({
-          targetRef: link.targetRef,
-          targetRefNorm,
-          targetAnchor: link.targetAnchor,
-          targetCollection: link.targetCollection,
-          linkType: link.kind,
-          linkText: link.displayText,
-          startLine: link.startLine,
-          startCol: link.startCol,
-          endLine: link.endLine,
-          endCol: link.endCol,
+        const linksResult = await store.setDocLinks(
+          docId,
+          linkInputs,
+          "parsed"
+        );
+        mustOk(linksResult, "setDocLinks", {
+          docId,
+          linkCount: linkInputs.length,
         });
-      }
 
-      const linksResult = await store.setDocLinks(docId, linkInputs, "parsed");
-      mustOk(linksResult, "setDocLinks", {
-        docId,
-        linkCount: linkInputs.length,
-      });
-
-      const status = existing ? "updated" : "added";
-      return {
-        relPath: entry.relPath,
-        status,
-        docid,
-        mirrorHash: artifact.mirrorHash,
-        contentType: extractedMetadata.contentType,
-        contentTypeSource: extractedMetadata.contentTypeSource,
+        const status = existing ? "updated" : "added";
+        return {
+          relPath: entry.relPath,
+          status,
+          docid,
+          mirrorHash: artifact.mirrorHash,
+          contentType: extractedMetadata.contentType,
+          contentTypeSource: extractedMetadata.contentTypeSource,
+        };
       };
+      if (!store.withTransaction) {
+        return await persistSuccessfulFile();
+      }
+      const persisted = await store.withTransaction(persistSuccessfulFile);
+      return mustOk(persisted, "persistSuccessfulFile", {
+        collection: collection.name,
+        relPath: entry.relPath,
+      });
     } catch (error) {
       const message = error instanceof Error ? error.message : "Unknown error";
       // Distinguish store errors from other internal errors
@@ -977,6 +1004,7 @@ export class SyncService {
               existingResult.value.sourceMtime,
             lastErrorCode: code,
             lastErrorMessage: message,
+            changeJournal: false,
           });
         }
       } catch {
@@ -992,6 +1020,27 @@ export class SyncService {
     }
   }
 
+  private async readPreviousStructure(
+    store: StorePort,
+    existing: DocumentRow | null
+  ): Promise<ReturnType<typeof extractDocumentStructure> | null | undefined> {
+    if (!existing) return null;
+    if (!existing.mirrorHash) return undefined;
+
+    const content = await store.getContent(existing.mirrorHash);
+    if (!content.ok) {
+      throw new Error(`Store operation failed: ${content.error.message}`, {
+        cause: content.error,
+      });
+    }
+    if (content.value === null) return undefined;
+    return extractDocumentStructure(
+      content.value,
+      existing.relPath,
+      existing.dateFields
+    );
+  }
+
   /**
    * Sync a specific set of files within a collection.
    */