@aefree/pi-plastic 0.7.6 → 0.8.1

package/src/pi/register.ts

@@ -0,0 +1,188 @@
+import { executeObjectWriteOutput, shelvesetCreateOutputSchema, shelvesetApplyOutputSchema, codeReviewCreateOutputSchema, codeReviewUpdateOutputSchema } from "./object-write-output";
+import { executePatchOutput, patchOutputSchema } from "./patch-output";
+import { executeCheckinOutput, checkinOutputSchema } from "./checkin-output";
+import { executeSwitchOutput, switchOutputSchema } from "./switch-output";
+import { executeUpdateOutput, updateOutputSchema } from "./update-output";
+import { executeAddOutput, addOutputSchema } from "./add-output";
+import { executeUndoOutput, undoOutputSchema } from "./undo-output";
+import { executeRemovalOutput, removalOutputSchema } from "./removal-output";
+import { executeWorkspaceMergeOutput, workspaceMergeOutputSchema } from "./workspace-merge-output";
+import { executeCloseoutOutput, closeoutOutputSchema } from "./closeout-output";
+import { executeBranchDeleteOutput, branchDeleteOutputSchema } from "./branch-delete-output";
+import { executeObjectDeleteOutput, shelvesetDeleteOutputSchema, codeReviewDeleteOutputSchema } from "./object-delete-output";
+import { executeBranchCreateOutput, branchCreateOutputSchema } from "./branch-create-output";
+import { executeServerMergeOutput, serverMergeOutputSchema } from "./server-merge-output";
+import { executeDiffOutput, diffInputSchema, diffOutputSchema } from "./diff-output";
+import { executeCodeReviewFindOutput, codeReviewFindOutputSchema } from "./code-review-find-output";
+import { executeShelvesetListOutput, shelvesetListOutputSchema } from "./shelveset-list-output";
+import { executeWorkspaceListOutput, workspaceListOutputSchema } from "./workspace-list-output";
+import { executeBranchListOutput, branchListOutputSchema } from "./branch-list-output";
+import { executeBranchOutput, currentBranchOutputSchema, branchExistsOutputSchema } from "./branch-output";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { executeStatusOutput, statusOutputSchema } from "./status-output";
+import { runWithAbortSignal } from "../execution/context";
+import { renderPlasticCall, renderPlasticResult, renderPlasticSearchResult } from "../plastic-renderers";
+import {
+  getEffectivePlasticToolOwnership,
+  getInitiallyInactivePlasticTools,
+  getPlasticToolLoadingMode,
+  getRestoredPlasticToolNames,
+  getUnknownExactPlasticToolNames,
+  isPlasticToolBrowseRequest,
+  PLASTIC_TOOL_BROWSE_TEXT,
+  PLASTIC_TOOL_SEARCH_NAME,
+  searchPlasticTools,
+} from "../plastic-tool-loading";
+import { TOOL_CONFIG, normalizeArgs } from "./arguments";
+import { buildParameters } from "./schemas";
+import { getCoreTool, getRegisteredPlasticExportNames, toToolName } from "./tool-registry";
+import { notifyPatchCapabilityWarning, type CapabilityDiagnosticContext } from "./capability-diagnostics";
+
+export function registerPlasticTools(pi: ExtensionAPI, extensionSourcePath: string) {
+  const exportNames = getRegisteredPlasticExportNames();
+  const coreDescriptions = new Map<string, string>();
+  for (const exportName of exportNames) {
+    const coreTool = getCoreTool(exportName);
+    coreDescriptions.set(toToolName(exportName), coreTool.description ?? toToolName(exportName));
+  }
+
+  for (const exportName of exportNames) {
+    const coreTool = getCoreTool(exportName);
+    const config = TOOL_CONFIG[exportName] ?? {};
+    pi.registerTool({
+      name: toToolName(exportName),
+      label: toToolName(exportName),
+      description: coreTool.description ?? toToolName(exportName),
+      parameters: exportName === "diff" ? diffInputSchema : buildParameters(coreTool.args),
+      ...(exportName === "shelvesetCreate" ? {outputSchema:shelvesetCreateOutputSchema} : exportName === "shelvesetApply" ? {outputSchema:shelvesetApplyOutputSchema} : exportName === "codeReviewCreate" ? {outputSchema:codeReviewCreateOutputSchema} : exportName === "codeReviewUpdate" ? {outputSchema:codeReviewUpdateOutputSchema} : exportName === "patch" ? {outputSchema:patchOutputSchema} : exportName === "status" ? { outputSchema: statusOutputSchema } : exportName === "currentBranch" ? { outputSchema: currentBranchOutputSchema } : exportName === "branchExists" ? { outputSchema: branchExistsOutputSchema } : exportName === "branchList" ? { outputSchema: branchListOutputSchema } : exportName === "workspaceList" ? { outputSchema: workspaceListOutputSchema } : exportName === "shelvesetList" ? { outputSchema: shelvesetListOutputSchema } : exportName === "codeReviewFind" ? { outputSchema: codeReviewFindOutputSchema } : exportName === "diff" ? { outputSchema: diffOutputSchema } : exportName === "mergeBranches" ? { outputSchema: serverMergeOutputSchema } : exportName === "checkin" ? { outputSchema: checkinOutputSchema } : exportName === "branchCreate" ? { outputSchema: branchCreateOutputSchema } : exportName === "switchBranch" ? { outputSchema: switchOutputSchema } : exportName === "update" ? { outputSchema: updateOutputSchema } : exportName === "add" ? { outputSchema: addOutputSchema } : exportName === "undo" ? { outputSchema: undoOutputSchema } : exportName === "resolveDeleteChangeConflict" ? { outputSchema: removalOutputSchema } : exportName === "merge" || exportName === "finalizeMerge" ? { outputSchema: workspaceMergeOutputSchema } : exportName === "mergeToBranch" ? { outputSchema: closeoutOutputSchema } : exportName === "branchDelete" ? { outputSchema: branchDeleteOutputSchema } : exportName === "shelvesetDelete" ? {outputSchema:shelvesetDeleteOutputSchema} : exportName === "codeReviewDelete" ? {outputSchema:codeReviewDeleteOutputSchema} : {}),
+      prepareArguments: config.prepareArguments,
+      renderCall(args, theme, context) {
+        return renderPlasticCall(exportName, args ?? {}, theme, context);
+      },
+      renderResult(result, options, theme, context) {
+        return renderPlasticResult(exportName, result, options, theme, context);
+      },
+      async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+        const normalizedParams = normalizeArgs(params);
+        if (exportName !== "mergeBranches" && normalizedParams.workdir === undefined && ctx?.cwd) {
+          normalizedParams.workdir = ctx.cwd;
+        }
+        if (exportName === "shelvesetCreate" || exportName === "shelvesetApply" || exportName === "codeReviewCreate" || exportName === "codeReviewUpdate") return runWithAbortSignal(signal, () => executeObjectWriteOutput(({shelvesetCreate:"shelveset-create",shelvesetApply:"shelveset-apply",codeReviewCreate:"code-review-create",codeReviewUpdate:"code-review-update"} as const)[exportName], normalizedParams));
+        if (exportName === "patch") return runWithAbortSignal(signal, () => executePatchOutput(normalizedParams));
+        if (exportName === "checkin") return runWithAbortSignal(signal, () => executeCheckinOutput(normalizedParams));
+        if (exportName === "switchBranch") return runWithAbortSignal(signal, () => executeSwitchOutput(normalizedParams));
+        if (exportName === "update") return runWithAbortSignal(signal, () => executeUpdateOutput(normalizedParams));
+        if (exportName === "add") return runWithAbortSignal(signal, () => executeAddOutput(normalizedParams));
+        if (exportName === "undo") return runWithAbortSignal(signal, () => executeUndoOutput(normalizedParams));
+        if (exportName === "resolveDeleteChangeConflict") return runWithAbortSignal(signal, () => executeRemovalOutput(normalizedParams));
+        if (exportName === "merge" || exportName === "finalizeMerge") return runWithAbortSignal(signal, () => executeWorkspaceMergeOutput(exportName === "merge" ? "merge" : "finalize-merge", normalizedParams));
+        if (exportName === "mergeToBranch") return runWithAbortSignal(signal, () => executeCloseoutOutput(normalizedParams));
+        if (exportName === "branchDelete") return runWithAbortSignal(signal, () => executeBranchDeleteOutput(normalizedParams));
+        if (exportName === "shelvesetDelete" || exportName === "codeReviewDelete") return runWithAbortSignal(signal, () => executeObjectDeleteOutput(exportName === "shelvesetDelete" ? "shelveset-delete" : "code-review-delete", normalizedParams));
+        if (exportName === "branchCreate") return runWithAbortSignal(signal, () => executeBranchCreateOutput(normalizedParams));
+        if (exportName === "mergeBranches") return runWithAbortSignal(signal, () => executeServerMergeOutput(normalizedParams));
+        if (exportName === "diff") return runWithAbortSignal(signal, () => executeDiffOutput(normalizedParams));
+        if (exportName === "codeReviewFind") return runWithAbortSignal(signal, () => executeCodeReviewFindOutput(normalizedParams));
+        if (exportName === "shelvesetList") return runWithAbortSignal(signal, () => executeShelvesetListOutput(normalizedParams));
+        if (exportName === "workspaceList") return runWithAbortSignal(signal, () => executeWorkspaceListOutput(normalizedParams));
+        if (exportName === "branchList") return runWithAbortSignal(signal, () => executeBranchListOutput(normalizedParams));
+        if (exportName === "status") return runWithAbortSignal(signal, () => executeStatusOutput(normalizedParams));
+        if (exportName === "currentBranch" || exportName === "branchExists") return runWithAbortSignal(signal, () => executeBranchOutput(exportName, normalizedParams));
+        throw new Error(`Missing producer-owned Plastic adapter: ${exportName}`);
+      },
+    });
+  }
+
+  pi.registerTool({
+    name: PLASTIC_TOOL_SEARCH_NAME,
+    label: "Plastic Tool Search",
+    description: "Search and enable Plastic SCM / Unity Version Control tools for workspace status and sync, changes and checkins, text-only diffs and patches, branches and merges, shelvesets, code reviews, and workspaces.",
+    promptSnippet: "Use plastic_tool_search to find and enable Plastic SCM capabilities that are not active.",
+    promptGuidelines: [
+      "Use plastic_tool_search before a Plastic SCM action when an appropriate plastic_* tool is not active. Inspect exact mutation targets. Do not preflight routinely: use preflight for ambiguous or broad scope, moved/deleted path rewriting, compound operations, or an explicit preview request.",
+    ],
+    parameters: Type.Object({
+      query: Type.Optional(Type.String({ description: "Capability or workflow to search for." })),
+      toolNames: Type.Optional(Type.Array(Type.String({ description: "Exact public Plastic tool name." }), { maxItems: 4, description: "Optional exact tool names to enable." })),
+      limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 4, description: "Maximum matching tools to enable. Defaults to the single best keyword match; exact toolNames requests may enable up to four." })),
+    }),
+    renderCall(args, theme, context) {
+      return renderPlasticCall("tool_search", args ?? {}, theme, context);
+    },
+    renderResult(result, options, theme, context) {
+      return renderPlasticSearchResult(result, options, theme, context);
+    },
+    async execute(_toolCallId, params) {
+      if (isPlasticToolBrowseRequest(params)) {
+        return {
+          content: [{ type: "text", text: PLASTIC_TOOL_BROWSE_TEXT }],
+          details: { browse: true, matches: [], added: [], alreadyActive: [], guidance: [] },
+        };
+      }
+
+      const ownership = getEffectivePlasticToolOwnership(pi.getAllTools(), extensionSourcePath);
+      const unknownToolNames = getUnknownExactPlasticToolNames(params.toolNames);
+      const active = pi.getActiveTools();
+      // Never infer ownership without canonical sourceInfo. In that
+      // compatibility mode we may describe known tools that are already active,
+      // but cannot safely activate an inactive same-named definition.
+      const matches = searchPlasticTools(params, coreDescriptions).filter((match) =>
+        ownership.usesSourceInfo ? ownership.ownedToolNames.has(match.name) : active.includes(match.name),
+      );
+      const requestedExactToolNames = Array.isArray(params.toolNames)
+        ? [...new Set(params.toolNames.filter((name): name is string => typeof name === "string" && name.trim().length > 0).map((name) => name.trim()))]
+        : [];
+      const unavailableToolNames = requestedExactToolNames.filter((name) => !matches.some((match) => match.name.toLowerCase() === name.toLowerCase()));
+      if (matches.length === 0) {
+        const unavailable = unavailableToolNames.length > 0
+          ? ` Unknown or unavailable exact tool names: ${unavailableToolNames.join(", ")}.`
+          : "";
+        return {
+          content: [{ type: "text", text: `No executable Plastic tools matched. Try a capability, workflow term, or exact public plastic_* tool name.${unavailable}` }],
+          details: { matches: [], added: [], alreadyActive: [], guidance: [], unknownToolNames, unavailableToolNames },
+        };
+      }
+
+      const matchNames = matches.map((match) => match.name);
+      const added = matchNames.filter((name) => !active.includes(name));
+      const alreadyActive = matchNames.filter((name) => active.includes(name));
+      if (added.length > 0) pi.setActiveTools([...new Set([...active, ...added])]);
+
+      const guidance = matches.flatMap((match) => match.guidance);
+      const unknownText = unavailableToolNames.length > 0 ? `\nUnknown or unavailable exact tool names: ${unavailableToolNames.join(", ")}.` : "";
+      const loadedText = added.length > 0 ? `Activated: ${added.join(", ")}.` : "All matching tools were already active.";
+      return {
+        content: [{
+          type: "text",
+          text: `${loadedText}\nMatches: ${matchNames.join(", ")}.\nGuidance: ${guidance.join(" ")}${unknownText}`,
+        }],
+        details: { matches: matchNames, added, alreadyActive, guidance, unknownToolNames, unavailableToolNames },
+      };
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    await notifyPatchCapabilityWarning(ctx as CapabilityDiagnosticContext);
+    const ownership = getEffectivePlasticToolOwnership(pi.getAllTools(), extensionSourcePath);
+    const active = pi.getActiveTools();
+    const mode = getPlasticToolLoadingMode();
+    // Fail safe when provenance is unavailable or the effective loader is a
+    // foreign first-registration-wins collision. Preserve the active set
+    // exactly; even adding the public loader name could activate foreign code.
+    if (!ownership.usesSourceInfo) return;
+
+    // The all-active eval mode keeps every currently exposed Plastic tool
+    // active while omitting the dynamic loader from the provider surface.
+    if (mode === "all-active") {
+      pi.setActiveTools(active.filter((name) => name !== PLASTIC_TOOL_SEARCH_NAME));
+      return;
+    }
+
+    const initiallyInactive = getInitiallyInactivePlasticTools(mode);
+    const ownedInitiallyInactive = new Set([...initiallyInactive].filter((name) => ownership.ownedToolNames.has(name)));
+    const restored = getRestoredPlasticToolNames(ctx.sessionManager.getBranch(), ownership.ownedToolNames);
+    const preserved = active.filter((name) => !ownedInitiallyInactive.has(name));
+    pi.setActiveTools([...new Set([...preserved, PLASTIC_TOOL_SEARCH_NAME, ...restored])]);
+  });
+}

package/src/pi/removal-output.ts

@@ -0,0 +1,59 @@
+import { Type } from "typebox";
+import { Check } from "typebox/value";
+import { assembleRemovalReceipt, emptyRemovalData, removalFailure, presentRemovalReceipt, safeRemovalText, REMOVAL_COMMAND, validRemovalOperands, type RemovalReceipt } from "../operations/removal-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: 258 }), 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(), observedResolvedItems: Type.Null(), observedResolution: Type.Null(), observedPreservation: Type.Null(), observedPendingState: Type.Null(), keepOnDiskRequested: Type.Union([Type.Boolean(), Type.Null()]), previewRequested: Type.Union([Type.Boolean(), Type.Null()]), outputFormatRequested: Type.Union([enumeration(["text", "json"]), Type.Null()]), resolutionIntent: Type.Literal("accept-source-deletion"), verification: Type.Literal("unverified") };
+const header = { schemaVersion: Type.Literal(1), action: Type.Literal("resolve-delete-change-conflict"), 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 removalOutputSchema = Type.Unsafe<RemovalReceipt>(Type.Union([
+    object({ ...header, ok: Type.Literal(true), outcome: Type.Literal("preflight"), data: object({ ...data, effect: Type.Literal("not-attempted") }) }),
+    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 validateRemovalOutput(value: unknown): value is RemovalReceipt {
+    if (!Check(removalOutputSchema, value) || Buffer.byteLength(JSON.stringify(value), "utf8") > 131072) return false;
+    const dto = value as RemovalReceipt, d = dto.data, a = d.attempt, c = d.capture;
+    if (d.intendedArgv[0] !== REMOVAL_COMMAND) return false;
+    if (d.requestedOperandCount === null) {
+        if (d.intendedArgv.length !== 1 || d.keepOnDiskRequested !== null || d.previewRequested !== null || d.outputFormatRequested !== null || d.workingDirectory !== null || c || !["not-attempted", "unknown"].includes(a.state)) return false;
+    } else {
+        if (typeof d.keepOnDiskRequested !== "boolean" || typeof d.previewRequested !== "boolean" || d.outputFormatRequested === null || !d.workingDirectory) return false;
+        const offset = d.keepOnDiskRequested ? 2 : 1;
+        if (d.keepOnDiskRequested && d.intendedArgv[1] !== "--nodisk" || !validRemovalOperands(d.intendedArgv.slice(offset)) || d.requestedOperandCount !== d.intendedArgv.length - offset) return false;
+    }
+    if (d.previewRequested === true && (d.requestedOperandCount === null || c || a.state !== "not-attempted" || a.terminal !== "not-observed" || a.exitCode !== null || a.aborted || a.timedOut || d.effect !== "not-attempted" || !dto.ok || dto.outcome !== "preflight")) return false;
+    if (dto.ok && dto.outcome === "preflight" && d.previewRequested !== true) return false;
+    if (d.workingDirectory !== null && !safeRemovalText(d.workingDirectory)) return false;
+    if (!dto.ok && !safeRemovalText(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 && dto.outcome === "command-completed" && (d.previewRequested !== false || 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 executeRemovalOutput(args: unknown) {
+    let dto = await assembleRemovalReceipt(args);
+    const valid: boolean = validateRemovalOutput(dto);
+    if (!valid) {
+        const possibleStart = !["not-attempted", "not-started"].includes(dto.data.attempt.state);
+        const data = emptyRemovalData();
+        if (possibleStart) { data.attempt.state = "unknown"; data.effect = "uncertain"; }
+        dto = removalFailure(data, "producer_failed", "Removal receipt validation failed; do not retry automatically.");
+        if (!validateRemovalOutput(dto)) throw new Error("Safe removal receipt could not be constructed.");
+    }
+    return { content: [{ type: "text" as const, text: presentRemovalReceipt(dto) }], details: {}, structuredContent: dto, isError: !dto.ok };
+}

package/src/pi/schemas.ts

@@ -0,0 +1,146 @@
+import { type TSchema, Type } from "typebox";
+
+type CoreSchemaNode = {
+  kind: string;
+  values?: unknown;
+  inner?: unknown;
+  metadata?: {
+    optional?: boolean;
+    description?: string;
+    min?: number;
+    max?: number;
+    int?: boolean;
+  };
+};
+
+const EMPTY_PARAMETERS = Type.Object({});
+const enumSchema = (values: readonly string[], description: string): TSchema =>
+  Type.Union(values.map((value) => Type.Literal(value)), { description });
+
+const OUTPUT_FORMAT_SCHEMA = enumSchema(["text", "json"], "Output format. Defaults to text.");
+const PENDING_CHANGES_SCHEMA = enumSchema(["shelve", "bring", "cancel"], "How to handle pending changes when switching branches.");
+const MERGE_STRATEGY_SCHEMA = enumSchema(["auto", "source", "destination"], "Conflict resolution strategy.");
+const COMPARISON_METHOD_SCHEMA = enumSchema(
+  ["ignoreeol", "ignorewhitespaces", "ignoreeolandwhitespaces", "recognizeall"],
+  "Comparison method used for diff calculations.",
+);
+const REVIEW_TARGET_TYPE_SCHEMA = enumSchema(["branch", "changeset"], "Filter by review target type.");
+const BRANCH_ORDER_BY_SCHEMA = enumSchema(["date", "branchname"], "Sort field for branch queries.");
+const REVIEW_ORDER_BY_SCHEMA = enumSchema(["date", "modifieddate", "status"], "Sort field for review queries.");
+
+function isCoreSchemaNode(value: unknown): value is CoreSchemaNode {
+  return Boolean(value) && typeof value === "object" && typeof (value as { kind?: unknown }).kind === "string";
+}
+
+function applySchemaMetadata(schema: TSchema, node: CoreSchemaNode): TSchema {
+  const metadata = node.metadata ?? {};
+  const options: { description?: string; minimum?: number; maximum?: number } = {};
+
+  if (metadata.description) options.description = metadata.description;
+  if (metadata.min !== undefined) options.minimum = metadata.min;
+  if (metadata.max !== undefined) options.maximum = metadata.max;
+
+  let nextSchema: TSchema = schema;
+  if (Object.keys(options).length > 0) {
+    if (Type.IsString(schema)) nextSchema = Type.String(options);
+    else if (Type.IsNumber(schema) || Type.IsInteger(schema)) nextSchema = metadata.int ? Type.Integer(options) : Type.Number(options);
+    else if (Type.IsBoolean(schema)) nextSchema = Type.Boolean(options);
+    else if (Type.IsArray(schema)) nextSchema = Type.Array(schema.items, options);
+    else nextSchema = Type.Unsafe({ ...schema, ...options });
+  }
+
+  if (metadata.int && Type.IsNumber(nextSchema)) {
+    nextSchema = Type.Integer(options);
+  }
+
+  return metadata.optional ? Type.Optional(nextSchema) : nextSchema;
+}
+
+function literalSchema(value: unknown): TSchema {
+  if (typeof value === "string") return Type.Literal(value);
+  if (typeof value === "number") return Number.isInteger(value) ? Type.Literal(value) : Type.Literal(value);
+  if (typeof value === "boolean") return Type.Literal(value);
+  return Type.Any();
+}
+
+function convertCoreSchema(node: unknown): TSchema {
+  if (!isCoreSchemaNode(node)) {
+    return literalSchema(node);
+  }
+
+  let schema: TSchema;
+  switch (node.kind) {
+    case "string":
+      schema = Type.String();
+      break;
+    case "number":
+      schema = node.metadata?.int ? Type.Integer() : Type.Number();
+      break;
+    case "boolean":
+      schema = Type.Boolean();
+      break;
+    case "any":
+      schema = Type.Any();
+      break;
+    case "array":
+      schema = Type.Array(convertCoreSchema(node.inner));
+      break;
+    case "enum": {
+      const values = Array.isArray(node.values) ? node.values : [];
+      if (values.every((value) => typeof value === "string")) {
+        const valueSet = values;
+        if (arraysEqual(valueSet, ["text", "json"])) {
+          schema = OUTPUT_FORMAT_SCHEMA;
+        } else if (arraysEqual(valueSet, ["shelve", "bring", "cancel"])) {
+          schema = PENDING_CHANGES_SCHEMA;
+        } else if (arraysEqual(valueSet, ["auto", "source", "destination"])) {
+          schema = MERGE_STRATEGY_SCHEMA;
+        } else if (arraysEqual(valueSet, ["ignoreeol", "ignorewhitespaces", "ignoreeolandwhitespaces", "recognizeall"])) {
+          schema = COMPARISON_METHOD_SCHEMA;
+        } else if (arraysEqual(valueSet, ["branch", "changeset"])) {
+          schema = REVIEW_TARGET_TYPE_SCHEMA;
+        } else if (arraysEqual(valueSet, ["date", "branchname"])) {
+          schema = BRANCH_ORDER_BY_SCHEMA;
+        } else if (arraysEqual(valueSet, ["date", "modifieddate", "status"])) {
+          schema = REVIEW_ORDER_BY_SCHEMA;
+        } else {
+          schema = enumSchema(valueSet, metadataDescription(node));
+        }
+      } else {
+        schema = Type.Union(values.map((value) => literalSchema(value)));
+      }
+      break;
+    }
+    case "union": {
+      const values = Array.isArray(node.values) ? node.values : [];
+      const converted = values.map((value) => convertCoreSchema(value));
+      schema = converted.length > 1 ? Type.Union(converted) : (converted[0] ?? Type.Any());
+      break;
+    }
+    default:
+      schema = Type.Any();
+      break;
+  }
+
+  return applySchemaMetadata(schema, node);
+}
+
+function arraysEqual(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function metadataDescription(node: CoreSchemaNode): string {
+  return node.metadata?.description ?? "Allowed values.";
+}
+
+export function buildParameters(args: Record<string, unknown> | undefined): TSchema {
+  if (!args || Object.keys(args).length === 0) {
+    return EMPTY_PARAMETERS;
+  }
+
+  const properties: Record<string, TSchema> = {};
+  for (const [key, value] of Object.entries(args)) {
+    properties[key] = convertCoreSchema(value);
+  }
+  return Type.Object(properties);
+}

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

@@ -0,0 +1,83 @@
+import { isAbsolute } from "node:path";
+import { Type, type TProperties } from "typebox";
+import { Check } from "typebox/value";
+import { assembleServerMergeReceipt, presentServerMergeReceipt, splitServerBranch, type MergeReceipt } from "../operations/server-merge";
+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 changeset = object({ id: Type.String({ pattern: "^(0|[1-9][0-9]{0,19})$" }), branch: str(), repository: str(), server: str(), mount: str() });
+const nullable = <T extends ReturnType<typeof object> | ReturnType<typeof Type.Array>>(s: T) => Type.Union([s, Type.Null()]);
+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 data = {
+    mode: enumOf(["apply", "analyze"]),
+    resolutionsFile: nullable(object({ path: str(), sha256: Type.String({ pattern: "^[a-f0-9]{64}$" }), entries: uint(500), resultFiles: uint(500), keepSource: uint(500), keepDestination: uint(500) })),
+    unlistedConflictPolicy: Type.Union([enumOf(["source", "destination"]), Type.Null()]),
+    requestedIdentity: nullable(object({ source: str(), target: str(), branch: str(), repository: str(), server: str() })),
+    command: nullable(Type.Array(str(8192), { maxItems: 16 })),
+    capability: object({ state: enumOf(["not-checked", "advertised", "missing", "unavailable"]), missingTokens: Type.Array(str(64), { maxItems: 9 }) }),
+    attempt, capture: object({ help: nullable(capture), merge: nullable(capture) }),
+    parse: nullable(object({ records: uint(500), malformed: Type.Boolean(), unknownOperations: uint(500), changesetsObserved: uint(500), conflictsObserved: uint(500) })),
+    observedChangesets: Type.Array(changeset, { maxItems: 100 }), conflictPaths: Type.Array(str(), { maxItems: 100 }),
+    counts: object({ changesetsReturned: uint(100), changesetsOmitted: uint(500), conflictsReturned: uint(100), conflictsOmitted: uint(500) }),
+    serverAliasEquivalence: Type.Literal("unverified"), mergeLinkIdentity: Type.Literal("unverified"), xlinkEffects: Type.Literal("unverified"), wouldRun: Type.Boolean(), remoteAnalysis: enumOf(["not-performed", "performed"]),
+};
+const header = { schemaVersion: Type.Literal(1), action: Type.Literal("merge-branches"), 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: enumOf(["invalid_request", "capability_unavailable", "unsupported", "aborted", "launch_failed", "conflict", "uncertain", "producer_failed"]), stage: enumOf(["input", "help", "merge", "producer"]), message: str(256) });
+export const serverMergeOutputSchema = Type.Unsafe<MergeReceipt>(Type.Union([
+    object({ ...header, ok: Type.Literal(true), outcome: Type.Literal("completed"), data: object({ ...data, createdChangeset: changeset, effect: Type.Literal("changeset-created") }) }),
+    object({ ...header, ok: Type.Literal(true), outcome: Type.Literal("analyzed"), data: object({ ...data, createdChangeset: Type.Null(), effect: Type.Literal("not-attempted") }) }),
+    object({ ...header, ok: Type.Literal(true), outcome: Type.Literal("preflight"), data: object({ ...data, createdChangeset: Type.Null(), effect: Type.Literal("not-attempted") }) }),
+    object({ ...header, ok: Type.Literal(true), outcome: Type.Literal("no-op"), data: object({ ...data, createdChangeset: Type.Null(), effect: Type.Literal("not-proven") }) }),
+    object({ ...header, ok: Type.Literal(false), outcome: enumOf(["failed", "unsupported"]), error, data: object({ ...data, createdChangeset: Type.Null(), effect: Type.Literal("not-attempted") }) }),
+    object({ ...header, ok: Type.Literal(false), outcome: enumOf(["conflict", "uncertain"]), error, data: object({ ...data, createdChangeset: Type.Null(), effect: Type.Literal("uncertain") }) }),
+]));
+export function validateServerMergeOutput(value: unknown): value is MergeReceipt {
+    if (!Check(serverMergeOutputSchema, value) || Buffer.byteLength(JSON.stringify(value), "utf8") > 131072) return false;
+    const dto = value as MergeReceipt, d = dto.data, a = d.attempt, p = d.parse;
+    const safeText = (s: string) => !/[\u0000-\u001f\u007f-\u009f]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(s);
+    for (const cs of [...d.observedChangesets, ...(d.createdChangeset ? [d.createdChangeset] : [])]) if (!splitServerBranch("br:" + cs.branch + "@" + cs.repository + "@" + cs.server) || ![cs.branch, cs.repository, cs.server, cs.mount].every(safeText)) return false;
+    if (!d.conflictPaths.every(s => s.startsWith("/") && safeText(s))) return false;
+    if (!p && (d.observedChangesets.length || d.conflictPaths.length || Object.values(d.counts).some(Boolean))) return false;
+    if (dto.completeness.capture === "complete" && !(d.capture.merge?.complete ?? d.capture.help?.complete)) return false;
+    if (dto.outcome === "preflight" && dto.completeness.capture !== "unknown") return false;
+    if (d.resolutionsFile && (d.resolutionsFile.resultFiles + d.resolutionsFile.keepSource + d.resolutionsFile.keepDestination !== d.resolutionsFile.entries || !safeText(d.resolutionsFile.path) || !isAbsolute(d.resolutionsFile.path))) return false;
+    if (d.mode === "analyze" && (d.resolutionsFile || d.unlistedConflictPolicy || d.command?.some(a => a === "--merge" || a.startsWith("-c=") || a.startsWith("--fileconflictsresolutionsfile=") || a === "--keepsource" || a === "--keepdestination"))) return false;
+    if (dto.outcome === "analyzed" && (d.mode !== "analyze" || d.remoteAnalysis !== "performed" || a.exitCode !== 0 || !d.command || !d.requestedIdentity || d.command[0] !== "cm" || d.command[1] !== "merge" || !d.command.includes("--nointeractiveresolution") || d.capture.merge?.stderrBytes || p?.changesetsObserved !== 0 || !p.records || dto.completeness.capture !== "complete")) return false;
+    if (dto.outcome !== "analyzed" && d.remoteAnalysis !== "not-performed") return false;
+    if (["completed", "no-op", "conflict"].includes(dto.outcome) && d.mode !== "apply") return false;
+    if (a.exitCode !== null && a.terminal !== "observed") return false;
+    if (["preflight", "unsupported", "failed"].includes(dto.outcome) && !["not-attempted", "not-started"].includes(a.state)) return false;
+    if (["completed", "no-op", "conflict", "analyzed"].includes(dto.outcome) && (a.state !== "started" || a.terminal !== "observed" || a.exitCode === null || a.aborted || a.timedOut || !d.capture.merge?.complete || !p || p.malformed || p.unknownOperations)) return false;
+    if (dto.outcome === "preflight" && (d.capture.help !== null || d.capture.merge !== null || d.capability.state !== "not-checked" || !d.command || !d.requestedIdentity || !d.wouldRun)) return false;
+    if (d.requestedIdentity) {
+        const s = splitServerBranch(d.requestedIdentity.source), t = splitServerBranch(d.requestedIdentity.target);
+        if (!s || !t || s.repository !== t.repository || s.server !== t.server || t.branch !== d.requestedIdentity.branch || t.repository !== d.requestedIdentity.repository || t.server !== d.requestedIdentity.server || s.branch === t.branch) return false;
+    }
+    const c = d.counts;
+    if (c.changesetsReturned + c.conflictsReturned > 100) return false;
+    if (c.changesetsReturned !== d.observedChangesets.length || c.conflictsReturned !== d.conflictPaths.length || p && (c.changesetsReturned + c.changesetsOmitted !== p.changesetsObserved || c.conflictsReturned + c.conflictsOmitted !== p.conflictsObserved)) return false;
+    if ((c.changesetsOmitted || c.conflictsOmitted) && dto.completeness.projection) return false;
+    if (dto.outcome === "completed" && (a.exitCode !== 0 || !d.requestedIdentity || !d.createdChangeset || d.createdChangeset.branch !== d.requestedIdentity.branch || d.createdChangeset.repository !== d.requestedIdentity.repository || d.createdChangeset.mount !== "/" || p?.changesetsObserved !== 1 || p.conflictsObserved !== 0)) return false;
+    if (dto.outcome === "no-op" && (a.exitCode !== 0 || p?.changesetsObserved !== 0 || p.conflictsObserved !== 0)) return false;
+    if (dto.outcome === "conflict" && (a.exitCode === 0 || p?.changesetsObserved !== 0 || !p.conflictsObserved)) return false;
+    for (const cap of [d.capture.help, d.capture.merge]) if (cap && (cap.stdoutRetainedBytes > cap.stdoutBytes || cap.stderrRetainedBytes > cap.stderrBytes || cap.complete && (!cap.validUtf8 || cap.truncated))) return false;
+    return true;
+}
+export async function executeServerMergeOutput(args: unknown) {
+    let dto = await assembleServerMergeReceipt(args);
+    const valid: boolean = validateServerMergeOutput(dto);
+    if (!valid) {
+        const mayHaveStarted = dto.data.attempt.state === "started" || dto.data.attempt.state === "unknown";
+        // Build a minimal bounded failure with no commands; damaged producer fields
+        // must not survive as apparently verified identities/capture facts.
+        const safe = await assembleServerMergeReceipt({});
+        dto = { ...safe, ok: false, outcome: mayHaveStarted ? "uncertain" : "failed", data: { ...safe.data, attempt: { ...safe.data.attempt, state: mayHaveStarted ? "unknown" : "not-attempted" }, effect: mayHaveStarted ? "uncertain" : "not-attempted" }, completeness: { capture: "unknown", projection: false }, error: { code: "producer_failed", stage: "producer", message: "The bounded server merge receipt could not be verified; do not retry automatically." } } as MergeReceipt;
+        if (!validateServerMergeOutput(dto)) throw new Error("The safe server merge receipt could not be constructed.");
+    }
+    const json = (args as { format?: unknown })?.format === "json";
+    let text = json ? JSON.stringify(dto) : await presentServerMergeReceipt(dto);
+    if (text.length > 24000) text = JSON.stringify({ action: dto.action, outcome: dto.outcome, ok: dto.ok, note: "Presentation omitted; inspect structuredContent for the bounded receipt." });
+    return { content: [{ type: "text" as const, text }], details: {}, structuredContent: dto, isError: !dto.ok };
+}

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

@@ -0,0 +1,50 @@
+import { Type, type Static, type TSchema } from "typebox";
+import { Check } from "typebox/value";
+import { assembleShelvesetListObservation, presentShelvesetListObservation, shelvesetListPayload, ShelvesetListError, validShelvesetId, validShelvesetQueryString, SHELVESET_LIST_MAX_BYTES, type ShelvesetListArgs } from "../operations/shelveset-list";
+import { ShelvesetListCommandError } from "../execution/shelveset-list-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({ owner: queryString, commentLike: queryString, dateFrom: queryString, limit: nullable(Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER })) });
+const common = { schemaVersion: Type.Literal(1), action: Type.Literal("shelveset-list"), 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 shelvesetListOutputSchema = 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_shelve_id_utf8"), diagnostics: object({ duplicateRecords: integer(19999) }), rows: Type.Array(object({ id: Type.String({ minLength: 1, maxLength: 20, pattern: "^(?:0|[1-9][0-9]*)$" }), shelveset: Type.String({ minLength: 4, maxLength: 23, pattern: "^sh:(?: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_shelve_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 ShelvesetListOutput = Static<typeof shelvesetListOutputSchema>;
+export type ShelvesetListErrorCode = Extract<ShelvesetListOutput, { ok: false }>["error"]["code"];
+const failure = (code: ShelvesetListErrorCode): ShelvesetListOutput => ({ schemaVersion: 1, action: "shelveset-list", provenance: { source: "plastic", producer: "@aefree/pi-plastic", contentTrust: "external" }, ok: false, completeness: { read: "incomplete", capture: "unknown", projection: false }, error: { code, message: `Shelveset list read failed (${code}); no reusable rows are available.` } });
+export function validateShelvesetListOutput(value: unknown): ShelvesetListOutput {
+    if (!Check(shelvesetListOutputSchema, value)) return failure("invalid_producer_data");
+    const dto = value as ShelvesetListOutput;
+    if (dto.ok) {
+        if ([dto.data.query.owner, dto.data.query.commentLike, dto.data.query.dateFrom].some(value => value !== null && !validShelvesetQueryString(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 => !validShelvesetId(row.id) || row.shelveset !== `sh:${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") > SHELVESET_LIST_MAX_BYTES) return failure("output_overflow");
+    return dto;
+}
+export async function executeShelvesetListOutput(args: ShelvesetListArgs) {
+    let dto: ShelvesetListOutput, rawResult: string | undefined;
+    try {
+        const observation = await assembleShelvesetListObservation(args, true);
+        if (getActiveAbortSignal()?.aborted) throw new ShelvesetListCommandError("aborted");
+        dto = validateShelvesetListOutput(shelvesetListPayload(observation));
+        if (dto.ok) rawResult = args.output === "json" ? JSON.stringify(dto) : presentShelvesetListObservation(observation);
+        if (getActiveAbortSignal()?.aborted) throw new ShelvesetListCommandError("aborted");
+    } catch (error) { dto = failure(error instanceof ShelvesetListError || error instanceof ShelvesetListCommandError ? error.code : "invalid_producer_data"); }
+    dto = validateShelvesetListOutput(dto);
+    return { content: [{ type: "text" as const, text: dto.ok ? rawResult! : dto.error.message }], structuredContent: dto, isError: !dto.ok, details: { exportName: "shelvesetList", rawResult: dto.ok ? rawResult : undefined, ...(args.workdir ? { workdir: args.workdir } : {}) } };
+}