@webex/contact-center 3.13.0-next.1 → 3.13.0-next.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/.repo-context.json +704 -0
  2. package/.sdd/manifest.json +1065 -339
  3. package/AGENTS.md +935 -60
  4. package/dist/webex.js +1 -1
  5. package/docs/adr/0001-spec-source-policy.md +97 -0
  6. package/{ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md → docs/adr/0002-consult-transfer-list-policy.md} +227 -244
  7. package/docs/adr/0003-repo-standards-migration.md +104 -0
  8. package/docs/adr/index.md +35 -0
  9. package/docs/architecture.md +460 -0
  10. package/docs/getting-started.md +142 -0
  11. package/docs/index.md +53 -0
  12. package/docs/specs/README.md +98 -0
  13. package/package.json +10 -9
  14. package/schemas/repo-context.schema.json +796 -0
  15. package/src/docs/README.md +727 -0
  16. package/src/metrics/docs/README.md +710 -0
  17. package/src/services/agent/docs/README.md +673 -0
  18. package/src/services/config/docs/README.md +530 -0
  19. package/src/services/core/docs/README.md +993 -0
  20. package/src/services/docs/README.md +765 -0
  21. package/src/services/task/docs/README.md +1569 -0
  22. package/src/services/task/state-machine/docs/README.md +1388 -0
  23. package/src/utils/AGENTS.md +6 -4
  24. package/src/utils/docs/README.md +413 -0
  25. package/umd/contact-center.min.js +2 -2
  26. package/umd/contact-center.min.js.map +1 -1
  27. package/ai-docs/ARCHITECTURE.md +0 -168
  28. package/ai-docs/CONTRACTS.md +0 -64
  29. package/ai-docs/GETTING_STARTED.md +0 -168
  30. package/ai-docs/GLOSSARY.md +0 -43
  31. package/ai-docs/README.md +0 -138
  32. package/ai-docs/REVIEW_CHECKLIST.md +0 -41
  33. package/ai-docs/RULES.md +0 -444
  34. package/ai-docs/SECURITY.md +0 -52
  35. package/ai-docs/SERVICE_STATE.md +0 -52
  36. package/ai-docs/SPEC_INDEX.md +0 -65
  37. package/ai-docs/adr/0001-spec-source-policy.md +0 -55
  38. package/ai-docs/adr/README.md +0 -8
  39. package/ai-docs/adr/_adr-template.md +0 -31
  40. package/ai-docs/contact-center-spec.md +0 -388
  41. package/ai-docs/features/contact-owner-change-refactor.md +0 -78
  42. package/ai-docs/features/generated-spec-conformance-fidelity-remediation/spec/feature-spec.md +0 -117
  43. package/ai-docs/features/residual-warning-coverage-completion/spec/feature-spec.md +0 -203
  44. package/ai-docs/features/validator-code-fidelity-drift-fix/spec/feature-spec.md +0 -315
  45. package/ai-docs/patterns/event-driven-patterns.md +0 -485
  46. package/ai-docs/patterns/testing-patterns.md +0 -480
  47. package/ai-docs/patterns/typescript-patterns.md +0 -365
  48. package/ai-docs/templates/README.md +0 -102
  49. package/ai-docs/templates/documentation/create-agents-md.md +0 -240
  50. package/ai-docs/templates/documentation/create-architecture-md.md +0 -295
  51. package/ai-docs/templates/existing-service/bug-fix.md +0 -254
  52. package/ai-docs/templates/existing-service/feature-enhancement.md +0 -450
  53. package/ai-docs/templates/new-method/00-master.md +0 -80
  54. package/ai-docs/templates/new-method/01-requirements.md +0 -232
  55. package/ai-docs/templates/new-method/02-implementation.md +0 -295
  56. package/ai-docs/templates/new-method/03-tests.md +0 -201
  57. package/ai-docs/templates/new-method/04-validation.md +0 -141
  58. package/ai-docs/templates/new-service/00-master.md +0 -109
  59. package/ai-docs/templates/new-service/01-pre-questions.md +0 -159
  60. package/ai-docs/templates/new-service/02-code-generation.md +0 -346
  61. package/ai-docs/templates/new-service/03-integration.md +0 -178
  62. package/ai-docs/templates/new-service/04-test-generation.md +0 -205
  63. package/ai-docs/templates/new-service/05-validation.md +0 -145
  64. package/src/metrics/ai-docs/AGENTS.md +0 -350
  65. package/src/metrics/ai-docs/ARCHITECTURE.md +0 -338
  66. package/src/metrics/ai-docs/metrics-spec.md +0 -971
  67. package/src/services/agent/ai-docs/AGENTS.md +0 -240
  68. package/src/services/agent/ai-docs/ARCHITECTURE.md +0 -304
  69. package/src/services/agent/ai-docs/agent-spec.md +0 -505
  70. package/src/services/ai-docs/AGENTS.md +0 -386
  71. package/src/services/ai-docs/services-spec.md +0 -512
  72. package/src/services/config/ai-docs/AGENTS.md +0 -250
  73. package/src/services/config/ai-docs/ARCHITECTURE.md +0 -413
  74. package/src/services/config/ai-docs/config-spec.md +0 -669
  75. package/src/services/core/ai-docs/AGENTS.md +0 -381
  76. package/src/services/core/ai-docs/ARCHITECTURE.md +0 -698
  77. package/src/services/core/ai-docs/core-spec.md +0 -797
  78. package/src/services/task/ai-docs/AGENTS.md +0 -457
  79. package/src/services/task/ai-docs/ARCHITECTURE.md +0 -595
  80. package/src/services/task/ai-docs/task-spec.md +0 -1501
  81. package/src/services/task/state-machine/ai-docs/AGENTS.md +0 -460
  82. package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md +0 -1156
  83. package/src/services/task/state-machine/ai-docs/task-state-machine-spec.md +0 -2247
  84. package/src/utils/ai-docs/utils-spec.md +0 -391
@@ -1,54 +1,54 @@
1
1
  ---
2
- type: Feature Spec
3
- title: Consult and transfer list policy
4
- description: Centralize consult and transfer destination eligibility, request shaping, ordering, and cache policy in the Contact Center SDK.
5
- tags: [feature, specification, contact-center, consult-transfer]
2
+ type: ADR
3
+ title: ADR-0002 - Consult and transfer list policy
4
+ description: The SDK owns the default consult and transfer destination policy (eligibility, request shaping, backend ordering, cache safety, and Task destination controls) on its existing list and transfer methods.
5
+ tags: [adr]
6
+ timestamp: 2026-08-19T00:00:00Z
7
+ status: accepted
6
8
  ---
7
-
8
- # Consult and transfer list policy
9
+ <!-- sdd-generated-metadata
10
+ doc_kind: standing-doc
11
+ generated_from: adr@0.3.0
12
+ generated_by: claude-code
13
+ approved_by: rarajes2@cisco.com
14
+ updated_at: 2026-11-17T03:03:58Z
15
+ validation_status: pass-with-warnings
16
+ -->
17
+
18
+ # ADR-0002 - Consult and transfer list policy
19
+
20
+ | Field | Value |
21
+ | ------------- | ----- |
22
+ | Status | Accepted |
23
+ | Decision date | 2026-08-19 |
24
+ | Deciders | Contact Center SDK maintainers (developer-approved, 2026-08-19) |
25
+ | Supersedes | N/A |
26
+ | Superseded by | N/A |
27
+
28
+ Related context: [package architecture](../architecture.md) · [specification registry](../specs/README.md) ·
29
+ [package agent instructions](../../AGENTS.md) · [ADR index](index.md)
30
+
31
+ ## Context
9
32
 
10
33
  This document owns the reusable consult/transfer destination-list policy. The SDK applies default telephony eligibility, ordering, profile views, and cache safety through the existing list methods; consumers use compatible existing parameters only when they need a different filter or sort.
11
34
 
12
- Related context: [package architecture](../../../ARCHITECTURE.md) · [specification index](../../../SPEC_INDEX.md) · [package instructions](../../../../AGENTS.md)
13
-
14
- ## Metadata
15
-
16
- | Field | Value |
17
- | --- | --- |
18
- | Feature key | `CAI-8354` |
19
- | Owner | Webex Contact Center SDK maintainers |
20
- | Status | Approved and implemented; diff-scoped drift validation PASS; independent validation pending |
21
- | Work type | Defect |
22
- | Change class | Contract |
23
- | Source/intake | Developer-approved consult/transfer behavior review and current code/tests |
24
- | Last verified | 2026-08-22 in the approved SDK/widgets worktrees |
25
-
26
- ## Applicability
27
-
28
- | Condition ID | Status | Evidence or reason | Owned section |
29
- | --- | --- | --- | --- |
30
- | `feature.feature_nontrivial` | Applicable | `src/cc.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/services/AddressBook.ts`, `src/services/task/Task.ts` | Feasibility and risks |
31
- | `feature.feature_interactions` | Applicable | `src/cc.ts` | Interaction and scenario matrix |
32
- | `feature.touches_data_shapes` | Applicable | `src/types.ts` | Requested data and fields |
33
- | `feature.backward_compat` | Applicable | `src/types.ts`, `src/index.ts` | Migration expectations |
34
- | `feature.perf_critical` | N/A | The change adds no new request fan-out; it corrects cache eligibility for query variants. | Scale and performance |
35
- | `feature.security_compliance` | N/A | Existing host-authenticated request ownership is unchanged and no credentials are added to list inputs. | Security and compliance |
36
- | `feature.needs_rollout` | N/A | No SDK feature flag or staged runtime branch is introduced. | Rollout and feature controls |
37
- | `feature.serviceability` | Applicable | `src/cc.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/services/AddressBook.ts` | Serviceability |
38
- | `feature.doc_obligations` | Applicable | `ai-docs/contact-center-spec.md` | Documentation obligations |
39
- | `feature.changes_ui` | N/A | The SDK has no user-visible screen or navigation ownership. | UI flow and design |
40
- | `feature.changes_api` | Applicable | `src/cc.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/services/AddressBook.ts`, `src/services/task/Task.ts` | API contract delta |
41
- | `feature.changes_events` | N/A | No event name, payload, producer, consumer, or delivery order changes. | Event contract delta |
42
- | `feature.changes_public_api` | Applicable | `src/index.ts`, `src/types.ts` | Public API and semver impact |
43
- | `feature.cross_package` | Applicable | `src/index.ts` | Cross-package impact |
44
-
45
- ## Problem and goal
35
+ This decision was raised as feature key `CAI-8354`, work type Defect, change class Contract, from a
36
+ developer-approved consult/transfer behavior review; the paired change in the Webex widgets repository
37
+ consumes it.
46
38
 
47
39
  Consult/transfer list decisions were split across the SDK and widgets. Generic SDK query types exposed low-level request choices, while widgets always restricted buddy agents to Available, filtered queues after fetching them, rebuilt pagination metadata, and could independently affect presentation order. That produced inconsistent behavior between consumers.
48
40
 
49
41
  The goal is to make the SDK the single owner of the default consult/transfer policy without adding parallel list methods or response signatures. The existing Queue method returns eligible full records, while the existing EntryPoint method maps profile-scoped dial-number rows to the established response wrapper. Queue, EntryPoint, and AddressBook request backend ordering, buddy-agent behavior is action-aware, CMS sort syntax is serialized correctly, and query variants that change results cannot reuse an incompatible cached page. Consumers render the response order and metadata without a second sort or filter.
50
42
 
51
- ## Stakeholders and open questions
43
+ ### Defect context
44
+
45
+ - Observed versus expected behavior: widgets and SDK callers could construct different destination requests, the services serialized sort with keys the CMS list API does not consume, and cache eligibility ignored view/shape flags; expected behavior is one SDK-owned default policy and unchanged backend response order.
46
+ - Reproduction and environment: issue Consult and Transfer destination requests for the same task media and compare query parameters and results across SDK consumers.
47
+ - Regression range or last known good state: unknown; the existing APIs and older query serialization predate the corrected defaults.
48
+ - Severity, frequency, and workaround: user-visible whenever eligibility/order differs; consumers could manually duplicate flags, but that perpetuates the ownership defect.
49
+ - Diagnostic evidence: `src/cc.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/utils/PageCache.ts`.
50
+
51
+ ### Stakeholders
52
52
 
53
53
  | Stakeholder | Need or decision | Status |
54
54
  | --- | --- | --- |
@@ -59,22 +59,44 @@ The goal is to make the SDK the single owner of the default consult/transfer pol
59
59
 
60
60
  There are no open product decisions for this delta.
61
61
 
62
- ## Scope
62
+ ### Prior work and evidence
63
63
 
64
- ### In scope
64
+ | Source | What it establishes | Decision or disposition |
65
+ | --- | --- | --- |
66
+ | `src/cc.ts` | The public façade keeps the established list method names/signatures and owns buddy-agent action policy. | Used |
67
+ | `src/types.ts`, `src/index.ts` | Existing queue/entry-point request and response types remain the public list contracts; entry-point rows expose the mapped dialled number as optional `number`. | Used |
68
+ | `src/services/Queue.ts` | The existing Queue path owns default query serialization and view flags. | Used |
69
+ | `src/services/EntryPoint.ts` | The existing EntryPoint path owns the desktop-profile dial-number query, field mapping, and backend ordering. | Used |
70
+ | `src/services/core/WebexRequest.ts` | The shared request wrapper forwards optional per-request headers needed by the dial-number endpoint while leaving other requests unchanged. | Used |
71
+ | `src/services/AddressBook.ts` | AddressBook owns its backend ordering default and caller override. | Used |
72
+ | `src/utils/PageCache.ts` | Cache eligibility must include every result- or shape-changing query option. | Used |
73
+ | `test/unit/spec/cc.ts` | Action mapping and thin delegation through the existing list methods are asserted. | Used |
74
+ | `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/AddressBook.ts` | Default policy, existing-parameter overrides, CMS sort serialization, view flags, and cache behavior are asserted. | Used |
75
+ | `src/services/task/state-machine/uiControlsComputer.ts`, `src/services/task/types.ts` | Task UI controls are the existing SDK-owned decision surface and can carry ordered destination availability. | Used |
76
+ | `test/unit/spec/services/task/state-machine/uiControlsComputer.ts`, `test/unit/spec/services/task/TaskFactory.ts` | Profile/media/direction gating, outbound flag path, ordering, and factory propagation are asserted. | Used |
77
+ | `src/services/task/Task.ts`, `src/services/task/constants.ts`, `test/unit/spec/services/task/Task.ts` | Direct entry-point transfer routing is translated to the backend EPDN value and sent through the vteam transfer path. | Used |
78
+ | The workspace sample docs/samples/contact-center/app.js (outside this package) | The sample renders buddy-agent state labels and mapped entry-point numbers while using the existing list methods and Task destination controls. | Used |
79
+
80
+ ## Decision
81
+
82
+ The SDK is the single owner of the default consult/transfer destination policy, applied through the
83
+ existing `getBuddyAgents`, `getQueues`, `getEntryPoints`, AddressBook, and `Task.transfer()` surfaces
84
+ and through `TaskUIControls.consultTransferDestinations`.
85
+
86
+ **In scope:**
65
87
 
66
88
  - Put consult/transfer defaults on the existing queue and entry-point list methods.
67
89
  - Map Consult versus Transfer to the correct buddy-agent state behavior.
68
90
  - Default omitted buddy-agent and queue media context to telephony.
69
91
  - Retain the existing queue/entry-point parameter and response wrappers; keep full Queue records, map EntryPoint dial-number rows to truthful `EntryPointRecord` fields, and retain compatible filter/sort overrides without exposing the fixed entry-point profile-scoping flag.
70
92
  - Default EntryPoint requests to backend `entryPointName,ASC` and AddressBook requests to `name,ASC` while allowing callers to pass another `sortBy`/`sortOrder` pair.
71
- - Serialize CMS ordering as `sort=<field>,<ORDER>`.
93
+ - Serialize CMS ordering as `sort=FIELD,ORDER` (for example `sort=name,ASC`).
72
94
  - Bypass the base pagination cache for every filter/view/shape flag that changes a result.
73
95
  - Keep the existing queue and entry-point method signatures and preserve explicit buddy-agent state callers.
74
96
  - Compute ordered, action-specific destination availability once on each Task and expose it through `TaskUIControls`, using Desktop Profile access, media, direction, and outbound queue-transfer capability.
75
97
  - Keep direct Entry Point available for eligible voice transfers and translate its public destination type to the backend EPDN value inside `Task.transfer()`.
76
98
 
77
- ### Out of scope
99
+ **Out of scope:**
78
100
 
79
101
  - Client-side sorting of agents, queues, or entry points.
80
102
  - Changing backend order after a response is received.
@@ -83,144 +105,128 @@ There are no open product decisions for this delta.
83
105
  - Adding a feature flag, data migration, commit, publication, or push.
84
106
  - Adding a separate destination-policy fetch method that Task consumers must call before rendering.
85
107
 
86
- ## Prior work and evidence
108
+ ### Decision rules and owning requirements
87
109
 
88
- | Source | What it establishes | Decision or disposition |
89
- | --- | --- | --- |
90
- | `src/cc.ts` | The public façade keeps the established list method names/signatures and owns buddy-agent action policy. | Used |
91
- | `src/types.ts`, `src/index.ts` | Existing queue/entry-point request and response types remain the public list contracts; entry-point rows expose the mapped dialled number as optional `number`. | Used |
92
- | `src/services/Queue.ts` | The existing Queue path owns default query serialization and view flags. | Used |
93
- | `src/services/EntryPoint.ts` | The existing EntryPoint path owns the desktop-profile dial-number query, field mapping, and backend ordering. | Used |
94
- | `src/services/core/WebexRequest.ts` | The shared request wrapper forwards optional per-request headers needed by the dial-number endpoint while leaving other requests unchanged. | Used |
95
- | `src/services/AddressBook.ts` | AddressBook owns its backend ordering default and caller override. | Used |
96
- | `src/utils/PageCache.ts` | Cache eligibility must include every result- or shape-changing query option. | Used |
97
- | `test/unit/spec/cc.ts` | Action mapping and thin delegation through the existing list methods are asserted. | Used |
98
- | `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/AddressBook.ts` | Default policy, existing-parameter overrides, CMS sort serialization, view flags, and cache behavior are asserted. | Used |
99
- | `src/services/task/state-machine/uiControlsComputer.ts`, `src/services/task/types.ts` | Task UI controls are the existing SDK-owned decision surface and can carry ordered destination availability. | Used |
100
- | `test/unit/spec/services/task/state-machine/uiControlsComputer.ts`, `test/unit/spec/services/task/TaskFactory.ts` | Profile/media/direction gating, outbound flag path, ordering, and factory propagation are asserted. | Used |
101
- | `src/services/task/Task.ts`, `src/services/task/constants.ts`, `test/unit/spec/services/task/Task.ts` | Direct entry-point transfer routing is translated to the backend EPDN value and sent through the vteam transfer path. | Used |
102
- | `docs/samples/contact-center/app.js` | The sample renders buddy-agent state labels and mapped entry-point numbers while using the existing list methods and Task destination controls. | Used |
103
-
104
- ## Requirements
105
-
106
- | ID | WHAT | WHY | Source evidence | Test or example evidence | Assumptions or gaps | Confidence |
107
- | --- | --- | --- | --- | --- | --- | --- |
108
- | `SDK-LIST-R-001` | Existing `getQueues` must retain `ContactServiceQueueSearchParams` and `ContactServiceQueuesResponse`, default to inbound active telephony queues ordered by backend name ascending with desktop-profile/agent/first-level views, avoid field projection, and honor defined caller-supplied existing parameters as overrides. Optional properties explicitly set to `undefined` retain defaults; explicit `false` flags and an explicit empty filter remain overrides. | Queue eligibility and ordering are consistent for ordinary calls without a new method or misleading projected/full-record type mismatch, while other consumers retain an explicit override path. Defined-only merging prevents a normally constructed optional-parameter object from accidentally disabling safe defaults. | `src/cc.ts`, `src/services/Queue.ts`, `src/types.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/Queue.ts` | Backend honors the documented CMS query flags. | Present |
109
- | `SDK-LIST-R-002` | Existing `getEntryPoints` must retain `EntryPointSearchParams` and `EntryPointListResponse`, query `/v3/dial-number` with organization/internal-data headers, fixed desktop-profile filtering, entry-point names, required mapping attributes, and backend `entryPointName,ASC`, then map each row to the existing `EntryPointRecord` as `id=entryPointId`, `name=entryPointName`, and optional `number=dialledNumber` without reordering. Caller-supplied compatible search, filter, attributes, and sort parameters remain available. | The visible entry-point number belongs to the dial-number mapping. Owning that mapping in the existing SDK method keeps consumers thin without exposing a parallel request or response type. | `src/cc.ts`, `src/services/EntryPoint.ts`, `src/services/config/constants.ts`, `src/services/core/WebexRequest.ts`, `src/types.ts` | `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/core/WebexRequest.ts` | The v3 response includes entry-point identifiers/names when `includeEntryPointName=true`. | Present |
110
- | `SDK-LIST-R-003` | Buddy-agent requests using `Transfer` must add state `Available`; requests using `Consult` must omit the state filter; omitted action-based media defaults to telephony; both `BuddyAgents` branches reuse one private supported-media union. | Transfer and Consult have different eligible populations, and one media allowlist prevents action-based callers from issuing unsupported buddy requests without adding another public type. | `src/cc.ts`, `src/types.ts` | `test/unit/spec/cc.ts` | The backend determines the Consult-eligible states when state is omitted. | Present |
111
- | `SDK-LIST-R-004` | Explicit buddy-agent state requests and existing queue/entry-point/address-book parameters must remain supported; caller-supplied filters and sort values override service defaults. | Existing SDK consumers need specialized behavior without a second list API. | `src/cc.ts`, `src/types.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/services/AddressBook.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/AddressBook.ts` | Existing callers that pass explicit `state` continue to use that branch. | Present |
112
- | `SDK-LIST-R-005` | Queue, EntryPoint, and AddressBook services must serialize ordering as CMS `sort=<field>,<ORDER>`, not separate `sortBy`/`sortOrder` query keys. Queue and AddressBook default to `name,ASC`; EntryPoint maps the public default `name` field to backend `entryPointName,ASC`; a Queue `sortOrder` without `sortBy` uses `name`. | Correct wire syntax and SDK-owned defaults make backend ordering consistent and prevent a caller's explicit direction from being silently ignored. | `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/services/AddressBook.ts` | `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/AddressBook.ts` | None. | Present |
113
- | `SDK-LIST-R-006` | PageCache must reject cache use when search, filter, attributes, a non-default/effective sort, or an enabled desktop-profile/provisioning/single-object flag is present. This includes a Queue `sortOrder` supplied without `sortBy`. Default Queue calls bypass simple-page caching because their eligibility filter and enabled views change the result set; profile-scoped EntryPoint requests are made directly without PageCache; AddressBook retains cache eligibility for its invariant default order. | The cache key does not encode result variants, so default policy requests and explicit query variants cannot safely share a page. | `src/utils/PageCache.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/services/AddressBook.ts` | `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/AddressBook.ts` | Service-level behavior covers default and override cases. | Present |
114
- | `SDK-LIST-R-007` | The SDK must not JavaScript-sort or reorder list response arrays. EntryPoint may rename/map fields row-for-row while preserving response order and pagination metadata. | Backend-requested order is authoritative, while field mapping must not alter list membership or order. | `src/cc.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/EntryPoint.ts` | The backend is the source of final row order. | Present |
115
- | `SDK-LIST-R-008` | The existing `BuddyAgents` input and `TaskUIControls.consultTransferDestinations` field must carry action/media and ordered destination typing without exporting one-off aliases; queue and entry-point consumers continue to use the established request/response wrappers. `EntryPointRecord` must strongly type optional mapped `number`, while configuration-only fields absent from the mapped list are optional. | Public consumers need a truthful compile-time contract without extra public aliases, destination abstractions, response wrappers, or casts for the displayed entry-point number. | `src/types.ts`, `src/services/task/types.ts`, `src/index.ts`, `src/cc.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/task/state-machine/uiControlsComputer.ts`, `package.json` | None. | Present |
116
- | `SDK-LIST-R-009` | Buddy-agent, queue, and entry-point failures must preserve their existing measured/logged rejection semantics and must not return a synthetic successful list. | Callers need to distinguish a real empty result from a transport or backend failure. | `src/cc.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts` | Consumer UI fallback behavior remains outside the SDK. | Present |
117
- | `SDK-LIST-R-010` | AddressBook must request backend `name,ASC` ordering by default and must accept caller-supplied `sortBy`/`sortOrder` overrides without a consult-specific façade method. | Widgets and other ordinary consumers receive backend-ordered dial numbers out of the box, while consumers with another requirement retain control. | `src/services/AddressBook.ts` | `test/unit/spec/services/AddressBook.ts` | Backend honors the documented CMS sort value. | Present |
118
- | `SDK-LIST-R-011` | Non-default queue media eligibility must be supplied through the existing RSQL `filter` parameter; the SDK never interpolates an unvalidated media string into a filter. | Reusing the established filter contract avoids a second media-bearing signature and removes the prior filter-injection path. | `src/services/Queue.ts`, `src/types.ts` | `test/unit/spec/services/Queue.ts` | Consumers that construct explicit RSQL filters remain responsible for supplying valid backend syntax. | Present |
119
- | `SDK-LIST-R-012` | Every Task must expose `uiControls.consultTransferDestinations` with ordered `consult` and `transfer` arrays. Order is Agent, Queue, Dial Number, Entry Point after gating: profile `NONE` removes agent/queue/entry point; voice Consult queue requires `allowConsultToQueue`; voice Transfer queue requires inbound direction or outbound plus `interaction.callProcessingDetails.outdialTransferToQueueEnabled === true`; unknown voice direction does not allow queue Transfer; digital exposes only allowed agent/queue categories. | All consumers need the same destination decision out of the box, without reading raw profile flags, interpreting task payload paths, or calling another policy API. | `src/cc.ts`, `src/services/task/TaskFactory.ts`, `src/services/task/types.ts`, `src/services/task/state-machine/uiControlsComputer.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/task/TaskFactory.ts`, `test/unit/spec/services/task/state-machine/uiControlsComputer.ts` | Consumers may hide an SDK-allowed category for host UX, but cannot enable one the SDK omitted. | Present |
120
- | `SDK-LIST-R-013` | A direct `Task.transfer()` to the public `entryPoint` destination must remain available for eligible voice tasks, translate internally to backend destination type `entrypointDialNumber`, and use `vteamTransfer`; callers continue to pass the selected entry-point identifier and do not perform backend translation. | Entry-point transfer is a supported vteam operation, while sending the public value unchanged through `blindTransfer` selects the wrong backend operation and makes SDK-owned controls advertise a failing action. | `src/services/task/Task.ts`, `src/services/task/constants.ts`, `src/services/task/types.ts` | `test/unit/spec/services/task/Task.ts` | The existing entry-point identifier remains a valid fallback when no analyzer identifier is exposed, matching the established transfer policy. | Present |
121
- | `SDK-LIST-R-014` | The Contact Center sample must treat a present empty Task destination array as an explicit “no destinations” decision by clearing and disabling the selector; only a missing/undefined control uses backward-compatible sample defaults. | An empty SDK policy result must not be replaced with categories the Task explicitly disallowed, while the sample still needs to run against older SDK builds that do not expose the field. | `docs/samples/contact-center/app.js` | Manual sample flow | The sample has no dedicated DOM unit suite. | Present |
122
-
123
- ## Defect context (when applicable)
110
+ Each decision rule keeps its `SDK-LIST-R-*` identifier; the behavior is specified by the module
111
+ requirement it links, which is authoritative.
124
112
 
125
- - Observed versus expected behavior: widgets and SDK callers could construct different destination requests, the services serialized sort with keys the CMS list API does not consume, and cache eligibility ignored view/shape flags; expected behavior is one SDK-owned default policy and unchanged backend response order.
126
- - Reproduction and environment: issue Consult and Transfer destination requests for the same task media and compare query parameters and results across SDK consumers.
127
- - Regression range or last known good state: unknown; the existing APIs and older query serialization predate the corrected defaults.
128
- - Severity, frequency, and workaround: user-visible whenever eligibility/order differs; consumers could manually duplicate flags, but that perpetuates the ownership defect.
129
- - Diagnostic evidence: `src/cc.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/utils/PageCache.ts`.
113
+ | Decision rule | Rule | Owning module requirement | Test evidence |
114
+ | --- | --- | --- | --- |
115
+ | `SDK-LIST-R-001` | `getQueues` defaults to inbound, active, telephony queues in backend `name,ASC` order with the desktop-profile, agent, and first-level views; optional fields set to `undefined` keep the defaults, while explicit `false` and an explicit empty filter override them | [SERVICES-R-007](../../src/services/docs/README.md) | `test/unit/spec/services/Queue.ts`, `test/unit/spec/cc.ts` |
116
+ | `SDK-LIST-R-002` | `getEntryPoints` maps profile-scoped `/v3/dial-number` rows to `{id, name, number?}` in backend `entryPointName,ASC` order | [SERVICES-R-007](../../src/services/docs/README.md) | `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/core/WebexRequest.ts` |
117
+ | `SDK-LIST-R-003` | Buddy agents: Transfer adds `Available`, Consult sends no state, media defaults to telephony, an explicit `state` wins | [AGENT-R-009](../../src/services/agent/docs/README.md) | `test/unit/spec/cc.ts` |
118
+ | `SDK-LIST-R-004` | Existing parameters (buddy-agent `state`, queue, entry-point, and address-book filters and sorts) override the defaults | [SERVICES-R-007](../../src/services/docs/README.md), [SERVICES-R-016](../../src/services/docs/README.md), [AGENT-R-009](../../src/services/agent/docs/README.md) | `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/AddressBook.ts` |
119
+ | `SDK-LIST-R-005` | Ordering is sent as one combined CMS `sort` value, never as separate `sortBy`/`sortOrder` keys | [SERVICES-R-007](../../src/services/docs/README.md), [SERVICES-R-016](../../src/services/docs/README.md) | `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/AddressBook.ts` |
120
+ | `SDK-LIST-R-006` | Only simple pagination may use the page cache | [UTILS-R-001](../../src/utils/docs/README.md) | `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/AddressBook.ts` |
121
+ | `SDK-LIST-R-007` | No JavaScript sort or reorder of list responses | This ADR, Constraint on future changes | `test/unit/spec/services/EntryPoint.ts` |
122
+ | `SDK-LIST-R-008` | Typing stays on `BuddyAgents`, `TaskUIControls`, and `EntryPointRecord` (optional `number`) with no one-off aliases | [CONTACT_CENTER-R-003](../../src/docs/README.md), [TASK_STATE_MACHINE-R-004](../../src/services/task/state-machine/docs/README.md) | `test/unit/spec/services/task/state-machine/uiControlsComputer.ts` |
123
+ | `SDK-LIST-R-009` | Failures reject with the existing measured and logged errors; no synthetic list | This ADR, Failure behavior | `test/unit/spec/cc.ts` |
124
+ | `SDK-LIST-R-010` | AddressBook defaults to `name,ASC` and accepts caller sorts | [SERVICES-R-016](../../src/services/docs/README.md) | `test/unit/spec/services/AddressBook.ts` |
125
+ | `SDK-LIST-R-011` | Non-default queue media goes through the existing `filter` parameter; the SDK never interpolates a media string | [SERVICES-R-007](../../src/services/docs/README.md) | `test/unit/spec/services/Queue.ts` |
126
+ | `SDK-LIST-R-012` | Every Task exposes ordered `consult` and `transfer` destination arrays | [TASK-R-009](../../src/services/task/docs/README.md), [TASK_STATE_MACHINE-R-004](../../src/services/task/state-machine/docs/README.md) | `test/unit/spec/services/task/TaskFactory.ts`, `test/unit/spec/services/task/state-machine/uiControlsComputer.ts` |
127
+ | `SDK-LIST-R-013` | `Task.transfer()` sends a public `entryPoint` destination as `entrypointDialNumber` through `vteamTransfer` | [Task spec](../../src/services/task/docs/README.md) `transfer` | `test/unit/spec/services/task/Task.ts` |
128
+ | `SDK-LIST-R-014` | The Contact Center sample treats a present empty destination array as no destinations | This ADR (the sample is outside the package) | Manual sample flow |
129
+
130
+ ### Contract changes
130
131
 
131
- ## MODIFIED Requirements
132
+ | API or operation | Change | Consumer impact | Compatibility expectation | Canonical definition |
133
+ | --- | --- | --- | --- | --- |
134
+ | Buddy-agent input | Add optional `action` to the existing options object and make `mediaType` optional with a telephony default. | Consumers may pass Consult/Transfer instead of choosing state. | Additive public option; explicit-state callers remain supported and take precedence. | `src/types.ts` |
135
+ | Existing queue list | Apply the telephony filter, profile views, and `name,ASC` by default. | Thin clients call `getQueues`; other consumers use existing parameters for overrides. | Intentional default correction; method and response signature unchanged. | `src/cc.ts`, `src/services/Queue.ts` |
136
+ | Existing entry-point list | Fetch desktop-profile `/v3/dial-number` mappings with the required organization/internal-data headers, request entry-point names, map fields row-for-row, and use `entryPointName,ASC` by default. | Thin clients call `getEntryPoints` and receive the displayed number without joining another endpoint. | Intentional default correction; method and response wrapper unchanged. | `src/cc.ts`, `src/services/EntryPoint.ts`, `src/services/config/constants.ts`, `src/services/core/WebexRequest.ts` |
137
+ | `EntryPointRecord` | Add optional mapped `number`; make configuration-only `type`, `isActive`, and `orgId` optional for truthful mapped-list typing. | Consumers can render the dialled number without a cast and cannot assume absent configuration fields. | Additive field with a type-correctness adjustment; no new response wrapper. | `src/types.ts` |
138
+ | Task destination controls | Add ordered `consultTransferDestinations.consult` and `.transfer` arrays to `TaskUIControls`. | Task consumers render availability directly; no separate policy call or raw profile injection is needed. | Additive public field using the existing destination values; no new standalone public alias. | `src/services/task/types.ts`, `src/services/task/state-machine/uiControlsComputer.ts`, `src/index.ts` |
139
+ | Existing `Task.transfer` entry-point input | Correct internal transport and backend destination translation. | Consumers keep passing `{to, destinationType: 'entryPoint'}` from the Task control array. | Behavioral bug fix; no method or public payload signature change. | `src/services/task/Task.ts`, `src/services/task/constants.ts` |
132
140
 
133
- ### MOD-001 — Contact Center façade policy (`CONTACT_CENTER-R-003`)
141
+ **Provides — MODIFIED:** The package keeps the existing queue, entry-point, buddy-agent, and Task transfer methods. Queue retains its established request/full-response signature and telephony defaults; EntryPoint retains its request/response wrapper while mapping desktop-profile dial-number rows to typed `{id, name, number?}` records in backend order; buddy agents accept action-aware input through `BuddyAgents`; `TaskUIControls` exposes inline ordered action-specific destination availability; direct entry-point transfer uses SDK-owned EPDN/vteam translation without changing the public payload.
134
142
 
135
- - **WHAT**: Retain the existing `getQueues`, `getEntryPoints`, and `getBuddyAgents` method names. Buddy-agent behavior is action-aware; Queue retains its parameter/full-record response and owns telephony eligibility/views/order, while EntryPoint retains its parameter/response wrapper and owns the profile-scoped dial-number query, row mapping, order, and cache policy.
136
- - **WHY**: A stable public owner prevents every UI consumer from reconstructing eligibility and query details.
137
- - **Evidence:** `src/cc.ts`, `src/types.ts`, `src/index.ts`, `test/unit/spec/cc.ts`.
138
- - **Acceptance:** Façade tests cover Consult, Transfer, and unchanged existing-method delegation; service tests cover default policy, explicit existing-filter overrides, and exact responses.
143
+ **Requires — MODIFIED:** Queue, EntryPoint, and AddressBook services require CMS list endpoints to honor the combined sort value. Queue requires its profile/agent/first-level views; EntryPoint requires `/v3/dial-number` to honor the organization/internal-data headers, desktop-profile filtering, `includeEntryPointName`, and mapping attributes. Direct entry-point transfer requires the WCC vteam transfer operation to accept the established `entrypointDialNumber` destination and selected entry-point identifier. The SDK continues to rely on host-authenticated Webex requests and backend response ordering.
139
144
 
140
- ### MOD-002 — Direct REST list services (`SERVICES-R-002`, `SERVICES-R-007`)
145
+ No event contract changes.
141
146
 
142
- - **WHAT**: Queue, EntryPoint, and AddressBook must serialize CMS sorting as a combined `sort` value and honor explicit compatible caller overrides. Queue must apply its defaults when optional properties are absent or `undefined`, while retaining explicit `false` and empty-filter overrides. Queue and AddressBook default to `name,ASC`; EntryPoint requests profile-scoped `/v3/dial-number` rows with `entryPointName,ASC` and maps them into the established response wrapper while retaining direct HTTP completion/error semantics.
143
- - **WHY**: SDK defaults are effective only when service wire parameters match the backend contract.
144
- - **Evidence:** `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/services/AddressBook.ts`, `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/AddressBook.ts`.
145
- - **Acceptance:** Service tests assert Queue/AddressBook `sort=name,ASC`, EntryPoint `sort=entryPointName,ASC`, Queue defaults with undefined optional fields, explicit Queue overrides, required views/mapping fields, and row-for-row EntryPoint mapping.
147
+ | Entity or payload | Requested field or shape | Purpose | Ownership | Privacy, retention, or compatibility constraint |
148
+ | --- | --- | --- | --- | --- |
149
+ | Buddy-agent input | Existing options object with optional `action`, `mediaType`, and explicit `state`; explicit state takes precedence | Derive Consult/Transfer eligibility without a parallel public input type. | SDK public type | No credential or persistent data. |
150
+ | Queue search input | Existing page, page size, search, filter, sort, and profile parameters | Consumer-controlled pagination plus optional default overrides. | Existing SDK public type | No second media-bearing request type. |
151
+ | Queue backend query | Default inbound/active/telephony filter, name ascending, desktop-profile/agent/first-level views, and no field projection | Full queue result using the default list policy. | Queue service | Fixed filter/views bypass simple-page caching. |
152
+ | Entry-point backend query | `/v3/dial-number`, `X-ORGANIZATION-ID`, `x-ignore-internal-data=false`, `desktopProfileFilter=true`, `includeEntryPointName=true`, required mapping attributes, and `entryPointName,ASC` | Return profile-scoped EP-DN rows with the visible dialled number. | EntryPoint service and shared WebexRequest wrapper | The service does not use PageCache for these profile-scoped requests. |
153
+ | Entry-point response row | `id=entryPointId`, `name=entryPointName`, optional `number=dialledNumber` | Let consumers route by entry-point ID and display the mapped dialled number without a cast or second request. | `EntryPointRecord` public type | Mapping preserves response order and pagination metadata. |
154
+ | Direct entry-point transfer payload | Caller-selected `to`; public `entryPoint` translated internally to `entrypointDialNumber` | Invoke the supported vteam transfer operation without consumer-side backend knowledge. | Task service | Translation is transport-only; metrics retain the caller-facing destination type and no new public field is required. |
155
+ | AddressBook backend query | Existing caller-selected fields plus name ascending by default | Backend-ordered dial numbers without a specialized façade. | AddressBook service | A non-default sort bypasses the default-order cache. |
156
+
157
+ ### Scenarios and interactions
158
+
159
+ | Scenario | Actor | Preconditions | Expected behavior | Failure or boundary behavior | Requirements |
160
+ | --- | --- | --- | --- | --- | --- |
161
+ | Consult buddy agents | SDK consumer | `action=Consult` | Telephony defaults when absent; state is omitted; backend order is preserved. | Request rejection is measured/logged and rethrown; applying the Transfer-only `Available` filter is invalid. | `SDK-LIST-R-003`, `SDK-LIST-R-007` |
162
+ | Transfer buddy agents | SDK consumer | `action=Transfer` | State `Available` is sent for the selected media. | An explicit `state` takes precedence over `action` when both are supplied; an omitted state filter would return idle agents. | `SDK-LIST-R-003`, `SDK-LIST-R-008` |
163
+ | Queue list | SDK consumer | Existing method called with page/search and optional filter override | SDK applies the default telephony policy and returns full records unchanged; an explicit existing filter overrides eligibility, for example `channelType==SOCIAL_CHANNEL`. | HTTP failure is propagated without a synthetic page; repeated view-filtered calls reach the backend, never a simple-page cache hit; no second media-bearing method signature. | `SDK-LIST-R-001`, `SDK-LIST-R-006`, `SDK-LIST-R-007`, `SDK-LIST-R-011` |
164
+ | Entry-point list | SDK consumer | Existing method called with page/search and optional compatible overrides | SDK fetches desktop-profile dial-number mappings with backend `sort=entryPointName,ASC`, preserves backend order/meta, and returns `{id, name, number?}` rows through `EntryPointListResponse`. | HTTP failure is propagated without a synthetic page; the widget neither sorts nor requests the mapping itself. | `SDK-LIST-R-002`, `SDK-LIST-R-007`, `SDK-LIST-R-008`, `SDK-LIST-R-009` |
165
+ | Dial-number list | SDK consumer | AddressBook page/search supplied | AddressBook applies backend `name,ASC` by default and returns the response unchanged. | A custom sort overrides the default and bypasses the default-order cache; the consumer never has to supply the default itself. | `SDK-LIST-R-010` |
166
+ | Specialized list consumer | SDK consumer | Uses an existing list method with explicit parameters | Explicit filter/sort/profile inputs override defaults; the backend receives the requested field/order and returns arrays and metadata in backend order. | No parallel consult/transfer method or projected response type is required; the SDK never overwrites the caller's explicit behavior or applies a JavaScript `.sort()`. | `SDK-LIST-R-004`, `SDK-LIST-R-005`, `SDK-LIST-R-007` |
167
+ | Direct entry-point transfer | SDK consumer | Voice Task exposes Entry Point in the Transfer destination array | `Task.transfer({to, destinationType: 'entryPoint'})` sends `{to, destinationType: 'entrypointDialNumber'}` through `vteamTransfer`. | Vteam rejection is measured and rethrown; `blindTransfer` is not invoked and the category is not hidden. | `SDK-LIST-R-012`, `SDK-LIST-R-013` |
168
+ | Sample receives an empty destination array | Sample user | Task exposes the requested action with `[]` | Destination selector is cleared and disabled. | Missing/undefined destination controls use the sample's compatibility defaults; legacy defaults never replace an explicit empty array. | `SDK-LIST-R-014` |
169
+
170
+ ### Failure behavior
171
+
172
+ | Failure | SDK behavior | Consumer-visible result | Evidence |
173
+ | --- | --- | --- | --- |
174
+ | Buddy-agent AQM rejection | Record failure context and rethrow. | Promise rejects; no synthetic agent list. | `src/cc.ts`, `test/unit/spec/cc.ts` |
175
+ | Queue HTTP rejection | Service metrics/logging remain active and the error propagates. | Promise rejects; no synthetic paginated result. | `src/services/Queue.ts`, `test/unit/spec/services/Queue.ts` |
176
+ | Entry-point HTTP rejection | Service metrics/logging remain active and the error propagates. | Promise rejects; no synthetic paginated result. | `src/services/EntryPoint.ts`, `test/unit/spec/services/EntryPoint.ts` |
177
+ | Missing action-based media | Default to telephony. | Valid request with predictable channel. | `src/cc.ts`, `test/unit/spec/cc.ts` |
178
+ | Non-default queue media eligibility | Consumer supplies a complete allowlisted RSQL value through the existing `filter` field; the SDK performs no media-string interpolation. | Existing queue method returns matching records or propagates the backend error. | `src/services/Queue.ts`, service tests |
179
+ | Direct entry-point vteam transfer rejection | Preserve existing Task transfer error normalization, failure metrics, and rethrow semantics. | `Task.transfer()` rejects; no fallback blind-transfer request is made. | `src/services/task/Task.ts`, `test/unit/spec/services/task/Task.ts` |
146
180
 
147
- ### MOD-003 — Buddy-agent request contract (`AGENT-R-003`)
181
+ - Existing methods make one delegated list request and add no retry or request fan-out.
182
+ - Queue, EntryPoint, and AddressBook callers use compatible explicit existing parameters when they require non-default behavior.
183
+ - View/filter/shape queries bypass cache rather than risk stale or cross-policy results.
184
+ - Errors remain caller-visible; the SDK does not manufacture an empty success response.
148
185
 
149
- - **WHAT**: Preserve the existing `BuddyAgents` options object and correlated request/response contract while allowing its optional `action` field to derive state from `Consult` or `Transfer`. `mediaType` defaults to telephony, and an explicit `state` takes precedence over the action default.
150
- - **WHY**: Eligibility changes must not alter AQM settlement or invent UI-side filtering.
151
- - **Evidence:** `src/cc.ts`, `src/services/agent/index.ts`, `test/unit/spec/cc.ts`, `test/unit/spec/services/agent/index.ts`.
152
- - **Acceptance:** Transfer sends `Available`; Consult sends no state; explicit state callers remain typed and supported.
186
+ ## Why
153
187
 
154
- ### MOD-004 — Query-aware cache eligibility (`UTILS-R-001`, `UTILS-R-006`)
188
+ Backend-requested order and one SDK-owned eligibility decision reach every consumer unchanged, while
189
+ consumers with another need keep an explicit override through the parameters the methods already
190
+ accept. The decision log records the rationale for each step of the decision:
155
191
 
156
- - **WHAT**: Treat enabled profile/response-shape flags and non-default sorts as cache-disqualifying inputs. Existing Queue requests bypass cache through their fixed filters/views, EntryPoint makes its profile-scoped requests directly without PageCache, and default `name,ASC` AddressBook pages remain cache-eligible because that ordering is invariant for its base cache key.
157
- - **WHY**: A page keyed only by scope/page/pageSize cannot safely represent query variants, but it can safely represent one invariant default order.
158
- - **Evidence:** `src/utils/PageCache.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`.
159
- - **Acceptance:** Two identical Queue view-filtered or custom-sort calls make two backend requests; EntryPoint always makes the requested backend call; repeated default-sorted AddressBook pagination remains cache-eligible.
192
+ | Date | Decision or change | Rationale | Owner |
193
+ | --- | --- | --- | --- |
194
+ | 2026-08-21 | Replaced provisional `dbId` with typed `EntryPointRecord.number` populated from the backend `/v3/dial-number` mapping, and kept the existing `getEntryPoints` method/response wrapper. | Runtime testing showed no `dbId`; the dialled number belongs to the EP-DN mapping, and consumers should not join or reinterpret backend data. | Developer + Codex |
195
+ | 2026-08-21 | Made Queue defaults resilient to optional properties explicitly set to `undefined`, retained explicit false/empty overrides, and made the sample honor a present empty destination array. | Common object-building patterns must not silently disable safe SDK defaults, and an explicit Task policy decision must not be replaced by sample fallback categories. | Developer + Codex |
196
+ | 2026-08-20 | Kept Entry Point available for eligible voice transfers and corrected `Task.transfer()` to use vteam routing with internal `entrypointDialNumber` translation. | The backend transfer policy supports direct entry-point transfer; hiding it would remove valid functionality, while consumers should not know the backend EPDN literal. | Developer + Codex |
197
+ | 2026-08-19 | Kept action/media typing inside `BuddyAgents`, inlined the destination arrays on `TaskUIControls`, removed the new root aliases, and removed `dbId` additions from queue/entry-point records. | The established methods and types already express the required behavior; consumers do not need standalone aliases or an unused record field. | Developer + Codex |
198
+ | 2026-08-19 | Assigned all reusable eligibility, query, ordering, and cache decisions to the SDK. | Keep widgets thin and prevent cross-consumer behavior drift. | Developer + Codex |
199
+ | 2026-08-19 | Made backend response order authoritative and prohibited SDK-side JavaScript sorting. | One backend ordering decision must reach every consumer unchanged. | Developer + Codex |
200
+ | 2026-08-19 | Moved EntryPoint and AddressBook `name,ASC` ordering to service defaults and removed the specialized dial-number façade. | Widgets must work without supplying SDK-owned decisions; other consumers can pass explicit sort overrides. | Developer + Codex |
201
+ | 2026-08-19 | Removed the specialized queue/entry-point methods and destination response/options types and kept default policy on existing `getQueues`/`getEntryPoints` with existing overrides. | Consumers should keep established method signatures; a parallel list abstraction adds needless public surface and projection complexity. The later EP-DN correction retained the response wrapper while mapping truthful fields. | Developer + Codex |
202
+ | 2026-08-19 | Put ordered Consult/Transfer destination availability directly on every Task's `uiControls` instead of adding `getConsultTransferDestinationPolicy`. | The Task already owns UI decisions and live interaction data, so consumers should not make a second request or reproduce profile/media/direction rules. | Developer + Codex |
160
203
 
161
- ### MOD-005 — Direct entry-point transfer routing (`TASK-R-003`, `TASK-R-009`)
204
+ ## Alternatives considered
162
205
 
163
- - **WHAT**: Keep Entry Point in eligible voice Transfer destination controls. When `Task.transfer()` receives the public `entryPoint` destination, translate it internally to `entrypointDialNumber` and invoke `contact.vteamTransfer`; Queue remains on `vteamTransfer`, while Agent and Dial Number remain on `blindTransfer`.
164
- - **WHY**: Consumers must be able to follow Task controls directly without knowing backend routing values, and supported entry-point transfers must use the same vteam operation as the established transfer policy.
165
- - **Evidence:** `src/services/task/Task.ts`, `src/services/task/constants.ts`, `src/services/task/types.ts`, `test/unit/spec/services/task/Task.ts`.
166
- - **Acceptance:** Task tests assert the exact EPDN vteam payload, no blind-transfer call, and unchanged Queue/Agent dispatch.
206
+ | Alternative | Why it was not selected |
207
+ | ----------- | ----------------------- |
208
+ | Keep consult/transfer filtering, pagination rebuilding, and ordering in the widgets | It is the defect being fixed; see the 2026-08-19 log row that assigns the decisions to the SDK |
209
+ | Add specialized queue and entry-point methods with projected destination types | See the 2026-08-19 log row that removed them |
210
+ | Sort agents, queues, or entry points in JavaScript | See the 2026-08-19 log row that made backend order authoritative |
211
+ | Add `getConsultTransferDestinationPolicy` | See the 2026-08-19 log row that put the destinations on `uiControls` |
212
+ | Expose a provisional `EntryPointRecord.dbId` | See the 2026-08-21 log row that introduced `number` |
213
+ | Hide Entry Point from voice Transfer controls | See the 2026-08-20 log row on entry-point transfer |
167
214
 
168
- ## Acceptance criteria
215
+ ## Consequences
169
216
 
170
- - [x] Transfer buddy lookup sends state `Available`; Consult omits state; action-based media defaults to telephony (`MOD-003`, `SDK-LIST-R-003`).
171
- - [x] Existing `getQueues` sends the default inbound/active/telephony filter, backend name ascending order, desktop-profile, agent, and first-level views without a field projection (`MOD-001`, `MOD-002`, `SDK-LIST-R-001`).
172
- - [x] Queue optional fields set to `undefined` retain safe defaults, while explicit `false` and an explicit empty filter remain overrides (`MOD-002`, `SDK-LIST-R-001`).
173
- - [x] Existing `getEntryPoints` requests desktop-profile-filtered `/v3/dial-number` mappings with required headers, entry-point names, and backend `entryPointName,ASC`, then exposes each dialled number as `EntryPointRecord.number` without changing row order (`SDK-LIST-R-002`, `SDK-LIST-R-007`).
174
- - [x] Caller-supplied existing queue filters override its telephony default; compatible EntryPoint filters/sorts override its v3 mapping defaults while profile scoping remains fixed (`SDK-LIST-R-001`, `SDK-LIST-R-002`, `SDK-LIST-R-011`).
175
- - [x] AddressBook sends backend name ascending order by default and honors a caller-supplied descending override (`MOD-002`, `SDK-LIST-R-004`, `SDK-LIST-R-010`).
176
- - [x] Queue, EntryPoint, and AddressBook serialize CMS ordering as the combined `sort` query value (`MOD-002`, `SDK-LIST-R-005`).
177
- - [x] Queue `sortOrder` without `sortBy` serializes as `sort=name,<ORDER>` and bypasses the simple-page cache (`SDK-LIST-R-005`, `SDK-LIST-R-006`).
178
- - [x] Default Queue policy and other view/filter/shape/custom-sort requests bypass PageCache, EntryPoint makes its profile-scoped requests directly, and default-sorted AddressBook pages remain cacheable (`MOD-004`, `SDK-LIST-R-006`).
179
- - [x] No SDK façade or service sorts returned arrays in JavaScript (`SDK-LIST-R-007`).
180
- - [x] Existing queue and entry-point methods retain their response wrappers; `EntryPointRecord` additively types mapped `number` and marks configuration-only fields optional because the v3 mapping response does not provide them (`SDK-LIST-R-008`).
181
- - [x] The Contact Center sample uses the existing Task/list surfaces, labels buddy-agent availability, and displays `EntryPointRecord.number` when present (`SDK-LIST-R-002`, `SDK-LIST-R-008`).
182
- - [x] The Contact Center sample clears and disables its destination selector for a present empty Task destination array, while missing controls retain backward compatibility (`SDK-LIST-R-014`).
183
- - [x] Direct entry-point transfer remains SDK-advertised for eligible voice tasks and is sent through `vteamTransfer` as `entrypointDialNumber`, with no widgets-side translation (`MOD-005`, `SDK-LIST-R-013`).
184
- - [x] The package builds and the complete Contact Center unit and style suites pass (`SDK-LIST-R-008`).
217
+ **Positive:**
185
218
 
186
- ## Scenarios and applicable change views
219
+ - Consumers call the existing list methods and read `uiControls.consultTransferDestinations` without
220
+ reproducing profile, media, direction, eligibility, or ordering rules.
221
+ - Query variants can no longer reuse a cached page created under a different view.
222
+ - Direct entry-point transfer works from the Task control array without consumer-side backend values.
187
223
 
188
- | Scenario | Actor | Preconditions | Expected behavior | Failure or boundary behavior | Requirements |
189
- | --- | --- | --- | --- | --- | --- |
190
- | Consult buddy agents | SDK consumer | `action=Consult` | Telephony defaults when absent; state is omitted; backend order is preserved. | Request rejection is measured/logged and rethrown. | `SDK-LIST-R-003`, `SDK-LIST-R-007` |
191
- | Transfer buddy agents | SDK consumer | `action=Transfer` | State `Available` is sent for the selected media. | Explicit state and action cannot be combined by the public type. | `SDK-LIST-R-003`, `SDK-LIST-R-008` |
192
- | Queue list | SDK consumer | Existing method called with page/search and optional filter override | SDK applies the default telephony policy and returns full records unchanged; an explicit existing filter overrides eligibility. | HTTP failure is propagated without a synthetic page. | `SDK-LIST-R-001`, `SDK-LIST-R-007`, `SDK-LIST-R-011` |
193
- | Entry-point list | SDK consumer | Existing method called with page/search and optional compatible overrides | SDK fetches desktop-profile dial-number mappings, preserves backend order/meta, and returns `{id, name, number?}` rows through `EntryPointListResponse`. | HTTP failure is propagated without a synthetic page. | `SDK-LIST-R-002`, `SDK-LIST-R-007`, `SDK-LIST-R-008`, `SDK-LIST-R-009` |
194
- | Dial-number list | SDK consumer | AddressBook page/search supplied | AddressBook applies backend `name,ASC` by default and returns the response unchanged. | A custom sort overrides the default and bypasses the default-order cache. | `SDK-LIST-R-010` |
195
- | Specialized list consumer | SDK consumer | Uses an existing list method with explicit parameters | Explicit filter/sort/profile inputs override defaults. | No parallel consult/transfer method or projected response type is required. | `SDK-LIST-R-004`, `SDK-LIST-R-005` |
196
- | Direct entry-point transfer | SDK consumer | Voice Task exposes Entry Point in the Transfer destination array | `Task.transfer({to, destinationType: 'entryPoint'})` sends `{to, destinationType: 'entrypointDialNumber'}` through `vteamTransfer`. | Vteam rejection is measured and rethrown; `blindTransfer` is not invoked. | `SDK-LIST-R-012`, `SDK-LIST-R-013` |
197
- | Sample receives an empty destination array | Sample user | Task exposes the requested action with `[]` | Destination selector is cleared and disabled. | Missing/undefined destination controls use the sample's compatibility defaults. | `SDK-LIST-R-014` |
198
-
199
- ### Interaction and scenario matrix
200
-
201
- | Context or interacting state | Trigger | Expected result | Invalid or conflicting result | Requirements |
202
- | --- | --- | --- | --- | --- |
203
- | Consult + agent | Action request | No state filter | Applying Transfer-only `Available` | `SDK-LIST-R-003` |
204
- | Transfer + agent | Action request | `state=Available` | Returning idle agents through an omitted state filter | `SDK-LIST-R-003` |
205
- | Queue + social media | Existing list request with filter override | Caller supplies `channelType==SOCIAL_CHANNEL` through `filter` | Adding a second media-bearing method signature | `SDK-LIST-R-001`, `SDK-LIST-R-011` |
206
- | View-filtered Queue or profile-scoped EntryPoint | Repeated page request | Backend called for each request | Simple-page cache hit | `SDK-LIST-R-006` |
207
- | Existing Queue or AddressBook | Sort omitted | Backend receives `sort=name,ASC` | Consumer must provide the default itself | `SDK-LIST-R-005`, `SDK-LIST-R-010` |
208
- | Existing EntryPoint | Sort omitted | Backend receives `sort=entryPointName,ASC` and mapped rows remain in that order | Widget sorts or requests the mapping itself | `SDK-LIST-R-002`, `SDK-LIST-R-005`, `SDK-LIST-R-007` |
209
- | Existing Queue, EntryPoint, or AddressBook | Custom sort supplied | Backend receives the requested field/order | SDK overwrites the caller's explicit behavior | `SDK-LIST-R-004`, `SDK-LIST-R-010` |
210
- | Backend result | Response received | Array and metadata returned in backend order | JavaScript `.sort()` or consumer-specific reorder | `SDK-LIST-R-007` |
211
- | Voice Transfer + entry point | Destination selected | SDK maps `entryPoint` to backend `entrypointDialNumber` and calls `vteamTransfer` | Sending `entryPoint` through `blindTransfer` or hiding the supported category | `SDK-LIST-R-013` |
212
- | Sample + present empty controls | Task selection changes | Selector has no options and is disabled | Sample substitutes legacy defaults for an explicit empty array | `SDK-LIST-R-014` |
213
-
214
- ### API contract delta
224
+ **Negative / tradeoffs:**
215
225
 
216
- | API or operation | Change | Consumer impact | Compatibility expectation | Canonical definition |
217
- | --- | --- | --- | --- | --- |
218
- | Buddy-agent input | Add optional `action` to the existing options object and make `mediaType` optional with a telephony default. | Consumers may pass Consult/Transfer instead of choosing state. | Additive public option; explicit-state callers remain supported and take precedence. | `src/types.ts` |
219
- | Existing queue list | Apply the telephony filter, profile views, and `name,ASC` by default. | Thin clients call `getQueues`; other consumers use existing parameters for overrides. | Intentional default correction; method and response signature unchanged. | `src/cc.ts`, `src/services/Queue.ts` |
220
- | Existing entry-point list | Fetch desktop-profile `/v3/dial-number` mappings with the required organization/internal-data headers, request entry-point names, map fields row-for-row, and use `entryPointName,ASC` by default. | Thin clients call `getEntryPoints` and receive the displayed number without joining another endpoint. | Intentional default correction; method and response wrapper unchanged. | `src/cc.ts`, `src/services/EntryPoint.ts`, `src/services/config/constants.ts`, `src/services/core/WebexRequest.ts` |
221
- | `EntryPointRecord` | Add optional mapped `number`; make configuration-only `type`, `isActive`, and `orgId` optional for truthful mapped-list typing. | Consumers can render the dialled number without a cast and cannot assume absent configuration fields. | Additive field with a type-correctness adjustment; no new response wrapper. | `src/types.ts` |
222
- | Task destination controls | Add ordered `consultTransferDestinations.consult` and `.transfer` arrays to `TaskUIControls`. | Task consumers render availability directly; no separate policy call or raw profile injection is needed. | Additive public field using the existing destination values; no new standalone public alias. | `src/services/task/types.ts`, `src/services/task/state-machine/uiControlsComputer.ts`, `src/index.ts` |
223
- | Existing `Task.transfer` entry-point input | Correct internal transport and backend destination translation. | Consumers keep passing `{to, destinationType: 'entryPoint'}` from the Task control array. | Behavioral bug fix; no method or public payload signature change. | `src/services/task/Task.ts`, `src/services/task/constants.ts` |
226
+ - The default request behavior of `getQueues`, `getEntryPoints`, and the AddressBook list changed
227
+ without a signature change, so generic callers needing the old behavior must pass explicit overrides.
228
+ - Default Queue calls always bypass the simple-page cache, and profile-scoped EntryPoint requests are
229
+ never cached, so repeated calls reach the backend.
224
230
 
225
231
  ### Public API and semver impact
226
232
 
@@ -240,38 +246,6 @@ There are no open product decisions for this delta.
240
246
  | `@webex/cc-store` | Delegates entry points directly to the existing SDK method; uses the existing queue `filter` parameter only for a non-telephony active task. | store → SDK | Consume a compatible SDK release. | Widgets maintainers |
241
247
  | `@webex/cc-task` and `@webex/cc-components` | Supply action and render results. | UI → store → SDK | Release after compatible store/SDK. | Widgets maintainers |
242
248
 
243
- ## Contracts delta
244
-
245
- **Provides — MODIFIED:** The package keeps the existing queue, entry-point, buddy-agent, and Task transfer methods. Queue retains its established request/full-response signature and telephony defaults; EntryPoint retains its request/response wrapper while mapping desktop-profile dial-number rows to typed `{id, name, number?}` records in backend order; buddy agents accept action-aware input through `BuddyAgents`; `TaskUIControls` exposes inline ordered action-specific destination availability; direct entry-point transfer uses SDK-owned EPDN/vteam translation without changing the public payload.
246
-
247
- **Requires — MODIFIED:** Queue, EntryPoint, and AddressBook services require CMS list endpoints to honor the combined sort value. Queue requires its profile/agent/first-level views; EntryPoint requires `/v3/dial-number` to honor the organization/internal-data headers, desktop-profile filtering, `includeEntryPointName`, and mapping attributes. Direct entry-point transfer requires the WCC vteam transfer operation to accept the established `entrypointDialNumber` destination and selected entry-point identifier. The SDK continues to rely on host-authenticated Webex requests and backend response ordering.
248
-
249
- No event contract changes.
250
-
251
- ## Success and guardrail metrics
252
-
253
- | Metric | Baseline | Target | Measurement source |
254
- | --- | --- | --- | --- |
255
- | Consumers that must recreate the default queue/entry-point policy | Widgets did | 0 for ordinary existing-method calls | `src/services/Queue.ts`, `src/services/EntryPoint.ts` |
256
- | JavaScript-side destination sorts in the changed SDK path | 0 | 0 | `src/cc.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts` |
257
- | Cache hits for view/filter/shape query variants | Possible | 0 | `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts` |
258
- | Contact Center unit failures | Unknown before change | 0 | `test/unit/spec` |
259
- | Contact Center build/style errors | Unknown before change | 0 | Package build and style commands |
260
-
261
- ## Requested data and fields
262
-
263
- | Entity or payload | Requested field or shape | Purpose | Ownership | Privacy, retention, or compatibility constraint |
264
- | --- | --- | --- | --- | --- |
265
- | Buddy-agent input | Existing options object with optional `action`, `mediaType`, and explicit `state`; explicit state takes precedence | Derive Consult/Transfer eligibility without a parallel public input type. | SDK public type | No credential or persistent data. |
266
- | Queue search input | Existing page, page size, search, filter, sort, and profile parameters | Consumer-controlled pagination plus optional default overrides. | Existing SDK public type | No second media-bearing request type. |
267
- | Queue backend query | Default inbound/active/telephony filter, name ascending, desktop-profile/agent/first-level views, and no field projection | Full queue result using the default list policy. | Queue service | Fixed filter/views bypass simple-page caching. |
268
- | Entry-point backend query | `/v3/dial-number`, `X-ORGANIZATION-ID`, `x-ignore-internal-data=false`, `desktopProfileFilter=true`, `includeEntryPointName=true`, required mapping attributes, and `entryPointName,ASC` | Return profile-scoped EP-DN rows with the visible dialled number. | EntryPoint service and shared WebexRequest wrapper | The service does not use PageCache for these profile-scoped requests. |
269
- | Entry-point response row | `id=entryPointId`, `name=entryPointName`, optional `number=dialledNumber` | Let consumers route by entry-point ID and display the mapped dialled number without a cast or second request. | `EntryPointRecord` public type | Mapping preserves response order and pagination metadata. |
270
- | Direct entry-point transfer payload | Caller-selected `to`; public `entryPoint` translated internally to `entrypointDialNumber` | Invoke the supported vteam transfer operation without consumer-side backend knowledge. | Task service | Translation is transport-only; metrics retain the caller-facing destination type and no new public field is required. |
271
- | AddressBook backend query | Existing caller-selected fields plus name ascending by default | Backend-ordered dial numbers without a specialized façade. | AddressBook service | A non-default sort bypasses the default-order cache. |
272
-
273
- ## Impacted domains
274
-
275
249
  | Repository or module | Impact | Owner |
276
250
  | --- | --- | --- |
277
251
  | `src` | Public façade and exports | SDK maintainers |
@@ -281,82 +255,91 @@ No event contract changes.
281
255
  | `src/utils` | Cache eligibility for query variants | SDK maintainers |
282
256
  | Webex widgets repository | Thin consumer of the new defaults | Widgets maintainers |
283
257
 
284
- ## Feasibility and risks
258
+ The current behavior is specified in the owning module specifications: the façade policy in the
259
+ [Contact Center plugin spec](../../src/docs/README.md), the Queue, EntryPoint, and AddressBook wire
260
+ queries in the [Services spec](../../src/services/docs/README.md), the buddy-agent request in the
261
+ [Agent spec](../../src/services/agent/docs/README.md), cache eligibility in the
262
+ [Utils spec](../../src/utils/docs/README.md), direct entry-point transfer in the
263
+ [Task spec](../../src/services/task/docs/README.md), and the destination controls in the
264
+ [Task state machine spec](../../src/services/task/state-machine/docs/README.md).
265
+
266
+ ### Risks and mitigations
285
267
 
286
268
  | Risk or assumption | Evidence | Mitigation or decision owner |
287
269
  | --- | --- | --- |
288
- | CMS ignores ordering when encoded as legacy separate keys. | `src/services/Queue.ts`, `src/services/EntryPoint.ts` | Use and test combined `sort=<field>,<ORDER>` serialization. |
270
+ | CMS ignores ordering when encoded as legacy separate keys. | `src/services/Queue.ts`, `src/services/EntryPoint.ts` | Use and test combined `sort=FIELD,ORDER` (for example `sort=name,ASC`) serialization. |
289
271
  | Simple cache returns a page created under a different view. | `src/utils/PageCache.ts` | Make every result/shape flag cache-disqualifying and retain repeated-call tests. |
290
272
  | New EntryPoint/AddressBook ordering defaults affect generic callers. | `src/services/EntryPoint.ts`, `src/services/AddressBook.ts` | Make the correction explicit, retain caller overrides, and test both default and custom order. |
291
273
  | A consumer re-sorts backend results. | `test/unit/spec/cc.ts` | Return the delegated response unchanged and document backend order as authoritative. |
292
274
  | Direct entry-point transfer is sent to the blind-transfer operation or with the public destination literal. | `src/services/task/Task.ts`, established transfer-policy behavior | Route through `vteamTransfer`, translate to `entrypointDialNumber`, and assert the exact payload. |
293
- | Entry-point configuration records do not contain the visible dialled number, and widget runtime returned no provisional `dbId`. | The backend `/v3/dial-number` contract returns `dialledNumber`, `entryPointId`, and `entryPointName`. | Move the EP-DN request/mapping into existing `getEntryPoints`, type `number`, and keep widget rendering declarative. |
275
+ | Entry-point configuration records do not contain the visible dialled number, and widget runtime returned no provisional `dbId`. | The backend /v3/dial-number contract returns dialledNumber, entryPointId, and entryPointName. | Move the EP-DN request/mapping into existing `getEntryPoints`, type `number`, and keep widget rendering declarative. |
294
276
 
295
- ## Error Matrix
296
-
297
- | Failure | SDK behavior | Consumer-visible result | Evidence |
298
- | --- | --- | --- | --- |
299
- | Buddy-agent AQM rejection | Record failure context and rethrow. | Promise rejects; no synthetic agent list. | `src/cc.ts`, `test/unit/spec/cc.ts` |
300
- | Queue HTTP rejection | Service metrics/logging remain active and the error propagates. | Promise rejects; no synthetic paginated result. | `src/services/Queue.ts`, `test/unit/spec/services/Queue.ts` |
301
- | Entry-point HTTP rejection | Service metrics/logging remain active and the error propagates. | Promise rejects; no synthetic paginated result. | `src/services/EntryPoint.ts`, `test/unit/spec/services/EntryPoint.ts` |
302
- | Missing action-based media | Default to telephony. | Valid request with predictable channel. | `src/cc.ts`, `test/unit/spec/cc.ts` |
303
- | Non-default queue media eligibility | Consumer supplies a complete allowlisted RSQL value through the existing `filter` field; the SDK performs no media-string interpolation. | Existing queue method returns matching records or propagates the backend error. | `src/services/Queue.ts`, service tests |
304
- | Direct entry-point vteam transfer rejection | Preserve existing Task transfer error normalization, failure metrics, and rethrow semantics. | `Task.transfer()` rejects; no fallback blind-transfer request is made. | `src/services/task/Task.ts`, `test/unit/spec/services/task/Task.ts` |
305
-
306
- ## Resilience
307
-
308
- - Existing methods make one delegated list request and add no retry or request fan-out.
309
- - Queue, EntryPoint, and AddressBook callers use compatible explicit existing parameters when they require non-default behavior.
310
- - View/filter/shape queries bypass cache rather than risk stale or cross-policy results.
311
- - Errors remain caller-visible; the SDK does not manufacture an empty success response.
312
-
313
- ## Observability
277
+ ### Observability, operations, and migration
314
278
 
315
279
  - Existing buddy-agent success/failure metrics retain media and derived state context plus count, without logging agent identities.
316
280
  - Existing Queue and EntryPoint request/success/failure metrics continue to cover the default and overridden calls.
317
281
  - Existing Task transfer success/failure metrics continue to report the caller-facing entry-point destination while transport uses the backend EPDN value.
318
282
  - No new metric taxonomy, PII-bearing log, credential log, trace, or alert is introduced.
319
283
 
320
- ## Operations
321
-
322
284
  - Build and run the complete Contact Center unit suite and style check before publishing.
323
285
  - Release the SDK before or with widgets that require the corrected existing-method defaults and Task controls.
324
286
  - Rollback is a coordinated package-version/code rollback; no persisted state, schema, or cache migration is required.
325
287
 
326
- ## Migration expectations
327
-
328
288
  - Compatibility: list method names and response wrappers remain unchanged; explicit buddy-agent state remains supported; optional `EntryPointRecord.number` is additive and configuration-only entry-point fields are now optional. Queue/AddressBook request `name,ASC`; EntryPoint requests mapped, profile-scoped `entryPointName,ASC` rows while retaining compatible filter/sort overrides.
329
289
  - Data or consumer transition: thin consumers continue using `getQueues` and `getEntryPoints`; consumers needing different behavior pass existing query overrides.
330
290
  - Coexistence period: no parallel list surface exists.
331
291
  - Completion and rollback outcome: consumers no longer own the default consult/transfer policy; rollback restores prior calls without data cleanup.
332
292
 
333
- ## Serviceability
334
-
335
293
  | Signal or support surface | Required change | Consumer or operator | Acceptance evidence |
336
294
  | --- | --- | --- | --- |
337
295
  | Buddy-agent operational metrics | Report derived action state and media without identities. | SDK maintainers | `test/unit/spec/cc.ts` |
338
296
  | Queue request metrics/logs | Preserve existing request success/failure coverage for default and overridden calls. | SDK maintainers | `test/unit/spec/services/Queue.ts` |
339
297
  | Entry-point request metrics/logs | Preserve existing request success/failure coverage for default and overridden calls. | SDK maintainers | `test/unit/spec/services/EntryPoint.ts` |
340
298
 
341
- ## Documentation obligations
299
+ ### Acceptance evidence
342
300
 
343
- - This approved delta modifies `CONTACT_CENTER-R-003`, `SERVICES-R-002`, `SERVICES-R-007`, `AGENT-R-003`, `UTILS-R-001`, and `UTILS-R-006` without overwriting protected canonical specs.
344
- - Direct entry-point routing additionally modifies `TASK-R-003` and `TASK-R-009` through this approved MODIFIED delta; the protected Task canonical spec remains unchanged until a future reconciliation/promotion.
345
- - The paired widgets feature spec must reference this SDK delta as the owner of queue eligibility/order/profile views and entry-point dial-number mapping/order; widgets delegate entry points without media filtering and may pass a queue filter for an active non-telephony task.
346
- - A future canonical-spec promotion must fold this delta into the routed module specs and reconcile the delta path rather than duplicate the requirements.
301
+ The test evidence for each decision rule is in the decision-rule table under Decision. The success
302
+ and guardrail metrics are:
347
303
 
348
- ## Decision and change log
349
-
350
- | Date | Decision or change | Rationale | Owner |
304
+ | Metric | Baseline | Target | Measurement source |
351
305
  | --- | --- | --- | --- |
352
- | 2026-08-21 | Replaced provisional `dbId` with typed `EntryPointRecord.number` populated from the backend `/v3/dial-number` mapping, and kept the existing `getEntryPoints` method/response wrapper. | Runtime testing showed no `dbId`; the dialled number belongs to the EP-DN mapping, and consumers should not join or reinterpret backend data. | Developer + Codex |
353
- | 2026-08-21 | Made Queue defaults resilient to optional properties explicitly set to `undefined`, retained explicit false/empty overrides, and made the sample honor a present empty destination array. | Common object-building patterns must not silently disable safe SDK defaults, and an explicit Task policy decision must not be replaced by sample fallback categories. | Developer + Codex |
354
- | 2026-08-21 | Superseded the provisional optional `EntryPointRecord.dbId` experiment. | Runtime validation established that the displayed field is `dialledNumber` from the EP-DN mapping, now exposed as `number`. | Developer + Codex |
355
- | 2026-08-20 | Kept Entry Point available for eligible voice transfers and corrected `Task.transfer()` to use vteam routing with internal `entrypointDialNumber` translation. | The backend transfer policy supports direct entry-point transfer; hiding it would remove valid functionality, while consumers should not know the backend EPDN literal. | Developer + Codex |
356
- | 2026-08-19 | Kept action/media typing inside `BuddyAgents`, inlined the destination arrays on `TaskUIControls`, removed the new root aliases, and removed `dbId` additions from queue/entry-point records. | The established methods and types already express the required behavior; consumers do not need standalone aliases or an unused record field. | Developer + Codex |
357
- | 2026-08-19 | Approved this exact MODIFIED delta path. | Preserve protected canonical specs while maintaining spec-currency with the implementation. | Developer |
358
- | 2026-08-19 | Assigned all reusable eligibility, query, ordering, and cache decisions to the SDK. | Keep widgets thin and prevent cross-consumer behavior drift. | Developer + Codex |
359
- | 2026-08-19 | Made backend response order authoritative and prohibited SDK-side JavaScript sorting. | One backend ordering decision must reach every consumer unchanged. | Developer + Codex |
360
- | 2026-08-19 | Moved EntryPoint and AddressBook `name,ASC` ordering to service defaults and removed the specialized dial-number façade. | Widgets must work without supplying SDK-owned decisions; other consumers can pass explicit sort overrides. | Developer + Codex |
361
- | 2026-08-19 | Removed the specialized queue/entry-point methods and destination response/options types and kept default policy on existing `getQueues`/`getEntryPoints` with existing overrides. | Consumers should keep established method signatures; a parallel list abstraction adds needless public surface and projection complexity. The later EP-DN correction retained the response wrapper while mapping truthful fields. | Developer + Codex |
362
- | 2026-08-19 | Put ordered Consult/Transfer destination availability directly on every Task's `uiControls` instead of adding `getConsultTransferDestinationPolicy`. | The Task already owns UI decisions and live interaction data, so consumers should not make a second request or reproduce profile/media/direction rules. | Developer + Codex |
306
+ | Consumers that must recreate the default queue/entry-point policy | Widgets did | 0 for ordinary existing-method calls | `src/services/Queue.ts`, `src/services/EntryPoint.ts` |
307
+ | JavaScript-side destination sorts in the changed SDK path | 0 | 0 | `src/cc.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts` |
308
+ | Cache hits for view/filter/shape query variants | Possible | 0 | `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts` |
309
+ | Contact Center unit failures | Unknown before change | 0 | All suites under test/unit/spec |
310
+ | Contact Center build/style errors | Unknown before change | 0 | Package build and style commands |
311
+
312
+ ## Constraint on future changes
313
+
314
+ While this decision is active, keep the policy on the existing methods: do not add parallel
315
+ consult/transfer list methods or projected response types, do not sort or reorder list responses in
316
+ JavaScript, keep every result- or shape-changing query option cache-disqualifying in `PageCache`, keep
317
+ desktop-profile scoping of entry points SDK-owned, keep the `entryPoint` to `entrypointDialNumber`
318
+ translation inside `Task.transfer()`, and keep `consultTransferDestinations` ordered Agent, Queue, Dial
319
+ Number, Entry Point with the first item as the consumer default.
320
+
321
+ ## Follow-up
322
+
323
+ - The paired widgets feature spec must reference this SDK delta as the owner of queue eligibility/order/profile views and entry-point dial-number mapping/order; widgets delegate entry points without media filtering and may pass a queue filter for an active non-telephony task.
324
+
325
+ ## Revisit when
326
+
327
+ - The CMS list APIs or `/v3/dial-number` change how they honor the combined `sort` value, the
328
+ desktop-profile views, or `includeEntryPointName`.
329
+ - The WCC vteam transfer operation stops accepting `entrypointDialNumber`.
330
+ - A consumer needs a destination category or order that the Task controls cannot express.
331
+
332
+ ## References
333
+
334
+ - `src/cc.ts`
335
+ - `src/types.ts`
336
+ - `src/services/Queue.ts`
337
+ - `src/services/EntryPoint.ts`
338
+ - `src/services/AddressBook.ts`
339
+ - `src/utils/PageCache.ts`
340
+ - `src/services/task/Task.ts`
341
+ - `src/services/task/state-machine/uiControlsComputer.ts`
342
+ - `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`,
343
+ `test/unit/spec/services/AddressBook.ts`, `test/unit/spec/cc.ts`,
344
+ `test/unit/spec/services/task/Task.ts`, `test/unit/spec/services/task/state-machine/uiControlsComputer.ts`
345
+ - The workspace sample docs/samples/contact-center/app.js (outside this package)