@humwick/server 0.130.1 → 0.130.3

package/node_modules/@humwick/kernel/event-log.ts

@@ -1,319 +0,0 @@
-import type { Database } from "bun:sqlite";
-import { isDeepStrictEqual } from "node:util";
-import type * as z from "zod";
-import type {
-  Clock,
-  EventName,
-  EventWriter,
-  ModuleDefinition,
-  ModuleManifest,
-  Scope,
-} from "./contract";
-
-const EVENTS_TABLE = "kernel_events";
-const SEQ_TABLE = "kernel_event_scope_seq";
-
-export const DEFAULT_EVENT_PAGE_SIZE = 500;
-export const MAX_EVENT_PAGE_SIZE = 5_000;
-
-export class EventSessionClosedError extends Error {
-  constructor() {
-    super("event session is closed");
-    this.name = "EventSessionClosedError";
-  }
-}
-
-/** Runtime rejection of an emit whose name is not one of the module's declared events. */
-export class UndeclaredEventError extends Error {
-  constructor(readonly moduleId: string, readonly eventName: string) {
-    super(`module '${moduleId}' declares no event named '${eventName}'`);
-    this.name = "UndeclaredEventError";
-  }
-}
-
-/** Runtime rejection of an emit whose topic prefix does not match the emitting module's id. */
-export class EventTopicMismatchError extends Error {
-  constructor(readonly moduleId: string, readonly eventName: string) {
-    super(`event '${eventName}' does not carry module '${moduleId}'s topic prefix '${moduleId}.'`);
-    this.name = "EventTopicMismatchError";
-  }
-}
-
-export class EventLogCorruptionError extends Error {
-  constructor(message: string) {
-    super(`event log corruption: ${message}`);
-    this.name = "EventLogCorruptionError";
-  }
-}
-
-interface PendingEvent {
-  readonly name: string;
-  readonly payload: string;
-}
-
-export interface EmittedEvent {
-  readonly scope: Scope;
-  readonly moduleId: string;
-  readonly seq: number;
-  readonly name: EventName;
-  readonly payload: unknown;
-  readonly createdAt: number;
-}
-
-export interface EventReplaySlice {
-  readonly events: readonly EmittedEvent[];
-  /** The highest seq in this slice (or `since` when empty); resume from here for the next page. */
-  readonly lastSeq: number;
-  /** More events exist beyond `lastSeq` in this scope; the caller must fetch the next slice. */
-  readonly truncated: boolean;
-}
-
-interface EventRow {
-  scope: string;
-  seq: number;
-  module_id: string;
-  name: string;
-  payload: string;
-  created_at: number;
-}
-
-/** Mirrors the *lossless* parts of a JSON round-trip (dropping explicit `undefined` object
- * keys, folding `-0` to `0`) without touching anything else, so genuinely non-JSON-safe shapes
- * (Date, bigint, function values) still show up as a mismatch against the real encoded output. */
-function normalizeJsonSafe(value: unknown): unknown {
-  if (typeof value === "number") return Object.is(value, -0) ? 0 : value;
-  if (Array.isArray(value)) return value.map(normalizeJsonSafe);
-  if (value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
-    const result: Record<string, unknown> = {};
-    for (const [key, entry] of Object.entries(value)) {
-      if (entry === undefined) continue;
-      result[key] = normalizeJsonSafe(entry);
-    }
-    return result;
-  }
-  return value;
-}
-
-function encodeEventPayload(value: unknown, name: string): string {
-  try {
-    const encoded = JSON.stringify(value);
-    if (encoded === undefined) throw new TypeError("value is not JSON-serializable");
-    if (!isDeepStrictEqual(JSON.parse(encoded) as unknown, normalizeJsonSafe(value))) {
-      throw new TypeError("value changes during JSON encoding");
-    }
-    return encoded;
-  } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
-    throw new TypeError(`event '${name}' payload must be JSON-safe: ${reason}`);
-  }
-}
-
-function decodeEventPayload(raw: string, seq: number): unknown {
-  try {
-    return JSON.parse(raw) as unknown;
-  } catch {
-    throw new EventLogCorruptionError(`event at seq ${seq} has invalid JSON payload`);
-  }
-}
-
-function rowToEvent(row: EventRow): EmittedEvent {
-  return {
-    scope: row.scope as Scope,
-    moduleId: row.module_id,
-    seq: row.seq,
-    name: row.name as EventName,
-    payload: decodeEventPayload(row.payload, row.seq),
-    createdAt: row.created_at,
-  };
-}
-
-/**
- * Install the kernel event-log catalog on a caller's shared connection (KAPI-1 W4c fix 3b): the
- * append-only `kernel_events` table + its per-scope high-water `kernel_event_scope_seq`. Idempotent
- * (`IF NOT EXISTS`), so a fresh `EventLogPersistence` still ensures it, but the src startup migration
- * calls this up front so the tables are never created at request time by a lazily-built control host.
- * Mirrors `ensureWorkflowJournalSchema(db)` — kernel-owned DDL, installed on the shared handle.
- */
-export function ensureEventLogSchema(db: Database): void {
-  db.run(`CREATE TABLE IF NOT EXISTS ${EVENTS_TABLE} (
-    scope TEXT NOT NULL,
-    seq INTEGER NOT NULL,
-    module_id TEXT NOT NULL,
-    name TEXT NOT NULL,
-    payload TEXT NOT NULL,
-    created_at INTEGER NOT NULL,
-    PRIMARY KEY (scope, seq)
-  )`);
-  db.run(`CREATE INDEX IF NOT EXISTS ${EVENTS_TABLE}__idx_module ON ${EVENTS_TABLE} (scope, module_id, seq)`);
-  db.run(`CREATE TABLE IF NOT EXISTS ${SEQ_TABLE} (
-    scope TEXT PRIMARY KEY,
-    high_water INTEGER NOT NULL
-  )`);
-}
-
-/** A buffered-intent emit attempt for one module's scoped event log, mirroring EntitySession. */
-export interface EventSession<E> {
-  /** Scope-bound writer installed directly as ModuleCtx.events. */
-  readonly events: EventWriter<E>;
-  readonly pendingEvents: number;
-  /** Close the async attempt before entering its synchronous commit transaction. */
-  seal(): void;
-  /** Flush into a caller-owned synchronous transaction (for workflow checkpoint composition). */
-  flush(): void;
-  /** Seal and flush in a standalone synchronous transaction. */
-  commit(): void;
-  /** Close the session and forget every buffered emit. */
-  discard(): void;
-}
-
-class EventSessionRuntime<E> implements EventSession<E> {
-  readonly events: EventWriter<E>;
-  readonly #buffer: PendingEvent[] = [];
-  #closed = false;
-  #finished = false;
-
-  constructor(
-    readonly db: Database,
-    readonly clock: Clock,
-    readonly scope: Scope,
-    readonly moduleId: string,
-    readonly schemas: ReadonlyMap<string, z.ZodType>,
-  ) {
-    const prefix = `${moduleId}.`;
-    const emit = async (name: string, payload: unknown): Promise<void> => {
-      this.#assertOpen();
-      if (!name.startsWith(prefix) || name.length === prefix.length) {
-        throw new EventTopicMismatchError(moduleId, name);
-      }
-      const schema = this.schemas.get(name);
-      if (!schema) throw new UndeclaredEventError(moduleId, name);
-      const parsed: unknown = schema.parse(payload);
-      const encoded = encodeEventPayload(parsed, name);
-      this.#buffer.push({ name, payload: encoded });
-    };
-    this.events = { emit } as unknown as EventWriter<E>;
-  }
-
-  get pendingEvents(): number {
-    return this.#buffer.length;
-  }
-
-  #assertOpen(): void {
-    if (this.#closed) throw new EventSessionClosedError();
-  }
-
-  seal(): void {
-    if (this.#finished) throw new EventSessionClosedError();
-    this.#closed = true;
-  }
-
-  #flushInsideTransaction(): void {
-    if (!this.#closed || this.#finished) throw new EventSessionClosedError();
-    if (!this.db.inTransaction) throw new Error("event emits must flush inside a synchronous SQLite transaction");
-    try {
-      if (this.#buffer.length > 0) {
-        const bumped = this.db.query(`INSERT INTO ${SEQ_TABLE} (scope, high_water) VALUES (?, ?)
-          ON CONFLICT(scope) DO UPDATE SET high_water = high_water + excluded.high_water
-          RETURNING high_water`).get(this.scope, this.#buffer.length) as { high_water: number };
-        const firstSeq = bumped.high_water - this.#buffer.length + 1;
-        const now = this.clock.now();
-        const insert = this.db.query(`INSERT INTO ${EVENTS_TABLE} (scope, seq, module_id, name, payload, created_at)
-          VALUES (?, ?, ?, ?, ?, ?)`);
-        this.#buffer.forEach((pending, index) => {
-          insert.run(this.scope, firstSeq + index, this.moduleId, pending.name, pending.payload, now);
-        });
-      }
-      this.#finished = true;
-    } catch (error) {
-      this.#finished = true;
-      throw error;
-    }
-  }
-
-  flush(): void {
-    this.#flushInsideTransaction();
-  }
-
-  commit(): void {
-    if (!this.#closed) this.seal();
-    this.db.transaction(() => this.#flushInsideTransaction())();
-  }
-
-  discard(): void {
-    if (this.#finished) throw new EventSessionClosedError();
-    this.#closed = true;
-    this.#buffer.length = 0;
-    this.#finished = true;
-  }
-}
-
-export interface EventLogOptions {
-  readonly db: Database;
-  readonly clock: Clock;
-  readonly modules?: Iterable<ModuleDefinition<ModuleManifest>>;
-}
-
-/** Kernel-owned scoped event log: schema-derived per module (like K4's entities), one shared
- * append-only table underneath so a scope's events interleave in one monotonic sequence. */
-export class EventLogPersistence {
-  readonly #modules = new Map<string, ReadonlyMap<string, z.ZodType>>();
-
-  constructor(readonly options: EventLogOptions) {
-    ensureEventLogSchema(options.db);
-    for (const module of options.modules ?? []) this.register(module);
-  }
-
-  register<M extends ModuleManifest>(module: ModuleDefinition<M>): void {
-    if (this.#modules.has(module.id)) throw new Error(`module '${module.id}' event log is already installed`);
-    this.#modules.set(module.id, new Map(Object.entries(module.events ?? {}) as Array<[string, z.ZodType]>));
-  }
-
-  begin<M extends ModuleManifest>(module: ModuleDefinition<M>, scope: Scope): EventSession<NonNullable<M["events"]>> {
-    const schemas = this.#modules.get(module.id);
-    if (!schemas) throw new Error(`module '${module.id}' event log is not installed`);
-    return new EventSessionRuntime<NonNullable<M["events"]>>(this.options.db, this.options.clock, scope, module.id, schemas);
-  }
-
-  /**
-   * Paged, ordered replay of one scope's events across every module that wrote into it, or — with
-   * `moduleId` (KAPI-1 / G-D) — narrowed to just that module's events, using the existing
-   * `(scope, module_id, seq)` index. Omitting `moduleId` reproduces the prior all-module behavior
-   * exactly, including how `truncated` is computed (the scope-wide high-water mark); with a
-   * `moduleId` filter, truncation instead checks for a further matching row past `lastSeq`, since
-   * the scope-wide high-water mark would over-report truncation for a narrowed module view.
-   */
-  replay(scope: Scope, since: number, limit = DEFAULT_EVENT_PAGE_SIZE, moduleId?: string): EventReplaySlice {
-    if (!Number.isInteger(since) || since < 0) throw new TypeError("since must be a non-negative integer");
-    if (!Number.isFinite(limit)) throw new TypeError("limit must be finite");
-    const pageSize = Math.min(Math.max(Math.trunc(limit), 1), MAX_EVENT_PAGE_SIZE);
-    const rows = moduleId === undefined
-      ? this.options.db.query(`SELECT scope, seq, module_id, name, payload, created_at
-          FROM ${EVENTS_TABLE} WHERE scope = ? AND seq > ? ORDER BY seq ASC LIMIT ?`)
-          .all(scope, since, pageSize) as EventRow[]
-      : this.options.db.query(`SELECT scope, seq, module_id, name, payload, created_at
-          FROM ${EVENTS_TABLE} WHERE scope = ? AND module_id = ? AND seq > ? ORDER BY seq ASC LIMIT ?`)
-          .all(scope, moduleId, since, pageSize) as EventRow[];
-    const events = rows.map(rowToEvent);
-    const lastSeq = events.at(-1)?.seq ?? since;
-    const truncated = rows.length === pageSize && this.#hasMoreEvents(scope, lastSeq, moduleId);
-    return { events, lastSeq, truncated };
-  }
-
-  /** Whether a further event exists past `lastSeq` — scope-wide via the high-water mark (unchanged
-   *  fast path), or module-scoped via an index-backed existence check when `moduleId` is given. */
-  #hasMoreEvents(scope: Scope, lastSeq: number, moduleId: string | undefined): boolean {
-    if (moduleId === undefined) return this.highWater(scope) > lastSeq;
-    return this.options.db.query(`SELECT 1 FROM ${EVENTS_TABLE}
-      WHERE scope = ? AND module_id = ? AND seq > ? LIMIT 1`).get(scope, moduleId, lastSeq) != null;
-  }
-
-  /** The highest seq ever assigned within a scope; survives even if that scope's rows are pruned. */
-  highWater(scope: Scope): number {
-    const row = this.options.db.query(`SELECT high_water FROM ${SEQ_TABLE} WHERE scope = ?`).get(scope) as { high_water: number } | undefined;
-    return row?.high_water ?? 0;
-  }
-}
-
-export function createEventLogPersistence(options: EventLogOptions): EventLogPersistence {
-  return new EventLogPersistence(options);
-}