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

package/src/schema/binding.ts

@@ -1,146 +0,0 @@
-/**
- * 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 raw node 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.js'
-
-import { tagSchema } from './tag.js'
-import { recordNode, writableFor } from './write.js'
-
-/** One tagged binding per (kernel, schema) — shared across the whole tree. */
-const bindingCache = new WeakMap<object, WeakMap<Schema, unknown>>()
-
-/**
- * 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)
-  }
-  const cached = bySchema.get(schema)
-  if (cached !== undefined) return cached as SchemaBoundView<S, FnMap>
-
-  const { writable, nodeIndex } = writableFor(kernel, memory)
-  const binding = tagBinding(createSchemaBoundView(writable, schema), schema, nodeIndex)
-  bySchema.set(schema, binding)
-  return binding
-}
-
-/**
- * Wrap a binding so `bind`/`bindAny`/`as` outputs carry a schema tag, and every
- * bound wire node is recorded with its class and path (the write cap's index); the
- * class handles and every other member pass straight through.
- */
-function tagBinding<S extends Schema>(
-  binding: SchemaBoundView<S, FnMap>,
-  schema: S,
-  nodeIndex: Map<string, Node>,
-): SchemaBoundView<S, FnMap> {
-  let taggedClasses: unknown
-  const handler: ProxyHandler<SchemaBoundView<S, FnMap>> = {
-    get: (target, prop, receiver) => {
-      const value = Reflect.get(target, prop, receiver) as unknown
-      if (prop === 'node' || prop === 'create') {
-        return async (...args: unknown[]) =>
-          tagBoundResult(
-            await (value as (...callArgs: unknown[]) => Promise<unknown>)(...args),
-            schema,
-            nodeIndex,
-          )
-      }
-      if (prop === 'bind') {
-        return (type: string, node: Node, opts?: unknown) => {
-          recordNode(nodeIndex, node)
-          return tagSchema(
-            (value as (t: string, n: Node, o?: unknown) => unknown)(type, node, opts),
-            schema,
-          )
-        }
-      }
-      if (prop === 'bindAny') {
-        return (node: Node) => {
-          recordNode(nodeIndex, node)
-          return tagSchema((value as (n: Node) => unknown)(node), schema)
-        }
-      }
-      if (prop === 'classes') {
-        taggedClasses ??= tagClassHandles(value as object, schema, nodeIndex)
-        return taggedClasses
-      }
-      if (prop === 'as') {
-        const as = value as SchemaBoundView<S, FnMap>['as']
-        return (credential: Parameters<typeof as>[0]) =>
-          tagBinding(as(credential), schema, nodeIndex)
-      }
-      if (prop === 'withSchema') {
-        return <S2 extends Schema>(next: S2) =>
-          tagBinding((value as SchemaBoundView<S, FnMap>['withSchema'])(next), next, nodeIndex)
-      }
-      return value
-    },
-  }
-  return new Proxy(binding, handler)
-}
-
-function tagClassHandles<S extends Schema>(
-  classes: object,
-  schema: S,
-  nodeIndex: Map<string, Node>,
-): object {
-  const handles = new Map<PropertyKey, unknown>()
-  return new Proxy(classes, {
-    get(target, prop, receiver) {
-      const cached = handles.get(prop)
-      if (cached !== undefined) return cached
-      const handle = Reflect.get(target, prop, receiver) as unknown
-      if (typeof handle !== 'function') return handle
-      const tagged = new Proxy(handle, {
-        get(handleTarget, member, handleReceiver) {
-          const value = Reflect.get(handleTarget, member, handleReceiver) as unknown
-          if (member !== 'get') return value
-          return async (...args: unknown[]) =>
-            tagBoundResult(
-              await (value as (...callArgs: unknown[]) => Promise<unknown>)(...args),
-              schema,
-              nodeIndex,
-            )
-        },
-      })
-      handles.set(prop, tagged)
-      return tagged
-    },
-  })
-}
-
-function tagBoundResult<R>(result: R, schema: Schema, nodeIndex: Map<string, Node>): R {
-  const nodes = Array.isArray(result) ? result : [result]
-  for (const node of nodes) {
-    if (node !== null && typeof node === 'object') {
-      recordNode(nodeIndex, node)
-      tagSchema(node, schema)
-    }
-  }
-  return result
-}
-
-export type { NodeRefInput }

package/src/schema/function.hook.ts

@@ -1,68 +0,0 @@
-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.js'
-import type { FunctionNames, FunctionParams, FunctionResult } from './types.js'
-
-import { useAction } from '../graph/action.js'
-import { useDomain } from './domain.hook.js'
-
-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/method.hook.ts

@@ -1,103 +0,0 @@
-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.js'
-import type { AutoMethodAction, BoundMethodAction, MethodNames } from './types.js'
-
-import { useAction } from '../graph/action.js'
-import { useDomain } from './domain.hook.js'
-
-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 DynamicBinding
-  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)
-}
-
-type DynamicClassHandle = Dispatch & ((ref: NodeRefInput) => Dispatch)
-type DynamicBinding = { classes: Record<string, DynamicClassHandle> }
-
-function staticCall(
-  binding: DynamicBinding,
-  type: string,
-  method: string,
-  params: unknown,
-): Promise<unknown> {
-  return binding.classes[type]![method]!(params)
-}
-
-function instance(
-  binding: DynamicBinding,
-  type: string,
-  ref: NodeRefInput,
-  method: string,
-  params: unknown,
-): Promise<unknown> {
-  return binding.classes[type]!(ref)[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

@@ -1,19 +0,0 @@
-/**
- * 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)
-}

package/src/schema/types.ts

@@ -1,150 +0,0 @@
-/**
- * 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.js'
-import type { ReadState, Windowed } from '../graph/memory/read/envelope.js'
-
-// ── 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

@@ -1,96 +0,0 @@
-/**
- * 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 { Node } from '@astrale-os/kernel-core'
-
-import type { SessionView } from '../auth/act-as.context.js'
-
-/**
- * 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 nodeIndex: Map<string, Node>
-}
-const writableCache = new WeakMap<object, WritableKernel>()
-
-export function writableFor(kernel: SessionView, memory: GraphMemory): WritableKernel {
-  let entry = writableCache.get(kernel)
-  if (entry === undefined) {
-    const nodeIndex = new Map<string, Node>()
-    entry = { writable: withMemoryWrites(kernel, memory, nodeIndex), nodeIndex }
-    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 needs the node's class and tree path — so an `@<id>` ref is translated
- * through `nodeIndex` (populated at bind time). A ref that is NOT indexed (a node
- * that was never bound) 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,
-  nodeIndex: Map<string, Node>,
-): 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 extendCapabilities(kernel, {
-    updateNode: (cls: PathLike, ref: PathLike, props: Properties): Promise<void> => {
-      const node = indexedNode(nodeIndex, ref)
-      return node !== null ? memory.update(node, 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),
-  })
-}
-
-/** Overlay memory writes without materializing a possibly virtual session surface. */
-function extendCapabilities<Base extends object, Extension extends object>(
-  base: Base,
-  extension: Extension,
-): Base & Extension {
-  return new Proxy(base as Base & Extension, {
-    get(target, prop, receiver) {
-      return Object.prototype.hasOwnProperty.call(extension, prop)
-        ? Reflect.get(extension, prop, extension)
-        : Reflect.get(target, prop, receiver)
-    },
-  })
-}
-
-/** The tree path an `@<id>` write ref maps to, via the bind-time index; else null. */
-function indexedNode(nodeIndex: Map<string, Node>, ref: PathLike): Node | null {
-  if (typeof ref !== 'string' || !ref.startsWith('@')) return null
-  return nodeIndex.get(ref.slice(1)) ?? null
-}
-
-/** Record a bound node's raw value so the write cap retains its class and tree path. */
-export function recordNode(nodeIndex: Map<string, Node>, node: unknown): void {
-  const wrapped = node as { raw?: unknown } | null
-  const candidate = wrapped?.raw !== null && typeof wrapped?.raw === 'object' ? wrapped.raw : node
-  const n = candidate as { id?: unknown; path?: { raw?: unknown } } | null
-  if (n !== null && typeof n.id === 'string' && typeof n.path?.raw === 'string') {
-    nodeIndex.set(n.id, candidate as Node)
-  }
-}