akanjs 3.0.0-beta.2 → 3.0.0-beta.21

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>;
 }

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>;