@cogenta/core 0.1.0

package/dist/db/sqlite.js

@@ -0,0 +1,213 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { CogentaError } from '../errors/index.js';
+import { compile, isWrite, returnsRows } from './dialect.js';
+/**
+ * `node:sqlite` ships with Node, so the default install compiles nothing and
+ * depends on nothing. `better-sqlite3` is deliberately not used: it is native
+ * code, and rule R10 forbids that without a fallback because it breaks on ARM,
+ * musl and shared hosting — exactly the deployments SQLite is meant to serve.
+ *
+ * It is unflagged from Node 22.13. On an older runtime this returns null and the
+ * registry reports the driver as unavailable rather than crashing.
+ */
+export async function loadSqliteModule() {
+    try {
+        return (await import('node:sqlite'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * One transaction at a time per database file, per process.
+ *
+ * `node:sqlite` is synchronous. Two connections to the same file inside one
+ * process deadlock without this: the second `BEGIN IMMEDIATE` blocks the thread
+ * holding it, and the first transaction can never reach its `COMMIT` because its
+ * continuation needs an event loop that is no longer turning. SQLite's
+ * `busy_timeout` cannot help — it just decides how long the deadlock lasts
+ * before it becomes an error.
+ *
+ * Serialising costs no parallelism that existed: a synchronous driver on one
+ * thread was never going to run two transactions at once. It turns a deadlock
+ * into an orderly queue. Across *processes*, SQLite's own locking applies as
+ * usual.
+ */
+const fileLocks = new Map();
+async function withFileLock(key, run) {
+    const previous = fileLocks.get(key) ?? Promise.resolve();
+    const current = previous.then(run, run);
+    fileLocks.set(key, current.catch(() => undefined));
+    try {
+        return await current;
+    }
+    finally {
+        if (fileLocks.get(key) === current)
+            fileLocks.delete(key);
+    }
+}
+function fileFromUrl(url) {
+    if (url === ':memory:')
+        return ':memory:';
+    if (url.startsWith('file:'))
+        return url.slice('file:'.length).replace(/^\/\//, '');
+    if (url.startsWith('sqlite://'))
+        return url.slice('sqlite://'.length);
+    return url;
+}
+function executorFor(database) {
+    const executor = {
+        dialect: 'sqlite',
+        query: async (fragment) => executor.execute(compile(fragment, 'sqlite')),
+        execute: async ({ text, params }, options) => {
+            try {
+                const statement = database.prepare(text);
+                const asArrays = options?.asArrays === true;
+                if (asArrays)
+                    statement.setReturnArrays?.(true);
+                if (returnsRows(text)) {
+                    const raw = statement.all(...params);
+                    const rows = (asArrays && statement.setReturnArrays === undefined ? raw.map(toValues) : raw);
+                    return { rows, rowsAffected: isWrite(text) ? rows.length : 0 };
+                }
+                const result = statement.run(...params);
+                return { rows: [], rowsAffected: Number(result.changes) };
+            }
+            catch (error) {
+                throw new CogentaError({
+                    code: 'DB_UNREACHABLE',
+                    message: `SQLite rejected a statement: ${error instanceof Error ? error.message : String(error)}`,
+                    hint: 'Check the statement and the schema. The failing SQL is in the details.',
+                    cause: error,
+                    // The statement is included, the parameters are not: they routinely
+                    // carry personal data, and this ends up in a log.
+                    details: { sql: text },
+                });
+            }
+        },
+    };
+    return executor;
+}
+/**
+ * The values of a row in the order the statement selected them.
+ *
+ * Only reached on a runtime whose `node:sqlite` cannot return arrays directly.
+ * Object key order follows column order, so this is exact for every query except
+ * one that selects the same column name twice.
+ */
+function toValues(row) {
+    return Object.values(row);
+}
+export async function createSqliteHandle(options) {
+    const module = await loadSqliteModule();
+    if (module === null) {
+        throw new CogentaError({
+            code: 'DRIVER_INIT_FAILED',
+            message: 'This Node runtime has no built-in SQLite module.',
+            hint: 'Upgrade to Node 22.13 or later, or use Postgres or MySQL instead.',
+        });
+    }
+    const file = fileFromUrl(options.url);
+    if (file !== ':memory:')
+        await mkdir(dirname(file), { recursive: true });
+    const database = new module.DatabaseSync(file);
+    const executor = executorFor(database);
+    // Two :memory: handles are two separate databases, so they never contend.
+    const lockKey = file === ':memory:' ? `memory:${randomUUID()}` : resolve(file);
+    // WAL lets a writer and readers work at the same time. Without it concurrent
+    // writes serialise on a global lock and time out under any real load — the
+    // failure the L0 spec calls out by name. `:memory:` has no journal to switch.
+    if (file !== ':memory:')
+        database.exec('PRAGMA journal_mode = WAL');
+    database.exec('PRAGMA busy_timeout = 5000');
+    database.exec('PRAGMA foreign_keys = ON');
+    let depth = 0;
+    return {
+        dialect: 'sqlite',
+        // Every statement takes the file lock, not only transactions. A plain
+        // UPDATE from a second connection, while a first holds BEGIN IMMEDIATE,
+        // deadlocks the process just as surely: it blocks the only thread, so the
+        // transaction it is waiting on can never commit. A statement issued from
+        // inside our own transaction already holds the lock and must not re-take it.
+        query: async (fragment) => depth > 0
+            ? executor.query(fragment)
+            : withFileLock(lockKey, () => executor.query(fragment)),
+        execute: async (query, executeOptions) => depth > 0
+            ? executor.execute(query, executeOptions)
+            : withFileLock(lockKey, () => executor.execute(query, executeOptions)),
+        transaction: async (run, transactionOptions) => {
+            // A nested call is already inside the lock; taking it again would wait on
+            // itself forever.
+            if (depth > 0)
+                return runTransaction(run, transactionOptions);
+            return withFileLock(lockKey, () => runTransaction(run, transactionOptions));
+        },
+        close: async () => {
+            database.close();
+        },
+    };
+    async function runTransaction(run, transactionOptions) {
+        // SQLite has no nested transactions; savepoints stand in for them so a
+        // caller can compose two functions that each want a transaction.
+        const nested = depth > 0;
+        const savepoint = `cogenta_sp_${depth}`;
+        if (nested) {
+            database.exec(`SAVEPOINT ${savepoint}`);
+        }
+        else {
+            database.exec(transactionOptions?.immediate === true ? 'BEGIN IMMEDIATE' : 'BEGIN');
+        }
+        depth += 1;
+        try {
+            const result = await run(executor);
+            database.exec(nested ? `RELEASE ${savepoint}` : 'COMMIT');
+            return result;
+        }
+        catch (error) {
+            if (nested) {
+                database.exec(`ROLLBACK TO ${savepoint}`);
+                database.exec(`RELEASE ${savepoint}`);
+            }
+            else {
+                database.exec('ROLLBACK');
+            }
+            throw error;
+        }
+        finally {
+            depth -= 1;
+        }
+    }
+}
+export function sqliteDatabaseDriver() {
+    let handle;
+    let url;
+    return {
+        name: 'sqlite',
+        tier: 'degraded',
+        available: async () => (await loadSqliteModule()) !== null,
+        init: async (config) => {
+            url = config.url ?? './.cogenta/site.db';
+            handle ??= await createSqliteHandle({ url });
+            return handle;
+        },
+        dispose: async () => {
+            await handle?.close();
+            handle = undefined;
+        },
+        health: async () => {
+            if (handle === undefined) {
+                return { status: 'down', driver: 'sqlite', tier: 'degraded', message: 'Not opened.' };
+            }
+            return {
+                status: 'degraded',
+                driver: 'sqlite',
+                tier: 'degraded',
+                // The path is safe to show; a SQLite URL never carries a password.
+                message: `SQLite at ${url ?? 'an unopened path'}. Single machine, no vector index.`,
+            };
+        },
+    };
+}
+//# sourceMappingURL=sqlite.js.map

package/dist/db/sqlite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../../src/db/sqlite.ts"],"names":[],"mappings":"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"}

package/dist/db/types.d.ts

@@ -0,0 +1,71 @@
+import type { CompiledQuery, SqlFragment } from './dialect.js';
+export declare const DATABASE_DIALECTS: readonly ['postgres', 'mysql', 'sqlite'];
+export type DatabaseDialect = (typeof DATABASE_DIALECTS)[number];
+export interface QueryResult<TRow = Record<string, unknown>> {
+    readonly rows: TRow[];
+    /** Rows created, changed or removed. Zero for a plain read. */
+    readonly rowsAffected: number;
+    /**
+     * The auto-increment key the server assigned to the first inserted row.
+     *
+     * Only MySQL reports one. Postgres and SQLite say the same thing through
+     * `RETURNING`, which is why nothing in the layer depends on this — it exists
+     * so the Drizzle bridge can answer `$returningId()` on MySQL.
+     */
+    readonly insertId?: number;
+}
+export interface ExecuteOptions {
+    /**
+     * Hand back each row as the ordered list of its column values instead of an
+     * object keyed by column name.
+     *
+     * A query that selects two columns with the same name — every join does,
+     * `users.id` and `posts.id` — loses one of them in an object, because the
+     * second key overwrites the first. Callers that map by position rather than by
+     * name need the values in order, and that is what an ORM built on top of this
+     * layer does.
+     */
+    readonly asArrays?: boolean;
+}
+export interface SqlExecutor {
+    readonly dialect: DatabaseDialect;
+    query<TRow = Record<string, unknown>>(fragment: SqlFragment): Promise<QueryResult<TRow>>;
+    /**
+     * Runs SQL that is already rendered for this dialect, placeholders and all.
+     *
+     * The escape hatch for a layer that writes its own SQL rather than composing
+     * `sql` fragments — Drizzle, in practice. It skips `encodeValue` on purpose:
+     * such a layer has already mapped every value to what its own column types
+     * promise, and encoding twice would corrupt it.
+     */
+    execute<TRow = Record<string, unknown>>(query: CompiledQuery, options?: ExecuteOptions): Promise<QueryResult<TRow>>;
+}
+export interface TransactionOptions {
+    /**
+     * Take the write lock at `BEGIN` instead of at the first write.
+     *
+     * On SQLite a deferred transaction that reads and then writes can fail with
+     * SQLITE_BUSY under concurrency, because the lock it needs was taken by
+     * someone else in between. Any read-modify-write — reserving a job, bumping a
+     * counter — needs this.
+     */
+    readonly immediate?: boolean;
+}
+export interface DatabaseHandle extends SqlExecutor {
+    transaction<T>(run: (tx: SqlExecutor) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    close(): Promise<void>;
+}
+/** The resolved `database` section of the configuration. */
+export interface DatabaseConfig {
+    readonly driver?: string;
+    readonly url?: string;
+    /**
+     * Maximum simultaneous connections. Deliberately small by default: shared
+     * hosting allows very few, and exhausting them takes the whole site down.
+     */
+    readonly poolSize?: number;
+}
+export interface DatabaseDriverOptions {
+    readonly poolSize?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/db/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/db/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE9D,eAAO,MAAM,iBAAiB,YAAI,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAA;AAEzE,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEhE,MAAM,WAAW,WAAW,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzD,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,CAAA;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAA;IACxF;;;;;;;OAOG;IACH,OAAO,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAA;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAC7B;AAED,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IAC9F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B"}

package/dist/db/types.js

@@ -0,0 +1,2 @@
+export const DATABASE_DIALECTS = ['postgres', 'mysql', 'sqlite'];
+//# sourceMappingURL=types.js.map

package/dist/db/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/db/types.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAA"}

package/dist/drivers/index.d.ts

@@ -0,0 +1,5 @@
+export type { DriverRegistry, DriverRegistryOptions } from './registry.js';
+export { createDriverRegistry } from './registry.js';
+export type { Driver, DriverChoice, DriverSelection, DriverTier, HealthReport, HealthStatus, SkippedDriver, } from './types.js';
+export { DRIVER_TIERS } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/drivers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/drivers/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACpD,YAAY,EACV,MAAM,EACN,YAAY,EACZ,eAAe,EACf,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA"}

package/dist/drivers/index.js

@@ -0,0 +1,3 @@
+export { createDriverRegistry } from './registry.js';
+export { DRIVER_TIERS } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/drivers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/drivers/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AAUpD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA"}

package/dist/drivers/registry.d.ts

@@ -0,0 +1,27 @@
+import { type Logger } from '../logger/index.js';
+import { type Driver, type DriverChoice, type DriverSelection } from './types.js';
+export interface DriverRegistryOptions {
+    /** What this registry provides: `cache`, `queue`, `storage`, `database`. */
+    readonly need: string;
+    readonly logger?: Logger;
+}
+export interface DriverRegistry<TInstance, TConfig extends DriverChoice> {
+    register(driver: Driver<TInstance, TConfig>): void;
+    /** Registered drivers, optimal first. Used by `cogenta doctor`. */
+    list(): readonly Driver<TInstance, TConfig>[];
+    select(config: TConfig): Promise<DriverSelection<TInstance>>;
+}
+/**
+ * Holds the implementations of one infrastructure need and picks between them.
+ *
+ * Two rules, and the difference between them matters more than it looks:
+ *
+ * - The configuration **names** a driver → that driver is used, and any failure
+ *   is fatal. The operator asked for Redis; starting on the filesystem instead
+ *   and saying nothing would be a silent, invisible downgrade of their site.
+ * - The configuration names **nothing** → the first available driver wins, in
+ *   tier order, and failures fall through. `npm create cogenta` must produce a
+ *   working site with nothing else installed.
+ */
+export declare function createDriverRegistry<TInstance, TConfig extends DriverChoice>(options: DriverRegistryOptions): DriverRegistry<TInstance, TConfig>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/drivers/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/drivers/registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAC9D,OAAO,EAEL,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,KAAK,eAAe,EAGrB,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,qBAAqB;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,cAAc,CAAC,SAAS,EAAE,OAAO,SAAS,YAAY;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAClD,mEAAmE;IACnE,IAAI,IAAI,SAAS,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,CAAA;IAC7C,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC,CAAA;CAC7D;AAYD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,OAAO,SAAS,YAAY,EAC1E,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAAC,SAAS,EAAE,OAAO,CAAC,CA6JpC"}

package/dist/drivers/registry.js

@@ -0,0 +1,162 @@
+import { CogentaError } from '../errors/index.js';
+import { createLogger } from '../logger/index.js';
+import { DRIVER_TIERS, } from './types.js';
+/** `auto`, like an absent value, means "you choose". */
+function namedDriver(config) {
+    const requested = config.driver;
+    return requested === undefined || requested === 'auto' ? undefined : requested;
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Holds the implementations of one infrastructure need and picks between them.
+ *
+ * Two rules, and the difference between them matters more than it looks:
+ *
+ * - The configuration **names** a driver → that driver is used, and any failure
+ *   is fatal. The operator asked for Redis; starting on the filesystem instead
+ *   and saying nothing would be a silent, invisible downgrade of their site.
+ * - The configuration names **nothing** → the first available driver wins, in
+ *   tier order, and failures fall through. `npm create cogenta` must produce a
+ *   working site with nothing else installed.
+ */
+export function createDriverRegistry(options) {
+    const { need } = options;
+    const logger = (options.logger ?? createLogger()).child({ need });
+    const drivers = new Map();
+    function ordered() {
+        return DRIVER_TIERS.flatMap((tier) => [...drivers.values()].filter((d) => d.tier === tier));
+    }
+    function selection(driver, instance, requested, reason, skipped) {
+        let disposed = false;
+        logger.info('driver selected', { driver: driver.name, tier: driver.tier, reason, requested });
+        return {
+            need,
+            driver: driver.name,
+            tier: driver.tier,
+            instance,
+            requested,
+            reason,
+            skipped,
+            dispose: async () => {
+                if (disposed)
+                    return;
+                disposed = true;
+                await driver.dispose();
+            },
+            health: () => driver.health(),
+        };
+    }
+    async function selectNamed(name, config) {
+        const driver = drivers.get(name);
+        if (driver === undefined) {
+            const known = ordered().map((d) => d.name);
+            throw new CogentaError({
+                code: 'DRIVER_UNKNOWN',
+                message: `No ${need} driver named "${name}".`,
+                hint: known.length === 0
+                    ? `No ${need} driver is registered at all.`
+                    : `Available ${need} drivers: ${known.join(', ')}. Use "auto" to let Cogenta choose.`,
+                details: { need, requested: name, known },
+            });
+        }
+        let reachable;
+        try {
+            reachable = await driver.available(config);
+        }
+        catch (error) {
+            throw new CogentaError({
+                code: 'DRIVER_UNAVAILABLE',
+                message: `The ${need} driver "${name}" could not be reached: ${describe(error)}`,
+                hint: `Start the service, fix its URL, or set ${need}.driver to "auto" to fall back automatically.`,
+                cause: error,
+                details: { need, driver: name },
+            });
+        }
+        if (!reachable) {
+            throw new CogentaError({
+                code: 'DRIVER_UNAVAILABLE',
+                message: `The ${need} driver "${name}" is configured but not available.`,
+                hint: `Start the service, fix its URL, or set ${need}.driver to "auto" to fall back automatically.`,
+                details: { need, driver: name },
+            });
+        }
+        try {
+            const instance = await driver.init(config);
+            return selection(driver, instance, true, `named in the configuration`, []);
+        }
+        catch (error) {
+            throw new CogentaError({
+                code: 'DRIVER_INIT_FAILED',
+                message: `The ${need} driver "${name}" failed to start: ${describe(error)}`,
+                hint: `This driver was named in the configuration, so Cogenta will not fall back to another one on its own. Fix it, or set ${need}.driver to "auto".`,
+                cause: error,
+                details: { need, driver: name },
+            });
+        }
+    }
+    async function selectAutomatically(config) {
+        const skipped = [];
+        for (const driver of ordered()) {
+            const skip = (reason) => {
+                skipped.push({ driver: driver.name, tier: driver.tier, reason });
+                logger.debug('driver skipped', { driver: driver.name, tier: driver.tier, reason });
+            };
+            try {
+                if (!(await driver.available(config))) {
+                    skip('not available');
+                    continue;
+                }
+            }
+            catch (error) {
+                skip(`not available: ${describe(error)}`);
+                continue;
+            }
+            try {
+                const instance = await driver.init(config);
+                const because = skipped.length === 0
+                    ? 'first available driver'
+                    : `${skipped.map((s) => `${s.driver} ${s.reason}`).join(', ')}`;
+                return selection(driver, instance, false, because, skipped);
+            }
+            catch (error) {
+                // It answered the probe and failed anyway. Keep going: the site booting
+                // on a degraded driver beats the site not booting.
+                skip(`failed to start: ${describe(error)}`);
+                logger.warn('driver failed to start, trying the next one', {
+                    driver: driver.name,
+                    error,
+                });
+            }
+        }
+        const tried = skipped.map((s) => `${s.driver} (${s.reason})`).join(', ');
+        throw new CogentaError({
+            code: 'DRIVER_UNAVAILABLE',
+            message: skipped.length === 0
+                ? `No ${need} driver is registered.`
+                : `No ${need} driver is available. Tried: ${tried}.`,
+            hint: `Every Cogenta need has a driver that works without any external service. If you see this, the degraded ${need} driver is missing or broken — please report it.`,
+            details: { need, skipped },
+        });
+    }
+    return {
+        register(driver) {
+            if (drivers.has(driver.name)) {
+                throw new CogentaError({
+                    code: 'DRIVER_DUPLICATE',
+                    message: `A ${need} driver named "${driver.name}" is already registered.`,
+                    hint: 'Driver names are unique per need. Rename one of them.',
+                    details: { need, driver: driver.name },
+                });
+            }
+            drivers.set(driver.name, driver);
+        },
+        list: () => ordered(),
+        select: async (config) => {
+            const name = namedDriver(config);
+            return name === undefined ? selectAutomatically(config) : selectNamed(name, config);
+        },
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/drivers/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/drivers/registry.ts"],"names":[],"mappings":"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"}

package/dist/drivers/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `optimal` needs an external service. `degraded` needs nothing beyond Node and
+ * the filesystem. Rule R1: every infrastructure need has at least one of each,
+ * so the default install has no external dependency at all.
+ */
+export type DriverTier = 'optimal' | 'degraded';
+export declare const DRIVER_TIERS: readonly DriverTier[];
+export type HealthStatus = 'ok' | 'degraded' | 'down';
+export interface HealthReport {
+    readonly status: HealthStatus;
+    readonly driver: string;
+    readonly tier: DriverTier;
+    readonly latencyMs?: number;
+    /** Plain sentence for the admin. Must never contain a credential. */
+    readonly message?: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+/**
+ * One implementation of an infrastructure need.
+ *
+ * `available()` answers "does the service actually answer?" — not "is a URL
+ * configured?". Getting that wrong turns a fallback into a startup crash.
+ */
+export interface Driver<TInstance, TConfig> {
+    readonly name: string;
+    readonly tier: DriverTier;
+    available(config: TConfig): Promise<boolean>;
+    init(config: TConfig): Promise<TInstance>;
+    dispose(): Promise<void>;
+    health(): Promise<HealthReport>;
+}
+export interface SkippedDriver {
+    readonly driver: string;
+    readonly tier: DriverTier;
+    readonly reason: string;
+}
+/**
+ * The outcome of a selection. `reason` and `skipped` exist so `cogenta doctor`
+ * and the admin can state what is running and why — "job queue: database
+ * (degraded), because Redis is absent". That is a product requirement, not a
+ * debugging aid.
+ */
+export interface DriverSelection<TInstance> {
+    readonly need: string;
+    readonly driver: string;
+    readonly tier: DriverTier;
+    readonly instance: TInstance;
+    /** True when the configuration named this driver, rather than leaving it to us. */
+    readonly requested: boolean;
+    readonly reason: string;
+    readonly skipped: readonly SkippedDriver[];
+    dispose(): Promise<void>;
+    health(): Promise<HealthReport>;
+}
+/** Any config section that may name a driver. `auto` names nothing. */
+export interface DriverChoice {
+    readonly driver?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/drivers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/drivers/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,UAAU,CAAA;AAE/C,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAA4B,CAAA;AAE1E,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,UAAU,GAAG,MAAM,CAAA;AAErD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACrD;AAED;;;;;GAKG;AACH,MAAM,WAAW,MAAM,CAAC,SAAS,EAAE,OAAO;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC5C,IAAI,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;IACzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC,CAAA;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,SAAS;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAA;IAC1C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC,CAAA;CAChC;AAED,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB"}

package/dist/drivers/types.js

@@ -0,0 +1,2 @@
+export const DRIVER_TIERS = ['optimal', 'degraded'];
+//# sourceMappingURL=types.js.map

package/dist/drivers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/drivers/types.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,YAAY,GAA0B,CAAC,SAAS,EAAE,UAAU,CAAC,CAAA"}

package/dist/errors/codes.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Every error Cogenta throws carries one of these codes. They are a public API:
+ * callers branch on them, logs are aggregated by them, and translations key off
+ * them. Adding a code is a minor version; changing the meaning of one is major.
+ */
+export declare const ERROR_CODES: readonly ['CONFIG_INVALID', 'CONFIG_NOT_FOUND', 'CONFIG_LOAD_FAILED', 'CONFIG_SECRET_IN_FILE', 'DRIVER_UNKNOWN', 'DRIVER_DUPLICATE', 'DRIVER_UNAVAILABLE', 'DRIVER_INIT_FAILED', 'DB_UNREACHABLE', 'DB_DIALECT_UNSUPPORTED', 'MIGRATION_FAILED', 'MIGRATION_IRREVERSIBLE', 'MIGRATION_LOCKED', 'MIGRATION_CHECKSUM_MISMATCH', 'MIGRATION_DESTRUCTIVE', 'SCHEMA_INVALID', 'CONTENT_NOT_FOUND', 'CONTENT_INVALID', 'CONTENT_CONFLICT', 'CONTENT_SLUG_INVALID', 'CONTENT_SLUG_TAKEN', 'CONTENT_ROUTE_INVALID', 'CONTENT_REDIRECT_LOOP', 'CONTENT_SCHEDULE_INVALID', 'CONTENT_READ_ONLY', 'BLOCK_UNKNOWN', 'BLOCK_INVALID', 'BLOCK_DEFINITION_INVALID', 'BLOCK_MIGRATION_FAILED', 'SKIN_TOKEN_MISSING', 'SKIN_TOKEN_UNKNOWN', 'SKIN_TOKEN_INVALID', 'SKIN_CONTRAST_INSUFFICIENT', 'SKIN_SCALE_NOT_MONOTONIC', 'SKIN_MOTION_NOT_REDUCED', 'THEME_NOT_FOUND', 'THEME_INVALID', 'THEME_BLOCK_MISSING', 'THEME_IMPORT_FORBIDDEN', 'THEME_SIGNATURE_INVALID', 'CONTENT_API_FAILED', 'THEME_IMAGE_UNSUPPORTED', 'BUILD_TARGET_UNKNOWN', 'BUILD_RUNTIME_UNSATISFIED', 'FORBIDDEN', 'UNAUTHENTICATED', 'PREVIEW_TOKEN_INVALID', 'PREVIEW_TOKEN_EXPIRED', 'QUERY_INVALID', 'AUTH_PASSWORD_INVALID', 'AUTH_INVALID_CREDENTIALS', 'AUTH_TOTP_INVALID', 'AUTH_TOTP_REQUIRED', 'AUTH_WEBAUTHN_FAILED', 'AUTH_SESSION_INVALID', 'AUTH_SESSION_EXPIRED', 'AUTH_RATE_LIMITED', 'AUTH_MFA_REQUIRED', 'AUTH_USER_EXISTS', 'AUTH_USER_NOT_FOUND', 'AUTH_ROLE_UNKNOWN', 'AUDIT_CHAIN_BROKEN', 'MEDIA_NOT_FOUND', 'MEDIA_INVALID', 'MEDIA_TYPE_REJECTED', 'CACHE_FAILED', 'QUEUE_FAILED', 'STORAGE_FAILED', 'PROVIDER_UNKNOWN', 'PROVIDER_REQUEST_FAILED', 'PROVIDER_RESPONSE_INVALID', 'PROVIDER_RATE_LIMITED', 'PROVIDER_TIMEOUT', 'TOOL_DEFINITION_INVALID', 'TOOL_DUPLICATE', 'TOOL_UNKNOWN', 'TOOL_INPUT_INVALID', 'TOOL_OUTPUT_INVALID', 'TOOL_CALL_REJECTED', 'HTTP_FETCH_DOMAIN_DENIED', 'APPROVAL_REQUEST_UNKNOWN', 'RECEIPT_UNKNOWN', 'RECEIPT_ALREADY_REVERTED', 'RECEIPT_NOT_REVERTIBLE', 'AGENT_SUBAGENT_UNKNOWN', 'AGENT_SUBAGENT_TOOLS_NOT_SUBSET', 'SKILL_UNKNOWN', 'SKILL_DEFINITION_INVALID', 'AGENT_APPROVAL_NOT_DECIDED', 'MCP_CLIENT_REMOTE_ERROR', 'MCP_CLIENT_TOOL_FAILED', 'PRIVACY_NO_DATA_LEAVES_VIOLATION', 'AGENT_DEFINITION_INVALID', 'AGENT_UNKNOWN', 'EVAL_THRESHOLD_NOT_MET', 'SECURITY_OSV_QUERY_FAILED', 'SECURITY_EPSS_QUERY_FAILED', 'SECURITY_DEPENDENCY_NOT_FOUND', 'PERFORMANCE_CRUX_QUERY_FAILED', 'BLUEPRINT_REGISTRY_CORRUPT', 'SKIN_GENERATION_RESPONSE_NOT_JSON', 'IMPORT_WXR_PARSE_FAILED', 'IMPORT_WXR_UNSAFE_DOCUMENT', 'PLAYGROUND_BLUEPRINT_UNKNOWN', 'CHANNEL_UNKNOWN', 'CHANNEL_DUPLICATE', 'CHANNEL_LINK_CODE_INVALID', 'CHANNEL_COMMAND_DUPLICATE', 'CHANNEL_TELEGRAM_API_ERROR', 'CHANNEL_MESSAGE_INVALID', 'CHANNEL_PREFERENCES_INVALID', 'CHANNEL_EMAIL_TRANSPORT_ERROR', 'CHANNEL_EMAIL_INBOUND_UNSUPPORTED', 'CHANNEL_SLACK_API_ERROR', 'CHANNEL_DISCORD_API_ERROR', 'CHANNEL_WEBHOOK_SIGNATURE_INVALID', 'CHANNEL_WEBHOOK_EXPIRED', 'CHANNEL_WEBHOOK_REPLAY_DETECTED', 'CHANNEL_WEBHOOK_DELIVERY_FAILED', 'CHANNEL_WEBHOOK_INBOUND_UNSUPPORTED', 'PLUGIN_MANIFEST_INVALID', 'PLUGIN_SOURCE_NOT_FOUND', 'PLUGIN_MANIFEST_FILE_NOT_FOUND', 'PLUGIN_MANIFEST_LOAD_FAILED', 'PLUGIN_MANIFEST_EXPORT_INVALID', 'PLUGIN_WORKER_TIMEOUT', 'PLUGIN_WORKER_CRASHED', 'PLUGIN_WORKER_RUNTIME_ERROR', 'PLUGIN_CAPABILITY_REFUSED', 'PLUGIN_DISABLED', 'PLUGIN_SIGNATURE_MISSING', 'PLUGIN_SIGNATURE_INVALID', 'FLEET_TELEMETRY_FORBIDDEN_FIELD', 'FLEET_CAMPAIGN_NOT_FOUND', 'FLEET_CAMPAIGN_STATE_CORRUPT', 'FLEET_ROLLBACK_NO_PRIOR_VERSION', 'INTERNAL'];
+export type ErrorCode = (typeof ERROR_CODES)[number];
+//# sourceMappingURL=codes.d.ts.map

package/dist/errors/codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../../src/errors/codes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,WAAW,YAEtB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EAGvB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EAGpB,gBAAgB,EAChB,wBAAwB,EACxB,kBAAkB,EAClB,wBAAwB,EACxB,kBAAkB,EAClB,6BAA6B,EAC7B,uBAAuB,EAGvB,gBAAgB,EAGhB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,EACvB,0BAA0B,EAC1B,mBAAmB,EAGnB,eAAe,EACf,eAAe,EACf,0BAA0B,EAC1B,wBAAwB,EAIxB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EAGzB,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,wBAAwB,EACxB,yBAAyB,EAGzB,oBAAoB,EAIpB,yBAAyB,EAIzB,sBAAsB,EACtB,2BAA2B,EAG3B,WAAW,EACX,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,EACvB,eAAe,EAGf,uBAAuB,EACvB,0BAA0B,EAC1B,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EAGpB,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EAGrB,cAAc,EACd,cAAc,EACd,gBAAgB,EAGhB,kBAAkB,EAClB,yBAAyB,EACzB,2BAA2B,EAC3B,uBAAuB,EACvB,kBAAkB,EAGlB,yBAAyB,EACzB,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EAGpB,0BAA0B,EAG1B,0BAA0B,EAG1B,iBAAiB,EACjB,0BAA0B,EAC1B,wBAAwB,EAGxB,wBAAwB,EACxB,iCAAiC,EAGjC,eAAe,EACf,0BAA0B,EAG1B,4BAA4B,EAG5B,yBAAyB,EACzB,wBAAwB,EAGxB,kCAAkC,EAGlC,0BAA0B,EAC1B,eAAe,EAGf,wBAAwB,EAGxB,2BAA2B,EAC3B,4BAA4B,EAC5B,+BAA+B,EAG/B,+BAA+B,EAG/B,4BAA4B,EAG5B,mCAAmC,EAGnC,yBAAyB,EACzB,4BAA4B,EAG5B,8BAA8B,EAG9B,iBAAiB,EACjB,mBAAmB,EAGnB,2BAA2B,EAG3B,2BAA2B,EAG3B,4BAA4B,EAG5B,yBAAyB,EAGzB,6BAA6B,EAG7B,+BAA+B,EAC/B,mCAAmC,EAGnC,yBAAyB,EAGzB,2BAA2B,EAG3B,mCAAmC,EACnC,yBAAyB,EACzB,iCAAiC,EACjC,iCAAiC,EACjC,qCAAqC,EAGrC,yBAAyB,EAGzB,yBAAyB,EACzB,gCAAgC,EAChC,6BAA6B,EAC7B,gCAAgC,EAGhC,uBAAuB,EACvB,uBAAuB,EACvB,6BAA6B,EAG7B,2BAA2B,EAG3B,iBAAiB,EAGjB,0BAA0B,EAC1B,0BAA0B,EAG1B,iCAAiC,EAGjC,0BAA0B,EAC1B,8BAA8B,EAG9B,iCAAiC,EAGjC,UAAU,CACF,CAAA;AAEV,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAA"}