@playfast/reform 0.0.5 → 0.0.8

package/src/state/stateFamily.test.ts

@@ -0,0 +1,138 @@
+import { expect, it } from '@effect/vitest'
+import { Duration, Effect, Layer, Schema as S } from 'effect'
+import { Engine, Event, publish, Reducer, StateFamily } from '../index'
+
+// A family is normalized keyed state: one logical slice per key, so a write to
+// one key must wake only that key's subscribers (the point of the primitive).
+
+const tick = Effect.sleep(Duration.millis(1))
+
+it.live("writing one key does not notify another key's subscribers", () => {
+  class Items extends StateFamily.make('items', S.String, S.Number) {}
+  const TestLayer = StateFamily.live(Items, 0)
+
+  return Effect.gen(function* () {
+    const family = yield* Items.store
+    const a = family.at('a')
+    const b = family.at('b')
+    const aWakes = { n: 0 }
+    const bWakes = { n: 0 }
+    a.subscribe(() => {
+      aWakes.n += 1
+    })
+    b.subscribe(() => {
+      bWakes.n += 1
+    })
+
+    a.set(1)
+    yield* tick
+    expect(aWakes.n).toBe(1)
+    expect(bWakes.n).toBe(0)
+    expect(b.get()).toBe(0)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('at(key) returns the same store each call, so subscriptions are stable', () => {
+  class Items extends StateFamily.make('items', S.String, S.Number) {}
+  const TestLayer = StateFamily.live(Items, 0)
+
+  return Effect.gen(function* () {
+    const family = yield* Items.store
+    expect(family.at('k')).toBe(family.at('k'))
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('forget(key) drops the store; re-reading the key reseeds it', () => {
+  class Items extends StateFamily.make('items', S.String, S.Number) {}
+  const TestLayer = StateFamily.live(Items, 0)
+
+  return Effect.gen(function* () {
+    const family = yield* Items.store
+    const first = family.at('k')
+    first.set(42)
+    expect(family.at('k').get()).toBe(42)
+
+    family.forget('k')
+    // A fresh store, reseeded to the family's initial value — not the old 42.
+    const reseeded = family.at('k')
+    expect(reseeded).not.toBe(first)
+    expect(reseeded.get()).toBe(0)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('evictWhenUnused drops a key once its last subscriber leaves', () => {
+  class Items extends StateFamily.make('items', S.String, S.Number) {}
+  const TestLayer = StateFamily.live(Items, 0, { evictWhenUnused: true })
+
+  return Effect.gen(function* () {
+    const family = yield* Items.store
+    const store = family.at('k')
+    const offA = store.subscribe(() => {})
+    const offB = store.subscribe(() => {})
+    expect(family.size()).toBe(1)
+
+    // One subscriber leaving keeps the key (another still reads it).
+    offA()
+    yield* tick
+    expect(family.size()).toBe(1)
+
+    // The last subscriber leaving evicts the key on the next microtask.
+    offB()
+    yield* tick
+    expect(family.size()).toBe(0)
+    // Re-reading reseeds a fresh store.
+    expect(family.at('k').get()).toBe(0)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('evictWhenUnused: a same-tick re-subscribe cancels eviction', () => {
+  class Items extends StateFamily.make('items', S.String, S.Number) {}
+  const TestLayer = StateFamily.live(Items, 0, { evictWhenUnused: true })
+
+  return Effect.gen(function* () {
+    const family = yield* Items.store
+    const store = family.at('k')
+    store.set(7)
+    const off = store.subscribe(() => {})
+    off() // count → 0, eviction scheduled for the next microtask
+    store.subscribe(() => {}) // re-subscribe in the same tick → count back to 1
+    yield* tick
+    // Not evicted: the value survives and `at` returns the same live store.
+    expect(family.size()).toBe(1)
+    expect(family.at('k').get()).toBe(7)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('a family reducer fold returning Tombstone evicts the key', () => {
+  class Items extends StateFamily.make('items', S.String, S.Number) {}
+  class Bumped extends Event.make('Bumped', S.Struct({ id: S.String })) {}
+  class Removed extends Event.make('Removed', S.Struct({ id: S.String })) {}
+  class ItemsReducer extends Reducer.make('ItemsReducer', {
+    family: Items,
+    keyOf: (event) => event.id,
+    events: [Bumped, Removed],
+  }) {}
+  const ItemsLive = Reducer.live(ItemsReducer, (n, event) =>
+    event._tag === 'Removed' ? StateFamily.Tombstone : n + 1,
+  )
+
+  const TestLayer = ItemsLive.pipe(
+    Layer.provideMerge(Layer.mergeAll(StateFamily.live(Items, 0), Engine)),
+  )
+
+  return Effect.gen(function* () {
+    const family = yield* Items.store
+
+    yield* publish('High', Event.construct(Bumped, { id: 'a' }))
+    yield* Effect.sleep(Duration.millis(5))
+    const before = family.at('a')
+    expect(before.get()).toBe(1)
+
+    // The fold returns the eviction sentinel: the key's store is dropped.
+    yield* publish('High', Event.construct(Removed, { id: 'a' }))
+    yield* Effect.sleep(Duration.millis(5))
+    const after = family.at('a')
+    expect(after).not.toBe(before)
+    expect(after.get()).toBe(0)
+  }).pipe(Effect.provide(TestLayer))
+})

package/src/state/stateFamily.ts

@@ -1,6 +1,7 @@
 import { Context, Effect, Layer, type Schema } from 'effect'
 import { type Manifest, definitionClass } from '../definition/definition'
 import { resolveScheduler, type Scheduler } from '../internal/scheduler'
+import { claimStateTag } from '../internal/stateRegistry'
 import { makeStore, type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
 
@@ -131,7 +132,9 @@ export const make = <const N extends string, K, V>(
   value: Schema.Schema<V, any>,
   options: { readonly title?: string; readonly description?: string } = {},
 ): StateFamilyClass<N, K, V> => {
-  const store = Context.GenericTag<FamilyStore<K, V>, FamilyStore<K, V>>(`reform/family/${name}`)
+  const identifier = `reform/family/${name}`
+  claimStateTag(identifier)
+  const store = Context.GenericTag<FamilyStore<K, V>, FamilyStore<K, V>>(identifier)
   const manifest: StateFamilyManifest<N, K, V> = {
     kind: 'StateFamily',
     name,

package/src/state/stateGroup.ts

@@ -1,6 +1,6 @@
 import { Layer } from 'effect'
 import { definitionClass } from '../definition/definition'
-import { UnknownGroupState } from '../internal/errors'
+import { DuplicateRegistration, UnknownGroupState } from '../internal/errors'
 // A group's members each carry a `store` tag, so the shared `StoresOf` (used for
 // calc inputs too) distributes them into the union of distinct stores their
 // `live` layer provides — no group-specific mapped type needed.
@@ -21,6 +21,27 @@ export interface StateGroupClass<Members extends ReadonlyArray<AnyState>> {
 
 export type AnyStateGroup = StateGroupClass<ReadonlyArray<AnyState>>
 
+/**
+ * Compile-time uniqueness guard for `StateGroup.make`. Member names key the tag,
+ * the seed record, `byName`, and `select` — duplicates are unaddressable, so a
+ * repeated name is replaced (positionally) by this marker tuple, which a real
+ * `StateClass` is not assignable to. The offending argument fails to typecheck
+ * with the colliding name spelled out in the message, rather than collapsing
+ * silently. Runtime `make` throws the same clash for seeds the root tsconfig
+ * never typechecks (test files live outside it).
+ */
+type DuplicateStateName<N extends string> = readonly ['reform: duplicate state name in group', N]
+
+type NoDuplicateNames<
+  Members extends ReadonlyArray<AnyState>,
+  Seen extends string = never,
+> = Members extends readonly [infer Head extends AnyState, ...infer Tail extends ReadonlyArray<AnyState>]
+  ? readonly [
+      StateName<Head> extends Seen ? DuplicateStateName<StateName<Head>> : Head,
+      ...NoDuplicateNames<Tail, Seen | StateName<Head>>,
+    ]
+  : readonly []
+
 // The seed record `StateGroup.live` requires: one entry per member, keyed by the
 // member's name and typed to that member's value (so a missing or mistyped seed
 // is a compile error). Written against the group class, so call sites read
@@ -32,13 +53,19 @@ export type GroupSeeds<G extends AnyStateGroup> =
 
 /** Compose atomic States into a group provided (and addressed) as a unit. */
 export const make = <const Members extends ReadonlyArray<AnyState>>(
-  ...members: Members
-): StateGroupClass<Members> =>
-  definitionClass<StateGroupClass<Members>>({
+  ...members: Members & NoDuplicateNames<Members>
+): StateGroupClass<Members> => {
+  // `byName` already de-dupes, so a smaller map than the member list means two
+  // members claimed one name — unaddressable, and a silent footgun on merge.
+  const names = members.map((m) => m.manifest.name)
+  const duplicate = names.find((name, i) => names.indexOf(name) !== i)
+  if (duplicate !== undefined) throw new DuplicateRegistration({ kind: 'state in group', name: duplicate })
+  return definitionClass<StateGroupClass<Members>>({
     kind: 'StateGroup' as const,
     members,
     byName: new Map(members.map((m) => [m.manifest.name, m] as const)),
   })
+}
 
 /**
  * Address a member by its tag — `StateGroup.select(TodosStates, 'feed')` —

package/src/state/token.ts

@@ -8,11 +8,12 @@ import { readTracked } from '../internal/track'
  * (its `name` and backing store tag). Returned by `StateGroup.select(group, name)`.
  */
 export class StateToken<out N extends string, in out A> extends Effectable.Class<A, never, Store<A>> {
-  constructor(
-    readonly name: N,
-    readonly store: Context.Tag<Store<A>, Store<A>>,
-  ) {
+  readonly name: N
+  readonly store: Context.Tag<Store<A>, Store<A>>
+  constructor(name: N, store: Context.Tag<Store<A>, Store<A>>) {
     super()
+    this.name = name
+    this.store = store
   }
   commit(): Effect.Effect<A, never, Store<A>> {
     return Effect.flatMap(this.store, readTracked)

package/src/synced/syncedStore.ts

@@ -0,0 +1,99 @@
+import { Context, Effect, Layer, type Schema, type Scope } from 'effect'
+import { type Manifest, yieldableClass } from '../definition/definition'
+import { resolveScheduler } from '../internal/scheduler'
+import { makeDerivedStore, type Store } from '../internal/store'
+import { readTracked } from '../internal/track'
+import type { Source } from '../state/token'
+import type { StateOptions } from '../state/state'
+
+// `SyncedStore` is the seam between Reform's reactive `Store` and any *external*
+// reactive source — a PGlite live query, a TanStack DB collection, a socket feed.
+// It is the synchronous, useSyncExternalStore-shaped bridge: a source exposes a
+// `snapshot()` (the current value, synchronously) and a `subscribe(onChange)`,
+// which is exactly what `makeDerivedStore` consumes. Like `RemoteState`'s `truth`
+// store, a `SyncedStore` is written ONLY by its upstream subscription — never by a
+// user reducer — so the "state changes only in the loop (or its driver)" invariant
+// holds. `@playfast/reform-db` is the first consumer: it feeds a `SyncedStore` from
+// a SQL live query whose value is an `AsyncData<Rows>`.
+
+/**
+ * The contract an external reactive source implements. `snapshot` must return a
+ * stable reference until the value actually changes (the `makeDerivedStore`
+ * memoization contract `useSyncExternalStore` requires); `subscribe` returns an
+ * unsubscribe thunk, fired on every upstream change.
+ */
+export interface SyncedSource<A> {
+  readonly snapshot: () => A
+  readonly subscribe: (onChange: () => void) => () => void
+}
+
+export interface SyncedStoreManifest<N extends string, A> extends Manifest {
+  readonly kind: 'SyncedStore'
+  readonly name: N
+  readonly schema: Schema.Schema<A, any>
+  readonly title?: string
+  readonly description?: string
+}
+
+export interface SyncedStoreClass<out N extends string, in out A>
+  extends Effect.Effect<A, never, Store<A>>,
+    Source<N, A> {
+  new (): {}
+  readonly manifest: SyncedStoreManifest<N, A>
+  /** Internal DI tag holding the live store. `SyncedStore.live` allocates it. */
+  readonly store: Context.Tag<Store<A>, Store<A>>
+  /** The name, so the class doubles as a `Source` input to a calc/composition. */
+  readonly name: N
+}
+
+export type AnySyncedStore = SyncedStoreClass<string, any>
+export type SyncedValue<S> = S extends SyncedStoreClass<string, infer A> ? A : never
+
+/**
+ * Define an externally-synced slice: a reflectable manifest + an internal store
+ * tag, yieldable to its current value and usable as a calc/composition `Source`.
+ * Carries no source — that is supplied at wiring time by `SyncedStore.live`,
+ * exactly as `State.make` defers its seed to `State.live`.
+ */
+export const make = <const N extends string, A>(
+  name: N,
+  schema: Schema.Schema<A, any>,
+  options: StateOptions = {},
+): SyncedStoreClass<N, A> => {
+  const store = Context.GenericTag<Store<A>, Store<A>>(`reform/syncedStore/${name}`)
+  const manifest: SyncedStoreManifest<N, A> = {
+    kind: 'SyncedStore',
+    name,
+    schema,
+    ...(options.title !== undefined ? { title: options.title } : {}),
+    ...(options.description !== undefined ? { description: options.description } : {}),
+  }
+  const read = Effect.flatMap(store, readTracked)
+  return yieldableClass(read, { manifest, store, name })
+}
+
+/**
+ * Allocate a synced store's backing cell and bind it to an external source.
+ * `acquire` yields the source within the layer's scope (so it can open a live
+ * query / subscription whose `R` — e.g. a `Db` driver — is captured here); the
+ * store mirrors `snapshot()` and re-notifies on every `subscribe` change through
+ * the runtime's coalescing scheduler. The upstream subscription is released with
+ * the layer's scope.
+ */
+export const live = <A, R>(
+  // A minimal store-carrier — satisfied by a `SyncedStoreClass` and by any
+  // companion primitive (e.g. `@playfast/reform-db`'s `DbQuery`) that allocates
+  // its own `Store` tag, so the seam is reusable beyond `SyncedStore` itself.
+  def: { readonly store: Context.Tag<Store<A>, Store<A>> },
+  acquire: Effect.Effect<SyncedSource<A>, never, R>,
+): Layer.Layer<Store<A>, never, Exclude<R, Scope.Scope>> =>
+  Layer.scoped(
+    def.store,
+    Effect.gen(function* () {
+      const scheduler = yield* resolveScheduler
+      const source = yield* acquire
+      const { store, unsubscribe } = makeDerivedStore(source.snapshot, source.subscribe, scheduler)
+      yield* Effect.addFinalizer(() => Effect.sync(unsubscribe))
+      return store
+    }),
+  )

package/src/wire/tree.test.ts

@@ -0,0 +1,81 @@
+import { expect, test } from 'vitest'
+import { Wire } from '../index'
+import type { WireNode, WireTree } from '../index'
+
+const node = (id: string, over: Partial<WireNode> = {}): WireNode => ({
+  id,
+  name: 'View',
+  parentId: null,
+  childIndex: 0,
+  slot: null,
+  key: null,
+  props: [],
+  ...over,
+})
+
+// `diff` / `apply` are a round trip: folding `diff(prev, next)` into `prev`
+// reconstructs `next` exactly, for any pair of trees.
+
+test('a fresh tree diffs to one upsert per node', () => {
+  const next: WireTree = [node('a'), node('b', { parentId: 'a', slot: 'body' })]
+  const patches = Wire.diff([], next)
+  expect(patches).toHaveLength(2)
+  expect(patches.every((patch) => patch._tag === 'Upsert')).toBe(true)
+  expect(Wire.apply([], patches)).toEqual(next)
+})
+
+test('unchanged nodes produce no patches', () => {
+  const tree: WireTree = [node('a'), node('b', { parentId: 'a' })]
+  expect(Wire.diff(tree, tree)).toHaveLength(0)
+})
+
+test('a changed prop upserts only that node', () => {
+  const prev: WireTree = [node('a', { props: [{ _tag: 'Data', name: 'count', value: 1 }] })]
+  const next: WireTree = [node('a', { props: [{ _tag: 'Data', name: 'count', value: 2 }] })]
+  const patches = Wire.diff(prev, next)
+  expect(patches).toEqual([{ _tag: 'Upsert', node: next[0] }])
+  expect(Wire.apply(prev, patches)).toEqual(next)
+})
+
+test('a removed node diffs to a delete', () => {
+  const prev: WireTree = [node('a'), node('b', { parentId: 'a' })]
+  const next: WireTree = [node('a')]
+  const patches = Wire.diff(prev, next)
+  expect(patches).toEqual([{ _tag: 'Delete', id: 'b' }])
+  expect(Wire.apply(prev, patches)).toEqual(next)
+})
+
+test('event props compare by handle, not by identity', () => {
+  const prev: WireTree = [node('a', { props: [{ _tag: 'Event', name: 'bump', handle: 'h1' }] })]
+  const same: WireTree = [node('a', { props: [{ _tag: 'Event', name: 'bump', handle: 'h1' }] })]
+  const changed: WireTree = [node('a', { props: [{ _tag: 'Event', name: 'bump', handle: 'h2' }] })]
+  expect(Wire.diff(prev, same)).toHaveLength(0)
+  expect(Wire.diff(prev, changed)).toHaveLength(1)
+})
+
+test('deletes precede upserts within a frame', () => {
+  const prev: WireTree = [node('old', { parentId: 'r', slot: 'body' }), node('r')]
+  const next: WireTree = [node('r'), node('new', { parentId: 'r', slot: 'body' })]
+  const patches = Wire.diff(prev, next)
+  const firstUpsert = patches.findIndex((patch) => patch._tag === 'Upsert')
+  const lastDelete = patches.map((patch) => patch._tag).lastIndexOf('Delete')
+  expect(lastDelete).toBeLessThan(firstUpsert)
+})
+
+test('roots and childrenOf order siblings by childIndex', () => {
+  const tree: WireTree = [
+    node('r1', { childIndex: 1 }),
+    node('r0', { childIndex: 0 }),
+    node('c1', { parentId: 'r0', childIndex: 1 }),
+    node('c0', { parentId: 'r0', childIndex: 0 }),
+  ]
+  expect(Wire.roots(tree).map((n) => n.id)).toEqual(['r0', 'r1'])
+  expect(Wire.childrenOf(tree, 'r0').map((n) => n.id)).toEqual(['c0', 'c1'])
+})
+
+test('nested deep prop changes are detected', () => {
+  const prev: WireTree = [node('a', { props: [{ _tag: 'Data', name: 'rows', value: [{ id: 1 }, { id: 2 }] }] })]
+  const next: WireTree = [node('a', { props: [{ _tag: 'Data', name: 'rows', value: [{ id: 1 }, { id: 3 }] }] })]
+  expect(Wire.diff(prev, next)).toHaveLength(1)
+  expect(Wire.diff(prev, prev)).toHaveLength(0)
+})

package/src/wire/tree.ts

@@ -0,0 +1,129 @@
+import { Match } from 'effect'
+
+/**
+ * The serializable model of a rendered UI tree, and the pure diff/apply over it.
+ *
+ * This is the renderer-neutral heart of the remote transport (REMOTE_UI.md §3):
+ * the server renders a scene to a `WireTree`, sends `diff(prev, next)` as
+ * `WirePatch`es, and the client folds them back with `apply`. No React, no
+ * Effect — pure data, so both ends and the proofs share one source of truth.
+ */
+
+/**
+ * A prop on a wire node: either an already-encoded data value, or a handle the
+ * client invokes to fire the server-side trigger (resolved by the trigger
+ * registry, REMOTE_UI.md §4). Streams, when added, become a third arm.
+ */
+export type WireProp =
+  | { readonly _tag: 'Data'; readonly name: string; readonly value: unknown }
+  | { readonly _tag: 'Event'; readonly name: string; readonly handle: string }
+
+/** One rendered UI contract instance, identified stably across frames. */
+export interface WireNode {
+  /** Stable identity across renders — the unit of diffing. */
+  readonly id: string
+  /** The UI contract name (`UiCapture.name`) the client looks up a presentation by. */
+  readonly name: string
+  /** Parent node id, or `null` for a root. */
+  readonly parentId: string | null
+  /** Order among siblings under the same parent. */
+  readonly childIndex: number
+  /** The slot name this node fills in its parent, or `null` for a root / direct child. */
+  readonly slot: string | null
+  /**
+   * The React `key` the parent gave this slot child (`createElement(slots.Row, { key })`),
+   * or `null` when none was set. It is the per-child identity a KEYED slot selects on: the
+   * client renders `<slots.Row slotKey={id} />` and the slot thunk picks the one wire child
+   * whose `key` matches, instead of rendering every child of that slot at every call site.
+   * Without it the client slot is render-all-children (correct for singleton slots, wrong for
+   * a list slot invoked once per item — it duplicates the whole list under each call).
+   */
+  readonly key: string | null
+  readonly props: ReadonlyArray<WireProp>
+}
+
+export type WireTree = ReadonlyArray<WireNode>
+
+/** A change to apply to a client's tree: upsert a node, or drop one by id. */
+export type WirePatch =
+  | { readonly _tag: 'Upsert'; readonly node: WireNode }
+  | { readonly _tag: 'Delete'; readonly id: string }
+
+const arraysEqual = (a: ReadonlyArray<unknown>, b: ReadonlyArray<unknown>): boolean =>
+  a.length === b.length && a.every((item, index) => deepEqual(item, b[index]))
+
+const recordsEqual = (a: Record<string, unknown>, b: Record<string, unknown>): boolean => {
+  const aKeys = Object.keys(a)
+  const bKeys = Object.keys(b)
+  return aKeys.length === bKeys.length && aKeys.every((key) => deepEqual(a[key], b[key]))
+}
+
+/** Structural equality over serializable wire values (and the tagged props that carry them). */
+const deepEqual = (a: unknown, b: unknown): boolean => {
+  if (a === b) return true
+  if (a === null || b === null) return false
+  if (Array.isArray(a)) return Array.isArray(b) && arraysEqual(a, b)
+  if (Array.isArray(b)) return false
+  if (typeof a === 'object' && typeof b === 'object') {
+    return recordsEqual(a as Record<string, unknown>, b as Record<string, unknown>)
+  }
+  return false
+}
+
+const nodesEqual = (a: WireNode, b: WireNode): boolean =>
+  a.name === b.name &&
+  a.parentId === b.parentId &&
+  a.childIndex === b.childIndex &&
+  a.slot === b.slot &&
+  a.key === b.key &&
+  deepEqual(a.props, b.props)
+
+const isUnchanged = (node: WireNode, previousById: ReadonlyMap<string, WireNode>): boolean => {
+  const previous = previousById.get(node.id)
+  return previous !== undefined && nodesEqual(previous, node)
+}
+
+/**
+ * The patches that turn `previous` into `next`. Deletes precede upserts so a
+ * client never holds a child whose reparented slot was freed in the same frame.
+ */
+export const diff = (previous: WireTree, next: WireTree): ReadonlyArray<WirePatch> => {
+  const previousById = new Map(previous.map((node) => [node.id, node]))
+  const nextById = new Map(next.map((node) => [node.id, node]))
+
+  const deletes = previous
+    .filter((node) => !nextById.has(node.id))
+    .map((node): WirePatch => ({ _tag: 'Delete', id: node.id }))
+
+  const upserts = next
+    .filter((node) => !isUnchanged(node, previousById))
+    .map((node): WirePatch => ({ _tag: 'Upsert', node }))
+
+  return [...deletes, ...upserts]
+}
+
+const upsertNode = (state: WireTree, node: WireNode): WireTree => {
+  const index = state.findIndex((existing) => existing.id === node.id)
+  if (index < 0) return [...state, node]
+  return [...state.slice(0, index), node, ...state.slice(index + 1)]
+}
+
+/** Fold patches into a client's tree (the receiving side's reducer). */
+export const apply = (state: WireTree, patches: ReadonlyArray<WirePatch>): WireTree =>
+  patches.reduce(
+    (current, patch) =>
+      Match.value(patch).pipe(
+        Match.tag('Delete', ({ id }) => current.filter((node) => node.id !== id)),
+        Match.tag('Upsert', ({ node }) => upsertNode(current, node)),
+        Match.exhaustive,
+      ),
+    state,
+  )
+
+/** The root nodes of a tree, in sibling order. */
+export const roots = (tree: WireTree): WireTree =>
+  tree.filter((node) => node.parentId === null).sort((a, b) => a.childIndex - b.childIndex)
+
+/** The children of a node, in sibling order. */
+export const childrenOf = (tree: WireTree, parentId: string): WireTree =>
+  tree.filter((node) => node.parentId === parentId).sort((a, b) => a.childIndex - b.childIndex)

package/src/wire/triggers.test.ts

@@ -0,0 +1,76 @@
+import { expect, test } from 'vitest'
+import { Effect, Exit, Schema as S } from 'effect'
+import { Triggers } from '../index'
+import type { Trigger } from '../index'
+
+const ByPayload = S.Struct({ by: S.Number })
+
+// The registry holds a live trigger behind a caller-provided handle, decodes the
+// wire payload through the contract's event schema, and fires — never shipping a
+// function, and validating at the seam.
+
+test('re-registering a handle overwrites it with the fresh trigger', () => {
+  const seen = Effect.runSync(
+    Effect.gen(function* () {
+      const registry = yield* Triggers.make
+      const calls: string[] = []
+      yield* registry.register('0:bump', () => void calls.push('stale'), ByPayload)
+      yield* registry.register('0:bump', () => void calls.push('fresh'), ByPayload)
+      yield* registry.invoke('0:bump', { by: 1 })
+      return calls
+    }),
+  )
+  expect(seen).toEqual(['fresh'])
+})
+
+test('invoke decodes the payload and fires the trigger with the decoded value', () => {
+  const seen = Effect.runSync(
+    Effect.gen(function* () {
+      const registry = yield* Triggers.make
+      const received: Array<{ by: number }> = []
+      const bump: Trigger<{ by: number }> = (payload) => void received.push(payload)
+      yield* registry.register('0:bump', bump, ByPayload)
+      yield* registry.invoke('0:bump', { by: 5 })
+      return received
+    }),
+  )
+  expect(seen).toEqual([{ by: 5 }])
+})
+
+test('invoke fails with ParseError when the wire payload violates the schema', () => {
+  const exit = Effect.runSyncExit(
+    Effect.gen(function* () {
+      const registry = yield* Triggers.make
+      yield* registry.register('0:bump', (() => {}) as Trigger<{ by: number }>, ByPayload)
+      yield* registry.invoke('0:bump', { by: 'not-a-number' })
+    }),
+  )
+  expect(Exit.isFailure(exit)).toBe(true)
+})
+
+test('invoke on an unknown handle fails with UnknownTrigger', () => {
+  const exit = Effect.runSyncExit(
+    Effect.gen(function* () {
+      const registry = yield* Triggers.make
+      yield* registry.invoke('t999', { by: 1 })
+    }),
+  )
+  expect(Exit.isFailure(exit)).toBe(true)
+  const error = Exit.isFailure(exit) ? exit.cause : undefined
+  expect(JSON.stringify(error)).toContain('UnknownTrigger')
+})
+
+test('a revoked handle no longer fires', () => {
+  const fired = Effect.runSync(
+    Effect.gen(function* () {
+      const registry = yield* Triggers.make
+      const calls: number[] = []
+      yield* registry.register('0:bump', ((p: { by: number }) => void calls.push(p.by)) as Trigger<{ by: number }>, ByPayload)
+      yield* registry.revoke('0:bump')
+      const exit = yield* Effect.exit(registry.invoke('0:bump', { by: 1 }))
+      return { calls, failed: Exit.isFailure(exit) }
+    }),
+  )
+  expect(fired.calls).toEqual([])
+  expect(fired.failed).toBe(true)
+})