@tearleads/client-sdk 0.0.0-stage → 0.1.13

package/data/sqlite/documentAttachmentSchema.js

@@ -0,0 +1,94 @@
+import { index, integer, primaryKey, sqliteTable, text, } from "drizzle-orm/sqlite-core";
+/**
+ * Pending attachment uploads for local document changes.
+ *
+ * These rows describe attachment blobs referenced by local document mutations
+ * that have not yet been folded into the synced attachment/blob projection.
+ * Once the attachment is accepted or discarded, the pending row is removed.
+ *
+ * Columns:
+ * - `localId`: Local document id that owns the attachment slot.
+ * - `slotId`: Stable attachment slot id within the document.
+ * - `name`: User-facing attachment filename.
+ * - `mimeType`: Optional MIME type supplied for the blob.
+ * - `storageKey`: Local blob storage key for upload/readback.
+ * - `byteLength`: Blob size in bytes.
+ * - `createdAt`: Queue insertion timestamp used for ordered display.
+ *
+ * Indexes:
+ * - `(localId, slotId)` is the primary key and keeps one pending blob per
+ *   document attachment slot.
+ * - `mimeType` supports blob-browser MIME grouping and sorting.
+ */
+export const documentPendingAttachments = sqliteTable("document_pending_attachments", {
+    localId: text("local_id").notNull(),
+    slotId: text("slot_id").notNull(),
+    name: text("name").notNull(),
+    mimeType: text("mime_type"),
+    storageKey: text("storage_key").notNull(),
+    byteLength: integer("byte_length").notNull(),
+    contentSha256: text("content_sha256").notNull(),
+    createdAt: text("created_at").notNull(),
+    // Upload-resume identity, set on the first upload attempt. Reusing the blob
+    // id, content key and IV seed makes every encrypted chunk byte-identical, so
+    // the persisted multipart stage can resume instead of being orphaned. All
+    // nullable: only in-flight uploads have them, and they are dropped with the
+    // row once the upload completes.
+    uploadBlobId: text("upload_blob_id"),
+    uploadContentKey: text("upload_content_key"),
+    uploadIv: text("upload_iv"),
+    uploadContentKeyEpoch: integer("upload_content_key_epoch"),
+    uploadPartSize: integer("upload_part_size"),
+    uploadPlaintextSha256: text("upload_plaintext_sha256"),
+    uploadStageId: text("upload_stage_id"),
+}, (table) => [
+    primaryKey({ columns: [table.localId, table.slotId] }),
+    index("document_pending_attachments_mime_type_idx").on(table.mimeType),
+    index("document_pending_attachments_storage_key_idx").on(table.storageKey),
+]);
+/**
+ * Local attachment blob projection for stored documents.
+ *
+ * This table tracks the attachment blobs currently available to the client for
+ * each document slot. `blobId` is optional because the local storage key can be
+ * known before the server blob identity has been assigned or downloaded.
+ *
+ * Columns:
+ * - `localId`: Local document id that owns the attachment slot.
+ * - `slotId`: Stable attachment slot id within the document.
+ * - `blobId`: Server blob id when known.
+ * - `storageKey`: Local blob storage key for opening the attachment.
+ * - `mimeType`: Optional MIME type associated with the blob.
+ * - `byteLength`: Blob size in bytes.
+ * - `contentSha256`: Plaintext digest of the bytes held at `storageKey`. The
+ *   document content records the digest it intends for the slot; a held copy
+ *   whose digest differs is a validly signed served binding the document has
+ *   not (yet) recorded, and read models flag it rather than hide it.
+ * - `updatedAt`: Local timestamp for the attachment projection update.
+ * - `detachedAt`: Local timestamp set when the slot is unlinked from a synced
+ *   document. The row outlives the unlink because it is also the durable
+ *   "still needs a remote detach" marker (see `syncDetachedAttachments`), so
+ *   read models that answer "what references this blob" must skip detached
+ *   rows instead of waiting for the detach to flush.
+ *
+ * Indexes:
+ * - `(localId, slotId)` is the primary key and keeps one projected blob per
+ *   document attachment slot.
+ * - `mimeType` supports blob-browser MIME grouping and sorting.
+ */
+export const documentAttachmentBlobProjection = sqliteTable("document_attachment_blob_projection", {
+    localId: text("local_id").notNull(),
+    slotId: text("slot_id").notNull(),
+    blobId: text("blob_id"),
+    storageKey: text("storage_key").notNull(),
+    mimeType: text("mime_type"),
+    byteLength: integer("byte_length").notNull(),
+    contentSha256: text("content_sha256").notNull(),
+    updatedAt: text("updated_at").notNull(),
+    detachedAt: text("detached_at"),
+}, (table) => [
+    primaryKey({ columns: [table.localId, table.slotId] }),
+    index("document_attachment_blob_projection_mime_type_idx").on(table.mimeType),
+    index("document_attachment_blob_projection_storage_key_idx").on(table.storageKey),
+]);
+//# sourceMappingURL=documentAttachmentSchema.js.map

package/data/sqlite/documentAttachmentSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentAttachmentSchema.js","sourceRoot":"","sources":["documentAttachmentSchema.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,OAAO,EACP,UAAU,EACV,WAAW,EACX,IAAI,GACL,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,WAAW,CACnD,8BAA8B,EAC9B;IACE,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE;IACnC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE;IACjC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE;IAC5B,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC;IAC3B,UAAU,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC,OAAO,EAAE;IACzC,UAAU,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,OAAO,EAAE;IAC5C,aAAa,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC,OAAO,EAAE;IAC/C,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE;IACvC,4EAA4E;IAC5E,6EAA6E;IAC7E,0EAA0E;IAC1E,4EAA4E;IAC5E,iCAAiC;IACjC,YAAY,EAAE,IAAI,CAAC,gBAAgB,CAAC;IACpC,gBAAgB,EAAE,IAAI,CAAC,oBAAoB,CAAC;IAC5C,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC;IAC3B,qBAAqB,EAAE,OAAO,CAAC,0BAA0B,CAAC;IAC1D,cAAc,EAAE,OAAO,CAAC,kBAAkB,CAAC;IAC3C,qBAAqB,EAAE,IAAI,CAAC,yBAAyB,CAAC;IACtD,aAAa,EAAE,IAAI,CAAC,iBAAiB,CAAC;CACvC,EACD,CAAC,KAAK,EAAE,EAAE,CAAC;IACT,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;IACtD,KAAK,CAAC,4CAA4C,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC;IACtE,KAAK,CAAC,8CAA8C,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC;CAC3E,CACF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,WAAW,CACzD,qCAAqC,EACrC;IACE,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE;IACnC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE;IACjC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC;IACvB,UAAU,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC,OAAO,EAAE;IACzC,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC;IAC3B,UAAU,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,OAAO,EAAE;IAC5C,aAAa,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC,OAAO,EAAE;IAC/C,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE;IACvC,UAAU,EAAE,IAAI,CAAC,aAAa,CAAC;CAChC,EACD,CAAC,KAAK,EAAE,EAAE,CAAC;IACT,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;IACtD,KAAK,CAAC,mDAAmD,CAAC,CAAC,EAAE,CAC3D,KAAK,CAAC,QAAQ,CACf;IACD,KAAK,CAAC,qDAAqD,CAAC,CAAC,EAAE,CAC7D,KAAK,CAAC,UAAU,CACjB;CACF,CACF,CAAC","sourcesContent":["import {\n  index,\n  integer,\n  primaryKey,\n  sqliteTable,\n  text,\n} from \"drizzle-orm/sqlite-core\";\n\n/**\n * Pending attachment uploads for local document changes.\n *\n * These rows describe attachment blobs referenced by local document mutations\n * that have not yet been folded into the synced attachment/blob projection.\n * Once the attachment is accepted or discarded, the pending row is removed.\n *\n * Columns:\n * - `localId`: Local document id that owns the attachment slot.\n * - `slotId`: Stable attachment slot id within the document.\n * - `name`: User-facing attachment filename.\n * - `mimeType`: Optional MIME type supplied for the blob.\n * - `storageKey`: Local blob storage key for upload/readback.\n * - `byteLength`: Blob size in bytes.\n * - `createdAt`: Queue insertion timestamp used for ordered display.\n *\n * Indexes:\n * - `(localId, slotId)` is the primary key and keeps one pending blob per\n *   document attachment slot.\n * - `mimeType` supports blob-browser MIME grouping and sorting.\n */\nexport const documentPendingAttachments = sqliteTable(\n  \"document_pending_attachments\",\n  {\n    localId: text(\"local_id\").notNull(),\n    slotId: text(\"slot_id\").notNull(),\n    name: text(\"name\").notNull(),\n    mimeType: text(\"mime_type\"),\n    storageKey: text(\"storage_key\").notNull(),\n    byteLength: integer(\"byte_length\").notNull(),\n    contentSha256: text(\"content_sha256\").notNull(),\n    createdAt: text(\"created_at\").notNull(),\n    // Upload-resume identity, set on the first upload attempt. Reusing the blob\n    // id, content key and IV seed makes every encrypted chunk byte-identical, so\n    // the persisted multipart stage can resume instead of being orphaned. All\n    // nullable: only in-flight uploads have them, and they are dropped with the\n    // row once the upload completes.\n    uploadBlobId: text(\"upload_blob_id\"),\n    uploadContentKey: text(\"upload_content_key\"),\n    uploadIv: text(\"upload_iv\"),\n    uploadContentKeyEpoch: integer(\"upload_content_key_epoch\"),\n    uploadPartSize: integer(\"upload_part_size\"),\n    uploadPlaintextSha256: text(\"upload_plaintext_sha256\"),\n    uploadStageId: text(\"upload_stage_id\"),\n  },\n  (table) => [\n    primaryKey({ columns: [table.localId, table.slotId] }),\n    index(\"document_pending_attachments_mime_type_idx\").on(table.mimeType),\n    index(\"document_pending_attachments_storage_key_idx\").on(table.storageKey),\n  ],\n);\n\n/**\n * Local attachment blob projection for stored documents.\n *\n * This table tracks the attachment blobs currently available to the client for\n * each document slot. `blobId` is optional because the local storage key can be\n * known before the server blob identity has been assigned or downloaded.\n *\n * Columns:\n * - `localId`: Local document id that owns the attachment slot.\n * - `slotId`: Stable attachment slot id within the document.\n * - `blobId`: Server blob id when known.\n * - `storageKey`: Local blob storage key for opening the attachment.\n * - `mimeType`: Optional MIME type associated with the blob.\n * - `byteLength`: Blob size in bytes.\n * - `contentSha256`: Plaintext digest of the bytes held at `storageKey`. The\n *   document content records the digest it intends for the slot; a held copy\n *   whose digest differs is a validly signed served binding the document has\n *   not (yet) recorded, and read models flag it rather than hide it.\n * - `updatedAt`: Local timestamp for the attachment projection update.\n * - `detachedAt`: Local timestamp set when the slot is unlinked from a synced\n *   document. The row outlives the unlink because it is also the durable\n *   \"still needs a remote detach\" marker (see `syncDetachedAttachments`), so\n *   read models that answer \"what references this blob\" must skip detached\n *   rows instead of waiting for the detach to flush.\n *\n * Indexes:\n * - `(localId, slotId)` is the primary key and keeps one projected blob per\n *   document attachment slot.\n * - `mimeType` supports blob-browser MIME grouping and sorting.\n */\nexport const documentAttachmentBlobProjection = sqliteTable(\n  \"document_attachment_blob_projection\",\n  {\n    localId: text(\"local_id\").notNull(),\n    slotId: text(\"slot_id\").notNull(),\n    blobId: text(\"blob_id\"),\n    storageKey: text(\"storage_key\").notNull(),\n    mimeType: text(\"mime_type\"),\n    byteLength: integer(\"byte_length\").notNull(),\n    contentSha256: text(\"content_sha256\").notNull(),\n    updatedAt: text(\"updated_at\").notNull(),\n    detachedAt: text(\"detached_at\"),\n  },\n  (table) => [\n    primaryKey({ columns: [table.localId, table.slotId] }),\n    index(\"document_attachment_blob_projection_mime_type_idx\").on(\n      table.mimeType,\n    ),\n    index(\"document_attachment_blob_projection_storage_key_idx\").on(\n      table.storageKey,\n    ),\n  ],\n);\n"]}

package/data/sqlite/documentDiscoveryEvidenceSchema.js

@@ -0,0 +1,28 @@
+import { integer, primaryKey, sqliteTable, text, } from "drizzle-orm/sqlite-core";
+/** Untrusted listing candidates retained until signed placement can be checked. */
+export const pendingDocumentDiscoveries = sqliteTable("pending_document_discoveries", {
+    containerId: text("container_id").notNull(),
+    documentId: text("document_id").notNull(),
+    accessEpoch: integer("access_epoch").notNull(),
+    generation: integer("generation").notNull(),
+    inputJson: text("input_json").notNull(),
+    retryAt: integer("retry_at").notNull().default(0),
+    attempts: integer("attempts").notNull().default(0),
+}, (table) => [primaryKey({ columns: [table.containerId, table.documentId] })]);
+/** Only the verified signed head writes this cache, never listing fields. */
+export const documentDiscoveryHeads = sqliteTable("document_discovery_heads", {
+    documentId: text("document_id").notNull(),
+    organizationId: text("organization_id").notNull(),
+    manifestHash: text("manifest_hash").notNull(),
+    accessEpoch: integer("access_epoch").notNull(),
+    linksJson: text("links_json").notNull(),
+}, (table) => [
+    primaryKey({ columns: [table.documentId, table.organizationId] }),
+]);
+/** Local request order, independent of untrusted server epoch claims. */
+export const documentDiscoverySequence = sqliteTable("document_discovery_sequence", {
+    id: text("id").primaryKey(),
+    generation: integer("generation").notNull(),
+    invalidatedThrough: integer("invalidated_through").notNull().default(0),
+});
+//# sourceMappingURL=documentDiscoveryEvidenceSchema.js.map

package/data/sqlite/documentDiscoveryEvidenceSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentDiscoveryEvidenceSchema.js","sourceRoot":"","sources":["documentDiscoveryEvidenceSchema.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,UAAU,EACV,WAAW,EACX,IAAI,GACL,MAAM,yBAAyB,CAAC;AAEjC,mFAAmF;AACnF,MAAM,CAAC,MAAM,0BAA0B,GAAG,WAAW,CACnD,8BAA8B,EAC9B;IACE,WAAW,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC,OAAO,EAAE;IAC3C,UAAU,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC,OAAO,EAAE;IACzC,WAAW,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC,OAAO,EAAE;IAC9C,UAAU,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE;IAC3C,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE;IACvC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IACjD,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;CACnD,EACD,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAC5E,CAAC;AAEF,6EAA6E;AAC7E,MAAM,CAAC,MAAM,sBAAsB,GAAG,WAAW,CAC/C,0BAA0B,EAC1B;IACE,UAAU,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC,OAAO,EAAE;IACzC,cAAc,EAAE,IAAI,CAAC,iBAAiB,CAAC,CAAC,OAAO,EAAE;IACjD,YAAY,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC,OAAO,EAAE;IAC7C,WAAW,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC,OAAO,EAAE;IAC9C,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE;CACxC,EACD,CAAC,KAAK,EAAE,EAAE,CAAC;IACT,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,cAAc,CAAC,EAAE,CAAC;CAClE,CACF,CAAC;AAEF,yEAAyE;AACzE,MAAM,CAAC,MAAM,yBAAyB,GAAG,WAAW,CAClD,6BAA6B,EAC7B;IACE,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE;IAC3B,UAAU,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE;IAC3C,kBAAkB,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;CACxE,CACF,CAAC","sourcesContent":["import {\n  integer,\n  primaryKey,\n  sqliteTable,\n  text,\n} from \"drizzle-orm/sqlite-core\";\n\n/** Untrusted listing candidates retained until signed placement can be checked. */\nexport const pendingDocumentDiscoveries = sqliteTable(\n  \"pending_document_discoveries\",\n  {\n    containerId: text(\"container_id\").notNull(),\n    documentId: text(\"document_id\").notNull(),\n    accessEpoch: integer(\"access_epoch\").notNull(),\n    generation: integer(\"generation\").notNull(),\n    inputJson: text(\"input_json\").notNull(),\n    retryAt: integer(\"retry_at\").notNull().default(0),\n    attempts: integer(\"attempts\").notNull().default(0),\n  },\n  (table) => [primaryKey({ columns: [table.containerId, table.documentId] })],\n);\n\n/** Only the verified signed head writes this cache, never listing fields. */\nexport const documentDiscoveryHeads = sqliteTable(\n  \"document_discovery_heads\",\n  {\n    documentId: text(\"document_id\").notNull(),\n    organizationId: text(\"organization_id\").notNull(),\n    manifestHash: text(\"manifest_hash\").notNull(),\n    accessEpoch: integer(\"access_epoch\").notNull(),\n    linksJson: text(\"links_json\").notNull(),\n  },\n  (table) => [\n    primaryKey({ columns: [table.documentId, table.organizationId] }),\n  ],\n);\n\n/** Local request order, independent of untrusted server epoch claims. */\nexport const documentDiscoverySequence = sqliteTable(\n  \"document_discovery_sequence\",\n  {\n    id: text(\"id\").primaryKey(),\n    generation: integer(\"generation\").notNull(),\n    invalidatedThrough: integer(\"invalidated_through\").notNull().default(0),\n  },\n);\n"]}

package/data/sqlite/documentHistoryPersistence.d.ts

@@ -0,0 +1,80 @@
+import type { DocumentScope } from "./documentPersistenceTypes.js";
+import { type ExecSql } from "./sqlSchema.js";
+/**
+ * Compaction thresholds: once the tail carries this many rows or bytes, the
+ * next persist of a full-history-capable document exports a fresh checkpoint
+ * and clears the tail. Small enough to keep restore replay short, large
+ * enough that a full-history export (O(history)) happens once per burst of
+ * edits instead of per keystroke.
+ */
+export declare const DOCUMENT_HISTORY_COMPACTION_MAX_ROWS = 200;
+export declare const DOCUMENT_HISTORY_COMPACTION_MAX_BYTES: number;
+/**
+ * Row provenance: "local" for updates authored on this device, "remote" for
+ * decrypted pulled updates. Restores advance the outgoing-delta marker across
+ * remote rows (already server-side); local rows never advance it.
+ */
+type DocumentHistoryUpdateOrigin = "local" | "remote";
+interface DocumentHistoryTailUpdate {
+    readonly origin: DocumentHistoryUpdateOrigin;
+    readonly updateData: string;
+}
+interface DocumentHistoryRestoreState {
+    readonly snapshot: string;
+    readonly tailUpdates: readonly DocumentHistoryTailUpdate[];
+}
+export declare function appendDocumentHistoryUpdates(execSql: ExecSql, scope: DocumentScope, updates: readonly string[], origin: DocumentHistoryUpdateOrigin): Promise<void>;
+/**
+ * The checkpoint + ordered tail for a scope, or null when NEITHER exists (a
+ * discovered shell that has not hydrated content yet; the caller starts the
+ * document empty and the remote pull supplies the content). A tail WITHOUT a
+ * checkpoint — a crash between the first enqueued edit's tail append and the
+ * birth-checkpoint seed — restores as tail-only (`snapshot: ""`): those tail
+ * rows can be the only durable copy of a local edit, so they must never be
+ * silently ignored.
+ */
+export declare function loadDocumentHistoryRestoreState(execSql: ExecSql, scope: DocumentScope): Promise<DocumentHistoryRestoreState | null>;
+export declare function readDocumentHistoryTailSize(execSql: ExecSql, scope: DocumentScope): Promise<{
+    byteLength: number;
+    hasCheckpoint: boolean;
+    rowCount: number;
+}>;
+interface DocumentHistoryTailEntry {
+    readonly id: string;
+    readonly updateData: string;
+}
+/**
+ * The current tail rows WITH their payloads, so a compactor can prove each
+ * row's ops are covered by the snapshot it is about to install (another
+ * pane's append may carry ops this pane's document has not merged yet).
+ */
+export declare function listDocumentHistoryTailEntries(execSql: ExecSql, scope: DocumentScope): Promise<DocumentHistoryTailEntry[]>;
+/**
+ * Replace the scope's checkpoint with a fresh full-history snapshot and
+ * delete ONLY the tail rows the caller captured before exporting it. Every
+ * append path writes its tail row after the ops are already in the live
+ * document, so any row captured before the export is provably covered by
+ * the snapshot — while a row appended concurrently (between export and this
+ * delete) survives for the next compaction instead of being lost.
+ */
+export declare function replaceDocumentHistoryCheckpoint(execSql: ExecSql, scope: DocumentScope, input: {
+    coveredTailIds: readonly string[];
+    endVersionVector: string;
+    /**
+     * Skip the monotonic version gate. Only for document CREATION, where any
+     * existing checkpoint under this localId is the orphan of a failed prior
+     * attempt (checkpoint written, record row never committed) — a retry's
+     * fresh document need not dominate that orphan to replace it.
+     */
+    force?: boolean;
+    snapshot: string;
+    /**
+     * Re-checked after acquiring the serialized mutation slot (like the
+     * record-save path): a store reset/recreation that happened while this
+     * call waited in the queue must abort the write, or a stale compactor
+     * could install the OLD document's checkpoint over the new identity's.
+     */
+    stillCurrent?: () => boolean;
+}): Promise<boolean>;
+export declare function deleteDocumentHistory(execSql: ExecSql, scope: DocumentScope): Promise<void>;
+export {};

package/data/sqlite/documentHistoryPersistence.js

@@ -0,0 +1,281 @@
+import { base64ToBytes } from "../../internal/encoding/index.js";
+import { createDocument, exportFullHistoryIdentity, importSnapshot, satisfiesVersionVector, } from "../../internal/loro/index.js";
+import { and, eq, inArray, sql } from "drizzle-orm";
+import { documentHistoryCheckpoints, documentHistoryUpdates, documentTables, } from "./schema.js";
+import { getClientSQLitePersistenceRuntime } from "./sqlitePersistenceRuntime.js";
+import { ensureSqlTables } from "./sqlSchema.js";
+/**
+ * Compaction thresholds: once the tail carries this many rows or bytes, the
+ * next persist of a full-history-capable document exports a fresh checkpoint
+ * and clears the tail. Small enough to keep restore replay short, large
+ * enough that a full-history export (O(history)) happens once per burst of
+ * edits instead of per keystroke.
+ */
+export const DOCUMENT_HISTORY_COMPACTION_MAX_ROWS = 200;
+export const DOCUMENT_HISTORY_COMPACTION_MAX_BYTES = 512 * 1024;
+export async function appendDocumentHistoryUpdates(execSql, scope, updates, origin) {
+    if (updates.length === 0) {
+        return;
+    }
+    await ensureSqlTables(execSql, documentTables);
+    const createdAt = new Date().toISOString();
+    await getClientSQLitePersistenceRuntime(execSql).runMutation(async (db) => {
+        // Chunked: a catch-up pull can carry thousands of updates, and a single
+        // multi-row insert would exceed SQLite's bound-variable limit.
+        for (let index = 0; index < updates.length; index += HISTORY_ROW_CHUNK) {
+            await db.insert(documentHistoryUpdates).values(updates.slice(index, index + HISTORY_ROW_CHUNK).map((updateData) => ({
+                id: crypto.randomUUID(),
+                appKind: scope.appKind,
+                localId: scope.localId,
+                updateData,
+                origin,
+                createdAt,
+            })));
+        }
+    });
+}
+/**
+ * The checkpoint + ordered tail for a scope, or null when NEITHER exists (a
+ * discovered shell that has not hydrated content yet; the caller starts the
+ * document empty and the remote pull supplies the content). A tail WITHOUT a
+ * checkpoint — a crash between the first enqueued edit's tail append and the
+ * birth-checkpoint seed — restores as tail-only (`snapshot: ""`): those tail
+ * rows can be the only durable copy of a local edit, so they must never be
+ * silently ignored.
+ */
+export async function loadDocumentHistoryRestoreState(execSql, scope) {
+    await ensureSqlTables(execSql, documentTables);
+    const { db } = getClientSQLitePersistenceRuntime(execSql);
+    // Read the TAIL before the (full) checkpoint: if another pane compacts
+    // between the two reads, this order yields old-tail + new-checkpoint — a
+    // safe superset (the new checkpoint subsumes the old tail, and replay is
+    // idempotent by op identity). The reverse order could yield old-checkpoint
+    // + already-emptied tail, a torn read that silently drops the compacted
+    // ops for the whole session.
+    const tail = await db
+        .select({
+        id: documentHistoryUpdates.id,
+        origin: documentHistoryUpdates.origin,
+        updateData: documentHistoryUpdates.updateData,
+    })
+        .from(documentHistoryUpdates)
+        .where(and(eq(documentHistoryUpdates.appKind, scope.appKind), eq(documentHistoryUpdates.localId, scope.localId)))
+        // Insertion order: same-millisecond appends make createdAt tie and a
+        // random-uuid tiebreak would replay out of order. importUpdates tolerates
+        // out-of-order batches, but replay should still be deterministic.
+        .orderBy(sql `rowid`);
+    const [checkpoint] = await db
+        .select({ snapshot: documentHistoryCheckpoints.snapshot })
+        .from(documentHistoryCheckpoints)
+        .where(and(eq(documentHistoryCheckpoints.appKind, scope.appKind), eq(documentHistoryCheckpoints.localId, scope.localId)))
+        .limit(1);
+    if (!checkpoint && tail.length === 0) {
+        return null;
+    }
+    return {
+        snapshot: checkpoint?.snapshot ?? "",
+        tailUpdates: tail.map((row) => ({
+            // Fail toward re-sending: an unrecognized origin never advances the
+            // marker, which is the recoverable direction (a redundant re-submit
+            // is idempotent; a skipped local op would be orphaned from sync).
+            origin: row.origin === "remote" ? "remote" : "local",
+            updateData: row.updateData,
+        })),
+    };
+}
+export async function readDocumentHistoryTailSize(execSql, scope) {
+    await ensureSqlTables(execSql, documentTables);
+    const { db } = getClientSQLitePersistenceRuntime(execSql);
+    const [totals] = await db
+        .select({
+        byteLength: sql `coalesce(sum(length(${documentHistoryUpdates.updateData})), 0)`,
+        rowCount: sql `count(*)`,
+    })
+        .from(documentHistoryUpdates)
+        .where(and(eq(documentHistoryUpdates.appKind, scope.appKind), eq(documentHistoryUpdates.localId, scope.localId)));
+    const [checkpoint] = await db
+        .select({ localId: documentHistoryCheckpoints.localId })
+        .from(documentHistoryCheckpoints)
+        .where(and(eq(documentHistoryCheckpoints.appKind, scope.appKind), eq(documentHistoryCheckpoints.localId, scope.localId)))
+        .limit(1);
+    return {
+        byteLength: Number(totals?.byteLength ?? 0),
+        hasCheckpoint: checkpoint !== undefined,
+        rowCount: Number(totals?.rowCount ?? 0),
+    };
+}
+/**
+ * The current tail rows WITH their payloads, so a compactor can prove each
+ * row's ops are covered by the snapshot it is about to install (another
+ * pane's append may carry ops this pane's document has not merged yet).
+ */
+export async function listDocumentHistoryTailEntries(execSql, scope) {
+    await ensureSqlTables(execSql, documentTables);
+    const { db } = getClientSQLitePersistenceRuntime(execSql);
+    const rows = await db
+        .select({
+        id: documentHistoryUpdates.id,
+        updateData: documentHistoryUpdates.updateData,
+    })
+        .from(documentHistoryUpdates)
+        .where(and(eq(documentHistoryUpdates.appKind, scope.appKind), eq(documentHistoryUpdates.localId, scope.localId)));
+    return rows.flatMap((row) => row.id === null ? [] : [{ id: row.id, updateData: row.updateData }]);
+}
+const HISTORY_ROW_CHUNK = 400;
+/**
+ * Replace the scope's checkpoint with a fresh full-history snapshot and
+ * delete ONLY the tail rows the caller captured before exporting it. Every
+ * append path writes its tail row after the ops are already in the live
+ * document, so any row captured before the export is provably covered by
+ * the snapshot — while a row appended concurrently (between export and this
+ * delete) survives for the next compaction instead of being lost.
+ */
+export async function replaceDocumentHistoryCheckpoint(execSql, scope, input) {
+    await ensureSqlTables(execSql, documentTables);
+    // Sequential (non-transactional) so callers already inside a transaction
+    // can nest this. Crash between the statements leaves the new checkpoint
+    // plus covered tail rows — a safe superset, since tail replay is
+    // idempotent by op identity. The replacement itself is a compare-and-swap
+    // on the stored revision, so the version gate cannot be bypassed by a
+    // concurrent compactor between the read and the write: whoever loses the
+    // CAS re-reads and re-evaluates the gate against the winner's checkpoint.
+    return getClientSQLitePersistenceRuntime(execSql).runMutation(async (tx) => {
+        if (input.stillCurrent?.() === false) {
+            return false;
+        }
+        for (let attempt = 0; attempt < CHECKPOINT_CAS_ATTEMPTS; attempt += 1) {
+            let replaced;
+            try {
+                replaced = await tryReplaceCheckpointOnce(tx, scope, input);
+            }
+            catch (error) {
+                if (error instanceof CheckpointGateRejected) {
+                    // A fresher checkpoint dominates this candidate: no write, and
+                    // the caller's covered rows must stay for the covering pane.
+                    return false;
+                }
+                throw error;
+            }
+            if (!replaced) {
+                // CAS lost to a concurrent writer — re-read and re-evaluate the
+                // gate against the winner's checkpoint.
+                continue;
+            }
+            for (let index = 0; index < input.coveredTailIds.length; index += HISTORY_ROW_CHUNK) {
+                await tx
+                    .delete(documentHistoryUpdates)
+                    .where(and(eq(documentHistoryUpdates.appKind, scope.appKind), eq(documentHistoryUpdates.localId, scope.localId), inArray(documentHistoryUpdates.id, input.coveredTailIds.slice(index, index + HISTORY_ROW_CHUNK))));
+            }
+            return true;
+        }
+        // Exhaustion must not read as durable success: creation and rebuild
+        // callers persist record rows assuming the checkpoint landed.
+        throw new Error("Document history checkpoint replacement lost every CAS attempt");
+    });
+}
+const CHECKPOINT_CAS_ATTEMPTS = 16;
+/**
+ * One compare-and-swap attempt. Returns true when this caller's checkpoint
+ * became the stored one, false when a concurrent writer won the CAS (the
+ * caller re-reads and retries), and throws CheckpointGateRejected when a
+ * fresher stored checkpoint dominates the candidate.
+ */
+async function tryReplaceCheckpointOnce(tx, scope, input) {
+    const updatedAt = new Date().toISOString();
+    const revision = crypto.randomUUID();
+    const [stored] = await tx
+        .select({
+        endVersionVector: documentHistoryCheckpoints.endVersionVector,
+        revision: documentHistoryCheckpoints.revision,
+        snapshot: documentHistoryCheckpoints.snapshot,
+    })
+        .from(documentHistoryCheckpoints)
+        .where(and(eq(documentHistoryCheckpoints.appKind, scope.appKind), eq(documentHistoryCheckpoints.localId, scope.localId)))
+        .limit(1);
+    if (!stored) {
+        const inserted = await tx
+            .insert(documentHistoryCheckpoints)
+            .values({
+            appKind: scope.appKind,
+            localId: scope.localId,
+            snapshot: input.snapshot,
+            endVersionVector: input.endVersionVector,
+            revision,
+            updatedAt,
+        })
+            .onConflictDoNothing({
+            target: [
+                documentHistoryCheckpoints.appKind,
+                documentHistoryCheckpoints.localId,
+            ],
+        })
+            .returning({ localId: documentHistoryCheckpoints.localId });
+        // Conflict means a concurrent writer inserted first — retry the gate.
+        return inserted.length > 0;
+    }
+    // A stale compactor (a pane whose document has not merged another pane's
+    // ops) must never replace a checkpoint it does not cover: the covered
+    // pane may already have deleted its tail rows, so regressing the
+    // checkpoint would leave those ops with no durable copy at all. Vector
+    // dominance proves counter coverage; the retained-prefix identity also
+    // proves the candidate carries the exact stored operations at those
+    // counters rather than a same-frontier fork.
+    if (input.force !== true) {
+        if (!satisfiesVersionVector(input.endVersionVector, stored.endVersionVector)) {
+            throw new CheckpointGateRejected();
+        }
+        if (input.snapshot !== stored.snapshot &&
+            !(await candidateContainsStoredCheckpointHistory({
+                candidateSnapshot: input.snapshot,
+                storedEndVersion: stored.endVersionVector,
+                storedSnapshot: stored.snapshot,
+            }))) {
+            throw new CheckpointGateRejected();
+        }
+    }
+    const replaced = await tx
+        .update(documentHistoryCheckpoints)
+        .set({
+        snapshot: input.snapshot,
+        endVersionVector: input.endVersionVector,
+        revision,
+        updatedAt,
+    })
+        .where(and(eq(documentHistoryCheckpoints.appKind, scope.appKind), eq(documentHistoryCheckpoints.localId, scope.localId), eq(documentHistoryCheckpoints.revision, stored.revision)))
+        .returning({ localId: documentHistoryCheckpoints.localId });
+    return replaced.length > 0;
+}
+async function candidateContainsStoredCheckpointHistory(input) {
+    const [candidateDocument, storedDocument] = await Promise.all([
+        createDocument("checkpoint-candidate-history-gate"),
+        createDocument("checkpoint-stored-history-gate"),
+    ]);
+    try {
+        importSnapshot(candidateDocument, base64ToBytes(input.candidateSnapshot));
+        importSnapshot(storedDocument, base64ToBytes(input.storedSnapshot));
+        return (exportFullHistoryIdentity(candidateDocument, input.storedEndVersion) ===
+            exportFullHistoryIdentity(storedDocument));
+    }
+    finally {
+        candidateDocument.free();
+        storedDocument.free();
+    }
+}
+class CheckpointGateRejected extends Error {
+    constructor() {
+        super("checkpoint gate rejected");
+        this.name = "CheckpointGateRejected";
+    }
+}
+export async function deleteDocumentHistory(execSql, scope) {
+    await ensureSqlTables(execSql, documentTables);
+    await getClientSQLitePersistenceRuntime(execSql).runMutation(async (tx) => {
+        await tx
+            .delete(documentHistoryCheckpoints)
+            .where(and(eq(documentHistoryCheckpoints.appKind, scope.appKind), eq(documentHistoryCheckpoints.localId, scope.localId)));
+        await tx
+            .delete(documentHistoryUpdates)
+            .where(and(eq(documentHistoryUpdates.appKind, scope.appKind), eq(documentHistoryUpdates.localId, scope.localId)));
+    });
+}
+//# sourceMappingURL=documentHistoryPersistence.js.map

package/data/sqlite/documentHistoryPersistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentHistoryPersistence.js","sourceRoot":"","sources":["documentHistoryPersistence.ts"],"names":[],"mappings":"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","sourcesContent":["import { base64ToBytes } from \"@tearleads/encoding\";\nimport {\n  createDocument,\n  exportFullHistoryIdentity,\n  importSnapshot,\n  satisfiesVersionVector,\n} from \"@tearleads/loro\";\nimport { and, eq, inArray, sql } from \"drizzle-orm\";\nimport type { DocumentScope } from \"./documentPersistenceTypes\";\nimport {\n  documentHistoryCheckpoints,\n  documentHistoryUpdates,\n  documentTables,\n} from \"./schema\";\nimport { getClientSQLitePersistenceRuntime } from \"./sqlitePersistenceRuntime\";\nimport { type ExecSql, ensureSqlTables } from \"./sqlSchema\";\n\n/**\n * Compaction thresholds: once the tail carries this many rows or bytes, the\n * next persist of a full-history-capable document exports a fresh checkpoint\n * and clears the tail. Small enough to keep restore replay short, large\n * enough that a full-history export (O(history)) happens once per burst of\n * edits instead of per keystroke.\n */\nexport const DOCUMENT_HISTORY_COMPACTION_MAX_ROWS = 200;\nexport const DOCUMENT_HISTORY_COMPACTION_MAX_BYTES = 512 * 1024;\n\n/**\n * Row provenance: \"local\" for updates authored on this device, \"remote\" for\n * decrypted pulled updates. Restores advance the outgoing-delta marker across\n * remote rows (already server-side); local rows never advance it.\n */\ntype DocumentHistoryUpdateOrigin = \"local\" | \"remote\";\n\ninterface DocumentHistoryTailUpdate {\n  readonly origin: DocumentHistoryUpdateOrigin;\n  readonly updateData: string;\n}\n\ninterface DocumentHistoryRestoreState {\n  readonly snapshot: string;\n  readonly tailUpdates: readonly DocumentHistoryTailUpdate[];\n}\n\nexport async function appendDocumentHistoryUpdates(\n  execSql: ExecSql,\n  scope: DocumentScope,\n  updates: readonly string[],\n  origin: DocumentHistoryUpdateOrigin,\n): Promise<void> {\n  if (updates.length === 0) {\n    return;\n  }\n  await ensureSqlTables(execSql, documentTables);\n  const createdAt = new Date().toISOString();\n  await getClientSQLitePersistenceRuntime(execSql).runMutation(async (db) => {\n    // Chunked: a catch-up pull can carry thousands of updates, and a single\n    // multi-row insert would exceed SQLite's bound-variable limit.\n    for (let index = 0; index < updates.length; index += HISTORY_ROW_CHUNK) {\n      await db.insert(documentHistoryUpdates).values(\n        updates.slice(index, index + HISTORY_ROW_CHUNK).map((updateData) => ({\n          id: crypto.randomUUID(),\n          appKind: scope.appKind,\n          localId: scope.localId,\n          updateData,\n          origin,\n          createdAt,\n        })),\n      );\n    }\n  });\n}\n\n/**\n * The checkpoint + ordered tail for a scope, or null when NEITHER exists (a\n * discovered shell that has not hydrated content yet; the caller starts the\n * document empty and the remote pull supplies the content). A tail WITHOUT a\n * checkpoint — a crash between the first enqueued edit's tail append and the\n * birth-checkpoint seed — restores as tail-only (`snapshot: \"\"`): those tail\n * rows can be the only durable copy of a local edit, so they must never be\n * silently ignored.\n */\nexport async function loadDocumentHistoryRestoreState(\n  execSql: ExecSql,\n  scope: DocumentScope,\n): Promise<DocumentHistoryRestoreState | null> {\n  await ensureSqlTables(execSql, documentTables);\n  const { db } = getClientSQLitePersistenceRuntime(execSql);\n  // Read the TAIL before the (full) checkpoint: if another pane compacts\n  // between the two reads, this order yields old-tail + new-checkpoint — a\n  // safe superset (the new checkpoint subsumes the old tail, and replay is\n  // idempotent by op identity). The reverse order could yield old-checkpoint\n  // + already-emptied tail, a torn read that silently drops the compacted\n  // ops for the whole session.\n  const tail = await db\n    .select({\n      id: documentHistoryUpdates.id,\n      origin: documentHistoryUpdates.origin,\n      updateData: documentHistoryUpdates.updateData,\n    })\n    .from(documentHistoryUpdates)\n    .where(\n      and(\n        eq(documentHistoryUpdates.appKind, scope.appKind),\n        eq(documentHistoryUpdates.localId, scope.localId),\n      ),\n    )\n    // Insertion order: same-millisecond appends make createdAt tie and a\n    // random-uuid tiebreak would replay out of order. importUpdates tolerates\n    // out-of-order batches, but replay should still be deterministic.\n    .orderBy(sql`rowid`);\n\n  const [checkpoint] = await db\n    .select({ snapshot: documentHistoryCheckpoints.snapshot })\n    .from(documentHistoryCheckpoints)\n    .where(\n      and(\n        eq(documentHistoryCheckpoints.appKind, scope.appKind),\n        eq(documentHistoryCheckpoints.localId, scope.localId),\n      ),\n    )\n    .limit(1);\n  if (!checkpoint && tail.length === 0) {\n    return null;\n  }\n\n  return {\n    snapshot: checkpoint?.snapshot ?? \"\",\n    tailUpdates: tail.map((row) => ({\n      // Fail toward re-sending: an unrecognized origin never advances the\n      // marker, which is the recoverable direction (a redundant re-submit\n      // is idempotent; a skipped local op would be orphaned from sync).\n      origin:\n        row.origin === \"remote\" ? (\"remote\" as const) : (\"local\" as const),\n      updateData: row.updateData,\n    })),\n  };\n}\n\nexport async function readDocumentHistoryTailSize(\n  execSql: ExecSql,\n  scope: DocumentScope,\n): Promise<{ byteLength: number; hasCheckpoint: boolean; rowCount: number }> {\n  await ensureSqlTables(execSql, documentTables);\n  const { db } = getClientSQLitePersistenceRuntime(execSql);\n  const [totals] = await db\n    .select({\n      byteLength: sql<number>`coalesce(sum(length(${documentHistoryUpdates.updateData})), 0)`,\n      rowCount: sql<number>`count(*)`,\n    })\n    .from(documentHistoryUpdates)\n    .where(\n      and(\n        eq(documentHistoryUpdates.appKind, scope.appKind),\n        eq(documentHistoryUpdates.localId, scope.localId),\n      ),\n    );\n  const [checkpoint] = await db\n    .select({ localId: documentHistoryCheckpoints.localId })\n    .from(documentHistoryCheckpoints)\n    .where(\n      and(\n        eq(documentHistoryCheckpoints.appKind, scope.appKind),\n        eq(documentHistoryCheckpoints.localId, scope.localId),\n      ),\n    )\n    .limit(1);\n  return {\n    byteLength: Number(totals?.byteLength ?? 0),\n    hasCheckpoint: checkpoint !== undefined,\n    rowCount: Number(totals?.rowCount ?? 0),\n  };\n}\n\ninterface DocumentHistoryTailEntry {\n  readonly id: string;\n  readonly updateData: string;\n}\n\n/**\n * The current tail rows WITH their payloads, so a compactor can prove each\n * row's ops are covered by the snapshot it is about to install (another\n * pane's append may carry ops this pane's document has not merged yet).\n */\nexport async function listDocumentHistoryTailEntries(\n  execSql: ExecSql,\n  scope: DocumentScope,\n): Promise<DocumentHistoryTailEntry[]> {\n  await ensureSqlTables(execSql, documentTables);\n  const { db } = getClientSQLitePersistenceRuntime(execSql);\n  const rows = await db\n    .select({\n      id: documentHistoryUpdates.id,\n      updateData: documentHistoryUpdates.updateData,\n    })\n    .from(documentHistoryUpdates)\n    .where(\n      and(\n        eq(documentHistoryUpdates.appKind, scope.appKind),\n        eq(documentHistoryUpdates.localId, scope.localId),\n      ),\n    );\n  return rows.flatMap((row) =>\n    row.id === null ? [] : [{ id: row.id, updateData: row.updateData }],\n  );\n}\n\nconst HISTORY_ROW_CHUNK = 400;\n\n/**\n * Replace the scope's checkpoint with a fresh full-history snapshot and\n * delete ONLY the tail rows the caller captured before exporting it. Every\n * append path writes its tail row after the ops are already in the live\n * document, so any row captured before the export is provably covered by\n * the snapshot — while a row appended concurrently (between export and this\n * delete) survives for the next compaction instead of being lost.\n */\nexport async function replaceDocumentHistoryCheckpoint(\n  execSql: ExecSql,\n  scope: DocumentScope,\n  input: {\n    coveredTailIds: readonly string[];\n    endVersionVector: string;\n    /**\n     * Skip the monotonic version gate. Only for document CREATION, where any\n     * existing checkpoint under this localId is the orphan of a failed prior\n     * attempt (checkpoint written, record row never committed) — a retry's\n     * fresh document need not dominate that orphan to replace it.\n     */\n    force?: boolean;\n    snapshot: string;\n    /**\n     * Re-checked after acquiring the serialized mutation slot (like the\n     * record-save path): a store reset/recreation that happened while this\n     * call waited in the queue must abort the write, or a stale compactor\n     * could install the OLD document's checkpoint over the new identity's.\n     */\n    stillCurrent?: () => boolean;\n  },\n): Promise<boolean> {\n  await ensureSqlTables(execSql, documentTables);\n  // Sequential (non-transactional) so callers already inside a transaction\n  // can nest this. Crash between the statements leaves the new checkpoint\n  // plus covered tail rows — a safe superset, since tail replay is\n  // idempotent by op identity. The replacement itself is a compare-and-swap\n  // on the stored revision, so the version gate cannot be bypassed by a\n  // concurrent compactor between the read and the write: whoever loses the\n  // CAS re-reads and re-evaluates the gate against the winner's checkpoint.\n  return getClientSQLitePersistenceRuntime(execSql).runMutation(async (tx) => {\n    if (input.stillCurrent?.() === false) {\n      return false;\n    }\n    for (let attempt = 0; attempt < CHECKPOINT_CAS_ATTEMPTS; attempt += 1) {\n      let replaced: boolean;\n      try {\n        replaced = await tryReplaceCheckpointOnce(tx, scope, input);\n      } catch (error) {\n        if (error instanceof CheckpointGateRejected) {\n          // A fresher checkpoint dominates this candidate: no write, and\n          // the caller's covered rows must stay for the covering pane.\n          return false;\n        }\n        throw error;\n      }\n      if (!replaced) {\n        // CAS lost to a concurrent writer — re-read and re-evaluate the\n        // gate against the winner's checkpoint.\n        continue;\n      }\n      for (\n        let index = 0;\n        index < input.coveredTailIds.length;\n        index += HISTORY_ROW_CHUNK\n      ) {\n        await tx\n          .delete(documentHistoryUpdates)\n          .where(\n            and(\n              eq(documentHistoryUpdates.appKind, scope.appKind),\n              eq(documentHistoryUpdates.localId, scope.localId),\n              inArray(\n                documentHistoryUpdates.id,\n                input.coveredTailIds.slice(index, index + HISTORY_ROW_CHUNK),\n              ),\n            ),\n          );\n      }\n      return true;\n    }\n    // Exhaustion must not read as durable success: creation and rebuild\n    // callers persist record rows assuming the checkpoint landed.\n    throw new Error(\n      \"Document history checkpoint replacement lost every CAS attempt\",\n    );\n  });\n}\n\nconst CHECKPOINT_CAS_ATTEMPTS = 16;\n\ntype MutationDb = Parameters<\n  Parameters<\n    ReturnType<typeof getClientSQLitePersistenceRuntime>[\"runMutation\"]\n  >[0]\n>[0];\n\n/**\n * One compare-and-swap attempt. Returns true when this caller's checkpoint\n * became the stored one, false when a concurrent writer won the CAS (the\n * caller re-reads and retries), and throws CheckpointGateRejected when a\n * fresher stored checkpoint dominates the candidate.\n */\nasync function tryReplaceCheckpointOnce(\n  tx: MutationDb,\n  scope: DocumentScope,\n  input: {\n    endVersionVector: string;\n    force?: boolean;\n    snapshot: string;\n  },\n): Promise<boolean> {\n  const updatedAt = new Date().toISOString();\n  const revision = crypto.randomUUID();\n  const [stored] = await tx\n    .select({\n      endVersionVector: documentHistoryCheckpoints.endVersionVector,\n      revision: documentHistoryCheckpoints.revision,\n      snapshot: documentHistoryCheckpoints.snapshot,\n    })\n    .from(documentHistoryCheckpoints)\n    .where(\n      and(\n        eq(documentHistoryCheckpoints.appKind, scope.appKind),\n        eq(documentHistoryCheckpoints.localId, scope.localId),\n      ),\n    )\n    .limit(1);\n\n  if (!stored) {\n    const inserted = await tx\n      .insert(documentHistoryCheckpoints)\n      .values({\n        appKind: scope.appKind,\n        localId: scope.localId,\n        snapshot: input.snapshot,\n        endVersionVector: input.endVersionVector,\n        revision,\n        updatedAt,\n      })\n      .onConflictDoNothing({\n        target: [\n          documentHistoryCheckpoints.appKind,\n          documentHistoryCheckpoints.localId,\n        ],\n      })\n      .returning({ localId: documentHistoryCheckpoints.localId });\n    // Conflict means a concurrent writer inserted first — retry the gate.\n    return inserted.length > 0;\n  }\n\n  // A stale compactor (a pane whose document has not merged another pane's\n  // ops) must never replace a checkpoint it does not cover: the covered\n  // pane may already have deleted its tail rows, so regressing the\n  // checkpoint would leave those ops with no durable copy at all. Vector\n  // dominance proves counter coverage; the retained-prefix identity also\n  // proves the candidate carries the exact stored operations at those\n  // counters rather than a same-frontier fork.\n  if (input.force !== true) {\n    if (\n      !satisfiesVersionVector(input.endVersionVector, stored.endVersionVector)\n    ) {\n      throw new CheckpointGateRejected();\n    }\n    if (\n      input.snapshot !== stored.snapshot &&\n      !(await candidateContainsStoredCheckpointHistory({\n        candidateSnapshot: input.snapshot,\n        storedEndVersion: stored.endVersionVector,\n        storedSnapshot: stored.snapshot,\n      }))\n    ) {\n      throw new CheckpointGateRejected();\n    }\n  }\n\n  const replaced = await tx\n    .update(documentHistoryCheckpoints)\n    .set({\n      snapshot: input.snapshot,\n      endVersionVector: input.endVersionVector,\n      revision,\n      updatedAt,\n    })\n    .where(\n      and(\n        eq(documentHistoryCheckpoints.appKind, scope.appKind),\n        eq(documentHistoryCheckpoints.localId, scope.localId),\n        eq(documentHistoryCheckpoints.revision, stored.revision),\n      ),\n    )\n    .returning({ localId: documentHistoryCheckpoints.localId });\n  return replaced.length > 0;\n}\n\nasync function candidateContainsStoredCheckpointHistory(input: {\n  candidateSnapshot: string;\n  storedEndVersion: string;\n  storedSnapshot: string;\n}): Promise<boolean> {\n  const [candidateDocument, storedDocument] = await Promise.all([\n    createDocument(\"checkpoint-candidate-history-gate\"),\n    createDocument(\"checkpoint-stored-history-gate\"),\n  ]);\n  try {\n    importSnapshot(candidateDocument, base64ToBytes(input.candidateSnapshot));\n    importSnapshot(storedDocument, base64ToBytes(input.storedSnapshot));\n    return (\n      exportFullHistoryIdentity(candidateDocument, input.storedEndVersion) ===\n      exportFullHistoryIdentity(storedDocument)\n    );\n  } finally {\n    candidateDocument.free();\n    storedDocument.free();\n  }\n}\n\nclass CheckpointGateRejected extends Error {\n  constructor() {\n    super(\"checkpoint gate rejected\");\n    this.name = \"CheckpointGateRejected\";\n  }\n}\n\nexport async function deleteDocumentHistory(\n  execSql: ExecSql,\n  scope: DocumentScope,\n): Promise<void> {\n  await ensureSqlTables(execSql, documentTables);\n  await getClientSQLitePersistenceRuntime(execSql).runMutation(async (tx) => {\n    await tx\n      .delete(documentHistoryCheckpoints)\n      .where(\n        and(\n          eq(documentHistoryCheckpoints.appKind, scope.appKind),\n          eq(documentHistoryCheckpoints.localId, scope.localId),\n        ),\n      );\n    await tx\n      .delete(documentHistoryUpdates)\n      .where(\n        and(\n          eq(documentHistoryUpdates.appKind, scope.appKind),\n          eq(documentHistoryUpdates.localId, scope.localId),\n        ),\n      );\n  });\n}\n"]}

package/data/sqlite/documentOrphanBlobReclaims.js

@@ -0,0 +1,6 @@
+import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { defineSqlTableSchema } from "./sqlTableSchema.js";
+/** Durable byte-reclamation queue populated before orphan attachment rows go. */
+export const documentOrphanBlobReclaims = sqliteTable("document_orphan_blob_reclaims", { storageKey: text("storage_key").primaryKey() });
+export const documentOrphanBlobReclaimTable = defineSqlTableSchema(documentOrphanBlobReclaims);
+//# sourceMappingURL=documentOrphanBlobReclaims.js.map

package/data/sqlite/documentOrphanBlobReclaims.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentOrphanBlobReclaims.js","sourceRoot":"","sources":["documentOrphanBlobReclaims.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD,iFAAiF;AACjF,MAAM,CAAC,MAAM,0BAA0B,GAAG,WAAW,CACnD,+BAA+B,EAC/B,EAAE,UAAU,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC,UAAU,EAAE,EAAE,CACjD,CAAC;AAEF,MAAM,CAAC,MAAM,8BAA8B,GAAG,oBAAoB,CAChE,0BAA0B,CAC3B,CAAC","sourcesContent":["import { sqliteTable, text } from \"drizzle-orm/sqlite-core\";\nimport { defineSqlTableSchema } from \"./sqlTableSchema\";\n\n/** Durable byte-reclamation queue populated before orphan attachment rows go. */\nexport const documentOrphanBlobReclaims = sqliteTable(\n  \"document_orphan_blob_reclaims\",\n  { storageKey: text(\"storage_key\").primaryKey() },\n);\n\nexport const documentOrphanBlobReclaimTable = defineSqlTableSchema(\n  documentOrphanBlobReclaims,\n);\n"]}

package/data/sqlite/documentPendingUpdatePersistence.d.ts

@@ -0,0 +1,56 @@
+import type { DocumentScope, PendingUpdateFields, PendingUpdateRecord } from "./documentPersistenceTypes.js";
+import type { ClientSQLiteTransactionScope } from "./sqlitePersistenceRuntime.js";
+import type { ExecSql } from "./sqlSchema.js";
+export declare function listDocumentPendingUpdates(execSql: ExecSql, scope: DocumentScope): Promise<PendingUpdateRecord[]>;
+export declare function enqueueDocumentPendingUpdate(execSql: ExecSql, scope: DocumentScope, pendingUpdate: PendingUpdateFields): Promise<string>;
+/**
+ * Enqueue an outgoing update AND append it to the durable-history tail in a
+ * single transaction. Serialization alone is not enough: a crash between
+ * separate inserts could leave the op restorable from history while missing
+ * from the outgoing queue, and a null-marker restore would then classify it
+ * as covered and never send it.
+ */
+export declare function enqueueDocumentPendingUpdateWithHistory(execSql: ExecSql, scope: DocumentScope, pendingUpdate: PendingUpdateFields, options?: {
+    expectedDocumentId: string | null;
+    expectedRecoveryGeneration: number;
+}): Promise<string | null>;
+export declare function insertDocumentPendingUpdateWithHistoryInTransaction(input: {
+    createdAt: string;
+    pendingUpdate: PendingUpdateFields;
+    scope: DocumentScope;
+    tx: ClientSQLiteTransactionScope;
+}): Promise<string>;
+/**
+ * Assign a fresh id to a pending update, keeping every other column. A lost
+ * sync ack leaves the server holding the update under the original id with
+ * ciphertext a rebuilt submission can never reproduce (each rebuild encrypts
+ * with a fresh IV), so the id is permanently poisoned: every resubmission
+ * 409s and the whole outgoing batch rolls back. Re-keying lets the next sync
+ * pass submit the same ops under a conflict-free id; the server-side copy is
+ * harmless because CRDT update import is idempotent.
+ *
+ * Returns null when no row carries the id, so callers never report progress
+ * for a row that lives in some other queue (or nowhere). The UPDATE's own
+ * RETURNING row is the progress signal — a pre-flight SELECT would race a
+ * second tab sharing the SQLite file, which can settle-delete the row between
+ * the read and the write and turn "rekeyed" into a spurious re-arm.
+ *
+ * The persisted per-row bound is enforced here as well: a row already at
+ * MAX_PENDING_UPDATE_REKEYS is left untouched and reported as no progress.
+ * The in-memory lane counter bounds a busy-loop within one session; this
+ * bound survives restarts, so a poisoned row cannot re-key forever at three
+ * passes per launch.
+ */
+export declare const MAX_PENDING_UPDATE_REKEYS = 5;
+/**
+ * Reset the durable re-key budget for every pending update in a scope. The
+ * cap exists to stop a server that keeps conflicting fresh ids from driving
+ * a network-speed loop — but a budget burned during an unrelated outage
+ * (e.g. yesterday's stale-bundle deadlock 409ing every submit) should not be
+ * terminal forever. An explicit manual retry is the deliberate, rate-limited
+ * signal that conditions changed, so it gets a fresh budget.
+ */
+export declare function resetDocumentPendingUpdateRekeyBudget(execSql: ExecSql, scope: DocumentScope): Promise<void>;
+export declare function rekeyDocumentPendingUpdate(execSql: ExecSql, id: string): Promise<string | null>;
+export declare function deleteDocumentPendingUpdate(execSql: ExecSql, id: string): Promise<void>;
+export declare function deleteDocumentPendingUpdates(execSql: ExecSql, scope: DocumentScope): Promise<void>;