Check the declared type when a graph writes a typed variable (#271)

A list variable with an item type only kept its shape in the editor.
A graph could write any list into it at runtime, and the List node had
no type at all. Now the declaration decides what a write may store.

- Writing a list into a typed list variable leaves out every item that
  does not have exactly the fields of the type. The rest is written and
  the console names each item that was left out, like Add item does.
- The same rule holds for typed list fields inside a struct variable
  and for lists inside typed items, at any depth.
- A typed struct variable refuses a struct with a field the type does
  not have, and a value that is no struct. A struct with missing fields
  still merges in as before, so a partial Pack keeps working.
- The check runs in the Variables node (own variables and Variables
  assets) and in the Properties node when it sets a behavior variable
  of another object.
- Ports learn their declaration through GraphLookup: what a variable
  declares about its type, and which behavior owns a graph. The rule
  itself lives in the new src/core/graph/typedValues.ts, fitsType moved
  there from SetItem.
- The List node gets a Type setting. With a type its items are shaped
  and marked, follow the struct asset, count when the type is deleted
  and offer Split into fields in For each. The mark never reaches the
  running game.
- A type on a List node holding something other than structs is
  refused with a console line.
- Setting the List node back to None removes the marks, unlike a list
  variable. A node list has no per-item type row, so marked items could
  never be freed there. Undo brings everything back.
- tests/core/kinds.test.ts looked for the value as the first parameter
  of a literal. Type now comes first on the List node, so the test
  finds the value by its key.

Tests:
- Gate: 198 files, 2869 tests (2856 + 13), CHECK EXIT 0
- e2e 55: 19 checks (+55j write at runtime, +2 for 55k List node)
- e2e 54: 16 checks, smokes 24 / 19 / 21
- Five mutations, each fails between 1 and 4 tests
- e2e total 1606 is computed (1603 + 3), no full run

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/core/graph/NodeRegistry.ts

@@ -2,7 +2,7 @@ import { isList, type ListValue, type PropertyBag, type PropertyValue } from '..
 import { isKindWith, plainKindOf } from '../properties/kinds';
 import { flatDef, type PropertyDef } from '../properties/PropertySchema';
 import type { DeclaredPort, Graph, GraphNode, PortType } from './Graph';
-import type { GraphLookup } from './lookup';
+import type { GraphLookup, ValueTyping } from './lookup';
 import type { NodeContext } from './NodeContext';
 import type { SharedPortGroup } from './portTypes';
 import { asList, namedValue, type Value } from './values';
@@ -25,6 +25,8 @@ export interface PortDef {
    * only the pin says what currently flows in. Set by `drawnDef`, read by `NodeView`, nowhere else.
    */
   paintType?: PortType;
+  /** On a port writing a declared variable: what the written value is held to (#271). */
+  typing?: ValueTyping;
 }
 
 /**
@@ -115,7 +117,7 @@ export interface NodeDef {
    */
   declaresPorts?: 'inputs' | 'outputs' | 'both';
   /** How a declared port becomes a port; without it, named after its key and typed by its kind. */
-  declaredPort?(port: DeclaredPort, node: GraphNode): PortDef;
+  declaredPort?(port: DeclaredPort, node: GraphNode, graph: Graph, lookup: GraphLookup): PortDef;
   /**
    * Edges between two such nodes are transitions: drawn as a straight arrow instead of the usual
    * curve, and hung on ports that are never shown. A transition graph is read as directed steps

src/core/graph/lookup.ts

@@ -38,7 +38,8 @@ export interface StateMachine {
 /**
  * What a node may look up in the project around its graph: the behaviors it can run, the state
  * machines it can read, the curves a `Lerp` eases along (#247) and the struct types `Add item`
- * checks (#254). One handle, so no caller can resolve a node with half of it.
+ * checks (#254), and what a variable written by a graph is held to (#271). One handle, so no caller
+ * can resolve a node with half of it.
  */
 export interface GraphLookup {
   behavior(assetId: string): BehaviorProgram | null;
@@ -48,11 +49,27 @@ export interface GraphLookup {
   structType(assetId: string): StructShape | null;
   /** A texture's, frame's or pixel-art frame's own size in pixels; null for no picture. */
   textureSize(pictureId: string): { w: number; h: number } | null;
+  /** The asset whose graph this is, `''` for none. */
+  ownerOf(graph: Graph): string;
+  /** What a variable of that asset declares about the structs it holds (#271); none for nothing typed. */
+  variableTyping(assetId: string, key: string): ValueTyping | undefined;
 }
 
 export interface StructShape {
   name: string;
   fields: readonly string[];
+  /** What the type's fields declare in turn, for those that declare anything. */
+  inner: Readonly<Record<string, ValueTyping>>;
+}
+
+/**
+ * What a written value is held to (#271): the Struct asset it is, the one every item of it is, and
+ * what its fields declare. Only the ids travel; a run asks `structType` for the rest.
+ */
+export interface ValueTyping {
+  structType?: string;
+  itemType?: string;
+  fields?: Readonly<Record<string, ValueTyping>>;
 }
 
 export const NO_LOOKUP: GraphLookup = {
@@ -61,4 +78,6 @@ export const NO_LOOKUP: GraphLookup = {
   curve: () => null,
   structType: () => null,
   textureSize: () => null,
+  ownerOf: () => '',
+  variableTyping: () => undefined,
 };

src/core/graph/nested.ts

@@ -178,7 +178,7 @@ function shapedDef(
     return shared ? withSharedType(def, shared, node, graph, lookup) : def;
   const own = (side: 'inputs' | 'outputs') =>
     declaredOn(def, node.ports ?? [], side).map((p) =>
-      def.declaredPort ? def.declaredPort(p, node) : portDefOf(p),
+      def.declaredPort ? def.declaredPort(p, node, graph, lookup) : portDefOf(p),
     );
   const grown = def.derivePorts?.({ node, graph, lookup }) ?? {};
   const side = (key: 'inputs' | 'outputs') => {

src/core/graph/nodes/data/AddItem.ts

@@ -3,8 +3,9 @@ import { itemKindOf } from '../../../properties/listItems';
 import { STRUCT_TYPE_SETTING } from '../../nested';
 import type { NodeDef } from '../../NodeRegistry';
 import { asList, asNumber, asString, asValueItem, type ValueList } from '../../values';
+import { fitsType } from '../../typedValues';
 import { any, int, list } from '../shared';
-import { fitsType, fitToSlot } from './SetItem';
+import { fitToSlot } from './SetItem';
 
 export const AddItem: NodeDef = {
   type: 'AddItem',

src/core/graph/nodes/data/Properties.ts

@@ -1,12 +1,15 @@
+import { textOf } from '../../../model/Properties';
 import { collapsedTitle, PROPERTIES } from '../../nested';
 import type { NodeDef } from '../../NodeRegistry';
 import {
+  OBJECT_BEHAVIOR_PARAM,
   OBJECT_BEHAVIOR_SETTING,
   OBJECT_TYPE_SETTING,
   propertyPort,
   propertyTargetOf,
 } from '../../propertyPorts';
-import { objectsOf, readLive, writePort } from '../../liveObjects';
+import { objectsOf, readLive } from '../../liveObjects';
+import { writeDeclared } from '../../typedValues';
 import { asEntity } from '../../values';
 import { exec, obj } from '../shared';
 
@@ -22,7 +25,13 @@ export const Properties: NodeDef = {
   params: [OBJECT_TYPE_SETTING, OBJECT_BEHAVIOR_SETTING],
   hiddenParams: (params) => (propertyTargetOf(params) === 'behavior' ? [] : [OBJECT_BEHAVIOR_SETTING.key]),
   declaresPorts: 'both',
-  declaredPort: (port, node) => propertyPort(port, node.params),
+  declaredPort: (port, node, _graph, lookup) => {
+    const def = propertyPort(port, node.params);
+    const onBehavior = propertyTargetOf(node.params) === 'behavior';
+    const behavior = textOf(node.params[OBJECT_BEHAVIOR_PARAM] ?? '');
+    const typing = onBehavior && behavior ? lookup.variableTyping(behavior, port.key) : undefined;
+    return typing ? { ...def, typing } : def;
+  },
   derivePorts: ({ node }) => {
     const ports = node.ports ?? [];
     const shape = ports.some((p) => p.write) ? { inputs: [exec()], outputs: [exec()] } : {};
@@ -32,11 +41,12 @@ export const Properties: NodeDef = {
     const target = asEntity(input('object'));
     return target ? readLive(target.props, def.outputs, objectsOf(ctx, target)) : {};
   },
-  run: (_ctx, inputs, _params, def) => {
+  run: (ctx, inputs, _params, def, _entry, lookup) => {
     const target = asEntity(inputs.object);
     if (target)
       for (const port of def.inputs)
-        if (port.type !== 'exec' && port.key !== 'object') writePort(target.props, port, inputs[port.key]);
+        if (port.type !== 'exec' && port.key !== 'object')
+          writeDeclared(target.props, port, inputs[port.key], lookup, (m) => ctx.log(m));
     return { next: 'exec' };
   },
 };

src/core/graph/nodes/data/SetItem.ts

@@ -1,9 +1,9 @@
-import { isStruct, type PropertyValue, tagOf, textOf } from '../../../model/Properties';
+import { type PropertyValue, textOf } from '../../../model/Properties';
 import { itemKindOf, itemLike, makeItem } from '../../../properties/listItems';
-import type { StructShape } from '../../lookup';
 import { STRUCT_TYPE_SETTING } from '../../nested';
 import type { NodeDef } from '../../NodeRegistry';
-import { asList, asNumber, asString, asValueItem, isEntity, type Value, type ValueList } from '../../values';
+import { fitsType } from '../../typedValues';
+import { asList, asNumber, asString, asValueItem, isEntity, type ValueList } from '../../values';
 import { any, int, list } from '../shared';
 
 export const SetItem: NodeDef = {
@@ -34,16 +34,6 @@ export const SetItem: NodeDef = {
   params: [STRUCT_TYPE_SETTING],
 };
 
-/**
- * A run knows a struct only by its fields (#254): one fits a type when it has exactly the type's
- * field names – none missing, none more.
- */
-export function fitsType(value: Value | undefined, type: StructShape): boolean {
-  if (isEntity(value) || !isStruct(value) || tagOf(value) !== undefined) return false;
-  const keys = Object.keys(value);
-  return keys.length === type.fields.length && type.fields.every((field) => field in value);
-}
-
 /** `value` as the kind `slot` holds, the way `Set item` and `Add item` write into a list. */
 export function fitToSlot(slot: ValueList[number] | undefined, value: ValueList[number]): ValueList[number] {
   // An object has no kind to keep and none to take on, so it is written as it is (#157).

src/core/graph/nodes/data/literals.ts

@@ -1,5 +1,7 @@
+import { withoutItemTypes } from '../../../model/Properties';
 import { KIND, kindLabel, type VariableKind } from '../../../properties/kinds';
 import { coerceValue, flatDef, type PropertyDef } from '../../../properties/PropertySchema';
+import { STRUCT_TYPE_SETTING } from '../../nested';
 import type { NodeDef } from '../../NodeRegistry';
 
 /** A node handing out one constant of a kind: its one setting, edited as that kind, is its output. */
@@ -18,7 +20,10 @@ function literal(type: string, kind: Exclude<VariableKind, 'struct' | 'object'>,
     inputs: [],
     outputs: [{ key: 'value', label: 'value', type: KIND[kind].travels }],
     params: [value],
-    run: (_ctx, _inputs, params) => ({ outputs: { value: coerceValue(value, params.value ?? value.default) } }),
+    // The items of a typed list carry their type's mark in the node, and a run never sees one (#271).
+    run: (_ctx, _inputs, params) => ({
+      outputs: { value: withoutItemTypes(coerceValue(value, params.value ?? value.default)) },
+    }),
   };
 }
 
@@ -55,8 +60,10 @@ export const AssetLiteral = literal(
   'asset',
   'A constant placeable asset, for a "Spawn" to place or an "Is asset" to compare with.',
 );
-export const ListLiteral = literal(
+const list = literal(
   'List',
   'list',
-  'A constant list, edited item by item in the inspector – each item with its own kind.',
+  'A constant list, edited item by item in the inspector – each item with its own kind. With a type, every item is a struct of that type.',
 );
+
+export const ListLiteral: NodeDef = { ...list, params: [STRUCT_TYPE_SETTING, ...list.params] };

src/core/graph/nodes/variable/Variables.ts

@@ -1,7 +1,8 @@
 import { collapsedTitle, portDefOf, VARIABLES, VARIABLES_SETTING, variablesSourceOf } from '../../nested';
 import { type NodeDef, withInlineDefault } from '../../NodeRegistry';
-import { objectsOf, readLive, writePort } from '../../liveObjects';
+import { objectsOf, readLive } from '../../liveObjects';
 import { variableBag } from '../../sharedState';
+import { writeDeclared } from '../../typedValues';
 import { exec } from '../shared';
 
 /**
@@ -19,7 +20,12 @@ export const Variables: NodeDef = {
   outputs: [],
   params: [VARIABLES_SETTING],
   declaresPorts: 'both',
-  declaredPort: (port) => withInlineDefault(portDefOf(port)),
+  declaredPort: (port, node, graph, lookup) => {
+    const owner = variablesSourceOf(node.params) || lookup.ownerOf(graph);
+    const typing = lookup.variableTyping(owner, port.key);
+    const def = withInlineDefault(portDefOf(port));
+    return typing ? { ...def, typing } : def;
+  },
   derivePorts: ({ node }) => {
     const ports = node.ports ?? [];
     const shape = ports.some((p) => p.write) ? { inputs: [exec()], outputs: [exec()] } : {};
@@ -27,9 +33,10 @@ export const Variables: NodeDef = {
   },
   read: (ctx, params, _input, def) =>
     readLive(variableBag(ctx, variablesSourceOf(params)), def.outputs, objectsOf(ctx, ctx.self)),
-  run: (ctx, inputs, params, def) => {
+  run: (ctx, inputs, params, def, _entry, lookup) => {
     const bag = variableBag(ctx, variablesSourceOf(params));
-    for (const port of def.inputs) if (port.type !== 'exec') writePort(bag, port, inputs[port.key]);
+    for (const port of def.inputs)
+      if (port.type !== 'exec') writeDeclared(bag, port, inputs[port.key], lookup, (m) => ctx.log(m));
     return { next: 'exec' };
   },
 };

src/core/graph/typedValues.ts

@@ -0,0 +1,83 @@
+import {
+  isList,
+  isStruct,
+  type PropertyBag,
+  type PropertyValue,
+  type StructValue,
+  tagOf,
+} from '../model/Properties';
+import { writePort } from './liveObjects';
+import type { GraphLookup, StructShape, ValueTyping } from './lookup';
+import type { PortDef } from './NodeRegistry';
+import { asString, isEntity, type Value } from './values';
+
+/**
+ * A run knows a struct only by its fields (#254): one fits a type when it has exactly the type's
+ * field names – none missing, none more.
+ */
+export function fitsType(value: Value | undefined, type: StructShape): boolean {
+  if (!isPlainStruct(value)) return false;
+  const keys = Object.keys(value);
+  return keys.length === type.fields.length && type.fields.every((field) => field in value);
+}
+
+/**
+ * What a typed struct variable takes (#271): a struct may leave fields out, which keep their value
+ * as with any struct slot, but may bring none the type lacks.
+ */
+function fitsWithin(value: Value | undefined, type: StructShape): boolean {
+  return isPlainStruct(value) && Object.keys(value).every((key) => type.fields.includes(key));
+}
+
+function isPlainStruct(value: Value | undefined): value is StructValue {
+  return !isEntity(value) && isStruct(value) && tagOf(value) === undefined;
+}
+
+/**
+ * Writes what arrives on `port` into a declared variable, held to its declaration (#271): a struct
+ * bringing a field its type lacks is not written, and an item of a typed list that is no struct of
+ * the type is left out – in the variable and in every list its declaration reaches inside it. The
+ * console says so for each, in the words `Add item` uses.
+ */
+export function writeDeclared(
+  bag: PropertyBag,
+  port: PortDef,
+  value: Value | undefined,
+  lookup: GraphLookup,
+  log: (message: string) => void,
+): void {
+  const typing = port.typing;
+  const type = typing?.structType ? lookup.structType(typing.structType) : null;
+  if (type && !fitsWithin(value, type)) {
+    log(`Set ${port.key}: ${asString(value ?? null) || 'nothing'} is no ${type.name} – not set`);
+    return;
+  }
+  writePort(bag, port, value);
+  const written = bag[port.key];
+  if (!typing || written === undefined) return;
+  bag[port.key] = heldTo(written, typing, lookup, port.key, (at, item, name) =>
+    log(`Set ${at}: ${asString(item) || 'nothing'} is no ${name} – left out`),
+  );
+}
+
+type Report = (at: string, item: PropertyValue, typeName: string) => void;
+
+function heldTo(
+  value: PropertyValue,
+  typing: ValueTyping,
+  lookup: GraphLookup,
+  at: string,
+  report: Report,
+): PropertyValue {
+  if (isList(value)) {
+    const type = typing.itemType ? lookup.structType(typing.itemType) : null;
+    if (!type) return value;
+    const kept = value.filter((item) => fitsType(item, type) || (report(at, item, type.name), false));
+    return kept.map((item) => heldTo(item, { fields: type.inner }, lookup, at, report));
+  }
+  if (!typing.fields || !isPlainStruct(value)) return value;
+  const out: Record<string, PropertyValue> = { ...value };
+  for (const [key, inner] of Object.entries(typing.fields))
+    if (value[key] !== undefined) out[key] = heldTo(value[key], inner, lookup, `${at}.${key}`, report);
+  return out;
+}