@convertcom/mcp-server 0.0.1-beta.16 → 0.0.1-beta.18

package/build/operator.js

@@ -2,6 +2,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { executeNamespacedTool, namespaceToolNameForAction } from './namespaced.js';
 import { JSON_SCHEMA_DRAFT_2020_12 } from './shared.js';
 import { scrubDiagnosticText } from './redaction.js';
+import { failureAttribution, failureFromStructured, inputFailure, safeFailureAttribution, } from './failure-attribution.js';
 import { FEEDBACK_BODY_SCHEMA, FEEDBACK_CONFIRMATION_SCHEMA, FeedbackContractError, feedbackConsentProof, feedbackSubmissionContextOutline, feedbackSubmissionDigest, sanitizeFeedbackBody, validateAndSanitizeFeedback, } from './feedback.js';
 const APPROVAL_RULE_CODES = new Set([
     'experience.activate',
@@ -129,7 +130,7 @@ const READ_ACTIONS = [
     {
         action: 'get_defaults',
         mode: 'read',
-        description: 'Infer and cache project defaults such as preferred goal, audience, location, URL, and traffic split.',
+        description: 'Infer and cache suggested project defaults such as preferred goal, audience, location, URL, and traffic split. Suggestions are not consent to attach or create a resource.',
         path_parameters: ['account_id', 'project_id'],
         accepts_body: true,
     },
@@ -145,14 +146,14 @@ const WRITE_ACTIONS = [
     {
         action: 'create_custom_code_ab_test',
         mode: 'write',
-        description: 'Create a draft custom-code A/B experience and verify the persisted payload. Required body: url plus non-empty js or css. Optional: name, control_name, variation_name, description, objective, primary_goal, goals, audiences, locations, settings. Canonical custom variations may be supplied as variations[].changes[] with at most 100 changes per variation for bounded verification. Payload verification is independent from attached-goal lifecycle health; goal_configuration reports archived or unresolved goals without encouraging a duplicate create. Returns one authoritative experience plus a compact create receipt. Unknown fields are rejected.',
+        description: 'Create a draft custom-code A/B experience and verify the persisted payload. Required body: url plus non-empty js or css. Optional: name, control_name, variation_name, description, objective, primary_goal, goals, audiences, locations, settings. Omitted goals and goals: [] can both trigger Convert goal fallback; resolve user-intended existing goals and primary, send explicit IDs, and inspect the expanded returned experience. A bare URL does not select the UI Experience URL location; attach a user-intended location explicitly. Canonical custom variations may be supplied as variations[].changes[] with at most 100 changes per variation for bounded verification. Payload verification is independent from attached-goal lifecycle health; goal_configuration reports archived or unresolved goals without encouraging a duplicate create. Returns one authoritative experience plus a compact create receipt. Unknown fields are rejected.',
         path_parameters: ['account_id', 'project_id'],
         accepts_body: true,
     },
     {
         action: 'create_split_url_test',
         mode: 'write',
-        description: 'Create a draft split URL experience and verify the persisted redirect. Required body: original_pattern (or url) and variation_pattern (variation_url and redirect_url are accepted aliases). Optional: name, variation_name, case_sensitive, description, objective, primary_goal, goals, audiences, locations, settings, split_regex_support, or canonical variations with at most 100 changes each for bounded verification. Payload verification is independent from attached-goal lifecycle health; goal_configuration reports archived or unresolved goals without encouraging a duplicate create. Returns one authoritative experience plus a compact create receipt. Unknown fields are rejected.',
+        description: 'Create a draft split URL experience with an Original no-redirect control and a redirect treatment, allocated 50/50, and verify both arms, baseline, allocation and redirects. Required body: original_pattern (or url) and variation_pattern (variation_url and redirect_url are accepted aliases). Optional: name, variation_name, case_sensitive, description, objective, primary_goal, goals, audiences, locations, settings, split_regex_support. Omitted goals and goals: [] can both trigger Convert goal fallback; resolve user-intended existing goals and primary, send explicit IDs, and inspect the expanded returned experience. A bare URL does not select the UI Experience URL location; attach a user-intended location explicitly. Custom variations require unique names, exactly one explicit is_baseline: true control with no changes, one defaultRedirect per treatment, and positive numeric traffic_distribution per arm totaling 100; at most 100 changes per variation. goal_configuration separately reports archived or unresolved goals. Returns one authoritative experience plus a create receipt. If verified is false, inspect that existing draft; never repeat create or activate it automatically. Unknown fields are rejected.',
         path_parameters: ['account_id', 'project_id'],
         accepts_body: true,
     },
@@ -172,6 +173,10 @@ const WRITE_ACTIONS = [
     },
 ];
 const ALL_ACTIONS = [...READ_ACTIONS, ...WRITE_ACTIONS];
+const ALL_ACTION_NAMES = new Set(ALL_ACTIONS.map((action) => action.action));
+export function isRegisteredOperatorAction(action) {
+    return typeof action === 'string' && ALL_ACTION_NAMES.has(action);
+}
 const DEFAULT_RESULTS_PER_PAGE = 50;
 const MAX_OPERATOR_COLLECTION_PAGES = 20;
 const MAX_OPERATOR_COLLECTION_BYTES = 8 * 1024 * 1024;
@@ -254,6 +259,9 @@ export const OPERATOR_OUTPUT_SCHEMA = {
         error: {},
         issues: { type: 'array', items: { type: 'object' } },
         verified: { type: 'boolean' },
+        failure: { type: 'object', description: 'Closed, identifier-free failure category and provenance for a failed operator call.' },
+        partial_failure_count: { type: 'integer', minimum: 1, description: 'Number of failed namespace calls when an operator workflow still returned partial evidence.' },
+        partial_failure: { type: 'object', description: 'Closed, identifier-free dominant failure category and provenance for a partially successful workflow.' },
     },
     additionalProperties: true,
 };
@@ -519,16 +527,24 @@ function validateOperatorWriteInput(args) {
     if (args.action === 'create_split_url_test') {
         const original = args.body.original_pattern ?? args.body.url;
         const variation = args.body.variation_pattern ?? args.body.variation_url ?? args.body.redirect_url;
-        const variationsIssue = validateCanonicalOperatorVariations(args.body.variations);
+        const variationsIssue = validateCanonicalOperatorVariations(args.body.variations, true);
         if (variationsIssue)
             return variationsIssue;
         if (typeof original !== 'string' || !original.trim()) {
             return 'operator.create_split_url_test requires body.original_pattern or body.url.';
         }
+        if (Array.isArray(args.body.variations)) {
+            const splitIssue = validateSplitUrlArms(args.body.variations);
+            if (splitIssue)
+                return splitIssue;
+        }
         if (!Array.isArray(args.body.variations)) {
             if (typeof variation !== 'string' || !variation.trim()) {
                 return 'operator.create_split_url_test requires body.variation_pattern; body.variation_url and body.redirect_url are accepted aliases.';
             }
+            const splitIssue = validateSplitUrlArms(buildSplitUrlExperienceBody(args.body).variations);
+            if (splitIssue)
+                return splitIssue;
         }
     }
     if (args.action === 'enable_split_url_regex'
@@ -609,7 +625,7 @@ async function prepareFeedback(args, toolSet, readOnlyImpersonation) {
             approved_payload_digest: digest,
         },
         next_step: submitAvailable
-            ? 'Show the sanitized summary, context outline, context byte count, payload digest, and review_contract to the user. Explain that context values are intentionally not re-echoed and that the digest binds approval to the complete sanitized payload. Only after explicit approval, call submit_feedback with the unchanged body and set all three confirmation_template booleans to true.'
+            ? 'Show the sanitized summary, context outline, context byte count, payload digest, and review_contract to the user. Explain that context values are intentionally not re-echoed and that the digest binds approval to the complete sanitized payload. Only after explicit approval, call submit_feedback with the unchanged body and set all three confirmation_template booleans to true. If the host reports no approval while the confirmation matches this template exactly, the host failed to capture approval: re-present the host approval card instead of editing the confirmation.'
             : readOnlyImpersonation
                 ? 'Show the sanitized summary, context outline, context byte count, payload digest, and review_contract to the user. Staff impersonation is browse-only, so this preparation cannot be submitted or attributed as the customer. Remove as_user and prepare the feedback again as the connected staff member if they explicitly want to submit it.'
                 : 'Show the sanitized summary, context outline, context byte count, payload digest, and review_contract to the user. This read-only MCP profile cannot store feedback; do not claim submission. A write-enabled Convert MCP profile is required after approval.',
@@ -639,13 +655,15 @@ function feedbackActionConstraints(actions) {
         });
     return constraints;
 }
-function validateCanonicalOperatorVariations(value) {
+function validateCanonicalOperatorVariations(value, allowBaseline = false) {
     if (typeof value === 'undefined')
         return null;
     if (!Array.isArray(value) || value.length === 0) {
         return 'body.variations must be a non-empty array when provided.';
     }
     const allowedVariationKeys = new Set(['name', 'status', 'traffic_distribution', 'traffic_percentage', 'changes']);
+    if (allowBaseline)
+        allowedVariationKeys.add('is_baseline');
     for (const [index, variation] of value.entries()) {
         if (!isObject(variation))
             return `body.variations[${index}] must be an object.`;
@@ -665,6 +683,28 @@ function validateCanonicalOperatorVariations(value) {
     }
     return null;
 }
+function validateSplitUrlArms(variations) {
+    const hint = 'Split URL tests require at least two uniquely named arms, exactly one explicit is_baseline: true control with no changes, and a defaultRedirect change in each treatment. Supply numeric traffic_distribution for every arm (positive, totaling 100).';
+    if (variations.some((v) => !isObject(v) || typeof v.name !== 'string' || !v.name.trim()
+        || !Array.isArray(v.changes) || v.changes.some((change) => !isObject(change))))
+        return hint;
+    if (variations.length < 2 || new Set(variations.map((v) => v.name)).size !== variations.length)
+        return hint;
+    const controls = variations.filter((v) => v.is_baseline === true);
+    if (controls.length !== 1 || controls[0].changes.length !== 0)
+        return hint;
+    for (const variation of variations) {
+        if (typeof variation.traffic_distribution !== 'number' || !Number.isFinite(variation.traffic_distribution)
+            || variation.traffic_distribution <= 0 || variation.traffic_distribution > 100)
+            return hint;
+        if (variation.is_baseline !== true
+            && variation.changes.filter((change) => change.type === 'defaultRedirect').length !== 1)
+            return hint;
+    }
+    if (Math.abs(variations.reduce((sum, v) => sum + v.traffic_distribution, 0) - 100) > 0.00005)
+        return hint;
+    return null;
+}
 function operatorVariationsContainCode(value) {
     if (!Array.isArray(value))
         return false;
@@ -909,15 +949,23 @@ async function experimentPortfolio(args, context) {
 }
 async function experimentVelocity(args, context) {
     await report(context, 'Fetching experiences for velocity report', 1, 3);
-    const experienceCall = await listExperiences(basePath(args), portfolioFilters(args));
+    const [experienceCall, goalCall] = await Promise.all([
+        listExperiences(basePath(args), portfolioFilters(args)),
+        listResource('goals', basePath(args)),
+    ]);
     const experiences = collectionFrom(experienceCall.data);
-    const summaries = summarizeExperiences(experiences);
+    const summaries = summarizeExperiences(experiences, canonicalGoalDefinitions(collectionFrom(goalCall.data)));
+    const goalCoverage = investigationCollectionCoverage(goalCall);
     const launched = summaries.filter((item) => typeof item.start_time === 'number' && item.start_time > 0);
     const completed = summaries.filter((item) => typeof item.end_time === 'number' && item.end_time > 0);
     const coverage = investigationCollectionCoverage(experienceCall);
     const completeCoverage = coverage.status === 'complete';
     return {
-        source_status: { experiences: experienceCall.ok ? 'available' : 'unavailable' },
+        source_status: {
+            experiences: experienceCall.ok ? 'available' : 'unavailable',
+            goals: goalCall.ok ? 'available' : 'unavailable',
+        },
+        goal_authority_coverage: goalCoverage,
         coverage,
         total: experienceCall.ok && completeCoverage ? summaries.length : null,
         created_or_returned: experienceCall.ok ? summaries.length : null,
@@ -942,7 +990,8 @@ async function experimentVelocity(args, context) {
             ...(experienceCall.ok && !completeCoverage
                 ? [`Experience velocity coverage is ${coverage.status}; exact totals and averages are null, while returned_* fields describe only fetched rows.`]
                 : []),
-            ...warningsFromCalls([experienceCall]),
+            ...goalAuthorityWarnings(goalCoverage),
+            ...warningsFromCalls([experienceCall, goalCall]),
         ],
     };
 }
@@ -1442,9 +1491,13 @@ async function investigate(args, context) {
 }
 async function failedTestAnalysis(args, context) {
     await report(context, 'Fetching completed and paused experiences', 1, 3);
-    const experienceCall = await listExperiences(basePath(args), { status: ['completed', 'paused'] });
+    const [experienceCall, goalCall] = await Promise.all([
+        listExperiences(basePath(args), { status: ['completed', 'paused'] }),
+        listResource('goals', basePath(args)),
+    ]);
     const experiences = collectionFrom(experienceCall.data);
-    const summaries = summarizeExperiences(experiences);
+    const summaries = summarizeExperiences(experiences, canonicalGoalDefinitions(collectionFrom(goalCall.data)));
+    const goalCoverage = investigationCollectionCoverage(goalCall);
     const applicable = summaries.filter((item) => item.outcome !== 'not_applicable');
     const losses = applicable.filter((item) => [
         'negative',
@@ -1456,7 +1509,11 @@ async function failedTestAnalysis(args, context) {
     const coverage = investigationCollectionCoverage(experienceCall);
     const completeCoverage = coverage.status === 'complete';
     return {
-        source_status: { experiences: experienceCall.ok ? 'available' : 'unavailable' },
+        source_status: {
+            experiences: experienceCall.ok ? 'available' : 'unavailable',
+            goals: goalCall.ok ? 'available' : 'unavailable',
+        },
+        goal_authority_coverage: goalCoverage,
         coverage,
         returned_reviewed: experienceCall.ok ? summaries.length : null,
         total_reviewed: experienceCall.ok && completeCoverage ? summaries.length : null,
@@ -1477,7 +1534,8 @@ async function failedTestAnalysis(args, context) {
             ...(experienceCall.ok && !completeCoverage
                 ? [`Failed-test analysis coverage is ${coverage.status}; exact totals are null and returned_* fields describe only fetched rows.`]
                 : []),
-            ...warningsFromCalls([experienceCall]),
+            ...goalAuthorityWarnings(goalCoverage),
+            ...warningsFromCalls([experienceCall, goalCall]),
         ],
     };
 }
@@ -1567,20 +1625,27 @@ async function cleanupCandidates(args, context) {
     await report(context, 'Fetching cleanup candidates', 1, 4);
     const path = basePath(args);
     const staleDraftDays = numberFrom(args.body.stale_draft_days ?? args.query.stale_draft_days, 30);
-    const [drafts, allExperiences, goals, audiences, locations, features] = await Promise.all([
+    const [drafts, allExperiences, goals, audiences, locations, features, goalAuthority] = await Promise.all([
         listExperiences(path, { status: ['draft'] }),
         listExperiences(path),
         listResource('goals', path, { usage: 'not_used' }),
         listResource('audiences', path, { usage: 'not_used' }),
         listResource('locations', path, { usage: 'not_used' }),
         listResource('features', path),
+        listResource('goals', path),
     ]);
     const experienceItems = collectionFrom(allExperiences.data);
     const draftItems = collectionFrom(drafts.data);
+    // Shared goals can embed stale or reordered definitions per experience; resolve
+    // every stale-draft summary against the goals authority (draft_qa parity) so a
+    // shared goal reports one consistent type/name/status everywhere. Missing ids
+    // fall back to their embeds, and an unavailable authority is disclosed below.
+    const canonicalGoals = canonicalGoalDefinitions(collectionFrom(goalAuthority.data));
+    const goalAuthorityCoverage = investigationCollectionCoverage(goalAuthority);
     const staleCutoff = Date.now() / 1000 - staleDraftDays * 24 * 60 * 60;
     const staleDrafts = draftItems
         .filter((item) => typeof item.created_at !== 'number' || item.created_at < staleCutoff)
-        .map((experience) => summarizeExperience(experience));
+        .map((experience) => summarizeExperience(experience, canonicalGoals));
     const experienceCoverage = investigationCollectionCoverage(allExperiences);
     const draftCoverage = investigationCollectionCoverage(drafts);
     const completeExperienceCoverage = experienceCoverage.status === 'complete';
@@ -1616,12 +1681,13 @@ async function cleanupCandidates(args, context) {
             sdk_search_patterns: feature.key ? [`${feature.key}`, `isFeatureEnabled(\"${feature.key}\")`, `getFeature(\"${feature.key}\")`] : [],
         };
     });
-    const cleanupWarnings = warningsFromCalls([drafts, allExperiences, goals, audiences, locations, features]);
+    const cleanupWarnings = warningsFromCalls([drafts, allExperiences, goals, audiences, locations, features, goalAuthority]);
     for (const [resource, status] of Object.entries(candidateSourceStatus)) {
         if (status !== 'complete') {
             cleanupWarnings.push(`${resource} cleanup candidates are unavailable because verification status is ${status}; other resource categories remain independently evaluated.`);
         }
     }
+    cleanupWarnings.push(...goalAuthorityWarnings(goalAuthorityCoverage));
     return {
         stale_draft_days: staleDraftDays,
         source_status: {
@@ -1636,6 +1702,7 @@ async function cleanupCandidates(args, context) {
             drafts: draftCoverage,
             experiences: experienceCoverage,
             ...resourceCoverage,
+            goal_authority: goalAuthorityCoverage,
         },
         returned_stale_drafts: drafts.ok ? staleDrafts.length : null,
         total_stale_drafts: drafts.ok && draftCoverage.status === 'complete' ? staleDrafts.length : null,
@@ -1804,6 +1871,10 @@ async function createSplitUrlTest(args, context) {
             readback_status: readback?.status ?? null,
         },
         verified,
+        ...(verified ? {} : {
+            remediation_required: true,
+            next_steps: ['Do not repeat create or activate this experience. Inspect the existing resource using create_receipt.experience_id; if the ID is unavailable, locate it before any further write. Correct the draft only after reviewing the persisted arms and allocation.'],
+        }),
         goal_configuration: goalConfigurationSummary(goalStatus),
         ...(verified && verification.normalizedCodeWhitespace ? {
             verification_normalizations: [
@@ -1816,7 +1887,9 @@ async function createSplitUrlTest(args, context) {
                     ? 'Readback confirmed the draft split URL experience and exact redirect patterns after Convert canonicalized only surrounding code whitespace.'
                     : 'Readback confirmed the draft split URL experience and exact redirect patterns.'
                 : 'Readback succeeded, but one or more requested split URL fields did not persist exactly.'
-            : 'Create call succeeded but no readback ID was available.',
+            : experienceId
+                ? 'Create succeeded, but readback failed. The existing draft is unverified; do not repeat create.'
+                : 'Create succeeded but returned no usable experience ID. Locate the existing draft before any further write; do not repeat create.',
     };
 }
 async function enableSplitUrlRegex(args, context) {
@@ -2095,8 +2168,11 @@ export function buildSplitUrlExperienceBody(input) {
             }
             : input.settings,
         variations: Array.isArray(input.variations) ? input.variations : [
+            { name: 'Original', is_baseline: true, traffic_distribution: 50, changes: [] },
             {
                 name: stringFrom(input.variation_name, 'Variation URL'),
+                is_baseline: false,
+                traffic_distribution: 50,
                 changes: [
                     {
                         type: 'defaultRedirect',
@@ -2371,6 +2447,7 @@ async function namespaceCall(namespace, action, path, body, query, confirmation)
             error: structured.error ?? text ?? 'Unknown error',
             details: structured,
             text,
+            failure: failureFromStructured(structured, 'namespace'),
         });
     }
     return recordNamespaceCall({
@@ -2396,6 +2473,13 @@ async function safeNamespaceCall(namespace, action, path, body, query) {
             namespace,
             action,
             error: error instanceof Error ? error.name : 'ThrownError',
+            failure: failureAttribution({
+                category: 'unknown',
+                source: 'operator',
+                stage: 'operator_workflow',
+                dispatchState: 'unknown',
+                code: error instanceof Error ? error.name : 'ThrownError',
+            }),
         });
     }
 }
@@ -2419,6 +2503,11 @@ function basePath(args, extra = [], override = {}) {
     }
     return path;
 }
+function goalAuthorityWarnings(coverage) {
+    return coverage.status === 'complete' ? [] : [
+        `Goal type/name/status for unresolved IDs fell back to experience embeds because the goals authority is ${coverage.status}; verify shared goal definitions via goals.get before acting on them.`,
+    ];
+}
 function summarizeExperiences(experiences, canonicalGoals = new Map()) {
     return experiences.map((experience) => summarizeExperience(experience, canonicalGoals));
 }
@@ -3172,11 +3261,25 @@ function stableLifecycleStatus(value) {
         : 'unknown';
 }
 function stableCallErrorClass(call) {
+    if (call.failure?.category === 'input')
+        return 'invalid_input';
+    if (call.failure?.category === 'permission')
+        return call.status === 401 ? 'authentication_failed' : 'permission_denied';
+    if (call.failure?.category === 'not_found')
+        return 'not_found';
+    if (call.failure?.category === 'timeout')
+        return 'upstream_timeout';
+    if (call.failure?.category === 'network')
+        return 'upstream_network_error';
+    if (call.failure?.category === 'cancellation')
+        return 'cancelled';
+    if (call.failure?.category === 'internal')
+        return 'internal_error';
     const status = call.status;
     if (status === 401)
         return 'authentication_failed';
     if (status === 403)
-        return 'permission_denied';
+        return 'upstream_request_failed';
     if (status === 404)
         return 'not_found';
     if (status === 422)
@@ -3719,6 +3822,21 @@ function splitUrlExperienceVerification(data, expected) {
     if (!experienceIdentityMatches(actual, expected)) {
         return { matches: false, normalizedCodeWhitespace: false };
     }
+    const arms = collectionFrom(actual.variations);
+    const expectedArms = collectionFrom(expected.variations);
+    if (arms.length !== expectedArms.length || validateSplitUrlArms(arms) !== null
+        || new Set(arms.map((arm) => Number(arm.id))).size !== arms.length
+        || arms.some((arm) => !Number.isSafeInteger(Number(arm.id)) || Number(arm.id) <= 0)
+        || arms.some((arm) => (arm.is_baseline === true)
+            !== (expectedArms.find((item) => item.name === arm.name)?.is_baseline === true))) {
+        return { matches: false, normalizedCodeWhitespace: false };
+    }
+    for (const arm of arms) {
+        const expectedArm = expectedArms.find((item) => item.name === arm.name);
+        if (!expectedArm || arm.changes.length !== collectionFrom(expectedArm.changes).length) {
+            return { matches: false, normalizedCodeWhitespace: false };
+        }
+    }
     return expectedVariationsVerification(actual.variations, expected.variations, false);
 }
 function experienceIdentityMatches(actual, expected) {
@@ -3962,11 +4080,40 @@ async function report(context, message, progress, total) {
 function finalizeOperatorResult(action, data, calls) {
     const allCallsFailed = calls.length > 0 && calls.every((call) => !call.ok);
     if (!allCallsFailed) {
-        return okResult(action, data);
+        return okResult(action, data, calls);
     }
     const status = dominantFailureStatus(calls);
     const errors = calls.map((call) => `${call.namespace}.${call.action}: ${stableCallErrorClass(call)}`);
-    return errorResult(action, 'AllUpstreamCallsFailed', `All upstream namespace calls failed for operator.${action}.`, { status, data, errors });
+    const partial = operatorFailureSummary(calls);
+    return errorResult(action, 'AllUpstreamCallsFailed', `All upstream namespace calls failed for operator.${action}.`, {
+        status,
+        data,
+        errors,
+        ...(partial ? { failure: partial.failure } : {}),
+    });
+}
+function operatorFailureSummary(calls) {
+    const failures = calls
+        .filter((call) => !call.ok)
+        .map((call) => call.failure ?? failureFromStructured({
+        ...(typeof call.status === 'number' ? { status: call.status } : {}),
+        error: typeof call.error === 'string' ? call.error : 'UnknownFailure',
+    }, 'namespace'));
+    if (failures.length === 0)
+        return null;
+    const priority = new Map([
+        ['permission', 0],
+        ['cancellation', 1],
+        ['timeout', 2],
+        ['network', 3],
+        ['not_found', 4],
+        ['upstream', 5],
+        ['input', 6],
+        ['internal', 7],
+        ['unknown', 8],
+    ]);
+    const failure = failures.slice().sort((left, right) => (priority.get(left.category) ?? 99) - (priority.get(right.category) ?? 99))[0];
+    return { count: failures.length, failure };
 }
 /** The most common HTTP status among failed calls, or 502 when no call reported a numeric status. */
 function dominantFailureStatus(calls) {
@@ -3980,11 +4127,12 @@ function dominantFailureStatus(calls) {
         return 502;
     return [...counts.entries()].sort((a, b) => b[1] - a[1])[0][0];
 }
-function okResult(action, data) {
+function okResult(action, data, calls = []) {
     const verified = typeof data.verified === 'boolean' ? data.verified : undefined;
     const responseData = verified === undefined ? data : { ...data };
     if (verified !== undefined)
         delete responseData.verified;
+    const partial = operatorFailureSummary(calls);
     const payload = {
         ok: true,
         namespace: 'operator',
@@ -3993,6 +4141,10 @@ function okResult(action, data) {
         status: 200,
         data: responseData,
         ...(verified !== undefined ? { verified } : {}),
+        ...(partial ? {
+            partial_failure_count: partial.count,
+            partial_failure: partial.failure,
+        } : {}),
     };
     return {
         content: [{ type: 'text', text: JSON.stringify(payload) }],
@@ -4003,6 +4155,10 @@ function errorResult(action, code, message, extra = {}) {
     const scrubbedExtra = scrubOperatorErrorValue(extra);
     const safeExtra = isObject(scrubbedExtra) ? scrubbedExtra : {};
     const status = typeof safeExtra.status === 'number' ? safeExtra.status : 400;
+    const existingFailure = safeFailureAttribution(safeExtra.failure);
+    const inferredFailure = code === 'MissingPathParameters'
+        ? inputFailure(code, 'operator', 'required', 'path')
+        : failureFromStructured({ ...safeExtra, error: code }, 'operator');
     const payload = {
         ...safeExtra,
         ok: false,
@@ -4012,6 +4168,7 @@ function errorResult(action, code, message, extra = {}) {
         status,
         error: code,
         message: scrubDiagnosticText(message),
+        failure: existingFailure ?? inferredFailure,
     };
     return {
         isError: true,
@@ -4065,6 +4222,14 @@ function approvalRequiredOperatorErrorResult(action, details) {
         error: 'ApprovalRequired',
         code: 'ApprovalRequired',
         message,
+        failure: failureAttribution({
+            category: 'permission',
+            source: 'operator',
+            stage: 'upstream_response',
+            dispatchState: 'dispatched',
+            code: 'ApprovalRequired',
+            upstreamStatus: 422,
+        }),
         approval_state: approvalState,
         approval_required: {
             rule_code: ruleCode,