@hearthlog/runtime 0.0.0-stage → 0.1.1

package/src/store/local-context.ts

@@ -0,0 +1,93 @@
+import { get as getKv, set as setKv } from '../db/kv.js';
+import {
+    clearActiveContext,
+    getActiveContext,
+    setActiveContext,
+    type ActiveContext,
+} from '../db/index.js';
+import { getLedgerClient, loadLedgerConfig, type SessionResponse } from '../ledger/index.js';
+import { tenant } from '@hearthlog/contracts/tenant/config';
+
+interface CachedSession extends SessionResponse {
+    ledgerOrigin: string;
+}
+
+export function getLedgerOrigin(): string {
+    const baseUrl = loadLedgerConfig().baseUrl;
+    const browserOrigin =
+        typeof globalThis.location === 'undefined'
+            ? 'http://localhost'
+            : globalThis.location.origin;
+    const url = new URL(baseUrl, browserOrigin);
+    return `${url.origin}${url.pathname.replace(/\/$/, '')}`;
+}
+
+export async function getLedgerCredentialFingerprint(): Promise<string> {
+    const { authToken } = loadLedgerConfig();
+    const credentialIdentity = authToken ?? `worker-managed:${getLedgerOrigin()}`;
+    const bytes = new TextEncoder().encode(credentialIdentity);
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    return [...new Uint8Array(digest)]
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+}
+
+export async function getLedgerCacheKey(resource: string): Promise<string> {
+    // The origin is stable when a tenant's frontend is redeployed. Include the
+    // compiled tenant identity so a pre-isolation cache cannot carry a log or
+    // session selection into the newly isolated tenant build.
+    return `ledger-${resource}:${tenant.id}:${getLedgerOrigin()}:${await getLedgerCredentialFingerprint()}`;
+}
+
+export async function resolveLedgerSession(): Promise<CachedSession> {
+    const cacheKey = await getLedgerCacheKey('session');
+    const cached = await getKv<CachedSession>(cacheKey);
+    // Reuse only this namespace's verified session when explicitly offline.
+    // An online/unknown hint still follows the normal verification policy.
+    if (cached && typeof navigator !== 'undefined' && navigator.onLine === false) {
+        return cached;
+    }
+    const { authToken } = loadLedgerConfig();
+    if (cached && authToken) {
+        void getLedgerClient().getSession()
+            .then((session) => setKv(cacheKey, { ...session, ledgerOrigin: getLedgerOrigin() }))
+            .catch(() => undefined);
+        return cached;
+    }
+
+    try {
+        const session = await getLedgerClient().getSession();
+        const verified = { ...session, ledgerOrigin: getLedgerOrigin() };
+        await setKv(cacheKey, verified);
+        return verified;
+    } catch (error) {
+        if (cached) return cached;
+        throw new Error(
+            'This Ledger credential must be verified online before its offline data can be opened',
+            { cause: error },
+        );
+    }
+}
+
+export async function activateLogContext(logId: string): Promise<ActiveContext> {
+    if (!logId) throw new Error('Cannot activate an empty Ledger log ID');
+    const session = await resolveLedgerSession();
+    const context: ActiveContext = {
+        tenantId: session.appId,
+        principalId: session.principalId,
+        logId,
+        ledgerOrigin: session.ledgerOrigin,
+    };
+    await setActiveContext(context);
+    // Reload in-memory dynamic registry for this log (definitions are log-scoped)
+    const { loadDynamicEntityTypes } = await import('../event/dynamic-entities.js');
+    await loadDynamicEntityTypes();
+    return context;
+}
+
+export async function deactivateLogContext(): Promise<void> {
+    await clearActiveContext();
+}
+
+export { getActiveContext };
+export { getSessionContext, setSessionContext } from '../db/session-context.js';

package/src/store/local-store.svelte.ts

@@ -0,0 +1,58 @@
+export type LocalStorePhase = 'booting' | 'ready' | 'degraded' | 'failed';
+
+export interface LocalStoreStatus {
+    phase: LocalStorePhase;
+    activeLogId: string | null;
+    schemaVersion: number | null;
+    schemaRebuilt: boolean;
+    errorMessage: string | null;
+    readyAt: Date | null;
+}
+
+export const localStoreStatus = $state<LocalStoreStatus>({
+    phase: 'booting',
+    activeLogId: null,
+    schemaVersion: null,
+    schemaRebuilt: false,
+    errorMessage: null,
+    readyAt: null,
+});
+
+export function markLocalStoreBooting(): void {
+    localStoreStatus.phase = 'booting';
+    localStoreStatus.errorMessage = null;
+}
+
+export function markLocalStoreReady(input: {
+    activeLogId: string;
+    schemaVersion: number;
+    schemaRebuilt: boolean;
+}): void {
+    localStoreStatus.phase = 'ready';
+    localStoreStatus.activeLogId = input.activeLogId;
+    localStoreStatus.schemaVersion = input.schemaVersion;
+    localStoreStatus.schemaRebuilt = input.schemaRebuilt;
+    localStoreStatus.errorMessage = null;
+    localStoreStatus.readyAt = new Date();
+}
+
+export function markLocalStoreDegraded(input: {
+    message: string;
+    schemaVersion: number;
+}): void {
+    localStoreStatus.phase = 'degraded';
+    localStoreStatus.activeLogId = null;
+    localStoreStatus.schemaVersion = input.schemaVersion;
+    localStoreStatus.schemaRebuilt = false;
+    localStoreStatus.errorMessage = input.message;
+    localStoreStatus.readyAt = new Date();
+}
+
+export function markLocalStoreFailed(error: unknown): void {
+    localStoreStatus.phase = 'failed';
+    localStoreStatus.errorMessage = error instanceof Error
+        ? error.message
+        : 'The local database could not be opened';
+    localStoreStatus.readyAt = null;
+}
+

package/src/store/log-version.svelte.ts

@@ -0,0 +1,35 @@
+import { db, requireActiveContext } from '../db/index.js';
+
+/**
+ * The active log's version as this device sees it: the contiguous accepted head
+ * plus the local actions that have no version yet, so saving moves the number
+ * before sync catches up. `null` while local data is not open.
+ */
+export const logVersion = $state<{ value: number | null }>({ value: null });
+
+export async function refreshLogVersion(logId: string | null): Promise<void> {
+    if (!logId) {
+        logVersion.value = null;
+        return;
+    }
+    try {
+        const context = await requireActiveContext();
+        const [head, pending] = await Promise.all([
+            db.selectFrom('log_sync_state')
+                .select('downloaded_head_version')
+                .where('tenant_id', '=', context.tenantId)
+                .where('log_id', '=', logId)
+                .executeTakeFirst(),
+            db.selectFrom('raw_events')
+                .select((eb) => eb.fn.count('id').as('count'))
+                .where('tenant_id', '=', context.tenantId)
+                .where('log_id', '=', logId)
+                .where('log_version', 'is', null)
+                .where('projection_state', '=', 'effective')
+                .executeTakeFirst(),
+        ]);
+        logVersion.value = (head?.downloaded_head_version ?? 0) + Number(pending?.count ?? 0);
+    } catch {
+        logVersion.value = null;
+    }
+}

package/src/store/logs.svelte.ts

@@ -0,0 +1,60 @@
+import { getLedgerClient, type LogLineageIndex, type LogListResponse, type LogSummary } from "../ledger/index.js";
+import { get as getKv, set as setKv } from '../db/kv.js';
+import { getLedgerCacheKey } from './local-context.js';
+
+class LogsStore {
+  #value = $state<LogSummary[]>([]);
+  #lineage = $state<LogLineageIndex | null>(null);
+
+  get value() {
+    return this.#value;
+  }
+
+  get lineage() {
+    return this.#lineage;
+  }
+
+  get names() {
+    return this.#value.map((log) => log.name);
+  }
+
+  async loadCached() {
+    try {
+      const cached = await getKv<LogListResponse | LogSummary[]>(await getLedgerCacheKey('logs'));
+      if (Array.isArray(cached)) {
+        this.#value = cached;
+        this.#lineage = null;
+      } else if (cached) {
+        this.#value = cached.logs;
+        this.#lineage = cached.lineage ?? null;
+      }
+    } catch {
+      // A missing credential has no safe cache namespace.
+    }
+  }
+
+  /** Hides or shows a log in the tree. The list updates once Ledger confirms. */
+  async setHidden(logId: string, hidden: boolean) {
+    const updated = await getLedgerClient().setLogVisibility(logId, hidden);
+    this.#value = this.#value.map((log) => (log.id === logId ? { ...log, hiddenAt: updated.hiddenAt ?? null } : log));
+    try {
+      await setKv(await getLedgerCacheKey('logs'), { logs: this.#value, lineage: this.#lineage ?? undefined });
+    } catch {
+      // The next refresh rewrites the cache.
+    }
+  }
+
+  async refresh() {
+    await this.loadCached();
+    try {
+      const response = await getLedgerClient().listLogsResponse();
+      this.#value = response.logs;
+      this.#lineage = response.lineage ?? null;
+      await setKv(await getLedgerCacheKey('logs'), response);
+    } catch (e) {
+      // ignore refresh errors; UI will keep last known list
+    }
+  }
+}
+
+export const logs = new LogsStore();

package/src/store/moved.svelte.ts

@@ -0,0 +1,43 @@
+import { del, get, set } from '../db/kv.js';
+import { isLedgerServiceError } from '../ledger/errors.js';
+
+/**
+ * A workspace that moved to another origin. The old origin's Ledger answers
+ * writes with 410 `tenant_moved`; this device then stops sending, keeps its
+ * queued work, and offers to export it (see pending-work.ts). The flag is kept
+ * on the device so a reload does not start sending again.
+ */
+
+const KEY = 'stor:workspace-moved';
+
+export interface MovedWorkspace {
+    /** The origin the workspace lives at now, when the old one said so. */
+    destination: string | null;
+    detectedAt: string;
+}
+
+export const movedWorkspace = $state<{ value: MovedWorkspace | null }>({ value: null });
+
+/** The destination named by a "moved" answer, or null when the error is anything else. */
+export function movedDestination(error: unknown): { destination: string | null } | null {
+    if (!isLedgerServiceError(error) || error.statusCode !== 410 || error.code !== 'tenant_moved') return null;
+    const destination = (error.response as { destination?: unknown } | undefined)?.destination;
+    return { destination: typeof destination === 'string' ? destination : null };
+}
+
+export async function markWorkspaceMoved(destination: string | null): Promise<void> {
+    if (movedWorkspace.value) return;
+    const moved: MovedWorkspace = { destination, detectedAt: new Date().toISOString() };
+    movedWorkspace.value = moved;
+    await set(KEY, moved).catch(() => undefined);
+}
+
+export async function restoreMovedWorkspace(): Promise<void> {
+    movedWorkspace.value = await get<MovedWorkspace>(KEY).catch(() => null);
+}
+
+/** Sending again after the operator lifted the fence, or when this origin turns out to be the new home. */
+export async function clearMovedWorkspace(): Promise<void> {
+    movedWorkspace.value = null;
+    await del(KEY).catch(() => undefined);
+}

package/src/store/offline-readiness.svelte.ts

@@ -0,0 +1,188 @@
+export type OfflineReadinessPhase =
+    | 'checking'
+    | 'installing'
+    | 'available'
+    | 'unavailable'
+    | 'unsupported'
+    | 'failed';
+
+export interface OfflineReadinessState {
+    phase: OfflineReadinessPhase;
+    errorMessage: string | null;
+    checkedAt: number | null;
+}
+
+interface CacheRequirement {
+    label: string;
+    path: RegExp;
+    contentType: RegExp;
+}
+
+interface OfflineReadinessDependencies {
+    serviceWorker?: Pick<ServiceWorkerContainer, 'getRegistration'> | null;
+    cacheStorage?: CacheStorage | null;
+    now?: () => number;
+}
+
+const REQUIRED_CORE_CACHE_ENTRIES: readonly CacheRequirement[] = [
+    { label: 'application fallback', path: /\/index\.html$/, contentType: /text\/html/i },
+    {
+        label: 'application entry',
+        path: /\/_app\/immutable\/entry\/app\.[^/]+\.js$/,
+        contentType: /(?:java|ecma)script/i,
+    },
+    {
+        label: 'SQLocal worker',
+        path: /\/_app\/immutable\/workers\/worker-[^/]+\.js$/,
+        contentType: /(?:java|ecma)script/i,
+    },
+    {
+        label: 'SQLocal worker chunk',
+        path: /\/_app\/immutable\/workers\/chunks\/[^/]+\.js$/,
+        contentType: /(?:java|ecma)script/i,
+    },
+    {
+        label: 'SQLite OPFS proxy',
+        path: /\/_app\/immutable\/workers\/sqlite3-opfs-async-proxy-[^/]+\.js$/,
+        contentType: /(?:java|ecma)script/i,
+    },
+    {
+        label: 'SQLite WASM',
+        path: /\/_app\/immutable\/workers\/assets\/sqlite3[.-][^/]+\.wasm$/,
+        contentType: /application\/wasm/i,
+    },
+];
+
+export const offlineReadiness = $state<OfflineReadinessState>({
+    phase: 'checking',
+    errorMessage: null,
+    checkedAt: null,
+});
+
+function updateOfflineReadiness(
+    phase: OfflineReadinessPhase,
+    errorMessage: string | null,
+    checkedAt: number | null = Date.now(),
+): void {
+    offlineReadiness.phase = phase;
+    offlineReadiness.errorMessage = errorMessage;
+    offlineReadiness.checkedAt = checkedAt;
+}
+
+export function markOfflineReadinessInstalling(): void {
+    updateOfflineReadiness('installing', null, null);
+}
+
+export function markOfflineReadinessFailed(error: unknown): void {
+    updateOfflineReadiness(
+        'failed',
+        error instanceof Error ? error.message : 'The offline bundle could not be installed.',
+    );
+}
+
+export async function checkOfflineReadiness(
+    dependencies: OfflineReadinessDependencies = {},
+): Promise<void> {
+    const serviceWorker = dependencies.serviceWorker === undefined
+        ? (typeof navigator !== 'undefined' && 'serviceWorker' in navigator
+            ? navigator.serviceWorker
+            : undefined)
+        : dependencies.serviceWorker ?? undefined;
+    const cacheStorage = dependencies.cacheStorage === undefined
+        ? (typeof caches !== 'undefined' ? caches : undefined)
+        : dependencies.cacheStorage ?? undefined;
+    const now = dependencies.now ?? Date.now;
+
+    if (!serviceWorker || !cacheStorage) {
+        updateOfflineReadiness('unsupported', 'Offline caching is not supported by this browser.', now());
+        return;
+    }
+
+    updateOfflineReadiness('checking', null, null);
+
+    try {
+        const registration = await serviceWorker.getRegistration();
+        if (!registration) {
+            updateOfflineReadiness('unavailable', 'No service worker is registered yet.', now());
+            return;
+        }
+        if (!registration.active) {
+            updateOfflineReadiness('installing', null, now());
+            return;
+        }
+
+        const cacheNames = (await cacheStorage.keys()).filter((name) => name.includes('precache'));
+        const cachedRequests = (
+            await Promise.all(cacheNames.map(async (cacheName) => {
+                const cache = await cacheStorage.open(cacheName);
+                return (await cache.keys()).map((request) => ({ cache, request }));
+            }))
+        ).flat();
+
+        const missing: string[] = [];
+        for (const requirement of REQUIRED_CORE_CACHE_ENTRIES) {
+            const match = cachedRequests.find(({ request }) =>
+                requirement.path.test(new URL(request.url).pathname),
+            );
+            if (!match) {
+                missing.push(requirement.label);
+                continue;
+            }
+
+            const response = await match.cache.match(match.request);
+            if (!response) {
+                missing.push(requirement.label);
+                continue;
+            }
+
+            const contentType = response.headers.get('content-type') ?? '';
+            if (!requirement.contentType.test(contentType)) {
+                updateOfflineReadiness(
+                    'failed',
+                    `${requirement.label} has an invalid content type (${contentType || 'missing'}).`,
+                    now(),
+                );
+                return;
+            }
+        }
+
+        if (missing.length > 0) {
+            updateOfflineReadiness(
+                'unavailable',
+                `Offline bundle is missing: ${missing.join(', ')}.`,
+                now(),
+            );
+            return;
+        }
+
+        for (const { cache, request } of cachedRequests) {
+            if (!new URL(request.url).pathname.endsWith('.js')) continue;
+            const response = await cache.match(request);
+            if (!response) {
+                updateOfflineReadiness(
+                    'unavailable',
+                    `Offline bundle is missing cached JavaScript: ${new URL(request.url).pathname}.`,
+                    now(),
+                );
+                return;
+            }
+            const contentType = response.headers.get('content-type') ?? '';
+            if (!/(?:java|ecma)script/i.test(contentType)) {
+                updateOfflineReadiness(
+                    'failed',
+                    `Cached JavaScript has an invalid content type (${contentType || 'missing'}).`,
+                    now(),
+                );
+                return;
+            }
+        }
+
+        updateOfflineReadiness('available', null, now());
+    } catch (error) {
+        updateOfflineReadiness(
+            'failed',
+            error instanceof Error ? error.message : 'Offline readiness could not be checked.',
+            now(),
+        );
+    }
+}

package/src/store/outbox-request.ts

@@ -0,0 +1,61 @@
+import type { AppendEventsRequest, IncomingEvent } from '../ledger/index.js';
+
+/** Matches Ledger's append contract (`appendEventsBody` in `packages/ledger/src/schemas.ts`). */
+export const MAX_BATCH_SIZE = 512;
+
+export interface PendingBatchEvent {
+    id: string;
+    type: string;
+    timestamp: number;
+    entityId: string;
+    payload: Record<string, unknown>;
+    localSequence: number;
+}
+
+export function prepareAppendRequest(
+    events: PendingBatchEvent[],
+    currentVersions: ReadonlyMap<string, number>,
+    requestId: string = crypto.randomUUID(),
+): AppendEventsRequest {
+    if (events.length === 0) throw new Error('Cannot prepare an empty Ledger append');
+    if (events.length > MAX_BATCH_SIZE) {
+        throw new Error(`Ledger batches are limited to ${MAX_BATCH_SIZE} events`);
+    }
+
+    const nextVersions = new Map(currentVersions);
+    const incomingEvents: IncomingEvent[] = events.map((event) => {
+        if (!event.id) throw new Error('Every local event must have an ID before it enters the outbox');
+        const currentVersion = nextVersions.get(event.entityId);
+        const incoming: IncomingEvent = {
+            id: event.id,
+            type: event.type,
+            entityId: event.entityId,
+            timestamp: event.timestamp,
+            payload: event.payload,
+        };
+        if (currentVersion !== undefined) incoming.baseEntityVersion = currentVersion;
+        nextVersions.set(event.entityId, (currentVersion ?? 0) + 1);
+        return incoming;
+    });
+    return { requestId, events: incomingEvents };
+}
+
+export async function hashRequest(request: AppendEventsRequest): Promise<string> {
+    const bytes = new TextEncoder().encode(JSON.stringify(canonicalize(request)));
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    return [...new Uint8Array(digest)]
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+}
+
+function canonicalize(value: unknown): unknown {
+    if (Array.isArray(value)) return value.map(canonicalize);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(
+            Object.entries(value as Record<string, unknown>)
+                .sort(([left], [right]) => left.localeCompare(right))
+                .map(([key, nested]) => [key, canonicalize(nested)]),
+        );
+    }
+    return value;
+}