@astrale-os/shell-react 0.2.9 → 0.2.10-beta.2

package/src/graph/call/stream.hook.ts

@@ -1,57 +1,44 @@
-import type { FnMap, StreamFns } from '@astrale-os/kernel-client'
+import type { Call } from '@astrale-os/kernel-client'
+import type { SessionRequestOptions } from '@astrale-os/kernel-client/session'
+import type { Value } from '@astrale-os/sdk/value'
+import type { KernelClient } from '@astrale-os/shell'
 
-/**
- * useStream (API §7) — streaming domain-function dispatch over `kernel.stream`,
- * an AsyncIterable driven by an explicit start/cancel handle. A superseding
- * `start` (or unmount) closes the prior run and discards its late chunks/errors;
- * never live. Dispatch is a graph operation (rule 2).
- */
 import { useCallback, useEffect, useReducer, useRef } from 'react'
 
 import { useSessionKernel } from '../../auth/session-kernel.js'
 
-export interface StreamOptions<T> {
-  /** Notified per chunk as it arrives (in addition to `chunks` accumulation). */
-  onChunk?(chunk: T): void
+export type KernelStream = Awaited<ReturnType<KernelClient['stream']>>
+export type StreamItem = Value
+export type CallAuthor<A extends unknown[]> = Call | ((...args: A) => Call)
+
+export interface StreamOptions<T = StreamItem> extends SessionRequestOptions {
+  readonly onChunk?: (chunk: T) => void
 }
 
-export interface StreamHandle<T> {
-  /** Begin a run: resets chunks, then resolves when the stream ends / rejects on failure. */
-  start(params: unknown): Promise<void>
-  /** Chunks accumulated in the current run; reset on the next `start`. */
+export interface StreamHandle<A extends unknown[] = unknown[], T = StreamItem> {
+  start(...args: A): Promise<void>
   readonly chunks: readonly T[]
-  /** The most recent chunk, or null before the first. */
   readonly last: T | null
-  /** A run is in flight. */
   readonly streaming: boolean
-  /** Last run failure; retained until the next `start`. */
   readonly error: unknown
-  /** Close the stream (returns the iterator); a later `start` begins fresh. */
   cancel(): void
 }
 
-interface StreamSnapshot<T> {
+interface Snapshot<T> {
   readonly chunks: readonly T[]
   readonly last: T | null
   readonly streaming: boolean
   readonly error: unknown
 }
 
-const IDLE_STREAM: StreamSnapshot<unknown> = {
-  chunks: [],
-  last: null,
-  streaming: false,
-  error: undefined,
-}
-
-type StreamEvent<T> =
+type Event<T> =
   | { readonly type: 'start' }
   | { readonly type: 'chunk'; readonly value: T }
   | { readonly type: 'end' }
   | { readonly type: 'error'; readonly error: unknown }
   | { readonly type: 'cancel' }
 
-function streamReducer<T>(state: StreamSnapshot<T>, event: StreamEvent<T>): StreamSnapshot<T> {
+function reducer<T>(state: Snapshot<T>, event: Event<T>): Snapshot<T> {
   switch (event.type) {
     case 'start':
       return { chunks: [], last: null, streaming: true, error: undefined }
@@ -63,138 +50,74 @@ function streamReducer<T>(state: StreamSnapshot<T>, event: StreamEvent<T>): Stre
         error: undefined,
       }
     case 'end':
+    case 'cancel':
       return { ...state, streaming: false }
     case 'error':
-      // Chunks accumulated before the failure are preserved.
       return { ...state, streaming: false, error: event.error }
-    case 'cancel':
-      return { ...state, streaming: false }
   }
 }
 
-/** Same shape, minus `readonly`, so the render step can re-stamp the snapshot. */
-interface MutableStreamHandle<T> {
-  start(params: unknown): Promise<void>
-  chunks: readonly T[]
-  last: T | null
-  streaming: boolean
-  error: unknown
-  cancel(): void
-}
-
-interface StreamRun<T> {
-  readonly controller: AbortController
-  iterator: AsyncIterator<T> | null
-}
-
-/**
- * Streaming domain-function dispatch. `start(params)` opens a run over
- * `kernel.stream`; chunks accumulate on `chunks`; `cancel()` closes the iterator
- * and a later `start` begins fresh. A superseding `start` (or unmount) closes the
- * prior run and discards its late chunks/errors — only the current run drives
- * state. Never live; the handle keeps one identity for the hook's lifetime.
- */
-export function useStream<K extends StreamFns<FnMap>>(
-  method: K | null,
-  opts?: StreamOptions<FnMap[K]['result']>,
-): StreamHandle<FnMap[K]['result']> {
-  type T = FnMap[K]['result']
+export function useStream<A extends unknown[] = []>(
+  author: CallAuthor<A> | null,
+  options?: StreamOptions,
+): StreamHandle<A, StreamItem> {
   const kernel = useSessionKernel()
-
-  // Latest-closure refs so the stable start/cancel dispatch the current inputs.
   const kernelRef = useRef(kernel)
   kernelRef.current = kernel
-  const methodRef = useRef(method)
-  methodRef.current = method
-  const optsRef = useRef(opts)
-  optsRef.current = opts
-
-  const [snapshot, dispatch] = useReducer(streamReducer<T>, IDLE_STREAM as StreamSnapshot<T>)
-
-  // `runId` supersession token; only the run whose id is still current drives state.
-  const runIdRef = useRef(0)
-  const currentRef = useRef<StreamRun<T> | null>(null)
-  const alive = useRef(true)
+  const authorRef = useRef(author)
+  authorRef.current = author
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+  const [snapshot, dispatch] = useReducer(reducer<StreamItem>, {
+    chunks: [],
+    last: null,
+    streaming: false,
+    error: undefined,
+  })
+  const runId = useRef(0)
+  const controller = useRef<AbortController | null>(null)
 
-  const stop = useCallback(() => {
-    const run = currentRef.current
-    if (run !== null) {
-      run.controller.abort()
-      void run.iterator?.return?.(undefined)
-      currentRef.current = null
-    }
+  const cancel = useCallback(() => {
+    runId.current += 1
+    controller.current?.abort()
+    controller.current = null
+    dispatch({ type: 'cancel' })
   }, [])
 
-  useEffect(() => {
-    alive.current = true
-    return () => {
-      alive.current = false
-      stop()
-    }
-  }, [stop])
-
-  const cancel = useCallback(() => {
-    runIdRef.current += 1
-    stop()
-    if (alive.current) dispatch({ type: 'cancel' })
-  }, [stop])
+  useEffect(() => cancel, [cancel])
 
   const start = useCallback(
-    (params: unknown): Promise<void> => {
-      const method_ = methodRef.current
-      if (method_ === null) {
-        return Promise.reject(new Error('useStream: method is null (idle handle started)'))
-      }
-      runIdRef.current += 1
-      const runId = runIdRef.current
-      stop() // close any prior run before opening the new one
+    async (...args: A): Promise<void> => {
+      const current = authorRef.current
+      if (current === null) throw new Error('useStream: idle handle started')
+      cancel()
+      const id = ++runId.current
+      const abort = new AbortController()
+      controller.current = abort
       dispatch({ type: 'start' })
-
-      const controller = new AbortController()
-      const run: StreamRun<T> = { controller, iterator: null }
-      currentRef.current = run
-      const current = (): boolean => runIdRef.current === runId
-
-      return (async () => {
-        try {
-          const iterable = await kernelRef.current.stream(method_, params, {
-            signal: controller.signal,
-          })
-          if (!current()) return
-          const iterator = iterable[Symbol.asyncIterator]()
-          run.iterator = iterator
-          for (;;) {
-            const next = await iterator.next()
-            if (!current()) return
-            if (next.done === true) break
-            if (alive.current) dispatch({ type: 'chunk', value: next.value })
-            optsRef.current?.onChunk?.(next.value)
-          }
-          if (current()) {
-            currentRef.current = null
-            if (alive.current) dispatch({ type: 'end' })
-          }
-        } catch (error) {
-          if (!current()) return // a superseded/cancelled run's failure is discarded
-          currentRef.current = null
-          if (alive.current) dispatch({ type: 'error', error })
-          throw error
+      const call = typeof current === 'function' ? current(...args) : current
+      try {
+        const { onChunk: _onChunk, ...requestOptions } = optionsRef.current ?? {}
+        const stream = await kernelRef.current.stream(call, {
+          ...requestOptions,
+          signal: abort.signal,
+        })
+        for await (const chunk of stream) {
+          if (id !== runId.current) return
+          dispatch({ type: 'chunk', value: chunk })
+          optionsRef.current?.onChunk?.(chunk)
         }
-      })()
+        if (id === runId.current) dispatch({ type: 'end' })
+      } catch (error) {
+        if (id !== runId.current) return
+        dispatch({ type: 'error', error })
+        throw error
+      } finally {
+        if (id === runId.current) controller.current = null
+      }
     },
-    [stop],
+    [cancel],
   )
 
-  // One render-stable handle: built once (start/cancel are stable), then its
-  // snapshot fields re-stamped each render so reads stay current across chunks.
-  const handleRef = useRef<MutableStreamHandle<T> | null>(null)
-  if (handleRef.current === null) {
-    handleRef.current = { start, cancel } as MutableStreamHandle<T>
-  }
-  const handle = handleRef.current
-  handle.chunks = snapshot.chunks
-  handle.last = snapshot.last
-  handle.streaming = snapshot.streaming
-  handle.error = snapshot.error
-  return handle as StreamHandle<T>
+  return { start, cancel, ...snapshot }
 }

package/src/graph/graph.context.ts

@@ -1,14 +1,9 @@
-import type { GraphMemory } from '@astrale-os/kernel-client/store'
+import type { GraphStore } from '@astrale-os/kernel-client/store'
 
-/**
- * GraphContext (ex MemoryContext) — the root of the graph plane. Seats the base
- * (default-scope) memory the provider builds; the SAME handle the graph/schema/
- * nav hooks read through `memory/scope.ts`, and selection's liveness source.
- * Under `<ActAs>` the read hooks re-scope via `forScope`; selection reads the
- * base scope here.
- */
 import { createContext } from 'react'
 
-export type { GraphMemory }
-export const GraphContext = createContext<GraphMemory | null>(null)
-GraphContext.displayName = 'AstraleGraphContext'
+/** Optional exact Client GraphStore supplied by an injected Shell adapter. */
+export const GraphContext = createContext<GraphStore | null>(null)
+GraphContext.displayName = 'AstraleGraphStoreContext'
+
+export type { GraphStore }

package/src/graph/guards.error.ts

@@ -1,58 +1,20 @@
-/**
- * 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,
+  ClientError,
+  ProtocolError,
+  ResponseError,
+  StaleRouteError,
   TransportError,
 } from '@astrale-os/kernel-client'
+export { NodeUnavailableError } from '@astrale-os/kernel-client/graph'
+export { UnsupportedFeatureError } from './memory/read/envelope.js'
+
+import { ClientError } from '@astrale-os/kernel-client'
+import { NodeUnavailableError } from '@astrale-os/kernel-client/graph'
+
+export function isClientError(error: unknown): error is ClientError {
+  return error instanceof ClientError
+}
+
+export function isNodeUnavailableError(error: unknown): error is NodeUnavailableError {
+  return error instanceof NodeUnavailableError
+}

package/src/graph/index.ts

@@ -1,20 +1,26 @@
-// graph — the graph plane (API §5 + §7). Merged read hooks, writes, dispatch.
-export { useNode } from './query/node.hook.js'
-export type { NodeResult } from './query/node.hook.js'
-export { useChildren } from './query/children.hook.js'
-export type { ChildrenOptions, ChildrenResult } from './query/children.hook.js'
-export { useQuery } from './query/query.hook.js'
-export type { QueryResult } from './query/query.hook.js'
-export { useGraph } from './query/graph.hook.js'
-export { useMutate } from './mutate/mutate.hook.js'
-export type { UseMutateOptions } from './mutate/mutate.hook.js'
-export { useMove } from './mutate/move.hook.js'
-export type { MoveAction } from './mutate/move.hook.js'
+export { useGraphStore } from './store.js'
+export { useQuery } from './query-definition.hook.js'
+export type { QueryResourceOptions } from './query-definition.hook.js'
+export type { GraphResource, GraphResourceState } from './resource.js'
 export { useCall } from './call/call.hook.js'
-export type { CallOptions } from './call/call.hook.js'
+export type { CallOptions, CallResult } from './call/call.hook.js'
 export { useStream } from './call/stream.hook.js'
-export type { StreamHandle, StreamOptions } from './call/stream.hook.js'
+export type {
+  CallAuthor,
+  KernelStream,
+  StreamHandle,
+  StreamItem,
+  StreamOptions,
+} from './call/stream.hook.js'
 export type { Action } from './action.js'
-export type { ReadState, ReadOptions, Windowed, Node } from './memory/read/envelope.js'
-export type { GraphMemory } from './graph.context.js'
-export type { ShapeInput } from '@astrale-os/kernel-client/store'
+export type { GraphStore } from './graph.context.js'
+export {
+  ClientError,
+  NodeUnavailableError,
+  ProtocolError,
+  ResponseError,
+  StaleRouteError,
+  TransportError,
+  isClientError,
+  isNodeUnavailableError,
+} from './guards.error.js'

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

@@ -1,98 +1,73 @@
-/**
- * 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'
+import type { Node as KernelNode } from '@astrale-os/sdk/graph/node'
 
-// ── Read envelope (§1.1) ─────────────────────────────────────────────────────
-
-/** Base of every read hook's result — stale-while-revalidate + liveness + seq. */
+/** Common result state for Shell React reads. */
 export interface ReadState {
-  /** A (re)validation is in flight; data shown alongside is last-good. */
+  /** A request is in flight. Last-good data may still be present. */
   readonly pending: boolean
-  /** Last refresh failure; last-good data is retained. Cleared on next success. */
+  /** Last request failure. Cleared when the next request begins. */
   readonly error: unknown
-  /** A watch subscription is active for this shape (Tier ≥ 1), or Tier-0 only. */
+  /** True only when an upstream subscription is active. */
   readonly live: boolean
-  /** Journal position this result reflects (FRONTEND spec §6.1). 0 until known. */
+  /** Reserved journal position. Direct Graph reads report zero. */
   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
+    load(): Promise<void>
   }
 }
 
-/** Options accepted by every read hook (§1.5). */
+/** Options shared by point, Query, and neighbor reads. */
 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
+  readonly signal?: AbortSignal
+  readonly timeoutMs?: number
+  /** Retain the previous successful value while the next request is pending. */
+  readonly keepPrevious?: boolean
 }
 
-/** A graph node — derived from the memory result so no direct kernel-core import is needed. */
-export type Node = NonNullable<LiveResult['node']>
+export type Node = KernelNode
 
-/** Read options plus the windowing lever `useChildren`/`useQuery` add. */
-export type CoreReadOptions = ReadOptions & { window?: 'append' | 'paged' }
+export const EMPTY_NODES: readonly Node[] = Object.freeze([])
 
-/**
- * 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 NO_MORE: Windowed['more'] = Object.freeze({
+  has: false,
+  pending: false,
+  load: () => Promise.resolve(),
+})
 
-export const EMPTY: readonly Node[] = []
+/** Stable failure for a retained hook whose required Kernel capability does not exist. */
+export class UnsupportedFeatureError extends Error {
+  readonly code = 'SHELL_REACT_UNSUPPORTED' as const
+  readonly feature: string
 
-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() }
+  constructor(feature: string) {
+    super(`${feature} is not supported by the current Kernel Graph contract.`)
+    this.name = 'UnsupportedFeatureError'
+    this.feature = feature
+  }
+}
 
-export function emptyRead(pending: boolean): RawRead {
+export function idleReadState(): ReadState {
   return {
-    nodes: EMPTY,
-    roots: EMPTY,
-    first: null,
-    children: EMPTY,
-    gathered: idleGathered,
-    pending,
+    pending: false,
     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 }
+export function unsupportedReadState(feature: string): ReadState {
+  const error = new UnsupportedFeatureError(feature)
+  return {
+    pending: false,
+    error,
+    live: false,
+    seq: 0,
+    refetch: () => Promise.reject(error),
+  }
 }

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

@@ -1,24 +1,11 @@
-/**
- * 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.js'
 
-/**
- * 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
+import { idleReadState as idle } from './envelope.js'
+
+export function isIdleInput(value: unknown): value is null | undefined {
+  return value === null || value === 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 }
+  return idle()
 }
-const idleRefetch = (): Promise<void> => Promise.resolve()