@aefree/pi-plastic 0.7.5 → 0.8.0

package/src/diff/text.ts

@@ -0,0 +1,187 @@
+import { isUtf8 } from "node:buffer";
+import { promises as fs } from "node:fs";
+import { join, extname } from "path";
+import { spawnAndCollect, getDiffExecutable } from "../execution/process";
+import { getActiveAbortSignal, commandExecutionStorage } from "../execution/context";
+import { tmpdir } from "os";
+import { runCm } from "../execution/cm";
+
+export const DIFF_OUTPUT_MAX_CHARS = 60_000;
+
+export type TextDiffResult = {
+    backend: "diff";
+    changed: boolean;
+    binary: boolean;
+    output: string;
+    truncated: boolean;
+    totalChars: number;
+};
+
+// Do not classify serialized Unity YAML by its extension or importer metadata:
+// valid UTF-8 YAML is text, while NUL-containing or invalid UTF-8 bytes are binary.
+
+export const isBinaryContent = (content: Buffer): boolean => content.includes(0) || !isUtf8(content);
+
+export const stableDiffHeaders = (output: string, leftLabel: string, rightLabel: string): string =>
+{
+    const lines = output.split(/\r?\n/);
+    // Both GNU and BSD `diff -u` put the source paths in the first two header
+    // lines. Replacing only those lines keeps hunk content verbatim while never
+    // leaking package-owned temporary paths or host-specific timestamps.
+    if (lines[0]?.startsWith("--- "))
+    {
+        lines[0] = `--- ${leftLabel}`;
+    }
+    if (lines[1]?.startsWith("+++ "))
+    {
+        lines[1] = `+++ ${rightLabel}`;
+    }
+    return lines.join("\n").replace(/\n+$/, "");
+};
+
+export const boundDiffOutput = (output: string): Pick<TextDiffResult, "output" | "truncated" | "totalChars"> =>
+{
+    const totalChars = output.length;
+    if (totalChars <= DIFF_OUTPUT_MAX_CHARS)
+    {
+        return { output, truncated: false, totalChars };
+    }
+
+    return {
+        output: `${output.slice(0, DIFF_OUTPUT_MAX_CHARS)}\n\n[Diff output truncated at ${DIFF_OUTPUT_MAX_CHARS} characters; inspect a narrower file or use a review patch for the complete change.]`,
+        truncated: true,
+        totalChars,
+    };
+};
+
+export const runPortableTextDiff = async (
+    leftPath: string,
+    rightPath: string,
+    _cwd: string,
+    leftLabel: string,
+    rightLabel: string,
+): Promise<TextDiffResult> =>
+{
+    const [leftContent, rightContent] = await Promise.all([fs.readFile(leftPath), fs.readFile(rightPath)]);
+    if (isBinaryContent(leftContent) || isBinaryContent(rightContent))
+    {
+        return { backend: "diff", changed: !leftContent.equals(rightContent), binary: true, output: "", truncated: false, totalChars: 0 };
+    }
+
+    // Do not pass either workspace or historical source paths to diff: a
+    // Unicode workspace path reproduces an Invalid argument failure in the
+    // configured Windows GnuWin32 backend. Labels intentionally stay out of
+    // argv and are restored by stableDiffHeaders below.
+    const materializationDir = await createAsciiTempDirectory("pi-plastic-diff-");
+    const materializedLeftPath = join(materializationDir, `left${safeTempExtension(leftPath)}`);
+    const materializedRightPath = join(materializationDir, `right${safeTempExtension(rightPath)}`);
+    try
+    {
+        await Promise.all([
+            fs.writeFile(materializedLeftPath, leftContent),
+            fs.writeFile(materializedRightPath, rightContent),
+        ]);
+        const { stdout, stderr, exitCode, aborted, stdoutTruncated, stdoutTotalChars } = await spawnAndCollect(
+            getDiffExecutable(),
+            ["-u", materializedLeftPath, materializedRightPath],
+            materializationDir,
+            undefined,
+            getActiveAbortSignal(),
+            { ...commandExecutionStorage.getStore(), outputLimitChars: DIFF_OUTPUT_MAX_CHARS },
+        );
+        if (aborted)
+        {
+            throw new Error("Text diff was aborted.");
+        }
+        if (exitCode > 1)
+        {
+            const diagnostic = [stdout, stderr].filter(Boolean).join("\n").trim();
+            const sanitized = diagnostic
+                .split(materializedLeftPath).join(leftLabel)
+                .split(materializedRightPath).join(rightLabel);
+            throw new Error(sanitized || `Text diff failed with exit code ${exitCode}.`);
+        }
+
+        const normalized = stableDiffHeaders(stdout, leftLabel, rightLabel);
+        const bounded = stdoutTruncated
+            ? {
+                output: `${normalized}\n\n[Diff output truncated at ${DIFF_OUTPUT_MAX_CHARS} characters; inspect a narrower file or generate a review patch for the complete change.]`,
+                truncated: true,
+                totalChars: stdoutTotalChars ?? normalized.length,
+            }
+            : boundDiffOutput(normalized);
+        return { backend: "diff", changed: exitCode === 1, binary: false, ...bounded };
+    }
+    finally
+    {
+        await fs.rm(materializationDir, { recursive: true, force: true });
+    }
+};
+
+export const safeTempExtension = (pathValue: string): string =>
+{
+    const extension = extname(pathValue);
+    return /^\.[A-Za-z0-9]{1,12}$/.test(extension) ? extension : ".tmp";
+};
+
+export const isAsciiPath = (pathValue: string): boolean => /^[\x20-\x7e]*$/.test(pathValue);
+
+// GnuWin32 diff cannot reliably accept Unicode operands. Keep every package
+// materialization path ASCII-only; labels are restored after the backend exits.
+
+export const createAsciiTempDirectory = async (prefix: string): Promise<string> =>
+{
+    const temporaryRoot = tmpdir();
+    if (!isAsciiPath(temporaryRoot))
+    {
+        throw new Error("Text diff requires an ASCII-safe temporary directory because the configured backend cannot reliably accept Unicode paths. Set TEMP and TMP to a writable ASCII-only path.");
+    }
+    return fs.mkdtemp(join(temporaryRoot, prefix));
+};
+
+export const materializeRevision = async (revision: string, destination: string, workdir?: string): Promise<void> =>
+{
+    // --file keeps historical bytes out of the decoded stdout path. This is
+    // required for both reliable binary detection and Unity YAML text handling.
+    try
+    {
+        await runCm(["cat", revision, `--file=${destination}`], workdir);
+        const destinationStat = await fs.stat(destination).catch(() => null);
+        if (!destinationStat?.isFile())
+        {
+            throw new Error("Plastic did not materialize the requested historical file content.");
+        }
+    }
+    catch (error)
+    {
+        // cm cat --file can leave a zero-byte output on failure. The destination
+        // is package-owned, so remove it before surfacing a sanitized diagnostic.
+        await fs.rm(destination, { force: true }).catch(() => undefined);
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(message.split(destination).join("<package-owned-temp-file>"));
+    }
+};
+
+export const isNoDataError = (message: string): boolean =>
+{
+    const normalized = message.toLowerCase();
+    return normalized.includes("--nodata")
+        || normalized.includes("no data available")
+        || normalized.includes("data is not available")
+        || normalized.includes("cannot retrieve data")
+        || normalized.includes("could not retrieve data");
+};
+
+export const withWorkspaceBaseUnavailableDiagnostic = (path: string, error: unknown): Error =>
+{
+    const message = error instanceof Error ? error.message : String(error);
+    if (!isNoDataError(message))
+    {
+        return error instanceof Error ? error : new Error(message);
+    }
+
+    return new Error(
+        `Plastic cannot supply historical/base bytes for '${path}' because this workspace/status record is --nodata. `
+        + "A workspace diff cannot be calculated without those bytes. Run plastic_status(machineReadable=true, includeRevId=true) to verify the item, then update/refresh the workspace or use plastic_diff with mode=revisions and two known file-qualified revisions when historical content is available.",
+    );
+};

package/src/domain/add-contract.ts

@@ -0,0 +1,24 @@
+import type { AddAttempt, AddCapture } from "../execution/add-command";
+export type { AddAttempt, AddCapture } from "../execution/add-command";
+export const ADD_COMMAND = "add" as const;
+export const safeAddText = (value: unknown): value is string => typeof value === "string" && value.length > 0 && value.length <= 4096 && value.trim().length > 0 && !/[\u0000-\u001f\u007f-\u009f]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(value);
+export function validAddOperands(paths: unknown): paths is string[] {
+    if (!Array.isArray(paths) || !paths.length || paths.length > 256) return false;
+    let bytes = 0;
+    for (let index = 0; index < paths.length; index++) {
+        const path = paths[index];
+        if (!safeAddText(path) || path.trimStart().startsWith("-")) return false;
+        bytes += Buffer.byteLength(path, "utf8");
+        if (bytes > 32768) return false;
+    }
+    return true;
+}
+export type AddData = {
+    intendedArgv: readonly string[]; requestedOperandCount: number | null; workingDirectory: string | null;
+    attempt: AddAttempt; capture: AddCapture | null;
+    observedWorkspaceIdentity: null; observedAddedItems: null;
+    verification: "unverified"; effect: "not-attempted" | "not-proven" | "uncertain";
+};
+type Header = { schemaVersion: 1; action: "add"; provenance: { source: "plastic"; producer: "@aefree/pi-plastic"; contentTrust: "external" }; completeness: { capture: "complete" | "incomplete" | "unknown"; projection: true }; data: AddData };
+export type AddError = { code: "invalid_request" | "launch_failed" | "aborted" | "uncertain" | "producer_failed"; message: string };
+export type AddReceipt = Header & ({ ok: true; outcome: "command-completed" } | { ok: false; outcome: "failed" | "uncertain"; error: AddError });

package/src/domain/branch-create-contract.ts

@@ -0,0 +1,38 @@
+export type BranchCreateRequest = { branch: string; parent?: string; changeset?: string; label?: string; comment?: string; commentsFile?: string; allowRootBranch?: boolean; workdir?: string };
+import type { BranchCreateAttempt, BranchCreateCapture } from "../execution/branch-create-command";
+export { emptyBranchCreateAttempt } from "../execution/branch-create-command";
+export type { BranchCreateAttempt, BranchCreateCapture } from "../execution/branch-create-command";
+export type BranchCreateData = {
+    requested: { branch: string; parent: string | null; changeset: string | null; label: string | null; comment: string | null; commentsFile: string | null; allowRootBranch: boolean } | null;
+    resolvedTarget: string | null;
+    parentResolution: { basis: "not-required" | "explicit" | "status" | "unresolved"; observedBranch: string | null; repositoryVerification: "unverified" };
+    parentCommands: Array<{ argv: string[]; attempt: BranchCreateAttempt; capture: BranchCreateCapture }>;
+    command: string[] | null;
+    attempt: BranchCreateAttempt;
+    capture: BranchCreateCapture | null;
+    observedCreatedIdentity: null;
+    repositoryVerification: "unverified";
+    workspaceSwitch: "not-requested";
+};
+type Base = { schemaVersion: 1; action: "branch-create"; provenance: { source: "plastic"; producer: "@aefree/pi-plastic"; contentTrust: "external" }; completeness: { capture: "complete" | "incomplete" | "unknown"; projection: true } };
+export type BranchCreateError = { code: "invalid_request" | "unsupported_source" | "ambiguous_qualifier" | "parent_unresolved" | "launch_failed" | "aborted" | "uncertain" | "producer_failed"; stage: "input" | "source" | "parent" | "create" | "producer"; message: string };
+export type BranchCreateReceipt = Base & (
+    { ok: true; outcome: "command-completed"; data: BranchCreateData & { effect: "not-proven" } } |
+    { ok: false; outcome: "failed" | "unsupported"; data: BranchCreateData & { effect: "not-attempted" }; error: BranchCreateError } |
+    { ok: false; outcome: "uncertain"; data: BranchCreateData & { effect: "uncertain" }; error: BranchCreateError }
+);
+export const branchCreateUnsafeText = /[\u0000-\u001f\u007f-\u009f]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u;
+export const safeBranchCreateText = (s: string): boolean => s.length <= 4096 && !branchCreateUnsafeText.test(s);
+/**
+ * Direct standard-status source only, admitted against known-original Unicode
+ * on Windows cm 11.0.16.10371. No runtime version query or compact grammar is
+ * claimed. Changeset ownership is not the loaded branch. '?' and U+FFFD remain
+ * unsupported/ambiguous source identities, not proof of character degradation.
+ */
+export function parseBranchCreateParent(output: string): string | null {
+    const lines = output.split(/\r?\n/).filter(line => line.length > 0);
+    if (lines.length !== 1) return null;
+    const match = /^(\/[^@]+)@[^@]+@[^\s]+ \(cs:(?:0|[1-9][0-9]{0,19}) - head\)$/u.exec(lines[0]!);
+    if (!match || !safeBranchCreateText(match[1]!) || !/^\/(?:[^/@\\]+)(?:\/[^/@\\]+)*$/u.test(match[1]!) || match[1] !== match[1]!.trim() || /[?\uFFFD]/u.test(match[1]!)) return null;
+    return match[1]!;
+}

package/src/domain/branch-delete-contract.ts

@@ -0,0 +1,15 @@
+import type { WorkspaceMergeAttempt, WorkspaceMergeCapture } from "../execution/workspace-merge-command";
+export type BranchDeleteAttempt = WorkspaceMergeAttempt;
+export type BranchDeleteCapture = WorkspaceMergeCapture;
+export const safeBranchDeleteText = (v: unknown): v is string => typeof v === "string" && v.length > 0 && v.length <= 4096 && v.trim().length > 0 && !/[\u0000-\u001f\u007f-\u009f]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(v);
+export const validBranchDeleteOperand = (v: unknown): v is string => safeBranchDeleteText(v) && !v.trimStart().startsWith("-");
+export type BranchDeleteData = {
+ intendedArgv: readonly string[]; requestedBranch: string | null; workingDirectory: string | null;
+ deleteChangesetsRequested: boolean | null; previewRequested: boolean | null; outputFormatRequested: "text" | "json" | null;
+ attempt: BranchDeleteAttempt; capture: BranchDeleteCapture | null;
+ observedDeletedBranch: null; observedDeletedChangesets: null; observedRepositoryIdentity: null; observedWorkspaceIdentity: null;
+ verification: "unverified"; rollback: "not-proven"; effect: "not-attempted" | "not-proven" | "uncertain";
+};
+export type BranchDeleteError = { code: "invalid_request" | "launch_failed" | "aborted" | "uncertain" | "producer_failed"; message: string };
+export type BranchDeleteReceipt = { schemaVersion: 1; action: "branch-delete"; provenance: { source: "plastic"; producer: "@aefree/pi-plastic"; contentTrust: "external" }; completeness: { capture: "complete" | "incomplete" | "unknown"; projection: true }; data: BranchDeleteData } & ({ ok: true; outcome: "preflight" | "command-completed" } | { ok: false; outcome: "failed" | "uncertain"; error: BranchDeleteError });
+export const branchDeleteArgv = (branch: string, deleteChangesets: boolean): string[] => ["branch", "delete", branch, ...(deleteChangesets ? ["--delete-changesets"] : [])];

package/src/domain/branches.ts

@@ -0,0 +1,263 @@
+import { runCmRaw, normalizeFindOutputLines } from "../execution/cm";
+import { parsePlasticStatusBranch } from "../plastic-workspace";
+import { normalizeErrorMessage } from "./merge-output";
+
+export const normalizeBranchSpecForComparison = (branch: string): string =>
+{
+    const trimmed = branch.trim();
+    const withoutPrefix = trimmed.replace(/^br:/i, "");
+    const withoutRepository = withoutPrefix.split("@")[0] ?? withoutPrefix;
+    return withoutRepository.replace(/\\/g, "/");
+};
+
+export const isSameBranchSpec = (left: string, right: string): boolean =>
+{
+    return normalizeBranchSpecForComparison(left) === normalizeBranchSpecForComparison(right);
+};
+
+export const assertWorkspaceOnBranch = (actualBranch: string, expectedBranch: string, phase: string): void =>
+{
+    if (isSameBranchSpec(actualBranch, expectedBranch))
+    {
+        return;
+    }
+
+    throw new Error([
+        `Plastic workspace branch mismatch after ${phase}.`,
+        `Expected target: ${expectedBranch}`,
+        `Actual branch: ${actualBranch}`,
+        "The requested merge/checkin was not completed on the target branch.",
+        "Do not switch branches and assume the changeset moved; Plastic changesets remain on the branch where they were created. Inspect branch history and retry the merge from the actual target branch.",
+    ].join("\n"));
+};
+
+export const getBranchLeafName = (branch: string): string =>
+{
+    const normalized = normalizeBranchSpecForComparison(branch);
+    const segments = normalized.split("/").filter((segment) => segment.length > 0);
+    return segments.at(-1) ?? normalized;
+};
+
+export const resolveBranchCreationTarget = (
+    requestedBranch: string,
+    parentBranch?: string,
+    allowRootBranch = false,
+): string =>
+{
+    const requested = requestedBranch.trim();
+    const normalizedRequested = normalizeBranchSpecForComparison(requested);
+
+    if (normalizedRequested.length === 0)
+    {
+        throw new Error("Branch must be non-empty.");
+    }
+
+    if (!normalizedRequested.startsWith("/"))
+    {
+        if (!parentBranch)
+        {
+            throw new Error("A relative branch name requires a parent branch.");
+        }
+
+        const normalizedParent = normalizeBranchSpecForComparison(parentBranch).replace(/\/$/, "");
+        if (!normalizedParent.startsWith("/") || normalizedParent === "/")
+        {
+            throw new Error(`Parent branch must be a hierarchical branch path, received ${parentBranch}.`);
+        }
+        return `${normalizedParent}/${normalizedRequested}`;
+    }
+
+    const segments = normalizedRequested.split("/").filter((segment) => segment.length > 0);
+    if (segments.length === 1 && !allowRootBranch)
+    {
+        throw new Error(
+            `Refusing to create top-level branch ${requested}. ` +
+            "Create <parent-branch>/<new-branch>, pass parent with a relative branch name, " +
+            "or set allowRootBranch=true when top-level branch creation is intentional.",
+        );
+    }
+
+    return requested;
+};
+
+export const escapeCmWhereValue = (value: string): string => value.replace(/\\/g, "\\\\").replace(/'/g, "''");
+export const cmWhereEquals = (field: string, value: string): string => `${field} = '${escapeCmWhereValue(value)}'`;
+export const cmWhereLike = (field: string, value: string): string => `${field} like '${escapeCmWhereValue(value)}'`;
+export const listRecentBranchNames = async (workdir?: string, limit = 200): Promise<string[]> =>
+{
+    const output = await runCmRaw([
+        "find",
+        "branch",
+        `order by date desc limit ${limit}`,
+        "--format={name}",
+        "--nototal",
+    ], workdir);
+    return normalizeFindOutputLines(output);
+};
+
+export type BranchParentLookupOutcome =
+    | { kind: "resolved"; branch: string; parent: string }
+    | { kind: "root"; branch: string; matchedBranch: string }
+    | { kind: "not-found"; branch: string; attemptedCandidates: string[] }
+    | { kind: "malformed-output"; branch: string; attemptedCandidates: string[]; diagnostics: string[] }
+    | { kind: "command-failed"; branch: string; attemptedCandidates: string[]; diagnostics: string[] };
+
+export type BranchParentRow = { name: string; parent?: string };
+
+export const parseBranchParentRows = (output: string): BranchParentRow[] | undefined =>
+{
+    const lines = normalizeFindOutputLines(output);
+    const rows: BranchParentRow[] = [];
+    for (const line of lines)
+    {
+        const separator = line.indexOf("|");
+        if (separator <= 0 || line.indexOf("|", separator + 1) !== -1)
+        {
+            return undefined;
+        }
+        const name = line.slice(0, separator).trim();
+        const parent = line.slice(separator + 1).trim();
+        if (!name)
+        {
+            return undefined;
+        }
+        rows.push({ name, ...(parent ? { parent } : {}) });
+    }
+    return rows;
+};
+
+export const branchRepositoryQualifier = (branch: string): string | undefined =>
+{
+    const match = branch.trim().match(/^(?:br:)?[^@]+(@.+)$/);
+    return match?.[1];
+};
+
+export const branchRepositorySpec = (branch: string): string | undefined =>
+{
+    const qualifier = branchRepositoryQualifier(branch);
+    return qualifier?.slice(1);
+};
+
+export const branchNameForLookup = (branch: string): string => normalizeBranchSpecForComparison(branch);
+
+export const qualifyBranchName = (branchName: string, requestedBranch: string): string =>
+{
+    const qualifier = branchRepositoryQualifier(requestedBranch);
+    return qualifier && !branchName.includes("@") ? `${branchName}${qualifier}` : branchName;
+};
+
+export const resolveBranchParentName = async (branch: string, workdir?: string): Promise<BranchParentLookupOutcome> =>
+{
+    const requestedBranch = branch.trim();
+    // A qualified selector is identity-bearing input; never strip its repository/server.
+    const lookupBranchName = branchNameForLookup(requestedBranch);
+    const candidates = Array.from(new Set(
+        (requestedBranch.includes("@")
+            ? [lookupBranchName]
+            : [requestedBranch, lookupBranchName, `br:${lookupBranchName}`])
+            .filter((candidate) => candidate.length > 0),
+    ));
+    const diagnostics: string[] = [];
+    const repositorySpec = branchRepositorySpec(requestedBranch);
+    const repositoryClause = repositorySpec
+        ? ` on repository '${repositorySpec.replace(/'/g, "''")}'`
+        : "";
+
+    for (const candidate of candidates)
+    {
+        try
+        {
+            const output = await runCmRaw([
+                "find",
+                "branch",
+                `where ${cmWhereEquals("name", candidate)}${repositoryClause}`,
+                "--format={name}|{parent}",
+                "--nototal",
+            ], workdir);
+            const rows = parseBranchParentRows(output);
+            if (!rows || rows.length > 1)
+            {
+                return {
+                    kind: "malformed-output",
+                    branch: requestedBranch,
+                    attemptedCandidates: candidates,
+                    diagnostics: [`Expected one name|parent row, received ${rows ? rows.length : "malformed"}.`],
+                };
+            }
+            const row = rows[0];
+            if (row && branchNameForLookup(row.name) !== lookupBranchName)
+            {
+                return {
+                    kind: "malformed-output",
+                    branch: requestedBranch,
+                    attemptedCandidates: candidates,
+                    diagnostics: ["Returned branch identity did not match the requested branch name."],
+                };
+            }
+            if (row?.parent)
+            {
+                return {
+                    kind: "resolved",
+                    branch: qualifyBranchName(row.name, requestedBranch),
+                    parent: qualifyBranchName(row.parent, requestedBranch),
+                };
+            }
+            if (row)
+            {
+                return { kind: "root", branch: requestedBranch, matchedBranch: qualifyBranchName(row.name, requestedBranch) };
+            }
+        }
+        catch (error)
+        {
+            diagnostics.push(normalizeErrorMessage(error).slice(0, 256));
+        }
+    }
+
+    if (diagnostics.length > 0)
+    {
+        return { kind: "command-failed", branch: requestedBranch, attemptedCandidates: candidates, diagnostics: diagnostics.slice(0, 3) };
+    }
+
+    return { kind: "not-found", branch: requestedBranch, attemptedCandidates: candidates };
+};
+
+export const resolveCurrentBranchName = async (workdir?: string): Promise<string> =>
+{
+    const statusOutput = await runCmRaw(["status"], workdir);
+    const statusBranch = parsePlasticStatusBranch(statusOutput);
+    if (statusBranch.kind === "found" && statusBranch.value.branch)
+    {
+        return statusBranch.value.branch;
+    }
+
+    const compactOutput = await runCmRaw(["status", "--compact"], workdir);
+    const compactBranch = parsePlasticStatusBranch(compactOutput);
+    if (compactBranch.kind === "found" && compactBranch.value.branch)
+    {
+        return compactBranch.value.branch;
+    }
+
+    if (compactBranch.kind === "found" && compactBranch.value.changesetId)
+    {
+        const changesetBranchOutput = await runCmRaw([
+            "find",
+            "changeset",
+            `where changesetid=${compactBranch.value.changesetId}`,
+            "--format={branch}",
+            "--nototal",
+        ], workdir);
+        const branchLines = normalizeFindOutputLines(changesetBranchOutput);
+        if (branchLines.length > 0)
+        {
+            return branchLines[0];
+        }
+    }
+
+    const trimmed = compactOutput.trim();
+    if (trimmed.length === 0)
+    {
+        throw new Error("Unable to determine current branch from empty status output.");
+    }
+
+    throw new Error(`Unable to parse current branch from status output: ${trimmed}`);
+};

package/src/domain/checkin-contract.ts

@@ -0,0 +1,70 @@
+import { parseMachineReadablePendingItems, type PendingItem } from "./pending";
+import { parseCopiedPending } from "./copied-merge";
+export type CheckinRequest = { message: string; paths?: string[]; applyChanged?: boolean; includePrivate?: boolean; includeAll?: boolean; updateAfter?: boolean; preflight?: boolean; format?: "text" | "json"; workdir?: string };
+import type { CheckinAttempt, CheckinCapture } from "../execution/checkin-command";
+export type { CheckinAttempt, CheckinCapture } from "../execution/checkin-command";
+export type CheckinChangeset = { id: string; branch: string; repository: string; server: string; mount: "/" };
+export type CheckinSummary = { totalPending: number; tracked: number; private: number; added: number; changed: number; moved: number; deleted: number; other: number };
+export type CheckinStep = { name: "pending-before" | "initial-checkin" | "private-add" | "private-retry" | "pending-recovery" | "fallback-checkin" | "pending-after" | "merge-diagnostic"; operation: "status" | "checkin" | "add"; attempt: CheckinAttempt; capture: CheckinCapture; effect: "not-attempted" | "uncertain" | "command-completed" | "changeset-created" | "read-observed"; evidence: "unadmitted" | "admitted"; records: number; summary: CheckinSummary | null; changeset: CheckinChangeset | null };
+export type CheckinItemEvent = { operation: "CO" | "AD" | "DE" | "CP"; path: string } | { operation: "MV"; sourcePath: string; path: string };
+export type CheckinData = { sourceAdmission: "windows-cm11.0.16.10371-observed"; requestedPaths: string[]; includedPaths: string[]; fallbackPaths: string[]; excludedPaths: Array<{ path: string; reason: string }>; privateAddPaths: string[]; blockedPrivatePaths: Array<{ path: string; reason: string }>; itemEvents: CheckinItemEvent[]; observedChangesets: CheckinChangeset[]; command: string[] | null; steps: CheckinStep[]; autoEnabledApplyChanged: boolean; usedFallbackRetry: boolean; usedPrivateAutoAddRecovery: boolean; pendingBefore: CheckinSummary | null; pendingAfter: CheckinSummary | null; wouldRun: boolean; omittedReferences: number; scopeExhaustion: "unverified"; branchHead: "unverified"; serverAliasEquivalence: "unverified"; xlinkEffects: "unverified"; mergeLinkIdentity: "unverified" };
+type Base = { schemaVersion: 1; action: "checkin"; provenance: { source: "plastic"; producer: "@aefree/pi-plastic"; contentTrust: "external" }; completeness: { capture: "complete" | "incomplete" | "unknown"; projection: boolean } };
+export type CheckinReceipt = Base & (
+    { ok: true; outcome: "completed"; data: CheckinData & { effect: "changeset-created"; createdChangeset: CheckinChangeset } } |
+    { ok: true; outcome: "preflight"; data: CheckinData & { effect: "not-attempted"; createdChangeset: null } } |
+    { ok: false; outcome: "failed" | "unsupported" | "uncertain"; data: CheckinData & { effect: "not-attempted" | "uncertain" | "command-completed" | "changeset-created"; createdChangeset: CheckinChangeset | null }; error: { code: string; stage: "input" | "pending" | "checkin" | "producer"; message: string } }
+);
+export const checkinUnsafeText = /[\u0000-\u001f\u007f-\u009f]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+export const checkinSafeValue = (s: unknown): s is string => typeof s === "string" && s.length > 0 && s.length <= 4096 && !checkinUnsafeText.test(s);
+// Comments alone admit CR/LF; all other controls, bounds and surrogate rules stay unchanged.
+export const checkinSafeComment = (s: unknown): s is string => typeof s === "string" && s.length > 0 && s.length <= 4096 && !checkinUnsafeText.test(s.replace(/[\r\n]/g, " "));
+// Loss-marker rejection is a conservative admission policy, not proof of original Unicode fidelity.
+const identity = (s: string) => checkinSafeValue(s) && s === s.trim() && !/[?\uFFFD]/.test(s);
+const absolute = (s: string) => identity(s) && /^(?:[A-Za-z]:[\\/]|\\\\)/.test(s);
+export const checkinDecimal = /^(0|[1-9][0-9]{0,19})$/;
+export function parseCheckinChangeset(payload: string): CheckinChangeset | null {
+    const m = /^cs:(0|[1-9][0-9]{0,19})@br:(\/[^@]+)@([^@]+)@([^@]+(?:@(cloud|unity))?) \(mount:'\/'\)$/.exec(payload);
+    if (!m || !m.slice(2, 5).every(identity) || m[2].endsWith("/")) return null;
+    return { id: m[1], branch: m[2], repository: m[3], server: m[4], mount: "/" };
+}
+export type CheckinSeparators = { start: string; end: string; field: string };
+export function parseCheckinEvidence(text: string, s: CheckinSeparators) {
+    const changesets: CheckinChangeset[] = [], events: CheckinItemEvent[] = [];
+    const lines = text.split(/\r?\n/); if (lines.at(-1) === "") lines.pop();
+    let malformed = !lines.length || lines.length > 500, started = 0;
+    for (const [index, line] of lines.entries()) {
+        if (!line.startsWith(s.start) || !line.endsWith(s.end)) { malformed = true; continue; }
+        const fields = line.slice(s.start.length, -s.end.length).split(s.field), [op, value] = fields;
+        if (op === "CI_START" && fields.length === 1) { started++; if (index !== 0) malformed = true; }
+        else if (op === "STAGE" && fields.length === 2 && value.length <= 4096 && !checkinUnsafeText.test(value)) { if (changesets.length) malformed = true; }
+        else if ((op === "CO" || op === "AD" || op === "DE" || op === "CP") && fields.length === 2 && absolute(value)) { events.push({ operation: op, path: value }); if (changesets.length) malformed = true; }
+        else if (op === "MV" && fields.length === 3 && absolute(value) && absolute(fields[2])) { events.push({ operation: "MV", sourcePath: value, path: fields[2] }); if (changesets.length) malformed = true; }
+        else if (op === "CHANGESET" && fields.length === 2) { const cs = parseCheckinChangeset(value); if (cs) changesets.push(cs); else malformed = true; }
+        else malformed = true;
+    }
+    if (started !== 1 || changesets.length > 1) malformed = true;
+    return { admitted: !malformed, records: Math.min(lines.length, 501), changesets, events };
+}
+export function parseCheckinPending(text: string, cwd: string) {
+    // statusCode CP retained; added kind is local checkin selection, not legacy migration.
+    const copied = parseCopiedPending(text, cwd);
+    if (copied) {
+        const items = parseMachineReadablePendingItems(text, cwd).map(item => ({ ...item, kind: "added" as const }));
+        return { admitted: items.length === copied.paths.length, records: copied.paths.length + 1, items, repository: copied.repository, server: copied.server };
+    }
+    const lines = text.split(/\r?\n/); if (lines.at(-1) === "") lines.pop();
+    let admitted = lines.length > 0 && lines.length <= 500;
+    const h = (lines[0] ?? "").split("\x1f");
+    if (h.length !== 4 || h[0] !== "STATUS" || !checkinDecimal.test(h[1]) || !identity(h[2] ?? "") || !identity(h[3] ?? "")) admitted = false;
+    for (const line of lines.slice(1)) {
+        const f = line.split("\x1f");
+        // Exact observed shapes only; unfamiliar status/metadata fails closed.
+        // CO uses -1 (no reusable revision identity), even for unselected paths.
+        if (f[0] === "MV") {
+            if (f.length !== 7 || f[1] !== "100%" || !absolute(f[2]) || !absolute(f[3]) || f[4] !== "False" || !checkinDecimal.test(f[5]) || f[5] === "0" || f[6] !== "NO_MERGES") admitted = false;
+        } else if (f.length !== 5 || !/^(PR|AD|CO|CH|LD)$/.test(f[0]) || !absolute(f[1]) || !/^(True|False)$/.test(f[2]) || !(/^(PR|AD|CO)$/.test(f[0]) ? f[3] === "-1" : checkinDecimal.test(f[3]) && f[3] !== "0") || f[4] !== "NO_MERGES") admitted = false;
+    }
+    const items: PendingItem[] = admitted ? parseMachineReadablePendingItems(text, cwd) : [];
+    if (admitted && items.length !== lines.length - 1) admitted = false;
+    return { admitted, records: Math.min(lines.length, 501), items, repository: admitted ? h[2] : null, server: admitted ? h[3] : null };
+}

package/src/domain/closeout-contract.ts

@@ -0,0 +1,30 @@
+import { parseSwitchTarget } from "./switch-contract";
+import { cmWhereEquals } from "./branches";
+/** Name is a leaf filter; emitted full name, not the filter, is identity.
+ * Two returned rows are ambiguity, not a reason to choose the first or retry. */
+export function buildCloseoutParentArgv(source: string): string[] {
+ const spec=parseSwitchTarget(source);if(!spec)throw Error("Invalid parent lookup source.");
+ const leaf=spec.branch.slice(spec.branch.lastIndexOf("/")+1);
+ const clause=spec.repository===null?"":` on repository '${(spec.repository+"@"+spec.server).replace(/'/g,"''")}'`;
+ return ["find","branch",`where ${cmWhereEquals("name",leaf)} order by branchname asc limit 2${clause}`,"--format={name}|{parent}","--nototal"];
+}
+import type { WorkspaceMergeAttempt, WorkspaceMergeCapture, MergeStrategy, WorkspaceMergeReceipt } from "./workspace-merge-contract";
+import type { SwitchBranchObservation, SwitchSummary, SwitchReceipt } from "./switch-contract";
+import type { CheckinChangeset, CheckinReceipt } from "./checkin-contract";
+import type { UpdateReceipt } from "./update-contract";
+export type CloseoutRequest = { source?: string; target?: string; cardRef?: string; message?: string; strategy?: MergeStrategy; updateTarget?: boolean; includePrivate?: boolean; preflight?: boolean; format?: "text" | "json"; workdir?: string };
+export const CLOSEOUT_STAGE_NAMES = ["loaded-before", "parent", "pending-before", "switch", "loaded-after-switch", "update", "loaded-before-merge", "merge", "readiness", "loaded-before-checkin", "checkin-preflight", "checkin", "loaded-final", "pending-final"] as const;
+export type CloseoutStageName = typeof CLOSEOUT_STAGE_NAMES[number];
+export type CloseoutRead = { argv: string[]; attempt: WorkspaceMergeAttempt; capture: WorkspaceMergeCapture | null; admission: "unsupported" | "admitted"; branch: SwitchBranchObservation | null; parentPath: string | null; emptyParentResult: boolean; summary: SwitchSummary | null };
+export type CloseoutStage = { name: CloseoutStageName } & (
+ { kind: "read"; result: CloseoutRead } | { kind: "switch"; result: SwitchReceipt } | { kind: "update"; result: UpdateReceipt } | { kind: "merge"; result: WorkspaceMergeReceipt } | { kind: "checkin"; result: CheckinReceipt }
+);
+export type CloseoutData = { requested: { source: string | null; target: string | null; message: string | null; cardRef: string | null; strategy: MergeStrategy; updateTarget: boolean; includePrivate: boolean; preflight: boolean; outputFormat: "text" | "json"; workdir: string } | null; sourceBranch: string | null; targetBranch: string | null; targetSource: "unresolved" | "explicit" | "parent-read"; checkinMessage: string | null; stages: CloseoutStage[]; unattemptedStages: CloseoutStageName[]; unobservedChild: "switch" | "update" | "merge" | "checkin-preflight" | "checkin" | null; createdChangeset: CheckinChangeset | null; pendingAfter: SwitchSummary | null; targetVerification: "unverified" | "name-only" | "exact-qualifier-spelling"; serverAliasEquivalence: "unverified"; sourceLink: "unverified"; branchHead: "unverified"; exclusiveScope: "unverified"; rollback: "not-proven"; effect: "not-attempted" | "command-completed" | "uncertain" | "changeset-created" };
+export type CloseoutReceipt = { schemaVersion: 1; action: "merge-to-branch"; provenance: { source: "plastic"; producer: "@aefree/pi-plastic"; contentTrust: "external" }; completeness: { capture: "complete" | "incomplete" | "unknown"; projection: boolean }; data: CloseoutData } & (
+ { ok: true; outcome: "preflight" | "completed" } | { ok: false; outcome: "blocked" | "failed" | "uncertain"; error: { code: "invalid_request" | "unsupported_source" | "observation_failed" | "target_unverified" | "policy_blocked" | "child_failed" | "producer_failed"; stage: "input" | CloseoutStageName | "producer"; message: string } }
+);
+export const CLOSEOUT_DTO_BYTES = 1048576;
+/** Ledger keeps the five complete bounded child receipts and at most eleven compact reads.
+ * No child text/stdout/stderr is duplicated, no positive changeset is projected away. */
+export function closeoutChildEffect(s: CloseoutStage): CloseoutData["effect"] { if(s.kind==="read")return "not-attempted";const e=s.result.data.effect;return e==="not-proven"?"command-completed":e; }
+export function closeoutCaptures(stages: CloseoutStage[]) { return stages.flatMap(s=>s.kind==="read"?[s.result.capture]:s.kind==="update"?[s.result.data.capture]:s.kind==="merge"?[s.result.data.apply.capture,s.result.data.shortStatus.capture,s.result.data.fullStatus.capture]:s.result.data.steps.map(x=>x.capture)).filter((x):x is WorkspaceMergeCapture=>x!==null); }