@astrosheep/keiyaku 2.9.13 → 4.0.0

package/build/src/akuma/publication.js

@@ -0,0 +1,107 @@
+import { HeldAkumaLeash, initializeHeart, readHeart, readSoul, } from "./heart/index.js";
+import { allocateAkumaDirectory, } from "./identity.js";
+import { probeProcessTree } from "../runtime/proc/run.js";
+const POLL_MS = 25;
+export const BIRTH_TIMEOUT_MS = 5_000;
+function wait(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function diagnostic(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function settleTimedOutBirth(paths) {
+    const leash = HeldAkumaLeash.try(paths);
+    if (leash === null)
+        return null;
+    const result = leash.sealIfUnborn(paths, { evidence: "call-timeout", at: new Date().toISOString() });
+    if (result === "sealed")
+        throw new Error("Akuma body failed before birth");
+    leash.release();
+    const soul = readSoul(paths);
+    if (soul === null)
+        throw new Error("Akuma birth settled without a soul");
+    return soul;
+}
+async function awaitBirth(paths) {
+    const deadline = performance.now() + BIRTH_TIMEOUT_MS;
+    for (;;) {
+        const soul = readSoul(paths);
+        if (soul !== null)
+            return soul;
+        if (performance.now() >= deadline) {
+            const settled = settleTimedOutBirth(paths);
+            if (settled !== null)
+                return settled;
+        }
+        await wait(POLL_MS);
+    }
+}
+async function takeLeashUntil(paths, deadline) {
+    for (;;) {
+        const leash = HeldAkumaLeash.try(paths);
+        if (leash !== null)
+            return leash;
+        if (performance.now() >= deadline)
+            return null;
+        await wait(POLL_MS);
+    }
+}
+async function awaitAsleepBirth(paths, collar) {
+    const leash = await takeLeashUntil(paths, performance.now() + BIRTH_TIMEOUT_MS);
+    if (leash === null)
+        throw new Error("Forked Akuma did not finish its birth body");
+    try {
+        if (readHeart(paths).latestBody?.end !== "exited") {
+            throw new Error("Forked Akuma birth body did not exit cleanly");
+        }
+    }
+    finally {
+        leash.release();
+    }
+    const deadline = performance.now() + BIRTH_TIMEOUT_MS;
+    for (;;) {
+        const probe = probeProcessTree(collar);
+        if (probe.kind === "gone")
+            return;
+        if (performance.now() >= deadline) {
+            if (probe.kind === "unverifiable") {
+                throw new Error(`Forked Akuma birth collar is unverifiable: ${probe.diagnostic}`);
+            }
+            throw new Error("Forked Akuma birth process did not exit");
+        }
+        await wait(POLL_MS);
+    }
+}
+function sealLocalFailure(allocated, error) {
+    try {
+        const leash = HeldAkumaLeash.try(allocated.paths);
+        if (leash === null)
+            return;
+        try {
+            leash.sealIfUnborn(allocated.paths, { evidence: diagnostic(error), at: new Date().toISOString() });
+        }
+        finally {
+            leash.release();
+        }
+    }
+    catch { /* the original local publication failure remains authoritative */ }
+}
+export async function publishAkuma(input) {
+    const allocated = allocateAkumaDirectory({ worldRoot: input.worldPath, archetype: input.archetype });
+    let collar;
+    try {
+        initializeHeart(allocated.paths);
+        input.reserve?.(allocated);
+        collar = await input.launch(allocated);
+    }
+    catch (error) {
+        sealLocalFailure(allocated, error);
+        throw error;
+    }
+    const soul = await awaitBirth(allocated.paths);
+    if (soul.id !== allocated.id)
+        throw new Error("Akuma birth returned a different identity");
+    if (input.awaitAsleep === true)
+        await awaitAsleepBirth(allocated.paths, collar);
+    return allocated;
+}

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

@@ -0,0 +1,46 @@
+import { type RequestRecipe, type Soul } from "./heart/index.js";
+import { type AkuId, type AkumaPaths } from "./identity.js";
+import type { ProcessCollar } from "../runtime/proc/run.js";
+type RequestClaim = Readonly<{
+    id: string;
+    world: string;
+    archetype: string;
+    body: string;
+    cwd?: string;
+    recipe: RequestRecipe;
+}>;
+export type RequestChildLaunch = Readonly<{
+    paths: AkumaPaths;
+    seed: Omit<Soul, "createdAt">;
+    initialBody: string;
+}>;
+export declare class AkumaBodyRequestError extends Error {
+    readonly outcome: "refused" | "voided";
+    readonly diagnostic: string;
+    readonly kind = "akuma-body-request";
+    constructor(outcome: "refused" | "voided", diagnostic: string);
+}
+export declare function injectedBodyRequests(): string | null;
+export declare function requestBodyCall(input: RequestClaim & Readonly<{
+    directory: string;
+}>): Promise<AkuId>;
+export declare class BodyRequestPump {
+    private readonly input;
+    readonly directory: string;
+    readonly failure: Promise<never>;
+    private closed;
+    private readonly handled;
+    private readonly running;
+    constructor(input: Readonly<{
+        paths: AkumaPaths;
+        parent: Soul;
+        bodySequence: number;
+        now(): string;
+        spawn(launch: RequestChildLaunch): Promise<ProcessCollar>;
+    }>);
+    private run;
+    close(): Promise<void>;
+    stopAdmission(): void;
+}
+export declare function settleBodyRequests(paths: AkumaPaths, parent: Soul, now: () => string): Promise<"settled" | "pending">;
+export {};

package/build/src/akuma/requests.js

@@ -0,0 +1,388 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { HeldAkumaLeash, admitRequest, readNonterminalRequests, readRequest, readSoul, refuseRequest, reserveRequest, serveRequest, voidRequest, } from "./heart/index.js";
+import { parseAkuId, pathsForAkuId, archetypeName, worldRootForAkumaPaths, } from "./identity.js";
+import { BIRTH_TIMEOUT_MS, publishAkuma } from "./publication.js";
+import { AKUMA_REQUESTS_ENV, decodeProviderOptions } from "./provider.js";
+import { decodeProviderExecution, providerNamed } from "./providers/index.js";
+const POLL_MS = 25;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+export class AkumaBodyRequestError extends Error {
+    outcome;
+    diagnostic;
+    kind = "akuma-body-request";
+    constructor(outcome, diagnostic) {
+        super(`Akuma body request ${outcome}: ${diagnostic}`);
+        this.outcome = outcome;
+        this.diagnostic = diagnostic;
+        this.name = "AkumaBodyRequestError";
+    }
+}
+function wait(milliseconds) {
+    return new Promise((resolveWait) => setTimeout(resolveWait, milliseconds));
+}
+function diagnostic(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function exactKeys(value, expected) {
+    const actual = Object.keys(value).sort();
+    return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+function absolute(value) {
+    return typeof value === "string" && isAbsolute(value) && resolve(value) === value;
+}
+function matchingConfinement(value, expected) {
+    const confinement = object(value);
+    if (confinement === null || confinement.kind !== expected.kind)
+        return false;
+    if (expected.kind === "unconfined")
+        return exactKeys(confinement, ["kind"]);
+    if (!exactKeys(confinement, ["kind", "writableRoots"]) || !Array.isArray(confinement.writableRoots))
+        return false;
+    return confinement.writableRoots.length === expected.writableRoots.length
+        && confinement.writableRoots.every((root, index) => root === expected.writableRoots[index]);
+}
+function decodeRecipe(value, cwd) {
+    const recipe = object(value);
+    if (recipe === null)
+        return null;
+    const expectedKeys = [
+        "confinement",
+        ...(recipe.description === undefined ? [] : ["description"]),
+        "options",
+        "provider",
+    ];
+    if (!exactKeys(recipe, expectedKeys))
+        return null;
+    if (recipe.description !== undefined
+        && (typeof recipe.description !== "string" || recipe.description.trim().length === 0))
+        return null;
+    try {
+        const provider = decodeProviderExecution(recipe.provider);
+        const adapter = providerNamed(provider);
+        const decodedOptions = decodeProviderOptions(recipe.options);
+        const admission = adapter.admitOptions(decodedOptions);
+        if (admission.kind === "refused")
+            return null;
+        const confinement = adapter.confinement({ cwd, options: admission.options });
+        if (!matchingConfinement(recipe.confinement, confinement))
+            return null;
+        return Object.freeze({
+            ...(recipe.description === undefined ? {} : { description: recipe.description }),
+            provider,
+            options: admission.options,
+            confinement,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function decodeClaim(bytes, fileId) {
+    let decoded;
+    try {
+        decoded = JSON.parse(bytes);
+    }
+    catch {
+        return null;
+    }
+    const value = object(decoded);
+    if (value === null)
+        return null;
+    const expected = [
+        "archetype",
+        "body",
+        ...(value.cwd === undefined ? [] : ["cwd"]),
+        "id",
+        "recipe",
+        "world",
+    ];
+    if (!exactKeys(value, expected))
+        return null;
+    if (value.id !== fileId || typeof value.id !== "string" || !UUID.test(value.id))
+        return null;
+    if (typeof value.body !== "string" || !absolute(value.world))
+        return null;
+    if (value.cwd !== undefined && !absolute(value.cwd))
+        return null;
+    try {
+        archetypeName(value.archetype);
+    }
+    catch {
+        return null;
+    }
+    const recipe = decodeRecipe(value.recipe, (value.cwd ?? value.world));
+    if (recipe === null)
+        return null;
+    return {
+        id: value.id,
+        world: value.world,
+        archetype: value.archetype,
+        body: value.body,
+        recipe,
+        ...(value.cwd === undefined ? {} : { cwd: value.cwd }),
+    };
+}
+function decodeReceipt(bytes, requestId) {
+    let decoded;
+    try {
+        decoded = JSON.parse(bytes);
+    }
+    catch {
+        return null;
+    }
+    const value = object(decoded);
+    if (value === null || value.id !== requestId)
+        return null;
+    if (value.state === "served" && exactKeys(value, ["child", "id", "state"])) {
+        try {
+            return { id: requestId, state: "served", child: parseAkuId(value.child).id };
+        }
+        catch {
+            return null;
+        }
+    }
+    if (value.state === "refused" && exactKeys(value, ["diagnostic", "id", "state"])
+        && typeof value.diagnostic === "string") {
+        return { id: requestId, state: "refused", diagnostic: value.diagnostic };
+    }
+    if (value.state === "voided" && exactKeys(value, ["evidence", "id", "state"])
+        && typeof value.evidence === "string") {
+        return { id: requestId, state: "voided", evidence: value.evidence };
+    }
+    return null;
+}
+function atomicJson(path, value) {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, `${JSON.stringify(value)}\n`, { flag: "wx" });
+        renameSync(temporary, path);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+function receiptFor(fact) {
+    if (fact.state === "served")
+        return { id: fact.id, state: fact.state, child: fact.child };
+    if (fact.state === "refused")
+        return { id: fact.id, state: fact.state, diagnostic: fact.diagnostic };
+    if (fact.state === "voided")
+        return { id: fact.id, state: fact.state, evidence: fact.evidence };
+    return null;
+}
+function projectReceipt(directory, fact) {
+    const receipt = receiptFor(fact);
+    if (receipt !== null)
+        atomicJson(join(directory, `${fact.id}.receipt.json`), receipt);
+}
+export function injectedBodyRequests() {
+    const directory = process.env[AKUMA_REQUESTS_ENV];
+    if (directory === undefined)
+        return null;
+    if (!absolute(directory))
+        throw new Error(`${AKUMA_REQUESTS_ENV} must be an absolute normalized path`);
+    return directory;
+}
+export async function requestBodyCall(input) {
+    atomicJson(join(input.directory, `${input.id}.request.json`), {
+        id: input.id,
+        world: input.world,
+        archetype: input.archetype,
+        body: input.body,
+        recipe: input.recipe,
+        ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
+    });
+    const receiptPath = join(input.directory, `${input.id}.receipt.json`);
+    for (;;) {
+        try {
+            const receipt = decodeReceipt(readFileSync(receiptPath, "utf8"), input.id);
+            if (receipt === null)
+                throw new Error(`Akuma body request ${input.id} has an invalid receipt`);
+            if (receipt.state === "served")
+                return receipt.child;
+            if (receipt.state === "refused")
+                throw new AkumaBodyRequestError("refused", receipt.diagnostic);
+            throw new AkumaBodyRequestError("voided", receipt.evidence);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        await wait(POLL_MS);
+    }
+}
+async function serveClaim(input) {
+    let fact = admitRequest(input.paths, { ...input.claim, admittedAt: input.now() });
+    const existing = receiptFor(fact);
+    if (existing !== null) {
+        projectReceipt(input.directory, fact);
+        return;
+    }
+    if (fact.state !== "admitted")
+        throw new Error(`Akuma request ${fact.id} cannot be replayed from ${fact.state}`);
+    const request = fact;
+    const servingWorld = worldRootForAkumaPaths(input.paths);
+    if (request.world !== servingWorld) {
+        fact = refuseRequest(input.paths, request.id, `request world ${request.world} does not match ${servingWorld}`);
+        projectReceipt(input.directory, fact);
+        return;
+    }
+    const cwd = resolve(request.cwd ?? servingWorld);
+    let child;
+    try {
+        const published = await publishAkuma({
+            worldPath: servingWorld,
+            archetype: request.archetype,
+            reserve: (allocated) => { fact = reserveRequest(input.paths, request.id, allocated.id); },
+            launch: async (allocated) => 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,
+                    cwd,
+                    origin: { kind: "request", parentId: input.parent.id, requestId: request.id },
+                    confinement: request.recipe.confinement,
+                },
+                initialBody: request.body,
+            }),
+        });
+        child = published.id;
+    }
+    catch (error) {
+        const current = readRequest(input.paths, request.id);
+        if (current === null)
+            throw error;
+        fact = current.state === "admitted" || current.state === "reserved"
+            ? voidRequest(input.paths, request.id, diagnostic(error))
+            : current;
+        projectReceipt(input.directory, fact);
+        return;
+    }
+    fact = serveRequest(input.paths, request.id, child);
+    projectReceipt(input.directory, fact);
+}
+function requestFiles(directory) {
+    try {
+        return readdirSync(directory)
+            .filter((name) => name.endsWith(".request.json"))
+            .sort();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+export class BodyRequestPump {
+    input;
+    directory;
+    failure;
+    closed = false;
+    handled = new Set();
+    running;
+    constructor(input) {
+        this.input = input;
+        this.directory = join(input.paths.directory, "requests", String(input.bodySequence));
+        mkdirSync(this.directory, { recursive: true });
+        this.running = this.run();
+        this.failure = this.running.then(() => new Promise(() => { }), (error) => Promise.reject(error));
+    }
+    async run() {
+        while (!this.closed) {
+            for (const name of requestFiles(this.directory)) {
+                if (this.closed)
+                    return;
+                const id = name.slice(0, -".request.json".length);
+                if (this.handled.has(id))
+                    continue;
+                const claim = decodeClaim(readFileSync(join(this.directory, name), "utf8"), id);
+                if (claim === null) {
+                    this.handled.add(id);
+                    continue;
+                }
+                if (this.closed)
+                    return;
+                await serveClaim({ directory: this.directory, claim, ...this.input });
+                this.handled.add(id);
+            }
+            await wait(POLL_MS);
+        }
+    }
+    async close() {
+        this.stopAdmission();
+        try {
+            await this.running;
+        }
+        finally {
+            rmSync(this.directory, { recursive: true, force: true });
+        }
+    }
+    stopAdmission() { this.closed = true; }
+}
+function matchingRequestOrigin(soul, parent, requestId) {
+    return soul.origin.kind === "request"
+        && soul.origin.parentId === parent
+        && soul.origin.requestId === requestId;
+}
+function settleObservedSoul(paths, parent, request, soul) {
+    if (matchingRequestOrigin(soul, parent.id, request.id))
+        serveRequest(paths, request.id, request.child);
+    else
+        voidRequest(paths, request.id, "reserved child origin does not match the request");
+}
+async function settleReserved(paths, parent, request, now) {
+    const childPaths = pathsForAkuId(request.world, request.child);
+    const deadline = performance.now() + BIRTH_TIMEOUT_MS;
+    for (;;) {
+        if (!existsSync(childPaths.directory)) {
+            voidRequest(paths, request.id, "reserved child directory is absent");
+            return true;
+        }
+        const childSoul = readSoul(childPaths);
+        if (childSoul !== null) {
+            settleObservedSoul(paths, parent, request, childSoul);
+            return true;
+        }
+        const leash = HeldAkumaLeash.try(childPaths);
+        if (leash !== null) {
+            try {
+                const settledSoul = readSoul(childPaths);
+                if (settledSoul !== null) {
+                    settleObservedSoul(paths, parent, request, settledSoul);
+                }
+                else {
+                    leash.sealIfUnborn(childPaths, { evidence: "request settlement", at: now() });
+                    voidRequest(paths, request.id, "reserved child was sealed unborn");
+                }
+            }
+            finally {
+                leash.release();
+            }
+            return true;
+        }
+        if (performance.now() >= deadline)
+            return false;
+        await wait(POLL_MS);
+    }
+}
+export async function settleBodyRequests(paths, parent, now) {
+    let pending = false;
+    for (const request of readNonterminalRequests(paths)) {
+        if (request.state === "admitted") {
+            voidRequest(paths, request.id, "body died before serving the request");
+        }
+        else if (request.state === "reserved" && !await settleReserved(paths, parent, request, now))
+            pending = true;
+    }
+    return pending ? "pending" : "settled";
+}

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

@@ -0,0 +1,17 @@
+import { type AkuId } from "../akuma/identity.js";
+import { type AkumaAlias } from "../identity/selector.js";
+export type AliasBinding = Readonly<{
+    alias: AkumaAlias;
+    akuId: AkuId;
+}>;
+export type AliasMove = Readonly<{
+    alias: AliasBinding;
+    previous: AkuId | null;
+}>;
+export declare function readAliases(world: string): readonly AliasBinding[];
+export declare function resolveAlias(world: string, value: AkumaAlias): AkuId | null;
+export declare function moveAlias(input: Readonly<{
+    world: string;
+    alias: AkumaAlias;
+    akuId: AkuId;
+}>): Promise<AliasMove>;

package/build/src/alias/index.js

@@ -0,0 +1,104 @@
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { parseAkuId } from "../akuma/identity.js";
+import { replaceFileDurably } from "../coordination/durable-file.js";
+import { acquireSqliteTransactionLock } from "../coordination/sqlite-transaction-lock.js";
+import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { parseAkumaAlias } from "../identity/selector.js";
+const VERSION = 1;
+function paths(world) {
+    if (typeof world !== "string" || world.trim().length === 0) {
+        throw new TypeError("Alias world must be a nonblank path");
+    }
+    const root = resolve(world);
+    return {
+        authority: resolve(root, ".keiyaku", "akuma", "alias.json"),
+        lock: resolve(root, ".keiyaku", "locks", "akuma-alias.sqlite"),
+    };
+}
+function canonical(bindings) {
+    const aliases = Object.fromEntries(bindings
+        .slice()
+        .sort((left, right) => Buffer.compare(Buffer.from(left.alias), Buffer.from(right.alias)))
+        .map((binding) => [binding.alias, binding.akuId]));
+    const file = { version: VERSION, aliases };
+    return `${JSON.stringify(file)}\n`;
+}
+function corruption(message, cause) {
+    throw new AuthorityCorruptionError(message, cause === undefined ? {} : { cause });
+}
+function decode(path, bytes) {
+    let value;
+    try {
+        if (!bytes.endsWith("\n") || bytes.slice(0, -1).includes("\n")) {
+            corruption(`Alias file is not one canonical JSON line: ${path}`);
+        }
+        value = JSON.parse(bytes);
+    }
+    catch (error) {
+        if (error instanceof AuthorityCorruptionError)
+            throw error;
+        return corruption(`invalid Alias JSON: ${path}`, error);
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        corruption(`Alias file must be an object: ${path}`);
+    }
+    const record = value;
+    if (Object.keys(record).length !== 2 || !Object.hasOwn(record, "version") || !Object.hasOwn(record, "aliases")) {
+        corruption(`Alias file has invalid fields: ${path}`);
+    }
+    if (record.version !== VERSION)
+        corruption(`Alias file version must be ${VERSION}: ${path}`);
+    if (typeof record.aliases !== "object" || record.aliases === null || Array.isArray(record.aliases)) {
+        corruption(`Alias map must be an object: ${path}`);
+    }
+    const bindings = [];
+    for (const [rawAlias, rawAkuId] of Object.entries(record.aliases)) {
+        if (typeof rawAkuId !== "string")
+            corruption(`Alias target must be an AkuId: ${path}`);
+        try {
+            bindings.push({ alias: parseAkumaAlias(rawAlias), akuId: parseAkuId(rawAkuId).id });
+        }
+        catch (error) {
+            return corruption(`Alias binding is invalid: ${path}`, error);
+        }
+    }
+    bindings.sort((left, right) => Buffer.compare(Buffer.from(left.alias), Buffer.from(right.alias)));
+    if (canonical(bindings) !== bytes)
+        corruption(`Alias bytes are not canonical: ${path}`);
+    return bindings;
+}
+function read(path) {
+    try {
+        return decode(path, readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+export function readAliases(world) {
+    return read(paths(world).authority);
+}
+export function resolveAlias(world, value) {
+    const alias = parseAkumaAlias(value);
+    return readAliases(world).find((binding) => binding.alias === alias)?.akuId ?? null;
+}
+export async function moveAlias(input) {
+    const alias = parseAkumaAlias(input.alias);
+    const akuId = parseAkuId(input.akuId).id;
+    const location = paths(input.world);
+    const held = await acquireSqliteTransactionLock({ path: location.lock, mode: "immediate" });
+    try {
+        const current = read(location.authority);
+        const previous = current.find((binding) => binding.alias === alias)?.akuId ?? null;
+        const next = [...current.filter((binding) => binding.alias !== alias), { alias, akuId }];
+        mkdirSync(dirname(location.authority), { recursive: true });
+        replaceFileDurably(location.authority, canonical(next));
+        return { alias: { alias, akuId }, previous };
+    }
+    finally {
+        held.close();
+    }
+}

package/build/src/body/amend.d.ts

@@ -0,0 +1,2 @@
+import type { DecodedContractDocument } from "./types.js";
+export declare function applyAmendDocument(source: string, current: DecodedContractDocument): string;