@kivimedia/kmhub 2.0.0 → 2.9.1

package/coach-book-output-guard.mjs

@@ -0,0 +1,760 @@
+const FORBIDDEN_OUTPUT_KEYS = new Set([
+  'credential', 'credentials', 'accesstoken', 'refreshtoken', 'apikey',
+  'password', 'secret', 'secretvalue', 'clientsecret', 'token',
+  'authorization', 'bearer', 'privatekey', 'signature',
+  'protectedspec', 'sourcetext', 'chunktext', 'excerpt', 'embedding',
+  'vector', 'vectors', 'queryvector', 'clausevector', 'clausevectors',
+  'anchor', 'anchors', 'anchorid', 'anchorids', 'semantictext', 'semantictexts',
+  'semanticmodel', 'modelinternals',
+  'systemprompt', 'providerconfig', 'connectorconfig', 'runtimeadapterid',
+  'adaptersecret', 'sourcecode', 'skillfile', 'skillfiles', 'skillpath',
+  'sqlquery', 'formula', 'expression', 'when', 'left', 'right',
+  'forbiddeneffects', 'sourcedocumentid', 'sourcesha256',
+]);
+
+const SECRET_VALUE_PATTERNS = [
+  /-----BEGIN(?: [A-Z0-9]+)? PRIVATE KEY-----/i,
+  /\bBearer\s+[A-Za-z0-9._~+/=-]{16,}\b/i,
+  /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/,
+  /\bsk-(?:proj-|svcacct-|ant-)?[A-Za-z0-9_-]{20,}\b/i,
+  /\bgithub_pat_[A-Za-z0-9_]{40,}\b/,
+  /\bgh[pousr]_[A-Za-z0-9]{30,}\b/,
+  /\bxox[baprs]-[A-Za-z0-9-]{20,}\b/i,
+  /\b(?:sk|rk)_live_[A-Za-z0-9]{16,}\b/i,
+  /\bAIza[0-9A-Za-z_-]{30,}\b/,
+  /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/,
+  /\bEA[A-Za-z0-9]{35,}\b/,
+  /\b(?:api[_ -]?key|access[_ -]?token|refresh[_ -]?token|client[_ -]?secret|password)\s*[:=]\s*["']?[A-Za-z0-9_+/.=-]{16,}/i,
+  /(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?):\/\/[^:\s/]+:[^@\s/]{6,}@/i,
+  /[?&](?:access_token|refresh_token|api_key|token|signature|sig)=[A-Za-z0-9_+/.=-]{16,}/i,
+];
+
+export class CoachBookOutputError extends Error {
+  constructor() {
+    super('The Fully Booked Coach response failed public-output verification.');
+    this.name = 'CoachBookOutputError';
+  }
+}
+
+function normalizedKey(key) {
+  return key.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+function record(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new CoachBookOutputError();
+  return value;
+}
+
+function records(value) {
+  if (!Array.isArray(value)) throw new CoachBookOutputError();
+  return value.map(record);
+}
+
+function text(value) {
+  if (typeof value !== 'string') throw new CoachBookOutputError();
+  return value;
+}
+
+function integer(value) {
+  if (!Number.isSafeInteger(value)) throw new CoachBookOutputError();
+  return Number(value);
+}
+
+function number(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) throw new CoachBookOutputError();
+  return value;
+}
+
+function boolean(value) {
+  if (typeof value !== 'boolean') throw new CoachBookOutputError();
+  return value;
+}
+
+function nullableText(value) {
+  if (value === null || value === undefined || value === '') return null;
+  return text(value);
+}
+
+function stringArray(value) {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+    throw new CoachBookOutputError();
+  }
+  return [...value];
+}
+
+function optionalNumber(target, source, key) {
+  if (source[key] !== undefined) target[key] = number(source[key]);
+}
+
+function optionalText(target, source, key) {
+  if (source[key] !== undefined) target[key] = text(source[key]);
+}
+
+function projectRanges(value) {
+  return records(value).map((range) => {
+    const currentLocator = range.start !== undefined || range.end !== undefined;
+    return currentLocator
+      ? { start: integer(range.start), end: integer(range.end) }
+      : { start: integer(range.pdfPageStart), end: integer(range.pdfPageEnd) };
+  });
+}
+
+function projectCitations(value) {
+  return records(value).map((citation) => ({
+    label: text(citation.label),
+    pdfPageStart: integer(citation.pdfPageStart),
+    pdfPageEnd: integer(citation.pdfPageEnd),
+  }));
+}
+
+function projectField(value) {
+  const source = record(value);
+  const projected = {
+    id: text(source.id),
+    type: text(source.type),
+    label: text(source.label),
+    required: boolean(source.required),
+  };
+  optionalText(projected, source, 'helpText');
+  for (const key of ['minimum', 'maximum', 'decimalPlaces', 'minimumItems', 'maximumItems']) {
+    optionalNumber(projected, source, key);
+  }
+  if (source.choices !== undefined) {
+    projected.choices = records(source.choices).map((choice) => ({
+      value: text(choice.value),
+      label: text(choice.label),
+    }));
+  }
+  return projected;
+}
+
+function projectPublicSpec(value) {
+  const source = record(value);
+  const projected = {
+    schemaVersion: text(source.schemaVersion),
+    title: text(source.title),
+    summary: text(source.summary),
+    category: text(source.category),
+    estimatedMinutes: integer(source.estimatedMinutes),
+    executorKind: text(source.executorKind),
+    effectClass: text(source.effectClass),
+    steps: records(source.steps).map((step) => ({
+      id: text(step.id),
+      title: text(step.title),
+      description: text(step.description),
+      fields: records(step.fields).map(projectField),
+    })),
+    artifactSections: records(source.artifactSections).map((section) => ({
+      id: text(section.id),
+      title: text(section.title),
+      fieldIds: stringArray(section.fieldIds),
+      calculationIds: stringArray(section.calculationIds),
+    })),
+    sourceCitations: projectCitations(source.sourceCitations),
+  };
+  optionalText(projected, source, 'availabilityClass');
+  return projected;
+}
+
+function projectCatalogMethod(value) {
+  const source = record(value);
+  return {
+    tool_spec_id: text(source.tool_spec_id),
+    version: integer(source.version),
+    title: text(source.title),
+    sequence: integer(source.sequence),
+    summary: text(source.summary),
+    category: text(source.category),
+    estimated_minutes: integer(source.estimated_minutes),
+    implementation_status: text(source.implementation_status),
+    availability_class: text(source.availability_class),
+    executor_kind: text(source.executor_kind),
+    effect_class: text(source.effect_class),
+    runnable: boolean(source.runnable),
+    specialized: boolean(source.specialized),
+    source_page_ranges: projectRanges(source.source_page_ranges),
+  };
+}
+
+function projectDescribedMethod(value) {
+  const source = record(value);
+  return { ...projectCatalogMethod(source), public_spec: projectPublicSpec(source.public_spec) };
+}
+
+function projectSummary(value) {
+  const source = record(value);
+  return {
+    run_id: text(source.run_id),
+    status: text(source.status),
+    tool_spec_id: text(source.tool_spec_id),
+    tool_spec_version: integer(source.tool_spec_version),
+    artifact_count: integer(source.artifact_count),
+    decision_count: integer(source.decision_count),
+    reserved_charge_usd_micros: source.reserved_charge_usd_micros === undefined
+      ? 0
+      : integer(source.reserved_charge_usd_micros),
+    retained_provider_cost_usd_micros: source.retained_provider_cost_usd_micros === undefined
+      ? 0
+      : integer(source.retained_provider_cost_usd_micros),
+    charged_usd_micros: source.charged_usd_micros === undefined
+      ? 0
+      : integer(source.charged_usd_micros),
+    released_usd_micros: source.released_usd_micros === undefined
+      ? 0
+      : integer(source.released_usd_micros),
+    approved_at: nullableText(source.approved_at),
+    started_at: nullableText(source.started_at),
+    settled_at: nullableText(source.settled_at),
+    created_at: nullableText(source.created_at),
+  };
+}
+
+function projectArtifactValue(value) {
+  if (typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  return stringArray(value);
+}
+
+function projectArtifact(value) {
+  if (value === null || value === undefined) return null;
+  const source = record(value);
+  return {
+    title: text(source.title),
+    sections: records(source.sections).map((section) => ({
+      id: text(section.id),
+      title: text(section.title),
+      values: records(section.values).map((item) => ({
+        id: text(item.id),
+        label: text(item.label),
+        value: projectArtifactValue(item.value),
+      })),
+    })),
+    sourceCitations: projectCitations(source.sourceCitations),
+  };
+}
+
+function projectBoundaries(value) {
+  const source = record(value);
+  return {
+    providerUse: boolean(source.providerUse),
+    spend: boolean(source.spend),
+    contact: boolean(source.contact),
+    publication: boolean(source.publication),
+    durableCrmChange: boolean(source.durableCrmChange),
+    connectorDispatch: boolean(source.connectorDispatch),
+    outcomePromise: boolean(source.outcomePromise),
+    separateApprovalRequired: boolean(source.separateApprovalRequired),
+  };
+}
+
+function projectMethodResult(value) {
+  if (value === null || value === undefined) return null;
+  const source = record(value);
+  return {
+    schemaVersion: text(source.schemaVersion),
+    toolSpecId: text(source.toolSpecId),
+    toolSpecVersion: integer(source.toolSpecVersion),
+    status: text(source.status),
+    completedStepIds: stringArray(source.completedStepIds),
+    nextStepId: nullableText(source.nextStepId),
+    calculations: records(source.calculations).map((calculation) => ({
+      id: text(calculation.id),
+      label: text(calculation.label),
+      rawValue: number(calculation.rawValue),
+      formattedValue: text(calculation.formattedValue),
+    })),
+    decisions: records(source.decisions).map((decision) => ({
+      id: text(decision.id),
+      label: text(decision.label),
+      outcome: text(decision.outcome),
+      guidance: text(decision.guidance),
+    })),
+    artifact: projectArtifact(source.artifact),
+    boundaries: projectBoundaries(source.boundaries),
+  };
+}
+
+function projectReceipt(value) {
+  if (value === null || value === undefined) return null;
+  const source = record(value);
+  const projected = {
+    outcome: text(source.outcome),
+    retained_provider_cost_usd_micros: integer(source.retained_provider_cost_usd_micros),
+    charged_usd_micros: integer(source.charged_usd_micros),
+  };
+  for (const key of ['released_usd_micros', 'promo_released_usd_micros', 'paid_released_usd_micros', 'markup_multiplier']) {
+    if (source[key] !== undefined) projected[key] = integer(source[key]);
+  }
+  for (const key of ['provider_use', 'external_effect_performed']) {
+    if (source[key] !== undefined) projected[key] = boolean(source[key]);
+  }
+  if (source.created_at !== undefined) projected.created_at = nullableText(source.created_at);
+  return projected;
+}
+
+function projectGenericRun(value) {
+  const source = record(value);
+  const method = record(source.method);
+  const progress = record(source.progress);
+  return {
+    summary: projectSummary(source.summary),
+    method: {
+      tool_spec_id: text(method.tool_spec_id),
+      method_id: text(method.method_id),
+      sequence: integer(method.sequence),
+      version: integer(method.version),
+      title: text(method.title),
+      executor_kind: text(method.executor_kind),
+      effect_class: text(method.effect_class),
+      public_spec: projectPublicSpec(method.public_spec),
+      source_page_ranges: projectRanges(method.source_page_ranges),
+    },
+    progress: {
+      completed_step_ids: stringArray(progress.completed_step_ids),
+      next_step_id: nullableText(progress.next_step_id),
+      result: projectMethodResult(progress.result),
+      settlement_pending: boolean(progress.settlement_pending),
+    },
+    receipt: projectReceipt(source.receipt),
+  };
+}
+
+function projectNicheDimension(value) {
+  const source = record(value);
+  const threshold = record(source.threshold);
+  const evidenceGate = record(source.evidenceGate);
+  return {
+    dimension: text(source.dimension),
+    score: number(source.score),
+    threshold: {
+      operator: text(threshold.operator),
+      value: number(threshold.value),
+      sourcePage: integer(threshold.sourcePage),
+    },
+    thresholdPassed: boolean(source.thresholdPassed),
+    falsePositiveObserved: boolean(source.falsePositiveObserved),
+    passed: boolean(source.passed),
+    confidence: text(source.confidence),
+    evidenceGate: {
+      directSourcePresent: boolean(evidenceGate.directSourcePresent),
+      counterevidenceCompleted: boolean(evidenceGate.counterevidenceCompleted),
+      passed: boolean(evidenceGate.passed),
+      failures: stringArray(evidenceGate.failures),
+    },
+  };
+}
+
+function projectNicheResult(value) {
+  const source = record(value);
+  const dimensions = record(source.dimensions);
+  const plan = record(source.validationPlan);
+  const pace = record(plan.paceObservationWeeks);
+  const stopRules = record(plan.falsePositiveStopRules);
+  const boundaries = record(source.boundaries);
+  return {
+    schemaVersion: text(source.schemaVersion),
+    dimensions: {
+      findability: projectNicheDimension(dimensions.findability),
+      bragability: projectNicheDimension(dimensions.bragability),
+      sellability: projectNicheDimension(dimensions.sellability),
+    },
+    overallStatus: text(source.overallStatus),
+    confidence: text(source.confidence),
+    recommendation: text(source.recommendation),
+    validationPlan: {
+      durationDays: integer(plan.durationDays),
+      paceObservationWeeks: { minimum: integer(pace.minimum), maximum: integer(pace.maximum) },
+      weeklyAcceptedCollaborationTarget: integer(plan.weeklyAcceptedCollaborationTarget),
+      approximateAnnualCollaborationPace: integer(plan.approximateAnnualCollaborationPace),
+      brandAssetsRequiredBeforeTest: boolean(plan.brandAssetsRequiredBeforeTest),
+      trackedSignals: stringArray(plan.trackedSignals),
+      falsePositiveStopRules: {
+        findability: text(stopRules.findability),
+        bragability: text(stopRules.bragability),
+        sellability: text(stopRules.sellability),
+      },
+      humanDecisionRequired: boolean(plan.humanDecisionRequired),
+      separateApprovalRequiredFor: stringArray(plan.separateApprovalRequiredFor),
+      performsExternalAction: boolean(plan.performsExternalAction),
+      promisesOutcome: boolean(plan.promisesOutcome),
+      sourcePages: Array.isArray(plan.sourcePages) ? plan.sourcePages.map(integer) : (() => { throw new CoachBookOutputError(); })(),
+      sourceNote: text(plan.sourceNote),
+    },
+    boundaries: {
+      modelScoreAllowed: boolean(boundaries.modelScoreAllowed),
+      providerUse: boolean(boundaries.providerUse),
+      spend: boolean(boundaries.spend),
+      contact: boolean(boundaries.contact),
+      publication: boolean(boundaries.publication),
+      outcomePromise: boolean(boundaries.outcomePromise),
+    },
+  };
+}
+
+function projectNicheRun(value) {
+  const source = record(value);
+  const artifact = source.artifact === null || source.artifact === undefined ? null : record(source.artifact);
+  const decision = source.decision === null || source.decision === undefined ? null : record(source.decision);
+  return {
+    summary: projectSummary(source.summary),
+    artifact: artifact ? {
+      id: text(artifact.id),
+      artifact_type: text(artifact.artifact_type),
+      result: projectNicheResult(artifact.result),
+      source_citations: records(artifact.source_citations).map((citation) => ({
+        locator: text(citation.locator),
+        page_start: integer(citation.page_start),
+        page_end: integer(citation.page_end),
+        supports: text(citation.supports),
+      })),
+      resume_supported_surfaces: stringArray(artifact.resume_supported_surfaces),
+      created_at: nullableText(artifact.created_at),
+    } : null,
+    decision: decision ? {
+      id: text(decision.id),
+      decision_type: text(decision.decision_type),
+      decision_status: text(decision.decision_status),
+      decision_payload: {
+        confirmed_by_user: boolean(record(decision.decision_payload).confirmed_by_user),
+        tool_spec_id: text(record(decision.decision_payload).tool_spec_id),
+        result_status: text(record(decision.decision_payload).result_status),
+        performs_external_action: boolean(record(decision.decision_payload).performs_external_action),
+      },
+      created_at: nullableText(decision.created_at),
+    } : null,
+    receipt: projectReceipt(source.receipt),
+  };
+}
+
+function hasForbiddenOutput(value, allowConfirmationToken = false) {
+  if (typeof value === 'string') return SECRET_VALUE_PATTERNS.some((pattern) => pattern.test(value));
+  if (Array.isArray(value)) return value.some((entry) => hasForbiddenOutput(entry, false));
+  if (!value || typeof value !== 'object') return false;
+  return Object.entries(value).some(([key, child]) => {
+    const normalized = normalizedKey(key);
+    const allowedToken = allowConfirmationToken && normalized === 'confirmtoken';
+    if (!allowedToken && (
+      FORBIDDEN_OUTPUT_KEYS.has(normalized)
+      || normalized.endsWith('token')
+      || normalized.endsWith('secret')
+      || normalized.endsWith('password')
+      || normalized.endsWith('privatekey')
+      || normalized.endsWith('digest')
+    )) return true;
+    return allowedToken ? false : hasForbiddenOutput(child, false);
+  });
+}
+
+function assertPublicOutput(value) {
+  if (hasForbiddenOutput(value)) throw new CoachBookOutputError();
+}
+
+const FBC_METHOD_ID_RE = /^fbc[.]method[.][0-9]{3}[.][a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const FBC_METHOD_RANKER_VERSION = 'fbc.method-ranker.semantic-hybrid-v2';
+const FBC_RECOMMENDATION_OUTCOMES = new Set([
+  'recommended', 'clarification_required', 'no_runnable_match', 'no_match',
+]);
+const FBC_RECOMMENDATION_CONFIDENCE = new Set(['high', 'medium', 'low']);
+const FBC_RECOMMENDATION_AVAILABILITY = new Set(['runnable_only', 'include_pending']);
+const FBC_RECOMMENDATION_EXECUTORS = new Set(['deterministic_single_step', 'guided_multi_step']);
+const FBC_RECOMMENDATION_EFFECTS = new Set(['none', 'action_preview']);
+const FBC_RECOMMENDATION_STAGES = new Set([
+  'purpose_and_capacity', 'oath', 'niche', 'collaboration', 'authority_content',
+  'audience_growth', 'strategy_session', 'offer_and_package', 'follow_up',
+  'client_map', 'super_coaching_delivery', 'results_and_proof', 'renewal_and_referral',
+]);
+const FBC_RECOMMENDATION_REASONS = new Set(['goal_too_broad', 'close_scores', 'low_confidence']);
+const FBC_RECOMMENDATION_STATUSES = new Set(['implemented', 'method_owner_accepted', 'live_proven']);
+const SHA256_RE = /^[0-9a-f]{64}$/;
+
+function boundedText(value, minimum, maximum) {
+  const result = text(value);
+  if (result.length < minimum || result.length > maximum) throw new CoachBookOutputError();
+  return result;
+}
+
+function enumText(value, allowed) {
+  const result = text(value);
+  if (!allowed.has(result)) throw new CoachBookOutputError();
+  return result;
+}
+
+function nullableEnumText(value, allowed) {
+  if (value === null || value === undefined) return null;
+  return enumText(value, allowed);
+}
+
+function methodId(value) {
+  const result = text(value);
+  if (!FBC_METHOD_ID_RE.test(result)) throw new CoachBookOutputError();
+  return result;
+}
+
+function projectRecommendationMatch(value, expectedRank, lane) {
+  const source = record(value);
+  const rank = integer(source.rank);
+  const estimatedMinutes = integer(source.estimated_minutes);
+  const score = number(source.score);
+  if (
+    rank !== expectedRank
+    || estimatedMinutes < 1
+    || estimatedMinutes > 240
+    || score < 0
+    || score > 1
+  ) {
+    throw new CoachBookOutputError();
+  }
+  const matchedIntents = stringArray(source.matched_intents);
+  if (
+    matchedIntents.length > 6
+    || matchedIntents.some((intent) => intent.length < 1 || intent.length > 80)
+  ) {
+    throw new CoachBookOutputError();
+  }
+  const sourcePageRanges = projectRanges(source.source_page_ranges);
+  if (sourcePageRanges.length > 20) throw new CoachBookOutputError();
+  const implementationStatus = enumText(source.implementation_status, FBC_RECOMMENDATION_STATUSES);
+  const runnable = boolean(source.runnable);
+  const canStart = boolean(source.can_start);
+  const laneIsValid = lane === 'runnable'
+    ? ['method_owner_accepted', 'live_proven'].includes(implementationStatus)
+      && runnable === true
+      && canStart === true
+    : implementationStatus === 'implemented'
+      && runnable === false
+      && canStart === false;
+  if (!laneIsValid) throw new CoachBookOutputError();
+  return {
+    rank,
+    tool_spec_id: methodId(source.tool_spec_id),
+    title: boundedText(source.title, 3, 200),
+    summary: boundedText(source.summary, 10, 1200),
+    category: boundedText(source.category, 2, 160),
+    estimated_minutes: estimatedMinutes,
+    executor_kind: enumText(source.executor_kind, FBC_RECOMMENDATION_EXECUTORS),
+    effect_class: enumText(source.effect_class, FBC_RECOMMENDATION_EFFECTS),
+    implementation_status: implementationStatus,
+    runnable,
+    can_start: canStart,
+    score,
+    matched_intents: matchedIntents,
+    use_when: boundedText(source.use_when, 4, 1000),
+    source_page_ranges: sourcePageRanges,
+  };
+}
+
+function projectRecommendationMatches(value, lane) {
+  const source = records(value);
+  if (source.length > 3) throw new CoachBookOutputError();
+  const projected = source.map((match, index) => projectRecommendationMatch(match, index + 1, lane));
+  const toolSpecIds = projected.map((match) => String(match.tool_spec_id));
+  const ranks = projected.map((match) => Number(match.rank));
+  if (new Set(toolSpecIds).size !== toolSpecIds.length || new Set(ranks).size !== ranks.length) {
+    throw new CoachBookOutputError();
+  }
+  return projected;
+}
+function projectRecommendationClarification(value) {
+  if (value === null || value === undefined) return null;
+  const source = record(value);
+  const choices = records(source.choices);
+  if (choices.length < 1 || choices.length > 3) throw new CoachBookOutputError();
+  const question = text(source.question);
+  const instruction = text(source.instruction);
+  if (
+    question !== 'Which result do you want right now?'
+    || instruction !== 'Ask this question exactly and do not choose for the user.'
+  ) {
+    throw new CoachBookOutputError();
+  }
+  return {
+    reason: enumText(source.reason, FBC_RECOMMENDATION_REASONS),
+    question,
+    choices: choices.map((choice) => ({
+      choice_id: methodId(choice.choice_id),
+      label: boundedText(choice.label, 1, 200),
+      description: boundedText(choice.description, 4, 1000),
+    })),
+    instruction,
+  };
+}
+
+function projectRecommendationBoundaries(value) {
+  const source = record(value);
+  const projected = {
+    public_metadata_only: boolean(source.public_metadata_only),
+    source_retrieval: boolean(source.source_retrieval),
+    protected_spec_access: boolean(source.protected_spec_access),
+    provider_use: boolean(source.provider_use),
+    writes: boolean(source.writes),
+    ask_the_book: text(source.ask_the_book),
+  };
+  if (
+    projected.public_metadata_only !== true
+    || projected.source_retrieval !== false
+    || projected.protected_spec_access !== false
+    || projected.provider_use !== false
+    || projected.writes !== false
+    || projected.ask_the_book !== 'closed_by_product_decision'
+  ) {
+    throw new CoachBookOutputError();
+  }
+  return projected;
+}
+
+function assertRecommendationSourceSafe(source) {
+  const {
+    registry_digest: registryDigest,
+    candidate_set_digest: candidateSetDigest,
+    goal_digest: goalDigest,
+    ...publicCandidate
+  } = source;
+  const digests = [registryDigest, candidateSetDigest, goalDigest];
+  const presentDigests = digests.filter((digest) => digest !== undefined);
+  if (presentDigests.length !== 0 && presentDigests.length !== digests.length) {
+    throw new CoachBookOutputError();
+  }
+  for (const digest of presentDigests) {
+    if (typeof digest !== 'string' || !SHA256_RE.test(digest)) throw new CoachBookOutputError();
+  }
+  assertPublicOutput(publicCandidate);
+}
+
+function projectRecommendation(value) {
+  assertRecommendationSourceSafe(value);
+  if (
+    value.schema_version !== 'fbc.method-recommendations.v1'
+    || value.ranker_version !== FBC_METHOD_RANKER_VERSION
+  ) {
+    throw new CoachBookOutputError();
+  }
+  const outcome = enumText(value.outcome, FBC_RECOMMENDATION_OUTCOMES);
+  const confidence = nullableEnumText(value.confidence, FBC_RECOMMENDATION_CONFIDENCE);
+  const context = record(value.context_used);
+  const methodStage = nullableEnumText(context.method_stage, FBC_RECOMMENDATION_STAGES);
+  const maxMinutes = context.max_minutes === null || context.max_minutes === undefined
+    ? null
+    : integer(context.max_minutes);
+  if (maxMinutes !== null && (maxMinutes < 5 || maxMinutes > 240)) {
+    throw new CoachBookOutputError();
+  }
+  const matches = projectRecommendationMatches(value.matches, 'runnable');
+  const pendingMatches = projectRecommendationMatches(value.pending_matches, 'pending');
+  const matchIds = matches.map((match) => String(match.tool_spec_id));
+  const pendingIds = pendingMatches.map((match) => String(match.tool_spec_id));
+  if (pendingIds.some((toolSpecId) => matchIds.includes(toolSpecId))) {
+    throw new CoachBookOutputError();
+  }
+  const selectedToolSpecId = value.selected_tool_spec_id === null
+    ? null
+    : methodId(value.selected_tool_spec_id);
+  const clarification = projectRecommendationClarification(value.clarification);
+  const clarificationChoices = clarification === null ? [] : records(clarification.choices);
+  const clarificationBindsMatches = clarification !== null
+    && clarificationChoices.length === matches.length
+    && clarificationChoices.every((choice, index) => (
+      choice.choice_id === matches[index]?.tool_spec_id
+      && choice.description === matches[index]?.use_when
+    ));
+  const firstMatchId = matches[0]?.tool_spec_id ?? null;
+  const outcomeIsValid = outcome === 'recommended'
+    ? matches.length > 0
+      && selectedToolSpecId === firstMatchId
+      && (confidence === 'high' || confidence === 'medium')
+      && value.clarification === null
+    : outcome === 'clarification_required'
+      ? matches.length > 0
+        && selectedToolSpecId === null
+        && confidence === 'low'
+        && clarificationBindsMatches
+      : outcome === 'no_runnable_match'
+        ? matches.length === 0
+          && pendingMatches.length > 0
+          && selectedToolSpecId === null
+          && value.confidence === null
+          && value.clarification === null
+        : matches.length === 0
+          && pendingMatches.length === 0
+          && selectedToolSpecId === null
+          && value.confidence === null
+          && value.clarification === null;
+  if (!outcomeIsValid || (outcome === 'clarification_required') !== (clarification !== null)) {
+    throw new CoachBookOutputError();
+  }
+  return {
+    ok: true,
+    schema_version: 'fbc.method-recommendations.v1',
+    ranker_version: FBC_METHOD_RANKER_VERSION,
+    outcome,
+    confidence,
+    context_used: {
+      method_stage: methodStage,
+      availability_scope: enumText(context.availability_scope, FBC_RECOMMENDATION_AVAILABILITY),
+      max_minutes: maxMinutes,
+      executor_kind: nullableEnumText(context.executor_kind, FBC_RECOMMENDATION_EXECUTORS),
+      effect_class: nullableEnumText(context.effect_class, FBC_RECOMMENDATION_EFFECTS),
+    },
+    matches,
+    selected_tool_spec_id: selectedToolSpecId,
+    clarification,
+    pending_matches: pendingMatches,
+    boundaries: projectRecommendationBoundaries(value.boundaries),
+  };
+}
+function projectError(source) {
+  const projected = { error: text(source.error) };
+  if (source.message !== undefined) projected.message = text(source.message);
+  if (source.billing_url !== undefined) {
+    const billingUrl = text(source.billing_url);
+    if (!billingUrl.startsWith('https://')) throw new CoachBookOutputError();
+    projected.billing_url = billingUrl;
+  }
+  return projected;
+}
+
+function projectConfirmation(source) {
+  if (source.error !== 'confirmation_required' || typeof source.confirm_token !== 'string') {
+    throw new CoachBookOutputError();
+  }
+  if (source.confirm_token.length < 1 || source.confirm_token.length > 4096 || !/^[A-Za-z0-9._-]+$/.test(source.confirm_token)) {
+    throw new CoachBookOutputError();
+  }
+  if (hasForbiddenOutput(source, true)) throw new CoachBookOutputError();
+  const projected = {
+    error: 'confirmation_required',
+    confirm_token: source.confirm_token,
+  };
+  for (const key of ['what_would_happen', 'message', 'note', 'why']) optionalText(projected, source, key);
+  if (source.expires_in_seconds !== undefined) projected.expires_in_seconds = integer(source.expires_in_seconds);
+  return projected;
+}
+
+export function projectCoachBookConnectorResult(kind, value) {
+  if (!['catalog', 'describe', 'recommendation', 'run'].includes(kind)) throw new CoachBookOutputError();
+  const source = record(value);
+  const data = record(source.data);
+  const status = integer(source.status);
+  const connectorOk = boolean(source.ok);
+  let projectedData;
+  if (status === 409 && data.error === 'confirmation_required') {
+    projectedData = projectConfirmation(data);
+  } else {
+    if (!(connectorOk && kind === 'recommendation')) assertPublicOutput(data);
+    if (!connectorOk) {
+      projectedData = projectError(data);
+    } else if (data.ok !== true) {
+      throw new CoachBookOutputError();
+    } else if (kind === 'catalog') {
+      projectedData = { ok: true, methods: records(data.methods).map(projectCatalogMethod) };
+    } else if (kind === 'describe') {
+      projectedData = { ok: true, method: projectDescribedMethod(data.method) };
+    } else if (kind === 'recommendation') {
+      projectedData = projectRecommendation(data);
+    } else {
+      const run = record(data.run);
+      projectedData = { ok: true, run: run.method ? projectGenericRun(run) : projectNicheRun(run) };
+    }
+    assertPublicOutput(projectedData);
+  }
+  return { ok: connectorOk, status, data: projectedData };
+}