@selvajs/supabase-provider 0.14.2 → 0.14.4-beta.0

package/src/data/__tests__/share-link-concurrency.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Audit Q4/Q5 — the concurrent-solve guarantee for share-link caps.
+ *
+ * `tryIncrementSolveCount` is the load-bearing race-sensitive method: the
+ * `/api/compute` endpoint calls it BEFORE solving and turns a `null` return
+ * (cap hit) into HTTP 429. Under concurrent solves against one capped link, the
+ * cap must hold exactly — no overshoot, no lost update handing two solves the
+ * same slot. Supabase provides this via the SECURITY DEFINER
+ * `try_increment_share_link_solve_count` RPC, which does the check-and-increment
+ * in a single statement.
+ *
+ * This lives in the Supabase suite (not the shared conformance suite or the app
+ * route tests) because it is the ONLY backend that actually provides the
+ * guarantee: the local provider's whole-file read-modify-write is a documented
+ * dev-scale tradeoff and is not concurrency-safe. Skipped without a live stack,
+ * matching the other conformance tests here.
+ *
+ * Complements the sequential cap/count tests at
+ * `packages/selva/src/routes/api/compute/__tests__/solve-cap-and-count.test.ts`.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import type { RequestContext, ShareLink } from '@selvajs/platform';
+import { SupabaseShareLinkStore } from '../SupabaseShareLinkStore.js';
+import { readEnv, resetAllData, seedUser } from './test-helpers.js';
+
+const envCtx = readEnv();
+
+if (!envCtx) {
+	describe.skip('SupabaseShareLinkStore concurrency (skipped: no live stack)', () => {
+		it('populate packages/providers/supabase/.env.test with Supabase creds to run these tests', () => {});
+	});
+} else {
+	const ctx: RequestContext = { userId: '', system: true } as RequestContext;
+
+	/** Seed org → project → definition → share link, all via service-role. */
+	async function seedCappedLink(maxSolves: number): Promise<{ linkId: string }> {
+		const { userId: ownerId } = await seedUser(envCtx!, '');
+		const admin = envCtx!.adminClient;
+		const orgId = crypto.randomUUID();
+		const projectId = crypto.randomUUID();
+		const definitionId = crypto.randomUUID();
+		const linkId = crypto.randomUUID();
+		const now = new Date().toISOString();
+
+		const { error: orgErr } = await admin.from('orgs').insert({
+			id: orgId,
+			name: 'Concurrency Org',
+			slug: `conc-${orgId.slice(0, 8)}`,
+			owner_id: ownerId,
+			created_at: now,
+			updated_at: now
+		});
+		if (orgErr) throw orgErr;
+		const { error: projErr } = await admin.from('projects').insert({
+			id: projectId,
+			org_id: orgId,
+			name: 'Project',
+			slug: `proj-${projectId.slice(0, 8)}`,
+			visibility: 'public',
+			owner_id: ownerId,
+			created_at: now,
+			updated_at: now
+		});
+		if (projErr) throw projErr;
+		const { error: defErr } = await admin.from('definitions').insert({
+			guid: definitionId,
+			project_id: projectId,
+			owner_id: ownerId,
+			display_name: 'Def',
+			status: 'published',
+			created_at: now,
+			updated_at: now
+		});
+		if (defErr) throw defErr;
+
+		const link: ShareLink = {
+			id: linkId,
+			definitionId,
+			channel: 'live',
+			tokenHash: crypto.randomUUID().replace(/-/g, ''),
+			createdBy: ownerId,
+			createdAt: now,
+			expiresAt: null,
+			revokedAt: null,
+			allowSolve: true,
+			maxSolves,
+			solveCount: 0
+		};
+		const store = new SupabaseShareLinkStore(envCtx!.bundle);
+		await store.create(ctx, link);
+		return { linkId };
+	}
+
+	describe('SupabaseShareLinkStore — concurrent solve-cap enforcement', () => {
+		beforeEach(async () => {
+			await resetAllData(envCtx!);
+		});
+
+		it('N concurrent solves against a cap-K link admit exactly K, refuse the rest', async () => {
+			const CAP = 5;
+			const ATTEMPTS = 25;
+			const { linkId } = await seedCappedLink(CAP);
+			const store = new SupabaseShareLinkStore(envCtx!.bundle);
+
+			const outcomes = await Promise.all(
+				Array.from({ length: ATTEMPTS }, () => store.tryIncrementSolveCount(ctx, linkId))
+			);
+
+			const admitted = outcomes.filter((n): n is number => n !== null);
+			const refused = outcomes.filter((n) => n === null);
+			// Exactly CAP admitted — the atomic RPC never lets a concurrent burst
+			// overshoot the cap.
+			expect(admitted).toHaveLength(CAP);
+			expect(refused).toHaveLength(ATTEMPTS - CAP);
+			// Each admitted solve got a distinct slot 1..CAP — no lost update.
+			expect([...admitted].sort((a, b) => a - b)).toEqual([1, 2, 3, 4, 5]);
+
+			// The persisted count settles at exactly the cap.
+			const finalLink = await store.getById(ctx, linkId);
+			expect(finalLink?.solveCount).toBe(CAP);
+		});
+	});
+}

package/src/data/client.ts

@@ -10,6 +10,27 @@ import type { RequestContext } from '@selvajs/platform';
  */
 export type SelvaSchemaClient = SupabaseClient<any, 'public', 'selva'>;
 
+/** Default schema every engine store targets. */
+export const DEFAULT_SCHEMA = 'selva' as const;
+
+/**
+ * A client pinned to a caller-chosen schema. When the schema is `'selva'` this
+ * is the narrow `SelvaSchemaClient`; for an app-owned schema (e.g. `'public'`)
+ * the schema generic is opaque — the store surface (`.from` / `.rpc`) is the
+ * same either way.
+ */
+export type SchemaClient = SupabaseClient<any, string, any>;
+
+export interface ForRequestOptions {
+	/**
+	 * Postgres schema this client targets. Defaults to `'selva'` (the engine's
+	 * tables). Pass `'public'` (or another app schema) to build stores on the
+	 * consuming app's own tables while keeping the same fail-closed RLS
+	 * dispatch as the engine stores.
+	 */
+	schema?: string;
+}
+
 /**
  * Build a Supabase client for a given `RequestContext`.
  *
@@ -35,15 +56,20 @@ export type SelvaSchemaClient = SupabaseClient<any, 'public', 'selva'>;
  * fetch connection without leaking auth across requests.
  */
 export interface ClientBundle {
-	/** Long-lived service-role client. Bypasses RLS. */
+	/** Long-lived service-role client, pinned to the `'selva'` schema. Bypasses RLS. */
 	serviceClient: SelvaSchemaClient;
 	/**
-	 * Produce (or reuse) a client scoped to this request's identity.
+	 * Produce (or reuse) a client scoped to this request's identity, targeting
+	 * `opts.schema` (default `'selva'`).
 	 *  - `ctx.system === true` → service-role (RLS bypassed).
 	 *  - `ctx.adapterContext.sessionToken` set → user-scoped (RLS active).
 	 *  - neither → anon client (RLS active, no `auth.uid()`).
+	 *
+	 * The schema pin and the RLS dispatch travel together: an app building
+	 * stores on its own `'public'` tables gets the same fail-closed behavior as
+	 * engine stores, just aimed at a different schema.
 	 */
-	forRequest(ctx: RequestContext): SelvaSchemaClient;
+	forRequest(ctx: RequestContext, opts?: ForRequestOptions): SchemaClient;
 }
 
 export interface BuildClientOptions {
@@ -53,44 +79,93 @@ export interface BuildClientOptions {
 }
 
 export function buildClientBundle(opts: BuildClientOptions): ClientBundle {
-	const serviceClient = createClient(opts.supabaseUrl, opts.serviceRoleKey, {
-		db: { schema: 'selva' },
-		auth: { persistSession: false, autoRefreshToken: false }
-	});
+	// Long-lived service-role + anon clients, one per schema. Both are stateless
+	// w.r.t. request identity, so a single instance is safe to share across all
+	// requests targeting the same schema.
+	const serviceBySchema = new Map<string, SchemaClient>();
+	const anonBySchema = new Map<string, SchemaClient>();
+
+	function serviceFor(schema: string): SchemaClient {
+		let client = serviceBySchema.get(schema);
+		if (!client) {
+			client = createClient(opts.supabaseUrl, opts.serviceRoleKey, {
+				db: { schema },
+				auth: { persistSession: false, autoRefreshToken: false }
+			});
+			serviceBySchema.set(schema, client);
+		}
+		return client;
+	}
+
+	function anonFor(schema: string): SchemaClient {
+		let client = anonBySchema.get(schema);
+		if (!client) {
+			client = createClient(opts.supabaseUrl, opts.anonKey, {
+				db: { schema },
+				auth: { persistSession: false, autoRefreshToken: false }
+			});
+			anonBySchema.set(schema, client);
+		}
+		return client;
+	}
 
-	// Long-lived anon client — the fail-closed default for ctxes that aren't
-	// explicitly system and don't carry a session token.
-	const anonClient = createClient(opts.supabaseUrl, opts.anonKey, {
-		db: { schema: 'selva' },
-		auth: { persistSession: false, autoRefreshToken: false }
-	});
+	// The `'selva'`-pinned service client is exposed directly on the bundle for
+	// engine code that reaches for RLS-bypassing reads without a request context.
+	const serviceClient = serviceFor(DEFAULT_SCHEMA) as SelvaSchemaClient;
 
-	const perRequestCache = new WeakMap<RequestContext, SelvaSchemaClient>();
+	// Per-request user-scoped clients, keyed first by context then by schema so
+	// a handler that touches both `'selva'` and an app schema reuses one client
+	// per (request, schema) without leaking auth across requests.
+	const perRequestCache = new WeakMap<RequestContext, Map<string, SchemaClient>>();
 
 	return {
 		serviceClient,
-		forRequest(ctx: RequestContext): SelvaSchemaClient {
-			if (ctx.system) return serviceClient;
+		forRequest(ctx: RequestContext, forOpts?: ForRequestOptions): SchemaClient {
+			const schema = forOpts?.schema ?? DEFAULT_SCHEMA;
+			if (ctx.system) return serviceFor(schema);
 
 			const token = extractSessionToken(ctx.adapterContext);
-			if (!token) return anonClient;
+			if (!token) return anonFor(schema);
 
-			const cached = perRequestCache.get(ctx);
+			let bySchema = perRequestCache.get(ctx);
+			if (!bySchema) {
+				bySchema = new Map();
+				perRequestCache.set(ctx, bySchema);
+			}
+			const cached = bySchema.get(schema);
 			if (cached) return cached;
 
 			const client = createClient(opts.supabaseUrl, opts.anonKey, {
-				db: { schema: 'selva' },
+				db: { schema },
 				auth: { persistSession: false, autoRefreshToken: false },
 				global: {
 					headers: { Authorization: `Bearer ${token}` }
 				}
 			});
-			perRequestCache.set(ctx, client);
+			bySchema.set(schema, client);
 			return client;
 		}
 	};
 }
 
+/**
+ * Build a `ClientBundle` straight from environment variables — the
+ * `SUPABASE_URL` / `SUPABASE_ANON_KEY` / `SUPABASE_SERVICE_ROLE_KEY` triple,
+ * nothing else. Deliberately does NOT require `SELVA_AT_REST_KEY`: that key
+ * only matters for compute-server secret encryption, which a consuming app
+ * building its own `'public'` stores never touches. `SupabaseDataProvider.fromEnv`
+ * layers the at-rest-key requirement on top of this.
+ */
+export function clientBundleFromEnv(env: Record<string, string | undefined>): ClientBundle {
+	const supabaseUrl = env.SUPABASE_URL;
+	const anonKey = env.SUPABASE_ANON_KEY;
+	const serviceRoleKey = env.SUPABASE_SERVICE_ROLE_KEY;
+	if (!supabaseUrl) throw new Error('Missing required env var: SUPABASE_URL');
+	if (!anonKey) throw new Error('Missing required env var: SUPABASE_ANON_KEY');
+	if (!serviceRoleKey) throw new Error('Missing required env var: SUPABASE_SERVICE_ROLE_KEY');
+	return buildClientBundle({ supabaseUrl, anonKey, serviceRoleKey });
+}
+
 function extractSessionToken(adapterContext: unknown): string | undefined {
 	if (!adapterContext || typeof adapterContext !== 'object') return undefined;
 	const maybe = (adapterContext as { sessionToken?: unknown }).sessionToken;

package/src/data/errors.ts

@@ -0,0 +1,45 @@
+import { ProviderError } from '@selvajs/platform';
+
+/**
+ * Canonical PostgREST/Postgres error translation shared by every Supabase
+ * store. Replaces the six near-identical private `mapError` copies that had
+ * drifted into two variants (a "full" one preserving `details`/`hint`, and a
+ * slimmer message-only one) and none of which handled `PGRST116`.
+ *
+ * Mapping:
+ *  - `PGRST116` (single-row selector matched zero rows) → 404. PostgREST
+ *    raises this when `.single()` finds nothing; treating it as "not found"
+ *    is almost always what a store's caller wants.
+ *  - `23505` (unique violation) / `23503` (foreign-key violation) → 409.
+ *  - Anything else → a plain `Error` (500 downstream via `api-errors`), with
+ *    `details`/`hint`/`code` preserved on the error object for logs.
+ */
+
+/** The subset of a `PostgrestError` this mapper inspects. */
+interface PostgrestErrorShape {
+	code?: string;
+	message?: string;
+	details?: string;
+	hint?: string;
+}
+
+export function mapPostgrestError(e: unknown): Error {
+	const pg = e as PostgrestErrorShape;
+	switch (pg?.code) {
+		case 'PGRST116':
+			return new ProviderError(pg.message ?? 'Not found', 404);
+		case '23505':
+			return new ProviderError(pg.message ?? 'Duplicate record', 409);
+		case '23503':
+			return new ProviderError(pg.message ?? 'Foreign key violation', 409);
+	}
+	if (e instanceof Error) return e;
+	if (e && typeof e === 'object') {
+		const obj = e as PostgrestErrorShape;
+		const msg = obj.message ?? obj.details ?? obj.hint ?? 'Unknown Postgres error';
+		const err = new Error(obj.code ? `[${obj.code}] ${msg}` : msg);
+		Object.assign(err, obj);
+		return err;
+	}
+	return new Error(String(e));
+}

package/src/data/index.ts

@@ -8,5 +8,22 @@ export { SupabaseDataProvider } from './SupabaseDataProvider.js';
 export { SupabaseEventSink } from './SupabaseEventSink.js';
 export { SupabaseSolveMetricSink } from './SupabaseSolveMetricSink.js';
 export { SupabaseAuditQuery } from './SupabaseAuditQuery.js';
-export { buildClientBundle } from './client.js';
-export type { ClientBundle, BuildClientOptions } from './client.js';
+export { buildClientBundle, clientBundleFromEnv, DEFAULT_SCHEMA } from './client.js';
+export type {
+	ClientBundle,
+	BuildClientOptions,
+	ForRequestOptions,
+	SchemaClient,
+	SelvaSchemaClient
+} from './client.js';
+export { mapPostgrestError } from './errors.js';
+export { stampUpdate, stampSoftDelete } from './rowStamp.js';
+export { notDeleted } from './query.js';
+export {
+	toRange,
+	orderColumn,
+	nextCursorFromRange,
+	encodeCursor,
+	decodeCursor
+} from './pagination.js';
+export type { RangeSpec } from './pagination.js';

package/src/data/query.ts

@@ -0,0 +1,22 @@
+/**
+ * Small query-builder helpers shared across Supabase stores.
+ */
+
+/**
+ * The slice of a PostgREST filter builder these helpers touch: an `.is()`
+ * method that returns the same builder for chaining. Generic over the builder
+ * type so the caller's concrete builder (and its row generic) flows through.
+ */
+interface DeletableQuery {
+	is(column: string, value: null): this;
+}
+
+/**
+ * Apply the soft-delete filter `deleted_at IS NULL`. The `.is('deleted_at', null)`
+ * idiom is repeated across every store that soft-deletes; this names it.
+ *
+ *   let q = notDeleted(client.from('projects').select(COLS));
+ */
+export function notDeleted<Q extends DeletableQuery>(query: Q): Q {
+	return query.is('deleted_at', null);
+}

package/src/data/rowStamp.ts

@@ -0,0 +1,48 @@
+import type { RequestContext } from '@selvajs/platform';
+import { auditSoftDelete } from '@selvajs/platform';
+
+/**
+ * Row-level (snake_case) audit-stamp helpers for Supabase stores.
+ *
+ * Platform's `auditUpdate` / `auditSoftDelete` emit camelCase *domain* fields
+ * (`updatedAt` / `updatedBy`), but Postgres rows are snake_case, so every store
+ * hand-translated them. These helpers own that translation once. Row-column
+ * naming is a provider concern, so they live here rather than in platform.
+ *
+ * Two deliberate rules, matched to how the engine's stores already write rows:
+ *  - `updated_by` is written ONLY when `ctx.userId` is set. On system contexts
+ *    it's the empty string, and the column FKs `auth.users(id)` with
+ *    `ON DELETE SET NULL` — writing `''` would violate the FK, so it's omitted
+ *    and the existing value is left untouched.
+ *  - Plain updates DON'T stamp `updated_at`: a per-table `updated_at` trigger
+ *    already sets it. Only the soft-delete stamp writes `updated_at` explicitly,
+ *    so it matches `deleted_at` (a single timestamp for the deletion event).
+ */
+
+/**
+ * Stamp for a plain UPDATE: `{ updated_by }` when the context carries a user,
+ * `{}` otherwise (the DB trigger handles `updated_at`). Spread into the row:
+ * `const row = { ...patch, ...stampUpdate(ctx) }`.
+ */
+export function stampUpdate(ctx: RequestContext): { updated_by?: string } {
+	return ctx.userId ? { updated_by: ctx.userId } : {};
+}
+
+/**
+ * Stamp for a soft-delete: `{ deleted_at, updated_at, updated_by? }`. `updated_at`
+ * is set explicitly to equal `deleted_at`; `updated_by` follows the same
+ * omit-when-empty rule as {@link stampUpdate}. `fallbackActor` defaults to
+ * `ctx.userId` (matching the engine stores' `auditSoftDelete(ctx, ctx.userId)`).
+ */
+export function stampSoftDelete(
+	ctx: RequestContext,
+	fallbackActor: string | null | undefined = ctx.userId
+): { deleted_at: string; updated_at: string; updated_by?: string } {
+	const stamp = auditSoftDelete(ctx, fallbackActor);
+	const row: { deleted_at: string; updated_at: string; updated_by?: string } = {
+		deleted_at: stamp.deletedAt,
+		updated_at: stamp.updatedAt
+	};
+	if (stamp.updatedBy) row.updated_by = stamp.updatedBy;
+	return row;
+}

package/src/index.ts

@@ -12,9 +12,27 @@ export {
 	SupabaseEventSink,
 	SupabaseSolveMetricSink,
 	SupabaseAuditQuery,
-	buildClientBundle
+	buildClientBundle,
+	clientBundleFromEnv,
+	DEFAULT_SCHEMA,
+	mapPostgrestError,
+	stampUpdate,
+	stampSoftDelete,
+	notDeleted,
+	toRange,
+	orderColumn,
+	nextCursorFromRange,
+	encodeCursor,
+	decodeCursor
+} from './data/index.js';
+export type {
+	ClientBundle,
+	BuildClientOptions,
+	ForRequestOptions,
+	SchemaClient,
+	SelvaSchemaClient,
+	RangeSpec
 } from './data/index.js';
-export type { ClientBundle, BuildClientOptions } from './data/index.js';
 
 export { SupabaseUserProfileProvider } from './userProfile/index.js';
 

package/src/storage/SupabaseStorageProvider.ts

@@ -1,6 +1,6 @@
 import type { SupabaseClient } from '@supabase/supabase-js';
 import { createClient } from '@supabase/supabase-js';
-import { transcodeImageIfNeeded } from '@selvajs/platform/storage';
+import { transcodeImageIfNeeded, classifyAssetPath } from '@selvajs/platform/storage';
 import type { IStorageProvider } from '@selvajs/platform/storage';
 
 /**
@@ -74,14 +74,19 @@ export class SupabaseStorageProvider implements IStorageProvider {
 	}
 
 	/**
-	 * Route a storage path to a bucket. Any `.gh`/`.ghx` source file is
-	 * private — confidentiality is determined by extension, not location, so
-	 * a path-scheme rename (e.g. `definition.gh` → `versions/v1.gh`) can't
-	 * silently move source files into the public bucket. Everything else
-	 * (covers, archives, thumbnails) is public.
+	 * Route a storage path to a bucket. A path is private when either:
+	 *   - it's a `.gh`/`.ghx` source file — confidentiality by extension, so a
+	 *     path-scheme rename can't silently move sources into the public bucket;
+	 *   - it classifies as a non-`public` asset class (`classifyAssetPath`) —
+	 *     e.g. `orgs/{id}/private/*` pricing sheets are members-only and must
+	 *     never land in the CDN-readable bucket.
+	 * Everything else (branding, covers, archives, thumbnails) is public.
 	 */
 	private bucketFor(storagePath: string): string {
-		return /\.(gh|ghx)$/i.test(storagePath) ? this.privateBucket : this.publicBucket;
+		if (/\.(gh|ghx)$/i.test(storagePath)) return this.privateBucket;
+		const cls = classifyAssetPath(storagePath);
+		if (cls && cls.class.visibility !== 'public') return this.privateBucket;
+		return this.publicBucket;
 	}
 
 	async get(storagePath: string): Promise<Uint8Array | null> {

package/supabase/config.toml

@@ -7,7 +7,7 @@ project_id = "selva-supabase-provider"
 
 [api]
 enabled = true
-port = 54321
+port = 54421
 # Exposed REST schemas. `selva` (where all Selva tables live, isolated from a
 # consuming app's `public`) is intentionally NOT listed here: PostgREST loads
 # this config at stack boot, *before* migrations run, so naming a not-yet-created
@@ -20,8 +20,8 @@ extra_search_path = ["public", "extensions"]
 max_rows = 1000
 
 [db]
-port = 54322
-shadow_port = 54320
+port = 54422
+shadow_port = 54420
 major_version = 15
 
 [db.pooler]
@@ -33,11 +33,11 @@ sql_paths = ["./seed.sql"]
 
 [studio]
 enabled = true
-port = 54323
+port = 54423
 
 [inbucket]
 enabled = true
-port = 54324
+port = 54424
 
 [storage]
 enabled = true
@@ -45,7 +45,7 @@ file_size_limit = "50MiB"
 
 [auth]
 enabled = true
-site_url = "http://127.0.0.1:54321"
+site_url = "http://127.0.0.1:54421"
 additional_redirect_urls = ["http://127.0.0.1:5173"]
 jwt_expiry = 3600
 enable_signup = true

package/supabase/migrations/20260630120000_org_assets.sql

@@ -0,0 +1,19 @@
+-- ============================================================================
+-- Add org branding assets
+--
+-- A JSONB `assets` map on selva.orgs holds public URLs of the org's branding
+-- assets, keyed by kind (`logo`, `favicon`, …) — e.g. {"logo": "https://…"}.
+-- Each blob lives in the public storage bucket at `orgs/{id}/{kind}.webp`;
+-- every upload (including SVG) is rasterized to WebP by the shared transcoder,
+-- so no vector blob is ever stored and the served bytes carry no XSS surface.
+--
+-- One JSONB column instead of a column-per-asset: adding a new asset kind is an
+-- app-layer enum change, never another migration.
+--
+-- No new RLS policy: the existing `orgs` UPDATE policy
+-- (instance_admin or owner_id = auth.uid()) already governs every column on the
+-- row; asset edits are additionally gated to `manage_org_members` at the app
+-- layer.
+-- ============================================================================
+
+alter table selva.orgs add column if not exists assets jsonb not null default '{}'::jsonb;

package/supabase/migrations/20260711120000_selva_definition_schema_version.sql

@@ -0,0 +1,18 @@
+-- ============================================================================
+-- Expose the cached schema's format version as a queryable column (ADR 0005).
+--
+-- The stored `schema` blob is a disposable cache of the compute-extracted UI
+-- schema; its embedded `schemaVersion` says which schema format it was written
+-- in. A GENERATED column keeps that version queryable for ops ("how many
+-- versions are stale?") with zero write-path involvement — it can never drift
+-- from the blob, and rows whose schema is NULL (pre-caching uploads) yield
+-- NULL. The web render path re-extracts from compute on version mismatch; it
+-- reads the version from the blob itself, not from this column.
+-- ============================================================================
+
+alter table selva.definition_versions
+	add column if not exists schema_version text
+		generated always as (schema ->> 'schemaVersion') stored;
+
+comment on column selva.definition_versions.schema_version is
+	'Schema format version of the cached `schema` blob (generated from schema->>''schemaVersion''). NULL when no schema is cached. Ops/diagnostics only — the app reads the version from the blob.';