@doync/client 0.1.0 → 0.1.1

package/dist/index.d.cts

@@ -1,2 +1,3 @@
-import { F as ClientMutation, I as ClientMutationHandler, L as ClientMutationRegistry, R as ClientMutationTx, _ as SchemaEventKind, b as ViewStatus, c as FalsyQuery, d as MutationResult, f as OnceView, g as SchemaEvent, h as QueryStatus, l as LogoutBehavior, m as PreloadOptions, o as ConnectionStatus, p as PreloadHandle, s as DoyncClient, u as MutationOptions, v as SubscribeOptions, y as View } from "./client-DHXO0dbf.cjs";
-export type { ClientMutation, ClientMutationHandler, ClientMutationRegistry, ClientMutationTx, ConnectionStatus, DoyncClient, FalsyQuery, LogoutBehavior, MutationOptions, MutationResult, OnceView, PreloadHandle, PreloadOptions, QueryStatus, SchemaEvent, SchemaEventKind, SubscribeOptions, View, ViewStatus };
+import { _ as SchemaEvent, b as View, c as DoyncClient, d as MutationOptions, f as MutationResult, g as QueryStatus, h as PreloadOptions, l as FalsyQuery, m as PreloadHandle, p as OnceView, s as ConnectionStatus, u as LogoutBehavior, v as SchemaEventKind, x as ViewStatus, y as SubscribeOptions } from "./client-OPt8Axyp.cjs";
+import { AuthData } from "@doync/core";
+export type { AuthData, ConnectionStatus, DoyncClient, FalsyQuery, LogoutBehavior, MutationOptions, MutationResult, OnceView, PreloadHandle, PreloadOptions, QueryStatus, SchemaEvent, SchemaEventKind, SubscribeOptions, View, ViewStatus };

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-import { F as ClientMutation, I as ClientMutationHandler, L as ClientMutationRegistry, R as ClientMutationTx, _ as SchemaEventKind, b as ViewStatus, c as FalsyQuery, d as MutationResult, f as OnceView, g as SchemaEvent, h as QueryStatus, l as LogoutBehavior, m as PreloadOptions, o as ConnectionStatus, p as PreloadHandle, s as DoyncClient, u as MutationOptions, v as SubscribeOptions, y as View } from "./client-CNyLMCw0.js";
-export type { ClientMutation, ClientMutationHandler, ClientMutationRegistry, ClientMutationTx, ConnectionStatus, DoyncClient, FalsyQuery, LogoutBehavior, MutationOptions, MutationResult, OnceView, PreloadHandle, PreloadOptions, QueryStatus, SchemaEvent, SchemaEventKind, SubscribeOptions, View, ViewStatus };
+import { _ as SchemaEvent, b as View, c as DoyncClient, d as MutationOptions, f as MutationResult, g as QueryStatus, h as PreloadOptions, l as FalsyQuery, m as PreloadHandle, p as OnceView, s as ConnectionStatus, u as LogoutBehavior, v as SchemaEventKind, x as ViewStatus, y as SubscribeOptions } from "./client-OAVaC3pt.js";
+import { AuthData } from "@doync/core";
+export type { AuthData, ConnectionStatus, DoyncClient, FalsyQuery, LogoutBehavior, MutationOptions, MutationResult, OnceView, PreloadHandle, PreloadOptions, QueryStatus, SchemaEvent, SchemaEventKind, SubscribeOptions, View, ViewStatus };

package/dist/internal.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./client-C6jAdhbe.cjs");let t=require("@doync/sqlite-parser");function n(e){return encodeURIComponent(e).replaceAll(`_`,`%5F`)}function r(e,t){let r=n(e);return t===null?`doync__${r}__anon.db`:`doync__${r}__${n(t)}.db`}function i(e){let n;try{n=(0,t.parse)(e)}catch(t){return console.warn(`extractWriteTable: failed to parse SQL statement`,{sql:e,err:t}),null}switch(n.kind){case`STMT_INSERT`:case`STMT_UPDATE`:case`STMT_DELETE`:return n.table??null;default:return null}}exports.ClientEngine=e.r,exports.__CONNECTED_CLOCK_META_KEY=e.i,exports.__LOGOUT_BEHAVIOR_META_KEY=e.a,exports.applyBundledMigrations=e.l,exports.asClientMutation=e.v,exports.bundledSchemaDdl=e.h,exports.classifyClientStatement=e.g,exports.createClientEngine=e.n,exports.createEngineTables=e.u,exports.dbFileForUserId=r,exports.dropConsumerTables=e.d,exports.extractWriteTable=i,exports.isFalsyQuery=e.o,exports.normalizeQuerySurface=e.s,exports.readMeta=e.p,exports.replayMigrations=e.f,exports.settledRejection=e.c,exports.splitClientStatements=e._,exports.toClientMutationRegistry=e.b,exports.validateMutationArgs=e.y,exports.writeMeta=e.m;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./client-Bv6QMenB.cjs");let t=require("@doync/sqlite-parser");function n(e){return encodeURIComponent(e).replaceAll(`_`,`%5F`)}function r(e,t){let r=n(e);return t===null?`doync__${r}__anon.db`:`doync__${r}__${n(t)}.db`}function i(e){let n;try{n=(0,t.parse)(e)}catch(t){return console.warn(`extractWriteTable: failed to parse SQL statement`,{sql:e,err:t}),null}switch(n.kind){case`STMT_INSERT`:case`STMT_UPDATE`:case`STMT_DELETE`:return n.table??null;default:return null}}exports.ClientEngine=e.i,exports.__CONNECTED_CLOCK_META_KEY=e.a,exports.__LOGOUT_BEHAVIOR_PREF_KEY=e.o,exports.applyBundledMigrations=e.u,exports.bundledSchemaDdl=e.v,exports.classifyClientStatement=e.y,exports.createClientEngine=e.n,exports.createEngineTables=e.d,exports.dbFileForUserId=r,exports.dropConsumerTables=e.f,exports.extractWriteTable=i,exports.isFalsyQuery=e.s,exports.normalizeQuerySurface=e.c,exports.readMeta=e.m,exports.readPref=e.h,exports.replayMigrations=e.p,exports.resolveClientAuthData=e.r,exports.settledRejection=e.l,exports.splitClientStatements=e.b,exports.writeMeta=e.g,exports.writePref=e._;

package/dist/internal.d.cts

@@ -1,15 +1,6 @@
-import { A as readMeta, B as validateMutationArgs, C as isFalsyQuery, D as createEngineTables, E as applyBundledMigrations, L as ClientMutationRegistry, O as dropConsumerTables, S as __LOGOUT_BEHAVIOR_META_KEY, T as settledRejection, U as extractWriteTable, a as ClientEngineConfig, i as ClientEngine, j as writeMeta, k as replayMigrations, r as createClientEngine, w as normalizeQuerySurface, x as __CONNECTED_CLOCK_META_KEY, z as asClientMutation } from "./client-DHXO0dbf.cjs";
-import { DoyncSchema, MutationTree } from "@doync/core";
+import { A as replayMigrations, B as extractWriteTable, C as __LOGOUT_BEHAVIOR_PREF_KEY, D as applyBundledMigrations, E as settledRejection, M as readPref, N as writeMeta, O as createEngineTables, P as writePref, S as __CONNECTED_CLOCK_META_KEY, T as normalizeQuerySurface, a as ClientEngine, i as resolveClientAuthData, j as readMeta, k as dropConsumerTables, o as ClientEngineConfig, r as createClientEngine, w as isFalsyQuery } from "./client-OPt8Axyp.cjs";
+import { DoyncSchema } from "@doync/core";
 
-//#region src/client-mutation-registry.d.ts
-/**
-* Flat `dottedName → {args, handler}` registry the client engine resolves
-* optimistic bodies against (ADR-0019). Feed the SHARED tree so no `.server.ts`
-* override enters the client bundle. Handler may return a promise (exclusive
-* chain awaits); engine validates args at `mutate()` via carried schema.
-*/
-declare function toClientMutationRegistry(tree: MutationTree): ClientMutationRegistry;
-//#endregion
 //#region src/identity.d.ts
 /**
 * Durable replica file for one `(Database name, asserted userId)` pair:
@@ -65,5 +56,5 @@ declare function classifyClientStatement(statement: string): ClientStatementKind
 */
 declare function bundledSchemaDdl(schema: DoyncSchema, fromVersion: number, toVersion: number): string[];
 //#endregion
-export { ClientEngine, type ClientEngineConfig, type ClientStatementKind, __CONNECTED_CLOCK_META_KEY, __LOGOUT_BEHAVIOR_META_KEY, applyBundledMigrations, asClientMutation, bundledSchemaDdl, classifyClientStatement, createClientEngine, createEngineTables, dbFileForUserId, dropConsumerTables, extractWriteTable, isFalsyQuery, normalizeQuerySurface, readMeta, replayMigrations, settledRejection, splitClientStatements, toClientMutationRegistry, validateMutationArgs, writeMeta };
+export { ClientEngine, type ClientEngineConfig, type ClientStatementKind, __CONNECTED_CLOCK_META_KEY, __LOGOUT_BEHAVIOR_PREF_KEY, applyBundledMigrations, bundledSchemaDdl, classifyClientStatement, createClientEngine, createEngineTables, dbFileForUserId, dropConsumerTables, extractWriteTable, isFalsyQuery, normalizeQuerySurface, readMeta, readPref, replayMigrations, resolveClientAuthData, settledRejection, splitClientStatements, writeMeta, writePref };
 //# sourceMappingURL=internal.d.cts.map

package/dist/internal.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"internal.d.cts","names":[],"sources":["../src/client-mutation-registry.ts","../src/identity.ts","../src/migrate.ts"],"mappings":";;;;;;;;AAqBG;;iBAFa,wBAAA,CACd,IAAA,EAAM,YAAA,GACL,sBAAA;;;;;;;AAFH;;;;iBCgBgB,eAAA,CAAgB,IAAA,UAAc,MAAA;;;;;;ADhB9C;;;;;KEAY,mBAAA;;;AFET;;;;ACcH;;;;AAA8C;;iBCgE9B,qBAAA,CAAsB,GAAA;;AAhFtC;;;;AAAY;AAgFZ;;iBAkBgB,uBAAA,CACd,SAAA,WACC,mBAAA;;AApBmC;AAkBtC;;;;AAEG;AAeH;;;iBAAgB,gBAAA,CACd,MAAA,EAAQ,WAAA,EACR,WAAA,UACA,SAAA"}
+{"version":3,"file":"internal.d.cts","names":[],"sources":["../src/identity.ts","../src/migrate.ts"],"mappings":";;;;;;;;AAmCA;;;;iBAAgB,eAAA,CAAgB,IAAA,UAAc,MAAA;;;;;;AAA9C;;;;AAA8C;AAAA,KChBlC,mBAAA;;;AAAZ;;;;AAAY;AAgFZ;;;;AAAsC;iBAAtB,qBAAA,CAAsB,GAAA;;;;AAoBnC;AAeH;;;;iBAjBgB,uBAAA,CACd,SAAA,WACC,mBAAA;;;;;AAkBD;;;;;;iBAHc,gBAAA,CACd,MAAA,EAAQ,WAAA,EACR,WAAA,UACA,SAAA"}

package/dist/internal.d.ts

@@ -1,15 +1,6 @@
-import { A as readMeta, B as validateMutationArgs, C as isFalsyQuery, D as createEngineTables, E as applyBundledMigrations, L as ClientMutationRegistry, O as dropConsumerTables, S as __LOGOUT_BEHAVIOR_META_KEY, T as settledRejection, U as extractWriteTable, a as ClientEngineConfig, i as ClientEngine, j as writeMeta, k as replayMigrations, r as createClientEngine, w as normalizeQuerySurface, x as __CONNECTED_CLOCK_META_KEY, z as asClientMutation } from "./client-CNyLMCw0.js";
-import { DoyncSchema, MutationTree } from "@doync/core";
+import { A as replayMigrations, B as extractWriteTable, C as __LOGOUT_BEHAVIOR_PREF_KEY, D as applyBundledMigrations, E as settledRejection, M as readPref, N as writeMeta, O as createEngineTables, P as writePref, S as __CONNECTED_CLOCK_META_KEY, T as normalizeQuerySurface, a as ClientEngine, i as resolveClientAuthData, j as readMeta, k as dropConsumerTables, o as ClientEngineConfig, r as createClientEngine, w as isFalsyQuery } from "./client-OAVaC3pt.js";
+import { DoyncSchema } from "@doync/core";
 
-//#region src/client-mutation-registry.d.ts
-/**
-* Flat `dottedName → {args, handler}` registry the client engine resolves
-* optimistic bodies against (ADR-0019). Feed the SHARED tree so no `.server.ts`
-* override enters the client bundle. Handler may return a promise (exclusive
-* chain awaits); engine validates args at `mutate()` via carried schema.
-*/
-declare function toClientMutationRegistry(tree: MutationTree): ClientMutationRegistry;
-//#endregion
 //#region src/identity.d.ts
 /**
 * Durable replica file for one `(Database name, asserted userId)` pair:
@@ -65,5 +56,5 @@ declare function classifyClientStatement(statement: string): ClientStatementKind
 */
 declare function bundledSchemaDdl(schema: DoyncSchema, fromVersion: number, toVersion: number): string[];
 //#endregion
-export { ClientEngine, type ClientEngineConfig, type ClientStatementKind, __CONNECTED_CLOCK_META_KEY, __LOGOUT_BEHAVIOR_META_KEY, applyBundledMigrations, asClientMutation, bundledSchemaDdl, classifyClientStatement, createClientEngine, createEngineTables, dbFileForUserId, dropConsumerTables, extractWriteTable, isFalsyQuery, normalizeQuerySurface, readMeta, replayMigrations, settledRejection, splitClientStatements, toClientMutationRegistry, validateMutationArgs, writeMeta };
+export { ClientEngine, type ClientEngineConfig, type ClientStatementKind, __CONNECTED_CLOCK_META_KEY, __LOGOUT_BEHAVIOR_PREF_KEY, applyBundledMigrations, bundledSchemaDdl, classifyClientStatement, createClientEngine, createEngineTables, dbFileForUserId, dropConsumerTables, extractWriteTable, isFalsyQuery, normalizeQuerySurface, readMeta, readPref, replayMigrations, resolveClientAuthData, settledRejection, splitClientStatements, writeMeta, writePref };
 //# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal.d.ts","names":[],"sources":["../src/client-mutation-registry.ts","../src/identity.ts","../src/migrate.ts"],"mappings":";;;;;;;;AAqBG;;iBAFa,wBAAA,CACd,IAAA,EAAM,YAAA,GACL,sBAAA;;;;;;;AAFH;;;;iBCgBgB,eAAA,CAAgB,IAAA,UAAc,MAAA;;;;;;ADhB9C;;;;;KEAY,mBAAA;;;AFET;;;;ACcH;;;;AAA8C;;iBCgE9B,qBAAA,CAAsB,GAAA;;AAhFtC;;;;AAAY;AAgFZ;;iBAkBgB,uBAAA,CACd,SAAA,WACC,mBAAA;;AApBmC;AAkBtC;;;;AAEG;AAeH;;;iBAAgB,gBAAA,CACd,MAAA,EAAQ,WAAA,EACR,WAAA,UACA,SAAA"}
+{"version":3,"file":"internal.d.ts","names":[],"sources":["../src/identity.ts","../src/migrate.ts"],"mappings":";;;;;;;;AAmCA;;;;iBAAgB,eAAA,CAAgB,IAAA,UAAc,MAAA;;;;;;AAA9C;;;;AAA8C;AAAA,KChBlC,mBAAA;;;AAAZ;;;;AAAY;AAgFZ;;;;AAAsC;iBAAtB,qBAAA,CAAsB,GAAA;;;;AAoBnC;AAeH;;;;iBAjBgB,uBAAA,CACd,SAAA,WACC,mBAAA;;;;;AAkBD;;;;;;iBAHc,gBAAA,CACd,MAAA,EAAQ,WAAA,EACR,WAAA,UACA,SAAA"}

package/dist/internal.js

@@ -1,2 +1,2 @@
-import{_ as e,a as t,b as n,c as r,d as i,f as a,g as o,h as s,i as c,l,m as u,n as d,o as f,p,r as m,s as h,u as g,v as _,y as v}from"./client-ClV8ce6X.js";import{parse as y}from"@doync/sqlite-parser";function b(e){return encodeURIComponent(e).replaceAll(`_`,`%5F`)}function x(e,t){let n=b(e);return t===null?`doync__${n}__anon.db`:`doync__${n}__${b(t)}.db`}function S(e){let t;try{t=y(e)}catch(t){return console.warn(`extractWriteTable: failed to parse SQL statement`,{sql:e,err:t}),null}switch(t.kind){case`STMT_INSERT`:case`STMT_UPDATE`:case`STMT_DELETE`:return t.table??null;default:return null}}export{m as ClientEngine,c as __CONNECTED_CLOCK_META_KEY,t as __LOGOUT_BEHAVIOR_META_KEY,l as applyBundledMigrations,_ as asClientMutation,s as bundledSchemaDdl,o as classifyClientStatement,d as createClientEngine,g as createEngineTables,x as dbFileForUserId,i as dropConsumerTables,S as extractWriteTable,f as isFalsyQuery,h as normalizeQuerySurface,p as readMeta,a as replayMigrations,r as settledRejection,e as splitClientStatements,n as toClientMutationRegistry,v as validateMutationArgs,u as writeMeta};
+import{_ as e,a as t,b as n,c as r,d as i,f as a,g as o,h as s,i as c,l,m as u,n as d,o as f,p,r as m,s as h,u as g,v as _,y as v}from"./client-Db0Jfwuy.js";import{parse as y}from"@doync/sqlite-parser";function b(e){return encodeURIComponent(e).replaceAll(`_`,`%5F`)}function x(e,t){let n=b(e);return t===null?`doync__${n}__anon.db`:`doync__${n}__${b(t)}.db`}function S(e){let t;try{t=y(e)}catch(t){return console.warn(`extractWriteTable: failed to parse SQL statement`,{sql:e,err:t}),null}switch(t.kind){case`STMT_INSERT`:case`STMT_UPDATE`:case`STMT_DELETE`:return t.table??null;default:return null}}export{c as ClientEngine,t as __CONNECTED_CLOCK_META_KEY,f as __LOGOUT_BEHAVIOR_PREF_KEY,g as applyBundledMigrations,_ as bundledSchemaDdl,v as classifyClientStatement,d as createClientEngine,i as createEngineTables,x as dbFileForUserId,a as dropConsumerTables,S as extractWriteTable,h as isFalsyQuery,r as normalizeQuerySurface,u as readMeta,s as readPref,p as replayMigrations,m as resolveClientAuthData,l as settledRejection,n as splitClientStatements,o as writeMeta,e as writePref};
 //# sourceMappingURL=internal.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doync/client",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "doync client engine: optimistic Layer-1 savepoint/rebase over a synchronous local-DB port",
   "keywords": [
     "client",
@@ -57,7 +57,7 @@
     }
   },
   "dependencies": {
-    "@doync/core": "0.1.0",
+    "@doync/core": "0.1.1",
     "@doync/sqlite-parser": "0.3053001.0"
   },
   "devDependencies": {
@@ -69,7 +69,7 @@
     "typescript": "^7.0.2",
     "unplugin-raw": "^0.7.0",
     "vitest": "4.1.9",
-    "@doync/drizzle": "0.1.0"
+    "@doync/drizzle": "0.1.1"
   },
   "scripts": {
     "build": "rm -rf dist && tsdown",

package/src/client.ts

@@ -1,25 +1,32 @@
-import type { DoyncSchema, MutationTree } from '@doync/core'
+import type {
+  AuthContext,
+  AuthData,
+  DoyncSchema,
+  MutationTree,
+} from '@doync/core'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+
+import { flattenMutations, validateStandardSchema } from '@doync/core/internal'
 
 import type { DoyncClient, LogoutBehavior, SchemaEvent } from './engine'
 import type { LocalDb } from './port'
 import type { SyncSocket } from './socket'
 
-import { toClientMutationRegistry } from './client-mutation-registry'
-import { ClientEngine, __LOGOUT_BEHAVIOR_META_KEY } from './engine'
-import { createEngineTables, writeMeta } from './replica'
+import { __LOGOUT_BEHAVIOR_PREF_KEY, ClientEngine } from './engine'
+import { createEngineTables, writePref } from './replica'
 
 // The durable logout-policy seam (ADR-0022) is owned by the engine (the layer
-// that owns `__doync_meta` and the runtime {@link ClientEngine.setLogoutBehavior}).
-// Only LogoutBehavior is public; the meta key stays on `./internal`.
+// that owns `__doync_prefs` and the runtime {@link ClientEngine.setLogoutBehavior}).
+// Only LogoutBehavior is public; the pref key stays on `./internal`.
 export type { LogoutBehavior } from './engine'
 
-// Identity is the asserted triple `{ token, ctx, userId }` — never derived
-// from a bearer token (ADR-0018 asserted-identity).
 /**
  * Options for {@link createClient}. Platform adapters (`@doync/web`,
  * `@doync/mobile`) fill these; app code rarely calls `createClient` directly.
  */
-export interface CreateClientOptions<TAuthData = unknown> {
+export interface CreateClientOptions<
+  TAuthContext extends AuthContext = AuthContext,
+> {
   /** Synchronous local SQLite port (wa-sqlite / node:sqlite / op-sqlite). */
   readonly db: LocalDb
   /** Synced schema shared with Origin and Mirror. */
@@ -32,22 +39,16 @@ export interface CreateClientOptions<TAuthData = unknown> {
   /** Transport to the Mirror. */
   readonly socket: SyncSocket
   /**
-   * Bearer credential for the handshake. Does not drive `userId` or `ctx`. Omit
-   * for cookie-session auth.
-   */
-  readonly token?: string
-  /**
-   * Projected auth context for optimistic query/mutation resolution (mirror
-   * your server `toContext`). Defaults to `{}`.
+   * Whole client identity, or `null` for anonymous. `token` is optional inside
+   * {@link AuthData} (cookie auth); `ctx` is required when authenticated.
    */
-  readonly ctx?: TAuthData
+  readonly authData: AuthData<TAuthContext> | null
   /**
-   * Authenticated identity, or `null`/omit for anonymous. Never derived from
-   * `token`.
+   * Standard Schema for `authData.ctx`. When present, construction validates
+   * synchronously and throws on failure. Platform adapters pass the consumer's
+   * shared `ctxValidationSchema`.
    */
-  readonly userId?: string | null
-  /** Pin a durable client id across restarts. */
-  readonly clientId?: string
+  readonly ctxValidationSchema: StandardSchemaV1<unknown, TAuthContext>
   /** Observe schema/recovery transitions. */
   readonly onSchemaEvent?: (event: SchemaEvent) => void
   /**
@@ -63,38 +64,87 @@ export interface CreateClientOptions<TAuthData = unknown> {
  * Mirror socket. App code normally goes through `@doync/web` / `@doync/mobile`
  * instead.
  */
-export function createClient<TAuthData = unknown>(
-  options: CreateClientOptions<TAuthData>,
+export function createClient<TAuthContext extends AuthContext = AuthContext>(
+  options: CreateClientOptions<TAuthContext>,
 ): DoyncClient {
   return createClientEngine(options)
 }
 
+/**
+ * {@link CreateClientOptions} for trusted internal construction: the web DB
+ * worker receives tab-validated identity over the wire and cannot hold the
+ * consumer's schema (a validator is a function), so the schema is optional here
+ * — absent means the caller already validated.
+ */
+export type CreateClientEngineOptions<
+  TAuthContext extends AuthContext = AuthContext,
+> = Omit<CreateClientOptions<TAuthContext>, 'ctxValidationSchema'> & {
+  readonly ctxValidationSchema?: StandardSchemaV1<unknown, TAuthContext>
+  /** Pin a durable client id (monorepo test/bench lanes only). */
+  readonly clientId?: string
+}
+
 /**
  * Concrete-engine factory (ADR-0033 / closeio/doync#241). Same construction as
  * {@link createClient}, but typed as {@link ClientEngine} so platform adapters
  * (web DB-worker, mobile wrapper) can reach engine-only fields like `clientId`
  * without an unchecked downcast. Exported on `@doync/client/internal` only.
  */
-export function createClientEngine<TAuthData = unknown>(
-  options: CreateClientOptions<TAuthData>,
-): ClientEngine {
+export function createClientEngine<
+  TAuthContext extends AuthContext = AuthContext,
+>(options: CreateClientEngineOptions<TAuthContext>): ClientEngine {
   // Logout policy must land before boot (ADR-0022 / #135): construction opens
   // the optimistic overlay (ADR-0019), so a later write on this connection would
   // join the savepoint and roll back. Pre-boot is autocommit.
   if (options.logoutBehavior !== undefined) {
     createEngineTables(options.db)
-    writeMeta(options.db, __LOGOUT_BEHAVIOR_META_KEY, options.logoutBehavior)
+    writePref(options.db, __LOGOUT_BEHAVIOR_PREF_KEY, options.logoutBehavior)
   }
+  const identity = resolveClientAuthData(
+    options.authData,
+    options.ctxValidationSchema,
+  )
   return new ClientEngine({
     db: options.db,
     schema: options.schema,
-    mutations: toClientMutationRegistry(options.mutations),
+    mutations: flattenMutations(options.mutations),
     socket: options.socket,
     // Asserted identity (ADR-0018 / #167): never derived.
-    ctx: (options.ctx as Record<string, unknown> | undefined) ?? {},
-    token: options.token,
-    userId: options.userId ?? null,
+    ctx: identity.ctx,
+    token: identity.token,
+    userId: identity.userId,
     clientId: options.clientId,
     onSchemaEvent: options.onSchemaEvent,
   })
 }
+
+/**
+ * Validate and flatten `authData` for engine slots. When a schema is present
+ * and identity is non-null, `ctx` is validated synchronously (throws at the
+ * call site). Anonymous (`null`) yields `userId: null`, `ctx: null`, no token.
+ */
+export function resolveClientAuthData<TAuthContext extends AuthContext>(
+  authData: AuthData<TAuthContext> | null,
+  ctxValidationSchema?: StandardSchemaV1<unknown, TAuthContext>,
+): {
+  userId: string | null
+  token: string | undefined
+  ctx: AuthContext
+} {
+  if (authData === null) {
+    return { userId: null, token: undefined, ctx: null }
+  }
+  let ctx: Record<string, unknown> = authData.ctx
+  if (ctxValidationSchema !== undefined) {
+    ctx = validateStandardSchema(
+      ctxValidationSchema,
+      authData.ctx,
+      'auth context',
+    ) as Record<string, unknown>
+  }
+  return {
+    userId: authData.userId,
+    token: authData.token,
+    ctx,
+  }
+}