@aefree/pi-plastic 0.7.6 → 0.8.0

package/src/pi/status-output.ts

@@ -0,0 +1,149 @@
+import { Type, type Static, type TSchema } from "typebox";
+import { Check } from "typebox/value";
+import { assembleStatusObservation, presentStatusObservation, type StatusObservationOptions, type StatusObservation, StatusOptionError, StatusXmlError } from "../operations/status";
+import { StatusCommandError } from "../execution/status-command";
+
+export const STATUS_OUTPUT_MAX_BYTES = 131072;
+const object = <T extends Record<string, TSchema>>(fields: T) => Type.Object(fields, { additionalProperties: false });
+const count = Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });
+const baseSummary = { totalPending: count, added: count, changed: count, moved: count, deleted: count, other: count };
+const completeness = object({
+    read: Type.Union([Type.Literal("complete"), Type.Literal("incomplete"), Type.Literal("unknown")]),
+    capture: Type.Union([Type.Literal("complete"), Type.Literal("unknown")]),
+    projection: Type.Boolean(),
+});
+const common = {
+    schemaVersion: Type.Literal(1), action: Type.Literal("status"),
+    provenance: object({ source: Type.Literal("plastic"), producer: Type.Literal("@aefree/pi-plastic"), contentTrust: Type.Literal("external") }),
+    completeness,
+};
+// Reject pre-decoding Windows substitution as well as UTF-8 replacement loss.
+const statusPathPattern = process.platform === "win32" ? "^[^\\uFFFD?]*$" : "^[^\\uFFFD]*$";
+const item = object({
+    statusCode: Type.String({ minLength: 1, maxLength: 64 }),
+    kind: Type.Union([Type.Literal("added"), Type.Literal("changed"), Type.Literal("moved"), Type.Literal("deleted"), Type.Literal("private"), Type.Literal("other")]),
+    path: Type.String({ minLength: 1, maxLength: 4096, pattern: statusPathPattern }), isDirectory: Type.Boolean(),
+    revisionId: Type.Optional(Type.String({ minLength: 1, maxLength: 128, pattern: "^[0-9]+$" })),
+    sourcePath: Type.Optional(Type.String({ minLength: 1, maxLength: 4096, pattern: statusPathPattern })),
+});
+const xmlCount = Type.Integer({ minimum: 0, maximum: 20000 });
+const xmlSummary = { totalPending: xmlCount, added: xmlCount, changed: xmlCount, moved: xmlCount, deleted: xmlCount, other: Type.Literal(0), private: xmlCount, tracked: xmlCount };
+const xmlPathPattern = `^(?:/|[A-Za-z]:\\\\|\\\\\\\\)[^\\u0000-\\u001f${process.platform === "win32" ? "?" : ""}]*$`;
+const xmlItem = object({
+    statusCode: Type.Union([Type.Literal("CH"), Type.Literal("AD"), Type.Literal("DE"), Type.Literal("LD"), Type.Literal("MV"), Type.Literal("PR")]),
+    kind: Type.Union([Type.Literal("added"), Type.Literal("changed"), Type.Literal("moved"), Type.Literal("deleted"), Type.Literal("private")]),
+    path: Type.String({ minLength: 1, maxLength: 4096, pattern: xmlPathPattern }), isDirectory: Type.Boolean(),
+    sourcePath: Type.Optional(Type.String({ minLength: 1, maxLength: 4096, pattern: xmlPathPattern })),
+});
+export const statusOutputSchema = Type.Union([
+    object({ ...common, schemaVersion: Type.Literal(2), ok: Type.Literal(true), data: object({
+        mode: Type.Literal("xml"), requestedShort: Type.Literal(false), summaryBasis: Type.Literal("parsed_records"),
+        source: object({ transport: Type.Literal("status_xml"), encoding: Type.Literal("utf-8"), pathBasis: Type.Literal("absolute"), scope: Type.Literal("workspace"), baseRevisionAvailability: Type.Literal("unavailable") }),
+        items: Type.Array(xmlItem, { maxItems: 500 }),
+        itemCount: object({ parsed: xmlCount, returned: Type.Integer({ minimum: 0, maximum: 500 }), omitted: xmlCount, excluded: Type.Literal(0), overCap: xmlCount }),
+        summary: object(xmlSummary),
+        parse: object({ records: xmlCount, unsupportedRecords: Type.Literal(0), malformedRecords: Type.Literal(0) }),
+    }) }),
+    object({ ...common, schemaVersion: Type.Literal(2), ok: Type.Literal(false), error: object({
+        code: Type.Union([Type.Literal("command_failed"), Type.Literal("aborted"), Type.Literal("capture_incomplete"), Type.Literal("invalid_producer_data"), Type.Literal("output_overflow"), Type.Literal("unsupported_source"), Type.Literal("malformed_output")]),
+        message: Type.String({ maxLength: 256 }),
+    }) }),
+    object({ ...common, ok: Type.Literal(true), data: object({
+        mode: Type.Literal("machine"), requestedShort: Type.Boolean(),
+        summaryBasis: Type.Literal("parsed_records"),
+        items: Type.Array(item, { maxItems: 500 }),
+        itemCount: object({ parsed: count, returned: count, omitted: count, excluded: count, overCap: count }),
+        summary: object({ ...baseSummary, private: count, tracked: count }),
+        parse: object({ valid: count, blank: count, header: count, unsupported: count, malformed: count, ambiguousLegacyMove: count }),
+    }) }),
+    object({ ...common, ok: Type.Literal(true), data: object({
+        mode: Type.Literal("standard"), requestedShort: Type.Boolean(),
+        summaryBasis: Type.Literal("short_output_classification"), summary: object(baseSummary),
+        mergeHints: object({ basis: Type.Literal("text_hints"), hasPendingMergeLinks: Type.Boolean(), hasMergeInProgress: Type.Boolean(), pendingMergeLinkCount: count, mergeInProgressHintCount: count }),
+    }) }),
+    object({ ...common, ok: Type.Literal(false), error: object({
+        code: Type.Union([Type.Literal("command_failed"), Type.Literal("aborted"), Type.Literal("capture_incomplete"), Type.Literal("invalid_producer_data"), Type.Literal("output_overflow")]),
+        message: Type.String({ maxLength: 256 }),
+    }) }),
+]);
+export type StatusOutput = Static<typeof statusOutputSchema>;
+const provenance = { source: "plastic", producer: "@aefree/pi-plastic", contentTrust: "external" } as const;
+const envelope = { schemaVersion: 1, action: "status", provenance } as const;
+type StatusErrorCode = Extract<StatusOutput, { ok: false; schemaVersion: 1 }>["error"]["code"];
+const errorOutput = (code: StatusErrorCode, message: string, schemaVersion: 1 | 2 = 1): StatusOutput => ({ ...envelope, schemaVersion, ok: false, completeness: { read: "incomplete", capture: "unknown", projection: false }, error: { code, message } });
+
+export function validateStatusOutput(value: unknown, schemaVersion: 1 | 2 = 1): StatusOutput {
+    if (!Check(statusOutputSchema, value)) return errorOutput("invalid_producer_data", "Status producer data did not match the output contract.", schemaVersion);
+    const checked = value as StatusOutput;
+    if (checked.ok && checked.data.mode === "xml") {
+        const data = checked.data;
+        const { parsed, returned, omitted, excluded, overCap } = data.itemCount;
+        const seen = new Set<string>();
+        const kinds = { CH: "changed", AD: "added", DE: "deleted", LD: "deleted", MV: "moved", PR: "private" };
+        const invalidRows = data.items.some(row => {
+            const unsafe = (path: string) => /[\uFFFE\uFFFF]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(path);
+            const invalid = unsafe(row.path) || (row.sourcePath !== undefined && unsafe(row.sourcePath)) || row.kind !== kinds[row.statusCode] || (row.kind === "moved") !== Boolean(row.sourcePath) || row.sourcePath === row.path || seen.has(row.path);
+            seen.add(row.path); return invalid;
+        });
+        if (data.summary.added + data.summary.changed + data.summary.deleted + data.summary.moved + data.summary.private + data.summary.other !== parsed || data.summary.other !== 0 || data.summary.tracked !== parsed - data.summary.private || invalidRows || returned !== data.items.length || parsed !== data.parse.records || parsed !== data.summary.totalPending || omitted !== parsed - returned || excluded !== 0 || overCap !== omitted || checked.completeness.read !== "complete" || checked.completeness.capture !== "complete" || checked.completeness.projection !== (returned === parsed)) return errorOutput("invalid_producer_data", "Status producer data did not match the output contract.", 2);
+    }
+    if (Buffer.byteLength(JSON.stringify(value), "utf8") > STATUS_OUTPUT_MAX_BYTES) return errorOutput("output_overflow", "Status output exceeded the compact UTF-8 byte limit.", schemaVersion);
+    return value as StatusOutput;
+}
+
+export function projectStatusOutput(observation: StatusObservation, maxItems = 100): StatusOutput {
+    if (observation.kind === "xml") {
+        const items = observation.items.slice(0, maxItems);
+        const parsed = observation.items.length;
+        const summary = observation.summary;
+        return validateStatusOutput({ ...envelope, schemaVersion: 2, ok: true,
+            completeness: { read: "complete", capture: "complete", projection: items.length === parsed },
+            data: { mode: "xml", requestedShort: false, summaryBasis: "parsed_records",
+                source: { transport: "status_xml", encoding: "utf-8", pathBasis: "absolute", scope: "workspace", baseRevisionAvailability: "unavailable" },
+                items, itemCount: { parsed, returned: items.length, omitted: parsed - items.length, excluded: 0, overCap: parsed - items.length }, summary,
+                parse: { records: parsed, unsupportedRecords: 0, malformedRecords: 0 } },
+        }, 2);
+    }
+    if (observation.kind === "machine") {
+        const { diagnostics: parse, pendingItems } = observation;
+        const eligible = pendingItems.map(row => ({
+            statusCode: row.statusCode, kind: row.kind, path: row.workspacePath, isDirectory: row.isDirectory,
+            ...(row.revisionId !== undefined ? { revisionId: row.revisionId } : {}),
+            ...(row.sourceWorkspacePath !== undefined ? { sourcePath: row.sourceWorkspacePath } : {}),
+        })).filter(row => Check(item, row));
+        const items = eligible.slice(0, maxItems);
+        const excluded = pendingItems.length - eligible.length;
+        const summary = { totalPending: pendingItems.length, added: 0, changed: 0, moved: 0, deleted: 0, private: 0, other: 0, tracked: 0 };
+        for (const row of pendingItems) summary[row.kind]++;
+        summary.tracked = summary.totalPending - summary.private;
+        const parseComplete = parse.unsupported + parse.malformed + parse.ambiguousLegacyMove === 0;
+        return validateStatusOutput({ ...envelope, ok: true,
+            completeness: { read: !parseComplete ? "incomplete" : observation.capture === "complete" ? "complete" : "unknown", capture: observation.capture, projection: items.length === pendingItems.length },
+            data: { mode: "machine", requestedShort: observation.requestedShort, summaryBasis: "parsed_records", items, itemCount: { parsed: pendingItems.length, returned: items.length, omitted: pendingItems.length - items.length, excluded, overCap: eligible.length - items.length }, summary, parse },
+        });
+    }
+    return validateStatusOutput({ ...envelope, ok: true,
+        completeness: { read: "unknown", capture: observation.capture, projection: true },
+        data: { mode: "standard", requestedShort: observation.usedShortFlag, summaryBasis: "short_output_classification", summary: observation.summary,
+            mergeHints: { basis: "text_hints", hasPendingMergeLinks: observation.mergeState.hasPendingMergeLinks, hasMergeInProgress: observation.mergeState.hasMergeInProgress, pendingMergeLinkCount: observation.mergeState.pendingMergeLinks.length, mergeInProgressHintCount: observation.mergeState.mergeInProgressHints.length },
+        },
+    });
+}
+
+export async function executeStatusOutput(args: StatusObservationOptions & { format?: "text" | "json"; maxItems?: number; includeRaw?: boolean }) {
+    let dto: StatusOutput;
+    let rawResult: string | undefined;
+    try {
+        const observation = await assembleStatusObservation(args);
+        dto = projectStatusOutput(observation, args.maxItems);
+        if (dto.ok) rawResult = await presentStatusObservation(observation, args);
+    } catch (error) {
+        const version = args.source === "xml" ? 2 : 1;
+        dto = validateStatusOutput(error instanceof StatusXmlError ? ({ ...envelope, schemaVersion: 2, ok: false, completeness: { read: "incomplete", capture: "complete", projection: false }, error: { code: error.code, message: error.message } }) : error instanceof StatusCommandError ? errorOutput(error.code, error.message, version) : error instanceof StatusOptionError ? errorOutput("command_failed", error.message, version) : errorOutput("invalid_producer_data", "Status producer failed to produce valid data.", version), version);
+    }
+    return {
+        content: [{ type: "text" as const, text: dto.ok ? dto.data.mode !== "standard" ? `Status: ${dto.data.itemCount.parsed} parsed records; ${dto.data.itemCount.returned} returned. Read: ${dto.completeness.read}.` : `Status: ${dto.data.summary.totalPending} classified short-output lines. Read: unknown.` : dto.error.message }],
+        structuredContent: dto, isError: !dto.ok,
+        details: { exportName: "status", rawResult, ...(args.workdir && (dto.ok || args.source !== "xml") ? { workdir: args.workdir } : {}) },
+    };
+}

package/src/pi/switch-output.ts

@@ -0,0 +1,80 @@
+import { Type, type TProperties } from "typebox";
+import { Check } from "typebox/value";
+import { assembleSwitchReceipt, presentSwitchReceipt, safeSwitchValue, parseSwitchTarget, compareSwitchTarget, type SwitchReceipt, type SwitchStep, type SwitchSummary, type SwitchBranchObservation } from "../operations/switch-receipt";
+const object = <P extends TProperties>(p:P) => Type.Object(p,{additionalProperties:false});
+const enumeration = <const V extends readonly string[]>(v:V) => Type.Unsafe<V[number]>({anyOf:v.map(value=>({type:"string",const:value}))});
+const str = (max=4096) => Type.String({maxLength:max,minLength:1});
+const uint = (max=Number.MAX_SAFE_INTEGER) => Type.Integer({minimum:0,maximum:max});
+const nullable = (s:ReturnType<typeof Type.Object>|ReturnType<typeof Type.String>) => Type.Union([s,Type.Null()]);
+const attempt = object({state:enumeration(["not-attempted","not-started","started","unknown"]),terminal:enumeration(["not-observed","observed"]),exitCode:Type.Union([uint(2147483647),Type.Null()]),aborted:Type.Boolean(),timedOut:Type.Boolean()});
+const capture = object({stdoutBytes:uint(),stderrBytes:uint(),stdoutRetainedBytes:uint(1048576),stderrRetainedBytes:uint(65536),truncated:Type.Boolean(),complete:Type.Boolean(),validUtf8:Type.Boolean()});
+const branch = object({branch:str(),repository:str(),server:str(),basis:Type.Literal("standard-status"),scope:Type.Literal("loaded-workspace")});
+const summary = object({totalPending:uint(19999),tracked:uint(19999),private:uint(19999),added:uint(19999),changed:uint(19999),moved:uint(19999),deleted:uint(19999),other:uint(19999)});
+const names=["branch-before","pending-before","shelve","pending-recovery","switch","branch-after"] as const;
+const step=object({name:enumeration(names),argv:Type.Array(str(8192),{minItems:1,maxItems:4}),attempt,capture,evidence:enumeration(["unadmitted","admitted","terminal-only","eligible-no-changes"]),effect:enumeration(["read-observed","not-attempted","command-completed","uncertain"]),branch:nullable(branch),summary:nullable(summary),records:uint(20001)});
+const mutations=Type.Array(enumeration(["shelve","switch"]),{maxItems:2});
+const data=object({requestedTarget:nullable(str()),workdir:nullable(str()),pendingPolicy:enumeration(["shelve","bring","cancel"]),defaultedPolicy:Type.Boolean(),preflight:Type.Boolean(),strategy:enumeration(["unresolved","already-on-target-branch","silent-noinput","direct-switch-private-only","blocked-bring-tracked-pending","cancel-with-pending","shelve-then-switch-noinput"]),wouldRun:Type.Boolean(),plannedMutations:mutations,unattemptedMutations:mutations,steps:Type.Array(step,{maxItems:6}),branchBefore:nullable(branch),branchAfter:nullable(branch),pendingBefore:nullable(summary),pendingRecovery:nullable(summary),observedShelveset:Type.Null(),usedNoChangesShelveRecovery:Type.Boolean(),targetVerification:enumeration(["unverified","name-only","exact-qualifier-spelling"]),serverAliasEquivalence:Type.Literal("unverified"),filePreservation:Type.Literal("unverified"),xlinkEffects:Type.Literal("unverified"),effect:enumeration(["not-attempted","command-completed","uncertain"])});
+const base={schemaVersion:Type.Literal(1),action:Type.Literal("switch-branch"),provenance:object({source:Type.Literal("plastic"),producer:Type.Literal("@aefree/pi-plastic"),contentTrust:Type.Literal("external")}),sourceAdmission:Type.Literal("windows-cm11.0.16.10371-observed"),completeness:object({read:enumeration(["complete","incomplete","unknown"]),capture:enumeration(["complete","incomplete","unknown"]),projection:Type.Literal(true)}),data};
+const error=object({code:enumeration(["invalid_request","unsupported_source","observation_failed","policy_canceled","policy_blocked","mutation_failed","target_unverified","producer_failed"]),stage:enumeration(["input",...names,"policy","producer"]),message:str(256)});
+export const switchOutputSchema=Type.Unsafe<SwitchReceipt>(Type.Union([object({...base,ok:Type.Literal(true),outcome:enumeration(["preflight","already-loaded","switched"])}),object({...base,ok:Type.Literal(false),outcome:enumeration(["canceled","blocked","failed","uncertain","command-completed-unverified"]),error})]));
+const same=(a:unknown,b:unknown)=>JSON.stringify(a)===JSON.stringify(b);
+const validSummary=(s:SwitchSummary)=>s.totalPending===s.tracked+s.private&&s.totalPending===s.added+s.changed+s.moved+s.deleted+s.other+s.private;
+const validBranch=(b:SwitchBranchObservation)=>safeSwitchValue(`${b.branch}@${b.repository}@${b.server}`)&&!!parseSwitchTarget(`${b.branch}@${b.repository}@${b.server}`);
+const normal=(s:SwitchStep)=>s.capture.complete&&s.attempt.state==="started"&&s.attempt.terminal==="observed"&&!s.attempt.aborted&&!s.attempt.timedOut;
+export function validateSwitchOutput(value:unknown):value is SwitchReceipt {
+    if(!Check(switchOutputSchema,value)||Buffer.byteLength(JSON.stringify(value),"utf8")>131072)return false;
+    const dto=value as SwitchReceipt,d=dto.data;
+    if(!dto.ok&&!safeSwitchValue(dto.error.message))return false;
+    if(d.requestedTarget!==null&&!parseSwitchTarget(d.requestedTarget)||d.workdir!==null&&!safeSwitchValue(d.workdir))return false;
+    if(d.steps.length&&(!d.requestedTarget||!d.workdir)||d.defaultedPolicy&&d.pendingPolicy!=="cancel")return false;
+    let prior=-1;
+    for(const s of d.steps){
+        const i=names.indexOf(s.name);if(i<=prior)return false;prior=i;
+        const mut=s.name==="shelve"||s.name==="switch",pending=s.name==="pending-before"||s.name==="pending-recovery",a=s.attempt,c=s.capture;
+        const expected=s.name==="shelve"?["shelveset","create","--all",`-c=Auto-shelve before switch to ${d.requestedTarget}`]:s.name==="switch"?["switch","--silent","--noinput",d.requestedTarget]:pending?["status","--machinereadable","--includeRevId","--fieldseparator=\x1f"]:["status"];
+        if(!same(s.argv,expected)||c.stdoutRetainedBytes>(pending?1048576:65536)||c.stderrRetainedBytes>(pending?65536:16384)||c.stdoutRetainedBytes>c.stdoutBytes||c.stderrRetainedBytes>c.stderrBytes)return false;
+        if(a.exitCode!==null&&(a.terminal!=="observed"||a.state!=="started"&&a.state!=="unknown")||a.state==="not-attempted"&&(a.terminal!=="not-observed"||a.timedOut)||a.state==="not-started"&&a.exitCode!==null)return false;
+        if(c.complete&&(!c.validUtf8||c.truncated||c.stdoutRetainedBytes!==c.stdoutBytes||c.stderrRetainedBytes!==c.stderrBytes||a.state!=="started"||a.terminal!=="observed"||a.exitCode===null||a.aborted||a.timedOut))return false;
+        if(s.branch&&!validBranch(s.branch)||s.summary&&!validSummary(s.summary))return false;
+        if(s.evidence==="admitted") { if(mut||!normal(s)||a.exitCode!==0||c.stderrBytes||s.effect!=="read-observed"||(pending?!s.summary||!!s.branch||s.records!==s.summary.totalPending+1:!s.branch||!!s.summary||s.records!==1))return false; }
+        else if(s.branch||s.summary||s.effect==="read-observed")return false;
+        if(mut){
+            if(s.records||!d.plannedMutations.includes(s.name as "shelve"|"switch"))return false;
+            const completed=normal(s)&&a.exitCode===0&&!c.stderrBytes;
+            if(s.effect!== (completed?"command-completed":["not-attempted","not-started"].includes(a.state)?"not-attempted":"uncertain"))return false;
+            if(s.evidence==="terminal-only"&&!completed||completed&&s.evidence!=="terminal-only")return false;
+            if(s.evidence==="eligible-no-changes"&&(s.name!=="shelve"||!normal(s)||a.exitCode!==1||c.stdoutBytes!==0||c.stderrBytes===0))return false;
+        }else if(!["admitted","unadmitted"].includes(s.evidence)||s.evidence==="unadmitted"&&s.effect!=="not-attempted")return false;
+    }
+    if(d.steps.length&&d.steps[0].name!=="branch-before"||d.steps.length>1&&(d.steps[0].evidence!=="admitted"||d.steps[1].name!=="pending-before"))return false;
+    const find=(name:SwitchStep["name"])=>d.steps.find(s=>s.name===name);
+    if(!same(d.branchBefore,find("branch-before")?.branch??null)||!same(d.branchAfter,find("branch-after")?.branch??null)||!same(d.pendingBefore,find("pending-before")?.summary??null)||!same(d.pendingRecovery,find("pending-recovery")?.summary??null))return false;
+    if(find("branch-after")&&!find("switch")||find("branch-after")&&find("switch")?.effect!=="command-completed")return false;
+    if(find("shelve")&&d.strategy!=="shelve-then-switch-noinput"||find("pending-recovery")&&find("shelve")?.evidence!=="eligible-no-changes")return false;
+    if(find("switch")&&find("shelve")&&find("shelve")?.effect!=="command-completed"&&(!d.usedNoChangesShelveRecovery||!d.pendingRecovery||d.pendingRecovery.tracked!==0))return false;
+    if(d.usedNoChangesShelveRecovery!==!!(find("pending-recovery")?.evidence==="admitted"&&d.pendingRecovery?.tracked===0))return false;
+    const ms=d.steps.filter(s=>s.name==="shelve"||s.name==="switch");
+    const effect=ms.some(s=>s.effect==="uncertain")?"uncertain":ms.some(s=>s.effect==="command-completed")?"command-completed":"not-attempted";
+    if(d.effect!==effect||!same(d.unattemptedMutations,d.plannedMutations.filter(n=>!ms.some(s=>s.name===n&&s.attempt.state!=="not-attempted"))))return false;
+    if(d.wouldRun!==!!d.plannedMutations.length||!same(d.plannedMutations,d.strategy==="shelve-then-switch-noinput"?["shelve","switch"]:["silent-noinput","direct-switch-private-only"].includes(d.strategy)?["switch"]:[]))return false;
+    if(d.pendingBefore){
+        const p=d.pendingBefore,match=!!d.branchBefore&&compareSwitchTarget(d.branchBefore,d.requestedTarget!)!=="unverified";
+        const expected=match?"already-on-target-branch":!p.totalPending?"silent-noinput":p.private>0&&p.tracked===0&&(d.pendingPolicy!=="cancel"||d.defaultedPolicy)?"direct-switch-private-only":d.pendingPolicy==="bring"&&p.tracked>0?"blocked-bring-tracked-pending":d.pendingPolicy==="cancel"?"cancel-with-pending":"shelve-then-switch-noinput";
+        if(d.strategy!==expected)return false;
+    }else if(d.strategy!=="unresolved")return false;
+    const observation=d.strategy==="already-on-target-branch"?d.branchBefore:d.branchAfter;
+    if(d.targetVerification!==(observation&&d.requestedTarget?compareSwitchTarget(observation,d.requestedTarget):"unverified"))return false;
+    if(dto.outcome==="preflight"&&(!d.preflight||!d.pendingBefore||ms.length)||dto.outcome==="already-loaded"&&(d.preflight||d.strategy!=="already-on-target-branch"||ms.length||d.targetVerification==="unverified"))return false;
+    if(dto.outcome==="switched"&&(d.preflight||!d.branchAfter||find("switch")?.effect!=="command-completed"||d.targetVerification==="unverified"||d.usedNoChangesShelveRecovery||d.effect!=="command-completed"))return false;
+    if(dto.outcome==="canceled"&&(d.preflight||d.strategy!=="cancel-with-pending"||ms.length)||dto.outcome==="blocked"&&(d.preflight||d.strategy!=="blocked-bring-tracked-pending"||ms.length))return false;
+    if(dto.outcome==="command-completed-unverified"&&(find("switch")?.effect!=="command-completed"||d.targetVerification!=="unverified"))return false;
+    if(dto.ok&&dto.outcome!=="preflight"&&d.preflight)return false;
+    const reads=d.steps.filter(s=>s.name!=="shelve"&&s.name!=="switch");
+    if(dto.completeness.capture!==(d.steps.length?d.steps.every(s=>s.capture.complete)?"complete":"incomplete":"unknown")||dto.completeness.read!==(reads.length?reads.every(s=>s.evidence==="admitted")?"complete":"incomplete":"unknown"))return false;
+    return true;
+}
+export async function executeSwitchOutput(args:unknown){
+    const dto=await assembleSwitchReceipt(args);
+    if(!validateSwitchOutput(dto))throw Error("Bounded switch receipt could not be validated. Earlier effects may exist; do not retry automatically.");
+    return {content:[{type:"text" as const,text:presentSwitchReceipt(dto,(args as SwitchReceipt["data"] & {format?:string})?.format==="json"?"json":"text")}],details:{},structuredContent:dto,isError:!dto.ok};
+}

package/src/pi/tool-registry.ts

@@ -0,0 +1,72 @@
+import { status } from "../operations/status";
+import { update, add, undo, resolveDeleteChangeConflict, workspaceList } from "../operations/workspace";
+import { checkin } from "../operations/checkin";
+import { diff } from "../operations/diff";
+import { patch } from "../operations/patch";
+import { branchCreate, currentBranch, branchList, branchExists, branchDelete } from "../operations/branches";
+import { switchBranch } from "../operations/switch";
+import { merge, finalizeMerge } from "../operations/merge";
+import { mergeBranches } from "../operations/server-merge";
+import { mergeToBranch } from "../operations/closeout";
+import { shelvesetCreate, shelvesetApply, shelvesetDelete, shelvesetList } from "../operations/shelvesets";
+import { codeReviewCreate, codeReviewUpdate, codeReviewDelete, codeReviewFind } from "../operations/reviews";
+import { PLASTIC_TOOL_NAMES } from "../plastic-tool-loading";
+
+type CoreTool = {
+  description?: string;
+  args?: Record<string, unknown>;
+  execute: (args: Record<string, unknown>) => Promise<unknown> | unknown;
+};
+
+export const PLASTIC_TOOL_REGISTRY = {
+  status,
+  update,
+  add,
+  checkin,
+  undo,
+  resolveDeleteChangeConflict,
+  diff,
+  patch,
+  branchCreate,
+  switchBranch,
+  merge,
+  mergeBranches,
+  mergeToBranch,
+  finalizeMerge,
+  currentBranch,
+  branchList,
+  branchExists,
+  branchDelete,
+  shelvesetCreate,
+  shelvesetApply,
+  shelvesetDelete,
+  shelvesetList,
+  codeReviewCreate,
+  codeReviewUpdate,
+  codeReviewDelete,
+  codeReviewFind,
+  workspaceList,
+} as const;
+
+export type PlasticExportName = keyof typeof PLASTIC_TOOL_REGISTRY;
+
+export function toToolName(exportName: string): string {
+  return `plastic_${exportName}`;
+}
+
+/** Preserve registration order while verifying the loading vocabulary has no drift. */
+export function getRegisteredPlasticExportNames(): PlasticExportName[] {
+  const names = Object.keys(PLASTIC_TOOL_REGISTRY) as PlasticExportName[];
+  if (names.length !== PLASTIC_TOOL_NAMES.size || names.some((name) => !PLASTIC_TOOL_NAMES.has(toToolName(name)))) {
+    throw new Error("Plastic tool registry does not match the loading catalogue.");
+  }
+  return names;
+}
+
+export function getCoreTool(exportName: PlasticExportName): CoreTool {
+  const candidate = PLASTIC_TOOL_REGISTRY[exportName] as unknown as CoreTool;
+  if (!candidate || typeof candidate.execute !== "function") {
+    throw new Error(`Missing Plastic core tool export '${exportName}'.`);
+  }
+  return candidate;
+}

package/src/pi/undo-output.ts

@@ -0,0 +1,52 @@
+import { Type } from "typebox";
+import { Check } from "typebox/value";
+import { assembleUndoReceipt, emptyUndoData, undoFailure, presentUndoReceipt, safeUndoText, UNDO_COMMAND, validUndoOperands, type UndoReceipt } from "../operations/undo-receipt";
+const object = (p: Record<string, any>) => Type.Object(p, { additionalProperties: false });
+const enumeration = (values: readonly string[]) => Type.Union(values.map(value => Type.Literal(value)));
+const uint = (max = Number.MAX_SAFE_INTEGER) => Type.Integer({ minimum: 0, maximum: max });
+const attempt = object({ state: enumeration(["not-attempted", "not-started", "started", "unknown"]), terminal: enumeration(["not-observed", "observed"]), exitCode: Type.Union([uint(2147483647), Type.Null()]), aborted: Type.Boolean(), timedOut: Type.Boolean() });
+const capture = object({ stdoutBytes: uint(), stderrBytes: uint(), stdoutRetainedBytes: uint(65536), stderrRetainedBytes: uint(16384), truncated: Type.Boolean(), complete: Type.Boolean(), validUtf8: Type.Boolean() });
+const data = { intendedArgv: Type.Array(Type.String({ minLength: 1, maxLength: 4096 }), { minItems: 1, maxItems: 257 }), requestedOperandCount: Type.Union([uint(256), Type.Null()]), workingDirectory: Type.Union([Type.String({ minLength: 1, maxLength: 4096 }), Type.Null()]), attempt, capture: Type.Union([capture, Type.Null()]), observedWorkspaceIdentity: Type.Null(), observedUndoneItems: Type.Null(), verification: Type.Literal("unverified") };
+const header = { schemaVersion: Type.Literal(1), action: Type.Literal("undo"), provenance: object({ source: Type.Literal("plastic"), producer: Type.Literal("@aefree/pi-plastic"), contentTrust: Type.Literal("external") }), completeness: object({ capture: enumeration(["complete", "incomplete", "unknown"]), projection: Type.Literal(true) }) };
+const error = object({ code: enumeration(["invalid_request", "launch_failed", "aborted", "uncertain", "producer_failed"]), message: Type.String({ minLength: 1, maxLength: 256 }) });
+export const undoOutputSchema = Type.Unsafe<UndoReceipt>(Type.Union([
+    object({ ...header, ok: Type.Literal(true), outcome: Type.Literal("command-completed"), data: object({ ...data, effect: Type.Literal("not-proven") }) }),
+    object({ ...header, ok: Type.Literal(false), outcome: Type.Literal("failed"), data: object({ ...data, effect: Type.Literal("not-attempted") }), error }),
+    object({ ...header, ok: Type.Literal(false), outcome: Type.Literal("uncertain"), data: object({ ...data, effect: Type.Literal("uncertain") }), error }),
+]));
+export function validateUndoOutput(value: unknown): value is UndoReceipt {
+    if (!Check(undoOutputSchema, value) || Buffer.byteLength(JSON.stringify(value), "utf8") > 131072) return false;
+    const dto = value as UndoReceipt, d = dto.data, a = d.attempt, c = d.capture;
+    if (d.intendedArgv[0] !== UNDO_COMMAND) return false;
+    if (d.requestedOperandCount === null) {
+        if (d.intendedArgv.length !== 1 || d.workingDirectory !== null || c || !["not-attempted", "unknown"].includes(a.state)) return false;
+    } else if (!validUndoOperands(d.intendedArgv.slice(1)) || d.requestedOperandCount !== d.intendedArgv.length - 1 || !d.workingDirectory) return false;
+    if (d.workingDirectory !== null && !safeUndoText(d.workingDirectory)) return false;
+    if (!dto.ok && !safeUndoText(dto.error.message)) return false;
+    if (a.exitCode !== null && a.terminal !== "observed" || a.state === "not-attempted" && (a.terminal !== "not-observed" || a.exitCode !== null || a.timedOut) || a.state === "not-started" && (a.terminal !== "not-observed" || a.exitCode !== null)) return false;
+    if (c) {
+        if (!d.workingDirectory || c.stdoutRetainedBytes > c.stdoutBytes || c.stderrRetainedBytes > c.stderrBytes) return false;
+        if (c.complete && (!c.validUtf8 || c.truncated || c.stdoutBytes !== c.stdoutRetainedBytes || c.stderrBytes !== c.stderrRetainedBytes || a.state !== "started" || a.terminal !== "observed" || a.exitCode === null || a.aborted || a.timedOut)) return false;
+        if (a.state === "not-attempted" && (!a.aborted || c.stdoutBytes || c.stderrBytes || c.validUtf8 || c.complete)) return false;
+    }
+    if (dto.completeness.capture !== (c ? c.complete ? "complete" : "incomplete" : "unknown")) return false;
+    if (dto.ok && (d.requestedOperandCount === null || !d.workingDirectory || !c?.complete || a.state !== "started" || a.terminal !== "observed" || a.exitCode !== 0 || a.aborted || a.timedOut)) return false;
+    if (!dto.ok && dto.outcome === "uncertain" && !["started", "unknown"].includes(a.state)) return false;
+    if (!dto.ok && dto.outcome === "failed" && !["not-attempted", "not-started"].includes(a.state)) return false;
+    if (!dto.ok && dto.error.code === "invalid_request" && (d.workingDirectory !== null || c || a.state !== "not-attempted" || a.aborted)) return false;
+    if (!dto.ok && dto.error.code === "aborted" && !a.aborted) return false;
+    if (!dto.ok && dto.error.code === "launch_failed" && !["not-attempted", "not-started"].includes(a.state)) return false;
+    return true;
+}
+export async function executeUndoOutput(args: unknown) {
+    let dto = await assembleUndoReceipt(args);
+    const valid: boolean = validateUndoOutput(dto);
+    if (!valid) {
+        const possibleStart = !["not-attempted", "not-started"].includes(dto.data.attempt.state);
+        const data = emptyUndoData();
+        if (possibleStart) { data.attempt.state = "unknown"; data.effect = "uncertain"; }
+        dto = undoFailure(data, "producer_failed", "Undo receipt validation failed; do not retry automatically.");
+        if (!validateUndoOutput(dto)) throw new Error("Safe undo receipt could not be constructed.");
+    }
+    return { content: [{ type: "text" as const, text: presentUndoReceipt(dto) }], details: {}, structuredContent: dto, isError: !dto.ok };
+}

package/src/pi/update-output.ts

@@ -0,0 +1,48 @@
+import { Type } from "typebox";
+import { Check } from "typebox/value";
+import { assembleUpdateReceipt, emptyUpdateData, updateFailure, presentUpdateReceipt, safeUpdateText, UPDATE_ARGV, type UpdateReceipt } from "../operations/update-receipt";
+const object = (p: Record<string, any>) => Type.Object(p, { additionalProperties: false });
+const enumeration = (values: readonly string[]) => Type.Union(values.map(value => Type.Literal(value)));
+const uint = (max = Number.MAX_SAFE_INTEGER) => Type.Integer({ minimum: 0, maximum: max });
+const attempt = object({ state: enumeration(["not-attempted", "not-started", "started", "unknown"]), terminal: enumeration(["not-observed", "observed"]), exitCode: Type.Union([uint(2147483647), Type.Null()]), aborted: Type.Boolean(), timedOut: Type.Boolean() });
+const capture = object({ stdoutBytes: uint(), stderrBytes: uint(), stdoutRetainedBytes: uint(65536), stderrRetainedBytes: uint(16384), truncated: Type.Boolean(), complete: Type.Boolean(), validUtf8: Type.Boolean() });
+const data = { intendedArgv: Type.Tuple(UPDATE_ARGV.map(value => Type.Literal(value))), workingDirectory: Type.Union([Type.String({ minLength: 1, maxLength: 4096 }), Type.Null()]), attempt, capture: Type.Union([capture, Type.Null()]), observedWorkspaceIdentity: Type.Null(), observedChanges: Type.Null(), verification: Type.Literal("unverified") };
+const header = { schemaVersion: Type.Literal(1), action: Type.Literal("update"), provenance: object({ source: Type.Literal("plastic"), producer: Type.Literal("@aefree/pi-plastic"), contentTrust: Type.Literal("external") }), completeness: object({ capture: enumeration(["complete", "incomplete", "unknown"]), projection: Type.Literal(true) }) };
+const error = object({ code: enumeration(["invalid_request", "launch_failed", "aborted", "uncertain", "producer_failed"]), message: Type.String({ minLength: 1, maxLength: 256 }) });
+export const updateOutputSchema = Type.Unsafe<UpdateReceipt>(Type.Union([
+    object({ ...header, ok: Type.Literal(true), outcome: Type.Literal("command-completed"), data: object({ ...data, effect: Type.Literal("not-proven") }) }),
+    object({ ...header, ok: Type.Literal(false), outcome: Type.Literal("failed"), data: object({ ...data, effect: Type.Literal("not-attempted") }), error }),
+    object({ ...header, ok: Type.Literal(false), outcome: Type.Literal("uncertain"), data: object({ ...data, effect: Type.Literal("uncertain") }), error }),
+]));
+export function validateUpdateOutput(value: unknown): value is UpdateReceipt {
+    if (!Check(updateOutputSchema, value) || Buffer.byteLength(JSON.stringify(value), "utf8") > 131072) return false;
+    const dto = value as UpdateReceipt, d = dto.data, a = d.attempt, c = d.capture;
+    if (d.workingDirectory !== null && !safeUpdateText(d.workingDirectory)) return false;
+    if (!dto.ok && !safeUpdateText(dto.error.message)) return false;
+    if (a.exitCode !== null && a.terminal !== "observed" || a.state === "not-attempted" && (a.terminal !== "not-observed" || a.exitCode !== null || a.timedOut) || a.state === "not-started" && (a.terminal !== "not-observed" || a.exitCode !== null)) return false;
+    if (c) {
+        if (!d.workingDirectory || c.stdoutRetainedBytes > c.stdoutBytes || c.stderrRetainedBytes > c.stderrBytes) return false;
+        if (c.complete && (!c.validUtf8 || c.truncated || c.stdoutBytes !== c.stdoutRetainedBytes || c.stderrBytes !== c.stderrRetainedBytes || a.state !== "started" || a.terminal !== "observed" || a.exitCode === null || a.aborted || a.timedOut)) return false;
+        if (a.state === "not-attempted" && (!a.aborted || c.stdoutBytes || c.stderrBytes || c.validUtf8 || c.complete)) return false;
+    }
+    if (dto.completeness.capture !== (c ? c.complete ? "complete" : "incomplete" : "unknown")) return false;
+    if (dto.ok && (!d.workingDirectory || !c?.complete || a.state !== "started" || a.terminal !== "observed" || a.exitCode !== 0 || a.aborted || a.timedOut)) return false;
+    if (!dto.ok && dto.outcome === "uncertain" && !["started", "unknown"].includes(a.state)) return false;
+    if (!dto.ok && dto.outcome === "failed" && !["not-attempted", "not-started"].includes(a.state)) return false;
+    if (!dto.ok && dto.error.code === "invalid_request" && (d.workingDirectory !== null || c || a.state !== "not-attempted" || a.aborted)) return false;
+    if (!dto.ok && dto.error.code === "aborted" && !a.aborted) return false;
+    if (!dto.ok && dto.error.code === "launch_failed" && !["not-attempted", "not-started"].includes(a.state)) return false;
+    return true;
+}
+export async function executeUpdateOutput(args: unknown) {
+    let dto = await assembleUpdateReceipt(args);
+    const valid: boolean = validateUpdateOutput(dto);
+    if (!valid) {
+        const possibleStart = !["not-attempted", "not-started"].includes(dto.data.attempt.state);
+        const data = emptyUpdateData();
+        if (possibleStart) { data.attempt.state = "unknown"; data.effect = "uncertain"; }
+        dto = updateFailure(data, "producer_failed", "Update receipt validation failed; do not retry automatically.");
+        if (!validateUpdateOutput(dto)) throw new Error("Safe update receipt could not be constructed.");
+    }
+    return { content: [{ type: "text" as const, text: presentUpdateReceipt(dto) }], details: {}, structuredContent: dto, isError: !dto.ok };
+}

package/src/pi/workspace-list-output.ts

@@ -0,0 +1,53 @@
+import { Type, type Static, type TSchema } from "typebox";
+import { Check } from "typebox/value";
+import { assembleWorkspaceListObservation, presentWorkspaceListObservation, workspaceListPayload, WorkspaceListError, validWorkspaceName, validWorkspacePath, validWorkspaceGuid, workspaceCapability, WORKSPACE_LIST_MAX_BYTES, type WorkspaceListArgs } from "../operations/workspace-list";
+import { WorkspaceListCommandError } from "../execution/workspace-list-command";
+import { getActiveAbortSignal } from "../execution/context";
+const object = <T extends Record<string, TSchema>>(fields: T) => Type.Object(fields, { additionalProperties: false });
+const integer = (maximum: number) => Type.Integer({ minimum: 0, maximum });
+const identity = Type.String({ minLength: 1, maxLength: 4096, pattern: "^[\\x20-\\x3e\\x40-\\x7e]+$" });
+const common = { schemaVersion: Type.Literal(1), action: Type.Literal("workspace-list"), provenance: object({ source: Type.Literal("plastic"), producer: Type.Literal("@aefree/pi-plastic"), contentTrust: Type.Literal("external") }) };
+const dataCommon = { scope: Type.Literal("local_client_inventory"), limits: object({ maxItems: Type.Integer({ minimum: 1, maximum: 500 }), identityCodeUnits: Type.Literal(4096), compactUtf8Bytes: Type.Literal(131072) }) };
+const capability = object({ identities: Type.Literal(workspaceCapability.identities), prerequisite: Type.Literal(workspaceCapability.prerequisite), originalVerification: Type.Literal(workspaceCapability.originalVerification), formatterLoss: Type.Literal(workspaceCapability.formatterLoss) });
+const errorCode = Type.Union([Type.Literal("command_failed"), Type.Literal("aborted"), Type.Literal("capture_incomplete"), Type.Literal("malformed_output"), Type.Literal("invalid_identity"), Type.Literal("unsupported_query"), Type.Literal("invalid_producer_data"), Type.Literal("output_overflow")]);
+export const workspaceListOutputSchema = Type.Union([
+    object({ ...common, ok: Type.Literal(true), completeness: object({ read: Type.Literal("complete_under_ascii_prerequisite"), capture: Type.Literal("complete"), projection: Type.Boolean() }), data: object({ ...dataCommon, mode: Type.Literal("fields"), basis: Type.Literal("workspace_list_tab_fields"), capability, pathBasis: Type.Literal("producer_absolute"), diagnostics: object({ duplicateRecords: integer(19999) }), rows: Type.Array(object({ name: identity, path: identity, guid: Type.String({ pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }) }), { maxItems: 500 }), countBasis: Type.Literal("observed_response_rows"), counts: object({ observed: integer(20000), returned: integer(500), omitted: integer(20000), excluded: Type.Literal(0) }) }) }),
+    object({ ...common, ok: Type.Literal(true), completeness: object({ read: Type.Literal("unknown"), capture: Type.Literal("unknown"), projection: Type.Literal(false) }), data: object({ ...dataCommon, mode: Type.Literal("native"), basis: Type.Literal("workspace_list_native"), capability: Type.Literal("noncanonical"), pathBasis: Type.Literal("unavailable"), rows: Type.Null(), counts: Type.Null(), countBasis: Type.Literal("unavailable") }) }),
+    object({ ...common, ok: Type.Literal(false), completeness: object({ read: Type.Literal("incomplete"), capture: Type.Literal("unknown"), projection: Type.Literal(false) }), error: object({ code: errorCode, message: Type.String({ minLength: 1, maxLength: 256 }) }) }),
+]);
+export type WorkspaceListOutput = Static<typeof workspaceListOutputSchema>;
+export type WorkspaceListErrorCode = Extract<WorkspaceListOutput, { ok: false }>["error"]["code"];
+const failure = (code: WorkspaceListErrorCode): WorkspaceListOutput => ({ schemaVersion: 1, action: "workspace-list", provenance: { source: "plastic", producer: "@aefree/pi-plastic", contentTrust: "external" }, ok: false, completeness: { read: "incomplete", capture: "unknown", projection: false }, error: { code, message: `Workspace list read failed (${code}); no reusable rows are available.` } });
+export function validateWorkspaceListOutput(value: unknown): WorkspaceListOutput {
+    if (!Check(workspaceListOutputSchema, value)) return failure("invalid_producer_data");
+    const dto = value as WorkspaceListOutput;
+    if (dto.ok && dto.data.mode === "fields") {
+        const { rows, counts, limits, diagnostics } = dto.data;
+        const guids = new Map<string, string>(), names = new Map<string, string>(), paths = new Map<string, string>();
+        let returnedDuplicates = 0, conflict = false;
+        for (const row of rows) {
+            const value = JSON.stringify(row);
+            const prior = [guids.get(row.guid.toLowerCase()), names.get(row.name), paths.get(row.path)].filter(value => value !== undefined);
+            if (prior.some(previous => previous !== value)) conflict = true;
+            if (prior.length) returnedDuplicates++;
+            guids.set(row.guid.toLowerCase(), value); names.set(row.name, value); paths.set(row.path, value);
+        }
+        if (rows.some(row => !validWorkspaceName(row.name) || !validWorkspacePath(row.path) || !validWorkspaceGuid(row.guid))
+            || conflict || diagnostics.duplicateRecords < returnedDuplicates || diagnostics.duplicateRecords > returnedDuplicates + counts.omitted || diagnostics.duplicateRecords > Math.max(0, counts.observed - 1)
+            || counts.returned !== rows.length || counts.observed !== counts.returned + counts.omitted || counts.returned !== Math.min(counts.observed, limits.maxItems) || dto.completeness.projection !== (counts.omitted === 0)) return failure("invalid_producer_data");
+    }
+    if (Buffer.byteLength(JSON.stringify(dto), "utf8") > WORKSPACE_LIST_MAX_BYTES) return failure("output_overflow");
+    return dto;
+}
+export async function executeWorkspaceListOutput(args: WorkspaceListArgs) {
+    let dto: WorkspaceListOutput, rawResult: string | undefined;
+    try {
+        const observation = await assembleWorkspaceListObservation(args, true);
+        if (getActiveAbortSignal()?.aborted) throw new WorkspaceListCommandError("aborted");
+        dto = validateWorkspaceListOutput(workspaceListPayload(observation));
+        if (dto.ok) rawResult = await presentWorkspaceListObservation(observation, args);
+        if (getActiveAbortSignal()?.aborted) throw new WorkspaceListCommandError("aborted");
+    } catch (error) { dto = failure(error instanceof WorkspaceListError || error instanceof WorkspaceListCommandError ? error.code : "invalid_producer_data"); }
+    dto = validateWorkspaceListOutput(dto);
+    return { content: [{ type: "text" as const, text: dto.ok ? rawResult! : dto.error.message }], structuredContent: dto, isError: !dto.ok, details: { exportName: "workspaceList", rawResult: dto.ok ? rawResult : undefined, ...(args.workdir ? { workdir: args.workdir } : {}) } };
+}

package/src/pi/workspace-merge-output.ts

@@ -0,0 +1,46 @@
+import { Type } from "typebox";
+import { Check } from "typebox/value";
+import { assembleWorkspaceMergeReceipt, emptyWorkspaceMergeData, workspaceMergeFailure, presentWorkspaceMergeReceipt, buildWorkspaceMergeArgv, safeMergeText, type MergeAction, type WorkspaceMergeReceipt } from "../operations/workspace-merge-receipt";
+const obj=(p:Record<string,any>)=>Type.Object(p,{additionalProperties:false}),enm=(v:string[])=>Type.Union(v.map(x=>Type.Literal(x))),nil=(s:any)=>Type.Union([s,Type.Null()]),uint=(max=Number.MAX_SAFE_INTEGER)=>Type.Integer({minimum:0,maximum:max});
+const attempt=obj({state:enm(["not-attempted","not-started","started","unknown"]),terminal:enm(["not-observed","observed"]),exitCode:nil(uint(2147483647)),aborted:Type.Boolean(),timedOut:Type.Boolean()});
+const capture=obj({stdoutBytes:uint(),stderrBytes:uint(),stdoutRetainedBytes:uint(65536),stderrRetainedBytes:uint(16384),truncated:Type.Boolean(),complete:Type.Boolean(),validUtf8:Type.Boolean()});
+const stage=obj({attempt,capture:nil(capture),admission:enm(["not-observed","unsupported","admitted"])});
+const text=Type.String({minLength:1,maxLength:4096});
+const data=obj({intendedArgv:Type.Array(text,{minItems:1,maxItems:13}),workingDirectory:nil(text),requestedSource:nil(text),strategy:nil(enm(["auto","source","destination"])),cherrypicking:nil(Type.Boolean()),forced:nil(Type.Boolean()),previewRequested:nil(Type.Boolean()),outputFormatRequested:nil(enm(["text","json"])),apply:stage,shortStatus:stage,fullStatus:stage,pendingReadMode:enm(["short","copied-machine"]),commandCompleted:Type.Boolean(),observedWorkspaceIdentity:Type.Null(),observedSourceIdentity:Type.Null(),observedFinalizedMetadata:Type.Null(),observedPreservation:Type.Null(),observedPendingItems:Type.Null(),fileConflictCount:nil(uint(256)),protocol:enm(["not-observed","already-connected","file-conflict","apply-add","apply-add-copied","unsupported"]),checkinReadiness:enm(["unknown","blocked","supported-no-unresolved-signals"]),verification:Type.Literal("unverified"),effect:enm(["not-attempted","not-proven","uncertain"])});
+export const workspaceMergeOutputSchema=Type.Unsafe<WorkspaceMergeReceipt>(Type.Union([
+ obj({schemaVersion:Type.Literal(1),action:enm(["merge","finalize-merge"]),provenance:obj({source:Type.Literal("plastic"),producer:Type.Literal("@aefree/pi-plastic"),contentTrust:Type.Literal("external")}),completeness:obj({capture:enm(["complete","incomplete","unknown"]),projection:Type.Literal(true)}),data,ok:Type.Literal(true),outcome:enm(["preflight","command-completed"])}),
+ obj({schemaVersion:Type.Literal(1),action:enm(["merge","finalize-merge"]),provenance:obj({source:Type.Literal("plastic"),producer:Type.Literal("@aefree/pi-plastic"),contentTrust:Type.Literal("external")}),completeness:obj({capture:enm(["complete","incomplete","unknown"]),projection:Type.Literal(true)}),data,ok:Type.Literal(false),outcome:enm(["failed","uncertain","blocked"]),error:obj({code:enm(["invalid_request","launch_failed","aborted","uncertain","unsupported_readiness","conflict","producer_failed"]),message:Type.String({minLength:1,maxLength:256})})})
+]));
+export function validateWorkspaceMergeOutput(v:unknown):v is WorkspaceMergeReceipt{
+ if(!Check(workspaceMergeOutputSchema,v)||Buffer.byteLength(JSON.stringify(v),"utf8")>131072)return false;
+ const dto=v as WorkspaceMergeReceipt,d=dto.data,stages=[d.apply,d.shortStatus,d.fullStatus];
+ if(d.requestedSource===null){if(d.intendedArgv.length!==1||d.intendedArgv[0]!=="merge"||[d.workingDirectory,d.strategy,d.cherrypicking,d.forced,d.previewRequested,d.outputFormatRequested].some(x=>x!==null))return false;
+  if(d.commandCompleted||d.protocol!=="not-observed"||d.fileConflictCount!==null||d.checkinReadiness!=="unknown"||d.apply.capture!==null||d.apply.attempt.terminal!=="not-observed"||d.apply.attempt.exitCode!==null||d.apply.attempt.aborted||d.apply.attempt.timedOut||!["not-attempted","unknown"].includes(d.apply.attempt.state)||d.apply.admission!==(d.apply.attempt.state==="unknown"?"unsupported":"not-observed")||stages.slice(1).some(s=>s.admission!=="not-observed"))return false;}
+ else{
+  if(!safeMergeText(d.requestedSource)||d.requestedSource.trimStart().startsWith("-")||!safeMergeText(d.workingDirectory)||d.strategy===null||typeof d.cherrypicking!=="boolean"||typeof d.forced!=="boolean"||typeof d.previewRequested!=="boolean"||d.outputFormatRequested===null)return false;
+  const match=/^--startlineseparator=(__WM_[a-f0-9]{24}__)S__$/.exec(d.intendedArgv[5]??"");if(!match||JSON.stringify(d.intendedArgv)!==JSON.stringify(buildWorkspaceMergeArgv(d.requestedSource,d.strategy,d.cherrypicking,d.forced,match[1])))return false;
+  if(dto.action==="finalize-merge"&&(d.strategy==="auto"||d.cherrypicking||d.forced))return false;
+ }
+ for(const s of stages){const a=s.attempt,c=s.capture;
+  if(a.exitCode!==null&&a.terminal!=="observed"||["not-attempted","not-started"].includes(a.state)&&(a.terminal!=="not-observed"||a.exitCode!==null)||a.state==="not-attempted"&&a.timedOut)return false;
+  if(c){if(c.stdoutRetainedBytes>c.stdoutBytes||c.stderrRetainedBytes>c.stderrBytes)return false;if(c.complete&&(!c.validUtf8||c.truncated||c.stdoutBytes!==c.stdoutRetainedBytes||c.stderrBytes!==c.stderrRetainedBytes||a.state!=="started"||a.terminal!=="observed"||a.exitCode===null||a.aborted||a.timedOut))return false;}
+  if(s.admission==="admitted"&&(!c?.complete||a.state!=="started"))return false;
+  if(s.admission==="not-observed"&&(c||a.state!=="not-attempted"||a.aborted||a.timedOut))return false;
+ }
+ const captured=stages.filter(s=>s.capture);if(dto.completeness.capture!==(!captured.length?"unknown":captured.every(s=>s.capture!.complete)?"complete":"incomplete"))return false;
+ if(d.commandCompleted!==Boolean(d.apply.capture?.complete&&d.apply.attempt.state==="started"&&d.apply.attempt.exitCode===0))return false;
+ if(d.shortStatus.admission==="admitted"&&((d.pendingReadMode==="short"?d.shortStatus.capture?.stdoutBytes!==0:!d.shortStatus.capture?.stdoutBytes)||d.shortStatus.capture?.stderrBytes!==0)||d.fullStatus.admission==="admitted"&&(!d.fullStatus.capture?.stdoutBytes||d.fullStatus.capture?.stderrBytes!==0))return false;
+ if(d.pendingReadMode==="copied-machine"&&d.protocol!=="apply-add-copied"||d.protocol==="apply-add-copied"&&d.pendingReadMode!=="copied-machine")return false;
+ const later=stages.slice(1).some(s=>s.admission!=="not-observed");if(later&&(!d.commandCompleted||!["already-connected","apply-add","apply-add-copied"].includes(d.protocol)))return false;
+ if(d.fullStatus.admission!=="not-observed"&&(!d.shortStatus.capture?.complete||d.shortStatus.attempt.exitCode!==0))return false;
+ if(d.protocol==="not-observed"&&(d.apply.admission==="admitted"||d.fileConflictCount!==null)||d.protocol==="unsupported"&&(d.fileConflictCount!==null||d.apply.admission!=="unsupported"))return false;
+ if(["already-connected","apply-add","apply-add-copied","file-conflict"].includes(d.protocol)&&d.apply.admission!=="admitted")return false;
+ if(d.protocol==="file-conflict"?(d.fileConflictCount===null||d.fileConflictCount===0||d.checkinReadiness!=="blocked"):d.checkinReadiness==="blocked")return false;
+ if(["already-connected","apply-add","apply-add-copied"].includes(d.protocol)&&d.fileConflictCount!==0)return false;
+ if(d.checkinReadiness==="supported-no-unresolved-signals"&&(!d.commandCompleted||!stages.every(s=>s.admission==="admitted"&&s.capture?.complete&&s.attempt.exitCode===0&&s.capture.stderrBytes===0)))return false;
+ if(d.previewRequested===true&&(!dto.ok||dto.outcome!=="preflight"||stages.some(s=>s.admission!=="not-observed")||d.effect!=="not-attempted"||d.commandCompleted||d.checkinReadiness!=="unknown"))return false;
+ if(dto.ok){if(dto.outcome==="preflight"&&d.previewRequested!==true)return false;if(dto.outcome==="command-completed"&&(d.previewRequested!==false||d.effect!=="not-proven"||d.checkinReadiness!=="supported-no-unresolved-signals"))return false;}
+ else{if(!safeMergeText(dto.error.message))return false;if(dto.outcome==="failed"&&(d.effect!=="not-attempted"||!["not-attempted","not-started"].includes(d.apply.attempt.state)))return false;if(dto.outcome!=="failed"&&(d.effect!=="uncertain"||!["started","unknown"].includes(d.apply.attempt.state)))return false;if(dto.outcome==="blocked"&&d.checkinReadiness!=="blocked"||dto.outcome==="uncertain"&&d.checkinReadiness!=="unknown")return false;if(dto.error.code==="invalid_request"&&(d.requestedSource!==null||stages.some(s=>s.admission!=="not-observed")))return false;}
+ return true;
+}
+export async function executeWorkspaceMergeOutput(action:MergeAction,args:unknown){let dto=await assembleWorkspaceMergeReceipt(action,args);const valid:boolean=validateWorkspaceMergeOutput(dto);if(!valid){const possible=["started","unknown"].includes(dto.data.apply.attempt.state),d=emptyWorkspaceMergeData();if(possible){d.apply.attempt.state="unknown";d.apply.admission="unsupported";d.effect="uncertain";}dto=workspaceMergeFailure(action,d,"producer_failed","Workspace merge receipt validation failed; effects remain possible, no automatic retry.");if(!validateWorkspaceMergeOutput(dto))throw new Error("Safe workspace merge receipt unavailable.");}return {content:[{type:"text" as const,text:presentWorkspaceMergeReceipt(dto)}],details:{},structuredContent:dto,isError:!dto.ok};}