@neocompose/cli 0.87.2 → 0.89.0

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

@@ -1,773 +0,0 @@
-# Declarations and construction
-
-Use this reference for schema declarations, annotations, member contracts,
-constructors, and construction-time settlement.
-
-## Contents
-
-- Declaration rules
-- Annotations and settings
-- Member and relation rules
-- Function overloads
-- Computed initializers and declared constructors
-- Required constructors and settlement
-- Inheritance construction
-
-## Declaration rules
-
-Declare classes, interfaces, and enums only at the top level of definition
-`.neo` files. Do not nest them in a type, body, accessor, lambda, initializer,
-migration, or `.neoflow` file. NeoFlow has its own single-dialogue exception.
-
-Persist the declared identifier as the schema name; there is no separate
-technical/display name. Keep existing IDs stable.
-
-NeoScript keywords are case-sensitive. Qualified member labels, schema keys,
-registry entries, and enum options occupy their owner's namespace, so they may
-reuse unrelated builtin names such as `Set`, `Dictionary`, `List`, or `Math`.
-Type-token spellings such as `Set` and `Dictionary` are also legal parameters.
-Actual lowercase grammar keywords such as `class` and `return` remain
-reserved. Top-level declarations and bindings retain their own reservations:
-for example, neither may shadow the unqualified builtin `Math` namespace, and
-implicit bindings such as `this`, `root`, and `context` cannot be parameters.
-
-```neo
-@id("interface-named-id")
-interface INamed {
-  @id("named-name-id")
-  string Name { get; }
-
-  @id("named-use-id")
-  void Use(SomeClass context);
-}
-
-@id("class-item-id")
-@storage(allowed: .Immutable)
-abstract class Item<TContext extends SomeClass> : INamed {
-  @id("item-name-id")
-  @settings(searchBy: .MemberKey)
-  public virtual string Name = "";
-
-  @id("item-use-id")
-  public abstract void Use(TContext context);
-
-  @id("item-load-id")
-  public native async bool Load(TContext context);
-}
-```
-
-Use ordinary `public`, `protected`, `private`, `static`, `virtual`, `abstract`,
-`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 can declare type
-parameters and pass arguments to the interfaces they extend; see Interface
-members.
-A `closed` class is implicitly abstract and defines an exhaustive subtype
-family within the project version. Do not combine `closed` with `abstract` or
-`sealed`. Descendants remain open unless explicitly sealed or closed. Every
-generic parameter of a direct subclass must appear in its base construction.
-Changing the family requires recompilation of its switch-expression consumers.
-Generated Unity C# uses an abstract class; C# 15 is not required.
-
-A read-only override may narrow a class or interface contract to an assignable
-class or derived interface, including a non-null value for a nullable contract.
-Generated Unity C# keeps the inherited property type for Mono compatibility;
-NeoScript sees the narrowed type. Stored implementations of an abstract getter
-remain get-only in generated C#.
-
-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.
-
-## Annotations and settings
-
-Never author `@system`. It marks platform-owned system records and is rejected
-on project-authored declarations, members, overrides, values, and files. The
-system types visible in project source may themselves have system provenance;
-that does not authorize copying the annotation onto authored records.
-
-Use context-aware typed annotations:
-
-- `@settings(...)` for format/search/collection/editor constraints.
-- `@storage(allowed: ...)` on classes and storage keys on members.
-- `@visibility(.Hidden)` only on a class; absence means visible.
-- Stateful settings use contextual enum cases, such as
-  `@settings(format: .Plain)` and `@settings(kind: .Unordered)`.
-- `@settings(...)` before a `List` or `Set` element or `Dictionary` value type
-  configures the collection's entries: `List<@settings(format: .Plain) string>`,
-  `Dictionary<string, @settings(min: 0) int>`. Only the member that declares
-  the collection spells them; overrides share its entries.
-- `@relations(...)` only on the source class of a specialized direct relation.
-- `@distribution(kind: .Sparse | .Packed)` only on a value-owning member
-  declaration or override. It chooses whether the member's value keeps its
-  own row (`.Sparse`) or is stored inside its owning parent's row (`.Packed`).
-  Omit it unless the choice must be explicit: on a root declaration absence
-  means the automatic distribution for the member's kind and settings, and on
-  an override it means inherit. `pull` writes the annotation only where it is
-  explicitly stored. A packed subtree shares its parent's document-size limit,
-  so a write that would exceed the hard limit fails instead of falling back.
-  `.Packed` is rejected on a List whose `listKind` is unordered.
-- `@effect` only on a class member function. The Unity runtime runs it for
-  every live instance and reruns it whenever data it read changes; the web
-  editor, `neo test`, and dry runs never run effects. It must be an immediate,
-  parameterless `void` instance function with a NeoScript or abstract body.
-  An override without the annotation inherits; `@effect(kind: .None)` stops
-  an inherited effect. Use it instead of polling or relaying changes by hand.
-
-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.
-
-`root.User` holds per-player data that every save shares, such as settings.
-Only User classes go under it. Declare one with `@storage(allowed: .User)` on
-the class; its subclasses and base must be User classes too:
-
-```neo
-@storage(allowed: .User)
-class AudioPrefs {
-  public float Volume = 1;
-}
-```
-
-Members of a User class declare no `@storage` and no stored statics, and every
-type they name must be User-safe: primitives, enums, User classes, collections
-and delegates of those, and interfaces whose signatures are User-safe. Code in
-a User class reads only `root.User`. Other code reads `root.User` but can't
-assign, mutate, construct, or invoke User data. Lookups and listeners don't
-cross between User and Save data; Session lookups may target `root.User`.
-
-`readonly` is init-only, as in C#, and independent of storage. A field
-initializer, a constructor body, an object initializer block, or an authored
-value sets it; nothing writes it after construction. It is valid on Save,
-Session, Immutable, and User classes, but not with Writable storage. It may
-read a header parameter:
-
-```neo
-class MixerGroup(string name) {
-  public readonly string Name = name;
-  public readonly List<MixerChannel> Children = [];
-  public float Volume = 1;
-}
-```
-
-Readonly is shallow. A readonly collection's membership is fixed, while its
-entries' members follow their own storage and mutability. User class members
-still declare no storage.
-
-A readonly member declared as a literal (no initializer or constructor call)
-that reads neither `this` nor a constructor argument and holds nothing
-writable is a constant. Instances share its declared value and store nothing
-until a constructor or initializer block writes it. A readonly collection or
-initializer is still built per instance.
-
-`@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
-class. An index accepts a non-localizable string or single-select enum. A column
-may target `__other__` for the default layout of subclass-added fields. Declare
-indexes only on the original List member. Overrides inherit its indexes, and
-`@index` on an override is a source error. A List field may override an abstract
-List getter.
-
-Use `.EnumCase` only when context fixes one enum type; otherwise write
-`EnumType.Case`. Constructor parameters supply this context for positional
-and named arguments, including substituted generic parameter types. Defaults
-and settings must be statically analyzable. An integer is not an enum option.
-Instance fields, static fields, and local value definitions report incompatible
-enum initializers at the authored expression before value lowering. Extracting
-a list or dictionary into a local preserves element validation. Errors point
-to the entry in the local definition, including missing `.Option` or
-`EnumType.Option` dictionary keys.
-
-An explicit construction must be assignable to its receiving type. For example,
-`List<Base>` accepts `new Derived()` when `Derived` inherits `Base`, but rejects
-an unrelated class at `new`. Generic arguments must also be compatible.
-
-A generic class without a declared constructor is constructed with its type
-arguments, such as `new Box<int> { Item = 4 }` or a target-typed
-`new() { Item = 4 }`. A `T` field is required unless the type argument is
-nullable, so `new Box<int?>()` may omit it. `new Box()` is rejected as an open
-generic Class. Inside the class, methods and field initializers construct with
-the class's own parameter, such as `public Bag<T> B = new Bag<T>();`. Such an
-initializer with fields or entries, like `new Bag<T> { N = 3 }`, runs per
-instance, since each instance closes `T` differently. A type
-argument that wraps the parameter, such as `new Bag<List<T>>()`, is rejected.
-Type arguments must satisfy `extends` constraints in bodies too. A written
-type argument list names every parameter, so `item is Tool<Asset>` is rejected
-when `Tool` declares two. A bare generic name, such as `item is Tool`, stays
-allowed.
-A type argument may be a delegate, such as `Box<NeoDelegate<int, int>>`, but
-not a `NeoAction`, which is never a value.
-
-Primary-constructor parameters can initialize generic collection fields directly:
-
-```neo
-class Box<T>(List<T> value) {
-  public List<T> Value = value;
-}
-```
-
-The same rule applies to `Dictionary<string, T>`, nested collections, and
-stored instances such as `public static Box<int> Value = new([1, 2]);`.
-
-## Member and relation rules
-
-Infer member kind and optionality from its type and nullability. Treat the
-initializer as its default. Omitted fields remain virtual and resolve through
-the instance's recorded constructor or variant. They track later source-default
-edits until that field is explicitly overridden; resetting an override makes it
-virtual again.
-Editing an inline child preserves the outer construction's call-site values for
-its other fields. The child keeps that construction while its variant selection
-matches; selecting a different variant gives it an independent recipe.
-
-Declare a lookup member as `Reference<T>`. `T` can be any value type except
-code types; see the NeoScript reference for handle and slot references.
-`public Reference<Config> Config` selects one row and reads as `Config`.
-`public Set<Reference<Config>> Configs` selects several and reads as
-`Set<Config>`. `public Reference<int> TrackedStat` names another member's int.
-`Reference<T>` also works as a constructor or method parameter, a collection
-element, a dictionary value, and an unbound generic argument such as
-`Box<Reference<int>>`. An initializer body for a single reference returns one
-row, never a set. `T` with `@settings(collection:)` is an error; the language
-server's quick fix respells it.
-
-`@settings(collection: Owner.Member)` binds a class reference to one
-collection. Without it the reference is unbound: it selects any stored row of
-`T` or a subclass, or any member slot of type `T`, anywhere in the project. A
-bound reference can't be a generic argument. The selected row's store decides
-writes. A write through it to a Save row lands, and to an asset row it errors.
-Its generated C# property is the read-only interface; call `TryWritable` to
-write.
-
-An unbound default can name its row by a unique index:
-
-```neo
-public Reference<Item> StarterSeed = root.Assets.Items.Index.Slug["seed.carrot"]!;
-```
-
-The receiver is a `root` path to a List, `.Index.<Name>` is a unique index on
-it, and the key is a string literal. Any other shape stays initializer code.
-
-A slot reference's default wraps a member path in `Reference()`. The path may
-use the same index segments. A plain value isn't a default, and `this` doesn't
-exist yet:
-
-```neo
-public Reference<int> TrackedStat = Reference(root.Player.Gold);
-public Reference<string> Greeting = Reference(root.Npcs.Index.Slug["mira"]!.Greeting);
-public Reference<NeoVariant<Tree>> Look = Reference(root.Garden.Felled);
-```
-
-A `NeoVariant<T>` member's own default stays the bare variant path. A
-`Reference<NeoVariant<T>>` names a member that holds a variant, so its default
-is a `Reference()` member path.
-
-A `Reference<T>` member satisfies an interface `T Foo { get; }` or
-`{ get; set; }` and an abstract `T Foo { get; }`.
-
-Constructor and function parameters use `Set<T>` for several selections.
-
-### Interface members
-
-An interface types a member anywhere a class does: a field, a nullable,
-`readonly`, or `static` field, a `List`, `Set`, or `Dictionary` entry, a
-generic argument, a parameter, and `Reference<I>`. Each row holds its own
-class, which must implement the interface.
-
-```neo
-interface IContainer<T extends Item> {
-  List<T> Contents { get; }
-}
-
-class Crate<T extends Item> : IContainer<T> {
-  public List<T> Contents = [];
-}
-
-class Player {
-  public IContainer<Seed>? Pouch = new Crate<Seed>();
-  public List<IContainer<Seed>> Racks = [];
-}
-```
-
-- Construct a class, never the interface: `new IContainer<Seed>()` is an error.
-  Defaults and constructor arguments name the concrete class.
-- An open class can sit in an interface slot only when the interface fills
-  every class parameter, as `Crate<T> : IContainer<T>` does. Otherwise store a
-  closed subclass.
-- A class implements a given interface once, counting its `extends` chain.
-  `IContainer<Seed>` and `IContainer<Tool>` on one class is an error.
-- An interface argument is a type parameter in scope or a type with none
-  inside it. `IContainer<List<T>>` is an error.
-- `x is IContainer<Seed>` compares the arguments the row implements the
-  interface with. A generic interface needs its arguments in `is`.
-- `NeoVariant<I>` is an error, since variants belong to a class. `@index` on a
-  collection of interface entries is an error; `@column` can name an interface
-  property.
-- Interfaces carry no storage. A row fits a slot only when its class allows
-  the storage the row lives in. The compiler refuses an assignment that can't
-  fit, and push and commit refuse an authored row that doesn't fit.
-- A variant or animation override that puts a different class in an
-  interface slot replaces the slot's row.
-- A generic parameter can be constrained by an interface,
-  `T extends IContainer<Seed>`, and an interface can be a generic argument
-  where the parameter's constraint admits it.
-
-Generated C# types the slot by the generated interface, so a class that
-doesn't implement it doesn't compile. Writing a C# class that implements the
-interface but isn't a Neo class throws, naming the slot. So does writing a row
-the interface doesn't determine.
-
-### Set members
-
-`Set<T>` is an insertion-ordered collection that can't hold duplicates. The
-element picks the storage:
-
-- An enum `Set<Trait>` is a multi-select Enum.
-- `Set<Reference<T>>` is a multi-select lookup.
-- `Set<NeoDialogueReference>` is a multi-select dialogue lookup.
-- Any other element makes an owned Set whose entries are rows, like a List.
-
-Constructor mutations such as `Bag.Add(7)` keep owned collection entries as
-backing rows during export and sparse replay. Existing entries retain their
-identities; added entries receive stable identities under the instance.
-
-An owned Set holds `bool`, `int`, `float`, `decimal`,
-`@settings(format: .Plain) string`, vectors, `Color`, sprites, audio clips,
-a class, or an interface. Elements can't be nullable, collections, variants,
-delegates, or actions. A class or interface entry is unique by row, a value
-entry by its value. `@index` and `@column` work as on a List; `kind:` is an error, since a
-Set is always insertion-ordered.
-
-```neo
-@index(member: Slug, kind: .Unique)
-public Set<Quest> ActiveQuests = [];
-public Set<int> LuckyNumbers = [3, 7];
-public Set<Trait> Traits = [.Brave];
-```
-
-`selection:` is an error everywhere: `Set<T>` selects many and `T` selects
-one. The language server's quick fix rewrites `@settings(selection: .Multi)`
-to a `Set<…>` type. A default literal that repeats a value fails `push`, and a
-`List<Trait>` stays an ordered List of enum values. Queries over a Set, such
-as `Where` and `OrderBy`, return a Set; `ToSet()` turns a List into one.
-
-Declare a multicast event as `NeoAction<…>`. Its value is an ordered listener
-set, so give it a bracketed list of method groups — never a lambda, and never
-a bare method group — and never mark it `required`: the rest state is the
-empty set.
-
-```neo
-public NeoAction<int> OnDamaged = [PlayHitFlash, ApplyDamage];
-```
-
-A nested field initializer such as `Watcher = new() { OnTally = [Handle] }`
-can target an inherited generic method on its enclosing instance. The listener
-uses that owning instance, including when declaration defaults are materialized.
-Explicit receiver targets keep their captured instance.
-
-An instance-bound listener reachable through a stable project root keeps its
-receiver path, for example `public NeoAction<int> OnDamaged =
-[root.Assets.OnDamage];`. Pull refuses a bound receiver that has no
-deterministic `root.*` path instead of emitting a source expression that would
-silently change the target.
-
-Subscribe and unsubscribe with `+=` and `-=` against the member reference
-itself; both are durable writes deduplicated by target identity, so
-re-running a subscription cannot double-subscribe. Invoke it as a statement —
-an action is never a value, never a return type, and never assigned with `=`.
-
-Implement a system lifecycle interface to run code when the runtime does.
-`INeoOnLoad` and `INeoOnUnload` run when an instance becomes live and when it
-stops being live. The `INeoUnity*` interfaces, such as `INeoUnityUpdate` and
-`INeoUnityOnTriggerEnter2D`, run for a rendered `NeoObjectBase` in play mode.
-Their member names, such as `OnLoad` and `Update`, are reserved: declare one
-only as the public, immediate instance method that implements its interface,
-and never mark it `@effect`. Subscribe Session actions in `OnLoad` and remove
-them in `OnUnload`. React to data changes with `@effect`, and keep `Update`
-for work that really happens every frame.
-
-Keep generic project relations as typed top-level declarations in
-`Relations.neo`. Let the compiler derive identities for owned descriptors and
-concrete generic bindings.
-
-For world layer links, instantiate a project-authored descendant of
-`NeoTileLayerLink` or `NeoObjectLayerLink` that resolves exactly one
-`targetLayer` relation. The relation is the complete binding; do not add
-value-level target metadata.
-
-### Function overloads
-
-A class may declare several functions with one name when their parameter
-types differ:
-
-```neo
-class Inventory {
-  public int Add(Item item) { return 1; }
-  public int Add(Item item, int count) { return count; }
-  public int Add(List<Item> items) { return items.Count; }
-}
-```
-
-A class's overload set for a name holds every function of that name it
-declares or inherits. A derived class adding `Add(Item item, int count)` next
-to an inherited `Add(Item item)` overloads it. Static and instance functions,
-NSFunctions and native functions, and generic and non-generic functions mix
-freely.
-
-Every two functions in a set need different parameter types after dropping
-nullability, substituting base type arguments, and renaming function type
-parameters by position. So `Add(Item)` and `Add(Item?)` collide, and so do
-`F()` and `F<T>()`. A `Find<T = Item>(T value)` occupies `Find(Item)`.
-
-At most one function per name and class may be dispatched: `abstract`,
-`virtual`, `override`, or an interface implementation. Overrides target that
-one function. Interfaces can't overload, so an interface declares each
-function name once. When several class functions share an interface
-function's name, the one whose parameters match implements it.
-
-`Equals` and names a platform class or interface declares, such as
-`OnTriggerEnter2D` and lifecycle hooks, can't be overloaded. A function still
-can't share a name with a field, property, getter, or action.
-
-Overloads generate C# overloads with the same name. A plain overload stores
-under the key `Name#<memberId>`. A dispatched or lone function keeps the key
-`Name`, so a project without overloads stores exactly what it did before.
-
-## Computed initializers and declared constructors
-
-Inherited member initializers read parameters from the constructor that declared
-them, including when export materialization clones their bodies. A storage-only
-override keeps that original constructor scope.
-
-Use an expression initializer when a member default must be evaluated during
-construction rather than stored as a closed literal. It is replayed for omitted
-members in push, web, and SDK contexts. A stored override remains pinned until
-it is reset.
-
-Operator expressions are valid member defaults and store as computed
-initializers, the same way calls do — `public float Derived =
-Flags.Start / Flags.Scale;` is fine. Positions that store no rows still
-require literals: dictionary keys must be string literals or enum option
-literals for enum-keyed dictionaries, and Color components must be numeric
-literals. In a static member or its collection entries, a vector with a
-computed component, such as `new Vector2(Probe.X, 1)`, stores as a computed
-initializer. Instance member defaults, including their collection entries,
-still require numeric literal vector components. When a computed list or
-dictionary entry carries an authored `@id`, parenthesize the expression —
-`@id("row") (A.B / A.C)` — so the annotation names the row rather than its left
-operand.
-A push that assigns such a row's ID adds those parentheses itself.
-
-Numeric literals do not use C# suffixes: write `0` or `0.5`, not `0f` or
-`0.5f`. The declared/contextual type determines whether a literal is stored as
-an int, float, or decimal.
-
-A direct field or property read is computed too, whether it is local,
-qualified static, or reached through a stable root path. For example,
-`protected int Slots = FeatureFlags.StartInventorySize;` evaluates the current
-static field or getter whenever a new instance is constructed; it is not baked
-into a persisted literal during push.
-Root paths such as `root.Save.World.Time.Year` remain executable even when
-`World` and `Time` exist only through construction defaults. This also applies
-inside `new() { Year = root.Save.World.Time.Year }`: the child field retains
-its initializer and reads the root when the instance is constructed.
-
-Declare overloadable constructors as members when each constructor body owns
-its parameter scope:
-
-```neo
-class Foo {
-  public string Bar;
-  public bool IsFun;
-
-  public Foo(string bar, bool isFun) {
-    this.Bar = bar;
-    this.IsFun = isFun;
-  }
-}
-
-Foo value = new(bar: "BAR", isFun: true) { IsFun = false };
-```
-
-Constructor parameters are visible only in that constructor body. Do not read
-them from member initializers. Each declared constructor must settle every
-required member on its own; a call-site block cannot repair an invalid
-constructor declaration.
-
-## Parameter default values
-
-Default a parameter with `= <constant>` on class headers, declared
-constructors, native functions, NSFunctions, and interface functions:
-
-```neo
-class Foo(string bar = "BAR", int volume = 3) {
-  public string Bar = bar;
-
-  public string Shout(string text = "hey", bool loud = true) {
-    return loud ? text.ToUpper() : text;
-  }
-}
-
-Foo a = new();                 // fully defaulted header: all defaults apply
-Foo b = new(bar: "bar");       // volume fills from its default
-```
-
-Use only constants: bool, int, float, and decimal literals (optional leading
-`-`), string literals without interpolation, leading-dot enum options
-(`.North`), and `null` on a nullable parameter. Place every defaulted
-parameter after every non-defaulted one. `Type? name` stays nullable-and-
-mandatory unless it also declares a default — nullability and defaultedness
-are independent.
-
-Omit defaulted arguments at call sites: function calls bind positionally and
-drop only a trailing suffix; constructor calls name a subset that covers
-every non-defaulted parameter. When several overloads match, the one filling
-in the fewest defaults wins, and a residual tie is a declaration-time error.
-Implementations of an interface function restate its defaults exactly.
-
-Do not default parameters of deferred functions, delegates, actions,
-closures, or overrides. Enum defaults store the option id, so renaming the
-option changes the emitted `.Option` spelling without a record change.
-
-Editing a stored object's constructor arguments rebuilds it under the same
-identity. Initializers that read that object, including collection projections,
-wait for its replacement before evaluating its members.
-
-Stored objects created with an implicit constructor may have required fields
-settled in their object body. Keep that body when editing initializer behavior
-or adding a parameterless constructor; an empty stored argument list does not
-require inventing constructor arguments.
-
-## Required constructors and settlement
-
-Put one required constructor on the class header when the entire class body
-needs the parameters:
-
-```neo
-class Foo(string bar, bool isFun) {
-  public string Bar = bar;
-  public bool IsFun;
-
-  init {
-    if (isFun) {
-      IsFun = true;
-    } else {
-      IsFun = false;
-    }
-  }
-}
-
-Foo value = new(bar: "BAR", isFun: true) { IsFun = false };
-```
-
-Header parameters are in scope throughout the instance members of the class.
-Field initializers, collection entries, object initializers, and lambdas read
-them per construction, so `public NeoDelegate<int> Value = () => n;` returns
-each instance's own `n`. A lambda can also read `this`, as in
-`() => n + this.M`; the rest of an initializer can't. Static members have no
-construction and can't read header parameters. Permit at most one `init`
-block. A header constructor disables implicit parameterless `new` and forbids
-additional constructor overloads. Its derived constructor identity is not
-authored with `@id`.
-
-Treat a non-null member with no default as required. Treat a nullable member
-with no default as implicitly `null` and therefore settled:
-
-```neo
-class Result {
-  public string Value;   // required
-  public bool Ok = true; // settled by default
-  public string? Note;   // settled by implicit null
-}
-```
-
-Accept settlement only from:
-
-1. The member's own initializer expression.
-2. Assignment on every reachable path in `init` or a constructor body.
-3. A call-site initializer entry, in value source and NeoScript bodies alike,
-   when using an otherwise valid construction path.
-
-Do not infer settlement from a side effect inside another function. Require
-full `if`/`else` coverage when an assignment is conditional.
-
-Apply construction in this order: base construction, member initializers,
-`init` or declared-constructor body, then the call-site initializer block. The
-call-site block wins when it refines an earlier value.
-
-## Inheritance construction
-
-Treat the base clause as a construction expression:
-
-```neo
-class Base(string name) {
-  public string Name = name;
-}
-
-class Child(string name, int rank) : Base(name) {
-  public int Rank = rank;
-}
-```
-
-Call a declared base constructor with `: Base(args)`. When a base has no
-constructor, use a base initializer block to settle required inherited members:
-
-```neo
-class Base {
-  public string Name;
-  public bool Enabled = true;
-}
-
-class Child(string name) : Base {
-  Name = name,
-  Enabled = false
-} {
-}
-```
-
-A header base clause with no arguments, such as `: Base()` or `: Base`,
-runs a zero-argument or fully defaulted base constructor when available.
-Otherwise, if the base has only declared constructors, it uses the member
-initializers and base block without running a base constructor. The base block
-must settle any remaining required members. A required base constructor cannot
-be skipped. A declared constructor's `: base()` must call a base constructor
-when the base declares one.
-
-Bind generic base arguments explicitly when needed. Reject a subclass that
-omits required base arguments or leaves any inherited required member
-unsettled.
-
-Generic constraints may construct another generic from a parameter in the
-same declaration. This preserves the relationship between the parameters in
-source checks, stored initializer replay, and generated C#:
-
-```neo
-class PlacedItem<
-  TData extends InventoryStackData,
-  TItem extends InventoryItem<TData>
->(TItem item) {
-  public TData Data = item.DefaultData.Clone();
-}
-```
-
-Object initializer blocks can set `readonly` members of the newly constructed
-instance, including nested `new` expressions. Ordinary assignments after
-construction remain subject to storage and `readonly` restrictions.
-
-Runtime construction never supplies an Immutable member: an initializer block,
-constructor body, base-clause argument, or generated C# factory cannot set one.
-The value is never stored with the instance. When the declaration, including
-every row it owns, reads neither `this` nor a constructor argument, and no
-value of its type holds a writable member, the member is a constant and every
-instance shares one value. Otherwise each instance evaluates the declared
-initializer with its own `this` and constructor arguments, again after a
-reload. A method group such as `selector: SelectTorso` binds `this`.
-`Clone()` shares an authored Immutable value or a constant and re-evaluates a
-per-instance one. A class with a required Immutable member and
-no initializer cannot be constructed at runtime; only authored values construct
-it.
-
-Populated unordered member defaults, such as `@settings(kind: .Unordered)` with
-`List<Entry> Entries = [new Entry()]`, are constructed by an initializer for
-each instance. A declaration has no container value row to own unordered entries.
-Nested unordered lists already have container rows and retain their stored values.
-A field, collection entry, or dictionary value can't place a value that
-something else already owns, such as `Bag = [Shared.Pattern]` or a constructor
-parameter stored in an ordinary field. Call `Clone()` or use `Reference`.
-
-A lookup's declared class must be assignable to the entry class of its
-`@settings(collection: Owner.Member)` collection. A subclass may narrow the
-selection. Constructor arguments and member initializers must select compatible
-targets too. An `NPC` lookup cannot select from `List<Quest>`, even when its
-initializer is typed `NPC`; status reports the conflicting collection annotation.
-
-Generic constructions can nest the same generic class, including through
-collections, such as `Box<Box<int>>` or `Box<List<Box<int>>>`. Each `new` uses
-its own type arguments during first push and stored replay. Editing a nested
-constructor argument rebuilds its projected fields in place, including fields
-stored inside a packed parent; push followed by pull leaves a clean checkout.
-
-Sparse children with their own declared constructor replay that constructor
-when reconciling edits, including when passed as an aggregate argument.
-
-Schema export retains a constructed default's generic arguments, including
-nested collection references. For example, a `NeoAnimationClip<ArmPart>`
-default constructs `new NeoAnimationClip<ArmPart>` and its frames reference
-`List<NeoAnimationFrame<ArmPart>>`.
-
-When a construction leaves a required member unsettled, CLI diagnostics point to
-`new` and include the member declaration as a related location. Fix that
-construction before pushing. Valid root initializers still participate in
-reference checking, so an unrelated root error does not imply their values are
-missing or deleted. Independent reference errors remain visible.
-
-Object initializer assignments use commas. The last comma is optional; the
-semicolon terminating the enclosing declaration is valid:
-
-```neo
-AudioSettings AUDIO_SETTINGS = new() {
-  Main = new AudioMixerGroupSettingsFolder("Main", "Master", "MasterVolume", []),
-};
-```
-
-A semicolon after `Main = ...` inside the initializer is invalid. Editor and CLI
-diagnostics highlight that separator in the authored file, including global,
-static member, and protected root initializers. Statement semicolons inside
-function or delegate bodies remain valid.
-
-## Stored tuples
-
-Declare fixed positions with ordinary types and optional labels:
-
-```neo
-public (int Count, bool Enabled) State = (3, true);
-public (int, (string Label, int Count))? Detail = null;
-```
-
-Each position has a derived member descriptor. Do not author descriptor IDs.
-Changing a label preserves its position and identity. Changing arity or moving
-stored positions requires migrating existing values. A required tuple without
-a default must be supplied during construction; it has no automatic zero tuple.
-Owned class and collection elements keep the ordinary single-owner rule. Use
-an explicit reference or clone when another stored value already owns them.