@astrosheep/keiyaku 4.0.4 → 4.0.6

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

@@ -0,0 +1,484 @@
+import { access, mkdir, readFile, readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { abortableDelay } from "./abort.js";
+import { HeldAkumaLeash, admitRequest, readNonterminalRequests, readRequest, readSoul, refuseRequest, reserveRequest, serveRequest, serveUpstreamRequest, voidRequest, } from "./heart/index.js";
+import { pathsForAkuId, worldRootForAkumaPaths, } from "./identity.js";
+import { BIRTH_TIMEOUT_MS, publishAkuma } from "./publication.js";
+import { atomicJson, canonicalAkuId, decodeClaim, decodeRecipe, receiptPath, } from "./request-wire.js";
+import { isTaskMutationAction } from "../task/mutation.js";
+const POLL_MS = 25;
+function diagnostic(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isTask(value) {
+    return isTaskMutationAction(value.action);
+}
+function acceptedReceipt(fact, service) {
+    return {
+        id: fact.id,
+        action: fact.action,
+        state: fact.state,
+        reference: service.action === "contract.deliver"
+            ? {
+                kind: "accepted-reference",
+                repoRoot: service.repoRoot,
+                contractId: service.contractId,
+                deliveryFactId: service.deliveryFactId,
+            }
+            : {
+                kind: "accepted-reference",
+                repoRoot: service.repoRoot,
+                contractId: service.contractId,
+                reviewFactId: service.reviewFactId,
+            },
+    };
+}
+function receiptFor(fact) {
+    if (fact.state === "refused") {
+        return { id: fact.id, action: fact.action, state: fact.state, diagnostic: fact.diagnostic };
+    }
+    if (fact.state === "voided") {
+        return { id: fact.id, action: fact.action, state: fact.state, evidence: fact.evidence };
+    }
+    if (fact.action === "akuma.call" && fact.state === "served") {
+        return { id: fact.id, action: fact.action, state: fact.state, child: fact.child };
+    }
+    if (fact.state !== "served")
+        return null;
+    if (fact.action === "contract.deliver") {
+        return acceptedReceipt(fact, fact.service);
+    }
+    if (fact.action === "contract.review") {
+        return acceptedReceipt(fact, fact.service);
+    }
+    if (isTask(fact)) {
+        return {
+            id: fact.id,
+            action: fact.action,
+            state: fact.state,
+            reference: { kind: "served-reference", action: fact.action },
+        };
+    }
+    return null;
+}
+async function projectReceipt(directory, fact, outcome) {
+    const receipt = outcome === undefined
+        ? receiptFor(fact)
+        : fact.action === "akuma.call"
+            ? null
+            : { id: fact.id, action: fact.action, state: "served", outcome };
+    if (receipt === null)
+        return;
+    try {
+        await atomicJson(receiptPath(directory, fact.id), receipt);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+async function serveCall(input) {
+    input.signal.throwIfAborted();
+    if (!input.admissionOpen())
+        return;
+    const recipe = decodeRecipe(input.claim.recipe);
+    if (recipe === null)
+        return;
+    let fact = await admitRequest(input.paths, { ...input.claim, recipe, admittedAt: input.now() });
+    const existing = receiptFor(fact);
+    if (existing !== null) {
+        await projectReceipt(input.directory, fact);
+        return;
+    }
+    if (!input.admissionOpen()) {
+        fact = await voidRequest(input.paths, input.claim.id, "body closed request admission");
+        await projectReceipt(input.directory, fact);
+        return;
+    }
+    if (fact.action !== "akuma.call" || fact.state !== "admitted") {
+        throw new Error(`Akuma request ${fact.id} cannot be replayed from ${fact.state}`);
+    }
+    const request = fact;
+    const world = worldRootForAkumaPaths(input.paths);
+    if (request.world !== world) {
+        fact = await refuseRequest(input.paths, request.id, `request world ${request.world} does not match ${world}`);
+        await projectReceipt(input.directory, fact);
+        return;
+    }
+    try {
+        const published = await publishAkuma({
+            worldPath: world,
+            archetype: request.archetype,
+            signal: input.signal,
+            reserve: async (allocated) => {
+                if (!input.admissionOpen())
+                    throw new Error("body closed request admission");
+                fact = await reserveRequest(input.paths, request.id, allocated.id);
+            },
+            launch: async (allocated) => {
+                if (!input.admissionOpen())
+                    throw new Error("body closed request admission");
+                await input.spawn({
+                    paths: allocated.paths,
+                    seed: {
+                        id: allocated.id,
+                        archetype: allocated.archetype,
+                        ...(request.recipe.description === undefined
+                            ? {}
+                            : { description: request.recipe.description }),
+                        provider: request.recipe.provider,
+                        options: request.recipe.options,
+                        ...(request.recipe.readonly === undefined
+                            ? {}
+                            : { readonly: request.recipe.readonly }),
+                        allowed: request.recipe.allowed,
+                        cwd: request.cwd ?? input.parent.cwd,
+                        origin: {
+                            kind: "request",
+                            parent: input.parent.id,
+                            requestId: request.id,
+                        },
+                    },
+                    initialBody: request.body,
+                });
+            },
+        });
+        fact = await serveRequest(input.paths, request.id, published.id);
+    }
+    catch (error) {
+        const current = await readRequest(input.paths, request.id);
+        if (current === null)
+            throw error;
+        fact = current.state === "admitted" || current.state === "reserved"
+            ? await voidRequest(input.paths, request.id, diagnostic(error))
+            : current;
+    }
+    await projectReceipt(input.directory, fact);
+}
+function failure(error) {
+    const value = error !== null && typeof error === "object" ? error : null;
+    if (value?.kind === "akuma-not-born") {
+        const id = canonicalAkuId(value.id);
+        if (id !== null)
+            return { kind: "akuma-not-born", id };
+    }
+    return { kind: "failed", diagnostic: diagnostic(error) };
+}
+async function execute(input, request) {
+    if (input.upstream === undefined)
+        throw new Error("upstream execution port is unavailable");
+    if (request.action === "akuma.wait") {
+        const result = await input.upstream.wait({
+            targets: request.targets,
+            completion: request.completion,
+            ...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
+            signal: input.signal,
+        });
+        return { result, service: { action: request.action } };
+    }
+    if (request.action === "akuma.tell") {
+        const result = await input.upstream.tell({
+            target: request.target,
+            body: request.body,
+            tellId: request.id,
+            recordedAt: request.admittedAt,
+            signal: input.signal,
+        });
+        return {
+            result,
+            service: { action: request.action, target: request.target, tellId: request.id },
+        };
+    }
+    if (request.action === "akuma.kill") {
+        const served = await input.upstream.kill({
+            targets: request.targets,
+            signal: input.signal,
+        });
+        return {
+            result: served.result,
+            service: { action: request.action, results: served.service },
+        };
+    }
+    if (request.action === "contract.deliver") {
+        return await executeDeliver(input, request);
+    }
+    if (request.action === "contract.review") {
+        return await executeReview(input, request);
+    }
+    const task = request;
+    const result = await input.upstream.task({
+        world: task.world,
+        request: task.request,
+        requester: task.requester,
+        signal: input.signal,
+    });
+    return { result, service: { action: task.action } };
+}
+async function executeDeliver(input, request) {
+    if (input.upstream === undefined)
+        throw new Error("upstream execution port is unavailable");
+    const served = await input.upstream.deliver({
+        repoRoot: request.repoRoot,
+        contractId: request.contractId,
+        ...(request.message === undefined ? {} : { message: request.message }),
+        includeDirty: request.includeDirty,
+        materializeConflict: request.materializeConflict,
+        requester: request.requester,
+        signal: input.signal,
+    });
+    return {
+        result: served.result,
+        ...(served.deliveryFactId === undefined ? {} : {
+            service: {
+                action: request.action,
+                repoRoot: request.repoRoot,
+                contractId: request.contractId,
+                deliveryFactId: served.deliveryFactId,
+            },
+        }),
+    };
+}
+async function executeReview(input, request) {
+    if (input.upstream === undefined)
+        throw new Error("upstream execution port is unavailable");
+    const served = await input.upstream.review({
+        repoRoot: request.repoRoot,
+        contractId: request.contractId,
+        verdict: request.verdict,
+        ...(request.summary === undefined ? {} : { summary: request.summary }),
+        requester: request.requester,
+        signal: input.signal,
+    });
+    return {
+        result: served.result,
+        ...(served.reviewFactId === undefined ? {} : {
+            service: {
+                action: request.action,
+                repoRoot: request.repoRoot,
+                contractId: request.contractId,
+                reviewFactId: served.reviewFactId,
+            },
+        }),
+    };
+}
+function pendingService(request) {
+    if (request.action === "akuma.wait")
+        return { action: request.action };
+    if (request.action === "akuma.tell") {
+        return { action: request.action, target: request.target, tellId: request.id };
+    }
+    return request.action === "akuma.kill" ? { action: request.action, results: [] } : undefined;
+}
+async function serveUpstream(input) {
+    input.signal.throwIfAborted();
+    let fact = await admitRequest(input.paths, {
+        ...input.claim,
+        admittedAt: input.now(),
+    });
+    const existing = receiptFor(fact);
+    if (existing !== null) {
+        await projectReceipt(input.directory, fact);
+        return;
+    }
+    if (fact.state === "served") {
+        await projectReceipt(input.directory, fact, {
+            kind: "failed",
+            failure: {
+                kind: "failed",
+                diagnostic: "served request receipt is no longer available",
+            },
+        });
+        return;
+    }
+    if (!input.admissionOpen()) {
+        fact = await voidRequest(input.paths, input.claim.id, "body closed request admission");
+        await projectReceipt(input.directory, fact);
+        return;
+    }
+    if (fact.state !== "admitted" || fact.action === "akuma.call") {
+        throw new Error(`Akuma request ${fact.id} cannot be served from ${fact.state}`);
+    }
+    const request = fact;
+    let outcome;
+    let service = pendingService(request);
+    try {
+        const served = await execute(input, request);
+        outcome = { kind: "returned", result: served.result };
+        if (served.service !== undefined)
+            service = served.service;
+    }
+    catch (error) {
+        outcome = { kind: "failed", failure: failure(error) };
+        fact = await voidRequest(input.paths, request.id, "body failed before serving the request");
+        await projectReceipt(input.directory, fact);
+        return;
+    }
+    fact = service === undefined
+        ? await voidRequest(input.paths, request.id, "body completed without a durable Contract fact reference")
+        : await serveUpstreamRequest(input.paths, request.id, service);
+    await projectReceipt(input.directory, fact, outcome);
+}
+async function serve(input) {
+    return input.claim.action === "akuma.call"
+        ? await serveCall({ ...input, claim: input.claim })
+        : await serveUpstream({ ...input, claim: input.claim });
+}
+async function requestFiles(directory) {
+    try {
+        return (await readdir(directory))
+            .filter((name) => name.endsWith(".request.json"))
+            .sort();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+export class BodyRequestPump {
+    input;
+    directory;
+    failure;
+    closeSignal = new AbortController();
+    executionSignal = new AbortController();
+    handled = new Set();
+    running;
+    cancelBody;
+    admissionClosed = false;
+    constructor(input) {
+        this.input = input;
+        this.directory = join(input.paths.directory, "requests", String(input.bodySequence));
+        this.cancelBody = () => {
+            this.stopAdmission();
+            if (!this.executionSignal.signal.aborted) {
+                this.executionSignal.abort(input.signal.reason);
+            }
+        };
+        input.signal.addEventListener("abort", this.cancelBody, { once: true });
+        if (input.signal.aborted)
+            this.cancelBody();
+        this.running = this.run();
+        this.failure = this.running.then(() => new Promise(() => { }), (error) => Promise.reject(error));
+    }
+    static async open(input) {
+        await mkdir(join(input.paths.directory, "requests", String(input.bodySequence)), { recursive: true });
+        return new BodyRequestPump(input);
+    }
+    async run() {
+        while (!this.closeSignal.signal.aborted) {
+            for (const name of await requestFiles(this.directory)) {
+                if (this.closeSignal.signal.aborted)
+                    return;
+                const id = name.slice(0, -".request.json".length);
+                if (this.handled.has(id))
+                    continue;
+                const path = join(this.directory, name);
+                const claim = decodeClaim(await readFile(path, "utf8"), id);
+                if (claim === null) {
+                    await rm(path, { force: true });
+                    this.handled.add(id);
+                    continue;
+                }
+                if (!this.admissionClosed) {
+                    await serve({
+                        directory: this.directory,
+                        claim,
+                        ...this.input,
+                        signal: this.executionSignal.signal,
+                        admissionOpen: () => !this.admissionClosed,
+                    });
+                }
+                this.handled.add(id);
+            }
+            try {
+                await abortableDelay(POLL_MS, this.closeSignal.signal);
+            }
+            catch (error) {
+                if (this.closeSignal.signal.aborted)
+                    return;
+                throw error;
+            }
+        }
+    }
+    async close() {
+        this.stopAdmission();
+        try {
+            await this.running;
+        }
+        finally {
+            this.input.signal.removeEventListener("abort", this.cancelBody);
+            await rm(this.directory, { recursive: true, force: true });
+        }
+    }
+    stopAdmission() {
+        this.admissionClosed = true;
+        if (!this.closeSignal.signal.aborted) {
+            this.closeSignal.abort(new Error("Body request pump closed"));
+        }
+    }
+}
+export async function clearBodyRequestTransport(paths) {
+    await rm(join(paths.directory, "requests"), { recursive: true, force: true });
+}
+function matchingRequestOrigin(soul, parent, id) {
+    return soul.origin.kind === "request"
+        && soul.origin.parent === parent
+        && soul.origin.requestId === id;
+}
+async function settleReservedSoul(paths, parent, request, soul) {
+    await (matchingRequestOrigin(soul, parent.id, request.id)
+        ? serveRequest(paths, request.id, request.child)
+        : voidRequest(paths, request.id, "reserved child origin does not match the request"));
+}
+async function settleReserved(paths, parent, request, now, signal) {
+    const childPaths = pathsForAkuId(request.world, request.child);
+    const deadline = performance.now() + BIRTH_TIMEOUT_MS;
+    for (;;) {
+        signal?.throwIfAborted();
+        if (!await access(childPaths.directory).then(() => true, () => false)) {
+            await voidRequest(paths, request.id, "reserved child directory is absent");
+            return true;
+        }
+        const soul = await readSoul(childPaths);
+        if (soul !== null) {
+            await settleReservedSoul(paths, parent, request, soul);
+            return true;
+        }
+        const leash = await HeldAkumaLeash.try(childPaths);
+        if (leash !== null) {
+            try {
+                const settled = await readSoul(childPaths);
+                if (settled !== null) {
+                    await settleReservedSoul(paths, parent, request, settled);
+                }
+                else {
+                    await leash.sealIfUnborn(childPaths, {
+                        evidence: "request settlement",
+                        at: now(),
+                    });
+                    await voidRequest(paths, request.id, "reserved child was sealed unborn");
+                }
+            }
+            finally {
+                leash.release();
+            }
+            return true;
+        }
+        if (performance.now() >= deadline)
+            return false;
+        await abortableDelay(POLL_MS, signal);
+    }
+}
+export async function settleBodyRequests(paths, parent, now, signal) {
+    let pending = false;
+    for (const request of await readNonterminalRequests(paths)) {
+        signal?.throwIfAborted();
+        if (request.state === "admitted") {
+            await voidRequest(paths, request.id, "body died before serving the request");
+        }
+        else if (request.state === "reserved"
+            && !await settleReserved(paths, parent, request, now, signal))
+            pending = true;
+    }
+    return pending ? "pending" : "settled";
+}

package/build/src/akuma/request-wire.d.ts

@@ -0,0 +1,125 @@
+import { type AkuId } from "./identity.js";
+import { decodeProviderOptions, type ReadonlyRestraint } from "./provider-recipe.js";
+import { decodeProviderExecution } from "./providers/index.js";
+import { type TaskMutationAction, type TaskMutationRequest } from "../task/mutation.js";
+export type RequestRecipe = Readonly<{
+    description?: string;
+    allowed: readonly string[];
+    provider: ReturnType<typeof decodeProviderExecution>;
+    options: ReturnType<typeof decodeProviderOptions>;
+    readonly?: ReadonlyRestraint;
+}>;
+export type CallRequestClaim = Readonly<{
+    id: string;
+    action: "akuma.call";
+    world: string;
+    archetype: string;
+    body: string;
+    cwd?: string;
+    recipe: RequestRecipe;
+}>;
+export type WaitRequestClaim = Readonly<{
+    id: string;
+    action: "akuma.wait";
+    targets: readonly AkuId[];
+    completion: "any" | "all";
+    timeoutMs?: number;
+}>;
+export type TellRequestClaim = Readonly<{
+    id: string;
+    action: "akuma.tell";
+    target: AkuId;
+    body: string;
+}>;
+export type KillRequestClaim = Readonly<{
+    id: string;
+    action: "akuma.kill";
+    targets: readonly AkuId[];
+}>;
+export type DeliverRequestClaim = Readonly<{
+    id: string;
+    action: "contract.deliver";
+    repoRoot: string;
+    contractId: string;
+    message?: string;
+    includeDirty: boolean;
+    materializeConflict: boolean;
+}>;
+export type ReviewRequestClaim = Readonly<{
+    id: string;
+    action: "contract.review";
+    repoRoot: string;
+    contractId: string;
+    verdict: "satisfied" | "unsatisfied";
+    summary?: string;
+}>;
+export type TaskRequestClaim = Readonly<{
+    id: string;
+    action: TaskMutationAction;
+    world: string;
+    request: TaskMutationRequest;
+}>;
+export type RequestClaim = CallRequestClaim | WaitRequestClaim | TellRequestClaim | KillRequestClaim | DeliverRequestClaim | ReviewRequestClaim | TaskRequestClaim;
+export type StructuralRequestClaim = Omit<CallRequestClaim, "recipe"> & Readonly<{
+    recipe: unknown;
+}> | Exclude<RequestClaim, CallRequestClaim>;
+export type UpstreamRequestFailure = Readonly<{
+    kind: "akuma-not-born";
+    id: AkuId;
+}> | Readonly<{
+    kind: "failed";
+    diagnostic: string;
+}>;
+export type UpstreamRequestOutcome = Readonly<{
+    kind: "returned";
+    result: unknown;
+}> | Readonly<{
+    kind: "failed";
+    failure: UpstreamRequestFailure;
+}>;
+export type ForwardedDeliveryReference = Readonly<{
+    kind: "accepted-reference";
+    repoRoot: string;
+    contractId: string;
+    deliveryFactId: string;
+}>;
+export type ForwardedReviewReference = Readonly<{
+    kind: "accepted-reference";
+    repoRoot: string;
+    contractId: string;
+    reviewFactId: string;
+}>;
+export type ForwardedTaskReference = Readonly<{
+    kind: "served-reference";
+    action: TaskMutationAction;
+}>;
+type ReceiptBase<A extends RequestClaim["action"], S extends string> = Readonly<{
+    id: string;
+    action: A;
+    state: S;
+}>;
+export type RequestReceipt = (ReceiptBase<"akuma.call", "served"> & Readonly<{
+    child: AkuId;
+}>) | (ReceiptBase<"contract.deliver", "served"> & Readonly<{
+    reference: ForwardedDeliveryReference;
+}>) | (ReceiptBase<"contract.review", "served"> & Readonly<{
+    reference: ForwardedReviewReference;
+}>) | (ReceiptBase<TaskMutationAction, "served"> & Readonly<{
+    reference: ForwardedTaskReference;
+}>) | (ReceiptBase<Exclude<RequestClaim["action"], "akuma.call">, "served"> & Readonly<{
+    outcome: UpstreamRequestOutcome;
+}>) | (ReceiptBase<RequestClaim["action"], "refused"> & Readonly<{
+    diagnostic: string;
+}>) | (ReceiptBase<RequestClaim["action"], "voided"> & Readonly<{
+    evidence: string;
+}>);
+export declare function absolute(value: unknown): value is string;
+export declare function canonicalAkuId(value: unknown): AkuId | null;
+export declare function decodeRecipe(value: unknown): RequestRecipe | null;
+export declare function decodeClaim(bytes: string, fileId: string): StructuralRequestClaim | null;
+export declare function decodeReceipt(bytes: string, id: string, action: RequestClaim["action"]): RequestReceipt | null;
+export declare function requestPayload(claim: RequestClaim): unknown;
+export declare function requestPath(directory: string, id: string): string;
+export declare function receiptPath(directory: string, id: string): string;
+export declare function atomicJson(path: string, value: unknown): Promise<void>;
+export {};