akanjs 3.0.0-beta.8 → 3.0.0

package/types/service/liveSyncHub.d.ts

@@ -28,25 +28,12 @@ interface LiveRoom {
     evaluator: DocumentQueryEvaluator;
     payload: "light" | "id";
     subscribers: number;
-    /**
-     * Top-level `<path> eq <value>` conditions this room's query requires, when it is a plain conjunction of them.
-     * A change whose document disagrees with one of these cannot belong to this room, and cannot have belonged to it
-     * before either, so the room is skipped without walking its tree at all.
-     */
+    /** The query's top-level `eq` conditions when it is a plain conjunction; a document disagreeing skips the room. */
     index: Map<string, unknown> | null;
 }
 /**
- * Routes a document change to the rooms it belongs to.
- *
- * A room is one live subscription's resolved query, kept from the moment the socket subscribed. When a document
- * changes, the same query is evaluated against the version before the write and the version after it, and the pair
- * of answers is the event: appearing is `enter`, disappearing is `leave`, and staying is `update`. That is why the
- * CRUD verb never reaches a subscriber — an edit that moves a row out of a filter has to arrive as a removal from
- * that list, and a create that lands in one has to arrive as an insertion, which the verb alone cannot say.
- *
- * Every read wraps the caller's query in `removedAt` being empty (`SqlDocumentStore.findForRead`), and that wrapper
- * is added by the store rather than carried in the descriptor a slice returns. It is applied here for the same
- * reason: without it a soft delete still satisfies the query and would be routed as an ordinary update.
+ * Evaluates each room's query before and after a write: appearing is `enter`, disappearing `leave`, staying `update`.
+ * `removedAt` is wrapped in here as the store does on every read, or a soft delete would route as an update.
  */
 export declare class LiveSyncHub {
     #private;
@@ -54,14 +41,9 @@ export declare class LiveSyncHub {
     roomCountOf(refName: string): number;
     /** Idempotent: a second socket subscribing to the same room shares the one evaluation. */
     join({ refName, roomId, query, fallback, payload, fields }: LiveRoomRegistration): LiveRoom;
-    /** Every room this process currently holds, for a recovery that has to tell all of them to resynchronize. */
     roomIds(): string[];
     leave(roomId: string): void;
-    /**
-     * Which rooms this change belongs to and how it reads in each.
-     *
-     * `previous` is absent on a create, which is the same thing as having belonged to no room before.
-     */
+    /** `previous` is absent on a create — no room held the document before. */
     route(refName: string, next: Record<string, unknown>, previous?: Record<string, unknown>): LiveRoomTarget[];
 }
 export {};

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

@@ -1,4 +1,4 @@
-import type { AgentWireAttachment, AgentWireMessage, LlmAccepts, LlmAdaptor, LlmOption, LlmTurnAnswer, LlmTurnRequest } from "./llm.adaptor";
+import type { AgentWireAttachment, AgentWireMessage, LlmAccepts, LlmAdaptor, LlmLimits, LlmOption, LlmTurnAnswer, LlmTurnRequest, LlmUsage } from "./llm.adaptor";
 type AnthropicSource = {
     type: "base64";
     media_type: string;
@@ -30,6 +30,12 @@ interface AnthropicMessage {
     role: "user" | "assistant";
     content: AnthropicBlock[];
 }
+interface AnthropicUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_read_input_tokens?: number | null;
+    cache_creation_input_tokens?: number | null;
+}
 interface AnthropicAnswer {
     content?: {
         type?: string;
@@ -39,46 +45,27 @@ interface AnthropicAnswer {
         input?: Record<string, unknown>;
     }[];
     stop_reason?: string;
+    usage?: AnthropicUsage;
 }
 declare const AnthropicLlm_base: import("..").AdaptorCls<{}, {
     llmOption: import("..").InjectInfo<"use", LlmOption, never, never>;
 }>;
-/**
- * Anthropic's Messages API — the one provider akanjs ships that reads a picture and a PDF.
- *
- * It is not the chat-completions dialect wearing a different host: the system prompt is a top-level field rather
- * than a message, tool calls and their results are content blocks rather than a parallel `tool_calls` array, the
- * results ride in a *user* turn, roles must alternate, and `max_tokens` is required. So it is its own file rather
- * than a branch in `OpenaiDialect`, and nothing is shared between them but the wire they both map from.
- *
- * `model` is required and has no default, for the reason `OpenaiLlm` gives.
- */
+/** Anthropic's Messages API, which reads images and PDFs. `model` is required and has no default. */
 export declare class AnthropicLlm extends AnthropicLlm_base implements LlmAdaptor {
     #private;
     /** Pinned rather than read from a header the API might move: a revision change is a mapping change, not config. */
     static readonly version = "2023-06-01";
-    /**
-     * The API refuses a request that names no ceiling, so one is always sent. An agent turn's answer is a sentence
-     * and a few tool calls, so this is slack rather than a budget — except on a model that reasons before it
-     * writes, which can spend the whole of it thinking and return nothing with a length stop. That reads as the
-     * model refusing, so it is `option.setLlm({ maxTokens })` and not a constant.
-     */
+    /** The API refuses a request with no ceiling; a reasoning model may spend all of it thinking, hence `maxTokens`. */
     static readonly defaultMaxTokens = 8192;
     /**
-     * The four the API's image block reads. An exact set rather than an `image/*` prefix, because by the time an
-     * attachment reaches here `accepts.image` has already carried it past `AgentService.readable`: a phone's
-     * `image/heic` — the iPhone camera default, so the likeliest non-canonical image an app sees — arrives as bytes,
-     * becomes a block the API refuses, and takes the **whole turn** down on a 400 rather than going unread.
-     *
-     * The app cannot gate it either: `AttachReader` answers `null` for "not mine", which falls through to the
-     * built-in reader that base64s any `image/*`, so there is no way for a reader to refuse one. The check belongs
-     * where the block vocabulary is known, which is here.
+     * Exact, not `image/*`: a phone's `image/heic` would become a block the API refuses, taking the whole turn down on a
+     * 400, and no `AttachReader` can refuse an image before it gets here.
      */
     static readonly imageTypes: Set<string>;
-    /** What the API's blocks carry. A model of the family that reads neither takes the `accepts` override. */
+    get limits(): LlmLimits;
     get accepts(): LlmAccepts;
     chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null>;
-    static refusal(response: Response): Promise<Error>;
+    static refusal(host: string, response: Response): Promise<Error>;
     /** The API answers a refusal as `{ error: { type, message } }`, and the sentence is the half worth printing. */
     static reasonOf(response: Response): Promise<string>;
     static requestBody(model: string, request: LlmTurnRequest, { accepts, stream, maxTokens }?: {
@@ -99,31 +86,16 @@ export declare class AnthropicLlm extends AnthropicLlm_base implements LlmAdapto
     };
     /** Context rides below the instructions framed as data — screen state must never read as directives. */
     static systemPrompt({ instructions, context }: LlmTurnRequest): string;
-    /**
-     * The API takes strictly alternating turns, so two wire messages that map to one role are merged rather than
-     * sent as two — which is not an edge case here: a turn's tool results and the next thing the user says are both
-     * user turns, and so is the tool-result turn that follows a batch of calls.
-     */
+    /** The API takes strictly alternating roles, so tool results and the user's next ask merge into one user turn. */
     static providerMessages(messages: AgentWireMessage[], accepts?: LlmAccepts): AnthropicMessage[];
     static providerMessage(message: AgentWireMessage, accepts?: LlmAccepts): AnthropicMessage;
     static userContent(message: AgentWireMessage, accepts?: LlmAccepts): AnthropicBlock[];
-    /** The block's `media_type` is the essence, not whatever parameters the browser attached to it. */
     static typed(source: AnthropicSource, mimeType: string): AnthropicSource;
-    /**
-     * Bytes beat an address when a host sent both: it already paid for them on the way in, and the address it also
-     * sent is the one it renders — which the default storage backend serves on a path only the app can resolve.
-     * Picking that costs a confident answer about a picture nothing fetched; picking the bytes costs one hop that
-     * already carries them. A URL the provider really can reach travels alone.
-     */
+    /** Bytes beat a URL: the default storage serves a path only the app can resolve, so the provider cannot fetch it. */
     static sourceOf(attachment: AgentWireAttachment): AnthropicSource | null;
     static turnAnswer(answer: AnthropicAnswer): LlmTurnAnswer;
-    /** The ceiling wins over the calls that did arrive — see `OpenaiDialect.stopOf` for why. */
+    static usageOf(usage: AnthropicUsage): LlmUsage;
     static stopOf(reason: string | null | undefined, calls: number): LlmTurnAnswer["stop"];
-    /**
-     * The API streams named SSE events rather than one chunk shape. A tool call opens as `content_block_start`
-     * carrying its id and name and then arrives as `input_json_delta` fragments of a JSON string, so it is assembled
-     * by block 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>;
     /** A tool called with no arguments streams no fragment at all, so an empty string is an empty object. */
     static parsedArgs(raw: string): Record<string, unknown>;

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

@@ -1,40 +1,70 @@
-import type { BaseEnv, Dayjs, SshOptions } from "akanjs/base";
+import { type BaseEnv, type Dayjs } from "akanjs/base";
 import type { Redis } from "ioredis";
 export interface CacheSetOptions {
     expireAt?: Dayjs;
 }
+/** An object, an array or a boolean is stored as JSON and read back parsed, so a class instance returns as its JSON. */
+export type CacheValue = string | number | boolean | Uint8Array | object;
 export interface CacheAdaptor {
-    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>;
+    /** Reads and removes in one step: of two callers racing for a one-time value, one gets it and the other nothing. */
+    getDel<T extends CacheValue = CacheValue>(topic: string, key: string): Promise<T | undefined>;
+    /** Writes only where nothing live is stored, and answers whether this call wrote. */
+    setIfAbsent(topic: string, key: string, value: CacheValue, option?: CacheSetOptions): Promise<boolean>;
+    /** Adds `by` and answers the sum. A counter this call creates takes `expireAt`; a live one keeps its own. */
+    incr(topic: string, key: string, by?: number, option?: CacheSetOptions): Promise<number>;
+    /** Takes the lease for `owner` when nobody else holds a live one; the holder calling again renews it. */
+    acquireLease(topic: string, key: string, owner: string, ttlMs: number): Promise<boolean>;
+    /** Extends a lease `owner` still holds, and answers false once it lapsed or passed to someone else. */
+    renewLease(topic: string, key: string, owner: string, ttlMs: number): Promise<boolean>;
+    releaseLease(topic: string, key: string, owner: string): Promise<void>;
     getClient?(): Redis;
-    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>;
+    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>;
 }
 interface RedisEnv extends BaseEnv {
     redis?: {
         username?: string;
         password?: string;
-        sshOptions?: SshOptions;
     };
 }
 declare const RedisCache_base: import("..").AdaptorCls<{}, {
     redis: import("..").InjectInfo<"env", Redis, RedisEnv, never>;
+    keyPrefix: import("..").InjectInfo<"env", string, {
+        [key: string]: any;
+    }, never>;
 }>;
 export declare class RedisCache extends RedisCache_base implements CacheAdaptor {
-    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>;
+    #private;
+    /** `REDIS_URI` (`rediss://` for TLS) is required outside local: a guessed host is a split brain that boots. */
+    static resolveUrl(): string;
+    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>;
     getClient(): Redis;
     onDestroy(): Promise<void>;
 }

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

@@ -1,4 +1,4 @@
-import { type PromiseOrObject } from "akanjs/base";
+import type { PromiseOrObject } from "akanjs/base";
 import type { ConstantModel } from "akanjs/constant";
 import type { DatabaseModel, SchemaOf } from "akanjs/document";
 import { SearchIndex } from "./searchIndex.d.ts";
@@ -6,23 +6,16 @@ import { BunSqliteClient } from "./sql/driver/bunSqlite.d.ts";
 import { LibsqlAkanClient } from "./sql/driver/libsql.d.ts";
 import { PostgresAkanClient } from "./sql/driver/postgres.d.ts";
 import { SqlDocumentStore } from "./sql/SqlDocumentStore.d.ts";
-import type { DatabaseAdaptor, SqliteEnv } from "./sql/types.d.ts";
+import { type ConcurrentIndexBuild, type DatabaseAdaptor, type InsightSession, type SearchConfig, type SqliteEnv } from "./sql/types.d.ts";
 export { PostgresDialect } from "./sql/dialect/postgres.d.ts";
 export { SqliteDialect } from "./sql/dialect/sqlite.d.ts";
 export { SqlDocumentStore } from "./sql/SqlDocumentStore.d.ts";
-/**
- * The three SQL databases an app can mount, and nothing else. The layer underneath them — drivers, dialects,
- * the query and update compilers, and the document store they all share — lives in .
- */
-export type { AkanSqlClient, AkanSqlStatement, DatabaseAdaptor, DatabaseConfig, DocumentDatabaseOwner, DocumentStore, LibsqlDatabaseConfig, PostgresDatabaseConfig, SearchConfig, SqliteDatabaseConfig, SqlResultRows, } from "./sql/types.d.ts";
+export type { AkanSqlClient, AkanSqlStatement, DatabaseAdaptor, DatabaseConfig, DocumentDatabaseOwner, DocumentStore, InsightSession, LibsqlDatabaseConfig, PostgresDatabaseConfig, SearchConfig, SqlDialect, SqliteDatabaseConfig, SqlResultRows, } from "./sql/types.d.ts";
 declare const SqliteDatabase_base: import("..").AdaptorCls<{}, {
     scheduler: import("..").InjectInfo<"plug", import("./schedule.adaptor").ScheduleAdaptor, never, never>;
     config: import("..").InjectInfo<"env", {
         filePath: string;
-        search: {
-            enabled: boolean;
-            tokenizer: string;
-        };
+        search: Required<SearchConfig>;
         journalMode: "WAL" | "DELETE" | "TRUNCATE" | "PERSIST" | "MEMORY" | "OFF";
         busyTimeoutMs: number;
         synchronous: "OFF" | "NORMAL" | "FULL" | "EXTRA";
@@ -37,6 +30,8 @@ export declare class SqliteDatabase extends SqliteDatabase_base implements Datab
     onDestroy(): Promise<void>;
     getConnection(): BunSqliteClient;
     getSearchIndex(): SearchIndex;
+    openInsight(): Promise<InsightSession>;
+    stores(): SqlDocumentStore[];
     getStore(constant: ConstantModel, database: DatabaseModel, schema: SchemaOf): SqlDocumentStore;
     getMeta(key: string): string | undefined;
     setMeta(key: string, value: string): Promise<void>;
@@ -50,10 +45,7 @@ declare const LibsqlDatabase_base: import("..").AdaptorCls<{}, {
     config: import("..").InjectInfo<"env", {
         url: string;
         authToken: string | undefined;
-        search: {
-            enabled: boolean;
-            tokenizer: string;
-        };
+        search: Required<SearchConfig>;
     }, SqliteEnv, never>;
 }>;
 export declare class LibsqlDatabase extends LibsqlDatabase_base implements DatabaseAdaptor {
@@ -62,6 +54,8 @@ export declare class LibsqlDatabase extends LibsqlDatabase_base implements Datab
     onDestroy(): Promise<void>;
     getConnection(): LibsqlAkanClient;
     getSearchIndex(): SearchIndex;
+    openInsight(): Promise<InsightSession>;
+    stores(): SqlDocumentStore[];
     getStore(constant: ConstantModel, database: DatabaseModel, schema: SchemaOf): SqlDocumentStore;
     getMeta(key: string): Promise<string | undefined>;
     setMeta(key: string, value: string): Promise<void>;
@@ -69,6 +63,7 @@ export declare class LibsqlDatabase extends LibsqlDatabase_base implements Datab
     afterCommit(fn: () => PromiseOrObject<void>): Promise<void>;
 }
 declare const PostgresDatabase_base: import("..").AdaptorCls<{}, {
+    scheduler: import("..").InjectInfo<"plug", import("./schedule.adaptor").ScheduleAdaptor, never, never>;
     config: import("..").InjectInfo<"env", {
         url: string | undefined;
         host: string;
@@ -76,17 +71,26 @@ declare const PostgresDatabase_base: import("..").AdaptorCls<{}, {
         database: string;
         user: string;
         password: string;
+        insightUrl: string | undefined;
+        search: Required<SearchConfig>;
     }, SqliteEnv, never>;
 }>;
 export declare class PostgresDatabase extends PostgresDatabase_base implements DatabaseAdaptor {
     #private;
     onInit(): Promise<void>;
+    grantInsight(table: string): Promise<void>;
+    openInsight(): Promise<InsightSession>;
     onDestroy(): Promise<void>;
     getConnection(): PostgresAkanClient;
-    getSearchIndex(): null;
+    getSearchIndex(): SearchIndex;
+    stores(): SqlDocumentStore[];
     getStore(constant: ConstantModel, database: DatabaseModel, schema: SchemaOf): SqlDocumentStore;
     getMeta(key: string): Promise<string | undefined>;
     setMeta(key: string, value: string): Promise<void>;
     transaction<T>(fn: () => PromiseOrObject<T>): Promise<T>;
     afterCommit(fn: () => PromiseOrObject<void>): Promise<void>;
+    lockSchema<T>(fn: () => Promise<T>): Promise<T>;
+    hasTable(table: string): Promise<boolean>;
+    hasValidIndex(name: string): Promise<boolean>;
+    buildIndexConcurrently({ name, next, create, replace }: ConcurrentIndexBuild): Promise<void>;
 }

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,14 +18,12 @@ 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;
 }
 /**
- * Data the caller pointed at while writing one message, rather than a file they attached. `value` is a snapshot
- * taken when the message was sent and already masked by the host — the server has no model class to mask it with,
- * so what the browser staged is what leaves. `refName`/`refId`/`path` are the way back to the current value, which
- * is why they travel even when the value itself does not.
+ * `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;
@@ -40,10 +34,7 @@ export interface AgentWireReference {
     /** Read by the model in place of a value there is none of — clipped, unreadable, or gone from a restored chat. */
     note?: 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.
- */
+/** `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;
@@ -52,10 +43,7 @@ export interface AgentWireMessage {
     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 {
@@ -77,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;
+}