@astrosheep/keiyaku 2.9.13 → 4.0.1

package/build/src/library/address.js

@@ -0,0 +1,134 @@
+import { readAliases } from "../alias/index.js";
+import { Akuma } from "../akuma/akuma.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 { requireInput } from "./input.js";
+import { scopeForRepo } from "./repo.js";
+function nonblank(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        throw new TypeError(`${label} must be a nonblank string`);
+    return value;
+}
+function settingsOption(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || typeof value.namespace !== "function") {
+        throw new TypeError("settings must be a Settings");
+    }
+    return value;
+}
+function world(path, settings) {
+    return Akuma.of(path, settings);
+}
+function directId(path, selector) {
+    if (selector.startsWith("@")) {
+        const alias = parseAkumaAlias(selector);
+        const resolved = readAliases(path).find((binding) => binding.alias === alias)?.akuId ?? null;
+        if (resolved === null)
+            throw new TypeError(`unknown Akuma alias: ${alias}`);
+        return resolved;
+    }
+    return parseAkuId(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);
+    const contractMatches = input.contracts.filter((row) => row.disposition === "active"
+        && row.workspace === "worktree" && row.worktreePath !== null
+        && `@${row.id.slice("kei/".length)}` === alias);
+    const aliasId = input.path === null
+        ? null
+        : readAliases(input.path).find((binding) => binding.alias === alias)?.akuId ?? null;
+    if (contractMatches.length > 0 && aliasId !== null)
+        throw new TypeError(`ambiguous selector matches Contract and Akuma: ${selector}`);
+    if (contractMatches.length === 1)
+        return { kind: "contract", id: contractMatches[0].id };
+    if (contractMatches.length > 1)
+        throw new TypeError(`ambiguous Contract selector: ${selector}`);
+    if (aliasId !== null)
+        return { kind: "akuma", id: aliasId };
+    throw new TypeError(`unknown selector: ${selector}`);
+}
+export function addressAkuma(input) {
+    const values = requireInput(input, "Akuma address input");
+    for (const key of Object.keys(values)) {
+        if (!["path", "akuma", "settings", "repo"].includes(key))
+            throw new TypeError(`Akuma address input has unknown field: ${key}`);
+    }
+    if (values.repo !== undefined)
+        scopeForRepo(values.repo);
+    const path = nonblank(values.path, "path");
+    const settings = settingsOption(values.settings);
+    return { path, id: directId(path, nonblank(values.akuma, "akuma")), ...(settings === undefined ? {} : { settings }) };
+}
+function idsFromFleet(fleet) {
+    return fleet.rows.map((row) => row.id);
+}
+export async function addressAkumaSet(input) {
+    const values = requireInput(input, "Akuma set address input");
+    for (const key of Object.keys(values)) {
+        if (!["path", "akuma", "settings", "repo"].includes(key))
+            throw new TypeError(`Akuma set address input has unknown field: ${key}`);
+    }
+    if (!Array.isArray(values.akuma) || values.akuma.length === 0)
+        throw new TypeError("akuma must be a nonempty selector array");
+    const path = nonblank(values.path, "path");
+    const settings = settingsOption(values.settings);
+    const selectors = values.akuma.map((raw) => {
+        const selector = nonblank(raw, "akuma selector");
+        if (selector.startsWith("kei/"))
+            return { kind: "contract", value: contractId(selector) };
+        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 };
+    });
+    if (selectors.some((selector) => selector.kind === "contract") && values.repo === undefined) {
+        throw new TypeError("Contract Akuma selector requires repo");
+    }
+    const fleetIds = selectors.some((selector) => selector.kind === "glob")
+        ? idsFromFleet(world(path, settings).list())
+        : [];
+    const aliases = selectors.some((selector) => selector.kind === "alias")
+        ? new Map(readAliases(path).map((binding) => [binding.alias, binding.akuId]))
+        : new Map();
+    const dispatches = selectors.some((selector) => selector.kind === "contract")
+        ? await readDispatches(scopeForRepo(values.repo))
+        : [];
+    const selected = new Set();
+    for (const selector of selectors) {
+        if (selector.kind === "contract") {
+            const members = dispatches
+                .filter((dispatch) => dispatch.contractId === selector.value)
+                .map((dispatch) => dispatch.akuId);
+            for (const id of members)
+                selected.add(id);
+            continue;
+        }
+        if (selector.kind === "glob") {
+            for (const id of fleetIds)
+                if (matchesAkumaGlob(selector.value, id))
+                    selected.add(id);
+            continue;
+        }
+        if (selector.kind === "alias") {
+            const id = aliases.get(selector.value);
+            if (id === undefined)
+                throw new TypeError(`unknown Akuma alias: ${selector.value}`);
+            selected.add(id);
+        }
+        else
+            selected.add(selector.value);
+    }
+    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 { path, ids, ...(settings === undefined ? {} : { settings }) };
+}

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

@@ -0,0 +1,83 @@
+import { type AliasBinding } from "../alias/index.js";
+import { type AkumaStatus, type ForkReceipt } from "../akuma/akuma.js";
+import type { AkuId } from "../akuma/identity.js";
+import { type Dispatch, type DispatchFailure } from "../dispatch/index.js";
+import { type AkumaAlias } from "../identity/selector.js";
+import type { Settings } from "../settings.js";
+import type { WorldRoot } from "../world.js";
+import { type Keiyaku } from "./contract.js";
+import { type Repo } from "./repo.js";
+export type { AkumaStatus } from "../akuma/akuma.js";
+export type IntegrationFailure = Readonly<{
+    kind: "authority-corruption" | "infrastructure";
+    diagnostic: string;
+}>;
+export type DispatchStage = Readonly<{
+    kind: "none";
+}> | Readonly<{
+    kind: "dispatched";
+    dispatch: Dispatch;
+}> | Readonly<{
+    kind: "failed";
+    failure: DispatchFailure | IntegrationFailure;
+}>;
+export type AliasStage = Readonly<{
+    kind: "none";
+}> | Readonly<{
+    kind: "aliased";
+    alias: AliasBinding;
+    previous: AkuId | null;
+}> | Readonly<{
+    kind: "skipped";
+    reason: "dispatch-failed";
+}> | Readonly<{
+    kind: "failed";
+    failure: IntegrationFailure;
+}>;
+export type CallInput = Readonly<{
+    path: WorldRoot;
+    archetype: string;
+    body: string;
+    cwd?: string;
+    mode?: "wait" | "detach";
+    timeoutMs?: number;
+    settings?: Settings;
+    contract?: Keiyaku;
+    alias?: AkumaAlias;
+}>;
+export type CallObservation = Readonly<{
+    kind: "detached";
+}> | Readonly<{
+    kind: "observed";
+    status: AkumaStatus;
+}> | Readonly<{
+    kind: "failed";
+    failure: IntegrationFailure;
+}>;
+export type CallResult = Readonly<{
+    kind: "called";
+    akuma: AkuId;
+    dispatch: DispatchStage;
+    alias: AliasStage;
+    observation: CallObservation;
+}>;
+export type ForkInput = Readonly<{
+    path: WorldRoot;
+    akuma: string;
+    at: string;
+    settings?: Settings;
+    repo?: Repo;
+}>;
+export type ForkResult = Readonly<{
+    kind: "forked";
+    parent: AkuId;
+    child: AkuId;
+    dispatch: DispatchStage;
+}> | (Exclude<ForkReceipt, Readonly<{
+    kind: "forked";
+    child: AkuId;
+}>> & Readonly<{
+    parent: AkuId;
+}>);
+export declare function callKeiyaku(input: CallInput): Promise<CallResult>;
+export declare function forkKeiyaku(input: ForkInput): Promise<ForkResult>;

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

@@ -0,0 +1,152 @@
+import { moveAlias } from "../alias/index.js";
+import { Akuma } from "../akuma/akuma.js";
+import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { publishDispatch, readDispatch, } from "../dispatch/index.js";
+import { parseAkumaAlias } from "../identity/selector.js";
+import { requireInput } from "./input.js";
+import { addressAkuma } from "./address.js";
+import { seatForKeiyaku } from "./contract.js";
+import { scopeForRepo } from "./repo.js";
+function nonblank(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`${label} must be a nonblank string`);
+    }
+    return value;
+}
+function text(value, label) {
+    if (typeof value !== "string")
+        throw new TypeError(`${label} must be a string`);
+    return value;
+}
+function settingsOption(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || typeof value.namespace !== "function") {
+        throw new TypeError("settings must be a Settings");
+    }
+    return value;
+}
+function onlyKeys(values, allowed, label) {
+    const accepted = new Set(allowed);
+    for (const key of Object.keys(values)) {
+        if (!accepted.has(key))
+            throw new TypeError(`${label} has unknown field: ${key}`);
+    }
+}
+function integrationFailure(error) {
+    return {
+        kind: error instanceof AuthorityCorruptionError ? "authority-corruption" : "infrastructure",
+        diagnostic: error instanceof Error ? error.message : String(error),
+    };
+}
+function callMode(value) {
+    if (value === undefined || value === "wait")
+        return "wait";
+    if (value === "detach")
+        return "detach";
+    throw new TypeError("mode must be wait or detach");
+}
+function callTimeout(value, mode) {
+    if (mode === "detach" && value !== undefined) {
+        throw new TypeError("timeoutMs is not valid in detach mode");
+    }
+    if (value === undefined)
+        return 300_000;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new TypeError("timeoutMs must be a nonnegative finite number");
+    }
+    return value;
+}
+async function observeCall(handle, mode, timeoutMs) {
+    if (mode === "detach")
+        return { kind: "detached" };
+    try {
+        return { kind: "observed", status: await handle.wait(undefined, { timeoutMs }) };
+    }
+    catch (error) {
+        return { kind: "failed", failure: integrationFailure(error) };
+    }
+}
+function dispatchStage(input) {
+    try {
+        const published = publishDispatch(input);
+        return published.kind === "dispatched"
+            ? { kind: "dispatched", dispatch: published.dispatch }
+            : { kind: "failed", failure: published.failure };
+    }
+    catch (error) {
+        return { kind: "failed", failure: integrationFailure(error) };
+    }
+}
+function forkDispatchStage(input) {
+    try {
+        const parent = readDispatch(input.repository, input.parent);
+        return parent === null
+            ? { kind: "none" }
+            : dispatchStage({ repository: input.repository, akuId: input.child, contractId: parent.contractId });
+    }
+    catch (error) {
+        return { kind: "failed", failure: integrationFailure(error) };
+    }
+}
+export async function callKeiyaku(input) {
+    const values = requireInput(input, "Keiyaku.call input");
+    onlyKeys(values, ["path", "archetype", "body", "cwd", "mode", "timeoutMs", "settings", "contract", "alias"], "Keiyaku.call input");
+    const path = nonblank(values.path, "path");
+    const archetype = nonblank(values.archetype, "archetype");
+    const body = text(values.body, "body");
+    const cwd = values.cwd === undefined ? undefined : nonblank(values.cwd, "cwd");
+    const mode = callMode(values.mode);
+    const timeoutMs = callTimeout(values.timeoutMs, mode);
+    const settings = settingsOption(values.settings);
+    const alias = values.alias === undefined
+        ? undefined
+        : parseAkumaAlias(nonblank(values.alias, "alias"));
+    const seat = values.contract === undefined ? undefined : seatForKeiyaku(values.contract);
+    const handle = await Akuma.of(path, settings).call({
+        archetype,
+        body,
+        ...(cwd === undefined ? {} : { cwd }),
+    });
+    const dispatch = seat === undefined
+        ? { kind: "none" }
+        : dispatchStage({ repository: seat.scope, akuId: handle.id, contractId: seat.id });
+    let aliasStage = { kind: "none" };
+    if (alias !== undefined) {
+        if (dispatch.kind === "failed")
+            aliasStage = { kind: "skipped", reason: "dispatch-failed" };
+        else {
+            try {
+                const moved = await moveAlias({ world: path, alias, akuId: handle.id });
+                aliasStage = { kind: "aliased", alias: moved.alias, previous: moved.previous };
+            }
+            catch (error) {
+                aliasStage = { kind: "failed", failure: integrationFailure(error) };
+            }
+        }
+    }
+    const observation = await observeCall(handle, mode, timeoutMs);
+    return { kind: "called", akuma: handle.id, dispatch, alias: aliasStage, observation };
+}
+export async function forkKeiyaku(input) {
+    const values = requireInput(input, "Keiyaku.fork input");
+    onlyKeys(values, ["path", "akuma", "at", "settings", "repo"], "Keiyaku.fork input");
+    const path = nonblank(values.path, "path");
+    const at = nonblank(values.at, "at");
+    const settings = settingsOption(values.settings);
+    const akuma = addressAkuma({
+        path,
+        akuma: nonblank(values.akuma, "akuma"),
+        ...(settings === undefined ? {} : { settings }),
+    }).id;
+    const repository = values.repo === undefined ? undefined : scopeForRepo(values.repo);
+    const receipt = await Akuma.of(path, settings)
+        .of({ id: akuma })
+        .fork({ at });
+    if (receipt.kind !== "forked")
+        return { ...receipt, parent: akuma };
+    const dispatch = repository === undefined
+        ? { kind: "none" }
+        : forkDispatchStage({ repository, parent: akuma, child: receipt.child });
+    return { kind: "forked", parent: akuma, child: receipt.child, dispatch };
+}

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

@@ -0,0 +1,21 @@
+import { type ActorId, type ContractId } from "../core/facts/types.js";
+import type { GitDecodeChannel } from "../git/read-observation.js";
+import { bindOperation, type IntentOutcome, type RepositoryScope } from "../protocol/operations.js";
+import type { TaskId } from "../task/identity.js";
+import type { VerificationDeclarationPreparation } from "../verification/declaration.js";
+import type { KeiyakuRefusal } from "./refusal.js";
+type BindAttemptInput = Readonly<{
+    scope: RepositoryScope;
+    channel: GitDecodeChannel;
+    title: string;
+    terms: Parameters<typeof bindOperation>[0]["terms"];
+    verification: VerificationDeclarationPreparation;
+    workspace: "worktree" | "here";
+    target?: string;
+    task?: TaskId;
+    actor?: ActorId;
+}>;
+export declare function admitBindWithAppointment(input: BindAttemptInput): Promise<IntentOutcome<Readonly<{
+    contractId: ContractId;
+}>, KeiyakuRefusal>>;
+export {};

package/build/src/library/bind.js

@@ -0,0 +1,56 @@
+import { randomBytes } from "node:crypto";
+import { releaseContractWorktree, reserveContractWorktree, withContractWorktreeAppointment, } from "../contract-worktree.js";
+import { contractIdFromSegment } from "../core/facts/types.js";
+import { fitIdentityStem, normalizeIdentityStem } from "../identity/normalize.js";
+import { bindOperation } from "../protocol/operations.js";
+import { claimTaskHolder } from "../settlement/holder.js";
+function candidateId(title, collision) {
+    const stem = fitIdentityStem({ stem: normalizeIdentityStem({ source: title }) || "contract", maxBytes: 48 });
+    const suffix = collision === 0 ? "" : `-${randomBytes(8).toString("hex")}`;
+    return contractIdFromSegment(`${stem}${suffix}`);
+}
+async function attempt(input, id) {
+    return bindOperation({
+        scope: input.scope,
+        channel: input.channel,
+        title: input.title,
+        terms: input.terms,
+        verification: input.verification,
+        workspace: input.workspace,
+        contractId: id,
+        ...(input.target === undefined ? {} : { target: input.target }),
+        ...(input.task === undefined ? {} : {
+            decorateOffer: ({ contractId: owner }) => [claimTaskHolder(input.task, owner)],
+        }),
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+    });
+}
+async function attemptCandidates(input) {
+    for (let collision = 0; collision <= 3; collision += 1) {
+        const id = candidateId(input.title, collision);
+        let reserved = false;
+        if (input.workspace === "here") {
+            const reservation = reserveContractWorktree(input.scope, id);
+            if (reservation.kind !== "reserved") {
+                return { kind: "refused", refusal: {
+                        kind: "here-worktree-appointed",
+                        path: reservation.path,
+                        ...(reservation.kind === "appointed" ? { contract: reservation.contract } : {}),
+                    } };
+            }
+            reserved = true;
+        }
+        const result = await attempt(input, id);
+        if (result.kind === "accepted")
+            return result;
+        if (reserved)
+            releaseContractWorktree(input.scope, id);
+        if (result.kind !== "refused" || result.refusal.kind !== "contract-exists")
+            return result;
+    }
+    throw new Error("contract identity collision attempts exhausted");
+}
+export function admitBindWithAppointment(input) {
+    const action = () => attemptCandidates(input);
+    return input.workspace === "here" ? withContractWorktreeAppointment(input.scope, action) : action();
+}

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

@@ -0,0 +1,58 @@
+import { type AkumaList } from "../akuma/akuma.js";
+import { type ArchetypeCatalogRow } from "../akuma/archetype.js";
+import type { Settings } from "../settings.js";
+import { type TaskRow } from "../task/index.js";
+import { type ContractBoard } from "./contract.js";
+import { Repo } from "./repo.js";
+import type { WorldRoot } from "../world.js";
+export type CatalogQuery = Readonly<{
+    kind: "tasks";
+}> | Readonly<{
+    kind: "contracts";
+}> | Readonly<{
+    kind: "archetypes";
+}> | Readonly<{
+    kind: "akuma";
+    archetype?: string;
+}>;
+export type CatalogInput = Readonly<{
+    query: Extract<CatalogQuery, {
+        kind: "tasks";
+    }>;
+    path: WorldRoot;
+}> | Readonly<{
+    query: Extract<CatalogQuery, {
+        kind: "contracts";
+    }>;
+    repo: Repo;
+}> | Readonly<{
+    query: Extract<CatalogQuery, {
+        kind: "archetypes";
+    }>;
+    settings: Settings;
+}> | Readonly<{
+    query: Extract<CatalogQuery, {
+        kind: "akuma";
+    }>;
+    path: WorldRoot;
+}>;
+export type Catalog = Readonly<{
+    kind: "tasks";
+    root: WorldRoot;
+    rows: readonly TaskRow[];
+}> | Readonly<{
+    kind: "contracts";
+    root: string;
+    state: string | null;
+    rows: ContractBoard["rows"];
+}> | Readonly<{
+    kind: "archetypes";
+    rows: readonly ArchetypeCatalogRow[];
+}> | Readonly<{
+    kind: "akuma";
+    root: WorldRoot;
+    archetype: string | null;
+    rows: AkumaList["rows"];
+    searched: readonly string[];
+}>;
+export declare function listCatalog(input: CatalogInput): Promise<Catalog>;

package/build/src/library/catalog.js

@@ -0,0 +1,72 @@
+import { Akuma } from "../akuma/akuma.js";
+import { listArchetypeDefinitions } from "../akuma/archetype.js";
+import { Tasks } from "../task/index.js";
+import { listKeiyaku } from "./contract.js";
+import { requireInput } from "./input.js";
+import { Repo } from "./repo.js";
+function settingsValue(value) {
+    if (typeof value !== "object" || value === null
+        || typeof value.namespace !== "function") {
+        throw new TypeError("settings must be a Settings");
+    }
+    return value;
+}
+function worldRoot(value) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        throw new TypeError("path must be a WorldRoot");
+    return value;
+}
+function queryValue(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError("Keiyaku.ls query must be an object");
+    }
+    const query = value;
+    if (query.kind !== "tasks" && query.kind !== "contracts" && query.kind !== "archetypes" && query.kind !== "akuma") {
+        throw new TypeError("Keiyaku.ls query kind is invalid");
+    }
+    for (const key of Object.keys(query)) {
+        if (key !== "kind" && !(query.kind === "akuma" && key === "archetype")) {
+            throw new TypeError(`Keiyaku.ls query has unknown field: ${key}`);
+        }
+    }
+    if (query.kind !== "akuma")
+        return { kind: query.kind };
+    if (query.archetype !== undefined && typeof query.archetype !== "string") {
+        throw new TypeError("Keiyaku.ls Akuma archetype must be a string");
+    }
+    return { kind: "akuma", ...(query.archetype === undefined ? {} : { archetype: query.archetype }) };
+}
+export async function listCatalog(input) {
+    const values = requireInput(input, "Keiyaku.ls input");
+    const query = queryValue(values.query);
+    const allowed = query.kind === "contracts" ? ["query", "repo"]
+        : query.kind === "archetypes" ? ["query", "settings"] : ["query", "path"];
+    for (const key of Object.keys(values)) {
+        if (!allowed.includes(key))
+            throw new TypeError(`Keiyaku.ls input has unknown field: ${key}`);
+    }
+    if (query.kind === "contracts") {
+        if (!(values.repo instanceof Repo))
+            throw new TypeError("repo must be a Repo");
+        const board = await listKeiyaku({ repo: values.repo });
+        return { kind: "contracts", root: board.root, state: board.state, rows: board.rows };
+    }
+    if (query.kind === "archetypes") {
+        return { kind: "archetypes", rows: listArchetypeDefinitions({ settings: settingsValue(values.settings) }) };
+    }
+    const path = worldRoot(values.path);
+    if (query.kind === "tasks") {
+        const result = await Tasks.of(path).list({ selection: "all", scope: "world" });
+        if (result.kind !== "accepted")
+            throw new Error(`Task catalog ${result.kind}: ${JSON.stringify(result)}`);
+        return { kind: "tasks", root: path, rows: result.value };
+    }
+    const listed = Akuma.of(path).list(query.archetype === undefined ? undefined : { archetype: query.archetype });
+    return {
+        kind: "akuma",
+        root: path,
+        archetype: query.archetype ?? null,
+        rows: listed.rows,
+        searched: listed.searched,
+    };
+}

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

@@ -0,0 +1,17 @@
+import { SettingsError, type Settings } from "../settings.js";
+import type { WorktreeHooks } from "../git/hooks.js";
+export type { HookCommand, WorktreeHooks } from "../git/hooks.js";
+export type Gate = string;
+export type GatesFromInput = Readonly<{
+    settings: Settings;
+    name?: string;
+}>;
+export type RequireBranchesToBeUpToDateFromInput = Readonly<{
+    settings: Settings;
+}>;
+export { SettingsError };
+export declare function gatesFrom(input: GatesFromInput): readonly Gate[];
+export declare function requireBranchesToBeUpToDateFrom(input: RequireBranchesToBeUpToDateFromInput): boolean;
+export declare function normalizedWorktreeHooks(value: unknown): WorktreeHooks;
+export declare const EMPTY_WORKTREE_HOOKS: WorktreeHooks;
+export declare function worktreeHooksOption(value: unknown): WorktreeHooks;