@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.27

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

@@ -0,0 +1,43 @@
+export const BOOKING_INTENT_SCHEMA_VERSION = 'booking.intent.v1';
+export const BOOKING_INTENT_TARGETS = [
+    'search.results',
+    'results.refined',
+    'hotel.focused',
+    'hotel.selected',
+    'offers.loaded',
+    'offers.refined',
+    'offers.compared',
+    'offer.selected',
+    'offer.verified',
+    'checkout.prepared',
+    'order.observed',
+];
+/** Ordered read path; an intent target may not be overshot by its action. */
+export const BOOKING_INTENT_ACTION_ORDINAL = {
+    'search.patch': 0,
+    'search.run': 1,
+    'results.view.patch': 2,
+    'hotel.focus': 3,
+    'hotel.select': 4,
+    'offers.query': 5,
+    'offers.view.patch': 6,
+    'offers.compare': 7,
+    'offer.select': 8,
+    'offer.check': 9,
+    'checkout.prepare': 10,
+    'order.observe': 11,
+};
+export const BOOKING_INTENT_TARGET_ACTION = {
+    'search.results': 'search.run',
+    'results.refined': 'results.view.patch',
+    'hotel.focused': 'hotel.focus',
+    'hotel.selected': 'hotel.select',
+    'offers.loaded': 'offers.query',
+    'offers.refined': 'offers.view.patch',
+    'offers.compared': 'offers.compare',
+    'offer.selected': 'offer.select',
+    'offer.verified': 'offer.check',
+    'checkout.prepared': 'checkout.prepare',
+    'order.observed': 'order.observe',
+};
+export const BOOKING_INTENT_TARGET_ORDINAL = Object.fromEntries(Object.entries(BOOKING_INTENT_TARGET_ACTION).map(([target, action]) => [target, BOOKING_INTENT_ACTION_ORDINAL[action]]));

package/dist/src/booking-surface/cancel-refund-commission.js

@@ -0,0 +1,379 @@
+/**
+ * Cancel/refund independent outcomes + explicit commission disclosure
+ * (issue #233, M5-4 pre-entry contract layer; parent #136).
+ *
+ * Contract only: pure types + pure functions. Zero network, zero subprocess,
+ * zero ledger/schema change, zero supplier call surface — the write path stays
+ * sealed behind #136 M5 Entry; receipt/outbox/dispatch authority belongs to
+ * #231/#232 and is deliberately NOT modeled here.
+ *
+ * Frozen sources of truth:
+ * - docs/design/write-gate-production-design.md §3 (SupplierOutcome closed set),
+ *   §4 (commission_disclosure digest enters the request fingerprint; a
+ *   disclosure change invalidates the old receipt), §7 (outcome × user copy
+ *   matrix), §8 (cancellation / refund order / wallet refund are separate
+ *   outcomes; cancel.serviceFee is not the customer refund amount; pending →
+ *   compensated cancels only the local suggestion and never means "refunded"),
+ *   §10 (commission/sponsorship disclosure before confirmation; unknown must
+ *   not default to none), §11 (redaction);
+ * - docs/design/fact-writegate-seam.md §2.3 (wording authority per claim type:
+ *   "cancellation requested" only; refunded only from authoritative evidence).
+ *
+ * Default-off: nothing in this module is wired into any runtime path. The
+ * focused suite ts/scripts/issue-233-cancel-refund-commission-tests.ts pins
+ * the contract (run-all §62).
+ */
+import { createHash } from 'node:crypto';
+// ---- 1. Independent outcome closed sets -----------------------------------------
+export const CANCELLATION_OUTCOME_SCHEMA = 'gotry.cancellation_outcome.v1';
+/** Cancel REQUEST outcome. There is deliberately no "cancelled" terminal here:
+ * only an explicit supplier cancellation receipt (supplierCancellationConfirmed)
+ * upgrades a submission into a confirmed cancellation. */
+export const CANCELLATION_STATUSES = ['not_requested', 'cancel_submitted', 'cancel_failed', 'cancel_unknown'];
+export const REFUND_OUTCOME_SCHEMA = 'gotry.refund_outcome.v1';
+/** Money-arrival outcome. Independent from the cancellation outcome by design:
+ * the two objects are never merged into a single success state. */
+export const REFUND_STATUSES = ['not_applicable', 'refund_pending', 'refund_failed', 'refunded', 'refund_unknown'];
+/** ADR-17 ledger alphabet, mirrored read-only for copy consistency checks.
+ * This module does not touch the ledger (that is #231's surface). */
+export const LOCAL_LEDGER_STATUSES = ['pending', 'confirmed', 'compensated'];
+/** Refund amount may only be concluded from authoritative refund/wallet records. */
+export const REFUND_AUTHORITY_SOURCES = ['supplier_refund_record', 'wallet_refund_record'];
+/** The supplier cancellation fee is a separate disclosure; it is never a refund amount. */
+export const SERVICE_FEE_SOURCE = 'cancel_return_service_fee';
+/** supplierReferenceNo is used only as a supplier-returned value — never decoded
+ * or guessed from customerReferenceNo (write-gate design §2/§6). The only way to
+ * construct one is `supplierReferenceNoFromReturn` with an explicit return source. */
+export const SUPPLIER_REFERENCE_RETURN_SOURCES = ['supplier_cancel_return', 'supplier_query_return', 'supplier_refund_return'];
+export function supplierReferenceNoFromReturn(value, source) {
+    const trimmed = typeof value === 'string' ? value.trim() : '';
+    if (trimmed === '')
+        return { ok: false, reason: 'supplier_reference_empty' };
+    if (!SUPPLIER_REFERENCE_RETURN_SOURCES.includes(source))
+        return { ok: false, reason: 'supplier_reference_not_returned_value' };
+    return { ok: true, value: Object.freeze({ value: trimmed, source }) };
+}
+const AMOUNT_RE = /^\d+(\.\d+)?$/;
+function nonEmpty(v) {
+    return typeof v === 'string' && v.trim() !== '';
+}
+function validAmount(v) {
+    return nonEmpty(v) && AMOUNT_RE.test(v.trim());
+}
+export function cancellationOutcome(input) {
+    if (input?.schema !== CANCELLATION_OUTCOME_SCHEMA)
+        return { ok: false, reason: 'schema_mismatch' };
+    if (!CANCELLATION_STATUSES.includes(input.status))
+        return { ok: false, reason: 'unknown_cancellation_status' };
+    if (!nonEmpty(input.customerReferenceNo))
+        return { ok: false, reason: 'customer_reference_required' };
+    if (input.supplierReferenceNo !== undefined) {
+        const r = input.supplierReferenceNo;
+        if (!nonEmpty(r?.value) || !SUPPLIER_REFERENCE_RETURN_SOURCES.includes(r?.source)) {
+            return { ok: false, reason: 'supplier_reference_not_returned_value' };
+        }
+    }
+    if (input.supplierCancellationConfirmed !== undefined && !nonEmpty(input.supplierCancellationConfirmed?.digest)) {
+        return { ok: false, reason: 'supplier_cancellation_receipt_digest_required' };
+    }
+    if (!nonEmpty(input.observedAt))
+        return { ok: false, reason: 'observed_at_required' };
+    return { ok: true, value: Object.freeze({ ...input }) };
+}
+export function refundOutcome(input) {
+    if (input?.schema !== REFUND_OUTCOME_SCHEMA)
+        return { ok: false, reason: 'schema_mismatch' };
+    if (!REFUND_STATUSES.includes(input.status))
+        return { ok: false, reason: 'unknown_refund_status' };
+    if (!nonEmpty(input.observedAt))
+        return { ok: false, reason: 'observed_at_required' };
+    if (input.customerRefund !== undefined) {
+        const cr = input.customerRefund;
+        if (!validAmount(cr?.amount) || !nonEmpty(cr?.currency))
+            return { ok: false, reason: 'refund_amount_invalid' };
+        if (cr.source === SERVICE_FEE_SOURCE)
+            return { ok: false, reason: 'service_fee_used_as_refund_amount' };
+    }
+    if (input.status === 'refunded') {
+        const authoritative = input.customerRefund !== undefined &&
+            REFUND_AUTHORITY_SOURCES.includes(input.customerRefund.source) &&
+            input.evidence !== undefined &&
+            REFUND_AUTHORITY_SOURCES.includes(input.evidence?.kind) &&
+            nonEmpty(input.evidence?.digest);
+        if (!authoritative)
+            return { ok: false, reason: 'refund_claimed_without_evidence' };
+    }
+    if (input.supplierServiceFee !== undefined && (!validAmount(input.supplierServiceFee?.amount) || !nonEmpty(input.supplierServiceFee?.currency))) {
+        return { ok: false, reason: 'service_fee_invalid' };
+    }
+    return { ok: true, value: Object.freeze({ ...input }) };
+}
+export function aftercareFacts(cancel, refund) {
+    return Object.freeze({
+        cancellationRequested: cancel.status === 'cancel_submitted',
+        orderCancelled: cancel.supplierCancellationConfirmed !== undefined
+            ? true
+            : cancel.status === 'cancel_failed'
+                ? false
+                : 'unknown',
+        moneyReturned: refund.status === 'refunded'
+            ? true
+            : refund.status === 'refund_failed' || refund.status === 'not_applicable'
+                ? false
+                : 'unknown',
+        refundStatus: refund.status,
+    });
+}
+// ---- 3. Commission / sponsorship disclosure --------------------------------------
+export const COMMISSION_DISCLOSURE_SCHEMA = 'gotry.commission_disclosure.v1';
+export const COMMISSION_BENEFIT_KINDS = ['commission', 'rebate', 'sponsorship', 'preferred_placement'];
+export const COMMISSION_CERTAINTIES = ['known_benefit', 'known_none', 'unknown'];
+export const COMMISSION_SOURCES = ['supplier_field', 'contract_rule'];
+export const COMMISSION_AMOUNT_BASES = ['fixed', 'percent_of_total', 'per_night'];
+const PAID_BY = ['supplier', 'distributor', 'customer'];
+export const COMMISSION_VIOLATION_CODES = [
+    'commission_undisclosed',
+    'commission_none_without_source',
+    'commission_benefit_incomplete',
+    'commission_amount_basis_inconsistent',
+    'disclosure_digest_mismatch',
+];
+const POSITIVE_NUMBER_RE = /^(0*[1-9][0-9]*(\.[0-9]+)?|0*\.[0-9]*[1-9][0-9]*)$/;
+export function validateCommissionDisclosure(v) {
+    if (typeof v !== 'object' || v === null || v.schema !== COMMISSION_DISCLOSURE_SCHEMA) {
+        return { ok: false, violations: ['commission_undisclosed'] };
+    }
+    const d = v;
+    if (!COMMISSION_CERTAINTIES.includes(d.certainty))
+        return { ok: false, violations: ['commission_undisclosed'] };
+    if (!COMMISSION_SOURCES.includes(d.source))
+        return { ok: false, violations: ['commission_benefit_incomplete'] };
+    const violations = [];
+    if (!Array.isArray(d.benefits))
+        return { ok: false, violations: ['commission_benefit_incomplete'] };
+    if (d.certainty === 'known_none' || d.certainty === 'unknown') {
+        if (d.benefits.length > 0)
+            violations.push('commission_benefit_incomplete');
+        if (d.certainty === 'known_none' && d.source !== 'contract_rule')
+            violations.push('commission_none_without_source');
+    }
+    if (d.certainty === 'known_benefit') {
+        if (d.benefits.length === 0)
+            violations.push('commission_benefit_incomplete');
+    }
+    for (const b of d.benefits) {
+        if (!COMMISSION_BENEFIT_KINDS.includes(b?.kind) ||
+            !PAID_BY.includes(b?.paidBy) ||
+            !nonEmpty(b?.paidTo)) {
+            violations.push('commission_benefit_incomplete');
+            continue;
+        }
+        const basis = b.basis;
+        if (!COMMISSION_AMOUNT_BASES.includes(basis?.type)) {
+            violations.push('commission_amount_basis_inconsistent');
+            continue;
+        }
+        if (basis.type === 'percent_of_total') {
+            const okPercent = validAmount(basis.percent) && POSITIVE_NUMBER_RE.test(basis.percent.trim()) && basis.amount === undefined;
+            if (!okPercent)
+                violations.push('commission_amount_basis_inconsistent');
+        }
+        else {
+            const okFixed = validAmount(basis.amount) && nonEmpty(basis.currency) && basis.percent === undefined;
+            if (!okFixed)
+                violations.push('commission_amount_basis_inconsistent');
+        }
+    }
+    return violations.length === 0 ? { ok: true } : { ok: false, violations };
+}
+/** Canonical JSON (sorted keys, stable) — local to keep this module dependency-free. */
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const obj = value;
+    return `{${Object.keys(obj)
+        .sort()
+        .map(key => `${JSON.stringify(key)}:${canonicalJson(obj[key])}`)
+        .join(',')}}`;
+}
+export function computeDisclosureDigest(disclosure) {
+    return createHash('sha256')
+        .update(canonicalJson({ schema: disclosure.schema, certainty: disclosure.certainty, benefits: disclosure.benefits, source: disclosure.source }))
+        .digest('hex');
+}
+/** Confirmation boundary: no disclosure object at all is a hard reject — a card
+ * may not be confirmed without explicit commission disclosure (§10). */
+export function disclosureForConfirmation(v) {
+    const checked = validateCommissionDisclosure(v);
+    if (!checked.ok)
+        return { ok: false, violation: checked.violations[0] };
+    const disclosure = v;
+    return { ok: true, disclosure, digest: computeDisclosureDigest(disclosure) };
+}
+/** The request-fingerprint field carrying the disclosure digest (design §4). */
+export const COMMISSION_DISCLOSURE_FINGERPRINT_FIELD = 'commission_disclosure';
+export function bindDisclosureToFingerprint(fingerprint, disclosure) {
+    const digest = computeDisclosureDigest(disclosure);
+    const existing = fingerprint[COMMISSION_DISCLOSURE_FINGERPRINT_FIELD];
+    if (typeof existing === 'string' && existing !== digest) {
+        // Disclosure caliber changed after confirmation: the old receipt is invalid;
+        // re-confirmation against the new disclosure is required.
+        return { ok: false, violation: 'disclosure_digest_mismatch' };
+    }
+    return { ok: true, fingerprint: { ...fingerprint, [COMMISSION_DISCLOSURE_FINGERPRINT_FIELD]: digest }, digest };
+}
+/** Arrival claims. If copy states these while the outcome is not an evidenced
+ * `refunded`, the wording contradicts the ledger-side tokens. */
+const ARRIVAL_TOKENS = {
+    en: ['refunded', 'refund received', 'refund has arrived'],
+    'zh-CN': ['已退款', '退款已到账', '退款到账'],
+};
+const CANCEL_DONE_TOKENS = {
+    en: ['cancelled'],
+    'zh-CN': ['已取消'],
+};
+const BENEFIT_MARKERS = {
+    en: ['commission', 'rebate', 'sponsorship', 'preferred placement'],
+    'zh-CN': ['佣金', '返利', '赞助', '优先位'],
+};
+/** A definite benefit claim (only allowed when certainty='known_benefit'). */
+const DEFINITE_BENEFIT_TOKENS = {
+    en: ['paid by', '% of total'],
+    'zh-CN': ['支付给', '%'],
+};
+const ZH_BENEFIT_KIND = {
+    commission: '佣金',
+    rebate: '返利',
+    sponsorship: '赞助',
+    preferred_placement: '优先位',
+};
+export const COPY_VIOLATION_CODES = [
+    'copy_claimed_cancelled_without_supplier_evidence',
+    'copy_claimed_refund_arrival_without_authority',
+    'copy_refund_wording_while_pending_or_unknown',
+    'copy_refund_wording_on_local_compensation_only',
+    'commission_disclosure_missing_from_summary',
+    'commission_status_contradicts_summary',
+];
+export function localLedgerCopy(status, locale) {
+    if (locale === 'zh-CN') {
+        if (status === 'pending')
+            return '本地建议待确认；未下单。';
+        if (status === 'confirmed')
+            return '本地已确认授权；供应商结果待回执。';
+        return '本地账面已补偿；这只是账务动作，退款状态以退款结果为准。';
+    }
+    if (status === 'pending')
+        return 'Local suggestion pending confirmation; no order placed.';
+    if (status === 'confirmed')
+        return 'Confirmed and authorized locally; supplier outcome pending receipt.';
+    return 'Compensated locally; this is a ledger action only — refund state is tracked by the refund outcome.';
+}
+function basisLabel(basis, locale) {
+    if (basis.type === 'percent_of_total')
+        return locale === 'zh-CN' ? `总价 ${basis.percent}%` : `${basis.percent}% of total`;
+    if (basis.type === 'per_night')
+        return locale === 'zh-CN' ? `每晚 ${basis.amount} ${basis.currency}` : `${basis.amount} ${basis.currency} per night`;
+    return locale === 'zh-CN' ? `固定 ${basis.amount} ${basis.currency}` : `${basis.amount} ${basis.currency} fixed`;
+}
+function disclosureLines(disclosure, locale) {
+    const zh = locale === 'zh-CN';
+    if (disclosure.certainty === 'unknown')
+        return [zh ? '佣金/返利/赞助披露：未知（不默认没有）。' : 'Commission/sponsorship disclosure: unknown (not assumed none).'];
+    if (disclosure.certainty === 'known_none')
+        return [zh ? '佣金/返利/赞助披露：无（依据合同规则记录）。' : 'Commission/sponsorship disclosure: none (source: contract rule).'];
+    return disclosure.benefits.map(b => zh
+        ? `${ZH_BENEFIT_KIND[b.kind]}：由 ${b.paidBy} 支付给 ${b.paidTo}，口径 ${basisLabel(b.basis, locale)}。`
+        : `${b.kind.replaceAll('_', ' ')}: paid by ${b.paidBy} to ${b.paidTo} — ${basisLabel(b.basis, locale)}.`);
+}
+export function renderAftercareCopy(cancel, refund, ledgerStatus, disclosure, locale) {
+    const zh = locale === 'zh-CN';
+    const lines = [localLedgerCopy(ledgerStatus, locale)];
+    if (cancel.supplierCancellationConfirmed !== undefined) {
+        lines.push(zh ? '供应商回执确认已取消（证据摘要已留存）。' : 'Cancelled per supplier receipt (evidence digest on file).');
+    }
+    else if (cancel.status === 'not_requested') {
+        lines.push(zh ? '未申请取消。' : 'No cancellation requested.');
+    }
+    else if (cancel.status === 'cancel_submitted') {
+        lines.push(zh ? '已提交取消申请；等待供应商确认。' : 'Cancellation requested/submitted; awaiting supplier confirmation.');
+    }
+    else if (cancel.status === 'cancel_failed') {
+        lines.push(zh ? '取消失败。' : 'Cancellation failed.');
+    }
+    else {
+        lines.push(zh ? '取消结果未知；对账中。' : 'Cancellation outcome unknown; reconciling.');
+    }
+    if (refund.status === 'not_applicable') {
+        lines.push(zh ? '不涉及退款。' : 'No refund involved.');
+    }
+    else if (refund.status === 'refund_pending') {
+        lines.push(zh ? '退款处理中；尚未到账。' : 'Refund pending; not yet arrived.');
+    }
+    else if (refund.status === 'refund_failed') {
+        lines.push(zh ? '退款失败；未到账。' : 'Refund failed; the refund did not arrive.');
+    }
+    else if (refund.status === 'refund_unknown') {
+        lines.push(zh ? '退款结果未知；对账中。' : 'Refund outcome unknown; reconciling.');
+    }
+    else {
+        lines.push(zh
+            ? `退款已到账：${refund.customerRefund?.amount} ${refund.customerRefund?.currency}（依据 ${refund.evidence?.kind}）。`
+            : `Refund received: ${refund.customerRefund?.amount} ${refund.customerRefund?.currency} per ${refund.evidence?.kind}.`);
+    }
+    if (refund.supplierServiceFee !== undefined) {
+        lines.push(zh
+            ? `供应商取消手续费（供应商收取，不是退款金额）：${refund.supplierServiceFee.amount} ${refund.supplierServiceFee.currency}。`
+            : `Supplier cancellation service fee (charged by supplier, not the refund): ${refund.supplierServiceFee.amount} ${refund.supplierServiceFee.currency}.`);
+    }
+    if (disclosure !== undefined)
+        lines.push(...disclosureLines(disclosure, locale));
+    return lines.join('\n');
+}
+/** Mechanical token gate: copy shown to the user must not claim states the
+ * outcome objects (and the ledger mirror) do not carry, and must not hide the
+ * commission disclosure behind a total price. This is a regression anchor for
+ * generated/hand-written/LLM copy — not an NLU claim. */
+export function copyTokenViolations(text, state) {
+    const violations = [];
+    const zh = state.locale === 'zh-CN';
+    const hay = zh ? text : text.toLowerCase();
+    const has = (tokens) => tokens.some(t => hay.includes(t));
+    const arrival = ARRIVAL_TOKENS[state.locale];
+    const cancelDone = CANCEL_DONE_TOKENS[state.locale];
+    if (state.cancel.supplierCancellationConfirmed === undefined && has(cancelDone)) {
+        violations.push('copy_claimed_cancelled_without_supplier_evidence');
+    }
+    if (state.refund.status !== 'refunded' && has(arrival)) {
+        violations.push('copy_claimed_refund_arrival_without_authority');
+        if (state.refund.status === 'refund_pending' || state.refund.status === 'refund_unknown') {
+            violations.push('copy_refund_wording_while_pending_or_unknown');
+        }
+    }
+    if (state.ledgerStatus === 'compensated' && state.refund.status === 'not_applicable' && has(arrival)) {
+        violations.push('copy_refund_wording_on_local_compensation_only');
+    }
+    const d = state.disclosure;
+    if (d !== undefined) {
+        if (d.certainty === 'known_benefit') {
+            if (!has(BENEFIT_MARKERS[state.locale]))
+                violations.push('commission_disclosure_missing_from_summary');
+        }
+        else {
+            const required = d.certainty === 'unknown'
+                ? zh
+                    ? hay.includes('佣金') && hay.includes('未知')
+                    : hay.includes('commission') && hay.includes('unknown')
+                : zh
+                    ? hay.includes('无（依据')
+                    : hay.includes('none');
+            if (!required)
+                violations.push('commission_disclosure_missing_from_summary');
+            if (has(DEFINITE_BENEFIT_TOKENS[state.locale]))
+                violations.push('commission_status_contradicts_summary');
+        }
+    }
+    return violations;
+}

package/dist/src/booking-surface/canonical-schema.js

@@ -0,0 +1,116 @@
+/**
+ * Runtime projection of the canonical booking.surface JSON Schema.
+ *
+ * dsh tools need self-contained JSON Schemas, while the canonical document is
+ * organized with local $refs. This helper derives each action branch directly
+ * from those canonical bytes and recursively inlines local references. No
+ * model-facing action schema is maintained by hand.
+ */
+
+import { readFileSync } from 'node:fs'
+
+const schemaUrl = new URL('../../../schemas/booking.surface.schema.json', import.meta.url)
+export const canonicalBookingSurfaceSchema = JSON.parse(readFileSync(schemaUrl, 'utf8'))
+const intentSchemaUrl = new URL('../../../schemas/booking.intent.schema.json', import.meta.url)
+export const canonicalBookingIntentSchema = JSON.parse(readFileSync(intentSchemaUrl, 'utf8'))
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value))
+}
+
+function definitionFromRef(ref, schema) {
+  const prefix = '#/$defs/'
+  if (typeof ref !== 'string' || !ref.startsWith(prefix)) {
+    throw new Error(`booking_schema_external_ref_forbidden:${String(ref)}`)
+  }
+  const name = ref.slice(prefix.length)
+  const definition = schema.$defs?.[name]
+  if (!definition) throw new Error(`booking_schema_missing_definition:${name}`)
+  return definition
+}
+
+function inlineLocalRefs(value, schema, stack = []) {
+  if (Array.isArray(value)) return value.map((item) => inlineLocalRefs(item, schema, stack))
+  if (typeof value !== 'object' || value === null) return value
+  if (typeof value.$ref === 'string') {
+    if (stack.includes(value.$ref)) throw new Error(`booking_schema_recursive_ref:${value.$ref}`)
+    const { $ref, ...siblings } = value
+    return {
+      ...inlineLocalRefs(definitionFromRef($ref, schema), schema, [...stack, $ref]),
+      ...inlineLocalRefs(siblings, schema, stack),
+    }
+  }
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, inlineLocalRefs(item, schema, stack)]))
+}
+
+function canonicalActionSchemaForKind(kind, schema, definitionName) {
+  const action = schema.$defs?.[definitionName]
+  if (!action) throw new Error('booking_schema_action_union_missing')
+  if (Array.isArray(action.allOf)) {
+    const branch = action.allOf.find((candidate) => candidate?.if?.properties?.kind?.const === kind)
+    const input = branch?.then?.properties?.input
+    if (!input) throw new Error(`booking_schema_action_kind_missing:${kind}`)
+    return clone(inlineLocalRefs({
+      type: action.type,
+      required: action.required,
+      properties: { ...action.properties, kind: { type: 'string', const: kind }, input },
+      additionalProperties: action.additionalProperties,
+    }, schema))
+  }
+  if (!Array.isArray(action.oneOf)) throw new Error('booking_schema_action_union_missing')
+  const branch = action.oneOf.find((candidate) => candidate?.allOf?.some((part) => part?.properties?.kind?.const === kind))
+  const base = schema.$defs?.ActionBase
+  const input = branch?.allOf?.find((part) => part?.properties?.input)?.properties?.input
+  if (!base || !input) throw new Error(`booking_schema_action_kind_missing:${kind}`)
+  return clone(inlineLocalRefs({
+    ...base,
+    properties: { ...base.properties, kind: { type: 'string', const: kind }, input },
+  }, schema))
+}
+
+export function canonicalBookingActionSchemaForKind(kind) {
+  return canonicalActionSchemaForKind(kind, canonicalBookingSurfaceSchema, 'Action')
+}
+
+const DSH_JSON_SCHEMA_KEYS = new Set([
+  'type', 'oneOf', 'properties', 'required', 'additionalProperties', 'items',
+  'enum', 'const', 'description', 'title', 'default', 'examples',
+])
+
+function projectDshSchema(value) {
+  if (Array.isArray(value)) return value.map(projectDshSchema)
+  if (typeof value !== 'object' || value === null) return value
+  return Object.fromEntries(Object.entries(value)
+    .filter(([key]) => DSH_JSON_SCHEMA_KEYS.has(key))
+    .map(([key, item]) => {
+      if (key === 'properties') {
+        return [key, Object.fromEntries(Object.entries(item).map(([name, property]) => [name, projectDshSchema(property)]))]
+      }
+      return [key, projectDshSchema(item)]
+    }))
+}
+
+/**
+ * dsh-tools intentionally supports a smaller enforced JSON-Schema vocabulary.
+ * Keep the canonical shape/type/enum/closure guarantees at the model seam;
+ * the full canonical AJV validator remains the runtime authority for numeric,
+ * pattern, size and uniqueness constraints before an operation can be issued.
+ */
+export function dshBookingActionSchemaForKind(kind) {
+  return projectDshSchema(canonicalBookingActionSchemaForKind(kind))
+}
+
+/** Self-contained intent schema with its sole public-contract ref inlined. */
+export function canonicalBookingIntentProjectionSchema() {
+  const intent = clone(canonicalBookingIntentSchema)
+  intent.properties.offerCriteria = clone(inlineLocalRefs(
+    canonicalBookingSurfaceSchema.$defs.OfferCriteria,
+    canonicalBookingSurfaceSchema,
+  ))
+  return intent
+}
+
+/** Provider-advertised subset; execute-time validation uses the full form. */
+export function dshBookingIntentProjectionSchema() {
+  return projectDshSchema(canonicalBookingIntentProjectionSchema())
+}

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

@@ -0,0 +1,75 @@
+/**
+ * Canonical TypeScript contract for HotelByte's embedded Booking Copilot.
+ *
+ * Executable facts cross this boundary only as discriminated data. Human text
+ * is limited to a user turn or an explanation and is never parsed as an action.
+ */
+/** Compatibility line. Additive compatible changes retain this value; breaking changes must bump it. */
+export const BOOKING_SURFACE_SCHEMA_VERSION = 'booking.surface';
+/** Diagnostic SHA-256 of the exact local schema artifact; it detects drift but is not a compatibility gate. */
+export const BOOKING_SURFACE_SCHEMA_SHA256 = 'a6b4ded86998a25a3345a0813d46cf7c43c9c91c14c5a6cac053af75f8064847';
+export const BOOKING_SURFACE_VERSION_HEADER = 'x-booking-surface-version';
+export const BOOKING_SURFACE_SCHEMA_SHA256_HEADER = 'x-booking-surface-schema-sha256';
+/**
+ * Additive capabilities are sender-gated instead of creating a new contract
+ * line. A sender may use one only after every currently routable peer has
+ * advertised it; an omitted feature list therefore means no optional feature.
+ */
+export const BOOKING_SURFACE_FEATURES = ['trusted-order-observation-v1'];
+export const BOOKING_SURFACE_FEATURES_HEADER = 'x-booking-surface-features';
+function advertisedBookingSurfaceFeatures(advertisement) {
+    if (!Array.isArray(advertisement.features))
+        return new Set();
+    return new Set(advertisement.features.filter((feature) => typeof feature === 'string' && BOOKING_SURFACE_FEATURES.includes(feature)));
+}
+/**
+ * Computes the safe fleet intersection. Callers must supply one fresh
+ * advertisement for every routable release identity; an empty or mixed set
+ * disables optional fields instead of guessing from the schema hash.
+ */
+export function bookingSurfaceFleetFeatures(advertisements) {
+    if (advertisements.length === 0)
+        return [];
+    const advertised = advertisements.map(advertisedBookingSurfaceFeatures);
+    return BOOKING_SURFACE_FEATURES.filter((feature) => advertised.every((features) => features.has(feature)));
+}
+export const BOOKING_SURFACES = [
+    'tenant',
+    'customer_portal',
+    'storefront',
+    'payment_link',
+];
+/**
+ * Process composition modes are deliberately separate from the payload
+ * schema. The default accepts turns already bound by HotelByte's BFF; the
+ * second mode is reserved for an in-process BFF binding seam.
+ */
+export const BOOKING_COPILOT_INGRESS_MODES = ['bff-bound-turn-only', 'bff-ingress-binding'];
+export const BOOKING_COPILOT_ACCEPTED_TURN_KINDS = ['user.turn', 'action.receipt.continuation'];
+export const BOOKING_COPILOT_INGRESS_TURN_KIND = 'user.turn.ingress';
+/** Hard task-level operation budget. The counter is persisted in the ledger. */
+export const BOOKING_COPILOT_MAX_OPERATIONS = 20;
+export const BOOKING_READ_ACTION_KINDS = ['search.patch', 'search.run', 'results.view.patch', 'hotel.focus', 'hotel.select', 'offers.query', 'offers.view.patch', 'offers.compare', 'offer.select', 'offer.check', 'checkout.prepare', 'order.observe'];
+/** Full read journey shared by tenant and customer-portal workspaces. */
+export const BOOKING_FULL_JOURNEY_ACTION_KINDS = ['search.patch', 'search.run', 'results.view.patch', 'hotel.focus', 'offers.query', 'offers.view.patch', 'offers.compare', 'offer.select', 'offer.check', 'checkout.prepare', 'order.observe'];
+/** Product-owned least-privilege action matrix. BFF bindings may narrow these lists, never expand them. */
+export const BOOKING_SURFACE_ALLOWED_ACTIONS = {
+    tenant: BOOKING_FULL_JOURNEY_ACTION_KINDS,
+    customer_portal: BOOKING_FULL_JOURNEY_ACTION_KINDS,
+    storefront: ['search.patch', 'search.run', 'results.view.patch', 'hotel.focus'],
+    payment_link: ['search.patch', 'search.run', 'results.view.patch', 'hotel.focus', 'hotel.select'],
+};
+/** Stable product-matrix observation for UAT and server readiness proofs. */
+export function bookingSurfaceAllowedActions(surface) {
+    return [...BOOKING_SURFACE_ALLOWED_ACTIONS[surface]];
+}
+/** BFF-facing allowlist after optional, fleet-safe feature negotiation. */
+export function bookingSurfaceNegotiatedActions(surface, advertisements) {
+    return bookingSurfaceActionsForFeatures(surface, bookingSurfaceFleetFeatures(advertisements));
+}
+/** Applies an already-computed fleet intersection supplied by the trusted BFF. */
+export function bookingSurfaceActionsForFeatures(surface, features) {
+    return bookingSurfaceAllowedActions(surface).filter((action) => action !== 'order.observe' || features.includes('trusted-order-observation-v1'));
+}
+export const BOOKING_BLOCKER_CODES = ['no_hotels_matched', 'hotel_not_visible', 'hotel_rates_failed', 'criterion_must_not_met', 'offer_target_not_reached', 'offer_unavailable'];
+export const BOOKING_GAP_CODES = ['byos_mapped_risk', 'check_avail_failed', 'check_avail_unverified', 'component_executor_unavailable', 'hotel_not_visible', 'hotel_rates_failed', 'offer_facts_changed', 'offer_not_loaded', 'offer_unavailable', 'order_not_found', 'order_outcome_not_observed', 'order_state_unknown', 'order_status_unavailable', 'requested_offers_not_loaded', 'search_failed', 'search_form_invalid', 'search_session_expired', 'search_terminal_timeout', 'stale_revision', 'surface_adapter_failed', 'undo_token_not_found', 'unhandled', 'unsupported', 'verified_offer_required', 'workspace_changed_during_action', 'criterion_must_not_met', 'no_hotels_matched', 'offer_target_not_reached'];