@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/dist/src/booking-surface/dsh-plugin.js

@@ -7,7 +7,8 @@
  * the sole executor after the parent adapter validates the canonical action.
  */
 
-import { dshBookingActionSchemaForKind } from './canonical-schema.js'
+import Ajv2020 from 'ajv/dist/2020.js'
+import { canonicalBookingSurfaceSchema, dshBookingActionSchemaForKind } from './canonical-schema.js'
 
 export const name = 'gotry-embedded-booking'
 export const inject = ['tools']
@@ -50,6 +51,12 @@ function toolDefinition(toolName, capabilityId, actionKinds) {
     kind: { type: 'string', const: 'operation' },
     action: { oneOf: actionKinds.map(actionSchema) },
   })
+  const parameters = closedObject({
+    decision: {
+      oneOf: [operationDecision, questionDecision, explanationDecision, terminalDecision, errorDecision],
+    },
+  })
+  const validateArgs = new Ajv2020({ allErrors: true, strict: false }).compile(parameters)
   return Object.freeze({
     name: toolName,
     description: `Emit exactly one typed ${capabilityId} decision for the existing Booking workspace. This capability never books, pays, edits holder/guest data, or calls a supplier.`,
@@ -69,6 +76,15 @@ function toolDefinition(toolName, capabilityId, actionKinds) {
       },
     },
     async execute(args) {
+      // Native self-correction boundary: when the model's tool call violates
+      // the canonical decision schema, throw with the exact Ajv errors. The
+      // dsh agent loop feeds tool failures back to the model as tool results,
+      // so the model repairs its own shape inside the same turn — no schema
+      // knowledge duplicated outside this plugin.
+      if (!validateArgs(args)) {
+        const errors = (validateArgs.errors ?? []).map((e) => `${e.instancePath || '/'}: ${e.message}`).join('; ')
+        throw new Error(`decision_schema_violation: ${errors}`)
+      }
       const decision = args.decision
       return {
         accepted: true,

package/dist/src/booking-surface/error-codes.js

@@ -1,3 +1,4 @@
+/** Closed, non-sensitive error vocabulary for planner/runtime boundaries. */
 export const BOOKING_TYPED_ERROR_CODES = [
     'PAYLOAD_TOO_LARGE',
     'TASK_NOT_FOUND',
@@ -21,8 +22,77 @@ export const BOOKING_TYPED_ERROR_CODES = [
     'INVALID_INGRESS_BINDING',
     'BOOKING_SURFACE_SCHEMA_MISMATCH',
     'UNAUTHORIZED',
-    'NOT_FOUND'
+    'NOT_FOUND',
 ];
+/** Exact, closed reasons safe to expose in dispatch diagnostics. */
+export const BOOKING_DISPATCH_REJECTION_REASONS = [
+    'approval_expired',
+    'approval_mismatch',
+    'approval_not_awaiting',
+    'approval_not_presented',
+    'approval_replayed',
+    'approval_required',
+    'availability_attempt_mismatch',
+    'availability_attempt_unknown',
+    'availability_criteria_changed',
+    'availability_criteria_invalid',
+    'availability_criteria_mismatch',
+    'availability_criteria_required',
+    'availability_duplicate_offer_ref',
+    'availability_duplicate_offer_version_ref',
+    'availability_expected_revision_missing',
+    'availability_generation_mismatch',
+    'availability_hotel_limit_exceeded',
+    'availability_hotel_not_active',
+    'availability_hotel_unknown',
+    'availability_observation_required',
+    'availability_offer_limit_exceeded',
+    'availability_offers_count_mismatch',
+    'availability_offers_hotel_mismatch',
+    'availability_offers_observation_required',
+    'availability_offers_receipt_incoherent',
+    'availability_offers_unreported',
+    'availability_offers_workspace_mismatch',
+    'availability_query_not_reserved',
+    'availability_query_provenance_mismatch',
+    'availability_query_receipt_mismatch',
+    'availability_receipt_digest_mismatch',
+    'availability_receipt_incoherent',
+    'availability_stale_receipt',
+    'availability_terminal',
+    'booking_malformed_workspace',
+    'context_mismatch',
+    'invalid_task_id',
+    'receipt_action_mismatch',
+    'receipt_conflict',
+    'receipt_observation_action_mismatch',
+    'receipt_relaxation_unauthorized',
+    'receipt_required',
+    'receipt_source_action_mismatch',
+    'receipt_source_digest_mismatch',
+    'receipt_target_mismatch',
+    'receipt_verified_offer_expired',
+    'reanchor_turn_required',
+    'request_conflict',
+    'request_key_invalidated',
+    'revision_mismatch',
+    'revision_regression',
+    'task_not_found',
+    'task_terminal',
+    'turn_conflict',
+    'unexpected_receipt',
+    'unsafe_opaque_ref',
+    'workspace_mismatch',
+];
+export const BOOKING_DISPATCH_UNKNOWN_REASON = 'UNCLASSIFIED';
+const DISPATCH_REJECTION_REASON_SET = new Set(BOOKING_DISPATCH_REJECTION_REASONS);
+/** Returns a reason only when the complete boundary error is one known token. */
+export function extractBookingDispatchReason(error) {
+    const message = typeof error === 'string' ? error : error instanceof Error ? error.message : undefined;
+    return message !== undefined && DISPATCH_REJECTION_REASON_SET.has(message)
+        ? message
+        : BOOKING_DISPATCH_UNKNOWN_REASON;
+}
 const ALIASES = {
     payload_too_large: 'PAYLOAD_TOO_LARGE',
     task_not_found: 'TASK_NOT_FOUND',
@@ -46,7 +116,7 @@ const ALIASES = {
     invalid_ingress_binding: 'INVALID_INGRESS_BINDING',
     booking_surface_schema_mismatch: 'BOOKING_SURFACE_SCHEMA_MISMATCH',
     unauthorized: 'UNAUTHORIZED',
-    not_found: 'NOT_FOUND'
+    not_found: 'NOT_FOUND',
 };
 const SAFE_MESSAGES = {
     PAYLOAD_TOO_LARGE: 'Request payload exceeds the configured limit.',
@@ -71,24 +141,26 @@ const SAFE_MESSAGES = {
     INVALID_INGRESS_BINDING: 'The trusted ingress binding is invalid.',
     BOOKING_SURFACE_SCHEMA_MISMATCH: 'The booking surface schema is not supported.',
     UNAUTHORIZED: 'The request is not authorized.',
-    NOT_FOUND: 'The requested resource was not found.'
+    NOT_FOUND: 'The requested resource was not found.',
 };
 function rawCode(error) {
-    if (typeof error === 'string') return error.split(':', 1)[0];
-    if (error instanceof Error && error.message) return error.message.split(':', 1)[0];
+    if (typeof error === 'string')
+        return error.split(':', 1)[0];
+    if (error instanceof Error && error.message)
+        return error.message.split(':', 1)[0];
     return 'planner_failed';
 }
 export function normalizeBookingErrorCode(error) {
     const raw = rawCode(error);
     const normalized = raw.trim().toLowerCase();
     const aliased = ALIASES[normalized];
-    if (aliased) return aliased;
+    if (aliased)
+        return aliased;
     const uppercase = raw.trim().replace(/[^A-Za-z0-9]+/g, '_').toUpperCase();
-    return BOOKING_TYPED_ERROR_CODES.includes(uppercase) ? uppercase : 'PLANNER_FAILED';
+    return BOOKING_TYPED_ERROR_CODES.includes(uppercase)
+        ? uppercase
+        : 'PLANNER_FAILED';
 }
 export function safeBookingErrorMessage(code) {
     return SAFE_MESSAGES[BOOKING_TYPED_ERROR_CODES.includes(code) ? code : 'PLANNER_FAILED'];
 }
-
-
-//# sourceURL=ts/src/booking-surface/error-codes.ts

package/dist/src/booking-surface/index.js

@@ -6,6 +6,3 @@ export * from './server.js';
 export * from './startup.js';
 export * from './validation.js';
 export * from './availability-policy.js';
-
-
-//# sourceURL=ts/src/booking-surface/index.ts

package/dist/src/booking-surface/profile.js

@@ -4,65 +4,21 @@ export const EMBEDDED_BOOKING_CAPABILITY_IDS = [
     'find-room-offers',
     'compare-offers',
     'prepare-booking',
-    'observe-booking'
+    'observe-booking',
 ];
+/** Closed registry. No booking/payment/write capability exists in this profile. */
 export const embeddedBookingProfile = Object.freeze({
     id: 'embedded-booking',
     schemaVersion: 'booking.surface',
     capabilities: Object.freeze([
-        Object.freeze({
-            id: 'search-hotels',
-            effect: 'read',
-            actions: Object.freeze([
-                'search.patch',
-                'search.run'
-            ])
-        }),
-        Object.freeze({
-            id: 'refine-results',
-            effect: 'read',
-            actions: Object.freeze([
-                'results.view.patch',
-                'hotel.focus',
-                'hotel.select'
-            ])
-        }),
-        Object.freeze({
-            id: 'find-room-offers',
-            effect: 'read',
-            actions: Object.freeze([
-                'offers.query',
-                'offers.view.patch'
-            ])
-        }),
-        Object.freeze({
-            id: 'compare-offers',
-            effect: 'read',
-            actions: Object.freeze([
-                'offers.compare',
-                'offer.select'
-            ])
-        }),
-        Object.freeze({
-            id: 'prepare-booking',
-            effect: 'read',
-            actions: Object.freeze([
-                'offer.check',
-                'checkout.prepare'
-            ])
-        }),
-        Object.freeze({
-            id: 'observe-booking',
-            effect: 'read',
-            actions: Object.freeze([
-                'order.observe'
-            ])
-        })
-    ])
+        Object.freeze({ id: 'search-hotels', effect: 'read', actions: Object.freeze(['search.patch', 'search.run']) }),
+        Object.freeze({ id: 'refine-results', effect: 'read', actions: Object.freeze(['results.view.patch', 'hotel.focus', 'hotel.select']) }),
+        Object.freeze({ id: 'find-room-offers', effect: 'read', actions: Object.freeze(['offers.query', 'offers.view.patch']) }),
+        Object.freeze({ id: 'compare-offers', effect: 'read', actions: Object.freeze(['offers.compare', 'offer.select']) }),
+        Object.freeze({ id: 'prepare-booking', effect: 'read', actions: Object.freeze(['offer.check', 'checkout.prepare']) }),
+        Object.freeze({ id: 'observe-booking', effect: 'read', actions: Object.freeze(['order.observe']) }),
+    ]),
 });
 export function actionsForEmbeddedCapability(id) {
-    return embeddedBookingProfile.capabilities.find((capability)=>capability.id === id)?.actions ?? [];
+    return embeddedBookingProfile.capabilities.find((capability) => capability.id === id)?.actions ?? [];
 }
-
-
-//# sourceURL=ts/src/booking-surface/profile.ts

package/dist/src/booking-surface/recovery-chain.js

@@ -0,0 +1,367 @@
+/**
+ * Booking Copilot unavailable/changed 恢复链契约层（issue #142 非门控切片）。
+ *
+ * ⚠ 非运行时激活：纯函数契约层，不发起供应商调用、不读凭据、不接线 runtime seam——
+ * #142 合并 gate 中「四 surface 真实库存」与「真实 Checkout/QueryOrders 证据」仍是
+ * no-spend 门控项（等真实供应商/UAT）。本层只把恢复链的**结构化处置**固化为可离线
+ * 证明的契约：检测（识别分类）→ 恢复（受控重试）→ 用户沟通（显式披露）→ 审计（可对账）。
+ * 检测/恢复的合法性判定仍归 availability reducer（ADR-23 availability-policy.ts）所有；
+ * 本层是它的用户沟通与审计投影，不替代、不绕过。
+ *
+ * 词汇复用（不发明新通道）：
+ *   - 分类闭集复用 ActionReceipt.status 闭集（changed/unavailable/no_match/applied/partial/
+ *     stale/failed/needs_input/unsupported，contracts.ts）与 offer.availability/gap 观测形态；
+ *   - 每酒店有界恢复预算复用 availability-policy 的 MAX_OFFER_QUERIES_PER_HOTEL /
+ *     MAX_OFFER_CHECKS_PER_HOTEL（RECOVERY_REUSED_BUDGETS 冻结引用，防两处漂移）；
+ *   - 恢复轮次的模型调用语义对齐 planner 三次调用预算（dsh-planner attempt < 3）：
+ *     每个触发源最多 3 次计入预算的恢复轮，第 4 次结构性拒绝、必须降级；
+ *   - 审计事件命名沿用账本 booking.copilot.* 命名空间（runtime.ts 事件 kind 惯例）；
+ *     链校验形态对齐 booking-saga 的 sagaTraceViolations（开立→推进→终态吸收）。
+ *
+ * 红线（全部结构性编码）：
+ *   - changed/unavailable 必须显式分类——不静默当确认，也不静默丢弃；
+ *   - 不可确认证据只产生 inconclusive，不得宣称「市场无房」（与 availability reducer 同红线）；
+ *   - 恢复命中与用户原选择不同酒店/报价 = 替换，必须先出显式披露——静默换房换航结构性拒绝；
+ *   - 恢复耗尽只能显式降级并向用户披露，不得静默替换或假称确认；
+ *   - 版本位移（v1→v2）的解决必须携带非空变化说明——不静默换版；
+ *   - 每条审计事件带 receiptDigest 可回溯；resolved/degraded 为吸收终态，其后不得再有事件；
+ *   - 纯函数：每次推进返回新状态，原状态不可变。
+ */
+import { createHash } from 'node:crypto';
+import { MAX_OFFER_CHECKS_PER_HOTEL, MAX_OFFER_QUERIES_PER_HOTEL } from './availability-policy.js';
+export const RECOVERY_CHAIN_SCHEMA = 'booking_recovery_chain.v1';
+/** 每个触发源最多 3 次计入预算的恢复轮——对齐 planner 三次调用预算的语义（dsh-planner attempt < 3）。 */
+export const MAX_RECOVERY_MODEL_TURNS_PER_TRIGGER = 3;
+export const MAX_RECOVERY_BUDGET_NOTE = '3 counted model turns per trigger, aligned with the planner three-call attempt budget (dsh-planner); ' +
+    'per-hotel query/check budgets stay policy-owned (availability-policy MAX_OFFER_QUERIES_PER_HOTEL / MAX_OFFER_CHECKS_PER_HOTEL)';
+/** 恢复重试计入的既有预算（冻结引用 availability-policy 常量，防两处漂移）。 */
+export const RECOVERY_REUSED_BUDGETS = {
+    offerQueriesPerHotel: MAX_OFFER_QUERIES_PER_HOTEL,
+    offerChecksPerHotel: MAX_OFFER_CHECKS_PER_HOTEL,
+    modelTurnsPerTrigger: MAX_RECOVERY_MODEL_TURNS_PER_TRIGGER,
+};
+const RECOVERY_APPROACHES = new Set(['recheck_version', 'requery_same_hotel', 'alternative_candidate']);
+function isNonEmpty(value) { return typeof value === 'string' && value.trim().length > 0; }
+function requireBinding(key, value) {
+    if (!isNonEmpty(value))
+        throw new Error(`recovery_binding_missing:${key}`);
+    return value;
+}
+function stable(value) {
+    if (Array.isArray(value))
+        return value.map(stable);
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]));
+}
+/** 分类输入 receipt 的规范摘要（键排序后 sha256；证据链锚点）。 */
+export function receiptDigestOf(receipt) {
+    return createHash('sha256').update(JSON.stringify(stable(receipt))).digest('hex');
+}
+/**
+ * 检测（识别分类）：把一张 action receipt 分类到恢复链闭集。
+ *  - offer.availability 观测：完整分类 + 连贯性守卫（与 availability reducer 同一套不变式，
+ *    违例抛 availability_receipt_incoherent / availability_observation_required 同名错误）；
+ *  - offers.state 观测：query seam，generation 折叠归 policy 所有 → unrelated；
+ *  - gap 观测：不可确认 → inconclusive（不得宣称市场无房）；
+ *  - 其余观测上的 changed/unavailable/no_match 是错配凭证 → fail-closed 抛错；
+ *    其余状态（applied/partial/…）落在其他 seam → unrelated。
+ */
+export function classifyRecoveryTrigger(receipt) {
+    const observation = receipt.observation;
+    if (observation.kind === 'offers.state')
+        return { kind: 'unrelated', observationKind: observation.kind, reason: 'query seam: generation folding is availability-policy owned' };
+    if (observation.kind === 'gap')
+        return { kind: 'inconclusive', reason: `gap observation (${observation.code}): unconfirmable evidence — not_claim_market_empty` };
+    if (observation.kind !== 'offer.availability') {
+        if (['changed', 'unavailable', 'no_match'].includes(receipt.status))
+            throw new Error('availability_observation_required');
+        return { kind: 'unrelated', observationKind: observation.kind, reason: `receipt status ${receipt.status} rides a non-offer observation` };
+    }
+    const { offerRef, checkedOfferVersionRef, available, currentOfferVersionRef, verifiedOfferRef, changedFactRefs } = observation;
+    // 连贯性守卫（镜像 recordOfferCheckReceipt 的 incoherent 判定，fail-closed）
+    if (available && (receipt.resultContract.outcome === 'empty' || ['unavailable', 'no_match', 'failed', 'stale', 'unsupported'].includes(receipt.status)))
+        throw new Error('availability_receipt_incoherent');
+    if (!available && (verifiedOfferRef || currentOfferVersionRef))
+        throw new Error('availability_receipt_incoherent');
+    if (['unavailable', 'no_match'].includes(receipt.status) && receipt.resultContract.outcome !== 'empty')
+        throw new Error('availability_receipt_incoherent');
+    if (receipt.status === 'applied' && available && currentOfferVersionRef === checkedOfferVersionRef && verifiedOfferRef && changedFactRefs.length === 0) {
+        return { kind: 'confirmed', offerRef, offerVersionRef: checkedOfferVersionRef, verifiedOfferRef };
+    }
+    if (receipt.status === 'changed' && available && currentOfferVersionRef && currentOfferVersionRef !== checkedOfferVersionRef) {
+        return { kind: 'changed', offerRef, checkedOfferVersionRef, currentOfferVersionRef, changedFactRefs, reason: `supplier superseded ${checkedOfferVersionRef} with ${currentOfferVersionRef} (${changedFactRefs.join(',') || 'unspecified facts'})` };
+    }
+    if (['unavailable', 'no_match'].includes(receipt.status) && !available) {
+        return { kind: 'unavailable', offerRef, offerVersionRef: checkedOfferVersionRef, reason: `complete negative evidence (${receipt.status}, empty outcome)` };
+    }
+    return { kind: 'inconclusive', reason: `status ${receipt.status}: unconfirmable evidence — partial/stale/failed/gap cannot claim market empty (not_claim_market_empty)` };
+}
+function isSelection(value) {
+    const candidate = value;
+    return Boolean(candidate && isNonEmpty(candidate.hotelRef) && isNonEmpty(candidate.offerRef) && isNonEmpty(candidate.offerVersionRef));
+}
+function sameOfferTarget(a, b) {
+    return a.hotelRef === b.hotelRef && a.offerRef === b.offerRef;
+}
+/**
+ * 开立恢复链：检测出 changed/unavailable/inconclusive 触发后建链（fail-closed 绑定键 +
+ * 首条 recovery.detected 审计事件）。confirmed 无需恢复链、unrelated 无触发，均拒绝开链。
+ */
+export function openRecoveryChain(seed) {
+    const taskId = requireBinding('taskId', seed.taskId);
+    const contextRef = requireBinding('contextRef', seed.contextRef);
+    if (!isNonEmpty(seed.at))
+        throw new Error('recovery_binding_missing:at');
+    const originalSelection = seed.originalSelection;
+    if (!isSelection(originalSelection))
+        throw new Error('recovery_binding_missing:originalSelection');
+    const classification = classifyRecoveryTrigger(seed.receipt);
+    if (classification.kind === 'confirmed')
+        throw new Error('recovery_chain_not_required');
+    if (classification.kind === 'unrelated')
+        throw new Error('recovery_trigger_absent');
+    return {
+        schemaVersion: RECOVERY_CHAIN_SCHEMA,
+        taskId,
+        contextRef,
+        trigger: classification.kind,
+        triggerReason: classification.reason,
+        originalSelection: { ...originalSelection },
+        countedModelTurns: 0,
+        phase: 'detected',
+        substitutionDisclosed: false,
+        history: [{
+                at: seed.at,
+                kind: 'recovery.detected',
+                from: 'detected',
+                to: 'detected',
+                reason: classification.reason,
+                receiptDigest: receiptDigestOf(seed.receipt),
+                target: { ...originalSelection },
+            }],
+    };
+}
+/**
+ * 受控恢复推进：一步一凭证（重查/换版复查/替代候选的检查结果）。
+ *  - confirmed → resolved；目标与原选择不同酒店/报价且未先披露 = 静默替换，结构性拒绝；
+ *  - 其余分类 → 计入预算的恢复轮（countedModelTurns + 1，含确认轮）；超 3 次拒绝、必须降级；
+ *  - resolved/degraded 为吸收终态，其后不得再有 attempt。
+ */
+export function attemptRecoveryStep(state, attempt, at) {
+    if (state.phase === 'resolved' || state.phase === 'degraded')
+        throw new Error('recovery_chain_terminal');
+    if (!RECOVERY_APPROACHES.has(attempt.approach))
+        throw new Error('recovery_approach_invalid');
+    if (!isNonEmpty(at))
+        throw new Error('recovery_binding_missing:at');
+    if (!isSelection(attempt.target))
+        throw new Error('recovery_binding_missing:target');
+    const classification = classifyRecoveryTrigger(attempt.receipt);
+    if (classification.kind === 'unrelated')
+        throw new Error('recovery_trigger_absent');
+    if (classification.kind === 'confirmed') {
+        if (!sameOfferTarget(attempt.target, state.originalSelection) && !state.substitutionDisclosed) {
+            throw new Error('recovery_silent_swap_forbidden');
+        }
+        const versionShifted = attempt.target.offerVersionRef !== state.originalSelection.offerVersionRef;
+        return {
+            ...state,
+            phase: 'resolved',
+            resolvedTo: { ...attempt.target },
+            history: [...state.history, {
+                    at,
+                    kind: 'recovery.resolved',
+                    from: state.phase,
+                    to: 'resolved',
+                    reason: `confirmed via ${attempt.approach}${versionShifted ? ' on superseded version' : ''}`,
+                    receiptDigest: receiptDigestOf(attempt.receipt),
+                    target: { ...attempt.target },
+                    substitution: !sameOfferTarget(attempt.target, state.originalSelection),
+                }],
+        };
+    }
+    if (state.countedModelTurns + 1 > MAX_RECOVERY_MODEL_TURNS_PER_TRIGGER) {
+        throw new Error(`recovery_model_turn_budget_exhausted (${MAX_RECOVERY_MODEL_TURNS_PER_TRIGGER} counted turns per trigger; degrade explicitly instead of retrying)`);
+    }
+    const reason = classification.reason;
+    return {
+        ...state,
+        phase: 'recovering',
+        countedModelTurns: state.countedModelTurns + 1,
+        history: [...state.history, {
+                at,
+                kind: 'recovery.attempt',
+                from: state.phase,
+                to: 'recovering',
+                reason: `${attempt.approach}: ${classification.kind}: ${reason}`,
+                receiptDigest: receiptDigestOf(attempt.receipt),
+                target: { ...attempt.target },
+            }],
+    };
+}
+/**
+ * 替换披露：恢复将落在与用户原选择不同的酒店/报价上时，必须在确认前显式披露。
+ * 空披露文本拒绝——「显式说明变化，不静默换房换航」的结构化落点。
+ */
+export function discloseSubstitution(state, disclosure) {
+    if (state.phase === 'resolved' || state.phase === 'degraded')
+        throw new Error('recovery_chain_terminal');
+    if (!isNonEmpty(disclosure.disclosureText))
+        throw new Error('recovery_disclosure_required');
+    if (!isSelection(disclosure.target))
+        throw new Error('recovery_binding_missing:target');
+    if (!isNonEmpty(disclosure.at))
+        throw new Error('recovery_binding_missing:at');
+    return {
+        ...state,
+        substitutionDisclosed: true,
+        history: [...state.history, {
+                at: disclosure.at,
+                kind: 'recovery.disclosed',
+                from: state.phase,
+                to: state.phase,
+                reason: disclosure.disclosureText.slice(0, 500),
+                target: { ...disclosure.target },
+                substitution: true,
+            }],
+    };
+}
+/**
+ * 显式降级：恢复预算耗尽（或有界候选全负/不可确认）时，只能携非空用户披露降级结束——
+ * 静默降级拒绝；降级后链吸收，不得再推进。
+ */
+export function degradeRecoveryChain(state, degrade) {
+    if (state.phase === 'resolved' || state.phase === 'degraded')
+        throw new Error('recovery_chain_terminal');
+    if (!isNonEmpty(degrade.reason))
+        throw new Error('recovery_binding_missing:reason');
+    if (!isNonEmpty(degrade.disclosureText))
+        throw new Error('recovery_degrade_requires_disclosure');
+    if (!isNonEmpty(degrade.at))
+        throw new Error('recovery_binding_missing:at');
+    return {
+        ...state,
+        phase: 'degraded',
+        history: [...state.history,
+            {
+                at: degrade.at,
+                kind: 'recovery.disclosed',
+                from: state.phase,
+                to: state.phase,
+                reason: degrade.disclosureText.slice(0, 500),
+                substitution: false,
+            },
+            {
+                at: degrade.at,
+                kind: 'recovery.degraded',
+                from: state.phase,
+                to: 'degraded',
+                reason: degrade.reason.slice(0, 500),
+            },
+        ],
+    };
+}
+/** 用户沟通投影：结构化披露（substitution/versionShifted/确定性说明文本）。 */
+export function buildUserDisclosure(state) {
+    if (state.phase === 'resolved' && state.resolvedTo) {
+        const substitution = !sameOfferTarget(state.resolvedTo, state.originalSelection);
+        const versionShifted = state.resolvedTo.offerVersionRef !== state.originalSelection.offerVersionRef;
+        if (substitution) {
+            return {
+                substitution,
+                versionShifted,
+                text: `Availability changed: original ${state.originalSelection.hotelRef}/${state.originalSelection.offerRef} could not be confirmed (${state.triggerReason}). The substitute ${state.resolvedTo.hotelRef}/${state.resolvedTo.offerRef} is disclosed explicitly for your approval — no silent swap.`,
+            };
+        }
+        if (versionShifted) {
+            return {
+                substitution,
+                versionShifted,
+                text: `Availability changed: ${state.originalSelection.offerRef} moved from version ${state.originalSelection.offerVersionRef} to ${state.resolvedTo.offerVersionRef} at the supplier; re-confirmed on the new version.`,
+            };
+        }
+        return { substitution, versionShifted, text: 'Original selection confirmed after recovery.' };
+    }
+    if (state.phase === 'degraded') {
+        return { substitution: false, versionShifted: false, text: `Recovery exhausted for ${state.originalSelection.hotelRef}/${state.originalSelection.offerRef}: ${state.triggerReason}. Task ended explicitly with no substitute booked.` };
+    }
+    return { substitution: false, versionShifted: false, text: `Recovery in progress: supplier reported ${state.trigger} — ${state.triggerReason}` };
+}
+/**
+ * 审计链校验（形态对齐 booking-saga 的 sagaTraceViolations；空数组 = 链合法）：
+ *  - 必须以恰好一条 recovery.detected 开链；
+ *  - resolved/degraded 至多各一次且为吸收终态——其后不得有任何事件；
+ *  - attempt/disclosed 只许出现在终态前；
+ *  - resolved 目标与 detected 原目标不同酒店/报价时，之前必须有 substitution=true 的披露；
+ *  - degraded 之前必须有披露事件（静默降级违例）。
+ */
+export function recoveryAuditViolations(events) {
+    const violations = [];
+    let opened = false;
+    let detectedTarget;
+    let terminal;
+    let disclosedSubstitution = false;
+    let disclosedSeen = false;
+    events.forEach((event, index) => {
+        const at = `#${index} ${event.kind}`;
+        if (terminal) {
+            violations.push(`${at}: 终态(${terminal})后出现事件(吸收态)`);
+            return;
+        }
+        switch (event.kind) {
+            case 'recovery.detected': {
+                if (opened) {
+                    violations.push(`${at}: 重复开链`);
+                    return;
+                }
+                opened = true;
+                detectedTarget = event.target;
+                return;
+            }
+            case 'recovery.attempt': {
+                if (!opened) {
+                    violations.push(`${at}: 开链前的 attempt`);
+                    return;
+                }
+                return;
+            }
+            case 'recovery.disclosed': {
+                if (!opened) {
+                    violations.push(`${at}: 开链前的披露`);
+                    return;
+                }
+                disclosedSeen = true;
+                if (event.substitution)
+                    disclosedSubstitution = true;
+                return;
+            }
+            case 'recovery.resolved': {
+                if (!opened) {
+                    violations.push(`${at}: 开链前的 resolved`);
+                    return;
+                }
+                if (detectedTarget && event.target && !sameOfferTarget(event.target, detectedTarget) && !disclosedSubstitution) {
+                    violations.push(`${at}: 静默替换(resolved 目标偏离原选择且无披露)`);
+                }
+                terminal = 'resolved';
+                return;
+            }
+            case 'recovery.degraded': {
+                if (!opened) {
+                    violations.push(`${at}: 开链前的 degraded`);
+                    return;
+                }
+                if (!disclosedSeen)
+                    violations.push(`${at}: 静默降级(degraded 前无披露)`);
+                terminal = 'degraded';
+                return;
+            }
+            default:
+                violations.push(`${at}: 未知事件 kind`);
+        }
+    });
+    if (!opened)
+        violations.push('链未以 recovery.detected 开立');
+    return violations;
+}