@aefree/pi-plastic 0.8.3 → 0.8.5

package/src/domain/pending.ts

@@ -14,6 +14,8 @@ export type PendingItem = {
     revisionId?: string;
     sourceWorkspacePath?: string;
     baseRepository?: string;
+    /** Observation-only fraction in [0, 1]; producer precision is transport-specific. */
+    similarity?: number;
 };
 
 export type PendingItemSummary = {
@@ -35,6 +37,8 @@ export type MachineReadableStatusItem = {
     isDirectory: boolean;
     revisionId?: string;
     sourcePath?: string;
+    /** Observation-only fraction in [0, 1], never rename authorization. */
+    similarity?: number;
 };
 
 export type MachineReadableStatusSummary = Omit<PendingItemSummary, "privatePaths">;
@@ -185,11 +189,29 @@ export const parseMachineReadablePendingItems = (output: string, cwd: string): P
 export const hasStatusPathDecodingLoss = (path: string, platform: NodeJS.Platform = process.platform): boolean =>
     path.includes("\uFFFD") || (platform === "win32" && path.includes("?"));
 
+// Observation-only lexical identities. Never use these diagnostics as mutation admission.
+export const statusObservationPathKey = (value: string): string | null => {
+    if (!value || value.length > 4096 || /[\u0000-\u001f\uFFFE\uFFFF]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(value)) return null;
+    const path = value.replace(/\\/g, "/");
+    if (!/^(?:\/|[A-Za-z]:\/)/.test(path) || path.split("/").some(part => part === "." || part === "..")) return null;
+    const windows = /^[A-Za-z]:\//.test(path) || path.startsWith("//");
+    const tail = path.slice(path.startsWith("//") ? 2 : windows ? 3 : 1);
+    if (tail.includes("//") || (windows && (/[<>:"|?*]/.test(tail) || tail.split("/").some(part => /[. ]$/.test(part))))) return null;
+    if (path.startsWith("//") && !/^\/\/[^/]+\/[^/]+\//.test(path)) return null;
+    const key = windows ? path.toLowerCase() : path;
+    return key.length > (windows ? 3 : 1) ? key.replace(/\/$/, "") : key;
+};
+export const statusObservationPathRoot = (value: string): string => {
+    const path = value.replace(/\\/g, "/").toLowerCase();
+    return path.match(/^[a-z]:/)?.[0] ?? (path.startsWith("//") ? path.split("/").slice(0, 4).join("/") : "/");
+};
+
 // Diagnostics deliberately leave the legacy selection parser unchanged for mutation/diff consumers.
 export const diagnoseMachineReadablePendingItems = (output: string, cwd: string, platform: NodeJS.Platform = process.platform) =>
 {
     const diagnostics = { valid: 0, blank: 0, header: 0, unsupported: 0, malformed: 0, ambiguousLegacyMove: 0 };
     const pendingItems: PendingItem[] = [];
+    const seen = new Set<string>();
     for (const rawLine of output.split(/\r?\n/))
     {
         const line = rawLine.trim();
@@ -198,7 +220,32 @@ export const diagnoseMachineReadablePendingItems = (output: string, cwd: string,
         if (fields[0] === "STATUS" && fields.length === 4 && /^\d+$/.test(fields[1]) && fields[2] && fields[3]) { diagnostics.header++; continue; }
         if (/^STATUS \d+ \S+ \S+$/.test(line)) { diagnostics.header++; continue; }
         if (fields[0] === "STATUS" || line.startsWith("STATUS ")) { diagnostics.malformed++; continue; }
+        // Inferred moves are observed separately; legacy mutation/diff selection is unchanged.
+        if (fields[0] === "LM") {
+            const [, percent, source, destination, directory, revision, metadata] = fields;
+            const sourceKey = statusObservationPathKey(source ?? "");
+            const destinationKey = statusObservationPathKey(destination ?? "");
+            const validPercent = (percent?.length ?? 0) <= 64 && /^(?:100(?:\.0+)?|[0-9]{1,2}(?:\.[0-9]+)?)%$/.test(percent ?? "");
+            if (fields.length !== 7 || !validPercent || !sourceKey || !destinationKey || sourceKey === destinationKey ||
+                statusObservationPathRoot(source) !== statusObservationPathRoot(destination) ||
+                seen.has(sourceKey) || seen.has(destinationKey) || (directory !== "True" && directory !== "False") ||
+                !/^[1-9][0-9]{0,19}$/.test(revision ?? "") || metadata !== "NO_MERGES" ||
+                [source, destination].some(path => hasStatusPathDecodingLoss(path, platform))) {
+                diagnostics.malformed++; continue;
+            }
+            seen.add(sourceKey); seen.add(destinationKey);
+            pendingItems.push({ statusCode: "LM", kind: "moved", workspacePath: destination,
+                normalizedPath: toNormalizedAbsolutePath(destination, cwd), comparisonKey: toPathComparisonKey(destination, cwd),
+                isDirectory: directory === "True", revisionId: revision, sourceWorkspacePath: source, similarity: Number(percent.slice(0, -1)) / 100 });
+            diagnostics.valid++; continue;
+        }
         const items = parseMachineReadablePendingItems(line, cwd);
+        for (const item of items) {
+            for (const path of [item.workspacePath, item.sourceWorkspacePath].filter((path): path is string => path !== undefined)) {
+                const key = statusObservationPathKey(path);
+                if (key) { if (seen.has(key)) diagnostics.malformed++; seen.add(key); }
+            }
+        }
         pendingItems.push(...items);
         if (items.length) {
             diagnostics.valid++;
@@ -239,6 +286,7 @@ export const toMachineReadableStatusItems = (pendingItems: PendingItem[]): Machi
         isDirectory: item.isDirectory,
         ...(item.revisionId ? { revisionId: item.revisionId } : {}),
         ...(item.sourceWorkspacePath ? { sourcePath: item.sourceWorkspacePath } : {}),
+        ...(item.similarity !== undefined ? { similarity: item.similarity } : {}),
     }));
 
 export const toMachineReadableStatusSummary = (pendingItems: PendingItem[], cwd: string): MachineReadableStatusSummary =>

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

@@ -13,7 +13,7 @@ export type MergeReceiptData = {
     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; warningsObserved: number } | null;
+    parse: { records: number; malformed: boolean; unknownOperations: number; changesetsObserved: number; conflictsObserved: number; warningsObserved: number; unknownOperationClasses: string[]; resolvedConflictsVerified: number } | null;
     observedChangesets: ServerChangeset[];
     conflictPaths: string[];
     counts: { changesetsReturned: number; changesetsOmitted: number; conflictsReturned: number; conflictsOmitted: number };

package/src/domain/status-xml.ts

@@ -1,5 +1,5 @@
 import { DOMParser, type Element } from "@xmldom/xmldom";
-import type { MachineReadableStatusItem, MachineReadableStatusSummary } from "./pending";
+import { statusObservationPathKey, statusObservationPathRoot, type MachineReadableStatusItem, type MachineReadableStatusSummary } from "./pending";
 
 import { STATUS_XML_LIMITS } from "../execution/status-xml-limits";
 export { STATUS_XML_LIMITS } from "../execution/status-xml-limits";
@@ -13,11 +13,12 @@ export class StatusXmlError extends Error {
 }
 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 kinds = { CH: "changed", CO: "changed", CP: "added", RP: "changed", AD: "added", DE: "deleted", LD: "deleted", MV: "moved", LM: "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();
+    if (!statusObservationPathKey(value)) invalid();
     return value;
 };
 
@@ -95,6 +96,7 @@ export function parseStatusXml(bytes: Uint8Array): { output: string; items: XmlS
         if (change.tagName !== "Change") invalid();
         const row = children(change, fields);
         // All recognized fields are scalar in the verified configuration.
+        // TypeVerbose/MergesInfo are display metadata, never merge-readiness evidence.
         for (const value of row.values()) leaf(value);
         const statusCode = leaf(row.get("Type"));
         if (!/^[A-Z][A-Z0-9_]*$/.test(statusCode)) invalid();
@@ -104,15 +106,28 @@ export function parseStatusXml(bytes: Uint8Array): { output: string; items: XmlS
         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";
+        const supportedType = revisionType === "enDirectory" || revisionType === "enTextFile" || revisionType === "enBinaryFile";
         if (supportedStatus && (kind === "moved") !== Boolean(oldPath)) invalid();
-        if (oldPath && identity(oldPath) === path) invalid();
-        if (seen.has(path)) invalid();
-        seen.add(path);
+        if (oldPath) identity(oldPath);
+        const keys = [path, ...(oldPath ? [oldPath] : [])].map(value => statusObservationPathKey(value)!);
+        if (new Set(keys).size !== keys.length || keys.some(key => seen.has(key))) invalid();
+        for (const key of keys) seen.add(key);
+        let similarity: number | undefined;
+        if (statusCode === "LM") {
+            if (statusObservationPathRoot(path) !== statusObservationPathRoot(oldPath)) invalid();
+            const perUnit = leaf(row.get("SimilarityPerUnit"));
+            if (perUnit.length > 64 || !/^(?:0(?:\.[0-9]+)?|1(?:\.0+)?)$/.test(perUnit)) invalid();
+            similarity = Number(perUnit);
+            // Rounded display is neither the identity nor an exact equality check on the fraction.
+            if (row.has("Similarity")) {
+                const display = leaf(row.get("Similarity"));
+                if (display.length > 64 || !/^(?:100(?:\.0+)?|[0-9]{1,2}(?:\.[0-9]+)?)%$/.test(display)) invalid();
+            }
+        }
         // 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 } : {}) });
+        items.push({ statusCode: statusCode as keyof typeof kinds, kind: kind!, path, isDirectory: revisionType === "enDirectory", ...(oldPath ? { sourcePath: oldPath } : {}), ...(similarity !== undefined ? { similarity } : {}) });
     }
     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 };

package/src/domain/switch-contract.ts

@@ -21,7 +21,8 @@ export function parseSwitchTarget(value: string) {
 }
 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;
+    // A numeric head is an annotation, not the loaded changeset or branch owner.
+    const grammar = /^(\/[^@]+)@([^@]+)@([^\s]+) \(cs:(?:0|[1-9][0-9]{0,19}) - head(?::(?:0|[1-9][0-9]{0,19}))?\)$/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" };

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

@@ -1,3 +1,4 @@
+import { parseMergedApply, type MergedDeclaration } from "./merged-workspace";
 import type { WorkspaceMergeAttempt, WorkspaceMergeCapture } from "../execution/workspace-merge-command";
 export type { WorkspaceMergeAttempt, WorkspaceMergeCapture } from "../execution/workspace-merge-command";
 export type MergeAction = "merge" | "finalize-merge";
@@ -6,9 +7,9 @@ export const safeMergeText = (v: unknown): v is string => typeof v === "string"
 export type MergeStage = { attempt: WorkspaceMergeAttempt; capture: WorkspaceMergeCapture | null; admission: "not-observed" | "unsupported" | "admitted" };
 export type WorkspaceMergeData = {
  intendedArgv: readonly string[]; workingDirectory: string | null; requestedSource: string | null; strategy: MergeStrategy | null; cherrypicking: boolean | null; forced: boolean | null; previewRequested: boolean | null; outputFormatRequested: "text" | "json" | null;
- apply: MergeStage; shortStatus: MergeStage; fullStatus: MergeStage; pendingReadMode: "short" | "copied-machine";
+ apply: MergeStage; shortStatus: MergeStage; fullStatus: MergeStage; pendingReadMode: "short" | "copied-machine" | "merged-machine";
  commandCompleted: boolean; observedWorkspaceIdentity: null; observedSourceIdentity: null; observedFinalizedMetadata: null; observedPreservation: null; observedPendingItems: null;
- fileConflictCount: number | null; protocol: "not-observed" | "already-connected" | "file-conflict" | "apply-add" | "apply-add-copied" | "unsupported";
+ fileConflictCount: number | null; protocol: "not-observed" | "already-connected" | "file-conflict" | "apply-add" | "apply-add-copied" | "merged-candidate" | "unsupported";
  checkinReadiness: "unknown" | "blocked" | "supported-no-unresolved-signals"; verification: "unverified"; effect: "not-attempted" | "not-proven" | "uncertain";
 };
 type Header = { schemaVersion: 1; action: MergeAction; provenance: { source: "plastic"; producer: "@aefree/pi-plastic"; contentTrust: "external" }; completeness: { capture: "complete" | "incomplete" | "unknown"; projection: true }; data: WorkspaceMergeData };
@@ -19,7 +20,9 @@ export function buildWorkspaceMergeArgv(source: string, strategy: MergeStrategy,
  if(cherry)result.push("--cherrypicking");if(forced)result.push("--forced");return result;
 }
 /** Narrow observed CM profile. Unknown records/text are not missing-conflict proof. */
-export function admitWorkspaceMergeOutput(text: string, token: string): { protocol: WorkspaceMergeData["protocol"]; fileConflictCount: number | null; copiedPaths: string[]; addedPaths: string[] } {
+export function admitWorkspaceMergeOutput(text: string, token: string): { protocol: WorkspaceMergeData["protocol"]; fileConflictCount: number | null; copiedPaths: string[]; addedPaths: string[]; declarations?: MergedDeclaration[] } {
+ const declarations = parseMergedApply(text, token);
+ if (declarations?.some(d => d.status !== "CP")) return { protocol: "merged-candidate", fileConflictCount: declarations.filter(d => d.status === "CO").length, copiedPaths: [], addedPaths: [], declarations };
  const start=token+"S__",end=token+"E__",field=token+"F__";let rest=text,count=0,conflicts=0,connected=0,adds=0; const copiedPaths:string[]=[], addedPaths:string[]=[];
  while(rest.trim()!==""){
   if(++count>256)return {protocol:"unsupported",fileConflictCount:null,copiedPaths:[],addedPaths:[]};const s=rest.indexOf(start),e=rest.indexOf(end,s+start.length);

package/src/operations/checkin-receipt.ts

@@ -1,3 +1,6 @@
+import { win32 } from "node:path";
+import { admitMergedStandardStatus, correlateMergedCheckin } from "../domain/merged-workspace";
+import { parseSwitchLoadedBranch } from "../domain/switch-contract";
 import { randomBytes } from "node:crypto";
 import { buildFallbackScopePaths } from "../domain/paths";
 import { summarizePendingItems, resolveCheckinPaths, filterPendingItemsByScope, selectPrivatePathsForAutoAdd, type PendingItem } from "../domain/pending";
@@ -7,6 +10,34 @@ const pendingArgv = ["status", "--machinereadable", "--includeRevId", "--fieldse
 const summary = (items: PendingItem[], cwd: string): CheckinSummary => { const { privatePaths: _, ...s } = summarizePendingItems(items, cwd); return s; };
 const normal = (o: CheckinCommandObservation) => o.capture.complete && !o.failed && o.attempt.state === "started" && o.attempt.terminal === "observed" && o.attempt.exitCode !== null && !o.attempt.aborted && !o.attempt.timedOut;
 const success = (o: CheckinCommandObservation) => normal(o) && o.attempt.exitCode === 0 && o.capture.stderrBytes === 0;
+// Inspect section/row markers, never words embedded in a branch or filename.
+// Default status can omit unchanged checkouts, so a valid header-only body is
+// allowed; unfamiliar sections/metadata still cannot establish ordinary state.
+function ordinaryStatusBodyAdmitted(text: string): boolean {
+    const shapes = {
+        Changed: { header: /^    Status +Size +Last Modified +Path *$/, label: "(?:Changed|Checked-out \\((?:changed|unchanged)\\))" },
+        Added: { header: /^    Status +Size +Last Modified +Path *$/, label: "(?:Added|Private)" },
+        Deleted: { header: /^    Status +Size +Path *$/, label: "(?:Deleted|Locally deleted|Removed)" },
+        Moved: { header: /^    Status +Size +Similarity +Path *$/, label: "(?:Moved|Moved locally)" },
+    };
+    let section: keyof typeof shapes | null = null, needsHeader = false;
+    const seen = new Set<string>();
+    for (const line of text.split(/\r?\n/).slice(1)) {
+        if (!line.trim()) continue;
+        if (line.length > 4096 || /[\u0000-\u001f\u007f-\u009f]/.test(line)) return false;
+        if (Object.hasOwn(shapes, line)) {
+            if (needsHeader || seen.has(line)) return false;
+            seen.add(line); section = line as keyof typeof shapes; needsHeader = true; continue;
+        }
+        if (!section) return false;
+        const shape = shapes[section];
+        if (needsHeader) { if (!shape.header.test(line)) return false; needsHeader = false; continue; }
+        // A status-label annotation is metadata, unlike a parenthesis in the
+        // later path cell. Unknown annotations (including Merge from) fail.
+        if (new RegExp(`^    ${shape.label} +\\(`).test(line) || !new RegExp(`^    ${shape.label} {2,}.+$`).test(line)) return false;
+    }
+    return !needsHeader;
+}
 function validateRequest(input: unknown): asserts input is CheckinRequest {
     if (!input || typeof input !== "object" || Array.isArray(input)) throw Error("Invalid bounded checkin input.");
     const r = input as Record<string, unknown>;
@@ -66,6 +97,21 @@ export async function assembleCheckinReceipt(input: unknown): Promise<CheckinRec
         const before = await read("pending-before");
         if (!before) return finish("unsupported", "pending_source_unadmitted", "pending", "Pending selection could not be admitted; no mutation was dispatched.");
         data.pendingBefore = summary(before.items, cwd);
+        const merged = before.merged;
+        let loaded: ReturnType<typeof parseSwitchLoadedBranch> = null;
+        // CO/-1/NO_MERGES also occurs during an unresolved merge. Read the
+        // native link state before any checkin, including standalone/preflight.
+        if (merged || before.items.some(i => i.statusCode === "CO")) {
+            const { o, s } = await record("merge-readiness", ["status"]);
+            loaded = success(o) ? parseSwitchLoadedBranch(o.stdout ?? "") : null;
+            const source = /^    Merge from cs:[1-9][0-9]{0,19} at (.+)\r?$/m.exec(o.stdout ?? "")?.[1];
+            const ready = loaded && loaded.repository === before.repository && loaded.server === before.server && (merged
+                ? !!source && admitMergedStandardStatus(o.stdout!, merged, source, cwd)
+                : ordinaryStatusBodyAdmitted(o.stdout ?? ""));
+            if (!ready) return finish("unsupported", "merge_readiness_unadmitted", "pending", "Merge source/resolution metadata could not be admitted; no checkin was dispatched.");
+            s.evidence = "admitted";
+        }
+        if (merged && input.includePrivate) return finish("unsupported", "merged_private_scope", "pending", "Merged checkin does not admit private inclusion; leave unrelated private work excluded.");
         let includedAbsolute: string[] = [], scoped = before.items, apply = input.applyChanged ?? false;
         if (input.paths?.length) {
             const r = resolveCheckinPaths(input.paths, before.items, cwd);
@@ -74,20 +120,33 @@ export async function assembleCheckinReceipt(input: unknown): Promise<CheckinRec
             scoped = filterPendingItemsByScope(before.items, includedAbsolute);
             if (!data.includedPaths.length) return finish("failed", "NO_PENDING_PATHS", "pending", "None of the provided checkin paths have admitted pending changes.");
         }
+        if (merged) {
+            data.excludedPaths.push(...before.items.filter(i => i.kind === "private").map(i => ({ path: i.workspacePath, reason: "Unrelated private work excluded from merged checkin (includePrivate=false)." })));
+            scoped = scoped.filter(i => i.kind !== "private");
+            if (merged.privateRows.length) {
+                // Do not rely on workspace-wide --all selection in the presence
+                // of private work. These directories are proven disjoint above.
+                data.includedPaths = merged.rows.map(r => win32.relative(cwd, r.path));
+            }
+            // All merged controlled rows must remain selected. Partial merge
+            // checkins and directory scopes overlapping private rows are unproven.
+            if (scoped.length !== merged.rows.length) return finish("unsupported", "merged_partial_scope", "pending", "All correlated merged controlled paths must be selected.");
+        }
         const nonce = randomBytes(16).toString("hex"), seps = { start: `__PI_CI_START_${nonce}__`, end: `__PI_CI_END_${nonce}__`, field: `__PI_CI_FIELD_${nonce}__` };
         const command = (paths: string[], force: boolean) => ["checkin", `-c=${input.message}`, ...(input.includeAll ? ["--all"] : []), ...(force ? ["--applychanged"] : []), ...(input.includePrivate ? ["--private"] : []), ...paths, "--machinereadable", `--startlineseparator=${seps.start}`, `--endlineseparator=${seps.end}`, `--fieldseparator=${seps.field}`];
         const initial = command(data.includedPaths, apply); data.command = ["cm", ...initial]; data.wouldRun = true;
         if (input.preflight) return finish("preflight");
         const attempt = async (name: "initial-checkin" | "private-retry" | "fallback-checkin", argv: string[]) => {
             const { o, s } = await record(name, argv), p = parseCheckinEvidence(o.stdout ?? "", seps); s.records = p.records;
-            const admitted = p.admitted && p.changesets.every(c => c.repository === before.repository);
+            const mergedEvents = !merged || correlateMergedCheckin(p.events, merged, cwd);
+            const admitted = p.admitted && mergedEvents && p.changesets.every(c => c.repository === before.repository && c.server === before.server && (!loaded || c.branch === loaded.branch));
             if (admitted && normal(o)) {
                 s.evidence = "admitted";
                 data.itemEvents.push(...p.events); data.observedChangesets.push(...p.changesets);
             }
             if (success(o) && admitted && p.changesets.length === 1) { created = p.changesets[0]; s.changeset = created; s.effect = "changeset-created"; }
             // Only genuine complete native failure without a created record may drive the existing recovery policy.
-            const retryEligible = normal(o) && admitted && o.attempt.exitCode !== 0 && p.changesets.length === 0;
+            const retryEligible = !merged && normal(o) && admitted && o.attempt.exitCode !== 0 && p.changesets.length === 0;
             return { completed: !!s.changeset, retryEligible, message: retryEligible ? o.stderr ?? "" : "" };
         };
         stage = "checkin";

package/src/operations/closeout-receipt.ts

@@ -3,6 +3,7 @@ import { parseSwitchTarget, parseSwitchLoadedBranch, compareSwitchTarget, parseS
 import { checkinSafeComment, checkinSafeValue } from "../domain/checkin-contract";
 import { admitCleanStandardStatus } from "../domain/workspace-merge-contract";
 import { parseCopiedPending } from "../domain/copied-merge";
+import { parseMergedPending, admitMergedStandardStatus, type MergedPending } from "../domain/merged-workspace";
 import { cmWhereEquals } from "../domain/branches";
 import { buildCloseoutParentArgv, CLOSEOUT_STAGE_NAMES, closeoutChildEffect, closeoutCaptures, type CloseoutData, type CloseoutReceipt, type CloseoutRequest, type CloseoutStageName, type CloseoutRead, type CloseoutStage } from "../domain/closeout-contract";
 import { captureWorkspaceMergeCommand, emptyWorkspaceMergeAttempt } from "../execution/workspace-merge-command";
@@ -29,7 +30,7 @@ export async function assembleCloseoutReceipt(input:unknown):Promise<CloseoutRec
  };
  const push=(s:CloseoutStage)=>{if(data.stages.length>=16)throw Error();data.stages.push(s);data.unattemptedStages=data.unattemptedStages.filter(n=>n!==s.name);};
  const read=async(name:CloseoutStageName,argv:string[])=>{stage=name;const s:CloseoutRead={argv:[...argv],attempt:{...emptyWorkspaceMergeAttempt(),state:"unknown"},capture:null,admission:"unsupported",branch:null,parentPath:null,emptyParentResult:false,summary:null};push({name,kind:"read",result:s});const o=await captureWorkspaceMergeCommand([...argv],data.requested!.workdir);s.attempt=o.attempt;s.capture=o.capture;const success=o.capture.complete&&!o.failed&&o.attempt.state==="started"&&o.attempt.terminal==="observed"&&o.attempt.exitCode===0&&!o.attempt.aborted&&!o.attempt.timedOut&&o.stderr===""&&o.stdout!==null;return {s,o,success};};
- const loaded=async(name:CloseoutStageName,verify=false)=>{const {s,o,success}=await read(name,["status"]);if(success){s.branch=parseSwitchLoadedBranch(o.stdout!);if(s.branch)s.admission="admitted";}if(!s.branch)return false;if(verify){data.targetVerification=compareSwitchTarget(s.branch,data.targetBranch!);if(data.targetVerification==="unverified")return false;}return true;};
+ const loaded=async(name:CloseoutStageName,verify=false,mergedPending?:MergedPending|null)=>{const {s,o,success}=await read(name,["status"]);if(success){s.branch=parseSwitchLoadedBranch(o.stdout!);if(s.branch&&(!mergedPending||admitMergedStandardStatus(o.stdout!,mergedPending,data.sourceBranch!,data.requested!.workdir)))s.admission="admitted";else s.branch=null;}if(!s.branch)return false;if(verify){data.targetVerification=compareSwitchTarget(s.branch,data.targetBranch!);if(data.targetVerification==="unverified")return false;}return true;};
  const pending=async(name:"pending-before"|"pending-final")=>{const {s,o,success}=await read(name,[...switchPendingArgv]);if(success){const p=parseSwitchPending(o.stdout!,data.requested!.workdir);if(p.summary){s.admission="admitted";s.summary=p.summary;}}return s.summary;};
  try{
   const submitted=input&&typeof input==="object"&&!Array.isArray(input)?Object.freeze({...input}):input;admitRequest(submitted);const cwd=submitted.workdir??process.cwd();if(!safeSwitchValue(cwd)||!safeSwitchValue(resolve(cwd)))return finish("failed","invalid_request","Closeout needs a bounded workdir.");data.requested={source:submitted.source??null,target:submitted.target??null,message:submitted.message??null,cardRef:submitted.cardRef??null,strategy:submitted.strategy??"auto",updateTarget:submitted.updateTarget??true,includePrivate:submitted.includePrivate??false,preflight:submitted.preflight??false,outputFormat:submitted.format??"text",workdir:cwd};
@@ -60,9 +61,13 @@ export async function assembleCloseoutReceipt(input:unknown):Promise<CloseoutRec
   if(data.requested.updateTarget){stage="update";childEntered=true;const updated=await assembleUpdateReceipt({workdir:cwd});push({name:"update",kind:"update",result:updated});childEntered=false;if(!updated.ok)return finish("failed","child_failed");}
   if(!await loaded("loaded-before-merge",true))return finish("failed","target_unverified");
   stage="merge";childEntered=true;const merged=await assembleWorkspaceMergeReceipt("merge",{source:data.sourceBranch!,strategy:data.requested.strategy,workdir:cwd});push({name:"merge",kind:"merge",result:merged});childEntered=false;if(!merged.ok)return finish("failed","child_failed");
-  const copiedReady=merged.data.protocol==="apply-add-copied";
-  const ready=await read("readiness",copiedReady?[...switchPendingArgv]:["status"]);if(!ready.success||ready.o.stderr!==""||!(copiedReady?!!parseCopiedPending(ready.o.stdout!,cwd):admitCleanStandardStatus(ready.o.stdout!)))return finish("failed","observation_failed","Independent post-merge readiness is outside the admitted profile; no checkin permitted. Prior effects remain possible.");ready.s.admission="admitted";
-  if(!await loaded("loaded-before-checkin",true))return finish("failed","target_unverified");
+  const copiedReady=merged.data.protocol==="apply-add-copied",mergedReady=merged.data.protocol==="merged-candidate";
+  const ready=await read("readiness",copiedReady||mergedReady?[...switchPendingArgv]:["status"]);
+  const mergedPending=mergedReady&&ready.success?parseMergedPending(ready.o.stdout!,cwd):null;
+  if(!ready.success||ready.o.stderr!==""||!(mergedReady?!!mergedPending:copiedReady?!!parseCopiedPending(ready.o.stdout!,cwd):admitCleanStandardStatus(ready.o.stdout!)))return finish("failed","observation_failed","Independent post-merge readiness is outside the admitted profile; no checkin permitted. Prior effects remain possible.");ready.s.admission="admitted";
+  // The independent machine snapshot is not readiness proof by itself: the next
+  // full status must still correlate its source link, namespace and resolved rows.
+  if(!await loaded("loaded-before-checkin",true,mergedPending))return finish("failed","target_unverified");
   const checkinArgs={message:data.checkinMessage,includeAll:true,includePrivate:data.requested.includePrivate,workdir:cwd};
   stage="checkin-preflight";childEntered=true;const preview=await assembleCheckinReceipt({...checkinArgs,preflight:true});push({name:"checkin-preflight",kind:"checkin",result:preview});childEntered=false;if(!preview.ok)return finish("failed","child_failed");
   stage="checkin";childEntered=true;const checked=await assembleCheckinReceipt(checkinArgs);push({name:"checkin",kind:"checkin",result:checked});childEntered=false;data.createdChangeset=checked.data.createdChangeset;if(!checked.ok)return finish("failed","child_failed");

package/src/operations/consolidated-diff.ts

@@ -17,10 +17,23 @@ export type DiffRequest = { workdir?:string;format?:"text"|"json";maxChars?:numb
     {mode:"workspace";paths:string[];allPending?:never;includePrivate?:never;maxFiles?:number} |
     {mode:"workspace";allPending:true;paths?:never;includePrivate?:boolean;maxFiles?:number}
 );
+const baseMessages = {
+    "fileinfo-command": "Loaded-base fileinfo observation failed. No baseline was selected; inspect command/capture state before another attempt.",
+    "fileinfo-profile": "Loaded-base fileinfo XML is unsupported or malformed. Retain sanitized producer evidence; no baseline was guessed.",
+    "fileinfo-path": "Loaded-base fileinfo path does not match the requested workspace path. No baseline was selected.",
+    "fileinfo-type": "Loaded-base fileinfo item type is unsupported. No baseline was selected.",
+    "deletion-state": "Loaded deletion metadata conflicts with pending status. No empty baseline was substituted.",
+    "ls-command": "Loaded-base ls observation failed. No baseline was selected; inspect command/capture state before another attempt.",
+    "ls-profile": "Loaded-base ls XML is unsupported or malformed. Retain sanitized producer evidence; no baseline was guessed.",
+    "ls-path": "Loaded-base tree path does not match the inspected path. No baseline was selected.",
+    "revision-mismatch": "Loaded-base changeset/hash observations disagree. No baseline was selected; workspace changes may have displaced the observation.",
+    "ownership-mismatch": "Loaded-base repository/server identity is inconsistent. Alias equivalence is unverified. No baseline was selected.",
+} as const;
+type BaseReason = keyof typeof baseMessages;
 export class ConsolidatedDiffError extends Error {
-    constructor(readonly code:string,readonly stage:string) { super("The requested diff could not be verified."); }
+    constructor(readonly code:string,readonly stage:string,readonly reason?:BaseReason) { super("The requested diff could not be verified."); }
 }
-const fail=(code:string,stage:string):never=>{throw new ConsolidatedDiffError(code,stage);};
+const fail=(code:string,stage:string,reason?:BaseReason):never=>{throw new ConsolidatedDiffError(code,stage,reason);};
 const aborted=()=>{if(getActiveAbortSignal()?.aborted)fail("aborted","comparison");};
 const safe=(s:unknown,max:number):s is string=>typeof s==="string"&&s.length>0&&s.length<=max&&s.trim()===s&&!/[\u0000-\u001f\u007f-\u009f]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(s);
 export function validateDiffRequest(input:unknown):asserts input is DiffRequest {
@@ -76,21 +89,32 @@ function comparison(observation:DiffRevisionsObservation,left:DiffSide,right:Dif
 const side=(origin:DiffSide["origin"],bytes:Buffer,path:string|null,selector:string|null,identity:LoadedIdentity|null=null):DiffSide=>({origin,path,selector,identity,bytes:bytes.length,binary:isBinaryContent(bytes)});
 async function pending(cwd:string):Promise<DiffPendingSnapshot>{try{return parseDiffPending(await xmlCommand(["status","--xml","--encoding=utf-8","--fullpaths","--iscochanged"],cwd,"status"));}catch(e){if(e instanceof ConsolidatedDiffError)throw e;return fail("malformed_output","status");}}
 async function base(path:string,cwd:string,snapshot:DiffPendingSnapshot,item:DiffPendingItem|null):Promise<{selector:string;identity:LoadedIdentity;hash:string;algorithm:"md5"|"sha1"}>{
+    let phase:"fileinfo-profile"|"ls-profile"="fileinfo-profile";
     try {
         const info=parseLoadedFileInfo(await xmlCommand(["fileinfo",path,"--fields=ClientPath,ServerPath,RevisionChangeset,Hash,RepSpec,Status,Type","--xml","--encoding=utf-8"],cwd,"base"));
-        if(key(info.clientPath)!==key(path)||!["txt","bin","file"].includes(info.type.toLowerCase()))return fail("base_unavailable","base");
+        if(key(info.clientPath)!==key(path))return fail("base_unavailable","base","fileinfo-path");
+        if(!["txt","bin","file"].includes(info.type.toLowerCase()))return fail("base_unavailable","base","fileinfo-type");
         // DE removes live-tree membership/RepSpec. Deliberately inspect the
         // frozen loaded root tree, never retry a failed live-tree lookup or
         // guess a parent owning repository. Require loaded changeset/hash match.
         const deleted=item?.code==="DE";
-        if(deleted&&info.status!=="deleted")return fail("base_changed","base");
+        if(deleted&&info.status!=="deleted")return fail("base_changed","base","deletion-state");
         const query=deleted?["ls",info.serverPath,"--tree=cs:"+snapshot.changeset+"@"+snapshot.repository+"@"+snapshot.server,"--xml","--encoding=utf-8"]:["ls",path,"--xml","--encoding=utf-8"];
+        phase="ls-profile";
         const row=parseLoadedLs(await xmlCommand(query,cwd,"base"));
-        if((deleted?row.path!==info.serverPath:key(row.path)!==key(path))||row.changeset!==info.changeset||row.hash!==info.hash||!deleted&&info.repSpec!==row.repository+"@"+row.server)return fail("base_changed","base");
+        if(deleted?row.path!==info.serverPath:key(row.path)!==key(path))return fail("base_changed","base","ls-path");
+        if(row.changeset!==info.changeset||row.hash!==info.hash)return fail("base_changed","base","revision-mismatch");
+        if(!deleted&&info.repSpec!==row.repository+"@"+row.server)return fail("base_changed","base","ownership-mismatch");
         const selector="revid:"+row.revisionId+"@rep:"+row.repository+"@repserver:"+row.server;
         if(!validDiffRevisionsSelector(selector))return fail("invalid_selector","base");
         return {selector,identity:{revisionId:row.revisionId,changeset:row.changeset,repository:row.repository,server:row.server},hash:row.hash,algorithm:row.algorithm};
-    }catch(e){if(e instanceof ConsolidatedDiffError)throw e;return fail("base_unavailable","base");}
+    }catch(e){
+        if(e instanceof ConsolidatedDiffError){
+            if(e.code==="command_failed")return fail(e.code,e.stage,phase==="fileinfo-profile"?"fileinfo-command":"ls-command");
+            throw e;
+        }
+        return fail("base_unavailable","base",phase);
+    }
 }
 async function fileComparison(args:DiffRequest&{mode:"file"},cwd:string,root:string,snapshot:DiffPendingSnapshot|null,item:DiffPendingItem|null):Promise<Comparison>{
     const path=resolve(cwd,args.path);if(!contains(root,path))return fail("outside_workspace","selection");
@@ -111,7 +135,7 @@ async function fileComparison(args:DiffRequest&{mode:"file"},cwd:string,root:str
     } finally {await fs.rm(temp,{recursive:true,force:true}).catch(()=>fail("cleanup_failed","cleanup"));}
 }
 export type DiffOutcome={path:string;sourcePath:string|null;kind:string;status:"compared";comparison:Comparison}|{path:string;sourcePath:string|null;kind:string;status:"skipped-directory"}|{path:string;sourcePath:string|null;kind:string;status:"unavailable";error:{code:string;stage:string;message:string}};
-export function diffError(e:unknown){const r=e as {code?:unknown;stage?:unknown};const codes=new Set(["invalid_request","invalid_selector","workspace_unavailable","outside_workspace","base_unavailable","base_changed","malformed_output","command_failed","aborted","cleanup_failed","materialization_failed","materialization_limit","invalid_utf8","capture_incomplete","output_overflow","missing_file","unsupported_file","file_limit","file_changed","read_failed"]);return {code:typeof r?.code==="string"&&codes.has(r.code)?r.code:"comparison_failed",stage:typeof r?.stage==="string"&&["input","selection","status","base","left","right","comparison","cleanup","producer"].includes(r.stage)?r.stage:"comparison",message:"The requested diff could not be verified."};}
+export function diffError(e:unknown){const r=e as {code?:unknown;stage?:unknown};const codes=new Set(["invalid_request","invalid_selector","workspace_unavailable","outside_workspace","base_unavailable","base_changed","malformed_output","command_failed","aborted","cleanup_failed","materialization_failed","materialization_limit","invalid_utf8","capture_incomplete","output_overflow","missing_file","unsupported_file","file_limit","file_changed","read_failed"]);return {code:typeof r?.code==="string"&&codes.has(r.code)?r.code:"comparison_failed",stage:typeof r?.stage==="string"&&["input","selection","status","base","left","right","comparison","cleanup","producer"].includes(r.stage)?r.stage:"comparison",message:e instanceof ConsolidatedDiffError&&e.reason?baseMessages[e.reason]:r?.code==="materialization_limit"?"Historical file exceeds the 4 MiB materialization limit. maxChars controls output only; no empty baseline was substituted.":"The requested diff could not be verified."};}
 export async function assembleConsolidatedDiff(input:unknown){
     validateDiffRequest(input);const args=input;aborted();
     const header={schemaVersion:1 as const,action:"diff" as const,mode:args.mode,provenance:{source:"plastic" as const,producer:"@aefree/pi-plastic" as const,contentTrust:"external" as const}};

package/src/operations/patch-receipt.ts

@@ -39,7 +39,7 @@ export function patchFailure(d: PatchData, code: Extract<PatchReceipt,{ok:false}
     return {...header(d),ok:false,outcome:["started","unknown"].includes(d.attempt.state)&&!d.artifact?"uncertain":"failed",error:{code,message}};
 }
 export async function assemblePatchReceipt(args: unknown): Promise<PatchReceipt> {
-    const d=emptyPatchData();let stage: string|null=null;let entered=false;let failure: {code:Extract<PatchReceipt,{ok:false}>["error"]["code"];message:string}|null=null;
+    const d=emptyPatchData();let stage: string|null=null;let setupStage:"backend"|"selector"|"output"="backend";let entered=false;let failure: {code:Extract<PatchReceipt,{ok:false}>["error"]["code"];message:string}|null=null;
     try {
         if (!args||typeof args!=="object"||Array.isArray(args)||Object.keys(args).some(k=>!["source","destination","output","toolPath","clean","integration","workdir","preflight","format"].includes(k)))
             return patchFailure(d,"invalid_request","Use declared bounded patch controls only.");
@@ -49,11 +49,13 @@ export async function assemblePatchReceipt(args: unknown): Promise<PatchReceipt>
         d.requested=r;d.publication=r.output===null?"not-requested":"not-published";
         const toolPath=resolvePatchToolPath(r.toolPath??undefined);
         if (!validPatchText(toolPath)) throw new Error("Invalid patch backend.");
+        setupStage="selector";
         const branch=await resolvePatchBranchSpecs({source:r.source,...(r.destination===null?{}:{destination:r.destination})},r.workdir);
         const v={source:branch.source,destination:branch.destination??null,toolPath,output:r.output===null?null:isAbsolute(r.output)?r.output:resolve(r.workdir,r.output)};
         if ([v.source,v.destination,v.toolPath,v.output].some(s=>s!==null&&(s.length>8192||/[\u0000-\u001f\u007f-\u009f]/.test(s)))) throw new Error("Resolved patch controls exceed limits.");
         d.resolved=v;d.intendedArgv=patchReceiptArgv(r,v);
         if (r.preflight) return {...header(d),ok:true,outcome:"preflight"};
+        setupStage="output";
         if (v.output!==null) await ensurePatchOutputDoesNotExist(v.output);
         stage=await fs.mkdtemp(join(v.output===null?tmpdir():resolve(v.output,".."),".pi-plastic-patch-"));
         const staged=join(stage,"patch-output");
@@ -77,7 +79,12 @@ export async function assemblePatchReceipt(args: unknown): Promise<PatchReceipt>
         }
     } catch {
         if (entered&&d.capture===null) {d.attempt={...emptyWorkspaceMergeAttempt(),state:"unknown"};d.effect="unverified";}
-        failure={code:entered?"producer_failed":"setup_failed",message:entered?"Patch observation failed; earlier observed effects remain recorded, no automatic retry.":"Patch setup unavailable. Verify exact selector repository, backend and new output parent; no command was dispatched."};
+        const setupMessages={
+            backend:"Patch backend unavailable. Set PI_PLASTIC_PATCH_EXECUTABLE to a verified non-GUI GNU-compatible executable, or pass toolPath. No command was dispatched.",
+            selector:"Patch selector repository could not be verified. Use an exact qualified br:/branch@repository@server selector. No command was dispatched.",
+            output:"Patch output is unavailable or already exists. Use a new filename in an existing writable parent directory. No command was dispatched.",
+        };
+        failure={code:entered?"producer_failed":"setup_failed",message:entered?"Patch observation failed; earlier observed effects remain recorded, no automatic retry.":setupMessages[setupStage]};
     } finally {
         if (stage!==null) {
             if (entered&&(d.attempt.state==="unknown"||d.attempt.state==="started")&&(d.attempt.terminal!=="observed"||d.attempt.aborted||d.attempt.timedOut)) {d.cleanup="retained";d.retainedStagingDirectory=stage;}