@astrosheep/keiyaku 4.5.29 → 4.6.2

package/build/src/library/input.js

@@ -1,5 +1,8 @@
+import { decodeArcDocument } from "../body/arc.js";
+import { decodeContractDocument } from "../body/decode.js";
+import { validated } from "./outcome.js";
 import { verificationDefinition } from "../body/decode.js";
-import { actorId, gate, gateWord, } from "../core/facts/types.js";
+import { actorId } from "../core/facts/types.js";
 import { parseTaskId } from "../task/identity.js";
 import { prepareVerificationDeclaration } from "../verification/declaration.js";
 export function actorOption(actor) {
@@ -84,21 +87,6 @@ export function normalizedList(values, label, brand) {
         }
     });
 }
-export function normalizedGates(values) {
-    if (values === undefined)
-        return [];
-    if (!Array.isArray(values))
-        throw new TypeError("gates must be an array");
-    const normalized = values.map((value, index) => {
-        if (!gateWord(value)) {
-            throw new TypeError(`gates[${index}] must match ^[a-z][a-z0-9-]{0,63}$`);
-        }
-        return gate(value);
-    });
-    if (new Set(normalized).size !== normalized.length)
-        throw new TypeError("gates must not contain duplicates");
-    return normalized;
-}
 export function contractTerms(document, gates, after) {
     return {
         document: document.document,
@@ -119,3 +107,10 @@ export function documentDerivation(document, gates, contractId) {
         }),
     };
 }
+/** Early CLI acquisition uses the same Library caller boundary, never document-owner capabilities. */
+export function validateContractMarkdown(markdown) {
+    validated(() => decodeContractDocument(requireMarkdown(markdown), { requireTimeout: true }));
+}
+export function validateArcMarkdown(markdown) {
+    validated(() => decodeArcDocument(requireMarkdown(markdown)));
+}

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

@@ -0,0 +1,87 @@
+import type { ContractHead, ContractId, JournalEntry } from "../core/facts/types.js";
+import type { ReconcileResult } from "../git/reconcile.js";
+import type { AuditReport } from "../protocol/audit.js";
+import type { CandidateCompletion, CompletionEvidence } from "../protocol/completion.js";
+import { type ExecutionObservation, type ExecutionObserver } from "../protocol/execution-observation.js";
+import type { AcceptedProtocolStep } from "../protocol/outcome.js";
+import type { ContractCheckpoint, ExecutionStop, ProgressResidue, ProtocolProgress, VerificationResidue } from "../protocol/progress.js";
+import type { SettlementReport } from "../settlement/settle.js";
+import type { WorldRoot } from "../world.js";
+import type { ContinuationReport } from "./continuation.js";
+import type { InvocationEffect, ReconciliationEffect, ReconciliationLag, ResetCounts } from "./outcome.js";
+export type InvocationSnapshot = Readonly<{
+    facts: readonly JournalEntry[];
+    checkpoints: ReadonlyMap<ContractId, ContractCheckpoint>;
+    heads: ReadonlyMap<ContractId, ContractHead>;
+    affected: readonly ContractId[];
+    effects: readonly InvocationEffect[];
+    conclusions: ReadonlyMap<ContractId, Readonly<Record<string, unknown>>>;
+    reset?: Readonly<{
+        world: WorldRoot;
+        removed: ResetCounts;
+    }>;
+}>;
+type ReconciliationRecord = Readonly<{
+    effects?: readonly ReconciliationEffect[];
+    lag?: readonly ReconciliationLag[];
+    settlement?: SettlementReport;
+    retiredWorktree?: string;
+    retainedWorktree?: string;
+}>;
+/**
+ * The one invocation accumulator. It exists before any admission-capable await, satisfies the lower
+ * Protocol progress sink, and holds every confirmed publication, candidate conclusion and physical
+ * observation until the single final projection.
+ */
+export declare class InvocationAccumulator implements ProtocolProgress {
+    private readonly observer?;
+    private readonly entries;
+    private readonly admittedFacts;
+    private readonly admittedHeads;
+    private readonly admittedCheckpoints;
+    private readonly affectedContracts;
+    private readonly records;
+    private readonly candidateConclusions;
+    private readonly reportedResidue;
+    private resetState?;
+    constructor(observer?: ExecutionObserver | undefined);
+    beginReset(world: WorldRoot): void;
+    recordResetRemoved(counts: Partial<ResetCounts>): void;
+    observe(event: ExecutionObservation): void;
+    /** A confirmed publication is retained even if folding or later physical work throws. */
+    recordPublication(contract: ContractId, head: ContractHead, facts: readonly JournalEntry[]): void;
+    recordAdmission(step: AcceptedProtocolStep): void;
+    hasFact(fact: JournalEntry): boolean;
+    head(contract: ContractId): ContractHead | undefined;
+    checkpoint(contract: ContractId): ContractCheckpoint | undefined;
+    recordResidue(contract: ContractId, residue: ProgressResidue): void;
+    recordVerification(contract: ContractId, snapshot: Parameters<ProtocolProgress["recordVerification"]>[1], result: VerificationResidue): void;
+    /** Replace the current candidate's conclusions; accumulated resources are never erased. */
+    recordCandidate(contract: ContractId, evidence: CompletionEvidence): void;
+    /** The candidate's completion base, known before an optional observation can fail. */
+    recordCompletion(contract: ContractId, completion: CandidateCompletion): void;
+    recordAudit(contract: ContractId, report: Partial<AuditReport>): void;
+    /** Physical residue a continuation's dependent reconciliation observed. */
+    recordPhysical(contract: ContractId, physical: ReconcileResult): void;
+    recordPlacementPhysical(contract: ContractId, physical: ReconcileResult): void;
+    /** Incremental continuation progress for the primary Contract. */
+    recordContinuation(contract: ContractId, report: ContinuationReport): void;
+    recordStop(stop: ExecutionStop): void;
+    /** Physical reconciliation observations: effects, lags, settlement, and worktree topology. */
+    recordReconciliation(contract: ContractId, record: ReconcileResult | ReconciliationRecord): void;
+    recordSettlement(contract: ContractId, report: SettlementReport): void;
+    recordChannelRetirement(contract: ContractId, error: unknown): void;
+    /** World reset observations share the carrier without pretending a Contract admission happened. */
+    recordReset(effect: Extract<InvocationEffect, {
+        kind: "reset-owner-stopped" | "reset-residue";
+    }>): void;
+    /** Replace the current candidate conclusions; accumulated resources are never erased. */
+    recordConclusions(contract: ContractId, patch: Readonly<Record<string, unknown>>): void;
+    extendConclusions(contract: ContractId, patch: Readonly<Record<string, unknown>>): void;
+    conclusions(contract: ContractId): Readonly<Record<string, unknown>> | undefined;
+    snapshot(): InvocationSnapshot;
+    private recordSeatClose;
+    private recordLag;
+}
+export declare function physicalOf(snapshot: InvocationSnapshot): ReconcileResult;
+export {};

package/build/src/library/invocation.js

@@ -0,0 +1,290 @@
+/** @architectureCompositionRoot */
+import { encodeEntry } from "../core/facts/codec.js";
+import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { observeExecution, } from "../protocol/execution-observation.js";
+import { reconcileLagScope } from "./reconcile.js";
+const CANDIDATE_CONCLUSION_KEYS = [
+    "completion",
+    "verification",
+    "verificationReuse",
+    "verificationSubject",
+    "verificationSummary",
+    "placement",
+];
+function entryKey(fact) {
+    return `${fact.contract}\u0000${fact.entry}`;
+}
+/** The owner codec's canonical bytes: identity is (contract, entry), the payload is retained whole. */
+function entryBytes(fact) {
+    return encodeEntry(fact);
+}
+/**
+ * The one invocation accumulator. It exists before any admission-capable await, satisfies the lower
+ * Protocol progress sink, and holds every confirmed publication, candidate conclusion and physical
+ * observation until the single final projection.
+ */
+export class InvocationAccumulator {
+    observer;
+    entries = new Map();
+    admittedFacts = [];
+    admittedHeads = new Map();
+    admittedCheckpoints = new Map();
+    affectedContracts = new Set();
+    records = [];
+    candidateConclusions = new Map();
+    reportedResidue = new WeakSet();
+    resetState;
+    constructor(observer) {
+        this.observer = observer;
+    }
+    beginReset(world) {
+        this.resetState = { world, removed: { refs: 0, worktrees: 0, tasks: 0 } };
+    }
+    recordResetRemoved(counts) {
+        if (this.resetState === undefined)
+            throw new Error("reset progress requires its World");
+        for (const key of ["refs", "worktrees", "tasks"])
+            this.resetState.removed[key] += counts[key] ?? 0;
+    }
+    observe(event) {
+        observeExecution(this.observer, event);
+    }
+    /** A confirmed publication is retained even if folding or later physical work throws. */
+    recordPublication(contract, head, facts) {
+        const incoming = new Map();
+        for (const fact of facts) {
+            const key = entryKey(fact);
+            const bytes = entryBytes(fact);
+            const previous = incoming.get(key)?.bytes ?? this.entries.get(key);
+            if (previous !== undefined && previous !== bytes)
+                throw new AuthorityCorruptionError("conflicting invocation receipt");
+            incoming.set(key, { fact, bytes });
+        }
+        let fresh = false;
+        for (const [key, { fact, bytes }] of incoming) {
+            if (this.entries.has(key))
+                continue;
+            this.entries.set(key, bytes);
+            this.admittedFacts.push(fact);
+            if (fact.kind === "deliver")
+                this.extendConclusions(fact.contract, {
+                    ...fact.data,
+                    leading: { kind: "admitted-now", fact: fact.entry },
+                });
+            this.observe({ kind: "admitted", contractId: contract, fact });
+            this.affectedContracts.add(fact.contract);
+            fresh = true;
+        }
+        if (fresh || !this.admittedHeads.has(contract))
+            this.admittedHeads.set(contract, head);
+    }
+    recordAdmission(step) {
+        if (step.state.head === null)
+            throw new Error("admission requires a journal head");
+        this.recordPublication(step.state.id, step.state.head, step.facts);
+        if (this.admittedHeads.get(step.state.id) === step.state.head) {
+            this.admittedCheckpoints.set(step.state.id, { state: step.state, journal: step.journal });
+        }
+        this.recordResidue(step.state.id, step);
+    }
+    hasFact(fact) {
+        return this.entries.get(entryKey(fact)) === entryBytes(fact);
+    }
+    head(contract) {
+        return this.admittedHeads.get(contract);
+    }
+    checkpoint(contract) {
+        return this.admittedCheckpoints.get(contract);
+    }
+    recordResidue(contract, residue) {
+        if (residue.physical !== undefined)
+            this.recordReconciliation(contract, residue.physical);
+        for (const failure of residue.seatClose ?? [])
+            this.recordSeatClose(contract, failure);
+    }
+    recordVerification(contract, snapshot, result) {
+        if (result.cleanup !== undefined)
+            this.records.push({
+                kind: "cleanup",
+                contract,
+                issue: {
+                    kind: "verification-cleanup",
+                    contractId: contract,
+                    ...(snapshot === undefined ? {} : { snapshot }),
+                    failure: result.cleanup,
+                },
+            });
+        if (result.leak !== undefined)
+            this.records.push({
+                kind: "cleanup",
+                contract,
+                issue: {
+                    kind: "worktree-leak",
+                    contractId: contract,
+                    ...(snapshot === undefined ? {} : { snapshot }),
+                    leak: result.leak,
+                },
+            });
+    }
+    /** Replace the current candidate's conclusions; accumulated resources are never erased. */
+    recordCandidate(contract, evidence) {
+        const next = { ...(this.candidateConclusions.get(contract) ?? {}) };
+        for (const key of CANDIDATE_CONCLUSION_KEYS)
+            delete next[key];
+        for (const [key, value] of Object.entries(evidence))
+            if (value !== undefined)
+                next[key] = value;
+        this.candidateConclusions.set(contract, next);
+    }
+    /** The candidate's completion base, known before an optional observation can fail. */
+    recordCompletion(contract, completion) {
+        this.extendConclusions(contract, { completion });
+    }
+    recordAudit(contract, report) {
+        this.extendConclusions(contract, report);
+    }
+    /** Physical residue a continuation's dependent reconciliation observed. */
+    recordPhysical(contract, physical) {
+        this.recordReconciliation(contract, physical);
+    }
+    recordPlacementPhysical(contract, physical) {
+        for (const lag of physical.lag) {
+            if (lag.kind !== "target-checkout-retained" || this.reportedResidue.has(lag))
+                continue;
+            this.reportedResidue.add(lag);
+            this.records.push({
+                kind: "checkout-retained",
+                contract,
+                path: lag.path,
+                target: lag.target,
+                diagnostic: lag.diagnostic,
+            });
+            this.affectedContracts.add(contract);
+        }
+        this.recordReconciliation(contract, physical);
+    }
+    /** Incremental continuation progress for the primary Contract. */
+    recordContinuation(contract, report) {
+        this.extendConclusions(contract, { continuation: report });
+    }
+    recordStop(stop) {
+        if (this.records.some((record) => record.kind === "execution-stopped" &&
+            record.contract === stop.contractId &&
+            record.stage === stop.stage &&
+            record.reason === stop.reason &&
+            record.diagnostic === stop.diagnostic))
+            return;
+        this.records.push({
+            kind: "execution-stopped",
+            contract: stop.contractId,
+            stage: stop.stage,
+            reason: stop.reason,
+            diagnostic: stop.diagnostic,
+        });
+    }
+    /** Physical reconciliation observations: effects, lags, settlement, and worktree topology. */
+    recordReconciliation(contract, record) {
+        for (const effect of "effects" in record ? (record.effects ?? []) : []) {
+            if (this.reportedResidue.has(effect))
+                continue;
+            this.reportedResidue.add(effect);
+            this.records.push({ kind: "reconciliation-effect", contract, effect });
+            this.affectedContracts.add(contract);
+        }
+        for (const lag of "lag" in record ? (record.lag ?? []) : []) {
+            if (this.reportedResidue.has(lag))
+                continue;
+            this.reportedResidue.add(lag);
+            this.recordLag(contract, lag);
+        }
+        const settlement = "settlement" in record ? record.settlement : undefined;
+        if (settlement !== undefined)
+            this.recordSettlement(contract, settlement);
+        const retired = "retiredWorktree" in record ? record.retiredWorktree : undefined;
+        if (retired !== undefined &&
+            !this.records.some((entry) => entry.kind === "worktree-retired" && entry.contract === contract && entry.name === retired))
+            this.records.push({ kind: "worktree-retired", contract, name: retired });
+        const retained = "retainedWorktree" in record ? record.retainedWorktree : undefined;
+        if (retained !== undefined &&
+            !this.records.some((entry) => entry.kind === "worktree-retained" && entry.contract === contract && entry.path === retained))
+            this.records.push({ kind: "worktree-retained", contract, path: retained });
+    }
+    recordSettlement(contract, report) {
+        for (const action of report.actions)
+            this.records.push({ kind: "settlement-action", contract, action });
+        for (const lag of report.lags)
+            this.records.push({ kind: "settlement-lag", contract, lag });
+        for (const failure of report.seatClose ?? [])
+            this.recordSeatClose(contract, failure);
+    }
+    recordChannelRetirement(contract, error) {
+        this.records.push({
+            kind: "cleanup",
+            contract,
+            issue: {
+                kind: "decode-channel-retirement",
+                contractId: contract,
+                diagnostic: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+    /** World reset observations share the carrier without pretending a Contract admission happened. */
+    recordReset(effect) {
+        this.records.push(effect);
+    }
+    /** Replace the current candidate conclusions; accumulated resources are never erased. */
+    recordConclusions(contract, patch) {
+        this.candidateConclusions.set(contract, patch);
+    }
+    extendConclusions(contract, patch) {
+        this.candidateConclusions.set(contract, { ...(this.candidateConclusions.get(contract) ?? {}), ...patch });
+    }
+    conclusions(contract) {
+        return this.candidateConclusions.get(contract);
+    }
+    snapshot() {
+        return {
+            facts: Object.freeze([...this.admittedFacts]),
+            checkpoints: new Map(this.admittedCheckpoints),
+            heads: new Map(this.admittedHeads),
+            affected: Object.freeze([...this.affectedContracts]),
+            effects: Object.freeze([...this.records]),
+            conclusions: new Map(this.candidateConclusions),
+            ...(this.resetState === undefined
+                ? {}
+                : {
+                    reset: Object.freeze({
+                        world: this.resetState.world,
+                        removed: Object.freeze({ ...this.resetState.removed }),
+                    }),
+                }),
+        };
+    }
+    recordSeatClose(contract, failure) {
+        if (this.reportedResidue.has(failure))
+            return;
+        this.reportedResidue.add(failure);
+        this.records.push({
+            kind: "cleanup",
+            contract,
+            issue: { kind: "private-state-seat-close", contractId: contract, failure },
+        });
+    }
+    recordLag(contract, lag) {
+        const affects = reconcileLagScope(lag);
+        this.records.push({ kind: "reconciliation-lag", contract, affects, lag });
+        if (affects !== "none")
+            this.affectedContracts.add(contract);
+    }
+}
+export function physicalOf(snapshot) {
+    const effects = [];
+    const lag = [];
+    for (const record of snapshot.effects) {
+        if (record.kind === "reconciliation-effect" && record.effect.kind !== "contract-file")
+            effects.push(record.effect);
+        else if (record.kind === "reconciliation-lag" && record.lag.kind !== "contract-file-failed")
+            lag.push(record.lag);
+    }
+    return { effects, lag };
+}

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

@@ -1,22 +1,45 @@
-export { Keiyaku } from "./contract-handle.js";
-export { Delivery, KeiyakuRefused, KeiyakuRetry, projectMutationFinality } from "./contract.js";
-export type { KeiyakuRefusal, KeiyakuRetryReason } from "./contract.js";
-export { AuthorityCorruptionError } from "../core/facts/errors.js";
-export { NoGitWorldError, Repo } from "./repo.js";
-export { gatesFrom, requireBranchesToBeUpToDateFrom, SettingsError, worktreeHooksFrom } from "./configuration.js";
-export { bodyRequestExecution } from "../akuma/requests.js";
-export { nukeKeiyaku as nuke } from "./nuke.js";
-export { executionReceipt } from "./execution-result.js";
-export type { LibraryExecution } from "../akuma/requests.js";
-export type { LocalContractComposition, KeiyakuSelectInput } from "./contract-types.js";
-export type { KeiyakuLibrary, KeiyakuWithInput } from "./composition.js";
-export type { AbandonInput, ActorId, AmendInput, AmendResult, ArcInput, AttestationVerdict, AuditInput, AuditReport, DeliveryPreparationRefusal, BindInput, BindResult, ContractAfterEdge, ContractBoard, ContractDependent, ContractDisposition, ContractGateCurrent, ContractGateReport, ContractHistory, ContractHistoryEvent, ContractList, ContractListInput, ContractObservation, ContractObservationInput, ContractPhase, ContractRow, ContractWorkspaceObservation, ContinuationReport, DeliverInput, Fact, FactKind, IntegrationConflictMaterialized, Lag, MutationResult, MutationFinality, MutationFinalityInput, MutationFinalitySurface, MutationPendingSurface, PlacementStop, ReconcileReport, Review, ReviewInput, TaskId, TopologyEffect, VerificationReuse, VerificationStop, } from "./contract.js";
-export type { ContractId, ContractState, ChangeId, SnapshotId } from "../core/facts/types.js";
-export type { Gate, GatesFromInput, HookCommand, RequireBranchesToBeUpToDateFromInput, WorktreeHooks, } from "./configuration.js";
-export type { RegionOverlap } from "./region.js";
-export type { ReconcileInput, RepoAtInput, RepoReconcileReport } from "./repo.js";
-export type { SettlementAction, SettlementLag, SettlementReport } from "../settlement/settle.js";
-export type { NukeInput, NukeResult } from "./nuke.js";
-export type { NukeConfirmationRefusal, NukeConfirmationRequiredRefusal } from "./refusal.js";
-export type { ContractExecution, ExecutionEvent } from "./execution.js";
-export type { ExecutionCleanup, ExecutionStop, ExecutionReceipt, MutationOperation } from "./execution-result.js";
+/** @architectureCompositionRoot */
+import { type ExecutionContext } from "../akuma/requests.js";
+import type { ContractId, ContractState } from "../core/facts/types.js";
+import { type RepositoryScope } from "../protocol/operations.js";
+import { type KeiyakuLibrary } from "./contract-composition.js";
+import type { AbandonOutcome, AmendOutcome, ArcOutcome, AuditInput, AuditOutcome, DeliverOutcome, MutationObservation, ReviewOutcome } from "./contract-outcomes.js";
+import type { LocalContractCompositionCapture } from "./contract-settings.js";
+import type { AbandonInput, AmendInput, ArcInput, ContractHistory, DeliverInput, LocalContractComposition, ReviewInput } from "./contract-types.js";
+import { type Delivery } from "./delivery.js";
+declare const KEIYAKU_HANDLE: unique symbol;
+type HandleSeat = Readonly<{
+    id: ContractId;
+    scope: RepositoryScope;
+}>;
+export declare class Keiyaku {
+    static with(input?: LocalContractComposition): KeiyakuLibrary;
+    private readonly id;
+    private readonly scope;
+    private readonly operations;
+    constructor(token: typeof KEIYAKU_HANDLE, id: ContractId, scope: RepositoryScope, execution: ExecutionContext | undefined, composition: LocalContractCompositionCapture);
+    /** The handle's one durable identity; everything else is process-local custody. */
+    toJSON(): Readonly<{
+        contract: ContractId;
+    }>;
+    state(): Promise<ContractState | null>;
+    history(): Promise<ContractHistory | null>;
+    guidance(): Promise<string | null>;
+    delivery(): Promise<Delivery | null>;
+    amend(input: AmendInput): Promise<AmendOutcome>;
+    deliver(input?: DeliverInput, options?: MutationObservation): Promise<DeliverOutcome>;
+    review(input: ReviewInput, options?: MutationObservation): Promise<ReviewOutcome>;
+    abandon(input?: AbandonInput): Promise<AbandonOutcome>;
+    arc(input: ArcInput): Promise<ArcOutcome>;
+    audit(input?: AuditInput, options?: MutationObservation): Promise<AuditOutcome>;
+    /**
+     * Reads answer with a value or `null` for legitimate absence. Corrupt authority stays exceptional
+     * and keeps its original native cause instead of being disguised as a raw native exception.
+     */
+    private read;
+}
+/** Internal constructor capability; callers select a Contract through Keiyaku.with. */
+export declare function createKeiyakuHandle(id: ContractId, scope: RepositoryScope, execution: ExecutionContext, composition: LocalContractCompositionCapture): Keiyaku;
+/** Internal package composition capability; not exported from the package root. */
+export declare function seatForKeiyaku(value: unknown): HandleSeat | null;
+export {};

package/build/src/library/keiyaku.js

@@ -1,8 +1,134 @@
-export { Keiyaku } from "./contract-handle.js";
-export { Delivery, KeiyakuRefused, KeiyakuRetry, projectMutationFinality } from "./contract.js";
-export { AuthorityCorruptionError } from "../core/facts/errors.js";
-export { NoGitWorldError, Repo } from "./repo.js";
-export { gatesFrom, requireBranchesToBeUpToDateFrom, SettingsError, worktreeHooksFrom } from "./configuration.js";
-export { bodyRequestExecution } from "../akuma/requests.js";
-export { nukeKeiyaku as nuke } from "./nuke.js";
-export { executionReceipt } from "./execution-result.js";
+/** @architectureCompositionRoot */
+import { localExecutionContext } from "../akuma/requests.js";
+import { renderContractGuidance } from "../contract-guidance.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 { contractObservationOperation, deliveryOperation, stateOperation, } from "../protocol/operations.js";
+import { readManagedWorktreeAppointment } from "../workspace-place.js";
+import { composeContractLibrary, readContractValue } from "./contract-composition.js";
+import { ContractExecution } from "./contract-execution.js";
+import { deliveryForContract } from "./delivery.js";
+const KEIYAKU_HANDLE = Symbol("Keiyaku handle");
+const KEIYAKU_SEATS = new WeakMap();
+export class Keiyaku {
+    static with(input) {
+        return composeContractLibrary(localExecutionContext(), createKeiyakuHandle, input);
+    }
+    id;
+    scope;
+    operations;
+    constructor(token, id, scope, execution = localExecutionContext(), composition) {
+        if (token !== KEIYAKU_HANDLE)
+            throw new TypeError("Keiyaku handles are created by Keiyaku.with");
+        this.id = id;
+        this.scope = scope;
+        this.operations = new ContractExecution({ id, scope, execution, composition });
+        // Process-local custody never serializes: identity-only JSON projection.
+        Object.defineProperties(this, {
+            id: { value: id, enumerable: false },
+            scope: { value: scope, enumerable: false },
+            execution: { value: execution, enumerable: false },
+            operations: { value: this.operations, enumerable: false },
+            composition: { value: composition, enumerable: false },
+        });
+        KEIYAKU_SEATS.set(this, { id, scope });
+        Object.freeze(this);
+    }
+    /** The handle's one durable identity; everything else is process-local custody. */
+    toJSON() {
+        return { contract: this.id };
+    }
+    async state() {
+        return await this.read(() => withGitDecodeChannel(this.scope, (channel) => stateOperation({ scope: this.scope, channel, contractId: this.id })));
+    }
+    async history() {
+        return await this.read(() => 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)
+                return null;
+            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;
+            });
+            const workspace = await readManagedWorktreeAppointment(this.scope, this.id);
+            return {
+                id: this.id,
+                state: mintSnapshotId(commit),
+                ...(workspace.kind === "appointed"
+                    ? { workspace: { kind: "worktree", path: workspace.path } }
+                    : {}),
+                events,
+            };
+        })));
+    }
+    async guidance() {
+        return await this.read(() => withGitDecodeChannel(this.scope, async (channel) => {
+            const observed = await contractObservationOperation({ scope: this.scope, channel, contractId: this.id });
+            if (observed.kind === "missing")
+                return null;
+            const state = await stateOperation({ scope: this.scope, channel, contractId: this.id });
+            return state === null ? null : renderContractGuidance(state);
+        }));
+    }
+    async delivery() {
+        const delivery = await this.read(() => withGitDecodeChannel(this.scope, (channel) => deliveryOperation({ scope: this.scope, channel, contractId: this.id })));
+        return delivery === null ? null : deliveryForContract(this.scope, delivery);
+    }
+    async amend(input) {
+        return await this.operations.amend(input);
+    }
+    async deliver(input, options) {
+        return await this.operations.deliver(input, options);
+    }
+    async review(input, options) {
+        return await this.operations.review(input, options);
+    }
+    async abandon(input) {
+        return await this.operations.abandon(input);
+    }
+    async arc(input) {
+        return await this.operations.arc(input);
+    }
+    async audit(input, options) {
+        return await this.operations.audit(input, options);
+    }
+    /**
+     * Reads answer with a value or `null` for legitimate absence. Corrupt authority stays exceptional
+     * and keeps its original native cause instead of being disguised as a raw native exception.
+     */
+    async read(operation) {
+        return await readContractValue(operation);
+    }
+}
+/** Internal constructor capability; callers select a Contract through Keiyaku.with. */
+export function createKeiyakuHandle(id, scope, execution, composition) {
+    return new Keiyaku(KEIYAKU_HANDLE, id, scope, execution, composition);
+}
+/** 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;
+}

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

@@ -1,20 +1,11 @@
-import { type PrivateStateSeatCloseLag } from "../git/private-state-seat.js";
 import type { GitRepository } from "../git/process.js";
 import { type WorldRoot } from "../world.js";
+import { type ResetOutcome } from "./outcome.js";
 export type NukeInput = Readonly<{
     world: WorldRoot;
     confirm?: string;
 }>;
-export type NukeResult = Readonly<{
-    kind: "success";
-    world: WorldRoot;
-    seatClose?: readonly PrivateStateSeatCloseLag[];
-}> | Readonly<{
-    kind: "failed";
-    world: WorldRoot;
-    diagnostic: string;
-    seatClose?: readonly PrivateStateSeatCloseLag[];
-}>;
+export type NukeResult = ResetOutcome;
 type NukeGitOptions = Readonly<Pick<GitRepository, "onPrivateStateSeatContention" | "onPrivateStateSeatClose">>;
 export declare function nukeKeiyaku(input: NukeInput, gitOptions?: NukeGitOptions): Promise<NukeResult>;
 export {};