@astrosheep/keiyaku 4.0.0 → 4.0.2

package/build/src/akuma/akuma.js

@@ -1,18 +1,16 @@
 import { randomUUID } from "node:crypto";
-import { readdirSync } from "node:fs";
+import { readdir } from "node:fs/promises";
 import { resolve } from "node:path";
-import { spawnAkumaBody } from "./body.js";
-import { HeldAkumaLeash, activitySlice, life, probeLeash, readCurrentTurn, readHeart, readLastAnsweredTurn, readTurns, readForkPoint, readSeal, readSoul, recordDeath, recordTell, requestPause, requestStop, } from "./heart/index.js";
+import { CONTROL_RESPONSE_MS, spawnAkumaBody } from "./body.js";
+import { HeldAkumaLeash, activitySlice, life, lifeAt, probeLeash, readHeart, readLastAnsweredTurn, readForkPoint, readKill, readSeal, readSoul, recordTell, requestPause, requestStop, } from "./heart/index.js";
 import { akuIdFromDirectoryName, akumaPaths, akumaRunRoot, parseAkuId, pathsForAkuId, archetypeName, } from "./identity.js";
-import { projectActivityHistory, selectActivitySnapshot, } from "./activity.js";
+import { ordinarySelectedCount, ordinarySnapshotBudget, projectTurns, selectActivitySnapshot, selectHistory, selectSnapshot, } from "./projection.js";
 import { listArchetypes as readArchetypes, loadArchetype } from "./archetype.js";
 import { publishAkuma } from "./publication.js";
-import { providerNamed } from "./providers/index.js";
+import { resolveProviderExecution } from "./providers/index.js";
 import { injectedBodyRequests, requestBodyCall } from "./requests.js";
-import { probeProcessTree, putDownProcessTree } from "../runtime/proc/run.js";
 import { settings as readSettings } from "../settings.js";
 const POLL_MS = 25;
-const KILL_GRACE_MS = 1_000;
 export class AkumaNotBornError extends Error {
     id;
     kind = "akuma-not-born";
@@ -27,7 +25,7 @@ function wait(milliseconds) {
 }
 async function takeLeashUntil(paths, deadline) {
     for (;;) {
-        const leash = HeldAkumaLeash.try(paths);
+        const leash = await HeldAkumaLeash.try(paths);
         if (leash !== null)
             return leash;
         if (performance.now() >= deadline)
@@ -35,74 +33,77 @@ async function takeLeashUntil(paths, deadline) {
         await wait(POLL_MS);
     }
 }
-function recordTellBody(paths, body) {
+async function recordTellBody(paths, akuma, body) {
     const id = randomUUID();
-    const admitted = recordTell(paths, { id, body, recordedAt: new Date().toISOString() });
-    return admitted === "dead" ? { kind: "dead" } : { kind: "recorded", id };
+    const admitted = await recordTell(paths, { kind: "tell", id, body, recordedAt: new Date().toISOString() });
+    if (admitted.kind === "not-born")
+        throw new AkumaNotBornError(akuma);
+    return { kind: "recorded", tellId: admitted.tell.id };
 }
-async function wakeTell(paths, akuma, id) {
-    const soul = readSoul(paths);
-    if (soul === null)
-        throw new Error(`Akuma ${akuma} has no soul`);
+async function wakeTell(paths, tellId) {
     try {
         await spawnAkumaBody({ paths });
-        return { id, state: "recorded", wake: "spawned" };
+        return { admission: { tellId, fact: "recorded" }, wake: "spawned" };
     }
     catch (error) {
         return {
-            id,
-            state: "recorded",
+            admission: { tellId, fact: "recorded" },
             wake: { kind: "failed", diagnostic: error instanceof Error ? error.message : String(error) },
         };
     }
 }
-function collarProbe(snapshot) {
-    if (snapshot.latestBody === null)
-        return { kind: "gone", end: null };
-    const probe = probeProcessTree(snapshot.latestBody.collar);
-    if (probe.kind === "gone")
-        return { kind: "gone", end: snapshot.latestBody.end ?? null };
-    return probe;
-}
-function bornListRow(paths, expected, snapshot = readHeart(paths)) {
+async function bornListRow(paths, expected, snapshot) {
+    snapshot ??= await readHeart(paths);
     if (snapshot.soul === null)
         throw new AkumaNotBornError(expected);
     if (snapshot.soul.id !== expected)
         throw new Error("Akuma soul does not match its coordinate");
-    const collar = collarProbe(snapshot);
+    const currentLife = life({
+        leash: await probeLeash(paths),
+        body: snapshot.latestBody,
+        kill: snapshot.latestKill,
+    });
     return {
         id: snapshot.soul.id,
         archetype: snapshot.soul.archetype,
         ...(snapshot.soul.description === undefined ? {} : { description: snapshot.soul.description }),
-        life: life(probeLeash(paths), collar, snapshot.death),
-        collar,
+        life: currentLife,
+        lifeAt: lifeAt(currentLife, snapshot.latestBody, snapshot.latestKill, snapshot.soul.createdAt),
         confinement: snapshot.soul.confinement,
         pending: snapshot.pending.map((tell) => tell.id),
     };
 }
-function bornStatus(paths, expected) {
-    const snapshot = readHeart(paths);
+async function bornStatus(paths, expected, budget) {
+    const snapshot = await readHeart(paths);
     if (snapshot.soul === null)
         throw new AkumaNotBornError(expected);
-    const current = bornListRow(paths, expected, snapshot);
-    const latest = readCurrentTurn(paths);
+    const current = await bornListRow(paths, expected, snapshot);
+    const resumeUnsupported = current.life === "stranded"
+        && snapshot.latestSession?.provider === snapshot.soul.provider.name
+        && resolveProviderExecution(snapshot.soul.provider).adapter.resume === undefined;
+    const slice = await activitySlice(paths, { limit: Number.MAX_SAFE_INTEGER });
     return {
-        ...current,
-        ...(latest === null ? {} : { outcomeAt: latest.completedAt }),
-        ...(latest?.outcome.kind === "answered"
-            ? { answer: latest.outcome.answer, answerHistoryId: latest.outcome.historyId }
-            : {}),
-        ...(latest?.outcome.kind === "failed" ? { failure: latest.outcome.diagnostic } : {}),
-        activity: (() => {
-            const slice = activitySlice(paths, { limit: 5_000 });
-            return selectActivitySnapshot(slice.rows, {
-                pending: snapshot.pending,
-                lowestRetained: slice.lowestRetained,
-                highest: slice.highest,
-            });
-        })(),
+        id: current.id,
+        life: current.life,
+        ...(snapshot.soul.readonly === undefined ? {} : { readonly: snapshot.soul.readonly }),
+        ...(resumeUnsupported ? { strandedReason: "resume-unsupported" } : {}),
+        timeline: budget === undefined
+            ? selectActivitySnapshot(slice.rows)
+            : selectSnapshot(projectTurns(slice.rows), budget),
     };
 }
+/** Package-internal action observation; it uses the same snapshot selector as status. */
+export async function readActionFeedbackStatus(worldPath, id) {
+    return await bornStatus(pathsForAkuId(worldPath, id), id);
+}
+/** Package-internal budgeted observation; Fleet allocates, Akuma still selects. */
+export async function readBudgetedStatus(worldPath, id, input) {
+    if (!Number.isSafeInteger(input.ordinaryBudget) || input.ordinaryBudget < 0) {
+        throw new TypeError("ordinary budget must be a nonnegative safe integer");
+    }
+    const status = await bornStatus(pathsForAkuId(worldPath, id), id, ordinarySnapshotBudget(input.ordinaryBudget));
+    return { status, ordinarySelected: ordinarySelectedCount(status.timeline) };
+}
 function diagnostic(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -116,10 +117,10 @@ export class AkumaHandle {
     get paths() {
         return pathsForAkuId(this.worldPath, this.id);
     }
-    status() {
-        return bornStatus(this.paths, this.id);
+    async status() {
+        return await bornStatus(this.paths, this.id);
     }
-    history(input = {}) {
+    async history(input = {}) {
         if (input.before !== undefined && input.since !== undefined) {
             throw new TypeError("Akuma history before and since are mutually exclusive");
         }
@@ -132,13 +133,17 @@ export class AkumaHandle {
         if (!Number.isSafeInteger(limit) || limit <= 0 || limit > 5_000) {
             throw new TypeError("Akuma history limit must be a positive safe integer no greater than 5000");
         }
-        const slice = activitySlice(this.paths, {
+        const slice = await activitySlice(this.paths, {
             ...(input.before === undefined ? {} : { before: input.before }),
             ...(input.since === undefined ? {} : { since: input.since }),
             limit: 5_000,
         });
-        return projectActivityHistory(slice, readTurns(this.paths), {
-            since: input.since !== undefined,
+        return selectHistory(projectTurns(slice.rows, {
+            lowestRetained: slice.lowestRetained,
+            highest: slice.highest,
+        }), {
+            ...(input.before === undefined ? {} : { before: input.before }),
+            ...(input.since === undefined ? {} : { since: input.since }),
             limit,
         });
     }
@@ -149,66 +154,73 @@ export class AkumaHandle {
         }
         const deadline = options.timeoutMs === undefined ? undefined : performance.now() + options.timeoutMs;
         for (;;) {
-            const status = this.status();
+            const status = await this.status();
             if (predicate(status) || (deadline !== undefined && performance.now() >= deadline))
                 return status;
             await wait(deadline === undefined ? POLL_MS : Math.min(POLL_MS, Math.max(0, deadline - performance.now())));
         }
     }
     async tell(body) {
-        const recorded = recordTellBody(this.paths, body);
-        if (recorded.kind === "dead")
-            throw new Error(`Akuma ${this.id} is dead`);
-        return await wakeTell(this.paths, this.id, recorded.id);
+        const recorded = await recordTellBody(this.paths, this.id, body);
+        return await wakeTell(this.paths, recorded.tellId);
     }
     async interrupt(body) {
-        if (requestPause(this.paths, new Date().toISOString()) === "dead")
-            return { kind: "dead" };
+        const request = await requestPause(this.paths, new Date().toISOString());
+        if (request.kind === "not-born") {
+            throw new AkumaNotBornError(this.id);
+        }
         let putDown = "was-idle";
-        let leash = HeldAkumaLeash.try(this.paths);
+        let leash = await HeldAkumaLeash.try(this.paths);
         if (leash === null) {
-            leash = await takeLeashUntil(this.paths, performance.now() + KILL_GRACE_MS);
+            leash = await takeLeashUntil(this.paths, performance.now() + CONTROL_RESPONSE_MS);
             putDown = "self-aborted";
         }
         if (leash === null) {
-            const current = readHeart(this.paths).latestBody;
-            if (current === null)
-                return { kind: "unstoppable", evidence: "no-collar" };
-            if (probeProcessTree(current.collar).kind === "unverifiable") {
-                return { kind: "unstoppable", evidence: "collar-unverifiable" };
+            const body = (await readHeart(this.paths)).latestBody;
+            return { kind: "unavailable", evidence: body?.sequence === request.body.sequence && body.hung !== undefined
+                    ? "hung"
+                    : "unavailable" };
+        }
+        const settledBody = (await readHeart(this.paths)).latestBody;
+        if (settledBody?.sequence !== request.body.sequence || settledBody.end === undefined) {
+            try {
+                await leash.clearPause(this.paths);
             }
-            const evidence = await putDownProcessTree(current.collar);
-            if (evidence === "unavailable" || evidence === "alive-after-sigkill") {
-                return { kind: "unstoppable", evidence };
+            finally {
+                leash.release();
             }
-            leash = await takeLeashUntil(this.paths, performance.now() + KILL_GRACE_MS);
-            if (leash === null)
-                return { kind: "unstoppable", evidence: "leash-held-after-put-down" };
-            putDown = "collar";
+            return { kind: "unavailable", evidence: "untidy" };
         }
+        if (request.body.end !== undefined || settledBody.end !== "put-down")
+            putDown = "was-idle";
         let recorded;
         try {
-            leash.clearPause(this.paths);
-            recorded = recordTellBody(this.paths, body);
+            const id = randomUUID();
+            const admitted = await leash.recordInterruptTell(this.paths, {
+                kind: "tell",
+                id,
+                body,
+                recordedAt: new Date().toISOString(),
+            });
+            if (admitted.kind === "not-born")
+                throw new AkumaNotBornError(this.id);
+            recorded = { kind: "recorded", tellId: admitted.tell.id };
         }
         finally {
             leash.release();
         }
-        if (recorded.kind === "dead") {
-            return { kind: "interrupted", putDown, tell: { kind: "refused-dead" } };
-        }
-        return { kind: "interrupted", putDown, tell: await wakeTell(this.paths, this.id, recorded.id) };
+        return { kind: "interrupted", putDown, tell: await wakeTell(this.paths, recorded.tellId) };
     }
     async fork(input) {
-        const source = readSoul(this.paths);
+        const source = await readSoul(this.paths);
         if (source === null)
             throw new AkumaNotBornError(this.id);
         if (source.id !== this.id)
             throw new Error("Akuma soul does not match its coordinate");
-        const adapter = providerNamed(source.provider);
+        const adapter = resolveProviderExecution(source.provider).adapter;
         if (adapter.fork === undefined)
             return { kind: "provider-cannot-fork", provider: source.provider.name };
-        const point = readForkPoint(this.paths, input.at);
+        const point = await readForkPoint(this.paths, input.at);
         if (point === null)
             return { kind: "unknown-history", at: input.at };
         if (point.provider !== source.provider.name)
@@ -241,6 +253,7 @@ export class AkumaHandle {
                         ...(source.description === undefined ? {} : { description: source.description }),
                         provider: source.provider,
                         options: source.options,
+                        ...(source.readonly === undefined ? {} : { readonly: source.readonly }),
                         cwd: source.cwd,
                         origin: { kind: "fork", parent: this.id, at: input.at },
                         confinement: source.confinement,
@@ -256,57 +269,77 @@ export class AkumaHandle {
     }
     async kill() {
         const at = new Date().toISOString();
-        if (requestStop(this.paths, at) === "dead")
-            return "already-dead";
-        const graceDeadline = performance.now() + KILL_GRACE_MS;
-        while (probeLeash(this.paths) === "held" && performance.now() < graceDeadline)
-            await wait(POLL_MS);
-        if (probeLeash(this.paths) === "held") {
-            const current = readHeart(this.paths).latestBody;
-            if (current === null)
+        const request = await requestStop(this.paths, at);
+        if (request.kind !== "requested")
+            return request.kind;
+        const target = request.body;
+        const graceDeadline = performance.now() + CONTROL_RESPONSE_MS;
+        const leash = await takeLeashUntil(this.paths, graceDeadline);
+        if (await readKill(this.paths, target.sequence) !== null) {
+            leash?.release();
+            return "killed";
+        }
+        if (leash === null) {
+            if (await readKill(this.paths, target.sequence) !== null)
+                return "killed";
+            const body = (await readHeart(this.paths)).latestBody;
+            return body?.sequence === target.sequence && body.hung !== undefined ? "hung" : "unavailable";
+        }
+        try {
+            const settledBody = (await readHeart(this.paths)).latestBody;
+            if (settledBody?.sequence !== target.sequence)
+                return await readKill(this.paths, target.sequence) === null ? "unavailable" : "killed";
+            if (settledBody.end !== "put-down") {
+                await leash.clearStop(this.paths);
+                return "untidy";
+            }
+            const settled = await leash.settleStop(this.paths, target.sequence);
+            if (settled === null)
                 return "unavailable";
-            const evidence = await putDownProcessTree(current.collar);
-            if (evidence === "unavailable" || evidence === "alive-after-sigkill")
-                return evidence;
+            return "killed";
+        }
+        finally {
+            leash.release();
         }
-        const releaseDeadline = performance.now() + KILL_GRACE_MS;
-        while (probeLeash(this.paths) === "held" && performance.now() < releaseDeadline)
-            await wait(POLL_MS);
-        if (probeLeash(this.paths) === "held")
-            return "unavailable";
-        return recordDeath(this.paths, { evidence: "killed", at }) === "already-dead" ? "already-dead" : "killed";
     }
-    lastAnswer() {
-        const turn = readLastAnsweredTurn(this.paths);
-        return turn?.outcome.kind === "answered" ? turn.outcome.answer : "";
+    async lastAnswer() {
+        const turn = await readLastAnsweredTurn(this.paths);
+        return turn?.end?.outcome.kind === "answered"
+            ? { kind: "answer", answer: turn.end.outcome.answer }
+            : { kind: "no-answer" };
     }
 }
 export class Akuma {
     path;
-    settings;
-    constructor(path, settings) {
+    configuredSettings;
+    constructor(path, configuredSettings) {
         this.path = path;
-        this.settings = settings;
+        this.configuredSettings = configuredSettings;
+    }
+    static of(root, settings) {
+        if (typeof root !== "string")
+            throw new TypeError("Akuma.of root must be a WorldRoot");
+        return new Akuma(root, settings);
     }
-    static at(input) {
-        const path = resolve(input.path);
-        return new Akuma(path, input.settings ?? readSettings({ root: path }));
+    async settings() {
+        return this.configuredSettings ?? await readSettings({ root: this.path });
     }
     of(input) {
         return new AkumaHandle(parseAkuId(input.id).id, this.path);
     }
-    listArchetypes() {
-        return readArchetypes({ settings: this.settings });
+    async listArchetypes() {
+        return readArchetypes({ settings: await this.settings() });
     }
     async call(input) {
         const name = archetypeName(input.archetype);
-        const archetype = loadArchetype({ name, settings: this.settings });
+        const archetype = await loadArchetype({ name, settings: await this.settings() });
         const provider = archetype.adapter;
         const cwd = resolve(input.cwd ?? this.path);
         const recipe = Object.freeze({
             ...(archetype.description === undefined ? {} : { description: archetype.description }),
             provider: archetype.provider,
             options: archetype.options,
+            ...(archetype.readonly === undefined ? {} : { readonly: archetype.readonly }),
             confinement: provider.confinement({ cwd, options: archetype.options }),
         });
         const requests = injectedBodyRequests();
@@ -333,6 +366,7 @@ export class Akuma {
                     ...(archetype.description === undefined ? {} : { description: archetype.description }),
                     provider: archetype.provider,
                     options: archetype.options,
+                    ...(archetype.readonly === undefined ? {} : { readonly: archetype.readonly }),
                     cwd,
                     origin: { kind: "direct" },
                     confinement: recipe.confinement,
@@ -342,11 +376,18 @@ export class Akuma {
         });
         return new AkumaHandle(published.id, this.path);
     }
-    list() {
+    async list(input = {}) {
+        if (typeof input !== "object" || input === null || Array.isArray(input)) {
+            throw new TypeError("Akuma list input must be an object");
+        }
+        const unknown = Object.keys(input).find((key) => key !== "archetype");
+        if (unknown !== undefined)
+            throw new TypeError(`Akuma list input has unknown field: ${unknown}`);
+        const selected = input.archetype === undefined ? undefined : archetypeName(input.archetype);
         const runRoot = akumaRunRoot(this.path);
         let names;
         try {
-            names = readdirSync(runRoot, { withFileTypes: true })
+            names = (await readdir(runRoot, { withFileTypes: true }))
                 .filter((entry) => entry.isDirectory())
                 .map((entry) => entry.name)
                 .sort();
@@ -356,24 +397,31 @@ export class Akuma {
                 return { rows: [], searched: [runRoot] };
             throw error;
         }
-        const rows = names.flatMap((name) => {
+        const rows = [];
+        for (const name of names) {
             try {
                 const physical = akuIdFromDirectoryName(name);
+                if (selected !== undefined && physical.archetype !== selected)
+                    continue;
                 const paths = akumaPaths({ runRoot, archetype: physical.archetype, suffix: physical.suffix });
-                const snapshot = readHeart(paths);
-                if (snapshot.soul !== null)
-                    return [bornListRow(paths, physical.id, snapshot)];
-                if (probeLeash(paths) === "held")
-                    return [{ id: physical.id, life: "unborn" }];
-                const seal = readSeal(paths);
-                return seal === null
-                    ? [{ id: physical.id, life: "unborn" }]
-                    : [{ id: physical.id, life: "stillborn", seal }];
+                const snapshot = await readHeart(paths);
+                if (snapshot.soul !== null) {
+                    rows.push(await bornListRow(paths, physical.id, snapshot));
+                    continue;
+                }
+                if (await probeLeash(paths) === "held") {
+                    rows.push({ id: physical.id, life: "unborn" });
+                    continue;
+                }
+                const seal = await readSeal(paths);
+                rows.push(seal === null
+                    ? { id: physical.id, life: "unborn" }
+                    : { id: physical.id, life: "stillborn", seal });
             }
             catch {
-                return [];
+                continue;
             }
-        });
+        }
         return {
             rows,
             searched: [runRoot],

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

@@ -1,6 +1,6 @@
 import type { Settings } from "../settings.js";
-import { type ProviderAdapter, type ProviderOptions } from "./provider.js";
-import type { ProviderExecution } from "./heart/index.js";
+import type { ProviderAdapter } from "./provider.js";
+import { type ProviderExecution, type ProviderOptions, type ReadonlyRestraint } from "./provider-recipe.js";
 type DecodedArchetype = Readonly<{
     name: string;
     path: string;
@@ -8,24 +8,33 @@ type DecodedArchetype = Readonly<{
     description?: string;
     options: ProviderOptions;
 }>;
+export type ArchetypeCatalogRow = Readonly<{
+    name: string;
+    model?: string;
+    description?: string;
+}>;
 type ArchetypeDefinition = DecodedArchetype & Readonly<{
     adapter: ProviderAdapter;
 }>;
 type AdmittedArchetype = Omit<ArchetypeDefinition, "provider"> & Readonly<{
     provider: ProviderExecution;
+    readonly?: ReadonlyRestraint;
 }>;
 export declare class AkumaArchetypeError extends Error {
     readonly archetype: string;
     readonly searched: readonly string[];
     readonly reason: string;
     readonly kind = "akuma-archetype";
-    constructor(archetype: string, searched: readonly string[], reason: string);
+    constructor(archetype: string, searched: readonly string[], reason: string, guidance?: string);
 }
 export declare function listArchetypes(input: Readonly<{
     settings: Settings;
-}>): readonly string[];
+}>): Promise<readonly string[]>;
+export declare function listArchetypeDefinitions(input: Readonly<{
+    settings: Settings;
+}>): Promise<readonly ArchetypeCatalogRow[]>;
 export declare function loadArchetype(input: Readonly<{
     name: string;
     settings: Settings;
-}>): AdmittedArchetype;
+}>): Promise<AdmittedArchetype>;
 export {};