@hearthlog/runtime 0.0.0-stage → 0.1.0

package/src/db/kv.ts

@@ -0,0 +1,33 @@
+import { openDB, type IDBPDatabase } from 'idb';
+
+const DB_NAME = 'kv-store';
+const STORE_NAME = 'key-value';
+
+let dbPromise: Promise<IDBPDatabase<unknown>> | null = null;
+
+function getDb(): Promise<IDBPDatabase<unknown>> {
+    if (!dbPromise) {
+        dbPromise = openDB(DB_NAME, 1, {
+            upgrade(db) {
+                db.createObjectStore(STORE_NAME);
+            },
+        });
+    }
+    return dbPromise;
+}
+
+export async function get<T>(key: string): Promise<T | null> {
+    const db = await getDb();
+    const value = await db.get(STORE_NAME, key);
+    return value as T | null;
+}
+
+export async function set(key: string, value: unknown): Promise<void> {
+    const db = await getDb();
+    await db.put(STORE_NAME, value, key);
+}
+
+export async function del(key: string): Promise<void> {
+    const db = await getDb();
+    await db.delete(STORE_NAME, key);
+}

package/src/db/local-statistics.ts

@@ -0,0 +1,106 @@
+import { db } from './index.js';
+import { createKyselyRawSqliteExecutor, type RawSqliteExecutor } from './raw-browser.js';
+
+export interface LocalSqliteStats {
+    allocatedBytes: number;
+    occupiedBytes: number;
+    reusableBytes: number;
+    pageSize: number;
+    pageCount: number;
+    freePageCount: number;
+    schemaVersion: number;
+    sqliteVersion: string;
+    tableCount: number;
+    indexCount: number;
+    activeLog: {
+        eventCount: number;
+        pendingOperationCount: number;
+    } | null;
+}
+
+const localExecutor = createKyselyRawSqliteExecutor(db);
+
+/** File-wide page figures and SQL-scoped counts for the selected tenant/log. */
+export async function loadLocalSqliteStats(
+    executor: RawSqliteExecutor = localExecutor,
+): Promise<LocalSqliteStats> {
+    // SQLocal labels a bare `PRAGMA page_size` result with its value (for
+    // example "8192"), so use SQLite's table-valued read-only PRAGMAs.
+    const rows = await executor.query<{
+        page_count: number | string;
+        page_size: number | string;
+        freelist_count: number | string;
+        user_version: number | string;
+        sqlite_version: string;
+        tables: number | string;
+        indexes: number | string;
+    }>(`
+        SELECT sqlite_version() AS sqlite_version, pages.page_count, sizes.page_size, free.freelist_count, versions.user_version,
+            (SELECT COUNT(*) FROM sqlite_schema
+                WHERE type = 'table' AND name NOT LIKE 'sqlite_%') AS tables,
+            (SELECT COUNT(*) FROM sqlite_schema WHERE type = 'index') AS indexes
+        FROM pragma_page_count AS pages
+        CROSS JOIN pragma_page_size AS sizes
+        CROSS JOIN pragma_freelist_count AS free
+        CROSS JOIN pragma_user_version AS versions
+    `);
+
+    const pageCount = Number(rows[0]?.page_count ?? 0);
+    const pageSize = Number(rows[0]?.page_size ?? 0);
+    const freePageCount = Number(rows[0]?.freelist_count ?? 0);
+    const allocatedBytes = pageCount * pageSize;
+    const reusableBytes = freePageCount * pageSize;
+
+    let activeLog: LocalSqliteStats['activeLog'] = null;
+    try {
+        const rows = await executor.query<{
+            event_count: number;
+            pending_operation_count: number;
+        }>(`
+            SELECT
+                (SELECT COUNT(*) FROM raw_events AS events
+                    WHERE events.tenant_id = context.tenant_id
+                      AND events.log_id = context.log_id) AS event_count,
+                (SELECT COUNT(*) FROM outbox_operations AS operations
+                    WHERE operations.tenant_id = context.tenant_id
+                      AND operations.log_id = context.log_id
+                      AND operations.status IN ('pending', 'syncing', 'failed', 'needs_attention')) AS pending_operation_count
+            FROM active_context AS context
+            WHERE context.id = 1
+        `);
+        if (rows[0]) {
+            activeLog = {
+                eventCount: Number(rows[0].event_count),
+                pendingOperationCount: Number(rows[0].pending_operation_count),
+            };
+        }
+    } catch {
+        // The file remains inspectable before a log is selected or migration finishes.
+    }
+
+    return {
+        allocatedBytes,
+        occupiedBytes: Math.max(0, allocatedBytes - reusableBytes),
+        reusableBytes,
+        pageSize,
+        pageCount,
+        freePageCount,
+        schemaVersion: Number(rows[0]?.user_version ?? 0),
+        sqliteVersion: String(rows[0]?.sqlite_version ?? 'unknown'),
+        tableCount: Number(rows[0]?.tables ?? 0),
+        indexCount: Number(rows[0]?.indexes ?? 0),
+        activeLog,
+    };
+}
+
+export function formatSqliteBytes(bytes: number): string {
+    if (bytes < 1024) return `${bytes} B`;
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let value = bytes;
+    let unit = -1;
+    do {
+        value /= 1024;
+        unit += 1;
+    } while (value >= 1024 && unit < units.length - 1);
+    return `${value >= 100 || Number.isInteger(value) ? value.toFixed(0) : value.toFixed(1)} ${units[unit]}`;
+}

package/src/db/module-projections.ts

@@ -0,0 +1,46 @@
+/**
+ * The projection ledger: which version of each module's read model the local
+ * database holds. A module raises `projectionVersion` in its manifest when its
+ * tables or their meaning change; the next load rebuilds from raw events.
+ *
+ * A database that predates the ledger (schema 41) holds every module's tables
+ * at the baseline, version 1.
+ */
+
+import { MODULE_ENTITY_DEFINITIONS, MODULE_PROJECTIONS } from '#generated/modules';
+
+export const BASELINE_PROJECTION_VERSION = 1;
+
+export interface ProjectionRow {
+    module_id: string;
+    projection_version: number;
+}
+
+/** The modules a tenant runs (at least one enabled feature) and the version each should have. */
+export function currentProjections(features: ReadonlySet<string>): Array<{ module: string; version: number }> {
+    return MODULE_PROJECTIONS
+        .filter((projection) => projection.features.some((feature) => features.has(feature)))
+        .map(({ module, version }) => ({ module, version }));
+}
+
+/** Modules whose stored projection differs from the running code; a missing row counts as the baseline. */
+export function staleModules(
+    stored: readonly ProjectionRow[],
+    current: ReadonlyArray<{ module: string; version: number }>,
+): string[] {
+    const versions = new Map(stored.map((row) => [row.module_id, row.projection_version]));
+    return current
+        .filter(({ module, version }) => (versions.get(module) ?? BASELINE_PROJECTION_VERSION) !== version)
+        .map(({ module }) => module);
+}
+
+/** The projection tables of the named modules: those of the entities of the features each module owns. */
+export function moduleTables(modules: readonly string[]): string[] {
+    const features = new Set(MODULE_PROJECTIONS.filter(({ module }) => modules.includes(module)).flatMap((projection) => projection.features));
+    return MODULE_ENTITY_DEFINITIONS.filter((definition) => features.has(definition.feature)).map((definition) => definition.table);
+}
+
+/** Every module's projection tables (the core's own tables are not among them). */
+export function allModuleTables(): string[] {
+    return moduleTables(MODULE_PROJECTIONS.map(({ module }) => module));
+}

package/src/db/raw-browser.ts

@@ -0,0 +1,361 @@
+import { sql, type Kysely } from 'kysely';
+import { db, type Database } from './index.js';
+import { tenant } from '@hearthlog/contracts/tenant/config';
+
+export const RAW_SQLITE_PAGE_SIZES = [20, 50, 100] as const;
+export const DEFAULT_RAW_SQLITE_PAGE_SIZE = 50;
+
+export type RawSqlitePageSize = (typeof RAW_SQLITE_PAGE_SIZES)[number];
+export type RawSqliteSortDirection = 'asc' | 'desc';
+
+export interface RawSqliteExecutor {
+    query<Row extends Record<string, unknown>>(statement: string): Promise<Row[]>;
+}
+
+export interface RawSqliteTable {
+    name: string;
+}
+
+export interface RawSqliteColumn {
+    name: string;
+    dataType: string;
+    notNull: boolean;
+    defaultValue: unknown;
+    primaryKeyPosition: number;
+}
+
+export interface RawSqliteTablePage {
+    tables: RawSqliteTable[];
+    tableName: string | null;
+    columns: RawSqliteColumn[];
+    rows: Record<string, unknown>[];
+    totalRows: number;
+    currentPage: number;
+    pageSize: RawSqlitePageSize;
+    totalPages: number;
+    sortField: string | null;
+    sortDirection: RawSqliteSortDirection;
+}
+
+export type RawSqliteValuePresentation = {
+    kind: 'null' | 'blob' | 'scalar';
+    text: string;
+};
+
+type SqliteTableRow = {
+    name: string;
+};
+
+type SqliteColumnRow = {
+    cid: number;
+    name: string;
+    type: string;
+    notnull: number;
+    dflt_value: unknown;
+    pk: number;
+};
+
+type ActiveScope = {
+    tenantId: string;
+    logId: string;
+};
+
+const localExecutor = createKyselyRawSqliteExecutor(db);
+
+export function createKyselyRawSqliteExecutor(
+    database: Kysely<Database>,
+): RawSqliteExecutor {
+    return {
+        async query<Row extends Record<string, unknown>>(
+            statement: string,
+        ): Promise<Row[]> {
+            const result = await sql.raw<Row>(statement).execute(database);
+            return [...result.rows];
+        },
+    };
+}
+
+export function quoteRawSqliteIdentifier(identifier: string): string {
+    return `"${identifier.replace(/"/g, '""')}"`;
+}
+
+export function parseRawSqlitePage(value: string | number | null | undefined): number {
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : 1;
+}
+
+export function parseRawSqlitePageSize(
+    value: string | number | null | undefined,
+): RawSqlitePageSize {
+    const parsed = Number(value);
+    return RAW_SQLITE_PAGE_SIZES.includes(parsed as RawSqlitePageSize)
+        ? (parsed as RawSqlitePageSize)
+        : DEFAULT_RAW_SQLITE_PAGE_SIZE;
+}
+
+export function parseRawSqliteSortDirection(
+    value: string | number | null | undefined,
+): RawSqliteSortDirection {
+    return String(value).toLowerCase() === 'desc' ? 'desc' : 'asc';
+}
+
+export function parseRawSqliteSortField(
+    value: string | number | null | undefined,
+    columns?: ReadonlyArray<Pick<RawSqliteColumn, 'name'>> | null,
+): string | null {
+    const trimmed = String(value ?? '').trim();
+    if (!trimmed) return null;
+    if (columns && !columns.some((column) => column.name === trimmed)) {
+        return null;
+    }
+    return trimmed;
+}
+
+export async function listRawSqliteTables(
+    executor: RawSqliteExecutor = localExecutor,
+    allowedTableNames?: ReadonlySet<string>,
+): Promise<RawSqliteTable[]> {
+    const rows = await executor.query<SqliteTableRow>(`
+        SELECT name
+        FROM sqlite_schema
+        WHERE type = 'table'
+          AND name NOT LIKE 'sqlite_%'
+        ORDER BY name COLLATE NOCASE, name
+    `);
+
+    const visibleTableNames = allowedTableNames
+        ?? await tenantVisibleTableNames(executor);
+    return rows
+        .filter(({ name }) => visibleTableNames.has(name))
+        .map(({ name }) => ({ name }));
+}
+
+export async function loadRawSqliteTablePage(
+    input: {
+        tableName?: string | null;
+        page?: string | number | null;
+        pageSize?: string | number | null;
+        sort?: string | null;
+        direction?: string | number | null;
+    },
+    executor: RawSqliteExecutor = localExecutor,
+    allowedTableNames?: ReadonlySet<string>,
+): Promise<RawSqliteTablePage> {
+    const tables = await listRawSqliteTables(executor, allowedTableNames);
+    const selectedTable = tables.find((table) => table.name === input.tableName)
+        ?? tables[0]
+        ?? null;
+    const pageSize = parseRawSqlitePageSize(input.pageSize);
+
+    if (!selectedTable) {
+        return {
+            tables,
+            tableName: null,
+            columns: [],
+            rows: [],
+            totalRows: 0,
+            currentPage: 1,
+            pageSize,
+            totalPages: 1,
+            sortField: null,
+            sortDirection: 'asc',
+        };
+    }
+
+    const tablePage = await readRawSqliteTablePage(
+        {
+            tableName: selectedTable.name,
+            page: input.page,
+            pageSize,
+            sort: input.sort,
+            direction: input.direction,
+        },
+        executor,
+        tables,
+        allowedTableNames,
+    );
+
+    return {
+        tables,
+        ...tablePage,
+    };
+}
+
+export async function readRawSqliteTablePage(
+    input: {
+        tableName: string;
+        page?: string | number | null;
+        pageSize?: string | number | null;
+        sort?: string | null;
+        direction?: string | number | null;
+    },
+    executor: RawSqliteExecutor = localExecutor,
+    knownTables?: RawSqliteTable[],
+    allowedTableNames?: ReadonlySet<string>,
+): Promise<Omit<RawSqliteTablePage, 'tables'>> {
+    const visibleTableNames = allowedTableNames
+        ?? await tenantVisibleTableNames(executor);
+    const tables = (knownTables ?? await listRawSqliteTables(executor, visibleTableNames))
+        .filter(({ name }) => visibleTableNames.has(name));
+    if (!tables.some((table) => table.name === input.tableName)) {
+        throw new Error(`Unknown local SQLite table "${input.tableName}"`);
+    }
+
+    const tableIdentifier = quoteRawSqliteIdentifier(input.tableName);
+    const columnRows = await executor.query<SqliteColumnRow>(
+        `PRAGMA table_info(${tableIdentifier})`,
+    );
+    const columns = columnRows
+        .sort((left, right) => Number(left.cid) - Number(right.cid))
+        .map((column) => ({
+            name: column.name,
+            dataType: column.type || 'ANY',
+            notNull: Boolean(column.notnull),
+            defaultValue: column.dflt_value,
+            primaryKeyPosition: Number(column.pk),
+        }));
+
+    const scope = await activeScope(executor);
+    const isScoped = columns.some((column) => column.name === 'tenant_id')
+        && columns.some((column) => column.name === 'log_id');
+    if (isScoped && !scope) {
+        throw new Error('No active tenant context is available for this table.');
+    }
+    const where = isScoped
+        ? ` WHERE ${quoteRawSqliteIdentifier('tenant_id')} = ${quoteRawSqliteLiteral(scope!.tenantId)}\n` +
+            `  AND ${quoteRawSqliteIdentifier('log_id')} = ${quoteRawSqliteLiteral(scope!.logId)}`
+        : '';
+
+    const countRows = await executor.query<{ count: number | bigint | string }>(
+        `SELECT COUNT(*) AS count FROM ${tableIdentifier}${where}`,
+    );
+    const totalRows = Number(countRows[0]?.count ?? 0);
+    const pageSize = parseRawSqlitePageSize(input.pageSize);
+    const totalPages = Math.max(1, Math.ceil(totalRows / pageSize));
+    const currentPage = Math.min(parseRawSqlitePage(input.page), totalPages);
+    const offset = (currentPage - 1) * pageSize;
+    const sortField = parseRawSqliteSortField(input.sort, columns);
+    const sortDirection = parseRawSqliteSortDirection(input.direction);
+    const primaryKeyColumns = columns
+        .filter((column) => column.primaryKeyPosition > 0)
+        .sort((left, right) => left.primaryKeyPosition - right.primaryKeyPosition);
+    const orderByParts: string[] = [];
+    if (sortField) {
+        orderByParts.push(`${quoteRawSqliteIdentifier(sortField)} ${sortDirection.toUpperCase()}`);
+    }
+    const defaultOrderBy = primaryKeyColumns.length > 0
+        ? primaryKeyColumns
+            .map((column) => `${quoteRawSqliteIdentifier(column.name)} ASC`)
+            .join(', ')
+        : '_rowid_ ASC';
+    // The sort column doubles as the tiebreak when it is unique-ish, but a
+    // stable PK/_rowid_ tiebreak keeps pagination deterministic for duplicate
+    // values (e.g. many rows sharing the same amount or status).
+    if (!sortField || !defaultOrderBy.startsWith(`${quoteRawSqliteIdentifier(sortField)} `)) {
+        orderByParts.push(defaultOrderBy);
+    }
+    const orderBy = orderByParts.join(', ');
+    const rows = await executor.query<Record<string, unknown>>(`
+        SELECT *
+        FROM ${tableIdentifier}
+        ${where}
+        ORDER BY ${orderBy}
+        LIMIT ${pageSize}
+        OFFSET ${offset}
+    `);
+
+    return {
+        tableName: input.tableName,
+        columns,
+        rows,
+        totalRows,
+        currentPage,
+        pageSize,
+        totalPages,
+        sortField,
+        sortDirection,
+    };
+}
+
+async function tenantVisibleTableNames(
+    executor: RawSqliteExecutor,
+): Promise<ReadonlySet<string>> {
+    const visible = new Set(tenant.approvedEntities.tables);
+    if (!tenant.dynamicEntities) return visible;
+
+    const scope = await activeScope(executor);
+    if (!scope) return visible;
+    try {
+        const rows = await executor.query<{ table_name: string }>(`
+            SELECT table_name
+            FROM "entity_type_definitions"
+            WHERE tenant_id = ${quoteRawSqliteLiteral(scope.tenantId)}
+              AND log_id = ${quoteRawSqliteLiteral(scope.logId)}
+              AND is_archived = 0
+        `);
+        for (const row of rows) visible.add(row.table_name);
+    } catch {
+        // A legacy/incomplete database may not have dynamic definitions yet.
+        // Static approved tables remain available in that case.
+    }
+    return visible;
+}
+
+async function activeScope(executor: RawSqliteExecutor): Promise<ActiveScope | null> {
+    try {
+        const rows = await executor.query<{ tenant_id: string; log_id: string }>(`
+            SELECT tenant_id, log_id
+            FROM "active_context"
+            WHERE id = 1
+            LIMIT 1
+        `);
+        const row = rows[0];
+        if (!row?.tenant_id || !row.log_id) return null;
+        return { tenantId: row.tenant_id, logId: row.log_id };
+    } catch {
+        return null;
+    }
+}
+
+export function quoteRawSqliteLiteral(value: string): string {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+
+export function presentRawSqliteValue(value: unknown): RawSqliteValuePresentation {
+    if (value === null || value === undefined) {
+        return { kind: 'null', text: 'NULL' };
+    }
+
+    if (value instanceof ArrayBuffer) {
+        return { kind: 'blob', text: formatBlobSize(value.byteLength) };
+    }
+
+    if (ArrayBuffer.isView(value)) {
+        return { kind: 'blob', text: formatBlobSize(value.byteLength) };
+    }
+
+    if (typeof value === 'string') {
+        return { kind: 'scalar', text: value };
+    }
+
+    if (
+        typeof value === 'number'
+        || typeof value === 'bigint'
+        || typeof value === 'boolean'
+    ) {
+        return { kind: 'scalar', text: String(value) };
+    }
+
+    try {
+        return {
+            kind: 'scalar',
+            text: JSON.stringify(value) ?? String(value),
+        };
+    } catch {
+        return { kind: 'scalar', text: String(value) };
+    }
+}
+
+function formatBlobSize(byteLength: number): string {
+    return `<BLOB ${byteLength} ${byteLength === 1 ? 'byte' : 'bytes'}>`;
+}

package/src/db/read-repositories.ts

@@ -0,0 +1,29 @@
+import { createStandardRepositories } from '#generated/standard-db';
+import type { ReadModelSession } from './read-session.js';
+import { runActiveRead } from '../runtime/read-coordinator.js';
+import { createCalendarRepository } from './calendar.js';
+import { createEntityRepository } from './entities.js';
+import { createHistoryRepository } from './history.js';
+import { createModuleRepositories } from '#generated/module-repositories';
+
+function createReadRepositories(session: ReadModelSession) {
+    return {
+        records: createStandardRepositories(session),
+        ...createModuleRepositories(session),
+        calendar: createCalendarRepository(session),
+        history: createHistoryRepository(session),
+        entities: createEntityRepository(session),
+    };
+}
+
+export type ReadRepositories = ReturnType<typeof createReadRepositories>;
+
+/**
+ * Executes ordinary application reads against the currently active database view.
+ * Schema selection, snapshot leasing, and tenant/log scoping stay inside the data layer.
+ */
+export function queryDatabase<T>(
+    callback: (repositories: ReadRepositories) => Promise<T>,
+): Promise<T> {
+    return runActiveRead((session) => callback(createReadRepositories(session)));
+}

package/src/db/read-session.ts

@@ -0,0 +1,47 @@
+import { sql, type Kysely, type QueryResult, type RawBuilder, type SelectQueryBuilder, type SqlBool } from 'kysely';
+import type { EntityTypeDefinitionTable } from './index.js';
+import type { EntityDatabaseTables } from '#generated/schema';
+import { qualifiedIdentifier } from '../event/projection-builder.js';
+
+export type ReadScope = { tenantId: string; logId: string };
+export type ReadView = { effectiveNow: string };
+
+export interface ReadModelDatabase extends EntityDatabaseTables {
+    entity_type_definitions: EntityTypeDefinitionTable;
+}
+
+/** Read-model queries are always scoped to the selected tenant and log. */
+export interface ReadModelSession {
+    readonly scope: ReadScope;
+    readonly view: ReadView;
+    selectFrom<TB extends keyof ReadModelDatabase>(table: TB): SelectQueryBuilder<ReadModelDatabase, TB, {}>;
+    table(name: string): RawBuilder<unknown>;
+    execute<T>(query: RawBuilder<T>): Promise<QueryResult<T>>;
+}
+
+export function createReadModelSession(
+    database: Kysely<ReadModelDatabase>,
+    options: { schema: string; scope: ReadScope; view: ReadView },
+): ReadModelSession {
+    const scopedDb = database.withSchema(options.schema);
+    const { scope } = options;
+
+    function scopedSelect<TB extends keyof ReadModelDatabase>(table: TB): SelectQueryBuilder<ReadModelDatabase, TB, {}> {
+        const scoped = scopedDb.selectFrom(table) as SelectQueryBuilder<ReadModelDatabase, TB, {}>;
+        return scoped
+            .where(sql<SqlBool>`${sql.ref(`${table}.tenant_id`)} = ${scope.tenantId}`)
+            .where(sql<SqlBool>`${sql.ref(`${table}.log_id`)} = ${scope.logId}`);
+    }
+
+    return {
+        scope,
+        view: options.view,
+        selectFrom: scopedSelect,
+        table(name) {
+            return sql`(SELECT * FROM ${sql.raw(qualifiedIdentifier(options.schema, name))} WHERE tenant_id = ${scope.tenantId} AND log_id = ${scope.logId})`;
+        },
+        execute(query) {
+            return query.execute(database);
+        },
+    };
+}