@astrale-os/shell-react 0.1.0

package/src/schema/types.ts

@@ -0,0 +1,150 @@
+/**
+ * Type-level surface for the schema module (API §6): the read envelopes
+ * (`TypedNodeResult`/`TypedChildrenResult`/`EndpointResult`) and the method /
+ * function contract projections. Param inference mirrors the client's proxy
+ * types (Zod optionality preserved), re-derived here because it is not exported.
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type {
+  AnyBoundNode,
+  BoundNode,
+  DefOf,
+  EdgeNames,
+  EndpointsOf,
+  NodeRefInput,
+  TypeNames,
+} from '@astrale-os/kernel-client'
+import type { z } from '@astrale-os/kernel-core'
+import type {
+  AllMethods,
+  ExtractMethodNames,
+  ExtractMethodParams,
+  ExtractMethodReturnValue,
+  Schema,
+} from '@astrale-os/kernel-dsl'
+
+import type { Action } from '../graph/action'
+import type { ReadState, Windowed } from '../graph/memory/read/envelope'
+
+// ── Read envelopes ──────────────────────────────────────────────────────────────
+
+export interface TypedNodeResult<S extends Schema, T extends TypeNames<S>> extends ReadState {
+  readonly node: BoundNode<DefOf<S, T>, S> | null
+}
+
+export interface TypedChildrenResult<S extends Schema, T extends TypeNames<S>>
+  extends ReadState, Windowed {
+  readonly children: readonly BoundNode<DefOf<S, T>, S>[]
+}
+
+/** Cardinality decides the envelope key: single|null for `1`/`0..1`, array otherwise. */
+export type EndpointResult<S extends Schema, E extends EdgeNames<S>, Side extends 'from' | 'to'> =
+  EndpointsOf<S, E, Side> extends readonly unknown[]
+    ? ReadState & { readonly nodes: EndpointsOf<S, E, Side> }
+    : ReadState & { readonly node: EndpointsOf<S, E, Side> }
+
+/** Untyped traversal fallback — mirrors the raw `neighbors` shorthand. */
+export interface UntypedEndpointResult<S extends Schema> extends ReadState, Windowed {
+  readonly nodes: readonly AnyBoundNode<S>[]
+}
+
+// ── Method contracts ──────────────────────────────────────────────────────────────
+
+/** Dispatchable method names on `type` (own + inherited). */
+export type MethodNames<S extends Schema, T extends TypeNames<S>> = ExtractMethodNames<DefOf<S, T>>
+
+type OptionalKeys<P> = {
+  [K in keyof P]: P[K] extends z.ZodOptional<any> | z.ZodDefault<any> ? K : never
+}[keyof P]
+type RequiredKeys<P> = Exclude<keyof P, OptionalKeys<P>>
+type InferParams<P> = {
+  [K in RequiredKeys<P>]: P[K] extends z.ZodType<infer T> ? T : never
+} & {
+  [K in OptionalKeys<P>]?: P[K] extends z.ZodType<infer T> ? T : never
+}
+type Simplify<T> = { [K in keyof T]: T[K] }
+
+/** Runtime params object for method `M` on `type`. */
+export type MethodParams<
+  S extends Schema,
+  T extends TypeNames<S>,
+  M extends MethodNames<S, T>,
+> = Simplify<InferParams<ExtractMethodParams<DefOf<S, T>, M & string>>>
+
+/** Resolved return value of method `M` on `type`. */
+export type MethodResult<
+  S extends Schema,
+  T extends TypeNames<S>,
+  M extends MethodNames<S, T>,
+> = ExtractMethodReturnValue<DefOf<S, T>, M & string>
+
+/** True when method `M` on `type` is static. */
+export type MethodIsStatic<
+  S extends Schema,
+  T extends TypeNames<S>,
+  M extends MethodNames<S, T>,
+> = M extends keyof AllMethods<DefOf<S, T>>
+  ? AllMethods<DefOf<S, T>>[M] extends { config: { static: true } }
+    ? true
+    : false
+  : false
+
+/** Action for a `on`-bound or static method: `action(params)`. */
+export type BoundMethodAction<
+  S extends Schema,
+  T extends TypeNames<S>,
+  M extends MethodNames<S, T>,
+> = Action<[MethodParams<S, T, M>], MethodResult<S, T, M>>
+
+/** Action for an unbound instance method: `action(ref, params)`. */
+export type TargetedMethodAction<
+  S extends Schema,
+  T extends TypeNames<S>,
+  M extends MethodNames<S, T>,
+> = Action<[ref: NodeRefInput, params: MethodParams<S, T, M>], MethodResult<S, T, M>>
+
+/** Static → `action(params)`; instance → `action(ref, params)` (no `on`). */
+export type AutoMethodAction<
+  S extends Schema,
+  T extends TypeNames<S>,
+  M extends MethodNames<S, T>,
+> =
+  MethodIsStatic<S, T, M> extends true ? BoundMethodAction<S, T, M> : TargetedMethodAction<S, T, M>
+
+// ── Function contracts ──────────────────────────────────────────────────────────────
+//
+// DEGRADATION (§6 deviation — tracked to kernel-dsl): `defineSchema`
+// (kernel/dsl/src/schema/define.ts) does NOT make the `functions` record generic
+// — `Schema.functions` is the widened `Record<string, FuncDef>`, and `FuncDef`'s
+// input/output default to `z.ZodType`. So for a real domain schema `S['functions']
+// [F]` is a bare `FuncDef`: `FunctionNames<S>` widens to `string` (ANY name
+// compiles), and `FunctionParams`/`FunctionResult` resolve to `unknown`. These
+// projections are correct in shape; the phantom type-safety is upstream. The fix
+// belongs in kernel-dsl (make `defineSchema` generic over the functions record →
+// `Schema<I, C, F>`) and is deferred here: it is a cross-ecosystem change (a third
+// `Schema` type param threads through every domain's declared type) carrying the
+// declaration-emit size hazard `imports` was widened to avoid (schema.ts). Until
+// then, treat `useFunction` names/params/results as UNCHECKED at real call sites.
+
+/** Standalone top-level function names of the schema (widens to `string` today — see above). */
+export type FunctionNames<S extends Schema> = keyof S['functions'] & string
+
+/** Input value of standalone function `F` (`unknown` for a widened `FuncDef` — see above). */
+export type FunctionParams<
+  S extends Schema,
+  F extends FunctionNames<S>,
+> = S['functions'][F] extends { config: { input: infer I } }
+  ? I extends z.ZodType
+    ? z.infer<I>
+    : never
+  : never
+
+/** Output value of standalone function `F` (`unknown` for a widened `FuncDef` — see above). */
+export type FunctionResult<
+  S extends Schema,
+  F extends FunctionNames<S>,
+> = S['functions'][F] extends { config: { output: infer O } }
+  ? O extends z.ZodType
+    ? z.infer<O>
+    : never
+  : never

package/src/schema/write.ts

@@ -0,0 +1,80 @@
+/**
+ * Memory-routed writes (API §6). Wraps a session view so `updateNode`/`createNode`
+ * route through the shared `GraphMemory`'s optimistic write shorthands — so
+ * `BoundNode.update` / `SchemaBoundView.create` from hook-returned nodes are
+ * optimistic (SAFE-MODE prop regime) and revalidate affected shapes, instead of
+ * the raw kernel-client floor that bypasses the overlay. Keeps the bind-time
+ * `id → tree-path` index the write capability addresses nodes through.
+ */
+import type { CredentialInput } from '@astrale-os/kernel-client'
+import type { PathLike, Properties } from '@astrale-os/kernel-client/graph'
+import type { GraphMemory } from '@astrale-os/kernel-client/store'
+
+import type { SessionView } from '../auth/act-as.context'
+
+/**
+ * One memory-backed writable kernel per (effective) session view, plus the
+ * bind-time `id → tree-path` index it consults. Shared across every schema binding
+ * over the same session so a node bound under any schema resolves for a write.
+ */
+export interface WritableKernel {
+  readonly writable: SessionView
+  readonly pathIndex: Map<string, string>
+}
+const writableCache = new WeakMap<object, WritableKernel>()
+
+export function writableFor(kernel: SessionView, memory: GraphMemory): WritableKernel {
+  let entry = writableCache.get(kernel)
+  if (entry === undefined) {
+    const pathIndex = new Map<string, string>()
+    entry = { writable: withMemoryWrites(kernel, memory, pathIndex), pathIndex }
+    writableCache.set(kernel, entry)
+  }
+  return entry
+}
+
+/**
+ * Wrap a session view so `updateNode`/`createNode` route through the memory's
+ * optimistic write shorthands. `BoundNode.update` addresses a node by `@<id>`,
+ * but the memory indexes entities by tree path — so an `@<id>` ref is translated
+ * through `pathIndex` (populated at bind time). A ref that is NOT indexed (a node
+ * that was never read through a hook) falls back to the raw kernel-client floor:
+ * it still dispatches, just without the overlay — matching the imperative floor.
+ */
+function withMemoryWrites(
+  kernel: SessionView,
+  memory: GraphMemory,
+  pathIndex: Map<string, string>,
+): SessionView {
+  const base = kernel as unknown as {
+    updateNode(cls: PathLike, ref: PathLike, props: Properties): Promise<void>
+    createNode(cls: PathLike, at: PathLike, props?: Properties): Promise<string>
+    as(cred: CredentialInput | (() => CredentialInput)): SessionView
+  }
+  const rawUpdate = base.updateNode.bind(base)
+  return {
+    ...(kernel as object),
+    updateNode: (cls: PathLike, ref: PathLike, props: Properties): Promise<void> => {
+      const path = treePathFor(pathIndex, ref)
+      return path !== null ? memory.update(path, props) : rawUpdate(cls, ref, props)
+    },
+    createNode: (cls: PathLike, at: PathLike, props?: Properties): Promise<string> =>
+      memory.create(cls, at, props),
+    // Credential rebind stays on the raw kernel-client floor (§6 note).
+    as: (cred: CredentialInput | (() => CredentialInput)): SessionView => base.as(cred),
+  } as unknown as SessionView
+}
+
+/** The tree path an `@<id>` write ref maps to, via the bind-time index; else null. */
+function treePathFor(pathIndex: Map<string, string>, ref: PathLike): string | null {
+  if (typeof ref !== 'string' || !ref.startsWith('@')) return null
+  return pathIndex.get(ref.slice(1)) ?? null
+}
+
+/** Record a bound node's `id → tree path` so the write cap can address it. */
+export function recordPath(pathIndex: Map<string, string>, node: unknown): void {
+  const n = node as { id?: unknown; path?: { raw?: unknown } } | null
+  if (n !== null && typeof n.id === 'string' && typeof n.path?.raw === 'string') {
+    pathIndex.set(n.id, n.path.raw)
+  }
+}

package/src/selection/index.ts

@@ -0,0 +1,5 @@
+// selection — API §9. SelectionScope + useSelection: an insertion-ordered id set
+// with an anchor, projected to LIVE memory nodes.
+export { SelectionScope } from './scope.context'
+export type { Selection, SelectionScopeProps } from './scope.context'
+export { useSelection } from './selection.hook'

package/src/selection/live.ts

@@ -0,0 +1,142 @@
+import type { GraphMemory, ReadOptions, ShapeInput } from '@astrale-os/kernel-client/store'
+
+/**
+ * Selection liveness (API §9) — resolve the scope's ids to LIVE memory nodes, and
+ * the node types the selection speaks. Each id is subscribed as an independent
+ * point-read shape; an id drops ONLY once its shape has SETTLED to absence (the
+ * fixed latch) — a cold shape whose point-read has not landed is kept alive with
+ * no node, so a selection made from a children row is never self-cleared before
+ * its fetch resolves. Degrades to no nodes (ids kept) when no memory is in scope.
+ */
+import { useCallback, useContext, useRef, useSyncExternalStore } from 'react'
+
+import { GraphContext } from '../graph/graph.context'
+
+/** A live memory node — the non-null projection of a point read. */
+export type SelectionNode = NonNullable<ReturnType<GraphMemory['getSnapshot']>['node']>
+export type NodeId = SelectionNode['id']
+
+const LIVE_OPTS: ReadOptions = { live: true }
+const EMPTY_NODES: readonly SelectionNode[] = []
+const NOOP = (): void => {}
+
+/** Point-read shape addressing a node by its graph id. */
+function nodeShape(id: NodeId): ShapeInput {
+  return `@${id}`
+}
+
+/** A point-read snapshot — the arms selection reads (widened to tolerate fakes). */
+type NodeSnapshot = { readonly node: SelectionNode | null; live?: boolean; pending?: boolean }
+
+/**
+ * A null-node id is a CONFIRMED absence (drop it) only when the shape settled
+ * there: it was seen warm and is now gone (deletion), or a live subscription has
+ * finished fetching and found nothing (mask/never-existed). A never-warm, not-
+ * yet-fetched (cold/pending) shape is NOT absence — the id stays alive, no node.
+ */
+function isConfirmedAbsent(snap: NodeSnapshot, id: NodeId, everWarm: ReadonlySet<NodeId>): boolean {
+  if (everWarm.has(id)) return true
+  return snap.live === true && snap.pending === false
+}
+
+/**
+ * The in-scope graph memory, structurally narrowed. Reads the base memory the
+ * provider seats in `GraphContext`, defensively so selection also works under a
+ * bare/fake context (tests) or before one is mounted.
+ */
+export function useMemory(): GraphMemory | null {
+  const ctx = useContext(GraphContext) as unknown as GraphMemory | null
+  return ctx !== null &&
+    typeof ctx.subscribe === 'function' &&
+    typeof ctx.getSnapshot === 'function'
+    ? ctx
+    : null
+}
+
+export interface LiveSnapshot {
+  readonly aliveIds: readonly NodeId[]
+  readonly nodes: readonly SelectionNode[]
+}
+
+function unchanged(
+  prev: LiveSnapshot,
+  aliveIds: readonly NodeId[],
+  nodes: readonly SelectionNode[],
+): boolean {
+  // `aliveIds` and `nodes` can differ in length (a cold id is alive with no node
+  // yet), so compare the two lists independently.
+  if (prev.aliveIds.length !== aliveIds.length || prev.nodes.length !== nodes.length) return false
+  for (let i = 0; i < aliveIds.length; i += 1) if (prev.aliveIds[i] !== aliveIds[i]) return false
+  for (let i = 0; i < nodes.length; i += 1) if (prev.nodes[i] !== nodes[i]) return false
+  return true
+}
+
+/**
+ * Subscribe to each id's node shape and project the surviving nodes. The result
+ * keeps a stable reference across renders when membership and node identities
+ * are unchanged (useSyncExternalStore contract).
+ */
+export function useLiveNodes(
+  orderedIds: readonly NodeId[],
+  memory: GraphMemory | null,
+): LiveSnapshot {
+  // Stands in for `orderedIds` in the callback deps (a fresh array each render).
+  const idsKey = orderedIds.join(' ')
+  const cache = useRef<{ memory: GraphMemory | null; snap: LiveSnapshot } | null>(null)
+  // Ids whose shape has been seen warm at least once — a later null is a deletion
+  // (confirmed absence), whereas a never-warm null is merely cold. Monotonic, so
+  // re-reading getSnapshot within a render is idempotent (useSyncExternalStore-safe).
+  const everWarm = useRef<Set<NodeId>>(new Set())
+
+  const getSnapshot = useCallback((): LiveSnapshot => {
+    let aliveIds: readonly NodeId[]
+    let nodes: readonly SelectionNode[]
+    if (memory === null) {
+      // No liveness source: keep the ids, resolve no nodes.
+      aliveIds = orderedIds
+      nodes = EMPTY_NODES
+    } else {
+      const seen = everWarm.current
+      const a: NodeId[] = []
+      const n: SelectionNode[] = []
+      for (const id of orderedIds) {
+        const snap = memory.getSnapshot(nodeShape(id), LIVE_OPTS) as NodeSnapshot
+        const node = snap.node
+        if (node !== null) {
+          seen.add(id)
+          a.push(id)
+          n.push(node)
+        } else if (!isConfirmedAbsent(snap, id, seen)) {
+          // Cold / not-yet-fetched: keep the id alive, no node yet — never a
+          // premature drop (the critical self-clear this guards against).
+          a.push(id)
+        }
+        // else: settled absence (deleted/masked) → drops from ids and nodes.
+      }
+      aliveIds = a
+      nodes = n
+    }
+    const prev = cache.current
+    if (prev !== null && prev.memory === memory && unchanged(prev.snap, aliveIds, nodes)) {
+      return prev.snap
+    }
+    const snap: LiveSnapshot = { aliveIds, nodes }
+    cache.current = { memory, snap }
+    return snap
+  }, [memory, idsKey])
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void): (() => void) => {
+      if (memory === null || orderedIds.length === 0) return NOOP
+      const unsubs = orderedIds.map((id) =>
+        memory.subscribe(nodeShape(id), onStoreChange, LIVE_OPTS),
+      )
+      return () => {
+        for (const unsub of unsubs) unsub()
+      }
+    },
+    [memory, idsKey],
+  )
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}

package/src/selection/scope.context.tsx

@@ -0,0 +1,151 @@
+import type { ReactElement, ReactNode } from 'react'
+
+/**
+ * SelectionScope (API §9) — an insertion-ordered id set with an anchor (the last
+ * explicit pick), projected to LIVE memory nodes. A deleted node drops out of
+ * `ids`/`nodes`, and the scope re-canonicalizes its stored set to match. Range
+ * math stays caller-side (read `anchor`). Seats the selection context.
+ */
+import { createContext, useCallback, useEffect, useMemo, useReducer, useRef } from 'react'
+
+import type { NodeId, SelectionNode } from './live'
+
+import { useLiveNodes, useMemory } from './live'
+
+/** The value `useSelection()` returns (API §9). */
+export interface Selection {
+  /** Selected ids, insertion-ordered. A deleted node drops out. */
+  readonly ids: readonly NodeId[]
+  /** LIVE nodes for `ids`, same order — a deleted node drops out here too. */
+  readonly nodes: readonly SelectionNode[]
+  /** Last explicit pick; null when empty or the anchor node is gone. Range math is caller-side. */
+  readonly anchor: NodeId | null
+  has(id: NodeId): boolean
+  set(ids: readonly NodeId[]): void
+  add(id: NodeId): void
+  toggle(id: NodeId): void
+  clear(): void
+}
+
+export interface SelectionScopeProps {
+  /** Seed selection (deduped); read once at mount. */
+  initial?: readonly NodeId[]
+  /** Fires when the selection changes — explicit ops AND liveness drops. Persist here. */
+  onChange?: (ids: readonly NodeId[]) => void
+  children: ReactNode
+}
+
+export const SelectionContext = createContext<Selection | null>(null)
+SelectionContext.displayName = 'AstraleSelectionContext'
+
+interface State {
+  readonly ids: readonly NodeId[]
+  readonly anchor: NodeId | null
+}
+
+type Action =
+  | { readonly t: 'set'; readonly ids: readonly NodeId[] }
+  | { readonly t: 'add'; readonly id: NodeId }
+  | { readonly t: 'toggle'; readonly id: NodeId }
+  | { readonly t: 'clear' }
+  | { readonly t: 'prune'; readonly alive: readonly NodeId[] }
+
+function dedupe(ids: readonly NodeId[]): readonly NodeId[] {
+  const seen = new Set<NodeId>()
+  const out: NodeId[] = []
+  for (const id of ids) {
+    if (!seen.has(id)) {
+      seen.add(id)
+      out.push(id)
+    }
+  }
+  return out
+}
+
+function sameIds(a: readonly NodeId[], b: readonly NodeId[]): boolean {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false
+  return true
+}
+
+function reducer(state: State, action: Action): State {
+  switch (action.t) {
+    case 'set': {
+      const ids = dedupe(action.ids)
+      const anchor = ids.length > 0 ? ids[ids.length - 1]! : null
+      if (sameIds(state.ids, ids) && state.anchor === anchor) return state
+      return { ids, anchor }
+    }
+    case 'add': {
+      if (state.ids.includes(action.id)) {
+        return state.anchor === action.id ? state : { ids: state.ids, anchor: action.id }
+      }
+      return { ids: [...state.ids, action.id], anchor: action.id }
+    }
+    case 'toggle': {
+      // Toggle-off keeps the anchor (the removed id is no longer a valid pivot).
+      if (state.ids.includes(action.id)) {
+        return { ids: state.ids.filter((x) => x !== action.id), anchor: state.anchor }
+      }
+      return { ids: [...state.ids, action.id], anchor: action.id }
+    }
+    case 'clear':
+      return state.ids.length === 0 && state.anchor === null ? state : { ids: [], anchor: null }
+    case 'prune': {
+      const anchorAlive = state.anchor === null || action.alive.includes(state.anchor)
+      if (sameIds(state.ids, action.alive)) {
+        return anchorAlive ? state : { ids: state.ids, anchor: null }
+      }
+      return { ids: action.alive, anchor: anchorAlive ? state.anchor : null }
+    }
+  }
+}
+
+function initState(initial: readonly NodeId[] | undefined): State {
+  return { ids: dedupe(initial ?? []), anchor: null }
+}
+
+export function SelectionScope(props: SelectionScopeProps): ReactElement {
+  const { initial, onChange, children } = props
+  const [state, dispatch] = useReducer(reducer, initial, initState)
+
+  const memory = useMemory()
+  const { aliveIds, nodes } = useLiveNodes(state.ids, memory)
+
+  // Re-canonicalize stored state when liveness drops a node (or its anchor).
+  useEffect(() => {
+    const anchorDead = state.anchor !== null && !aliveIds.includes(state.anchor)
+    if (!sameIds(state.ids, aliveIds) || anchorDead) dispatch({ t: 'prune', alive: aliveIds })
+  }, [aliveIds, state.ids, state.anchor])
+
+  // Report changes (explicit ops AND liveness drops), skipping the initial mount.
+  const onChangeRef = useRef(onChange)
+  onChangeRef.current = onChange
+  const mounted = useRef(false)
+  useEffect(() => {
+    if (!mounted.current) {
+      mounted.current = true
+      return
+    }
+    onChangeRef.current?.(aliveIds)
+  }, [aliveIds])
+
+  const set = useCallback((ids: readonly NodeId[]) => dispatch({ t: 'set', ids }), [])
+  const add = useCallback((id: NodeId) => dispatch({ t: 'add', id }), [])
+  const toggle = useCallback((id: NodeId) => dispatch({ t: 'toggle', id }), [])
+  const clear = useCallback(() => dispatch({ t: 'clear' }), [])
+
+  const aliveSet = useMemo(() => new Set(aliveIds), [aliveIds])
+  const aliveSetRef = useRef(aliveSet)
+  aliveSetRef.current = aliveSet
+  const has = useCallback((id: NodeId) => aliveSetRef.current.has(id), [])
+
+  const anchor = state.anchor !== null && aliveSet.has(state.anchor) ? state.anchor : null
+
+  const value = useMemo<Selection>(
+    () => ({ ids: aliveIds, nodes, anchor, has, set, add, toggle, clear }),
+    [aliveIds, nodes, anchor, has, set, add, toggle, clear],
+  )
+
+  return <SelectionContext.Provider value={value}>{children}</SelectionContext.Provider>
+}

package/src/selection/selection.hook.ts

@@ -0,0 +1,18 @@
+/**
+ * useSelection (API §9) — the nearest selection scope's value (ids/nodes/anchor +
+ * has/set/add/toggle/clear). Throws outside a `<SelectionScope>`.
+ */
+import { useContext } from 'react'
+
+import type { Selection } from './scope.context'
+
+import { SelectionContext } from './scope.context'
+
+/** The nearest selection scope. Throws outside a `<SelectionScope>`. */
+export function useSelection(): Selection {
+  const selection = useContext(SelectionContext)
+  if (selection === null) {
+    throw new Error('useSelection must be used within a <SelectionScope>')
+  }
+  return selection
+}

package/src/session/boot/boot.ts

@@ -0,0 +1,57 @@
+/**
+ * The boot machine inputs (API §2): config identity (what triggers a reboot) and
+ * whoami resolution (`createShell → init → whoami → OS-user preresolve`). Kept
+ * pure of React so the provider's boot effect composes them.
+ */
+import type { Shell, ShellConfig } from '@astrale-os/shell'
+
+import type { SelfNode } from '../session.context'
+
+export function isShellConfig(config: ShellConfig | Shell): config is ShellConfig {
+  return 'mode' in config
+}
+
+let prebuiltCounter = 0
+const prebuiltIds = new WeakMap<object, string>()
+/** Stable id per prebuilt-Shell object reference (a new object reboots). */
+function prebuiltId(shell: object): string {
+  let id = prebuiltIds.get(shell)
+  if (id === undefined) {
+    prebuiltCounter += 1
+    id = `prebuilt#${prebuiltCounter}`
+    prebuiltIds.set(shell, id)
+  }
+  return id
+}
+
+/**
+ * Identity of a config — primitive fields only, so re-passing an inline `fetch`,
+ * `adapter`, `getCredential`, or `parentWindow` each render does not reboot;
+ * changing the kernel/credential does. A principal switch driven by a NEW
+ * `getCredential` closure (rather than a new `credential` string) is therefore
+ * NOT observed here — remount the provider (React `key`) to rebind it.
+ */
+export function configIdentity(config: ShellConfig | Shell): string {
+  if (!isShellConfig(config)) return prebuiltId(config)
+  if (config.mode === 'standalone') {
+    return [
+      'standalone',
+      config.kernelUrl,
+      config.credential ?? '',
+      config.mintIdentity ?? '',
+      config.windowId ?? '',
+    ].join('|')
+  }
+  return `sandboxed|${config.initTimeoutMs ?? ''}`
+}
+
+/** Resolve whoami when the bound kernel exposes an auth surface; else null. */
+export async function resolveSelf(shell: Shell): Promise<SelfNode | null> {
+  const kernel = shell.kernel as unknown as {
+    auth?: { whoami?: () => Promise<SelfNode> }
+  }
+  const auth = kernel.auth
+  const whoami = auth?.whoami
+  if (typeof whoami !== 'function') return null
+  return whoami.call(auth)
+}

package/src/session/boot/ownership.ts

@@ -0,0 +1,54 @@
+/**
+ * StrictMode/HMR single-ownership + deferred teardown (API §2). A booted shell's
+ * dispose is deferred one macrotask keyed by the SHELL object, so a synchronous
+ * re-mount (StrictMode/HMR, or a different provider reusing a prebuilt Shell)
+ * adopts the same shell by cancelling the pending dispose before it fires.
+ */
+import type { Shell } from '@astrale-os/shell'
+
+export interface BootRef {
+  key: string | null
+  shell: Shell | null
+  /** Bumped per boot attempt; an in-flight init/whoami whose generation is stale is ignored. */
+  generation: number
+}
+
+/**
+ * Pending deferred teardowns keyed by the SHELL object (not the provider): a new
+ * adopter of the same shell — a StrictMode/HMR re-setup, OR a different provider
+ * instance reusing a prebuilt Shell — cancels the pending dispose before it
+ * fires, so the old provider's timer can never dispose a shell the new one just
+ * adopted. Config-built shells are unique per boot, so they never collide here.
+ */
+const pendingTeardowns = new WeakMap<Shell, ReturnType<typeof setTimeout>>()
+
+export function cancelTeardown(shell: Shell): void {
+  const timer = pendingTeardowns.get(shell)
+  if (timer !== undefined) {
+    clearTimeout(timer)
+    pendingTeardowns.delete(shell)
+  }
+}
+
+/** Defer a shell's dispose one macrotask, resetting the owning ref when it fires. */
+export function scheduleTeardown(shell: Shell, ref: BootRef): void {
+  cancelTeardown(shell)
+  const timer = setTimeout(() => {
+    pendingTeardowns.delete(shell)
+    ref.generation += 1
+    disposeShell(shell)
+    if (ref.shell === shell) ref.shell = null
+    ref.key = null
+  }, 0)
+  pendingTeardowns.set(shell, timer)
+}
+
+export function disposeShell(shell: Shell): void {
+  // Best-effort: dispose never rejects meaningfully for a booted shell.
+  try {
+    const result = shell.dispose() as unknown
+    if (result instanceof Promise) result.catch(() => undefined)
+  } catch {
+    /* swallow — teardown must not throw */
+  }
+}