@spooky-sync/core 0.0.1-canary.139 → 0.0.1-canary.141

package/dist/index.d.ts

@@ -1191,6 +1191,62 @@ declare class FeatureFlagModule<S extends SchemaStructure> {
   private applyRecords;
 }
 //#endregion
+//#region src/modules/app-release/index.d.ts
+interface AppReleaseSnapshot {
+  /** Latest announced version for the app, or undefined when no row exists. */
+  version: string | undefined;
+  /** Clients should clear SW/caches when reloading onto this version. */
+  cacheBust: boolean;
+  /** Clients should reload/update immediately instead of asking. */
+  mandatory: boolean;
+  releasedAt: string | undefined;
+}
+interface AppReleaseOptions {
+  ttl?: QueryTimeToLive;
+}
+declare class AppReleaseHandle {
+  readonly app: string;
+  private latest;
+  private listeners;
+  private onCloseFn;
+  private closed;
+  constructor(app: string);
+  set(snapshot: AppReleaseSnapshot): void;
+  snapshot(): AppReleaseSnapshot;
+  version(): string | undefined;
+  /** True when the announced version is semver-newer than `currentVersion`. */
+  updateAvailable(currentVersion: string): boolean;
+  subscribe(cb: (s: AppReleaseSnapshot) => void): () => void;
+  onClose(cb: () => void): void;
+  close(): void;
+}
+interface AppReleaseModuleDeps<S extends SchemaStructure> {
+  dataModule: DataModule<S>;
+  sync: Sp00kySync<S>;
+  auth: AuthService<S>;
+  logger: Logger$1;
+}
+declare class AppReleaseModule<S extends SchemaStructure> {
+  private deps;
+  private logger;
+  private handles;
+  private authUnsubscribe;
+  private lastUserId;
+  private querySubscription;
+  private starting;
+  private ttl;
+  private snapshots;
+  private loaded;
+  constructor(deps: AppReleaseModuleDeps<S>);
+  init(): void;
+  release(app: string, options?: AppReleaseOptions): AppReleaseHandle;
+  closeAll(): Promise<void>;
+  private refresh;
+  private teardownQuery;
+  private ensureStarted;
+  private applyRecords;
+}
+//#endregion
 //#region src/sp00ky.d.ts
 declare class BucketHandle {
   private bucketName;
@@ -1217,6 +1273,7 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   private devTools;
   private crdtManager;
   private featureFlags;
+  private appReleases;
   private preloadedHashes;
   private pendingQueryInits;
   private logger;
@@ -1285,6 +1342,14 @@ declare class Sp00kyClient<S extends SchemaStructure> {
    * its own row, and cannot create or modify assignments.
    */
   feature(key: string, options?: FeatureFlagOptions): FeatureFlagHandle;
+  /**
+   * Observe the announced release of an app (`_00_app_release:<app>`, written
+   * by `spky deploy` / `spky release`). The handle's `snapshot()` carries the
+   * announced version plus the cache-bust/mandatory flags, and
+   * `updateAvailable(currentVersion)` compares it semver-wise against the
+   * running build. World-readable; writes are root-only.
+   */
+  appRelease(app: string, options?: AppReleaseOptions): AppReleaseHandle;
   authenticate(token: string): Promise<surrealdb0.Tokens>;
   /**
    * Open a CRDT field for collaborative editing.
@@ -1388,6 +1453,10 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   private fetchSessionId;
 }
 //#endregion
+//#region src/utils/semver.d.ts
+/** True when `a` is a valid version strictly greater than valid version `b`. */
+declare function semverGt(a: unknown, b: unknown): boolean;
+//#endregion
 //#region src/utils/index.d.ts
 declare function fileToUint8Array(file: File | Blob): Promise<Uint8Array>;
 /**
@@ -1400,4 +1469,4 @@ declare function textToHtml(text: string): string;
  */
 
 //#endregion
-export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagSnapshot, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };
+export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagSnapshot, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, semverGt, textToHtml };

package/dist/index.js

@@ -3004,6 +3004,7 @@ var DataModule = class {
 		const record = {
 			path,
 			payload: JSON.stringify(payload),
+			status: "pending",
 			max_retries: options?.max_retries ?? 3,
 			retry_strategy: options?.retry_strategy ?? "linear"
 		};
@@ -5106,8 +5107,8 @@ function parseBackendInfo(raw) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.139";
-const WASM_VERSION = "0.0.1-canary.139";
+const CORE_VERSION = "0.0.1-canary.141";
+const WASM_VERSION = "0.0.1-canary.141";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];
@@ -6907,6 +6908,159 @@ var FeatureFlagModule = class {
 	}
 };
 
+//#endregion
+//#region src/utils/semver.ts
+function parse(v) {
+	const parts = String(v ?? "").trim().split(".");
+	if (parts.length === 0 || parts.length > 3 || parts[0] === "") return null;
+	const nums = [];
+	for (let i = 0; i < 3; i++) {
+		const raw = parts[i] ?? "0";
+		if (!/^\d+$/.test(raw)) return null;
+		nums.push(parseInt(raw, 10));
+	}
+	return nums;
+}
+/** True when `a` is a valid version strictly greater than valid version `b`. */
+function semverGt(a, b) {
+	const pa = parse(a);
+	const pb = parse(b);
+	if (!pa || !pb) return false;
+	for (let i = 0; i < 3; i++) {
+		if (pa[i] > pb[i]) return true;
+		if (pa[i] < pb[i]) return false;
+	}
+	return false;
+}
+
+//#endregion
+//#region src/modules/app-release/index.ts
+const RELEASE_QUERY = "SELECT * FROM _00_app_release";
+const EMPTY_SNAPSHOT = {
+	version: void 0,
+	cacheBust: false,
+	mandatory: false,
+	releasedAt: void 0
+};
+var AppReleaseHandle = class {
+	latest = EMPTY_SNAPSHOT;
+	listeners = /* @__PURE__ */ new Set();
+	onCloseFn = null;
+	closed = false;
+	constructor(app) {
+		this.app = app;
+	}
+	set(snapshot) {
+		if (this.closed) return;
+		this.latest = snapshot;
+		for (const cb of this.listeners) cb(snapshot);
+	}
+	snapshot() {
+		return this.latest;
+	}
+	version() {
+		return this.latest.version;
+	}
+	/** True when the announced version is semver-newer than `currentVersion`. */
+	updateAvailable(currentVersion) {
+		return semverGt(this.latest.version, currentVersion);
+	}
+	subscribe(cb) {
+		this.listeners.add(cb);
+		cb(this.latest);
+		return () => {
+			this.listeners.delete(cb);
+		};
+	}
+	onClose(cb) {
+		this.onCloseFn = cb;
+	}
+	close() {
+		if (this.closed) return;
+		this.closed = true;
+		this.listeners.clear();
+		this.onCloseFn?.();
+	}
+};
+var AppReleaseModule = class {
+	logger;
+	handles = /* @__PURE__ */ new Set();
+	authUnsubscribe = null;
+	lastUserId = null;
+	querySubscription = null;
+	starting = false;
+	ttl = "10m";
+	snapshots = /* @__PURE__ */ new Map();
+	loaded = false;
+	constructor(deps) {
+		this.deps = deps;
+		this.logger = deps.logger.child({ service: "AppReleaseModule" });
+	}
+	init() {
+		if (this.authUnsubscribe) return;
+		this.authUnsubscribe = this.deps.auth.subscribe((userId) => {
+			if (userId === this.lastUserId) return;
+			this.lastUserId = userId;
+			this.refresh();
+		});
+	}
+	release(app, options = {}) {
+		const handle = new AppReleaseHandle(app);
+		this.handles.add(handle);
+		handle.onClose(() => this.handles.delete(handle));
+		if (options.ttl) this.ttl = options.ttl;
+		if (this.loaded) handle.set(this.snapshots.get(app) ?? EMPTY_SNAPSHOT);
+		this.ensureStarted();
+		return handle;
+	}
+	async closeAll() {
+		this.authUnsubscribe?.();
+		this.authUnsubscribe = null;
+		this.teardownQuery();
+		for (const handle of [...this.handles]) handle.close();
+	}
+	async refresh() {
+		this.teardownQuery();
+		this.loaded = false;
+		this.snapshots.clear();
+		await this.ensureStarted();
+	}
+	teardownQuery() {
+		this.querySubscription?.();
+		this.querySubscription = null;
+	}
+	async ensureStarted() {
+		if (this.querySubscription || this.starting || this.handles.size === 0) return;
+		this.starting = true;
+		try {
+			const hash = await this.deps.dataModule.query("_00_app_release", RELEASE_QUERY, {}, this.ttl);
+			this.deps.sync.enqueueDownEvent({
+				type: "register",
+				payload: { hash }
+			});
+			this.querySubscription = this.deps.dataModule.subscribe(hash, (records) => this.applyRecords(records), { immediate: true });
+		} catch (err) {
+			this.logger.warn({
+				err,
+				Category: "sp00ky-client::AppReleaseModule::register"
+			}, "Failed to register app release query");
+		} finally {
+			this.starting = false;
+		}
+	}
+	applyRecords(records) {
+		this.snapshots.clear();
+		for (const row of records ?? []) if (row && typeof row.app === "string" && typeof row.version === "string") this.snapshots.set(row.app, {
+			version: row.version,
+			cacheBust: row.cache_bust === true,
+			mandatory: row.mandatory === true,
+			releasedAt: row.released_at
+		});
+		this.loaded = true;
+		for (const handle of this.handles) handle.set(this.snapshots.get(handle.app) ?? EMPTY_SNAPSHOT);
+	}
+};
+
 //#endregion
 //#region src/services/persistence/localstorage.ts
 var LocalStoragePersistenceClient = class {
@@ -7084,6 +7238,7 @@ var Sp00kyClient = class {
 	devTools;
 	crdtManager;
 	featureFlags;
+	appReleases;
 	preloadedHashes = /* @__PURE__ */ new Set();
 	pendingQueryInits = /* @__PURE__ */ new Map();
 	logger;
@@ -7157,6 +7312,12 @@ var Sp00kyClient = class {
 			auth: this.auth,
 			logger
 		});
+		this.appReleases = new AppReleaseModule({
+			dataModule: this.dataModule,
+			sync: this.sync,
+			auth: this.auth,
+			logger
+		});
 		this.devTools = new DevToolsService(this.local, this.remote, logger, this.config.schema, this.auth, this.dataModule);
 		this.streamProcessor.addReceiver(this.devTools);
 		this.setupCallbacks();
@@ -7265,6 +7426,8 @@ var Sp00kyClient = class {
 			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "Sync initialized");
 			this.featureFlags.init();
 			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "FeatureFlagModule initialized");
+			this.appReleases.init();
+			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "AppReleaseModule initialized");
 			this.logger.info({ Category: "sp00ky-client::Sp00kyClient::init" }, "Sp00kyClient initialization completed successfully");
 		} catch (e) {
 			this.logger.error({
@@ -7362,6 +7525,7 @@ var Sp00kyClient = class {
 	}
 	async close() {
 		await this.featureFlags.closeAll();
+		await this.appReleases.closeAll();
 		this.crdtManager.closeAll();
 		await this.local.close();
 		await this.remote.close();
@@ -7378,6 +7542,16 @@ var Sp00kyClient = class {
 	feature(key, options) {
 		return this.featureFlags.feature(key, options);
 	}
+	/**
+	* Observe the announced release of an app (`_00_app_release:<app>`, written
+	* by `spky deploy` / `spky release`). The handle's `snapshot()` carries the
+	* announced version plus the cache-bust/mandatory flags, and
+	* `updateAvailable(currentVersion)` compares it semver-wise against the
+	* running build. World-readable; writes are root-only.
+	*/
+	appRelease(app, options) {
+		return this.appReleases.release(app, options);
+	}
 	authenticate(token) {
 		return this.remote.getClient().authenticate(token);
 	}
@@ -7600,4 +7774,4 @@ var Sp00kyClient = class {
 };
 
 //#endregion
-export { AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, FeatureFlagHandle, FeatureFlagModule, MATERIALIZATION_SAMPLE_WINDOW, Sp00kyClient, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };
+export { AppReleaseHandle, AppReleaseModule, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, FeatureFlagHandle, FeatureFlagModule, MATERIALIZATION_SAMPLE_WINDOW, Sp00kyClient, createAuthEventSystem, cursorColorFromName, fileToUint8Array, semverGt, textToHtml };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.139",
+  "version": "0.0.1-canary.141",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -60,8 +60,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.139",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.139",
+    "@spooky-sync/query-builder": "0.0.1-canary.141",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.141",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",

package/src/index.ts

@@ -8,4 +8,11 @@ export {
   type FeatureFlagOptions,
   type FeatureFlagSnapshot,
 } from './modules/feature-flag/index';
+export {
+  AppReleaseModule,
+  AppReleaseHandle,
+  type AppReleaseOptions,
+  type AppReleaseSnapshot,
+} from './modules/app-release/index';
+export { semverGt } from './utils/semver';
 export { fileToUint8Array, textToHtml } from './utils/index';

package/src/modules/app-release/index.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { AppReleaseModule } from './index';
+
+// Mirrors the FeatureFlagModule test rig: the DataModule mock captures the
+// single subscribe callback so tests can push live results, and counts
+// query() calls to assert the query is SHARED across apps.
+function makeDeps() {
+  let subCb: ((records: unknown[]) => void) | null = null;
+  const calls: Array<{ sql: string; params: unknown }> = [];
+  let authCb: ((userId: string | null) => void) | null = null;
+
+  const dataModule = {
+    query: async (_table: string, sql: string, params: unknown) => {
+      calls.push({ sql, params });
+      return `hash:${calls.length}`;
+    },
+    subscribe: (_hash: string, cb: (records: unknown[]) => void) => {
+      subCb = cb;
+      return () => {
+        subCb = null;
+      };
+    },
+  };
+  const sync = { enqueueDownEvent: () => {} };
+  const auth = {
+    subscribe: (cb: (userId: string | null) => void) => {
+      authCb = cb;
+      return () => {
+        authCb = null;
+      };
+    },
+  };
+  const logger = { child: () => ({ warn: () => {} }) };
+
+  const deps = { dataModule, sync, auth, logger } as any;
+  return {
+    deps,
+    calls,
+    push: (records: unknown[]) => subCb?.(records),
+    setUser: (id: string | null) => authCb?.(id),
+    hasSub: () => subCb !== null,
+  };
+}
+
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+describe('AppReleaseModule', () => {
+  let env: ReturnType<typeof makeDeps>;
+  let mod: AppReleaseModule<any>;
+
+  beforeEach(() => {
+    env = makeDeps();
+    mod = new AppReleaseModule(env.deps);
+  });
+
+  it('registers ONE shared, unfiltered query for many apps', async () => {
+    mod.release('web');
+    mod.release('admin');
+    await tick();
+
+    expect(env.calls.length).toBe(1);
+    expect(env.calls[0].sql).not.toContain('WHERE');
+    expect(env.calls[0].sql).toContain('FROM _00_app_release');
+  });
+
+  it('fans the shared result out to each handle by app', async () => {
+    const web = mod.release('web');
+    const missing = mod.release('missing');
+    await tick();
+
+    env.push([{ app: 'web', version: '1.2.0', cache_bust: true, mandatory: null }]);
+
+    expect(web.version()).toBe('1.2.0');
+    expect(web.snapshot().cacheBust).toBe(true);
+    expect(web.snapshot().mandatory).toBe(false);
+    expect(missing.version()).toBeUndefined();
+    expect(missing.updateAvailable('1.0.0')).toBe(false);
+  });
+
+  it('updateAvailable compares semver against the running build', async () => {
+    const web = mod.release('web');
+    await tick();
+
+    env.push([{ app: 'web', version: '1.2.0' }]);
+    expect(web.updateAvailable('1.1.9')).toBe(true);
+    expect(web.updateAvailable('1.2.0')).toBe(false);
+    expect(web.updateAvailable('1.3.0')).toBe(false);
+    expect(web.updateAvailable('garbage')).toBe(false);
+  });
+
+  it('observes row updates live without re-registering', async () => {
+    const web = mod.release('web');
+    await tick();
+
+    env.push([{ app: 'web', version: '1.0.0' }]);
+    expect(web.updateAvailable('1.0.0')).toBe(false);
+
+    env.push([{ app: 'web', version: '1.0.1', mandatory: true }]);
+    expect(web.updateAvailable('1.0.0')).toBe(true);
+    expect(web.snapshot().mandatory).toBe(true);
+
+    expect(env.calls.length).toBe(1);
+  });
+
+  it('seeds a late-created handle from the already-loaded snapshot', async () => {
+    mod.release('web');
+    await tick();
+    env.push([{ app: 'web', version: '2.0.0' }]);
+
+    const late = mod.release('web');
+    expect(late.version()).toBe('2.0.0');
+  });
+
+  it('re-registers on user change', async () => {
+    mod.init();
+    const web = mod.release('web');
+    await tick();
+    env.push([{ app: 'web', version: '1.0.0' }]);
+    expect(web.version()).toBe('1.0.0');
+
+    env.setUser('user:other');
+    await tick();
+    expect(env.hasSub()).toBe(true); // re-registered under the new session
+  });
+});

package/src/modules/app-release/index.ts

@@ -0,0 +1,201 @@
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+import type { DataModule } from '../data/index';
+import type { Sp00kySync } from '../sync/index';
+import type { AuthService } from '../auth/index';
+import type { Logger } from '../../services/logger/index';
+import type { QueryTimeToLive } from '../../types';
+import { semverGt } from '../../utils/semver';
+
+// One shared LIVE query over every app's release row. `_00_app_release` is
+// world-readable (root-only writes), one row per app keyed by name — written
+// by `spky deploy` / `spky release` / the git-linked builder. A single
+// registration observes every app at once; a handle for an app with no row
+// simply reports no update. Mirrors the FeatureFlagModule design.
+const RELEASE_QUERY = 'SELECT * FROM _00_app_release';
+
+interface ReleaseRow {
+  app?: string;
+  version?: string;
+  cache_bust?: boolean | null;
+  mandatory?: boolean | null;
+  released_at?: string;
+}
+
+export interface AppReleaseSnapshot {
+  /** Latest announced version for the app, or undefined when no row exists. */
+  version: string | undefined;
+  /** Clients should clear SW/caches when reloading onto this version. */
+  cacheBust: boolean;
+  /** Clients should reload/update immediately instead of asking. */
+  mandatory: boolean;
+  releasedAt: string | undefined;
+}
+
+const EMPTY_SNAPSHOT: AppReleaseSnapshot = {
+  version: undefined,
+  cacheBust: false,
+  mandatory: false,
+  releasedAt: undefined,
+};
+
+export interface AppReleaseOptions {
+  ttl?: QueryTimeToLive;
+}
+
+export class AppReleaseHandle {
+  private latest: AppReleaseSnapshot = EMPTY_SNAPSHOT;
+  private listeners = new Set<(s: AppReleaseSnapshot) => void>();
+  private onCloseFn: (() => void) | null = null;
+  private closed = false;
+
+  constructor(public readonly app: string) {}
+
+  set(snapshot: AppReleaseSnapshot): void {
+    if (this.closed) return;
+    this.latest = snapshot;
+    for (const cb of this.listeners) cb(snapshot);
+  }
+
+  snapshot(): AppReleaseSnapshot {
+    return this.latest;
+  }
+
+  version(): string | undefined {
+    return this.latest.version;
+  }
+
+  /** True when the announced version is semver-newer than `currentVersion`. */
+  updateAvailable(currentVersion: string): boolean {
+    return semverGt(this.latest.version, currentVersion);
+  }
+
+  subscribe(cb: (s: AppReleaseSnapshot) => void): () => void {
+    this.listeners.add(cb);
+    cb(this.latest);
+    return () => {
+      this.listeners.delete(cb);
+    };
+  }
+
+  onClose(cb: () => void): void {
+    this.onCloseFn = cb;
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.listeners.clear();
+    this.onCloseFn?.();
+  }
+}
+
+export interface AppReleaseModuleDeps<S extends SchemaStructure> {
+  dataModule: DataModule<S>;
+  sync: Sp00kySync<S>;
+  auth: AuthService<S>;
+  logger: Logger;
+}
+
+export class AppReleaseModule<S extends SchemaStructure> {
+  private logger: Logger;
+  private handles = new Set<AppReleaseHandle>();
+  private authUnsubscribe: (() => void) | null = null;
+  private lastUserId: string | null = null;
+
+  private querySubscription: (() => void) | null = null;
+  private starting = false;
+  private ttl: QueryTimeToLive = '10m';
+  private snapshots = new Map<string, AppReleaseSnapshot>();
+  private loaded = false;
+
+  constructor(private deps: AppReleaseModuleDeps<S>) {
+    this.logger = deps.logger.child({ service: 'AppReleaseModule' });
+  }
+
+  init(): void {
+    if (this.authUnsubscribe) return;
+    // Auth changes re-register the shared query (a new session invalidates the
+    // old SSP plan). The table itself is world-readable, so the data is the
+    // same for every user — this is purely plumbing hygiene.
+    this.authUnsubscribe = this.deps.auth.subscribe((userId) => {
+      if (userId === this.lastUserId) return;
+      this.lastUserId = userId;
+      void this.refresh();
+    });
+  }
+
+  release(app: string, options: AppReleaseOptions = {}): AppReleaseHandle {
+    const handle = new AppReleaseHandle(app);
+    this.handles.add(handle);
+    handle.onClose(() => this.handles.delete(handle));
+    if (options.ttl) this.ttl = options.ttl;
+    if (this.loaded) {
+      handle.set(this.snapshots.get(app) ?? EMPTY_SNAPSHOT);
+    }
+    void this.ensureStarted();
+    return handle;
+  }
+
+  async closeAll(): Promise<void> {
+    this.authUnsubscribe?.();
+    this.authUnsubscribe = null;
+    this.teardownQuery();
+    for (const handle of [...this.handles]) handle.close();
+  }
+
+  private async refresh(): Promise<void> {
+    this.teardownQuery();
+    this.loaded = false;
+    this.snapshots.clear();
+    await this.ensureStarted();
+  }
+
+  private teardownQuery(): void {
+    this.querySubscription?.();
+    this.querySubscription = null;
+  }
+
+  private async ensureStarted(): Promise<void> {
+    if (this.querySubscription || this.starting || this.handles.size === 0) return;
+    this.starting = true;
+    try {
+      const hash = await this.deps.dataModule.query(
+        '_00_app_release' as any,
+        RELEASE_QUERY,
+        {},
+        this.ttl,
+      );
+      this.deps.sync.enqueueDownEvent({ type: 'register', payload: { hash } });
+      this.querySubscription = this.deps.dataModule.subscribe(
+        hash,
+        (records) => this.applyRecords(records as ReleaseRow[]),
+        { immediate: true },
+      );
+    } catch (err) {
+      this.logger.warn(
+        { err, Category: 'sp00ky-client::AppReleaseModule::register' },
+        'Failed to register app release query',
+      );
+    } finally {
+      this.starting = false;
+    }
+  }
+
+  private applyRecords(records: ReleaseRow[]): void {
+    this.snapshots.clear();
+    for (const row of records ?? []) {
+      if (row && typeof row.app === 'string' && typeof row.version === 'string') {
+        this.snapshots.set(row.app, {
+          version: row.version,
+          cacheBust: row.cache_bust === true,
+          mandatory: row.mandatory === true,
+          releasedAt: row.released_at,
+        });
+      }
+    }
+    this.loaded = true;
+    for (const handle of this.handles) {
+      handle.set(this.snapshots.get(handle.app) ?? EMPTY_SNAPSHOT);
+    }
+  }
+}

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

@@ -57,6 +57,7 @@ describe('DataModule.runRecurring', () => {
     expect(record.next_run_at).toBeInstanceOf(Date);
     expect(record.assigned_to).toBe(CONN);
     expect(record.path).toBe('/syncGames');
+    expect(record.status).toBe('pending');
     expect(JSON.parse(record.payload)).toEqual({ connection: CONN });
   });
 
@@ -103,6 +104,21 @@ describe('DataModule.runRecurring', () => {
   });
 });
 
+describe('DataModule.run', () => {
+  it('creates the one-shot job with status pending so the optimistic row reads in-flight', async () => {
+    const { dm, create } = makeDm([]);
+    await dm.run('gamesync' as any, '/syncGames' as any, { connection: CONN } as any, { assignedTo: CONN });
+
+    expect(create).toHaveBeenCalledTimes(1);
+    const [id, record] = create.mock.calls[0] as [string, any];
+    expect(id.startsWith('job:')).toBe(true);
+    // The schema's DEFAULT ALWAYS "pending" only runs server-side; without the
+    // explicit field the local optimistic row has status undefined and
+    // in-flight indicators miss it until the first server echo.
+    expect(record.status).toBe('pending');
+  });
+});
+
 describe('DataModule.pokeRecurring', () => {
   it('bumps next_run_at on the existing schedule row', async () => {
     const { dm, update } = makeDm([{ id: 'job:x' }]);

package/src/modules/data/index.ts

@@ -1205,6 +1205,11 @@ export class DataModule<S extends SchemaStructure> {
     const record: Record<string, unknown> = {
       path,
       payload: JSON.stringify(payload),
+      // Set explicitly: the schema's DEFAULT ALWAYS "pending" is server-side
+      // only. An optimistic local create without it surfaces with status
+      // undefined, so in-flight indicators keyed on pending/processing stay
+      // off until the first server echo (seconds on a delayed job).
+      status: 'pending',
       max_retries: options?.max_retries ?? 3,
       retry_strategy: options?.retry_strategy ?? 'linear',
     };

package/src/sp00ky.ts

@@ -46,6 +46,8 @@ import { CrdtManager, CrdtField } from './modules/crdt/index';
 import { preloadLoro } from './modules/crdt/loro-loader';
 import { FeatureFlagModule, FeatureFlagHandle } from './modules/feature-flag/index';
 import type { FeatureFlagOptions } from './modules/feature-flag/index';
+import { AppReleaseModule, AppReleaseHandle } from './modules/app-release/index';
+import type { AppReleaseOptions } from './modules/app-release/index';
 import { LocalStoragePersistenceClient } from './services/persistence/localstorage';
 import { ANON_USER_ID, bucketIdForUser } from './modules/ref-tables';
 import { parseParams, encodeRecordId, parseDuration } from './utils/index';
@@ -132,6 +134,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
   private devTools: DevToolsService;
   private crdtManager: CrdtManager;
   private featureFlags!: FeatureFlagModule<S>;
+  private appReleases!: AppReleaseModule<S>;
   // Query hashes already preloaded this session — skip redundant one-shot
   // fetches when the same preload query is requested again (e.g. a list row
   // re-rendering). Cleared on process/session end only.
@@ -291,6 +294,15 @@ export class Sp00kyClient<S extends SchemaStructure> {
       logger,
     });
 
+    // App release announcements (world-readable `_00_app_release`, written by
+    // spky deploy/release). Same shared-live-query design as feature flags.
+    this.appReleases = new AppReleaseModule({
+      dataModule: this.dataModule,
+      sync: this.sync,
+      auth: this.auth,
+      logger,
+    });
+
     // Initialize DevTools
     this.devTools = new DevToolsService(
       this.local,
@@ -503,6 +515,12 @@ export class Sp00kyClient<S extends SchemaStructure> {
         'FeatureFlagModule initialized'
       );
 
+      this.appReleases.init();
+      this.logger.debug(
+        { Category: 'sp00ky-client::Sp00kyClient::init' },
+        'AppReleaseModule initialized'
+      );
+
       this.logger.info(
         { Category: 'sp00ky-client::Sp00kyClient::init' },
         'Sp00kyClient initialization completed successfully'
@@ -636,6 +654,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
 
   async close() {
     await this.featureFlags.closeAll();
+    await this.appReleases.closeAll();
     this.crdtManager.closeAll();
     await this.local.close();
     await this.remote.close();
@@ -654,6 +673,17 @@ export class Sp00kyClient<S extends SchemaStructure> {
     return this.featureFlags.feature(key, options);
   }
 
+  /**
+   * Observe the announced release of an app (`_00_app_release:<app>`, written
+   * by `spky deploy` / `spky release`). The handle's `snapshot()` carries the
+   * announced version plus the cache-bust/mandatory flags, and
+   * `updateAvailable(currentVersion)` compares it semver-wise against the
+   * running build. World-readable; writes are root-only.
+   */
+  appRelease(app: string, options?: AppReleaseOptions): AppReleaseHandle {
+    return this.appReleases.release(app, options);
+  }
+
   authenticate(token: string) {
     return this.remote.getClient().authenticate(token);
   }

package/src/utils/semver.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import { semverGt } from './semver';
+
+describe('semverGt', () => {
+  it('compares strictly greater', () => {
+    expect(semverGt('1.0.1', '1.0.0')).toBe(true);
+    expect(semverGt('1.1.0', '1.0.9')).toBe(true);
+    expect(semverGt('2.0.0', '1.9.9')).toBe(true);
+    expect(semverGt('1.10.0', '1.9.0')).toBe(true); // numeric, not lexicographic
+  });
+
+  it('equal and lower are not greater', () => {
+    expect(semverGt('1.0.0', '1.0.0')).toBe(false);
+    expect(semverGt('1.0.0', '1.0.1')).toBe(false);
+    expect(semverGt('0.9.9', '1.0.0')).toBe(false);
+  });
+
+  it('missing parts default to zero', () => {
+    expect(semverGt('1.2', '1.2.0')).toBe(false);
+    expect(semverGt('1.2.1', '1.2')).toBe(true);
+    expect(semverGt('2', '1.9.9')).toBe(true);
+  });
+
+  it('junk never compares greater', () => {
+    expect(semverGt('abc', '1.0.0')).toBe(false);
+    expect(semverGt('1.0.0', 'abc')).toBe(false);
+    expect(semverGt('', '0.0.0')).toBe(false);
+    expect(semverGt(null, undefined)).toBe(false);
+    expect(semverGt('1.0.0-beta', '0.9.0')).toBe(false); // prerelease unsupported
+    expect(semverGt('1.2.3.4', '1.0.0')).toBe(false);
+  });
+});

package/src/utils/semver.ts

@@ -0,0 +1,30 @@
+// Minimal semver comparison for app-release version checks. "X.Y.Z" numeric
+// with missing parts read as 0 ("1.2" == "1.2.0"); any malformed input never
+// compares greater, so a bad release row can never nag (or force-reload)
+// every client.
+
+function parse(v: unknown): [number, number, number] | null {
+  const parts = String(v ?? '')
+    .trim()
+    .split('.');
+  if (parts.length === 0 || parts.length > 3 || parts[0] === '') return null;
+  const nums: number[] = [];
+  for (let i = 0; i < 3; i++) {
+    const raw = parts[i] ?? '0';
+    if (!/^\d+$/.test(raw)) return null;
+    nums.push(parseInt(raw, 10));
+  }
+  return nums as [number, number, number];
+}
+
+/** True when `a` is a valid version strictly greater than valid version `b`. */
+export function semverGt(a: unknown, b: unknown): boolean {
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return false;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] > pb[i]) return true;
+    if (pa[i] < pb[i]) return false;
+  }
+  return false;
+}