@humwick/server 0.130.1 → 0.130.3

package/node_modules/@humwick/kernel/persistence.ts

@@ -1,510 +0,0 @@
-import type { Database } from "bun:sqlite";
-import { Buffer } from "node:buffer";
-import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
-import type {
-  Clock,
-  EntityDecl,
-  EntityListOptions,
-  EntityPage,
-  EntityStore,
-  EntityStores,
-  ModuleDefinition,
-  ModuleManifest,
-  Scope,
-} from "./contract";
-import { assertValidManifest } from "./manifest-validation";
-import {
-  decodeField,
-  encodeField,
-  installModuleEntities,
-  type EntityField,
-  type EntityTable,
-} from "./persistence-schema";
-
-export const DEFAULT_ENTITY_PAGE_SIZE = 50;
-export const MAX_ENTITY_PAGE_SIZE = 200;
-
-export class EntityNotFoundError extends Error {
-  constructor(readonly moduleId: string, readonly entityName: string, readonly key: unknown) {
-    super(`entity '${moduleId}.${entityName}' with key '${String(key)}' was not found`);
-    this.name = "EntityNotFoundError";
-  }
-}
-
-export class EntityConflictError extends Error {
-  constructor(readonly moduleId: string, readonly entityName: string, readonly key: unknown) {
-    super(`stale entity version for '${moduleId}.${entityName}' key '${String(key)}'`);
-    this.name = "EntityConflictError";
-  }
-}
-
-export class EntitySessionClosedError extends Error {
-  constructor() {
-    super("entity session is closed");
-    this.name = "EntitySessionClosedError";
-  }
-}
-
-type EntityValue = Record<string, unknown>;
-type StoredRow = Record<string, unknown> & { version: number };
-type Mutation =
-  | { readonly kind: "put"; readonly table: EntityTable; readonly key: unknown; readonly expectedVersion: number | null; value: EntityValue }
-  | { readonly kind: "delete"; readonly table: EntityTable; readonly key: unknown; readonly expectedVersion: number };
-
-interface RowState {
-  readonly table: EntityTable;
-  readonly key: unknown;
-  readonly expectedVersion: number | null;
-  value?: EntityValue;
-  deleted?: boolean;
-  mutation?: Mutation;
-}
-
-interface CursorPayload {
-  readonly v: 2;
-  readonly module: string;
-  readonly entity: string;
-  readonly scope: string;
-  readonly type: string;
-  readonly key: string | number;
-}
-
-function signCursorBody(secret: Buffer, body: string): string {
-  return createHmac("sha256", secret).update(body).digest("base64url");
-}
-
-/** Length-prefixed (not delimited) so no field value, however constructed, can forge a collision. */
-function keyIdentity(table: EntityTable, key: unknown): string {
-  const encoded = encodeField(table.key, key);
-  const parts = [table.name, typeof encoded, String(encoded)];
-  return parts.map((part) => `${part.length}:${part}`).join("");
-}
-
-function rowValue(table: EntityTable, row: StoredRow): EntityValue {
-  const raw: EntityValue = {};
-  for (const field of table.fields) {
-    const value = decodeField(field, row[field.name]);
-    if (value !== undefined) raw[field.name] = value;
-  }
-  return table.decl.schema.parse(raw) as EntityValue;
-}
-
-function encodeCursor(secret: Buffer, table: EntityTable, scope: Scope, key: unknown): string {
-  const encoded = encodeField(table.key, key);
-  const payload: CursorPayload = {
-    v: 2,
-    module: table.moduleId,
-    entity: table.entityName,
-    scope,
-    type: typeof encoded,
-    key: typeof encoded === "bigint" ? encoded.toString() : encoded as string | number,
-  };
-  const body = Buffer.from(JSON.stringify(payload)).toString("base64url");
-  return `${body}.${signCursorBody(secret, body)}`;
-}
-
-function decodeCursor(secret: Buffer, table: EntityTable, scope: Scope, cursor: string): unknown {
-  try {
-    const separator = cursor.lastIndexOf(".");
-    if (separator < 0) throw new Error();
-    const body = cursor.slice(0, separator);
-    const signature = Buffer.from(cursor.slice(separator + 1));
-    const expected = Buffer.from(signCursorBody(secret, body));
-    if (signature.length !== expected.length || !timingSafeEqual(signature, expected)) throw new Error();
-    const payload = JSON.parse(Buffer.from(body, "base64url").toString("utf8")) as CursorPayload;
-    if (payload.v !== 2 || payload.module !== table.moduleId || payload.entity !== table.entityName || payload.scope !== scope) {
-      throw new Error();
-    }
-    if (payload.type === "bigint") return BigInt(payload.key);
-    if (payload.type !== typeof payload.key) throw new Error();
-    return payload.key;
-  } catch {
-    throw new TypeError(`invalid cursor for entity '${table.moduleId}.${table.entityName}'`);
-  }
-}
-
-function compareKeys(table: EntityTable, left: unknown, right: unknown): number {
-  const a = encodeField(table.key, left);
-  const b = encodeField(table.key, right);
-  if (a === b) return 0;
-  return a! < b! ? -1 : 1;
-}
-
-function parsedWhere(table: EntityTable, where: Readonly<Record<string, unknown>> | undefined): ReadonlyMap<EntityField, unknown> {
-  const result = new Map<EntityField, unknown>();
-  for (const [name, value] of Object.entries(where ?? {})) {
-    const field = table.fieldByName.get(name);
-    if (!field) throw new TypeError(`unknown where field '${name}' on '${table.moduleId}.${table.entityName}'`);
-    result.set(field, field.schema.parse(value));
-  }
-  return result;
-}
-
-function matchesWhere(value: EntityValue, where: ReadonlyMap<EntityField, unknown>): boolean {
-  for (const [field, expected] of where) {
-    if (encodeField(field, value[field.name]) !== encodeField(field, expected)) return false;
-  }
-  return true;
-}
-
-function pageSize(limit: number | undefined): number {
-  const resolved = limit ?? DEFAULT_ENTITY_PAGE_SIZE;
-  if (!Number.isInteger(resolved) || resolved < 1 || resolved > MAX_ENTITY_PAGE_SIZE) {
-    throw new RangeError(`entity page limit must be an integer from 1 to ${MAX_ENTITY_PAGE_SIZE}`);
-  }
-  return resolved;
-}
-
-export interface EntitySession<E> {
-  /** Scope-bound stores installed directly as ModuleCtx.entities. */
-  readonly entities: EntityStores<E>;
-  readonly pendingMutations: 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 mutation. */
-  discard(): void;
-}
-
-class EntitySessionRuntime<E> implements EntitySession<E> {
-  readonly entities: EntityStores<E>;
-  readonly #states = new Map<string, RowState>();
-  #closed = false;
-  #finished = false;
-
-  constructor(
-    readonly db: Database,
-    readonly clock: Clock,
-    readonly scope: Scope,
-    readonly cursorSecret: Buffer,
-    tables: ReadonlyMap<string, EntityTable>,
-  ) {
-    const stores: Record<string, EntityStore> = {};
-    for (const [name, table] of tables) stores[name] = this.#store(table);
-    this.entities = Object.freeze(stores) as EntityStores<E>;
-  }
-
-  get pendingMutations(): number {
-    let count = 0;
-    for (const state of this.#states.values()) if (state.mutation) count++;
-    return count;
-  }
-
-  #assertOpen(): void {
-    if (this.#closed) throw new EntitySessionClosedError();
-  }
-
-  #read(table: EntityTable, key: unknown): RowState {
-    const identity = keyIdentity(table, key);
-    const known = this.#states.get(identity);
-    if (known) return known;
-    const columns = [...table.fields.map((field) => field.quoted), "version"].join(", ");
-    const row = this.db.query(`SELECT ${columns} FROM ${table.quoted} WHERE scope = ? AND ${table.key.quoted} = ?`)
-      .get(this.scope, encodeField(table.key, key)) as StoredRow | null;
-    const state: RowState = {
-      table,
-      key,
-      expectedVersion: row?.version ?? null,
-      value: row ? rowValue(table, row) : undefined,
-    };
-    this.#states.set(identity, state);
-    return state;
-  }
-
-  #remember(table: EntityTable, row: StoredRow): RowState {
-    const value = rowValue(table, row);
-    const key = value[table.key.name];
-    const identity = keyIdentity(table, key);
-    const known = this.#states.get(identity);
-    if (known) return known;
-    const state: RowState = { table, key, expectedVersion: row.version, value };
-    this.#states.set(identity, state);
-    return state;
-  }
-
-  #store(table: EntityTable): EntityStore {
-    return {
-      get: async (key) => {
-        this.#assertOpen();
-        const state = this.#read(table, key);
-        return state.deleted ? undefined : state.value;
-      },
-      list: async (options) => this.#list(table, options as EntityListOptions<EntityValue> | undefined),
-      create: async (input) => {
-        this.#assertOpen();
-        const value = table.decl.schema.parse(input) as EntityValue;
-        const key = value[table.key.name];
-        const state = this.#read(table, key);
-        if (!state.deleted && state.value !== undefined) throw new EntityConflictError(table.moduleId, table.entityName, key);
-        state.value = value;
-        state.deleted = false;
-        state.mutation = { kind: "put", table, key, expectedVersion: state.expectedVersion, value };
-        return value;
-      },
-      update: async (key, patch) => {
-        this.#assertOpen();
-        const state = this.#read(table, key);
-        if (state.deleted || !state.value) throw new EntityNotFoundError(table.moduleId, table.entityName, key);
-        const value = table.decl.schema.parse({ ...state.value, ...patch }) as EntityValue;
-        if (keyIdentity(table, value[table.key.name]) !== keyIdentity(table, key)) {
-          throw new TypeError(`entity key '${table.key.name}' cannot be changed`);
-        }
-        state.value = value;
-        state.mutation = { kind: "put", table, key, expectedVersion: state.expectedVersion, value };
-        return value;
-      },
-      delete: async (key) => {
-        this.#assertOpen();
-        const state = this.#read(table, key);
-        if (state.deleted || !state.value) return false;
-        state.deleted = true;
-        state.value = undefined;
-        if (state.expectedVersion === null) state.mutation = undefined;
-        else state.mutation = { kind: "delete", table, key, expectedVersion: state.expectedVersion };
-        return true;
-      },
-    };
-  }
-
-  async #list(table: EntityTable, options: EntityListOptions<EntityValue> | undefined): Promise<EntityPage<EntityValue>> {
-    this.#assertOpen();
-    const limit = pageSize(options?.limit);
-    const where = parsedWhere(table, options?.where);
-    const cursorKey = options?.cursor ? decodeCursor(this.cursorSecret, table, this.scope, options.cursor) : undefined;
-    const clauses = ["scope = ?"];
-    const bindings: Array<string | number | bigint | null> = [this.scope];
-    for (const [field, value] of where) {
-      const encoded = encodeField(field, value);
-      clauses.push(encoded === null ? `${field.quoted} IS NULL` : `${field.quoted} = ?`);
-      if (encoded !== null) bindings.push(encoded);
-    }
-    if (cursorKey !== undefined) {
-      clauses.push(`${table.key.quoted} > ?`);
-      bindings.push(encodeField(table.key, cursorKey));
-    }
-    const stagedCount = [...this.#states.values()].filter((state) => state.table === table && state.mutation).length;
-    bindings.push(limit + stagedCount + 1);
-    const columns = [...table.fields.map((field) => field.quoted), "version"].join(", ");
-    const rows = this.db.query(`SELECT ${columns} FROM ${table.quoted}
-      WHERE ${clauses.join(" AND ")} ORDER BY ${table.key.quoted} ASC LIMIT ?`).all(...bindings) as StoredRow[];
-
-    const candidates = new Map<string, EntityValue>();
-    for (const row of rows) {
-      const state = this.#remember(table, row);
-      if (!state.deleted && state.value && matchesWhere(state.value, where)) {
-        candidates.set(keyIdentity(table, state.key), state.value);
-      }
-    }
-    for (const state of this.#states.values()) {
-      if (state.table !== table || state.deleted || !state.value || !matchesWhere(state.value, where)) continue;
-      if (cursorKey !== undefined && compareKeys(table, state.key, cursorKey) <= 0) continue;
-      candidates.set(keyIdentity(table, state.key), state.value);
-    }
-    const sorted = [...candidates.values()].sort((a, b) => compareKeys(table, a[table.key.name], b[table.key.name]));
-    const hasMore = sorted.length > limit;
-    const items = sorted.slice(0, limit);
-    return {
-      items,
-      ...(hasMore ? { cursor: encodeCursor(this.cursorSecret, table, this.scope, items[items.length - 1]![table.key.name]) } : {}),
-    };
-  }
-
-  seal(): void {
-    if (this.#finished) throw new EntitySessionClosedError();
-    this.#closed = true;
-  }
-
-  #flushInsideTransaction(): void {
-    if (!this.#closed || this.#finished) throw new EntitySessionClosedError();
-    if (!this.db.inTransaction) throw new Error("entity mutations must flush inside a synchronous SQLite transaction");
-    try {
-      for (const state of this.#states.values()) {
-        const mutation = state.mutation;
-        if (!mutation) continue;
-        const now = this.clock.now();
-        let changes: number;
-        if (mutation.kind === "delete") {
-          changes = this.db.query(`DELETE FROM ${mutation.table.quoted}
-            WHERE scope = ? AND ${mutation.table.key.quoted} = ? AND version = ?`)
-            .run(this.scope, encodeField(mutation.table.key, mutation.key), mutation.expectedVersion).changes;
-        } else if (mutation.expectedVersion === null) {
-          const fields = mutation.table.fields;
-          const columns = ["scope", ...fields.map((field) => field.quoted), "version", "created_at", "updated_at"];
-          const placeholders = columns.map(() => "?").join(", ");
-          changes = this.db.query(`INSERT INTO ${mutation.table.quoted} (${columns.join(", ")})
-            VALUES (${placeholders}) ON CONFLICT(scope, ${mutation.table.key.quoted}) DO NOTHING`)
-            .run(this.scope, ...fields.map((field) => encodeField(field, mutation.value[field.name])), 0, now, now).changes;
-        } else {
-          const fields = mutation.table.fields.filter((field) => field !== mutation.table.key);
-          const assignments = [
-            ...fields.map((field) => `${field.quoted} = ?`),
-            "version = version + 1",
-            "updated_at = ?",
-          ];
-          changes = this.db.query(`UPDATE ${mutation.table.quoted}
-            SET ${assignments.join(", ")}
-            WHERE scope = ? AND ${mutation.table.key.quoted} = ? AND version = ?`)
-            .run(...fields.map((field) => encodeField(field, mutation.value[field.name])), now, this.scope,
-              encodeField(mutation.table.key, mutation.key), mutation.expectedVersion).changes;
-        }
-        if (changes !== 1) throw new EntityConflictError(mutation.table.moduleId, mutation.table.entityName, mutation.key);
-      }
-      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 EntitySessionClosedError();
-    this.#closed = true;
-    this.#states.clear();
-    this.#finished = true;
-  }
-}
-
-export interface EntityPersistenceOptions {
-  readonly db: Database;
-  readonly clock: Clock;
-  readonly modules?: Iterable<ModuleDefinition<ModuleManifest>>;
-}
-
-type RowMeta = { readonly created_at: number; readonly updated_at: number };
-
-/** One decoded `kernel_entity__<module>__<entity>` row, module-agnostic (KAPI-1 / G-C). `fields`
- *  carries every declared column decoded through the entity's own codec (including the key) —
- *  raw, ungated: a control-plane caller applies redaction/allowlisting on top (§1.3, K-C3). */
-export interface EntityRawRow {
-  readonly module: string;
-  readonly entity: string;
-  readonly scope: Scope;
-  readonly key: unknown;
-  readonly version: number;
-  readonly createdAt: number;
-  readonly updatedAt: number;
-  readonly fields: Readonly<Record<string, unknown>>;
-}
-
-export interface EntityRawListOptions {
-  readonly where?: Readonly<Record<string, unknown>>;
-  readonly cursor?: string;
-  readonly limit?: number;
-}
-
-export interface EntityRawPage {
-  readonly items: readonly EntityRawRow[];
-  readonly cursor?: string;
-}
-
-function toRawRow(table: EntityTable, scope: Scope, row: StoredRow & RowMeta): EntityRawRow {
-  const value = rowValue(table, row);
-  return {
-    module: table.moduleId,
-    entity: table.entityName,
-    scope,
-    key: value[table.key.name],
-    version: row.version,
-    createdAt: row.created_at,
-    updatedAt: row.updated_at,
-    fields: value,
-  };
-}
-
-export class EntityPersistence {
-  readonly #tables = new Map<string, ReadonlyMap<string, EntityTable>>();
-  readonly #cursorSecret = randomBytes(32);
-
-  constructor(readonly options: EntityPersistenceOptions) {
-    options.db.run("PRAGMA foreign_keys = ON");
-    const { foreign_keys: enforced } = options.db.query("PRAGMA foreign_keys").get() as { foreign_keys: number };
-    if (enforced !== 1) {
-      throw new Error("entity persistence requires PRAGMA foreign_keys = ON to be honored by the injected SQLite handle");
-    }
-    for (const module of options.modules ?? []) this.register(module);
-  }
-
-  register<M extends ModuleManifest>(module: ModuleDefinition<M>): void {
-    assertValidManifest(module);
-    if (this.#tables.has(module.id)) throw new Error(`module '${module.id}' entity persistence is already installed`);
-    this.#tables.set(module.id, installModuleEntities(this.options.db, module));
-  }
-
-  begin<M extends ModuleManifest>(module: ModuleDefinition<M>, scope: Scope): EntitySession<M["entities"]> {
-    const tables = this.#tables.get(module.id);
-    if (!tables) throw new Error(`module '${module.id}' entity persistence is not installed`);
-    return new EntitySessionRuntime<M["entities"]>(this.options.db, this.options.clock, scope, this.#cursorSecret, tables);
-  }
-
-  #lookupTable(moduleId: string, entityName: string): EntityTable | undefined {
-    return this.#tables.get(moduleId)?.get(entityName);
-  }
-
-  /**
-   * Generic `(module, entity, key)` point read (KAPI-1 / G-C) — the module-agnostic sibling of
-   * `EntityStore.get`, usable without a module's typed `ModuleDefinition` on hand. Returns
-   * `undefined` for an unregistered module/entity (not an error: a caller enumerating module ids
-   * dynamically should see "no such row," not a throw) or an absent key, exactly like `getInstance`
-   * on the workflow journal. No owner-scoping or redaction — that's the control module's job.
-   */
-  readEntity(moduleId: string, entityName: string, scope: Scope, key: unknown): EntityRawRow | undefined {
-    const table = this.#lookupTable(moduleId, entityName);
-    if (!table) return undefined;
-    const columns = [...table.fields.map((field) => field.quoted), "version", "created_at", "updated_at"].join(", ");
-    const row = this.options.db.query(`SELECT ${columns} FROM ${table.quoted} WHERE scope = ? AND ${table.key.quoted} = ?`)
-      .get(scope, encodeField(table.key, key)) as (StoredRow & RowMeta) | null;
-    return row ? toRawRow(table, scope, row) : undefined;
-  }
-
-  /**
-   * Generic `(module, entity)` cursor-paginated list (KAPI-1 / G-C), mirroring `EntityStore.list`'s
-   * cursor/where semantics but keyed by string module/entity names instead of a typed
-   * `ModuleDefinition`. Returns an empty page for an unregistered module/entity. No owner-scoping
-   * or redaction — the control module filters/gates the raw rows this returns.
-   */
-  listEntity(moduleId: string, entityName: string, scope: Scope, options?: EntityRawListOptions): EntityRawPage {
-    const table = this.#lookupTable(moduleId, entityName);
-    if (!table) return { items: [] };
-    const limit = pageSize(options?.limit);
-    const where = parsedWhere(table, options?.where);
-    const cursorKey = options?.cursor ? decodeCursor(this.#cursorSecret, table, scope, options.cursor) : undefined;
-    const clauses = ["scope = ?"];
-    const bindings: Array<string | number | bigint | null> = [scope];
-    for (const [field, value] of where) {
-      const encoded = encodeField(field, value);
-      clauses.push(encoded === null ? `${field.quoted} IS NULL` : `${field.quoted} = ?`);
-      if (encoded !== null) bindings.push(encoded);
-    }
-    if (cursorKey !== undefined) {
-      clauses.push(`${table.key.quoted} > ?`);
-      bindings.push(encodeField(table.key, cursorKey));
-    }
-    bindings.push(limit + 1);
-    const columns = [...table.fields.map((field) => field.quoted), "version", "created_at", "updated_at"].join(", ");
-    const rows = this.options.db.query(`SELECT ${columns} FROM ${table.quoted}
-      WHERE ${clauses.join(" AND ")} ORDER BY ${table.key.quoted} ASC LIMIT ?`)
-      .all(...bindings) as Array<StoredRow & RowMeta>;
-    const hasMore = rows.length > limit;
-    const items = rows.slice(0, limit).map((row) => toRawRow(table, scope, row));
-    return {
-      items,
-      ...(hasMore ? { cursor: encodeCursor(this.#cursorSecret, table, scope, items[items.length - 1]!.key) } : {}),
-    };
-  }
-}
-
-export function createEntityPersistence(options: EntityPersistenceOptions): EntityPersistence {
-  return new EntityPersistence(options);
-}

package/node_modules/@humwick/kernel/registry.ts

@@ -1,60 +0,0 @@
-import type { ModuleDefinition, ModuleManifest } from "./contract";
-import { assertValidManifest } from "./manifest-validation";
-
-export class DuplicateModuleIdError extends Error {
-  constructor(readonly moduleId: string) {
-    super(`module '${moduleId}' is already registered`);
-    this.name = "DuplicateModuleIdError";
-  }
-}
-
-export class UnknownModuleError extends Error {
-  constructor(readonly moduleId: string) {
-    super(`module '${moduleId}' is not registered`);
-    this.name = "UnknownModuleError";
-  }
-}
-
-type AnyModuleDefinition = ModuleDefinition<ModuleManifest>;
-
-/** In-process catalog of validated, compile-time module definitions. */
-export class ModuleRegistry {
-  readonly #modules = new Map<string, AnyModuleDefinition>();
-
-  constructor(definitions: Iterable<AnyModuleDefinition> = []) {
-    for (const definition of definitions) this.register(definition);
-  }
-
-  register<const M extends ModuleManifest>(definition: ModuleDefinition<M>): ModuleDefinition<M> {
-    assertValidManifest(definition);
-    if (this.#modules.has(definition.id)) throw new DuplicateModuleIdError(definition.id);
-    this.#modules.set(definition.id, definition as AnyModuleDefinition);
-    return definition;
-  }
-
-  has(moduleId: string): boolean {
-    return this.#modules.has(moduleId);
-  }
-
-  get(moduleId: string): AnyModuleDefinition | undefined {
-    return this.#modules.get(moduleId);
-  }
-
-  require(moduleId: string): AnyModuleDefinition {
-    const definition = this.get(moduleId);
-    if (!definition) throw new UnknownModuleError(moduleId);
-    return definition;
-  }
-
-  list(): readonly AnyModuleDefinition[] {
-    return [...this.#modules.values()];
-  }
-
-  get size(): number {
-    return this.#modules.size;
-  }
-}
-
-export function createModuleRegistry(definitions: Iterable<AnyModuleDefinition> = []): ModuleRegistry {
-  return new ModuleRegistry(definitions);
-}