agentfootprint/dist/types/artifacts/sqliteArtifacts.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * artifacts/sqliteArtifacts — the claim-check store in one SQLite file.
 *
 * The durable pairing for `sqliteSessions`: point both at files beside each
 * other and the artifacts a conversation minted live exactly as long as the
 * conversation that can speak their refs — retention coupled by
 * construction, not by checkup. It follows `hosting/sqliteSessions` law for
 * law: `node:sqlite` loaded lazily at construction and refused by name where
 * absent (no install, no native build, and no version-floor tax on consumers
 * who never construct one); WAL requested and the journal mode REPORTED as
 * read back rather than assumed; STRICT tables; a file that exists but is not
 * ours refused by name (`not-our-schema` / `newer-schema` / `cannot-open`) —
 * an unreadable store and an empty one are different facts, and only one of
 * them is safe to answer with a fresh start; `':memory:'` refused, because
 * `inMemoryArtifacts` says that in its name.
 *
 * The columns repeat what the meta knows (kind, bytes, expiry, creation) so
 * an incident can ask "what is filling this store?" from the `sqlite3`
 * command line without a JSON parser and without this library.
 *
 * One process, one machine, one writer at a time — the same ceiling
 * sqliteSessions states, inherited rather than restated at length.
 */
import { type ArtifactRetention } from './retention.js';
import { type ArtifactStore } from './types.js';
/** One prepared statement, as this adapter calls it. */
export interface SqliteArtifactsStatementLike {
    run(...params: readonly unknown[]): unknown;
    get(...params: readonly unknown[]): unknown;
    all(...params: readonly unknown[]): unknown[];
}
/** One open database, as this adapter calls it. */
export interface SqliteArtifactsDatabaseLike {
    exec(sql: string): void;
    prepare(sql: string): SqliteArtifactsStatementLike;
    close(): void;
}
/** The shape of `node:sqlite`'s DatabaseSync this adapter needs. */
export interface SqliteArtifactsModuleLike {
    new (path: string): SqliteArtifactsDatabaseLike;
}
/** Options for {@link sqliteArtifacts}. */
export interface SqliteArtifactsOptions {
    /** The database file. Created if missing, parent directory included.
     *  `':memory:'` is refused — use `inMemoryArtifacts()`, it says so in its name. */
    readonly file: string;
    /** Retention dials — optional here: disk is a budget the operator owns.
     *  Budget evictions are least-recently-ACCESSED first (reads refresh recency). */
    readonly retention?: ArtifactRetention;
    /** How long a write waits for another writer's lock before failing loudly.
     *  Default 5000 ms. */
    readonly busyTimeoutMs?: number;
    /** @internal Test seam only — the `node:sqlite` module, injected. Not public
     *  API and not a place to plug in another SQLite driver. */
    readonly _sqlite?: SqliteArtifactsModuleLike;
    /** @internal Test seam — the clock. Defaults to `Date.now`. */
    readonly _now?: () => number;
}
/** The store, plus the three things a real file store owes beyond the port. */
export interface SqliteArtifacts extends ArtifactStore {
    /** The journal mode the file ACTUALLY has, read back from SQLite. */
    readonly journalMode: string;
    /** Close the file. Idempotent; using the store afterwards refuses by name. */
    close(): void;
}
/**
 * Raised when the file exists but this runtime cannot use it as an artifact
 * store — never answered with an empty store. Same law, same three cases as
 * `UnreadableSessionFileError`, per store.
 */
export declare class UnreadableArtifactStoreError extends Error {
    readonly code: "ERR_UNREADABLE_ARTIFACT_STORE";
    readonly file: string;
    readonly problem: 'cannot-open' | 'not-our-schema' | 'newer-schema';
    constructor(file: string, problem: UnreadableArtifactStoreError['problem'], detail: string);
}
/**
 * An artifact store in one SQLite file — durable across restarts, crash-safe
 * under WAL, and the natural neighbour of `sqliteSessions({ file })`.
 *
 * @throws SqliteUnavailableError when the running Node has no `node:sqlite`.
 * @throws UnreadableArtifactStoreError when the file exists but cannot be used.
 *
 * @example
 *   const agent = Agent.create({
 *     provider,
 *     artifacts: sqliteArtifacts({ file: './data/artifacts.db' }),
 *   });
 */
export declare function sqliteArtifacts(options: SqliteArtifactsOptions): SqliteArtifacts;
//# sourceMappingURL=sqliteArtifacts.d.ts.map