@spooky-sync/core 0.0.1-canary.111 → 0.0.1-canary.112

package/dist/index.d.ts

@@ -543,6 +543,45 @@ declare class DataModule<S extends SchemaStructure> {
    */
   notifyQuerySynced(queryHash: string): Promise<void>;
   run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(backend: B, path: R, data: RoutePayload<S, B, R>, options?: RunOptions): Promise<void>;
+  /**
+   * Build the outbox job record + resolve its table for a backend route. Shared
+   * by `run` (one-shot) and `runRecurring` (durable schedule).
+   */
+  private buildJobRecord;
+  /**
+   * Deterministic id for the single recurring-schedule row of a given
+   * (assigned_to, path). One row per pair => calling `runRecurring` twice cannot
+   * fork a second schedule, and `poke`/`cancel` address the same row.
+   */
+  private recurringJobId;
+  /**
+   * Register a RECURRING job: one durable row per (assigned_to, path) that
+   * re-runs every `options.interval` ms (measured from each run's completion).
+   * Idempotent: if the schedule already exists it is left untouched, so calling
+   * this on every connect/re-login never forks a second schedule. The first run
+   * fires immediately (`next_run_at = now`), then every interval thereafter.
+   */
+  runRecurring<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(backend: B, path: R, data: RoutePayload<S, B, R>, options: RunOptions & {
+    interval: number;
+    assignedTo: string;
+  }): Promise<void>;
+  /**
+   * Manually trigger a recurring job NOW and reset its interval clock. Sets
+   * `next_run_at = now` on the schedule row; the SSP ingest picks up the update
+   * and dispatches an immediate run, after which the runner re-arms the clock
+   * from that run's completion. No-op if no schedule exists (caller should have
+   * created one via `runRecurring`).
+   */
+  pokeRecurring<B extends BackendNames<S>>(backend: B, path: BackendRoutes<S, B>, options: {
+    assignedTo: string;
+  }): Promise<void>;
+  /**
+   * Cancel a recurring schedule: delete the single schedule row so it stops
+   * being dispatched server-side.
+   */
+  cancelRecurring<B extends BackendNames<S>>(backend: B, path: BackendRoutes<S, B>, options: {
+    assignedTo: string;
+  }): Promise<void>;
   /**
    * Create a new record
    */
@@ -1241,6 +1280,16 @@ declare class Sp00kyClient<S extends SchemaStructure> {
    */
   reportFrontendTiming(queryHash: string, ms: number): void;
   run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(backend: B, path: R, payload: RoutePayload<S, B, R>, options?: RunOptions): Promise<void>;
+  runRecurring<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(backend: B, path: R, payload: RoutePayload<S, B, R>, options: RunOptions & {
+    interval: number;
+    assignedTo: string;
+  }): Promise<void>;
+  pokeRecurring<B extends BackendNames<S>>(backend: B, path: BackendRoutes<S, B>, options: {
+    assignedTo: string;
+  }): Promise<void>;
+  cancelRecurring<B extends BackendNames<S>>(backend: B, path: BackendRoutes<S, B>, options: {
+    assignedTo: string;
+  }): Promise<void>;
   bucket<B extends BucketNames<S>>(name: B): BucketHandle;
   create(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
   update(table: string, id: string, data: Record<string, unknown>, options?: UpdateOptions): Promise<{

package/dist/index.js

@@ -2927,6 +2927,15 @@ var DataModule = class {
 		}
 	}
 	async run(backend, path, data, options) {
+		const { tableName, record } = this.buildJobRecord(backend, path, data, options);
+		const recordId = `${tableName}:${generateId()}`;
+		await this.create(recordId, record);
+	}
+	/**
+	* Build the outbox job record + resolve its table for a backend route. Shared
+	* by `run` (one-shot) and `runRecurring` (durable schedule).
+	*/
+	buildJobRecord(backend, path, data, options) {
 		const route = this.schema.backends?.[backend]?.routes?.[path];
 		if (!route) throw new Error(`Route ${backend}.${path} not found`);
 		const tableName = this.schema.backends?.[backend]?.outboxTable;
@@ -2946,8 +2955,74 @@ var DataModule = class {
 		if (options?.timeout != null) record.timeout = options.timeout;
 		if (options?.delay != null) record.delay = options.delay;
 		if (options?.assignedTo) record.assigned_to = options.assignedTo;
-		const recordId = `${tableName}:${generateId()}`;
-		await this.create(recordId, record);
+		return {
+			tableName,
+			record
+		};
+	}
+	/**
+	* Deterministic id for the single recurring-schedule row of a given
+	* (assigned_to, path). One row per pair => calling `runRecurring` twice cannot
+	* fork a second schedule, and `poke`/`cancel` address the same row.
+	*/
+	recurringJobId(tableName, assignedTo, path) {
+		return `${tableName}:${`${assignedTo}_${path}`.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "")}`;
+	}
+	/**
+	* Register a RECURRING job: one durable row per (assigned_to, path) that
+	* re-runs every `options.interval` ms (measured from each run's completion).
+	* Idempotent: if the schedule already exists it is left untouched, so calling
+	* this on every connect/re-login never forks a second schedule. The first run
+	* fires immediately (`next_run_at = now`), then every interval thereafter.
+	*/
+	async runRecurring(backend, path, data, options) {
+		if (options?.interval == null) throw new Error("runRecurring requires options.interval (ms)");
+		if (!options?.assignedTo) throw new Error("runRecurring requires options.assignedTo");
+		const { tableName, record } = this.buildJobRecord(backend, path, data, options);
+		const recordId = this.recurringJobId(tableName, options.assignedTo, path);
+		const rid = parseRecordIdString(recordId);
+		const [existing] = await withRetry(this.logger, () => this.local.query("SELECT id FROM ONLY $id", { id: rid }));
+		if (existing) return;
+		record.recurring = true;
+		record.interval = options.interval;
+		record.next_run_at = /* @__PURE__ */ new Date();
+		try {
+			await this.create(recordId, record);
+		} catch (err) {
+			this.logger.debug({
+				id: recordId,
+				err: err?.message,
+				Category: "sp00ky-client::DataModule::runRecurring"
+			}, "runRecurring create skipped (schedule likely already exists)");
+		}
+	}
+	/**
+	* Manually trigger a recurring job NOW and reset its interval clock. Sets
+	* `next_run_at = now` on the schedule row; the SSP ingest picks up the update
+	* and dispatches an immediate run, after which the runner re-arms the clock
+	* from that run's completion. No-op if no schedule exists (caller should have
+	* created one via `runRecurring`).
+	*/
+	async pokeRecurring(backend, path, options) {
+		if (!options?.assignedTo) throw new Error("pokeRecurring requires options.assignedTo");
+		const tableName = this.schema.backends?.[backend]?.outboxTable;
+		if (!tableName) throw new Error(`Outbox table for backend ${backend} not found`);
+		const recordId = this.recurringJobId(tableName, options.assignedTo, path);
+		const rid = parseRecordIdString(recordId);
+		const [existing] = await withRetry(this.logger, () => this.local.query("SELECT id FROM ONLY $id", { id: rid }));
+		if (!existing) return;
+		await this.update(tableName, recordId, { next_run_at: /* @__PURE__ */ new Date() });
+	}
+	/**
+	* Cancel a recurring schedule: delete the single schedule row so it stops
+	* being dispatched server-side.
+	*/
+	async cancelRecurring(backend, path, options) {
+		if (!options?.assignedTo) throw new Error("cancelRecurring requires options.assignedTo");
+		const tableName = this.schema.backends?.[backend]?.outboxTable;
+		if (!tableName) throw new Error(`Outbox table for backend ${backend} not found`);
+		const recordId = this.recurringJobId(tableName, options.assignedTo, path);
+		await this.delete(tableName, recordId);
 	}
 	/**
 	* Create a new record
@@ -4976,8 +5051,8 @@ function parseBackendInfo(raw) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.111";
-const WASM_VERSION = "0.0.1-canary.111";
+const CORE_VERSION = "0.0.1-canary.112";
+const WASM_VERSION = "0.0.1-canary.112";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];
@@ -7300,6 +7375,15 @@ var Sp00kyClient = class {
 	run(backend, path, payload, options) {
 		return this.dataModule.run(backend, path, payload, options);
 	}
+	runRecurring(backend, path, payload, options) {
+		return this.dataModule.runRecurring(backend, path, payload, options);
+	}
+	pokeRecurring(backend, path, options) {
+		return this.dataModule.pokeRecurring(backend, path, options);
+	}
+	cancelRecurring(backend, path, options) {
+		return this.dataModule.cancelRecurring(backend, path, options);
+	}
 	bucket(name) {
 		return new BucketHandle(name, this.remote);
 	}

package/dist/types.d.ts

@@ -693,6 +693,12 @@ interface RunOptions {
    * delayed the job stays pending (enqueued) and can still be killed.
    */
   delay?: number;
+  /**
+   * Interval in milliseconds for a RECURRING job (see `runRecurring`). When set,
+   * the job re-runs `interval` ms after each run COMPLETES (drift-free from
+   * completion, not wall-clock). Ignored by the plain `run`.
+   */
+  interval?: number;
 }
 /**
  * Options for update operations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.111",
+  "version": "0.0.1-canary.112",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -59,8 +59,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.111",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.111",
+    "@spooky-sync/query-builder": "0.0.1-canary.112",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.112",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",

package/src/modules/data/data.recurring.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { DataModule } from './index';
+
+/**
+ * Tests for the recurring-outbox API added to DataModule: runRecurring builds a
+ * single deterministic schedule row (idempotent, swallows a duplicate CREATE);
+ * pokeRecurring bumps next_run_at only when the schedule exists; cancelRecurring
+ * deletes it. The heavy create/update/delete pipeline is spied so these assert
+ * the orchestration (deterministic id, field-building, existence gating) without
+ * a real engine.
+ */
+
+function makeLogger(): any {
+  const noop = () => {};
+  const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  logger.child = () => logger;
+  return logger;
+}
+
+const schema = {
+  tables: [{ name: 'job', columns: {} }],
+  backends: {
+    gamesync: {
+      outboxTable: 'job',
+      routes: { '/syncGames': { args: { connection: { optional: false } } } },
+    },
+  },
+};
+
+const CONN = 'connection:CONN_abc';
+
+// localQueryResult drives the existence check ([] = absent, [row] = present).
+function makeDm(localQueryResult: unknown[]) {
+  const local = { query: vi.fn().mockResolvedValue(localQueryResult) };
+  const dm = new DataModule({} as any, local as any, schema as any, makeLogger(), 100);
+  const create = vi.spyOn(dm, 'create').mockResolvedValue(undefined as any);
+  const update = vi.spyOn(dm, 'update').mockResolvedValue(undefined as any);
+  const del = vi.spyOn(dm, 'delete').mockResolvedValue(undefined as any);
+  return { dm, local, create, update, del };
+}
+
+describe('DataModule.runRecurring', () => {
+  it('creates a single deterministic schedule row with the recurring fields', async () => {
+    const { dm, create } = makeDm([]); // no existing row
+    await dm.runRecurring(
+      'gamesync' as any,
+      '/syncGames' as any,
+      { connection: CONN } as any,
+      { assignedTo: CONN, interval: 300000 }
+    );
+
+    expect(create).toHaveBeenCalledTimes(1);
+    const [id, record] = create.mock.calls[0] as [string, any];
+    expect(id.startsWith('job:')).toBe(true);
+    expect(record.recurring).toBe(true);
+    expect(record.interval).toBe(300000);
+    expect(record.next_run_at).toBeInstanceOf(Date);
+    expect(record.assigned_to).toBe(CONN);
+    expect(record.path).toBe('/syncGames');
+    expect(JSON.parse(record.payload)).toEqual({ connection: CONN });
+  });
+
+  it('is idempotent: does nothing when a schedule already exists', async () => {
+    const { dm, create } = makeDm([{ id: 'job:x' }]); // existing row
+    await dm.runRecurring(
+      'gamesync' as any,
+      '/syncGames' as any,
+      { connection: CONN } as any,
+      { assignedTo: CONN, interval: 300000 }
+    );
+    expect(create).not.toHaveBeenCalled();
+  });
+
+  it('swallows a duplicate CREATE (row exists on server but not yet synced locally)', async () => {
+    const { dm, create } = makeDm([]); // local says absent
+    create.mockRejectedValueOnce(new Error('record already exists'));
+    await expect(
+      dm.runRecurring(
+        'gamesync' as any,
+        '/syncGames' as any,
+        { connection: CONN } as any,
+        { assignedTo: CONN, interval: 300000 }
+      )
+    ).resolves.toBeUndefined();
+  });
+
+  it('uses a stable id per (assignedTo, path)', async () => {
+    const a = makeDm([]);
+    await a.dm.runRecurring('gamesync' as any, '/syncGames' as any, { connection: CONN } as any, { assignedTo: CONN, interval: 300000 });
+    const b = makeDm([]);
+    await b.dm.runRecurring('gamesync' as any, '/syncGames' as any, { connection: CONN } as any, { assignedTo: CONN, interval: 300000 });
+    expect(a.create.mock.calls[0][0]).toBe(b.create.mock.calls[0][0]);
+  });
+
+  it('validates required options', async () => {
+    const { dm } = makeDm([]);
+    await expect(
+      dm.runRecurring('gamesync' as any, '/syncGames' as any, { connection: CONN } as any, { assignedTo: CONN } as any)
+    ).rejects.toThrow(/interval/);
+    await expect(
+      dm.runRecurring('gamesync' as any, '/syncGames' as any, { connection: CONN } as any, { interval: 300000 } as any)
+    ).rejects.toThrow(/assignedTo/);
+  });
+});
+
+describe('DataModule.pokeRecurring', () => {
+  it('bumps next_run_at on the existing schedule row', async () => {
+    const { dm, update } = makeDm([{ id: 'job:x' }]);
+    await dm.pokeRecurring('gamesync' as any, '/syncGames' as any, { assignedTo: CONN });
+    expect(update).toHaveBeenCalledTimes(1);
+    const [table, id, data] = update.mock.calls[0] as [string, string, any];
+    expect(table).toBe('job');
+    expect(id.startsWith('job:')).toBe(true);
+    expect(data.next_run_at).toBeInstanceOf(Date);
+  });
+
+  it('is a no-op when no schedule exists', async () => {
+    const { dm, update } = makeDm([]);
+    await dm.pokeRecurring('gamesync' as any, '/syncGames' as any, { assignedTo: CONN });
+    expect(update).not.toHaveBeenCalled();
+  });
+});
+
+describe('DataModule.cancelRecurring', () => {
+  it('deletes the deterministic schedule row', async () => {
+    const { dm, del, create } = makeDm([]);
+    // Capture the id runRecurring would create, to prove cancel targets the same.
+    await dm.runRecurring('gamesync' as any, '/syncGames' as any, { connection: CONN } as any, { assignedTo: CONN, interval: 300000 });
+    const createdId = create.mock.calls[0][0];
+
+    await dm.cancelRecurring('gamesync' as any, '/syncGames' as any, { assignedTo: CONN });
+    expect(del).toHaveBeenCalledTimes(1);
+    const [table, id] = del.mock.calls[0] as [string, string];
+    expect(table).toBe('job');
+    expect(id).toBe(createdId);
+  });
+});

package/src/modules/data/index.ts

@@ -1064,6 +1064,21 @@ export class DataModule<S extends SchemaStructure> {
     data: RoutePayload<S, B, R>,
     options?: RunOptions
   ): Promise<void> {
+    const { tableName, record } = this.buildJobRecord(backend, path, data, options);
+    const recordId = `${tableName}:${generateId()}`;
+    await this.create(recordId, record);
+  }
+
+  /**
+   * Build the outbox job record + resolve its table for a backend route. Shared
+   * by `run` (one-shot) and `runRecurring` (durable schedule).
+   */
+  private buildJobRecord<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(
+    backend: B,
+    path: R,
+    data: RoutePayload<S, B, R>,
+    options?: RunOptions
+  ): { tableName: string; record: Record<string, unknown> } {
     const route = this.schema.backends?.[backend]?.routes?.[path];
     if (!route) {
       throw new Error(`Route ${backend}.${path} not found`);
@@ -1102,8 +1117,114 @@ export class DataModule<S extends SchemaStructure> {
       record.assigned_to = options.assignedTo;
     }
 
-    const recordId = `${tableName}:${generateId()}`;
-    await this.create(recordId, record);
+    return { tableName, record };
+  }
+
+  /**
+   * Deterministic id for the single recurring-schedule row of a given
+   * (assigned_to, path). One row per pair => calling `runRecurring` twice cannot
+   * fork a second schedule, and `poke`/`cancel` address the same row.
+   */
+  private recurringJobId(tableName: string, assignedTo: string, path: string): string {
+    const suffix = `${assignedTo}_${path}`.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+    return `${tableName}:${suffix}`;
+  }
+
+  /**
+   * Register a RECURRING job: one durable row per (assigned_to, path) that
+   * re-runs every `options.interval` ms (measured from each run's completion).
+   * Idempotent: if the schedule already exists it is left untouched, so calling
+   * this on every connect/re-login never forks a second schedule. The first run
+   * fires immediately (`next_run_at = now`), then every interval thereafter.
+   */
+  async runRecurring<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(
+    backend: B,
+    path: R,
+    data: RoutePayload<S, B, R>,
+    options: RunOptions & { interval: number; assignedTo: string }
+  ): Promise<void> {
+    if (options?.interval == null) {
+      throw new Error('runRecurring requires options.interval (ms)');
+    }
+    if (!options?.assignedTo) {
+      throw new Error('runRecurring requires options.assignedTo');
+    }
+
+    const { tableName, record } = this.buildJobRecord(backend, path, data, options);
+    const recordId = this.recurringJobId(tableName, options.assignedTo, path);
+    const rid = parseRecordIdString(recordId);
+
+    // Single schedule per key: if the row already exists, do nothing.
+    const [existing] = await withRetry(this.logger, () =>
+      this.local.query<[unknown]>('SELECT id FROM ONLY $id', { id: rid })
+    );
+    if (existing) return;
+
+    record.recurring = true;
+    record.interval = options.interval;
+    record.next_run_at = new Date(); // run now, then re-arm to now + interval on completion
+    try {
+      await this.create(recordId, record);
+    } catch (err) {
+      // The local existence check can miss a row that exists on the server but
+      // hasn't synced into this session yet (e.g. a re-login before catch-up).
+      // The deterministic id makes that CREATE collide; treat it as "schedule
+      // already exists" and keep runRecurring idempotent rather than throwing.
+      this.logger.debug(
+        { id: recordId, err: (err as Error)?.message, Category: 'sp00ky-client::DataModule::runRecurring' },
+        'runRecurring create skipped (schedule likely already exists)'
+      );
+    }
+  }
+
+  /**
+   * Manually trigger a recurring job NOW and reset its interval clock. Sets
+   * `next_run_at = now` on the schedule row; the SSP ingest picks up the update
+   * and dispatches an immediate run, after which the runner re-arms the clock
+   * from that run's completion. No-op if no schedule exists (caller should have
+   * created one via `runRecurring`).
+   */
+  async pokeRecurring<B extends BackendNames<S>>(
+    backend: B,
+    path: BackendRoutes<S, B>,
+    options: { assignedTo: string }
+  ): Promise<void> {
+    if (!options?.assignedTo) {
+      throw new Error('pokeRecurring requires options.assignedTo');
+    }
+    const tableName = this.schema.backends?.[backend]?.outboxTable;
+    if (!tableName) {
+      throw new Error(`Outbox table for backend ${backend} not found`);
+    }
+    const recordId = this.recurringJobId(tableName, options.assignedTo, path as string);
+    const rid = parseRecordIdString(recordId);
+
+    const [existing] = await withRetry(this.logger, () =>
+      this.local.query<[unknown]>('SELECT id FROM ONLY $id', { id: rid })
+    );
+    if (!existing) return;
+
+    await this.update(tableName, recordId, { next_run_at: new Date() });
+  }
+
+  /**
+   * Cancel a recurring schedule: delete the single schedule row so it stops
+   * being dispatched server-side.
+   */
+  async cancelRecurring<B extends BackendNames<S>>(
+    backend: B,
+    path: BackendRoutes<S, B>,
+    options: { assignedTo: string }
+  ): Promise<void> {
+    if (!options?.assignedTo) {
+      throw new Error('cancelRecurring requires options.assignedTo');
+    }
+    const tableName = this.schema.backends?.[backend]?.outboxTable;
+    if (!tableName) {
+      throw new Error(`Outbox table for backend ${backend} not found`);
+    }
+    const recordId = this.recurringJobId(tableName, options.assignedTo, path as string);
+    await this.delete(tableName, recordId);
   }
 
   // ==================== MUTATION MANAGEMENT ====================

package/src/sp00ky.ts

@@ -754,6 +754,34 @@ export class Sp00kyClient<S extends SchemaStructure> {
     return this.dataModule.run(backend, path, payload, options);
   }
 
+  runRecurring<
+    B extends BackendNames<S>,
+    R extends BackendRoutes<S, B>,
+  >(
+    backend: B,
+    path: R,
+    payload: RoutePayload<S, B, R>,
+    options: RunOptions & { interval: number; assignedTo: string }
+  ) {
+    return this.dataModule.runRecurring(backend, path, payload, options);
+  }
+
+  pokeRecurring<B extends BackendNames<S>>(
+    backend: B,
+    path: BackendRoutes<S, B>,
+    options: { assignedTo: string }
+  ) {
+    return this.dataModule.pokeRecurring(backend, path, options);
+  }
+
+  cancelRecurring<B extends BackendNames<S>>(
+    backend: B,
+    path: BackendRoutes<S, B>,
+    options: { assignedTo: string }
+  ) {
+    return this.dataModule.cancelRecurring(backend, path, options);
+  }
+
   bucket<B extends BucketNames<S>>(name: B): BucketHandle {
     return new BucketHandle(name, this.remote);
   }

package/src/types.ts

@@ -425,6 +425,12 @@ export interface RunOptions {
    * delayed the job stays pending (enqueued) and can still be killed.
    */
   delay?: number;
+  /**
+   * Interval in milliseconds for a RECURRING job (see `runRecurring`). When set,
+   * the job re-runs `interval` ms after each run COMPLETES (drift-free from
+   * completion, not wall-clock). Ignored by the plain `run`.
+   */
+  interval?: number;
 }
 
 /**