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

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()

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

@@ -0,0 +1,270 @@
+import type { GraphStore, StoreQueryResponse, StoreSnapshot } from '@astrale-os/kernel-client/store'
+import type {
+  QueryAstExecutionOptions,
+  QueryDefinition,
+  QueryValueBinder,
+} from '@astrale-os/sdk/query'
+import type { QueryAST } from '@astrale-os/sdk/query'
+import type { DomainBinding } from '@astrale-os/shell'
+
+import { bindQueries } from '@astrale-os/sdk/query'
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react'
+
+import type { GraphResource, GraphResourceState } from './resource.js'
+
+import { useDynamicDomain } from '../schema/domain.hook.js'
+import { retainRefreshScheduler } from './resource.js'
+import { useGraphStore } from './store.js'
+
+export interface QueryResourceOptions {
+  readonly keepPrevious?: boolean
+  readonly refreshInterval?: number
+  readonly refreshWhen?: 'always' | 'visible'
+}
+
+interface TouchedShape {
+  readonly ast: QueryAST
+  readonly options: QueryAstExecutionOptions
+}
+
+interface DefinitionSnapshot<Output> {
+  readonly state: GraphResourceState
+  readonly data?: Output
+  readonly error?: unknown
+}
+
+class DefinitionObserver<Input, Output, Query extends QueryAST> {
+  private readonly listeners = new Set<() => void>()
+  private subscriptions: readonly (() => void)[] = Object.freeze([])
+  private touched: readonly TouchedShape[] = Object.freeze([])
+  private current: DefinitionSnapshot<Output> = Object.freeze({ state: 'loading' })
+  private generation = 0
+  private pending: Promise<void> | null = null
+  private started = false
+  private rerunQueued = false
+
+  constructor(
+    private readonly store: GraphStore,
+    private readonly binding: DomainBinding,
+    private readonly definition: QueryDefinition<Input, Output, Query>,
+    private readonly input: Input,
+  ) {}
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  getSnapshot = (): DefinitionSnapshot<Output> => this.current
+
+  start(): () => void {
+    this.started = true
+    void this.run('cached')
+    return () => {
+      this.started = false
+      this.generation += 1
+      this.subscriptions.forEach((unsubscribe) => unsubscribe())
+      this.subscriptions = Object.freeze([])
+    }
+  }
+
+  refresh = async (): Promise<void> => {
+    await this.run('refresh')
+  }
+
+  private run(freshness: 'cached' | 'refresh'): Promise<void> {
+    if (this.pending !== null && freshness === 'cached') return this.pending
+    const generation = ++this.generation
+    const touched: TouchedShape[] = []
+    this.update({
+      state: this.current.data === undefined ? 'loading' : 'refreshing',
+      ...(this.current.data === undefined ? {} : { data: this.current.data }),
+    })
+    const execute = async <Ast extends QueryAST>(
+      ast: Ast,
+      options: QueryAstExecutionOptions,
+    ): Promise<StoreQueryResponse<Ast>> => {
+      touched.push(Object.freeze({ ast, options }))
+      return this.store.read(ast, { ...options, freshness })
+    }
+    const bind = this.binding.$.bind as unknown as QueryValueBinder
+    const query = bindQueries(execute, { bind })
+    const running = query(this.definition, this.input)
+      .then((data) => {
+        if (!this.started || generation !== this.generation) return
+        this.touched = dedupeShapes(touched)
+        this.bindShapes()
+        this.update({ state: this.storeState(), data })
+      })
+      .catch((error: unknown) => {
+        if (!this.started || generation !== this.generation) return
+        this.touched = dedupeShapes(touched)
+        this.bindShapes()
+        this.update({
+          state: 'failed',
+          ...(this.current.data === undefined ? {} : { data: this.current.data }),
+          error,
+        })
+      })
+      .finally(() => {
+        if (this.pending === running) this.pending = null
+      })
+    this.pending = running
+    return running
+  }
+
+  private bindShapes(): void {
+    this.subscriptions.forEach((unsubscribe) => unsubscribe())
+    this.subscriptions = Object.freeze(
+      this.touched.map(({ ast, options }) =>
+        this.store.subscribe(ast, this.onStoreChange, options),
+      ),
+    )
+  }
+
+  private onStoreChange = (): void => {
+    const state = this.storeState()
+    this.update({
+      state,
+      ...(this.current.data === undefined ? {} : { data: this.current.data }),
+      ...(this.current.error === undefined ? {} : { error: this.current.error }),
+    })
+    if ((state === 'ready' || state === 'optimistic') && !this.rerunQueued) {
+      this.rerunQueued = true
+      queueMicrotask(() => {
+        this.rerunQueued = false
+        if (this.started) void this.run('cached')
+      })
+    }
+  }
+
+  private storeState(): GraphResourceState {
+    const snapshots = this.touched.map(({ ast, options }) => this.store.getSnapshot(ast, options))
+    if (snapshots.length === 0) return this.current.state
+    return combine(snapshots)
+  }
+
+  private update(next: DefinitionSnapshot<Output>): void {
+    if (
+      next.state === this.current.state &&
+      next.data === this.current.data &&
+      next.error === this.current.error
+    )
+      return
+    this.current = Object.freeze(next)
+    this.listeners.forEach((listener) => listener())
+  }
+}
+
+/** Execute one named SDK Query definition exclusively through the current GraphStore. */
+export function useQuery<Input, Output, Query extends QueryAST>(
+  definition: QueryDefinition<Input, Output, Query> | null,
+  input: Input,
+  options: QueryResourceOptions = {},
+): GraphResource<Output> {
+  const store = useGraphStore()
+  const binding = useDynamicDomain()
+  const inputIdentity = stableIdentity(input)
+  const observer = useMemo(
+    () => (definition === null ? null : new DefinitionObserver(store, binding, definition, input)),
+    [store, binding, definition, inputIdentity],
+  )
+  const idle = useMemo<DefinitionSnapshot<Output>>(() => Object.freeze({ state: 'idle' }), [])
+  const subscribe = useCallback(
+    (listener: () => void) => observer?.subscribe(listener) ?? (() => {}),
+    [observer],
+  )
+  const snapshot = useCallback(() => observer?.getSnapshot() ?? idle, [observer, idle])
+  const current = useSyncExternalStore(subscribe, snapshot, snapshot)
+  useEffect(() => observer?.start(), [observer])
+
+  const identity = definition === null ? 'idle' : `${definition.id}\u0000${inputIdentity}`
+  useEffect(() => {
+    if (observer === null || options.refreshInterval === undefined) return
+    return retainRefreshScheduler(
+      store,
+      identity,
+      observer.refresh,
+      options.refreshInterval,
+      options.refreshWhen ?? 'visible',
+    )
+  }, [store, observer, identity, options.refreshInterval, options.refreshWhen])
+
+  const previousRef = useRef<{ readonly identity: string; readonly data: Output } | undefined>(
+    undefined,
+  )
+  const previous =
+    options.keepPrevious && previousRef.current?.identity !== identity
+      ? previousRef.current
+      : undefined
+  useEffect(() => {
+    if (current.data !== undefined) {
+      previousRef.current = Object.freeze({ identity, data: current.data })
+    }
+  }, [identity, current.data])
+
+  return useMemo(
+    () =>
+      Object.freeze({
+        state: current.state,
+        data: current.data,
+        error: current.error,
+        ...(previous === undefined ? {} : { previous }),
+        transitioning: current.state === 'loading' || current.state === 'refreshing',
+        live: false as const,
+        sequence: 0 as const,
+        refresh: observer?.refresh ?? (() => Promise.resolve()),
+        more: Object.freeze({ has: false, pending: false, load: () => Promise.resolve() }),
+      }),
+    [current, previous, observer],
+  )
+}
+
+function dedupeShapes(input: readonly TouchedShape[]): readonly TouchedShape[] {
+  const seen = new Set<string>()
+  return Object.freeze(
+    input.filter(({ ast, options }) => {
+      const key = `${JSON.stringify(ast)}\u0000${JSON.stringify(options.page)}`
+      if (seen.has(key)) return false
+      seen.add(key)
+      return true
+    }),
+  )
+}
+
+function combine(snapshots: readonly StoreSnapshot[]): GraphResourceState {
+  if (snapshots.some((snapshot) => snapshot.state === 'cold')) return 'loading'
+  for (const state of ['failed', 'loading', 'refreshing', 'optimistic', 'stale'] as const) {
+    if (snapshots.some((snapshot) => snapshot.state === state)) return state
+  }
+  return 'ready'
+}
+
+function stableIdentity(value: unknown): string {
+  const seen = new WeakSet<object>()
+  const encode = (input: unknown): unknown => {
+    if (input === null) return ['null']
+    if (typeof input !== 'object') {
+      if (typeof input === 'function' || typeof input === 'symbol' || typeof input === 'bigint') {
+        throw new TypeError('Query input must be portable and serializable.')
+      }
+      if (input === undefined) return ['undefined']
+      if (typeof input === 'number' && !Number.isFinite(input)) {
+        throw new TypeError('Query input numbers must be finite.')
+      }
+      return [typeof input, input]
+    }
+    if (seen.has(input)) throw new TypeError('Query input cannot contain cycles.')
+    seen.add(input)
+    if (Array.isArray(input)) return ['array', input.map(encode)]
+    return [
+      'object',
+      Object.fromEntries(
+        Object.keys(input as Record<string, unknown>)
+          .sort()
+          .map((key) => [key, encode((input as Record<string, unknown>)[key])]),
+      ),
+    ]
+  }
+  return JSON.stringify(encode(value))
+}