@astrosheep/keiyaku 4.5.7 → 4.5.8

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

@@ -0,0 +1,125 @@
+import { decodeContractDocument } from "../body/decode.js";
+import { contractId } from "../core/facts/types.js";
+import { withGitDecodeChannel } from "../git/read-observation.js";
+import { deliverOperation } from "../protocol/deliver.js";
+import { reviewOperation } from "../protocol/review.js";
+import { auditContract } from "./audit.js";
+import { continueAcceptedCompletion } from "./continuation.js";
+import { actorOption, documentDerivation, invalidInput, optionalNonblank } from "./input.js";
+import { completionInput, completeMutation } from "./mutation.js";
+import { requireAccepted } from "./refusal.js";
+import { auditReportSchema, auditResultSchema, deliveryResultSchema, reviewResultSchema, } from "./contract-forwarding-result.js";
+import { scopeForRepo } from "./repo.js";
+function derivedDocument(state) {
+    return documentDerivation(decodeContractDocument(state.terms.document.bytes), state.terms.gates, state.id);
+}
+function operationContext(scope, channel, contractId) {
+    return { scope, channel, contractId, deriveDocument: derivedDocument };
+}
+export async function executeLocalDelivery(input) {
+    const scope = input.scope;
+    return withGitDecodeChannel(scope, async (channel) => {
+        const operation = operationContext(scope, channel, input.contractId);
+        const outcome = await deliverOperation({
+            ...operation,
+            ...(input.actor === undefined ? {} : { actor: input.actor }),
+            ...(input.message === undefined ? {} : { message: input.message }),
+            requireBranchesToBeUpToDate: input.requireBranchesToBeUpToDate,
+            includeDirty: input.includeDirty,
+            materializeConflict: input.materializeConflict,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+        });
+        if (outcome.kind === "integration-conflict-materialized")
+            return outcome;
+        const accepted = requireAccepted(outcome);
+        const continued = await continueAcceptedCompletion({
+            ...operation,
+            accepted,
+            ...(input.actor === undefined ? {} : { actor: input.actor }),
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+        });
+        return completeMutation({
+            ...completionInput(scope, channel, input.contractId, (delivery) => delivery, input.hooks),
+            accepted: continued,
+        });
+    });
+}
+export async function executeLocalReview(input) {
+    return withGitDecodeChannel(input.scope, async (channel) => {
+        const operation = operationContext(input.scope, channel, input.contractId);
+        const accepted = requireAccepted(await reviewOperation({
+            ...operation,
+            verdict: input.verdict,
+            ...(input.summary === undefined ? {} : { summary: input.summary }),
+            ...(input.actor === undefined ? {} : { actor: input.actor }),
+        }));
+        const continued = await continueAcceptedCompletion({
+            ...operation,
+            accepted,
+            ...(input.actor === undefined ? {} : { actor: input.actor }),
+        });
+        return completeMutation({
+            ...completionInput(input.scope, channel, input.contractId, (review) => review, input.hooks),
+            accepted: continued,
+        });
+    });
+}
+export async function executeForwardedDeliver(input) {
+    const id = contractId(input.contractId);
+    const actor = actorOption(input.requester).actor;
+    const message = optionalNonblank(input.message, "deliver message");
+    const result = await executeLocalDelivery({
+        scope: scopeForRepo(input.repo),
+        contractId: id,
+        ...(actor === undefined ? {} : { actor }),
+        ...(message === undefined ? {} : { message }),
+        requireBranchesToBeUpToDate: input.requireBranchesToBeUpToDate,
+        includeDirty: input.includeDirty,
+        materializeConflict: input.materializeConflict,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+        hooks: input.hooks,
+    });
+    if (!("facts" in result))
+        return { result: deliveryResultSchema.parse(result) };
+    const delivery = result.facts.find((fact) => fact.kind === "deliver");
+    if (delivery === undefined)
+        throw new Error("accepted delivery is missing its journal fact");
+    return { result: deliveryResultSchema.parse(result), deliveryFactId: delivery.entry };
+}
+export async function executeForwardedReview(input) {
+    const id = contractId(input.contractId);
+    const actor = actorOption(input.requester).actor;
+    if (input.verdict !== "satisfied" && input.verdict !== "unsatisfied") {
+        invalidInput("verdict must be satisfied or unsatisfied");
+    }
+    const summary = optionalNonblank(input.summary, "review summary");
+    const result = await executeLocalReview({
+        scope: scopeForRepo(input.repo),
+        contractId: id,
+        ...(actor === undefined ? {} : { actor }),
+        verdict: input.verdict,
+        ...(summary === undefined ? {} : { summary }),
+        hooks: input.hooks,
+    });
+    const review = result.facts.find((fact) => fact.kind === "attestation");
+    if (review === undefined)
+        throw new Error("accepted review is missing its journal fact");
+    return { result: reviewResultSchema.parse(result), reviewFactId: review.entry };
+}
+export async function executeForwardedAudit(input) {
+    const id = contractId(input.contractId);
+    const actor = actorOption(input.requester).actor;
+    const result = await auditContract({
+        scope: scopeForRepo(input.repo),
+        contractId: id,
+        input: {
+            ...(actor === undefined ? {} : { actor }),
+            includeDirty: input.includeDirty,
+            showDiff: input.showDiff,
+            requireBranchesToBeUpToDate: input.requireBranchesToBeUpToDate,
+            ...(input.hooks === undefined ? {} : { hooks: input.hooks }),
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+        },
+    });
+    return { result: auditResultSchema.parse(result), auditReport: auditReportSchema.parse(result.value) };
+}

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

@@ -0,0 +1,36 @@
+import { type ContractId, type ContractState } from "../core/facts/types.js";
+import { type RepositoryScope } from "../protocol/operations.js";
+import type { AuditReport } from "../protocol/audit.js";
+import type { IntegrationConflictMaterialized } from "../protocol/deliver.js";
+import { type ReconcileInput } from "./repo.js";
+import { type ExecutionContext } from "../akuma/requests.js";
+import { type AuditInput } from "./audit.js";
+import { Delivery } from "./delivery.js";
+import { type MutationResult } from "./mutation.js";
+import type { AbandonInput, AmendInput, AmendResult, ArcInput, DeliverInput, ReconcileReport, ReviewInput, ContractHistory } from "./contract-types.js";
+import { type Review as OperationReview } from "./contract-operations.js";
+type Review = OperationReview;
+export declare class KeiyakuHandle {
+    private readonly id;
+    private readonly scope;
+    private readonly execution;
+    constructor(id: ContractId, scope: RepositoryScope, execution?: ExecutionContext);
+    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;
+}> | null;
+export {};

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

@@ -0,0 +1,313 @@
+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-guidance.js";
+import { actorOption, contractTerms, documentDerivation, normalizedGates, normalizedList, optionalBoolean, optionalNonblank, optionalSignal, invalidInput, requireInput, requireMarkdown, } from "./input.js";
+import { observeChangedRegion } from "./region.js";
+import { worktreeHooksOption } from "./configuration.js";
+import { contractId } from "../core/facts/types.js";
+import { contractObservationOperation, 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 } from "./repo.js";
+import { executionChannel, localExecutionContext } from "../akuma/requests.js";
+import { auditContract } from "./audit.js";
+import { deliveryHandle } from "./delivery.js";
+import { completionInput, completeHolderMutation, completeMutation } from "./mutation.js";
+import { completeReconcile } from "./reconcile.js";
+import { executeLocalDelivery, executeLocalReview, requestForwardedContractLive, } from "./contract-operations.js";
+import { KeiyakuRefused, requireAccepted } from "./refusal.js";
+export class KeiyakuHandle {
+    id;
+    scope;
+    execution;
+    constructor(id, scope, execution = localExecutionContext()) {
+        this.id = id;
+        this.scope = scope;
+        this.execution = execution;
+        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) {
+            return invalidInput("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 channel = executionChannel(this.execution);
+        const result = channel.kind === "local"
+            ? await executeLocalDelivery({
+                scope: this.scope,
+                contractId: this.id,
+                ...actor,
+                ...(message === undefined ? {} : { message }),
+                requireBranchesToBeUpToDate,
+                includeDirty,
+                materializeConflict,
+                ...(signal === undefined ? {} : { signal }),
+                hooks,
+            })
+            : await requestForwardedContractLive({
+                directory: channel.directory,
+                action: "contract.deliver",
+                request: {
+                    action: "contract.deliver",
+                    repoRoot: this.scope.primaryWorktree,
+                    contractId: this.id,
+                    ...(message === undefined ? {} : { message }),
+                    includeDirty,
+                    materializeConflict,
+                },
+                ...(signal === undefined ? {} : { signal }),
+            });
+        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") {
+            return invalidInput("verdict must be satisfied or unsatisfied");
+        }
+        const summary = optionalNonblank(values.summary, "review summary");
+        const actor = actorOption(values.actor);
+        const channel = executionChannel(this.execution);
+        if (channel.kind === "body-request") {
+            return await requestForwardedContractLive({
+                directory: channel.directory,
+                action: "contract.review",
+                request: {
+                    action: "contract.review",
+                    repoRoot: this.scope.primaryWorktree,
+                    contractId: this.id,
+                    verdict,
+                    ...(summary === undefined ? {} : { summary }),
+                },
+            });
+        }
+        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) {
+        const channel = executionChannel(this.execution);
+        if (channel.kind === "body-request") {
+            const values = input === undefined ? undefined : requireInput(input, "audit input");
+            worktreeHooksOption(values?.hooks);
+            actorOption(values?.actor);
+            const includeDirty = optionalBoolean(values?.includeDirty, "includeDirty") ?? false;
+            const showDiff = optionalBoolean(values?.showDiff, "showDiff") ?? false;
+            const requireBranchesToBeUpToDate = optionalBoolean(values?.requireBranchesToBeUpToDate, "requireBranchesToBeUpToDate") ?? false;
+            const signal = optionalSignal(values?.signal);
+            return await requestForwardedContractLive({
+                directory: channel.directory,
+                action: "contract.audit",
+                request: {
+                    action: "contract.audit",
+                    repoRoot: this.scope.primaryWorktree,
+                    contractId: this.id,
+                    includeDirty,
+                    showDiff,
+                    requireBranchesToBeUpToDate,
+                },
+                ...(signal === undefined ? {} : { signal }),
+            });
+        }
+        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) {
+    return value !== null && (typeof value === "object" || typeof value === "function")
+        ? (KEIYAKU_SEATS.get(value) ?? null)
+        : null;
+}