@tearleads/client-sdk 0.0.0-stage → 0.1.11

package/data/documents/documentRowList.js

@@ -0,0 +1,162 @@
+import { LoroMap } from "../../internal/loro/index.js";
+// A document's repeated rows (e.g. a .env file's variables, a blood pressure
+// tracker's readings) live in one first-class Loro list — each row a nested
+// LoroMap. Storing each row as its own container makes concurrent edits to
+// different rows (or different cells of the same row) merge instead of
+// clobbering; only two writes to the same cell of the same row race, and Loro
+// resolves those last-writer-wins.
+const DOCUMENT_ROWS_LIST_KEY = "rows";
+// Reserved row-map keys are namespaced so they never collide with a document
+// type's own field names (none of which begin with "@").
+const ROW_META_PREFIX = "@";
+const ROW_ID_KEY = "@id";
+const ROW_CREATED_BY_KEY = "@createdBy";
+const ROW_CREATED_AT_KEY = "@createdAt";
+const ROW_UPDATED_BY_KEY = "@updatedBy";
+const ROW_UPDATED_AT_KEY = "@updatedAt";
+let localRowIdCounter = 0;
+export function createDocumentRowId() {
+    const randomId = globalThis.crypto?.randomUUID?.();
+    if (randomId) {
+        return randomId;
+    }
+    localRowIdCounter += 1;
+    return `row-${Date.now()}-${localRowIdCounter}`;
+}
+function readRowString(row, key) {
+    const value = row.get(key);
+    return typeof value === "string" ? value : "";
+}
+// The peer that last set a key, from Loro's per-key last-writer-wins register.
+// "@updatedAt" is restamped with a fresh timestamp on every row write, so its
+// last editor is the peer of the row's most recent write. (Probing "@updatedBy"
+// would be wrong: it stores a user id that repeats when one user edits twice,
+// which Loro records as a no-op, leaving the register on the earlier writer.)
+function readRowEditorPeer(row, key) {
+    return row.getLastEditor(key) ?? null;
+}
+function parseDocumentRow(row) {
+    const id = readRowString(row, ROW_ID_KEY);
+    if (id.length === 0) {
+        return null;
+    }
+    const fields = {};
+    const fieldEditors = {};
+    for (const [key, value] of row.entries()) {
+        if (key.startsWith(ROW_META_PREFIX)) {
+            continue;
+        }
+        if (typeof value === "string") {
+            fields[key] = value;
+            // Each data cell has its own last-editor register, so field-level
+            // attribution is read the same way as the row-level peer.
+            fieldEditors[key] = readRowEditorPeer(row, key);
+        }
+    }
+    return {
+        id,
+        fields,
+        fieldEditors,
+        createdBy: readRowString(row, ROW_CREATED_BY_KEY),
+        createdAt: readRowString(row, ROW_CREATED_AT_KEY),
+        createdByPeer: readRowEditorPeer(row, ROW_CREATED_AT_KEY),
+        updatedBy: readRowString(row, ROW_UPDATED_BY_KEY),
+        updatedAt: readRowString(row, ROW_UPDATED_AT_KEY),
+        updatedByPeer: readRowEditorPeer(row, ROW_UPDATED_AT_KEY),
+    };
+}
+export function ensureDocumentRowsStructure(doc) {
+    doc.getList(DOCUMENT_ROWS_LIST_KEY);
+}
+function findRowMap(list, id) {
+    for (let index = 0; index < list.length; index += 1) {
+        const value = list.get(index);
+        if (value instanceof LoroMap && readRowString(value, ROW_ID_KEY) === id) {
+            return value;
+        }
+    }
+    return null;
+}
+export function listDocumentRows(doc) {
+    const list = doc.getList(DOCUMENT_ROWS_LIST_KEY);
+    const rows = [];
+    for (let index = 0; index < list.length; index += 1) {
+        const value = list.get(index);
+        if (value instanceof LoroMap) {
+            const row = parseDocumentRow(value);
+            if (row) {
+                rows.push(row);
+            }
+        }
+    }
+    return rows;
+}
+function writeRowFields(row, fields) {
+    for (const [key, value] of Object.entries(fields)) {
+        // Never let a caller's field name overwrite reserved metadata.
+        if (key.startsWith(ROW_META_PREFIX)) {
+            continue;
+        }
+        row.set(key, value);
+    }
+}
+export function addDocumentRow(doc, id, fields, attribution) {
+    const list = doc.getList(DOCUMENT_ROWS_LIST_KEY);
+    const row = list.pushContainer(new LoroMap());
+    row.set(ROW_ID_KEY, id);
+    row.set(ROW_CREATED_BY_KEY, attribution.userId);
+    row.set(ROW_CREATED_AT_KEY, attribution.at);
+    row.set(ROW_UPDATED_BY_KEY, attribution.userId);
+    row.set(ROW_UPDATED_AT_KEY, attribution.at);
+    writeRowFields(row, fields);
+}
+export function setDocumentRowFields(doc, id, patch, attribution) {
+    const list = doc.getList(DOCUMENT_ROWS_LIST_KEY);
+    const row = findRowMap(list, id);
+    if (!row) {
+        return false;
+    }
+    writeRowFields(row, patch);
+    row.set(ROW_UPDATED_BY_KEY, attribution.userId);
+    row.set(ROW_UPDATED_AT_KEY, attribution.at);
+    return true;
+}
+export function removeDocumentRow(doc, id) {
+    const list = doc.getList(DOCUMENT_ROWS_LIST_KEY);
+    for (let index = 0; index < list.length; index += 1) {
+        const value = list.get(index);
+        if (value instanceof LoroMap && readRowString(value, ROW_ID_KEY) === id) {
+            list.delete(index, 1);
+            return true;
+        }
+    }
+    return false;
+}
+function sameRow(left, right) {
+    if (left.id !== right.id ||
+        left.createdBy !== right.createdBy ||
+        left.createdAt !== right.createdAt ||
+        left.createdByPeer !== right.createdByPeer ||
+        left.updatedBy !== right.updatedBy ||
+        left.updatedAt !== right.updatedAt ||
+        left.updatedByPeer !== right.updatedByPeer) {
+        return false;
+    }
+    const leftKeys = Object.keys(left.fields);
+    const rightKeys = Object.keys(right.fields);
+    if (leftKeys.length !== rightKeys.length) {
+        return false;
+    }
+    // fieldEditors shares the exact key set as fields, so comparing per key here
+    // also covers a cell whose value is unchanged but whose editor changed.
+    return leftKeys.every((key) => left.fields[key] === right.fields[key] &&
+        left.fieldEditors[key] === right.fieldEditors[key]);
+}
+export function sameDocumentRows(left, right) {
+    return (left.length === right.length &&
+        left.every((row, index) => {
+            const nextRow = right[index];
+            return nextRow !== undefined && sameRow(row, nextRow);
+        }));
+}
+//# sourceMappingURL=documentRowList.js.map

package/data/documents/documentRowList.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentRowList.js","sourceRoot":"","sources":["documentRowList.ts"],"names":[],"mappings":"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","sourcesContent":["import { type LoroList, LoroMap } from \"@tearleads/loro\";\n\n// A document's repeated rows (e.g. a .env file's variables, a blood pressure\n// tracker's readings) live in one first-class Loro list — each row a nested\n// LoroMap. Storing each row as its own container makes concurrent edits to\n// different rows (or different cells of the same row) merge instead of\n// clobbering; only two writes to the same cell of the same row race, and Loro\n// resolves those last-writer-wins.\nconst DOCUMENT_ROWS_LIST_KEY = \"rows\";\n\n// Reserved row-map keys are namespaced so they never collide with a document\n// type's own field names (none of which begin with \"@\").\nconst ROW_META_PREFIX = \"@\";\nconst ROW_ID_KEY = \"@id\";\nconst ROW_CREATED_BY_KEY = \"@createdBy\";\nconst ROW_CREATED_AT_KEY = \"@createdAt\";\nconst ROW_UPDATED_BY_KEY = \"@updatedBy\";\nconst ROW_UPDATED_AT_KEY = \"@updatedAt\";\n\nexport interface DocumentRowAttribution {\n  // The signing user id of the writer, or \"\" when unauthenticated. Matches the\n  // key the edit-attribution/blame layer resolves against.\n  userId: string;\n  // ISO-8601 timestamp of the write.\n  at: string;\n}\n\nexport interface DocumentRow {\n  id: string;\n  fields: Record<string, string>;\n  createdBy: string;\n  createdAt: string;\n  updatedBy: string;\n  updatedAt: string;\n  // The Loro peer id that last wrote this row (read from the last-editor register\n  // of the always-restamped \"@updatedAt\" key). Unlike `updatedBy` — a\n  // self-attested user id stored in the row — this peer can be resolved to a\n  // server-verified writer via the edit-attribution segments. Null when the\n  // register has no editor (e.g. a never-written row). Survives snapshot\n  // reload, so it is stable across the store's persist cycle.\n  updatedByPeer: string | null;\n  // The Loro peer that created this row (last editor of the write-once\n  // \"@createdAt\" key), resolvable to a verified writer like `updatedByPeer`.\n  createdByPeer: string | null;\n  // Per-cell last-editor peers, keyed identically to `fields`. Each resolves to\n  // the verified writer of that specific cell's current value — the field-level\n  // analog of `updatedByPeer`.\n  fieldEditors: Record<string, string | null>;\n}\n\n// The minimal projection of a row the document projector needs to derive a\n// title (e.g. a reading/variable count) without depending on the store.\nexport interface DocumentRowSummary {\n  id: string;\n  fields: Readonly<Record<string, string>>;\n}\n\ninterface RowListDocumentShape {\n  getList: (key: string) => LoroList;\n}\n\nlet localRowIdCounter = 0;\n\nexport function createDocumentRowId(): string {\n  const randomId = globalThis.crypto?.randomUUID?.();\n  if (randomId) {\n    return randomId;\n  }\n\n  localRowIdCounter += 1;\n  return `row-${Date.now()}-${localRowIdCounter}`;\n}\n\nfunction readRowString(row: LoroMap, key: string): string {\n  const value = row.get(key);\n  return typeof value === \"string\" ? value : \"\";\n}\n\n// The peer that last set a key, from Loro's per-key last-writer-wins register.\n// \"@updatedAt\" is restamped with a fresh timestamp on every row write, so its\n// last editor is the peer of the row's most recent write. (Probing \"@updatedBy\"\n// would be wrong: it stores a user id that repeats when one user edits twice,\n// which Loro records as a no-op, leaving the register on the earlier writer.)\nfunction readRowEditorPeer(row: LoroMap, key: string): string | null {\n  return row.getLastEditor(key) ?? null;\n}\n\nfunction parseDocumentRow(row: LoroMap): DocumentRow | null {\n  const id = readRowString(row, ROW_ID_KEY);\n  if (id.length === 0) {\n    return null;\n  }\n\n  const fields: Record<string, string> = {};\n  const fieldEditors: Record<string, string | null> = {};\n  for (const [key, value] of row.entries()) {\n    if (key.startsWith(ROW_META_PREFIX)) {\n      continue;\n    }\n    if (typeof value === \"string\") {\n      fields[key] = value;\n      // Each data cell has its own last-editor register, so field-level\n      // attribution is read the same way as the row-level peer.\n      fieldEditors[key] = readRowEditorPeer(row, key);\n    }\n  }\n\n  return {\n    id,\n    fields,\n    fieldEditors,\n    createdBy: readRowString(row, ROW_CREATED_BY_KEY),\n    createdAt: readRowString(row, ROW_CREATED_AT_KEY),\n    createdByPeer: readRowEditorPeer(row, ROW_CREATED_AT_KEY),\n    updatedBy: readRowString(row, ROW_UPDATED_BY_KEY),\n    updatedAt: readRowString(row, ROW_UPDATED_AT_KEY),\n    updatedByPeer: readRowEditorPeer(row, ROW_UPDATED_AT_KEY),\n  };\n}\n\nexport function ensureDocumentRowsStructure(doc: RowListDocumentShape): void {\n  doc.getList(DOCUMENT_ROWS_LIST_KEY);\n}\n\nfunction findRowMap(list: LoroList, id: string): LoroMap | null {\n  for (let index = 0; index < list.length; index += 1) {\n    const value = list.get(index);\n    if (value instanceof LoroMap && readRowString(value, ROW_ID_KEY) === id) {\n      return value;\n    }\n  }\n\n  return null;\n}\n\nexport function listDocumentRows(doc: RowListDocumentShape): DocumentRow[] {\n  const list = doc.getList(DOCUMENT_ROWS_LIST_KEY);\n  const rows: DocumentRow[] = [];\n  for (let index = 0; index < list.length; index += 1) {\n    const value = list.get(index);\n    if (value instanceof LoroMap) {\n      const row = parseDocumentRow(value);\n      if (row) {\n        rows.push(row);\n      }\n    }\n  }\n\n  return rows;\n}\n\nfunction writeRowFields(\n  row: LoroMap,\n  fields: Readonly<Record<string, string>>,\n): void {\n  for (const [key, value] of Object.entries(fields)) {\n    // Never let a caller's field name overwrite reserved metadata.\n    if (key.startsWith(ROW_META_PREFIX)) {\n      continue;\n    }\n    row.set(key, value);\n  }\n}\n\nexport function addDocumentRow(\n  doc: RowListDocumentShape,\n  id: string,\n  fields: Readonly<Record<string, string>>,\n  attribution: DocumentRowAttribution,\n): void {\n  const list = doc.getList(DOCUMENT_ROWS_LIST_KEY);\n  const row = list.pushContainer(new LoroMap());\n  row.set(ROW_ID_KEY, id);\n  row.set(ROW_CREATED_BY_KEY, attribution.userId);\n  row.set(ROW_CREATED_AT_KEY, attribution.at);\n  row.set(ROW_UPDATED_BY_KEY, attribution.userId);\n  row.set(ROW_UPDATED_AT_KEY, attribution.at);\n  writeRowFields(row, fields);\n}\n\nexport function setDocumentRowFields(\n  doc: RowListDocumentShape,\n  id: string,\n  patch: Readonly<Record<string, string>>,\n  attribution: DocumentRowAttribution,\n): boolean {\n  const list = doc.getList(DOCUMENT_ROWS_LIST_KEY);\n  const row = findRowMap(list, id);\n  if (!row) {\n    return false;\n  }\n\n  writeRowFields(row, patch);\n  row.set(ROW_UPDATED_BY_KEY, attribution.userId);\n  row.set(ROW_UPDATED_AT_KEY, attribution.at);\n  return true;\n}\n\nexport function removeDocumentRow(\n  doc: RowListDocumentShape,\n  id: string,\n): boolean {\n  const list = doc.getList(DOCUMENT_ROWS_LIST_KEY);\n  for (let index = 0; index < list.length; index += 1) {\n    const value = list.get(index);\n    if (value instanceof LoroMap && readRowString(value, ROW_ID_KEY) === id) {\n      list.delete(index, 1);\n      return true;\n    }\n  }\n\n  return false;\n}\n\nfunction sameRow(left: DocumentRow, right: DocumentRow): boolean {\n  if (\n    left.id !== right.id ||\n    left.createdBy !== right.createdBy ||\n    left.createdAt !== right.createdAt ||\n    left.createdByPeer !== right.createdByPeer ||\n    left.updatedBy !== right.updatedBy ||\n    left.updatedAt !== right.updatedAt ||\n    left.updatedByPeer !== right.updatedByPeer\n  ) {\n    return false;\n  }\n\n  const leftKeys = Object.keys(left.fields);\n  const rightKeys = Object.keys(right.fields);\n  if (leftKeys.length !== rightKeys.length) {\n    return false;\n  }\n\n  // fieldEditors shares the exact key set as fields, so comparing per key here\n  // also covers a cell whose value is unchanged but whose editor changed.\n  return leftKeys.every(\n    (key) =>\n      left.fields[key] === right.fields[key] &&\n      left.fieldEditors[key] === right.fieldEditors[key],\n  );\n}\n\nexport function sameDocumentRows(\n  left: ReadonlyArray<DocumentRow>,\n  right: ReadonlyArray<DocumentRow>,\n): boolean {\n  return (\n    left.length === right.length &&\n    left.every((row, index) => {\n      const nextRow = right[index];\n      return nextRow !== undefined && sameRow(row, nextRow);\n    })\n  );\n}\n"]}

package/data/documents/documentSummary.d.ts

@@ -0,0 +1,24 @@
+import type { ContainerAccessLevel } from "../../internal/crypto/index.js";
+import type { StoredDocumentKind } from "./documentKinds.js";
+/** Non-empty because callers use this tuple to build SQL `NOT IN` clauses. */
+export declare const HIDDEN_DOCUMENT_SUMMARY_KINDS: readonly ["organization_profile"];
+export interface DocumentSummary {
+    accessStateHash?: string | null;
+    createdAt?: string | null;
+    effectiveAccessLevel?: ContainerAccessLevel | undefined;
+    id: string;
+    containerId: string | null;
+    documentKind?: StoredDocumentKind;
+    documentId: string | null;
+    title: string;
+    updatedAt: string;
+}
+export interface DiscoveredDocumentInput {
+    accessEpoch: number;
+    accessStateHash?: string | null;
+    containerId: string;
+    createdAt: string;
+    documentId: string;
+    effectiveAccessLevel?: ContainerAccessLevel | undefined;
+    linkedContainerIds: ReadonlyArray<string>;
+}

package/data/documents/documentSummary.js

@@ -0,0 +1,5 @@
+/** Non-empty because callers use this tuple to build SQL `NOT IN` clauses. */
+export const HIDDEN_DOCUMENT_SUMMARY_KINDS = [
+    "organization_profile",
+];
+//# sourceMappingURL=documentSummary.js.map

package/data/documents/documentSummary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentSummary.js","sourceRoot":"","sources":["documentSummary.ts"],"names":[],"mappings":"AAGA,8EAA8E;AAC9E,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,sBAAsB;CACmD,CAAC","sourcesContent":["import type { ContainerAccessLevel } from \"@tearleads/crypto\";\nimport type { StoredDocumentKind } from \"./documentKinds\";\n\n/** Non-empty because callers use this tuple to build SQL `NOT IN` clauses. */\nexport const HIDDEN_DOCUMENT_SUMMARY_KINDS = [\n  \"organization_profile\",\n] as const satisfies readonly [StoredDocumentKind, ...StoredDocumentKind[]];\n\nexport interface DocumentSummary {\n  accessStateHash?: string | null;\n  createdAt?: string | null;\n  effectiveAccessLevel?: ContainerAccessLevel | undefined;\n  id: string;\n  containerId: string | null;\n  documentKind?: StoredDocumentKind;\n  documentId: string | null;\n  title: string;\n  updatedAt: string;\n}\n\nexport interface DiscoveredDocumentInput {\n  accessEpoch: number;\n  accessStateHash?: string | null;\n  containerId: string;\n  createdAt: string;\n  documentId: string;\n  effectiveAccessLevel?: ContainerAccessLevel | undefined;\n  linkedContainerIds: ReadonlyArray<string>;\n}\n"]}

package/data/documents/documentSync.js

@@ -0,0 +1,68 @@
+import { bytesToBase64 } from "../../internal/encoding/index.js";
+import { getImportBlobMetadata, versionVectorsEqual } from "../../internal/loro/index.js";
+import { isPlainObject } from "../../internal/validators/isPlainObject.js";
+import { WsDocumentUpdateCreatedHintSchema, } from "../../internal/validators/realtime/index.js";
+export function createPendingUpdateFields(update, sourceVersionVector) {
+    if (update.byteLength === 0) {
+        return null;
+    }
+    const { mode, partialEndVersionVector, partialStartVersionVector } = getImportBlobMetadata(update);
+    // A Loro delta that encodes no ops still serializes to a small non-empty blob
+    // (~22 bytes) with start == end version vectors, so the byteLength guard above
+    // does not catch it. Such an update produces zero spans server-side, which the
+    // frontier diff treats as permanently "missing" and re-sends to every reader
+    // on every sync forever. Drop it: a zero-span update carries nothing.
+    if (versionVectorsEqual(partialStartVersionVector, partialEndVersionVector)) {
+        return null;
+    }
+    if (sourceVersionVector != null) {
+        if (mode !== "snapshot") {
+            throw new Error("Rotation baseline must be a full-history Loro snapshot");
+        }
+        if (!versionVectorsEqual(sourceVersionVector, partialEndVersionVector)) {
+            throw new Error("Rotation baseline source must equal its decoded end version vector");
+        }
+    }
+    return {
+        updateData: bytesToBase64(update),
+        partialStartVersionVector,
+        partialEndVersionVector,
+        sourceVersionVector: sourceVersionVector ?? null,
+    };
+}
+export function isDocumentUpdateCreatedEvent(event) {
+    return WsDocumentUpdateCreatedHintSchema.safeParse(event).success;
+}
+export function isDocumentMutationCreatedEvent(event) {
+    if (!isPlainObject(event)) {
+        return false;
+    }
+    const containerIds = Reflect.get(event, "containerIds");
+    const documentId = Reflect.get(event, "documentId");
+    const eventType = Reflect.get(event, "eventType");
+    return (Reflect.get(event, "type") === "document_mutation_created" &&
+        typeof documentId === "string" &&
+        documentId.length > 0 &&
+        (eventType === "document.link" ||
+            eventType === "document.purge" ||
+            eventType === "document.unlink") &&
+        Array.isArray(containerIds) &&
+        containerIds.length > 0 &&
+        containerIds.every((containerId) => typeof containerId === "string" && containerId.length > 0));
+}
+/**
+ * Realtime hints after which a cached writer projection may cite a stale
+ * manifest: a container mutation (grant, rekey, recite, ...) or the gateway's
+ * dependent-path notice. An eviction resync also drops the previously held
+ * projection before revalidation; its later parent-only hint names no child.
+ */
+export function isContainerProjectionInvalidationHint(event) {
+    if (typeof event !== "object" || event === null)
+        return false;
+    const type = Reflect.get(event, "type");
+    return (type === "container_mutation_created" ||
+        type === "container_path_changed" ||
+        type === "container_children_changed" ||
+        type === "resync_required");
+}
+//# sourceMappingURL=documentSync.js.map

package/data/documents/documentSync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentSync.js","sourceRoot":"","sources":["documentSync.ts"],"names":[],"mappings":"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","sourcesContent":["import { bytesToBase64 } from \"@tearleads/encoding\";\nimport { getImportBlobMetadata, versionVectorsEqual } from \"@tearleads/loro\";\nimport { isPlainObject } from \"@tearleads/validators/isPlainObject\";\nimport {\n  WsDocumentUpdateCreatedHintSchema,\n  type WsInvalidationHint,\n} from \"@tearleads/validators/realtime\";\nimport type { PendingUpdateFields } from \"../sqlite/documentPersistence\";\n\ntype DocumentUpdateCreatedEvent = Extract<\n  WsInvalidationHint,\n  { type: \"document_update_created\" }\n>;\n\ninterface DocumentMutationCreatedEvent {\n  type: \"document_mutation_created\";\n  containerIds: string[];\n  documentId: string;\n  eventType: \"document.link\" | \"document.purge\" | \"document.unlink\";\n}\n\nexport function createPendingUpdateFields(\n  update: Uint8Array,\n  sourceVersionVector?: string | null,\n): PendingUpdateFields | null {\n  if (update.byteLength === 0) {\n    return null;\n  }\n\n  const { mode, partialEndVersionVector, partialStartVersionVector } =\n    getImportBlobMetadata(update);\n\n  // A Loro delta that encodes no ops still serializes to a small non-empty blob\n  // (~22 bytes) with start == end version vectors, so the byteLength guard above\n  // does not catch it. Such an update produces zero spans server-side, which the\n  // frontier diff treats as permanently \"missing\" and re-sends to every reader\n  // on every sync forever. Drop it: a zero-span update carries nothing.\n  if (versionVectorsEqual(partialStartVersionVector, partialEndVersionVector)) {\n    return null;\n  }\n\n  if (sourceVersionVector != null) {\n    if (mode !== \"snapshot\") {\n      throw new Error(\"Rotation baseline must be a full-history Loro snapshot\");\n    }\n    if (!versionVectorsEqual(sourceVersionVector, partialEndVersionVector)) {\n      throw new Error(\n        \"Rotation baseline source must equal its decoded end version vector\",\n      );\n    }\n  }\n\n  return {\n    updateData: bytesToBase64(update),\n    partialStartVersionVector,\n    partialEndVersionVector,\n    sourceVersionVector: sourceVersionVector ?? null,\n  };\n}\n\nexport function isDocumentUpdateCreatedEvent(\n  event: unknown,\n): event is DocumentUpdateCreatedEvent {\n  return WsDocumentUpdateCreatedHintSchema.safeParse(event).success;\n}\n\nexport function isDocumentMutationCreatedEvent(\n  event: unknown,\n): event is DocumentMutationCreatedEvent {\n  if (!isPlainObject(event)) {\n    return false;\n  }\n\n  const containerIds = Reflect.get(event, \"containerIds\");\n  const documentId = Reflect.get(event, \"documentId\");\n  const eventType = Reflect.get(event, \"eventType\");\n\n  return (\n    Reflect.get(event, \"type\") === \"document_mutation_created\" &&\n    typeof documentId === \"string\" &&\n    documentId.length > 0 &&\n    (eventType === \"document.link\" ||\n      eventType === \"document.purge\" ||\n      eventType === \"document.unlink\") &&\n    Array.isArray(containerIds) &&\n    containerIds.length > 0 &&\n    containerIds.every(\n      (containerId) =>\n        typeof containerId === \"string\" && containerId.length > 0,\n    )\n  );\n}\n\n/**\n * Realtime hints after which a cached writer projection may cite a stale\n * manifest: a container mutation (grant, rekey, recite, ...) or the gateway's\n * dependent-path notice. An eviction resync also drops the previously held\n * projection before revalidation; its later parent-only hint names no child.\n */\nexport function isContainerProjectionInvalidationHint(event: unknown): boolean {\n  if (typeof event !== \"object\" || event === null) return false;\n  const type = Reflect.get(event, \"type\");\n  return (\n    type === \"container_mutation_created\" ||\n    type === \"container_path_changed\" ||\n    type === \"container_children_changed\" ||\n    type === \"resync_required\"\n  );\n}\n"]}

package/data/documents/editAttribution.d.ts

@@ -0,0 +1,77 @@
+import type { DocumentEditAttributionRangeResponse } from "../../internal/validators/response/index.js";
+import { type DocumentAttributionInterval } from "./editAttributionTypes.js";
+export { type DocumentBlameRange, type DocumentCharacterBlameSummary, resolveOpIdAttribution, summarizeBlameRanges, summarizeCharacterBlame, summarizeDocumentBlame, } from "./editAttributionBlame.js";
+export type { DocumentAttributionInterval } from "./editAttributionTypes.js";
+export type DocumentEditAttributionRange = DocumentEditAttributionRangeResponse;
+export interface DocumentContributor {
+    writerUserId: string;
+    writerKeyFingerprint: string;
+    /** Total Loro op counters attributed to this writer across the document. */
+    opCount: number;
+    /** Ordinary (incremental) op counters attributed to this signing identity. */
+    directOpCount: number;
+    /** Op counters credited via a rotate_baseline re-assertion. */
+    baselineOpCount: number;
+    /** This writer has at least one ordinary (incremental) attributed range. */
+    hasDirectAuthority: boolean;
+    /** This identity has at least one rotate_baseline re-asserted range. */
+    hasBaselineAuthority: boolean;
+}
+/**
+ * Aggregate attribution segments into a per-signing-identity summary, ordered
+ * by op count (desc). Writers are keyed by signing identity (`writerUserId` /
+ * `writerKeyFingerprint`) — no roster/profile decryption needed; the fingerprint
+ * is resolvable via the plaintext org directory.
+ */
+export declare function summarizeDocumentContributors(segments: readonly DocumentAttributionInterval[]): DocumentContributor[];
+interface DocumentAttributionSegment {
+    peerId: string;
+    startCounter: number;
+    endCounter: number;
+    /** Loro op counters in this contiguous range (`endCounter - startCounter`). */
+    opCount: number;
+    /** The signed upload (`document_updates.id`) that delivered this range. */
+    updateId: string;
+    writerUserId: string;
+    writerKeyFingerprint: string;
+    authorityKind: "direct" | "baseline";
+}
+/**
+ * Normalize attribution segments into the granular per-range list behind the
+ * contributor rollup: empty ranges dropped, each tagged with its op count, and
+ * ordered to mirror {@link summarizeDocumentContributors} (identities by total
+ * op count desc, then each identity's ranges in counter order). This is the
+ * drill-down detail — "who wrote which ranges, direct vs re-asserted" — that the
+ * `N edits` summary collapses away.
+ */
+export declare function listDocumentAttributionSegments(segments: readonly DocumentEditAttributionRange[]): DocumentAttributionSegment[];
+interface PeerWriterAttribution {
+    writerUserId: string;
+    writerKeyFingerprint: string;
+}
+/**
+ * Map each Loro peer to one signing identity. A peer spanning multiple users or
+ * fingerprints maps to `null`; peer-only field metadata cannot choose the exact
+ * interval without guessing. Authority changes do not obscure a stable identity.
+ */
+export declare function writerByPeerId(segments: readonly DocumentAttributionInterval[]): Map<string, PeerWriterAttribution | null>;
+export interface DocumentFieldBlame {
+    /** The structured field's map key (e.g. `firstName`, `cardNumber`). */
+    fieldKey: string;
+    /** Writer credited with the last edit, or null when unresolved. */
+    writerUserId: string | null;
+    /** null when unresolved. */
+    writerKeyFingerprint: string | null;
+}
+/**
+ * Per-field "blame" for a structured document (contact, card, license): resolve
+ * the peer that last set each field — from `listSnapshotFieldEditors` — to a
+ * writer. Unlike the character path, a field carries only its last-editor peer
+ * (no op counter), so this resolves peer-level via {@link writerByPeerId}: a
+ * field whose peer has no segment or spans signing identities is left
+ * unattributed (`writerUserId: null`). Fields are sorted by key.
+ */
+export declare function summarizeFieldBlame(fieldEditors: ReadonlyArray<{
+    readonly key: string;
+    readonly peerId: string | null;
+}>, segments: readonly DocumentAttributionInterval[]): DocumentFieldBlame[];

package/data/documents/editAttribution.js

@@ -0,0 +1,131 @@
+import { compareCanonicalStrings } from "../../internal/crypto/index.js";
+import { signingIdentityKey, } from "./editAttributionTypes.js";
+export { resolveOpIdAttribution, summarizeBlameRanges, summarizeCharacterBlame, summarizeDocumentBlame, } from "./editAttributionBlame.js";
+/**
+ * Aggregate attribution segments into a per-signing-identity summary, ordered
+ * by op count (desc). Writers are keyed by signing identity (`writerUserId` /
+ * `writerKeyFingerprint`) — no roster/profile decryption needed; the fingerprint
+ * is resolvable via the plaintext org directory.
+ */
+export function summarizeDocumentContributors(segments) {
+    const byWriter = new Map();
+    for (const segment of segments) {
+        const opCount = segment.endCounter - segment.startCounter;
+        if (opCount <= 0) {
+            continue;
+        }
+        const identityKey = signingIdentityKey(segment);
+        const existing = byWriter.get(identityKey);
+        if (existing) {
+            existing.opCount += opCount;
+            existing.directOpCount +=
+                segment.authorityKind === "direct" ? opCount : 0;
+            existing.baselineOpCount +=
+                segment.authorityKind === "baseline" ? opCount : 0;
+            existing.hasDirectAuthority ||= segment.authorityKind === "direct";
+            existing.hasBaselineAuthority ||= segment.authorityKind === "baseline";
+            continue;
+        }
+        byWriter.set(identityKey, {
+            writerUserId: segment.writerUserId,
+            writerKeyFingerprint: segment.writerKeyFingerprint,
+            opCount,
+            directOpCount: segment.authorityKind === "direct" ? opCount : 0,
+            baselineOpCount: segment.authorityKind === "baseline" ? opCount : 0,
+            hasDirectAuthority: segment.authorityKind === "direct",
+            hasBaselineAuthority: segment.authorityKind === "baseline",
+        });
+    }
+    return [...byWriter.values()].sort((left, right) => right.opCount - left.opCount ||
+        compareCanonicalStrings(left.writerUserId, right.writerUserId) ||
+        compareCanonicalStrings(left.writerKeyFingerprint, right.writerKeyFingerprint));
+}
+/**
+ * Normalize attribution segments into the granular per-range list behind the
+ * contributor rollup: empty ranges dropped, each tagged with its op count, and
+ * ordered to mirror {@link summarizeDocumentContributors} (identities by total
+ * op count desc, then each identity's ranges in counter order). This is the
+ * drill-down detail — "who wrote which ranges, direct vs re-asserted" — that the
+ * `N edits` summary collapses away.
+ */
+export function listDocumentAttributionSegments(segments) {
+    const rangesByWriter = new Map();
+    for (const segment of segments) {
+        if (segment.endCounter <= segment.startCounter) {
+            continue;
+        }
+        const range = {
+            peerId: segment.peerId,
+            startCounter: segment.startCounter,
+            endCounter: segment.endCounter,
+            opCount: segment.endCounter - segment.startCounter,
+            updateId: segment.updateId,
+            writerUserId: segment.writerUserId,
+            writerKeyFingerprint: segment.writerKeyFingerprint,
+            authorityKind: segment.authorityKind,
+        };
+        const identityKey = signingIdentityKey(segment);
+        const existing = rangesByWriter.get(identityKey);
+        if (existing) {
+            existing.push(range);
+        }
+        else {
+            rangesByWriter.set(identityKey, [range]);
+        }
+    }
+    // summarizeDocumentContributors credits every writer with an op-bearing range,
+    // and rangesByWriter is grouped from those same ranges, so each contributor has
+    // a group here — flat-mapping by contributor order aligns the drill-down with
+    // the Contributors section and drops nothing.
+    return summarizeDocumentContributors(segments).flatMap((contributor) => (rangesByWriter.get(signingIdentityKey(contributor)) ?? []).sort((left, right) => left.startCounter - right.startCounter ||
+        compareCanonicalStrings(left.peerId, right.peerId)));
+}
+/**
+ * Map each Loro peer to one signing identity. A peer spanning multiple users or
+ * fingerprints maps to `null`; peer-only field metadata cannot choose the exact
+ * interval without guessing. Authority changes do not obscure a stable identity.
+ */
+export function writerByPeerId(segments) {
+    const byPeer = new Map();
+    for (const segment of segments) {
+        if (segment.endCounter <= segment.startCounter) {
+            continue;
+        }
+        const existing = byPeer.get(segment.peerId);
+        if (existing === undefined) {
+            byPeer.set(segment.peerId, {
+                writerUserId: segment.writerUserId,
+                writerKeyFingerprint: segment.writerKeyFingerprint,
+            });
+            continue;
+        }
+        if (existing !== null &&
+            (existing.writerUserId !== segment.writerUserId ||
+                existing.writerKeyFingerprint !== segment.writerKeyFingerprint)) {
+            byPeer.set(segment.peerId, null);
+        }
+    }
+    return byPeer;
+}
+/**
+ * Per-field "blame" for a structured document (contact, card, license): resolve
+ * the peer that last set each field — from `listSnapshotFieldEditors` — to a
+ * writer. Unlike the character path, a field carries only its last-editor peer
+ * (no op counter), so this resolves peer-level via {@link writerByPeerId}: a
+ * field whose peer has no segment or spans signing identities is left
+ * unattributed (`writerUserId: null`). Fields are sorted by key.
+ */
+export function summarizeFieldBlame(fieldEditors, segments) {
+    const byPeer = writerByPeerId(segments);
+    return fieldEditors
+        .map(({ key, peerId }) => {
+        const writer = peerId === null ? null : (byPeer.get(peerId) ?? null);
+        return {
+            fieldKey: key,
+            writerUserId: writer?.writerUserId ?? null,
+            writerKeyFingerprint: writer?.writerKeyFingerprint ?? null,
+        };
+    })
+        .sort((left, right) => compareCanonicalStrings(left.fieldKey, right.fieldKey));
+}
+//# sourceMappingURL=editAttribution.js.map

package/data/documents/editAttribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editAttribution.js","sourceRoot":"","sources":["editAttribution.ts"],"names":[],"mappings":"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","sourcesContent":["import { compareCanonicalStrings } from \"@tearleads/crypto\";\nimport type { DocumentEditAttributionRangeResponse } from \"@tearleads/validators/response\";\nimport {\n  type DocumentAttributionInterval,\n  signingIdentityKey,\n} from \"./editAttributionTypes\";\n\nexport {\n  type DocumentBlameRange,\n  type DocumentCharacterBlameSummary,\n  resolveOpIdAttribution,\n  summarizeBlameRanges,\n  summarizeCharacterBlame,\n  summarizeDocumentBlame,\n} from \"./editAttributionBlame\";\nexport type { DocumentAttributionInterval } from \"./editAttributionTypes\";\n\nexport type DocumentEditAttributionRange = DocumentEditAttributionRangeResponse;\n\nexport interface DocumentContributor {\n  writerUserId: string;\n  writerKeyFingerprint: string;\n  /** Total Loro op counters attributed to this writer across the document. */\n  opCount: number;\n  /** Ordinary (incremental) op counters attributed to this signing identity. */\n  directOpCount: number;\n  /** Op counters credited via a rotate_baseline re-assertion. */\n  baselineOpCount: number;\n  /** This writer has at least one ordinary (incremental) attributed range. */\n  hasDirectAuthority: boolean;\n  /** This identity has at least one rotate_baseline re-asserted range. */\n  hasBaselineAuthority: boolean;\n}\n\n/**\n * Aggregate attribution segments into a per-signing-identity summary, ordered\n * by op count (desc). Writers are keyed by signing identity (`writerUserId` /\n * `writerKeyFingerprint`) — no roster/profile decryption needed; the fingerprint\n * is resolvable via the plaintext org directory.\n */\nexport function summarizeDocumentContributors(\n  segments: readonly DocumentAttributionInterval[],\n): DocumentContributor[] {\n  const byWriter = new Map<string, DocumentContributor>();\n  for (const segment of segments) {\n    const opCount = segment.endCounter - segment.startCounter;\n    if (opCount <= 0) {\n      continue;\n    }\n    const identityKey = signingIdentityKey(segment);\n    const existing = byWriter.get(identityKey);\n    if (existing) {\n      existing.opCount += opCount;\n      existing.directOpCount +=\n        segment.authorityKind === \"direct\" ? opCount : 0;\n      existing.baselineOpCount +=\n        segment.authorityKind === \"baseline\" ? opCount : 0;\n      existing.hasDirectAuthority ||= segment.authorityKind === \"direct\";\n      existing.hasBaselineAuthority ||= segment.authorityKind === \"baseline\";\n      continue;\n    }\n    byWriter.set(identityKey, {\n      writerUserId: segment.writerUserId,\n      writerKeyFingerprint: segment.writerKeyFingerprint,\n      opCount,\n      directOpCount: segment.authorityKind === \"direct\" ? opCount : 0,\n      baselineOpCount: segment.authorityKind === \"baseline\" ? opCount : 0,\n      hasDirectAuthority: segment.authorityKind === \"direct\",\n      hasBaselineAuthority: segment.authorityKind === \"baseline\",\n    });\n  }\n  return [...byWriter.values()].sort(\n    (left, right) =>\n      right.opCount - left.opCount ||\n      compareCanonicalStrings(left.writerUserId, right.writerUserId) ||\n      compareCanonicalStrings(\n        left.writerKeyFingerprint,\n        right.writerKeyFingerprint,\n      ),\n  );\n}\n\ninterface DocumentAttributionSegment {\n  peerId: string;\n  startCounter: number;\n  endCounter: number;\n  /** Loro op counters in this contiguous range (`endCounter - startCounter`). */\n  opCount: number;\n  /** The signed upload (`document_updates.id`) that delivered this range. */\n  updateId: string;\n  writerUserId: string;\n  writerKeyFingerprint: string;\n  authorityKind: \"direct\" | \"baseline\";\n}\n\n/**\n * Normalize attribution segments into the granular per-range list behind the\n * contributor rollup: empty ranges dropped, each tagged with its op count, and\n * ordered to mirror {@link summarizeDocumentContributors} (identities by total\n * op count desc, then each identity's ranges in counter order). This is the\n * drill-down detail — \"who wrote which ranges, direct vs re-asserted\" — that the\n * `N edits` summary collapses away.\n */\nexport function listDocumentAttributionSegments(\n  segments: readonly DocumentEditAttributionRange[],\n): DocumentAttributionSegment[] {\n  const rangesByWriter = new Map<string, DocumentAttributionSegment[]>();\n  for (const segment of segments) {\n    if (segment.endCounter <= segment.startCounter) {\n      continue;\n    }\n    const range: DocumentAttributionSegment = {\n      peerId: segment.peerId,\n      startCounter: segment.startCounter,\n      endCounter: segment.endCounter,\n      opCount: segment.endCounter - segment.startCounter,\n      updateId: segment.updateId,\n      writerUserId: segment.writerUserId,\n      writerKeyFingerprint: segment.writerKeyFingerprint,\n      authorityKind: segment.authorityKind,\n    };\n    const identityKey = signingIdentityKey(segment);\n    const existing = rangesByWriter.get(identityKey);\n    if (existing) {\n      existing.push(range);\n    } else {\n      rangesByWriter.set(identityKey, [range]);\n    }\n  }\n  // summarizeDocumentContributors credits every writer with an op-bearing range,\n  // and rangesByWriter is grouped from those same ranges, so each contributor has\n  // a group here — flat-mapping by contributor order aligns the drill-down with\n  // the Contributors section and drops nothing.\n  return summarizeDocumentContributors(segments).flatMap((contributor) =>\n    (rangesByWriter.get(signingIdentityKey(contributor)) ?? []).sort(\n      (left, right) =>\n        left.startCounter - right.startCounter ||\n        compareCanonicalStrings(left.peerId, right.peerId),\n    ),\n  );\n}\n\ninterface PeerWriterAttribution {\n  writerUserId: string;\n  writerKeyFingerprint: string;\n}\n\n/**\n * Map each Loro peer to one signing identity. A peer spanning multiple users or\n * fingerprints maps to `null`; peer-only field metadata cannot choose the exact\n * interval without guessing. Authority changes do not obscure a stable identity.\n */\nexport function writerByPeerId(\n  segments: readonly DocumentAttributionInterval[],\n): Map<string, PeerWriterAttribution | null> {\n  const byPeer = new Map<string, PeerWriterAttribution | null>();\n  for (const segment of segments) {\n    if (segment.endCounter <= segment.startCounter) {\n      continue;\n    }\n    const existing = byPeer.get(segment.peerId);\n    if (existing === undefined) {\n      byPeer.set(segment.peerId, {\n        writerUserId: segment.writerUserId,\n        writerKeyFingerprint: segment.writerKeyFingerprint,\n      });\n      continue;\n    }\n    if (\n      existing !== null &&\n      (existing.writerUserId !== segment.writerUserId ||\n        existing.writerKeyFingerprint !== segment.writerKeyFingerprint)\n    ) {\n      byPeer.set(segment.peerId, null);\n    }\n  }\n  return byPeer;\n}\n\nexport interface DocumentFieldBlame {\n  /** The structured field's map key (e.g. `firstName`, `cardNumber`). */\n  fieldKey: string;\n  /** Writer credited with the last edit, or null when unresolved. */\n  writerUserId: string | null;\n  /** null when unresolved. */\n  writerKeyFingerprint: string | null;\n}\n\n/**\n * Per-field \"blame\" for a structured document (contact, card, license): resolve\n * the peer that last set each field — from `listSnapshotFieldEditors` — to a\n * writer. Unlike the character path, a field carries only its last-editor peer\n * (no op counter), so this resolves peer-level via {@link writerByPeerId}: a\n * field whose peer has no segment or spans signing identities is left\n * unattributed (`writerUserId: null`). Fields are sorted by key.\n */\nexport function summarizeFieldBlame(\n  fieldEditors: ReadonlyArray<{\n    readonly key: string;\n    readonly peerId: string | null;\n  }>,\n  segments: readonly DocumentAttributionInterval[],\n): DocumentFieldBlame[] {\n  const byPeer = writerByPeerId(segments);\n  return fieldEditors\n    .map(({ key, peerId }) => {\n      const writer = peerId === null ? null : (byPeer.get(peerId) ?? null);\n      return {\n        fieldKey: key,\n        writerUserId: writer?.writerUserId ?? null,\n        writerKeyFingerprint: writer?.writerKeyFingerprint ?? null,\n      };\n    })\n    .sort((left, right) =>\n      compareCanonicalStrings(left.fieldKey, right.fieldKey),\n    );\n}\n"]}

package/data/documents/editAttributionBlame.d.ts

@@ -0,0 +1,59 @@
+import { type DocumentAttributionInterval } from "./editAttributionTypes.js";
+interface OpIdAttribution {
+    writerUserId: string;
+    writerKeyFingerprint: string;
+    authorityKind: "direct" | "baseline";
+}
+interface CharacterOpId {
+    readonly peerId: string;
+    readonly counter: number;
+}
+interface DocumentBlameSource {
+    readonly codePoints: readonly string[];
+    readonly opIds: readonly CharacterOpId[];
+}
+interface DocumentCharacterBlame {
+    writerUserId: string;
+    writerKeyFingerprint: string;
+    /** Characters (code points) currently attributed to this signing identity. */
+    characterCount: number;
+    /** Live characters credited through ordinary incremental updates. */
+    directCharacterCount: number;
+    /** Live characters credited through rotate_baseline re-assertions. */
+    baselineCharacterCount: number;
+    hasDirectAuthority: boolean;
+    hasBaselineAuthority: boolean;
+}
+export interface DocumentCharacterBlameSummary {
+    /** Per-signing-identity breakdown, ordered by `characterCount` desc. */
+    writers: DocumentCharacterBlame[];
+    totalCharacterCount: number;
+    /** Characters not covered by the current remote attribution intervals. */
+    unattributedCharacterCount: number;
+}
+export interface DocumentBlameRange {
+    /** Code-point start index (inclusive) of this run in the current text. */
+    startIndex: number;
+    /** Code-point end index (exclusive). */
+    endIndex: number;
+    text: string;
+    writerUserId: string | null;
+    writerKeyFingerprint: string | null;
+    authorityKind: "direct" | "baseline" | null;
+}
+interface DocumentBlameSummary {
+    characterBlame: DocumentCharacterBlameSummary;
+    blameRanges: DocumentBlameRange[];
+}
+/** Resolve one op id. Reuse the summary functions for whole-document sweeps. */
+export declare function resolveOpIdAttribution(segments: readonly DocumentAttributionInterval[], peerId: string, counter: number): OpIdAttribution | null;
+/** Count current characters by signing identity. */
+export declare function summarizeCharacterBlame(charOpIds: readonly CharacterOpId[], segments: readonly DocumentAttributionInterval[]): DocumentCharacterBlameSummary;
+/** Coalesce current prose into homogeneous signing-identity/authority runs. */
+export declare function summarizeBlameRanges(source: DocumentBlameSource, segments: readonly DocumentAttributionInterval[]): DocumentBlameRange[];
+/**
+ * Derive character totals and prose runs with one interval lookup per code point.
+ * The standalone summary functions remain available for callers needing one view.
+ */
+export declare function summarizeDocumentBlame(source: DocumentBlameSource, segments: readonly DocumentAttributionInterval[]): DocumentBlameSummary;
+export {};