@astrosheep/keiyaku 4.5.19 → 4.5.21

package/build/src/plugin/akuma-signals.d.ts

@@ -8,5 +8,11 @@ type CalledPluginSignalInput = Readonly<{
     callerAkumaId?: string;
     contractId?: string;
 }>;
+export declare function emitInitiatingPluginSignal(input: Readonly<{
+    world: WorldRoot;
+    settings?: Settings;
+    initiator: string;
+    reportDiagnostic: (message: string) => void;
+}>): Promise<void>;
 export declare function emitCalledPluginSignal(input: CalledPluginSignalInput): Promise<void>;
 export {};

package/build/src/plugin/akuma-signals.js

@@ -1,11 +1,19 @@
 import { pluginRuntime } from "./runtime.js";
+export async function emitInitiatingPluginSignal(input) {
+    const runtime = await pluginRuntime({
+        world: input.world,
+        ...(input.settings === undefined ? {} : { settings: input.settings }),
+        reportDiagnostic: input.reportDiagnostic,
+    });
+    await runtime.emit({ kind: "akuma.initiating", initiator: input.initiator }, input.reportDiagnostic);
+}
 export async function emitCalledPluginSignal(input) {
     const runtime = await pluginRuntime({
         world: input.world,
         ...(input.settings === undefined ? {} : { settings: input.settings }),
         reportDiagnostic: input.reportDiagnostic,
     });
-    runtime.emit({
+    await runtime.emit({
         kind: "akuma.called",
         akumaId: input.akumaId,
         ...(input.callerAkumaId === undefined ? {} : { callerAkumaId: input.callerAkumaId }),

package/build/src/plugin/public.d.ts

@@ -16,6 +16,9 @@ export type PluginOutcome = Readonly<{
 }>;
 export type PluginBodyEnd = "exited" | "broke-off" | "put-down" | "hung";
 export type PluginSignalMap = Readonly<{
+    "akuma.initiating": Readonly<{
+        initiator: string;
+    }>;
     "akuma.called": Readonly<{
         akumaId: string;
         callerAkumaId?: string;
@@ -24,6 +27,7 @@ export type PluginSignalMap = Readonly<{
     "akuma.turn-outcome": Readonly<{
         akumaId: string;
         turnSequence: number;
+        initiator?: string;
         outcome: PluginOutcome;
         contractId?: string;
     }>;
@@ -43,7 +47,7 @@ export type PluginSignal = {
 export type PluginHooks = Readonly<{
     [K in keyof PluginSignalMap]?: (signal: Readonly<{
         kind: K;
-    }> & PluginSignalMap[K]) => Promise<void> | void;
+    }> & PluginSignalMap[K], cancellation?: AbortSignal) => Promise<void> | void;
 }>;
 export type PluginContext = Readonly<{
     world: WorldRoot;
@@ -52,7 +56,7 @@ export type PluginContext = Readonly<{
 }>;
 export type KeiyakuPlugin = Readonly<{
     manifest: PluginManifest;
-    activate(context: PluginContext): Promise<PluginInstance> | PluginInstance;
+    activate(context: PluginContext, cancellation?: AbortSignal): Promise<PluginInstance> | PluginInstance;
 }>;
 export type PluginInstance = Readonly<{
     signals?: PluginHooks;

package/build/src/plugin/runtime.d.ts

@@ -1,6 +1,6 @@
 import { type Settings } from "../settings.js";
 import type { WorldRoot } from "../world.js";
-import type { PluginSignal, PluginSignalMap } from "./public.js";
+import type { PluginSignal } from "./public.js";
 type PluginDiagnostic = (diagnostic: string) => void;
 type PluginRuntimeInput = Readonly<{
     world: WorldRoot;
@@ -9,8 +9,6 @@ type PluginRuntimeInput = Readonly<{
 }>;
 export type PluginRuntime = Readonly<{
     emit(signal: PluginSignal, reportDiagnostic?: PluginDiagnostic): Promise<void>;
-    drain(kind?: keyof PluginSignalMap): Promise<void>;
 }>;
 export declare function pluginRuntime(input: PluginRuntimeInput): Promise<PluginRuntime>;
-export declare function drainPluginRuntime(world: WorldRoot): Promise<void>;
 export {};

package/build/src/plugin/runtime.js

@@ -4,13 +4,14 @@ import { isAbsolute, join, posix, relative, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { settings } from "../settings.js";
 const DIAGNOSTIC_LIMIT = 500;
-const PLUGIN_DRAIN_TIMEOUT_MS = 5_000;
+const PLUGIN_ATTEMPT_TIMEOUT_MS = 5_000;
 const PLUGIN_NAMESPACE = "plugins";
 const SQUARE_PLUGIN_PACKAGE = "@astrosheep/keiyaku-plugin-square";
 const BUILTIN_PLUGINS = Object.freeze([
     Object.freeze({ id: "square", package: SQUARE_PLUGIN_PACKAGE, config: undefined }),
 ]);
 const PROCESS_RUNTIMES = new Map();
+const ABORTED = Symbol("plugin attempt aborted");
 function object(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -27,6 +28,43 @@ function diagnostic(report, subject, stage, error) {
         // Diagnostics are optional side effects too.
     }
 }
+function timeoutError() {
+    return new Error(`timed out after ${PLUGIN_ATTEMPT_TIMEOUT_MS}ms`);
+}
+async function boundedAttempt(attempt, timeoutMs = PLUGIN_ATTEMPT_TIMEOUT_MS) {
+    if (timeoutMs <= 0)
+        return { kind: "timed-out" };
+    const controller = new AbortController();
+    let timeout;
+    const completed = Promise.resolve()
+        .then(() => attempt(controller.signal))
+        .then((value) => ({ kind: "settled", value }), (error) => ({ kind: "failed", error }));
+    const expired = new Promise((resolve) => {
+        timeout = setTimeout(() => {
+            controller.abort(timeoutError());
+            resolve({ kind: "timed-out" });
+        }, timeoutMs);
+    });
+    const result = await Promise.race([completed, expired]);
+    if (timeout !== undefined)
+        clearTimeout(timeout);
+    return result;
+}
+async function settleBefore(promise, cancellation) {
+    if (cancellation.aborted)
+        return ABORTED;
+    let releaseAbort;
+    const aborted = new Promise((resolve) => {
+        releaseAbort = () => resolve(ABORTED);
+        cancellation.addEventListener("abort", releaseAbort, { once: true });
+    });
+    try {
+        return await Promise.race([promise, aborted]);
+    }
+    finally {
+        cancellation.removeEventListener("abort", releaseAbort);
+    }
+}
 function selectedEntry(entry, report) {
     if (entry.name.trim().length === 0) {
         diagnostic(report, "<unnamed>", "selection", new TypeError("plugin setting name must be nonblank"));
@@ -170,7 +208,10 @@ function handlers(pluginId, instance) {
         throw new TypeError("plugin signals must be an object");
     const registered = [];
     for (const [kind, handler] of Object.entries(instance.signals)) {
-        if (kind !== "akuma.called" && kind !== "akuma.turn-outcome" && kind !== "akuma.body-ended") {
+        if (kind !== "akuma.initiating" &&
+            kind !== "akuma.called" &&
+            kind !== "akuma.turn-outcome" &&
+            kind !== "akuma.body-ended") {
             throw new TypeError(`plugin signal is unknown: ${kind}`);
         }
         if (typeof handler !== "function")
@@ -214,7 +255,8 @@ async function importFromWorld(world, packageName) {
         hooks.deregister();
     }
 }
-async function activate(selected, world, activated, report, onStarted) {
+async function activate(input) {
+    const { selected, world, activated, report, cancellation, onStarted } = input;
     let started = false;
     const markStarted = () => {
         if (started)
@@ -231,6 +273,10 @@ async function activate(selected, world, activated, report, onStarted) {
         diagnostic(report, selected.id, "import", error);
         return [];
     }
+    if (cancellation.aborted) {
+        markStarted();
+        return [];
+    }
     let candidate;
     try {
         candidate = manifest(module.default);
@@ -264,9 +310,15 @@ async function activate(selected, world, activated, report, onStarted) {
         diagnostic(report, selected.id, "validation", error);
         return [];
     }
+    if (cancellation.aborted) {
+        markStarted();
+        return [];
+    }
     markStarted();
     try {
-        const instance = await candidate.activate(context);
+        const instance = await candidate.activate(context, cancellation);
+        if (cancellation.aborted)
+            return [];
         const registered = handlers(candidate.manifest.id, instance);
         activated.add(candidate.manifest.id);
         return registered;
@@ -276,23 +328,12 @@ async function activate(selected, world, activated, report, onStarted) {
         return [];
     }
 }
-function deliver(entry, signal, reportDiagnostic, inFlight) {
-    try {
-        const delivery = Promise.resolve(entry.handler(signal)).catch((error) => diagnostic(reportDiagnostic, entry.pluginId, "signal", error));
-        const deliveries = inFlight.get(signal.kind) ?? new Set();
-        deliveries.add(delivery);
-        inFlight.set(signal.kind, deliveries);
-        void delivery.finally(() => deliveries.delete(delivery));
-    }
-    catch (error) {
-        diagnostic(reportDiagnostic, entry.pluginId, "signal", error);
-    }
-}
-function deliverTo(handlers, signal, reportDiagnostic, inFlight) {
-    for (const entry of handlers) {
-        if (entry.kind === signal.kind)
-            deliver(entry, signal, reportDiagnostic, inFlight);
-    }
+async function deliver(entry, signal, reportDiagnostic, timeoutMs) {
+    const result = await boundedAttempt((cancellation) => entry.handler(signal, cancellation), timeoutMs);
+    if (result.kind === "timed-out")
+        diagnostic(reportDiagnostic, entry.pluginId, "signal", timeoutError());
+    if (result.kind === "failed")
+        diagnostic(reportDiagnostic, entry.pluginId, "signal", result.error);
 }
 export async function pluginRuntime(input) {
     let runtime = PROCESS_RUNTIMES.get(input.world);
@@ -302,101 +343,52 @@ export async function pluginRuntime(input) {
     }
     return await runtime;
 }
-export async function drainPluginRuntime(world) {
-    const runtime = PROCESS_RUNTIMES.get(world);
-    if (runtime !== undefined)
-        await (await runtime).drain();
-}
-async function drainWithDeadline(pending) {
-    let timeout;
-    try {
-        await Promise.race([
-            pending,
-            new Promise((resolve) => {
-                timeout = setTimeout(resolve, PLUGIN_DRAIN_TIMEOUT_MS);
-            }),
-        ]);
-    }
-    finally {
-        clearTimeout(timeout);
-    }
-}
 async function createPluginRuntime(input) {
     const report = input.reportDiagnostic;
     const selected = selectedPlugins(input.settings ?? (await settings({ root: input.world })), report);
     const activated = new Set();
-    const registered = new Map();
-    const settled = new Set();
-    const pending = new Map();
-    const settledPromises = [];
-    const inFlight = new Map();
     let previousStarted = Promise.resolve();
-    for (const [index, entry] of selected.entries()) {
+    const activations = selected.map((entry) => {
         let releaseStarted;
-        let releaseSettled;
         const started = new Promise((resolve) => {
             releaseStarted = resolve;
         });
-        settledPromises.push(new Promise((resolve) => {
-            releaseSettled = resolve;
-        }));
-        void previousStarted.then(async () => {
-            try {
-                const handlers = await activate(entry, input.world, activated, report, releaseStarted);
-                if (handlers.length > 0)
-                    registered.set(index, handlers);
-                settled.add(index);
-                const queued = pending.get(index);
-                if (queued !== undefined) {
-                    pending.delete(index);
-                    for (const signal of queued)
-                        deliverTo(handlers, signal, report, inFlight);
-                }
-            }
-            catch (error) {
-                diagnostic(report, entry.id, "activation", error);
-                settled.add(index);
-                pending.delete(index);
-            }
-            finally {
-                releaseStarted();
-                releaseSettled();
-            }
+        const activation = previousStarted.then(async () => {
+            const result = await boundedAttempt((cancellation) => activate({ selected: entry, world: input.world, activated, report, cancellation, onStarted: releaseStarted }));
+            releaseStarted();
+            if (result.kind === "settled")
+                return { handlers: result.value, timedOut: false };
+            diagnostic(report, entry.id, "activation", result.kind === "failed" ? result.error : timeoutError());
+            return { handlers: [], timedOut: result.kind === "timed-out" };
         });
         previousStarted = started;
-    }
+        return activation;
+    });
     return Object.freeze({
-        emit(signal, reportDiagnostic = report) {
-            const deliveries = [...registered.entries()]
-                .sort(([left], [right]) => left - right)
-                .flatMap(([, handlers]) => handlers)
-                .filter((handler) => handler.kind === signal.kind);
-            for (const [index] of selected.entries()) {
-                if (!settled.has(index)) {
-                    const queue = pending.get(index);
-                    if (queue === undefined)
-                        pending.set(index, [signal]);
-                    else
-                        queue.push(signal);
-                }
+        async emit(signal, reportDiagnostic = report) {
+            const deadline = performance.now() + PLUGIN_ATTEMPT_TIMEOUT_MS;
+            const activated = await boundedAttempt(async (cancellation) => {
+                const handlers = await Promise.all(activations.map(async (activation, index) => {
+                    const activatedHandlers = await settleBefore(activation, cancellation);
+                    if (activatedHandlers !== ABORTED) {
+                        if (activatedHandlers.timedOut)
+                            diagnostic(reportDiagnostic, selected[index].id, "signal", timeoutError());
+                        return activatedHandlers.handlers;
+                    }
+                    diagnostic(reportDiagnostic, selected[index].id, "signal", timeoutError());
+                    return [];
+                }));
+                return handlers.flat();
+            });
+            if (activated.kind === "failed") {
+                diagnostic(reportDiagnostic, "runtime", "signal", activated.error);
+                return;
             }
-            for (const entry of deliveries)
-                deliver(entry, signal, reportDiagnostic, inFlight);
-            return Promise.resolve();
-        },
-        async drain(kind) {
-            const settle = async () => {
-                await Promise.all(settledPromises);
-                for (;;) {
-                    const pending = kind === undefined
-                        ? [...inFlight.values()].flatMap((deliveries) => [...deliveries])
-                        : [...(inFlight.get(kind) ?? [])];
-                    if (pending.length === 0)
-                        return;
-                    await Promise.all(pending);
-                }
-            };
-            await drainWithDeadline(settle());
+            if (activated.kind === "timed-out")
+                return;
+            await Promise.all(activated.value
+                .filter((entry) => entry.kind === signal.kind)
+                .map((entry) => deliver(entry, signal, reportDiagnostic, Math.max(0, deadline - performance.now()))));
         },
     });
 }

package/build/src/protocol/amend.js

@@ -30,14 +30,15 @@ export async function amendOperation(input) {
         const initial = await observeContractsForAdmissionAt(input.scope, input.channel, [input.contractId]);
         source = contractState(initial.decision, input.contractId)?.terms;
     }
+    // Deriving the caller-stamped document is pure: it never depends on the latest Contract.
+    const amendment = source === undefined || input.deriveAmendment === undefined
+        ? undefined
+        : { source, ...input.deriveAmendment(source) };
     return intentOutcomeWithSeatClose(await withPrivateStatePublicationSeat(input.scope, async (seat) => {
         const attempts = mintAttempts({ entryCount: 1 });
         for (let index = 0; index < attempts.length; index += 1) {
             let observation = await observeContractsForAdmissionAt(input.scope, input.channel, [input.contractId]);
             const state = contractState(observation.decision, input.contractId);
-            const amendment = source === undefined || input.deriveAmendment === undefined
-                ? undefined
-                : { source, ...input.deriveAmendment(source) };
             if (amendment !== undefined) {
                 observation = await extendPrerequisiteClosureAt(input.channel, observation, [
                     ...new Set([...(state?.terms.after ?? []), ...amendment.terms.after]),

package/build/src/protocol/attempt.d.ts

@@ -35,6 +35,8 @@ export type AttemptTerminal = Readonly<{
     kind: "collision";
 }> | PublicationFailed;
 export type DecidedOfferResult<Refusal = never> = AcceptedAdmission | AttemptTerminal | Readonly<{
+    kind: "stale";
+}> | Readonly<{
     kind: "redecide";
 }> | Readonly<{
     kind: "refused";

package/build/src/protocol/bind.js

@@ -1,8 +1,8 @@
-import { normalizeTargetBranch, observeBindCoordinates } from "../git/observe.js";
+import { normalizeTargetBranch, observeBindCoordinates, } from "../git/observe.js";
 import { gitObjectIdForSnapshot } from "../git/identity.js";
 import { contractId } from "../core/facts/types.js";
 import { decideBind } from "../core/verbs/bind.js";
-import { admitIntent } from "./intent.js";
+import { admitPreparedIntent } from "./intent.js";
 import { complete } from "./outcome.js";
 export function decodeTargetInputRefusal(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
@@ -29,19 +29,44 @@ export function decodeForkSourceMovedRefusal(value) {
         throw new Error("malformed fork-source refusal");
     }
 }
-async function bindPreparation(input, selection, seed) {
+/**
+ * Acquire the repeatable Git coordinates outside the publication seat. The artifact carries the
+ * observed start/target plus the expected ref assertions that publication must still confirm.
+ */
+async function prepareBindCoordinates(input, selection) {
     if (input.verification.kind === "refused") {
-        return { kind: "prepared", input: { ...seed, preparation: input.verification } };
+        return { kind: "prepared", prepared: { kind: "declaration-refused", preparation: input.verification } };
     }
     const observed = await observeBindCoordinates(input.scope, selection);
     if (observed === null)
-        return { kind: "refused", refusal: { kind: "target-missing" } };
-    if (!("start" in observed)) {
-        return { kind: "refused", refusal: { kind: "unborn-head" } };
+        return { kind: "prepared", prepared: { kind: "unresolved", reason: "target-missing" } };
+    if ("kind" in observed)
+        return { kind: "prepared", prepared: { kind: "unresolved", reason: "unborn-head" } };
+    return {
+        kind: "prepared",
+        prepared: { kind: "resolved", observed },
+        ...(input.coordinates === undefined
+            ? { assertions: [{ ref: observed.target ?? "HEAD", oid: gitObjectIdForSnapshot(observed.start) }] }
+            : {}),
+    };
+}
+/**
+ * Assemble the decision input from the fresh in-custody observation. Coordinates fixed by the
+ * invocation are never replaced; mutable coordinate disappearance is read again as current evidence.
+ */
+async function assembleBindInput(input, selection, seed, prepared) {
+    if (prepared.kind === "declaration-refused") {
+        return { kind: "prepared", input: { ...seed, preparation: prepared.preparation } };
+    }
+    if (prepared.kind === "unresolved") {
+        const current = await observeBindCoordinates(input.scope, selection);
+        if (current === null)
+            return { kind: "refused", refusal: { kind: "target-missing" } };
+        if ("kind" in current)
+            return { kind: "refused", refusal: { kind: "unborn-head" } };
+        return { kind: "stale" };
     }
-    const start = input.coordinates?.start ?? observed.start;
-    const oid = gitObjectIdForSnapshot(input.coordinates === undefined ? start : observed.start);
-    const assertions = input.coordinates === undefined ? [{ ref: observed.target ?? "HEAD", oid }] : [];
+    const observed = prepared.observed;
     return {
         kind: "prepared",
         input: {
@@ -50,7 +75,7 @@ async function bindPreparation(input, selection, seed) {
                 kind: "prepared",
                 data: {
                     coordinates: {
-                        start,
+                        start: input.coordinates?.start ?? observed.start,
                         ...(observed.target === undefined ? {} : { target: observed.target }),
                         workspace: input.workspace,
                     },
@@ -58,7 +83,6 @@ async function bindPreparation(input, selection, seed) {
                 },
             },
         },
-        assertions,
     };
 }
 export async function bindOperation(input) {
@@ -71,13 +95,16 @@ export async function bindOperation(input) {
     }
     const at = new Date().toISOString();
     const id = input.contractId;
-    return complete(await admitIntent(input.channel, input.scope, {
+    return complete(await admitPreparedIntent(input.channel, input.scope, {
         contractId: id,
         ...(input.actor === undefined ? {} : { actor: input.actor }),
         at,
     }, decideBind, {
         observedContracts: [id, ...input.terms.after, ...(input.source === undefined ? [] : [input.source.contractId])],
-        prepareInput: async (_observation, original) => bindPreparation(input, selection, original),
+        preparation: {
+            external: async () => await prepareBindCoordinates(input, selection),
+            assemble: async (_observation, original, prepared) => await assembleBindInput(input, selection, original, prepared),
+        },
         ...(input.source === undefined
             ? {}
             : {

package/build/src/protocol/completion.d.ts

@@ -6,6 +6,9 @@ import { type ContractCheckpoint, type ExecutionProgress, type ExecutionStop } f
 import type { DocumentDerivation, PlacementStop, VerificationStop } from "./operations.js";
 export type CandidateCompletion = Readonly<{
     integration: SnapshotId;
+    /** The reference this placement advanced and the head it advanced from, both observed at completion time. */
+    predecessor?: SnapshotId;
+    target?: string;
     verification?: Readonly<{
         mode: "ran" | "reused";
         verdict: "satisfied" | "unsatisfied";

package/build/src/protocol/completion.js

@@ -82,6 +82,8 @@ function completedResult(cursor) {
     const integration = state.currentIntegration?.snapshot;
     if (integration === undefined)
         throw new Error("accepted placement requires its integration snapshot");
+    const target = state.coordinates.target;
+    const predecessor = state.currentIntegration?.predecessor;
     // Never attach a superseded run's verdict to the final integration.
     const current = currentVerifiedAttestation(state);
     const verification = current === undefined
@@ -96,7 +98,11 @@ function completedResult(cursor) {
         checkpoint: cursor.checkpoint,
         evidence: {
             ...evidence,
-            completion: { integration, ...(verification === undefined ? {} : { verification }) },
+            completion: {
+                integration,
+                ...(predecessor === undefined || target === undefined ? {} : { predecessor, target }),
+                ...(verification === undefined ? {} : { verification }),
+            },
             ...(current === undefined || verification?.mode !== "reused" ? {} : { verificationReuse: current }),
             ...(current?.verdict !== "unsatisfied" || current.summary === undefined
                 ? {}
@@ -113,17 +119,35 @@ function stoppedResult(cursor, stop) {
 async function placeCurrentCandidate(input, cursor) {
     cursor.stage = "placement";
     input.signal?.throwIfAborted();
-    const result = await admitPlacement({
-        channel: input.channel,
-        repository: input.repository,
-        progress: input.progress,
-        target: cursor.checkpoint.state.coordinates.target,
-        placement: {
-            contractId: cursor.checkpoint.state.id,
-            ...(input.actor === undefined ? {} : { actor: input.actor }),
-            at: timestamp(),
-        },
+    input.progress.observe({
+        kind: "stage",
+        contractId: cursor.checkpoint.state.id,
+        stage: "placement",
+        state: "started",
     });
+    const result = await (async () => {
+        try {
+            return await admitPlacement({
+                channel: input.channel,
+                repository: input.repository,
+                progress: input.progress,
+                target: cursor.checkpoint.state.coordinates.target,
+                placement: {
+                    contractId: cursor.checkpoint.state.id,
+                    ...(input.actor === undefined ? {} : { actor: input.actor }),
+                    at: timestamp(),
+                },
+            });
+        }
+        finally {
+            input.progress.observe({
+                kind: "stage",
+                contractId: cursor.checkpoint.state.id,
+                stage: "placement",
+                state: "finished",
+            });
+        }
+    })();
     if (result.kind === "accepted") {
         cursor.checkpoint = contractCheckpoint(result);
         input.progress.recordResidue(result.state.id, result);