@hearthlog/runtime 0.0.0-stage → 0.1.0

package/src/db/dynamic-ddl.ts

@@ -0,0 +1,127 @@
+/**
+ * Dynamic DDL Generator
+ * 
+ * Generates SQL DDL for dynamic entity tables at runtime.
+ */
+
+import type { DynamicFieldDefinition } from '../event/meta-entity-types.js';
+import { qualifiedIdentifier, quoteIdentifier } from '../event/projection-builder.js';
+
+/**
+ * Entity type record from the entity_type_definitions table
+ */
+export interface EntityTypeRecord {
+    tenant_id: string;
+    log_id: string;
+    id: string;
+    name: string;
+    display_name: string;
+    table_name: string;
+    fields_json: string;
+    calendar_json: string | null;
+    is_archived: number;
+    created_at: string;
+    updated_at: string;
+}
+
+// ============================================================================
+// DDL generation
+// ============================================================================
+
+/**
+ * Map DynamicFieldType to SQLite type
+ */
+function getSQLiteType(type: DynamicFieldDefinition['type']): string {
+    switch (type) {
+        case 'number':
+            return 'REAL';
+        case 'boolean':
+            return 'INTEGER'; // SQLite uses 0/1 for booleans
+        case 'string':
+        case 'reference':
+        case 'datetime':
+        default:
+            return 'TEXT';
+    }
+}
+
+/**
+ * Convert a default value to SQL-safe format
+ */
+function toSQLDefault(value: string | number | boolean | null | undefined): string {
+    if (value === null || value === undefined) {
+        return 'NULL';
+    }
+    if (typeof value === 'boolean') {
+        return value ? '1' : '0';
+    }
+    if (typeof value === 'number') {
+        return String(value);
+    }
+    // Only allow the two deterministic defaults emitted by the entity editor.
+    if (/^(?:date|datetime)\('now'\)$/.test(value)) {
+        return value;
+    }
+    // String value - escape quotes
+    return `'${value.replace(/'/g, "''")}'`;
+}
+
+/**
+ * Parse the stored field definitions defensively: a malformed row must not
+ * crash table creation with an opaque SyntaxError.
+ */
+function parseStoredFields(record: EntityTypeRecord): DynamicFieldDefinition[] {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(record.fields_json);
+    } catch {
+        throw new Error(
+            `Dynamic entity "${record.name}" has malformed field definitions`,
+        );
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error(
+            `Dynamic entity "${record.name}" has malformed field definitions`,
+        );
+    }
+    return parsed as DynamicFieldDefinition[];
+}
+
+/**
+ * Generate DDL for a dynamic entity table
+ */
+export function generateDynamicTableDDL(record: EntityTypeRecord, schema?: string): string {
+    const fields = parseStoredFields(record);
+
+    const columns = fields.map(f => {
+        const sqlType = getSQLiteType(f.type);
+        const nullable = f.required ? ' NOT NULL' : '';
+        const defaultVal = f.default !== undefined ? ` DEFAULT ${toSQLDefault(f.default)}` : '';
+        return `        ${quoteIdentifier(f.name)} ${sqlType}${nullable}${defaultVal}`;
+    });
+
+    return `
+CREATE TABLE IF NOT EXISTS ${qualifiedIdentifier(schema, record.table_name)} (
+    "tenant_id" TEXT NOT NULL,
+    "log_id" TEXT NOT NULL,
+    "id" TEXT NOT NULL,
+${columns.join(',\n')},
+    "created_at" TEXT DEFAULT (datetime('now')),
+    "updated_at" TEXT DEFAULT (datetime('now')),
+    PRIMARY KEY ("tenant_id", "log_id", "id")
+);`.trim();
+}
+
+/**
+ * Generate DDL to add a new column to an existing table
+ */
+export function generateAddColumnDDL(
+    tableName: string,
+    field: DynamicFieldDefinition,
+    schema?: string,
+): string {
+    const sqlType = getSQLiteType(field.type);
+    const defaultVal = field.default !== undefined ? ` DEFAULT ${toSQLDefault(field.default)}` : '';
+    // Note: SQLite doesn't support NOT NULL on ALTER TABLE ADD COLUMN without a default
+    return `ALTER TABLE ${qualifiedIdentifier(schema, tableName)} ADD COLUMN ${quoteIdentifier(field.name)} ${sqlType}${defaultVal};`;
+}

package/src/db/entities.ts

@@ -0,0 +1,208 @@
+import { sql } from 'kysely';
+import { normalizeCalendarSources, serializeCalendarConfig } from '@hearthlog/contracts/calendar/config';
+import type { EntityTypeRecord } from './dynamic-ddl.js';
+import { ENTITY_DEFINITIONS, getEntityDefinition, getPayloadKey } from '@hearthlog/contracts/event/entity-definitions';
+import { parseEntityFields } from '../event/dynamic-entities.js';
+import type { DynamicFieldDefinition } from '../event/meta-entity-types.js';
+import { quoteIdentifier } from '../event/projection-builder.js';
+import type { ReadModelSession } from './read-session.js';
+import { withTimeout } from '../utils/async.js';
+import { tenant } from '@hearthlog/contracts/tenant/config';
+
+const DB_TIMEOUT_MS = 5000;
+
+export type EntityTypeWithStatic = EntityTypeRecord & { is_static?: boolean };
+
+export interface EntityQuery {
+    search: string;
+    pageSize: number;
+    requestedPage: number;
+    sortField: string | null;
+    sortDirection: 'asc' | 'desc';
+}
+
+export function createEntityRepository(session: ReadModelSession) {
+    const { scope } = session;
+
+    async function getDynamicDefinition(name: string): Promise<EntityTypeRecord | null> {
+        const record = await session.selectFrom('entity_type_definitions')
+            .selectAll()
+            .where('name', '=', name)
+            .where('is_archived', '=', 0)
+            .executeTakeFirst();
+        return record as EntityTypeRecord | undefined ?? null;
+    }
+
+    function staticRecord(name: string): EntityTypeWithStatic | null {
+        const definition = getEntityDefinition(name);
+        if (!definition) return null;
+        return {
+            tenant_id: scope.tenantId,
+            log_id: scope.logId,
+            id: definition.name,
+            name: definition.name,
+            display_name: definition.displayName ?? titleCase(definition.name),
+            table_name: definition.table,
+            fields_json: JSON.stringify(definition.fields),
+            calendar_json: serializeCalendarConfig(
+                normalizeCalendarSources(definition.calendar),
+            ),
+            is_archived: 0,
+            created_at: session.view.effectiveNow,
+            updated_at: session.view.effectiveNow,
+            is_static: true,
+        };
+    }
+
+    async function getEntityType(name: string): Promise<{
+        record: EntityTypeWithStatic;
+        fields: DynamicFieldDefinition[];
+    } | null> {
+        // Static names are reserved and take precedence over dynamic records.
+        // Check the tenant approval before touching the projection so a direct
+        // URL/reference lookup cannot query a disabled feature's table.
+        const definition = getEntityDefinition(name);
+        if (definition) {
+            if (!tenant.approvedEntities.entityNames.has(name)) return null;
+            const record = staticRecord(name);
+            if (!record) return null;
+            return {
+                record,
+                fields: definition.fields.map((field) => ({
+                    ...field,
+                    payloadKey: getPayloadKey(field),
+                })) as DynamicFieldDefinition[],
+            };
+        }
+
+        if (!tenant.dynamicEntities) return null;
+        const dynamic = await getDynamicDefinition(name);
+        if (dynamic) {
+            return {
+                record: dynamic,
+                fields: parseEntityFields(dynamic),
+            };
+        }
+        return null;
+    }
+
+    async function loadReferenceOptions(entityName: string): Promise<Array<{ id: string; label: string }>> {
+        const target = await getEntityType(entityName);
+        if (!target) return [];
+        const displayField = ['name', 'title', 'label'].find((candidate) =>
+            target.fields.some((field) => field.name === candidate));
+        const columns = ['id', displayField].filter(Boolean) as string[];
+        const orderBy = displayField
+            ? sql`ORDER BY ${sql.raw(quoteIdentifier(displayField))} ASC`
+            : sql``;
+        const rows = await withTimeout(
+            session.execute(sql<Record<string, unknown>>`
+                SELECT ${sql.raw(columns.map(quoteIdentifier).join(', '))}
+                FROM ${session.table(target.record.table_name)}
+                ${orderBy}
+                LIMIT 100
+            `),
+            DB_TIMEOUT_MS,
+            `Reference query for ${entityName} timed out`,
+        );
+        return rows.rows.map((row) => ({
+            id: String(row.id),
+            label: String(row.name ?? row.title ?? row.label ?? row.id),
+        }));
+    }
+
+    return {
+        async getEntityCatalog(): Promise<EntityTypeWithStatic[]> {
+            const dynamic = await withTimeout(
+                session.selectFrom('entity_type_definitions')
+                    .selectAll()
+                    .where('is_archived', '=', 0)
+                    .orderBy('display_name', 'asc')
+                    .execute(),
+                DB_TIMEOUT_MS,
+                'Entity catalog query timed out',
+            );
+            // Feature scoping: only entities the tenant is approved for are
+            // part of the catalog (dynamic types are per-log and always shown).
+            const approvedStatic = ENTITY_DEFINITIONS.filter(
+                (definition) => tenant.approvedEntities.entityNames.has(definition.name),
+            ).map((definition) => staticRecord(definition.name)!);
+            return [
+                ...approvedStatic,
+                ...(tenant.dynamicEntities ? dynamic as EntityTypeRecord[] : []),
+            ].sort((left, right) => left.display_name.localeCompare(right.display_name));
+        },
+
+        getEntityType,
+
+        async queryEntities(entityName: string, query: EntityQuery) {
+            const entityType = await getEntityType(entityName);
+            if (!entityType) return null;
+            const searchableColumns = [...new Set(['id', ...entityType.fields.map((field) => field.name)])];
+            const where = buildSearchWhere(searchableColumns, query.search);
+            const countRows = await withTimeout(
+                session.execute(sql<{ count: number | string }>`
+                    SELECT COUNT(*) AS count
+                    FROM ${session.table(entityType.record.table_name)}
+                    ${where}
+                `),
+                DB_TIMEOUT_MS,
+                `Count query for ${entityName} timed out`,
+            );
+            const totalRows = Number(countRows.rows[0]?.count ?? 0);
+            const totalPages = Math.max(1, Math.ceil(totalRows / query.pageSize));
+            const currentPage = Math.min(query.requestedPage, totalPages);
+            const offset = (currentPage - 1) * query.pageSize;
+            const sortableFields = new Set(entityType.fields.map((field) => field.name));
+            const sortField = query.sortField && sortableFields.has(query.sortField)
+                ? query.sortField
+                : null;
+            const orderBy = sortField
+                ? sql`ORDER BY ${sql.raw(quoteIdentifier(sortField))} ${sql.raw(query.sortDirection.toUpperCase())}`
+                : sql`ORDER BY ${sql.raw(quoteIdentifier('id'))} ASC`;
+            const rows = await withTimeout(
+                session.execute(sql<Record<string, unknown>>`
+                    SELECT *
+                    FROM ${session.table(entityType.record.table_name)}
+                    ${where}
+                    ${orderBy}
+                    LIMIT ${query.pageSize}
+                    OFFSET ${offset}
+                `),
+                DB_TIMEOUT_MS,
+                `Query for ${entityName} timed out`,
+            );
+            const referenceOptionEntries = await Promise.all(
+                entityType.fields
+                    .filter((field) => field.type === 'reference' && field.referenceTo)
+                    .map(async (field) => [field.name, await loadReferenceOptions(field.referenceTo!)] as const),
+            );
+            return {
+                entityType: entityType.record,
+                fields: entityType.fields,
+                entities: rows.rows,
+                referenceOptions: Object.fromEntries(referenceOptionEntries),
+                referencedBy: {},
+                search: query.search,
+                sortField,
+                sortDirection: query.sortDirection,
+                currentPage,
+                pageSize: query.pageSize,
+                totalRows,
+                totalPages,
+            };
+        },
+    };
+}
+
+function buildSearchWhere(columns: string[], search: string) {
+    if (!search) return sql``;
+    const pattern = `%${search.replace(/[\\%_]/g, (character) => `\\${character}`)}%`;
+    const clauses = columns.map((column) =>
+        sql`CAST(${sql.raw(quoteIdentifier(column))} AS TEXT) LIKE ${pattern} ESCAPE ${'\\'}`);
+    return sql`WHERE (${sql.join(clauses, sql` OR `)})`;
+}
+
+function titleCase(value: string): string {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}

package/src/db/history.ts

@@ -0,0 +1,194 @@
+import { sql } from 'kysely';
+import type { ReadModelSession } from './read-session.js';
+import { ENTITY_DEFINITIONS, getEventPrefix } from '@hearthlog/contracts/event/entity-definitions';
+import { FEATURES } from '@hearthlog/contracts/features/registry';
+import { visibleEventCondition } from '../event/queries.js';
+import { completeActionBoundary } from '../history/action-boundary.js';
+import type { ForkReview, HistoryEntry, HistoryItem, HistoryListOptions, HistoryPoint, HistoryRecord } from '../history/contracts.js';
+import { withTimeout } from '../utils/async.js';
+
+// Registry metadata, never user records. All activity selection and aggregation stays in SQL.
+const metadata = sql.join(ENTITY_DEFINITIONS.map(entity => sql`(
+    ${getEventPrefix(entity)}, ${entity.feature}, ${entity.displayName ?? entity.name.replace(/_/g, ' ')}, ${entity.table.replace(/_/g, ' ')}
+)`));
+const featureLabels = sql.join(FEATURES.map(feature => sql`(${feature.id}, ${feature.page?.label ?? feature.id})`));
+// Records without a name read as their main value, such as "Weight 81.2 kg";
+// entity definitions declare it (`summary`).
+const summarized = ENTITY_DEFINITIONS.filter((entity) => entity.summary);
+const summaries = summarized.length
+    ? sql`VALUES ${sql.join(summarized.map((entity) => sql`(${getEventPrefix(entity)}, ${entity.summary!.noun}, ${entity.summary!.key}, ${entity.summary!.unit})`))}`
+    : sql`SELECT NULL, NULL, NULL, NULL WHERE 0`;
+const order = sql`(version IS NULL) DESC, COALESCE(version, local_sequence) DESC, id DESC`;
+
+export function createHistoryRepository(session: ReadModelSession) {
+    const base = sql`
+        WITH raw_events AS (SELECT * FROM ${session.table('raw_events')}),
+        metadata(prefix, feature, entity_label, plural_label) AS (VALUES ${metadata}),
+        feature_labels(feature, label) AS (VALUES ${featureLabels}),
+        summaries(prefix, noun, key, unit) AS (${summaries}),
+        enriched AS (
+            SELECT raw_events.*, COALESCE(action_id, id) AS group_id,
+                metadata.feature, metadata.entity_label, metadata.plural_label,
+                CASE WHEN ${visibleEventCondition()} THEN 1 ELSE 0 END AS visible,
+                CASE WHEN log_version IS NOT NULL AND projection_state IN ('effective', 'restored_out')
+                    AND ${completeActionBoundary} THEN 1 ELSE 0 END AS complete,
+                (SELECT CAST(value AS TEXT) FROM raw_events AS prior, json_each(prior.payload)
+                    WHERE COALESCE(prior.entity_id, json_extract(prior.payload, '$.id'), prior.id)
+                        = COALESCE(raw_events.entity_id, json_extract(raw_events.payload, '$.id'), raw_events.id)
+                      AND key IN ('title', 'name', 'invoiceNumber', 'number', 'description', 'label', 'filename', 'fileName')
+                      AND json_each.type = 'text' AND trim(CAST(value AS TEXT)) != ''
+                      AND (prior.id = raw_events.id OR (prior.projection_state IN ('effective', 'restored_out')
+                        AND prior.is_tombstoned = 0 AND (
+                            (raw_events.log_version IS NOT NULL AND prior.log_version <= raw_events.log_version)
+                            OR (raw_events.log_version IS NULL AND prior.local_sequence <= raw_events.local_sequence))))
+                    ORDER BY (prior.id = raw_events.id) DESC, prior.log_version DESC, prior.local_sequence DESC,
+                        CASE key WHEN 'title' THEN 0 WHEN 'name' THEN 1 WHEN 'invoiceNumber' THEN 2 WHEN 'number' THEN 3
+                            WHEN 'description' THEN 4 ELSE 5 END
+                    LIMIT 1) AS record_label,
+                (SELECT noun || ' ' || printf('%g', json_extract(raw_events.payload, '$.' || key)) || unit FROM summaries
+                    WHERE substr(raw_events.type, 1, length(prefix)) = prefix
+                      AND json_type(raw_events.payload, '$.' || key) IN ('integer', 'real')) AS summary_label,
+                (SELECT lower(noun) FROM summaries WHERE substr(raw_events.type, 1, length(prefix)) = prefix) AS summary_noun,
+                (SELECT operation.last_error_message FROM outbox_operation_items AS item
+                    JOIN ${session.table('outbox_operations')} AS operation ON operation.id = item.operation_id
+                    WHERE item.event_id = raw_events.id AND operation.status = 'needs_attention'
+                    ORDER BY operation.updated_at DESC LIMIT 1) AS sync_error
+            FROM raw_events LEFT JOIN metadata ON substr(raw_events.type, 1, length(prefix)) = prefix
+        ), ranked AS (
+            SELECT *, ROW_NUMBER() OVER (PARTITION BY group_id
+                    ORDER BY log_version DESC, action_index DESC, local_sequence DESC, id DESC) AS rank,
+                COUNT(*) OVER (PARTITION BY group_id) AS member_count,
+                MAX(visible) OVER (PARTITION BY group_id) AS has_visible,
+                MAX(CASE WHEN sync_state IN ('conflicted', 'rejected') OR projection_state = 'excluded'
+                    OR sync_error IS NOT NULL THEN 1 ELSE 0 END) OVER (PARTITION BY group_id) AS attention,
+                MAX(COALESCE(rejection_detail, rejection_code, sync_error)) OVER (PARTITION BY group_id) AS issue,
+                MIN(log_version) OVER (PARTITION BY group_id) AS first_version
+            FROM enriched
+        ), actions AS (
+            SELECT id, group_id, type, timestamp, log_version AS version, local_sequence, feature, actor,
+                COALESCE(action_size, member_count) AS eventCount,
+                COALESCE(first_version - 1, 0) AS previousVersion,
+                CASE WHEN attention = 1 THEN 'attention' WHEN complete = 1 THEN 'ready' ELSE 'waiting' END AS status,
+                CASE WHEN attention = 1 THEN COALESCE(issue, 'Open sync issues to review this action.')
+                    WHEN complete = 1 THEN NULL
+                    WHEN log_version IS NULL THEN 'Saved on this device. Waiting to sync.'
+                    ELSE 'This action is still arriving. Wait for sync to finish.' END AS reason,
+                CASE WHEN COALESCE(action_size, member_count) > 1 THEN
+                    CASE WHEN record_label IS NOT NULL AND (
+                        SELECT COUNT(DISTINCT COALESCE(entity_id, json_extract(payload, '$.id'), id))
+                        FROM enriched AS member WHERE member.group_id = ranked.group_id
+                    ) = 1 THEN 'Edited ' || record_label
+                    WHEN (SELECT COUNT(DISTINCT type) FROM enriched AS member WHERE member.group_id = ranked.group_id) = 1
+                        THEN CASE WHEN type LIKE '%_ADDED' THEN 'Added ' WHEN type LIKE '%_REMOVED' THEN 'Removed ' ELSE 'Edited ' END
+                            || member_count || ' ' || COALESCE(plural_label, 'records')
+                    ELSE COALESCE((SELECT label FROM feature_labels WHERE feature_labels.feature = ranked.feature), 'Log') || ' action' END
+                WHEN type = 'WORKSPACE_RESTORED' THEN 'Restored log'
+                WHEN type = 'EVENTS_EXCISED' THEN 'Removed events'
+                WHEN type = 'EVENT_TOMBSTONED' THEN 'Undid a change'
+                ELSE CASE WHEN type LIKE '%_ADDED' THEN 'Added '
+                    WHEN type LIKE '%_UPDATED' THEN 'Edited '
+                    WHEN type LIKE '%_REMOVED' OR type LIKE '%_DELETED' THEN 'Removed '
+                    ELSE 'Changed ' END || COALESCE(record_label, summary_label, summary_noun, entity_label, lower(replace(type, '_', ' '))) END AS label
+            FROM ranked WHERE rank = 1 AND has_visible = 1
+        )`;
+
+    function execute<T>(query: import('kysely').RawBuilder<T>) {
+        return withTimeout(session.execute(query), 15_000, 'History could not be loaded. Try again.');
+    }
+
+    return {
+        async changes(entry: HistoryEntry): Promise<HistoryRecord[]> {
+            if (entry.status !== 'ready' || entry.version === null) throw new Error('Choose a complete synced action.');
+            const { readActionChanges } = await import('../history/point-snapshot.js');
+            return withTimeout(readActionChanges(entry.previousVersion, entry.version, session.scope), 30_000, 'Could not inspect this action. Try again.');
+        },
+        async list(options: HistoryListOptions = {}): Promise<HistoryItem[]> {
+            const search = options.search?.trim() ?? '';
+            const feature = options.feature ?? '';
+            const markers = search || feature ? [] : options.markers ?? [];
+            const marks = markers.length
+                ? sql`VALUES ${sql.join(markers.map(marker => sql`(${marker.key}, ${marker.version})`))}`
+                : sql`SELECT NULL, NULL WHERE 0`;
+            const { rows } = await execute<(Omit<HistoryEntry, 'copied'> & { kind: 'action'; copied: number })
+                | Extract<HistoryItem, { kind: 'marker' }>>(sql`${base}, filtered AS (
+                SELECT *, CASE WHEN date(timestamp / 1000, 'unixepoch', 'localtime') IS
+                        LAG(date(timestamp / 1000, 'unixepoch', 'localtime')) OVER (ORDER BY ${order})
+                        THEN 0 ELSE 1 END AS startsDay
+                FROM actions WHERE (${feature} = '' OR EXISTS (
+                    SELECT 1 FROM enriched AS member WHERE member.group_id = actions.group_id AND member.feature = ${feature}
+                )) AND (${search} = '' OR instr(lower(label), lower(${search})) > 0
+                    OR EXISTS (SELECT 1 FROM enriched AS member WHERE member.group_id = actions.group_id
+                        AND instr(lower(member.payload || ' ' || member.type), lower(${search})) > 0))
+            ), marks(marker_key, version) AS (${marks}),
+            items AS (
+                SELECT 'action' AS kind, id, NULL AS markerKey, label, timestamp, version, previousVersion, eventCount,
+                    feature, actor, status, reason, startsDay,
+                    CASE WHEN version IS NOT NULL AND version <= ${options.sourceVersion ?? -1} THEN 1 ELSE 0 END AS copied,
+                    CASE WHEN version IS NULL THEN 1 ELSE 0 END AS pending,
+                    COALESCE(version, local_sequence) * 2 AS position
+                FROM filtered
+                UNION ALL
+                -- A log that shares version v sits between action v and the one after it.
+                SELECT 'marker', 'marker:' || marker_key, marker_key, NULL, NULL, version, NULL, NULL,
+                    NULL, NULL, NULL, NULL, 0, 0, 0, version * 2 + 1 FROM marks
+            ), numbered AS (
+                SELECT *, ROW_NUMBER() OVER (ORDER BY pending DESC, position DESC, id DESC) AS row_number,
+                    COUNT(*) OVER () AS total
+                FROM items
+            ) SELECT * FROM numbered
+            WHERE row_number <= MAX(${options.limit ?? 60},
+                COALESCE((SELECT row_number FROM numbered WHERE id = ${options.through ?? ''}), 0) + 20)
+            ORDER BY row_number`);
+            return rows.map(row => row.kind === 'action' ? { ...row, copied: Boolean(row.copied) } : row);
+        },
+        /** The newest synced action, where Copy this log starts. */
+        async latest(): Promise<HistoryEntry | null> {
+            const { rows } = await execute<HistoryEntry>(sql`${base} SELECT *, 0 AS total, 0 AS startsDay FROM actions
+                WHERE status = 'ready' ORDER BY version DESC LIMIT 1`);
+            return rows[0] ?? null;
+        },
+        /** When the newest action happened, so the log map can end there. */
+        async newest(): Promise<number | null> {
+            const { rows } = await execute<{ newest: number | null }>(sql`${base} SELECT MAX(timestamp) AS newest FROM actions`);
+            return rows[0]?.newest ?? null;
+        },
+        /** Actions within a time span, newest first, for the log map's points. */
+        async points(since: number, until: number, limit = 3000): Promise<HistoryPoint[]> {
+            const { rows } = await execute<HistoryPoint>(sql`${base}
+                SELECT id, label, timestamp, version FROM actions WHERE timestamp >= ${since} AND timestamp <= ${until}
+                ORDER BY timestamp DESC, id DESC LIMIT ${limit}`);
+            return rows;
+        },
+        async get(selection: { id?: string; version?: number }): Promise<HistoryEntry | null> {
+            const { rows } = await execute<HistoryEntry>(sql`${base} SELECT *, 0 AS total, 0 AS startsDay FROM actions
+                WHERE ${selection.id ? sql`id = ${selection.id}` : sql`version = ${selection.version ?? -1}`} LIMIT 1`);
+            return rows[0] ?? null;
+        },
+        async review(targetVersion: number): Promise<ForkReview> {
+            const { rows } = await execute<ForkReview>(sql`${base}, later AS (
+                SELECT DISTINCT group_id FROM enriched WHERE log_version > ${targetVersion}
+                    AND projection_state IN ('effective', 'restored_out')
+            ), kept AS (
+                SELECT DISTINCT group_id FROM enriched WHERE log_version <= ${targetVersion}
+                    AND projection_state IN ('effective', 'restored_out')
+            ) SELECT (SELECT COUNT(*) FROM kept) AS keptActions, (SELECT COUNT(*) FROM later) AS laterActions,
+                COALESCE((SELECT group_concat(label, ', ') FROM (
+                    SELECT DISTINCT COALESCE(feature_labels.label, 'Other changes') AS label
+                    FROM enriched LEFT JOIN feature_labels ON feature_labels.feature = enriched.feature
+                    WHERE log_version > ${targetVersion} AND projection_state IN ('effective', 'restored_out') ORDER BY label
+                )), '') AS features,
+                COALESCE((SELECT MAX(log_version) FROM raw_events), 0) AS localHead`);
+            return rows[0];
+        },
+        async savedValues(id: string): Promise<HistoryRecord[]> {
+            const { rows } = await execute<{ key: string; label: string; fields: string }>(sql`${base}
+                SELECT member.id AS key, COALESCE(member.record_label, member.entity_label, member.type) AS label,
+                    (SELECT json_group_array(json_object('key', key, 'label', replace(key, '_', ' '), 'after', value))
+                        FROM (SELECT key, value FROM json_each(member.payload)
+                            WHERE key NOT IN ('id', 'tenant_id', 'log_id', 'created_at', 'updated_at') ORDER BY key)) AS fields
+                FROM enriched AS member WHERE member.group_id = (SELECT group_id FROM actions WHERE id = ${id})
+                ORDER BY member.action_index, member.local_sequence, member.id`);
+            return rows.map(row => ({ ...row, kind: 'saved', fields: JSON.parse(row.fields) }));
+        },
+    };
+}