@astrosheep/keiyaku 2.9.2 → 2.9.4

package/build/core/context.js

@@ -1,13 +1,12 @@
-import * as path from "node:path";
 import { KEIYAKU_BRANCH_PREFIX } from "../keiyaku.js";
 import { FlowError } from "../flow-error.js";
-import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, wrapGitError } from "../git/core.js";
+import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, NOT_GIT_REPOSITORY_PATTERNS, wrapGitError } from "../git/core.js";
 import { getCurrentBranch, listLocalBranches } from "../git/branches.js";
 import { readLedger } from "./ledger.js";
 import { listContractIds } from "./ledger.js";
 import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
 import { latestBase } from "./status/drift.js";
-import { activeContractIdForWorktreeDir } from "./worktree-path.js";
+import { activeContractBoundByEngineWorktree } from "./worktree-path.js";
 function isOperableLedger(entries) {
     const state = deriveContractState(entries);
     return state.state !== "corrupt" && !isTerminalState(state);
@@ -25,6 +24,17 @@ async function isOperableContract(cwd, contractId) {
     return (await operableContractIds(cwd)).includes(contractId);
 }
 export async function resolveImplicitCurrentContractId(cwd) {
+    // Prefer the verified engine-worktree binding (same tier as existing-commission verbs).
+    try {
+        const bound = await activeContractBoundByEngineWorktree(cwd);
+        if (bound)
+            return bound;
+    }
+    catch (error) {
+        if (!errorContainsAnyPattern(error, NOT_GIT_REPOSITORY_PATTERNS))
+            throw error;
+    }
+    // Branch remains a residual signal for workspace:here checkouts without an engine worktree.
     const git = createGit(cwd);
     try {
         const branch = (await git.raw(["branch", "--show-current"])).trim();
@@ -39,10 +49,6 @@ export async function resolveImplicitCurrentContractId(cwd) {
             throw wrapGitError("branch --show-current", error, cwd);
         }
     }
-    const worktreeId = path.basename(cwd);
-    const worktreeContractId = await activeContractIdForWorktreeDir(cwd, worktreeId);
-    if (worktreeContractId)
-        return worktreeContractId;
     return undefined;
 }
 export async function resolveCurrentContractId(cwd) {

package/build/core/contract-view.js

@@ -1,4 +1,9 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { FlowError } from "../flow-error.js";
 import { shortCommitHash } from "../git/commits.js";
+import { KEIYAKU_FILE } from "../keiyaku.js";
+import { readLedger } from "./ledger.js";
 import { deriveContractState } from "./status/lifecycle.js";
 const VERB_COLUMN_WIDTH = 11;
 const TIME_COLUMN_WIDTH = 6;
@@ -208,6 +213,18 @@ export function renderVerticalLog(input) {
     }
     return renderLedgerRows(input.entries).join("\n");
 }
+/**
+ * Sole post-mutation KEIYAKU.md refresh: read the authoritative ledger at
+ * ledgerCwd, then write the projection at renderCwd. ledgerCwd and renderCwd
+ * are distinct coordinates (hub vs linked delivery worktree).
+ */
+export async function refreshContractView(input) {
+    const ledger = await readLedger(input.ledgerCwd, input.contractId);
+    if (!ledger) {
+        throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} active ledger disappeared before render`);
+    }
+    await fs.writeFile(path.join(input.renderCwd, KEIYAKU_FILE), renderContractView({ id: input.contractId, entries: ledger.entries }), "utf8");
+}
 export function renderContractView(input) {
     const bind = input.entries.find((entry) => entry.kind === "bind");
     const state = deriveContractState(input.entries);
@@ -237,13 +254,13 @@ export function renderContractView(input) {
         `place: ${bind.data.place ?? "(none)"}`,
         `after: ${(bind.data.after ?? []).join(", ") || "(none)"}`,
         "",
-        "objective:",
+        "## Objective",
         bind.data.objective,
         "",
-        "scope:",
+        "## Scope",
         ...bind.data.scope.map((pattern) => `- ${pattern}`),
         "",
-        "checks:",
+        "## Checks",
         ...bind.data.checks.map((check) => `- ${check}`),
         "",
         ...(bind.data.extensions.length > 0

package/build/core/draft.js

@@ -1,7 +1,9 @@
 import { FlowError } from "../flow-error.js";
-import { extractListItems, parseToAST, renderSectionContent } from "./markdown/parser.js";
+import { parseToAST } from "./markdown/parser.js";
+import { extractListItems, renderSectionContent } from "./markdown/render.js";
 import { normalizeScopePattern } from "./scope.js";
 const KNOWN_SECTIONS = new Set(["objective", "scope", "checks"]);
+const BIND_DRAFT_SECTION_ORDER = ["name", "objective", "scope", "checks"];
 function invalidBindDraft(message) {
     throw new FlowError("INVALID_KEIYAKU_DRAFT", `INVALID_BIND_DRAFT: ${message}`);
 }
@@ -71,7 +73,7 @@ function extractSingleLineChecks(section) {
         return trimmed;
     });
 }
-export function parseBindDraft(content) {
+function collectBindDraftNodes(content) {
     const ast = parseToAST(content);
     let name;
     let seenH1 = false;
@@ -103,6 +105,124 @@ export function parseBindDraft(content) {
             content: normalizeExtensionContent(renderSectionContent(node)),
         });
     }
+    return { ...(name === undefined ? {} : { name }), sections, extensions };
+}
+function parseScopeSection(scope) {
+    const unexpectedScopeLine = findUnexpectedListOnlyLine(scope);
+    if (unexpectedScopeLine) {
+        invalidBindDraft(`Scope must be a bullet list; found '${unexpectedScopeLine}'`);
+    }
+    const scopeItems = extractListItems(scope);
+    if (scopeItems.length === 0) {
+        invalidBindDraft("Scope must be a bullet list; found empty Scope section");
+    }
+    return scopeItems.map((item) => {
+        if (item.trim().length === 0) {
+            invalidBindDraft("empty scope pattern in bind draft");
+        }
+        return normalizeScopePattern(item);
+    });
+}
+/**
+ * Parse any subset of the bind document grammar. Absent sections stay undefined
+ * so callers can merge task defaults under stdin overrides.
+ */
+export function parsePartialBindDraft(content) {
+    if (content.trim().length === 0)
+        return {};
+    const { name, sections, extensions } = collectBindDraftNodes(content);
+    const partial = {};
+    if (name !== undefined)
+        partial.name = name;
+    const objective = sections.get("objective");
+    if (objective) {
+        const objectiveText = renderSectionContent(objective).trim();
+        if (!objectiveText)
+            invalidBindDraft("Objective section cannot be empty");
+        partial.objective = objectiveText;
+    }
+    const scope = sections.get("scope");
+    if (scope)
+        partial.scope = parseScopeSection(scope);
+    const checks = sections.get("checks");
+    if (checks)
+        partial.checks = extractSingleLineChecks(checks);
+    if (extensions.length > 0)
+        partial.extensions = extensions;
+    return partial;
+}
+export function mergeBindDraft(base, override) {
+    return {
+        ...(base.name !== undefined ? { name: base.name } : {}),
+        ...(base.objective !== undefined ? { objective: base.objective } : {}),
+        ...(base.scope !== undefined ? { scope: base.scope } : {}),
+        ...(base.checks !== undefined ? { checks: base.checks } : {}),
+        ...(base.extensions !== undefined ? { extensions: base.extensions } : {}),
+        ...(override.name !== undefined ? { name: override.name } : {}),
+        ...(override.objective !== undefined ? { objective: override.objective } : {}),
+        ...(override.scope !== undefined ? { scope: override.scope } : {}),
+        ...(override.checks !== undefined ? { checks: override.checks } : {}),
+        ...(override.extensions !== undefined ? { extensions: override.extensions } : {}),
+    };
+}
+export function missingBindDraftSections(partial) {
+    const missing = [];
+    if (partial.name === undefined || partial.name.trim().length === 0)
+        missing.push("name");
+    if (partial.objective === undefined || partial.objective.trim().length === 0)
+        missing.push("objective");
+    if (partial.scope === undefined || partial.scope.length === 0)
+        missing.push("scope");
+    if (partial.checks === undefined || partial.checks.length === 0)
+        missing.push("checks");
+    return missing;
+}
+/** Paste-ready partial markdown for only the missing required sections. */
+export function renderMissingBindSectionsTemplate(missing) {
+    const lines = [];
+    for (const section of BIND_DRAFT_SECTION_ORDER) {
+        if (!missing.includes(section))
+            continue;
+        if (section === "name") {
+            lines.push("# <name>");
+            continue;
+        }
+        if (section === "objective") {
+            lines.push("## Objective", "<what the commission should accomplish>");
+            continue;
+        }
+        if (section === "scope") {
+            lines.push("## Scope", "- <pattern>");
+            continue;
+        }
+        lines.push("## Checks", "- <verification>");
+    }
+    return lines.join("\n");
+}
+export function describeMissingBindSections(missing) {
+    if (missing.length === 0)
+        return "";
+    if (missing.length === 1)
+        return missing[0];
+    if (missing.length === 2)
+        return `${missing[0]} or ${missing[1]}`;
+    return `${missing.slice(0, -1).join(", ")}, or ${missing[missing.length - 1]}`;
+}
+export function materializeBindDraft(partial) {
+    const missing = missingBindDraftSections(partial);
+    if (missing.length > 0) {
+        invalidBindDraft(`missing ${describeMissingBindSections(missing)} in bind draft`);
+    }
+    return {
+        name: partial.name.trim(),
+        objective: partial.objective.trim(),
+        scope: partial.scope,
+        checks: partial.checks,
+        extensions: partial.extensions ?? [],
+    };
+}
+export function parseBindDraft(content) {
+    const { name, sections, extensions } = collectBindDraftNodes(content);
     if (!name) {
         invalidBindDraft("missing H1 in bind draft; expected '# <name>' followed by '## Objective', '## Scope', and '## Checks'");
     }
@@ -118,23 +238,10 @@ export function parseBindDraft(content) {
     const objectiveText = renderSectionContent(objective).trim();
     if (!objectiveText)
         invalidBindDraft("Objective section cannot be empty");
-    const unexpectedScopeLine = findUnexpectedListOnlyLine(scope);
-    if (unexpectedScopeLine) {
-        invalidBindDraft(`Scope must be a bullet list; found '${unexpectedScopeLine}'`);
-    }
-    const scopeItems = extractListItems(scope);
-    if (scopeItems.length === 0) {
-        invalidBindDraft("Scope must be a bullet list; found empty Scope section");
-    }
     return {
         name,
         objective: objectiveText,
-        scope: scopeItems.map((item) => {
-            if (item.trim().length === 0) {
-                invalidBindDraft("empty scope pattern in bind draft");
-            }
-            return normalizeScopePattern(item);
-        }),
+        scope: parseScopeSection(scope),
         checks: extractSingleLineChecks(checks),
         extensions,
     };

package/build/core/forfeit.js

@@ -1,9 +1,10 @@
 import { FlowError } from "../flow-error.js";
+import { assertCleanTrackedWorkingTree } from "../git/worktree.js";
 import { activeLedgerRef, appendWithRetry, readLedger } from "./ledger.js";
 import { releaseScope } from "./registry.js";
 import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
-import { reconcileTaskForfeit } from "./task-contract.js";
-import { cleanupContractWorkspace, stableRepoRoot } from "./worktree-path.js";
+import { reconcileTaskForfeit } from "./task/index.js";
+import { cleanupContractWorkspace, findContractWorktreePath, stableRepoRoot } from "./worktree-path.js";
 async function cleanupForfeit(cwd, contractId, actor, at) {
     const stableRoot = await stableRepoRoot(cwd);
     await releaseScope(stableRoot, { contractId, actor, at });
@@ -12,6 +13,8 @@ async function cleanupForfeit(cwd, contractId, actor, at) {
 export async function forfeitContract(input, deps = {}) {
     const at = new Date(input.nowMs).toISOString();
     const stableRoot = await stableRepoRoot(input.cwd);
+    const deliveryWorktree = await findContractWorktreePath(stableRoot, input.contractId);
+    await assertCleanTrackedWorkingTree(deliveryWorktree ?? stableRoot);
     const ledger = await readLedger(stableRoot, input.contractId);
     if (ledger) {
         const state = deriveContractState(ledger.entries);

package/build/core/hints.js

@@ -1,63 +1,6 @@
-import path from "node:path";
-import { ACTOR_IDENTITY, ACTOR_IDENTITY_PLURAL, BASE_RULES_FILE, KEIYAKU_ARTIFACT_DIRS, KEIYAKU_DRAFT_DIR, KEIYAKU_FILE, RESPONSE_HISTORY_DIR, SETTINGS_FILE, TOOL_NAMES, formatArtifactDirectories, } from "../keiyaku.js";
+import { TOOL_NAMES } from "../keiyaku.js";
 import { renderTemplate } from "../flow-error.js";
 const GUIDANCE_BRANCH_LIST_LIMIT = 3;
-const HELP_BODY_TEMPLATE = [
-    "## Workflow",
-    "`bind -> arc -> [call | amend | delivery work]* -> arc | renew | petition`",
-    "",
-    `- **\${bind}**: Create the active contract ledger and workspace files from Markdown stdin. The worktree must be clean; call it once per Keiyaku.`,
-    `- **\${arc}**: Record the delivery arc title, objective, and brief before work starts. It seals any open arc and does not run agents or mutate delivery code.`,
-    `- **\${call}**: Call a ${ACTOR_IDENTITY} for bounded work. An open arc supplies scoped context; the caller still owns review, integration, and commits.`,
-    `- **akuma ls / akuma view**: Inspect available ${ACTOR_IDENTITY_PLURAL} and their resolved provider/executable before choosing \`keiyaku call NAME\`.`,
-    "- **delivery commits**: Commit the actual code or documentation changes in git before sealing them.",
-    `- **\${renew}**: Capture receipts, update delivery onto the default branch, seal the open arc, and record the new base.`,
-    `- **\${amend}**: Update the Keiyaku when scope, rules, criteria, or intent changed.`,
-    "- **petition**: Run the gated petition -> verdict -> engine-claim settlement pipeline.",
-    "- **claim**: Engine-only tombstone; use `keiyaku petition`.",
-    "- **forfeit**: Mark an addressed contract as forfeited, optionally with `--reason TEXT`.",
-    "- **status**: Render the Kanshi board: 現世 head, arc sparkline, age, drift ▲N, and queue stall.",
-    "",
-    "## Command Boundaries",
-    `- \`\${arc}\` and \`\${renew}\` are ledger operations; they do not call agents and do not edit delivery code.`,
-    `- \`\${call}\` can run outside a Keiyaku, but an open arc gives the ${ACTOR_IDENTITY} better context.`,
-    `- \`\${call}\` starts a new session. Use \`keiyaku revive ARTIFACT_ID\` to continue a prior response artifact.`,
-    "- `akuma ls` and `akuma view <name>` are read-only inspection commands; they do not start a helper.",
-    "- `keiyaku revive` restores the agent from the response artifact; `--incognito` calls cannot be revived later.",
-    "- Premature `petition` requests are rejected; continue with `${arc}`, `${call}`, or `${renew}` until the work is verified.",
-    "",
-    "## Core Files (.keiyaku/)",
-    "Detailed configuration and protocol nuances live here.",
-    "",
-    `- **${path.posix.basename(BASE_RULES_FILE)}**: Mandatory architectural boundaries and coding standards.`,
-    "  - **Purpose**: Global rules injected into every mission.",
-    `- **${path.posix.basename(SETTINGS_FILE)}**: Local JSON configuration at \`${SETTINGS_FILE}\`.`,
-    "  - **Shape**: Supports `default` (agent name), `reviewer` (agent name), `gate` (gated commands), and `defaultBranch` (base branch override) at the top level.",
-    "  - **Use Cases**: Configure defaults, petition gates, and base branch override.",
-    "- **.env**: Local environment defaults at `.keiyaku/.env`.",
-    "  - **Format**: Standard dotenv-style `KEY=value` entries.",
-    "  - **Precedence**: Real process environment variables override `.keiyaku/.env`.",
-    "  - **Template**: Run `keiyaku dump-env` to print the full env template with defaults.",
-    "",
-    "## Rules Protocol",
-    "- **Raw Markdown**: Project rules are preserved as authored; use any valid Markdown structure.",
-    "- **No Header Flattening**: Headings stay as headings instead of being rewritten into prefixed list labels.",
-    `- **Preserve Authoring**: Formatting is kept intact aside from safe heading-level demotion when sections are rendered into \`${KEIYAKU_FILE}\`.`,
-    `- **Strict Rule**: Keep section-level structure in \`${KEIYAKU_FILE}\` intact (\`##\` headings define sections).`,
-    "",
-    "## Draft Recovery",
-    `- Failed \${bind} runs may leave timestamped drafts under \`${KEIYAKU_DRAFT_DIR}/\` for retry.`,
-    `- Reuse a saved draft by passing its path to \`\${bind}\` with \`from_draft\`.`,
-    `- \`claim\` preserves drafts; Keiyaku never stages or commits files under \`${KEIYAKU_DRAFT_DIR}/\` during arcs.`,
-    "",
-    "## Runtime Artifacts",
-    `- Response history is written under \`${RESPONSE_HISTORY_DIR}/\`; draft retries live under \`${KEIYAKU_DRAFT_DIR}/\`.`,
-    "- Add these directories to `.gitignore` if you do not want tracked artifacts blocking operations.",
-    "",
-    "## Workflow Tactics",
-    "- **Pause / Resume**: Use `status` to find active contracts and `@<id-prefix>` to address them from any terminal.",
-    "- **Delegation Markers**: Place `KEIYAKU_TODO(<instruction>)` comments when you want ${call} or ${bind} to pick up scoped follow-on work.",
-];
 const ARCHITECT_TOOL_NAMES = {
     bind: TOOL_NAMES.bind,
     arc: TOOL_NAMES.arc,
@@ -66,9 +9,6 @@ const ARCHITECT_TOOL_NAMES = {
     amend: TOOL_NAMES.amend,
     close: TOOL_NAMES.close,
 };
-function renderArchitectText(template) {
-    return template.map((line) => renderTemplate(line, ARCHITECT_TOOL_NAMES));
-}
 export function buildNoActiveKeiyakuGuidance(input) {
     const targetToolName = ARCHITECT_TOOL_NAMES[input.toolName];
     const message = `Current workspace '${input.currentBranch}' is not addressing an active Keiyaku contract.`;
@@ -92,17 +32,3 @@ export function buildNoActiveKeiyakuGuidance(input) {
         ],
     };
 }
-export function buildGuideBody(version) {
-    const body = renderArchitectText(HELP_BODY_TEMPLATE).join("\n");
-    return [`# Keiyaku Guide (v${version})`, "", body].join("\n");
-}
-export function buildDirtyWorktreeArtifactHint() {
-    return `Files under \`.keiyaku/\` are blocking the operation. Add ${formatArtifactDirectories(KEIYAKU_ARTIFACT_DIRS)} to \`.gitignore\` if you do not want those artifacts tracked.`;
-}
-export function buildVerificationFailureHints(label, stdout, stderr) {
-    return [
-        `Fix failures from '${label}', then retry CLAIM.`,
-        `stdout:\n${stdout}`,
-        `stderr:\n${stderr}`,
-    ];
-}

package/build/core/identifier-slug.js

@@ -0,0 +1,66 @@
+const SLUG_CHARACTER = /[\p{Letter}\p{Number}\p{Mark}]/u;
+const SLUG_LETTER_OR_NUMBER = /[\p{Letter}\p{Number}]/u;
+const WINDOWS_RESERVED_BASENAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/u;
+/**
+ * Leaves room in a portable 255-byte filename component for identity prefixes,
+ * collision ordinals, extensions, and temporary-write bookkeeping.
+ */
+export const IDENTIFIER_SLUG_MAX_UTF8_BYTES = 120;
+/** Reserves `-` plus every decimal digit of a safe-integer collision ordinal. */
+export const SUFFIXABLE_IDENTIFIER_SLUG_MAX_UTF8_BYTES = IDENTIFIER_SLUG_MAX_UTF8_BYTES - 17;
+export class IdentifierSlugError extends Error {
+    code = "INVALID_IDENTIFIER_SLUG";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "IdentifierSlugError";
+    }
+}
+function utf8Bytes(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+/**
+ * Normalize human text into one Unicode-safe, portable identifier slug.
+ * NFKC makes canonically and compatibly equivalent input deterministic. All
+ * non-letter/number/mark runs become one ASCII hyphen, then the result is
+ * truncated at a Unicode code-point boundary to the shared UTF-8 byte bound.
+ */
+export function normalizeIdentifierSlug(value, maxUtf8Bytes = IDENTIFIER_SLUG_MAX_UTF8_BYTES) {
+    if (!Number.isSafeInteger(maxUtf8Bytes) || maxUtf8Bytes < 1 || maxUtf8Bytes > IDENTIFIER_SLUG_MAX_UTF8_BYTES) {
+        throw new IdentifierSlugError(`slug byte bound must be from 1 through ${IDENTIFIER_SLUG_MAX_UTF8_BYTES}`);
+    }
+    let slug = "";
+    let pendingSeparator = false;
+    for (const character of value.normalize("NFKC").toLowerCase()) {
+        if (SLUG_CHARACTER.test(character)) {
+            const addition = `${pendingSeparator && slug ? "-" : ""}${character}`;
+            if (utf8Bytes(slug) + utf8Bytes(addition) > maxUtf8Bytes)
+                break;
+            slug += addition;
+            pendingSeparator = false;
+        }
+        else if (slug) {
+            pendingSeparator = true;
+        }
+    }
+    if (!slug || !SLUG_LETTER_OR_NUMBER.test(slug)) {
+        throw new IdentifierSlugError("text cannot be converted to a portable identifier slug; use at least one Unicode letter or number");
+    }
+    if (WINDOWS_RESERVED_BASENAME.test(slug)) {
+        const portable = `${slug}-id`;
+        if (utf8Bytes(portable) > maxUtf8Bytes) {
+            throw new IdentifierSlugError("text normalizes to a reserved Windows filename within the configured byte bound");
+        }
+        return portable;
+    }
+    return slug;
+}
+export function isNormalizedIdentifierSlug(value) {
+    if (!value || utf8Bytes(value) > IDENTIFIER_SLUG_MAX_UTF8_BYTES)
+        return false;
+    try {
+        return normalizeIdentifierSlug(value) === value;
+    }
+    catch {
+        return false;
+    }
+}

package/build/core/ids.js

@@ -1,11 +1,13 @@
 import { createGit, wrapGitError } from "../git/core.js";
+import { IdentifierSlugError, isNormalizedIdentifierSlug, normalizeIdentifierSlug, } from "./identifier-slug.js";
 const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
 const ULID_RE = /^[0-9A-HJKMNP-TV-Z]{26}$/;
 /** Canonical commission identity: slugified lowercase hyphen segments + `.` + Crockford ULID. */
-export const COMMISSION_ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*\.[0-9A-HJKMNP-TV-Z]{26}$/;
+export const COMMISSION_ID_RE = /^([\p{Letter}\p{Number}\p{Mark}]+(?:-[\p{Letter}\p{Number}\p{Mark}]+)*)\.([0-9A-HJKMNP-TV-Z]{26})$/u;
 /** Minted opaque repository identity: `repo_` + ULID. */
 export function isCommissionId(value) {
-    return COMMISSION_ID_RE.test(value);
+    const match = COMMISSION_ID_RE.exec(value);
+    return match !== null && isNormalizedIdentifierSlug(match[1]);
 }
 export class ContractIdError extends Error {
     code = "INVALID_CONTRACT_ID";
@@ -15,16 +17,28 @@ export class ContractIdError extends Error {
     }
 }
 export function slugifyContractName(name) {
-    const slug = name
-        .trim()
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/-+/g, "-")
-        .replace(/^-+|-+$/g, "");
-    if (!slug) {
-        throw new ContractIdError("contract name cannot be converted to a slug");
+    try {
+        return normalizeIdentifierSlug(name);
+    }
+    catch (error) {
+        if (error instanceof IdentifierSlugError) {
+            throw new ContractIdError(`contract name ${error.message}`, { cause: error });
+        }
+        throw error;
     }
-    return slug;
+}
+/** Human-facing slug from a commission ID (`<slug>.<ULID>`). Splits on the last `.`. */
+export function commissionSlug(commissionId) {
+    const separator = commissionId.lastIndexOf(".");
+    return separator > 0 ? commissionId.slice(0, separator) : commissionId;
+}
+/**
+ * Human-facing contract coordinate: `<slug> @<place>` in worktree state, `<slug>` in here state.
+ * Full ULID never appears in this string.
+ */
+export function formatCommissionCoordinate(input) {
+    const slug = commissionSlug(input.commissionId);
+    return input.place && input.place !== slug ? `${slug} @${input.place}` : slug;
 }
 function encodeTime(nowMs) {
     if (!Number.isSafeInteger(nowMs) || nowMs < 0 || nowMs > 0xffffffffffff) {

package/build/core/ledger.js

@@ -1,70 +1,34 @@
-import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, wrapGitError, } from "../git/core.js";
+import { createGit, wrapGitError, } from "../git/core.js";
 import { formatLedgerEntryCommitMessage, parseLedgerEntryCommitMessage, } from "./entry.js";
-const EMPTY_TREE_HASH = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
-const MISSING_REF_SENTINEL = "0".repeat(40);
+import { casUpdateRefLog, createRefLogCommit, listRefLogCommits, readRefLogCommitMessage, resolveRefLogHead, } from "./ref-log.js";
 export const ACTIVE_LEDGER_REF_PREFIX = "refs/keiyaku/active/";
 export function activeLedgerRef(contractId) {
     return `${ACTIVE_LEDGER_REF_PREFIX}${contractId}`;
 }
-async function resolveRefHead(cwd, ref) {
-    const git = createGit(cwd);
-    try {
-        const output = await git.raw(["rev-parse", "--verify", `${ref}^{commit}`]);
-        return output.trim();
-    }
-    catch (error) {
-        if (errorContainsAnyPattern(error, MISSING_HEAD_PATTERNS)) {
-            return null;
-        }
-        throw wrapGitError(`rev-parse ${ref}`, error, cwd);
-    }
-}
-async function createLedgerCommit(cwd, entry, parentHead) {
-    const git = createGit(cwd);
+export async function appendEntry(cwd, ref, entry, expectedHead) {
     const message = formatLedgerEntryCommitMessage(entry);
     const separator = message.indexOf("\n\n");
     const subject = message.slice(0, separator);
     const body = message.slice(separator + 2).trimEnd();
-    const args = ["commit-tree", EMPTY_TREE_HASH];
-    if (parentHead) {
-        args.push("-p", parentHead);
-    }
-    args.push("-m", subject, "-m", body);
-    try {
-        return (await git.raw(args)).trim();
-    }
-    catch (error) {
-        throw wrapGitError(`commit-tree ledger ${entry.kind} ${entry.contract}`, error, cwd);
-    }
-}
-async function readCommitMessage(cwd, commit) {
-    const git = createGit(cwd);
-    try {
-        return await git.raw(["show", "-s", "--format=%B", commit]);
-    }
-    catch (error) {
-        throw wrapGitError(`show commit message ${commit}`, error, cwd);
-    }
-}
-export async function appendEntry(cwd, ref, entry, expectedHead) {
-    const git = createGit(cwd);
-    const newHead = await createLedgerCommit(cwd, entry, expectedHead);
-    const oldValue = expectedHead ?? MISSING_REF_SENTINEL;
-    try {
-        await git.raw(["update-ref", ref, newHead, oldValue]);
+    const newHead = await createRefLogCommit(cwd, {
+        subject,
+        body,
+        parentHead: expectedHead,
+        errorLabel: `ledger ${entry.kind} ${entry.contract}`,
+    });
+    const casOk = await casUpdateRefLog(cwd, ref, newHead, expectedHead);
+    if (casOk)
         return { ok: true, head: newHead };
+    // Intentional: CAS loss re-resolves and surfaces conflict/missing-ref without throw.
+    const currentHead = await resolveRefLogHead(cwd, ref);
+    if (currentHead === null) {
+        return { ok: false, reason: "missing-ref" };
     }
-    catch (error) {
-        const currentHead = await resolveRefHead(cwd, ref);
-        if (currentHead === null) {
-            return { ok: false, reason: "missing-ref" };
-        }
-        return { ok: false, reason: "conflict", currentHead };
-    }
+    return { ok: false, reason: "conflict", currentHead };
 }
 export async function appendWithRetry(cwd, ref, build, options = {}) {
     const maxRetries = options.maxRetries ?? 3;
-    let currentHead = await resolveRefHead(cwd, ref);
+    let currentHead = await resolveRefLogHead(cwd, ref);
     const startedMissing = currentHead === null;
     for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
         const currentEntries = currentHead ? (await readLedgerRef(cwd, ref, currentHead)).entries : [];
@@ -90,28 +54,16 @@ export async function appendWithRetry(cwd, ref, build, options = {}) {
     return { ok: false, reason: "conflict", currentHead };
 }
 async function readLedgerRef(cwd, ref, head) {
-    const git = createGit(cwd);
-    let output;
-    try {
-        output = await git.raw(["rev-list", "--reverse", head]);
-    }
-    catch (error) {
-        throw wrapGitError(`rev-list ${ref}`, error, cwd);
-    }
-    const commits = output
-        .trim()
-        .split("\n")
-        .map((value) => value.trim())
-        .filter((value) => value.length > 0);
+    const commits = await listRefLogCommits(cwd, head, ref);
     const entries = [];
     for (const commit of commits) {
-        entries.push(parseLedgerEntryCommitMessage(await readCommitMessage(cwd, commit)));
+        entries.push(parseLedgerEntryCommitMessage(await readRefLogCommitMessage(cwd, commit)));
     }
     return { ref, head, entries };
 }
 export async function readLedger(cwd, contractId) {
     const ref = activeLedgerRef(contractId);
-    const head = await resolveRefHead(cwd, ref);
+    const head = await resolveRefLogHead(cwd, ref);
     if (!head)
         return null;
     return { contractId, ...(await readLedgerRef(cwd, ref, head)) };