@astrosheep/keiyaku 4.6.6 → 4.6.8

package/build/src/cli/runtime.js

@@ -1,7 +1,6 @@
 import { AkumaNotBornError, AkumaObservationError } from "../akuma/akuma-errors.js";
-import { AkumaArchetypeError } from "../akuma/archetype.js";
-import { AKUMA_REQUESTS_ENV } from "../akuma/provider.js";
-import { bodyRequestExecution, localExecutionContext } from "../akuma/requests.js";
+import { executionForEnvironment } from "../akuma/requests.js";
+import { AkumaArchetypeError } from "../index.js";
 import { AkumaAddressError, AkumaWorldScopeError } from "../library/address.js";
 import { encodeFailureWire, KeiyakuError } from "../library/outcome.js";
 import { isParsedAkumaCommand, runAkumaCommand } from "./commands/akuma.js";
@@ -28,11 +27,6 @@ function memoized(reader) {
     let value;
     return () => (value ??= reader());
 }
-function executionForEnvironment(environment) {
-    return environment[AKUMA_REQUESTS_ENV] === undefined
-        ? localExecutionContext()
-        : bodyRequestExecution({ directory: environment[AKUMA_REQUESTS_ENV] });
-}
 function homeFromEnvironment(environment) {
     const mapped = environment.KEIYAKU_HOME?.trim();
     return mapped === undefined || mapped.length === 0 ? undefined : mapped;
@@ -175,16 +169,16 @@ export async function runCliCommand(invocation, input = {}) {
     const home = homeFromEnvironment(environment);
     const cancellation = cliCancellation(input.signal);
     let progress;
-    const runtime = {
-        environment,
-        execution: executionForEnvironment(environment),
-        ...(home === undefined ? {} : { home }),
-        readStdin: memoized(input.readStdin ?? processStdin),
-        signal: cancellation.signal,
-        progress: () => (progress ??= writeExecutionProgress()),
-        ...(input.actor === undefined ? {} : { actor: input.actor }),
-    };
     try {
+        const runtime = {
+            environment,
+            execution: await executionForEnvironment(environment, cancellation.signal),
+            ...(home === undefined ? {} : { home }),
+            readStdin: memoized(input.readStdin ?? processStdin),
+            signal: cancellation.signal,
+            progress: () => (progress ??= writeExecutionProgress()),
+            ...(input.actor === undefined ? {} : { actor: input.actor }),
+        };
         if (command.command === "install")
             return await runInstall(command, environment);
         await admitBindInput(command, invocation, runtime, input.cwd ?? process.cwd());

package/build/src/cli/selectors.d.ts

@@ -1,14 +1,11 @@
 import { type ExecutionContext } from "../akuma/requests.js";
-import type { ContractBoard, ContractId, Keiyaku, Repo } from "../index.js";
-import type { KanshiReport } from "../kanshi/index.js";
+import { Keiyaku, type ContractId, type Repo } from "../index.js";
 type SelectedContract = Readonly<{
     id: ContractId;
     contract: Keiyaku;
 }>;
 export declare function contractFromInput(repo: Repo, value: string, execution?: ExecutionContext): SelectedContract;
-export declare function resolveContextualContract(board: ContractBoard, selector: string | undefined, scope: string): ContractId;
-/** Resolve one explicit, short, or worktree-contextual selector to its Contract id. */
-export declare function resolveContractId(repo: Repo, selector: string | undefined, scope: string): Promise<ContractId>;
+/** Adapt public Contract resolution evidence to the existing CLI usage diagnostics. */
+export declare function resolveContractId(repo: Repo, selector: string | undefined, cwd: string): Promise<ContractId>;
 export declare function canonicalContractSelector(selector: string): ContractId;
-export declare function resolveKanshiContract(report: KanshiReport, selector: string): string;
 export {};

package/build/src/cli/selectors.js

@@ -1,76 +1,45 @@
-import { resolve } from "node:path";
 import { localExecutionContext } from "../akuma/requests.js";
 import { identitySegments } from "../identity/coordinates.js";
+import { Keiyaku } from "../index.js";
 import { composeContractLibrary } from "../library/contract-composition.js";
 import { createKeiyakuHandle } from "../library/keiyaku.js";
 import { CliUsageError } from "./parse.js";
-function selectorError(message) {
-    throw new CliUsageError(message);
-}
-function activeManagedCandidates(rows) {
-    return rows.flatMap((contract) => {
-        if (contract.disposition !== "active" || contract.workspace !== "worktree" || contract.worktreePath === null)
-            return [];
-        return [{ id: contract.id, worktreePath: contract.worktreePath }];
-    });
-}
 export function contractFromInput(repo, value, execution = localExecutionContext()) {
     try {
         const id = value;
         return { id, contract: composeContractLibrary(execution, createKeiyakuHandle).select({ repo, id }) };
     }
     catch (error) {
-        selectorError(error instanceof Error ? error.message : String(error));
+        throw new CliUsageError(error instanceof Error ? error.message : String(error));
     }
 }
-function resolveShortContract(rows, selector) {
-    if (selector.startsWith("@kei/"))
-        selectorError(`redundant short contract selector: ${selector}`);
-    const short = selector.slice(1);
-    const candidates = activeManagedCandidates(rows).filter((candidate) => candidate.id.slice("kei/".length) === short);
-    if (candidates.length === 0)
-        selectorError(`unknown contract selector: ${selector}`);
-    if (candidates.length !== 1)
-        selectorError(`ambiguous contract selector: ${selector}`);
-    return candidates[0].id;
-}
-function resolveOmittedContract(board, scope) {
-    const candidates = activeManagedCandidates(board.rows).filter((candidate) => resolve(scope) === resolve(candidate.worktreePath));
-    if (candidates.length === 0) {
-        selectorError("an explicit full or @ contract selector is required outside a managed worktree");
+/** Adapt public Contract resolution evidence to the existing CLI usage diagnostics. */
+export async function resolveContractId(repo, selector, cwd) {
+    const result = await Keiyaku.with().resolve({ repo, ...(selector === undefined ? {} : { selector }), cwd });
+    if (result.kind === "resolved")
+        return result.id;
+    const refusal = result.refusal;
+    switch (refusal.kind) {
+        case "invalid-selector":
+            throw new CliUsageError(refusal.diagnostic);
+        case "redundant-short-selector":
+            throw new CliUsageError(`redundant short contract selector: ${refusal.selector}`);
+        case "unknown-short-selector":
+            throw new CliUsageError(`unknown contract selector: ${refusal.selector}`);
+        case "ambiguous-selector":
+            throw new CliUsageError("selector" in refusal
+                ? `ambiguous contract selector: ${refusal.selector}`
+                : "ambiguous managed worktree contract selector");
+        case "no-contextual-match":
+            throw new CliUsageError("an explicit full or @ contract selector is required outside a managed worktree");
     }
-    if (candidates.length !== 1)
-        selectorError("ambiguous managed worktree contract selector");
-    return candidates[0].id;
-}
-export function resolveContextualContract(board, selector, scope) {
-    if (selector === undefined)
-        return resolveOmittedContract(board, scope);
-    if (selector.startsWith("@"))
-        return resolveShortContract(board.rows, selector);
-    return selectorError(`contract selector must be kei/<contract-segment> or @<contract-segment>: ${selector}`);
-}
-/** Resolve one explicit, short, or worktree-contextual selector to its Contract id. */
-export async function resolveContractId(repo, selector, scope) {
-    if (selector !== undefined && !selector.startsWith("@"))
-        return contractFromInput(repo, selector).id;
-    const { listKeiyaku } = await import("../library/contract-composition.js");
-    return resolveContextualContract(await listKeiyaku({ repo }), selector, scope);
 }
 export function canonicalContractSelector(selector) {
     try {
         identitySegments({ family: "kei", value: selector });
     }
     catch {
-        return selectorError(`contract selector must use kei/: ${selector}`);
+        throw new CliUsageError(`contract selector must use kei/: ${selector}`);
     }
     return selector;
 }
-export function resolveKanshiContract(report, selector) {
-    if (report.contracts.kind !== "present") {
-        return selectorError(`cannot select a contract while the Contract world is ${report.contracts.kind}`);
-    }
-    if (selector.startsWith("@"))
-        return resolveShortContract(report.contracts.value.rows, selector);
-    return canonicalContractSelector(selector);
-}

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

@@ -3,7 +3,7 @@ import { type AkuId } from "../akuma/identity.js";
 import { type PrivateStateSeatCloseLag } from "../git/private-state-seat.js";
 import type { GitRepository } from "../git/process.js";
 import { type GitReadObservation } from "../git/read-observation.js";
-import { type DispatchAssociation } from "./association.js";
+import { type DispatchAssociation } from "../akuma/dispatch-association.js";
 export type Dispatch = Readonly<{
     akuId: AkuId;
     contractId: ContractId;
@@ -16,7 +16,7 @@ export type DispatchFailure = Readonly<{
     kind: "publication-failed";
     diagnostic: string;
 }>;
-export type DispatchPublication = Readonly<{
+type DispatchPublication = Readonly<{
     kind: "dispatched";
     dispatch: Dispatch;
     seatClose?: readonly PrivateStateSeatCloseLag[];
@@ -32,6 +32,6 @@ export declare function publishDispatch(input: Readonly<{
     akuId: AkuId;
     contractId: ContractId;
 }>): Promise<DispatchPublication>;
-export { dispatchAssociationSchema, NO_DISPATCH_ASSOCIATION, parseDispatchAssociation, type DispatchAssociation, } from "./association.js";
 /** Read selected associations in one targeted observation, isolating per-identity decoding failures. */
 export declare function observeDispatchAssociations(repository: GitRepository | undefined, akuIds: readonly AkuId[]): Promise<ReadonlyMap<AkuId, DispatchAssociation>>;
+export {};

package/build/src/dispatch/index.js

@@ -5,7 +5,7 @@ import { parseAkuId } from "../akuma/identity.js";
 import { appendPrivateStateSeatClose, confirmPrivateStatePublication, mergePrivateStateSeatClose, withPrivateStatePublicationSeat, } from "../git/private-state-seat.js";
 import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, readBlob, readGitPaths, updateGitTree, updateRefsAtomically, writeBlob, writeStateCommit, } from "../git/repository.js";
 import { withGitDecodeChannel, withGitReadObservation, withGitTargetedReadObservation, } from "../git/read-observation.js";
-import { NO_DISPATCH_ASSOCIATION } from "./association.js";
+import { NO_DISPATCH_ASSOCIATION } from "../akuma/dispatch-association.js";
 const DISPATCH_ROOT = "dispatch";
 const DISPATCH_PREFIX = `${DISPATCH_ROOT}/`;
 const DISPATCH_SUFFIX = ".json";
@@ -186,7 +186,6 @@ export async function publishDispatch(input) {
         };
     }));
 }
-export { dispatchAssociationSchema, NO_DISPATCH_ASSOCIATION, parseDispatchAssociation, } from "./association.js";
 /** Read selected associations in one targeted observation, isolating per-identity decoding failures. */
 export async function observeDispatchAssociations(repository, akuIds) {
     const requested = [...new Set(akuIds.map((akuId) => parseAkuId(akuId).id))];

package/build/src/git/observe.d.ts

@@ -49,8 +49,12 @@ export type BindTargetSelection = Readonly<{
 export declare function normalizeTargetBranch(repository: GitRepository, input: string): Promise<string | null>;
 /** Read one worktree's attached branch, or null for detached HEAD. */
 export declare function currentBranch(repository: GitRepository, path?: string): Promise<string | null>;
-/** Observe bind's tender start and optional reward target without creating persistent state. */
-export declare function observeBindCoordinates(repository: GitRepository, selection?: BindTargetSelection): Promise<BindCoordinatesObservation | UnbornHeadObservation | null>;
+/**
+ * Observe bind's tender start and optional reward target without creating persistent state.
+ * `current-branch` reads the observed worktree coordinate's own attached branch; the caller names
+ * which coordinate it wants observed.
+ */
+export declare function observeBindCoordinates(repository: GitRepository, selection: BindTargetSelection): Promise<BindCoordinatesObservation | UnbornHeadObservation | null>;
 export declare function observeActiveContractWorld(observation: GitReadObservation): Promise<ActiveContractWorldObservation>;
 export declare function observeContractWorld(observation: GitReadObservation, requested?: readonly ContractId[]): Promise<ContractWorldObservation>;
 export declare function observeContractsForAdmissionAt(repository: GitRepository, channel: GitDecodeChannel, ids: readonly ContractId[], selection?: GitTreeSelection): Promise<GitDecisionObservation>;

package/build/src/git/observe.js

@@ -77,8 +77,12 @@ async function observeHeadCoordinates(repository) {
         throw error;
     }
 }
-/** Observe bind's tender start and optional reward target without creating persistent state. */
-export async function observeBindCoordinates(repository, selection = { kind: "targetless" }) {
+/**
+ * Observe bind's tender start and optional reward target without creating persistent state.
+ * `current-branch` reads the observed worktree coordinate's own attached branch; the caller names
+ * which coordinate it wants observed.
+ */
+export async function observeBindCoordinates(repository, selection) {
     if (selection.kind === "explicit") {
         const requestedTarget = selection.target;
         if (isKeiyakuOwnedRef(requestedTarget)) {

package/build/src/index.d.ts

@@ -45,17 +45,17 @@ export { actorId } from "./core/facts/types.js";
  * configuration helpers stay off this entry; only CLI and Body import them.
  */
 export { z } from "zod";
-export { ALLOWED_ACTIONS, Akuma, AkumaBusyError, AkumaDecodeError, AkumaNotBornError, AkumaProviderError, Schema, } from "./akuma/index.js";
-export type { ActivityHistory, ActivityRow, AkuId, AkumaAskObservation, AkumaAskOptions, AkumaAskResult, AkumaBirthInput, AkumaHistoryOptions, AkumaIdleOptions, AkumaIdleResult, AkumaSignalOptions, AkumaStatus, AkumaTellOptions, AkumaTellResult, AllowedAction, AllowedActions, InterruptReceipt, JsonSchema, JsonSchemaDocument, KillEvidence, SchemaLike, StandardSchemaV1, } from "./akuma/index.js";
+export { ALLOWED_ACTIONS, Akuma, AkumaArchetypeError, AkumaBusyError, AkumaDecodeError, AkumaNotBornError, AkumaProviderError, Schema, listArchetypeDefinitions, } from "./akuma/index.js";
+export type { AkumaCaller, AkumaOrigin, ActivityHistory, ActivityRow, AkuId, AkumaAskObservation, AkumaAskOptions, AkumaAskResult, AkumaBirthInput, AkumaHistoryOptions, AkumaHostOptions, AkumaIdleOptions, AkumaIdleResult, AkumaSignalOptions, AkumaStatus, AkumaTellOptions, AkumaTellResult, AllowedAction, AllowedActions, ArchetypeCatalog, ArchetypeCatalogInput, ArchetypeCatalogRow, InterruptReceipt, JsonSchema, JsonSchemaDocument, KillEvidence, SchemaLike, StandardSchemaV1, } from "./akuma/index.js";
 export type { ActorId, ChangeId, ContractHead, ContractId, ContractState, JournalEntry as Fact, FactKind, SnapshotId, } from "./core/facts/types.js";
-export { kanshi, observeKanshi, selectKanshi, selectRegion } from "./kanshi/index.js";
-export type { AkumaKanshiRow, AkumaKanshiWorld, ContractEndpointObservation, ContractHolderObservation, ContractKanshiBoard, ContractKanshiRow, KanshiInput, KanshiRegionSelection, KanshiReport, KanshiSelection, RegionDeclaration, RegionRead, Section, TaskKanshiRow, TaskKanshiWorld, } from "./kanshi/index.js";
+export { kanshi, kanshiCategory, observeKanshi, selectKanshi, selectRegion } from "./kanshi/index.js";
+export type { AkumaKanshiRow, AkumaKanshiWorld, ContractEndpointObservation, ContractHolderObservation, ContractKanshiBoard, ContractKanshiRow, KanshiCategoryInput, KanshiCategoryReport, KanshiInput, KanshiRegionSelection, KanshiReport, KanshiSelection, RegionDeclaration, RegionRead, Section, TaskKanshiRow, TaskKanshiWorld, } from "./kanshi/index.js";
 export { AkumaAddressError, AkumaWorldScopeError, Akumas } from "./library/akumas.js";
 export type { AkumaAddressInput, AkumaAskInput, AkumaHistoryInput, AkumaHistoryResult, AkumaKillInput, AkumaKillResult, AkumaList, AkumaListInput, AkumaObservation, AkumaObservationStage, AkumaTellInput, AkumaWaitInput, AkumaWaitResult, AkumaWorldScopeRefusal, CallInput, CallResult, CallWaitHead, CreatedTaskObservation, DispatchAssociation, DispatchStage, ForkInput, ForkResult, TellResult, TellWake, WaitObservedAkuma, WaitObserver, WaitSelectedAkuma, } from "./library/akumas.js";
 export type { ContinuationReport } from "./library/continuation.js";
 export type { KeiyakuLibrary, ReconcileInput } from "./library/contract-composition.js";
 export type { AbandonOutcome, AmendOutcome, ArcOutcome, AuditOutcome, BindOutcome, BindResult, DeliverOutcome, ReviewOutcome, } from "./library/contract-outcomes.js";
-export type { AbandonInput, AmendInput, ArcInput, BindInput, ContractHistory, ContractHistoryEvent, ContractList, ContractListInput, ContractObservationInput, DeliverInput, KeiyakuSelectInput, LocalContractComposition, ReviewInput, } from "./library/contract-types.js";
+export type { AbandonInput, AmendInput, ArcInput, BindInput, ContractHistory, ContractHistoryEvent, ContractList, ContractListInput, ContractObservationInput, ContractResolveInput, ContractResolution, ContractSelectorRefusal, DeliverInput, KeiyakuSelectInput, LocalContractComposition, ReviewInput, } from "./library/contract-types.js";
 export { nukeKeiyaku as nuke } from "./library/nuke.js";
 export type { NukeInput, NukeResult } from "./library/nuke.js";
 export type { InvocationEffect, KeiyakuErrorCategory, PartialOutcomeEnvelope, PendingSurface, ReconciliationLag, Review, } from "./library/outcome.js";
@@ -63,7 +63,7 @@ export type { ReconcileCompletion, RepoContractReconcileReport, RepoReconcileRep
 export type { KeiyakuRefusal, KeiyakuRetryReason, NukeConfirmationRefusal, NukeConfirmationRequiredRefusal, OperationRetries, } from "./library/refusal.js";
 export type { RegionOverlap } from "./library/region.js";
 export type { RepoAtInput } from "./library/repo.js";
-export type { KeiyakuPlugin, PluginBodyEnd, PluginContext, PluginHooks, PluginInstance, PluginManifest, PluginOutcome, PluginSignal, PluginSignalMap, } from "./plugin/public.js";
+export type { KeiyakuPlugin, PluginAkumaCaller, PluginAkumaOrigin, PluginBodyEnd, PluginContext, PluginHooks, PluginInstance, PluginManifest, PluginOutcome, PluginSignal, PluginSignalMap, } from "./plugin/public.js";
 export type { AuditReport } from "./protocol/audit.js";
 export type { IntegrationConflictMaterialized, VerificationReuse } from "./protocol/deliver.js";
 export type { ExecutionObservation, ExecutionObserver } from "./protocol/execution-observation.js";

package/build/src/index.js

@@ -45,8 +45,8 @@ export { actorId } from "./core/facts/types.js";
  * configuration helpers stay off this entry; only CLI and Body import them.
  */
 export { z } from "zod";
-export { ALLOWED_ACTIONS, Akuma, AkumaBusyError, AkumaDecodeError, AkumaNotBornError, AkumaProviderError, Schema, } from "./akuma/index.js";
-export { kanshi, observeKanshi, selectKanshi, selectRegion } from "./kanshi/index.js";
+export { ALLOWED_ACTIONS, Akuma, AkumaArchetypeError, AkumaBusyError, AkumaDecodeError, AkumaNotBornError, AkumaProviderError, Schema, listArchetypeDefinitions, } from "./akuma/index.js";
+export { kanshi, kanshiCategory, observeKanshi, selectKanshi, selectRegion } from "./kanshi/index.js";
 export { AkumaAddressError, AkumaWorldScopeError, Akumas } from "./library/akumas.js";
 export { nukeKeiyaku as nuke } from "./library/nuke.js";
 export { SettingsError, settings } from "./settings.js";

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

@@ -1,5 +1,5 @@
 export { kanshi, kanshiCategory, observeKanshi } from "./read.js";
 export { selectKanshi, selectRegion } from "./select.js";
-export type { KanshiInput } from "./read.js";
+export type { KanshiCategoryInput, KanshiInput } from "./read.js";
 export type { AkumaKanshiRow, AkumaKanshiWorld, ContractEndpointObservation, ContractHolderObservation, ContractKanshiBoard, ContractKanshiRow, KanshiCategoryReport, KanshiReport, Section, TaskKanshiRow, TaskKanshiWorld, KanshiRegionSelection, RegionDeclaration, RegionOverlap, RegionRead, } from "./report.js";
 export type { KanshiSelection } from "./select.js";

package/build/src/kanshi/read.js

@@ -89,6 +89,12 @@ function regionSelection(value) {
     }
     throw new TypeError(`kanshi region selection kind is invalid: ${selection.kind}`);
 }
+function worldCoordinate(world, repo) {
+    if (world !== null && (typeof world !== "string" || world.trim().length === 0))
+        throw new TypeError("kanshi world must be a WorldRoot or null");
+    if (repo !== undefined && !(repo instanceof Repo))
+        throw new TypeError("kanshi repo must be a Repo");
+}
 function coordinate(input) {
     if (typeof input !== "object" || input === null || Array.isArray(input))
         throw new TypeError("kanshi input must be an object");
@@ -97,11 +103,7 @@ function coordinate(input) {
             throw new TypeError(`kanshi input has unknown field: ${key}`);
         }
     }
-    if (input.world !== null && (typeof input.world !== "string" || input.world.trim().length === 0)) {
-        throw new TypeError("kanshi world must be a WorldRoot or null");
-    }
-    if (input.repo !== undefined && !(input.repo instanceof Repo))
-        throw new TypeError("kanshi repo must be a Repo");
+    worldCoordinate(input.world, input.repo);
     return {
         ...input,
         ...(input.region === undefined ? {} : { region: regionSelection(input.region) }),
@@ -498,9 +500,22 @@ async function observeContractCategory(world, repo, limit, observedAt) {
         return report({ kind: "failed", failure: { message: diagnostic(error) } });
     }
 }
+const DEFAULT_CATEGORY_LIMIT = 10;
+/** Caller-invalid category requests are refused here, before any owner observation runs. */
+function validateCategoryInput(input) {
+    const value = record(input, "category input");
+    exactKeys(value, ["world", "repo", "category", "limit"], "category input");
+    worldCoordinate(value.world, value.repo);
+    if (value.category !== "akuma" && value.category !== "contract")
+        throw new TypeError(`kanshi category is invalid: ${String(value.category)}`);
+    const { limit } = value;
+    if (limit !== undefined && (typeof limit !== "number" || !Number.isSafeInteger(limit) || limit < 1))
+        throw new TypeError("kanshi category limit must be a positive safe integer");
+}
 export async function kanshiCategory(input) {
     const observedAt = new Date().toISOString();
-    const { world, repo, category, limit = 10 } = input;
+    validateCategoryInput(input);
+    const { world, repo, category, limit = DEFAULT_CATEGORY_LIMIT } = input;
     if (category === "contract") {
         if (repo === undefined)
             throw new TypeError("kanshi contract category requires a Repo");

package/build/src/library/address.js

@@ -7,6 +7,7 @@ import { contractId } from "../core/facts/types.js";
 import { readDispatches } from "../dispatch/index.js";
 import { matchesAkumaGlob, parseReadableAkumaAlias, parseAkumaGlob, } from "../identity/selector.js";
 import { World } from "../world.js";
+import { matchContractCandidates } from "./contract-address.js";
 import { requireInput } from "./input.js";
 import { scopeForRepo } from "./repo.js";
 export class AkumaAddressError extends Error {
@@ -69,10 +70,7 @@ export function resolveNamedAddress(input) {
     if (selector.startsWith("aku/"))
         return { kind: "akuma", id: parseAddressId(selector).id };
     const alias = parseAddressAlias(selector);
-    const contractMatches = (input.report.contracts.kind === "present" ? input.report.contracts.value.rows : []).filter((row) => row.disposition === "active" &&
-        row.workspace === "worktree" &&
-        row.worktreePath !== null &&
-        `@${row.id.slice("kei/".length)}` === alias);
+    const contractMatches = matchContractCandidates(input.report.contracts.kind === "present" ? input.report.contracts.value.rows : [], { selector: alias });
     const aliasId = input.aliases.kind === "present"
         ? (input.aliases.value.find((binding) => binding.alias === alias)?.akuId ?? null)
         : null;

package/build/src/library/akuma-creation.d.ts

@@ -1,3 +1,4 @@
+import { type AkumaCaller } from "../akuma/caller.js";
 import { type ForkReceipt } from "../akuma/akuma-owner.js";
 import { type AskObserver } from "../akuma/akuma-selection-execution.js";
 import type { AkumaStatus } from "../akuma/akuma.js";
@@ -63,6 +64,7 @@ export type CallInput = Readonly<{
     allowed?: readonly AllowedAction[];
     schema?: Schema<unknown>;
     initiator?: string;
+    caller?: AkumaCaller;
     signal?: AbortSignal;
     observe?: CallWaitObserver;
 }>;
@@ -98,6 +100,8 @@ export type ForkInput = Readonly<{
     akuma: string;
     at: string;
     repo?: Repo;
+    caller?: AkumaCaller;
+    initiator?: string;
 }>;
 export type ForkResult = Readonly<{
     kind: "forked";
@@ -112,7 +116,7 @@ export type ForkResult = Readonly<{
 }>);
 export declare function callAkumas(input: CallInput & Readonly<{
     path: WorldRoot;
-}>, execution?: ExecutionContext): Promise<CallResult>;
+}>, execution?: ExecutionContext, reportDiagnostic?: (message: string) => void): Promise<CallResult>;
 export declare function forkAkumas(input: ForkInput & Readonly<{
     path: WorldRoot;
 }>): Promise<ForkResult>;

package/build/src/library/akuma-creation.js

@@ -1,11 +1,11 @@
 /** @architectureCompositionRoot */
 import { randomUUID } from "node:crypto";
 import { appendFile } from "node:fs/promises";
+import { decodeAkumaCaller } from "../akuma/caller.js";
 import { admitAkumaCall } from "../akuma/akuma-call.js";
 import { AkumaOwner } from "../akuma/akuma-owner.js";
 import { decodeAskObservation, observeAdmittedAskAkuma } from "../akuma/akuma-selection-execution.js";
 import { canonicalBirthCwd } from "../akuma/call-input.js";
-import { readSoul } from "../akuma/heart/index.js";
 import { pathsForAkuId } from "../akuma/identity.js";
 import { localExecutionContext } from "../akuma/requests.js";
 import { schemaJsonText } from "../akuma/schema.js";
@@ -13,7 +13,7 @@ import { moveAlias } from "../alias/index.js";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { publishDispatch, readDispatch } from "../dispatch/index.js";
 import { parseAkumaAlias } from "../identity/selector.js";
-import { emitCalledPluginSignal } from "../plugin/akuma-signals.js";
+import { outcomePluginObserver } from "../plugin/akuma-signals.js";
 import { World } from "../world.js";
 import { addressAkuma } from "./address.js";
 import { requireInput } from "./input.js";
@@ -100,52 +100,24 @@ function callSeat(contract) {
         throw new TypeError("contract must be a Keiyaku");
     return seat;
 }
-async function requestedParent(path, id) {
-    const soul = await readSoul(pathsForAkuId(path, id));
-    return soul?.origin.kind === "request" ? soul.origin.parent : undefined;
-}
 function pluginDiagnostic(error) {
     const message = error instanceof Error ? error.message : String(error);
     return message.length <= 500 ? message : `${message.slice(0, 500)}...`;
 }
-async function recordPluginDiagnostic(paths, error) {
+async function recordPluginDiagnostic(paths, error, occurrence) {
     try {
-        await appendFile(paths.log, `plugin call admission failed: ${pluginDiagnostic(error)}\n`);
+        await appendFile(paths.log, `plugin ${occurrence} failed: ${pluginDiagnostic(error)}\n`);
     }
     catch {
         // Plugin diagnostic loss must not change an already admitted call.
     }
 }
-/**
- * The submitting process's optional called-plugin observation. It runs once,
- * after the prepared executor returned its local value or the forwarded caller
- * received its exact live output, and it never gates birth, initial Tell, or a
- * later integration stage. A failed delivery stays a diagnostic.
- */
-async function emitCalledSignal(input) {
-    try {
-        const paths = pathsForAkuId(input.path, input.admitted.id);
-        const callerAkumaId = input.admitted.requested ? await requestedParent(input.path, input.admitted.id) : undefined;
-        const reportDiagnostic = (message) => {
-            void recordPluginDiagnostic(paths, message);
-        };
-        try {
-            await emitCalledPluginSignal({
-                world: input.path,
-                ...(input.settings === undefined ? {} : { settings: input.settings }),
-                reportDiagnostic,
-                akumaId: input.admitted.id,
-                ...(callerAkumaId === undefined ? {} : { callerAkumaId }),
-                ...(input.contractId === undefined ? {} : { contractId: input.contractId }),
-            });
-        }
-        catch (error) {
-            await recordPluginDiagnostic(paths, error);
-        }
-    }
-    catch {
-        // Plugin delivery must not change an already admitted call.
-    }
+function callDiagnosticSink(paths, occurrence, reportDiagnostic) {
+    return (message) => {
+        void recordPluginDiagnostic(paths, message, occurrence);
+        // Return the host's possible Promise for the plugin diagnostic isolation boundary.
+        return reportDiagnostic?.(message);
+    };
 }
 async function dispatchStage(input) {
     try {
@@ -210,6 +182,7 @@ const CALL_INPUT_KEYS = [
     "allowed",
     "schema",
     "initiator",
+    "caller",
     "signal",
     "observe",
 ];
@@ -220,6 +193,7 @@ async function parseCallInput(input) {
     const archetype = nonblank(values.archetype, "archetype");
     const body = callBody(values.body);
     const initiator = values.initiator === undefined ? undefined : text(values.initiator, "initiator");
+    const caller = decodeAkumaCaller(values.caller);
     const cwd = values.cwd === undefined ? undefined : nonblank(values.cwd, "cwd");
     const mode = callMode(values.mode);
     validateCallBodyOptions(body, values, mode);
@@ -253,6 +227,8 @@ async function parseCallInput(input) {
         ...(alias === undefined ? {} : { alias }),
         ...(values.allowed === undefined ? {} : { allowed: values.allowed }),
         seat,
+        ...(caller === undefined ? {} : { caller }),
+        ...(initiator === undefined ? {} : { initiator }),
         ...(initialTell === undefined ? {} : { initialTell }),
         ...(observe === undefined ? {} : { observe }),
     };
@@ -267,6 +243,8 @@ function callConfiguration(input, execution) {
 function callAdmissionInput(input, execution) {
     return {
         archetype: input.archetype,
+        ...(input.caller === undefined ? {} : { caller: input.caller }),
+        ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
         ...(input.initialTell === undefined
             ? {}
             : {
@@ -303,7 +281,7 @@ function failedCall(result, tellId, error, tell) {
         },
     };
 }
-async function observeCall(input) {
+async function observeCall(input, reportDiagnostic) {
     const onObserve = {
         admitted: async (receipt, id) => {
             await input.observe?.admitted?.(receipt, id, {
@@ -320,6 +298,11 @@ async function observeCall(input) {
             tellId: input.initialTell.tellId,
             timeoutMs: input.timeoutMs,
             receipt: input.receipt,
+            outcomeObserved: outcomePluginObserver({
+                world: input.path,
+                ...(input.settings === undefined ? {} : { settings: input.settings }),
+                reportDiagnostic: callDiagnosticSink(pathsForAkuId(input.path, input.akuma), "outcome observation", reportDiagnostic),
+            }),
             ...(input.signal === undefined ? {} : { signal: input.signal }),
             onObserve,
         });
@@ -351,7 +334,7 @@ function knownChildFailure(reason, akuma) {
 function asError(failure) {
     return failure instanceof Error ? failure : new Error(failure === undefined ? "call failed" : String(failure));
 }
-export async function callAkumas(input, execution = localExecutionContext()) {
+export async function callAkumas(input, execution = localExecutionContext(), reportDiagnostic) {
     const parsed = await parseCallInput(input);
     const selectedExecution = await resolveCallExecution(parsed.cwd === undefined ? {} : { cwd: parsed.cwd });
     const seat = parsed.seat;
@@ -359,14 +342,6 @@ export async function callAkumas(input, execution = localExecutionContext()) {
         ...callAdmissionInput(parsed, selectedExecution),
         ...(seat === undefined ? {} : { contractId: seat.id }),
     }, selectedExecution === undefined ? {} : { cwdCanonical: true });
-    // One caller-wiring sequence, after the prepared executor returned its local value
-    // or the forwarded caller received its exact live output, before outcome observation.
-    await emitCalledSignal({
-        path: parsed.path,
-        ...(parsed.settings === undefined ? {} : { settings: parsed.settings }),
-        admitted,
-        ...(seat === undefined ? {} : { contractId: seat.id }),
-    });
     const dispatch = seat === undefined
         ? { kind: "none" }
         : await dispatchStage({ repository: seat.scope, akuId: admitted.id, contractId: seat.id });
@@ -400,18 +375,25 @@ export async function callAkumas(input, execution = localExecutionContext()) {
             initialTell: parsed.initialTell,
             receipt,
             timeoutMs: parsed.timeoutMs,
+            ...(parsed.settings === undefined ? {} : { settings: parsed.settings }),
             ...(parsed.signal === undefined ? {} : { signal: parsed.signal }),
             ...(parsed.observe === undefined ? {} : { observe: parsed.observe }),
-        });
+        }, reportDiagnostic);
 }
 export async function forkAkumas(input) {
     const values = requireInput(input, "Akumas.fork input");
-    onlyKeys(values, ["path", "akuma", "at", "repo"], "Akumas.fork input");
+    onlyKeys(values, ["path", "akuma", "at", "repo", "caller", "initiator"], "Akumas.fork input");
+    const caller = decodeAkumaCaller(values.caller);
+    const initiator = values.initiator === undefined ? undefined : text(values.initiator, "initiator");
     const at = nonblank(values.at, "at");
     const addressed = await addressAkuma({ path: values.path, akuma: nonblank(values.akuma, "akuma") });
     const { path, id: akuma } = addressed;
     const repository = values.repo === undefined ? undefined : scopeForRepo(values.repo);
-    const receipt = await new AkumaOwner(akuma, path).fork({ at });
+    const receipt = await new AkumaOwner(akuma, path).fork({
+        at,
+        ...(caller === undefined ? {} : { caller }),
+        ...(initiator === undefined ? {} : { initiator }),
+    });
     if (receipt.kind !== "forked")
         return { ...receipt, parent: akuma };
     const dispatch = repository === undefined

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

@@ -1,8 +1,9 @@
 /** @architectureCompositionRoot */
+import { type AkumaHostOptions } from "../akuma/akuma-instance.js";
 import type { AkumaList, AkumaListInput } from "../akuma/akuma.js";
 import type { TellResult, TellWake } from "../akuma/body.js";
 import { type ExecutionContext } from "../akuma/requests.js";
-import type { DispatchAssociation } from "../dispatch/association.js";
+import type { DispatchAssociation } from "../akuma/dispatch-association.js";
 import type { CreatedTaskObservation } from "../task/created-observation.js";
 import { type WorldRoot } from "../world.js";
 import type { AkumaAddressInput, AkumaWorldScopeRefusal } from "./address.js";
@@ -18,7 +19,7 @@ export type { WaitObservedAkuma, WaitObserver, WaitSelectedAkuma } from "../akum
 export type Akumas = AkumasHandle;
 declare class AkumasHandle {
     #private;
-    constructor(world: WorldRoot, execution: ExecutionContext);
+    constructor(world: WorldRoot, execution: ExecutionContext, host?: AkumaHostOptions);
     list(input?: AkumaListInput): Promise<AkumaList>;
     call(input: CallInput): Promise<CallResult>;
     fork(input: ForkInput): Promise<ForkResult>;
@@ -34,7 +35,7 @@ declare class AkumasHandle {
  * The one Akumas composition. Public `of` fixes local execution; CLI and Body pass their captured
  * internal channel through `akumasWithExecution` instead of a second constructor.
  */
-export declare function akumasWithExecution(world: WorldRoot, execution: ExecutionContext): Akumas;
+export declare function akumasWithExecution(world: WorldRoot, execution: ExecutionContext, host?: AkumaHostOptions): Akumas;
 export declare const Akumas: Readonly<{
-    of(world: WorldRoot): Akumas;
+    of(world: WorldRoot, host?: AkumaHostOptions): Akumas;
 }>;