@aefree/pi-plastic 0.7.6 → 0.8.1

package/src/domain/revisions.ts

@@ -0,0 +1,301 @@
+import { promises as fs } from "node:fs";
+import { dirname } from "path";
+import { runCmRaw } from "../execution/cm";
+import { discoverPlasticWorkspace } from "../plastic-workspace";
+import { toNormalizedAbsolutePath, toFilesystemIdentityPath, toPathComparisonKeyFromAbsolutePath, isWithinPathScope } from "./paths";
+import { PendingItem } from "./pending";
+
+export const isRevisionNotFoundError = (message: string): boolean =>
+{
+    const normalized = message.toLowerCase();
+    return normalized.includes("the specified revision was not found");
+};
+
+export const isGlobalRevisionSpec = (revision: string): boolean =>
+{
+    const normalized = revision.toLowerCase();
+    return normalized.startsWith("rev:")
+        || normalized.startsWith("revid:")
+        || normalized.startsWith("itemid:")
+        || normalized.startsWith("serverpath:");
+};
+
+export const isItemSelectorRevisionSpec = (revision: string): boolean =>
+{
+    const normalized = revision.toLowerCase();
+    return /^\d+$/.test(revision)
+        || normalized.startsWith("cs:")
+        || normalized.startsWith("br:")
+        || normalized.startsWith("lb:");
+};
+
+export type DiffFileRevisionResolution = {
+    supplied: string | null;
+    kind: "workspace-base" | "changeset" | "branch" | "label" | "global-revision" | "file-qualified";
+    resolved: string;
+};
+
+export const resolveDiffFileRevision = (pathForRevision: string, revision?: string): DiffFileRevisionResolution =>
+{
+    const normalizedPath = pathForRevision.trim();
+    const normalizedRevision = revision?.trim() ?? "";
+    if (!normalizedPath)
+    {
+        throw new Error("path must identify a workspace file.");
+    }
+
+    // A bare item path is the unambiguous common case: cm cat resolves the
+    // workspace's loaded/base revision without asking agents to guess a revspec.
+    if (!normalizedRevision)
+    {
+        return { supplied: null, kind: "workspace-base", resolved: normalizedPath };
+    }
+
+    const lowerRevision = normalizedRevision.toLowerCase();
+    if (lowerRevision === "base" || lowerRevision === "head" || lowerRevision === "cs:head" || /^cs:br:/i.test(normalizedRevision))
+    {
+        throw new Error(
+            `Unsupported revision '${revision}'. Omit revision for the workspace base, or use a changeset number/cs:<number>, br:/<branch>, lb:<label>, a file-qualified '<path>#<selector>', or a global revid:/rev: spec.`,
+        );
+    }
+
+    if (normalizedRevision.includes("#"))
+    {
+        return { supplied: normalizedRevision, kind: "file-qualified", resolved: normalizedRevision };
+    }
+
+    if (isGlobalRevisionSpec(normalizedRevision))
+    {
+        return { supplied: normalizedRevision, kind: "global-revision", resolved: normalizedRevision };
+    }
+
+    if (/^\d+$/.test(normalizedRevision) || /^cs:\d+$/i.test(normalizedRevision))
+    {
+        const selector = /^\d+$/.test(normalizedRevision) ? `cs:${normalizedRevision}` : normalizedRevision;
+        return { supplied: normalizedRevision, kind: "changeset", resolved: `${normalizedPath}#${selector}` };
+    }
+
+    if (/^br:\/.+/i.test(normalizedRevision))
+    {
+        return { supplied: normalizedRevision, kind: "branch", resolved: `${normalizedPath}#${normalizedRevision}` };
+    }
+
+    if (/^lb:[^\s#]+/i.test(normalizedRevision))
+    {
+        return { supplied: normalizedRevision, kind: "label", resolved: `${normalizedPath}#${normalizedRevision}` };
+    }
+
+    throw new Error(
+        `Unsupported revision '${revision}'. Omit revision for the workspace base, or use a changeset number/cs:<number>, br:/<branch>, lb:<label>, a file-qualified '<path>#<selector>', or a global revid:/rev: spec.`,
+    );
+};
+
+// Kept as a small compatibility seam for older focused tests and consumers.
+export const normalizeDiffFileRevisionSpec = (pathForRevision: string, revision: string): string =>
+    resolveDiffFileRevision(pathForRevision, revision).resolved;
+
+export const isValidGlobalRevisionSpec = (revision: string): boolean =>
+    /^(?:rev|revid|itemid|serverpath):\S+$/i.test(revision.trim());
+
+export const isValidFileQualifiedRevisionSpec = (revision: string): boolean =>
+{
+    const normalized = revision.trim();
+    const separator = normalized.lastIndexOf("#");
+    if (separator <= 0 || separator === normalized.length - 1)
+    {
+        return false;
+    }
+
+    const selector = normalized.slice(separator + 1);
+    return /^cs:\d+$/i.test(selector)
+        || /^br:\/.+/i.test(selector)
+        || /^lb:[^\s#]+$/i.test(selector)
+        || isValidGlobalRevisionSpec(selector);
+};
+
+export const isValidDiffRevisionSpec = (revision: string): boolean =>
+    isValidGlobalRevisionSpec(revision) || isValidFileQualifiedRevisionSpec(revision);
+
+export const isUnscopedDiffRevisionSpec = (revision: string): boolean => !isValidDiffRevisionSpec(revision);
+
+export const extractBranchSelectorFromRevision = (revision: string): string | null =>
+{
+    const match = revision.match(/(?:^|#)(br:[^\s#]+)/i);
+    if (!match)
+    {
+        return null;
+    }
+
+    const selector = (match[1] ?? "").trim();
+    return selector.length > 0 ? selector : null;
+};
+
+export const extractBranchNameFromSelector = (branchSelector: string): string | null =>
+{
+    const normalized = branchSelector.trim().replace(/^br:/i, "");
+    if (!normalized)
+    {
+        return null;
+    }
+
+    const atIndex = normalized.indexOf("@");
+    const branchName = atIndex >= 0 ? normalized.slice(0, atIndex).trim() : normalized.trim();
+    return branchName.length > 0 ? branchName : null;
+};
+
+export type PendingBaseIdentityResolver = {
+    resolve: (item: PendingItem) => Promise<string>;
+};
+
+export type RepositoryIdentity = {
+    repository: string;
+    server: string;
+};
+
+export const parseRepositoryIdentity = (selector: string | undefined): RepositoryIdentity | null =>
+{
+    if (!selector || /[\u0000-\u001f\u007f]/.test(selector))
+    {
+        return null;
+    }
+    // Repository names cannot contain @; cloud server names can (for example,
+    // an organization-qualified cloud endpoint), so split only at the first @.
+    const separator = selector.indexOf("@");
+    if (separator <= 0 || separator === selector.length - 1)
+    {
+        return null;
+    }
+    return { repository: selector.slice(0, separator), server: selector.slice(separator + 1) };
+};
+
+export const parseRepositorySelector = (output: string): RepositoryIdentity | null =>
+{
+    const match = output.match(/^\s*(?:repository|rep)\s+(?:"([^"]+)"|(\S+))\s*$/mi);
+    return parseRepositoryIdentity(match?.[1] ?? match?.[2]);
+};
+
+export const parseXlinkRepositorySelector = (output: string): RepositoryIdentity | null =>
+{
+    // `cm xlink --show` reports wxlink:<serverpath>@<loaded-revision>@<repository>@<server>.
+    const match = output.match(/^.+?\s+-->\s+wxlink:.+?@(?:\d+|cs:\d+)@(.+)\s*$/mi);
+    return parseRepositoryIdentity(match?.[1]?.trim());
+};
+
+export const isNotXlinkError = (error: unknown): boolean => /\bis not an xlink\.?\s*$/i.test(error instanceof Error ? error.message.trim() : String(error).trim());
+
+export const createPendingBaseIdentityResolver = (cwd: string, workdir?: string): PendingBaseIdentityResolver =>
+{
+    let workspaceRoot: Promise<string> | undefined;
+    const getWorkspaceRoot = (): Promise<string> =>
+    {
+        workspaceRoot ??= discoverPlasticWorkspace(cwd).then((outcome) =>
+        {
+            if (outcome.kind !== "found")
+            {
+                throw new Error(`Plastic cannot determine the workspace root for pending base resolution: ${outcome.kind === "unavailable" ? outcome.reason : "no workspace marker found"}.`);
+            }
+            return toNormalizedAbsolutePath(outcome.value.root, cwd);
+        });
+        return workspaceRoot;
+    };
+    const xlinkLookups = new Map<string, Promise<RepositoryIdentity | null>>();
+    let workspaceRepository: Promise<RepositoryIdentity> | undefined;
+    const getWorkspaceRepository = (): Promise<RepositoryIdentity> =>
+    {
+        workspaceRepository ??= runCmRaw(["showselector"], workdir).then((output) =>
+        {
+            const repository = parseRepositorySelector(output);
+            if (!repository)
+            {
+                throw new Error("Plastic returned no repository/server identity for this workspace.");
+            }
+            return repository;
+        });
+        return workspaceRepository;
+    };
+    const getXlinkRepository = async (candidate: string): Promise<RepositoryIdentity | null> =>
+    {
+        // Use the physical identity for cache keys, but keep candidate lexical for cm.
+        const key = toPathComparisonKeyFromAbsolutePath(await toFilesystemIdentityPath(candidate));
+        let lookup = xlinkLookups.get(key);
+        if (!lookup)
+        {
+            lookup = runCmRaw(["xlink", "--show", candidate], workdir)
+                .then((output) =>
+                {
+                    const repository = parseXlinkRepositorySelector(output);
+                    if (!repository)
+                    {
+                        throw new Error(`Plastic returned malformed Xlink ownership for '${candidate}'.`);
+                    }
+                    return repository;
+                })
+                .catch((error) =>
+                {
+                    if (isNotXlinkError(error))
+                    {
+                        return null;
+                    }
+                    throw error;
+                });
+            xlinkLookups.set(key, lookup);
+        }
+        return lookup;
+    };
+
+    return {
+        async resolve(item)
+        {
+            if (!item.revisionId)
+            {
+                throw new Error(`Plastic status did not provide a base revision ID for '${item.workspacePath}'.`);
+            }
+            const root = await getWorkspaceRoot();
+            const rootIdentity = await toFilesystemIdentityPath(root);
+            const ownershipPath = item.kind === "moved" && item.sourceWorkspacePath
+                ? toNormalizedAbsolutePath(item.sourceWorkspacePath, cwd)
+                : item.normalizedPath;
+            if (!isWithinPathScope(
+                toPathComparisonKeyFromAbsolutePath(await toFilesystemIdentityPath(ownershipPath)),
+                toPathComparisonKeyFromAbsolutePath(rootIdentity),
+            ))
+            {
+                throw new Error(`Plastic cannot resolve an owning repository for '${item.workspacePath}' outside the requested workspace.`);
+            }
+            let candidate = dirname(ownershipPath);
+            while (isWithinPathScope(
+                toPathComparisonKeyFromAbsolutePath(await toFilesystemIdentityPath(candidate)),
+                toPathComparisonKeyFromAbsolutePath(rootIdentity),
+            ))
+            {
+                // The workspace root belongs to its selector; cm rejects Xlink queries there.
+                if (toPathComparisonKeyFromAbsolutePath(await toFilesystemIdentityPath(candidate))
+                    === toPathComparisonKeyFromAbsolutePath(rootIdentity))
+                {
+                    break;
+                }
+                // A missing ancestor can be a removed Xlink mount. Status does not
+                // retain ownership, so parent-repository fallback would be unsafe.
+                if ((item.kind === "deleted" || item.kind === "moved") && !(await fs.stat(candidate).catch(() => null)))
+                {
+                    throw new Error(`Plastic cannot resolve the owning repository for '${item.workspacePath}' because an ownership ancestor is missing.`);
+                }
+                const repository = await getXlinkRepository(candidate);
+                if (repository)
+                {
+                    item.baseRepository = `${repository.repository}@${repository.server}`;
+                    return `revid:${item.revisionId}@rep:${repository.repository}@repserver:${repository.server}`;
+                }
+                const parent = dirname(candidate);
+                if (parent === candidate)
+                {
+                    break;
+                }
+                candidate = parent;
+            }
+            const repository = await getWorkspaceRepository();
+            item.baseRepository = `${repository.repository}@${repository.server}`;
+            return `revid:${item.revisionId}@rep:${repository.repository}@repserver:${repository.server}`;
+        },
+    };
+};

package/src/domain/server-merge-contract.ts

@@ -0,0 +1,45 @@
+import type { ResolutionFileSummary } from "./server-merge-resolutions";
+export type ServerMergeRequest = { source: string; target: string; message?: string; mode?: "apply" | "analyze"; fileConflictsResolutionsFile?: string; unlistedConflictPolicy?: "source" | "destination"; preflight?: boolean; format?: "text" | "json" };
+export type ServerChangeset = { id: string; branch: string; repository: string; server: string; mount: string };
+import type { MergeAttempt, MergeCapture } from "../execution/server-merge-command";
+export { emptyMergeAttempt } from "../execution/server-merge-command";
+export type { MergeAttempt, MergeCapture } from "../execution/server-merge-command";
+export type MergeReceiptData = {
+    mode: "apply" | "analyze";
+    resolutionsFile: ResolutionFileSummary | null;
+    unlistedConflictPolicy: "source" | "destination" | null;
+    requestedIdentity: { source: string; target: string; branch: string; repository: string; server: string } | null;
+    command: string[] | null;
+    capability: { state: "not-checked" | "advertised" | "missing" | "unavailable"; missingTokens: string[] };
+    attempt: MergeAttempt;
+    capture: { help: MergeCapture | null; merge: MergeCapture | null };
+    parse: { records: number; malformed: boolean; unknownOperations: number; changesetsObserved: number; conflictsObserved: number } | null;
+    observedChangesets: ServerChangeset[];
+    conflictPaths: string[];
+    counts: { changesetsReturned: number; changesetsOmitted: number; conflictsReturned: number; conflictsOmitted: number };
+    createdChangeset: ServerChangeset | null;
+    effect: "not-attempted" | "changeset-created" | "not-proven" | "uncertain";
+    serverAliasEquivalence: "unverified";
+    mergeLinkIdentity: "unverified";
+    xlinkEffects: "unverified";
+    wouldRun: boolean;
+    remoteAnalysis: "not-performed" | "performed";
+};
+type Base = { schemaVersion: 1; action: "merge-branches"; provenance: { source: "plastic"; producer: "@aefree/pi-plastic"; contentTrust: "external" }; completeness: { capture: "complete" | "incomplete" | "unknown"; projection: boolean } };
+export type MergeReceiptError = { code: string; stage: "input" | "help" | "merge" | "producer"; message: string };
+export type MergeReceipt = Base & (
+    { ok: true; outcome: "completed"; data: MergeReceiptData & { createdChangeset: ServerChangeset; effect: "changeset-created" } } |
+    { ok: true; outcome: "preflight"; data: MergeReceiptData & { createdChangeset: null; effect: "not-attempted" } } |
+    { ok: true; outcome: "analyzed"; data: MergeReceiptData & { createdChangeset: null; effect: "not-attempted" } } |
+    { ok: true; outcome: "no-op"; data: MergeReceiptData & { createdChangeset: null; effect: "not-proven" } } |
+    { ok: false; outcome: "unsupported" | "failed"; data: MergeReceiptData & { createdChangeset: null; effect: "not-attempted" }; error: MergeReceiptError } |
+    { ok: false; outcome: "conflict" | "uncertain"; data: MergeReceiptData & { createdChangeset: null; effect: "uncertain" }; error: MergeReceiptError }
+);
+/** Unambiguous supported syntax: branch/repository contain no @, full server tail is retained. */
+export function splitServerBranch(raw: string): { branch: string; repository: string; server: string } | null {
+    const match = /^br:(\/[^@]+)@([^@]+)@([^@]+(?:@(cloud|unity))?)$/.exec(raw);
+    if (!match) return null;
+    const [, branch, repository, server] = match;
+    if (!branch || !repository || !server || branch.endsWith("/") || [branch, repository, server].some(s => s !== s.trim())) return null;
+    return { branch, repository, server };
+}

package/src/domain/server-merge-resolutions.ts

@@ -0,0 +1,61 @@
+import { open, stat } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { createHash } from "node:crypto";
+
+export const RESOLUTIONS_MAX_BYTES = 1024 * 1024;
+export const RESOLUTIONS_MAX_ENTRIES = 500;
+const unsafe = /[\u0000-\u001f\u007f-\u009f]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+export type ResolutionFileSummary = { path: string; sha256: string; entries: number; resultFiles: number; keepSource: number; keepDestination: number };
+function object(value: unknown): value is Record<string, unknown> { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function safePath(value: unknown): value is string { return typeof value === "string" && value.length > 0 && value.length <= 4096 && !unsafe.test(value); }
+export function assertAbsoluteResolutionPath(value: unknown): asserts value is string {
+    if (!safePath(value) || !isAbsolute(value)) throw new Error("Resolution input paths must be bounded absolute local paths without control/malformed characters.");
+}
+/** Read-only local validation. CLI remains responsible for matching entries to current conflicts. */
+export async function inspectResolutionFile(path: string): Promise<ResolutionFileSummary> {
+    assertAbsoluteResolutionPath(path);
+    let bytes: Buffer;
+    if (!(await stat(path)).isFile()) throw new Error("Resolutions JSON must be a regular file.");
+    const file = await open(path, "r");
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > RESOLUTIONS_MAX_BYTES) throw new Error("Resolutions JSON must be a regular file of at most 1 MiB.");
+        // Bounded even if another process grows the file after stat.
+        const buffer = Buffer.alloc(RESOLUTIONS_MAX_BYTES + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const { bytesRead } = await file.read(buffer, length, buffer.length - length, null);
+            if (!bytesRead) break;
+            length += bytesRead;
+        }
+        if (length > RESOLUTIONS_MAX_BYTES) throw new Error("Resolutions JSON exceeds 1 MiB.");
+        bytes = buffer.subarray(0, length);
+    } finally { await file.close(); }
+    let value: unknown;
+    try { value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)); }
+    catch { throw new Error("Resolutions file must contain valid UTF-8 JSON."); }
+    if (!object(value) || Object.keys(value).some(k => k !== "resolutions") || !Array.isArray(value.resolutions) || value.resolutions.length > RESOLUTIONS_MAX_ENTRIES) throw new Error("Resolutions JSON requires only a resolutions array with at most 500 entries.");
+    const summary: ResolutionFileSummary = { path, sha256: createHash("sha256").update(bytes).digest("hex"), entries: value.resolutions.length, resultFiles: 0, keepSource: 0, keepDestination: 0 };
+    const paths = new Set<string>();
+    for (let index = 0; index < value.resolutions.length; index++) {
+        const entry = value.resolutions[index];
+        const bad = () => new Error(`Invalid resolution entry ${index + 1}: require a unique destination conflict path and exactly one of keep (source/destination) or an absolute readable resultFile.`);
+        if (!object(entry) || Object.keys(entry).some(k => !["path", "keep", "resultFile"].includes(k)) || !safePath(entry.path) || !entry.path.startsWith("/") || paths.has(entry.path) || Object.hasOwn(entry, "keep") === Object.hasOwn(entry, "resultFile")) throw bad();
+        paths.add(entry.path);
+        if (Object.hasOwn(entry, "keep")) {
+            if (entry.keep === "source") summary.keepSource++;
+            else if (entry.keep === "destination") summary.keepDestination++;
+            else throw bad();
+        } else {
+            try {
+                assertAbsoluteResolutionPath(entry.resultFile);
+                if (!(await stat(entry.resultFile)).isFile()) throw bad();
+                const result = await open(entry.resultFile, "r");
+                try { if (!(await result.stat()).isFile()) throw bad(); }
+                finally { await result.close(); }
+            } catch { throw bad(); }
+            summary.resultFiles++;
+        }
+    }
+    return summary;
+}

package/src/domain/status-xml.ts

@@ -0,0 +1,122 @@
+import { DOMParser, type Element } from "@xmldom/xmldom";
+import type { MachineReadableStatusItem, MachineReadableStatusSummary } from "./pending";
+
+import { STATUS_XML_LIMITS } from "../execution/status-xml-limits";
+export { STATUS_XML_LIMITS } from "../execution/status-xml-limits";
+export type XmlStatusItem = Omit<MachineReadableStatusItem, "revisionId" | "statusCode" | "kind"> & { statusCode: keyof typeof kinds; kind: typeof kinds[keyof typeof kinds] };
+export class StatusXmlError extends Error {
+    constructor(readonly code: "unsupported_source" | "malformed_output" | "output_overflow" = "malformed_output") {
+        super(code === "unsupported_source" ? "Status XML contains an unsupported record profile."
+            : code === "output_overflow" ? "Status XML exceeded the bounded observation limits."
+            : "Status XML did not match the supported observation contract.");
+    }
+}
+function invalid(): never { throw new StatusXmlError(); }
+function limit(): never { throw new StatusXmlError("output_overflow"); }
+const kinds = { CH: "changed", AD: "added", DE: "deleted", LD: "deleted", MV: "moved", PR: "private" } as const;
+const fields = new Set(["Type", "TypeVerbose", "Path", "OldPath", "PrintableMovedPath", "MergesInfo", "SimilarityPerUnit", "Similarity", "Size", "PrintableSize", "PrintableLastModified", "RevisionType", "LastModified"]);
+const isAbsolute = (path: string): boolean => path.startsWith("/") || /^[A-Za-z]:\\/.test(path) || /^\\\\[^\\]+\\[^\\]+\\/.test(path);
+const identity = (value: string): string => {
+    if (!value || value.length > STATUS_XML_LIMITS.path || !isAbsolute(value) || /[\u0000-\u001f\uFFFE\uFFFF]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(value) || (process.platform === "win32" && value.includes("?"))) invalid();
+    return value;
+};
+
+// Fatal byte decoding distinguishes literal U+FFFD from decoder substitution.
+export function decodeStatusXml(bytes: Uint8Array): string {
+    if (bytes.byteLength > STATUS_XML_LIMITS.stdoutBytes) limit();
+    let output: string;
+    try { output = new TextDecoder("utf-8", { fatal: true }).decode(bytes); } catch { return invalid(); }
+    // This is a declaration gate, not an XML parser. Only the documented UTF-8 document format is supported.
+    if (!/^<\?xml\s+version\s*=\s*(["'])1\.0\1\s+encoding\s*=\s*(["'])utf-8\2(?:\s+standalone\s*=\s*(["'])(?:yes|no)\3)?\s*\?>/i.test(output)) invalid();
+    return output;
+}
+
+export function parseStatusXml(bytes: Uint8Array): { output: string; items: XmlStatusItem[]; summary: MachineReadableStatusSummary } {
+    const output = decodeStatusXml(bytes);
+    // Conservative denial also rejects these tokens in comments/CDATA; no DTD processing is allowed.
+    const upper = output.toUpperCase();
+    if (upper.includes("<!DOCTYPE") || upper.includes("<!ENTITY")) invalid();
+    let document;
+    try {
+        document = new DOMParser({ locator: false, onError: () => invalid() }).parseFromString(output, "application/xml");
+    } catch { return invalid(); }
+    if (document.doctype || !document.documentElement || document.documentElement.tagName !== "StatusOutput") invalid();
+    const stack: Array<[Element, number]> = [[document.documentElement, 1]];
+    let records = 0;
+    while (stack.length) {
+        const [element, depth] = stack.pop()!;
+        if (depth > STATUS_XML_LIMITS.depth) limit();
+        if (element.attributes.length || element.namespaceURI) invalid();
+        if (element.tagName === "Change" && ++records > STATUS_XML_LIMITS.records) limit();
+        const cap = element.tagName === "Path" || element.tagName === "OldPath" ? STATUS_XML_LIMITS.path : element.tagName === "Type" ? STATUS_XML_LIMITS.code : STATUS_XML_LIMITS.text;
+        // Accumulated text, including adjacent text/CDATA nodes, is bounded before projection.
+        let textLength = 0;
+        for (let node = element.firstChild; node; node = node.nextSibling) {
+            if (node.nodeType === 1) stack.push([node as Element, depth + 1]);
+            else if (node.nodeType === 3 || node.nodeType === 4) textLength += (node.nodeValue ?? "").length;
+            else if (node.nodeType !== 8) invalid();
+        }
+        if (textLength > cap) limit();
+    }
+    const children = (element: Element, allowed: ReadonlySet<string>): Map<string, Element> => {
+        const result = new Map<string, Element>();
+        for (let node = element.firstChild; node; node = node.nextSibling) {
+            if (node.nodeType === 1) {
+                const child = node as Element;
+                if (!allowed.has(child.tagName) || result.has(child.tagName)) invalid();
+                result.set(child.tagName, child);
+            } else if (node.nodeType !== 8 && (node.nodeValue ?? "").trim()) invalid();
+        }
+        return result;
+    };
+    const leaf = (element: Element | undefined): string => {
+        if (!element || element.getElementsByTagName("*").length) return invalid();
+        return element.textContent ?? "";
+    };
+    const root = children(document.documentElement, new Set(["WorkspaceStatus", "WkConfigType", "WkConfigName", "Changes"]));
+    // A well-formed but foreign/underspecified document must never become complete-empty status.
+    const workspace = root.get("WorkspaceStatus");
+    if (!workspace || !leaf(root.get("WkConfigType")) || !leaf(root.get("WkConfigName"))) invalid();
+    const status = children(workspace, new Set(["Status"])).get("Status");
+    if (!status) invalid();
+    const context = children(status, new Set(["RepSpec", "Changeset"]));
+    if (!/^\d+$/.test(leaf(context.get("Changeset")))) invalid();
+    const rep = context.get("RepSpec");
+    if (!rep) invalid();
+    const spec = children(rep, new Set(["Server", "Name"]));
+    if (!leaf(spec.get("Server")) || !leaf(spec.get("Name"))) invalid();
+    const items: XmlStatusItem[] = [];
+    const seen = new Set<string>();
+    let unsupported = false;
+    const changes = root.get("Changes");
+    if (changes) for (let node = changes.firstChild; node; node = node.nextSibling) {
+        if (node.nodeType !== 1) { if (node.nodeType !== 8 && (node.nodeValue ?? "").trim()) invalid(); continue; }
+        const change = node as Element;
+        if (change.tagName !== "Change") invalid();
+        const row = children(change, fields);
+        // All recognized fields are scalar in the verified configuration.
+        for (const value of row.values()) leaf(value);
+        const statusCode = leaf(row.get("Type"));
+        if (!/^[A-Z][A-Z0-9_]*$/.test(statusCode)) invalid();
+        const supportedStatus = Object.hasOwn(kinds, statusCode);
+        const kind = supportedStatus ? kinds[statusCode as keyof typeof kinds] : undefined;
+        const path = identity(leaf(row.get("Path")));
+        const oldPath = leaf(row.get("OldPath"));
+        const revisionType = leaf(row.get("RevisionType"));
+        if (!/^en[A-Za-z0-9]+$/.test(revisionType)) invalid();
+        const supportedType = revisionType === "enDirectory" || revisionType === "enTextFile";
+        if (supportedStatus && (kind === "moved") !== Boolean(oldPath)) invalid();
+        if (oldPath && identity(oldPath) === path) invalid();
+        if (seen.has(path)) invalid();
+        seen.add(path);
+        // Validate the entire document before reporting unsupported profiles: a later unsafe
+        // identity/structure must not be masked by an earlier unadmitted record.
+        if (!supportedStatus || !supportedType) { unsupported = true; continue; }
+        items.push({ statusCode: statusCode as keyof typeof kinds, kind: kind!, path, isDirectory: revisionType === "enDirectory", ...(oldPath ? { sourcePath: oldPath } : {}) });
+    }
+    if (unsupported) throw new StatusXmlError("unsupported_source");
+    const summary: MachineReadableStatusSummary = { totalPending: items.length, added: 0, changed: 0, moved: 0, deleted: 0, private: 0, other: 0, tracked: 0 };
+    for (const row of items) summary[row.kind]++;
+    summary.tracked = items.length - summary.private;
+    return { output, items, summary };
+}

package/src/domain/switch-contract.ts

@@ -0,0 +1,60 @@
+import { parseMachineReadablePendingItems, summarizePendingItems } from "./pending";
+import type { SwitchAttempt, SwitchCapture } from "../execution/switch-command";
+export type { SwitchAttempt, SwitchCapture } from "../execution/switch-command";
+export type SwitchRequest = { branch: string; pendingChanges?: "shelve" | "bring" | "cancel"; preflight?: boolean; format?: "text" | "json"; workdir?: string };
+export type SwitchBranchObservation = { branch: string; repository: string; server: string; basis: "standard-status"; scope: "loaded-workspace" };
+export type SwitchSummary = { totalPending: number; tracked: number; private: number; added: number; changed: number; moved: number; deleted: number; other: number };
+export type SwitchStepName = "branch-before" | "pending-before" | "shelve" | "pending-recovery" | "switch" | "branch-after";
+export type SwitchStep = { name: SwitchStepName; argv: string[]; attempt: SwitchAttempt; capture: SwitchCapture; evidence: "unadmitted" | "admitted" | "terminal-only" | "eligible-no-changes"; effect: "read-observed" | "not-attempted" | "command-completed" | "uncertain"; branch: SwitchBranchObservation | null; summary: SwitchSummary | null; records: number };
+export type SwitchStrategy = "unresolved" | "already-on-target-branch" | "silent-noinput" | "direct-switch-private-only" | "blocked-bring-tracked-pending" | "cancel-with-pending" | "shelve-then-switch-noinput";
+export type SwitchData = { requestedTarget: string | null; workdir: string | null; pendingPolicy: "shelve" | "bring" | "cancel"; defaultedPolicy: boolean; preflight: boolean; strategy: SwitchStrategy; wouldRun: boolean; plannedMutations: Array<"shelve" | "switch">; unattemptedMutations: Array<"shelve" | "switch">; steps: SwitchStep[]; branchBefore: SwitchBranchObservation | null; branchAfter: SwitchBranchObservation | null; pendingBefore: SwitchSummary | null; pendingRecovery: SwitchSummary | null; observedShelveset: null; usedNoChangesShelveRecovery: boolean; targetVerification: "unverified" | "name-only" | "exact-qualifier-spelling"; serverAliasEquivalence: "unverified"; filePreservation: "unverified"; xlinkEffects: "unverified"; effect: "not-attempted" | "command-completed" | "uncertain" };
+type Base = { schemaVersion: 1; action: "switch-branch"; provenance: { source: "plastic"; producer: "@aefree/pi-plastic"; contentTrust: "external" }; sourceAdmission: "windows-cm11.0.16.10371-observed"; completeness: { read: "complete" | "incomplete" | "unknown"; capture: "complete" | "incomplete" | "unknown"; projection: true }; data: SwitchData };
+export type SwitchReceipt = Base & ({ ok: true; outcome: "preflight" | "already-loaded" | "switched" } | { ok: false; outcome: "canceled" | "blocked" | "failed" | "uncertain" | "command-completed-unverified"; error: { code: "invalid_request" | "unsupported_source" | "observation_failed" | "policy_canceled" | "policy_blocked" | "mutation_failed" | "target_unverified" | "producer_failed"; stage: "input" | SwitchStepName | "policy" | "producer"; message: string } });
+export const safeSwitchValue = (value: unknown): value is string => typeof value === "string" && value.length > 0 && value.length <= 4096 && value === value.trim() && !/[\u0000-\u001f\u007f-\u009f]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(value);
+const identity = (value: string) => safeSwitchValue(value) && !/[?\uFFFD]/u.test(value);
+const hierarchy = (value: string) => identity(value) && /^\/(?:[^/@\\]+)(?:\/[^/@\\]+)*$/u.test(value);
+export function parseSwitchTarget(value: string) {
+    const text = value.replace(/^br:/i, "");
+    const m = /^(\/[^@]+)(?:@([^@]+)@([^@]+(?:@(?:cloud|unity))?))?$/u.exec(text);
+    if (!safeSwitchValue(value) || !m || !hierarchy(m[1]) || m[2] !== undefined && (!identity(m[2]) || !identity(m[3]))) return null;
+    return { branch: m[1], repository: m[2] ?? null, server: m[3] ?? null };
+}
+export function parseSwitchLoadedBranch(text: string): SwitchBranchObservation | null {
+    const lines = text.split(/\r?\n/);
+    const grammar = /^(\/[^@]+)@([^@]+)@([^\s]+) \(cs:(?:0|[1-9][0-9]{0,19}) - head\)$/u;
+    const match = grammar.exec(lines[0] ?? "");
+    if (!match || lines.slice(1).some(line => grammar.test(line)) || !hierarchy(match[1]) || !identity(match[2]) || !identity(match[3]) || !safeSwitchValue(`${match[1]}@${match[2]}@${match[3]}`) || !parseSwitchTarget(`${match[1]}@${match[2]}@${match[3]}`)) return null;
+    return { branch: match[1], repository: match[2], server: match[3], basis: "standard-status", scope: "loaded-workspace" };
+}
+export function compareSwitchTarget(observed: SwitchBranchObservation, requested: string): SwitchData["targetVerification"] {
+    const target = parseSwitchTarget(requested);
+    if (!target || observed.branch !== target.branch) return "unverified";
+    if (target.repository === null) return "name-only";
+    return target.repository === observed.repository && target.server === observed.server ? "exact-qualifier-spelling" : "unverified";
+}
+const decimal = /^(0|[1-9][0-9]{0,19})$/;
+const absolute = (value: string) => identity(value) && /^(?:[A-Za-z]:[\\/]|\\\\)/.test(value);
+export const switchPendingArgv = ["status", "--machinereadable", "--includeRevId", "--fieldseparator=\x1f"];
+/** Selected strict pending source; legacy selector and checkin's 500-record contract stay untouched. */
+export function parseSwitchPending(text: string, cwd: string) {
+    const lines = text.split(/\r?\n/); if (lines.at(-1) === "") lines.pop();
+    const records = Math.min(lines.length, 20001), h = (lines[0] ?? "").split("\x1f");
+    let admitted = lines.length > 0 && lines.length <= 20000 && h.length === 4 && h[0] === "STATUS" && decimal.test(h[1]) && identity(h[2] ?? "") && identity(h[3] ?? "");
+    for (const line of lines.slice(1)) {
+        const f = line.split("\x1f");
+        if (f[0] === "MV") {
+            if (f.length !== 7 || f[1] !== "100%" || !absolute(f[2]) || !absolute(f[3]) || f[4] !== "False" || !decimal.test(f[5]) || f[5] === "0" || f[6] !== "NO_MERGES") admitted = false;
+        } else if (f.length !== 5 || !/^(PR|AD|CH|LD)$/.test(f[0]) || !absolute(f[1]) || !/^(True|False)$/.test(f[2]) || !(/^(PR|AD)$/.test(f[0]) ? f[3] === "-1" : decimal.test(f[3]) && f[3] !== "0") || f[4] !== "NO_MERGES") admitted = false;
+    }
+    if (!admitted) return { admitted: false, records, summary: null };
+    const items = parseMachineReadablePendingItems(text, cwd);
+    if (items.length !== lines.length - 1) return { admitted: false, records, summary: null };
+    const { privatePaths: _privatePaths, ...summary } = summarizePendingItems(items, cwd);
+    return { admitted: true, records, summary };
+}
+/** Genuine empty shelve source: exit1, empty stdout and exact workspace-specific error, never a loose substring. */
+export function admittedSwitchNoChanges(stdout: string, stderr: string, cwd: string): boolean {
+    const m = /^Error: There are no changes in the workspace ([^\r\n]+)\r?\n?$/u.exec(stderr);
+    const key = (s: string) => s.replace(/\\/g, "/").replace(/\/$/, "").toLowerCase();
+    return stdout === "" && !!m && safeSwitchValue(m[1]) && key(m[1]) === key(cwd);
+}