@aghents/pulse 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,313 @@
+import { Result } from 'neverthrow';
+import { Database } from '@aghents/identity';
+import { SupabaseClient } from '@supabase/supabase-js';
+import { z } from 'zod';
+
+type SeatKind = "human" | "persona";
+type ActorMeta = {
+    actorKind: "human";
+} | {
+    actorKind: "system";
+} | {
+    actorKind: "persona";
+    personaId: string;
+    tier: "heuristic" | "llm";
+    model: string;
+};
+interface PulseGame<State, Event, View> {
+    key: string;
+    create(input: {
+        gameId: string;
+        seed: string;
+        config: unknown;
+        seats: {
+            seatId: string;
+            kind: SeatKind;
+        }[];
+    }): State;
+    advance(state: State, event: Event): {
+        ok: true;
+        state: State;
+    } | {
+        ok: false;
+        error: {
+            code: string;
+            message: string;
+        };
+    };
+    view(state: State, seatId: string): View;
+    clockEvents: {
+        lock: Event;
+        resolve: Event;
+    };
+    /**
+     * Whether `advance` would treat this event as a clock transition. Games that dispatch on a
+     * field (Vouch on `type`) must implement it: `{ type: "lock", extra: true }` is not deep-equal
+     * to `clockEvents.lock` yet runs the clock. Absent, submit falls back to deep equality.
+     */
+    isClockEvent?(event: Event): boolean;
+    phaseOf(state: State): "open" | "lock" | "complete";
+    pulseOf(state: State): number;
+    seqOf(state: State): number;
+}
+declare function definePulseGame<S, E, V>(g: PulseGame<S, E, V>): PulseGame<S, E, V>;
+
+type Timescale = "quick" | "daily";
+/**
+ * Pulse windows: a pulse is one open window followed by one lock window. Every window must be
+ * >= the scheduler cadence (Vercel Cron, once a minute) plus the llm worst case (gateway
+ * MIN_WINDOW_MS = 100s): the clock is only advanced by a tick, a persona is due no later than
+ * windowEnd - (cadence [+ llm worst case]), and a window shorter than that could pass with no
+ * tick able to act inside it. gateway's scheduler.test pins every timescale against it.
+ */
+declare const SCHEDULER_CADENCE_MS = 60000;
+declare const TIMESCALES: Record<Timescale, {
+    openMs: number;
+    lockMs: number;
+}>;
+declare function pulseTimes(startedAtMs: number, timescale: Timescale, pulse: number): {
+    openAtMs: number;
+    lockAtMs: number;
+    resolveAtMs: number;
+};
+
+type PulseError = {
+    code: string;
+    message: string;
+};
+/**
+ * `conflict`: a (gameId, seq) collision, the loser of a race. `llm_budget_exceeded`: the game has
+ * spent its LLM_CALL_BUDGET llm calls (the scheduler skips the persona). `room_full`: the room's
+ * insert trigger (0002) refused the member for capacity, the loser of a join race. `room_closed`:
+ * the same trigger's status path only (0005): the room is no longer open. Everything else is
+ * `store`.
+ */
+type StoreError = {
+    code: "conflict" | "llm_budget_exceeded" | "room_full" | "room_closed" | "store";
+    message: string;
+};
+/** Mirrors the cap inside pulse.spend_llm_call (0002_pulse.sql). */
+declare const LLM_CALL_BUDGET = 200;
+type RoomSettings = {
+    seats: number;
+    timescale: Timescale;
+};
+type RoomStatus = "open" | "playing" | "complete";
+interface RoomRecord {
+    roomId: string;
+    gameKey: string;
+    inviteCode: string;
+    hostUserId: string;
+    settings: RoomSettings;
+    status: RoomStatus;
+}
+interface RoomMember {
+    roomId: string;
+    userId: string;
+    displayName: string;
+}
+interface GameSeatRecord {
+    seatId: string;
+    kind: SeatKind;
+    userId: string | null;
+    personaProfileId: string | null;
+    personaTier: "heuristic" | "llm" | null;
+}
+/**
+ * SERVER-SIDE ONLY: holds seat secrets (kind, persona, user mapping). Clients only ever get a
+ * View through getView. `seats` come back in canonical order (lexicographic by seatId): games
+ * assign roles by folding seats in that order, so any other order would silently reassign them.
+ */
+interface GameRecord {
+    gameId: string;
+    roomId: string;
+    gameKey: string;
+    seed: string;
+    config: unknown;
+    timescale: Timescale;
+    startedAtMs: number;
+    status: GameStatus;
+    seats: GameSeatRecord[];
+}
+type GameStatus = "playing" | "complete";
+interface StoredEvent<E> {
+    seq: number;
+    event: E;
+    actor: ActorMeta;
+}
+interface GameStore<E> {
+    createRoom(room: RoomRecord): Promise<Result<void, StoreError>>;
+    /** Compensation only (rooms.createRoom undoes a room whose host could not be seated). */
+    deleteRoom(roomId: string): Promise<Result<void, StoreError>>;
+    getRoom(roomId: string): Promise<Result<RoomRecord | null, StoreError>>;
+    getRoomByCode(inviteCode: string): Promise<Result<RoomRecord | null, StoreError>>;
+    setRoomStatus(roomId: string, status: RoomStatus): Promise<Result<void, StoreError>>;
+    addMember(member: RoomMember): Promise<Result<void, StoreError>>;
+    listMembers(roomId: string): Promise<Result<RoomMember[], StoreError>>;
+    createGame(game: GameRecord): Promise<Result<void, StoreError>>;
+    getGame(gameId: string): Promise<Result<GameRecord | null, StoreError>>;
+    getLatestGameByRoom(roomId: string): Promise<Result<GameRecord | null, StoreError>>;
+    setGameStatus(gameId: string, status: GameStatus): Promise<Result<void, StoreError>>;
+    listEvents(gameId: string): Promise<Result<StoredEvent<E>[], StoreError>>;
+    /** err `conflict` when (gameId, seq) already exists (the optimistic-concurrency signal). */
+    appendEvent(gameId: string, stored: StoredEvent<E>): Promise<Result<void, StoreError>>;
+    /**
+     * Spend one of the game's LLM_CALL_BUDGET llm calls, atomically; ok(calls so far), or err
+     * `llm_budget_exceeded` with the counter untouched. The scheduler spends before each llm-tier
+     * decision, so the budget counts calls made, not events produced.
+     */
+    spendLlmCall(gameId: string): Promise<Result<number, StoreError>>;
+    /**
+     * Take the game's tick lease for ttlMs: ok(true) when taken, ok(false) when another pass holds
+     * an unexpired one. An expired lease is reacquirable, so a pass that died never wedges a game.
+     */
+    acquireTickLease(gameId: string, ttlMs: number): Promise<Result<boolean, StoreError>>;
+    releaseTickLease(gameId: string): Promise<Result<void, StoreError>>;
+}
+
+declare function foldState<S, E, V>(game: PulseGame<S, E, V>, record: GameRecord, events: StoredEvent<E>[]): Result<S, PulseError>;
+/**
+ * Advance every due phase transition for a game up to nowMs. Lazy scheduler: callers invoke this
+ * before any read or write; there is no cron. Clock events are appended one at a time through the
+ * store's optimistic concurrency; a conflict means another caller already appended that
+ * transition, so the log is re-read and the loop continues from where they left it.
+ */
+declare function catchUp<S, E, V>(game: PulseGame<S, E, V>, store: GameStore<E>, gameId: string, nowMs: number): Promise<Result<S | null, PulseError>>;
+
+declare function submit<S, E, V>(game: PulseGame<S, E, V>, store: GameStore<E>, input: {
+    gameId: string;
+    seatId: string;
+    event: E;
+    nowMs: number;
+    actor: ActorMeta;
+}): Promise<Result<V, PulseError>>;
+type ViewResult<V> = {
+    view: V;
+    deadline: {
+        phase: "open" | "lock";
+        atMs: number;
+    } | null;
+};
+declare function getView<S, E, V>(game: PulseGame<S, E, V>, store: GameStore<E>, input: {
+    gameId: string;
+    seatId: string;
+    nowMs: number;
+}): Promise<Result<ViewResult<V>, PulseError>>;
+/**
+ * The view of one event snapshot, for a caller that has already caught the clock up and holds
+ * the log it wants to derive other facts from (the hub's view route reads `lastActor` off the
+ * same array, so view and actor can never disagree).
+ */
+declare function viewFromEvents<S, E, V>(game: PulseGame<S, E, V>, record: GameRecord, events: StoredEvent<E>[], seatId: string): Result<ViewResult<V>, PulseError>;
+
+declare function createRng(seed: string): () => number;
+
+declare function inviteCode(rng: () => number, length?: number): string;
+declare function createRoom<E>(store: GameStore<E>, input: {
+    roomId: string;
+    gameKey: string;
+    hostUserId: string;
+    hostDisplayName: string;
+    settings: RoomSettings;
+    rng: () => number;
+}): Promise<Result<RoomRecord, PulseError>>;
+declare function joinRoom<E>(store: GameStore<E>, input: {
+    inviteCode: string;
+    userId: string;
+    displayName: string;
+}): Promise<Result<RoomRecord, PulseError>>;
+
+declare class MemoryStore<E> implements GameStore<E> {
+    private readonly nowMs;
+    /** The lease clock; injected because the store never reads the wall clock on its own. */
+    constructor(nowMs?: () => number);
+    private leases;
+    private rooms;
+    private members;
+    private games;
+    private gameOrder;
+    private events;
+    private llmCalls;
+    createRoom(room: RoomRecord): Promise<Result<void, StoreError>>;
+    deleteRoom(roomId: string): Promise<Result<void, StoreError>>;
+    getRoom(roomId: string): Promise<Result<RoomRecord | null, StoreError>>;
+    getRoomByCode(inviteCode: string): Promise<Result<RoomRecord | null, StoreError>>;
+    setRoomStatus(roomId: string, status: RoomStatus): Promise<Result<void, StoreError>>;
+    addMember(member: RoomMember): Promise<Result<void, StoreError>>;
+    listMembers(roomId: string): Promise<Result<RoomMember[], StoreError>>;
+    createGame(game: GameRecord): Promise<Result<void, StoreError>>;
+    getGame(gameId: string): Promise<Result<GameRecord | null, StoreError>>;
+    setGameStatus(gameId: string, status: GameStatus): Promise<Result<void, StoreError>>;
+    getLatestGameByRoom(roomId: string): Promise<Result<GameRecord | null, StoreError>>;
+    listEvents(gameId: string): Promise<Result<StoredEvent<E>[], StoreError>>;
+    appendEvent(gameId: string, stored: StoredEvent<E>): Promise<Result<void, StoreError>>;
+    acquireTickLease(gameId: string, ttlMs: number): Promise<Result<boolean, StoreError>>;
+    releaseTickLease(gameId: string): Promise<Result<void, StoreError>>;
+    spendLlmCall(gameId: string): Promise<Result<number, StoreError>>;
+}
+
+/**
+ * The ONLY module in @aghents/pulse that touches the network. Maps the GameStore contract onto the
+ * pulse.* tables of 0002_pulse.sql through a service-role client; clients never reach these tables.
+ */
+
+declare const envSchema: z.ZodObject<{
+    SUPABASE_URL: z.ZodString;
+    SUPABASE_SERVICE_ROLE_KEY: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    SUPABASE_URL: string;
+    SUPABASE_SERVICE_ROLE_KEY: string;
+}, {
+    SUPABASE_URL: string;
+    SUPABASE_SERVICE_ROLE_KEY: string;
+}>;
+type ServiceEnv = z.infer<typeof envSchema>;
+declare function readServiceEnv(raw: Record<string, string | undefined>): ServiceEnv;
+type Json = Database["pulse"]["Tables"]["game_events"]["Row"]["event"];
+type AppendEventArgs = {
+    p_game_id: string;
+    p_seq: number;
+    p_event: Json;
+    p_actor_kind: string;
+    p_persona_id: string | null;
+    p_tier: string | null;
+    p_model: string | null;
+};
+type PulseDatabase = Omit<Database, "pulse"> & {
+    pulse: Omit<Database["pulse"], "Functions"> & {
+        Functions: Omit<Database["pulse"]["Functions"], "append_event"> & {
+            append_event: {
+                Args: AppendEventArgs;
+                Returns: undefined;
+            };
+        };
+    };
+};
+type PulseServiceClient = SupabaseClient<PulseDatabase>;
+declare function createServiceClient(env: ServiceEnv): PulseServiceClient;
+declare class SupabaseStore<E> implements GameStore<E> {
+    private readonly db;
+    private readonly pageSize;
+    constructor(db: PulseServiceClient, pageSize?: number);
+    private get pulse();
+    createRoom(room: RoomRecord): Promise<Result<void, StoreError>>;
+    deleteRoom(roomId: string): Promise<Result<void, StoreError>>;
+    private roomWhere;
+    getRoom(roomId: string): Promise<Result<RoomRecord | null, StoreError>>;
+    getRoomByCode(inviteCode: string): Promise<Result<RoomRecord | null, StoreError>>;
+    setRoomStatus(roomId: string, status: RoomStatus): Promise<Result<void, StoreError>>;
+    addMember(member: RoomMember): Promise<Result<void, StoreError>>;
+    listMembers(roomId: string): Promise<Result<RoomMember[], StoreError>>;
+    createGame(game: GameRecord): Promise<Result<void, StoreError>>;
+    private gameFromRow;
+    getGame(gameId: string): Promise<Result<GameRecord | null, StoreError>>;
+    setGameStatus(gameId: string, status: GameStatus): Promise<Result<void, StoreError>>;
+    getLatestGameByRoom(roomId: string): Promise<Result<GameRecord | null, StoreError>>;
+    listEvents(gameId: string): Promise<Result<StoredEvent<E>[], StoreError>>;
+    appendEvent(gameId: string, stored: StoredEvent<E>): Promise<Result<void, StoreError>>;
+    acquireTickLease(gameId: string, ttlMs: number): Promise<Result<boolean, StoreError>>;
+    releaseTickLease(gameId: string): Promise<Result<void, StoreError>>;
+    spendLlmCall(gameId: string): Promise<Result<number, StoreError>>;
+}
+
+export { type ActorMeta, type GameRecord, type GameSeatRecord, type GameStatus, type GameStore, LLM_CALL_BUDGET, MemoryStore, type PulseError, type PulseGame, type PulseServiceClient, type RoomMember, type RoomRecord, type RoomSettings, type RoomStatus, SCHEDULER_CADENCE_MS, type SeatKind, type ServiceEnv, type StoreError, type StoredEvent, SupabaseStore, TIMESCALES, type Timescale, type ViewResult, catchUp, createRng, createRoom, createServiceClient, definePulseGame, foldState, getView, inviteCode, joinRoom, pulseTimes, readServiceEnv, submit, viewFromEvents };

package/dist/index.js

@@ -0,0 +1,610 @@
+// src/catchup.ts
+import { err, ok } from "neverthrow";
+
+// src/store.ts
+var LLM_CALL_BUDGET = 200;
+var bySeatId = (seats) => [...seats].sort((a, b) => a.seatId < b.seatId ? -1 : a.seatId > b.seatId ? 1 : 0);
+
+// src/timetable.ts
+var SCHEDULER_CADENCE_MS = 6e4;
+var TIMESCALES = {
+  quick: { openMs: 12e4, lockMs: 12e4 },
+  daily: { openMs: 828e5, lockMs: 36e5 }
+};
+function pulseTimes(startedAtMs, timescale2, pulse) {
+  const { openMs, lockMs } = TIMESCALES[timescale2];
+  const openAtMs = startedAtMs + (pulse - 1) * (openMs + lockMs);
+  return { openAtMs, lockAtMs: openAtMs + openMs, resolveAtMs: openAtMs + openMs + lockMs };
+}
+
+// src/catchup.ts
+var SYSTEM = { actorKind: "system" };
+function guarded(what, fn) {
+  try {
+    return ok(fn());
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    return err({ code: "corrupt_log", message: `${what} threw: ${message}` });
+  }
+}
+function foldState(game, record, events) {
+  const created = guarded(
+    "create",
+    () => game.create({
+      gameId: record.gameId,
+      seed: record.seed,
+      config: record.config,
+      seats: bySeatId(record.seats).map((s) => ({ seatId: s.seatId, kind: s.kind }))
+    })
+  );
+  if (created.isErr()) return err(created.error);
+  let state = created.value;
+  for (const e of events) {
+    const advanced = guarded(`seq ${e.seq}`, () => game.advance(state, e.event));
+    if (advanced.isErr()) return err(advanced.error);
+    const r = advanced.value;
+    if (!r.ok) {
+      return err({ code: "corrupt_log", message: `seq ${e.seq}: ${r.error.code}` });
+    }
+    if (e.seq !== game.seqOf(r.state)) {
+      return err({
+        code: "corrupt_log",
+        message: `seq mismatch: expected ${game.seqOf(r.state)}, stored ${e.seq}`
+      });
+    }
+    state = r.state;
+  }
+  return ok(state);
+}
+async function catchUp(game, store, gameId, nowMs) {
+  const found = await store.getGame(gameId);
+  if (found.isErr()) return err(found.error);
+  const record = found.value;
+  if (!record) return ok(null);
+  const fold = async () => (await store.listEvents(gameId)).andThen((events) => foldState(game, record, events));
+  let folded = await fold();
+  if (folded.isErr()) return err(folded.error);
+  let state = folded.value;
+  while (game.phaseOf(state) !== "complete") {
+    const phase = game.phaseOf(state);
+    const t = pulseTimes(record.startedAtMs, record.timescale, game.pulseOf(state));
+    const dueAt = phase === "open" ? t.lockAtMs : t.resolveAtMs;
+    if (nowMs < dueAt) break;
+    const event = phase === "open" ? game.clockEvents.lock : game.clockEvents.resolve;
+    const advanced = guarded(
+      phase === "open" ? "lock" : "resolve",
+      () => game.advance(state, event)
+    );
+    if (advanced.isErr()) return err(advanced.error);
+    const r = advanced.value;
+    if (!r.ok)
+      return err({ code: r.error.code, message: `clock event refused: ${r.error.message}` });
+    const appended = await store.appendEvent(gameId, {
+      seq: game.seqOf(r.state),
+      event,
+      actor: SYSTEM
+    });
+    if (appended.isOk()) {
+      state = r.state;
+      continue;
+    }
+    if (appended.error.code !== "conflict") return err(appended.error);
+    folded = await fold();
+    if (folded.isErr()) return err(folded.error);
+    if (game.seqOf(folded.value) <= game.seqOf(state)) {
+      return err({
+        code: "conflict",
+        message: `seq ${game.seqOf(r.state)} collided but the log did not advance`
+      });
+    }
+    state = folded.value;
+  }
+  if (game.phaseOf(state) === "complete" && record.status !== "complete") {
+    const marked = await store.setGameStatus(gameId, "complete");
+    if (marked.isErr()) return err(marked.error);
+  }
+  return ok(state);
+}
+
+// src/game.ts
+function definePulseGame(g) {
+  return g;
+}
+
+// src/play.ts
+import { isDeepStrictEqual } from "util";
+import { err as err2, ok as ok2 } from "neverthrow";
+async function seated(game, store, input) {
+  const record = await store.getGame(input.gameId);
+  if (record.isErr()) return err2(record.error);
+  if (!record.value) return err2({ code: "game_not_found", message: "game not found" });
+  const seat = record.value.seats.find((s) => s.seatId === input.seatId);
+  if (!seat) return err2({ code: "not_in_game", message: `no seat ${input.seatId} in this game` });
+  const state = await catchUp(game, store, input.gameId, input.nowMs);
+  if (state.isErr()) return err2(state.error);
+  if (!state.value) return err2({ code: "game_not_found", message: "game not found" });
+  return ok2({ record: record.value, seat, state: state.value });
+}
+var actorMatches = (seat, actor) => seat.kind === "human" ? actor.actorKind === "human" : actor.actorKind === "persona" && actor.personaId === seat.personaProfileId;
+async function submit(game, store, input) {
+  const { lock, resolve } = game.clockEvents;
+  const isClock = game.isClockEvent ?? ((e) => isDeepStrictEqual(e, lock) || isDeepStrictEqual(e, resolve));
+  if (isClock(input.event)) {
+    return err2({ code: "not_allowed", message: "clock events are appended by the scheduler" });
+  }
+  const cur = await seated(game, store, input);
+  if (cur.isErr()) return err2(cur.error);
+  if (!actorMatches(cur.value.seat, input.actor)) {
+    return err2({ code: "invalid_actor", message: `actor does not match seat ${input.seatId}` });
+  }
+  if (game.phaseOf(cur.value.state) === "complete") {
+    return err2({ code: "phase_closed", message: "game is complete" });
+  }
+  const advanced = guarded("advance", () => game.advance(cur.value.state, input.event));
+  if (advanced.isErr()) return err2(advanced.error);
+  const r = advanced.value;
+  if (!r.ok) return err2(r.error);
+  const appended = await store.appendEvent(input.gameId, {
+    seq: game.seqOf(r.state),
+    event: input.event,
+    actor: input.actor
+  });
+  if (appended.isErr()) return err2(appended.error);
+  return guarded("view", () => game.view(r.state, input.seatId));
+}
+function viewOf(game, record, state, seatId) {
+  const phase = game.phaseOf(state);
+  const t = pulseTimes(record.startedAtMs, record.timescale, game.pulseOf(state));
+  const deadline = phase === "open" ? { phase, atMs: t.lockAtMs } : phase === "lock" ? { phase, atMs: t.resolveAtMs } : null;
+  return guarded("view", () => game.view(state, seatId)).map((view) => ({ view, deadline }));
+}
+async function getView(game, store, input) {
+  const cur = await seated(game, store, input);
+  if (cur.isErr()) return err2(cur.error);
+  return viewOf(game, cur.value.record, cur.value.state, input.seatId);
+}
+function viewFromEvents(game, record, events, seatId) {
+  return foldState(game, record, events).andThen((state) => viewOf(game, record, state, seatId));
+}
+
+// src/rng.ts
+function hashSeed(seed) {
+  let h = 1779033703 ^ seed.length;
+  for (let i = 0; i < seed.length; i++) {
+    h = Math.imul(h ^ seed.charCodeAt(i), 3432918353);
+    h = h << 13 | h >>> 19;
+  }
+  return h >>> 0;
+}
+function createRng(seed) {
+  let a = hashSeed(seed);
+  return () => {
+    a = a + 1831565813 | 0;
+    let t = Math.imul(a ^ a >>> 15, 1 | a);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+
+// src/rooms.ts
+import { err as err3, ok as ok3 } from "neverthrow";
+var CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+function inviteCode(rng, length = 6) {
+  let code = "";
+  for (let i = 0; i < length; i++) code += CODE_ALPHABET[Math.floor(rng() * CODE_ALPHABET.length)];
+  return code;
+}
+async function createRoom(store, input) {
+  const room = {
+    roomId: input.roomId,
+    gameKey: input.gameKey,
+    inviteCode: inviteCode(input.rng),
+    hostUserId: input.hostUserId,
+    settings: input.settings,
+    status: "open"
+  };
+  const created = await store.createRoom(room);
+  if (created.isErr()) return err3(created.error);
+  const added = await store.addMember({
+    roomId: input.roomId,
+    userId: input.hostUserId,
+    displayName: input.hostDisplayName
+  });
+  if (added.isOk()) return ok3(room);
+  const undone = await store.deleteRoom(input.roomId);
+  if (undone.isErr()) {
+    return err3({
+      code: added.error.code,
+      message: `${added.error.message}; undo failed: ${undone.error.message}`
+    });
+  }
+  return err3(added.error);
+}
+async function joinRoom(store, input) {
+  const found = await store.getRoomByCode(input.inviteCode);
+  if (found.isErr()) return err3(found.error);
+  const room = found.value;
+  if (!room) return err3({ code: "room_not_found", message: "room not found" });
+  if (room.status !== "open") return err3({ code: "room_closed", message: "room is not open" });
+  const members = await store.listMembers(room.roomId);
+  if (members.isErr()) return err3(members.error);
+  if (members.value.some((m) => m.userId === input.userId)) return ok3(room);
+  if (members.value.length >= room.settings.seats) {
+    return err3({ code: "room_full", message: "room is full" });
+  }
+  const added = await store.addMember({
+    roomId: room.roomId,
+    userId: input.userId,
+    displayName: input.displayName
+  });
+  if (added.isErr()) return err3(added.error);
+  return ok3(room);
+}
+
+// src/store.memory.ts
+import { err as err4, ok as ok4 } from "neverthrow";
+var MemoryStore = class {
+  /** The lease clock; injected because the store never reads the wall clock on its own. */
+  constructor(nowMs = () => 0) {
+    this.nowMs = nowMs;
+  }
+  nowMs;
+  leases = /* @__PURE__ */ new Map();
+  rooms = /* @__PURE__ */ new Map();
+  members = /* @__PURE__ */ new Map();
+  games = /* @__PURE__ */ new Map();
+  gameOrder = [];
+  events = /* @__PURE__ */ new Map();
+  llmCalls = /* @__PURE__ */ new Map();
+  async createRoom(room) {
+    this.rooms.set(room.roomId, structuredClone(room));
+    return ok4(void 0);
+  }
+  async deleteRoom(roomId) {
+    this.rooms.delete(roomId);
+    this.members.delete(roomId);
+    return ok4(void 0);
+  }
+  async getRoom(roomId) {
+    return ok4(structuredClone(this.rooms.get(roomId) ?? null));
+  }
+  async getRoomByCode(inviteCode2) {
+    for (const r of this.rooms.values()) {
+      if (r.inviteCode === inviteCode2) return ok4(structuredClone(r));
+    }
+    return ok4(null);
+  }
+  async setRoomStatus(roomId, status) {
+    const r = this.rooms.get(roomId);
+    if (r) this.rooms.set(roomId, { ...r, status });
+    return ok4(void 0);
+  }
+  async addMember(member) {
+    const list = this.members.get(member.roomId) ?? [];
+    if (!list.some((m) => m.userId === member.userId)) list.push({ ...member });
+    this.members.set(member.roomId, list);
+    return ok4(void 0);
+  }
+  async listMembers(roomId) {
+    return ok4(structuredClone(this.members.get(roomId) ?? []));
+  }
+  async createGame(game) {
+    const personas = game.seats.flatMap((s) => s.personaProfileId ? [s.personaProfileId] : []);
+    if (new Set(personas).size !== personas.length) {
+      return err4({
+        code: "store",
+        message: "game_seats_persona_once: a persona sits once per game"
+      });
+    }
+    this.games.set(game.gameId, structuredClone({ ...game, seats: bySeatId(game.seats) }));
+    this.gameOrder.push(game.gameId);
+    return ok4(void 0);
+  }
+  async getGame(gameId) {
+    return ok4(structuredClone(this.games.get(gameId) ?? null));
+  }
+  async setGameStatus(gameId, status) {
+    const g = this.games.get(gameId);
+    if (g) this.games.set(gameId, { ...g, status });
+    return ok4(void 0);
+  }
+  async getLatestGameByRoom(roomId) {
+    for (let i = this.gameOrder.length - 1; i >= 0; i--) {
+      const g = this.games.get(this.gameOrder[i] ?? "");
+      if (g && g.roomId === roomId) return ok4(structuredClone(g));
+    }
+    return ok4(null);
+  }
+  async listEvents(gameId) {
+    return ok4(structuredClone(this.events.get(gameId) ?? []).sort((a, b) => a.seq - b.seq));
+  }
+  async appendEvent(gameId, stored) {
+    const list = this.events.get(gameId) ?? [];
+    if (list.some((e) => e.seq === stored.seq)) {
+      return err4({ code: "conflict", message: `duplicate seq ${stored.seq} for ${gameId}` });
+    }
+    list.push(structuredClone(stored));
+    this.events.set(gameId, list);
+    return ok4(void 0);
+  }
+  async acquireTickLease(gameId, ttlMs) {
+    if (!this.games.has(gameId)) return err4({ code: "store", message: `no game ${gameId}` });
+    const now = this.nowMs();
+    const until = this.leases.get(gameId);
+    if (until !== void 0 && until >= now) return ok4(false);
+    this.leases.set(gameId, now + ttlMs);
+    return ok4(true);
+  }
+  async releaseTickLease(gameId) {
+    this.leases.delete(gameId);
+    return ok4(void 0);
+  }
+  async spendLlmCall(gameId) {
+    if (!this.games.has(gameId)) return err4({ code: "store", message: `no game ${gameId}` });
+    const calls = (this.llmCalls.get(gameId) ?? 0) + 1;
+    if (calls > LLM_CALL_BUDGET) {
+      return err4({ code: "llm_budget_exceeded", message: "llm_budget_exceeded" });
+    }
+    this.llmCalls.set(gameId, calls);
+    return ok4(calls);
+  }
+};
+
+// src/store.supabase.ts
+import { createClient } from "@supabase/supabase-js";
+import { err as err5, ok as ok5 } from "neverthrow";
+import { z } from "zod";
+var envSchema = z.object({
+  SUPABASE_URL: z.string().url(),
+  SUPABASE_SERVICE_ROLE_KEY: z.string().min(20)
+});
+function readServiceEnv(raw) {
+  return envSchema.parse(raw);
+}
+function createServiceClient(env) {
+  return createClient(env.SUPABASE_URL, env.SUPABASE_SERVICE_ROLE_KEY, {
+    auth: { autoRefreshToken: false, persistSession: false }
+  });
+}
+var timescale = z.enum(["quick", "daily"]);
+var roomRow = z.object({
+  id: z.string(),
+  game_key: z.string(),
+  invite_code: z.string(),
+  host_user_id: z.string(),
+  settings: z.object({ seats: z.number().int(), timescale }),
+  status: z.enum(["open", "playing", "complete"])
+});
+var seatRow = z.object({
+  seat_id: z.string(),
+  kind: z.enum(["human", "persona"]),
+  user_id: z.string().nullable(),
+  persona_profile_id: z.string().nullable(),
+  persona_tier: z.enum(["heuristic", "llm"]).nullable()
+});
+var gameRow = z.object({
+  id: z.string(),
+  room_id: z.string(),
+  game_key: z.string(),
+  seed: z.string(),
+  config: z.unknown(),
+  timescale,
+  started_at_ms: z.number(),
+  status: z.enum(["playing", "complete"])
+});
+var actorRow = z.discriminatedUnion("actor_kind", [
+  z.object({ actor_kind: z.literal("human") }),
+  z.object({ actor_kind: z.literal("system") }),
+  z.object({
+    actor_kind: z.literal("persona"),
+    persona_id: z.string(),
+    tier: z.enum(["heuristic", "llm"]),
+    model: z.string()
+  })
+]);
+var eventRow = z.object({ seq: z.number().int(), event: z.unknown() }).and(actorRow);
+var toActor = (a) => a.actor_kind === "persona" ? { actorKind: "persona", personaId: a.persona_id, tier: a.tier, model: a.model } : { actorKind: a.actor_kind };
+var fromActor = (a) => a.actorKind === "persona" ? { p_actor_kind: a.actorKind, p_persona_id: a.personaId, p_tier: a.tier, p_model: a.model } : { p_actor_kind: a.actorKind, p_persona_id: null, p_tier: null, p_model: null };
+var parse = (schema, value) => {
+  const r = schema.safeParse(value);
+  return r.success ? ok5(r.data) : err5({ code: "store", message: r.error.message });
+};
+var dbErr = (e) => ({ code: "store", message: e.message });
+var toRoom = (r) => ({
+  roomId: r.id,
+  gameKey: r.game_key,
+  inviteCode: r.invite_code,
+  hostUserId: r.host_user_id,
+  settings: r.settings,
+  status: r.status
+});
+var asJson = (v) => v;
+var SupabaseStore = class {
+  // pageSize mirrors the Data API's max_rows (supabase/config.toml); smaller only in tests.
+  constructor(db, pageSize = 1e3) {
+    this.db = db;
+    this.pageSize = pageSize;
+  }
+  db;
+  pageSize;
+  get pulse() {
+    return this.db.schema("pulse");
+  }
+  async createRoom(room) {
+    const { error } = await this.pulse.from("rooms").insert({
+      id: room.roomId,
+      game_key: room.gameKey,
+      invite_code: room.inviteCode,
+      host_user_id: room.hostUserId,
+      settings: room.settings,
+      status: room.status
+    });
+    return error ? err5(dbErr(error)) : ok5(void 0);
+  }
+  async deleteRoom(roomId) {
+    const { error } = await this.pulse.from("rooms").delete().eq("id", roomId);
+    return error ? err5(dbErr(error)) : ok5(void 0);
+  }
+  async roomWhere(column, value) {
+    const { data, error } = await this.pulse.from("rooms").select().eq(column, value).maybeSingle();
+    if (error) return err5(dbErr(error));
+    return data ? parse(roomRow, data).map(toRoom) : ok5(null);
+  }
+  getRoom(roomId) {
+    return this.roomWhere("id", roomId);
+  }
+  getRoomByCode(inviteCode2) {
+    return this.roomWhere("invite_code", inviteCode2);
+  }
+  async setRoomStatus(roomId, status) {
+    const { error } = await this.pulse.from("rooms").update({ status }).eq("id", roomId);
+    return error ? err5(dbErr(error)) : ok5(void 0);
+  }
+  async addMember(member) {
+    const { error } = await this.pulse.from("room_members").upsert(
+      { room_id: member.roomId, user_id: member.userId, display_name: member.displayName },
+      { onConflict: "room_id,user_id" }
+    );
+    if (!error) return ok5(void 0);
+    if (error.code === "23514") {
+      for (const code of ["room_full", "room_closed"]) {
+        if (error.message.includes(code)) return err5({ code, message: error.message });
+      }
+    }
+    return err5(dbErr(error));
+  }
+  async listMembers(roomId) {
+    const { data, error } = await this.pulse.from("room_members").select().eq("room_id", roomId).order("joined_at", { ascending: true });
+    if (error) return err5(dbErr(error));
+    return ok5(
+      data.map((r) => ({ roomId: r.room_id, userId: r.user_id, displayName: r.display_name }))
+    );
+  }
+  async createGame(game) {
+    const { error } = await this.pulse.from("games").insert({
+      id: game.gameId,
+      room_id: game.roomId,
+      game_key: game.gameKey,
+      seed: game.seed,
+      config: asJson(game.config),
+      timescale: game.timescale,
+      started_at_ms: game.startedAtMs,
+      status: game.status
+    });
+    if (error) return err5(dbErr(error));
+    const { error: seatErr } = await this.pulse.from("game_seats").insert(
+      game.seats.map((s) => ({
+        game_id: game.gameId,
+        seat_id: s.seatId,
+        kind: s.kind,
+        user_id: s.userId,
+        persona_profile_id: s.personaProfileId,
+        persona_tier: s.personaTier
+      }))
+    );
+    if (!seatErr) return ok5(void 0);
+    const { error: undo } = await this.pulse.from("games").delete().eq("id", game.gameId);
+    return err5(
+      dbErr(undo ? { message: `${seatErr.message}; undo failed: ${undo.message}` } : seatErr)
+    );
+  }
+  async gameFromRow(raw) {
+    const row = parse(gameRow, raw);
+    if (row.isErr()) return err5(row.error);
+    const { data, error } = await this.pulse.from("game_seats").select().eq("game_id", row.value.id).order("seat_id", { ascending: true });
+    if (error) return err5(dbErr(error));
+    return parse(z.array(seatRow), data).map((seats) => ({
+      gameId: row.value.id,
+      roomId: row.value.room_id,
+      gameKey: row.value.game_key,
+      seed: row.value.seed,
+      config: row.value.config,
+      timescale: row.value.timescale,
+      startedAtMs: row.value.started_at_ms,
+      status: row.value.status,
+      seats: seats.map((s) => ({
+        seatId: s.seat_id,
+        kind: s.kind,
+        userId: s.user_id,
+        personaProfileId: s.persona_profile_id,
+        personaTier: s.persona_tier
+      }))
+    }));
+  }
+  async getGame(gameId) {
+    const { data, error } = await this.pulse.from("games").select().eq("id", gameId).maybeSingle();
+    if (error) return err5(dbErr(error));
+    return data ? this.gameFromRow(data) : ok5(null);
+  }
+  async setGameStatus(gameId, status) {
+    const { error } = await this.pulse.from("games").update({ status }).eq("id", gameId);
+    return error ? err5(dbErr(error)) : ok5(void 0);
+  }
+  async getLatestGameByRoom(roomId) {
+    const { data, error } = await this.pulse.from("games").select().eq("room_id", roomId).order("created_at", { ascending: false }).limit(1).maybeSingle();
+    if (error) return err5(dbErr(error));
+    return data ? this.gameFromRow(data) : ok5(null);
+  }
+  async listEvents(gameId) {
+    const data = [];
+    for (let from = 0; ; from += this.pageSize) {
+      const page = await this.pulse.from("game_events").select().eq("game_id", gameId).order("seq", { ascending: true }).range(from, from + this.pageSize - 1);
+      if (page.error) return err5(dbErr(page.error));
+      data.push(...page.data);
+      if (page.data.length < this.pageSize) break;
+    }
+    return parse(z.array(eventRow), data).map(
+      (rows) => rows.map((r) => ({ seq: r.seq, event: r.event, actor: toActor(r) }))
+    );
+  }
+  async appendEvent(gameId, stored) {
+    const { error } = await this.pulse.rpc("append_event", {
+      p_game_id: gameId,
+      p_seq: stored.seq,
+      p_event: asJson(stored.event),
+      ...fromActor(stored.actor)
+    });
+    if (!error) return ok5(void 0);
+    if (error.code === "23505") return err5({ code: "conflict", message: error.message });
+    return err5(dbErr(error));
+  }
+  async acquireTickLease(gameId, ttlMs) {
+    const { data, error } = await this.pulse.rpc("acquire_tick_lease", {
+      p_game_id: gameId,
+      p_ttl_ms: ttlMs
+    });
+    return error ? err5(dbErr(error)) : ok5(data);
+  }
+  async releaseTickLease(gameId) {
+    const { error } = await this.pulse.rpc("release_tick_lease", { p_game_id: gameId });
+    return error ? err5(dbErr(error)) : ok5(void 0);
+  }
+  async spendLlmCall(gameId) {
+    const { data, error } = await this.pulse.rpc("spend_llm_call", { p_game_id: gameId });
+    if (!error) return ok5(data);
+    if (error.code === "23514" && error.message.includes("llm_budget_exceeded")) {
+      return err5({ code: "llm_budget_exceeded", message: error.message });
+    }
+    return err5(dbErr(error));
+  }
+};
+export {
+  LLM_CALL_BUDGET,
+  MemoryStore,
+  SCHEDULER_CADENCE_MS,
+  SupabaseStore,
+  TIMESCALES,
+  catchUp,
+  createRng,
+  createRoom,
+  createServiceClient,
+  definePulseGame,
+  foldState,
+  getView,
+  inviteCode,
+  joinRoom,
+  pulseTimes,
+  readServiceEnv,
+  submit,
+  viewFromEvents
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@aghents/pulse",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@supabase/supabase-js": "^2.110.2",
+    "neverthrow": "^8.1.1",
+    "zod": "^3.24.1",
+    "@aghents/identity": "0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  }
+}