@astrosheep/keiyaku 4.5.26 → 4.5.28

package/build/src/identity/selector.js

@@ -1,8 +1,20 @@
-const AKUMA_ALIAS_PATTERN = /^@[a-z][a-z0-9-]{0,63}$/u;
+import { MAX_AKUMA_NAME_BYTES, normalizeIdentityStem, validateAkumaName } from "./normalize.js";
 const AKUMA_GLOB_SUFFIX = /^[0-9a-f*]+$/u;
+const LEGACY_AKUMA_ALIAS_PATTERN = /^@[a-z][a-z0-9-]{0,63}$/u;
+// Old alias spellings remain readable, but new bindings use canonical Akuma names.
+export function parseReadableAkumaAlias(value) {
+    if (LEGACY_AKUMA_ALIAS_PATTERN.test(value))
+        return value;
+    return parseAkumaAlias(value);
+}
 export function parseAkumaAlias(value) {
-    if (!AKUMA_ALIAS_PATTERN.test(value)) {
-        throw new TypeError("Akuma alias must match ^@[a-z][a-z0-9-]{0,63}$");
+    if (!value.startsWith("@"))
+        throw new TypeError("Akuma alias selector must start with @");
+    try {
+        validateAkumaName(value.slice(1));
+    }
+    catch {
+        throw new TypeError(`Akuma alias name must be a normalized Akuma name of at most ${MAX_AKUMA_NAME_BYTES} UTF-8 bytes`);
     }
     return value;
 }
@@ -26,4 +38,3 @@ export function matchesAkumaGlob(glob, value) {
         .replaceAll("*", "[^/]*");
     return new RegExp(`^${pattern}$`, "u").test(value);
 }
-import { normalizeIdentityStem } from "./normalize.js";

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

@@ -28,6 +28,17 @@ export type AkumaWorldScopeRefusal = Readonly<{
     ids: readonly AkuId[];
     world: WorldRoot;
 }>;
+export type AkumaAddressRefusal = Readonly<{
+    kind: "akuma-alias-not-found";
+    alias: AkumaAlias;
+}> | Readonly<{
+    kind: "invalid-akuma";
+    selector: string;
+}>;
+export declare class AkumaAddressError extends Error {
+    readonly refusal: AkumaAddressRefusal;
+    constructor(refusal: AkumaAddressRefusal);
+}
 export declare class AkumaWorldScopeError extends TypeError {
     readonly refusal: AkumaWorldScopeRefusal;
     constructor(refusal: AkumaWorldScopeRefusal);
@@ -45,15 +56,34 @@ export type NamedAddressInput = Readonly<{
     aliases: Section<readonly AliasBinding[]>;
 }>;
 export declare function resolveNamedAddress(input: NamedAddressInput): NamedAddress;
-export declare function addressAkuma(input: UncheckedAkumaAddressInput): Promise<Readonly<{
+type AddressedAkuma = Readonly<{
     path: WorldRoot;
     id: AkuId;
+}>;
+/**
+ * Resolves one selector to a complete identity without proving it born. The
+ * caller is a forwarding boundary: the parent Fleet answers for the target, so
+ * this process must not read its own Heart files to decide.
+ */
+export declare function resolveAkuma(input: UncheckedAkumaAddressInput): Promise<AddressedAkuma>;
+/**
+ * Resolves one selector against this World, where a local caller is answered
+ * for the target's birth by the one addressability normalization.
+ */
+export declare function addressAkuma(input: UncheckedAkumaAddressInput): Promise<AddressedAkuma>;
+/**
+ * Resolves a selector set to complete identities without proving any born. The
+ * caller is a forwarding boundary, the parent Fleet owns the answer, and no
+ * member's Heart is read here.
+ */
+export declare function resolveAkumaSet(input: UncheckedAkumaAddressInput): Promise<Readonly<{
+    path: WorldRoot;
+    ids: readonly AkuId[];
+    orderedIds: readonly AkuId[];
 }>>;
 export declare function addressAkumaSet(input: UncheckedAkumaAddressInput): Promise<Readonly<{
     path: WorldRoot;
-    /** The complete selected set in canonical order. */
     ids: readonly AkuId[];
-    /** The same set in the caller's selector order, for surfaces that name the selection as chosen. */
     orderedIds: readonly AkuId[];
 }>>;
 export {};

package/build/src/library/address.js

@@ -1,14 +1,24 @@
 /** @architectureCompositionRoot */
 import { readAliases } from "../alias/index.js";
 import { createAkumaProduct } from "../akuma/akuma-product.js";
-import { probeBornAkuma } from "../akuma/akuma-probe.js";
+import { akumaAddressability, requireBornAkuma } from "../akuma/akuma-probe.js";
 import { parseAkuId } from "../akuma/identity.js";
 import { contractId } from "../core/facts/types.js";
 import { readDispatches } from "../dispatch/index.js";
-import { matchesAkumaGlob, parseAkumaAlias, parseAkumaGlob, } from "../identity/selector.js";
+import { matchesAkumaGlob, parseReadableAkumaAlias, parseAkumaGlob, } from "../identity/selector.js";
 import { World } from "../world.js";
 import { requireInput } from "./input.js";
 import { scopeForRepo } from "./repo.js";
+export class AkumaAddressError extends Error {
+    refusal;
+    constructor(refusal) {
+        super(refusal.kind === "akuma-alias-not-found"
+            ? `unknown Akuma alias: ${refusal.alias}`
+            : `invalid Akuma: ${refusal.selector}`);
+        this.refusal = refusal;
+        this.name = "AkumaAddressError";
+    }
+}
 export class AkumaWorldScopeError extends TypeError {
     refusal;
     constructor(refusal) {
@@ -22,23 +32,43 @@ function nonblank(value, label) {
         throw new TypeError(`${label} must be a nonblank string`);
     return value;
 }
+function parseAddressAlias(selector) {
+    try {
+        return parseReadableAkumaAlias(selector);
+    }
+    catch (error) {
+        if (!(error instanceof TypeError))
+            throw error;
+        throw new AkumaAddressError({ kind: "invalid-akuma", selector });
+    }
+}
+function parseAddressId(selector) {
+    try {
+        return parseAkuId(selector);
+    }
+    catch (error) {
+        if (!(error instanceof TypeError))
+            throw error;
+        throw new AkumaAddressError({ kind: "invalid-akuma", selector });
+    }
+}
 async function directId(path, selector) {
     if (selector.startsWith("@")) {
-        const alias = parseAkumaAlias(selector);
+        const alias = parseAddressAlias(selector);
         const resolved = (await readAliases(path)).find((binding) => binding.alias === alias)?.akuId ?? null;
         if (resolved === null)
-            throw new TypeError(`unknown Akuma alias: ${alias}`);
+            throw new AkumaAddressError({ kind: "akuma-alias-not-found", alias });
         return resolved;
     }
-    return parseAkuId(selector).id;
+    return parseAddressId(selector).id;
 }
 export function resolveNamedAddress(input) {
     const selector = nonblank(input.selector, "selector");
     if (selector.startsWith("kei/"))
         return { kind: "contract", id: contractId(selector) };
     if (selector.startsWith("aku/"))
-        return { kind: "akuma", id: parseAkuId(selector).id };
-    const alias = parseAkumaAlias(selector);
+        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 &&
@@ -62,9 +92,14 @@ export function resolveNamedAddress(input) {
     if (input.aliases.kind === "failed") {
         throw new TypeError("cannot resolve a named selector while Alias authority is failed");
     }
-    throw new TypeError(`unknown selector: ${selector}`);
+    throw new AkumaAddressError({ kind: "akuma-alias-not-found", alias });
 }
-export async function addressAkuma(input) {
+/**
+ * Resolves one selector to a complete identity without proving it born. The
+ * caller is a forwarding boundary: the parent Fleet answers for the target, so
+ * this process must not read its own Heart files to decide.
+ */
+export async function resolveAkuma(input) {
     const values = requireInput(input, "Akuma address input");
     for (const key of Object.keys(values)) {
         if (!["path", "akuma", "repo"].includes(key)) {
@@ -74,7 +109,17 @@ export async function addressAkuma(input) {
     if (values.repo !== undefined)
         scopeForRepo(values.repo);
     const path = await World.prove(nonblank(values.path, "path"));
-    return { path, id: await directId(path, nonblank(values.akuma, "akuma")) };
+    const id = await directId(path, nonblank(values.akuma, "akuma"));
+    return { path, id };
+}
+/**
+ * Resolves one selector against this World, where a local caller is answered
+ * for the target's birth by the one addressability normalization.
+ */
+export async function addressAkuma(input) {
+    const addressed = await resolveAkuma(input);
+    await requireBornAkuma(addressed.path, addressed.id);
+    return addressed;
 }
 function parseSetSelector(raw) {
     const selector = nonblank(raw, "akuma selector");
@@ -83,13 +128,13 @@ function parseSetSelector(raw) {
     if (selector.includes("*"))
         return { kind: "glob", value: parseAkumaGlob(selector) };
     if (selector.startsWith("@"))
-        return { kind: "alias", value: parseAkumaAlias(selector) };
-    return { kind: "direct", value: parseAkuId(selector).id };
+        return { kind: "alias", value: parseAddressAlias(selector) };
+    return { kind: "direct", value: parseAddressId(selector).id };
 }
 function hasSelectorKind(selectors, kind) {
     return selectors.some((selector) => selector.kind === kind);
 }
-function addSelectorIds(selector, sources, selected, contractMembers) {
+function addSelectorIds(selector, sources, selected, contractMembers, explicit) {
     if (selector.kind === "contract") {
         for (const dispatch of sources.dispatches) {
             if (dispatch.contractId !== selector.value)
@@ -108,20 +153,18 @@ function addSelectorIds(selector, sources, selected, contractMembers) {
     if (selector.kind === "alias") {
         const id = sources.aliases.get(selector.value);
         if (id === undefined)
-            throw new TypeError(`unknown Akuma alias: ${selector.value}`);
+            throw new AkumaAddressError({ kind: "akuma-alias-not-found", alias: selector.value });
         selected.add(id);
+        explicit.add(id);
         return;
     }
     selected.add(selector.value);
+    explicit.add(selector.value);
 }
 async function contractMemberInWorld(path, id) {
-    try {
-        return await probeBornAkuma(path, id);
-    }
-    catch {
-        // A dispatched physical member remains selected when its Heart cannot be read.
-        return true;
-    }
+    // A dispatched physical member stays selected when its Heart cannot be read:
+    // the World, not this reader, remains the authority on its membership.
+    return (await akumaAddressability(path, id)).kind !== "absent";
 }
 async function refuseForeignContractMembers(path, ids, contractMembers) {
     const foreign = [];
@@ -132,7 +175,13 @@ async function refuseForeignContractMembers(path, ids, contractMembers) {
     if (foreign.length > 0)
         throw new AkumaWorldScopeError({ kind: "akuma-not-in-world", ids: foreign, world: path });
 }
-export async function addressAkumaSet(input) {
+function canonicalAkumaOrder(selected) {
+    const ids = [...selected].sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+    if (ids.length === 0)
+        throw new TypeError("Akuma selector snapshot is empty");
+    return ids;
+}
+async function readAkumaSet(input) {
     const values = requireInput(input, "Akuma set address input");
     for (const key of Object.keys(values)) {
         if (!["path", "akuma", "repo"].includes(key)) {
@@ -157,13 +206,25 @@ export async function addressAkumaSet(input) {
         : [];
     const selected = new Set();
     const contractMembers = new Set();
+    const explicit = new Set();
     const sources = { fleetIds, aliases, dispatches };
     for (const selector of selectors)
-        addSelectorIds(selector, sources, selected, contractMembers);
-    const orderedIds = [...selected];
-    const ids = [...selected].sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
-    if (ids.length === 0)
-        throw new TypeError("Akuma selector snapshot is empty");
-    await refuseForeignContractMembers(path, ids, contractMembers);
-    return { path, ids, orderedIds };
+        addSelectorIds(selector, sources, selected, contractMembers, explicit);
+    return { path, orderedIds: [...selected], ids: canonicalAkumaOrder(selected), contractMembers, explicit };
+}
+/**
+ * Resolves a selector set to complete identities without proving any born. The
+ * caller is a forwarding boundary, the parent Fleet owns the answer, and no
+ * member's Heart is read here.
+ */
+export async function resolveAkumaSet(input) {
+    const resolved = await readAkumaSet(input);
+    return { path: resolved.path, ids: resolved.ids, orderedIds: resolved.orderedIds };
+}
+export async function addressAkumaSet(input) {
+    const resolved = await readAkumaSet(input);
+    for (const id of resolved.explicit)
+        await requireBornAkuma(resolved.path, id);
+    await refuseForeignContractMembers(resolved.path, resolved.ids, resolved.contractMembers);
+    return { path: resolved.path, ids: resolved.ids, orderedIds: resolved.orderedIds };
 }

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

@@ -73,7 +73,7 @@ export type CallResult = Readonly<{
     readonly?: ReadonlyRestraint;
     execution: Readonly<{
         cwd: string;
-        source: "input" | "contract-worktree" | "caller" | "process" | "world";
+        source: "input" | "caller" | "process" | "world";
     }>;
     dispatch: DispatchStage;
     alias: AliasStage;

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

@@ -9,7 +9,6 @@ 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 { readManagedWorktreeAppointment } from "../workspace-place.js";
 import { World } from "../world.js";
 import { Akuma as PublicAkuma } from "../akuma/akuma-instance.js";
 import { requestForwardedFleetTellAnswer } from "../akuma/fleet-request.js";
@@ -17,7 +16,6 @@ import { localExecutionContext } from "../akuma/requests.js";
 import { callReadonly, canonicalBirthCwd } from "../akuma/call-input.js";
 import { requireInput } from "./input.js";
 import { addressAkuma } from "./address.js";
-import { KeiyakuRefused } from "./contract.js";
 import { seatForKeiyaku } from "./contract-handle.js";
 import { scopeForRepo } from "./repo.js";
 function nonblank(value, label) {
@@ -67,10 +65,10 @@ function integrationFailure(error) {
     };
 }
 function callMode(value) {
-    if (value === undefined || value === "wait")
-        return "wait";
-    if (value === "detach")
+    if (value === undefined || value === "detach")
         return "detach";
+    if (value === "wait")
+        return "wait";
     throw new TypeError("mode must be wait or detach");
 }
 function callTimeout(value, mode) {
@@ -196,49 +194,13 @@ async function forkDispatchStage(input) {
         return { kind: "failed", failure: integrationFailure(error) };
     }
 }
-function unavailableWorkspace(contractId, detail) {
-    return new Error(`Contract workspace is unavailable: ${contractId} ${detail}`);
-}
-async function currentManagedContract(contract, contractId) {
-    let state;
-    try {
-        state = await contract.state();
-    }
-    catch (error) {
-        if (error instanceof Error && error.message === `contract does not exist: ${contractId}`) {
-            throw new KeiyakuRefused({ kind: "contract-missing", contractId });
-        }
-        throw error;
-    }
-    if (state.terminal !== null)
-        throw new KeiyakuRefused({ kind: "terminal", contractId: state.id });
-    return state;
-}
 async function resolveCallExecution(input) {
-    if (input.cwd !== undefined) {
-        return {
-            cwd: await canonicalBirthCwd(input.cwd),
-            source: "input",
-        };
-    }
-    if (input.contract !== undefined) {
-        const seat = seatForKeiyaku(input.contract);
-        if (seat === null)
-            throw new TypeError("contract must be a Keiyaku");
-        const state = await currentManagedContract(input.contract, seat.id);
-        const appointment = await readManagedWorktreeAppointment(seat.scope, state.id);
-        if (appointment.kind === "unappointed") {
-            throw unavailableWorkspace(state.id, "is unappointed; use reconcile");
-        }
-        if (appointment.kind === "failed") {
-            throw new Error(`${appointment.diagnostic}; use reconcile`);
-        }
-        return {
-            cwd: await canonicalBirthCwd(appointment.path, `Contract workspace is unavailable: ${appointment.path}`),
-            source: "contract-worktree",
-        };
-    }
-    return undefined;
+    if (input.cwd === undefined)
+        return undefined;
+    return {
+        cwd: await canonicalBirthCwd(input.cwd),
+        source: "input",
+    };
 }
 async function resolveAliasStage(path, alias, dispatch, akuma) {
     if (alias === undefined)
@@ -326,11 +288,7 @@ function schemaTell(input) {
 }
 async function prepareCall(input, context) {
     const parsed = await parseCallInput(input);
-    const execution = await resolveCallExecution({
-        path: parsed.path,
-        ...(parsed.cwd === undefined ? {} : { cwd: parsed.cwd }),
-        ...(parsed.seat === undefined ? {} : { contract: parsed.values.contract }),
-    });
+    const execution = await resolveCallExecution(parsed.cwd === undefined ? {} : { cwd: parsed.cwd });
     const world = akumaWorld(parsed.path, parsed.home, parsed.settings, context);
     const { born, akuma } = await admitCall({
         path: parsed.path,

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

@@ -16,7 +16,7 @@ export declare function composeLibrary(context?: ExecutionContext, composition?:
         readonly?: import("../akuma/provider-recipe.js").ReadonlyRestraint;
         execution: Readonly<{
             cwd: string;
-            source: "input" | "contract-worktree" | "caller" | "process" | "world";
+            source: "input" | "caller" | "process" | "world";
         }>;
         dispatch: import("./akuma-creation.js").DispatchStage;
         alias: import("./akuma-creation.js").AliasStage;
@@ -191,6 +191,10 @@ export declare function composeLibrary(context?: ExecutionContext, composition?:
                             } | {
                                 kind: "other";
                                 display: string;
+                                input?: {
+                                    json: string;
+                                    truncated: boolean;
+                                } | undefined;
                             };
                             state: "active";
                             truncated?: true | undefined;
@@ -227,6 +231,10 @@ export declare function composeLibrary(context?: ExecutionContext, composition?:
                             } | {
                                 kind: "other";
                                 display: string;
+                                input?: {
+                                    json: string;
+                                    truncated: boolean;
+                                } | undefined;
                             };
                             state: {
                                 status: "error" | "ok";
@@ -317,6 +325,10 @@ export declare function composeLibrary(context?: ExecutionContext, composition?:
                             } | {
                                 kind: "other";
                                 display: string;
+                                input?: {
+                                    json: string;
+                                    truncated: boolean;
+                                } | undefined;
                             };
                             state: {
                                 status: "error" | "ok";
@@ -345,6 +357,7 @@ export declare function composeLibrary(context?: ExecutionContext, composition?:
                         };
                     } | undefined;
                 };
+                cwd?: string | undefined;
                 readonly?: {
                     enforcement: "native";
                 } | {

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

@@ -1,10 +1,11 @@
 /** @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 { TellWaitObserver, WaitObserver } from "../akuma/fleet-execution.js";
 import { type DispatchAssociation } from "../dispatch/index.js";
+import { type Schema } from "../akuma/schema.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";
+import { type AkumaKillResult, type AkumaObservation, type AkumaObservationStage, type AkumaTellResult, type AkumaTellWaitResult, type AkumaWaitResult } from "../akuma/fleet-observation.js";
 export type AkumaWaitInput = AkumaSetAddressInput & Readonly<{
     completion?: "any" | "all";
     timeoutMs?: number;
@@ -15,6 +16,15 @@ export type AkumaTellInput = AkumaAddressInput & Readonly<{
     initiator?: string;
     signal?: AbortSignal;
 }>;
+export type AkumaTellWaitInput = AkumaAddressInput & Readonly<{
+    body: string;
+    timeoutMs: number;
+    schema?: Schema<unknown>;
+    interrupt?: boolean;
+    initiator?: string;
+    signal?: AbortSignal;
+    observe?: TellWaitObserver;
+}>;
 export type { TellResult, TellWake } from "../akuma/akuma.js";
 export type { CreatedTaskObservation } from "../task/created-observation.js";
 export type { DispatchAssociation } from "../dispatch/association.js";
@@ -68,5 +78,6 @@ export declare function statusAkuma(input: AkumaAddressInput): Promise<AkumaObse
 export declare function waitAkuma(input: AkumaWaitInput, execution?: ExecutionContext, observer?: WaitObserver): Promise<AkumaWaitResult>;
 export declare function killAkuma(input: AkumaKillInput, execution?: ExecutionContext): Promise<AkumaKillResult>;
 export declare function tellAkuma(input: AkumaTellInput, execution?: ExecutionContext): Promise<AkumaTellResult>;
+export declare function tellWaitAkuma(input: AkumaTellWaitInput, execution?: ExecutionContext): Promise<AkumaTellWaitResult>;
 export declare function interruptAkuma(input: AkumaInterruptInput): Promise<AkumaInterruptResult>;
 export declare function historyAkuma(input: AkumaHistoryInput): Promise<AkumaHistoryResult>;