@astrosheep/keiyaku 4.5.11 → 4.5.13

package/build/src/protocol/run.js

@@ -1,19 +1,74 @@
 import { extendAdmissionPathsAt, observeContractsForAdmissionAt } from "../git/observe.js";
-import { withPrivateStatePublicationSeat } from "../git/private-state-seat.js";
+import { appendPrivateStateSeatClose, isPrivateStateSeatContention, mergePrivateStateSeatClose, withPrivateStatePublicationSeat, } from "../git/private-state-seat.js";
+import { GIT_REF, readRefs } from "../git/repository.js";
 import { admitDecidedOffer } from "./attempt.js";
-/** Form one decided offer without admitting or reinterpreting it. */
-export async function prepareProtocolAttempt(input, baseAttempt) {
-    const decisionObservation = input.observe === undefined
+export const STALE_PRIVATE_STATE_PREPARATION = {
+    kind: "publication-failed",
+    diagnostic: "stale private-state preparation",
+};
+export function privateRootCommit(observation) {
+    return observation.admission.snapshot.commit;
+}
+export function samePrivateRootObservation(prepared, fresh) {
+    return privateRootCommit(prepared) === privateRootCommit(fresh);
+}
+export function sameSpeculativeWorktreeInput(prepared, fresh) {
+    if (prepared === undefined || fresh === undefined)
+        return prepared === fresh;
+    return (prepared.tree === fresh.tree &&
+        prepared.head === fresh.head &&
+        prepared.mergeHead === fresh.mergeHead &&
+        prepared.dirty === fresh.dirty &&
+        prepared.changeId === fresh.changeId);
+}
+export async function privateStateAssertionsMatch(repository, assertions) {
+    if (assertions.length === 0)
+        return true;
+    const refs = await readRefs(repository, [GIT_REF, ...assertions.map((assertion) => assertion.ref)]);
+    return assertions.every((assertion) => refs.get(assertion.ref) === assertion.oid);
+}
+export function publicationFailedFromSeatError(error) {
+    if (isPrivateStateSeatContention(error))
+        return { kind: "publication-failed", diagnostic: error.message };
+    throw error;
+}
+export async function matchingPrivateRootObservation(repository, channel, contractId, prepared, revalidate) {
+    const fresh = await observeContractsForAdmissionAt(repository, channel, [contractId]);
+    if (!samePrivateRootObservation(prepared, fresh))
+        return STALE_PRIVATE_STATE_PREPARATION;
+    if (revalidate !== undefined && !(await revalidate(fresh)))
+        return STALE_PRIVATE_STATE_PREPARATION;
+    return fresh;
+}
+export async function privateStateSeatAttempt(repository, action, wrap) {
+    try {
+        return wrap(await withPrivateStatePublicationSeat(repository, action));
+    }
+    catch (error) {
+        return publicationFailedFromSeatError(error);
+    }
+}
+async function observeProtocolDecision(input) {
+    return input.observe === undefined
         ? await observeContractsForAdmissionAt(input.repository, input.channel, input.contracts, input.observationSelection)
         : await input.observe(input.repository, input.channel, input.contracts);
-    const observation = decisionObservation.decision;
-    const preparedInput = "prepareInput" in input && input.prepareInput !== undefined
-        ? await input.prepareInput(decisionObservation, input.input)
-        : { kind: "prepared", input: input.input, assertions: [] };
-    if (preparedInput.kind === "refused")
-        return preparedInput;
-    const attempt = input.extendAttempt === undefined ? baseAttempt : input.extendAttempt(baseAttempt, observation.size);
-    const decision = input.decide({ input: preparedInput.input, attempt, observation });
+}
+async function prepareProtocolSeed(input, observation) {
+    if (!("prepareInput" in input) || input.prepareInput === undefined) {
+        return { kind: "prepared", input: input.input, assertions: [] };
+    }
+    const prepared = await input.prepareInput(observation, input.input);
+    return prepared.kind === "refused" ? prepared : { ...prepared, assertions: prepared.assertions ?? [] };
+}
+async function decideDecoratedProtocolOffer(input, baseAttempt, decisionObservation, preparedInput) {
+    const attempt = input.extendAttempt === undefined
+        ? baseAttempt
+        : input.extendAttempt(baseAttempt, decisionObservation.decision.size);
+    const decision = input.decide({
+        input: preparedInput.input,
+        attempt,
+        observation: decisionObservation.decision,
+    });
     if (decision.kind === "refused")
         return decision;
     const companions = input.decorateOffer === undefined
@@ -35,29 +90,64 @@ export async function prepareProtocolAttempt(input, baseAttempt) {
         observation: admissionObservation,
         attempt,
         offer,
-        assertions: preparedInput.assertions ?? [],
+        assertions: preparedInput.assertions,
     };
 }
+/** Form one decided offer without admitting or reinterpreting it. */
+export async function prepareProtocolAttempt(input, baseAttempt) {
+    const decisionObservation = await observeProtocolDecision(input);
+    const preparedInput = await prepareProtocolSeed(input, decisionObservation);
+    if (preparedInput.kind === "refused")
+        return preparedInput;
+    return await decideDecoratedProtocolOffer(input, baseAttempt, decisionObservation, preparedInput);
+}
+function protocolAttemptWithSeatClose(outcome) {
+    return mergePrivateStateSeatClose(outcome, (value, closeLag) => {
+        if (value.kind !== "accepted")
+            throw new Error(closeLag.diagnostic);
+        return { ...value, seatClose: appendPrivateStateSeatClose(value.seatClose, closeLag) };
+    });
+}
+async function speculateProtocolAttempt(input) {
+    const observation = await observeProtocolDecision(input);
+    const prepared = await prepareProtocolSeed(input, observation);
+    return prepared.kind === "refused" ? prepared : { observation, ...prepared };
+}
+async function admitSpeculativeProtocolAttempt(input, seat, speculated, attempt) {
+    const fresh = await observeProtocolDecision(input);
+    if (!samePrivateRootObservation(speculated.observation, fresh) ||
+        !(await privateStateAssertionsMatch(input.repository, speculated.assertions))) {
+        return STALE_PRIVATE_STATE_PREPARATION;
+    }
+    const decided = await decideDecoratedProtocolOffer(input, attempt, fresh, {
+        kind: "prepared",
+        input: speculated.input,
+        assertions: speculated.assertions,
+    });
+    if (decided.kind === "refused")
+        return decided;
+    return await admitDecidedOffer({
+        channel: input.channel,
+        repository: input.repository,
+        seat,
+        decisionObservation: decided.observation,
+        attempt: decided.attempt,
+        offer: decided.offer,
+        primaryContract: input.input.contractId,
+        assertions: decided.assertions,
+        ...(input.validateAdmission === undefined ? {} : { validateAdmission: input.validateAdmission }),
+    });
+}
+async function runSpeculativeProtocolAttempt(input, speculated, attempt) {
+    if (speculated.kind === "refused")
+        return speculated;
+    return await privateStateSeatAttempt(input.repository, async (seat) => await admitSpeculativeProtocolAttempt(input, seat, speculated, attempt), protocolAttemptWithSeatClose);
+}
 /** Run bounded, verb-neutral attempts and return one real admission on acceptance. */
 export async function runProtocol(input) {
     const attempts = input.attempts;
     for (let index = 0; index < attempts.length; index += 1) {
-        const result = await withPrivateStatePublicationSeat(input.repository, async (seat) => {
-            const prepared = await prepareProtocolAttempt(input, attempts[index]);
-            if (prepared.kind === "refused")
-                return prepared;
-            return await admitDecidedOffer({
-                channel: input.channel,
-                repository: input.repository,
-                seat,
-                decisionObservation: prepared.observation,
-                attempt: prepared.attempt,
-                offer: prepared.offer,
-                primaryContract: input.input.contractId,
-                assertions: prepared.assertions,
-                ...(input.validateAdmission === undefined ? {} : { validateAdmission: input.validateAdmission }),
-            });
-        });
+        const result = await runSpeculativeProtocolAttempt(input, await speculateProtocolAttempt(input), attempts[index]);
         if (result.kind === "refused" || result.kind === "accepted" || result.kind === "publication-failed")
             return result;
         if (result.kind === "collision" && index + 1 === attempts.length)

package/build/src/runtime/proc/lifecycle.js

@@ -17,7 +17,7 @@ export function createProcessLifecycle(runTermination, releaseCustody) {
             return termination;
         },
         release() {
-            if (state !== "active")
+            if (state === "inert")
                 return;
             state = "inert";
             releaseCustody();

package/build/src/runtime/proc/line-rpc.d.ts

@@ -12,6 +12,7 @@ export declare class LineRpcProcess {
     private readonly pending;
     private readonly notifications;
     private readonly serverRequests;
+    private readonly requestTimeoutMs;
     private nextId;
     private stdout;
     private closed;
@@ -19,6 +20,8 @@ export declare class LineRpcProcess {
         argv: readonly [string, ...string[]];
         cwd: string;
         env?: NodeJS.ProcessEnv;
+        requestTimeoutMs?: number;
+        timeoutMs?: number;
     }>);
     onNotification(listener: (value: LineRpcNotification) => void): void;
     onServerRequest(listener: (value: LineRpcServerRequest) => void): void;
@@ -26,7 +29,10 @@ export declare class LineRpcProcess {
     private consume;
     private receive;
     private fail;
-    request(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown>;
+    private failAndClose;
+    request(method: string, params?: Readonly<Record<string, unknown>>, options?: Readonly<{
+        timeoutMs?: number;
+    }>): Promise<unknown>;
     notify(method: string): void;
     endInputAndDrain(timeoutMs?: number): Promise<void>;
     close(force?: boolean): Promise<void>;

package/build/src/runtime/proc/line-rpc.js

@@ -1,4 +1,5 @@
 import { spawnStdioProcess } from "./stdio.js";
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 function object(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -12,10 +13,15 @@ export class LineRpcProcess {
     pending = new Map();
     notifications = new Set();
     serverRequests = new Set();
+    requestTimeoutMs;
     nextId = 1;
     stdout = "";
     closed = false;
     constructor(input) {
+        this.requestTimeoutMs = input.requestTimeoutMs ?? input.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        if (!Number.isFinite(this.requestTimeoutMs) || this.requestTimeoutMs < 0) {
+            throw new TypeError("line RPC request timeout must be a nonnegative finite millisecond duration");
+        }
         this.process = spawnStdioProcess(input);
         this.process.output.setEncoding("utf8");
         this.process.output.on("data", (chunk) => this.consume(chunk));
@@ -34,15 +40,22 @@ export class LineRpcProcess {
         void this.process.exited.then(listener);
     }
     consume(chunk) {
-        this.stdout += chunk;
-        for (;;) {
-            const newline = this.stdout.indexOf("\n");
-            if (newline < 0)
+        let offset = 0;
+        while (offset < chunk.length) {
+            const newline = chunk.indexOf("\n", offset);
+            if (newline < 0) {
+                this.stdout += chunk.slice(offset);
                 return;
-            const line = this.stdout.slice(0, newline).trim();
-            this.stdout = this.stdout.slice(newline + 1);
+            }
+            this.stdout += chunk.slice(offset, newline);
+            const rawLine = this.stdout;
+            this.stdout = "";
+            offset = newline + 1;
+            const line = rawLine.trim();
             if (line.length > 0)
                 this.receive(line);
+            if (this.closed)
+                return;
         }
     }
     receive(line) {
@@ -51,6 +64,7 @@ export class LineRpcProcess {
             decoded = JSON.parse(line);
         }
         catch {
+            this.failAndClose(new Error("line RPC protocol received malformed JSON"));
             return;
         }
         const message = object(decoded);
@@ -61,6 +75,8 @@ export class LineRpcProcess {
             if (pending === undefined)
                 return;
             this.pending.delete(message.id);
+            if (pending.timer !== undefined)
+                clearTimeout(pending.timer);
             const error = object(message.error);
             if (error !== undefined)
                 pending.reject(new Error(text(error.message) ?? "line RPC error"));
@@ -81,20 +97,44 @@ export class LineRpcProcess {
             listener({ method, ...(params === undefined ? {} : { params }) });
     }
     fail(error) {
-        for (const pending of this.pending.values())
+        for (const pending of this.pending.values()) {
+            if (pending.timer !== undefined)
+                clearTimeout(pending.timer);
             pending.reject(error);
+        }
         this.pending.clear();
     }
-    request(method, params) {
+    failAndClose(error) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.fail(error);
+        void this.process.close(true).catch(() => undefined);
+    }
+    request(method, params, options = {}) {
         if (this.closed)
             return Promise.reject(new Error("line RPC process is closed"));
+        const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
+        if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+            return Promise.reject(new TypeError("line RPC request timeout must be a nonnegative finite millisecond duration"));
+        }
         const id = this.nextId++;
         return new Promise((resolve, reject) => {
-            this.pending.set(id, { resolve, reject });
+            const pending = { resolve, reject };
+            pending.timer = setTimeout(() => {
+                if (this.pending.get(id) !== pending)
+                    return;
+                this.pending.delete(id);
+                reject(new Error(`line RPC request timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            pending.timer.unref?.();
+            this.pending.set(id, pending);
             this.process.input.write(`${JSON.stringify({ id, method, ...(params === undefined ? {} : { params }) })}\n`, (error) => {
                 if (error === null || error === undefined)
                     return;
                 this.pending.delete(id);
+                if (pending.timer !== undefined)
+                    clearTimeout(pending.timer);
                 reject(error);
             });
         });

package/build/src/runtime/proc/run.d.ts

@@ -53,5 +53,4 @@ export { terminateOwnedProcess } from "./termination.js";
 export declare function spawnDetachedProcess(input: DetachedProcessInput): Promise<OwnedProcess>;
 export declare function runProcess(input: ProcessInput): Promise<ProcessOutcome>;
 export declare function runCrossPlatformProcess(input: ProcessInput): Promise<ProcessOutcome>;
-export declare function runProcessToExit(input: ProcessLaunch): Promise<ProcessOutcome>;
 export declare function consumeProcessStdout(input: ProcessInput, consume: (chunk: Buffer) => void): Promise<ProcessConsumption>;

package/build/src/runtime/proc/run.js

@@ -87,14 +87,10 @@ export async function spawnDetachedProcess(input) {
         const from = (await log.stat()).size;
         const child = spawn(input.argv[0], input.argv.slice(1), spawnOptionsFor(input, ["ignore", log.fd, log.fd]));
         const lifecycle = createProcessLifecycle((force) => terminateOwnedProcess(child, force), () => child.unref());
-        const invalidate = () => {
-            lifecycle.markInert();
-        };
-        child.once("exit", invalidate);
-        child.once("close", invalidate);
         const exited = new Promise((resolve, reject) => {
             child.once("close", (code, signal) => {
                 void (async () => {
+                    await lifecycle.terminate();
                     const status = detachedExitStatus(code, signal);
                     let failure;
                     let result;
@@ -239,12 +235,6 @@ export async function runCrossPlatformProcess(input) {
         throw new Error("buffered process produced a stream consumer error");
     return result.outcome;
 }
-export async function runProcessToExit(input) {
-    const result = await executeProcess(input, undefined);
-    if (result.outcome.kind === "stream-error")
-        throw new Error("buffered process produced a stream consumer error");
-    return result.outcome;
-}
 export function consumeProcessStdout(input, consume) {
     return executeProcess(input, input.timeoutMs, consume);
 }

package/build/src/runtime/proc/termination.d.ts

@@ -1,4 +1,5 @@
 import { type ChildProcess } from "node:child_process";
+export declare function ownedProcessGroupExists(pid: number): boolean;
 export declare function terminateWindowsTree(pid: number): Promise<void>;
 export declare function settleWindowsTermination(exit: Promise<void>): Promise<void>;
 export declare function terminateOwnedProcess(child: ChildProcess, force?: boolean): Promise<void>;

package/build/src/runtime/proc/termination.js

@@ -4,6 +4,7 @@ import { promisify } from "node:util";
 const TERMINATION_GRACE_MS = 250;
 const WINDOWS_TERMINATION_SETTLE_MS = 250;
 const WINDOWS_TERMINATION_TIMEOUT_MS = 1_000;
+const PROCESS_GROUP_POLL_MS = 10;
 const execFileAsync = promisify(execFile);
 function isMissingProcess(error) {
     return error.code === "ESRCH";
@@ -25,6 +26,29 @@ async function signalOwnedProcessGroup(pid, signal, exit) {
             throw error;
     }
 }
+export function ownedProcessGroupExists(pid) {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (isMissingProcess(error))
+            return false;
+        if (error.code === "EPERM")
+            return true;
+        throw error;
+    }
+}
+async function waitForOwnedProcessGroupExit(pid) {
+    const attempts = Math.ceil(TERMINATION_GRACE_MS / PROCESS_GROUP_POLL_MS);
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        if (!ownedProcessGroupExists(pid))
+            return;
+        await delay(PROCESS_GROUP_POLL_MS, undefined, { ref: false });
+    }
+    if (ownedProcessGroupExists(pid))
+        throw new Error("owned process group did not exit after termination");
+}
 export async function terminateWindowsTree(pid) {
     try {
         await execFileAsync("taskkill", ["/PID", String(pid), "/T", "/F"], {
@@ -54,24 +78,41 @@ function closeWindowsStreams(child) {
     child.stdout?.destroy();
     child.stderr?.destroy();
 }
-export async function terminateOwnedProcess(child, force = false) {
-    const pid = child.pid;
-    if (pid === undefined || child.exitCode !== null || child.signalCode !== null)
-        return;
-    let exited = false;
-    const exit = new Promise((resolve) => {
-        child.once("exit", () => {
-            exited = true;
+function waitForOwnedChildExit(child, pid) {
+    return new Promise((resolve) => {
+        if (child.exitCode !== null || child.signalCode !== null) {
             resolve();
-        });
-        child.once("close", () => {
-            exited = true;
+            return;
+        }
+        let settled = false;
+        const settle = () => {
+            if (settled)
+                return;
+            settled = true;
             resolve();
+        };
+        child.once("exit", settle);
+        child.once("close", settle);
+        // Unknown exit can leave exitCode/signalCode both null after close; settle if the leader pid is gone.
+        process.nextTick(() => {
+            if (child.exitCode !== null || child.signalCode !== null) {
+                settle();
+                return;
+            }
+            try {
+                process.kill(pid, 0);
+            }
+            catch {
+                settle();
+            }
         });
     });
-    await new Promise((resolve) => setImmediate(resolve));
-    if (exited || child.exitCode !== null || child.signalCode !== null)
+}
+export async function terminateOwnedProcess(child, force = false) {
+    const pid = child.pid;
+    if (pid === undefined)
         return;
+    const exit = waitForOwnedChildExit(child, pid);
     if (process.platform === "win32") {
         try {
             await terminateWindowsTree(pid);
@@ -84,15 +125,19 @@ export async function terminateOwnedProcess(child, force = false) {
     }
     if (force) {
         await signalOwnedProcessGroup(pid, "SIGKILL", exit);
+        await waitForOwnedProcessGroupExit(pid);
         await exit;
         return;
     }
     await signalOwnedProcessGroup(pid, "SIGTERM", exit);
-    if (exited || child.exitCode !== null || child.signalCode !== null)
-        return;
-    await Promise.race([exit, delay(TERMINATION_GRACE_MS)]);
-    if (exited || child.exitCode !== null || child.signalCode !== null)
+    if (!ownedProcessGroupExists(pid)) {
+        await exit;
         return;
-    await signalOwnedProcessGroup(pid, "SIGKILL", exit);
+    }
+    await delay(TERMINATION_GRACE_MS);
+    if (ownedProcessGroupExists(pid)) {
+        await signalOwnedProcessGroup(pid, "SIGKILL", exit);
+        await waitForOwnedProcessGroupExit(pid);
+    }
     await exit;
 }

package/build/src/settings.d.ts

@@ -46,6 +46,16 @@ export declare class SettingsError extends Error {
     readonly kind = "settings";
     constructor(message: string);
 }
+export type Gate = string;
+export type GatesFromInput = Readonly<{
+    settings: Settings;
+    names?: readonly string[];
+}>;
+export type RequireBranchesToBeUpToDateFromInput = Readonly<{
+    settings: Settings;
+}>;
 export declare function settings(input?: SettingsInput): Promise<Settings>;
 /** Read only the project scope owned by a materialized candidate snapshot. */
 export declare function projectSettings(root: string): Promise<Settings>;
+export declare function gatesFrom(input: GatesFromInput): readonly Gate[];
+export declare function requireBranchesToBeUpToDateFrom(input: RequireBranchesToBeUpToDateFromInput): boolean;

package/build/src/settings.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { gateWord } from "./core/facts/types.js";
 export class SettingsError extends Error {
     kind = "settings";
     constructor(message) {
@@ -52,9 +53,10 @@ function namespaceEntries(name, scope, loaded) {
     if (loaded.state.kind === "failed") {
         return { entries: [], failure: { scope, diagnostic: loaded.state.diagnostic } };
     }
-    const value = loaded.root?.[name];
-    if (value === undefined)
+    if (loaded.root === undefined || !Object.prototype.hasOwnProperty.call(loaded.root, name)) {
         return { entries: [] };
+    }
+    const value = loaded.root[name];
     if (!object(value)) {
         return { entries: [], failure: { scope, diagnostic: `${name} must be an object of named values` } };
     }
@@ -116,3 +118,87 @@ export async function projectSettings(root) {
         state: { kind: "absent" },
     });
 }
+function namespaceFailure(view) {
+    if (view.kind !== "failed")
+        throw new Error("settings namespace failure expected");
+    throw new SettingsError(view.failures.map((failure) => `${failure.scope}: ${failure.diagnostic}`).join("; "));
+}
+function bundleGates(name, value) {
+    if (!object(value))
+        throw new SettingsError(`gate bundle '${name}' must be an object`);
+    if (value.kind !== "bundle") {
+        throw new SettingsError(`gate bundle '${name}' has unsupported kind: ${String(value.kind)}`);
+    }
+    for (const field of Object.keys(value)) {
+        if (field !== "kind" && field !== "gates") {
+            throw new SettingsError(`gate bundle '${name}' has unknown field: ${field}`);
+        }
+    }
+    if (!Array.isArray(value.gates)) {
+        throw new SettingsError(`gate bundle '${name}'.gates must be an array`);
+    }
+    return value.gates.map((gate) => {
+        if (!gateWord(gate)) {
+            throw new SettingsError(`gate bundle '${name}' contains an invalid gate word`);
+        }
+        if (gate !== "reviewed" && gate !== "verified") {
+            throw new SettingsError(`gate bundle '${name}' contains a gate without a producer: ${gate}`);
+        }
+        return gate;
+    });
+}
+export function gatesFrom(input) {
+    if (!object(input))
+        throw new TypeError("gatesFrom input must be an object");
+    if (input.names !== undefined && !Array.isArray(input.names)) {
+        throw new TypeError("gatesFrom names must be an array");
+    }
+    const names = input.names ?? ["default"];
+    for (const name of names) {
+        if (!gateWord(name))
+            throw new SettingsError("gate bundle name must match ^[a-z][a-z0-9-]{0,63}$");
+    }
+    const view = input.settings.namespace("gates");
+    if (view.kind === "failed")
+        namespaceFailure(view);
+    const expanded = [];
+    const seen = new Set();
+    for (const name of names) {
+        const selected = view.entries.find((entry) => entry.name === name);
+        if (selected === undefined) {
+            if (input.names === undefined) {
+                if (!seen.has("reviewed"))
+                    expanded.push("reviewed");
+                seen.add("reviewed");
+                continue;
+            }
+            throw new SettingsError(`unknown gate bundle: ${name}`);
+        }
+        for (const gate of bundleGates(name, selected.value)) {
+            if (seen.has(gate))
+                continue;
+            seen.add(gate);
+            expanded.push(gate);
+        }
+    }
+    return Object.freeze(expanded);
+}
+export function requireBranchesToBeUpToDateFrom(input) {
+    if (!object(input))
+        throw new TypeError("requireBranchesToBeUpToDateFrom input must be an object");
+    const view = input.settings.namespace("git");
+    if (view.kind === "failed")
+        namespaceFailure(view);
+    for (const entry of view.entries) {
+        if (entry.name !== "requireBranchesToBeUpToDate") {
+            throw new SettingsError(`git has unknown entry: ${entry.name}`);
+        }
+    }
+    const selected = view.entries.find((entry) => entry.name === "requireBranchesToBeUpToDate");
+    if (selected === undefined)
+        return false;
+    if (typeof selected.value !== "boolean") {
+        throw new SettingsError("git.requireBranchesToBeUpToDate must be a boolean");
+    }
+    return selected.value;
+}

package/build/src/settlement/result-codec.d.ts

@@ -0,0 +1,2 @@
+import type { SettlementLag } from "./settle.js";
+export declare function decodeSettlementLag(value: unknown): SettlementLag;

package/build/src/settlement/result-codec.js

@@ -0,0 +1,56 @@
+import { contractId } from "../core/facts/types.js";
+import { canonicalTaskId } from "../task/identity.js";
+function fail() {
+    throw new Error("malformed settlement lag");
+}
+function object(value, required, optional = []) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        fail();
+    const record = value;
+    const allowed = new Set([...required, ...optional]);
+    for (const key of Object.keys(record))
+        if (!allowed.has(key))
+            fail();
+    for (const key of required)
+        if (!(key in record))
+            fail();
+    return record;
+}
+function nonblank(value) {
+    if (typeof value !== "string" || value.trim() === "")
+        fail();
+    return value;
+}
+export function decodeSettlementLag(value) {
+    const record = object(value, ["kind", "surface", "contractId", "diagnostic"], ["taskId", "path"]);
+    if (record.kind !== "settlement-failed")
+        fail();
+    if (record.surface !== "task-holder" && record.surface !== "task")
+        fail();
+    let id;
+    try {
+        id = contractId(nonblank(record.contractId));
+    }
+    catch {
+        fail();
+    }
+    const lag = {
+        kind: "settlement-failed",
+        surface: record.surface,
+        contractId: id,
+        diagnostic: nonblank(record.diagnostic),
+    };
+    if (record.taskId !== undefined) {
+        try {
+            return {
+                ...lag,
+                taskId: canonicalTaskId(nonblank(record.taskId)),
+                ...(record.path === undefined ? {} : { path: nonblank(record.path) }),
+            };
+        }
+        catch {
+            fail();
+        }
+    }
+    return record.path === undefined ? lag : { ...lag, path: nonblank(record.path) };
+}