akanjs 3.0.0-beta.9 → 3.0.0

package/types/service/predefinedAdaptor/sql/driver/libsql.d.ts

@@ -1,17 +1,20 @@
-import type { Client as LibsqlClient } from "@libsql/client";
+import type { Client as LibsqlClient, Transaction as LibsqlTransaction } from "@libsql/client";
 import type { AkanSqlClient, AkanSqlStatement } from "../types.d.ts";
+import { type SqliteWriteTurn } from "./bunSqlite.d.ts";
 export declare class LibsqlStatement implements AkanSqlStatement {
+    #private;
     private readonly client;
     private readonly sql;
-    constructor(client: LibsqlClient, sql: string);
+    constructor(client: LibsqlClient | LibsqlTransaction, sql: string, writeTurn?: SqliteWriteTurn);
     run(...params: unknown[]): Promise<import("@libsql/client").ResultSet>;
     get<Row = Record<string, unknown>>(...params: unknown[]): Promise<Row | null>;
     all<Row = Record<string, unknown>>(...params: unknown[]): Promise<Row[]>;
 }
 export declare class LibsqlAkanClient implements AkanSqlClient {
-    readonly client: LibsqlClient;
-    constructor(client: LibsqlClient);
-    execute(sql: string, params?: unknown[] | Record<string, unknown>): Promise<import("@libsql/client").ResultSet>;
+    readonly client: LibsqlClient | LibsqlTransaction;
+    private readonly writeTurn;
+    constructor(client: LibsqlClient | LibsqlTransaction, writeTurn?: SqliteWriteTurn);
+    execute(sql: string, params?: unknown[] | Record<string, unknown>): Promise<unknown>;
     prepare(sql: string): AkanSqlStatement;
     close(): Promise<void>;
 }

package/types/service/predefinedAdaptor/sql/driver/postgres.d.ts

@@ -1,16 +1,16 @@
-import type { Sql } from "postgres";
+import type { Sql, TransactionSql } from "postgres";
 import type { AkanSqlClient, AkanSqlStatement } from "../types.d.ts";
 export declare class PostgresStatement implements AkanSqlStatement {
     private readonly client;
     private readonly sql;
-    constructor(client: Sql, sql: string);
+    constructor(client: Sql | TransactionSql, sql: string);
     run(...params: unknown[]): Promise<import("postgres").RowList<(import("postgres").Row & Iterable<import("postgres").Row>)[]>>;
     get<Row = Record<string, unknown>>(...params: unknown[]): Promise<Row | null>;
     all<Row = Record<string, unknown>>(...params: unknown[]): Promise<Row[]>;
 }
 export declare class PostgresAkanClient implements AkanSqlClient {
-    readonly client: Sql;
-    constructor(client: Sql);
+    readonly client: Sql | TransactionSql;
+    constructor(client: Sql | TransactionSql);
     execute(sql: string, params?: unknown[] | Record<string, unknown>): Promise<import("postgres").RowList<(import("postgres").Row & Iterable<import("postgres").Row>)[]>>;
     prepare(sql: string): AkanSqlStatement;
     close(): Promise<void>;

package/types/service/predefinedAdaptor/sql/search/fts5.d.ts

@@ -0,0 +1,28 @@
+import { type ConstantModel } from "akanjs/constant";
+import { type DatabaseModel, type SearchColumn } from "akanjs/document";
+import type { SqlFrag } from "../types.d.ts";
+import { type ModelTriggers, type SearchColumns, type SearchEngine, type SearchIndexOwner, type SearchQuery } from "./types.d.ts";
+/** The SQLite/libsql index: an fts5 table with `search_doc` as its external content. */
+export declare class Fts5SearchEngine implements SearchEngine {
+    #private;
+    readonly backfillLock = "";
+    readonly merges = true;
+    constructor(owner: SearchIndexOwner, tokenizer: string);
+    /** Quotes every term: a raw `-`, `:`, `*`, `"` or trailing `AND` is fts5 syntax that raises instead of matching. */
+    static matchExpression(text: string, { prefix, columns }?: {
+        prefix?: boolean;
+        columns?: readonly SearchColumn[];
+    }): string | null;
+    schemaDescriptor(): {
+        doc: readonly ["title", "desc", "tag", "thumb", "filter"];
+        columns: readonly ["title", "desc", "tag", "filter"];
+        tokenizer: string;
+    };
+    ensureSchema(current: boolean): Promise<("filter" | "title" | "desc" | "tag" | "thumb")[]>;
+    columns(constant: ConstantModel, database: DatabaseModel, alias: "NEW" | "OLD"): SearchColumns | null;
+    modelTriggers(ref: string, next: SearchColumns, prev: SearchColumns | null): ModelTriggers;
+    createModelTriggers(ref: string, triggers: ModelTriggers, replace: boolean): Promise<void>;
+    dropModelTriggers(ref: string): Promise<void>;
+    merge(): Promise<void>;
+    join({ ref, text, prefix, columns, weights }: SearchQuery): SqlFrag | null;
+}

package/types/service/predefinedAdaptor/sql/search/mirror.d.ts

@@ -0,0 +1,20 @@
+import { type ConstantModel, type FieldObject } from "akanjs/constant";
+import type { DatabaseModel } from "akanjs/document";
+import type { SearchColumns } from "./types.d.ts";
+export interface MirrorSegment {
+    name: string;
+    arrDepth: number;
+}
+/** The `search_doc` row both engines keep, and the parts of the SQL that fills it which read alike in both. */
+export declare class SearchMirror {
+    #private;
+    static readonly docColumns: string;
+    static readonly upsertTail: string;
+    static sqlString(value: string): string;
+    static filterToken(path: string, value: string): string;
+    static columnList(columns: SearchColumns): string;
+    /** The declared field behind each segment of a text path, or null when the model does not declare it. */
+    static segments(fields: FieldObject, path: string): MirrorSegment[] | null;
+    /** Joins one expression per declared path into a column per role; null when the model declares no role at all. */
+    static columns(constant: ConstantModel, database: DatabaseModel, expression: (segments: MirrorSegment[], path: string, role: string) => string): SearchColumns | null;
+}

package/types/service/predefinedAdaptor/sql/search/postgres.d.ts

@@ -0,0 +1,53 @@
+import { type ConstantModel } from "akanjs/constant";
+import { type DatabaseModel, type SearchColumn } from "akanjs/document";
+import type { SqlFrag } from "../types.d.ts";
+import { type ModelTriggers, type SearchColumns, type SearchEngine, type SearchIndexOwner, type SearchQuery } from "./types.d.ts";
+type PostgresSearchMode = {
+    kind: "word";
+    unaccent: boolean;
+} | {
+    kind: "trigram";
+    caseSensitive: boolean;
+};
+export interface PostgresSearchOwner extends SearchIndexOwner {
+    lockSchema<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * A weighted `tsvector` under GIN, or pg_trgm GIN for `trigram`. Matches the rows fts5 matches for the same text; only
+ * the ranking differs, as `ts_rank` has no document-frequency term.
+ */
+export declare class PostgresSearchEngine implements SearchEngine {
+    #private;
+    readonly merges = false;
+    readonly backfillLock = "FOR SHARE OF NEW";
+    constructor(owner: PostgresSearchOwner, { tokenizer, schema }: {
+        tokenizer: string;
+        schema: string;
+    });
+    /** Maps the fts5 tokenizer spelling onto what Postgres can build; anything else would silently match differently. */
+    static mode(tokenizer: string): PostgresSearchMode;
+    /**
+     * `<->` inside a term and `&` between terms, as fts5 reads a quoted term. Stripping ASCII punctuation removes every
+     * tsquery syntax character, so a piece needs no escaping.
+     */
+    static tsquery(text: string, { prefix, columns }: {
+        prefix?: boolean;
+        columns?: readonly SearchColumn[];
+    }): string | null;
+    schemaDescriptor(): {
+        engine: string;
+        mode: PostgresSearchMode;
+        doc: readonly ["title", "desc", "tag", "thumb", "filter"];
+        columns: readonly ["title", "desc", "tag", "filter"];
+        vector: string;
+        purge: string;
+    };
+    ensureSchema(current: boolean): Promise<("filter" | "title" | "desc" | "tag" | "thumb")[]>;
+    columns(constant: ConstantModel, database: DatabaseModel, alias: "NEW" | "OLD"): SearchColumns | null;
+    modelTriggers(ref: string, next: SearchColumns, prev: SearchColumns | null): ModelTriggers;
+    createModelTriggers(ref: string, triggers: ModelTriggers, replace: boolean): Promise<void>;
+    dropModelTriggers(ref: string): Promise<void>;
+    merge(): Promise<void>;
+    join({ ref, text, prefix, columns, weights }: SearchQuery): SqlFrag | null;
+}
+export {};

package/types/service/predefinedAdaptor/sql/search/types.d.ts

@@ -0,0 +1,45 @@
+import type { ConstantModel, textFieldRoles } from "akanjs/constant";
+import type { DatabaseModel, SearchColumn } from "akanjs/document";
+import type { AkanSqlClient, SqlFrag } from "../types.d.ts";
+export declare const DOC_TABLE = "search_doc";
+export declare const FTS_TABLE = "search_fts";
+export type SearchColumns = Record<(typeof textFieldRoles)[number], string>;
+export type ModelTriggers = [name: string, sql: string][];
+export interface SearchIndexOwner {
+    getConnection(): AkanSqlClient;
+    getMeta(key: string): Promise<string | undefined> | string | undefined;
+    setMeta(key: string, value: string): Promise<void>;
+    lockSchema?<T>(fn: () => Promise<T>): Promise<T>;
+    transaction?<T>(fn: () => Promise<T>): Promise<T>;
+}
+export interface SearchQuery {
+    ref: string;
+    text: string;
+    prefix: boolean;
+    columns: readonly SearchColumn[] | undefined;
+    weights: readonly number[];
+}
+/** What differs between fts5 and Postgres; `SearchIndex` owns the rest (disabled marker, hashes, claims, backfill). */
+export interface SearchEngine {
+    /** What the index structure is built from; a change rebuilds it from `search_doc`. */
+    schemaDescriptor(): unknown;
+    /**
+     * Runs under the owner's schema lock or write transaction. `current` means the stored descriptor matches, so only a
+     * missing index is rebuilt. Returns the `search_doc` columns it had to add.
+     */
+    ensureSchema(current: boolean): Promise<string[]>;
+    /** One SQL expression per role over the `alias` row, or null when the model declares no text role. */
+    columns(constant: ConstantModel, database: DatabaseModel, alias: "NEW" | "OLD"): SearchColumns | null;
+    /** The DDL that keeps a ref's mirror rows current. Hashed, so a template change rebuilds the ref. */
+    modelTriggers(ref: string, next: SearchColumns, prev: SearchColumns | null): ModelTriggers;
+    /** `replace` swaps existing definitions; otherwise only the missing ones are created. */
+    createModelTriggers(ref: string, triggers: ModelTriggers, replace: boolean): Promise<void>;
+    dropModelTriggers(ref: string): Promise<void>;
+    /** Follows the backfill's `WHERE`. */
+    readonly backfillLock: string;
+    /** Whether `merge` folds anything; an index that keeps no segments has nothing to fold on a timer. */
+    readonly merges: boolean;
+    merge(): Promise<void>;
+    /** A subquery exposing `rid` and a `score` that sorts best-first ascending; null matches nothing. */
+    join(query: SearchQuery): SqlFrag | null;
+}

package/types/service/predefinedAdaptor/sql/types.d.ts

@@ -2,6 +2,7 @@ import type { PromiseOrObject } from "akanjs/base";
 import type { ConstantModel } from "akanjs/constant";
 import type { DatabaseModel, DocumentQuery, DocumentQueryNode, DocumentSchema, DocumentUpdateInput, DocumentUpdateOperator, DocumentUpdateOptions } from "akanjs/document";
 import type { SearchIndex } from "../searchIndex.d.ts";
+import type { SqlDocumentStore } from "./SqlDocumentStore.d.ts";
 export interface SqliteDatabaseConfig {
     filePath?: string;
     journalMode?: "WAL" | "DELETE" | "TRUNCATE" | "PERSIST" | "MEMORY" | "OFF";
@@ -22,13 +23,14 @@ export interface PostgresDatabaseConfig {
     database?: string;
     user?: string;
     password?: string;
+    /** A login role holding SELECT on base columns and nothing else — the one `InsightQuery` reads as. */
+    insightUrl?: string;
 }
 export interface SearchConfig {
     enabled?: boolean;
     tokenizer?: string;
 }
 export interface DatabaseConfig {
-    driver?: "sqlite" | "libsql" | "postgres";
     sqlite?: SqliteDatabaseConfig;
     libsql?: LibsqlDatabaseConfig;
     postgres?: PostgresDatabaseConfig;
@@ -97,6 +99,9 @@ export interface DocumentStore {
     hydrate(data: DocumentRecord, originalData?: DocumentRecord, options?: {
         track?: boolean;
     }): any;
+    /** A document as text that another process turns back into the same document. */
+    serialize(doc: DocumentRecord): string;
+    deserialize(text: string): any;
 }
 export interface SqlResultRows<Row = Record<string, unknown>> {
     rows: Row[];
@@ -111,11 +116,27 @@ export interface AkanSqlClient {
     prepare(sql: string): AkanSqlStatement;
     close(): Promise<void>;
 }
+/** A connection on which the engine itself cannot reach `_doc`. */
+export interface InsightSession {
+    read(statement: string, timeoutMs: number): Promise<Record<string, unknown>[]>;
+    close(): Promise<void>;
+}
 export interface DatabaseAdaptor {
     getConnection(): AkanSqlClient;
     getStore(constant: ConstantModel, database: DatabaseModel, schema: DocumentSchema): DocumentStore;
+    /** Every model table this process has opened a store for. */
+    stores?(): SqlDocumentStore[];
     transaction<T>(fn: () => PromiseOrObject<T>): Promise<T>;
     getSearchIndex(): SearchIndex | null;
+    openInsight?(): Promise<InsightSession>;
+}
+/** A model row as it is stored, `_doc` parsed — the unit a transfer between databases copies. */
+export interface TransferRow {
+    id: string;
+    createdAt: number;
+    updatedAt: number;
+    removedAt: number | null;
+    _doc: Record<string, unknown>;
 }
 export interface SqliteEnv {
     workspaceRoot?: string;
@@ -164,24 +185,35 @@ export interface SqliteDocumentRow {
     _doc: string;
 }
 export type ProjectedSqliteDocumentRow = Omit<SqliteDocumentRow, "_doc"> & Record<string, unknown>;
+export interface ConcurrentIndexBuild {
+    name: string;
+    /** Where a replacement is built before it takes `name` over. */
+    next: string;
+    create: (name: string) => string;
+    /** The index exists under a different descriptor and is rebuilt; otherwise it is built only if missing. */
+    replace: boolean;
+}
 export interface DocumentDatabaseOwner {
     getConnection(): AkanSqlClient;
     getSearchIndex(): SearchIndex | null;
     getMeta(key: string): Promise<string | undefined> | string | undefined;
     setMeta(key: string, value: string): Promise<void>;
     afterCommit(fn: () => PromiseOrObject<void>): Promise<void>;
+    transaction?<T>(fn: () => PromiseOrObject<T>): Promise<T>;
+    /** Runs `fn` as the only schema change: Postgres races two `CREATE … IF NOT EXISTS` into a duplicate-key error. */
+    lockSchema?<T>(fn: () => Promise<T>): Promise<T>;
+    hasTable?(table: string): Promise<boolean>;
+    hasValidIndex?(name: string): Promise<boolean>;
+    /** Lets the role `InsightQuery` reads as see the table's base columns, and never `_doc`. */
+    grantInsight?(table: string): Promise<void>;
+    /** Builds an index on a table that already holds rows without blocking its writes; never inside a transaction. */
+    buildIndexConcurrently?(build: ConcurrentIndexBuild): Promise<void>;
 }
 export declare const QUERY_OPERATOR_KEYS: Set<string>;
 export interface SqlFrag {
     sql: string;
     params: unknown[];
 }
-export interface SearchJoinProps {
-    alias: string;
-    ref: string;
-    match: string;
-    weights: number[];
-}
 export interface SearchJoin extends SqlFrag {
     alias: string;
 }
@@ -194,28 +226,50 @@ export interface CompileContext {
     joins: SearchJoin[];
     conjunctive: boolean;
 }
+/**
+ * `text` for a declared string (`String`, `ID`, a string enum, a relation's id), `json` for the rest, untyped paths
+ * included. SQLite reads both alike; Postgres compares them apart.
+ */
+export type PathKind = "text" | "json";
+export interface IndexColumn {
+    path: string;
+    expr: string;
+    isArray: boolean;
+}
+export interface CreateIndexProps {
+    name: string;
+    table: string;
+    unique: boolean;
+    columns: IndexColumn[];
+    /** Build without blocking writes to a table that already holds rows. Postgres only, and never in a transaction. */
+    concurrently?: boolean;
+}
 export interface SqlDialect {
     readonly name: "sqlite" | "postgres";
     timestampType(): string;
     docColumnType(): string;
     docColumn(): string;
     docValuePlaceholder(): string;
-    extract(path: string): string;
+    extract(path: string, kind?: PathKind): string;
     projectExpr(path: string): string;
     decodeProjected(value: unknown): unknown;
-    eq(path: string, value: unknown): SqlFrag;
-    ne(path: string, value: unknown): SqlFrag;
-    compare(path: string, op: "gt" | "gte" | "lt" | "lte", value: unknown): SqlFrag;
-    between(path: string, from: unknown, to: unknown): SqlFrag;
-    inList(path: string, values: unknown[]): SqlFrag;
-    notInList(path: string, values: unknown[]): SqlFrag;
+    eq(path: string, value: unknown, kind?: PathKind): SqlFrag;
+    ne(path: string, value: unknown, kind?: PathKind): SqlFrag;
+    compare(path: string, op: "gt" | "gte" | "lt" | "lte", value: unknown, kind?: PathKind): SqlFrag;
+    between(path: string, from: unknown, to: unknown, kind?: PathKind): SqlFrag;
+    inList(path: string, values: unknown[], kind?: PathKind): SqlFrag;
+    notInList(path: string, values: unknown[], kind?: PathKind): SqlFrag;
     exists(path: string): SqlFrag;
     missing(path: string): SqlFrag;
     empty(path: string): SqlFrag;
     arrayHas(path: string, value: unknown): SqlFrag;
     contains(path: string, value: unknown): SqlFrag;
-    searchJoin(props: SearchJoinProps): SqlFrag;
+    orderTerm(expr: string, direction: 1 | -1): string;
+    indexName(name: string): string;
+    createIndex(props: CreateIndexProps): string;
     applyUpdate(acc: string, op: DocumentUpdateOperator, path: string, value: unknown): SqlFrag;
+    /** The stored document with these top-level fields replaced (value as JSON text) and these removed. */
+    mergeDocument(set: [field: string, json: string][], removed: string[]): SqlFrag;
     affectedRows(result: unknown): number;
 }
 export type QueryLeafOps = Pick<SqlDialect, "eq" | "ne" | "compare" | "between" | "inList" | "notInList" | "exists" | "missing" | "empty" | "arrayHas" | "contains">;

package/types/service/predefinedAdaptor/sql/values.d.ts

@@ -10,4 +10,12 @@ export declare const toPostgresSql: (sql: string, params: unknown[]) => {
 export declare const encodeSqlValue: (value: unknown) => unknown;
 export declare const decodeDateValue: (value: unknown) => import("dayjs").Dayjs | null | undefined;
 export declare const jsonStr: (value: unknown) => string;
+/** Postgres refuses U+0000 inside jsonb, so every mode refuses it — one app stores the same thing in each. */
+export declare const assertStorableJson: (json: string, table: string) => string;
+export declare const likePattern: (value: unknown) => string;
 export declare const BASE_COLUMN_LEAF: QueryLeafOps;
+export declare const quoteIdent: (identifier: string) => string;
+export declare const jsonPath: (path: string) => string;
+export declare const stableJson: (value: unknown) => string;
+/** Stored in `_akan_meta`, so a changed schema definition is detected without migrations. */
+export declare const descriptorHash: (value: unknown) => Promise<string>;

package/types/service/predefinedAdaptor/sqlitePath.d.ts

@@ -6,4 +6,5 @@ interface ResolveDefaultSqliteFileOptions {
     workspaceRoot?: string;
 }
 export declare const resolveDefaultSqliteFile: ({ appName, fileName, isProduction, operationMode, workspaceRoot, }: ResolveDefaultSqliteFileOptions) => string;
+export declare const defaultSqliteFile: (suffix: string, workspaceRoot?: string) => string;
 export {};

package/types/service/predefinedAdaptor/sseData.d.ts

@@ -0,0 +1 @@
+export declare const eachSseData: (body: ReadableStream<Uint8Array>, onData: (payload: string) => void) => Promise<void>;

package/types/service/predefinedAdaptor/storage.adaptor.d.ts

@@ -1,4 +1,3 @@
-import { type BaseEnv } from "akanjs/base";
 export interface DownloadRequest {
     path: string;
     localPath: string;
@@ -53,7 +52,7 @@ export interface StorageAdaptor {
     deleteData(url: string): Promise<boolean>;
     deleteDataByPath(path: string): Promise<boolean>;
 }
-export interface BlobStorageOptions extends BaseEnv {
+export interface BlobStorageOptions {
     blobStorage?: {
         baseDir?: string;
         privateBaseDir?: string;
@@ -67,6 +66,8 @@ declare const BlobStorage_base: import("..").AdaptorCls<{}, {
 }>;
 export declare class BlobStorage extends BlobStorage_base implements StorageAdaptor {
     #private;
+    /** Throws for a deployed `multiple`/`cluster` app on local disk unless `AKAN_STORAGE_SHARED=true` marks it shared. */
+    static assertShared(storage: string): void;
     readData(path: string): Promise<ReadableStream>;
     readDataAsJson<T>(path: string): Promise<T>;
     getDataList(prefix?: string): Promise<string[]>;

package/types/service/predefinedAdaptor/websocket.adaptor.d.ts

@@ -1,42 +1,41 @@
-import type { BaseEnv, Cls } from "akanjs/base";
-import { ProtobufCompressor } from "./compress.adaptor";
 export interface WsSocketData {
     socketId?: string;
     createdAt?: number;
 }
 export type WsRedisEventHandler = (roomId: string, data: unknown) => void;
+/** A committed write to a model that live slices route, as text every server of the app turns back into documents. */
+export interface LiveChange {
+    refName: string;
+    next: string;
+    /** Absent on a create. */
+    previous?: string;
+}
+export type LiveChangeHandler = (change: LiveChange) => void;
+export interface WebsocketPublishOption {
+    /** Only the newest frame for the room matters, so an undelivered older one may be dropped for it. */
+    coalesce?: boolean;
+}
 export interface WebsocketAdaptor {
-    /** Publish data to a room across all server instances */
-    publish(roomId: string, data: unknown): void;
-    /** Register an event handler for incoming cross-server messages */
+    /** Across every server instance. */
+    publish(roomId: string, data: unknown, option?: WebsocketPublishOption): void;
     setEventHandler(handler: WsRedisEventHandler): void;
-    /** Unregister the event handler */
     clearEventHandler(): void;
-    /**
-     * Called after the cross-server channel has been down and come back, if this transport can lose one.
-     *
-     * A dropped subscription is the one message loss nothing else notices: the client's own socket stays open the
-     * whole time, so it has no reason to suspect its list is behind. A transport with no channel to lose — the
-     * single-node one, which delivers through the gateway's own IPC — leaves this out.
-     */
+    /** After a lost cross-server channel returns — a loss the still-open client socket never notices. Optional. */
     onRecovered?(handler: () => void): void;
-    /** Register endpoint return type info for protobuf encoding */
-    registerEndpoint(key: string, returnRef: Cls, arrDepth: number): void;
-    /** Register a socket joining a room (tracked in Redis for cross-server awareness) */
+    /** To every other server of the app: the writer only knows its own rooms, and a batch process holds none. */
+    publishChange?(change: LiveChange): void;
+    onChange?(handler: LiveChangeHandler): void;
     joinRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void>;
-    /** Remove a socket from a room */
     leaveRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void>;
-    /** Remove a socket from all rooms and clean up its Redis state */
     leaveAllRooms(ws: Bun.ServerWebSocket<unknown>): Promise<void>;
-    /** Register a socket connection on this server */
     registerSocket(ws: Bun.ServerWebSocket<unknown>, meta?: Record<string, string>): Promise<void>;
-    /** Unregister a socket connection */
     unregisterSocket(ws: Bun.ServerWebSocket<unknown>): Promise<void>;
 }
 declare const WebSocketRedisAdaptor_base: import("..").AdaptorCls<{}, {
-    redis: import("..").InjectInfo<"plug", import("ioredis").default, never, never>;
-    compressor: import("..").InjectInfo<"plug", ProtobufCompressor, never, never>;
-    serverId: import("..").InjectInfo<"env", string, BaseEnv, never>;
+    channelPrefix: import("..").InjectInfo<"plug", string, never, never>;
+    serverId: import("..").InjectInfo<"env", string, {
+        [key: string]: any;
+    }, never>;
     publisher: import("..").InjectInfo<"plug", import("ioredis").default, never, never>;
     subscriber: import("..").InjectInfo<"plug", import("ioredis").default, never, never>;
 }>;
@@ -44,15 +43,16 @@ export declare class WebSocketRedisAdaptor extends WebSocketRedisAdaptor_base im
     #private;
     onInit(): Promise<void>;
     onDestroy(): Promise<void>;
-    publish(roomId: string, data: unknown): void;
+    publish(roomId: string, data: unknown, { coalesce }?: WebsocketPublishOption): void;
+    publishChange(change: LiveChange): void;
+    onChange(handler: LiveChangeHandler): void;
     setEventHandler(handler: WsRedisEventHandler): void;
     clearEventHandler(): void;
     onRecovered(handler: () => void): void;
-    registerEndpoint(key: string, returnRef: Cls, arrDepth: number): void;
     joinRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void>;
     leaveRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void>;
     leaveAllRooms(ws: Bun.ServerWebSocket<unknown>): Promise<void>;
-    registerSocket(ws: Bun.ServerWebSocket<unknown>, meta?: Record<string, string>): Promise<void>;
+    registerSocket(ws: Bun.ServerWebSocket<unknown>): Promise<void>;
     unregisterSocket(ws: Bun.ServerWebSocket<unknown>): Promise<void>;
 }
 export {};

package/types/service/serviceModule.d.ts

@@ -1,6 +1,6 @@
-import type { MergeAllKeyOfObjects, PromiseOrObject, UnCls } from "akanjs/base";
+import type { MergeAllKeyOfObjects, UnCls } from "akanjs/base";
 import type { ConstantModel, QueryOf } from "akanjs/constant";
-import type { CRUDEventType, DatabaseModel, DataInputOf, Doc, FindQueryOption, ListQueryOption, SaveEventType } from "akanjs/document";
+import { type DatabaseModel, type DataInputOf, type Doc, type FilterInfo, type FindQueryOption, type ListQueryOption, type SaveEventListener, type SaveEventType } from "akanjs/document";
 import type { ServiceCls } from "./serve.d.ts";
 import type { DatabaseService } from "./types.d.ts";
 export declare class ServiceModel<Srv extends ServiceCls = ServiceCls, CnstModel extends ConstantModel = any, DbModel extends DatabaseModel = any, SrvMap extends {
@@ -19,7 +19,7 @@ export declare class ServiceModel<Srv extends ServiceCls = ServiceCls, CnstModel
     static from<Srv extends ServiceCls>(srv: Srv): ServiceModel<Srv, never, never, { [K in `${Uncapitalize<Srv["refName"]>}Service`]: UnCls<Srv>; }>;
     with<SrvModules extends ServiceModel[]>(...srvs: SrvModules): ServiceModel<Srv, CnstModel, DbModel, SrvMap & MergeAllKeyOfObjects<SrvModules, "srvMap">>;
     static getDefaultDbServiceMethods(className: string): {
-        [x: string]: ((this: DatabaseService, query: QueryOf<any>, queryOption?: ListQueryOption) => Promise<any>) | ((this: DatabaseService, query: QueryOf<any>, queryOption?: FindQueryOption) => Promise<any>) | ((this: DatabaseService, id: string, data: Partial<Doc>) => Promise<Partial<Doc>>) | ((this: DatabaseService, type: SaveEventType, listener: (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>) => any) | ((this: DatabaseService, id: string, data: DataInputOf) => Promise<any>);
+        [x: string]: ((this: DatabaseService, query: QueryOf<any>, queryOption?: ListQueryOption) => Promise<any>) | ((this: DatabaseService, query: QueryOf<any>, queryOption?: FindQueryOption) => Promise<any>) | ((this: DatabaseService, id: string, data: Partial<Doc>) => Promise<Partial<Doc>>) | ((this: DatabaseService, type: SaveEventType, listener: SaveEventListener<Doc>) => any) | ((this: DatabaseService, id: string, data: DataInputOf) => Promise<any>);
         __get(this: DatabaseService, id: string): Promise<any>;
         __load(this: DatabaseService, id?: string): Promise<any>;
         __loadMany(this: DatabaseService, ids: string[]): Promise<any>;
@@ -38,13 +38,13 @@ export declare class ServiceModel<Srv extends ServiceCls = ServiceCls, CnstModel
         _postUpdate(this: DatabaseService, doc: Doc): Promise<Doc>;
         _preRemove(this: DatabaseService, id: string): Promise<void>;
         _postRemove(this: DatabaseService, doc: Doc): Promise<Doc>;
-        listenPre(this: DatabaseService, type: SaveEventType, listener: (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>): any;
-        listenPost(this: DatabaseService, type: SaveEventType, listener: (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>): any;
+        listenPre(this: DatabaseService, type: SaveEventType, listener: SaveEventListener<Doc>): any;
+        listenPost(this: DatabaseService, type: SaveEventType, listener: SaveEventListener<Doc>): any;
         __create(this: DatabaseService, data: DataInputOf): Promise<any>;
         __update(this: DatabaseService, id: string, data: DataInputOf): Promise<any>;
         __remove(this: DatabaseService, id: string): Promise<Doc>;
     };
-    static getFilterServiceMethods(queryKey: string, queryFn: (...args: any[]) => QueryOf<any>): {
-        [x: string]: (this: DatabaseService, ...args: any) => any;
+    static getFilterServiceMethods(queryKey: string, filterInfo: FilterInfo): {
+        [x: string]: (...args: any) => any;
     };
 }

package/types/service/toolNames.d.ts

@@ -1,34 +1,17 @@
 import type { AgentWireToolCall, LlmTurnRequest } from "./predefinedAdaptor/llm.adaptor";
 /**
- * Renames a turn's tools onto what a provider's function-calling wire accepts, and reads the answer back.
- *
- * A zone publishes its tools scope-prefixed — `videoProjectDraft.createVideoProject` — which is legal for MCP,
- * where `.` is an allowed character and the scope join. Every OpenAI-compatible and Anthropic function schema is
- * narrower: `[A-Za-z0-9_-]`, at most 64 characters. A provider that validates answers 400; DeepSeek does not, and
- * what happened instead was worse to debug — the model normalized the illegal name itself, called the bare
- * `createVideoProject`, and the browser answered `Unknown tool`, spending a turn on a tool that was published all
- * along.
- *
- * Renamed here rather than in each adaptor for the reason `AgentService.explained` gives: every adaptor would
- * otherwise have to remember, and forgetting is silent. A name the wire already accepts is left alone, so the
- * root agent's request is byte-for-byte what it was.
+ * OpenAI-dialect and Anthropic function names are `[A-Za-z0-9_-]{1,64}` while a zone scopes tools with `.`; DeepSeek
+ * does not refuse an illegal name but calls a normalized one that the browser does not know.
  */
 export declare class ToolNames {
     #private;
-    /** Both dialects reject a longer name, and neither says so in terms of the tool you wrote. */
     static readonly limit = 64;
-    /**
-     * Every name the request carries, not just the published ones: the transcript holds calls to tools that have
-     * since left the screen, and one of those reaching the wire unrenamed is the same failure a turn later.
-     */
+    /** The transcript's names too: a call to a tool that has since left the screen still reaches the wire. */
     static of(request: LlmTurnRequest): ToolNames;
     constructor(names: Iterable<string>);
     get renamed(): boolean;
     wire(name: string): string;
-    /**
-     * Unknown stays as it came. A model that invented a name is answered by the surface's own `Unknown tool`, which
-     * lands in the transcript as a tool result it can correct from — guessing which tool it meant would run one.
-     */
+    /** An invented name stays as it came for the surface's `Unknown tool`: guessing the intended tool would run one. */
     surface(name: string): string;
     encode(request: LlmTurnRequest): LlmTurnRequest;
     decode(calls: AgentWireToolCall[]): AgentWireToolCall[];

package/types/service/types.d.ts

@@ -1,7 +1,7 @@
 import type { Cls, MergeAllTypes, PromiseOrObject } from "akanjs/base";
 import type { Logger } from "akanjs/common";
 import type { QueryOf } from "akanjs/constant";
-import type { CRUDEventType, DatabaseModel, DataInputOf, DocumentUpdateInput, FilterInstance, FindQueryOption, GetDocObject, ListQueryOption, QueryMethodPart, SaveEventType, UpdateResult } from "akanjs/document";
+import type { DatabaseModel, DataInputOf, DocumentUpdateInput, FilterInstance, FindQueryOption, GetDocObject, ListQueryOption, QueryMethodPart, SaveEventListener, SaveEventType, UpdateResult } from "akanjs/document";
 type ServiceMixinOmitKey = "onInit" | "onDestroy" | "_libsOnInit" | "_libsOnDestroy" | "_preCreate" | "_postCreate" | "_preUpdate" | "_postUpdate" | "_preRemove" | "_postRemove" | "_libsPreCreate" | "_libsPostCreate" | "_libsPreUpdate" | "_libsPostUpdate" | "_libsPreRemove" | "_libsPostRemove";
 type DatabaseQueryMethods<Query, Sort, Obj, Doc, Insight, FindQueryOption, ListQueryOption, DocQuery> = QueryMethodPart<Query, Sort, Obj, Doc, Insight, FindQueryOption, ListQueryOption, DocQuery>;
 type DocumentLike = {
@@ -56,8 +56,8 @@ export type DatabaseService<T extends string = string, Input = any, Doc = any, O
     __libsPostUpdate: (doc: Doc) => Promise<Doc>;
     __libsPreRemove: (id: string) => Promise<void>;
     __libsPostRemove: (doc: Doc) => Promise<Doc>;
-    listenPre: (type: SaveEventType, listener: (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>) => () => void;
-    listenPost: (type: SaveEventType, listener: (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>) => () => void;
+    listenPre: (type: SaveEventType, listener: SaveEventListener<Doc>) => () => void;
+    listenPost: (type: SaveEventType, listener: SaveEventListener<Doc>) => () => void;
 } & {
     [key in `${T}Model`]: Model;
 } & {