@neocompose/cli 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [0.30.0] - 2026-08-13
+
+### Added
+
+- P66 sealed classes: author a leaf type as `sealed class` in project source.
+  The modifier round-trips through pull and push, and the CLI rejects both
+  `sealed abstract` declarations and attempts to extend a sealed class.
+
+### Changed
+
+- Sealed classes are omitted from extends-position language completions, and
+  the project contract carries optional `isSealed` metadata. Absence and
+  explicit `false` are equivalent, so existing projects need no migration.
+- Unity export schema version is 20. Matching SDKs preserve the sealed
+  inheritance contract in generated C#.
+
+## [0.29.0] - 2026-08-12
+
+### Added
+
+- `Reference<T>(id: "...", withProvenance: true)` for executable NeoScript.
+  The opt-in flag resolves an authored row id to the nearest clone carrying it
+  as `sourceValueId` in the lexical receiver's ownership graph. It defaults to
+  `false`, preserving exact-ID behavior for every existing reference.
+
+### Changed
+
+- Animation child selectors created by the world UI and the legacy
+  `Child`-to-`Selector` reconciler now opt into provenance so clips authored
+  against a class default select each placement's cloned child.
+- Unity export schema version is 19 and NeoScript compiler revision is 9.
+  Older SDKs reject the export rather than silently ignoring provenance and
+  applying an override to the shared authored row.
+
 ## [0.28.0] - 2026-08-12
 
 ### Added

package/dist/neo.mjs

@@ -7891,7 +7891,7 @@ var NEOSCRIPT_COMPILER_REVISION;
 var init_strict_ir = __esm({
   "../packages/neoscript-language/src/strict-ir.ts"() {
     "use strict";
-    NEOSCRIPT_COMPILER_REVISION = 8;
+    NEOSCRIPT_COMPILER_REVISION = 9;
   }
 });
 
@@ -10597,9 +10597,34 @@ var init_strict_resolver = __esm({
                   expression.pos
                 );
               }
-              if (expression.args.length !== 1 || expression.argumentNames?.[0] !== "id" || expression.args[0]?.kind !== "litString" || expression.args[0].value.length === 0) {
+              const hasProvenanceArgument = expression.args.length === 2;
+              if (expression.args.length < 1 || expression.args.length > 2) {
                 throw new CompileError(
-                  "Reference<T> requires exactly one named id: string argument.",
+                  "Reference<T> requires id: string and optionally withProvenance: bool.",
+                  expression.pos
+                );
+              }
+              if (expression.argumentNames?.[0] !== "id") {
+                throw new CompileError(
+                  "Reference<T> requires id: as its first named argument.",
+                  expression.pos
+                );
+              }
+              if (expression.args[0]?.kind !== "litString" || expression.args[0].value.length === 0) {
+                throw new CompileError(
+                  "Reference<T> id must be a non-empty string literal.",
+                  expression.pos
+                );
+              }
+              if (hasProvenanceArgument && expression.argumentNames?.[1] !== "withProvenance") {
+                throw new CompileError(
+                  "Reference<T>'s second named argument must be withProvenance: bool.",
+                  expression.pos
+                );
+              }
+              if (hasProvenanceArgument && expression.args[1]?.kind !== "litBool") {
+                throw new CompileError(
+                  "Reference<T> withProvenance must be a boolean literal.",
                   expression.pos
                 );
               }
@@ -10613,7 +10638,8 @@ var init_strict_resolver = __esm({
               return {
                 pointer: {
                   type: "reference" /* Reference */,
-                  valueId: expression.args[0].value
+                  valueId: expression.args[0].value,
+                  ...expression.args[1]?.kind === "litBool" && expression.args[1].value ? { withProvenance: true } : {}
                 },
                 type: referencedType
               };
@@ -17350,7 +17376,7 @@ var init_project_schema_contract_generated = __esm({
   "../packages/neoscript-language/src/project-schema-contract.generated.ts"() {
     "use strict";
     PROJECT_SCHEMA_MANIFEST_FORMAT_VERSION = 3;
-    PROJECT_SCHEMA_MANIFEST_CONTRACT_VERSION = "3.10";
+    PROJECT_SCHEMA_MANIFEST_CONTRACT_VERSION = "3.11";
     PROJECT_FILE_UPLOAD_BATCH_SIZE = 32;
     NEO_PROJECT_SOURCE_RECORD_CONTRACT = {
       "recordFields": {
@@ -17411,6 +17437,7 @@ var init_project_schema_contract_generated = __esm({
           "extendsClassId",
           "implementsInterfaceIds",
           "hiddenInMemberSelector",
+          "isSealed",
           "isAbstract",
           "system",
           "allowedStorage",
@@ -21834,7 +21861,9 @@ function validateReferenceExpression(expression, expected, environment, uri, ran
   const typeArguments = expression.typeArguments ?? [];
   const names = expression.argumentNames ?? [];
   const idIndex = names.findIndex((name) => name === "id");
+  const provenanceIndex = names.findIndex((name) => name === "withProvenance");
   const hasId = idIndex >= 0;
+  const hasProvenance = provenanceIndex >= 0;
   const argument2 = expression.args[hasId ? idIndex : 0];
   const malformed = (message) => pushDiagnostic(
     diagnostics,
@@ -21878,9 +21907,11 @@ function validateReferenceExpression(expression, expected, environment, uri, ran
     }
     return;
   }
-  if (expression.args.length !== 1 || hasId && (idIndex !== 0 || names.some((name) => name !== "id")) || !hasId && names.some((name) => name !== null)) {
+  const validIdShape = hasId && idIndex === 0 && expression.args.length === (hasProvenance ? 2 : 1) && (!hasProvenance || provenanceIndex === 1) && names.every((name) => name === "id" || name === "withProvenance");
+  const validSymbolShape = !hasId && !hasProvenance && expression.args.length === 1 && names.every((name) => name === null);
+  if (!validIdShape && !validSymbolShape) {
     malformed(
-      "Reference requires exactly one symbol argument or one named id: string argument."
+      "Reference requires one symbol argument, or id: string followed by optional withProvenance: bool."
     );
     return;
   }
@@ -21890,6 +21921,10 @@ function validateReferenceExpression(expression, expected, environment, uri, ran
       malformed("Reference id must be one non-empty string literal.");
       return;
     }
+    if (hasProvenance && expression.args[provenanceIndex]?.kind !== "litBool") {
+      malformed("Reference withProvenance must be a boolean literal.");
+      return;
+    }
     if (!explicit && expected?.name !== "string") {
       malformed("Reference(id: ...) requires an explicit generic target type.");
       return;
@@ -25986,6 +26021,7 @@ function projectFallbackCompletions(analysis, document, position) {
   const expectedTypeName = construction?.expectedTypeName ?? recoveredInitializerType;
   const afterNew = expression && projectAfterNewAt(document, position);
   const typePosition = projectTypePositionAt(analysis, document, position);
+  const classBasePosition = projectClassBasePositionAt(document, position);
   const keywords = expression ? afterNew ? [] : ["new"] : typePosition ? [] : [
     "class",
     "interface",
@@ -26024,6 +26060,11 @@ function projectFallbackCompletions(analysis, document, position) {
       continue;
     }
     const isType = symbol.kind === "class" || symbol.kind === "interface" || symbol.kind === "enum" || symbol.kind === "genericParameter";
+    if (classBasePosition && symbol.kind === "class") {
+      const declaration = findTypeDeclaration(analysis, symbol.name);
+      if (declaration?.kind === "class" && declaration.modifiers.includes("sealed"))
+        continue;
+    }
     if (typePosition && !isType) continue;
     if (expression) {
       if (afterNew) {
@@ -26165,6 +26206,49 @@ function projectTypePositionAt(analysis, document, position) {
     line
   );
 }
+function projectClassBasePositionAt(document, position) {
+  const tokens = tokensBeforePosition(document.text, position);
+  let classIndex = -1;
+  for (let index = tokens.length - 1; index >= 0; index--) {
+    const text = tokens[index]?.text;
+    if (text === "class") {
+      classIndex = index;
+      break;
+    }
+    if (text === "{" || text === "}" || text === ";") return false;
+  }
+  if (classIndex < 0) return false;
+  let angleDepth = 0;
+  let parenthesisDepth = 0;
+  let bracketDepth = 0;
+  let colonIndex = -1;
+  for (let index = classIndex + 1; index < tokens.length; index++) {
+    const text = tokens[index]?.text;
+    if (text === "<") angleDepth++;
+    else if (text === ">") angleDepth = Math.max(0, angleDepth - 1);
+    else if (text === "(") parenthesisDepth++;
+    else if (text === ")") parenthesisDepth = Math.max(0, parenthesisDepth - 1);
+    else if (text === "[") bracketDepth++;
+    else if (text === "]") bracketDepth = Math.max(0, bracketDepth - 1);
+    else if (text === ":" && angleDepth === 0 && parenthesisDepth === 0 && bracketDepth === 0) {
+      colonIndex = index;
+      break;
+    } else if (text === "{" || text === "}" || text === ";") {
+      return false;
+    }
+  }
+  if (colonIndex < 0) return false;
+  angleDepth = 0;
+  for (let index = colonIndex + 1; index < tokens.length; index++) {
+    const text = tokens[index]?.text;
+    if (text === "<") angleDepth++;
+    else if (text === ">") angleDepth = Math.max(0, angleDepth - 1);
+    else if (angleDepth === 0 && (text === "(" || text === "{" || text === "}" || text === ";")) {
+      return false;
+    }
+  }
+  return true;
+}
 function sourceTypeAt(document, position) {
   const contains2 = (type) => {
     for (const argument2 of type.typeArguments) {
@@ -26596,7 +26680,11 @@ function projectSignatureHelp(analysis, document, position) {
     return signatureResult(`@${callee.text}`, parameters, activeParameter);
   }
   if (callee.text === "Reference") {
-    return signatureResult("Reference", ["symbol", "id"], activeParameter);
+    return signatureResult(
+      "Reference",
+      ["symbol or id", "withProvenance = false"],
+      activeParameter
+    );
   }
   if (callee.text === "Pause") {
     return signatureResult(
@@ -31482,6 +31570,7 @@ var init_document_contracts = __esm({
           "extendsClassId",
           "implementsInterfaceIds",
           "hiddenInMemberSelector",
+          "isSealed",
           "isAbstract",
           "system",
           "allowedStorage",
@@ -31496,6 +31585,7 @@ var init_document_contracts = __esm({
         derived: [],
         volatile: ["projectId", "createdAt", "updatedAt"],
         normalization: {
+          isSealed: "falseIsAbsent",
           targetMemberId: "nullIsAbsent",
           schemaKeyOrder: "nullIsAbsent",
           extendsClassId: "nullIsAbsent",
@@ -31764,6 +31854,10 @@ function normalizeDocumentFields(recordKind, value) {
       }
       continue;
     }
+    if (rule === "falseIsAbsent") {
+      if (current === false) delete normalized[field];
+      continue;
+    }
     const isFullMember = recordKind !== "member" || typeof normalized.extendsMemberId !== "string";
     if (recordKind === "member" && (current === void 0 || current === null) && rule.startsWith("missingIs") && !memberDefaultApplies(field, normalized.kind)) {
       if (current === null) delete normalized[field];
@@ -34361,6 +34455,7 @@ function schemaClassFromDocument(record3, context) {
     name: requiredString(data, "name", record3),
     ...optionalDocsTextProperty(data.docsText, record3),
     declarationModifier: data.isAbstract === true ? "abstract" : "concrete",
+    ...data.isSealed === void 0 ? {} : { isSealed: booleanValue(data.isSealed, record3, "isSealed") },
     schema: requiredRecord(data, "schema", record3),
     schemaKeyOrder: optionalStringArrayOrNull(data.schemaKeyOrder),
     extendsClassId: optionalStringOrNull(data.extendsClassId),
@@ -34396,6 +34491,7 @@ function schemaClassToDocument(schemaClass2) {
     implementsInterfaceIds: schemaClass2.implementsInterfaceIds,
     hiddenInMemberSelector: schemaClass2.hiddenInMemberSelector,
     isAbstract: schemaClass2.declarationModifier === "abstract",
+    isSealed: schemaClass2.isSealed,
     system: systemToDocument(schemaClass2.system),
     allowedStorage: schemaClass2.allowedStorage,
     allowedStorageKeys: schemaClass2.allowedStorageKeys,
@@ -35670,6 +35766,7 @@ function assertNeoSchemaClass(value, path) {
     ],
     [
       "docsText",
+      "isSealed",
       "constructorProjections",
       "constructorIds",
       "requiredConstructorId"
@@ -35685,6 +35782,9 @@ function assertNeoSchemaClass(value, path) {
   );
   stringRecord(type.schema, `${path}.schema`);
   nullableStringArray(type.schemaKeyOrder, `${path}.schemaKeyOrder`);
+  if (type.isSealed !== void 0) {
+    booleanAt(type.isSealed, `${path}.isSealed`);
+  }
   nullableNonEmptyString(type.extendsClassId, `${path}.extendsClassId`);
   stringArray(type.implementsInterfaceIds, `${path}.implementsInterfaceIds`);
   booleanAt(type.hiddenInMemberSelector, `${path}.hiddenInMemberSelector`);
@@ -38455,7 +38555,9 @@ function isNSKeyOf(value) {
 }
 function isNSPointerReference(value) {
   const v = value;
-  return v?.type === "reference" /* reference */ && typeof v?.valueId === "string";
+  if (v?.type !== "reference" /* reference */) return false;
+  if (typeof v.valueId !== "string") return false;
+  return v.withProvenance === void 0 || typeof v.withProvenance === "boolean";
 }
 function isNSPointerVariable(value) {
   const v = value;
@@ -39442,7 +39544,7 @@ function isNeoSchemaClassBase(value) {
   const v = value;
   return typeof v?.name === "string" && isValidDocsText(v.docsText) && isClassSchema(v?.schema) && isOptionalSchemaKeyOrder(v?.schemaKeyOrder) && (v.implementsInterfaceIds === void 0 || v.implementsInterfaceIds === null || Array.isArray(v.implementsInterfaceIds) && v.implementsInterfaceIds.every(
     (interfaceId) => typeof interfaceId === "string" && interfaceId.length > 0
-  )) && typeof v?.hiddenInMemberSelector === "boolean" && typeof v?.isAbstract === "boolean" && (v.allowedStorage === void 0 || v.allowedStorage === null || isEffectiveMemberStorage(v.allowedStorage)) && (v.allowedStorageKeys === void 0 || v.allowedStorageKeys === null || Array.isArray(v.allowedStorageKeys) && v.allowedStorageKeys.every((key) => typeof key === "string")) && (v.genericParams === void 0 || v.genericParams === null || Array.isArray(v.genericParams) && v.genericParams.every(isGenericParamDeclaration)) && (v.extendsGenericBindings === void 0 || v.extendsGenericBindings === null || isGenericBindingsRecord(v.extendsGenericBindings)) && (v.constructorProjections === void 0 || v.constructorProjections === null || Array.isArray(v.constructorProjections) && v.constructorProjections.every(isNeoClassConstructorProjection) && v.system?.kind === SystemProtectionKind.WorldAuthoring) && (v.constructorIds === void 0 || v.constructorIds === null || Array.isArray(v.constructorIds) && v.constructorIds.every(
+  )) && typeof v?.hiddenInMemberSelector === "boolean" && typeof v?.isAbstract === "boolean" && (v.isSealed === void 0 || typeof v.isSealed === "boolean") && (v.allowedStorage === void 0 || v.allowedStorage === null || isEffectiveMemberStorage(v.allowedStorage)) && (v.allowedStorageKeys === void 0 || v.allowedStorageKeys === null || Array.isArray(v.allowedStorageKeys) && v.allowedStorageKeys.every((key) => typeof key === "string")) && (v.genericParams === void 0 || v.genericParams === null || Array.isArray(v.genericParams) && v.genericParams.every(isGenericParamDeclaration)) && (v.extendsGenericBindings === void 0 || v.extendsGenericBindings === null || isGenericBindingsRecord(v.extendsGenericBindings)) && (v.constructorProjections === void 0 || v.constructorProjections === null || Array.isArray(v.constructorProjections) && v.constructorProjections.every(isNeoClassConstructorProjection) && v.system?.kind === SystemProtectionKind.WorldAuthoring) && (v.constructorIds === void 0 || v.constructorIds === null || Array.isArray(v.constructorIds) && v.constructorIds.every(
     (constructorId) => typeof constructorId === "string" && constructorId.length > 0
   ) && new Set(v.constructorIds).size === v.constructorIds.length) && (v.requiredConstructorId === void 0 || v.requiredConstructorId === null || typeof v.requiredConstructorId === "string" && v.requiredConstructorId.length > 0 && (v.constructorIds ?? []).length === 0) && (v.targetMemberId === void 0 || v.targetMemberId === null || typeof v.targetMemberId === "string" && v.targetMemberId.length > 0) && (v.system === void 0 || v.system === null || isSystemMetadata(v.system));
 }
@@ -46642,7 +46744,7 @@ function emitClass(context, schemaClass2, memberIds) {
     ...schemaClass2.system ? [systemAnnotation2(schemaClass2.system)] : [],
     ...relationsAnnotations(context, schemaClass2)
   ];
-  const modifier = schemaClass2.declarationModifier === "abstract" ? "abstract " : "";
+  const modifier = schemaClass2.isSealed ? "sealed " : schemaClass2.declarationModifier === "abstract" ? "abstract " : "";
   const generics = schemaClass2.genericParameters.length ? `<
 ${schemaClass2.genericParameters.map((parameter4) => {
     const constraint = parameter4.constraint ? ` extends ${parameter4.constraint.kind === "class" ? required(
@@ -51301,9 +51403,14 @@ function collectFunctions(args) {
       for (const action of node.actions) {
         if (!isObjectRecord2(action) || action.type !== 0 || !isObjectRecord2(action.logic))
           continue;
-        if (action.logic.sourceInline === true || action.logic.type === 0 && isCompleteUIAction(action.logic.action))
-          continue;
         const useId = stringField(action, "id");
+        if (action.logic.sourceInline === true) continue;
+        if (action.logic.type === 0) {
+          if (isCompleteUIAction(action.logic.action)) continue;
+          throw new Error(
+            `Dialogue action "${useId}" on actions node "${nodeId}" is incomplete. Complete or remove the action in Neo Compose before pulling.`
+          );
+        }
         add(action.logic, `action:${useId}`, "void");
       }
     }
@@ -52989,6 +53096,7 @@ function lowerClass(context, declaration) {
     name: declaration.name,
     ...declaration.docsText === void 0 ? {} : { docsText: declaration.docsText },
     declarationModifier: declaration.modifiers.includes("abstract") ? "abstract" : "concrete",
+    ...declaration.modifiers.includes("sealed") ? { isSealed: true } : {},
     schema,
     schemaKeyOrder: persistedSchemaOrder,
     extendsClassId,
@@ -54332,6 +54440,16 @@ function lowerExpressionValue(context, expression, declaredExpected, ownerClass,
       if (expression.callee.kind === "ident" && expression.callee.name === "Reference") {
         const index = expression.argumentNames?.findIndex((name) => name === "id") ?? -1;
         if (index >= 0) {
+          if (expression.argumentNames?.includes("withProvenance") === true) {
+            throw new Error(
+              `${path} writes Reference(id: ..., withProvenance: ...) as a persisted member value. Provenance-aware references are executable NeoScript values and must be used inside a function or delegate closure.`
+            );
+          }
+          if (expression.args.length !== 1 || expression.argumentNames?.some((name) => name !== "id")) {
+            throw new Error(
+              `${path} writes Reference(id: ...) with unsupported arguments.`
+            );
+          }
           const idArgument = expression.args[index];
           if (idArgument?.kind === "litString") return idArgument.value;
           throw new Error(
@@ -59911,13 +60029,14 @@ function evaluatorOwnershipDistances(rowId, indexes) {
   indexes.ownershipDistancesByRowId.set(rowId, distances);
   return distances;
 }
-function resolveRuntimeReferenceRow(sourceValueId, ctx) {
+function resolveRuntimeReferenceRow(sourceValueId, ctx, withProvenance) {
   const direct = evalValueById(
     ctx,
     sourceValueId,
     ctx.__runtimeSessionValues,
     ctx.__valueOverlay
   );
+  if (!withProvenance) return direct;
   const receiver = trackedRowForValueReference(ctx.thisValue, ctx);
   if (receiver === null) return direct;
   const indexes = evaluatorIndexes(ctx);
@@ -62128,7 +62247,11 @@ function evalPointer(pointer, scope, ctx) {
       return scope.get(pointer.variableId);
     }
     case "reference" /* reference */: {
-      const row = resolveRuntimeReferenceRow(pointer.valueId, ctx);
+      const row = resolveRuntimeReferenceRow(
+        pointer.valueId,
+        ctx,
+        pointer.withProvenance === true
+      );
       if (!row) {
         throw new NSGetterRuntimeError(
           `Missing value reference: ${pointer.valueId}`
@@ -76955,6 +77078,19 @@ function readClass(value) {
       throw new Error(`Class "${value.id}" schema value is invalid.`);
     }
   }
+  if (value.isSealed !== void 0 && typeof value.isSealed !== "boolean") {
+    throw new Error(`Class "${value.name}" (${value.id}) isSealed is invalid.`);
+  }
+  if (value.isAbstract !== void 0 && typeof value.isAbstract !== "boolean") {
+    throw new Error(
+      `Class "${value.name}" (${value.id}) isAbstract is invalid.`
+    );
+  }
+  if (value.isAbstract === true && value.isSealed === true) {
+    throw new Error(
+      `Class "${value.name}" (${value.id}) cannot be both abstract and sealed.`
+    );
+  }
   if (value.implementsInterfaceIds != null && (!Array.isArray(value.implementsInterfaceIds) || !value.implementsInterfaceIds.every((id2) => typeof id2 === "string"))) {
     throw new Error(`Class "${value.id}" implementsInterfaceIds is invalid.`);
   }
@@ -77227,6 +77363,14 @@ function assertProjectInterfaceDocumentValid(view, options = {}) {
   const classesById = new Map(
     classes.map((schemaClass2) => [schemaClass2.id, schemaClass2])
   );
+  for (const schemaClass2 of classes) {
+    if (schemaClass2.extendsClassId === void 0) continue;
+    const baseClass = classesById.get(schemaClass2.extendsClassId);
+    if (baseClass?.isSealed !== true) continue;
+    throw new Error(
+      `Class "${schemaClass2.name}" (${schemaClass2.id}) cannot extend sealed class "${baseClass.name}" (${baseClass.id}).`
+    );
+  }
   const genericParamConstraintsById = new Map(
     classes.flatMap(
       (schemaClass2) => (schemaClass2.genericParams ?? []).map(
@@ -104469,8 +104613,8 @@ var init_registry2 = __esm({
     "use strict";
     PROJECT_SCHEMA_CONTRACT = Object.freeze({
       formatVersion: 3,
-      contractVersion: "3.10",
-      cliVersion: "0.28.0",
+      contractVersion: "3.11",
+      cliVersion: "0.30.0",
       projectFileUploadBatchSize: 32,
       documentRecords: {
         member: {
@@ -104565,6 +104709,7 @@ var init_registry2 = __esm({
             "extendsClassId",
             "implementsInterfaceIds",
             "hiddenInMemberSelector",
+            "isSealed",
             "isAbstract",
             "system",
             "allowedStorage",
@@ -104579,6 +104724,7 @@ var init_registry2 = __esm({
           derived: [],
           volatile: ["projectId", "createdAt", "updatedAt"],
           normalization: {
+            isSealed: "falseIsAbsent",
             targetMemberId: "nullIsAbsent",
             schemaKeyOrder: "nullIsAbsent",
             extendsClassId: "nullIsAbsent",
@@ -111036,7 +111182,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.28.0");
+    console.log("0.30.0");
     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.28.0",
+  "version": "0.30.0",
   "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.28.0 -->
+<!-- reviewed-through-cli: 0.30.0 -->
 
 # Neo Compose CLI
 

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

@@ -109,12 +109,14 @@ override replaces the whole leaf.
 Frame overrides may change `Enabled`, `FlipX`, and `SortingOrder`; they may
 not add, remove, or reorder `Children`.
 
-Address direct children through selector delegates. A selector should implement
-the project's own stable identity contract, such as an immutable `Name`, slug,
-or semantic position; do not turn a mutable object-row ID back into identity by
-returning `Reference<T>(id: "...")`. Missing optional child slots are skipped
-with diagnostics when the authored slot is absent, while stale pre-provenance
-placements may still fail closed.
+Address direct children through selector delegates. Prefer the project's own
+stable identity contract, such as an immutable `Name`, slug, or semantic
+position. When a selector means one specific authored child slot whose
+placement clones carry `sourceValueId`, return
+`Reference<T>(id: "<authored-child-id>", withProvenance: true)`. The flag is
+opt-in and defaults to `false`; without it the ID is matched exactly. Missing
+optional child slots are skipped with diagnostics when the authored slot is
+absent, while stale pre-provenance placements may still fail closed.
 
 A placement row carries its `assetClassId` binding and optional `assetValueId`
 override beside its schema keys. They are row provenance, not declared schema:
@@ -176,11 +178,11 @@ class LegPart : NeoObject {
 ```
 
 Selectors may also be compatible inline closures. Prefer a named function when
-the identity rule is reused or deserves an explicit failure message. Never use
-a selector merely to wrap `Reference<T>(id: "...")`; that recreates the
-row-ID coupling selectors were introduced to remove. For new track rows, omit
-`@id` and let the successful push assign it. Preserve IDs already present on
-pulled rows.
+the identity rule is reused or deserves an explicit failure message. An exact
+`Reference<T>(id: "...")` recreates the row-ID coupling selectors were
+introduced to remove; use `withProvenance: true` only for a deliberately
+authored slot identity. For new track rows, omit `@id` and let the successful
+push assign it. Preserve IDs already present on pulled rows.
 
 A selector argument such as `this.SelectPants` is evaluated in the lexical
 scope of the class that declares the clip. Here `this` is the `LegPart`, not

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

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

package/skills/neocompose-cli/references/declarations-and-construction.md

@@ -47,8 +47,17 @@ abstract class Item<TContext extends SomeClass> : INamed {
 ```
 
 Use ordinary `public`, `protected`, `private`, `static`, `virtual`, `abstract`,
-and `override` semantics. Interfaces are non-generic. Do not put `@id` on
-inferred list/dictionary type entries or on derived structural descriptors.
+`sealed`, and `override` semantics. A sealed class is an instantiable leaf:
+it may extend another class but cannot be extended, cannot also be abstract,
+and can only be sealed while it has no subclasses. Interfaces are non-generic.
+Do not put `@id` on inferred list/dictionary type entries or on derived
+structural descriptors.
+
+```neo
+sealed class DirtTile : PlaceableTile {
+  public bool IsWet = false;
+}
+```
 
 A bodyless function must be `abstract`, `native`, or an interface contract.
 `async` alone does not make it valid.

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

@@ -83,6 +83,7 @@ supports:
 Reference(Assets.Capitol)
 Reference(root.Assets.Cosmetics.Pants)
 Reference<Outpost>(id: "capitol-value-id")
+Reference<NeoSpriteObject>(id: "authored-child-id", withProvenance: true)
 Reference<PantsAsset>(key: "pants.long")
 Reference<PantsAsset>(key: "pants.long", index: Slug)
 Reference<Dialogue>(id: "capitol-dialogue-id")
@@ -95,14 +96,20 @@ Reference<Dialogue>(id: "capitol-dialogue-id")
 - Use the generic `id:` form when the ID is the only target information. A
   `Reference` call whose argument is neither `id:` nor `key:` is rejected by
   name rather than read as an ID.
+- Inside executable NeoScript, add `withProvenance: true` when the ID names an
+  authored row and the reference must select its nearest `sourceValueId` clone
+  in the lexical receiver's ownership graph. The parameter defaults to `false`;
+  absent or explicit `false` keeps exact-ID behavior. This option is not a
+  persisted member-default form.
 - Both forms are legal in a member's declaration default, not only inside a
   value graph. A key written there resolves after every pass has run, so it may
   name a row the same push creates.
 - Keep genuine structural references ID-based when their collection has no
   stable symbol, path, or key surface. Animation track and frame-override
   targets are selectors, not structural references: encode a stable
-  project-owned identity such as `Name` or slug in the selector instead of
-  wrapping a row ID in `Reference<T>(id: "...")`.
+  project-owned identity such as `Name` or slug. The exception is an authored
+  child slot whose placement clones retain `sourceValueId`: select that slot
+  with `Reference<T>(id: "...", withProvenance: true)`.
 
 Declaration and file order do not affect resolution within one push. Cyclic
 identity references are legal because they resolve IDs rather than evaluate a