@aefree/pi-plastic 0.7.5 → 0.8.0

package/src/pi/checkin-output.ts

@@ -0,0 +1,68 @@
+import { Type, type TProperties } from "typebox";
+import { Check } from "typebox/value";
+import { assembleCheckinReceipt, presentCheckinReceipt, checkinSafeValue, parseCheckinChangeset, type CheckinReceipt } from "../operations/checkin-receipt";
+const object = <P extends TProperties>(p: P) => Type.Object(p, { additionalProperties: false });
+const enumOf = <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 });
+const uint = (max = Number.MAX_SAFE_INTEGER) => Type.Integer({ minimum: 0, maximum: max });
+const nullable = <T extends ReturnType<typeof object> | ReturnType<typeof Type.Array>>(s: T) => Type.Union([s, Type.Null()]);
+const cs = object({ id: Type.String({ pattern: "^(0|[1-9][0-9]{0,19})$" }), branch: str(), repository: str(), server: str(), mount: Type.Literal("/") });
+const summary = object({ totalPending: uint(499), tracked: uint(499), private: uint(499), added: uint(499), changed: uint(499), moved: uint(499), deleted: uint(499), other: uint(499) });
+const attempt = object({ state: enumOf(["not-attempted", "not-started", "started", "unknown"]), terminal: enumOf(["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 step = object({ name: enumOf(["pending-before", "initial-checkin", "private-add", "private-retry", "pending-recovery", "fallback-checkin", "pending-after", "merge-diagnostic"]), operation: enumOf(["status", "checkin", "add"]), attempt, capture, effect: enumOf(["not-attempted", "uncertain", "command-completed", "changeset-created", "read-observed"]), evidence: enumOf(["unadmitted", "admitted"]), records: uint(501), summary: nullable(summary), changeset: nullable(cs) });
+const paths = Type.Array(str(), { maxItems: 100 });
+const reasons = Type.Array(object({ path: str(), reason: str(256) }), { maxItems: 100 });
+const data = { sourceAdmission: Type.Literal("windows-cm11.0.16.10371-observed"), requestedPaths: paths, includedPaths: paths, fallbackPaths: paths, excludedPaths: reasons, privateAddPaths: paths, blockedPrivatePaths: reasons, itemEvents: Type.Array(Type.Union([object({ operation: enumOf(["CO", "AD", "DE", "CP"]), path: str() }), object({ operation: Type.Literal("MV"), sourcePath: str(), path: str() })]), { maxItems: 100 }), observedChangesets: Type.Array(cs, { maxItems: 100 }), command: nullable(Type.Array(str(8192), { maxItems: 120 })), steps: Type.Array(step, { maxItems: 8 }), autoEnabledApplyChanged: Type.Boolean(), usedFallbackRetry: Type.Boolean(), usedPrivateAutoAddRecovery: Type.Boolean(), pendingBefore: nullable(summary), pendingAfter: nullable(summary), wouldRun: Type.Boolean(), omittedReferences: uint(10000), scopeExhaustion: Type.Literal("unverified"), branchHead: Type.Literal("unverified"), serverAliasEquivalence: Type.Literal("unverified"), xlinkEffects: Type.Literal("unverified"), mergeLinkIdentity: Type.Literal("unverified") };
+const header = { schemaVersion: Type.Literal(1), action: Type.Literal("checkin"), provenance: object({ source: Type.Literal("plastic"), producer: Type.Literal("@aefree/pi-plastic"), contentTrust: Type.Literal("external") }), completeness: object({ capture: enumOf(["complete", "incomplete", "unknown"]), projection: Type.Boolean() }) };
+const error = object({ code: str(64), stage: enumOf(["input", "pending", "checkin", "producer"]), message: str(512) });
+export const checkinOutputSchema = Type.Unsafe<CheckinReceipt>(Type.Union([
+    object({ ...header, ok: Type.Literal(true), outcome: Type.Literal("completed"), data: object({ ...data, effect: Type.Literal("changeset-created"), createdChangeset: cs }) }),
+    object({ ...header, ok: Type.Literal(true), outcome: Type.Literal("preflight"), data: object({ ...data, effect: Type.Literal("not-attempted"), createdChangeset: Type.Null() }) }),
+    object({ ...header, ok: Type.Literal(false), outcome: enumOf(["failed", "unsupported", "uncertain"]), error, data: object({ ...data, effect: enumOf(["not-attempted", "uncertain", "command-completed", "changeset-created"]), createdChangeset: nullable(cs) }) }),
+]));
+export function validateCheckinOutput(value: unknown): value is CheckinReceipt {
+    if (!Check(checkinOutputSchema, value) || Buffer.byteLength(JSON.stringify(value), "utf8") > 131072) return false;
+    const d = (value as CheckinReceipt).data, dto = value as CheckinReceipt;
+    const lists = [d.requestedPaths, d.includedPaths, d.fallbackPaths, d.excludedPaths, d.privateAddPaths, d.blockedPrivatePaths, d.itemEvents, d.observedChangesets, d.command ?? []];
+    if (lists.reduce((n, a) => n + a.length, 0) > 100 || dto.completeness.projection !== (d.omittedReferences === 0)) return false;
+    if (![...d.requestedPaths, ...d.includedPaths, ...d.fallbackPaths, ...d.privateAddPaths, ...d.excludedPaths.map(p => p.path), ...d.blockedPrivatePaths.map(p => p.path)].every(checkinSafeValue)) return false;
+    const validCs = (c: NonNullable<typeof d.createdChangeset>) => !!parseCheckinChangeset(`cs:${c.id}@br:${c.branch}@${c.repository}@${c.server} (mount:'/')`);
+    if (!d.observedChangesets.every(validCs) || d.createdChangeset && !validCs(d.createdChangeset)) return false;
+    for (const e of d.itemEvents) if (!checkinSafeValue(e.path) || e.operation === "MV" && !checkinSafeValue(e.sourcePath)) return false;
+    if (d.command && (d.command.reduce((n, a) => n + a.length, 0) > 32768 || Buffer.byteLength(JSON.stringify(d.command), "utf8") > 65536 || d.command[0] !== "cm" || d.command[1] !== "checkin")) return false;
+    const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
+    const summaryValid = (s: NonNullable<typeof d.pendingBefore>) => s.totalPending === s.tracked + s.private && s.totalPending === s.added + s.changed + s.moved + s.deleted + s.private + s.other;
+    if (d.pendingBefore && !summaryValid(d.pendingBefore) || d.pendingAfter && !summaryValid(d.pendingAfter)) return false;
+    const normal = (s: typeof d.steps[number]) => s.attempt.state === "started" && s.attempt.terminal === "observed" && s.attempt.exitCode !== null && !s.attempt.aborted && !s.attempt.timedOut && s.capture.complete;
+    for (const s of d.steps) {
+        const a = s.attempt, c = s.capture;
+        if (a.exitCode !== null && a.terminal !== "observed" || c.stdoutRetainedBytes > c.stdoutBytes || c.stderrRetainedBytes > c.stderrBytes || c.complete && (!c.validUtf8 || c.truncated || a.terminal !== "observed" || a.aborted || a.timedOut)) return false;
+        if (s.summary && (!summaryValid(s.summary) || s.operation !== "status" || s.effect !== "read-observed")) return false;
+        if (s.operation === "status" && !["not-attempted", "read-observed"].includes(s.effect)) return false;
+        if (s.operation !== "status" && s.summary) return false;
+        if (s.effect === "read-observed" && (!normal(s) || a.exitCode !== 0 || c.stderrBytes || s.evidence !== "admitted" || !s.summary)) return false;
+        if (s.effect === "command-completed" && (s.operation !== "add" || !normal(s) || a.exitCode !== 0)) return false;
+        if (s.effect === "changeset-created" && (s.operation !== "checkin" || !normal(s) || a.exitCode !== 0 || c.stderrBytes || s.evidence !== "admitted" || !s.changeset || !validCs(s.changeset))) return false;
+        if (s.changeset && s.effect !== "changeset-created") return false;
+        if (s.operation !== "status" && s.effect === "not-attempted" && !["not-attempted", "not-started"].includes(a.state)) return false;
+    }
+    const mutations = d.steps.filter(s => s.operation !== "status"), created = mutations.filter(s => s.effect === "changeset-created");
+    const expected = created.length ? "changeset-created" : mutations.some(s => s.effect === "uncertain") ? "uncertain" : mutations.some(s => s.effect === "command-completed") ? "command-completed" : "not-attempted";
+    if (d.effect !== expected || created.length > 1 || !!d.createdChangeset !== !!created.length || d.createdChangeset && !same(d.createdChangeset, created[0].changeset)) return false;
+    if (dto.outcome === "completed" && (!d.createdChangeset || !d.pendingBefore || !d.wouldRun)) return false;
+    if (dto.outcome === "preflight" && (mutations.length || !d.pendingBefore || !d.wouldRun || d.steps.length !== 1)) return false;
+    if ((dto.outcome === "failed" || dto.outcome === "unsupported") && mutations.length) return false;
+    if (d.usedFallbackRetry !== d.steps.some(s => s.name === "fallback-checkin")) return false;
+    if (d.usedPrivateAutoAddRecovery !== d.steps.some(s => s.name === "private-add" && s.effect === "command-completed")) return false;
+    if (dto.completeness.capture !== (d.steps.length ? d.steps.every(s => s.capture.complete) ? "complete" : "incomplete" : "unknown")) return false;
+    if (d.pendingBefore && !same(d.pendingBefore, d.steps.find(s => s.name === "pending-before")?.summary)) return false;
+    if (d.pendingAfter && !d.steps.some(s => ["pending-recovery", "pending-after"].includes(s.name) && same(s.summary, d.pendingAfter))) return false;
+    return true;
+}
+export async function executeCheckinOutput(args: unknown) {
+    const dto = await assembleCheckinReceipt(args);
+    if (!validateCheckinOutput(dto)) throw new Error("The bounded checkin producer receipt could not be verified.");
+    const text = presentCheckinReceipt(dto, (args as { format?: unknown })?.format === "json" ? "json" : "text");
+    return { content: [{ type: "text" as const, text }], details: {}, structuredContent: dto, isError: !dto.ok };
+}

package/src/pi/closeout-output.ts

@@ -0,0 +1,87 @@
+import { Type } from "typebox";
+import { Check } from "typebox/value";
+import { resolve } from "node:path";
+import { switchOutputSchema, validateSwitchOutput } from "./switch-output";
+import { updateOutputSchema, validateUpdateOutput } from "./update-output";
+import { workspaceMergeOutputSchema, validateWorkspaceMergeOutput } from "./workspace-merge-output";
+import { checkinOutputSchema, validateCheckinOutput } from "./checkin-output";
+import { buildCloseoutParentArgv, assembleCloseoutReceipt, presentCloseoutReceipt, CLOSEOUT_STAGE_NAMES, CLOSEOUT_DTO_BYTES, closeoutCaptures, closeoutChildEffect, compareSwitchTarget, parseSwitchTarget, safeSwitchValue, switchPendingArgv, checkinSafeComment, checkinSafeValue, cmWhereEquals, type CloseoutReceipt, type CloseoutStage, type CloseoutRead } from "../operations/closeout-receipt";
+const obj=(p:Record<string,any>)=>Type.Object(p,{additionalProperties:false}),enm=(v:readonly string[])=>Type.Union(v.map(x=>Type.Literal(x))),nil=(t:any)=>Type.Union([t,Type.Null()]),str=(max=4096)=>Type.String({maxLength:max}),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 branch=obj({branch:str(),repository:str(),server:str(),basis:Type.Literal("standard-status"),scope:Type.Literal("loaded-workspace")});
+const summary=obj(Object.fromEntries(["totalPending","tracked","private","added","changed","moved","deleted","other"].map(k=>[k,uint(20000)])));
+const changeset=obj({id:Type.String({pattern:"^(0|[1-9][0-9]{0,19})$"}),branch:str(),repository:str(),server:str(),mount:Type.Literal("/")});
+const read=obj({argv:Type.Array(str(16384),{minItems:1,maxItems:5}),attempt,capture:nil(capture),admission:enm(["unsupported","admitted"]),branch:nil(branch),parentPath:nil(str()),emptyParentResult:Type.Boolean(),summary:nil(summary)});
+const stage=Type.Union([obj({name:enm(CLOSEOUT_STAGE_NAMES),kind:Type.Literal("read"),result:read}),...[["switch",switchOutputSchema],["update",updateOutputSchema],["merge",workspaceMergeOutputSchema],["checkin",checkinOutputSchema]].map(([k,s])=>obj({name:enm(CLOSEOUT_STAGE_NAMES),kind:Type.Literal(k as string),result:s}))]);
+const requested=obj({source:nil(str()),target:nil(str()),message:nil(str()),cardRef:nil(str()),strategy:enm(["auto","source","destination"]),updateTarget:Type.Boolean(),includePrivate:Type.Boolean(),preflight:Type.Boolean(),outputFormat:enm(["text","json"]),workdir:str()});
+const data=obj({requested:nil(requested),sourceBranch:nil(str()),targetBranch:nil(str()),targetSource:enm(["unresolved","explicit","parent-read"]),checkinMessage:nil(str(16384)),stages:Type.Array(stage,{maxItems:16}),unattemptedStages:Type.Array(enm(CLOSEOUT_STAGE_NAMES),{maxItems:14,uniqueItems:true}),unobservedChild:nil(enm(["switch","update","merge","checkin-preflight","checkin"])),createdChangeset:nil(changeset),pendingAfter:nil(summary),targetVerification:enm(["unverified","name-only","exact-qualifier-spelling"]),serverAliasEquivalence:Type.Literal("unverified"),sourceLink:Type.Literal("unverified"),branchHead:Type.Literal("unverified"),exclusiveScope:Type.Literal("unverified"),rollback:Type.Literal("not-proven"),effect:enm(["not-attempted","command-completed","uncertain","changeset-created"])});
+const header={schemaVersion:Type.Literal(1),action:Type.Literal("merge-to-branch"),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.Boolean()}),data};
+export const closeoutOutputSchema=Type.Unsafe<CloseoutReceipt>(Type.Union([obj({...header,ok:Type.Literal(true),outcome:enm(["preflight","completed"])}),obj({...header,ok:Type.Literal(false),outcome:enm(["blocked","failed","uncertain"]),error:obj({code:enm(["invalid_request","unsupported_source","observation_failed","target_unverified","policy_blocked","child_failed","producer_failed"]),stage:enm(["input",...CLOSEOUT_STAGE_NAMES,"producer"]),message:str(256)})})]));
+const same=(a:unknown,b:unknown)=>JSON.stringify(a)===JSON.stringify(b);
+const normal=(s:CloseoutRead)=>s.capture?.complete&&s.attempt.state==="started"&&s.attempt.terminal==="observed"&&s.attempt.exitCode===0&&!s.attempt.aborted&&!s.attempt.timedOut&&s.capture.stderrBytes===0;
+function validateRead(s:CloseoutStage&{kind:"read"}):boolean {
+ const r=s.result,c=r.capture,a=r.attempt;
+ if(a.exitCode!==null&&a.terminal!=="observed")return false;
+ if(c&&(c.stdoutRetainedBytes>c.stdoutBytes||c.stderrRetainedBytes>c.stderrBytes||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(r.admission==="admitted"&&!normal(r))return false;
+ if(r.admission==="unsupported"&&(r.branch||r.parentPath||r.summary||r.emptyParentResult))return false;
+ if(s.name.startsWith("loaded-")) {if(!same(r.argv,["status"])||r.parentPath||r.summary||r.emptyParentResult||r.admission==="admitted"&&!r.branch)return false;if(r.branch&&(!parseSwitchTarget(`${r.branch.branch}@${r.branch.repository}@${r.branch.server}`)||!safeSwitchValue(r.branch.branch)))return false;}
+ else if(s.name==="parent"){if(r.branch||r.summary||r.admission==="admitted"&&!(r.emptyParentResult?!r.parentPath:!!r.parentPath&&!!parseSwitchTarget(r.parentPath)))return false;}
+ else if(s.name==="pending-before"||s.name==="pending-final"){if(!same(r.argv,[...switchPendingArgv])||r.branch||r.parentPath||r.emptyParentResult||r.admission==="admitted"&&!r.summary)return false;if(r.summary){const p=r.summary;if(p.tracked!==p.added+p.changed+p.moved+p.deleted||p.totalPending!==p.tracked+p.private+p.other)return false;}}
+ else if(s.name==="readiness"){if(!(same(r.argv,["status"])||same(r.argv,[...switchPendingArgv]))||r.branch||r.parentPath||r.summary||r.emptyParentResult||r.admission==="admitted"&&!r.capture?.stdoutBytes)return false;}
+ else return false;
+ return true;
+}
+export function validateCloseoutOutput(value:unknown):value is CloseoutReceipt {
+ if(!Check(closeoutOutputSchema,value)||Buffer.byteLength(JSON.stringify(value),"utf8")>CLOSEOUT_DTO_BYTES)return false;
+ const dto=value as CloseoutReceipt,d=dto.data,r=d.requested,stages=d.stages;
+ if(!same(d.unattemptedStages,CLOSEOUT_STAGE_NAMES.filter(n=>!stages.some(s=>s.name===n)&&d.unobservedChild!==n)))return false;
+ const caps=closeoutCaptures(stages),expectedCapture=!caps.length?"unknown":!d.unobservedChild&&stages.every(s=>s.kind!=="read"||s.result.capture!==null)&&caps.every(c=>c.complete)?"complete":"incomplete";
+ if(dto.completeness.capture!==expectedCapture||dto.completeness.projection!==stages.every(s=>s.kind==="read"||s.result.completeness.projection))return false;
+ const effects=stages.map(closeoutChildEffect),effect=d.createdChangeset?"changeset-created":d.unobservedChild||effects.includes("uncertain")?"uncertain":effects.includes("command-completed")?"command-completed":"not-attempted";
+ if(d.effect!==effect)return false;
+ if(!r)return !dto.ok&&dto.outcome==="failed"&&dto.error.code==="invalid_request"&&dto.error.stage==="input"&&!stages.length&&!d.unobservedChild&&!d.sourceBranch&&!d.targetBranch&&d.targetSource==="unresolved"&&!d.checkinMessage&&!d.createdChangeset&&!d.pendingAfter&&d.targetVerification==="unverified";
+ if(!safeSwitchValue(r.workdir)||r.source!==null&&!parseSwitchTarget(r.source)||r.target!==null&&!parseSwitchTarget(r.target)||r.message!==null&&!checkinSafeComment(r.message)||r.cardRef!==null&&!checkinSafeValue(r.cardRef)||Buffer.byteLength(JSON.stringify(r),"utf8")>32768+256)return false;
+ const parentCount=stages.filter(s=>s.name==="parent").length;if(parentCount>1||r.target!==null&&parentCount)return false;
+ const plan=["loaded-before",...(r.target===null?Array(Math.max(1,parentCount)).fill("parent"):[]),"pending-before","switch","loaded-after-switch",...(r.updateTarget?["update"]:[]),"loaded-before-merge","merge","readiness","loaded-before-checkin","checkin-preflight","checkin","loaded-final","pending-final"];
+ if(stages.some((s,i)=>s.name!==plan[i])||d.unobservedChild&&d.unobservedChild!==plan[stages.length])return false;
+ if(d.unobservedChild&&(dto.ok||dto.error.code!=="producer_failed"||dto.error.stage!==d.unobservedChild))return false;
+ const initial=stages[0]?.kind==="read"?stages[0].result.branch:null;
+ if(d.sourceBranch!==null&&(!initial||d.sourceBranch!==(r.source??initial.branch)))return false;
+ if(d.targetSource==="explicit"&&(d.targetBranch!==r.target||r.target===null)||d.targetSource==="unresolved"&&d.targetBranch!==null)return false;
+ const parent=stages.filter(s=>s.name==="parent"&&s.kind==="read").at(-1) as (CloseoutStage&{kind:"read"})|undefined;
+ if(d.targetSource==="parent-read"){if(!parent?.result.parentPath||r.target!==null||!d.sourceBranch)return false;const src=parseSwitchTarget(d.sourceBranch)!;if(d.targetBranch!==(src.repository===null?parent.result.parentPath:`${parent.result.parentPath}@${src.repository}@${src.server}`))return false;}
+ if(d.targetBranch!==null&&!parseSwitchTarget(d.targetBranch))return false;
+ if(d.checkinMessage!==null&&(!d.sourceBranch||!d.targetBranch||d.checkinMessage!==(r.message?.trim()?r.message:`Merge ${d.sourceBranch} into ${d.targetBranch}${r.cardRef?.trim()?`\n\n${r.cardRef.trim()}`:""}`)))return false;
+ let lastVerification="unverified";
+ for(const [index,s] of stages.entries()) {
+  if(s.kind==="read") {
+   if(!validateRead(s))return false;
+   if(s.name==="readiness"){const merge=stages.slice(0,index).find(x=>x.kind==="merge");if(!merge||merge.kind!=="merge"||!same(s.result.argv,merge.result.data.protocol==="apply-add-copied"?[...switchPendingArgv]:["status"]))return false;}
+   if(s.name==="parent"){if(!d.sourceBranch||!same(s.result.argv,buildCloseoutParentArgv(d.sourceBranch)))return false;const src=parseSwitchTarget(d.sourceBranch)!;if(s.result.parentPath&&(s.result.parentPath!==src.branch.slice(0,src.branch.lastIndexOf("/"))||!s.result.capture?.stdoutBytes))return false;if(s.result.emptyParentResult&&s.result.capture?.stdoutBytes!==0)return false;if(index<stages.length-1&&(s.result.emptyParentResult||!s.result.parentPath||stages[index+1].name!=="pending-before"))return false;}
+   if(index<stages.length-1&&s.result.admission!=="admitted")return false;
+   if(s.name.startsWith("loaded-")&&s.name!=="loaded-before"&&s.result.branch){if(!d.targetBranch)return false;lastVerification=compareSwitchTarget(s.result.branch,d.targetBranch);if(index<stages.length-1&&lastVerification==="unverified")return false;}
+  }else{
+   if(!d.sourceBranch||!d.targetBranch||!d.checkinMessage||!checkinSafeComment(d.checkinMessage))return false;
+   if(s.kind==="switch"){if(s.name!=="switch"||!validateSwitchOutput(s.result)||s.result.data.requestedTarget!==d.targetBranch||s.result.data.pendingPolicy!=="cancel"||s.result.data.preflight||s.result.data.workdir!==resolve(r.workdir))return false;}
+   else if(s.kind==="update"){if(s.name!=="update"||!validateUpdateOutput(s.result)||s.result.data.workingDirectory!==r.workdir)return false;}
+   else if(s.kind==="merge"){if(s.name!=="merge"||!validateWorkspaceMergeOutput(s.result)||s.result.action!=="merge"||s.result.data.requestedSource!==d.sourceBranch||s.result.data.strategy!==r.strategy||s.result.data.workingDirectory!==r.workdir||s.result.data.previewRequested!==false||s.result.data.cherrypicking||s.result.data.forced)return false;}
+   else{if(!["checkin-preflight","checkin"].includes(s.name)||!validateCheckinOutput(s.result)||s.name==="checkin-preflight"&&s.result.ok&&s.result.outcome!=="preflight"||s.name==="checkin"&&s.result.ok&&s.result.outcome!=="completed")return false;const cmd=s.result.data.command,expected=["cm","checkin",`-c=${d.checkinMessage}`,"--all",...(r.includePrivate?["--private"]:[])];if(cmd&&(!same(cmd.slice(0,expected.length),expected)||cmd[expected.length]!=="--machinereadable"))return false;}
+   if(index<stages.length-1&&!s.result.ok)return false;
+  }
+ }
+ const pending=stages.find(s=>s.name==="pending-before");if(pending&&pending.kind==="read"&&pending.result.summary&&d.targetBranch&&initial){const v=compareSwitchTarget(initial,d.targetBranch);if(!stages.some(s=>s.name.startsWith("loaded-")&&s.name!=="loaded-before"&&s.kind==="read"&&s.result.branch))lastVerification=v;if(v==="unverified"&&pending.result.summary.totalPending>0&&stages.some(s=>s.kind!=="read"))return false;}
+ if(d.targetVerification!==lastVerification)return false;
+ if(dto.ok||stages.some(s=>s.kind!=="read")){if(!initial||!d.targetBranch||!d.sourceBranch||parseSwitchTarget(d.sourceBranch)!.branch===parseSwitchTarget(d.targetBranch)!.branch)return false;for(const spec of [d.sourceBranch,d.targetBranch]){const p=parseSwitchTarget(spec)!;if(p.repository!==null&&(p.repository!==initial.repository||p.server!==initial.server))return false;}}
+ const checked=stages.find(s=>s.name==="checkin"&&s.kind==="checkin") as (CloseoutStage&{kind:"checkin"})|undefined;
+ if(!same(d.createdChangeset,checked?.result.data.createdChangeset??null))return false;
+ const final=stages.find(s=>s.name==="pending-final"&&s.kind==="read") as (CloseoutStage&{kind:"read"})|undefined;
+ if(!same(d.pendingAfter,final?.result.summary??null))return false;
+ if(r.preflight&&(stages.some(s=>s.kind!=="read"||!["loaded-before","parent","pending-before"].includes(s.name))||d.unobservedChild))return false;
+ if(dto.ok){if(dto.outcome==="preflight")return r.preflight&&!!d.sourceBranch&&!!d.targetBranch&&!!d.checkinMessage&&checkinSafeComment(d.checkinMessage)&&stages.at(-1)?.name==="pending-before"&&pending?.kind==="read"&&pending.result.admission==="admitted"&&d.effect==="not-attempted";const loaded=stages.find(s=>s.name==="loaded-final"&&s.kind==="read") as (CloseoutStage&{kind:"read"})|undefined,b=loaded?.result.branch,c=d.createdChangeset;return !r.preflight&&stages.length===plan.length&&!!c&&!!b&&c.branch===b.branch&&c.repository===b.repository&&c.server===b.server&&!!d.pendingAfter&&d.targetVerification!=="unverified"&&final?.result.admission==="admitted";}
+ if(!safeSwitchValue(dto.error.message))return false;
+ if(dto.outcome==="uncertain"?d.effect==="not-attempted":d.effect!=="not-attempted")return false;
+ return dto.error.stage==="input"&&!stages.length||dto.error.stage===stages.at(-1)?.name||dto.error.stage===d.unobservedChild;
+}
+export async function executeCloseoutOutput(args:unknown){const dto=await assembleCloseoutReceipt(args);if(!validateCloseoutOutput(dto))throw Error("Closeout receipt could not be validated; prior effects remain possible. No automatic retry.");return {content:[{type:"text" as const,text:presentCloseoutReceipt(dto)}],details:{},structuredContent:dto,isError:!dto.ok};}

package/src/pi/code-review-find-output.ts

@@ -0,0 +1,50 @@
+import { Type, type Static, type TSchema } from "typebox";
+import { Check } from "typebox/value";
+import { assembleCodeReviewFindObservation, presentCodeReviewFindObservation, codeReviewFindPayload, CodeReviewFindError, validCodeReviewId, validCodeReviewQueryString, CODE_REVIEW_FIND_MAX_BYTES, type CodeReviewFindArgs } from "../operations/code-review-find";
+import { CodeReviewFindCommandError } from "../execution/code-review-find-command";
+import { getActiveAbortSignal } from "../execution/context";
+const object = <T extends Record<string, TSchema>>(fields: T) => Type.Object(fields, { additionalProperties: false });
+const nullable = <T extends TSchema>(schema: T) => Type.Union([schema, Type.Null()]);
+const integer = (maximum: number) => Type.Integer({ minimum: 0, maximum });
+const queryString = nullable(Type.String({ maxLength: 4096, pattern: "^[^\\u0000-\\u001f\\u007f-\\u009f]*$" }));
+const query = object({ status: queryString, assignee: queryString, owner: queryString, target: queryString, titleLike: queryString, targetType: nullable(Type.Union([Type.Literal("branch"), Type.Literal("changeset")])), orderBy: nullable(Type.Union([Type.Literal("date"), Type.Literal("modifieddate"), Type.Literal("status")])), descending: nullable(Type.Boolean()), limit: nullable(Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER })) });
+const common = { schemaVersion: Type.Literal(1), action: Type.Literal("code-review-find"), provenance: object({ source: Type.Literal("plastic"), producer: Type.Literal("@aefree/pi-plastic"), contentTrust: Type.Literal("external") }) };
+const dataCommon = { scope: Type.Literal("workspace_repository"), qualifierVerified: Type.Literal(false), query, limits: object({ maxItems: Type.Integer({ minimum: 1, maximum: 500 }), idDigits: Type.Literal(20), queryCodeUnits: Type.Literal(4096), compactUtf8Bytes: Type.Literal(131072) }) };
+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 codeReviewFindOutputSchema = Type.Union([
+    object({ ...common, ok: Type.Literal(true), completeness: object({ read: Type.Literal("complete"), capture: Type.Literal("complete"), projection: Type.Boolean() }), data: object({ ...dataCommon, mode: Type.Literal("ids"), basis: Type.Literal("find_review_id_utf8"), diagnostics: object({ duplicateRecords: integer(19999) }), rows: Type.Array(object({ id: Type.String({ minLength: 1, maxLength: 20, pattern: "^(?:0|[1-9][0-9]*)$" }) }), { maxItems: 500 }), countBasis: Type.Literal("observed_query_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("find_review_native"), 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 CodeReviewFindOutput = Static<typeof codeReviewFindOutputSchema>;
+export type CodeReviewFindErrorCode = Extract<CodeReviewFindOutput, { ok: false }>["error"]["code"];
+const failure = (code: CodeReviewFindErrorCode): CodeReviewFindOutput => ({ schemaVersion: 1, action: "code-review-find", provenance: { source: "plastic", producer: "@aefree/pi-plastic", contentTrust: "external" }, ok: false, completeness: { read: "incomplete", capture: "unknown", projection: false }, error: { code, message: `Code review find read failed (${code}); no reusable rows are available.` } });
+export function validateCodeReviewFindOutput(value: unknown): CodeReviewFindOutput {
+    if (!Check(codeReviewFindOutputSchema, value)) return failure("invalid_producer_data");
+    const dto = value as CodeReviewFindOutput;
+    if (dto.ok) {
+        if ([dto.data.query.status, dto.data.query.assignee, dto.data.query.owner, dto.data.query.target, dto.data.query.titleLike].some(value => value !== null && !validCodeReviewQueryString(value))) return failure("invalid_producer_data");
+        if (dto.data.mode === "ids") {
+            const { rows, counts, diagnostics, limits, query } = dto.data;
+            const repeats = rows.length - new Set(rows.map(row => row.id)).size;
+            if (rows.some(row => !validCodeReviewId(row.id))
+                || counts.returned !== rows.length || counts.observed !== counts.returned + counts.omitted || counts.returned !== Math.min(counts.observed, limits.maxItems)
+                || (query.limit !== null && counts.observed > query.limit) || dto.completeness.projection !== (counts.omitted === 0)
+                || diagnostics.duplicateRecords < repeats || diagnostics.duplicateRecords > repeats + counts.omitted || diagnostics.duplicateRecords > Math.max(0, counts.observed - 1)) return failure("invalid_producer_data");
+        }
+    }
+    if (Buffer.byteLength(JSON.stringify(dto), "utf8") > CODE_REVIEW_FIND_MAX_BYTES) return failure("output_overflow");
+    return dto;
+}
+export async function executeCodeReviewFindOutput(args: CodeReviewFindArgs) {
+    let dto: CodeReviewFindOutput, rawResult: string | undefined;
+    try {
+        const observation = await assembleCodeReviewFindObservation(args, true);
+        if (getActiveAbortSignal()?.aborted) throw new CodeReviewFindCommandError("aborted");
+        dto = validateCodeReviewFindOutput(codeReviewFindPayload(observation));
+        if (dto.ok) rawResult = await presentCodeReviewFindObservation(observation, args);
+        if (getActiveAbortSignal()?.aborted) throw new CodeReviewFindCommandError("aborted");
+    } catch (error) { dto = failure(error instanceof CodeReviewFindError || error instanceof CodeReviewFindCommandError ? error.code : "invalid_producer_data"); }
+    dto = validateCodeReviewFindOutput(dto);
+    return { content: [{ type: "text" as const, text: dto.ok ? rawResult! : dto.error.message }], structuredContent: dto, isError: !dto.ok, details: { exportName: "codeReviewFind", rawResult: dto.ok ? rawResult : undefined, ...(args.workdir ? { workdir: args.workdir } : {}) } };
+}

package/src/pi/diff-output.ts

@@ -0,0 +1,66 @@
+import { Type, type Static, type TProperties } from "typebox";
+import { Check } from "typebox/value";
+import { validDiffRevisionsSelector } from "../operations/diff-revisions";
+import { assembleConsolidatedDiff, diffError, type DiffRequest } from "../operations/consolidated-diff";
+const object=<P extends TProperties>(p:P)=>Type.Object(p,{additionalProperties:false});
+const enumOf=<const V extends readonly string[]>(v:V)=>Type.Unsafe<V[number]>({anyOf:v.map(x=>({type:"string",const:x}))});
+const string=(max=4096)=>Type.String({maxLength:max});
+const uint=(max=4194304)=>Type.Integer({minimum:0,maximum:max});
+const nullable=<T extends ReturnType<typeof Type.String>|ReturnType<typeof object>|ReturnType<typeof Type.Array>|ReturnType<typeof Type.Integer>|ReturnType<typeof enumOf>>(s:T)=>Type.Union([s,Type.Null()]);
+const common={workdir:Type.Optional(Type.String({minLength:1,maxLength:4096})),format:Type.Optional(enumOf(["text","json"])),maxChars:Type.Optional(Type.Integer({minimum:500,maximum:20000}))};
+const paths=Type.Array(Type.String({minLength:1,maxLength:1024}),{minItems:1,maxItems:20});
+const workspace={...common,maxChars:Type.Optional(Type.Integer({minimum:500,maximum:8000})),maxFiles:Type.Optional(Type.Integer({minimum:1,maximum:20}))};
+const variants=Type.Union([
+    object({mode:Type.Literal("file"),path:Type.String({minLength:1,maxLength:1024}),revision:Type.Optional(Type.String({minLength:1,maxLength:4096})),...common}),
+    object({mode:Type.Literal("revisions"),leftRevision:Type.String({minLength:1,maxLength:4096}),rightRevision:Type.String({minLength:1,maxLength:4096}),...common}),
+    object({mode:Type.Literal("workspace"),paths,...workspace}),
+    object({mode:Type.Literal("workspace"),allPending:Type.Literal(true),includePrivate:Type.Optional(Type.Boolean()),...workspace}),
+]);
+export const diffInputSchema=Type.Unsafe<DiffRequest>({...variants,type:"object"});
+const provenance=object({source:Type.Literal("plastic"),producer:Type.Literal("@aefree/pi-plastic"),contentTrust:Type.Literal("external")});
+const completeness=object({read:enumOf(["complete","incomplete"]),capture:enumOf(["complete","unknown"]),projection:Type.Boolean()});
+const error=object({code:enumOf(["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","comparison_failed","partial_comparison"]),stage:enumOf(["input","selection","status","base","left","right","comparison","cleanup","producer"]),message:string(256)});
+const identity=object({revisionId:Type.String({pattern:"^(0|[1-9][0-9]{0,19})$"}),changeset:Type.String({pattern:"^(0|[1-9][0-9]{0,19})$"}),repository:string(),server:string()});
+const side=object({origin:enumOf(["historical","local-snapshot","synthetic-empty"]),selector:nullable(string()),path:nullable(string()),identity:nullable(identity),bytes:uint(),binary:Type.Boolean()});
+const excerpt=object({countBasis:Type.Literal("normalized_diff_utf16"),text:string(20000),observedChars:uint(1060000),sourceChars:uint(20000),returnedChars:uint(20000),omittedChars:uint(1060000),markerChars:uint(59),truncated:Type.Boolean()});
+const comparison=object({atomicSnapshot:Type.Literal(false),kind:enumOf(["revision-to-revision","explicit-revision-to-local","loaded-base-to-local"]),pendingKind:nullable(enumOf(["changed","added","deleted","moved","private","checkedout","copied","replaced"])),left:side,right:side,status:enumOf(["changed","unchanged","binary-different","added-empty"]),changed:Type.Boolean(),binary:Type.Boolean(),comparisonBasis:enumOf(["byte_equality","diff_u"]),hunkCount:uint(),capture:object({diffStdoutBytes:nullable(uint(1048576)),diffExitCode:nullable(uint(1))}),excerpt:nullable(excerpt)});
+const outcome=Type.Union([object({path:string(),sourcePath:nullable(string()),kind:string(32),status:Type.Literal("compared"),comparison}),object({path:string(),sourcePath:nullable(string()),kind:string(32),status:Type.Literal("skipped-directory")}),object({path:string(),sourcePath:nullable(string()),kind:string(32),status:Type.Literal("unavailable"),error})]);
+const collection=object({scope:enumOf(["selected","all-pending"]),requestedPaths:nullable(paths),includePrivate:Type.Boolean(),excludedPrivate:uint(20000),counts:object({parsed:uint(20000),eligible:uint(20000),selected:uint(20),attempted:uint(20),completed:uint(20),failed:uint(20),skipped:uint(20),unattempted:uint(20),limited:uint(20000),returned:uint(20),omitted:uint(20)}),unmatched:Type.Array(string(1024),{maxItems:20}),outcomes:Type.Array(outcome,{maxItems:20})});
+const header={schemaVersion:Type.Literal(1),action:Type.Literal("diff"),provenance,completeness};
+export const diffOutputSchema=Type.Union([
+    object({...header,mode:enumOf(["file","revisions"]),ok:Type.Literal(true),data:comparison}),
+    object({...header,mode:Type.Literal("workspace"),ok:Type.Literal(true),data:collection}),
+    object({...header,mode:Type.Literal("workspace"),ok:Type.Literal(false),data:collection,error}),
+    object({...header,mode:Type.Union([enumOf(["file","revisions","workspace"]),Type.Null()]),ok:Type.Literal(false),error}),
+]);
+export type DiffOutput=Static<typeof diffOutputSchema>;
+export function validateDiffOutput(value:unknown):value is DiffOutput {
+    if(!Check(diffOutputSchema,value)||Buffer.byteLength(JSON.stringify(value),"utf8")>131072)return false;
+    const p=value as DiffOutput;
+    const check=(c:Static<typeof comparison>)=>{
+        if(c.kind==="revision-to-revision"&&(c.pendingKind!==null||c.left.origin!=="historical"||c.right.origin!=="historical"||c.left.identity!==null||c.right.identity!==null))return false;
+        if(c.kind==="explicit-revision-to-local"&&(c.pendingKind!==null||c.left.origin!=="historical"||c.left.identity!==null||c.right.origin!=="local-snapshot"))return false;
+        if(c.kind==="loaded-base-to-local"&&(["added","private"].includes(c.pendingKind??"")?c.left.origin!=="synthetic-empty":c.left.origin!=="historical"||c.left.identity===null))return false;
+        for(const s of [c.left,c.right]){if(s.origin==="historical"&&(!s.selector||!validDiffRevisionsSelector(s.selector))||s.origin!=="historical"&&(s.selector!==null||s.identity!==null)||s.origin==="synthetic-empty"&&(s.bytes!==0||s.binary))return false;}
+        const e=c.excerpt;if(e&&(e.text.length!==e.returnedChars||e.returnedChars!==e.sourceChars+e.markerChars||e.observedChars!==e.sourceChars+e.omittedChars||e.truncated!==(e.omittedChars>0)||e.markerChars!==(e.truncated?59:0)))return false;
+        if(c.binary!==(c.left.binary||c.right.binary)||c.comparisonBasis!==(c.binary?"byte_equality":"diff_u")||(c.excerpt===null)!==c.binary)return false;
+        if(c.status==="changed"&&(!c.changed||c.binary)||c.status==="binary-different"&&(!c.binary||!c.changed)||c.status==="unchanged"&&c.changed||c.status==="added-empty"&&(c.changed||c.pendingKind!=="added"||c.right.bytes))return false;
+        return c.binary?c.hunkCount===0&&c.capture.diffExitCode===null&&c.capture.diffStdoutBytes===null:c.capture.diffExitCode===(c.changed?1:0)&&c.hunkCount>0===c.changed;
+    };
+    if("data"in p){if(p.mode==="workspace"){const c=p.data.counts;if(c.returned!==p.data.outcomes.length||c.returned+c.omitted!==c.selected-c.unattempted||c.completed+c.failed!==c.attempted||c.attempted+c.skipped+c.unattempted!==c.selected||c.selected+c.limited!==c.eligible||c.eligible>c.parsed||p.ok!==(c.failed===0&&c.unattempted===0)||!p.data.outcomes.every(o=>o.status!=="compared"||check(o.comparison)))return false;}else if(!check(p.data)||(p.mode==="revisions")!==(p.data.kind==="revision-to-revision")||p.completeness.read!=="complete"||p.completeness.capture!=="complete"||p.completeness.projection!==!p.data.excerpt?.truncated)return false;}
+    return true;
+}
+export async function executeDiffOutput(args:unknown){
+    let payload:unknown;
+    try{payload=await assembleConsolidatedDiff(args);}catch(e){const mode=(args as {mode?:unknown})?.mode;payload={schemaVersion:1,action:"diff",mode:["file","revisions","workspace"].includes(String(mode))?mode:null,provenance:{source:"plastic",producer:"@aefree/pi-plastic",contentTrust:"external"},ok:false,completeness:{read:"incomplete",capture:"unknown",projection:false},error:diffError(e)};}
+    if(!validateDiffOutput(payload))payload={schemaVersion:1,action:"diff",mode:null,provenance:{source:"plastic",producer:"@aefree/pi-plastic",contentTrust:"external"},ok:false,completeness:{read:"incomplete",capture:"unknown",projection:false},error:{code:"comparison_failed",stage:"producer",message:"The diff producer envelope could not be verified."}};
+    const dto=payload as DiffOutput;
+    const json=(args as {format?:unknown})?.format==="json";
+    let text=JSON.stringify(dto);
+    if(!json){
+        if("data"in dto)text=dto.mode==="workspace"?"## Workspace Diff\n"+(dto.ok?"":"Partial failure: "+dto.error.code+"\n")+JSON.stringify(dto.data.counts)+"\nPrivate excluded: "+dto.data.excludedPrivate+"; unmatched paths: "+dto.data.unmatched.length+"\n"+dto.data.outcomes.map(o=>o.path+": "+o.status+(o.status==="compared"?"\n"+(o.comparison.excerpt?.text??o.comparison.status):o.status==="unavailable"?" ("+o.error.code+")":"")).join("\n\n"):"## Diff\n"+dto.data.status+"\n"+(dto.data.excerpt?.text??"");
+        else text=dto.error.message;
+    }
+    if(text.length>24000)text=json?JSON.stringify({action:"diff",mode:dto.mode,ok:dto.ok,note:"Presentation omitted; use structuredContent for the bounded producer observation."}):text.slice(0,23920)+"\n[Presentation truncated; inspect the structured projection/completeness fields.]";
+    return {content:[{type:"text" as const,text}],details:{},structuredContent:dto,isError:!dto.ok};
+}

package/src/pi/diff-revisions-output.ts

@@ -0,0 +1,55 @@
+import { Type, type Static, type TSchema } from "typebox";
+import { Check } from "typebox/value";
+import { assembleDiffRevisionsObservation, presentDiffRevisions, diffRevisionsPayload, validDiffRevisionsSelector, DiffRevisionsError, DIFF_REVISIONS_FILE_BYTES, DIFF_REVISIONS_MAX_BYTES, DIFF_REVISIONS_EXCERPT_MARKER, type DiffRevisionsArgs, type DiffRevisionsErrorCode, type DiffRevisionsStage } from "../operations/diff-revisions";
+import { getActiveAbortSignal } from "../execution/context";
+const object = <T extends Record<string, TSchema>>(fields: T) => Type.Object(fields, { additionalProperties: false });
+const integer = (max: number) => Type.Integer({ minimum: 0, maximum: max });
+const nullable = <T extends TSchema>(schema: T) => Type.Union([schema, Type.Null()]);
+const common = { schemaVersion: Type.Literal(1), action: Type.Literal("diff-revisions"), provenance: object({ source: Type.Literal("plastic"), producer: Type.Literal("@aefree/pi-plastic"), contentTrust: Type.Literal("external") }) };
+const side = object({ selector: Type.String({ minLength: 1, maxLength: 4096 }), kind: Type.Union([Type.Literal("file-qualified"), Type.Literal("global-revision")]), resolvedIdentity: Type.Null(), bytes: integer(DIFF_REVISIONS_FILE_BYTES), binary: Type.Boolean() });
+export const diffRevisionsOutputSchema = Type.Union([
+    object({ ...common, ok: Type.Literal(true), completeness: object({ read: Type.Literal("complete"), capture: Type.Literal("complete"), projection: Type.Boolean() }), data: object({
+        scope: Type.Literal("explicit_selector_pair"), qualifierVerified: Type.Literal(false), resolvedIdentities: Type.Null(), comparisonKind: Type.Literal("revision-to-revision"), left: side, right: side,
+        status: Type.Union([Type.Literal("changed"),Type.Literal("unchanged"),Type.Literal("binary-different")]), changed: Type.Boolean(), binary: Type.Boolean(), comparisonBasis: Type.Union([Type.Literal("byte_equality"),Type.Literal("diff_u")]),
+        hunkCount: integer(1048576), capture: object({ diffStdoutBytes: nullable(integer(1048576)), diffExitCode: nullable(integer(1)) }),
+        limits: object({ maxChars: Type.Integer({ minimum: 500, maximum: 20000 }), selectorCodeUnits: Type.Literal(4096), materializedBytesPerSide: Type.Literal(4194304), compactUtf8Bytes: Type.Literal(131072) }),
+        excerpt: nullable(object({ countBasis: Type.Literal("normalized_diff_utf16"), text: Type.String({ maxLength: 20000 }), observedChars: integer(1060000), sourceChars: integer(20000), returnedChars: integer(20000), omittedChars: integer(1060000), markerChars: integer(100), truncated: Type.Boolean() })),
+    }) }),
+    object({ ...common, ok: Type.Literal(false), completeness: object({ read: Type.Literal("incomplete"), capture: Type.Literal("unknown"), projection: Type.Literal(false) }), error: object({ code: Type.Union([Type.Literal("invalid_selector"),Type.Literal("invalid_producer_data"),Type.Literal("materialization_failed"),Type.Literal("materialization_limit"),Type.Literal("cleanup_failed"),Type.Literal("invalid_utf8"),Type.Literal("malformed_output"),Type.Literal("command_failed"),Type.Literal("aborted"),Type.Literal("capture_incomplete"),Type.Literal("output_overflow")]), stage: Type.Union([Type.Literal("input"),Type.Literal("left"),Type.Literal("right"),Type.Literal("comparison"),Type.Literal("cleanup"),Type.Literal("producer")]), message: Type.String({ minLength: 1, maxLength: 256 }) }) }),
+]);
+export type DiffRevisionsOutput = Static<typeof diffRevisionsOutputSchema>;
+const failure = (code: DiffRevisionsErrorCode, stage: DiffRevisionsStage): DiffRevisionsOutput => ({ ...{ schemaVersion: 1, action: "diff-revisions", provenance: { source: "plastic", producer: "@aefree/pi-plastic", contentTrust: "external" } } as const, ok: false, completeness: { read: "incomplete", capture: "unknown", projection: false }, error: { code, stage, message: "Historical revision comparison failed (" + code + ", " + stage + "); no verified comparison is available." } });
+export function validateDiffRevisionsOutput(value: unknown): DiffRevisionsOutput {
+    if (!Check(diffRevisionsOutputSchema,value)) return failure("invalid_producer_data","producer");
+    const dto=value as DiffRevisionsOutput;
+    if(dto.ok){
+        const d=dto.data;
+        if([d.left,d.right].some(s=>!validDiffRevisionsSelector(s.selector)||s.kind!==(s.selector.includes("#")?"file-qualified":"global-revision"))
+            || d.binary!==(d.left.binary||d.right.binary) || d.status!==(d.changed?d.binary?"binary-different":"changed":"unchanged")) return failure("invalid_producer_data","producer");
+        if(d.binary){
+            if(d.comparisonBasis!=="byte_equality"||d.excerpt!==null||d.hunkCount!==0||d.capture.diffStdoutBytes!==null||d.capture.diffExitCode!==null||!dto.completeness.projection) return failure("invalid_producer_data","producer");
+        }else{
+            const e=d.excerpt;
+            if(d.comparisonBasis!=="diff_u"||e===null||d.capture.diffStdoutBytes===null||d.capture.diffExitCode!==(d.changed?1:0)
+                ||e.returnedChars!==e.text.length||e.returnedChars> d.limits.maxChars||e.returnedChars!==e.sourceChars+e.markerChars
+                ||e.observedChars!==e.sourceChars+e.omittedChars||e.truncated!==(e.omittedChars>0)||dto.completeness.projection===e.truncated
+                || /[\uD800-\uDFFF]/u.test(e.text)
+                || (e.truncated ? !e.text.endsWith(DIFF_REVISIONS_EXCERPT_MARKER)||e.markerChars!==DIFF_REVISIONS_EXCERPT_MARKER.length : e.markerChars!==0)
+                || (d.changed ? d.hunkCount<1||e.observedChars<1||d.capture.diffStdoutBytes<1 : d.hunkCount!==0||e.observedChars!==0||d.capture.diffStdoutBytes!==0)) return failure("invalid_producer_data","producer");
+        }
+    }
+    if(Buffer.byteLength(JSON.stringify(dto),"utf8")>DIFF_REVISIONS_MAX_BYTES)return failure("output_overflow","producer");
+    return dto;
+}
+export async function executeDiffRevisionsOutput(args: DiffRevisionsArgs){
+    let dto: DiffRevisionsOutput, rawResult: string | undefined;
+    try{
+        const observation=await assembleDiffRevisionsObservation(args);
+        if(getActiveAbortSignal()?.aborted)throw new DiffRevisionsError("aborted","comparison");
+        dto=validateDiffRevisionsOutput(diffRevisionsPayload(observation));
+        if(dto.ok) rawResult=await presentDiffRevisions(observation,args);
+        if(getActiveAbortSignal()?.aborted)throw new DiffRevisionsError("aborted","comparison");
+    }catch(error){dto=failure(error instanceof DiffRevisionsError?error.code:"invalid_producer_data",error instanceof DiffRevisionsError?error.stage:"producer");}
+    dto=validateDiffRevisionsOutput(dto);
+    return { content:[{type:"text" as const,text:dto.ok?rawResult!:dto.error.message}], structuredContent:dto, isError:!dto.ok, details:{exportName:"diffRevisions",rawResult:dto.ok?rawResult:undefined,...(args.workdir?{workdir:args.workdir}:{})} };
+}

package/src/pi/object-delete-output.ts

@@ -0,0 +1,15 @@
+import {Type} from "typebox";import {Check} from "typebox/value";
+import {assembleObjectDeleteReceipt,emptyObjectDeleteData,objectDeleteFailure,objectDeleteArgv,objectDeletePrefix,presentObjectDeleteReceipt,validObjectDeleteOperands,validObjectDeleteText as safeBranchDeleteText,type ObjectDeleteAction,type ObjectDeleteReceipt} from "../operations/object-delete-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=(n=Number.MAX_SAFE_INTEGER)=>Type.Integer({minimum:0,maximum:n}),text=Type.String({minLength:1,maxLength:4096});
+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()}),capture=obj({stdoutBytes:uint(),stderrBytes:uint(),stdoutRetainedBytes:uint(65536),stderrRetainedBytes:uint(16384),truncated:Type.Boolean(),complete:Type.Boolean(),validUtf8:Type.Boolean()});
+function schema<A extends ObjectDeleteAction>(action:A){const request=obj({operands:Type.Array(text,{minItems:1,maxItems:action==="shelveset-delete"?1:256}),repository:action==="shelveset-delete"?Type.Null():nil(text),workdir:text,preflight:Type.Boolean(),format:enm(["text","json"])}),data={requested:nil(request),intendedArgv:Type.Array(Type.String({minLength:1,maxLength:8192}),{minItems:2,maxItems:259}),attempt,capture:nil(capture),observedDeletedObjects:Type.Null(),observedRepositoryIdentity:Type.Null(),scope:Type.Literal("requested-only"),rollback:Type.Literal("not-proven")},header={schemaVersion:Type.Literal(1),action:Type.Literal(action),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)})},error=obj({code:enm(["invalid_request","launch_failed","aborted","uncertain","producer_failed"]),message:Type.String({minLength:1,maxLength:256})});return Type.Unsafe<ObjectDeleteReceipt & {action:A;data:{requested:(ObjectDeleteReceipt["data"]["requested"] & {repository:A extends "shelveset-delete"?null:string|null})|null}}>(Type.Union([obj({...header,ok:Type.Literal(true),outcome:Type.Literal("preflight"),data:obj({...data,effect:Type.Literal("not-attempted")})}),obj({...header,ok:Type.Literal(true),outcome:Type.Literal("command-completed"),data:obj({...data,effect:Type.Literal("not-proven")})}),obj({...header,ok:Type.Literal(false),outcome:Type.Literal("failed"),data:obj({...data,effect:Type.Literal("not-attempted")}),error}),obj({...header,ok:Type.Literal(false),outcome:Type.Literal("uncertain"),data:obj({...data,effect:Type.Literal("uncertain")}),error})]));}
+export const shelvesetDeleteOutputSchema=schema("shelveset-delete"),codeReviewDeleteOutputSchema=schema("code-review-delete");
+export function validateObjectDeleteOutput(v:unknown):v is ObjectDeleteReceipt{if(!v||typeof v!=="object")return false;const dto=v as ObjectDeleteReceipt;if(!["shelveset-delete","code-review-delete"].includes(dto.action)||!Check(dto.action==="shelveset-delete"?shelvesetDeleteOutputSchema:codeReviewDeleteOutputSchema,v)||Buffer.byteLength(JSON.stringify(v),"utf8")>131072)return false;const d=dto.data,r=d.requested,a=d.attempt,c=d.capture;
+ if(r===null){if(JSON.stringify(d.intendedArgv)!==JSON.stringify(objectDeletePrefix(dto.action))||c||a.terminal!=="not-observed"||a.exitCode!==null||a.aborted||a.timedOut||!["not-attempted","unknown"].includes(a.state))return false;}else{if(!validObjectDeleteOperands(dto.action,r.operands)||!safeBranchDeleteText(r.workdir)||r.repository!==null&&!safeBranchDeleteText(r.repository)||Buffer.byteLength(JSON.stringify(r),"utf8")>32768||JSON.stringify(d.intendedArgv)!==JSON.stringify(objectDeleteArgv(dto.action,r)))return false;}
+ 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(!r||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(r?.preflight===true&&(!dto.ok||dto.outcome!=="preflight"||c||a.state!=="not-attempted"||a.terminal!=="not-observed"||a.exitCode!==null||a.aborted||a.timedOut))return false;
+ if(dto.ok&&dto.outcome==="preflight"&&!r?.preflight)return false;if(dto.ok&&dto.outcome==="command-completed"&&(!r||r.preflight||!c?.complete||a.state!=="started"||a.exitCode!==0))return false;
+ if(!dto.ok){if(c?.complete&&a.exitCode===0||dto.error.code==="uncertain"&&(dto.outcome!=="uncertain"||d.effect!=="uncertain"||!["started","unknown"].includes(a.state)))return false;if(!safeBranchDeleteText(dto.error.message)||dto.outcome==="uncertain"&&!["started","unknown"].includes(a.state)||dto.outcome==="failed"&&!["not-attempted","not-started"].includes(a.state))return false;if(dto.error.code==="invalid_request"&&(r!==null||c||a.state!=="not-attempted"||a.aborted)||dto.error.code==="aborted"&&!a.aborted||dto.error.code==="launch_failed"&&!["not-attempted","not-started"].includes(a.state))return false;}return true;}
+export async function executeObjectDeleteOutput(action:ObjectDeleteAction,args:unknown){let dto=await assembleObjectDeleteReceipt(action,args);const valid:boolean=validateObjectDeleteOutput(dto)&&dto.action===action;if(!valid){const possible=["started","unknown"].includes(dto.data.attempt.state),d=emptyObjectDeleteData(action);if(possible){d.attempt.state="unknown";d.effect="uncertain";}dto=objectDeleteFailure(action,d,"producer_failed","Object-delete receipt validation failed; effects remain possible, no automatic retry.");if(!validateObjectDeleteOutput(dto))throw Error("Safe object-delete receipt unavailable.");}return {content:[{type:"text" as const,text:presentObjectDeleteReceipt(dto)}],details:{},structuredContent:dto,isError:!dto.ok};}

package/src/pi/object-write-output.ts

@@ -0,0 +1,54 @@
+import { Type } from "typebox";
+import { Check } from "typebox/value";
+import { assembleObjectWriteReceipt, emptyObjectWriteData, objectWriteFailure, objectWriteArgv, objectWritePrefix, parseObjectWriteIdentity, presentObjectWriteReceipt, validObjectWriteRequest, validWriteText, OBJECT_WRITE_ACTIONS, type ObjectWriteAction, type ObjectWriteReceipt } from "../operations/object-write-receipt";
+const obj=(p:Record<string,any>)=>Type.Object(p,{additionalProperties:false}),enm=(v:readonly 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}),text=Type.String({minLength:1,maxLength:4096}),optionalText=nil(Type.String({maxLength:4096}));
+const common={workdir:text,preflight:Type.Boolean(),output:enm(["text","json"])},paths=nil(Type.Array(text,{maxItems:256}));
+const requests={
+    "shelveset-create":obj({...common,paths,comment:optionalText,commentsFile:optionalText,all:Type.Boolean(),dependencies:Type.Boolean(),summaryFormat:Type.Boolean()}),
+    "shelveset-apply":obj({...common,shelveset:text,changePaths:paths,preview:Type.Boolean(),dontCheckout:Type.Boolean(),comparisonMethod:nil(enm(["ignoreeol","ignorewhitespaces","ignoreeolandwhitespaces","recognizeall"]))}),
+    "code-review-create":obj({...common,target:text,title:text,status:optionalText,assignee:optionalText,repository:optionalText,format:optionalText}),
+    "code-review-update":obj({...common,id:text,status:optionalText,assignee:optionalText,repository:optionalText}),
+};
+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()}),capture=obj({stdoutBytes:uint(),stderrBytes:uint(),stdoutRetainedBytes:uint(65536),stderrRetainedBytes:uint(16384),truncated:Type.Boolean(),complete:Type.Boolean(),validUtf8:Type.Boolean()});
+function schema<A extends ObjectWriteAction>(action:A) {
+    const data=obj({requested:nil(requests[action]),intendedArgv:Type.Array(Type.String({minLength:1,maxLength:8192}),{minItems:1,maxItems:263}),attempt,capture:nil(capture),commandOutput:nil(obj({kind:Type.Literal("opaque-command-output"),text:Type.String({maxLength:65536})})),observedCreatedIdentity:nil(obj({kind:enm(["shelveset","code-review"]),value:text,basis:enm(["default-scalar","summary-scalar"])})),observedAppliedItems:Type.Null(),observedUpdatedState:Type.Null(),observedRepositoryIdentity:Type.Null(),scope:Type.Literal("requested-only"),rollback:Type.Literal("not-proven"),effect:enm(["not-attempted","not-proven","identity-emitted","uncertain"])});
+    const header={schemaVersion:Type.Literal(1),action:Type.Literal(action),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};
+    return Type.Unsafe<ObjectWriteReceipt<A>>(Type.Union([obj({...header,ok:Type.Literal(true),outcome:enm(["preflight","command-completed"])}),obj({...header,ok:Type.Literal(false),outcome:enm(["failed","uncertain"]),error:obj({code:enm(["invalid_request","editor_configured","launch_failed","aborted","uncertain","producer_failed"]),message:Type.String({minLength:1,maxLength:256})})})]));
+}
+export const shelvesetCreateOutputSchema=schema("shelveset-create"),shelvesetApplyOutputSchema=schema("shelveset-apply"),codeReviewCreateOutputSchema=schema("code-review-create"),codeReviewUpdateOutputSchema=schema("code-review-update");
+export const objectWriteSchemas={"shelveset-create":shelvesetCreateOutputSchema,"shelveset-apply":shelvesetApplyOutputSchema,"code-review-create":codeReviewCreateOutputSchema,"code-review-update":codeReviewUpdateOutputSchema};
+export function validateObjectWriteOutput(v:unknown):v is ObjectWriteReceipt {
+    if(!v||typeof v!=="object")return false;const dto=v as ObjectWriteReceipt;
+    if(!OBJECT_WRITE_ACTIONS.includes(dto.action)||!Check(objectWriteSchemas[dto.action],v)||Buffer.byteLength(JSON.stringify(v),"utf8")>524288)return false;
+    const d=dto.data,r=d.requested,a=d.attempt,c=d.capture,o=d.commandOutput,id=d.observedCreatedIdentity;
+    if(dto.completeness.capture!==(c?c.complete?"complete":"incomplete":"unknown"))return false;
+    if(r===null) {if(JSON.stringify(d.intendedArgv)!==JSON.stringify(objectWritePrefix(dto.action))||c||o||id||a.terminal!=="not-observed"||a.exitCode!==null||a.aborted||a.timedOut||!["not-attempted","unknown"].includes(a.state)||dto.ok)return false;}
+    else if(!validObjectWriteRequest(dto.action,r)||JSON.stringify(d.intendedArgv)!==JSON.stringify(objectWriteArgv(dto.action,r)))return false;
+    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(!r||c.stdoutRetainedBytes>c.stdoutBytes||c.stderrRetainedBytes>c.stderrBytes)return false;
+        if(c.truncated!==(c.stdoutBytes>65536||c.stderrBytes>16384))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;
+    }
+    const completed=!!c?.complete&&a.state==="started"&&a.exitCode===0;
+    if(o!==null) {if(!r||!completed||/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(o.text)||Buffer.byteLength(o.text,"utf8")!==c!.stdoutBytes||JSON.stringify(id)!==JSON.stringify(parseObjectWriteIdentity(dto.action,r,o.text)))return false;}
+    else if(id!==null||completed)return false;
+    if(d.effect!==(id?"identity-emitted":dto.ok&&dto.outcome==="command-completed"?"not-proven":["started","unknown"].includes(a.state)?"uncertain":"not-attempted"))return false;
+    if(r?.preflight)return dto.ok&&dto.outcome==="preflight"&&a.state==="not-attempted"&&a.terminal==="not-observed"&&a.exitCode===null&&!a.aborted&&!a.timedOut&&!c&&!o&&!id;
+    if(dto.ok)return dto.outcome==="command-completed"&&r!==null&&!r.preflight&&completed&&c!.stderrBytes===0;
+    if(dto.outcome!==(["started","unknown"].includes(a.state)?"uncertain":"failed")||!validWriteText(dto.error.message))return false;
+    if(completed&&c!.stderrBytes===0)return false;
+    if(dto.error.code==="invalid_request"&&(r!==null||c||a.state!=="not-attempted"||a.aborted)||dto.error.code==="aborted"&&!a.aborted||dto.error.code==="launch_failed"&&!["not-attempted","not-started"].includes(a.state)||dto.error.code==="uncertain"&&!['started','unknown'].includes(a.state))return false;
+    if(dto.error.code==="editor_configured"&&(dto.action!=="shelveset-create"||r===null||(r as any).comment!==null||(r as any).commentsFile!==null||a.state!=="not-attempted"||c||o||id))return false;
+    return true;
+}
+export async function executeObjectWriteOutput(a:ObjectWriteAction,args:unknown) {
+    let dto=await assembleObjectWriteReceipt(a,args);
+    if(!validateObjectWriteOutput(dto)||dto.action!==a) {
+        const d=emptyObjectWriteData(a);d.attempt.state="unknown";d.effect="uncertain";
+        dto=objectWriteFailure(a,d,"producer_failed","Object-write receipt invalid; earlier creation/application/update effects may exist. No automatic retry or verification.");
+        if(!validateObjectWriteOutput(dto))throw Error("Safe object-write receipt unavailable; earlier effects may exist.");
+    }
+    return {content:[{type:"text" as const,text:presentObjectWriteReceipt(dto)}],details:{},structuredContent:dto,isError:!dto.ok};
+}

package/src/pi/patch-output.ts

@@ -0,0 +1,69 @@
+import { Type } from "typebox";
+import { Check } from "typebox/value";
+import { createHash } from "node:crypto";
+import { isAbsolute, resolve } from "node:path";
+import { assemblePatchReceipt, emptyPatchData, patchFailure, patchReceiptArgv, presentPatchReceipt, validPatchRequest, PATCH_FILE_MAX_BYTES, PATCH_RECEIPT_MAX_BYTES, type PatchReceipt } from "../operations/patch-receipt";
+const obj=(p:Record<string,any>)=>Type.Object(p,{additionalProperties:false});
+const 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}),text=Type.String({minLength:1,maxLength:8192});
+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 artifact=obj({bytes:uint(PATCH_FILE_MAX_BYTES),sha256:Type.String({pattern:"^[a-f0-9]{64}$"}),utf8:Type.Boolean(),empty:Type.Boolean(),binaryLimited:Type.Boolean(),totalChars:nil(uint(PATCH_FILE_MAX_BYTES)),truncated:Type.Boolean(),content:nil(Type.String({maxLength:60500}))});
+const request=obj({source:text,destination:nil(text),output:nil(text),toolPath:nil(text),clean:Type.Boolean(),integration:Type.Boolean(),workdir:text,preflight:Type.Boolean(),format:enm(["text","json"])});
+const data=obj({requested:nil(request),resolved:nil(obj({source:text,destination:nil(text),toolPath:text,output:nil(text)})),intendedArgv:Type.Array(text,{minItems:1,maxItems:7}),attempt,capture:nil(capture),artifact:nil(artifact),publication:enm(["not-requested","not-published","published","unknown"]),cleanup:enm(["not-created","completed","failed","retained","unknown"]),retainedStagingDirectory:nil(text),effect:enm(["not-attempted","unverified","artifact-observed","published"]),workspaceEffects:Type.Literal("unverified"),moveRepresentation:Type.Literal("backend-determined")});
+const header={schemaVersion:Type.Literal(1),action:Type.Literal("patch"),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};
+export const patchOutputSchema=Type.Unsafe<PatchReceipt>(Type.Union([obj({...header,ok:Type.Literal(true),outcome:enm(["preflight","generated","empty"])}),obj({...header,ok:Type.Literal(false),outcome:enm(["failed","uncertain"]),error:obj({code:enm(["invalid_request","setup_failed","command_failed","uncertain","backend_incompatible","artifact_failed","publication_failed","cleanup_failed","producer_failed"]),message:Type.String({minLength:1,maxLength:256})})})]));
+const safe=(s:string)=>s.trim().length>0&&!/[\u0000-\u001f\u007f-\u009f]/.test(s);
+function resolvedSelector(requested:string,observed:string) {const s=requested.trim();return observed===s||/^br:\/.+/i.test(s)&&!s.includes("@")&&observed.startsWith(s+"@")&&observed.slice(s.length+1).split("@").every(p=>p.trim().length>0&&p===p.trim());}
+export function validatePatchOutput(v:unknown):v is PatchReceipt {
+    if(!Check(patchOutputSchema,v)||Buffer.byteLength(JSON.stringify(v),"utf8")>PATCH_RECEIPT_MAX_BYTES)return false;
+    const dto=v as PatchReceipt,d=dto.data,r=d.requested,z=d.resolved,a=d.attempt,c=d.capture,f=d.artifact;
+    if(dto.completeness.capture!==(c?c.complete?"complete":"incomplete":"unknown"))return false;
+    if(r===null) {
+        if(z||c||f||JSON.stringify(d.intendedArgv)!=='["patch"]'||d.retainedStagingDirectory!==null||a.terminal!=="not-observed"||a.exitCode!==null||a.aborted||a.timedOut)return false;
+        if(a.state==="not-attempted")return !dto.ok&&dto.outcome==="failed"&&dto.error.code==="invalid_request"&&d.effect==="not-attempted"&&d.cleanup==="not-created"&&d.publication==="not-requested";
+        return !dto.ok&&dto.outcome==="uncertain"&&dto.error.code==="producer_failed"&&a.state==="unknown"&&d.effect==="unverified"&&d.cleanup==="unknown"&&d.publication==="unknown";
+    }
+    if(!validPatchRequest(r))return false;
+    if(z) {
+        if(!Object.values(z).every(s=>s===null||safe(s))||!resolvedSelector(r.source,z.source)||(r.destination===null?z.destination!==null:z.destination===null||!resolvedSelector(r.destination,z.destination))||JSON.stringify(d.intendedArgv)!==JSON.stringify(patchReceiptArgv(r,z)))return false;
+        if(r.toolPath!==null&&z.toolPath!==r.toolPath.trim()||r.output===null&&z.output!==null||r.output!==null&&z.output!==(isAbsolute(r.output)?r.output:resolve(r.workdir,r.output)))return false;
+        const tails=[r.source,r.destination].map((s,i)=>s!==null&&/^br:\/.+/i.test(s.trim())&&!s.includes("@")?(i===0?z.source:z.destination)!.slice(s.trim().length):null).filter(s=>s!==null);
+        if(tails.some(t=>t!==tails[0]))return false;
+    } else if(c||f||JSON.stringify(d.intendedArgv)!=='["patch"]'||a.state!=="not-attempted"||d.cleanup!=="not-created")return false;
+    if(a.exitCode!==null&&a.terminal!=="observed"||["not-attempted","not-started"].includes(a.state)&&(a.exitCode!==null||a.terminal!=="not-observed")||a.state==="not-attempted"&&a.timedOut)return false;
+    if(c) {
+        if(!z||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(dto.completeness.capture!==(c?c.complete?"complete":"incomplete":"unknown"))return false;
+    if((d.retainedStagingDirectory!==null)!==["failed","retained"].includes(d.cleanup)||["failed","retained"].includes(d.cleanup)&&!safe(d.retainedStagingDirectory!))return false;
+    if(d.cleanup==="retained"&&(a.terminal==="observed"&&!a.aborted&&!a.timedOut||!["started","unknown"].includes(a.state)))return false;
+    if(f) {
+        if(f.utf8&&(f.totalChars===null||f.totalChars>f.bytes||f.bytes>3*f.totalChars))return false;
+        if(!c?.complete||a.state!=="started"||a.exitCode!==0||c.stderrBytes!==0||f.empty!==(f.bytes===0)||!f.utf8&&!f.binaryLimited||!f.utf8&&(f.content!==null||f.totalChars!==null||f.truncated)||f.utf8&&f.totalChars===null)return false;
+        if(r.output!==null&&(f.content!==null||f.truncated)||r.output===null&&f.utf8&&f.content===null)return false;
+        if(r.output===null&&f.utf8) {
+            if(f.truncated!==(f.totalChars!>60000))return false;
+            if(!f.truncated&&(f.totalChars!==f.content!.length||f.bytes!==Buffer.byteLength(f.content!,"utf8")||f.sha256!==createHash("sha256").update(f.content!).digest("hex")))return false;
+            if(f.truncated&&f.content!.length<=60000)return false;
+        }
+        if(f.empty&&(!f.utf8||f.totalChars!==0||f.sha256!==createHash("sha256").update("").digest("hex")))return false;
+    }
+    if(d.publication==="published"&&(!f||f.empty||r.output===null||d.effect!=="published")||d.publication!=="published"&&d.effect==="published")return false;
+    if(d.publication!=="published"&&d.publication!==(r.output===null?"not-requested":"not-published"))return false;
+    if(d.effect!==(d.publication==="published"?"published":f?"artifact-observed":["started","unknown"].includes(a.state)?"unverified":"not-attempted"))return false;
+    if(r.preflight)return !c&&!f&&a.state==="not-attempted"&&!a.aborted&&d.cleanup==="not-created"&&(dto.ok?dto.outcome==="preflight"&&!!z:dto.outcome==="failed"&&dto.error.code==="setup_failed");
+    if(dto.ok)return !!z&&!!f&&d.cleanup==="completed"&&(dto.outcome==="empty"?f.empty:dto.outcome==="generated"&&!f.empty)&&(r.output===null||d.publication==="published");
+    if(dto.outcome!==(["started","unknown"].includes(a.state)&&!f?"uncertain":"failed"))return false;
+    if(dto.error.code==="invalid_request"||dto.error.code==="setup_failed"&&(a.state!=="not-attempted"||c||f)||dto.error.code==="uncertain"&&!["started","unknown"].includes(a.state)||["publication_failed","cleanup_failed"].includes(dto.error.code)&&!f)return false;
+    return true;
+}
+export async function executePatchOutput(args:unknown) {
+    let dto=await assemblePatchReceipt(args);
+    if(!validatePatchOutput(dto)) {
+        const d=emptyPatchData();d.attempt.state="unknown";d.effect="unverified";d.publication="unknown";d.cleanup="unknown";
+        dto=patchFailure(d,"producer_failed","Patch receipt invalid; generation/publication and staging effects may already exist. No automatic retry or cleanup.");
+        if(!validatePatchOutput(dto))throw new Error("Safe patch receipt unavailable; earlier effects may exist.");
+    }
+    return {content:[{type:"text" as const,text:presentPatchReceipt(dto)}],details:{},structuredContent:dto,isError:!dto.ok};
+}