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

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

@@ -0,0 +1,15 @@
+import type { DatabaseAdaptor } from "./sql/types.d.ts";
+export interface TransferReport {
+    table: string;
+    rows: number;
+}
+/**
+ * Model tables to one NDJSON file each and back, rows as stored. `_akan_meta`, the search mirror, the cache and the
+ * queue stay behind: the target writes its own meta and rebuilds the mirror; sessions and pending jobs do not move.
+ */
+export declare class DocumentTransfer {
+    #private;
+    constructor(database: DatabaseAdaptor);
+    exportTo(dir: string): Promise<TransferReport[]>;
+    importFrom(dir: string): Promise<TransferReport[]>;
+}

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

@@ -2,9 +2,10 @@ export * from "./anthropicLlm.d.ts";
 export * from "./cache.adaptor";
 export * from "./compress.adaptor";
 export * from "./database.adaptor";
-export * from "./deepseekLlm.d.ts";
+export * from "./documentTransfer.d.ts";
 export * from "./insightQuery.d.ts";
 export * from "./llm.adaptor";
+export * from "./llmOverflow.d.ts";
 export * from "./logging.adaptor";
 export * from "./openaiDialect.d.ts";
 export * from "./openaiLlm.d.ts";

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

@@ -1,47 +1,24 @@
-import type { AkanSqlClient } from "./database.adaptor";
+import type { DatabaseAdaptor } from "./database.adaptor";
 export interface InsightQueryOptions {
-    /** Rows to return at most. Clamped to `InsightQuery.maxRows`, which no caller can raise. */
+    /** Clamped to `InsightQuery.maxRows`, which no caller can raise. */
     limit?: number;
-    /** How long to wait for the driver, in ms. See the note on `#raced` for which dialects this can actually stop. */
+    /** In ms. Only Postgres stops the query (`statement_timeout`); a synchronous `bun:sqlite` read runs to the end. */
     timeoutMs?: number;
 }
 export interface InsightQueryResult {
     columns: string[];
     rows: Record<string, unknown>[];
-    /** The ceiling cut the answer short, so the caller knows not to read it as complete. */
     truncated: boolean;
 }
 /**
- * One read-only SQL statement, for an agent or an operator asking a question the domain endpoints cannot express.
- *
- * This is the layer-bypassing read, and every safeguard the framework has is bypassed with it — guards, soft delete,
- * cascade, `_postRemove`, and the `hidden`/`secret` masking every other response path performs. So it is read-only
- * by construction rather than by convention, and it is deliberately *not* wired to an endpoint here: the framework
- * owns no guard strong enough to sit in front of it. An app that wants it writes the endpoint with its own
- * `SuperAdmin`, the same way guards ship with the library that owns the model.
- *
- * Three things enforce read-only, and only the third is ours:
- *
- * 1. The statement is wrapped as a derived table — `SELECT * FROM (<sql>) AS "akanInsight" LIMIT ?`. Nothing but a
- *    query is legal in that position, in either dialect, so a write is a syntax error from the engine rather than a
- *    pattern this code had to recognise. A second statement smuggled behind `;` is a syntax error for the same
- *    reason, and the row ceiling rides along on the same wrapper.
- * 2. A rejection before execution, so the caller reads why rather than a syntax error. It runs on the statement with
- *    comments and string literals removed, because that is what makes `-- ` and `'…'` unable to hide anything.
- * 3. **`_doc` never crosses the boundary.** Every non-base field lives in that one JSON column, which is where the
- *    plan's "re-apply schema-based masking" runs into the fact that an arbitrary SELECT has no model to mask by. So
- *    the enforceable rule is the column itself: unnameable in the statement, dropped from the rows, and any cell
- *    that still arrives holding a JSON object or array is refused. An insight is made of scalars; a value that is
- *    not one is either a document or indistinguishable from it.
- *
- * What that costs is real and worth saying: this answers "how many, since when, grouped how" over base columns and
- * the search mirror, and it cannot read a domain field. Field-level reads go through the domain tools, which mask.
+ * One read-only statement that bypasses guards, soft delete and `hidden`/`secret` masking, so no endpoint is wired
+ * here: an app fronts it with its own `SuperAdmin`. `_doc` is withheld by the engine — `openInsight()` opens a
+ * read-only connection lacking the column, since no text check catches `*`, whole-row values or quoted names.
  */
 export declare class InsightQuery {
     #private;
-    /** Not an option. A caller asking for more gets this, because the point is that no caller sets the ceiling. */
     static readonly maxRows = 1000;
-    constructor(client: AkanSqlClient);
+    constructor(database: DatabaseAdaptor);
     run(sql: string, { limit, timeoutMs }?: InsightQueryOptions): Promise<{
         columns: string[];
         rows: Record<string, unknown>[];

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

@@ -10,11 +10,7 @@ export interface AgentWireToolResult {
     changes?: unknown[];
     error?: string;
 }
-/**
- * A file the caller attached to one message. Exactly one carrier reaches the model — `data` as inlined bytes, `url`
- * as something the provider fetches, `text` as content already extracted — and which of them a given provider can
- * read is what `LlmAccepts` answers.
- */
+/** Exactly one carrier reaches the model: `data` (inlined bytes), `url` (fetched by the provider) or `text`. */
 export interface AgentWireAttachment {
     name: string;
     mimeType: string;
@@ -22,24 +18,32 @@ export interface AgentWireAttachment {
     data?: string;
     url?: string;
     text?: string;
-    /** The host's own handle on this file, carried so a relay can act on it. A provider mapping ignores it. */
+    /** The host's own handle on this file, for a relay; a provider mapping ignores it. */
     ref?: string;
 }
 /**
- * One transcript message of the in-page agent wire (`use-agentic`'s WIRE.md), typed at both ends independently —
- * the wire is the contract, so the server never imports the client package.
+ * `value` is a send-time snapshot the host already masked — the server has no model class to mask it with — and
+ * `refName`/`refId`/`path` lead back to the current value.
  */
+export interface AgentWireReference {
+    refName: string;
+    refId: string;
+    label: string;
+    path?: string;
+    value?: unknown;
+    /** Read by the model in place of a value there is none of — clipped, unreadable, or gone from a restored chat. */
+    note?: string;
+}
+/** `use-agentic`'s WIRE.md, typed at both ends independently so the server never imports the client package. */
 export interface AgentWireMessage {
     role: "user" | "assistant" | "tool";
     text?: string;
     attachments?: AgentWireAttachment[];
+    references?: AgentWireReference[];
     toolCalls?: AgentWireToolCall[];
     toolResults?: AgentWireToolResult[];
     error?: string;
-    /**
-     * Stands in for the messages the client's own compaction replaced. It arrives with the user's role because the
-     * wire has no other, but it is history rather than an ask, so a provider mapping frames it as one.
-     */
+    /** A compaction summary: it arrives with the user's role but is history, not an ask, and a provider frames it so. */
     summary?: boolean;
 }
 export interface AgentWireTool {
@@ -61,71 +65,67 @@ export interface LlmTurnRequest {
 export interface LlmTurnAnswer {
     text?: string;
     toolCalls?: AgentWireToolCall[];
-    /**
-     * Why the turn ended. `"length"` is the provider's ceiling — `finish_reason: "length"`, `stop_reason:
-     * "max_tokens"` — and it is distinguished from `"end"` because the two are indistinguishable downstream
-     * otherwise: a truncated answer reads as a complete one, and a turn cut off mid tool call carries no complete
-     * call at all, so it would end the loop looking exactly like a model that chose to stop.
-     */
+    /** `"length"` is the provider's ceiling; a turn cut off mid tool call must not read as a model that chose to stop. */
     stop: "end" | "toolUse" | "length";
+    /** Absent when the provider reported nothing. */
+    usage?: LlmUsage;
+    /** The model that answered, as the adaptor named it to the provider. */
+    model?: string;
+}
+/** `inputTokens` is the whole prompt, cached part included; `cachedTokens` is the share billed at the cache rate. */
+export interface LlmUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens: number;
 }
 /**
- * The provider seam for one stateless agent turn: the whole transcript in, one assistant answer out. The server
- * relays — it never executes a client tool — so this is the only surface a provider integration fills. An
- * implementation is an `adapt()` class in a lib's `srvkit/`.
- *
- * `null` means this provider is not configured, and the caller turns it into the one sentence that says so. A
- * failure the provider explained is logged and **thrown** instead, as an `Err` whose text the chat prints: a
- * refused turn and an unconfigured app are different things to be told, and collapsing both into `null` left a
- * user reading "no model is configured" about a conversation that had merely outgrown the context window.
+ * The provider seam for one stateless agent turn; the server relays and never executes a client tool. `chat`
+ * resolves `null` only when unconfigured — a refusal the provider explained is thrown as an `Err` the chat prints.
  */
 export interface LlmAdaptor {
-    /**
-     * `onDelta` opts into streaming: the adapter reports assistant text as it arrives and still resolves the full
-     * answer. An adapter may ignore it — the caller treats zero reported deltas as "answered whole".
-     */
+    /** `onDelta` opts into streaming and the full answer still resolves; an adaptor may ignore it. */
     chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null>;
-    /** Which attachment carriers this provider's model can read. Omitted means text only. */
+    /** Omitted means text only. */
     readonly accepts?: LlmAccepts;
+    /** Omitted means nothing is known. */
+    readonly limits?: LlmLimits;
+}
+/** Relayed to the browser on every turn, so the chat compacts its transcript before the provider refuses it. */
+export interface LlmLimits {
+    /** The model's context window, prompt and answer together. */
+    window?: number;
+    /** The answer ceiling the adaptor actually requests; left out when it sends none. */
+    output?: number;
 }
 /**
- * What an adaptor's model reads beyond text. Declared rather than defaulted to true, because the failure of
- * guessing wrong is the worst one available: a provider handed bytes it cannot decode either rejects the whole
- * turn or accepts it having seen nothing, and the model then answers confidently about a file it never read.
- * `AgentService` degrades what is not accepted into a note the model can repeat back, so a text-only provider
- * needs no attachment code at all — which is every provider until somebody swaps one in for vision.
+ * Declared, never defaulted to true: a provider handed bytes it cannot decode refuses the turn or answers about a
+ * file it never read. `AgentService` degrades what is not accepted into a note.
  */
 export interface LlmAccepts {
-    /** Inlined or linked image bytes. */
     image?: boolean;
     /** Non-image bytes handed over whole — a PDF the model parses itself. */
     document?: boolean;
 }
 /**
- * Settings for whichever adaptor fills `LlmAdaptorRole`, registered with `option.setLlm(...)` and injected as the
- * `llmOption` use. It belongs to the role rather than to one provider: swapping the default for another `adapt()`
- * class re-reads the same three fields under that provider's own defaults.
+ * Registered with `option.setLlm(...)` for whichever adaptor fills `LlmAdaptorRole`. `setLlm` keeps extra fields, so
+ * a custom adaptor extends this interface and reads it with `use<MyLlmOption>()`.
  */
 export interface LlmOption {
     apiKey?: string;
     model?: string;
     host?: string;
-    /**
-     * What the *configured* model reads beyond text, overriding what the adaptor claims for its provider. It rides
-     * beside `model` because that is what capability belongs to: an adaptor answers for an API, and one API serves
-     * models that differ. Declared here rather than as a table the framework keeps, because a table is a claim about
-     * models that ship after it and goes quietly wrong — and getting this wrong is the worst failure available, a
-     * provider handed bytes it cannot decode either refusing the turn or accepting it having seen nothing.
-     */
+    /** Overrides what the adaptor claims for its provider: one API serves models that read different things. */
     accepts?: LlmAccepts;
     /**
-     * The answer ceiling, for an API that requires one. A fixed default is a hazard on a model that thinks before
-     * it writes: the budget goes on reasoning and the turn comes back empty with a length stop, which reads as the
-     * model refusing rather than as a number being too small.
-     *
-     * Sampling knobs are deliberately absent from this option. They are the one place a per-model difference is a
-     * hard failure rather than a nuance — `temperature` is a 400 on some models rather than an ignored field — so
-     * the role carries nothing it would have to guess the legality of per model.
+     * The answer ceiling, for an API that requires one. Sampling knobs are absent on purpose: `temperature` is a 400
+     * on some models.
      */
     maxTokens?: number;
+    /** In tokens. Left out, the chat learns it from the first refusal that names it. */
+    contextWindow?: number;
 }
+/**
+ * The refusing party printed on `agent.error.llmRequestFailed`: the host, not the adaptor's name, since one dialect
+ * class serves many hosts. A host that is not a URL is printed as written.
+ */
+export declare const llmProviderOf: (host: string) => string;

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

@@ -0,0 +1,16 @@
+/** Each field is present only when the refusal named it. */
+export interface LlmOverflowFacts {
+    limit?: number;
+    requested?: number;
+}
+/** Matches each provider's own too-long-prompt sentence; a status code cannot tell it from any other bad request. */
+export declare class LlmOverflow {
+    #private;
+    static readonly patterns: RegExp[];
+    /** A quota borrows the same words, and compacting a conversation that fit loses detail for nothing. */
+    static readonly quotas: RegExp[];
+    static readonly measured: RegExp[];
+    static match(reason: string): LlmOverflowFacts | null;
+    /** `contextOverflow` when the prompt did not fit (the chat compacts and asks again), else `llmRequestFailed`. */
+    static refusal(host: string, status: number, reason: string): Error;
+}

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,16 +46,10 @@ 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 {
+    /** 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;
         stream?: boolean;
@@ -61,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.
-     */
     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;