@hearthlog/runtime 0.0.0-stage → 0.1.0

package/src/event/rebuild.ts

@@ -0,0 +1,176 @@
+import { reconcileRestoredEvents } from '../history/legacy-replay.js';
+/**
+ * Read Model Rebuild
+ * 
+ * Functions for rebuilding the entire read model from the event store.
+ */
+
+import { db as readModelDB, ensureCoreSchema, recreateModuleProjectionTables, requireActiveContext } from '../db/index.js';
+import type { Database, ActiveContext } from '../db/index.js';
+import { sql, type Transaction } from 'kysely';
+import { buildBulkProjectionSQL, type EntityProjectionConfig } from './projection-builder.js';
+import { entityRegistry, getAllEntityTables } from './registry.js';
+import { versionTracker } from '../ledger/version-tracker-singleton.js';
+import { get as getKv, set as setKv } from '../db/kv.js';
+import { SCHEMA_VERSION } from '../db/schema-version.js';
+import { currentProjections, moduleTables, staleModules } from '../db/module-projections.js';
+import { loadDynamicEntityTypes } from './dynamic-entities.js';
+import { materializeDynamicEntities } from './dynamic-materializer.js';
+import { withTiming } from '../utils/perf.js';
+import { tenant } from '@hearthlog/contracts/tenant/config';
+import { postTabChange, SCHEMA_LOCK_NAME, withTabLock } from '../store/tab-coordination.js';
+
+/**
+ * Rebuilds the entire read model from raw_events
+ * Uses the entity registry to iterate over all entities
+ */
+const SCHEMA_VERSION_KEY = 'schema-version';
+/** Projection tables the stored read model was built for. */
+const PROJECTED_TABLES_KEY = 'projected-tables';
+
+export async function rebuildIfSchemaChanged(): Promise<boolean> {
+    return withTiming('rebuild', 'rebuildIfSchemaChanged', async () => {
+        // Ensure core tables (raw_events) have the latest columns
+        const context = await requireActiveContext();
+        await ensureCoreSchema({ tenantId: context.tenantId, logId: context.logId });
+
+        // Always load dynamic entity types first - they need to be registered
+        // before any event processing can happen
+        await loadDynamicEntityTypes();
+
+        // Tabs opening together decide inside one lock, so exactly one rebuilds
+        // and the rest find the stored version current.
+        return withTabLock(SCHEMA_LOCK_NAME, async () => {
+            const storedVersion = await getKv<number>(SCHEMA_VERSION_KEY);
+            // A re-enabled feature gets its projection table back empty; a build
+            // with a different feature set re-projects like a schema change.
+            const projectedTables = [...tenant.approvedEntities.tables].sort();
+            const storedTables = await getKv<string[]>(PROJECTED_TABLES_KEY);
+            const tablesUnchanged = JSON.stringify(storedTables) === JSON.stringify(projectedTables);
+
+            // A module that raised its projection version re-projects like a schema change.
+            const projections = currentProjections(tenant.features);
+            const storedProjections = await readModelDB.selectFrom('module_migrations')
+                .select(['module_id', 'projection_version']).execute();
+            const stale = staleModules(storedProjections, projections);
+
+            if (storedVersion === SCHEMA_VERSION && tablesUnchanged && stale.length === 0) {
+                console.log('[Event] Schema version unchanged, skipping rebuild');
+                return false;
+            }
+
+            console.log(`[Event] Schema version (${storedVersion} → ${SCHEMA_VERSION}), projected tables, or module projections (${stale.join(', ') || 'none'}) changed, rebuilding...`);
+            // A module whose tables changed shape gets them recreated; no column repair is written.
+            if (stale.length > 0) await recreateModuleProjectionTables(readModelDB, moduleTables(stale));
+            await rebuildReadModel();
+            await setKv(SCHEMA_VERSION_KEY, SCHEMA_VERSION);
+            await setKv(PROJECTED_TABLES_KEY, projectedTables);
+            for (const { module, version } of projections) {
+                await readModelDB.insertInto('module_migrations')
+                    .values({ module_id: module, projection_version: version, applied_at: new Date().toISOString() })
+                    .onConflict((conflict) => conflict.column('module_id').doUpdateSet({ projection_version: version, applied_at: new Date().toISOString() }))
+                    .execute();
+            }
+            return true;
+        });
+    }, { currentVersion: SCHEMA_VERSION });
+}
+
+/**
+ * Rebuilds the entire read model from raw events.
+ * Uses the entity registry to iterate over all entities.
+ * Only call this explicitly when needed - not on every app load!
+ */
+export async function rebuildReadModel(options: { includePendingDdl?: boolean } = {}): Promise<void> {
+    return withTiming('rebuild', 'rebuildReadModel', async () => {
+        console.log('[Event] Starting read model rebuild');
+        const context = await requireActiveContext();
+
+        const staticConfigs = Object.values(entityRegistry).filter(entry => !entry.isDynamic).map(entry => entry.projection);
+        const previousTables = getAllEntityTables();
+        // Definitions, DDL, restore membership, and all entity rows publish together.
+        // Keep the tab-local registry unchanged until the database commit succeeds.
+        await readModelDB.transaction().execute(async (tx) => {
+            await reconcileRestoredEvents(tx, context, options.includePendingDdl);
+            const dynamicConfigs = await rebuildDynamicDefinitions(tx, context, options.includePendingDdl);
+            const configs = [...staticConfigs, ...dynamicConfigs];
+            console.log('[Event] Clearing existing read model tables for active log');
+
+            // Clear only this log's projection rows — leave other logs intact
+            for (const table of new Set([...previousTables, ...configs.map(config => config.tableName)])) {
+                await tx.deleteFrom(table as keyof Database)
+                    .where('tenant_id', '=', context.tenantId)
+                    .where('log_id', '=', context.logId)
+                    .execute();
+            }
+            await tx.deleteFrom('entity_versions')
+                .where('tenant_id', '=', context.tenantId)
+                .where('log_id', '=', context.logId)
+                .execute();
+            console.log('[Event] Read model tables cleared for scope');
+
+            // Rebuild each entity from events using the registry
+            for (const config of configs) {
+                await buildBulkProjectionSQL(config, context).execute(tx);
+            }
+        });
+        await loadDynamicEntityTypes();
+
+        // Rebuild entity version cache
+        console.log('[Event] Rebuilding entity version cache');
+        await versionTracker.rebuildVersionCache();
+
+        // Other tabs hold stale registries and pages until told.
+        postTabChange({ kind: 'rebuild', tenantId: context.tenantId, logId: context.logId });
+        console.log('[Event] Read model rebuild completed successfully');
+    }, { entityCount: Object.keys(entityRegistry).length });
+}
+
+/**
+ * Rebuilds the entity_type_definitions table and dynamic registry
+ * by replaying all definition events.
+ */
+async function rebuildDynamicDefinitions(tx: Transaction<Database>, context: ActiveContext, includePendingDdl = false): Promise<EntityProjectionConfig[]> {
+    return withTiming('rebuild', 'rebuildDynamicDefinitions', async () => {
+        console.log('[Event] Rebuilding dynamic entity definitions...');
+
+        if (!tenant.dynamicEntities) {
+            await tx.deleteFrom('entity_type_definitions')
+                .where('tenant_id', '=', context.tenantId)
+                .where('log_id', '=', context.logId)
+                .execute();
+            console.log('[Event] Dynamic entities disabled; definitions remain hidden');
+            return [];
+        }
+
+        const stagedTable = '__stor_live_effective_events';
+        try {
+            await tx.deleteFrom('entity_type_definitions')
+                .where('tenant_id', '=', context.tenantId)
+                .where('log_id', '=', context.logId)
+                .execute();
+            await sql.raw(`DROP TABLE IF EXISTS temp."${stagedTable}"`).execute(tx);
+            await sql`
+                CREATE TEMP TABLE ${sql.raw(`"${stagedTable}"`)} AS
+                SELECT * FROM main.raw_events
+                WHERE tenant_id = ${context.tenantId}
+                  AND log_id = ${context.logId}
+                  AND (projection_state = 'effective' OR (${includePendingDdl ? 1 : 0} = 1 AND projection_state = 'pending_ddl'))
+                  AND is_tombstoned = 0
+            `.execute(tx);
+            const result = await materializeDynamicEntities({
+                database: tx,
+                schema: 'main',
+                sourceSchema: 'temp',
+                sourceTable: stagedTable,
+                scope: context,
+                registerLive: false,
+            });
+            return result.activeProjectionConfigs;
+        } finally {
+            await sql.raw(`DROP TABLE IF EXISTS temp."${stagedTable}"`).execute(tx);
+        }
+    }, {});
+}
+
+export { versionTracker };

package/src/event/reference-lookup.ts

@@ -0,0 +1,93 @@
+import { sql } from 'kysely';
+import type { ReadModelSession } from '../db/read-session.js';
+import { ENTITY_DEFINITIONS, getPayloadKey } from '@hearthlog/contracts/event/entity-definitions';
+import { parseEntityFields } from './dynamic-entities.js';
+import type { DynamicFieldDefinition } from './meta-entity-types.js';
+import { quoteIdentifier } from './projection-builder.js';
+import { withTimeout } from '../utils/async.js';
+import { tenant } from '@hearthlog/contracts/tenant/config';
+
+export interface ReferencingEntity {
+    entityType: string;
+    entityTypeDisplayName: string;
+    entityId: string;
+    entityLabel: string;
+    fieldName: string;
+}
+
+export interface ReferencedByResult {
+    byType: Record<string, ReferencingEntity[]>;
+    totalCount: number;
+}
+
+export function createReferenceLookup(session: ReadModelSession) {
+    return {
+        async findReferencingEntities(
+            targetEntityId: string,
+            targetEntityType?: string,
+        ): Promise<ReferencedByResult> {
+            const result: ReferencedByResult = { byType: {}, totalCount: 0 };
+            const dynamic = await session.selectFrom('entity_type_definitions')
+                .selectAll()
+                .where('is_archived', '=', 0)
+                .execute();
+            const entityTypes = [
+                ...ENTITY_DEFINITIONS
+                    .filter((definition) => tenant.approvedEntities.entityNames.has(definition.name))
+                    .map((definition) => ({
+                        name: definition.name,
+                        display_name: definition.displayName ?? definition.name,
+                        table_name: definition.table,
+                        fields: definition.fields.map((field) => ({
+                            ...field,
+                            payloadKey: getPayloadKey(field),
+                        })) as DynamicFieldDefinition[],
+                    })),
+                ...(tenant.dynamicEntities ? dynamic : []).map((definition) => ({
+                    name: definition.name,
+                    display_name: definition.display_name,
+                    table_name: definition.table_name,
+                    fields: parseEntityFields(definition),
+                })),
+            ];
+
+            for (const entityType of entityTypes) {
+                const fields = entityType.fields.filter((field) =>
+                    field.type === 'reference' &&
+                    (!targetEntityType || field.referenceTo === targetEntityType) &&
+                    (!field.referenceTo || isVisibleEntityType(field.referenceTo)));
+                for (const field of fields) {
+                    const rows = await withTimeout(
+                        session.execute(sql<Record<string, unknown>>`
+                            SELECT *
+                            FROM ${session.table(entityType.table_name)}
+                            WHERE ${sql.raw(quoteIdentifier(field.name))} = ${targetEntityId}
+                            LIMIT 50
+                        `),
+                        5000,
+                        'Reference lookup query timed out',
+                    );
+                    for (const row of rows.rows) {
+                        const item: ReferencingEntity = {
+                            entityType: entityType.name,
+                            entityTypeDisplayName: entityType.display_name,
+                            entityId: String(row.id),
+                            entityLabel: String(row.name ?? row.title ?? row.label ?? row.id),
+                            fieldName: field.name,
+                        };
+                        (result.byType[entityType.name] ??= []).push(item);
+                        result.totalCount += 1;
+                    }
+                }
+            }
+            return result;
+        },
+    };
+}
+
+function isVisibleEntityType(name: string): boolean {
+    const definition = ENTITY_DEFINITIONS.find((candidate) => candidate.name === name);
+    return definition
+        ? tenant.approvedEntities.entityNames.has(name)
+        : tenant.dynamicEntities;
+}

package/src/event/registry.ts

@@ -0,0 +1,158 @@
+/**
+ * Entity Registry
+ * 
+ * Hybrid registry supporting both static (compile-time) and dynamic (runtime) entities.
+ * Static entities from ENTITY_DEFINITIONS always take precedence over dynamic ones.
+ */
+
+import { ENTITY_DEFINITIONS, getEventPrefix } from '@hearthlog/contracts/event/entity-definitions';
+import type { EntityCalendarSource } from '@hearthlog/contracts/calendar/config';
+import { tenant } from '@hearthlog/contracts/tenant/config';
+import { PROJECTION_CONFIGS, type EntityProjectionConfig } from './projection-builder.js';
+
+export interface EntityRegistryEntry {
+    /** Projection configuration for SQL generation */
+    projection: EntityProjectionConfig;
+    /** Event type prefix for type guards (e.g., 'CALENDAR_EVENT_') */
+    eventPrefix: string;
+    /** Database table name */
+    table: string;
+    /** Whether this is a dynamic (runtime-defined) entity */
+    isDynamic?: boolean;
+    /** Calendar dates the entity exposes (dynamic entities only today). */
+    calendar?: EntityCalendarSource[];
+}
+
+// ============================================================================
+// Static Registry (Compile-time entities)
+// ============================================================================
+
+/**
+ * Static registry of the entities this tenant is approved for (feature
+ * ownership in entity-definitions.ts; approval derived from the tenant's
+ * enabled features). Events for non-approved entities are stored in
+ * raw_events but never materialized.
+ */
+const staticRegistry: Record<string, EntityRegistryEntry> = Object.fromEntries(
+    ENTITY_DEFINITIONS
+        .filter(def => tenant.approvedEntities.entityNames.has(def.name))
+        .map(def => [
+            def.name,
+            {
+                projection: PROJECTION_CONFIGS[def.name],
+                eventPrefix: getEventPrefix(def),
+                table: def.table,
+                isDynamic: false,
+            }
+        ])
+);
+
+// ============================================================================
+// Dynamic Registry (Runtime entities)
+// ============================================================================
+
+/**
+ * Dynamic registry of entities defined at runtime.
+ * Mutable - can be updated as new entity types are created.
+ */
+let dynamicRegistry: Record<string, EntityRegistryEntry> = {};
+
+/**
+ * Register a dynamic entity type.
+ * If a static entity with the same name exists, the static one takes precedence.
+ */
+export function registerDynamicEntity(name: string, entry: EntityRegistryEntry): void {
+    if (staticRegistry[name]) {
+        console.warn(`[Registry] Dynamic entity "${name}" shadowed by static entity`);
+        return;
+    }
+    dynamicRegistry[name] = { ...entry, isDynamic: true };
+    console.log(`[Registry] Registered dynamic entity: ${name}`);
+}
+
+/**
+ * Unregister a dynamic entity type.
+ */
+export function unregisterDynamicEntity(name: string): void {
+    delete dynamicRegistry[name];
+    console.log(`[Registry] Unregistered dynamic entity: ${name}`);
+}
+
+/**
+ * Clear all dynamic entities (used during rebuild).
+ */
+export function clearDynamicRegistry(): void {
+    dynamicRegistry = {};
+    console.log('[Registry] Cleared dynamic registry');
+}
+
+/**
+ * Get names of all dynamic entities.
+ */
+export function getDynamicEntityNames(): string[] {
+    return Object.keys(dynamicRegistry);
+}
+
+// ============================================================================
+// Unified Access (Backwards Compatible)
+// ============================================================================
+
+/**
+ * Get the combined registry of static + dynamic entities.
+ * Static entities take precedence over dynamic ones.
+ */
+export function getEntityRegistry(): Record<string, EntityRegistryEntry> {
+    return { ...dynamicRegistry, ...staticRegistry };
+}
+
+/**
+ * Legacy: Direct access to registry for backwards compatibility.
+ * Prefer using getEntityRegistry() for future code.
+ */
+export const entityRegistry: Record<string, EntityRegistryEntry> = new Proxy({} as Record<string, EntityRegistryEntry>, {
+    get(_target, prop: string) {
+        return getEntityRegistry()[prop];
+    },
+    has(_target, prop: string) {
+        return prop in getEntityRegistry();
+    },
+    ownKeys() {
+        return Object.keys(getEntityRegistry());
+    },
+    getOwnPropertyDescriptor(_target, prop: string) {
+        const registry = getEntityRegistry();
+        if (prop in registry) {
+            return { configurable: true, enumerable: true, value: registry[prop] };
+        }
+        return undefined;
+    }
+});
+
+/**
+ * Get all registered entity configurations (static + dynamic).
+ */
+export function getAllEntityConfigs(): EntityProjectionConfig[] {
+    return Object.values(getEntityRegistry()).map(e => e.projection);
+}
+
+/**
+ * Get all registered table names (static + dynamic).
+ */
+export function getAllEntityTables(): string[] {
+    return Object.values(getEntityRegistry()).map(e => e.table);
+}
+
+/**
+ * Get only static entity names.
+ */
+export function getStaticEntityNames(): string[] {
+    return Object.keys(staticRegistry);
+}
+
+/**
+ * Check if an entity is static (compile-time defined).
+ */
+export function isStaticEntity(name: string): boolean {
+    return name in staticRegistry;
+}
+

package/src/event/schema-effects.ts

@@ -0,0 +1,45 @@
+import type { Kysely, Transaction } from 'kysely';
+import type { Database } from '../db/index.js';
+import { EVENTS_EXCISED, WORKSPACE_RESTORED } from '@hearthlog/contracts/history/replay-selection';
+
+const SCHEMA_EFFECT_TYPES = [
+    'ENTITY_TYPE_DEFINED',
+    'ENTITY_TYPE_UPDATED',
+    'ENTITY_TYPE_ARCHIVED',
+    WORKSPACE_RESTORED,
+];
+
+/**
+ * Directive events that change the projected schema (dynamic definitions and
+ * restore pointers) must take the DDL rebuild path instead of a targeted
+ * reprojection. Tombstones and excisions both qualify when they name a schema
+ * event.
+ */
+export async function schemaTombstoneIds(
+    database: Kysely<Database> | Transaction<Database>,
+    scope: { tenantId: string; logId: string },
+    events: ReadonlyArray<{ id: string; type: string; payload: unknown }>,
+): Promise<Set<string>> {
+    const tombstones = events.filter(event => event.type === 'EVENT_TOMBSTONED');
+    const excisions = events.filter(event => event.type === EVENTS_EXCISED);
+    if (!tombstones.length && !excisions.length) return new Set();
+    const targetIds = [
+        ...tombstones.map(event => (event.payload as { eventId: string }).eventId),
+        ...excisions.flatMap(event => (event.payload as { eventIds: string[] }).eventIds),
+    ];
+    if (!targetIds.length) return new Set();
+    const targets = await database.selectFrom('raw_events').select('id')
+        .where('tenant_id', '=', scope.tenantId).where('log_id', '=', scope.logId)
+        .where('id', 'in', targetIds)
+        .where('type', 'in', SCHEMA_EFFECT_TYPES).execute();
+    const schemaTargetIds = new Set(targets.map(row => row.id));
+    const result = new Set<string>();
+    for (const tombstone of tombstones) {
+        if (schemaTargetIds.has((tombstone.payload as { eventId: string }).eventId)) result.add(tombstone.id);
+    }
+    for (const excision of excisions) {
+        const targets = (excision.payload as { eventIds: string[] }).eventIds;
+        if (targets.some(id => schemaTargetIds.has(id))) result.add(excision.id);
+    }
+    return result;
+}

package/src/event/types.ts

@@ -0,0 +1,20 @@
+/**
+ * Event Types
+ * 
+ * Re-exports all types from the generated file.
+ * 
+ * IMPORTANT: Do not manually edit event types here.
+ * Instead, update entity-definitions.ts and run `pnpm generate:entities`.
+ */
+
+// Re-export all generated types
+export * from '#generated/types';
+
+// Re-export meta-entity types (runtime entity type management)
+export * from './meta-entity-types.js';
+
+// Extended AppEvent union that includes meta-entity events
+import type { AppEvent as GeneratedAppEvent } from '#generated/types';
+import type { MetaEntityEvent } from './meta-entity-types.js';
+
+export type ExtendedAppEvent = GeneratedAppEvent | MetaEntityEvent;

package/src/history/action-boundary.ts

@@ -0,0 +1,18 @@
+import { sql, type SqlBool } from 'kysely';
+
+/** A paged download must contain every accepted member before exposing an action. */
+export const completeActionBoundary = sql<SqlBool>`(
+    raw_events.action_id IS NULL OR (
+        raw_events.action_size > 0
+        AND raw_events.action_index = raw_events.action_size - 1
+        AND (SELECT COUNT(*) FROM raw_events AS member
+            WHERE member.tenant_id = raw_events.tenant_id
+              AND member.log_id = raw_events.log_id
+              AND member.action_id = raw_events.action_id
+              AND member.action_size = raw_events.action_size
+              AND member.projection_state IN ('effective', 'restored_out')
+              AND member.log_version BETWEEN raw_events.log_version - raw_events.action_size + 1 AND raw_events.log_version
+              AND member.action_index = member.log_version - (raw_events.log_version - raw_events.action_size + 1)
+        ) = raw_events.action_size
+    )
+)`;

package/src/history/action-detail.ts

@@ -0,0 +1,23 @@
+import { requireActiveContext } from '../db/index.js';
+import { getAdjacentHistoryPoint, getHistoryPoint, type HistoryPoint } from './history.js';
+import { readWorkspaceSnapshot } from './point-snapshot.js';
+import { compareWorkspaceRecords, type HistoryChange } from './change-comparison.js';
+
+export interface HistoryActionDetail {
+    point: HistoryPoint;
+    previousVersion: number;
+    changes: HistoryChange[];
+}
+
+/** Compare only the selected accepted action boundary with its predecessor. */
+export async function loadHistoryActionDetail(version: number): Promise<HistoryActionDetail> {
+    const point = await getHistoryPoint(version);
+    if (!point) throw new Error('That action is no longer available in this log.');
+    const previous = await getAdjacentHistoryPoint(version, 'previous');
+    const context = await requireActiveContext();
+    const scope = { tenantId: context.tenantId, logId: context.logId };
+    const previousVersion = previous?.version ?? 0;
+    const before = await readWorkspaceSnapshot(previousVersion, scope);
+    const after = await readWorkspaceSnapshot(point.version, scope);
+    return { point, previousVersion, changes: compareWorkspaceRecords(before, after) };
+}

package/src/history/change-comparison.ts

@@ -0,0 +1,29 @@
+import type { WorkspaceRecord } from './point-snapshot.js';
+
+export interface HistoryChange {
+    key: string;
+    label: string;
+    kind: 'added' | 'changed' | 'removed';
+    before?: Record<string, unknown>;
+    after?: Record<string, unknown>;
+}
+
+export function compareWorkspaceRecords(before: WorkspaceRecord[], after: WorkspaceRecord[]): HistoryChange[] {
+    const previous = new Map(before.map(record => [record.key, record]));
+    const next = new Map(after.map(record => [record.key, record]));
+    const changes: HistoryChange[] = [];
+    for (const key of [...new Set([...previous.keys(), ...next.keys()])].sort()) {
+        const left = previous.get(key), right = next.get(key);
+        if (left && right && stableJson(left.value) === stableJson(right.value)) continue;
+        changes.push({ key, label: (right ?? left)!.label, kind: !left ? 'added' : !right ? 'removed' : 'changed',
+            ...(left ? { before: left.value } : {}), ...(right ? { after: right.value } : {}) });
+    }
+    return changes;
+}
+
+function stableJson(value: unknown): string {
+    if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+    if (value && typeof value === 'object') return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(',')}}`;
+    return JSON.stringify(value);
+}

package/src/history/change-display.ts

@@ -0,0 +1,41 @@
+import type { HistoryChange } from './change-comparison.js';
+import { formatNumber } from '@hearthlog/ui/utils/number-format.js';
+
+export interface ChangedField {
+    key: string;
+    label: string;
+    before: string;
+    after: string;
+}
+
+const hiddenFields = new Set(['id', 'tenant_id', 'log_id', 'created_at', 'updated_at']);
+
+function sameValue(left: unknown, right: unknown): boolean {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+
+export function fieldChanges(change: HistoryChange): ChangedField[] {
+    const before = change.before ?? {};
+    const after = change.after ?? {};
+    return [...new Set([...Object.keys(before), ...Object.keys(after)])]
+        .filter(key => !hiddenFields.has(key) && !sameValue(before[key], after[key]))
+        .sort((left, right) => left.localeCompare(right))
+        .map(key => ({
+            key,
+            label: key.replace(/_/g, ' ').replace(/\b\w/g, letter => letter.toUpperCase()),
+            before: displayHistoryValue(before[key]),
+            after: displayHistoryValue(after[key]),
+        }));
+}
+
+export function displayHistoryValue(value: unknown): string {
+    if (value === null || value === undefined || value === '') return '—';
+    if (typeof value === 'boolean') return value ? 'Yes' : 'No';
+    if (typeof value === 'number') return formatNumber(value, 4);
+    if (typeof value === 'string') return value;
+    return JSON.stringify(value);
+}
+
+export function changeVerb(kind: HistoryChange['kind']): string {
+    return kind === 'added' ? 'Added' : kind === 'removed' ? 'Removed' : 'Changed';
+}

package/src/history/contracts.ts

@@ -0,0 +1,63 @@
+import type { FeatureId } from '@hearthlog/contracts/features/registry';
+
+export interface HistoryEntry {
+    id: string;
+    label: string;
+    timestamp: number;
+    version: number | null;
+    previousVersion: number;
+    eventCount: number;
+    feature: FeatureId | null;
+    /** Who wrote the action, as Ledger recorded it; null for older or local-only actions. */
+    actor: string | null;
+    status: 'ready' | 'waiting' | 'attention';
+    reason: string | null;
+    startsDay: boolean;
+    total: number;
+}
+
+/** A row of the history list: an action, or a place where a log starts. */
+export type HistoryItem =
+    | (HistoryEntry & { kind: 'action'; copied: boolean })
+    | { kind: 'marker'; id: string; markerKey: string; total: number };
+
+/** An action as a point on the log map. */
+export interface HistoryPoint {
+    id: string;
+    label: string;
+    timestamp: number;
+    version: number | null;
+}
+
+export interface HistoryListOptions {
+    search?: string;
+    feature?: string;
+    limit?: number;
+    /** Keep loading until this action is in the list. */
+    through?: string | null;
+    /** Actions at or below this version were copied from the source log. */
+    sourceVersion?: number | null;
+    /** Fork points to place between actions; left out while searching or filtering. */
+    markers?: { key: string; version: number }[];
+}
+
+export interface HistoryField {
+    key: string;
+    label: string;
+    before: unknown;
+    after: unknown;
+}
+
+export interface HistoryRecord {
+    key: string;
+    label: string;
+    kind: 'added' | 'changed' | 'removed' | 'saved';
+    fields: HistoryField[];
+}
+
+export interface ForkReview {
+    keptActions: number;
+    laterActions: number;
+    features: string;
+    localHead: number;
+}