@osovv/vv-opencode 1.4.5 → 1.6.0

package/dist/plugins/workflow/input-validation.js

@@ -0,0 +1,536 @@
+// FILE: src/plugins/workflow/input-validation.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Own strict branch-aware runtime input validation for all five vvoc workflow tools: owned-tool contracts over the registered argument maps, canonical standalone/generic/checkpoint/decision/authority branch rules, an args-only allowed/required field matrix for every action and decision, whitespace/omission normalization, and the exported validateWorkflowToolInput entry shared by the tool.execute.before hook and every direct handler.
+//   SCOPE: Structural full-object parsing (unknown keys, enums, owning-validator bounds, closed nested shapes), documented trim with field-specific blank rejection from the contract schema, plus args-only branch conditions from the approved workflow branch matrix: execution/runId exclusivity, standalone versus generic item rules, source variants, action-specific required fields, recognized-field conflicts with the selected action/decision, bounded decision/recovery fields, and authority stage/stop validity. No store lookup, no state eligibility, no permission decisions, no filesystem or SDK session access.
+//   DEPENDS: [src/lib/agent-tool-contract.ts, src/lib/workflow-contract.ts, src/plugins/workflow/schemas.ts]
+//   LINKS: [M-WORKFLOW-TOOLING, M-AGENT-TOOL-CONTRACT, M-WORKFLOW-CONTRACT, M-PLUGIN-WORKFLOW]
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   WORKFLOW_TOOL_IDS - Canonical ids of the five vvoc-owned workflow tools.
+//   WorkflowToolId - Union of the five workflow tool ids.
+//   isWorkflowToolId - Whether a value names an owned workflow tool.
+//   WORKFLOW_TOOL_DESCRIPTIONS - Canonical public descriptions shared by registrations and contracts.
+//   WorkflowToolInputMap - Schema-derived argument type per workflow tool id.
+//   WorkflowToolValidation - Successful parsed arguments or bounded structural/branch issues.
+//   validateWorkflowToolInput - Strict structural plus branch validation for one workflow tool call.
+//   assertWorkflowToolInput - Throwing guard mirroring the owned pre-execute contract, including branch rules.
+//   workflowToolContracts - Owned-tool contracts for the five workflow tools.
+//   getWorkflowToolContract - Contract lookup by tool id.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [C-AGENT-TOOL-CONTRACTS T-002 - Initial branch-aware workflow tool input validation with exported validateWorkflowToolInput, owned contracts, and canonical descriptions; correction cycle adds an args-only action/decision field matrix, bounded branch diagnostics with precise indexed boundary paths, and shared generic task branch validation for both work_item_open items and work_checkpoint register/amend tasks. Field-specific trims/bounds now live in the contract schema so no blanket recursive string rejection is applied.]
+// END_CHANGE_SUMMARY
+import { ContractInputError, MAX_CONTRACT_ISSUES, MAX_ISSUE_MESSAGE_CHARS, MAX_ISSUE_PATH_CHARS, MAX_ISSUE_VALUE_CHARS, defineOwnedToolContract, formatIssuePath, summarizeReceivedValue, } from "../../lib/agent-tool-contract.js";
+import { normalizeDeclaredScopePath, validateExecutionBoundary, } from "../../lib/workflow-contract.js";
+import { workCheckpointArgs, workItemCloseArgs, workItemDecideArgs, workItemListArgs, workItemOpenArgs, } from "./schemas.js";
+// START_BLOCK_TOOL_IDS
+/** Canonical ids of the five vvoc-owned workflow tools. */
+export const WORKFLOW_TOOL_IDS = [
+    "work_item_open",
+    "work_item_list",
+    "work_item_close",
+    "work_item_decide",
+    "work_checkpoint",
+];
+/** Whether a value names an owned workflow tool. */
+export function isWorkflowToolId(value) {
+    return typeof value === "string" && WORKFLOW_TOOL_IDS.includes(value);
+}
+/** Canonical public descriptions shared by registrations and contracts. */
+export const WORKFLOW_TOOL_DESCRIPTIONS = {
+    work_item_open: "Open one or more workflow work items idempotently with explicit mode and requiredReviewers.",
+    work_item_list: "List workflow work items for the current session.",
+    work_item_close: "Close a workflow work item by id when it is ready_to_close.",
+    work_item_decide: "Accept or request changes for the current completed delegated attempt, authorize bounded rework of an accepted task from a failed checkpoint, or recover a stopped or exhausted unaccepted task with a bounded diagnosis and changed condition.",
+    work_checkpoint: "Register an approved delegated plan, start a declared review checkpoint, verify checkpoint outcomes, or recover a stopped or generation-exhausted checkpoint; verify with complete: true seals a finished final checkpoint.",
+};
+const contracts = {
+    work_item_open: defineOwnedToolContract({
+        toolId: "work_item_open",
+        description: WORKFLOW_TOOL_DESCRIPTIONS.work_item_open,
+        registeredArgs: workItemOpenArgs,
+    }),
+    work_item_list: defineOwnedToolContract({
+        toolId: "work_item_list",
+        description: WORKFLOW_TOOL_DESCRIPTIONS.work_item_list,
+        registeredArgs: workItemListArgs,
+    }),
+    work_item_close: defineOwnedToolContract({
+        toolId: "work_item_close",
+        description: WORKFLOW_TOOL_DESCRIPTIONS.work_item_close,
+        registeredArgs: workItemCloseArgs,
+    }),
+    work_item_decide: defineOwnedToolContract({
+        toolId: "work_item_decide",
+        description: WORKFLOW_TOOL_DESCRIPTIONS.work_item_decide,
+        registeredArgs: workItemDecideArgs,
+    }),
+    work_checkpoint: defineOwnedToolContract({
+        toolId: "work_checkpoint",
+        description: WORKFLOW_TOOL_DESCRIPTIONS.work_checkpoint,
+        registeredArgs: workCheckpointArgs,
+    }),
+};
+/** Owned-tool contracts for the five workflow tools. */
+export const workflowToolContracts = [
+    contracts.work_item_open,
+    contracts.work_item_list,
+    contracts.work_item_close,
+    contracts.work_item_decide,
+    contracts.work_checkpoint,
+];
+/** Contract lookup by tool id. */
+export function getWorkflowToolContract(toolId) {
+    return contracts[toolId];
+}
+// END_BLOCK_CONTRACTS
+// START_BLOCK_BRANCH_ISSUES
+function truncateChars(value, max) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, Math.max(0, max - 1))}…`;
+}
+/** Bound one branch-level issue so every claimed-bounded diagnostic is finite. */
+function boundedIssue(issue) {
+    return {
+        code: issue.code,
+        path: truncateChars(issue.path, MAX_ISSUE_PATH_CHARS),
+        message: truncateChars(issue.message, MAX_ISSUE_MESSAGE_CHARS),
+        ...(issue.expected !== undefined
+            ? { expected: truncateChars(issue.expected, MAX_ISSUE_MESSAGE_CHARS) }
+            : {}),
+        ...(issue.received !== undefined
+            ? { received: truncateChars(issue.received, MAX_ISSUE_VALUE_CHARS) }
+            : {}),
+    };
+}
+function pushIssue(issues, issue) {
+    if (issues.length >= MAX_CONTRACT_ISSUES)
+        return;
+    issues.push(boundedIssue(issue));
+}
+function missingIssue(issues, path, message, expected) {
+    pushIssue(issues, {
+        code: "missing_value",
+        path: formatIssuePath(path),
+        message,
+        expected,
+    });
+}
+function conflictIssue(issues, path, message, expected) {
+    pushIssue(issues, {
+        code: "invalid_value",
+        path: formatIssuePath(path),
+        message,
+        expected,
+    });
+}
+function requireNonEmpty(issues, value, path, label) {
+    if (value === undefined || value.trim() === "") {
+        missingIssue(issues, path, `${label} must be a non-empty string`, `a non-empty ${label}`);
+    }
+}
+function requireNonEmptyList(issues, values, path, label) {
+    if (values === undefined || values.length === 0) {
+        missingIssue(issues, path, `${label} must be a non-empty array`, `at least one ${label} entry`);
+        return;
+    }
+    values.forEach((entry, index) => {
+        if (entry.trim() === "") {
+            missingIssue(issues, [...path, index], `${label} entries must be non-empty strings`, `a non-empty ${label} entry`);
+        }
+    });
+}
+// END_BLOCK_BRANCH_ISSUES
+// START_BLOCK_OPEN_BRANCHES
+const GENERIC_TASK_FIELDS = [
+    "taskId",
+    "goal",
+    "acceptanceCriteria",
+    "verification",
+    "dependsOn",
+    "blockedBy",
+];
+function validateDeclaredFileList(issues, entries, path) {
+    const seen = new Set();
+    entries.forEach((entry, index) => {
+        const normalized = normalizeDeclaredScopePath(entry);
+        if (!normalized.ok) {
+            conflictIssue(issues, [...path, index], `path ${summarizeReceivedValue(entry)} is malformed (${normalized.reason})`, "a workspace-relative exact file path without traversal, wildcards, or trailing separators");
+            return;
+        }
+        if (seen.has(normalized.path)) {
+            conflictIssue(issues, [...path, index], `path ${summarizeReceivedValue(normalized.path)} is declared more than once`, "unique file paths");
+            return;
+        }
+        seen.add(normalized.path);
+    });
+}
+/**
+ * Validate one task/work-item entry against its mode. `base` is the exact token
+ * path to the entry (`["items", i]` for work_item_open, `["tasks", i]` for
+ * work_checkpoint register/amend) so both entry routes share the same rules and
+ * report their own indexed paths.
+ */
+function validateOpenItemBranch(issues, item, base, generic) {
+    if (generic) {
+        if (item.mode !== "delegated") {
+            conflictIssue(issues, [...base, "mode"], "generic open/append items require mode delegated", '"delegated"');
+        }
+        if (item.planRunId !== undefined || item.planTaskId !== undefined) {
+            conflictIssue(issues, [...base, "planRunId"], "native plan bindings conflict with generic open/append items", "no planRunId/planTaskId on generic tasks");
+        }
+        if (item.writeScope === undefined || item.writeScope.length === 0) {
+            missingIssue(issues, [...base, "writeScope"], "generic tasks require a non-empty writeScope of workspace-relative files", "at least one workspace-relative file path");
+        }
+        else {
+            validateDeclaredFileList(issues, item.writeScope, [...base, "writeScope"]);
+        }
+        if (new Set(item.requiredReviewers).size !== item.requiredReviewers.length) {
+            conflictIssue(issues, [...base, "requiredReviewers"], "requiredReviewers must be a unique spec/code array", "unique canonical reviewer roles");
+        }
+        return;
+    }
+    for (const field of GENERIC_TASK_FIELDS) {
+        if (item[field] !== undefined) {
+            conflictIssue(issues, [...base, field], `${field} is a generic task field and conflicts with standalone work_item_open items`, "generic task fields only on execution/runId open or work_checkpoint amendments");
+        }
+    }
+    if (item.mode === "delegated") {
+        if (item.requiredReviewers.length !== 0) {
+            conflictIssue(issues, [...base, "requiredReviewers"], "delegated mode requires an explicitly empty requiredReviewers array", "[]");
+        }
+        if (item.writeScope === undefined || item.writeScope.length === 0) {
+            missingIssue(issues, [...base, "writeScope"], "delegated mode requires a non-empty writeScope of workspace-relative files", "at least one workspace-relative file path");
+        }
+        else {
+            validateDeclaredFileList(issues, item.writeScope, [...base, "writeScope"]);
+        }
+        if ((item.planRunId === undefined) !== (item.planTaskId === undefined)) {
+            const offending = item.planRunId === undefined ? "planRunId" : "planTaskId";
+            conflictIssue(issues, [...base, offending], "planRunId and planTaskId must be provided together", "both native plan bindings or neither");
+        }
+        return;
+    }
+    // standalone implementation / review_only
+    if (item.requiredReviewers.length === 0) {
+        missingIssue(issues, [...base, "requiredReviewers"], "standalone implementation/review_only require a non-empty unique reviewer set", "at least one canonical spec/code reviewer");
+    }
+    else if (new Set(item.requiredReviewers).size !== item.requiredReviewers.length) {
+        conflictIssue(issues, [...base, "requiredReviewers"], "requiredReviewers must be a unique spec/code array", "unique canonical reviewer roles");
+    }
+    if (item.writeScope !== undefined) {
+        conflictIssue(issues, [...base, "writeScope"], `writeScope is only valid for delegated mode, not ${item.mode}`, "no writeScope on standalone implementation/review_only items");
+    }
+    if (item.planRunId !== undefined || item.planTaskId !== undefined) {
+        const offending = item.planRunId !== undefined ? "planRunId" : "planTaskId";
+        conflictIssue(issues, [...base, offending], `plan bindings are only valid for delegated mode, not ${item.mode}`, "no plan bindings on standalone implementation/review_only items");
+    }
+}
+function validateOpenBranches(issues, data) {
+    const hasExecution = data.execution !== undefined;
+    const hasRunId = data.runId !== undefined;
+    if (hasExecution && hasRunId) {
+        conflictIssue(issues, ["execution"], "execution and runId are mutually exclusive", "exactly one of execution (register) or runId (append)");
+    }
+    if (hasExecution) {
+        // Amendment context belongs to runId appends only; a registration must not
+        // silently drop supplied append-only fields.
+        for (const field of ["amendmentId", "rationale"]) {
+            if (data[field] !== undefined) {
+                conflictIssue(issues, [field], `${field} is append-only amendment context and conflicts with execution registration`, "runId with amendment context instead of execution");
+            }
+        }
+    }
+    if (!hasExecution && !hasRunId) {
+        if (data.amendmentId !== undefined || data.rationale !== undefined) {
+            conflictIssue(issues, ["amendmentId"], "amendmentId and rationale are only valid with runId appends", "runId with amendment context");
+        }
+    }
+    const generic = hasExecution || hasRunId;
+    data.items.forEach((item, index) => validateOpenItemBranch(issues, item, ["items", index], generic));
+    if (data.execution) {
+        const boundary = validateExecutionBoundary(data.execution.boundary);
+        if (!boundary.ok) {
+            for (const problem of boundary.problems) {
+                pushIssue(issues, {
+                    code: problem.code === "EMPTY_BOUNDARY" ? "missing_value" : "invalid_value",
+                    // The pure boundary validator supplies the indexed file/directory path;
+                    // never reconstruct it by parsing the prose message.
+                    path: formatIssuePath(["execution", ...(problem.path ?? ["boundary"])]),
+                    message: problem.message,
+                    expected: "normalized non-empty exact files or directory subtrees",
+                });
+            }
+        }
+    }
+    if (hasRunId) {
+        requireNonEmpty(issues, data.runId, ["runId"], "runId");
+        requireNonEmpty(issues, data.amendmentId, ["amendmentId"], "amendmentId");
+        requireNonEmpty(issues, data.rationale, ["rationale"], "rationale");
+    }
+}
+// END_BLOCK_OPEN_BRANCHES
+// START_BLOCK_DECIDE_BRANCHES
+/**
+ * Args-only field matrix for work_item_decide, derived from the fields each
+ * decision branch actually consumes. A recognized field supplied for a
+ * different decision is rejected instead of being silently ignored.
+ */
+const DECIDE_DECISION_FIELDS = {
+    accept: ["workItemId", "attempt", "decision", "rationale", "evidence", "concernsDisposition"],
+    request_changes: [
+        "workItemId",
+        "attempt",
+        "decision",
+        "rationale",
+        "evidence",
+        "concernsDisposition",
+    ],
+    rework: ["workItemId", "attempt", "decision", "runId", "checkpointId", "rationale"],
+    recover: [
+        "workItemId",
+        "attempt",
+        "decision",
+        "recoveryId",
+        "diagnosis",
+        "changedCondition",
+        "verification",
+        "userMessageId",
+        "authorityId",
+        "runId",
+    ],
+};
+function validateDecideFieldMatrix(issues, data) {
+    const allowed = new Set(DECIDE_DECISION_FIELDS[data.decision]);
+    for (const key of Object.keys(data)) {
+        const value = data[key];
+        if (value === undefined || allowed.has(key))
+            continue;
+        conflictIssue(issues, [key], `${key} is not consumed by decision ${data.decision}`, `only ${[...allowed].join(", ")}`);
+    }
+}
+function validateDecideBranches(issues, data) {
+    validateDecideFieldMatrix(issues, data);
+    requireNonEmpty(issues, data.workItemId, ["workItemId"], "workItemId");
+    if (data.concernsDisposition !== undefined && data.concernsDisposition.trim() === "") {
+        missingIssue(issues, ["concernsDisposition"], "concernsDisposition must be a non-empty string when provided", "a non-empty concerns disposition");
+    }
+    if (data.decision === "accept" || data.decision === "request_changes") {
+        requireNonEmpty(issues, data.rationale, ["rationale"], "rationale");
+        requireNonEmptyList(issues, data.evidence, ["evidence"], "evidence");
+        return;
+    }
+    if (data.decision === "rework") {
+        requireNonEmpty(issues, data.runId, ["runId"], "runId");
+        requireNonEmpty(issues, data.checkpointId, ["checkpointId"], "checkpointId");
+        return;
+    }
+    // recover
+    requireNonEmpty(issues, data.recoveryId, ["recoveryId"], "recoveryId");
+    requireNonEmpty(issues, data.diagnosis, ["diagnosis"], "diagnosis");
+    requireNonEmpty(issues, data.changedCondition, ["changedCondition"], "changedCondition");
+    requireNonEmptyList(issues, data.verification, ["verification"], "verification");
+    if (data.authorityId !== undefined) {
+        requireNonEmpty(issues, data.runId, ["runId"], "runId");
+    }
+    else if (data.runId !== undefined) {
+        // runId is only consumed by recover when it owns the advance authority;
+        // without authorityId it would be silently ignored.
+        conflictIssue(issues, ["runId"], "runId is only consumed by recover together with an authorityId", "authorityId with its owning runId, or neither");
+    }
+}
+// END_BLOCK_DECIDE_BRANCHES
+// START_BLOCK_CHECKPOINT_BRANCHES
+/**
+ * Args-only allowed-field matrix for work_checkpoint, derived from the fields
+ * each action branch (native and generic) actually consumes. A recognized field
+ * supplied for a different action is rejected instead of being silently ignored;
+ * fields that are only valid on one source variant stay allowed here and are
+ * resolved by the source lookup in tooling.ts.
+ */
+const CHECKPOINT_ACTION_FIELDS = {
+    register: ["planPath", "runId", "amendmentId", "rationale", "tasks", "checkpoints"],
+    start: ["runId", "checkpointId", "startFingerprint"],
+    verify: ["runId", "checkpointId", "complete", "reviewer"],
+    recover: [
+        "runId",
+        "checkpointId",
+        "recoveryId",
+        "diagnosis",
+        "changedCondition",
+        "verification",
+        "userMessageId",
+        "authorityId",
+    ],
+    review: ["runId", "checkpointId", "reviewer"],
+    bind: ["runId", "checkpointId", "reviewer"],
+    complete: ["runId", "rationale", "verification"],
+    amend: ["runId", "amendmentId", "rationale", "tasks", "checkpoints"],
+    authorize: [
+        "runId",
+        "authorityId",
+        "messageId",
+        "stages",
+        "decisionScope",
+        "fileBoundary",
+        "reservedStops",
+    ],
+    record_approval: [
+        "runId",
+        "authorityId",
+        "approvalId",
+        "stage",
+        "artifactPath",
+        "artifactSha256",
+    ],
+    revoke_authority: ["runId", "authorityId", "revocationId", "stages", "rationale"],
+};
+function validateCheckpointFieldMatrix(issues, data) {
+    const allowed = new Set(CHECKPOINT_ACTION_FIELDS[data.action]);
+    for (const key of Object.keys(data)) {
+        if (key === "action")
+            continue;
+        const value = data[key];
+        if (value === undefined || allowed.has(key))
+            continue;
+        conflictIssue(issues, [key], `${key} is not consumed by action ${data.action}`, `only ${[...allowed].join(", ")}`);
+    }
+}
+function validateCheckpointBranches(issues, data) {
+    validateCheckpointFieldMatrix(issues, data);
+    const hasPlanPath = data.planPath !== undefined;
+    const hasRunId = data.runId !== undefined;
+    const action = data.action;
+    // Generic register/amend tasks obey the same branch rules as work_item_open
+    // generic items; without this they reached the store with a conflicting mode
+    // or native bindings silently erased.
+    if ((action === "register" || action === "amend") && hasRunId && data.tasks !== undefined) {
+        data.tasks.forEach((task, index) => validateOpenItemBranch(issues, task, ["tasks", index], true));
+    }
+    if (action === "register") {
+        if (hasPlanPath && hasRunId) {
+            conflictIssue(issues, ["runId"], "register accepts either planPath (native package) or runId (generic amend context), not both", "exactly one registration route");
+        }
+        if (hasPlanPath) {
+            // Native package registration loads the plan itself; generic task and
+            // amendment fields are not consumed and must not be silently ignored.
+            for (const field of ["amendmentId", "rationale", "tasks", "checkpoints"]) {
+                if (data[field] !== undefined) {
+                    conflictIssue(issues, [field], `${field} is generic register/amend context and conflicts with native planPath registration`, "no generic registration fields with planPath");
+                }
+            }
+        }
+        if (!hasPlanPath) {
+            if (!hasRunId) {
+                missingIssue(issues, ["runId"], "generic register requires the target runId of an existing execution", "the existing execution runId");
+            }
+            requireNonEmpty(issues, data.amendmentId, ["amendmentId"], "amendmentId");
+            requireNonEmpty(issues, data.rationale, ["rationale"], "rationale");
+        }
+    }
+    else if (!hasRunId) {
+        missingIssue(issues, ["runId"], `action ${action} requires the target runId`, "the target execution runId");
+    }
+    switch (action) {
+        case "start":
+        case "verify":
+        case "review":
+        case "bind":
+            requireNonEmpty(issues, data.checkpointId, ["checkpointId"], "checkpointId");
+            return;
+        case "recover":
+            requireNonEmpty(issues, data.runId, ["runId"], "runId");
+            requireNonEmpty(issues, data.checkpointId, ["checkpointId"], "checkpointId");
+            requireNonEmpty(issues, data.recoveryId, ["recoveryId"], "recoveryId");
+            requireNonEmpty(issues, data.diagnosis, ["diagnosis"], "diagnosis");
+            requireNonEmpty(issues, data.changedCondition, ["changedCondition"], "changedCondition");
+            requireNonEmptyList(issues, data.verification, ["verification"], "verification");
+            return;
+        case "amend":
+            requireNonEmpty(issues, data.runId, ["runId"], "runId");
+            requireNonEmpty(issues, data.amendmentId, ["amendmentId"], "amendmentId");
+            requireNonEmpty(issues, data.rationale, ["rationale"], "rationale");
+            return;
+        case "complete":
+            return;
+        case "authorize":
+            requireNonEmpty(issues, data.authorityId, ["authorityId"], "authorityId");
+            requireNonEmpty(issues, data.messageId, ["messageId"], "messageId");
+            if (data.stages === undefined || data.stages.length === 0) {
+                missingIssue(issues, ["stages"], "authorize requires explicit delegatable stages", "at least one canonical authority stage");
+            }
+            return;
+        case "record_approval":
+            requireNonEmpty(issues, data.authorityId, ["authorityId"], "authorityId");
+            requireNonEmpty(issues, data.approvalId, ["approvalId"], "approvalId");
+            if (data.stage === undefined) {
+                missingIssue(issues, ["stage"], "record_approval requires an authority stage", "a canonical authority stage");
+            }
+            requireNonEmpty(issues, data.artifactPath, ["artifactPath"], "artifactPath");
+            requireNonEmpty(issues, data.artifactSha256, ["artifactSha256"], "artifactSha256");
+            return;
+        case "revoke_authority":
+            requireNonEmpty(issues, data.authorityId, ["authorityId"], "authorityId");
+            requireNonEmpty(issues, data.revocationId, ["revocationId"], "revocationId");
+            return;
+        default:
+            return;
+    }
+}
+// END_BLOCK_CHECKPOINT_BRANCHES
+// START_BLOCK_VALIDATE_ENTRY
+/**
+ * Strict structural plus branch validation for one workflow tool call.
+ * Unknown keys, enums, and nested shapes fail first; empty-after-trim supplied
+ * values fail next for the whole request; then the args-only branch matrix
+ * enforces required fields and rejects recognized fields that conflict with the
+ * selected action or decision. Every issue carries a bounded tokenized path.
+ * The result never mutates the input and never confers state/permission eligibility.
+ */
+export function validateWorkflowToolInput(toolId, rawArgs) {
+    const contract = contracts[toolId];
+    // The contract schema already applies the documented trim and rejects a
+    // supplied blank on every field whose owning validator requires non-empty
+    // (whole-request structural rejection before any item opens). Empty content
+    // that is a documented default (decisionScope) stays representable.
+    const parsed = contract.safeParse(rawArgs);
+    if (!parsed.success) {
+        return { ok: false, issues: parsed.issues };
+    }
+    const issues = [];
+    switch (toolId) {
+        case "work_item_open":
+            validateOpenBranches(issues, parsed.data);
+            break;
+        case "work_item_list":
+            break;
+        case "work_item_close":
+            requireNonEmpty(issues, parsed.data.workItemId, ["workItemId"], "workItemId");
+            break;
+        case "work_item_decide":
+            validateDecideBranches(issues, parsed.data);
+            break;
+        case "work_checkpoint":
+            validateCheckpointBranches(issues, parsed.data);
+            break;
+    }
+    if (issues.length > 0) {
+        return { ok: false, issues };
+    }
+    return { ok: true, data: parsed.data };
+}
+/** Throwing guard mirroring the owned pre-execute contract, including branch rules. */
+export function assertWorkflowToolInput(toolId, rawArgs) {
+    const result = validateWorkflowToolInput(toolId, rawArgs);
+    if (!result.ok) {
+        throw new ContractInputError(toolId, result.issues);
+    }
+}
+// END_BLOCK_VALIDATE_ENTRY
+//# sourceMappingURL=input-validation.js.map

package/dist/plugins/workflow/input-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-validation.js","sourceRoot":"","sources":["../../../src/plugins/workflow/input-validation.ts"],"names":[],"mappings":"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"}

package/dist/plugins/workflow/inspection.d.ts

@@ -0,0 +1,60 @@
+import { type WorkItemRecord, type WorkItemStore, type WorkItemStoreData } from "./state.js";
+import { summarizeDelegatedProgress, type DelegatedNextAction } from "./delegated.js";
+import { latestAttemptView } from "./execution.js";
+import type { WorkflowContractIdentity, WorkflowDelegatedRunView, WorkflowExecutionView, WorkflowWorkItemView } from "./results.js";
+/**
+ * Gate-derived guidance for one delegated work item. `nextAction` always agrees
+ * with the shared launch/decision gates; `blockers` names the exact gate reason
+ * (with the offending task or checkpoint id) when an ordinary launch is blocked.
+ */
+export interface DelegatedGuidanceView {
+    nextAction: DelegatedNextAction;
+    launchEligible: boolean;
+    blockers: string[];
+    prerequisites: string[];
+    requiresConcernsDisposition: boolean;
+}
+export interface WorkflowInspectionResult extends Record<string, unknown> {
+    tool: "work_item_list";
+    sessionId: string;
+    includeClosed: boolean;
+    items: WorkflowWorkItemView[];
+    planRuns?: WorkflowDelegatedRunView[];
+    executions?: WorkflowExecutionView[];
+    contract: WorkflowContractIdentity;
+}
+/** Store context required to derive snapshot-level (not host-level) eligibility. */
+export interface InspectionContext {
+    data: WorkItemStoreData;
+    sessionId: string;
+}
+/**
+ * Loaded package/revision identity from the accepted cross-plugin contract
+ * module only. Never reads a global install, user config, or remote metadata.
+ */
+export declare function getWorkflowContractIdentity(): WorkflowContractIdentity;
+interface DelegatedGuidanceOptions {
+    record: WorkItemRecord;
+    progress: ReturnType<typeof summarizeDelegatedProgress>;
+    latest: ReturnType<typeof latestAttemptView>;
+    context: InspectionContext;
+}
+/**
+ * Build gate-derived guidance. Ordinary launches are downgraded to
+ * `launch_blocked` whenever the real item-level or execution-level gate would
+ * reject, so a caller can never see `launch_implementer` beside a blocker. This
+ * is the single composed helper shared by inspection and every mutation/failure
+ * response that reports a next action.
+ */
+export declare function deriveDelegatedGuidance(options: DelegatedGuidanceOptions): DelegatedGuidanceView;
+/**
+ * Read-only serialization of one work item. Delegated budget/guidance derives
+ * from shared pure gates; no private ledger body or authorization message text
+ * is exposed. Store context is required for delegated items so snapshot-level
+ * global gates are honored; non-delegated items are context-independent.
+ */
+export declare function serializeWorkItem(record: WorkItemRecord, context?: InspectionContext): WorkflowWorkItemView;
+export declare function getWorkflowInspection(store: WorkItemStore, sessionId: string, options?: {
+    includeClosed?: boolean;
+}): WorkflowInspectionResult;
+export {};