@hearthlog/runtime 0.0.0-stage → 0.1.0

package/src/history/log-map.ts

@@ -0,0 +1,110 @@
+import { format, startOfMonth, addMonths } from 'date-fns';
+import type { LogNode } from './lineage.js';
+
+const DAY = 86_400_000;
+
+export interface MapRow {
+    node: LogNode;
+    y: number;
+    x0: number;
+    x1: number;
+    /** Where the line leaves its parent's row. */
+    fork: { x: number; y: number } | null;
+    /** The log began before the map does. */
+    clipped: boolean;
+    label: { x: number; anchor: 'start' | 'end' };
+}
+
+export interface LogMapModel {
+    width: number;
+    height: number;
+    axisY: number;
+    rows: MapRow[];
+    ticks: { x: number; label: string; anchor: 'start' | 'middle' | 'end' }[];
+    x: (time: number) => number;
+}
+
+function time(value: string | null | undefined): number | null {
+    const parsed = value ? Date.parse(value) : Number.NaN;
+    return Number.isFinite(parsed) ? parsed : null;
+}
+
+function forkTime(node: LogNode): number | null {
+    return node.log.sourceLogId
+        ? time(node.log.sourceTimestamp) ?? time(node.log.createdAt)
+        : time(node.log.createdAt);
+}
+
+export interface MapSpan {
+    start: number;
+    end: number;
+}
+
+/**
+ * The time the map covers. It ends at the latest activity, which is today for a
+ * log in use. Forks cluster near the end, so it covers the month before it,
+ * reaching back to the oldest fork within four months; older logs run in from
+ * the left edge.
+ */
+export function mapSpan(nodes: readonly LogNode[], now: number, newestAction: number | null): MapSpan {
+    const latest = Math.max(newestAction ?? Number.NEGATIVE_INFINITY, ...nodes.map(node =>
+        time(node.log.lastUpdatedAt) ?? time(node.log.createdAt) ?? Number.NEGATIVE_INFINITY));
+    // Recent activity counts as today, so the axis reads "Today".
+    const end = !Number.isFinite(latest) || latest > now - 2 * DAY ? now : Math.min(latest, now);
+    const forks = nodes.filter(node => node.log.sourceLogId).map(forkTime)
+        .filter((value): value is number => value !== null && value <= end);
+    const start = Math.max(end - 120 * DAY, Math.min(end - 30 * DAY, ...forks));
+    return { start: start - (end - start) * 0.03, end: end + (end === now ? 0 : (end - start) * 0.02) };
+}
+
+/** One line per log on a shared time axis, in tree order. Pure geometry. */
+export function logMap(
+    nodes: readonly LogNode[],
+    options: { currentLogId: string | null; now: number; span: MapSpan; width?: number; rowGap?: number },
+): LogMapModel {
+    const width = options.width ?? 360;
+    // Rows tighten as logs are added, so the whole tree stays in view.
+    const rowGap = options.rowGap ?? Math.max(16, Math.min(26, 104 / Math.max(1, nodes.length - 1)));
+    const top = 22;
+    const left = 8;
+    const right = 8;
+    const now = options.now;
+    const { start, end } = options.span;
+    const x = (value: number) => left + ((Math.min(Math.max(value, start), end) - start) / (end - start)) * (width - left - right);
+
+    const rowY = new Map<string, number>();
+    const rows = nodes.map((node, index): MapRow => {
+        const y = top + index * rowGap;
+        rowY.set(node.log.id, y);
+        const began = forkTime(node) ?? start;
+        const x0 = x(began);
+        const current = node.log.id === options.currentLogId;
+        const last = current || node.log.status === 'preparing'
+            ? end
+            : time(node.log.lastUpdatedAt) ?? time(node.log.createdAt) ?? began;
+        const x1 = Math.max(x(last), x0 + 4);
+        const parentY = node.parentId ? rowY.get(node.parentId) : undefined;
+        const estimate = node.log.name.length * 6.2 + 4;
+        return {
+            node, y, x0, x1,
+            fork: node.log.sourceLogId && parentY !== undefined ? { x: x0, y: parentY } : null,
+            clipped: began < start,
+            // After the start when it fits, otherwise just before it, clear of the fork line.
+            label: x0 + estimate <= width - 4 ? { x: x0 + 2, anchor: 'start' }
+                : x0 - estimate >= 4 ? { x: x0 - 6, anchor: 'end' } : { x: 4, anchor: 'start' },
+        };
+    });
+
+    const axisY = top + Math.max(0, nodes.length - 1) * rowGap + 18;
+    const ticks: LogMapModel['ticks'] = [
+        { x: left, label: format(start, 'MMM d'), anchor: 'start' },
+        { x: width - right, label: end >= now - DAY ? 'Today' : format(end, 'MMM d'), anchor: 'end' },
+    ];
+    if (end - start > 60 * DAY) {
+        for (let month = startOfMonth(addMonths(start, 1)).getTime(); month < end - 20 * DAY; month = addMonths(month, 1).getTime()) {
+            const at = x(month);
+            if (at > left + 44 && at < width - right - 44) ticks.push({ x: at, label: format(month, 'MMM'), anchor: 'middle' });
+        }
+    }
+    return { width, height: axisY + 16, axisY, rows, ticks, x };
+}

package/src/history/navigation.ts

@@ -0,0 +1,14 @@
+import { browser } from '$app/env';
+import { goto } from '$app/navigation';
+import { page } from '$app/state';
+
+/** Shallow navigation changes page.state; the address bar remains authoritative. */
+export function historyRouteUrl(): URL {
+    void page.state;
+    void page.url;
+    return browser ? new URL(window.location.href) : new URL(page.url.href);
+}
+
+export function navigateHistory(url: URL, replace = false): void {
+    void goto(url, { shallow: true, replace, state: { ...page.state, historyUrl: url.href } });
+}

package/src/history/point-snapshot.ts

@@ -0,0 +1,229 @@
+import { sql, type Kysely } from 'kysely';
+import { db, type Database } from '../db/index.js';
+import { generateDynamicTableDDL } from '../db/dynamic-ddl.js';
+import { getAllEntityDDL, getAllEntityIndexDDL } from '#generated/schema';
+import { createProjectionConfigFromDynamic } from '../event/dynamic-entities.js';
+import { materializeDynamicEntities } from '../event/dynamic-materializer.js';
+import {
+    buildBulkProjectionSQL,
+    PROJECTION_CONFIGS,
+    qualifiedIdentifier,
+    quoteIdentifier,
+} from '../event/projection-builder.js';
+import { completeActionBoundary } from './action-boundary.js';
+import { EVENTS_EXCISED, WORKSPACE_RESTORED } from '@hearthlog/contracts/history/replay-selection';
+import { filterRestoredSnapshot } from './legacy-replay.js';
+import type { DynamicFieldDefinition } from '../event/meta-entity-types.js';
+import type { ReadScope } from '../db/read-session.js';
+import type { HistoryRecord } from './contracts.js';
+
+const STAGED_EVENTS_TABLE = '__stor_effective_events';
+const aliases = globalThis as typeof globalThis & { storPointSnapshotAliasCounter?: number };
+
+/** Parse staged dynamic field JSON; a malformed row fails the snapshot. */
+function parseDefinitionFields(fieldsJson: string): DynamicFieldDefinition[] {
+    try {
+        const parsed: unknown = JSON.parse(fieldsJson);
+        if (Array.isArray(parsed)) return parsed as DynamicFieldDefinition[];
+    } catch {
+        // Fall through to the typed error below.
+    }
+    throw new Error('point-snapshot-invalid-dynamic-fields');
+}
+
+export interface WorkspaceRecord {
+    key: string;
+    label: string;
+    value: Record<string, unknown>;
+}
+
+/** Build one accepted prefix for a Log history comparison, then release it. */
+export async function readWorkspaceSnapshot(version: number, scope: ReadScope): Promise<WorkspaceRecord[]> {
+    return withPointSnapshot(version, scope, async (schema, projectionConfigs) => {
+        const records: WorkspaceRecord[] = [];
+        for (const config of projectionConfigs) {
+            const result = await sql<Record<string, unknown>>`SELECT * FROM ${sql.raw(qualifiedIdentifier(schema, config.tableName))}`.execute(db);
+            for (const row of result.rows) {
+                const { tenant_id: _tenant, log_id: _log, ...value } = row;
+                records.push({ key: `${config.entityName}:${String(row.id)}`, label: String(row.title ?? row.name ?? row.id), value });
+            }
+        }
+        const definitions = await sql<Record<string, unknown>>`SELECT * FROM ${sql.raw(qualifiedIdentifier(schema, 'entity_type_definitions'))}`.execute(db);
+        for (const row of definitions.rows) {
+            const { tenant_id: _tenant, log_id: _log, ...value } = row;
+            records.push({ key: `entity_type:${String(row.id)}`, label: String(row.display_name ?? row.name ?? row.id), value });
+        }
+        return records.sort((a, b) => a.key.localeCompare(b.key));
+    });
+}
+
+/** Keep both materialized prefixes leased while SQLite compares records and fields. */
+export async function readActionChanges(previousVersion: number, version: number, scope: ReadScope): Promise<HistoryRecord[]> {
+    return withPointSnapshot(previousVersion, scope, async (beforeSchema, beforeConfigs) =>
+        withPointSnapshot(version, scope, async (afterSchema, afterConfigs) => {
+            function snapshotRows(schema: string, configs: typeof beforeConfigs) {
+                const tables = [...configs.map(config => ({ entity: config.entityName, table: config.tableName,
+                    fields: config.fields.map(field => field.name) })),
+                    { entity: 'entity_type', table: 'entity_type_definitions',
+                        fields: ['name', 'display_name', 'table_name', 'fields_json', 'calendar_json', 'is_archived'] }];
+                return sql.join(tables.map(table => sql`SELECT ${table.entity} || ':' || id AS key,
+                    json_object(${sql.join(table.fields.flatMap(field => [sql`${field}`, sql.ref(field)]))}) AS value
+                    FROM ${sql.raw(qualifiedIdentifier(schema, table.table))}`), sql` UNION ALL `);
+            }
+            const { rows } = await sql<{ key: string; label: string; kind: HistoryRecord['kind']; fields: string }>`
+                WITH before_records AS (${snapshotRows(beforeSchema, beforeConfigs)}),
+                after_records AS (${snapshotRows(afterSchema, afterConfigs)}),
+                keys AS (SELECT key FROM before_records UNION SELECT key FROM after_records),
+                changes AS (
+                    SELECT keys.key, b.value AS before_value, a.value AS after_value,
+                        CASE WHEN b.key IS NULL THEN 'added' WHEN a.key IS NULL THEN 'removed' ELSE 'changed' END AS kind,
+                        (SELECT json_group_array(json_object('key', field, 'label', replace(field, '_', ' '),
+                            'before', json_extract(b.value, '$.' || field), 'after', json_extract(a.value, '$.' || field)))
+                         FROM (SELECT key AS field FROM json_each(b.value) UNION SELECT key FROM json_each(a.value))
+                         WHERE json_extract(b.value, '$.' || field) IS NOT json_extract(a.value, '$.' || field)
+                         ORDER BY field) AS fields
+                    FROM keys LEFT JOIN before_records b ON b.key = keys.key LEFT JOIN after_records a ON a.key = keys.key
+                ) SELECT key, kind, fields,
+                    COALESCE(json_extract(after_value, '$.title'), json_extract(after_value, '$.name'), json_extract(after_value, '$.number'),
+                        json_extract(before_value, '$.title'), json_extract(before_value, '$.name'), json_extract(before_value, '$.number'), key) AS label
+                FROM changes WHERE kind != 'changed' OR json_array_length(fields) > 0 ORDER BY key
+            `.execute(db);
+            return rows.map(row => ({ ...row, fields: JSON.parse(row.fields) }));
+        }));
+}
+
+async function withPointSnapshot<T>(version: number, scope: ReadScope,
+    read: (schema: string, configs: Awaited<ReturnType<typeof buildPointSnapshot>>['projectionConfigs']) => Promise<T>): Promise<T> {
+    if (!Number.isSafeInteger(version) || version < 0) throw new Error('Invalid history version');
+    const head = await downloadedHead(scope);
+    if (version > (head ?? 0)) throw new Error('Download this log before inspecting its history');
+    if (version > 0) {
+        const boundary = await db.selectFrom('raw_events').select('id')
+            .where('tenant_id', '=', scope.tenantId).where('log_id', '=', scope.logId)
+            .where('log_version', '=', version).where('projection_state', 'in', ['effective', 'restored_out'])
+            .where(completeActionBoundary).executeTakeFirst();
+        if (!boundary) throw new Error('Choose a complete accepted action');
+    }
+
+    const schema = `stor_point_${aliases.storPointSnapshotAliasCounter = (aliases.storPointSnapshotAliasCounter ?? 0) + 1}`;
+    await sql.raw(`ATTACH DATABASE ':memory:' AS ${quoteIdentifier(schema)}`).execute(db);
+    try {
+        const { projectionConfigs, knownEventTypes } = await buildPointSnapshot(schema, scope, version);
+        const types = await sql<{ type: string }>`
+            SELECT DISTINCT type FROM ${sql.raw(qualifiedIdentifier(schema, STAGED_EVENTS_TABLE))}
+        `.execute(db);
+        const unknown = types.rows.filter(row => !knownEventTypes.has(row.type));
+        if (unknown.length) throw new Error(`Cannot inspect unrecognized event types: ${unknown.map(row => row.type).join(', ')}`);
+
+        return await read(schema, projectionConfigs);
+    } finally {
+        await sql.raw(`DETACH DATABASE ${quoteIdentifier(schema)}`).execute(db);
+    }
+}
+
+async function buildPointSnapshot(schema: string, scope: ReadScope, version: number) {
+    return db.transaction().execute(async (tx) => {
+        for (const ddl of getAllEntityDDL().map(statement => qualifyGeneratedDDL(statement, schema))) {
+            await sql.raw(ddl).execute(tx);
+        }
+        for (const ddl of getAllEntityIndexDDL().map(statement => qualifyGeneratedDDL(statement, schema))) {
+            await sql.raw(ddl).execute(tx);
+        }
+        await sql.raw(entityTypeDefinitionsDDL(schema)).execute(tx);
+        await stageAcceptedPrefix(tx, schema, scope, version);
+
+        const dynamic = await materializeDynamicEntities({
+            database: tx,
+            schema,
+            scope,
+            registerLive: false,
+            sourceTable: STAGED_EVENTS_TABLE,
+        });
+        for (const record of dynamic.records.filter(record => record.is_archived)) {
+            await sql.raw(generateDynamicTableDDL(record, schema)).execute(tx);
+            dynamic.activeProjectionConfigs.push(createProjectionConfigFromDynamic(
+                record.name, record.table_name, parseDefinitionFields(record.fields_json),
+            ));
+        }
+        const projectionConfigs = [...Object.values(PROJECTION_CONFIGS), ...dynamic.activeProjectionConfigs];
+        const projectionOptions = {
+            target: { schema },
+            source: { schema, table: STAGED_EVENTS_TABLE, staged: true },
+        } as const;
+        for (const config of projectionConfigs) {
+            await buildBulkProjectionSQL(config, scope, projectionOptions).execute(tx);
+        }
+        const knownEventTypes = new Set([
+            'EVENT_TOMBSTONED', WORKSPACE_RESTORED, EVENTS_EXCISED,
+            'ENTITY_TYPE_DEFINED', 'ENTITY_TYPE_UPDATED', 'ENTITY_TYPE_ARCHIVED',
+            ...projectionConfigs.flatMap(config => config.eventTypes),
+            ...dynamic.records.flatMap(record => createProjectionConfigFromDynamic(
+                record.name, record.table_name, parseDefinitionFields(record.fields_json),
+            ).eventTypes),
+        ]);
+        return { projectionConfigs, knownEventTypes };
+    });
+}
+
+async function stageAcceptedPrefix(database: Kysely<Database>, schema: string, scope: ReadScope, version: number): Promise<void> {
+    const staged = qualifiedIdentifier(schema, STAGED_EVENTS_TABLE);
+    await sql`
+        CREATE TABLE ${sql.raw(staged)} AS
+        SELECT * FROM main.raw_events
+        WHERE tenant_id = ${scope.tenantId}
+          AND log_id = ${scope.logId}
+          AND projection_state IN ('effective', 'restored_out')
+          AND log_version IS NOT NULL
+          AND log_version <= ${version}
+    `.execute(database);
+    // Old restore/removal facts in the prefix still affect its projected state.
+    await filterRestoredSnapshot(database, staged, version);
+    const indexSchema = quoteIdentifier(schema);
+    await sql.raw(`CREATE INDEX ${indexSchema}."idx_stor_history_type" ON "${STAGED_EVENTS_TABLE}" ("type")`).execute(database);
+    await sql.raw(`CREATE INDEX ${indexSchema}."idx_stor_history_entity" ON "${STAGED_EVENTS_TABLE}" ("entity_id", "entity_version")`).execute(database);
+    await sql.raw(`CREATE INDEX ${indexSchema}."idx_stor_history_version" ON "${STAGED_EVENTS_TABLE}" ("log_version")`).execute(database);
+}
+
+function qualifyGeneratedDDL(statement: string, schema: string): string {
+    const qualifiedSchema = quoteIdentifier(schema);
+    return statement.replace(
+        /^(\s*CREATE TABLE IF NOT EXISTS )"([^"]+)"/,
+        `$1${qualifiedSchema}."$2"`,
+    ).replace(
+        /^(\s*CREATE (?:UNIQUE )?INDEX IF NOT EXISTS )"([^"]+)"/,
+        `$1${qualifiedSchema}."$2"`,
+    );
+}
+
+async function downloadedHead(scope: ReadScope): Promise<number | null> {
+    const syncState = await db.selectFrom('log_sync_state').select('downloaded_head_version')
+        .where('tenant_id', '=', scope.tenantId).where('log_id', '=', scope.logId).executeTakeFirst();
+    if (syncState) return syncState.downloaded_head_version;
+    const available = await db.selectFrom('raw_events')
+        .select(({ fn }) => fn.max('log_version').as('head'))
+        .where('tenant_id', '=', scope.tenantId).where('log_id', '=', scope.logId)
+        .where('projection_state', 'in', ['effective', 'restored_out'])
+        .where('log_version', 'is not', null).executeTakeFirst();
+    return available?.head == null ? null : Number(available.head);
+}
+
+function entityTypeDefinitionsDDL(schema: string): string {
+    return `
+        CREATE TABLE ${qualifiedIdentifier(schema, 'entity_type_definitions')} (
+            "tenant_id" TEXT NOT NULL,
+            "log_id" TEXT NOT NULL,
+            "id" TEXT NOT NULL,
+            "name" TEXT NOT NULL,
+            "display_name" TEXT NOT NULL,
+            "table_name" TEXT NOT NULL,
+            "fields_json" TEXT NOT NULL,
+            "calendar_json" TEXT,
+            "is_archived" INTEGER DEFAULT 0,
+            "created_at" TEXT DEFAULT (datetime('now')),
+            "updated_at" TEXT DEFAULT (datetime('now')),
+            PRIMARY KEY ("tenant_id", "log_id", "id"),
+            UNIQUE ("tenant_id", "log_id", "name"),
+            UNIQUE ("tenant_id", "log_id", "table_name")
+        )
+    `;
+}

package/src/history/timeline.ts

@@ -0,0 +1,215 @@
+import { db, requireActiveContext } from '../db/index.js';
+import { sql } from 'kysely';
+import { eventLabel, getAdjacentHistoryPoint, getHistoryPointAtOrBefore, type HistoryPoint } from './history.js';
+import { EVENTS_EXCISED, WORKSPACE_RESTORED } from '@hearthlog/contracts/history/replay-selection';
+
+export interface HistoryBucket {
+    bucket: number;
+    count: number;
+    startVersion: number;
+    endVersion: number;
+    startTimestamp: number;
+    endTimestamp: number;
+}
+
+export interface HistoryActivity {
+    buckets: HistoryBucket[];
+    minVersion: number;
+    maxVersion: number;
+    maxCount: number;
+    firstTimestamp: number;
+    lastTimestamp: number;
+}
+
+export interface HistoryMarker {
+    id: string;
+    type: 'restore' | 'excision';
+    /** Accepted markers have a version; a pending local marker is legend-only. */
+    version: number | null;
+    timestamp: number;
+    label: string;
+    count: number;
+    active: boolean;
+}
+
+export interface HistoryGhost {
+    id: string;
+    version: number;
+    timestamp: number;
+    label: string;
+}
+
+/**
+ * Density series for the history scrubber. Bucketing and counting happen in
+ * SQLite over accepted complete-action boundaries; the UI never loads the log
+ * to draw the chart.
+ */
+export async function loadHistoryActivity(bucketCount = 96): Promise<HistoryActivity | null> {
+    const context = await requireActiveContext();
+    const buckets = Math.max(8, Math.min(240, Math.floor(bucketCount)));
+    const rows = await sql<{
+        bucket: number;
+        count: number;
+        start_version: number;
+        end_version: number;
+        start_timestamp: number;
+        end_timestamp: number;
+    }>`
+        WITH bounds AS (
+            SELECT MIN(log_version) AS min_v, MAX(log_version) AS max_v
+            FROM raw_events
+            WHERE tenant_id = ${context.tenantId}
+              AND log_id = ${context.logId}
+              AND log_version IS NOT NULL
+              AND projection_state IN ('effective', 'restored_out')
+              AND (action_id IS NULL OR action_index = action_size - 1)
+        )
+        SELECT
+            CAST((events.log_version - bounds.min_v) * ${buckets} / (bounds.max_v - bounds.min_v + 1) AS INTEGER) AS bucket,
+            COUNT(*) AS count,
+            MIN(events.log_version) AS start_version,
+            MAX(events.log_version) AS end_version,
+            MIN(events.timestamp) AS start_timestamp,
+            MAX(events.timestamp) AS end_timestamp
+        FROM raw_events events, bounds
+        WHERE events.tenant_id = ${context.tenantId}
+          AND events.log_id = ${context.logId}
+          AND events.log_version IS NOT NULL
+          AND events.projection_state IN ('effective', 'restored_out')
+          AND (events.action_id IS NULL OR events.action_index = events.action_size - 1)
+        GROUP BY bucket
+        ORDER BY bucket
+    `.execute(db);
+
+    if (rows.rows.length === 0) return null;
+    const first = rows.rows[0]!;
+    const last = rows.rows[rows.rows.length - 1]!;
+    const minVersion = Number(first.start_version);
+    const maxVersion = Number(last.end_version);
+    const series: HistoryBucket[] = rows.rows.map((row) => ({
+        bucket: Number(row.bucket),
+        count: Number(row.count),
+        startVersion: Number(row.start_version),
+        endVersion: Number(row.end_version),
+        startTimestamp: Number(row.start_timestamp),
+        endTimestamp: Number(row.end_timestamp),
+    }));
+    return {
+        buckets: series,
+        minVersion,
+        maxVersion,
+        maxCount: Math.max(1, ...series.map((bucket) => bucket.count)),
+        firstTimestamp: Number(first.start_timestamp),
+        lastTimestamp: Number(last.end_timestamp),
+    };
+}
+
+/** Restore and excision directives, positioned on the same version axis. */
+export async function loadHistoryMarkers(): Promise<HistoryMarker[]> {
+    const context = await requireActiveContext();
+    const rows = await db.selectFrom('raw_events')
+        .select(['id', 'type', 'timestamp', 'payload', 'log_version', 'projection_state', 'is_tombstoned'])
+        .where('tenant_id', '=', context.tenantId)
+        .where('log_id', '=', context.logId)
+        .where('type', 'in', [WORKSPACE_RESTORED, EVENTS_EXCISED])
+        .where('projection_state', 'in', ['effective', 'restored_out'])
+        .orderBy(sql`log_version is null`, 'asc')
+        .orderBy('log_version', 'asc')
+        .execute();
+    return rows.map((row) => {
+        let label = row.type === WORKSPACE_RESTORED ? 'Restored log' : 'Removed events';
+        let count = 1;
+        try {
+            const payload = JSON.parse(row.payload) as { targetVersion?: unknown; eventIds?: unknown };
+            if (row.type === WORKSPACE_RESTORED && typeof payload.targetVersion === 'number') {
+                label = `Restored log to v${payload.targetVersion}`;
+            }
+            if (row.type === EVENTS_EXCISED && Array.isArray(payload.eventIds)) {
+                count = payload.eventIds.length;
+                label = `Removed ${count} event${count === 1 ? '' : 's'}`;
+            }
+        } catch {
+            // Keep the fallback label for a malformed marker.
+        }
+        return {
+            id: row.id,
+            type: row.type === WORKSPACE_RESTORED ? 'restore' as const : 'excision' as const,
+            version: row.log_version ?? null,
+            timestamp: row.timestamp,
+            label,
+            count,
+            active: row.projection_state === 'effective' && row.is_tombstoned === 0,
+        };
+    });
+}
+
+/** Events hidden by a live excision, drawn as hollow ticks under the density. */
+export async function loadHistoryGhosts(limit = 300): Promise<HistoryGhost[]> {
+    const context = await requireActiveContext();
+    const markers = await db.selectFrom('raw_events')
+        .select('payload')
+        .where('tenant_id', '=', context.tenantId)
+        .where('log_id', '=', context.logId)
+        .where('type', '=', EVENTS_EXCISED)
+        .where('projection_state', '=', 'effective')
+        .where('is_tombstoned', '=', 0)
+        .execute();
+    const ids = new Set<string>();
+    for (const marker of markers) {
+        try {
+            const payload = JSON.parse(marker.payload) as { eventIds?: unknown };
+            if (Array.isArray(payload.eventIds)) {
+                for (const id of payload.eventIds) {
+                    if (typeof id === 'string') ids.add(id);
+                }
+            }
+        } catch {
+            // A malformed marker contributes no ghosts.
+        }
+    }
+    if (ids.size === 0) return [];
+    const rows = await db.selectFrom('raw_events')
+        .select(['id', 'type', 'timestamp', 'log_version'])
+        .where('tenant_id', '=', context.tenantId)
+        .where('log_id', '=', context.logId)
+        .where('id', 'in', [...ids])
+        .where('log_version', 'is not', null)
+        .orderBy('log_version', 'asc')
+        .limit(limit)
+        .execute();
+    return rows.map((row) => ({
+        id: row.id,
+        version: row.log_version!,
+        timestamp: row.timestamp,
+        label: eventLabel(row.type),
+    }));
+}
+
+/** Snap a free timeline position to the nearest selectable action boundary. */
+export async function resolveNearestHistoryPoint(version: number): Promise<HistoryPoint | null> {
+    const [before, after] = await Promise.all([
+        getHistoryPointAtOrBefore(version),
+        getAdjacentHistoryPoint(version, 'next'),
+    ]);
+    if (!before) return after;
+    if (!after) return before;
+    return Math.abs(before.version - version) <= Math.abs(after.version - version) ? before : after;
+}
+
+/** The nearest bucket for a free position, used by the scrubber tooltip. */
+export function nearestBucket(activity: HistoryActivity, version: number): HistoryBucket | null {
+    let best: HistoryBucket | null = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const bucket of activity.buckets) {
+        const distance = version < bucket.startVersion
+            ? bucket.startVersion - version
+            : version > bucket.endVersion
+                ? version - bucket.endVersion
+                : 0;
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = bucket;
+        }
+    }
+    return best;
+}

package/src/history/url.ts

@@ -0,0 +1,18 @@
+// `historyLimit` and `historySide` are no longer read; they stay listed so closing the panel clears old links.
+export const HISTORY_PARAMS = ['logPanel', 'historyAction', 'historyVersion', 'historySearch', 'historyFeature', 'historyLimit', 'historyStep', 'historySide', 'hiddenLogs'] as const;
+
+export function historyUrlState(url: URL) {
+    const version = Number(url.searchParams.get('historyVersion'));
+    const step = url.searchParams.get('historyStep');
+    return {
+        tab: url.searchParams.get('logPanel') === 'logs' ? 'logs' : 'history',
+        /** The action opened in place. */
+        action: url.searchParams.get('historyAction'),
+        version: Number.isSafeInteger(version) && version > 0 ? version : null,
+        search: url.searchParams.get('historySearch') ?? '',
+        feature: url.searchParams.get('historyFeature') ?? '',
+        /** `fork` starts a log after the opened action; `copy` after the latest one. */
+        step: step === 'review' || step === 'fork' ? 'fork' : step === 'copy' ? 'copy' : null,
+        showHidden: url.searchParams.get('hiddenLogs') === '1',
+    } as const;
+}