@astrosheep/keiyaku 4.5.7 → 4.5.9

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

@@ -1,57 +1,44 @@
-import { type RegionOverlap } from "./region.js";
+import { actorOption } from "./input.js";
+import { worktreeHooksOption } from "./configuration.js";
+import type { RegionOverlap } from "./region.js";
 import { type ChangeId, type FactKind, type ContractId, type ContractState, type SnapshotId } from "../core/facts/types.js";
 export { AuthorityCorruptionError } from "../core/facts/errors.js";
-import { type PlacementStop, type RepositoryScope, type VerificationStop, type DeliveryPreparationRefusal } from "../protocol/operations.js";
+import { type PlacementStop, type VerificationStop, type DeliveryPreparationRefusal } from "../protocol/operations.js";
 import type { ContractBoard, ContractDisposition, ContractGateCurrent, ContractGateReport, ContractObservation, ContractPhase, ContractRow, AfterEndpointObservation, ContractAfterEdge, ContractDependent, ContractWorkspaceObservation } from "../protocol/read/status.js";
 import type { AuditReport } from "../protocol/audit.js";
 import type { IntegrationConflictMaterialized, VerificationReuse } from "../protocol/deliver.js";
 import type { TaskId } from "../task/identity.js";
-import { type ReconcileInput } from "./repo.js";
-import { type AuditInput } from "./audit.js";
+import { type ExecutionContext } from "../akuma/requests.js";
+import type { AuditInput } from "./audit.js";
 import { Delivery } from "./delivery.js";
 import { type ContinuationReport } from "./continuation.js";
-import { type MutationResult } from "./mutation.js";
-import type { AbandonInput, AmendInput, AmendResult, ArcInput, BindInput, BindResult, ContractListInput, ContractObservationInput, DeliverInput, ForkBindInput, KeiyakuOfInput, MarkdownBindInput, ReconcileReport, ReviewInput, ContractHistory, ContractHistoryEvent, Fact, Lag, TopologyEffect } from "./contract-types.js";
-import { type AttestationVerdict as OperationAttestationVerdict, type Review as OperationReview } from "./contract-operations.js";
+import type { MutationResult } from "./mutation.js";
+export { KeiyakuHandle } from "./contract-handle.js";
+import { KeiyakuHandle } from "./contract-handle.js";
+import type { AbandonInput, AmendInput, AmendResult, ArcInput, BindInput, BindResult, ContractListInput, ContractObservationInput, DeliverInput, ForkBindInput, KeiyakuOfInput, LocalContractComposition, MarkdownBindInput, ReconcileReport, ReviewInput, ContractHistory, ContractHistoryEvent, Fact, Lag, TopologyEffect } from "./contract-types.js";
+import type { AttestationVerdict as OperationAttestationVerdict, Review as OperationReview } from "./contract-operations.js";
 import { KeiyakuRetry, type KeiyakuRefusal, type KeiyakuRetryReason } from "./refusal.js";
 export { KeiyakuRefused } from "./refusal.js";
 export { KeiyakuRetry, type KeiyakuRefusal, type KeiyakuRetryReason };
-export { executeForwardedDeliver, executeForwardedReview } from "./contract-operations.js";
 export { gatesFrom, requireBranchesToBeUpToDateFrom, SettingsError } from "./configuration.js";
 export type { Gate, GatesFromInput, HookCommand, RequireBranchesToBeUpToDateFromInput, WorktreeHooks, } from "./configuration.js";
-export type { AbandonInput, AmendInput, AmendResult, ArcInput, AuditInput, AuditReport, ChangeId, ContinuationReport, ContractBoard, ContractDisposition, ContractGateCurrent, ContractGateReport, ContractAfterEdge, ContractId, ContractHistory, ContractHistoryEvent, ContractDependent, ContractObservation, ContractPhase, ContractRow, ContractState, ContractWorkspaceObservation, BindInput, BindResult, ContractListInput, ContractObservationInput, DeliverInput, ForkBindInput, KeiyakuOfInput, MarkdownBindInput, ReconcileReport, ReviewInput, DeliveryPreparationRefusal, Fact, FactKind, IntegrationConflictMaterialized, Lag, MutationResult, PlacementStop, RegionOverlap, SnapshotId, TaskId, TopologyEffect, VerificationReuse, VerificationStop, };
+export type { AbandonInput, AmendInput, AmendResult, ArcInput, AuditInput, AuditReport, ChangeId, ContinuationReport, ContractBoard, ContractDisposition, ContractGateCurrent, ContractGateReport, ContractAfterEdge, ContractId, ContractHistory, ContractHistoryEvent, ContractDependent, ContractObservation, ContractPhase, ContractRow, ContractState, ContractWorkspaceObservation, BindInput, BindResult, ContractListInput, ContractObservationInput, DeliverInput, ForkBindInput, KeiyakuOfInput, MarkdownBindInput, ReconcileReport, ReviewInput, DeliveryPreparationRefusal, Fact, FactKind, IntegrationConflictMaterialized, Lag, LocalContractComposition, MutationResult, PlacementStop, RegionOverlap, SnapshotId, TaskId, TopologyEffect, VerificationReuse, VerificationStop, };
 export type { AfterEndpointObservation };
 export type ActorId = string;
 export type AttestationVerdict = OperationAttestationVerdict;
 export type Review = OperationReview;
 export { Delivery };
 export type { SettlementAction, SettlementLag, SettlementReport } from "../settlement/settle.js";
-export declare class KeiyakuHandle {
-    private readonly id;
-    private readonly scope;
-    constructor(id: ContractId, scope: RepositoryScope);
-    state(): Promise<ContractState>;
-    history(): Promise<ContractHistory>;
-    guidance(): Promise<string>;
-    delivery(): Promise<Delivery | null>;
-    amend(input: AmendInput): Promise<AmendResult>;
-    deliver(input?: DeliverInput): Promise<MutationResult<Delivery> | IntegrationConflictMaterialized>;
-    review(input: ReviewInput): Promise<MutationResult<Review>>;
-    abandon(input?: AbandonInput): Promise<MutationResult<void>>;
-    arc(input: ArcInput): Promise<MutationResult<void>>;
-    audit(input?: AuditInput): Promise<MutationResult<AuditReport>>;
-    reconcile(input?: ReconcileInput): Promise<ReconcileReport>;
-    private deliveryHandle;
-}
-/** Internal package composition capability; not exported from the package root. */
-export declare function seatForKeiyaku(value: unknown): Readonly<{
-    id: ContractId;
-    scope: RepositoryScope;
-}>;
 export type Keiyaku = KeiyakuHandle;
-export declare function keiyakuOf(input: KeiyakuOfInput): Keiyaku;
+export type LocalContractCompositionCapture = Readonly<{
+    actor?: NonNullable<ReturnType<typeof actorOption>["actor"]>;
+    hooks: ReturnType<typeof worktreeHooksOption>;
+    requireBranchesToBeUpToDate: boolean;
+}>;
+export declare function captureLocalContractComposition(input?: LocalContractComposition): LocalContractCompositionCapture;
+export declare function keiyakuOf(input: KeiyakuOfInput, execution?: ExecutionContext, composition?: LocalContractCompositionCapture): Keiyaku;
 export declare function listKeiyaku(input: ContractListInput): Promise<ContractBoard>;
 export declare function observeKeiyaku(input: ContractObservationInput): Promise<ContractObservation>;
-export declare function bindKeiyaku(input: BindInput): Promise<BindResult>;
+export declare function bindKeiyaku(input: BindInput, execution?: ExecutionContext, composition?: LocalContractCompositionCapture): Promise<BindResult>;
 /** Internal CLI composition; not exported from the package root. */
-export declare function bindFromCli(input: BindInput): Promise<BindResult>;
+export declare function bindFromCli(input: BindInput, execution?: ExecutionContext): Promise<BindResult>;

package/build/src/library/contract.js

@@ -1,299 +1,40 @@
-import { documentDiff } from "../markdown/diff.js";
-import { applyAmendDocument } from "../body/amend.js";
-import { decodeArcDocument } from "../body/arc.js";
-import { decodeContractDocument } from "../body/decode.js";
-import { renderContractGuidance } from "../contract-worktree.js";
-import { actorOption, contractTerms, documentDerivation, normalizedGates, normalizedList, optionalBoolean, optionalNonblank, optionalSignal, requireInput, requireMarkdown, } from "./input.js";
-import { observeChangedRegion } from "./region.js";
+// Contract's static facade deliberately depends only on construction and observation.
+import { actorOption, optionalBoolean, requireInput } from "./input.js";
 import { worktreeHooksOption } from "./configuration.js";
 import { contractId, } from "../core/facts/types.js";
 export { AuthorityCorruptionError } from "../core/facts/errors.js";
-import { contractObservationOperation, contractsOperation, deliveryDiffOperation, deliveryOperation, stateOperation, } from "../protocol/operations.js";
-import { abandonOperation } from "../protocol/abandon.js";
-import { amendOperation } from "../protocol/amend.js";
-import { arcOperation } from "../protocol/arc.js";
-import { readDispatchesAt } from "../dispatch/index.js";
-import { mintSnapshotId } from "../git/identity.js";
-import { observeContractsForAdmissionInObservationAt } from "../git/observe.js";
-import { withGitDecodeChannel, withGitReadObservation } from "../git/read-observation.js";
-import { releaseTaskHolder, releaseTaskHolderWithFence, taskHolderObservationSelection } from "../settlement/holder.js";
-import { reconcileInput, scopeForRepo } from "./repo.js";
-import { injectedBodyRequests, requestBodyDeliver, requestBodyReview } from "../akuma/requests.js";
-import { auditContract } from "./audit.js";
-import { Delivery, deliveryHandle } from "./delivery.js";
-import { completionInput, completeHolderMutation, completeMutation } from "./mutation.js";
-import { completeReconcile } from "./reconcile.js";
+import { contractObservationOperation, contractsOperation, } from "../protocol/operations.js";
+import { withGitDecodeChannel } from "../git/read-observation.js";
+import { scopeForRepo } from "./repo.js";
+import { localExecutionContext } from "../akuma/requests.js";
+import { Delivery } from "./delivery.js";
 import { bindFromCli as bindFromCliImplementation, bindKeiyaku as bindKeiyakuImplementation } from "./contract-bind.js";
-import { executeLocalDelivery, executeLocalReview, forwardedReceipt, requireForwarded, } from "./contract-operations.js";
-import { KeiyakuRefused, KeiyakuRetry, requireAccepted, } from "./refusal.js";
+export { KeiyakuHandle } from "./contract-handle.js";
+import { KeiyakuHandle } from "./contract-handle.js";
+import { KeiyakuRetry } from "./refusal.js";
 export { KeiyakuRefused } from "./refusal.js";
 export { KeiyakuRetry };
-export { executeForwardedDeliver, executeForwardedReview } from "./contract-operations.js";
 export { gatesFrom, requireBranchesToBeUpToDateFrom, SettingsError } from "./configuration.js";
 export { Delivery };
-export class KeiyakuHandle {
-    id;
-    scope;
-    constructor(id, scope) {
-        this.id = id;
-        this.scope = scope;
-        KEIYAKU_SEATS.set(this, { id, scope });
-    }
-    async state() {
-        return withGitDecodeChannel(this.scope, (channel) => stateOperation({
-            scope: this.scope,
-            channel,
-            contractId: this.id,
-        }));
-    }
-    async history() {
-        return withGitDecodeChannel(this.scope, (channel) => withGitReadObservation(this.scope, channel, async (observation) => {
-            const [journals, dispatches] = await Promise.all([
-                observeContractsForAdmissionInObservationAt(observation, [this.id]),
-                readDispatchesAt(observation),
-            ]);
-            const record = journals.journals.get(this.id);
-            if (record === undefined)
-                throw new Error(`missing requested contract observation: ${this.id}`);
-            if (record.state === null)
-                throw new KeiyakuRefused({ kind: "contract-missing", contractId: this.id });
-            const commit = observation.snapshot.commit;
-            if (commit === null)
-                throw new Error("contract history requires a keiyaku-state snapshot");
-            const recordedAt = (event) => event.source === "journal" ? event.fact.at : event.dispatch.dispatchedAt;
-            const events = [
-                ...record.entries.map((fact) => ({ source: "journal", fact })),
-                ...dispatches
-                    .filter((dispatch) => dispatch.contractId === this.id)
-                    .map((dispatch) => ({ source: "dispatch", dispatch })),
-            ].sort((left, right) => {
-                const leftAt = recordedAt(left);
-                const rightAt = recordedAt(right);
-                if (leftAt !== rightAt)
-                    return leftAt < rightAt ? -1 : 1;
-                if (left.source !== right.source)
-                    return left.source === "journal" ? -1 : 1;
-                return 0;
-            });
-            return { id: this.id, state: mintSnapshotId(commit), events };
-        }));
-    }
-    async guidance() {
-        return withGitDecodeChannel(this.scope, async (channel) => {
-            const observed = await contractObservationOperation({ scope: this.scope, channel, contractId: this.id });
-            if (observed.kind === "missing")
-                throw new KeiyakuRefused({ kind: "contract-missing", contractId: this.id });
-            return renderContractGuidance(await stateOperation({ scope: this.scope, channel, contractId: this.id }));
-        });
-    }
-    async delivery() {
-        const delivery = await withGitDecodeChannel(this.scope, (channel) => deliveryOperation({
-            scope: this.scope,
-            channel,
-            contractId: this.id,
-        }));
-        return delivery === null ? null : this.deliveryHandle(delivery);
-    }
-    async amend(input) {
-        const values = requireInput(input, "amend input");
-        const hooks = worktreeHooksOption(values.hooks);
-        const markdown = values.markdown === undefined ? undefined : requireMarkdown(values.markdown);
-        const actor = actorOption(values.actor);
-        const gates = values.gates === undefined ? undefined : normalizedGates(values.gates);
-        const prerequisites = values.after === undefined ? undefined : normalizedList(values.after, "after", contractId);
-        if (markdown === undefined && gates === undefined && prerequisites === undefined) {
-            throw new TypeError("amend requires markdown, after, or gates");
-        }
-        const amendment = await withGitDecodeChannel(this.scope, async (channel) => {
-            let changedSections;
-            const accepted = requireAccepted(await amendOperation({
-                scope: this.scope,
-                channel,
-                contractId: this.id,
-                ...actor,
-                deriveAmendment: (source) => {
-                    const amendment = markdown === undefined
-                        ? undefined
-                        : applyAmendDocument(markdown, decodeContractDocument(source.document.bytes));
-                    changedSections = amendment?.changedSections;
-                    const document = amendment === undefined
-                        ? decodeContractDocument(source.document.bytes)
-                        : decodeContractDocument(amendment.document);
-                    const terms = markdown === undefined
-                        ? {
-                            document: source.document,
-                            segments: source.segments,
-                            gates: gates ?? source.gates,
-                            after: prerequisites ?? source.after,
-                        }
-                        : contractTerms(document, gates ?? source.gates, prerequisites ?? source.after);
-                    return {
-                        terms,
-                        verification: documentDerivation(document, terms.gates, this.id).verification,
-                    };
-                },
-            }));
-            const completed = await completeMutation({
-                ...completionInput(this.scope, channel, this.id, () => undefined, hooks),
-                accepted,
-            });
-            return {
-                completed,
-                document: decodeContractDocument(accepted.value.terms.document.bytes),
-                changedSections,
-                documentDiff: documentDiff("before", "after", accepted.value.source.document.bytes, accepted.value.terms.document.bytes),
-            };
-        });
-        const regionObservation = await observeChangedRegion(this.scope, this.id, amendment.changedSections, amendment.document.region);
-        return {
-            ...amendment.completed,
-            documentDiff: amendment.documentDiff,
-            ...regionObservation,
-        };
-    }
-    async deliver(input) {
-        const values = input === undefined ? undefined : requireInput(input, "deliver input");
-        const hooks = worktreeHooksOption(values?.hooks);
-        const message = optionalNonblank(values?.message, "deliver message");
-        const requireBranchesToBeUpToDate = optionalBoolean(values?.requireBranchesToBeUpToDate, "requireBranchesToBeUpToDate") ?? false;
-        const includeDirty = optionalBoolean(values?.includeDirty, "includeDirty") ?? false;
-        const materializeConflict = optionalBoolean(values?.materializeConflict, "materializeConflict") ?? false;
-        const actor = actorOption(values?.actor);
-        const signal = optionalSignal(values?.signal);
-        const requests = injectedBodyRequests();
-        const result = requests === null
-            ? await executeLocalDelivery({
-                scope: this.scope,
-                contractId: this.id,
-                ...actor,
-                ...(message === undefined ? {} : { message }),
-                requireBranchesToBeUpToDate,
-                includeDirty,
-                materializeConflict,
-                ...(signal === undefined ? {} : { signal }),
-                hooks,
-            })
-            : requireForwarded(forwardedReceipt(await requestBodyDeliver({
-                directory: requests,
-                repoRoot: this.scope.primaryWorktree,
-                contractId: this.id,
-                ...(message === undefined ? {} : { message }),
-                includeDirty,
-                materializeConflict,
-                ...(signal === undefined ? {} : { signal }),
-            }), "deliver"));
-        return "facts" in result ? { ...result, value: this.deliveryHandle(result.value) } : result;
-    }
-    async review(input) {
-        const values = requireInput(input, "review input");
-        const hooks = worktreeHooksOption(values.hooks);
-        const verdict = values.verdict;
-        if (verdict !== "satisfied" && verdict !== "unsatisfied") {
-            throw new TypeError("verdict must be satisfied or unsatisfied");
-        }
-        const summary = optionalNonblank(values.summary, "review summary");
-        const actor = actorOption(values.actor);
-        const requests = injectedBodyRequests();
-        if (requests !== null) {
-            return requireForwarded(forwardedReceipt(await requestBodyReview({
-                directory: requests,
-                repoRoot: this.scope.primaryWorktree,
-                contractId: this.id,
-                verdict,
-                ...(summary === undefined ? {} : { summary }),
-            }), "review"));
-        }
-        return await executeLocalReview({
-            scope: this.scope,
-            contractId: this.id,
-            ...actor,
-            verdict,
-            ...(summary === undefined ? {} : { summary }),
-            hooks,
-        });
-    }
-    async abandon(input) {
-        const values = input === undefined ? undefined : requireInput(input, "abandon input");
-        const hooks = worktreeHooksOption(values?.hooks);
-        const note = optionalNonblank(values?.note, "abandon note");
-        return withGitDecodeChannel(this.scope, async (channel) => {
-            const admission = await releaseTaskHolderWithFence(this.scope, channel, this.id, () => abandonOperation({
-                scope: this.scope,
-                channel,
-                contractId: this.id,
-                ...actorOption(values?.actor),
-                ...(note === undefined ? {} : { note }),
-                observationSelection: taskHolderObservationSelection(),
-                decorateOffer: async ({ observation, contractId: owner }) => {
-                    const companion = await releaseTaskHolder(channel, observation, owner);
-                    return companion === null ? [] : [companion];
-                },
-            }));
-            return completeHolderMutation({
-                completion: completionInput(this.scope, channel, this.id, () => undefined, hooks),
-                admission,
-                requireAccepted,
-            });
-        });
-    }
-    async arc(input) {
-        const values = requireInput(input, "arc input");
-        const hooks = worktreeHooksOption(values.hooks);
-        const chapter = decodeArcDocument(requireMarkdown(values.markdown));
-        return withGitDecodeChannel(this.scope, async (channel) => {
-            const accepted = requireAccepted(await arcOperation({
-                scope: this.scope,
-                channel,
-                contractId: this.id,
-                ...actorOption(values.actor),
-                chapter,
-            }));
-            return completeMutation({
-                ...completionInput(this.scope, channel, this.id, () => undefined, hooks),
-                accepted,
-            });
-        });
-    }
-    async audit(input) {
-        return auditContract({
-            scope: this.scope,
-            contractId: this.id,
-            ...(input === undefined ? {} : { input }),
-        });
-    }
-    async reconcile(input) {
-        const options = reconcileInput(input);
-        return withGitDecodeChannel(this.scope, (channel) => completeReconcile({
-            scope: this.scope,
-            channel,
-            contractId: this.id,
-            ...options,
-        }));
-    }
-    deliveryHandle(delivery) {
-        return deliveryHandle(delivery, () => deliveryDiffOperation({
-            scope: this.scope,
-            integrationPredecessor: delivery.integration.predecessor,
-            integrationSnapshot: delivery.integration.snapshot,
-        }));
-    }
-}
-const KEIYAKU_SEATS = new WeakMap();
-/** Internal package composition capability; not exported from the package root. */
-export function seatForKeiyaku(value) {
-    if (!(value instanceof KeiyakuHandle))
-        throw new TypeError("contract must be a Keiyaku");
-    const seat = KEIYAKU_SEATS.get(value);
-    if (seat === undefined)
-        throw new TypeError("contract must be a Keiyaku");
-    return seat;
+export function captureLocalContractComposition(input) {
+    const values = requireInput(input ?? {}, "Keiyaku.withLocal input", [
+        "actor",
+        "hooks",
+        "requireBranchesToBeUpToDate",
+    ]);
+    const actor = actorOption(values.actor).actor;
+    return Object.freeze({
+        ...(actor === undefined ? {} : { actor }),
+        hooks: worktreeHooksOption(values.hooks),
+        requireBranchesToBeUpToDate: optionalBoolean(values.requireBranchesToBeUpToDate, "Keiyaku.withLocal requireBranchesToBeUpToDate") ?? false,
+    });
 }
-export function keiyakuOf(input) {
+export function keiyakuOf(input, execution = localExecutionContext(), composition = captureLocalContractComposition()) {
     const values = requireInput(input, "Keiyaku.of input");
     const scope = scopeForRepo(values.repo);
     if (typeof values.id !== "string")
         throw new TypeError("contract ID must be a string");
-    return new KeiyakuHandle(contractId(values.id), scope);
+    return new KeiyakuHandle(contractId(values.id), scope, execution, composition);
 }
 export async function listKeiyaku(input) {
     const values = requireInput(input, "Keiyaku.list input");
@@ -320,10 +61,11 @@ export async function observeKeiyaku(input) {
     }
     return withGitDecodeChannel(scope, (channel) => contractObservationOperation({ scope, channel, contractId: id }));
 }
-export async function bindKeiyaku(input) {
-    return bindKeiyakuImplementation(input, (id, scope) => new KeiyakuHandle(id, scope));
+export async function bindKeiyaku(input, execution = localExecutionContext(), composition = captureLocalContractComposition()) {
+    return bindKeiyakuImplementation(input, (id, scope) => new KeiyakuHandle(id, scope, execution, composition));
 }
 /** Internal CLI composition; not exported from the package root. */
-export async function bindFromCli(input) {
-    return bindFromCliImplementation(input, (id, scope) => new KeiyakuHandle(id, scope));
+export async function bindFromCli(input, execution = localExecutionContext()) {
+    const composition = captureLocalContractComposition();
+    return bindFromCliImplementation(input, (id, scope) => new KeiyakuHandle(id, scope, execution, composition));
 }