@xnetjs/data 2.3.0 → 2.5.0

package/dist/index.js

@@ -222,7 +222,73 @@ import {
   validateJsonData,
   validateRollupConfig,
   visibleFormQuestions
-} from "./chunk-56EXPOJ4.js";
+} from "./chunk-TW5XJHNF.js";
+import {
+  MemoryNodeStorageAdapter,
+  NodeStore,
+  PermissionError,
+  QUERY_AST_VERSION,
+  SQLiteNodeStorageAdapter,
+  TEMP_ID_PREFIX,
+  and,
+  avg,
+  between,
+  contains,
+  count,
+  countDistinct,
+  createNodeStorageAdapter,
+  createSchemaLookup,
+  dashboardQuerySet,
+  defineNodeQueryAST,
+  defineQuerySetAST,
+  defineSavedViewDescriptor,
+  eq,
+  evaluateQueryASTPlannerGate,
+  executeQueryASTLoadedAggregates,
+  filterQueryASTLoadedRows,
+  follow,
+  from,
+  getQueryASTRelationIndexRequirements,
+  groupBy,
+  gt,
+  gte,
+  having,
+  includesAny,
+  isNotNull,
+  isNull,
+  isTempId,
+  lt,
+  lte,
+  matchesQueryASTLoadedRow,
+  max,
+  min,
+  neq,
+  not,
+  or,
+  planQueryASTAggregates,
+  queryOperators,
+  querySetCount,
+  resolveTempIds,
+  startsWith,
+  sum,
+  validateQueryAST,
+  validateSavedViewDescriptor
+} from "./chunk-ODOPVGUX.js";
+import {
+  applyNodeQueryDescriptor,
+  createNodeQueryDescriptor,
+  decodeNodeQueryCursor,
+  encodeNodeQueryCursor,
+  filterNodeQueryResults,
+  getNodeQuerySearchTokens,
+  matchesNodeQueryDescriptor,
+  nodeQueryDescriptorNeedsBoundedReload,
+  nodeQueryDescriptorToOptions,
+  serializeNodeQueryDescriptor,
+  sortNodeQueryResults,
+  withoutNodeQueryMaterializedView,
+  withoutNodeQueryPagination
+} from "./chunk-WOEFYS7Y.js";
 import {
   LensRegistry,
   MAX_LINK_PREVIEWS_PER_MESSAGE,
@@ -291,7 +357,7 @@ import {
   taskBranchName,
   transform,
   when
-} from "./chunk-32IVMT6Z.js";
+} from "./chunk-MAB662PR.js";
 import {
   AbuseReportSchema,
   AppealSchema,
@@ -544,7 +610,7 @@ import {
 } from "./chunk-R2AZXT3D.js";
 import {
   PageSchema
-} from "./chunk-Y2XWK7AA.js";
+} from "./chunk-JF4VCZER.js";
 import {
   FOLDER_SCHEMA_IRI,
   FolderSchema,
@@ -599,72 +665,6 @@ import {
   DatabaseViewSchema
 } from "./chunk-UFV5QWCL.js";
 import "./chunk-RLRAWZJE.js";
-import {
-  MemoryNodeStorageAdapter,
-  NodeStore,
-  PermissionError,
-  QUERY_AST_VERSION,
-  SQLiteNodeStorageAdapter,
-  TEMP_ID_PREFIX,
-  and,
-  avg,
-  between,
-  contains,
-  count,
-  countDistinct,
-  createNodeStorageAdapter,
-  createSchemaLookup,
-  dashboardQuerySet,
-  defineNodeQueryAST,
-  defineQuerySetAST,
-  defineSavedViewDescriptor,
-  eq,
-  evaluateQueryASTPlannerGate,
-  executeQueryASTLoadedAggregates,
-  filterQueryASTLoadedRows,
-  follow,
-  from,
-  getQueryASTRelationIndexRequirements,
-  groupBy,
-  gt,
-  gte,
-  having,
-  includesAny,
-  isNotNull,
-  isNull,
-  isTempId,
-  lt,
-  lte,
-  matchesQueryASTLoadedRow,
-  max,
-  min,
-  neq,
-  not,
-  or,
-  planQueryASTAggregates,
-  queryOperators,
-  querySetCount,
-  resolveTempIds,
-  startsWith,
-  sum,
-  validateQueryAST,
-  validateSavedViewDescriptor
-} from "./chunk-27AF2RSY.js";
-import {
-  applyNodeQueryDescriptor,
-  createNodeQueryDescriptor,
-  decodeNodeQueryCursor,
-  encodeNodeQueryCursor,
-  filterNodeQueryResults,
-  getNodeQuerySearchTokens,
-  matchesNodeQueryDescriptor,
-  nodeQueryDescriptorNeedsBoundedReload,
-  nodeQueryDescriptorToOptions,
-  serializeNodeQueryDescriptor,
-  sortNodeQueryResults,
-  withoutNodeQueryMaterializedView,
-  withoutNodeQueryPagination
-} from "./chunk-WOEFYS7Y.js";
 import {
   evaluateLedgerWrite,
   foldAccountRecord,
@@ -2049,9 +2049,646 @@ var BlobService = class {
   }
 };
 
+// src/portability/types.ts
+var XNETPACK_FORMAT_VERSION = "xnetpack/1";
+var BUNDLE_ENTRY = {
+  manifest: "manifest.json",
+  changes: "changes.ndjson",
+  blobIndex: "blobs.ndjson",
+  yjsDocs: "yjs/docs.ndjson"
+};
+var FRONTIER_HEADS_CAP = 32;
+
+// src/portability/serialize.ts
+import { bytesToBase64, base64ToBytes, hash, hashHex } from "@xnetjs/crypto";
+var textEncoder = new TextEncoder();
+var textDecoder = new TextDecoder();
+function toPortableChangeRecord(change) {
+  const record = {
+    id: change.id,
+    type: change.type,
+    hash: change.hash,
+    nodeId: change.payload.nodeId,
+    schemaId: change.payload.schemaId,
+    lamportTime: change.lamport,
+    authorDid: change.authorDID,
+    wallTime: change.wallTime,
+    parentHash: change.parentHash,
+    payload: change.payload,
+    signatureB64: bytesToBase64(change.signature),
+    // protocolVersion is part of the hashed fields — dropping it makes the
+    // record fail verifyChangeHash on the importing side.
+    protocolVersion: change.protocolVersion,
+    batchId: change.batchId,
+    batchIndex: change.batchIndex,
+    batchSize: change.batchSize
+  };
+  return record;
+}
+function fromPortableChangeRecord(record) {
+  const payload = record.payload && !record.payload.schemaId && record.schemaId ? { ...record.payload, schemaId: record.schemaId } : record.payload;
+  return {
+    id: record.id,
+    type: record.type,
+    hash: record.hash,
+    parentHash: record.parentHash,
+    authorDID: record.authorDid,
+    signature: base64ToBytes(record.signatureB64),
+    wallTime: record.wallTime,
+    lamport: record.lamportTime,
+    payload,
+    protocolVersion: record.protocolVersion,
+    batchId: record.batchId,
+    batchIndex: record.batchIndex,
+    batchSize: record.batchSize
+  };
+}
+function sortObjectKeys(obj) {
+  if (obj === null || typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) return obj.map(sortObjectKeys);
+  const sorted = {};
+  for (const key of Object.keys(obj).sort()) {
+    sorted[key] = sortObjectKeys(obj[key]);
+  }
+  return sorted;
+}
+function canonicalManifestBytes(manifest) {
+  const unsigned = { ...manifest };
+  delete unsigned.signatureB64;
+  return textEncoder.encode(JSON.stringify(sortObjectKeys(unsigned)));
+}
+function createNdjsonDigest() {
+  const lineDigests = [];
+  return {
+    addLine(line) {
+      lineDigests.push(hash(textEncoder.encode(line)));
+    },
+    finish() {
+      const concat = new Uint8Array(lineDigests.length * 32);
+      lineDigests.forEach((d, i) => concat.set(d, i * 32));
+      return hashHex(concat);
+    },
+    lineCount() {
+      return lineDigests.length;
+    }
+  };
+}
+function digestEntryBytes(bytes) {
+  return hashHex(bytes);
+}
+function combineEntryDigests(entries) {
+  const lines = [...entries.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([path, digest]) => `${path}
+${digest}
+`);
+  return hashHex(textEncoder.encode(lines.join("")));
+}
+function encodeNdjsonLine(value) {
+  return JSON.stringify(value);
+}
+function decodeUtf8(bytes) {
+  return textDecoder.decode(bytes);
+}
+function encodeUtf8(text2) {
+  return textEncoder.encode(text2);
+}
+
+// src/portability/write.ts
+import { compareChangeApplicationOrder } from "@xnetjs/core";
+import { CURRENT_PROTOCOL_VERSION } from "@xnetjs/sync";
+import { bytesToBase64 as bytesToBase642 } from "@xnetjs/crypto";
+function blobEntryPath(cid) {
+  const match = /^cid:([a-z0-9-]+):([0-9a-f]+)$/i.exec(cid);
+  if (match) return `blobs/${match[1]}/${match[2]}`;
+  return `blobs/raw/${encodeURIComponent(cid)}`;
+}
+function frontierOf(changes) {
+  let lamport = 0;
+  for (const change of changes) if (change.lamport > lamport) lamport = change.lamport;
+  const heads = changes.filter((c) => c.lamport === lamport).slice(0, FRONTIER_HEADS_CAP).map((c) => c.hash);
+  return { lamport, heads, changeCount: changes.length };
+}
+function spaceOf(properties) {
+  return properties["space"];
+}
+async function collectScopedNodeIds(store, scope) {
+  if (scope.kind === "nodes") return [...scope.nodeIds];
+  if (scope.kind === "schemas") {
+    const ids2 = [];
+    for (const schemaId of scope.schemaIds) {
+      const nodes = await store.list({ schemaId, includeDeleted: true });
+      for (const node of nodes) ids2.push(node.id);
+    }
+    return ids2;
+  }
+  if (scope.kind !== "space") return [];
+  const all = await store.list({ includeDeleted: true });
+  const ids = [];
+  for (const node of all) {
+    if (node.id === scope.spaceId) {
+      ids.push(node.id);
+      continue;
+    }
+    const space = spaceOf(node.properties);
+    if (space === scope.spaceId) ids.push(node.id);
+    else if (Array.isArray(space) && space.includes(scope.spaceId)) ids.push(node.id);
+  }
+  return ids;
+}
+async function collectChanges(store, scope, since) {
+  let changes;
+  if (scope.kind === "full") {
+    changes = since ? await store.getChangesSince(since.lamport) : await store.getAllChanges();
+  } else {
+    const nodeIds = await collectScopedNodeIds(store, scope);
+    const byHash = /* @__PURE__ */ new Map();
+    for (const nodeId of nodeIds) {
+      for (const change of await store.getChanges(nodeId)) {
+        if (!since || change.lamport > since.lamport) byHash.set(change.hash, change);
+      }
+    }
+    changes = [...byHash.values()];
+  }
+  return changes.sort(
+    (a, b) => compareChangeApplicationOrder(
+      { lamport: a.lamport, author: a.authorDID },
+      { lamport: b.lamport, author: b.authorDID }
+    )
+  );
+}
+async function writeBundle(store, scope, sink, options) {
+  const entryDigests = /* @__PURE__ */ new Map();
+  const changes = await collectChanges(store, scope, options.since);
+  const changesDigest = createNdjsonDigest();
+  const changeLines = [];
+  for (const change of changes) {
+    const line = encodeNdjsonLine(toPortableChangeRecord(change));
+    changesDigest.addLine(line);
+    changeLines.push(line);
+  }
+  await sink.writeEntry(
+    BUNDLE_ENTRY.changes,
+    encodeUtf8(changeLines.join("\n") + (changeLines.length ? "\n" : ""))
+  );
+  entryDigests.set(BUNDLE_ENTRY.changes, changesDigest.finish());
+  let blobCount = 0;
+  const blobIndexDigest = createNdjsonDigest();
+  const blobIndexLines = [];
+  if (options.blobPort) {
+    for await (const blob of options.blobPort.list()) {
+      const path = blobEntryPath(blob.cid);
+      await sink.writeEntry(path, blob.bytes);
+      entryDigests.set(path, digestEntryBytes(blob.bytes));
+      const record = {
+        cid: blob.cid,
+        path,
+        size: blob.bytes.byteLength,
+        mimeType: blob.mimeType
+      };
+      const line = encodeNdjsonLine(record);
+      blobIndexDigest.addLine(line);
+      blobIndexLines.push(line);
+      blobCount++;
+    }
+  }
+  await sink.writeEntry(
+    BUNDLE_ENTRY.blobIndex,
+    encodeUtf8(blobIndexLines.join("\n") + (blobIndexLines.length ? "\n" : ""))
+  );
+  entryDigests.set(BUNDLE_ENTRY.blobIndex, blobIndexDigest.finish());
+  let yjsCount = 0;
+  const yjsDigest = createNdjsonDigest();
+  const yjsLines = [];
+  if (options.yjsPort) {
+    for await (const doc of options.yjsPort.list()) {
+      const line = encodeNdjsonLine({ nodeId: doc.nodeId, updateB64: bytesToBase642(doc.update) });
+      yjsDigest.addLine(line);
+      yjsLines.push(line);
+      yjsCount++;
+    }
+  }
+  await sink.writeEntry(
+    BUNDLE_ENTRY.yjsDocs,
+    encodeUtf8(yjsLines.join("\n") + (yjsLines.length ? "\n" : ""))
+  );
+  entryDigests.set(BUNDLE_ENTRY.yjsDocs, yjsDigest.finish());
+  const manifest = {
+    formatVersion: XNETPACK_FORMAT_VERSION,
+    protocolVersion: { change: CURRENT_PROTOCOL_VERSION },
+    ownerDid: options.ownerDid,
+    scope,
+    createdAt: Date.now(),
+    frontier: frontierOf(changes),
+    prerequisites: options.since,
+    counts: { changes: changes.length, blobs: blobCount, yjsDocs: yjsCount },
+    contentDigest: combineEntryDigests(entryDigests)
+  };
+  if (options.manifestSigner) {
+    const signature = await options.manifestSigner(canonicalManifestBytes(manifest));
+    manifest.signatureB64 = bytesToBase642(signature);
+  }
+  await sink.writeEntry(BUNDLE_ENTRY.manifest, encodeUtf8(JSON.stringify(manifest, null, 2)));
+  return manifest;
+}
+
+// src/portability/verify.ts
+import { verifyChange, verifyChangeHash, CURRENT_PROTOCOL_VERSION as CURRENT_PROTOCOL_VERSION2 } from "@xnetjs/sync";
+import { base64ToBytes as base64ToBytes2, verify as verifySignature } from "@xnetjs/crypto";
+import { parseDID } from "@xnetjs/identity";
+function parseCidHex(path) {
+  const match = /^blobs\/([a-z0-9-]+)\/([0-9a-f]+)$/i.exec(path);
+  if (!match || match[1] === "raw") return null;
+  return { algo: match[1], hex: match[2] };
+}
+async function verifyBundle(source, options = {}) {
+  const verifyChangeSignatures = options.verifyChangeSignatures ?? true;
+  const issues = [];
+  const error = (code, detail, subject) => issues.push({ severity: "error", code, detail, subject });
+  const warning = (code, detail, subject) => issues.push({ severity: "warning", code, detail, subject });
+  const manifestBytes = await source.readEntry(BUNDLE_ENTRY.manifest);
+  if (!manifestBytes) {
+    error("unknown-format", "bundle has no manifest.json");
+    return { ok: false, manifest: null, issues, danglingParents: 0 };
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(decodeUtf8(manifestBytes));
+  } catch (err) {
+    error("unknown-format", `manifest.json is not valid JSON: ${err.message}`);
+    return { ok: false, manifest: null, issues, danglingParents: 0 };
+  }
+  if (manifest.formatVersion !== XNETPACK_FORMAT_VERSION) {
+    error("unknown-format", `unsupported formatVersion "${manifest.formatVersion}"`);
+    return { ok: false, manifest, issues, danglingParents: 0 };
+  }
+  if ((manifest.protocolVersion?.change ?? 0) > CURRENT_PROTOCOL_VERSION2) {
+    error(
+      "future-protocol",
+      `bundle uses change protocol v${manifest.protocolVersion.change}, this build supports v${CURRENT_PROTOCOL_VERSION2}`
+    );
+  }
+  if (!manifest.signatureB64) {
+    warning("manifest-unsigned", "manifest carries no signature");
+  } else {
+    try {
+      const publicKey = parseDID(manifest.ownerDid);
+      const signature = base64ToBytes2(manifest.signatureB64);
+      if (!verifySignature(canonicalManifestBytes(manifest), signature, publicKey)) {
+        error(
+          "manifest-signature-invalid",
+          `manifest signature does not verify against ${manifest.ownerDid}`
+        );
+      }
+    } catch (err) {
+      error(
+        "manifest-signature-invalid",
+        `cannot verify manifest signature: ${err.message}`
+      );
+    }
+  }
+  const entryDigests = /* @__PURE__ */ new Map();
+  const changesDigest = createNdjsonDigest();
+  const presentHashes = /* @__PURE__ */ new Set();
+  const parentHashes = [];
+  let lineNumber = 0;
+  for await (const line of source.readLines(BUNDLE_ENTRY.changes)) {
+    lineNumber++;
+    changesDigest.addLine(line);
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      error(
+        "change-unparseable",
+        `changes.ndjson line ${lineNumber} is not valid JSON`,
+        `line:${lineNumber}`
+      );
+      continue;
+    }
+    let change;
+    try {
+      change = fromPortableChangeRecord(record);
+    } catch (err) {
+      error("change-unparseable", `line ${lineNumber}: ${err.message}`, record.hash);
+      continue;
+    }
+    if (verifyChangeSignatures) {
+      if (!verifyChangeHash(change)) {
+        error(
+          "change-hash-invalid",
+          `change ${change.id} fails hash re-computation (tampered?)`,
+          record.hash
+        );
+        continue;
+      }
+      try {
+        const publicKey = parseDID(change.authorDID);
+        if (!verifyChange(change, publicKey)) {
+          error(
+            "change-signature-invalid",
+            `change ${change.id} signature does not match ${change.authorDID}`,
+            record.hash
+          );
+          continue;
+        }
+      } catch (err) {
+        error(
+          "change-signature-invalid",
+          `change ${change.id}: ${err.message}`,
+          record.hash
+        );
+        continue;
+      }
+    }
+    presentHashes.add(change.hash);
+    parentHashes.push(change.parentHash);
+  }
+  entryDigests.set(BUNDLE_ENTRY.changes, changesDigest.finish());
+  if (changesDigest.lineCount() !== manifest.counts.changes) {
+    error(
+      "count-mismatch",
+      `manifest declares ${manifest.counts.changes} changes, bundle has ${changesDigest.lineCount()}`
+    );
+  }
+  const prerequisiteHeads = new Set(manifest.prerequisites?.heads ?? []);
+  let danglingParents = 0;
+  for (const parent of parentHashes) {
+    if (parent !== null && !presentHashes.has(parent) && !prerequisiteHeads.has(parent)) {
+      danglingParents++;
+    }
+  }
+  if (danglingParents > 0) {
+    warning(
+      "dangling-parent",
+      `${danglingParents} change(s) reference parents outside the bundle (expected for scoped/incremental exports)`
+    );
+  }
+  const blobIndexDigest = createNdjsonDigest();
+  const indexedPaths = /* @__PURE__ */ new Set();
+  for await (const line of source.readLines(BUNDLE_ENTRY.blobIndex)) {
+    blobIndexDigest.addLine(line);
+    try {
+      const record = JSON.parse(line);
+      indexedPaths.add(record.path);
+    } catch {
+      error("change-unparseable", "blobs.ndjson contains an unparseable line");
+    }
+  }
+  entryDigests.set(BUNDLE_ENTRY.blobIndex, blobIndexDigest.finish());
+  if (blobIndexDigest.lineCount() !== manifest.counts.blobs) {
+    error(
+      "count-mismatch",
+      `manifest declares ${manifest.counts.blobs} blobs, index has ${blobIndexDigest.lineCount()}`
+    );
+  }
+  for (const path of await source.listEntries("blobs/")) {
+    if (path === BUNDLE_ENTRY.blobIndex) continue;
+    const bytes = await source.readEntry(path);
+    if (!bytes) continue;
+    entryDigests.set(path, digestEntryBytes(bytes));
+    const cid = parseCidHex(path);
+    if (cid && cid.algo === "blake3" && digestEntryBytes(bytes) !== cid.hex.toLowerCase()) {
+      error("blob-digest-mismatch", `blob ${path} bytes do not hash to their filename`, path);
+    }
+    if (!indexedPaths.has(path)) {
+      warning("count-mismatch", `blob entry ${path} is not listed in blobs.ndjson`, path);
+    }
+  }
+  const yjsDigest = createNdjsonDigest();
+  for await (const line of source.readLines(BUNDLE_ENTRY.yjsDocs)) {
+    yjsDigest.addLine(line);
+  }
+  entryDigests.set(BUNDLE_ENTRY.yjsDocs, yjsDigest.finish());
+  if (yjsDigest.lineCount() !== manifest.counts.yjsDocs) {
+    error(
+      "count-mismatch",
+      `manifest declares ${manifest.counts.yjsDocs} yjs docs, bundle has ${yjsDigest.lineCount()}`
+    );
+  }
+  if (combineEntryDigests(entryDigests) !== manifest.contentDigest) {
+    error("content-digest-mismatch", "entry digests do not match manifest.contentDigest");
+  }
+  return {
+    ok: !issues.some((i) => i.severity === "error"),
+    manifest,
+    issues,
+    danglingParents
+  };
+}
+
+// src/portability/apply.ts
+import { compareChangeApplicationOrder as compareChangeApplicationOrder2 } from "@xnetjs/core";
+import { base64ToBytes as base64ToBytes3 } from "@xnetjs/crypto";
+var BundleImportError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "BundleImportError";
+  }
+};
+var APPLY_BATCH_SIZE = 500;
+async function applyBundle(store, source, options) {
+  const verifyReport = await verifyBundle(source, { verifyChangeSignatures: false });
+  if (!verifyReport.ok || !verifyReport.manifest) {
+    const details = verifyReport.issues.filter((i) => i.severity === "error").map((i) => i.detail).join("; ");
+    throw new BundleImportError(`bundle failed verification: ${details}`, "verify-failed");
+  }
+  const manifest = verifyReport.manifest;
+  if (!manifest.signatureB64 && !options.allowUnsigned) {
+    throw new BundleImportError(
+      "bundle manifest is unsigned \u2014 pass allowUnsigned to import anyway",
+      "unsigned-manifest"
+    );
+  }
+  if (manifest.ownerDid !== options.importerDid && !options.allowForeignOwner) {
+    throw new BundleImportError(
+      `bundle is owned by ${manifest.ownerDid} but the importer is ${options.importerDid} \u2014 pass allowForeignOwner to import a bundle from another identity`,
+      "foreign-owner"
+    );
+  }
+  const missingPrerequisites = [];
+  if (manifest.prerequisites) {
+    for (const head of manifest.prerequisites.heads) {
+      if (!await store.hasChange(head)) missingPrerequisites.push(head);
+    }
+    if (missingPrerequisites.length > 0 && !options.ignoreMissingPrerequisites) {
+      throw new BundleImportError(
+        `store is missing ${missingPrerequisites.length} prerequisite head(s) \u2014 this incremental bundle needs its base bundle imported first (or pass ignoreMissingPrerequisites)`,
+        "missing-prerequisites"
+      );
+    }
+  }
+  const quarantined = [];
+  const quarantine = (record) => {
+    quarantined.push(record);
+    options.onQuarantine?.(record);
+  };
+  const changes = [];
+  for await (const line of source.readLines(BUNDLE_ENTRY.changes)) {
+    try {
+      changes.push(fromPortableChangeRecord(JSON.parse(line)));
+    } catch (err) {
+      quarantine({ kind: "change", subject: line.slice(0, 80), reason: err.message });
+    }
+  }
+  changes.sort(
+    (a, b) => compareChangeApplicationOrder2(
+      { lamport: a.lamport, author: a.authorDID },
+      { lamport: b.lamport, author: b.authorDID }
+    )
+  );
+  let applied = 0;
+  let duplicates = 0;
+  for (let i = 0; i < changes.length; i += APPLY_BATCH_SIZE) {
+    for (const change of changes.slice(i, i + APPLY_BATCH_SIZE)) {
+      try {
+        if (await store.hasChange(change.hash)) {
+          duplicates++;
+          continue;
+        }
+        await store.applyRemoteChange(change);
+        applied++;
+      } catch (err) {
+        quarantine({
+          kind: "change",
+          subject: change.hash,
+          reason: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+  }
+  let blobsInstalled = 0;
+  if (options.blobPort) {
+    for await (const line of source.readLines(BUNDLE_ENTRY.blobIndex)) {
+      let record;
+      try {
+        record = JSON.parse(line);
+      } catch (err) {
+        quarantine({ kind: "blob", subject: line.slice(0, 80), reason: err.message });
+        continue;
+      }
+      try {
+        if (await options.blobPort.has(record.cid)) continue;
+        const bytes = await source.readEntry(record.path);
+        if (!bytes) {
+          quarantine({
+            kind: "blob",
+            subject: record.cid,
+            reason: `bundle entry ${record.path} missing`
+          });
+          continue;
+        }
+        await options.blobPort.put(bytes, { cid: record.cid, mimeType: record.mimeType });
+        blobsInstalled++;
+      } catch (err) {
+        quarantine({ kind: "blob", subject: record.cid, reason: err.message });
+      }
+    }
+  }
+  let yjsDocsApplied = 0;
+  if (options.yjsPort) {
+    for await (const line of source.readLines(BUNDLE_ENTRY.yjsDocs)) {
+      let record;
+      try {
+        record = JSON.parse(line);
+      } catch (err) {
+        quarantine({ kind: "yjs-doc", subject: line.slice(0, 80), reason: err.message });
+        continue;
+      }
+      try {
+        await options.yjsPort.apply(record.nodeId, base64ToBytes3(record.updateB64));
+        yjsDocsApplied++;
+      } catch (err) {
+        quarantine({ kind: "yjs-doc", subject: record.nodeId, reason: err.message });
+      }
+    }
+  }
+  return { applied, duplicates, quarantined, blobsInstalled, yjsDocsApplied, missingPrerequisites };
+}
+async function readBundleManifest(source) {
+  const bytes = await source.readEntry(BUNDLE_ENTRY.manifest);
+  if (!bytes) return null;
+  try {
+    return JSON.parse(decodeUtf8(bytes));
+  } catch {
+    return null;
+  }
+}
+
+// src/portability/memory-bundle.ts
+var MemoryBundleSink = class {
+  entries = /* @__PURE__ */ new Map();
+  writeEntry(path, data) {
+    this.entries.set(path, data);
+  }
+  toSource() {
+    return new MemoryBundleSource(this.entries);
+  }
+};
+var MemoryBundleSource = class {
+  constructor(entries) {
+    this.entries = entries;
+  }
+  async readEntry(path) {
+    return this.entries.get(path) ?? null;
+  }
+  async *readLines(path) {
+    const bytes = this.entries.get(path);
+    if (!bytes) return;
+    let start = 0;
+    const text2 = decodeUtf8(bytes);
+    while (start < text2.length) {
+      let end = text2.indexOf("\n", start);
+      if (end === -1) end = text2.length;
+      const line = text2.slice(start, end);
+      if (line.length > 0) yield line;
+      start = end + 1;
+    }
+  }
+  async listEntries(prefix) {
+    return [...this.entries.keys()].filter((p) => p.startsWith(prefix)).sort();
+  }
+};
+
+// src/portability/store-yjs-port.ts
+import * as Y2 from "yjs";
+function createStoreYjsPort(store) {
+  return {
+    async *list() {
+      const nodes = await store.list({ includeDeleted: true });
+      for (const node of nodes) {
+        const content = await store.getDocumentContent(node.id);
+        if (content && content.byteLength > 0) {
+          yield { nodeId: node.id, update: content };
+        }
+      }
+    },
+    async apply(nodeId, update) {
+      const existing = await store.getDocumentContent(nodeId);
+      if (!existing || existing.byteLength === 0) {
+        await store.setDocumentContent(nodeId, update);
+        return;
+      }
+      let merged;
+      const doc = new Y2.Doc();
+      try {
+        Y2.applyUpdate(doc, existing);
+        Y2.applyUpdate(doc, update);
+        merged = Y2.encodeStateAsUpdate(doc);
+      } catch (err) {
+        throw new Error(
+          `document content for ${nodeId} is not a mergeable Yjs update (${err.message}); left the existing content untouched`
+        );
+      } finally {
+        doc.destroy();
+      }
+      await store.setDocumentContent(nodeId, merged);
+    }
+  };
+}
+
 // src/index.ts
 import {
-  Doc,
+  Doc as Doc2,
   Map as Map3,
   Array as Array2,
   Text,
@@ -2092,8 +2729,10 @@ export {
   AgentSessionSchema,
   AppealSchema,
   BUDGET_SCHEMA_IRI,
+  BUNDLE_ENTRY,
   BlobService,
   BudgetSchema,
+  BundleImportError,
   CELL_PREFIX,
   CHANNEL_KINDS,
   CHECKPOINT_SCHEMA_IRI,
@@ -2196,6 +2835,8 @@ export {
   MediaAssetSchema,
   MeetingSchema,
   MeetingTranscriptSchema,
+  MemoryBundleSink,
+  MemoryBundleSource,
   MemoryItemSchema,
   MemoryNodeStorageAdapter,
   MessageRequestSchema,
@@ -2284,8 +2925,9 @@ export {
   TranscriptionSchema,
   UserWidgetSchema,
   WorkspaceSchema,
+  XNETPACK_FORMAT_VERSION,
   Array2 as YArray,
-  Doc as YDoc,
+  Doc2 as YDoc,
   Map3 as YMap,
   Text as YText,
   XmlElement as YXmlElement,
@@ -2306,6 +2948,7 @@ export {
   agentSessionId,
   aggregate,
   and,
+  applyBundle,
   applyNodeQueryDescriptor,
   applySignedUpdate,
   asRowHeight,
@@ -2313,6 +2956,7 @@ export {
   avg,
   batchComputeRollups,
   between,
+  blobEntryPath,
   bucketPresenceCount,
   buildDatabaseSchema,
   buildEffectiveSchema,
@@ -2328,6 +2972,7 @@ export {
   bumpSchemaVersion,
   canManageSpace,
   canModifyColumn,
+  canonicalManifestBytes,
   captureUpdate,
   cellKey,
   cellValueToText,
@@ -2383,6 +3028,7 @@ export {
   createSelectOption,
   createSort,
   createSortQuery,
+  createStoreYjsPort,
   createVersionEntry,
   createView2 as createView,
   createView as createViewNode,
@@ -2458,6 +3104,7 @@ export {
   formatValue,
   from,
   fromCellProperties,
+  fromPortableChangeRecord,
   gameSchemas,
   generateColumnIdMap,
   generateSortKey,
@@ -2626,6 +3273,7 @@ export {
   queryOperators,
   queryRows,
   querySetCount,
+  readBundleManifest,
   rebalanceDatabase,
   rebalanceSortKeys,
   recoveryRecordId,
@@ -2697,6 +3345,7 @@ export {
   toCellProperties,
   toColumnDefinitions,
   toFieldNode,
+  toPortableChangeRecord,
   toSelectOptionNode,
   toggleGroupCollapsed,
   toggleGroupCollapsed2 as toggleGroupCollapsedState,
@@ -2719,11 +3368,13 @@ export {
   validateRollupConfig,
   validateSavedViewDescriptor,
   validateSchemaDefinitionNode,
+  verifyBundle,
   verifyUpdate,
   visibleFormQuestions,
   when,
   withoutNodeQueryMaterializedView,
   withoutNodeQueryPagination,
   wouldCreateFolderCycle,
-  wouldCreateSpaceCycle
+  wouldCreateSpaceCycle,
+  writeBundle
 };