@gmickel/gno 2.5.1 → 2.6.0

package/src/core/capture-publish.ts

@@ -0,0 +1,239 @@
+/**
+ * Shared leased capture publication for CLI, MCP, SDK and REST.
+ *
+ * One critical section under the shared write lease: plan against current
+ * state, publish the note, lexically sync it. With a request ID the same
+ * steps run through the request-receipt service so a retry replays or
+ * finishes the admitted capture instead of planning a second one.
+ *
+ * @module src/core/capture-publish
+ */
+
+// node:fs/promises mkdir: filesystem structure op, no Bun equivalent
+import { mkdir } from "node:fs/promises";
+// node:path has no Bun path utilities
+import { dirname, join } from "node:path";
+
+import type { Collection, Config } from "../config/types";
+import type { StorePort } from "../store/types";
+
+import {
+  buildCaptureReceipt,
+  type CaptureInput,
+  CaptureSyncError,
+  type CapturePlan,
+  type CaptureReceipt,
+  type CaptureSyncPaths,
+  ensureCapturedFileIndexed,
+  syncCapturedFile,
+  type SyncCapturedFileResult,
+} from "./capture";
+import { writeCapturePlanFile } from "./capture-write";
+import { withWriteLock } from "./file-lock";
+import {
+  type RequestCheckpoint,
+  requestDigest,
+  type RequestPlanState,
+  type RequestReceiptInfo,
+  runRequestedWrite,
+} from "./request-receipts";
+import { DEFAULT_LOCK_WAIT_MS } from "./write-lease";
+
+export interface CaptureRequest {
+  ledgerPath: string;
+  namespace: string;
+  requestId: string;
+  /** Semantic capture input: the request digest payload. */
+  input: CaptureInput;
+  checkpoint?: (stage: RequestCheckpoint) => Promise<void> | void;
+}
+
+export interface PublishCaptureInput {
+  collection: Collection;
+  store: StorePort;
+  lockPath: string;
+  lockWaitMs?: number;
+  config?: Pick<Config, "contentTypes">;
+  syncPaths?: CaptureSyncPaths;
+  /** Plan against current state. Runs under the lease; must not write. */
+  plan: () => Promise<CapturePlan>;
+  beforeWrite?: (absPath: string) => void;
+  /**
+   * CLI/SDK receipt contract without a request ID: a failed lexical sync is
+   * reported in `sync` (not thrown) and an unindexed `open_existing` file is
+   * returned as `skipped` rather than synced.
+   */
+  reportSyncFailure?: boolean;
+  /** Runs under the lease once the capture is retrievable. */
+  afterSync?: (
+    synced: SyncCapturedFileResult,
+    receipt: CaptureReceipt
+  ) => Promise<void> | void;
+  request?: CaptureRequest;
+}
+
+export interface PublishedCapture {
+  receipt: CaptureReceipt;
+  request?: RequestReceiptInfo;
+}
+
+/**
+ * Private recovery record: destination, expected file hashes and the
+ * pre-sync receipt (metadata only, never the note content).
+ */
+interface CaptureRecoveryPlan {
+  openedExisting: boolean;
+  fileHash: string;
+  baseHash: string | null;
+  receipt: CaptureReceipt;
+}
+
+const sha256 = (value: string): string =>
+  new Bun.CryptoHasher("sha256").update(value).digest("hex");
+
+async function readFileHash(absPath: string): Promise<string | null> {
+  const file = Bun.file(absPath);
+  if (!(await file.exists())) return null;
+  return sha256(await file.text());
+}
+
+/** Pre-sync receipt; `sync` is replaced once the capture is retrievable. */
+function toReceipt(plan: CapturePlan, absPath: string): CaptureReceipt {
+  return buildCaptureReceipt({
+    plan,
+    absPath,
+    overwritten: plan.collisionPolicyResult === "overwritten",
+    sync: plan.provenanceConflict
+      ? {
+          status: "skipped",
+          reason:
+            "Existing capture has absent or different browser provenance.",
+        }
+      : undefined,
+  });
+}
+
+export async function publishCapture(
+  options: PublishCaptureInput
+): Promise<PublishedCapture> {
+  const absPathFor = (relPath: string) =>
+    join(options.collection.path, relPath);
+  const syncInput = (plan: Pick<CaptureReceipt, "relPath">) => ({
+    collection: options.collection,
+    store: options.store,
+    relPath: plan.relPath,
+    absPath: absPathFor(plan.relPath),
+    config: options.config,
+    syncPaths: options.syncPaths,
+  });
+  const write = async (plan: CapturePlan): Promise<void> => {
+    const absPath = absPathFor(plan.relPath);
+    await mkdir(dirname(absPath), { recursive: true });
+    options.beforeWrite?.(absPath);
+    await writeCapturePlanFile(plan, absPath);
+  };
+  const finish = async (
+    draft: CaptureReceipt,
+    openedExisting: boolean
+  ): Promise<CaptureReceipt> => {
+    const synced = openedExisting
+      ? await ensureCapturedFileIndexed(syncInput(draft))
+      : await syncCapturedFile(syncInput(draft));
+    await options.afterSync?.(synced, draft);
+    return { ...draft, docid: synced.docid, sync: synced.sync };
+  };
+  const lockWaitMs = options.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS;
+
+  if (!options.request) {
+    const receipt = await withWriteLock(
+      options.lockPath,
+      async () => {
+        const plan = await options.plan();
+        if (plan.provenanceConflict) {
+          return toReceipt(plan, absPathFor(plan.relPath));
+        }
+        if (!plan.openedExisting) await write(plan);
+        const draft = toReceipt(plan, absPathFor(plan.relPath));
+        if (!options.reportSyncFailure) {
+          return finish(draft, plan.openedExisting);
+        }
+        if (plan.openedExisting) {
+          const existing = await options.store.getDocument(
+            plan.collection,
+            plan.relPath
+          );
+          if (!existing.ok) throw new Error(existing.error.message);
+          const opened: CaptureReceipt = {
+            ...draft,
+            docid: existing.value?.docid,
+            sync: existing.value
+              ? { status: "completed" }
+              : {
+                  status: "skipped",
+                  reason: "Existing file is not indexed yet.",
+                },
+          };
+          return opened;
+        }
+        try {
+          return await finish(draft, false);
+        } catch (error) {
+          if (!(error instanceof CaptureSyncError)) throw error;
+          const failed: CaptureReceipt = {
+            ...draft,
+            sync: { status: "failed", error: error.syncError },
+          };
+          return failed;
+        }
+      },
+      lockWaitMs
+    );
+    return { receipt };
+  }
+
+  const outcome = await runRequestedWrite<CaptureRecoveryPlan, CaptureReceipt>({
+    ledgerPath: options.request.ledgerPath,
+    namespace: options.request.namespace,
+    requestId: options.request.requestId,
+    operation: "capture",
+    digest: requestDigest("capture", options.request.input),
+    lockPath: options.lockPath,
+    lockWaitMs,
+    checkpoint: options.request.checkpoint,
+    prepare: async () => {
+      const plan = await options.plan();
+      if (plan.provenanceConflict) {
+        return { result: toReceipt(plan, absPathFor(plan.relPath)) };
+      }
+      const absPath = absPathFor(plan.relPath);
+      const baseHash = plan.overwrite ? await readFileHash(absPath) : null;
+      return {
+        plan: {
+          openedExisting: plan.openedExisting,
+          fileHash: sha256(plan.content),
+          baseHash,
+          receipt: toReceipt(plan, absPath),
+        },
+        publish: async () => {
+          if (!plan.openedExisting) await write(plan);
+        },
+      };
+    },
+    inspect: async (recovery): Promise<RequestPlanState> => {
+      const onDisk = await readFileHash(absPathFor(recovery.receipt.relPath));
+      if (recovery.openedExisting) {
+        return onDisk === null ? "absent" : "published";
+      }
+      if (onDisk === recovery.fileHash) return "published";
+      if (onDisk === recovery.baseHash) return "absent";
+      return onDisk === null ? "absent" : "unexpected";
+    },
+    finish: (recovery) => finish(recovery.receipt, recovery.openedExisting),
+    resultRef: (receipt) => ({
+      uri: receipt.uri,
+      docid: receipt.docid,
+      contentHash: receipt.contentHash,
+    }),
+  });
+  return { receipt: outcome.result, request: outcome.request };
+}

package/src/core/capture-sync.ts

@@ -27,6 +27,8 @@ export class CaptureSyncError extends Error {
   readonly code = CAPTURE_SYNC_FAILED_CODE;
   readonly absPath: string;
   readonly relPath: string;
+  /** The sync failure itself, without the write half of the message. */
+  readonly syncError: string;
 
   constructor(input: { absPath: string; relPath: string; cause: string }) {
     super(
@@ -35,6 +37,7 @@ export class CaptureSyncError extends Error {
     this.name = "CaptureSyncError";
     this.absPath = input.absPath;
     this.relPath = input.relPath;
+    this.syncError = input.cause;
   }
 }
 

package/src/core/memory-remember.ts

@@ -56,6 +56,13 @@ import {
   MEMORY_SEMANTIC_LIKELY_THRESHOLD,
   MemoryError,
 } from "./memory-types";
+import {
+  isLeaseBusy,
+  RequestReceiptError,
+  requestDigest,
+  runRequestedWrite,
+  validateRequestId,
+} from "./request-receipts";
 
 export interface CandidateQuery {
   text: string;
@@ -249,6 +256,12 @@ async function supersedesEdgeProjected(
 // remember
 // ─────────────────────────────────────────────────────────────────────────────
 
+interface RememberPlan {
+  frontmatter: MemoryRecordFrontmatter;
+  supersedes: string[];
+  relPath: string;
+}
+
 export async function rememberFact(
   deps: MemoryServiceDeps,
   rawInput: RememberInput
@@ -270,14 +283,26 @@ export async function rememberFact(
       );
     }
   }
+  const requestId =
+    rawInput.requestId === undefined
+      ? undefined
+      : validateRequestId(rawInput.requestId);
+  if (requestId !== undefined && decision === undefined) {
+    throw new RequestReceiptError(
+      "REQUEST_ID_INVALID",
+      "requestId applies only to writes: pass decision add or supersede."
+    );
+  }
 
   const { candidates, matching } = await findMemoryCandidates(deps, {
     text,
     collection: collection.name,
     scopes,
   });
+  // With a request ID the exact-duplicate decision is made (and recorded)
+  // under the lease, so a later retry replays it instead of re-deciding.
   const exact = candidates.find((candidate) => candidate.match === "exact");
-  if (exact && decision !== "supersede") {
+  if (exact && decision !== "supersede" && requestId === undefined) {
     const { similarity: _similarity, match: _match, ...record } = exact;
     return { outcome: "existing", record, matching };
   }
@@ -285,135 +310,222 @@ export async function rememberFact(
     return { outcome: "candidates", candidates, matching };
   }
 
-  const createdAt = memoryNow(deps).toISOString();
   const source = rawInput.source?.trim() || undefined;
-  const frontmatter: MemoryRecordFrontmatter = {
-    recordId: buildMemoryRecordId({
-      contentHash,
-      createdAt,
+  const absPathOf = (plan: RememberPlan) => join(collection.path, plan.relPath);
+
+  /** Under the lease: decide against current state; never writes. */
+  const prepare = async (): Promise<
+    { plan: RememberPlan } | { result: RememberResult }
+  > => {
+    const supersedes: string[] = [];
+    if (decision === "supersede") {
+      supersedes.push(
+        await verifyPredecessor(
+          deps,
+          collection.name,
+          rawInput.predecessorUri as string,
+          rawInput.predecessorHash as string
+        )
+      );
+    } else {
+      // The pre-lease check raced with any concurrent writer; decide
+      // idempotency on the state visible under the lease.
+      const existing = await findExactCurrent(deps, {
+        text,
+        collection: collection.name,
+        scopes,
+        contentHash,
+      });
+      if (existing) {
+        return { result: { outcome: "existing", record: existing, matching } };
+      }
+    }
+    const createdAt = memoryNow(deps).toISOString();
+    const frontmatter: MemoryRecordFrontmatter = {
+      recordId: buildMemoryRecordId({
+        contentHash,
+        createdAt,
+        caller: identity.caller,
+        session: identity.session,
+      }),
+      scopes,
       caller: identity.caller,
       session: identity.session,
-    }),
-    scopes,
-    caller: identity.caller,
-    session: identity.session,
-    createdAt,
-    contentHash,
-    ...(source ? { source } : {}),
+      createdAt,
+      contentHash,
+      ...(source ? { source } : {}),
+    };
+    return {
+      plan: {
+        frontmatter,
+        supersedes,
+        relPath: buildMemoryRecordRelPath(frontmatter),
+      },
+    };
   };
-  const relPath = buildMemoryRecordRelPath(frontmatter);
-  const absPath = join(collection.path, relPath);
-  const lockWaitMs = memoryLockWaitMs(deps);
-
-  let leased: RememberResult;
-  try {
-    leased = await withWriteLock(
-      deps.lockPath,
-      async () => {
-        const supersedes: string[] = [];
-        if (decision === "supersede") {
-          supersedes.push(
-            await verifyPredecessor(
-              deps,
-              collection.name,
-              rawInput.predecessorUri as string,
-              rawInput.predecessorHash as string
-            )
-          );
-        } else {
-          // The pre-lease check raced with any concurrent writer; decide
-          // idempotency on the state visible under the lease.
-          const existing = await findExactCurrent(deps, {
-            text,
-            collection: collection.name,
-            scopes,
-            contentHash,
-          });
-          if (existing) {
-            return { outcome: "existing", record: existing, matching };
+  const serialize = (plan: RememberPlan): string =>
+    serializeMemoryRecord({
+      frontmatter: plan.frontmatter,
+      supersedes: plan.supersedes,
+      text,
+    });
+  const publish = async (plan: RememberPlan): Promise<void> => {
+    await mkdir(dirname(absPathOf(plan)), { recursive: true });
+    await atomicCreate(absPathOf(plan), serialize(plan));
+  };
+  /** Under the lease: lexical sync, projection check, result. */
+  const finish = async (plan: RememberPlan): Promise<RememberResult> => {
+    const { relPath, supersedes, frontmatter } = plan;
+    const absPath = absPathOf(plan);
+    // syncPaths (not syncFiles) so typed-edge projection errors surface.
+    const syncResult = await (deps.syncService ?? defaultSyncService).syncPaths(
+      collection,
+      store,
+      [relPath],
+      withContentTypeRules({ runUpdateCmd: false, gitPull: false }, config)
+    );
+    const fileResult = syncResult.files?.[0];
+    const doc = await store.getDocument(collection.name, relPath);
+    const sync: MemorySyncState =
+      fileResult?.status === "error" || !doc.ok || doc.value === null
+        ? {
+            status: "failed",
+            error:
+              fileResult?.errorMessage ??
+              fileResult?.errorCode ??
+              "memory record was written but is not retrievable yet",
           }
-        }
-        await mkdir(dirname(absPath), { recursive: true });
-        await atomicCreate(
-          absPath,
-          serializeMemoryRecord({ frontmatter, supersedes, text })
+        : { status: "completed" };
+    if (sync.status === "failed") {
+      throw new MemoryError(
+        "MEMORY_SYNC_FAILED",
+        `Memory record written to ${absPath} but lexical sync failed: ${sync.error}. Run gno update to retry indexing.`
+      );
+    }
+    const written = (doc as { value: DocumentRow }).value;
+    const projectionErrors = syncResult.errors
+      .map((error) => `${error.relPath}: ${error.message}`)
+      .join("; ");
+    if (decision === "supersede") {
+      // The write is only a supersession once the edge is projected;
+      // until then the predecessor still reads as current.
+      const projected =
+        projectionErrors.length === 0 &&
+        (await supersedesEdgeProjected(deps, written.id, supersedes));
+      if (!projected) {
+        throw new MemoryError(
+          "MEMORY_SUPERSEDE_PROJECTION_FAILED",
+          `Successor written to ${absPath} but its supersedes edge did not project${projectionErrors ? ` (${projectionErrors})` : ""}; the predecessor still reads as current. Run gno update to retry the projection.`
         );
-        // syncPaths (not syncFiles) so typed-edge projection errors surface.
-        const syncResult = await (
-          deps.syncService ?? defaultSyncService
-        ).syncPaths(
-          collection,
-          store,
-          [relPath],
-          withContentTypeRules({ runUpdateCmd: false, gitPull: false }, config)
+      }
+    } else if (projectionErrors.length > 0) {
+      throw new MemoryError(
+        "MEMORY_SYNC_FAILED",
+        `Memory record written to ${absPath} but typed-edge projection failed: ${projectionErrors}. Run gno update to retry indexing.`
+      );
+    }
+    const record: MemoryFact = {
+      uri: written.uri,
+      docid: written.docid,
+      recordId: frontmatter.recordId,
+      text,
+      scopes: frontmatter.scopes,
+      caller: frontmatter.caller,
+      session: frontmatter.session,
+      createdAt: frontmatter.createdAt,
+      contentHash,
+      supersedes,
+      ...(frontmatter.source ? { source: frontmatter.source } : {}),
+    };
+    return {
+      outcome: decision === "supersede" ? "superseded" : "added",
+      record,
+      absPath,
+      sync,
+      matching,
+    };
+  };
+
+  const lockWaitMs = memoryLockWaitMs(deps);
+  try {
+    if (requestId === undefined) {
+      return await withWriteLock(
+        deps.lockPath,
+        async () => {
+          const prepared = await prepare();
+          if ("result" in prepared) return prepared.result;
+          await publish(prepared.plan);
+          return finish(prepared.plan);
+        },
+        lockWaitMs
+      );
+    }
+    if (!deps.requests) {
+      throw new RequestReceiptError(
+        "REQUEST_LEDGER_UNAVAILABLE",
+        "This memory service has no request ledger; retry without requestId."
+      );
+    }
+    const outcome = await runRequestedWrite<RememberPlan, RememberResult>({
+      ledgerPath: deps.requests.ledgerPath,
+      namespace: deps.requests.namespace,
+      requestId,
+      operation: "remember",
+      // Caller/session are provenance, not intent: a retry may reconnect
+      // under a new session and must still match.
+      digest: requestDigest("remember", {
+        collection: collection.name,
+        text,
+        scopes,
+        decision,
+        predecessorUri: rawInput.predecessorUri?.trim(),
+        predecessorHash: rawInput.predecessorHash,
+        source,
+      }),
+      lockPath: deps.lockPath,
+      lockWaitMs,
+      checkpoint: deps.requests.checkpoint,
+      prepare: async () => {
+        const prepared = await prepare();
+        if ("result" in prepared) return prepared;
+        return { plan: prepared.plan, publish: () => publish(prepared.plan) };
+      },
+      inspect: async (plan) => {
+        const file = Bun.file(absPathOf(plan));
+        if (!(await file.exists())) return "absent";
+        if ((await file.text()) !== serialize(plan)) return "unexpected";
+        // Another successor may have superseded the predecessor while this
+        // one sat unprojected: finishing would leave two successors.
+        const [predecessorUri] = plan.supersedes;
+        if (!predecessorUri) return "published";
+        const predecessor = await store.getDocumentByUri(predecessorUri);
+        if (!predecessor.ok || !predecessor.value) return "unexpected";
+        const successors = await store.getEdgeBacklinksForDoc(
+          predecessor.value.id,
+          { edgeType: MEMORY_SUPERSEDES_EDGE }
         );
-        const fileResult = syncResult.files?.[0];
-        const doc = await store.getDocument(collection.name, relPath);
-        const sync: MemorySyncState =
-          fileResult?.status === "error" || !doc.ok || doc.value === null
-            ? {
-                status: "failed",
-                error:
-                  fileResult?.errorMessage ??
-                  fileResult?.errorCode ??
-                  "memory record was written but is not retrievable yet",
-              }
-            : { status: "completed" };
-        if (sync.status === "failed") {
-          throw new MemoryError(
-            "MEMORY_SYNC_FAILED",
-            `Memory record written to ${absPath} but lexical sync failed: ${sync.error}. Run gno update to retry indexing.`
-          );
-        }
-        const written = (doc as { value: DocumentRow }).value;
-        const projectionErrors = syncResult.errors
-          .map((error) => `${error.relPath}: ${error.message}`)
-          .join("; ");
-        if (decision === "supersede") {
-          // The write is only a supersession once the edge is projected;
-          // until then the predecessor still reads as current.
-          const projected =
-            projectionErrors.length === 0 &&
-            (await supersedesEdgeProjected(deps, written.id, supersedes));
-          if (!projected) {
-            throw new MemoryError(
-              "MEMORY_SUPERSEDE_PROJECTION_FAILED",
-              `Successor written to ${absPath} but its supersedes edge did not project${projectionErrors ? ` (${projectionErrors})` : ""}; the predecessor still reads as current. Run gno update to retry the projection.`
-            );
-          }
-        } else if (projectionErrors.length > 0) {
-          throw new MemoryError(
-            "MEMORY_SYNC_FAILED",
-            `Memory record written to ${absPath} but typed-edge projection failed: ${projectionErrors}. Run gno update to retry indexing.`
-          );
-        }
-        const record: MemoryFact = {
-          uri: written.uri,
-          docid: written.docid,
-          recordId: frontmatter.recordId,
-          text,
-          scopes,
-          caller: identity.caller,
-          session: identity.session,
-          createdAt,
-          contentHash,
-          supersedes,
-          ...(source ? { source } : {}),
-        };
-        return {
-          outcome: decision === "supersede" ? "superseded" : "added",
-          record,
-          absPath,
-          sync,
-          matching,
-        };
+        const ownUri = `gno://${collection.name}/${plan.relPath}`;
+        return successors.ok &&
+          successors.value.every((edge) => edge.sourceUri === ownUri)
+          ? "published"
+          : "unexpected";
       },
-      lockWaitMs
-    );
+      finish,
+      resultRef: (result) =>
+        result.outcome === "candidates"
+          ? {}
+          : {
+              uri: result.record.uri,
+              docid: result.record.docid,
+              contentHash: result.record.contentHash,
+            },
+    });
+    return { ...outcome.result, request: outcome.request } as RememberResult;
   } catch (error) {
-    if (error instanceof MemoryError) throw error;
-    const message = error instanceof Error ? error.message : String(error);
-    if (message.startsWith("LOCKED")) {
+    if (error instanceof MemoryError || error instanceof RequestReceiptError) {
+      throw error;
+    }
+    if (isLeaseBusy(error)) {
       throw new MemoryError(
         "MEMORY_WRITE_LEASE_BUSY",
         `Could not acquire the shared write lease at ${deps.lockPath} within ${lockWaitMs}ms: another write holds it. The memory service takes the lease itself; callers must not pre-hold it.`
@@ -421,5 +533,4 @@ export async function rememberFact(
     }
     throw error;
   }
-  return leased;
 }