@hearthlog/runtime 0.0.0-stage → 0.1.0

package/src/event/meta-entity-types.ts

@@ -0,0 +1,165 @@
+/**
+ * Meta-Entity Event Types
+ * 
+ * Event types for managing entity type definitions at runtime.
+ * These events are stored in the Ledger and enable dynamic entity creation.
+ */
+
+import type { EntityCalendarSource } from '@hearthlog/contracts/calendar/config';
+
+// ============================================================================
+// Field Definition Types
+// ============================================================================
+
+/**
+ * Field type for dynamic entity fields
+ */
+export type DynamicFieldType = 'string' | 'number' | 'boolean' | 'reference' | 'datetime';
+
+/**
+ * Definition for a field in a dynamic entity
+ */
+export interface DynamicFieldDefinition {
+    /** Database column name (snake_case) */
+    name: string;
+    /** Field data type */
+    type: DynamicFieldType;
+    /** Event payload key (camelCase). Defaults to camelCase version of name */
+    payloadKey: string;
+    /** Whether the field is required in ADD events */
+    required?: boolean;
+    /** Default value for the field */
+    default?: string | number | boolean | null;
+
+    // Validation constraints
+    /** Regex pattern for string validation */
+    pattern?: string;
+    /** Minimum value for numbers */
+    min?: number;
+    /** Maximum value for numbers */
+    max?: number;
+    /** Minimum length for strings */
+    minLength?: number;
+    /** Maximum length for strings */
+    maxLength?: number;
+    /** Allowed values (picklist/enum) */
+    enum?: string[];
+
+    // Reference configuration
+    /** Target entity name for reference fields */
+    referenceTo?: string;
+}
+
+// ============================================================================
+// Event Payload Types
+// ============================================================================
+
+/**
+ * Payload for ENTITY_TYPE_DEFINED event
+ */
+export interface DefineEntityTypePayload {
+    /** Entity type ID (UUID) */
+    id: string;
+    /** Entity name (lowercase, e.g., 'project') */
+    name: string;
+    /** Human-readable display name (e.g., 'Project') */
+    displayName: string;
+    /** Database table name (e.g., 'projects') */
+    tableName: string;
+    /** Field definitions */
+    fields: DynamicFieldDefinition[];
+    /** Optional calendar dates exposed by this entity. */
+    calendar?: EntityCalendarSource[];
+}
+
+/**
+ * Payload for ENTITY_TYPE_UPDATED event
+ */
+export interface UpdateEntityTypePayload {
+    /** Entity type ID */
+    id: string;
+    /** Updated display name */
+    displayName?: string;
+    /** Fields to add (additive only) */
+    addFields?: DynamicFieldDefinition[];
+    /** Replace the calendar dates; null clears them. */
+    calendar?: EntityCalendarSource[] | null;
+    /** Field updates (non-breaking changes only) */
+    updateFields?: Array<{
+        name: string;
+        displayName?: string;
+        default?: string | number | boolean | null;
+        // Validation can be loosened but not tightened
+        pattern?: string;
+        min?: number;
+        max?: number;
+        minLength?: number;
+        maxLength?: number;
+        enum?: string[];
+    }>;
+}
+
+/**
+ * Payload for ENTITY_TYPE_ARCHIVED event
+ */
+export interface ArchiveEntityTypePayload {
+    /** Entity type ID */
+    id: string;
+}
+
+// ============================================================================
+// Event Types
+// ============================================================================
+
+export interface EntityTypeDefinedEvent {
+    id: string;
+    type: 'ENTITY_TYPE_DEFINED';
+    timestamp: number;
+    payload: DefineEntityTypePayload;
+}
+
+export interface EntityTypeUpdatedEvent {
+    id: string;
+    type: 'ENTITY_TYPE_UPDATED';
+    timestamp: number;
+    payload: UpdateEntityTypePayload;
+}
+
+export interface EntityTypeArchivedEvent {
+    id: string;
+    type: 'ENTITY_TYPE_ARCHIVED';
+    timestamp: number;
+    payload: ArchiveEntityTypePayload;
+}
+
+/**
+ * Union type for all meta-entity events
+ */
+export type MetaEntityEvent =
+    | EntityTypeDefinedEvent
+    | EntityTypeUpdatedEvent
+    | EntityTypeArchivedEvent;
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export function isMetaEntityEvent(event: { type: string }): event is MetaEntityEvent {
+    return (
+        event.type === 'ENTITY_TYPE_DEFINED' ||
+        event.type === 'ENTITY_TYPE_UPDATED' ||
+        event.type === 'ENTITY_TYPE_ARCHIVED'
+    );
+}
+
+export function isEntityTypeDefinedEvent(event: { type: string }): event is EntityTypeDefinedEvent {
+    return event.type === 'ENTITY_TYPE_DEFINED';
+}
+
+export function isEntityTypeUpdatedEvent(event: { type: string }): event is EntityTypeUpdatedEvent {
+    return event.type === 'ENTITY_TYPE_UPDATED';
+}
+
+export function isEntityTypeArchivedEvent(event: { type: string }): event is EntityTypeArchivedEvent {
+    return event.type === 'ENTITY_TYPE_ARCHIVED';
+}

package/src/event/projection-builder.ts

@@ -0,0 +1,384 @@
+/**
+ * Projection Builder - SQL factory utilities for event sourcing projections
+ *
+ * Generates consistent CTE-based SQL for materializing entity state from raw_events.
+ * Eliminates duplication across entity projectors and rebuild functions.
+ *
+ * Projection is always scoped by explicit tenant/log — never via ambient active_context.
+ */
+
+import { sql, type RawBuilder, type Transaction } from 'kysely';
+import type { ActiveContext, Database } from '../db/index.js';
+import { requireActiveContext } from '../db/index.js';
+
+/**
+ * Configuration for an entity field projection
+ */
+export interface FieldConfig {
+    /** Column name in the target table */
+    name: string;
+    /** Key in the event payload JSON */
+    payloadKey: string;
+    /** SQL type cast (e.g., 'REAL', 'INTEGER') */
+    cast?: string;
+    /** Default value if null */
+    default?: string | number | null;
+}
+
+/**
+ * Configuration for projecting an entity type from events
+ */
+export interface EntityProjectionConfig {
+    /** Entity name (e.g., 'calendar_event') */
+    entityName: string;
+    /** Target table name (e.g., 'calendar_events') */
+    tableName: string;
+    /** Entity ID field alias in CTEs (e.g., 'asset_id', 'tx_id') */
+    entityIdAlias: string;
+    /** Event types to include in projection */
+    eventTypes: string[];
+    /** The 'removed' event type that marks entity deletion */
+    removedEventType: string;
+    /** Fields to project from event payload */
+    fields: FieldConfig[];
+}
+
+export type ProjectionBoundary =
+    | { kind: 'current' }
+    | { kind: 'log-version'; version: number };
+
+export interface ProjectionTarget {
+    schema?: string;
+}
+
+export interface ProjectionSource {
+    schema?: string;
+    table: string;
+    /** A staged snapshot source has already applied scope, boundary, and tombstones. */
+    staged?: boolean;
+}
+
+export interface ProjectionBuildOptions {
+    boundary?: ProjectionBoundary;
+    target?: ProjectionTarget;
+    source?: ProjectionSource;
+}
+
+/** Quote a SQLite identifier. Values are never accepted as identifiers. */
+export function quoteIdentifier(identifier: string): string {
+    return `"${identifier.replace(/"/g, '""')}"`;
+}
+
+export function qualifiedIdentifier(schema: string | undefined, name: string): string {
+    return schema
+        ? `${quoteIdentifier(schema)}.${quoteIdentifier(name)}`
+        : quoteIdentifier(name);
+}
+
+/**
+ * Builds the field extraction expressions for the entity_events CTE. Each
+ * field also records whether the payload names it: an explicit null clears a
+ * value, while an omitted key leaves it unchanged.
+ */
+function buildFieldExtractions(fields: FieldConfig[]): string {
+    return fields
+        .map(f => `json_extract(payload, '$.${f.payloadKey}') AS ${f.name},
+                    json_type(payload, '$.${f.payloadKey}') IS NOT NULL AS ${presenceColumn(f)}`)
+        .join(',\n                    ');
+}
+
+function presenceColumn(field: FieldConfig): string {
+    return `__present_${field.name}`;
+}
+
+/**
+ * Builds the FIRST_VALUE window function expressions for the 'w' CTE
+ */
+function buildWindowFunctions(fields: FieldConfig[], entityIdAlias: string): string {
+    return fields
+        .map(f => `
+                    FIRST_VALUE(${f.name}) OVER (
+                        PARTITION BY ${entityIdAlias}
+                        ORDER BY ${presenceColumn(f)} DESC, (entity_version IS NULL) DESC, entity_version DESC, local_sequence DESC, timestamp DESC, id DESC
+                        ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
+                    ) AS final_${f.name}`)
+        .join(',');
+}
+
+/**
+ * Builds the final SELECT field expressions with type casting and defaults
+ */
+function buildFinalFields(fields: FieldConfig[]): string {
+    return fields
+        .map(f => {
+            let expr = `final_${f.name}`;
+            if (f.cast) {
+                expr = `CAST(${expr} AS ${f.cast})`;
+            }
+            if (f.default !== undefined && f.default !== null) {
+                // SQL expressions (containing parentheses) should not be quoted
+                // Plain string literals should be quoted
+                const isSqlExpression = typeof f.default === 'string' && f.default.includes('(');
+                const deterministicTimeDefault = f.default === "date('now')"
+                    ? "date(created_ts/1000, 'unixepoch')"
+                    : f.default === "datetime('now')"
+                        ? "datetime(created_ts/1000, 'unixepoch')"
+                        : null;
+                const defaultVal = deterministicTimeDefault ?? (
+                    typeof f.default === 'string' && !isSqlExpression
+                        ? `'${f.default.replace(/'/g, "''")}'`
+                        : f.default
+                );
+                expr = `COALESCE(${expr}, ${defaultVal})`;
+            }
+            return `${expr} AS ${f.name}`;
+        })
+        .join(',\n                    ');
+}
+
+/**
+ * Builds the INSERT column list and final SELECT column list (scoped projection rows)
+ */
+function buildColumnLists(fields: FieldConfig[]): { insertCols: string; selectCols: string } {
+    const fieldNames = fields.map(f => f.name);
+    return {
+        insertCols: ['tenant_id', 'log_id', 'id', ...fieldNames, 'created_at', 'updated_at'].join(', '),
+        selectCols: [
+            'tenant_id',
+            'log_id',
+            'id',
+            ...fieldNames,
+            "datetime(created_ts/1000, 'unixepoch') AS created_at",
+            "datetime(updated_ts/1000, 'unixepoch') AS updated_at",
+        ].join(', '),
+    };
+}
+
+/**
+ * Generates the common CTE prefix filtered by explicit tenant/log.
+ */
+function buildCommonCTEs(
+    tenantId: string,
+    logId: string,
+    options: ProjectionBuildOptions,
+): RawBuilder<unknown> {
+    const source = options.source ?? { schema: 'main', table: 'raw_events' };
+    const sourceTable = sql.raw(qualifiedIdentifier(source.schema, source.table));
+
+    if (source.staged) {
+        return sql`WITH effective AS (SELECT events.* FROM ${sourceTable} events)`;
+    }
+
+    const boundary = options.boundary ?? { kind: 'current' as const };
+    if (boundary.kind === 'current') {
+        return sql`
+            WITH effective AS (
+                SELECT events.*
+                FROM ${sourceTable} events
+                WHERE events.is_tombstoned = 0
+                  AND events.projection_state = 'effective'
+                  AND events.tenant_id = ${tenantId}
+                  AND events.log_id = ${logId}
+            )`;
+    }
+
+    return sql`
+        WITH bounded AS (
+            SELECT events.*
+            FROM ${sourceTable} events
+            WHERE events.projection_state = 'effective'
+              AND events.tenant_id = ${tenantId}
+              AND events.log_id = ${logId}
+              AND events.log_version IS NOT NULL
+              AND events.log_version <= ${boundary.version}
+        ),
+        temporal_tombstones AS (
+            SELECT json_extract(payload, '$.eventId') AS target_event_id
+            FROM bounded
+            WHERE type = 'EVENT_TOMBSTONED'
+        ),
+        effective AS (
+            SELECT events.*
+            FROM bounded events
+            WHERE NOT EXISTS (
+                SELECT 1
+                FROM temporal_tombstones tombstones
+                WHERE tombstones.target_event_id = events.id
+            )
+        )`;
+}
+
+function buildProjectionSQL(
+    config: EntityProjectionConfig,
+    context: Pick<ActiveContext, 'tenantId' | 'logId'>,
+    options: ProjectionBuildOptions,
+    entityId?: string | readonly string[],
+): RawBuilder<unknown> {
+    const { tableName, entityIdAlias, eventTypes, removedEventType, fields } = config;
+    const { insertCols, selectCols } = buildColumnLists(fields);
+    const fieldExtractions = buildFieldExtractions(fields);
+    const windowFunctions = buildWindowFunctions(fields, entityIdAlias);
+    const finalFields = buildFinalFields(fields);
+    const eventTypeValues = eventTypes.map((eventType) => sql`${eventType}`);
+    const entityFilter = entityId === undefined
+        ? sql``
+        : typeof entityId === 'string'
+            ? sql`AND entity_id = ${entityId}`
+            : sql`AND entity_id IN (${sql.join(entityId)})`;
+    const targetTable = sql.raw(qualifiedIdentifier(options.target?.schema, tableName));
+
+    return sql`
+        INSERT INTO ${targetTable} (${sql.raw(insertCols)})
+        ${buildCommonCTEs(context.tenantId, context.logId, options)},
+        entity_events AS (
+            SELECT
+                id,
+                type,
+                timestamp,
+                entity_version,
+                local_sequence,
+                json_extract(payload, '$.id') AS ${sql.raw(entityIdAlias)},
+                ${sql.raw(fieldExtractions)}
+            FROM effective
+            WHERE type IN (${sql.join(eventTypeValues, sql`, `)})
+              ${entityFilter}
+        ),
+        w AS (
+            SELECT
+                *,
+                MIN(timestamp) OVER (PARTITION BY ${sql.raw(entityIdAlias)}) AS created_ts,${sql.raw(windowFunctions)},
+                ROW_NUMBER() OVER (
+                    PARTITION BY ${sql.raw(entityIdAlias)}
+                    ORDER BY (entity_version IS NULL) DESC, entity_version DESC, local_sequence DESC, timestamp DESC, id DESC
+                ) AS rn
+            FROM entity_events
+        ),
+        final AS (
+            SELECT
+                ${context.tenantId} AS tenant_id,
+                ${context.logId} AS log_id,
+                ${sql.raw(entityIdAlias)} AS id,
+                ${sql.raw(finalFields)},
+                type,
+                created_ts,
+                timestamp AS updated_ts
+            FROM w
+            WHERE rn = 1
+        )
+        SELECT ${sql.raw(selectCols)}
+        FROM final
+        WHERE type <> ${removedEventType}
+    `;
+}
+
+/**
+ * Generates a projection SQL query for a single entity
+ * Used when projecting after a single event
+ */
+export function buildSingleEntityProjectionSQL(
+    config: EntityProjectionConfig,
+    entityId: string,
+    context: Pick<ActiveContext, 'tenantId' | 'logId'>,
+    options: ProjectionBuildOptions = {},
+): RawBuilder<unknown> {
+    return buildProjectionSQL(config, context, options, entityId);
+}
+
+/**
+ * Generates a projection SQL query for all entities of a type
+ * Used during full rebuild
+ */
+export function buildBulkProjectionSQL(
+    config: EntityProjectionConfig,
+    context: Pick<ActiveContext, 'tenantId' | 'logId'>,
+    options: ProjectionBuildOptions = {},
+): RawBuilder<unknown> {
+    return buildProjectionSQL(config, context, options);
+}
+
+/** Reproject a bounded affected set without touching other records of the type. */
+export async function projectEntitySet(
+    config: EntityProjectionConfig,
+    entityIds: readonly string[],
+    tx: Transaction<Database>,
+    context: Pick<ActiveContext, 'tenantId' | 'logId'>,
+): Promise<void> {
+    if (entityIds.length === 0) return;
+    await tx.deleteFrom(config.tableName as keyof Database)
+        .where('tenant_id', '=', context.tenantId)
+        .where('log_id', '=', context.logId)
+        .where('id', 'in', entityIds.map(entityId => entityId.split(':')[1]))
+        .execute();
+    await buildProjectionSQL(config, context, {}, entityIds).execute(tx);
+}
+
+/**
+ * Creates an entity projector function from configuration
+ * Returns a function that can be used to project a single event to the read model
+ */
+export function createEntityProjector(config: EntityProjectionConfig) {
+    return async function projectEvent(
+        event: { payload: { id: string } },
+        tx: Transaction<Database>,
+        entityIdOverride?: string,
+        context?: Pick<ActiveContext, 'tenantId' | 'logId'>,
+    ): Promise<void> {
+        const id = event.payload.id;
+        // If an explicit entity ID is provided (e.g. from the event envelope), use it.
+        // Otherwise, construct it from the config and payload ID.
+        // This ensures consistency between what's in raw_events and what we query for.
+        const fullEntityId = entityIdOverride || `${config.entityName}:${id}`;
+        const scope = context ?? await requireActiveContext();
+
+        // Delete existing entry for this scope + entity id
+        await tx.deleteFrom(config.tableName as keyof Database)
+            .where('tenant_id', '=', scope.tenantId)
+            .where('log_id', '=', scope.logId)
+            .where('id', '=', id)
+            .execute();
+
+        // Rebuild from events using the full entity ID to find matching events
+        const query = buildSingleEntityProjectionSQL(config, fullEntityId, scope);
+        await query.execute(tx);
+    };
+}
+
+// ============================================================================
+// Entity Definition to Projection Config Conversion
+// ============================================================================
+
+import {
+    ENTITY_DEFINITIONS,
+    getEventTypes,
+    getPayloadKey,
+    type EntityDefinition,
+    type EntityFieldDefinition,
+} from '@hearthlog/contracts/event/entity-definitions';
+
+/**
+ * Converts an EntityDefinition to an EntityProjectionConfig
+ */
+export function createProjectionConfigFromDefinition(def: EntityDefinition): EntityProjectionConfig {
+    const eventTypes = getEventTypes(def);
+
+    return {
+        entityName: def.name,
+        tableName: def.table,
+        entityIdAlias: `${def.name}_id`,
+        eventTypes: eventTypes,
+        removedEventType: eventTypes[2], // REMOVED event
+        fields: def.fields.map((field: EntityFieldDefinition) => ({
+            name: field.name,
+            payloadKey: getPayloadKey(field),
+            cast: field.type === 'number' ? 'REAL' : undefined,
+            default: field.default,
+        })),
+    };
+}
+
+/**
+ * Auto-generated projection configs from ENTITY_DEFINITIONS
+ */
+export const PROJECTION_CONFIGS: Record<string, EntityProjectionConfig> = Object.fromEntries(
+    ENTITY_DEFINITIONS.map(def => [def.name, createProjectionConfigFromDefinition(def)])
+);

package/src/event/queries.ts

@@ -0,0 +1,126 @@
+/**
+ * Event Queries
+ * 
+ * Functions for reading events from the local database.
+ */
+
+import { db as readModelDB, requireActiveContext } from '../db/index.js';
+import type { AppEvent } from './types.js';
+import { withTimeout } from '../utils/async.js';
+import { tenant } from '@hearthlog/contracts/tenant/config';
+import { sql, type RawBuilder } from 'kysely';
+
+/**
+ * Tenant feature visibility as a SQL predicate, so raw event reads never
+ * fetch rows they must discard. Mirrors `isVisibleEventType` exactly.
+ */
+export function visibleEventCondition(): RawBuilder<boolean> {
+    const prefixes = [...tenant.approvedEntities.eventPrefixes];
+    const prefixCondition = prefixes.length
+        ? sql.join(
+            prefixes.map((prefix) => sql`type LIKE ${`${prefix}%`}`),
+            sql` OR `,
+        )
+        : sql`0`;
+    const dynamicSuffix = tenant.dynamicEntities
+        ? sql`(type LIKE '%_ADDED' OR type LIKE '%_UPDATED' OR type LIKE '%_REMOVED')`
+        : sql`0`;
+    return sql<boolean>`(
+        CASE
+            WHEN type IN ('EVENT_TOMBSTONED', 'WORKSPACE_RESTORED', 'EVENTS_EXCISED') THEN 1
+            WHEN type LIKE 'ENTITY_TYPE_%' THEN ${tenant.dynamicEntities ? 1 : 0}
+            WHEN ${prefixCondition} THEN 1
+            WHEN ${dynamicSuffix} THEN 1
+            ELSE 0
+        END = 1
+    )`;
+}
+
+function parseEventPayload(payload: string): AppEvent['payload'] {
+    try {
+        return JSON.parse(payload) as AppEvent['payload'];
+    } catch (error) {
+        throw new Error(
+            `Stored event payload is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+        );
+    }
+}
+
+/**
+ * Gets all events from the local database (for display purposes)
+ */
+export async function getAllEvents(order: 'asc' | 'desc' = 'desc'): Promise<AppEvent[]> {
+    const context = await requireActiveContext();
+    const rows = await readModelDB
+        .selectFrom('raw_events')
+        .select(['id', 'type', 'timestamp', 'payload'])
+        .where('tenant_id', '=', context.tenantId)
+        .where('log_id', '=', context.logId)
+        .where(visibleEventCondition())
+        .orderBy('timestamp', order)
+        .execute();
+
+    return rows.map((r) => ({
+        id: r.id,
+        type: r.type as AppEvent['type'],
+        timestamp: r.timestamp,
+        payload: parseEventPayload(r.payload),
+    }) as AppEvent);
+}
+
+/**
+ * Gets only local events that haven't been uploaded to the server yet
+ */
+export async function getEvents(): Promise<AppEvent[]> {
+    const context = await requireActiveContext();
+    const rows = await withTimeout(
+        readModelDB
+            .selectFrom('raw_events')
+            .select(['id', 'type', 'timestamp', 'payload'])
+            .where('tenant_id', '=', context.tenantId)
+            .where('log_id', '=', context.logId)
+            .where('sync_state', '=', 'pending')
+            .where('projection_state', '=', 'effective')
+            .where(visibleEventCondition())
+            .orderBy('local_sequence', 'asc')
+            .execute(),
+        5000,
+        'getEvents query timed out'
+    );
+
+    const localEvents: AppEvent[] = rows.map((r) => ({
+        id: r.id,
+        type: r.type as AppEvent['type'],
+        timestamp: r.timestamp,
+        payload: parseEventPayload(r.payload),
+    }) as AppEvent);
+
+    console.log(
+        `[Event] getEvents returning ${localEvents.length} local-only events`
+    );
+    return localEvents;
+}
+
+/**
+ * Keep operational event views within the tenant's feature contract. Raw
+ * events remain locally stored for sync/recovery, but disabled feature events
+ * must not become a backdoor into another tenant artifact's data model.
+ */
+export function isVisibleEventType(type: string): boolean {
+    if (type === 'EVENT_TOMBSTONED' || type === 'WORKSPACE_RESTORED' || type === 'EVENTS_EXCISED') return true;
+    if (type.startsWith('ENTITY_TYPE_')) return tenant.dynamicEntities;
+    if ([...tenant.approvedEntities.eventPrefixes].some((prefix) => type.startsWith(prefix))) {
+        return true;
+    }
+    // Dynamic entity events are runtime-defined and are only valid for sites
+    // that expose the dynamic entity capability.
+    return tenant.dynamicEntities && /_(ADDED|UPDATED|REMOVED)$/.test(type);
+}
+
+/**
+ * Exports all events as JSON string
+ */
+export async function exportEventsAsJson(): Promise<string> {
+    const allEvents = await getAllEvents('asc');
+    return JSON.stringify(allEvents, null, 2);
+}