@neocompose/cli 0.58.2 → 0.58.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.58.3] - 2026-09-24
+
+- Joined snapshot pages carry stored JSON. Document readers decode it after the query returns, reducing query work and allowing large numeric payloads to fit in fewer requests.
+
+- Document reads plan independent ranges before fetching payloads, with parallelism scaled to project size and deployment capacity. Pull and other document readers trade some additional reads for shorter waits; each payload page uses the available Convex limits and stays on the same published revision.
+
 ## [0.58.2] - 2026-09-24
 
 - Pull downloads up to eight managed image or audio files concurrently. Matching local bytes are still reused.

package/dist/neo.mjs

@@ -86570,6 +86570,54 @@ var init_materialize_values = __esm({
   }
 });
 
+// ../convex/convexValues.ts
+function decodeConvexOpaqueJson(value, context) {
+  if (typeof value !== "string") {
+    throw new Error(`${context} must be an encoded JSON string.`);
+  }
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${context} could not be parsed as JSON: ${message}`);
+  }
+}
+var CONVEX_DOCUMENT_WARNING_BYTES, CONVEX_DOCUMENT_MAX_BYTES;
+var init_convexValues = __esm({
+  "../convex/convexValues.ts"() {
+    "use strict";
+    CONVEX_DOCUMENT_WARNING_BYTES = 750 * 1024;
+    CONVEX_DOCUMENT_MAX_BYTES = 1024 * 1024;
+  }
+});
+
+// ../convex/projectRecordSnapshotStorage.ts
+function decodeProjectRecordSnapshotData(snapshot, context = `Project record snapshot for ${snapshot.recordKind} "${snapshot.recordId}" dataJson`) {
+  const decoded = decodeConvexOpaqueJson(snapshot.dataJson, context);
+  if (!isPlainRecord(decoded)) return decoded;
+  const hydratedData = { ...decoded };
+  if (snapshot.recordKind === "enum" && !Object.hasOwn(hydratedData, "optionKeyOrder") && isPlainRecord(hydratedData.options)) {
+    hydratedData.optionKeyOrder = Object.keys(hydratedData.options);
+  }
+  hydratedData.id = snapshot.recordId;
+  if (snapshot.recordKind !== "project") {
+    hydratedData.projectId = snapshot.projectId;
+  }
+  if (!Object.hasOwn(hydratedData, "updatedAt")) {
+    hydratedData.updatedAt = snapshot.createdAt;
+  }
+  return hydratedData;
+}
+function isPlainRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var init_projectRecordSnapshotStorage = __esm({
+  "../convex/projectRecordSnapshotStorage.ts"() {
+    "use strict";
+    init_convexValues();
+  }
+});
+
 // ../src/database/project-read-base.ts
 import { ConvexError } from "convex/values";
 function readProjectReadBase(value) {
@@ -86887,6 +86935,7 @@ var project_document_read_exports = {};
 __export(project_document_read_exports, {
   DOCUMENT_MANIFEST_PAGE_SIZE: () => DOCUMENT_MANIFEST_PAGE_SIZE,
   assembleProjectDocumentRaw: () => assembleProjectDocumentRaw,
+  createDocumentPageReader: () => createDocumentPageReader,
   fetchProjectDocumentPartitionRecords: () => fetchProjectDocumentPartitionRecords,
   fetchProjectDocumentRawChunked: () => fetchProjectDocumentRawChunked,
   fetchProjectDocumentRawChunkedOnce: () => fetchProjectDocumentRawChunkedOnce,
@@ -86944,46 +86993,14 @@ async function fetchProjectDocumentRawChunkedOnce(runner, options = {}) {
   };
   try {
     await rememberRecords(firstPage);
-    const fetchRemainingPages = async (mapKey, initialCursor) => {
-      let cursor = initialCursor;
-      while (cursor !== null) {
-        const pageResult = await runner.fetchPage(
-          {
-            numItems: DOCUMENT_MANIFEST_PAGE_SIZE,
-            cursor
-          },
-          mapKey,
-          readBase
-        );
-        if (pageResult === null) {
-          throw new Error(
-            "Convex project document manifest returned null for a continuation page."
-          );
-        }
-        const page = readProjectDocumentPage(pageResult);
-        assertProjectReadBase(readBase, page.readBase);
-        await rememberRecords(page);
-        cursor = page.continueCursor;
-      }
-    };
-    await fetchRemainingPages(firstMapKey, firstPage.continueCursor);
-    for (const mapKey of mapKeys.slice(1)) {
-      const pageResult = await runner.fetchPage(
-        { numItems: DOCUMENT_MANIFEST_PAGE_SIZE, cursor: null },
-        mapKey,
-        readBase,
-        "omit"
-      );
-      if (pageResult === null) {
-        throw new Error(
-          `Convex project document manifest returned null for partition "${mapKey ?? "all"}".`
-        );
-      }
-      const page = readProjectDocumentPage(pageResult);
-      assertProjectReadBase(readBase, page.readBase);
-      await rememberRecords(page);
-      await fetchRemainingPages(mapKey, page.continueCursor);
-    }
+    const pages = createDocumentPageReader(runner, firstPage.readConcurrency);
+    await drainDocumentReads([
+      pages.remaining(firstPage, firstMapKey, readBase, rememberRecords),
+      ...mapKeys.slice(1).map(async (mapKey) => {
+        const page = await pages.first(mapKey, readBase, rememberRecords);
+        await pages.remaining(page, mapKey, readBase, rememberRecords);
+      })
+    ]);
     const snapshotsById = await snapshots.finish();
     if (options.mapKeys !== void 0 && !options.mapKeys.includes("all")) {
       const members = [];
@@ -87043,28 +87060,15 @@ async function fetchProjectDocumentPartitionRecords(runner, mapKey, readBase) {
     (ids) => fetchScopedSnapshotBatch(runner, ids, readBase)
   );
   try {
-    let cursor = null;
-    do {
-      const pageResult = await runner.fetchPage(
-        { numItems: DOCUMENT_MANIFEST_PAGE_SIZE, cursor },
-        mapKey,
-        readBase,
-        "omit"
-      );
-      if (pageResult === null) {
-        throw new Error(
-          `Convex project document manifest returned null for partition "${mapKey}".`
-        );
-      }
-      const page = readProjectDocumentPage(pageResult);
-      assertProjectReadBase(readBase, page.readBase);
-      for (const record6 of page.records) {
+    const pages = createDocumentPageReader(runner);
+    const remember = async (page) => {
+      for (const record6 of page.records)
         recordsByKey.set(`${record6.recordKind} ${record6.recordId}`, record6);
-      }
       if (page.snapshots !== void 0) snapshots.seed(page.snapshots);
       await snapshots.enqueue(page.records.map((record6) => record6.snapshotId));
-      cursor = page.continueCursor;
-    } while (cursor !== null);
+    };
+    const first = await pages.first(mapKey, readBase, remember);
+    await pages.remaining(first, mapKey, readBase, remember);
     const snapshotsById = await snapshots.finish();
     await runner.validateReadBase(readBase);
     return [...recordsByKey.values()].map((record6) => {
@@ -87086,6 +87090,84 @@ async function fetchProjectDocumentPartitionRecords(runner, mapKey, readBase) {
     await snapshots.stop();
   }
 }
+function createDocumentPageReader(runner, concurrency) {
+  let active = 0;
+  let nextWaiter = 0;
+  let waiters = [];
+  let failure;
+  const readPage = async (pagination, mapKey, readBase, remember) => {
+    if (active >= (concurrency ?? 1))
+      await new Promise((resolve5) => waiters.push(resolve5));
+    else active++;
+    try {
+      if (failure !== void 0) throw failure.error;
+      const raw = await runner.fetchPage(pagination, mapKey, readBase, "omit");
+      if (raw === null)
+        throw new Error(
+          `Missing document page for partition "${mapKey ?? "all"}".`
+        );
+      const page = readProjectDocumentPage(raw);
+      assertProjectReadBase(readBase, page.readBase);
+      concurrency ??= page.readConcurrency ?? 1;
+      if (pagination.cursor !== null && page.continueCursor === pagination.cursor)
+        throw new Error("Document continuation made no progress.");
+      if (pagination.endCursor != null && page.continueCursor === null)
+        throw new Error("Document range ended before its endpoint.");
+      await remember(page, pagination.cursor);
+      return page;
+    } catch (error) {
+      failure ??= { error };
+      throw error;
+    } finally {
+      const next = waiters[nextWaiter++];
+      if (next !== void 0) next();
+      else {
+        active--;
+        nextWaiter = 0;
+        waiters = [];
+      }
+    }
+  };
+  return {
+    first(mapKey, readBase, remember) {
+      return readPage(
+        { numItems: DOCUMENT_MANIFEST_PAGE_SIZE, cursor: null },
+        mapKey,
+        readBase,
+        remember
+      );
+    },
+    async remaining(first, mapKey, readBase, remember) {
+      if (first.continueCursor === null) return;
+      const ranges = first.remainingRanges ?? [
+        { cursor: first.continueCursor, endCursor: null }
+      ];
+      await drainDocumentReads(
+        ranges.map(async (range2) => {
+          let cursor = range2.cursor;
+          while (cursor !== null && cursor !== range2.endCursor) {
+            const page = await readPage(
+              {
+                numItems: DOCUMENT_MANIFEST_PAGE_SIZE,
+                cursor,
+                endCursor: range2.endCursor
+              },
+              mapKey,
+              readBase,
+              remember
+            );
+            cursor = page.continueCursor;
+          }
+        })
+      );
+    }
+  };
+}
+async function drainDocumentReads(reads) {
+  const results = await Promise.allSettled(reads);
+  for (const result of results)
+    if (result.status === "rejected") throw result.reason;
+}
 async function fetchProjectDocumentValueRecords(runner, valueIds, readBase) {
   if (runner.fetchValueSnapshotsPage === void 0) {
     throw new Error(
@@ -87151,6 +87233,41 @@ function readProjectDocumentPage(value) {
       "Convex project document manifest page continueCursor must be a string or null."
     );
   }
+  let remainingRanges;
+  if (value.remainingRanges !== void 0) {
+    if (!Array.isArray(value.remainingRanges))
+      throw new Error("Snapshot remaining ranges must be an array.");
+    remainingRanges = [];
+    let expectedCursor = continueCursor;
+    for (const range2 of value.remainingRanges) {
+      if (!isObject4(range2))
+        throw new Error("Snapshot range must be an object.");
+      if (typeof range2.cursor !== "string")
+        throw new Error("Snapshot range cursor must be a string.");
+      if (range2.endCursor !== null && typeof range2.endCursor !== "string")
+        throw new Error("Snapshot range end cursor must be a string or null.");
+      if (range2.cursor !== expectedCursor)
+        throw new Error("Snapshot ranges must form a contiguous continuation.");
+      if (range2.cursor === range2.endCursor)
+        throw new Error("Snapshot range must make progress.");
+      remainingRanges.push({
+        cursor: range2.cursor,
+        endCursor: range2.endCursor
+      });
+      expectedCursor = range2.endCursor;
+    }
+    if (expectedCursor !== null)
+      throw new Error("Snapshot ranges must cover the entire remaining tail.");
+  }
+  const readConcurrency = value.readConcurrency;
+  if (readConcurrency !== void 0) {
+    if (typeof readConcurrency !== "number")
+      throw new Error("Document read concurrency must be a number.");
+    if (!Number.isSafeInteger(readConcurrency))
+      throw new Error("Document read concurrency must be a safe integer.");
+    if (readConcurrency < 1)
+      throw new Error("Document read concurrency must be positive.");
+  }
   const metadata = value.metadata ?? null;
   if (metadata !== null && !isObject4(metadata)) {
     throw new Error(
@@ -87167,6 +87284,8 @@ function readProjectDocumentPage(value) {
       releaseChannels: metadata.releaseChannels,
       documentRevision: metadata.documentRevision
     },
+    ...remainingRanges === void 0 ? {} : { remainingRanges },
+    ...readConcurrency === void 0 ? {} : { readConcurrency },
     ...snapshots === void 0 ? {} : { snapshots },
     records: snapshots === void 0 ? readProjectDocumentManifestRecords(value.records) : snapshots.map((snapshot) => ({
       recordKind: snapshot.recordKind,
@@ -87220,7 +87339,21 @@ function readProjectDocumentManifestPageRecords(value) {
   if (!isObject4(value)) {
     throw new Error("Convex project document manifest page must be an object.");
   }
-  return readProjectDocumentPage(value).records;
+  if (value.snapshots === void 0)
+    return readProjectDocumentManifestRecords(value.records);
+  if (!Array.isArray(value.snapshots))
+    throw new Error("Snapshot page snapshots must be an array.");
+  return readProjectDocumentManifestRecords(
+    value.snapshots.map((snapshot) => {
+      if (!isObject4(snapshot))
+        throw new Error("Snapshot page entry must be an object.");
+      return {
+        recordKind: snapshot.recordKind,
+        recordId: snapshot.recordId,
+        snapshotId: snapshot.id
+      };
+    })
+  );
 }
 async function fetchProjectDocumentSnapshots(fetchBatch, snapshotIds) {
   const loader = createProjectDocumentSnapshotLoader(fetchBatch);
@@ -87236,6 +87369,7 @@ function createProjectDocumentSnapshotLoader(fetchBatch) {
   const snapshotsById = /* @__PURE__ */ new Map();
   const active = /* @__PURE__ */ new Set();
   let pending = [];
+  let enqueued = Promise.resolve();
   let stopped = false;
   let failure;
   const checkFailure = () => {
@@ -87272,17 +87406,21 @@ function createProjectDocumentSnapshotLoader(fetchBatch) {
         snapshotsById.set(snapshot.id, snapshot);
       }
     },
-    async enqueue(snapshotIds) {
-      checkFailure();
-      for (const id2 of snapshotIds) {
-        if (seen.has(id2)) continue;
-        seen.add(id2);
-        pending.push(id2);
-        if (pending.length === DOCUMENT_SNAPSHOT_FETCH_CHUNK_SIZE)
-          await flush();
-      }
+    enqueue(snapshotIds) {
+      enqueued = enqueued.then(async () => {
+        checkFailure();
+        for (const id2 of snapshotIds) {
+          if (seen.has(id2)) continue;
+          seen.add(id2);
+          pending.push(id2);
+          if (pending.length === DOCUMENT_SNAPSHOT_FETCH_CHUNK_SIZE)
+            await flush();
+        }
+      });
+      return enqueued;
     },
     async finish() {
+      await enqueued;
       await flush();
       await Promise.all(active);
       checkFailure();
@@ -87290,6 +87428,8 @@ function createProjectDocumentSnapshotLoader(fetchBatch) {
     },
     async stop() {
       stopped = true;
+      await enqueued.catch(() => {
+      });
       await Promise.all(active);
     }
   };
@@ -87361,6 +87501,30 @@ function readProjectDocumentSnapshotBatch(value, requestedIds) {
         `Convex project record snapshot "${snapshot.id}" is missing a content hash.`
       );
     }
+    let data = snapshot.data;
+    if ("dataJson" in snapshot) {
+      if (typeof snapshot.dataJson !== "string")
+        throw new Error(`Snapshot "${snapshot.id}" dataJson must be a string.`);
+      if (typeof snapshot.projectId !== "string")
+        throw new Error(
+          `Snapshot "${snapshot.id}" projectId must be a string.`
+        );
+      if (typeof snapshot.createdAt !== "number")
+        throw new Error(
+          `Snapshot "${snapshot.id}" createdAt must be a number.`
+        );
+      if (!Number.isFinite(snapshot.createdAt))
+        throw new Error(
+          `Snapshot "${snapshot.id}" createdAt must be finite milliseconds.`
+        );
+      data = decodeProjectRecordSnapshotData({
+        projectId: snapshot.projectId,
+        recordKind,
+        recordId: snapshot.recordId,
+        createdAt: snapshot.createdAt,
+        dataJson: snapshot.dataJson
+      });
+    }
     return {
       id: snapshot.id,
       recordKind,
@@ -87371,7 +87535,7 @@ function readProjectDocumentSnapshotBatch(value, requestedIds) {
       data: readCurrentProjectRecordData({
         recordKind,
         dataSchemaVersion: snapshot.dataSchemaVersion,
-        data: snapshot.data
+        data
       })
     };
   });
@@ -87693,6 +87857,7 @@ var DOCUMENT_MANIFEST_PAGE_SIZE, DOCUMENT_SNAPSHOT_FETCH_CHUNK_SIZE, DOCUMENT_SN
 var init_project_document_read = __esm({
   "../src/database/project-document-read.ts"() {
     "use strict";
+    init_projectRecordSnapshotStorage();
     init_project_read_base();
     init_project2();
     init_members();
@@ -87711,7 +87876,7 @@ var init_project_document_read = __esm({
     init_projectRecordBuckets();
     init_project_record_migrations();
     init_member_default_reference_ids();
-    DOCUMENT_MANIFEST_PAGE_SIZE = 2048;
+    DOCUMENT_MANIFEST_PAGE_SIZE = 8192;
     DOCUMENT_SNAPSHOT_FETCH_CHUNK_SIZE = 128;
     DOCUMENT_SNAPSHOT_FETCH_CONCURRENCY = 4;
   }
@@ -88394,7 +88559,7 @@ var init_commit_preparation_scope_planner = __esm({
 
 // ../src/database/project-record-semantics.ts
 function projectRecordSemanticData(value) {
-  if (!isPlainRecord(value)) return value;
+  if (!isPlainRecord2(value)) return value;
   const semantic = {};
   for (const [key, child] of Object.entries(value)) {
     if (SERVER_MANAGED_PROJECT_RECORD_FIELDS.has(key)) continue;
@@ -88431,7 +88596,7 @@ function toCanonicalJsonValue2(value) {
   if (Array.isArray(value)) {
     return value.map((item) => toCanonicalJsonValue2(item) ?? null);
   }
-  if (!isPlainRecord(value)) {
+  if (!isPlainRecord2(value)) {
     throw new Error("Cannot canonicalize a non-plain object.");
   }
   const canonical = {};
@@ -88445,7 +88610,7 @@ function toCanonicalJsonValue2(value) {
   }
   return canonical;
 }
-function isPlainRecord(value) {
+function isPlainRecord2(value) {
   if (value === null || typeof value !== "object") return false;
   const prototype = Object.getPrototypeOf(value);
   return prototype === Object.prototype || prototype === null;
@@ -88479,7 +88644,7 @@ function stagedChangesAffectClassRelations(current, changes) {
       const before2 = classesById.get(change.recordId);
       if (before2 === void 0) return true;
       const after = change.nextData;
-      if (!isPlainRecord2(after)) return true;
+      if (!isPlainRecord3(after)) return true;
       if (before2.extendsClassId !== after.extendsClassId) return true;
       continue;
     }
@@ -88498,11 +88663,11 @@ function valueCreateCannotAffectClassRelations(change, before) {
   return before === void 0;
 }
 function relationEndpointClassId(record6) {
-  if (!isPlainRecord2(record6)) return void 0;
+  if (!isPlainRecord3(record6)) return void 0;
   if (typeof record6.classId === "string") return record6.classId;
   return void 0;
 }
-function isPlainRecord2(value) {
+function isPlainRecord3(value) {
   if (value === null || typeof value !== "object") return false;
   return !Array.isArray(value);
 }
@@ -88558,7 +88723,7 @@ function assertWorldFootprintEntryTypes(document, changes) {
     if (change.recordKind !== "value" || change.operation === "delete" || change.deleted)
       continue;
     referencedIds2.add(change.recordId);
-    if (isPlainRecord3(change.nextData) && Array.isArray(change.nextData.value)) {
+    if (isPlainRecord4(change.nextData) && Array.isArray(change.nextData.value)) {
       for (const id2 of change.nextData.value)
         if (typeof id2 === "string") referencedIds2.add(id2);
     }
@@ -88595,14 +88760,14 @@ function createdWorldPlacementIds(changes, worldKinds) {
 }
 function hasWorldPlacementBinding(value, worldKinds) {
   if (hasWorldPlacementSidecar(value)) return true;
-  if (!isPlainRecord3(value) || typeof value.containerId !== "string")
+  if (!isPlainRecord4(value) || typeof value.containerId !== "string")
     return false;
   if (typeof value.classId !== "string") return false;
   const kind = worldKinds?.get(value.classId);
   return kind === NeoWorldSystemClassKind.Tile;
 }
 function hasWorldPlacementSidecar(value) {
-  if (!isPlainRecord3(value) || !isPlainRecord3(value.value)) return false;
+  if (!isPlainRecord4(value) || !isPlainRecord4(value.value)) return false;
   const body = value.value;
   if (typeof body.assetClassId === "string") return true;
   if (typeof body.assetValueId === "string") return true;
@@ -88616,7 +88781,7 @@ function worldPlacementBindingChanged(before, after) {
   );
 }
 function worldPlacementBindingSlice(value) {
-  if (!isPlainRecord3(value) || !isPlainRecord3(value.value)) return null;
+  if (!isPlainRecord4(value) || !isPlainRecord4(value.value)) return null;
   return {
     classId: value.classId ?? null,
     containerId: value.containerId ?? null,
@@ -88635,13 +88800,13 @@ function ownedSparseValueBindingChanged(before, after) {
   );
 }
 function ownedSparseValueBindingSlice(value) {
-  if (!isPlainRecord3(value)) return null;
+  if (!isPlainRecord4(value)) return null;
   return {
     classId: value.classId ?? null,
     containerId: value.containerId ?? null
   };
 }
-function isPlainRecord3(value) {
+function isPlainRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function stagedChangesRequireWorldLayerBindingValidation(current, changes) {
@@ -88657,14 +88822,14 @@ function stagedChangesRequireWorldLayerBindingValidation(current, changes) {
       continue;
     }
     if (change.recordKind !== "class") continue;
-    if (change.operation === "create" && change.deleted !== true && !classesById.has(change.recordId) && isPlainRecord3(change.nextData) && change.nextData.extendsClassId == null && change.nextData.system == null)
+    if (change.operation === "create" && change.deleted !== true && !classesById.has(change.recordId) && isPlainRecord4(change.nextData) && change.nextData.extendsClassId == null && change.nextData.system == null)
       continue;
     if (change.operation !== "update") return true;
     if (change.deleted === true) return true;
     const before = classesById.get(change.recordId);
     if (before === void 0) return true;
     const after = change.nextData;
-    if (!isPlainRecord3(after)) return true;
+    if (!isPlainRecord4(after)) return true;
     if (before.extendsClassId !== after.extendsClassId) return true;
     if (isAbstractClass(before) !== isAbstractClass(after)) return true;
     if (!worldClassSystemBlockIsEqual(before.system, after.system)) return true;
@@ -88686,12 +88851,12 @@ function stagedChangesRequireWorldLayerBindingValidation(current, changes) {
       before,
       change.deleted === true || change.operation === "delete" ? null : change.nextData
     ) ? [before, change.nextData] : []) {
-      if (!isPlainRecord3(row) || typeof row.containerId !== "string") continue;
+      if (!isPlainRecord4(row) || typeof row.containerId !== "string") continue;
       for (const owner of [
         valuesById.get(row.containerId),
         changedValuesById.get(row.containerId)
       ]) {
-        if (isPlainRecord3(owner) && isPlainRecord3(owner.value) && owner.value.assetValueId === change.recordId)
+        if (isPlainRecord4(owner) && isPlainRecord4(owner.value) && owner.value.assetValueId === change.recordId)
           return true;
       }
     }
@@ -88714,9 +88879,9 @@ function worldClassSystemBlockIsEqual(before, after) {
   );
 }
 function hasWorldLayerOverrideMetadata(record6) {
-  if (!isPlainRecord3(record6)) return false;
+  if (!isPlainRecord4(record6)) return false;
   const value = record6.value;
-  if (!isPlainRecord3(value)) return false;
+  if (!isPlainRecord4(value)) return false;
   return typeof value.layerOverrideValueId === "string";
 }
 var init_project_world_placement_bindings = __esm({
@@ -106579,7 +106744,7 @@ function systemProtectedWriteInheritedRecordId(write) {
     return null;
   if (write.deleted) return null;
   if (!isSystemBearingRecordKind(write.recordKind)) return null;
-  if (!isPlainRecord4(write.nextData)) return null;
+  if (!isPlainRecord5(write.nextData)) return null;
   if (readSystemMetadata(write.nextData) === null) return null;
   const extendsMemberId = write.nextData.extendsMemberId;
   if (typeof extendsMemberId !== "string") return null;
@@ -106599,7 +106764,7 @@ function assertSystemProtectedRecordWriteValid(write) {
   assertSystemMetadataUnchanged(write, base);
 }
 function readBaseRecord(write) {
-  if (!isPlainRecord4(write.baseData)) return null;
+  if (!isPlainRecord5(write.baseData)) return null;
   return {
     recordKind: write.recordKind,
     data: write.baseData,
@@ -106612,7 +106777,7 @@ function collectSystemBearingBaseRecords(document) {
     const stored = document[collection];
     if (!Array.isArray(stored)) continue;
     for (const record6 of stored) {
-      if (!isPlainRecord4(record6)) continue;
+      if (!isPlainRecord5(record6)) continue;
       const id2 = record6.id;
       if (typeof id2 !== "string") continue;
       records2.set(baseKey(recordKind, id2), {
@@ -106626,7 +106791,7 @@ function collectSystemBearingBaseRecords(document) {
 }
 function assertCreateDeclaresNoSystemMetadata(write) {
   if (!isSystemBearingRecordKind(write.recordKind)) return;
-  if (!isPlainRecord4(write.nextData)) return;
+  if (!isPlainRecord5(write.nextData)) return;
   const system = readSystemMetadata(write.nextData);
   if (system === null) return;
   if (inheritsLegacyEmittedSystemMetadata(write, system)) return;
@@ -106652,11 +106817,11 @@ function assertProtectedRecordNotEdited(change, base) {
   )) {
     return;
   }
-  if (!isPlainRecord4(change.nextData)) return;
+  if (!isPlainRecord5(change.nextData)) return;
   if (authoredFieldsEqual(change.recordKind, base.data, change.nextData)) {
     return;
   }
-  if (isInheritedWorldDefaultEdit(change) && isPlainRecord4(change.inheritedBaseData) && change.inheritedBaseData.id === base.data.extendsMemberId && systemMetadataEqual(
+  if (isInheritedWorldDefaultEdit(change) && isPlainRecord5(change.inheritedBaseData) && change.inheritedBaseData.id === base.data.extendsMemberId && systemMetadataEqual(
     base.system,
     readSystemMetadata(change.inheritedBaseData)
   ))
@@ -106668,7 +106833,7 @@ function assertProtectedRecordNotEdited(change, base) {
 function isInheritedWorldDefaultEdit(write) {
   if (write.recordKind !== "member" || write.recordId.startsWith("system_"))
     return false;
-  if (write.deleted || !isPlainRecord4(write.baseData) || !isPlainRecord4(write.nextData))
+  if (write.deleted || !isPlainRecord5(write.baseData) || !isPlainRecord5(write.nextData))
     return false;
   if (readSystemMetadata(write.baseData)?.kind !== SystemProtectionKind.WorldAuthoring)
     return false;
@@ -106684,7 +106849,7 @@ function isInheritedWorldDefaultEdit(write) {
   );
 }
 function assertSystemMetadataUnchanged(change, base) {
-  if (!isPlainRecord4(change.nextData)) return;
+  if (!isPlainRecord5(change.nextData)) return;
   const next = readSystemMetadata(change.nextData);
   if (systemMetadataEqual(base.system, next)) return;
   throw new Error(
@@ -106735,10 +106900,10 @@ function repointedChildValueIds(document, change) {
   );
   if (baseValue === void 0) return [];
   const before = baseValue.value;
-  if (!isPlainRecord4(before)) return [];
-  if (!isPlainRecord4(change.nextData)) return [];
+  if (!isPlainRecord5(before)) return [];
+  if (!isPlainRecord5(change.nextData)) return [];
   const after = change.nextData.value;
-  if (!isPlainRecord4(after)) return [];
+  if (!isPlainRecord5(after)) return [];
   return Object.entries(before).flatMap(([schemaKey, childValueId2]) => {
     if (typeof childValueId2 !== "string") return [];
     if (after[schemaKey] === childValueId2) return [];
@@ -106773,7 +106938,7 @@ function isSystemBearingRecordKind(recordKind) {
   );
 }
 function readSystemMetadata(record6) {
-  if (!isPlainRecord4(record6)) return null;
+  if (!isPlainRecord5(record6)) return null;
   const system = record6.system;
   if (!isSystemMetadata(system)) return null;
   return system;
@@ -106792,11 +106957,11 @@ function systemReason(system) {
   return SYSTEM_PROTECTION_RULES[system.kind].serverReason;
 }
 function describeChangedRecord(recordKind, recordId, record6) {
-  const name = isPlainRecord4(record6) ? record6.name : void 0;
+  const name = isPlainRecord5(record6) ? record6.name : void 0;
   if (typeof name !== "string") return `Record ${recordKind} "${recordId}"`;
   return `Record ${recordKind} "${name}" (${recordId})`;
 }
-function isPlainRecord4(value) {
+function isPlainRecord5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function baseKey(recordKind, recordId) {
@@ -106927,7 +107092,7 @@ function readWorldReferenceList(args) {
     args.keyCandidates
   );
   if (schemaKey === null) return [];
-  if (!isPlainRecord5(args.ownerValue.value)) return [];
+  if (!isPlainRecord6(args.ownerValue.value)) return [];
   const listValueId = args.ownerValue.value[schemaKey];
   if (typeof listValueId !== "string") return [];
   const listValue2 = args.graph.valuesById.get(listValueId);
@@ -106993,18 +107158,18 @@ function worldReferenceClassInherits(graph, classId, ancestorClassId) {
   return false;
 }
 function toWorldReferenceClassRecord(value) {
-  if (!isPlainRecord5(value)) return null;
+  if (!isPlainRecord6(value)) return null;
   const id2 = stringField2(value, "id");
   if (id2 === null) return null;
   return {
     id: id2,
     extendsClassId: nullableStringField(value, "extendsClassId"),
     schema: isStringRecord8(value.schema) ? value.schema : void 0,
-    system: isPlainRecord5(value.system) ? value.system : null
+    system: isPlainRecord6(value.system) ? value.system : null
   };
 }
 function toWorldReferenceValueRecord(value) {
-  if (!isPlainRecord5(value)) return null;
+  if (!isPlainRecord6(value)) return null;
   const id2 = stringField2(value, "id");
   if (id2 === null) return null;
   return {
@@ -107018,10 +107183,10 @@ function worldReferenceValueClassId(value) {
   return typeof value.classId === "string" && value.classId.length > 0 ? value.classId : null;
 }
 function isStringRecord8(value) {
-  if (!isPlainRecord5(value)) return false;
+  if (!isPlainRecord6(value)) return false;
   return Object.values(value).every((entry) => typeof entry === "string");
 }
-function isPlainRecord5(value) {
+function isPlainRecord6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function stringField2(value, key) {
@@ -107603,7 +107768,7 @@ function stagedAffectedWorldLayerLinkClassIds(args) {
       change.nextData
     ];
     for (const candidate of candidates) {
-      if (!isPlainRecord2(candidate)) continue;
+      if (!isPlainRecord3(candidate)) continue;
       const relationKind = candidate.relationKind;
       if (typeof relationKind !== "string") continue;
       if (!isStagedWorldLayerLinkTargetRelationKind(relationKind)) continue;
@@ -107788,7 +107953,7 @@ function candidateActionListenerRowIds(projected, actions) {
   for (const row of projected.values) {
     if (storedRowActionListeners(row).length > 0) candidates.add(row.id);
     if (actionSchemaKeys.size === 0) continue;
-    if (!isPlainRecord2(row.value)) continue;
+    if (!isPlainRecord3(row.value)) continue;
     for (const schemaKey of actionSchemaKeys) {
       const childId = row.value[schemaKey];
       if (typeof childId === "string") candidates.add(childId);
@@ -107798,7 +107963,7 @@ function candidateActionListenerRowIds(projected, actions) {
 }
 function storedRowActionListeners(row) {
   const body = row.value;
-  if (!isPlainRecord2(body)) return [];
+  if (!isPlainRecord3(body)) return [];
   const listeners = body.listeners;
   return Array.isArray(listeners) ? listeners : [];
 }
@@ -107876,7 +108041,7 @@ function authoredActionListeners(action) {
   if (defaultValue === void 0 || defaultValue === null) return [];
   if (!isLiteralValueContent(defaultValue)) return [];
   const body = defaultValue.value;
-  if (!isPlainRecord2(body)) return [];
+  if (!isPlainRecord3(body)) return [];
   const listeners = body.listeners;
   return Array.isArray(listeners) ? listeners : [];
 }
@@ -108238,7 +108403,7 @@ function candidateVariantRowIds(projected, variantMembers) {
       candidates.add(row.id);
     }
     if (schemaKeys.size === 0) continue;
-    if (!isPlainRecord2(row.value)) continue;
+    if (!isPlainRecord3(row.value)) continue;
     for (const [schemaKey, childId] of Object.entries(row.value)) {
       if (schemaKeys.has(schemaKey) && typeof childId === "string")
         candidates.add(childId);
@@ -130577,27 +130742,6 @@ var init_convex = __esm({
   }
 });
 
-// ../convex/convexValues.ts
-function decodeConvexOpaqueJson(value, context) {
-  if (typeof value !== "string") {
-    throw new Error(`${context} must be an encoded JSON string.`);
-  }
-  try {
-    return JSON.parse(value);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`${context} could not be parsed as JSON: ${message}`);
-  }
-}
-var CONVEX_DOCUMENT_WARNING_BYTES, CONVEX_DOCUMENT_MAX_BYTES;
-var init_convexValues = __esm({
-  "../convex/convexValues.ts"() {
-    "use strict";
-    CONVEX_DOCUMENT_WARNING_BYTES = 750 * 1024;
-    CONVEX_DOCUMENT_MAX_BYTES = 1024 * 1024;
-  }
-});
-
 // ../src/database/project-version-transaction-result.ts
 function decodeProjectVersionTransactionResultPage(page) {
   const assignments = {};
@@ -140680,7 +140824,7 @@ var init_registry2 = __esm({
   "schema-contract/registry.mjs"() {
     "use strict";
     PROJECT_SCHEMA_CONTRACT = Object.freeze({
-      cliVersion: "0.58.2",
+      cliVersion: "0.58.3",
       projectFileUploadBatchSize: 32,
       documentRecords: {
         member: {
@@ -148501,7 +148645,7 @@ There is no --keep-current: preserving current semantic state defines flatten.
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.command === "--version") {
-    console.log("0.58.2");
+    console.log("0.58.3");
     return;
   }
   if (args.command === null || args.command === "help" || args.command === "--help" || args.command === "-h") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.58.2",
+  "version": "0.58.3",
   "description": "Neo Compose native project-source CLI with bidirectional sync.",
   "license": "MIT",
   "type": "module",

package/skills/neocompose-cli/SKILL.md

@@ -9,7 +9,7 @@ description: >-
   `@neocompose/cli` or `node cli/bin/neo.mjs` in the neo-compose repository.
 ---
 
-<!-- reviewed-through-cli: 0.58.2 -->
+<!-- reviewed-through-cli: 0.58.3 -->
 
 # Neo Compose CLI
 

package/skills/neocompose-cli/references/cli-development.md

@@ -97,7 +97,7 @@ wrappers.
 The marker near the top of `SKILL.md` must exactly match the package version:
 
 ```html
-<!-- reviewed-through-cli: 0.58.2 -->
+<!-- reviewed-through-cli: 0.58.3 -->
 ```
 
 The quoted version above is checked too, so this instruction cannot go stale

package/skills/neocompose-cli/references/commands-and-sync.md

@@ -66,8 +66,9 @@ matching local bytes. It verifies all downloads before replacing binaries or
 updating conflict artifacts. A failed transfer leaves existing files intact;
 retry the pull after resolving the reported download error.
 
-Pull pins every page and snapshot batch to one published generation and logical
-revision. If either changes during assembly, the CLI discards the attempt and
+Full document pulls size pages against Convex resource limits and fetch
+independent remaining ranges concurrently. Pull pins every page and snapshot
+batch to one published generation and logical revision. If either changes during assembly, the CLI discards the attempt and
 restarts. Upgrade the CLI together with the P83 server read protocol.
 
 Treat `neo push --dry-run` as a full local commit rehearsal: source emission,