@neocompose/cli 0.57.3 → 0.58.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.58.1] - 2026-09-24
+
+- Push writes `@id` on list entries nested inside a new computed row, such as the items of a list on a new `new Event(...) { ... }` entry, so `neo status` is clean afterwards. Before, those entries stayed without ids and status kept reporting changes.
+- A new row that names a stored row's `@id`, such as a row moved or copied under a new parent, is an error that names the `@id`, in `neo status` and `neo push --dry-run` too. Before, dry run passed and push either failed with a base-hash-conflict or committed a row that still referenced the deleted original. Drop the `@id` to create a new row.
+- Source that places one stored row twice, such as a list entry copied with its `@id` into the same or another list or dictionary, is an error. Before, the push stored the same row at two positions.
+- A negative number after `@id`, such as `[@id("…") -3]`, parses as the annotated entry, and a push of a new list with negative entries writes its ids. Before, `@id` could not precede `-3`, so the push failed after the server had applied it.
+- A stored enum value may be written `Direction.North` as well as `.North`. Before, `neo status` failed with "Enum member … requires contextual .Option values."
+- A push that deletes a row and creates a new one with the same localized text, such as re-creating a part under a new parent, updates source after it commits. Before, it failed with "Localizable value references missing localized text" after the server had already applied it.
+
+## [0.58.0] - 2026-09-24
+
+- **Behavior change:** NeoScript cell queries the CLI evaluates, such as in `neo test`, no longer return an object that has no placement tiles. Before, such an object answered for its origin cell. This matches the Unity SDK (0.43.0) and the web editor: `PlacementTiles` are the cells an object occupies, and without them it occupies none.
+
 ## [0.57.3] - 2026-09-24
 
 - Status, pull, and push no longer copy a shared row passed to a constructor when they check a stored construction. Before, a constructor argument that named a shared row, such as a schedule event's `area`, copied that row's whole graph for every construction. Once an area grid held a few placed characters, this failed with "NeoScript constructed Session row limit of 4096 exceeded."

package/dist/neo.mjs

@@ -3672,7 +3672,8 @@ var init_executable_parser = __esm({
           return {
             kind: "annotated",
             annotations,
-            expression: this.parsePostfix(),
+            // Unary, so `@id("…") -3` annotates the negative entry.
+            expression: this.parseUnary(),
             pos: at(t)
           };
         }
@@ -45372,17 +45373,12 @@ function lowerDictionaryKey(expression, keyEnum, path) {
   if (keyEnum === null) {
     throw new Error(`Dictionary ${path} requires string keys.`);
   }
-  let optionName;
-  if (expression.kind === "contextualEnum") {
-    optionName = expression.name;
-  } else if (expression.kind === "member" && expression.receiver.kind === "ident") {
-    if (expression.receiver.name !== keyEnum.name) {
-      throw new Error(
-        `Dictionary key at ${path} names enum ${JSON.stringify(expression.receiver.name)}, expected ${JSON.stringify(keyEnum.name)}.`
-      );
-    }
-    optionName = expression.name;
-  } else {
+  const optionName = enumOptionSpelling(
+    expression,
+    keyEnum.name,
+    `Dictionary key at ${path}`
+  );
+  if (optionName === null) {
     throw new Error(
       `Dictionary key at ${path} must be .Option, ${keyEnum.name}.Option, or a quoted option ID.`
     );
@@ -45395,6 +45391,17 @@ function lowerDictionaryKey(expression, keyEnum, path) {
   }
   return optionId;
 }
+function enumOptionSpelling(expression, enumName, subject) {
+  if (expression.kind === "contextualEnum") return expression.name;
+  if (expression.kind !== "member") return null;
+  if (expression.receiver.kind !== "ident") return null;
+  if (expression.receiver.name !== enumName) {
+    throw new Error(
+      `${subject} names enum ${JSON.stringify(expression.receiver.name)}, expected ${JSON.stringify(enumName)}.`
+    );
+  }
+  return expression.name;
+}
 function emitDictionaryKey(key, options) {
   const name = options?.get(key)?.name;
   return name === void 0 ? quoteNeoString(key) : `.${name}`;
@@ -64310,9 +64317,9 @@ var init_dialogue_sources = __esm({
         if (typeof memberId !== "string") return null;
         const nameMember = this.members.get(memberId);
         if (nameMember?.kind !== 3) return null;
-        const childValueId = value.value[memberName];
-        if (typeof childValueId !== "string") return null;
-        const child = this.values.get(childValueId);
+        const childValueId2 = value.value[memberName];
+        if (typeof childValueId2 !== "string") return null;
+        const child = this.values.get(childValueId2);
         if (typeof child?.value !== "string") return null;
         const localizedText = this.localizedTexts.get(child.value);
         const localeValues = isObjectRecord2(localizedText?.localeValues) ? localizedText.localeValues : null;
@@ -67652,13 +67659,13 @@ function resolveOwnerMembersForValues(document, targetValueIds, additionalRoots,
       const env = overlayStamp(instanceEnv, body.genericBindings);
       for (const entry of merged) {
         if (entry.memberId === null) continue;
-        const childValueId = body.value[entry.schemaKey];
-        if (childValueId === void 0) continue;
+        const childValueId2 = body.value[entry.schemaKey];
+        if (childValueId2 === void 0) continue;
         const childMember = membersById.get(entry.memberId);
         if (childMember === void 0) continue;
         const substituted = trySubstituteMember(childMember, env);
         if (substituted === null) continue;
-        searchRow(substituted, childValueId, rootOwner, env, rootKind);
+        searchRow(substituted, childValueId2, rootOwner, env, rootKind);
       }
       return;
     }
@@ -67669,8 +67676,8 @@ function resolveOwnerMembersForValues(document, targetValueIds, additionalRoots,
       const entryEnv = overlayStamp(ambientEnv, body.genericBindings);
       const entryMember = trySubstituteMember(entryMemberRecord, entryEnv);
       if (entryMember === null) return;
-      for (const childValueId of Object.values(body.value)) {
-        searchRow(entryMember, childValueId, rootOwner, entryEnv, rootKind);
+      for (const childValueId2 of Object.values(body.value)) {
+        searchRow(entryMember, childValueId2, rootOwner, entryEnv, rootKind);
       }
       return;
     }
@@ -67688,9 +67695,9 @@ function resolveOwnerMembersForValues(document, targetValueIds, additionalRoots,
         return;
       }
       if (!Array.isArray(body.value)) return;
-      for (const childValueId of body.value) {
-        if (typeof childValueId !== "string") continue;
-        searchRow(entryMember, childValueId, rootOwner, entryEnv, rootKind);
+      for (const childValueId2 of body.value) {
+        if (typeof childValueId2 !== "string") continue;
+        searchRow(entryMember, childValueId2, rootOwner, entryEnv, rootKind);
       }
       return;
     }
@@ -67811,14 +67818,14 @@ function findOwningMembersForValues(document, valueIds, additionalRoots, travers
       args.genericBindings
     );
     for (const entry of merged) {
-      const childValueId = args.record[entry.schemaKey];
-      if (childValueId === void 0) continue;
+      const childValueId2 = args.record[entry.schemaKey];
+      if (childValueId2 === void 0) continue;
       const childMember = membersById.get(entry.memberId);
       if (childMember === void 0) continue;
       queue.push({
         member: substituteMember(childMember, env, document.members),
         memberRecordId: childMember.id,
-        id: childValueId,
+        id: childValueId2,
         parentValueId: args.parentValueId,
         env,
         // Descending through `Overrides` opens an override graph, and every
@@ -67978,11 +67985,11 @@ function findOwningMembersForValues(document, valueIds, additionalRoots, travers
         env,
         document.members
       );
-      for (const childValueId of Object.values(storedValue.value)) {
+      for (const childValueId2 of Object.values(storedValue.value)) {
         queue.push({
           member: entryMember,
           memberRecordId: entryMemberRecord.id,
-          id: childValueId,
+          id: childValueId2,
           // An entry inherits its collection's position: a Dictionary is not
           // itself a way into an override graph.
           insideAnimationOverrideGraph: current.insideAnimationOverrideGraph,
@@ -68002,11 +68009,11 @@ function findOwningMembersForValues(document, valueIds, additionalRoots, travers
         document.members
       );
       const childValueIds = listKindOf(current.member) === 1 /* Unordered */ ? (rowsByContainerId.get(storedValue.id) ?? []).map((row) => row.id) : isStringListValue(storedValue.value) ? storedValue.value : [];
-      for (const childValueId of childValueIds) {
+      for (const childValueId2 of childValueIds) {
         queue.push({
           member: entryMember,
           memberRecordId: entryMemberRecord.id,
-          id: childValueId,
+          id: childValueId2,
           // An entry inherits its collection's position: a List is not itself
           // a way into an override graph.
           insideAnimationOverrideGraph: current.insideAnimationOverrideGraph,
@@ -70414,7 +70421,6 @@ function buildIndex(source) {
             seen.add(key);
           }
         }
-        if (footprint.length === 0) footprint.push(cell);
         const placement = {
           valueId,
           isNeoObject: kinds.get(row.classId) === NeoWorldSystemClassKind.Object,
@@ -81751,16 +81757,16 @@ function createStoredValuePlacementTraversal(args, trackReferences = false) {
             if (settled === null || Object.hasOwn(value.value, settled.schemaKey)) {
               continue;
             }
-            const childValueId = value.constructorArgs[constructorActionParameterId(constructor2, index)];
-            if (typeof childValueId === "string") {
-              settledChildrenBySchemaKey.set(settled.schemaKey, childValueId);
+            const childValueId2 = value.constructorArgs[constructorActionParameterId(constructor2, index)];
+            if (typeof childValueId2 === "string") {
+              settledChildrenBySchemaKey.set(settled.schemaKey, childValueId2);
             }
           }
         }
         for (const entry of storedSchema(classId)) {
           const childMember = membersById.get(entry.memberId);
-          const childValueId = value.value[entry.schemaKey] ?? settledChildrenBySchemaKey.get(entry.schemaKey);
-          if (childMember === void 0 || typeof childValueId !== "string") {
+          const childValueId2 = value.value[entry.schemaKey] ?? settledChildrenBySchemaKey.get(entry.schemaKey);
+          if (childMember === void 0 || typeof childValueId2 !== "string") {
             continue;
           }
           if (memberAccessOf(childMember) !== 0 /* Public */) continue;
@@ -81768,7 +81774,7 @@ function createStoredValuePlacementTraversal(args, trackReferences = false) {
             memberId: childMember.id,
             parentValueId: value.id,
             source: { kind: "classField", schemaKey: entry.schemaKey },
-            valueId: childValueId
+            valueId: childValueId2
           });
         }
         continue;
@@ -81780,16 +81786,16 @@ function createStoredValuePlacementTraversal(args, trackReferences = false) {
       if (entryMember === void 0) continue;
       if (isMemberDictionaryBase(member)) {
         if (!isStringRecord4(value.value)) continue;
-        for (const [key, childValueId] of Object.entries(value.value)) {
+        for (const [key, childValueId2] of Object.entries(value.value)) {
           queue.push({
             memberId: entryMember.id,
             parentValueId: value.id,
             source: {
               kind: "collectionEntry",
               containerMemberId: storedMember.id,
-              entry: { kind: "dict", key, valueId: childValueId }
+              entry: { kind: "dict", key, valueId: childValueId2 }
             },
-            valueId: childValueId
+            valueId: childValueId2
           });
         }
         continue;
@@ -81797,9 +81803,9 @@ function createStoredValuePlacementTraversal(args, trackReferences = false) {
       const entries = listKindOf(member) === 1 /* Unordered */ ? args.indexedRows === void 0 ? unorderedEntriesByContainerId.get(value.id) ?? [] : args.indexedRows.unorderedListEntryIds(value.id).flatMap((id2) => {
         const row = valuesById.get(id2);
         return row === void 0 ? [] : [row];
-      }) : Array.isArray(value.value) ? value.value.flatMap((childValueId) => {
-        if (typeof childValueId !== "string") return [];
-        const childValue = valuesById.get(childValueId);
+      }) : Array.isArray(value.value) ? value.value.flatMap((childValueId2) => {
+        if (typeof childValueId2 !== "string") return [];
+        const childValue = valuesById.get(childValueId2);
         return childValue === void 0 ? [] : [childValue];
       }) : [];
       for (const [index, childValue] of entries.entries()) {
@@ -93980,8 +93986,8 @@ function findParentValues(valueId, values) {
       continue;
     }
     if (!isStringRecord6(value.value)) continue;
-    for (const [key, childValueId] of Object.entries(value.value)) {
-      if (childValueId === valueId) parents.push({ value, key });
+    for (const [key, childValueId2] of Object.entries(value.value)) {
+      if (childValueId2 === valueId) parents.push({ value, key });
     }
   }
   return parents;
@@ -96652,8 +96658,8 @@ function inspectClass(options, member) {
       options.index.members
     );
     if (!memberKindSupportsStorage(childMember.kind)) continue;
-    const childValueId = body[entry.schemaKey];
-    if (childValueId === void 0) {
+    const childValueId2 = body[entry.schemaKey];
+    if (childValueId2 === void 0) {
       if (isRequiredMember2(childMember) && !options.allowMissingRequiredClassFields) {
         fail(
           `${options.path} is missing required schema key "${entry.schemaKey}".`
@@ -96663,7 +96669,7 @@ function inspectClass(options, member) {
     }
     children.push({
       member: childMember,
-      valueId: childValueId,
+      valueId: childValueId2,
       path: `${options.path}.${entry.schemaKey}`,
       genericEnv: environment,
       insideAnimationOverrideGraph: options.insideAnimationOverrideGraph || entersAnimationOverrideGraph(entry.memberId)
@@ -106732,10 +106738,10 @@ function repointedChildValueIds(document, change) {
   if (!isPlainRecord4(change.nextData)) return [];
   const after = change.nextData.value;
   if (!isPlainRecord4(after)) return [];
-  return Object.entries(before).flatMap(([schemaKey, childValueId]) => {
-    if (typeof childValueId !== "string") return [];
-    if (after[schemaKey] === childValueId) return [];
-    return [childValueId];
+  return Object.entries(before).flatMap(([schemaKey, childValueId2]) => {
+    if (typeof childValueId2 !== "string") return [];
+    if (after[schemaKey] === childValueId2) return [];
+    return [childValueId2];
   });
 }
 function authoredFieldsEqual(recordKind, base, next) {
@@ -115997,12 +116003,12 @@ function buildStoredValuePlacementIndexV4(records2) {
     const classId = typeof value.classId === "string" ? value.classId : null;
     const body = value.value;
     if (isObjectRecord2(body)) {
-      for (const [schemaKey, childValueId] of Object.entries(body)) {
-        if (typeof childValueId !== "string" || !values.has(childValueId)) {
+      for (const [schemaKey, childValueId2] of Object.entries(body)) {
+        if (typeof childValueId2 !== "string" || !values.has(childValueId2)) {
           continue;
         }
         add({
-          childValueId,
+          childValueId: childValueId2,
           memberId: classId === null ? null : memberIdForSchemaKey(classId, schemaKey),
           parentValueId,
           schemaKey,
@@ -116030,8 +116036,8 @@ function buildStoredValuePlacementIndexV4(records2) {
         continue;
       }
       const parameterId = constructorActionParameterId(constructor2, index);
-      const childValueId = constructorArgs[parameterId];
-      if (typeof childValueId !== "string" || !values.has(childValueId) || !memberStoresAggregate(
+      const childValueId2 = constructorArgs[parameterId];
+      if (typeof childValueId2 !== "string" || !values.has(childValueId2) || !memberStoresAggregate(
         memberDataById.get(settled.memberId),
         value,
         memberDataById,
@@ -116042,7 +116048,7 @@ function buildStoredValuePlacementIndexV4(records2) {
         continue;
       }
       add({
-        childValueId,
+        childValueId: childValueId2,
         memberId: settled.memberId,
         parentValueId,
         schemaKey: settled.schemaKey,
@@ -117767,16 +117773,7 @@ function computeWorkspaceStatus(workspace, options) {
     projectSources.push({ uri: relPath, source, kind: sourceKind });
   }
   if (conflictedFiles.length > 0) {
-    return {
-      changes: [],
-      conflictedFiles,
-      parseErrors,
-      parseWarnings,
-      reconstructed: /* @__PURE__ */ new Map(),
-      authoredValueSeeds: /* @__PURE__ */ new Map(),
-      binaryChanges: [],
-      binaryFiles: []
-    };
+    return refusedStatus(conflictedFiles, parseErrors, parseWarnings);
   }
   const { records: loweringRecords, residency: packedResidency } = logicalValueBaseRecordsV4(loweringBaseRecords(workspace.state.records));
   const baseDocuments = schemaBaseDocuments(workspace);
@@ -117908,16 +117905,7 @@ function computeWorkspaceStatus(workspace, options) {
         1
       )
     );
-    return {
-      changes: [],
-      conflictedFiles,
-      parseErrors,
-      parseWarnings,
-      reconstructed: /* @__PURE__ */ new Map(),
-      authoredValueSeeds: /* @__PURE__ */ new Map(),
-      binaryChanges: [],
-      binaryFiles: []
-    };
+    return refusedStatus(conflictedFiles, parseErrors, parseWarnings);
   }
   const sourceByKey = manifestRecordSources(manifest);
   const documents = projectSchemaManifestToDocuments(
@@ -118220,8 +118208,7 @@ function computeWorkspaceStatus(workspace, options) {
     if (reconstructed3.has(key)) continue;
     if (brokenFiles.has(recordFile)) continue;
     if (recordState.conflictServerHash === null) continue;
-    if (recordState.recordKind === "localized-text" && isLocalizedText(recordState.data) && recordState.data.memberSource !== void 0)
-      continue;
+    if (isSharedMemberText(recordState)) continue;
     if (recordState.recordKind === "value") {
       deletedValueIds.add(recordState.recordId);
     }
@@ -118235,6 +118222,9 @@ function computeWorkspaceStatus(workspace, options) {
       casBaseHash: recordState.conflictServerHash !== void 0 ? recordState.conflictServerHash : recordState.contentHash
     });
   }
+  const sourceTextByUri = new Map(
+    sourceEntries.map((entry) => [entry.relPath, entry.source])
+  );
   const referenceFailures = drainValueReferenceObligationsV4(
     prospectiveState,
     manifest,
@@ -118242,9 +118232,7 @@ function computeWorkspaceStatus(workspace, options) {
       registry: valueLowerRegistry,
       analysis: projectAnalysisV4,
       deletedValueIds,
-      sourceTextByUri: new Map(
-        sourceEntries.map((entry) => [entry.relPath, entry.source])
-      )
+      sourceTextByUri
     }
   );
   for (const failure of referenceFailures) {
@@ -118261,16 +118249,7 @@ function computeWorkspaceStatus(workspace, options) {
   }
   reportPhase("record-diff-references", "Checking packed values\u2026");
   if (referenceFailures.length > 0) {
-    return {
-      changes: [],
-      conflictedFiles,
-      parseErrors,
-      parseWarnings,
-      reconstructed: /* @__PURE__ */ new Map(),
-      authoredValueSeeds: /* @__PURE__ */ new Map(),
-      binaryChanges: [],
-      binaryFiles: []
-    };
+    return refusedStatus(conflictedFiles, parseErrors, parseWarnings);
   }
   const unanchoredValueDeletes = unanchoredValueDeleteIds({
     records: workspace.state.records,
@@ -118294,16 +118273,7 @@ function computeWorkspaceStatus(workspace, options) {
           "value-base-desync"
         )
       );
-      return {
-        changes: [],
-        conflictedFiles,
-        parseErrors,
-        parseWarnings,
-        reconstructed: /* @__PURE__ */ new Map(),
-        authoredValueSeeds: /* @__PURE__ */ new Map(),
-        binaryChanges: [],
-        binaryFiles: []
-      };
+      return refusedStatus(conflictedFiles, parseErrors, parseWarnings);
     }
     parseWarnings.push(
       new SchemaSourceError(
@@ -118316,6 +118286,23 @@ function computeWorkspaceStatus(workspace, options) {
       )
     );
   }
+  if (valueLowerRegistry.storedRowClaims.size > 0) {
+    for (const claim of valueLowerRegistry.storedRowClaims.values()) {
+      const position = composeReferenceSitePosition(
+        claim.site,
+        sourceTextByUri
+      );
+      parseErrors.push(
+        new SchemaSourceError(
+          claim.message,
+          position.file,
+          position.line,
+          position.column
+        )
+      );
+    }
+    return refusedStatus(conflictedFiles, parseErrors, parseWarnings);
+  }
   for (let index = changes.length - 1; index >= 0; index -= 1) {
     const change = changes[index];
     if (change === void 0 || change.kind !== "update") continue;
@@ -119502,6 +119489,21 @@ function summarizeFieldDiff(baseData3, nextData) {
   }
   return lines;
 }
+function isSharedMemberText(record6) {
+  return record6.recordKind === "localized-text" && isLocalizedText(record6.data) && record6.data.memberSource !== void 0;
+}
+function refusedStatus(conflictedFiles, parseErrors, parseWarnings) {
+  return {
+    changes: [],
+    conflictedFiles,
+    parseErrors,
+    parseWarnings,
+    reconstructed: /* @__PURE__ */ new Map(),
+    authoredValueSeeds: /* @__PURE__ */ new Map(),
+    binaryChanges: [],
+    binaryFiles: []
+  };
+}
 var ANIMATION_DOCUMENT_RECORD_KINDS, ANIMATION_REPLAY_RECORD_KINDS, PROSPECTIVE_ANIMATION_RECORD_KINDS;
 var init_workspace_status_core = __esm({
   "src/project-source/workspace-status-core.ts"() {
@@ -121563,8 +121565,8 @@ function animationConstructorProjectionTargetValueIds(context, classId, value) {
       classId,
       projection.memberId
     );
-    const childValueId = schemaKey === null ? void 0 : value.value[schemaKey];
-    const childValue = typeof childValueId === "string" ? context.values.get(childValueId) : void 0;
+    const childValueId2 = schemaKey === null ? void 0 : value.value[schemaKey];
+    const childValue = typeof childValueId2 === "string" ? context.values.get(childValueId2) : void 0;
     const projectedMember = context.members.get(projection.memberId);
     if (childValue !== void 0 && projectedMember !== void 0 && numberField(projectedMember, "kind") === 9 /* Lookup */ && Array.isArray(childValue.value) && typeof childValue.value[0] === "string") {
       targetIds.push(childValue.value[0]);
@@ -121717,6 +121719,8 @@ function createValueLowerRegistryV4(options = {}) {
     referenceObligations: [],
     initAuthoredRowIds: /* @__PURE__ */ new Map(),
     loweringFailures: [],
+    storedRowClaims: /* @__PURE__ */ new Map(),
+    placedStoredRowIds: /* @__PURE__ */ new Set(),
     pendingValueIdentitySites: /* @__PURE__ */ new Map(),
     initializerReconciliations: /* @__PURE__ */ new Map()
   };
@@ -121849,6 +121853,8 @@ function buildValueLowerContext(state, manifest, options = {}) {
     ),
     referenceObligations: registry.referenceObligations,
     loweringFailures: registry.loweringFailures,
+    storedRowClaims: registry.storedRowClaims,
+    placedStoredRowIds: registry.placedStoredRowIds,
     pendingValueIdentitySites: registry.pendingValueIdentitySites,
     initializerReconciliations: registry.initializerReconciliations,
     materializedConstructorExpressions: registry.materializedConstructorExpressions,
@@ -121954,14 +121960,16 @@ function entrySliceRequiresEvaluation(entry, declaredConstructors2, entryClassNa
   }
 }
 function indexAuthoredRowIds(index, initSource, owner) {
-  const pattern = /@id\(\s*"((?:[^"\\]|\\.)*)"\s*\)/g;
-  let match = pattern.exec(initSource);
-  while (match !== null) {
+  for (const authored of authoredRowIds(initSource)) {
+    index.set(authored, owner);
+  }
+}
+function* authoredRowIds(initSource) {
+  for (const match of initSource.matchAll(
+    /@id\(\s*"((?:[^"\\]|\\.)*)"\s*\)/g
+  )) {
     const authored = match[1];
-    if (authored !== void 0 && authored.length > 0) {
-      index.set(authored, owner);
-    }
-    match = pattern.exec(initSource);
+    if (authored !== void 0 && authored.length > 0) yield authored;
   }
 }
 function indexDeclaredInitializers(analysis) {
@@ -123538,7 +123546,8 @@ function lowerSeedRow(context, member, sourceExpression, source, valueId, path,
         expressionPosition: {
           line: sourceExpression.pos.line,
           column: sourceExpression.pos.column
-        }
+        },
+        nestedListEntries: idlessNestedListEntries(context, expression)
       });
     }
     const code = initializerExpressionSlice(authoredSlice);
@@ -123654,9 +123663,9 @@ function lowerSeedRow(context, member, sourceExpression, source, valueId, path,
         );
       }
       const childPath = `${path}.${schemaKey}`;
-      const childValueId = pendingNestedValueId(source, childPath);
-      if (rows.has(childValueId)) {
-        throw new Error(`Value construction reuses identity ${childValueId}.`);
+      const childValueId2 = pendingNestedValueId(source, childPath);
+      if (rows.has(childValueId2)) {
+        throw new Error(`Value construction reuses identity ${childValueId2}.`);
       }
       if (projectedMember.kind === "lookup") {
         if (argument2.kind !== "litString") {
@@ -123854,6 +123863,13 @@ function lowerSeedRow(context, member, sourceExpression, source, valueId, path,
   registerSeedRow(context, rows, row, source, sourceExpression);
   return row;
 }
+function* storedRowIdsRecreatedBy(context, row) {
+  if (context.state[`value:${row.id}`] !== void 0) yield row.id;
+  if (row.nodeType !== "initializer") return;
+  for (const authored of authoredRowIds(row.code)) {
+    if (context.state[`value:${authored}`] !== void 0) yield authored;
+  }
+}
 function registerSeedRow(context, rows, row, source, expression) {
   if (rows.has(row.id)) {
     throw new Error(`Value construction reuses identity ${row.id}.`);
@@ -123866,6 +123882,15 @@ function registerSeedRow(context, rows, row, source, expression) {
     rows.set(row.id, row);
     return;
   }
+  if (!context.structuralConstruction) {
+    for (const storedId of storedRowIdsRecreatedBy(context, row)) {
+      if (context.storedRowClaims.has(storedId)) continue;
+      context.storedRowClaims.set(storedId, {
+        message: `Value ${source.label} names existing row @id(${JSON.stringify(storedId)}) inside a new row. A row keeps its parent: drop the @id to create a new row.`,
+        site: referenceSite(source, expression)
+      });
+    }
+  }
   rows.set(row.id, row);
   context.pendingValues.set(row.id, row);
   if (row.containerId !== void 0) {
@@ -124782,8 +124807,8 @@ function lowerConstructorProjections(context, schemaClass2, expression, base, ba
     argument: argument2,
     argumentIndex
   } of resolved) {
-    const childValueId = baseBody[schemaKey];
-    if (typeof childValueId !== "string") {
+    const childValueId2 = baseBody[schemaKey];
+    if (typeof childValueId2 !== "string") {
       throw new Error(
         `Class value ${String(base.id)}.${schemaKey} has no existing structural row.`
       );
@@ -124794,27 +124819,27 @@ function lowerConstructorProjections(context, schemaClass2, expression, base, ba
           `Class value ${String(base.id)}.${schemaKey} requires a value-row id string literal.`
         );
       }
-      const projectedBase = valueBase(context, childValueId);
+      const projectedBase = valueBase(context, childValueId2);
       addReconstructed(
         context,
         "value",
-        childValueId,
+        childValueId2,
         { ...valueFileFields(projectedBase), value: [argument2.value] },
         source.source
       );
-      body[schemaKey] = childValueId;
+      body[schemaKey] = childValueId2;
       continue;
     }
     lowerValueRow(
       context,
       projectedMember,
       argument2,
-      childValueId,
+      childValueId2,
       source,
       environment,
       argumentSlices[argumentIndex]
     );
-    body[schemaKey] = childValueId;
+    body[schemaKey] = childValueId2;
   }
 }
 function classInheritanceChain(classes, classId) {
@@ -125325,6 +125350,12 @@ function lowerListValue(context, member, expression, base, source, inheritedEnvi
       );
       continue;
     }
+    recordRepeatedRow(
+      context,
+      itemId,
+      `List ${member.name}`,
+      referenceSite(source, element)
+    );
     const child = valueBase(context, itemId);
     if (member.listKind === "unordered" && child.containerId !== base.id) {
       throw new Error(
@@ -125348,6 +125379,16 @@ function lowerListValue(context, member, expression, base, source, inheritedEnvi
     value: member.listKind === "unordered" ? [] : ids
   };
 }
+function recordRepeatedRow(context, rowId, collection, site) {
+  if (!context.placedStoredRowIds.has(rowId)) {
+    context.placedStoredRowIds.add(rowId);
+    return;
+  }
+  context.loweringFailures.push({
+    message: `${collection} places existing row @id(${JSON.stringify(rowId)}), which source already places elsewhere. A row has one position: drop the @id on the copy to create a new row.`,
+    site
+  });
+}
 function lowerPendingListItem(context, member, expression, source, path, containerId, environment, authoredSlice) {
   const rows = /* @__PURE__ */ new Map();
   const localizedTexts = /* @__PURE__ */ new Map();
@@ -125415,6 +125456,12 @@ function lowerDictionaryValue(context, member, expression, base, source, inherit
         `Dictionary ${member.name}[${JSON.stringify(key)}] has no existing row. New dictionary entries are not implemented by this slice.`
       );
     }
+    recordRepeatedRow(
+      context,
+      valueId,
+      `Dictionary ${member.name}`,
+      referenceSite(source, entry.value)
+    );
     body[key] = lowerValueRow(
       context,
       entryMember,
@@ -125486,14 +125533,20 @@ function lowerEnum2(context, member, expression) {
     throw new Error(`Enum member ${member.name} requires [...].`);
   const options = context.enumOptions.get(member.enumId);
   if (options === void 0) throw new Error(`Unknown enum ${member.enumId}.`);
+  const enumName = context.enumNames.get(member.enumId);
+  if (enumName === void 0) {
+    throw new Error(`Enum ${member.enumId} has no manifest name.`);
+  }
+  const subject = `Enum member ${member.name}`;
   return elements.map((entry) => {
-    if (entry.kind !== "contextualEnum") {
+    const optionName = enumOptionSpelling(entry, enumName, subject);
+    if (optionName === null) {
       throw new Error(
-        `Enum member ${member.name} requires contextual .Option values.`
+        `${subject} requires .Option or ${enumName}.Option values.`
       );
     }
-    const id2 = options.get(entry.name);
-    if (id2 === void 0) throw new Error(`Enum has no option ${entry.name}.`);
+    const id2 = options.get(optionName);
+    if (id2 === void 0) throw new Error(`Enum has no option ${optionName}.`);
     return id2;
   });
 }
@@ -126079,17 +126132,17 @@ function indexValuePlacements(state, options = {}) {
     }
     const body = isObjectRecord2(row.body) ? row.body : null;
     if (body === null) continue;
-    for (const [memberName, childValueId] of Object.entries(body)) {
-      if (typeof childValueId !== "string") continue;
-      const placementKey = `${memberName}:${childValueId}`;
+    for (const [memberName, childValueId2] of Object.entries(body)) {
+      if (typeof childValueId2 !== "string") continue;
+      const placementKey = `${memberName}:${childValueId2}`;
       if (!containerBodyByPlacement.has(placementKey)) {
         containerBodyByPlacement.set(placementKey, body);
       }
       const placed = mutablePlacedValueIds.get(memberName) ?? /* @__PURE__ */ new Set();
-      placed.add(childValueId);
+      placed.add(childValueId2);
       mutablePlacedValueIds.set(memberName, placed);
       const placement = {
-        valueId: childValueId,
+        valueId: childValueId2,
         schemaKey: memberName,
         containerValueId: row.id,
         containerClassId: row.classId
@@ -126097,9 +126150,9 @@ function indexValuePlacements(state, options = {}) {
       const byKey = placementsBySchemaKey.get(memberName) ?? [];
       byKey.push(placement);
       placementsBySchemaKey.set(memberName, byKey);
-      const byValue = placementsByValueId.get(childValueId) ?? [];
+      const byValue = placementsByValueId.get(childValueId2) ?? [];
       byValue.push(placement);
-      placementsByValueId.set(childValueId, byValue);
+      placementsByValueId.set(childValueId2, byValue);
     }
   }
   const valueIdByMemberId = /* @__PURE__ */ new Map();
@@ -126570,6 +126623,68 @@ function fileTargetId(context, expression, registry) {
   }
   return null;
 }
+function idlessNestedListEntries(context, expression) {
+  const entries = [];
+  let spellable = true;
+  const visit = (node, path) => {
+    const { expression: unwrapped } = annotatedValue(node);
+    if (unwrapped.kind === "new") {
+      for (const field of unwrapped.initializer ?? []) {
+        visit(field.value, [...path, field.name]);
+      }
+      return;
+    }
+    if (unwrapped.kind === "litDict") {
+      for (const entry of unwrapped.entries) {
+        if (entry.key.kind === "litString") {
+          visit(entry.value, [...path, entry.key.value]);
+          continue;
+        }
+        const before = entries.length;
+        visit(entry.value, path);
+        if (entries.length > before) spellable = false;
+      }
+      return;
+    }
+    if (unwrapped.kind !== "litList") return;
+    unwrapped.elements.forEach((element, index) => {
+      const entryPath = [...path, index];
+      if (annotatedValue(element).id === null && sourceValueSymbol(context, element) === null) {
+        const start = stampableEntryStart(element);
+        if (start === null) spellable = false;
+        else {
+          entries.push({
+            path: entryPath,
+            expressionPosition: { line: start.line, column: start.column }
+          });
+        }
+      }
+      visit(element, entryPath);
+    });
+  };
+  visit(expression, []);
+  return spellable ? entries : null;
+}
+function stampableEntryStart(expression) {
+  switch (expression.kind) {
+    case "member":
+    case "index":
+      return stampableEntryStart(expression.receiver);
+    case "call":
+      return stampableEntryStart(expression.callee);
+    case "force":
+      return stampableEntryStart(expression.operand);
+    case "binary":
+    case "coalesce":
+    case "conditional":
+    case "is":
+    case "lambda":
+    case "annotated":
+      return null;
+    default:
+      return expression.pos;
+  }
+}
 function memberPath2(expression) {
   if (expression.kind === "ident") return expression.name;
   if (expression.kind !== "member") return null;
@@ -128006,10 +128121,10 @@ function constructorProjectionSource(context, classId, body, visited, environmen
       classId,
       projection.memberId
     );
-    const childValueId = schemaKey === null ? void 0 : body[schemaKey];
-    const childValue = typeof childValueId === "string" ? context.values.get(childValueId) : void 0;
+    const childValueId2 = schemaKey === null ? void 0 : body[schemaKey];
+    const childValue = typeof childValueId2 === "string" ? context.values.get(childValueId2) : void 0;
     const projectedMember = context.members.get(projection.memberId);
-    if (schemaKey === null || typeof childValueId !== "string" || childValue === void 0 || projectedMember === void 0) {
+    if (schemaKey === null || typeof childValueId2 !== "string" || childValue === void 0 || projectedMember === void 0) {
       throw new Error(
         `Class ${context.manifestClasses.get(classId)?.name ?? classId} constructor projection ${projection.parameterName} has no stored projected value.`
       );
@@ -128024,7 +128139,7 @@ function constructorProjectionSource(context, classId, body, visited, environmen
           `Class ${context.manifestClasses.get(classId)?.name ?? classId} constructor projection ${projection.parameterName} requires exactly one referenced value.`
         );
       }
-      visited.add(childValueId);
+      visited.add(childValueId2);
       targetValueIds.push(targetIds[0]);
       argumentsValue.push(
         `${projection.parameterName}: ${quote5(targetIds[0])}`
@@ -128035,7 +128150,7 @@ function constructorProjectionSource(context, classId, body, visited, environmen
       `${projection.parameterName}: ${emitValue(
         context,
         projectedMember,
-        childValueId,
+        childValueId2,
         {
           definitionSite: true,
           writeIdentity: false,
@@ -133950,7 +134065,10 @@ ${blockingErrors.map((error) => `  ${error.message}`).join("\n")}`
     workspace,
     replacements.exact,
     localStatus.pendingValueIdentitySites,
-    { sourceSnapshot: localStatus.sourceSnapshot }
+    {
+      sourceSnapshot: localStatus.sourceSnapshot,
+      committedValueAtPath: committedValueAtPathReader(nextRecords)
+    }
   );
   const localRecords = rewriteReconstructedRecords(
     localStatus.reconstructed,
@@ -133978,7 +134096,8 @@ ${blockingErrors.map((error) => `  ${error.message}`).join("\n")}`
   for (const [key, state] of Object.entries(nextRecords)) {
     const prior = previousRecords[key];
     const local = localRecords.get(key);
-    if (local === void 0 && prior?.file !== void 0) continue;
+    if (local === void 0 && prior?.file !== void 0 && !isSharedMemberText(state))
+      continue;
     const submitted = submittedByKey.get(key);
     const emitData = local === void 0 ? state.data : changedKeys.has(key) && submitted !== void 0 ? mergeCommittedRecordWithLaterLocalEdits(
       state.recordKind,
@@ -134517,12 +134636,10 @@ function materializeAssignedSchemaIdsInAuthoredSource(workspace, replacements, p
         entry.identity.source.range.start.line,
         entry.identity.source.range.start.character
       );
-      const indentation = sourceIndentationAt(source, start);
-      const newline = source.includes("\r\n") ? "\r\n" : "\n";
       edits.push({
         start,
         end: start,
-        text: `@id(${JSON.stringify(assignedId)})${newline}${indentation}`
+        text: idStampText(source, start, assignedId)
       });
     } else {
       const quotedPendingId = JSON.stringify(pendingId2);
@@ -134560,15 +134677,18 @@ function materializeAssignedSchemaIdsInAuthoredSource(workspace, replacements, p
       site.expressionPosition.column
     );
     if (expressionOffset === null) continue;
-    const insertion = initializerOffset + expressionOffset;
-    const indentation = sourceIndentationAt(source, insertion);
-    const newline = source.includes("\r\n") ? "\r\n" : "\n";
-    const edits = editsByUri.get(site.uri) ?? [];
-    edits.push({
-      start: insertion,
-      end: insertion,
-      text: `@id(${JSON.stringify(assignedId)})${newline}${indentation}`
+    const stamp = (offset, id2) => ({
+      start: offset,
+      end: offset,
+      text: idStampText(source, offset, id2)
     });
+    const entryStamps = options.committedValueAtPath === void 0 ? [] : nestedListEntryStamps(site, assignedId, options.committedValueAtPath);
+    if (entryStamps === null) continue;
+    const edits = editsByUri.get(site.uri) ?? [];
+    edits.push(stamp(initializerOffset + expressionOffset, assignedId));
+    for (const entry of entryStamps) {
+      edits.push(stamp(initializerOffset + entry.offset, entry.id));
+    }
     editsByUri.set(site.uri, edits);
     const handled = handledByUri.get(site.uri) ?? /* @__PURE__ */ new Set();
     handled.add(pendingId2);
@@ -134602,6 +134722,49 @@ function materializeAssignedSchemaIdsInAuthoredSource(workspace, replacements, p
   }
   return preserved;
 }
+function nestedListEntryStamps(site, rowId, committedValueAtPath) {
+  if (site.nestedListEntries === null) return null;
+  const stamps = [];
+  for (const entry of site.nestedListEntries) {
+    const id2 = committedValueAtPath(rowId, entry.path);
+    if (id2 === null) return null;
+    const offset = sourceOffsetInsideInitializer(
+      site.initializer,
+      entry.expressionPosition.line,
+      entry.expressionPosition.column
+    );
+    if (offset === null) return null;
+    if (precedingNonWhitespace(site.initializer, offset) === "(") return null;
+    stamps.push({ offset, id: id2 });
+  }
+  return stamps;
+}
+function precedingNonWhitespace(text, offset) {
+  let index = offset - 1;
+  while (index >= 0 && /\s/u.test(text[index] ?? "")) index -= 1;
+  return text[index];
+}
+function committedValueAtPathReader(records2) {
+  let rows;
+  return (rootId, path) => {
+    rows ??= storedValueRowsByIdV4(Object.values(records2));
+    let id2 = rootId;
+    for (const key of path) {
+      const next = childValueId(rows.get(id2)?.value, key);
+      if (next === null) return null;
+      id2 = next;
+    }
+    return id2;
+  };
+}
+function childValueId(body, key) {
+  if (typeof key === "number") {
+    const entry = Array.isArray(body) ? body[key] : void 0;
+    return typeof entry === "string" ? entry : null;
+  }
+  const child = isObjectRecord2(body) ? body[key] : void 0;
+  return typeof child === "string" ? child : null;
+}
 function sourceOffsetInsideInitializer(source, oneBasedLine, oneBasedColumn) {
   if (oneBasedLine < 1 || oneBasedColumn < 1) return null;
   let offset = 0;
@@ -134631,9 +134794,13 @@ function sourceOffsetAt2(source, line, character) {
   }
   return Math.min(offset + character, source.length);
 }
-function sourceIndentationAt(source, offset) {
+function idStampText(source, offset, id2) {
+  const annotation2 = `@id(${JSON.stringify(id2)})`;
   const lineStart = source.lastIndexOf("\n", Math.max(0, offset - 1)) + 1;
-  return /^[\t ]*/u.exec(source.slice(lineStart, offset))?.[0] ?? "";
+  const prefix = source.slice(lineStart, offset);
+  if (!/^[\t ]*$/u.test(prefix)) return `${annotation2} `;
+  const newline = source.includes("\r\n") ? "\r\n" : "\n";
+  return `${annotation2}${newline}${prefix}`;
 }
 async function buildPostPushCompileSchema(workspace, status) {
   const byKind = /* @__PURE__ */ new Map();
@@ -136575,8 +136742,7 @@ ${blockingErrors.map((error) => `  ${error.message}`).join("\n")}`
       baseState.data,
       mainLocale
     );
-    const locallyDeleted = hasBaseline && baseState.file !== void 0 && local === void 0 && // Member-owned texts survive losing their last inline source reference.
-    !(serverRecord.recordKind === "localized-text" && isLocalizedText(baseState.data) && baseState.data.memberSource !== void 0);
+    const locallyDeleted = hasBaseline && baseState.file !== void 0 && local === void 0 && !isSharedMemberText(baseState);
     if (!serverChanged) {
       plans.set(key, {
         emitData: locallyDeleted ? void 0 : local === void 0 ? serverRecord.data : mergeProjectDocumentRecord(
@@ -137304,7 +137470,6 @@ var init_pull = __esm({
   "src/commands/pull.ts"() {
     "use strict";
     init_push();
-    init_localization2();
     init_source_layout();
     init_project_read_base();
     init_document();
@@ -140445,7 +140610,7 @@ var init_registry2 = __esm({
   "schema-contract/registry.mjs"() {
     "use strict";
     PROJECT_SCHEMA_CONTRACT = Object.freeze({
-      cliVersion: "0.57.3",
+      cliVersion: "0.58.1",
       projectFileUploadBatchSize: 32,
       documentRecords: {
         member: {
@@ -144978,8 +145143,8 @@ function collectClassInstances(document, targetClassId, memberById2, valueById,
       const schema = schemaClass2 !== void 0 && isObjectRecord2(schemaClass2.schema) ? schemaClass2.schema : {};
       const instanceValue = valueRecord.value;
       if (isObjectRecord2(instanceValue)) {
-        for (const [key, childValueId] of Object.entries(instanceValue)) {
-          walk(schema[key], childValueId);
+        for (const [key, childValueId2] of Object.entries(instanceValue)) {
+          walk(schema[key], childValueId2);
         }
       }
       return;
@@ -144987,8 +145152,8 @@ function collectClassInstances(document, targetClassId, memberById2, valueById,
     if (memberKind === 6) {
       const entries = valueRecord.value;
       if (Array.isArray(entries)) {
-        for (const childValueId of entries) {
-          walk(member.entryMemberId, childValueId);
+        for (const childValueId2 of entries) {
+          walk(member.entryMemberId, childValueId2);
         }
       }
       return;
@@ -144996,8 +145161,8 @@ function collectClassInstances(document, targetClassId, memberById2, valueById,
     if (memberKind === 5) {
       const entries = valueRecord.value;
       if (isObjectRecord2(entries)) {
-        for (const childValueId of Object.values(entries)) {
-          walk(member.entryMemberId, childValueId);
+        for (const childValueId2 of Object.values(entries)) {
+          walk(member.entryMemberId, childValueId2);
         }
       }
     }
@@ -147013,10 +147178,10 @@ function dryrunOwnership(document, valueById, saveBindings = /* @__PURE__ */ new
       const childMemberByKey = new Map(
         storageResolver.mergedSchema(classId).map((entry) => [entry.schemaKey, entry.memberId])
       );
-      for (const [key, childValueId] of Object.entries(value.value)) {
+      for (const [key, childValueId2] of Object.entries(value.value)) {
         const childMemberId = childMemberByKey.get(key);
-        if (childMemberId !== void 0 && typeof childValueId === "string") {
-          walkOwnedGraph([...memberPath3, childMemberId], childValueId);
+        if (childMemberId !== void 0 && typeof childValueId2 === "string") {
+          walkOwnedGraph([...memberPath3, childMemberId], childValueId2);
         }
       }
       return;
@@ -147025,9 +147190,9 @@ function dryrunOwnership(document, valueById, saveBindings = /* @__PURE__ */ new
     if (unorderedList && (Array.isArray(value.value) || includeHistoricalNullLists && membership.has(valueId))) {
       const entryMemberId = storageResolver.resolvedEntryMemberId(memberId);
       if (entryMemberId === void 0) return;
-      for (const childValueId of membership.get(valueId) ?? []) {
-        if (typeof childValueId === "string") {
-          walkOwnedGraph([...memberPath3, entryMemberId], childValueId);
+      for (const childValueId2 of membership.get(valueId) ?? []) {
+        if (typeof childValueId2 === "string") {
+          walkOwnedGraph([...memberPath3, entryMemberId], childValueId2);
         }
       }
       return;
@@ -147036,9 +147201,9 @@ function dryrunOwnership(document, valueById, saveBindings = /* @__PURE__ */ new
       const entryMemberId = storageResolver.resolvedEntryMemberId(memberId);
       if (entryMemberId === void 0) return;
       const childIds = Array.isArray(value.value) ? value.value : Object.values(value.value);
-      for (const childValueId of childIds) {
-        if (typeof childValueId === "string") {
-          walkOwnedGraph([...memberPath3, entryMemberId], childValueId);
+      for (const childValueId2 of childIds) {
+        if (typeof childValueId2 === "string") {
+          walkOwnedGraph([...memberPath3, entryMemberId], childValueId2);
         }
       }
     }
@@ -148266,7 +148431,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.57.3");
+    console.log("0.58.1");
     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.57.3",
+  "version": "0.58.1",
   "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.57.3 -->
+<!-- reviewed-through-cli: 0.58.1 -->
 
 # Neo Compose CLI
 
@@ -63,6 +63,8 @@ opaque JSON or guessed syntax.
   values, files, or other records. `@system` is reserved for platform-owned
   system records; authoring it can make the record uneditable.
 - Preserve existing `@id` annotations through rename, reorder, and file moves.
+  A new row cannot reuse a stored row's `@id`, including inside a new parent:
+  author the new row without it.
 - Omit `@id` on new ordinary declarations and nested rows unless a same-push
   structural reference genuinely requires an explicit UUID. A successful push
   assigns the durable IDs and rewrites source.

package/skills/neocompose-cli/references/animation-and-world-authoring.md

@@ -71,7 +71,9 @@ initializer cannot assign them. `Cell` is the placement's writable field.
 
 Object `PlacementTiles` is a `List<NeoPlacementTile>`. Each entry marks a
 footprint cell with its own `Cell` member. It is independent of `NeoTile`. Rendered
-tile classes do not belong in this list.
+tile classes do not belong in this list. An object with no placement tiles
+occupies no cells. It doesn't block other placements, and cell queries don't
+return it.
 
 Convert a writable placement without changing its row identity or cell:
 

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.57.3 -->
+<!-- reviewed-through-cli: 0.58.1 -->
 ```
 
 The quoted version above is checked too, so this instruction cannot go stale

package/skills/neocompose-cli/references/values-identities-and-references.md

@@ -57,9 +57,11 @@ keys as quoted IDs when their option has been deleted.
 
 ## Identity rules
 
-Preserve every existing ID through rename, reorder, and file moves. For a new
-ordinary record, omit `@id` and let a successful real push assign and insert
-it. Dry-run and failed pushes leave tracked source unchanged.
+Preserve every existing ID through rename, reorder, and file moves. A new row
+cannot reuse a stored row's `@id`, including inside a new parent, and source
+cannot place one stored row in two collection positions. For a new ordinary record, omit
+`@id` and let a successful real push assign and insert it. Dry-run and failed pushes
+leave tracked source unchanged.
 
 Nested class/list rows remain independently addressable and keep inline IDs: