@neocompose/cli 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [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
               };
@@ -21834,7 +21860,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 +21906,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 +21920,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;
@@ -26596,7 +26630,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(
@@ -38455,7 +38493,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;
@@ -51301,9 +51341,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");
       }
     }
@@ -54332,6 +54377,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 +59966,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 +62184,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}`
@@ -104470,7 +104530,7 @@ var init_registry2 = __esm({
     PROJECT_SCHEMA_CONTRACT = Object.freeze({
       formatVersion: 3,
       contractVersion: "3.10",
-      cliVersion: "0.28.0",
+      cliVersion: "0.29.0",
       projectFileUploadBatchSize: 32,
       documentRecords: {
         member: {
@@ -111036,7 +111096,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.29.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.29.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.29.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.29.0 -->
 ```
 
 The quoted version above is checked too, so this instruction cannot go stale

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