@neocompose/cli 0.87.2 → 0.88.0

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

@@ -1,421 +0,0 @@
-# Values, identities, and references
-
-Use this reference for root/static values, nested identities, references,
-localization, and managed project files.
-
-## Contents
-
-- Root and static bindings
-- Identity rules
-- Same-push references
-- Defaults and localization
-- Managed files
-
-## Root and static bindings
-
-Edit only the initializer after `=` in the compiler-owned `Root.neo` envelope.
-The root member name, type, member ID, lock, and storage metadata are read-only.
-
-```neo
-Root root = new() {
-  @id("root-assets-member-id")
-  @storage(allowed: .Immutable)
-  Assets Assets = new() {
-    Outposts = [Assets.Capitol.Clone()],
-  };
-}
-```
-
-Do not place another `@id` immediately before the root initializer. The member
-ID owns the binding. Apply the same rule to static stored members:
-
-```neo
-@id("assets-class-id")
-class Assets {
-  @id("capitol-member-id")
-  static Outpost Capitol = new {
-    Name = "Capitol",
-  };
-
-  @id("home-getter-id")
-  static Outpost Home => Assets.Capitol;
-}
-```
-
-A computed static getter is an alias; it creates neither a binding nor a row.
-
-A static used in another initializer copies value kinds, including scalars and
-delegates. Class, list, set, and dictionary values have exactly one owner.
-Placing a value that something else already owns is refused: a static, a
-static's field, a collection entry, a local placed elsewhere, or a constructor
-parameter stored in an ordinary field. Status, push, and `neo test` report the
-placement at its authored position. Call `Clone()` to own a copy, or use
-`Reference`:
-
-```neo
-static Outpost Annex = Assets.Capitol.Clone();
-static Reference<Outpost> Seat = Reference(Assets.Capitol);
-```
-
-Statics created together may refer to each other regardless of declaration
-order; no preliminary push is needed.
-
-Enum-keyed dictionaries accept contextual or qualified option keys in defaults
-and stored values:
-
-```neo
-Dictionary<ToolType, float> Damage = { .Pickaxe: 10, ToolType.Axe: 2 };
-```
-
-Pull writes `.Option` for known keys. A quoted raw option ID is also accepted;
-a quoted option name such as `"Pickaxe"` is not an ID. Pull preserves orphaned
-keys as quoted IDs when their option has been deleted.
-
-## Identity rules
-
-Preserve every existing ID through rename, reorder, and file moves. Renaming a
-schema member while keeping its ID preserves its owned value graph. Update
-initializer keys to the new name and retain existing child IDs, including when
-editing those children in the same change. A copy
-must get a new ID. A stored nested class value may keep its UUID-v4 when moved
-to an empty, compatible class field on another existing parent. Remove its
-old owning declaration in the same push. Both fields must declare the same
-non-generic class and storage rules. The move must leave exactly one owning
-path to the same root or static binding through ordinary class fields.
-Both ownership paths must use inherited storage and automatic distribution;
-member overrides are not supported for moves. Moving
-projected values, constructor-owned slots, partitioned values, generic
-instances, or unordered-list entries is refused. Moves into newly constructed
-parents are also refused; omit the ID to create a new value there.
-
-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.
-
-A local initializer's existing row ID may precede its variable declaration:
-
-```neo
-@id("existing-quest-row-id")
-Quest HardAsStone = new Quest() { Name = "Hard as stone" };
-```
-
-This names the initializer row. It does not create a stored global. The inline
-`Quest HardAsStone = @id("...") new Quest();` spelling is also accepted, and
-formatting moves its ID above the declaration. Do not put an ID in both places.
-
-A local initializer such as `Delivery DeliveryRow = new()` retains `Delivery`
-when consumed by a base-class member. Aliases retain that same concrete type.
-
-Complete local member and collection initializers also work inside constructions
-that execute a constructor. Each local composes its owned subtree and preserves
-its concrete class:
-
-```neo
-AudioFolder SFX_FOLDER = new("Sound effects") {
-  Children = [UI_VOLUME, GAMEPLAY_VOLUME]
-};
-AudioSettings AUDIO_SETTINGS = new() { Main = SFX_FOLDER };
-```
-
-In constructor arguments and executable operands, a class local names its one
-stored instance instead of constructing a copy. Its owning placement keeps it,
-so a constructor that stores it needs a `Reference` field:
-
-```neo
-@id("86ac7c7d-8d3b-4642-9def-cdf32643bdc5")
-DeliveryQuest HARD_AS_STONE = new();
-// The core quest list owns HARD_AS_STONE.
-WorkflowStep UNLOCK = new QuestUnlockStep(HARD_AS_STONE);
-
-class QuestUnlockStep(DeliveryQuest quest) : WorkflowStep {
-  public Reference<DeliveryQuest> Quest = quest;
-}
-```
-
-The referenced local must have exactly one owning placement. A nested target
-needs its existing `@id`. A structurally owned list entry can also use an unused
-UUID-v4 in the same push. For a local nested inside an evaluated constructor,
-leave it idless on the first push; push assigns its actual identity before it can
-be referenced. Do not assign a fresh UUID to that nested construction. A direct static owning member can supply an idless local's pending identity.
-Aliases of that static local work too. A member default is a construction template,
-so its local does not identify a single stored instance. Unowned locals, ambiguous
-placements, and cycles are errors at source. Constructor argument type checking
-still applies. Canonical construction arguments may use `Reference<Type>(id: "…")`.
-
-Owned locals inside evaluated initializers need directly addressable fields, list
-entries, or literal dictionary keys; inline the construction when a computed key
-or other executable expression prevents tracking its owning path.
-
-Scalar locals remain complete-initializer bindings; inline their expressions when
-using them in arithmetic or constructor arguments. Closure bodies cannot capture
-project authoring locals.
-
-Nested class/list rows remain independently addressable and keep inline IDs:
-
-```neo
-Tags = [
-  @id("story-tag-item-id")
-  "story",
-];
-```
-
-Never match an existing ordered row by index or payload. A bare row is pending
-create shorthand.
-
-When a same-push structural reference has no symbolic, path, or unique-key
-form, an author may assign a previously unseen UUID-v4 with `@id` to the new
-row and reference it in the same edit. Reusing an existing ID means update, not
-create. The server validates authored new IDs for UUID-v4 shape and uniqueness.
-Prefer generated IDs unless the structural reference needs an ID immediately.
-Dry-run preserves a valid authored UUID-v4 ID on a new nested member or dictionary
-value, including one declared as a local initializer. An unknown malformed member
-value ID is an error at its annotation; remove `@id` to let push assign the ID,
-or supply an unused UUID v4. This does not change the derived identity of a
-root/static binding or an existing projected value.
-
-Do not invent IDs for structural rows whose identities derive from an owner
-role. Do not add a separate root/static initializer ID. A constructor argument
-is one such row — its identity comes from the schema key its parameter settles
-— so it never carries `@id`, in either the named or the positional form.
-
-## Same-push references
-
-`Reference<T>` and `Set<Reference<T>>` declare lookup storage. For a class
-`T`, their runtime values are `T` and `Set<T>`, so a projection can assign
-existing class values directly:
-
-```neo
-EligibleIngredients = root.Assets.Crafting.FurnaceRecipes
-  .Select((MachineRecipe recipe) => recipe.Ingredient)
-  .ToSet()
-```
-
-`Box<Reference<Item>>` keeps its reference storage type through push and pull,
-including explicit `new Box<Reference<Item>>()` calls. Its `Item` targets stay
-shared; reading a class reference still produces the class value. A derived
-construction in a base-typed slot retains reference bindings forwarded through
-the inheritance chain, such as `Base<Reference<Item>>` holding
-`new Derived<Reference<Item>>()`.
-
-Writing `Reference(recipe.Ingredient)` inside the callback is also valid.
-`Reference(value)` preserves an evaluated class value and its identity; it does
-not clone it or turn it into a separate wrapper object. An optional generic
-argument checks the target type. Lookup assignment still requires an existing
-backing row and enforces its declared target and collection constraints.
-
-A class-constrained generic lookup may select from a collection of its bound
-class. For example, `Reference<TAsset>` with `TAsset extends HeldItemAsset`
-may use `@settings(collection: CosmeticAssets.HeldItems)` when that collection
-holds `HeldItemAsset`. Derived classes may specialize the target and override
-the member; retain the collection setting on each override.
-
-Use the `Reference` intrinsic. Prefer the most readable form the target
-supports:
-
-```neo
-Reference(Assets.Capitol)
-Reference(root.Assets.Cosmetics.Pants)
-Reference(root.Player.Gold)
-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<NeoDialogue>(id: "capitol-dialogue-id")
-```
-
-- Use a symbol or root path when source can name the value directly. A
-  value-type reference such as `Reference<int>` always names a member path or
-  an `id:`; a plain value is an error.
-- Use `key:` only for a collection with a unique index. Omit `index:` when the
-  collection has exactly one usable unique index; supply the bare member name
-  when it has more than one.
-- Use the generic `id:` form when the ID is the only target information.
-  Unrecognized named arguments are rejected rather than read as IDs.
-- 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.
-- List and dictionary declaration defaults can contain slot references, including
-  nested collections: `List<Reference<int>> Counts = [Reference(root.Save.Bits)]`.
-  Each instance owns its collection; entries continue to target the original
-  root or static slot, including slots supplied by declaration defaults.
-- 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. 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
-dependency graph. Validate against the project after the push: a row deleted by
-the edit is not a target, and lookup/dialogue references must still satisfy
-assignability, collection membership, multiplicity, and group constraints.
-
-`collectionValue` references follow the same post-push resolution and
-membership rules as member defaults. Name the collection itself, for example
-`root.Assets.Quests.Daily` or `Reference(root.Assets.Quests.Daily)`. Invalid
-reference-valued settings are errors; they never silently remove the binding.
-A path may traverse construction defaults
-and declarations created in the same push. Preparation materializes the target
-collection and its required ancestor rows together, preserving the virtual
-identities. No preliminary push or manual value ID is needed.
-
-An object Root.neo writes is init-built when its class has an `init` block. A
-declaration binding may name a member inside it, and the push stores that
-member's row so the binding has a target. A reference an `init` block or
-constructor captures, such as `new Rule(Reference(this.Weather))`, stores its
-target's ID and keeps the target's row. Status refuses two forms, because their
-target has no row to check until the push stores it: a value row's reference to
-a member of an init-built object (bind it from a declaration instead), and a
-binding to a class or list an `init` block builds. A project an older CLI pushed
-with such a captured reference stored it without its target; push once to
-repair it.
-
-## Defaults and localization
-
-A class member whose default constructs its declared type emits a contextual
-`= new()`, including populated defaults and defaults whose value row is
-virtual. A default that constructs a subclass keeps the concrete type, such as
-`Base Value = new Derived();`. Edit the declaration to change the shared
-default, or assign the member inside an instance initializer to override only
-that instance. Leaving the emitted construction unchanged creates no redundant
-value rows. A nullable member with no default remains bare; an explicit null
-default emits `= null`.
-
-Changing a construction to another overload or shared argument rebuilds the
-instance even when the argument values compare equal. Owned inline arguments
-still compare by contents; unchanged shared arguments keep their identities.
-
-Spelling an unchanged child default, such as `FPS = 8`, stays a no-op after
-push even when sibling fields own stored rows. Adding a different child default
-preserves those siblings' row identities; it does not transfer their ownership.
-
-Omitted members are virtual projections of the instance's recorded constructor
-or variant. Later edits to that source update every omitted member. Writing a
-member creates a sparse override with its deterministic projected ID; removing
-that member from an existing initializer resets the override and resumes source
-tracking. Require either transition to appear in `neo diff`.
-
-A stored class with no construction record still inherits literal declaration
-defaults for omitted fields. For example, `FoodInfo.Quality = .OneStar` supplies
-the quality of an existing food row that stores only its price. Do not add an
-instance override to repair that omission. Reads do not invent a historical
-constructor, and required fields with no applicable default remain errors.
-Explicit stored overrides and partial payloads keep their existing meaning.
-
-Generic arguments specify types, not default values. A required generic member
-must be supplied at construction unless its member declaration or an inherited
-member declaration supplies a default. Missing required members are compile
-errors. Pull preserves incomplete stored objects for repair; add the missing
-initializer or declare the intended member default before testing or pushing.
-An override without a local initializer inherits an available base member
-default, including when its stored `defaultValue` carrier is null. An explicit
-`= null` initializer is a literal nullable default, not an inheritance marker.
-
-Editing an initializer updates sparse override rows in place: projected member
-IDs remain stable, and omitted virtual rows are never emitted as authored seed
-records. Spelling a declared default verbatim in a new initializer lowers to
-the same absence as omitting the member — a leaf equal to its declaration, or
-a bare class construction whose members the declaration wholly settles, mints
-no override row and resumes source tracking. A stored row already spelling its
-default converges to the sparse form on its next authored touch. A stored
-construction predating the P75 collapse converges the same way: its next push
-drops the constructor-settled keys the body duplicated from the creation data
-and stamps the construction's provenance. That is a one-time storage
-convergence, not an edit — resolved values do not change, and the argument
-rows stay reachable through the creation data that already named them.
-
-Defaulted members may be added without recreating existing instances, including
-instances whose sparse arguments are retained only as constructor data.
-Source is authoritative for a construction: editing its constructor arguments,
-including a static's, rebuilds the instance in place on push. The value keeps
-its ID, rows at unchanged positions keep theirs, added entries create rows,
-removed entries delete them, and the stored creation data records the new
-arguments. Overrides the rebuilt construction no longer produces are deleted,
-so keep them in the construction's `{ ... }` block. A construction whose class
-changed fails with `construction-arguments-conflict`; delete and recreate the
-value to change its class.
-
-Write main-locale text directly in localizable string initializers. Pull/lower
-retargets only the edited assignment. Equal primary-locale text on the same
-declared member shares a localization record across member overrides and
-instances. Different members keep separate translation contexts. Editing a
-class default updates its inheriting instances; editing one instance does not
-change that default. Reverting the instance text to its default restores the
-shared assignment and archives an unreferenced unique text record.
-
-An empty string stores no localization ID. Entering nonempty primary-locale
-text selects or creates the member's shared localization record. Do not author
-localized-text IDs in place of prose. Nullability, not text length, controls
-whether the member is required. Other locales remain translations of their
-linked source record.
-
-## Managed files
-
-Managed images support PNG, JPEG, GIF, and SVG. SVG files use `image/svg+xml`
-and retain their original bytes through pull, push, and Unity export; the CLI
-does not rasterize them. The same byte-length, MIME-type, and SHA-256 checks
-apply to SVG transfers as to other managed files.
-
-Declare files in typed registries:
-
-```neo
-ImageRegistry Images = new() {
-  @id("sword-image-file-id")
-  @settings(template: PixelArt)
-  NeoImage Sword = new("Files/Images/Sword.png");
-}
-
-AudioClipRegistry AudioClips = new() {
-  @id("sword-hit-audio-file-id")
-  @settings(template: SoundEffect)
-  NeoAudioClip SwordHit = new("Files/AudioClips/SwordHit.wav");
-}
-```
-
-Reference a sprite with `Images.Sword.Slice(0)` and an audio clip with
-`AudioClips.SwordHit`. A bare `Images.Sword` represents the file ID only in a
-file-valued context such as `SpriteInfo.FileId`; it is not a complete sprite.
-
-Dropping a supported binary under `Files/Images/` or `Files/AudioClips/`
-creates a pending file with a provisional deterministic symbol. Status,
-diff, and dry-run do not rewrite its registry. A successful push creates the
-record, uploads verified bytes, and materializes its declaration and ID.
-
-Registry symbols derive deterministically from the persisted file name. For
-example, `tree.cherryblossom.png` becomes `TreeCherryblossom`. Keep an authored
-declaration aligned with that spelling, or set an explicit persisted name such
-as `@settings(name: "TreeCherryBlossom.png")` when the binary path should stay
-different. The name must end with the binary's extension, because pull
-rebuilds the file's path from it. With no template annotation, the CLI persists the complete built-in
-Unity defaults for the file kind.
-
-Template-backed Unity settings may contain sparse nested override values and leaf
-paths such as `platformSettings.standalone.maxTextureSize` or
-`spriteSettings.pivot.x`. Preserve these paths during synchronization so untouched
-settings continue inheriting from the template.
-
-A top-level `NeoImage` or `NeoAudioClip` declaration in any definition file
-can stand in for an inline entry. The registry lists it by name
-(`NeoAudioClip SwordHit = SWORD_HIT;`), and the declaration carries the `@id`,
-`@settings`, and path. Push, pull and reset keep it in its own file. Every such
-declaration must be listed exactly once.
-
-Pull/push compare server-verified SHA-256, not storage ETags. A divergent
-binary keeps local bytes and writes the verified remote side under
-`.neo/conflicts/files/<file-id>/`. A retained declaration with a missing binary
-is an error; remove the declaration to request deletion.
-
-New schema getters referenced by NeoFlow interpolation need no `@id`. Export and
-`neo dev` assign the same identity to the declaration and its references, including
-inherited getters. Repeated exports and the next push reuse the export identity ledger.
-
-Dictionary string keys are data. An entry named `"Id"` reads its value through
-`dictionary["Id"]`; class `.Id` continues to return the class instance identity.
-
-You can remove a constructor and replace every call to it in the same edit. Push prepares the new calls together with the schema change and removes argument rows owned by the old constructions.