@zeix/cause-effect 1.0.0 → 1.0.1

package/skills/cause-effect-dev/SKILL.md

@@ -7,108 +7,69 @@ description: >
 user_invocable: false
 ---
 
-# Cause & Effect — Developer Skill
+<scope>
+This skill is for development work **on the @zeix/cause-effect library itself** — use it only inside the cause-effect repository where `REQUIREMENTS.md`, `ARCHITECTURE.md`, and `src/` are present at the project root.
 
-You are an expert developer on the **@zeix/cause-effect** reactive state management primitives library (v1.0.0). Work only from authoritative sources listed below. Never guess API shapes or behaviors — read the source.
+For consumer projects that use `@zeix/cause-effect` as a dependency, use the `cause-effect` skill instead.
+</scope>
 
-## Authoritative Sources
+<essential_principles>
+**Read before writing.** Always read the relevant source file(s) before proposing or making changes.
 
-| What you need | Where to look |
+**The signal type set is complete.** Check `REQUIREMENTS.md` before proposing anything new — new signal types are explicitly out of scope.
+
+**`T extends {}`** — all signal generics exclude `null` and `undefined`. Use wrapper types or sentinel values to represent absence.
+
+**Run `bun test`** after every change.
+</essential_principles>
+
+<intake>
+What kind of task is this?
+
+1. **Implement** — add or extend functionality
+2. **Fix** — debug or fix unexpected behavior
+3. **Test** — write or update tests
+4. **Question** — understand the API, internals, or a design decision
+
+**Wait for response before proceeding.**
+</intake>
+
+<routing>
+| Response | Workflow |
 |---|---|
-| Vision, audience, constraints, non-goals | `REQUIREMENTS.md` |
-| Mental model, non-obvious behaviors, TS constraints | `CLAUDE.md` |
-| Full API reference with examples | `README.md` |
-| Mapping from React/Vue/Angular patterns; when to use each signal type | `GUIDE.md` |
-| Graph engine architecture, node shapes, propagation | `ARCHITECTURE.md` |
-| Public API surface (all exports, types) | `index.ts` |
-| Core graph engine (flags, propagation, flush, ownership) | `src/graph.ts` |
-| Error classes | `src/errors.ts` |
-| Signal base types and type guards | `src/signal.ts` |
-| Shared utilities | `src/util.ts` |
-
-## Source File Map
-
-Each signal type lives in its own file:
-
-| Signal | File | Create | Type guard |
-|---|---|---|---|
-| State | `src/nodes/state.ts` | `createState()` | `isState()` |
-| Sensor | `src/nodes/sensor.ts` | `createSensor()` | `isSensor()` |
-| Memo | `src/nodes/memo.ts` | `createMemo()` | `isMemo()` |
-| Task | `src/nodes/task.ts` | `createTask()` | `isTask()` |
-| Effect | `src/nodes/effect.ts` | `createEffect()` | — |
-| Slot | `src/nodes/slot.ts` | `createSlot()` | `isSlot()` |
-| Store | `src/nodes/store.ts` | `createStore()` | `isStore()` |
-| List | `src/nodes/list.ts` | `createList()` | `isList()` |
-| Collection | `src/nodes/collection.ts` | `createCollection()` / `deriveCollection()` | `isCollection()` |
-
-`match()` and `MatchHandlers` live in `src/nodes/effect.ts` alongside `createEffect`.
-
-## Internal Node Shapes
-
-```
-StateNode<T>  — source only
-MemoNode<T>   — source + sink (also used by Slot, Store, List, Collection internals)
-TaskNode<T>   — source + sink + AbortController
-EffectNode    — sink + owner
-Scope         — owner only
-```
-
-Two independent global pointers:
-- `activeSink` — tracked for dependency edges (nulled by `untrack()`)
-- `activeOwner` — tracked for cleanup registration (nulled by `unown()`)
-
-## Key API Facts
-
-- **`T extends {}`** — all signal generics exclude `null` and `undefined`. Use wrapper types or sentinel values to represent absence.
-- **`createScope(fn)`** — returns a single `Cleanup` function. `fn` receives no arguments and returns an optional cleanup.
-- **`createEffect(fn)`** — returns a `Cleanup`. Must be called inside an owner (effect or scope).
-- **`batch(fn)`** — defers flush until `fn` returns; multiple state writes coalesce into one propagation.
-- **`untrack(fn)`** — runs `fn` without recording dependency edges (nulls `activeSink`).
-- **`unown(fn)`** — runs `fn` without registering cleanup in the current owner (nulls `activeOwner`). Use in `connectedCallback` for DOM-owned lifecycles.
-- **`SKIP_EQUALITY`** — sentinel for `options.equals`; forces propagation on every update (use with mutable-reference sensors).
-- **Memo/Task callbacks receive `prev`** — the previous value as first argument, enabling reducer patterns without external state.
-- **`Slot` is a property descriptor** — has `get`, `set`, `configurable`, `enumerable`; can be passed directly to `Object.defineProperty()`.
-
-## Non-Obvious Behaviors
-
-**`byKey()`, `at()`, `keyAt()`, `indexOfKey()` do not create graph edges.** They are direct lookups. To react to structural changes (key added/removed), read `get()`, `keys()`, or `length`.
-
-**Conditional reads delay `watched` activation.** Read signals eagerly before conditional logic to ensure `watched` fires immediately:
-
-```typescript
-// Good — both signals tracked on every run
-createEffect(() => {
-  match([task, derived], { ok: ([r, v]) => render(v, r), nil: () => showSpinner() })
-})
-
-// Bad — derived only tracked after task resolves
-createEffect(() => {
-  match([task], { ok: ([r]) => render(derived.get(), r), nil: () => showSpinner() })
-})
-```
-
-**`equals` suppresses entire subtrees.** When a Memo recomputes to the same value, downstream nodes receive `FLAG_CHECK` and are skipped without running. A custom `equals` on an intermediate Memo can suppress whole subgraphs.
-
-**`watched` stays stable through mutations.** Structural mutations on a List/Collection source do not restart the `watched` callback; it stays active as long as any downstream effect is subscribed.
-
-## Error Classes
-
-| Class | When thrown |
+| 1, "implement", "add", "extend", "build" | workflows/implement-feature.md |
+| 2, "fix", "bug", "debug", "broken", "wrong" | workflows/fix-bug.md |
+| 3, "test", "spec", "coverage" | workflows/write-tests.md |
+| 4, "question", "explain", "how", "why", "what" | workflows/answer-question.md |
+
+**Intent-based routing** (if user provides clear context without selecting):
+- Describes a change to make → workflows/implement-feature.md
+- Describes something not working → workflows/fix-bug.md
+- Asks to write/update tests → workflows/write-tests.md
+- Asks how something works → workflows/answer-question.md
+
+**After identifying the workflow, read it and follow it exactly.**
+</routing>
+
+<reference_index>
+All in `references/`:
+
+| File | Contents |
+|---|---|
+| source-map.md | Authoritative documents + signal source file locations |
+| internal-types.md | Node shapes and global pointers |
+| api-facts.md | Key API constraints and callback patterns |
+| non-obvious-behaviors.md | Counterintuitive behaviors with examples |
+| error-classes.md | Error classes and when they are thrown |
+</reference_index>
+
+<workflows_index>
+All in `workflows/`:
+
+| Workflow | Purpose |
 |---|---|
-| `NullishSignalValueError` | Signal value is `null` or `undefined` |
-| `InvalidSignalValueError` | Value fails the `guard` check |
-| `InvalidCallbackError` | A required callback argument is not a function |
-| `DuplicateKeyError` | List/Collection key collision |
-| `UnsetSignalValueError` | Reading a Sensor/Task before it has produced a value |
-| `ReadonlySignalError` | Writing to a read-only signal |
-| `RequiredOwnerError` | `createEffect` called outside an owner |
-| `CircularDependencyError` | Cycle detected in the graph |
-
-## Workflow
-
-1. **Read before writing.** Always read the relevant source file(s) before proposing or making changes.
-2. **Check `ARCHITECTURE.md`** for graph-level questions (propagation, ownership, flag semantics).
-3. **Check `README.md`** for public API usage patterns and option signatures.
-4. **Check `REQUIREMENTS.md`** before adding anything new — the signal type set is complete and new types are explicitly out of scope.
-5. **Run `bun test`** after changes to verify correctness.
+| implement-feature.md | Add or extend library functionality |
+| fix-bug.md | Diagnose and fix unexpected behavior |
+| write-tests.md | Write or update tests for a signal type or behavior |
+| answer-question.md | Answer questions about the API, internals, or design |
+</workflows_index>

package/skills/cause-effect-dev/references/api-facts.md

@@ -0,0 +1,96 @@
+<overview>
+Key API constraints, defaults, and callback patterns for @zeix/cause-effect. Read this when writing or reviewing any code that uses the public API.
+</overview>
+
+<type_constraint>
+**`T extends {}`** — all signal generics exclude `null` and `undefined` at the type level. This is intentional. Use wrapper types or sentinel values to represent absence:
+
+```typescript
+// Wrong — TypeScript will reject this
+const count = createState<number | null>(null)
+
+// Correct — use a sentinel or wrapper
+const count = createState<number>(0)
+const value = createState<{ data: string } | never>({ data: '' })
+```
+</type_constraint>
+
+<core_functions>
+**`createScope(fn)`**
+- Returns a single `Cleanup` function
+- `fn` receives no arguments
+- `fn` may return an optional cleanup that runs when the scope is disposed
+- Used to group effects and control their lifetime
+
+**`createEffect(fn)`**
+- Returns a `Cleanup` function
+- **Must be called inside an owner** (another effect or a scope) — throws `RequiredOwnerError` otherwise
+- `fn` runs immediately and re-runs whenever its tracked dependencies change
+- Registers cleanup with the current `activeOwner`
+
+**`batch(fn)`**
+- Defers the reactive flush until `fn` returns
+- Multiple state writes inside `fn` coalesce into a single propagation pass
+- Use when updating several signals that feed the same downstream computation
+
+**`untrack(fn)`**
+- Runs `fn` without recording dependency edges (nulls `activeSink`)
+- Reads inside `fn` do not subscribe the current computation to those signals
+- Use to read a signal's current value without creating a reactive dependency
+
+**`unown(fn)`**
+- Runs `fn` without registering cleanups in the current owner (nulls `activeOwner`)
+- Use in `connectedCallback` and similar DOM lifecycle hooks where the DOM — not the reactive graph — owns the element's lifetime
+</core_functions>
+
+<options>
+**`equals`**
+- Available on `createState`, `createSensor`, `createMemo`, `createTask`
+- Default: strict equality (`===`)
+- When a new value is `equals` to the previous, propagation stops — downstream nodes are not re-run
+- **`SKIP_EQUALITY`** — special sentinel for `equals`; forces propagation on every update regardless of value. Use with mutable-reference sensors where the reference never changes but the contents do
+
+**`guard`**
+- Available on `createState`, `createSensor`
+- A predicate `(value: unknown) => value is T`
+- Throws `InvalidSignalValueError` if a set value fails the guard
+- Use to enforce runtime type safety at signal boundaries
+</options>
+
+<callback_patterns>
+**Memo and Task callbacks receive `prev`**
+- Signature: `(prev: T) => T` for Memo; `(prev: T, signal: AbortSignal) => Promise<T>` for Task
+- `prev` is the previous value on every run after the first
+- Enables reducer patterns without external state:
+
+```typescript
+const count = createState(0)
+const doubled = createMemo((prev) => {
+  const next = count.get() * 2
+  return next === prev ? prev : next  // referential stability
+})
+```
+
+**`Slot` is a property descriptor**
+- Has `get`, `set`, `configurable`, `enumerable` fields
+- Can be passed directly to `Object.defineProperty()`:
+
+```typescript
+const slot = createSlot(store, 'name')
+Object.defineProperty(element, 'name', slot)
+```
+
+**`Task` carries an `AbortSignal`**
+- The second argument to the Task callback is an `AbortSignal`
+- The signal is aborted when the Task's dependencies change before the previous async operation completes
+- Always pass it to any `fetch` or cancellable async operation inside a Task
+</callback_patterns>
+
+<lifecycle_summary>
+| Function | Must be in owner? | Returns | Re-runs on dependency change? |
+|---|---|---|---|
+| `createScope(fn)` | No | `Cleanup` | No (fn runs once) |
+| `createEffect(fn)` | **Yes** | `Cleanup` | Yes |
+| `createMemo(fn)` | No | `Memo<T>` | Lazily (on read) |
+| `createTask(fn)` | No | `Task<T>` | Yes (async) |
+</lifecycle_summary>

package/skills/cause-effect-dev/references/error-classes.md

@@ -0,0 +1,97 @@
+<overview>
+Error classes thrown by @zeix/cause-effect and the conditions that trigger them. Read this when writing error-handling code, testing error conditions, or diagnosing an unexpected throw.
+</overview>
+
+<error_table>
+| Class | When thrown |
+|---|---|
+| `NullishSignalValueError` | Signal value is `null` or `undefined` |
+| `InvalidSignalValueError` | Value fails the `guard` predicate |
+| `InvalidCallbackError` | A required callback argument is not a function |
+| `DuplicateKeyError` | List/Collection key collision on insert |
+| `UnsetSignalValueError` | Reading a Sensor or Task before it has produced its first value |
+| `ReadonlySignalError` | Attempting to write to a read-only signal |
+| `RequiredOwnerError` | `createEffect` called outside an owner (effect or scope) |
+| `CircularDependencyError` | A cycle is detected in the reactive graph |
+
+All error classes are defined in `src/errors.ts`.
+</error_table>
+
+<error_details>
+
+<NullishSignalValueError>
+Thrown when a signal's value is `null` or `undefined`. Because all signal generics use `T extends {}`, nullish values are excluded by type — this error surfaces the constraint at runtime for cases where type safety is bypassed (e.g. untyped interop, type assertions).
+</NullishSignalValueError>
+
+<InvalidSignalValueError>
+Thrown when a value passed to `set()` fails the `guard` predicate supplied in the signal's options. This is the runtime enforcement of custom type narrowing at signal boundaries.
+
+```typescript
+const age = createState(0, {
+  guard: (v): v is number => typeof v === 'number' && v >= 0,
+})
+age.set(-1) // throws InvalidSignalValueError
+```
+</InvalidSignalValueError>
+
+<InvalidCallbackError>
+Thrown when a required callback argument (e.g. the computation function passed to `createMemo`, `createTask`, or `createEffect`) is not a function. Catches programming errors like passing `undefined` or a non-function value.
+</InvalidCallbackError>
+
+<DuplicateKeyError>
+Thrown when inserting an item into a List or Collection whose key already exists. Keys must be unique within a given List or Collection. Use `update()` or `set()` to change an existing entry instead.
+</DuplicateKeyError>
+
+<UnsetSignalValueError>
+Thrown when `.get()` is called on a Sensor or Task before it has emitted its first value. Unlike State, Sensor and Task have no initial value — they start in an explicitly unset state.
+
+Handle this with `match`, which provides a `nil` branch for the unset case:
+
+```typescript
+match([sensor, task], {
+  ok: ([s, t]) => render(s, t),
+  nil: () => showSpinner(),
+})
+```
+</UnsetSignalValueError>
+
+<ReadonlySignalError>
+Thrown when code attempts to call `.set()` on a signal that was created as or converted to a read-only signal. Derived signals (Memo, Task) are inherently read-only; certain factory options can also produce read-only State or Sensor instances.
+</ReadonlySignalError>
+
+<RequiredOwnerError>
+Thrown when `createEffect` is called without an active owner in the current execution context. Effects must be created inside a `createScope` callback or inside another `createEffect` callback so that their cleanup can be registered.
+
+```typescript
+// Wrong — no active owner
+createEffect(() => console.log('runs'))  // throws RequiredOwnerError
+
+// Correct — wrapped in a scope
+const dispose = createScope(() => {
+  createEffect(() => console.log('runs'))
+})
+```
+</RequiredOwnerError>
+
+<CircularDependencyError>
+Thrown when the graph engine detects a cycle during propagation — a signal that, directly or transitively, depends on itself. Cycles make it impossible to determine a stable evaluation order and are always a programming error.
+
+Common cause: a Memo or Task that writes to a State it also reads, or two Memos that read each other.
+</CircularDependencyError>
+
+</error_details>
+
+<testing_error_conditions>
+Use `expect(() => ...).toThrow(ErrorClass)` to assert that a specific error is thrown:
+
+```typescript
+import { InvalidSignalValueError, createState } from '@zeix/cause-effect'
+
+test('rejects negative age', () => {
+  const age = createState(0, { guard: (v): v is number => typeof v === 'number' && v >= 0 })
+  expect(() => age.set(-1)).toThrow(InvalidSignalValueError)
+})
+```
+
+Import error classes directly from `src/errors.ts` in internal tests, or from the package root in consumer-facing tests.
+</testing_error_conditions>

package/skills/cause-effect-dev/references/internal-types.md

@@ -0,0 +1,54 @@
+<overview>
+Internal node shapes and global pointers in the @zeix/cause-effect graph engine. Read this when working on graph propagation, ownership, or cleanup.
+</overview>
+
+<node_shapes>
+Five node shapes are used internally. Source files are authoritative — these are summaries only.
+
+| Shape | Role | File |
+|---|---|---|
+| `StateNode<T>` | Source only — holds a value, no dependencies | `src/nodes/state.ts` |
+| `MemoNode<T>` | Source + sink — derives a value from dependencies | `src/nodes/memo.ts` |
+| `TaskNode<T>` | Source + sink + `AbortController` — async derivation with cancellation | `src/nodes/task.ts` |
+| `EffectNode` | Sink + owner — runs side effects, owns child effects/scopes | `src/nodes/effect.ts` |
+| `Scope` | Owner only — groups cleanup registrations, no reactive tracking | `src/graph.ts` |
+
+`Slot`, `Store`, `List`, and `Collection` are built on top of `MemoNode<T>` internally.
+</node_shapes>
+
+<global_pointers>
+Two independent global pointers are maintained by `src/graph.ts`:
+
+**`activeSink`**
+- Set to the currently-running Memo, Task, or Effect during its computation
+- Any signal read while `activeSink` is set records a dependency edge to it
+- Nulled by `untrack(fn)` — reads inside `fn` do not create edges
+- Reset to `null` after each computation completes
+
+**`activeOwner`**
+- Set to the currently-running Effect or Scope
+- Any cleanup registered while `activeOwner` is set is attached to that owner
+- Nulled by `unown(fn)` — cleanups registered inside `fn` are not owned by the current context
+- Use `unown` in `connectedCallback` for nodes whose lifecycle is managed by the DOM, not by the reactive graph
+</global_pointers>
+
+<ownership_vs_tracking>
+The two pointers are independent and serve different purposes:
+
+| Pointer | Purpose | Nulled by |
+|---|---|---|
+| `activeSink` | Dependency tracking (what re-runs when a source changes) | `untrack()` |
+| `activeOwner` | Cleanup registration (what is disposed when an owner is disposed) | `unown()` |
+
+A computation can track dependencies without owning cleanups, and vice versa. These are not the same concept.
+</ownership_vs_tracking>
+
+<flag_semantics>
+Propagation is driven by bitmask flags defined in `src/graph.ts`. Read that file and `ARCHITECTURE.md` for the full semantics. Key flags:
+
+- `FLAG_DIRTY` — node's value is stale and must recompute
+- `FLAG_CHECK` — node may be stale; check sources before deciding whether to recompute
+- `FLAG_NOTIFIED` — node has already been scheduled in the current flush
+
+`FLAG_CHECK` is how `equals` suppresses subtrees: when a Memo recomputes to the same value, downstream nodes are marked `FLAG_CHECK` instead of `FLAG_DIRTY`, and they skip recomputation if their sources have not actually changed.
+</flag_semantics>

package/skills/cause-effect-dev/references/non-obvious-behaviors.md

@@ -0,0 +1,146 @@
+<overview>
+Counterintuitive behaviors in @zeix/cause-effect that commonly cause bugs or confusion. Read this when debugging unexpected reactive behavior, or when writing tests that cover edge cases.
+</overview>
+
+<direct_lookups_do_not_track>
+**`byKey()`, `at()`, `keyAt()`, and `indexOfKey()` do not create graph edges.** They are direct lookups into the internal map/array — calling them inside an effect or memo does not subscribe to structural changes.
+
+To react to structural changes (key added, key removed, order changed), read a tracking accessor instead:
+
+| You want to react to | Read this |
+|---|---|
+| Any structural change | `collection.get()` or `list.get()` |
+| Key set membership | `collection.keys()` |
+| Length / item count | `collection.length` |
+| A specific item's value | `collection.get()` then access the item |
+
+```typescript
+// Wrong — effect does not re-run when keys are added or removed
+createEffect(() => {
+  const item = collection.byKey('id-123')
+  render(item)
+})
+
+// Correct — reading keys() creates a dependency on structural changes
+createEffect(() => {
+  const keys = collection.keys()              // tracks structure
+  const item = collection.byKey('id-123')     // safe after establishing the edge
+  render(item)
+})
+```
+</direct_lookups_do_not_track>
+
+<conditional_reads_delay_watched>
+**Conditional signal reads delay `watched` activation.** The `watched` callback on a State or Sensor fires when the first downstream effect subscribes. If a signal is only read inside a branch that hasn't executed yet, `watched` does not fire until that branch runs.
+
+Read all signals you care about eagerly — before any conditional logic — to ensure `watched` fires on the first effect run:
+
+```typescript
+// Bad — `derived` is only read after `task` resolves to `ok`
+// `derived.watched` does not fire until the task has a value
+createEffect(() => {
+  match([task], {
+    ok: ([result]) => render(derived.get(), result),
+    nil: () => showSpinner(),
+  })
+})
+
+// Good — both signals are read on every run, regardless of task state
+// Both `watched` callbacks fire immediately when the effect is created
+createEffect(() => {
+  match([task, derived], {
+    ok: ([result, value]) => render(value, result),
+    nil: () => showSpinner(),
+  })
+})
+```
+
+This also applies to plain `if` / ternary / `&&` patterns — any signal read gated behind a condition may not establish its dependency edge until the condition is true.
+</conditional_reads_delay_watched>
+
+<equals_suppresses_subtrees>
+**`equals` suppresses entire downstream subgraphs, not just the node it is set on.** When a Memo or State recomputes to a value that is `equals` to the previous one, all downstream nodes receive `FLAG_CHECK` instead of `FLAG_DIRTY`. Those nodes skip recomputation entirely without running their callbacks.
+
+This is a powerful optimization, but it has a non-obvious consequence: a custom `equals` on an intermediate Memo can silently prevent large parts of the graph from updating, even if upstream sources changed.
+
+```typescript
+const source = createState({ x: 1, y: 2 })
+
+// This memo compares by x only
+const xOnly = createMemo(
+  () => source.get().x,
+  { equals: (a, b) => a === b }
+)
+
+// This effect depends on xOnly
+// It will NOT re-run if source changes but x stays the same,
+// even if y changed dramatically
+createEffect(() => {
+  console.log('x is', xOnly.get())
+})
+```
+
+When debugging "why did my effect not re-run", check for custom `equals` on intermediate memos in the dependency chain.
+</equals_suppresses_subtrees>
+
+<watched_stable_through_mutations>
+**`watched` stays active through structural mutations.** The `watched` callback on a List or Collection source is called once when the first downstream effect subscribes, and `unwatched` is called when the last downstream effect unsubscribes. Structural mutations (adding items, removing items, updating values) do not call `unwatched` and then `watched` again — the callback remains active for the lifetime of the subscription.
+
+```typescript
+const list = createList(
+  () => fetchItems(),         // watched: start polling / open WebSocket
+  () => stopPolling(),        // unwatched: stop polling / close WebSocket
+)
+
+// Adding or removing items from the list does NOT restart the watched/unwatched cycle.
+// The data source stays open as long as at least one effect is subscribed.
+list.push({ id: '1', name: 'Item 1' })   // watched callback is NOT called again
+list.delete('1')                          // watched callback is NOT called again
+```
+</watched_stable_through_mutations>
+
+<task_abort_on_dependency_change>
+**A Task's `AbortSignal` is aborted when dependencies change before the async operation completes.** If a Task's sources update while the previous `Promise` is still pending, a new run is scheduled and the previous `AbortController` is aborted. Not forwarding the signal to cancellable async operations will cause stale results to overwrite fresh ones.
+
+```typescript
+// Wrong — fetch is not cancellable; stale response may arrive after a newer one
+const results = createTask(async () => {
+  return fetch(`/api/search?q=${query.get()}`).then(r => r.json())
+})
+
+// Correct — abort signal forwarded; stale requests are cancelled
+const results = createTask(async (prev, signal) => {
+  return fetch(`/api/search?q=${query.get()}`, { signal }).then(r => r.json())
+})
+```
+</task_abort_on_dependency_change>
+
+<sensor_unset_before_first_value>
+**Reading a Sensor or Task before it has produced a value throws `UnsetSignalValueError`.** Unlike State, these signals have no initial value — they are explicitly "unset" until the first value arrives.
+
+Guard against this with `match` or by checking the signal's status before reading:
+
+```typescript
+const sensor = createSensor(set => {
+  const id = setInterval(() => set(Date.now()), 1000)
+  return () => clearInterval(id)
+})
+
+// Wrong — throws UnsetSignalValueError on first run, before the interval fires
+createEffect(() => {
+  console.log(sensor.get())
+})
+
+// Correct — match handles the nil (unset) case explicitly
+createEffect(() => {
+  match([sensor], {
+    ok: ([timestamp]) => console.log(timestamp),
+    nil: () => console.log('waiting for first value…'),
+  })
+})
+```
+</sensor_unset_before_first_value>
+
+<scope_cleanup_is_synchronous>
+**Scope and Effect cleanup runs synchronously when the returned `Cleanup` function is called.** It does not wait for the current flush to complete. Calling cleanup during a flush (e.g. inside a batch callback) is safe but will immediately dispose the owner and all its children.
+</scope_cleanup_is_synchronous>

package/skills/cause-effect-dev/references/source-map.md

@@ -0,0 +1,45 @@
+<overview>
+Where to find things in the @zeix/cause-effect codebase. Read this before locating any source file.
+</overview>
+
+<authoritative_documents>
+| What you need | Where to look |
+|---|---|
+| Vision, audience, constraints, non-goals | `REQUIREMENTS.md` |
+| Mental model, non-obvious behaviors, TS constraints | `CLAUDE.md` |
+| Full API reference with examples | `README.md` |
+| Mapping from React/Vue/Angular patterns; when to use each signal type | `GUIDE.md` |
+| Graph engine architecture, node shapes, propagation | `ARCHITECTURE.md` |
+| Public API surface (all exports, types) | `index.ts` |
+| Core graph engine (flags, propagation, flush, ownership) | `src/graph.ts` |
+| Error classes | `src/errors.ts` |
+| Signal base types and type guards | `src/signal.ts` |
+| Shared utilities | `src/util.ts` |
+</authoritative_documents>
+
+<signal_source_files>
+Each signal type lives in its own file under `src/nodes/`:
+
+| Signal | File | Factory | Type guard |
+|---|---|---|---|
+| State | `src/nodes/state.ts` | `createState()` | `isState()` |
+| Sensor | `src/nodes/sensor.ts` | `createSensor()` | `isSensor()` |
+| Memo | `src/nodes/memo.ts` | `createMemo()` | `isMemo()` |
+| Task | `src/nodes/task.ts` | `createTask()` | `isTask()` |
+| Effect | `src/nodes/effect.ts` | `createEffect()` | — |
+| Slot | `src/nodes/slot.ts` | `createSlot()` | `isSlot()` |
+| Store | `src/nodes/store.ts` | `createStore()` | `isStore()` |
+| List | `src/nodes/list.ts` | `createList()` | `isList()` |
+| Collection | `src/nodes/collection.ts` | `createCollection()` / `deriveCollection()` | `isCollection()` |
+
+`match()` and `MatchHandlers` live in `src/nodes/effect.ts` alongside `createEffect`.
+</signal_source_files>
+
+<quick_lookup>
+- Changing a signal's public API → read the signal's source file + `index.ts` + the relevant section of `README.md`
+- Changing graph traversal, flags, or flush order → read `src/graph.ts` + `ARCHITECTURE.md`
+- Adding or changing error conditions → read `src/errors.ts`
+- Adding a shared utility → check `src/util.ts` first; add there if it belongs to multiple nodes
+- Checking type constraints or TS-specific decisions → read `CLAUDE.md`
+- Verifying a feature is in scope → read `REQUIREMENTS.md`
+</quick_lookup>