@absolutejs/sync 1.22.0 → 1.24.0

package/dist/engine/migrate.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Tenant migration primitives. Closes G7 from the deep-research
+ * audit: "move a tenant from engine A to engine B."
+ *
+ * The substrate offers three composable verbs:
+ *
+ * - **`engine.fence({ reason })`** — pause new mutations on the
+ *   source so its captured state stops drifting. Subscribers continue
+ *   to read; only `runMutation` rejects (with
+ *   {@link EngineFencedError}). Returns a {@link FenceHandle} with
+ *   `lift()` to undo.
+ * - **`engine.exportSnapshot({ tables?, ctx? })`** — walk the
+ *   registered readers and return a portable
+ *   {@link EngineSnapshot} carrying the source `instanceId`,
+ *   `version`, and current rows per table. Cheap and synchronous from
+ *   the operator's POV.
+ * - **`engine.importSnapshot(snapshot, options?)`** — on the target,
+ *   bulk-load the rows via each table's registered writer. Tracks
+ *   per-table progress. Returns a {@link MigrationImportResult} with
+ *   row counts.
+ *
+ * The intended choreography for a cross-region tenant move:
+ *
+ * ```ts
+ * // ── on the source ──
+ * const fence = source.fence({ reason: 'tenant-7 → us-east-2' });
+ * try {
+ *   const snapshot = await source.exportSnapshot();
+ *   await transport(snapshot); // S3, message bus, etc.
+ *   // ── on the target ──
+ *   await target.importSnapshot(snapshot, {
+ *     onProgress: (table, done, total) =>
+ *       console.log(`${table}: ${done}/${total}`)
+ *   });
+ *   await cutoverDns(); // direct clients at target
+ * } finally {
+ *   fence.lift();
+ * }
+ * ```
+ *
+ * Out of scope: out-of-band writes (CDC drivers, raw SQL) — the
+ * caller is responsible for pausing those before fencing, otherwise
+ * the captured snapshot drifts.
+ *
+ * Added in 1.24.0.
+ */
+/**
+ * Portable per-tenant state captured by
+ * {@link SyncEngine.exportSnapshot}. Consumed by
+ * {@link SyncEngine.importSnapshot} on the target engine.
+ */
+export type EngineSnapshot = {
+    /** The exporting engine's `instanceId` (for audit / forensics). */
+    sourceInstanceId: string;
+    /** Source engine's monotonic version at snapshot time. */
+    version: number;
+    /** `Date.now()` at export — used by hosts for staleness checks. */
+    exportedAt: number;
+    /** Current rows per table, read from each table's registered reader. */
+    tables: Record<string, ReadonlyArray<unknown>>;
+};
+/**
+ * Returned by {@link SyncEngine.importSnapshot}.
+ */
+export type MigrationImportResult = {
+    /** Number of tables that had at least one row imported. */
+    tablesImported: number;
+    /** Total rows inserted across all tables. */
+    rowsImported: number;
+    /** Rows inserted per table. Tables with zero rows are still listed. */
+    perTable: Record<string, number>;
+    /**
+     * Tables present in the snapshot that the target engine has no
+     * registered writer for — skipped silently. Surface this to
+     * operators so they can catch "I forgot to register `tasks` on
+     * the new shard" cleanly.
+     */
+    skipped: ReadonlyArray<string>;
+};
+/**
+ * Returned by {@link SyncEngine.fence}. Hold this and call `lift()`
+ * to re-enable mutations. Holding multiple fences is supported — the
+ * engine stays fenced until every handle has been lifted.
+ */
+export type FenceHandle = {
+    /** `Date.now()` at fence time. */
+    fencedAt: number;
+    /** Human-readable reason — surfaced on {@link EngineFencedError}. */
+    reason: string;
+    /** Re-enable mutations. Idempotent (later calls are no-ops). */
+    lift: () => void;
+};
+export type ExportSnapshotOptions = {
+    /**
+     * Narrow the export to a subset of registered tables. Useful for
+     * per-tenant cuts when readers expose `ctx`-scoped data.
+     */
+    tables?: ReadonlyArray<string>;
+    /**
+     * Context passed to each reader's `all(ctx)`. The default `{}`
+     * works for engines whose readers ignore context.
+     */
+    ctx?: unknown;
+};
+export type ImportSnapshotOptions = {
+    /**
+     * Narrow the import to a subset of tables in the snapshot.
+     * Tables outside the filter are skipped (NOT recorded in
+     * `skipped`; that field is for tables with no writer).
+     */
+    tables?: ReadonlyArray<string>;
+    /**
+     * Called for each row insertion. Fires synchronously inside the
+     * import loop; keep it cheap or schedule heavy work elsewhere.
+     */
+    onProgress?: (table: string, done: number, total: number) => void;
+    /**
+     * Context passed to each writer's `insert(data, ctx, tx)`. The
+     * default `{}` works for writers that ignore context.
+     */
+    ctx?: unknown;
+};
+/**
+ * Thrown by `runMutation` when the engine is fenced. The reason
+ * carries through so operators can correlate denied calls to the
+ * fence that caused them.
+ */
+export declare class EngineFencedError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}

package/dist/engine/syncEngine.d.ts

@@ -10,6 +10,7 @@ import type { SearchCollectionDefinition } from './search';
 import type { ScheduleDefinition } from './schedule';
 import type { EngineActivity, EngineInspection, EngineMetrics } from './devtools';
 import type { SchemaDefinition, TableSchema } from './schema';
+import { type EngineSnapshot, type ExportSnapshotOptions, type FenceHandle, type ImportSnapshotOptions, type MigrationImportResult } from './migrate';
 import type { CrdtMergeable } from '../crdt';
 import type { ClusterBus } from './cluster';
 import type { ChangeSource, RowChange, ViewDiff } from './types';
@@ -324,6 +325,61 @@ export type SyncEngine = {
      * ```
      */
     replayTo: (options: ReplayOptions) => Promise<ReplayResult>;
+    /**
+     * Pause new mutations on the engine — the source half of the G7 tenant
+     * migration contract. While at least one fence is held, `runMutation`
+     * rejects with {@link EngineFencedError}; subscribe/hydrate continue to
+     * work, so live readers stay served while the snapshot is in flight.
+     *
+     * Multiple fence handles compose — the engine stays fenced until every
+     * handle has been `lift()`-ed. Lifting is idempotent.
+     *
+     * Out of scope: out-of-band writes (CDC drivers, raw SQL). The caller
+     * is responsible for halting those before fencing, otherwise the
+     * snapshot will drift between `exportSnapshot` and import on the target.
+     *
+     * Added in 1.24.0.
+     */
+    fence: (options: {
+        reason: string;
+    }) => FenceHandle;
+    /**
+     * Capture the engine's current per-table state into a portable
+     * {@link EngineSnapshot}. Walks every registered reader's `all(ctx)`
+     * and collects the rows. Used to ship a tenant between engines (G7).
+     *
+     * Pair with `fence()` on the source to stop drift, then
+     * `importSnapshot()` on the target. The shape is intentionally
+     * detached from `ChangeLogSnapshot` — snapshots carry live state, not
+     * history. Use `exportChangeLog()` separately if you need forensic
+     * continuity at the target instanceId.
+     *
+     * Added in 1.24.0.
+     *
+     * @example
+     * const fence = source.fence({ reason: 'tenant move' });
+     * try {
+     *   const snapshot = await source.exportSnapshot();
+     *   await target.importSnapshot(snapshot);
+     * } finally { fence.lift(); }
+     */
+    exportSnapshot: (options?: ExportSnapshotOptions) => Promise<EngineSnapshot>;
+    /**
+     * Bulk-load an {@link EngineSnapshot} into this engine via each table's
+     * registered writer. Tables present in the snapshot but missing a
+     * writer here are surfaced in `result.skipped` so the operator can
+     * detect a misconfigured target. The target half of the G7 migration
+     * contract.
+     *
+     * Inserts do NOT emit change events to subscribers — the import is
+     * meant to land on a fresh target whose clients will re-hydrate after
+     * the DNS cutover. If you need to fan changes out (e.g. mid-flight
+     * cutover), drain the change log via `streamChanges()` and
+     * `applyChange()` separately.
+     *
+     * Added in 1.24.0.
+     */
+    importSnapshot: (snapshot: EngineSnapshot, options?: ImportSnapshotOptions) => Promise<MigrationImportResult>;
     /**
      * Subscribe to the live engine activity stream (changes, mutation outcomes,
      * subscribe/unsubscribe). Returns an unsubscribe. Powers the devtools feed.

package/dist/index.js

@@ -1143,6 +1143,16 @@ var defineSearchCollection = (definition) => ({
   kind: "search"
 });
 
+// src/engine/migrate.ts
+class EngineFencedError extends Error {
+  reason;
+  constructor(reason) {
+    super(`[sync] Engine is fenced for migration: ${reason}`);
+    this.name = "EngineFencedError";
+    this.reason = reason;
+  }
+}
+
 // src/engine/syncEngine.ts
 class UnauthorizedError extends Error {
   constructor(subject) {
@@ -1345,6 +1355,7 @@ var createSyncEngine = (options = {}) => {
   let mutationsInFlight = 0;
   const mutationWaiters = [];
   let mutationsQueued = 0;
+  const activeFences = new Set;
   const acquireMutationSlot = async () => {
     const limit = options.mutationConcurrency;
     if (limit === undefined) {
@@ -2463,6 +2474,10 @@ var createSyncEngine = (options = {}) => {
         }
       });
       try {
+        if (activeFences.size > 0) {
+          const oldest = activeFences.values().next().value;
+          throw new EngineFencedError(oldest.reason);
+        }
         const mutation = mutations.get(name);
         if (mutation === undefined) {
           throw new Error(`Unknown mutation "${name}"`);
@@ -2838,6 +2853,70 @@ var createSyncEngine = (options = {}) => {
       }
       return { asOfAt, asOfVersion, rows, truncated };
     },
+    fence: ({ reason }) => {
+      const handle = {
+        fencedAt: Date.now(),
+        reason,
+        lift: () => {
+          activeFences.delete(handle);
+        }
+      };
+      activeFences.add(handle);
+      return handle;
+    },
+    exportSnapshot: async ({ tables, ctx = {} } = {}) => {
+      const tableFilter = tables !== undefined ? new Set(tables) : undefined;
+      const rows = {};
+      for (const [table, reader] of readers) {
+        if (tableFilter !== undefined && !tableFilter.has(table)) {
+          continue;
+        }
+        const iterable = await reader.all(ctx);
+        rows[table] = [...iterable];
+      }
+      return {
+        exportedAt: Date.now(),
+        sourceInstanceId: instanceId,
+        tables: rows,
+        version
+      };
+    },
+    importSnapshot: async (snapshot, { tables, onProgress, ctx = {} } = {}) => {
+      const tableFilter = tables !== undefined ? new Set(tables) : undefined;
+      const perTable = {};
+      const skipped = [];
+      let tablesImported = 0;
+      let rowsImported = 0;
+      for (const [table, snapshotRows] of Object.entries(snapshot.tables)) {
+        if (tableFilter !== undefined && !tableFilter.has(table)) {
+          continue;
+        }
+        const writer = writers.get(table);
+        if (writer === undefined) {
+          skipped.push(table);
+          continue;
+        }
+        const total = snapshotRows.length;
+        let done = 0;
+        for (const row of snapshotRows) {
+          await writer.insert(row, ctx, undefined);
+          done += 1;
+          rowsImported += 1;
+          if (onProgress !== undefined) {
+            onProgress(table, done, total);
+          }
+        }
+        perTable[table] = done;
+        if (done > 0)
+          tablesImported += 1;
+      }
+      return {
+        perTable,
+        rowsImported,
+        skipped,
+        tablesImported
+      };
+    },
     metrics: () => {
       const now = Date.now();
       const byCollection = {};
@@ -3063,7 +3142,7 @@ var syncCdc = ({
 };
 // src/devtools.ts
 import { Elysia as Elysia3 } from "elysia";
-var dashboardHtml = (streamPath) => `<!doctype html>
+var dashboardHtml = (streamPath, replayPath) => `<!doctype html>
 <html lang="en"><head><meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 <title>@absolutejs/sync devtools</title>
@@ -3086,12 +3165,37 @@ th{color:#7f849c;font-weight:600}
 .t-change{color:#94e2d5}.t-mutation{color:#cba6f7}.err{color:#f38ba8}
 .pill{padding:0 6px;border-radius:10px;background:#1c2230;flex:0 0 auto}
 .empty{color:#6c7086;padding:6px}
+.replay{grid-column:1/3}
+.replay-controls{display:flex;flex-wrap:wrap;gap:8px;align-items:center;margin-bottom:8px}
+.replay-controls input{background:#0b0e14;border:1px solid #1c2230;color:#cdd6f4;border-radius:4px;padding:4px 6px;font:inherit}
+.replay-controls input[type="datetime-local"]{min-width:200px}
+.replay-controls input[type="text"]{min-width:180px}
+.replay-controls button{background:#89b4fa;border:none;color:#0b0e14;border-radius:4px;padding:5px 12px;font:inherit;font-weight:600;cursor:pointer}
+.replay-controls button:hover{background:#74c7ec}
+.replay-controls button:disabled{background:#1c2230;color:#6c7086;cursor:not-allowed}
+.replay-controls label{color:#7f849c;display:flex;align-items:center;gap:6px}
+.truncated{background:#311b1b;border:1px solid #f38ba8;color:#f38ba8;padding:6px 10px;border-radius:4px;margin-bottom:8px}
+.replay-meta{color:#a6adc8;margin-bottom:8px}
+.replay-meta b{color:#cdd6f4}
+.replay-table{margin-top:10px}
+.replay-table h3{margin:0 0 4px;color:#94e2d5;font-size:12px;font-weight:600}
+.replay-rows pre{margin:0;font-size:11px;color:#a6adc8;background:#0b0e14;border:1px solid #1c2230;border-radius:4px;padding:6px;max-height:200px;overflow:auto;white-space:pre-wrap;word-break:break-word}
 </style></head>
 <body>
 <header><b>@absolutejs/sync</b> devtools <span id="status" class="empty">connecting\u2026</span><span class="ver">v<span id="version">0</span></span></header>
 <main>
 <section><h2>Collections</h2><table><thead><tr><th>name</th><th>kind</th><th>tables</th><th class="subs">subs</th></tr></thead><tbody id="collections"></tbody></table></section>
 <section><h2>Mutations \xB7 Schedules</h2><div id="ops"></div></section>
+<section class="replay"><h2>Point-in-time replay</h2>
+<div class="replay-controls">
+  <label>at <input type="datetime-local" id="replay-at" step="1" /></label>
+  <label>tables <input type="text" id="replay-tables" placeholder="(all if blank \u2014 csv)" /></label>
+  <label>max rows per table <input type="number" id="replay-max" value="10" min="1" max="500" style="width:64px" /></label>
+  <button id="replay-go">Replay</button>
+  <button id="replay-now" type="button" title="Set datetime to right now">Now</button>
+</div>
+<div id="replay-result"><div class="empty">Pick a date+time, optionally filter tables, then click Replay to reconstruct state at that point in the log window.</div></div>
+</section>
 <section class="log"><h2>Activity</h2><div id="activity"><div class="empty">waiting for changes &amp; mutations\u2026</div></div></section>
 </main>
 <script>
@@ -3120,6 +3224,57 @@ const logActivity=(a)=>{
   box.prepend(row);
   while(box.childNodes.length>200)box.removeChild(box.lastChild);
 };
+const localToMs=(value)=>{
+  if(!value)return null;
+  const ms=new Date(value).getTime();
+  return Number.isFinite(ms)?ms:null;
+};
+const msToLocal=(ms)=>{
+  const d=new Date(ms);
+  const pad=(n)=>String(n).padStart(2,'0');
+  return d.getFullYear()+'-'+pad(d.getMonth()+1)+'-'+pad(d.getDate())+'T'+pad(d.getHours())+':'+pad(d.getMinutes())+':'+pad(d.getSeconds());
+};
+const renderReplay=(result, maxRows)=>{
+  const box=$('replay-result');
+  const tables=Object.keys(result.rows).sort();
+  const trunc=result.truncated?'<div class="truncated">\u26A0 Replay truncated \u2014 log retention window doesn\\'t cover this timestamp. Result is best-effort, walked forward from the oldest retained entry.</div>':'';
+  const meta='<div class="replay-meta">As of <b>version '+result.asOfVersion+'</b> at <b>'+(result.asOfAt?new Date(result.asOfAt).toLocaleString():'(no entries folded)')+'</b></div>';
+  if(tables.length===0){
+    box.innerHTML=trunc+meta+'<div class="empty">No rows in any table at this timestamp.</div>';
+    return;
+  }
+  const sections=tables.map((t)=>{
+    const rows=result.rows[t];
+    const total=rows.length;
+    const shown=rows.slice(0,maxRows);
+    const more=total>maxRows?'<div class="empty">\u2026 '+(total-maxRows)+' more rows omitted</div>':'';
+    return '<div class="replay-table"><h3>'+esc(t)+' <span class="empty">('+total+' row'+(total===1?'':'s')+')</span></h3><div class="replay-rows"><pre>'+esc(JSON.stringify(shown,null,2))+'</pre>'+more+'</div></div>';
+  });
+  box.innerHTML=trunc+meta+sections.join('');
+};
+const doReplay=async()=>{
+  const at=localToMs($('replay-at').value);
+  if(at===null){alert('Please pick a valid date+time');return;}
+  const tables=$('replay-tables').value.split(',').map((s)=>s.trim()).filter(Boolean);
+  const maxRows=Math.max(1,Math.min(500,parseInt($('replay-max').value)||10));
+  const btn=$('replay-go');btn.disabled=true;btn.textContent='Replaying\u2026';
+  try{
+    const params=new URLSearchParams();
+    params.set('at',String(at));
+    if(tables.length>0)params.set('tables',tables.join(','));
+    const res=await fetch('${replayPath}?'+params.toString());
+    if(!res.ok){throw new Error('HTTP '+res.status);}
+    const result=await res.json();
+    renderReplay(result,maxRows);
+  }catch(e){
+    $('replay-result').innerHTML='<div class="truncated">Replay failed: '+esc(e.message)+'</div>';
+  }finally{
+    btn.disabled=false;btn.textContent='Replay';
+  }
+};
+$('replay-go').addEventListener('click',doReplay);
+$('replay-now').addEventListener('click',()=>{$('replay-at').value=msToLocal(Date.now());});
+$('replay-at').value=msToLocal(Date.now()-60*60*1000); // default: 1 hour ago
 const src=new EventSource('${streamPath}');
 src.addEventListener('open',()=>{$('status').textContent='live';$('status').className='';});
 src.addEventListener('error',()=>{$('status').textContent='reconnecting\u2026';$('status').className='empty';});
@@ -3132,9 +3287,44 @@ var syncDevtools = ({
   snapshotMs = 2000
 }) => {
   const streamPath = `${path}/stream`;
-  return new Elysia3({ name: "@absolutejs/sync/devtools" }).get(path, () => new Response(dashboardHtml(streamPath), {
+  const replayPath = `${path}/replay`;
+  return new Elysia3({ name: "@absolutejs/sync/devtools" }).get(path, () => new Response(dashboardHtml(streamPath, replayPath), {
     headers: { "content-type": "text/html; charset=utf-8" }
-  })).get(streamPath, (context) => {
+  })).get(replayPath, async (context) => {
+    const url = new URL(context.request.url);
+    const atRaw = url.searchParams.get("at");
+    const atMs = atRaw === null ? NaN : Number(atRaw);
+    if (!Number.isFinite(atMs)) {
+      return new Response(JSON.stringify({
+        error: "invalid `at` \u2014 must be a numeric ms timestamp"
+      }), {
+        headers: {
+          "content-type": "application/json; charset=utf-8"
+        },
+        status: 400
+      });
+    }
+    const tablesRaw = url.searchParams.get("tables");
+    const tables = tablesRaw === null || tablesRaw.length === 0 ? undefined : tablesRaw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    try {
+      const result = await engine.replayTo(tables === undefined ? { at: atMs } : { at: atMs, tables });
+      return new Response(JSON.stringify(result), {
+        headers: {
+          "cache-control": "no-store",
+          "content-type": "application/json; charset=utf-8"
+        }
+      });
+    } catch (error) {
+      return new Response(JSON.stringify({
+        error: error instanceof Error ? error.message : String(error)
+      }), {
+        headers: {
+          "content-type": "application/json; charset=utf-8"
+        },
+        status: 500
+      });
+    }
+  }).get(streamPath, (context) => {
     const encoder = new TextEncoder;
     const stream = new ReadableStream({
       start(controller) {
@@ -3255,5 +3445,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=6DBA546C7A7B1DC564756E2164756E21
+//# debugId=07C83ADFBDD0094F64756E2164756E21
 //# sourceMappingURL=index.js.map