@pumped-fn/lite 1.11.3 → 1.11.4

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @pumped-fn/lite
 
+## 1.11.4
+
+### Patch Changes
+
+- a3ae2b7: Replace text glossary with mermaid sequence diagrams in documentation
+
+  - README.md now uses visual diagrams for composition, atom lifecycle, tag resolution, type utilities, and API surface
+  - PATTERNS.md converted all usage patterns to sequence diagrams for clarity
+
 ## 1.11.3
 
 ### Patch Changes

package/PATTERNS.md

@@ -1,380 +1,263 @@
-# Architectural Patterns
+# Patterns
 
-Design patterns implemented by `@pumped-fn/lite` and how to compose them for application architecture.
+Usage patterns as sequences. For API details, see `packages/lite/dist/index.d.mts`.
 
-## Composite Patterns
+## A. Fundamental Usage
 
 ### Request Lifecycle
 
-**Combines:** IoC Container + Command + Composite
-
-| GoF Pattern | Primitive |
-|-------------|-----------|
-| IoC Container | `Scope` (long-lived, caches atoms) |
-| Command | `Flow` (operations within request) |
-| Composite | `ExecutionContext` (parent-child with isolated data) |
-
-**Key Insight:**
-- `Scope` = application container (atoms cached here)
-- `ExecutionContext` = request boundary (data lives here, closed at request end)
-- `Flow` / `ctx.exec` = operations within the request (share context via `seekTag`)
+Model a request boundary with cleanup and shared context.
 
 ```mermaid
 sequenceDiagram
     participant App
     participant Scope
-    participant Context as ExecutionContext
-    participant ServiceAtom as Service Atom
-    participant Flow1 as Flow (validate)
-    participant Flow2 as Flow (process)
-
-    Note over Scope: Long-lived (app lifetime)
-    App->>Scope: resolve(serviceAtom)
-    Scope-->>App: service (cached)
+    participant Ctx as ExecutionContext
+    participant Flow
 
-    Note over Context: Per-request boundary
-    App->>Scope: createContext({ tags: [requestId, userId] })
+    App->>Scope: createScope()
+    App->>Scope: scope.createContext({ tags })
     Scope-->>App: ctx
 
-    App->>Context: ctx.data.setTag(TX_TAG, beginTransaction())
-    App->>Context: ctx.onClose(() => tx.rollback())
-
-    App->>Context: ctx.exec({ flow: validateFlow, input })
-    Context->>Scope: resolve flow deps (atoms)
-    Scope-->>Context: deps (cached in scope)
-    Context->>Flow1: factory(childCtx, deps)
-    Note over Flow1: childCtx.parent = ctx
-    Flow1->>Flow1: tags.required(userIdTag) from merged tags
-    Flow1-->>Context: validated
-
-    App->>Context: ctx.exec({ flow: processFlow, input: validated })
-    Context->>Scope: resolve flow deps (atoms)
-    Scope-->>Context: deps (from cache)
-    Context->>Flow2: factory(childCtx, deps)
-    Flow2->>Flow2: childCtx.exec({ fn: service.save, params: [data] })
-    Note over Flow2: Creates grandchildCtx
-    Flow2->>ServiceAtom: service.save(grandchildCtx, data)
-    ServiceAtom->>ServiceAtom: grandchildCtx.data.seekTag(TX_TAG)
-    Note over ServiceAtom: seekTag traverses parent chain
-    ServiceAtom-->>Flow2: saved
-    Flow2-->>Context: result
-
-    App->>Context: ctx.data.getTag(TX_TAG).commit()
-    App->>Context: ctx.close()
-    Context->>Context: onClose cleanups run (rollback skipped)
-```
+    App->>Ctx: ctx.exec({ flow, input, tags })
+    Ctx->>Flow: factory(childCtx, deps)
+    Flow-->>Ctx: output
+    Ctx->>Ctx: childCtx.close()
+    Ctx-->>App: output
 
-**Characteristics:**
-- Scope caches atoms across requests (resolve once, use many)
-- ExecutionContext bounds request lifecycle (`onClose` for cleanup)
-- Each `exec()` creates child context with isolated `data` Map
-- `seekTag()` traverses parent chain for shared data (e.g., transaction)
-- `ctx.close()` runs all `onClose` cleanups (LIFO order)
-- On error: child context auto-closes, cleanups still run
+    App->>Ctx: ctx.onClose(cleanup)
+    App->>Ctx: ctx.close()
+    Ctx->>Ctx: run cleanups (LIFO)
+```
 
-**Primitives:** `createScope()`, `scope.createContext()`, `ctx.exec()`, `ctx.data.setTag/seekTag()`, `ctx.onClose()`, `ctx.close()`
+### Extensions Pipeline
 
----
+Observe and wrap timing for atoms/flows (logging, auth, tracing).
 
-### Flow Deps & Execution
+```mermaid
+sequenceDiagram
+    participant App
+    participant Scope
+    participant Ext as Extension
+    participant Atom
+    participant Flow
 
-**Combines:** Command + Composite + Resource Management
+    App->>Scope: createScope({ extensions: [ext] })
+    Scope->>Ext: ext.init(scope)
+    App->>Scope: await scope.ready
+
+    App->>Scope: resolve(atom)
+    Scope->>Ext: wrapResolve(next, atom, scope)
+    Ext->>Ext: before logic
+    Ext->>Atom: next()
+    Atom-->>Ext: value
+    Ext->>Ext: after logic
+    Ext-->>Scope: value
+
+    App->>Scope: ctx.exec({ flow })
+    Scope->>Ext: wrapExec(next, flow, ctx)
+    Ext->>Flow: next()
+    Flow-->>Ext: output
+    Ext-->>Scope: output
+
+    App->>Scope: dispose()
+    Scope->>Ext: ext.dispose(scope)
+```
 
-| Concern | Primitive |
-|---------|-----------|
-| Dependency injection | `deps` (atoms from Scope, tags from context hierarchy) |
-| Service invocation | `ctx.exec({ fn, params })` (observable by extensions) |
-| Resource cleanup | `ctx.onClose()` (LIFO, runs on success or failure) |
+### Scoped Isolation + Testing
 
-**Deps Resolution:**
+Swap implementations and isolate tenants/tests.
 
 ```mermaid
-flowchart TB
-    subgraph Flow["flow({ deps, factory })"]
-        Deps["deps: { db: dbAtom, userId: tags.required(userIdTag) }"]
-    end
+sequenceDiagram
+    participant Test
+    participant Scope
+    participant Atom
 
-    subgraph Resolution
-        Deps --> AtomPath["Atom deps"]
-        Deps --> TagPath["Tag deps (TagExecutor)"]
+    Test->>Scope: createScope({ presets: [preset(dbAtom, mockDb)], tags: [tenantTag(id)] })
+    Test->>Scope: resolve(dbAtom)
+    Scope-->>Test: mockDb (not real db)
 
-        AtomPath --> Scope["Scope.resolve()"]
-        Scope --> |"cached in scope"| ResolvedAtom["db instance"]
+    Test->>Scope: createContext()
+    Scope-->>Test: ctx with tenantTag
+```
 
-        TagPath --> CtxHierarchy["ctx.data.seekTag()"]
-        CtxHierarchy --> |"traverses parent chain"| ResolvedTag["userId value"]
-    end
+## B. Advanced Client/State Usage
 
-    subgraph Factory["factory(ctx, { db, userId })"]
-        ResolvedAtom --> DepsObj["deps object"]
-        ResolvedTag --> DepsObj
-    end
-```
+### Controller Reactivity
 
-**Service Invocation:**
+Client-side state with lifecycle hooks and invalidation.
 
 ```mermaid
 sequenceDiagram
-    participant Flow
-    participant Ctx as ExecutionContext
-    participant Ext as Extension.wrapExec
-    participant Fn as service.method
-
-    Note over Flow: ❌ Direct call
-    Flow->>Fn: service.method(ctx, data)
-    Note over Fn: Extensions cannot observe
-
-    Note over Flow: ✅ Via ctx.exec
-    Flow->>Ctx: ctx.exec({ fn: service.method, params: [data] })
-    Ctx->>Ctx: create childCtx (parent = ctx)
-    Ctx->>Ext: wrapExec(next, fn, childCtx)
-    Ext->>Fn: next()
-    Fn-->>Ext: result
-    Ext-->>Ctx: result
-    Ctx->>Ctx: childCtx.close()
-    Ctx-->>Flow: result
-```
+    participant App
+    participant Scope
+    participant Ctrl as Controller
+    participant Atom
 
-**Cleanup Pattern:**
+    App->>Scope: controller(atom)
+    Scope-->>App: ctrl
 
-```mermaid
-sequenceDiagram
-    participant Flow
-    participant Ctx as ExecutionContext
-    participant Tx as Transaction
-
-    Flow->>Tx: beginTransaction()
-    Tx-->>Flow: tx
-    Flow->>Ctx: ctx.onClose(() => tx.rollback())
-
-    alt Success
-        Flow->>Flow: do work
-        Flow->>Tx: tx.commit()
-        Flow->>Ctx: return result
-        Ctx->>Ctx: close() → rollback() is no-op
-    else Error
-        Flow->>Flow: do work (throws)
-        Ctx->>Ctx: close() → rollback() executes
-        Ctx->>Tx: tx.rollback()
-    end
-```
+    App->>Ctrl: ctrl.on('resolving' | 'resolved' | '*', listener)
+    Ctrl-->>App: unsubscribe
 
-**Characteristics:**
-- Atoms resolve via `Scope.resolve()` (cached, long-lived)
-- Tag deps resolve via `ctx.data.seekTag()` (traverses parent → grandparent → scope tags)
-- `ctx.exec({ fn, params })` creates child context with isolated `data` Map
-- Extensions intercept via `wrapExec(next, target, ctx)`
-- Register pessimistic cleanup via `ctx.onClose(fn)`, neutralize on success
+    App->>Ctrl: ctrl.get()
+    Ctrl-->>App: current value
 
-**Primitives:** `flow({ deps })`, `tags.required()`, `tags.optional()`, `tags.all()`, `ctx.exec()`, `ctx.onClose()`
+    App->>Ctrl: ctrl.set(newValue)
+    Ctrl->>Ctrl: notify listeners
 
----
+    App->>Ctrl: ctrl.update(v => v + 1)
+    Ctrl->>Ctrl: notify listeners
 
-### Request Pipeline
+    App->>Ctrl: ctrl.invalidate()
+    Ctrl->>Atom: re-run factory
+    Ctrl->>Ctrl: notify listeners
+```
 
-**Combines:** Command + Interceptor + Context Object
+### Ambient Context (Tags)
 
-| GoF Pattern | Primitive |
-|-------------|-----------|
-| Command | `Flow` (encapsulates request with input/output) |
-| Interceptor | `Extension.wrapExec()` (wraps execution) |
-| Context Object | `Tag` (propagates metadata without explicit passing) |
+Propagate state without wiring parameters (app shell, user, locale).
 
 ```mermaid
 sequenceDiagram
-    participant Client
-    participant Scope
-    participant Extension1 as Extension (Auth)
-    participant Extension2 as Extension (Tracing)
-    participant Flow
-    participant Context as ExecutionContext
-
-    Client->>Scope: createContext({ tags: [requestId] })
-    Scope-->>Client: ctx
-    Client->>Context: exec({ flow, input, tags: [userId] })
-
-    Context->>Context: merge tags (flow → scope → context → exec)
-    Context->>Context: create child context
-
-    Context->>Extension1: wrapExec(next, flow, childCtx)
-    Extension1->>Extension1: extract userId tag, validate
-    Extension1->>Extension2: next()
-    Extension2->>Extension2: read parent span from ctx.parent?.data
-    Extension2->>Extension2: create child span, store in ctx.data
-    Extension2->>Flow: next()
-    Flow->>Flow: factory(ctx, deps) with tags.required(userId)
-    Flow-->>Extension2: result
-    Extension2->>Extension2: end span
-    Extension2-->>Extension1: result
-    Extension1-->>Context: result
-    Context->>Context: auto-close child (run onClose cleanups)
-    Context-->>Client: result
-```
-
-**Characteristics:**
-- Extensions wrap in registration order (outer → inner)
-- Each `exec()` creates isolated child context with own `data` Map
-- Tags merge with later sources winning (exec tags override flow tags)
-- Parent chain enables span correlation without AsyncLocalStorage
+    participant App
+    participant Ctx as ExecutionContext
+    participant ChildCtx
+    participant Data as ctx.data
 
-**Primitives:** `flow()`, `Extension.wrapExec`, `tag()`, `ctx.exec()`, `ctx.parent`, `ctx.data`
+    App->>Data: ctx.data.setTag(userTag, user)
+    App->>Ctx: ctx.exec({ flow, tags: [localeTag('en')] })
+    Ctx->>ChildCtx: create with merged tags
 
----
+    ChildCtx->>Data: ctx.data.seekTag(userTag)
+    Data-->>ChildCtx: user (from parent)
 
-### Scoped Isolation
+    ChildCtx->>Data: ctx.data.getTag(localeTag)
+    Data-->>ChildCtx: 'en'
+```
 
-**Combines:** IoC Container + Strategy + Composite
+### Derived State (Select)
 
-| GoF Pattern | Primitive |
-|-------------|-----------|
-| IoC Container | `Scope` (manages atom lifecycles and resolution) |
-| Strategy | `Preset` (swap implementations at scope creation) |
-| Composite | `ExecutionContext` (parent-child isolation) |
+Subscribe to a slice of atom state with custom equality.
 
 ```mermaid
 sequenceDiagram
     participant App
-    participant TenantScope as Scope (Tenant A)
-    participant TestScope as Scope (Test)
-    participant DbAtom as dbAtom
-    participant MockDb as mockDbAtom
-
-    Note over App: Production - Tenant A
-    App->>TenantScope: createScope({ tags: [tenantId('A')] })
-    App->>TenantScope: resolve(dbAtom)
-    TenantScope->>DbAtom: factory(ctx, deps)
-    DbAtom->>DbAtom: tags.required(tenantId) → 'A'
-    DbAtom-->>TenantScope: TenantA DB connection
-
-    Note over App: Test - Mocked DB
-    App->>TestScope: createScope({ presets: [preset(dbAtom, mockDbAtom)] })
-    App->>TestScope: resolve(dbAtom)
-    TestScope->>TestScope: check presets → found
-    TestScope->>MockDb: resolve mockDbAtom instead
-    MockDb-->>TestScope: Mock DB instance
-
-    Note over App: Parallel tenant contexts
-    par Tenant A request
-        TenantScope->>TenantScope: createContext({ tags: [requestId('r1')] })
-    and Tenant B request
-        TenantScope->>TenantScope: createContext({ tags: [requestId('r2')] })
-    end
-    Note over TenantScope: Each context isolated, same scope
-```
-
-**Characteristics:**
-- Each Scope is an isolated DI container with own cache
-- Presets swap atom implementations without changing definitions
-- Tags at scope level apply to all resolutions
-- Multiple ExecutionContexts share scope but isolate request data
-- Child contexts inherit parent tags, can override
+    participant Scope
+    participant Handle as SelectHandle
+    participant Atom
 
-**Use Cases:**
-- Multi-tenancy: scope-level tenant tag, context-level request isolation
-- Testing: preset mocks without touching production atom definitions
-- Feature flags: preset alternative implementations per environment
+    App->>Scope: select(atom, v => v.count, { eq: shallowEqual })
+    Scope-->>App: handle
 
-**Primitives:** `createScope()`, `preset()`, `tag()`, `createContext()`, scope `tags` option
+    App->>Handle: handle.get()
+    Handle-->>App: selected value
 
----
+    App->>Handle: handle.subscribe(listener)
+    Handle-->>App: unsubscribe
 
-## Foundational Patterns
+    Note over Atom,Handle: atom changes
+    Handle->>Handle: eq(prev, next)?
+    Handle->>App: notify if changed
+```
 
-### IoC Container
+### Service Pattern
 
-**GoF:** Inversion of Control / Dependency Injection Container
+Constrain atom methods to ExecutionContext-first signature for tracing/auth.
 
 ```mermaid
-graph TB
-    Scope["Scope (Container)"]
-    AtomA["Atom A"]
-    AtomB["Atom B"]
-    AtomC["Atom C"]
-    Cache["Resolution Cache"]
-
-    Scope -->|resolve| AtomA
-    Scope -->|resolve| AtomB
-    AtomB -->|deps| AtomA
-    AtomC -->|deps| AtomA
-    AtomC -->|deps| AtomB
-    Scope --- Cache
-```
-
-**Primitives:** `createScope()`, `atom()`, `deps`, `scope.resolve()`
+sequenceDiagram
+    participant App
+    participant Scope
+    participant Ctx as ExecutionContext
+    participant Svc as Service Atom
 
-**Characteristics:** Lazy resolution, automatic caching, dependency graph traversal, circular dependency detection.
+    App->>Scope: resolve(userService)
+    Scope-->>App: { getUser, updateUser }
 
----
+    App->>Ctx: svc.getUser(ctx, userId)
+    Ctx->>Svc: traced execution
+    Svc-->>Ctx: user
+    Ctx-->>App: user
+```
 
-### Observer
+### Typed Flow Input
 
-**GoF:** Observer Pattern with State Machine
+Type flow input without runtime parsing overhead.
 
 ```mermaid
-stateDiagram-v2
-    [*] --> idle
-    idle --> resolving: resolve()
-    resolving --> resolved: success
-    resolving --> failed: error
-    resolved --> resolving: invalidate()
-    failed --> resolving: invalidate()
-
-    note right of resolving: listeners notified
-    note right of resolved: listeners notified
+sequenceDiagram
+    participant App
+    participant Flow
+    participant Ctx
+
+    Note over Flow: flow({ parse: typed<T>(), factory })
+    App->>Flow: ctx.exec({ flow, input: typedInput })
+    Flow->>Flow: skip parse (type-only)
+    Flow->>Ctx: factory(ctx) with ctx.input: T
+    Ctx-->>App: output
 ```
 
-**Primitives:** `controller()`, `ctrl.on('resolved' | 'resolving' | '*')`, `ctrl.invalidate()`
+### Controller as Dependency
 
-**Characteristics:** State-filtered subscriptions, LIFO cleanup before re-resolution, sequential invalidation chains with loop detection.
+Receive reactive handle instead of resolved value in atom/flow deps.
 
----
+```mermaid
+sequenceDiagram
+    participant Scope
+    participant AtomA as serverAtom
+    participant Ctrl as Controller
+    participant AtomB as configAtom
+
+    Scope->>AtomA: resolve(serverAtom)
+    Note over AtomA: deps: { cfg: controller(configAtom, { resolve: true }) }
+    AtomA->>Scope: resolve configAtom first
+    Scope-->>Ctrl: ctrl (already resolved)
+    AtomA->>AtomA: factory(ctx, { cfg: ctrl })
+    AtomA->>Ctrl: ctrl.on('resolved', () => ctx.invalidate())
+    Note over AtomA: react to config changes
+```
 
-### Context Object
+### Inline Function Execution
 
-**GoF:** Context Object / Ambient Context
+Execute ad-hoc logic within context without defining a flow.
 
 ```mermaid
-graph TB
-    subgraph Sources
-        FlowTags[Flow tags]
-        ScopeTags[Scope tags]
-        CtxTags[Context tags]
-        ExecTags[Exec tags]
-    end
-
-    subgraph Merge[Tag Merge - later wins]
-        FlowTags --> Merged
-        ScopeTags --> Merged
-        CtxTags --> Merged
-        ExecTags --> Merged
-    end
+sequenceDiagram
+    participant App
+    participant Ctx as ExecutionContext
 
-    subgraph Extract
-        Merged --> Required[tags.required]
-        Merged --> Optional[tags.optional]
-        Merged --> All[tags.all]
-    end
+    App->>Ctx: ctx.exec({ fn: (ctx, a, b) => a + b, params: [1, 2], tags })
+    Ctx->>Ctx: create childCtx with tags
+    Ctx->>Ctx: fn(childCtx, 1, 2)
+    Ctx->>Ctx: childCtx.close()
+    Ctx-->>App: 3
 ```
 
-**Primitives:** `tag()`, `tags.required()`, `tags.optional()`, `tags.all()`, `Tagged`
+### Atom Retention (GC)
 
-**Characteristics:** Implicit propagation through execution layers, type-safe extraction, merge precedence (exec > context > scope > flow).
+Control when atoms are garbage collected or kept alive indefinitely.
 
----
+```mermaid
+sequenceDiagram
+    participant App
+    participant Scope
+    participant Atom
 
-### Strategy
+    App->>Scope: createScope({ gc: { enabled: true, graceMs: 3000 } })
 
-**GoF:** Strategy Pattern
+    App->>Scope: resolve(atom)
+    Scope-->>App: value
+    Note over Scope: no refs → start grace timer
 
-```mermaid
-graph TB
-    Scope -->|resolve| Atom
-    Atom -->|check| Presets{Preset?}
-    Presets -->|value| Direct[Return value]
-    Presets -->|atom| Redirect[Resolve other atom]
-    Presets -->|none| Factory[Run factory]
-```
-
-**Primitives:** `preset()`, `createScope({ presets })`, `isPreset()`
+    alt keepAlive: true
+        Note over Atom: never GC'd
+    else graceMs expires
+        Scope->>Atom: release()
+        Atom->>Atom: run cleanups
+    end
 
-**Characteristics:** Swap implementations at scope creation, value injection bypasses factory, atom redirection for mock substitution.
+    App->>Scope: flush()
+    Note over Scope: wait all pending
+```

package/README.md

@@ -1,442 +1,230 @@
 # @pumped-fn/lite
 
-A lightweight effect system for TypeScript with managed lifecycles and minimal reactivity.
+Lightweight effect system for TypeScript: scoped lifecycles, tagged context, and opt‑in reactivity.
 
-**Zero dependencies** · **<17KB bundle** · **Full TypeScript support**
-
-## Documentation
-
-| Resource | Purpose |
-|----------|---------|
-| [PATTERNS.md](./PATTERNS.md) | Architecture patterns, flow design, deps resolution, cleanup strategies |
-| [dist/index.d.mts](./dist/index.d.mts) | API reference with TSDoc |
+Docs: `packages/lite/PATTERNS.md` for usage patterns, `packages/lite/dist/index.d.mts` for API details.
 
 ## How It Works
 
 ```mermaid
 sequenceDiagram
-    participant User
+    participant App
     participant Scope
+    participant Ext as Extension
+    participant Ctx as ExecutionContext
     participant Atom
+    participant Flow
+    participant Ctrl as Controller
+
+    App->>Scope: createScope({ extensions, presets, tags })
+    Scope-->>App: scope (ready)
+
+    App->>Scope: resolve(atom)
+    Scope->>Ext: wrapResolve(next, atom)
+    Ext->>Atom: factory(ctx, deps)
+    Atom-->>Scope: value (cached)
+
+    App->>Scope: createContext({ tags })
+    Scope-->>App: ctx
+
+    App->>Ctx: ctx.exec({ flow, input, tags })
+    Ctx->>Ctx: merge tags, create childCtx
+    Ctx->>Ext: wrapExec(next, flow, childCtx)
+    Ext->>Flow: parse(input) + factory(childCtx, deps)
+    Flow-->>Ext: output
+    Ext-->>Ctx: output
+    Ctx->>Ctx: childCtx.close() (onClose LIFO)
+    Ctx-->>App: output
+
+    rect rgb(240, 248, 255)
+        Note over App,Ctrl: Reactivity (opt‑in)
+        App->>Scope: controller(atom)
+        Scope-->>Ctrl: ctrl
+        App->>Ctrl: ctrl.get() / ctrl.resolve()
+        Ctrl-->>App: value
+        App->>Ctrl: ctrl.set(v) / ctrl.update(fn)
+        App->>Ctrl: ctrl.on('resolved', listener)
+        Ctrl-->>App: unsubscribe
+        App->>Ctrl: ctrl.invalidate()
+        Ctrl->>Atom: re‑run factory
+        App->>Ctrl: ctrl.release()
+        App->>Scope: release(atom)
+        Scope->>Scope: run cleanups, remove cache
+        App->>Scope: select(atom, selector, { eq })
+        Scope-->>App: { get, subscribe }
+        App->>Scope: on('resolved', atom, listener)
+        Scope-->>App: unsubscribe
+    end
 
-    User->>Scope: createScope(options?)
-    Scope-->>User: scope
-    User->>Scope: await scope.ready
-
-    User->>Scope: scope.resolve(atom)
-    alt preset exists
-        Scope-->>User: preset value (factory skipped)
-    else no preset
-        Scope->>Atom: factory(ctx, deps)
-        Atom-->>Scope: value (cached)
-        Scope-->>User: value
+    rect rgb(255, 250, 240)
+        Note over App,Scope: Introspection
+        App->>App: isAtom(v), isFlow(v), isTag(v), isTagged(v)
+        App->>App: isPreset(v), isControllerDep(v), isTagExecutor(v)
+        App->>App: getAllTags() → Tag[]
     end
 
-    User->>Scope: scope.dispose()
-    Scope->>Atom: run cleanups, release all
+    App->>Scope: flush()
+    Note right of Scope: wait pending ops
+    App->>Ctx: ctx.close()
+    Ctx->>Ctx: run onClose (LIFO)
+    App->>Scope: dispose()
+    Scope->>Scope: release atoms, run cleanups
 ```
 
-## Invalidation & Data Retention
+## Composition
 
 ```mermaid
-sequenceDiagram
-    participant User
-    participant Controller
-    participant Atom
-    participant DataStore as ctx.data
-
-    Note over DataStore: persists across invalidations
-
-    User->>Controller: ctrl.invalidate()
-    Controller->>Atom: run cleanups (LIFO)
-    Note over DataStore: retained
-    Controller->>Atom: state = resolving
-    Controller->>Atom: factory(ctx, deps)
-    Note right of Atom: ctx.data still has previous values
-    Atom-->>Controller: new value
-    Controller->>Atom: state = resolved
-    Controller-->>User: listeners notified
-```
-
-## Flow Execution
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant Scope
-    participant Context as ExecutionContext
-    participant Flow
-
-    User->>Scope: scope.createContext(options?)
-    Scope-->>User: context
+graph LR
+    subgraph Primitives
+        atom["atom({ factory, deps?, tags?, keepAlive? })"]
+        flow["flow({ factory, parse?, deps?, tags? })"]
+        service["service({ factory, deps? })"]
+        tag["tag({ label, default?, parse? })"]
+        preset["preset(target, value)"]
+    end
 
-    User->>Context: ctx.exec({ flow, input, tags? })
-    Context->>Flow: parse(input)
-    Context->>Context: resolve flow deps
-    Context->>Flow: factory(ctx, deps)
-    Flow-->>Context: output
-    Context-->>User: output
+    subgraph Wrappers
+        typed["typed&lt;T&gt;()"]
+        ctrlDep["controller(atom, { resolve? })"]
+        tagExec["tags.required/optional/all(tag)"]
+    end
 
-    User->>Context: ctx.close()
-    Context->>Context: run onClose cleanups (LIFO)
+    flow --> typed
+    atom --> ctrlDep
+    tag --> tagExec
 ```
 
-## Tag Inheritance (ADR-023)
-
-Tags are auto-populated into `ctx.data` and resolved via `seekTag()`:
+## Context Data
 
 ```mermaid
-flowchart TD
-    subgraph Root["Root Context (ctx.data)"]
-        S["scope.tags → auto-populated"]
-        C["context.tags → auto-populated"]
-        subgraph Child["Child Context (exec)"]
-            E["exec.tags → auto-populated"]
-            F["flow.tags → auto-populated"]
-            D["ctx.data.setTag() → runtime"]
-            subgraph Deps["tags.required(tag)"]
-                R["seekTag() traverses: Child → Root"]
-            end
-        end
+graph TD
+    subgraph "ctx.data"
+        raw["Raw: get/set/has/delete/clear/seek"]
+        typed["Typed: getTag/setTag/hasTag/deleteTag/seekTag/getOrSetTag"]
     end
-
-    Note["Nearest value wins. Propagates to all descendants."]
+    raw --> typed
 ```
 
-## Controller Reactivity
+## Atom Lifecycle (AtomState)
 
 ```mermaid
-sequenceDiagram
-    participant User
-    participant Controller
-    participant Atom
-
-    User->>Controller: scope.controller(atom)
-    User->>Controller: ctrl.on('resolved', listener)
-    Controller-->>User: unsubscribe fn
-
-    Note over Controller: atom invalidated elsewhere
-
-    Controller->>Atom: state = resolving
-    Controller-->>User: 'resolving' listeners fire
-    Atom-->>Controller: new value
-    Controller->>Atom: state = resolved
-    Controller-->>User: 'resolved' listeners fire
-
-    User->>Controller: ctrl.get()
-    Controller-->>User: current value
+stateDiagram-v2
+    [*] --> idle
+    idle --> resolving: resolve() / controller()
+    resolving --> resolved: factory completes
+    resolving --> failed: factory throws
+    resolved --> resolving: invalidate()
+    resolved --> idle: release()
+    failed --> resolving: invalidate()
+    failed --> idle: release()
 ```
 
-## Primitives
-
-### Scope
-
-Entry point. Manages atom lifecycles, caching, and cleanup orchestration.
-
-- `createScope(options?)` — create with optional extensions, presets, tags
-- `scope.ready` — wait for extension initialization
-- `scope.resolve(atom)` — resolve and cache
-- `scope.controller(atom)` — get reactive handle
-- `scope.release(atom)` — run cleanups, remove from cache
-- `scope.dispose()` — release all, cleanup extensions
-- `scope.createContext(options?)` — create execution context for flows
-- `scope.select(atom, selector)` — fine-grained reactivity
-- `scope.flush()` — wait for pending invalidations
-
-### Atom
-
-Long-lived cached dependency with lifecycle.
-
-- Dependencies on other atoms via `deps`
-- `ctx.cleanup(fn)` — runs on invalidate and release (LIFO order)
-- `ctx.invalidate()` — schedule re-resolution
-- `ctx.data` — storage that survives invalidation (cleared on release)
-- `ctx.data.getOrSetTag(tag, defaultValue)` — initialize and retrieve in one call
-
-### Flow
-
-Short-lived operation with input/output.
-
-- `parse` — validate/transform input before factory (throws `ParseError` on failure)
-- `typed<T>()` — type marker without runtime parsing
-- Dependencies on atoms via `deps`
-- `ctx.input` — typed input access
-- `ctx.onClose(fn)` — cleanup when context closes
-- `ctx.exec({ flow, rawInput })` — pass unknown input when flow has `parse`
-
-### Tag
-
-Contextual value passed through execution without explicit wiring.
-
-- Hierarchical lookup via `seekTag()` (ADR-023)
-- Auto-populates into `ctx.data`: scope → context → exec → flow
-- Registry tracks atom↔tag relationships (ADR-026)
+## Tag Resolution
 
 ```mermaid
-flowchart TD
-    subgraph "Tag Registry (ADR-026)"
-        direction LR
-        A["atom({ tags: [...] })"] -->|auto-register| R["WeakMap⟨Tag, WeakRef⟨Atom⟩[]⟩"]
-        R -->|"tag.atoms()"| Q["query atoms by tag"]
-        R -->|"getAllTags()"| T["query all tags"]
-    end
-
-    subgraph "Tag Inheritance (ADR-023)"
-        S[scope.tags] --> D[ctx.data]
-        C[context.tags] --> D
-        E[exec.tags] --> D
-        F[flow.tags] --> D
-        D -->|"seekTag()"| V["nearest value wins"]
-    end
-```
-
-Memory: `WeakRef` allows GC of unused atoms/tags. Cleanup on query.
-
-### Controller
-
-Reactive handle for observing and controlling atom state.
-
-- `ctrl.state` — sync access: `'idle' | 'resolving' | 'resolved' | 'failed'`
-- `ctrl.get()` — sync value access (throws if not resolved, returns stale during resolving)
-- `ctrl.resolve()` — async resolution
-- `ctrl.invalidate()` — trigger re-resolution (runs factory)
-- `ctrl.set(value)` — replace value directly (skips factory)
-- `ctrl.update(fn)` — transform value: `fn(currentValue) → newValue` (skips factory)
-- `ctrl.on(event, listener)` — subscribe to `'resolved' | 'resolving' | '*'`
-- Use `controller(atom)` in deps for reactive dependency (unresolved, you control timing)
-- Use `controller(atom, { resolve: true })` to auto-resolve before passing to factory
-- Use `scope.controller(atom, { resolve: true })` for same behavior outside deps
-
-### Preset
+sequenceDiagram
+    participant App
+    participant Tag
+    participant Source as Atom/Flow/Ctx
 
-Value injection for testing. Bypasses factory entirely.
+    App->>Tag: tag({ label, default? })
+    Tag-->>App: Tag<T>
 
-- `preset(atom, value)` — inject direct value
-- `preset(atom, otherAtom)` — redirect to another atom's factory
-- Pass via `createScope({ presets: [...] })`
+    App->>Tag: tag(value)
+    Tag-->>App: Tagged<T>
 
-### Extension
+    App->>Source: attach Tagged[] to atom/flow/ctx
 
-AOP-style middleware for cross-cutting concerns.
+    App->>Tag: tag.get(source)
+    Tag->>Source: find first match
+    Source-->>Tag: value or throw
 
-- `init(scope)` — setup when scope created
-- `wrapResolve(next, atom, scope)` — intercept atom resolution
-- `wrapExec(next, target, ctx)` — intercept flow execution
-- `dispose(scope)` — cleanup when scope disposed
-- Pass via `createScope({ extensions: [...] })`
+    App->>Tag: tag.find(source)
+    Tag->>Source: find first match
+    Source-->>Tag: value or undefined
 
-## Patterns
+    App->>Tag: tag.collect(source)
+    Tag->>Source: gather all matches
+    Source-->>Tag: T[]
 
-### Eager Resolution via Tag Registry
+    App->>Tag: tag.atoms()
+    Tag-->>App: Atom[] with this tag
+```
 
-Use tags to mark atoms for eager resolution without hardcoding atom references:
+## Type Utilities
 
 ```mermaid
-flowchart LR
-    subgraph "Define"
-        T[eagerTag] --> A1[atomA]
-        T --> A2[atomB]
-        T --> A3[atomC]
+graph LR
+    subgraph "Lite.Utils"
+        AtomValue["AtomValue&lt;A&gt;"]
+        FlowOutput["FlowOutput&lt;F&gt;"]
+        FlowInput["FlowInput&lt;F&gt;"]
+        TagValue["TagValue&lt;T&gt;"]
+        DepsOf["DepsOf&lt;A|F&gt;"]
+        ControllerValue["ControllerValue&lt;C&gt;"]
+        Simplify["Simplify&lt;T&gt;"]
+        AtomType["AtomType&lt;T, D&gt;"]
+        FlowType["FlowType&lt;O, I, D&gt;"]
     end
 
-    subgraph "Extension init()"
-        E["eagerTag.atoms()"] --> R["resolve all marked atoms"]
+    subgraph "Type Guards"
+        isAtom
+        isFlow
+        isTag
+        isTagged
+        isPreset
+        isControllerDep
+        isTagExecutor
     end
 
-    A1 & A2 & A3 -.->|"auto-tracked"| E
-```
-
-### Extension Discovery via getAllTags()
-
-Extensions can discover and process all tags at runtime:
-
-```mermaid
-flowchart LR
-    subgraph "Runtime"
-        G["getAllTags()"] --> F{"filter by criteria"}
-        F --> P["process matching tags"]
-        P --> A["tag.atoms() for each"]
+    subgraph "Convenience"
+        AnyAtom
+        AnyFlow
+        AnyController
     end
 ```
 
-Use cases: metrics collection, debugging, documentation generation.
-
-## Types
-
-All types available under the `Lite` namespace:
-
-```typescript
-import type { Lite } from '@pumped-fn/lite'
-```
-
-## Edge Cases
-
-### Controller.set() / update()
-
-| State | Behavior |
-|-------|----------|
-| `idle` | Throws "Atom not resolved" |
-| `resolving` | Queues, applies after resolution completes |
-| `resolved` | Queues normally |
-| `failed` | Throws the stored error |
-
-Both run cleanups before applying the new value.
-
-### ContextData.getTag()
-
-`ctx.data.getTag(tag)` always returns `T | undefined` (Map-like semantics). Use `getOrSetTag(tag)` when you need the tag's default value.
-
-```typescript
-const countTag = tag<number>({ label: 'count', default: 0 })
-
-ctx.data.getTag(countTag)       // undefined (not stored)
-ctx.data.getOrSetTag(countTag)  // 0 (uses default, now stored)
-ctx.data.getTag(countTag)       // 0 (now stored)
-```
-
-### Hierarchical Data Lookup with seekTag() (ADR-023)
-
-Tag dependencies (`tags.required()`, `tags.optional()`, `tags.all()`) use `seekTag()` internally to traverse the ExecutionContext parent chain. Tags from all sources are auto-populated into `ctx.data`:
-
-```typescript
-const requestIdTag = tag<string>({ label: 'requestId' })
-
-const middleware = flow({
-  factory: async (ctx) => {
-    ctx.data.setTag(requestIdTag, 'req-123')
-    return ctx.exec({ flow: handler })
-  }
-})
-
-const handler = flow({
-  deps: { reqId: tags.required(requestIdTag) },
-  factory: (ctx, { reqId }) => {
-    // reqId === 'req-123' (found via seekTag from parent)
-  }
-})
-```
-
-| Method | Scope | Use Case |
-|--------|-------|----------|
-| `getTag(tag)` | Local only | Per-exec isolated data |
-| `seekTag(tag)` | Local → parent → root | Cross-cutting concerns |
-| `setTag(tag, v)` | Local only | Always writes to current context |
-| `tags.required(tag)` | Uses `seekTag()` | Dependency injection |
-
-### Resolution Timing
-
-Tag dependencies resolve **once** at factory start. Direct `seekTag()` calls reflect runtime changes:
-
-```typescript
-const handler = flow({
-  deps: { userId: tags.required(userIdTag) },
-  factory: (ctx, { userId }) => {
-    ctx.data.setTag(userIdTag, 'changed')
-
-    console.log(userId)                      // Original (stable)
-    console.log(ctx.data.seekTag(userIdTag)) // 'changed' (dynamic)
-  }
-})
-```
-
-| Access | Resolution | Runtime Changes |
-|--------|------------|-----------------|
-| `deps: { x: tags.required(tag) }` | Once at start | Stable snapshot |
-| `ctx.data.seekTag(tag)` | Each call | Sees changes |
-
-## Automatic Garbage Collection
-
-Atoms are automatically released when they have no subscribers, preventing memory leaks in long-running applications.
-
-### How It Works
+## Introspection
 
 ```mermaid
 sequenceDiagram
-    participant Component
-    participant Controller
-    participant Scope
-    participant Timer
-
-    Component->>Controller: ctrl.on('resolved', callback)
-    Note over Controller: subscriberCount = 1
-    
-    Component->>Controller: unsubscribe()
-    Note over Controller: subscriberCount = 0
-    Controller->>Timer: schedule GC (3000ms)
-    
-    alt Resubscribe before timeout
-        Component->>Controller: ctrl.on('resolved', callback)
-        Controller->>Timer: cancel GC
-        Note over Controller: Atom stays alive
-    else Timeout fires
-        Timer->>Scope: release(atom)
-        Note over Scope: Cleanups run, cache cleared
-        Scope->>Scope: Check dependencies for cascading GC
-    end
-```
-
-### Configuration
-
-```typescript
-// Default: GC enabled with 3000ms grace period
-const scope = createScope()
-
-// Custom grace period (useful for tests)
-const scope = createScope({
-  gc: { graceMs: 100 }
-})
-
-// Disable GC entirely (preserves pre-1.11 behavior)
-const scope = createScope({
-  gc: { enabled: false }
-})
-```
-
-### Opt-Out with keepAlive
+    participant App
+    participant Registry
 
-Mark atoms that should never be automatically released:
+    App->>Registry: getAllTags()
+    Registry-->>App: Tag[] (all live tags)
 
-```typescript
-const configAtom = atom({
-  factory: () => loadConfig(),
-  keepAlive: true  // Never auto-released
-})
+    App->>App: isAtom(v) / isFlow(v) / isTag(v)
+    App->>App: isTagged(v) / isPreset(v)
+    App->>App: isControllerDep(v) / isTagExecutor(v)
 ```
 
-### Cascading Dependency Protection
+## Additional Exports
 
-Dependencies are protected while dependents are mounted:
-
-```
-configAtom (keepAlive: true)
-    ↑
-dbAtom ←── userServiceAtom ←── [Component subscribes]
-```
-
-- `dbAtom` won't be GC'd while `userServiceAtom` is mounted
-- When component unmounts, `userServiceAtom` is GC'd after grace period
-- Then `dbAtom` becomes eligible for GC (no dependents)
-- `configAtom` stays alive due to `keepAlive: true`
-
-### React Strict Mode Compatibility
+```mermaid
+graph LR
+    subgraph Errors
+        ParseError["ParseError (tag | flow-input)"]
+    end
 
-The 3000ms default grace period handles React's double-mount behavior:
+    subgraph Meta
+        VERSION
+    end
 
+    subgraph "Symbols (advanced)"
+        atomSymbol
+        flowSymbol
+        tagSymbol
+        taggedSymbol
+        presetSymbol
+        controllerSymbol
+        controllerDepSymbol
+        tagExecutorSymbol
+        typedSymbol
+    end
 ```
-Mount (render 1):     subscribe    → count=1
-Unmount (cleanup 1):  unsubscribe  → count=0 → schedule GC
-Mount (render 2):     subscribe    → count=1 → CANCEL GC
-```
-
-The second mount always happens before the GC timer fires.
-
-### API Summary
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `gc.enabled` | `true` | Enable/disable automatic GC |
-| `gc.graceMs` | `3000` | Delay before releasing (ms) |
-| `atom.keepAlive` | `false` | Prevent auto-release for specific atoms |
+API reference: `packages/lite/dist/index.d.mts`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pumped-fn/lite",
-  "version": "1.11.3",
+  "version": "1.11.4",
   "description": "Lightweight dependency injection with minimal reactivity",
   "type": "module",
   "main": "./dist/index.cjs",