@rindle/client 0.1.1 → 0.1.3

package/src/schema.ts

@@ -34,6 +34,19 @@ export interface TableMeta<N extends string = string, C extends AnyCols = AnyCol
   // `TableMeta` non-covariant in `C` and break `TableDef<concrete>` → `AnyTable`. Key
   // validity is enforced on the `primaryKey()` builder method (`K extends keyof C`).
   readonly primaryKey: readonly string[];
+  /** A **local-only** table (`201-LOCAL-ONLY-TABLES-DESIGN.md`): client-authoritative,
+   *  never synced/tracked/rebased. The single marker the whole design keys off (§4) — it is
+   *  immutable for the table's lifetime (N2) and never crosses the wire (C2). Absent ⇒ an
+   *  ordinary synced table. */
+  readonly local?: boolean;
+}
+
+/** Options for {@link table}. */
+export interface TableOptions {
+  /** Declare a {@link TableMeta.local local-only} table (selection state, draft text, view
+   *  prefs, scratch rows): client-authoritative, never synced or rebased. See
+   *  `201-LOCAL-ONLY-TABLES-DESIGN.md`. */
+  local?: boolean;
 }
 
 export type TableDef<N extends string, C extends AnyCols> = {
@@ -53,13 +66,14 @@ export type AnyTable = TableLike<AnyCols>;
  *  the schema instead of hand-maintaining a parallel twin. */
 export type Row<T extends AnyTable> = RowOf<T[typeof SCHEMA]["columns"]>;
 
-/** `table("issue").columns({ id: string(), … }).primaryKey("id")`. */
-export function table<N extends string>(name: N) {
+/** `table("issue").columns({ id: string(), … }).primaryKey("id")`. Pass `{ local: true }` for a
+ *  {@link TableMeta.local local-only} table (`201-LOCAL-ONLY-TABLES-DESIGN.md`). */
+export function table<N extends string>(name: N, opts?: TableOptions) {
   return {
     columns<C extends AnyCols>(cols: C) {
       return {
         primaryKey<K extends keyof C & string>(...keys: K[]): TableDef<N, C> {
-          return makeTableDef<N, C>({ name, columns: cols, primaryKey: keys });
+          return makeTableDef<N, C>({ name, columns: cols, primaryKey: keys, local: opts?.local });
         },
       };
     },
@@ -95,17 +109,83 @@ export interface Schema<S extends ColsMap = ColsMap> {
   readonly __cols: S;
 }
 
+/** Table-name prefixes reserved by the engine for SYNTHETIC tables — `__agg_<fnv>` aggregate
+ *  bases (`AGGREGATE-SYNC-DESIGN.md` §3.3) and `_rindle_*` system tables (e.g. the lmid table).
+ *  A user table (synced OR local) under one of these would shadow a synthetic source — and since
+ *  `registerTable` is idempotent-on-name and base tables register before synthetics, the later
+ *  synthetic registration would silently no-op and the agg join would read the user table as the
+ *  count (silent corruption, `201-LOCAL-ONLY-TABLES-DESIGN.md` N1). The ban makes that
+ *  structurally impossible — checked once, statically, at {@link createSchema}. */
+export const RESERVED_TABLE_PREFIXES = ["__agg_", "_rindle_"] as const;
+
+/** Whether `name` collides with an engine-reserved synthetic prefix ({@link RESERVED_TABLE_PREFIXES}). */
+export function isReservedTableName(name: string): boolean {
+  return RESERVED_TABLE_PREFIXES.some((p) => name.startsWith(p));
+}
+
 export function createSchema<const T extends readonly AnyTable[]>(opts: {
   tables: T;
 }): Schema<SchemaOf<T>> {
   const tables: Record<string, TableMeta> = {};
   for (const t of opts.tables) {
     const m = t[SCHEMA];
-    tables[m.name] = m;
+    addTableMeta(tables, m, "createSchema");
   }
   return { tables } as Schema<SchemaOf<T>>;
 }
 
+/** Extend a generated/synced schema with client-authoritative local-only tables.
+ *
+ *  This is the ergonomic path for SQL-first apps: keep `schema.gen.ts` fully generated, define
+ *  private UI tables in a tiny hand-written file, then hand the combined schema to the browser
+ *  client. The added tables MUST be `table(name, { local: true })`: `extendSchema` deliberately
+ *  refuses to append ordinary synced tables, because those need to come from daemon introspection
+ *  (`rindle schema gen`) so the server and client cannot drift. */
+export function extendSchema<S extends ColsMap, const T extends readonly AnyTable[]>(
+  base: Schema<S>,
+  opts: { tables: T },
+): Schema<S & SchemaOf<T>> {
+  const tables: Record<string, TableMeta> = { ...base.tables };
+  for (const t of opts.tables) {
+    const m = t[SCHEMA];
+    if (m.local !== true) {
+      throw new Error(
+        `extendSchema: table "${m.name}" is not local-only — synced tables must be generated from the daemon schema.`,
+      );
+    }
+    addTableMeta(tables, m, "extendSchema");
+  }
+  return { tables } as Schema<S & SchemaOf<T>>;
+}
+
+function addTableMeta(tables: Record<string, TableMeta>, m: TableMeta, caller: "createSchema" | "extendSchema") {
+  // N1: ban reserved synthetic prefixes for ANY user table (synced or local). One source per
+  // name, statically disjoint from the dynamic `__agg_*`/`_rindle_*` namespace.
+  if (isReservedTableName(m.name)) {
+    throw new Error(
+      `${caller}: table "${m.name}" uses a reserved prefix (${RESERVED_TABLE_PREFIXES.join(", ")}) — ` +
+        `these namespaces are owned by the engine's synthetic tables (201-LOCAL-ONLY-TABLES-DESIGN.md N1).`,
+    );
+  }
+  // N1/N2: one name → one source. A duplicate (incl. a local/synced name clash, since both
+  // register from this one array) is a genuine collision, not a silent overwrite.
+  if (Object.prototype.hasOwnProperty.call(tables, m.name)) {
+    throw new Error(`${caller}: duplicate table "${m.name}" — table names must be unique.`);
+  }
+  tables[m.name] = m;
+}
+
+/** Whether `table` is a {@link TableMeta.local local-only} table in `schema` (an unknown table
+ *  reads as non-local). The single locality predicate the backends key off. */
+export function isLocalTable<S extends ColsMap>(schema: Schema<S>, table: string): boolean {
+  return schema.tables[table]?.local === true;
+}
+
+/** The set of local-only table names in `schema` (`201-LOCAL-ONLY-TABLES-DESIGN.md` §4). */
+export function localTableNames<S extends ColsMap>(schema: Schema<S>): Set<string> {
+  return new Set(Object.keys(schema.tables).filter((n) => schema.tables[n].local));
+}
+
 // ----------------------------- relationships (FRAGMENT-COMPOSITION-DESIGN §4.2, named edges) -----
 //
 // A relationship is the correlation (`parent.col → child.col`) declared ONCE as a value, so `sub`,
@@ -171,11 +251,16 @@ export function tableSpec(meta: TableMeta): { columns: string[]; primaryKey: num
  *  normalized `hello` advertises (NORMALIZED-CHANGES-DESIGN.md §3). Used to validate a
  *  server hello against the CLIENT's own typed schema so a column-order / PK skew is caught
  *  instead of silently transposing positional cells (CRIT#4). Sorted by name for stable
- *  ordering. */
+ *  ordering.
+ *
+ *  Local-only tables are **omitted** (`201-LOCAL-ONLY-TABLES-DESIGN.md` E1): the client never
+ *  claims them to the server, the server never expects/ships them, and they stay out of the schema
+ *  fingerprint (`normalizedFp`) so a local table can't skew it vs. the server's. */
 export function normalizedTableSchemas<S extends ColsMap>(
   schema: Schema<S>,
 ): { name: string; columns: string[]; primaryKey: number[] }[] {
   return Object.keys(schema.tables)
+    .filter((name) => !schema.tables[name].local)
     .sort()
     .map((name) => ({ name, ...tableSpec(schema.tables[name]) }));
 }

package/src/ssr.ts

@@ -10,7 +10,7 @@
 // `useQuery` is byte-for-byte identical in both — only the injected backend (and whether a live
 // subscribe ever happens) differs.
 
-import type { Query } from "./query.ts";
+import { assertNoLocalTables, type Query } from "./query.ts";
 import type { ColsMap, Schema } from "./schema.ts";
 import { type AssembledNode, type DehydratedState, Store } from "./store.ts";
 import type { Backend, ChangeEvent, Mutation, QueryId, RemoteQuery } from "./types.ts";
@@ -74,10 +74,12 @@ export interface ServerStoreOptions {
  */
 export class ServerStore<S extends ColsMap> {
   readonly store: Store<S>;
+  private readonly schema: Schema<S>;
   private readonly opts: ServerStoreOptions;
 
   constructor(schema: Schema<S>, opts: ServerStoreOptions) {
     this.store = new Store(schema, new OneShotBackend());
+    this.schema = schema;
     this.opts = opts;
   }
 
@@ -85,6 +87,11 @@ export class ServerStore<S extends ColsMap> {
    *  Call once per query in the route loader, before the synchronous render. */
   async preload(query: Query<any, any, any>): Promise<void> {
     const ast = query.ast();
+    // E3 backstop: a local-only table must never be forwarded to the daemon. The `OneShotBackend`'s
+    // `registerQuery` is a no-op (no engine-side E3 check runs on the SSR path), and a query built
+    // from the LOCAL builder permits local tables — so the AST is re-checked here regardless of how
+    // it was built (201-LOCAL-ONLY-TABLES-DESIGN.md E3).
+    assertNoLocalTables(ast, this.schema);
     // Forward the AST (a direct-to-daemon backend reads it) plus the named identity when this came
     // from `defineQuery` (an API-tier backend resolves `(name, args)` → AST itself, never trusting
     // a client AST). The seed is keyed by the AST's `viewKey` either way, so the browser's

package/src/store.ts

@@ -11,7 +11,7 @@ import type { Ast } from "./ast.ts";
 import { stableKey } from "./key.ts";
 import { queries, type Query, type QueryRoot } from "./query.ts";
 import type { ColsMap, RowOf, Schema } from "./schema.ts";
-import type { Backend, ChangeEvent, ColType, Mutation, QueryId, RemoteQuery, WireSchema, WireValue } from "./types.ts";
+import type { Backend, ChangeEvent, ColType, Mutation, QueryId, RemoteQuery, ResultType, WireSchema, WireValue } from "./types.ts";
 import { type ArrayView, FlatArrayView, type SingularArrayView, SingularView, type ViewTypes } from "./view.ts";
 
 /** One query's SSR snapshot, keyed by its `viewKey` ({@link stableKey} of the AST): the
@@ -51,6 +51,39 @@ export interface CachedQueryView<Q extends Query<any, any, any>> {
   destroy(): void;
 }
 
+/** One live materialized view's read-only summary for a devtools pane (DEBUG-TOOLS-BROWSER-DESIGN
+ *  §4.2 — "surface, not instrument"). All fields are already held by the {@link Store}; this is the
+ *  single read-only accessor over the otherwise-private `views`/`asts` maps. */
+export interface QueryInspect {
+  /** The Store-assigned query id (also the backend's qid — the Store passes it straight through). */
+  qid: QueryId;
+  /** The query's AST (`Store.asts`), for the inspector's pretty-print / table-derivation. */
+  ast: Ast;
+  /** The view's SERVER-CHANNEL state (`unknown` while loading, `complete` once authoritative). */
+  resultType: ResultType;
+  /** Current materialized row count (`view.data.length`). */
+  rowCount: number;
+  /** A capped peek at the projected rows (reference-stable objects off the live view). */
+  sample: readonly unknown[];
+}
+
+/** A frozen snapshot of the Store's live query state for a devtools pane ({@link Store.__inspect}). */
+export interface StoreInspect {
+  queries: QueryInspect[];
+}
+
+/** A dev-only passive tap over the Store's per-query streams (DEBUG-TOOLS-BROWSER-DESIGN §6.2).
+ *  Registered via {@link Store.__attachDevtools}; it ADDS a listener and never displaces the
+ *  single `backend.onEvent`/`onResultType` handlers the Store already owns, so attaching devtools
+ *  cannot perturb the app. Both hooks are optional. */
+export interface StoreDevObserver {
+  /** The raw per-query {@link ChangeEvent} (hello / snapshot / batch) the Store just routed to its
+   *  view — the source of the devtools delta stream (§4.3). Fired AFTER the view has folded it. */
+  onDelta?(qid: QueryId, ev: ChangeEvent): void;
+  /** A per-query {@link ResultType} transition the Store just applied to its view (§4.2). */
+  onResultType?(qid: QueryId, rt: ResultType): void;
+}
+
 export class Store<S extends ColsMap> {
   /** Type-safe query entry: `store.query.issue.where.closed(false).materialize()`. */
   readonly query: QueryRoot<S>;
@@ -64,15 +97,26 @@ export class Store<S extends ColsMap> {
   // seeded for first paint; a seed is consumed (dropped) the moment its query's first live
   // `hello` lands, so later mounts don't flash stale SSR data.
   private readonly seeds = new Map<string, DehydratedQuery>();
+  // Dev-only devtools taps (DEBUG-TOOLS-BROWSER-DESIGN §6.2). `undefined` until the first
+  // `__attachDevtools`, so a production app that never attaches a pane pays one undefined-check per
+  // routed event and nothing else — there is no global singleton and no hot-path instrumentation.
+  private devObservers?: Set<StoreDevObserver>;
 
   constructor(schema: Schema<S>, backend: Backend) {
     this.schema = schema;
     this.backend = backend;
     this.backend.onEvent((qid, ev) => this.onEvent(qid, ev));
     // Route the backend's per-query lifecycle onto its view (`view.resultType`). Backends without a
-    // lifecycle omit `onResultType`, leaving every view `complete`.
-    this.backend.onResultType?.((qid, rt) => this.views.get(qid)?.setResultType(rt));
-    this.query = queries(this.schema, (query) => this.materialize(query)) as QueryRoot<S>;
+    // lifecycle omit `onResultType`, leaving every view `complete`. A devtools tap mirrors the
+    // transition (it never displaces this single handler).
+    this.backend.onResultType?.((qid, rt) => {
+      this.views.get(qid)?.setResultType(rt);
+      if (this.devObservers) for (const o of this.devObservers) o.onResultType?.(qid, rt);
+    });
+    // `store.query` is the LOCAL builder (201-LOCAL-ONLY-TABLES-DESIGN.md §5): it scopes over
+    // synced AND local-only tables, so a local query can join the two. Server/named queries use
+    // the synced-only `newQueryBuilder`, which excludes local tables.
+    this.query = queries(this.schema, (query) => this.materialize(query), { includeLocal: true }) as QueryRoot<S>;
   }
 
   /** Materialize any fluent query object. Named queries subscribe remotely by `(name,args)`;
@@ -113,6 +157,42 @@ export class Store<S extends ColsMap> {
    *  accepted them (local: applied; remote: sent). The resulting view updates flow back via
    *  the backend's event stream. */
   write(fn: (tx: WriteTx<S>) => void): Promise<void> {
+    return Promise.resolve(this.backend.mutate(this.collectMutations(fn)));
+  }
+
+  /** Direct-commit write to LOCAL-only tables (`201-LOCAL-ONLY-TABLES-DESIGN.md` §6): the
+   *  client-authoritative path for selection state, draft text, view prefs, scratch rows. It
+   *  bypasses the optimistic pending stack entirely — a local table is untracked, so it never
+   *  rebases, reverts, or waits on a server confirmation (it "moves on its own").
+   *
+   *  Rejects a synced/tracked table (M2): a direct write to one would be un-applied on the very
+   *  next server rewind. Local writes also must NOT live inside a replayable mutator (M1) — the
+   *  server runs the mutator from `args` alone and cannot see local tables; use this instead.
+   *  Same keyed `WriteTx` shape as {@link write}. `async` so the no-seam / M2 guards surface as a
+   *  REJECTED promise (the `Promise<void>` contract) rather than a synchronous throw that escapes a
+   *  caller's `.catch` and crashes the event handler / render frame. */
+  async writeLocal(fn: (tx: WriteTx<S>) => void): Promise<void> {
+    if (!this.backend.writeLocal) {
+      throw new Error(
+        "store.writeLocal: this backend has no local-write seam (local-only tables need the wasm/optimistic backend).",
+      );
+    }
+    const muts = this.collectMutations(fn);
+    // Defense in depth (M2): a clear Store-level rejection of any non-local table, before the
+    // backend's own chokepoint guard. Local writes are authoritative-for-themselves only.
+    for (const m of muts) {
+      if (!this.schema.tables[m.table]?.local) {
+        throw new Error(
+          `store.writeLocal: "${m.table}" is not a local-only table — use store.write or a named mutator (M2).`,
+        );
+      }
+    }
+    this.backend.writeLocal(muts);
+  }
+
+  /** Drain a keyed `WriteTx` callback into positional {@link Mutation}s (shared by
+   *  {@link write} / {@link writeLocal}; json columns stringified, rows in column order). */
+  private collectMutations(fn: (tx: WriteTx<S>) => void): Mutation[] {
     const muts: Mutation[] = [];
     const tx = {
       add: (t: string, row: Record<string, unknown>) =>
@@ -123,7 +203,7 @@ export class Store<S extends ColsMap> {
         muts.push({ op: "edit", table: t, old: this.positionalize(t, o), new: this.positionalize(t, n) }),
     } as unknown as WriteTx<S>;
     fn(tx);
-    return Promise.resolve(this.backend.mutate(muts));
+    return muts;
   }
 
   // --- SSR (SSR-DESIGN.md §6) ---------------------------------------------------
@@ -207,7 +287,16 @@ export class Store<S extends ColsMap> {
       }
       baseDestroy();
     };
-    this.backend.registerQuery(qid, ast, remote);
+    // If the backend rejects the registration (E3: a remote query naming a local-only table), roll
+    // back the per-qid state we just created — otherwise the view + ast entry leak (the caller never
+    // gets a handle to `destroy()` them, since the throw aborts before we return).
+    try {
+      this.backend.registerQuery(qid, ast, remote);
+    } catch (e) {
+      this.views.delete(qid);
+      this.asts.delete(qid);
+      throw e;
+    }
     // SSR first paint (SSR-DESIGN.md §6): if this AST was preloaded/hydrated, seed the view now.
     // A synchronous backend (wasm) already reset the view above, so its live data wins and the
     // seed is inert; an async backend (ws) leaves it PENDING, so the seed shows until `hello`.
@@ -246,6 +335,43 @@ export class Store<S extends ColsMap> {
     } else {
       this.views.get(qid)?.applyChanges(ev.events);
     }
+    // Mirror the raw delta to any devtools tap, AFTER the view has folded it (so a pane re-reading
+    // `__inspect` sees the post-apply state). No-op (one undefined-check) when no pane is attached.
+    if (this.devObservers) for (const o of this.devObservers) o.onDelta?.(qid, ev);
+  }
+
+  // --- dev-only introspection (DEBUG-TOOLS-BROWSER-DESIGN §2/§6.2) --------------
+  // A single read-only accessor + a passive tap per the design's "surface, not instrument" rule.
+  // Only ever called by `@rindle/devtools` (imported in dev); inert otherwise.
+
+  /** Register a devtools {@link StoreDevObserver}; returns a detach function. Multiple panes may
+   *  attach. The observer is ADDITIVE — it does not touch the backend's single handler slots. */
+  __attachDevtools(observer: StoreDevObserver): () => void {
+    (this.devObservers ??= new Set()).add(observer);
+    return () => {
+      this.devObservers?.delete(observer);
+    };
+  }
+
+  /** A read-only snapshot of every live materialized view (DEBUG-TOOLS-BROWSER-DESIGN §4.2): its
+   *  qid, AST, {@link ResultType}, row count, and a capped row sample. Built fresh on each call from
+   *  the live `views`/`asts` maps — never cached, never mutating. `sampleRows` caps the per-query
+   *  peek (default 50) so a large view doesn't bloat the snapshot. */
+  __inspect(sampleRows = 50): StoreInspect {
+    const queries: QueryInspect[] = [];
+    for (const [qid, view] of this.views) {
+      const ast = this.asts.get(qid);
+      if (!ast) continue; // a view mid-teardown (ast already dropped) — skip
+      const data = view.data;
+      queries.push({
+        qid,
+        ast,
+        resultType: view.resultType,
+        rowCount: data.length,
+        sample: sampleRows >= data.length ? data : data.slice(0, sampleRows),
+      });
+    }
+    return { queries };
   }
 
   private columns(table: string): Record<string, { type: ColType }> {

package/src/types.ts

@@ -148,6 +148,11 @@ export interface Backend {
   releaseRemoteQuery?(queryId: QueryId): void;
   /** Local: applies now (changes flow back on the stream). Remote: sends to the server. */
   mutate(mutations: Mutation[]): Promise<void>;
+  /** Optional DIRECT-COMMIT path for LOCAL-only tables (`201-LOCAL-ONLY-TABLES-DESIGN.md` §6):
+   *  applies the writes straight to the engine, OUTSIDE the optimistic pending stack (a local
+   *  table is untracked, so it never rebases). The backend rejects any synced/tracked table (M2).
+   *  Backends with no local-table support (a plain remote sync backend) omit it. */
+  writeLocal?(mutations: Mutation[]): void;
   onEvent(handler: (queryId: QueryId, event: ChangeEvent) => void): void;
   /** Optional: the backend pushes per-query {@link ResultType} changes here and the core routes
    *  each to the matching view (so `view.resultType` tracks it). Backends with no lifecycle (the