@astrosheep/keiyaku 4.0.1 → 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, readHeart, readLastAnsweredTurn, readForkPoint, readKill, readSeal, readSoul, 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 "./projection.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,9 +33,9 @@ async function takeLeashUntil(paths, deadline) {
         await wait(POLL_MS);
     }
 }
-function recordTellBody(paths, akuma, body) {
+async function recordTellBody(paths, akuma, body) {
     const id = randomUUID();
-    const admitted = recordTell(paths, { kind: "tell", id, body, recordedAt: new Date().toISOString() });
+    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 };
@@ -54,56 +52,57 @@ async function wakeTell(paths, tellId) {
         };
     }
 }
-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.latestBody, snapshot.latestKill),
-        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, profile = "status") {
-    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 current = await bornListRow(paths, expected, snapshot);
     const resumeUnsupported = current.life === "stranded"
         && snapshot.latestSession?.provider === snapshot.soul.provider.name
-        && providerNamed(snapshot.soul.provider).resume === undefined;
+        && resolveProviderExecution(snapshot.soul.provider).adapter.resume === undefined;
+    const slice = await activitySlice(paths, { limit: Number.MAX_SAFE_INTEGER });
     return {
         id: current.id,
         life: current.life,
-        collar: current.collar,
+        ...(snapshot.soul.readonly === undefined ? {} : { readonly: snapshot.soul.readonly }),
         ...(resumeUnsupported ? { strandedReason: "resume-unsupported" } : {}),
-        timeline: (() => {
-            const slice = activitySlice(paths, { limit: Number.MAX_SAFE_INTEGER });
-            return selectActivitySnapshot(slice.rows, {
-                lowestRetained: slice.lowestRetained,
-                highest: slice.highest,
-                profile,
-            });
-        })(),
+        timeline: budget === undefined
+            ? selectActivitySnapshot(slice.rows)
+            : selectSnapshot(projectTurns(slice.rows), budget),
     };
 }
-/** Package-internal compact observation for action feedback. */
-export function readActionFeedbackStatus(worldPath, id) {
-    return bornStatus(pathsForAkuId(worldPath, id), id, "feedback");
+/** 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);
@@ -118,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");
         }
@@ -134,12 +133,15 @@ 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, {
+        return selectHistory(projectTurns(slice.rows, {
+            lowestRetained: slice.lowestRetained,
+            highest: slice.highest,
+        }), {
             ...(input.before === undefined ? {} : { before: input.before }),
             ...(input.since === undefined ? {} : { since: input.since }),
             limit,
@@ -152,46 +154,49 @@ 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, this.id, body);
+        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()).kind === "not-born") {
+        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 {
             const id = randomUUID();
-            const admitted = leash.recordInterruptTell(this.paths, {
+            const admitted = await leash.recordInterruptTell(this.paths, {
                 kind: "tell",
                 id,
                 body,
@@ -207,15 +212,15 @@ export class AkumaHandle {
         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)
@@ -248,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,
@@ -263,28 +269,31 @@ export class AkumaHandle {
     }
     async kill() {
         const at = new Date().toISOString();
-        const request = requestStop(this.paths, at);
-        if (request.kind === "already-killed")
-            return "already-killed";
+        const request = await requestStop(this.paths, at);
+        if (request.kind !== "requested")
+            return request.kind;
         const target = request.body;
-        const graceDeadline = performance.now() + KILL_GRACE_MS;
-        while (probeLeash(this.paths) === "held" && performance.now() < graceDeadline)
-            await wait(POLL_MS);
-        if (readKill(this.paths, target.sequence) !== null)
+        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";
-        const targetProbe = probeProcessTree(target.collar);
-        if (targetProbe.kind === "unverifiable")
-            return "unavailable";
-        if (targetProbe.kind === "alive") {
-            const evidence = await putDownProcessTree(target.collar);
-            if (evidence === "unavailable" || evidence === "alive-after-sigkill")
-                return evidence;
         }
-        const leash = await takeLeashUntil(this.paths, performance.now() + KILL_GRACE_MS);
-        if (leash === null)
-            return readKill(this.paths, target.sequence) === null ? "unavailable" : "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 settled = leash.settleStop(this.paths, target.sequence);
+            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";
             return "killed";
@@ -293,8 +302,8 @@ export class AkumaHandle {
             leash.release();
         }
     }
-    lastAnswer() {
-        const turn = readLastAnsweredTurn(this.paths);
+    async lastAnswer() {
+        const turn = await readLastAnsweredTurn(this.paths);
         return turn?.end?.outcome.kind === "answered"
             ? { kind: "answer", answer: turn.end.outcome.answer }
             : { kind: "no-answer" };
@@ -312,24 +321,25 @@ export class Akuma {
             throw new TypeError("Akuma.of root must be a WorldRoot");
         return new Akuma(root, settings);
     }
-    settings() {
-        return this.configuredSettings ?? readSettings({ root: this.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();
@@ -356,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,
@@ -365,7 +376,7 @@ export class Akuma {
         });
         return new AkumaHandle(published.id, this.path);
     }
-    list(input = {}) {
+    async list(input = {}) {
         if (typeof input !== "object" || input === null || Array.isArray(input)) {
             throw new TypeError("Akuma list input must be an object");
         }
@@ -376,7 +387,7 @@ export class Akuma {
         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();
@@ -386,26 +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)
-                    return [];
+                    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;
@@ -18,22 +18,23 @@ type ArchetypeDefinition = DecodedArchetype & Readonly<{
 }>;
 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;
-}>): readonly ArchetypeCatalogRow[];
+}>): Promise<readonly ArchetypeCatalogRow[]>;
 export declare function loadArchetype(input: Readonly<{
     name: string;
     settings: Settings;
-}>): AdmittedArchetype;
+}>): Promise<AdmittedArchetype>;
 export {};