@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/adapters/scoped/updateGuard.js

@@ -0,0 +1,40 @@
+import { Refusal } from '../adapter.js';
+import { comparableType, isJsonType } from '../../shared/schema.js';
+/** Appended to a complete primary-key WHERE, with values bound after its parameters. */
+export function buildUpdateGuard(request, types, style, dialect, startIndex) {
+    if (request.expected === undefined)
+        return { text: '', params: [] };
+    const expected = request.expected;
+    if (!expected || typeof expected !== 'object' || Array.isArray(expected))
+        throw new Refusal('Expected values must be an object containing exactly the fields being updated.');
+    /* A JSON column is written whole and compares on no engine, so its
+       original value may be left out (a command's update leaves it out). */
+    const columns = Object.keys(request.values).filter((column) => Object.hasOwn(expected, column) || !isJsonType(types[column] ?? ''));
+    if (Object.keys(expected).length !== columns.length || !columns.every((column) => Object.hasOwn(expected, column))) {
+        throw new Refusal('Expected values must contain exactly the fields being updated.');
+    }
+    const params = [];
+    const checks = columns.map((column) => {
+        const value = expected[column];
+        const quoted = style.quote(column);
+        if (value === null)
+            return `${quoted} IS NULL`;
+        if (typeof value !== 'string' && typeof value !== 'boolean' && !(typeof value === 'number' && Number.isFinite(value))) {
+            throw new Refusal(`The original value of "${column}" must be a scalar or NULL.`);
+        }
+        const type = types[column] ?? '';
+        if (!comparableType(type)) {
+            throw new Refusal(`Protected editing of "${column}" (${type}) is not supported. Its original value cannot be compared safely here.`);
+        }
+        const placeholder = style.placeholder(startIndex + params.length);
+        // Preserve decimal/integer strings: Number() could round the original value.
+        params.push(dialect === 'sqlite' && typeof value === 'boolean' ? Number(value) : value);
+        // SQLite can store text even without a declared type; its collation still applies.
+        if (dialect === 'sqlite')
+            return `${quoted} COLLATE BINARY = ${placeholder}`;
+        if (/char|text|clob|citext/i.test(type))
+            return `${quoted}::text COLLATE "C" = ${placeholder}`;
+        return `${quoted} = ${placeholder}`;
+    });
+    return checks.length ? { text: ` AND (${checks.join(' AND ')})`, params } : { text: '', params: [] };
+}

package/dist/adapters/serverSettings.d.ts

@@ -0,0 +1,45 @@
+import type { PoolerMode } from './poolMetrics.js';
+export type WriteOrder = 'serial' | 'keyed';
+/** `--trust-proxy-hops` and `--trust-proxy-cloudflare`: how a forwarded client address is found (trust.ts). */
+export interface ClientAddressPolicy {
+    /** This many proxies append to X-Forwarded-For, the socket peer being the first. */
+    readonly hops?: number;
+    /** The server is reachable only through Cloudflare, which sets CF-Connecting-IP. */
+    readonly cloudflare?: boolean;
+}
+export interface ServerSettings {
+    readonly clientAddress: ClientAddressPolicy;
+    /**
+     * The address the server is published at (MISTRI_PUBLIC_URL, or a mounting
+     * host's) is https: a TLS front end stands before every request, so a
+     * request counts as https whatever its own socket says (trust.ts
+     * `arrivedOverHttps`). Cloudflare, Cloud Run and most platforms end TLS
+     * and forward plain http from a peer nobody can name in `--trust-proxy`.
+     */
+    readonly httpsFront?: boolean;
+    /** `--read-pool`: a PostgreSQL reader pool's size; unset, it follows the write order (postgresPool.ts). */
+    readonly readers?: number;
+    /** `--pooler`. */
+    readonly pooler: PoolerMode;
+    /** `--write-pool`; unset, the balanced size (writeLanes.ts). */
+    readonly writers?: number;
+    /** `--lock-timeout`; unset, the default. */
+    readonly lockTimeoutMs?: number;
+    /**
+     * `keyed` where the server serves Apps, `serial` for the database browser
+     * (writeLanes.ts). Settled once the config is read, before a connection
+     * opens, so it is the one field startup writes after the scope is entered.
+     */
+    writeOrder: WriteOrder;
+}
+/** What a server that names nothing gets. */
+export declare function defaultServerSettings(): ServerSettings;
+/** The settings of the server this work belongs to: its scope's, or the process's. */
+export declare function serverSettings(): ServerSettings;
+/** Run `work`, and everything it starts, as the server `settings` describe. */
+export declare function withServerSettings<T>(settings: ServerSettings, work: () => T): T;
+/**
+ * Change the process's settings — what is read outside any scope: the
+ * command line's one server, a test. Fields it leaves out keep their value.
+ */
+export declare function configureServerSettings(change: Partial<ServerSettings>): void;

package/dist/adapters/serverSettings.js

@@ -0,0 +1,46 @@
+/**
+ * What one server was started with that is read far below its requests: the
+ * client-address rule a rate limit keys by (http/trust.ts `forwardedClient`),
+ * and the pool sizes, pooler mode, lock wait and write order every adapter it
+ * opens takes (postgresPool.ts, writeLanes.ts).
+ *
+ * These were process globals, set once at startup, which was right while a
+ * process was one server. `createHandler` (embed/handler.ts) puts
+ * several in one host process, and each started by overwriting the globals:
+ * the last handler's proxy trust decided whose X-Forwarded-For every
+ * handler's limits believed. So a handler's settings are a value it carries,
+ * and everything it runs — its startup, every request it is given, its
+ * close — runs inside `withServerSettings`, where `serverSettings()` reads
+ * them. The command line is one server per process and installs its own as
+ * the process's (`configureServerSettings`), which is what is read outside
+ * any scope.
+ *
+ * A scope rather than an argument: the readers are a dozen limiters and the
+ * constructor of every pool, opened by the registry, a tenant source, the job
+ * host and a startup check alike. An argument would have to reach each, and
+ * one that missed would quietly return to the default — the failure this
+ * exists to end. A scope reaches all of them by construction, timers and
+ * all, since an async context follows its callbacks.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** What a server that names nothing gets. */
+export function defaultServerSettings() {
+    return { clientAddress: {}, pooler: 'session', writeOrder: 'serial' };
+}
+let processSettings = defaultServerSettings();
+const scope = new AsyncLocalStorage();
+/** The settings of the server this work belongs to: its scope's, or the process's. */
+export function serverSettings() {
+    return scope.getStore() ?? processSettings;
+}
+/** Run `work`, and everything it starts, as the server `settings` describe. */
+export function withServerSettings(settings, work) {
+    return scope.run(settings, work);
+}
+/**
+ * Change the process's settings — what is read outside any scope: the
+ * command line's one server, a test. Fields it leaves out keep their value.
+ */
+export function configureServerSettings(change) {
+    processSettings = { ...processSettings, ...change };
+}

package/dist/adapters/sqlite.d.ts

@@ -0,0 +1,262 @@
+import { DatabaseSync, type SQLInputValue } from 'node:sqlite';
+import { type Adapter, type ScopedReads, type Filter, type QueryRequest, type QueryResult, type SqlRequest, type SqlResult, type DeleteRequest, type DeleteResult, type UpdateRequest, type UpdateResult, type ViewResult, type BreakdownResult, TransactionOperations, type WriteTransaction, type InsertRequest, type InsertResult, type ExplainRequest, type ExplainResult, type ProfileLimits, type ProfileResult, type CountItem } from './adapter.js';
+import { type SqliteScopeCatalog } from './scoped/sqliteScopeCatalog.js';
+import { type RowScope } from '../shared/rowScope.js';
+import { type ViewDef } from '../shared/view.js';
+import { type BreakdownDef } from '../shared/breakdown.js';
+import { type DatabaseSchema } from '../shared/schema.js';
+/** Identity-only native provenance; no caller can register a lookalike. */
+export declare const isSqliteVerifiedCommandSource: (value: unknown) => value is SqliteAdapter;
+export declare class SqliteAdapter implements Adapter {
+    private file;
+    private label;
+    readonly dialect: 'sqlite';
+    private db;
+    /** Opened lazily, only when an edit is actually applied. */
+    private writeDb;
+    private closed;
+    private writes;
+    private readonly writeIdentity;
+    private readonly introspectedVersions;
+    private readonly catalogCache;
+    /** The epoch the open write transaction read, on the handle it read it on. */
+    private txEpoch?;
+    constructor(file: string, label?: string);
+    private queueWrite;
+    private assertWriteIdentity;
+    private schemaVersion;
+    /** Opt-in physical-schema lifetime fence. No logical clone or another
+     * adapter's schema is accepted. Ordinary DDL invalidates it synchronously;
+     * malicious manual schema_version resets are outside this contract. */
+    captureSchemaLifetime(schema: DatabaseSchema): () => void;
+    introspect(): Promise<DatabaseSchema>;
+    private indexesOf;
+    /**
+     * The columns a unique index makes unique alone. `PRAGMA index_list`
+     * reports UNIQUE constraints as the indexes SQLite made for them, so one
+     * reading covers both; a partial index proves nothing about the rows it
+     * leaves out, and an expression column has no name.
+     */
+    private uniqueColumns;
+    /** The column pairs a unique index of exactly two named columns keeps
+     * unique together, read as uniqueColumns reads one alone. */
+    private uniquePairs;
+    /**
+     * The columns an ORDER BY can lean on.
+     *
+     * `PRAGMA index_list` reports every index including the implicit ones
+     * SQLite creates for UNIQUE and for a non-integer primary key; `index_info`
+     * gives their columns in order and only the first of each is useful for
+     * sorting.
+     *
+     * `INTEGER PRIMARY KEY` is special and has no index at all — it *is* the
+     * rowid, so ordering by it is free — which is exactly the case a naive
+     * index scan would report as unindexed and then refuse to sort by.
+     */
+    private leadingIndexColumns;
+    query(request: QueryRequest): Promise<QueryResult>;
+    scopeReads(input: RowScope): Promise<ScopedReads>;
+    private queryOn;
+    /**
+     * Run a compiled view.
+     *
+     * Everything hard happened in `compileView`: paths resolved against the
+     * catalog, joins planned with collision-free aliases, values reduced to
+     * bound parameters. What is left here is picking the dialect's style and
+     * handing the statement to the driver — which is the point. An adapter that
+     * built its own joins would be an adapter that could get LEFT wrong on its
+     * own.
+     */
+    runView(view: ViewDef, offset?: number): Promise<ViewResult>;
+    runBreakdown(breakdown: BreakdownDef, offset?: number): Promise<BreakdownResult>;
+    countBreakdown(breakdown: BreakdownDef, limit?: number): Promise<number>;
+    countView(view: ViewDef, limit?: number): Promise<number>;
+    /**
+     * EXPLAIN QUERY PLAN, indented the way the tree nests.
+     *
+     * Prepared and read, never executed: the rows come from the EXPLAIN
+     * statement itself, so even a write handed here is only ever planned — on
+     * the read-only handle, at that.
+     */
+    explainSql(request: ExplainRequest): Promise<ExplainResult>;
+    /**
+     * SQLite keeps no column statistics worth reading — sqlite_stat1 knows
+     * index selectivity, not null shares — so this looks: one aggregate pass
+     * for counts and edges, then one small GROUP BY per column that provably
+     * repeats. `source` tells the caller what the look cost.
+     *
+     * Above `scanAtMost` rows it stops scanning and samples, because
+     * node:sqlite is synchronous and a full pass over a ten-million-row table
+     * holds the whole process for seconds. Every k-th rowid rather than the
+     * first N: insertion order is not a sample, it is a history, and a min
+     * taken from the first month of data would be presented as the table's.
+     * A view — or a WITHOUT ROWID table, which refuses the arithmetic — falls
+     * back to the first N with the same honest label, because running a view
+     * twice to randomise it would cost what sampling exists to avoid.
+     */
+    profile(table: string, limits?: ProfileLimits): Promise<ProfileResult>;
+    /**
+     * After each statement a call runs: a turn of the event loop — a cancel
+     * can only be read when there is one, and node:sqlite gives none while a
+     * statement runs — then a stop if the call was cancelled, before its next
+     * statement starts. After, not before, so a read takes its arguments as it
+     * is called. A read nobody can cancel does not pay for it.
+     */
+    private turn;
+    /** Introspection is cheap here but not free; the view path re-uses it. */
+    private cachedSchema;
+    private schema;
+    count(table: string, filter?: Filter, limit?: number): Promise<number>;
+    countEach(items: readonly CountItem[], limit?: number): Promise<number[]>;
+    private countOn;
+    /**
+     * One compiled read's rows, BigInts and all. A read that could hold the
+     * server's one thread — a count, a filter or a sort over a large table —
+     * runs in the statement process instead (sqliteCostlyReads.ts); one on the
+     * write handle, inside a transaction, stays where its transaction is.
+     */
+    private readRows;
+    /**
+     * SQLite stores the original statement text, so this is the real thing —
+     * whitespace, comments, check constraints and all — not a reconstruction.
+     * Indexes are appended because they are separate statements in
+     * `sqlite_master` and are usually the first thing you want after the shape.
+     */
+    ddl(table: string): Promise<string | undefined>;
+    /**
+     * The write path, on its own handle.
+     *
+     * `this.db` is opened read-only and stays that way for the life of the
+     * process, so browsing can never write no matter what the UI believes. A
+     * second handle is opened the first time an edit is actually applied.
+     */
+    update(request: UpdateRequest): Promise<UpdateResult>;
+    private updateNow;
+    /**
+     * Add one row.
+     *
+     * The guards are `update`'s where they apply — real columns, coerced
+     * values, a NOT NULL that cannot be handed null — but the key rules
+     * invert: a primary key may be supplied (currency.code is one somebody
+     * types) or left for the database to assign. What is deliberately *not*
+     * pre-checked is completeness: a missing NOT NULL column with no default
+     * is the database's refusal to make, and its message names the column
+     * better than a paraphrase would.
+     *
+     * `RETURNING *` rather than last_insert_rowid plus a re-read: one
+     * statement returns the row as stored — defaults filled, the assigned key
+     * included — with no window for another write to land in between.
+     */
+    insert(request: InsertRequest): Promise<InsertResult>;
+    private insertNow;
+    /**
+     * Run a statement the user wrote.
+     *
+     * The read handle is opened `readOnly: true` at the file level, which SQLite
+     * enforces in the engine — there is no session setting for a statement to
+     * reset, so unlike the other two adapters no transaction wrapper is needed
+     * to make the guarantee real.
+     *
+     * What SQLite does not have is a statement timeout, and `node:sqlite` is
+     * synchronous with no interrupt, so a pathological statement on this handle
+     * blocks the whole process rather than one request. The LIMIT wrap covers
+     * the ordinary case — a streaming SELECT stops once it has enough rows — but
+     * not an aggregate over a cross join, which has to finish before it returns
+     * anything. So a read whose caller can stop it — one run inside
+     * `withCancellation`, as every MCP tool call is — runs in a process of its
+     * own instead, which its cap or a cancel kills (sqliteStatementProcess.ts).
+     * The browser's SQL editor runs its reads that way too (dataWriteRoutes.ts);
+     * only an in-memory database, which has no second handle, and a caller with
+     * no signal keep the in-process handle and its limit.
+     */
+    runSql(request: SqlRequest): Promise<SqlResult>;
+    private runSqlNow;
+    /**
+     * Delete one row.
+     *
+     * The guards are `update`'s, for the same reason they are `update`'s: the
+     * danger in an editor is never injection, it is a statement whose WHERE is
+     * broader than the author believed. A delete has the sharper version of that
+     * problem, so nothing here is relaxed.
+     *
+     * Foreign keys are the database's business. `node:sqlite` enables
+     * `foreign_keys` by default — checked, not assumed — so a RESTRICT fires and
+     * a CASCADE cascades exactly as the schema says, and the error the user sees
+     * is SQLite's own.
+     */
+    remove(request: DeleteRequest): Promise<DeleteResult>;
+    private recordsHistory;
+    /**
+     * A store's layout attested once per schema epoch rather than on every
+     * read: its three catalog reads were two of every room's statements in an
+     * App that keeps notices. The epoch — the schema versions, and the store's
+     * meta row, a data fact — is one statement read first; the layout is
+     * described again whenever it has moved.
+     */
+    private attestedStore;
+    /** A write capture's reads on a transaction's own handle (writeCapture.ts). */
+    private captureSource;
+    private lockRecordNow;
+    private removeNow;
+    private writeHandle;
+    /**
+     * Several writes as one, or none of them.
+     *
+     * `BEGIN IMMEDIATE` serializes writers across processes, not just this queue.
+     * Reads and mutation preflights inside the callback share its write handle.
+     * Ordinary browsing remains on the separate read-only handle.
+     *
+     * `node:sqlite` is synchronous, so nothing can interleave *within* one
+     * statement; the queue is what stops another request's write interleaving
+     * *between* two of these.
+     */
+    transaction<T>(run: (tx: WriteTransaction) => Promise<T>): Promise<T>;
+    /**
+     * Records and a durable journal in one transaction, the journal lent by
+     * the App framework (storeHost.ts TransactionJournal): the command journal,
+     * or a public placement's. Lent through the store host, never on the
+     * class, so the database browser has no journal path at all. A verified
+     * ordinary transaction's check is trusted host code, never a
+     * handler/request: it runs after BEGIN and journal attestation and after
+     * the operations drain, before COMMIT, and infers no tenant namespace, row
+     * scope or bearer authority.
+     */
+    private journalTransaction;
+    scopeTransaction<T>(input: RowScope, run: (tx: WriteTransaction, catalog: DatabaseSchema) => Promise<T>): Promise<T>;
+    /** Private source-owner boundary, deliberately absent from Adapter. The
+     * verifier is trusted host code, never a business callback or wire value.
+     * It must be synchronous and may not retain the raw handle. */
+    scopeVerifiedTransaction<T>(input: RowScope, verify: (db: DatabaseSync, catalog: SqliteScopeCatalog) => void, run: (tx: WriteTransaction, catalog: DatabaseSchema) => Promise<T>): Promise<T>;
+    /** Internal runtime-owner composition, deliberately absent from Adapter.
+     * Only trusted runtime code may create bounded maintenance facades here; raw
+     * handles must never reach business handlers, policies or request callbacks.
+     * Runtime edits share the ordinary writer queue, drain and outcome handling. */
+    runtimeMaintenanceTransaction<T>(verify: (db: DatabaseSync) => void, run: (db: DatabaseSync, operations: TransactionOperations, assertCurrent: () => void) => Promise<T>): Promise<T>;
+    private transact;
+    close(): Promise<void>;
+    /**
+     * Table names are the one identifier that cannot be a bound parameter, so
+     * they are checked against the catalog rather than escaped and hoped for.
+     * An unknown name is rejected before it reaches a statement.
+     */
+    /**
+     * The same check for a read on the browsing handle, answered from the
+     * catalog read on connect when it names the table: a name found there is
+     * one the catalog gave, so the probe would only say so again, once per
+     * statement. A name it does not hold — a table made since — still gets the
+     * live probe, and so does every write (assertTable).
+     */
+    private readTable;
+    private assertTable;
+    /** A table's columns, as a write reads them: from the catalog, or inside a
+     * write transaction from what was read under the epoch it holds. */
+    private tableInfo;
+    /** Whether a relation is a view, as a write reads it: kept under the epoch, as its columns are. */
+    private isView;
+    /** The epoch the open write transaction holds, when `db` is its handle and it is still open. */
+    private epochOf;
+}
+export declare function sqliteParams(params: readonly unknown[]): SQLInputValue[];
+/** As toJsonSafe, but a blob stays its bytes: a file download asked for them (`QueryRequest.binary`). */
+export declare function withBytes(row: Record<string, unknown>): Record<string, unknown>;
+export declare function toJsonSafe(row: Record<string, unknown>): Record<string, unknown>;