@astrale-os/shell-react 0.1.0

package/src/schema/bind-read.ts

@@ -0,0 +1,319 @@
+import type { GatherBuilder, OrderInput, QuerySource } from '@astrale-os/kernel-client/graph'
+import type {
+  LiveResult,
+  ReadOptions as StoreReadOptions,
+  ShapeInput,
+} from '@astrale-os/kernel-client/store'
+import type { Node } from '@astrale-os/kernel-core'
+import type { Schema } from '@astrale-os/kernel-dsl'
+
+import {
+  BindTypeMismatchError,
+  normalizeRef,
+  type AnyBoundNode,
+  type BoundNode,
+  type DefOf,
+  type NodeRefInput,
+  type SchemaBoundView,
+  type TypeNames,
+} from '@astrale-os/kernel-client'
+import { shapeInputToAST, stableStringify, stripCursors } from '@astrale-os/kernel-client/store'
+import { compileDomain } from '@astrale-os/kernel-core/domain'
+/**
+ * Binder-over-memory composition (API §6, §1.7) — consumed by the `graph/query/`
+ * overloads. Binds wire `Node`s from the shared memory to stable `BoundNode`s
+ * (an unchanged wire node re-binds to the SAME instance), and composes those
+ * binders with a `useSyncExternalStore` read substrate (`useShape`) into the typed
+ * `useNode`/`useChildren` reads. A typed read and its untyped twin ride the SAME
+ * memory shape, so they are one cache entry, one liveness, one overlay.
+ */
+import { useCallback, useMemo, useRef, useSyncExternalStore } from 'react'
+
+import type { ReadState, ReadOptions } from '../graph/memory/read/envelope'
+import type { TypedChildrenResult, TypedNodeResult } from './types'
+
+import { useSessionKernel } from '../auth/session-kernel'
+import { idleReadState, isIdleInput } from '../graph/memory/read/idle'
+import { useMemory } from '../graph/memory/scope'
+import { bindingFor } from './binding'
+import { schemaOf, tagSchema } from './tag'
+
+// ── binder hooks ────────────────────────────────────────────────────────────────
+
+interface OneCache<S extends Schema> {
+  wire: Node | null
+  binding: SchemaBoundView<S>
+  type: string
+  bound: BoundNode<unknown, S> | null
+}
+
+/** Bind one wire node as `type`; stable while the wire node, binding, and type hold. */
+export function useBoundNode<S extends Schema, T extends TypeNames<S>>(
+  binding: SchemaBoundView<S>,
+  type: T,
+  wire: Node | null | undefined,
+): BoundNode<DefOf<S, T>, S> | null {
+  const ref = useRef<OneCache<S> | null>(null)
+  const node = wire ?? null
+  let entry = ref.current
+  if (entry === null || entry.wire !== node || entry.binding !== binding || entry.type !== type) {
+    entry = {
+      wire: node,
+      binding,
+      type,
+      bound: node === null ? null : (binding.bind(type, node) as BoundNode<unknown, S>),
+    }
+    ref.current = entry
+  }
+  return entry.bound as BoundNode<DefOf<S, T>, S> | null
+}
+
+interface ManyCache<S extends Schema> {
+  binding: SchemaBoundView<S>
+  type: string
+  perNode: WeakMap<Node, BoundNode<unknown, S>>
+  last: readonly BoundNode<unknown, S>[]
+}
+
+/**
+ * Bind many wire nodes as `type`; per-node identity + a stable array on no
+ * change. `skipMismatch` drops nodes whose class is not `type` (a mixed-class
+ * child set) instead of throwing.
+ */
+export function useBoundNodes<S extends Schema, T extends TypeNames<S>>(
+  binding: SchemaBoundView<S>,
+  type: T,
+  wires: readonly Node[],
+  skipMismatch = false,
+): readonly BoundNode<DefOf<S, T>, S>[] {
+  const ref = useRef<ManyCache<S> | null>(null)
+  if (ref.current === null || ref.current.binding !== binding || ref.current.type !== type) {
+    ref.current = { binding, type, perNode: new WeakMap(), last: [] }
+  }
+  const cache = ref.current
+  const next: BoundNode<unknown, S>[] = []
+  for (const w of wires) {
+    let b = cache.perNode.get(w)
+    if (b === undefined) {
+      try {
+        b = binding.bind(type, w) as BoundNode<unknown, S>
+      } catch (error) {
+        if (skipMismatch && error instanceof BindTypeMismatchError) continue
+        throw error
+      }
+      cache.perNode.set(w, b)
+    }
+    next.push(b)
+  }
+  if (sameArray(cache.last, next)) return cache.last as readonly BoundNode<DefOf<S, T>, S>[]
+  cache.last = next
+  return next as readonly BoundNode<DefOf<S, T>, S>[]
+}
+
+interface EndpointCache<S extends Schema> {
+  binding: SchemaBoundView<S>
+  perNode: WeakMap<Node, AnyBoundNode<S>>
+  last: readonly AnyBoundNode<S>[]
+}
+
+/** Bind many wire nodes classlessly (traversal endpoints); per-node + stable array. */
+export function useBoundEndpoints<S extends Schema>(
+  binding: SchemaBoundView<S>,
+  wires: readonly Node[],
+): readonly AnyBoundNode<S>[] {
+  const ref = useRef<EndpointCache<S> | null>(null)
+  if (ref.current === null || ref.current.binding !== binding) {
+    ref.current = { binding, perNode: new WeakMap(), last: [] }
+  }
+  const cache = ref.current
+  const next = wires.map((w) => {
+    let b = cache.perNode.get(w)
+    if (b === undefined) {
+      b = binding.bindAny(w)
+      cache.perNode.set(w, b)
+    }
+    return b
+  })
+  if (sameArray(cache.last, next)) return cache.last
+  cache.last = next
+  return next
+}
+
+function sameArray<A>(a: readonly A[], b: readonly A[]): boolean {
+  return a.length === b.length && a.every((x, i) => x === b[i])
+}
+
+// ── read substrate ────────────────────────────────────────────────────────────
+
+/** Base read options plus the window growth mode (a `useChildren`-specific extra). */
+export type ShapeOptions = ReadOptions & { window?: 'append' | 'paged' }
+
+/** Store-facing options — render-time concerns (`suspend`/`keepPrevious`) stay here. */
+function toStoreOptions(opts?: ShapeOptions): 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
+  if (opts.with !== undefined) out.with = opts.with as unknown as StoreReadOptions['with']
+  return out
+}
+
+/** A stable string identity for a (shape, options) pair — the subscription key. */
+function keyOf(shape: ShapeInput, opts?: ShapeOptions): string {
+  const ast = stripCursors(shapeInputToAST(shape))
+  return `${stableStringify(ast)}|${opts?.live === false ? '0' : '1'}|${opts?.window ?? ''}|${opts?.with ?? ''}`
+}
+
+/**
+ * Subscribe to a memory shape. `null` shape → idle (`null`, no I/O). A cold
+ * shape suspends unless `suspend: false`. The returned `LiveResult` is the
+ * unified read envelope — callers project `node`/`children`/`nodes`.
+ */
+export function useShape(
+  shape: ShapeInput | null | undefined,
+  opts?: ShapeOptions,
+): LiveResult | null {
+  const memory = useMemory()
+  const storeOpts = toStoreOptions(opts)
+  const key = isIdleInput(shape) ? null : keyOf(shape, opts)
+
+  const subscribe = useCallback(
+    (onChange: () => void): (() => void) => {
+      if (isIdleInput(shape)) return () => {}
+      return memory.subscribe(shape, onChange, storeOpts)
+    },
+    // The shape's canonical identity is `key`; the captured `shape` is equivalent.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [memory, key],
+  )
+  const getSnapshot = useCallback(
+    (): LiveResult | null => (isIdleInput(shape) ? null : memory.getSnapshot(shape, storeOpts)),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [memory, key],
+  )
+
+  const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+
+  if (!isIdleInput(shape) && opts?.suspend !== false && memory.peek(shape, storeOpts) === null) {
+    // Cold FAILURE (§1.4): a rejected fetch with no data throws to the boundary;
+    // re-throwing the promise would re-arm a fetch each retry (infinite loop).
+    if (snapshot !== null && snapshot.error !== undefined) throw snapshot.error
+    throw memory.promise(shape, storeOpts)
+  }
+  return snapshot
+}
+
+// ── typed reads (schema-first useNode, BoundNode-first useChildren) ──────────────
+
+export function useNode<S extends Schema, T extends TypeNames<S>>(
+  schema: S,
+  type: T,
+  ref: NodeRefInput | null | undefined,
+  opts?: ReadOptions,
+): TypedNodeResult<S, T> {
+  const binding = bindingFor(useSessionKernel(), schema, useMemory())
+  const shape = isIdleInput(ref) ? null : normalizeRef(ref)
+  const snap = useShape(shape, opts)
+  const wire = snap?.node ?? null
+  const bound = useBoundNode(binding, type, wire)
+  if (bound !== null) tagSchema(bound, schema)
+  const live = snap === null ? idleReadState() : readStateOf(snap)
+  return useMemo(
+    () => ({ ...live, node: bound }),
+    [bound, live.pending, live.error, live.live, live.seq],
+  )
+}
+
+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> {
+  const kernel = useSessionKernel()
+  const memory = useMemory()
+  const schema = isIdleInput(parent) ? null : requireSchema(parent)
+  const binding = schema === null ? null : bindingFor(kernel, schema, memory)
+
+  const parentRef = isIdleInput(parent) ? null : `@${parent.id}`
+  const classRef = schema === null ? undefined : classRefFor(schema, opts.type)
+  const shape =
+    parentRef === null
+      ? null
+      : (q: QuerySource): GatherBuilder =>
+          q.from(parentRef).children({
+            ...(classRef !== undefined ? { classes: [classRef] } : {}),
+            ...(opts.order !== undefined ? { order: opts.order } : {}),
+            ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
+          })
+
+  const snap = useShape(shape, opts)
+  const wires = snap?.children ?? EMPTY
+  const bound = useBoundNodes(
+    (binding ?? UNBOUND) as unknown as SchemaBoundView<S>,
+    opts.type,
+    binding === null ? EMPTY : wires,
+    true,
+  )
+  if (schema !== null) for (const b of bound) tagSchema(b, schema)
+
+  const live = snap === null ? idleReadState() : readStateOf(snap)
+  const more = snap?.more ?? IDLE_MORE
+  return useMemo(
+    () => ({ ...live, more, children: bound }),
+    [bound, more, live.pending, live.error, live.live, live.seq],
+  )
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+const EMPTY: readonly never[] = Object.freeze([])
+const IDLE_MORE = { has: false, load: () => Promise.resolve(), pending: false } as const
+const UNBOUND = {} as never
+
+function readStateOf(snap: {
+  pending: boolean
+  error: unknown
+  live: boolean
+  seq: number
+  refetch(): Promise<void>
+}): ReadState {
+  return {
+    pending: snap.pending,
+    error: snap.error,
+    live: snap.live,
+    seq: snap.seq,
+    refetch: snap.refetch,
+  }
+}
+
+/** Recover the schema a BoundNode was bound under; a clear error if it is untagged. */
+export function requireSchema(node: object): Schema {
+  const schema = schemaOf(node)
+  if (schema === undefined) {
+    throw new Error(
+      'useChildren: the parent was not produced by a shell-react typed binding — ' +
+        'obtain it from useNode / useDomain(schema).bind() so its schema is known.',
+    )
+  }
+  return schema
+}
+
+const compiledCache = new WeakMap<Schema, ReturnType<typeof compileDomain>>()
+
+/** The descent class ref for a type name (class or interface), or undefined. */
+function classRefFor(schema: Schema, type: string): string | undefined {
+  let compiled = compiledCache.get(schema)
+  if (compiled === undefined) {
+    compiled = compileDomain(schema)
+    compiledCache.set(schema, compiled)
+  }
+  const accessor = compiled.$ as unknown as {
+    c(name: string): { path?: { class?: { raw: string } } } | undefined
+    i(name: string): { path?: { class?: { raw: string } } } | undefined
+  }
+  return accessor.c(type)?.path?.class?.raw ?? accessor.i(type)?.path?.class?.raw
+}

package/src/schema/binding.ts

@@ -0,0 +1,91 @@
+/**
+ * bindingFor(kernel, schema) — memoized `withSchema` handles (API §6). The
+ * `withSchema` handle is a *binding*, never a "view". Memoizes
+ * `createSchemaBoundView` per (session, schema) so a binding — and the BoundNodes
+ * it mints — keep referential identity across renders. Each binding is wrapped so
+ * every BoundNode it hands back is schema-tagged (the traversal hooks read it
+ * back) and its `id → tree path` recorded (the write capability's index).
+ */
+import type { FnMap, NodeRefInput, SchemaBoundView } from '@astrale-os/kernel-client'
+import type { GraphMemory } from '@astrale-os/kernel-client/store'
+import type { Node } from '@astrale-os/kernel-core'
+import type { Schema } from '@astrale-os/kernel-dsl'
+
+import { createSchemaBoundView } from '@astrale-os/kernel-client'
+
+import type { SessionView } from '../auth/act-as.context'
+
+import { tagSchema } from './tag'
+import { recordPath, writableFor } from './write'
+
+type AnyBinding = SchemaBoundView<Schema, FnMap>
+
+/** One tagged binding per (kernel, schema) — shared across the whole tree. */
+const bindingCache = new WeakMap<object, WeakMap<Schema, AnyBinding>>()
+
+/**
+ * Resolve (and memoize) the tagged schema-bound handle for `schema` on `kernel`.
+ * `kernel` is the EFFECTIVE dispatch kernel (root or `<ActAs>` — §4); the cache is
+ * keyed on it, so an acted-as subtree gets its own memoized bindings for free.
+ * `memory` is the SAME scoped memory the read hooks use (1:1 with `kernel`).
+ */
+export function bindingFor<S extends Schema>(
+  kernel: SessionView,
+  schema: S,
+  memory: GraphMemory,
+): SchemaBoundView<S, FnMap> {
+  let bySchema = bindingCache.get(kernel)
+  if (bySchema === undefined) {
+    bySchema = new WeakMap()
+    bindingCache.set(kernel, bySchema)
+  }
+  let binding = bySchema.get(schema)
+  if (binding === undefined) {
+    const { writable, pathIndex } = writableFor(kernel, memory)
+    binding = tagBinding(createSchemaBoundView(writable, schema) as AnyBinding, schema, pathIndex)
+    bySchema.set(schema, binding)
+  }
+  return binding as SchemaBoundView<S, FnMap>
+}
+
+/**
+ * Wrap a binding so `bind`/`bindAny`/`as` outputs carry a schema tag, and every
+ * bound wire node's `id → tree path` is recorded (the write cap's index); the
+ * bare-call dispatch and every other member pass straight through.
+ */
+function tagBinding(
+  binding: AnyBinding,
+  schema: Schema,
+  pathIndex: Map<string, string>,
+): AnyBinding {
+  const handler: ProxyHandler<AnyBinding> = {
+    apply: (target, _thisArg, args) =>
+      (target as unknown as (...a: unknown[]) => unknown)(...(args as unknown[])),
+    get: (target, prop, receiver) => {
+      const value = Reflect.get(target, prop, receiver) as unknown
+      if (prop === 'bind') {
+        return (type: string, node: Node, opts?: unknown) => {
+          recordPath(pathIndex, node)
+          return tagSchema(
+            (value as (t: string, n: Node, o?: unknown) => unknown)(type, node, opts),
+            schema,
+          )
+        }
+      }
+      if (prop === 'bindAny') {
+        return (node: Node) => {
+          recordPath(pathIndex, node)
+          return tagSchema((value as (n: Node) => unknown)(node), schema)
+        }
+      }
+      if (prop === 'as') {
+        return (credential: unknown) =>
+          tagBinding((value as (c: unknown) => AnyBinding)(credential), schema, pathIndex)
+      }
+      return value
+    },
+  }
+  return new Proxy(binding, handler)
+}
+
+export type { NodeRefInput }

package/src/schema/domain.hook.ts

@@ -0,0 +1,16 @@
+/**
+ * useDomain(schema) (API §6) — the typed domain binding, `kernel.withSchema(schema)`,
+ * memoized per (effective session, schema). The BoundNodes it mints ride the
+ * shared scoped memory, so typed writes are optimistic and revalidate (§6).
+ */
+import type { FnMap, SchemaBoundView } from '@astrale-os/kernel-client'
+import type { Schema } from '@astrale-os/kernel-dsl'
+
+import { useSessionKernel } from '../auth/session-kernel'
+import { useMemory } from '../graph/memory/scope'
+import { bindingFor } from './binding'
+
+/** The typed domain binding — `kernel.withSchema(schema)`, memoized per (session, schema). */
+export function useDomain<S extends Schema>(schema: S): SchemaBoundView<S, FnMap> {
+  return bindingFor(useSessionKernel(), schema, useMemory())
+}

package/src/schema/function.hook.ts

@@ -0,0 +1,68 @@
+import type { Schema } from '@astrale-os/kernel-dsl'
+
+import { compileDomain } from '@astrale-os/kernel-core/domain'
+/**
+ * `useFunction` (API §6) — `useMethod`'s sibling for a domain's top-level
+ * standalone functions (the `functions` map of `defineSchema`). Dispatched by the
+ * compiled FunctionPath from the compiled-domain accessor, never string-built.
+ * Dispatch is correct but not compile-time typed (see the note in schema/types.ts).
+ */
+import { useCallback, useMemo, useRef } from 'react'
+
+import type { Action } from '../graph/action'
+import type { FunctionNames, FunctionParams, FunctionResult } from './types'
+
+import { useAction } from '../graph/action'
+import { useDomain } from './domain.hook'
+
+export interface FunctionOptions {
+  /** Extra failure channel; the action still rejects and records `.error`. */
+  onError?: (error: unknown) => void
+}
+
+const compiledCache = new WeakMap<Schema, ReturnType<typeof compileDomain>>()
+
+/** The dispatch path for a standalone function, from the compiled accessor. */
+function functionPathOf(schema: Schema, name: string): string {
+  let compiled = compiledCache.get(schema)
+  if (compiled === undefined) {
+    compiled = compileDomain(schema)
+    compiledCache.set(schema, compiled)
+  }
+  const entry = compiled.$.f(name)
+  if (entry === undefined) {
+    throw new Error(`Unknown function '${name}' in schema '${schema.domain}'`)
+  }
+  return entry.path.domain.raw
+}
+
+type RawCall = (method: string, params: unknown, opts?: unknown) => Promise<unknown>
+
+export function useFunction<S extends Schema, F extends FunctionNames<S>>(
+  schema: S,
+  fn: F,
+  opts?: FunctionOptions,
+): Action<[FunctionParams<S, F>], FunctionResult<S, F>> {
+  const binding = useDomain(schema)
+  const path = useMemo(() => functionPathOf(schema, String(fn)), [schema, fn])
+
+  const onErrorRef = useRef(opts?.onError)
+  onErrorRef.current = opts?.onError
+
+  const call = useCallback(
+    async (params: FunctionParams<S, F>): Promise<FunctionResult<S, F>> => {
+      try {
+        return (await (binding.raw.call as unknown as RawCall)(path, params)) as FunctionResult<
+          S,
+          F
+        >
+      } catch (error) {
+        onErrorRef.current?.(error)
+        throw error
+      }
+    },
+    [binding, path],
+  )
+
+  return useAction(call)
+}

package/src/schema/index.ts

@@ -0,0 +1,25 @@
+// schema — the typing substrate (API §6). Typed kernel/domain bindings, typed
+// reads, method/function dispatch. See SHELL_REACT_API.md.
+export { useKernel } from './kernel.hook'
+export { useDomain } from './domain.hook'
+export { useNode, useChildren, useBoundNode, useBoundNodes, useBoundEndpoints } from './bind-read'
+export { useOut, useIn } from '../graph/query/neighbors.hook'
+export { useMethod } from './method.hook'
+export type { MethodOptions } from './method.hook'
+export { useFunction } from './function.hook'
+export type { FunctionOptions } from './function.hook'
+export type {
+  AutoMethodAction,
+  BoundMethodAction,
+  EndpointResult,
+  FunctionNames,
+  FunctionParams,
+  FunctionResult,
+  MethodIsStatic,
+  MethodNames,
+  MethodParams,
+  MethodResult,
+  TargetedMethodAction,
+  TypedChildrenResult,
+  TypedNodeResult,
+} from './types'

package/src/schema/kernel.hook.ts

@@ -0,0 +1,17 @@
+/**
+ * useKernel (API §6) — the typed kernel, `kernel.withSchema(KernelSchema)`,
+ * memoized per (effective) session. The kernel's own schema baked in; dispatch
+ * and reads run as the subtree's principal over its scoped memory (§4).
+ */
+import type { FnMap, SchemaBoundView } from '@astrale-os/kernel-client'
+
+import { KernelSchema } from '@astrale-os/kernel-core'
+
+import { useSessionKernel } from '../auth/session-kernel'
+import { useMemory } from '../graph/memory/scope'
+import { bindingFor } from './binding'
+
+/** The typed kernel — `kernel.withSchema(KernelSchema)`, memoized (§4-scoped). */
+export function useKernel(): SchemaBoundView<typeof KernelSchema, FnMap> {
+  return bindingFor(useSessionKernel(), KernelSchema, useMemory())
+}

package/src/schema/method.hook.ts

@@ -0,0 +1,103 @@
+import type { NodeRefInput, TypeNames } from '@astrale-os/kernel-client'
+import type { Schema } from '@astrale-os/kernel-dsl'
+
+import { resolveAllMethods } from '@astrale-os/kernel-dsl'
+/**
+ * `useMethod` (API §6) — typed method dispatch with call state. Three forms,
+ * selected by the method's static-ness and whether `on` is given:
+ *   static            → action(params)
+ *   instance + on     → action(params)   (bound to that node)
+ *   instance, no on   → action(ref, params)
+ * Params/result come from the method's Zod contracts.
+ */
+import { useCallback, useMemo, useRef } from 'react'
+
+import type { Action } from '../graph/action'
+import type { AutoMethodAction, BoundMethodAction, MethodNames } from './types'
+
+import { useAction } from '../graph/action'
+import { useDomain } from './domain.hook'
+
+export interface MethodOptions {
+  /** Bind the action to this node — dispatch as `action(params)`. */
+  on?: NodeRefInput
+  /** Extra failure channel; the action still rejects and records `.error`. */
+  onError?: (error: unknown) => void
+}
+
+type Dispatch = Record<string, (params: unknown) => Promise<unknown>>
+
+export function useMethod<S extends Schema, T extends TypeNames<S>, M extends MethodNames<S, T>>(
+  schema: S,
+  type: T,
+  method: M,
+  opts: MethodOptions & { on: NodeRefInput },
+): BoundMethodAction<S, T, M>
+export function useMethod<S extends Schema, T extends TypeNames<S>, M extends MethodNames<S, T>>(
+  schema: S,
+  type: T,
+  method: M,
+  opts?: MethodOptions,
+): AutoMethodAction<S, T, M>
+export function useMethod<S extends Schema, T extends TypeNames<S>, M extends MethodNames<S, T>>(
+  schema: S,
+  type: T,
+  method: M,
+  opts?: MethodOptions,
+): Action<never[], unknown> {
+  const binding = useDomain(schema) as unknown as Dispatcher
+  const on = opts?.on
+  const isStatic = useMemo(() => detectStatic(schema, type, String(method)), [schema, type, method])
+
+  const onErrorRef = useRef(opts?.onError)
+  onErrorRef.current = opts?.onError
+
+  const call = useCallback(
+    async (...args: unknown[]): Promise<unknown> => {
+      const name = String(method)
+      try {
+        if (on !== undefined) return await instance(binding, type as string, on, name, args[0])
+        if (isStatic) return await staticCall(binding, type as string, name, args[0])
+        return await instance(binding, type as string, args[0] as NodeRefInput, name, args[1])
+      } catch (error) {
+        onErrorRef.current?.(error)
+        throw error
+      }
+    },
+    [binding, type, method, on, isStatic],
+  )
+
+  return useAction(call)
+}
+
+/** The bare-call dispatch signature of a `SchemaBoundView`, address-only. */
+type Dispatcher = (type: string, ref?: NodeRefInput) => unknown
+
+function staticCall(
+  binding: Dispatcher,
+  type: string,
+  method: string,
+  params: unknown,
+): Promise<unknown> {
+  return (binding(type) as unknown as Dispatch)[method]!(params)
+}
+
+function instance(
+  binding: Dispatcher,
+  type: string,
+  ref: NodeRefInput,
+  method: string,
+  params: unknown,
+): Promise<unknown> {
+  return (binding(type, ref) as unknown as Dispatch)[method]!(params)
+}
+
+/** Read the method's `static` flag from the schema (own + inherited). */
+function detectStatic(schema: Schema, type: string, method: string): boolean {
+  const def =
+    (schema.classes as Record<string, unknown>)[type] ??
+    (schema.interfaces as Record<string, unknown>)[type]
+  if (def === undefined) return false
+  const methods = resolveAllMethods(def as Parameters<typeof resolveAllMethods>[0])
+  return methods[method]?.config.static === true
+}

package/src/schema/tag.ts

@@ -0,0 +1,19 @@
+/**
+ * Schema-tagging of raw nodes (API §6, the bindAny bridge). A module-level tag
+ * records the schema each BoundNode was bound under, so the traversal hooks can
+ * recover it from the node alone (`useChildren`/`useOut`/`useIn` re-bind endpoints).
+ */
+import type { Schema } from '@astrale-os/kernel-dsl'
+
+const schemaOfNode = new WeakMap<object, Schema>()
+
+/** Record the schema a BoundNode was bound under; returns the node unchanged. */
+export function tagSchema<N>(node: N, schema: Schema): N {
+  if (node !== null && typeof node === 'object') schemaOfNode.set(node, schema)
+  return node
+}
+
+/** The schema a BoundNode was bound under, if it came from a shell-react binding. */
+export function schemaOf(node: object): Schema | undefined {
+  return schemaOfNode.get(node)
+}