@astrosheep/keiyaku 2.9.13 → 4.0.1

package/build/src/akuma/requests.js

@@ -0,0 +1,391 @@
+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", parent: 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; }
+}
+export function clearBodyRequestTransport(paths) {
+    rmSync(join(paths.directory, "requests"), { recursive: true, force: true });
+}
+function matchingRequestOrigin(soul, parent, requestId) {
+    return soul.origin.kind === "request"
+        && soul.origin.parent === 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,18 @@
+import { type AkuId } from "../akuma/identity.js";
+import { type AkumaAlias } from "../identity/selector.js";
+import type { WorldRoot } from "../world.js";
+export type AliasBinding = Readonly<{
+    alias: AkumaAlias;
+    akuId: AkuId;
+}>;
+export type AliasMove = Readonly<{
+    alias: AliasBinding;
+    previous: AkuId | null;
+}>;
+export declare function readAliases(world: WorldRoot): readonly AliasBinding[];
+export declare function resolveAlias(world: WorldRoot, value: AkumaAlias): AkuId | null;
+export declare function moveAlias(input: Readonly<{
+    world: WorldRoot;
+    alias: AkumaAlias;
+    akuId: AkuId;
+}>): Promise<AliasMove>;

package/build/src/alias/index.js

@@ -0,0 +1,103 @@
+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");
+    }
+    return {
+        authority: resolve(world, ".keiyaku", "akuma", "alias.json"),
+        lock: resolve(world, ".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;