@astrosheep/keiyaku 2.9.12 → 2.9.13

package/build/core/contract-carrier.js

@@ -1,22 +1,28 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { DatabaseSync } from "node:sqlite";
 import { FlowError } from "../flow-error.js";
-import { createGit, errorContainsAnyPattern, isFullGitObjectId, MISSING_HEAD_PATTERNS, runGitProcess, wrapGitError } from "../git/core.js";
+import { isCommitAncestor, readCommitCoordinate } from "../git/commits.js";
+import { isFullGitObjectId, runGitProcess } from "../git/core.js";
+import { resolveExactRefHeads } from "../git/refs.js";
 import { KEIYAKU_FILE } from "../keiyaku.js";
-import { renderCurrentContractView } from "./contract-view.js";
+import { renderCanonicalCarrierBody } from "./contract-view.js";
 import { isCommissionId } from "./ids.js";
 import { activeWorkspaceHereContracts } from "./repository-ledger/inventory.js";
 import { lookupCurrentContract, readRepositoryLifecycle, } from "./repository-ledger/read-model.js";
 import { REPOSITORY_LEDGER_REF, } from "./repository-ledger/codec.js";
 import { resolveContractCarrierTarget, stableRepoRoot, } from "./worktree-path.js";
+import { carrierDigest, carrierInputIdentity, contractHead, } from "./repository-ledger/identity.js";
 import { installCarrierRuntimePorts } from "./contract-carrier-runtime.js";
-export { convergeContractCarrier, reconcileContractCarrierProjection, withContractCarrierSession } from "./contract-carrier-runtime.js";
+export { convergeContractCarrier, reconcileContractCarrierProjection, withContractCarrierSession, withObservedContractCarrierSession } from "./contract-carrier-runtime.js";
 const BUSY_SLICE_MS = 25;
-const CARRIER_CONTRACT = /^id: (\S+)$/m;
-const CARRIER_PROVENANCE = /^ledger: (\S+)$/m;
+const CARRIER_HEADER = "<!-- keiyaku-carrier";
+const CARRIER_HEADER_END = "-->";
+const CARRIER_ID_LINE = "contract-id";
+const CARRIER_HEAD_LINE = "contract-head";
+const CARRIER_DIGEST_LINE = "carrier-digest";
 export function acceptedBind(lifecycle) {
     for (const { entry } of lifecycle.history) {
         if (entry.kind === "bind")
@@ -38,10 +44,10 @@ async function projectRenewDeliveryRoot(root, oldHead, newHead) {
         throw new FlowError("INTERNAL_STATE", update.stderr.trim() || update.error?.message || `read-tree exited ${String(update.status)}`, { cause: update.error });
     }
     const [head, status] = await Promise.all([
-        runGitProcess(root, ["rev-parse", "--verify", "HEAD^{commit}"]),
+        readCommitCoordinate(root, "HEAD"),
         runGitProcess(root, ["status", "--porcelain=v1", "--untracked-files=no"]),
     ]);
-    if (head.status !== 0 || head.error || head.stdout.trim() !== newHead || status.status !== 0 || status.error || status.stdout !== "") {
+    if (head.status !== "ok" || head.coordinate.commit !== newHead || status.status !== 0 || status.error || status.stdout !== "") {
         throw new FlowError("INTERNAL_STATE", "delivery worktree did not align to the committed renew head");
     }
 }
@@ -59,9 +65,15 @@ export async function reconcileFoldedDeliveryWorktree(input) {
     }
     const indexTree = index.stdout.trim();
     const newTree = await resolveCommitTree(input.targetRoot, renew.entry.data.newHead);
-    if (indexTree === newTree)
-        return "already-present";
     const oldTree = await resolveCommitTree(input.targetRoot, renew.entry.data.oldHead);
+    if (indexTree === newTree && worktree.status === 0 && !worktree.error)
+        return "already-present";
+    if (indexTree !== oldTree
+        && worktree.status === 0
+        && !worktree.error
+        && await isCommitAncestor(input.targetRoot, renew.entry.data.newHead, "HEAD")) {
+        return "already-present";
+    }
     if (indexTree !== oldTree || worktree.status !== 0 || worktree.error) {
         throw new FlowError("INTERNAL_STATE", `delivery worktree cannot be safely reconstructed for accepted renew ${renew.objectId}`);
     }
@@ -69,11 +81,14 @@ export async function reconcileFoldedDeliveryWorktree(input) {
     return "created";
 }
 async function resolveCommitTree(cwd, commit) {
-    const result = await runGitProcess(cwd, ["rev-parse", "--verify", `${commit}^{tree}`]);
-    if (result.status !== 0 || result.error) {
-        throw new FlowError("INTERNAL_STATE", result.stderr.trim() || result.error?.message || `cannot resolve tree for ${commit}`, { cause: result.error });
+    const read = await readCommitCoordinate(cwd, commit);
+    if (read.status !== "ok") {
+        if (read.status === "failed") {
+            throw new FlowError("INTERNAL_STATE", read.result.stderr.trim() || read.error.message || `cannot resolve tree for ${commit}`, { cause: read.error });
+        }
+        throw new FlowError("INTERNAL_STATE", `cannot resolve tree for ${commit}`);
     }
-    return result.stdout.trim();
+    return read.coordinate.tree;
 }
 export function observedLedgerHead(observations) {
     const observation = observations.find((item) => item.ref === REPOSITORY_LEDGER_REF)?.observed;
@@ -90,14 +105,19 @@ export function checkCancellation(signal) {
     if (signal?.aborted)
         throwCancelled();
 }
-export async function acquireGate(stableRoot, signal) {
+export function carrierPublicationGatePath(stableRoot, contractId, targetPath) {
+    const key = createHash("sha256").update(`${contractId}\0${targetPath}`).digest("hex");
+    return path.join(stableRoot, ".keiyaku", "carrier-gates", `${key}.sqlite`);
+}
+export async function acquireGate(stableRoot, contractId, targetPath, signal) {
     checkCancellation(signal);
-    const directory = path.join(stableRoot, ".keiyaku");
+    const databasePath = carrierPublicationGatePath(stableRoot, contractId, targetPath);
+    const directory = path.dirname(databasePath);
     await fs.mkdir(directory, { recursive: true });
     checkCancellation(signal);
     let database;
     try {
-        database = new DatabaseSync(path.join(directory, "contract-carrier.sqlite"));
+        database = new DatabaseSync(databasePath);
         database.exec(`PRAGMA busy_timeout = ${BUSY_SLICE_MS}`);
     }
     catch (error) {
@@ -127,9 +147,9 @@ export function releaseGate(database) {
     }
 }
 /** Serialize cross-process committed replay decisions without exposing gate coordinates. */
-export async function withContractReplayGate(cwd, signal, action) {
+export async function withContractReplayGate(cwd, contractId, targetPath, signal, action) {
     const stableRoot = await stableRepoRoot(cwd);
-    const gate = await acquireGate(stableRoot, signal);
+    const gate = await acquireGate(stableRoot, contractId, targetPath, signal);
     try {
         return await action(stableRoot);
     }
@@ -137,35 +157,102 @@ export async function withContractReplayGate(cwd, signal, action) {
         releaseGate(gate);
     }
 }
-export async function readCarrierIdentity(target) {
+function canonicalBody(lifecycle) {
+    return Buffer.from(renderCanonicalCarrierBody(lifecycle), "utf8");
+}
+export function expectedCarrierIdentity(lifecycle) {
+    return carrierInputIdentity({
+        contractId: lifecycle.contract,
+        contractHead: lifecycle.contractHead,
+        bodyDigest: carrierDigest(createHash("sha256").update(canonicalBody(lifecycle)).digest("hex")),
+    });
+}
+export function renderCarrier(lifecycle) {
+    const identity = expectedCarrierIdentity(lifecycle);
+    return [
+        CARRIER_HEADER,
+        `${CARRIER_ID_LINE}: ${identity.contractId}`,
+        `${CARRIER_HEAD_LINE}: ${identity.contractHead}`,
+        `${CARRIER_DIGEST_LINE}: ${identity.bodyDigest}`,
+        CARRIER_HEADER_END,
+        "",
+        canonicalBody(lifecycle).toString("utf8"),
+    ].join("\n");
+}
+function parsedCarrierFromBytes(source) {
+    if (source.subarray(0, 3).equals(Buffer.from([0xef, 0xbb, 0xbf])))
+        return null;
+    const text = source.toString("utf8");
+    if (!Buffer.from(text, "utf8").equals(source))
+        return null;
+    const lines = text.split("\n");
+    if (lines.length < 7 || lines[0] !== CARRIER_HEADER || lines[4] !== CARRIER_HEADER_END || lines[5] !== "")
+        return null;
+    const field = (line, name) => line.startsWith(`${name}: `) ? line.slice(name.length + 2) : null;
+    const contractId = field(lines[1], CARRIER_ID_LINE);
+    const head = field(lines[2], CARRIER_HEAD_LINE);
+    const digest = field(lines[3], CARRIER_DIGEST_LINE);
+    if (contractId === null || head === null || digest === null || !isCommissionId(contractId) || !isFullGitObjectId(head))
+        return null;
     try {
-        return parseCarrierIdentity(await fs.readFile(target, "utf8"));
+        return {
+            identity: carrierInputIdentity({ contractId, contractHead: contractHead(head), bodyDigest: carrierDigest(digest) }),
+            body: Buffer.from(lines.slice(6).join("\n"), "utf8"),
+        };
     }
     catch {
         return null;
     }
 }
+/** Strict current-version parser; it intentionally accepts no legacy carrier format. */
 export function parseCarrierIdentity(source) {
-    const contractId = source.match(CARRIER_CONTRACT)?.[1] ?? "";
-    const ledgerHead = source.match(CARRIER_PROVENANCE)?.[1] ?? "";
-    return isCommissionId(contractId) && isFullGitObjectId(ledgerHead) ? { contractId, ledgerHead } : null;
+    const parsed = parsedCarrierFromBytes(Buffer.from(source, "utf8"));
+    if (!parsed)
+        return null;
+    const digest = carrierDigest(createHash("sha256").update(parsed.body).digest("hex"));
+    return digest === parsed.identity.bodyDigest ? parsed.identity : null;
+}
+export async function verifyCarrier(input) {
+    const expected = expectedCarrierIdentity(input.lifecycle);
+    let source;
+    try {
+        source = await fs.readFile(input.target);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return { status: "missing", expected, target: input.target };
+        return { status: "invalid-header", expected, target: input.target };
+    }
+    const parsed = parsedCarrierFromBytes(source);
+    if (!parsed)
+        return { status: "invalid-header", expected, target: input.target };
+    const actualBodyDigest = carrierDigest(createHash("sha256").update(parsed.body).digest("hex"));
+    if (!parsed.body.equals(canonicalBody(input.lifecycle)) || actualBodyDigest !== parsed.identity.bodyDigest) {
+        return { status: "modified", expected, actual: parsed.identity, target: input.target };
+    }
+    if (parsed.identity.contractId !== expected.contractId
+        || parsed.identity.contractHead !== expected.contractHead
+        || parsed.identity.bodyDigest !== expected.bodyDigest) {
+        return { status: "identity-mismatch", expected, actual: parsed.identity, target: input.target };
+    }
+    return { status: "current", expected, actual: parsed.identity, target: input.target };
 }
-export function carrierMatches(identity, contractId, ledgerHead) {
-    return identity?.contractId === contractId && identity.ledgerHead === ledgerHead;
+export function carrierMatches(verification) {
+    return verification.status === "current";
 }
 export async function retireTerminalHereCarrier(lifecycle, target) {
     if (target.status !== "available" || target.workspace !== "here")
         return "already-present";
-    let source;
     try {
-        source = await fs.readFile(target.path, "utf8");
+        await fs.access(target.path);
     }
     catch (error) {
         if (error instanceof Error && "code" in error && error.code === "ENOENT")
             return "already-present";
         throw error;
     }
-    if (parseCarrierIdentity(source)?.contractId !== lifecycle.contract)
+    const verification = await verifyCarrier({ target: target.path, lifecycle });
+    if (!carrierMatches(verification))
         return "already-present";
     try {
         await fs.unlink(target.path);
@@ -179,45 +266,51 @@ export async function retireTerminalHereCarrier(lifecycle, target) {
 }
 export async function publishCarrier(input) {
     if (input.target.status === "unavailable") {
-        return { status: "target-unavailable", ledgerHead: input.lifecycle.observedLedgerHead, reason: input.target.reason };
+        return { status: "target-unavailable", contractHead: input.lifecycle.contractHead, reason: input.target.reason };
     }
-    if (input.target.workspace === "here") {
-        const occupants = activeWorkspaceHereContracts(input.repository);
-        if (occupants.length !== 1 || occupants[0] !== input.contractId) {
-            return {
-                status: "failed",
-                ledgerHead: input.lifecycle.observedLedgerHead,
-                target: input.target.path,
-                cause: `workspace-here carrier occupancy does not admit ${input.contractId}`,
-            };
+    const target = input.target;
+    const hasExpectedTarget = async () => {
+        const observed = await observe(input.stableRoot, input.contractId);
+        if (observed.lifecycle.contractHead !== input.lifecycle.contractHead)
+            return false;
+        if (observed.target.status !== "available" || observed.target.path !== target.path || observed.target.workspace !== target.workspace)
+            return false;
+        if (observed.target.workspace === "here") {
+            const occupants = activeWorkspaceHereContracts(observed.repository);
+            return occupants.length === 1 && occupants[0] === input.contractId;
         }
+        return true;
+    };
+    if (target.workspace === "here" && !await hasExpectedTarget()) {
+        return {
+            status: "failed",
+            contractHead: input.lifecycle.contractHead,
+            target: target.path,
+            cause: `workspace-here carrier occupancy does not admit ${input.contractId}`,
+        };
     }
-    if (carrierMatches(await readCarrierIdentity(input.target.path), input.contractId, input.lifecycle.observedLedgerHead)) {
-        return { status: "current", ledgerHead: input.lifecycle.observedLedgerHead, target: input.target.path };
+    if (carrierMatches(await verifyCarrier({ target: target.path, lifecycle: input.lifecycle }))) {
+        return { status: "current", contractHead: input.lifecycle.contractHead, target: target.path };
     }
-    const directory = path.dirname(input.target.path);
+    const directory = path.dirname(target.path);
     const temporary = path.join(directory, `.${path.basename(KEIYAKU_FILE)}.${process.pid}.${randomUUID()}.tmp`);
     try {
         await fs.mkdir(directory, { recursive: true });
-        await fs.writeFile(temporary, renderCurrentContractView(input.lifecycle), { encoding: "utf8", flag: "wx" });
-        if ((await resolveCommitOrNull(input.stableRoot, REPOSITORY_LEDGER_REF)) !== input.lifecycle.observedLedgerHead) {
+        await fs.writeFile(temporary, renderCarrier(input.lifecycle), { encoding: "utf8", flag: "wx" });
+        if (!await hasExpectedTarget()) {
             await fs.unlink(temporary);
-            return { status: "failed", ledgerHead: input.lifecycle.observedLedgerHead, target: input.target.path, cause: "authoritative ledger head changed before carrier replacement" };
+            return { status: "failed", contractHead: input.lifecycle.contractHead, target: target.path, cause: "contract carrier target changed before replacement" };
         }
-        await (input.contractViewWriter?.replace ?? fs.rename)(temporary, input.target.path);
-        const [activeHead, carrierIdentity] = await Promise.all([
-            resolveCommitOrNull(input.stableRoot, REPOSITORY_LEDGER_REF),
-            readCarrierIdentity(input.target.path),
-        ]);
-        if (activeHead !== input.lifecycle.observedLedgerHead ||
-            !carrierMatches(carrierIdentity, input.contractId, input.lifecycle.observedLedgerHead)) {
-            return { status: "failed", ledgerHead: input.lifecycle.observedLedgerHead, target: input.target.path, cause: "carrier post-check did not prove the published contract identity and ledger head" };
+        await (input.contractViewWriter?.replace ?? fs.rename)(temporary, target.path);
+        const verification = await verifyCarrier({ target: target.path, lifecycle: input.lifecycle });
+        if (!await hasExpectedTarget() || !carrierMatches(verification)) {
+            return { status: "failed", contractHead: input.lifecycle.contractHead, target: target.path, cause: "carrier post-check did not prove the published contract identity" };
         }
-        return { status: "materialized", ledgerHead: input.lifecycle.observedLedgerHead, target: input.target.path };
+        return { status: "materialized", contractHead: input.lifecycle.contractHead, target: target.path };
     }
     catch (error) {
         await fs.unlink(temporary).catch(() => undefined);
-        return { status: "failed", ledgerHead: input.lifecycle.observedLedgerHead, target: input.target.path, cause: diagnostic(error) };
+        return { status: "failed", contractHead: input.lifecycle.contractHead, target: target.path, cause: diagnostic(error) };
     }
 }
 export async function observe(stableRoot, contractId) {
@@ -237,34 +330,24 @@ export async function observe(stableRoot, contractId) {
     const target = await resolveContractCarrierTarget(stableRoot, contractId, bind);
     const targetRef = lifecycle.pins.target.ref;
     const deliveryRef = lifecycle.resources.deliveryRef;
-    const [targetHead, deliveryHead] = await Promise.all([
-        resolveCommitOrNull(stableRoot, targetRef),
-        resolveCommitOrNull(stableRoot, deliveryRef),
-    ]);
-    return { repository, lifecycle, target, pins: { ledgerHead: lifecycle.observedLedgerHead, target: { ref: targetRef, head: targetHead }, delivery: { ref: deliveryRef, head: deliveryHead } } };
-}
-export async function resolveCommitOrNull(cwd, ref) {
-    try {
-        return (await createGit(cwd).raw(["rev-parse", "--verify", `${ref}^{commit}`])).trim();
-    }
-    catch (error) {
-        if (errorContainsAnyPattern(error, MISSING_HEAD_PATTERNS))
-            return null;
-        throw wrapGitError(`rev-parse ${ref}`, error, cwd);
-    }
+    const heads = await resolveExactRefHeads(stableRoot, [targetRef, deliveryRef]);
+    const targetHead = heads.get(targetRef) ?? null;
+    const deliveryHead = heads.get(deliveryRef) ?? null;
+    if (repository.observedLedgerHead === null)
+        throw new FlowError("INTERNAL_STATE", "accepted contract has no repository ledger observation");
+    return { repository, lifecycle, target, pins: { repositoryLedgerHead: repository.observedLedgerHead, target: { ref: targetRef, head: targetHead }, delivery: { ref: deliveryRef, head: deliveryHead } } };
 }
 installCarrierRuntimePorts({
     acceptedBind,
     acquireGate,
     carrierMatches,
     checkCancellation,
+    expectedCarrierIdentity,
     observe,
     observedLedgerHead,
-    projectRenewDeliveryWorktree,
     publishCarrier,
-    readCarrierIdentity,
+    verifyCarrier,
     reconcileFoldedDeliveryWorktree,
     releaseGate,
-    resolveCommitOrNull,
     retireTerminalHereCarrier,
 });

package/build/core/contract-view.js

@@ -1,6 +1,7 @@
 import { shortCommitHash } from "../git/commits.js";
-import { effectiveCriteria } from "./lifecycle-history.js";
+import { effectiveCriteria, effectiveVerification } from "./lifecycle-history.js";
 import { renderScopeFragment } from "./scope.js";
+import { renderVerificationDeclarations } from "./verification-declaration.js";
 import { currentLifecycleState, } from "./repository-ledger/read-model.js";
 export { currentLifecycleState } from "./repository-ledger/read-model.js";
 const VERB_COLUMN_WIDTH = 11;
@@ -227,6 +228,7 @@ export function renderContractView(input) {
             "",
         ].join("\n");
     }
+    const verification = effectiveVerification(input.entries);
     return [
         `# ${bind.data.title}`,
         "",
@@ -255,8 +257,8 @@ export function renderContractView(input) {
         "## Criteria",
         ...effectiveCriteria(input.entries).map((criterion) => `- ${criterion}`),
         "",
-        ...(bind.data.verification.length > 0
-            ? ["## Verification", ...bind.data.verification.map((declaration) => `- ${declaration}`), ""]
+        ...(verification.length > 0
+            ? ["## Verification", renderVerificationDeclarations(verification), ""]
             : []),
         ...(bind.data.extensions.length > 0
             ? [
@@ -270,12 +272,47 @@ export function renderContractView(input) {
         "",
     ].join("\n");
 }
-export function renderCurrentContractView(model) {
+/** Exact UTF-8/LF carrier body; metadata and diagnostic renderings stay outside it. */
+export function renderCanonicalCarrierBody(model) {
+    const entries = model.history.map(({ entry }) => entry);
+    const bind = entries.find((entry) => entry.kind === "bind");
+    if (!bind)
+        throw new Error(`contract ${model.contract} has no bind body to render`);
+    const verification = effectiveVerification(entries);
+    return [
+        `# ${bind.data.title}`,
+        "",
+        "## Context",
+        bind.data.context,
+        "",
+        "## Objective",
+        bind.data.objective,
+        "",
+        "## Design & Approach",
+        bind.data.design,
+        "",
+        "## Scope",
+        ...renderScopeFragment(model.effectiveScope).split("\n"),
+        "",
+        "## Criteria",
+        ...effectiveCriteria(entries).map((criterion) => `- ${criterion}`),
+        "",
+        ...(verification.length > 0
+            ? ["## Verification", renderVerificationDeclarations(verification), ""]
+            : []),
+        ...(bind.data.extensions.length > 0
+            ? bind.data.extensions.flatMap((extension) => extension.content.length > 0
+                ? [`## ${extension.title}`, extension.content, ""]
+                : [`## ${extension.title}`, ""])
+            : []),
+    ].join("\n").replace(/\n*$/, "\n");
+}
+export function renderCurrentContractView(model, observedLedgerHead) {
     const entries = model.history.map(({ entry }) => entry);
     return renderContractView({
         id: model.contract,
         entries,
-        ledgerHead: model.observedLedgerHead,
+        ledgerHead: observedLedgerHead ?? undefined,
         state: currentLifecycleState(model),
         effectiveScope: model.effectiveScope,
     });

package/build/core/contract.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { verificationDeclarationSchema } from "./verification-declaration.js";
 export const contractStateSchema = z.enum(["bound", "active", "petitioned", "claimed", "forfeited"]);
 export const contractRecordSchema = z
     .object({
@@ -9,7 +10,7 @@ export const contractRecordSchema = z
     design: z.string().trim().min(1),
     scope: z.array(z.string().trim().min(1)).min(1),
     criteria: z.array(z.string().trim().min(1)).min(1),
-    verification: z.array(z.string().trim().min(1)).min(1),
+    verification: z.array(verificationDeclarationSchema),
     base: z.string().trim().min(1),
     place: z.string().trim().min(1).nullable().optional(),
     after: z.array(z.string().trim().min(1)),