@astrosheep/keiyaku 4.5.16 → 4.5.18

package/build/src/akuma/akuma-observe.js

@@ -1,4 +1,4 @@
-import { activitySlice, isHeartAbsent, life, lifeAt, probeLeash, readHeart, readSeal, readSoul, } from "./heart/index.js";
+import { activitySlice, HeldAkumaLeash, isHeartAbsent, life, lifeAt, probeLeash, readHeart, readSeal, readSoul, } from "./heart/index.js";
 import { pathsForAkuId } from "./identity.js";
 import { ordinarySnapshotBudget, projectTurns, selectHistory, selectSnapshot, } from "./projection.js";
 import { resolveProviderExecution } from "./providers/index.js";
@@ -6,7 +6,7 @@ import { AkumaNotBornError } from "./akuma-errors.js";
 export async function fleetListRow(paths, expected) {
     const snapshot = await readHeart(paths);
     if (snapshot.soul !== null)
-        return await bornListRow(paths, expected, snapshot);
+        return (await bornObservation(paths, expected, snapshot)).row;
     try {
         if ((await probeLeash(paths)) === "held")
             return { id: expected, life: "unborn" };
@@ -19,33 +19,51 @@ export async function fleetListRow(paths, expected) {
         throw error;
     }
 }
-async function bornListRow(paths, expected, snapshot) {
+async function bornObservation(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 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: currentLife,
-        lifeAt: lifeAt(currentLife, snapshot.latestBody, snapshot.latestKill, snapshot.soul.createdAt),
-        lastActivityAt: snapshot.lastActivityAt,
-        pending: snapshot.pending.map((tell) => tell.id),
-    };
+    const claim = await HeldAkumaLeash.try(paths);
+    try {
+        // A Body may finish after the first read. Refresh under the free seat so
+        // neither its release nor a successor can manufacture an untidy observation.
+        if (claim !== null)
+            snapshot = await readHeart(paths);
+        const soul = snapshot.soul;
+        if (soul === null)
+            throw new AkumaNotBornError(expected);
+        if (soul.id !== expected)
+            throw new Error("Akuma soul does not match its coordinate");
+        const currentLife = life({
+            leash: claim === null ? "held" : "free",
+            body: snapshot.latestBody,
+            kill: snapshot.latestKill,
+        });
+        return {
+            snapshot,
+            soul,
+            row: {
+                id: soul.id,
+                archetype: soul.archetype,
+                ...(soul.description === undefined ? {} : { description: soul.description }),
+                life: currentLife,
+                lifeAt: lifeAt(currentLife, snapshot.latestBody, snapshot.latestKill, soul.createdAt),
+                lastActivityAt: snapshot.lastActivityAt,
+                pending: snapshot.pending.map((tell) => tell.id),
+            },
+        };
+    }
+    finally {
+        claim?.release();
+    }
 }
 export async function bornStatus(paths, expected, input) {
     if (input.ordinaryBudget !== undefined && (!Number.isSafeInteger(input.ordinaryBudget) || input.ordinaryBudget < 0))
         throw new TypeError("ordinary budget must be a nonnegative safe integer");
-    const snapshot = await readHeart(paths);
-    if (snapshot.soul === null)
-        throw new AkumaNotBornError(expected);
-    const current = await bornListRow(paths, expected, snapshot);
+    const { snapshot, soul, row: current } = await bornObservation(paths, expected);
     const resumeUnsupported = current.life === "stranded" &&
-        snapshot.latestSession?.provider === snapshot.soul.provider.name &&
-        (await resolveProviderExecution(snapshot.soul.provider)).adapter.resume === undefined;
+        snapshot.latestSession?.provider === soul.provider.name &&
+        (await resolveProviderExecution(soul.provider)).adapter.resume === undefined;
     const slice = await activitySlice(paths);
     const selected = selectSnapshot(projectTurns(slice.rows), {
         aperture: input.aperture,
@@ -56,7 +74,7 @@ export async function bornStatus(paths, expected, input) {
         status: {
             id: current.id,
             life: current.life,
-            ...(snapshot.soul.readonly === undefined ? {} : { readonly: snapshot.soul.readonly }),
+            ...(soul.readonly === undefined ? {} : { readonly: soul.readonly }),
             ...(resumeUnsupported ? { strandedReason: "resume-unsupported" } : {}),
             timeline: selected.snapshot,
         },

package/build/src/akuma/akuma-product.d.ts

@@ -20,7 +20,7 @@ export type BornAkumaCall = Readonly<{
             kind: "direct";
         };
     }>;
-    initialBody: string;
+    initialBody?: string;
     initialSchemaJson?: string;
     execution: BornExecution;
 }>;
@@ -31,21 +31,23 @@ export type RequestedAkumaCall = Readonly<{
     execution: BornExecution;
 }>;
 export type AkumaBornCall = BornAkumaCall | RequestedAkumaCall;
-type AkumaCallLaunchInput = AkumaCallInput;
+type AkumaCallLaunchInput = Omit<AkumaCallInput, "body"> & Readonly<{
+    body?: string;
+}>;
 export declare const PAGE_POOL_SIZE = 16;
 export declare function boundedMap<Value, Result>(values: readonly Value[], mapper: (value: Value) => Promise<Result>): Promise<readonly Result[]>;
-export declare class Akuma {
+declare class AkumaProduct {
     private readonly path;
     private readonly configuration;
     private constructor();
-    static of(root: WorldRoot, input?: AkumaConfiguration): Akuma;
-    of(input: Readonly<{
+    static create(root: WorldRoot, input?: AkumaConfiguration): AkumaProduct;
+    selectHandle(input: Readonly<{
         id: string;
     }>): AkumaHandle;
     listArchetypes(): Promise<readonly string[]>;
-    call(input: AkumaCallLaunchInput): Promise<AkumaHandle>;
-    beginCall(input: AkumaCallLaunchInput, context: AkumaCallContext): Promise<AkumaBornCall>;
-    finishCall(born: AkumaBornCall, completion?: Readonly<{
+    invoke(input: AkumaCallLaunchInput): Promise<AkumaHandle>;
+    admit(input: AkumaCallLaunchInput, context: AkumaCallContext): Promise<AkumaBornCall>;
+    publish(born: AkumaBornCall, completion?: Readonly<{
         contractId?: string;
     }>): Promise<AkumaHandle>;
     [CALL_WITH_CONTEXT](input: AkumaCallLaunchInput, context: AkumaCallContext): Promise<AkumaHandle>;
@@ -54,4 +56,6 @@ export declare class Akuma {
     }>): Promise<AkumaCompleteList>;
     list(input?: AkumaListInput): Promise<AkumaList>;
 }
+/** Internal composition product; the package exposes the smaller Akuma instance instead. */
+export declare function createAkumaProduct(root: WorldRoot, input?: AkumaConfiguration): AkumaProduct;
 export {};

package/build/src/akuma/akuma-product.js

@@ -13,6 +13,55 @@ import { requestForwardedAkumaCall } from "./call-request.js";
 import { executionChannel } from "./requests.js";
 import { decodeAllowedActions, unionAllowedActions } from "./allowed.js";
 import { settings as readSettings } from "../settings.js";
+import { schemaJsonText } from "./schema.js";
+async function admitBodyRequest(input) {
+    const cwd = input.call.cwd === undefined
+        ? undefined
+        : input.context.cwdCanonical === true
+            ? input.call.cwd
+            : await canonicalBirthCwd(input.call.cwd);
+    const child = await requestForwardedAkumaCall({
+        directory: input.execution.directory,
+        id: randomUUID(),
+        world: input.path,
+        archetype: input.name,
+        ...(input.call.body === undefined ? {} : { body: input.call.body }),
+        ...(cwd === undefined ? {} : { cwd }),
+        recipe: input.recipe,
+    });
+    const bornCwd = await readAkumaBirthCwd(input.path, child);
+    return {
+        kind: "requested",
+        id: child,
+        cwd: bornCwd,
+        execution: { cwd: bornCwd, source: cwd === undefined ? "caller" : "input" },
+    };
+}
+async function admitDirect(input) {
+    const initiatorCwd = input.context.initiatorCwd;
+    const selectedCwd = input.call.cwd ?? initiatorCwd ?? input.path;
+    const cwd = input.call.cwd !== undefined && input.context.cwdCanonical === true
+        ? input.call.cwd
+        : await canonicalBirthCwd(selectedCwd);
+    const allocated = await birthAkuma({ worldPath: input.path, archetype: input.archetype.name });
+    return {
+        kind: "born",
+        allocated,
+        seed: {
+            id: allocated.id,
+            archetype: allocated.archetype,
+            ...input.recipe,
+            cwd,
+            origin: { kind: "direct" },
+        },
+        ...(input.call.body === undefined ? {} : { initialBody: input.call.body }),
+        ...(input.call.schema === undefined ? {} : { initialSchemaJson: schemaJsonText(input.call.schema) }),
+        execution: {
+            cwd,
+            source: input.call.cwd !== undefined ? "input" : initiatorCwd === undefined ? "world" : "process",
+        },
+    };
+}
 export const PAGE_POOL_SIZE = 16;
 function activityAt(row) {
     if (!("lifeAt" in row))
@@ -106,19 +155,19 @@ async function readableRows(rows) {
     });
     return [...loaded].filter((row) => row !== null);
 }
-export class Akuma {
+class AkumaProduct {
     path;
     configuration;
     constructor(path, configuration) {
         this.path = path;
         this.configuration = configuration;
     }
-    static of(root, input = {}) {
+    static create(root, input = {}) {
         if (typeof root !== "string")
-            throw new TypeError("Akuma.of root must be a WorldRoot");
-        return new Akuma(root, input);
+            throw new TypeError("Akuma product root must be a WorldRoot");
+        return new AkumaProduct(root, input);
     }
-    of(input) {
+    selectHandle(input) {
         return new AkumaHandle(parseAkuId(input.id).id, this.path);
     }
     async listArchetypes() {
@@ -127,10 +176,10 @@ export class Akuma {
             ...(this.configuration.home === undefined ? {} : { home: this.configuration.home }),
         });
     }
-    async call(input) {
+    async invoke(input) {
         return await this[CALL_WITH_CONTEXT](input, { initiatorCwd: process.cwd() });
     }
-    async beginCall(input, context) {
+    async admit(input, context) {
         const readonly = callReadonly(input.readonly);
         const name = archetypeName(input.archetype);
         const home = this.configuration.home === undefined ? {} : { home: this.configuration.home };
@@ -147,52 +196,11 @@ export class Akuma {
             ...(archetype.readonly === undefined ? {} : { readonly: archetype.readonly }),
             allowed,
         });
-        if (execution.kind === "body-request") {
-            const cwd = input.cwd === undefined
-                ? undefined
-                : context?.cwdCanonical === true
-                    ? input.cwd
-                    : await canonicalBirthCwd(input.cwd);
-            const child = await requestForwardedAkumaCall({
-                directory: execution.directory,
-                id: randomUUID(),
-                world: this.path,
-                archetype: name,
-                body: input.body,
-                ...(cwd === undefined ? {} : { cwd }),
-                recipe: requestRecipe,
-            });
-            const bornCwd = await readAkumaBirthCwd(this.path, child);
-            return {
-                kind: "requested",
-                id: child,
-                cwd: bornCwd,
-                execution: { cwd: bornCwd, source: cwd === undefined ? "caller" : "input" },
-            };
-        }
-        const initiatorCwd = context.initiatorCwd;
-        const selectedCwd = input.cwd ?? initiatorCwd ?? this.path;
-        const cwd = input.cwd !== undefined && context?.cwdCanonical === true ? input.cwd : await canonicalBirthCwd(selectedCwd);
-        const allocated = await birthAkuma({ worldPath: this.path, archetype: archetype.name });
-        return {
-            kind: "born",
-            allocated,
-            seed: {
-                id: allocated.id,
-                archetype: allocated.archetype,
-                ...requestRecipe,
-                cwd,
-                origin: { kind: "direct" },
-            },
-            initialBody: input.body,
-            ...(input.schema === undefined ? {} : { initialSchemaJson: input.schema.jsonText }),
-            execution: {
-                cwd,
-                source: input.cwd !== undefined ? "input" : initiatorCwd === undefined ? "world" : "process",
-            },
-        };
+        if (execution.kind === "body-request")
+            return await admitBodyRequest({ call: input, context, path: this.path, name, recipe: requestRecipe, execution });
+        return await admitDirect({ call: input, context, path: this.path, archetype, recipe: requestRecipe });
     }
-    async finishCall(born, completion = {}) {
+    async publish(born, completion = {}) {
         if (born.kind === "requested") {
             return new AkumaHandle(born.id, this.path, { cwd: born.cwd, source: born.execution.source });
         }
@@ -201,7 +209,7 @@ export class Akuma {
             launch: async (allocated) => await spawnAkumaBody({
                 paths: allocated.paths,
                 seed: born.seed,
-                initialBody: born.initialBody,
+                ...(born.initialBody === undefined ? {} : { initialBody: born.initialBody }),
                 ...(born.initialSchemaJson === undefined ? {} : { initialSchemaJson: born.initialSchemaJson }),
                 ...(Object.keys(completion).length === 0 ? {} : { completion }),
             }),
@@ -212,7 +220,7 @@ export class Akuma {
         });
     }
     async [CALL_WITH_CONTEXT](input, context) {
-        return await this.finishCall(await this.beginCall(input, context));
+        return await this.publish(await this.admit(input, context));
     }
     async listComplete(input = {}) {
         if (typeof input !== "object" || input === null || Array.isArray(input))
@@ -270,3 +278,7 @@ export class Akuma {
         };
     }
 }
+/** Internal composition product; the package exposes the smaller Akuma instance instead. */
+export function createAkumaProduct(root, input = {}) {
+    return AkumaProduct.create(root, input);
+}

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

@@ -1,7 +1,6 @@
-import { type TellResult, type TellWakeRuntime } from "./body.js";
-import { HeldAkumaLeash, type AkumaLife, type KillEvidence, type ResumeCoordinate } from "./heart/index.js";
+import { type AkumaLife, type KillEvidence, type ResumeCoordinate } from "./heart/index.js";
 export type { KillEvidence };
-import { type AkuId, type AkumaPaths } from "./identity.js";
+import { type AkuId } from "./identity.js";
 import type { Settings } from "../settings.js";
 import type { WorldRoot } from "../world.js";
 import type { AllowedAction } from "./allowed.js";
@@ -9,6 +8,9 @@ import type { ExecutionContext } from "./requests.js";
 import { z } from "zod";
 import type { BoundedList } from "../bounded-list.js";
 import type { Schema } from "./schema.js";
+import { killAkumaWithRecovery } from "./akuma-handle.js";
+import type { TellResult } from "./body.js";
+export { killAkumaWithRecovery };
 export declare const POLL_MS = 100;
 export type AkumaListRow = Readonly<{
     id: AkuId;
@@ -431,7 +433,6 @@ export type AkumaCallExecution = Readonly<{
     cwd: string;
     source: "input" | "caller" | "process" | "world";
 }>;
-export { CALL_WITH_CONTEXT } from "./akuma-product-symbols.js";
 export type AkumaCallInput = Readonly<{
     archetype: string;
     body: string;
@@ -472,27 +473,14 @@ export type ForkReceipt = Readonly<{
 }>;
 export { AkumaNotBornError } from "./akuma-errors.js";
 export declare function wait(milliseconds: number): Promise<void>;
-export declare function takeLeashUntil(paths: AkumaPaths, deadline: number): Promise<HeldAkumaLeash | null>;
-export declare function recordTellBody(paths: AkumaPaths, akuma: AkuId, body: string, id?: string, recordedAt?: string): Promise<Readonly<{
-    kind: "recorded";
-    tellId: string;
-}>>;
-export declare function tellAkumaWithId(input: Readonly<{
-    worldPath: WorldRoot;
-    id: AkuId;
-    body: string;
-    tellId: string;
-    recordedAt?: string;
-    runtime?: TellWakeRuntime;
-}>): Promise<TellResult>;
-export declare function diagnostic(error: unknown): string;
-export declare function killAkumaWithRecovery(paths: AkumaPaths, recover?: (paths: AkumaPaths) => Promise<void>): Promise<KillEvidence>;
 export { bornStatus, fleetListRow, readAkumaBirthCwd, readBudgetedStatus, type BudgetedStatusObservation, } from "./akuma-observe.js";
 export type AkumaConfiguration = Readonly<{
     home?: string;
     settings?: Settings;
     execution?: ExecutionContext;
 }>;
-export { AkumaHandle, akumaCallExecution, type LastAnswer } from "./akuma-handle.js";
-export { Akuma } from "./akuma-product.js";
+/** Internal catalog observation for composition owners. */
+export declare function readAkumaCatalog(path: WorldRoot, input?: AkumaListInput): Promise<AkumaList>;
+/** Internal timeline observation for composition owners. */
+export declare function readAkumaTimeline(path: WorldRoot, id: AkuId): Promise<AkumaStatus["timeline"]>;
 export { AkumaBusyError, AkumaDecodeError, AkumaProviderError } from "./akuma-errors.js";

package/build/src/akuma/akuma.js

@@ -1,9 +1,9 @@
-import { randomUUID } from "node:crypto";
-import { CONTROL_RESPONSE_MS, handoffPendingTells, wakeRecordedTell, } from "./body.js";
-import { HeldAkumaLeash, readHeart, readKill, recordTell, requestStop, } from "./heart/index.js";
-import { parseAkuId, pathsForAkuId } from "./identity.js";
+import { parseAkuId } from "./identity.js";
 import { activitySnapshotSchema } from "./projection.js";
 import { z } from "zod";
+import { createAkumaProduct } from "./akuma-product.js";
+import { killAkumaWithRecovery } from "./akuma-handle.js";
+export { killAkumaWithRecovery };
 export const POLL_MS = 100;
 export const akumaIdSchema = z.string().transform((value, context) => {
     try {
@@ -38,73 +38,17 @@ export function defaultWaitComplete(status) {
     return (status.life !== "running" &&
         !status.timeline.entries.some((entry) => entry.kind === "row" && entry.row.kind === "tell" && entry.row.state === "pending"));
 }
-export { CALL_WITH_CONTEXT } from "./akuma-product-symbols.js";
 export { AkumaNotBornError } from "./akuma-errors.js";
-import { AkumaNotBornError } from "./akuma-errors.js";
 export function wait(milliseconds) {
     return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
-export async function takeLeashUntil(paths, deadline) {
-    for (;;) {
-        const leash = await HeldAkumaLeash.try(paths);
-        if (leash !== null)
-            return leash;
-        if (performance.now() >= deadline)
-            return null;
-        await wait(Math.min(POLL_MS, Math.max(0, deadline - performance.now())));
-    }
-}
-export async function recordTellBody(paths, akuma, body, id = randomUUID(), recordedAt = new Date().toISOString()) {
-    const admitted = await recordTell(paths, { kind: "tell", id, body, recordedAt });
-    if (admitted.kind === "not-born")
-        throw new AkumaNotBornError(akuma);
-    return { kind: "recorded", tellId: admitted.tell.id };
-}
-export async function tellAkumaWithId(input) {
-    const paths = pathsForAkuId(input.worldPath, input.id);
-    const recorded = await recordTellBody(paths, input.id, input.body, input.tellId, input.recordedAt);
-    return await wakeRecordedTell(paths, recorded.tellId, input.runtime);
+export { bornStatus, fleetListRow, readAkumaBirthCwd, readBudgetedStatus, } from "./akuma-observe.js";
+/** Internal catalog observation for composition owners. */
+export async function readAkumaCatalog(path, input = {}) {
+    return await createAkumaProduct(path).list(input);
 }
-export function diagnostic(error) {
-    return error instanceof Error ? error.message : String(error);
+/** Internal timeline observation for composition owners. */
+export async function readAkumaTimeline(path, id) {
+    return (await createAkumaProduct(path).selectHandle({ id }).status()).timeline;
 }
-export async function killAkumaWithRecovery(paths, recover = handoffPendingTells) {
-    try {
-        const request = await requestStop(paths, new Date().toISOString());
-        if (request.kind !== "requested")
-            return request.kind;
-        const target = request.body;
-        const leash = await takeLeashUntil(paths, performance.now() + CONTROL_RESPONSE_MS);
-        if ((await readKill(paths, target.sequence)) !== null) {
-            leash?.release();
-            return "killed";
-        }
-        if (leash === null) {
-            if ((await readKill(paths, target.sequence)) !== null)
-                return "killed";
-            const body = (await readHeart(paths)).latestBody;
-            return body?.sequence === target.sequence && body.hung !== undefined ? "hung" : "unavailable";
-        }
-        try {
-            const settledBody = (await readHeart(paths)).latestBody;
-            if (settledBody?.sequence !== target.sequence)
-                return (await readKill(paths, target.sequence)) === null ? "unavailable" : "killed";
-            if (settledBody.end !== "put-down") {
-                await leash.clearStop(paths);
-                return "untidy";
-            }
-            const settled = await leash.settleStop(paths, target.sequence);
-            return settled === null ? "unavailable" : "killed";
-        }
-        finally {
-            leash.release();
-        }
-    }
-    finally {
-        void recover(paths).catch(() => undefined);
-    }
-}
-export { bornStatus, fleetListRow, readAkumaBirthCwd, readBudgetedStatus, } from "./akuma-observe.js";
-export { AkumaHandle, akumaCallExecution } from "./akuma-handle.js";
-export { Akuma } from "./akuma-product.js";
 export { AkumaBusyError, AkumaDecodeError, AkumaProviderError } from "./akuma-errors.js";