unspaghettit 0.2.0 → 0.4.0

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

@@ -1,5 +1,6 @@
-import type { Effect, SetStateEffect } from '../value-objects/Effect';
+import type { Effect, ListItemMatch, SetStateEffect } from '../value-objects/Effect';
 import {
+  deepEqualValue,
   isExpression,
   resolveValueOrExpression,
   type EvaluationContext,
@@ -8,7 +9,9 @@ import {
 import { humanizeStatePath } from '../value-objects/humanize';
 import type { EffectId, SurfaceId } from '../value-objects/ids';
 import type { EventName } from '../value-objects/EventName';
-import { writePath, type StateSnapshot, type StatePath } from '../value-objects/StatePath';
+import type { StateValue } from '../value-objects/StateValue';
+import { advanceClock } from '../value-objects/SimulationClock';
+import { readPath, writePath, type StateSnapshot, type StatePath } from '../value-objects/StatePath';
 
 export type AppliedEffectRecord = {
   readonly effectId: EffectId;
@@ -96,9 +99,40 @@ const summarize = (effect: Effect): string => {
       return 'allow';
     case 'transition_surface':
       return `transition to surface ${effect.target}`;
+    case 'append_to_list':
+      return `append to ${humanizeStatePath(effect.path)}`;
+    case 'remove_from_list':
+      return `remove from ${humanizeStatePath(effect.path)}${effect.where ? ` where ${effect.where.field} matches` : ''}`;
+    case 'update_list_item':
+      return `set ${effect.field} on ${humanizeStatePath(effect.path)} items where ${effect.where.field} matches`;
+    case 'advance_time':
+      return `advance time by ${isExpression(effect.by) ? `<expr:${effect.by.kind}>` : JSON.stringify(effect.by)}`;
   }
 };
 
+/** Read the array at `path`, or `null` when the slot is absent or not an array. */
+const readArray = (snapshot: StateSnapshot, path: StatePath): readonly StateValue[] | null => {
+  const current = readPath(snapshot, path);
+  return Array.isArray(current) ? current : null;
+};
+
+/**
+ * True when `element` is an object whose `match.field` deep-equals the
+ * resolved `match.equals`. Non-object elements never match (the predicate is
+ * field-based). The comparand resolves against the running snapshot + params so
+ * "where productId equals the productId param" works.
+ */
+const elementMatches = (
+  element: StateValue,
+  match: ListItemMatch,
+  context: EvaluationContext
+): boolean => {
+  if (!element || typeof element !== 'object' || Array.isArray(element)) return false;
+  const field = (element as { [k: string]: StateValue })[match.field];
+  const target = resolveValueOrExpression(match.equals, context);
+  return deepEqualValue(field, target);
+};
+
 /**
  * Apply an effect. `parameters` defaults to empty so existing call-sites
  * (and tests that only deal with literal effects) keep working. Pass real
@@ -208,6 +242,80 @@ export const applyEffect = (
         transition: effect.target
       };
     }
+    case 'append_to_list': {
+      // List mutations follow set_state's block discipline: once a rule has
+      // blocked, no state lands.
+      if (current.blocked) {
+        return { ...current, applied: [...current.applied, record] };
+      }
+      const context: EvaluationContext = { snapshot: current.snapshot, parameters };
+      const item = resolveValueOrExpression(effect.item, context);
+      // An item that can't be resolved (missing param / non-computable expr)
+      // is skipped rather than pushing `undefined` and poisoning the array.
+      if (item === undefined) {
+        return { ...current, applied: [...current.applied, record] };
+      }
+      const existing = readArray(current.snapshot, effect.path) ?? [];
+      const nextSnapshot = writePath(current.snapshot, effect.path, [...existing, item]);
+      return { ...current, snapshot: nextSnapshot, applied: [...current.applied, record] };
+    }
+    case 'remove_from_list': {
+      if (current.blocked) {
+        return { ...current, applied: [...current.applied, record] };
+      }
+      const existing = readArray(current.snapshot, effect.path);
+      // No array → nothing to remove. Record the attempt and move on.
+      if (existing === null) {
+        return { ...current, applied: [...current.applied, record] };
+      }
+      const context: EvaluationContext = { snapshot: current.snapshot, parameters };
+      let kept: readonly StateValue[];
+      if (effect.where !== undefined) {
+        kept = existing.filter((el) => !elementMatches(el, effect.where!, context));
+      } else if (effect.value !== undefined) {
+        const target = resolveValueOrExpression(effect.value, context);
+        // Unresolvable comparand removes nothing (safer than removing all).
+        kept =
+          target === undefined ? existing : existing.filter((el) => !deepEqualValue(el, target));
+      } else {
+        // No selector: never implicitly clear the whole list.
+        kept = existing;
+      }
+      const nextSnapshot = writePath(current.snapshot, effect.path, [...kept]);
+      return { ...current, snapshot: nextSnapshot, applied: [...current.applied, record] };
+    }
+    case 'update_list_item': {
+      if (current.blocked) {
+        return { ...current, applied: [...current.applied, record] };
+      }
+      const existing = readArray(current.snapshot, effect.path);
+      if (existing === null) {
+        return { ...current, applied: [...current.applied, record] };
+      }
+      const context: EvaluationContext = { snapshot: current.snapshot, parameters };
+      const value = resolveValueOrExpression(effect.value, context);
+      // Unresolvable value → leave every element untouched (don't write undefined).
+      if (value === undefined) {
+        return { ...current, applied: [...current.applied, record] };
+      }
+      const nextArray = existing.map((el) =>
+        elementMatches(el, effect.where, context)
+          ? { ...(el as { [k: string]: StateValue }), [effect.field]: value }
+          : el
+      );
+      const nextSnapshot = writePath(current.snapshot, effect.path, nextArray);
+      return { ...current, snapshot: nextSnapshot, applied: [...current.applied, record] };
+    }
+    case 'advance_time': {
+      if (current.blocked) {
+        return { ...current, applied: [...current.applied, record] };
+      }
+      const context: EvaluationContext = { snapshot: current.snapshot, parameters };
+      const by = resolveValueOrExpression(effect.by, context);
+      // Non-numeric / unresolvable duration → no-op (advanceClock clamps).
+      const nextSnapshot = advanceClock(current.snapshot, typeof by === 'number' ? by : 0);
+      return { ...current, snapshot: nextSnapshot, applied: [...current.applied, record] };
+    }
     default: {
       // An unrecognized effect type means malformed data slipped past the
       // Zod schema (the only legitimate route into `Effect`). Falling through
@@ -218,7 +326,8 @@ export const applyEffect = (
       const unknown = effect as { type?: string };
       throw new Error(
         `EffectApplier: unknown effect type "${unknown.type ?? '<missing>'}". ` +
-          `Valid types: set_state, show_message, emit_event, block_action, allow_action, transition_surface.`
+          `Valid types: set_state, show_message, emit_event, block_action, allow_action, ` +
+          `transition_surface, append_to_list, remove_from_list, update_list_item, advance_time.`
       );
     }
   }

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

@@ -1,166 +1,166 @@
-import type { Entity, EntityField } from '../entities/Entity';
-import type { Feature } from '../entities/Feature';
-import type { EntityFieldType } from '../value-objects/EntityFieldType';
-import type { EntityFieldId, EntityId, ResourceId } from '../value-objects/ids';
-import type { StatePath } from '../value-objects/StatePath';
-import { humanizeStatePath } from '../value-objects/humanize';
-
-/**
- * Where each piece of an EffectiveEntities came from. Deduced fields are inferred
- * from state-path namespaces; declared fields were explicitly authored on a
- * Entity entity.
- */
-export type FieldSource = 'deduced' | 'declared';
-
-export type EffectiveDataField = {
-  readonly id?: EntityFieldId;
-  readonly name: string;
-  readonly path: StatePath;
-  readonly type: EntityFieldType;
-  readonly source: FieldSource;
-  /** type='object' nested fields (declared only). */
-  readonly fields?: readonly EntityField[];
-  /** type='array' element schema (declared only). */
-  readonly items?: EntityField;
-};
-
-/**
- * The unified view of a Entity entity that the UI consumes. Combines:
- *  - state-path namespaces in the feature (always present), and
- *  - any explicitly authored Entity record (optional overrides).
- *
- * "Materialized" means a `Entity` record exists in `feature.entities`. Editing
- * an unmaterialized entry should lazily create one so the metadata
- * (description, resource link, custom name) has somewhere to live.
- */
-export type EffectiveEntities = {
-  readonly id?: EntityId;
-  readonly name: string;
-  readonly namespace: string;
-  readonly description?: string;
-  readonly resourceId?: ResourceId;
-  readonly fields: readonly EffectiveDataField[];
-  readonly isMaterialized: boolean;
-  readonly usedBySurfaces: readonly string[];
-};
-
-const capitalize = (s: string): string =>
-  s.length === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1);
-
-const fieldNameFromPath = (path: string): string => {
-  const segments = path.split('.');
-  if (segments.length <= 1) return path;
-  return segments[segments.length - 1] as string;
-};
-
-/**
- * Produce the list of all Entity entities visible in the feature. Every
- * state-path namespace, enriched with metadata from any matching authored
- * `Entity` record. Authored entries with no matching state paths still appear
- * (so the user doesn't lose explicit work).
- */
-export const getEffectiveEntities = (feature: Feature): readonly EffectiveEntities[] => {
-  type DeducedAcc = {
-    readonly fields: Map<string, EffectiveDataField>;
-    readonly surfaces: Set<string>;
-  };
-  const deduced = new Map<string, DeducedAcc>();
-
-  for (const surface of feature.surfaces) {
-    for (const def of surface.stateDefinitions) {
-      const namespace = def.path.split('.')[0] ?? def.path;
-      let acc = deduced.get(namespace);
-      if (!acc) {
-        acc = { fields: new Map(), surfaces: new Set() };
-        deduced.set(namespace, acc);
-      }
-      if (!acc.fields.has(def.path)) {
-        acc.fields.set(def.path, {
-          name: fieldNameFromPath(def.path),
-          path: def.path,
-          type: def.type,
-          source: 'deduced'
-        });
-      }
-      acc.surfaces.add(surface.name);
-    }
-  }
-
-  const declaredByNamespace = new Map<string, Entity>();
-  for (const data of feature.entities) {
-    declaredByNamespace.set(data.namespace, data);
-  }
-
-  const namespaces = new Set<string>([
-    ...deduced.keys(),
-    ...declaredByNamespace.keys()
-  ]);
-
-  const results: EffectiveEntities[] = [];
-  for (const namespace of namespaces) {
-    const declared = declaredByNamespace.get(namespace);
-    const acc = deduced.get(namespace);
-
-    // Build the field map. Start with deduced fields, then layer declared
-    // fields. A declared field with the same path overrides type/name and
-    // marks the source as "declared".
-    const fieldByPath = new Map<string, EffectiveDataField>();
-    if (acc) {
-      for (const [path, f] of acc.fields) fieldByPath.set(path, f);
-    }
-    if (declared) {
-      for (const f of declared.fields) {
-        // Declared fields without a path can't surface in the effective view
-        // (they live inside an object/array and don't map to a state path).
-        if (!f.path) continue;
-        fieldByPath.set(String(f.path), {
-          id: f.id,
-          name: f.name,
-          path: f.path,
-          type: f.type,
-          source: 'declared',
-          fields: f.fields,
-          items: f.items
-        });
-      }
-    }
-
-    const fields = Array.from(fieldByPath.values()).sort((a, b) =>
-      a.path.localeCompare(b.path)
-    );
-
-    results.push({
-      id: declared?.id,
-      // Display name is always derived from the namespace. There's no
-      // authored override, the namespace is the canonical identity.
-      name: capitalize(humanizeStatePath(namespace)),
-      namespace,
-      description: declared?.description,
-      resourceId: declared?.resourceId,
-      fields,
-      isMaterialized: declared !== undefined,
-      usedBySurfaces: acc ? Array.from(acc.surfaces).sort() : []
-    });
-  }
-  results.sort((a, b) => a.namespace.localeCompare(b.namespace));
-  return results;
-};
-
-/**
- * Promote an effective data entry into a stored `Entity` record. Used when the
- * user wants to attach metadata (description, resource link, …). The resulting
- * `Entity` carries every effective field exactly as displayed.
- */
-export const materializeFields = (
-  effective: EffectiveEntities,
-  newFieldId: () => EntityFieldId
-): readonly EntityField[] => {
-  return effective.fields.map((f) => ({
-    id: f.id ?? newFieldId(),
-    name: f.name,
-    path: f.path,
-    type: f.type,
-    fields: f.fields,
-    items: f.items
-  }));
-};
+import type { Entity, EntityField } from '../entities/Entity';
+import type { Feature } from '../entities/Feature';
+import type { EntityFieldType } from '../value-objects/EntityFieldType';
+import type { EntityFieldId, EntityId, ResourceId } from '../value-objects/ids';
+import type { StatePath } from '../value-objects/StatePath';
+import { humanizeStatePath } from '../value-objects/humanize';
+
+/**
+ * Where each piece of an EffectiveEntities came from. Deduced fields are inferred
+ * from state-path namespaces; declared fields were explicitly authored on a
+ * Entity entity.
+ */
+export type FieldSource = 'deduced' | 'declared';
+
+export type EffectiveDataField = {
+  readonly id?: EntityFieldId;
+  readonly name: string;
+  readonly path: StatePath;
+  readonly type: EntityFieldType;
+  readonly source: FieldSource;
+  /** type='object' nested fields (declared only). */
+  readonly fields?: readonly EntityField[];
+  /** type='array' element schema (declared only). */
+  readonly items?: EntityField;
+};
+
+/**
+ * The unified view of a Entity entity that the UI consumes. Combines:
+ *  - state-path namespaces in the feature (always present), and
+ *  - any explicitly authored Entity record (optional overrides).
+ *
+ * "Materialized" means a `Entity` record exists in `feature.entities`. Editing
+ * an unmaterialized entry should lazily create one so the metadata
+ * (description, resource link, custom name) has somewhere to live.
+ */
+export type EffectiveEntities = {
+  readonly id?: EntityId;
+  readonly name: string;
+  readonly namespace: string;
+  readonly description?: string;
+  readonly resourceId?: ResourceId;
+  readonly fields: readonly EffectiveDataField[];
+  readonly isMaterialized: boolean;
+  readonly usedBySurfaces: readonly string[];
+};
+
+const capitalize = (s: string): string =>
+  s.length === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1);
+
+const fieldNameFromPath = (path: string): string => {
+  const segments = path.split('.');
+  if (segments.length <= 1) return path;
+  return segments[segments.length - 1] as string;
+};
+
+/**
+ * Produce the list of all Entity entities visible in the feature. Every
+ * state-path namespace, enriched with metadata from any matching authored
+ * `Entity` record. Authored entries with no matching state paths still appear
+ * (so the user doesn't lose explicit work).
+ */
+export const getEffectiveEntities = (feature: Feature): readonly EffectiveEntities[] => {
+  type DeducedAcc = {
+    readonly fields: Map<string, EffectiveDataField>;
+    readonly surfaces: Set<string>;
+  };
+  const deduced = new Map<string, DeducedAcc>();
+
+  for (const surface of feature.surfaces) {
+    for (const def of surface.stateDefinitions) {
+      const namespace = def.path.split('.')[0] ?? def.path;
+      let acc = deduced.get(namespace);
+      if (!acc) {
+        acc = { fields: new Map(), surfaces: new Set() };
+        deduced.set(namespace, acc);
+      }
+      if (!acc.fields.has(def.path)) {
+        acc.fields.set(def.path, {
+          name: fieldNameFromPath(def.path),
+          path: def.path,
+          type: def.type,
+          source: 'deduced'
+        });
+      }
+      acc.surfaces.add(surface.name);
+    }
+  }
+
+  const declaredByNamespace = new Map<string, Entity>();
+  for (const data of feature.entities) {
+    declaredByNamespace.set(data.namespace, data);
+  }
+
+  const namespaces = new Set<string>([
+    ...deduced.keys(),
+    ...declaredByNamespace.keys()
+  ]);
+
+  const results: EffectiveEntities[] = [];
+  for (const namespace of namespaces) {
+    const declared = declaredByNamespace.get(namespace);
+    const acc = deduced.get(namespace);
+
+    // Build the field map. Start with deduced fields, then layer declared
+    // fields. A declared field with the same path overrides type/name and
+    // marks the source as "declared".
+    const fieldByPath = new Map<string, EffectiveDataField>();
+    if (acc) {
+      for (const [path, f] of acc.fields) fieldByPath.set(path, f);
+    }
+    if (declared) {
+      for (const f of declared.fields) {
+        // Declared fields without a path can't surface in the effective view
+        // (they live inside an object/array and don't map to a state path).
+        if (!f.path) continue;
+        fieldByPath.set(String(f.path), {
+          id: f.id,
+          name: f.name,
+          path: f.path,
+          type: f.type,
+          source: 'declared',
+          fields: f.fields,
+          items: f.items
+        });
+      }
+    }
+
+    const fields = Array.from(fieldByPath.values()).sort((a, b) =>
+      a.path.localeCompare(b.path)
+    );
+
+    results.push({
+      id: declared?.id,
+      // Display name is always derived from the namespace. There's no
+      // authored override, the namespace is the canonical identity.
+      name: capitalize(humanizeStatePath(namespace)),
+      namespace,
+      description: declared?.description,
+      resourceId: declared?.resourceId,
+      fields,
+      isMaterialized: declared !== undefined,
+      usedBySurfaces: acc ? Array.from(acc.surfaces).sort() : []
+    });
+  }
+  results.sort((a, b) => a.namespace.localeCompare(b.namespace));
+  return results;
+};
+
+/**
+ * Promote an effective data entry into a stored `Entity` record. Used when the
+ * user wants to attach metadata (description, resource link, …). The resulting
+ * `Entity` carries every effective field exactly as displayed.
+ */
+export const materializeFields = (
+  effective: EffectiveEntities,
+  newFieldId: () => EntityFieldId
+): readonly EntityField[] => {
+  return effective.fields.map((f) => ({
+    id: f.id ?? newFieldId(),
+    name: f.name,
+    path: f.path,
+    type: f.type,
+    fields: f.fields,
+    items: f.items
+  }));
+};

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

@@ -1,83 +1,83 @@
-import type { Feature } from '../entities/Feature';
-import type { StatePath } from '../value-objects/StatePath';
-import type { StateType } from '../value-objects/StateValue';
-import { humanizeStatePath } from '../value-objects/humanize';
-
-export type DeducedField = {
-  readonly name: string;
-  readonly path: StatePath;
-  readonly type: StateType;
-};
-
-export type DeducedDataCandidate = {
-  /** First segment of the dot-path; the proposed entity's namespace. */
-  readonly namespace: string;
-  /** Suggested human-friendly name (e.g. "User", "Cart"). */
-  readonly proposedName: string;
-  readonly fields: readonly DeducedField[];
-  readonly usedBySurfaces: readonly string[];
-};
-
-const capitalize = (s: string): string =>
-  s.length === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1);
-
-const fieldNameFromPath = (path: string): string => {
-  const segments = path.split('.');
-  if (segments.length <= 1) return path;
-  // Everything after the namespace becomes the field name. If there are
-  // multiple sub-segments (e.g. "user.address.city"), use the last one.
-  return segments[segments.length - 1] as string;
-};
-
-/**
- * Walk every state definition across every surface and group by the first
- * path segment (namespace). Each unique namespace becomes a candidate Entity
- * entity. Namespaces that already have a materialized Entity entry are skipped.
- *
- * Output is sorted alphabetically for stable rendering.
- */
-export const deduceDataCandidates = (
-  feature: Feature
-): readonly DeducedDataCandidate[] => {
-  const existingNamespaces = new Set(feature.entities.map((d) => d.namespace));
-
-  type Acc = {
-    fields: Map<string, DeducedField>; // path -> field (dedup)
-    surfaces: Set<string>;
-  };
-  const byNamespace = new Map<string, Acc>();
-
-  for (const surface of feature.surfaces) {
-    for (const def of surface.stateDefinitions) {
-      const segments = def.path.split('.');
-      const namespace = segments[0] ?? def.path;
-      if (existingNamespaces.has(namespace)) continue;
-
-      let acc = byNamespace.get(namespace);
-      if (!acc) {
-        acc = { fields: new Map(), surfaces: new Set() };
-        byNamespace.set(namespace, acc);
-      }
-      if (!acc.fields.has(def.path)) {
-        acc.fields.set(def.path, {
-          name: fieldNameFromPath(def.path),
-          path: def.path,
-          type: def.type
-        });
-      }
-      acc.surfaces.add(surface.name);
-    }
-  }
-
-  const candidates: DeducedDataCandidate[] = [];
-  for (const [namespace, acc] of byNamespace) {
-    candidates.push({
-      namespace,
-      proposedName: capitalize(humanizeStatePath(namespace)),
-      fields: Array.from(acc.fields.values()).sort((a, b) => a.path.localeCompare(b.path)),
-      usedBySurfaces: Array.from(acc.surfaces).sort()
-    });
-  }
-  candidates.sort((a, b) => a.namespace.localeCompare(b.namespace));
-  return candidates;
-};
+import type { Feature } from '../entities/Feature';
+import type { StatePath } from '../value-objects/StatePath';
+import type { StateType } from '../value-objects/StateValue';
+import { humanizeStatePath } from '../value-objects/humanize';
+
+export type DeducedField = {
+  readonly name: string;
+  readonly path: StatePath;
+  readonly type: StateType;
+};
+
+export type DeducedDataCandidate = {
+  /** First segment of the dot-path; the proposed entity's namespace. */
+  readonly namespace: string;
+  /** Suggested human-friendly name (e.g. "User", "Cart"). */
+  readonly proposedName: string;
+  readonly fields: readonly DeducedField[];
+  readonly usedBySurfaces: readonly string[];
+};
+
+const capitalize = (s: string): string =>
+  s.length === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1);
+
+const fieldNameFromPath = (path: string): string => {
+  const segments = path.split('.');
+  if (segments.length <= 1) return path;
+  // Everything after the namespace becomes the field name. If there are
+  // multiple sub-segments (e.g. "user.address.city"), use the last one.
+  return segments[segments.length - 1] as string;
+};
+
+/**
+ * Walk every state definition across every surface and group by the first
+ * path segment (namespace). Each unique namespace becomes a candidate Entity
+ * entity. Namespaces that already have a materialized Entity entry are skipped.
+ *
+ * Output is sorted alphabetically for stable rendering.
+ */
+export const deduceDataCandidates = (
+  feature: Feature
+): readonly DeducedDataCandidate[] => {
+  const existingNamespaces = new Set(feature.entities.map((d) => d.namespace));
+
+  type Acc = {
+    fields: Map<string, DeducedField>; // path -> field (dedup)
+    surfaces: Set<string>;
+  };
+  const byNamespace = new Map<string, Acc>();
+
+  for (const surface of feature.surfaces) {
+    for (const def of surface.stateDefinitions) {
+      const segments = def.path.split('.');
+      const namespace = segments[0] ?? def.path;
+      if (existingNamespaces.has(namespace)) continue;
+
+      let acc = byNamespace.get(namespace);
+      if (!acc) {
+        acc = { fields: new Map(), surfaces: new Set() };
+        byNamespace.set(namespace, acc);
+      }
+      if (!acc.fields.has(def.path)) {
+        acc.fields.set(def.path, {
+          name: fieldNameFromPath(def.path),
+          path: def.path,
+          type: def.type
+        });
+      }
+      acc.surfaces.add(surface.name);
+    }
+  }
+
+  const candidates: DeducedDataCandidate[] = [];
+  for (const [namespace, acc] of byNamespace) {
+    candidates.push({
+      namespace,
+      proposedName: capitalize(humanizeStatePath(namespace)),
+      fields: Array.from(acc.fields.values()).sort((a, b) => a.path.localeCompare(b.path)),
+      usedBySurfaces: Array.from(acc.surfaces).sort()
+    });
+  }
+  candidates.sort((a, b) => a.namespace.localeCompare(b.namespace));
+  return candidates;
+};