@d19n/youfibre-odin-sdk 2.0.103-beta.13 → 2.0.103-beta.14

package/dist/wholesale-provider/index.d.ts

@@ -29,5 +29,7 @@ export type { WholesaleProvider, CreateOrderOptions, CancellationReasonCode, Res
 export type { WholesaleResult, WholesaleSyncResponse, WholesaleRejectionResponse, WholesaleRejectionMessage, WholesaleBUS, WholesaleSYS, ISO8601DateTime, ISODate, TransactionId, UPRN, UUID, SwitchOrderReference, } from './types/wholesale';
 export { NetomniaProvider, AggregateNotificationError } from './providers/netomnia-provider';
 export type { NetomniaProviderDeps } from './providers/netomnia-provider';
+export { KCI_EFFECT_ROWS, decideKciDispatch, detectKciKind, } from './kci-effect-bridge';
+export type { KciServiceOrderKind, YfWoComposedActionKey, YfKciEffectKind, YfKciTargetEntity, YfKciEffect, KciEffectRow, KciDispatchDecision, } from './kci-effect-bridge';
 export type { VMO2OrderId, VMO2RequestId, VMO2AppointmentKey, VMO2PremiseId, VMO2OrderNotificationType, VMO2SMRNotificationType, VMO2NotificationEnvelope, VMO2OrderNotification, VMO2SMRNotification, VMO2InboundNotification, } from './types/vmo2';
 export * from './types/fibrecafe';

package/dist/wholesale-provider/index.js

@@ -41,11 +41,16 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AggregateNotificationError = exports.NetomniaProvider = void 0;
+exports.detectKciKind = exports.decideKciDispatch = exports.KCI_EFFECT_ROWS = exports.AggregateNotificationError = exports.NetomniaProvider = void 0;
 // ── Provider implementation ───────────────────────────────────────────
 var netomnia_provider_1 = require("./providers/netomnia-provider");
 Object.defineProperty(exports, "NetomniaProvider", { enumerable: true, get: function () { return netomnia_provider_1.NetomniaProvider; } });
 Object.defineProperty(exports, "AggregateNotificationError", { enumerable: true, get: function () { return netomnia_provider_1.AggregateNotificationError; } });
+// ── KCI effect bridge (canonical typed catalog + walker) ──────────────
+var kci_effect_bridge_1 = require("./kci-effect-bridge");
+Object.defineProperty(exports, "KCI_EFFECT_ROWS", { enumerable: true, get: function () { return kci_effect_bridge_1.KCI_EFFECT_ROWS; } });
+Object.defineProperty(exports, "decideKciDispatch", { enumerable: true, get: function () { return kci_effect_bridge_1.decideKciDispatch; } });
+Object.defineProperty(exports, "detectKciKind", { enumerable: true, get: function () { return kci_effect_bridge_1.detectKciKind; } });
 // ── Reference types (re-exported — not on WholesaleProvider surface) ──
 //
 // FibreCafe wire-format types — useful for module-level DTO consolidation

package/dist/wholesale-provider/kci-effect-bridge.d.ts

@@ -0,0 +1,94 @@
+/**
+ * KCI → YF effect bridge — canonical typed catalog of how every supplier
+ * KCI maps to a YF-side action.
+ *
+ * **Contract:**
+ *
+ *   1. Cannot cancel an INSTALL WorkOrder directly — must cancel the Order.
+ *   2. Cannot move a WO to any stage directly — only via composed actions.
+ *   3. KCIs from providers ONLY move the INSTALL WO. Never the Order.
+ *   4. Every KCI is logged against the Order as an OrderKci record.
+ *
+ * The type system encodes rules #1-3 structurally. `YfKciEffectKind` does
+ * NOT include `ORDER_TRANSITION` (rule #3), `WO_CANCEL` or `WO_TRANSITION`
+ * (rules #1, #2). Only `WO_FLOW_ACTION`, `PROPERTY_WRITE`, `LOG_KCI_ONLY`,
+ * or `NO_OP_DOCUMENTED` reach the WO. Action keys are constrained to the
+ * `YfWoComposedActionKey` union — every value grep-resolves in
+ * `packages/youfibre-odin-sdk/src/actions-v2/<Name>Dto.ts`.
+ *
+ * Companion: `agent-os/knowledge/business-processes/yf-kci-effect-bridge.ts`
+ * — same content as documentation; the SDK file here is the executable
+ * source of truth that production consumers (`receiveKci` walker) import.
+ *
+ * Linked: T-20260508-010 Step 3 followup (receiveKci 100% typed + handled).
+ */
+import type { FibreCafeKciDto, FibreCafeKciReasonCode } from './types/fibrecafe';
+export declare type KciServiceOrderKind = 'PROVIDE' | 'CEASE' | 'MODIFY' | 'UNSOLICITED_CEASE';
+/**
+ * Allowed YF SDK composed action keys. Every value MUST grep-resolve as
+ * `actionKey` in `packages/youfibre-odin-sdk/src/actions-v2/<Name>Dto.ts`.
+ */
+export declare type YfWoComposedActionKey = 'MoveInstallWorkOrderToScheduled' | 'MoveInstallWorkOrderFromInProgressToPending' | 'MoveInstallWorkOrderFromPendingToInProgress' | 'MoveInstallWorkOrderToRemediation' | 'MoveInstallWorkOrderFromRemediationToInProgress' | 'CreateInstallRescheduledChangeReasonSupplier' | 'CompleteInstallWorkOrderFlow' | 'CancelInstallWorkOrderFlowSupplier' | 'CreateInstallCancelledChangeReasonSupplier';
+export declare type YfKciEffectKind = 'LOG_KCI_ONLY' | 'WO_FLOW_ACTION' | 'PROPERTY_WRITE' | 'NO_OP_DOCUMENTED';
+export declare type YfKciTargetEntity = 'OrderModule:Order' | 'CrmModule:Address' | 'FieldServiceModule:WorkOrder';
+export interface YfKciEffect {
+    readonly kind: YfKciEffectKind;
+    /** For WO_FLOW_ACTION: the composed action key. */
+    readonly woActionKey?: YfWoComposedActionKey;
+    /** For PROPERTY_WRITE: target entity + property keys. */
+    readonly propertyWrite?: {
+        readonly entityKey: YfKciTargetEntity;
+        readonly properties: ReadonlyArray<string>;
+    };
+    /** For NO_OP_DOCUMENTED: required reason text. */
+    readonly noOpReason?: string;
+    readonly notes: string;
+}
+export interface KciEffectRow {
+    readonly id: string;
+    readonly reasonCode: FibreCafeKciReasonCode;
+    readonly serviceOrderKind: KciServiceOrderKind;
+    readonly yfOrderStagePreconditions?: ReadonlyArray<string>;
+    readonly yfEffect: YfKciEffect;
+    /** Always true per rule #4. Field is explicit so future rows that
+     *  document an intentional skip can mark it false. */
+    readonly logAgainstOrder: boolean;
+    readonly specRef?: string;
+}
+export declare const KCI_EFFECT_ROWS: ReadonlyArray<KciEffectRow>;
+export declare type KciDispatchDecision = {
+    kind: 'LOG_KCI_ONLY';
+    row: KciEffectRow;
+} | {
+    kind: 'WO_FLOW_ACTION';
+    row: KciEffectRow;
+    woActionKey: YfWoComposedActionKey;
+} | {
+    kind: 'PROPERTY_WRITE';
+    row: KciEffectRow;
+    entityKey: YfKciTargetEntity;
+    properties: ReadonlyArray<string>;
+} | {
+    kind: 'NO_OP_DOCUMENTED';
+    row: KciEffectRow;
+    reason: string;
+} | {
+    kind: 'NO_MATCH';
+    reasonCode: FibreCafeKciReasonCode;
+    serviceOrderKind: KciServiceOrderKind;
+};
+/**
+ * Determine which serviceOrder kind the KCI is about by inspecting which
+ * sub-body field is populated.
+ */
+export declare function detectKciKind(dto: FibreCafeKciDto): KciServiceOrderKind | null;
+/**
+ * Pure function — given a KCI dto, return the dispatch decision per the
+ * bridge. Caller (`receiveKci` in netomnia.provider.ts) executes the
+ * decision (fires the SDK action / writes the property / logs the KCI).
+ *
+ * The decision type is exhaustive: no `default` fall-through; missing
+ * (reasonCode × kind) tuples return `NO_MATCH` so the caller can surface
+ * the gap explicitly.
+ */
+export declare function decideKciDispatch(dto: FibreCafeKciDto): KciDispatchDecision;

package/dist/wholesale-provider/kci-effect-bridge.js

@@ -0,0 +1,325 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decideKciDispatch = exports.detectKciKind = exports.KCI_EFFECT_ROWS = void 0;
+// ──────────────────────────────────────────────────────────────────────
+//  Bridge rows — PROVIDE coverage (24/24)
+// ──────────────────────────────────────────────────────────────────────
+//
+//  CEASE / MODIFY / UNSOLICITED_CEASE are out of scope per Frank
+//  2026-05-09. Add rows when those journeys are tested.
+exports.KCI_EFFECT_ROWS = [
+    // ── PROVIDE — happy path ──────────────────────────────────────────
+    {
+        id: 'provide-acknowledged',
+        reasonCode: 'ACKNOWLEDGED',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'PROPERTY_WRITE',
+            propertyWrite: { entityKey: 'OrderModule:Order', properties: ['ExternalReference'] },
+            notes: 'Stamp NET supplierOrderReference onto YF Order.ExternalReference.',
+        },
+        logAgainstOrder: true,
+        specRef: 'fibrecafe-docs/pages/orderstate.md (ACKNOWLEDGED)',
+    },
+    {
+        id: 'provide-committed',
+        reasonCode: 'COMMITTED',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'PROPERTY_WRITE',
+            propertyWrite: { entityKey: 'OrderModule:Order', properties: ['CommittedDate'] },
+            notes: 'Persist supplier-committed fulfillment date. Order stage already moved Sold→Supply on dispatch (rule #3: KCI does not move Order).',
+        },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-completed',
+        reasonCode: 'COMPLETED',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'WO_FLOW_ACTION',
+            woActionKey: 'CompleteInstallWorkOrderFlow',
+            notes: 'Supplier confirmed install completion. Composed flow handles WO Done + downstream (ISP reprovision, etc.). Order Sold→Supply→Active cascade is downstream of WO completion.',
+        },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-cancelled',
+        reasonCode: 'CANCELLED',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'WO_FLOW_ACTION',
+            woActionKey: 'CancelInstallWorkOrderFlowSupplier',
+            notes: 'Supplier-initiated cancel. Composed flow handles WO transition + Order cascade — NOT a raw stage move (rule #1).',
+        },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-failed',
+        reasonCode: 'FAILED',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'WO_FLOW_ACTION',
+            woActionKey: 'CancelInstallWorkOrderFlowSupplier',
+            notes: 'Same disposition as CANCELLED — install will not happen.',
+        },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-rejected',
+        reasonCode: 'REJECTED',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'WO_FLOW_ACTION',
+            woActionKey: 'CancelInstallWorkOrderFlowSupplier',
+            notes: 'Order rejected at validation time. Supplier-cancel flow.',
+        },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-order-rejected',
+        reasonCode: 'ORDER_REJECTED',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'WO_FLOW_ACTION',
+            woActionKey: 'CancelInstallWorkOrderFlowSupplier',
+            notes: 'Order rejected at processing.',
+        },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-partial',
+        reasonCode: 'PARTIAL',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'WO_FLOW_ACTION',
+            woActionKey: 'CompleteInstallWorkOrderFlow',
+            notes: 'Partial install — primary tasks done, side tasks deferred. Treated as terminal complete on YF side.',
+        },
+        logAgainstOrder: true,
+    },
+    // ── PROVIDE — Pending (tenant action required) ───────────────────
+    {
+        id: 'provide-information-required',
+        reasonCode: 'INFORMATION_REQUIRED',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'WO_FLOW_ACTION',
+            woActionKey: 'MoveInstallWorkOrderFromInProgressToPending',
+            notes: 'Supplier needs additional info before continuing. WO → Pending.',
+        },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-contact-customer',
+        reasonCode: 'CONTACT_CUSTOMER',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'WO_FLOW_ACTION',
+            woActionKey: 'MoveInstallWorkOrderFromInProgressToPending',
+            notes: 'Supplier asks YF to contact customer. WO → Pending.',
+        },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-contact-reappoint',
+        reasonCode: 'CONTACT_REAPPOINT',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'WO_FLOW_ACTION',
+            woActionKey: 'MoveInstallWorkOrderFromInProgressToPending',
+            notes: 'Customer-initiated reappointment needed. WO → Pending until new appointment.',
+        },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-reappoint',
+        reasonCode: 'REAPPOINT',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'WO_FLOW_ACTION',
+            woActionKey: 'MoveInstallWorkOrderFromInProgressToPending',
+            notes: 'Supplier requests reappointment. WO → Pending. Followed by REAPPOINTED when slot reserved.',
+        },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-resumed',
+        reasonCode: 'RESUMED',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'WO_FLOW_ACTION',
+            woActionKey: 'MoveInstallWorkOrderFromPendingToInProgress',
+            notes: 'Supplier resumed fulfillment after Pending/Held.',
+        },
+        logAgainstOrder: true,
+    },
+    // ── PROVIDE — Remediation ────────────────────────────────────────
+    {
+        id: 'provide-delay',
+        reasonCode: 'DELAY',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'WO_FLOW_ACTION',
+            woActionKey: 'MoveInstallWorkOrderToRemediation',
+            notes: "Supplier delay — install can't complete on planned date. WO → RemediationRequired for triage.",
+        },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-resolved',
+        reasonCode: 'RESOLVED',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'WO_FLOW_ACTION',
+            woActionKey: 'MoveInstallWorkOrderFromRemediationToInProgress',
+            notes: 'Problem resolved without target-date impact. WO → InProgress.',
+        },
+        logAgainstOrder: true,
+    },
+    // ── PROVIDE — appointment confirmation ────────────────────────────
+    {
+        id: 'provide-reappointed',
+        reasonCode: 'REAPPOINTED',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'WO_FLOW_ACTION',
+            woActionKey: 'CreateInstallRescheduledChangeReasonSupplier',
+            notes: 'Supplier-side reappointment confirmed. Reschedule flow + ChangeReason for audit.',
+        },
+        logAgainstOrder: true,
+    },
+    // ── PROVIDE — informational / no-action ──────────────────────────
+    {
+        id: 'provide-update',
+        reasonCode: 'UPDATE',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: { kind: 'LOG_KCI_ONLY', notes: 'General update; no specific action.' },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-warning',
+        reasonCode: 'WARNING',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: { kind: 'LOG_KCI_ONLY', notes: 'Supplier warning, informational.' },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-additional',
+        reasonCode: 'ADDITIONAL',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: { kind: 'LOG_KCI_ONLY', notes: 'Additional info added (notes / engineer tasks).' },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-created',
+        reasonCode: 'CREATED',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: { kind: 'LOG_KCI_ONLY', notes: 'Rare on PROVIDE; supplier-created entity.' },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-resubmit',
+        reasonCode: 'RESUBMIT',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'LOG_KCI_ONLY',
+            notes: 'Supplier asks tenant to resubmit. Manual ops triage.',
+        },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-amended',
+        reasonCode: 'AMENDED',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'LOG_KCI_ONLY',
+            notes: 'Amendment applied at supplier side. WO continues at current stage.',
+        },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-amendment-rejected',
+        reasonCode: 'AMENDMENT_REJECTED',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'LOG_KCI_ONLY',
+            notes: 'Supplier rejected an amendment request. WO continues with original spec.',
+        },
+        logAgainstOrder: true,
+    },
+    {
+        id: 'provide-cancellation-rejected',
+        reasonCode: 'CANCELLATION_REJECTED',
+        serviceOrderKind: 'PROVIDE',
+        yfEffect: {
+            kind: 'LOG_KCI_ONLY',
+            notes: 'Supplier rejected cancellation request. WO continues; ops triage.',
+        },
+        logAgainstOrder: true,
+    },
+];
+/**
+ * Determine which serviceOrder kind the KCI is about by inspecting which
+ * sub-body field is populated.
+ */
+function detectKciKind(dto) {
+    if (dto.provideServiceOrder)
+        return 'PROVIDE';
+    if (dto.ceaseServiceOrder)
+        return 'CEASE';
+    if (dto.modifyServiceOrder)
+        return 'MODIFY';
+    if (dto.unsolicitedCeaseServiceOrder)
+        return 'UNSOLICITED_CEASE';
+    return null;
+}
+exports.detectKciKind = detectKciKind;
+/**
+ * Pure function — given a KCI dto, return the dispatch decision per the
+ * bridge. Caller (`receiveKci` in netomnia.provider.ts) executes the
+ * decision (fires the SDK action / writes the property / logs the KCI).
+ *
+ * The decision type is exhaustive: no `default` fall-through; missing
+ * (reasonCode × kind) tuples return `NO_MATCH` so the caller can surface
+ * the gap explicitly.
+ */
+function decideKciDispatch(dto) {
+    const kind = detectKciKind(dto);
+    if (!kind) {
+        return {
+            kind: 'NO_MATCH',
+            reasonCode: dto.reasonCode,
+            serviceOrderKind: 'PROVIDE',
+        };
+    }
+    const row = exports.KCI_EFFECT_ROWS.find((r) => r.reasonCode === dto.reasonCode && r.serviceOrderKind === kind);
+    if (!row) {
+        return { kind: 'NO_MATCH', reasonCode: dto.reasonCode, serviceOrderKind: kind };
+    }
+    switch (row.yfEffect.kind) {
+        case 'LOG_KCI_ONLY':
+            return { kind: 'LOG_KCI_ONLY', row };
+        case 'WO_FLOW_ACTION':
+            if (!row.yfEffect.woActionKey) {
+                throw new Error(`bridge invariant: WO_FLOW_ACTION row ${row.id} missing woActionKey`);
+            }
+            return { kind: 'WO_FLOW_ACTION', row, woActionKey: row.yfEffect.woActionKey };
+        case 'PROPERTY_WRITE':
+            if (!row.yfEffect.propertyWrite) {
+                throw new Error(`bridge invariant: PROPERTY_WRITE row ${row.id} missing propertyWrite`);
+            }
+            return {
+                kind: 'PROPERTY_WRITE',
+                row,
+                entityKey: row.yfEffect.propertyWrite.entityKey,
+                properties: row.yfEffect.propertyWrite.properties,
+            };
+        case 'NO_OP_DOCUMENTED':
+            if (!row.yfEffect.noOpReason) {
+                throw new Error(`bridge invariant: NO_OP_DOCUMENTED row ${row.id} missing noOpReason`);
+            }
+            return { kind: 'NO_OP_DOCUMENTED', row, reason: row.yfEffect.noOpReason };
+    }
+}
+exports.decideKciDispatch = decideKciDispatch;

package/dist/wholesale-provider/test/kci-effect-bridge.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/wholesale-provider/test/kci-effect-bridge.spec.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * KCI effect bridge walker tests.
+ *
+ * Verifies:
+ *   1. detectKciKind correctly classifies dto by populated sub-body
+ *   2. decideKciDispatch returns the correct decision for every (reasonCode × kind)
+ *      tuple in the bridge
+ *   3. Coverage: every PROVIDE × KciReasonCode tuple has a row (no NO_MATCH for in-scope)
+ *   4. Bridge invariants hold (every WO_FLOW_ACTION row has woActionKey, etc.)
+ *
+ * Run: npm run test:wholesale-provider — runs all wholesale provider specs
+ */
+const kci_effect_bridge_1 = require("../kci-effect-bridge");
+let passed = 0;
+let failed = 0;
+const failures = [];
+function assert(label, cond, hint) {
+    if (cond) {
+        passed += 1;
+        console.log(`  PASS  ${label}`);
+    }
+    else {
+        failed += 1;
+        const msg = `  FAIL  ${label}${hint ? ' — ' + hint : ''}`;
+        failures.push(msg);
+        console.log(msg);
+    }
+}
+function makeProvideDto(reasonCode) {
+    return {
+        id: 'kci-test',
+        sequenceNumber: 1,
+        issuedOn: '2026-05-09T00:00:00Z',
+        reasonCode,
+        provideServiceOrder: {
+            id: 'order-1',
+            tenant: 'YOUFIBRE',
+            status: 'IN_PROGRESS',
+            address: { id: '12345', type: 'UPRN' },
+            serviceOrderItem: {
+                serviceSpecification: { id: 'FTTP' },
+                serviceCharacteristics: [],
+            },
+            primaryContact: { name: 'Test', phoneNumber: '0' },
+        },
+    };
+}
+function run() {
+    console.log('KCI effect bridge — walker tests\n');
+    // ── 1. detectKciKind correctly classifies ──────────────────────────
+    console.log('Test: detectKciKind on PROVIDE');
+    {
+        const dto = makeProvideDto('ACKNOWLEDGED');
+        assert('detectKciKind returns PROVIDE', (0, kci_effect_bridge_1.detectKciKind)(dto) === 'PROVIDE');
+    }
+    console.log('Test: detectKciKind on CEASE');
+    {
+        const dto = {
+            id: 'k',
+            sequenceNumber: 1,
+            issuedOn: '2026-05-09T00:00:00Z',
+            reasonCode: 'COMPLETED',
+            ceaseServiceOrder: { id: 'o', tenant: 'YF', status: 'COMPLETED' },
+        };
+        assert('detectKciKind returns CEASE', (0, kci_effect_bridge_1.detectKciKind)(dto) === 'CEASE');
+    }
+    console.log('Test: detectKciKind on no-body dto');
+    {
+        const dto = {
+            id: 'k',
+            sequenceNumber: 1,
+            issuedOn: '2026-05-09T00:00:00Z',
+            reasonCode: 'WARNING',
+        };
+        assert('detectKciKind returns null', (0, kci_effect_bridge_1.detectKciKind)(dto) === null);
+    }
+    // ── 2. Bridge coverage: every PROVIDE reason resolves ──────────────
+    const allReasons = [
+        'CREATED', 'ACKNOWLEDGED', 'COMMITTED', 'UPDATE',
+        'INFORMATION_REQUIRED', 'DELAY', 'RESUBMIT', 'RESOLVED', 'RESUMED',
+        'AMENDED', 'AMENDMENT_REJECTED', 'CANCELLED', 'CANCELLATION_REJECTED',
+        'COMPLETED', 'PARTIAL', 'FAILED', 'REJECTED', 'ORDER_REJECTED',
+        'REAPPOINT', 'REAPPOINTED', 'CONTACT_CUSTOMER', 'CONTACT_REAPPOINT',
+        'WARNING', 'ADDITIONAL',
+    ];
+    console.log('Test: every PROVIDE reason code has a matching row (24/24)');
+    for (const reasonCode of allReasons) {
+        const dto = makeProvideDto(reasonCode);
+        const decision = (0, kci_effect_bridge_1.decideKciDispatch)(dto);
+        assert(`${reasonCode} resolves`, decision.kind !== 'NO_MATCH', decision.kind === 'NO_MATCH'
+            ? `got NO_MATCH for PROVIDE × ${reasonCode}`
+            : undefined);
+    }
+    // ── 3. Specific decision shapes — spot checks per kind ─────────────
+    console.log('Test: ACKNOWLEDGED → PROPERTY_WRITE on Order.ExternalReference');
+    {
+        const decision = (0, kci_effect_bridge_1.decideKciDispatch)(makeProvideDto('ACKNOWLEDGED'));
+        assert('kind=PROPERTY_WRITE', decision.kind === 'PROPERTY_WRITE');
+        if (decision.kind === 'PROPERTY_WRITE') {
+            assert('entity=OrderModule:Order', decision.entityKey === 'OrderModule:Order');
+            assert('properties contains ExternalReference', decision.properties.includes('ExternalReference'));
+        }
+    }
+    console.log('Test: COMPLETED → WO_FLOW_ACTION CompleteInstallWorkOrderFlow');
+    {
+        const decision = (0, kci_effect_bridge_1.decideKciDispatch)(makeProvideDto('COMPLETED'));
+        assert('kind=WO_FLOW_ACTION', decision.kind === 'WO_FLOW_ACTION');
+        if (decision.kind === 'WO_FLOW_ACTION') {
+            assert('woActionKey=CompleteInstallWorkOrderFlow', decision.woActionKey === 'CompleteInstallWorkOrderFlow');
+        }
+    }
+    console.log('Test: CANCELLED → WO_FLOW_ACTION CancelInstallWorkOrderFlowSupplier');
+    {
+        const decision = (0, kci_effect_bridge_1.decideKciDispatch)(makeProvideDto('CANCELLED'));
+        assert('kind=WO_FLOW_ACTION', decision.kind === 'WO_FLOW_ACTION');
+        if (decision.kind === 'WO_FLOW_ACTION') {
+            assert('woActionKey=CancelInstallWorkOrderFlowSupplier', decision.woActionKey === 'CancelInstallWorkOrderFlowSupplier');
+        }
+    }
+    console.log('Test: INFORMATION_REQUIRED → MoveInstallWorkOrderFromInProgressToPending');
+    {
+        const decision = (0, kci_effect_bridge_1.decideKciDispatch)(makeProvideDto('INFORMATION_REQUIRED'));
+        assert('kind=WO_FLOW_ACTION', decision.kind === 'WO_FLOW_ACTION');
+        if (decision.kind === 'WO_FLOW_ACTION') {
+            assert('woActionKey=MoveInstallWorkOrderFromInProgressToPending', decision.woActionKey === 'MoveInstallWorkOrderFromInProgressToPending');
+        }
+    }
+    console.log('Test: DELAY → MoveInstallWorkOrderToRemediation');
+    {
+        const decision = (0, kci_effect_bridge_1.decideKciDispatch)(makeProvideDto('DELAY'));
+        assert('kind=WO_FLOW_ACTION', decision.kind === 'WO_FLOW_ACTION');
+        if (decision.kind === 'WO_FLOW_ACTION') {
+            assert('woActionKey=MoveInstallWorkOrderToRemediation', decision.woActionKey === 'MoveInstallWorkOrderToRemediation');
+        }
+    }
+    console.log('Test: RESUMED → MoveInstallWorkOrderFromPendingToInProgress');
+    {
+        const decision = (0, kci_effect_bridge_1.decideKciDispatch)(makeProvideDto('RESUMED'));
+        assert('kind=WO_FLOW_ACTION', decision.kind === 'WO_FLOW_ACTION');
+        if (decision.kind === 'WO_FLOW_ACTION') {
+            assert('woActionKey=MoveInstallWorkOrderFromPendingToInProgress', decision.woActionKey === 'MoveInstallWorkOrderFromPendingToInProgress');
+        }
+    }
+    console.log('Test: REAPPOINTED → CreateInstallRescheduledChangeReasonSupplier');
+    {
+        const decision = (0, kci_effect_bridge_1.decideKciDispatch)(makeProvideDto('REAPPOINTED'));
+        assert('kind=WO_FLOW_ACTION', decision.kind === 'WO_FLOW_ACTION');
+        if (decision.kind === 'WO_FLOW_ACTION') {
+            assert('woActionKey=CreateInstallRescheduledChangeReasonSupplier', decision.woActionKey === 'CreateInstallRescheduledChangeReasonSupplier');
+        }
+    }
+    console.log('Test: WARNING → LOG_KCI_ONLY');
+    {
+        const decision = (0, kci_effect_bridge_1.decideKciDispatch)(makeProvideDto('WARNING'));
+        assert('kind=LOG_KCI_ONLY', decision.kind === 'LOG_KCI_ONLY');
+    }
+    // ── 4. Bridge invariants ───────────────────────────────────────────
+    console.log('Test: every row has logAgainstOrder=true (Frank rule #4)');
+    {
+        const violations = kci_effect_bridge_1.KCI_EFFECT_ROWS.filter((r) => !r.logAgainstOrder);
+        assert('no logAgainstOrder violations', violations.length === 0, violations.length > 0 ? `violations: ${violations.map((r) => r.id).join(', ')}` : undefined);
+    }
+    console.log('Test: every WO_FLOW_ACTION row has woActionKey set');
+    {
+        const violations = kci_effect_bridge_1.KCI_EFFECT_ROWS.filter((r) => r.yfEffect.kind === 'WO_FLOW_ACTION' && !r.yfEffect.woActionKey);
+        assert('no missing woActionKey', violations.length === 0, violations.length > 0 ? `rows: ${violations.map((r) => r.id).join(', ')}` : undefined);
+    }
+    console.log('Test: every PROPERTY_WRITE row has propertyWrite set');
+    {
+        const violations = kci_effect_bridge_1.KCI_EFFECT_ROWS.filter((r) => r.yfEffect.kind === 'PROPERTY_WRITE' && !r.yfEffect.propertyWrite);
+        assert('no missing propertyWrite', violations.length === 0);
+    }
+    console.log('Test: row ids are unique');
+    {
+        const ids = new Set();
+        let dupes = 0;
+        for (const row of kci_effect_bridge_1.KCI_EFFECT_ROWS) {
+            if (ids.has(row.id))
+                dupes += 1;
+            ids.add(row.id);
+        }
+        assert('no duplicate ids', dupes === 0, dupes > 0 ? `${dupes} dupes` : undefined);
+    }
+    // ── 5. NO_MATCH for out-of-scope kinds (CEASE/MODIFY/UNSOLICITED) ──
+    console.log('Test: CEASE × COMPLETED returns NO_MATCH (out of scope)');
+    {
+        const dto = {
+            id: 'k',
+            sequenceNumber: 1,
+            issuedOn: '2026-05-09T00:00:00Z',
+            reasonCode: 'COMPLETED',
+            ceaseServiceOrder: { id: 'o', tenant: 'YF', status: 'COMPLETED' },
+        };
+        const decision = (0, kci_effect_bridge_1.decideKciDispatch)(dto);
+        assert('kind=NO_MATCH', decision.kind === 'NO_MATCH');
+        if (decision.kind === 'NO_MATCH') {
+            const k = decision.serviceOrderKind;
+            assert('serviceOrderKind=CEASE', k === 'CEASE');
+        }
+    }
+    console.log('\n────────────────────────────────────────');
+    console.log(`Tests: ${passed} passed, ${failed} failed`);
+    if (failed > 0) {
+        console.log('');
+        failures.forEach((f) => console.log(f));
+        process.exit(1);
+    }
+}
+run();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d19n/youfibre-odin-sdk",
-  "version": "2.0.103-beta.13",
+  "version": "2.0.103-beta.14",
   "description": "",
   "author": "@d19n",
   "license": "UNLICENSED",
@@ -32,7 +32,7 @@
     "@d19n/odin-types": "^3.0.41"
   },
   "scripts": {
-    "test:wholesale-provider": "npx --yes tsx src/wholesale-provider/test/netomnia-provider.spec.ts",
+    "test:wholesale-provider": "npx --yes tsx src/wholesale-provider/test/netomnia-provider.spec.ts && npx --yes tsx src/wholesale-provider/test/kci-effect-bridge.spec.ts",
     "release:beta": "git pull --ff-only && rm -rf dist && tsc && npm version prerelease --preid=beta && git push && npm publish --tag beta",
     "release:prod": "git pull --ff-only && rm -rf dist && tsc && npm version patch && git push && npm publish --tag latest"
   },