@astrale-os/kernel-client 0.2.3 → 0.3.0

package/dist/store/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAGvC,OAAO,EACL,eAAe,EACf,eAAe,EACf,QAAQ,EACR,eAAe,EACf,YAAY,GACb,MAAM,gBAAgB,CAAA;AAGvB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAGxC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAGrC,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAGnD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA"}

package/dist/store/invalidate.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Tier-0 invalidation matching (FRONTEND §5.6 / §5.7).
+ *
+ * Because the runnable algebra is closed (a single `has_parent` descent + N
+ * single-hop gathers), "does patch P affect shape S" is decidable client-side
+ * with no kernel change. This module is pure over a {@link ShapeView} — the
+ * ShapeStore supplies the view, the overlay/memory apply the matches.
+ *
+ * SHIM CONTRACT (§5.7): this is a deliberately OVER-BROAD disposable shim, the
+ * whole reason SAFE MODE is "slow but never wrong". A false positive costs one
+ * needless refetch; a false NEGATIVE is a shape that silently never reconciles —
+ * a stale view and hours of debugging, and is FORBIDDEN. So every arm biases to
+ * "affected" the instant it is uncertain (an unresolved class, an unknown edge
+ * selector, a path form it cannot compare). Do NOT grow this toward faithful
+ * query semantics to shave refetches — `function.watch` (§7) deletes it whole,
+ * and with it the whole dual-semantics burden.
+ */
+import type { GraphNodeWire } from '../graph';
+import type { NormalPatch } from './overlay';
+type NodeId = GraphNodeWire['id'];
+/** One gather step's selector: which edge classes, which direction. */
+export interface GatherSpec {
+    /** Matched edge classes; `undefined` = all classes. */
+    readonly edgeClasses?: readonly string[];
+    readonly dir: 'in' | 'out' | 'both';
+}
+/** The projection of a shape the matcher needs — produced by the ShapeStore. */
+export interface ShapeView {
+    readonly id: string;
+    /** Resolved root paths (raw). */
+    readonly rootPaths: readonly string[];
+    /** `has_parent` descent depth; 0 for a point read (no move). */
+    readonly depth: number;
+    /** The move's `children.classes` restriction, or `undefined` for all. */
+    readonly moveClasses?: readonly string[];
+    readonly gathers: readonly GatherSpec[];
+    /** Membership test — is this node id a root or a member of the shape? */
+    hasNode(id: NodeId): boolean;
+}
+/** Context the matcher resolves paths and identifies the tree edge with. */
+export interface InvalidateCtx {
+    readonly hasParentClass: string;
+    /** Resolve a raw path to a live node id (confirmed ⊕ overlay). */
+    resolve(raw: string): NodeId | undefined;
+}
+/** The set of shape ids a patch affects. */
+export declare function affectedShapes(patch: NormalPatch, shapes: Iterable<ShapeView>, ctx: InvalidateCtx): Set<string>;
+/**
+ * A node create/delete at `pRaw` (class `cls`) affects a shape when `pRaw`
+ * falls in a root's subtree within `depth` and the move's class filter admits
+ * it (the root itself is never class-filtered — it is the seed, not a child).
+ */
+export declare function matchesNodeStructural(shape: ShapeView, pRaw: string, cls: string | undefined): boolean;
+/**
+ * An edge op affects a shape when some gather selector matches its class and a
+ * root is the near endpoint; a `has_parent` edge additionally re-tests subtree
+ * membership at its child (source) endpoint.
+ */
+export declare function matchesEdge(shape: ShapeView, edgeClass: string, sourceRaw: string, targetRaw: string, hasParentClass: string): boolean;
+/**
+ * Depth of `pRaw` below `rootRaw` in the tree (0 = the root itself), or `null`
+ * when `pRaw` is not within the root's subtree. Slug-segment prefix test.
+ */
+export declare function subtreeDelta(rootRaw: string, pRaw: string): number | null;
+export {};
+//# sourceMappingURL=invalidate.d.ts.map

package/dist/store/invalidate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidate.d.ts","sourceRoot":"","sources":["../../src/store/invalidate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAE5C,KAAK,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAA;AAEjC,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxC,QAAQ,CAAC,GAAG,EAAE,IAAI,GAAG,KAAK,GAAG,MAAM,CAAA;CACpC;AAED,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,yEAAyE;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxC,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAA;IACvC,yEAAyE;IACzE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;CAC7B;AAED,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,kEAAkE;IAClE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CACzC;AAED,4CAA4C;AAC5C,wBAAgB,cAAc,CAC5B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,EAC3B,GAAG,EAAE,aAAa,GACjB,GAAG,CAAC,MAAM,CAAC,CAMb;AAyBD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,OAAO,CAgBT;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GACrB,OAAO,CAQT;AAYD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASzE"}

package/dist/store/invalidate.js

@@ -0,0 +1,117 @@
+/**
+ * Tier-0 invalidation matching (FRONTEND §5.6 / §5.7).
+ *
+ * Because the runnable algebra is closed (a single `has_parent` descent + N
+ * single-hop gathers), "does patch P affect shape S" is decidable client-side
+ * with no kernel change. This module is pure over a {@link ShapeView} — the
+ * ShapeStore supplies the view, the overlay/memory apply the matches.
+ *
+ * SHIM CONTRACT (§5.7): this is a deliberately OVER-BROAD disposable shim, the
+ * whole reason SAFE MODE is "slow but never wrong". A false positive costs one
+ * needless refetch; a false NEGATIVE is a shape that silently never reconciles —
+ * a stale view and hours of debugging, and is FORBIDDEN. So every arm biases to
+ * "affected" the instant it is uncertain (an unresolved class, an unknown edge
+ * selector, a path form it cannot compare). Do NOT grow this toward faithful
+ * query semantics to shave refetches — `function.watch` (§7) deletes it whole,
+ * and with it the whole dual-semantics burden.
+ */
+/** The set of shape ids a patch affects. */
+export function affectedShapes(patch, shapes, ctx) {
+    const out = new Set();
+    for (const shape of shapes) {
+        if (shapeAffected(shape, patch, ctx))
+            out.add(shape.id);
+    }
+    return out;
+}
+function shapeAffected(shape, patch, ctx) {
+    // node create/delete — ancestor-chain + class-filter test against resolved roots
+    for (const c of patch.nodes.create) {
+        if (matchesNodeStructural(shape, c.at, c.class))
+            return true;
+    }
+    for (const d of patch.nodes.delete) {
+        if (matchesNodeStructural(shape, d.path, d.class))
+            return true;
+        const id = ctx.resolve(d.path);
+        if (id !== undefined && shape.hasNode(id))
+            return true;
+    }
+    // node update — membership (order re-sort is handled by the resulting recompute)
+    for (const u of patch.nodes.update) {
+        const id = ctx.resolve(u.path);
+        if (id !== undefined && shape.hasNode(id))
+            return true;
+    }
+    // edge create/update/delete — gather selector + endpoint-in-roots; has_parent
+    // additionally re-tests subtree membership at the child endpoint
+    for (const e of [...patch.edges.create, ...patch.edges.update, ...patch.edges.delete]) {
+        if (matchesEdge(shape, e.class, e.source, e.target, ctx.hasParentClass))
+            return true;
+    }
+    return false;
+}
+/**
+ * A node create/delete at `pRaw` (class `cls`) affects a shape when `pRaw`
+ * falls in a root's subtree within `depth` and the move's class filter admits
+ * it (the root itself is never class-filtered — it is the seed, not a child).
+ */
+export function matchesNodeStructural(shape, pRaw, cls) {
+    for (const root of shape.rootPaths) {
+        const delta = subtreeDelta(root, pRaw);
+        if (delta === null || delta > shape.depth)
+            continue;
+        // Bias to affected (§5.7): the root is never class-filtered, an all-classes
+        // move admits everything, and an UNKNOWN class (`cls === undefined`) is
+        // treated as admitted — a possible false positive (one refetch), never a
+        // false negative (a class we couldn't read silently excluding a real child).
+        const admits = delta === 0 ||
+            shape.moveClasses === undefined ||
+            cls === undefined ||
+            shape.moveClasses.includes(cls);
+        if (admits)
+            return true;
+    }
+    return false;
+}
+/**
+ * An edge op affects a shape when some gather selector matches its class and a
+ * root is the near endpoint; a `has_parent` edge additionally re-tests subtree
+ * membership at its child (source) endpoint.
+ */
+export function matchesEdge(shape, edgeClass, sourceRaw, targetRaw, hasParentClass) {
+    if (edgeClass === hasParentClass && matchesNodeStructural(shape, sourceRaw, undefined))
+        return true;
+    for (const g of shape.gathers) {
+        if (g.edgeClasses !== undefined && !g.edgeClasses.includes(edgeClass))
+            continue;
+        if (endpointInRoots(shape.rootPaths, g.dir, sourceRaw, targetRaw))
+            return true;
+    }
+    return false;
+}
+function endpointInRoots(rootPaths, dir, sourceRaw, targetRaw) {
+    const near = dir === 'out' ? [sourceRaw] : dir === 'in' ? [targetRaw] : [sourceRaw, targetRaw];
+    return near.some((p) => rootPaths.includes(p));
+}
+/**
+ * Depth of `pRaw` below `rootRaw` in the tree (0 = the root itself), or `null`
+ * when `pRaw` is not within the root's subtree. Slug-segment prefix test.
+ */
+export function subtreeDelta(rootRaw, pRaw) {
+    if (rootRaw === pRaw)
+        return 0;
+    const rs = segments(rootRaw);
+    const ps = segments(pRaw);
+    if (ps.length <= rs.length)
+        return null;
+    for (let i = 0; i < rs.length; i++) {
+        if (rs[i] !== ps[i])
+            return null;
+    }
+    return ps.length - rs.length;
+}
+function segments(raw) {
+    return raw.split('/').filter((s) => s.length > 0);
+}
+//# sourceMappingURL=invalidate.js.map

package/dist/store/invalidate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidate.js","sourceRoot":"","sources":["../../src/store/invalidate.ts"],"names":[],"mappings":"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"}

package/dist/store/memory.d.ts

@@ -0,0 +1,97 @@
+/**
+ * createMemory (FRONTEND §4.5, SHELL_REACT §5) — the framework-free memory
+ * facade over a `GraphApi`.
+ *
+ * One partial client copy of the graph per scope (= principal): entity store +
+ * shape store + optimistic overlay. Reads are shape-keyed, deduped, and
+ * stale-while-revalidate; a `subscribe`/`getSnapshot` pair gives
+ * useSyncExternalStore semantics (tear-free, referentially stable when
+ * unchanged) and `promise` a cold-shape handle for React suspense.
+ *
+ * SAFE MODE (§5.7 — ratified until the §6 wire amendments land). One rule:
+ * **confirmed state comes only from server responses; client predictions live
+ * only in a display layer guaranteed to be discarded and replaced by server
+ * truth.** Concretely:
+ *   - Confirmed state (EntityStore + shape membership) is written ONLY by read
+ *     responses (`integrate` / `integrateShape`).
+ *   - Every write DISPATCHES, then marks the shapes it touched stale and
+ *     REVALIDATES them (refetch = reconcile). "Slow but never wrong."
+ *   - The optimistic overlay is DISPLAY-ONLY. Prop updates on cached nodes and
+ *     deletes get an overlay (no-flicker prediction); creates/links/unlinks are
+ *     reconcile-only (a create/link misprediction is a phantom, forbidden; a
+ *     delete misprediction is loud — a brief reappearance). The overlay is held
+ *     from apply until the reconciling refetch lands, then dropped — never
+ *     folded into confirmed state.
+ *   - Ordering: the logical merge clock is stamped at response ARRIVAL, and a
+ *     per-scope mutation EPOCH closes the read-straddles-commit window (a
+ *     response older than a commit is integrated-then-restaled).
+ *   - Isolation: the `with` lens partitions the ENTITY store, not just the
+ *     shape key — lenses never share entities.
+ *
+ * The public surface (`GraphMemory`/`LiveResult`, `createMemory`) is stable:
+ * when seq/rev/delta/watch (§6/§7) land, this becomes "fast and never wrong"
+ * with no surface change (`commitOverlay` is already the server-delta seam).
+ */
+import type { Node } from '@astrale-os/kernel-core';
+import type { EdgeIdentity, GraphApi, MutationResultWire, PatchBuilder, PatchInput, PathLike, Properties } from '../graph';
+import type { ShapeInput } from './canonicalize';
+import type { LiveResult, MutateOptions, ReadOptions, MemoryOptions } from './types';
+/** The framework-free memory surface (SHELL_REACT §5 + FRONTEND §4.5). */
+export interface GraphMemory {
+    /** The principal/isolation key this handle is bound to. */
+    readonly scope: string;
+    /** The raw floor, untouched. */
+    readonly api: GraphApi;
+    /** Read-through: resolve the shape, fetching if cold, then return the live result. */
+    query(shape: ShapeInput, opts?: ReadOptions): Promise<LiveResult>;
+    /** Memory-only, synchronous — no I/O. `null` when the shape is cold. */
+    peek(shape: ShapeInput, opts?: ReadOptions): LiveResult | null;
+    /** Warm the exact shape a later render reads. */
+    preload(shape: ShapeInput, opts?: ReadOptions): Promise<void>;
+    /** External-store subscription: `onStoreChange` fires when this shape changes. */
+    subscribe(shape: ShapeInput, onStoreChange: () => void, opts?: ReadOptions): () => void;
+    /** The current live result for a shape — stable ref when unchanged (getSnapshot). */
+    getSnapshot(shape: ShapeInput, opts?: ReadOptions): LiveResult;
+    /** A promise that resolves once the shape first has confirmed data (suspense). */
+    promise(shape: ShapeInput, opts?: ReadOptions): Promise<LiveResult>;
+    /** Convenience: subscribe + push the current (and each subsequent) snapshot to `cb`. */
+    watch(shape: ShapeInput, cb: (result: LiveResult) => void, opts?: ReadOptions): () => void;
+    /** Batch write — optimistic-auto (§4.4). Builder or pre-built patch. */
+    mutate(arg: ((m: PatchBuilder) => void | Promise<void>) | PatchInput, opts?: MutateOptions): Promise<MutationResultWire>;
+    update(node: Node | PathLike, props: Properties, opts?: MutateOptions): Promise<void>;
+    create(cls: PathLike, at: PathLike, props?: Properties, opts?: MutateOptions): Promise<string>;
+    remove(node: Node | PathLike, opts?: MutateOptions): Promise<void>;
+    link(edge: EdgeIdentity & {
+        props?: Properties;
+    }, opts?: MutateOptions): Promise<string>;
+    unlink(edge: EdgeIdentity, opts?: MutateOptions): Promise<void>;
+    /**
+     * Apply a MANUAL optimistic overlay decoupled from any dispatch (§1.6 — the
+     * method-dispatch seam a patch arm can't express, e.g. `user::switchSpace`).
+     * SAFE MODE: only the display-safe arms (prop updates on cached nodes,
+     * deletes) predict; the caller dispatches whatever it likes, then `commit()`s
+     * (reconcile the touched shapes from the server, drop the overlay) or
+     * `rollback()`s.
+     */
+    overlay(build: (m: PatchBuilder) => void, opts?: {
+        scope?: string;
+    }): OptimisticOverlay;
+    /** An isolated handle for another scope (principal). No store sharing (§5.4). */
+    forScope(scope: string, api?: GraphApi): GraphMemory;
+    /** Release unobserved shapes past their ttl and GC unreachable entities. */
+    sweep(): void;
+}
+/** A live manual-overlay handle (see {@link GraphMemory.overlay}). */
+export interface OptimisticOverlay {
+    /**
+     * Reconcile the shapes this overlay touched from the server and drop the
+     * display prediction. The `result` param is retained for the §6.3 server-delta
+     * path; on Tier-0 it is unused (reconciliation is by refetch).
+     */
+    commit(result?: MutationResultWire): void;
+    /** Drop the overlay — the dispatch failed. */
+    rollback(): void;
+}
+/** Bind the memory onto a `GraphApi`. */
+export declare function createMemory(api: GraphApi, opts?: MemoryOptions): GraphMemory;
+//# sourceMappingURL=memory.d.ts.map

package/dist/store/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/store/memory.ts"],"names":[],"mappings":"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"}