@astrosheep/keiyaku 4.5.7 → 4.5.8

package/build/src/akuma/call-request.js

@@ -0,0 +1,211 @@
+import { isAbsolute, resolve } from "node:path";
+import { clipAllowedActions, decodeAllowedActions } from "./allowed.js";
+import { refuseRequest, reserveRequest } from "./heart/index.js";
+import { archetypeName, parseAkuId } from "./identity.js";
+import { publishAkuma } from "./publication.js";
+import { decodeProviderOptions, decodeReadonlyRestraint } from "./provider-recipe.js";
+import { decodeProviderExecution } from "./providers/index.js";
+import { requestBodyCommand } from "./request-rendezvous.js";
+import { eraseRequestCommand } from "./request-wire.js";
+import { z } from "zod";
+import { World } from "../world.js";
+function schemaDecode(decode, message) {
+    return z.unknown().transform((value, context) => {
+        try {
+            return decode(value);
+        }
+        catch {
+            context.addIssue({ code: "custom", message });
+            return z.NEVER;
+        }
+    });
+}
+const absolutePathSchema = z.string().refine((value) => isAbsolute(value) && resolve(value) === value);
+const akuIdSchema = z.string().transform((value, context) => {
+    try {
+        const id = parseAkuId(value).id;
+        if (id !== value) {
+            context.addIssue({ code: "custom", message: "expected canonical AkuId" });
+            return z.NEVER;
+        }
+        return id;
+    }
+    catch {
+        context.addIssue({ code: "custom", message: "expected canonical AkuId" });
+        return z.NEVER;
+    }
+});
+const archetypeSchema = z.string().transform((value, context) => {
+    try {
+        return archetypeName(value);
+    }
+    catch {
+        context.addIssue({ code: "custom", message: "expected archetype" });
+        return z.NEVER;
+    }
+});
+const allowedActionsSchema = schemaDecode(decodeAllowedActions, "expected allowed actions");
+const providerExecutionSchema = schemaDecode(decodeProviderExecution, "expected provider execution");
+const providerOptionsSchema = schemaDecode(decodeProviderOptions, "expected provider options");
+const readonlyRestraintSchema = schemaDecode(decodeReadonlyRestraint, "expected readonly restraint");
+const akumaCallRecipeSchema = z
+    .object({
+    description: z.string().trim().min(1).optional(),
+    allowed: allowedActionsSchema,
+    provider: providerExecutionSchema,
+    options: providerOptionsSchema,
+    readonly: readonlyRestraintSchema.optional(),
+})
+    .strict()
+    .superRefine((recipe, context) => {
+    if ((recipe.options.readonly === true) !== (recipe.readonly !== undefined)) {
+        context.addIssue({ code: "custom", message: "readonly recipe fields disagree" });
+    }
+});
+const akumaCallPayloadSchema = z
+    .object({
+    world: absolutePathSchema,
+    archetype: archetypeSchema,
+    body: z.string(),
+    cwd: absolutePathSchema.optional(),
+    recipe: akumaCallRecipeSchema,
+})
+    .strict();
+function carriesLaunchWorld(value) {
+    const upstream = object(value);
+    return upstream !== null && typeof upstream.launchWorld === "function";
+}
+function decodeCallExecutionContext(value) {
+    const context = object(value);
+    const paths = object(context?.paths);
+    const parent = object(context?.parent);
+    const parentId = akuIdSchema.safeParse(parent?.id);
+    if (context === null ||
+        typeof context.id !== "string" ||
+        context.id.trim() === "" ||
+        typeof context.requester !== "string" ||
+        typeof context.signal !== "object" ||
+        context.signal === null ||
+        typeof context.signal.throwIfAborted !== "function" ||
+        paths === null ||
+        !["directory", "heart", "leash", "log", "requests"].every((key) => typeof paths[key] === "string") ||
+        parent === null ||
+        !parentId.success ||
+        typeof parent.cwd !== "string" ||
+        !Array.isArray(parent.allowed) ||
+        typeof context.spawn !== "function" ||
+        typeof context.admissionOpen !== "function")
+        throw new Error("invalid Akuma call execution context");
+    if (!carriesLaunchWorld(context.upstream))
+        throw new Error("Akuma call requires a minted launch World");
+    return {
+        id: context.id,
+        requester: context.requester,
+        signal: context.signal,
+        world: context.upstream.launchWorld(),
+        paths: context.paths,
+        parent: context.parent,
+        spawn: context.spawn,
+        admissionOpen: context.admissionOpen,
+    };
+}
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+export function decodeAkumaCallRequest(value) {
+    const parsed = akumaCallPayloadSchema.safeParse(value);
+    return parsed.success ? { ...parsed.data, action: "akuma.call" } : null;
+}
+function callPayload(request) {
+    const { action: _action, ...payload } = request;
+    return payload;
+}
+async function executeAkumaCall(request, context) {
+    const world = context.world;
+    const requestWorld = await World.prove(request.world);
+    if (requestWorld !== world) {
+        await refuseRequest(context.paths, context.id, `request world ${requestWorld} does not match ${world}`);
+        throw new Error(`request world ${requestWorld} does not match ${world}`);
+    }
+    const recipe = {
+        ...(request.recipe.description === undefined ? {} : { description: request.recipe.description }),
+        allowed: clipAllowedActions(request.recipe.allowed, context.parent.allowed),
+        provider: request.recipe.provider,
+        options: request.recipe.options,
+        ...(request.recipe.readonly === undefined ? {} : { readonly: request.recipe.readonly }),
+    };
+    const published = await publishAkuma({
+        worldPath: world,
+        archetype: request.archetype,
+        signal: context.signal,
+        launch: async (allocated) => {
+            if (!context.admissionOpen())
+                throw new Error("body closed request admission");
+            await reserveRequest(context.paths, context.id, allocated.id);
+            return await context.spawn({
+                paths: allocated.paths,
+                seed: {
+                    id: allocated.id,
+                    archetype: allocated.archetype,
+                    ...recipe,
+                    cwd: request.cwd ?? context.parent.cwd,
+                    origin: { kind: "request", parent: context.parent.id, requestId: context.id },
+                },
+                initialBody: request.body,
+            });
+        },
+    });
+    return { result: published.id, child: published.id };
+}
+export function akumaCallRequestCommand() {
+    return {
+        action: "akuma.call",
+        encodeRequest: callPayload,
+        decodeRequest: decodeAkumaCallRequest,
+        encodeResult: (result) => result,
+        decodeResult: (result) => {
+            const child = akuIdSchema.safeParse(result);
+            if (!child.success)
+                throw new Error("Akuma call returned an invalid child");
+            return child.data;
+        },
+        encodeService: (service) => service,
+        decodeService: (_service) => {
+            throw new Error("Akuma call has no service evidence");
+        },
+        projectService: (_service) => {
+            throw new Error("Akuma call has no service evidence");
+        },
+        projectChild: (child) => {
+            const id = akuIdSchema.safeParse(child);
+            if (!id.success)
+                throw new Error("Akuma call stored an invalid child reference");
+            return id.data;
+        },
+        decodeReference: (reference) => {
+            const child = akuIdSchema.safeParse(reference);
+            if (!child.success)
+                throw new Error("Akuma call stored an invalid child reference");
+            return child.data;
+        },
+        isPermitted: (allowed) => allowed.includes("akuma.call"),
+        decodeExecutionContext: decodeCallExecutionContext,
+        execute: executeAkumaCall,
+    };
+}
+export function akumaCallRequestCommands() {
+    return { "akuma.call": eraseRequestCommand(akumaCallRequestCommand()) };
+}
+export async function requestForwardedAkumaCall(input) {
+    const { directory, id, signal, ...request } = input;
+    const response = await requestBodyCommand({
+        directory,
+        id,
+        command: akumaCallRequestCommand(),
+        value: { ...request, action: "akuma.call" },
+        ...(signal === undefined ? {} : { signal }),
+    });
+    return response.kind === "returned" ? response.result : response.reference;
+}

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

@@ -2,7 +2,6 @@ import type { AkuId } from "../identity.js";
 import type { ResumeCoordinate } from "../coordinate.js";
 import type { ProviderExecution, ProviderOptions, ReadonlyRestraint } from "../provider-recipe.js";
 import type { AllowedActions } from "../allowed.js";
-import type { TaskMutationAction, TaskMutationRequest } from "../../task/mutation.js";
 export type { ResumeCoordinate } from "../coordinate.js";
 export type AkumaOrigin = Readonly<{
     kind: "direct";
@@ -123,75 +122,10 @@ export type TellReceiptInput = Readonly<{
     turnSequence: number;
     fence: string;
 }>);
-export type TaskRequestInput = Readonly<{
-    id: string;
-    action: TaskMutationAction;
-    world: string;
-    request: TaskMutationRequest;
-}>;
 export type RequestInput = Readonly<{
     id: string;
-    action: "akuma.call";
-    archetype: string;
-    body: string;
-    cwd?: string;
-    world: string;
-    recipe: RequestRecipe;
-}> | Readonly<{
-    id: string;
-    action: "akuma.wait";
-    targets: readonly AkuId[];
-    completion: "any" | "all";
-    timeoutMs?: number;
-}> | Readonly<{
-    id: string;
-    action: "akuma.tell";
-    target: AkuId;
-    body: string;
-}> | Readonly<{
-    id: string;
-    action: "akuma.kill";
-    targets: readonly AkuId[];
-}> | Readonly<{
-    id: string;
-    action: "contract.deliver";
-    repoRoot: string;
-    contractId: string;
-    message?: string;
-    includeDirty: boolean;
-    materializeConflict: boolean;
-}> | Readonly<{
-    id: string;
-    action: "contract.review";
-    repoRoot: string;
-    contractId: string;
-    verdict: "satisfied" | "unsatisfied";
-    summary?: string;
-}> | TaskRequestInput;
-export type UpstreamRequestService = Readonly<{
-    action: "akuma.wait";
-}> | Readonly<{
-    action: "akuma.tell";
-    target: AkuId;
-    tellId: string;
-}> | Readonly<{
-    action: "akuma.kill";
-    results: readonly Readonly<{
-        id: AkuId;
-        evidence: KillEvidence;
-    }>[];
-}> | Readonly<{
-    action: "contract.deliver";
-    repoRoot: string;
-    contractId: string;
-    deliveryFactId: string;
-}> | Readonly<{
-    action: "contract.review";
-    repoRoot: string;
-    contractId: string;
-    reviewFactId: string;
-}> | Readonly<{
-    action: TaskMutationRequest["action"];
+    action: string;
+    payloadJson: string;
 }>;
 type AdmittedRequest = RequestInput & Readonly<{
     requester: AkuId;
@@ -199,21 +133,15 @@ type AdmittedRequest = RequestInput & Readonly<{
 }>;
 export type RequestFact = (AdmittedRequest & Readonly<{
     state: "admitted";
-}>) | (Extract<AdmittedRequest, {
-    action: "akuma.call";
-}> & Readonly<{
+}>) | (AdmittedRequest & Readonly<{
     state: "reserved";
     child: AkuId;
-}>) | (Extract<AdmittedRequest, {
-    action: "akuma.call";
-}> & Readonly<{
+}>) | (AdmittedRequest & Readonly<{
     state: "served";
     child: AkuId;
-}>) | (Exclude<AdmittedRequest, {
-    action: "akuma.call";
-}> & Readonly<{
+}>) | (AdmittedRequest & Readonly<{
     state: "served";
-    service: UpstreamRequestService;
+    serviceJson: string;
 }>) | (AdmittedRequest & Readonly<{
     state: "refused";
     diagnostic: string;

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

@@ -6,7 +6,7 @@ import { type ActivityFactSlice } from "./timeline.js";
 export { HeartAbsentError, HeldAkumaLeash, classifyHeartSchema, initializeHeart, isHeartAbsent, probeLeash, } from "./storage.js";
 export { admitRequest, isRequestInputConflict, readNonterminalRequests, readRequest, refuseRequest, reserveRequest, serveRequest, serveUpstreamRequest, voidRequest, } from "./request-authority.js";
 export { life, lifeAt } from "./facts.js";
-export type { AkumaLife, AkumaOrigin, BodyEnd, BodyFact, HeartSnapshot, ForkPoint, KillEvidence, KillFact, LeashProbe, PauseFact, RequestFact, RequestInput, RequestRecipe, UpstreamRequestService, SealFact, SessionFact, Soul, StopFact, TellFact, TellDelivery, TellDeliveryInput, TellReceiptInput, TurnEndFact, TurnFact, TurnOutcome, TurnStartFact, } from "./facts.js";
+export type { AkumaLife, AkumaOrigin, BodyEnd, BodyFact, HeartSnapshot, ForkPoint, KillEvidence, KillFact, LeashProbe, PauseFact, RequestFact, RequestInput, RequestRecipe, SealFact, SessionFact, Soul, StopFact, TellFact, TellDelivery, TellDeliveryInput, TellReceiptInput, TurnEndFact, TurnFact, TurnOutcome, TurnStartFact, } from "./facts.js";
 export type { ResumeCoordinate } from "../coordinate.js";
 export declare function readSoul(paths: AkumaPaths): Promise<Soul | null>;
 export declare function heartExists(paths: AkumaPaths): Promise<boolean>;

package/build/src/akuma/heart/request-authority.d.ts

@@ -1,12 +1,13 @@
-import type { AkuId, AkumaPaths } from "../identity.js";
-import type { RequestFact, RequestInput, UpstreamRequestService } from "./facts.js";
+import { type AkuId, type AkumaPaths } from "../identity.js";
+import type { RequestFact, RequestInput } from "./facts.js";
 export declare function isRequestInputConflict(error: unknown): error is Error;
 export declare function admitRequest(paths: AkumaPaths, input: RequestInput & Readonly<{
     admittedAt: string;
+    permitted: boolean;
 }>): Promise<RequestFact>;
 export declare function reserveRequest(paths: AkumaPaths, id: string, child: AkuId): Promise<RequestFact>;
-export declare function serveRequest(paths: AkumaPaths, id: string, child: AkuId): Promise<RequestFact>;
-export declare function serveUpstreamRequest(paths: AkumaPaths, id: string, service: UpstreamRequestService): Promise<RequestFact>;
+export declare function serveRequest(paths: AkumaPaths, id: string, child: string): Promise<RequestFact>;
+export declare function serveUpstreamRequest(paths: AkumaPaths, id: string, serviceJson: string): Promise<RequestFact>;
 export declare function refuseRequest(paths: AkumaPaths, id: string, diagnostic: string): Promise<RequestFact>;
 export declare function voidRequest(paths: AkumaPaths, id: string, evidence: string): Promise<RequestFact>;
 export declare function readRequest(paths: AkumaPaths, id: string): Promise<RequestFact | null>;

package/build/src/akuma/heart/request-authority.js

@@ -1,7 +1,7 @@
+import { parseAkuId } from "../identity.js";
 import { insertRequestFact, nonterminalRequestFacts, requestFact, updateRequestRefused, updateRequestReserved, updateRequestServed, updateRequestVoided, updateUpstreamRequestServed, } from "./request-rows.js";
 import { transaction, withHeart } from "./storage.js";
 import { soulFact } from "./soul.js";
-import { clipAllowedActions } from "../allowed.js";
 import { requestPayloadJson } from "./request-rows.js";
 // This stays out of the public Heart index: only transport service projects it as a refusal.
 class RequestInputConflictError extends Error {
@@ -18,31 +18,19 @@ export async function admitRequest(paths, input) {
         const soul = soulFact(heart);
         if (soul === null)
             throw new Error("Akuma request admission requires a born Soul");
-        const action = input.action;
-        const parentAllowed = soul.allowed;
-        const permitted = action === "akuma.wait" || parentAllowed.includes(action);
-        const normalized = input.action === "akuma.call"
-            ? {
-                ...input,
-                recipe: {
-                    ...input.recipe,
-                    allowed: permitted ? clipAllowedActions(input.recipe.allowed, parentAllowed) : input.recipe.allowed,
-                },
-            }
-            : input;
+        const { permitted, ...request } = input;
         insertRequestFact(heart, {
-            ...normalized,
+            ...request,
             requester: soul.id,
-            admittedAt: input.admittedAt,
-            ...(permitted ? {} : { refusal: `not-allowed: ${action}` }),
+            ...(permitted ? {} : { refusal: `not-allowed: ${input.action}` }),
         });
         const fact = requestFact(heart, input.id);
         if (fact === null)
             throw new Error(`Akuma request ${input.id} was not admitted`);
         if (fact.requester !== soul.id ||
-            fact.id !== normalized.id ||
-            fact.action !== normalized.action ||
-            requestPayloadJson(fact) !== requestPayloadJson(normalized)) {
+            fact.id !== input.id ||
+            fact.action !== input.action ||
+            requestPayloadJson(fact) !== requestPayloadJson(input)) {
             throw new RequestInputConflictError(input.id);
         }
         return fact;
@@ -53,43 +41,41 @@ export async function reserveRequest(paths, id, child) {
         const before = requestFact(heart, id);
         if (before === null)
             throw new Error(`unknown Akuma request ${id}`);
-        if (before.action !== "akuma.call")
-            throw new Error(`Akuma request ${id} cannot reserve a child`);
         if (before.state === "admitted")
             updateRequestReserved(heart, id, child);
-        else if ((before.state !== "reserved" && before.state !== "served") || before.child !== child) {
+        else if ((before.state !== "reserved" && before.state !== "served") ||
+            !("child" in before) ||
+            before.child !== child) {
             throw new Error(`Akuma request ${id} cannot reserve ${child}`);
         }
         return requestFact(heart, id);
     }));
 }
 export async function serveRequest(paths, id, child) {
+    const parsed = parseAkuId(child);
+    if (parsed.id !== child)
+        throw new Error(`Akuma request ${id} has a noncanonical child`);
     return await withHeart(paths, (heart) => transaction(heart, () => {
         const before = requestFact(heart, id);
         if (before === null)
             throw new Error(`unknown Akuma request ${id}`);
-        if (before.action !== "akuma.call")
-            throw new Error(`Akuma request ${id} cannot serve a child`);
-        if (before.state === "reserved" && before.child === child)
-            updateRequestServed(heart, id, child);
-        else if (before.state !== "served" || before.child !== child) {
+        if (before.state === "reserved" && before.child === parsed.id)
+            updateRequestServed(heart, id, parsed.id);
+        else if (before.state !== "served" || !("child" in before) || before.child !== parsed.id) {
             throw new Error(`Akuma request ${id} cannot serve ${child}`);
         }
         return requestFact(heart, id);
     }));
 }
-export async function serveUpstreamRequest(paths, id, service) {
+export async function serveUpstreamRequest(paths, id, serviceJson) {
     return await withHeart(paths, (heart) => transaction(heart, () => {
         const before = requestFact(heart, id);
         if (before === null)
             throw new Error(`unknown Akuma request ${id}`);
-        if (before.action === "akuma.call" || service.action !== before.action) {
-            throw new Error(`Akuma request ${id} has a mismatched service reference`);
-        }
         if (before.state === "admitted")
-            updateUpstreamRequestServed(heart, id, service);
-        else if (before.state !== "served") {
-            throw new Error(`Akuma request ${id} cannot be served as ${service.action}`);
+            updateUpstreamRequestServed(heart, id, serviceJson);
+        else if (before.state !== "served" || !("serviceJson" in before) || before.serviceJson !== serviceJson) {
+            throw new Error(`Akuma request ${id} cannot be served with this service reference`);
         }
         return requestFact(heart, id);
     }));

package/build/src/akuma/heart/request-rows.js

@@ -1,45 +1,34 @@
-import { isTaskMutationAction } from "../../task/mutation.js";
-function json(value) {
-    return JSON.stringify(value);
-}
-function parsed(value) {
+function assertJsonText(value) {
     if (typeof value !== "string")
         throw new Error("Akuma authority contains non-text JSON");
-    return JSON.parse(value);
+    JSON.parse(value);
+    return value;
 }
 export function requestPayloadJson(input) {
-    const { id: _id, action: _action, requester: _requester, admittedAt: _admittedAt, state: _state, child: _child, service: _service, diagnostic: _diagnostic, evidence: _evidence, refusal: _refusal, ...payload } = input;
-    return json(payload);
+    return assertJsonText(input.payloadJson);
 }
 function decodeRequestRow(row) {
-    const knownAction = ["akuma.call", "akuma.wait", "akuma.tell", "akuma.kill", "contract.deliver", "contract.review"].includes(row.action) || isTaskMutationAction(row.action);
-    if (!knownAction)
-        throw new Error(`Akuma authority contains an unknown request action: ${row.action}`);
-    const payload = parsed(row.payload_json);
     const input = {
         id: row.id,
         requester: row.requester,
         action: row.action,
-        ...payload,
+        payloadJson: assertJsonText(row.payload_json),
         admittedAt: row.admitted_at,
     };
     if (row.state === "reserved") {
-        if (input.action !== "akuma.call" || row.child === null) {
+        if (row.child === null || row.service_json !== null) {
             throw new Error("Akuma authority contains an invalid reserved request");
         }
         return { ...input, state: row.state, child: row.child };
     }
     if (row.state === "served") {
-        if (input.action === "akuma.call") {
-            if (row.child === null)
-                throw new Error("Akuma authority contains a served call without a child");
+        if (row.child !== null && row.service_json === null) {
             return { ...input, state: row.state, child: row.child };
         }
-        if (row.service_json === null) {
-            throw new Error("Akuma authority contains a served request without a service reference");
+        if (row.child === null && row.service_json !== null) {
+            return { ...input, state: row.state, serviceJson: assertJsonText(row.service_json) };
         }
-        const service = parsed(row.service_json);
-        return { ...input, state: row.state, service };
+        throw new Error("Akuma authority contains an invalid served request");
     }
     if (row.state === "refused")
         return { ...input, state: row.state, diagnostic: row.diagnostic };
@@ -82,8 +71,8 @@ export function updateRequestServed(database, id, child) {
 export function updateUpstreamRequestServed(database, id, service) {
     database
         .prepare(`UPDATE requests SET state = 'served', service_json = ?
-    WHERE id = ? AND state = 'admitted' AND action != 'akuma.call'`)
-        .run(json(service), id);
+    WHERE id = ? AND state = 'admitted'`)
+        .run(assertJsonText(service), id);
 }
 export function updateRequestRefused(database, id, diagnostic) {
     database

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

@@ -2,5 +2,5 @@ import type { DatabaseSync } from "node:sqlite";
 export declare function assertHeartSchemaVersion(database: DatabaseSync): void;
 export declare function assertLeashSchemaVersion(database: DatabaseSync): void;
 export declare function heartSchemaIsCurrent(database: DatabaseSync): boolean;
-export declare const HEART_SCHEMA = "\n  CREATE TABLE IF NOT EXISTS akuma_schema (\n    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),\n    version INTEGER NOT NULL CHECK (version = 20)\n  ) STRICT;\n  INSERT OR IGNORE INTO akuma_schema(singleton, version) VALUES (1, 20);\n  CREATE TABLE IF NOT EXISTS soul (\n    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),\n    soul_json TEXT NOT NULL CHECK (json_valid(soul_json))\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS bodies (\n    sequence INTEGER PRIMARY KEY AUTOINCREMENT,\n    leash_taken_at TEXT NOT NULL,\n    hung_diagnostic TEXT,\n    hung_at TEXT,\n    end TEXT CHECK (end IN ('exited', 'broke-off', 'put-down')),\n    ended_at TEXT,\n    CHECK ((hung_diagnostic IS NULL AND hung_at IS NULL)\n      OR (hung_diagnostic IS NOT NULL AND hung_at IS NOT NULL))\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS sessions (\n    sequence INTEGER PRIMARY KEY AUTOINCREMENT,\n    provider TEXT NOT NULL,\n    coordinate_json TEXT NOT NULL CHECK (json_valid(coordinate_json)),\n    cwd TEXT NOT NULL,\n    options_json TEXT NOT NULL CHECK (json_valid(options_json)),\n    admitted_at TEXT NOT NULL\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS turns (\n    sequence INTEGER PRIMARY KEY REFERENCES timeline(sequence) ON DELETE CASCADE,\n    body_sequence INTEGER NOT NULL REFERENCES bodies(sequence),\n    started_at TEXT NOT NULL,\n    end_sequence INTEGER UNIQUE REFERENCES timeline(sequence) ON DELETE SET NULL,\n    outcome TEXT CHECK (outcome IN ('answered', 'failed')),\n    history_id TEXT UNIQUE,\n    session_json TEXT CHECK (session_json IS NULL OR json_valid(session_json)),\n    answer TEXT,\n    diagnostic TEXT,\n    completed_at TEXT,\n    CHECK (\n      (outcome = 'answered' AND session_json IS NOT NULL AND answer IS NOT NULL AND diagnostic IS NULL)\n      OR (outcome = 'failed' AND history_id IS NULL AND session_json IS NULL AND answer IS NULL AND diagnostic IS NOT NULL)\n      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)\n    )\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS timeline (\n    sequence INTEGER PRIMARY KEY AUTOINCREMENT,\n    kind TEXT NOT NULL CHECK (kind IN ('turn-start', 'call', 'activity', 'tell', 'turn-end'))\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS calls (\n    sequence INTEGER PRIMARY KEY REFERENCES timeline(sequence) ON DELETE CASCADE,\n    turn_sequence INTEGER NOT NULL REFERENCES turns(sequence) ON DELETE CASCADE,\n    body TEXT NOT NULL,\n    at TEXT NOT NULL\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS activity (\n    sequence INTEGER PRIMARY KEY REFERENCES timeline(sequence) ON DELETE CASCADE,\n    turn_sequence INTEGER NOT NULL REFERENCES turns(sequence) ON DELETE CASCADE,\n    event_json TEXT NOT NULL CHECK (json_valid(event_json)),\n    at TEXT NOT NULL\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS tells (\n    id TEXT PRIMARY KEY,\n    sequence INTEGER NOT NULL UNIQUE REFERENCES timeline(sequence) ON DELETE CASCADE,\n    body TEXT NOT NULL,\n    recorded_at TEXT NOT NULL\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS tell_deliveries (\n    sequence INTEGER PRIMARY KEY AUTOINCREMENT,\n    tell_id TEXT NOT NULL REFERENCES tells(id) ON DELETE CASCADE,\n    route TEXT NOT NULL CHECK (route IN ('launch', 'live')),\n    turn_sequence INTEGER NOT NULL REFERENCES turns(sequence) ON DELETE CASCADE,\n    fence TEXT NOT NULL,\n    receipt TEXT CHECK (receipt IN ('unavailable', 'required')),\n    delivered_at TEXT NOT NULL,\n    CHECK ((route = 'launch' AND receipt IS NULL) OR (route = 'live' AND receipt IS NOT NULL)),\n    UNIQUE (tell_id, turn_sequence, fence)\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS tell_receipts (\n    sequence INTEGER PRIMARY KEY AUTOINCREMENT,\n    evidence TEXT NOT NULL CHECK (evidence IN ('exact', 'fence')),\n    tell_id TEXT REFERENCES tells(id) ON DELETE CASCADE,\n    turn_sequence INTEGER REFERENCES turns(sequence) ON DELETE CASCADE,\n    fence TEXT,\n    kind TEXT NOT NULL,\n    received_at TEXT NOT NULL,\n    CHECK (\n      (evidence = 'exact' AND tell_id IS NOT NULL AND turn_sequence IS NULL AND fence IS NULL)\n      OR (evidence = 'fence' AND tell_id IS NULL AND turn_sequence IS NOT NULL AND fence IS NOT NULL)\n    )\n  ) STRICT;\n  CREATE UNIQUE INDEX IF NOT EXISTS tell_receipts_exact\n    ON tell_receipts(tell_id, kind) WHERE evidence = 'exact';\n  CREATE UNIQUE INDEX IF NOT EXISTS tell_receipts_fence\n    ON tell_receipts(turn_sequence, fence, kind) WHERE evidence = 'fence';\n  CREATE TABLE IF NOT EXISTS requests (\n    sequence INTEGER PRIMARY KEY AUTOINCREMENT,\n    id TEXT NOT NULL UNIQUE,\n    requester TEXT NOT NULL,\n    action TEXT NOT NULL CHECK (\n      action IN (\n        'akuma.call', 'akuma.wait', 'akuma.tell', 'akuma.kill',\n        'contract.deliver', 'contract.review',\n        'task.add', 'task.addDocument', 'task.compose', 'task.update', 'task.start',\n        'task.stop', 'task.hold', 'task.resume', 'task.done', 'task.drop'\n      )\n    ),\n    payload_json TEXT NOT NULL CHECK (json_valid(payload_json)),\n    admitted_at TEXT NOT NULL,\n    state TEXT NOT NULL CHECK (state IN ('admitted', 'reserved', 'served', 'refused', 'voided')),\n    child TEXT,\n    service_json TEXT CHECK (service_json IS NULL OR json_valid(service_json)),\n    diagnostic TEXT,\n    evidence TEXT,\n    CHECK (\n      (state = 'admitted' AND child IS NULL AND service_json IS NULL AND diagnostic IS NULL AND evidence IS NULL)\n      OR (state = 'reserved' AND action = 'akuma.call'\n        AND child IS NOT NULL AND service_json IS NULL\n        AND diagnostic IS NULL AND evidence IS NULL)\n      OR (state = 'served'\n        AND ((action = 'akuma.call' AND child IS NOT NULL AND service_json IS NULL)\n          OR (action != 'akuma.call' AND child IS NULL AND service_json IS NOT NULL))\n        AND diagnostic IS NULL AND evidence IS NULL)\n      OR (state = 'refused' AND child IS NULL AND service_json IS NULL AND diagnostic IS NOT NULL AND evidence IS NULL)\n      OR (state = 'voided' AND child IS NULL AND service_json IS NULL AND diagnostic IS NULL AND evidence IS NOT NULL)\n    )\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS control (\n    kind TEXT PRIMARY KEY CHECK (kind IN ('stop', 'pause')),\n    value_json TEXT NOT NULL CHECK (json_valid(value_json)),\n    at TEXT NOT NULL\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS kills (\n    sequence INTEGER PRIMARY KEY AUTOINCREMENT,\n    body_sequence INTEGER NOT NULL UNIQUE REFERENCES bodies(sequence),\n    evidence TEXT NOT NULL CHECK (evidence = 'killed'),\n    at TEXT NOT NULL\n  ) STRICT;\n";
+export declare const HEART_SCHEMA = "\n  CREATE TABLE IF NOT EXISTS akuma_schema (\n    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),\n    version INTEGER NOT NULL CHECK (version = 21)\n  ) STRICT;\n  INSERT OR IGNORE INTO akuma_schema(singleton, version) VALUES (1, 21);\n  CREATE TABLE IF NOT EXISTS soul (\n    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),\n    soul_json TEXT NOT NULL CHECK (json_valid(soul_json))\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS bodies (\n    sequence INTEGER PRIMARY KEY AUTOINCREMENT,\n    leash_taken_at TEXT NOT NULL,\n    hung_diagnostic TEXT,\n    hung_at TEXT,\n    end TEXT CHECK (end IN ('exited', 'broke-off', 'put-down')),\n    ended_at TEXT,\n    CHECK ((hung_diagnostic IS NULL AND hung_at IS NULL)\n      OR (hung_diagnostic IS NOT NULL AND hung_at IS NOT NULL))\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS sessions (\n    sequence INTEGER PRIMARY KEY AUTOINCREMENT,\n    provider TEXT NOT NULL,\n    coordinate_json TEXT NOT NULL CHECK (json_valid(coordinate_json)),\n    cwd TEXT NOT NULL,\n    options_json TEXT NOT NULL CHECK (json_valid(options_json)),\n    admitted_at TEXT NOT NULL\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS turns (\n    sequence INTEGER PRIMARY KEY REFERENCES timeline(sequence) ON DELETE CASCADE,\n    body_sequence INTEGER NOT NULL REFERENCES bodies(sequence),\n    started_at TEXT NOT NULL,\n    end_sequence INTEGER UNIQUE REFERENCES timeline(sequence) ON DELETE SET NULL,\n    outcome TEXT CHECK (outcome IN ('answered', 'failed')),\n    history_id TEXT UNIQUE,\n    session_json TEXT CHECK (session_json IS NULL OR json_valid(session_json)),\n    answer TEXT,\n    diagnostic TEXT,\n    completed_at TEXT,\n    CHECK (\n      (outcome = 'answered' AND session_json IS NOT NULL AND answer IS NOT NULL AND diagnostic IS NULL)\n      OR (outcome = 'failed' AND history_id IS NULL AND session_json IS NULL AND answer IS NULL AND diagnostic IS NOT NULL)\n      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)\n    )\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS timeline (\n    sequence INTEGER PRIMARY KEY AUTOINCREMENT,\n    kind TEXT NOT NULL CHECK (kind IN ('turn-start', 'call', 'activity', 'tell', 'turn-end'))\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS calls (\n    sequence INTEGER PRIMARY KEY REFERENCES timeline(sequence) ON DELETE CASCADE,\n    turn_sequence INTEGER NOT NULL REFERENCES turns(sequence) ON DELETE CASCADE,\n    body TEXT NOT NULL,\n    at TEXT NOT NULL\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS activity (\n    sequence INTEGER PRIMARY KEY REFERENCES timeline(sequence) ON DELETE CASCADE,\n    turn_sequence INTEGER NOT NULL REFERENCES turns(sequence) ON DELETE CASCADE,\n    event_json TEXT NOT NULL CHECK (json_valid(event_json)),\n    at TEXT NOT NULL\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS tells (\n    id TEXT PRIMARY KEY,\n    sequence INTEGER NOT NULL UNIQUE REFERENCES timeline(sequence) ON DELETE CASCADE,\n    body TEXT NOT NULL,\n    recorded_at TEXT NOT NULL\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS tell_deliveries (\n    sequence INTEGER PRIMARY KEY AUTOINCREMENT,\n    tell_id TEXT NOT NULL REFERENCES tells(id) ON DELETE CASCADE,\n    route TEXT NOT NULL CHECK (route IN ('launch', 'live')),\n    turn_sequence INTEGER NOT NULL REFERENCES turns(sequence) ON DELETE CASCADE,\n    fence TEXT NOT NULL,\n    receipt TEXT CHECK (receipt IN ('unavailable', 'required')),\n    delivered_at TEXT NOT NULL,\n    CHECK ((route = 'launch' AND receipt IS NULL) OR (route = 'live' AND receipt IS NOT NULL)),\n    UNIQUE (tell_id, turn_sequence, fence)\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS tell_receipts (\n    sequence INTEGER PRIMARY KEY AUTOINCREMENT,\n    evidence TEXT NOT NULL CHECK (evidence IN ('exact', 'fence')),\n    tell_id TEXT REFERENCES tells(id) ON DELETE CASCADE,\n    turn_sequence INTEGER REFERENCES turns(sequence) ON DELETE CASCADE,\n    fence TEXT,\n    kind TEXT NOT NULL,\n    received_at TEXT NOT NULL,\n    CHECK (\n      (evidence = 'exact' AND tell_id IS NOT NULL AND turn_sequence IS NULL AND fence IS NULL)\n      OR (evidence = 'fence' AND tell_id IS NULL AND turn_sequence IS NOT NULL AND fence IS NOT NULL)\n    )\n  ) STRICT;\n  CREATE UNIQUE INDEX IF NOT EXISTS tell_receipts_exact\n    ON tell_receipts(tell_id, kind) WHERE evidence = 'exact';\n  CREATE UNIQUE INDEX IF NOT EXISTS tell_receipts_fence\n    ON tell_receipts(turn_sequence, fence, kind) WHERE evidence = 'fence';\n  CREATE TABLE IF NOT EXISTS requests (\n    sequence INTEGER PRIMARY KEY AUTOINCREMENT,\n    id TEXT NOT NULL UNIQUE,\n    requester TEXT NOT NULL,\n    action TEXT NOT NULL,\n    payload_json TEXT NOT NULL CHECK (json_valid(payload_json)),\n    admitted_at TEXT NOT NULL,\n    state TEXT NOT NULL CHECK (state IN ('admitted', 'reserved', 'served', 'refused', 'voided')),\n    child TEXT,\n    service_json TEXT CHECK (service_json IS NULL OR json_valid(service_json)),\n    diagnostic TEXT,\n    evidence TEXT,\n    CHECK (\n      (state = 'admitted' AND child IS NULL AND service_json IS NULL AND diagnostic IS NULL AND evidence IS NULL)\n      OR (state = 'reserved' AND child IS NOT NULL AND service_json IS NULL\n        AND diagnostic IS NULL AND evidence IS NULL)\n      OR (state = 'served'\n        AND ((child IS NOT NULL AND service_json IS NULL)\n          OR (child IS NULL AND service_json IS NOT NULL))\n        AND diagnostic IS NULL AND evidence IS NULL)\n      OR (state = 'refused' AND child IS NULL AND service_json IS NULL AND diagnostic IS NOT NULL AND evidence IS NULL)\n      OR (state = 'voided' AND child IS NULL AND service_json IS NULL AND diagnostic IS NULL AND evidence IS NOT NULL)\n    )\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS control (\n    kind TEXT PRIMARY KEY CHECK (kind IN ('stop', 'pause')),\n    value_json TEXT NOT NULL CHECK (json_valid(value_json)),\n    at TEXT NOT NULL\n  ) STRICT;\n  CREATE TABLE IF NOT EXISTS kills (\n    sequence INTEGER PRIMARY KEY AUTOINCREMENT,\n    body_sequence INTEGER NOT NULL UNIQUE REFERENCES bodies(sequence),\n    evidence TEXT NOT NULL CHECK (evidence = 'killed'),\n    at TEXT NOT NULL\n  ) STRICT;\n";
 export declare const LEASH_SCHEMA = "\n  PRAGMA journal_mode=DELETE;\n  CREATE TABLE IF NOT EXISTS leash_schema (\n    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),\n    version INTEGER NOT NULL CHECK (version = 4)\n  ) STRICT;\n  INSERT OR IGNORE INTO leash_schema(singleton, version) VALUES (1, 4);\n  CREATE TABLE IF NOT EXISTS seal (\n    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),\n    evidence TEXT NOT NULL,\n    at TEXT NOT NULL\n  ) STRICT;\n";

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

@@ -1,4 +1,4 @@
-const HEART_SCHEMA_VERSION = 20;
+const HEART_SCHEMA_VERSION = 21;
 const LEASH_SCHEMA_VERSION = 4;
 function assertSchemaVersion(database, table, expected) {
     const row = database.prepare(`SELECT version FROM ${table} WHERE singleton = 1`).get();
@@ -119,14 +119,7 @@ export const HEART_SCHEMA = `
     sequence INTEGER PRIMARY KEY AUTOINCREMENT,
     id TEXT NOT NULL UNIQUE,
     requester TEXT NOT NULL,
-    action TEXT NOT NULL CHECK (
-      action IN (
-        'akuma.call', 'akuma.wait', 'akuma.tell', 'akuma.kill',
-        'contract.deliver', 'contract.review',
-        'task.add', 'task.addDocument', 'task.compose', 'task.update', 'task.start',
-        'task.stop', 'task.hold', 'task.resume', 'task.done', 'task.drop'
-      )
-    ),
+    action TEXT NOT NULL,
     payload_json TEXT NOT NULL CHECK (json_valid(payload_json)),
     admitted_at TEXT NOT NULL,
     state TEXT NOT NULL CHECK (state IN ('admitted', 'reserved', 'served', 'refused', 'voided')),
@@ -136,12 +129,11 @@ export const HEART_SCHEMA = `
     evidence TEXT,
     CHECK (
       (state = 'admitted' AND child IS NULL AND service_json IS NULL AND diagnostic IS NULL AND evidence IS NULL)
-      OR (state = 'reserved' AND action = 'akuma.call'
-        AND child IS NOT NULL AND service_json IS NULL
+      OR (state = 'reserved' AND child IS NOT NULL AND service_json IS NULL
         AND diagnostic IS NULL AND evidence IS NULL)
       OR (state = 'served'
-        AND ((action = 'akuma.call' AND child IS NOT NULL AND service_json IS NULL)
-          OR (action != 'akuma.call' AND child IS NULL AND service_json IS NOT NULL))
+        AND ((child IS NOT NULL AND service_json IS NULL)
+          OR (child IS NULL AND service_json IS NOT NULL))
         AND diagnostic IS NULL AND evidence IS NULL)
       OR (state = 'refused' AND child IS NULL AND service_json IS NULL AND diagnostic IS NOT NULL AND evidence IS NULL)
       OR (state = 'voided' AND child IS NULL AND service_json IS NULL AND diagnostic IS NULL AND evidence IS NOT NULL)

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

@@ -1,6 +1,6 @@
 import { type AkuId } from "./identity.js";
 import type { WorldRoot } from "../world.js";
-export { Akuma, AkumaHandle, AkumaNotBornError, defaultWaitComplete } from "./akuma.js";
+export { Akuma, AkumaHandle, AkumaNotBornError, akumaIdSchema, akumaStatusSchema, defaultWaitComplete, parseAkumaStatus, } from "./akuma.js";
 export type { AkumaCallInput } from "./akuma.js";
 export { ALLOWED_ACTIONS } from "./allowed.js";
 export type { AllowedAction, AllowedActions } from "./allowed.js";

package/build/src/akuma/index.js

@@ -1,6 +1,6 @@
 import { readSoul } from "./heart/index.js";
 import { pathsForAkuId } from "./identity.js";
-export { Akuma, AkumaHandle, AkumaNotBornError, defaultWaitComplete } from "./akuma.js";
+export { Akuma, AkumaHandle, AkumaNotBornError, akumaIdSchema, akumaStatusSchema, defaultWaitComplete, parseAkumaStatus, } from "./akuma.js";
 export { ALLOWED_ACTIONS } from "./allowed.js";
 export async function probeBornAkuma(worldPath, id) {
     const soul = await readSoul(pathsForAkuId(worldPath, id));

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

@@ -10,6 +10,7 @@ export declare function selectSnapshot(ledger: TurnLedger, input: Readonly<{
         tail: number;
         voice?: number;
     }>;
+    admittedTellId?: string;
 }>): Readonly<{
     snapshot: ActivitySnapshot;
     ordinaryCount: number;

package/build/src/akuma/projection-read.js

@@ -76,7 +76,14 @@ export function selectSnapshot(ledger, input) {
         return { snapshot: { kind: "unborn", entries: [], omitted: 0, ...EMPTY_REPORTED }, ordinaryCount: 0 };
     const pending = ledger.rows.filter(isPendingTell);
     const latestTold = input.aperture === "monitoring" ? ledger.rows.findLast(isToldTell) : undefined;
-    const pins = latestTold === undefined ? pending : [...pending, latestTold];
+    const admittedTell = input.aperture === "receipt" && input.admittedTellId !== undefined
+        ? ledger.rows.find((row) => row.kind === "tell" && row.tellId === input.admittedTellId)
+        : undefined;
+    const pins = input.aperture === "receipt" && input.admittedTellId !== undefined
+        ? admittedTell === undefined
+            ? []
+            : [admittedTell]
+        : [...pending, ...(latestTold === undefined ? [] : [latestTold])];
     const reported = frontierReportedChanges(ledger);
     if (ledger.openTurn !== undefined) {
         const window = ledger.openTurn.rows;