@d19n/youfibre-odin-sdk 2.0.151 → 2.0.157

package/dist/wholesale-provider/change-reason-classifications.d.ts

@@ -0,0 +1,73 @@
+/**
+ * ChangeReason enum classifications — the single source of truth for how
+ * the Install Fulfilment digest (and any future audit / detector) interprets
+ * `ChangeReasonRescheduleReason` and `ChangeReasonCancelReason` values.
+ *
+ * Why this lives in the SDK:
+ *   The values in `entities-v2/ChangeReason.ts` are flat enums — they don't
+ *   tell a consumer "which of these are tenant-side resolves vs supplier-side
+ *   escalations vs data hygiene". Without a classification anchor, every
+ *   downstream consumer (alerts, dashboards, remediation scripts) ends up
+ *   hand-coding its own predicate.
+ *
+ *   The authoring origin is the agent-os BP knowledge file
+ *   `business-processes/change-reason-classifications.ts`; this is its
+ *   published projection so both the agent-os tooling AND deployed services
+ *   (youfibre-api-connect) consume one source. Keep the two in lockstep.
+ *
+ *   String literals (not the SDK enum) are used so the sets stay decoupled
+ *   from enum-shape churn; the `unclassified*` helpers below surface drift
+ *   when a consumer passes `Object.values(ChangeReason*Reason)`.
+ */
+/**
+ * Billing-blocked reschedules — YF moved the WO because the customer has no
+ * active direct-debit mandate. YF does NOT dispatch `amendOrder` to the
+ * supplier (held off until billing is set up), so these will NEVER receive
+ * an `AMENDED` KCI back. Action lever: chase the customer for the mandate.
+ */
+export declare const BILLING_BLOCKED_RESCHEDULE_REASONS: ReadonlySet<string>;
+/** Alias kept for backward compatibility — prefer the specific category above. */
+export declare const TENANT_PENDING_RESCHEDULE_REASONS: ReadonlySet<string>;
+/**
+ * Customer follow-up reschedules — customer unavailable / unaware, so YF
+ * moved the appointment and must chase the customer to rebook.
+ */
+export declare const CUSTOMER_FOLLOWUP_RESCHEDULE_REASONS: ReadonlySet<string>;
+/**
+ * Misselling-signal reschedules — customer indicates they don't need the
+ * service (likely a sales-time misselling artifact).
+ */
+export declare const MISSELLING_RESCHEDULE_REASONS: ReadonlySet<string>;
+/** Reschedules whose root cause is a supplier-side issue. */
+export declare const SUPPLIER_SIDE_CAUSE_RESCHEDULE_REASONS: ReadonlySet<string>;
+/** Intra-today shuffle — `previousDate = today AND currentDate = today`. */
+export declare const INTRA_TODAY_RESCHEDULE_REASONS: ReadonlySet<string>;
+/**
+ * Recontract side-effect cancellations — applying an existing-subscriber
+ * recontract cancels the PREVIOUS Order with `CancellationReason =
+ * CONTRACT_RENEWAL`. The install succeeded; the previous Order is retired.
+ * MUST be excluded from cancellation counts.
+ */
+export declare const RECONTRACT_SIDE_EFFECT_CANCEL_REASONS: ReadonlySet<string>;
+/** Data-hygiene cancellations — excluded from "failed installs". */
+export declare const DATA_HYGIENE_CANCEL_REASONS: ReadonlySet<string>;
+/** Customer churn / decision cancellations — real fulfilment loss. */
+export declare const CHURN_CANCEL_REASONS: ReadonlySet<string>;
+/** Supplier-side cause cancellations — install blocked by supplier/network. */
+export declare const SUPPLIER_SIDE_CAUSE_CANCEL_REASONS: ReadonlySet<string>;
+/** Customer-side cause cancellations — premises / billing / engagement. */
+export declare const CUSTOMER_SIDE_CAUSE_CANCEL_REASONS: ReadonlySet<string>;
+/**
+ * A cancellation counts as a fulfilment failure iff its CancellationReason
+ * is NOT a recontract side-effect AND NOT a data-hygiene cleanup. Customer-
+ * and supplier-cause cancellations DO count — the customer didn't get
+ * serviced today. Unknown reason → conservative (counts as failure).
+ */
+export declare function isFulfilmentFailureCancel(cancelReason: string | undefined): boolean;
+/**
+ * Returns enum values from `allKnownValues` not classified into any
+ * operational set. Callers pass `Object.values(ChangeReasonRescheduleReason)`
+ * so this stays free of a hard enum import while still enabling drift checks.
+ */
+export declare function unclassifiedRescheduleReasons(allKnownValues: readonly string[]): string[];
+export declare function unclassifiedCancelReasons(allKnownValues: readonly string[]): string[];

package/dist/wholesale-provider/change-reason-classifications.js

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * ChangeReason enum classifications — the single source of truth for how
+ * the Install Fulfilment digest (and any future audit / detector) interprets
+ * `ChangeReasonRescheduleReason` and `ChangeReasonCancelReason` values.
+ *
+ * Why this lives in the SDK:
+ *   The values in `entities-v2/ChangeReason.ts` are flat enums — they don't
+ *   tell a consumer "which of these are tenant-side resolves vs supplier-side
+ *   escalations vs data hygiene". Without a classification anchor, every
+ *   downstream consumer (alerts, dashboards, remediation scripts) ends up
+ *   hand-coding its own predicate.
+ *
+ *   The authoring origin is the agent-os BP knowledge file
+ *   `business-processes/change-reason-classifications.ts`; this is its
+ *   published projection so both the agent-os tooling AND deployed services
+ *   (youfibre-api-connect) consume one source. Keep the two in lockstep.
+ *
+ *   String literals (not the SDK enum) are used so the sets stay decoupled
+ *   from enum-shape churn; the `unclassified*` helpers below surface drift
+ *   when a consumer passes `Object.values(ChangeReason*Reason)`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unclassifiedCancelReasons = exports.unclassifiedRescheduleReasons = exports.isFulfilmentFailureCancel = exports.CUSTOMER_SIDE_CAUSE_CANCEL_REASONS = exports.SUPPLIER_SIDE_CAUSE_CANCEL_REASONS = exports.CHURN_CANCEL_REASONS = exports.DATA_HYGIENE_CANCEL_REASONS = exports.RECONTRACT_SIDE_EFFECT_CANCEL_REASONS = exports.INTRA_TODAY_RESCHEDULE_REASONS = exports.SUPPLIER_SIDE_CAUSE_RESCHEDULE_REASONS = exports.MISSELLING_RESCHEDULE_REASONS = exports.CUSTOMER_FOLLOWUP_RESCHEDULE_REASONS = exports.TENANT_PENDING_RESCHEDULE_REASONS = exports.BILLING_BLOCKED_RESCHEDULE_REASONS = void 0;
+// ──────────────────────────────────────────────────────────────────────
+// RescheduleReason classification
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * Billing-blocked reschedules — YF moved the WO because the customer has no
+ * active direct-debit mandate. YF does NOT dispatch `amendOrder` to the
+ * supplier (held off until billing is set up), so these will NEVER receive
+ * an `AMENDED` KCI back. Action lever: chase the customer for the mandate.
+ */
+exports.BILLING_BLOCKED_RESCHEDULE_REASONS = new Set([
+    'MISSING_MANDATE',
+]);
+/** Alias kept for backward compatibility — prefer the specific category above. */
+exports.TENANT_PENDING_RESCHEDULE_REASONS = exports.BILLING_BLOCKED_RESCHEDULE_REASONS;
+/**
+ * Customer follow-up reschedules — customer unavailable / unaware, so YF
+ * moved the appointment and must chase the customer to rebook.
+ */
+exports.CUSTOMER_FOLLOWUP_RESCHEDULE_REASONS = new Set([
+    'PROPERTY_UNOCCUPIED',
+    'UNAWARE_OF_APPOINTMENT',
+]);
+/**
+ * Misselling-signal reschedules — customer indicates they don't need the
+ * service (likely a sales-time misselling artifact).
+ */
+exports.MISSELLING_RESCHEDULE_REASONS = new Set([
+    'NO_LONGER_REQUIRED',
+    'CANCELLATION_FOR_PERSONAL_REASONS',
+]);
+/** Reschedules whose root cause is a supplier-side issue. */
+exports.SUPPLIER_SIDE_CAUSE_RESCHEDULE_REASONS = new Set([
+    'AREA_NOT_RFS_SUPPLIER',
+    'ADDITIONAL_WORKS_REQUIRED_APPROVAL_NEEDED',
+    'SCHEDULE_CHANGED',
+    'SCHEDULE_CONTRACTOR_CHANGED',
+    'ENGINEER_DID_NOT_ATTEND',
+    'ENGINEER_UNABLE_TO_RESOLVE',
+    'ADVERSE_WEATHER_CONDITIONS',
+    'UNABLE_TO_ATTEND', // supplier-set slot the customer couldn't make
+]);
+/** Intra-today shuffle — `previousDate = today AND currentDate = today`. */
+exports.INTRA_TODAY_RESCHEDULE_REASONS = new Set([
+    'TIME_BLOCK_CHANGED',
+]);
+// ──────────────────────────────────────────────────────────────────────
+// CancelReason classification
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * Recontract side-effect cancellations — applying an existing-subscriber
+ * recontract cancels the PREVIOUS Order with `CancellationReason =
+ * CONTRACT_RENEWAL`. The install succeeded; the previous Order is retired.
+ * MUST be excluded from cancellation counts.
+ */
+exports.RECONTRACT_SIDE_EFFECT_CANCEL_REASONS = new Set([
+    'CONTRACT_RENEWAL',
+    'CONTRACT_RENEWAL_ROLLBACK',
+]);
+/** Data-hygiene cancellations — excluded from "failed installs". */
+exports.DATA_HYGIENE_CANCEL_REASONS = new Set([
+    'DUPLICATE_ORDER_OR_WORK_ORDER',
+    'REMEDIATION_RAISED_IN_ERROR',
+    'PREPULL_CANCELLATION_RAISED_IN_ERROR',
+    'REMEDIATION_NOT_REQUIRED',
+    'SERVICE_VISIT_NO_LONGER_REQUIRED',
+    'PTF_PROCESS_NOT_FOLLOWED',
+    'CHANGED_ASSIGNED_CONTRACTOR',
+    'PREPULL_CANCELLATION_ACCEPTING_INST_RISK',
+]);
+/** Customer churn / decision cancellations — real fulfilment loss. */
+exports.CHURN_CANCEL_REASONS = new Set([
+    'CUSTOMER_CANCELLED',
+    'STAYING_WITH_EXISTING_PROVIDER',
+    'NO_LONGER_INTERESTED_IN_SERVICE',
+    'MULTIPLE_RESCHEDULE_NO_LONGER_WANTS_SERVICE',
+    'MOVING_PREMISES',
+    'CLAIMING_MISSELING',
+    'STILL_IN_CONTRACT',
+    'CANCELLATION_FOR_PERSONAL_REASONS',
+]);
+/** Supplier-side cause cancellations — install blocked by supplier/network. */
+exports.SUPPLIER_SIDE_CAUSE_CANCEL_REASONS = new Set([
+    'AREA_NOT_RFS_SUPPLIER',
+    'MDU_NOT_RFS',
+    'CONNECTION_COSTS_UNVIABLE',
+    'NO_CLEAR_INSTALLATION_ROUTE',
+    'UNABLE_TO_GET_PTD_WAYLEAVE',
+    'RFS_QUARANTINED',
+    'RFS_REVERSED',
+    'ENGINEER_DID_NOT_ATTEND',
+    'ADDITIONAL_WORKS_REQUIRED_APPROVAL_NEEDED',
+    'ADVERSE_WEATHER_CONDITIONS',
+]);
+/** Customer-side cause cancellations — premises / billing / engagement. */
+exports.CUSTOMER_SIDE_CAUSE_CANCEL_REASONS = new Set([
+    'MISSING_MANDATE',
+    'HEALTH_AND_SAFETY_CONCERN_CUSTOMER_PREMISE',
+    'H_S_CONCERN_CUSTOMER_PREMISE',
+    'UNHAPPY_WITH_EXTERNAL_INSTALLATION_ROUTE',
+    'UNHAPPY_WITH_INTERNAL_INSTALLATION_ROUTE',
+    'INCORRECT_ADDRESS_BOOKED',
+    'UNABLE_TO_ATTEND',
+    'CUSTOMER_REFUSED_REMEDIATION_WORK',
+    'REMEDIATION_REQUIRED_CUSTOMER_UNWILLING_TO_WAIT',
+]);
+// ──────────────────────────────────────────────────────────────────────
+// Convenience predicate
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * A cancellation counts as a fulfilment failure iff its CancellationReason
+ * is NOT a recontract side-effect AND NOT a data-hygiene cleanup. Customer-
+ * and supplier-cause cancellations DO count — the customer didn't get
+ * serviced today. Unknown reason → conservative (counts as failure).
+ */
+function isFulfilmentFailureCancel(cancelReason) {
+    if (!cancelReason)
+        return true;
+    if (exports.RECONTRACT_SIDE_EFFECT_CANCEL_REASONS.has(cancelReason))
+        return false;
+    if (exports.DATA_HYGIENE_CANCEL_REASONS.has(cancelReason))
+        return false;
+    return true;
+}
+exports.isFulfilmentFailureCancel = isFulfilmentFailureCancel;
+// ──────────────────────────────────────────────────────────────────────
+// Coverage helpers — surface drift between the SDK enum and these sets
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * Returns enum values from `allKnownValues` not classified into any
+ * operational set. Callers pass `Object.values(ChangeReasonRescheduleReason)`
+ * so this stays free of a hard enum import while still enabling drift checks.
+ */
+function unclassifiedRescheduleReasons(allKnownValues) {
+    const classified = new Set([
+        ...exports.TENANT_PENDING_RESCHEDULE_REASONS,
+        ...exports.CUSTOMER_FOLLOWUP_RESCHEDULE_REASONS,
+        ...exports.MISSELLING_RESCHEDULE_REASONS,
+        ...exports.SUPPLIER_SIDE_CAUSE_RESCHEDULE_REASONS,
+        ...exports.INTRA_TODAY_RESCHEDULE_REASONS,
+    ]);
+    return allKnownValues.filter((v) => !classified.has(v));
+}
+exports.unclassifiedRescheduleReasons = unclassifiedRescheduleReasons;
+function unclassifiedCancelReasons(allKnownValues) {
+    const classified = new Set([
+        ...exports.RECONTRACT_SIDE_EFFECT_CANCEL_REASONS,
+        ...exports.DATA_HYGIENE_CANCEL_REASONS,
+        ...exports.CHURN_CANCEL_REASONS,
+        ...exports.SUPPLIER_SIDE_CAUSE_CANCEL_REASONS,
+        ...exports.CUSTOMER_SIDE_CAUSE_CANCEL_REASONS,
+    ]);
+    return allKnownValues.filter((v) => !classified.has(v));
+}
+exports.unclassifiedCancelReasons = unclassifiedCancelReasons;

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

@@ -25,11 +25,14 @@
  *
  * Linked: T-20260508-009 / T-20260508-010
  */
-export type { WholesaleProvider, CreateOrderOptions, CancellationReasonCode, ReserveAppointmentArgs, ListAppointmentsArgs, ScheduleServiceWorkOrderArgs, RescheduleServiceWorkOrderArgs, AmendAppointmentArgs, SyncWorkOrderToSupplierArgs, UpdateOrderExternalRefArgs, } from './interface';
+export type { WholesaleProvider, CreateOrderOptions, CancellationReasonCode, CancelServiceWorkOrderArgs, ReserveAppointmentArgs, ListAppointmentsArgs, ScheduleServiceWorkOrderArgs, RescheduleServiceWorkOrderArgs, AmendAppointmentArgs, SyncWorkOrderToSupplierArgs, UpdateOrderExternalRefArgs, } from './interface';
 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, YfKciSemanticOp, YfKciEffectKind, YfKciTargetEntity, YfKciEffect, KciEffectRow, KciDispatchDecision, } from './kci-effect-bridge';
+export { INSTALL_STAGE_KCI_SOURCES, buildInstallStageReasonCodeSpecs, } from './install-stage-kci-spec';
+export type { InstallStageKciSource, InstallStageReasonCodeSpec, } from './install-stage-kci-spec';
+export { BILLING_BLOCKED_RESCHEDULE_REASONS, TENANT_PENDING_RESCHEDULE_REASONS, CUSTOMER_FOLLOWUP_RESCHEDULE_REASONS, MISSELLING_RESCHEDULE_REASONS, SUPPLIER_SIDE_CAUSE_RESCHEDULE_REASONS, INTRA_TODAY_RESCHEDULE_REASONS, RECONTRACT_SIDE_EFFECT_CANCEL_REASONS, DATA_HYGIENE_CANCEL_REASONS, CHURN_CANCEL_REASONS, SUPPLIER_SIDE_CAUSE_CANCEL_REASONS, CUSTOMER_SIDE_CAUSE_CANCEL_REASONS, isFulfilmentFailureCancel, unclassifiedRescheduleReasons, unclassifiedCancelReasons, } from './change-reason-classifications';
 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,7 +41,7 @@ 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.detectKciKind = exports.decideKciDispatch = exports.KCI_EFFECT_ROWS = exports.AggregateNotificationError = exports.NetomniaProvider = void 0;
+exports.unclassifiedCancelReasons = exports.unclassifiedRescheduleReasons = exports.isFulfilmentFailureCancel = exports.CUSTOMER_SIDE_CAUSE_CANCEL_REASONS = exports.SUPPLIER_SIDE_CAUSE_CANCEL_REASONS = exports.CHURN_CANCEL_REASONS = exports.DATA_HYGIENE_CANCEL_REASONS = exports.RECONTRACT_SIDE_EFFECT_CANCEL_REASONS = exports.INTRA_TODAY_RESCHEDULE_REASONS = exports.SUPPLIER_SIDE_CAUSE_RESCHEDULE_REASONS = exports.MISSELLING_RESCHEDULE_REASONS = exports.CUSTOMER_FOLLOWUP_RESCHEDULE_REASONS = exports.TENANT_PENDING_RESCHEDULE_REASONS = exports.BILLING_BLOCKED_RESCHEDULE_REASONS = exports.buildInstallStageReasonCodeSpecs = exports.INSTALL_STAGE_KCI_SOURCES = 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; } });
@@ -51,6 +51,25 @@ 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; } });
+// ── Install Fulfilment digest BP inputs (published projections) ───────
+var install_stage_kci_spec_1 = require("./install-stage-kci-spec");
+Object.defineProperty(exports, "INSTALL_STAGE_KCI_SOURCES", { enumerable: true, get: function () { return install_stage_kci_spec_1.INSTALL_STAGE_KCI_SOURCES; } });
+Object.defineProperty(exports, "buildInstallStageReasonCodeSpecs", { enumerable: true, get: function () { return install_stage_kci_spec_1.buildInstallStageReasonCodeSpecs; } });
+var change_reason_classifications_1 = require("./change-reason-classifications");
+Object.defineProperty(exports, "BILLING_BLOCKED_RESCHEDULE_REASONS", { enumerable: true, get: function () { return change_reason_classifications_1.BILLING_BLOCKED_RESCHEDULE_REASONS; } });
+Object.defineProperty(exports, "TENANT_PENDING_RESCHEDULE_REASONS", { enumerable: true, get: function () { return change_reason_classifications_1.TENANT_PENDING_RESCHEDULE_REASONS; } });
+Object.defineProperty(exports, "CUSTOMER_FOLLOWUP_RESCHEDULE_REASONS", { enumerable: true, get: function () { return change_reason_classifications_1.CUSTOMER_FOLLOWUP_RESCHEDULE_REASONS; } });
+Object.defineProperty(exports, "MISSELLING_RESCHEDULE_REASONS", { enumerable: true, get: function () { return change_reason_classifications_1.MISSELLING_RESCHEDULE_REASONS; } });
+Object.defineProperty(exports, "SUPPLIER_SIDE_CAUSE_RESCHEDULE_REASONS", { enumerable: true, get: function () { return change_reason_classifications_1.SUPPLIER_SIDE_CAUSE_RESCHEDULE_REASONS; } });
+Object.defineProperty(exports, "INTRA_TODAY_RESCHEDULE_REASONS", { enumerable: true, get: function () { return change_reason_classifications_1.INTRA_TODAY_RESCHEDULE_REASONS; } });
+Object.defineProperty(exports, "RECONTRACT_SIDE_EFFECT_CANCEL_REASONS", { enumerable: true, get: function () { return change_reason_classifications_1.RECONTRACT_SIDE_EFFECT_CANCEL_REASONS; } });
+Object.defineProperty(exports, "DATA_HYGIENE_CANCEL_REASONS", { enumerable: true, get: function () { return change_reason_classifications_1.DATA_HYGIENE_CANCEL_REASONS; } });
+Object.defineProperty(exports, "CHURN_CANCEL_REASONS", { enumerable: true, get: function () { return change_reason_classifications_1.CHURN_CANCEL_REASONS; } });
+Object.defineProperty(exports, "SUPPLIER_SIDE_CAUSE_CANCEL_REASONS", { enumerable: true, get: function () { return change_reason_classifications_1.SUPPLIER_SIDE_CAUSE_CANCEL_REASONS; } });
+Object.defineProperty(exports, "CUSTOMER_SIDE_CAUSE_CANCEL_REASONS", { enumerable: true, get: function () { return change_reason_classifications_1.CUSTOMER_SIDE_CAUSE_CANCEL_REASONS; } });
+Object.defineProperty(exports, "isFulfilmentFailureCancel", { enumerable: true, get: function () { return change_reason_classifications_1.isFulfilmentFailureCancel; } });
+Object.defineProperty(exports, "unclassifiedRescheduleReasons", { enumerable: true, get: function () { return change_reason_classifications_1.unclassifiedRescheduleReasons; } });
+Object.defineProperty(exports, "unclassifiedCancelReasons", { enumerable: true, get: function () { return change_reason_classifications_1.unclassifiedCancelReasons; } });
 // ── Reference types (re-exported — not on WholesaleProvider surface) ──
 //
 // FibreCafe wire-format types — useful for module-level DTO consolidation

package/dist/wholesale-provider/install-stage-kci-spec.d.ts

@@ -0,0 +1,26 @@
+export interface InstallStageKciSource {
+    /** WorkOrder stage key (e.g. 'WorkOrderStageScheduled'). */
+    readonly stageKey: string;
+    /** Human-readable stage name (e.g. 'Scheduled'). */
+    readonly stageName: string;
+    /** Bridge row ids whose KCI drives entry into this stage. */
+    readonly kciSourceRowIds: readonly string[];
+}
+/**
+ * Frozen projection of INSTALL_PROCESS.stages (install.ts) — only stages
+ * with at least one kciSource-bearing entryAction. Verified against the
+ * live BP on 2026-05-20.
+ */
+export declare const INSTALL_STAGE_KCI_SOURCES: readonly InstallStageKciSource[];
+export interface InstallStageReasonCodeSpec {
+    readonly stageKey: string;
+    readonly stageName: string;
+    /** Distinct supplier KCI reasonCodes that drive entry into this stage. */
+    readonly expectedReasonCodes: readonly string[];
+}
+/**
+ * Resolve `INSTALL_STAGE_KCI_SOURCES` rowIds → distinct reasonCodes via
+ * `KCI_EFFECT_ROWS`. Stages whose rowIds resolve to no reasonCode are
+ * dropped (matches the digest's `reasonSet.size === 0` skip).
+ */
+export declare function buildInstallStageReasonCodeSpecs(): InstallStageReasonCodeSpec[];

package/dist/wholesale-provider/install-stage-kci-spec.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildInstallStageReasonCodeSpecs = exports.INSTALL_STAGE_KCI_SOURCES = void 0;
+/**
+ * INSTALL work-order stage → expected supplier-KCI reasonCode spec.
+ *
+ * The Install Fulfilment digest's "KCI audit by stage" needs, per INSTALL
+ * WO stage, the set of supplier KCI `reasonCode`s that legitimately drive
+ * entry into that stage. That mapping is a projection of the typed BP
+ * template `business-processes/install.ts` (agent-os authoring origin):
+ * for each stage, its `entryActions[].kciSource.rowId` resolved against
+ * `KCI_EFFECT_ROWS` (the canonical bridge catalog, already in this SDK).
+ *
+ * `INSTALL_STAGE_KCI_SOURCES` below is the frozen projection of
+ * `INSTALL_PROCESS.stages[].entryActions[].kciSource.rowId`, extracted
+ * mechanically from install.ts. If the BP rewires a stage's kciSource,
+ * regenerate this array (it is the published copy, not a re-derivation).
+ *
+ * `buildInstallStageReasonCodeSpecs()` resolves the rowIds → reasonCodes via
+ * `KCI_EFFECT_ROWS` so consumers never hand-map rowId→reasonCode themselves.
+ */
+const kci_effect_bridge_1 = require("./kci-effect-bridge");
+/**
+ * Frozen projection of INSTALL_PROCESS.stages (install.ts) — only stages
+ * with at least one kciSource-bearing entryAction. Verified against the
+ * live BP on 2026-05-20.
+ */
+exports.INSTALL_STAGE_KCI_SOURCES = [
+    {
+        stageKey: 'WorkOrderStageScheduled',
+        stageName: 'Scheduled',
+        kciSourceRowIds: ['provide-reappointed', 'provide-amended'],
+    },
+    {
+        stageKey: 'WorkOrderStageEnRoute',
+        stageName: 'En Route',
+        kciSourceRowIds: ['provide-update-install-en-route'],
+    },
+    {
+        stageKey: 'WorkOrderStageInProgress',
+        stageName: 'In Progress',
+        kciSourceRowIds: ['provide-update-install-in-progress', 'provide-resolved'],
+    },
+    {
+        stageKey: 'WorkOrderRemediationRequired',
+        stageName: 'Remediation Required',
+        kciSourceRowIds: ['provide-delay'],
+    },
+    {
+        stageKey: 'CustomerWorkOrdersStagePending',
+        stageName: 'Pending',
+        kciSourceRowIds: [
+            'provide-information-required',
+            'provide-contact-customer',
+            'provide-contact-reappoint',
+            'provide-reappoint',
+        ],
+    },
+    {
+        stageKey: 'WorkOrderStageDone',
+        stageName: 'Done',
+        kciSourceRowIds: ['provide-completed', 'provide-partial'],
+    },
+    {
+        stageKey: 'WorkOrderStageCancelled',
+        stageName: 'Cancelled',
+        kciSourceRowIds: [
+            'provide-cancelled',
+            'provide-failed',
+            'provide-rejected',
+            'provide-order-rejected',
+        ],
+    },
+];
+/**
+ * Resolve `INSTALL_STAGE_KCI_SOURCES` rowIds → distinct reasonCodes via
+ * `KCI_EFFECT_ROWS`. Stages whose rowIds resolve to no reasonCode are
+ * dropped (matches the digest's `reasonSet.size === 0` skip).
+ */
+function buildInstallStageReasonCodeSpecs() {
+    const rowIdToReason = new Map();
+    for (const r of kci_effect_bridge_1.KCI_EFFECT_ROWS)
+        rowIdToReason.set(r.id, r.reasonCode);
+    const out = [];
+    for (const stage of exports.INSTALL_STAGE_KCI_SOURCES) {
+        const reasonSet = new Set();
+        for (const rowId of stage.kciSourceRowIds) {
+            const rc = rowIdToReason.get(rowId);
+            if (rc)
+                reasonSet.add(rc);
+        }
+        if (reasonSet.size === 0)
+            continue;
+        out.push({
+            stageKey: stage.stageKey,
+            stageName: stage.stageName,
+            expectedReasonCodes: [...reasonSet],
+        });
+    }
+    return out;
+}
+exports.buildInstallStageReasonCodeSpecs = buildInstallStageReasonCodeSpecs;

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

@@ -30,7 +30,7 @@
  * full types are available).
  */
 import type { VMO2OrderNotification, VMO2SMRNotification } from './types/vmo2';
-import type { FibreCafeServiceAvailability200, FibreCafeAvailableAppointments200, FibreCafeReserveAppointment201, FibreCafeScheduleServiceWorkOrder201, FibreCafeRescheduleServiceWorkOrder200, FibreCafeOrderCreate202, FibreCafeOrderAmendAccept202, FibreCafeKciDto } from './types/fibrecafe';
+import type { FibreCafeServiceAvailability200, FibreCafeAvailableAppointments200, FibreCafeReserveAppointment201, FibreCafeScheduleServiceWorkOrder201, FibreCafeRescheduleServiceWorkOrder200, FibreCafeOrderCreate202, FibreCafeOrderAmendAccept202, FibreCafeKciDto, FibreCafeServiceProblemCancellationReasonCode } from './types/fibrecafe';
 /**
  * Reasons a cancellation request can be made (NET wire-level enum value
  * passed through to the FibreCafe gateway).
@@ -107,6 +107,33 @@ export interface UpdateOrderExternalRefArgs {
     oldYfId: string;
     newYfId: string;
 }
+/**
+ * Args for the tenant-initiated cancellation of an inflight SERVICE WO
+ * (REPAIR). Structurally identical to `RescheduleServiceWorkOrderArgs` —
+ * cancel is the same action shape as reschedule, just a terminal
+ * transition instead of a slot move. Same flat primitive fields; only
+ * delta is `reasonCode` in place of the timeslot fields (mirrors how
+ * `cancelOrder` carries a `reasonCode` while `createOrder` doesn't).
+ *
+ * The provider impl posts to
+ * `POST /WholesaleGateway/v1.0/gateway/service-work-orders/cancel`. NET
+ * looks up its SERVICE WO by `externalId = yfWorkOrderId` (NET stamps
+ * the YF WO uuid as externalId at create time per
+ * `scheduleServiceWorkOrder`), then drives the NET WO to Cancelled via
+ * NET field-service `/cancel-action-apply` with a tenant-originated
+ * ChangeReason. The existing SERVICE WO stage-update handler emits the
+ * UPDATE+`NETOMNIA_SERVICE_WORK_ORDER_CANCELLED` KCI back to YF.
+ *
+ * YF only commits its own SERVICE WO → Cancelled transition after this
+ * call resolves successfully (NET-first semantics — see
+ * `CancelServiceWorkOrderTenantService` in field-service module).
+ */
+export interface CancelServiceWorkOrderArgs {
+    yfWorkOrderId: string;
+    uprn: number;
+    yfOrderId: string;
+    reasonCode: FibreCafeServiceProblemCancellationReasonCode;
+}
 /**
  * Capability-shaped interface to a wholesale supplier. Method NAMES align
  * with VMO2 spec where it makes sense; ARGS match existing NET module
@@ -154,6 +181,20 @@ export interface WholesaleProvider<TPrincipal = unknown> {
     cancelOrder(yfOrderId: string, reasonCode: CancellationReasonCode): Promise<FibreCafeOrderCreate202>;
     /** Active-customer cease (post-Active churn / OTS-losing). */
     ceaseOrder(yfOrderId: string, serviceId: string): Promise<FibreCafeOrderCreate202>;
+    /**
+     * Tenant-initiated cancel of an inflight SERVICE WO. Structurally
+     * parallel to `rescheduleServiceWorkOrder` — same flat-primitive args,
+     * same response envelope shape, just a terminal transition instead of
+     * a slot move.
+     *
+     * **YF must NOT transition its SERVICE WO to Cancelled until this call
+     * resolves successfully** — the call site (`CancelServiceWorkOrderTenant
+     * Service` in field-service module) is responsible for gating the YF
+     * stage change on the response. The inbound UPDATE+CANCELLED KCI from
+     * NET (walker row `repair-update-service-cancelled`) is the secondary
+     * cure when YF didn't already advance.
+     */
+    cancelServiceWorkOrder(args: CancelServiceWorkOrderArgs): Promise<FibreCafeRescheduleServiceWorkOrder200>;
     /**
      * Inbound supplier KCI handler — the ONE inbound channel from supplier
      * to YF. KCIs drive (a) OrderKci persistence and (b) WO state changes

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

@@ -24,7 +24,25 @@
  * 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';
+/**
+ * Discriminator for the BUSINESS KIND of a KCI — not the wire envelope shape.
+ *
+ *   PROVIDE / CEASE / MODIFY / UNSOLICITED_CEASE — typed by the populated
+ *     sub-body field on the FibreCafe envelope (`provideServiceOrder` etc.).
+ *
+ *   REPAIR — SERVICE WorkOrder state changes. NET emits these on the parent
+ *     PROVIDE envelope (the SERVICE WO is a child of the PROVIDE order in
+ *     the data model) but the semantic kind is REPAIR, discriminated by a
+ *     `NETOMNIA_SERVICE_WORK_ORDER_*` value in `supplierCodes[]`. The
+ *     envelope wire shape is a data-model artifact; the BP vocabulary is
+ *     what consumers reason about (SERVICE WO = repair / service visit).
+ *
+ * `detectKciKind()` returns REPAIR when ANY supplier code matches the
+ * `NETOMNIA_SERVICE_WORK_ORDER_*` prefix, taking precedence over the
+ * envelope-field-based PROVIDE detection so service-WO KCIs route to the
+ * REPAIR-marked bridge rows.
+ */
+export declare type KciServiceOrderKind = 'PROVIDE' | 'CEASE' | 'MODIFY' | 'UNSOLICITED_CEASE' | 'REPAIR';
 export declare type YfKciEffectKind = 'LOG_KCI_ONLY' | 'WO_FLOW_ACTION' | 'WO_SCHEDULE_APPOINTMENT' | 'PROPERTY_WRITE' | 'NO_OP_DOCUMENTED';
 export declare type YfKciTargetEntity = 'OrderModule:Order' | 'CrmModule:Address' | 'FieldServiceModule:WorkOrder';
 /**

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

@@ -321,11 +321,19 @@ exports.KCI_EFFECT_ROWS = [
         },
         logAgainstOrder: true,
     },
-    // SERVICE WO
-    {
-        id: 'provide-update-service-scheduled',
+    // ═══════════════════════════════════════════════════════════════════
+    //  REPAIR — SERVICE WO state changes (post-install fault / service visit)
+    //
+    //  NET emits these on the parent PROVIDE envelope (data-model artifact:
+    //  SERVICE WO is a child of the PROVIDE order). The semantic kind is
+    //  REPAIR — discriminated by a `NETOMNIA_SERVICE_WORK_ORDER_*` value in
+    //  `supplierCodes[]`. `detectKciKind()` recognises that prefix and
+    //  returns REPAIR ahead of the envelope-field-based PROVIDE detection.
+    // ═══════════════════════════════════════════════════════════════════
+    {
+        id: 'repair-update-service-scheduled',
         reasonCode: 'UPDATE',
-        serviceOrderKind: 'PROVIDE',
+        serviceOrderKind: 'REPAIR',
         supplierCodes: ['NETOMNIA_SERVICE_WORK_ORDER_SCHEDULED'],
         yfEffect: {
             kind: 'LOG_KCI_ONLY',
@@ -334,9 +342,9 @@ exports.KCI_EFFECT_ROWS = [
         logAgainstOrder: true,
     },
     {
-        id: 'provide-update-service-en-route',
+        id: 'repair-update-service-en-route',
         reasonCode: 'UPDATE',
-        serviceOrderKind: 'PROVIDE',
+        serviceOrderKind: 'REPAIR',
         supplierCodes: ['NETOMNIA_SERVICE_WORK_ORDER_EN_ROUTE'],
         yfEffect: {
             kind: 'WO_FLOW_ACTION',
@@ -346,9 +354,9 @@ exports.KCI_EFFECT_ROWS = [
         logAgainstOrder: true,
     },
     {
-        id: 'provide-update-service-in-progress',
+        id: 'repair-update-service-in-progress',
         reasonCode: 'UPDATE',
-        serviceOrderKind: 'PROVIDE',
+        serviceOrderKind: 'REPAIR',
         supplierCodes: ['NETOMNIA_SERVICE_WORK_ORDER_IN_PROGRESS'],
         yfEffect: {
             kind: 'WO_FLOW_ACTION',
@@ -448,12 +456,38 @@ exports.KCI_EFFECT_ROWS = [
         },
         logAgainstOrder: true,
     },
+    // SERVICE-WO cancel — same REPAIR-kind UPDATE-with-supplierCode pattern
+    // as the scheduled / en-route / in-progress rows above. NET enum value:
+    // NETOMNIA_SERVICE_WORK_ORDER_CANCELLED (netomnia-supplier-code.enum.ts).
+    // Dispatcher resolves the cancel semanticOp per WO.type —
+    // SERVICE → CancelServiceWorkOrderFlowSupplier.
+    {
+        id: 'repair-update-service-cancelled',
+        reasonCode: 'UPDATE',
+        serviceOrderKind: 'REPAIR',
+        supplierCodes: ['NETOMNIA_SERVICE_WORK_ORDER_CANCELLED'],
+        yfEffect: {
+            kind: 'WO_FLOW_ACTION',
+            semanticOp: 'cancel',
+            notes: 'SERVICE WO cancelled by supplier — advance YF SERVICE WO Accepted/Scheduled/EnRoute/InProgress → Cancelled via CancelServiceWorkOrderFlowSupplier. Also the inbound confirmation when YF tenant-initiated the cancel via /WholesaleGateway/v1.0/gateway/service-work-orders/cancel; YF WO usually already at Cancelled, action is idempotent on the WO stage.',
+        },
+        logAgainstOrder: true,
+    },
 ];
 /**
  * Determine which serviceOrder kind the KCI is about by inspecting which
  * sub-body field is populated.
  */
 function detectKciKind(dto) {
+    var _a;
+    // REPAIR check first — SERVICE WO state changes use the NETOMNIA_SERVICE_
+    // WORK_ORDER_* supplier-code discriminator, regardless of which sub-body
+    // field is populated (it's typically `provideServiceOrder` because the
+    // SERVICE WO is a child of a PROVIDE order in the data model).
+    const codes = (_a = dto.supplierCodes) !== null && _a !== void 0 ? _a : [];
+    if (codes.some((c) => c.startsWith('NETOMNIA_SERVICE_WORK_ORDER_'))) {
+        return 'REPAIR';
+    }
     if (dto.provideServiceOrder)
         return 'PROVIDE';
     if (dto.ceaseServiceOrder)

package/dist/wholesale-provider/providers/netomnia-provider.d.ts

@@ -27,7 +27,7 @@
  * invokes `dispatchOrderNotification` / `dispatchSMRNotification` after
  * envelope-mapping; registered handlers are fanned out.
  */
-import type { WholesaleProvider, CreateOrderOptions, CancellationReasonCode, ReserveAppointmentArgs, ListAppointmentsArgs, ScheduleServiceWorkOrderArgs, RescheduleServiceWorkOrderArgs, AmendAppointmentArgs, SyncWorkOrderToSupplierArgs, UpdateOrderExternalRefArgs } from '../interface';
+import type { WholesaleProvider, CreateOrderOptions, CancellationReasonCode, CancelServiceWorkOrderArgs, ReserveAppointmentArgs, ListAppointmentsArgs, ScheduleServiceWorkOrderArgs, RescheduleServiceWorkOrderArgs, AmendAppointmentArgs, SyncWorkOrderToSupplierArgs, UpdateOrderExternalRefArgs } from '../interface';
 import type { VMO2OrderNotification, VMO2SMRNotification } from '../types/vmo2';
 import type { FibreCafeServiceAvailability200, FibreCafeAvailableAppointments200, FibreCafeReserveAppointment201, FibreCafeScheduleServiceWorkOrder201, FibreCafeRescheduleServiceWorkOrder200, FibreCafeOrderCreate202, FibreCafeOrderAmendAccept202, FibreCafeKciDto } from '../types/fibrecafe';
 /**
@@ -60,6 +60,7 @@ export interface NetomniaProviderDeps<TPrincipal = unknown, TKci = FibreCafeKciD
     amendOrder: (principal: TPrincipal, yfOrderId: string) => Promise<FibreCafeOrderCreate202 | null>;
     cancelOrder: (yfOrderId: string, reasonCode: CancellationReasonCode) => Promise<FibreCafeOrderCreate202>;
     ceaseOrder: (yfOrderId: string, serviceId: string) => Promise<FibreCafeOrderCreate202>;
+    cancelServiceWorkOrder: (args: CancelServiceWorkOrderArgs) => Promise<FibreCafeRescheduleServiceWorkOrder200>;
     receiveKci: (principal: TPrincipal, dto: FibreCafeKciDto) => Promise<void>;
     syncWorkOrderToSupplier: (args: SyncWorkOrderToSupplierArgs<TPrincipal>) => Promise<void>;
     retrieveServiceIdByUprn: (uprn: number) => Promise<string | null>;
@@ -82,6 +83,7 @@ export declare class NetomniaProvider<TPrincipal = unknown> implements Wholesale
     amendOrder(principal: TPrincipal, yfOrderId: string): Promise<FibreCafeOrderCreate202>;
     cancelOrder(yfOrderId: string, reasonCode: CancellationReasonCode): Promise<FibreCafeOrderCreate202>;
     ceaseOrder(yfOrderId: string, serviceId: string): Promise<FibreCafeOrderCreate202>;
+    cancelServiceWorkOrder(args: CancelServiceWorkOrderArgs): Promise<FibreCafeRescheduleServiceWorkOrder200>;
     receiveKci(principal: TPrincipal, dto: FibreCafeKciDto): Promise<void>;
     syncWorkOrderToSupplier(args: SyncWorkOrderToSupplierArgs<TPrincipal>): Promise<void>;
     retrieveServiceIdByUprn(uprn: number): Promise<string>;

package/dist/wholesale-provider/providers/netomnia-provider.js

@@ -47,6 +47,9 @@ class NetomniaProvider {
     ceaseOrder(yfOrderId, serviceId) {
         return this.deps.ceaseOrder(yfOrderId, serviceId);
     }
+    cancelServiceWorkOrder(args) {
+        return this.deps.cancelServiceWorkOrder(args);
+    }
     receiveKci(principal, dto) {
         return this.deps.receiveKci(principal, dto);
     }

package/dist/wholesale-provider/test/netomnia-provider.spec.js

@@ -71,6 +71,7 @@ function buildDeps() {
         amendOrder: {},
         cancelOrder: {},
         ceaseOrder: {},
+        cancelServiceWorkOrder: { workOrderId: 'WO-CANC-1', appointmentId: '' },
     };
     const deps = {
         searchAddress: (uprn) => {
@@ -113,6 +114,10 @@ function buildDeps() {
             log.push({ method: 'ceaseOrder', args: [yfOrderId, serviceId] });
             return Promise.resolve(stubs.ceaseOrder);
         },
+        cancelServiceWorkOrder: (args) => {
+            log.push({ method: 'cancelServiceWorkOrder', args: [args] });
+            return Promise.resolve(stubs.cancelServiceWorkOrder);
+        },
         receiveKci: (principal, dto) => {
             log.push({ method: 'receiveKci', args: [principal, dto] });
             return Promise.resolve();

package/dist/wholesale-provider/types/fibrecafe.d.ts

@@ -430,6 +430,21 @@ export interface FibreCafeModifyServiceOrder {
     serviceOrderCancellationId?: string | number;
     serviceOrderCancellationReference?: string;
 }
+/**
+ * Codes representing the reason for cancelling an inflight service problem
+ * (FibreCafe `POST /service-problem-cancellations` request body). Used on
+ * the OUTBOUND (YF → NET) side for the tenant-initiated SERVICE WO cancel.
+ *
+ * The corresponding INBOUND state-change (NET → YF) confirming the
+ * cancellation is emitted by NET as an `UPDATE` KCI with
+ * `supplierCodes: [NETOMNIA_SERVICE_WORK_ORDER_CANCELLED]` — see the
+ * `provide-update-service-cancelled` row in kci-effect-bridge.ts.
+ *
+ * Mirrors NET's `ServiceProblemCancellationReasonCode` enum verbatim.
+ *
+ * @see {@link https://docs.thefibrecafe.net/openapi/supplier/operation/handleCancelProblem/#!path=reasonCode&t=request | FibreCafe ServiceProblemCancellationReasonCode}
+ */
+export declare type FibreCafeServiceProblemCancellationReasonCode = 'ISSUE_RESOLVED' | 'CUSTOMER_NETWORK_ISSUE' | 'NO_LONGER_REQUIRED' | 'OTHER';
 /** Unsolicited cease — supplier-initiated, surfaced via KCI. */
 export interface FibreCafeUnsolicitedCeaseServiceOrder {
     orderType?: FibreCafeCeaseOrderType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d19n/youfibre-odin-sdk",
-  "version": "2.0.151",
+  "version": "2.0.157",
   "description": "",
   "author": "@d19n",
   "license": "UNLICENSED",