akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/store/storeInstance.ts

@@ -1,7 +1,7 @@
 import { ACTION_META, ACTION_OWNER_META, getEnv, STATE_DERIVED_META, STATE_INIT_META } from "akanjs/base";
 import { Translator } from "akanjs/client";
 import { loadCapacitorApp } from "akanjs/client/capacitor";
-import { capitalize, type DynamicRecord, Logger, parseAkanI18nEnv } from "akanjs/common";
+import { capitalize, type DynamicRecord, isRecord, Logger, parseAkanI18nEnv } from "akanjs/common";
 import { ConstantRegistry } from "akanjs/constant";
 import type { SerializedArg } from "akanjs/signal";
 import { enableMapSet, produce } from "immer";
@@ -12,6 +12,7 @@ import { useFormTools } from "./agentic/useFormTools";
 import { DraftStore } from "./draftStore";
 import { useEffect, useRef, useSyncExternalStore } from "./hooks";
 import type { RootStoreCls } from "./rootStore";
+import { sliceKeysOf } from "./sliceKeys";
 import type { SliceActionKey, SliceActionRole, SliceStateRole } from "./sliceRole";
 import type { DraftState, SliceStateKey } from "./state";
 import { evaluateInitializers, type SearchParamsState, type StateDerivedMeta } from "./stateBuilder";
@@ -21,14 +22,10 @@ enableMapSet();
 
 type StoreStateRecord = Record<string, unknown>;
 
-/** Long enough that a burst of typing is one write, short enough that a route change lands what came before it. */
 const DRAFT_DEBOUNCE_MS = 400;
 type StoreAction = (...args: unknown[]) => unknown;
 type TranslationParam = Record<string, string | number>;
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  Boolean(value && typeof value === "object" && !Array.isArray(value));
-
 const getActionErrorKey = (error: unknown) => {
   if (typeof error === "string") return error;
   if (!isRecord(error)) return String(error);
@@ -193,11 +190,6 @@ export class StoreInstance {
     }, [key, count, scopeKey]);
   }
 
-  /**
-   * `sel` and `ref` take an opaque selector, so the keys it reads are learned by running it once over a recording
-   * proxy. Captured at mount, like every surface declaration: the retained set must equal the released set, and a
-   * selector is a new closure every render.
-   */
   #useLiveSelector(selector: (state: StoreStateRecord) => unknown) {
     const scopeKey = useScopePath().join(".");
     useEffect(() => {
@@ -248,18 +240,12 @@ export class StoreInstance {
   readonly #liveKeys = new Map<string, Map<string, number>>();
   readonly #generatedSetters = new Set<string>();
 
-  /**
-   * How many mounted components are reading each state key right now. `st.use.*` is a hook, so subscription is
-   * presence — this is how an agent context knows which keys the screen is actually built from.
-   */
+  /** How many mounted components read each state key right now. */
   get liveKeys(): ReadonlyMap<string, number> {
     return this.liveKeysIn("");
   }
 
-  /**
-   * The live keys as one zone view sees them: retentions tagged at the view's scope or below. The empty view is the
-   * whole screen. Zones are views, not walls — a key read inside a zone counts for that zone and for the root alike.
-   */
+  /** Live keys retained at `viewKey`'s scope or below; `""` is the whole screen. */
   liveKeysIn(viewKey: string): ReadonlyMap<string, number> {
     const keys = new Map<string, number>();
     for (const [key, scopes] of this.#liveKeys) {
@@ -273,23 +259,15 @@ export class StoreInstance {
     return keys;
   }
 
-  /** Which module declared each action. See `ActionOwner`. */
   get actionOwners(): ReadonlyMap<string, ActionOwner> {
     return this.#actionOwners;
   }
 
-  /**
-   * How many arguments each action declares.
-   *
-   * Recorded because `do[key]` is a rest-argument wrapper around the real method, so its own `length` is zero for
-   * everything — the arity is gone by the time anyone holding the instance could ask. A rest parameter on the method
-   * itself still reads as zero; nothing can recover that.
-   */
+  /** Each method's own `length`: `do[key]` is a rest-argument wrapper whose `length` is 0. */
   get actionArity(): ReadonlyMap<string, number> {
     return this.#actionArity;
   }
 
-  /** What each generated slice key is, for a reader that has only the finished store. See `SliceActionRole`. */
   get sliceActionRoles(): ReadonlyMap<string, SliceActionRole> {
     return this.#sliceActionRoles;
   }
@@ -298,12 +276,12 @@ export class StoreInstance {
     return this.#sliceStateRoles;
   }
 
-  /** Keys the store materializes from a computation, the URL, or storage. `set` throws on them. */
+  /** `search()` and `computed()` keys; `set` throws on them. */
   get derivedKeys(): ReadonlySet<string> {
     return this.#derivedMeta.derivedKeys;
   }
 
-  /** The `set<Key>` conveniences `#extendAccessors` writes for every plain state key. Their value is untyped. */
+  /** The generated `set<Key>` setters for plain state keys; their value is untyped. */
   get generatedSetters(): ReadonlySet<string> {
     return this.#generatedSetters;
   }
@@ -333,7 +311,6 @@ export class StoreInstance {
     return this;
   }
 
-  /** `<model>Form` for a model this client knows, or null — the only state key whose setters are worth publishing. */
   static #formRefNameOf(key: string) {
     if (!key.endsWith("Form")) return null;
     const refName = key.slice(0, -"Form".length);
@@ -350,7 +327,7 @@ export class StoreInstance {
   #extendAccessors(state: StoreStateRecord, actions: { [key: string]: StoreAction }) {
     for (const k of Object.keys(state)) {
       if (typeof state[k] !== "function") {
-
+        
         const formRefName = StoreInstance.#formRefNameOf(k);
         this.use[k] = formRefName
           ? (options?: StoreUseOptions) => {
@@ -379,7 +356,6 @@ export class StoreInstance {
         Logger.verbose(`${k} action loading...`);
         const start = Date.now();
         try {
-          
           await (this.#ctx[k] as StoreAction)(...args);
           Logger.verbose(`=> ${k} action dispatched (${Date.now() - start}ms)`);
         } catch (error) {
@@ -388,7 +364,7 @@ export class StoreInstance {
           throw error;
         }
       };
-
+      
       this.do[k] = tagAction(dispatch, actionTagOf(actions[k]) ?? { action: k });
     }
   }
@@ -413,74 +389,15 @@ export class StoreInstance {
   #buildSlices(store: RootStoreCls) {
     Object.entries(store.slice).forEach(([refName, sliceObj]) => {
       Object.entries(sliceObj).forEach(([suffix, serializedSlice]) => {
-        const sliceName = `${refName}${capitalize(suffix)}`;
-        this.#buildSlice(refName, sliceName, serializedSlice);
+        this.#buildSlice(refName, suffix, serializedSlice);
       });
     });
   }
 
-  #buildSlice(refName: string, sliceName: string, serializedSlice: { args?: SerializedArg[] }) {
-    const [fieldName, className] = [refName, capitalize(refName)];
-    const names: { [key in SliceStateKey | SliceActionKey | "model" | "Model"]: string } = {
-      model: fieldName,
-      Model: className,
-      defaultModel: `default${className}`,
-      modelInsight: `${fieldName}Insight`,
-      modelList: `${fieldName}List`,
-      modelListLoading: `${fieldName}ListLoading`,
-      modelInitList: `${fieldName}InitList`,
-      modelInitAt: `${fieldName}InitAt`,
-      modelStaleAt: `${fieldName}StaleAt`,
-      pageOfModel: `pageOf${className}`,
-      limitOfModel: `limitOf${className}`,
-      hasMoreOfModel: `hasMoreOf${className}`,
-      isCumulativeOfModel: `isCumulativeOf${className}`,
-      queryArgsOfModel: `queryArgsOf${className}`,
-      sortOfModel: `sortOf${className}`,
-      modelSelection: `${fieldName}Selection`,
-      initModel: `init${className}`,
-      refreshModel: `refresh${className}`,
-      selectModel: `select${className}`,
-      setPageOfModel: `setPageOf${className}`,
-      loadMoreOfModel: `loadMoreOf${className}`,
-      setLimitOfModel: `setLimitOf${className}`,
-      setQueryArgsOfModel: `setQueryArgsOf${className}`,
-      setSortOfModel: `setSortOf${className}`,
-      applyLiveModel: `applyLive${className}`,
-      watchLiveModel: `watchLive${className}`,
-      lastPageOfModel: `lastPageOf${className}`,
-    };
-    const SliceName = capitalize(sliceName);
-    const namesOfSliceState: { [key in SliceStateKey]: string } = {
-      defaultModel: SliceName.replace(names.Model, names.defaultModel),
-      modelInitList: SliceName.replace(names.Model, names.modelInitList),
-      modelInsight: sliceName.replace(names.model, names.modelInsight),
-      modelList: sliceName.replace(names.model, names.modelList),
-      modelListLoading: sliceName.replace(names.model, names.modelListLoading),
-      modelInitAt: SliceName.replace(names.Model, names.modelInitAt),
-      modelStaleAt: SliceName.replace(names.Model, names.modelStaleAt),
-      lastPageOfModel: SliceName.replace(names.Model, names.lastPageOfModel),
-      pageOfModel: SliceName.replace(names.Model, names.pageOfModel),
-      limitOfModel: SliceName.replace(names.Model, names.limitOfModel),
-      hasMoreOfModel: SliceName.replace(names.Model, names.hasMoreOfModel),
-      isCumulativeOfModel: SliceName.replace(names.Model, names.isCumulativeOfModel),
-      queryArgsOfModel: SliceName.replace(names.Model, names.queryArgsOfModel),
-      sortOfModel: SliceName.replace(names.Model, names.sortOfModel),
-      modelSelection: SliceName.replace(names.Model, names.modelSelection),
-    };
-    const namesOfSliceAction: { [key in SliceActionKey]: string } = {
-      initModel: SliceName.replace(names.Model, names.initModel),
-      refreshModel: SliceName.replace(names.Model, names.refreshModel),
-      selectModel: SliceName.replace(names.Model, names.selectModel),
-      setPageOfModel: SliceName.replace(names.Model, names.setPageOfModel),
-      loadMoreOfModel: SliceName.replace(names.Model, names.loadMoreOfModel),
-      setLimitOfModel: SliceName.replace(names.Model, names.setLimitOfModel),
-      setQueryArgsOfModel: SliceName.replace(names.Model, names.setQueryArgsOfModel),
-      setSortOfModel: SliceName.replace(names.Model, names.setSortOfModel),
-      applyLiveModel: SliceName.replace(names.Model, names.applyLiveModel),
-      watchLiveModel: SliceName.replace(names.Model, names.watchLiveModel),
-    };
-
+  #buildSlice(refName: string, suffix: string, serializedSlice: { args?: SerializedArg[] }) {
+    const sliceName = `${refName}${capitalize(suffix)}`;
+    const names = sliceKeysOf(refName);
+    const { state: namesOfSliceState, action: namesOfSliceAction } = sliceKeysOf(refName, suffix);
     const targetSlice: {
       do: { [key: string]: (...args: any[]) => void };
       use: { [key: string]: () => any };
@@ -501,18 +418,18 @@ export class StoreInstance {
     for (const key of Object.keys(namesOfSliceAction) as SliceActionKey[]) {
       const rootActionKey = namesOfSliceAction[key];
       if (!this.do[rootActionKey]) continue;
-      targetSlice.do[names[key]] = this.do[rootActionKey];
+      targetSlice.do[names.action[key]] = this.do[rootActionKey];
       this.#sliceActionRoles.set(rootActionKey, { role: key, refName, sliceName, args });
     }
 
     for (const key of Object.keys(namesOfSliceState) as SliceStateKey[]) {
       const rootStateKey = namesOfSliceState[key];
       if (this.use[rootStateKey]) {
-        targetSlice.use[names[key]] = this.use[rootStateKey];
+        targetSlice.use[names.state[key]] = this.use[rootStateKey];
         this.#sliceStateRoles.set(rootStateKey, { role: key, refName, sliceName });
       }
       const setRootKey = `set${capitalize(rootStateKey)}`;
-      const setLocalKey = `set${capitalize(names[key])}`;
+      const setLocalKey = `set${capitalize(names.state[key])}`;
       if (this.do[setRootKey]) targetSlice.do[setLocalKey] = this.do[setRootKey];
     }
 
@@ -520,7 +437,7 @@ export class StoreInstance {
       const state = this.get();
       return Object.fromEntries(
         (Object.entries(namesOfSliceState) as [SliceStateKey, string][]).map(([key, value]) => [
-          names[key],
+          names.state[key],
           state[value],
         ]),
       );
@@ -573,16 +490,6 @@ export class StoreInstance {
     }
   }
 
-  /**
-   * Schedules a save of every open form whose value moved.
-   *
-   * A form is only saved while `<model>Draft.key` is armed — `new<Model>` / `edit<Model>` arm it and a submit or
-   * reset disarms it — so a store that never opened a form writes nothing. The dirty comparison happens in the
-   * flush rather than here: it encodes the whole form, and a keystroke is not worth that.
-   *
-   * The debounce belongs to the store, not to a component, so an editor that unmounts mid-window still lands its
-   * last write. Only a closing tab can outrun it, which is what the flush listeners answer.
-   */
   #syncDrafts(prev: StoreStateRecord, next: StoreStateRecord) {
     if (typeof window === "undefined") return;
     for (const meta of Object.values(this.#derivedMeta.drafts)) {
@@ -592,7 +499,7 @@ export class StoreInstance {
         continue;
       }
       if (Object.is(prev[meta.formKey], next[meta.formKey])) continue;
-
+      
       if (!Object.is(prev[meta.draftKey], next[meta.draftKey])) continue;
       this.#armDraftFlush();
       this.#cancelDraftTimer(meta.formKey);
@@ -619,7 +526,7 @@ export class StoreInstance {
     if (!draft?.key || !form) return;
     try {
       const hash = DraftStore.formHash(refName, form);
-
+      
       if (hash === draft.baseHash) {
         await DraftStore.remove(draft.key);
         return;
@@ -635,7 +542,7 @@ export class StoreInstance {
     }
   }
 
-  /** Lands every pending write before the page or the app goes away. */
+  /** Writes every pending draft now, cancelling its debounce. */
   flushDrafts = () => {
     for (const [formKey, timer] of this.#draftTimers) {
       clearTimeout(timer);

package/store/storeRegistry.ts

@@ -42,14 +42,13 @@ function getStoreRegistryState(): StoreRegistryState {
 
 export class StoreRegistry {
   static #state = getStoreRegistryState();
-  /** The one store every `st.use` / `st.do` in the process goes through. What an agent bridge drives. */
   static get instance(): StoreInstance {
     return StoreRegistry.#state.instance;
   }
   static register<StrCls extends StoreCls>(store: StrCls): StrCls {
     const parentStore = Object.getPrototypeOf(store) as StoreCls | null;
     const actions = { ...(parentStore?.[ACTION_META] ?? {}) };
-
+    
     const owners = { ...(parentStore?.[ACTION_OWNER_META] ?? {}) };
     Object.entries(Object.getOwnPropertyDescriptors(store.prototype)).forEach(([key, descriptor]) => {
       if (key === "constructor") return;
@@ -64,11 +63,6 @@ export class StoreRegistry {
     return store;
   }
 
-  /**
-   * A `_postSet<Field>` hook cannot be typed — the generated setters live in a mapped type, so every name the base
-   * declares is a property a subclass method may not redeclare (TS2425), and the hook only compiles because the base
-   * declares nothing under it. A misspelled field would therefore never fire and never complain, so say so here.
-   */
   static #warnUnknownPostSetHooks(store: StoreCls) {
     const hooks = Object.keys(Object.getOwnPropertyDescriptors(store.prototype)).filter((key) =>
       key.startsWith("_postSet"),
@@ -85,7 +79,6 @@ export class StoreRegistry {
   static get(refName: string) {
     return StoreRegistry.#state.store.get(refName);
   }
-  /** Every registered module store by refName. What the agent surface derives key ownership and exposure from. */
   static get stores(): ReadonlyMap<string, StoreCls> {
     return StoreRegistry.#state.store;
   }

package/store/types.ts

@@ -22,7 +22,7 @@ type PickFunc<
   F extends keyof State = IsAny<State> extends true ? any : keyof State extends never ? any : keyof State,
 > = (...fields: F[]) => {
   [K in (typeof fields)[number]]: Exclude<State[K], null | undefined | "loading">;
-}; 
+};
 export interface SetGet<State = any> {
   set: (setState: Partial<State> | ((state: State) => void)) => void;
   get: () => State;

package/test/conformance.ts

@@ -0,0 +1,299 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import {
+  DEFAULT_TOKENIZER,
+  getSolidConfig,
+  LibsqlDatabase,
+  PostgresDatabase,
+  PostgresDialect,
+  RedisCache,
+  Scheduler,
+  type SearchConfig,
+  SolidCache,
+  type SqlDialect,
+  SqliteDatabase,
+  SqliteDialect,
+} from "akanjs/service";
+
+type ConformanceBackend = "redis" | "postgres" | "libsql";
+
+export type ConformanceCacheKind = "solid" | "redis";
+
+/** `libsqlRemote` is a sqld server shared by every run, so it only hosts cases that bring their own table. */
+export type SqlDriverKind = "sqlite" | "libsql" | "postgres" | "libsqlRemote";
+
+export interface SqlDriverOptions {
+  insight?: boolean;
+  memory?: boolean;
+  search?: SearchConfig;
+}
+
+export interface SqlDriver {
+  kind: SqlDriverKind;
+  database: SqliteDatabase | LibsqlDatabase | PostgresDatabase;
+  dialect: SqlDialect;
+  /** A new adaptor on the same storage — what a process restart sees, so only what was committed. */
+  restart: () => Promise<SqlDriver>;
+  /** A second adaptor on the same storage while this one stays open: another process, with these search settings. */
+  sibling: (search?: SearchConfig) => Promise<SqlDriver>;
+  /** A restart with other text search settings — a redeploy that changed `AKAN_SEARCH_*`. */
+  reconfigure: (search: SearchConfig) => Promise<SqlDriver>;
+  close: () => Promise<void>;
+}
+
+const backendEnvNames = {
+  redis: "AKAN_TEST_REDIS_URL",
+  postgres: "AKAN_TEST_POSTGRES_URL",
+  libsql: "AKAN_TEST_LIBSQL_URL",
+} as const;
+
+/** `bun run testConformance` (`infra/test/compose.yaml`) sets all three backends; plain `bun test` runs SQLite. */
+export class ConformanceEnv {
+  static readonly #announced = new Set<string>();
+  /** Where a deployment points an app at its data. A test that hands its storage in has these cleared first. */
+  static readonly deploymentEnvKeys = [
+    "AKAN_DATABASE_MODES",
+    "AKAN_SOLID_DB_PATH",
+    "SQLITE_DATABASE_PATH",
+    "LIBSQL_URL",
+    "LIBSQL_URI",
+    "LIBSQL_AUTH_TOKEN",
+    "POSTGRES_URL",
+    "POSTGRES_URI",
+    "POSTGRES_HOST",
+    "POSTGRES_PORT",
+    "POSTGRES_DATABASE",
+    "POSTGRES_DB",
+    "POSTGRES_USER",
+    "POSTGRES_PASSWORD",
+    "POSTGRES_INSIGHT_URL",
+  ] as const;
+
+  /** This process's env without what a deployment would point the app at. */
+  static isolatedProcessEnv() {
+    const env: Record<string, string | undefined> = { ...process.env };
+    for (const key of ConformanceEnv.deploymentEnvKeys) delete env[key];
+    return env;
+  }
+
+  static url(backend: ConformanceBackend): string | null {
+    return process.env[backendEnvNames[backend]]?.trim() || null;
+  }
+
+  /** Says once per suite and backend when it is missing: a skipped suite must never read as a passing one. */
+  static has(suite: string, backend: ConformanceBackend): boolean {
+    if (ConformanceEnv.url(backend)) return true;
+    const key = `${suite}:${backend}`;
+    if (!ConformanceEnv.#announced.has(key)) {
+      ConformanceEnv.#announced.add(key);
+      console.info(
+        `[conformance] ${suite}: ${backend} cases skipped — set ${backendEnvNames[backend]}, or run \`bun run testConformance\``,
+      );
+    }
+    return false;
+  }
+
+  static uniqueName(prefix: string) {
+    return `${prefix}_${process.pid}_${crypto.randomUUID().replaceAll("-", "").slice(0, 8)}`;
+  }
+
+  static async tempDir(prefix: string) {
+    const dir = await mkdtemp(path.join(tmpdir(), `${prefix}-`));
+    return { dir, remove: async () => await rm(dir, { recursive: true, force: true }) };
+  }
+
+  /**
+   * A throwaway schema and a URL pinning every pooled connection to it: postgres.js forwards unknown query parameters
+   * as startup parameters, so `search_path` holds on later connections too. `insight` adds a login role, dropped too.
+   */
+  static async postgresSchema(prefix: string, { insight = false }: { insight?: boolean } = {}) {
+    const base = ConformanceEnv.url("postgres");
+    if (!base) throw new Error("postgresSchema() needs AKAN_TEST_POSTGRES_URL");
+    const schema = ConformanceEnv.uniqueName(prefix).toLowerCase();
+    const role = `${schema}_insight`;
+    const { default: postgres } = await import("postgres");
+    const admin = postgres(base, { max: 1, onnotice: () => undefined });
+    await admin.unsafe(`CREATE SCHEMA "${schema}"`);
+    const insightUrl = insight ? await ConformanceEnv.#createLoginRole(admin, base, role) : undefined;
+    await admin.end();
+    const url = new URL(base);
+    url.searchParams.set("search_path", schema);
+    return {
+      schema,
+      url: url.toString(),
+      insightUrl,
+      drop: async () => {
+        const dropper = postgres(base, { max: 1, onnotice: () => undefined });
+        await dropper.unsafe(`DROP SCHEMA IF EXISTS "${schema}" CASCADE`);
+        if (insight) await dropper.unsafe(`DROP ROLE IF EXISTS "${role}"`);
+        await dropper.end();
+      },
+    };
+  }
+
+  /** A login role with no privilege and no membership, and the URL that logs in as it. */
+  static async createPostgresLoginRole(role: string) {
+    const base = ConformanceEnv.url("postgres");
+    if (!base) throw new Error("createPostgresLoginRole() needs AKAN_TEST_POSTGRES_URL");
+    const { default: postgres } = await import("postgres");
+    const admin = postgres(base, { max: 1, onnotice: () => undefined });
+    const url = await ConformanceEnv.#createLoginRole(admin, base, role);
+    await admin.end();
+    return {
+      url,
+      drop: async () => {
+        const dropper = postgres(base, { max: 1, onnotice: () => undefined });
+        await dropper.unsafe(`DROP OWNED BY "${role}"`);
+        await dropper.unsafe(`DROP ROLE IF EXISTS "${role}"`);
+        await dropper.end();
+      },
+    };
+  }
+
+  static async #createLoginRole(admin: { unsafe: (sql: string) => Promise<unknown> }, base: string, role: string) {
+    const password = crypto.randomUUID().replaceAll("-", "");
+    await admin.unsafe(`CREATE ROLE "${role}" LOGIN PASSWORD '${password}'`);
+    const url = new URL(base);
+    url.username = role;
+    url.password = password;
+    return url.toString();
+  }
+
+  static cacheKinds(suite: string): ConformanceCacheKind[] {
+    return ConformanceEnv.has(suite, "redis") ? ["solid", "redis"] : ["solid"];
+  }
+
+  /** `app` stands for the app that built the cache: on Redis it is the key prefix, and closing deletes under it. */
+  static async openCache(
+    kind: ConformanceCacheKind,
+    { app = ConformanceEnv.uniqueName("app") }: { app?: string } = {},
+  ) {
+    if (kind === "solid") {
+      const { dir, remove } = await ConformanceEnv.tempDir("akan-cache");
+      const cache = new SolidCache();
+      Object.assign(cache, { config: getSolidConfig({ solid: { filePath: path.join(dir, `${app}.db`) } }) });
+      await cache.onInit();
+      return {
+        cache: cache as SolidCache | RedisCache,
+        close: async () => {
+          await cache.onDestroy();
+          await remove();
+        },
+      };
+    }
+    const { Redis } = await import("ioredis");
+    const client = new Redis(ConformanceEnv.url("redis") as string, { lazyConnect: true });
+    await client.connect();
+    const cache = new RedisCache();
+    const keyPrefix = `${app}:testing:`;
+    Object.assign(cache, { redis: client, keyPrefix });
+    return {
+      cache: cache as SolidCache | RedisCache,
+      close: async () => {
+        const keys = await client.keys(`${keyPrefix}*`);
+        if (keys.length) await client.del(...keys);
+        await cache.onDestroy();
+      },
+    };
+  }
+
+  /** The local drivers always, and each remote one whose backend the suite can reach. */
+  static sqlDrivers(suite: string, { remote = false }: { remote?: boolean } = {}): SqlDriverKind[] {
+    const kinds: SqlDriverKind[] = ["sqlite"];
+    if (ConformanceEnv.#hasLibsqlBinding(suite)) kinds.push("libsql");
+    if (ConformanceEnv.has(suite, "postgres")) kinds.push("postgres");
+    if (remote && ConformanceEnv.has(suite, "libsql")) kinds.push("libsqlRemote");
+    return kinds;
+  }
+
+  static #hasLibsqlBinding(suite: string) {
+    if (process.platform !== "win32" || process.arch !== "arm64") return true;
+    const key = `${suite}:libsql-binding`;
+    if (!ConformanceEnv.#announced.has(key)) {
+      ConformanceEnv.#announced.add(key);
+      console.info(`[conformance] ${suite}: local libsql cases skipped — libsql publishes no win32-arm64 binding`);
+    }
+    return false;
+  }
+
+  /**
+   * The real adaptor, initialised as the DI container would, on storage nothing else sees. `insight` gives Postgres a
+   * login role for `InsightQuery`; `memory` puts SQLite in memory, as `TestServer` does.
+   */
+  static async openSqlDriver(kind: SqlDriverKind, options: SqlDriverOptions = {}): Promise<SqlDriver> {
+    return await ConformanceEnv.#openSqlAdaptor(kind, await ConformanceEnv.#sqlStorage(kind, options));
+  }
+
+  static async #sqlStorage(
+    kind: SqlDriverKind,
+    { insight = false, memory = false, search: searchConfig }: SqlDriverOptions,
+  ): Promise<{ config: object; remove: () => Promise<void> }> {
+    const search = { enabled: kind !== "libsqlRemote", tokenizer: DEFAULT_TOKENIZER, ...searchConfig };
+    if (kind === "postgres") {
+      const { url, insightUrl, drop } = await ConformanceEnv.postgresSchema("akan_sql", { insight });
+      return { config: { url, insightUrl, search }, remove: drop };
+    }
+    if (kind === "libsqlRemote")
+      return { config: { url: ConformanceEnv.url("libsql"), search }, remove: async () => undefined };
+    if (kind === "sqlite" && memory)
+      return {
+        config: { filePath: ":memory:", journalMode: "MEMORY", synchronous: "OFF", foreignKeys: true, search },
+        remove: async () => undefined,
+      };
+    const { dir, remove } = await ConformanceEnv.tempDir(`akan-${kind}`);
+    const filePath = path.join(dir, "conformance.db");
+    return {
+      config:
+        kind === "sqlite"
+          ? { filePath, journalMode: "WAL", busyTimeoutMs: 5000, synchronous: "NORMAL", foreignKeys: true, search }
+          : { url: `file:${filePath}`, search },
+      remove,
+    };
+  }
+
+  static #withSearch(config: object, search: SearchConfig) {
+    const current = (config as { search?: SearchConfig }).search;
+    return { ...config, search: { ...current, ...search } };
+  }
+
+  static async #openSqlAdaptor(
+    kind: SqlDriverKind,
+    storage: { config: object; remove: () => Promise<void> },
+  ): Promise<SqlDriver> {
+    const scheduler = new Scheduler();
+    const database =
+      kind === "postgres" ? new PostgresDatabase() : kind === "sqlite" ? new SqliteDatabase() : new LibsqlDatabase();
+    Object.assign(database, { scheduler, config: storage.config });
+    await database.onInit();
+    const shutdown = async () => {
+      await database.onDestroy();
+      await scheduler.onDestroy();
+    };
+    return {
+      kind,
+      database,
+      dialect: kind === "postgres" ? new PostgresDialect() : new SqliteDialect(),
+      restart: async () => {
+        await shutdown();
+        return await ConformanceEnv.#openSqlAdaptor(kind, storage);
+      },
+      sibling: async (search: SearchConfig = {}) =>
+        await ConformanceEnv.#openSqlAdaptor(kind, {
+          config: ConformanceEnv.#withSearch(storage.config, search),
+          remove: async () => undefined,
+        }),
+      reconfigure: async (search: SearchConfig) => {
+        await shutdown();
+        return await ConformanceEnv.#openSqlAdaptor(kind, {
+          ...storage,
+          config: ConformanceEnv.#withSearch(storage.config, search),
+        });
+      },
+      close: async () => {
+        await shutdown();
+        await storage.remove();
+      },
+    };
+  }
+}

package/test/index.ts

@@ -1,5 +1,5 @@
-export { sample } from "./sample";
-export { sampleOf } from "./sampleOf";
+export { type ConformanceCacheKind, ConformanceEnv, type SqlDriver, type SqlDriverKind } from "./conformance";
+export { sample, sampleOf } from "./sampleOf";
 export {
   configureSignalTest,
   getOrSetupSignalTestContext,