@astrale-os/shell-react 0.1.0

package/dist/auth/can.hook.js

@@ -0,0 +1,119 @@
+import { rawOf } from '@astrale-os/kernel-client/graph';
+/**
+ * useCan (API §4) — deduped standing-grant permission checks. `auth.check`-backed:
+ * `undefined` while the first check is in flight (or `on` is idle), then a boolean.
+ * Deduped per (principal, perms, nodeId) across the whole tree via the principal's
+ * check ledger (folded in here as the dedup substrate). Standing-grant semantics:
+ * the dispatched call remains the gatekeeper — this is a UI affordance, not the
+ * enforcement point (SPEC §6.2). A local grant/revoke invalidates the ledger.
+ */
+import { useCallback, useMemo, useSyncExternalStore } from 'react';
+import { isIdleInput } from '../graph/memory/read/idle';
+import { useIdentityBinding } from './act-as.context';
+const NOOP_UNSUB = () => undefined;
+/** A node value carries the id/class/path triple (mirrors the memory's `isNodeValue`). */
+export function isNodeValue(x) {
+    return typeof x === 'object' && x !== null && 'id' in x && 'class' in x && 'path' in x;
+}
+/** Normalize a `useCan` subject to a dispatchable `Ref` plus a stable dedup key. */
+export function toRef(on) {
+    if (isNodeValue(on))
+        return { ref: on.path, key: `@${on.id}` };
+    return { ref: on, key: rawOf(on) };
+}
+// ── check ledger (the dedup substrate) ───────────────────────────────────────
+/** One deduped check — its last-known value plus the subscribers watching it. */
+class CheckCell {
+    auth;
+    perms;
+    on;
+    value = undefined;
+    inFlight = false;
+    listeners = new Set();
+    constructor(auth, perms, on) {
+        this.auth = auth;
+        this.perms = perms;
+        this.on = on;
+    }
+    subscribe = (onChange) => {
+        this.listeners.add(onChange);
+        this.ensure();
+        return () => this.listeners.delete(onChange);
+    };
+    getSnapshot = () => this.value;
+    /** Run the check once when the value is unknown and nothing is in flight. */
+    ensure() {
+        if (this.value !== undefined || this.inFlight)
+            return;
+        this.run();
+    }
+    /** Force a re-check (local grant/revoke on this principal). */
+    invalidate() {
+        if (this.listeners.size === 0) {
+            this.value = undefined; // recompute lazily on the next subscribe
+            return;
+        }
+        this.run();
+    }
+    run() {
+        this.inFlight = true;
+        void this.auth
+            .check({ on: this.on, perms: this.perms })
+            .then((ok) => {
+            this.value = ok;
+        }, () => {
+            // A failed check leaves the value unknown (undefined) — never a false grant.
+            this.value = undefined;
+        })
+            .finally(() => {
+            this.inFlight = false;
+            for (const l of this.listeners)
+                l();
+        });
+    }
+}
+/** Per-principal cell registry — dedup across the whole tree for one kernel handle. */
+export class CheckLedger {
+    auth;
+    cells = new Map();
+    constructor(auth) {
+        this.auth = auth;
+    }
+    cell(key, perms, on) {
+        let cell = this.cells.get(key);
+        if (cell === undefined) {
+            cell = new CheckCell(this.auth, perms, on);
+            this.cells.set(key, cell);
+        }
+        return cell;
+    }
+    /** Re-check every observed cell — conservative Tier-0 sweep after a local grant/revoke. */
+    invalidateAll() {
+        for (const cell of this.cells.values())
+            cell.invalidate();
+    }
+}
+// One ledger per bound kernel object → per principal. `session.as(cred)` mints a
+// fresh view per ActAs, so acted-as principals never share a ledger with the root.
+const ledgers = new WeakMap();
+export function ledgerFor(kernel) {
+    let ledger = ledgers.get(kernel);
+    if (ledger === undefined) {
+        ledger = new CheckLedger(kernel.auth);
+        ledgers.set(kernel, ledger);
+    }
+    return ledger;
+}
+// ── useCan ────────────────────────────────────────────────────────────────────
+export function useCan(perms, on) {
+    const binding = useIdentityBinding();
+    const ref = isIdleInput(on) ? null : toRef(on);
+    // The shared cell for (principal, perms, nodeId): identical to every other
+    // useCan reading the same triple, so one check serves the whole tree.
+    const cell = useMemo(() => ref === null ? null : ledgerFor(binding.kernel).cell(`${perms}\0${ref.key}`, perms, ref.ref), 
+    // ref is rebuilt per render; its `key` string is the stable identity.
+    [binding.kernel, perms, ref?.key]);
+    const subscribe = useCallback((onChange) => (cell === null ? NOOP_UNSUB : cell.subscribe(onChange)), [cell]);
+    const getSnapshot = useCallback(() => cell?.getSnapshot(), [cell]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

package/dist/auth/index.d.ts

@@ -0,0 +1,6 @@
+export { ActAs } from './act-as.context';
+export type { ActAsProps } from './act-as.context';
+export { useAuth } from './auth.hook';
+export { useCan } from './can.hook';
+export { useSelf } from './self.hook';
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACxC,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACnC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA"}

package/dist/auth/index.js

@@ -0,0 +1,5 @@
+// auth — API §4 (useSelf, useCan, useAuth, ActAs). See SHELL_REACT_API.md.
+export { ActAs } from './act-as.context';
+export { useAuth } from './auth.hook';
+export { useCan } from './can.hook';
+export { useSelf } from './self.hook';

package/dist/auth/self.hook.d.ts

@@ -0,0 +1,3 @@
+import type { NodeValue } from './act-as.context';
+export declare function useSelf(): NodeValue;
+//# sourceMappingURL=self.hook.d.ts.map

package/dist/auth/self.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self.hook.d.ts","sourceRoot":"","sources":["../../src/auth/self.hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAWjD,wBAAgB,OAAO,IAAI,SAAS,CAEnC"}

package/dist/auth/self.hook.js

@@ -0,0 +1,11 @@
+/**
+ * useSelf (API §4) — the caller's identity node, resolved at boot and read
+ * synchronously (never suspends). An <ActAs> subtree returns the acted-as
+ * identity. FLAG: today this is the boot-resolved whoami snapshot; it becomes a
+ * live memory shape once the graph plane subscribes the self node — no signature
+ * change.
+ */
+import { useIdentityBinding } from './act-as.context';
+export function useSelf() {
+    return useIdentityBinding().self;
+}

package/dist/auth/session-kernel.d.ts

@@ -0,0 +1,4 @@
+import type { SessionView } from './act-as.context';
+/** The EFFECTIVE dispatch kernel for this subtree. Throws outside a provider. */
+export declare function useSessionKernel(): SessionView;
+//# sourceMappingURL=session-kernel.d.ts.map

package/dist/auth/session-kernel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-kernel.d.ts","sourceRoot":"","sources":["../../src/auth/session-kernel.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAKnD,iFAAiF;AACjF,wBAAgB,gBAAgB,IAAI,WAAW,CAQ9C"}

package/dist/auth/session-kernel.js

@@ -0,0 +1,21 @@
+/**
+ * useSessionKernel (API §4) — the dispatch-floor resolver. Inside an `<ActAs>` it
+ * is the acted-as principal's bound session view; otherwise the root
+ * `shell.kernel`. Every dispatch floor (schema bindings, useCall/useStream, useMove,
+ * typed method dispatch) routes through this so a call runs as the subtree's
+ * principal — not the root — and its scoped memory.
+ */
+import { useContext } from 'react';
+import { ShellContext } from '../session/session.context';
+import { IdentityContext } from './act-as.context';
+/** The EFFECTIVE dispatch kernel for this subtree. Throws outside a provider. */
+export function useSessionKernel() {
+    const binding = useContext(IdentityContext);
+    const runtime = useContext(ShellContext);
+    if (binding !== null)
+        return binding.kernel;
+    if (runtime === null) {
+        throw new Error('session hooks must be used within a <ShellProvider>');
+    }
+    return runtime.shell.kernel;
+}

package/dist/graph/action.d.ts

@@ -0,0 +1,22 @@
+/** The stateful callable every write/dispatch hook returns. */
+export interface Action<A extends unknown[], R> {
+    /** Invoke; rejects on failure AND records it on `.error`. */
+    (...args: A): Promise<R>;
+    /** ≥1 invocation in flight (the OR across concurrent calls). */
+    readonly pending: boolean;
+    /** Last rejection; cleared when the next invocation starts. */
+    readonly error: unknown;
+    /** Last successful resolution. */
+    readonly result: R | undefined;
+    /** Clears error/result. */
+    reset(): void;
+}
+/**
+ * Wrap an async function in the Action envelope. Concurrent invocations are
+ * allowed — each returns its own promise; `pending` is the OR of the in-flight
+ * count and `result`/`error` reflect the latest settlement. The callable keeps
+ * ONE identity for the hook's lifetime (safe in deps arrays); its snapshot
+ * fields are re-stamped each render, so reads stay current across settlements.
+ */
+export declare function useAction<A extends unknown[], R>(fn: (...args: A) => Promise<R>): Action<A, R>;
+//# sourceMappingURL=action.d.ts.map

package/dist/graph/action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../src/graph/action.ts"],"names":[],"mappings":"AASA,+DAA+D;AAC/D,MAAM,WAAW,MAAM,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC;IAC5C,6DAA6D;IAC7D,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IACxB,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,SAAS,CAAA;IAC9B,2BAA2B;IAC3B,KAAK,IAAI,IAAI,CAAA;CACd;AA4CD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAsD9F"}

package/dist/graph/action.js

@@ -0,0 +1,85 @@
+/**
+ * The Action envelope (API §1.2) — a graph-plane primitive, not a context (rule
+ * 5). Holds the `Action<A,R>` type (public — it appears in every write/dispatch
+ * hook signature) and the `useAction` stateful-callable factory (internal): a
+ * render-stable callable whose pending/error/result snapshot is re-stamped each
+ * render, safe in deps arrays.
+ */
+import { useCallback, useEffect, useReducer, useRef } from 'react';
+const IDLE_SNAPSHOT = {
+    pending: false,
+    error: undefined,
+    result: undefined,
+};
+function actionReducer(state, event) {
+    switch (event.type) {
+        case 'start':
+            // §1.2: a new invocation clears the error and keeps the last result.
+            return { pending: true, error: undefined, result: state.result };
+        case 'resolve':
+            // Latest settlement wins: a success records the result and clears error.
+            return { pending: event.inFlight > 0, error: undefined, result: event.value };
+        case 'reject':
+            return { pending: event.inFlight > 0, error: event.error, result: state.result };
+        case 'reset':
+            return { pending: state.pending, error: undefined, result: undefined };
+    }
+}
+/**
+ * Wrap an async function in the Action envelope. Concurrent invocations are
+ * allowed — each returns its own promise; `pending` is the OR of the in-flight
+ * count and `result`/`error` reflect the latest settlement. The callable keeps
+ * ONE identity for the hook's lifetime (safe in deps arrays); its snapshot
+ * fields are re-stamped each render, so reads stay current across settlements.
+ */
+export function useAction(fn) {
+    // Latest-closure ref so the stable callable always dispatches the current fn.
+    const fnRef = useRef(fn);
+    fnRef.current = fn;
+    const [snapshot, dispatch] = useReducer(actionReducer, IDLE_SNAPSHOT);
+    const inFlight = useRef(0);
+    const alive = useRef(true);
+    useEffect(() => {
+        alive.current = true;
+        return () => {
+            alive.current = false;
+        };
+    }, []);
+    const call = useCallback((...args) => {
+        inFlight.current += 1;
+        dispatch({ type: 'start' });
+        let promise;
+        try {
+            promise = Promise.resolve(fnRef.current(...args));
+        }
+        catch (err) {
+            promise = Promise.reject(err);
+        }
+        void promise.then((value) => {
+            inFlight.current -= 1;
+            if (alive.current)
+                dispatch({ type: 'resolve', value, inFlight: inFlight.current });
+        }, (err) => {
+            inFlight.current -= 1;
+            if (alive.current)
+                dispatch({ type: 'reject', error: err, inFlight: inFlight.current });
+        });
+        return promise;
+    }, []);
+    const reset = useCallback(() => dispatch({ type: 'reset' }), []);
+    // One render-stable callable: built once (call/reset are themselves stable),
+    // then its snapshot fields re-stamped every render. Re-renders are driven by
+    // the reducer, so the stamped pending/error/result stay fresh WITHOUT minting
+    // a new function identity — the documented "safe in deps arrays" guarantee.
+    const actionRef = useRef(null);
+    if (actionRef.current === null) {
+        const action = ((...args) => call(...args));
+        action.reset = reset;
+        actionRef.current = action;
+    }
+    const action = actionRef.current;
+    action.pending = snapshot.pending;
+    action.error = snapshot.error;
+    action.result = snapshot.result;
+    return action;
+}

package/dist/graph/async.d.ts

@@ -0,0 +1,11 @@
+import type { ReadState } from './memory/read/envelope';
+export interface AsyncResource<T> extends ReadState {
+    readonly data: T;
+}
+/**
+ * Subscribe a component to `load()`. `null` loader → idle. The loader runs on
+ * mount and whenever `deps` change (stale responses discarded); last-good data is
+ * retained through a pending refetch or a failure (§1.1).
+ */
+export declare function useAsyncResource<T>(load: (() => Promise<T>) | null, empty: T, deps: readonly unknown[]): AsyncResource<T>;
+//# sourceMappingURL=async.d.ts.map

package/dist/graph/async.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../../src/graph/async.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAEvD,MAAM,WAAW,aAAa,CAAC,CAAC,CAAE,SAAQ,SAAS;IACjD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;CACjB;AAQD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,IAAI,EAAE,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAC/B,KAAK,EAAE,CAAC,EACR,IAAI,EAAE,SAAS,OAAO,EAAE,GACvB,aAAa,CAAC,CAAC,CAAC,CAyDlB"}

package/dist/graph/async.js

@@ -0,0 +1,60 @@
+/**
+ * useAsyncResource (API §1.1) — a one-shot async read projected into the §1 read
+ * envelope (`ReadState`): the non-memory sibling of `useRead`, stale-guarded and
+ * `refetch`-able, with a `null` loader as idle. Shared by `application/` and the
+ * window `useViewsFor` dispatch; homed here (below both) to keep rule 9 acyclic.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+/**
+ * Subscribe a component to `load()`. `null` loader → idle. The loader runs on
+ * mount and whenever `deps` change (stale responses discarded); last-good data is
+ * retained through a pending refetch or a failure (§1.1).
+ */
+export function useAsyncResource(load, empty, deps) {
+    const [state, setState] = useState({
+        data: empty,
+        pending: load !== null,
+        error: undefined,
+    });
+    const loadRef = useRef(load);
+    loadRef.current = load;
+    const emptyRef = useRef(empty);
+    emptyRef.current = empty;
+    const seq = useRef(0);
+    const alive = useRef(true);
+    useEffect(() => {
+        alive.current = true;
+        return () => {
+            alive.current = false;
+        };
+    }, []);
+    const refetch = useCallback(() => {
+        const run = loadRef.current;
+        if (run === null) {
+            setState({ data: emptyRef.current, pending: false, error: undefined });
+            return Promise.resolve();
+        }
+        const my = ++seq.current;
+        setState((s) => ({ data: s.data, pending: true, error: undefined }));
+        return run().then((data) => {
+            if (alive.current && my === seq.current)
+                setState({ data, pending: false, error: undefined });
+        }, (error) => {
+            if (alive.current && my === seq.current) {
+                setState((s) => ({ data: s.data, pending: false, error }));
+            }
+        });
+    }, []);
+    useEffect(() => {
+        void refetch();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, deps);
+    return useMemo(() => ({
+        data: state.data,
+        pending: state.pending,
+        error: state.error,
+        live: false,
+        seq: 0,
+        refetch,
+    }), [state.data, state.pending, state.error, refetch]);
+}

package/dist/graph/call/call.hook.d.ts

@@ -0,0 +1,21 @@
+/**
+ * useCall (API §7) — unary domain-function dispatch over `kernel.call`, in the
+ * Action envelope. No result caching, no liveness — domain function reads are not
+ * structurally invalidatable (FRONTEND §5.7); a consumer that needs freshness
+ * owns its own refetch policy. Dispatch is a graph operation (rule 2).
+ */
+import type { CallFns, FnMap } from '@astrale-os/kernel-client';
+import type { Action } from '../action';
+export interface CallOptions {
+    /** Per-call timeout (ms), forwarded to the kernel dispatch. */
+    timeout?: number;
+    /** Side-channel notified on rejection (the Action also records `.error`). */
+    onError?(error: unknown): void;
+}
+/**
+ * Unary domain-function dispatch as an {@link Action}. `method` is a typed FnMap
+ * `call` path or any string (the untyped floor); `null` yields an idle action
+ * that rejects if invoked. Params/result are typed from the FnMap entry.
+ */
+export declare function useCall<K extends CallFns<FnMap>>(method: K | null, opts?: CallOptions): Action<[FnMap[K]['params']], FnMap[K]['result']>;
+//# sourceMappingURL=call.hook.d.ts.map

package/dist/graph/call/call.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call.hook.d.ts","sourceRoot":"","sources":["../../../src/graph/call/call.hook.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAA;AAE/D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAKvC,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,6EAA6E;IAC7E,OAAO,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,OAAO,CAAC,KAAK,CAAC,EAC9C,MAAM,EAAE,CAAC,GAAG,IAAI,EAChB,IAAI,CAAC,EAAE,WAAW,GACjB,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAalD"}

package/dist/graph/call/call.hook.js

@@ -0,0 +1,23 @@
+import { useSessionKernel } from '../../auth/session-kernel';
+import { useAction } from '../action';
+/**
+ * Unary domain-function dispatch as an {@link Action}. `method` is a typed FnMap
+ * `call` path or any string (the untyped floor); `null` yields an idle action
+ * that rejects if invoked. Params/result are typed from the FnMap entry.
+ */
+export function useCall(method, opts) {
+    const kernel = useSessionKernel();
+    // A fresh closure per render captures the current method/opts; `useAction`
+    // keeps ONE stable callable and always dispatches this latest closure.
+    return useAction(async (params) => {
+        if (method === null)
+            throw new Error('useCall: method is null (idle action invoked)');
+        try {
+            return await kernel.call(method, params, { timeout: opts?.timeout });
+        }
+        catch (error) {
+            opts?.onError?.(error);
+            throw error;
+        }
+    });
+}

package/dist/graph/call/stream.hook.d.ts

@@ -0,0 +1,28 @@
+import type { FnMap, StreamFns } from '@astrale-os/kernel-client';
+export interface StreamOptions<T> {
+    /** Notified per chunk as it arrives (in addition to `chunks` accumulation). */
+    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`. */
+    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;
+}
+/**
+ * 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 declare function useStream<K extends StreamFns<FnMap>>(method: K | null, opts?: StreamOptions<FnMap[K]['result']>): StreamHandle<FnMap[K]['result']>;
+//# sourceMappingURL=stream.hook.d.ts.map

package/dist/graph/call/stream.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.hook.d.ts","sourceRoot":"","sources":["../../../src/graph/call/stream.hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAYjE,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,+EAA+E;IAC/E,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAA;CACzB;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,2FAA2F;IAC3F,KAAK,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAA;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;IACvB,0BAA0B;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,6EAA6E;IAC7E,MAAM,IAAI,IAAI,CAAA;CACf;AA2DD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,SAAS,CAAC,KAAK,CAAC,EAClD,MAAM,EAAE,CAAC,GAAG,IAAI,EAChB,IAAI,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,GACvC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAoGlC"}

package/dist/graph/call/stream.hook.js

@@ -0,0 +1,137 @@
+/**
+ * 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';
+const IDLE_STREAM = {
+    chunks: [],
+    last: null,
+    streaming: false,
+    error: undefined,
+};
+function streamReducer(state, event) {
+    switch (event.type) {
+        case 'start':
+            return { chunks: [], last: null, streaming: true, error: undefined };
+        case 'chunk':
+            return {
+                chunks: [...state.chunks, event.value],
+                last: event.value,
+                streaming: true,
+                error: undefined,
+            };
+        case 'end':
+            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 };
+    }
+}
+/**
+ * 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(method, opts) {
+    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, IDLE_STREAM);
+    // `runId` supersession token; only the run whose id is still current drives state.
+    const runIdRef = useRef(0);
+    const currentRef = useRef(null);
+    const alive = useRef(true);
+    const stop = useCallback(() => {
+        const run = currentRef.current;
+        if (run !== null) {
+            run.controller.abort();
+            void run.iterator?.return?.(undefined);
+            currentRef.current = null;
+        }
+    }, []);
+    useEffect(() => {
+        alive.current = true;
+        return () => {
+            alive.current = false;
+            stop();
+        };
+    }, [stop]);
+    const cancel = useCallback(() => {
+        runIdRef.current += 1;
+        stop();
+        if (alive.current)
+            dispatch({ type: 'cancel' });
+    }, [stop]);
+    const start = useCallback((params) => {
+        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
+        dispatch({ type: 'start' });
+        const controller = new AbortController();
+        const run = { controller, iterator: null };
+        currentRef.current = run;
+        const current = () => 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;
+            }
+        })();
+    }, [stop]);
+    // 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(null);
+    if (handleRef.current === null) {
+        handleRef.current = { start, cancel };
+    }
+    const handle = handleRef.current;
+    handle.chunks = snapshot.chunks;
+    handle.last = snapshot.last;
+    handle.streaming = snapshot.streaming;
+    handle.error = snapshot.error;
+    return handle;
+}

package/dist/graph/graph.context.d.ts

@@ -0,0 +1,4 @@
+import type { GraphMemory } from '@astrale-os/kernel-client/store';
+export type { GraphMemory };
+export declare const GraphContext: import("react").Context<GraphMemory | null>;
+//# sourceMappingURL=graph.context.d.ts.map

package/dist/graph/graph.context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.context.d.ts","sourceRoot":"","sources":["../../src/graph/graph.context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AAWlE,YAAY,EAAE,WAAW,EAAE,CAAA;AAC3B,eAAO,MAAM,YAAY,6CAA0C,CAAA"}

package/dist/graph/graph.context.js

@@ -0,0 +1,10 @@
+/**
+ * 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 const GraphContext = createContext(null);
+GraphContext.displayName = 'AstraleGraphContext';

package/dist/graph/guards.error.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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, TransportError, } from '@astrale-os/kernel-client';
+//# sourceMappingURL=guards.error.d.ts.map

package/dist/graph/guards.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.error.d.ts","sourceRoot":"","sources":["../../src/graph/guards.error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,WAAW,EACX,oBAAoB,EACpB,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,yBAAyB,EACzB,eAAe,EACf,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,uBAAuB,EACvB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,EACzB,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,YAAY,EACZ,uBAAuB,EACvB,4BAA4B,EAC5B,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,0BAA0B,EAC1B,8BAA8B,EAC9B,gBAAgB,EAChB,2BAA2B,EAC3B,iBAAiB,EACjB,YAAY,GACb,MAAM,2BAA2B,CAAA;AAClC,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,2BAA2B,CAAA"}

package/dist/graph/guards.error.js

@@ -0,0 +1,7 @@
+/**
+ * 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';