@hearthlog/runtime 0.0.0-stage → 0.1.1

package/src/commands/index.ts

@@ -0,0 +1,184 @@
+import { db, requireActiveContext } from '../db/index.js';
+import {
+    applyMetaEvents,
+    cacheEventId,
+    projectEntityById,
+} from '../event/handlers.js';
+import { schemaTombstoneIds } from '../event/schema-effects.js';
+import type {
+    ExtendedAppEvent,
+} from '../event/types.js';
+import { commitLocalEventBatch, SubmissionMismatchError, submissionContent } from './local-commit.js';
+import { validateCommandEvents } from './validation.js';
+
+export { CommandValidationError, validateCommandEvents } from './validation.js';
+export { commitLocalEventBatch, localBatchId, SubmissionMismatchError } from './local-commit.js';
+
+export interface LocalCommandOptions {
+    submissionId?: string;
+}
+
+export interface LocalCommandResult {
+    batchId: string;
+    duplicate: boolean;
+    eventIds: string[];
+    projectionPending: boolean;
+}
+
+type CommitListener = (result: LocalCommandResult) => void | Promise<void>;
+
+const commitListeners = new Set<CommitListener>();
+const inFlightCommands = new Map<string, { content: string; execution: Promise<LocalCommandResult> }>();
+
+export function onLocalCommandCommitted(listener: CommitListener): () => void {
+    commitListeners.add(listener);
+    return () => commitListeners.delete(listener);
+}
+
+export async function executeLocalCommand(
+    eventOrEvents: ExtendedAppEvent | ExtendedAppEvent[],
+    options: LocalCommandOptions = {},
+): Promise<LocalCommandResult> {
+    const events = Array.isArray(eventOrEvents) ? eventOrEvents : [eventOrEvents];
+    validateCommandEvents(events);
+
+    const context = await requireActiveContext();
+    const submissionId = options.submissionId ?? events.map((event) => event.id).join(':');
+    const inFlightKey = JSON.stringify([context.tenantId, context.logId, submissionId]);
+    const content = submissionContent(events);
+    const existing = inFlightCommands.get(inFlightKey);
+    if (existing) {
+        if (existing.content !== content) throw new SubmissionMismatchError();
+        return existing.execution;
+    }
+
+    const execution = execute(events, submissionId, context);
+    inFlightCommands.set(inFlightKey, { content, execution });
+    try {
+        return await execution;
+    } finally {
+        inFlightCommands.delete(inFlightKey);
+    }
+}
+
+const BUSY_RETRY_DELAYS_MS = [50, 100, 200, 400];
+
+/**
+ * Another tab may hold the database's write lock (a rebuild, an ingestion).
+ * A commit is atomic and its submission identity makes a repeat harmless, so
+ * a busy answer waits briefly and tries again.
+ */
+export async function withBusyRetry<T>(
+    task: () => Promise<T>,
+    delaysMs: readonly number[] = BUSY_RETRY_DELAYS_MS,
+    wait: (ms: number) => Promise<void> = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+): Promise<T> {
+    for (let attempt = 0; ; attempt++) {
+        try {
+            return await task();
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const delay = delaysMs[attempt];
+            if (delay === undefined || !/database is locked|SQLITE_BUSY/i.test(message)) throw error;
+            await wait(delay);
+        }
+    }
+}
+
+async function execute(
+    events: ExtendedAppEvent[],
+    submissionId: string,
+    context: Awaited<ReturnType<typeof requireActiveContext>>,
+): Promise<LocalCommandResult> {
+    const committed = await withBusyRetry(() => commitLocalEventBatch({
+        database: db,
+        context,
+        events,
+        submissionId,
+        projectEntity: projectEntityById,
+    }));
+
+    let projectionPending = committed.pendingDdlEventIds.length > 0;
+    if (!committed.duplicate) {
+        committed.eventIds.forEach(cacheEventId);
+        if (committed.pendingDdlEventIds.length > 0) {
+            projectionPending = !(await applyPendingDdlEvents(events, context));
+        }
+    }
+
+    const result: LocalCommandResult = {
+        batchId: committed.batchId,
+        duplicate: committed.duplicate,
+        eventIds: committed.eventIds,
+        projectionPending,
+    };
+
+    if (!committed.duplicate) await notifyCommitted(result);
+    return result;
+}
+
+async function applyPendingDdlEvents(
+    events: ExtendedAppEvent[],
+    context: Awaited<ReturnType<typeof requireActiveContext>>,
+): Promise<boolean> {
+    const metaEvents = events.filter((event) =>
+        event.type === 'ENTITY_TYPE_DEFINED' ||
+        event.type === 'ENTITY_TYPE_UPDATED' ||
+        event.type === 'ENTITY_TYPE_ARCHIVED'
+    );
+    const schemaUndos = await schemaTombstoneIds(db, context, events);
+    if (metaEvents.length === 0 && schemaUndos.size === 0) return true;
+
+    try {
+        if (schemaUndos.size > 0) {
+            const { rebuildReadModel } = await import('../event/rebuild.js');
+            await rebuildReadModel({ includePendingDdl: true });
+        } else {
+            await applyMetaEvents(metaEvents);
+        }
+        await db.updateTable('raw_events')
+            .set({ projection_state: 'effective' })
+            .where('tenant_id', '=', context.tenantId)
+            .where('log_id', '=', context.logId)
+            .where('id', 'in', [...metaEvents.map(event => event.id), ...schemaUndos])
+            .execute();
+        return true;
+    } catch (error) {
+        console.error('[Command] Dynamic schema projection remains pending', error);
+        return false;
+    }
+}
+
+export async function retryPendingCommandProjections(): Promise<number> {
+    const context = await requireActiveContext();
+    const rows = await db.selectFrom('raw_events')
+        .select(['id', 'type', 'timestamp', 'payload'])
+        .where('tenant_id', '=', context.tenantId)
+        .where('log_id', '=', context.logId)
+        .where('projection_state', '=', 'pending_ddl')
+        .orderBy('local_sequence', 'asc')
+        .execute();
+    let completed = 0;
+
+    for (const row of rows) {
+        const event = {
+            id: row.id,
+            type: row.type,
+            timestamp: row.timestamp,
+            payload: JSON.parse(row.payload),
+        } as ExtendedAppEvent;
+        if (await applyPendingDdlEvents([event], context)) completed++;
+    }
+
+    return completed;
+}
+
+async function notifyCommitted(result: LocalCommandResult): Promise<void> {
+    for (const listener of commitListeners) {
+        try {
+            await listener(result);
+        } catch (error) {
+            console.error('[Command] Post-commit listener failed', error);
+        }
+    }
+}

package/src/commands/local-commit.ts

@@ -0,0 +1,214 @@
+import { schemaTombstoneIds } from '../event/schema-effects.js';
+import type { ActiveContext, Database } from '../db/index.js';
+import { extractEntityId } from '../ledger/entity-id.js';
+import type { ExtendedAppEvent } from '../event/types.js';
+import { isMetaEntityEvent } from '../event/meta-entity-types.js';
+import { reconcileRestoredEvents } from '../history/legacy-replay.js';
+import { EVENTS_EXCISED, WORKSPACE_RESTORED } from '@hearthlog/contracts/history/replay-selection';
+import type { Kysely, Transaction } from 'kysely';
+
+export type ProjectEntity = (
+    entityId: string,
+    tx: Transaction<Database>,
+    context: ActiveContext,
+) => Promise<void>;
+
+export interface LocalCommitInput {
+    database: Kysely<Database>;
+    context: ActiveContext;
+    events: ExtendedAppEvent[];
+    submissionId: string;
+    projectEntity: ProjectEntity;
+}
+
+export interface LocalCommitResult {
+    batchId: string;
+    duplicate: boolean;
+    eventIds: string[];
+    pendingDdlEventIds: string[];
+}
+
+/** A submission identity was reused for different content. */
+export class SubmissionMismatchError extends Error {
+    constructor() {
+        super('This action was already saved with different values. Reopen it to make another change.');
+        this.name = 'SubmissionMismatchError';
+    }
+}
+
+/** What a retry must repeat exactly: each event's type and payload, in order. */
+export function submissionContent(
+    events: ReadonlyArray<{ type: string; payload: unknown }>,
+): string {
+    return JSON.stringify(events.map((event) => [event.type, event.payload]));
+}
+
+export function localBatchId(
+    context: Pick<ActiveContext, 'tenantId' | 'logId'>,
+    submissionId: string,
+): string {
+    return `local:${context.tenantId}:${context.logId}:${submissionId}`;
+}
+
+export async function commitLocalEventBatch(
+    input: LocalCommitInput,
+): Promise<LocalCommitResult> {
+    const { database, context, events, submissionId, projectEntity } = input;
+    const batchId = localBatchId(context, submissionId);
+    let eventIds = events.map((event) => event.id);
+    let pendingDdlEventIds = events
+        .filter(isMetaEntityEvent)
+        .map((event) => event.id);
+    let duplicate = false;
+
+    await database.transaction().execute(async (tx) => {
+        const existingBatch = await tx
+            .selectFrom('local_batches')
+            .select('id')
+            .where('id', '=', batchId)
+            .where('tenant_id', '=', context.tenantId)
+            .where('log_id', '=', context.logId)
+            .executeTakeFirst();
+
+        if (existingBatch) {
+            const persisted = await tx.selectFrom('raw_events')
+                .select(['id', 'type', 'payload', 'projection_state'])
+                .where('tenant_id', '=', context.tenantId).where('log_id', '=', context.logId)
+                .where('local_batch_id', '=', batchId).orderBy('local_sequence').execute();
+            const recorded = persisted.map((event) => ({ type: event.type, payload: JSON.parse(event.payload) as unknown }));
+            if (submissionContent(recorded) !== submissionContent(events)) throw new SubmissionMismatchError();
+            eventIds = persisted.map(event => event.id);
+            pendingDdlEventIds = persisted.filter(event => event.projection_state === 'pending_ddl').map(event => event.id);
+            duplicate = true;
+            return;
+        }
+
+        const schemaUndos = await schemaTombstoneIds(tx, context, events);
+        pendingDdlEventIds.push(...schemaUndos);
+
+        const maxSequence = await tx
+            .selectFrom('raw_events')
+            .select((eb) => eb.fn.max('local_sequence').as('max_sequence'))
+            .where('tenant_id', '=', context.tenantId)
+            .where('log_id', '=', context.logId)
+            .executeTakeFirst();
+        let nextSequence = Number(maxSequence?.max_sequence ?? 0);
+        const affectedEntityIds = new Set<string>();
+        let replayMembershipChanged = false;
+
+        await tx.insertInto('local_batches').values({
+            id: batchId,
+            tenant_id: context.tenantId,
+            log_id: context.logId,
+            status: 'pending',
+            replacement_for: null,
+        }).execute();
+
+        for (const event of events) {
+            const entityId = extractEntityId(event);
+            const pendingDdl = isMetaEntityEvent(event) || schemaUndos.has(event.id);
+
+            await tx.insertInto('raw_events').values({
+                id: event.id,
+                tenant_id: context.tenantId,
+                log_id: context.logId,
+                local_batch_id: batchId,
+                local_sequence: ++nextSequence,
+                type: event.type,
+                timestamp: event.timestamp,
+                payload: JSON.stringify(event.payload),
+                entity_id: entityId,
+                entity_version: null,
+                log_version: null,
+                sync_state: 'pending',
+                projection_state: pendingDdl ? 'pending_ddl' : 'effective',
+                rejection_code: null,
+                rejection_detail: null,
+                is_tombstoned: 0,
+            }).execute();
+
+            if (entityId) affectedEntityIds.add(entityId);
+
+            if (event.type === 'EVENT_TOMBSTONED') {
+                const targetEventId = (event.payload as { eventId: string }).eventId;
+                const target = await tx.selectFrom('raw_events')
+                    .select(['entity_id', 'type', 'payload'])
+                    .where('tenant_id', '=', context.tenantId)
+                    .where('log_id', '=', context.logId)
+                    .where('id', '=', targetEventId)
+                    .executeTakeFirst();
+
+                if (target) {
+                    await tx.updateTable('raw_events')
+                        .set({ is_tombstoned: 1 })
+                        .where('tenant_id', '=', context.tenantId)
+                        .where('log_id', '=', context.logId)
+                        .where('id', '=', targetEventId)
+                        .execute();
+                    if (target.entity_id) affectedEntityIds.add(target.entity_id);
+                    // Undoing an excision or a restore changes replay
+                    // membership; recompute it and reproject the events the
+                    // directive had excluded.
+                    if (target.type === EVENTS_EXCISED || target.type === WORKSPACE_RESTORED) {
+                        replayMembershipChanged = true;
+                        await collectDirectiveTargetEntities(tx, context, target.type, target.payload, affectedEntityIds);
+                    }
+                }
+            }
+
+            if (event.type === EVENTS_EXCISED) {
+                replayMembershipChanged = true;
+                await collectDirectiveTargetEntities(tx, context, event.type, JSON.stringify(event.payload), affectedEntityIds);
+            }
+        }
+
+        if (replayMembershipChanged) {
+            // Membership is derived, not incremental: one pass recomputes
+            // projection_state/is_tombstoned for the whole scope so excision
+            // and revive stay exact.
+            await reconcileRestoredEvents(tx, context);
+        }
+
+        for (const entityId of affectedEntityIds) {
+            await projectEntity(entityId, tx, context);
+        }
+    });
+
+    return {
+        batchId,
+        duplicate,
+        eventIds,
+        pendingDdlEventIds,
+    };
+}
+
+/** Entities whose events are hidden or revealed by a replay directive. */
+async function collectDirectiveTargetEntities(
+    tx: Transaction<Database>,
+    context: ActiveContext,
+    type: string,
+    payload: string,
+    affectedEntityIds: Set<string>,
+): Promise<void> {
+    if (type === WORKSPACE_RESTORED) return;
+    if (type !== EVENTS_EXCISED) return;
+    let eventIds: string[] = [];
+    try {
+        const parsed = JSON.parse(payload) as { eventIds?: unknown };
+        if (Array.isArray(parsed.eventIds)) {
+            eventIds = parsed.eventIds.filter((id): id is string => typeof id === 'string' && id.length > 0);
+        }
+    } catch {
+        return;
+    }
+    if (eventIds.length === 0) return;
+    const rows = await tx.selectFrom('raw_events')
+        .select('entity_id')
+        .where('tenant_id', '=', context.tenantId)
+        .where('log_id', '=', context.logId)
+        .where('id', 'in', eventIds)
+        .execute();
+    for (const row of rows) {
+        if (row.entity_id) affectedEntityIds.add(row.entity_id);
+    }
+}

package/src/commands/standard.ts

@@ -0,0 +1,8 @@
+import { executeLocalCommand, type LocalCommandOptions } from './index.js';
+import type { AppEvent } from '../event/types.js';
+
+/** Typed convenience around the existing command boundary; no separate write path. */
+export function standardCommand<T extends AppEvent['type']>(type: T) {
+    return (payload: Extract<AppEvent, { type: T }>['payload'], options?: LocalCommandOptions) =>
+        executeLocalCommand({ id: crypto.randomUUID(), type, timestamp: Date.now(), payload } as AppEvent, options);
+}

package/src/commands/validation.ts

@@ -0,0 +1,206 @@
+import {
+    ENTITY_DEFINITIONS,
+    getEventTypes,
+    getPayloadKey,
+} from '@hearthlog/contracts/event/entity-definitions';
+import type { ExtendedAppEvent } from '../event/types.js';
+import type { EntityDefinition } from '@hearthlog/contracts/event/entity-definitions';
+import { tenant } from '@hearthlog/contracts/tenant/config';
+import {
+    sanitizeCalendarSource,
+    validateCalendarConfig,
+    type CalendarFieldLike,
+    type EntityCalendarSource,
+} from '@hearthlog/contracts/calendar/config';
+
+export class CommandValidationError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'CommandValidationError';
+    }
+}
+
+type KnownEvent = {
+    definition: EntityDefinition;
+    kind: 'added' | 'updated' | 'removed';
+};
+
+const eventDefinitions = new Map<string, KnownEvent>(
+    ENTITY_DEFINITIONS.flatMap((definition) => {
+        const [added, updated, removed] = getEventTypes(definition);
+        return [
+            [added, { definition, kind: 'added' as const }],
+            [updated, { definition, kind: 'updated' as const }],
+            [removed, { definition, kind: 'removed' as const }],
+        ];
+    }),
+);
+
+export function validateCommandEvents(events: ExtendedAppEvent[]): void {
+    if (events.length === 0) {
+        throw new CommandValidationError('A command must contain at least one event');
+    }
+
+    const ids = new Set<string>();
+    for (const event of events) {
+        if (!event.id?.trim()) throw new CommandValidationError('Event ID is required');
+        if (ids.has(event.id)) {
+            throw new CommandValidationError(`Duplicate event ID in command: ${event.id}`);
+        }
+        ids.add(event.id);
+
+        if (!event.type?.trim()) throw new CommandValidationError('Event type is required');
+        if (!Number.isFinite(event.timestamp)) {
+            throw new CommandValidationError(`Event ${event.id} has an invalid timestamp`);
+        }
+        if (!event.payload || typeof event.payload !== 'object' || Array.isArray(event.payload)) {
+            throw new CommandValidationError(`Event ${event.id} must have an object payload`);
+        }
+
+        validateKnownEvent(event);
+    }
+}
+
+function validateKnownEvent(event: ExtendedAppEvent): void {
+    if (['EVENT_TOMBSTONED', 'EVENTS_EXCISED', 'WORKSPACE_RESTORED'].includes(event.type)) {
+        throw new CommandValidationError(`Event ${event.id}: history removal and restore commands are retired`);
+    }
+
+    if (
+        event.type === 'ENTITY_TYPE_DEFINED' ||
+        event.type === 'ENTITY_TYPE_UPDATED' ||
+        event.type === 'ENTITY_TYPE_ARCHIVED'
+    ) {
+        if (!tenant.dynamicEntities) {
+            throw new CommandValidationError(
+                `Event ${event.id}: this site is not allowed to manage dynamic entity types`,
+            );
+        }
+        if (event.type !== 'ENTITY_TYPE_DEFINED') {
+            requireString(event, 'id');
+            sanitizeCalendarPayload(event);
+            return;
+        }
+        requireString(event, 'id');
+        requireString(event, 'name');
+        requireString(event, 'displayName');
+        requireString(event, 'tableName');
+        // SAFETY: payload was checked to be a non-array object by validateCommandEvents.
+        const payload = event.payload as unknown as Record<string, unknown>;
+        if (!Array.isArray(payload.fields)) {
+            throw new CommandValidationError(`Event ${event.id} requires fields`);
+        }
+        const sources = sanitizeCalendarPayload(event);
+        if (sources.length > 0) {
+            const fields: CalendarFieldLike[] = (payload.fields as unknown[])
+                .filter(
+                    (field): field is { name: string; type: string } =>
+                        typeof field === 'object' &&
+                        field !== null &&
+                        typeof (field as { name?: unknown }).name === 'string' &&
+                        typeof (field as { type?: unknown }).type === 'string',
+                )
+                .map((field) => ({ name: field.name, type: field.type }));
+            const errors = validateCalendarConfig(
+                payload.name as string,
+                sources,
+                fields,
+                { parentTables: new Set<string>() },
+            );
+            if (errors.length > 0) {
+                throw new CommandValidationError(
+                    `Event ${event.id}: ${errors[0]}`,
+                );
+            }
+        }
+        return;
+    }
+
+    const known = eventDefinitions.get(event.type);
+    if (!known) {
+        if (/_(ADDED|UPDATED|REMOVED)$/.test(event.type)) requireString(event, 'id');
+        return;
+    }
+
+    // Feature scoping (defense in depth — the owning pages are already
+    // gated): commands may never append events for entities the tenant is
+    // not approved for. Dynamic (runtime-defined) entity events are not in
+    // this map and pass through; their creation is gated separately.
+    const approvalError = eventApprovalError(
+        event.type,
+        tenant.features as ReadonlySet<string>,
+    );
+    if (approvalError) {
+        throw new CommandValidationError(`Event ${event.id}: ${approvalError}`);
+    }
+
+    requireString(event, 'id');
+    if (known.kind !== 'added') return;
+
+    for (const field of known.definition.fields.filter((item) => item.required)) {
+        const key = getPayloadKey(field);
+        // SAFETY: payload was checked to be a non-array object by validateCommandEvents.
+        const value = (event.payload as unknown as Record<string, unknown>)[key];
+        if (value === undefined || value === null || value === '') {
+            throw new CommandValidationError(`Event ${event.id} requires ${key}`);
+        }
+        if (field.type === 'number' && (typeof value !== 'number' || !Number.isFinite(value))) {
+            throw new CommandValidationError(`Event ${event.id} requires a finite ${key}`);
+        }
+    }
+}
+
+/**
+ * Returns an error message when the event type belongs to an entity the
+ * given feature set does not approve; null when allowed (meta events and
+ * dynamic entity events are not feature-scoped here).
+ */
+export function eventApprovalError(
+    eventType: string,
+    features: ReadonlySet<string>,
+): string | null {
+    const known = eventDefinitions.get(eventType);
+    if (!known) return null;
+    if (!features.has(known.definition.feature)) {
+        return (
+            `the entity "${known.definition.table}" belongs to the ` +
+            `"${known.definition.feature}" feature, which is not enabled for this site`
+        );
+    }
+    return null;
+}
+
+/**
+ * Validate the optional `calendar` payload of a meta event. Returns the
+ * sanitized sources; an omitted or null value means "no calendar dates".
+ * Semantic field checks run in the DEFINED branch where fields are present.
+ */
+function sanitizeCalendarPayload(event: ExtendedAppEvent): EntityCalendarSource[] {
+    // SAFETY: payload was checked to be a non-array object by validateCommandEvents.
+    const payload = event.payload as unknown as Record<string, unknown>;
+    if (payload.calendar === undefined || payload.calendar === null) return [];
+    if (!Array.isArray(payload.calendar)) {
+        throw new CommandValidationError(
+            `Event ${event.id} requires calendar to be a list`,
+        );
+    }
+    const sources: EntityCalendarSource[] = [];
+    for (const entry of payload.calendar) {
+        const source = sanitizeCalendarSource(entry);
+        if (!source) {
+            throw new CommandValidationError(
+                `Event ${event.id} has an invalid calendar source`,
+            );
+        }
+        sources.push(source);
+    }
+    return sources;
+}
+
+function requireString(event: ExtendedAppEvent, key: string): void {
+    // SAFETY: payload was checked to be a non-array object by validateCommandEvents.
+    const value = (event.payload as unknown as Record<string, unknown>)[key];
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new CommandValidationError(`Event ${event.id} requires ${key}`);
+    }
+}

package/src/db/bootstrap.ts

@@ -0,0 +1,72 @@
+import { rebuildIfSchemaChanged } from '../event/rebuild.js';
+import { eventLogFilename } from '../store/event-log.svelte.js';
+import { activateLogContext } from '../store/local-context.js';
+import {
+    markLocalStoreBooting,
+    markLocalStoreDegraded,
+    markLocalStoreFailed,
+    markLocalStoreReady,
+    type LocalStorePhase,
+} from '../store/local-store.svelte.js';
+import { getLocalSchemaVersion } from './index.js';
+import { retryPendingCommandProjections } from '../commands/index.js';
+
+export interface LocalStoreBootstrapResult {
+    activeLogId: string | null;
+    schemaRebuilt: boolean;
+    schemaVersion: number;
+    phase: LocalStorePhase;
+}
+
+let bootstrapPromise: Promise<LocalStoreBootstrapResult> | null = null;
+
+async function runBootstrap(): Promise<LocalStoreBootstrapResult> {
+    markLocalStoreBooting();
+    await eventLogFilename.ready();
+
+    const activeLogId = eventLogFilename.value;
+    if (!activeLogId) {
+        const schemaVersion = await getLocalSchemaVersion();
+        markLocalStoreDegraded({
+            message: 'No event log is selected',
+            schemaVersion,
+        });
+        return {
+            activeLogId: null,
+            schemaRebuilt: false,
+            schemaVersion,
+            phase: 'degraded',
+        };
+    }
+
+    await activateLogContext(activeLogId);
+    const schemaRebuilt = await rebuildIfSchemaChanged();
+    await retryPendingCommandProjections();
+
+    const result: LocalStoreBootstrapResult = {
+        activeLogId,
+        schemaRebuilt,
+        schemaVersion: await getLocalSchemaVersion(),
+        phase: 'ready',
+    };
+    markLocalStoreReady({
+        activeLogId,
+        schemaVersion: result.schemaVersion,
+        schemaRebuilt,
+    });
+    return result;
+}
+
+/**
+ * Initializes the selected local Ledger scope exactly once per tab. Route loaders
+ * await this through the root layout before issuing scoped projection queries.
+ * Failed attempts are not cached so a navigation or explicit retry can recover.
+ */
+export function bootstrapLocalStore(): Promise<LocalStoreBootstrapResult> {
+    bootstrapPromise ??= runBootstrap().catch((error) => {
+        bootstrapPromise = null;
+        markLocalStoreFailed(error);
+        throw error;
+    });
+    return bootstrapPromise;
+}