@astrosheep/keiyaku 4.0.0 → 4.0.1

package/build/src/core/facts/eligibility.d.ts

@@ -1,16 +1,7 @@
-import type { Offer } from "./offer.js";
 import { type ContractsObservation } from "./observation.js";
-import type { ContractId, EntryUlid } from "./types.js";
+import type { ContractId } from "./types.js";
 type EligibilityObservation = ContractsObservation;
-type EligibilityAttempt = Readonly<{
-    entryUlids: readonly EntryUlid[];
-}>;
-type PrerequisiteStatus = "unknown" | "pending" | "claimed";
-/** Resolve prerequisite existence and eligibility from one decision snapshot. */
-export declare function prerequisiteStatus(prerequisites: readonly ContractId[], observation: EligibilityObservation, offeredClaims?: ReadonlySet<ContractId>): PrerequisiteStatus;
 /** Decide whether resulting prerequisites reach the amended contract. */
 export declare function prerequisitesReach(contract: ContractId, prerequisites: readonly ContractId[], observation: EligibilityObservation): boolean;
 export declare function samePrerequisites(left: readonly ContractId[], right: readonly ContractId[]): boolean;
-/** Append bounds made eligible by a claimed offer from its full snapshot. */
-export declare function placeEligibleBounds(offer: Offer, observation: EligibilityObservation, attempt: EligibilityAttempt): Offer;
 export {};

package/build/src/core/facts/eligibility.js

@@ -1,16 +1,4 @@
 import { contractState } from "./observation.js";
-/** Resolve prerequisite existence and eligibility from one decision snapshot. */
-export function prerequisiteStatus(prerequisites, observation, offeredClaims) {
-    let pending = false;
-    for (const dependency of prerequisites) {
-        const state = contractState(observation, dependency);
-        if (state === null)
-            return "unknown";
-        if (state.terminal?.kind !== "claimed" && offeredClaims?.has(dependency) !== true)
-            pending = true;
-    }
-    return pending ? "pending" : "claimed";
-}
 /** Decide whether resulting prerequisites reach the amended contract. */
 export function prerequisitesReach(contract, prerequisites, observation) {
     const pending = [...prerequisites];
@@ -36,40 +24,3 @@ export function samePrerequisites(left, right) {
         return false;
     return left.every((id, index) => id === right[index]);
 }
-/** Append bounds made eligible by a claimed offer from its full snapshot. */
-export function placeEligibleBounds(offer, observation, attempt) {
-    const claimedEntry = offer.facts[0]?.entries[0];
-    if (offer.facts.length !== 1 || offer.facts[0]?.entries.length !== 1 || claimedEntry?.kind !== "claimed") {
-        throw new Error("eligible-bound placement requires exactly one claimed fact");
-    }
-    const claimed = new Set([claimedEntry.contract]);
-    const used = new Set([claimedEntry.entry]);
-    const available = attempt.entryUlids.filter((entry) => !used.has(entry));
-    let availableIndex = 0;
-    const additions = [];
-    for (const id of observation.keys()) {
-        const state = contractState(observation, id);
-        if (!state || state.bound || state.terminal)
-            continue;
-        if (prerequisiteStatus(state.terms.after, observation, claimed) !== "claimed")
-            continue;
-        const entry = available[availableIndex];
-        if (entry === undefined)
-            throw new Error("placement attempt lacks an entry ULID for an eligible contract");
-        availableIndex += 1;
-        additions.push({
-            contractId: id,
-            expectedHead: state.head,
-            entries: [{
-                    v: 1,
-                    kind: "bound",
-                    contract: id,
-                    entry,
-                    at: claimedEntry.at,
-                    ...(claimedEntry.actor === undefined ? {} : { actor: claimedEntry.actor }),
-                    data: {},
-                }],
-        });
-    }
-    return additions.length === 0 ? offer : { ...offer, facts: [...additions, ...offer.facts] };
-}

package/build/src/core/facts/observation.d.ts

@@ -1,8 +1,11 @@
 import type { ContractId, ContractState, DocumentKey } from "./types.js";
 /** The complete state projection consumed by one pure pact decision. */
 export type ContractsObservation = ReadonlyMap<ContractId, ContractState | null>;
+export type PrerequisiteStatus = "unknown" | "pending" | "claimed";
 /** Read one requested identity; a missing key violates the observation contract. */
 export declare function contractState(observation: ContractsObservation, contract: ContractId): ContractState | null;
+/** Project prerequisite existence and terminal satisfaction from one observation. */
+export declare function prerequisiteStatus(prerequisites: readonly ContractId[], observation: ContractsObservation): PrerequisiteStatus;
 export type ActiveContractRefusal = Readonly<{
     kind: "contract-missing" | "terminal";
     contractId: ContractId;

package/build/src/core/facts/observation.js

@@ -9,6 +9,18 @@ export function contractState(observation, contract) {
     }
     return state;
 }
+/** Project prerequisite existence and terminal satisfaction from one observation. */
+export function prerequisiteStatus(prerequisites, observation) {
+    let pending = false;
+    for (const dependency of prerequisites) {
+        const state = contractState(observation, dependency);
+        if (state === null)
+            return "unknown";
+        if (state.terminal?.kind !== "claimed")
+            pending = true;
+    }
+    return pending ? "pending" : "claimed";
+}
 /** The single lifecycle guard shared by every operation on an existing contract. */
 export function activeContract(observation, contract) {
     const state = contractState(observation, contract);

package/build/src/core/facts/types.d.ts

@@ -74,9 +74,16 @@ export type BindData = Readonly<{
 export type AmendData = ContractTerms;
 export type BoundData = Readonly<Record<string, never>>;
 export type DeliverData = Readonly<{
-    expectedPredecessor: SnapshotId;
-    candidate: SnapshotId;
-    deliveryPatchId: ChangeId;
+    tenderSnapshot: SnapshotId;
+    integration: Readonly<{
+        predecessor: SnapshotId;
+        snapshot: SnapshotId;
+        changeId: ChangeId;
+    }>;
+    method: "squash";
+    policy: Readonly<{
+        requireBranchesToBeUpToDate: boolean;
+    }>;
 }>;
 export type AttestationData = Readonly<{
     gate: Gate;

package/build/src/core/subject.js

@@ -69,8 +69,8 @@ function currentKeys(state) {
         encodeKey({ kind: "document", value: state.terms.document.key }),
         ...state.terms.segments.map((value) => encodeKey({ kind: "segment", value })),
         ...(state.delivery === null ? [] : [
-            encodeKey({ kind: "snapshot", value: state.delivery.data.candidate }),
-            encodeKey({ kind: "change", value: state.delivery.data.deliveryPatchId }),
+            encodeKey({ kind: "snapshot", value: state.delivery.data.integration.snapshot }),
+            encodeKey({ kind: "change", value: state.delivery.data.integration.changeId }),
         ]),
     ]);
 }

package/build/src/core/verbs/amend.js

@@ -1,5 +1,13 @@
-import { prerequisiteStatus, prerequisitesReach, samePrerequisites } from "../facts/eligibility.js";
-import { activeContract } from "../facts/observation.js";
+import { prerequisitesReach, samePrerequisites } from "../facts/eligibility.js";
+import { activeContract, prerequisiteStatus } from "../facts/observation.js";
+function prerequisitesConsumed(current, next, observation) {
+    if (samePrerequisites(current.terms.after, next.after))
+        return false;
+    const status = prerequisiteStatus(current.terms.after, observation);
+    if (status === "unknown")
+        throw new Error("current prerequisite is absent from the decision observation");
+    return current.bound !== null || status === "claimed";
+}
 export function decideAmend({ input, attempt, observation }) {
     const id = input.contractId;
     const current = activeContract(observation, id);
@@ -21,7 +29,7 @@ export function decideAmend({ input, attempt, observation }) {
     if (input.preparation.kind === "refused")
         return { kind: "refused", refusal: input.preparation.refusal };
     const { data } = input.preparation;
-    if (current.bound !== null && !samePrerequisites(current.terms.after, data.after)) {
+    if (prerequisitesConsumed(current, data, observation)) {
         return { kind: "refused", refusal: { kind: "prerequisites-already-consumed", contractId: id } };
     }
     const prerequisites = prerequisiteStatus(data.after, observation);
@@ -40,17 +48,5 @@ export function decideAmend({ input, attempt, observation }) {
         ...(input.actor === undefined ? {} : { actor: input.actor }),
         data,
     };
-    const entries = [entry];
-    if (current.bound === null && prerequisites === "claimed") {
-        entries.push({
-            v: 1,
-            kind: "bound",
-            contract: id,
-            entry: attempt.entryUlids[1],
-            at: input.at,
-            ...(input.actor === undefined ? {} : { actor: input.actor }),
-            data: {},
-        });
-    }
-    return { kind: "offer", offer: { facts: [{ contractId: id, expectedHead: current.head, entries }] } };
+    return { kind: "offer", offer: { facts: [{ contractId: id, expectedHead: current.head, entries: [entry] }] } };
 }

package/build/src/core/verbs/bind.js

@@ -1,5 +1,4 @@
-import { prerequisiteStatus } from "../facts/eligibility.js";
-import { contractState } from "../facts/observation.js";
+import { contractState, prerequisiteStatus } from "../facts/observation.js";
 export function decideBind({ input, attempt, observation }) {
     const id = input.contractId;
     const current = contractState(observation, id);
@@ -23,18 +22,5 @@ export function decideBind({ input, attempt, observation }) {
         ...(input.actor === undefined ? {} : { actor: input.actor }),
         data,
     };
-    const entries = [bind];
-    if (prerequisites === "claimed") {
-        const bound = {
-            v: 1,
-            kind: "bound",
-            contract: id,
-            entry: attempt.entryUlids[1],
-            at: input.at,
-            ...(input.actor === undefined ? {} : { actor: input.actor }),
-            data: {},
-        };
-        entries.push(bound);
-    }
-    return { kind: "offer", offer: { facts: [{ contractId: id, expectedHead: null, entries }] } };
+    return { kind: "offer", offer: { facts: [{ contractId: id, expectedHead: null, entries: [bind] }] } };
 }

package/build/src/core/verbs/deliver.js

@@ -1,10 +1,14 @@
-import { activeContract, documentIsCurrent } from "../facts/observation.js";
+import { activeContract, documentIsCurrent, prerequisiteStatus } from "../facts/observation.js";
 export function decideDeliver({ input, attempt, observation, }) {
     const state = activeContract(observation, input.contractId);
     if ("kind" in state)
         return { kind: "refused", refusal: state };
-    if (state.bound === null)
+    const prerequisites = state.bound === null
+        ? prerequisiteStatus(state.terms.after, observation)
+        : "claimed";
+    if (prerequisites !== "claimed") {
         return { kind: "refused", refusal: { kind: "not-bound", contractId: input.contractId } };
+    }
     if (input.preparation.kind === "unavailable") {
         throw new Error("existing contract requires a stamped delivery preparation");
     }
@@ -13,14 +17,26 @@ export function decideDeliver({ input, attempt, observation, }) {
     }
     if (input.preparation.kind === "refused")
         return { kind: "refused", refusal: input.preparation.refusal };
+    const entries = [];
+    if (state.bound === null)
+        entries.push({
+            v: 1,
+            kind: "bound",
+            contract: input.contractId,
+            entry: attempt.entryUlids[0],
+            at: input.at,
+            ...(input.actor === undefined ? {} : { actor: input.actor }),
+            data: {},
+        });
     const deliver = {
         v: 1,
         kind: "deliver",
         contract: input.contractId,
-        entry: attempt.entryUlids[0],
+        entry: attempt.entryUlids[state.bound === null ? 1 : 0],
         at: input.at,
         ...(input.actor === undefined ? {} : { actor: input.actor }),
         data: input.preparation.data,
     };
-    return { kind: "offer", offer: { facts: [{ contractId: input.contractId, expectedHead: state.head, entries: [deliver] }] } };
+    entries.push(deliver);
+    return { kind: "offer", offer: { facts: [{ contractId: input.contractId, expectedHead: state.head, entries }] } };
 }

package/build/src/core/verbs/placement.js

@@ -1,5 +1,4 @@
 import { gatesSatisfied } from "../facts/gate.js";
-import { placeEligibleBounds } from "../facts/eligibility.js";
 import { activeContract } from "../facts/observation.js";
 export function decidePlacement({ input, attempt, observation }) {
     const id = input.contractId;
@@ -22,21 +21,17 @@ export function decidePlacement({ input, attempt, observation }) {
         ...(input.actor === undefined ? {} : { actor: input.actor }),
         data: { delivery: delivery.entry },
     };
-    const offer = {
+    return {
         kind: "offer",
         offer: {
             facts: [{ contractId: id, expectedHead: current.head, entries: [claimed] }],
             ...(current.coordinates.target === undefined ? {} : {
                 target: {
                     target: current.coordinates.target,
-                    expectedOid: delivery.data.expectedPredecessor,
-                    newOid: delivery.data.candidate,
+                    expectedOid: delivery.data.integration.predecessor,
+                    newOid: delivery.data.integration.snapshot,
                 },
             }),
         },
     };
-    return {
-        ...offer,
-        offer: placeEligibleBounds(offer.offer, observation, attempt),
-    };
 }

package/build/src/dispatch/index.d.ts

@@ -1,6 +1,7 @@
 import { type ContractId } from "../core/facts/types.js";
 import { type AkuId } from "../akuma/identity.js";
 import { type GitRepository } from "../git/repository.js";
+import { type GitReadObservation } from "../git/read-observation.js";
 export type Dispatch = Readonly<{
     akuId: AkuId;
     contractId: ContractId;
@@ -23,7 +24,8 @@ export type DispatchPublication = Readonly<{
     failure: DispatchFailure;
 }>;
 export declare function readDispatch(repository: GitRepository, value: AkuId): Dispatch | null;
-export declare function readDispatches(repository: GitRepository): readonly Dispatch[];
+export declare function readDispatchesAt(observation: GitReadObservation): Promise<readonly Dispatch[]>;
+export declare function readDispatches(repository: GitRepository): Promise<readonly Dispatch[]>;
 export declare function publishDispatch(input: Readonly<{
     repository: GitRepository;
     akuId: AkuId;

package/build/src/dispatch/index.js

@@ -2,7 +2,8 @@ import { createHash } from "node:crypto";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { contractId } from "../core/facts/types.js";
 import { parseAkuId } from "../akuma/identity.js";
-import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, readBlob, readGit, readGitPaths, updateGitTree, updateRefsAtomically, writeBlob, writeCommit, } from "../git/repository.js";
+import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, readBlob, readGitPaths, updateGitTree, updateRefsAtomically, writeBlob, writeCommit, } from "../git/repository.js";
+import { withGitDecodeChannel, withGitReadObservation } from "../git/read-observation.js";
 const DISPATCH_ROOT = "dispatch";
 const DISPATCH_PREFIX = `${DISPATCH_ROOT}/`;
 const DISPATCH_SUFFIX = ".json";
@@ -77,11 +78,13 @@ export function readDispatch(repository, value) {
     const path = pathFor(akuId);
     return dispatchFromSnapshot(repository, readGitPaths(repository, [path]), akuId);
 }
-export function readDispatches(repository) {
-    const snapshot = readGit(repository);
+export async function readDispatchesAt(observation) {
+    const entries = [...observation.snapshot.paths]
+        .filter(([path, entry]) => path.startsWith(DISPATCH_PREFIX) && entry.type === "blob");
+    const blobs = await observation.readBlobs(entries.map(([, entry]) => entry.oid));
     const dispatches = [];
     const seen = new Set();
-    for (const [path, entry] of snapshot.paths) {
+    for (const [path, entry] of observation.snapshot.paths) {
         if (path === DISPATCH_ROOT)
             corruption(`Dispatch authority root is not a tree: ${path}`);
         if (!path.startsWith(DISPATCH_PREFIX))
@@ -90,7 +93,10 @@ export function readDispatches(repository) {
             corruption(`unexpected Dispatch authority path: ${path}`);
         if (entry.type !== "blob")
             corruption(`Dispatch path is not a blob: ${path}`);
-        const dispatch = decode(path, readBlob(repository, entry.oid));
+        const result = blobs.get(entry.oid);
+        if (result?.kind !== "present")
+            corruption(`missing Dispatch Git object: ${path}`);
+        const dispatch = decode(path, result.bytes);
         if (seen.has(dispatch.akuId))
             corruption(`duplicate Dispatch identity: ${dispatch.akuId}`);
         seen.add(dispatch.akuId);
@@ -98,6 +104,9 @@ export function readDispatches(repository) {
     }
     return dispatches.sort((left, right) => Buffer.compare(Buffer.from(left.akuId), Buffer.from(right.akuId)));
 }
+export async function readDispatches(repository) {
+    return withGitDecodeChannel(repository, (channel) => withGitReadObservation(repository, channel, readDispatchesAt));
+}
 function observedPublication(repository, akuId, owner) {
     const current = readDispatch(repository, akuId);
     if (current === null)

package/build/src/duration.d.ts

@@ -0,0 +1,10 @@
+export type DurationParseResult = Readonly<{
+    kind: "parsed";
+    milliseconds: number;
+}> | Readonly<{
+    kind: "invalid";
+}> | Readonly<{
+    kind: "overflow";
+}>;
+export declare function parseDuration(value: string): DurationParseResult;
+export declare function formatDuration(milliseconds: number): string;

package/build/src/duration.js

@@ -0,0 +1,22 @@
+const MULTIPLIERS = Object.freeze({
+    ms: 1n,
+    s: 1000n,
+    m: 60000n,
+    h: 3600000n,
+});
+export function parseDuration(value) {
+    const match = /^(0|[1-9][0-9]*)(ms|s|m|h)$/u.exec(value);
+    if (match === null)
+        return { kind: "invalid" };
+    const milliseconds = BigInt(match[1]) * MULTIPLIERS[match[2]];
+    if (milliseconds > BigInt(Number.MAX_SAFE_INTEGER))
+        return { kind: "overflow" };
+    return { kind: "parsed", milliseconds: Number(milliseconds) };
+}
+export function formatDuration(milliseconds) {
+    for (const [unit, multiplier] of [["h", 3_600_000], ["m", 60_000], ["s", 1_000]]) {
+        if (milliseconds >= multiplier && milliseconds % multiplier === 0)
+            return `${milliseconds / multiplier}${unit}`;
+    }
+    return `${milliseconds}ms`;
+}

package/build/src/git/admission.d.ts

@@ -1,6 +1,6 @@
 import type { Offer } from "../core/facts/offer.js";
 import type { GitAdmissionSnapshot } from "./observe.js";
-import { type GitRepository } from "./repository.js";
+import { type GitRepository, type GitRefAssertion } from "./repository.js";
 import { type ContractHead } from "../core/facts/types.js";
 type Accepted = Readonly<{
     kind: "accepted";
@@ -14,5 +14,5 @@ type Unknown = Readonly<{
     kind: "unknown";
 }>;
 export type Admission = Accepted | PublicationFailed | Unknown;
-export declare function admit(repository: GitRepository, offer: Offer, admission: GitAdmissionSnapshot): Admission;
+export declare function admit(repository: GitRepository, offer: Offer, admission: GitAdmissionSnapshot, assertions?: readonly GitRefAssertion[]): Admission;
 export {};

package/build/src/git/admission.js

@@ -1,8 +1,8 @@
-import { encodeEntry, } from "../core/facts/codec.js";
-import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, updateGitTree, updateRefsAtomically, writeBlob, writeCommit, } from "./repository.js";
-import { contractJournalPath, gitObjectIdForSnapshot, mintContractHead, mintSnapshotId, } from "./identity.js";
+import { decodeJournal, encodeEntry, } from "../core/facts/codec.js";
+import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, updateGitTreeFromFrozenDirectories, updateRefsAtomically, writeBlob, writeCommit, } from "./repository.js";
+import { contractJournalPath, contractJournalPaths, gitObjectIdForSnapshot, mintContractHead, mintSnapshotId, } from "./identity.js";
 import { validPath } from "./tree.js";
-const CONTRACT_JOURNAL_PATH = /^contracts\/[0-9a-f]{2}\/[0-9a-f]{2}\/[0-9a-f]{60}\.jsonl$/u;
+const CONTRACT_JOURNAL_PATH = /^contracts\/(?:active|terminal)\/[0-9a-f]{2}\/[0-9a-f]{2}\/[0-9a-f]{60}\.jsonl$/u;
 function assertAppendStructure(appends) {
     const seen = new Set();
     for (const append of appends) {
@@ -20,7 +20,7 @@ function assertAppendStructure(appends) {
     return appends;
 }
 function assertCompanionStructure(companions, appends) {
-    const reserved = new Set([GIT_FORMAT_PATH, ...appends.map((append) => contractJournalPath(append.contractId))]);
+    const reserved = new Set([GIT_FORMAT_PATH, ...appends.flatMap((append) => contractJournalPaths(append.contractId))]);
     const seen = new Set();
     for (const companion of companions) {
         if (!companion || typeof companion !== "object")
@@ -39,16 +39,19 @@ function assertCompanionStructure(companions, appends) {
 }
 function readCanonicalJournal(admission, id) {
     const snapshot = admission.snapshot;
-    const path = contractJournalPath(id);
+    const matches = contractJournalPaths(id).filter((path) => snapshot.paths.has(path));
+    if (matches.length > 1)
+        throw new Error(`duplicate contract journal identity: ${id}`);
+    const path = matches[0];
+    if (path === undefined)
+        return { bytes: Buffer.alloc(0), path: null };
     const entry = snapshot.paths.get(path);
-    if (entry === undefined)
-        return Buffer.alloc(0);
     if (entry.type !== "blob")
         throw new Error(`journal path is not a blob: ${path}`);
     const journal = admission.frozenJournalBytes.get(entry.oid);
     if (journal === undefined)
         throw new Error(`missing frozen journal bytes: ${path}`);
-    return journal;
+    return { bytes: journal, path };
 }
 function buildOffer(repository, admission, appends, companions) {
     const snapshot = admission.snapshot;
@@ -65,17 +68,24 @@ function buildOffer(repository, admission, appends, companions) {
         });
     }
     for (const append of appends) {
-        let journal = readCanonicalJournal(admission, append.contractId);
+        const current = readCanonicalJournal(admission, append.contractId);
+        let journal = current.bytes;
         for (const entry of append.entries)
             journal = Buffer.concat([journal, Buffer.from(encodeEntry(entry))]);
         const blob = writeBlob(repository, journal);
-        changes.set(contractJournalPath(append.contractId), { oid: blob, mode: "100644", type: "blob" });
+        const entries = decodeJournal(journal.toString("utf8"));
+        const terminal = entries.some((entry) => entry.kind === "claimed" || entry.kind === "abandoned");
+        const destination = contractJournalPath(append.contractId, terminal ? "terminal" : "active");
+        if (current.path !== null && current.path !== destination)
+            changes.set(current.path, null);
+        changes.set(destination, { oid: blob, mode: "100644", type: "blob" });
         heads[append.contractId] = mintContractHead(blob);
     }
     return { changes, heads };
 }
-function publishOffer(repository, snapshot, target, changes) {
-    const gitTree = updateGitTree(repository, snapshot.tree, changes);
+function publishOffer(repository, admission, target, changes, assertions) {
+    const { snapshot } = admission;
+    const gitTree = updateGitTreeFromFrozenDirectories(repository, snapshot.tree, admission.treeDirectories, changes);
     const gitCommit = mintSnapshotId(writeCommit({
         repository,
         tree: gitTree,
@@ -90,9 +100,9 @@ function publishOffer(repository, snapshot, target, changes) {
                     newOid: gitObjectIdForSnapshot(target.newOid),
                     expectedOid: gitObjectIdForSnapshot(target.expectedOid),
                 }]),
-    ]);
+    ], assertions);
 }
-export function admit(repository, offer, admission) {
+export function admit(repository, offer, admission, assertions = []) {
     if (!Array.isArray(offer.facts) || offer.facts.length === 0) {
         throw new Error("facts must be a nonempty array");
     }
@@ -100,7 +110,7 @@ export function admit(repository, offer, admission) {
     const companions = assertCompanionStructure(offer.companions ?? [], appends);
     const target = offer.target ?? null;
     const attempt = buildOffer(repository, admission, appends, companions);
-    const publication = publishOffer(repository, admission.snapshot, target, attempt.changes);
+    const publication = publishOffer(repository, admission, target, attempt.changes, assertions);
     if (publication.kind === "published") {
         return {
             kind: "accepted",

package/build/src/git/hooks.d.ts

@@ -1,3 +1,4 @@
+import { type Settings } from "../settings.js";
 export type HookCommand = Readonly<{
     argv: readonly string[];
     timeoutMs: number;
@@ -28,7 +29,21 @@ export type WorktreeHookLag = Readonly<{
     failure: HookFailure;
 }>;
 type HookPhase = "create" | "destroy";
+export declare function worktreeHooksFrom(input: Readonly<{
+    settings: Settings;
+}>): WorktreeHooks;
 export declare function hookMarkerPath(administrationDirectory: string): string;
+export type HookCommandRun = Readonly<{
+    kind: "ok";
+}> | Readonly<{
+    kind: "cancelled";
+}> | Readonly<{
+    kind: "failed";
+    command: number;
+    failure: HookFailure;
+}>;
+/** Execute an ordered command list without lifecycle state. Scratch owns this policy. */
+export declare function runHookCommands(worktree: string, commands: readonly HookCommand[], signal?: AbortSignal): Promise<HookCommandRun>;
 export declare function runCreateHooks(worktree: string, administrationDirectory: string, hooks: WorktreeHooks, retryHooks: boolean): Promise<WorktreeHookLag | null>;
 export declare function runDestroyHooks(worktree: string, administrationDirectory: string, hooks: WorktreeHooks, retryHooks: boolean): Promise<WorktreeHookLag | null>;
 export {};

package/build/src/git/hooks.js

@@ -4,10 +4,46 @@ import { fileURLToPath } from "node:url";
 import { replaceFileDurably } from "../coordination/durable-file.js";
 import { acquireSqliteTransactionLock } from "../coordination/sqlite-transaction-lock.js";
 import { runProcess, runProcessToExit } from "../runtime/proc/run.js";
+import { SettingsError } from "../settings.js";
 const MARKER_VERSION = 1;
 function object(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+export function worktreeHooksFrom(input) {
+    if (!object(input))
+        throw new TypeError("worktreeHooksFrom input must be an object");
+    const view = input.settings.namespace("worktree");
+    if (view.kind === "failed") {
+        throw new SettingsError(view.failures.map((failure) => `${failure.scope}: ${failure.diagnostic}`).join("; "));
+    }
+    for (const entry of view.entries) {
+        if (entry.name !== "create" && entry.name !== "destroy")
+            throw new SettingsError(`worktree has unknown entry: ${entry.name}`);
+    }
+    const commands = (phase) => {
+        const selected = view.entries.find((entry) => entry.name === phase);
+        if (selected === undefined)
+            return Object.freeze([]);
+        if (!Array.isArray(selected.value))
+            throw new SettingsError(`worktree.${phase} must be an array`);
+        return Object.freeze(selected.value.map((item, index) => {
+            if (!object(item))
+                throw new SettingsError(`worktree.${phase}[${index}] must be an object`);
+            const coordinate = `worktree.${phase}[${index}]`;
+            exactKeys(item, ["argv", "timeoutMs"], coordinate);
+            if (!Array.isArray(item.argv) || item.argv.length === 0 || !item.argv.every((value) => typeof value === "string")) {
+                throw new SettingsError(`${coordinate}.argv must be a nonempty string array`);
+            }
+            if (item.argv[0].trim().length === 0)
+                throw new SettingsError(`${coordinate}.argv[0] must be nonblank`);
+            if (!Number.isSafeInteger(item.timeoutMs) || item.timeoutMs < 1 || item.timeoutMs > 2_147_483_647) {
+                throw new SettingsError(`${coordinate}.timeoutMs must be an integer from 1 through 2147483647`);
+            }
+            return Object.freeze({ argv: Object.freeze([...item.argv]), timeoutMs: item.timeoutMs });
+        }));
+    };
+    return Object.freeze({ create: commands("create"), destroy: commands("destroy") });
+}
 function exactKeys(value, keys, coordinate) {
     const actual = Object.keys(value).sort();
     const expected = [...keys].sort();
@@ -139,6 +175,23 @@ function failedOutcome(outcome) {
     }
     return outcome;
 }
+/** Execute an ordered command list without lifecycle state. Scratch owns this policy. */
+export async function runHookCommands(worktree, commands, signal) {
+    for (const [command, value] of commands.entries()) {
+        const outcome = await runProcess({
+            argv: value.argv,
+            timeoutMs: value.timeoutMs,
+            cwd: worktree,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        if (outcome.kind === "cancelled")
+            return outcome;
+        const failure = failedOutcome(outcome);
+        if (failure !== null)
+            return { kind: "failed", command, failure };
+    }
+    return { kind: "ok" };
+}
 function withProgress(marker, phase, progress) {
     return { ...marker, [phase]: progress };
 }
@@ -183,11 +236,10 @@ async function executePendingCommand(input) {
         const command = marker.commands[input.phase][input.command];
         if (command === undefined)
             throw new Error("worktree hook marker pending index is out of range");
-        const failure = failedOutcome(await runProcess({
-            argv: command.argv,
-            timeoutMs: command.timeoutMs,
-            cwd: input.worktree,
-        }));
+        const result = await runHookCommands(input.worktree, [command]);
+        if (result.kind === "cancelled")
+            throw new Error("managed hook runner cancelled without a signal");
+        const failure = result.kind === "failed" ? result.failure : null;
         const next = input.command + 1;
         writeMarker(input.administrationDirectory, withProgress(marker, input.phase, failure === null
             ? next === marker.commands[input.phase].length ? { status: "ok" } : { status: "pending", next }

package/build/src/git/identity.d.ts

@@ -4,7 +4,11 @@ export type GitObjectId = string & {
     readonly [gitObjectIdBrand]: "GitObjectId";
 };
 export declare function contractLocator(contract: ContractId): string;
-export declare function contractJournalPath(contract: ContractId): string;
+export declare function gitRefLocator(ref: string): string;
+export declare function contractPhysicalName(contract: ContractId): string;
+export type ContractJournalClass = "active" | "terminal";
+export declare function contractJournalPath(contract: ContractId, journalClass?: ContractJournalClass): string;
+export declare function contractJournalPaths(contract: ContractId): readonly string[];
 export declare function gitObjectId(value: string, label?: string): GitObjectId;
 export declare function mintSnapshotId(value: string): SnapshotId;
 export declare function mintChangeId(value: string): ChangeId;