@rindle/react 0.1.3 → 0.2.0

package/src/index.ts

@@ -8,16 +8,53 @@ import {
   useSyncExternalStore,
 } from "react";
 import type { ReactNode } from "react";
-import { stableKey } from "@rindle/client";
-import type { CachedQueryView, ColsMap, Fragment, FragmentRef, Query, ResultType, Store } from "@rindle/client";
+import {
+  createLocalFragmentRefForTable,
+  fragmentAst,
+  isFragment,
+  isFragmentRelationship,
+  localQueryReadAst,
+  localFragmentReadAst,
+  localRootFragmentRefsAst,
+  queryFromAst,
+  stableKey,
+  tableMeta,
+} from "@rindle/client";
+import type {
+  AnyQuery,
+  Ast,
+  CachedQueryView,
+  ColsMap,
+  Fragment,
+  FragmentData,
+  FragmentCoverage,
+  FragmentRef,
+  LitValue,
+  LocalFragmentRef,
+  NamedQuery,
+  QueryLocalData,
+  ResultType,
+  Store,
+} from "@rindle/client";
 
-type AnyQuery = Query<any, any, any>;
 type AnyView = ReturnType<AnyQuery["materialize"]>;
+type AnyFragment = Fragment<any, any, any, any>;
+type AnyNamedQuery = NamedQuery<any, readonly unknown[], AnyQuery>;
 
 export type QueryData<Q extends AnyQuery> = ReturnType<Q["materialize"]>["data"];
+export type RootData<Q extends AnyQuery> = QueryLocalData<Q>;
+export type RootRefData<Q extends AnyQuery, F extends Fragment<any, any, any, any>> =
+  QueryData<Q> extends readonly unknown[] ? readonly FragmentRef<F>[] : FragmentRef<F> | null;
+export interface RootDetails {
+  readonly status: ResultType;
+}
+export type RootResult<Q extends AnyQuery> = readonly [data: RootData<Q>, details: RootDetails];
+export type RootRefResult<Q extends AnyQuery, F extends Fragment<any, any, any, any>> =
+  readonly [data: RootRefData<Q, F>, details: RootDetails];
 
 export type { ResultType } from "@rindle/client";
-export type { Fragment, FragmentRef } from "@rindle/client";
+export type { Fragment, FragmentData, FragmentRef } from "@rindle/client";
+export { fragmentKey } from "@rindle/client";
 
 export interface RindleProps<S extends ColsMap = ColsMap> {
   store: Store<S>;
@@ -35,6 +72,11 @@ interface QueryLease {
   viewKey: string;
 }
 
+interface SyncLease {
+  id: number;
+  coverageKey: string;
+}
+
 interface MaterializedLease extends QueryLease {
   view: AnyView;
   remote: boolean;
@@ -71,10 +113,12 @@ const EMPTY_ARRAY: readonly never[] = Object.freeze([]);
 class RindleContextValue {
   readonly store: Store<ColsMap>;
   readonly cache: QueryCache;
+  readonly syncCache: SyncQueryCache;
 
   constructor(store: Store<ColsMap>) {
     this.store = store;
     this.cache = new QueryCache(store);
+    this.syncCache = new SyncQueryCache(store);
   }
 }
 
@@ -160,24 +204,596 @@ export function useQueryStatus(query: AnyQuery): ResultType {
   return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }
 
+/** Retain a named server query for normalized/local-first sync coverage without subscribing React
+ *  to that query's broad result tree. The returned value is lifecycle state only; it is `unknown`
+ *  until the backend reports that the retained coverage has hydrated. */
+export function useSyncQuery(query: AnyQuery): ResultType {
+  const ctx = useRindleContext();
+  const descriptor = useMemo(() => describeQuery(query), [query]);
+  const queryRef = useRef(query);
+  queryRef.current = query;
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      const lease = ctx.syncCache.retain(descriptor.leaseKey, queryRef.current);
+      const unsubscribe = ctx.syncCache.subscribe(descriptor.leaseKey, onStoreChange);
+      return () => {
+        unsubscribe();
+        ctx.syncCache.release(lease);
+      };
+    },
+    [ctx.syncCache, descriptor.leaseKey],
+  );
+
+  const getSnapshot = useCallback(() => {
+    const live = ctx.syncCache.resultType(descriptor.leaseKey);
+    return live === "unknown" && ctx.cache.serverResultType(descriptor.viewKey) === "complete" ? "complete" : live;
+  }, [ctx.cache, ctx.syncCache, descriptor.leaseKey, descriptor.viewKey]);
+
+  const getServerSnapshot = useCallback(
+    () => ctx.cache.serverResultType(descriptor.viewKey),
+    [ctx.cache, descriptor.viewKey],
+  );
+
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+
+/** Run a named root query and expose its local React-facing data. Fragment child relationships are
+ *  refs, so child components can keep owning their own local reads. Passing a root fragment as the
+ *  final argument switches the result to opaque root refs for that fragment. */
+export function useRoot<Q extends AnyQuery>(query: Q): RootResult<Q>;
+export function useRoot<Q extends AnyQuery, F extends AnyFragment>(
+  query: Q,
+  fragment: F,
+): RootRefResult<Q, F>;
+export function useRoot<Q extends AnyQuery>(
+  query: NamedQuery<void, [], Q>,
+): RootResult<Q>;
+export function useRoot<Q extends AnyQuery, F extends AnyFragment>(
+  query: NamedQuery<void, [], Q>,
+  fragment: F,
+): RootRefResult<Q, F>;
+export function useRoot<Args, Ctx extends readonly unknown[], Q extends AnyQuery>(
+  query: NamedQuery<Args, Ctx, Q>,
+  args: Args,
+  ...ctx: Ctx
+): RootResult<Q>;
+export function useRoot<Args, Ctx extends readonly unknown[], Q extends AnyQuery, F extends AnyFragment>(
+  query: NamedQuery<Args, Ctx, Q>,
+  args: Args,
+  ...ctxAndFragment: [...ctx: Ctx, fragment: F]
+): RootRefResult<Q, F>;
+export function useRoot<Q extends AnyQuery, F extends AnyFragment>(
+  queryOrNamed: Q | AnyNamedQuery,
+  ...args: unknown[]
+): RootResult<Q> | RootRefResult<Q, F> {
+  const { query, fragment } = resolveRootQueryInput(queryOrNamed, args, "useRoot");
+  const stableQuery = useStableQuery(query as Q);
+  const status = useSyncQuery(stableQuery);
+  const data = fragment === undefined
+    ? useLocalRootQueryData(stableQuery)
+    : useRootRefData(stableQuery, fragment as F);
+  const details = useMemo<RootDetails>(() => ({ status }), [status]);
+  return useMemo(
+    () => [data, details] as const,
+    [data, details],
+  ) as RootResult<Q> | RootRefResult<Q, F>;
+}
+
+function resolveRootQueryInput(
+  queryOrNamed: AnyQuery | AnyNamedQuery,
+  args: readonly unknown[],
+  hookName: string,
+): { query: AnyQuery; fragment?: AnyFragment } {
+  const last = args[args.length - 1];
+  const fragment = isFragment(last) ? last as AnyFragment : undefined;
+  const queryArgs = fragment === undefined ? args : args.slice(0, -1);
+  if (isNamedQuery(queryOrNamed)) {
+    const query = queryArgs.length === 0
+      ? (queryOrNamed as unknown as () => AnyQuery)()
+      : queryOrNamed(queryArgs[0], ...queryArgs.slice(1));
+    return { query, fragment };
+  }
+  if (queryArgs.length !== 0) throw new Error(`${hookName}(): expected (query) or (query, fragment).`);
+  return { query: queryOrNamed, fragment };
+}
+
+function isNamedQuery(v: unknown): v is AnyNamedQuery {
+  return typeof v === "function"
+    && typeof (v as Partial<AnyNamedQuery>).queryName === "string"
+    && typeof (v as Partial<AnyNamedQuery>).resolve === "function";
+}
+
+function useStableQuery<Q extends AnyQuery>(query: Q): Q {
+  const descriptor = describeQuery(query);
+  const ref = useRef<{ leaseKey: string; query: Q } | undefined>(undefined);
+  if (ref.current === undefined || ref.current.leaseKey !== descriptor.leaseKey) {
+    ref.current = { leaseKey: descriptor.leaseKey, query };
+  }
+  return ref.current.query;
+}
+
+function useLocalRootQueryData<Q extends AnyQuery>(
+  query: Q,
+): RootData<Q> {
+  const ctx = useRindleContext();
+  const descriptor = useMemo(() => describeQuery(query), [query]);
+  const ast = useMemo(
+    () => localQueryReadAst(query, (table) => ctx.store.primaryKeyFor(table)),
+    [ctx.store, query],
+  );
+  const localQuery = useMemo(() => queryFromAst(ast), [ast]);
+  const localDescriptor = useMemo(() => describeQuery(localQuery), [localQuery]);
+  const projection = useMemo(
+    () => new LocalFragmentProjection(ast, { key: descriptor.leaseKey, query }, (table) => ctx.store.primaryKeyFor(table)),
+    [ctx.store, ast, descriptor.leaseKey, query],
+  );
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      const localLease = ctx.cache.retain(localDescriptor.viewKey, localQuery);
+      const unsubscribeLocal = ctx.cache.subscribe(localDescriptor.viewKey, onStoreChange);
+      return () => {
+        unsubscribeLocal();
+        ctx.cache.release(localLease);
+      };
+    },
+    [ctx.cache, localDescriptor.viewKey, localQuery],
+  );
+
+  // Stale-while-revalidate: render whatever the local IVM view already holds (synced rows,
+  // optimistic writes, partially-covered rows) rather than blanking to empty until the server
+  // confirms coverage. `status` (from useSyncQuery) stays a SEPARATE signal callers can gate on;
+  // the data itself never waits on the round-trip, so navigating to a view that's locally warm
+  // shows rows immediately instead of flashing a loading state. (Eviction-on-release still drops
+  // a cold view; a release TTL to keep views warm across nav is future work.)
+  const getSnapshot = useCallback(() => {
+    if (ctx.cache.serverResultType(descriptor.viewKey) === "complete") {
+      return projectLocalRootSnapshot(ctx.cache.serverSnapshot(descriptor.viewKey, descriptor.one), descriptor.one, projection);
+    }
+    return projectLocalRootSnapshot(ctx.cache.snapshot(localDescriptor.viewKey, descriptor.one), descriptor.one, projection);
+  }, [ctx.cache, descriptor.one, descriptor.viewKey, localDescriptor.viewKey, projection]);
+
+  const getServerSnapshot = useCallback(
+    () => projectLocalRootSnapshot(ctx.cache.serverSnapshot(descriptor.viewKey, descriptor.one), descriptor.one, projection),
+    [ctx.cache, descriptor.one, descriptor.viewKey, projection],
+  );
+
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot) as RootData<Q>;
+}
+
+function useRootRefData<Q extends AnyQuery, F extends Fragment<any, any, any, any>>(
+  query: Q,
+  fragment: F,
+): RootRefData<Q, F> {
+  const ctx = useRindleContext();
+  const descriptor = useMemo(() => describeQuery(query), [query]);
+  const ast = useMemo(
+    () => localRootFragmentRefsAst(fragment, query, (table) => ctx.store.primaryKeyFor(table)),
+    [ctx.store, fragment, query],
+  );
+  const localQuery = useMemo(() => queryFromAst(ast), [ast]);
+  const localDescriptor = useMemo(() => describeQuery(localQuery), [localQuery]);
+  const projection = useMemo(
+    () => new RootRefProjection(fragment, { key: descriptor.leaseKey, query }, (table) => ctx.store.primaryKeyFor(table)),
+    [ctx.store, descriptor.leaseKey, fragment, query],
+  );
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      const localLease = ctx.cache.retain(localDescriptor.viewKey, localQuery);
+      const unsubscribeLocal = ctx.cache.subscribe(localDescriptor.viewKey, onStoreChange);
+      return () => {
+        unsubscribeLocal();
+        ctx.cache.release(localLease);
+      };
+    },
+    [ctx.cache, localDescriptor.viewKey, localQuery],
+  );
+
+  // Stale-while-revalidate (see useLocalRootQueryData): the root rows render from the live local
+  // view as soon as it holds anything; `status` is the separate axis for "server-authoritative yet".
+  const getSnapshot = useCallback(() => {
+    if (ctx.cache.serverResultType(descriptor.viewKey) === "complete") {
+      return projectRootRefSnapshot(ctx.cache.serverSnapshot(descriptor.viewKey, descriptor.one), descriptor.one, projection);
+    }
+    const raw = ctx.cache.snapshot(localDescriptor.viewKey, descriptor.one);
+    return descriptor.one ? projection.projectOne(raw) : projection.projectMany(raw);
+  }, [ctx.cache, descriptor.one, descriptor.viewKey, localDescriptor.viewKey, projection]);
+
+  const getServerSnapshot = useCallback(
+    () => projectRootRefSnapshot(ctx.cache.serverSnapshot(descriptor.viewKey, descriptor.one), descriptor.one, projection),
+    [ctx.cache, descriptor.one, descriptor.viewKey, projection],
+  );
+
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot) as RootRefData<Q, F>;
+}
+
 /**
- * Read a {@link Fragment}'s slice off the shared root view (FRAGMENT-COMPOSITION-DESIGN.md §7).
+ * Read a {@link Fragment}'s local data from an opaque ref.
  *
- * The waterfall-free contract: the ROOT component `useQuery`s the composed query (every child
- * fragment spread into it), and every descendant calls `useFragment` — a PURE READ of the
- * already-projected node at this fragment's alias — instead of opening its own `useQuery`. So a
- * whole component tree resolves through the ONE query the root opened, with no request waterfall;
- * a descendant that opens its own `useQuery` reintroduces the waterfall at that boundary.
+ * The query boundary calls {@link useRoot} with a fragment argument to retain the full named
+ * coverage query and receive root refs. Descendants call `useFragment` with those refs (or child
+ * refs returned by a parent fragment read) to open narrow local-only reads for the fields their
+ * fragment owns.
  *
- * Phase 0 is a typed pass-through: `ref` already IS the projected node (the parent got it from
- * `useQuery` and handed the slice down), so this returns it typed as the fragment's
- * {@link FragmentRef}. `fragment` declares *which* selection this component reads (co-location +
- * the seam masking plugs into); masking (Phase 2) narrows the returned shape with no call-site
- * change. Not a subscription — it adds no lease and never re-renders on its own.
+ * `ref` is an opaque token created by {@link useRoot} or returned from another local fragment read.
+ * The hook opens a narrow local-only query for this exact fragment and keeps the root coverage
+ * lease retained while mounted. Passing a legacy projected data object is unsupported.
  */
-export function useFragment<F extends Fragment<any, any, any>>(fragment: F, ref: FragmentRef<F>): FragmentRef<F> {
-  void fragment;
-  return ref;
+export function useFragment<F extends Fragment<any, any, any, any>>(
+  fragment: F,
+  ref: FragmentRef<F> | null | undefined,
+): FragmentData<F> | null {
+  return useLocalFragment(fragment, ref);
+}
+
+function useLocalFragment<F extends Fragment<any, any, any, any>>(
+  fragment: F,
+  ref: LocalFragmentRef<F> | null | undefined,
+): FragmentData<F> | null {
+  const ctx = useRindleContext();
+  const coverage = ref?.coverage;
+  const coverageDescriptor = useMemo(() => (coverage ? describeQuery(coverage.query) : undefined), [coverage]);
+  const ast = useMemo(
+    () => (ref ? localFragmentReadAst(fragment, ref, (table) => ctx.store.primaryKeyFor(table)) : undefined),
+    [ctx.store, fragment, ref],
+  );
+  const query = useMemo(() => (ast ? queryFromAst(ast) : undefined), [ast]);
+  const descriptor = useMemo(() => (query ? describeQuery(query) : undefined), [query]);
+  const projection = useMemo(
+    () => (coverage ? new LocalFragmentProjection(fragmentAst(fragment), coverage, (table) => ctx.store.primaryKeyFor(table)) : undefined),
+    [ctx.store, coverage, fragment],
+  );
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      if (!coverage || !descriptor || !query) return () => {};
+      const syncLease = ctx.syncCache.retain(coverage.key, coverage.query);
+      const localLease = ctx.cache.retain(descriptor.viewKey, query);
+      const unsubscribeSync = ctx.syncCache.subscribe(coverage.key, onStoreChange);
+      const unsubscribeLocal = ctx.cache.subscribe(descriptor.viewKey, onStoreChange);
+      return () => {
+        unsubscribeLocal();
+        unsubscribeSync();
+        ctx.cache.release(localLease);
+        ctx.syncCache.release(syncLease);
+      };
+    },
+    [ctx.cache, ctx.syncCache, coverage, descriptor, query],
+  );
+
+  // Stale-while-revalidate (see useLocalRootQueryData): project the fragment's local view as soon
+  // as the row exists locally instead of returning null until its coverage is server-complete —
+  // otherwise every nested fragment (UserBadge, TagChip, CommentCard, …) flashes empty for a
+  // round-trip on each navigation. A field not yet synced simply reads absent, not "loading".
+  const getSnapshot = useCallback(() => {
+    if (!coverage || !descriptor || !projection) return null;
+    if (coverageDescriptor && ctx.cache.serverResultType(coverageDescriptor.viewKey) === "complete") {
+      return projectFragmentSeed(ctx, coverage.query.ast(), coverageDescriptor, ref, projection);
+    }
+    const data = projection.project(ctx.cache.snapshot(descriptor.viewKey, true));
+    return data as FragmentData<F> | null;
+  }, [ctx, coverage, coverageDescriptor, descriptor, projection, ref]);
+
+  const getServerSnapshot = useCallback(
+    () => projectFragmentSeed(ctx, coverage?.query.ast(), coverageDescriptor, ref, projection),
+    [ctx, coverage, coverageDescriptor, projection, ref],
+  );
+
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+
+function projectRootRefSnapshot(raw: unknown, one: boolean, projection: RootRefProjection): unknown {
+  return one ? projection.projectOne(raw) : projection.projectMany(raw);
+}
+
+function projectLocalRootSnapshot(raw: unknown, one: boolean, projection: LocalFragmentProjection): unknown {
+  return one ? projection.projectOne(raw) : projection.projectMany(raw);
+}
+
+function projectFragmentSeed<F extends Fragment<any, any, any, any>>(
+  ctx: RindleContextValue,
+  coverageAst: Ast | undefined,
+  coverageDescriptor: QueryDescriptor | undefined,
+  ref: LocalFragmentRef<F> | null | undefined,
+  projection: LocalFragmentProjection | undefined,
+): FragmentData<F> | null {
+  if (!coverageAst || !coverageDescriptor || !ref || !projection) return null;
+  const raw = ctx.cache.serverSnapshot(coverageDescriptor.viewKey, coverageDescriptor.one);
+  const row = findFragmentSeedRow(coverageAst, raw, ref.table, ref.pk, (table) => ctx.store.primaryKeyFor(table));
+  return projection.project(row) as FragmentData<F> | null;
+}
+
+function findFragmentSeedRow(
+  ast: Ast,
+  raw: unknown,
+  table: string,
+  pk: Readonly<Record<string, LitValue>>,
+  primaryKeyFor: (table: string) => readonly string[],
+): unknown {
+  if (Array.isArray(raw)) {
+    for (const row of raw) {
+      const found = findFragmentSeedRowInObject(ast, row, table, pk, primaryKeyFor);
+      if (found !== null) return found;
+    }
+    return null;
+  }
+  return findFragmentSeedRowInObject(ast, raw, table, pk, primaryKeyFor);
+}
+
+function findFragmentSeedRowInObject(
+  ast: Ast,
+  raw: unknown,
+  table: string,
+  pk: Readonly<Record<string, LitValue>>,
+  primaryKeyFor: (table: string) => readonly string[],
+): unknown {
+  if (raw === null || raw === undefined || typeof raw !== "object") return null;
+  const row = raw as Record<string, unknown>;
+  if (ast.table === table && rowMatchesPk(row, pk, primaryKeyFor(table))) return row;
+  for (const rel of ast.related ?? []) {
+    if (rel.subquery.aggregate !== undefined) continue;
+    const alias = rel.subquery.alias;
+    if (alias === undefined) continue;
+    const found = findFragmentSeedRow(rel.subquery, row[alias], table, pk, primaryKeyFor);
+    if (found !== null) return found;
+  }
+  return null;
+}
+
+function rowMatchesPk(row: Record<string, unknown>, pk: Readonly<Record<string, LitValue>>, primaryKey: readonly string[]): boolean {
+  for (const col of primaryKey) {
+    if (!Object.prototype.hasOwnProperty.call(row, col)) return false;
+    if (stableKey(row[col]) !== stableKey(pk[col])) return false;
+  }
+  return true;
+}
+
+class LocalFragmentProjection {
+  private readonly manyCache = new WeakMap<object, readonly unknown[]>();
+  private readonly cache = new WeakMap<object, unknown>();
+  private readonly refCache = new Map<string, LocalFragmentRef>();
+  private readonly ast: Ast;
+  private readonly coverage: FragmentCoverage;
+  private readonly primaryKeyFor: (table: string) => readonly string[];
+
+  constructor(
+    ast: Ast,
+    coverage: FragmentCoverage,
+    primaryKeyFor: (table: string) => readonly string[],
+  ) {
+    this.ast = ast;
+    this.coverage = coverage;
+    this.primaryKeyFor = primaryKeyFor;
+  }
+
+  projectOne(raw: unknown): unknown {
+    return this.project(raw);
+  }
+
+  projectMany(raw: unknown): readonly unknown[] {
+    if (!Array.isArray(raw)) return EMPTY_ARRAY;
+    const cached = this.manyCache.get(raw);
+    if (cached) return cached;
+    const out = raw.map((row) => this.project(row));
+    this.manyCache.set(raw, out);
+    return out;
+  }
+
+  project(raw: unknown): unknown {
+    if (raw === null || raw === undefined || typeof raw !== "object") return null;
+    const cached = this.cache.get(raw);
+    if (cached !== undefined) return cached;
+
+    const out = this.projectRow(this.ast, raw);
+    this.cache.set(raw, out);
+    return out;
+  }
+
+  private projectRow(ast: Ast, raw: unknown): unknown {
+    if (raw === null || raw === undefined || typeof raw !== "object") return null;
+    const row = raw as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    const relationshipAliases = new Set((ast.related ?? []).map((rel) => rel.subquery.alias).filter((a): a is string => a !== undefined));
+    if (ast.select === undefined) {
+      for (const [key, value] of Object.entries(row)) {
+        if (!relationshipAliases.has(key)) out[key] = value;
+      }
+    } else {
+      for (const col of ast.select) {
+        if (Object.prototype.hasOwnProperty.call(row, col)) out[col] = row[col];
+      }
+    }
+
+    for (const rel of ast.related ?? []) {
+      const alias = rel.subquery.alias;
+      if (alias === undefined) continue;
+      const value = row[alias];
+      if (rel.subquery.aggregate !== undefined) {
+        out[alias] = value;
+        continue;
+      }
+      out[alias] = isFragmentRelationship(rel) ? this.projectRelatedRefs(rel.subquery, value) : this.projectInline(rel.subquery, value);
+    }
+
+    return out;
+  }
+
+  private projectInline(childAst: Ast, value: unknown): unknown {
+    if (Array.isArray(value)) return value.map((row) => this.projectRow(childAst, row));
+    if (value === null || value === undefined) return value ?? null;
+    return this.projectRow(childAst, value);
+  }
+
+  private projectRelatedRefs(childAst: Ast, value: unknown): unknown {
+    if (Array.isArray(value)) return value.map((row) => this.refForRow(childAst.table, row));
+    if (value === null || value === undefined) return value ?? null;
+    return this.refForRow(childAst.table, value);
+  }
+
+  private refForRow(table: string, value: unknown): LocalFragmentRef {
+    if (value === null || typeof value !== "object") {
+      throw new Error(`useFragment(): cannot build a local fragment ref for "${table}" from a non-object row.`);
+    }
+    const row = value as Record<string, unknown>;
+    const pk: Record<string, LitValue> = {};
+    for (const col of this.primaryKeyFor(table)) {
+      if (!Object.prototype.hasOwnProperty.call(row, col)) {
+        throw new Error(`useFragment(): local relationship row for "${table}" is missing primary key column "${col}".`);
+      }
+      pk[col] = row[col] as LitValue;
+    }
+    const key = stableKey({ table, pk });
+    const cached = this.refCache.get(key);
+    if (cached) return cached;
+    const ref = createLocalFragmentRefForTable(table, pk, this.coverage);
+    this.refCache.set(key, ref);
+    return ref;
+  }
+}
+
+class RootRefProjection {
+  private readonly cache = new WeakMap<object, readonly LocalFragmentRef[]>();
+  private readonly rowCache = new WeakMap<object, LocalFragmentRef>();
+  private readonly keyCache = new Map<string, LocalFragmentRef>();
+  private readonly table: string;
+  private readonly coverage: FragmentCoverage;
+  private readonly primaryKeyFor: (table: string) => readonly string[];
+
+  constructor(
+    fragment: Fragment<any, any, any>,
+    coverage: FragmentCoverage,
+    primaryKeyFor: (table: string) => readonly string[],
+  ) {
+    this.table = tableMeta(fragment.table).name;
+    this.coverage = coverage;
+    this.primaryKeyFor = primaryKeyFor;
+  }
+
+  projectOne(raw: unknown): LocalFragmentRef | null {
+    if (raw === null || raw === undefined) return null;
+    return this.refForRow(raw);
+  }
+
+  projectMany(raw: unknown): readonly LocalFragmentRef[] {
+    if (!Array.isArray(raw)) return EMPTY_ARRAY as readonly LocalFragmentRef[];
+    const cached = this.cache.get(raw);
+    if (cached) return cached;
+    const refs = raw.map((row) => this.refForRow(row));
+    this.cache.set(raw, refs);
+    return refs;
+  }
+
+  private refForRow(value: unknown): LocalFragmentRef {
+    if (value === null || typeof value !== "object") {
+      throw new Error(`useRoot(): cannot build a fragment ref for "${this.table}" from a non-object row.`);
+    }
+    const cached = this.rowCache.get(value);
+    if (cached) return cached;
+    const row = value as Record<string, unknown>;
+    const pk: Record<string, LitValue> = {};
+    for (const col of this.primaryKeyFor(this.table)) {
+      if (!Object.prototype.hasOwnProperty.call(row, col)) {
+        throw new Error(`useRoot(): local root row for "${this.table}" is missing primary key column "${col}".`);
+      }
+      pk[col] = row[col] as LitValue;
+    }
+    const key = stableKey({ table: this.table, pk });
+    const existing = this.keyCache.get(key);
+    if (existing) {
+      this.rowCache.set(value, existing);
+      return existing;
+    }
+    const ref = createLocalFragmentRefForTable(this.table, pk, this.coverage);
+    this.keyCache.set(key, ref);
+    this.rowCache.set(value, ref);
+    return ref;
+  }
+}
+
+interface SyncCacheEntry {
+  handle: SyncQueryHandle;
+  leases: SyncLease[];
+  listeners: Set<() => void>;
+  unsubscribe: () => void;
+}
+
+interface SyncQueryHandle {
+  readonly resultType: ResultType;
+  subscribe(listener: () => void): () => void;
+  release(): void;
+}
+
+export class SyncQueryCache {
+  private readonly entries = new Map<string, SyncCacheEntry>();
+  private nextLeaseId = 1;
+  private readonly store: Store<ColsMap>;
+
+  constructor(store: Store<ColsMap>) {
+    this.store = store;
+  }
+
+  retain(coverageKey: string, query: AnyQuery): SyncLease {
+    let entry = this.entries.get(coverageKey);
+    if (!entry) {
+      const handle = this.createHandle(query);
+      entry = {
+        handle,
+        leases: [],
+        listeners: new Set(),
+        unsubscribe: () => {},
+      };
+      entry.unsubscribe = handle.subscribe(() => {
+        for (const listener of entry!.listeners) listener();
+      });
+      this.entries.set(coverageKey, entry);
+    }
+    const lease = { id: this.nextLeaseId++, coverageKey };
+    entry.leases.push(lease);
+    return lease;
+  }
+
+  release(lease: SyncLease): void {
+    const entry = this.entries.get(lease.coverageKey);
+    if (!entry) return;
+    const index = entry.leases.findIndex((l) => l.id === lease.id);
+    if (index < 0) return;
+    entry.leases.splice(index, 1);
+    if (entry.leases.length > 0) return;
+    entry.unsubscribe();
+    entry.handle.release();
+    this.entries.delete(lease.coverageKey);
+  }
+
+  subscribe(coverageKey: string, listener: () => void): () => void {
+    const entry = this.entries.get(coverageKey);
+    if (!entry) return () => {};
+    entry.listeners.add(listener);
+    return () => {
+      entry.listeners.delete(listener);
+    };
+  }
+
+  resultType(coverageKey: string): ResultType {
+    return this.entries.get(coverageKey)?.handle.resultType ?? "unknown";
+  }
+
+  size(): number {
+    return this.entries.size;
+  }
+
+  private createHandle(query: AnyQuery): SyncQueryHandle {
+    if (this.store.canRetainRemoteQueries()) return this.store.retainSyncQuery(query);
+    const view = this.store.materialize(query) as AnyView;
+    return {
+      get resultType() {
+        return view.resultType;
+      },
+      subscribe: (listener: () => void) => view.subscribe(listener),
+      release: () => view.destroy(),
+    };
+  }
 }
 
 export class QueryCache {