@absolutejs/sync 1.23.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 = {};
@@ -3366,5 +3445,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=9662318FD91E917A64756E2164756E21
+//# debugId=07C83ADFBDD0094F64756E2164756E21
 //# sourceMappingURL=index.js.map