@neocompose/cli 0.55.0 → 0.56.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.56.0] - 2026-09-23
+
+- `@storage(allowed: .Writable)` declares a member that is always writable at runtime and persists wherever its owner persists: Save under a Save parent, Session otherwise. NeoScript can write it through any receiver, including one read from Assets, and animation clips can target it. `neo pull` writes it back in the same form. Earlier CLIs fail on a project that uses it, so upgrade before pulling.
+- `@storage(allowed: .Writable)` on a class requires every placement of the class to resolve to Save or Session.
+- An override below a `.Writable` member may narrow it to `.Save` or `.Session`. Declaring `.Immutable` or `.Inherit` on it fails at the member's position and names the `.Writable` ancestor. `.Writable` on a static member also fails at its position. A `readonly` member under or declaring `.Writable` fails with the existing "Read-only field … requires resolved @storage(allowed: .Immutable)" error.
+
 ## [0.55.0] - 2026-09-23
 
 - `@settings` before a `List` element or `Dictionary` value type configures the collection's entries, such as `List<@settings(format: .Plain) string>` or `Dictionary<string, @settings(min: 0) int>`. `neo pull` writes entry settings in this form. Switching entries between Localized and Plain converts every entry's text exactly as the same change on a string member does. Annotations on a Dictionary key, another generic's type argument, or an override's element type are reported at their position. Run `neo pull` before your first push so entry settings set in the web app appear in source.

package/dist/neo.mjs

@@ -18769,13 +18769,15 @@ var init_project_schema_contract_generated = __esm({
           "Inherit",
           "Immutable",
           "Save",
-          "Session"
+          "Session",
+          "Writable"
         ],
         "NeoAllowedStorage": [
           "Any",
           "Immutable",
           "Save",
-          "Session"
+          "Session",
+          "Writable"
         ],
         "NeoListKind": [
           "Ordered",
@@ -32457,10 +32459,22 @@ function resolvedAllowedStorage(classId, environment) {
   }
   return null;
 }
-function staticDefaultWritability(classId, environment) {
-  const allowed = resolvedAllowedStorage(classId, environment);
+function constraintDefaultWritability(allowed) {
   return allowed === "immutable" || allowed === "save" || allowed === "session" ? allowed : "session";
 }
+function declaredStorageWritability(storage, staticOwnerClassId, environment) {
+  if (storage === "immutable" || storage === "save" || storage === "session") {
+    return storage;
+  }
+  if (storage === "writable") return "runtime";
+  if (!staticOwnerClassId) return void 0;
+  return staticDefaultWritability(staticOwnerClassId, environment);
+}
+function staticDefaultWritability(classId, environment) {
+  return constraintDefaultWritability(
+    resolvedAllowedStorage(classId, environment)
+  );
+}
 function createRootType(ids, environment) {
   const definitions = [
     ["Assets", ids.assets, false],
@@ -32522,7 +32536,7 @@ function effectiveMemberWritability(members, classes, roots) {
     seen.add(memberId);
     const member = memberById2.get(memberId);
     if (!member) return null;
-    if (member.storage === "immutable" || member.storage === "save" || member.storage === "session") {
+    if (member.storage === "immutable" || member.storage === "save" || member.storage === "session" || member.storage === "writable") {
       return member.storage;
     }
     return typeof member.overrideOf === "string" ? declaredStorage(member.overrideOf, seen) : null;
@@ -32545,8 +32559,8 @@ function effectiveMemberWritability(members, classes, roots) {
       seen.add(currentId);
       const current = classById.get(currentId);
       if (!current) break;
-      if (current.allowedStorage === "immutable" || current.allowedStorage === "save" || current.allowedStorage === "session") {
-        return current.allowedStorage;
+      if (typeof current.allowedStorage === "string") {
+        return constraintDefaultWritability(current.allowedStorage);
       }
       currentId = typeof current.extendsClassId === "string" ? current.extendsClassId : null;
     }
@@ -32581,6 +32595,7 @@ function effectiveMemberWritability(members, classes, roots) {
   }
   const effective = /* @__PURE__ */ new Map();
   const anchored = /* @__PURE__ */ new Set();
+  const writable = /* @__PURE__ */ new Set();
   const rootStorage = /* @__PURE__ */ new Map();
   if (typeof roots.assets === "string") {
     rootStorage.set(roots.assets, "immutable");
@@ -32590,16 +32605,19 @@ function effectiveMemberWritability(members, classes, roots) {
     rootStorage.set(roots.session, "session");
   }
   for (const [memberId, member] of memberById2) {
-    const root = rootStorage.get(memberId);
-    const declared = declaredStorage(memberId);
-    let storage = root ?? declared;
-    if (storage === void 0 || storage === null) {
+    const declared = rootStorage.get(memberId) ?? declaredStorage(memberId);
+    if (declared === "writable") {
+      writable.add(memberId);
+      continue;
+    }
+    let storage = declared;
+    if (storage === null) {
       const owner = optionalRecord(member.owner);
       if (member.modifier === "static" && owner?.kind === "classMember" && typeof owner.classId === "string") {
         storage = staticDefault(owner.classId);
       }
     }
-    if (storage === void 0 || storage === null) continue;
+    if (storage === null) continue;
     effective.set(memberId, /* @__PURE__ */ new Set([storage]));
     anchored.add(memberId);
   }
@@ -32609,8 +32627,11 @@ function effectiveMemberWritability(members, classes, roots) {
     for (const memberId of memberById2.keys()) {
       if (anchored.has(memberId)) continue;
       const next = new Set(effective.get(memberId) ?? []);
+      const isWritable = writable.has(memberId);
       for (const parentId of parents.get(memberId) ?? []) {
-        for (const storage of effective.get(parentId) ?? []) next.add(storage);
+        for (const storage of effective.get(parentId) ?? []) {
+          next.add(isWritable && storage === "immutable" ? "session" : storage);
+        }
       }
       const current = effective.get(memberId);
       if (current?.size === next.size || next.size === 0) continue;
@@ -32741,7 +32762,16 @@ function memberSymbol(member, schemaKey, environment, field) {
   }
   const writable = isReadOnly ? false : kind === "computed" ? computedHasSetter(member, field) : true;
   const storage = typeof member.storage === "string" ? member.storage : void 0;
-  const writability = isReadOnly ? "readOnly" : kind === "computed" ? writable ? "setter" : "readOnly" : !writable ? "readOnly" : storage === "immutable" || storage === "save" || storage === "session" ? storage : isStatic && ownerClassId ? staticDefaultWritability(ownerClassId, environment) : void 0;
+  let writability;
+  if (!writable) writability = "readOnly";
+  else if (kind === "computed") writability = "setter";
+  else {
+    writability = declaredStorageWritability(
+      storage,
+      isStatic ? ownerClassId : void 0,
+      environment
+    );
+  }
   const lookupCollectionMemberId = kind === "lookup" ? string2(member.collectionMemberId, `${field}.collectionMemberId`) : null;
   const lookupCollectionWritability = lookupCollectionMemberId === null ? void 0 : environment.effectiveWritabilityByMemberId.get(
     lookupCollectionMemberId
@@ -40103,7 +40133,13 @@ var init_codecs = __esm({
     };
     MEMBER_MODIFIERS = ["virtual", "sealed", "abstract", "static"];
     MEMBER_ACCESS = ["public", "protected", "private"];
-    MEMBER_STORAGE = ["inherit", "immutable", "save", "session"];
+    MEMBER_STORAGE = [
+      "inherit",
+      "immutable",
+      "save",
+      "session",
+      "writable"
+    ];
     MEMBER_DISTRIBUTION = ["sparse", "packed"];
     STRING_FORMAT = ["localized", "plain"];
     MEMBER_SEARCH_BY = ["none", "memberKey"];
@@ -40823,7 +40859,7 @@ function schemaClassToDocument(schemaClass2) {
     uiVisibility: schemaClass2.hiddenInMemberSelector ? 1 : void 0,
     modifier: schemaClass2.declarationModifier === "abstract" ? 1 : schemaClass2.declarationModifier === "sealed" ? 2 : void 0,
     system: systemToDocument(schemaClass2.system),
-    allowedStorage: schemaClass2.allowedStorage === null ? void 0 : ["immutable", "save", "session"].indexOf(schemaClass2.allowedStorage) + 1,
+    allowedStorage: schemaClass2.allowedStorage === null ? void 0 : CLASS_ALLOWED_STORAGE.indexOf(schemaClass2.allowedStorage),
     allowedStorageKeys: schemaClass2.allowedStorageKeys,
     // An unconstrained param is stored with no `constraint` key. The manifest
     // spells that absence `null` for a uniform in-memory shape, so emitting
@@ -40846,7 +40882,7 @@ function schemaClassToDocument(schemaClass2) {
 function allowedStorageFromDocument(value, record6) {
   const storage = ordinalValue(
     value ?? 0,
-    ["any", "immutable", "save", "session"],
+    CLASS_ALLOWED_STORAGE,
     record6,
     "allowedStorage"
   );
@@ -40893,12 +40929,19 @@ function optionalDocsTextProperty(value, record6) {
   const docsText = optionalDocsText(value, record6, "docsText");
   return docsText === void 0 ? {} : { docsText };
 }
-var CLASS_SCHEMA_RECORD_ADAPTER;
+var CLASS_ALLOWED_STORAGE, CLASS_SCHEMA_RECORD_ADAPTER;
 var init_class = __esm({
   "src/project-manifest/record-adapters/class.ts"() {
     "use strict";
     init_contracts();
     init_codecs();
+    CLASS_ALLOWED_STORAGE = [
+      "any",
+      "immutable",
+      "save",
+      "session",
+      "writable"
+    ];
     CLASS_SCHEMA_RECORD_ADAPTER = {
       recordKind: "class",
       manifestCollection: "classes",
@@ -42999,7 +43042,7 @@ var init_schema_member = __esm({
       defaultValue: nullable(schemaDefaultValueSchema),
       overrideOf: nullableId2,
       system: nullable(schemaSystemMetadataSchema),
-      storage: nullable(picklist(["immutable", "save", "session"])),
+      storage: nullable(picklist(["immutable", "save", "session", "writable"])),
       distribution: nullable(picklist(["sparse", "packed"])),
       storageKey: nullableId2
     };
@@ -44665,7 +44708,7 @@ function booleanAt(value, path) {
 }
 function nullableStorage(value, path) {
   if (value === null) return;
-  stringIn(value, /* @__PURE__ */ new Set(["immutable", "save", "session"]), path);
+  stringIn(value, /* @__PURE__ */ new Set(["immutable", "save", "session", "writable"]), path);
 }
 function stringIn(value, allowed, path) {
   const result = stringAt(value, path);
@@ -45434,15 +45477,59 @@ var init_class_generics = __esm({
 
 // ../src/models/members/member-storage.ts
 function isMemberStorageKind(value) {
-  return value === 0 /* Inherit */ || value === 1 /* Immutable */ || value === 2 /* Save */ || value === 3 /* Session */;
+  return value === 0 /* Inherit */ || value === 1 /* Immutable */ || value === 2 /* Save */ || value === 3 /* Session */ || value === 4 /* Writable */;
 }
 function isEffectiveMemberStorage(value) {
+  return value === 1 /* Immutable */ || value === 2 /* Save */ || value === 3 /* Session */;
+}
+function isClassAllowedStorage(value) {
   if (!isMemberStorageKind(value)) return false;
   return value !== 0 /* Inherit */;
 }
+function childEffectiveStorage(declared, parent) {
+  switch (declared) {
+    case 0 /* Inherit */:
+      return parent;
+    case 4 /* Writable */:
+      return parent === 2 /* Save */ ? 2 /* Save */ : 3 /* Session */;
+    default:
+      return declared;
+  }
+}
+function constraintDefaultStorage(constraint) {
+  if (constraint === null) return 3 /* Session */;
+  if (constraint === 4 /* Writable */) {
+    return 3 /* Session */;
+  }
+  return constraint;
+}
+function createWritableAncestorLookup(memberById2) {
+  const memo = /* @__PURE__ */ new Map();
+  const lookup = (member) => {
+    const cached = memo.get(member.id);
+    if (cached !== void 0) return cached;
+    memo.set(member.id, null);
+    const baseId = member.extendsMemberId;
+    const base = baseId === void 0 ? void 0 : memberById2(baseId);
+    if (base === void 0) return null;
+    const result = base.storage === 4 /* Writable */ ? base : lookup(base);
+    memo.set(member.id, result);
+    return result;
+  };
+  return lookup;
+}
+var MemberStorageKind;
 var init_member_storage = __esm({
   "../src/models/members/member-storage.ts"() {
     "use strict";
+    MemberStorageKind = /* @__PURE__ */ ((MemberStorageKind3) => {
+      MemberStorageKind3[MemberStorageKind3["Inherit"] = 0] = "Inherit";
+      MemberStorageKind3[MemberStorageKind3["Immutable"] = 1] = "Immutable";
+      MemberStorageKind3[MemberStorageKind3["Save"] = 2] = "Save";
+      MemberStorageKind3[MemberStorageKind3["Session"] = 3] = "Session";
+      MemberStorageKind3[MemberStorageKind3["Writable"] = 4] = "Writable";
+      return MemberStorageKind3;
+    })(MemberStorageKind || {});
   }
 });
 
@@ -47419,7 +47506,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 || Array.isArray(v.implementsInterfaceIds) && v.implementsInterfaceIds.every(
     (interfaceId) => typeof interfaceId === "string" && interfaceId.length > 0
-  )) && (v.uiVisibility === void 0 || v.uiVisibility === 0 /* Visible */ || v.uiVisibility === 1 /* Hidden */) && (v.modifier === void 0 || v.modifier === 0 /* Open */ || v.modifier === 1 /* Abstract */ || v.modifier === 2 /* Sealed */) && (v.allowedStorage === void 0 || isEffectiveMemberStorage(v.allowedStorage)) && (v.allowedStorageKeys === void 0 || Array.isArray(v.allowedStorageKeys) && v.allowedStorageKeys.every((key) => typeof key === "string")) && (v.genericParams === void 0 || Array.isArray(v.genericParams) && v.genericParams.every(isGenericParamDeclaration)) && (v.extendsGenericBindings === void 0 || isGenericBindingsRecord(v.extendsGenericBindings)) && (v.constructorIds === void 0 || Array.isArray(v.constructorIds) && v.constructorIds.every(
+  )) && (v.uiVisibility === void 0 || v.uiVisibility === 0 /* Visible */ || v.uiVisibility === 1 /* Hidden */) && (v.modifier === void 0 || v.modifier === 0 /* Open */ || v.modifier === 1 /* Abstract */ || v.modifier === 2 /* Sealed */) && (v.allowedStorage === void 0 || isClassAllowedStorage(v.allowedStorage)) && (v.allowedStorageKeys === void 0 || Array.isArray(v.allowedStorageKeys) && v.allowedStorageKeys.every((key) => typeof key === "string")) && (v.genericParams === void 0 || Array.isArray(v.genericParams) && v.genericParams.every(isGenericParamDeclaration)) && (v.extendsGenericBindings === void 0 || isGenericBindingsRecord(v.extendsGenericBindings)) && (v.constructorIds === void 0 || 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 || typeof v.requiredConstructorId === "string" && v.requiredConstructorId.length > 0 && (v.constructorIds ?? []).length === 0) && (v.targetMemberId === void 0 || typeof v.targetMemberId === "string" && v.targetMemberId.length > 0) && (v.system === void 0 || isSystemMetadata(v.system));
 }
@@ -53020,7 +53107,7 @@ function assertOwnedSchemaIsImmutable(args) {
   const bindingKey = `${args.memberId}\0${genericEnvironmentKey(args.genericEnv)}`;
   if (args.visitedBindings.has(bindingKey)) return;
   args.visitedBindings.add(bindingKey);
-  if (resolved.storage === 2 /* Save */ || resolved.storage === 3 /* Session */) {
+  if (resolved.storage === 2 /* Save */ || resolved.storage === 3 /* Session */ || resolved.storage === 4 /* Writable */) {
     throw new Error(
       `Read-only member "${args.label}" has a non-Immutable owned default child "${resolved.name}"; ${args.ownerContext}.`
     );
@@ -56911,6 +56998,9 @@ var init_effective_storage = __esm({
       schemaIndex;
       parentIdsByMemberId = /* @__PURE__ */ new Map();
       effectiveByMemberId = /* @__PURE__ */ new Map();
+      writableAncestor = createWritableAncestorLookup(
+        (id2) => this.schemaIndex.member(id2)
+      );
       resolving = /* @__PURE__ */ new Set();
       /** Declared storage of `memberId`, resolved through the extends chain. */
       declaredStorage(memberId) {
@@ -56919,6 +57009,15 @@ var init_effective_storage = __esm({
           this.schemaIndex.membersById
         );
       }
+      /**
+       * Nearest member in `memberId`'s `extendsMemberId` chain, excluding itself,
+       * whose own record declares `Writable` (P93 §1.4), or null.
+       */
+      writableAncestorId(memberId) {
+        const member = this.schemaIndex.member(memberId);
+        if (member === void 0) return null;
+        return this.writableAncestor(member)?.id ?? null;
+      }
       /** Placement-parent member ids of `memberId` (empty for roots). */
       parentMemberIds(memberId) {
         if (this.ctx.rootStorage.has(memberId)) return [];
@@ -56942,21 +57041,21 @@ var init_effective_storage = __esm({
             result.add(rootStorage);
           } else {
             const declared = this.declaredStorage(memberId);
-            const member = this.schemaIndex.member(memberId);
-            if (isStaticMember(member) === true) {
-              if (declared !== 0 /* Inherit */) {
-                result.add(declared);
-              } else {
-                const declaringClassId = this.schemaIndex.firstSchemaPlacement(memberId)?.ownerClass.id;
-                const inherited = declaringClassId === void 0 ? null : resolveAllowedStorage(declaringClassId, this.ctx.classes);
-                result.add(inherited ?? 3 /* Session */);
-              }
-            } else if (declared !== 0 /* Inherit */) {
+            if (isEffectiveMemberStorage(declared)) {
               result.add(declared);
+            } else if (isStaticMember(this.schemaIndex.member(memberId))) {
+              const declaringClassId = this.schemaIndex.firstSchemaPlacement(memberId)?.ownerClass.id;
+              const constraint = declaringClassId === void 0 ? null : resolveAllowedStorage(declaringClassId, this.ctx.classes);
+              result.add(
+                childEffectiveStorage(
+                  declared,
+                  constraintDefaultStorage(constraint)
+                )
+              );
             } else {
               for (const parentId of this.parentMemberIds(memberId)) {
                 for (const storage of this.effectiveStorages(parentId)) {
-                  result.add(storage);
+                  result.add(childEffectiveStorage(declared, storage));
                 }
               }
             }
@@ -56971,26 +57070,44 @@ var init_effective_storage = __esm({
        * Effective storage for one concrete placement chain, ordered root-first
        * (the project root at index 0, the target member last). Used when the
        * caller knows the exact path (NeoScript member walks, value trees).
+       * Anchors at the root, the nearest concrete declaration, or a single-storage
+       * static head, then folds the members below through `childEffectiveStorage`.
        */
       effectiveStorageForPath(memberIdsRootToLeaf) {
-        for (let i = memberIdsRootToLeaf.length - 1; i >= 0; i--) {
-          const memberId = memberIdsRootToLeaf[i];
-          const rootStorage = this.ctx.rootStorage.get(memberId);
-          if (rootStorage !== void 0 && i === 0) return rootStorage;
+        let anchorIndex = memberIdsRootToLeaf.length - 1;
+        let storage;
+        for (; anchorIndex >= 0; anchorIndex--) {
+          const memberId = memberIdsRootToLeaf[anchorIndex];
+          if (anchorIndex === 0) storage = this.ctx.rootStorage.get(memberId);
+          if (storage !== void 0) break;
           const declared = this.declaredStorage(memberId);
-          if (declared !== 0 /* Inherit */) return declared;
+          if (isEffectiveMemberStorage(declared)) {
+            storage = declared;
+            break;
+          }
+        }
+        if (storage === void 0) {
+          anchorIndex = 0;
+          storage = this.staticRootStorage(memberIdsRootToLeaf[0]);
+        }
+        for (let i = anchorIndex + 1; i < memberIdsRootToLeaf.length; i++) {
+          storage = childEffectiveStorage(
+            this.declaredStorage(memberIdsRootToLeaf[i]),
+            storage
+          );
         }
-        const rootId = memberIdsRootToLeaf[0];
-        const anchored = rootId === void 0 ? void 0 : this.ctx.rootStorage.get(rootId);
-        if (anchored !== void 0) return anchored;
+        return storage;
+      }
+      /** A static chain head's storage when it resolves to exactly one. */
+      staticRootStorage(rootId) {
         if (rootId !== void 0 && isStaticMember(this.schemaIndex.member(rootId))) {
           const staticStorages = this.effectiveStorages(rootId);
           if (staticStorages.size === 1) {
-            return staticStorages.values().next().value;
+            for (const storage of staticStorages) return storage;
           }
         }
         throw new Error(
-          `Storage path did not resolve: no member in the chain declares a storage class and the chain head "${rootId ?? "(empty)"}" is not a stamped project root.`
+          `Storage path did not resolve: no member in the chain declares an Immutable, Save, or Session storage class and the chain head "${rootId ?? "(empty)"}" is not a stamped project root.`
         );
       }
       /** Class's merged (inheritance-resolved) schema. */
@@ -64211,6 +64328,14 @@ function buildRootStorageMap(project) {
   }
   return map;
 }
+function writtenRootStorage(project, memberIds) {
+  const map = /* @__PURE__ */ new Map();
+  for (const root of PROJECT_ROOTS) {
+    const memberId = project[root.projectField];
+    if (memberIds.has(memberId)) map.set(memberId, root.storage);
+  }
+  return map;
+}
 function isProjectRootMember(project, memberId) {
   return PROJECT_ROOTS.some((root) => project[root.projectField] === memberId);
 }
@@ -64802,7 +64927,9 @@ function symbolWritability(memberId, context, staticOwnerClassId) {
   if (storage === 0 /* Inherit */ && staticOwnerClassId === null) {
     return {};
   }
-  const effectiveStorage = storage === 0 /* Inherit */ ? resolveAllowedStorage(staticOwnerClassId, context.vm.classes) ?? 3 /* Session */ : storage;
+  const effectiveStorage = storage === 0 /* Inherit */ ? constraintDefaultStorage(
+    resolveAllowedStorage(staticOwnerClassId, context.vm.classes)
+  ) : storage;
   switch (effectiveStorage) {
     case 1 /* Immutable */:
       return { writability: "immutable" };
@@ -64810,6 +64937,8 @@ function symbolWritability(memberId, context, staticOwnerClassId) {
       return { writability: "save" };
     case 3 /* Session */:
       return { writability: "session" };
+    case 4 /* Writable */:
+      return { writability: "runtime" };
   }
 }
 function uniqueEffectiveWritability(memberId, context) {
@@ -101375,10 +101504,6 @@ var init_unity_static_members = __esm({
 });
 
 // ../src/models/animation/animation-clips.ts
-function isWorldAnimationStructuralMember(memberId, members) {
-  const membersById = new Map(members.map((member) => [member.id, member]));
-  return isWorldAnimationStructuralMemberFromIndex(memberId, membersById);
-}
 function isWorldAnimationStructuralMemberFromIndex(memberId, membersById) {
   const visited = /* @__PURE__ */ new Set();
   let currentId = memberId;
@@ -101389,6 +101514,35 @@ function isWorldAnimationStructuralMemberFromIndex(memberId, membersById) {
   }
   return false;
 }
+function worldOverridePathIsStructurallyEligible(memberIdsRootToLeaf, membersById) {
+  for (const memberId of memberIdsRootToLeaf) {
+    if (isWorldAnimationStructuralMemberFromIndex(memberId, membersById)) {
+      return false;
+    }
+    const member = membersById.get(memberId);
+    if (member === void 0) return false;
+    const resolved = resolveMemberFromIndex(member, membersById);
+    if (isStaticMember(resolved) || isReadOnlyMember(resolved)) return false;
+    if (resolved.kind === 13 /* Function */ || resolved.kind === 23 /* NSFunction */ || resolved.kind === 10 /* NSProperty */ || resolved.kind === 6 /* List */ || resolved.kind === 5 /* Dictionary */) {
+      return false;
+    }
+  }
+  return true;
+}
+function animationTrackStorage(memberIdsRootToLeaf, membersById, childrenPrefix = []) {
+  if (!worldOverridePathIsStructurallyEligible(memberIdsRootToLeaf, membersById)) {
+    return null;
+  }
+  const path = [...childrenPrefix, ...memberIdsRootToLeaf];
+  for (let index = path.length - 1; index >= 0; index -= 1) {
+    const memberId = path[index];
+    if (memberId === void 0) continue;
+    const storage = declaredMemberStorageFromIndex(memberId, membersById);
+    if (storage === 0 /* Inherit */) continue;
+    return storage === 1 /* Immutable */ ? null : storage;
+  }
+  return null;
+}
 function assertAnimationClipDocumentValid(document, scope) {
   const context = new AnimationValidationContext(document);
   context.validateSegments(scope);
@@ -101416,7 +101570,6 @@ var init_animation_clips = __esm({
     init_member_storage();
     init_neoscript_types();
     init_neoscript_guards();
-    init_project_root_members();
     init_members();
     WORLD_ANIMATION_STRUCTURAL_MEMBER_ROOT_IDS = /* @__PURE__ */ new Set([
       WORLD_GRID_CHILDREN_MEMBER_ID,
@@ -101442,17 +101595,11 @@ var init_animation_clips = __esm({
           document.members.map((value) => [value.id, value])
         );
         this.valueById = new Map(document.values.map((value) => [value.id, value]));
-        this.storage = new EffectiveStorageResolver({
-          classes: document.classes,
-          members: document.members,
-          rootStorage: buildRootStorageMap(document.project)
-        });
       }
       document;
       classById;
       memberById;
       valueById;
-      storage;
       classHasWorldKind(classId, worldKind) {
         const visited = /* @__PURE__ */ new Set();
         let current = this.classById.get(classId);
@@ -101528,6 +101675,7 @@ var init_animation_clips = __esm({
               definitionNode: targetDefinition,
               memberPath: [],
               storagePath: [],
+              childrenPrefix: [],
               visited: /* @__PURE__ */ new Set()
             });
           }
@@ -101612,7 +101760,8 @@ var init_animation_clips = __esm({
               overrideNode: overrides,
               definitionNode: child,
               memberPath: [`child:${childId}`],
-              storagePath: [...args.childStoragePath],
+              storagePath: [],
+              childrenPrefix: args.childStoragePath,
               visited: /* @__PURE__ */ new Set()
             });
           }
@@ -101955,12 +102104,13 @@ var init_animation_clips = __esm({
             `${args.label} targets "${boundChildName}.${targetEntry.schemaKey}" of kind ${MemberKind[targetMember.kind]}, but its segment plays ${MemberKind[valueBindingMember.kind]} values.`
           );
         }
-        if (!this.overrideLeafEligible(targetMember, [
-          ...args.childStoragePath,
-          targetMember.id
-        ])) {
+        if (!this.overrideLeafEligible(
+          targetMember,
+          [targetMember.id],
+          args.childStoragePath
+        )) {
           throw new Error(
-            `${args.label} targets "${boundChildName}.${targetEntry.schemaKey}", which is not a writable Save/Session override leaf.`
+            `${args.label} targets "${boundChildName}.${targetEntry.schemaKey}", which is not a writable Save, Session, or Writable override leaf.`
           );
         }
       }
@@ -102130,7 +102280,8 @@ var init_animation_clips = __esm({
                 partial: overrideChild.value,
                 path,
                 schemaKey,
-                storagePath: args.storagePath
+                storagePath: args.storagePath,
+                childrenPrefix: args.childrenPrefix
               });
               continue;
             }
@@ -102161,9 +102312,13 @@ var init_animation_clips = __esm({
               });
               continue;
             }
-            if (!this.overrideLeafEligible(member, [...args.storagePath, member.id])) {
+            if (!this.overrideLeafEligible(
+              member,
+              [...args.storagePath, member.id],
+              args.childrenPrefix
+            )) {
               throw new Error(
-                `Animation clip "${args.clipName}" frame ${args.frameIndex} member "${path.join(".")}" is not a writable Save/Session override leaf.`
+                `Animation clip "${args.clipName}" frame ${args.frameIndex} member "${path.join(".")}" is not a writable Save, Session, or Writable override leaf.`
               );
             }
           }
@@ -102198,12 +102353,13 @@ var init_animation_clips = __esm({
           );
         }
         const kindLabel = MemberKind[kind];
-        if (!this.overrideLeafEligible(args.member, [
-          ...args.storagePath,
-          args.member.id
-        ])) {
+        if (!this.overrideLeafEligible(
+          args.member,
+          [...args.storagePath, args.member.id],
+          args.childrenPrefix
+        )) {
           throw new Error(
-            `${prefix} ${kindLabel} member "${memberPath3}" cannot take a "${STRUCTURED_LEAF_PARTIAL_KEY}" field override; member "${args.member.name}" is not a writable Save/Session override leaf.`
+            `${prefix} ${kindLabel} member "${memberPath3}" cannot take a "${STRUCTURED_LEAF_PARTIAL_KEY}" field override; member "${args.member.name}" is not a writable Save, Session, or Writable override leaf.`
           );
         }
         const violation = structuredLeafPartialViolation(
@@ -102244,24 +102400,9 @@ var init_animation_clips = __esm({
           throw new Error(`${descent}; its value is not a ${kindLabel} record.`);
         }
       }
-      overrideLeafEligible(member, storagePath) {
-        if (isReadOnlyMember(member) === true || isStaticMember(member))
-          return false;
-        if (isWorldAnimationStructuralMember(member.id, this.document.members)) {
-          return false;
-        }
-        if (member.kind === 13 /* Function */ || member.kind === 23 /* NSFunction */ || member.kind === 10 /* NSProperty */ || member.kind === 7 /* Class */ || member.kind === 6 /* List */ || member.kind === 5 /* Dictionary */) {
-          return false;
-        }
-        try {
-          const storage = this.storage.effectiveStorageForPath(storagePath);
-          return storage === 2 /* Save */ || storage === 3 /* Session */;
-        } catch {
-          const storages = this.storage.effectiveStorages(member.id);
-          return storages.size > 0 && [...storages].every(
-            (storage) => storage === 2 /* Save */ || storage === 3 /* Session */
-          );
-        }
+      overrideLeafEligible(member, storagePath, childrenPrefix) {
+        if (member.kind === 7 /* Class */) return false;
+        return animationTrackStorage(storagePath, this.memberById, childrenPrefix) !== null;
       }
       authoredChildren(targetClassId, definitionNode) {
         const childEntry = mergeStoredInstanceSchema(
@@ -102285,9 +102426,8 @@ var init_animation_clips = __esm({
               (value) => typeof value === "string"
             ) : []
           ),
-          // Child values inherit storage from their concrete placement under the
-          // owner's resolved Children member. This mirrors the authoring panel's
-          // storage path instead of treating a shared child-class leaf as a root.
+          // P93 §5: a child track's declaration walk continues through the
+          // owner's resolved Children member, as the authoring pane's does.
           storagePath: [childEntry.memberId]
         };
       }
@@ -103250,7 +103390,7 @@ function readClass(value) {
     CLASS_VISIBILITY_KINDS,
     `${label} uiVisibility`
   );
-  if (value.allowedStorage != null && !isEffectiveMemberStorage(value.allowedStorage)) {
+  if (value.allowedStorage != null && !isClassAllowedStorage(value.allowedStorage)) {
     throw new Error(`${label} allowedStorage is invalid.`);
   }
   if (value.genericParams !== void 0 && value.genericParams !== null) {
@@ -103632,6 +103772,14 @@ function assertProjectInterfaceDocumentValid(view, options = {}) {
   const classes = view.classes.map(readClass);
   const interfaces = view.interfaces.map(readInterface);
   const membersById = new Map(members.map((member) => [member.id, member]));
+  for (const [rootId, stamped] of view.rootStorage ?? []) {
+    const root = membersById.get(rootId);
+    if (root === void 0 || root.storage === stamped) continue;
+    const declared = root.storage === void 0 ? "none" : MemberStorageKind[root.storage];
+    throw new Error(
+      `Project root member "${root.name}" (${rootId}) must declare ${MemberStorageKind[stamped]} storage but declares ${declared}.`
+    );
+  }
   const classesById = new Map(
     classes.map((schemaClass2) => [schemaClass2.id, schemaClass2])
   );
@@ -103751,6 +103899,11 @@ function assertProjectInterfaceDocumentValid(view, options = {}) {
         `Static member "${member.name}" (${member.id}) must be a plain non-override member.`
       );
     }
+    if (member.storage === 4 /* Writable */) {
+      throw new Error(
+        `Static member "${member.name}" (${member.id}) cannot declare Writable storage; a static member has no placement parent to resolve it against.`
+      );
+    }
     if (member.kind === 21) {
       throw new Error(
         `Generic placeholder member "${member.name}" (${member.id}) cannot be static.`
@@ -104055,6 +104208,19 @@ function assertProjectInterfaceDocumentValid(view, options = {}) {
     if (member.mutability === void 0) delete resolved.mutability;
     return resolved;
   };
+  const writableAncestor2 = createWritableAncestorLookup(
+    (id2) => membersById.get(id2)
+  );
+  for (const member of members) {
+    if (member.storage !== 1 /* Immutable */ && member.storage !== 0 /* Inherit */) {
+      continue;
+    }
+    const ancestor = writableAncestor2(member);
+    if (ancestor === null) continue;
+    throw new Error(
+      `Member "${member.name}" (${member.id}) declares ${MemberStorageKind[member.storage]} storage but overrides Writable member "${ancestor.name}" (${ancestor.id}); an override of a Writable member may declare Writable, Save, or Session, or omit storage.`
+    );
+  }
   const rootAndEntryMemberIds = /* @__PURE__ */ new Set();
   for (const owner of members) {
     if (typeof owner.entryMemberId === "string") {
@@ -104196,7 +104362,7 @@ function assertProjectInterfaceDocumentValid(view, options = {}) {
         }
       }
       if (rawOwned.id === member.id && isAbstractMember(member)) return;
-      if (owned.storage === 2 /* Save */ || owned.storage === 3 /* Session */) {
+      if (owned.storage === 2 /* Save */ || owned.storage === 3 /* Session */ || owned.storage === 4 /* Writable */) {
         throw new Error(
           `Read-only member "${member.name}" has a non-Immutable owned default child "${owned.name}"; ${ownerLabel}.`
         );
@@ -104727,7 +104893,7 @@ function assertProjectInterfaceDocumentValid(view, options = {}) {
       return resolved.setterCode === void 0 ? "NSProperty has no setter implementation." : null;
     }
     const storage = resolved.storage;
-    if (storage === 2 /* Save */ || storage === 3 /* Session */) {
+    if (storage === 2 /* Save */ || storage === 3 /* Session */ || storage === 4 /* Writable */) {
       return null;
     }
     if (storage === 1 /* Immutable */) {
@@ -106765,6 +106931,14 @@ function assertStagedProjectInterfaceValid(projected, changes) {
       variants: projected.variants ?? [],
       variantFolders: projected.variantFolders ?? [],
       interfaces: projected.interfaces,
+      rootStorage: writtenRootStorage(
+        projected.project,
+        new Set(
+          changes.flatMap(
+            (change) => change.recordKind === "member" ? [change.recordId] : []
+          )
+        )
+      ),
       values: projected.values
     },
     {
@@ -107360,6 +107534,7 @@ var init_project_version_whole_graph_validation = __esm({
     init_core();
     init_animation_clips();
     init_projectInterfaceValidation();
+    init_project_root_members();
     init_project_schema_identifier_validation();
     init_packed_value_write_fold();
     init_project_version_schema_commit();
@@ -109487,6 +109662,7 @@ function memberCommon(context, ownerClass, declaration, id2, owner, base) {
   const storage = annotation(declaration.annotations, "storage");
   const distribution = annotation(declaration.annotations, "distribution");
   const inheritedId = declaration.modifiers.includes("override") || declaration.modifiers.includes("sealed") ? inheritedMemberId(context, ownerClass, declaration.name) : null;
+  assertWritableStorageRules(context, ownerClass, declaration, inheritedId);
   return {
     id: id2,
     source: sourceIdentity2(declaration, "member", declaration.name),
@@ -111523,7 +111699,74 @@ function numberArgument(value, name) {
 }
 function storageValue(value, name) {
   const enumValue2 = contextualEnumArgument(value, name)?.toLowerCase();
-  return enumValue2 === "immutable" || enumValue2 === "save" || enumValue2 === "session" ? enumValue2 : null;
+  return enumValue2 === "immutable" || enumValue2 === "save" || enumValue2 === "session" || enumValue2 === "writable" ? enumValue2 : null;
+}
+function assertWritableStorageRules(context, ownerClass, declaration, inheritedId) {
+  const site = `${ownerClass.name}.${declaration.name}`;
+  const storage = annotation(declaration.annotations, "storage");
+  const declared = storage ? contextualEnumArgument(storage, "allowed")?.toLowerCase() : void 0;
+  if (declared === "writable" && declaration.modifiers.includes("static")) {
+    throw new Error(
+      `Static member ${site} cannot declare Writable storage: a static member has no parent to resolve it against. Declare Save or Session.`
+    );
+  }
+  if (inheritedId === null) return;
+  const ancestor = writableAncestor(context, inheritedId);
+  if (ancestor === null) return;
+  if (declared === "immutable") {
+    throw new Error(
+      `${site} cannot declare Immutable storage because it overrides ${ancestor}, which declares Writable. Declare Writable, Save, or Session, or omit @storage.`
+    );
+  }
+  if (declared === "inherit") {
+    throw new Error(
+      `${site} cannot declare Inherit storage because it overrides ${ancestor}, which declares Writable. Declare Writable, Save, or Session, or omit @storage.`
+    );
+  }
+}
+function writableAncestor(context, memberId) {
+  const memo = context.writableAncestors;
+  const chain = /* @__PURE__ */ new Set();
+  let currentId = memberId;
+  let found = null;
+  while (currentId !== null) {
+    const known = memo.get(currentId);
+    if (known !== void 0) {
+      found = known;
+      break;
+    }
+    if (chain.has(currentId)) break;
+    chain.add(currentId);
+    const step = storageChainStep(context, currentId);
+    if (step === null) break;
+    if (step.storage === "writable") {
+      found = step.label;
+      break;
+    }
+    currentId = step.overrideOf;
+  }
+  for (const id2 of chain) memo.set(id2, found);
+  return found;
+}
+function storageChainStep(context, memberId) {
+  const sourcePlacement = context.sourceMembersById.get(memberId);
+  if (sourcePlacement !== void 0) {
+    const { ownerClass, member } = sourcePlacement;
+    const storage = annotation(member.annotations, "storage");
+    return {
+      label: `${ownerClass.name}.${member.name}`,
+      storage: storage ? storageValue(storage, "allowed") : null,
+      overrideOf: member.modifiers.includes("override") || member.modifiers.includes("sealed") ? inheritedMemberId(context, ownerClass, member.name) : null
+    };
+  }
+  const persisted = context.baseMembers.get(memberId);
+  if (persisted === void 0) return null;
+  const ownerName = persisted.owner.kind === "classMember" ? context.baseClasses.get(persisted.owner.classId)?.name : void 0;
+  return {
+    label: ownerName === void 0 ? persisted.name : `${ownerName}.${persisted.name}`,
+    storage: persisted.storage,
+    overrideOf: persisted.overrideOf
+  };
 }
 function referenceIdArgument(value, name) {
   const raw = argument(value, name);
@@ -112503,6 +112746,7 @@ function lowerProjectSchemaV4(base, analysis, options = {}) {
     enumOptionsByName,
     loweredMembers: /* @__PURE__ */ new Map(),
     entryTypesByEntryId: /* @__PURE__ */ new Map(),
+    writableAncestors: /* @__PURE__ */ new Map(),
     placements: /* @__PURE__ */ new Map(),
     staticValueIdsBySymbol: staticValueIdsBySymbol3,
     settleInitializerReferences: createSchemaInitializerReferenceSettlerV4({
@@ -139241,7 +139485,7 @@ var init_registry2 = __esm({
   "schema-contract/registry.mjs"() {
     "use strict";
     PROJECT_SCHEMA_CONTRACT = Object.freeze({
-      cliVersion: "0.55.0",
+      cliVersion: "0.56.0",
       projectFileUploadBatchSize: 32,
       documentRecords: {
         member: {
@@ -139583,8 +139827,8 @@ var init_registry2 = __esm({
       sdkDeclarations: {
         attributes: {
           enums: {
-            NeoStorage: ["Inherit", "Immutable", "Save", "Session"],
-            NeoAllowedStorage: ["Any", "Immutable", "Save", "Session"],
+            NeoStorage: ["Inherit", "Immutable", "Save", "Session", "Writable"],
+            NeoAllowedStorage: ["Any", "Immutable", "Save", "Session", "Writable"],
             NeoListKind: ["Ordered", "Unordered"],
             NeoDictionaryKeyKind: ["String", "Enum"],
             NeoClassVisibility: ["Visible", "Hidden"],
@@ -147062,7 +147306,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.55.0");
+    console.log("0.56.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.55.0",
+  "version": "0.56.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.55.0 -->
+<!-- reviewed-through-cli: 0.56.0 -->
 
 # Neo Compose CLI
 

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

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

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

@@ -103,6 +103,39 @@ Use context-aware typed annotations:
 Use numeric literals for numeric limits. Keep annotations separate instead of
 inventing a generic metadata bag.
 
+### Storage
+
+A member's `@storage(allowed: ...)` is `.Immutable`, `.Save`, `.Session`, or
+`.Writable`. Omit it to inherit the placement parent's storage. `.Writable` is
+always writable at runtime and resolves from where the value is placed: Save
+under a Save parent, Session under a Session or Immutable parent. Use it for a
+member that NeoScript or an animation clip writes and whose value should persist
+exactly when its owner persists. Animation clips can target `.Writable` members.
+
+```neo
+class AnimationSpriteObject(SpriteInfo sprite) : NeoSpriteObject {
+  @id("69905c25-8c05-4d18-90fd-069f1526a38a")
+  @storage(allowed: .Writable)
+  public override Vector3 Size = new(1, 1, 0);
+}
+
+abstract class BodyLayerSprite(CharacterCosmeticConfig config, SpriteInfo sprite, int nearOrder, int farOrder) : AnimationSpriteObject(sprite: sprite) {
+  @id("e81dcef4-9ea8-4bbc-a83b-565b7cf3feff")
+  @storage(allowed: .Session)
+  public override Vector3 Size = new(2, 2, 0);
+}
+```
+
+An override below a `.Writable` member, directly or through other overrides,
+may declare `.Writable`, `.Save`, or `.Session`, or omit `@storage`. It may not
+declare `.Immutable` or `.Inherit`, and it may not be `readonly`. Static
+members, `readonly` members, and project roots cannot declare `.Writable`.
+Lowering reports each violation at the member's position.
+
+On a class, `@storage(allowed: .Writable)` means every placement must resolve
+to Save or Session. A subclass may narrow it to `.Save` or `.Session`. An
+undeclared static member of such a class is Session.
+
 `@index(member: Field, kind: .Unique)` and
 `@column(member: Field, width: ..., visibility: ..., pin: ..., overflow: ...)`
 are repeatable List annotations. `member:` is a bare field name on the entry