@astrosheep/keiyaku 4.5.29 → 4.6.2

package/build/src/protocol/operations.js

@@ -1,11 +1,186 @@
-import { readDeliveryDiff } from "../git/integration.js";
+import { z } from "zod";
+import { boundedListLimit } from "../bounded-list.js";
+import { gate } from "../core/facts/types.js";
+import { changeIdSchema, contractIdSchema, snapshotIdSchema } from "../git/identity.js";
+import { integrationPreparationRefusalSchema, readDeliveryDiff } from "../git/integration.js";
 import { currentBranch, observeContractAt } from "../git/observe.js";
-import { repositoryAt } from "../git/repository.js";
-import { withGitReadObservation } from "../git/read-observation.js";
 import { appendPrivateStateSeatClose, concatenatePrivateStateSeatClose, mergePrivateStateSeatClose, } from "../git/private-state-seat.js";
+import { withGitReadObservation } from "../git/read-observation.js";
+import { repositoryAt } from "../git/repository.js";
+import { checkoutNotFollowableRefusalSchema } from "../git/target-placement.js";
+import { dirtyWorkspaceRefusalSchema, unmergedPathsRefusalSchema, worktreeMissingRefusalSchema, } from "../git/tender.js";
+import { conflictRecoverySchema, worktreeWorkspaceSchema } from "../git/workspace.js";
+import { forkSourceMovedRefusalSchema, targetInputRefusalSchema } from "./bind.js";
+import { verificationRuntimeStopSchema } from "./intent.js";
 import { readDocuments } from "./read/documents.js";
 import { readContractBoard, readContractCatalogue, readContractObservationAt, } from "./read/status.js";
-import { boundedListLimit } from "../bounded-list.js";
+import { protocolTerminalSchema } from "./run.js";
+export { changeIdSchema, contractIdSchema, snapshotIdSchema } from "../git/identity.js";
+export { entryUlidSchema } from "./attempt.js";
+export const gateSchema = z.string().transform((value, context) => {
+    try {
+        return gate(value);
+    }
+    catch {
+        context.addIssue({ code: "custom", message: "invalid gate" });
+        return z.NEVER;
+    }
+});
+export const deliverDataSchema = z
+    .object({
+    tenderSnapshot: snapshotIdSchema,
+    integration: z
+        .object({ predecessor: snapshotIdSchema, snapshot: snapshotIdSchema, changeId: changeIdSchema })
+        .strict(),
+    method: z.literal("squash"),
+    policy: z.object({ requireBranchesToBeUpToDate: z.boolean() }).strict(),
+})
+    .strict();
+export const verdictSchema = z.enum(["satisfied", "unsatisfied"]);
+export const activeContractRefusalSchema = z
+    .object({ kind: z.enum(["contract-missing", "terminal"]), contractId: contractIdSchema })
+    .strict();
+export const bindRefusalSchema = z
+    .object({ kind: z.enum(["contract-exists", "invalid-after", "unknown-prerequisite"]), contractId: contractIdSchema })
+    .strict();
+export const amendRefusalSchema = z
+    .object({
+    kind: z.enum(["contract-missing", "terminal", "terms-moved", "unknown-prerequisite", "cyclic-prerequisite"]),
+    contractId: contractIdSchema,
+})
+    .strict();
+export const deliverRefusalSchema = z
+    .object({ kind: z.enum(["contract-missing", "terminal", "document-moved"]), contractId: contractIdSchema })
+    .strict();
+export const verificationDeclarationRefusalSchema = z
+    .object({ kind: z.literal("verification-declaration-invalid"), contractId: contractIdSchema.optional() })
+    .strict();
+const staleGateReasonSchema = z
+    .object({
+    kind: z.literal("candidate-content-changed"),
+    target: z.string().optional(),
+    previousChange: changeIdSchema,
+    currentChange: changeIdSchema,
+})
+    .strict();
+export const gateReportSchema = z
+    .object({
+    gate: gateSchema,
+    current: z.union([
+        z.object({ kind: z.literal("missing") }).strict(),
+        z
+            .object({ kind: z.literal("attested"), verdict: verdictSchema, at: z.string(), summary: z.string().optional() })
+            .strict(),
+        z
+            .object({ kind: z.literal("stale"), priorVerdict: verdictSchema, reason: staleGateReasonSchema.optional() })
+            .strict(),
+    ]),
+})
+    .strict();
+export const placementRefusalSchema = z.union([
+    z
+        .object({ kind: z.enum(["contract-missing", "delivery-missing", "terminal"]), contractId: contractIdSchema })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("gates-unsatisfied"),
+        contractId: contractIdSchema,
+        unmet: z.array(gateReportSchema).readonly(),
+        target: z.string().min(1).optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("prerequisites-unsatisfied"),
+        contractId: contractIdSchema,
+        unmet: z
+            .array(z.object({ contractId: contractIdSchema, state: z.enum(["missing", "active", "abandoned"]) }).strict())
+            .readonly(),
+    })
+        .strict(),
+]);
+const mergeStatePresentRefusalSchema = z
+    .object({ kind: z.literal("merge-state-present"), contractId: contractIdSchema, workspace: worktreeWorkspaceSchema })
+    .strict();
+export const deliverConflictRefusalSchema = z
+    .object({
+    kind: z.literal("integration-failed"),
+    contractId: contractIdSchema,
+    reason: z.literal("conflict"),
+    targetHead: snapshotIdSchema,
+    conflictPaths: z.array(z.string().refine((value) => value.trim() !== "")).readonly(),
+    recovery: conflictRecoverySchema,
+})
+    .strict();
+const targetMissingRefusalSchema = z
+    .object({ kind: z.literal("target-missing"), contractId: contractIdSchema })
+    .strict();
+export const deliveryPreparationRefusalSchema = z.union([
+    targetMissingRefusalSchema,
+    worktreeMissingRefusalSchema,
+    dirtyWorkspaceRefusalSchema,
+    unmergedPathsRefusalSchema,
+    integrationPreparationRefusalSchema,
+    mergeStatePresentRefusalSchema,
+    checkoutNotFollowableRefusalSchema,
+]);
+export const intentRefusalSchema = z.union([
+    activeContractRefusalSchema,
+    amendRefusalSchema,
+    bindRefusalSchema,
+    forkSourceMovedRefusalSchema,
+    deliverRefusalSchema,
+    deliveryPreparationRefusalSchema,
+    deliverConflictRefusalSchema,
+    placementRefusalSchema,
+    targetInputRefusalSchema,
+    verificationDeclarationRefusalSchema,
+]);
+export const verificationStopSchema = z.union([
+    z.object({ refusal: z.union([activeContractRefusalSchema, verificationDeclarationRefusalSchema]) }).strict(),
+    z.object({ retry: protocolTerminalSchema }).strict(),
+    verificationRuntimeStopSchema,
+]);
+export const placementStopSchema = z.union([
+    z
+        .object({
+        refusal: z.union([
+            placementRefusalSchema,
+            checkoutNotFollowableRefusalSchema,
+            integrationPreparationRefusalSchema,
+            targetMissingRefusalSchema,
+        ]),
+    })
+        .strict(),
+    z.object({ retry: protocolTerminalSchema }).strict(),
+    z
+        .object({
+        failure: z.literal("target-placement-failed"),
+        diagnostic: z.string().refine((value) => value.trim() !== ""),
+    })
+        .strict(),
+    z
+        .object({
+        failure: z.literal("target-moved"),
+        contractId: contractIdSchema,
+        target: z.string().refine((value) => value.trim() !== ""),
+        integratedAt: snapshotIdSchema,
+        observed: snapshotIdSchema.nullable(),
+        attempts: z.number().int(),
+        observedTreeEqualsCandidate: z.boolean(),
+    })
+        .strict(),
+    z
+        .object({
+        failure: z.literal("target-moved"),
+        contractId: contractIdSchema,
+        target: z.string().refine((value) => value.trim() !== ""),
+        expected: snapshotIdSchema,
+        observed: snapshotIdSchema.nullable(),
+        observedTreeEqualsCandidate: z.boolean(),
+    })
+        .strict(),
+]);
 export function timestamp() {
     return new Date().toISOString();
 }
@@ -34,13 +209,20 @@ export function stepStop(result) {
 }
 export function unpackVerificationOutcome(verification) {
     const step = verification.step;
-    const stop = "failure" in step ? step : stepStop(step);
+    const stop = "failure" in step
+        ? step
+        : "refusal" in step && step.refusal.kind === "verification-reuse"
+            ? undefined
+            : "kind" in step && step.kind === "reused"
+                ? undefined
+                : stepStop(step);
     const admission = !("failure" in step) && step.kind === "accepted" ? step : undefined;
     return {
         ...(verification.cleanup === undefined ? {} : { cleanup: verification.cleanup }),
         ...(verification.leak === undefined ? {} : { leak: verification.leak }),
         ...(stop === undefined ? {} : { stop }),
         ...(admission === undefined ? {} : { admission }),
+        ...(verification.reuse === undefined ? {} : { reuse: verification.reuse }),
         ...(verification.counts === undefined ? {} : { counts: verification.counts }),
     };
 }
@@ -79,11 +261,9 @@ export async function contractObservationOperation(input) {
 export async function documentsOperationAt(scope, channel) {
     return withGitReadObservation(scope, channel, readDocuments);
 }
+/** A legitimately absent Contract is `null`; the caller maps absence to its own domain answer. */
 export async function stateOperation(input) {
-    const state = (await observeContractAt(input.scope, input.channel, input.contractId)).state;
-    if (state === null)
-        throw new Error(`contract does not exist: ${input.contractId}`);
-    return state;
+    return (await observeContractAt(input.scope, input.channel, input.contractId)).state;
 }
 export async function deliveryOperation(input) {
     const state = (await observeContractAt(input.scope, input.channel, input.contractId)).state;

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

@@ -17,7 +17,7 @@ export type LeadingOutcome<Value, Refusal> = (AcceptedProtocolStep & Readonly<{
     kind: "retry";
     reason: ProtocolTerminal;
 }>;
-export type AcceptedObligations = Readonly<{
+type AcceptedObligations = Readonly<{
     cleanup?: VerificationCleanupFailure;
     leak?: WorktreeLeak;
     seatClose?: readonly PrivateStateSeatCloseLag[];
@@ -39,3 +39,4 @@ export declare function accepted<Value, Refusal = never>(state: ContractState, f
 export declare function admitted<Value, Refusal = never>(admission: AcceptedProtocolStep, value: Value): IntentOutcome<Value, Refusal>;
 export declare function complete<Value, Refusal>(result: ProtocolResult<Refusal>, value: Value): IntentOutcome<Value, Refusal>;
 export declare function intentOutcomeWithSeatClose<Value, Refusal>(outcome: PrivateStateSeatOutcome<IntentOutcome<Value, Refusal>>): IntentOutcome<Value, Refusal>;
+export {};

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

@@ -1,4 +1,4 @@
-import type { ExecutionProgress } from "./progress.js";
+import type { ProtocolProgress } from "./progress.js";
 import type { ActorId, ContractId, SnapshotId } from "../core/facts/types.js";
 import { type PlacementRefusal } from "../core/verbs/placement.js";
 import type { GitDecodeChannel } from "../git/read-observation.js";
@@ -34,7 +34,7 @@ type PlacementAdmissionInput<ExtraRefusal> = Readonly<{
     target: string | undefined;
     placement: PlacementProtocolInput;
     onDeliveryMissing?: () => Promise<PlacementProtocolResult<ExtraRefusal> | undefined>;
-    progress?: ExecutionProgress;
+    progress?: ProtocolProgress;
 }>;
 /** Hold the existing target-placement fence for one owner callback. */
 export declare function runUnderTargetPlacementFence<T>(repository: GitRepository, target: string, run: () => Promise<T>, onReleaseFailure?: (result: T, error: unknown) => T | PlacementExecutionFailure): Promise<T | PlacementExecutionFailure>;

package/build/src/protocol/placement.js

@@ -102,7 +102,9 @@ async function runFencedPlacement(repository, input, protocol) {
             return result;
         if (preparedPhysical === undefined)
             throw new Error("accepted placement has no prepared target checkout");
-        return { ...result, physical: await followTargetPlacement(repository, preparedPhysical) };
+        const physical = await followTargetPlacement(repository, preparedPhysical, (report) => protocol.progress?.recordPlacementPhysical(input.contractId, report));
+        protocol.progress?.recordPlacementPhysical(input.contractId, physical);
+        return { ...result, physical };
     }
     return { kind: "exhausted" };
 }

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

@@ -1,86 +1,129 @@
+import { z } from "zod";
 import type { ContractHead, ContractId, ContractState, JournalEntry, SnapshotId } from "../core/facts/types.js";
 import type { ReconcileResult } from "../git/reconcile.js";
 import type { WorktreeLeak } from "../git/scratch.js";
-import type { PrivateStateSeatCloseLag } from "../git/private-state-seat.js";
+import { type PrivateStateSeatCloseLag } from "../git/private-state-seat.js";
 import type { VerificationCleanupFailure } from "./intent.js";
-import type { AcceptedProtocolStep, IntentOutcome } from "./outcome.js";
-import { type ExecutionEvent, type ExecutionObserver } from "./execution-observation.js";
+import type { AcceptedProtocolStep } from "./outcome.js";
+import type { ExecutionObservation } from "./execution-observation.js";
+import type { CandidateCompletion, CompletionEvidence } from "./completion.js";
 /** A captured interpretation is not an invocation's admission receipt. */
 export type ContractCheckpoint = Readonly<{
     state: ContractState;
     journal: readonly JournalEntry[];
 }>;
 export declare function contractCheckpoint(input: ContractCheckpoint): ContractCheckpoint;
-export type ExecutionCleanup = Readonly<{
-    kind: "verification-cleanup";
-    contractId: ContractId;
-    snapshot?: SnapshotId;
-    failure: VerificationCleanupFailure;
-}> | Readonly<{
-    kind: "worktree-leak";
-    contractId: ContractId;
-    snapshot?: SnapshotId;
-    leak: WorktreeLeak;
-}> | Readonly<{
-    kind: "private-state-seat-close";
-    contractId: ContractId;
-    failure: PrivateStateSeatCloseLag;
-}>;
-export type ExecutionStage = "admission" | "verification" | "placement" | "reintegration" | "continuation" | "reconciliation";
-export type ExecutionStop = Readonly<{
-    kind: "execution-stopped";
-    contractId: ContractId;
-    stage: ExecutionStage;
-    reason: "cancelled" | "failed";
-    diagnostic: string;
+export declare const executionCleanupSchema: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"decode-channel-retirement">;
+    contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+    diagnostic: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"verification-cleanup">;
+    contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+    snapshot: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<SnapshotId, string>>>;
+    failure: z.ZodObject<{
+        phase: z.ZodLiteral<"destroy">;
+        name: z.ZodString;
+        detail: z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"exit">;
+            code: z.ZodNumber;
+            stdout: z.ZodString;
+            stderr: z.ZodString;
+            truncated: z.ZodBoolean;
+        }, z.core.$strict>, z.ZodObject<{
+            stdout: z.ZodOptional<z.ZodString>;
+            stderr: z.ZodOptional<z.ZodString>;
+            truncated: z.ZodOptional<z.ZodBoolean>;
+            kind: z.ZodLiteral<"timeout">;
+        }, z.core.$strict>, z.ZodObject<{
+            stdout: z.ZodOptional<z.ZodString>;
+            stderr: z.ZodOptional<z.ZodString>;
+            truncated: z.ZodOptional<z.ZodBoolean>;
+            kind: z.ZodLiteral<"unknown-exit">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"spawn-error">;
+            diagnostic: z.ZodString;
+        }, z.core.$strict>]>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"worktree-leak">;
+    contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+    snapshot: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<SnapshotId, string>>>;
+    leak: z.ZodObject<{
+        path: z.ZodString;
+        diagnostic: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"private-state-seat-close">;
+    contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+    failure: z.ZodObject<{
+        kind: z.ZodLiteral<"private-state-seat-close-failed">;
+        diagnostic: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>]>;
+export type ExecutionCleanup = z.infer<typeof executionCleanupSchema>;
+export declare const executionStageSchema: z.ZodEnum<{
+    admission: "admission";
+    placement: "placement";
+    verification: "verification";
+    continuation: "continuation";
+    reconciliation: "reconciliation";
+    reintegration: "reintegration";
 }>;
+export type ExecutionStage = z.infer<typeof executionStageSchema>;
+export declare const executionStopSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"execution-stopped">;
+    contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+    stage: z.ZodEnum<{
+        admission: "admission";
+        placement: "placement";
+        verification: "verification";
+        continuation: "continuation";
+        reconciliation: "reconciliation";
+        reintegration: "reintegration";
+    }>;
+    reason: z.ZodEnum<{
+        failed: "failed";
+        cancelled: "cancelled";
+    }>;
+    diagnostic: z.ZodString;
+}, z.core.$strict>;
+export type ExecutionStop = z.infer<typeof executionStopSchema>;
+/** Only owner-declared operational classes and native system I/O failures are operational. */
+export declare function isOperationalFailure(error: unknown): error is Error;
+/** Cancellation is witnessed by this exact signal reason, not by a signal merely being aborted. */
+export declare function isOperationalStop(error: unknown, signal?: AbortSignal): boolean;
 /** Classify operational failures only; programming errors and corrupt authority still throw. */
 export declare function executionStop(contractId: ContractId, stage: ExecutionStage, error: unknown, signal?: AbortSignal): ExecutionStop;
-export type ExecutionSnapshot = Readonly<{
-    facts: readonly JournalEntry[];
-    checkpoints: ReadonlyMap<ContractId, ContractCheckpoint>;
-    heads: ReadonlyMap<ContractId, ContractHead>;
-    affected: readonly ContractId[];
-    physical: ReconcileResult;
-    cleanup: readonly ExecutionCleanup[];
-    stops: readonly ExecutionStop[];
-}>;
-type Residue = Readonly<{
+/** Physical residue and custodial residue a leading admission or reconciliation step reports. */
+export type ProgressResidue = Readonly<{
     physical?: ReconcileResult;
     seatClose?: readonly PrivateStateSeatCloseLag[];
 }>;
-/** Invocation-local receipts and ephemeral observations; no scheduling or authority reads. */
-export declare class ExecutionProgress {
-    private readonly observer?;
-    constructor(observer?: ExecutionObserver | undefined);
-    observe(event: ExecutionEvent): void;
-    private readonly entries;
-    private readonly admittedFacts;
-    private readonly admittedHeads;
-    private readonly admittedCheckpoints;
-    private readonly affectedContracts;
-    private readonly effects;
-    private readonly lags;
-    private readonly cleanupIssues;
-    private readonly executionStops;
-    private readonly reportedResidue;
-    /** A confirmed publication is retained even if folding or later physical work throws. */
+export type VerificationResidue = Readonly<{
+    cleanup?: VerificationCleanupFailure;
+    leak?: WorktreeLeak;
+}>;
+/**
+ * The narrow lower sink an invocation offers to protocol operations. Operation nodes report
+ * observations here and never assemble a public result.
+ */
+export interface ProtocolProgress {
+    observe(event: ExecutionObservation): void;
     recordPublication(contractId: ContractId, head: ContractHead, facts: readonly JournalEntry[]): void;
     recordAdmission(step: AcceptedProtocolStep): void;
-    hasFact(fact: JournalEntry): boolean;
-    head(contractId: ContractId): ContractHead | undefined;
-    recordResidue(contractId: ContractId, residue: Residue): void;
-    recordPhysical(contractId: ContractId, physical: ReconcileResult): void;
-    recordVerification(contractId: ContractId, snapshot: SnapshotId | undefined, result: Readonly<{
-        cleanup?: VerificationCleanupFailure;
-        leak?: WorktreeLeak;
-    }>): void;
+    recordResidue(contractId: ContractId, residue: ProgressResidue): void;
+    recordPhysical(contractId: ContractId, report: ReconcileResult): void;
+    /** Physical follow owned by this invocation's target movement, distinct from retained topology. */
+    recordPlacementPhysical(contractId: ContractId, report: ReconcileResult): void;
+    recordVerification(contractId: ContractId, snapshot: SnapshotId | undefined, result: VerificationResidue): void;
     recordStop(stop: ExecutionStop): void;
+    recordAudit(contractId: ContractId, report: Partial<import("./audit.js").AuditReport>): void;
+    /** Current candidate conclusions, retained before the next await can fail. */
+    recordCandidate(contractId: ContractId, evidence: CompletionEvidence): void;
+    /** The candidate's completion base, retained before an optional scope read can fail. */
+    recordCompletion(contractId: ContractId, completion: CandidateCompletion): void;
     checkpoint(contractId: ContractId): ContractCheckpoint | undefined;
-    snapshot(): ExecutionSnapshot;
-    /** One final assembly; a dependent's checkpoint can never replace the addressed head. */
-    accepted<Value>(contractId: ContractId, value: Value): Extract<IntentOutcome<Value>, {
-        kind: "accepted";
-    }>;
+    hasFact(fact: JournalEntry): boolean;
+    head(contractId: ContractId): ContractHead | undefined;
 }
-export {};