@astrosheep/keiyaku 2.9.8 → 2.9.10

package/build/core/draft.js

@@ -3,8 +3,9 @@ import { parseToAST } from "./markdown/parser.js";
 import { extractListItems, renderSectionContent } from "./markdown/render.js";
 import { normalizeSectionTitle } from "./markdown/titles.js";
 import { markdownSourceSections, renderScopeFragment, validateScopeFragmentLines } from "./scope.js";
-const KNOWN_SECTIONS = new Set(["objective", "scope", "checks"]);
-const BIND_DRAFT_SECTION_ORDER = ["name", "objective", "scope", "checks"];
+const KNOWN_SECTIONS = new Set(["context", "objective", "design", "scope", "criteria", "verification"]);
+const RETIRED_OR_MALFORMED_CORE_SECTIONS = new Set(["title", "name", "checks"]);
+const BIND_DRAFT_SECTION_ORDER = ["title", "context", "objective", "design", "scope", "criteria", "verification"];
 function invalidBindDraft(message) {
     throw new FlowError("INVALID_KEIYAKU_DRAFT", `INVALID_BIND_DRAFT: ${message}`);
 }
@@ -50,26 +51,26 @@ function findUnexpectedListOnlyLine(section) {
     }
     return null;
 }
-function extractSingleLineChecks(section) {
+function extractSingleLineDeclarations(section, heading) {
     const unexpected = findUnexpectedListOnlyLine(section);
     if (unexpected) {
-        invalidBindDraft(`Checks must be a bullet list; found '${unexpected}'`);
+        invalidBindDraft(`${heading} must be a bullet list; found '${unexpected}'`);
     }
     const items = extractListItems(section);
     if (items.length === 0) {
         const hasListNode = section.children.some((child) => child.type === "list");
         if (hasListNode) {
-            invalidBindDraft("empty check in bind draft");
+            invalidBindDraft(`empty ${heading.toLowerCase()} declaration in bind draft`);
         }
-        invalidBindDraft("Checks must be a bullet list; found empty Checks section");
+        invalidBindDraft(`${heading} must be a bullet list; found empty ${heading} section`);
     }
     return items.map((item) => {
         const trimmed = item.trim();
         if (trimmed.length === 0) {
-            invalidBindDraft("empty check in bind draft");
+            invalidBindDraft(`empty ${heading.toLowerCase()} declaration in bind draft`);
         }
         if (item.includes("\n") || item.includes("\r")) {
-            invalidBindDraft("check items must be a single line");
+            invalidBindDraft(`${heading} declarations must be a single line`);
         }
         return trimmed;
     });
@@ -85,7 +86,7 @@ function collectBindDraftNodes(content) {
         structuralContent = `${structuralContent.slice(0, source.contentStart)}\`\`\`\nscope\n\`\`\`\n${structuralContent.slice(source.end)}`;
     }
     const ast = parseToAST(structuralContent);
-    let name;
+    let title;
     let seenH1 = false;
     const sections = new Map();
     const extensions = [];
@@ -97,12 +98,16 @@ function collectBindDraftNodes(content) {
                 invalidBindDraft("bind draft allows exactly one H1 heading");
             }
             seenH1 = true;
-            name = node.title.trim() || undefined;
+            title = node.title.trim() || undefined;
             continue;
         }
         if (node.level !== 2)
             continue;
         const normalized = normalizeSectionName(node.title);
+        if (RETIRED_OR_MALFORMED_CORE_SECTIONS.has(normalized)) {
+            const replacement = normalized === "checks" ? "Criteria and Verification" : "the H1 Title";
+            invalidBindDraft(`obsolete or malformed core section '${node.title}'; use ${replacement}`);
+        }
         if (KNOWN_SECTIONS.has(normalized)) {
             if (sections.has(normalized)) {
                 invalidBindDraft(`duplicate section '${node.title}' in bind draft`);
@@ -115,7 +120,7 @@ function collectBindDraftNodes(content) {
             content: normalizeExtensionContent(renderSectionContent(node)),
         });
     }
-    return { ...(name === undefined ? {} : { name }), sections, extensions };
+    return { ...(title === undefined ? {} : { title }), sections, extensions };
 }
 function parseScopeSection(content) {
     const sourceSections = markdownSourceSections(content).filter((section) => section.level === 2 && normalizeSectionTitle(section.title) === "scope");
@@ -141,52 +146,68 @@ function parseScopeSection(content) {
 export function parsePartialBindDraft(content) {
     if (content.trim().length === 0)
         return {};
-    const { name, sections, extensions } = collectBindDraftNodes(content);
+    const { title, 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;
+    if (title !== undefined)
+        partial.title = title;
+    for (const sectionName of ["context", "objective", "design"]) {
+        const section = sections.get(sectionName);
+        if (!section)
+            continue;
+        const text = renderSectionContent(section).trim();
+        const heading = `${sectionName[0].toUpperCase()}${sectionName.slice(1)}`;
+        if (!text)
+            invalidBindDraft(`${heading} section cannot be empty`);
+        partial[sectionName] = text;
     }
     const scope = sections.get("scope");
     if (scope) {
         partial.scope = parseScopeSection(content);
     }
-    const checks = sections.get("checks");
-    if (checks)
-        partial.checks = extractSingleLineChecks(checks);
+    const criteria = sections.get("criteria");
+    if (criteria)
+        partial.criteria = extractSingleLineDeclarations(criteria, "Criteria");
+    const verification = sections.get("verification");
+    if (verification)
+        partial.verification = extractSingleLineDeclarations(verification, "Verification");
     if (extensions.length > 0)
         partial.extensions = extensions;
     return partial;
 }
 export function mergeBindDraft(base, override) {
     return {
-        ...(base.name !== undefined ? { name: base.name } : {}),
+        ...(base.title !== undefined ? { title: base.title } : {}),
+        ...(base.context !== undefined ? { context: base.context } : {}),
         ...(base.objective !== undefined ? { objective: base.objective } : {}),
+        ...(base.design !== undefined ? { design: base.design } : {}),
         ...(base.scope !== undefined ? { scope: base.scope } : {}),
-        ...(base.checks !== undefined ? { checks: base.checks } : {}),
+        ...(base.criteria !== undefined ? { criteria: base.criteria } : {}),
+        ...(base.verification !== undefined ? { verification: base.verification } : {}),
         ...(base.extensions !== undefined ? { extensions: base.extensions } : {}),
-        ...(override.name !== undefined ? { name: override.name } : {}),
+        ...(override.title !== undefined ? { title: override.title } : {}),
+        ...(override.context !== undefined ? { context: override.context } : {}),
         ...(override.objective !== undefined ? { objective: override.objective } : {}),
+        ...(override.design !== undefined ? { design: override.design } : {}),
         ...(override.scope !== undefined ? { scope: override.scope } : {}),
-        ...(override.checks !== undefined ? { checks: override.checks } : {}),
+        ...(override.criteria !== undefined ? { criteria: override.criteria } : {}),
+        ...(override.verification !== undefined ? { verification: override.verification } : {}),
         ...(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.title === undefined || partial.title.trim().length === 0)
+        missing.push("title");
+    if (partial.context === undefined || partial.context.trim().length === 0)
+        missing.push("context");
     if (partial.objective === undefined || partial.objective.trim().length === 0)
         missing.push("objective");
+    if (partial.design === undefined || partial.design.trim().length === 0)
+        missing.push("design");
     if (partial.scope === undefined || partial.scope.length === 0)
         missing.push("scope");
-    if (partial.checks === undefined || partial.checks.length === 0)
-        missing.push("checks");
+    if (partial.criteria === undefined || partial.criteria.length === 0)
+        missing.push("criteria");
     return missing;
 }
 /** Paste-ready partial markdown for only the missing required sections. */
@@ -195,19 +216,31 @@ export function renderMissingBindSectionsTemplate(missing) {
     for (const section of BIND_DRAFT_SECTION_ORDER) {
         if (!missing.includes(section))
             continue;
-        if (section === "name") {
-            lines.push("# <name>");
+        if (section === "title") {
+            lines.push("# <title>");
+            continue;
+        }
+        if (section === "context") {
+            lines.push("## Context", "<established facts and constraints>");
             continue;
         }
         if (section === "objective") {
             lines.push("## Objective", "<what the commission should accomplish>");
             continue;
         }
+        if (section === "design") {
+            lines.push("## Design", "<settled owner, boundaries, flow, state, and failure behavior>");
+            continue;
+        }
         if (section === "scope") {
             lines.push("## Scope", "~~~", "<pattern>", "<another-pattern>", "~~~");
             continue;
         }
-        lines.push("## Checks", "- <verification>");
+        if (section === "criteria") {
+            lines.push("## Criteria", "- <declarative acceptance criterion>");
+            continue;
+        }
+        lines.push("## Verification", "- <executable command or testimony declaration>");
     }
     return lines.join("\n");
 }
@@ -226,46 +259,70 @@ export function materializeBindDraft(partial) {
         invalidBindDraft(`missing ${describeMissingBindSections(missing)} in bind draft`);
     }
     return {
-        name: partial.name.trim(),
+        title: partial.title.trim(),
+        context: partial.context.trim(),
         objective: partial.objective.trim(),
+        design: partial.design.trim(),
         scope: partial.scope,
-        checks: partial.checks,
+        criteria: partial.criteria,
+        verification: partial.verification ?? [],
         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'");
+    const { title, sections, extensions } = collectBindDraftNodes(content);
+    if (!title) {
+        invalidBindDraft("missing H1 Title in bind draft; expected '# <title>' followed by Context, Objective, Design, Scope, and Criteria; Verification is optional");
     }
+    const context = sections.get("context");
     const objective = sections.get("objective");
+    const design = sections.get("design");
     const scope = sections.get("scope");
-    const checks = sections.get("checks");
+    const criteria = sections.get("criteria");
+    const verification = sections.get("verification");
+    if (!context)
+        invalidBindDraft("missing Context section in bind draft");
     if (!objective)
         invalidBindDraft("missing Objective section in bind draft");
+    if (!design)
+        invalidBindDraft("missing Design section in bind draft");
     if (!scope)
         invalidBindDraft("missing Scope section in bind draft");
     const parsedScope = parseScopeSection(content);
-    if (!checks)
-        invalidBindDraft("missing Checks section in bind draft");
+    if (!criteria)
+        invalidBindDraft("missing Criteria section in bind draft");
+    const contextText = renderSectionContent(context).trim();
     const objectiveText = renderSectionContent(objective).trim();
+    const designText = renderSectionContent(design).trim();
+    if (!contextText)
+        invalidBindDraft("Context section cannot be empty");
     if (!objectiveText)
         invalidBindDraft("Objective section cannot be empty");
+    if (!designText)
+        invalidBindDraft("Design section cannot be empty");
     return {
-        name,
+        title,
+        context: contextText,
         objective: objectiveText,
+        design: designText,
         scope: parsedScope,
-        checks: extractSingleLineChecks(checks),
+        criteria: extractSingleLineDeclarations(criteria, "Criteria"),
+        verification: verification ? extractSingleLineDeclarations(verification, "Verification") : [],
         extensions,
     };
 }
 export function renderBindDraft(draft) {
     const sections = [
-        `# ${draft.name}`,
+        `# ${draft.title}`,
+        `## Context\n${draft.context}`,
         `## Objective\n${draft.objective}`,
+        `## Design\n${draft.design}`,
         `## Scope\n${renderScopeFragment(draft.scope)}`,
-        `## Checks\n${draft.checks.map((check) => `- ${check}`).join("\n")}`,
+        `## Criteria\n${draft.criteria.map((criterion) => `- ${criterion}`).join("\n")}`,
     ];
+    if (draft.verification.length > 0) {
+        sections.push(`## Verification\n${draft.verification.map((declaration) => `- ${declaration}`).join("\n")}`);
+    }
     for (const extension of draft.extensions) {
         const content = normalizeExtensionContent(extension.content);
         if (content.length > 0) {
@@ -279,21 +336,32 @@ export function renderBindDraft(draft) {
 }
 export function compileBindDraftFlags(input) {
     for (const [flag, value] of [
-        ["--place", input.place],
+        ["--title", input.title],
+        ["--context", input.context],
         ["--objective", input.objective],
+        ["--design", input.design],
         ["--scope", input.scope],
-        ["--checks", input.checks],
+        ["--criteria", input.criteria],
+        ["--verification", input.verification],
     ]) {
-        if (value.includes("\n") || value.includes("\r")) {
+        if (value !== undefined && (value.includes("\n") || value.includes("\r"))) {
             throw new FlowError("EMPTY_PARAM", `${flag} must be a single line`);
         }
     }
-    const draft = {
-        name: input.place,
-        objective: input.objective,
-        scope: [input.scope],
-        checks: [input.checks],
-        extensions: [],
-    };
-    return renderBindDraft(parseBindDraft(renderBindDraft(draft)));
+    const sections = [];
+    if (input.title !== undefined)
+        sections.push(`# ${input.title}`);
+    if (input.context !== undefined)
+        sections.push(`## Context\n${input.context}`);
+    if (input.objective !== undefined)
+        sections.push(`## Objective\n${input.objective}`);
+    if (input.design !== undefined)
+        sections.push(`## Design\n${input.design}`);
+    if (input.scope !== undefined)
+        sections.push(`## Scope\n~~~\n${input.scope}\n~~~`);
+    if (input.criteria !== undefined)
+        sections.push(`## Criteria\n- ${input.criteria}`);
+    if (input.verification !== undefined)
+        sections.push(`## Verification\n- ${input.verification}`);
+    return sections.length > 0 ? `${sections.join("\n\n")}\n` : "";
 }

package/build/core/forfeit.js

@@ -1,67 +1,123 @@
 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/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 });
-    return await cleanupContractWorkspace(stableRoot, contractId);
-}
-export async function forfeitContract(input, deps = {}) {
+import { runLifecycle } from "./lifecycle-runner.js";
+import { currentLifecycleState } from "./repository-ledger/read-model.js";
+import { isTerminalState } from "./status/lifecycle.js";
+import { terminalCleanupFacts } from "./worktree-path.js";
+import { repositoryDeliveryRef } from "./repository-ledger/codec.js";
+export async function forfeitContract(input) {
     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);
-        if (state.state === "forfeited") {
-            await reconcileTaskForfeit({
-                cwd: stableRoot,
-                contractId: input.contractId,
-                publishLedger: async () => undefined,
-            });
-            const cleanup = await (deps.cleanupForfeit ?? cleanupForfeit)(stableRoot, input.contractId, input.actor, at);
-            return { contractId: input.contractId, cleanup };
-        }
-    }
-    if (!ledger) {
-        throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} not found or not active`);
-    }
-    const state = deriveContractState(ledger.entries);
-    if (state.state === "corrupt" || isTerminalState(state)) {
-        throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} cannot forfeit from state ${state.state}`);
-    }
-    await reconcileTaskForfeit({
-        cwd: stableRoot,
+    const requestedNote = input.note?.trim() || undefined;
+    const execution = await runLifecycle({
+        cwd: input.cwd,
         contractId: input.contractId,
-        publishLedger: async () => {
-            const result = await appendWithRetry(stableRoot, activeLedgerRef(input.contractId), () => {
-                const entry = {
-                    v: 1,
-                    kind: "forfeit",
-                    contract: input.contractId,
-                    at,
+        mutation: {
+            verb: "forfeit",
+        },
+        signal: input.signal,
+        ...(input.terminalWorkspaceCleanup ? { terminalWorkspaceCleanup: input.terminalWorkspaceCleanup } : {}),
+        admit: async (session, replay) => {
+            const state = currentLifecycleState(session.lifecycle);
+            if (state.state !== "forfeited" && isTerminalState(state))
+                throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} cannot forfeit from state ${state.state}`);
+            if (state.state === "forfeited") {
+                const transaction = replay.state === "verb-committed" ? replay.transaction : undefined;
+                const existing = transaction?.entries.at(-1);
+                if (!existing || existing.kind !== "forfeit")
+                    throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} forfeited without an accepted forfeit transaction`);
+                return {
+                    state,
+                    delivery: { status: "absent" },
+                    existing: { transactionObjectId: transaction.transactionObjectId, entry: existing },
+                    ...(session.target.status === "available" ? { targetRoot: session.target.root } : {}),
+                };
+            }
+            if (session.target.status === "available")
+                await assertCleanTrackedWorkingTree(session.target.root);
+            if (session.lifecycle.petition.state === "awaiting-verdict") {
+                throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} has a pending settlement`);
+            }
+            if (session.lifecycle.petition.state === "approved" && session.lifecycle.petition.intent !== "forfeit") {
+                throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} has an approved non-forfeit settlement`);
+            }
+            if (!session.pins.delivery.head)
+                throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} delivery ref is absent before forfeit`);
+            return {
+                state,
+                delivery: { status: "present", head: session.pins.delivery.head },
+                ...(session.target.status === "available" ? { targetRoot: session.target.root } : {}),
+            };
+        },
+        prepare: (admission) => ({
+            ...(admission.business.existing ? { existing: admission.business.existing } : {}),
+            entry: admission.business.existing?.entry ?? {
+                v: 2,
+                kind: "forfeit",
+                contract: input.contractId,
+                at,
+                actor: input.actor,
+                data: {
+                    reason: input.reason,
                     actor: input.actor,
-                    data: {
-                        reason: input.reason,
-                        by: input.actor,
-                        ...(input.note?.trim() ? { note: input.note.trim() } : {}),
+                    finalHead: admission.business.delivery.status === "present"
+                        ? admission.business.delivery.head
+                        : admission.business.existing.entry.data.finalHead,
+                    ...(requestedNote ? { note: requestedNote } : {}),
+                },
+            },
+        }),
+        revalidate: async ({ session, admission, prepared }) => {
+            const state = currentLifecycleState(session.lifecycle);
+            if (prepared.existing) {
+                return session.repository.topology.nodes.some((node) => node.objectId === prepared.existing.transactionObjectId)
+                    ? undefined
+                    : { code: "FORFEIT_STATE_CHANGED", message: "accepted forfeit entry changed during replay preparation" };
+            }
+            if (session.target.status === "available")
+                await assertCleanTrackedWorkingTree(session.target.root);
+            if (admission.business.delivery.status !== "present" || session.pins.delivery.head !== admission.business.delivery.head) {
+                return { code: "FORFEIT_DELIVERY_CHANGED", message: "contract delivery changed during forfeit preparation" };
+            }
+            return state.state === admission.business.state.state
+                ? undefined
+                : { code: "FORFEIT_STATE_CHANGED", message: "contract lifecycle changed during forfeit preparation" };
+        },
+        effect: async ({ context, admission, prepared }) => {
+            const publication = prepared.existing
+                ? await context.replayCommitted({ transactionObjectId: prepared.existing.transactionObjectId, carrier: "retire" })
+                : await context.publishAuthoritative({
+                    verb: "forfeit",
+                    admittedLedgerHead: admission.ledgerHead,
+                    acceptedLifecycleTail: context.session.lifecycle.history.at(-1).objectId,
+                    entries: [prepared.entry],
+                    delivery: {
+                        ref: repositoryDeliveryRef(input.contractId),
+                        expectedOid: admission.business.delivery.status === "present" ? admission.business.delivery.head : null,
                     },
-                };
-                return entry;
-            });
-            if (!result.ok)
-                throw new FlowError("INTERNAL_STATE", `failed to forfeit ${input.contractId}: ${result.reason}`);
-            return result;
+                });
+            if (publication.status === "indeterminate") {
+                return { kind: "precommit-effects-only", authoritativeHead: publication.currentHead ?? admission.ledgerHead };
+            }
+            if (publication.status !== "committed") {
+                return { kind: "refused-before-effects", authoritativeHead: publication.currentHead ?? admission.ledgerHead, refusal: { code: "LEDGER_CAS_CONFLICT", message: `contract ${input.contractId} changed during forfeit` } };
+            }
+            const published = publication;
+            await context.session.completeReplay("retire");
+            const cleanupRow = context.journal.all().find((row) => row.effect === "worktree-projection" && row.status === "succeeded");
+            const cleanupFacts = cleanupRow?.status === "succeeded" ? cleanupRow.receipt?.facts : undefined;
+            const deliveryRefRow = context.journal.all().find((row) => row.effect === "delivery-ref-projection" && row.status === "succeeded");
+            const deliveryRefFacts = deliveryRefRow?.status === "succeeded" ? deliveryRefRow.receipt?.facts : undefined;
+            const cleanup = terminalCleanupFacts(cleanupFacts, deliveryRefFacts);
+            if (!cleanup)
+                throw new FlowError("INTERNAL_STATE", "terminal replay completed without typed cleanup facts");
+            return { kind: "committed", commit: published, entryKind: "forfeit", value: { cleanup } };
         },
     });
-    // Forfeit entry naturally removes membership; no dequeue record.
-    const cleanup = await (deps.cleanupForfeit ?? cleanupForfeit)(stableRoot, input.contractId, input.actor, at);
-    return { contractId: input.contractId, cleanup };
+    if (execution.kind === "noncommitted")
+        return execution.outcome;
+    if (execution.kind === "contained")
+        return { ...execution.outcome, contractId: input.contractId };
+    return { ...execution.outcome, contractId: input.contractId, cleanup: execution.payload.cleanup, carrier: execution.carrier };
 }
 export async function forfeitContractCommand(input) {
     return await forfeitContract({
@@ -71,5 +127,6 @@ export async function forfeitContractCommand(input) {
         nowMs: input.nowMs,
         reason: "manual",
         note: input.note,
+        signal: input.signal,
     });
 }

package/build/core/identifier-slug.js

@@ -1,3 +1,4 @@
+import * as crypto from "node:crypto";
 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;
@@ -6,8 +7,8 @@ const WINDOWS_RESERVED_BASENAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/u;
  * 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 const TASK_IDENTIFIER_MAX_UTF8_BYTES = 48;
+const TASK_IDENTIFIER_DIGEST_HEX_LENGTH = 8;
 export class IdentifierSlugError extends Error {
     code = "INVALID_IDENTIFIER_SLUG";
     constructor(message, options) {
@@ -18,23 +19,14 @@ export class IdentifierSlugError extends Error {
 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}`);
-    }
+function normalizedIdentifierSlug(value, maxUtf8Bytes) {
     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;
+                return { slug, truncated: true };
             slug += addition;
             pendingSeparator = false;
         }
@@ -42,6 +34,18 @@ export function normalizeIdentifierSlug(value, maxUtf8Bytes = IDENTIFIER_SLUG_MA
             pendingSeparator = true;
         }
     }
+    return { slug, truncated: false };
+}
+function truncateNormalizedIdentifierSlug(value, maxUtf8Bytes) {
+    let prefix = "";
+    for (const character of value) {
+        if (utf8Bytes(prefix) + utf8Bytes(character) > maxUtf8Bytes)
+            break;
+        prefix += character;
+    }
+    return prefix.replace(/-+$/u, "");
+}
+function validatedIdentifierSlug(slug, maxUtf8Bytes) {
     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");
     }
@@ -54,6 +58,52 @@ export function normalizeIdentifierSlug(value, maxUtf8Bytes = IDENTIFIER_SLUG_MA
     }
     return slug;
 }
+function completeNormalizedIdentifierSlug(value) {
+    let slug = "";
+    let pendingSeparator = false;
+    for (const character of value.normalize("NFKC").toLowerCase()) {
+        if (SLUG_CHARACTER.test(character)) {
+            slug += `${pendingSeparator && slug ? "-" : ""}${character}`;
+            pendingSeparator = false;
+        }
+        else if (slug) {
+            pendingSeparator = true;
+        }
+    }
+    return validatedIdentifierSlug(slug, Number.MAX_SAFE_INTEGER);
+}
+/**
+ * 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}`);
+    }
+    return validatedIdentifierSlug(normalizedIdentifierSlug(value, maxUtf8Bytes).slug, maxUtf8Bytes);
+}
+/**
+ * Allocate a newly generated task ID. Persisted task documents remain
+ * addressable at their original ID; this limit applies only to new IDs.
+ */
+export function taskIdentifierSlug(value, collisionSuffix = "") {
+    const suffixBytes = utf8Bytes(collisionSuffix);
+    const availableBytes = TASK_IDENTIFIER_MAX_UTF8_BYTES - suffixBytes;
+    if (availableBytes < TASK_IDENTIFIER_DIGEST_HEX_LENGTH + 2) {
+        throw new IdentifierSlugError("task collision suffix leaves no room for a bounded identifier");
+    }
+    const normalized = completeNormalizedIdentifierSlug(value);
+    if (utf8Bytes(normalized) <= TASK_IDENTIFIER_MAX_UTF8_BYTES) {
+        return `${truncateNormalizedIdentifierSlug(normalized, availableBytes)}${collisionSuffix}`;
+    }
+    const prefixBytes = availableBytes - TASK_IDENTIFIER_DIGEST_HEX_LENGTH - 1;
+    const prefix = truncateNormalizedIdentifierSlug(normalized, prefixBytes);
+    const digest = crypto.createHash("sha256").update(normalized, "utf8").digest("hex")
+        .slice(0, TASK_IDENTIFIER_DIGEST_HEX_LENGTH);
+    return `${prefix}-${digest}${collisionSuffix}`;
+}
 export function isNormalizedIdentifierSlug(value) {
     if (!value || utf8Bytes(value) > IDENTIFIER_SLUG_MAX_UTF8_BYTES)
         return false;

package/build/core/ids.js

@@ -16,13 +16,13 @@ export class ContractIdError extends Error {
         this.name = "ContractIdError";
     }
 }
-export function slugifyContractName(name) {
+export function slugifyContractTitle(title) {
     try {
-        return normalizeIdentifierSlug(name);
+        return normalizeIdentifierSlug(title);
     }
     catch (error) {
         if (error instanceof IdentifierSlugError) {
-            throw new ContractIdError(`contract name ${error.message}`, { cause: error });
+            throw new ContractIdError(`contract title ${error.message}`, { cause: error });
         }
         throw error;
     }
@@ -77,7 +77,7 @@ export function createUlid(nowMs, randomBytes) {
     return ulid;
 }
 export function buildContractId(input) {
-    return `${slugifyContractName(input.name)}.${createUlid(input.nowMs, input.randomBytes)}`;
+    return `${slugifyContractTitle(input.title)}.${createUlid(input.nowMs, input.randomBytes)}`;
 }
 export async function assertValidContractId(cwd, id) {
     const git = createGit(cwd);