akanjs 3.0.0-beta.8 → 3.0.0

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

@@ -1,4 +1,4 @@
-import type { AgentWireMessage, LlmAccepts, LlmTurnAnswer, LlmTurnRequest } from "./llm.adaptor";
+import type { AgentWireMessage, LlmAccepts, LlmTurnAnswer, LlmTurnRequest, LlmUsage } from "./llm.adaptor";
 export interface OpenaiToolCall {
     id?: string;
     function?: {
@@ -6,6 +6,14 @@ export interface OpenaiToolCall {
         arguments?: string;
     };
 }
+interface OpenaiUsage {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+    } | null;
+    prompt_cache_hit_tokens?: number;
+}
 export interface OpenaiAnswer {
     choices?: {
         message?: {
@@ -14,6 +22,7 @@ export interface OpenaiAnswer {
         };
         finish_reason?: string;
     }[];
+    usage?: OpenaiUsage | null;
 }
 type OpenaiContentPart = {
     type: "text";
@@ -37,22 +46,9 @@ export interface OpenaiMessage {
     }[];
     tool_call_id?: string;
 }
-/**
- * The OpenAI chat-completions wire format, which several providers speak — OpenAI's own endpoint, DeepSeek, and
- * every gateway that copied it. It lives apart from any one of them because a protocol fix belongs in one place:
- * the SSE tool-call assembly below is the subtle part, and two copies of it drift silently.
- *
- * `accepts` decides the shape of a user turn, and nothing else here reads it. A provider that takes no image gets
- * one string, exactly as before, because `AgentService.readable` has already reduced every attachment it cannot
- * read to a note in the text.
- */
+/** The chat-completions wire that OpenAI, DeepSeek and every gateway copying them speak. */
 export declare class OpenaiDialect {
-    /**
-     * The types this dialect's image part reads. Exact rather than an `image/*` prefix and declared apart from
-     * Anthropic's identical-looking set, because the two are each a provider's own list and only happen to agree:
-     * an unsupported one passed through is a refused *request*, not an unread attachment, so the safe direction is
-     * to name what is known to work and note the rest.
-     */
+    /** Apart from Anthropic's identical set: each is one provider's list, and an unlisted type is a refused request. */
     static readonly imageTypes: Set<string>;
     static requestBody(model: string, request: LlmTurnRequest, { accepts, stream }?: {
         accepts?: LlmAccepts;
@@ -68,36 +64,23 @@ export declare class OpenaiDialect {
         }[] | undefined;
         messages: OpenaiMessage[];
         stream?: boolean | undefined;
+        stream_options?: {
+            include_usage: boolean;
+        } | undefined;
         model: string;
     };
     /** Context rides below the instructions framed as data — screen state must never read as directives. */
     static systemPrompt({ instructions, context }: LlmTurnRequest): string;
     static providerMessages(message: AgentWireMessage, accepts?: LlmAccepts): OpenaiMessage[];
-    /**
-     * Text attachments are labelled into the message, because a model handed two unlabelled documents can no longer
-     * cite either one. Images become their own parts only when the provider said it reads them; the dialect carries
-     * one as a `data:` URL, which is the same encoding whether the bytes were inlined or already addressable, so
-     * both carriers take one branch — the inlined bytes first, for the reason named at the branch.
-     */
     static userContent(message: AgentWireMessage, accepts?: LlmAccepts): string | OpenaiContentPart[];
-    /**
-     * The dialect streams `data: {chunk}` SSE lines ending with `data: [DONE]`. Tool calls arrive fragmented — the
-     * first fragment of an index carries id/name, later ones append to the arguments string — so they are assembled
-     * by index and parsed once at the end; only assistant text is worth reporting as it arrives.
-     */
     static consumeStream(body: ReadableStream<Uint8Array>, onDelta: (delta: string) => void): Promise<LlmTurnAnswer>;
-    /**
-     * The ceiling wins over the calls that did arrive. A turn the provider cut short is one whose last call may be
-     * missing, so running the batch it did finish is acting on half an intention.
-     */
+    static usageOf(usage: OpenaiUsage): LlmUsage;
+    /** The ceiling wins over the calls that did arrive: a cut-off turn's last call may be missing. */
     static stopOf(finish: string | null | undefined, calls: number): LlmTurnAnswer["stop"];
     static turnAnswer(answer: OpenaiAnswer): LlmTurnAnswer;
     /** The provider sends arguments as a JSON string; an unparsable one becomes an empty call rather than a crash. */
     static parsedArgs(raw: string | undefined): Record<string, unknown>;
-    /**
-     * The dialect answers a refusal as `{ error: { message } }`, and that sentence is the useful half — a request
-     * past the context window says exactly which limit it passed.
-     */
+    /** The dialect refuses as `{ error: { message } }`, and that sentence names the limit a long prompt passed. */
     static reasonOf(response: Response): Promise<string>;
 }
 export {};

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

@@ -1,24 +1,19 @@
-import type { LlmAccepts, LlmAdaptor, LlmOption, LlmTurnAnswer, LlmTurnRequest } from "./llm.adaptor";
+import type { LlmAccepts, LlmAdaptor, LlmLimits, LlmOption, LlmTurnAnswer, LlmTurnRequest } from "./llm.adaptor";
 declare const OpenaiLlm_base: import("..").AdaptorCls<{}, {
     llmOption: import("..").InjectInfo<"use", LlmOption, never, never>;
 }>;
 /**
- * OpenAI's chat-completions endpoint, and every gateway that serves the same dialect — `host` is what points it
- * at one. It is `DeepseekLlm`'s sibling rather than its replacement: same wire, and the difference that earns a
- * second class is that this one declares `accepts`, so an attached image reaches the model as an image part
- * instead of a note saying it could not be read.
- *
- * `model` is required and has no default. A default would be a model name that ages out of the provider's
- * catalogue into a 404 at the first turn, and — worse here than for a text-only adaptor — it would decide the
- * vision claim below on the app's behalf. Name the model in `option.setLlm({ model })`, and name
- * `accepts: { image: false }` beside it when that model is one of the provider's text-only ones.
+ * The default `LlmAdaptorRole` fill, for every host serving the chat-completions wire. `model` has no default: one
+ * would age into a 404 and decide the vision claim on the app's behalf.
  */
 export declare class OpenaiLlm extends OpenaiLlm_base implements LlmAdaptor {
     #private;
-    /** The endpoint takes image parts, so that is the provider's answer; a model that does not takes the override. */
-    get accepts(): LlmAccepts;
+    static readonly defaultHost = "https://api.openai.com/v1";
+    /** No answer ceiling: the dialect sends none, so the provider's own default is the one that applies. */
+    get limits(): LlmLimits;
+    /** A named host is text-only until `setLlm({ accepts })` says otherwise: undecodable bytes fail the whole turn. */
+    get accepts(): LlmAccepts | undefined;
     chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null>;
-    /** Carried on the `Err` so the chat prints the provider's own sentence rather than a status number. */
-    static refusal(response: Response): Promise<Error>;
+    static refusal(host: string, response: Response): Promise<Error>;
 }
 export {};

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

@@ -1,21 +1,26 @@
+import type { Redis } from "ioredis";
 import type { AkanJob, AkanJobOptions, AkanWorker } from "../ipcTypes.d.ts";
-type QueueLike = {
+interface BullEmitter {
+    on(event: "error", listener: (error: Error) => void): unknown;
+    waitUntilReady(): Promise<unknown>;
+    close(): Promise<void>;
+}
+interface QueueLike extends BullEmitter {
     add(name: string, args: unknown[], options?: AkanJobOptions): Promise<unknown>;
-};
-type WorkerLike = AkanWorker;
+}
+type WorkerLike = AkanWorker & BullEmitter;
 export interface QueueAdaptor {
     registerProcessWorker(key: string, handler: (job: AkanJob) => Promise<unknown>): AkanWorker;
     registerProcessQueue(key: string, args: unknown[], jobOptions?: AkanJobOptions): Promise<AkanJob>;
 }
 declare const BullQueue_base: import("..").AdaptorCls<{}, {
-    redis: import("..").InjectInfo<"plug", import("ioredis").default, never, never>;
-    prefix: import("..").InjectInfo<"env", string, {
-        [key: string]: any;
-    }, never>;
+    redis: import("..").InjectInfo<"plug", Redis, never, never>;
+    prefix: import("..").InjectInfo<"plug", string, never, never>;
 }>;
 export declare class BullQueue extends BullQueue_base implements QueueAdaptor {
     #private;
     onInit(): Promise<void>;
+    onDestroy(): Promise<void>;
     getQueue(key: string): QueueLike;
     registerProcessWorker(key: string, handler: (job: AkanJob) => Promise<unknown>): WorkerLike;
     registerProcessQueue(key: string, args: unknown[], jobOptions?: AkanJobOptions): Promise<AkanJob>;

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

@@ -20,7 +20,9 @@ export interface ScheduleAdaptor {
     }): NodeJS.Timeout;
     unregisterTimeout(key: string): void;
     getInit(key: string): (() => Promise<void>) | undefined;
-    registerInit(key: string, callback: () => Promise<void>): void;
+    registerInit(key: string, callback: () => Promise<void>, option?: {
+        once?: boolean;
+    }): void;
     unregisterInit(key: string): void;
     _runInit(): Promise<void>;
     getDestroy(key: string): (() => Promise<void>) | undefined;
@@ -32,6 +34,7 @@ declare const Scheduler_base: import("..").AdaptorCls<{}, {
     cache: import("..").InjectInfo<"plug", import("./cache.adaptor").CacheAdaptor, never, never>;
 }>;
 export declare class Scheduler extends Scheduler_base implements ScheduleAdaptor {
+    #private;
     readonly lockMap: Map<string, boolean>;
     readonly cronMap: Map<string, AkanCronJob>;
     readonly intervalMap: Map<string, NodeJS.Timeout>;
@@ -52,7 +55,9 @@ export declare class Scheduler extends Scheduler_base implements ScheduleAdaptor
     registerTimeout(key: string, scheduleTime: number, callback: () => Promise<void>): NodeJS.Timeout;
     unregisterTimeout(key: string): void;
     getInit(key: string): (() => Promise<void>) | undefined;
-    registerInit(key: string, callback: () => Promise<void>): void;
+    registerInit(key: string, callback: () => Promise<void>, { once }?: {
+        once?: boolean;
+    }): void;
     unregisterInit(key: string): void;
     _runInit(): Promise<void>;
     getDestroy(key: string): (() => Promise<void>) | undefined;

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

@@ -1,73 +1,43 @@
-import { type ConstantModel, textFieldRoles } from "akanjs/constant";
-import { type DatabaseModel, type SearchColumn } from "akanjs/document";
-import type { AkanSqlClient } from "./database.adaptor";
-export declare const DOC_TABLE = "search_doc";
-export declare const FTS_TABLE = "search_fts";
+import type { ConstantModel } from "akanjs/constant";
+import type { DatabaseModel } from "akanjs/document";
+import { type SearchColumns, type SearchEngine, type SearchIndexOwner, type SearchQuery } from "./sql/search/types.d.ts";
+export { Fts5SearchEngine } from "./sql/search/fts5.d.ts";
+export { PostgresSearchEngine } from "./sql/search/postgres.d.ts";
+export type { SearchEngine, SearchIndexOwner, SearchQuery } from "./sql/search/types.d.ts";
+export { DOC_TABLE, FTS_TABLE } from "./sql/search/types.d.ts";
 export declare const DEFAULT_TOKENIZER = "unicode61 remove_diacritics 2";
 export declare const OPTIMIZE_CRON_KEY = "searchIndexOptimize";
 export declare const OPTIMIZE_CRON = "17 4 * * *";
 export declare const RETRY_INTERVAL_KEY = "searchIndexRetry";
 export declare const RETRY_INTERVAL_MS = 60000;
 export declare const DEFAULT_SEARCH_WEIGHTS: number[];
-export interface SearchIndexOwner {
-    getConnection(): AkanSqlClient;
-    getMeta(key: string): Promise<string | undefined> | string | undefined;
-    setMeta(key: string, value: string): Promise<void>;
-}
 export interface SearchIndexOptions {
     enabled: boolean;
     tokenizer: string;
 }
-type SearchColumns = Record<(typeof textFieldRoles)[number], string>;
-/**
- * Reads `AKAN_SEARCH_ENABLED`. Unset means enabled; an unrecognised value fails the boot rather than
- * silently falling back, because a typo like `ture` would otherwise look identical to the default.
- */
+/** Unset means enabled; an unrecognised value fails the boot, since a typo like `ture` would look like the default. */
 export declare const parseSearchEnabled: (value: string | undefined) => boolean;
-/**
- * Turns raw user input into an fts5 MATCH expression.
- *
- * Raw text cannot be passed through: `-`, `:`, `*`, `"` and a trailing `AND` are all fts5 syntax and each
- * raises `SQLiteError` instead of returning no rows. Quoting every term makes the whole input literal.
- */
-export declare const toMatchExpression: (text: string, { prefix, columns }?: {
-    prefix?: boolean;
-    columns?: readonly SearchColumn[];
-}) => string | null;
-/**
- * Owns the `search_doc` mirror and its fts5 index.
- *
- * The mirror is maintained by SQL triggers rather than document hooks because `updateOneByQuery` and friends
- * deliberately fire no hooks — most searchable-field mutations go through exactly that path, so an app-level
- * hook would miss them silently.
- */
+/** The `search_doc` mirror is trigger-maintained, not hook-maintained: `updateOneByQuery` and friends fire no hooks. */
 export declare class SearchIndex {
     #private;
-    constructor(owner: SearchIndexOwner, { enabled, tokenizer }: SearchIndexOptions);
+    constructor(owner: SearchIndexOwner, { enabled, tokenizer }: SearchIndexOptions, engine?: SearchEngine);
     get enabled(): boolean;
     ensureSchema(): Promise<void>;
     /** Returns whether this ref's mirror is now current. `false` means another process is rebuilding it. */
     ensureRef(constant: ConstantModel, database: DatabaseModel): Promise<boolean>;
-    /** Re-runs the refs another process was holding. Returns how many are still outstanding. */
+    /** Returns how many held refs are still outstanding. */
     retryPending(): Promise<number>;
     /**
-     * Rebuilds one ref's mirror rows in id-ordered chunks so a large table does not block the boot. `onChunk` runs
-     * between chunks and reports whether this process still holds the claim: a backfill that outlives the lock TTL
-     * would otherwise keep writing rows underneath the `DELETE` of the process that took over. Returns whether the
-     * whole table was covered.
+     * `onChunk` reports whether this process still holds the claim, or an outlived backfill writes under the new holder's
+     * `DELETE`. Returns whether the whole table was covered.
      */
     reconcileRef(ref: string, columns: SearchColumns, onChunk?: () => Promise<boolean>): Promise<boolean>;
-    /** Merges accumulated fts5 segments. Returns whether this process was the one that did the work. */
+    /** Returns whether this process was the one that merged. */
     optimize(): Promise<boolean>;
-    /**
-     * Drops a ref's triggers so a bulk import skips the per-row mirror write. Pair with `resume`.
-     *
-     * The hash is cleared here rather than in `resume` alone: a process that dies mid-import never reaches `resume`,
-     * and a boot that finds the hash intact recreates the triggers and skips the backfill, leaving everything
-     * written in between missing from the mirror for good.
-     */
+    /** Pair with `resume`. The hash is cleared here too: a process dying mid-import must not skip the backfill. */
     suspend(database: DatabaseModel): Promise<void>;
     /** Returns whether the mirror is current again; `false` means another process holds the rebuild. */
     resume(constant: ConstantModel, database: DatabaseModel): Promise<boolean>;
+    /** The subquery `q.search()` joins; null when the text holds nothing to match, which matches no row. */
+    join(query: SearchQuery): import("./sql/types.d.ts").SqlFrag | null;
 }
-export {};

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

@@ -1,4 +1,4 @@
-import type { CacheAdaptor, CacheSetOptions } from "./cache.adaptor";
+import type { CacheAdaptor, CacheSetOptions, CacheValue } from "./cache.adaptor";
 import { type SolidConfig, type SolidEnv } from "./solidSqlite.d.ts";
 declare const SolidCache_base: import("..").AdaptorCls<{}, {
     config: import("..").InjectInfo<"env", Required<SolidConfig>, SolidEnv, never>;
@@ -7,14 +7,23 @@ export declare class SolidCache extends SolidCache_base implements CacheAdaptor
     #private;
     onInit(): Promise<void>;
     onDestroy(): Promise<void>;
-    set(topic: string, key: string, value: string | number | Buffer, option?: CacheSetOptions): Promise<void>;
-    get<T extends string | number | Buffer>(topic: string, key: string): Promise<T | undefined>;
+    set(topic: string, key: string, value: CacheValue, option?: CacheSetOptions): Promise<void>;
+    get<T extends CacheValue = CacheValue>(topic: string, key: string): Promise<T | undefined>;
     delete(topic: string, key: string): Promise<void>;
-    hset(topic: string, key: string, subKey: string, value: string | number | Buffer, option?: CacheSetOptions): Promise<void>;
-    hget<T extends string | number | Buffer>(topic: string, key: string, subKey: string): Promise<T | undefined>;
+    getDel<T extends CacheValue = CacheValue>(topic: string, key: string): Promise<T | undefined>;
+    setIfAbsent(topic: string, key: string, value: CacheValue, option?: CacheSetOptions): Promise<boolean>;
+    incr(topic: string, key: string, by?: number, option?: CacheSetOptions): Promise<number>;
+    acquireLease(topic: string, key: string, owner: string, ttlMs: number): Promise<boolean>;
+    renewLease(topic: string, key: string, owner: string, ttlMs: number): Promise<boolean>;
+    releaseLease(topic: string, key: string, owner: string): Promise<void>;
+    hset(topic: string, key: string, subKey: string, value: CacheValue, option?: CacheSetOptions): Promise<void>;
+    hget<T extends CacheValue = CacheValue>(topic: string, key: string, subKey: string): Promise<T | undefined>;
     hdelete(topic: string, key: string, subKey: string): Promise<void>;
     hkeys(topic: string, key: string): Promise<string[]>;
-    hentries<T extends string | number | Buffer>(topic: string, key: string): Promise<[string, T][]>;
+    hentries<T extends CacheValue = CacheValue>(topic: string, key: string): Promise<[string, T][]>;
     hclear(topic: string, key: string): Promise<void>;
+    hgetDel<T extends CacheValue = CacheValue>(topic: string, key: string, subKey: string): Promise<T | undefined>;
+    hsetIfAbsent(topic: string, key: string, subKey: string, value: CacheValue, option?: CacheSetOptions): Promise<boolean>;
+    hincr(topic: string, key: string, subKey: string, by?: number, option?: CacheSetOptions): Promise<number>;
 }
 export {};

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

@@ -1,16 +1,18 @@
-import type { BaseEnv, Cls } from "akanjs/base";
-import type { WebsocketAdaptor, WsRedisEventHandler } from "./websocket.adaptor";
+import type { LiveChange, LiveChangeHandler, WebsocketAdaptor, WsRedisEventHandler } from "./websocket.adaptor";
 declare const SolidPubSub_base: import("..").AdaptorCls<{}, {
-    serverId: import("..").InjectInfo<"env", string, BaseEnv, never>;
+    serverId: import("..").InjectInfo<"env", string, {
+        [key: string]: any;
+    }, never>;
 }>;
 export declare class SolidPubSub extends SolidPubSub_base implements WebsocketAdaptor {
     #private;
     onInit(): Promise<void>;
     onDestroy(): Promise<void>;
     publish(roomId: string, data: unknown): void;
+    publishChange(change: LiveChange): void;
+    onChange(handler: LiveChangeHandler): void;
     setEventHandler(handler: WsRedisEventHandler): void;
     clearEventHandler(): 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>;

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

@@ -1,5 +1,5 @@
 import { Database } from "bun:sqlite";
-import { type Dayjs } from "akanjs/base";
+import type { Dayjs } from "akanjs/base";
 export interface SolidConfig {
     filePath?: string;
     journalMode?: "WAL" | "DELETE" | "TRUNCATE" | "PERSIST" | "MEMORY" | "OFF";
@@ -8,6 +8,7 @@ export interface SolidConfig {
     cleanupIntervalMs?: number;
     queuePollIntervalMs?: number;
     queueLeaseMs?: number;
+    queueFailedRetentionMs?: number;
 }
 export interface SolidEnv {
     workspaceRoot?: string;

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

@@ -0,0 +1,20 @@
+import type { Options, PostgresType } from "postgres";
+import type { InsightSession } from "./types.d.ts";
+interface PostgresInsightSessionProps {
+    url: string;
+    schema: string;
+    options: Options<Record<string, PostgresType>>;
+}
+/**
+ * Its own login as a role with SELECT on base columns only, so Postgres refuses `_doc` however it is reached (`*`, a
+ * whole-row value, `query_to_xml`). Not `SET ROLE`: a statement could `set_config('role', 'none', true)` its way back
+ * to the app's role. A role that can read `_doc` anywhere is refused on open.
+ */
+export declare class PostgresInsightSession implements InsightSession {
+    #private;
+    private constructor();
+    static open({ url, schema, options }: PostgresInsightSessionProps): Promise<PostgresInsightSession>;
+    read(statement: string, timeoutMs: number): Promise<Record<string, unknown>[]>;
+    close(): Promise<void>;
+}
+export {};

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

@@ -1,27 +1,25 @@
 import { type DocumentQuery } from "akanjs/document";
-import { type CompiledQuery, type FieldMap, type SqlDialect } from "./types.d.ts";
+import { type SearchIndex } from "../searchIndex.d.ts";
+import { type CompiledQuery, type FieldMap, type PathKind, type SqlDialect } from "./types.d.ts";
 export declare class QueryCompiler {
     #private;
     private readonly fields;
     private readonly dialect;
     private readonly ref;
-    private readonly searchEnabled;
-    constructor(fields: FieldMap, dialect: SqlDialect, ref: string, searchEnabled: () => boolean);
+    private readonly searchIndex;
+    constructor(fields: FieldMap, dialect: SqlDialect, ref: string, searchIndex: () => SearchIndex | null);
     compile(query?: DocumentQuery): CompiledQuery;
     orderBy(sort?: Record<string, 1 | -1>): string;
     fieldExpr(path: string): string;
+    /** Walks declared scalar models down the path; a path through anything else is one the model does not type. */
+    pathKind(path: string): PathKind;
+    isArrayPath(path: string): boolean;
     projectExpr(path: string): string;
     private compileNode;
     private compileField;
     /**
-     * The root segment only, deliberately.
-     *
-     * Everything past it reaches the escaped JSON-path literal and nothing else, so a deep typo is a query that
-     * matches nothing rather than a query that does something else. Validating it would mean walking the field
-     * graph through array indices (`payments.3.name`), array-of-object leaves (`works.tags`) and `Map` keys, which
-     * have no fixed path to check against — a validator that guessed there would refuse working queries, which is
-     * worse than the silence. Deep paths are written by the model's own filter code, where the first test catches
-     * a typo; the root is the one segment a caller can reach.
+     * The root segment only: a deeper typo reaches only the escaped JSON-path literal and matches nothing, while checking
+     * indices, array leaves and `Map` keys would refuse working queries.
      */
     private assertPath;
     private isQueryNode;

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

@@ -1,7 +1,7 @@
 import { type ConstantModel } from "akanjs/constant";
 import { type DatabaseModel, type DocumentQuery, type DocumentSchema, type DocumentUpdateInput, type DocumentUpdateOptions } from "akanjs/document";
 import { QueryCompiler } from "./QueryCompiler.d.ts";
-import { type DocumentDatabaseOwner, type DocumentRecord, type FindManyOptions, type FindOneOptions, type SortOption, type SqlDialect, type WriteHookOptions } from "./types.d.ts";
+import { type DocumentDatabaseOwner, type DocumentRecord, type FindManyOptions, type FindOneOptions, type SortOption, type SqlDialect, type TransferRow, type WriteHookOptions } from "./types.d.ts";
 import { UpdateCompiler } from "./UpdateCompiler.d.ts";
 export declare class SqlDocumentStore {
     #private;
@@ -21,6 +21,10 @@ export declare class SqlDocumentStore {
     }): Promise<any>;
     update(id: string, patch: DocumentRecord, options?: WriteHookOptions): Promise<any>;
     remove(id: string): Promise<any>;
+    /** Up to `limit` stored rows after the id `after`, in id order and removed ones included. */
+    exportRows(after: string, limit: number): Promise<TransferRow[]>;
+    /** Rows as another database stored them: a taken id is replaced, and no hook runs or field is derived. */
+    importRows(rows: TransferRow[]): Promise<void>;
     updateOneByQuery(query: DocumentQuery, update: DocumentUpdateInput, options?: DocumentUpdateOptions): Promise<{
         acknowledged: boolean;
         matchedCount: number;
@@ -57,12 +61,8 @@ export declare class SqlDocumentStore {
         upsertedId: string | null;
     }>;
     find(query?: DocumentQuery, options?: FindManyOptions): Promise<any[]>;
-    findIds(query?: DocumentQuery, options?: {
-        sort?: SortOption;
-        skip?: number | null;
-        limit?: number | null;
-        sample?: number;
-    }): Promise<string[]>;
+    findIds(query?: DocumentQuery, options?: Omit<FindManyOptions, "select">): Promise<string[]>;
+    private listQuery;
     findOne(query?: DocumentQuery, options?: FindOneOptions): Promise<any>;
     findId(query?: DocumentQuery, options?: {
         sort?: SortOption;
@@ -100,28 +100,14 @@ export declare class SqlDocumentStore {
     private decodeNestedValue;
     private normalizeWriteValue;
     private fillScalarDefaults;
-    /**
-     * `track` buys `isModified()` and costs a deep clone of the row, so it is decided per call site rather than
-     * paid everywhere. Only the read paths (`find`, and the projected read behind it) opt out — that clone was 42%
-     * of a list query, and a listed document is never the one a save hook runs on. Everything else keeps it, so an
-     * external caller of `hydrate` sees no change.
-     */
+    /** `track` buys `isModified()` with a deep clone of the row; only the read paths opt out. */
     hydrate(data: DocumentRecord, originalData?: DocumentRecord, { track }?: {
         track?: boolean;
     }): any;
+    serialize(doc: DocumentRecord): string;
+    deserialize(text: string): any;
     private runHooks;
     private insertStmt;
-    private prepareReadStmt;
+    private prepareStmt;
     private assertValidRefName;
 }
-/**
- * The schema setups `getStore` starts but nobody awaits.
- *
- * `getStore` returns a store synchronously while `ensure()` goes on creating tables and indexes, so
- * the connection could be closed out from under one — a server shutting down, or a test tearing its
- * fixture down. That surfaced as an unhandled `Cannot use a closed database` blamed on whatever ran
- * next, which made it look like a flaky test rather than a race at shutdown.
- *
- * Every statement `ensure()` runs is `IF NOT EXISTS`, so one cut short is simply redone on the next
- * boot; a failure *before* the close is still a real problem and still surfaces.
- */

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

@@ -0,0 +1,15 @@
+import type { InsightSession } from "./types.d.ts";
+/**
+ * Attached to a fresh in-memory connection under a random schema, every `_doc` table shadowed by a TEMP view omitting
+ * it: bun:sqlite has no authorizer, and no text check can hold since SQLite reads `'admin'.'_doc'` as the column.
+ * `query_only` refuses every write, whatever the text.
+ */
+export declare class SqliteInsightSession implements InsightSession {
+    #private;
+    private constructor();
+    static open(file: string): SqliteInsightSession;
+    /** No second connection can open an in-memory database, so it is read from a copy that lives for one session. */
+    static openSnapshot(bytes: Uint8Array): Promise<SqliteInsightSession>;
+    read(statement: string): Promise<Record<string, unknown>[]>;
+    close(): Promise<void>;
+}

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

@@ -11,7 +11,3 @@ export declare class UpdateCompiler {
         setOnInsert: Record<string, unknown>;
     };
 }
-/**
- * Per-document modification state, attached only when a document is hydrated for writing.
- * Non-enumerable so `{ ...doc }` in `toRow` and `Object.entries` in `sanitizeJson` never see it.
- */

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

@@ -1,27 +1,35 @@
 import type { DocumentUpdateOperator } from "akanjs/document";
-import type { SearchJoinProps, SqlDialect, SqlFrag } from "../types.d.ts";
+import type { CreateIndexProps, PathKind, SqlDialect, SqlFrag } from "../types.d.ts";
 export declare class PostgresDialect implements SqlDialect {
     #private;
     readonly name: "postgres";
+    /**
+     * `jsonb_set` drops a nested write whose parent is missing, where SQLite's `json_set` creates it. A function, since
+     * inline SQL would re-read the folded document per level and repeat every earlier operation's parameters.
+     */
+    static schemaSetup(): string;
     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;
+    decodeProjected(value: unknown): any;
+    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({ ref }: SearchJoinProps): SqlFrag;
+    orderTerm(expr: string, direction: 1 | -1): string;
+    indexName(name: string): string;
+    createIndex({ name, table, unique, columns, concurrently }: CreateIndexProps): string;
     applyUpdate(acc: string, op: DocumentUpdateOperator, path: string, value: unknown): SqlFrag;
+    mergeDocument(set: [field: string, json: string][], removed: string[]): SqlFrag;
     affectedRows(result: unknown): number;
 }

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

@@ -1,5 +1,5 @@
 import type { DocumentUpdateOperator } from "akanjs/document";
-import type { SearchJoinProps, SqlDialect, SqlFrag } from "../types.d.ts";
+import type { CreateIndexProps, SqlDialect, SqlFrag } from "../types.d.ts";
 export declare class SqliteDialect implements SqlDialect {
     #private;
     readonly name: "sqlite";
@@ -21,7 +21,10 @@ export declare class SqliteDialect implements SqlDialect {
     empty(path: string): SqlFrag;
     arrayHas(path: string, value: unknown): SqlFrag;
     contains(path: string, value: unknown): SqlFrag;
-    searchJoin({ alias, ref, match, weights }: SearchJoinProps): SqlFrag;
+    orderTerm(expr: string, direction: 1 | -1): string;
+    indexName(name: string): string;
+    createIndex({ name, table, unique, columns }: CreateIndexProps): string;
     applyUpdate(acc: string, op: DocumentUpdateOperator, path: string, value: unknown): SqlFrag;
+    mergeDocument(set: [field: string, json: string][], removed: string[]): SqlFrag;
     affectedRows(result: unknown): number;
 }

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

@@ -1,16 +1,22 @@
 import type { Database, Statement } from "bun:sqlite";
 import type { AkanSqlClient, AkanSqlStatement } from "../types.d.ts";
+/** Resolves once a write from the calling context may run; `null` when it may run now. */
+export type SqliteWriteTurn = () => Promise<void> | null;
+export declare const openTurn: SqliteWriteTurn;
+export declare const waitForTurn: (sql: string, writeTurn: SqliteWriteTurn) => () => Promise<void>;
 export declare class BunSqliteStatement implements AkanSqlStatement {
+    #private;
     private readonly statement;
-    constructor(statement: Statement);
+    constructor(statement: Statement, sql: string, writeTurn?: SqliteWriteTurn);
     run(...params: unknown[]): Promise<import("bun:sqlite").Changes>;
     get<Row = Record<string, unknown>>(...params: unknown[]): Promise<Row | null>;
     all<Row = Record<string, unknown>>(...params: unknown[]): Promise<Row[]>;
 }
 export declare class BunSqliteClient implements AkanSqlClient {
     readonly db: Database;
-    constructor(db: Database);
-    execute(sql: string, params?: unknown[] | Record<string, unknown>): Promise<import("bun:sqlite").Changes>;
+    private readonly writeTurn;
+    constructor(db: Database, writeTurn?: SqliteWriteTurn);
+    execute(sql: string, params?: unknown[] | Record<string, unknown>): Promise<unknown>;
     prepare(sql: string): AkanSqlStatement;
     close(): Promise<void>;
 }