@astrosheep/keiyaku 4.0.4 → 4.0.6

package/build/src/protocol/arc.d.ts

@@ -0,0 +1,6 @@
+import type { ArcData } from "../core/facts/types.js";
+import { type ArcRefusal } from "../core/verbs/arc.js";
+import type { IntentOutcome, MutationOperationInput } from "./operations.js";
+export declare function arcOperation(input: MutationOperationInput & Readonly<{
+    chapter: Omit<ArcData, "seq">;
+}>): Promise<IntentOutcome<void, ArcRefusal>>;

package/build/src/protocol/arc.js

@@ -0,0 +1,12 @@
+import { decideArc } from "../core/verbs/arc.js";
+import { admitIntent } from "./intent.js";
+import { complete } from "./outcome.js";
+import { timestamp } from "./operations.js";
+export async function arcOperation(input) {
+    return complete(await admitIntent(input.channel, input.scope, {
+        contractId: input.contractId,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        at: timestamp(),
+        data: input.chapter,
+    }, decideArc), undefined);
+}

package/build/src/protocol/attempt.d.ts

@@ -1,7 +1,8 @@
 import { type PublicationFailed } from "../git/admission.js";
 import { type GitDecisionObservation } from "../git/observe.js";
 import type { GitDecodeChannel } from "../git/read-observation.js";
-import { type GitRefAssertion, type GitRepository } from "../git/repository.js";
+import { type GitRefAssertion } from "../git/repository.js";
+import type { GitRepository } from "../git/process.js";
 import type { AttemptContext } from "../core/decide.js";
 import type { Offer } from "../core/facts/offer.js";
 import { type ContractId, type ContractState, type EntryUlid, type JournalEntry } from "../core/facts/types.js";

package/build/src/protocol/audit.d.ts

@@ -0,0 +1,53 @@
+import { type DeliveryDiffScope } from "../git/integration.js";
+import type { ChangeId, ContractState, DeliverData } from "../core/facts/types.js";
+import { type AuditTargetAnswer } from "../git/target-placement.js";
+import type { DeliveryPreparationRefusal, DocumentDerivation, IntentOutcome, MutationOperationInput, VerificationStop } from "./operations.js";
+type AuditWorkspace = Readonly<{
+    kind: "worktree" | "here";
+    path: string;
+}>;
+type DiffScope = DeliveryDiffScope;
+export type AuditReport = Readonly<{
+    candidate: Readonly<{
+        kind: "blocked";
+        refusal: DeliveryPreparationRefusal;
+    }> | Readonly<{
+        kind: "ready";
+        workspace: AuditWorkspace;
+        identity: DeliverData;
+        scope: DiffScope;
+        diff?: string;
+    }>;
+    verification: Readonly<{
+        kind: "not-run";
+    }> | Readonly<{
+        kind: "satisfied";
+        passed: number;
+        total: number;
+        summary?: string;
+    }> | Readonly<{
+        kind: "unsatisfied";
+        passed: number;
+        total: number;
+        summary?: string;
+    }> | Readonly<{
+        kind: "stopped";
+        stop: VerificationStop;
+    }>;
+    target: Readonly<{
+        kind: "not-observed";
+    }> | AuditTargetAnswer;
+    delivery?: Readonly<{
+        changeId: ChangeId;
+        relation: "identical" | "differs";
+    }>;
+}>;
+type AuditOperationInput = MutationOperationInput & Readonly<{
+    deriveDocument?: (state: ContractState) => DocumentDerivation;
+    requireBranchesToBeUpToDate?: boolean;
+    includeDirty?: boolean;
+    showDiff?: boolean;
+    signal?: AbortSignal;
+}>;
+export declare function auditOperation(input: AuditOperationInput): Promise<IntentOutcome<AuditReport>>;
+export {};

package/build/src/protocol/audit.js

@@ -0,0 +1,147 @@
+import { readDeliveryDiff, readDeliveryScope } from "../git/integration.js";
+import { observeContractsForAdmissionAt } from "../git/observe.js";
+import { activeContract, documentIsCurrent } from "../core/facts/observation.js";
+import { adjudicateAuditTarget } from "../git/target-placement.js";
+import { readManagedWorktreeAppointment } from "../workspace-place.js";
+import { verifyDelivery } from "./intent.js";
+import { accepted, admitted } from "./outcome.js";
+import { prepareDelivery } from "./deliver.js";
+import { timestamp, unpackVerificationOutcome } from "./operations.js";
+async function auditWorkspace(repository, state, resolveHereWorkspace) {
+    if (state.coordinates.workspace === "here") {
+        const path = resolveHereWorkspace === undefined
+            ? repository.effectiveCwd
+            : await resolveHereWorkspace(state.id);
+        return path === undefined
+            ? { kind: "unappointed" }
+            : { kind: "ready", answer: { kind: "here", path } };
+    }
+    const appointed = await readManagedWorktreeAppointment(repository, state.id);
+    if (appointed.kind === "failed")
+        throw new Error(appointed.diagnostic);
+    if (appointed.kind === "unappointed")
+        return appointed;
+    return { kind: "ready", answer: { kind: "worktree", path: appointed.path }, appointment: appointed };
+}
+function auditDeliveryRelation(state, candidate) {
+    const recorded = state.delivery?.data.integration.changeId;
+    if (recorded === undefined)
+        return undefined;
+    return { changeId: recorded, relation: recorded === candidate.integration.changeId ? "identical" : "differs" };
+}
+async function auditCandidateVerification(input, state, snapshot, definition) {
+    const verification = await verifyDelivery({
+        channel: input.channel,
+        repository: input.scope,
+        contractId: input.contractId,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        at: timestamp(),
+        state,
+        snapshot,
+        environment: process.env,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+        verification: definition,
+    });
+    if (verification === null)
+        throw new Error("audit verification preparation unexpectedly produced no attempt");
+    return unpackVerificationOutcome(verification);
+}
+function auditVerificationAnswer(verified) {
+    if (verified === undefined)
+        return { kind: "not-run" };
+    if (verified.stop !== undefined)
+        return { kind: "stopped", stop: verified.stop };
+    if (verified.counts === undefined)
+        throw new Error("terminal Verification is missing producer counts");
+    return {
+        kind: verified.counts.verdict,
+        passed: verified.counts.passed,
+        total: verified.counts.total,
+        ...(verified.counts.summary === undefined ? {} : { summary: verified.counts.summary }),
+    };
+}
+async function readyAuditCandidate(repository, candidate, workspace, showDiff) {
+    const predecessor = candidate.integration.predecessor;
+    const snapshot = candidate.integration.snapshot;
+    const scope = await readDeliveryScope(repository, predecessor, snapshot, showDiff);
+    const diff = showDiff ? await readDeliveryDiff(repository, predecessor, snapshot) : undefined;
+    return {
+        kind: "ready",
+        workspace,
+        identity: candidate,
+        scope,
+        ...(diff === undefined || diff === null ? {} : { diff }),
+    };
+}
+async function auditTargetAnswer(repository, state, candidate, workspacePath) {
+    const target = state.coordinates.target;
+    if (target === undefined)
+        return { kind: "not-observed" };
+    return await adjudicateAuditTarget(repository, {
+        contractId: state.id,
+        coordinates: { ...state.coordinates, target },
+        predecessor: candidate.integration.predecessor,
+        candidate: candidate.integration.snapshot,
+        ...(workspacePath === undefined ? {} : { hereWorkspacePath: workspacePath }),
+    });
+}
+function blockedAudit(refusal) {
+    return {
+        candidate: { kind: "blocked", refusal },
+        verification: { kind: "not-run" },
+        target: { kind: "not-observed" },
+    };
+}
+function completedAudit(state, verified, value) {
+    const obligations = {
+        ...(verified?.cleanup === undefined ? {} : { cleanup: verified.cleanup }),
+        ...(verified?.leak === undefined ? {} : { leak: verified.leak }),
+    };
+    return verified?.admission === undefined
+        ? accepted(state, [], value, undefined, obligations)
+        : { ...admitted(verified.admission, value), ...obligations };
+}
+export async function auditOperation(input) {
+    const observed = await observeContractsForAdmissionAt(input.scope, input.channel, [input.contractId]);
+    const state = activeContract(observed.decision, input.contractId);
+    if ("kind" in state)
+        return { kind: "refused", refusal: state };
+    const derivation = input.deriveDocument?.(state);
+    if (derivation === undefined || !documentIsCurrent(state, derivation.document)) {
+        return { kind: "refused", refusal: { kind: "document-moved", contractId: input.contractId } };
+    }
+    if (derivation.verification.kind === "refused")
+        return { kind: "refused", refusal: derivation.verification.refusal };
+    const workspace = await auditWorkspace(input.scope, state, input.resolveHereWorkspace);
+    if (workspace.kind === "unappointed") {
+        return accepted(state, [], blockedAudit({ kind: "worktree-missing", contractId: state.id }));
+    }
+    const prepared = await prepareDelivery(input.scope, {
+        contractId: state.id,
+        coordinates: state.coordinates,
+        ...(workspace.appointment === undefined ? {} : { appointment: workspace.appointment }),
+        ...(workspace.answer.kind === "here" ? { workspacePath: workspace.answer.path } : {}),
+    }, {
+        title: derivation.title,
+        document: derivation.bytes,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        requireBranchesToBeUpToDate: input.requireBranchesToBeUpToDate ?? false,
+        includeDirty: input.includeDirty ?? false,
+    });
+    if (prepared.kind === "refused")
+        return accepted(state, [], blockedAudit(prepared.refusal));
+    const verified = derivation.verification.data === null
+        ? undefined
+        : await auditCandidateVerification(input, state, prepared.data.integration.snapshot, derivation.verification.data);
+    const verification = auditVerificationAnswer(verified);
+    const delivery = auditDeliveryRelation(state, prepared.data);
+    const value = {
+        candidate: await readyAuditCandidate(input.scope, prepared.data, workspace.answer, input.showDiff === true),
+        verification,
+        target: verification.kind === "stopped"
+            ? { kind: "not-observed" }
+            : await auditTargetAnswer(input.scope, state, prepared.data, workspace.answer.kind === "here" ? workspace.answer.path : undefined),
+        ...(delivery === undefined ? {} : { delivery }),
+    };
+    return completedAudit(state, verified, value);
+}

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

@@ -1,4 +1,4 @@
-import type { GitRepository } from "../git/repository.js";
+import type { GitRepository } from "../git/process.js";
 import type { GitDecodeChannel } from "../git/read-observation.js";
 import type { BindData, ActorId, ContractId } from "../core/facts/types.js";
 import { type BindRefusal } from "../core/verbs/bind.js";

package/build/src/protocol/completion.d.ts

@@ -0,0 +1,42 @@
+import type { ActorId, ContractId, SnapshotId } from "../core/facts/types.js";
+import type { WorktreeLeak } from "../git/scratch.js";
+import type { GitRepository } from "../git/process.js";
+import type { GitDecodeChannel } from "../git/read-observation.js";
+import type { VerificationDeclarationPreparation } from "../verification/declaration.js";
+import { type CurrentVerifiedAttestation, type VerificationCleanupFailure } from "./intent.js";
+import type { AcceptedProtocolStep } from "./outcome.js";
+import type { PlacementStop, VerificationStop } from "./operations.js";
+export type CandidateCompletion = Readonly<{
+    integration: SnapshotId;
+    verification?: Readonly<{
+        mode: "ran" | "reused";
+        verdict: "satisfied" | "unsatisfied";
+    }>;
+}>;
+export type CompletionEvidence = Readonly<{
+    completion?: CandidateCompletion;
+    verification?: VerificationStop;
+    verificationReuse?: CurrentVerifiedAttestation;
+    verificationSummary?: string;
+    placement?: PlacementStop;
+    cleanup?: VerificationCleanupFailure;
+    leak?: WorktreeLeak;
+}>;
+type CompletionInput = Readonly<{
+    channel: GitDecodeChannel;
+    repository: GitRepository;
+    contractId: ContractId;
+    target?: string;
+    actor?: ActorId;
+    signal?: AbortSignal;
+    verification: VerificationDeclarationPreparation;
+    initial: AcceptedProtocolStep;
+    verifyInitial: boolean;
+    hereWorkspacePath?: string;
+}>;
+export type CompletionResult = Readonly<{
+    admission: AcceptedProtocolStep;
+    evidence: CompletionEvidence;
+}>;
+export declare function completeCandidate(input: CompletionInput): Promise<CompletionResult>;
+export {};

package/build/src/protocol/completion.js

@@ -0,0 +1,183 @@
+import { currentVerifiedAttestation, verifyDelivery } from "./intent.js";
+import { admitPlacement } from "./placement.js";
+import { reintegrateOperation } from "./reintegrate.js";
+import { mergeAdmissions, placementStop, timestamp, unpackVerificationOutcome } from "./operations.js";
+const MAX_REINTEGRATION_CYCLES = 3;
+function reintegrationStop(result) {
+    if (result.kind === "placement-failed") {
+        return { failure: "target-placement-failed", diagnostic: result.diagnostic };
+    }
+    if (result.kind === "refused")
+        return { refusal: result.refusal };
+    return { retry: result.reason };
+}
+async function verificationFor(input, admission, snapshot) {
+    const current = currentVerifiedAttestation(admission.state);
+    if (current !== undefined) {
+        return {
+            admission,
+            evidence: { verificationReuse: current },
+            completionVerification: {
+                mode: "reused",
+                verdict: current.verdict,
+                ...(current.summary === undefined ? {} : { summary: current.summary }),
+            },
+        };
+    }
+    if (input.verification.kind === "refused") {
+        return { admission, evidence: { verification: { refusal: input.verification.refusal } } };
+    }
+    const result = await verifyDelivery({
+        channel: input.channel,
+        repository: input.repository,
+        contractId: input.contractId,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        at: timestamp(),
+        state: admission.state,
+        snapshot,
+        environment: process.env,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+        ...(input.verification.data === null ? {} : { verification: input.verification.data }),
+    });
+    if (result === null)
+        return { admission, evidence: {} };
+    const unpacked = unpackVerificationOutcome(result);
+    return {
+        admission: unpacked.admission === undefined ? admission : mergeAdmissions(admission, unpacked.admission),
+        evidence: {
+            ...(unpacked.stop === undefined ? {} : { verification: unpacked.stop }),
+            ...(unpacked.counts?.verdict !== "unsatisfied" || unpacked.counts.summary === undefined
+                ? {}
+                : { verificationSummary: unpacked.counts.summary }),
+            ...(unpacked.cleanup === undefined ? {} : { cleanup: unpacked.cleanup }),
+            ...(unpacked.leak === undefined ? {} : { leak: unpacked.leak }),
+        },
+        ...(unpacked.counts === undefined
+            ? {}
+            : {
+                completionVerification: {
+                    mode: "ran",
+                    verdict: unpacked.counts.verdict,
+                    ...(unpacked.counts.summary === undefined ? {} : { summary: unpacked.counts.summary }),
+                },
+            }),
+    };
+}
+function mergeEvidence(current, next) {
+    const merged = { ...current, ...next };
+    if (next.verification !== undefined) {
+        const { verificationReuse: _ignored, ...withoutReuse } = merged;
+        return withoutReuse;
+    }
+    if (next.verificationReuse !== undefined) {
+        const { verification: _ignored, ...withoutVerification } = merged;
+        return withoutVerification;
+    }
+    return merged;
+}
+function replaceVerificationEvidence(current, next) {
+    const { verification: _verification, verificationReuse: _verificationReuse, verificationSummary: _verificationSummary, ...withoutVerification } = current;
+    return mergeEvidence(withoutVerification, next);
+}
+function requiredPlacementStop(result) {
+    const stop = placementStop(result);
+    if (stop === undefined)
+        throw new Error("non-accepted placement is missing its stop");
+    return stop;
+}
+function acceptedCompletion(admission, completionVerification) {
+    const integration = admission.state.currentIntegration?.snapshot;
+    if (integration === undefined)
+        throw new Error("accepted placement is missing its final integration");
+    const current = completionVerification ?? currentVerifiedAttestation(admission.state);
+    const verification = current === undefined
+        ? undefined
+        : { mode: completionVerification?.mode ?? "reused", verdict: current.verdict };
+    const summary = current?.summary;
+    return {
+        completion: {
+            integration,
+            ...(verification === undefined ? {} : { verification }),
+        },
+        ...(verification?.verdict !== "unsatisfied" || summary === undefined ? {} : { verificationSummary: summary }),
+    };
+}
+async function admitCurrentPlacement(input) {
+    return await admitPlacement({
+        channel: input.channel,
+        repository: input.repository,
+        target: input.target,
+        placement: {
+            contractId: input.contractId,
+            ...(input.actor === undefined ? {} : { actor: input.actor }),
+            at: timestamp(),
+        },
+        ...(input.hereWorkspacePath === undefined ? {} : { hereWorkspacePath: input.hereWorkspacePath }),
+    });
+}
+export async function completeCandidate(input) {
+    let admission = input.initial;
+    let evidence = {};
+    let completionVerification;
+    if (input.verifyInitial) {
+        const snapshot = admission.state.currentIntegration?.snapshot;
+        if (snapshot === undefined)
+            throw new Error("accepted delivery is missing its current integration");
+        const verified = await verificationFor(input, admission, snapshot);
+        admission = verified.admission;
+        evidence = mergeEvidence(evidence, verified.evidence);
+        completionVerification = verified.completionVerification;
+    }
+    let placement = await admitCurrentPlacement(input);
+    if (placement.kind === "accepted") {
+        admission = mergeAdmissions(admission, placement);
+        return { admission, evidence: mergeEvidence(evidence, acceptedCompletion(admission, completionVerification)) };
+    }
+    if (placement.kind !== "target-moved" || input.target === undefined) {
+        return { admission, evidence: mergeEvidence(evidence, { placement: requiredPlacementStop(placement) }) };
+    }
+    let integratedAt;
+    for (let attempts = 1; attempts <= MAX_REINTEGRATION_CYCLES; attempts += 1) {
+        const reintegrated = await reintegrateOperation({
+            channel: input.channel,
+            repository: input.repository,
+            contractId: input.contractId,
+            target: input.target,
+            ...(input.actor === undefined ? {} : { actor: input.actor }),
+            ...(input.hereWorkspacePath === undefined ? {} : { hereWorkspacePath: input.hereWorkspacePath }),
+        });
+        if (reintegrated.kind !== "accepted") {
+            return { admission, evidence: mergeEvidence(evidence, { placement: reintegrationStop(reintegrated) }) };
+        }
+        admission = mergeAdmissions(admission, reintegrated);
+        integratedAt = reintegrated.value.snapshot;
+        const verified = await verificationFor(input, admission, reintegrated.value.snapshot);
+        admission = verified.admission;
+        evidence = replaceVerificationEvidence(evidence, verified.evidence);
+        completionVerification = verified.completionVerification;
+        placement = await admitCurrentPlacement(input);
+        if (placement.kind === "accepted") {
+            admission = mergeAdmissions(admission, placement);
+            return { admission, evidence: mergeEvidence(evidence, acceptedCompletion(admission, completionVerification)) };
+        }
+        if (placement.kind !== "target-moved") {
+            return { admission, evidence: mergeEvidence(evidence, { placement: requiredPlacementStop(placement) }) };
+        }
+        if (attempts === MAX_REINTEGRATION_CYCLES) {
+            return {
+                admission,
+                evidence: mergeEvidence(evidence, {
+                    placement: {
+                        failure: "target-moved",
+                        contractId: input.contractId,
+                        target: input.target,
+                        integratedAt: integratedAt,
+                        observed: placement.observed,
+                        attempts,
+                    },
+                }),
+            };
+        }
+    }
+    throw new Error("reintegration cycle bound was not enforced");
+}

package/build/src/protocol/deliver.d.ts

@@ -0,0 +1,49 @@
+import type { ActorId, ContractId, ContractState, DeliverData, SnapshotId } from "../core/facts/types.js";
+import type { CurrentVerifiedAttestation } from "./intent.js";
+import { type CompletionEvidence } from "./completion.js";
+import { type ManagedWorktreeAppointment } from "../workspace-place.js";
+import type { DeliveryPreparationRefusal, DocumentDerivation, IntentOutcome, MutationOperationInput } from "./operations.js";
+type DeliveryIdentity = DeliverData;
+export type VerificationReuse = CurrentVerifiedAttestation;
+export type DeliverValue = DeliveryIdentity & CompletionEvidence;
+export type AppointedWorkspace = Readonly<{
+    kind: "here" | "worktree";
+    path: string;
+}>;
+export type IntegrationConflictMaterialized = Readonly<{
+    kind: "integration-conflict-materialized";
+    targetHead: SnapshotId;
+    conflictPaths: readonly string[];
+    workspace: AppointedWorkspace;
+}>;
+type DeliverOperationInput = MutationOperationInput & Readonly<{
+    deriveDocument: (state: ContractState) => DocumentDerivation;
+    message?: string;
+    requireBranchesToBeUpToDate: boolean;
+    includeDirty: boolean;
+    materializeConflict: boolean;
+    signal?: AbortSignal;
+}>;
+export declare function prepareDelivery(repository: import("../git/process.js").GitRepository, stage: Readonly<{
+    contractId: ContractId;
+    coordinates: ContractState["coordinates"];
+    appointment?: Extract<ManagedWorktreeAppointment, {
+        kind: "appointed";
+    }>;
+    workspacePath?: string;
+}>, input: Readonly<{
+    title: string;
+    document: string;
+    actor?: ActorId;
+    message?: string;
+    requireBranchesToBeUpToDate?: boolean;
+    includeDirty?: boolean;
+}>): Promise<{
+    kind: "prepared";
+    data: DeliverData;
+} | {
+    kind: "refused";
+    refusal: DeliveryPreparationRefusal;
+}>;
+export declare function deliverOperation(input: DeliverOperationInput): Promise<IntentOutcome<DeliverValue> | IntegrationConflictMaterialized>;
+export {};