@signaliz/sdk 1.0.17 → 1.0.18

package/dist/index.js

@@ -890,7 +890,11 @@ var Campaigns = class {
       maxSupportedTargetCount: data.max_supported_target_count,
       brainContext: data.brain_context ?? {},
       learningHoldout: data.learning_holdout ?? {},
-      providerRoute: mapProviderRoute(data)
+      providerRoute: mapProviderRoute(data),
+      effectiveSourceRouting: recordOrNull(data.effective_source_routing ?? data.source_routing),
+      sourcePlan: recordOrNull(data.source_plan ?? data.plan?.source_plan),
+      sourceRoutes: recordArray(data.source_routes ?? data.source_plan?.routes ?? data.plan?.source_plan?.routes),
+      sourceShards: recordArray(data.source_shards ?? data.source_plan?.shards ?? data.plan?.source_plan?.shards)
     };
   }
   async getCampaignBuildStatus(campaignBuildId) {
@@ -1082,6 +1086,9 @@ function recordOrNull(value) {
 function stringArray(value) {
   return Array.isArray(value) ? value.map((item) => String(item || "").trim()).filter(Boolean) : [];
 }
+function recordArray(value) {
+  return Array.isArray(value) ? value.map(recordOrNull).filter((item) => Boolean(item)) : [];
+}
 function diagnosticMessages(value) {
   if (!Array.isArray(value)) return [];
   return value.map((item) => {
@@ -1243,7 +1250,8 @@ function buildArgs(request) {
       suppress_prior_campaign_ids: request.cacheReusePolicy.suppressPriorCampaignIds,
       suppress_prior_list_ids: request.cacheReusePolicy.suppressPriorListIds,
       uniqueness: request.cacheReusePolicy.uniqueness,
-      require_usage_metadata: request.cacheReusePolicy.requireUsageMetadata
+      require_usage_metadata: request.cacheReusePolicy.requireUsageMetadata,
+      verified_cache_ttl_days: request.cacheReusePolicy.verifiedCacheTtlDays
     };
   }
   if (request.brainPreflight) args.brain_preflight = request.brainPreflight;
@@ -1926,6 +1934,7 @@ var CampaignBuilderAgent = class {
         },
         brain_defaults: plan.buildRequest.brainDefaults,
         brain_preflight: plan.buildRequest.brainPreflight,
+        learning_holdout: plan.buildRequest.learningHoldout,
         campaign_strategy_context: plan.buildRequest.campaignStrategyContext,
         delivery_risk_preflight: plan.buildRequest.deliveryRisk,
         delivery_risk: plan.buildRequest.deliveryRisk
@@ -1939,7 +1948,8 @@ var CampaignBuilderAgent = class {
           estimated_credits: plan.estimatedCredits
         },
         brain_delivery_risk_preflight: plan.buildRequest.deliveryRisk,
-        delivery_risk: plan.buildRequest.deliveryRisk
+        delivery_risk: plan.buildRequest.deliveryRisk,
+        learning_holdout: plan.buildRequest.learningHoldout
       },
       approval_required: plan.approvals.some((approval) => approval.blocking),
       actor_type: "agent",
@@ -3345,6 +3355,21 @@ function routesFromCustomerTools(tools) {
     }))
   );
 }
+function normalizeCampaignBuilderLearningHoldout(input, gtmCampaignId, campaignName) {
+  const source = asRecord(input);
+  if (source.enabled === false) return { enabled: false };
+  const controlPercentage = numberOrUndefined2(source.control_percentage ?? source.controlPercentage);
+  const minControlSize = numberOrUndefined2(source.min_control_size ?? source.minControlSize);
+  const experimentKey = stringValue(source.experiment_key ?? source.experimentKey) ?? (gtmCampaignId ? `gtm_campaign:${gtmCampaignId}:learning_holdout` : `campaign_builder_agent:${hashString(campaignName)}:learning_holdout`);
+  return {
+    enabled: true,
+    controlPercentage: controlPercentage ?? 0.2,
+    minControlSize: minControlSize ?? 50,
+    experimentKey,
+    sourceCampaignId: stringValue(source.source_campaign_id ?? source.sourceCampaignId) ?? gtmCampaignId,
+    primaryMetric: stringValue(source.primary_metric ?? source.primaryMetric) ?? "positive_reply_rate"
+  };
+}
 function createBuildRequest(request, defaults, targetCount, campaignName, scopeBuildArgs, routes = [], memory, scopeBrainPreflight) {
   const buildRequest = {
     name: campaignName,
@@ -3377,6 +3402,11 @@ function createBuildRequest(request, defaults, targetCount, campaignName, scopeB
   };
   const scoped = asRecord(scopeBuildArgs);
   buildRequest.gtmCampaignId = request.gtmCampaignId ?? stringValue(scoped.gtm_campaign_id ?? scoped.gtmCampaignId);
+  buildRequest.learningHoldout = normalizeCampaignBuilderLearningHoldout(
+    request.learningHoldout ?? scoped.learning_holdout ?? scoped.learningHoldout,
+    buildRequest.gtmCampaignId,
+    campaignName
+  );
   if (typeof scoped.name === "string") buildRequest.name = scoped.name;
   if (typeof scoped.prompt === "string") buildRequest.prompt = scoped.prompt;
   if (typeof scoped.target_count === "number") buildRequest.targetCount = scoped.target_count;
@@ -3451,6 +3481,7 @@ function createBrainPreflight(request, buildRequest, routes, memory) {
     target_icp: targetIcp,
     provider_chain: providerChain,
     lead_source: providerChain[0] ?? "signaliz",
+    learning_holdout: buildRequest.learningHoldout,
     tool_sequence: [
       { tool: "gtm_brain_learning_cycle_plan", purpose: "Plan the Brain learning loop for this campaign.", arguments: learningArgs },
       { tool: "gtm_brain_seed_defaults", purpose: "Seed campaign defaults from workspace memory and safe aggregate patterns.", arguments: defaultsArgs },
@@ -4118,6 +4149,16 @@ function buildCampaignArgs(request) {
   if (request.dedupKeys) args.dedup_keys = request.dedupKeys;
   if (request.brainPreflight) args.brain_preflight = request.brainPreflight;
   if (request.brainDefaults) args.brain_defaults = request.brainDefaults;
+  if (request.learningHoldout) {
+    args.learning_holdout = compact({
+      enabled: request.learningHoldout.enabled,
+      control_percentage: request.learningHoldout.controlPercentage,
+      min_control_size: request.learningHoldout.minControlSize,
+      experiment_key: request.learningHoldout.experimentKey,
+      source_campaign_id: request.learningHoldout.sourceCampaignId,
+      primary_metric: request.learningHoldout.primaryMetric
+    });
+  }
   if (request.campaignStrategyContext) args.campaign_strategy_context = request.campaignStrategyContext;
   if (request.deliveryRisk) args.delivery_risk = request.deliveryRisk;
   if (request.icp) {
@@ -4214,6 +4255,7 @@ function buildExecutionPrepareArgs(request, dryRun, confirmSpend) {
     delivery_risk: buildArgs2.delivery_risk,
     dedup_keys: buildArgs2.dedup_keys,
     policy: buildArgs2.policy,
+    learning_holdout: buildArgs2.learning_holdout,
     signals: buildArgs2.signals,
     qualification: buildArgs2.qualification,
     copy: buildArgs2.copy,
@@ -4248,10 +4290,145 @@ function mapBuildResult(data, dryRun) {
     targetLimitReason: data.target_limit_reason,
     maxSupportedTargetCount: data.max_supported_target_count,
     brainContext: data.brain_context ?? {},
+    learningHoldout: data.learning_holdout ?? {},
     providerRoute: mapProviderRoute2(data)
   };
 }
+var CAMPAIGN_BUILDER_TERMINAL_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "canceled", "cancelled"]);
+var CAMPAIGN_BUILDER_BLOCKED_TERMINAL_STATUSES = /* @__PURE__ */ new Set(["failed", "canceled", "cancelled"]);
+function mapAgentCampaignPhaseHealth(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((phase) => {
+    const record = asRecord(phase);
+    return {
+      phase: stringValue(record.phase) ?? "unknown",
+      status: stringValue(record.status) ?? "unknown",
+      recordsProcessed: numberOrNull2(record.records_processed ?? record.recordsProcessed),
+      recordsSucceeded: numberOrNull2(record.records_succeeded ?? record.recordsSucceeded),
+      recordsFailed: numberOrNull2(record.records_failed ?? record.recordsFailed),
+      heartbeatAgeSeconds: numberOrNull2(record.heartbeat_age_seconds ?? record.heartbeatAgeSeconds ?? record.phase_age_seconds)
+    };
+  });
+}
+function deriveCampaignBuildTerminalState(input) {
+  const status = input.status.toLowerCase();
+  const heartbeatAgeSeconds = input.phaseAgeSeconds;
+  const stale = input.staleRunningPhase === true;
+  const safeWatchAction = input.triggerRunId ? `signaliz ops run-status ${input.triggerRunId} --watch` : "signaliz campaign-agent status <campaign_build_id>";
+  if (CAMPAIGN_BUILDER_BLOCKED_TERMINAL_STATUSES.has(status)) {
+    return {
+      kind: "blocked",
+      label: "Blocked terminal state",
+      reviewable: true,
+      terminal: true,
+      stale: false,
+      phase: input.phase,
+      phaseStatus: input.phaseStatus,
+      heartbeatAgeSeconds,
+      nextPollAfterSeconds: input.nextPollAfterSeconds,
+      terminalReason: input.terminalReason,
+      staleReason: null,
+      safeNextAction: input.nextAction || "Review errors and rerun only after the blocker is resolved."
+    };
+  }
+  if (status === "pending_approval") {
+    return {
+      kind: "pending_approval",
+      label: "Pending delivery approval",
+      reviewable: true,
+      terminal: false,
+      stale: false,
+      phase: input.phase,
+      phaseStatus: input.phaseStatus,
+      heartbeatAgeSeconds,
+      nextPollAfterSeconds: input.nextPollAfterSeconds,
+      terminalReason: input.terminalReason,
+      staleReason: null,
+      safeNextAction: input.approvalAction || input.nextAction || "Review rows and approve delivery only after the approval packet passes."
+    };
+  }
+  if (CAMPAIGN_BUILDER_TERMINAL_STATUSES.has(status)) {
+    return {
+      kind: "terminal",
+      label: "Terminal and reviewable",
+      reviewable: true,
+      terminal: true,
+      stale: false,
+      phase: input.phase,
+      phaseStatus: input.phaseStatus,
+      heartbeatAgeSeconds,
+      nextPollAfterSeconds: input.nextPollAfterSeconds,
+      terminalReason: input.terminalReason,
+      staleReason: null,
+      safeNextAction: input.nextAction || "Review rows, artifacts, scorecard, and approval locks before delivery."
+    };
+  }
+  if (status === "running" || status === "queued" || status === "processing") {
+    if (stale) {
+      return {
+        kind: "running_stale",
+        label: "Running but stale",
+        reviewable: false,
+        terminal: false,
+        stale: true,
+        phase: input.phase,
+        phaseStatus: input.phaseStatus,
+        heartbeatAgeSeconds,
+        nextPollAfterSeconds: input.nextPollAfterSeconds,
+        terminalReason: null,
+        staleReason: input.staleReason || "The active phase heartbeat is stale.",
+        safeNextAction: input.nextAction || safeWatchAction
+      };
+    }
+    return {
+      kind: "running_healthy",
+      label: "Running and healthy",
+      reviewable: false,
+      terminal: false,
+      stale: false,
+      phase: input.phase,
+      phaseStatus: input.phaseStatus,
+      heartbeatAgeSeconds,
+      nextPollAfterSeconds: input.nextPollAfterSeconds,
+      terminalReason: null,
+      staleReason: null,
+      safeNextAction: input.nextAction || safeWatchAction
+    };
+  }
+  return {
+    kind: "unknown",
+    label: "Unknown build state",
+    reviewable: false,
+    terminal: false,
+    stale,
+    phase: input.phase,
+    phaseStatus: input.phaseStatus,
+    heartbeatAgeSeconds,
+    nextPollAfterSeconds: input.nextPollAfterSeconds,
+    terminalReason: input.terminalReason,
+    staleReason: input.staleReason,
+    safeNextAction: input.nextAction || "Read campaign build status again before making a launch or delivery decision."
+  };
+}
 function mapAgentCampaignBuildStatus(data) {
+  const customerRowCounts = mapAgentCustomerRowCounts(data.customer_row_counts);
+  const phaseHealth = mapAgentCampaignPhaseHealth(data.phases);
+  const terminalReason = stringValue(data.terminal_reason) ?? customerRowCounts?.terminalReason ?? null;
+  const staleReason = stringValue(data.stale_reason) ?? stringValue(asRecord(data.diagnostics).stale_reason) ?? null;
+  const nextPollAfterSeconds = numberOrNull2(data.next_poll_after_seconds ?? data.nextPollAfterSeconds);
+  const terminalState = deriveCampaignBuildTerminalState({
+    status: stringValue(data.status) ?? "unknown",
+    phase: stringValue(data.current_phase) ?? null,
+    phaseStatus: stringValue(data.current_phase_status) ?? null,
+    staleRunningPhase: data.stale_running_phase === true,
+    phaseAgeSeconds: numberOrNull2(data.phase_age_seconds),
+    nextPollAfterSeconds,
+    terminalReason,
+    staleReason,
+    nextAction: formatAgentNextAction(data.next_action),
+    approvalAction: formatAgentNextAction(data.approval_action),
+    triggerRunId: stringValue(data.trigger_run_id) ?? null
+  });
   return {
     campaignBuildId: stringValue(data.campaign_build_id) ?? "",
     campaignId: stringValue(data.campaign_id) ?? null,
@@ -4269,12 +4446,18 @@ function mapAgentCampaignBuildStatus(data) {
     errors: diagnosticMessages2(data.errors),
     artifactCount: numberOrUndefined2(data.artifact_count) ?? 0,
     artifactDownloads: Array.isArray(data.artifact_downloads) ? data.artifact_downloads.map(mapAgentCampaignArtifactDownload) : [],
-    customerRowCounts: mapAgentCustomerRowCounts(data.customer_row_counts),
+    customerRowCounts,
     phaseAttemptTotals: nullableRecord(data.phase_attempt_totals) ?? void 0,
     providerRoute: mapProviderRoute2(data),
     triggerRunId: stringValue(data.trigger_run_id) ?? null,
     staleRunningPhase: data.stale_running_phase === true,
     phaseAgeSeconds: numberOrNull2(data.phase_age_seconds),
+    nextPollAfterSeconds,
+    terminalReason,
+    staleReason,
+    safeNextAction: terminalState.safeNextAction,
+    terminalState,
+    phaseHealth,
     diagnostics: nullableRecord(data.diagnostics) ?? {},
     nextAction: formatAgentNextAction(data.next_action),
     approvalAction: formatAgentNextAction(data.approval_action),
@@ -4362,67 +4545,285 @@ function mapAgentCampaignArtifact(data) {
     createdAt: stringValue(data.created_at) ?? ""
   };
 }
+var NORTH_STAR_BANNED_COPY_PHRASES = [
+  "i have been following",
+  "i saw that",
+  "would you be opposed",
+  "unlock new opportunities",
+  "significant success",
+  "we understand",
+  "hope this finds you well"
+];
+function campaignReviewGate(id, label, status, detail) {
+  return {
+    id,
+    label,
+    status,
+    passed: status !== "blocked",
+    detail
+  };
+}
+function northStarMetric(id, label, status, detail, value, target) {
+  return {
+    id,
+    label,
+    status,
+    detail,
+    ...value !== void 0 ? { value } : {},
+    ...target !== void 0 ? { target } : {}
+  };
+}
+function createCampaignBuilderNorthStarScorecard(status, rows, artifacts, terminalState) {
+  if (!terminalState.reviewable) {
+    const pendingMetric = northStarMetric(
+      "terminal_state",
+      "Terminal-state contract",
+      terminalState.kind === "running_stale" ? "blocked" : "pending",
+      terminalState.kind === "running_stale" ? `Build is stale in ${terminalState.phase || "unknown phase"}; do not grade output yet.` : `Build is ${terminalState.label.toLowerCase()}; wait for terminal or approval state before grading.`,
+      terminalState.kind,
+      "terminal or pending_approval"
+    );
+    return {
+      version: "campaign-builder-north-star.v1",
+      status: pendingMetric.status,
+      score: null,
+      moatState: "scaffolding_ready",
+      metrics: [pendingMetric],
+      blockers: pendingMetric.status === "blocked" ? [pendingMetric.detail] : [],
+      warnings: pendingMetric.status === "pending" ? [pendingMetric.detail] : [],
+      nextAction: terminalState.safeNextAction
+    };
+  }
+  const sampledRows = rows.rows.length;
+  const rowData = rows.rows.map((row) => asRecord(row.data));
+  const requestedTarget = status.customerRowCounts?.requestedTarget ?? status.recordsTotal ?? rows.count;
+  const finalRows = status.customerRowCounts?.deliveredRows ?? status.customerRowCounts?.qaReadyRows ?? status.customerRowCounts?.copiedRows ?? status.customerRowCounts?.acceptedRows ?? rows.count;
+  const rowsWithEmail = rows.rows.filter(campaignReviewRowHasEmail).length;
+  const verifiedEmailRows = rowData.filter(campaignReviewDataHasVerifiedEmail).length;
+  const uniqueEmails = new Set(rowData.map(campaignReviewDataEmail).filter(Boolean)).size;
+  const uniqueDomains = new Set(rowData.map(campaignReviewDataDomain).filter(Boolean)).size;
+  const copyReadyRows = rows.rows.filter(campaignReviewRowHasCopy).length;
+  const copyQaIssuesByRow = rowData.map(campaignReviewDataCopyQaIssues).filter((issues) => issues.length > 0);
+  const copyQaIssueCounts = countCampaignReviewIssues(copyQaIssuesByRow);
+  const signalBackedRows = rowData.filter(campaignReviewDataHasSignalBasis).length;
+  const noSupportedSignalRows = rowData.filter(campaignReviewDataHasNoSupportedSignal).length;
+  const unsupportedSignalClaims = rowData.filter(campaignReviewDataHasUnsupportedSignalClaim).length;
+  const approvalLockedRows = rowData.filter(campaignReviewDataHasApprovalLock).length;
+  const holdoutRows = rowData.filter(campaignReviewDataHasHoldoutAttribution).length;
+  const artifactCount = artifacts.length || status.artifactCount || 0;
+  const deliveredRows = status.customerRowCounts?.deliveredRows ?? 0;
+  const feedbackReady = campaignReviewStatusHasFeedbackReadiness(status);
+  const feedbackRequiredForApproval = terminalState.kind === "pending_approval";
+  const moat = campaignReviewMoatState(status, holdoutRows);
+  const metrics = [
+    northStarMetric(
+      "terminal_state",
+      "Terminal-state contract",
+      terminalState.kind === "blocked" ? "blocked" : "pass",
+      terminalState.label,
+      terminalState.kind,
+      "terminal or pending_approval"
+    ),
+    northStarMetric(
+      "target_fill",
+      "Target fill",
+      requestedTarget && finalRows < requestedTarget ? "review" : "pass",
+      requestedTarget ? `${finalRows || 0}/${requestedTarget} final or reviewable row(s) are accounted for.` : "No requested target was reported; using sampled rows for review.",
+      finalRows || sampledRows,
+      requestedTarget || sampledRows
+    ),
+    northStarMetric(
+      "unique_emails",
+      "Unique emails",
+      sampledRows === 0 ? "blocked" : uniqueEmails === rowsWithEmail ? "pass" : "blocked",
+      sampledRows === 0 ? "No sampled rows were available for email uniqueness review." : `${uniqueEmails}/${rowsWithEmail} sampled email(s) are unique.`,
+      uniqueEmails,
+      rowsWithEmail
+    ),
+    northStarMetric(
+      "unique_domains",
+      "Unique domains",
+      sampledRows === 0 ? "blocked" : uniqueDomains === sampledRows ? "pass" : "review",
+      sampledRows === 0 ? "No sampled rows were available for domain uniqueness review." : `${uniqueDomains}/${sampledRows} sampled company domain(s) are unique.`,
+      uniqueDomains,
+      sampledRows
+    ),
+    northStarMetric(
+      "verified_email_rows",
+      "Verified email rows",
+      sampledRows === 0 ? "blocked" : verifiedEmailRows === sampledRows ? "pass" : rowsWithEmail === sampledRows ? "review" : "blocked",
+      sampledRows === 0 ? "No sampled rows were available for email verification review." : `${verifiedEmailRows}/${sampledRows} sampled row(s) carry verified-email evidence.`,
+      verifiedEmailRows,
+      sampledRows
+    ),
+    northStarMetric(
+      "copy_completeness",
+      "Copy completeness",
+      sampledRows === 0 ? "blocked" : copyReadyRows === sampledRows ? "pass" : "blocked",
+      sampledRows === 0 ? "No sampled rows were available for copy review." : `${copyReadyRows}/${sampledRows} sampled row(s) include generated copy.`,
+      copyReadyRows,
+      sampledRows
+    ),
+    northStarMetric(
+      "copy_quality",
+      "Copy QA",
+      copyQaIssuesByRow.length === 0 ? "pass" : "blocked",
+      copyQaIssuesByRow.length === 0 ? "No sampled copy QA blockers were detected." : `${copyQaIssuesByRow.length}/${sampledRows} sampled row(s) have copy QA issue(s): ${formatCampaignReviewIssueCounts(copyQaIssueCounts)}.`,
+      copyQaIssuesByRow.length,
+      0
+    ),
+    northStarMetric(
+      "signal_grounding",
+      "Signal grounding",
+      unsupportedSignalClaims > 0 ? "blocked" : signalBackedRows > 0 ? "pass" : "review",
+      unsupportedSignalClaims > 0 ? `${unsupportedSignalClaims} sampled row(s) make unsupported signal claims.` : signalBackedRows > 0 ? `${signalBackedRows}/${sampledRows} sampled row(s) include supported signal or personalization basis.` : noSupportedSignalRows > 0 ? `${noSupportedSignalRows}/${sampledRows} sampled row(s) are explicitly marked no_supported_signal; copy should stay conservative.` : "No sampled rows include supported signal evidence; copy should stay conservative.",
+      signalBackedRows,
+      sampledRows
+    ),
+    northStarMetric(
+      "approval_locks",
+      "Approval locks",
+      approvalLockedRows > 0 || deliveredRows === 0 ? "pass" : "review",
+      approvalLockedRows > 0 ? `${approvalLockedRows}/${sampledRows} sampled row(s) show approval/export lock metadata.` : "Approval-lock metadata was not visible in sampled rows; preserve delivery approval gates.",
+      approvalLockedRows,
+      sampledRows
+    ),
+    northStarMetric(
+      "export_send_safety",
+      "Export/send safety",
+      deliveredRows > 0 && status.status !== "completed" ? "blocked" : "pass",
+      deliveredRows > 0 ? `${deliveredRows} row(s) are delivered; status is ${status.status}.` : "No delivered rows are reported before approval.",
+      deliveredRows,
+      0
+    ),
+    northStarMetric(
+      "holdout_attribution",
+      "Holdout attribution",
+      holdoutRows > 0 ? "pass" : "review",
+      holdoutRows > 0 ? `${holdoutRows}/${sampledRows} sampled row(s) preserve holdout attribution.` : "No holdout attribution was visible in the sampled rows.",
+      holdoutRows,
+      sampledRows
+    ),
+    northStarMetric(
+      "feedback_readiness",
+      "Feedback readiness",
+      feedbackReady ? "pass" : feedbackRequiredForApproval ? "blocked" : "review",
+      feedbackReady ? "Feedback readiness is visible in status diagnostics." : feedbackRequiredForApproval ? "Feedback webhook or approved pull readiness is required before delivery approval." : "Feedback webhook or approved pull readiness was not visible; require it before real send approval.",
+      feedbackReady,
+      true
+    ),
+    northStarMetric(
+      "causal_moat",
+      "Causal moat",
+      moat.state === "proved" ? "pass" : "review",
+      moat.detail,
+      moat.state,
+      "proved"
+    ),
+    northStarMetric(
+      "artifact_readback",
+      "Artifact readback",
+      artifactCount > 0 ? "pass" : "review",
+      artifactCount > 0 ? `${artifactCount} artifact(s) are available for review.` : "No review artifact is available yet.",
+      artifactCount,
+      1
+    )
+  ];
+  const gradedMetrics = metrics.filter((metric) => metric.status !== "pending");
+  const score = gradedMetrics.length === 0 ? null : Math.round(gradedMetrics.filter((metric) => metric.status === "pass").length / gradedMetrics.length * 100);
+  const blockers = metrics.filter((metric) => metric.status === "blocked").map((metric) => metric.detail);
+  const warnings = metrics.filter((metric) => metric.status === "review").map((metric) => metric.detail);
+  const scorecardStatus = blockers.length > 0 ? "blocked" : warnings.length > 0 ? "review" : "pass";
+  return {
+    version: "campaign-builder-north-star.v1",
+    status: scorecardStatus,
+    score,
+    moatState: moat.state,
+    metrics,
+    blockers,
+    warnings,
+    nextAction: scorecardStatus === "blocked" ? "Fix blocked North Star gates before approval or delivery." : terminalState.safeNextAction
+  };
+}
 function createCampaignBuilderBuildReview(status, rows, artifacts) {
+  const terminalState = status.terminalState ?? deriveCampaignBuildTerminalState({
+    status: status.status,
+    phase: status.currentPhase,
+    phaseStatus: status.currentPhaseStatus,
+    staleRunningPhase: status.staleRunningPhase === true,
+    phaseAgeSeconds: status.phaseAgeSeconds ?? null,
+    nextPollAfterSeconds: status.nextPollAfterSeconds ?? null,
+    terminalReason: status.terminalReason ?? status.customerRowCounts?.terminalReason ?? null,
+    staleReason: status.staleReason ?? null,
+    nextAction: status.nextAction,
+    approvalAction: status.approvalAction,
+    triggerRunId: status.triggerRunId ?? null
+  });
   const sampledRows = rows.rows.length;
   const availableRows = rows.count || sampledRows;
   const qualifiedRows = rows.rows.filter((row) => row.qualified !== false).length;
   const rowsWithEmail = rows.rows.filter(campaignReviewRowHasEmail).length;
   const copyReadyRows = rows.rows.filter(campaignReviewRowHasCopy).length;
   const artifactCount = artifacts.length || status.artifactCount || 0;
+  const northStarScorecard = createCampaignBuilderNorthStarScorecard(status, rows, artifacts, terminalState);
   const gates = [
-    {
-      id: "build_completed",
-      label: "Build completed",
-      passed: status.status === "completed",
-      detail: status.status === "completed" ? "The campaign build is completed." : `The campaign build is ${status.status}; review again after completion.`
-    },
-    {
-      id: "rows_available",
-      label: "Rows available",
-      passed: sampledRows > 0,
-      detail: sampledRows > 0 ? `${sampledRows} sampled row(s) are available for review.` : "No rows were returned for review."
-    },
-    {
-      id: "qualified_sample",
-      label: "Sample rows qualified",
-      passed: sampledRows > 0 && qualifiedRows === sampledRows,
-      detail: sampledRows > 0 ? `${qualifiedRows}/${sampledRows} sampled row(s) are marked qualified.` : "Qualification could not be checked without sampled rows."
-    },
-    {
-      id: "email_coverage",
-      label: "Email coverage",
-      passed: sampledRows > 0 && rowsWithEmail === sampledRows,
-      detail: sampledRows > 0 ? `${rowsWithEmail}/${sampledRows} sampled row(s) include an email.` : "Email coverage could not be checked without sampled rows."
-    },
-    {
-      id: "artifact_available",
-      label: "Artifact available",
-      passed: artifactCount > 0,
-      detail: artifactCount > 0 ? `${artifactCount} artifact(s) are available.` : "No delivery artifact is available yet."
-    },
-    {
-      id: "no_failed_rows",
-      label: "No failed rows",
-      passed: status.recordsFailed === 0,
-      detail: status.recordsFailed === 0 ? "The build reports zero failed rows." : `${status.recordsFailed} row(s) failed during the build.`
-    }
+    campaignReviewGate(
+      "build_reviewable",
+      "Build reviewable",
+      terminalState.kind === "running_healthy" ? "pending" : terminalState.kind === "running_stale" || terminalState.kind === "blocked" ? "blocked" : "pass",
+      terminalState.label
+    ),
+    campaignReviewGate(
+      "rows_available",
+      "Rows available",
+      sampledRows > 0 ? "pass" : terminalState.reviewable ? "blocked" : "pending",
+      sampledRows > 0 ? `${sampledRows} sampled row(s) are available for review.` : terminalState.reviewable ? "No rows were returned for review." : "Rows are not graded until the build is reviewable."
+    ),
+    campaignReviewGate(
+      "qualified_sample",
+      "Sample rows qualified",
+      sampledRows === 0 ? terminalState.reviewable ? "blocked" : "pending" : qualifiedRows === sampledRows ? "pass" : "blocked",
+      sampledRows > 0 ? `${qualifiedRows}/${sampledRows} sampled row(s) are marked qualified.` : "Qualification could not be checked without sampled rows."
+    ),
+    campaignReviewGate(
+      "email_coverage",
+      "Email coverage",
+      sampledRows === 0 ? terminalState.reviewable ? "blocked" : "pending" : rowsWithEmail === sampledRows ? "pass" : "blocked",
+      sampledRows > 0 ? `${rowsWithEmail}/${sampledRows} sampled row(s) include an email.` : "Email coverage could not be checked without sampled rows."
+    ),
+    campaignReviewGate(
+      "artifact_available",
+      "Artifact available",
+      artifactCount > 0 ? "pass" : terminalState.reviewable ? "review" : "pending",
+      artifactCount > 0 ? `${artifactCount} artifact(s) are available.` : "No delivery artifact is available yet."
+    ),
+    campaignReviewGate(
+      "no_failed_rows",
+      "No failed rows",
+      status.recordsFailed === 0 ? "pass" : "blocked",
+      status.recordsFailed === 0 ? "The build reports zero failed rows." : `${status.recordsFailed} row(s) failed during the build.`
+    )
   ];
-  const blockedReasons = gates.filter((gate) => !gate.passed).map((gate) => gate.detail);
+  const blockedReasons = gates.filter((gate) => gate.status === "blocked" || !gate.passed).map((gate) => gate.detail);
   const warnings = [
     rows.hasMore ? "This review is based on a row sample; page through remaining rows before final approval." : void 0,
     sampledRows > 0 && copyReadyRows < sampledRows ? `${copyReadyRows}/${sampledRows} sampled row(s) include generated copy.` : void 0,
     ...status.warnings
   ].filter((item) => Boolean(item));
-  const readyForDeliveryApproval = blockedReasons.length === 0;
+  const readyForDeliveryApproval = terminalState.reviewable && blockedReasons.length === 0 && northStarScorecard.status !== "blocked";
   return {
     campaignBuildId: status.campaignBuildId || rows.campaignBuildId,
     status,
     rows,
     artifacts,
     gates,
+    northStarScorecard,
     summary: {
       status: status.status,
       phase: status.currentPhase,
+      terminalState: terminalState.kind,
+      scorecardStatus: northStarScorecard.status,
+      scorecardScore: northStarScorecard.score,
       sampledRows,
       availableRows,
       qualifiedRows,
@@ -4476,6 +4877,184 @@ function campaignReviewRowHasCopy(row) {
     stringValue(data.subject) || stringValue(data.subject_line) || stringValue(data.subjectLine) || stringValue(data.opener) || stringValue(data.body) || stringValue(data.cta) || stringValue(copy.subject) || stringValue(copy.body) || stringValue(rawCopy.subject) || stringValue(rawCopy.body)
   );
 }
+function campaignReviewDataEmail(data) {
+  return stringValue(data.email) || stringValue(data.work_email) || stringValue(data.workEmail) || stringValue(asRecord(data.contact).email);
+}
+function campaignReviewDataDomain(data) {
+  const domain = stringValue(data.company_domain) || stringValue(data.companyDomain) || stringValue(asRecord(data.company).domain);
+  return domain?.toLowerCase();
+}
+function campaignReviewDataHasVerifiedEmail(data) {
+  const status = String(data.email_status ?? data.emailStatus ?? asRecord(data.contact).email_status ?? "").toLowerCase();
+  return data.email_verified === true || data.emailVerified === true || asRecord(data.contact).email_verified === true || ["valid", "validated", "verified"].includes(status);
+}
+function campaignReviewDataCopyParts(data) {
+  const copy = asRecord(data.copy);
+  const rawCopy = asRecord(data.raw_copy ?? data.rawCopy);
+  return [
+    stringValue(data.subject),
+    stringValue(data.subject_line),
+    stringValue(data.opener),
+    stringValue(data.body),
+    stringValue(data.cta),
+    stringValue(copy.subject),
+    stringValue(copy.opener),
+    stringValue(copy.body),
+    stringValue(copy.cta),
+    stringValue(rawCopy.subject),
+    stringValue(rawCopy.opener),
+    stringValue(rawCopy.body),
+    stringValue(rawCopy.cta)
+  ].filter((part) => Boolean(part));
+}
+function campaignReviewDataHasBadGreeting(data) {
+  return campaignReviewDataCopyParts(data).some(
+    (part) => /\bhi\s*(?:,|\{\{|\[)|\bhello\s*(?:,|\{\{|\[)/i.test(part) || /\b(first_name|firstname|name)\b/i.test(part)
+  );
+}
+function campaignReviewDataHasBannedPhrase(data) {
+  const text = campaignReviewDataCopyParts(data).join(" ").toLowerCase();
+  return NORTH_STAR_BANNED_COPY_PHRASES.some((phrase) => text.includes(phrase));
+}
+function campaignReviewDataSubject(data) {
+  const copy = asRecord(data.copy);
+  const rawCopy = asRecord(data.raw_copy ?? data.rawCopy);
+  return stringValue(data.subject) || stringValue(data.subject_line) || stringValue(data.subjectLine) || stringValue(copy.subject) || stringValue(rawCopy.subject);
+}
+function campaignReviewDataCta(data) {
+  const copy = asRecord(data.copy);
+  const rawCopy = asRecord(data.raw_copy ?? data.rawCopy);
+  return stringValue(data.cta) || stringValue(copy.cta) || stringValue(rawCopy.cta);
+}
+function countCampaignReviewIssues(issueRows) {
+  return issueRows.flat().reduce((acc, issue) => {
+    acc[issue] = (acc[issue] || 0) + 1;
+    return acc;
+  }, {});
+}
+function formatCampaignReviewIssueCounts(counts) {
+  const entries = Object.entries(counts);
+  return entries.length > 0 ? entries.map(([issue, count]) => `${issue}=${count}`).join(", ") : "none";
+}
+function campaignReviewDataCopyQaIssues(data) {
+  const issues = /* @__PURE__ */ new Set();
+  const copyParts = campaignReviewDataCopyParts(data);
+  if (copyParts.length === 0) return [];
+  if (campaignReviewDataHasBadGreeting(data)) issues.add("bad_greeting");
+  if (campaignReviewDataHasBannedPhrase(data)) issues.add("banned_or_vague_phrase");
+  if (campaignReviewDataHasUnsupportedSignalClaim(data)) issues.add("unsupported_signal_claim");
+  if (campaignReviewDataPersonalizationBasis(data).length === 0) issues.add("missing_personalization_basis");
+  if (!campaignReviewDataCta(data)) issues.add("missing_cta");
+  const subject = campaignReviewDataSubject(data);
+  if (subject && subject.length > 70) issues.add("overlong_subject");
+  return [...issues];
+}
+function campaignReviewDataPersonalizationBasis(data) {
+  const rawCopy = asRecord(data.raw_copy ?? data.rawCopy);
+  const copy = asRecord(data.copy);
+  const metadata = asRecord(data.metadata);
+  const signalEvidence = asRecord(data.signal_evidence ?? metadata.signal_evidence ?? metadata.signalEvidence);
+  return [
+    ...arrayOfStrings(data.personalization_basis) ?? [],
+    ...arrayOfStrings(data.personalizationBasis) ?? [],
+    ...arrayOfStrings(copy.personalization_basis) ?? [],
+    ...arrayOfStrings(rawCopy.personalization_basis) ?? [],
+    ...arrayOfStrings(metadata.personalization_basis) ?? [],
+    ...arrayOfStrings(metadata.personalizationBasis) ?? [],
+    ...arrayOfStrings(signalEvidence.personalization_basis) ?? []
+  ];
+}
+function campaignReviewDataHasNoSupportedSignal(data) {
+  const metadata = asRecord(data.metadata);
+  const copy = asRecord(data.copy);
+  const state = [
+    data.copy_signal_state,
+    data.signal_basis,
+    data.signal_type,
+    metadata.copy_signal_state,
+    metadata.signal_basis,
+    metadata.signal_type,
+    copy.copy_signal_state
+  ].map((value) => stringValue(value)?.toLowerCase()).filter(Boolean);
+  return data.no_supported_signal === true || metadata.no_supported_signal === true || state.includes("no_supported_signal");
+}
+function campaignReviewDataHasSignalBasis(data) {
+  if (campaignReviewDataHasNoSupportedSignal(data)) return false;
+  const metadata = asRecord(data.metadata);
+  const signal = asRecord(data.signal);
+  const signalEvidence = asRecord(data.signal_evidence ?? metadata.signal_evidence ?? metadata.signalEvidence);
+  const basis = campaignReviewDataPersonalizationBasis(data);
+  return Boolean(
+    stringValue(data.signal_type) || stringValue(data.signalType) || stringValue(data.signal_summary) || stringValue(data.signalSummary) || stringValue(data.signal_source_url) || stringValue(data.signalSourceUrl) || stringValue(metadata.signal_type) || stringValue(metadata.signal_summary) || stringValue(metadata.signal_source_url) || stringValue(signal.type) || stringValue(signal.summary) || stringValue(signal.source_url) || stringValue(signalEvidence.signal_type) || stringValue(signalEvidence.summary) || stringValue(signalEvidence.source_url) || basis.some((item) => /\bsignal|hiring|funding|leadership|growth|launch|news|technology\b/i.test(item))
+  );
+}
+function campaignReviewDataHasUnsupportedSignalClaim(data) {
+  const copyText = campaignReviewDataCopyParts(data).join(" ").toLowerCase();
+  const claimsSignal = /\b(hiring|funding|raised|launched|expanding|appointed|announced|recent news|new role|job posting)\b/.test(copyText);
+  return claimsSignal && !campaignReviewDataHasSignalBasis(data);
+}
+function campaignReviewDataHasApprovalLock(data) {
+  const metadata = asRecord(data.fit_metadata ?? data.metadata);
+  const approval = String(data.approval_status ?? data.delivery_approval_status ?? metadata.approval_status ?? "").toLowerCase();
+  const exportStatus = String(data.export_status ?? data.exportStatus ?? "").toLowerCase();
+  return data.export_ready === false || data.exportReady === false || data.delivery_approved === false || data.deliveryApproved === false || ["pending", "pending_approval", "blocked", "approval_required", "held"].includes(approval) || ["pending", "blocked", "approval_required", "held"].includes(exportStatus);
+}
+function campaignReviewDataHasHoldoutAttribution(data) {
+  const fitMetadata = asRecord(data.fit_metadata ?? data.fitMetadata);
+  const metadata = asRecord(data.metadata);
+  const holdout = asRecord(
+    fitMetadata.learning_holdout ?? fitMetadata.learningHoldout ?? metadata.learning_holdout ?? metadata.learningHoldout ?? data.learning_holdout ?? data.learningHoldout
+  );
+  const experimentKey = stringValue(holdout.experiment_key ?? holdout.experimentKey ?? data.experiment_key ?? data.experimentKey);
+  const cohort = stringValue(holdout.cohort_role ?? holdout.cohortRole ?? data.cohort_role ?? data.learning_cohort ?? data.learningCohort);
+  const brainApplied = holdout.brain_applied ?? holdout.brainApplied ?? data.brain_applied ?? data.signaliz_brain_applied;
+  return Boolean(experimentKey && cohort && brainApplied !== void 0);
+}
+function campaignReviewStatusHasFeedbackReadiness(status) {
+  const diagnostics = asRecord(status.diagnostics);
+  const feedbackReadiness = asRecord(diagnostics.feedback_readiness ?? diagnostics.feedbackReadiness);
+  const feedbackSubstrate = asRecord(diagnostics.feedback_substrate ?? diagnostics.feedbackSubstrate);
+  const evidenceCounts = asRecord(diagnostics.evidence_counts ?? diagnostics.evidenceCounts);
+  return feedbackReadiness.ready === true || feedbackReadiness.webhook_configured === true || feedbackSubstrate.stage === "ready" || Number(evidenceCounts.feedback_events ?? 0) > 0;
+}
+function campaignReviewMoatState(status, holdoutRows) {
+  const diagnostics = asRecord(status.diagnostics);
+  const evidenceCounts = asRecord(diagnostics.evidence_counts ?? diagnostics.evidenceCounts);
+  const embeddedHoldout = asRecord(diagnostics.embedded_holdout ?? diagnostics.embeddedHoldout);
+  const holdoutLift = asRecord(diagnostics.holdout_lift ?? diagnostics.holdoutLift ?? diagnostics.holdout_measurement ?? diagnostics.holdoutMeasurement);
+  const controlSample = Math.max(
+    Number(evidenceCounts.holdout_control_sample_size ?? 0),
+    Number(evidenceCounts.embedded_holdout_control_sample ?? 0),
+    Number(embeddedHoldout.control_sample_size ?? 0)
+  );
+  const learnedSample = Math.max(
+    Number(evidenceCounts.holdout_learned_sample_size ?? 0),
+    Number(evidenceCounts.embedded_holdout_learned_sample ?? 0),
+    Number(embeddedHoldout.learned_sample_size ?? 0)
+  );
+  const feedbackEvents = Math.max(
+    Number(evidenceCounts.feedback_events ?? 0),
+    Number(evidenceCounts.campaign_build_feedback_events ?? 0),
+    Number(evidenceCounts.delivery_holdout_sent_outcomes ?? 0)
+  );
+  const proved = diagnostics.closed_loop_proof_ready === true || holdoutLift.honest_measurement === true && holdoutLift.positive_lift === true;
+  if (proved) {
+    return {
+      state: "proved",
+      detail: "Real attributed feedback shows positive lift for explicit control and learned cohorts."
+    };
+  }
+  if (controlSample > 0 && learnedSample > 0 && feedbackEvents > 0) {
+    return {
+      state: "moved_needs_lift_volume",
+      detail: `Control and learned cohorts have attributed feedback (${controlSample} control, ${learnedSample} learned, ${feedbackEvents} feedback event(s)); keep collecting lift volume before claiming proof.`
+    };
+  }
+  return {
+    state: "scaffolding_ready",
+    detail: holdoutRows > 0 ? `${holdoutRows} sampled row(s) carry holdout attribution, but real control/learned feedback lift is not proved yet.` : "Holdout and feedback scaffolding may be ready, but no real control/learned feedback lift is proved yet."
+  };
+}
 function createCampaignBuilderReadinessLane(route, plan) {
   const builtIn = campaignBuilderBuiltInForRoute(route);
   const customRoute = route.provider !== "signaliz" && route.provider !== "csv" && builtIn === void 0;
@@ -7691,6 +8270,16 @@ var GtmKernel = class {
       min_privacy_k: input.minPrivacyK
     });
   }
+  /** Queue a dry-run-first bridge from imported historical feedback to attribution-only Campaign Build surrogates. */
+  async runHistoricalCampaignBuildBridge(input = {}) {
+    return this.callMcp("gtm_historical_campaign_build_bridge_run", {
+      dry_run: input.dryRun,
+      write_approved: input.writeApproved,
+      max_events: input.maxEvents,
+      max_campaigns: input.maxCampaigns,
+      min_feedback_events: input.minFeedbackEvents
+    });
+  }
   /** Prepare a provider-agnostic feedback webhook URL for Smartlead, HeyReach, Airbyte, or custom sender events. */
   async prepareFeedbackWebhook(input) {
     return this.callMcp("gtm_feedback_webhook_prepare", {