attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/database/sql/schema.js

@@ -0,0 +1,416 @@
+/**
+ * DDL for the SQLite store. Migrations live in the store, not here.
+ */
+export const MetaSchema = `
+CREATE TABLE IF NOT EXISTS meta (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+);
+`;
+export const Schema = `
+CREATE TABLE IF NOT EXISTS objects (
+    seq INTEGER PRIMARY KEY AUTOINCREMENT,
+    kind TEXT NOT NULL,
+    id TEXT NOT NULL,
+    body TEXT NOT NULL,
+    hash TEXT NOT NULL,
+    prev TEXT NOT NULL,
+    at TEXT NOT NULL,
+    UNIQUE(kind, id)
+);
+CREATE INDEX IF NOT EXISTS objects_kind_seq ON objects(kind, seq);
+
+CREATE TABLE IF NOT EXISTS processes (
+    pid INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL UNIQUE,
+    name TEXT NOT NULL,
+    role TEXT,
+    state TEXT NOT NULL CHECK(state IN ('created','running','idle','suspended','terminated')),
+    priority INTEGER NOT NULL DEFAULT 0,
+    budget TEXT NOT NULL,
+    used TEXT NOT NULL,
+    parent_pid INTEGER REFERENCES processes(pid),
+    created_at TEXT NOT NULL,
+    started_at TEXT,
+    terminated_at TEXT,
+    exit_code TEXT,
+    exit_note TEXT,
+    version INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS processes_state ON processes(state, priority DESC);
+
+CREATE TABLE IF NOT EXISTS threads (
+    tid INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL UNIQUE,
+    pid INTEGER NOT NULL REFERENCES processes(pid) ON DELETE CASCADE,
+    goal TEXT NOT NULL,
+    statement TEXT NOT NULL,
+    success TEXT NOT NULL,
+    state TEXT NOT NULL CHECK(state IN ('ready','running','blocked','done','failed','abandoned')),
+    priority INTEGER NOT NULL DEFAULT 0,
+    quantum_ms INTEGER NOT NULL DEFAULT 1000,
+    slice_used_ms INTEGER NOT NULL DEFAULT 0,
+    budget TEXT NOT NULL,
+    used TEXT NOT NULL,
+    blocked_on TEXT,
+    wake_at TEXT,
+    created_at TEXT NOT NULL,
+    finished_at TEXT,
+    exit_note TEXT,
+    owner_worker TEXT,
+    lease INTEGER NOT NULL DEFAULT 0,
+    version INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS threads_ready ON threads(state, priority DESC, tid);
+CREATE INDEX IF NOT EXISTS threads_pid ON threads(pid, state);
+CREATE UNIQUE INDEX IF NOT EXISTS threads_one_running_per_process ON threads(pid) WHERE state = 'running';
+
+CREATE TABLE IF NOT EXISTS steps (
+    step_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    pid INTEGER NOT NULL,
+    tid INTEGER NOT NULL,
+    at TEXT NOT NULL,
+    outcome TEXT NOT NULL,
+    usage TEXT NOT NULL,
+    note TEXT,
+    receipt_id TEXT
+);
+CREATE INDEX IF NOT EXISTS steps_pid ON steps(pid, step_id);
+
+/* Address space: which immutable objects a process can see. Inherited rows are
+   copy-on-write views of the parent's warrant; writing creates a new object. */
+CREATE TABLE IF NOT EXISTS process_objects (
+    pid INTEGER NOT NULL REFERENCES processes(pid) ON DELETE CASCADE,
+    seq INTEGER NOT NULL REFERENCES objects(seq) ON DELETE CASCADE,
+    role TEXT NOT NULL CHECK(role IN ('own','inherited','mapped','joined')),
+    mode TEXT NOT NULL CHECK(mode IN ('read','write')),
+    attached_at TEXT NOT NULL,
+    PRIMARY KEY (pid, seq)
+);
+CREATE INDEX IF NOT EXISTS process_objects_pid ON process_objects(pid, seq);
+
+/* Capability table: a handle is an unforgeable row over ANY resource, carrying
+   rights, scope and expiry. Ownership is implicit for the owner process; every
+   other subject needs a row here. Grants create a child row in another subject,
+   and revoke walks the tree, so a revoked parent invalidates every grant below
+   it. This is the only isolation mechanism a logical process has. */
+CREATE TABLE IF NOT EXISTS handles (
+    hid INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL UNIQUE,
+    subject_kind TEXT NOT NULL CHECK(subject_kind IN ('host','process','thread')),
+    subject_id TEXT NOT NULL,
+    subject_pid INTEGER,
+    resource_kind TEXT NOT NULL CHECK(resource_kind IN ('object','process','thread','mailbox','budget')),
+    resource_id TEXT NOT NULL,
+    owner_pid INTEGER,
+    rights TEXT NOT NULL,
+    scope TEXT NOT NULL CHECK(scope IN ('process','thread','shared')),
+    parent_hid INTEGER REFERENCES handles(hid),
+    refcount INTEGER NOT NULL DEFAULT 1,
+    expires_at TEXT,
+    revoked_at TEXT,
+    granted_by TEXT,
+    created_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS handles_subject ON handles(subject_kind, subject_id, resource_kind, resource_id);
+CREATE INDEX IF NOT EXISTS handles_parent ON handles(parent_hid);
+
+/* Inter-process messages: bounded mailbox per recipient, delivered exactly once
+   by delivered_at; the delivery writes a receipt object so the exchange is in
+   the evidence chain. Intra-process traffic uses the blackboard, not this table. */
+CREATE TABLE IF NOT EXISTS messages (
+    msg_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL UNIQUE,
+    from_pid INTEGER NOT NULL REFERENCES processes(pid),
+    from_tid INTEGER NOT NULL,
+    to_pid INTEGER NOT NULL REFERENCES processes(pid),
+    to_tid INTEGER,
+    kind TEXT NOT NULL CHECK(kind IN ('request','response','event','signal')),
+    body TEXT NOT NULL,
+    correlation_id TEXT,
+    at TEXT NOT NULL,
+    delivered_at TEXT,
+    receipt_id TEXT
+);
+CREATE INDEX IF NOT EXISTS messages_inbox ON messages(to_pid, delivered_at, msg_id);
+
+/* Worker registry: every kernel instance that touches the store has an entry
+   and a heartbeat. A thread is owned by exactly one worker (fencing lease), so
+   another worker can recover it only after the owner's lease expires. */
+CREATE TABLE IF NOT EXISTS workers (
+    worker_id TEXT PRIMARY KEY,
+    host TEXT,
+    pid INTEGER,
+    started_at TEXT NOT NULL,
+    heartbeat_at TEXT NOT NULL,
+    expires_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS workers_expiry ON workers(expires_at);
+
+/* Idempotency: external effects and message sends are keyed, so a retry after a
+   crash returns the stored result instead of performing the effect twice. */
+CREATE TABLE IF NOT EXISTS idempotency (
+    key TEXT PRIMARY KEY,
+    result TEXT NOT NULL,
+    created_at TEXT NOT NULL
+);
+
+/* Context window: a per-thread address space. Pages point at immutable objects;
+   the page table is durable so a restart can rebuild the resident set instead
+   of pretending the model still remembers it. */
+CREATE TABLE IF NOT EXISTS windows (
+    tid INTEGER PRIMARY KEY,
+    capacity_tokens INTEGER NOT NULL,
+    used_tokens INTEGER NOT NULL,
+    updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS window_pages (
+    tid INTEGER NOT NULL,
+    page_id TEXT NOT NULL,
+    object_kind TEXT NOT NULL,
+    object_id TEXT NOT NULL,
+    tokens INTEGER NOT NULL,
+    pinned INTEGER NOT NULL,
+    last_used INTEGER NOT NULL,
+    PRIMARY KEY (tid, page_id)
+);
+CREATE INDEX IF NOT EXISTS window_pages_tid ON window_pages(tid, last_used);
+
+/* Cross-worker mutual exclusion for a named resource (file, session, tab).
+   A lease is a capability's sibling: permission says "may", a lock says "now". */
+CREATE TABLE IF NOT EXISTS resource_locks (
+    name TEXT PRIMARY KEY,
+    holder TEXT NOT NULL,
+    fencing INTEGER NOT NULL DEFAULT 0,
+    acquired_at TEXT NOT NULL,
+    expires_at TEXT NOT NULL
+);
+
+/* Registry: concepts and modules are data, not only directories.
+   Each declaration writes an object; the row keeps the latest version and the
+   object seq, so "this module exists" is a checkable claim, not a convention. */
+CREATE TABLE IF NOT EXISTS concepts (
+    cid INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL UNIQUE,
+    label TEXT NOT NULL,
+    definition TEXT NOT NULL,
+    status TEXT NOT NULL CHECK(status IN ('proposed','active','deprecated')),
+    version INTEGER NOT NULL,
+    object_seq INTEGER,
+    digest TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS modules (
+    mid INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL UNIQUE,
+    kind TEXT NOT NULL CHECK(kind IN ('kernel','database','domain','protocol','module','structure','tool','boundary')),
+    entry TEXT NOT NULL,
+    description TEXT NOT NULL,
+    status TEXT NOT NULL CHECK(status IN ('planned','active','deprecated')),
+    version INTEGER NOT NULL,
+    object_seq INTEGER,
+    digest TEXT,
+    content_digest TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS module_concepts (
+    mid INTEGER NOT NULL REFERENCES modules(mid) ON DELETE CASCADE,
+    cid INTEGER NOT NULL REFERENCES concepts(cid) ON DELETE CASCADE,
+    role TEXT NOT NULL CHECK(role IN ('owns','uses','constrains','implements')),
+    PRIMARY KEY (mid, cid, role)
+);
+
+CREATE TABLE IF NOT EXISTS module_dependencies (
+    mid INTEGER NOT NULL REFERENCES modules(mid) ON DELETE CASCADE,
+    depends_on_mid INTEGER NOT NULL REFERENCES modules(mid) ON DELETE CASCADE,
+    reason TEXT,
+    PRIMARY KEY (mid, depends_on_mid)
+);
+
+CREATE TABLE IF NOT EXISTS attestations (
+    aid INTEGER PRIMARY KEY AUTOINCREMENT,
+    subject_kind TEXT NOT NULL CHECK(subject_kind IN ('concept','module')),
+    subject_id TEXT NOT NULL,
+    claim_id TEXT NOT NULL,
+    object_seq INTEGER,
+    at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS attestations_subject ON attestations(subject_kind, subject_id);
+
+/* Person layer: an agent is a person, not a prompt.
+   Self is narrative (versioned), roles are social positions, memory is typed,
+   affect is state, relationships and institutions constitute the social person. */
+CREATE TABLE IF NOT EXISTS person_profiles (
+    pid INTEGER PRIMARY KEY REFERENCES processes(pid) ON DELETE CASCADE,
+    name TEXT NOT NULL,
+    narrative TEXT NOT NULL DEFAULT '',
+    values_json TEXT NOT NULL DEFAULT '[]',
+    constraints_json TEXT NOT NULL DEFAULT '[]',
+    life_chapter TEXT NOT NULL DEFAULT 'starting',
+    updated_at TEXT NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1
+);
+
+CREATE TABLE IF NOT EXISTS self_narratives (
+    snid INTEGER PRIMARY KEY AUTOINCREMENT,
+    pid INTEGER NOT NULL REFERENCES processes(pid) ON DELETE CASCADE,
+    version INTEGER NOT NULL,
+    identity_json TEXT NOT NULL DEFAULT '{}',
+    narrative TEXT NOT NULL,
+    at TEXT NOT NULL,
+    object_seq INTEGER,
+    UNIQUE(pid, version)
+);
+
+CREATE TABLE IF NOT EXISTS roles (
+    rid INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL UNIQUE,
+    label TEXT NOT NULL,
+    obligations_json TEXT NOT NULL DEFAULT '[]',
+    permissions_json TEXT NOT NULL DEFAULT '[]',
+    audiences_json TEXT NOT NULL DEFAULT '[]',
+    scripts_json TEXT NOT NULL DEFAULT '[]',
+    status TEXT NOT NULL CHECK(status IN ('active','retired')) DEFAULT 'active',
+    created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS person_roles (
+    pid INTEGER NOT NULL REFERENCES processes(pid) ON DELETE CASCADE,
+    rid INTEGER NOT NULL REFERENCES roles(rid) ON DELETE CASCADE,
+    salience REAL NOT NULL DEFAULT 0.5,
+    active INTEGER NOT NULL DEFAULT 0,
+    since TEXT NOT NULL,
+    PRIMARY KEY (pid, rid)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS person_roles_one_active ON person_roles(pid) WHERE active = 1;
+
+CREATE TABLE IF NOT EXISTS memories (
+    mem_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL UNIQUE,
+    pid INTEGER NOT NULL REFERENCES processes(pid) ON DELETE CASCADE,
+    role_id TEXT,
+    kind TEXT NOT NULL CHECK(kind IN ('episodic','semantic','procedural','social','affective')),
+    content TEXT NOT NULL,
+    salience REAL NOT NULL DEFAULT 0.5,
+    at TEXT NOT NULL,
+    refs_json TEXT NOT NULL DEFAULT '[]',
+    source TEXT,
+    consolidated INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS memories_pid ON memories(pid, salience DESC, at DESC);
+
+CREATE TABLE IF NOT EXISTS affect_states (
+    pid INTEGER PRIMARY KEY REFERENCES processes(pid) ON DELETE CASCADE,
+    valence REAL NOT NULL DEFAULT 0,
+    arousal REAL NOT NULL DEFAULT 0,
+    stress REAL NOT NULL DEFAULT 0,
+    fatigue REAL NOT NULL DEFAULT 0,
+    mood TEXT NOT NULL DEFAULT 'neutral',
+    updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS relationships (
+    rel_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL UNIQUE,
+    from_pid INTEGER NOT NULL REFERENCES processes(pid) ON DELETE CASCADE,
+    to_pid INTEGER NOT NULL REFERENCES processes(pid) ON DELETE CASCADE,
+    kind TEXT NOT NULL,
+    trust REAL NOT NULL DEFAULT 0.5,
+    attachment REAL NOT NULL DEFAULT 0.5,
+    obligations_json TEXT NOT NULL DEFAULT '[]',
+    since TEXT NOT NULL,
+    last_contact TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS relationships_pair ON relationships(from_pid, to_pid, kind);
+
+CREATE TABLE IF NOT EXISTS institutions (
+    iid INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL UNIQUE,
+    name TEXT NOT NULL,
+    norms_json TEXT NOT NULL DEFAULT '[]'
+);
+
+CREATE TABLE IF NOT EXISTS memberships (
+    pid INTEGER NOT NULL REFERENCES processes(pid) ON DELETE CASCADE,
+    iid INTEGER NOT NULL REFERENCES institutions(iid) ON DELETE CASCADE,
+    role TEXT NOT NULL,
+    status TEXT NOT NULL CHECK(status IN ('active','left')) DEFAULT 'active',
+    since TEXT NOT NULL,
+    PRIMARY KEY (pid, iid)
+);
+
+CREATE TABLE IF NOT EXISTS background_processes (
+    bpid INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL UNIQUE,
+    pid INTEGER NOT NULL REFERENCES processes(pid) ON DELETE CASCADE,
+    kind TEXT NOT NULL CHECK(kind IN ('habit','emotion','monitor','drive')),
+    label TEXT NOT NULL,
+    intensity REAL NOT NULL DEFAULT 0.5,
+    trigger TEXT,
+    script TEXT,
+    status TEXT NOT NULL CHECK(status IN ('active','paused','retired')) DEFAULT 'active',
+    updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS background_pid ON background_processes(pid, status, intensity DESC);
+
+CREATE TABLE IF NOT EXISTS life_events (
+    ev_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL UNIQUE,
+    pid INTEGER NOT NULL REFERENCES processes(pid) ON DELETE CASCADE,
+    kind TEXT NOT NULL,
+    summary TEXT NOT NULL,
+    at TEXT NOT NULL,
+    role_id TEXT,
+    impact REAL NOT NULL DEFAULT 0.5,
+    narrative_version INTEGER
+);
+CREATE INDEX IF NOT EXISTS life_events_pid ON life_events(pid, at DESC);
+
+/* Transactional outbox for runtime receipts/events. Rows are written by the
+   application transaction and dispatched later; this keeps the runtime sink
+   observable without making the domain depend on SQLite. */
+CREATE TABLE IF NOT EXISTS outbox (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    topic TEXT NOT NULL,
+    payload TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    dispatched_at TEXT
+);
+CREATE INDEX IF NOT EXISTS outbox_pending ON outbox(dispatched_at, id);
+
+/* Runtime session snapshots (attention state + priors + history). */
+CREATE TABLE IF NOT EXISTS runtime_sessions (
+    pid INTEGER PRIMARY KEY,
+    data TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+
+/* Queryable turn snapshots (JSON includes actions/operations/behavior). */
+CREATE TABLE IF NOT EXISTS runtime_turns (
+    id TEXT PRIMARY KEY,
+    pid INTEGER NOT NULL,
+    session_id TEXT,
+    data TEXT NOT NULL,
+    created_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS runtime_turns_pid ON runtime_turns(pid, created_at DESC);
+
+/* Independent approval audit rows; the outbox carries the dispatch copy. */
+CREATE TABLE IF NOT EXISTS runtime_approvals (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    pid INTEGER NOT NULL,
+    turn_id TEXT NOT NULL,
+    operation_id TEXT NOT NULL,
+    tool TEXT NOT NULL,
+    risk TEXT NOT NULL,
+    decision TEXT NOT NULL,
+    status TEXT NOT NULL,
+    created_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS runtime_approvals_pid ON runtime_approvals(pid, id DESC);
+`;

package/lib/database/sql/sql.d.ts

@@ -0,0 +1,290 @@
+/**
+ * Generic SQL layer for one table.
+ *
+ * Every concrete table adapter extends {@link Sql} and supplies its
+ * {@link TableMeta}. The base class owns the statement shapes shared by all
+ * tables: primary-key lookup, list, count, insert, update, delete, upsert and
+ * existence checks. Table-specific queries belong in a concrete subclass and
+ * use the protected `query`, `queryOne`, `run` and `quote` helpers.
+ *
+ * Parameters are always bound; identifiers come from trusted {@link TableMeta}
+ * values and are validated before they are interpolated.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import type { PrimaryKey } from "../entity/entity.js";
+import type { TableMeta } from "../entity/meta.js";
+/**
+ * Value accepted by a SQLite bound parameter.
+ */
+export type SqlParameter = string | number | bigint | null | Uint8Array;
+/**
+ * Result of an INSERT, UPDATE or DELETE statement.
+ */
+export interface MutationResult {
+    /**
+     * Number of rows changed by the statement.
+     */
+    readonly changes: number;
+    /**
+     * SQLite rowid generated by an INSERT, or zero when none was generated.
+     */
+    readonly lastInsertRowid: number | bigint;
+}
+/**
+ * Options for a generated SELECT.
+ */
+export interface SelectOptions {
+    /**
+     * Optional SQL after WHERE.
+     */
+    readonly where?: string;
+    /**
+     * Bound values for the WHERE fragment.
+     */
+    readonly params?: readonly SqlParameter[];
+    /**
+     * Full ORDER BY fragment, for example a value returned by `Sort.toSql()`.
+     */
+    readonly orderBy?: string;
+    /**
+     * Maximum row count.
+     */
+    readonly limit?: number;
+    /**
+     * Number of rows to skip.
+     */
+    readonly offset?: number;
+    /**
+     * Optional column projection.
+     */
+    readonly columns?: readonly string[];
+}
+/**
+ * Convert a JavaScript value into a value `node:sqlite` can bind.
+ *
+ * Booleans become `1`/`0`, `undefined` becomes `NULL`, and unsupported object
+ * types fail early instead of being stringified silently.
+ *
+ * @param value - Value from a repository or service.
+ * @returns A bindable SQLite parameter.
+ * @throws TypeError when the value has no SQLite representation.
+ */
+export declare const toSqlParameter: (value: unknown) => SqlParameter;
+/**
+ * Validate a SQL identifier before it is interpolated into a statement.
+ *
+ * @param identifier - Table or column name.
+ * @returns The identifier unchanged.
+ * @throws Error when the identifier contains anything except letters, digits
+ * and underscores, or when it starts with a digit.
+ */
+export declare const assertSqlIdentifier: (identifier: string) => string;
+/**
+ * Abstract CRUD adapter for a single table.
+ *
+ * @typeParam TEntity - Row shape returned by the table.
+ * @typeParam TKey - Primary-key type.
+ */
+export declare abstract class Sql<TEntity extends object, TKey extends PrimaryKey = PrimaryKey> {
+    protected readonly db: DatabaseSync;
+    readonly meta: TableMeta;
+    private readonly columnSet;
+    /**
+     * Create a table adapter.
+     *
+     * @param db - Open SQLite connection.
+     * @param meta - Table, primary key and column metadata.
+     */
+    protected constructor(db: DatabaseSync, meta: TableMeta);
+    /**
+     * Physical table name.
+     */
+    get table(): string;
+    /**
+     * Primary-key column name.
+     */
+    get primaryKey(): string;
+    /**
+     * Columns allowed in generated statements.
+     */
+    get columns(): readonly string[];
+    /**
+     * Find one row by primary key.
+     *
+     * @param id - Primary-key value.
+     * @returns The row, or `undefined` when absent.
+     */
+    findById(id: TKey): TEntity | undefined;
+    /**
+     * Read rows in unspecified order.
+     *
+     * @param limit - Maximum row count.
+     * @returns Matching rows.
+     */
+    all(limit?: number): TEntity[];
+    /**
+     * Read rows with a trusted SQL WHERE fragment.
+     *
+     * The fragment is not analyzed; callers must pass only literals and
+     * placeholders, never interpolated user input.
+     *
+     * @param clause - SQL after `WHERE`.
+     * @param params - Bound values for the clause.
+     * @returns Matching rows.
+     */
+    where(clause: string, ...params: SqlParameter[]): TEntity[];
+    /**
+     * Read rows with optional filtering, ordering and pagination.
+     *
+     * @param options - Select options.
+     * @returns Matching rows.
+     */
+    select(options?: SelectOptions): TEntity[];
+    /**
+     * Count rows, optionally restricted by a WHERE fragment.
+     *
+     * @param clause - Optional SQL after `WHERE`.
+     * @param params - Bound values for the clause.
+     * @returns Number of matching rows.
+     */
+    count(clause?: string, ...params: SqlParameter[]): number;
+    /**
+     * Test whether a primary key exists.
+     *
+     * @param id - Primary-key value.
+     * @returns `true` when the row exists.
+     */
+    exists(id: TKey): boolean;
+    /**
+     * Insert one row.
+     *
+     * @param values - Column values; unknown keys are rejected.
+     * @returns Mutation metadata.
+     */
+    insert(values: Readonly<Record<string, unknown>>): MutationResult;
+    /**
+     * Update one row by primary key.
+     *
+     * @param id - Primary-key value.
+     * @param values - Column values; the primary key is ignored.
+     * @returns Number of changed rows.
+     */
+    update(id: TKey, values: Readonly<Record<string, unknown>>): number;
+    /**
+     * Update rows selected by a trusted WHERE fragment.
+     *
+     * @param clause - SQL after `WHERE`.
+     * @param values - Column values; the primary key is ignored.
+     * @param params - Bound values for the clause.
+     * @returns Number of changed rows.
+     */
+    updateWhere(clause: string, values: Readonly<Record<string, unknown>>, ...params: SqlParameter[]): number;
+    /**
+     * Delete one row by primary key.
+     *
+     * @param id - Primary-key value.
+     * @returns Number of deleted rows.
+     */
+    delete(id: TKey): number;
+    /**
+     * Delete rows selected by a trusted WHERE fragment.
+     *
+     * @param clause - SQL after `WHERE`.
+     * @param params - Bound values for the clause.
+     * @returns Number of deleted rows.
+     */
+    deleteWhere(clause: string, ...params: SqlParameter[]): number;
+    /**
+     * Insert a row, replacing conflicting columns on a conflict.
+     *
+     * @param values - Column values; conflict columns must be present.
+     * @param conflictColumns - Unique columns; defaults to the primary key.
+     * @returns Mutation metadata.
+     */
+    upsert(values: Readonly<Record<string, unknown>>, conflictColumns?: readonly string[]): MutationResult;
+    /**
+     * Build a SELECT column list.
+     *
+     * @param columns - Optional columns; omitted means all columns.
+     * @returns SQL column list.
+     */
+    private selectList;
+    /**
+     * Execute a trusted statement with bound parameters.
+     *
+     * @param sql - Complete SQL statement.
+     * @param params - Bound values.
+     * @returns Mutation metadata.
+     */
+    protected run(sql: string, ...params: SqlParameter[]): MutationResult;
+    /**
+     * Read rows from a trusted statement.
+     *
+     * @typeParam TRow - Row shape.
+     * @param sql - Complete SQL statement.
+     * @param params - Bound values.
+     * @returns Rows.
+     */
+    query<TRow>(sql: string, ...params: SqlParameter[]): TRow[];
+    /**
+     * Read one row from a trusted statement.
+     *
+     * @typeParam TRow - Row shape.
+     * @param sql - Complete SQL statement.
+     * @param params - Bound values.
+     * @returns The row, or `undefined`.
+     */
+    queryOne<TRow>(sql: string, ...params: SqlParameter[]): TRow | undefined;
+    /**
+     * Quote an identifier after validating it.
+     *
+     * @param identifier - Table or column name.
+     * @returns Double-quoted identifier.
+     */
+    protected quote(identifier: string): string;
+    /**
+     * Check that the table metadata is internally consistent.
+     */
+    private assertMeta;
+    /**
+     * Select writable columns from a value map.
+     *
+     * @param values - Caller-supplied values.
+     * @param includePrimaryKey - Whether the primary key is writable.
+     * @returns Ordered column names.
+     */
+    private collectColumns;
+    /**
+     * Build bound parameters in column order.
+     *
+     * @param values - Caller-supplied values.
+     * @param columns - Ordered column names.
+     * @returns Bindable parameters.
+     */
+    private collectParams;
+    /**
+     * Validate and normalize a LIMIT value.
+     *
+     * @param limit - Requested row count.
+     * @returns A non-negative integer.
+     */
+    private normalizeLimit;
+}
+/**
+ * Concrete SQL adapter for a table that only needs generated CRUD statements.
+ *
+ * Table-specific operations can instead subclass {@link Sql} and use the
+ * public query helpers.
+ *
+ * @typeParam TEntity - Row shape returned by the table.
+ * @typeParam TKey - Primary-key type.
+ */
+export declare class TableSql<TEntity extends object, TKey extends PrimaryKey = PrimaryKey> extends Sql<TEntity, TKey> {
+    /**
+     * Create a generated table adapter.
+     *
+     * @param db - Open SQLite connection.
+     * @param meta - Table, primary key and column metadata.
+     */
+    constructor(db: DatabaseSync, meta: TableMeta);
+}