@astrosheep/keiyaku 4.0.1 → 4.0.3

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

@@ -1,24 +1,67 @@
 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, insertKillFact, insertSealFact, insertSessionFact, insertSoulFact, killFactForBody, latestBodyFact, latestKillFact, sealExists, sealFact, soulFact, stopFact, } from "./rows.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");
 }
-export function openHeart(path, verify = true) {
-    const database = new DatabaseSync(path);
-    database.exec("PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL");
-    if (verify)
-        assertHeartSchemaVersion(database);
-    return database;
+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 function withHeart(paths, body) {
-    const database = openHeart(paths.heart);
+export async function withHeart(paths, body) {
+    const database = await openHeart(paths.heart);
     try {
         return body(database);
     }
@@ -41,8 +84,8 @@ export function transaction(database, body) {
         throw error;
     }
 }
-export function initializeHeart(paths) {
-    const heart = openHeart(paths.heart, false);
+export async function initializeHeart(paths) {
+    const heart = new DatabaseSync(paths.heart);
     try {
         heart.exec(HEART_SCHEMA);
         assertHeartSchemaVersion(heart);
@@ -62,11 +105,12 @@ export function initializeHeart(paths) {
 export class HeldAkumaLeash {
     database;
     closed = false;
+    bodySequence;
     constructor(database) {
         this.database = database;
     }
-    static try(paths) {
-        const database = new DatabaseSync(paths.leash, { timeout: 0 });
+    static async try(paths) {
+        const database = await openExistingDatabase(paths.leash, 0);
         try {
             assertLeashSchemaVersion(database);
             database.exec("PRAGMA busy_timeout=0; BEGIN EXCLUSIVE");
@@ -79,10 +123,10 @@ export class HeldAkumaLeash {
             throw error;
         }
     }
-    birth(paths, soul, session) {
+    async birth(paths, soul, session) {
         if (sealExists(this.database))
             return "sealed";
-        return withHeart(paths, (heart) => transaction(heart, () => {
+        return await withHeart(paths, (heart) => transaction(heart, () => {
             if (soulFact(heart) !== null)
                 return "already-born";
             insertSoulFact(heart, soul);
@@ -91,8 +135,10 @@ export class HeldAkumaLeash {
             return "born";
         }));
     }
-    sealIfUnborn(paths, input) {
-        if (withHeart(paths, (heart) => soulFact(heart)) !== null)
+    async sealIfUnborn(paths, input) {
+        if (sealExists(this.database))
+            return "sealed";
+        if (await withHeart(paths, (heart) => soulFact(heart)) !== null)
             return "born";
         insertSealFact(this.database, input);
         this.database.exec("COMMIT");
@@ -100,9 +146,26 @@ export class HeldAkumaLeash {
         this.database.close();
         return "sealed";
     }
-    clearPause(paths) { withHeart(paths, deletePauseControl); }
-    settleStop(paths, expectedBodySequence) {
-        return withHeart(paths, (heart) => transaction(heart, () => {
+    readSeal() {
+        return sealFact(this.database);
+    }
+    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)
@@ -116,6 +179,8 @@ export class HeldAkumaLeash {
             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");
@@ -123,8 +188,8 @@ export class HeldAkumaLeash {
             return { target, result };
         }));
     }
-    recordInterruptTell(paths, tell) {
-        return withHeart(paths, (heart) => transaction(heart, () => {
+    async recordInterruptTell(paths, tell) {
+        return await withHeart(paths, (heart) => transaction(heart, () => {
             deletePauseControl(heart);
             if (soulFact(heart) === null)
                 return { kind: "not-born" };
@@ -145,15 +210,15 @@ export class HeldAkumaLeash {
         }
     }
 }
-export function probeLeash(paths) {
-    const claim = HeldAkumaLeash.try(paths);
+export async function probeLeash(paths) {
+    const claim = await HeldAkumaLeash.try(paths);
     if (claim === null)
         return "held";
     claim.release();
     return "free";
 }
-export function readSealFromLeash(paths) {
-    const leash = new DatabaseSync(paths.leash);
+export async function readSealFromLeash(paths) {
+    const leash = await openExistingDatabase(paths.leash);
     try {
         assertLeashSchemaVersion(leash);
         return sealFact(leash);

package/build/src/akuma/identity.d.ts

@@ -35,12 +35,12 @@ export declare function akuIdFromDirectoryName(name: string): Readonly<{
     archetype: string;
     suffix: string;
 }>;
-export declare function ensureAkumaRunRoot(worldRoot: string): string;
+export declare function ensureAkumaRunRoot(worldRoot: string): Promise<string>;
 export declare function allocateAkumaDirectory(input: Readonly<{
     worldRoot: string;
     archetype: string;
     draw?: () => string;
-}>): AllocatedAkuma;
+}>): Promise<AllocatedAkuma>;
 export declare function pathsForAkuId(worldRoot: string, id: AkuId): AkumaPaths;
 export declare function worldRootForAkumaPaths(paths: AkumaPaths): string;
 export {};

package/build/src/akuma/identity.js

@@ -1,12 +1,12 @@
 import { randomBytes } from "node:crypto";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { identityCoordinate, identitySegments } from "../identity/coordinates.js";
 import { normalizeIdentityStem } from "../identity/normalize.js";
 const HEX8 = /^[0-9a-f]{8}$/u;
 export function archetypeName(value) {
     if (value.length === 0 || normalizeIdentityStem({ source: value }) !== value) {
-        throw new TypeError("Akuma archetype must be one normalized human identity segment");
+        throw new TypeError("Akuma name must be one normalized human identity segment");
     }
     return value;
 }
@@ -24,7 +24,7 @@ export function akuId(input) {
 export function parseAkuId(value) {
     const segments = identitySegments({ family: "aku", value });
     if (segments.length !== 2)
-        throw new TypeError("Akuma identity must be aku/<archetype>/<hex8>");
+        throw new TypeError("Akuma identity must be aku/<akuma>/<hex8>");
     const archetype = archetypeName(segments[0]);
     const suffix = suffixSegment(segments[1]);
     return { id: akuId({ archetype, suffix }), archetype, suffix };
@@ -48,11 +48,11 @@ export function akuIdFromDirectoryName(name) {
     const suffix = name.slice(-8);
     return { id: akuId({ archetype, suffix }), archetype, suffix };
 }
-export function ensureAkumaRunRoot(worldRoot) {
+export async function ensureAkumaRunRoot(worldRoot) {
     const runRoot = akumaRunRoot(worldRoot);
-    mkdirSync(runRoot, { recursive: true });
+    await mkdir(runRoot, { recursive: true });
     try {
-        writeFileSync(join(runRoot, ".gitignore"), "*\n", { flag: "wx" });
+        await writeFile(join(runRoot, ".gitignore"), "*\n", { flag: "wx" });
     }
     catch (error) {
         if (error.code !== "EEXIST")
@@ -60,14 +60,14 @@ export function ensureAkumaRunRoot(worldRoot) {
     }
     return runRoot;
 }
-export function allocateAkumaDirectory(input) {
+export async function allocateAkumaDirectory(input) {
     const archetype = archetypeName(input.archetype);
-    const runRoot = ensureAkumaRunRoot(input.worldRoot);
+    const runRoot = await ensureAkumaRunRoot(input.worldRoot);
     for (;;) {
         const suffix = suffixSegment(input.draw?.() ?? randomBytes(4).toString("hex"));
         const paths = akumaPaths({ runRoot, archetype, suffix });
         try {
-            mkdirSync(paths.directory);
+            await mkdir(paths.directory);
             return { id: akuId({ archetype, suffix }), archetype, suffix, paths };
         }
         catch (error) {

package/build/src/akuma/index.d.ts

@@ -1,9 +1,14 @@
+import { type AkuId } from "./identity.js";
+import type { WorldRoot } from "../world.js";
 export { Akuma, AkumaHandle, AkumaNotBornError } from "./akuma.js";
 export type { WorldRoot } from "../world.js";
+export declare function probeBornAkuma(worldPath: WorldRoot, id: AkuId): Promise<boolean>;
 export { AkumaArchetypeError, listArchetypeDefinitions, listArchetypes } from "./archetype.js";
 export type { ArchetypeCatalogRow } from "./archetype.js";
 export { AkumaBodyRequestError } from "./requests.js";
 export type { AkumaList, AkumaListInput, AkumaListRow, AkumaStatus, ActivityHistory, ActivityRow, ActivitySnapshot, ActivitySnapshotEntry, ForkReceipt, InterruptReceipt, TellResult, UnbornAkumaListRow, } from "./akuma.js";
+export type { ActiveToolRow, ClosedTurn, ClosedTurnRow, CompletedToolRow, HistoryCursor, HistoryPage, IdleSnapshotRow, OpenSnapshotRow, OpenTurn, OpenTurnRow, OutcomeRow, RetainedWindow, Snapshot, SnapshotRow, TellRow, TurnLedger, TurnOutcome, TurnStartRow, UnsettledToolRow, } from "./akuma.js";
 export type { AgentEvent, ToolCall, ToolEvent, ToolResult } from "./provider.js";
 export type { AkuId } from "./identity.js";
-export type { Confinement, KillEvidence, ProviderOptions, ResumeCoordinate, TurnFact, } from "./heart/index.js";
+export type { Confinement, KillEvidence, ResumeCoordinate, TurnFact, } from "./heart/index.js";
+export type { ProviderOptions, ReadonlyRestraint } from "./provider-recipe.js";

package/build/src/akuma/index.js

@@ -1,3 +1,9 @@
+import { readSoul } from "./heart/index.js";
+import { pathsForAkuId } from "./identity.js";
 export { Akuma, AkumaHandle, AkumaNotBornError } from "./akuma.js";
+export async function probeBornAkuma(worldPath, id) {
+    const soul = await readSoul(pathsForAkuId(worldPath, id));
+    return soul !== null;
+}
 export { AkumaArchetypeError, listArchetypeDefinitions, listArchetypes } from "./archetype.js";
 export { AkumaBodyRequestError } from "./requests.js";

package/build/src/akuma/projection.d.ts

@@ -1,50 +1,46 @@
 import { type ToolCall, type ToolResult } from "./provider.js";
-import type { ActivitySlice, TellDelivery, TellFact, TimelineFact, TurnEndFact } from "./heart/index.js";
-export type ActivityRow = Readonly<{
+import type { TellDelivery, TellFact, TimelineFact, TurnEndFact } from "./heart/index.js";
+export type TurnOutcome = TurnEndFact["outcome"];
+export type TurnStartRow = Readonly<{
     kind: "turn";
     sequence: number;
     turnSequence: number;
     bodySequence: number;
     at: string;
-}> | Readonly<{
+}>;
+type CallRow = Readonly<{
     kind: "call";
     sequence: number;
     turnSequence: number;
     at: string;
     text: string;
-}> | Readonly<{
+}>;
+type SaidRow = Readonly<{
     kind: "said";
     sequence: number;
     turnSequence: number;
     at: string;
     text: string;
     truncated?: true;
-}> | Readonly<{
+}>;
+type ThoughtRow = Readonly<{
     kind: "thought";
     sequence: number;
     turnSequence: number;
     at: string;
     text: string;
     truncated?: true;
-}> | Readonly<{
-    kind: "tool";
-    sequence: number;
-    turnSequence: number;
-    at: string;
-    completedAt?: string;
-    durationMs?: number;
-    name: string;
-    call: ToolCall;
-    state: "running" | ToolResult;
-    truncated?: true;
-}> | Readonly<{
+}>;
+type NoteRow = Readonly<{
     kind: "note";
     sequence: number;
     turnSequence: number;
     at: string;
     text: string;
     truncated?: true;
-}> | Readonly<{
+}>;
+type TurnNarrationRow = CallRow | SaidRow | ThoughtRow | NoteRow;
+export type TellRow = Readonly<{
     kind: "tell";
     sequence: number;
     at: string;
@@ -52,26 +48,88 @@ export type ActivityRow = Readonly<{
     text: string;
     state: TellFact["state"];
     deliveries: readonly TellDelivery[];
-}> | Readonly<{
+}>;
+export type OutcomeRow = Readonly<{
     kind: "outcome";
     sequence: number;
     turnSequence: number;
     at: string;
-    outcome: TurnEndFact["outcome"];
+    outcome: TurnOutcome;
 }>;
-export type ActivitySnapshot = Readonly<{
-    entries: readonly ActivitySnapshotEntry[];
-    lowestRetained: number | null;
-    highest: number | null;
+export type ActiveToolRow = Readonly<{
+    kind: "tool";
+    sequence: number;
+    turnSequence: number;
+    at: string;
+    name: string;
+    call: ToolCall;
+    state: "active";
+    truncated?: true;
 }>;
-export type ActivitySnapshotEntry = Readonly<{
+export type CompletedToolRow = Readonly<{
+    kind: "tool";
+    sequence: number;
+    turnSequence: number;
+    at: string;
+    completedAt?: string;
+    durationMs?: number;
+    name: string;
+    call: ToolCall;
+    state: ToolResult;
+    truncated?: true;
+}>;
+export type UnsettledToolRow = Readonly<{
+    kind: "tool";
+    sequence: number;
+    turnSequence: number;
+    at: string;
+    name: string;
+    call: ToolCall;
+    state: "unsettled";
+    truncated?: true;
+}>;
+export type OpenTurnRow = TurnNarrationRow | ActiveToolRow | CompletedToolRow;
+export type ClosedTurnRow = TurnNarrationRow | UnsettledToolRow | CompletedToolRow;
+export type OpenTurn = Readonly<{
+    kind: "open";
+    turn: TurnStartRow;
+    rows: readonly OpenTurnRow[];
+}>;
+export type ClosedTurn = Readonly<{
+    kind: "closed";
+    turn: TurnStartRow;
+    rows: readonly ClosedTurnRow[];
+    outcome: OutcomeRow;
+}>;
+export type ProjectedTurn = OpenTurn | ClosedTurn;
+export type ActivityRow = TurnStartRow | OpenTurnRow | ClosedTurnRow | TellRow | OutcomeRow;
+type SnapshotFactRow = TurnNarrationRow | TellRow;
+export type OpenSnapshotRow = SnapshotFactRow | ActiveToolRow | CompletedToolRow;
+export type IdleSnapshotRow = SnapshotFactRow | CompletedToolRow;
+export type SnapshotRow = OpenSnapshotRow | IdleSnapshotRow;
+export type ActivitySnapshotEntry<Row extends SnapshotRow = SnapshotRow> = Readonly<{
     kind: "row";
-    row: ActivityRow;
+    row: Row;
 }> | Readonly<{
     kind: "gap";
     count: number;
 }>;
-export type ActivitySnapshotProfile = "status" | "feedback";
+export type Snapshot = Readonly<{
+    kind: "unborn";
+    entries: readonly [];
+    omitted: 0;
+}> | Readonly<{
+    kind: "open";
+    turn: TurnStartRow;
+    entries: readonly ActivitySnapshotEntry<OpenSnapshotRow>[];
+    omitted: number;
+}> | Readonly<{
+    kind: "idle";
+    outcome?: OutcomeRow;
+    entries: readonly ActivitySnapshotEntry<IdleSnapshotRow>[];
+    omitted: number;
+}>;
+export type ActivitySnapshot = Snapshot;
 export type ActivityHistory = Readonly<{
     rows: readonly ActivityRow[];
     omitted: number;
@@ -81,17 +139,38 @@ export type ActivityHistory = Readonly<{
     lowestRetained: number | null;
     highest: number | null;
 }>;
-/** Project the complete retained fact window in persisted timeline order. */
-export declare function projectTimeline(facts: readonly TimelineFact[]): readonly ActivityRow[];
-/** Apply the bounded snapshot policy after semantic projection. */
-export declare function selectActivitySnapshot(facts: readonly TimelineFact[], input?: Readonly<{
-    lowestRetained?: number | null;
-    highest?: number | null;
-    profile?: ActivitySnapshotProfile;
-}>): ActivitySnapshot;
-/** Apply cursor and limit to the one semantic timeline projection. */
-export declare function projectActivityHistory(slice: ActivitySlice, input: Readonly<{
+export type HistoryPage = ActivityHistory;
+export type HistoryCursor = Readonly<{
     before?: number;
     since?: number;
     limit: number;
-}>): ActivityHistory;
+}>;
+export type RetainedWindow = Readonly<{
+    lowestRetained: number | null;
+    highest: number | null;
+}>;
+export type TurnLedger = Readonly<{
+    rows: readonly ActivityRow[];
+    turns: readonly ProjectedTurn[];
+    retained: RetainedWindow;
+    openTurn?: OpenTurn;
+    latestOutcome?: OutcomeRow;
+}>;
+/** Fold the retained fact timeline into Turn-owned rows without inventing provider facts. */
+export declare function projectTurns(facts: readonly TimelineFact[], retained?: RetainedWindow): TurnLedger;
+/** Split one nonnegative ordinary allowance into newest tail first, then pre-tail voice. */
+export declare function ordinarySnapshotBudget(ordinaryBudget: number): Readonly<{
+    tail: number;
+    voice: number;
+}>;
+/** Count selected ordinary rows; active tools and pending tells stay outside this total. */
+export declare function ordinarySelectedCount(snapshot: ActivitySnapshot): number;
+/** Select one current Turn, one latest outcome, or no focus; pending tells stay actionable. */
+export declare function selectSnapshot(ledger: TurnLedger, budget?: Readonly<{
+    tail: number;
+    voice?: number;
+}>): ActivitySnapshot;
+/** Apply the one snapshot policy used by every public observation consumer. */
+export declare function selectActivitySnapshot(facts: readonly TimelineFact[]): ActivitySnapshot;
+export declare function selectHistory(ledger: TurnLedger, cursor: HistoryCursor): HistoryPage;
+export {};