@gmickel/gno 1.30.7 → 1.32.0

package/src/serve/server.ts

@@ -93,6 +93,10 @@ import {
   handleDocSimilar,
 } from "./routes/links";
 import { createMcpHttpGateway } from "./routes/mcp";
+import {
+  handleCreateSectionTarget,
+  handleResolveSectionTarget,
+} from "./routes/section-targets";
 import {
   handleTraceDelete,
   handleTraceExport,
@@ -1172,6 +1176,36 @@ export async function startServer(
             );
           },
         },
+        "/api/doc/:id/section-targets": {
+          POST: async (req: Request) => {
+            if (!isRequestAllowed(req, port)) {
+              return withSecurityHeaders(forbiddenResponse(), isDev);
+            }
+            const parts = new URL(req.url).pathname.split("/");
+            const id = decodeURIComponent(parts[3] || "");
+            return withSecurityHeaders(
+              await handleResidentRead(runtime as ResidentRuntime, req, () =>
+                handleCreateSectionTarget(store, id, req)
+              ),
+              isDev
+            );
+          },
+        },
+        "/api/doc/:id/section-targets/resolve": {
+          POST: async (req: Request) => {
+            if (!isRequestAllowed(req, port)) {
+              return withSecurityHeaders(forbiddenResponse(), isDev);
+            }
+            const parts = new URL(req.url).pathname.split("/");
+            const id = decodeURIComponent(parts[3] || "");
+            return withSecurityHeaders(
+              await handleResidentRead(runtime as ResidentRuntime, req, () =>
+                handleResolveSectionTarget(store, id, req)
+              ),
+              isDev
+            );
+          },
+        },
         "/api/doc/:id/backlinks": {
           GET: async (req: Request) => {
             const url = new URL(req.url);

package/src/store/migrations/026-file-refactor-recovery-journal.ts

@@ -0,0 +1,72 @@
+/**
+ * Migration: bounded, metadata-only file-refactor recovery journal.
+ *
+ * Stores IDs, plan digests, collection/relpaths, phase/state, timestamps,
+ * and fingerprints/status only. Never stores note bodies or replacements.
+ * Create prunes oldest terminal receipts under FILE_REFACTOR_JOURNAL_MAX_RECEIPTS.
+ *
+ * @module src/store/migrations/026-file-refactor-recovery-journal
+ */
+
+import type { Database } from "bun:sqlite";
+
+import type { Migration } from "./runner";
+
+export const migration: Migration = {
+  version: 26,
+  name: "file_refactor_recovery_journal",
+
+  up(db: Database): void {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS file_refactor_recovery_journal (
+        journal_id TEXT PRIMARY KEY,
+        plan_digest TEXT NOT NULL,
+        collection TEXT NOT NULL,
+        operation TEXT NOT NULL
+          CHECK (operation IN ('rename', 'move')),
+        source_rel_path TEXT NOT NULL,
+        target_rel_path TEXT NOT NULL,
+        phase TEXT NOT NULL
+          CHECK (phase IN (
+            'prepared', 'staging', 'committing', 'committed', 'sync_pending',
+            'converged', 'rolling_back', 'rolled_back', 'recovery_required',
+            'aborted'
+          )),
+        phase_ordinal INTEGER NOT NULL CHECK (phase_ordinal >= 0),
+        filesystem_state TEXT NOT NULL
+          CHECK (filesystem_state IN (
+            'unchanged', 'committed', 'rolled_back', 'recovery_required'
+          )),
+        index_state TEXT NOT NULL
+          CHECK (index_state IN (
+            'not_attempted', 'pending', 'converged', 'skipped'
+          )),
+        file_entries_json TEXT NOT NULL
+          CHECK (length(CAST(file_entries_json AS BLOB)) <= 65536),
+        created_at_ms INTEGER NOT NULL CHECK (created_at_ms >= 0),
+        updated_at_ms INTEGER NOT NULL CHECK (updated_at_ms >= 0),
+        CHECK (length(CAST(journal_id AS BLOB)) BETWEEN 1 AND 128),
+        CHECK (
+          length(plan_digest) = 64
+          AND plan_digest NOT GLOB '*[^0-9a-f]*'
+        ),
+        CHECK (length(CAST(collection AS BLOB)) BETWEEN 1 AND 256),
+        CHECK (length(CAST(source_rel_path AS BLOB)) BETWEEN 1 AND 4096),
+        CHECK (length(CAST(target_rel_path AS BLOB)) BETWEEN 1 AND 4096),
+        CHECK (updated_at_ms >= created_at_ms)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_file_refactor_journal_plan_digest
+        ON file_refactor_recovery_journal(plan_digest, updated_at_ms DESC, journal_id DESC);
+
+      CREATE INDEX IF NOT EXISTS idx_file_refactor_journal_collection
+        ON file_refactor_recovery_journal(collection, updated_at_ms DESC);
+    `);
+  },
+
+  down(db: Database): void {
+    db.exec("DROP INDEX IF EXISTS idx_file_refactor_journal_collection");
+    db.exec("DROP INDEX IF EXISTS idx_file_refactor_journal_plan_digest");
+    db.exec("DROP TABLE IF EXISTS file_refactor_recovery_journal");
+  },
+};

package/src/store/migrations/index.ts

@@ -39,6 +39,7 @@ import { migration as m022 } from "./022-record-export-lineage";
 import { migration as m023 } from "./023-collection-egress-policy";
 import { migration as m024 } from "./024-egress-derived-lineage";
 import { migration as m025 } from "./025-collection-egress-policy-revision";
+import { migration as m026 } from "./026-file-refactor-recovery-journal";
 
 /** All migrations in order */
 export const migrations = [
@@ -67,4 +68,5 @@ export const migrations = [
   m023,
   m024,
   m025,
+  m026,
 ];

package/src/store/sqlite/adapter.ts

@@ -16,6 +16,11 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { basename } from "node:path";
 
 import type { EgressLineage } from "../../core/egress-provenance";
+import type {
+  FileRefactorJournalAdvance,
+  FileRefactorRecoveryReceipt,
+  FileRefactorRecoveryReceiptDraft,
+} from "../../core/file-refactor-journal";
 import type {
   ActivationIndexDocument,
   ActivationIndexIdentity,
@@ -55,6 +60,8 @@ import type {
   EgressAuditStatusResult,
   FtsResult,
   FtsSearchOptions,
+  FileRefactorResolutionReferrerDocument,
+  FileRefactorResolutionSnapshot,
   GetGraphNeighborsOptions,
   GetGraphOptions,
   GraphEdgeConfidence,
@@ -112,6 +119,10 @@ import {
   type FtsTokenizer,
   resolveConfiguredEgressPolicy,
 } from "../../config/types";
+import {
+  getDocumentCapabilities,
+  isTextLikeReferenceDocument,
+} from "../../core/document-capabilities";
 import { analyzeGraphCommunities } from "../../core/graph-analysis";
 import {
   classifyResolvedGraphEdge,
@@ -122,6 +133,7 @@ import {
   buildWikiBestRankMatchCountSubquery,
   buildWikiBestRankSubquery,
 } from "../../core/graph-resolver";
+import { buildContentPrefilterNeedles } from "../../core/link-relevance";
 import { normalizeWikiName, stripWikiMdExt } from "../../core/links";
 import {
   parseActivationReceipt,
@@ -160,6 +172,12 @@ import {
   listEgressAuditReceipts as listStoredEgressAuditReceipts,
   purgeEgressAuditReceipts as purgeStoredEgressAuditReceipts,
 } from "./egress-audit-store";
+import {
+  advanceFileRefactorReceipt as advanceStoredFileRefactorReceipt,
+  createFileRefactorPreparedReceipt as createStoredFileRefactorPreparedReceipt,
+  getFileRefactorReceiptById as getStoredFileRefactorReceiptById,
+  getLatestFileRefactorReceiptByPlanDigest as getStoredLatestFileRefactorReceiptByPlanDigest,
+} from "./file-refactor-journal-store";
 import { loadFts5Snowball } from "./fts5-snowball";
 import { queryGraphNeighborsForSeeds } from "./graph-neighbors";
 import {
@@ -1960,6 +1978,38 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
     return purgeStoredDocumentChanges(this.ensureOpen());
   }
 
+  async createFileRefactorPreparedReceipt(
+    draft: FileRefactorRecoveryReceiptDraft
+  ): Promise<StoreResult<FileRefactorRecoveryReceipt>> {
+    return createStoredFileRefactorPreparedReceipt(this.ensureOpen(), draft);
+  }
+
+  async advanceFileRefactorReceipt(
+    journalId: string,
+    update: FileRefactorJournalAdvance
+  ): Promise<StoreResult<FileRefactorRecoveryReceipt>> {
+    return advanceStoredFileRefactorReceipt(
+      this.ensureOpen(),
+      journalId,
+      update
+    );
+  }
+
+  async getFileRefactorReceiptById(
+    journalId: string
+  ): Promise<StoreResult<FileRefactorRecoveryReceipt | null>> {
+    return getStoredFileRefactorReceiptById(this.ensureOpen(), journalId);
+  }
+
+  async getLatestFileRefactorReceiptByPlanDigest(
+    planDigest: string
+  ): Promise<StoreResult<FileRefactorRecoveryReceipt | null>> {
+    return getStoredLatestFileRefactorReceiptByPlanDigest(
+      this.ensureOpen(),
+      planDigest
+    );
+  }
+
   async upsertSavedCapsuleRegistration(
     input: SavedCapsuleRegistrationInput
   ): Promise<StoreResult<SavedCapsuleRegistrationRecord>> {
@@ -3371,6 +3421,408 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
     }
   }
 
+  /**
+   * Bounded read seam for reference-safe rename/move planning.
+   * Loads catalog metadata plus content for indexed backlinks unioned with a
+   * conservative SQL content prefilter (opaque embeds/HTML/code/malformed may
+   * not appear in doc_links). Missing mirror content fails closed.
+   */
+  async getFileRefactorResolutionSnapshot(input: {
+    sourceUri: string;
+    maxCatalogDocuments?: number;
+    maxReferrerDocuments?: number;
+    maxContentCharsPerDocument?: number;
+    maxTotalContentChars?: number;
+  }): Promise<StoreResult<FileRefactorResolutionSnapshot>> {
+    try {
+      const db = this.ensureOpen();
+      const maxCatalog = Math.max(
+        1,
+        Math.floor(input.maxCatalogDocuments ?? 5_000)
+      );
+      const maxReferrers = Math.max(
+        1,
+        Math.floor(input.maxReferrerDocuments ?? 5_000)
+      );
+      const maxChars = Math.max(
+        1,
+        Math.floor(input.maxContentCharsPerDocument ?? 1_000_000)
+      );
+      const maxTotalChars = Math.max(
+        maxChars,
+        Math.floor(input.maxTotalContentChars ?? 20_000_000)
+      );
+      const truncationReasons: string[] = [];
+
+      const sourceRow = db
+        .query<
+          {
+            id: number;
+            uri: string;
+            rel_path: string;
+            collection: string;
+            title: string | null;
+            mirror_hash: string | null;
+            source_ext: string;
+            source_mime: string;
+            record_key: string | null;
+          },
+          [string]
+        >(
+          `SELECT id, uri, rel_path, collection, title, mirror_hash,
+                  source_ext, source_mime, record_key
+           FROM documents
+           WHERE uri = ? AND active = 1`
+        )
+        .get(input.sourceUri);
+
+      if (!sourceRow) {
+        return err("NOT_FOUND", `Document not found: ${input.sourceUri}`);
+      }
+
+      const sourceCaps = getDocumentCapabilities({
+        sourceExt: sourceRow.source_ext,
+        sourceMime: sourceRow.source_mime,
+        contentAvailable: Boolean(sourceRow.mirror_hash),
+        recordKey: sourceRow.record_key,
+      });
+
+      let sourceContent: string | null = null;
+      let sourceContentTruncated = false;
+      if (sourceRow.mirror_hash) {
+        const contentRow = db
+          .query<{ markdown: string }, [number, string]>(
+            `SELECT substr(markdown, 1, ?) AS markdown
+             FROM content WHERE mirror_hash = ?`
+          )
+          .get(maxChars + 1, sourceRow.mirror_hash);
+        if (contentRow) {
+          sourceContentTruncated = contentRow.markdown.length > maxChars;
+          sourceContent = sourceContentTruncated
+            ? contentRow.markdown.slice(0, maxChars)
+            : contentRow.markdown;
+          if (sourceContentTruncated) {
+            truncationReasons.push("source_content_truncated");
+          }
+        } else {
+          truncationReasons.push("source_content_missing");
+        }
+      } else {
+        // Null mirror_hash means source bytes are unavailable — fail closed.
+        truncationReasons.push("source_content_missing");
+      }
+
+      const catalogRows = db
+        .query<
+          {
+            id: number;
+            uri: string;
+            rel_path: string;
+            collection: string;
+            title: string | null;
+          },
+          [string, number]
+        >(
+          `SELECT id, uri, rel_path, collection, title
+           FROM documents
+           WHERE active = 1 AND collection = ?
+           ORDER BY id
+           LIMIT ?`
+        )
+        .all(sourceRow.collection, maxCatalog + 1);
+
+      if (catalogRows.length > maxCatalog) {
+        truncationReasons.push("catalog_truncated");
+      }
+      const catalog = catalogRows.slice(0, maxCatalog).map((row) => ({
+        id: row.id,
+        uri: row.uri,
+        relPath: row.rel_path,
+        collection: row.collection,
+        title: row.title,
+      }));
+
+      const occupiedRelPaths = catalog.map((doc) => doc.relPath);
+
+      const backlinksResult = await this.getBacklinksForDoc(sourceRow.id, {
+        collection: sourceRow.collection,
+      });
+      if (!backlinksResult.ok) {
+        return backlinksResult;
+      }
+
+      const candidateIds = new Set<number>();
+      for (const row of backlinksResult.value) {
+        if (row.sourceDocId !== sourceRow.id) {
+          candidateIds.add(row.sourceDocId);
+        }
+      }
+
+      const needles = buildContentPrefilterNeedles({
+        relPath: sourceRow.rel_path,
+        title: sourceRow.title,
+      });
+      const escapeLike = (value: string): string =>
+        value
+          .replaceAll("\\", "\\\\")
+          .replaceAll("%", "\\%")
+          .replaceAll("_", "\\_");
+
+      if (needles.length > 0) {
+        const likeClauses = needles
+          .map(() => `c.markdown LIKE '%' || ? || '%' ESCAPE '\\'`)
+          .join(" OR ");
+        const prefilterRows = db
+          .query<{ id: number }, (string | number)[]>(
+            `SELECT DISTINCT d.id AS id
+             FROM documents d
+             INNER JOIN content c ON c.mirror_hash = d.mirror_hash
+             WHERE d.active = 1
+               AND d.collection = ?
+               AND d.id != ?
+               AND (${likeClauses})
+             ORDER BY d.id
+             LIMIT ?`
+          )
+          .all(
+            sourceRow.collection,
+            sourceRow.id,
+            ...needles.map(escapeLike),
+            maxReferrers + 1
+          );
+        if (prefilterRows.length > maxReferrers) {
+          truncationReasons.push("content_prefilter_truncated");
+        }
+        for (const row of prefilterRows.slice(0, maxReferrers + 1)) {
+          candidateIds.add(row.id);
+        }
+      }
+
+      // Completeness: union same-collection docs whose mirror content cannot be
+      // loaded. Text-like docs (including read-only logical .md records) fail
+      // closed; non-text binaries are omitted (they cannot hold markdown/wiki/
+      // HTML refs). Preserve referrer caps via LIMIT + sorted slice below.
+      const missingMirrorRows = db
+        .query<
+          {
+            id: number;
+            source_ext: string;
+            source_mime: string;
+          },
+          [string, number, number]
+        >(
+          `SELECT d.id AS id,
+                  d.source_ext AS source_ext,
+                  d.source_mime AS source_mime
+           FROM documents d
+           WHERE d.active = 1
+             AND d.collection = ?
+             AND d.id != ?
+             AND (
+               d.mirror_hash IS NULL
+               OR NOT EXISTS (
+                 SELECT 1 FROM content c WHERE c.mirror_hash = d.mirror_hash
+               )
+             )
+           ORDER BY d.id
+           LIMIT ?`
+        )
+        .all(sourceRow.collection, sourceRow.id, maxReferrers + 1);
+      if (missingMirrorRows.length > maxReferrers) {
+        truncationReasons.push("missing_mirror_scan_truncated");
+      }
+      for (const row of missingMirrorRows) {
+        if (!isTextLikeReferenceDocument(row.source_ext, row.source_mime)) {
+          continue;
+        }
+        candidateIds.add(row.id);
+      }
+
+      const sortedCandidateIds = [...candidateIds].sort((a, b) => a - b);
+      if (sortedCandidateIds.length > maxReferrers) {
+        truncationReasons.push("referrers_truncated");
+      }
+
+      const referrers: FileRefactorResolutionReferrerDocument[] = [];
+      let totalContentChars = sourceContent?.length ?? 0;
+
+      for (const referrerId of sortedCandidateIds.slice(0, maxReferrers)) {
+        const referrerRow = db
+          .query<
+            {
+              id: number;
+              uri: string;
+              rel_path: string;
+              collection: string;
+              title: string | null;
+              mirror_hash: string | null;
+              source_ext: string;
+              source_mime: string;
+              record_key: string | null;
+            },
+            [number]
+          >(
+            `SELECT id, uri, rel_path, collection, title, mirror_hash,
+                    source_ext, source_mime, record_key
+             FROM documents
+             WHERE id = ? AND active = 1`
+          )
+          .get(referrerId);
+        if (!referrerRow) continue;
+
+        const caps = getDocumentCapabilities({
+          sourceExt: referrerRow.source_ext,
+          sourceMime: referrerRow.source_mime,
+          contentAvailable: Boolean(referrerRow.mirror_hash),
+          recordKey: referrerRow.record_key,
+        });
+
+        if (!referrerRow.mirror_hash) {
+          truncationReasons.push("referrer_content_missing");
+          referrers.push({
+            id: referrerRow.id,
+            uri: referrerRow.uri,
+            relPath: referrerRow.rel_path,
+            collection: referrerRow.collection,
+            title: referrerRow.title,
+            content: null,
+            contentTruncated: false,
+            contentMissing: true,
+            editable: caps.editable,
+            editableReason: caps.editable
+              ? undefined
+              : caps.reason
+                ? "read_only_document"
+                : "capability_denied",
+            sourceExt: referrerRow.source_ext,
+            sourceMime: referrerRow.source_mime,
+            recordKey: referrerRow.record_key,
+          });
+          continue;
+        }
+
+        const contentRow = db
+          .query<{ markdown: string }, [number, string]>(
+            `SELECT substr(markdown, 1, ?) AS markdown
+             FROM content WHERE mirror_hash = ?`
+          )
+          .get(maxChars + 1, referrerRow.mirror_hash);
+
+        if (!contentRow) {
+          truncationReasons.push("referrer_content_missing");
+          referrers.push({
+            id: referrerRow.id,
+            uri: referrerRow.uri,
+            relPath: referrerRow.rel_path,
+            collection: referrerRow.collection,
+            title: referrerRow.title,
+            content: null,
+            contentTruncated: false,
+            contentMissing: true,
+            editable: caps.editable,
+            editableReason: caps.editable
+              ? undefined
+              : caps.reason
+                ? "read_only_document"
+                : "capability_denied",
+            sourceExt: referrerRow.source_ext,
+            sourceMime: referrerRow.source_mime,
+            recordKey: referrerRow.record_key,
+          });
+          continue;
+        }
+
+        const contentTruncated = contentRow.markdown.length > maxChars;
+        if (contentTruncated) {
+          truncationReasons.push("referrer_content_truncated");
+        }
+        const content = contentTruncated
+          ? contentRow.markdown.slice(0, maxChars)
+          : contentRow.markdown;
+        totalContentChars += content.length;
+        if (totalContentChars > maxTotalChars) {
+          truncationReasons.push("total_content_truncated");
+          referrers.push({
+            id: referrerRow.id,
+            uri: referrerRow.uri,
+            relPath: referrerRow.rel_path,
+            collection: referrerRow.collection,
+            title: referrerRow.title,
+            content: null,
+            contentTruncated: false,
+            contentMissing: true,
+            editable: caps.editable,
+            editableReason: caps.editable
+              ? undefined
+              : caps.reason
+                ? "read_only_document"
+                : "capability_denied",
+            sourceExt: referrerRow.source_ext,
+            sourceMime: referrerRow.source_mime,
+            recordKey: referrerRow.record_key,
+          });
+          continue;
+        }
+
+        referrers.push({
+          id: referrerRow.id,
+          uri: referrerRow.uri,
+          relPath: referrerRow.rel_path,
+          collection: referrerRow.collection,
+          title: referrerRow.title,
+          content,
+          contentTruncated,
+          contentMissing: false,
+          editable: caps.editable,
+          editableReason: caps.editable
+            ? undefined
+            : caps.reason
+              ? "read_only_document"
+              : "capability_denied",
+          sourceExt: referrerRow.source_ext,
+          sourceMime: referrerRow.source_mime,
+          recordKey: referrerRow.record_key,
+        });
+      }
+
+      const snapshot: FileRefactorResolutionSnapshot = {
+        source: {
+          id: sourceRow.id,
+          uri: sourceRow.uri,
+          relPath: sourceRow.rel_path,
+          collection: sourceRow.collection,
+          title: sourceRow.title,
+          mirrorHash: sourceRow.mirror_hash,
+          sourceExt: sourceRow.source_ext,
+          sourceMime: sourceRow.source_mime,
+          recordKey: sourceRow.record_key,
+          content: sourceContent,
+          contentTruncated: sourceContentTruncated,
+          editable: sourceCaps.editable,
+          editableReason: sourceCaps.editable
+            ? undefined
+            : sourceCaps.reason
+              ? "read_only_document"
+              : "capability_denied",
+        },
+        catalog,
+        referrers,
+        occupiedRelPaths,
+        truncated: truncationReasons.length > 0,
+        truncationReasons: [...new Set(truncationReasons)].sort(),
+      };
+      return ok(snapshot);
+    } catch (cause) {
+      return err(
+        "QUERY_FAILED",
+        cause instanceof Error
+          ? cause.message
+          : "Failed to load file refactor resolution snapshot",
+        cause
+      );
+    }
+  }
+
   /**
    * Set semantic edges for a document.
    * Replaces edges from the given source.