@spooky-sync/core 0.0.1-canary.240 → 0.0.1-canary.241

package/src/testing/run-pure.ts

@@ -0,0 +1,128 @@
+import { webcrypto } from 'node:crypto';
+import type { Effect, EffectKind, Settled } from '../kernel/effects';
+import type { OutEvent, RuntimeEvent } from '../kernel/events';
+import type { Saga } from '../kernel/saga';
+import { runSaga } from '../kernel/saga';
+import type { ClientState } from '../state/client-state';
+import { emptyState } from '../state/client-state';
+
+export type EffectHandler = (effect: Effect, ctx: PureContext) => unknown | Promise<unknown>;
+
+export interface PureContext {
+  state: ClientState;
+  now: number;
+  log: Effect[];
+  timers: Map<string, { ms: number; event: RuntimeEvent }>;
+  emitted: OutEvent[];
+  dispatched: RuntimeEvent[];
+  ids: number;
+}
+
+export interface RunPureOptions {
+  state?: ClientState;
+  now?: number;
+  /** What `local.epoch` answers; a store-side counter, so it is scripted like `now`. */
+  epoch?: number;
+  handlers?: Partial<Record<EffectKind, EffectHandler>>;
+}
+
+export interface RunPureResult<R> extends PureContext {
+  result: R;
+}
+
+export class UnhandledEffectError extends Error {
+  constructor(public readonly effect: Effect) {
+    super(`runPure: no handler for effect '${effect.kind}'`);
+    this.name = 'UnhandledEffectError';
+  }
+}
+
+export async function sha256Hex(input: string): Promise<string> {
+  const bytes = new TextEncoder().encode(input);
+  const digest = await webcrypto.subtle.digest('SHA-256', bytes);
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Drive a saga with canned effect results. `state.*`, `now`, `id`, `hash`,
+ * `timer.*`, `emit`, `dispatch` and `local.epoch` are handled here; every other
+ * adapter effect (`local.*`, `remote.*`, `ssp.*`) must have a handler or the run throws, so
+ * a test can never pass by an effect silently returning `undefined`.
+ */
+export async function runPure<R>(saga: Saga<R>, opts: RunPureOptions = {}): Promise<RunPureResult<R>> {
+  const ctx: PureContext = {
+    state: opts.state ?? emptyState({ tabId: 'tab-test' }),
+    now: opts.now ?? 1_700_000_000_000,
+    log: [],
+    timers: new Map(),
+    emitted: [],
+    dispatched: [],
+    ids: 0,
+  };
+  const interpret = async (effect: Effect): Promise<unknown> => {
+    ctx.log.push(effect);
+    const custom = opts.handlers?.[effect.kind];
+    if (custom) return custom(effect, ctx);
+    switch (effect.kind) {
+      case 'state.read':
+        return effect.select(ctx.state);
+      case 'state.update':
+        ctx.state = effect.fn(ctx.state);
+        return ctx.state;
+      case 'state.wait':
+        if (effect.until(ctx.state)) return undefined;
+        throw new Error('runPure: state.wait would block; script a handler or prepare the state');
+      case 'now':
+        return ctx.now;
+      case 'local.epoch':
+        return opts.epoch ?? 0;
+      case 'id':
+        ctx.ids += 1;
+        return `${effect.scope}-${ctx.ids}`;
+      case 'hash':
+        return sha256Hex(effect.input);
+      case 'timer.set':
+        ctx.timers.set(effect.key, { ms: effect.ms, event: effect.event });
+        return undefined;
+      case 'timer.clear':
+        ctx.timers.delete(effect.key);
+        return undefined;
+      case 'emit':
+        ctx.emitted.push(effect.event);
+        return undefined;
+      case 'dispatch':
+        ctx.dispatched.push(effect.event);
+        return undefined;
+      case 'service':
+        throw new UnhandledEffectError(effect);
+      case 'all': {
+        const results: Settled[] = [];
+        for (const inner of effect.effects) {
+          try {
+            results.push({ ok: true, value: await interpret(inner) });
+          } catch (error) {
+            results.push({ ok: false, error });
+          }
+        }
+        return results;
+      }
+      default:
+        throw new UnhandledEffectError(effect);
+    }
+  };
+  const result = await runSaga(saga, interpret);
+  return { ...ctx, result };
+}
+
+/** Handler helper: answer effects by SQL prefix (first match wins). */
+export function bySqlPrefix(
+  table: Array<[prefix: string, answer: (effect: Effect & { sql: string }) => unknown]>
+): EffectHandler {
+  return (effect) => {
+    const sql = (effect as { sql?: string }).sql ?? '';
+    for (const [prefix, answer] of table) {
+      if (sql.startsWith(prefix)) return answer(effect as Effect & { sql: string });
+    }
+    throw new Error(`no scripted answer for SQL: ${sql.slice(0, 80)}`);
+  };
+}

package/src/testing/services.ts

@@ -0,0 +1,17 @@
+import type { Effect, ServiceCalls, ServiceName } from '../kernel/effects';
+import type { EffectHandler } from './run-pure';
+
+type Impl = { [N in ServiceName]?: (...args: Parameters<ServiceCalls[N]>) => unknown };
+
+/** Script the `service` effect by name and record every call. */
+export function fakeServices(impl: Impl = {}) {
+  const calls: Array<[ServiceName, unknown[]]> = [];
+  const handler: EffectHandler = (effect: Effect) => {
+    if (effect.kind !== 'service') throw new Error('not a service effect');
+    calls.push([effect.name, effect.args]);
+    const fn = impl[effect.name] as ((...a: unknown[]) => unknown) | undefined;
+    if (!fn) return undefined;
+    return fn(...effect.args);
+  };
+  return { handler, calls, names: () => calls.map(([n]) => n) };
+}

package/src/types.ts

@@ -1,7 +1,6 @@
 import type { RecordId, SchemaStructure, QueryPlan } from '@spooky-sync/query-builder';
 import type { Level, LoggerOptions } from 'pino';
 import type { PushEventOptions } from './events/index';
-import type { UpEvent } from './modules/sync/index';
 import type { LocalEngineChoice } from './services/database/cache-engine';
 
 export type { Level };
@@ -80,9 +79,11 @@ export type QueryTimeToLive =
 export type PreloadRefresh = 'onUse' | 'background' | 'stale';
 
 export interface PreloadOptions {
-  /** How to refresh when the query is already cached locally. Default `onUse`. */
+  /** Abort a cold preload that is still waiting for the server. */
+  signal?: AbortSignal;
+  /** @deprecated Preload is a registered query now; a warm preload never refetches by itself. Ignored. */
   refresh?: PreloadRefresh;
-  /** For `refresh: 'stale'` — max age before a warm copy is refetched. Default `1h`. */
+  /** @deprecated Ignored. */
   staleTime?: QueryTimeToLive;
 }
 
@@ -517,21 +518,21 @@ export interface QueryConfig {
   /**
    * Whether authoritative membership (`remoteArray`) has ever been established
    * for this query — either fetched from `_00_list_ref` this session, or read
-   * back from the durable `_00_window` row on a cold start.
+   * back from the durable `_00_view` row on a cold start.
    *
    * Tri-state matters: "known and empty" must render an empty list, while
    * "never established" has to fall back to a predicate scan of the local store
    * so a query first run on this device still paints offline. A
    * `remoteArray.length === 0` check cannot tell those apart.
    *
-   * On a cold start it is seeded from the durable `_00_window` row when that
+   * On a cold start it is seeded from the durable `_00_view` row when that
    * row is non-empty, or empty but `confirmed` (the server reported zero rows
    * for the query). An unconfirmed empty row is ignored, so a device poisoned
    * by an old client that mirrored unflushed reads still self-heals.
    */
   membershipKnown?: boolean;
   /**
-   * Key of this query's durable `_00_window` membership row: a hash of
+   * Key of this query's durable `_00_view` membership row: a hash of
    * `{surql, params}` WITHOUT the `session::id()` salt that `id` carries, so it
    * survives a reload (which mints a new session id) and a bucket switch.
    * In-memory only.
@@ -710,7 +711,7 @@ export type QueryStatusCallback = (status: QueryStatus) => void;
  * (bucket switch). What the bindings' `isAuthoritative()` mirrors.
  */
 export type QueryAuthorityCallback = (known: boolean) => void;
-export type MutationCallback = (mutations: UpEvent[]) => void;
+export type MutationCallback = (mutations: MutationEvent[]) => void;
 
 export type MutationEventType = 'create' | 'update' | 'delete';
 

package/src/utils/utils.test.ts

@@ -9,6 +9,7 @@ import {
   generateId,
   parseDuration,
 } from './index';
+import type { QueryTimeToLive } from '../types';
 
 describe('compareRecordIds', () => {
   it('returns true for equal strings', () => {
@@ -123,7 +124,7 @@ describe('generateId', () => {
 
 describe('parseDuration', () => {
   it('parses seconds', () => {
-    expect(parseDuration('30s')).toBe(30000);
+    expect(parseDuration('30s' as QueryTimeToLive)).toBe(30000);
   });
 
   it('parses minutes', () => {

package/vitest.config.ts

@@ -0,0 +1,48 @@
+import { defineConfig } from 'vitest/config';
+
+// Thresholds start at the numbers the suite hits today and are ratcheted per
+// directory as the saga core lands (see the plan's commit 10). Exclusions:
+//   *.fixture.ts / src/testing/**   test-only harness code
+//   sqlite-worker.ts                runs inside a Worker (sqlite-wasm + OPFS +
+//                                   postMessage globals); covered by the sqlite
+//                                   integration tests and the build check
+//   client/services.ts              constructs the real adapters (SurrealDB
+//                                   WASM store, socket, SharedWorker broker,
+//                                   OPFS blob cache); exercised by the example
+//                                   app and the WhitePawn A/B, not by vitest
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      all: true,
+      reporter: ['text-summary', 'lcov'],
+      include: ['src/**/*.ts'],
+      exclude: [
+        'src/**/*.test.ts',
+        'src/**/*.d.ts',
+        'src/**/*.fixture.ts',
+        'src/testing/**',
+        'src/services/database/sqlite-worker.ts',
+        'src/client/services.ts',
+      ],
+      thresholds: {
+        // Global numbers are held back by the legacy adapters (devtools,
+        // sqlite engine, tabs broker, blobs, crdt); the saga core below is 100%.
+        lines: 75,
+        functions: 82,
+        branches: 87,
+        statements: 75,
+        'src/kernel/**': { lines: 100, functions: 100, branches: 100, statements: 100 },
+        'src/state/**': { lines: 100, functions: 100, branches: 100, statements: 100 },
+        'src/query/**': { lines: 100, functions: 100, branches: 100, statements: 100 },
+        'src/mutation/**': { lines: 100, functions: 100, branches: 100, statements: 100 },
+        'src/sync/**': { lines: 100, functions: 100, branches: 100, statements: 100 },
+        'src/boot/**': { lines: 100, functions: 100, branches: 100, statements: 100 },
+        // The facade's shared-tabs host callbacks need a SharedWorker broker to fire.
+        'src/client/**': { lines: 93, functions: 92, branches: 89, statements: 93 },
+      },
+    },
+  },
+});

package/coverage/lcov-report/base.css

@@ -1,224 +0,0 @@
-body, html {
-  margin:0; padding: 0;
-  height: 100%;
-}
-body {
-    font-family: Helvetica Neue, Helvetica, Arial;
-    font-size: 14px;
-    color:#333;
-}
-.small { font-size: 12px; }
-*, *:after, *:before {
-  -webkit-box-sizing:border-box;
-     -moz-box-sizing:border-box;
-          box-sizing:border-box;
-  }
-h1 { font-size: 20px; margin: 0;}
-h2 { font-size: 14px; }
-pre {
-    font: 12px/1.4 Consolas, "Liberation Mono", Menlo, Courier, monospace;
-    margin: 0;
-    padding: 0;
-    -moz-tab-size: 2;
-    -o-tab-size:  2;
-    tab-size: 2;
-}
-a { color:#0074D9; text-decoration:none; }
-a:hover { text-decoration:underline; }
-.strong { font-weight: bold; }
-.space-top1 { padding: 10px 0 0 0; }
-.pad2y { padding: 20px 0; }
-.pad1y { padding: 10px 0; }
-.pad2x { padding: 0 20px; }
-.pad2 { padding: 20px; }
-.pad1 { padding: 10px; }
-.space-left2 { padding-left:55px; }
-.space-right2 { padding-right:20px; }
-.center { text-align:center; }
-.clearfix { display:block; }
-.clearfix:after {
-  content:'';
-  display:block;
-  height:0;
-  clear:both;
-  visibility:hidden;
-  }
-.fl { float: left; }
-@media only screen and (max-width:640px) {
-  .col3 { width:100%; max-width:100%; }
-  .hide-mobile { display:none!important; }
-}
-
-.quiet {
-  color: #7f7f7f;
-  color: rgba(0,0,0,0.5);
-}
-.quiet a { opacity: 0.7; }
-
-.fraction {
-  font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
-  font-size: 10px;
-  color: #555;
-  background: #E8E8E8;
-  padding: 4px 5px;
-  border-radius: 3px;
-  vertical-align: middle;
-}
-
-div.path a:link, div.path a:visited { color: #333; }
-table.coverage {
-  border-collapse: collapse;
-  margin: 10px 0 0 0;
-  padding: 0;
-}
-
-table.coverage td {
-  margin: 0;
-  padding: 0;
-  vertical-align: top;
-}
-table.coverage td.line-count {
-    text-align: right;
-    padding: 0 5px 0 20px;
-}
-table.coverage td.line-coverage {
-    text-align: right;
-    padding-right: 10px;
-    min-width:20px;
-}
-
-table.coverage td span.cline-any {
-    display: inline-block;
-    padding: 0 5px;
-    width: 100%;
-}
-.missing-if-branch {
-    display: inline-block;
-    margin-right: 5px;
-    border-radius: 3px;
-    position: relative;
-    padding: 0 4px;
-    background: #333;
-    color: yellow;
-}
-
-.skip-if-branch {
-    display: none;
-    margin-right: 10px;
-    position: relative;
-    padding: 0 4px;
-    background: #ccc;
-    color: white;
-}
-.missing-if-branch .typ, .skip-if-branch .typ {
-    color: inherit !important;
-}
-.coverage-summary {
-  border-collapse: collapse;
-  width: 100%;
-}
-.coverage-summary tr { border-bottom: 1px solid #bbb; }
-.keyline-all { border: 1px solid #ddd; }
-.coverage-summary td, .coverage-summary th { padding: 10px; }
-.coverage-summary tbody { border: 1px solid #bbb; }
-.coverage-summary td { border-right: 1px solid #bbb; }
-.coverage-summary td:last-child { border-right: none; }
-.coverage-summary th {
-  text-align: left;
-  font-weight: normal;
-  white-space: nowrap;
-}
-.coverage-summary th.file { border-right: none !important; }
-.coverage-summary th.pct { }
-.coverage-summary th.pic,
-.coverage-summary th.abs,
-.coverage-summary td.pct,
-.coverage-summary td.abs { text-align: right; }
-.coverage-summary td.file { white-space: nowrap;  }
-.coverage-summary td.pic { min-width: 120px !important;  }
-.coverage-summary tfoot td { }
-
-.coverage-summary .sorter {
-    height: 10px;
-    width: 7px;
-    display: inline-block;
-    margin-left: 0.5em;
-    background: url(sort-arrow-sprite.png) no-repeat scroll 0 0 transparent;
-}
-.coverage-summary .sorted .sorter {
-    background-position: 0 -20px;
-}
-.coverage-summary .sorted-desc .sorter {
-    background-position: 0 -10px;
-}
-.status-line {  height: 10px; }
-/* yellow */
-.cbranch-no { background: yellow !important; color: #111; }
-/* dark red */
-.red.solid, .status-line.low, .low .cover-fill { background:#C21F39 }
-.low .chart { border:1px solid #C21F39 }
-.highlighted,
-.highlighted .cstat-no, .highlighted .fstat-no, .highlighted .cbranch-no{
-  background: #C21F39 !important;
-}
-/* medium red */
-.cstat-no, .fstat-no, .cbranch-no, .cbranch-no { background:#F6C6CE }
-/* light red */
-.low, .cline-no { background:#FCE1E5 }
-/* light green */
-.high, .cline-yes { background:rgb(230,245,208) }
-/* medium green */
-.cstat-yes { background:rgb(161,215,106) }
-/* dark green */
-.status-line.high, .high .cover-fill { background:rgb(77,146,33) }
-.high .chart { border:1px solid rgb(77,146,33) }
-/* dark yellow (gold) */
-.status-line.medium, .medium .cover-fill { background: #f9cd0b; }
-.medium .chart { border:1px solid #f9cd0b; }
-/* light yellow */
-.medium { background: #fff4c2; }
-
-.cstat-skip { background: #ddd; color: #111; }
-.fstat-skip { background: #ddd; color: #111 !important; }
-.cbranch-skip { background: #ddd !important; color: #111; }
-
-span.cline-neutral { background: #eaeaea; }
-
-.coverage-summary td.empty {
-    opacity: .5;
-    padding-top: 4px;
-    padding-bottom: 4px;
-    line-height: 1;
-    color: #888;
-}
-
-.cover-fill, .cover-empty {
-  display:inline-block;
-  height: 12px;
-}
-.chart {
-  line-height: 0;
-}
-.cover-empty {
-    background: white;
-}
-.cover-full {
-    border-right: none !important;
-}
-pre.prettyprint {
-    border: none !important;
-    padding: 0 !important;
-    margin: 0 !important;
-}
-.com { color: #999 !important; }
-.ignore-none { color: #999; font-weight: normal; }
-
-.wrapper {
-  min-height: 100%;
-  height: auto !important;
-  height: 100%;
-  margin: 0 auto -48px;
-}
-.footer, .push {
-  height: 48px;
-}

package/coverage/lcov-report/block-navigation.js

@@ -1,87 +0,0 @@
-/* eslint-disable */
-var jumpToCode = (function init() {
-    // Classes of code we would like to highlight in the file view
-    var missingCoverageClasses = ['.cbranch-no', '.cstat-no', '.fstat-no'];
-
-    // Elements to highlight in the file listing view
-    var fileListingElements = ['td.pct.low'];
-
-    // We don't want to select elements that are direct descendants of another match
-    var notSelector = ':not(' + missingCoverageClasses.join('):not(') + ') > '; // becomes `:not(a):not(b) > `
-
-    // Selector that finds elements on the page to which we can jump
-    var selector =
-        fileListingElements.join(', ') +
-        ', ' +
-        notSelector +
-        missingCoverageClasses.join(', ' + notSelector); // becomes `:not(a):not(b) > a, :not(a):not(b) > b`
-
-    // The NodeList of matching elements
-    var missingCoverageElements = document.querySelectorAll(selector);
-
-    var currentIndex;
-
-    function toggleClass(index) {
-        missingCoverageElements
-            .item(currentIndex)
-            .classList.remove('highlighted');
-        missingCoverageElements.item(index).classList.add('highlighted');
-    }
-
-    function makeCurrent(index) {
-        toggleClass(index);
-        currentIndex = index;
-        missingCoverageElements.item(index).scrollIntoView({
-            behavior: 'smooth',
-            block: 'center',
-            inline: 'center'
-        });
-    }
-
-    function goToPrevious() {
-        var nextIndex = 0;
-        if (typeof currentIndex !== 'number' || currentIndex === 0) {
-            nextIndex = missingCoverageElements.length - 1;
-        } else if (missingCoverageElements.length > 1) {
-            nextIndex = currentIndex - 1;
-        }
-
-        makeCurrent(nextIndex);
-    }
-
-    function goToNext() {
-        var nextIndex = 0;
-
-        if (
-            typeof currentIndex === 'number' &&
-            currentIndex < missingCoverageElements.length - 1
-        ) {
-            nextIndex = currentIndex + 1;
-        }
-
-        makeCurrent(nextIndex);
-    }
-
-    return function jump(event) {
-        if (
-            document.getElementById('fileSearch') === document.activeElement &&
-            document.activeElement != null
-        ) {
-            // if we're currently focused on the search input, we don't want to navigate
-            return;
-        }
-
-        switch (event.which) {
-            case 78: // n
-            case 74: // j
-                goToNext();
-                break;
-            case 66: // b
-            case 75: // k
-            case 80: // p
-                goToPrevious();
-                break;
-        }
-    };
-})();
-window.addEventListener('keydown', jumpToCode);