@astrosheep/keiyaku 4.6.7 → 4.6.9

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 { emitPluginSignal, outcomePluginObserver } 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,15 +100,11 @@ 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, occurrence = "call admission") {
+async function recordPluginDiagnostic(paths, error, occurrence) {
     try {
         await appendFile(paths.log, `plugin ${occurrence} failed: ${pluginDiagnostic(error)}\n`);
     }
@@ -116,30 +112,12 @@ async function recordPluginDiagnostic(paths, error, occurrence = "call admission
         // 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;
-        await emitPluginSignal({
-            world: input.path,
-            ...(input.settings === undefined ? {} : { settings: input.settings }),
-            reportDiagnostic: (message) => void recordPluginDiagnostic(paths, message),
-        }, {
-            kind: "akuma.called",
-            akumaId: input.admitted.id,
-            ...(callerAkumaId === undefined ? {} : { callerAkumaId }),
-            ...(input.contractId === undefined ? {} : { contractId: input.contractId }),
-        });
-    }
-    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 {
@@ -204,6 +182,7 @@ const CALL_INPUT_KEYS = [
     "allowed",
     "schema",
     "initiator",
+    "caller",
     "signal",
     "observe",
 ];
@@ -214,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);
@@ -247,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 }),
     };
@@ -261,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
             ? {}
             : {
@@ -297,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, {
@@ -317,9 +301,7 @@ async function observeCall(input) {
             outcomeObserved: outcomePluginObserver({
                 world: input.path,
                 ...(input.settings === undefined ? {} : { settings: input.settings }),
-                reportDiagnostic: (message) => {
-                    void recordPluginDiagnostic(pathsForAkuId(input.path, input.akuma), message, "outcome observation");
-                },
+                reportDiagnostic: callDiagnosticSink(pathsForAkuId(input.path, input.akuma), "outcome observation", reportDiagnostic),
             }),
             ...(input.signal === undefined ? {} : { signal: input.signal }),
             onObserve,
@@ -352,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;
@@ -360,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 });
@@ -404,16 +378,22 @@ export async function callAkumas(input, execution = localExecutionContext()) {
             ...(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,9 +1,10 @@
 /** @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 { CreatedTaskObservation } from "../task/created-observation.js";
+import type { DispatchAssociation } from "../akuma/dispatch-association.js";
+import type { CreatedDebtObservation } from "../debt/created-observation.js";
 import { type WorldRoot } from "../world.js";
 import type { AkumaAddressInput, AkumaWorldScopeRefusal } from "./address.js";
 import type { CallInput, CallResult, CallWaitHead, DispatchStage, ForkInput, ForkResult } from "./akuma-creation.js";
@@ -12,13 +13,12 @@ export { AkumaAddressError, AkumaWorldScopeError } from "./address.js";
 export type { AkumaAddressInput } from "./address.js";
 export type { CallInput, ForkInput } from "./akuma-creation.js";
 export type { AkumaAskInput, AkumaHistoryInput, AkumaKillInput, AkumaTellInput, AkumaWaitInput } from "./selection.js";
-export type { AkumaAskResult, AkumaHistoryResult, AkumaKillResult, AkumaList, AkumaListInput, AkumaObservation, AkumaObservationStage, AkumaTellResult, AkumaWaitResult, AkumaWorldScopeRefusal, CallResult, CallWaitHead, CreatedTaskObservation, DispatchAssociation, DispatchStage, ForkResult, TellResult, TellWake, };
+export type { AkumaAskResult, AkumaHistoryResult, AkumaKillResult, AkumaList, AkumaListInput, AkumaObservation, AkumaObservationStage, AkumaTellResult, AkumaWaitResult, AkumaWorldScopeRefusal, CallResult, CallWaitHead, CreatedDebtObservation, DispatchAssociation, DispatchStage, ForkResult, TellResult, TellWake, };
 /** The existing native wait-observation seam, exposed type-only for CLI composition. */
-export type { WaitObservedAkuma, WaitObserver, WaitSelectedAkuma } from "../akuma/akuma-wait.js";
 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 +34,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;
 }>;

package/build/src/library/akumas.js

@@ -1,3 +1,5 @@
+/** @architectureCompositionRoot */
+import { captureAkumaHostDiagnostic } from "../akuma/akuma-instance.js";
 import { readAkumaRoster } from "../akuma/akuma.js";
 import { localExecutionContext } from "../akuma/requests.js";
 import { readAliases } from "../alias/index.js";
@@ -10,11 +12,13 @@ class AkumasHandle {
     #world;
     #execution;
     #selection;
-    constructor(world, execution) {
+    #reportDiagnostic;
+    constructor(world, execution, host) {
         this.#world = world;
         this.#execution = execution;
         // One typed route seam captured at construction: no operation re-derives it.
-        this.#selection = selectionSeam(execution);
+        this.#reportDiagnostic = captureAkumaHostDiagnostic(host);
+        this.#selection = selectionSeam(execution, this.#reportDiagnostic);
         Object.freeze(this);
     }
     async list(input) {
@@ -25,13 +29,13 @@ class AkumasHandle {
         return withRosterAliases(roster, await readAliases(path));
     }
     call(input) {
-        return callAkumas(this.withWorld(input, "Akumas.call input"), this.#execution);
+        return callAkumas(this.withWorld(input, "Akumas.call input"), this.#execution, this.#reportDiagnostic);
     }
     fork(input) {
         return forkAkumas(this.withWorld(input, "Akumas.fork input"));
     }
     status(input) {
-        return statusAkuma(this.withWorld(input, "Akumas.status input"));
+        return statusAkuma(this.withWorld(input, "Akumas.status input"), this.#reportDiagnostic);
     }
     tell(input) {
         return tellAkumaOn(this.#selection, this.withWorld(input, "Akumas.tell input"));
@@ -46,7 +50,7 @@ class AkumasHandle {
         return killAkumaOn(this.#selection, this.withWorld(input, "Akumas.kill input"));
     }
     history(input) {
-        return historyAkuma(this.withWorld(input, "Akumas.history input"));
+        return historyAkuma(this.withWorld(input, "Akumas.history input"), this.#reportDiagnostic);
     }
     withWorld(input, label) {
         const values = requireInput(input, label);
@@ -72,13 +76,13 @@ function withRosterAliases(roster, bindings) {
  * 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 function akumasWithExecution(world, execution) {
+export function akumasWithExecution(world, execution, host) {
     if (typeof world !== "string")
         throw new TypeError("Akumas.of world must be a WorldRoot");
-    return new AkumasHandle(world, execution);
+    return new AkumasHandle(world, execution, host);
 }
 export const Akumas = Object.freeze({
-    of(world) {
-        return akumasWithExecution(world, localExecutionContext());
+    of(world, host) {
+        return akumasWithExecution(world, localExecutionContext(), host);
     },
 });

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

@@ -4,7 +4,7 @@ import type { GitDecodeChannel } from "../git/read-observation.js";
 import { type BindTargetSelection } from "../protocol/bind.js";
 import { type IntentOutcome, type RepositoryScope } from "../protocol/operations.js";
 import type { ProtocolProgress } from "../protocol/progress.js";
-import type { TaskId } from "../task/identity.js";
+import type { DebtId } from "../debt/identity.js";
 import type { ForkSourceRefusal, OperationRefusals } from "./refusal.js";
 type ForkBindAdmission = Readonly<{
     kind: "document";
@@ -21,7 +21,7 @@ export declare function admitForkBindWithAppointment(input: Readonly<{
     scope: RepositoryScope;
     channel: GitDecodeChannel;
     sourceId: ContractId;
-    target?: string;
+    target?: string | null;
     progress?: ProtocolProgress;
     actor?: ActorId;
 }>): Promise<Readonly<{
@@ -35,8 +35,8 @@ export declare function prepareMarkdownBind(input: Readonly<{
     gates: readonly import("../core/facts/types.js").Gate[];
     after: readonly ContractId[];
     workspace: "worktree";
-    targetSelection?: BindTargetSelection;
-    task?: TaskId;
+    targetSelection: BindTargetSelection;
+    debt?: DebtId;
     progress?: ProtocolProgress;
     actor?: ActorId;
 }>): Promise<{
@@ -45,16 +45,16 @@ export declare function prepareMarkdownBind(input: Readonly<{
         result: IntentOutcome<Readonly<{
             contractId: ContractId;
         }>, {
-            kind: "contract-exists" | "invalid-after" | "unknown-prerequisite";
-            contractId: ContractId;
-        } | {
             kind: "verification-declaration-invalid";
             contractId?: ContractId | undefined;
+        } | {
+            kind: "target-missing" | "unborn-head" | "invalid-target";
         } | {
             kind: "fork-source-moved";
             contractId: ContractId;
         } | {
-            kind: "unborn-head" | "target-missing" | "invalid-target";
+            kind: "contract-exists" | "invalid-after" | "unknown-prerequisite";
+            contractId: ContractId;
         } | {
             kind: "fork-source-missing" | "fork-source-unavailable";
             contractId: ContractId;
@@ -64,36 +64,36 @@ export declare function prepareMarkdownBind(input: Readonly<{
         result: IntentOutcome<Readonly<{
             contractId: ContractId;
         }>, {
-            kind: "contract-exists" | "invalid-after" | "unknown-prerequisite";
-            contractId: ContractId;
-        } | {
             kind: "verification-declaration-invalid";
             contractId?: ContractId | undefined;
+        } | {
+            kind: "target-missing" | "unborn-head" | "invalid-target";
         } | {
             kind: "fork-source-moved";
             contractId: ContractId;
         } | {
-            kind: "unborn-head" | "target-missing" | "invalid-target";
+            kind: "contract-exists" | "invalid-after" | "unknown-prerequisite";
+            contractId: ContractId;
         } | {
             kind: "fork-source-missing" | "fork-source-unavailable";
             contractId: ContractId;
         }>;
-        taskId: TaskId;
+        debtId: DebtId;
         diagnostic: string;
     }>) | null;
     result: IntentOutcome<Readonly<{
         contractId: ContractId;
     }>, {
-        kind: "contract-exists" | "invalid-after" | "unknown-prerequisite";
-        contractId: ContractId;
-    } | {
         kind: "verification-declaration-invalid";
         contractId?: ContractId | undefined;
+    } | {
+        kind: "target-missing" | "unborn-head" | "invalid-target";
     } | {
         kind: "fork-source-moved";
         contractId: ContractId;
     } | {
-        kind: "unborn-head" | "target-missing" | "invalid-target";
+        kind: "contract-exists" | "invalid-after" | "unknown-prerequisite";
+        contractId: ContractId;
     } | {
         kind: "fork-source-missing" | "fork-source-unavailable";
         contractId: ContractId;

package/build/src/library/bind.js

@@ -7,11 +7,19 @@ import { mintIdentitySegment } from "../identity/mint.js";
 import { fitIdentityStemWords, normalizeIdentityStem } from "../identity/normalize.js";
 import { bindOperation } from "../protocol/bind.js";
 import { stateOperation } from "../protocol/operations.js";
-import { admitWithTaskHolderFence, claimTaskHolder } from "../settlement/holder.js";
+import { admitWithDebtHolderFence, claimDebtHolder } from "../settlement/holder.js";
 import { KeiyakuError } from "./outcome.js";
 import { contractTerms, documentDerivation } from "./input.js";
 const CONTRACT_ID_CODE_POINTS = 32;
 const CONTRACT_ID_ATTEMPTS = 4;
+/** A fork with no target copies its source; `null` clears it and a string overrides it. */
+function forkTargetSelection(target, sourceTarget) {
+    if (target === null)
+        return { kind: "targetless" };
+    if (target !== undefined)
+        return { kind: "explicit", target };
+    return sourceTarget === undefined ? { kind: "targetless" } : { kind: "explicit", target: sourceTarget };
+}
 function drawContractSuffix() {
     return randomBytes(2).toString("hex");
 }
@@ -22,14 +30,14 @@ async function attempt(input, id) {
         terms: input.terms,
         verification: input.verification,
         workspace: input.workspace,
+        targetSelection: input.targetSelection,
         ...(input.coordinates === undefined ? {} : { coordinates: input.coordinates }),
         ...(input.source === undefined ? {} : { source: input.source }),
         contractId: id,
-        ...(input.targetSelection === undefined ? {} : { targetSelection: input.targetSelection }),
-        ...(input.task === undefined
+        ...(input.debt === undefined
             ? {}
             : {
-                decorateOffer: ({ contractId: owner }) => [claimTaskHolder(input.task, owner)],
+                decorateOffer: ({ contractId: owner }) => [claimDebtHolder(input.debt, owner)],
             }),
         ...(input.actor === undefined ? {} : { actor: input.actor }),
         ...(input.progress === undefined ? {} : { progress: input.progress }),
@@ -99,11 +107,7 @@ export async function admitForkBindWithAppointment(input) {
         terms,
         verification: documentDerivation(document, terms.gates).verification,
         workspace: "worktree",
-        targetSelection: input.target === undefined
-            ? source.coordinates.target === undefined
-                ? { kind: "targetless" }
-                : { kind: "explicit", target: source.coordinates.target }
-            : { kind: "explicit", target: input.target },
+        targetSelection: forkTargetSelection(input.target, source.coordinates.target),
         coordinates: { start: source.coordinates.start },
         source: {
             contractId: input.sourceId,
@@ -125,11 +129,11 @@ export async function prepareMarkdownBind(input) {
         terms,
         verification: documentDerivation(input.document, terms.gates).verification,
         workspace: input.workspace,
-        ...(input.targetSelection === undefined ? {} : { targetSelection: input.targetSelection }),
-        ...(input.task === undefined ? {} : { task: input.task }),
+        targetSelection: input.targetSelection,
+        ...(input.debt === undefined ? {} : { debt: input.debt }),
         ...(input.actor === undefined ? {} : { actor: input.actor }),
         ...(input.progress === undefined ? {} : { progress: input.progress }),
     });
-    const admission = input.task === undefined ? null : await admitWithTaskHolderFence(input.scope, input.task, admitCandidate);
+    const admission = input.debt === undefined ? null : await admitWithDebtHolderFence(input.scope, input.debt, admitCandidate);
     return { admission, result: admission === null ? await admitCandidate() : admission.result };
 }

package/build/src/library/contract-address.d.ts

@@ -0,0 +1,9 @@
+import type { ContractRow } from "../protocol/read/status.js";
+import type { ContractResolution, ContractResolveInput } from "./contract-types.js";
+/** Pure Contract membership shared with mixed Address; no cross-family judgment. */
+export declare function matchContractCandidates(rows: readonly ContractRow[], selection: Readonly<{
+    selector: string;
+}> | Readonly<{
+    cwd: string;
+}>): readonly ContractRow[];
+export declare function resolveContract(input: ContractResolveInput): Promise<ContractResolution>;

package/build/src/library/contract-address.js

@@ -0,0 +1,71 @@
+import { realpath, stat } from "node:fs/promises";
+import { isAbsolute, normalize } from "node:path";
+import { contractId } from "../core/facts/types.js";
+import { withGitDecodeChannel } from "../git/read-observation.js";
+import { contractsOperation } from "../protocol/operations.js";
+import { requireInput } from "./input.js";
+import { readContractValue } from "./outcome.js";
+import { scopeForRepo } from "./repo.js";
+/** Pure Contract membership shared with mixed Address; no cross-family judgment. */
+export function matchContractCandidates(rows, selection) {
+    return rows.filter((row) => row.disposition === "active" &&
+        row.workspace === "worktree" &&
+        row.worktreePath !== null &&
+        ("selector" in selection
+            ? `@${row.id.slice("kei/".length)}` === selection.selector
+            : normalize(row.worktreePath) === selection.cwd));
+}
+export async function resolveContract(input) {
+    const values = requireInput(input, "Keiyaku.with().resolve input", ["repo", "selector", "cwd"]);
+    const scope = scopeForRepo(values.repo);
+    const selector = values.selector;
+    if (selector !== undefined && typeof selector !== "string")
+        throw new TypeError("selector must be a string");
+    const suppliedCwd = values.cwd;
+    if (suppliedCwd !== undefined && (typeof suppliedCwd !== "string" || !isAbsolute(suppliedCwd)))
+        throw new TypeError("cwd must be an absolute directory coordinate");
+    let cwd = scope.invocationWorktree;
+    if (typeof suppliedCwd === "string") {
+        try {
+            cwd = await realpath(suppliedCwd);
+            if (!(await stat(cwd)).isDirectory())
+                throw new TypeError("cwd must be a directory");
+        }
+        catch (cause) {
+            throw new TypeError("cwd must be an absolute directory coordinate", { cause });
+        }
+    }
+    if (selector !== undefined) {
+        if (selector.startsWith("@kei/"))
+            return { kind: "refused", refusal: { kind: "redundant-short-selector", selector } };
+        try {
+            const id = contractId(selector.startsWith("@") ? `kei/${selector.slice(1)}` : selector);
+            if (!selector.startsWith("@"))
+                return { kind: "resolved", id };
+        }
+        catch (error) {
+            return {
+                kind: "refused",
+                refusal: {
+                    kind: "invalid-selector",
+                    selector,
+                    diagnostic: error instanceof Error ? error.message : String(error),
+                },
+            };
+        }
+    }
+    const board = await readContractValue(() => withGitDecodeChannel(scope, (channel) => contractsOperation({ scope, channel })));
+    const candidates = matchContractCandidates(board.rows, selector === undefined ? { cwd } : { selector });
+    if (candidates.length === 1)
+        return { kind: "resolved", id: candidates[0].id };
+    if (selector === undefined) {
+        return {
+            kind: "refused",
+            refusal: candidates.length === 0 ? { kind: "no-contextual-match", cwd } : { kind: "ambiguous-selector", cwd },
+        };
+    }
+    return {
+        kind: "refused",
+        refusal: candidates.length === 0 ? { kind: "unknown-short-selector", selector } : { kind: "ambiguous-selector", selector },
+    };
+}

package/build/src/library/contract-composition.d.ts

@@ -1,9 +1,8 @@
 /** @architectureCompositionRoot */
 import { type LibraryExecution } from "../akuma/requests.js";
-import type { BindTargetSelection } from "../protocol/bind.js";
 import type { ContractObservation } from "../protocol/read/status.js";
 import type { BindOutcome } from "./contract-outcomes.js";
-import type { BindInput, ContractList, ContractListInput, ContractObservationInput, KeiyakuSelectInput, LocalContractComposition } from "./contract-types.js";
+import type { BindInput, ContractList, ContractListInput, ContractObservationInput, ContractResolveInput, ContractResolution, KeiyakuSelectInput, LocalContractComposition } from "./contract-types.js";
 import type { Keiyaku, createKeiyakuHandle } from "./keiyaku.js";
 import { type ReconcileCompletion, type RepoReconcileReport } from "./reconcile.js";
 import { type Repo } from "./repo.js";
@@ -24,6 +23,7 @@ interface KeiyakuLibraryReconcile {
 export type KeiyakuLibrary = Readonly<{
     bind(input: BindInput): Promise<BindOutcome>;
     select(input: KeiyakuSelectInput): Keiyaku;
+    resolve(input: ContractResolveInput): Promise<ContractResolution>;
     list(input: ContractListInput): Promise<ContractList>;
     observe(input: ContractObservationInput): Promise<ContractObservation>;
     reconcile: KeiyakuLibraryReconcile;
@@ -32,12 +32,9 @@ export type KeiyakuLibrary = Readonly<{
  * The one private Contract composition constructor. `Keiyaku.with` fixes local execution; CLI and
  * Body pass their captured internal channel explicitly here instead of a second constructor. The
  * carrier is a positional argument, never a field of the public construction input, so no runtime
- * value reaching the public surface can select a private channel. `omittedMarkdownTarget` is the
- * internal bind intent an edge supplies for a Markdown bind whose caller omitted the target; the
- * public package-root composition leaves it targetless.
+ * value reaching the public surface can select a private channel.
  */
-export declare function composeContractLibrary(execution: LibraryExecution, createHandle: typeof createKeiyakuHandle, input?: LocalContractComposition, omittedMarkdownTarget?: BindTargetSelection): KeiyakuLibrary;
+export declare function composeContractLibrary(execution: LibraryExecution, createHandle: typeof createKeiyakuHandle, input?: LocalContractComposition): KeiyakuLibrary;
 export declare function listKeiyaku(input: ContractListInput): Promise<ContractList>;
 export declare function observeKeiyaku(input: ContractObservationInput): Promise<ContractObservation>;
-export declare function readContractValue<Value>(operation: () => Promise<Value>): Promise<Value>;
 export {};

package/build/src/library/contract-composition.js

@@ -3,25 +3,25 @@ import { localExecutionContext } from "../akuma/requests.js";
 import { contractId } from "../core/facts/types.js";
 import { withGitDecodeChannel } from "../git/read-observation.js";
 import { contractCatalogueOperation, contractObservationOperation, contractsOperation, } from "../protocol/operations.js";
+import { resolveContract } from "./contract-address.js";
 import { bindKeiyaku } from "./contract-creation.js";
 import { captureLocalContractComposition, derivedHooks, } from "./contract-settings.js";
 import { requireInput } from "./input.js";
-import { KeiyakuError, errorCategory } from "./outcome.js";
+import { readContractValue } from "./outcome.js";
 import { completeReconcile, completeRepoReconcile, } from "./reconcile.js";
 import { scopeForRepo } from "./repo.js";
 /**
  * The one private Contract composition constructor. `Keiyaku.with` fixes local execution; CLI and
  * Body pass their captured internal channel explicitly here instead of a second constructor. The
  * carrier is a positional argument, never a field of the public construction input, so no runtime
- * value reaching the public surface can select a private channel. `omittedMarkdownTarget` is the
- * internal bind intent an edge supplies for a Markdown bind whose caller omitted the target; the
- * public package-root composition leaves it targetless.
+ * value reaching the public surface can select a private channel.
  */
-export function composeContractLibrary(execution, createHandle, input, omittedMarkdownTarget = { kind: "targetless" }) {
+export function composeContractLibrary(execution, createHandle, input) {
     const composition = captureLocalContractComposition(input);
     return Object.freeze({
-        bind: (operation) => bindKeiyaku(operation, createHandle, execution, composition, omittedMarkdownTarget),
+        bind: (operation) => bindKeiyaku(operation, createHandle, execution, composition),
         select: (operation) => selectKeiyaku(operation, createHandle, execution, composition),
+        resolve: resolveContract,
         list: (operation) => listKeiyaku(operation),
         observe: (operation) => observeKeiyaku(operation),
         reconcile: reconcileOperation(composition),
@@ -93,15 +93,3 @@ export async function observeKeiyaku(input) {
     }
     return readContractValue(() => withGitDecodeChannel(scope, (channel) => contractObservationOperation({ scope, channel, contractId: id })));
 }
-export async function readContractValue(operation) {
-    try {
-        return await operation();
-    }
-    catch (error) {
-        if (error instanceof KeiyakuError)
-            throw error;
-        throw new KeiyakuError(errorCategory(error), error instanceof Error ? error.message : String(error), {
-            cause: error,
-        });
-    }
-}

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

@@ -1,13 +1,11 @@
 /** @architectureCompositionRoot */
 import { type ExecutionContext } from "../akuma/requests.js";
-import type { BindTargetSelection } from "../protocol/bind.js";
 import type { BindOutcome } from "./contract-outcomes.js";
 import { type LocalContractCompositionCapture } from "./contract-settings.js";
 import type { BindInput } from "./contract-types.js";
 import type { createKeiyakuHandle } from "./keiyaku.js";
 /**
- * One Contract bind. `omittedMarkdownTarget` is the internal composition input an edge
- * supplies for a Markdown bind whose caller omitted the target: the public package-root
- * composition leaves it targetless, while the CLI names the invocation branch.
+ * One Contract bind. An omitted Markdown target names the current branch of the caller's explicit
+ * Repo worktree coordinate, `null` is deliberately targetless, and a string is that literal target.
  */
-export declare function bindKeiyaku(input: BindInput, createHandle: typeof createKeiyakuHandle, execution?: ExecutionContext, composition?: LocalContractCompositionCapture, omittedMarkdownTarget?: BindTargetSelection): Promise<BindOutcome>;
+export declare function bindKeiyaku(input: BindInput, createHandle: typeof createKeiyakuHandle, execution?: ExecutionContext, composition?: LocalContractCompositionCapture): Promise<BindOutcome>;