@hearthlog/runtime 0.0.0-stage → 0.1.0

package/src/ledger/version-tracker.ts

@@ -0,0 +1,259 @@
+/**
+ * Entity Version Tracker
+ * 
+ * Tracks entity versions in the local read model to support optimistic locking.
+ * Maintains a cache of current entity versions for fast lookups during event appends.
+ */
+
+import type { Kysely } from 'kysely';
+import { requireActiveContext, type Database } from '../db/index.js';
+import type { StoredEvent } from './types.js';
+
+/**
+ * Tracks entity versions in the local SQLite database
+ */
+export class EntityVersionTracker {
+  constructor(private readonly db: Kysely<Database>) {}
+
+  /**
+   * Gets the current version for an entity
+   * 
+   * @param entityId - The entity identifier
+   * @returns The current entity version, or null if the entity doesn't exist locally
+   */
+  async getCurrentVersion(entityId: string): Promise<number | null> {
+    const context = await requireActiveContext();
+    const result = await this.db
+      .selectFrom('entity_versions')
+      .select('current_version')
+      .where('tenant_id', '=', context.tenantId)
+      .where('log_id', '=', context.logId)
+      .where('entity_id', '=', entityId)
+      .executeTakeFirst();
+
+    return result?.current_version ?? null;
+  }
+
+  /**
+   * Updates the entity version after a successful append
+   * 
+   * @param entityId - The entity identifier
+   * @param entityVersion - The new entity version
+   * @param logVersion - The log version where this entity version was recorded
+   */
+  async updateVersion(
+    entityId: string,
+    entityVersion: number,
+    logVersion: number
+  ): Promise<void> {
+    console.log('[VersionTracker] Updating version for entity', entityId, 'to', entityVersion);
+    
+    try {
+      const now = Date.now();
+      const context = await requireActiveContext();
+
+      await this.db
+        .insertInto('entity_versions')
+        .values({
+          tenant_id: context.tenantId,
+          log_id: context.logId,
+          entity_id: entityId,
+          current_version: entityVersion,
+          log_version: logVersion,
+          updated_at: now
+        })
+        .onConflict((oc) =>
+          oc.columns(['tenant_id', 'log_id', 'entity_id']).doUpdateSet({
+            current_version: entityVersion,
+            log_version: logVersion,
+            updated_at: now
+          })
+        )
+        .execute();
+      
+      console.log('[VersionTracker] Version updated successfully');
+    } catch (error) {
+      console.error('[VersionTracker] Failed to update version for entity', entityId, ':', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Batch updates entity versions from incoming events
+   * 
+   * @param events - Array of stored events to process
+   */
+  async updateVersionsFromEvents(events: StoredEvent[]): Promise<void> {
+    if (events.length === 0) {
+      console.log('[VersionTracker] No events to update versions from');
+      return;
+    }
+
+    console.log('[VersionTracker] Updating versions from', events.length, 'events');
+    const now = Date.now();
+    const context = await requireActiveContext();
+
+    try {
+      // Six columns x 100 events remain below the conservative 999-bind limit.
+      // SQLite resolves repeated entities and older notifications monotonically.
+      await this.db.transaction().execute(async (trx) => {
+        for (let offset = 0; offset < events.length; offset += 100) {
+          await trx
+            .insertInto('entity_versions')
+            .values(events.slice(offset, offset + 100).map(event => ({
+              tenant_id: context.tenantId,
+              log_id: context.logId,
+              entity_id: event.entityId,
+              current_version: event.entityVersion,
+              log_version: event.version,
+              updated_at: now
+            })))
+            .onConflict((oc) =>
+              oc.columns(['tenant_id', 'log_id', 'entity_id']).doUpdateSet(eb => ({
+                current_version: eb.fn('max', ['current_version', eb.ref('excluded.current_version')]),
+                log_version: eb.fn('max', ['log_version', eb.ref('excluded.log_version')]),
+                updated_at: now
+              }))
+            )
+            .execute();
+        }
+      });
+      
+      console.log('[VersionTracker] Version updates completed successfully');
+    } catch (error) {
+      console.error('[VersionTracker] Failed to update versions from events:', error);
+      if (error instanceof Error) {
+        console.error('[VersionTracker] Error message:', error.message);
+        console.error('[VersionTracker] Error stack:', error.stack);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Rebuilds the entity version cache from raw_events table
+   * 
+   * This is useful for recovering from cache corruption or initializing
+   * the cache after a database migration.
+   */
+  async rebuildVersionCache(): Promise<void> {
+    console.log('[VersionTracker] Rebuilding version cache from raw_events');
+    
+    try {
+      // Clear existing cache
+      const context = await requireActiveContext();
+      await this.db.deleteFrom('entity_versions')
+        .where('tenant_id', '=', context.tenantId)
+        .where('log_id', '=', context.logId)
+        .execute();
+      console.log('[VersionTracker] Cleared existing version cache');
+
+      // Query all events with entity information, ordered by entity and version
+      const events = await this.db
+        .selectFrom('raw_events')
+        .select(['entity_id', 'entity_version', 'log_version', 'timestamp'])
+        .where('tenant_id', '=', context.tenantId)
+        .where('log_id', '=', context.logId)
+        .where('sync_state', '=', 'synced')
+        .where('entity_id', 'is not', null)
+        .where('entity_version', 'is not', null)
+        .where('log_version', 'is not', null)
+        .orderBy('entity_id', 'asc')
+        .orderBy('entity_version', 'asc')
+        .execute();
+
+      console.log('[VersionTracker] Found', events.length, 'events with entity version data');
+
+      if (events.length === 0) {
+        console.log('[VersionTracker] No events to rebuild from');
+        return;
+      }
+
+      // Group by entity and find the maximum version for each
+      const entityVersions = new Map<
+        string,
+        { currentVersion: number; logVersion: number; updatedAt: number }
+      >();
+
+      for (const event of events) {
+        if (event.entity_id && event.entity_version !== null) {
+          const existing = entityVersions.get(event.entity_id);
+          if (event.log_version === null) {
+            continue;
+          }
+
+          if (!existing || event.entity_version > existing.currentVersion) {
+            entityVersions.set(event.entity_id, {
+              currentVersion: event.entity_version,
+              logVersion: event.log_version,
+              updatedAt: event.timestamp
+            });
+          }
+        }
+      }
+
+      console.log('[VersionTracker] Rebuilding cache for', entityVersions.size, 'entities');
+
+      // Insert all entity versions in a transaction
+      if (entityVersions.size > 0) {
+        await this.db.transaction().execute(async (trx) => {
+          const values = Array.from(entityVersions.entries()).map(
+            ([entityId, { currentVersion, logVersion, updatedAt }]) => ({
+              tenant_id: context.tenantId,
+              log_id: context.logId,
+              entity_id: entityId,
+              current_version: currentVersion,
+              log_version: logVersion,
+              updated_at: updatedAt
+            })
+          );
+
+          // Insert in batches to avoid hitting SQLite limits
+          const batchSize = 100;
+          for (let i = 0; i < values.length; i += batchSize) {
+            const batch = values.slice(i, i + batchSize);
+            await trx.insertInto('entity_versions').values(batch).execute();
+            console.log('[VersionTracker] Inserted batch of', batch.length, 'entity versions');
+          }
+        });
+        
+        console.log('[VersionTracker] Version cache rebuild completed successfully');
+      }
+    } catch (error) {
+      console.error('[VersionTracker] Failed to rebuild version cache:', error);
+      if (error instanceof Error) {
+        console.error('[VersionTracker] Error message:', error.message);
+        console.error('[VersionTracker] Error stack:', error.stack);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Gets all entity versions (useful for debugging)
+   * 
+   * @returns Map of entity IDs to their current versions
+   */
+  async getAllVersions(): Promise<Map<string, number>> {
+    const context = await requireActiveContext();
+    const results = await this.db
+      .selectFrom('entity_versions')
+      .select(['entity_id', 'current_version'])
+      .where('tenant_id', '=', context.tenantId)
+      .where('log_id', '=', context.logId)
+      .execute();
+
+    return new Map(results.map((r) => [r.entity_id, r.current_version]));
+  }
+
+  /**
+   * Clears all entity version data (useful for testing)
+   */
+  async clear(): Promise<void> {
+    const context = await requireActiveContext();
+    await this.db.deleteFrom('entity_versions')
+      .where('tenant_id', '=', context.tenantId)
+      .where('log_id', '=', context.logId)
+      .execute();
+  }
+}

package/src/log-management.ts

@@ -0,0 +1,123 @@
+import { invalidate } from "$app/navigation";
+import { MODULE_REFRESH_KEYS } from '#generated/modules';
+import {
+    getLedgerClient,
+    type CreateLogResponse,
+    type LogSummary,
+} from "./ledger/index.js";
+import { db, requireActiveContext } from './db/index.js';
+import { eventLogFilename } from "./store/event-log.svelte.js";
+import { logs } from "./store/logs.svelte.js";
+import {
+    loadStoredLogSnapshot,
+    runSyncCoordinator,
+    stopRealtime,
+    syncStatus,
+} from "./store/sync.svelte.js";
+import {
+    beginReadTargetTransition,
+    cancelReadTargetTransition,
+} from "./runtime/read-coordinator.js";
+import { validateNewLogName } from "./log-validation.js";
+
+async function invalidateAllViews(): Promise<void> {
+    await Promise.all([
+        ...MODULE_REFRESH_KEYS.map((key) => invalidate(key)),
+        invalidate("app:entities"),
+        invalidate("app:entity-types"),
+    ]);
+}
+
+/** Resume copying inherited private files; safe to call after an interrupted tab. */
+export async function prepareForkFiles(logId: string, onProgress?: (message: string) => void): Promise<void> {
+    let status = 'preparing';
+    while (status !== 'ready') {
+        const response = await fetch(`/api/log-forks/v1/${logId}/prepare`, { method: 'POST' });
+        const result = await response.json() as { status?: string; error?: string; remaining?: number };
+        if (!response.ok) throw new Error(result.error ?? 'Could not prepare this fork.');
+        status = result.status ?? 'preparing';
+        if (status !== 'ready') {
+            if (status !== 'preparing' || !Number.isSafeInteger(result.remaining) || (result.remaining ?? 0) < 1) {
+                throw new Error('Fork preparation did not report progress. Try again.');
+            }
+            onProgress?.(`Preparing documents… ${result.remaining} remaining`);
+        }
+    }
+}
+
+/** Create a server log and make its empty read model active in this tab. */
+export async function createAndActivateLog(name: string): Promise<CreateLogResponse> {
+    const normalized = validateNewLogName(name, logs.value);
+    const response = await getLedgerClient().createLog({ name: normalized });
+
+    await logs.refresh();
+
+    let transitionStarted = false;
+    try {
+        beginReadTargetTransition();
+        transitionStarted = true;
+        await stopRealtime();
+        await eventLogFilename.set(response.id, response.name || normalized);
+        await loadStoredLogSnapshot(response.id, []);
+        await runSyncCoordinator("manual");
+        await invalidateAllViews();
+        return response;
+    } catch (error) {
+        if (transitionStarted) cancelReadTargetTransition();
+        throw error;
+    }
+}
+
+/** Fork a synchronized accepted prefix, prepare private files, then activate it locally. */
+export async function forkAndActivateLog(input: {
+    name: string;
+    targetVersion: number;
+    expectedSourceHeadVersion: number;
+    requestId: string;
+    onProgress?: (message: string) => void;
+}): Promise<LogSummary> {
+    if (typeof navigator !== 'undefined' && !navigator.onLine) throw new Error('Connect to fork this log.');
+    const context = await requireActiveContext();
+    const sourceLogId = context.logId;
+    const normalized = validateNewLogName(input.name, logs.value.filter(log => log.status !== 'preparing'));
+    input.onProgress?.('Checking accepted changes…');
+    await runSyncCoordinator('manual');
+    const pending = await db.selectFrom('raw_events').select('id')
+        .where('tenant_id', '=', context.tenantId).where('log_id', '=', sourceLogId)
+        .where(eb => eb.or([eb('projection_state', '=', 'pending_ddl'), eb.and([
+            eb('log_version', 'is', null), eb('sync_state', 'in', ['pending', 'conflicted']),
+        ])])).executeTakeFirst();
+    const progress = await db.selectFrom('log_sync_state').selectAll()
+        .where('tenant_id', '=', context.tenantId).where('log_id', '=', sourceLogId).executeTakeFirst();
+    if (pending || syncStatus.pendingUploads > 0 || !progress
+        || progress.downloaded_head_version !== progress.projected_head_version
+        || progress.projected_head_version !== input.expectedSourceHeadVersion) {
+        throw new Error('Finish synchronizing this log, then review the fork point again.');
+    }
+    const client = getLedgerClient();
+    input.onProgress?.('Creating the new log…');
+    const fork = await client.forkLog(sourceLogId, {
+        name: normalized,
+        targetVersion: input.targetVersion,
+        expectedSourceHeadVersion: input.expectedSourceHeadVersion,
+        requestId: input.requestId,
+    });
+    input.onProgress?.('Preparing documents…');
+    if (fork.status !== 'ready') await prepareForkFiles(fork.id, input.onProgress);
+    input.onProgress?.('Opening the new log…');
+    await logs.refresh();
+    let transitionStarted = false;
+    try {
+        beginReadTargetTransition();
+        transitionStarted = true;
+        await stopRealtime();
+        await eventLogFilename.set(fork.id, fork.name);
+        await loadStoredLogSnapshot(fork.id, []);
+        await runSyncCoordinator('manual');
+        await invalidateAllViews();
+        return { ...fork, status: 'ready' };
+    } catch (cause) {
+        if (transitionStarted) cancelReadTargetTransition();
+        throw new Error(`The new log is ready, but could not be opened. Select it from the log switcher. ${cause instanceof Error ? cause.message : ''}`);
+    }
+}

package/src/log-validation.ts

@@ -0,0 +1,19 @@
+import type { LogSummary } from "./ledger/index.js";
+
+function logNamesMatch(left: string, right: string): boolean {
+    return left.trim().toLocaleLowerCase() === right.trim().toLocaleLowerCase();
+}
+
+export function validateNewLogName(
+    name: string,
+    existingLogs: readonly LogSummary[],
+): string {
+    const normalized = name.trim();
+    if (!normalized) throw new Error("Enter a log name.");
+
+    if (existingLogs.some((log) => logNamesMatch(log.name, normalized))) {
+        throw new Error(`A log named "${normalized}" already exists.`);
+    }
+
+    return normalized;
+}

package/src/native/reminders.ts

@@ -0,0 +1,2 @@
+/** Reminders fire at nine in the morning, device time. */
+export const REMINDER_HOUR = '09:00';

package/src/native/shell.svelte.ts

@@ -0,0 +1,136 @@
+import { goto } from '$app/navigation';
+import { buildNavigation } from '@hearthlog/contracts/features/navigation';
+import { FEATURES } from '@hearthlog/contracts/features/registry';
+import { onShellEvent, shell, shellApi, type ShellMenuEntry } from './shell.js';
+import { workspaceIsReady, workspaceReadiness } from '@hearthlog/ui/state/readiness.js';
+import { appClock } from '../runtime/view.js';
+import { attention } from '../store/attention.svelte.js';
+import { eventLogFilename } from '../store/event-log.svelte.js';
+import { events } from '../store/events.svelte.js';
+import { notificationState } from '@hearthlog/ui/state/notifications.svelte.js';
+import { syncStatus } from '../store/sync.svelte.js';
+import { APPEARANCE_EVENT, appearance } from '../theme/appearance.svelte.js';
+import { isFeatureEnabled, tenant } from '@hearthlog/contracts/tenant/config';
+
+const REMINDER_DEBOUNCE_MS = 1_500;
+/** An in-app route: absolute, same origin, never `//host`. */
+function isAppPath(path: unknown): path is string {
+    return typeof path === 'string' && path.startsWith('/') && !path.startsWith('//');
+}
+
+function menuEntries(): { destinations: ShellMenuEntry[]; actions: ShellMenuEntry[] } {
+    const destinations = buildNavigation(tenant).sections.map(({ id, label, path, children }) => ({
+        id,
+        title: label,
+        path,
+        children: children?.map((child) => ({ id: child.id, title: child.label, path: child.href })),
+    }));
+    const actions = FEATURES
+        .filter((feature) => isFeatureEnabled(feature.id))
+        .flatMap((feature) => feature.commands.map((command) => ({
+            id: command.id,
+            title: command.label,
+            path: command.href ?? `${feature.page?.path ?? '/'}${command.query ?? ''}`,
+        })));
+    return { destinations, actions };
+}
+
+async function refreshReminders(): Promise<void> {
+    if (!workspaceIsReady()) return;
+    shellApi.reminders(await attention.reminders(appClock.now()));
+}
+
+function reportAppearance(): void {
+    const background = getComputedStyle(document.documentElement).getPropertyValue('--stor-bg').trim();
+    shellApi.appearance(appearance.preference, appearance.resolved, background);
+}
+
+/**
+ * Where the Mac window controls belong. The sidebar's brand row reserves an empty
+ * `[data-stor-lights]` anchor for them, so the layout, not this code, decides the
+ * position; it follows the sidebar while it opens, closes and resizes.
+ */
+function trackWindowControls(): () => void {
+    let frame = 0;
+    const report = () => {
+        frame = 0;
+        const anchor = document.querySelector('[data-stor-lights]');
+        const rect = anchor?.getBoundingClientRect();
+        if (!rect || rect.width === 0) return;
+        shellApi.lights(Math.round(rect.left * 2) / 2, rect.top + rect.height / 2);
+    };
+    const schedule = () => { frame ||= requestAnimationFrame(report); };
+    const observer = new ResizeObserver(schedule);
+    observer.observe(document.documentElement);
+    const sidebar = document.querySelector('[data-testid="desktop-sidebar"]');
+    if (sidebar) observer.observe(sidebar);
+    schedule();
+    return () => {
+        observer.disconnect();
+        if (frame) cancelAnimationFrame(frame);
+    };
+}
+
+/**
+ * Connects the page to the native shell when there is one: native chrome follows the
+ * theme, menus and the app badge mirror what the page knows, reminders are scheduled
+ * on the device, and the shell can open routes. In a browser this returns at once.
+ */
+export function startNativeShell({ toggleSidebar }: { toggleSidebar: () => void }): (() => void) | undefined {
+    if (!shell) return undefined;
+    const cleanups: Array<() => void> = [];
+
+    cleanups.push(onShellEvent((event) => {
+        if (event.type === 'navigate') {
+            if (isAppPath(event.path)) void goto(event.path);
+        } else if (event.type === 'toggle-sidebar') {
+            toggleSidebar();
+        } else if (event.type === 'resume') {
+            scheduleReminders();
+        }
+    }));
+
+    window.addEventListener(APPEARANCE_EVENT, reportAppearance);
+    cleanups.push(() => window.removeEventListener(APPEARANCE_EVENT, reportAppearance));
+    reportAppearance();
+
+    const { destinations, actions } = menuEntries();
+    shellApi.menu(destinations, actions);
+
+    if (shell.kind === 'mac') {
+        cleanups.push(trackWindowControls());
+    }
+
+    let reminderTimer: ReturnType<typeof setTimeout> | undefined;
+    const scheduleReminders = () => {
+        clearTimeout(reminderTimer);
+        reminderTimer = setTimeout(() => { void refreshReminders().catch(() => undefined); }, REMINDER_DEBOUNCE_MS);
+    };
+    cleanups.push(() => clearTimeout(reminderTimer));
+    // The date moves on while the app sleeps, so plan again whenever it wakes.
+    const onVisible = () => { if (document.visibilityState === 'visible') scheduleReminders(); };
+    document.addEventListener('visibilitychange', onVisible);
+    cleanups.push(() => document.removeEventListener('visibilitychange', onVisible));
+    cleanups.push(workspaceReadiness.subscribe((state) => { if (state.ready) scheduleReminders(); }));
+
+    let lastHaptic = '';
+    cleanups.push($effect.root(() => {
+        $effect(() => { shellApi.badge(attention.total); });
+        $effect(() => { shellApi.outbox(syncStatus.pendingUploads); });
+        $effect(() => {
+            const latest = notificationState.items.at(-1);
+            if (!latest || latest.id === lastHaptic) return;
+            lastHaptic = latest.id;
+            if (latest.type === 'success') shellApi.haptic('success');
+            else if (latest.type === 'error') shellApi.haptic('warning');
+        });
+        // Re-plan after every event change and log switch.
+        $effect(() => {
+            void events.updatedAt;
+            void eventLogFilename.value;
+            scheduleReminders();
+        });
+    }));
+
+    return () => cleanups.forEach((cleanup) => cleanup());
+}

package/src/native/shell.ts

@@ -0,0 +1,102 @@
+/**
+ * Bridge to the native Mac and iOS shell (`apple/`).
+ *
+ * The shell is a thin WKWebView host that loads this same site. It defines
+ * `window.storShell` before any page script runs and listens on the `stor`
+ * script message handler. In a browser both are absent, so every function here
+ * does nothing and callers never branch on the platform.
+ *
+ * Only small values the page already shows cross the bridge: counts, dates,
+ * titles and screen positions. Events, rows and credentials never do.
+ */
+
+export type ShellKind = 'mac' | 'ios';
+
+export interface ShellInfo {
+    readonly kind: ShellKind;
+    readonly site: string;
+    readonly version: number;
+    /** Mac: points the window buttons take, so the sidebar can leave exactly that much room. */
+    readonly lights?: number;
+}
+
+export interface ShellMenuEntry {
+    id: string;
+    title: string;
+    path: string;
+    /** A section's sub-pages; the Mac Dock menu shows them as a submenu. */
+    children?: readonly ShellMenuEntry[];
+}
+
+export interface ShellReminder {
+    id: string;
+    title: string;
+    body: string;
+    /** Local wall-clock time, `YYYY-MM-DDTHH:mm`; the device's time zone applies. */
+    at: string;
+    /** Route opened when the notification is tapped. */
+    path: string;
+}
+
+/** Events the shell sends to the page (`window` event `stor-shell`). */
+export type ShellEvent =
+    | { type: 'navigate'; path: string }
+    | { type: 'toggle-sidebar' }
+    | { type: 'resume' };
+
+export const SHELL_EVENT = 'stor-shell';
+
+declare global {
+    interface Window {
+        storShell?: ShellInfo;
+        webkit?: { messageHandlers?: { stor?: { postMessage(message: unknown): void } } };
+    }
+}
+
+export const shell: ShellInfo | null = typeof window === 'undefined' ? null : (window.storShell ?? null);
+
+function post(type: string, body: Record<string, unknown> = {}): void {
+    if (!shell) return;
+    try {
+        window.webkit?.messageHandlers?.stor?.postMessage({ type, body });
+    } catch {
+        // The shell is advisory: a failed message never blocks the page.
+    }
+}
+
+export const shellApi = {
+    /** Lets native chrome (window material, status bar, sheets) follow the page's theme. */
+    appearance(preference: 'light' | 'dark' | 'system', resolved: 'light' | 'dark', background: string): void {
+        post('appearance', { preference, resolved, background });
+    },
+    /** App icon badge: late work, the same count as the navigation badges. */
+    badge(count: number): void {
+        post('badge', { count });
+    },
+    /** Replaces every scheduled reminder with this list. */
+    reminders(items: readonly ShellReminder[]): void {
+        post('reminders', { items });
+    },
+    /** Menu bar entries (Mac): the sections the tenant has, and its create shortcuts. */
+    menu(destinations: readonly ShellMenuEntry[], actions: readonly ShellMenuEntry[]): void {
+        post('menu', { destinations, actions });
+    },
+    /** Where the window controls belong: left edge of the first one and the vertical centre, in CSS pixels. */
+    lights(x: number, y: number): void {
+        post('lights', { x, y });
+    },
+    /** Changes still waiting to upload; iOS keeps the app alive a little longer while there are some. */
+    outbox(pending: number): void {
+        post('outbox', { pending });
+    },
+    haptic(kind: 'success' | 'warning'): void {
+        post('haptic', { kind });
+    },
+};
+
+export function onShellEvent(handler: (event: ShellEvent) => void): () => void {
+    if (typeof window === 'undefined') return () => {};
+    const listener = (event: Event) => handler((event as CustomEvent<ShellEvent>).detail);
+    window.addEventListener(SHELL_EVENT, listener);
+    return () => window.removeEventListener(SHELL_EVENT, listener);
+}