@neocompose/cli 0.22.0 → 0.22.2

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.22.2] - 2026-08-04
+
+### Changed
+
+- Dependency-selected NeoScript preparation narrows source-only bodies by
+  recoverable changed-contract identifiers instead of recompiling every body
+  without stored IR. Structurally affected owners and source that cannot be
+  lexically recovered retain the conservative fallback.
+- Optimized-versus-exhaustive fuzz parity now covers class, enum, value,
+  dialogue-node, and dialogue-group edits in addition to member edits.
+- Normal `neo pull` persists a transaction cursor and downloads only records
+  changed since the previous sync. Source-neutral deltas update local state
+  without rebuilding the complete canonical project source.
+
+## [0.22.1] - 2026-08-04
+
+### Fixed
+
+- The published `neo` executable retains its Node.js shebang, and package
+  verification checks the packed bin target and invokes it directly before
+  release.
+
 ## [0.22.0] - 2026-08-04
 
 ### Added

package/README.md

@@ -92,7 +92,10 @@ neo init --project <id> --version <id> --dir neo
 
 For an existing format-4 workspace, `neo pull --reset` regenerates canonical
 source and managed binaries. Normal `neo pull` performs a stable-ID-aware
-three-way merge and preserves source placement when possible.
+three-way merge, preserves source placement when possible, and uses a durable
+transaction cursor to fetch only records changed since the previous sync.
+Undo/reset metadata invalidates that cursor and safely falls back to a full
+snapshot.
 
 In Unity projects, `neo.json` may use `unityConfigPath` instead of storing
 `projectId` and `versionId`. The referenced `NeoComposeConfig.asset` then owns

package/dist/neo.mjs

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __esm = (fn, res, err) => function __init() {
@@ -68315,13 +68316,21 @@ function collectNeoScriptRecompileTargets(args) {
     }
   }
   const constructorOwnerById = constructorOwners(args.postDocument);
+  const impactedSourceNames = collectImpactedSourceNames({
+    currentDocument: args.currentDocument,
+    postDocument: args.postDocument,
+    impactedIds,
+    impactedTypeNames,
+    constructedClassIds
+  });
   const memberIds = new Set(explicit.memberIds);
   for (const member of args.postDocument.members) {
     if (recordDependsOnChangedContract(
       member,
       impactedIds,
       impactedTypeNames,
-      constructedClassIds
+      constructedClassIds,
+      impactedSourceNames
     )) {
       memberIds.add(member.id);
     }
@@ -68332,7 +68341,8 @@ function collectNeoScriptRecompileTargets(args) {
     explicit.valueIds,
     impactedIds,
     impactedTypeNames,
-    constructedClassIds
+    constructedClassIds,
+    impactedSourceNames
   );
   if (impactedIds.size > 0 && postValues.length > 0) {
     const ownerByValueId = resolveOwnerMembersForValues(
@@ -68355,6 +68365,7 @@ function collectNeoScriptRecompileTargets(args) {
       impactedIds,
       impactedTypeNames,
       constructedClassIds,
+      impactedSourceNames,
       (record3) => constructorOwnerById.get(record3.id) ?? null
     ),
     migrationIds: selectedRecordIds(
@@ -68362,21 +68373,24 @@ function collectNeoScriptRecompileTargets(args) {
       explicit.migrationIds,
       impactedIds,
       impactedTypeNames,
-      constructedClassIds
+      constructedClassIds,
+      impactedSourceNames
     ),
     dialogueNodeIds: selectedRecordIds(
       args.postDocument.dialogueNodes ?? [],
       explicit.dialogueNodeIds,
       impactedIds,
       impactedTypeNames,
-      constructedClassIds
+      constructedClassIds,
+      impactedSourceNames
     ),
     dialogueGroupIds: selectedRecordIds(
       args.postDocument.dialogueGroups ?? [],
       explicit.dialogueGroupIds,
       impactedIds,
       impactedTypeNames,
-      constructedClassIds
+      constructedClassIds,
+      impactedSourceNames
     ),
     valueIds
   };
@@ -68745,7 +68759,7 @@ function explicitTargetIds(changes) {
   }
   return result;
 }
-function selectedRecordIds(records2, explicitIds, impactedIds, impactedTypeNames, constructedClassIds, ownerId = () => null) {
+function selectedRecordIds(records2, explicitIds, impactedIds, impactedTypeNames, constructedClassIds, impactedSourceNames, ownerId = () => null) {
   const selected2 = new Set(explicitIds);
   for (const record3 of records2) {
     const owner = ownerId(record3);
@@ -68753,14 +68767,17 @@ function selectedRecordIds(records2, explicitIds, impactedIds, impactedTypeNames
       record3,
       impactedIds,
       impactedTypeNames,
-      constructedClassIds
+      constructedClassIds,
+      impactedSourceNames
     )) {
       selected2.add(record3.id);
     }
   }
   return selected2;
 }
-function recordDependsOnChangedContract(record3, impactedIds, impactedTypeNames, constructedClassIds) {
+function recordDependsOnChangedContract(record3, impactedIds, impactedTypeNames, constructedClassIds, impactedSourceNames) {
+  const recordId = isObjectRecord3(record3) ? record3.id : void 0;
+  if (typeof recordId === "string" && impactedIds.has(recordId)) return true;
   if (intersects(collectCompilerReferenceIds(record3), impactedIds)) return true;
   if (intersects(collectCompilerReferenceNames(record3), impactedTypeNames)) {
     return true;
@@ -68768,7 +68785,109 @@ function recordDependsOnChangedContract(record3, impactedIds, impactedTypeNames,
   if (intersects(collectConstructedClassIds(record3), constructedClassIds)) {
     return true;
   }
-  return (impactedIds.size > 0 || impactedTypeNames.size > 0) && containsAuthoredNeoScriptSource(record3) && !containsCompiledNeoScriptBody(record3);
+  if (impactedIds.size === 0 && impactedTypeNames.size === 0) return false;
+  if (!containsAuthoredNeoScriptSource(record3)) return false;
+  if (containsCompiledNeoScriptBody(record3)) return false;
+  if (impactedSourceNames === null) return true;
+  const sourceIdentifiers = collectAuthoredNeoScriptSourceIdentifiers(record3);
+  if (sourceIdentifiers === null) return true;
+  return intersects(sourceIdentifiers, impactedSourceNames);
+}
+function collectImpactedSourceNames(args) {
+  const names = new Set(args.impactedTypeNames);
+  let recoveredContract = args.impactedTypeNames.size > 0;
+  const collectDocument = (document) => {
+    const classById = new Map(
+      document.classes.map((schemaClass2) => [schemaClass2.id, schemaClass2])
+    );
+    const ownerByConstructorId = constructorOwners(document);
+    const impactedValueIds = new Set(
+      (document.values ?? []).filter((value) => args.impactedIds.has(value.id)).map((value) => value.id)
+    );
+    const ownerByValueId = resolveOwnerMembersForValues(
+      document,
+      impactedValueIds
+    );
+    for (const owner of ownerByValueId.values()) {
+      recoveredContract = true;
+      collectDeclaredSourceNames(owner, names);
+      const ownerId = Reflect.get(owner, "id");
+      if (typeof ownerId !== "string") continue;
+      for (const classId of classPlacementsForMember(ownerId, document)) {
+        const schemaClass2 = classById.get(classId);
+        if (schemaClass2 !== void 0) {
+          collectDeclaredSourceNames(schemaClass2, names);
+        }
+      }
+    }
+    const records2 = [
+      ...document.classes,
+      ...document.members,
+      ...document.constructors ?? [],
+      ...document.enums,
+      ...document.interfaces ?? [],
+      ...document.values ?? []
+    ];
+    for (const record3 of records2) {
+      if (!args.impactedIds.has(record3.id)) continue;
+      recoveredContract = true;
+      collectDeclaredSourceNames(record3, names);
+      const ownerClassId = ownerByConstructorId.get(record3.id);
+      if (ownerClassId === void 0) continue;
+      const owner = classById.get(ownerClassId);
+      if (owner !== void 0) collectDeclaredSourceNames(owner, names);
+    }
+    for (const schemaClass2 of document.classes) {
+      if (!args.constructedClassIds.has(schemaClass2.id)) continue;
+      recoveredContract = true;
+      collectDeclaredSourceNames(schemaClass2, names);
+    }
+  };
+  collectDocument(args.currentDocument);
+  collectDocument(args.postDocument);
+  return recoveredContract ? names : null;
+}
+function collectDeclaredSourceNames(value, names) {
+  if (Array.isArray(value)) {
+    for (const child of value) collectDeclaredSourceNames(child, names);
+    return;
+  }
+  if (!isObjectRecord3(value)) return;
+  for (const [field, child] of Object.entries(value)) {
+    if (typeof child === "string" && (field === "name" || field === "sourceName" || field === "sourceFunctionName" || field === "declaredTypeName" || field === "typeName")) {
+      names.add(child);
+      continue;
+    }
+    collectDeclaredSourceNames(child, names);
+  }
+}
+function collectAuthoredNeoScriptSourceIdentifiers(value) {
+  const identifiers = /* @__PURE__ */ new Set();
+  let complete2 = true;
+  const collect = (child) => {
+    if (Array.isArray(child)) {
+      for (const entry of child) collect(entry);
+      return;
+    }
+    if (!isObjectRecord3(child)) return;
+    for (const [field, nested] of Object.entries(child)) {
+      if ((field === "code" || field === "setterCode") && typeof nested === "string") {
+        const result = lex(nested);
+        if (result.diagnostics.some(
+          (diagnostic) => diagnostic.severity === "error"
+        )) {
+          complete2 = false;
+        }
+        for (const token of result.tokens) {
+          if (token.kind === "identifier") identifiers.add(token.text);
+        }
+        continue;
+      }
+      collect(nested);
+    }
+  };
+  collect(value);
+  return complete2 ? identifiers : null;
 }
 function containsAuthoredNeoScriptSource(value) {
   if (Array.isArray(value)) {
@@ -68867,6 +68986,7 @@ var init_neo_script_recompile_scope = __esm({
   "../src/database/neo-script-recompile-scope.ts"() {
     "use strict";
     init_canonical_json();
+    init_src();
     init_member_kind_enum();
     init_inheritance();
     init_effective_storage();
@@ -87198,20 +87318,172 @@ async function fetchProjectDocument(workspace) {
       });
     }
   }
+  const revision = readProjectDocumentRevisionMarker2(raw);
   return {
     records: records2,
     heads,
-    raw
+    raw,
+    ...revision === null ? {} : { revision }
+  };
+}
+async function fetchProjectDocumentSyncMarker(workspace) {
+  const convex = await createConvexClient(workspace);
+  return queryProjectDocumentSyncMarker(workspace, convex);
+}
+async function queryProjectDocumentSyncMarker(workspace, convex) {
+  const [revisionValue, signal] = await Promise.all([
+    convex.query(api2.projectDocuments.getDocumentRevision, {
+      projectId: workspace.config.projectId,
+      versionId: workspace.config.versionId
+    }),
+    convex.query(api2.projectExportData.schemaSignal, {
+      projectId: workspace.config.projectId,
+      versionId: workspace.config.versionId
+    })
+  ]);
+  if (!isProjectDocumentRevisionMarker(revisionValue)) {
+    throw new Error(
+      "Project document revision query returned an invalid cursor marker."
+    );
+  }
+  return {
+    revision: revisionValue,
+    headTransactionId: signal?.transactionId ?? null,
+    headTransactionHash: signal?.transactionHash ?? null
+  };
+}
+async function fetchProjectDocumentDelta(workspace, cursor) {
+  const convex = await createConvexClient(workspace);
+  const marker = await queryProjectDocumentSyncMarker(workspace, convex);
+  if (marker.revision.versionsStamp !== cursor.versionsStamp) {
+    return {
+      fullResync: true,
+      headTransactionHash: marker.headTransactionHash
+    };
+  }
+  if (marker.headTransactionId === marker.revision.latestTransactionId && marker.headTransactionHash === workspace.state.headTransactionHash) {
+    return {
+      fullResync: false,
+      document: projectDocumentFromWorkspaceState(workspace.state, cursor),
+      changedKeys: /* @__PURE__ */ new Set(),
+      cursor,
+      headTransactionHash: marker.headTransactionHash
+    };
+  }
+  const result = await convex.query(api2.projectDocuments.getRecordsSince, {
+    projectId: workspace.config.projectId,
+    versionId: workspace.config.versionId,
+    sinceCreatedAt: cursor.createdAt,
+    seenTransactionIds: [...cursor.transactionIds]
+  });
+  if (result.fullResync) {
+    return {
+      fullResync: true,
+      headTransactionHash: marker.headTransactionHash
+    };
+  }
+  const document = projectDocumentFromWorkspaceState(workspace.state, cursor);
+  const { records: records2, heads } = document;
+  const changedKeys = /* @__PURE__ */ new Set();
+  for (const record3 of result.records) {
+    const key = `${record3.recordKind}:${record3.recordId}`;
+    changedKeys.add(key);
+    if (record3.deleted) {
+      records2.delete(key);
+      heads.set(key, {
+        recordKind: record3.recordKind,
+        recordId: record3.recordId,
+        contentHash: "",
+        deleted: true
+      });
+      continue;
+    }
+    if (record3.contentHash === null) {
+      throw new Error(
+        `Project document delta record "${key}" is live but has no content hash.`
+      );
+    }
+    records2.set(key, {
+      recordKind: record3.recordKind,
+      recordId: record3.recordId,
+      contentHash: record3.contentHash,
+      deleted: false,
+      data: record3.data
+    });
+    heads.set(key, {
+      recordKind: record3.recordKind,
+      recordId: record3.recordId,
+      contentHash: record3.contentHash,
+      deleted: false
+    });
+  }
+  const next = result.cursor ?? cursor;
+  const nextCursor = {
+    createdAt: next.createdAt,
+    transactionIds: [...next.transactionIds],
+    versionsStamp: marker.revision.versionsStamp
+  };
+  return {
+    fullResync: false,
+    document: projectDocumentWithRevision(document, nextCursor),
+    changedKeys,
+    cursor: nextCursor,
+    headTransactionHash: marker.headTransactionHash
+  };
+}
+function projectDocumentFromWorkspaceState(state, cursor) {
+  const records2 = serverRecordsFromWorkspaceState(state);
+  const heads = new Map(
+    [...records2].map(([key, record3]) => [
+      key,
+      {
+        recordKind: record3.recordKind,
+        recordId: record3.recordId,
+        contentHash: record3.contentHash,
+        deleted: false
+      }
+    ])
+  );
+  return projectDocumentWithRevision({ records: records2, heads, raw: {} }, cursor);
+}
+function projectDocumentWithRevision(document, cursor) {
+  return {
+    ...document,
+    revision: {
+      latestTransactionId: cursor.transactionIds[cursor.transactionIds.length - 1] ?? null,
+      latestTransactionCreatedAt: cursor.createdAt,
+      versionsStamp: cursor.versionsStamp
+    }
   };
 }
-var fetchProjectDocumentRawChunked2, readProjectDocumentContentHashHeads2, SOURCE_RECORD_KINDS;
+function serverRecordsFromWorkspaceState(state) {
+  const records2 = /* @__PURE__ */ new Map();
+  for (const [key, record3] of Object.entries(state.records)) {
+    if (record3.conflictServerHash === null) continue;
+    const conflictServerHash = record3.conflictServerHash;
+    const hasConflictServer = conflictServerHash !== void 0;
+    records2.set(key, {
+      recordKind: record3.recordKind,
+      recordId: record3.recordId,
+      contentHash: hasConflictServer ? conflictServerHash : record3.contentHash,
+      deleted: false,
+      data: hasConflictServer ? record3.conflictServerData : record3.data
+    });
+  }
+  return records2;
+}
+var fetchProjectDocumentRawChunked2, readProjectDocumentContentHashHeads2, readProjectDocumentRevisionMarker2, SOURCE_RECORD_KINDS;
 var init_document = __esm({
   "src/document.ts"() {
     "use strict";
     init_project_document_read();
     init_project2();
     init_convex();
-    ({ fetchProjectDocumentRawChunked: fetchProjectDocumentRawChunked2, readProjectDocumentContentHashHeads: readProjectDocumentContentHashHeads2 } = project_document_read_exports);
+    ({
+      fetchProjectDocumentRawChunked: fetchProjectDocumentRawChunked2,
+      readProjectDocumentContentHashHeads: readProjectDocumentContentHashHeads2,
+      readProjectDocumentRevisionMarker: readProjectDocumentRevisionMarker2
+    } = project_document_read_exports);
     SOURCE_RECORD_KINDS = new Set(
       Object.values(ProjectRecordKind)
     );
@@ -87898,6 +88170,7 @@ var init_static_value_seed_records = __esm({
 // src/commands/pull.ts
 var pull_exports = {};
 __export(pull_exports, {
+  deltaRequiresSourceProjectionV4: () => deltaRequiresSourceProjectionV4,
   projectSourcePathsRequiringRewriteV4: () => projectSourcePathsRequiringRewriteV4,
   runPull: () => runPull
 });
@@ -87914,6 +88187,15 @@ async function runPull(workspace, options) {
     await runResetPull(workspace);
     return;
   }
+  const progress = spinner("Checking local workspace\u2026");
+  try {
+    await runNormalPull(workspace, options, progress);
+  } catch (error) {
+    progress.fail("Pull failed.");
+    throw error;
+  }
+}
+async function runNormalPull(workspace, options, progress) {
   const destructive = options.force;
   const hasBaseline = Object.keys(workspace.state.records).length > 0;
   let localByKey = /* @__PURE__ */ new Map();
@@ -87942,25 +88224,54 @@ ${blockingErrors.map((error) => `  ${error.message}`).join("\n")}`
       ])
     );
   }
-  if (!destructive && !options.regenerateSourceNames && workspace.state.headTransactionHash !== void 0) {
-    const convex = await createConvexClient(workspace);
-    const signal = await convex.query(api2.projectExportData.schemaSignal, {
-      projectId: workspace.config.projectId,
-      versionId: workspace.config.versionId
-    });
-    if (signal !== null && signal.transactionHash === workspace.state.headTransactionHash && localByKey.size > 0) {
-      const dirtyRecords = [...localByKey.entries()].some(([key, local]) => {
-        const base = workspace.state.records[key];
-        return base === void 0 || !authoredRecordsSemanticallyEqual(base.recordKind, local, base.data);
-      });
-      const dirtyBinaries = (localStatus?.binaryChanges?.length ?? 0) > 0;
-      if (!dirtyRecords && !dirtyBinaries) {
-        console.log("Already up to date (sync-signal head unchanged).");
+  let changedRecordKeys = null;
+  let nextCursor = null;
+  let observedHeadTransactionHash;
+  let document = null;
+  if (!destructive && hasBaseline) {
+    progress.update("Checking remote changes\u2026");
+    const cursor = workspace.state.documentRevisionCursor;
+    if (cursor !== void 0) {
+      const delta = await fetchProjectDocumentDelta(workspace, cursor);
+      observedHeadTransactionHash = delta.headTransactionHash;
+      if (!delta.fullResync) {
+        document = delta.document;
+        changedRecordKeys = delta.changedKeys;
+        nextCursor = delta.cursor;
+        if (delta.changedKeys.size === 0 && !options.regenerateSourceNames) {
+          const cursorChanged = !cursorsEqual(
+            workspace.state.documentRevisionCursor,
+            delta.cursor
+          );
+          const headChanged = workspace.state.headTransactionHash !== delta.headTransactionHash;
+          if (cursorChanged || headChanged) {
+            workspace.state.documentRevisionCursor = mutableCursor(
+              delta.cursor
+            );
+            workspace.state.headTransactionHash = delta.headTransactionHash;
+            writeWorkspaceState(workspace.root, workspace.state);
+          }
+          progress.succeed("Already up to date.");
+          return;
+        }
+      }
+    } else if (!options.regenerateSourceNames && workspace.state.headTransactionHash !== void 0) {
+      const marker = await fetchProjectDocumentSyncMarker(workspace);
+      observedHeadTransactionHash = marker.headTransactionHash;
+      if (marker.headTransactionId === marker.revision.latestTransactionId && marker.headTransactionHash === workspace.state.headTransactionHash) {
+        const seededCursor = cursorFromRevision(marker.revision);
+        workspace.state.documentRevisionCursor = mutableCursor(seededCursor);
+        writeWorkspaceState(workspace.root, workspace.state);
+        progress.succeed("Already up to date.");
         return;
       }
     }
   }
-  const document = await fetchProjectDocument(workspace);
+  if (document === null) {
+    progress.update("Downloading full project snapshot\u2026");
+    document = await fetchProjectDocument(workspace);
+    nextCursor = document.revision === void 0 ? null : cursorFromRevision(document.revision);
+  }
   const plans = /* @__PURE__ */ new Map();
   let mergedCount = 0;
   let conflictCount = 0;
@@ -88080,7 +88391,11 @@ ${blockingErrors.map((error) => `  ${error.message}`).join("\n")}`
     conflictKeys,
     localStatus,
     destructive,
-    regenerateSourceNames: destructive || options.regenerateSourceNames
+    regenerateSourceNames: destructive || options.regenerateSourceNames,
+    changedRecordKeys,
+    nextCursor,
+    observedHeadTransactionHash,
+    progress
   });
 }
 async function runResetPull(workspace) {
@@ -88110,10 +88425,17 @@ async function runResetPull(workspace) {
         projectId: workspace.config.projectId,
         versionId: workspace.config.versionId
       });
-      workspace.state.headTransactionHash = signal?.transactionHash ?? null;
+      workspace.state.headTransactionHash = document.revision !== void 0 && signal?.transactionId === document.revision.latestTransactionId ? signal.transactionHash : null;
     } catch {
       workspace.state.headTransactionHash = null;
     }
+    if (document.revision !== void 0) {
+      workspace.state.documentRevisionCursor = mutableCursor(
+        cursorFromRevision(document.revision)
+      );
+    } else {
+      delete workspace.state.documentRevisionCursor;
+    }
     writeWorkspaceState(workspace.root, workspace.state);
     progress.succeed(
       `Pulled ${document.records.size} records \u2014 ${reset.written} file(s) updated \u2014 ${reset.removed} removed.`
@@ -88133,8 +88455,30 @@ async function finishFormat4Pull(args) {
     conflictKeys,
     localStatus,
     destructive,
-    regenerateSourceNames
+    regenerateSourceNames,
+    changedRecordKeys,
+    nextCursor,
+    observedHeadTransactionHash,
+    progress
   } = args;
+  if (changedRecordKeys !== null && !regenerateSourceNames && conflictCount === 0 && localStatus !== null && !deltaRequiresSourceProjectionV4({
+    workspace,
+    document,
+    plans,
+    localStatus,
+    changedRecordKeys
+  })) {
+    finishRecordOnlyDeltaPull({
+      workspace,
+      document,
+      changedRecordKeys,
+      nextCursor,
+      observedHeadTransactionHash,
+      progress
+    });
+    return;
+  }
+  progress.update("Regenerating affected Neo sources\u2026");
   const plannedLocalRecords = buildEmitRecordSet(document, plans, "emit");
   for (const [key, record3] of staticValueSeedEmitRecords(
     localStatus,
@@ -88149,7 +88493,7 @@ async function finishFormat4Pull(args) {
     )
   );
   const localResult = emitProjectDocumentFilesV4(localRecords);
-  const serverResult = emitProjectDocumentFilesV4(
+  const serverResult = conflictCount === 0 ? null : emitProjectDocumentFilesV4(
     buildEmitRecordSet(document, plans, "server")
   );
   const binaries = await pullProjectBinariesV4({
@@ -88163,11 +88507,11 @@ async function finishFormat4Pull(args) {
     localResult.files.map((file) => [file.path, file])
   );
   const serverByPath = new Map(
-    serverResult.files.map((file) => [file.path, file])
+    (serverResult?.files ?? []).map((file) => [file.path, file])
   );
   const conflictPaths = /* @__PURE__ */ new Set();
   for (const key of conflictKeys) {
-    const path = localResult.recordFiles.get(key) ?? serverResult.recordFiles.get(key);
+    const path = localResult.recordFiles.get(key) ?? serverResult?.recordFiles.get(key);
     if (path) conflictPaths.add(path);
   }
   const emittedPaths = /* @__PURE__ */ new Set([
@@ -88179,7 +88523,7 @@ async function finishFormat4Pull(args) {
     localStatus,
     plans,
     localRecordFiles: localResult.recordFiles,
-    serverRecordFiles: serverResult.recordFiles,
+    serverRecordFiles: serverResult?.recordFiles ?? /* @__PURE__ */ new Map(),
     previousRecords: workspace.state.records,
     conflictPaths,
     emittedPaths,
@@ -88229,7 +88573,7 @@ async function finishFormat4Pull(args) {
       if (baseState) records2[key] = { ...baseState };
       continue;
     }
-    const file = localResult.recordFiles.get(key) ?? serverResult.recordFiles.get(key);
+    const file = localResult.recordFiles.get(key) ?? serverResult?.recordFiles.get(key) ?? baseState?.file;
     records2[key] = plan.conflicted ? {
       recordKind,
       recordId,
@@ -88248,7 +88592,7 @@ async function finishFormat4Pull(args) {
   }
   for (const [key, serverRecord] of document.records) {
     if (serverRecord.deleted || records2[key]) continue;
-    const file = localResult.recordFiles.get(key) ?? serverResult.recordFiles.get(key);
+    const file = localResult.recordFiles.get(key) ?? serverResult?.recordFiles.get(key);
     records2[key] = {
       recordKind: serverRecord.recordKind,
       recordId: serverRecord.recordId,
@@ -88262,30 +88606,37 @@ async function finishFormat4Pull(args) {
     if (record3) record3.projectBinary = state;
   }
   workspace.state.records = records2;
-  try {
-    const convex = await createConvexClient(workspace);
-    const signal = await convex.query(api2.projectExportData.schemaSignal, {
-      projectId: workspace.config.projectId,
-      versionId: workspace.config.versionId
-    });
-    workspace.state.headTransactionHash = signal?.transactionHash ?? null;
-  } catch {
-    workspace.state.headTransactionHash = null;
+  if (nextCursor !== null) {
+    workspace.state.documentRevisionCursor = mutableCursor(nextCursor);
+  }
+  if (observedHeadTransactionHash !== void 0) {
+    workspace.state.headTransactionHash = observedHeadTransactionHash;
+  } else {
+    try {
+      const convex = await createConvexClient(workspace);
+      const signal = await convex.query(api2.projectExportData.schemaSignal, {
+        projectId: workspace.config.projectId,
+        versionId: workspace.config.versionId
+      });
+      workspace.state.headTransactionHash = document.revision !== void 0 && signal?.transactionId === document.revision.latestTransactionId ? signal.transactionHash : null;
+    } catch {
+      workspace.state.headTransactionHash = null;
+    }
   }
   writeWorkspaceState(workspace.root, workspace.state);
   if (conflictCount === 0) {
     writeProjectSourceAnalysisCacheV4(workspace.root, localResult.analysis);
-    writeMaterializedConstructionBuildCacheV1(
-      workspace.root,
-      workspace.state,
-      // The cache is a baseline for workspace.state, not the merged authored
-      // tree. Retaining a local constructor edit here would bless it as the
-      // pulled construction and bypass the P61 recreate-conflict check.
-      serverResult.materializedConstructors
-    );
+    if (localStatus === null || localStatus.changes.length === 0) {
+      writeMaterializedConstructionBuildCacheV1(
+        workspace.root,
+        workspace.state,
+        localResult.materializedConstructors
+      );
+    }
   }
+  const pulledRecords = changedRecordKeys === null ? `Pulled ${document.records.size} records` : `Pulled ${changedRecordKeys.size} changed record(s)`;
   const summary = [
-    `Pulled ${document.records.size} records`,
+    pulledRecords,
     `${written} file(s) updated`,
     `${removed} removed`
   ];
@@ -88296,7 +88647,7 @@ async function finishFormat4Pull(args) {
   if (mergedCount > 0)
     summary.push(color.green(`${mergedCount} merged cleanly`));
   if (conflictCount > 0) summary.push(color.red(`${conflictCount} CONFLICTED`));
-  console.log(`${summary.join(" \u2014 ")}.`);
+  progress.succeed(`${summary.join(" \u2014 ")}.`);
   if (conflictCount > 0) {
     warn(
       'Conflict markers were written into the affected files. Edit them to the desired final state and push \u2014 the push is the resolution. To keep one side everywhere, use "neo resolve --mine" or "neo resolve --theirs".'
@@ -88310,6 +88661,98 @@ async function finishFormat4Pull(args) {
     for (const path of binaries.conflicts) console.log(`  ${sym.fail} ${path}`);
   }
 }
+function deltaRequiresSourceProjectionV4(args) {
+  const mainLocale = workspaceMainLocale(args.workspace.state.records);
+  for (const key of args.changedRecordKeys) {
+    const previous = args.workspace.state.records[key];
+    const local = args.localStatus.reconstructed.get(key)?.fullData;
+    const plan = args.plans.get(key);
+    const server = args.document.records.get(key);
+    if (server === void 0) {
+      if (previous?.file !== void 0 || local !== void 0) return true;
+      continue;
+    }
+    if (local === void 0 || plan?.emitData === void 0) {
+      if (previous?.file !== void 0 || previous === void 0) return true;
+      continue;
+    }
+    if (!sourceAuthoredRecordsSemanticallyEqual(
+      server.recordKind,
+      plan.emitData,
+      local,
+      mainLocale
+    )) {
+      return true;
+    }
+  }
+  return false;
+}
+function finishRecordOnlyDeltaPull(args) {
+  const cachedExpressions = readMaterializedConstructionBuildCacheV1(
+    args.workspace.root,
+    args.workspace.state
+  );
+  const records2 = { ...args.workspace.state.records };
+  for (const key of args.changedRecordKeys) {
+    const server = args.document.records.get(key);
+    if (server === void 0) {
+      delete records2[key];
+      continue;
+    }
+    const previous = records2[key];
+    records2[key] = {
+      recordKind: server.recordKind,
+      recordId: server.recordId,
+      contentHash: server.contentHash,
+      data: server.data,
+      ...previous?.file === void 0 ? {} : { file: previous.file },
+      ...previous?.projectBinary === void 0 ? {} : { projectBinary: previous.projectBinary }
+    };
+  }
+  args.workspace.state.records = records2;
+  if (args.nextCursor !== null) {
+    args.workspace.state.documentRevisionCursor = mutableCursor(
+      args.nextCursor
+    );
+  }
+  if (args.observedHeadTransactionHash !== void 0) {
+    args.workspace.state.headTransactionHash = args.observedHeadTransactionHash;
+  }
+  writeWorkspaceState(args.workspace.root, args.workspace.state);
+  if (cachedExpressions !== null) {
+    writeMaterializedConstructionBuildCacheV1(
+      args.workspace.root,
+      args.workspace.state,
+      cachedExpressions
+    );
+  }
+  args.progress.succeed(
+    `Pulled ${args.changedRecordKeys.size} changed record(s) \u2014 0 file(s) updated \u2014 0 removed.`
+  );
+}
+function cursorFromRevision(revision) {
+  return {
+    createdAt: revision.latestTransactionCreatedAt,
+    transactionIds: revision.latestTransactionId === null ? [] : [revision.latestTransactionId],
+    versionsStamp: revision.versionsStamp
+  };
+}
+function mutableCursor(cursor) {
+  return {
+    createdAt: cursor.createdAt,
+    transactionIds: [...cursor.transactionIds],
+    versionsStamp: cursor.versionsStamp
+  };
+}
+function cursorsEqual(left, right) {
+  if (left === void 0) return false;
+  if (left.createdAt !== right.createdAt) return false;
+  if (left.versionsStamp !== right.versionsStamp) return false;
+  if (left.transactionIds.length !== right.transactionIds.length) return false;
+  return left.transactionIds.every(
+    (transactionId, index) => transactionId === right.transactionIds[index]
+  );
+}
 function projectSourcePathsRequiringRewriteV4(args) {
   if (args.destructive || args.localStatus === null) {
     return new Set(args.emittedPaths);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.22.0",
+  "version": "0.22.2",
   "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.22.0 -->
+<!-- reviewed-through-cli: 0.22.2 -->
 
 # Neo Compose CLI
 

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

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

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

@@ -28,7 +28,9 @@ neo push --dry-run --force-recompile
 Use `neo pull --regenerate-source-names` to refresh readable naming while
 retaining normal merge behavior. Use `--reset` to regenerate canonical source
 and managed binaries. Use `--force` only to discard local edits for the server
-version.
+version. Normal pulls persist a transaction cursor and fetch only changed
+records; an undo/reset metadata change invalidates the cursor and causes a safe
+full-snapshot fallback.
 
 Treat `neo push --dry-run` as a full local commit rehearsal: source emission,
 in-memory pending-ID assignment, transport shapes, hashes, and repeat