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

package/src/schema/relation.hook.ts

@@ -0,0 +1,253 @@
+import type { StoreQueryResponse } from '@astrale-os/kernel-client/store'
+import type {
+  BoundInstanceOf,
+  Definition,
+  EdgeEndpointAcceptedDefinitionsOf,
+} from '@astrale-os/sdk/domain'
+import type { LinkedCountOf } from '@astrale-os/sdk/query'
+
+import { NodeId } from '@astrale-os/sdk/graph/node'
+import { Path } from '@astrale-os/sdk/graph/path'
+import { Query } from '@astrale-os/sdk/query'
+import { useCallback, useMemo } from 'react'
+
+import type { GraphResource } from '../graph/resource.js'
+
+import { useStoreResource } from '../graph/resource.js'
+import { bindingFor } from './domain.hook.js'
+
+type DefinitionCoordinates = Pick<
+  Definition<'class' | 'interface'>,
+  'kind' | 'origin' | 'name' | 'key' | 'schemaRef' | 'definition'
+>
+type NodeDefinition = DefinitionCoordinates & { readonly family: 'node' }
+type EdgeDefinition = DefinitionCoordinates & { readonly family: 'edge' }
+type EndpointRole = 'source' | 'target'
+type RelationCardinality = '1' | '0..1' | '0..*' | '1..*'
+type RuntimeEndpoint = {
+  readonly accepts: readonly {
+    readonly origin: string
+    readonly kind: 'class' | 'interface'
+    readonly name: string
+  }[]
+  readonly outgoing?: RelationCardinality
+  readonly incoming?: RelationCardinality
+}
+type Opposite<Role extends EndpointRole> = Role extends 'source' ? 'target' : 'source'
+type Accepted<
+  Definition extends EdgeDefinition,
+  Role extends EndpointRole,
+> = EdgeEndpointAcceptedDefinitionsOf<Definition, Opposite<Role>>
+type StartingDefinition<
+  Relation extends EdgeDefinition,
+  Role extends EndpointRole,
+> = EdgeEndpointAcceptedDefinitionsOf<Relation, Role> & NodeDefinition
+type RelatedDefinition<Relation extends EdgeDefinition, Role extends EndpointRole> = Accepted<
+  Relation,
+  Role
+> &
+  NodeDefinition
+type EffectiveCardinality<
+  Relation extends EdgeDefinition,
+  Role extends EndpointRole,
+  To extends RelatedDefinition<Relation, Role>,
+> = LinkedCountOf<Relation, Role, To>
+
+export interface RelationUnavailable {
+  readonly kind: 'required-hidden-or-invalid'
+  readonly cardinality: '1' | '1..*'
+}
+
+export class RelationUnavailableError extends Error {
+  readonly code = 'SHELL_REACT_RELATION_UNAVAILABLE' as const
+  constructor(readonly unavailable: RelationUnavailable) {
+    super(
+      `Required relation (${unavailable.cardinality}) is hidden or violates the installed schema.`,
+    )
+    this.name = 'RelationUnavailableError'
+  }
+}
+
+export type RelationResource<T, C extends string> = C extends '1' | '0..1'
+  ? GraphResource<T | null> & {
+      readonly cardinality: C
+      readonly unavailable?: RelationUnavailable
+      require(): T
+    }
+  : GraphResource<readonly T[]> & {
+      readonly cardinality: C
+      readonly unavailable?: RelationUnavailable
+      require(): readonly T[]
+    }
+
+export interface RelationOptions<Role extends EndpointRole, To> {
+  readonly from: Role
+  /** Exact rich opposite-endpoint definition used to admit and brand returned nodes. */
+  readonly to: To
+  readonly page?: { readonly size: number }
+}
+
+/** Traverse one exact rich Edge definition with endpoint and cardinality inference. */
+export function useRelation<
+  Definition extends EdgeDefinition,
+  Role extends EndpointRole,
+  To extends RelatedDefinition<Definition, Role>,
+>(
+  definition: Definition,
+  source: BoundInstanceOf<StartingDefinition<Definition, Role>> | null | undefined,
+  options: RelationOptions<Role, To>,
+): RelationResource<BoundInstanceOf<To>, EffectiveCardinality<Definition, Role, To>> {
+  const binding = bindingFor(definition)
+  if (source !== null && source !== undefined) {
+    admitSource(binding, definition, options.from, source)
+  }
+  admitRelatedDefinition(binding, definition, options.from, options.to)
+  const path = source === null || source === undefined ? null : Path.id(NodeId(source.id))
+  const query = useMemo(() => {
+    if (path === null) return null
+    const root = Query.from({ kind: 'node', paths: [path], binding: 'relation_source' })
+    const admitted = root.filter({ satisfies: source!.$.definition.schemaRef })
+    const expanded = admitted.expand({
+      via: [definition.schemaRef],
+      direction: options.from === 'source' ? 'outgoing' : 'incoming',
+    })
+    return expanded
+      .filter({ satisfies: options.to.schemaRef })
+      .select({ kind: 'graph', binding: expanded.node })
+  }, [definition, options.from, options.to, path?.raw, source])
+  const cardinality: RelationCardinality = effectiveCardinality(
+    binding,
+    definition,
+    options.from,
+    options.to,
+  )
+  const project = useCallback(
+    (response: StoreQueryResponse<NonNullable<typeof query>>) => {
+      const result = response.result
+      if (result.kind !== 'graph' || result.selection.kind !== 'node') {
+        return cardinality === '0..1'
+          ? null
+          : cardinality === '0..*'
+            ? Object.freeze([])
+            : undefined
+      }
+      const byId = new Map(result.graph.nodes.map((node) => [node.id, node]))
+      const values = result.selection.ids.flatMap((id) => {
+        const node = byId.get(id)
+        if (node === undefined) return []
+        const bind = binding.$.bind as unknown as (
+          expected: To,
+          value: typeof node,
+        ) => BoundInstanceOf<To>
+        return [bind(options.to, node)]
+      })
+      if (cardinality === '0..1') return values[0] ?? null
+      if (cardinality === '1') return values[0]
+      if (cardinality === '1..*' && values.length === 0) return undefined
+      return Object.freeze(values)
+    },
+    [binding, cardinality, options.to, query],
+  )
+  const resource = useStoreResource(query, options.page?.size ?? 50, project)
+  const unavailable =
+    (cardinality === '1' &&
+      resource.data === undefined &&
+      resource.state !== 'idle' &&
+      resource.state !== 'loading') ||
+    (cardinality === '1..*' &&
+      resource.data === undefined &&
+      resource.state !== 'idle' &&
+      resource.state !== 'loading')
+      ? Object.freeze({ kind: 'required-hidden-or-invalid' as const, cardinality })
+      : undefined
+  const require = () => {
+    if (unavailable !== undefined) throw new RelationUnavailableError(unavailable)
+    if (resource.data === undefined || resource.data === null) {
+      throw new Error('Relation resource is not settled with an available value.')
+    }
+    return resource.data
+  }
+  return Object.freeze({
+    ...resource,
+    cardinality,
+    ...(unavailable === undefined ? {} : { unavailable }),
+    require,
+  }) as RelationResource<BoundInstanceOf<To>, EffectiveCardinality<Definition, Role, To>>
+}
+
+function admitSource<Relation extends EdgeDefinition, Role extends EndpointRole>(
+  binding: ReturnType<typeof bindingFor>,
+  relation: Relation,
+  from: Role,
+  source: BoundInstanceOf<StartingDefinition<Relation, Role>>,
+): void {
+  const accepted = edgeEndpoints(relation)[from].accepts
+  const matches = accepted.some((ref) => {
+    const candidate = binding.$.inspect(ref) as Definition<'class' | 'interface'>
+    return source.$.definition.satisfies(candidate)
+  })
+  if (!matches) throw new TypeError('Relation source does not satisfy the selected endpoint.')
+}
+
+function endpointCardinality(definition: EdgeDefinition, side: EndpointRole): RelationCardinality {
+  const endpoint = edgeEndpoints(definition)[side]
+  const cardinality = side === 'source' ? endpoint.outgoing : endpoint.incoming
+  if (cardinality === undefined) {
+    throw new TypeError(`Relation ${side} endpoint does not expose its traversal cardinality.`)
+  }
+  return cardinality
+}
+
+function effectiveCardinality<
+  Relation extends EdgeDefinition,
+  Role extends EndpointRole,
+  To extends RelatedDefinition<Relation, Role>,
+>(
+  binding: ReturnType<typeof bindingFor>,
+  relation: Relation,
+  from: Role,
+  to: To,
+): EffectiveCardinality<Relation, Role, To> {
+  const base = endpointCardinality(relation, from)
+  if (base !== '1' && base !== '1..*') {
+    return base as EffectiveCardinality<Relation, Role, To>
+  }
+  const opposite: EndpointRole = from === 'source' ? 'target' : 'source'
+  const coversEndpoint = edgeEndpoints(relation)[opposite].accepts.every((ref) => {
+    const candidate = binding.$.inspect(ref) as Definition<'class' | 'interface'>
+    return candidate.satisfies(to)
+  })
+  return (coversEndpoint ? base : base === '1' ? '0..1' : '0..*') as EffectiveCardinality<
+    Relation,
+    Role,
+    To
+  >
+}
+
+function admitRelatedDefinition<
+  Relation extends EdgeDefinition,
+  Role extends EndpointRole,
+  To extends RelatedDefinition<Relation, Role>,
+>(binding: ReturnType<typeof bindingFor>, relation: Relation, from: Role, to: To): void {
+  const opposite: EndpointRole = from === 'source' ? 'target' : 'source'
+  const accepted = edgeEndpoints(relation)[opposite].accepts
+  const matches = accepted.some((ref) => {
+    const candidate = binding.$.inspect(ref) as Definition<'class' | 'interface'>
+    return to.satisfies(candidate)
+  })
+  if (!matches)
+    throw new TypeError('Relation target definition is not admitted by the opposite endpoint.')
+}
+
+function edgeEndpoints(relation: EdgeDefinition): Readonly<Record<EndpointRole, RuntimeEndpoint>> {
+  const declaration = relation.definition as unknown as {
+    readonly family?: unknown
+    readonly endpoints?: Partial<Record<EndpointRole, RuntimeEndpoint>>
+  }
+  const source = declaration.endpoints?.source
+  const target = declaration.endpoints?.target
+  if (declaration.family !== 'edge' || source === undefined || target === undefined) {
+    throw new TypeError('Relation definition does not expose admitted Edge endpoints.')
+  }
+  return Object.freeze({ source, target })
+}

package/src/selection/live.ts

@@ -1,142 +1,92 @@
-import type { GraphMemory, ReadOptions, ShapeInput } from '@astrale-os/kernel-client/store'
+import type { Node, NodeId } from '@astrale-os/sdk/graph/node'
 
-/**
- * Selection liveness (API §9) — resolve the scope's ids to LIVE memory nodes, and
- * the node types the selection speaks. Each id is subscribed as an independent
- * point-read shape; an id drops ONLY once its shape has SETTLED to absence (the
- * fixed latch) — a cold shape whose point-read has not landed is kept alive with
- * no node, so a selection made from a children row is never self-cleared before
- * its fetch resolves. Degrades to no nodes (ids kept) when no memory is in scope.
- */
-import { useCallback, useContext, useRef, useSyncExternalStore } from 'react'
+import { Path } from '@astrale-os/sdk/graph/path'
+import { useCallback, useEffect, useRef, useState } from 'react'
 
-import { GraphContext } from '../graph/graph.context.js'
+import { useSessionKernel } from '../auth/session-kernel.js'
 
-/** A live memory node — the non-null projection of a point read. */
-export type SelectionNode = NonNullable<ReturnType<GraphMemory['getSnapshot']>['node']>
-export type NodeId = SelectionNode['id']
+export type SelectionNode = Node
+export type { NodeId }
 
-const LIVE_OPTS: ReadOptions = { live: true }
-const EMPTY_NODES: readonly SelectionNode[] = []
-const NOOP = (): void => {}
-
-/** Point-read shape addressing a node by its graph id. */
-function nodeShape(id: NodeId): ShapeInput {
-  return `@${id}`
-}
-
-/** A point-read snapshot — the arms selection reads (widened to tolerate fakes). */
-type NodeSnapshot = { readonly node: SelectionNode | null; live?: boolean; pending?: boolean }
-
-/**
- * A null-node id is a CONFIRMED absence (drop it) only when the shape settled
- * there: it was seen warm and is now gone (deletion), or a live subscription has
- * finished fetching and found nothing (mask/never-existed). A never-warm, not-
- * yet-fetched (cold/pending) shape is NOT absence — the id stays alive, no node.
- */
-function isConfirmedAbsent(snap: NodeSnapshot, id: NodeId, everWarm: ReadonlySet<NodeId>): boolean {
-  if (everWarm.has(id)) return true
-  return snap.live === true && snap.pending === false
-}
-
-/**
- * The in-scope graph memory, structurally narrowed. Reads the base memory the
- * provider seats in `GraphContext`, defensively so selection also works under a
- * bare/fake context (tests) or before one is mounted.
- */
-export function useMemory(): GraphMemory | null {
-  const ctx = useContext(GraphContext) as unknown as GraphMemory | null
-  return ctx !== null &&
-    typeof ctx.subscribe === 'function' &&
-    typeof ctx.getSnapshot === 'function'
-    ? ctx
-    : null
-}
-
-export interface LiveSnapshot {
+export interface ResolvedSelection {
   readonly aliveIds: readonly NodeId[]
   readonly nodes: readonly SelectionNode[]
+  readonly pending: boolean
+  readonly error: unknown
+  refetch(): Promise<void>
 }
 
-function unchanged(
-  prev: LiveSnapshot,
-  aliveIds: readonly NodeId[],
-  nodes: readonly SelectionNode[],
-): boolean {
-  // `aliveIds` and `nodes` can differ in length (a cold id is alive with no node
-  // yet), so compare the two lists independently.
-  if (prev.aliveIds.length !== aliveIds.length || prev.nodes.length !== nodes.length) return false
-  for (let i = 0; i < aliveIds.length; i += 1) if (prev.aliveIds[i] !== aliveIds[i]) return false
-  for (let i = 0; i < nodes.length; i += 1) if (prev.nodes[i] !== nodes[i]) return false
-  return true
+interface State {
+  readonly key: string
+  readonly aliveIds: readonly NodeId[]
+  readonly nodes: readonly SelectionNode[]
+  readonly pending: boolean
+  readonly error: unknown
 }
 
-/**
- * Subscribe to each id's node shape and project the surviving nodes. The result
- * keeps a stable reference across renders when membership and node identities
- * are unchanged (useSyncExternalStore contract).
- */
-export function useLiveNodes(
-  orderedIds: readonly NodeId[],
-  memory: GraphMemory | null,
-): LiveSnapshot {
-  // Stands in for `orderedIds` in the callback deps (a fresh array each render).
-  const idsKey = orderedIds.join(' ')
-  const cache = useRef<{ memory: GraphMemory | null; snap: LiveSnapshot } | null>(null)
-  // Ids whose shape has been seen warm at least once — a later null is a deletion
-  // (confirmed absence), whereas a never-warm null is merely cold. Monotonic, so
-  // re-reading getSnapshot within a render is idempotent (useSyncExternalStore-safe).
-  const everWarm = useRef<Set<NodeId>>(new Set())
+/** Resolve selected identities through the authenticated GraphApi; no fake live subscription. */
+export function useResolvedNodes(orderedIds: readonly NodeId[]): ResolvedSelection {
+  const graph = useSessionKernel().graph
+  const key = orderedIds.join('\u0000')
+  const idsRef = useRef(orderedIds)
+  idsRef.current = orderedIds
+  const generation = useRef(0)
+  const alive = useRef(true)
+  const [state, setState] = useState<State>({
+    key,
+    aliveIds: orderedIds,
+    nodes: [],
+    pending: orderedIds.length > 0,
+    error: undefined,
+  })
+  useEffect(() => {
+    alive.current = true
+    return () => {
+      alive.current = false
+    }
+  }, [])
 
-  const getSnapshot = useCallback((): LiveSnapshot => {
-    let aliveIds: readonly NodeId[]
-    let nodes: readonly SelectionNode[]
-    if (memory === null) {
-      // No liveness source: keep the ids, resolve no nodes.
-      aliveIds = orderedIds
-      nodes = EMPTY_NODES
-    } else {
-      const seen = everWarm.current
-      const a: NodeId[] = []
-      const n: SelectionNode[] = []
-      for (const id of orderedIds) {
-        const snap = memory.getSnapshot(nodeShape(id), LIVE_OPTS) as NodeSnapshot
-        const node = snap.node
-        if (node !== null) {
-          seen.add(id)
-          a.push(id)
-          n.push(node)
-        } else if (!isConfirmedAbsent(snap, id, seen)) {
-          // Cold / not-yet-fetched: keep the id alive, no node yet — never a
-          // premature drop (the critical self-clear this guards against).
-          a.push(id)
-        }
-        // else: settled absence (deleted/masked) → drops from ids and nodes.
+  const load = useCallback(async (): Promise<void> => {
+    const ids = idsRef.current
+    const currentKey = ids.join('\u0000')
+    const id = ++generation.current
+    if (ids.length === 0) {
+      if (alive.current) {
+        setState({ key: currentKey, aliveIds: [], nodes: [], pending: false, error: undefined })
       }
-      aliveIds = a
-      nodes = n
+      return
     }
-    const prev = cache.current
-    if (prev !== null && prev.memory === memory && unchanged(prev.snap, aliveIds, nodes)) {
-      return prev.snap
+    setState({ key: currentKey, aliveIds: ids, nodes: [], pending: true, error: undefined })
+    try {
+      const values = await Promise.all(ids.map((nodeId) => graph.get(Path.id(nodeId))))
+      if (!alive.current || id !== generation.current) return
+      const aliveIds: NodeId[] = []
+      const nodes: Node[] = []
+      values.forEach((node, index) => {
+        if (node === null) return
+        aliveIds.push(ids[index]!)
+        nodes.push(node)
+      })
+      setState({
+        key: currentKey,
+        aliveIds: Object.freeze(aliveIds),
+        nodes: Object.freeze(nodes),
+        pending: false,
+        error: undefined,
+      })
+    } catch (error) {
+      if (alive.current && id === generation.current) {
+        setState({ key: currentKey, aliveIds: ids, nodes: [], pending: false, error })
+      }
     }
-    const snap: LiveSnapshot = { aliveIds, nodes }
-    cache.current = { memory, snap }
-    return snap
-  }, [memory, idsKey])
+  }, [graph])
 
-  const subscribe = useCallback(
-    (onStoreChange: () => void): (() => void) => {
-      if (memory === null || orderedIds.length === 0) return NOOP
-      const unsubs = orderedIds.map((id) =>
-        memory.subscribe(nodeShape(id), onStoreChange, LIVE_OPTS),
-      )
-      return () => {
-        for (const unsub of unsubs) unsub()
-      }
-    },
-    [memory, idsKey],
-  )
+  useEffect(() => {
+    void load()
+  }, [key, load])
 
-  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+  if (state.key !== key) {
+    return { aliveIds: orderedIds, nodes: [], pending: true, error: undefined, refetch: load }
+  }
+  return { ...state, refetch: load }
 }

package/src/selection/scope.context.tsx

@@ -10,7 +10,7 @@ import { createContext, useCallback, useEffect, useMemo, useReducer, useRef } fr
 
 import type { NodeId, SelectionNode } from './live.js'
 
-import { useLiveNodes, useMemory } from './live.js'
+import { useResolvedNodes } from './live.js'
 
 /** The value `useSelection()` returns (API §9). */
 export interface Selection {
@@ -109,14 +109,14 @@ export function SelectionScope(props: SelectionScopeProps): ReactElement {
   const { initial, onChange, children } = props
   const [state, dispatch] = useReducer(reducer, initial, initState)
 
-  const memory = useMemory()
-  const { aliveIds, nodes } = useLiveNodes(state.ids, memory)
+  const { aliveIds, nodes, pending, error } = useResolvedNodes(state.ids)
 
   // Re-canonicalize stored state when liveness drops a node (or its anchor).
   useEffect(() => {
     const anchorDead = state.anchor !== null && !aliveIds.includes(state.anchor)
+    if (pending || error !== undefined) return
     if (!sameIds(state.ids, aliveIds) || anchorDead) dispatch({ t: 'prune', alive: aliveIds })
-  }, [aliveIds, state.ids, state.anchor])
+  }, [aliveIds, pending, error, state.ids, state.anchor])
 
   // Report changes (explicit ops AND liveness drops), skipping the initial mount.
   const onChangeRef = useRef(onChange)

package/src/session/boot/boot.ts

@@ -1,8 +1,3 @@
-/**
- * The boot machine inputs (API §2): config identity (what triggers a reboot) and
- * whoami resolution (`createShell → init → whoami → OS-user preresolve`). Kept
- * pure of React so the provider's boot effect composes them.
- */
 import type { Shell, ShellConfig } from '@astrale-os/shell'
 
 import type { SelfNode } from '../session.context.js'
@@ -13,45 +8,25 @@ export function isShellConfig(config: ShellConfig | Shell): config is ShellConfi
 
 let prebuiltCounter = 0
 const prebuiltIds = new WeakMap<object, string>()
-/** Stable id per prebuilt-Shell object reference (a new object reboots). */
+
 function prebuiltId(shell: object): string {
   let id = prebuiltIds.get(shell)
   if (id === undefined) {
-    prebuiltCounter += 1
-    id = `prebuilt#${prebuiltCounter}`
+    id = `prebuilt#${++prebuiltCounter}`
     prebuiltIds.set(shell, id)
   }
   return id
 }
 
-/**
- * Identity of a config — primitive fields only, so re-passing an inline `fetch`,
- * `adapter`, `getCredential`, or `parentWindow` each render does not reboot;
- * changing the kernel/credential does. A principal switch driven by a NEW
- * `getCredential` closure (rather than a new `credential` string) is therefore
- * NOT observed here — remount the provider (React `key`) to rebind it.
- */
+/** Stable ownership key. Capability objects intentionally use reference identity. */
 export function configIdentity(config: ShellConfig | Shell): string {
   if (!isShellConfig(config)) return prebuiltId(config)
-  if (config.mode === 'standalone') {
-    return [
-      'standalone',
-      config.kernelUrl,
-      config.credential ?? '',
-      config.mintIdentity ?? '',
-      config.windowId ?? '',
-    ].join('|')
-  }
-  return `sandboxed|${config.initTimeoutMs ?? ''}`
+  if (config.mode === 'sandboxed') return prebuiltId(config)
+  if (config.client !== undefined) return `standalone-client|${prebuiltId(config.client)}`
+  return `standalone-session|${prebuiltId(config.session)}`
 }
 
-/** Resolve whoami when the bound kernel exposes an auth surface; else null. */
 export async function resolveSelf(shell: Shell): Promise<SelfNode | null> {
-  const kernel = shell.kernel as unknown as {
-    auth?: { whoami?: () => Promise<SelfNode> }
-  }
-  const auth = kernel.auth
-  const whoami = auth?.whoami
-  if (typeof whoami !== 'function') return null
-  return whoami.call(auth)
+  const auth = shell.kernel.auth
+  return typeof auth.whoami === 'function' ? auth.whoami() : null
 }

package/src/session/index.ts

@@ -6,3 +6,4 @@ export { useKernelClient } from './kernel-client.hook.js'
 export { useKernelInstance } from './kernel-instance.hook.js'
 export type { KernelInstance } from './kernel-instance.hook.js'
 export { useConnection } from './connection/connection.hook.js'
+export type { ConnectionStatus, ConnectionValue } from './connection/connection.store.js'

package/src/session/kernel-instance.hook.ts

@@ -2,21 +2,12 @@ import { useMemo } from 'react'
 
 import { useKernelClient } from './kernel-client.hook.js'
 
+/** Public, non-secret identity of the connected source Kernel. */
 export interface KernelInstance {
-  /** Kernel envelope endpoint this shell is bound to. */
   readonly url: string
-  /** Current kernel credential. Never cache; read per request. */
-  token(): string
 }
 
-/** Low-level access for direct kernel-envelope calls and token exchange code. */
 export function useKernelInstance(): KernelInstance {
   const kernel = useKernelClient()
-  return useMemo<KernelInstance>(
-    () => ({
-      url: kernel.url,
-      token: () => kernel.authToken(),
-    }),
-    [kernel],
-  )
+  return useMemo(() => Object.freeze({ url: kernel.url }), [kernel])
 }