@kontsedal/olas-core 0.0.5 → 0.1.0

package/src/controller/instance.ts

@@ -24,7 +24,8 @@ import { createMutation, type Mutation, type MutationSpec } from '../query/mutat
 import type { LocalCache, Query } from '../query/types'
 import { createInfiniteUse, createUse } from '../query/use'
 import type { Scope } from '../scope'
-import { computed, signal, effect as standaloneEffect } from '../signals'
+import { computed, signal, effect as standaloneEffect, untracked } from '../signals'
+import { readOnly } from '../signals/readonly'
 import { getFactory, getName } from './define'
 import type {
   Collection,
@@ -42,6 +43,14 @@ export type RootShared = {
   readonly devtools: DevtoolsEmitter
   readonly onError: ErrorHandler | undefined
   readonly queryClient: QueryClient
+  /**
+   * Monotonic counter bumped by every `ctx.provide(...)` call inside this
+   * root's tree. `ctx.inject(...)` caches its scope-walk result alongside
+   * the version it was computed at; a mismatch forces a re-walk. Cheap
+   * compared to the linear ancestor walk (most controllers never call
+   * provide, so cache hits dominate).
+   */
+  readonly scopesVersion: { value: number }
 }
 
 type LifecycleEntry =
@@ -62,7 +71,7 @@ type LifecycleEntry =
       suspend: () => void
       resume: () => void
     }
-  | { kind: 'child'; instance: ControllerInstance }
+  | { kind: 'child'; instance: ControllerInstance; explicitlySuspended?: boolean }
   | { kind: 'onDispose'; fn: () => void }
   | { kind: 'onSuspend'; fn: () => void }
   | { kind: 'onResume'; fn: () => void }
@@ -70,17 +79,123 @@ type LifecycleEntry =
 
 type State = 'constructing' | 'active' | 'suspended' | 'disposed'
 
+/**
+ * Doubly-linked-list node wrapping a `LifecycleEntry`. Holding a reference
+ * to the node lets call sites unlink in O(1) instead of the old
+ * `entries.indexOf(...) + splice(...)` which was quadratic for long-lived
+ * collections / lazyChildren / attach-style children.
+ *
+ * `unlinked: true` is a defensive flag — re-unlinking a node should be a
+ * no-op (the parent's dispose cascade may race with an explicit unlink
+ * from a `dispose()` returned to user code).
+ */
+type LifecycleNode = {
+  entry: LifecycleEntry
+  prev: LifecycleNode | null
+  next: LifecycleNode | null
+  unlinked: boolean
+}
+
+/**
+ * Append-and-unlink container for `LifecycleEntry`s. Replaces the historical
+ * `LifecycleEntry[]` to make per-entry removal O(1) — important for
+ * controllers that churn entries (`ctx.collection` reconcile, `lazyChild`
+ * loop, `attach` short-lived children).
+ *
+ * Iteration order is insertion order for `forward()` and reverse-insertion
+ * for `reverse()`. Iteration is safe against `push` during traversal (the
+ * generator captures `next`/`prev` *before* yielding) but not against
+ * unlinking the current node from inside the visitor — visitors must not
+ * call `unlink` on the entry they're currently inspecting.
+ */
+class LifecycleList {
+  private head: LifecycleNode | null = null
+  private tail: LifecycleNode | null = null
+  private _size = 0
+
+  get size(): number {
+    return this._size
+  }
+
+  push(entry: LifecycleEntry): LifecycleNode {
+    const node: LifecycleNode = { entry, prev: this.tail, next: null, unlinked: false }
+    if (this.tail !== null) this.tail.next = node
+    else this.head = node
+    this.tail = node
+    this._size += 1
+    return node
+  }
+
+  unlink(node: LifecycleNode): void {
+    if (node.unlinked) return
+    node.unlinked = true
+    if (node.prev !== null) node.prev.next = node.next
+    else this.head = node.next
+    if (node.next !== null) node.next.prev = node.prev
+    else this.tail = node.prev
+    this._size -= 1
+  }
+
+  clear(): void {
+    this.head = null
+    this.tail = null
+    this._size = 0
+  }
+
+  /** Yield entries in insertion order. */
+  *forward(): Generator<LifecycleEntry> {
+    let n = this.head
+    while (n !== null) {
+      const next = n.next
+      yield n.entry
+      n = next
+    }
+  }
+
+  /** Yield entries in reverse-insertion order — used by dispose / suspend. */
+  *reverse(): Generator<LifecycleEntry> {
+    let n = this.tail
+    while (n !== null) {
+      const prev = n.prev
+      yield n.entry
+      n = prev
+    }
+  }
+}
+
 export class ControllerInstance {
   readonly path: readonly string[]
   readonly deps: Record<string, unknown>
 
   private state: State = 'constructing'
-  private readonly entries: LifecycleEntry[] = []
+  private readonly entries: LifecycleList = new LifecycleList()
   private readonly rootShared: RootShared
   private readonly parent: ControllerInstance | null
   private childCounter = 0
   /** Scope values provided on this instance, keyed by `Scope.__id`. */
   private scopes: Map<symbol, unknown> | null = null
+  /**
+   * Memoized result of `ctx.inject(scope)` per scope id, stamped with the
+   * `scopesVersion` the lookup observed. A bump invalidates every cache
+   * entry implicitly — the next `inject(scope)` finds a stale version
+   * stamp and re-walks. Provide is rare; reads dominate.
+   */
+  private injectCache: Map<symbol, { value: unknown; version: number }> | null = null
+
+  /**
+   * Pre-seed scopes from outside the factory — used by `createRoot`'s
+   * `scopes:` option so an adapter (e.g. `@kontsedal/olas-router-tanstack`)
+   * can publish cross-cutting values without forcing the user to call
+   * `ctx.provide(...)` in their root controller. Idempotent per scope id:
+   * later calls override.
+   */
+  seedScopes(bindings: ReadonlyArray<readonly [{ __id: symbol }, unknown]>): void {
+    if (bindings.length === 0) return
+    if (this.scopes === null) this.scopes = new Map()
+    for (const [scope, value] of bindings) {
+      this.scopes.set(scope.__id, value)
+    }
+  }
 
   constructor(
     parent: ControllerInstance | null,
@@ -120,16 +235,20 @@ export class ControllerInstance {
 
   private rollbackPartialConstruction(): void {
     // Tear down what was built before the throw, in reverse order.
-    for (let i = this.entries.length - 1; i >= 0; i--) {
-      const entry = this.entries[i]
-      if (!entry) continue
+    for (const entry of this.entries.reverse()) {
       try {
         this.disposeEntry(entry)
-      } catch {
-        // Rollback paths can't throw further.
+      } catch (err) {
+        // A teardown error during rollback must not mask the original
+        // construction throw or abort the rest of the rollback — route it to
+        // onError, same as dispose(). (T2.8)
+        dispatchError(this.rootShared.onError, err, {
+          kind: 'effect',
+          controllerPath: this.path,
+        })
       }
     }
-    this.entries.length = 0
+    this.entries.clear()
     this.state = 'disposed'
   }
 
@@ -137,9 +256,7 @@ export class ControllerInstance {
     if (this.state === 'disposed') return
     this.state = 'disposed'
 
-    for (let i = this.entries.length - 1; i >= 0; i--) {
-      const entry = this.entries[i]
-      if (!entry) continue
+    for (const entry of this.entries.reverse()) {
       try {
         this.disposeEntry(entry)
       } catch (err) {
@@ -149,8 +266,9 @@ export class ControllerInstance {
         })
       }
     }
-    this.entries.length = 0
+    this.entries.clear()
     this.scopes = null
+    this.injectCache = null
 
     if (__DEV__) {
       this.rootShared.devtools.emit({ type: 'controller:disposed', path: this.path })
@@ -185,13 +303,15 @@ export class ControllerInstance {
     }
   }
 
+  isSuspended(): boolean {
+    return this.state === 'suspended'
+  }
+
   suspend(): void {
     if (this.state !== 'active') return
     this.state = 'suspended'
 
-    for (let i = this.entries.length - 1; i >= 0; i--) {
-      const entry = this.entries[i]
-      if (!entry) continue
+    for (const entry of this.entries.reverse()) {
       try {
         switch (entry.kind) {
           case 'effect':
@@ -229,11 +349,21 @@ export class ControllerInstance {
     if (this.state !== 'suspended') return
     this.state = 'active'
 
-    for (const entry of this.entries) {
+    for (const entry of this.entries.forward()) {
       try {
         switch (entry.kind) {
           case 'effect':
-            entry.dispose = standaloneEffect(entry.factory)
+            // Skip effects that are already live. An effect registered DURING
+            // this resume (e.g. from an onResume handler) was activated
+            // immediately by `ctx.effect` while state is 'active'; the forward
+            // loop then reaches its freshly-pushed node. Re-activating would
+            // overwrite the live `dispose` ref without calling it — the effect
+            // would run twice per change and one copy would survive dispose().
+            // Only re-activate effects that `suspend()` cleared (dispose null).
+            // (T2.2)
+            if (entry.dispose === null) {
+              entry.dispose = standaloneEffect(entry.factory)
+            }
             break
           case 'subscription-cache':
             // Re-acquire the entry, restart `refetchInterval`, and re-check
@@ -241,6 +371,11 @@ export class ControllerInstance {
             entry.resume()
             break
           case 'child':
+            // Skip children explicitly suspended via attach.suspend() or
+            // collection suspendItem() — a whole-tree resume (KeepAlive) must
+            // not wake them. They resume only via their own attach.resume() /
+            // resumeItem(). (T2.6)
+            if (entry.explicitlySuspended) break
             entry.instance.resume()
             break
           case 'onResume':
@@ -266,13 +401,24 @@ export class ControllerInstance {
 
   private buildCtx(): Ctx {
     const self = this
+    // A ctx.* factory called after the controller was disposed would push into
+    // a cleared lifecycle list — a live child / subscription / effect that
+    // never gets torn down. It is always a programming error (a captured `ctx`
+    // used past its owner's lifetime), so throw rather than leak or no-op. Not
+    // routed through dispatchError — this is a bug in the caller, not a runtime
+    // condition. (T2.4, spec §4)
+    const assertLive = (method: string): void => {
+      if (self.isTerminal()) {
+        throw new Error(`[olas] ctx.${method}() called after the controller was disposed`)
+      }
+    }
     const ctx: Ctx = {
       get deps() {
         return self.deps
       },
 
       effect(fn) {
-        if (self.isTerminal()) return
+        assertLive('effect')
         const entry: LifecycleEntry = {
           kind: 'effect',
           factory: () => fn(),
@@ -281,7 +427,23 @@ export class ControllerInstance {
         // Wrap with error reporting so an effect throw goes through onError.
         const wrapped = (): void | (() => void) => {
           try {
-            return fn()
+            const cleanup = fn()
+            // The effect body may return a cleanup fn that the signals runtime
+            // calls on re-run / dispose — OUTSIDE this try. Wrap it so a throw
+            // there also routes to onError instead of escaping. (T2.8)
+            if (typeof cleanup === 'function') {
+              return () => {
+                try {
+                  cleanup()
+                } catch (err) {
+                  dispatchError(self.rootShared.onError, err, {
+                    kind: 'effect',
+                    controllerPath: self.path,
+                  })
+                }
+              }
+            }
+            return cleanup
           } catch (err) {
             dispatchError(self.rootShared.onError, err, {
               kind: 'effect',
@@ -304,12 +466,14 @@ export class ControllerInstance {
         fetcher: (signal: AbortSignal) => Promise<T>,
         options?: LocalCacheOptions<T>,
       ): LocalCache<T> {
+        assertLive('cache')
         const cache = createLocalCache<T>(fetcher, options)
         self.entries.push({ kind: 'cleanup', dispose: () => cache.dispose() })
         return cache
       },
 
       use(query: any, keyOrOptions?: any): any {
+        assertLive('use')
         const brand = (query as { __olas?: string }).__olas
         if (brand === 'infiniteQuery') {
           const handle = createInfiniteUse(
@@ -340,6 +504,7 @@ export class ControllerInstance {
       },
 
       mutation<V, R>(spec: MutationSpec<V, R>): Mutation<V, R> {
+        assertLive('mutation')
         const queryClient = self.rootShared.queryClient
         const m = createMutation<V, R>(
           spec,
@@ -362,6 +527,7 @@ export class ControllerInstance {
       },
 
       emitter<T>(): Emitter<T> {
+        assertLive('emitter')
         const e = createEmitter<T>({
           // Spec §20.6: emit-time handler throws must not block sibling
           // handlers. Route to the root's onError with kind: 'emitter' and
@@ -377,7 +543,15 @@ export class ControllerInstance {
         return e
       },
 
-      field<T>(initial: T, validators?: ReadonlyArray<Validator<T>>): Field<T> {
+      signal,
+      computed,
+
+      field<T>(
+        initial: T,
+        validators?: ReadonlyArray<Validator<T>>,
+        options?: { validateOn?: 'change' | 'blur' | 'submit' },
+      ): Field<T> {
+        assertLive('field')
         // Pass the reporter at construct time so the FIRST validator pass
         // (which runs synchronously in the FieldImpl constructor's
         // validator-effect) is covered.
@@ -388,6 +562,7 @@ export class ControllerInstance {
               controllerPath: self.path,
             })
           },
+          validateOn: options?.validateOn,
         })
         self.entries.push({ kind: 'cleanup', dispose: () => f.dispose() })
         // Standalone fields (not inside a form) still publish field:validated
@@ -402,6 +577,7 @@ export class ControllerInstance {
       },
 
       form<S extends FormSchema>(schema: S, options?: FormOptions<S>): Form<S> {
+        assertLive('form')
         const reporter = (err: unknown): void => {
           dispatchError(self.rootShared.onError, err, {
             kind: 'effect',
@@ -432,6 +608,7 @@ export class ControllerInstance {
         itemFactory: (initial?: ItemInitial<I>) => I,
         options?: FieldArrayOptions<I>,
       ): FieldArray<I> {
+        assertLive('fieldArray')
         const reporter = (err: unknown): void => {
           dispatchError(self.rootShared.onError, err, {
             kind: 'effect',
@@ -457,18 +634,41 @@ export class ControllerInstance {
       provide<T>(scope: Scope<T>, value: T): void {
         if (self.scopes === null) self.scopes = new Map()
         self.scopes.set(scope.__id, value)
+        // Invalidate every cached inject lookup tree-wide. A descendant
+        // that resolved this scope from a higher ancestor (or from a
+        // default) would now resolve to the new value, but its cache
+        // still holds the old value. Cheap: just bump the counter; cache
+        // entries check against it on next read.
+        self.rootShared.scopesVersion.value += 1
       },
 
       inject<T>(scope: Scope<T>): T {
+        const version = self.rootShared.scopesVersion.value
+        const cache = self.injectCache
+        if (cache !== null) {
+          const cached = cache.get(scope.__id)
+          if (cached !== undefined && cached.version === version) {
+            return cached.value as T
+          }
+        }
+        const ensureMemo = (): Map<symbol, { value: unknown; version: number }> => {
+          if (self.injectCache === null) self.injectCache = new Map()
+          return self.injectCache
+        }
         let node: ControllerInstance | null = self
         while (node !== null) {
           const map = node.scopes
           if (map?.has(scope.__id)) {
-            return map.get(scope.__id) as T
+            const value = map.get(scope.__id) as T
+            ensureMemo().set(scope.__id, { value, version })
+            return value
           }
           node = node.parent
         }
-        if (scope.hasDefault) return scope.default as T
+        if (scope.hasDefault) {
+          ensureMemo().set(scope.__id, { value: scope.default, version })
+          return scope.default as T
+        }
         const label = scope.name ?? scope.__id.description ?? 'unnamed'
         throw new Error(
           `[olas] ctx.inject(): no provider for scope '${label}' and no default. Provide it on an ancestor via ctx.provide(${label}, ...) or pass a default to defineScope.`,
@@ -476,6 +676,7 @@ export class ControllerInstance {
       },
 
       on<T>(emitter: Emitter<T>, handler: (value: T) => void): void {
+        assertLive('on')
         const wrapped = (value: T) => {
           try {
             handler(value)
@@ -495,6 +696,7 @@ export class ControllerInstance {
         props: Props,
         options?: { deps?: Partial<Record<string, unknown>> },
       ): Api {
+        assertLive('child')
         const segment = self.makeChildSegment(getFactory(def), getName(def))
         const override = options?.deps
         const childDeps = override !== undefined ? { ...self.deps, ...override } : self.deps
@@ -511,21 +713,25 @@ export class ControllerInstance {
         props: Props,
         options?: { deps?: Partial<Record<string, unknown>> },
       ): { api: Api; dispose: () => void; suspend: () => void; resume: () => void } {
+        assertLive('attach')
         const segment = self.makeChildSegment(getFactory(def), getName(def))
         const override = options?.deps
         const childDeps = override !== undefined ? { ...self.deps, ...override } : self.deps
         const childInstance = new ControllerInstance(self, self.rootShared, segment, childDeps)
         const api = childInstance.construct(getFactory(def), props)
-        const entry: LifecycleEntry = { kind: 'child', instance: childInstance }
-        self.entries.push(entry)
+        const entry = {
+          kind: 'child' as const,
+          instance: childInstance,
+          explicitlySuspended: false,
+        }
+        const node = self.entries.push(entry)
         let disposed = false
         return {
           api,
           dispose: () => {
             if (disposed) return
             disposed = true
-            const idx = self.entries.indexOf(entry)
-            if (idx >= 0) self.entries.splice(idx, 1)
+            self.entries.unlink(node)
             try {
               childInstance.dispose()
             } catch (err) {
@@ -542,6 +748,7 @@ export class ControllerInstance {
           // extra flag here.
           suspend: () => {
             if (disposed) return
+            entry.explicitlySuspended = true
             try {
               childInstance.suspend()
             } catch (err) {
@@ -553,6 +760,12 @@ export class ControllerInstance {
           },
           resume: () => {
             if (disposed) return
+            // Clear the explicit-suspend mark. Under a still-suspended parent,
+            // DON'T activate now — a child must not run inside a frozen tree; it
+            // rejoins the parent's next resume cascade (which no longer skips it
+            // now the mark is clear). (T2.6)
+            entry.explicitlySuspended = false
+            if (self.isSuspended()) return
             try {
               childInstance.resume()
             } catch (err) {
@@ -570,19 +783,19 @@ export class ControllerInstance {
         props: Props,
         options?: { deps?: Partial<Record<string, unknown>> },
       ): readonly [Api, () => void] {
+        assertLive('session')
         const segment = self.makeChildSegment(getFactory(def), getName(def))
         const override = options?.deps
         const childDeps = override !== undefined ? { ...self.deps, ...override } : self.deps
         const childInstance = new ControllerInstance(self, self.rootShared, segment, childDeps)
         const api = childInstance.construct(getFactory(def), props)
         const entry: LifecycleEntry = { kind: 'child', instance: childInstance }
-        self.entries.push(entry)
+        const node = self.entries.push(entry)
         let disposed = false
         const dispose = (): void => {
           if (disposed) return
           disposed = true
-          const idx = self.entries.indexOf(entry)
-          if (idx >= 0) self.entries.splice(idx, 1)
+          self.entries.unlink(node)
           try {
             childInstance.dispose()
           } catch (err) {
@@ -600,10 +813,11 @@ export class ControllerInstance {
           | CollectionHomogeneousOptions<Item, K, Props, Api>
           | CollectionFactoryOptions<Item, K, R>,
       ): Collection<K, Api> | Collection<K, CollectionFactoryApi<R>> {
+        assertLive('collection')
         type ChildInfo = {
           instance: ControllerInstance
           api: Api
-          entry: LifecycleEntry
+          node: LifecycleNode
           // For factory form: the controller def used to construct this child.
           // A different def on a future render means "rebuild with new type".
           def: ControllerDef<unknown, unknown>
@@ -659,8 +873,7 @@ export class ControllerInstance {
           const info = childMap.get(key)
           if (info === undefined) return
           childMap.delete(key)
-          const idx = self.entries.indexOf(info.entry)
-          if (idx >= 0) self.entries.splice(idx, 1)
+          self.entries.unlink(info.node)
           try {
             info.instance.dispose()
           } catch (err) {
@@ -672,57 +885,75 @@ export class ControllerInstance {
         }
 
         const reconcile = (): void => {
+          // Only `source` is a tracked dependency — everything else (keyOf, the
+          // item factory, child construct/dispose) runs untracked so a child
+          // factory reading an unrelated signal can't force the whole
+          // collection to re-reconcile on every write to it (T2.3). Mirrors the
+          // untracked bind in ctx.use.
           const source = options.source.value
-          const itemByKey = new Map<K, Item>()
-          for (const item of source) {
-            const key = options.keyOf(item)
-            if (!itemByKey.has(key)) itemByKey.set(key, item)
-          }
+          untracked(() => {
+            const itemByKey = new Map<K, Item>()
+            for (const item of source) {
+              const key = options.keyOf(item)
+              if (itemByKey.has(key)) {
+                if (__DEV__) {
+                  // eslint-disable-next-line no-console
+                  console.warn(
+                    `[olas] ctx.collection: duplicate key ${String(key)} in source — only the` +
+                      ' first occurrence is kept. This is usually a bug in `keyOf(item)`;' +
+                      ' return a unique identifier per item.',
+                  )
+                }
+                continue
+              }
+              itemByKey.set(key, item)
+            }
 
-          // Drop removed keys.
-          for (const key of [...childMap.keys()]) {
-            if (!itemByKey.has(key)) removeKey(key)
-          }
+            // Drop removed keys.
+            for (const key of [...childMap.keys()]) {
+              if (!itemByKey.has(key)) removeKey(key)
+            }
 
-          // Add new keys + rebuild factory-form type changes.
-          for (const [key, item] of itemByKey) {
-            const existing = childMap.get(key)
-            if (existing !== undefined) {
-              if (isFactoryForm) {
-                const result = (options as CollectionFactoryOptions<Item, K, R>).factory(
-                  item,
-                ) as CollectionFactoryResult
-                if ((result.controller as unknown) !== existing.def) {
-                  removeKey(key)
-                  const built = buildChild(item)
-                  if (built !== null) {
-                    const entry: LifecycleEntry = { kind: 'child', instance: built.instance }
-                    self.entries.push(entry)
-                    childMap.set(key, { ...built, entry })
+            // Add new keys + rebuild factory-form type changes.
+            for (const [key, item] of itemByKey) {
+              const existing = childMap.get(key)
+              if (existing !== undefined) {
+                if (isFactoryForm) {
+                  const result = (options as CollectionFactoryOptions<Item, K, R>).factory(
+                    item,
+                  ) as CollectionFactoryResult
+                  if ((result.controller as unknown) !== existing.def) {
+                    removeKey(key)
+                    const built = buildChild(item)
+                    if (built !== null) {
+                      const entry: LifecycleEntry = { kind: 'child', instance: built.instance }
+                      const node = self.entries.push(entry)
+                      childMap.set(key, { ...built, node })
+                    }
                   }
                 }
+                continue
+              }
+              const built = buildChild(item)
+              if (built !== null) {
+                const entry: LifecycleEntry = { kind: 'child', instance: built.instance }
+                const node = self.entries.push(entry)
+                childMap.set(key, { ...built, node })
               }
-              continue
-            }
-            const built = buildChild(item)
-            if (built !== null) {
-              const entry: LifecycleEntry = { kind: 'child', instance: built.instance }
-              self.entries.push(entry)
-              childMap.set(key, { ...built, entry })
             }
-          }
 
-          // Project to items signal in source order, deduped, skipping failures.
-          const next: Array<{ key: K; api: Api }> = []
-          const seen = new Set<K>()
-          for (const item of source) {
-            const key = options.keyOf(item)
-            if (seen.has(key)) continue
-            seen.add(key)
-            const info = childMap.get(key)
-            if (info !== undefined) next.push({ key, api: info.api })
-          }
-          items$.set(next)
+            // Project to items signal in source order, deduped, skipping failures.
+            const next: Array<{ key: K; api: Api }> = []
+            const seen = new Set<K>()
+            for (const item of source) {
+              const key = options.keyOf(item)
+              if (seen.has(key)) continue
+              seen.add(key)
+              const info = childMap.get(key)
+              if (info !== undefined) next.push({ key, api: info.api })
+            }
+            items$.set(next)
+          })
         }
 
         // Register the diff loop as an 'effect' entry so it pauses on suspend
@@ -748,10 +979,33 @@ export class ControllerInstance {
         self.entries.push(effectEntry)
 
         return {
-          items: items$,
-          size: size$,
+          // readOnly so the writable backing signals can't be mutated through
+          // the ReadSignal-typed public surface. (T2.8)
+          items: readOnly(items$),
+          size: readOnly(size$),
           get: (key: K) => childMap.get(key)?.api,
           has: (key: K) => childMap.has(key),
+          suspendItem: (key: K) => {
+            const info = childMap.get(key)
+            if (info === undefined) return
+            // Mark the child entry so a whole-tree resume cascade skips it. (T2.6)
+            if (info.node.entry.kind === 'child') info.node.entry.explicitlySuspended = true
+            info.instance.suspend()
+          },
+          resumeItem: (key: K) => {
+            const info = childMap.get(key)
+            if (info === undefined) return
+            if (info.node.entry.kind === 'child') info.node.entry.explicitlySuspended = false
+            // Under a suspended parent, defer to the parent's next resume
+            // cascade (which no longer skips the cleared entry). (T2.6)
+            if (self.isSuspended()) return
+            info.instance.resume()
+          },
+          isItemSuspended: (key: K) => {
+            const info = childMap.get(key)
+            if (info === undefined) return false
+            return info.instance.isSuspended()
+          },
         }
       },
 
@@ -760,12 +1014,13 @@ export class ControllerInstance {
         props: Props,
         options?: { deps?: Partial<Record<string, unknown>> },
       ): LazyChild<Api> {
+        assertLive('lazyChild')
         const status$ = signal<'idle' | 'loading' | 'ready' | 'error'>('idle')
         const api$ = signal<Api | undefined>(undefined)
         const error$ = signal<unknown | undefined>(undefined)
 
         let childInstance: ControllerInstance | null = null
-        let childEntry: LifecycleEntry | null = null
+        let childNode: LifecycleNode | null = null
         let pendingLoad: Promise<Api> | null = null
         let disposed = false
 
@@ -777,7 +1032,7 @@ export class ControllerInstance {
             disposed = true
           },
         }
-        self.entries.push(flagEntry)
+        const flagNode = self.entries.push(flagEntry)
 
         const handleFailure = (err: unknown): void => {
           status$.set('error')
@@ -792,9 +1047,13 @@ export class ControllerInstance {
           if (disposed) {
             return Promise.reject(new Error('[olas] ctx.lazyChild: cannot load after dispose'))
           }
+          // Cached fulfilled or in-flight loads share a promise. A previously
+          // *rejected* load doesn't — we clear `pendingLoad` in the catch
+          // branch so the next `load()` reattempts the loader. Sticky
+          // rejections trap consumers on a transient import-failure.
           if (pendingLoad !== null) return pendingLoad
           status$.set('loading')
-          pendingLoad = loader().then(
+          const attempt = loader().then(
             (def) => {
               if (disposed) {
                 throw new Error('[olas] ctx.lazyChild: disposed during load')
@@ -806,8 +1065,7 @@ export class ControllerInstance {
               try {
                 const api = instance.construct(getFactory(def), props)
                 childInstance = instance
-                childEntry = { kind: 'child', instance }
-                self.entries.push(childEntry)
+                childNode = self.entries.push({ kind: 'child', instance })
                 api$.set(api)
                 status$.set('ready')
                 return api
@@ -822,15 +1080,21 @@ export class ControllerInstance {
               throw err
             },
           )
-          return pendingLoad
+          pendingLoad = attempt
+          attempt.catch(() => {
+            // Allow retry: drop the cached rejection if this is still the
+            // current attempt. A successful load leaves `pendingLoad` in
+            // place so repeat `load()` calls return the same fulfilled api.
+            if (pendingLoad === attempt) pendingLoad = null
+          })
+          return attempt
         }
 
         const dispose = (): void => {
           if (disposed) return
           disposed = true
-          if (childEntry !== null && childInstance !== null) {
-            const idx = self.entries.indexOf(childEntry)
-            if (idx >= 0) self.entries.splice(idx, 1)
+          if (childNode !== null && childInstance !== null) {
+            self.entries.unlink(childNode)
             try {
               childInstance.dispose()
             } catch (err) {
@@ -840,26 +1104,26 @@ export class ControllerInstance {
               })
             }
             childInstance = null
-            childEntry = null
+            childNode = null
           }
-          // Splice the parent-dispose flag entry too — its only job was to
+          // Unlink the parent-dispose flag entry too — its only job was to
           // signal disposal to an in-flight loader, and `disposed` is now
           // already true. Leaving it behind leaks one closure per ever-
           // disposed lazyChild for the parent's remaining lifetime.
-          const flagIdx = self.entries.indexOf(flagEntry)
-          if (flagIdx >= 0) self.entries.splice(flagIdx, 1)
+          self.entries.unlink(flagNode)
         }
 
         return {
-          status: status$,
-          api: api$,
-          error: error$,
+          status: readOnly(status$),
+          api: readOnly(api$),
+          error: readOnly(error$),
           load,
           dispose,
         }
       },
 
       onDispose(fn) {
+        assertLive('onDispose')
         self.entries.push({
           kind: 'onDispose',
           fn: () => {
@@ -876,6 +1140,7 @@ export class ControllerInstance {
       },
 
       onSuspend(fn) {
+        assertLive('onSuspend')
         self.entries.push({
           kind: 'onSuspend',
           fn: () => {
@@ -892,6 +1157,7 @@ export class ControllerInstance {
       },
 
       onResume(fn) {
+        assertLive('onResume')
         self.entries.push({
           kind: 'onResume',
           fn: () => {