@gmickel/gno 1.30.7 → 1.32.0

package/src/core/file-refactor-from-snapshot.ts

@@ -0,0 +1,148 @@
+/**
+ * Safe adapter from store resolution snapshot → planner input.
+ * Preserves truncation reasons so callers cannot drop them.
+ *
+ * @module src/core/file-refactor-from-snapshot
+ */
+
+import type { FileRefactorOperation } from "./file-refactor-contract";
+import type {
+  FileRefactorPlannerDocument,
+  PlanFileRefactorImpactInput,
+} from "./file-refactor-planner-types";
+
+import { planFileRefactorImpact } from "./file-refactor-planner";
+
+/** Store-seam snapshot shape (structurally matches FileRefactorResolutionSnapshot). */
+export interface FileRefactorSnapshotLike {
+  source: {
+    id: number;
+    uri: string;
+    relPath: string;
+    collection: string;
+    title: string | null;
+    content: string | null;
+    contentTruncated: boolean;
+    editable: boolean;
+    editableReason?: string;
+  };
+  catalog: Array<{
+    id: number;
+    uri: string;
+    relPath: string;
+    collection: string;
+    title: string | null;
+  }>;
+  referrers: Array<{
+    id: number;
+    uri: string;
+    relPath: string;
+    collection: string;
+    title: string | null;
+    content: string | null;
+    contentTruncated: boolean;
+    contentMissing: boolean;
+    editable: boolean;
+    editableReason?: string;
+  }>;
+  truncated: boolean;
+  truncationReasons: string[];
+}
+
+export function planInputFromResolutionSnapshot(input: {
+  operation: FileRefactorOperation;
+  snapshot: FileRefactorSnapshotLike;
+  target: {
+    uri: string;
+    relPath: string;
+    collection: string;
+    title?: string | null;
+  };
+  targetOccupied: boolean;
+  sourceEditable?: boolean;
+}): PlanFileRefactorImpactInput {
+  const { snapshot } = input;
+  const truncationReasons = [...snapshot.truncationReasons];
+  if (snapshot.truncated && truncationReasons.length === 0) {
+    truncationReasons.push("snapshot_truncated");
+  }
+  // Defensive: legacy/custom snapshots may omit the reason while content is null.
+  if (snapshot.source.content === null) {
+    truncationReasons.push("source_content_missing");
+  }
+  if (snapshot.source.contentTruncated) {
+    truncationReasons.push("source_content_truncated");
+  }
+
+  const documents: FileRefactorPlannerDocument[] = snapshot.catalog.map(
+    (doc) => ({
+      id: doc.id,
+      uri: doc.uri,
+      relPath: doc.relPath,
+      collection: doc.collection,
+      title: doc.title,
+      active: true,
+    })
+  );
+
+  const byUri = new Map(documents.map((doc) => [doc.uri, doc]));
+  for (const referrer of snapshot.referrers) {
+    let doc = byUri.get(referrer.uri);
+    if (!doc) {
+      doc = {
+        id: referrer.id,
+        uri: referrer.uri,
+        relPath: referrer.relPath,
+        collection: referrer.collection,
+        title: referrer.title,
+        active: true,
+      };
+      documents.push(doc);
+      byUri.set(doc.uri, doc);
+    }
+    doc.editable = referrer.editable;
+    doc.editableReason = referrer.editableReason;
+    if (referrer.contentMissing) {
+      doc.contentMissing = true;
+      doc.content = null;
+      truncationReasons.push("referrer_content_missing");
+    } else {
+      doc.content = referrer.content ?? null;
+      if (referrer.contentTruncated) {
+        truncationReasons.push("referrer_content_truncated");
+      }
+    }
+  }
+
+  return {
+    operation: input.operation,
+    source: {
+      uri: snapshot.source.uri,
+      relPath: snapshot.source.relPath,
+      collection: snapshot.source.collection,
+      title: snapshot.source.title,
+      content: snapshot.source.content ?? "",
+      editable: input.sourceEditable ?? snapshot.source.editable,
+    },
+    target: input.target,
+    documents,
+    targetOccupied: input.targetOccupied,
+    truncationReasons: [...new Set(truncationReasons)].sort(),
+  };
+}
+
+/** Plan impact directly from a store snapshot without dropping truncation. */
+export async function planFileRefactorImpactFromSnapshot(input: {
+  operation: FileRefactorOperation;
+  snapshot: FileRefactorSnapshotLike;
+  target: {
+    uri: string;
+    relPath: string;
+    collection: string;
+    title?: string | null;
+  };
+  targetOccupied: boolean;
+  sourceEditable?: boolean;
+}) {
+  return planFileRefactorImpact(planInputFromResolutionSnapshot(input));
+}

package/src/core/file-refactor-journal-port.ts

@@ -0,0 +1,150 @@
+/**
+ * Journal ports and helpers for reference-safe refactor apply.
+ *
+ * @module src/core/file-refactor-journal-port
+ */
+
+import type {
+  FileRefactorJournalPort,
+  FileRefactorRecoveryReceipt,
+} from "./file-refactor-journal";
+
+import {
+  assertAllowedJournalPhaseTransition,
+  FILE_REFACTOR_JOURNAL_MAX_RECEIPTS,
+  FILE_REFACTOR_JOURNAL_PHASE_ORDINAL,
+  isPrunableJournalPhase,
+} from "./file-refactor-journal";
+
+function pruneOldestTerminalReceipts(
+  byId: Map<string, FileRefactorRecoveryReceipt>
+): void {
+  while (byId.size >= FILE_REFACTOR_JOURNAL_MAX_RECEIPTS) {
+    const prunable = [...byId.values()]
+      .filter((row) => isPrunableJournalPhase(row.phase))
+      .sort((left, right) => {
+        if (left.updatedAtMs !== right.updatedAtMs) {
+          return left.updatedAtMs - right.updatedAtMs;
+        }
+        return left.journalId < right.journalId
+          ? -1
+          : left.journalId > right.journalId
+            ? 1
+            : 0;
+      });
+    const victim = prunable[0];
+    if (!victim) {
+      throw new Error(
+        "File refactor journal at capacity with no prunable terminal receipts"
+      );
+    }
+    byId.delete(victim.journalId);
+  }
+}
+
+/** In-memory journal port for focused unit tests. */
+export function createMemoryFileRefactorJournal(): FileRefactorJournalPort {
+  const byId = new Map<string, FileRefactorRecoveryReceipt>();
+  return {
+    async createPreparedReceipt(draft) {
+      pruneOldestTerminalReceipts(byId);
+      const receipt: FileRefactorRecoveryReceipt = {
+        ...draft,
+        phase: "prepared",
+        phaseOrdinal: FILE_REFACTOR_JOURNAL_PHASE_ORDINAL.prepared,
+        filesystemState: "unchanged",
+        indexState: "not_attempted",
+        updatedAtMs: draft.createdAtMs,
+      };
+      byId.set(receipt.journalId, receipt);
+      return receipt;
+    },
+    async advanceReceipt(journalId, update) {
+      const current = byId.get(journalId);
+      if (!current) throw new Error(`Missing journal ${journalId}`);
+      assertAllowedJournalPhaseTransition(current.phase, update.phase);
+      if (update.updatedAtMs < current.updatedAtMs) {
+        throw new Error("Journal updatedAtMs must be monotonic");
+      }
+      const next: FileRefactorRecoveryReceipt = {
+        ...current,
+        phase: update.phase,
+        phaseOrdinal: FILE_REFACTOR_JOURNAL_PHASE_ORDINAL[update.phase],
+        filesystemState: update.filesystemState ?? current.filesystemState,
+        indexState: update.indexState ?? current.indexState,
+        fileEntries: update.fileEntries ?? current.fileEntries,
+        updatedAtMs: update.updatedAtMs,
+      };
+      byId.set(journalId, next);
+      return next;
+    },
+    async getReceiptById(journalId) {
+      return byId.get(journalId) ?? null;
+    },
+    async getLatestReceiptByPlanDigest(planDigest) {
+      const matches = [...byId.values()].filter(
+        (row) => row.planDigest === planDigest
+      );
+      matches.sort((left, right) => {
+        if (left.updatedAtMs !== right.updatedAtMs) {
+          return right.updatedAtMs - left.updatedAtMs;
+        }
+        return right.journalId < left.journalId
+          ? -1
+          : right.journalId > left.journalId
+            ? 1
+            : 0;
+      });
+      return matches[0] ?? null;
+    },
+  };
+}
+
+/** Adapter: wrap StorePort journal methods as FileRefactorJournalPort. */
+export function journalPortFromStore(store: {
+  createFileRefactorPreparedReceipt: (
+    draft: Parameters<FileRefactorJournalPort["createPreparedReceipt"]>[0]
+  ) => Promise<
+    { ok: true; value: FileRefactorRecoveryReceipt } | { ok: false }
+  >;
+  advanceFileRefactorReceipt: (
+    journalId: string,
+    update: Parameters<FileRefactorJournalPort["advanceReceipt"]>[1]
+  ) => Promise<
+    { ok: true; value: FileRefactorRecoveryReceipt } | { ok: false }
+  >;
+  getFileRefactorReceiptById: (
+    journalId: string
+  ) => Promise<
+    { ok: true; value: FileRefactorRecoveryReceipt | null } | { ok: false }
+  >;
+  getLatestFileRefactorReceiptByPlanDigest: (
+    planDigest: string
+  ) => Promise<
+    { ok: true; value: FileRefactorRecoveryReceipt | null } | { ok: false }
+  >;
+}): FileRefactorJournalPort {
+  return {
+    async createPreparedReceipt(draft) {
+      const result = await store.createFileRefactorPreparedReceipt(draft);
+      if (!result.ok) throw new Error("Failed to create refactor receipt");
+      return result.value;
+    },
+    async advanceReceipt(journalId, update) {
+      const result = await store.advanceFileRefactorReceipt(journalId, update);
+      if (!result.ok) throw new Error("Failed to advance refactor receipt");
+      return result.value;
+    },
+    async getReceiptById(journalId) {
+      const result = await store.getFileRefactorReceiptById(journalId);
+      if (!result.ok) throw new Error("Failed to load refactor receipt");
+      return result.value;
+    },
+    async getLatestReceiptByPlanDigest(planDigest) {
+      const result =
+        await store.getLatestFileRefactorReceiptByPlanDigest(planDigest);
+      if (!result.ok) throw new Error("Failed to lookup refactor receipt");
+      return result.value;
+    },
+  };
+}

package/src/core/file-refactor-journal.ts

@@ -0,0 +1,347 @@
+/**
+ * Content-free recovery journal types for reference-safe file refactors.
+ *
+ * Receipts never embed note bodies or replacement content — only IDs,
+ * digests, paths, phases, fingerprints, and status.
+ *
+ * Bounded globally: oldest terminal receipts are pruned on create
+ * (see FILE_REFACTOR_JOURNAL_MAX_RECEIPTS = 256). Uncertain/recovery-required
+ * receipts are never pruned.
+ *
+ * @module src/core/file-refactor-journal
+ */
+
+import type { FileRefactorOperation } from "./file-refactor-contract";
+
+import { tryValidateRefactorArtifactRelPath } from "./file-refactor-apply-safety";
+
+/**
+ * Ordered phases. Numeric ordinals make interruption state detectable:
+ * prepared < staging < committing < committed < sync_pending < converged.
+ * Rollback branch: committing → rolling_back → rolled_back | recovery_required.
+ * Abort before commit: prepared|staging → aborted.
+ */
+export const FILE_REFACTOR_JOURNAL_PHASES = [
+  "prepared",
+  "staging",
+  "committing",
+  "committed",
+  "sync_pending",
+  "converged",
+  "rolling_back",
+  "rolled_back",
+  "recovery_required",
+  "aborted",
+] as const;
+
+export type FileRefactorJournalPhase =
+  (typeof FILE_REFACTOR_JOURNAL_PHASES)[number];
+
+export const FILE_REFACTOR_JOURNAL_PHASE_ORDINAL: Record<
+  FileRefactorJournalPhase,
+  number
+> = {
+  prepared: 10,
+  staging: 20,
+  committing: 30,
+  committed: 40,
+  sync_pending: 50,
+  converged: 60,
+  rolling_back: 35,
+  rolled_back: 70,
+  recovery_required: 80,
+  aborted: 5,
+};
+
+/** Hard cap: prune oldest terminal receipts only during create. */
+export const FILE_REFACTOR_JOURNAL_MAX_RECEIPTS = 256;
+
+export type FileRefactorJournalFileRole = "source" | "target" | "affected";
+
+export type FileRefactorJournalFileStatus =
+  | "pending"
+  | "staged"
+  | "committed"
+  | "restored"
+  | "absent"
+  | "failed";
+
+/** Per-file metadata only — fingerprints/status/artifact paths, never bodies. */
+export interface FileRefactorJournalFileEntry {
+  role: FileRefactorJournalFileRole;
+  relPath: string;
+  /** Collection-relative stage artifact path (content-free locator). */
+  stageRelPath?: string;
+  /** Collection-relative backup artifact path (content-free locator). */
+  backupRelPath?: string;
+  originalFingerprint?: string;
+  expectedFingerprint?: string;
+  status: FileRefactorJournalFileStatus;
+}
+
+export type FileRefactorJournalFilesystemState =
+  | "unchanged"
+  | "committed"
+  | "rolled_back"
+  | "recovery_required";
+
+export type FileRefactorJournalIndexState =
+  | "not_attempted"
+  | "pending"
+  | "converged"
+  | "skipped";
+
+/** Durable, content-free recovery receipt. */
+export interface FileRefactorRecoveryReceipt {
+  journalId: string;
+  planDigest: string;
+  collection: string;
+  operation: FileRefactorOperation;
+  sourceRelPath: string;
+  targetRelPath: string;
+  phase: FileRefactorJournalPhase;
+  phaseOrdinal: number;
+  filesystemState: FileRefactorJournalFilesystemState;
+  indexState: FileRefactorJournalIndexState;
+  fileEntries: FileRefactorJournalFileEntry[];
+  createdAtMs: number;
+  updatedAtMs: number;
+}
+
+export interface FileRefactorRecoveryReceiptDraft {
+  journalId: string;
+  planDigest: string;
+  collection: string;
+  operation: FileRefactorOperation;
+  sourceRelPath: string;
+  targetRelPath: string;
+  fileEntries: FileRefactorJournalFileEntry[];
+  createdAtMs: number;
+}
+
+export interface FileRefactorJournalAdvance {
+  phase: FileRefactorJournalPhase;
+  filesystemState?: FileRefactorJournalFilesystemState;
+  indexState?: FileRefactorJournalIndexState;
+  fileEntries?: FileRefactorJournalFileEntry[];
+  updatedAtMs: number;
+}
+
+/**
+ * Small explicit port for durable recovery receipts.
+ * Prefer injecting this over a full StorePort in the apply service.
+ */
+export interface FileRefactorJournalPort {
+  createPreparedReceipt(
+    draft: FileRefactorRecoveryReceiptDraft
+  ): Promise<FileRefactorRecoveryReceipt>;
+  advanceReceipt(
+    journalId: string,
+    update: FileRefactorJournalAdvance
+  ): Promise<FileRefactorRecoveryReceipt>;
+  getReceiptById(
+    journalId: string
+  ): Promise<FileRefactorRecoveryReceipt | null>;
+  /**
+   * Latest receipt for a plan digest (highest updatedAtMs, then journalId).
+   * Stable deterministic lookup for idempotent retry.
+   */
+  getLatestReceiptByPlanDigest(
+    planDigest: string
+  ): Promise<FileRefactorRecoveryReceipt | null>;
+}
+
+/**
+ * Allowed phase transitions (monotonic / documented rollback branch).
+ * Same-phase advances persist per-file status during staging/commit/rollback.
+ */
+export const FILE_REFACTOR_JOURNAL_ALLOWED_TRANSITIONS: Record<
+  FileRefactorJournalPhase,
+  readonly FileRefactorJournalPhase[]
+> = {
+  prepared: ["prepared", "staging", "aborted", "recovery_required"],
+  staging: [
+    "staging",
+    "committing",
+    "aborted",
+    "rolling_back",
+    "recovery_required",
+  ],
+  committing: ["committing", "committed", "rolling_back", "recovery_required"],
+  committed: ["sync_pending", "converged"],
+  sync_pending: ["converged", "sync_pending"],
+  converged: [],
+  rolling_back: ["rolling_back", "rolled_back", "recovery_required"],
+  rolled_back: [],
+  recovery_required: [],
+  aborted: [],
+};
+
+export function assertAllowedJournalPhaseTransition(
+  from: FileRefactorJournalPhase,
+  to: FileRefactorJournalPhase
+): void {
+  const allowed = FILE_REFACTOR_JOURNAL_ALLOWED_TRANSITIONS[from];
+  if (!allowed.includes(to)) {
+    throw new Error(`Invalid journal phase transition ${from} -> ${to}`);
+  }
+}
+
+export function isTerminalJournalPhase(
+  phase: FileRefactorJournalPhase
+): boolean {
+  return (
+    phase === "converged" ||
+    phase === "rolled_back" ||
+    phase === "recovery_required" ||
+    phase === "aborted"
+  );
+}
+
+/** Terminal phases safe to prune under the global retention cap. */
+export function isPrunableJournalPhase(
+  phase: FileRefactorJournalPhase
+): boolean {
+  return (
+    phase === "converged" || phase === "rolled_back" || phase === "aborted"
+  );
+}
+
+export function isUncertainJournalPhase(
+  phase: FileRefactorJournalPhase
+): boolean {
+  return (
+    phase === "prepared" ||
+    phase === "staging" ||
+    phase === "committing" ||
+    phase === "rolling_back" ||
+    phase === "recovery_required"
+  );
+}
+
+export function isCommittedFilesystemPhase(
+  phase: FileRefactorJournalPhase
+): boolean {
+  return (
+    phase === "committed" || phase === "sync_pending" || phase === "converged"
+  );
+}
+
+const FILE_ENTRY_ROLES = new Set(["source", "target", "affected"]);
+const FILE_ENTRY_STATUSES = new Set([
+  "pending",
+  "staged",
+  "committed",
+  "restored",
+  "absent",
+  "failed",
+]);
+
+function isOptionalString(value: unknown): value is string | undefined {
+  return value === undefined || typeof value === "string";
+}
+
+function assertOptionalFingerprint(
+  value: unknown,
+  field: string
+): asserts value is string | undefined {
+  if (value === undefined) return;
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) {
+    throw new Error(`Corrupt file_entries_json: invalid ${field}`);
+  }
+}
+
+function assertOptionalArtifactRelPath(
+  value: unknown,
+  kind: "stage" | "backup"
+): asserts value is string | undefined {
+  if (value === undefined) return;
+  if (typeof value !== "string") {
+    throw new Error(`Corrupt file_entries_json: invalid ${kind}RelPath`);
+  }
+  if (!tryValidateRefactorArtifactRelPath(value, kind)) {
+    throw new Error(`Corrupt file_entries_json: invalid ${kind}RelPath`);
+  }
+}
+
+/** Defensive parse of file_entries_json — rejects corrupt shapes. */
+export function parseFileRefactorJournalFileEntries(
+  raw: unknown
+): FileRefactorJournalFileEntry[] {
+  if (typeof raw === "string") {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new Error("Corrupt file_entries_json: invalid JSON");
+    }
+    return parseFileRefactorJournalFileEntries(parsed);
+  }
+  if (!Array.isArray(raw)) {
+    throw new Error("Corrupt file_entries_json: expected array");
+  }
+  const entries: FileRefactorJournalFileEntry[] = [];
+  const seenRelPaths = new Set<string>();
+  const seenRoles = new Set<string>();
+  for (const item of raw) {
+    if (item === null || typeof item !== "object" || Array.isArray(item)) {
+      throw new Error("Corrupt file_entries_json: entry must be object");
+    }
+    const row = item as Record<string, unknown>;
+    if (typeof row.role !== "string" || !FILE_ENTRY_ROLES.has(row.role)) {
+      throw new Error("Corrupt file_entries_json: invalid role");
+    }
+    if (typeof row.relPath !== "string" || row.relPath.length === 0) {
+      throw new Error("Corrupt file_entries_json: invalid relPath");
+    }
+    if (
+      typeof row.status !== "string" ||
+      !FILE_ENTRY_STATUSES.has(row.status)
+    ) {
+      throw new Error("Corrupt file_entries_json: invalid status");
+    }
+    if (
+      !isOptionalString(row.stageRelPath) ||
+      !isOptionalString(row.backupRelPath) ||
+      !isOptionalString(row.originalFingerprint) ||
+      !isOptionalString(row.expectedFingerprint)
+    ) {
+      throw new Error("Corrupt file_entries_json: invalid optional fields");
+    }
+    assertOptionalFingerprint(row.originalFingerprint, "originalFingerprint");
+    assertOptionalFingerprint(row.expectedFingerprint, "expectedFingerprint");
+    assertOptionalArtifactRelPath(row.stageRelPath, "stage");
+    assertOptionalArtifactRelPath(row.backupRelPath, "backup");
+    if (seenRelPaths.has(row.relPath)) {
+      throw new Error("Corrupt file_entries_json: duplicate relPath");
+    }
+    seenRelPaths.add(row.relPath);
+    const roleKey = `${row.role}:${row.relPath}`;
+    if (seenRoles.has(roleKey)) {
+      throw new Error("Corrupt file_entries_json: duplicate role/relPath");
+    }
+    seenRoles.add(roleKey);
+    if (
+      "content" in row ||
+      "body" in row ||
+      "replacement" in row ||
+      "originalDestination" in row ||
+      "finalContent" in row
+    ) {
+      throw new Error("File refactor journal must not store note content");
+    }
+    entries.push({
+      role: row.role as FileRefactorJournalFileEntry["role"],
+      relPath: row.relPath,
+      stageRelPath: row.stageRelPath,
+      backupRelPath: row.backupRelPath,
+      originalFingerprint: row.originalFingerprint,
+      expectedFingerprint: row.expectedFingerprint,
+      status: row.status as FileRefactorJournalFileEntry["status"],
+    });
+  }
+  return entries;
+}
+
+export const FILE_REFACTOR_SYNC_PENDING_INSTRUCTION =
+  "Filesystem refactor committed; retry apply with the same plan digest to finish index convergence without repeating file mutations.";

package/src/core/file-refactor-paths.ts

@@ -0,0 +1,60 @@
+/** Browser-safe path target planning for canonical rename and move. */
+
+// node:path/posix — no Bun path utils
+import { posix as pathPosix } from "node:path";
+
+import { validateRelPath } from "./validation";
+
+export interface RenamePlan {
+  nextRelPath: string;
+  nextUri: string;
+}
+
+export interface MovePlan {
+  nextRelPath: string;
+  nextUri: string;
+}
+
+export function planRenameRefactor(input: {
+  collection: string;
+  currentRelPath: string;
+  nextName: string;
+}): RenamePlan {
+  const current = validateRelPath(input.currentRelPath);
+  const directory = pathPosix.dirname(current);
+  const currentExt = pathPosix.extname(current);
+  const nextFilename = pathPosix.extname(input.nextName)
+    ? input.nextName
+    : `${input.nextName}${currentExt}`;
+  const nextRelPath =
+    directory === "."
+      ? validateRelPath(nextFilename)
+      : validateRelPath(`${directory}/${nextFilename}`);
+
+  return {
+    nextRelPath,
+    nextUri: `gno://${input.collection}/${nextRelPath}`,
+  };
+}
+
+export function planMoveRefactor(input: {
+  collection: string;
+  currentRelPath: string;
+  folderPath: string;
+  nextName?: string;
+}): MovePlan {
+  const current = validateRelPath(input.currentRelPath);
+  const safeFolder = validateRelPath(input.folderPath).replace(
+    /^\.\/|\/+$/g,
+    ""
+  );
+  const filename = input.nextName?.trim() || pathPosix.basename(current);
+  const nextRelPath = safeFolder
+    ? validateRelPath(`${safeFolder}/${filename}`)
+    : validateRelPath(filename);
+
+  return {
+    nextRelPath,
+    nextUri: `gno://${input.collection}/${nextRelPath}`,
+  };
+}