@astrosheep/keiyaku 4.0.0 → 4.0.2

package/build/src/akuma/heart/schema.js

@@ -1,4 +1,4 @@
-const HEART_SCHEMA_VERSION = 6;
+const HEART_SCHEMA_VERSION = 14;
 const LEASH_SCHEMA_VERSION = 4;
 function assertSchemaVersion(database, table, expected) {
     const row = database.prepare(`SELECT version FROM ${table} WHERE singleton = 1`).get();
@@ -19,24 +19,16 @@ export const HEART_SCHEMA = `
   INSERT OR IGNORE INTO akuma_schema(singleton, version) VALUES (1, ${HEART_SCHEMA_VERSION});
   CREATE TABLE IF NOT EXISTS soul (
     singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
-    id TEXT NOT NULL UNIQUE,
-    archetype TEXT NOT NULL,
-    description TEXT,
-    provider_json TEXT NOT NULL CHECK (json_valid(provider_json)),
-    options_json TEXT NOT NULL CHECK (json_valid(options_json)),
-    cwd TEXT NOT NULL,
-    origin_json TEXT NOT NULL CHECK (json_valid(origin_json)),
-    confinement_json TEXT NOT NULL CHECK (json_valid(confinement_json)),
-    created_at TEXT NOT NULL
+    soul_json TEXT NOT NULL CHECK (json_valid(soul_json))
   ) STRICT;
   CREATE TABLE IF NOT EXISTS bodies (
     sequence INTEGER PRIMARY KEY AUTOINCREMENT,
-    pid INTEGER NOT NULL CHECK (pid > 0),
-    process_group INTEGER NOT NULL CHECK (process_group > 0),
-    spawned_at TEXT NOT NULL,
     leash_taken_at TEXT NOT NULL,
+    hung_diagnostic TEXT,
+    hung_at TEXT,
     end TEXT CHECK (end IN ('exited', 'broke-off', 'put-down')),
-    ended_at TEXT
+    ended_at TEXT,
+    CHECK ((hung_diagnostic IS NULL AND hung_at IS NULL) OR (hung_diagnostic IS NOT NULL AND hung_at IS NOT NULL AND end IS NULL))
   ) STRICT;
   CREATE TABLE IF NOT EXISTS sessions (
     sequence INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -47,31 +39,72 @@ export const HEART_SCHEMA = `
     admitted_at TEXT NOT NULL
   ) STRICT;
   CREATE TABLE IF NOT EXISTS turns (
-    sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+    sequence INTEGER PRIMARY KEY REFERENCES timeline(sequence) ON DELETE CASCADE,
     body_sequence INTEGER NOT NULL REFERENCES bodies(sequence),
-    outcome TEXT NOT NULL CHECK (outcome IN ('answered', 'failed')),
+    started_at TEXT NOT NULL,
+    end_sequence INTEGER UNIQUE REFERENCES timeline(sequence) ON DELETE SET NULL,
+    outcome TEXT CHECK (outcome IN ('answered', 'failed')),
     history_id TEXT UNIQUE,
     session_json TEXT CHECK (session_json IS NULL OR json_valid(session_json)),
     answer TEXT,
     diagnostic TEXT,
-    completed_at TEXT NOT NULL,
+    completed_at TEXT,
     CHECK (
-      (outcome = 'answered' AND history_id IS NOT NULL AND session_json IS NOT NULL AND answer IS NOT NULL AND diagnostic IS NULL)
+      (outcome = 'answered' AND session_json IS NOT NULL AND answer IS NOT NULL AND diagnostic IS NULL)
       OR (outcome = 'failed' AND history_id IS NULL AND session_json IS NULL AND answer IS NULL AND diagnostic IS NOT NULL)
+      OR (outcome IS NULL AND end_sequence IS NULL AND history_id IS NULL AND session_json IS NULL AND answer IS NULL AND diagnostic IS NULL AND completed_at IS NULL)
     )
   ) STRICT;
-  CREATE TABLE IF NOT EXISTS activity (
+  CREATE TABLE IF NOT EXISTS timeline (
     sequence INTEGER PRIMARY KEY AUTOINCREMENT,
-    body_sequence INTEGER NOT NULL REFERENCES bodies(sequence),
+    kind TEXT NOT NULL CHECK (kind IN ('turn-start', 'call', 'activity', 'tell', 'turn-end'))
+  ) STRICT;
+  CREATE TABLE IF NOT EXISTS calls (
+    sequence INTEGER PRIMARY KEY REFERENCES timeline(sequence) ON DELETE CASCADE,
+    turn_sequence INTEGER NOT NULL REFERENCES turns(sequence) ON DELETE CASCADE,
+    body TEXT NOT NULL,
+    at TEXT NOT NULL
+  ) STRICT;
+  CREATE TABLE IF NOT EXISTS activity (
+    sequence INTEGER PRIMARY KEY REFERENCES timeline(sequence) ON DELETE CASCADE,
+    turn_sequence INTEGER NOT NULL REFERENCES turns(sequence) ON DELETE CASCADE,
     event_json TEXT NOT NULL CHECK (json_valid(event_json)),
     at TEXT NOT NULL
   ) STRICT;
   CREATE TABLE IF NOT EXISTS tells (
     id TEXT PRIMARY KEY,
+    sequence INTEGER NOT NULL UNIQUE REFERENCES timeline(sequence) ON DELETE CASCADE,
     body TEXT NOT NULL,
-    state TEXT NOT NULL CHECK (state IN ('recorded', 'delivered', 'seen', 'consumed', 'voided-by-death')),
     recorded_at TEXT NOT NULL
   ) STRICT;
+  CREATE TABLE IF NOT EXISTS tell_deliveries (
+    sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+    tell_id TEXT NOT NULL REFERENCES tells(id) ON DELETE CASCADE,
+    route TEXT NOT NULL CHECK (route IN ('launch', 'live')),
+    turn_sequence INTEGER NOT NULL REFERENCES turns(sequence) ON DELETE CASCADE,
+    fence TEXT NOT NULL,
+    receipt TEXT CHECK (receipt IN ('unavailable', 'required')),
+    delivered_at TEXT NOT NULL,
+    CHECK ((route = 'launch' AND receipt IS NULL) OR (route = 'live' AND receipt IS NOT NULL)),
+    UNIQUE (tell_id, turn_sequence, fence)
+  ) STRICT;
+  CREATE TABLE IF NOT EXISTS tell_receipts (
+    sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+    evidence TEXT NOT NULL CHECK (evidence IN ('exact', 'fence')),
+    tell_id TEXT REFERENCES tells(id) ON DELETE CASCADE,
+    turn_sequence INTEGER REFERENCES turns(sequence) ON DELETE CASCADE,
+    fence TEXT,
+    kind TEXT NOT NULL,
+    received_at TEXT NOT NULL,
+    CHECK (
+      (evidence = 'exact' AND tell_id IS NOT NULL AND turn_sequence IS NULL AND fence IS NULL)
+      OR (evidence = 'fence' AND tell_id IS NULL AND turn_sequence IS NOT NULL AND fence IS NOT NULL)
+    )
+  ) STRICT;
+  CREATE UNIQUE INDEX IF NOT EXISTS tell_receipts_exact
+    ON tell_receipts(tell_id, kind) WHERE evidence = 'exact';
+  CREATE UNIQUE INDEX IF NOT EXISTS tell_receipts_fence
+    ON tell_receipts(turn_sequence, fence, kind) WHERE evidence = 'fence';
   CREATE TABLE IF NOT EXISTS requests (
     sequence INTEGER PRIMARY KEY AUTOINCREMENT,
     id TEXT NOT NULL UNIQUE,
@@ -93,10 +126,16 @@ export const HEART_SCHEMA = `
     )
   ) STRICT;
   CREATE TABLE IF NOT EXISTS control (
-    kind TEXT PRIMARY KEY CHECK (kind IN ('stop', 'pause', 'death')),
+    kind TEXT PRIMARY KEY CHECK (kind IN ('stop', 'pause')),
     value_json TEXT NOT NULL CHECK (json_valid(value_json)),
     at TEXT NOT NULL
   ) STRICT;
+  CREATE TABLE IF NOT EXISTS kills (
+    sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+    body_sequence INTEGER NOT NULL UNIQUE REFERENCES bodies(sequence),
+    evidence TEXT NOT NULL CHECK (evidence = 'killed'),
+    at TEXT NOT NULL
+  ) STRICT;
 `;
 export const LEASH_SCHEMA = `
   PRAGMA journal_mode=DELETE;

package/build/src/akuma/heart/soul.d.ts

@@ -0,0 +1,8 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { Soul, SoulRow } from "./facts.js";
+export declare function decodeSoul(value: unknown): Soul;
+export declare function encodeSoul(soul: Soul): string;
+export declare function encodeSoulRow(soul: Soul): readonly [string];
+export declare function decodeSoulRow(row: SoulRow): Soul;
+export declare function soulFact(database: DatabaseSync): Soul | null;
+export declare function insertSoulFact(database: DatabaseSync, soul: Soul): void;

package/build/src/akuma/heart/soul.js

@@ -0,0 +1,136 @@
+import { parseAkuId } from "../identity.js";
+import { decodeProviderOptions, decodeProviderRecipe, decodeReadonlyRestraint, } from "../provider-recipe.js";
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function unknownKey(value, allowed) {
+    return Object.keys(value).find((key) => !allowed.includes(key));
+}
+function nonblank(value, what) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`Akuma soul ${what} must be a nonblank string`);
+    }
+    return value;
+}
+function soulAkuIdentity(value, what) {
+    try {
+        return parseAkuId(nonblank(value, what));
+    }
+    catch (error) {
+        throw new Error(`Akuma soul ${what} is not an Akuma identity coordinate`, { cause: error });
+    }
+}
+function decodeOrigin(value) {
+    const origin = record(value);
+    if (origin === null)
+        throw new Error("Akuma soul origin must be an object");
+    if (origin.kind === "direct") {
+        if (unknownKey(origin, ["kind"]) !== undefined)
+            throw new Error("Akuma soul direct origin must have only kind");
+        return { kind: "direct" };
+    }
+    if (origin.kind === "request") {
+        if (unknownKey(origin, ["kind", "parent", "requestId"]) !== undefined) {
+            throw new Error("Akuma soul request origin must have only kind, parent, and requestId");
+        }
+        return {
+            kind: "request",
+            parent: soulAkuIdentity(origin.parent, "request parent").id,
+            requestId: nonblank(origin.requestId, "request requestId"),
+        };
+    }
+    if (origin.kind === "fork") {
+        if (unknownKey(origin, ["at", "kind", "parent"]) !== undefined) {
+            throw new Error("Akuma soul fork origin must have only kind, parent, and at");
+        }
+        return {
+            kind: "fork",
+            parent: soulAkuIdentity(origin.parent, "fork parent").id,
+            at: nonblank(origin.at, "fork at"),
+        };
+    }
+    throw new Error("Akuma soul origin must be direct, request, or fork");
+}
+function decodeConfinement(value) {
+    const confinement = record(value);
+    if (confinement === null)
+        throw new Error("Akuma soul confinement must be an object");
+    if (confinement.kind === "unconfined") {
+        if (unknownKey(confinement, ["kind"]) !== undefined)
+            throw new Error("Akuma soul unconfined confinement must have only kind");
+        return { kind: "unconfined" };
+    }
+    if (confinement.kind === "declared") {
+        if (unknownKey(confinement, ["kind", "writableRoots"]) !== undefined) {
+            throw new Error("Akuma soul declared confinement must have only kind and writableRoots");
+        }
+        if (!Array.isArray(confinement.writableRoots)
+            || confinement.writableRoots.some((root) => typeof root !== "string" || root.trim().length === 0)) {
+            throw new Error("Akuma soul declared confinement writableRoots must be nonblank strings");
+        }
+        return { kind: "declared", writableRoots: [...confinement.writableRoots] };
+    }
+    throw new Error("Akuma soul confinement must be unconfined or declared");
+}
+function validateSoul(value) {
+    const soul = record(value);
+    if (soul === null)
+        throw new Error("Akuma soul must be an object");
+    if (unknownKey(soul, ["archetype", "confinement", "createdAt", "cwd", "description", "id", "options", "origin", "provider", "readonly"]) !== undefined) {
+        throw new Error("Akuma soul has an unknown field");
+    }
+    const identity = soulAkuIdentity(soul.id, "id");
+    const id = identity.id;
+    const archetype = nonblank(soul.archetype, "name");
+    if (identity.archetype !== archetype)
+        throw new Error("Akuma soul id and name must agree");
+    const description = soul.description === undefined ? undefined : nonblank(soul.description, "description");
+    const provider = decodeProviderRecipe(soul.provider);
+    const options = decodeProviderOptions(soul.options);
+    const restraint = soul.readonly === undefined ? undefined : decodeReadonlyRestraint(soul.readonly);
+    if ((options.readonly === true) !== (restraint !== undefined)) {
+        throw new Error("Akuma soul readonly option and restraint must agree");
+    }
+    return {
+        id,
+        archetype,
+        ...(description === undefined ? {} : { description }),
+        provider,
+        options,
+        ...(restraint === undefined ? {} : { readonly: restraint }),
+        cwd: nonblank(soul.cwd, "cwd"),
+        origin: decodeOrigin(soul.origin),
+        confinement: decodeConfinement(soul.confinement),
+        createdAt: nonblank(soul.createdAt, "createdAt"),
+    };
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === "object") {
+        for (const key of Object.keys(value)) {
+            deepFreeze(value[key]);
+        }
+        Object.freeze(value);
+    }
+    return value;
+}
+export function decodeSoul(value) {
+    return deepFreeze(validateSoul(value));
+}
+export function encodeSoul(soul) {
+    return JSON.stringify(validateSoul(soul));
+}
+export function encodeSoulRow(soul) {
+    return [encodeSoul(soul)];
+}
+export function decodeSoulRow(row) {
+    return decodeSoul(JSON.parse(row.soul_json));
+}
+export function soulFact(database) {
+    const row = database.prepare("SELECT soul_json FROM soul WHERE singleton = 1").get();
+    return row === undefined ? null : decodeSoulRow(row);
+}
+export function insertSoulFact(database, soul) {
+    database.prepare("INSERT INTO soul(singleton, soul_json) VALUES (1, ?)").run(...encodeSoulRow(soul));
+}

package/build/src/akuma/heart/storage.d.ts

@@ -0,0 +1,47 @@
+import { DatabaseSync } from "node:sqlite";
+import type { AkumaPaths } from "../identity.js";
+import type { BodyFact, LeashProbe, SessionFact, Soul, StopFact, TellFact } from "./facts.js";
+import { sealFact } from "./rows.js";
+export declare class HeartAbsentError extends Error {
+    readonly path: string;
+    constructor(path: string, options?: ErrorOptions);
+}
+export declare function isHeartAbsent(error: unknown): error is HeartAbsentError;
+export declare function withHeart<T>(paths: AkumaPaths, body: (database: DatabaseSync) => T): Promise<T>;
+export declare function transaction<T>(database: DatabaseSync, body: () => T): T;
+export declare function initializeHeart(paths: AkumaPaths): Promise<void>;
+export declare class HeldAkumaLeash {
+    private readonly database;
+    private closed;
+    private bodySequence;
+    private constructor();
+    static try(paths: AkumaPaths): Promise<HeldAkumaLeash | null>;
+    birth(paths: AkumaPaths, soul: Soul, session?: Omit<SessionFact, "sequence">): Promise<"born" | "already-born" | "sealed">;
+    sealIfUnborn(paths: AkumaPaths, input: Readonly<{
+        evidence: string;
+        at: string;
+    }>): Promise<"born" | "sealed">;
+    clearPause(paths: AkumaPaths): Promise<void>;
+    clearStop(paths: AkumaPaths): Promise<void>;
+    recordBody(paths: AkumaPaths, input: Readonly<{
+        leashTakenAt: string;
+    }>): Promise<BodyFact>;
+    recordBodyHung(paths: AkumaPaths, input: Readonly<{
+        sequence: number;
+        diagnostic: string;
+        at: string;
+    }>): Promise<void>;
+    settleStop(paths: AkumaPaths, expectedBodySequence?: number): Promise<Readonly<{
+        target: StopFact;
+        result: "recorded" | "already-killed";
+    }> | null>;
+    recordInterruptTell(paths: AkumaPaths, tell: Omit<TellFact, "sequence" | "state" | "deliveries">): Promise<Readonly<{
+        kind: "not-born";
+    } | {
+        kind: "recorded";
+        tell: TellFact;
+    }>>;
+    release(): void;
+}
+export declare function probeLeash(paths: AkumaPaths): Promise<LeashProbe>;
+export declare function readSealFromLeash(paths: AkumaPaths): Promise<ReturnType<typeof sealFact>>;

package/build/src/akuma/heart/storage.js

@@ -0,0 +1,224 @@
+import { DatabaseSync } from "node:sqlite";
+import { lstat } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { HEART_SCHEMA, LEASH_SCHEMA, assertHeartSchemaVersion, assertLeashSchemaVersion } from "./schema.js";
+import { deletePauseControl, deleteStopControl, insertBodyFact, insertKillFact, insertSealFact, insertSessionFact, killFactForBody, latestBodyFact, latestKillFact, markBodyHung, sealExists, sealFact, stopFact, } from "./rows.js";
+import { insertTellFact } from "./tells.js";
+import { pruneActivityFacts } from "./timeline.js";
+import { insertSoulFact, soulFact } from "./soul.js";
+const ACTIVITY_LIMIT = 5_000;
+const SQLITE_CANTOPEN = 14;
+export class HeartAbsentError extends Error {
+    path;
+    constructor(path, options) {
+        super(`Akuma Heart database is absent: ${path}`, options);
+        this.path = path;
+        this.name = "HeartAbsentError";
+    }
+}
+export function isHeartAbsent(error) {
+    return error instanceof HeartAbsentError;
+}
+function isBusy(error) {
+    const value = error;
+    const message = String(value?.message ?? "").toLowerCase();
+    return value?.code === "ERR_SQLITE_BUSY" || value?.code === "ERR_SQLITE_LOCKED"
+        || value?.errcode === 5 || message.includes("database is locked") || message.includes("database is busy");
+}
+async function openExistingDatabase(path, timeout) {
+    const uri = pathToFileURL(path);
+    uri.searchParams.set("mode", "rw");
+    try {
+        return timeout === undefined
+            ? new DatabaseSync(uri.href)
+            : new DatabaseSync(uri.href, { timeout });
+    }
+    catch (error) {
+        if (error.errcode === SQLITE_CANTOPEN) {
+            try {
+                await lstat(path);
+            }
+            catch (metadataError) {
+                if (metadataError.code === "ENOENT") {
+                    throw new HeartAbsentError(path, { cause: error });
+                }
+            }
+        }
+        throw error;
+    }
+}
+async function openHeart(path, verify = true) {
+    const database = await openExistingDatabase(path);
+    try {
+        database.exec("PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL");
+        if (verify)
+            assertHeartSchemaVersion(database);
+        return database;
+    }
+    catch (error) {
+        database.close();
+        throw error;
+    }
+}
+export async function withHeart(paths, body) {
+    const database = await openHeart(paths.heart);
+    try {
+        return body(database);
+    }
+    finally {
+        database.close();
+    }
+}
+export function transaction(database, body) {
+    database.exec("BEGIN IMMEDIATE");
+    try {
+        const result = body();
+        database.exec("COMMIT");
+        return result;
+    }
+    catch (error) {
+        try {
+            database.exec("ROLLBACK");
+        }
+        catch { /* preserve the adjudication failure */ }
+        throw error;
+    }
+}
+export async function initializeHeart(paths) {
+    const heart = new DatabaseSync(paths.heart);
+    try {
+        heart.exec(HEART_SCHEMA);
+        assertHeartSchemaVersion(heart);
+    }
+    finally {
+        heart.close();
+    }
+    const leash = new DatabaseSync(paths.leash);
+    try {
+        leash.exec(LEASH_SCHEMA);
+        assertLeashSchemaVersion(leash);
+    }
+    finally {
+        leash.close();
+    }
+}
+export class HeldAkumaLeash {
+    database;
+    closed = false;
+    bodySequence;
+    constructor(database) {
+        this.database = database;
+    }
+    static async try(paths) {
+        const database = await openExistingDatabase(paths.leash, 0);
+        try {
+            assertLeashSchemaVersion(database);
+            database.exec("PRAGMA busy_timeout=0; BEGIN EXCLUSIVE");
+            return new HeldAkumaLeash(database);
+        }
+        catch (error) {
+            database.close();
+            if (isBusy(error))
+                return null;
+            throw error;
+        }
+    }
+    async birth(paths, soul, session) {
+        if (sealExists(this.database))
+            return "sealed";
+        return await withHeart(paths, (heart) => transaction(heart, () => {
+            if (soulFact(heart) !== null)
+                return "already-born";
+            insertSoulFact(heart, soul);
+            if (session !== undefined)
+                insertSessionFact(heart, session);
+            return "born";
+        }));
+    }
+    async sealIfUnborn(paths, input) {
+        if (await withHeart(paths, (heart) => soulFact(heart)) !== null)
+            return "born";
+        insertSealFact(this.database, input);
+        this.database.exec("COMMIT");
+        this.closed = true;
+        this.database.close();
+        return "sealed";
+    }
+    async clearPause(paths) { await withHeart(paths, deletePauseControl); }
+    async clearStop(paths) { await withHeart(paths, deleteStopControl); }
+    async recordBody(paths, input) {
+        if (this.closed || this.bodySequence !== undefined)
+            throw new Error("Akuma leash cannot start another Body");
+        const sequence = await withHeart(paths, (heart) => insertBodyFact(heart, input));
+        this.bodySequence = sequence;
+        return { sequence, leashTakenAt: input.leashTakenAt };
+    }
+    async recordBodyHung(paths, input) {
+        if (this.closed || this.bodySequence !== input.sequence) {
+            throw new Error(`Akuma Body ${input.sequence} is not owned by this leash`);
+        }
+        await withHeart(paths, (heart) => markBodyHung(heart, input));
+    }
+    async settleStop(paths, expectedBodySequence) {
+        return await withHeart(paths, (heart) => transaction(heart, () => {
+            const target = stopFact(heart);
+            if (target === null) {
+                if (expectedBodySequence === undefined)
+                    return null;
+                const existing = killFactForBody(heart, expectedBodySequence);
+                return existing === null ? null : { target: { bodySequence: expectedBodySequence, requestedAt: existing.at }, result: "already-killed" };
+            }
+            if (expectedBodySequence !== undefined && target.bodySequence !== expectedBodySequence) {
+                throw new Error("Akuma stop target changed while kill was in progress");
+            }
+            const latest = latestBodyFact(heart);
+            if (latest?.sequence !== target.bodySequence)
+                throw new Error("Akuma stop target is not the latest Body");
+            if (latest.end !== "put-down")
+                return null;
+            const result = latestKillFact(heart)?.bodySequence === target.bodySequence
+                ? "already-killed"
+                : (insertKillFact(heart, target.bodySequence, target.requestedAt), "recorded");
+            deleteStopControl(heart);
+            return { target, result };
+        }));
+    }
+    async recordInterruptTell(paths, tell) {
+        return await withHeart(paths, (heart) => transaction(heart, () => {
+            deletePauseControl(heart);
+            if (soulFact(heart) === null)
+                return { kind: "not-born" };
+            const sequence = insertTellFact(heart, tell);
+            pruneActivityFacts(heart, ACTIVITY_LIMIT);
+            return { kind: "recorded", tell: { sequence, ...tell, state: "pending", deliveries: [] } };
+        }));
+    }
+    release() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            this.database.exec("ROLLBACK");
+        }
+        finally {
+            this.database.close();
+        }
+    }
+}
+export async function probeLeash(paths) {
+    const claim = await HeldAkumaLeash.try(paths);
+    if (claim === null)
+        return "held";
+    claim.release();
+    return "free";
+}
+export async function readSealFromLeash(paths) {
+    const leash = await openExistingDatabase(paths.leash);
+    try {
+        assertLeashSchemaVersion(leash);
+        return sealFact(leash);
+    }
+    finally {
+        leash.close();
+    }
+}

package/build/src/akuma/heart/tells.d.ts

@@ -0,0 +1,12 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { TellDeliveryInput, TellFact, TellReceiptInput } from "./facts.js";
+export declare const tellStateSql = "CASE\n  WHEN EXISTS (\n    SELECT 1 FROM tell_deliveries d\n    WHERE d.tell_id = tells.id AND (d.route = 'launch' OR d.receipt = 'unavailable')\n  ) THEN 'told'\n  WHEN EXISTS (SELECT 1 FROM tell_receipts r WHERE r.evidence = 'exact' AND r.tell_id = tells.id) THEN 'told'\n  WHEN EXISTS (\n    SELECT 1 FROM tell_receipts r\n    JOIN tell_deliveries d ON d.turn_sequence = r.turn_sequence AND d.fence = r.fence\n    WHERE r.evidence = 'fence' AND d.tell_id = tells.id\n  ) THEN 'told'\n  ELSE 'pending'\nEND";
+export declare const pendingTellSequencesSql = "SELECT tells.sequence FROM tells WHERE CASE\n  WHEN EXISTS (\n    SELECT 1 FROM tell_deliveries d\n    WHERE d.tell_id = tells.id AND (d.route = 'launch' OR d.receipt = 'unavailable')\n  ) THEN 'told'\n  WHEN EXISTS (SELECT 1 FROM tell_receipts r WHERE r.evidence = 'exact' AND r.tell_id = tells.id) THEN 'told'\n  WHEN EXISTS (\n    SELECT 1 FROM tell_receipts r\n    JOIN tell_deliveries d ON d.turn_sequence = r.turn_sequence AND d.fence = r.fence\n    WHERE r.evidence = 'fence' AND d.tell_id = tells.id\n  ) THEN 'told'\n  ELSE 'pending'\nEND = 'pending'";
+export declare const pendingTellProtectionSql = "SELECT d.turn_sequence FROM tell_deliveries d\n  JOIN tells ON tells.id = d.tell_id WHERE CASE\n  WHEN EXISTS (\n    SELECT 1 FROM tell_deliveries d\n    WHERE d.tell_id = tells.id AND (d.route = 'launch' OR d.receipt = 'unavailable')\n  ) THEN 'told'\n  WHEN EXISTS (SELECT 1 FROM tell_receipts r WHERE r.evidence = 'exact' AND r.tell_id = tells.id) THEN 'told'\n  WHEN EXISTS (\n    SELECT 1 FROM tell_receipts r\n    JOIN tell_deliveries d ON d.turn_sequence = r.turn_sequence AND d.fence = r.fence\n    WHERE r.evidence = 'fence' AND d.tell_id = tells.id\n  ) THEN 'told'\n  ELSE 'pending'\nEND = 'pending'";
+export declare function decodeTellAtSequence(database: DatabaseSync, sequence: number): TellFact;
+export declare function insertTellFact(database: DatabaseSync, tell: Omit<TellFact, "sequence" | "state" | "deliveries">): number;
+export declare function tellFact(database: DatabaseSync, id: string): TellFact | null;
+export declare function insertTellDeliveryFact(database: DatabaseSync, input: TellDeliveryInput): void;
+export declare function insertTellReceiptFact(database: DatabaseSync, input: TellReceiptInput): void;
+export declare function tellIdsForFence(database: DatabaseSync, turnSequence: number, fence: string): readonly string[];
+export declare function pendingTellFacts(database: DatabaseSync): readonly TellFact[];

package/build/src/akuma/heart/tells.js

@@ -0,0 +1,79 @@
+export const tellStateSql = `CASE
+  WHEN EXISTS (
+    SELECT 1 FROM tell_deliveries d
+    WHERE d.tell_id = tells.id AND (d.route = 'launch' OR d.receipt = 'unavailable')
+  ) THEN 'told'
+  WHEN EXISTS (SELECT 1 FROM tell_receipts r WHERE r.evidence = 'exact' AND r.tell_id = tells.id) THEN 'told'
+  WHEN EXISTS (
+    SELECT 1 FROM tell_receipts r
+    JOIN tell_deliveries d ON d.turn_sequence = r.turn_sequence AND d.fence = r.fence
+    WHERE r.evidence = 'fence' AND d.tell_id = tells.id
+  ) THEN 'told'
+  ELSE 'pending'
+END`;
+export const pendingTellSequencesSql = `SELECT tells.sequence FROM tells WHERE ${tellStateSql} = 'pending'`;
+export const pendingTellProtectionSql = `SELECT d.turn_sequence FROM tell_deliveries d
+  JOIN tells ON tells.id = d.tell_id WHERE ${tellStateSql} = 'pending'`;
+function tellDeliveries(database, id) {
+    const rows = database.prepare(`SELECT turn_sequence, route, receipt, delivered_at FROM tell_deliveries
+    WHERE tell_id = ? ORDER BY sequence`).all(id);
+    return rows.map((row) => row.receipt == null
+        ? { turnSequence: row.turn_sequence, route: row.route, deliveredAt: row.delivered_at }
+        : { turnSequence: row.turn_sequence, route: row.route, receipt: row.receipt, deliveredAt: row.delivered_at });
+}
+function decodeTellRow(database, row) {
+    return {
+        kind: "tell",
+        sequence: row.sequence,
+        id: row.id,
+        body: row.body,
+        state: row.state,
+        recordedAt: row.recorded_at,
+        deliveries: tellDeliveries(database, row.id),
+    };
+}
+export function decodeTellAtSequence(database, sequence) {
+    const row = database.prepare(`SELECT sequence, id, body, recorded_at, ${tellStateSql} AS state
+    FROM tells WHERE sequence = ?`).get(sequence);
+    if (row === undefined)
+        throw new Error(`Akuma timeline references missing tell ${sequence}`);
+    return decodeTellRow(database, row);
+}
+export function insertTellFact(database, tell) {
+    const sequence = Number(database.prepare("INSERT INTO timeline(kind) VALUES ('tell')").run().lastInsertRowid);
+    database.prepare("INSERT INTO tells(id, sequence, body, recorded_at) VALUES (?, ?, ?, ?)")
+        .run(tell.id, sequence, tell.body, tell.recordedAt);
+    return sequence;
+}
+export function tellFact(database, id) {
+    const row = database.prepare(`SELECT sequence, id, body, recorded_at, ${tellStateSql} AS state
+    FROM tells WHERE id = ?`).get(id);
+    return row === undefined ? null : decodeTellRow(database, row);
+}
+export function insertTellDeliveryFact(database, input) {
+    const result = database.prepare(`INSERT OR IGNORE INTO tell_deliveries(
+    tell_id, route, turn_sequence, fence, receipt, delivered_at
+  ) VALUES (?, ?, ?, ?, ?, ?)`).run(input.tellId, input.route, input.turnSequence, input.fence, input.route === "live" ? input.receipt : null, input.deliveredAt);
+    const row = database.prepare(`SELECT route, receipt FROM tell_deliveries
+    WHERE tell_id = ? AND turn_sequence = ? AND fence = ?`)
+        .get(input.tellId, input.turnSequence, input.fence);
+    if (row === undefined || (result.changes === 0
+        && (row.route !== input.route || row.receipt !== (input.route === "live" ? input.receipt : null)))) {
+        throw new Error(`tell delivery ${input.tellId} has conflicting evidence`);
+    }
+}
+export function insertTellReceiptFact(database, input) {
+    database.prepare(`INSERT OR IGNORE INTO tell_receipts(
+    evidence, tell_id, turn_sequence, fence, kind, received_at
+  ) VALUES (?, ?, ?, ?, ?, ?)`).run(input.evidence, input.evidence === "exact" ? input.tellId : null, input.evidence === "fence" ? input.turnSequence : null, input.evidence === "fence" ? input.fence : null, input.kind, input.receivedAt);
+}
+export function tellIdsForFence(database, turnSequence, fence) {
+    return database.prepare(`SELECT tell_id FROM tell_deliveries
+    WHERE turn_sequence = ? AND fence = ? ORDER BY sequence`)
+        .all(turnSequence, fence).map((row) => row.tell_id);
+}
+export function pendingTellFacts(database) {
+    const rows = database.prepare(`SELECT sequence, id, body, recorded_at, ${tellStateSql} AS state FROM tells
+    WHERE ${tellStateSql} = 'pending' ORDER BY sequence`).all();
+    return rows.map((row) => decodeTellRow(database, row));
+}

package/build/src/akuma/heart/timeline.d.ts

@@ -0,0 +1,15 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { CallFact, TellFact, TurnEndFact, TurnStartFact } from "./facts.js";
+import { type ActivityFact } from "./rows.js";
+export type TimelineFact = TurnStartFact | CallFact | ActivityFact | TellFact | TurnEndFact;
+export type ActivityFactSlice = Readonly<{
+    rows: readonly TimelineFact[];
+    lowestRetained: number | null;
+    highest: number | null;
+}>;
+export declare function pruneActivityFacts(database: DatabaseSync, limit: number): void;
+export declare function activityFactSlice(database: DatabaseSync, input: Readonly<{
+    before?: number;
+    since?: number;
+    limit: number;
+}>): ActivityFactSlice;