@astrale-os/shell-react 0.1.0

package/src/graph/guards.error.ts

@@ -0,0 +1,58 @@
+/**
+ * Error taxonomy (API §1.4) — re-exported from kernel-client so shell-react
+ * consumers narrow dispatch failures through the single import surface. The
+ * dispatched kernel call stays the source of truth; these guards drive UI
+ * affordances (retry, request-access, toast). Names match kernel-client exactly.
+ */
+export {
+  AuthBatchError,
+  AuthenticationError,
+  ClientSessionError,
+  ConnectionError,
+  DisconnectedError,
+  InvalidTransportError,
+  InvariantViolationError,
+  KernelError,
+  NodeUnavailableError,
+  NotFoundError,
+  PermissionDeniedError,
+  TimeoutError,
+  UnsupportedTransportError,
+  ValidationError,
+  WebOSError,
+  classifyKernelError,
+  isAuthBatchError,
+  isAuthenticationError,
+  isClientSessionError,
+  isDelegationMintError,
+  isDelegationPolicyError,
+  isDelegationRefusedError,
+  isHopLimitExceededError,
+  isIdentityError,
+  isInternalKernelError,
+  isInvalidRequestError,
+  isInvalidTransportError,
+  isInvariantViolationError,
+  isKernelError,
+  isNodeUnavailableError,
+  isNotFoundError,
+  isParseError,
+  isPermissionDeniedError,
+  isPersistenceLoadFailedError,
+  isPoolClosedError,
+  isRedirectPolicyError,
+  isRedirectRefusedError,
+  isRegistryWriteFailedError,
+  isSchemaOwnershipConflictError,
+  isTransportError,
+  isUnsupportedTransportError,
+  isValidationError,
+  isWebOSError,
+} from '@astrale-os/kernel-client'
+export type {
+  AuthReason,
+  ClientErrorDetails,
+  IdentityError,
+  KernelErrorKind,
+  TransportError,
+} from '@astrale-os/kernel-client'

package/src/graph/index.ts

@@ -0,0 +1,20 @@
+// graph — the graph plane (API §5 + §7). Merged read hooks, writes, dispatch.
+export { useNode } from './query/node.hook'
+export type { NodeResult } from './query/node.hook'
+export { useChildren } from './query/children.hook'
+export type { ChildrenOptions, ChildrenResult } from './query/children.hook'
+export { useQuery } from './query/query.hook'
+export type { QueryResult } from './query/query.hook'
+export { useGraph } from './query/graph.hook'
+export { useMutate } from './mutate/mutate.hook'
+export type { UseMutateOptions } from './mutate/mutate.hook'
+export { useMove } from './mutate/move.hook'
+export type { MoveAction } from './mutate/move.hook'
+export { useCall } from './call/call.hook'
+export type { CallOptions } from './call/call.hook'
+export { useStream } from './call/stream.hook'
+export type { StreamHandle, StreamOptions } from './call/stream.hook'
+export type { Action } from './action'
+export type { ReadState, ReadOptions, Windowed, Node } from './memory/read/envelope'
+export type { GraphMemory } from './graph.context'
+export type { ShapeInput } from '@astrale-os/kernel-client/store'

package/src/graph/memory/base.ts

@@ -0,0 +1,50 @@
+import type { GraphApi } from '@astrale-os/kernel-client/graph'
+import type { GraphMemory, MemoryEvent } from '@astrale-os/kernel-client/store'
+/**
+ * The base memory (API §5.4). One `GraphMemory` per live Shell — the partial
+ * client copy of the graph every graph/schema/nav hook reads through, so they all
+ * share one cache, one dedupe, one optimistic overlay. Derived from `shell.kernel`
+ * and memoized on the Shell object. Its `onError` fans out through a per-Shell
+ * sink the provider registers, so warm-refresh failures and rolled-back mutations
+ * reach the provider's `onError` channel (§2).
+ */
+import type { Shell } from '@astrale-os/shell'
+
+import { createMemory } from '@astrale-os/kernel-client/store'
+
+/** One memory per Shell reference — shared by every hook under that provider. */
+const memoryByShell = new WeakMap<Shell, GraphMemory>()
+
+/**
+ * Per-Shell error sink (API §2/§8). The provider registers a bridge here; the
+ * memory emits refresh/mutation/divergence events through it, read lazily at
+ * emit time so registration order doesn't matter. Cleared on provider unmount.
+ */
+const errorSinks = new WeakMap<Shell, (event: MemoryEvent) => void>()
+
+/** Register (or clear) the provider's memory-event bridge for a Shell. */
+export function setMemoryErrorSink(
+  shell: Shell,
+  sink: ((event: MemoryEvent) => void) | null,
+): void {
+  if (sink === null) errorSinks.delete(shell)
+  else errorSinks.set(shell, sink)
+}
+
+/**
+ * The base (default-scope) memory for a Shell — the SAME instance every graph/
+ * schema/nav hook reads through `useMemory`, so the provider can seat it in
+ * `GraphContext` (selection's liveness source) without minting a rival copy.
+ * Its `onError` fans out through the per-Shell sink so warm-refresh failures and
+ * rolled-back mutations reach `ShellProvider`'s `onError` channel (§2).
+ */
+export function baseMemoryFor(shell: Shell): GraphMemory {
+  let memory = memoryByShell.get(shell)
+  if (memory === undefined) {
+    memory = createMemory(shell.kernel as GraphApi, {
+      onError: (event) => errorSinks.get(shell)?.(event),
+    })
+    memoryByShell.set(shell, memory)
+  }
+  return memory
+}

package/src/graph/memory/read/envelope.ts

@@ -0,0 +1,98 @@
+/**
+ * The read envelope (API §1.1, §1.5) — the shape every read hook's result
+ * extends (`ReadState` + `Windowed`), the `ReadOptions` accepted by every read,
+ * and the assembly of the unified `RawRead` projection over a memory shape
+ * (empty/idle/keep-previous builders). Dependency-light so every context can
+ * consume it without a cycle.
+ */
+import type { LiveResult } from '@astrale-os/kernel-client/store'
+
+// ── Read envelope (§1.1) ─────────────────────────────────────────────────────
+
+/** Base of every read hook's result — stale-while-revalidate + liveness + seq. */
+export interface ReadState {
+  /** A (re)validation is in flight; data shown alongside is last-good. */
+  readonly pending: boolean
+  /** Last refresh failure; last-good data is retained. Cleared on next success. */
+  readonly error: unknown
+  /** A watch subscription is active for this shape (Tier ≥ 1), or Tier-0 only. */
+  readonly live: boolean
+  /** Journal position this result reflects (FRONTEND spec §6.1). 0 until known. */
+  readonly seq: number
+  /** Manual revalidate. Rarely needed; kept for tooling and non-live reads. */
+  refetch(): Promise<void>
+}
+
+/** Windowed reads add a cursor-fold `more`. */
+export interface Windowed {
+  readonly more: {
+    readonly has: boolean
+    load(): Promise<void>
+    readonly pending: boolean
+  }
+}
+
+/** Options accepted by every read hook (§1.5). */
+export interface ReadOptions {
+  /** default true; false = one-shot snapshot. */
+  live?: boolean
+  /** default true; false → pending-without-data on cold. */
+  suspend?: boolean
+  /** default false; show previous shape's data while a new one confirms. */
+  keepPrevious?: boolean
+  /** Visibility permission on the underlying AST — a kernel permission bitmask. */
+  with?: number
+}
+
+/** A graph node — derived from the memory result so no direct kernel-core import is needed. */
+export type Node = NonNullable<LiveResult['node']>
+
+/** Read options plus the windowing lever `useChildren`/`useQuery` add. */
+export type CoreReadOptions = ReadOptions & { window?: 'append' | 'paged' }
+
+/**
+ * The unified read projection: every data arm the memory materializes, over
+ * the shell-react read envelope (`ReadState` + `Windowed`). Each hook narrows
+ * to the arms it exposes. The store's `LiveResult` is a structural superset, so
+ * the warm path returns it directly (stable ref).
+ */
+export interface RawRead extends ReadState, Windowed {
+  readonly nodes: readonly Node[]
+  readonly roots: readonly Node[]
+  readonly first: Node | null
+  readonly children: readonly Node[]
+  gathered(alias: string): { readonly nodes: readonly Node[]; readonly first: Node | null }
+}
+
+export const EMPTY: readonly Node[] = []
+
+const idleGathered = (): { readonly nodes: readonly Node[]; readonly first: Node | null } => ({
+  nodes: EMPTY,
+  first: null,
+})
+const idleMore: Windowed['more'] = { has: false, pending: false, load: () => Promise.resolve() }
+
+export function emptyRead(pending: boolean): RawRead {
+  return {
+    nodes: EMPTY,
+    roots: EMPTY,
+    first: null,
+    children: EMPTY,
+    gathered: idleGathered,
+    pending,
+    error: undefined,
+    live: false,
+    seq: 0,
+    more: idleMore,
+    refetch: () => Promise.resolve(),
+  }
+}
+/** The result for a null/undefined subject (§1.3) — settled, empty, no I/O. */
+export const IDLE_READ = emptyRead(false)
+/** Cold shape with `suspend:false` (§1.4) — empty data, pending true. */
+export const EMPTY_PENDING = emptyRead(true)
+
+/** Previous shape's data while a new one confirms (§1.5 `keepPrevious`). */
+export function withPending(prev: LiveResult): RawRead {
+  return { ...prev, pending: true }
+}

package/src/graph/memory/read/idle.ts

@@ -0,0 +1,24 @@
+/**
+ * The idle-input rule (API §1.3). A read hook's `null | undefined` subject is
+ * inert: `isIdleInput` is the one gate every read branches on, and
+ * `idleReadState` is the settled, not-live, seq-0 envelope it returns.
+ */
+import type { ReadState } from './envelope'
+
+/**
+ * The chaining rule: every read hook accepts `null | undefined` for its subject
+ * and returns an *idle* result (empty data, no I/O). This predicate is the one
+ * gate — read hooks branch on it before touching the memory.
+ */
+export function isIdleInput(subject: unknown): subject is null | undefined {
+  return subject === null || subject === undefined
+}
+
+/**
+ * The idle `ReadState` a read hook returns for a `null`/`undefined` subject:
+ * settled, not live, seq 0, `refetch` a resolved no-op.
+ */
+export function idleReadState(): ReadState {
+  return { pending: false, error: undefined, live: false, seq: 0, refetch: idleRefetch }
+}
+const idleRefetch = (): Promise<void> => Promise.resolve()

package/src/graph/memory/read/read.ts

@@ -0,0 +1,103 @@
+import type {
+  LiveResult,
+  ReadOptions as StoreReadOptions,
+  ShapeInput,
+} from '@astrale-os/kernel-client/store'
+
+import { canonicalizeAST, shapeInputToAST, stableStringify } from '@astrale-os/kernel-client/store'
+/**
+ * The shared read substrate (API §1, §5). One `useSyncExternalStore` binding over
+ * a memory shape — the substrate every graph read hook narrows. Handles the four
+ * cross-cutting concerns once: idle inputs (§1.3), suspense-first on a cold shape
+ * (§1.4), stale-while-revalidate + `keepPrevious` (§1.5), and referential
+ * stability (§1.7 — an unchanged shape returns the store's own stable snapshot).
+ */
+import { useCallback, useRef, useSyncExternalStore } from 'react'
+
+import type { CoreReadOptions, RawRead } from './envelope'
+
+import { useMemory } from '../scope'
+import { EMPTY_PENDING, IDLE_READ, withPending } from './envelope'
+import { isIdleInput } from './idle'
+
+const NOOP_UNSUB = (): void => {}
+const IDLE_TOKEN = ' idle'
+
+/** Project shell-react read options onto the store's — `with`/`window`/`live` key the shape. */
+function storeReadOptions(opts?: CoreReadOptions): StoreReadOptions | undefined {
+  if (opts === undefined) return undefined
+  const out: StoreReadOptions = {}
+  if (opts.live !== undefined) out.live = opts.live
+  if (opts.window !== undefined) out.window = opts.window
+  // `with` is a PermName at the store/kernel (READ lit-up today); the public
+  // `PermMask` typing reconciles with the grant epoch (API §14 G7).
+  if (opts.with !== undefined) out.with = opts.with as unknown as StoreReadOptions['with']
+  return out
+}
+
+/**
+ * A stable per-render key for a shape input + its keying options, so the
+ * subscription/snapshot closures only re-bind when the LOGICAL read changes
+ * (not when an inline builder closure is re-created each render).
+ */
+function shapeToken(shape: ShapeInput, opts?: CoreReadOptions): string {
+  const canon = stableStringify(canonicalizeAST(shapeInputToAST(shape)))
+  return `${canon}#w=${String(opts?.with ?? '')}#win=${opts?.window ?? ''}#live=${
+    opts?.live === false ? '0' : '1'
+  }`
+}
+
+/**
+ * Subscribe to a memory shape and project it. `null`/`undefined` shape → idle.
+ * Cold + `suspend` (default) throws the cold-shape promise; `suspend:false`
+ * returns empty-pending; `keepPrevious` returns the last data while confirming.
+ */
+export function useRead(shape: ShapeInput | null | undefined, opts?: CoreReadOptions): RawRead {
+  const memory = useMemory()
+  const idle = isIdleInput(shape)
+
+  const shapeRef = useRef<ShapeInput | null | undefined>(shape)
+  shapeRef.current = shape
+  const optsRef = useRef<CoreReadOptions | undefined>(opts)
+  optsRef.current = opts
+
+  const token = idle ? IDLE_TOKEN : shapeToken(shape as ShapeInput, opts)
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      const s = shapeRef.current
+      if (token === IDLE_TOKEN || s === null || s === undefined) return NOOP_UNSUB
+      return memory.subscribe(s, onStoreChange, storeReadOptions(optsRef.current))
+    },
+    [memory, token],
+  )
+  const getSnapshot = useCallback((): LiveResult | null => {
+    const s = shapeRef.current
+    if (token === IDLE_TOKEN || s === null || s === undefined) return null
+    return memory.getSnapshot(s, storeReadOptions(optsRef.current))
+  }, [memory, token])
+
+  const snap = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+  const prevRef = useRef<LiveResult | null>(null)
+
+  if (idle) return IDLE_READ
+
+  const warm = memory.peek(shape as ShapeInput, storeReadOptions(opts)) !== null
+  if (warm && snap !== null) {
+    prevRef.current = snap
+    return snap
+  }
+  if (opts?.keepPrevious === true && prevRef.current !== null) {
+    return withPending(prevRef.current)
+  }
+  if (opts?.suspend !== false) {
+    // Cold FAILURE (§1.4): the shape fetched and rejected with no data to show —
+    // throw the error to the nearest boundary. Re-throwing the promise here would
+    // re-arm a fresh fetch every retry (the entry's inflight was cleared on
+    // failure), looping render→fetch→reject forever. This breaks that loop.
+    if (snap !== null && snap.error !== undefined) throw snap.error
+    // Cold shape: suspend on the first-confirmed-data promise (§1.4).
+    throw memory.promise(shape as ShapeInput, storeReadOptions(opts))
+  }
+  return EMPTY_PENDING
+}

package/src/graph/memory/scope.ts

@@ -0,0 +1,29 @@
+import type { GraphApi } from '@astrale-os/kernel-client/graph'
+import type { GraphMemory } from '@astrale-os/kernel-client/store'
+
+/**
+ * Memory scope resolution (API §5.4). `useMemory` returns the memory for this
+ * subtree: the base memory derived from the provider's Shell, re-scoped (and
+ * re-api'd) to the `<ActAs>` principal via `forScope` when an identity binding is
+ * present — so a principal never shares cached results with another.
+ */
+import { useContext, useMemo } from 'react'
+
+import { IdentityContext } from '../../auth/act-as.context'
+import { ShellContext } from '../../session/session.context'
+import { baseMemoryFor } from './base'
+
+/**
+ * The memory for this subtree. Throws outside a `<ShellProvider>`. Above any
+ * `<ActAs>` it is the base memory; inside one it is scoped by the binding.
+ */
+export function useMemory(): GraphMemory {
+  const runtime = useContext(ShellContext)
+  const binding = useContext(IdentityContext)
+  const shell = runtime?.shell ?? null
+  return useMemo(() => {
+    if (shell === null) throw new Error('graph hooks must be used within a <ShellProvider>')
+    const base = baseMemoryFor(shell)
+    return binding === null ? base : base.forScope(binding.scope, binding.kernel as GraphApi)
+  }, [shell, binding])
+}

package/src/graph/mutate/move.hook.ts

@@ -0,0 +1,70 @@
+import type { NodeRefInput } from '@astrale-os/kernel-client'
+import type { PathLike } from '@astrale-os/kernel-client/graph'
+import type { GraphMemory } from '@astrale-os/kernel-client/store'
+
+import { rawOf } from '@astrale-os/kernel-client/graph'
+/**
+ * useMove (API §5, the G1 seam) — dispatch the sealed `node::move` method (the one
+ * tree op no patch arm can express). PESSIMISTIC today (honest `pending`); affected
+ * container shapes revalidate on settlement. Turns optimistic when the `nodes.move`
+ * patch arm lands, with zero consumer change.
+ */
+import { useCallback } from 'react'
+
+import type { Action } from '../action'
+import type { Node } from '../memory/read/envelope'
+
+import { useSessionKernel } from '../../auth/session-kernel'
+import { useAction } from '../action'
+import { useMemory } from '../memory/scope'
+
+export type MoveAction = Action<[node: Node | NodeRefInput, to: PathLike], void>
+
+export function useMove(): MoveAction {
+  const kernel = useSessionKernel()
+  const memory = useMemory()
+  const run = useCallback(
+    async (node: Node | NodeRefInput, to: PathLike): Promise<void> => {
+      const method = isNode(node) ? `@${node.id}::move` : `${rawOf(node)}::move`
+      await kernel.call(method, { to: rawOf(to) })
+      await reconcileMove(memory, node, to)
+    },
+    [kernel, memory],
+  )
+  return useAction(run)
+}
+
+function isNode(x: Node | NodeRefInput): x is Node {
+  return typeof x === 'object' && x !== null && 'id' in x && 'class' in x && 'path' in x
+}
+
+/** Root-first parent of a raw absolute path, or `null` at the root. */
+function parentPathOf(raw: string): string | null {
+  const trimmed = raw.replace(/\/+$/, '')
+  const i = trimmed.lastIndexOf('/')
+  if (i < 0) return null
+  return i === 0 ? '/' : trimmed.slice(0, i)
+}
+
+/**
+ * Best-effort settlement reconciliation (Tier 0): refetch the source and
+ * destination container's default `children` shapes when they are observed. A
+ * custom-ordered/filtered children shape is keyed distinctly and is not reached
+ * here — consumers get honest `pending` and reconcile on G1.
+ */
+async function reconcileMove(
+  memory: GraphMemory,
+  node: Node | NodeRefInput,
+  to: PathLike,
+): Promise<void> {
+  const path = isNode(node) ? rawOf(node.path) : rawOf(node)
+  const containers = new Set<string>([rawOf(to)])
+  const old = parentPathOf(path)
+  if (old !== null) containers.add(old)
+  await Promise.allSettled(
+    [...containers].map((c) => {
+      const snap = memory.peek((q) => q.from(c).children())
+      return snap !== null ? snap.refetch() : Promise.resolve()
+    }),
+  )
+}

package/src/graph/mutate/mutate.hook.ts

@@ -0,0 +1,69 @@
+import type { PatchBuilder } from '@astrale-os/kernel-client/graph'
+import type { GraphMemory } from '@astrale-os/kernel-client/store'
+
+/**
+ * useMutate (API 5/1.6) - build a graph-scoped Action. The callback receives
+ * this subtree's GraphMemory, so callers do not need a separate useGraph() just
+ * to author the mutation. Patch-shaped writes are optimistic via their own
+ * overlay; pass a function `optimistic` to preview an opaque dispatch effect.
+ */
+import { useCallback, useRef } from 'react'
+
+import type { Action } from '../action'
+
+import { useAction } from '../action'
+import { useMemory } from '../memory/scope'
+
+export interface UseMutateOptions<A extends unknown[], R> {
+  /**
+   * `'auto'` (default) / `false`: the write's own overlay governs optimism - the
+   * callback's graph writes apply the authored patch. A function opens a
+   * MANUAL overlay decoupled from what the callback dispatches.
+   */
+  optimistic?: 'auto' | false | ((overlay: PatchBuilder, ...args: A) => void)
+  /** default 'auto'. false = keep the manual overlay on failure (caller reconciles). */
+  rollback?: 'auto' | false
+  onCommit?: (result: R) => void
+  onError?: (error: unknown) => void
+}
+
+export function useMutate<A extends unknown[], R>(
+  fn: (graph: GraphMemory, ...args: A) => Promise<R>,
+  opts?: UseMutateOptions<A, R>,
+): Action<A, R> {
+  const memory = useMemory()
+  const fnRef = useRef(fn)
+  fnRef.current = fn
+  const optsRef = useRef(opts)
+  optsRef.current = opts
+
+  const run = useCallback(
+    async (...args: A): Promise<R> => {
+      const o = optsRef.current
+      const optimistic = o?.optimistic
+      if (typeof optimistic === 'function') {
+        const overlay = memory.overlay((m) => optimistic(m, ...args))
+        try {
+          const result = await fnRef.current(memory, ...args)
+          overlay.commit()
+          o?.onCommit?.(result)
+          return result
+        } catch (error) {
+          if (o?.rollback !== false) overlay.rollback()
+          o?.onError?.(error)
+          throw error
+        }
+      }
+      try {
+        const result = await fnRef.current(memory, ...args)
+        o?.onCommit?.(result)
+        return result
+      } catch (error) {
+        o?.onError?.(error)
+        throw error
+      }
+    },
+    [memory],
+  )
+  return useAction(run)
+}

package/src/graph/query/children.hook.ts

@@ -0,0 +1,136 @@
+import type { AnyBoundNode, TypeNames } from '@astrale-os/kernel-client'
+import type {
+  GatherBuilder,
+  OrderInput,
+  PathLike,
+  QuerySource,
+  WalkOpts,
+} from '@astrale-os/kernel-client/graph'
+import type { Schema } from '@astrale-os/kernel-dsl'
+
+import { rawOf } from '@astrale-os/kernel-client/graph'
+/**
+ * useChildren (API §5 + §6) — ONE public symbol, overloaded: pass `opts.type`
+ * (over a `BoundNode` parent) for the typed children, or a bare parent for the
+ * untyped children. Both ride the SAME windowed memory shape. The untyped floor
+ * is a windowed, live read of a node's direct children; the typed twin binds them.
+ */
+import { useMemo } from 'react'
+
+import type { TypedChildrenResult } from '../../schema/types'
+import type { ReadState, Node, ReadOptions, Windowed } from '../memory/read/envelope'
+
+import { useChildren as useChildrenTyped } from '../../schema/bind-read'
+import { useRead } from '../memory/read/read'
+
+export interface ChildrenOptions extends ReadOptions {
+  /** Restrict to these classes (dual-path descent filter). */
+  classes?: PathLike[]
+  /** Server-ordered by a node prop / `id`. */
+  order?: OrderInput
+  /** Page size; `more.load()` extends. */
+  limit?: number
+  /** `append` (default, infinite) vs `paged` (replace). */
+  window?: 'append' | 'paged'
+}
+
+export interface ChildrenResult extends ReadState, Windowed {
+  /** Ordered, all loaded pages, parent excluded. */
+  readonly children: readonly Node[]
+}
+
+/** A node's direct children — windowed, live; `null` parent is idle (§1.3). */
+function useChildrenUntyped(
+  parent: Node | PathLike | null | undefined,
+  opts?: ChildrenOptions,
+): ChildrenResult {
+  const shape = isIdle(parent) ? null : childrenShape(parent, opts)
+  const r = useRead(shape, opts)
+  return useMemo(
+    () => ({
+      pending: r.pending,
+      error: r.error,
+      live: r.live,
+      seq: r.seq,
+      refetch: r.refetch,
+      children: r.children,
+      more: r.more,
+    }),
+    [r],
+  )
+}
+
+/** Typed: a bound node's children of `opts.type`. */
+export function useChildren<S extends Schema, T extends TypeNames<S>>(
+  parent: AnyBoundNode<S> | null | undefined,
+  opts: ReadOptions & {
+    type: T
+    order?: OrderInput
+    limit?: number
+    window?: 'append' | 'paged'
+  },
+): TypedChildrenResult<S, T>
+/** Untyped: a node's direct children — windowed, live; `null` parent is idle (§1.3). */
+export function useChildren(
+  parent: Node | PathLike | null | undefined,
+  opts?: ChildrenOptions,
+): ChildrenResult
+export function useChildren(
+  parent: unknown,
+  opts?: unknown,
+): ReadState & Windowed & { readonly children: readonly unknown[] } {
+  if (hasType(opts)) {
+    return useChildrenTyped(
+      parent as AnyBoundNode<Schema> | null | undefined,
+      opts as ReadOptions & { type: string },
+    )
+  }
+  return useChildrenUntyped(
+    parent as Node | PathLike | null | undefined,
+    opts as ChildrenOptions | undefined,
+  )
+}
+
+function hasType(opts: unknown): opts is { type: string } {
+  return (
+    typeof opts === 'object' &&
+    opts !== null &&
+    'type' in opts &&
+    (opts as { type?: unknown }).type !== undefined
+  )
+}
+
+// ── internals ────────────────────────────────────────────────────────────────
+
+function isIdle(x: unknown): x is null | undefined {
+  return x === null || x === undefined
+}
+
+function isNode(x: Node | PathLike): x is Node {
+  return typeof x === 'object' && x !== null && 'id' in x && 'class' in x && 'path' in x
+}
+
+/** A parent ref anchored on the node id (stable across rename) or the raw path. */
+function refOf(parent: Node | PathLike): PathLike {
+  return isNode(parent) ? `@${parent.id}` : parent
+}
+
+function walkOptsOf(opts?: ChildrenOptions): WalkOpts | undefined {
+  if (opts === undefined) return undefined
+  const { classes, order, limit } = opts
+  if (classes === undefined && order === undefined && limit === undefined) return undefined
+  return {
+    ...(classes !== undefined ? { classes: classes.map((c) => rawOf(c)) } : {}),
+    ...(order !== undefined ? { order } : {}),
+    ...(limit !== undefined ? { limit } : {}),
+  }
+}
+
+function childrenShape(
+  parent: Node | PathLike,
+  opts?: ChildrenOptions,
+): (q: QuerySource) => GatherBuilder {
+  const ref = refOf(parent)
+  const walk = walkOptsOf(opts)
+  return (q) => q.from(ref).children(walk)
+}

package/src/graph/query/graph.hook.ts

@@ -0,0 +1,13 @@
+/**
+ * useGraph (API §5) — the memory handle for this subtree (the raw floor plus the
+ * memory's optimistic-auto write shorthands). The same scoped memory every
+ * graph/schema/nav hook reads.
+ */
+import type { GraphMemory } from '@astrale-os/kernel-client/store'
+
+import { useMemory } from '../memory/scope'
+
+/** The memory for this subtree — the raw floor plus optimistic-auto shorthands (§5). */
+export function useGraph(): GraphMemory {
+  return useMemory()
+}