unspaghettit 0.2.0 → 0.4.0

package/src/features/behavior-model/domain/services/TransitionCatalog.ts

@@ -1,174 +1,174 @@
-import type { Feature } from '../entities/Feature';
-
-/**
- * Where a surface→surface transition was authored. Used by the UI to deep-link
- * back to the source and to show *why* a navigation can happen.
- */
-export type TransitionOrigin =
-  | 'declared'
-  | 'action_effect'
-  | 'action_rule_effect'
-  | 'surface_rule_effect';
-
-export type TransitionSource = {
-  readonly surfaceId: string;
-  readonly surfaceName: string;
-  readonly actionId?: string;
-  readonly actionName?: string;
-  readonly origin: TransitionOrigin;
-  /** Optional rationale (rule.description, transition.label, …) */
-  readonly description?: string;
-};
-
-export type TransitionEntry = {
-  readonly fromSurfaceId: string;
-  readonly fromSurfaceName: string;
-  readonly toSurfaceId: string;
-  readonly toSurfaceName: string;
-  readonly sources: readonly TransitionSource[];
-};
-
-/**
- * Walk every surface and collect every authored transition between two
- * surfaces, regardless of where it lives in the model:
- *  - `surface.transitions` (declared navigation hints)
- *  - action default effects of type `transition_surface`
- *  - action rule effects of type `transition_surface`
- *  - surface-level rule effects of type `transition_surface`
- *
- * Edges with the same (from, to) pair collapse into one entry whose
- * `sources` lists every contribution. Output is sorted by source surface
+import type { Feature } from '../entities/Feature';
+
+/**
+ * Where a surface→surface transition was authored. Used by the UI to deep-link
+ * back to the source and to show *why* a navigation can happen.
+ */
+export type TransitionOrigin =
+  | 'declared'
+  | 'action_effect'
+  | 'action_rule_effect'
+  | 'surface_rule_effect';
+
+export type TransitionSource = {
+  readonly surfaceId: string;
+  readonly surfaceName: string;
+  readonly actionId?: string;
+  readonly actionName?: string;
+  readonly origin: TransitionOrigin;
+  /** Optional rationale (rule.description, transition.label, …) */
+  readonly description?: string;
+};
+
+export type TransitionEntry = {
+  readonly fromSurfaceId: string;
+  readonly fromSurfaceName: string;
+  readonly toSurfaceId: string;
+  readonly toSurfaceName: string;
+  readonly sources: readonly TransitionSource[];
+};
+
+/**
+ * Walk every surface and collect every authored transition between two
+ * surfaces, regardless of where it lives in the model:
+ *  - `surface.transitions` (declared navigation hints)
+ *  - action default effects of type `transition_surface`
+ *  - action rule effects of type `transition_surface`
+ *  - surface-level rule effects of type `transition_surface`
+ *
+ * Edges with the same (from, to) pair collapse into one entry whose
+ * `sources` lists every contribution. Output is sorted by source surface
  * order (matches the feature editor's surface list), then by target surface name.
- */
-export const buildTransitionCatalog = (
-  feature: Feature
-): readonly TransitionEntry[] => {
-  const surfaceById = new Map<string, { name: string; index: number }>();
-  feature.surfaces.forEach((s, index) => {
-    surfaceById.set(s.id as unknown as string, { name: s.name, index });
-  });
-
-  type Acc = { sources: TransitionSource[]; fromIndex: number };
-  const byEdge = new Map<string, Acc>();
-
-  const targetExists = (id: string | undefined): id is string =>
-    id !== undefined && surfaceById.has(id);
-
-  const push = (
-    fromId: string,
-    toId: string,
-    source: TransitionSource
-  ) => {
-    if (!targetExists(toId)) return; // dangling targets don't make a real edge
-    const key = `${fromId}__${toId}`;
-    let acc = byEdge.get(key);
-    if (!acc) {
-      acc = { sources: [], fromIndex: surfaceById.get(fromId)?.index ?? 0 };
-      byEdge.set(key, acc);
-    }
-    acc.sources.push(source);
-  };
-
-  for (const surface of feature.surfaces) {
-    const fromId = surface.id as unknown as string;
-    const fromName = surface.name;
-
-    for (const transition of surface.transitions) {
-      push(fromId, transition.target as unknown as string, {
-        surfaceId: fromId,
-        surfaceName: fromName,
-        origin: 'declared',
-        description: transition.label ?? transition.description
-      });
-    }
-
-    for (const cap of surface.actions) {
-      // Default effects.
-      for (const effect of cap.effects) {
-        if (effect.type === 'transition_surface') {
-          push(fromId, effect.target as unknown as string, {
-            surfaceId: fromId,
-            surfaceName: fromName,
-            actionId: cap.id as unknown as string,
-            actionName: cap.name,
-            origin: 'action_effect',
-            description: effect.description
-          });
-        }
-      }
-      // Rule effects.
-      for (const rule of cap.rules) {
-        if (rule.effect.type === 'transition_surface') {
-          push(fromId, rule.effect.target as unknown as string, {
-            surfaceId: fromId,
-            surfaceName: fromName,
-            actionId: cap.id as unknown as string,
-            actionName: cap.name,
-            origin: 'action_rule_effect',
-            description: rule.description
-          });
-        }
-      }
-    }
-
-    for (const rule of surface.rules) {
-      if (rule.effect.type === 'transition_surface') {
-        push(fromId, rule.effect.target as unknown as string, {
-          surfaceId: fromId,
-          surfaceName: fromName,
-          origin: 'surface_rule_effect',
-          description: rule.description
-        });
-      }
-    }
-  }
-
-  const entries: TransitionEntry[] = [];
-  for (const [key, acc] of byEdge) {
-    const [fromId, toId] = key.split('__') as [string, string];
-    const from = surfaceById.get(fromId);
-    const to = surfaceById.get(toId);
-    if (!from || !to) continue;
-    entries.push({
-      fromSurfaceId: fromId,
-      fromSurfaceName: from.name,
-      toSurfaceId: toId,
-      toSurfaceName: to.name,
-      sources: acc.sources
-    });
-  }
-  entries.sort((a, b) => {
-    const fa = surfaceById.get(a.fromSurfaceId)?.index ?? 0;
-    const fb = surfaceById.get(b.fromSurfaceId)?.index ?? 0;
-    if (fa !== fb) return fa - fb;
-    const ta = surfaceById.get(a.toSurfaceId)?.index ?? 0;
-    const tb = surfaceById.get(b.toSurfaceId)?.index ?? 0;
-    return ta - tb;
-  });
-  return entries;
-};
-
-export type TransitionGroup = {
-  readonly fromSurfaceId: string;
-  readonly fromSurfaceName: string;
-  readonly transitions: readonly TransitionEntry[];
-};
-
-export const groupTransitionCatalog = (
-  entries: readonly TransitionEntry[]
-): readonly TransitionGroup[] => {
-  const map = new Map<string, TransitionGroup>();
-  for (const entry of entries) {
-    let group = map.get(entry.fromSurfaceId);
-    if (!group) {
-      group = {
-        fromSurfaceId: entry.fromSurfaceId,
-        fromSurfaceName: entry.fromSurfaceName,
-        transitions: []
-      };
-      map.set(entry.fromSurfaceId, group);
-    }
-    (group.transitions as TransitionEntry[]).push(entry);
-  }
-  return Array.from(map.values());
-};
+ */
+export const buildTransitionCatalog = (
+  feature: Feature
+): readonly TransitionEntry[] => {
+  const surfaceById = new Map<string, { name: string; index: number }>();
+  feature.surfaces.forEach((s, index) => {
+    surfaceById.set(s.id as unknown as string, { name: s.name, index });
+  });
+
+  type Acc = { sources: TransitionSource[]; fromIndex: number };
+  const byEdge = new Map<string, Acc>();
+
+  const targetExists = (id: string | undefined): id is string =>
+    id !== undefined && surfaceById.has(id);
+
+  const push = (
+    fromId: string,
+    toId: string,
+    source: TransitionSource
+  ) => {
+    if (!targetExists(toId)) return; // dangling targets don't make a real edge
+    const key = `${fromId}__${toId}`;
+    let acc = byEdge.get(key);
+    if (!acc) {
+      acc = { sources: [], fromIndex: surfaceById.get(fromId)?.index ?? 0 };
+      byEdge.set(key, acc);
+    }
+    acc.sources.push(source);
+  };
+
+  for (const surface of feature.surfaces) {
+    const fromId = surface.id as unknown as string;
+    const fromName = surface.name;
+
+    for (const transition of surface.transitions) {
+      push(fromId, transition.target as unknown as string, {
+        surfaceId: fromId,
+        surfaceName: fromName,
+        origin: 'declared',
+        description: transition.label ?? transition.description
+      });
+    }
+
+    for (const cap of surface.actions) {
+      // Default effects.
+      for (const effect of cap.effects) {
+        if (effect.type === 'transition_surface') {
+          push(fromId, effect.target as unknown as string, {
+            surfaceId: fromId,
+            surfaceName: fromName,
+            actionId: cap.id as unknown as string,
+            actionName: cap.name,
+            origin: 'action_effect',
+            description: effect.description
+          });
+        }
+      }
+      // Rule effects.
+      for (const rule of cap.rules) {
+        if (rule.effect.type === 'transition_surface') {
+          push(fromId, rule.effect.target as unknown as string, {
+            surfaceId: fromId,
+            surfaceName: fromName,
+            actionId: cap.id as unknown as string,
+            actionName: cap.name,
+            origin: 'action_rule_effect',
+            description: rule.description
+          });
+        }
+      }
+    }
+
+    for (const rule of surface.rules) {
+      if (rule.effect.type === 'transition_surface') {
+        push(fromId, rule.effect.target as unknown as string, {
+          surfaceId: fromId,
+          surfaceName: fromName,
+          origin: 'surface_rule_effect',
+          description: rule.description
+        });
+      }
+    }
+  }
+
+  const entries: TransitionEntry[] = [];
+  for (const [key, acc] of byEdge) {
+    const [fromId, toId] = key.split('__') as [string, string];
+    const from = surfaceById.get(fromId);
+    const to = surfaceById.get(toId);
+    if (!from || !to) continue;
+    entries.push({
+      fromSurfaceId: fromId,
+      fromSurfaceName: from.name,
+      toSurfaceId: toId,
+      toSurfaceName: to.name,
+      sources: acc.sources
+    });
+  }
+  entries.sort((a, b) => {
+    const fa = surfaceById.get(a.fromSurfaceId)?.index ?? 0;
+    const fb = surfaceById.get(b.fromSurfaceId)?.index ?? 0;
+    if (fa !== fb) return fa - fb;
+    const ta = surfaceById.get(a.toSurfaceId)?.index ?? 0;
+    const tb = surfaceById.get(b.toSurfaceId)?.index ?? 0;
+    return ta - tb;
+  });
+  return entries;
+};
+
+export type TransitionGroup = {
+  readonly fromSurfaceId: string;
+  readonly fromSurfaceName: string;
+  readonly transitions: readonly TransitionEntry[];
+};
+
+export const groupTransitionCatalog = (
+  entries: readonly TransitionEntry[]
+): readonly TransitionGroup[] => {
+  const map = new Map<string, TransitionGroup>();
+  for (const entry of entries) {
+    let group = map.get(entry.fromSurfaceId);
+    if (!group) {
+      group = {
+        fromSurfaceId: entry.fromSurfaceId,
+        fromSurfaceName: entry.fromSurfaceName,
+        transitions: []
+      };
+      map.set(entry.fromSurfaceId, group);
+    }
+    (group.transitions as TransitionEntry[]).push(entry);
+  }
+  return Array.from(map.values());
+};

package/src/features/behavior-model/domain/value-objects/Effect.ts

@@ -10,7 +10,11 @@ export type EffectType =
   | 'emit_event'
   | 'block_action'
   | 'allow_action'
-  | 'transition_surface';
+  | 'transition_surface'
+  | 'append_to_list'
+  | 'remove_from_list'
+  | 'update_list_item'
+  | 'advance_time';
 
 /**
  * Writes `value` (or the result of `value` if it is an `Expression`) to the
@@ -61,13 +65,94 @@ export type TransitionSurfaceEffect = {
   readonly description?: string;
 };
 
+/**
+ * Predicate that selects elements inside an array-typed state path. Matches
+ * an object element when `element[field]` deep-equals the resolved `equals`
+ * value (an Expression so the comparand can be a param, another state path,
+ * or a literal). Used by `remove_from_list` and `update_list_item` so a modeler
+ * can say "the cart line whose productId equals the `productId` parameter"
+ * without numeric indices (which state paths can't express).
+ */
+export type ListItemMatch = {
+  readonly field: string;
+  readonly equals: StateValue | Expression;
+};
+
+/**
+ * Appends `item` to the array at `path`. When the path holds no array yet
+ * (undefined / wrong type) the engine treats it as an empty list and writes
+ * `[item]`, so "add the first item to an empty cart" needs no separate seed.
+ * `item` may be an Expression (e.g. a `param` carrying the object to push, or
+ * an arithmetic result for an array of numbers). The grow half of collection
+ * support that `set_state` (whole-value overwrite) could never express.
+ */
+export type AppendToListEffect = {
+  readonly id: EffectId;
+  readonly type: 'append_to_list';
+  readonly path: StatePath;
+  readonly item: StateValue | Expression;
+  readonly description?: string;
+};
+
+/**
+ * Removes elements from the array at `path`. Selector is exactly one of:
+ *   - `where`: drop object elements matching the field predicate.
+ *   - `value`: drop elements deep-equal to the resolved value (arrays of
+ *     scalars, or whole-object equality).
+ * With neither selector the effect is a no-op — we never implicitly clear a
+ * whole list (use `set_state` with `[]` for that, explicitly).
+ */
+export type RemoveFromListEffect = {
+  readonly id: EffectId;
+  readonly type: 'remove_from_list';
+  readonly path: StatePath;
+  readonly where?: ListItemMatch;
+  readonly value?: StateValue | Expression;
+  readonly description?: string;
+};
+
+/**
+ * Sets `field` to the resolved `value` on every object element of the array
+ * at `path` that matches the `where` predicate. The in-place mutation half of
+ * collection support: "set qty to the `qty` param on the cart line whose
+ * productId matches" without rebuilding the whole array. Set multiple fields
+ * with multiple effects.
+ */
+export type UpdateListItemEffect = {
+  readonly id: EffectId;
+  readonly type: 'update_list_item';
+  readonly path: StatePath;
+  readonly where: ListItemMatch;
+  readonly field: string;
+  readonly value: StateValue | Expression;
+  readonly description?: string;
+};
+
+/**
+ * Advances the simulation clock (`clock.now`) forward by `by` logical time
+ * units. Time never runs backward — a non-positive delta is a no-op. Lets an
+ * action model "extend the session by 30", or a Tick action push time so a
+ * deadline rule ("now >= token.expiresAt → expire") becomes reachable. `by`
+ * may be an Expression (e.g. a `param` carrying the duration).
+ */
+export type AdvanceTimeEffect = {
+  readonly id: EffectId;
+  readonly type: 'advance_time';
+  readonly by: StateValue | Expression;
+  readonly description?: string;
+};
+
 export type Effect =
   | SetStateEffect
   | ShowMessageEffect
   | EmitEventEffect
   | BlockActionEffect
   | AllowActionEffect
-  | TransitionSurfaceEffect;
+  | TransitionSurfaceEffect
+  | AppendToListEffect
+  | RemoveFromListEffect
+  | UpdateListItemEffect
+  | AdvanceTimeEffect;
 
 export const ALL_EFFECT_TYPES: readonly EffectType[] = [
   'set_state',
@@ -75,7 +160,11 @@ export const ALL_EFFECT_TYPES: readonly EffectType[] = [
   'emit_event',
   'block_action',
   'allow_action',
-  'transition_surface'
+  'transition_surface',
+  'append_to_list',
+  'remove_from_list',
+  'update_list_item',
+  'advance_time'
 ];
 
 export const effectTypeLabel = (t: EffectType): string => {
@@ -92,6 +181,14 @@ export const effectTypeLabel = (t: EffectType): string => {
       return 'Allow action';
     case 'transition_surface':
       return 'Transition to surface';
+    case 'append_to_list':
+      return 'Append to list';
+    case 'remove_from_list':
+      return 'Remove from list';
+    case 'update_list_item':
+      return 'Update list item';
+    case 'advance_time':
+      return 'Advance time';
   }
 };
 

package/src/features/behavior-model/domain/value-objects/EntityFieldType.ts

@@ -1,57 +1,57 @@
-/**
- * Field types for Entity entities. Broader than `StateType` because Entity is
- * documentation of arbitrary JSON-shaped data. Including dates, timestamps,
- * raw JSON blobs, and the null literal.
- */
-export type EntityFieldType =
-  | 'string'
-  | 'number'
-  | 'boolean'
-  | 'enum'
-  | 'object'
-  | 'array'
-  | 'date'
-  | 'timestamp'
-  | 'null'
-  | 'json';
-
-export const ALL_DATA_FIELD_TYPES: readonly EntityFieldType[] = [
-  'string',
-  'number',
-  'boolean',
-  'enum',
-  'object',
-  'array',
-  'date',
-  'timestamp',
-  'null',
-  'json'
-];
-
-export const dataFieldTypeLabel = (t: EntityFieldType): string => {
-  switch (t) {
-    case 'string':
-      return 'string';
-    case 'number':
-      return 'number';
-    case 'boolean':
-      return 'boolean';
-    case 'enum':
-      return 'enum';
-    case 'object':
-      return 'object';
-    case 'array':
-      return 'array';
-    case 'date':
-      return 'date';
-    case 'timestamp':
-      return 'timestamp';
-    case 'null':
-      return 'null';
-    case 'json':
-      return 'json';
-  }
-};
-
-export const dataFieldTypeIsContainer = (t: EntityFieldType): boolean =>
-  t === 'object' || t === 'array';
+/**
+ * Field types for Entity entities. Broader than `StateType` because Entity is
+ * documentation of arbitrary JSON-shaped data. Including dates, timestamps,
+ * raw JSON blobs, and the null literal.
+ */
+export type EntityFieldType =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'enum'
+  | 'object'
+  | 'array'
+  | 'date'
+  | 'timestamp'
+  | 'null'
+  | 'json';
+
+export const ALL_DATA_FIELD_TYPES: readonly EntityFieldType[] = [
+  'string',
+  'number',
+  'boolean',
+  'enum',
+  'object',
+  'array',
+  'date',
+  'timestamp',
+  'null',
+  'json'
+];
+
+export const dataFieldTypeLabel = (t: EntityFieldType): string => {
+  switch (t) {
+    case 'string':
+      return 'string';
+    case 'number':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'enum':
+      return 'enum';
+    case 'object':
+      return 'object';
+    case 'array':
+      return 'array';
+    case 'date':
+      return 'date';
+    case 'timestamp':
+      return 'timestamp';
+    case 'null':
+      return 'null';
+    case 'json':
+      return 'json';
+  }
+};
+
+export const dataFieldTypeIsContainer = (t: EntityFieldType): boolean =>
+  t === 'object' || t === 'array';

package/src/features/behavior-model/domain/value-objects/Expression.ts

@@ -4,6 +4,7 @@ import type { StateValue } from './StateValue';
 import {
   isCompositeCondition,
   isParamLeft,
+  isQuantifierCondition,
   type RuleCondition
 } from './RuleCondition';
 import type { Operator } from './Operator';
@@ -167,6 +168,24 @@ export const evaluateConditionInternal = (
   context: EvaluationContext
 ): boolean => {
   if (condition === undefined || condition === null) return true;
+  if (isQuantifierCondition(condition)) {
+    const arr = readPath(context.snapshot, condition.overPath);
+    // Missing / non-array source: ∀ is vacuously true, ∃ is false.
+    if (!Array.isArray(arr)) return condition.kind === 'all_match';
+    for (const element of arr) {
+      // Bind the current element under `as` so the body reads `as` (scalars)
+      // or `as.field` (objects) while still seeing every outer state path.
+      const scoped: StateSnapshot = { ...context.snapshot, [condition.as]: element };
+      const held = evaluateConditionInternal(condition.where, {
+        ...context,
+        snapshot: scoped
+      });
+      if (condition.kind === 'all_match' && !held) return false;
+      if (condition.kind === 'any_match' && held) return true;
+    }
+    // Walked every element: all held ⇒ all_match true; none held ⇒ any_match false.
+    return condition.kind === 'all_match';
+  }
   if (isCompositeCondition(condition)) {
     if (condition.kind === 'not') {
       return !evaluateConditionInternal(condition.condition, context);
@@ -192,8 +211,9 @@ export const evaluateConditionInternal = (
 
 // Structural equality for two StateValue-shaped values. Inlined here (not
 // imported from RuleEvaluator) so this module stays an evaluator with no
-// upward dependency.
-const deepEqualValue = (a: unknown, b: unknown): boolean => {
+// upward dependency. Exported so collection-mutation effects (remove/update by
+// match) compare element fields with the exact same semantics conditions use.
+export const deepEqualValue = (a: unknown, b: unknown): boolean => {
   if (a === b) return true;
   if (a === null || b === null) return false;
   if (typeof a !== typeof b) return false;