@astrosheep/keiyaku 1.0.0 → 1.0.2

package/build/core/claim.js

@@ -1,12 +1,12 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { FlowError } from "../flow-error.js";
-import { createGit, wrapGitError } from "../git/core.js";
+import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, wrapGitError } from "../git/core.js";
 import { activeLedgerRef, appendWithRetry, readLedger } from "./ledger.js";
-import { dequeueContract, queuePositionFromEntries, queuedContracts, readQueue } from "./queue.js";
+import { assertClaimQueueHead, readQueueReadModel } from "./queue_v2.js";
 import { releaseScope } from "./registry.js";
 import { shortCommitHash } from "./render.js";
-import { deriveContractState, latestBase, resolveDefaultBranch } from "./status.js";
+import { commissionTarget, deriveContractState, latestBase } from "./status.js";
 import { cleanupContractWorkspace, findContractWorktreePath, stableRepoRoot } from "./worktree-path.js";
 const CLAIM_RECEIPTS_FILE = "claim-receipts.jsonl";
 async function appendClaimReceipt(cwd, receipt) {
@@ -44,6 +44,17 @@ async function resolveCommit(cwd, rev) {
         throw wrapGitError(`rev-parse ${rev}`, error, cwd);
     }
 }
+async function resolveCommitOrNull(cwd, rev) {
+    const git = createGit(cwd);
+    try {
+        return (await git.raw(["rev-parse", "--verify", `${rev}^{commit}`])).trim();
+    }
+    catch (error) {
+        if (errorContainsAnyPattern(error, MISSING_HEAD_PATTERNS))
+            return null;
+        throw wrapGitError(`rev-parse ${rev}`, error, cwd);
+    }
+}
 async function isAncestor(cwd, ancestor, descendant) {
     const git = createGit(cwd);
     try {
@@ -174,21 +185,30 @@ async function reconcileAfterCas(input) {
     }
 }
 async function defaultMergeDelivery(input) {
-    const target = await resolveDefaultBranch(input.cwd);
-    if (!target)
-        throw new FlowError("INTERNAL_STATE", `cannot claim ${input.contractId}: no default branch`);
+    const ledger = await readLedger(input.cwd, input.contractId);
+    if (!ledger) {
+        throw new FlowError("INTERNAL_STATE", `cannot claim ${input.contractId}: ledger missing`);
+    }
+    const commission = commissionTarget(ledger.entries);
+    if (!commission) {
+        throw new FlowError("INTERNAL_STATE", `cannot claim ${input.contractId}: missing commission target`);
+    }
+    const targetHead = await resolveCommitOrNull(input.cwd, commission.ref);
+    if (!targetHead) {
+        throw new FlowError("INTERNAL_STATE", `cannot claim ${input.contractId}: commission target ${commission.ref} does not resolve`);
+    }
     const branch = `keiyaku/${input.contractId}`;
     const deliveryHead = await resolveCommit(input.cwd, branch);
-    if (deliveryHead !== target.head && await isAncestor(input.cwd, deliveryHead, target.head)) {
-        return { mergeCommit: target.head };
+    if (deliveryHead !== targetHead && await isAncestor(input.cwd, deliveryHead, targetHead)) {
+        return { mergeCommit: targetHead };
     }
     const git = createGit(input.cwd);
     let tree;
     try {
-        tree = (await git.raw(["merge-tree", "--write-tree", target.head, deliveryHead])).trim();
+        tree = (await git.raw(["merge-tree", "--write-tree", targetHead, deliveryHead])).trim();
     }
     catch (error) {
-        throw new FlowError("CLOSE_MERGE_CONFLICT", `claim merge conflict for ${input.contractId} into ${target.branch}`, { cause: error });
+        throw new FlowError("CLOSE_MERGE_CONFLICT", `claim merge conflict for ${input.contractId} into ${commission.branch}`, { cause: error });
     }
     let mergeCommit;
     try {
@@ -196,13 +216,13 @@ async function defaultMergeDelivery(input) {
             "commit-tree",
             tree,
             "-p",
-            target.head,
+            targetHead,
             "-p",
             deliveryHead,
             "-m",
             `keiyaku: claim ${input.contractId}`,
             "-m",
-            `Merge contract ${input.contractId} into ${target.branch}.`,
+            `Merge contract ${input.contractId} into ${commission.branch}.`,
         ])).trim();
     }
     catch (error) {
@@ -211,26 +231,26 @@ async function defaultMergeDelivery(input) {
     // Pre-CAS: locate target worktree and snapshot real blockers while HEAD/index still share oldHead.
     const preCasSnapshot = await snapshotPreCasBlockers({
         cwd: input.cwd,
-        targetBranch: target.branch,
-        oldHead: target.head,
+        targetBranch: commission.branch,
+        oldHead: targetHead,
         mergeCommit,
     });
     try {
-        await git.raw(["update-ref", `refs/heads/${target.branch}`, mergeCommit, target.head]);
+        await git.raw(["update-ref", commission.ref, mergeCommit, targetHead]);
     }
     catch (error) {
-        const currentHead = await resolveCommit(input.cwd, target.branch);
+        const currentHead = await resolveCommit(input.cwd, commission.ref);
         if (await isAncestor(input.cwd, deliveryHead, currentHead)) {
             return { mergeCommit: currentHead };
         }
-        throw new FlowError("CONCURRENT_MODIFICATION", `target branch ${target.branch} moved while claiming ${input.contractId}`, { cause: error });
+        throw new FlowError("CONCURRENT_MODIFICATION", `target branch ${commission.branch} moved while claiming ${input.contractId}`, { cause: error });
     }
     // The target ref is authoritative. Receipt failure cannot undo its CAS.
     const receiptWarnings = [];
     try {
         await (input.writeClaimReceipt ?? appendClaimReceipt)(input.cwd, {
             kind: "receipt",
-            oldHead: target.head,
+            oldHead: targetHead,
             newHead: mergeCommit,
             contract: input.contractId,
         });
@@ -240,8 +260,8 @@ async function defaultMergeDelivery(input) {
     }
     const warnings = await reconcileAfterCas({
         contractId: input.contractId,
-        targetBranch: target.branch,
-        oldHead: target.head,
+        targetBranch: commission.branch,
+        oldHead: targetHead,
         mergeCommit,
         snapshot: preCasSnapshot,
     });
@@ -260,33 +280,29 @@ function assertClaimableFromLedger(contractId, ledger) {
     if (claim && state.state === "claimed")
         return claim;
     if (state.state === "forfeited") {
-        throw new FlowError("INTERNAL_STATE", `contract ${contractId} forfeited; run forfeit to clear queue`);
+        throw new FlowError("INTERNAL_STATE", `contract ${contractId} forfeited`);
     }
     throw new FlowError("INTERNAL_STATE", `contract ${contractId} cannot claim from state ${state.state}`);
 }
-async function assertQueueHead(cwd, contractId) {
-    const entries = await readQueue(cwd);
-    const position = queuePositionFromEntries(entries, contractId);
-    if (position !== 1) {
-        throw new FlowError("INTERNAL_STATE", `contract ${contractId} is not queue head; position=${position ?? "not queued"}`);
-    }
-}
 export async function previewClaimContract(input) {
-    const queueEntries = await readQueue(input.cwd);
-    const queued = queuedContracts(queueEntries);
-    const position = queuePositionFromEntries(queueEntries, input.contractId);
-    if (position !== 1) {
-        throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} is not queue head; position=${position ?? "not queued"}`);
-    }
+    const model = await readQueueReadModel(input.cwd);
+    const membership = assertClaimQueueHead(model, input.contractId);
     const ledger = await readLedger(input.cwd, input.contractId);
     assertClaimableFromLedger(input.contractId, ledger);
     const entries = ledger.entries;
     const cleanupPath = await findContractWorktreePath(input.cwd, input.contractId);
     const state = deriveContractState(entries);
     const base = latestBase(entries);
-    const target = await resolveDefaultBranch(input.cwd);
-    const freshness = base && target
-        ? base === target.head ? "fresh" : "stale"
+    const commission = commissionTarget(entries);
+    if (!commission) {
+        throw new FlowError("INTERNAL_STATE", `cannot preview claim ${input.contractId}: missing commission target`);
+    }
+    const targetHead = await resolveCommitOrNull(input.cwd, commission.ref);
+    if (!targetHead) {
+        throw new FlowError("INTERNAL_STATE", `cannot preview claim ${input.contractId}: commission target ${commission.ref} does not resolve`);
+    }
+    const freshness = base
+        ? base === targetHead ? "fresh" : "stale"
         : "unknown";
     const deliveryBranch = `keiyaku/${input.contractId}`;
     let deliveryHead;
@@ -298,16 +314,16 @@ export async function previewClaimContract(input) {
     }
     return {
         contractId: input.contractId,
-        queueHead: queued[0],
-        queuePosition: position,
+        queueHead: membership.queueHead,
+        queuePosition: membership.position,
         state: state.state,
         freshness,
         ...(base ? { base } : {}),
-        ...(target ? { targetBranch: target.branch, targetHead: target.head } : {}),
+        targetBranch: commission.branch,
+        targetHead,
         deliveryBranch,
         ...(deliveryHead ? { deliveryHead } : {}),
         cleanupEffects: [
-            `remove ${input.contractId} from queue`,
             `release registry scope for ${input.contractId}`,
             cleanupPath ? `remove worktree ${path.relative(input.cwd, cleanupPath) || "."} when present` : "no linked worktree to remove",
             `delete branch keiyaku/${input.contractId} when present`,
@@ -316,9 +332,21 @@ export async function previewClaimContract(input) {
 }
 export async function claimContract(input) {
     const at = new Date(input.nowMs).toISOString();
-    await assertQueueHead(input.cwd, input.contractId);
     const existing = await readLedger(input.cwd, input.contractId);
     const existingClaim = assertClaimableFromLedger(input.contractId, existing);
+    const existingState = existing ? deriveContractState(existing.entries) : undefined;
+    // Already-claimed retry: skip queue-head gating and merge; finish cleanup.
+    if (existingClaim && existingState?.state === "claimed") {
+        const cleanup = await cleanupClaim(input.cwd, input.contractId, input.actor, at);
+        return {
+            contractId: input.contractId,
+            mergeCommit: existingClaim.data.mergeCommit,
+            cleanup,
+        };
+    }
+    // Still petitioned: prove target-local head before merge.
+    const model = await readQueueReadModel(input.cwd);
+    assertClaimQueueHead(model, input.contractId);
     let mergeCommit = existingClaim?.data.mergeCommit;
     let warnings;
     if (!mergeCommit) {
@@ -349,11 +377,11 @@ export async function claimContract(input) {
             throw new FlowError("INTERNAL_STATE", `failed to append claim for ${input.contractId}: ${result.reason}`);
         }
     }
-    await dequeueContract(input.cwd, { contractId: input.contractId, actor: input.actor, at });
+    // Claim entry naturally removes membership; no dequeue record.
     const cleanup = await cleanupClaim(input.cwd, input.contractId, input.actor, at);
     return {
         contractId: input.contractId,
-        mergeCommit,
+        mergeCommit: mergeCommit,
         cleanup,
         ...(warnings && warnings.length > 0 ? { warnings } : {}),
     };

package/build/core/command-io.js

@@ -3,6 +3,7 @@ import { FlowError } from "../flow-error.js";
 import { parseMarkdownListSection, parseMarkdownStructure } from "./markdown/sections.js";
 import { KeiyakuParseError } from "./markdown/types.js";
 import { normalizeSectionTitle } from "./markdown/titles.js";
+import { isBlankScopePatternLine, normalizeScopePattern, ScopePatternError } from "./scope.js";
 function amendScopeHeading(name) {
     return `## Scope ${name[0].toUpperCase()}${name.slice(1)}`;
 }
@@ -29,8 +30,6 @@ function amendHeading(line) {
         return { level };
     if (title === "scope add")
         return { level, name: "add" };
-    if (title === "scope remove")
-        return { level, name: "remove" };
     return { level };
 }
 function amendFence(line) {
@@ -97,28 +96,36 @@ function scopePatterns(markdown, section) {
     const patterns = markdown
         .slice(section.contentStart, section.end)
         .split(/\r?\n/)
-        .map((line) => line.trim())
-        .filter(Boolean);
+        .filter((line) => !isBlankScopePatternLine(line))
+        .map((pattern) => {
+        try {
+            // Do not trim() here: gitignore treats trailing `\ ` as a significant space.
+            return normalizeScopePattern(pattern);
+        }
+        catch (error) {
+            if (error instanceof ScopePatternError) {
+                throw new FlowError("INVALID_KEIYAKU_DRAFT", error.message);
+            }
+            throw error;
+        }
+    });
     if (patterns.length === 0) {
         throw new FlowError("INVALID_KEIYAKU_DRAFT", `amend input has an empty ${amendScopeHeading(section.name)} section`);
     }
-    return [...new Set(patterns)];
+    return patterns;
 }
-export function buildAmendInput(markdown, cwd) {
+export function buildAmendInput(markdown, cwd, contractId, contractAddressSource) {
     const { sections, prose } = parseAmendScopeSections(markdown);
     const add = sections.add ? scopePatterns(markdown, sections.add) : [];
-    const remove = sections.remove ? scopePatterns(markdown, sections.remove) : [];
-    const conflict = add.find((pattern) => remove.includes(pattern));
-    if (conflict) {
-        throw new FlowError("INVALID_KEIYAKU_DRAFT", `amend scope pattern appears in both ${amendScopeHeading("add")} and ${amendScopeHeading("remove")}: ${conflict}`);
-    }
     if (!prose.trim()) {
         throw new FlowError("EMPTY_PARAM", "amendment cannot be empty");
     }
     return {
         cwd,
+        ...(contractId ? { contractId } : {}),
+        ...(contractAddressSource ? { contractAddressSource } : {}),
         amendment: prose,
-        ...(sections.add || sections.remove ? { scopeDelta: { add, remove } } : {}),
+        ...(sections.add ? { scopeDelta: { add } } : {}),
     };
 }
 export function defaultActorClock(nowMs = Date.now()) {
@@ -165,10 +172,3 @@ export function requireMarkdownTitle(parts) {
     }
     return title;
 }
-export function assertKnownMarkdownSections(parts, command, allowed) {
-    const allowedSet = new Set(allowed.map(normalizeSectionTitle));
-    const unknown = [...parts.sections.keys()].filter((section) => !allowedSet.has(section));
-    if (unknown.length > 0) {
-        throw new FlowError("INVALID_KEIYAKU_DRAFT", `${command} input has unknown section header(s): ${unknown.map((section) => `'${section}'`).join(", ")}`);
-    }
-}

package/build/core/context.js

@@ -4,16 +4,20 @@ import { FlowError } from "../flow-error.js";
 import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, wrapGitError } from "../git/core.js";
 import { getCurrentBranch, listLocalBranches } from "../git/branches.js";
 import { readLedger } from "./ledger.js";
-import { deriveContractState, isTerminalState, latestBase, listContractIds, resolveDefaultBranch } from "./status.js";
+import { listContractIds } from "./ledger.js";
+import { deriveContractState, isTerminalState, latestBase } from "./status.js";
 import { activeContractIdForWorktreeDir } from "./worktree-path.js";
-async function operableContractIds(cwd) {
+function isOperableLedger(entries) {
+    const state = deriveContractState(entries);
+    return state.state !== "corrupt" && !isTerminalState(state);
+}
+export async function operableContractIds(cwd) {
     const ids = await listContractIds(cwd);
     const ledgers = await Promise.all(ids.map(async (id) => ({ id, ledger: await readLedger(cwd, id) })));
     return ledgers.flatMap(({ id, ledger }) => {
         if (!ledger)
             return [];
-        const state = deriveContractState(ledger.entries);
-        return state.state !== "corrupt" && !isTerminalState(state) ? [id] : [];
+        return isOperableLedger(ledger.entries) ? [id] : [];
     });
 }
 async function isOperableContract(cwd, contractId) {
@@ -64,11 +68,12 @@ export async function readCurrentContractContext(cwd) {
         throw new FlowError("INTERNAL_STATE", `contract ${contractId} not found or not active`);
     }
     const base = latestBase(ledger.entries);
-    if (!base) {
+    const bind = ledger.entries.find((entry) => entry.kind === "bind");
+    if (!base || !bind) {
         throw new FlowError("INTERNAL_STATE", `contract ${contractId} active ledger is missing bind entry`);
     }
     const currentBranch = await getCurrentBranch(cwd);
-    const baseBranch = (await resolveDefaultBranch(cwd))?.branch ?? currentBranch;
+    const baseBranch = bind.data.target.slice("refs/heads/".length);
     return {
         contractId,
         currentBranch,
@@ -76,33 +81,3 @@ export async function readCurrentContractContext(cwd) {
         base,
     };
 }
-function normalizeAddressQuery(raw) {
-    const value = raw.startsWith("@") ? raw.slice(1) : raw;
-    if (!value.trim()) {
-        throw new FlowError("EMPTY_PARAM", "contract address cannot be empty");
-    }
-    return value.trim();
-}
-export async function resolveContractAddress(cwd, raw) {
-    if (!raw) {
-        const current = await resolveImplicitCurrentContractId(cwd);
-        if (current)
-            return current;
-        const operable = await operableContractIds(cwd);
-        if (operable.length === 1)
-            return operable[0];
-        throw new FlowError("EMPTY_PARAM", operable.length === 0
-            ? "no active contract found; pass @<id>"
-            : "multiple active contracts found; pass @<id>");
-    }
-    const query = normalizeAddressQuery(raw);
-    const ids = await listContractIds(cwd);
-    if (ids.includes(query))
-        return query;
-    const matches = ids.filter((id) => id.startsWith(query));
-    if (matches.length === 1)
-        return matches[0];
-    if (matches.length === 0)
-        throw new FlowError("EMPTY_PARAM", `unknown contract address @${query}`);
-    throw new FlowError("EMPTY_PARAM", `ambiguous contract address @${query}: ${matches.join(", ")}`);
-}

package/build/core/draft.js

@@ -41,9 +41,8 @@ export function parseBindDraft(content) {
         if (node.level !== 2)
             continue;
         const normalized = normalizeSectionName(node.title);
-        if (!KNOWN_SECTIONS.has(normalized)) {
-            invalidBindDraft(`unknown section '${node.title}' in bind draft`);
-        }
+        if (!KNOWN_SECTIONS.has(normalized))
+            continue;
         if (sections.has(normalized)) {
             invalidBindDraft(`duplicate section '${node.title}' in bind draft`);
         }

package/build/core/entry.js

@@ -2,12 +2,17 @@ import { z } from "zod";
 const SHA_RE = /^[0-9a-f]{7,40}$/i;
 const ISO_UTC_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
 const CONTRACT_ID_RE = /^\S+$/;
-const SUBJECT_RE = /^keiyaku: (bind|arc|seal|amend|renew|petition|verdict|claim|forfeit) ([^\s]+)$/;
+const SUBJECT_RE = /^keiyaku: (bind|arc|seal|amend|renew|petition|verdict|claim|forfeit|bootstrap) ([^\s]+)$/;
 const shaSchema = z.string().regex(SHA_RE, "expected git sha");
 const isoUtcSchema = z.string().regex(ISO_UTC_RE, "expected ISO 8601 UTC timestamp");
 const nonEmptyString = z.string().trim().min(1);
 const nonBlankString = z.string().refine((value) => value.trim().length > 0, "expected non-empty string");
-const placeSchema = z.string().regex(/^[a-z]{3,12}$/);
+// Scope patterns are gitignore text: do not trim, or escaped trailing spaces (`foo\ `) are destroyed.
+const scopePatternString = z
+    .string()
+    .refine((value) => value.trim().length > 0, "expected non-empty scope pattern");
+// Catalog base (2-13 lowercase letters) or generation overflow base2, base3, ...
+const placeSchema = z.string().regex(/^[a-z]{2,13}(?:[2-9]|[1-9][0-9]+)?$/);
 export const entryKindSchema = z.enum([
     "bind",
     "arc",
@@ -18,6 +23,7 @@ export const entryKindSchema = z.enum([
     "verdict",
     "claim",
     "forfeit",
+    "bootstrap",
 ]);
 const diffstatSchema = z
     .object({
@@ -32,15 +38,67 @@ const scopeAuditSchema = z
     waived: z.boolean(),
 })
     .strict();
+export const fullBranchRefSchema = z
+    .string()
+    .regex(/^refs\/heads\/\S+$/, "expected full branch ref");
+export const bindBootstrapPlanSchema = z
+    .object({
+    command: z.array(nonEmptyString).min(1),
+    timeoutMs: z.number().int().min(1).max(3_600_000),
+})
+    .strict();
 export const bindEntryDataSchema = z
     .object({
     name: nonEmptyString,
     objective: nonEmptyString,
-    scope: z.array(nonEmptyString).min(1),
+    scope: z.array(scopePatternString).min(1),
     base: shaSchema,
+    target: fullBranchRefSchema,
     workspace: z.enum(["worktree", "here"]),
     after: z.array(nonEmptyString).optional(),
     place: placeSchema.nullable().optional(),
+    bootstrap: bindBootstrapPlanSchema.optional(),
+})
+    .strict();
+const bootstrapExitResultSchema = z
+    .object({
+    kind: z.literal("exit"),
+    code: z.number().int().min(0).max(255),
+})
+    .strict();
+const bootstrapSignalResultSchema = z
+    .object({
+    kind: z.literal("signal"),
+    signal: z.string().min(1),
+})
+    .strict();
+const bootstrapTimeoutResultSchema = z
+    .object({
+    kind: z.literal("timeout"),
+})
+    .strict();
+const bootstrapSpawnResultSchema = z
+    .object({
+    kind: z.literal("spawn"),
+    message: z.string(),
+})
+    .strict();
+export const bootstrapResultSchema = z.discriminatedUnion("kind", [
+    bootstrapExitResultSchema,
+    bootstrapSignalResultSchema,
+    bootstrapTimeoutResultSchema,
+    bootstrapSpawnResultSchema,
+]);
+export const bootstrapEntryDataSchema = z
+    .object({
+    result: bootstrapResultSchema,
+    durationMs: z
+        .number()
+        .int()
+        .nonnegative()
+        .refine((value) => Number.isSafeInteger(value), "durationMs must be a safe integer"),
+    stderrTail: z.string().optional(),
+    stderrTruncated: z.boolean().optional(),
 })
     .strict();
 export const arcEntryDataSchema = z
@@ -67,8 +125,7 @@ export const amendEntryDataSchema = z
     amendment: nonBlankString,
     scopeDelta: z
         .object({
-        add: z.array(nonEmptyString),
-        remove: z.array(nonEmptyString),
+        add: z.array(scopePatternString),
     })
         .strict()
         .optional(),
@@ -82,7 +139,29 @@ export const renewEntryDataSchema = z
     newHead: shaSchema,
 })
     .strict();
-export const petitionEntryDataSchema = z.discriminatedUnion("intent", [
+const positiveSafeSeatSchema = z
+    .number()
+    .int()
+    .positive()
+    .refine((value) => Number.isSafeInteger(value), "seat must be a positive safe integer");
+// Current petitions always carry target + seat. Legacy residuals omit both and
+// exist only for diagnostic/rejection paths — never for production writers.
+export const petitionEntryDataSchema = z.union([
+    z
+        .object({
+        intent: z.literal("claim"),
+        oath: nonEmptyString,
+        target: fullBranchRefSchema,
+        seat: positiveSafeSeatSchema,
+    })
+        .strict(),
+    z
+        .object({
+        intent: z.literal("forfeit"),
+        target: fullBranchRefSchema,
+        seat: positiveSafeSeatSchema,
+    })
+        .strict(),
     z
         .object({
         intent: z.literal("claim"),
@@ -134,6 +213,7 @@ export const petitionEntrySchema = makeEntrySchema("petition", petitionEntryData
 export const verdictEntrySchema = makeEntrySchema("verdict", verdictEntryDataSchema);
 export const claimEntrySchema = makeEntrySchema("claim", claimEntryDataSchema);
 export const forfeitEntrySchema = makeEntrySchema("forfeit", forfeitEntryDataSchema);
+export const bootstrapEntrySchema = makeEntrySchema("bootstrap", bootstrapEntryDataSchema);
 export const ledgerEntrySchema = z.discriminatedUnion("kind", [
     bindEntrySchema,
     arcEntrySchema,
@@ -144,6 +224,7 @@ export const ledgerEntrySchema = z.discriminatedUnion("kind", [
     verdictEntrySchema,
     claimEntrySchema,
     forfeitEntrySchema,
+    bootstrapEntrySchema,
 ]);
 export class LedgerEntryFormatError extends Error {
     code = "INVALID_LEDGER_ENTRY_FORMAT";
@@ -190,6 +271,20 @@ export function parseLedgerEntryCommitMessage(message) {
     catch (error) {
         throw new LedgerEntryFormatError("ledger entry JSON body is not valid JSON", { cause: error });
     }
+    if (typeof parsed === "object" && parsed !== null && Object.hasOwn(parsed, "repoId")) {
+        const { repoId: _legacyRepoId, ...current } = parsed;
+        parsed = current;
+    }
+    if (typeof parsed === "object" && parsed !== null &&
+        parsed.kind === "amend") {
+        const data = parsed.data;
+        const scopeDelta = typeof data === "object" && data !== null
+            ? data.scopeDelta
+            : undefined;
+        if (typeof scopeDelta === "object" && scopeDelta !== null && Object.hasOwn(scopeDelta, "remove")) {
+            throw new LedgerEntrySchemaError("ledger entry schema validation failed: scopeDelta.remove is obsolete; ledger row is corrupt");
+        }
+    }
     const result = ledgerEntrySchema.safeParse(parsed);
     if (!result.success) {
         throw new LedgerEntrySchemaError(`ledger entry schema validation failed: ${result.error.message}`, {

package/build/core/execution-coordinate.js

@@ -0,0 +1,62 @@
+import { isCommissionId } from "./ids.js";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function assertExactFields(value, required, optional, prefix, invalid) {
+    for (const field of required) {
+        if (!(field in value))
+            throw invalid(prefix ? `${prefix}.${field}` : field, "is missing");
+    }
+    const allowed = new Set([...required, ...optional]);
+    const unknown = Object.keys(value).filter((field) => !allowed.has(field)).sort()[0];
+    if (unknown !== undefined)
+        throw invalid(prefix ? `${prefix}.${unknown}` : unknown, "is unknown");
+}
+function requireNonBlank(value, field, invalid) {
+    if (typeof value !== "string" || value.trim() === "")
+        throw invalid(field, "must be a non-blank string");
+}
+export function parseExecutionAuthority(value, invalid) {
+    if (!isRecord(value))
+        throw invalid("authority", "must be an object");
+    if (!("kind" in value))
+        throw invalid("authority.kind", "is missing");
+    if (value.kind === "repository") {
+        // repoId is the sole legacy coordinate field accepted on read. It is inert
+        // and deliberately discarded; current writers emit the unit variant.
+        assertExactFields(value, ["kind"], ["repoId"], "authority", invalid);
+        return { kind: "repository" };
+    }
+    if (value.kind === "user") {
+        assertExactFields(value, ["kind"], [], "authority", invalid);
+        return { kind: "user" };
+    }
+    throw invalid("authority.kind", "must be 'repository' or 'user'");
+}
+export function parseExecutionBinding(value, invalid) {
+    if (!isRecord(value))
+        throw invalid("binding", "must be an object");
+    if (!("kind" in value))
+        throw invalid("binding.kind", "is missing");
+    if (value.kind === "commission") {
+        assertExactFields(value, ["kind", "commissionId"], [], "binding", invalid);
+        requireNonBlank(value.commissionId, "binding.commissionId", invalid);
+        if (!isCommissionId(value.commissionId))
+            throw invalid("binding.commissionId", "must be a full commission ID");
+        return { kind: "commission", commissionId: value.commissionId };
+    }
+    if (value.kind === "bare" || value.kind === "unbound") {
+        assertExactFields(value, ["kind"], [], "binding", invalid);
+        return { kind: value.kind };
+    }
+    throw invalid("binding.kind", "must be 'commission', 'bare', or 'unbound'");
+}
+/** The one durable authority/binding schema used by pacts and response artifacts. */
+export function parseExecutionCoordinates(authorityValue, bindingValue, invalid) {
+    const authority = parseExecutionAuthority(authorityValue, invalid);
+    const binding = parseExecutionBinding(bindingValue, invalid);
+    if (authority.kind === "user" && binding.kind === "commission") {
+        throw invalid("binding.kind", "cannot be 'commission' when authority.kind is 'user'");
+    }
+    return { authority, binding };
+}