@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.4-dev.04a1e5b9e484

package/dist/session/session.types.js

@@ -1,12 +1,23 @@
 import path from "node:path";
+import { redactText } from "../shared/redaction/redaction.js";
+export class ForgeFailureError extends Error {
+    failureCode;
+    failureSource;
+    constructor(failureCode, message, failureSource = "bridge", options) {
+        super(message, options);
+        this.name = "ForgeFailureError";
+        this.failureCode = normalizeFailureCode(failureCode);
+        this.failureSource = failureSource;
+    }
+}
 export function parseRunOnceDispatchPacket(value) {
     const packet = asObject(value, "dispatch packet");
     const schemaVersion = requiredNumber(packet, "schemaVersion");
-    if (schemaVersion !== 1) {
+    if (schemaVersion !== 1 && schemaVersion !== 2) {
         throw new Error(`Unsupported dispatch schemaVersion: ${schemaVersion}`);
     }
     return {
-        schemaVersion: 1,
+        schemaVersion,
         userId: requiredString(packet, "userId"),
         workItem: parseWorkItem(packet.workItem),
         repo: parseRepo(packet.repo),
@@ -14,30 +25,676 @@ export function parseRunOnceDispatchPacket(value) {
         session: parseSession(packet.session),
         lease: parseLease(packet.lease),
         execution: parseExecution(packet.execution),
+        runtimeIntent: parseRuntimeIntent(packet.runtimeIntent),
         serverLocal: parseServerLocal(packet.serverLocal),
+        sandbox: parseSandbox(packet.sandbox, schemaVersion),
         pullRequest: parsePullRequest(packet.pullRequest),
         apiKeySecretGrant: parseApiKeySecretGrant(packet.apiKeySecretGrant),
+        apiKeySecretGrantHandle: parseApiKeySecretGrantHandle(packet.apiKeySecretGrantHandle),
         artifacts: parseArtifacts(packet.artifacts),
+        priorPhaseArtifacts: parsePriorPhaseArtifacts(packet.priorPhaseArtifacts),
         warmPathOverrides: parseWarmPathOverrides(packet.warmPathOverrides),
         qaBrowser: parseQaBrowser(packet.qaBrowser),
+        qaScope: parseQaScope(packet.qaScope ?? packet.qa_scope),
         qaRework: parseQaRework(packet.qaRework),
         architectRevision: parseArchitectRevision(packet.architectRevision),
+        architectDependencies: parseArchitectDependencies(packet.architectDependencies),
         storyDevelop: parseStoryDevelop(packet.storyDevelop),
         storyQa: parseStoryQa(packet.storyQa),
+        designerRefs: parseDesignerRefs(packet.designerRefs ?? packet.designer_refs),
         draft: parseDraftPrompt(packet.draft)
     };
 }
-export function failureResult(summary, events = []) {
+export function parseRunOnceResultPacket(value) {
+    const packet = asObject(value, "run-once result packet");
+    const schemaVersion = requiredNumber(packet, "schemaVersion");
+    if (schemaVersion !== 1 && schemaVersion !== 2) {
+        throw new Error(`Unsupported run-once result schemaVersion: ${schemaVersion}`);
+    }
+    const exitCode = requiredNumber(packet, "exitCode");
+    if (!Number.isSafeInteger(exitCode))
+        throw new Error("exitCode must be an integer.");
+    requiredString(packet, "summary");
+    if (!Array.isArray(packet.events))
+        throw new Error("events must be an array.");
+    for (const item of packet.events) {
+        if (typeof item !== "object" || item === null || !("wait" in item))
+            continue;
+        const event = asObject(item, "run-once result event");
+        if (event.wait !== undefined && event.wait !== null) {
+            parseWaitEnvelope(event.wait, requiredString(event, "eventType"));
+        }
+    }
+    if (schemaVersion === 1) {
+        if (packet.failure !== undefined && packet.failure !== null) {
+            throw new Error("run-once result schemaVersion 1 cannot contain a v2 failure envelope.");
+        }
+        return packet;
+    }
+    if (exitCode === 0 && packet.failure !== undefined && packet.failure !== null) {
+        throw new Error("run-once result cannot report both success and a failure envelope.");
+    }
+    if (exitCode !== 0 && (packet.failure === undefined || packet.failure === null)) {
+        throw new Error("run-once result schemaVersion 2 requires a failure envelope for a nonzero exit.");
+    }
+    if (packet.failure !== undefined && packet.failure !== null)
+        parseFailureEnvelope(packet.failure);
+    return packet;
+}
+const waitKinds = new Map([
+    ["host_runtime_admission_waiting", "host_runtime_admission"],
+    ["host_runtime_admission_acquired", "host_runtime_admission"],
+    ["host_runtime_serial_admission_waiting", "host_runtime_serial_admission"],
+    ["host_runtime_prepared_probe_started", "host_runtime_prepared_probe"],
+    ["host_runtime_prepared_probe_progress", "host_runtime_prepared_probe"],
+    ["host_runtime_prepared_probe_completed", "host_runtime_prepared_probe"],
+    ["host_runtime_prepared_admission_waiting", "host_runtime_prepared_admission"],
+    ["host_runtime_prepared_admission_acquired", "host_runtime_prepared_admission"],
+]);
+export function waitKindForEvent(eventType) {
+    const kind = waitKinds.get(eventType);
+    if (!kind)
+        throw new Error(`Unsupported typed wait observation '${eventType}'.`);
+    return kind;
+}
+export function waitWakeCondition(kind) {
+    switch (kind) {
+        case "host_runtime_serial_admission":
+            return "project_singleton_released";
+        case "host_runtime_prepared_probe":
+            return "prepared_runtime_probe_completed";
+        default:
+            return "host_runtime_admission_available";
+    }
+}
+function parseWaitEnvelope(value, eventType) {
+    const wait = asObject(value, "wait envelope");
+    if (requiredNumber(wait, "schemaVersion") !== 2) {
+        throw new Error("Unsupported wait envelope schemaVersion.");
+    }
+    let expectedKind;
+    try {
+        expectedKind = waitKindForEvent(eventType);
+    }
+    catch {
+        throw new Error("wait envelope is only valid on a wait lifecycle observation.");
+    }
+    const kind = requiredString(wait, "kind");
+    const scope = requiredString(wait, "scope");
+    const wakeCondition = requiredString(wait, "wakeCondition");
+    if (kind !== expectedKind
+        || !isWaitCode(kind, 80)
+        || !isWaitCode(scope, 64)
+        || !isWaitCode(wakeCondition, 80)
+        || wakeCondition !== waitWakeCondition(kind)) {
+        throw new Error("wait envelope kind, scope, or wakeCondition is invalid.");
+    }
+    if (!Array.isArray(wait.resourceKeys)
+        || wait.resourceKeys.length > 16
+        || wait.resourceKeys.some(item => typeof item !== "string" || !isWaitCode(item, 256))
+        || new Set(wait.resourceKeys).size !== wait.resourceKeys.length) {
+        throw new Error("wait envelope resourceKeys are invalid, duplicated, or exceed their bound.");
+    }
+    const queuePosition = wait.queuePosition;
+    if (queuePosition !== undefined && queuePosition !== null
+        && (typeof queuePosition !== "number" || !Number.isSafeInteger(queuePosition) || queuePosition <= 0)) {
+        throw new Error("wait envelope queuePosition is invalid.");
+    }
+    const blockerSessionId = wait.blockerSessionId;
+    if (blockerSessionId !== undefined && blockerSessionId !== null
+        && (typeof blockerSessionId !== "string"
+            || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(blockerSessionId)
+            || /^0{8}-0{4}-0{4}-0{4}-0{12}$/u.test(blockerSessionId))) {
+        throw new Error("wait envelope blockerSessionId is invalid.");
+    }
+    const blockerTitle = wait.blockerTitle;
+    if (blockerTitle !== undefined && blockerTitle !== null
+        && (typeof blockerTitle !== "string" || blockerTitle.length > 500)) {
+        throw new Error("wait envelope blockerTitle is invalid.");
+    }
+    const retryAt = wait.retryAt;
+    if (retryAt !== undefined && retryAt !== null
+        && (typeof retryAt !== "string" || !Number.isFinite(Date.parse(retryAt)))) {
+        throw new Error("wait envelope retryAt is invalid.");
+    }
+    const firstObservedAt = requiredString(wait, "firstObservedAt");
+    if (!Number.isFinite(Date.parse(firstObservedAt))) {
+        throw new Error("wait envelope firstObservedAt is invalid.");
+    }
+    const observationVersion = requiredNumber(wait, "observationVersion");
+    if (!Number.isSafeInteger(observationVersion) || observationVersion <= 0) {
+        throw new Error("wait envelope observationVersion is invalid.");
+    }
+    if (requiredString(wait, "contractOrigin") !== "bridge_v2") {
+        throw new Error("wait envelope contractOrigin must identify the v2 Bridge writer.");
+    }
+    return value;
+}
+function isWaitCode(value, maximumLength) {
+    return value.length <= maximumLength && /^[a-z][a-z0-9_.:-]*$/u.test(value);
+}
+function parseRuntimeIntent(value) {
+    if (value === undefined || value === null) {
+        return { executionClass: "managed_runtime", applicationRuntimeRequired: true };
+    }
+    const intent = asObject(value, "runtimeIntent");
+    const executionClass = requiredString(intent, "executionClass").trim().toLowerCase();
+    if (executionClass !== "analysis_only" && executionClass !== "managed_runtime") {
+        throw new Error("runtimeIntent.executionClass must be analysis_only or managed_runtime.");
+    }
+    const applicationRuntimeRequired = requiredBoolean(intent, "applicationRuntimeRequired");
+    if ((executionClass === "analysis_only") === applicationRuntimeRequired) {
+        throw new Error("runtimeIntent execution class and application runtime requirement are inconsistent.");
+    }
+    return { executionClass, applicationRuntimeRequired };
+}
+function parseSandbox(value, schemaVersion) {
+    if (value === undefined || value === null) {
+        if (schemaVersion === 2) {
+            throw new Error("sandbox is required for dispatch schemaVersion 2.");
+        }
+        return null;
+    }
+    const sandbox = asObject(value, "sandbox");
+    const executionMode = requiredString(sandbox, "executionMode");
+    if (executionMode !== "host" && executionMode !== "docker") {
+        throw new Error("sandbox.executionMode must be host or docker.");
+    }
+    const executionPolicy = requiredString(sandbox, "executionPolicy");
+    if (executionPolicy !== "host_allowed" && executionPolicy !== "sandbox_preferred" && executionPolicy !== "sandbox_required") {
+        throw new Error("sandbox.executionPolicy is invalid.");
+    }
+    return {
+        dispatchAttemptId: requiredString(sandbox, "dispatchAttemptId"),
+        executionLeaseId: requiredString(sandbox, "executionLeaseId"),
+        runnerInstanceId: requiredString(sandbox, "runnerInstanceId"),
+        executionMode,
+        executionPolicy,
+        networkPolicy: parseSandboxNetworkPolicy(sandbox.networkPolicy),
+        requestedResources: parseSandboxResourceRequest(sandbox.requestedResources),
+        runtime: optionalString(sandbox, "runtime"),
+        sandboxConfigCommitSha: optionalString(sandbox, "sandboxConfigCommitSha"),
+        inputCommitSha: optionalString(sandbox, "inputCommitSha"),
+        contractDigest: optionalString(sandbox, "contractDigest"),
+        imageDigest: optionalString(sandbox, "imageDigest"),
+        publicationMode: parsePublicationMode(sandbox.publicationMode),
+        publishGrantHandle: parsePublishGrantHandle(sandbox.publishGrantHandle)
+    };
+}
+function parsePublicationMode(value) {
+    if (value === undefined || value === null)
+        return "shared_filesystem";
+    if (value !== "bridge_push" && value !== "shared_filesystem")
+        throw new Error("sandbox.publicationMode is invalid.");
+    return value;
+}
+function parsePublishGrantHandle(value) {
+    if (value === undefined || value === null)
+        return null;
+    const handle = asObject(value, "sandbox.publishGrantHandle");
+    const grantId = requiredString(handle, "grantId");
+    const branch = requiredString(handle, "branch");
+    const expiresAt = requiredString(handle, "expiresAt");
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(grantId)) {
+        throw new Error("sandbox.publishGrantHandle.grantId is invalid.");
+    }
+    if (branch.length > 240)
+        throw new Error("sandbox.publishGrantHandle.branch is too long.");
+    if (!Number.isFinite(Date.parse(expiresAt)))
+        throw new Error("sandbox.publishGrantHandle.expiresAt is invalid.");
+    return { grantId, branch, expiresAt };
+}
+function parseSandboxResourceRequest(value) {
+    if (value === undefined || value === null) {
+        return {
+            sandboxSlots: 1,
+            cpuMillis: 2000,
+            workerMemoryLimitBytes: 2 * 1024 ** 3,
+            serviceMemoryLimitBytes: 0,
+            runtimeOverheadBytes: 128 * 1024 ** 2,
+            memoryBytes: 2 * 1024 ** 3 + 128 * 1024 ** 2,
+            workspaceBytes: 10 * 1024 ** 3,
+            pids: 512,
+            buildSlots: 1
+        };
+    }
+    const resources = asObject(value, "sandbox.requestedResources");
+    const memoryBytes = boundedInteger(resources, "memoryBytes", 128 * 1024 ** 2, 512 * 1024 ** 3);
+    const hasMemoryBreakdown = ["workerMemoryLimitBytes", "serviceMemoryLimitBytes", "runtimeOverheadBytes"]
+        .some(key => resources[key] !== undefined && resources[key] !== null);
+    const workerMemoryLimitBytes = hasMemoryBreakdown
+        ? boundedInteger(resources, "workerMemoryLimitBytes", 128 * 1024 ** 2, 512 * 1024 ** 3)
+        : memoryBytes;
+    const serviceMemoryLimitBytes = hasMemoryBreakdown
+        ? boundedInteger(resources, "serviceMemoryLimitBytes", 0, 512 * 1024 ** 3)
+        : 0;
+    const runtimeOverheadBytes = hasMemoryBreakdown
+        ? boundedInteger(resources, "runtimeOverheadBytes", 0, 64 * 1024 ** 3)
+        : 0;
+    if (workerMemoryLimitBytes + serviceMemoryLimitBytes + runtimeOverheadBytes !== memoryBytes) {
+        throw new Error("sandbox.requestedResources memory breakdown must equal memoryBytes.");
+    }
+    return {
+        sandboxSlots: boundedInteger(resources, "sandboxSlots", 1, 4),
+        cpuMillis: boundedInteger(resources, "cpuMillis", 100, 64_000),
+        workerMemoryLimitBytes,
+        serviceMemoryLimitBytes,
+        runtimeOverheadBytes,
+        memoryBytes,
+        workspaceBytes: boundedInteger(resources, "workspaceBytes", 1024 ** 3, 10 * 1024 ** 4),
+        pids: boundedInteger(resources, "pids", 32, 65_536),
+        buildSlots: boundedInteger(resources, "buildSlots", 0, 4)
+    };
+}
+function parseSandboxNetworkPolicy(value) {
+    if (value === undefined || value === null)
+        return { mode: "offline", allowedHosts: [] };
+    const policy = asObject(value, "sandbox.networkPolicy");
+    const mode = requiredString(policy, "mode");
+    if (mode !== "offline" && mode !== "public_allowlist" && mode !== "open_public") {
+        throw new Error("sandbox.networkPolicy.mode is invalid.");
+    }
+    const rawHosts = policy.allowedHosts ?? [];
+    if (!Array.isArray(rawHosts) || rawHosts.some((host) => typeof host !== "string")) {
+        throw new Error("sandbox.networkPolicy.allowedHosts must be a string array.");
+    }
+    const allowedHosts = [...new Set(rawHosts.map(host => host.trim().toLowerCase()).filter(Boolean))];
+    if (allowedHosts.length > 128 || allowedHosts.some(host => !/^(?:\*\.)?(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/u.test(host))) {
+        throw new Error("sandbox.networkPolicy.allowedHosts contains an invalid hostname.");
+    }
+    if (mode !== "public_allowlist" && allowedHosts.length > 0) {
+        throw new Error("sandbox.networkPolicy.allowedHosts requires public_allowlist mode.");
+    }
+    if (mode === "public_allowlist" && allowedHosts.length === 0) {
+        return { mode: "offline", allowedHosts: [] };
+    }
+    return { mode, allowedHosts };
+}
+const failureCodePattern = /^[a-z][a-z0-9_.-]{0,79}$/u;
+const failureCategories = new Set(["domain", "provider", "transport", "cancellation", "ownership", "resource", "unknown"]);
+const failurePhases = new Set(["offer", "build", "prepare", "agent", "validation", "import", "teardown", "unknown"]);
+const failureSources = new Set(["bridge", "provider", "sandbox", "unknown"]);
+const failureRetryabilities = new Set(["retryable", "non_retryable", "policy_required", "unknown"]);
+const failureOperatorActions = new Set(["none", "retry_dispatch", "retry_with_policy", "inspect_failure", "fix_input", "fix_environment", "reauthenticate", "restore_ownership"]);
+const maximumFailureMessageLength = 2000;
+const maximumFailureCausalChainLength = 8;
+const waitConditionCodes = new Set([
+    "host_runtime_admission_waiting",
+    "host_runtime_serial_admission_waiting",
+    "host_runtime_prepared_probe_started",
+    "host_runtime_prepared_probe_progress",
+    "host_runtime_prepared_admission_waiting",
+    "waiting_for_capacity",
+]);
+const stableFailureFamilyCodes = new Set([
+    "generated_output_reset_invalid",
+    "generated_output_reset_unsafe",
+    "sandbox_build_failed",
+    "sandbox_build_policy_failed",
+    "sandbox_builder_release_failed",
+    "sandbox_config_commit_invalid",
+    "sandbox_config_commit_missing",
+    "sandbox_config_commit_unapproved",
+    "contract_invalid",
+    "sandbox_input_failed",
+    "docker_capacity_unavailable",
+    "docker_engine_invalid_response",
+    "docker_engine_recovery_failed",
+    "docker_engine_recovery_timeout",
+    "docker_linux_required",
+    "docker_preflight_required",
+    "docker_rootless_required",
+    "docker_unavailable",
+    "docker_unreachable",
+    "sandbox_output_conflict",
+    "sandbox_output_invalid",
+    "sandbox_output_missing",
+    "sandbox_output_publish_forbidden",
+    "sandbox_output_rejected",
+    "sandbox_output_publish_rejected",
+    "sandbox_output_publish_stale",
+    "sandbox_output_publish_unavailable",
+    "sandbox_output_stale",
+    "sandbox_import_cancelled",
+    "sandbox_import_unavailable",
+    "teardown_failed",
+    "reaper_cleanup_degraded",
+    "reaper_runner_replaced",
+    "sandbox_egress_policy_invalid",
+    "sandbox_egress_proxy_unavailable",
+    "sandbox_event_flood",
+    "sandbox_event_invalid",
+    "sandbox_identity_invalid",
+    "sandbox_image_signature_failed",
+    "sandbox_log_limit",
+    "sandbox_preflight_failed",
+    "sandbox_security_profile_invalid",
+    "sandbox_security_profile_unavailable",
+    "sandbox_service_health_policy_invalid",
+]);
+export function failureResult(summary, events = [], facts = failureFactsForCode("bridge.execution_failed")) {
     return {
-        schemaVersion: 1,
+        schemaVersion: 2,
         exitCode: 1,
-        summary,
-        events
+        summary: boundedFailureText(summary),
+        events,
+        failure: createFailureEnvelope(summary, facts),
+    };
+}
+export function createFailureEnvelope(message, facts, occurredAt = new Date().toISOString()) {
+    const code = normalizeFailureCode(facts.code);
+    if (waitConditionCodes.has(code)) {
+        throw new Error(`Wait condition '${code}' must be emitted as lifecycle state, not a terminal failure.`);
+    }
+    assertFailureFactsMatchPolicy(code, facts);
+    return {
+        schemaVersion: 2,
+        code,
+        message: boundedFailureText(message),
+        category: facts.category,
+        phase: facts.phase,
+        source: facts.source,
+        retryability: facts.retryability,
+        operatorAction: facts.operatorAction,
+        causalChain: (facts.causalChain ?? []).slice(0, maximumFailureCausalChainLength).map(cause => ({
+            code: normalizeFailureCode(cause.code),
+            message: boundedFailureText(cause.message),
+            source: cause.source,
+        })),
+        occurredAt,
+        contractOrigin: "bridge_v2",
+    };
+}
+export function failureFactsFromError(error, options = {}) {
+    if (options.cancelled) {
+        const cancellationSource = options.source ?? "bridge";
+        return {
+            ...failureFactsForCode("bridge.dispatch_cancelled", cancellationSource),
+            causalChain: errorCauseChain(error, cancellationSource),
+        };
+    }
+    const source = error instanceof ForgeFailureError
+        ? error.failureSource
+        : options.source ?? "bridge";
+    const code = error instanceof ForgeFailureError
+        ? error.failureCode
+        : "bridge.execution_failed";
+    return {
+        ...failureFactsForCode(code, source),
+        causalChain: errorCauseChain(error, source),
     };
 }
+export function failureFactsForCode(code, source = "bridge") {
+    const policy = failurePolicyForCode(code);
+    if (policy.known && !policy.allowedSources.includes(source)) {
+        throw new Error(`Failure code '${policy.code}' cannot be attributed to source '${source}'.`);
+    }
+    return {
+        code: policy.code,
+        category: policy.category,
+        phase: policy.phase,
+        source,
+        retryability: policy.retryability,
+        operatorAction: policy.operatorAction,
+    };
+}
+export function failurePolicyForCode(code) {
+    code = normalizeFailureCode(code);
+    const classification = unvalidatedFailureFactsForCode(code, "bridge");
+    const known = classification.category !== "unknown" || code === "legacy_failure_unknown";
+    return {
+        code,
+        category: classification.category,
+        phase: classification.phase,
+        retryability: classification.retryability,
+        operatorAction: classification.operatorAction,
+        allowedSources: allowedSourcesForCode(code, known),
+        known,
+    };
+}
+function unvalidatedFailureFactsForCode(code, source) {
+    code = normalizeFailureCode(code);
+    if (["bridge.dispatch_cancelled", "dispatch_cancelled", "dispatch_session_terminal", "dispatch.capacity_retargeted"].includes(code)) {
+        return facts(code, "cancellation", "teardown", source, "non_retryable", "none");
+    }
+    if (["bridge.dispatch_fence_conflict", "bridge.reservation_stale", "bridge.capacity_wait_lost", "bridge.dispatch_attempt_missing"].includes(code)) {
+        return facts(code, "ownership", "offer", source, "non_retryable", "restore_ownership");
+    }
+    if (["reservation_expired", "bridge.lease_expired", "bridge.stale_runner_instance", "bridge.runner_replaced"].includes(code)) {
+        return facts(code, "ownership", "offer", source, "retryable", "retry_dispatch");
+    }
+    if (["bridge.dispatch_failed", "bridge.execution_failed", "bridge.cli_execution_failed", "bridge_callback_timeout"].includes(code)) {
+        return facts(code, "transport", "unknown", source, "policy_required", "inspect_failure");
+    }
+    if (code === "bridge.unavailable") {
+        return facts(code, "transport", "offer", source, "retryable", "retry_dispatch");
+    }
+    if (["capacity_unavailable", "bridge.runner_draining", "docker_engine_unavailable", "docker_memory_low", "docker_memory_sample_unavailable", "docker_cpu_low", "docker_disk_low", "server_local.resource_pressure", "server_local.capacity_unavailable", "dispatch.preparation_resource_pressure", "sandbox_capacity_profile_unavailable", "host_runtime_admission_expired"].includes(code)) {
+        return facts(code, "resource", "offer", source, "retryable", "retry_dispatch");
+    }
+    if (["bridge.lease_retry_exhausted", "bridge.capacity_wait_exhausted"].includes(code)) {
+        return facts(code, "resource", "offer", source, "non_retryable", "inspect_failure");
+    }
+    if (["prepublication_infrastructure_failed", "prepublication_capability_unavailable"].includes(code)) {
+        return facts(code, "resource", "validation", source, "retryable", "retry_with_policy");
+    }
+    if (["prepublication_validation_failed", "prepublication_contract_invalid", "prepublication_execution_scope_invalid"].includes(code)) {
+        return facts(code, "domain", "validation", source, "non_retryable", "fix_input");
+    }
+    if (["generated_output_reset_failed", "generated_output_reset_unverified", "worktree_prepare_failed", "host_runtime_ledger_write_failed", "host_diagnostics_temporary_unavailable", "attempt_process_supervisor_start_failed", "attempt_process_supervisor_start_timeout"].includes(code)) {
+        return facts(code, "transport", "prepare", source, "retryable", "retry_dispatch");
+    }
+    if (stableFailureFamilyCodes.has(code) && code.startsWith("generated_output_reset_")) {
+        return facts(code, "domain", "prepare", source, "non_retryable", "fix_environment");
+    }
+    if (code === "provider_start_unavailable") {
+        return facts(code, "provider", "prepare", source, "retryable", "retry_dispatch");
+    }
+    if (code === "provider_configuration_invalid") {
+        return facts(code, "provider", "prepare", source, "non_retryable", "fix_environment");
+    }
+    if (["host_port_collision", "host_runtime_process_exited", "host_runtime_listener_timeout", "host_runtime_http_readiness_timeout", "host_runtime_prepared_source_changed", "host_runtime_prepared_probe_incomplete", "host_runtime_prepared_probe_cleanup_unconfirmed"].includes(code)) {
+        return facts(code, "resource", "prepare", source, "retryable", "retry_dispatch");
+    }
+    if (code === "host_runtime_project_start_failed") {
+        return facts(code, "domain", "prepare", source, "non_retryable", "fix_environment");
+    }
+    if (stableFailureFamilyCodes.has(code) && (code.startsWith("sandbox_build") || code.startsWith("image_"))) {
+        const policyFailure = code === "sandbox_build_policy_failed";
+        return facts(code, "resource", "build", source, policyFailure ? "non_retryable" : "retryable", policyFailure ? "fix_environment" : "retry_dispatch");
+    }
+    if (code === "provider_network_policy_denied"
+        || stableFailureFamilyCodes.has(code) && (code.startsWith("sandbox_config") || code.startsWith("contract_") || code.startsWith("sandbox_input"))) {
+        return facts(code, "domain", "prepare", source, "non_retryable", "fix_environment");
+    }
+    if (stableFailureFamilyCodes.has(code) && code.startsWith("docker_")) {
+        return facts(code, "resource", "prepare", source, "non_retryable", "fix_environment");
+    }
+    if (code === "provider_network_unavailable") {
+        return facts(code, "transport", "offer", source, "retryable", "retry_dispatch");
+    }
+    if (code === "provider_request_not_found") {
+        return facts(code, "provider", "offer", source, "retryable", "retry_dispatch");
+    }
+    if (code === "provider_capacity_unavailable") {
+        return facts(code, "resource", "offer", source, "retryable", "retry_dispatch");
+    }
+    if (code === "provider_context_window_exhausted") {
+        return facts(code, "provider", "agent", source, "retryable", "retry_dispatch");
+    }
+    if (stableFailureFamilyCodes.has(code) && (code.startsWith("sandbox_output") || code.startsWith("sandbox_import"))) {
+        const retryable = code === "sandbox_import_unavailable" || code === "sandbox_output_publish_unavailable";
+        return facts(code, "transport", "import", source, retryable ? "retryable" : "non_retryable", retryable ? "retry_with_policy" : "inspect_failure");
+    }
+    if (stableFailureFamilyCodes.has(code) && (code.startsWith("teardown") || code.startsWith("reaper"))) {
+        return facts(code, "transport", "teardown", source, "retryable", "retry_with_policy");
+    }
+    if (["invalid_dispatch"].includes(code)) {
+        return facts(code, "domain", "offer", source, "non_retryable", "fix_input");
+    }
+    if ([
+        "bridge.api_key_auth_required",
+        "bridge.api_key_secret_grant_missing",
+        "bridge.api_key_secret_grant_denied",
+        "bridge.api_key_secret_grant_provider_mismatch",
+        "bridge.api_key_secret_missing",
+        "contract_plaintext_secret_rejected",
+    ].includes(code)) {
+        return facts(code, "domain", "prepare", source, "non_retryable", "reauthenticate");
+    }
+    if (code === "sandbox_idle_timeout") {
+        return facts(code, "provider", "agent", source, "retryable", "retry_with_policy");
+    }
+    if (code === "sandbox_wall_timeout") {
+        return facts(code, "provider", "agent", source, "retryable", "retry_with_policy");
+    }
+    if (["sandbox_oom_killed", "sandbox_pid_exhausted", "sandbox_file_descriptor_exhausted", "sandbox_storage_exhausted"].includes(code)) {
+        return facts(code, "resource", "agent", source, "non_retryable", "inspect_failure");
+    }
+    if (code === "sandbox_auth_unavailable") {
+        return facts(code, "domain", "prepare", source, "non_retryable", "reauthenticate");
+    }
+    if (code === "sandbox_lease_expired") {
+        return facts(code, "ownership", "agent", source, "non_retryable", "restore_ownership");
+    }
+    if (code === "sandbox_runtime_failed") {
+        return facts(code, "provider", "agent", source, "non_retryable", "inspect_failure");
+    }
+    if (code === "worktree_branch_integration_conflict") {
+        return facts(code, "domain", "agent", source, "non_retryable", "fix_input");
+    }
+    if (stableFailureFamilyCodes.has(code) && code.startsWith("sandbox_")) {
+        return facts(code, "provider", "agent", source, "non_retryable", "inspect_failure");
+    }
+    return facts(code, "unknown", "unknown", source, "unknown", "inspect_failure");
+}
+function parseFailureEnvelope(value) {
+    const failure = asObject(value, "failure");
+    if (requiredNumber(failure, "schemaVersion") !== 2)
+        throw new Error("failure.schemaVersion must be 2.");
+    const code = requiredString(failure, "code");
+    const message = requiredString(failure, "message");
+    const category = requiredString(failure, "category");
+    const phase = requiredString(failure, "phase");
+    const source = requiredString(failure, "source");
+    const retryability = requiredString(failure, "retryability");
+    const operatorAction = requiredString(failure, "operatorAction");
+    const occurredAt = requiredString(failure, "occurredAt");
+    const contractOrigin = requiredString(failure, "contractOrigin");
+    if (!failureCodePattern.test(code))
+        throw new Error("failure.code is invalid.");
+    if (message.length > maximumFailureMessageLength)
+        throw new Error("failure.message is too long.");
+    if (!failureCategories.has(category) || !failurePhases.has(phase) || !failureSources.has(source)
+        || !failureRetryabilities.has(retryability) || !failureOperatorActions.has(operatorAction)) {
+        throw new Error("failure contains an unsupported category, phase, source, retryability, or operator action.");
+    }
+    assertFailureFactsMatchPolicy(code, { code, category, phase, source, retryability, operatorAction });
+    if (!Number.isFinite(Date.parse(occurredAt)))
+        throw new Error("failure.occurredAt is invalid.");
+    if (contractOrigin !== "bridge_v2")
+        throw new Error("failure.contractOrigin must be bridge_v2.");
+    if (!Array.isArray(failure.causalChain) || failure.causalChain.length > maximumFailureCausalChainLength) {
+        throw new Error("failure.causalChain is invalid or too long.");
+    }
+    const causalChain = failure.causalChain.map((candidate, index) => {
+        const cause = asObject(candidate, `failure.causalChain[${index}]`);
+        const causeCode = requiredString(cause, "code");
+        const causeMessage = requiredString(cause, "message");
+        const causeSource = requiredString(cause, "source");
+        if (!failureCodePattern.test(causeCode) || causeMessage.length > maximumFailureMessageLength || !failureSources.has(causeSource)) {
+            throw new Error(`failure.causalChain[${index}] is invalid.`);
+        }
+        return { code: causeCode, message: causeMessage, source: causeSource };
+    });
+    return { schemaVersion: 2, code, message, category, phase, source, retryability, operatorAction, causalChain, occurredAt, contractOrigin };
+}
+function facts(code, category, phase, source, retryability, operatorAction) {
+    return { code, category, phase, source, retryability, operatorAction };
+}
+function allowedSourcesForCode(code, known) {
+    if (!known)
+        return ["bridge", "provider", "sandbox", "unknown"];
+    if (code.startsWith("provider_"))
+        return ["bridge", "provider", "sandbox"];
+    if (code.startsWith("sandbox_")
+        || code.startsWith("docker_")
+        || code.startsWith("image_")
+        || code.startsWith("contract_")
+        || code.startsWith("generated_output_reset_")
+        || code.startsWith("teardown")
+        || code.startsWith("reaper")) {
+        return ["bridge", "sandbox"];
+    }
+    return ["bridge"];
+}
+function assertFailureFactsMatchPolicy(code, factsToValidate) {
+    const policy = failurePolicyForCode(code);
+    if (!policy.known)
+        return;
+    if (factsToValidate.category !== policy.category
+        || factsToValidate.phase !== policy.phase
+        || factsToValidate.retryability !== policy.retryability
+        || factsToValidate.operatorAction !== policy.operatorAction
+        || !policy.allowedSources.includes(factsToValidate.source)) {
+        throw new Error(`Failure code '${policy.code}' contradicts the failure taxonomy or allowed-source registry.`);
+    }
+}
+function normalizeFailureCode(value) {
+    const normalized = value.trim().toLowerCase().slice(0, 80);
+    return failureCodePattern.test(normalized) ? normalized : "bridge.execution_failed";
+}
+function boundedFailureText(value) {
+    const bounded = value.trim().slice(0, maximumFailureMessageLength);
+    return bounded || "Dispatch failed without a diagnostic message.";
+}
+/**
+ * Rebuilds an error graph at a privileged execution boundary without
+ * retaining the raw error or any raw recursive cause. Forge failure metadata
+ * survives so the P7 taxonomy remains authoritative after sanitization.
+ */
+export function sanitizeFailureError(error, exactSecrets = []) {
+    return sanitizeFailureErrorAtDepth(error, exactSecrets, new Set(), 0);
+}
+function sanitizeFailureErrorAtDepth(error, exactSecrets, visited, depth) {
+    if (depth >= maximumFailureCausalChainLength) {
+        return new Error("Additional error causes were omitted.");
+    }
+    if (error !== null && typeof error === "object") {
+        if (visited.has(error))
+            return new Error("Circular error cause was omitted.");
+        visited.add(error);
+    }
+    const message = redactText(error instanceof Error ? error.message : String(error), exactSecrets);
+    const cause = error instanceof Error && error.cause !== undefined
+        ? sanitizeFailureErrorAtDepth(error.cause, exactSecrets, visited, depth + 1)
+        : undefined;
+    const options = cause === undefined ? undefined : { cause };
+    if (error instanceof ForgeFailureError) {
+        return new ForgeFailureError(error.failureCode, message, error.failureSource, options);
+    }
+    if (error instanceof AggregateError) {
+        const errors = [...error.errors].map(item => sanitizeFailureErrorAtDepth(item, exactSecrets, visited, depth + 1));
+        return new AggregateError(errors, message, options);
+    }
+    return new Error(message, options);
+}
+function errorCauseChain(error, source) {
+    const causes = [];
+    let current = error;
+    while (current !== undefined && current !== null && causes.length < maximumFailureCausalChainLength) {
+        const message = current instanceof Error ? current.message : String(current);
+        const code = current instanceof ForgeFailureError ? current.failureCode : "cause_unknown";
+        const causeSource = current instanceof ForgeFailureError ? current.failureSource : source;
+        causes.push({ code, message: boundedFailureText(message), source: causeSource });
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return causes;
+}
 function parseWorkItem(value) {
     const item = asObject(value, "workItem");
     return {
+        projectId: optionalString(item, "projectId"),
         id: requiredString(item, "id"),
         kind: requiredString(item, "kind"),
         title: requiredString(item, "title"),
@@ -61,6 +718,7 @@ function parseRepo(value) {
 function parseCycleRun(value) {
     const cycle = asObject(value, "cycleRun");
     return {
+        effectivePlanAmendmentHash: optionalString(cycle, "effectivePlanAmendmentHash"),
         id: requiredString(cycle, "id"),
         ownerType: optionalString(cycle, "ownerType"),
         ownerId: optionalString(cycle, "ownerId"),
@@ -70,6 +728,7 @@ function parseCycleRun(value) {
         requestedBase: optionalString(cycle, "requestedBase") ?? "develop",
         baseBranch: optionalString(cycle, "baseBranch") ?? "develop",
         expectedCurrentBranch: optionalString(cycle, "expectedCurrentBranch"),
+        repairHeadSha: optionalString(cycle, "repairHeadSha"),
         attempt: requiredNumber(cycle, "attempt"),
         model: requiredString(cycle, "model")
     };
@@ -79,7 +738,9 @@ function parseSession(value) {
     return {
         id: requiredString(session, "id"),
         model: requiredString(session, "model"),
-        lane: requiredString(session, "lane")
+        lane: requiredString(session, "lane"),
+        resumedFromSessionId: optionalString(session, "resumedFromSessionId"),
+        resumeProviderThreadId: optionalString(session, "resumeProviderThreadId")
     };
 }
 function parseLease(value) {
@@ -107,7 +768,8 @@ function parseExecution(value) {
         role: requiredString(execution, "role"),
         lane: requiredString(execution, "lane"),
         requiresApiKeySecretGrant: requiredBoolean(execution, "requiresApiKeySecretGrant"),
-        runnerRepoLocalPath: optionalString(execution, "runnerRepoLocalPath")
+        runnerRepoLocalPath: optionalString(execution, "runnerRepoLocalPath"),
+        effort: optionalString(execution, "effort")
     };
 }
 function parseDraftPrompt(value) {
@@ -118,9 +780,45 @@ function parseDraftPrompt(value) {
     return {
         kind: requiredString(draft, "kind"),
         systemPrompt: requiredString(draft, "systemPrompt"),
-        userPrompt: requiredString(draft, "userPrompt")
+        userPrompt: requiredString(draft, "userPrompt"),
+        projectName: optionalString(draft, "projectName"),
+        repoName: optionalString(draft, "repoName"),
+        attachments: parseDraftAttachments(draft.attachments)
     };
 }
+function parseDraftAttachments(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error("draft.attachments must be an array when provided.");
+    }
+    return value.map((entry, index) => {
+        const attachment = asObject(entry, `draft.attachments[${index}]`);
+        const kind = requiredString(attachment, "kind").trim().toLowerCase();
+        if (kind !== "text" && kind !== "image") {
+            throw new Error(`draft.attachments[${index}].kind must be text or image.`);
+        }
+        const textContent = optionalString(attachment, "textContent");
+        const contentBase64 = optionalString(attachment, "contentBase64");
+        if (kind === "text" && textContent === null) {
+            throw new Error(`draft.attachments[${index}].textContent is required for text attachments.`);
+        }
+        if (kind === "image" && contentBase64 === null) {
+            throw new Error(`draft.attachments[${index}].contentBase64 is required for image attachments.`);
+        }
+        return {
+            index: optionalNonNegativeInteger(attachment, "index") ?? index,
+            fileName: requiredString(attachment, "fileName"),
+            contentType: optionalString(attachment, "contentType") ?? "",
+            kind,
+            byteCount: optionalNonNegativeInteger(attachment, "byteCount") ?? 0,
+            summary: optionalString(attachment, "summary") ?? "",
+            textContent,
+            contentBase64
+        };
+    });
+}
 function parseApiKeySecretGrant(value) {
     if (value === undefined || value === null) {
         return null;
@@ -133,6 +831,16 @@ function parseApiKeySecretGrant(value) {
         expiresAt: requiredString(grant, "expiresAt")
     };
 }
+function parseApiKeySecretGrantHandle(value) {
+    if (value === undefined || value === null)
+        return null;
+    const grant = asObject(value, "apiKeySecretGrantHandle");
+    return {
+        grantId: requiredString(grant, "grantId"),
+        provider: requiredString(grant, "provider"),
+        expiresAt: requiredString(grant, "expiresAt")
+    };
+}
 function parseServerLocal(value) {
     const serverLocal = asObject(value, "serverLocal");
     return {
@@ -159,9 +867,49 @@ function parsePullRequest(value) {
         requiredChecksTotal: requiredNumber(pullRequest, "requiredChecksTotal"),
         unresolvedThreads: requiredNumber(pullRequest, "unresolvedThreads"),
         humanApproved: requiredBoolean(pullRequest, "humanApproved"),
-        hasMergeConflicts: requiredBoolean(pullRequest, "hasMergeConflicts")
+        hasMergeConflicts: requiredBoolean(pullRequest, "hasMergeConflicts"),
+        headSha: optionalString(pullRequest, "headSha") ?? "",
+        reviewIssueKey: optionalString(pullRequest, "reviewIssueKey"),
+        reviewFindings: parsePullRequestReviewFindings(pullRequest.reviewFindings),
+        openWorkOrderStories: parseWorkOrderStories(pullRequest.openWorkOrderStories)
     };
 }
+function parseWorkOrderStories(value) {
+    if (value === null || value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("pullRequest.openWorkOrderStories must be an array when provided.");
+    return value.map((entry, index) => {
+        const story = asObject(entry, `pullRequest.openWorkOrderStories[${index}]`);
+        return {
+            workItemId: requiredString(story, "workItemId"),
+            title: optionalString(story, "title") ?? "",
+            acceptanceCriteria: optionalString(story, "acceptanceCriteria") ?? ""
+        };
+    });
+}
+function parsePullRequestReviewFindings(value) {
+    if (value === null || value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("pullRequest.reviewFindings must be an array when provided.");
+    return value.map((entry, index) => {
+        const finding = asObject(entry, `pullRequest.reviewFindings[${index}]`);
+        return {
+            claimId: requiredString(finding, "claimId"),
+            kind: requiredString(finding, "kind"),
+            bodySha256: requiredString(finding, "bodySha256"),
+            body: optionalString(finding, "body") ?? "",
+            contentAvailable: requiredBoolean(finding, "contentAvailable"),
+            actionable: requiredBoolean(finding, "actionable"),
+            actionabilityReason: requiredString(finding, "actionabilityReason"),
+            author: optionalString(finding, "author"),
+            url: optionalString(finding, "url"),
+            path: optionalString(finding, "path"),
+            line: optionalPositiveInteger(finding, "line")
+        };
+    });
+}
 function parseWarmPathOverrides(value) {
     if (value === undefined || value === null) {
         return [];
@@ -197,6 +945,28 @@ function parseQaBrowser(value) {
         missingTargetReason: optionalString(qaBrowser, "missingTargetReason") ?? optionalString(qaBrowser, "missing_target_reason")
     };
 }
+function parseQaScope(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const qaScope = asObject(value, "qaScope");
+    return {
+        schema_version: requiredNumber(qaScope, "schema_version"),
+        surface: parseOptionalStringArray(qaScope.surface, "qaScope.surface"),
+        required_evidence: parseOptionalStringArray(qaScope.required_evidence, "qaScope.required_evidence"),
+        required_capabilities: parseOptionalStringArray(qaScope.required_capabilities ?? qaScope.requiredCapabilities, "qaScope.required_capabilities"),
+        not_applicable: parseOptionalStringArray(qaScope.not_applicable, "qaScope.not_applicable"),
+        browser_required: optionalBoolean(qaScope, "browser_required") ?? optionalBoolean(qaScope, "browserRequired") ?? false,
+        api_required: optionalBoolean(qaScope, "api_required") ?? optionalBoolean(qaScope, "apiRequired") ?? false,
+        source: optionalString(qaScope, "source"),
+        authority: optionalString(qaScope, "authority"),
+        confidence: optionalString(qaScope, "confidence"),
+        confirmed_by_user: optionalBoolean(qaScope, "confirmed_by_user") ?? optionalBoolean(qaScope, "confirmedByUser"),
+        locked: optionalBoolean(qaScope, "locked"),
+        derived_from: parseOptionalObject(qaScope.derived_from ?? qaScope.derivedFrom, "qaScope.derived_from"),
+        rationale: optionalString(qaScope, "rationale")
+    };
+}
 function parseQaAppLaunchTarget(value) {
     if (value === undefined || value === null) {
         return null;
@@ -211,6 +981,7 @@ function parseQaAppLaunchTarget(value) {
         command: optionalString(launchTarget, "command"),
         working_directory: optionalString(launchTarget, "working_directory"),
         ready_url: optionalString(launchTarget, "ready_url"),
+        managed_runtime_port: optionalString(launchTarget, "managed_runtime_port"),
         routes: Array.isArray(routes)
             ? routes.map((entry, index) => {
                 if (typeof entry !== "string") {
@@ -260,6 +1031,34 @@ function parseArchitectRevision(value) {
         feedback: requiredString(revision, "feedback")
     };
 }
+function parseArchitectDependencies(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const context = asObject(value, "architectDependencies");
+    const prerequisites = context.prerequisites;
+    if (!Array.isArray(prerequisites)) {
+        throw new Error("architectDependencies.prerequisites must be an array.");
+    }
+    return {
+        baseBranch: requiredString(context, "baseBranch").trim(),
+        prerequisites: prerequisites.map((entry, index) => {
+            const prerequisite = asObject(entry, `architectDependencies.prerequisites[${index}]`);
+            return {
+                storyId: requiredString(prerequisite, "storyId").trim(),
+                title: requiredString(prerequisite, "title").trim(),
+                scheduleIndex: optionalNonNegativeInteger(prerequisite, "scheduleIndex"),
+                waveIndex: optionalNonNegativeInteger(prerequisite, "waveIndex"),
+                featureScheduleIndex: optionalNonNegativeInteger(prerequisite, "featureScheduleIndex"),
+                expectedOutput: optionalString(prerequisite, "expectedOutput"),
+                handoffSummary: optionalString(prerequisite, "handoffSummary"),
+                dependencyReason: optionalString(prerequisite, "dependencyReason"),
+                pullRequestNumber: optionalPositiveInteger(prerequisite, "pullRequestNumber"),
+                targetBranch: requiredString(prerequisite, "targetBranch").trim()
+            };
+        })
+    };
+}
 function parseStoryDevelop(value) {
     if (value === undefined || value === null) {
         return null;
@@ -289,6 +1088,7 @@ function parseStoryQa(value) {
     }
     const storyQa = asObject(value, "storyQa");
     return {
+        references: parseStoryQaReferences(storyQa.references),
         storyWorkItemId: requiredString(storyQa, "storyWorkItemId"),
         planId: requiredString(storyQa, "planId"),
         planContentHash: requiredString(storyQa, "planContentHash"),
@@ -301,6 +1101,26 @@ function parseStoryQa(value) {
         dependencies: parseStoryQaDependencies(storyQa.dependencies)
     };
 }
+function parseStoryQaReferences(value) {
+    if (value === undefined || value === null)
+        return null;
+    const bundle = asObject(value, "storyQa.references");
+    if (!Array.isArray(bundle.files))
+        throw new Error("storyQa.references.files must be an array.");
+    return {
+        schemaVersion: requiredNumber(bundle, "schemaVersion"),
+        cycleRunId: requiredString(bundle, "cycleRunId"),
+        storyWorkItemId: requiredString(bundle, "storyWorkItemId"),
+        projectId: requiredString(bundle, "projectId"), repoId: requiredString(bundle, "repoId"),
+        planId: requiredString(bundle, "planId"), planContentHash: requiredString(bundle, "planContentHash"),
+        effectiveAmendmentHash: requiredString(bundle, "effectiveAmendmentHash"), capturedAt: requiredString(bundle, "capturedAt"),
+        files: bundle.files.map((entry, index) => {
+            const file = asObject(entry, `storyQa.references.files[${index}]`);
+            return { path: requiredString(file, "path"), body: requiredString(file, "body"),
+                contentHash: requiredString(file, "contentHash"), provenance: requiredString(file, "provenance") };
+        })
+    };
+}
 function parseStoryQaChildTasks(value) {
     if (!Array.isArray(value)) {
         throw new Error("storyQa.childTasks must be an array.");
@@ -365,6 +1185,58 @@ function parseStoryQaDependencies(value) {
         };
     });
 }
+function parseDesignerRefs(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const context = asObject(value, "designerRefs");
+    const refs = context.refs;
+    if (!Array.isArray(refs)) {
+        throw new Error("designerRefs.refs must be an array.");
+    }
+    return {
+        schemaVersion: requiredNumber(context, "schemaVersion"),
+        kind: requiredString(context, "kind"),
+        ownerType: requiredString(context, "ownerType"),
+        ownerId: requiredString(context, "ownerId"),
+        projectId: requiredString(context, "projectId"),
+        repoId: requiredString(context, "repoId"),
+        title: requiredString(context, "title"),
+        refs: refs.map((entry, index) => parseDesignerRefAttachment(entry, index))
+    };
+}
+function parseDesignerRefAttachment(value, index) {
+    const attachment = asObject(value, `designerRefs.refs[${index}]`);
+    return {
+        ref: parseDesignerRef(attachment.ref, index),
+        reason: optionalString(attachment, "reason") ?? "",
+        required: requiredBoolean(attachment, "required"),
+        source: optionalString(attachment, "source") ?? "",
+        lineageKind: optionalString(attachment, "lineageKind") ?? optionalString(attachment, "lineage_kind") ?? "",
+        inheritedFromItemType: optionalString(attachment, "inheritedFromItemType") ?? optionalString(attachment, "inherited_from_item_type"),
+        inheritedFromItemId: optionalString(attachment, "inheritedFromItemId") ?? optionalString(attachment, "inherited_from_item_id"),
+        inheritedFromDesignerRefId: optionalString(attachment, "inheritedFromDesignerRefId") ?? optionalString(attachment, "inherited_from_designer_ref_id"),
+        addedByLane: optionalString(attachment, "addedByLane") ?? optionalString(attachment, "added_by_lane") ?? "",
+        sortOrder: requiredNumber(attachment, "sortOrder"),
+        createdAt: requiredString(attachment, "createdAt")
+    };
+}
+function parseDesignerRef(value, index) {
+    const designerRef = asObject(value, `designerRefs.refs[${index}].ref`);
+    return {
+        id: requiredString(designerRef, "id"),
+        projectId: requiredString(designerRef, "projectId"),
+        repoId: requiredString(designerRef, "repoId"),
+        refKey: requiredString(designerRef, "refKey"),
+        kind: requiredString(designerRef, "kind"),
+        path: requiredString(designerRef, "path"),
+        anchor: optionalString(designerRef, "anchor"),
+        title: optionalString(designerRef, "title") ?? "",
+        contentHash: requiredString(designerRef, "contentHash"),
+        commitSha: requiredString(designerRef, "commitSha"),
+        createdAt: requiredString(designerRef, "createdAt")
+    };
+}
 function parseStringArray(value, label) {
     if (!Array.isArray(value)) {
         throw new Error(`${label} must be an array.`);
@@ -376,6 +1248,18 @@ function parseStringArray(value, label) {
         return entry.trim();
     });
 }
+function parseOptionalStringArray(value, label) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    return parseStringArray(value, label);
+}
+function parseOptionalObject(value, label) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    return asObject(value, label);
+}
 function parseArtifacts(value) {
     if (value === undefined || value === null) {
         return [];
@@ -397,6 +1281,34 @@ function parseArtifacts(value) {
         };
     });
 }
+function parsePriorPhaseArtifacts(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error("priorPhaseArtifacts must be an array when provided.");
+    }
+    return value.map((entry, index) => {
+        const artifact = asObject(entry, `priorPhaseArtifacts[${index}]`);
+        const phase = requiredString(artifact, "phase").trim().toLowerCase().replace(/-/g, "_");
+        if (phase !== "implementation" && phase !== "self_review" && phase !== "validation") {
+            throw new Error(`priorPhaseArtifacts[${index}].phase must be implementation, self_review, or validation.`);
+        }
+        return {
+            workItemId: requiredString(artifact, "workItemId"),
+            artifactId: requiredString(artifact, "artifactId"),
+            cycleRunId: requiredString(artifact, "cycleRunId"),
+            phase,
+            status: requiredString(artifact, "status"),
+            producedAt: requiredString(artifact, "producedAt"),
+            sourcePath: requiredString(artifact, "sourcePath"),
+            verdictJson: requiredString(artifact, "verdictJson"),
+            report: optionalString(artifact, "report") ?? "",
+            verdictContentHash: requiredString(artifact, "verdictContentHash").toLowerCase(),
+            reportContentHash: requiredString(artifact, "reportContentHash").toLowerCase()
+        };
+    });
+}
 function asObject(value, label) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw new Error(`${label} must be an object.`);
@@ -447,6 +1359,16 @@ function optionalPositiveInteger(source, key) {
     }
     return value;
 }
+function optionalNonNegativeInteger(source, key) {
+    const value = source[key];
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new Error(`${key} must be a non-negative integer when provided.`);
+    }
+    return value;
+}
 function requiredNumber(source, key) {
     const value = source[key];
     if (typeof value !== "number" || !Number.isFinite(value)) {
@@ -454,3 +1376,10 @@ function requiredNumber(source, key) {
     }
     return value;
 }
+function boundedInteger(source, key, minimum, maximum) {
+    const value = requiredNumber(source, key);
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new Error(`${key} must be an integer from ${minimum} through ${maximum}.`);
+    }
+    return value;
+}