@astrosheep/keiyaku 2.9.8 → 2.9.10

package/build/core/renew-build.js

@@ -0,0 +1,424 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertHostObjectId, deriveHostGitCoordinates, readCommitObject } from "./repository-ledger/git-object-store.js";
+import { runGitProcess, runGitProcessBytes } from "../git/core.js";
+import { stableRepoRoot } from "./worktree-path.js";
+const SCRATCH_VERSION = 1;
+const SCRATCH_DIRECTORY = path.join("keiyaku", "renew-scratch");
+const SCRATCH_STATE_FILE = "state.json";
+const SCRATCH_FILES_DIRECTORY = "files";
+const SCRATCH_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export class RenewBuildError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "RenewBuildError";
+    }
+}
+export function assertScratchName(scratchName) {
+    if (!SCRATCH_NAME_PATTERN.test(scratchName)) {
+        throw new RenewBuildError("INVALID_SCRATCH_NAME", `invalid renew scratch name ${JSON.stringify(scratchName)}`);
+    }
+}
+export function scratchPaths(scratchBase, scratchName) {
+    assertScratchName(scratchName);
+    const root = path.join(scratchBase, scratchName);
+    return {
+        root,
+        state: path.join(root, SCRATCH_STATE_FILE),
+        files: path.join(root, SCRATCH_FILES_DIRECTORY),
+    };
+}
+export async function renewScratchBase(cwd) {
+    const commonDirectory = (await successfulGit(cwd, [
+        "rev-parse",
+        "--path-format=absolute",
+        "--git-common-dir",
+    ])).trim();
+    if (!path.isAbsolute(commonDirectory)) {
+        throw new RenewBuildError("GIT_RENEW_BUILD_FAILED", `Git common directory is not absolute: ${commonDirectory}`);
+    }
+    return path.join(await fs.realpath(commonDirectory), SCRATCH_DIRECTORY);
+}
+function gitFailure(args, detail, cause) {
+    return new RenewBuildError("GIT_RENEW_BUILD_FAILED", `git ${args.join(" ")} failed: ${detail}`, cause ? { cause } : undefined);
+}
+export async function successfulGit(cwd, args, options) {
+    const result = await runGitProcess(cwd, args, options);
+    if (result.status !== 0 || result.error) {
+        throw gitFailure(args, result.stderr.trim() || result.error?.message || `exit ${String(result.status)}`, result.error);
+    }
+    return result.stdout;
+}
+export async function assertTree(cwd, coordinates, tree) {
+    assertHostObjectId(coordinates, tree);
+    const result = await runGitProcess(cwd, ["cat-file", "-t", tree]);
+    if (result.status !== 0 || result.error || result.stdout.trim() !== "tree") {
+        throw new RenewBuildError("INVALID_RENEW_RESOLUTION", `renew resolution ${tree} is not a tree`, {
+            cause: result.error,
+        });
+    }
+}
+function parseIdentity(header, label, objectId) {
+    const value = header.slice(label.length + 1);
+    const emailEnd = value.lastIndexOf("> ");
+    const emailStart = emailEnd < 0 ? -1 : value.lastIndexOf(" <", emailEnd);
+    if (emailStart <= 0 || emailEnd <= emailStart || !/^\d+ [+-]\d{4}$/.test(value.slice(emailEnd + 2))) {
+        throw new RenewBuildError("INVALID_DELIVERY_CHAIN", `commit ${objectId} has an invalid ${label} header`);
+    }
+    return {
+        name: value.slice(0, emailStart),
+        email: value.slice(emailStart + 2, emailEnd),
+        date: value.slice(emailEnd + 2),
+    };
+}
+async function readOriginalCommit(cwd, coordinates, objectId, expectedParent) {
+    const commit = await readCommitObject(cwd, coordinates, objectId);
+    if (commit.parents.length !== 1 || commit.parents[0] !== expectedParent) {
+        throw new RenewBuildError("INVALID_DELIVERY_CHAIN", `delivery commit ${objectId} must have exactly parent ${expectedParent}`);
+    }
+    const raw = await successfulGit(cwd, ["cat-file", "commit", objectId]);
+    const headers = raw.slice(0, raw.indexOf("\n\n")).split("\n");
+    const authorRows = headers.filter((row) => row.startsWith("author "));
+    const committerRows = headers.filter((row) => row.startsWith("committer "));
+    if (authorRows.length !== 1 || committerRows.length !== 1) {
+        throw new RenewBuildError("INVALID_DELIVERY_CHAIN", `commit ${objectId} has invalid identity headers`);
+    }
+    return {
+        objectId,
+        parent: expectedParent,
+        message: commit.messageBytes,
+        author: parseIdentity(authorRows[0], "author", objectId),
+        committer: parseIdentity(committerRows[0], "committer", objectId),
+    };
+}
+export async function validateCoordinates(input) {
+    for (const coordinate of [input.oldBase, input.oldHead, input.newBase]) {
+        assertHostObjectId(input.coordinates, coordinate);
+        await readCommitObject(input.cwd, input.coordinates, coordinate);
+    }
+    if (input.deliveryCommits.length === 0) {
+        if (input.oldHead !== input.oldBase) {
+            throw new RenewBuildError("INVALID_DELIVERY_CHAIN", "an empty delivery chain requires oldHead to equal oldBase");
+        }
+        return [];
+    }
+    if (input.deliveryCommits.at(-1) !== input.oldHead) {
+        throw new RenewBuildError("INVALID_DELIVERY_CHAIN", "the delivery chain must terminate at oldHead");
+    }
+    const commits = [];
+    let parent = input.oldBase;
+    for (const objectId of input.deliveryCommits) {
+        assertHostObjectId(input.coordinates, objectId);
+        const commit = await readOriginalCommit(input.cwd, input.coordinates, objectId, parent);
+        commits.push(commit);
+        parent = objectId;
+    }
+    return commits;
+}
+async function mergeCommitTree(input) {
+    const args = [
+        "--no-replace-objects",
+        "merge-tree",
+        "--write-tree",
+        `--merge-base=${input.original.parent}`,
+        input.currentHead,
+        input.original.objectId,
+    ];
+    const result = await runGitProcess(input.cwd, args);
+    if (result.error || (result.status !== 0 && result.status !== 1)) {
+        throw gitFailure(args, result.stderr.trim() || result.error?.message || `exit ${String(result.status)}`, result.error);
+    }
+    const lines = result.stdout.split(/\r?\n/);
+    const tree = lines[0]?.trim() ?? "";
+    assertHostObjectId(input.coordinates, tree);
+    await assertTree(input.cwd, input.coordinates, tree);
+    if (result.status === 0)
+        return { status: "clean", tree };
+    const paths = Array.from(new Set(lines.flatMap((line) => {
+        const match = /^\d{6} [0-9a-f]+ [123]\t(.+)$/.exec(line);
+        return match ? [match[1]] : [];
+    })));
+    return { status: "conflict", tree, paths };
+}
+export async function buildCommit(cwd, coordinates, original, tree, parent) {
+    await assertTree(cwd, coordinates, tree);
+    const args = ["commit-tree", tree, "-p", parent];
+    const result = await runGitProcessBytes(cwd, args, {
+        input: original.message,
+        env: {
+            GIT_AUTHOR_NAME: original.author.name,
+            GIT_AUTHOR_EMAIL: original.author.email,
+            GIT_AUTHOR_DATE: original.author.date,
+            GIT_COMMITTER_NAME: original.committer.name,
+            GIT_COMMITTER_EMAIL: original.committer.email,
+            GIT_COMMITTER_DATE: original.committer.date,
+        },
+    });
+    if (result.status !== 0 || result.error) {
+        throw gitFailure(args, result.stderr.toString("utf8").trim() || result.error?.message || `exit ${String(result.status)}`, result.error);
+    }
+    const objectId = result.stdout.toString("utf8").trim();
+    assertHostObjectId(coordinates, objectId);
+    return objectId;
+}
+export function interrupted(signal) {
+    if (signal?.aborted) {
+        throw new RenewBuildError("RENEW_BUILD_INTERRUPTED", "detached renew build was interrupted", {
+            cause: signal.reason instanceof Error ? signal.reason : undefined,
+        });
+    }
+}
+async function materializeConflict(cwd, scratch, tree) {
+    await fs.rm(scratch.files, { recursive: true, force: true });
+    await fs.mkdir(scratch.files, { recursive: true });
+    const listingArgs = ["ls-tree", "-r", "-z", "--full-tree", tree];
+    const listing = await runGitProcessBytes(cwd, listingArgs);
+    if (listing.status !== 0 || listing.error) {
+        throw gitFailure(listingArgs, listing.stderr.toString("utf8").trim() || listing.error?.message || `exit ${String(listing.status)}`, listing.error);
+    }
+    for (const row of listing.stdout.toString("utf8").split("\0").filter(Boolean)) {
+        const match = /^(\d{6}) (blob|commit) ([0-9a-f]+)\t([\s\S]+)$/.exec(row);
+        if (!match)
+            throw new RenewBuildError("GIT_RENEW_BUILD_FAILED", `invalid ls-tree row while materializing renew scratch`);
+        const [, mode, type, objectId, relative] = match;
+        const destination = path.resolve(scratch.files, relative);
+        const withinScratch = path.relative(scratch.files, destination);
+        if (withinScratch === "" || path.isAbsolute(withinScratch) || withinScratch === ".." || withinScratch.startsWith(`..${path.sep}`)) {
+            throw new RenewBuildError("GIT_RENEW_BUILD_FAILED", `unsafe path in renew conflict tree: ${JSON.stringify(relative)}`);
+        }
+        await fs.mkdir(path.dirname(destination), { recursive: true });
+        if (type === "commit") {
+            await fs.writeFile(destination, `${objectId}\n`, "utf8");
+            continue;
+        }
+        const blobArgs = ["cat-file", "blob", objectId];
+        const blob = await runGitProcessBytes(cwd, blobArgs);
+        if (blob.status !== 0 || blob.error) {
+            throw gitFailure(blobArgs, blob.stderr.toString("utf8").trim() || blob.error?.message || `exit ${String(blob.status)}`, blob.error);
+        }
+        if (mode === "120000") {
+            await fs.symlink(blob.stdout.toString("utf8"), destination);
+        }
+        else {
+            await fs.writeFile(destination, blob.stdout, { mode: mode === "100755" ? 0o755 : 0o644 });
+        }
+    }
+}
+async function writeScratchState(scratch, state) {
+    const temporary = `${scratch.state}.next`;
+    await fs.rm(temporary, { force: true });
+    await fs.writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+    await fs.rename(temporary, scratch.state);
+}
+export function evidenceResult(state) {
+    return {
+        observedLedgerHead: state.observedLedgerHead,
+        deliveryRef: state.deliveryRef,
+        targetRef: state.targetRef,
+        effectiveScope: [...state.effectiveScope],
+        oldBase: state.oldBase,
+        oldHead: state.oldHead,
+        newBase: state.newBase,
+        deliveryCommits: [...state.deliveryCommits],
+        evidenceMap: { ...state.evidenceMap },
+    };
+}
+async function persistConflict(cwd, scratchBase, state, create) {
+    const scratch = scratchPaths(scratchBase, state.scratchName);
+    if (create) {
+        await fs.mkdir(path.dirname(scratch.root), { recursive: true });
+        try {
+            await fs.mkdir(scratch.root);
+        }
+        catch (error) {
+            if (error.code === "EEXIST") {
+                throw new RenewBuildError("RENEW_SCRATCH_EXISTS", `renew scratch ${state.scratchName} already exists`, { cause: error });
+            }
+            throw error;
+        }
+    }
+    await materializeConflict(cwd, scratch, state.conflictTree);
+    await writeScratchState(scratch, state);
+    return {
+        status: "conflict",
+        ...evidenceResult(state),
+        scratchName: state.scratchName,
+        scratchPath: scratch.root,
+        filesPath: scratch.files,
+        conflictCommit: state.conflictCommit,
+        conflictPaths: [...state.conflictPaths],
+    };
+}
+export async function replayFrom(input) {
+    let currentHead = input.state.currentHead;
+    for (let index = input.state.nextIndex; index < input.commits.length; index += 1) {
+        interrupted(input.signal);
+        const original = input.commits[index];
+        const merged = await mergeCommitTree({
+            cwd: input.cwd,
+            coordinates: input.coordinates,
+            original,
+            currentHead,
+        });
+        if (merged.status === "conflict") {
+            const state = {
+                ...input.state,
+                nextIndex: index,
+                currentHead,
+                conflictCommit: original.objectId,
+                conflictTree: merged.tree,
+                conflictPaths: merged.paths,
+            };
+            return await persistConflict(input.cwd, input.scratchBase, state, input.createScratch);
+        }
+        currentHead = await buildCommit(input.cwd, input.coordinates, original, merged.tree, currentHead);
+        input.state.evidenceMap[original.objectId] = currentHead;
+        input.state.currentHead = currentHead;
+        input.state.nextIndex = index + 1;
+    }
+    interrupted(input.signal);
+    return {
+        status: "clean",
+        ...evidenceResult(input.state),
+        newHead: currentHead,
+    };
+}
+export async function buildDetachedRenewChain(input) {
+    assertScratchName(input.scratchName);
+    const repositoryRoot = await stableRepoRoot(input.cwd);
+    const scratchBase = await renewScratchBase(repositoryRoot);
+    const coordinates = await deriveHostGitCoordinates(repositoryRoot);
+    const commits = await validateCoordinates({ ...input, cwd: repositoryRoot, coordinates });
+    const existingScratch = scratchPaths(scratchBase, input.scratchName);
+    try {
+        await fs.lstat(existingScratch.root);
+        const state = await readScratchState(existingScratch);
+        if (state.observedLedgerHead !== input.observedLedgerHead
+            || state.deliveryRef !== input.deliveryRef
+            || state.targetRef !== input.targetRef
+            || state.oldBase !== input.oldBase
+            || state.oldHead !== input.oldHead
+            || state.newBase !== input.newBase
+            || JSON.stringify(state.effectiveScope) !== JSON.stringify(input.effectiveScope)
+            || JSON.stringify(state.deliveryCommits) !== JSON.stringify(input.deliveryCommits)) {
+            throw new RenewBuildError("RENEW_SCRATCH_EXISTS", `renew scratch ${input.scratchName} belongs to different coordinates`);
+        }
+        await validateScratchProgress(repositoryRoot, coordinates, state, commits);
+        return {
+            status: "conflict",
+            ...evidenceResult(state),
+            scratchName: state.scratchName,
+            scratchPath: existingScratch.root,
+            filesPath: existingScratch.files,
+            conflictCommit: state.conflictCommit,
+            conflictPaths: [...state.conflictPaths],
+        };
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const state = {
+        version: SCRATCH_VERSION,
+        scratchName: input.scratchName,
+        observedLedgerHead: input.observedLedgerHead,
+        deliveryRef: input.deliveryRef,
+        targetRef: input.targetRef,
+        effectiveScope: [...input.effectiveScope],
+        oldBase: input.oldBase,
+        oldHead: input.oldHead,
+        newBase: input.newBase,
+        deliveryCommits: [...input.deliveryCommits],
+        evidenceMap: {},
+        nextIndex: 0,
+        currentHead: input.newBase,
+        conflictCommit: "",
+        conflictTree: "",
+        conflictPaths: [],
+    };
+    return await replayFrom({
+        cwd: repositoryRoot,
+        scratchBase,
+        coordinates,
+        state,
+        commits,
+        createScratch: true,
+        signal: input.signal,
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export async function readScratchState(scratch) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await fs.readFile(scratch.state, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new RenewBuildError("RENEW_SCRATCH_NOT_FOUND", `renew scratch ${path.basename(scratch.root)} was not found`, { cause: error });
+        }
+        throw new RenewBuildError("INVALID_RENEW_SCRATCH", `cannot read renew scratch ${path.basename(scratch.root)}`, { cause: error });
+    }
+    if (!isRecord(parsed)
+        || parsed.version !== SCRATCH_VERSION
+        || parsed.scratchName !== path.basename(scratch.root)
+        || typeof parsed.observedLedgerHead !== "string"
+        || typeof parsed.deliveryRef !== "string"
+        || typeof parsed.targetRef !== "string"
+        || !Array.isArray(parsed.effectiveScope)
+        || parsed.effectiveScope.some((value) => typeof value !== "string")
+        || typeof parsed.oldBase !== "string"
+        || typeof parsed.oldHead !== "string"
+        || typeof parsed.newBase !== "string"
+        || !Array.isArray(parsed.deliveryCommits)
+        || parsed.deliveryCommits.some((value) => typeof value !== "string")
+        || !isRecord(parsed.evidenceMap)
+        || Object.values(parsed.evidenceMap).some((value) => typeof value !== "string")
+        || !Number.isSafeInteger(parsed.nextIndex)
+        || typeof parsed.currentHead !== "string"
+        || typeof parsed.conflictCommit !== "string"
+        || typeof parsed.conflictTree !== "string"
+        || !Array.isArray(parsed.conflictPaths)
+        || parsed.conflictPaths.some((value) => typeof value !== "string")) {
+        throw new RenewBuildError("INVALID_RENEW_SCRATCH", `renew scratch ${path.basename(scratch.root)} has invalid state`);
+    }
+    return parsed;
+}
+export async function treeFromScratchFiles(cwd, coordinates, scratch, state) {
+    const index = path.join(scratch.root, "continue.index");
+    await fs.rm(index, { force: true });
+    const env = { GIT_INDEX_FILE: index, GIT_WORK_TREE: scratch.files };
+    try {
+        await successfulGit(cwd, ["read-tree", state.conflictTree], { env });
+        await successfulGit(cwd, ["add", "--all", "--", "."], { env });
+        const tree = (await successfulGit(cwd, ["write-tree"], { env })).trim();
+        await assertTree(cwd, coordinates, tree);
+        return tree;
+    }
+    finally {
+        await fs.rm(index, { force: true });
+    }
+}
+export async function validateScratchProgress(cwd, coordinates, state, commits) {
+    if (state.nextIndex < 0 || state.nextIndex >= commits.length || commits[state.nextIndex]?.objectId !== state.conflictCommit) {
+        throw new RenewBuildError("INVALID_RENEW_SCRATCH", "renew scratch does not identify the stopped delivery commit");
+    }
+    let parent = state.newBase;
+    for (let index = 0; index < state.nextIndex; index += 1) {
+        const original = commits[index].objectId;
+        const rewritten = state.evidenceMap[original];
+        if (!rewritten)
+            throw new RenewBuildError("INVALID_RENEW_SCRATCH", `renew scratch is missing evidence for ${original}`);
+        const commit = await readCommitObject(cwd, coordinates, rewritten);
+        if (commit.parents.length !== 1 || commit.parents[0] !== parent) {
+            throw new RenewBuildError("INVALID_RENEW_SCRATCH", `rewritten commit ${rewritten} is not attached to its scratch predecessor`);
+        }
+        parent = rewritten;
+    }
+    if (parent !== state.currentHead || Object.keys(state.evidenceMap).length !== state.nextIndex) {
+        throw new RenewBuildError("INVALID_RENEW_SCRATCH", "renew scratch evidence does not match its stopped head");
+    }
+}

package/build/core/renew-plan.js

@@ -0,0 +1,239 @@
+import { FlowError } from "../flow-error.js";
+import { currentLifecycleState } from "./repository-ledger/read-model.js";
+import { buildDetachedRenewChain, continueDetachedRenewChain, renewScratchName } from "./renew-rewrite.js";
+import { hasStrandableProjectionGeneration } from "./projection/index.js";
+import { runGitProcess } from "../git/core.js";
+import { assertCleanTrackedWorkingTree } from "../git/worktree.js";
+import { normalizeScopePattern } from "./scope.js";
+import { captureFoldedRenewSeal } from "./seal.js";
+function assertOperable(contractId, model) {
+    if ((model.phase !== "active" && model.phase !== "sealed") || model.petition.state !== "none") {
+        const state = currentLifecycleState(model);
+        throw new FlowError("INTERNAL_STATE", `contract ${contractId} cannot renew from state ${state.state}`);
+    }
+}
+export function checkCancellation(signal) {
+    if (signal?.aborted)
+        throw new FlowError("CARRIER_GATE_CANCELLED", "contract lifecycle operation cancelled before durable effects");
+}
+async function deliveryChain(cwd, oldBase, oldHead) {
+    if (oldBase === oldHead)
+        return [];
+    const result = await runGitProcess(cwd, ["rev-list", "--reverse", "--ancestry-path", `${oldBase}..${oldHead}`]);
+    if (result.status !== 0 || result.error) {
+        throw new FlowError("INTERNAL_STATE", result.stderr.trim() || result.error?.message || "cannot read renew delivery chain", { cause: result.error });
+    }
+    return result.stdout.split(/\r?\n/).filter(Boolean);
+}
+export function scopeEntry(input) {
+    const patterns = (input.appendScope ?? []).map(normalizeScopePattern);
+    return patterns.length === 0 ? null : {
+        v: 1,
+        kind: "amend",
+        contract: input.contractId,
+        at: new Date(input.nowMs).toISOString(),
+        actor: input.actor,
+        data: { amendment: "Scope extended by lifecycle command.", scopeDelta: { add: patterns } },
+    };
+}
+function effectiveScope(model, amendment) {
+    return [...model.effectiveScope, ...(amendment?.data.scopeDelta?.add ?? [])];
+}
+async function gitTree(cwd, revision) {
+    const result = await runGitProcess(cwd, ["rev-parse", "--verify", `${revision}^{tree}`]);
+    return result.status === 0 && !result.error ? result.stdout.trim() : null;
+}
+async function acceptedRenewIsReplayable(targetRoot, entry) {
+    const [index, oldTree, newTree, worktree] = await Promise.all([
+        runGitProcess(targetRoot, ["write-tree"]),
+        gitTree(targetRoot, entry.data.oldHead),
+        gitTree(targetRoot, entry.data.newHead),
+        runGitProcess(targetRoot, ["diff-files", "--quiet"]),
+    ]);
+    if (index.status !== 0 || index.error || oldTree === null || newTree === null)
+        return false;
+    const indexTree = index.stdout.trim();
+    return (indexTree === oldTree || indexTree === newTree) && worktree.status === 0 && !worktree.error;
+}
+async function acceptedRenewFromReplay(model, targetRoot, deliveryHead, targetHead, replay) {
+    if (replay.state !== "verb-committed")
+        return null;
+    const renewIndex = replay.transaction.entries.findIndex((entry) => entry.kind === "renew");
+    const sealIndex = replay.transaction.entries.findIndex((entry) => entry.kind === "seal");
+    const renew = renewIndex < 0 ? undefined : replay.transaction.entries[renewIndex];
+    const seal = sealIndex < 0 ? undefined : replay.transaction.entries[sealIndex];
+    if (renew?.kind !== "renew" ||
+        seal?.kind !== "seal" ||
+        seal.data.sealedBy !== "renew" ||
+        renew.data.newBase !== targetHead ||
+        renew.data.newHead !== deliveryHead ||
+        model.pins.base !== renew.data.newBase ||
+        model.pins.delivery !== renew.data.newHead ||
+        !await acceptedRenewIsReplayable(targetRoot, renew))
+        return null;
+    return {
+        transactionObjectId: replay.transaction.transactionObjectId,
+        renewObjectId: replay.transaction.entryObjectIds[renewIndex],
+        sealObjectId: replay.transaction.entryObjectIds[sealIndex],
+        entry: structuredClone(renew),
+        seal: structuredClone(seal),
+    };
+}
+function acceptedFreshScopeFromReplay(model, replay, expected) {
+    if (replay.state !== "verb-committed" || !expected)
+        return null;
+    const accepted = replay.transaction.entries.at(-1);
+    if (accepted?.kind !== "amend")
+        return null;
+    return accepted.data.amendment === expected.data.amendment
+        && JSON.stringify(accepted.data.scopeDelta ?? null) === JSON.stringify(expected.data.scopeDelta ?? null)
+        ? { transactionObjectId: replay.transaction.transactionObjectId, entry: structuredClone(accepted) }
+        : null;
+}
+export async function admitRenew(session, input, replay, expected) {
+    const model = session.lifecycle;
+    assertOperable(input.contractId, model);
+    if (session.target.status !== "available")
+        throw new FlowError("INTERNAL_STATE", session.target.reason);
+    const oldHead = session.pins.delivery.head;
+    const newBase = session.pins.target.head;
+    if (!oldHead || !newBase)
+        throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} has missing delivery or target coordinates`);
+    if (session.pins.delivery.ref !== model.resources.deliveryRef || session.pins.target.ref !== model.pins.target.ref) {
+        throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} carrier pins disagree with the lifecycle read model`);
+    }
+    const amendment = scopeEntry(input);
+    const acceptedReplay = await acceptedRenewFromReplay(model, session.target.root, oldHead, newBase, replay);
+    if (acceptedReplay) {
+        return {
+            model,
+            repository: session.repository,
+            targetRoot: session.target.root,
+            oldBase: acceptedReplay.entry.data.oldBase,
+            oldFence: acceptedReplay.seal.data.oldFence,
+            oldHead: acceptedReplay.entry.data.oldHead,
+            newBase: acceptedReplay.entry.data.newBase,
+            deliveryRef: model.resources.deliveryRef,
+            targetRef: model.pins.target.ref,
+            effectiveScope: [...model.effectiveScope],
+            amendment: null,
+            acceptedReplay,
+            acceptedScopeReplay: null,
+        };
+    }
+    const acceptedScopeReplay = acceptedFreshScopeFromReplay(model, replay, amendment);
+    if (acceptedScopeReplay) {
+        return {
+            model,
+            repository: session.repository,
+            targetRoot: session.target.root,
+            oldBase: model.pins.base,
+            oldFence: model.pins.delivery,
+            oldHead,
+            newBase,
+            deliveryRef: model.resources.deliveryRef,
+            targetRef: model.pins.target.ref,
+            effectiveScope: [...model.effectiveScope],
+            amendment: null,
+            acceptedReplay: null,
+            acceptedScopeReplay,
+        };
+    }
+    await assertCleanTrackedWorkingTree(session.target.root);
+    if (await hasStrandableProjectionGeneration({ cwd: session.stableRoot, commissionId: input.contractId, deliveryWorktree: session.target.root, nowMs: input.nowMs })) {
+        throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} has a live projection that owns the delivery worktree`);
+    }
+    const scope = effectiveScope(model, amendment);
+    const admission = {
+        model,
+        repository: session.repository,
+        targetRoot: session.target.root,
+        oldBase: model.pins.base,
+        oldFence: model.pins.delivery,
+        oldHead,
+        newBase,
+        deliveryRef: model.resources.deliveryRef,
+        targetRef: model.pins.target.ref,
+        effectiveScope: scope,
+        amendment,
+        acceptedReplay: null,
+        acceptedScopeReplay: null,
+    };
+    if (expected && (expected.observedLedgerHead !== model.observedLedgerHead ||
+        expected.deliveryRef !== admission.deliveryRef ||
+        expected.targetRef !== admission.targetRef ||
+        expected.oldBase !== admission.oldBase ||
+        expected.oldHead !== admission.oldHead ||
+        expected.newBase !== admission.newBase ||
+        JSON.stringify(expected.effectiveScope) !== JSON.stringify(scope))) {
+        throw new FlowError("CONCURRENT_MODIFICATION", `renew scratch coordinates no longer match ${input.contractId}`);
+    }
+    return admission;
+}
+export async function prepareRenew(admission, input, continuation) {
+    if (admission.acceptedReplay || admission.acceptedScopeReplay)
+        return { build: null, capture: null, prefix: [], entry: null };
+    if (admission.oldBase === admission.newBase) {
+        return { build: null, capture: null, prefix: admission.amendment ? [admission.amendment] : [], entry: null };
+    }
+    const build = continuation
+        ? await continueDetachedRenewChain({ cwd: input.cwd, scratchName: continuation.scratch.scratchName, resolution: continuation.resolution, signal: input.signal })
+        : await buildDetachedRenewChain({
+            cwd: input.cwd,
+            scratchName: renewScratchName(input.contractId),
+            observedLedgerHead: admission.model.observedLedgerHead,
+            deliveryRef: admission.deliveryRef,
+            targetRef: admission.targetRef,
+            effectiveScope: admission.effectiveScope,
+            oldBase: admission.oldBase,
+            oldHead: admission.oldHead,
+            newBase: admission.newBase,
+            deliveryCommits: await deliveryChain(input.cwd, admission.oldBase, admission.oldHead),
+            signal: input.signal,
+        });
+    if (build.status === "conflict")
+        return { build, capture: null, prefix: [], entry: null };
+    const capture = await captureFoldedRenewSeal({
+        cwd: input.cwd,
+        contract: admission.model.contract,
+        intent: admission.model.intent,
+        receiptSegmentOpen: admission.model.seal === null,
+        deliveryFence: admission.model.pins.delivery,
+        effectiveScope: admission.model.effectiveScope,
+        pendingScopeOverlay: admission.amendment?.data.scopeDelta?.add ?? [],
+        receiptHead: admission.oldHead,
+        contentBase: admission.newBase,
+        contentHead: build.newHead,
+    });
+    if (!capture)
+        throw new FlowError("NO_OPEN_ARC", `contract ${input.contractId} has no active folded receipt segment to renew`);
+    const { scopeViolationEvidence: _scopeViolationEvidence, ...durableCapture } = capture;
+    const seal = {
+        v: 2,
+        kind: "seal",
+        contract: input.contractId,
+        at: new Date(input.nowMs).toISOString(),
+        actor: "engine",
+        data: { ...durableCapture, newFence: build.newHead, sealedBy: "renew" },
+    };
+    const entry = {
+        v: 1,
+        kind: "renew",
+        contract: input.contractId,
+        at: new Date(input.nowMs).toISOString(),
+        actor: input.actor,
+        data: { oldBase: admission.oldBase, newBase: admission.newBase, oldHead: admission.oldHead, newHead: build.newHead },
+    };
+    const prefix = admission.amendment ? [admission.amendment, seal] : [seal];
+    return { build, capture, prefix, entry };
+}
+export function sameAdmission(current, pinned) {
+    return current.model.observedLedgerHead === pinned.model.observedLedgerHead &&
+        current.oldBase === pinned.oldBase && current.oldFence === pinned.oldFence &&
+        current.oldHead === pinned.oldHead && current.newBase === pinned.newBase &&
+        current.deliveryRef === pinned.deliveryRef && current.targetRef === pinned.targetRef &&
+        current.targetRoot === pinned.targetRoot &&
+        JSON.stringify(current.effectiveScope) === JSON.stringify(pinned.effectiveScope) &&
+        current.acceptedReplay?.renewObjectId === pinned.acceptedReplay?.renewObjectId &&
+        current.acceptedScopeReplay?.transactionObjectId === pinned.acceptedScopeReplay?.transactionObjectId;
+}