@astrosheep/keiyaku 4.5.20 → 4.5.21

package/build/src/library/fleet.d.ts

@@ -1,6 +1,7 @@
 /** @architectureCompositionRoot */
 import { type ActivityHistory, type OutcomeRow, type AkumaStatus, type InterruptReceipt } from "../akuma/akuma.js";
 import { type ExecutionContext } from "../akuma/requests.js";
+import type { WaitObserver } from "../akuma/fleet-execution.js";
 import { type DispatchAssociation } from "../dispatch/index.js";
 import { type AkumaAddressInput, type AkumaSetAddressInput } from "./address.js";
 import { type AkumaKillResult, type AkumaObservation, type AkumaObservationStage, type AkumaTellResult, type AkumaWaitResult } from "../akuma/fleet-observation.js";
@@ -10,6 +11,7 @@ export type AkumaWaitInput = AkumaSetAddressInput & Readonly<{
 }>;
 export type AkumaTellInput = AkumaAddressInput & Readonly<{
     body: string;
+    initiator?: string;
 }>;
 export type { TellResult, TellWake } from "../akuma/akuma.js";
 export type { CreatedTaskObservation } from "../task/created-observation.js";
@@ -17,6 +19,7 @@ export type { DispatchAssociation } from "../dispatch/association.js";
 export type { AkumaKillResult, AkumaObservation, AkumaObservationStage, AkumaTellResult, AkumaUnobserved, AkumaWaitResult, } from "../akuma/fleet-observation.js";
 export type AkumaInterruptInput = AkumaAddressInput & Readonly<{
     body: string;
+    initiator?: string;
 }>;
 export type AkumaInterruptResult = Readonly<{
     id: AkumaStatus["id"];
@@ -56,7 +59,7 @@ export type AkumaHistoryResult = Readonly<{
     contract: DispatchAssociation;
 }>;
 export declare function statusAkuma(input: AkumaAddressInput): Promise<AkumaObservation>;
-export declare function waitAkuma(input: AkumaWaitInput, execution?: ExecutionContext): Promise<AkumaWaitResult>;
+export declare function waitAkuma(input: AkumaWaitInput, execution?: ExecutionContext, observer?: WaitObserver): Promise<AkumaWaitResult>;
 export declare function killAkuma(input: AkumaSetAddressInput, execution?: ExecutionContext): Promise<AkumaKillResult>;
 export declare function tellAkuma(input: AkumaTellInput, execution?: ExecutionContext): Promise<AkumaTellResult>;
 export declare function interruptAkuma(input: AkumaInterruptInput): Promise<AkumaInterruptResult>;

package/build/src/library/fleet.js

@@ -4,6 +4,7 @@ import { createAkumaProduct } from "../akuma/akuma-product.js";
 import { executionChannel, localExecutionContext } from "../akuma/requests.js";
 import { requestForwardedFleetKill, requestForwardedFleetTell, requestForwardedFleetWait, } from "../akuma/fleet-request.js";
 import { executeKillAkuma, executeTellAkuma, executeWaitAkuma } from "../akuma/fleet-execution.js";
+import { readAliases } from "../alias/index.js";
 import { observeDispatchAssociation } from "../dispatch/index.js";
 import { observeCreatedTaskObservations } from "../task/created-observation.js";
 import { addressAkuma, addressAkumaSet } from "./address.js";
@@ -23,6 +24,26 @@ async function dispatchAssociation(repo, id) {
 async function createdTasksFor(path, statuses) {
     return await observeCreatedTaskObservations(path, statuses.map((status) => status.id));
 }
+/**
+ * One wait's identity-fact resolver: the alias bound to an Akuma in its world and
+ * its Dispatch association. The alias index is read once, on the first observed
+ * Akuma, and each Akuma's alias is the first binding the canonical order offers.
+ */
+function waitIdentityFacts(path, repo) {
+    let aliases;
+    return async (id) => {
+        if (aliases === undefined) {
+            const bound = new Map();
+            for (const binding of await readAliases(path)) {
+                if (!bound.has(binding.akuId))
+                    bound.set(binding.akuId, binding.alias);
+            }
+            aliases = bound;
+        }
+        const alias = aliases.get(id);
+        return { ...(alias === undefined ? {} : { alias }), contract: await dispatchAssociation(repo, id) };
+    };
+}
 async function observeAkuma(status, path, repo) {
     return (await observeAkumaSet([status], path, repo))[0];
 }
@@ -85,7 +106,7 @@ export async function statusAkuma(input) {
     const addressed = await addressAkuma(input);
     return await observeAkuma(await source(addressed.path).selectHandle({ id: addressed.id }).status(), addressed.path, input.repo);
 }
-export async function waitAkuma(input, execution = localExecutionContext()) {
+export async function waitAkuma(input, execution = localExecutionContext(), observer) {
     const values = requireInput(input, "Keiyaku.wait input");
     for (const key of Object.keys(values)) {
         if (!["path", "akuma", "repo", "completion", "timeoutMs"].includes(key)) {
@@ -94,13 +115,11 @@ export async function waitAkuma(input, execution = localExecutionContext()) {
     }
     const addressed = await addressAkumaSet(setAddress(values));
     const completion = values.completion;
-    if (addressed.ids.length > 1 && completion !== "any" && completion !== "all") {
-        throw new TypeError("completion must be any or all when waiting for multiple Akuma");
-    }
     if (completion !== undefined && completion !== "any" && completion !== "all") {
         throw new TypeError("completion must be any or all");
     }
-    const selected = completion ?? "all";
+    // An omitted mode is any: a plural wait returns when any selected Akuma is complete.
+    const selected = completion ?? "any";
     const timeoutMs = timeout(values.timeoutMs);
     const channel = executionChannel(execution);
     const repo = values.repo;
@@ -117,6 +136,9 @@ export async function waitAkuma(input, execution = localExecutionContext()) {
         ids: addressed.ids,
         completion: selected,
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        identity: waitIdentityFacts(addressed.path, repo),
+        ...(observer?.selected === undefined ? {} : { onSelected: observer.selected }),
+        ...(observer?.observe === undefined ? {} : { observe: observer.observe }),
     }));
 }
 export async function killAkuma(input, execution = localExecutionContext()) {
@@ -136,7 +158,7 @@ export async function killAkuma(input, execution = localExecutionContext()) {
 export async function tellAkuma(input, execution = localExecutionContext()) {
     const values = requireInput(input, "Keiyaku.tell input");
     for (const key of Object.keys(values)) {
-        if (!["path", "akuma", "body", "repo"].includes(key)) {
+        if (!["path", "akuma", "body", "repo", "initiator"].includes(key)) {
             throw new TypeError(`Keiyaku.tell input has unknown field: ${key}`);
         }
     }
@@ -149,18 +171,20 @@ export async function tellAkuma(input, execution = localExecutionContext()) {
             directory: channel.directory,
             target: addressed.id,
             body: values.body,
+            ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
         });
     }
     return await executeTellAkuma({
         path: addressed.path,
         id: addressed.id,
         body: values.body,
+        ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
     });
 }
 export async function interruptAkuma(input) {
     const values = requireInput(input, "Keiyaku.interrupt input");
     for (const key of Object.keys(values)) {
-        if (!["path", "akuma", "body", "repo"].includes(key)) {
+        if (!["path", "akuma", "body", "repo", "initiator"].includes(key)) {
             throw new TypeError(`Keiyaku.interrupt input has unknown field: ${key}`);
         }
     }
@@ -168,7 +192,7 @@ export async function interruptAkuma(input) {
         throw new TypeError("body must be a string");
     const addressed = await addressAkuma(directAddress(values));
     const handle = source(addressed.path).selectHandle({ id: addressed.id });
-    const receipt = await handle.interrupt(values.body);
+    const receipt = await handle.interrupt(values.body, input.initiator === undefined ? {} : { initiator: input.initiator });
     const observation = await observeAkumaStage(addressed.path, addressed.id, values.repo);
     return { id: addressed.id, receipt, observation };
 }

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,4 +1,12 @@
 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,

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;
     }>;

package/build/src/plugin/runtime.js

@@ -208,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")

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
                 ? {}