@astrosheep/keiyaku 2.9.3 → 2.9.5

package/build/core/{claim-delivery.js → settlement/claim-delivery.js}

@@ -1,13 +1,13 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { FlowError } from "../flow-error.js";
-import { syncDirectory } from "../fs/durability.js";
-import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, wrapGitError } from "../git/core.js";
-import { readLedger } from "./ledger.js";
-import { shortCommitHash } from "../git/commits.js";
-import { commissionTarget, latestBase } from "./status/drift.js";
-import { settleTaskBoardForLanding } from "./task-contract.js";
-import { stableRepoRoot } from "./worktree-path.js";
+import { FlowError } from "../../flow-error.js";
+import { syncDirectory } from "../../fs/durability.js";
+import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, wrapGitError } from "../../git/core.js";
+import { readLedger } from "../ledger.js";
+import { shortCommitHash } from "../../git/commits.js";
+import { commissionTarget, latestBase } from "../status/drift.js";
+import { settleTaskBoardForLanding } from "../task/index.js";
+import { stableRepoRoot } from "../worktree-path.js";
 const CLAIM_RECEIPTS_FILE = "claim-receipts.jsonl";
 async function appendClaimReceipt(cwd, receipt, restoreIfMissing = "") {
     const receiptPath = path.join(await stableRepoRoot(cwd), ".keiyaku", CLAIM_RECEIPTS_FILE);

package/build/core/{claim.js → settlement/claim.js}

@@ -1,10 +1,11 @@
-import { FlowError } from "../flow-error.js";
-import { activeLedgerRef, appendWithRetry, readLedger } from "./ledger.js";
+import { FlowError } from "../../flow-error.js";
+import { assertCleanTrackedWorkingTree } from "../../git/worktree.js";
+import { activeLedgerRef, appendWithRetry, readLedger } from "../ledger.js";
 import { assertClaimQueueHead, readQueueReadModel } from "./queue.js";
-import { releaseScope } from "./registry.js";
-import { deriveContractState } from "./status/lifecycle.js";
-import { commissionTarget, latestBase } from "./status/drift.js";
-import { cleanupContractWorkspace, findContractWorktreePath, stableRepoRoot } from "./worktree-path.js";
+import { releaseScope } from "../registry.js";
+import { deriveContractState } from "../status/lifecycle.js";
+import { commissionTarget, latestBase } from "../status/drift.js";
+import { cleanupContractWorkspace, findContractWorktreePath, stableRepoRoot } from "../worktree-path.js";
 import { defaultMergeDelivery, relativeDisplayPath, resolveCommit, resolveCommitOrNull, } from "./claim-delivery.js";
 async function cleanupClaim(cwd, contractId, actor, at) {
     const stableRoot = await stableRepoRoot(cwd);
@@ -14,16 +15,37 @@ async function cleanupClaim(cwd, contractId, actor, at) {
 function findClaim(entries) {
     return entries.find((entry) => entry.kind === "claim");
 }
+/** Verdict belonging to the open petition window (after last petition, before claim). */
+function latestCurrentPetitionVerdict(entries) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry.kind === "verdict")
+            return entry;
+        if (entry.kind === "petition")
+            return undefined;
+    }
+    return undefined;
+}
+/**
+ * Delivery requires an approved verdict for the current petition.
+ * Already-claimed cleanup retry remains legal without re-proving judgment.
+ */
 function assertClaimableFromLedger(contractId, ledger) {
     if (!ledger) {
         throw new FlowError("INTERNAL_STATE", `contract ${contractId} not found`);
     }
     const state = deriveContractState(ledger.entries);
     const claim = findClaim(ledger.entries);
-    if (state.state === "petitioned")
-        return claim;
+    // Already-claimed cleanup retry: legal head even if a prior crash left debris.
     if (claim && state.state === "claimed")
         return claim;
+    if (state.state === "petitioned") {
+        const verdict = latestCurrentPetitionVerdict(ledger.entries);
+        if (verdict?.data.result !== "approved") {
+            throw new FlowError("INTERNAL_STATE", `contract ${contractId} cannot claim without approved verdict for current petition`);
+        }
+        return claim;
+    }
     if (state.state === "forfeited") {
         throw new FlowError("INTERNAL_STATE", `contract ${contractId} forfeited`);
     }
@@ -95,6 +117,8 @@ export async function previewClaimContract(input) {
 }
 export async function claimContract(input) {
     const at = new Date(input.nowMs).toISOString();
+    const deliveryWorktree = await findContractWorktreePath(input.cwd, input.contractId);
+    await assertCleanTrackedWorkingTree(deliveryWorktree ?? input.cwd);
     const existing = await readLedger(input.cwd, input.contractId);
     const existingClaim = assertClaimableFromLedger(input.contractId, existing);
     const existingState = existing ? deriveContractState(existing.entries) : undefined;

package/build/core/settlement/index.js

@@ -0,0 +1,19 @@
+/**
+ * Public surface for the settlement package.
+ * Only symbols required by current external consumers are re-exported.
+ * Package-internal modules must import each other directly, not through this file.
+ *
+ * Orchestrator owns: gates → petition → pure verdict → claim delivery / reject publish.
+ * Foundations (queue, claim-delivery) may be depended on downward by stage modules.
+ * Stage modules (petition, verdict, claim) do not import one another.
+ */
+export { claimKeiyaku, petitionKeiyaku, } from "./settlement.js";
+export { buildPetitionClaimInput, petitionContract, loadPetitionPreflightContext, assertPetitionFresh, assertPetitionArcReady, assertPetitionable, } from "./petition.js";
+export { previewPetition, PETITION_PREVIEW_GATE_NAMES, } from "./petition-preview.js";
+export { verdictContract, } from "./verdict.js";
+export { claimContract, previewClaimContract, } from "./claim.js";
+export { defaultMergeDelivery, relativeDisplayPath, resolveCommit, resolveCommitOrNull, } from "./claim-delivery.js";
+export { allocateSettlementSeat, assertClaimQueueHead, deriveQueueReadModel, queueMembership, readQueueReadModel, seatAllocatorRef, } from "./queue.js";
+export { buildClaimGatePipeline, createAgentReviewGate, createOathGate, } from "./petition-claim-gates.js";
+export { assertHeadUnchanged } from "./petition-head-guard.js";
+export { forfeitKeiyaku } from "./petition-forfeit.js";

package/build/core/{petition-claim-gates.js → settlement/petition-claim-gates.js}

@@ -1,21 +1,20 @@
-import { spawn } from "node:child_process";
-import { getConfig } from "../config/env.js";
-import { assertSettingsKnobUsable } from "../config/settings/disease.js";
-import { resolveReviewerAgentName } from "../config/settings/knobs.js";
-import { loadKeiyakuSettings } from "../config/settings/loader.js";
-import { loadAkumaCatalog } from "../config/akuma-loader.js";
-import { formatAvailableAgentNames } from "../agents/selector.js";
-import { getDiffStats } from "../git/diff/preview.js";
-import { readDiff } from "../git/diff/read.js";
-import { getCurrentBranch } from "../git/branches.js";
-import { getLatestCommitHash } from "../git/staging.js";
-import { DIFF_PREVIEW_TEXT_MAX_CHARS } from "../keiyaku.js";
-import { FlowError } from "../flow-error.js";
-import { persistResponseHistory } from "./transcripts.js";
-import { logInfo } from "../telemetry/logger.js";
-import { execSubagent } from "./call/call.js";
-import { readContractLog } from "./log.js";
-import { buildVerificationFailureHints } from "./hints.js";
+import { getConfig } from "../../config/env.js";
+import { assertSettingsKnobUsable } from "../../config/settings/disease.js";
+import { resolveReviewerAgentName } from "../../config/settings/knobs.js";
+import { loadKeiyakuSettings } from "../../config/settings/loader.js";
+import { loadAkumaCatalog } from "../../config/akuma-loader.js";
+import { formatAvailableAgentNames } from "../../agents/selector.js";
+import { getDiffStats } from "../../git/diff/preview.js";
+import { readDiff } from "../../git/diff/read.js";
+import { getCurrentBranch } from "../../git/branches.js";
+import { getLatestCommitHash } from "../../git/staging.js";
+import { DIFF_PREVIEW_TEXT_MAX_CHARS } from "../../keiyaku.js";
+import { FlowError } from "../../flow-error.js";
+import { persistResponseHistory } from "../transcripts.js";
+import { logInfo } from "../../telemetry/logger.js";
+import { execSubagent } from "../call/call.js";
+import { readContractLog } from "../log.js";
+import { runVerificationCommand } from "./verification.js";
 const CLAIM_VERIFICATION_OUTPUT_MAX_CHARS = 1200;
 const REVIEW_PASS_TOKEN = "PASS";
 const REVIEW_REJECTION_MESSAGE = "CLAIM rejected by independent reviewer.";
@@ -49,31 +48,6 @@ function buildReviewAttemptBlock(reviewNumber) {
         "Focus on whether the previous concerns have been addressed.",
     ];
 }
-async function runCommand(options) {
-    return await new Promise((resolve, reject) => {
-        const child = spawn(options.command, options.args, {
-            cwd: options.cwd,
-            stdio: ["ignore", "pipe", "pipe"],
-            env: getConfig().runtimeEnv,
-        });
-        let stdout = "";
-        let stderr = "";
-        child.stdout.on("data", (chunk) => {
-            stdout += String(chunk);
-        });
-        child.stderr.on("data", (chunk) => {
-            stderr += String(chunk);
-        });
-        child.on("error", reject);
-        child.on("close", (code) => {
-            resolve({
-                code: typeof code === "number" ? code : -1,
-                stdout,
-                stderr,
-            });
-        });
-    });
-}
 function clipCommandOutput(value, maxChars = CLAIM_VERIFICATION_OUTPUT_MAX_CHARS) {
     const trimmed = value.trim();
     if (!trimmed)
@@ -129,17 +103,18 @@ export function createCommandVerificationGate() {
         async evaluate({ cwd, verificationCommands }) {
             for (const verification of verificationCommands) {
                 logInfo(`[CLAIM] Running verification: ${verification.label}`, { cwd, section: "script", progressOnly: true });
-                const result = await runCommand({
-                    cwd,
-                    command: verification.command,
-                    args: verification.args,
-                });
+                const result = await runVerificationCommand(cwd, verification);
                 if (result.code !== 0) {
                     return {
                         pass: false,
                         code: "CLOSE_QUALITY_GATE_FAILED",
                         message: `CLAIM blocked: verification failed at '${verification.label}' (exit ${result.code}).`,
-                        hints: buildVerificationFailureHints(verification.label, clipCommandOutput(result.stdout), clipCommandOutput(result.stderr)),
+                        facts: {
+                            kind: "verification_failure",
+                            label: verification.label,
+                            stdout: clipCommandOutput(result.stdout.tail),
+                            stderr: clipCommandOutput(result.stderr.tail),
+                        },
                     };
                 }
             }

package/build/core/{petition-forfeit.js → settlement/petition-forfeit.js}

@@ -1,5 +1,5 @@
-import { forfeitContract } from "./forfeit.js";
-import { readContractLog } from "./log.js";
+import { forfeitContract } from "../forfeit.js";
+import { readContractLog } from "../log.js";
 function maxArc(entries) {
     return entries.filter((entry) => entry.kind === "arc").length;
 }

package/build/core/{petition-head-guard.js → settlement/petition-head-guard.js}

@@ -1,5 +1,5 @@
-import { FlowError } from "../flow-error.js";
-import { getLatestCommitHash } from "../git/staging.js";
+import { FlowError } from "../../flow-error.js";
+import { getLatestCommitHash } from "../../git/staging.js";
 const CONCURRENT_MODIFICATION_CODE = "CONCURRENT_MODIFICATION";
 export async function assertHeadUnchanged(cwd, expectedHead, operation) {
     const currentHead = await getLatestCommitHash(cwd);

package/build/core/settlement/petition-io.js

@@ -0,0 +1 @@
+export {};

package/build/core/{petition-preview.js → settlement/petition-preview.js}

@@ -1,6 +1,6 @@
 import { createOathGate } from "./petition-claim-gates.js";
 import { assertPetitionArcReady, assertPetitionFresh, assertPetitionable, loadPetitionPreflightContext, } from "./petition.js";
-import { petitionSealSource, previewSeal } from "./seal.js";
+import { petitionSealSource, previewSeal } from "../seal.js";
 export const PETITION_PREVIEW_GATE_NAMES = [
     "contract",
     "freshness",
@@ -55,7 +55,7 @@ export async function previewPetition(input) {
     let seal;
     if (freshness.result === "pass" && arc.result === "pass" && state.result === "pass") {
         try {
-            const sealPreview = await previewSeal(context.deliveryCwd, context.ledger.entries, "HEAD", input.waivePaths);
+            const sealPreview = await previewSeal(context.deliveryCwd, context.ledger.entries, "HEAD");
             seal = { name: "seal", result: "pass", detail: sealPathDetail(sealPreview.paths) };
         }
         catch (error) {

package/build/core/{petition.js → settlement/petition.js}

@@ -1,12 +1,13 @@
-import { FlowError } from "../flow-error.js";
-import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, wrapGitError } from "../git/core.js";
-import { parseCommandMarkdown } from "./command-io.js";
-import { activeLedgerRef, appendWithRetry, readLedger } from "./ledger.js";
+import { FlowError } from "../../flow-error.js";
+import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, wrapGitError } from "../../git/core.js";
+import { parseCommandMarkdown } from "../command-markdown.js";
+import { activeLedgerRef, appendWithRetry, readLedger } from "../ledger.js";
 import { allocateSettlementSeat, queueMembership, readQueueReadModel } from "./queue.js";
-import { findOpenArc, getMaxArc, receiptsAfterFence, sealCurrentArc } from "./seal.js";
-import { deriveContractState } from "./status/lifecycle.js";
-import { commissionTarget, latestBase } from "./status/drift.js";
-import { findContractWorktreePath } from "./worktree-path.js";
+import { appendScopeTerms, findOpenArc, getMaxArc, receiptsAfterFence, sealCurrentArc } from "../seal.js";
+import { deriveContractState } from "../status/lifecycle.js";
+import { commissionTarget, latestBase } from "../status/drift.js";
+import { findContractWorktreePath } from "../worktree-path.js";
+import { assertCleanTrackedWorkingTree } from "../../git/worktree.js";
 async function resolveCommit(cwd, ref) {
     const git = createGit(cwd);
     try {
@@ -47,7 +48,7 @@ export async function assertPetitionFresh(cwd, contractId, entries, base) {
         throw new FlowError("INTERNAL_STATE", `contract ${contractId} commission target ${target.ref} does not resolve`);
     }
     if (base !== head) {
-        throw new FlowError("INTERNAL_STATE", `contract ${contractId} must renew onto ${target.branch} before petition`, { hints: [`keiyaku @${contractId} renew — renews delivery before petition`] });
+        throw new FlowError("INTERNAL_STATE", `contract ${contractId} must renew onto ${target.branch} before petition`, { facts: { kind: "needs_renew", contractId } });
     }
 }
 export async function assertPetitionArcReady(deliveryCwd, contractId, entries) {
@@ -55,7 +56,7 @@ export async function assertPetitionArcReady(deliveryCwd, contractId, entries) {
         return;
     const loose = await receiptsAfterFence(deliveryCwd, entries);
     if (loose.length > 0) {
-        throw new FlowError("NO_OPEN_ARC", `${loose.length} commits after fence have no arc to receipt them`, { hints: [`keiyaku @${contractId} arc — opens a new arc to receipt them, then petition`] });
+        throw new FlowError("NO_OPEN_ARC", `${loose.length} commits after fence have no arc to receipt them`, { facts: { kind: "loose_commits", contractId, nextVerb: "petition" } });
     }
 }
 export function assertPetitionable(contractId, entries) {
@@ -68,16 +69,24 @@ export function assertPetitionable(contractId, entries) {
 export async function petitionContract(input) {
     const at = new Date(input.nowMs).toISOString();
     const { ledger, deliveryCwd, base, target } = await loadPetitionPreflightContext(input.cwd, input.contractId);
+    await assertCleanTrackedWorkingTree(deliveryCwd);
     await assertPetitionFresh(input.cwd, input.contractId, ledger.entries, base);
     await assertPetitionArcReady(deliveryCwd, input.contractId, ledger.entries);
     assertPetitionable(input.contractId, ledger.entries);
+    await appendScopeTerms({
+        cwd: input.cwd,
+        renderCwd: deliveryCwd,
+        contractId: input.contractId,
+        patterns: input.intent === "claim" ? input.appendScope : undefined,
+        actor: input.actor,
+        nowMs: input.nowMs,
+    });
     const sealed = await sealCurrentArc({
         cwd: deliveryCwd,
         renderCwd: deliveryCwd,
         contractId: input.contractId,
         sealedBy: "petition",
         nowMs: input.nowMs,
-        waivePaths: input.intent === "claim" ? input.waivePaths : undefined,
     });
     const allocated = await allocateSettlementSeat(input.cwd, {
         target: target.ref,
@@ -146,6 +155,6 @@ export function buildPetitionClaimInput(input) {
         plea: `Settle contract ${input.contractId} through the petition pipeline.`,
         oath,
         signal: input.signal,
-        waivePaths: input.waivePaths,
+        appendScope: input.appendScope,
     };
 }

package/build/core/settlement/queue-read-model.js

@@ -0,0 +1,143 @@
+import { listContractIds, readLedger } from "../ledger.js";
+import { deriveContractState } from "../status/lifecycle.js";
+import { commissionTarget } from "../status/drift.js";
+export function isCurrentPetitionData(data) {
+    return "target" in data && "seat" in data;
+}
+function latestPetition(entries) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry.kind === "petition")
+            return entry;
+    }
+    return undefined;
+}
+export function deriveQueueReadModel(ledgers) {
+    const seatsByContract = new Map();
+    const diagnosticsByContract = new Map();
+    const orderedByTarget = new Map();
+    for (const ledger of ledgers) {
+        if (deriveContractState(ledger.entries).state !== "petitioned")
+            continue;
+        const petition = latestPetition(ledger.entries);
+        if (!petition)
+            continue;
+        const derived = commissionTarget(ledger.entries);
+        if (!derived)
+            continue;
+        const diagnostics = [];
+        let seat;
+        if (isCurrentPetitionData(petition.data)) {
+            seat = {
+                contract: ledger.contractId,
+                target: petition.data.target,
+                seat: petition.data.seat,
+                legacy: false,
+            };
+            if (petition.data.target !== derived.ref) {
+                diagnostics.push({
+                    kind: "target-mismatch",
+                    petitioned: petition.data.target,
+                    derived: derived.ref,
+                });
+            }
+            const bucket = orderedByTarget.get(petition.data.target) ?? [];
+            bucket.push(seat);
+            orderedByTarget.set(petition.data.target, bucket);
+        }
+        else {
+            seat = {
+                contract: ledger.contractId,
+                target: derived.ref,
+                seat: null,
+                legacy: true,
+            };
+            diagnostics.push({ kind: "legacy-petition" });
+        }
+        seatsByContract.set(ledger.contractId, seat);
+        diagnosticsByContract.set(ledger.contractId, diagnostics);
+    }
+    for (const [target, seats] of orderedByTarget) {
+        const bySeat = new Map();
+        for (const seat of seats) {
+            if (seat.seat === null)
+                continue;
+            const group = bySeat.get(seat.seat) ?? [];
+            group.push(seat);
+            bySeat.set(seat.seat, group);
+        }
+        for (const [seatNumber, group] of bySeat) {
+            if (group.length < 2)
+                continue;
+            const sorted = [...group].sort((a, b) => a.contract.localeCompare(b.contract));
+            for (const member of sorted) {
+                const others = sorted.filter((other) => other.contract !== member.contract);
+                const existing = diagnosticsByContract.get(member.contract) ?? [];
+                for (const other of others) {
+                    existing.push({ kind: "duplicate-seat", seat: seatNumber, with: other.contract });
+                }
+                diagnosticsByContract.set(member.contract, existing);
+            }
+        }
+        seats.sort((a, b) => {
+            const seatA = a.seat ?? Number.POSITIVE_INFINITY;
+            const seatB = b.seat ?? Number.POSITIVE_INFINITY;
+            if (seatA !== seatB)
+                return seatA - seatB;
+            return a.contract.localeCompare(b.contract);
+        });
+        orderedByTarget.set(target, seats);
+    }
+    const targetQueues = [...orderedByTarget.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([target, ordered]) => ({ target, ordered }));
+    return {
+        targetQueues,
+        seatsByContract,
+        diagnosticsByContract,
+    };
+}
+export async function readQueueReadModel(cwd) {
+    const contractIds = await listContractIds(cwd);
+    const ledgers = [];
+    for (const id of contractIds) {
+        const ledger = await readLedger(cwd, id);
+        if (ledger)
+            ledgers.push(ledger);
+    }
+    return deriveQueueReadModel(ledgers);
+}
+export function queueMembership(model, contractId) {
+    const seat = model.seatsByContract.get(contractId);
+    if (!seat)
+        return undefined;
+    const diagnostics = model.diagnosticsByContract.get(contractId) ?? [];
+    if (seat.legacy) {
+        return {
+            seat,
+            position: null,
+            queueLength: 0,
+            queueHead: null,
+            diagnostics,
+        };
+    }
+    const targetQueue = model.targetQueues.find((queue) => queue.target === seat.target);
+    if (!targetQueue) {
+        return {
+            seat,
+            position: null,
+            queueLength: 0,
+            queueHead: null,
+            diagnostics,
+        };
+    }
+    const index = targetQueue.ordered.findIndex((entry) => entry.contract === contractId);
+    const position = index < 0 ? null : index + 1;
+    return {
+        seat,
+        position,
+        queueLength: targetQueue.ordered.length,
+        queueHead: targetQueue.ordered[0]?.contract ?? null,
+        diagnostics,
+    };
+}

package/build/core/settlement/queue-seat-allocation.js

@@ -0,0 +1,156 @@
+import { createHash } from "node:crypto";
+import { FlowError } from "../../flow-error.js";
+import { listContractIds, readLedger } from "../ledger.js";
+import { casUpdateRefLog, createRefLogCommit, listRefLogCommits, readRefLogCommitMessage, resolveRefLogHead, } from "../ref-log.js";
+import { isCurrentPetitionData, queueMembership, } from "./queue-read-model.js";
+const ISO_UTC_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+function isPositiveSafeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+export function assertClaimQueueHead(model, contractId) {
+    const membership = queueMembership(model, contractId);
+    if (!membership) {
+        throw new FlowError("INTERNAL_STATE", `contract ${contractId} is not queue head; position=not queued`);
+    }
+    if (membership.seat.legacy) {
+        throw new FlowError("QUEUE_LEGACY_PETITION", `contract ${contractId} petitioned before seat law took effect; reject its petition and petition again`);
+    }
+    const mismatch = membership.diagnostics.find((diagnostic) => diagnostic.kind === "target-mismatch");
+    if (mismatch && mismatch.kind === "target-mismatch") {
+        throw new FlowError("QUEUE_TARGET_MISMATCH", `contract ${contractId} petition target ${mismatch.petitioned} disagrees with derived target ${mismatch.derived}; reject its petition and petition again`);
+    }
+    if (membership.position !== 1) {
+        throw new FlowError("INTERNAL_STATE", `contract ${contractId} is not queue head; position=${membership.position ?? "not queued"}`);
+    }
+    return membership;
+}
+export function seatAllocatorRef(target) {
+    const digest = createHash("sha256").update(target, "utf8").digest("hex");
+    return `refs/keiyaku/seat/${digest}`;
+}
+function parseSeatAllocatorMessage(message, expectedTarget) {
+    const normalized = message.replace(/\r\n/g, "\n");
+    const separatorIndex = normalized.indexOf("\n\n");
+    if (separatorIndex < 0)
+        throw new Error("missing blank line");
+    const subject = normalized.slice(0, separatorIndex).trim();
+    const body = normalized.slice(separatorIndex + 2).trim();
+    const parsed = JSON.parse(body);
+    const keys = Object.keys(parsed).sort();
+    if (keys.join(",") !== "actor,at,seat,target,v")
+        throw new Error("unexpected fields");
+    if (parsed.v !== 1)
+        throw new Error("bad version");
+    if (typeof parsed.target !== "string" || parsed.target !== expectedTarget)
+        throw new Error("target mismatch");
+    if (!isPositiveSafeInteger(parsed.seat))
+        throw new Error("bad seat");
+    if (typeof parsed.at !== "string" || !ISO_UTC_RE.test(parsed.at))
+        throw new Error("bad at");
+    if (typeof parsed.actor !== "string" || parsed.actor.trim().length === 0)
+        throw new Error("bad actor");
+    if (subject !== `keiyaku seat: ${parsed.seat}`)
+        throw new Error("bad subject");
+    return {
+        v: 1,
+        target: parsed.target,
+        seat: parsed.seat,
+        at: parsed.at,
+        actor: parsed.actor,
+    };
+}
+async function parseAllocatorChain(cwd, head, expectedTarget) {
+    // Intentional degrade: any rev-list or parse failure treats the chain as corrupt.
+    let commits;
+    try {
+        commits = await listRefLogCommits(cwd, head);
+    }
+    catch {
+        return null;
+    }
+    if (commits.length === 0)
+        return null;
+    const entries = [];
+    let previousSeat = 0;
+    for (const commit of commits) {
+        try {
+            const entry = parseSeatAllocatorMessage(await readRefLogCommitMessage(cwd, commit), expectedTarget);
+            if (entry.seat <= previousSeat)
+                return null;
+            previousSeat = entry.seat;
+            entries.push(entry);
+        }
+        catch {
+            return null;
+        }
+    }
+    return { entries, lastSeat: previousSeat };
+}
+async function ledgerSeatFloor(cwd, target) {
+    const contractIds = await listContractIds(cwd);
+    let maxSeat = 0;
+    for (const id of contractIds) {
+        const ledger = await readLedger(cwd, id);
+        if (!ledger)
+            continue;
+        for (const entry of ledger.entries) {
+            if (entry.kind !== "petition")
+                continue;
+            if (!isCurrentPetitionData(entry.data))
+                continue;
+            if (entry.data.target !== target)
+                continue;
+            if (entry.data.seat > maxSeat)
+                maxSeat = entry.data.seat;
+        }
+    }
+    return maxSeat;
+}
+export async function allocateSettlementSeat(cwd, input) {
+    const ref = seatAllocatorRef(input.target);
+    const maxRetries = 3;
+    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+        // Raw observed-head read: any object id, not commit-only.
+        // Non-commit heads are returned so parseAllocatorChain can classify them as corrupt.
+        const observedHead = await resolveRefLogHead(cwd, ref, { peel: "object" });
+        const floor = await ledgerSeatFloor(cwd, input.target);
+        const parsed = observedHead ? await parseAllocatorChain(cwd, observedHead, input.target) : null;
+        const healthy = parsed !== null && parsed.lastSeat >= floor;
+        let seat;
+        let parent;
+        let expectedOld;
+        if (healthy && parsed) {
+            seat = parsed.lastSeat + 1;
+            parent = observedHead;
+            expectedOld = observedHead;
+        }
+        else {
+            // Missing, parse failure, target mismatch, non-monotonic, or stale-behind-ledger:
+            // mint a detached no-parent root at floor+1. Leave the bad chain for Git GC.
+            seat = floor + 1;
+            parent = null;
+            expectedOld = observedHead;
+        }
+        if (!isPositiveSafeInteger(seat)) {
+            throw new FlowError("INTERNAL_STATE", `settlement seats exhausted for ${input.target}`);
+        }
+        const entry = {
+            v: 1,
+            target: input.target,
+            seat,
+            at: input.at,
+            actor: input.actor,
+        };
+        const newHead = await createRefLogCommit(cwd, {
+            subject: `keiyaku seat: ${entry.seat}`,
+            body: JSON.stringify(entry, null, 2),
+            parentHead: parent,
+            errorLabel: `seat ${entry.seat}`,
+        });
+        // Intentional degrade: CAS failure returns false; bounded retry re-reads head.
+        const casOk = await casUpdateRefLog(cwd, ref, newHead, expectedOld);
+        if (casOk)
+            return { head: newHead, seat };
+    }
+    throw new FlowError("INTERNAL_STATE", `failed to allocate settlement seat for ${input.target}`);
+}

package/build/core/settlement/queue.js

@@ -0,0 +1,6 @@
+/**
+ * Settlement queue surface: read-model derivation/query and seat allocation/assertion.
+ * Implementation lives in sibling files; this module preserves the historical import path.
+ */
+export { deriveQueueReadModel, queueMembership, readQueueReadModel, } from "./queue-read-model.js";
+export { allocateSettlementSeat, assertClaimQueueHead, seatAllocatorRef, } from "./queue-seat-allocation.js";