@aefree/pi-plastic 0.7.6 → 0.8.1

package/src/operations/switch-receipt.ts

@@ -0,0 +1,85 @@
+import { resolve } from "node:path";
+import { captureSwitchCommand, emptySwitchAttempt, type SwitchCommandObservation } from "../execution/switch-command";
+import { compareSwitchTarget, parseSwitchTarget, parseSwitchLoadedBranch, parseSwitchPending, switchPendingArgv, safeSwitchValue, admittedSwitchNoChanges, type SwitchReceipt, type SwitchRequest, type SwitchData, type SwitchStep, type SwitchStepName } from "../domain/switch-contract";
+import { buildSwitchPendingProfile, canSwitchDirectWithPrivateOnlyPending, isSwitchBringBlockedForUnattended } from "../domain/switch-policy";
+export { presentSwitchReceipt } from "../presentation/switch-results";
+export { safeSwitchValue, compareSwitchTarget, parseSwitchTarget } from "../domain/switch-contract";
+export type { SwitchReceipt, SwitchStep, SwitchData, SwitchAttempt, SwitchCapture, SwitchSummary, SwitchBranchObservation } from "../domain/switch-contract";
+export function validateSwitchRequest(input: unknown): asserts input is SwitchRequest {
+    if (!input || typeof input !== "object" || Array.isArray(input)) throw Error("Switch request must be an object.");
+    const r = input as Record<string, unknown>;
+    if (Object.keys(r).some(k => !["branch", "pendingChanges", "preflight", "format", "workdir"].includes(k)) || !safeSwitchValue(r.branch) || !parseSwitchTarget(r.branch)) throw Error("Provide a bounded hierarchical branch selector with preserved complete qualification.");
+    if (r.workdir !== undefined && !safeSwitchValue(r.workdir) || r.pendingChanges !== undefined && !["shelve", "bring", "cancel"].includes(r.pendingChanges as string) || r.format !== undefined && !["text", "json"].includes(r.format as string) || r.preflight !== undefined && typeof r.preflight !== "boolean") throw Error("Switch options are unsupported or invalid.");
+}
+export async function assembleSwitchReceipt(input: unknown): Promise<SwitchReceipt> {
+    const data: SwitchData = { requestedTarget: null, workdir: null, pendingPolicy: "cancel", defaultedPolicy: true, preflight: false, strategy: "unresolved", wouldRun: false, plannedMutations: [], unattemptedMutations: [], steps: [], branchBefore: null, branchAfter: null, pendingBefore: null, pendingRecovery: null, observedShelveset: null, usedNoChangesShelveRecovery: false, targetVerification: "unverified", serverAliasEquivalence: "unverified", filePreservation: "unverified", xlinkEffects: "unverified", effect: "not-attempted" };
+    let stage: "input" | SwitchStepName | "policy" | "producer" = "input";
+    const finish = (outcome: SwitchReceipt["outcome"], code: Extract<SwitchReceipt, {ok:false}>["error"]["code"] = "observation_failed", message = "Switch evidence is unavailable; do not retry automatically."): SwitchReceipt => {
+        const mutations = data.steps.filter(s => s.name === "shelve" || s.name === "switch");
+        data.effect = mutations.some(s => s.effect === "uncertain") ? "uncertain" : mutations.some(s => s.effect === "command-completed") ? "command-completed" : "not-attempted";
+        data.unattemptedMutations = data.plannedMutations.filter(name => !mutations.some(s => s.name === name && s.attempt.state !== "not-attempted"));
+        const reads = data.steps.filter(s => s.name !== "shelve" && s.name !== "switch");
+        return { schemaVersion: 1, action: "switch-branch", provenance: { source: "plastic", producer: "@aefree/pi-plastic", contentTrust: "external" }, sourceAdmission: "windows-cm11.0.16.10371-observed", completeness: { read: reads.length ? reads.every(s => s.evidence === "admitted") ? "complete" : "incomplete" : "unknown", capture: data.steps.length ? data.steps.every(s => s.capture.complete) ? "complete" : "incomplete" : "unknown", projection: true }, data, ok: ["preflight", "already-loaded", "switched"].includes(outcome), outcome, ...(["preflight", "already-loaded", "switched"].includes(outcome) ? {} : {error:{code,stage,message}}) } as SwitchReceipt;
+    };
+    const normal = (o: SwitchCommandObservation) => !o.failed && o.capture.complete && o.attempt.state === "started" && o.attempt.terminal === "observed" && !o.attempt.aborted && !o.attempt.timedOut;
+    const observe = async (name: SwitchStepName, argv: string[]) => {
+        stage = name;
+        const mutation = name === "shelve" || name === "switch";
+        const s: SwitchStep = { name, argv: [...argv], attempt: { ...emptySwitchAttempt(), state:"unknown" }, capture: { stdoutBytes:0,stderrBytes:0,stdoutRetainedBytes:0,stderrRetainedBytes:0,truncated:false,complete:false,validUtf8:false }, evidence:"unadmitted", effect:mutation?"uncertain":"not-attempted", branch:null,summary:null,records:0 };
+        data.steps.push(s);
+        const o = await captureSwitchCommand(argv, data.workdir!);
+        s.attempt = o.attempt; s.capture = o.capture;
+        if (mutation) {
+            s.effect = ["not-attempted","not-started"].includes(o.attempt.state) ? "not-attempted" : "uncertain";
+            if (normal(o) && o.attempt.exitCode === 0 && !o.capture.stderrBytes) { s.effect="command-completed";s.evidence="terminal-only"; }
+        } else if (normal(o) && o.attempt.exitCode === 0 && !o.capture.stderrBytes) {
+            if (name === "branch-before" || name === "branch-after") { s.branch=parseSwitchLoadedBranch(o.stdout!);s.records=s.branch?1:0; }
+            else { const p=parseSwitchPending(o.stdout!,data.workdir!);s.summary=p.summary;s.records=p.records; }
+            if(s.branch || s.summary) { s.evidence="admitted";s.effect="read-observed"; }
+        }
+        return { o,s };
+    };
+    try {
+        validateSwitchRequest(input);
+        const r=input;
+        const cwd=resolve(r.workdir??process.cwd());if(!safeSwitchValue(cwd))return finish("failed","invalid_request","Resolved workdir exceeds the bound.");
+        Object.assign(data,{requestedTarget:r.branch,workdir:cwd,pendingPolicy:r.pendingChanges??"cancel",defaultedPolicy:r.pendingChanges===undefined,preflight:r.preflight??false});
+        if(process.platform!=="win32")return finish("failed","unsupported_source","Switch source is admitted only on observed Windows/client configuration.");
+        const before=await observe("branch-before",["status"]);data.branchBefore=before.s.branch;
+        if(!data.branchBefore)return finish("failed");
+        const pending=await observe("pending-before",switchPendingArgv);data.pendingBefore=pending.s.summary;
+        if(!data.pendingBefore)return finish("failed");
+        stage="policy";
+        const verification=compareSwitchTarget(data.branchBefore,r.branch);
+        if(verification!=="unverified") { data.strategy="already-on-target-branch";data.targetVerification=verification;return finish(data.preflight?"preflight":"already-loaded"); }
+        const profile=buildSwitchPendingProfile({...data.pendingBefore,privatePaths:[]});
+        if(!profile.hasPendingChanges)data.strategy="silent-noinput";
+        else if(canSwitchDirectWithPrivateOnlyPending(data.pendingPolicy,data.defaultedPolicy,profile))data.strategy="direct-switch-private-only";
+        else if(isSwitchBringBlockedForUnattended(data.pendingPolicy,profile)) { data.strategy="blocked-bring-tracked-pending";return finish(data.preflight?"preflight":"blocked","policy_blocked","Tracked pending bring requires interactive prompts and is blocked."); }
+        else if(data.pendingPolicy==="cancel") { data.strategy="cancel-with-pending";return finish(data.preflight?"preflight":"canceled","policy_canceled","Switch canceled by pending-change policy; no mutation was attempted."); }
+        else data.strategy="shelve-then-switch-noinput";
+        data.plannedMutations=data.strategy==="shelve-then-switch-noinput"?["shelve","switch"]:["switch"];data.wouldRun=true;
+        if(data.preflight)return finish("preflight");
+        if(data.strategy==="shelve-then-switch-noinput") {
+            const shelf=await observe("shelve",["shelveset","create","--all",`-c=Auto-shelve before switch to ${r.branch}`]);
+            if(shelf.s.effect!=="command-completed") {
+                if(!normal(shelf.o) || shelf.o.attempt.exitCode!==1 || !admittedSwitchNoChanges(shelf.o.stdout!,shelf.o.stderr!,cwd))return finish(data.effect==="not-attempted"&&["not-attempted","not-started"].includes(shelf.s.attempt.state)?"failed":"uncertain","mutation_failed");
+                shelf.s.evidence="eligible-no-changes";
+                const recovery=await observe("pending-recovery",switchPendingArgv);data.pendingRecovery=recovery.s.summary;
+                if(!data.pendingRecovery || data.pendingRecovery.tracked!==0)return finish("uncertain","observation_failed","Shelve failed; recovery did not prove absence of tracked pending. No switch was attempted.");
+                data.usedNoChangesShelveRecovery=true;
+            }
+        }
+        const switched=await observe("switch",["switch","--silent","--noinput",r.branch]);
+        if(switched.s.effect!=="command-completed")return finish(["not-attempted","not-started"].includes(switched.s.attempt.state)?"failed":"uncertain","mutation_failed");
+        const after=await observe("branch-after",["status"]);data.branchAfter=after.s.branch;
+        if(!data.branchAfter)return finish("command-completed-unverified","target_unverified","Switch command completed but loaded target could not be observed. Earlier effects remain; do not retry automatically.");
+        data.targetVerification=compareSwitchTarget(data.branchAfter,r.branch);
+        if(data.targetVerification==="unverified")return finish("command-completed-unverified","target_unverified","Switch command completed; requested target identity or full qualifier spelling remains unverified. Alias equivalence is not inferred.");
+        // Eligible failed shelving remains uncertain preservation, even after a verified switch.
+        if(data.usedNoChangesShelveRecovery) { stage="shelve";return finish("uncertain","mutation_failed","Loaded target observed after eligible recovery, but failed shelving did not prove preservation or absence of earlier effects."); }
+        return finish("switched");
+    } catch {
+        return finish(data.steps.some(s=>(s.name==="shelve"||s.name==="switch")&&!["not-attempted","not-started"].includes(s.attempt.state))?"uncertain":"failed",stage==="input"?"invalid_request":"producer_failed",stage==="input"?"Switch request could not be admitted.":"Switch producer failed; inspect recorded earlier effects before another attempt.");
+    }
+}

package/src/operations/switch.ts

@@ -0,0 +1,25 @@
+import { isSameBranchSpec, normalizeBranchSpecForComparison, assertWorkspaceOnBranch } from "../domain/branches";
+import { toLegacyPendingSummary, buildSwitchPendingProfile, isSwitchBringBlockedForUnattended, canSwitchDirectWithPrivateOnlyPending } from "../domain/switch-policy";
+export { toLegacyPendingSummary, createCanceledSwitchOutcome, buildSwitchPendingProfile, isSwitchBringBlockedForUnattended, canSwitchDirectWithPrivateOnlyPending } from "../domain/switch-policy";
+export type { SwitchPendingProfile, CanceledSwitchOutcome } from "../domain/switch-policy";
+import { assembleSwitchReceipt, presentSwitchReceipt } from "./switch-receipt";
+import { tool } from "../tool-definition";
+import { outputFormatArg } from "../presentation/results";
+import { workdirArg } from "./arguments";
+export const __plasticSwitchInternals = { toLegacyPendingSummary, normalizeBranchSpecForComparison, isSameBranchSpec, assertWorkspaceOnBranch, buildSwitchPendingProfile, isSwitchBringBlockedForUnattended, canSwitchDirectWithPrivateOnlyPending };
+export const switchBranch = tool({
+    description: "Switch the Plastic SCM workspace to a branch (cm switch), handling pending changes when needed.",
+    args: {
+        branch: tool.schema.string().min(1).describe("Branch name or spec selected from the current repository convention."),
+        pendingChanges: tool.schema.enum(["shelve", "bring", "cancel"]).optional().describe("How to handle pending changes when switching branches. Defaults to cancel. In unattended mode, bring is blocked only when tracked pending changes exist."),
+        preflight: tool.schema.boolean().optional().describe("Preview switch strategy without executing switch."),
+        format: outputFormatArg,
+        workdir: workdirArg,
+    },
+    async execute(args) {
+        const dto = await assembleSwitchReceipt(args);
+        // Policy cancellation also rejects here: a compound caller must not continue into target-side mutations.
+        if (!dto.ok && !args.preflight) throw new Error(dto.error.message);
+        return presentSwitchReceipt(dto,args.format);
+    },
+});

package/src/operations/undo-receipt.ts

@@ -0,0 +1,37 @@
+import { captureUndoCommand, emptyUndoAttempt } from "../execution/undo-command";
+import { UNDO_COMMAND, safeUndoText, validUndoOperands, type UndoData, type UndoError, type UndoReceipt } from "../domain/undo-contract";
+export { UNDO_COMMAND, safeUndoText, validUndoOperands } from "../domain/undo-contract";
+export type { UndoData, UndoError, UndoReceipt, UndoAttempt, UndoCapture } from "../domain/undo-contract";
+export { presentUndoReceipt } from "../presentation/undo-results";
+export function emptyUndoData(): UndoData {
+    return { intendedArgv: [UNDO_COMMAND], requestedOperandCount: null, workingDirectory: null, attempt: emptyUndoAttempt(), capture: null, observedWorkspaceIdentity: null, observedUndoneItems: null, verification: "unverified", effect: "not-attempted" };
+}
+function undoHeader(data: UndoData) {
+    return { schemaVersion: 1 as const, action: "undo" as const, provenance: { source: "plastic" as const, producer: "@aefree/pi-plastic" as const, contentTrust: "external" as const }, completeness: { capture: data.capture ? data.capture.complete ? "complete" as const : "incomplete" as const : "unknown" as const, projection: true as const }, data };
+}
+export function undoFailure(data: UndoData, code: UndoError["code"], message: string): UndoReceipt {
+    return { ...undoHeader(data), ok: false, outcome: data.effect === "uncertain" ? "uncertain" : "failed", error: { code, message } };
+}
+export async function assembleUndoReceipt(args: unknown): Promise<UndoReceipt> {
+    const data = emptyUndoData(); let dispatched = false;
+    try {
+        if (!args || typeof args !== "object" || Array.isArray(args) || Object.keys(args).some(key => key !== "workdir" && key !== "paths")) return undoFailure(data, "invalid_request", "Undo accepts paths and workdir only; preview and extra options are unsupported.");
+        const input = args as Record<string, unknown>;
+        const cwd = input.workdir === undefined ? process.cwd() : input.workdir;
+        if (!safeUndoText(cwd)) return undoFailure(data, "invalid_request", "Working directory must be nonblank bounded text without controls or invalid Unicode.");
+        const paths = Array.isArray(input.paths) && input.paths.length <= 256 ? Array.from(input.paths) : input.paths;
+        if (!validUndoOperands(paths)) return undoFailure(data, "invalid_request", "Provide 1–256 bounded path operands; CLI options, filters and hyphen-leading sentinels are rejected, aggregate UTF8 limit 32768 bytes.");
+        data.workingDirectory = cwd; data.intendedArgv = [UNDO_COMMAND, ...paths]; data.requestedOperandCount = paths.length; dispatched = true;
+        const observation = await captureUndoCommand([...data.intendedArgv], cwd);
+        data.attempt = observation.attempt; data.capture = observation.capture;
+        if (observation.capture.complete && !observation.failed && observation.attempt.state === "started" && observation.attempt.exitCode === 0) {
+            data.effect = "not-proven";
+            return { ...undoHeader(data), ok: true, outcome: "command-completed" };
+        }
+        data.effect = ["started", "unknown"].includes(data.attempt.state) ? "uncertain" : "not-attempted";
+        return undoFailure(data, data.attempt.aborted ? "aborted" : data.effect === "uncertain" ? "uncertain" : "launch_failed", data.effect === "uncertain" ? "Undo completion is not proven; partial undone-item or workspace effects may exist." : "Undo did not establish a process start.");
+    } catch {
+        if (dispatched) { data.attempt = { ...emptyUndoAttempt(), state: "unknown" }; data.capture = null; data.effect = "uncertain"; }
+        return undoFailure(data, "producer_failed", "Undo observation failed; no rollback or safe retry is proven.");
+    }
+}

package/src/operations/update-receipt.ts

@@ -0,0 +1,35 @@
+import { captureUpdateCommand, emptyUpdateAttempt } from "../execution/update-command";
+import { UPDATE_ARGV, safeUpdateText, type UpdateData, type UpdateError, type UpdateReceipt } from "../domain/update-contract";
+export { UPDATE_ARGV, safeUpdateText } from "../domain/update-contract";
+export type { UpdateData, UpdateError, UpdateReceipt, UpdateAttempt, UpdateCapture } from "../domain/update-contract";
+export { presentUpdateReceipt } from "../presentation/update-results";
+export function emptyUpdateData(): UpdateData {
+    return { intendedArgv: [...UPDATE_ARGV], workingDirectory: null, attempt: emptyUpdateAttempt(), capture: null, observedWorkspaceIdentity: null, observedChanges: null, verification: "unverified", effect: "not-attempted" };
+}
+function updateHeader(data: UpdateData) {
+    return { schemaVersion: 1 as const, action: "update" as const, provenance: { source: "plastic" as const, producer: "@aefree/pi-plastic" as const, contentTrust: "external" as const }, completeness: { capture: data.capture ? data.capture.complete ? "complete" as const : "incomplete" as const : "unknown" as const, projection: true as const }, data };
+}
+export function updateFailure(data: UpdateData, code: UpdateError["code"], message: string): UpdateReceipt {
+    return { ...updateHeader(data), ok: false, outcome: data.effect === "uncertain" ? "uncertain" : "failed", error: { code, message } };
+}
+export async function assembleUpdateReceipt(args: unknown): Promise<UpdateReceipt> {
+    const data = emptyUpdateData(); let dispatched = false;
+    try {
+        if (!args || typeof args !== "object" || Array.isArray(args) || Object.keys(args).some(key => key !== "workdir")) return updateFailure(data, "invalid_request", "Update accepts workdir only; preview and extra options are unsupported.");
+        const input = args as Record<string, unknown>;
+        const cwd = input.workdir === undefined ? process.cwd() : input.workdir;
+        if (!safeUpdateText(cwd)) return updateFailure(data, "invalid_request", "Working directory must be nonblank bounded text without controls or invalid Unicode.");
+        data.workingDirectory = cwd; dispatched = true;
+        const observation = await captureUpdateCommand([...UPDATE_ARGV], cwd);
+        data.attempt = observation.attempt; data.capture = observation.capture;
+        if (observation.capture.complete && !observation.failed && observation.attempt.state === "started" && observation.attempt.exitCode === 0) {
+            data.effect = "not-proven";
+            return { ...updateHeader(data), ok: true, outcome: "command-completed" };
+        }
+        data.effect = ["started", "unknown"].includes(data.attempt.state) ? "uncertain" : "not-attempted";
+        return updateFailure(data, data.attempt.aborted ? "aborted" : data.effect === "uncertain" ? "uncertain" : "launch_failed", data.effect === "uncertain" ? "Update completion is not proven; partial workspace effects may exist." : "Update did not establish a process start.");
+    } catch {
+        if (dispatched) { data.attempt = { ...emptyUpdateAttempt(), state: "unknown" }; data.capture = null; data.effect = "uncertain"; }
+        return updateFailure(data, "producer_failed", "Update observation failed; no rollback or safe retry is proven.");
+    }
+}

package/src/operations/workspace-list.ts

@@ -0,0 +1,92 @@
+import { runCm, normalizeFindOutputLines } from "../execution/cm";
+import { spawnAndCollect, getCmExecutable } from "../execution/process";
+import { commandExecutionStorage, getActiveAbortSignal } from "../execution/context";
+import { runWorkspaceListFieldsCommand, WorkspaceListCommandError, WORKSPACE_LIST_CAPTURE_LIMITS } from "../execution/workspace-list-command";
+import { toStructuredResult } from "../presentation/results";
+
+export type WorkspaceListArgs = { source?: "native" | "fields"; format?: string; output?: "text" | "json"; maxItems?: number; workdir?: string };
+export type WorkspaceRow = { name: string; path: string; guid: string };
+export class WorkspaceListError extends Error {
+    constructor(readonly code: "invalid_identity" | "malformed_output" | "unsupported_query" | "invalid_producer_data" | "output_overflow") { super(`Workspace list read failed (${code}); no reusable rows are available.`); }
+}
+export const WORKSPACE_LIST_MAX_BYTES = 131072;
+export const WORKSPACE_FIELDS_FORMAT = "{wkname}{tab}{machine}{tab}{path}{tab}{wkid}";
+export const validWorkspaceTemplate = (s: string) => s.length <= 4096 && !/[\u0000\uD800-\uDFFF]/u.test(s);
+// ASCII output is not independent proof that original identities were ASCII:
+// this source requires an independently known ASCII-name/path configuration.
+export const validWorkspaceIdentity = (s: string) => s.length > 0 && s.length <= 4096 && /^[\x20-\x7e]+$/.test(s) && !s.includes("?");
+export const validWorkspaceName = (s: string) => validWorkspaceIdentity(s) && !/[\\/@]/.test(s) && s.trim() === s;
+export const validWorkspacePath = (s: string) => validWorkspaceIdentity(s) && (s.startsWith("/") || /^[A-Za-z]:[\\/]/.test(s) || /^\\\\[^\\]+\\[^\\]+/.test(s));
+export const validWorkspaceGuid = (s: string) => /^[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}$/.test(s);
+export function workspaceListRequest(args: WorkspaceListArgs) {
+    if ((args.source !== undefined && args.source !== "native" && args.source !== "fields") || (args.output !== undefined && args.output !== "text" && args.output !== "json")
+        || (args.maxItems !== undefined && (!Number.isSafeInteger(args.maxItems) || args.maxItems < 1 || args.maxItems > 500))
+        || (args.format !== undefined && (typeof args.format !== "string" || !validWorkspaceTemplate(args.format)))) throw new WorkspaceListError("invalid_producer_data");
+    const source = args.source ?? "native";
+    if (source === "fields" && args.format) throw new WorkspaceListError("unsupported_query");
+    return { source, maxItems: args.maxItems ?? 100 };
+}
+export function workspaceListCommand(args: WorkspaceListArgs): string[] {
+    const request = workspaceListRequest(args);
+    return ["workspace", "list", ...(request.source === "fields" ? [`--format=${WORKSPACE_FIELDS_FORMAT}`] : args.format ? [`--format=${args.format}`] : [])];
+}
+export function parseWorkspaceListFields(bytes: Uint8Array): { rows: WorkspaceRow[]; duplicateRecords: number } {
+    if (bytes.length > WORKSPACE_LIST_CAPTURE_LIMITS.stdoutBytes) throw new WorkspaceListCommandError("capture_incomplete");
+    if (bytes.some(byte => byte > 127)) throw new WorkspaceListError("invalid_identity");
+    if (!bytes.length) return { rows: [], duplicateRecords: 0 };
+    const lines = Buffer.from(bytes).toString("ascii").split(/\r?\n/);
+    if (lines.at(-1) === "") lines.pop();
+    if (lines.length > WORKSPACE_LIST_CAPTURE_LIMITS.records) throw new WorkspaceListCommandError("capture_incomplete");
+    const rows: WorkspaceRow[] = [], guids = new Map<string, string>(), names = new Map<string, string>(), paths = new Map<string, string>();
+    let duplicateRecords = 0;
+    for (const line of lines) {
+        const fields = line.split("\t");
+        if (fields.length !== 4) throw new WorkspaceListError("malformed_output");
+        const [name, machine, path, guid] = fields;
+        if (!validWorkspaceName(name) || !validWorkspaceIdentity(machine) || !validWorkspacePath(path) || !validWorkspaceGuid(guid)) throw new WorkspaceListError("invalid_identity");
+        // Exact repeated full records are observed again, not silently deduplicated.
+        // Machine remains unpublished, but conflicts in it still fail the whole read.
+        const prior = [guids.get(guid.toLowerCase()), names.get(name), paths.get(path)].filter(value => value !== undefined);
+        if (prior.some(value => value !== line)) throw new WorkspaceListError("malformed_output");
+        if (prior.length) duplicateRecords++;
+        guids.set(guid.toLowerCase(), line); names.set(name, line); paths.set(path, line); rows.push({ name, path, guid });
+    }
+    return { rows, duplicateRecords };
+}
+export type WorkspaceListObservation = { maxItems: number } & ({ source: "native"; rawResult: string; command: string[] } | { source: "fields"; rows: WorkspaceRow[]; duplicateRecords: number });
+export async function assembleWorkspaceListObservation(args: WorkspaceListArgs, typedNative = false): Promise<WorkspaceListObservation> {
+    const request = workspaceListRequest(args), command = workspaceListCommand(args);
+    if (request.source === "fields") {
+        const bytes = await runWorkspaceListFieldsCommand(command, args.workdir);
+        if (getActiveAbortSignal()?.aborted) throw new WorkspaceListCommandError("aborted");
+        const parsed = parseWorkspaceListFields(bytes);
+        if (getActiveAbortSignal()?.aborted) throw new WorkspaceListCommandError("aborted");
+        return { ...request, source: "fields", ...parsed };
+    }
+    if (!typedNative) return { ...request, source: "native", command, rawResult: await runCm(command, args.workdir) };
+    const signal = getActiveAbortSignal();
+    if (signal?.aborted) throw new WorkspaceListCommandError("aborted");
+    let result;
+    try { result = await spawnAndCollect(getCmExecutable(), command, args.workdir ?? process.cwd(), undefined, signal, commandExecutionStorage.getStore()); }
+    catch { throw new WorkspaceListCommandError(signal?.aborted ? "aborted" : "command_failed"); }
+    if (result.aborted || signal?.aborted) throw new WorkspaceListCommandError("aborted");
+    if (result.timedOut || result.stdoutTruncated || result.stderrTruncated) throw new WorkspaceListCommandError("capture_incomplete");
+    if (result.exitCode !== 0) throw new WorkspaceListCommandError("command_failed");
+    return { ...request, source: "native", command, rawResult: [result.stdout, result.stderr].filter(Boolean).join("\n").trim() || "(no output)" };
+}
+export const workspaceCapability = { identities: "ascii_names_and_paths_only", prerequisite: "original_names_and_paths_are_ascii", originalVerification: "not_performed", formatterLoss: "non_ascii_may_be_replaced_or_best_fit_to_ascii" } as const;
+export function workspaceListPayload(observation: WorkspaceListObservation) {
+    const common = { schemaVersion: 1, action: "workspace-list", provenance: { source: "plastic", producer: "@aefree/pi-plastic", contentTrust: "external" }, ok: true } as const;
+    const data = { scope: "local_client_inventory", limits: { maxItems: observation.maxItems, identityCodeUnits: 4096, compactUtf8Bytes: WORKSPACE_LIST_MAX_BYTES } } as const;
+    const payload = observation.source === "native"
+        ? { ...common, completeness: { read: "unknown", capture: "unknown", projection: false }, data: { ...data, mode: "native", basis: "workspace_list_native", capability: "noncanonical", pathBasis: "unavailable", rows: null, counts: null, countBasis: "unavailable" } }
+        : { ...common, completeness: { read: "complete_under_ascii_prerequisite", capture: "complete", projection: observation.rows.length <= observation.maxItems }, data: { ...data, mode: "fields", basis: "workspace_list_tab_fields", capability: workspaceCapability, pathBasis: "producer_absolute", diagnostics: { duplicateRecords: observation.duplicateRecords }, rows: observation.rows.slice(0, observation.maxItems), countBasis: "observed_response_rows", counts: { observed: observation.rows.length, returned: Math.min(observation.rows.length, observation.maxItems), omitted: Math.max(0, observation.rows.length - observation.maxItems), excluded: 0 } } };
+    if (Buffer.byteLength(JSON.stringify(payload), "utf8") > WORKSPACE_LIST_MAX_BYTES) throw new WorkspaceListError("output_overflow");
+    return payload;
+}
+export async function presentWorkspaceListObservation(observation: WorkspaceListObservation, args: WorkspaceListArgs): Promise<string> {
+    if (observation.source === "native") return toStructuredResult("workspace-list", args.output ?? "text", observation.rawResult, { command: ["cm", ...observation.command], rawOutput: observation.rawResult, resultCount: normalizeFindOutputLines(observation.rawResult).length }, args.workdir);
+    if (args.output === "json") return JSON.stringify(workspaceListPayload(observation));
+    const rows = observation.rows.slice(0, observation.maxItems), omitted = observation.rows.length - rows.length;
+    return ["ASCII-only workspace names/paths required; originals are not independently verified by this read.", ...(rows.length ? rows.map(row => `${row.name}\t${row.path}\t${row.guid}`) : ["(no observed inventory rows)"]), ...(omitted ? [`(${omitted} observed rows omitted from presentation.)`] : [])].join("\n");
+}

package/src/operations/workspace-merge-receipt.ts

@@ -0,0 +1,50 @@
+import { randomBytes } from "node:crypto";
+import { win32 } from "node:path";
+import { parseCopiedPending, admitCopiedStandardStatus, copiedPendingArgv, copiedPathKey } from "../domain/copied-merge";
+import { captureWorkspaceMergeCommand, emptyWorkspaceMergeAttempt } from "../execution/workspace-merge-command";
+import { admitCleanStandardStatus, admitWorkspaceMergeOutput, buildWorkspaceMergeArgv, safeMergeText, type MergeAction, type MergeStage, type WorkspaceMergeData, type WorkspaceMergeReceipt, type MergeStrategy } from "../domain/workspace-merge-contract";
+export type { WorkspaceMergeReceipt, MergeAction } from "../domain/workspace-merge-contract";
+export { safeMergeText, buildWorkspaceMergeArgv } from "../domain/workspace-merge-contract";
+export { presentWorkspaceMergeReceipt } from "../presentation/workspace-merge-results";
+export const emptyMergeStage = (): MergeStage => ({attempt:emptyWorkspaceMergeAttempt(),capture:null,admission:"not-observed"});
+export function emptyWorkspaceMergeData(): WorkspaceMergeData { return {intendedArgv:["merge"],workingDirectory:null,requestedSource:null,strategy:null,cherrypicking:null,forced:null,previewRequested:null,outputFormatRequested:null,apply:emptyMergeStage(),shortStatus:emptyMergeStage(),fullStatus:emptyMergeStage(),pendingReadMode:"short",commandCompleted:false,observedWorkspaceIdentity:null,observedSourceIdentity:null,observedFinalizedMetadata:null,observedPreservation:null,observedPendingItems:null,fileConflictCount:null,protocol:"not-observed",checkinReadiness:"unknown",verification:"unverified",effect:"not-attempted"}; }
+function header(action:MergeAction,data:WorkspaceMergeData) {const stages=[data.apply,data.shortStatus,data.fullStatus],observed=stages.filter(s=>s.capture);return {schemaVersion:1 as const,action,provenance:{source:"plastic" as const,producer:"@aefree/pi-plastic" as const,contentTrust:"external" as const},completeness:{capture:!observed.length?"unknown" as const:observed.every(s=>s.capture!.complete)?"complete" as const:"incomplete" as const,projection:true as const},data};}
+export function workspaceMergeFailure(action:MergeAction,data:WorkspaceMergeData,code:WorkspaceMergeReceipt extends infer T ? T extends {error:{code:infer C}} ? C : never : never,message:string):WorkspaceMergeReceipt {return {...header(action,data),ok:false,outcome:data.effect==="not-attempted"?"failed":data.checkinReadiness==="blocked"?"blocked":"uncertain",error:{code,message}};}
+export async function assembleWorkspaceMergeReceipt(action:MergeAction,args:unknown):Promise<WorkspaceMergeReceipt>{
+ const data=emptyWorkspaceMergeData();let active: "apply"|"shortStatus"|"fullStatus"|null=null;
+ try{
+  const keys=action==="merge"?["source","strategy","cherrypicking","forced","preflight","format","workdir"]:["source","strategy","preflight","format","workdir"];
+  if(!args||typeof args!=="object"||Array.isArray(args)||Object.keys(args).some(k=>!keys.includes(k)))return workspaceMergeFailure(action,data,"invalid_request","Use only declared workspace merge controls.");
+  const i=args as Record<string,unknown>,source=i.source,cwd=i.workdir===undefined?process.cwd():i.workdir,strategy=i.strategy===undefined?(action==="merge"?"auto":"destination"):i.strategy,cherry=i.cherrypicking===undefined?false:i.cherrypicking,forced=i.forced===undefined?false:i.forced,preview=i.preflight===undefined?false:i.preflight,format=i.format===undefined?"text":i.format;
+  if(!safeMergeText(source)||source.trimStart().startsWith("-")||!safeMergeText(cwd)||!(action==="merge"?["auto","source","destination"]:["source","destination"]).includes(strategy as string)||[cherry,forced,preview].some(v=>typeof v!=="boolean")||!["text","json"].includes(format as string))return workspaceMergeFailure(action,data,"invalid_request","Use a bounded source operand, strict controls and text/json; source options/stdin are rejected.");
+  const token="__WM_"+randomBytes(12).toString("hex")+"__";data.intendedArgv=buildWorkspaceMergeArgv(source,strategy as MergeStrategy,cherry as boolean,forced as boolean,token);data.workingDirectory=cwd;data.requestedSource=source;data.strategy=strategy as MergeStrategy;data.cherrypicking=cherry as boolean;data.forced=forced as boolean;data.previewRequested=preview as boolean;data.outputFormatRequested=format as "text"|"json";
+  if(preview)return {...header(action,data),ok:true,outcome:"preflight"};
+  active="apply";const apply=await captureWorkspaceMergeCommand([...data.intendedArgv],cwd);data.apply={attempt:apply.attempt,capture:apply.capture,admission:"unsupported"};active=null;data.effect=["started","unknown"].includes(apply.attempt.state)?"uncertain":"not-attempted";
+  if(!apply.capture.complete||apply.failed||apply.attempt.state!=="started")return workspaceMergeFailure(action,data,apply.attempt.aborted?"aborted":data.effect==="not-attempted"?"launch_failed":"uncertain","Merge capture/start/completion is not established; do not retry automatically.");
+  data.commandCompleted=apply.attempt.exitCode===0;
+  const parsed=admitWorkspaceMergeOutput(apply.stdout!,token);data.protocol=parsed.protocol;data.pendingReadMode=parsed.protocol==="apply-add-copied"?"copied-machine":"short";data.fileConflictCount=parsed.fileConflictCount;data.apply.admission=parsed.protocol==="unsupported"?"unsupported":"admitted";
+  if(parsed.protocol==="file-conflict"){data.checkinReadiness="blocked";return workspaceMergeFailure(action,data,"conflict","Observed file-conflict records; checkin blocked. Earlier effects are not disproven.");}
+  if(!data.commandCompleted)return workspaceMergeFailure(action,data,"uncertain","Merge exited nonzero; workspace effects may already exist.");
+  if(parsed.protocol==="unsupported")return workspaceMergeFailure(action,data,"unsupported_readiness","Merge completed; applying profile unadmitted. Inspect apply.admission/protocol; verify loaded package revision and retain sanitized producer evidence. Readiness unknown; do not reapply automatically or infer rollback.");
+  const copied=parsed.protocol==="apply-add-copied";data.pendingReadMode=copied?"copied-machine":"short";
+  if(copied&&process.platform!=="win32")return workspaceMergeFailure(action,data,"unsupported_readiness","Copied readiness is sourced only on the observed Windows client.");
+  active="shortStatus";const short=await captureWorkspaceMergeCommand(copied?[...copiedPendingArgv]:["status","--short"],cwd);data.shortStatus={attempt:short.attempt,capture:short.capture,admission:"unsupported"};active=null;
+  if(!short.capture.complete||short.failed||short.attempt.exitCode!==0)return workspaceMergeFailure(action,data,"unsupported_readiness","Merge command completed; pending read failed/incomplete. Checkin readiness unknown.");
+  const pending=copied?parseCopiedPending(short.stdout!,cwd):null;
+  const copiedKeys=pending?.paths.map(copiedPathKey)??[];
+  const coherent=!!pending&&parsed.copiedPaths.length===copiedKeys.length&&new Set(parsed.copiedPaths.map(copiedPathKey)).size===copiedKeys.length&&parsed.copiedPaths.every(p=>copiedKeys.includes(copiedPathKey(p)))&&new Set(parsed.addedPaths.map(p=>copiedPathKey(win32.join(cwd,p)))).size===copiedKeys.length&&parsed.addedPaths.every(p=>p.startsWith("/")&&!p.includes("\\")&&p.slice(1).split("/").every(v=>v!==""&&v!=="."&&v!==".."&&!/[?\uFFFD]/u.test(v))&&copiedKeys.includes(copiedPathKey(win32.join(cwd,p))));
+  data.shortStatus.admission=(copied?coherent:short.stdout==="")&&short.stderr===""?"admitted":"unsupported";
+  active="fullStatus";const full=await captureWorkspaceMergeCommand(["status"],cwd);data.fullStatus={attempt:full.attempt,capture:full.capture,admission:"unsupported"};active=null;
+  if(!full.capture.complete||full.failed||full.attempt.exitCode!==0)return workspaceMergeFailure(action,data,"unsupported_readiness","Merge command completed; merge-state read failed/incomplete. Checkin readiness unknown.");
+  data.fullStatus.admission=(copied?!!pending&&admitCopiedStandardStatus(full.stdout!,pending,source,cwd):admitCleanStandardStatus(full.stdout!))&&full.stderr===""?"admitted":"unsupported";
+  // No warning/unknown stderr can authorize compound checkin.
+  if(apply.stderr!=="")return workspaceMergeFailure(action,data,"unsupported_readiness","Merge command completed; applying stderr is outside the admitted warning profile. Checkin paused; prior effects remain possible. Do not reapply automatically.");
+  if(data.shortStatus.admission!=="admitted")return workspaceMergeFailure(action,data,"unsupported_readiness",copied?"Merge command completed; copied pending/ADD/path cardinality correlation is unadmitted (shortStatus). Checkin paused; inspect separately authorized pending evidence without reapplying merge.":"Merge command completed; shortStatus pending/warning evidence is unadmitted. Checkin paused; inspect separately authorized pending evidence without reapplying merge.");
+  if(data.fullStatus.admission!=="admitted")return workspaceMergeFailure(action,data,"unsupported_readiness","Merge command completed; fullStatus namespace/link/copied or clean-status evidence is unadmitted. Checkin paused; prior effects remain possible. Inspect separately authorized status evidence without reapplying merge.");
+  data.effect="not-proven";data.checkinReadiness="supported-no-unresolved-signals";return {...header(action,data),ok:true,outcome:"command-completed"};
+ }catch{
+  if(active){data[active]={attempt:{...emptyWorkspaceMergeAttempt(),state:"unknown"},capture:null,admission:"unsupported"};}
+  if(active==="apply"||["started","unknown"].includes(data.apply.attempt.state))data.effect="uncertain";
+  return workspaceMergeFailure(action,data,"producer_failed","Merge evidence collection failed; prior effects remain possible and checkin readiness unknown.");
+ }
+}

package/src/operations/workspace.ts

@@ -0,0 +1,120 @@
+import { tool } from "../tool-definition";
+import { assembleWorkspaceListObservation, presentWorkspaceListObservation } from "./workspace-list";
+import { workdirArg } from "./arguments";
+import { assembleUpdateReceipt, presentUpdateReceipt } from "./update-receipt";
+import { assembleAddReceipt, presentAddReceipt } from "./add-receipt";
+import { assembleUndoReceipt, presentUndoReceipt } from "./undo-receipt";
+import { runCm } from "../execution/cm";
+import { outputFormatArg } from "../presentation/results";
+import { assembleRemovalReceipt, presentRemovalReceipt } from "./removal-receipt";
+
+export const update = tool({
+    description: "Update workspace safely without launching interactive merge (cm update --dontmerge --noinput).",
+    args: {
+        workdir: workdirArg,
+    },
+    async execute(args)
+    {
+        const receipt = await assembleUpdateReceipt(args);
+        const text = presentUpdateReceipt(receipt);
+        if (!receipt.ok) throw new Error(text);
+        return text;
+    },
+});
+
+export const add = tool({
+    description: "Add items to Plastic SCM (cm add).",
+    args: {
+        paths: tool.schema.array(tool.schema.string()).min(1).describe("Paths to add."),
+        workdir: workdirArg,
+    },
+    async execute(args)
+    {
+        const receipt = await assembleAddReceipt(args);
+        const text = presentAddReceipt(receipt);
+        if (!receipt.ok) throw new Error(text);
+        return text;
+    },
+});
+
+export const undo = tool({
+    description: "Undo changes for specified items (cm undo).",
+    args: {
+        paths: tool.schema.array(tool.schema.string()).min(1).describe("Paths to undo."),
+        workdir: workdirArg,
+    },
+    async execute(args)
+    {
+        const receipt = await assembleUndoReceipt(args);
+        const text = presentUndoReceipt(receipt);
+        if (!receipt.ok) throw new Error(text);
+        return text;
+    },
+});
+
+export const resolveDeleteChangeConflict = tool({
+    description: "Request source-side deletion for a Plastic SCM delete/change conflict via cm remove; actual resolution remains unverified.",
+    args: {
+        paths: tool.schema.array(tool.schema.string()).min(1).describe("Controlled workspace paths to resolve by accepting the source-side deletion."),
+        keepOnDisk: tool.schema.boolean().optional().describe("Request --nodisk to retain items on disk. Defaults to true; preservation remains unverified."),
+        preflight: tool.schema.boolean().optional().describe("Preview the resolution command without executing it."),
+        format: outputFormatArg,
+        workdir: workdirArg,
+    },
+    async execute(args)
+    {
+
+        const receipt = await assembleRemovalReceipt(args);
+        const text = presentRemovalReceipt(receipt);
+        if (!receipt.ok) throw new Error(text);
+        return text;
+    },
+});
+
+export const workspaceCreate = tool({
+    description: "Create a Plastic SCM workspace (cm workspace create).",
+    args: {
+        name: tool.schema.string().min(1).describe("Workspace name."),
+        path: tool.schema.string().min(1).describe("Workspace path."),
+        repositorySpec: tool.schema.string().optional().describe("Optional repository specification for the new workspace."),
+        selectorFile: tool.schema.string().optional().describe("Optional selector file path for the new workspace."),
+        workdir: workdirArg,
+    },
+    async execute(args)
+    {
+        if (args.repositorySpec && args.selectorFile)
+        {
+            throw new Error("Provide either repositorySpec or selectorFile, not both.");
+        }
+
+        const cmdArgs: string[] = ["workspace", "create", args.name, args.path];
+
+        if (args.repositorySpec)
+        {
+            cmdArgs.push(args.repositorySpec);
+        }
+
+        if (args.selectorFile)
+        {
+            cmdArgs.push(`--selector=${args.selectorFile}`);
+        }
+
+        return runCm(cmdArgs, args.workdir);
+    },
+});
+
+export const workspaceList = tool({
+    description: "List Plastic SCM workspaces (cm workspace list).",
+    args: {
+        format: tool.schema.string().optional().describe("Native CLI template (up to 4096 code units), not a presentation enum. Conflicts with fields source unless empty."),
+        source: tool.schema.enum(["native", "fields"]).optional().describe("Defaults to native. Fields requires independently known ASCII-only original workspace names and paths; formatter may silently best-fit non-ASCII to ASCII."),
+        maxItems: tool.schema.number().int().min(1).max(500).optional().describe("Fields projection limit, default 100; not a CLI query limit."),
+        output: outputFormatArg,
+        workdir: workdirArg,
+    },
+    async execute(args)
+    {
+        const observation = await assembleWorkspaceListObservation(args);
+        return presentWorkspaceListObservation(observation, args);
+    },
+});

package/src/pi/add-output.ts

@@ -0,0 +1,52 @@
+import { Type } from "typebox";
+import { Check } from "typebox/value";
+import { assembleAddReceipt, emptyAddData, addFailure, presentAddReceipt, safeAddText, ADD_COMMAND, validAddOperands, type AddReceipt } from "../operations/add-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(), observedAddedItems: Type.Null(), verification: Type.Literal("unverified") };
+const header = { schemaVersion: Type.Literal(1), action: Type.Literal("add"), 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 addOutputSchema = Type.Unsafe<AddReceipt>(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 validateAddOutput(value: unknown): value is AddReceipt {
+    if (!Check(addOutputSchema, value) || Buffer.byteLength(JSON.stringify(value), "utf8") > 131072) return false;
+    const dto = value as AddReceipt, d = dto.data, a = d.attempt, c = d.capture;
+    if (d.intendedArgv[0] !== ADD_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 (!validAddOperands(d.intendedArgv.slice(1)) || d.requestedOperandCount !== d.intendedArgv.length - 1 || !d.workingDirectory) return false;
+    if (d.workingDirectory !== null && !safeAddText(d.workingDirectory)) return false;
+    if (!dto.ok && !safeAddText(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 executeAddOutput(args: unknown) {
+    let dto = await assembleAddReceipt(args);
+    const valid: boolean = validateAddOutput(dto);
+    if (!valid) {
+        const possibleStart = !["not-attempted", "not-started"].includes(dto.data.attempt.state);
+        const data = emptyAddData();
+        if (possibleStart) { data.attempt.state = "unknown"; data.effect = "uncertain"; }
+        dto = addFailure(data, "producer_failed", "Add receipt validation failed; do not retry automatically.");
+        if (!validateAddOutput(dto)) throw new Error("Safe add receipt could not be constructed.");
+    }
+    return { content: [{ type: "text" as const, text: presentAddReceipt(dto) }], details: {}, structuredContent: dto, isError: !dto.ok };
+}