@agent-native/core-corpus 0.216.0 → 0.217.0

package/corpus/templates/content/server/live-copy/persist.ts

@@ -0,0 +1,656 @@
+import { ActionContractError } from "@agent-native/core";
+import type {
+  LiveCopyCommit,
+  LiveCopyPersistOutcome,
+} from "@agent-native/core/collab";
+import type { DbExec } from "@agent-native/core/db";
+import { and, desc, eq, isNull, or, sql } from "drizzle-orm";
+
+import {
+  lockPrimaryBlocksFields,
+  persistBlocksFieldIdentity,
+} from "../../actions/_blocks-field-identity.js";
+import { reconcileInlineDatabasesForDocumentWithDb } from "../../actions/_content-database-lifecycle.js";
+import { documentContentHash } from "../../actions/_document-edit-mutation.js";
+import { assertSourceAllowsPageEdit } from "../../actions/_document-source.js";
+import { HISTORY_IDLE_MS } from "../../app/components/editor/document-history-session.js";
+import { changedBlocksBetween } from "../../shared/document-intent-merge.js";
+import { getDb, schema } from "../db/index.js";
+import {
+  documentAttributionActor,
+  documentEditAttribution,
+} from "../lib/document-attribution.js";
+import { recordDocumentBodyIntent } from "../lib/document-body-intents.js";
+import {
+  recordDocumentHistoryTransition,
+  type DocumentHistoryCause,
+} from "../lib/document-history.js";
+import { nextDocumentUpdatedAt } from "../lib/document-updated-at.js";
+import {
+  liveBodyWriterFlagsOn,
+  liveBodyWriterGateForRow,
+} from "../lib/live-body-writer.js";
+import { syncPrivateCalloutReferences } from "../lib/private-icon-references.js";
+import { drizzleOverExec } from "./exec-db.js";
+import {
+  currentContentBodyWriteCause,
+  liveBodyConversionFor,
+  type ContentBodyIntentRecord,
+  type ContentBodyWriteCause,
+  type LiveBodyConversion,
+} from "./write-cause.js";
+
+type ContentDb = ReturnType<typeof getDb>;
+
+/** What one live-copy commit wrote to its page, read back in the same transaction. */
+export interface PersistedContentBodyCommit {
+  /** The page body before this commit. */
+  before: string;
+  /** The page body this commit wrote: the live copy's derived text. */
+  after: string;
+  bodyRevision: number;
+  updatedAt: string;
+  /** Inline collections the new body no longer holds, now in Trash. */
+  softDeletedDatabaseIds: string[];
+}
+
+const persistedCommits = new WeakMap<DbExec, PersistedContentBodyCommit>();
+
+/**
+ * What the binding's persist wrote in transaction `tx`, for a caller's own
+ * `mutateLiveCopy` persist, which core runs after it in the same
+ * transaction. `undefined` on an unchanged edit, which commits no live copy.
+ * A server write whose page left its live copy never gets this far: persist
+ * refuses it with `LIVE_BODY_WRITE_PATH_CHANGED`.
+ */
+export function persistedContentBodyCommit(
+  tx: DbExec,
+): PersistedContentBodyCommit | undefined {
+  return persistedCommits.get(tx);
+}
+
+export type LiveBodyConversionErrorCode = "base_changed" | "flag_off";
+
+export class LiveBodyConversionError extends Error {
+  constructor(
+    readonly code: LiveBodyConversionErrorCode,
+    readonly documentId: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "LiveBodyConversionError";
+  }
+}
+
+// A typing session sends a commit every few hundred milliseconds. History
+// keeps one row per this interval, and each commit inside it updates that
+// row, so a session's last row always holds its final state. A row changes
+// only within the interval after it was created.
+const LIVE_COPY_HISTORY_INTERVAL_MS = 2_000;
+
+const pageColumns = {
+  id: schema.documents.id,
+  title: schema.documents.title,
+  content: schema.documents.content,
+  bodyRevision: schema.documents.bodyRevision,
+  collabBodyRevision: schema.documents.collabBodyRevision,
+  liveBodySwitchedAt: schema.documents.liveBodySwitchedAt,
+  liveCopyVersion: schema.documents.liveCopyVersion,
+  ownerEmail: schema.documents.ownerEmail,
+  orgId: schema.documents.orgId,
+  updatedAt: schema.documents.updatedAt,
+  trashedAt: schema.documents.trashedAt,
+  sourceMode: schema.documents.sourceMode,
+  sourceRootPath: schema.documents.sourceRootPath,
+  sourcePath: schema.documents.sourcePath,
+};
+
+export type PageRow = {
+  id: string;
+  title: string;
+  content: string;
+  bodyRevision: number;
+  collabBodyRevision: number | null;
+  liveBodySwitchedAt: string | null;
+  liveCopyVersion: number | null;
+  ownerEmail: string;
+  orgId: string | null;
+  updatedAt: string;
+  trashedAt: string | null;
+  sourceMode: string | null;
+  sourceRootPath: string | null;
+  sourcePath: string | null;
+};
+
+type BlocksFields = Awaited<ReturnType<typeof lockPrimaryBlocksFields>>;
+
+export interface LockedPage {
+  page: PageRow;
+  blocksFields: BlocksFields;
+  lockedDatabaseIds: ReadonlySet<string>;
+  lockedMembershipIds: ReadonlySet<string>;
+}
+
+function scopeChanged(message: string): never {
+  throw new ActionContractError(message, {
+    errorCode: "DOCUMENT_METADATA_SCOPE_CHANGED",
+    statusCode: 409,
+  });
+}
+
+/**
+ * Locks a page for a body write in Content's row-lock order: the collection
+ * it backs and the inline collections it owns, in one id-ordered pass; then
+ * its memberships; then the page row. Core takes `_collab_docs` after all of
+ * them. Undefined when the page does not exist.
+ */
+async function lockPageForBodyWrite(
+  db: ContentDb,
+  documentId: string,
+): Promise<LockedPage | undefined> {
+  // guard:allow-unscoped — reads the owner of a page whose write the collab route or the calling action already authorized.
+  const [owner] = await db
+    .select({ ownerEmail: schema.documents.ownerEmail })
+    .from(schema.documents)
+    .where(eq(schema.documents.id, documentId));
+  if (!owner) return undefined;
+  const databases = await db
+    .select({
+      id: schema.contentDatabases.id,
+      documentId: schema.contentDatabases.documentId,
+    })
+    .from(schema.contentDatabases)
+    .innerJoin(
+      schema.documents,
+      eq(schema.documents.id, schema.contentDatabases.documentId),
+    )
+    .where(
+      or(
+        and(
+          eq(schema.documents.id, documentId),
+          eq(schema.documents.ownerEmail, owner.ownerEmail),
+        ),
+        and(
+          eq(schema.contentDatabases.ownerDocumentId, documentId),
+          eq(schema.contentDatabases.ownerEmail, owner.ownerEmail),
+          isNull(schema.contentDatabases.deletedAt),
+        ),
+      ),
+    )
+    .orderBy(sql`${schema.contentDatabases.id} COLLATE "C"`)
+    .for("update", { of: schema.contentDatabases });
+  if (databases.filter((row) => row.documentId === documentId).length > 1) {
+    scopeChanged(
+      "The document's backing collection changed. Read the document again and retry.",
+    );
+  }
+  // Read before the lock, so a membership added in between is refused later
+  // rather than written without its lock.
+  const memberships = await pageMembershipIds(db, documentId);
+  const blocksFields = await lockPrimaryBlocksFields(db, documentId);
+  // guard:allow-unscoped — locks the page row whose owner was read above, for a write already authorized.
+  const [page] = await db
+    .select(pageColumns)
+    .from(schema.documents)
+    .where(eq(schema.documents.id, documentId))
+    .for("update");
+  if (!page) return undefined;
+  if (page.ownerEmail !== owner.ownerEmail) {
+    scopeChanged(
+      `Page ${documentId} changed owner while its body was being written. Read it again and retry.`,
+    );
+  }
+  return {
+    page: page as PageRow,
+    blocksFields,
+    lockedDatabaseIds: new Set(databases.map((row) => row.id)),
+    lockedMembershipIds: new Set(memberships),
+  };
+}
+
+async function pageMembershipIds(
+  db: ContentDb,
+  documentId: string,
+): Promise<string[]> {
+  // guard:allow-unscoped — lists the memberships of a page whose write was already authorized.
+  const rows = await db
+    .select({ id: schema.contentDatabaseItems.id })
+    .from(schema.contentDatabaseItems)
+    .where(eq(schema.contentDatabaseItems.documentId, documentId));
+  return rows.map((row) => row.id);
+}
+
+/**
+ * The blocks-field write covers the memberships locked before the page. One
+ * added since would get no write, and locking it now would take it after the
+ * page, against an edit or restore that locks memberships first.
+ */
+async function assertMembershipsLocked(
+  db: ContentDb,
+  documentId: string,
+  lockedMembershipIds: ReadonlySet<string>,
+): Promise<void> {
+  const current = await pageMembershipIds(db, documentId);
+  if (current.some((id) => !lockedMembershipIds.has(id))) {
+    scopeChanged(
+      "The document was added to a collection while it saved. Read the document again and retry.",
+    );
+  }
+}
+
+/**
+ * Refuses a server write whose page left its live copy after the write
+ * chose it. A commit persist leaves alone would put the edit in Yjs and not
+ * in SQL; the writer can take its legacy path instead.
+ */
+function writePathChanged(documentId: string, reason: string): never {
+  throw new ActionContractError(
+    `Page ${documentId} stopped taking writes through its live copy (${reason}) while this write was in flight. Read it again and retry.`,
+    {
+      errorCode: "LIVE_BODY_WRITE_PATH_CHANGED",
+      statusCode: 409,
+      details: { documentId, reason },
+    },
+  );
+}
+
+// Live-copy commits bypass update-document's mutation checks.
+function assertEditablePage(page: PageRow): void {
+  if (page.trashedAt) {
+    throw new ActionContractError("Document not found.", {
+      errorCode: "DOCUMENT_NOT_FOUND",
+      statusCode: 404,
+    });
+  }
+  assertSourceAllowsPageEdit(page);
+}
+
+/**
+ * Locks a page in Content's order, as persist locks it, for a write that runs
+ * in a live-copy transaction without a body commit: mutateLiveCopy's own
+ * `persist` on an edit that changed nothing. Pass that persist's `tx`; a
+ * `getDb()` handle is another connection, outside the commit's locks.
+ * Refuses a page in Trash; undefined when the page does not exist.
+ */
+export async function lockLiveCopyPage(
+  tx: DbExec,
+  documentId: string,
+): Promise<LockedPage | undefined> {
+  const locked = await lockPageForBodyWrite(drizzleOverExec(tx), documentId);
+  if (locked) assertEditablePage(locked.page);
+  return locked;
+}
+
+type EditorHistory =
+  | { kind: "record"; cause: DocumentHistoryCause }
+  | { kind: "update"; versionId: string };
+
+/**
+ * History for a commit no server writer caused: the editor's own updates.
+ * They join the actor's open session, one row per interval.
+ */
+async function editorHistory(
+  db: ContentDb,
+  page: PageRow,
+  documentId: string,
+  actorEmail: string | null,
+  now: string,
+): Promise<EditorHistory> {
+  const [latest] = await db
+    .select({
+      id: schema.documentVersions.id,
+      groupId: schema.documentVersions.groupId,
+      groupKind: schema.documentVersions.groupKind,
+      checkpointKind: schema.documentVersions.checkpointKind,
+      actorEmail: schema.documentVersions.actorEmail,
+      createdAt: schema.documentVersions.createdAt,
+      updatedAt: schema.documentVersions.updatedAt,
+    })
+    .from(schema.documentVersions)
+    .where(
+      and(
+        eq(schema.documentVersions.ownerEmail, page.ownerEmail),
+        eq(schema.documentVersions.documentId, documentId),
+      ),
+    )
+    .orderBy(
+      desc(schema.documentVersions.createdAt),
+      sql`case when ${schema.documentVersions.checkpointKind} = 'after' then 0 else 1 end`,
+      desc(schema.documentVersions.id),
+    )
+    .limit(1);
+  const base = {
+    actorEmail,
+    actorKind: "human" as const,
+    origin: "collab",
+    operation: "live-copy-update",
+  };
+  if (
+    latest?.groupId &&
+    latest.groupKind === "human_session" &&
+    latest.actorEmail === actorEmail &&
+    Date.parse(now) - Date.parse(latest.updatedAt ?? latest.createdAt) <
+      HISTORY_IDLE_MS
+  ) {
+    if (
+      latest.checkpointKind === "after" &&
+      Date.parse(now) - Date.parse(latest.createdAt) <
+        LIVE_COPY_HISTORY_INTERVAL_MS
+    ) {
+      return { kind: "update", versionId: latest.id };
+    }
+    return {
+      kind: "record",
+      cause: {
+        ...base,
+        groupId: latest.groupId,
+        groupKind: "human_session",
+        skipBeforeCheckpoint: true,
+      },
+    };
+  }
+  return {
+    kind: "record",
+    cause: {
+      ...base,
+      groupId: `human:${actorEmail ?? "unknown"}:${crypto.randomUUID()}`,
+      groupKind: "human_session",
+    },
+  };
+}
+
+function serverHistoryCause(
+  cause: ContentBodyWriteCause,
+  actorEmail: string | null,
+): DocumentHistoryCause {
+  return {
+    ctx: cause.ctx,
+    // Without an action context, SQL attribution takes the request's user;
+    // History must name the same actor.
+    ...(cause.ctx ? {} : { actorEmail }),
+    operation: cause.operation,
+    ...(cause.origin ? { origin: cause.origin } : {}),
+    ...(cause.historySessionId
+      ? { historySessionId: cause.historySessionId }
+      : {}),
+  };
+}
+
+async function recordBodyIntent(
+  db: ContentDb,
+  documentId: string,
+  page: PageRow,
+  record: ContentBodyIntentRecord,
+  commit: { after: string; committedRevision: number; now: string },
+): Promise<void> {
+  await recordDocumentBodyIntent({
+    db,
+    ownerEmail: page.ownerEmail,
+    orgId: page.orgId ?? "",
+    documentId,
+    intent: {
+      ...record.intent,
+      authoredBaseRevision:
+        record.intent.authoredBaseRevision ?? page.bodyRevision,
+    },
+    candidateHash: record.candidateHash ?? documentContentHash(commit.after),
+    metadataHash: record.metadataHash,
+    changedBlockIndexes:
+      record.changedBlockIndexes ??
+      changedBlocksBetween(page.content, commit.after),
+    displacedCheckpointId: record.displacedCheckpointId,
+    committedRevision: commit.committedRevision,
+    canonicalChanged: commit.after !== page.content,
+    now: commit.now,
+  });
+}
+
+/**
+ * Writes `text` as the page body with everything a body write keeps in step:
+ * revision, attribution, blocks-field identity, callout references, History,
+ * body intent and inline collections. The caller holds the page lock.
+ */
+async function writeBody(args: {
+  tx: DbExec;
+  db: ContentDb;
+  documentId: string;
+  locked: LockedPage;
+  text: string;
+  /** The `_collab_docs.version` this commit leaves stored. */
+  liveCopyVersion: number;
+  cause: ContentBodyWriteCause | undefined;
+  extraColumns?: Partial<typeof schema.documents.$inferInsert>;
+}): Promise<PersistedContentBodyCommit> {
+  const { db, documentId, text, cause } = args;
+  const { page, blocksFields, lockedDatabaseIds, lockedMembershipIds } =
+    args.locked;
+  const changed = text !== page.content;
+  if (changed) {
+    await assertMembershipsLocked(db, documentId, lockedMembershipIds);
+  }
+  const bodyRevision = page.bodyRevision + (changed ? 1 : 0);
+  const updatedAt = changed
+    ? nextDocumentUpdatedAt(page.updatedAt)
+    : page.updatedAt;
+  const actor = documentAttributionActor(cause?.ctx);
+  // guard:allow-unscoped — writes the page row this transaction locked, for a write already authorized.
+  await db
+    .update(schema.documents)
+    .set({
+      ...args.extraColumns,
+      collabBodyRevision: bodyRevision,
+      liveCopyVersion: args.liveCopyVersion,
+      ...(changed
+        ? {
+            content: text,
+            bodyRevision,
+            updatedAt,
+            ...(actor ? documentEditAttribution(actor) : {}),
+          }
+        : {}),
+    })
+    .where(eq(schema.documents.id, documentId));
+
+  let softDeletedDatabaseIds: string[] = [];
+  if (changed) {
+    for (const field of blocksFields) {
+      await persistBlocksFieldIdentity({
+        db,
+        ownerEmail: field.ownerEmail,
+        documentId,
+        propertyId: field.propertyId,
+        previousMarkdown: page.content,
+        markdown: text,
+        now: updatedAt,
+      });
+    }
+    await syncPrivateCalloutReferences(db, {
+      documentId,
+      before: page.content,
+      after: text,
+      userEmail: actor ?? page.ownerEmail,
+      ownerEmail: page.ownerEmail,
+      orgId: page.orgId,
+    });
+    const history: EditorHistory = cause
+      ? { kind: "record", cause: serverHistoryCause(cause, actor) }
+      : await editorHistory(db, page, documentId, actor, updatedAt);
+    if (history.kind === "record") {
+      await recordDocumentHistoryTransition({
+        db,
+        ownerEmail: page.ownerEmail,
+        documentId,
+        before: { title: page.title, content: page.content },
+        after: { title: page.title, content: text },
+        beforeBodyRevision: page.bodyRevision,
+        afterBodyRevision: bodyRevision,
+        cause: history.cause,
+        now: updatedAt,
+      });
+    } else {
+      await db
+        .update(schema.documentVersions)
+        .set({
+          title: page.title,
+          content: text,
+          bodyRevision,
+          updatedAt,
+        })
+        .where(
+          and(
+            eq(schema.documentVersions.id, history.versionId),
+            eq(schema.documentVersions.ownerEmail, page.ownerEmail),
+            eq(schema.documentVersions.documentId, documentId),
+          ),
+        );
+    }
+    softDeletedDatabaseIds = await reconcileInlineDatabasesForDocumentWithDb({
+      db,
+      documentId,
+      content: text,
+      ownerEmail: page.ownerEmail,
+      now: updatedAt,
+      lockedDatabaseIds,
+    });
+  }
+  if (cause?.intent) {
+    await recordBodyIntent(db, documentId, page, cause.intent, {
+      after: text,
+      committedRevision: bodyRevision,
+      now: updatedAt,
+    });
+  }
+  const persisted = {
+    before: page.content,
+    after: text,
+    bodyRevision,
+    updatedAt,
+    softDeletedDatabaseIds,
+  };
+  persistedCommits.set(args.tx, persisted);
+  return persisted;
+}
+
+/**
+ * Switches a page whose live copy now holds `text`. Runs in the transaction
+ * that committed the copy, or, when the copy already held the body, in the
+ * one core opens for the conversion's own persist.
+ */
+export async function persistLiveBodyConversion(
+  tx: DbExec,
+  conversion: LiveBodyConversion,
+  text: string,
+  liveCopyVersion: number,
+): Promise<PersistedContentBodyCommit> {
+  const db = drizzleOverExec(tx);
+  const locked = await lockPageForBodyWrite(db, conversion.documentId);
+  const page = locked?.page;
+  if (!locked || !page || page.bodyRevision !== conversion.baseRevision) {
+    throw new LiveBodyConversionError(
+      "base_changed",
+      conversion.documentId,
+      `Page ${conversion.documentId} changed while it was being switched to its live copy.`,
+    );
+  }
+  if (!(await liveBodyWriterFlagsOn(page, { transaction: tx }))) {
+    throw new LiveBodyConversionError(
+      "flag_off",
+      conversion.documentId,
+      `The live-copy writer is off for page ${conversion.documentId}'s owner.`,
+    );
+  }
+  assertEditablePage(page);
+  return writeBody({
+    tx,
+    db,
+    documentId: conversion.documentId,
+    locked,
+    text,
+    liveCopyVersion,
+    cause: currentContentBodyWriteCause(),
+    extraColumns: { liveBodySwitchedAt: new Date().toISOString() },
+  });
+}
+
+/**
+ * The binding's persist: derives the page from its live copy in the commit's
+ * transaction. It rechecks the gate under the page lock and leaves a page
+ * that went back to its legacy writer alone.
+ */
+export async function persistContentLiveCopy(
+  tx: DbExec,
+  commit: LiveCopyCommit,
+): Promise<LiveCopyPersistOutcome> {
+  const conversion = liveBodyConversionFor(commit.docId);
+  if (conversion) {
+    await persistLiveBodyConversion(
+      tx,
+      conversion,
+      commit.text,
+      commit.version,
+    );
+    return { derived: true };
+  }
+  const cause = currentContentBodyWriteCause();
+  if (!cause && commit.origin !== "update") {
+    throw new Error(
+      `A server write to page ${commit.docId}'s live copy has no cause; wrap it in withContentBodyWriteCause.`,
+    );
+  }
+  const db = drizzleOverExec(tx);
+  const locked = await lockPageForBodyWrite(db, commit.docId);
+  const gate = await liveBodyWriterGateForRow(locked?.page, {
+    transaction: tx,
+  });
+  if (!locked || gate.writePath === "legacy") {
+    const reason = gate.writePath === "legacy" ? gate.reason : "no_page";
+    if (cause) writePathChanged(commit.docId, reason);
+    // An editor update still commits, as on main. It moves the live copy
+    // past `live_copy_version`, so the gate keeps the page legacy until it
+    // is converted again.
+    return { derived: false, reason };
+  }
+  assertEditablePage(locked.page);
+  await writeBody({
+    tx,
+    db,
+    documentId: commit.docId,
+    locked,
+    text: commit.text,
+    liveCopyVersion: commit.version,
+    cause,
+  });
+  return { derived: true };
+}
+
+/**
+ * The persist an edit that changed nothing gets, which core runs in place of
+ * the binding's: it locks the page in Content's order and records the
+ * cause's intent at the current revision, as a legacy save records an
+ * accepted no-op.
+ */
+export async function persistUnchangedContentBodyEdit(
+  tx: DbExec,
+  documentId: string,
+  cause: ContentBodyWriteCause,
+): Promise<void> {
+  const db = drizzleOverExec(tx);
+  const locked = await lockPageForBodyWrite(db, documentId);
+  const gate = await liveBodyWriterGateForRow(locked?.page, {
+    transaction: tx,
+  });
+  if (!locked || gate.writePath === "legacy") {
+    writePathChanged(
+      documentId,
+      gate.writePath === "legacy" ? gate.reason : "no_page",
+    );
+  }
+  assertEditablePage(locked.page);
+  if (cause.intent) {
+    await recordBodyIntent(db, documentId, locked.page, cause.intent, {
+      after: locked.page.content,
+      committedRevision: locked.page.bodyRevision,
+      now: new Date().toISOString(),
+    });
+  }
+}