@humwick/server 0.130.0 → 0.130.2

package/node_modules/@humwick/kernel/message-authority-chaos-worker.ts

@@ -1,200 +0,0 @@
-import { relayEnv } from "@humwick/sdk/env";
-/**
- * Real-process Stage-0 MESSAGE-authority crash fixture. This is intentionally a fake store: it
- * gives the dormant participant one CAS-shaped SQL statement without installing any production
- * timer table or call site.
- */
-import { existsSync, writeFileSync } from "node:fs";
-import { Database } from "bun:sqlite";
-import { z } from "zod";
-import {
-  createSqliteModuleHost,
-  createRealClock,
-  defineModule,
-  type MessageAuthorityOperation,
-  type MessageAuthorityStore,
-  type ModuleCtx,
-  type OpCommitFaults,
-  type WorkflowStepCommitFaults,
-} from "./index";
-
-const DB_PATH = required("AUTHORITY_CHAOS_DB");
-const COMMAND = required("AUTHORITY_CHAOS_COMMAND");
-const ID = process.env.AUTHORITY_CHAOS_ID ?? "sentinel";
-const TIMER_ID = process.env.AUTHORITY_CHAOS_TIMER_ID ?? "timer";
-const BOUNDARY = process.env.AUTHORITY_CHAOS_BOUNDARY ?? "none";
-const ROLE = process.env.AUTHORITY_CHAOS_ROLE ?? "winner";
-const READY_FILE = process.env.AUTHORITY_CHAOS_READY_FILE;
-const RELEASE_FILE = process.env.AUTHORITY_CHAOS_RELEASE_FILE;
-
-function required(name: string): string {
-  const value = relayEnv(process.env, name);
-  if (!value) throw new Error(`missing ${name}`);
-  return value;
-}
-
-function selfKill(): never {
-  process.kill(process.pid, "SIGKILL");
-  throw new Error("unreachable");
-}
-
-function pausePreFlush(): void {
-  if (!READY_FILE || !RELEASE_FILE) throw new Error("race loser needs marker paths");
-  writeFileSync(READY_FILE, "ready");
-  const deadline = Date.now() + 10_000;
-  while (!existsSync(RELEASE_FILE)) {
-    if (Date.now() >= deadline) throw new Error("race release timed out");
-    Bun.sleepSync(5);
-  }
-}
-
-function workflowFaults(): WorkflowStepCommitFaults | undefined {
-  switch (BOUNDARY) {
-    case "pre-tx": return { beforeCommit: selfKill };
-    case "after-lease-fence": return { afterFenceBeforeParticipant: selfKill };
-    case "after-participant-sql": return { afterParticipantBeforeEntities: selfKill };
-    case "between-entity-event": return { betweenEntitiesAndEvents: selfKill };
-    case "after-event-flush": return { insideTxBeforeJournal: selfKill };
-    case "after-journal-sql": return { afterJournalBeforeCommit: selfKill };
-    case "after-commit": return { afterCommit: selfKill };
-    default: return undefined;
-  }
-}
-
-function openDb(): Database {
-  const db = new Database(DB_PATH);
-  db.run("PRAGMA busy_timeout = 5000");
-  db.run("PRAGMA journal_mode = WAL");
-  db.run(`CREATE TABLE IF NOT EXISTS fake_message_authority (
-    timer_id TEXT PRIMARY KEY,
-    fence INTEGER NOT NULL,
-    winner TEXT NOT NULL
-  )`);
-  return db;
-}
-
-class FakeStore implements MessageAuthorityStore {
-  constructor(readonly winner: string) {}
-
-  executeInTransaction(db: Database, operation: MessageAuthorityOperation) {
-    if (!db.inTransaction) throw new Error("fake authority SQL escaped the caller transaction");
-    const changes = db.query(`INSERT INTO fake_message_authority (timer_id, fence, winner)
-      VALUES (?, ?, ?) ON CONFLICT(timer_id) DO UPDATE SET fence = excluded.fence, winner = excluded.winner
-      WHERE fake_message_authority.fence < excluded.fence`)
-      .run(operation.timer.timerId, operation.fence, this.winner).changes;
-    return changes === 1
-      ? { ok: true as const }
-      : { ok: false as const, code: "contended" as const, reason: "participant CAS lost" };
-  }
-}
-
-const inputSchema = z.object({ id: z.string(), timerId: z.string() });
-const stateSchema = z.object({ id: z.string(), timerId: z.string() });
-
-function stageSentinels(ctx: ModuleCtx, id: string, timerId: string): Promise<void> {
-  ctx.messageAuthority.applyFence({ timer: { timerId, message: { body: id } }, fence: 1 });
-  return Promise.all([
-    (ctx.entities as unknown as { mark: { create(row: { id: string; owner: string }): Promise<unknown> } })
-      .mark.create({ id, owner: id }),
-    ctx.events.emit("authority-chaos.wrote", { id }),
-  ]).then(() => undefined);
-}
-
-const module = defineModule({
-  id: "authority-chaos",
-  title: "MESSAGE authority chaos fixture",
-  description: "Fake-store transaction-enlistment proof.",
-  entities: { mark: { schema: z.object({ id: z.string(), owner: z.string() }) } },
-  events: { "authority-chaos.wrote": z.object({ id: z.string() }) },
-  workflows: {
-    execute: {
-      input: inputSchema,
-      state: stateSchema,
-      init: (input) => input,
-      start: "commit",
-      steps: {
-        commit: {
-          run: async (ctx, state) => {
-            await stageSentinels(ctx, state.id, state.timerId);
-            return { state, next: "done" as const };
-          },
-        },
-      },
-    },
-    seed: {
-      input: z.object({ id: z.string() }),
-      state: z.object({ id: z.string() }),
-      init: (input) => input,
-      start: "park",
-      steps: {
-        // Park rather than finish so the seed itself remains easy to distinguish from an op's rows.
-        park: { run: async (ctx, state) => ({ state, next: "park", sleepUntil: ctx.clock.now() + 60_000 }) },
-      },
-    },
-  },
-  ops: {
-    write: {
-      kind: "mutation",
-      grant: "authority-chaos:write",
-      summary: "Stage authority/entity/event/workflow-seed sentinels.",
-      idempotent: false,
-      emits: ["authority-chaos.wrote"],
-      input: inputSchema,
-      output: z.object({ ok: z.boolean() }),
-      handler: async (ctx, input) => {
-        await stageSentinels(ctx, input.id, input.timerId);
-        await ctx.workflows.start("seed", { id: input.id }, {
-          idempotencyKey: `seed-${input.id}`,
-          enlist: "op-commit",
-        });
-        return { ok: true };
-      },
-    },
-  },
-});
-
-function build(db: Database) {
-  const opFaults: OpCommitFaults | undefined = ROLE === "loser" ? { beforeCommit: pausePreFlush } : undefined;
-  const host = createSqliteModuleHost({
-    db,
-    clock: createRealClock(),
-    leaseTtlMs: 100,
-    busyTimeoutMs: 5_000,
-    messageAuthority: new FakeStore(ID),
-    workflowCommitFaults: () => ROLE === "loser" && COMMAND === "workflow"
-      ? { beforeCommit: pausePreFlush }
-      : workflowFaults(),
-    ...(opFaults ? { opCommitFaults: () => opFaults } : {}),
-  });
-  host.register(module);
-  return host;
-}
-
-async function recover(host: ReturnType<typeof build>, db: Database): Promise<void> {
-  const driver = host.workflowDriver(module, { actor: "chaos", grants: [] });
-  const deadline = Date.now() + 5_000;
-  while (Date.now() < deadline) {
-    await driver.recover();
-    const open = (db.query(`SELECT COUNT(*) AS n FROM workflow_instances
-      WHERE status NOT IN ('done','failed','canceled','sleeping','waiting')`).get() as { n: number }).n;
-    if (open === 0) return;
-    await Bun.sleep(10);
-  }
-  throw new Error("recovery timed out");
-}
-
-const db = openDb();
-const host = build(db);
-
-if (COMMAND === "workflow") {
-  await host.workflowDriver(module, { actor: "chaos", grants: [] })
-    .start("execute", { id: ID, timerId: TIMER_ID }, { idempotencyKey: `workflow-${ID}` });
-} else if (COMMAND === "op") {
-  await host.invoke(module, "write", { actor: "chaos", grants: ["authority-chaos:write"] }, { id: ID, timerId: TIMER_ID });
-} else if (COMMAND === "recover") {
-  await recover(host, db);
-} else {
-  throw new Error(`unknown command ${COMMAND}`);
-}
-
-db.close();

package/node_modules/@humwick/kernel/message-authority.ts

@@ -1,281 +0,0 @@
-import type { Database } from "bun:sqlite";
-
-/**
- * The timer projection carried by every MESSAGE-authority operation. The host participant accepts
- * only pure-message timers: a message must be present and `command` must be absent/null. Keeping
- * this check at the participant boundary means a future caller cannot accidentally enlist a shell
- * timer in the MESSAGE authority protocol even if it bypasses a module-level schema.
- */
-export interface MessageAuthorityTimer {
-  readonly timerId: string;
-  readonly message: unknown;
-  readonly command?: never;
-}
-
-export type MessageAuthorityEngine = "legacy" | "kernel";
-export type MessageAuthorityDecision = "dispatch" | "expired" | "terminal";
-
-export interface ApplyMessageAuthorityFence {
-  readonly kind: "applyFence";
-  readonly timer: MessageAuthorityTimer;
-  readonly fence: number;
-  readonly updatedAt?: number;
-}
-
-export interface DecideMessageAuthorityFire {
-  readonly kind: "decideFire";
-  readonly timer: MessageAuthorityTimer;
-  readonly fence: number;
-  readonly generation: number;
-  readonly run: number;
-  readonly engine: MessageAuthorityEngine;
-  readonly decision: MessageAuthorityDecision;
-  /** The deadline this exact generation/run woke for. It is part of the ownership predicate. */
-  readonly fireAt: number;
-  /** Authority lifecycle after this decision commits. */
-  readonly lifecycle: "scheduled" | "fired" | "disabled";
-  /** Immutable fire-row recurrence projection; null for a terminal decision. */
-  readonly nextRun: number | null;
-  readonly nextRunAt: number | null;
-  readonly decidedAt: number;
-  readonly sendPayload: unknown | null;
-  readonly idempotencyKey: string | null;
-}
-
-export interface CommitMessageAuthorityTransfer {
-  readonly kind: "commitTransfer";
-  readonly timer: MessageAuthorityTimer;
-  readonly fence: number;
-  readonly cutoverEpoch: number;
-  readonly generation: number;
-  readonly nextRun: number;
-  readonly from: "legacy";
-  readonly to: "kernel";
-}
-
-export interface CommitMessageAuthorityReverseTransfer {
-  readonly kind: "commitReverseTransfer";
-  readonly timer: MessageAuthorityTimer;
-  readonly fence: number;
-  readonly cutoverEpoch: number;
-  readonly generation: number;
-  readonly nextRun: number;
-  readonly from: "kernel";
-  readonly to: "legacy";
-}
-
-/** The deliberately closed set of host-owned authority mutations available to a module attempt. */
-export type MessageAuthorityOperation =
-  | ApplyMessageAuthorityFence
-  | DecideMessageAuthorityFire
-  | CommitMessageAuthorityTransfer
-  | CommitMessageAuthorityReverseTransfer;
-
-export type MessageAuthorityRefusal = {
-  readonly ok: false;
-  /** `superseded` is terminal for the exact workflow generation that proposed the operation;
-   *  ordinary authority refusal/contention remains retryable. */
-  readonly code: "contended" | "authority_refused" | "superseded";
-  readonly reason: string;
-};
-
-export type MessageAuthorityStoreResult = { readonly ok: true } | MessageAuthorityRefusal;
-
-/**
- * Host-owned implementation boundary. Stage 0 intentionally provides no production store: tests
- * inject a fake SQL store. Implementations must execute on the same Database connection passed to
- * the participant and must not open a transaction of their own.
- */
-export interface MessageAuthorityStore {
-  executeInTransaction(db: Database, operation: MessageAuthorityOperation): MessageAuthorityStoreResult;
-}
-
-/** The narrow module-visible staging surface. It exposes no SQL and no generic callback escape. */
-export interface MessageAuthorityParticipant {
-  applyFence(input: Omit<ApplyMessageAuthorityFence, "kind">): void;
-  decideFire(input: Omit<DecideMessageAuthorityFire, "kind">): void;
-  commitTransfer(input: Omit<CommitMessageAuthorityTransfer, "kind">): void;
-  commitReverseTransfer(input: Omit<CommitMessageAuthorityReverseTransfer, "kind">): void;
-}
-
-export class MessageAuthorityUnavailableError extends Error {
-  constructor() {
-    super("MESSAGE authority participation is not configured on this host");
-    this.name = "MessageAuthorityUnavailableError";
-  }
-}
-
-export class MessageAuthoritySessionClosedError extends Error {
-  constructor() {
-    super("MESSAGE authority participant session is closed");
-    this.name = "MessageAuthoritySessionClosedError";
-  }
-}
-
-export class MessageAuthorityShapeError extends TypeError {
-  constructor(message: string) {
-    super(message);
-    this.name = "MessageAuthorityShapeError";
-  }
-}
-
-/** A failed store predicate. Throwing this aborts the caller-owned transaction as one unit. */
-export class MessageAuthorityCommitRefusedError extends Error {
-  constructor(readonly refusal: MessageAuthorityRefusal, readonly operation: MessageAuthorityOperation) {
-    super(`MESSAGE authority ${refusal.code}: ${refusal.reason}`);
-    this.name = "MessageAuthorityCommitRefusedError";
-  }
-}
-
-export interface MessageAuthoritySession {
-  readonly participant: MessageAuthorityParticipant;
-  readonly pendingOperations: number;
-  seal(): void;
-  flush(): void;
-  /** Consume the clone-safe participant operations for an async persistence envelope. */
-  operations(): readonly MessageAuthorityOperation[];
-  discard(): void;
-}
-
-function assertInteger(value: number, name: string, minimum: number): void {
-  if (!Number.isSafeInteger(value) || value < minimum) {
-    throw new MessageAuthorityShapeError(`${name} must be a safe integer >= ${minimum}`);
-  }
-}
-
-function assertPureMessageTimer(timer: MessageAuthorityTimer): void {
-  if (typeof timer !== "object" || timer === null) {
-    throw new MessageAuthorityShapeError("MESSAGE authority requires a timer projection");
-  }
-  if (typeof timer.timerId !== "string" || timer.timerId.length === 0) {
-    throw new MessageAuthorityShapeError("MESSAGE authority requires a non-empty timerId");
-  }
-  if (timer.message === undefined || timer.message === null) {
-    throw new MessageAuthorityShapeError(`timer '${timer.timerId}' has no message payload`);
-  }
-  const command = (timer as unknown as { command?: unknown }).command;
-  if (command !== undefined && command !== null) {
-    throw new MessageAuthorityShapeError(`timer '${timer.timerId}' is command-shaped and cannot join MESSAGE authority`);
-  }
-}
-
-function validateOperation(operation: MessageAuthorityOperation): void {
-  assertPureMessageTimer(operation.timer);
-  assertInteger(operation.fence, "fence", 0);
-  if (operation.kind === "applyFence") {
-    if (operation.updatedAt !== undefined) assertInteger(operation.updatedAt, "updatedAt", 0);
-    return;
-  }
-  assertInteger(operation.generation, "generation", 0);
-  if (operation.kind === "decideFire") {
-    assertInteger(operation.run, "run", 1);
-    if (operation.run === Number.MAX_SAFE_INTEGER) {
-      throw new MessageAuthorityShapeError("run must leave room for the authority advance");
-    }
-    assertInteger(operation.fireAt, "fireAt", 0);
-    assertInteger(operation.decidedAt, "decidedAt", 0);
-    if (operation.nextRun !== null) assertInteger(operation.nextRun, "nextRun", 1);
-    if (operation.nextRunAt !== null) assertInteger(operation.nextRunAt, "nextRunAt", 0);
-    if ((operation.nextRun === null) !== (operation.nextRunAt === null)) {
-      throw new MessageAuthorityShapeError("nextRun and nextRunAt must both be null or both be present");
-    }
-    if ((operation.lifecycle === "scheduled") !== (operation.nextRun !== null)) {
-      throw new MessageAuthorityShapeError("scheduled lifecycle requires a next run/deadline");
-    }
-    if (operation.decision === "expired" && operation.lifecycle !== "disabled") {
-      throw new MessageAuthorityShapeError("expired decisions must disable authority");
-    }
-    const dispatch = operation.decision === "dispatch";
-    if (dispatch !== (operation.sendPayload !== null && operation.idempotencyKey !== null)) {
-      throw new MessageAuthorityShapeError("dispatch decisions require sendPayload and idempotencyKey only");
-    }
-    return;
-  }
-  assertInteger(operation.cutoverEpoch, "cutoverEpoch", 0);
-  assertInteger(operation.nextRun, "nextRun", 0);
-}
-
-class MessageAuthoritySessionRuntime implements MessageAuthoritySession {
-  readonly participant: MessageAuthorityParticipant;
-  readonly #operations: MessageAuthorityOperation[] = [];
-  #closed = false;
-  #finished = false;
-
-  constructor(
-    readonly available: boolean,
-    readonly flushOperations?: (operations: readonly MessageAuthorityOperation[]) => void,
-  ) {
-    this.participant = Object.freeze({
-      applyFence: (input: Omit<ApplyMessageAuthorityFence, "kind">) => this.#stage({ kind: "applyFence", ...input }),
-      decideFire: (input: Omit<DecideMessageAuthorityFire, "kind">) => this.#stage({ kind: "decideFire", ...input }),
-      commitTransfer: (input: Omit<CommitMessageAuthorityTransfer, "kind">) => this.#stage({ kind: "commitTransfer", ...input }),
-      commitReverseTransfer: (input: Omit<CommitMessageAuthorityReverseTransfer, "kind">) =>
-        this.#stage({ kind: "commitReverseTransfer", ...input }),
-    });
-  }
-
-  get pendingOperations(): number {
-    return this.#operations.length;
-  }
-
-  #stage(operation: MessageAuthorityOperation): void {
-    if (this.#closed) throw new MessageAuthoritySessionClosedError();
-    if (!this.available) throw new MessageAuthorityUnavailableError();
-    validateOperation(operation);
-    // Snapshot the validated projection. Holding the caller's mutable object would let detached
-    // code add `command` after validation but before commit and smuggle a command-shaped timer to
-    // the store. The participant needs only these two fields, so discard every other property.
-    const timer = Object.freeze({ timerId: operation.timer.timerId, message: operation.timer.message });
-    this.#operations.push(Object.freeze({ ...operation, timer }) as MessageAuthorityOperation);
-  }
-
-  seal(): void {
-    if (this.#finished) throw new MessageAuthoritySessionClosedError();
-    this.#closed = true;
-  }
-
-  flush(): void {
-    if (!this.#closed || this.#finished) throw new MessageAuthoritySessionClosedError();
-    try {
-      if (!this.flushOperations) throw new Error("async MESSAGE authority operations must commit through KernelPersistence");
-      this.flushOperations(this.#operations);
-      this.#finished = true;
-    } catch (error) {
-      this.#finished = true;
-      throw error;
-    }
-  }
-
-  operations(): readonly MessageAuthorityOperation[] {
-    if (!this.#closed || this.#finished) throw new MessageAuthoritySessionClosedError();
-    this.#finished = true;
-    return Object.freeze(this.#operations.map((operation) => structuredClone(operation)));
-  }
-
-  discard(): void {
-    if (this.#finished) throw new MessageAuthoritySessionClosedError();
-    this.#closed = true;
-    this.#operations.length = 0;
-    this.#finished = true;
-  }
-}
-
-/** Begin one participant session, scoped to exactly one op or workflow-step attempt. */
-export function beginMessageAuthoritySession(db: Database, store?: MessageAuthorityStore): MessageAuthoritySession;
-export function beginMessageAuthoritySession(available: boolean): MessageAuthoritySession;
-export function beginMessageAuthoritySession(dbOrAvailable: Database | boolean, store?: MessageAuthorityStore): MessageAuthoritySession {
-  return typeof dbOrAvailable === "boolean"
-    ? new MessageAuthoritySessionRuntime(dbOrAvailable)
-    : new MessageAuthoritySessionRuntime(store !== undefined, (operations) => {
-        if (!dbOrAvailable.inTransaction) {
-          throw new Error("MESSAGE authority operations must flush inside a caller-owned SQLite transaction");
-        }
-        for (const operation of operations) {
-          // The caller-owned handle is passed explicitly. A store that tries to wrap this in another
-          // BEGIN/COMMIT fails as a nested transaction instead of silently escaping the atomic commit.
-          const result = store?.executeInTransaction(dbOrAvailable, operation);
-          if (!result) throw new MessageAuthorityUnavailableError();
-          if (!result.ok) throw new MessageAuthorityCommitRefusedError(result, operation);
-        }
-      });
-}