diff --git a/upm/com.enzx.nxgraph.serialization/CHANGELOG.md b/upm/com.enzx.nxgraph.serialization/CHANGELOG.md index cc38462..9ea808f 100644 --- a/upm/com.enzx.nxgraph.serialization/CHANGELOG.md +++ b/upm/com.enzx.nxgraph.serialization/CHANGELOG.md @@ -4,7 +4,7 @@ All notable changes to this package are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [Unreleased] +## [2.2.0-alpha] ### Added diff --git a/upm/com.enzx.nxgraph/CHANGELOG.md b/upm/com.enzx.nxgraph/CHANGELOG.md index e3fc297..00baafd 100644 --- a/upm/com.enzx.nxgraph/CHANGELOG.md +++ b/upm/com.enzx.nxgraph/CHANGELOG.md @@ -2,20 +2,16 @@ All notable changes to this package will be documented in this file. -## [Unreleased] - -### Runtime (staged NxGraph core) -- Sub-graph ports: the machine-wrapping composites — nested machines (both runtimes), the history states, and the parallel family per region — accept an optional `SubGraphPorts` declaration (`SubGraphPorts.OwnBoard().In(source, childKey).Out(childKey, parentKey)`; DSL: a `ports` argument on all four `.SubGraph` overloads and `ParallelRegion` entries on `.Parallel`). Its presence makes the composite run the child graph on the child's **own** Graph-scoped board, created from the child's declared schema and substituted at stamp time — sibling sub-graphs stop colliding on same-named keys and a child stops seeing the parent's whole board. Inputs (literal or parent-key sources) apply in declaration order at every fresh child start after the board resets to its registered defaults; a history lift-back re-entry applies nothing. Outputs copy back in declaration order at the child's terminal, success and failure alike; several regions targeting one parent key resolve in region order. Construction rejections name the key (no child Graph schema, foreign target/source keys, Node-scoped parent-side keys); port application is typed copies, 0 B on both runtimes. Owned boards are durable artifacts: `EnumerateOwnedBoards()` walks every owning composite with node-index-path identity so hosts persist each board with `BlackboardSerializer` and restore into a fresh machine's enumeration before `ResumeDeep`. Validator: Info on owns-board presence, Warning on colliding output targets (across parallel regions included), best-effort Warning on an input the child never reads statically; the conflicting-child-schema warning no longer fires for board-owning composites. -- Serialization payload version 12: sub-graph ports ride the wire — the subgraph entries gain the owns-board flag plus a ports list, composites carry sparse per-region ports, and each port rides as direction, source key name or field-model literal, target name, and the runtime-stable value type name. Everything rebuilds name-bound; a deserialized child graph carries no schema, so the host binds a Graph-scoped board on the rebuilt child machine to supply the board to own. Pre-v12 payloads read shared-board and port-free. -- Hierarchical outcomes: the machine-wrapping single-child composites — nested machines (`.SubGraph(child)` / `.SubGraph(mode, child)`) and the history states — accept optional `outcomeCode` (`BlackboardKey`) and `outcomeName` (`BlackboardKey`) keys at construction. When the child run reaches a terminal, the composite writes the child machine's `LastOutcome` code and name through its stamped parent-level context, before returning its own `Result`, so a parent branches on *which* outcome a sub-graph ended with using the ordinary data-built `SwitchState`/`ChoiceState`. A terminal with no declared outcome publishes `0` and the empty string; failure terminals publish too; a history composite publishes only at genuine terminals — a lift-back re-entry publishes nothing until the resumed session ends. Node-scoped keys are rejected at construction naming the key, and the validator warns when a key is declared but the child graph declares no outcome codes. -- Serialization payload version 11: the declarations ride the existing subgraph/composite payload entries as key names; deserialized composites rebuild name-bound and resolve against the machine's bound boards per publish, with targeted miss/type-mismatch errors. Pre-v11 payloads read outcome-key-free. - ## [2.2.0-alpha] ### Breaking - The delegate-backed director states were renamed: `ChoiceState` → `RelayChoiceState`, `SwitchState` → `RelaySwitchState`, `AsyncChoiceState` → `AsyncRelayChoiceState`, `AsyncSwitchState` → `AsyncRelaySwitchState`. Behavior and constructors are unchanged, and the `.If(predicate)` / `.Switch(selector)` DSL paths still build them. **No obsolete forwarding aliases exist**: the old names are reused in this same release for the new data-built states, so an alias would silently compile old code into a state that means something else. Update the type names; the compiler error is the migration instruction. ### Runtime (staged NxGraph core) +- Sub-graph ports: the machine-wrapping composites — nested machines (both runtimes), the history states, and the parallel family per region — accept an optional `SubGraphPorts` declaration (`SubGraphPorts.OwnBoard().In(source, childKey).Out(childKey, parentKey)`; DSL: a `ports` argument on all four `.SubGraph` overloads and `ParallelRegion` entries on `.Parallel`). Its presence makes the composite run the child graph on the child's **own** Graph-scoped board, created from the child's declared schema and substituted at stamp time — sibling sub-graphs stop colliding on same-named keys and a child stops seeing the parent's whole board. Inputs (literal or parent-key sources) apply in declaration order at every fresh child start after the board resets to its registered defaults; a history lift-back re-entry applies nothing. Outputs copy back in declaration order at the child's terminal, success and failure alike; several regions targeting one parent key resolve in region order. Construction rejections name the key (no child Graph schema, foreign target/source keys, Node-scoped parent-side keys); port application is typed copies, 0 B on both runtimes. Owned boards are durable artifacts: `EnumerateOwnedBoards()` walks every owning composite with node-index-path identity so hosts persist each board with `BlackboardSerializer` and restore into a fresh machine's enumeration before `ResumeDeep`. Validator: Info on owns-board presence, Warning on colliding output targets (across parallel regions included), best-effort Warning on an input the child never reads statically; the conflicting-child-schema warning no longer fires for board-owning composites. +- Serialization payload version 12: sub-graph ports ride the wire — the subgraph entries gain the owns-board flag plus a ports list, composites carry sparse per-region ports, and each port rides as direction, source key name or field-model literal, target name, and the runtime-stable value type name. Everything rebuilds name-bound; a deserialized child graph carries no schema, so the host binds a Graph-scoped board on the rebuilt child machine to supply the board to own. Pre-v12 payloads read shared-board and port-free. +- Hierarchical outcomes: the machine-wrapping single-child composites — nested machines (`.SubGraph(child)` / `.SubGraph(mode, child)`) and the history states — accept optional `outcomeCode` (`BlackboardKey`) and `outcomeName` (`BlackboardKey`) keys at construction. When the child run reaches a terminal, the composite writes the child machine's `LastOutcome` code and name through its stamped parent-level context, before returning its own `Result`, so a parent branches on *which* outcome a sub-graph ended with using the ordinary data-built `SwitchState`/`ChoiceState`. A terminal with no declared outcome publishes `0` and the empty string; failure terminals publish too; a history composite publishes only at genuine terminals — a lift-back re-entry publishes nothing until the resumed session ends. Node-scoped keys are rejected at construction naming the key, and the validator warns when a key is declared but the child graph declares no outcome codes. +- Serialization payload version 11: the declarations ride the existing subgraph/composite payload entries as key names; deserialized composites rebuild name-bound and resolve against the machine's bound boards per publish, with targeted miss/type-mismatch errors. Pre-v11 payloads read outcome-key-free. - **Data-built branching**: `ChoiceState(conditions, ConditionMatch.All|Any, trueTarget, falseTarget)` and `SwitchState(key, literal cases, defaultTarget)` decide from data instead of a closure, so a branching graph rides the serialization payload with zero serializer options and survives suspend/resume. Conditions live in `NxGraph.Conditions` (`ICondition`, `KeyEquals`, `IsTrue`, `Not`), reuse the behavior model's `BehaviorContext`, and reuse none of the fault model — a false condition is a decision, never a node failure. Author with `.If(condition)`, `.If(ConditionMatch.Any, …)`, and `.Switch(blackboardKey).Case(value, …).Default(…).End()`; a switch is a lookup (literal cases, duplicates rejected at build time) and ordered first-match-wins rules lower to a chain of choices. - Typed event entry points: `GraphBuilder.StartWithEvents()` builds one graph with N externally-raised entry chains (`.On(key, e => chain)`, `.Otherwise(...)`); raise with `Execute(evt)` / `ExecuteAsync(evt, ct)` / `StepAsync(evt, ct)`. Event payloads deliver through Graph-scoped blackboard keys, so payload durability falls out of the existing blackboard artifacts. - Declarative behaviors: author a node as an ordered, fail-fast list of small data-shaped behaviors (`.ToBehaviors(...)` / `.ToBehaviorsAsync(...)`, plus typed-agent variants). `BlackboardValue` binds each field to a literal or a blackboard key; the standard set ships `Log` and `SetValue`, and `Repeat` adds bounded sub-node iteration in both runtimes.