@htilabs/platform-common-models 0.34.0 → 0.36.0

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 (52) hide show
  1. package/README.md +135 -0
  2. package/dist/constants/index.cjs +2 -0
  3. package/dist/constants/index.cjs.map +1 -1
  4. package/dist/constants/index.js +2 -0
  5. package/dist/constants/index.js.map +1 -1
  6. package/dist/{cvcEntry-DAuhe0cd.d.cts → cvcEntry-BqAGctqK.d.cts} +36 -36
  7. package/dist/{cvcEntry-DAuhe0cd.d.ts → cvcEntry-BqAGctqK.d.ts} +36 -36
  8. package/dist/{index-1pWiqEBC.d.cts → index-BTqHP4DM.d.cts} +1 -1
  9. package/dist/{index-uz57Fic9.d.ts → index-Dr6GBCoY.d.ts} +1 -1
  10. package/dist/index.cjs +2 -0
  11. package/dist/index.cjs.map +1 -1
  12. package/dist/index.d.cts +2 -2
  13. package/dist/index.d.ts +2 -2
  14. package/dist/index.js +2 -0
  15. package/dist/index.js.map +1 -1
  16. package/dist/models/index.d.cts +2 -2
  17. package/dist/models/index.d.ts +2 -2
  18. package/dist/org-directory/index.cjs +4 -3
  19. package/dist/org-directory/index.cjs.map +1 -1
  20. package/dist/org-directory/index.d.cts +22 -6
  21. package/dist/org-directory/index.d.ts +22 -6
  22. package/dist/org-directory/index.js +4 -3
  23. package/dist/org-directory/index.js.map +1 -1
  24. package/dist/points-of-contact/index.cjs +6 -3
  25. package/dist/points-of-contact/index.cjs.map +1 -1
  26. package/dist/points-of-contact/index.js +6 -3
  27. package/dist/points-of-contact/index.js.map +1 -1
  28. package/dist/schemas/index.d.cts +11 -11
  29. package/dist/schemas/index.d.ts +11 -11
  30. package/dist/share-review/index.cjs +301 -0
  31. package/dist/share-review/index.cjs.map +1 -0
  32. package/dist/share-review/index.d.cts +431 -0
  33. package/dist/share-review/index.d.ts +431 -0
  34. package/dist/share-review/index.js +263 -0
  35. package/dist/share-review/index.js.map +1 -0
  36. package/package.json +11 -1
  37. package/src/__sot__/README.md +2 -0
  38. package/src/__sot__/captureConflictSemantics.pin.json +156 -0
  39. package/src/generated/captureConflictSemantics.ts +200 -0
  40. package/src/orgDirectory/__tests__/orgDirectory.test.ts +60 -0
  41. package/src/orgDirectory/rules.ts +26 -9
  42. package/src/pointsOfContact/__tests__/writer.test.ts +15 -0
  43. package/src/shareReview/__tests__/captureConflictSemantics.test.ts +148 -0
  44. package/src/shareReview/__tests__/captureConflictSemanticsPin.test.ts +78 -0
  45. package/src/shareReview/__tests__/recommendedDecision.test.ts +35 -0
  46. package/src/shareReview/__tests__/reviewDecision.test.ts +102 -0
  47. package/src/shareReview/__tests__/shareFieldReviewPlan.test.ts +523 -0
  48. package/src/shareReview/captureConflictSemantics.ts +170 -0
  49. package/src/shareReview/index.ts +23 -0
  50. package/src/shareReview/recommendedDecision.ts +21 -0
  51. package/src/shareReview/reviewDecision.ts +71 -0
  52. package/src/shareReview/shareFieldReviewPlan.ts +288 -0
@@ -0,0 +1,200 @@
1
+ // ⚠️ GENERATED FILE — DO NOT EDIT BY HAND. ⚠️
2
+ //
3
+ // Emitted by scripts/gen-capture-conflict-semantics.ts from ONE input:
4
+ // src/__sot__/captureConflictSemantics.pin.json, which `npm run sot:pins` derives
5
+ // from the SSOT, the hti-features field-mapping registry (htilabstech/hti-features,
6
+ // src/hti_features/field_mapping/registry.json), key `capture_conflict_semantics` on captured rows.
7
+ // The prototype's generated `window.HTI_CAPTURE_CONFLICT_SEMANTICS` block is a
8
+ // sibling projection of the same key.
9
+ //
10
+ // To change a value: author it in the registry, then
11
+ // `npm run sot:pins -- --only=captureConflictSemantics` against an hti-features
12
+ // checkout, then `npm run gen:capture-conflict-semantics`.
13
+ // Drift-gated by `npm run gen:capture-conflict-semantics:check` (hermetic, CI).
14
+ //
15
+ // The table is SPARSE on purpose: 141 of 533 captured registry rows
16
+ // author a value. An absent field means NOBODY HAS RULED, which the resolver in
17
+ // src/shareReview/captureConflictSemantics.ts keeps distinct from every value.
18
+ // Do not add entries here to fill the gap.
19
+ //
20
+ // Registry version 1 @ ed3a1f9
21
+
22
+ /**
23
+ * How a CONFLICT between two values of the same captured field resolves at
24
+ * review time. Vocabulary fixed by the registry validator.
25
+ *
26
+ * - `additive_log` — entries add; never a conflict (a NAME is never a conflict,
27
+ * at most a display question).
28
+ * - `log_end_date_current` — one current entry + dated history; a conflict
29
+ * resolves by END-DATING one entry, BOTH kept.
30
+ * - `single_value_keep_replace` — true one-value facts; keep/replace by
31
+ * supersession, never deletion.
32
+ * - `no_conflict_derived` — the value never conflicts because it is derived.
33
+ */
34
+ export const CAPTURE_CONFLICT_SEMANTICS = [
35
+ "additive_log",
36
+ "log_end_date_current",
37
+ "single_value_keep_replace",
38
+ "no_conflict_derived",
39
+ ] as const;
40
+
41
+ export type CaptureConflictSemantics = (typeof CAPTURE_CONFLICT_SEMANTICS)[number];
42
+
43
+ /** Authored semantics keyed by registry field id (`capture.*` and kin). */
44
+ export const CAPTURE_CONFLICT_SEMANTICS_BY_FIELD: Readonly<
45
+ Record<string, CaptureConflictSemantics>
46
+ > = Object.freeze({
47
+ "capture.accommodation_type_set": "single_value_keep_replace",
48
+ "capture.account_link_role": "single_value_keep_replace",
49
+ "capture.address": "additive_log",
50
+ "capture.address_state": "single_value_keep_replace",
51
+ "capture.age_bin_reporting": "single_value_keep_replace",
52
+ "capture.assessment_capture_status": "single_value_keep_replace",
53
+ "capture.associate_subrole": "single_value_keep_replace",
54
+ "capture.birth_country": "single_value_keep_replace",
55
+ "capture.birth_state": "single_value_keep_replace",
56
+ "capture.case_account_id": "single_value_keep_replace",
57
+ "capture.case_team_id": "single_value_keep_replace",
58
+ "capture.child_custody": "single_value_keep_replace",
59
+ "capture.child_health": "single_value_keep_replace",
60
+ "capture.child_identity": "single_value_keep_replace",
61
+ "capture.child_legal": "single_value_keep_replace",
62
+ "capture.chronic_health_severity": "single_value_keep_replace",
63
+ "capture.citizenship": "additive_log",
64
+ "capture.collection_context": "additive_log",
65
+ "capture.contact_info": "additive_log",
66
+ "capture.contact_info_type": "additive_log",
67
+ "capture.contact_info_use_type": "additive_log",
68
+ "capture.contact_link_role": "single_value_keep_replace",
69
+ "capture.contact_safety_status": "single_value_keep_replace",
70
+ "capture.cooperativeness": "single_value_keep_replace",
71
+ "capture.destination_living_situation": "single_value_keep_replace",
72
+ "capture.education_level": "additive_log",
73
+ "capture.employment_status": "additive_log",
74
+ "capture.encounter_location": "additive_log",
75
+ "capture.english_proficiency": "single_value_keep_replace",
76
+ "capture.exit_reason": "single_value_keep_replace",
77
+ "capture.eye_color": "single_value_keep_replace",
78
+ "capture.facilitator_source_labels": "additive_log",
79
+ "capture.foreign_national": "single_value_keep_replace",
80
+ "capture.funder": "single_value_keep_replace",
81
+ "capture.hair_color": "single_value_keep_replace",
82
+ "capture.has_disability": "single_value_keep_replace",
83
+ "capture.has_tattoos": "single_value_keep_replace",
84
+ "capture.hiv_status": "single_value_keep_replace",
85
+ "capture.hmis_dv_currently_fleeing": "single_value_keep_replace",
86
+ "capture.hmis_dv_survivor": "single_value_keep_replace",
87
+ "capture.hmis_project_type": "single_value_keep_replace",
88
+ "capture.housing_subsidy_type": "log_end_date_current",
89
+ "capture.identification_rung_reached": "single_value_keep_replace",
90
+ "capture.immigration_status": "single_value_keep_replace",
91
+ "capture.income_cadence": "additive_log",
92
+ "capture.income_history": "additive_log",
93
+ "capture.industry_sector": "single_value_keep_replace",
94
+ "capture.involvement_role": "single_value_keep_replace",
95
+ "capture.kinship_basis": "additive_log",
96
+ "capture.lap_screen_result": "single_value_keep_replace",
97
+ "capture.le_report_status": "single_value_keep_replace",
98
+ "capture.legal_action_type": "additive_log",
99
+ "capture.lifecycle_engagement_state": "log_end_date_current",
100
+ "capture.link_end_reason": "additive_log",
101
+ "capture.living_situation": "log_end_date_current",
102
+ "capture.long_term_conditions": "single_value_keep_replace",
103
+ "capture.mental_health_status": "single_value_keep_replace",
104
+ "capture.mid_stay_event_type": "additive_log",
105
+ "capture.name": "additive_log",
106
+ "capture.needs_accommodations": "single_value_keep_replace",
107
+ "capture.non_residential_program_subtype": "single_value_keep_replace",
108
+ "capture.origin_interaction_type": "single_value_keep_replace",
109
+ "capture.participation_role": "additive_log",
110
+ "capture.pet_exit_reason": "single_value_keep_replace",
111
+ "capture.po_service_status": "single_value_keep_replace",
112
+ "capture.preferred_contact_method": "single_value_keep_replace",
113
+ "capture.priorities_safety": "single_value_keep_replace",
114
+ "capture.race_ethnicity": "log_end_date_current",
115
+ "capture.recipient_role": "single_value_keep_replace",
116
+ "capture.record_removal_reason": "additive_log",
117
+ "capture.referral_outcome": "single_value_keep_replace",
118
+ "capture.relationship": "single_value_keep_replace",
119
+ "capture.relationship_dynamics": "additive_log",
120
+ "capture.relationship_status_current": "single_value_keep_replace",
121
+ "capture.relationship_tie": "additive_log",
122
+ "capture.relationship_to_hoh": "single_value_keep_replace",
123
+ "capture.release_case_id": "single_value_keep_replace",
124
+ "capture.release_consent_type": "single_value_keep_replace",
125
+ "capture.release_scope_version": "single_value_keep_replace",
126
+ "capture.release_status": "single_value_keep_replace",
127
+ "capture.reporting_audience": "single_value_keep_replace",
128
+ "capture.residential_program_subtype": "single_value_keep_replace",
129
+ "capture.rural": "single_value_keep_replace",
130
+ "capture.service_delivery_channel": "single_value_keep_replace",
131
+ "capture.service_instance.linked_lifecycle_id": "no_conflict_derived",
132
+ "capture.service_instance.track_id": "no_conflict_derived",
133
+ "capture.service_plan_state": "single_value_keep_replace",
134
+ "capture.service_state": "log_end_date_current",
135
+ "capture.session_account_id": "single_value_keep_replace",
136
+ "capture.session_actor": "single_value_keep_replace",
137
+ "capture.session_ended_at": "single_value_keep_replace",
138
+ "capture.session_personnel": "no_conflict_derived",
139
+ "capture.session_route_state": "single_value_keep_replace",
140
+ "capture.session_signature": "single_value_keep_replace",
141
+ "capture.session_started_at": "single_value_keep_replace",
142
+ "capture.session_state": "single_value_keep_replace",
143
+ "capture.session_template": "single_value_keep_replace",
144
+ "capture.smt_type": "additive_log",
145
+ "capture.substance_use_status": "single_value_keep_replace",
146
+ "capture.survivor_achievement_item": "additive_log",
147
+ "capture.trafficking_relevant_role": "additive_log",
148
+ "capture.tribal_affiliation": "single_value_keep_replace",
149
+ "capture.us_veteran": "single_value_keep_replace",
150
+ "capture.us_veteran_branch": "additive_log",
151
+ "capture.us_veteran_status": "single_value_keep_replace",
152
+ "capture.vehicle_link_role": "single_value_keep_replace",
153
+ "capture.visa_type": "single_value_keep_replace",
154
+ "leads.assertion_car.assertion_domain": "single_value_keep_replace",
155
+ "leads.assertion_car.authored_app": "single_value_keep_replace",
156
+ "leads.assertion_car.handling_flags": "additive_log",
157
+ "leads.assertion_car.recency_band": "single_value_keep_replace",
158
+ "leads.case.closure_reason": "single_value_keep_replace",
159
+ "leads.charge.disposition": "additive_log",
160
+ "leads.criminal_org.category": "single_value_keep_replace",
161
+ "leads.criminal_org.ht_status": "additive_log",
162
+ "leads.deconfliction.ack_action": "single_value_keep_replace",
163
+ "leads.deconfliction.tier": "no_conflict_derived",
164
+ "leads.deconfliction.trigger": "no_conflict_derived",
165
+ "leads.disclosure_record.cui_marking": "no_conflict_derived",
166
+ "leads.lead.agency_record_snapshot": "no_conflict_derived",
167
+ "leads.lead.triage_outcome": "single_value_keep_replace",
168
+ "leads.milestone_snapshot.risk_band": "no_conflict_derived",
169
+ "leads.network.status": "additive_log",
170
+ "leads.person.identity_status": "single_value_keep_replace",
171
+ "leads.person_phase.trigger": "single_value_keep_replace",
172
+ "leads.roi.methods": "single_value_keep_replace",
173
+ "leads.roi.scope": "single_value_keep_replace",
174
+ "leads.share_edge.cadence": "no_conflict_derived",
175
+ "leads.share_edge.channel_state": "single_value_keep_replace",
176
+ "leads.share_edge.delivery_channel": "single_value_keep_replace",
177
+ "leads.share_edge.information_scope": "single_value_keep_replace",
178
+ "leads.share_edge.response_reason": "additive_log",
179
+ "leads.share_edge.review_state": "single_value_keep_replace",
180
+ "leads.sharing_grant.information_scope": "single_value_keep_replace",
181
+ "leads.tip.incident_source_type": "single_value_keep_replace",
182
+ "service_instance.non_client_audiences": "single_value_keep_replace",
183
+ "service_instance.why_not_code": "log_end_date_current",
184
+ "service_instance.why_not_secondary": "log_end_date_current",
185
+ "service_track.case_id": "no_conflict_derived",
186
+ "service_track.completed_confirmation": "single_value_keep_replace",
187
+ "service_track.state_override": "single_value_keep_replace",
188
+ });
189
+
190
+ /** Provenance of the pin this module was emitted from. */
191
+ export const CAPTURE_CONFLICT_SEMANTICS_SOURCE = Object.freeze({
192
+ repo: "htilabstech/hti-features",
193
+ path: "src/hti_features/field_mapping/registry.json",
194
+ commit: "ed3a1f9",
195
+ registryVersion: 1,
196
+ /** Captured rows in the registry — the denominator for the sparse table. */
197
+ capturedRowCount: 533,
198
+ /** Rows that author a value — the size of the table above. */
199
+ authoredCount: 141,
200
+ });
@@ -96,6 +96,59 @@ describe("row shape", () => {
96
96
  expect(organizationRowShape({ name: "X" })).toBe("unknown");
97
97
  expect(organizationRowShape(null)).toBe("unknown");
98
98
  });
99
+
100
+ // organizations.type is moving from the IC-58 Int to the CVC-48 key: the
101
+ // form of `type` must never make a shared-shape row "pave".
102
+ it("a Thread / auth row whose type is a CVC-48 key string is still Thread / auth shape", () => {
103
+ const authRow = {
104
+ _id: new Oid(ORG),
105
+ _schemaVersion: 1,
106
+ name: "The Spring",
107
+ agencyScope: new Oid(AGENCY),
108
+ agencyId: new Oid(AGENCY),
109
+ createdUser: new Oid(AGENCY),
110
+ emails: [],
111
+ phones: [],
112
+ status: 1,
113
+ };
114
+ for (const type of ["victim_service_provider", "own_agency_internal", "unknown", "LAW_ENFORCEMENT"]) {
115
+ expect(organizationRowShape({ ...authRow, type }), type).toBe("thread");
116
+ }
117
+ // a heading key (never stored, but a legacy number resolves to one) is still a type
118
+ expect(organizationRowShape({ ...authRow, type: "housing_shelter_continuum" })).toBe("thread");
119
+ expect(organizationRowShape({ ...authRow, type: 10 })).toBe("thread");
120
+ // PAVE's pl-958 shared row: Int type plus its own extras
121
+ expect(
122
+ organizationRowShape({ ...authRow, type: 28, typeKey: "victim_service_provider", shortName: "TS", requiresROI: true }),
123
+ ).toBe("thread");
124
+ });
125
+
126
+ it("a real PAVE-shape row is still pave, whatever its type", () => {
127
+ // platform-dev's PAVE rows (migratedFrom pave-dev): string id + acronym + location
128
+ const paveRow = {
129
+ _id: new Oid(ORG),
130
+ _schemaVersion: 1,
131
+ id: "org-dvis",
132
+ name: "DVIS",
133
+ acronym: "DVIS",
134
+ location: "Tulsa, OK",
135
+ type: "victim_service_provider",
136
+ migratedFrom: "pave-dev",
137
+ createdUser: new Oid(AGENCY),
138
+ };
139
+ expect(organizationRowShape(paveRow)).toBe("pave");
140
+ expect(organizationRowShape({ ...paveRow, type: 28 })).toBe("pave");
141
+ const { id: _id, acronym: _a, ...locationOnly } = paveRow;
142
+ expect(organizationRowShape(locationOnly)).toBe("pave");
143
+ });
144
+
145
+ it("a row with no type is unknown; a string type alone never makes a row pave", () => {
146
+ // platform-dev's account rows
147
+ expect(organizationRowShape({ name: "Acct", isAccount: true, type: null, apps: [] })).toBe("unknown");
148
+ expect(organizationRowShape({ name: "X", type: " " })).toBe("unknown");
149
+ // validity is the reader's question, not the shape's
150
+ expect(organizationRowShape({ name: "X", type: "Hospital" })).toBe("thread");
151
+ });
99
152
  });
100
153
 
101
154
  describe("the agency's own organization", () => {
@@ -169,6 +222,13 @@ describe("views", () => {
169
222
  typeKey: "care_center",
170
223
  paveId: "spring",
171
224
  });
225
+ const migrated = toDirectoryOrganizationView({
226
+ _id: new Oid(ORG),
227
+ name: "The Spring",
228
+ type: "victim_service_provider",
229
+ agencyScope: new Oid(AGENCY),
230
+ })!;
231
+ expect(migrated).toMatchObject({ shape: "thread", type: null, typeKey: "victim_service_provider" });
172
232
  expect(
173
233
  toDirectoryProgramView({ programId: "p", name: "N", reviewStatus: "declined" }),
174
234
  ).toBeNull();
@@ -38,10 +38,22 @@ export function sameDirectoryId(a: unknown, b: unknown): boolean {
38
38
  * Which writer's shape a stored `organizations` row has.
39
39
  *
40
40
  * - `canonical`: auth / Thread's global singletons (Unknown, Anonymous), marked by `canonicalKey`.
41
- * - `pave`: PAVE 2.0's shape (`packages/db/src/models/organization.ts`):
42
- * a string `id`, `type` as a CVC-48 key, `acronym`, `location`.
43
- * - `thread`: the Thread / auth shape: `type` an IC-58 Int.
44
- * - `unknown`: none of the above.
41
+ * - `pave`: PAVE 2.0's legacy own shape (`packages/db/src/models/organization.ts`
42
+ * before pl-958): a string `id`, `acronym`, `location`. Any ONE of the three
43
+ * marks it.
44
+ * - `thread`: the shared Thread / auth / Platform / PAVE (pl-958) shape: a
45
+ * `type` in either stored form — the IC-58 Int (legacy) or a non-empty string
46
+ * (the CVC-48 key). Whether the value is a VALID type is not this rule's
47
+ * question (the subpath stays SOT-free); readers resolve it.
48
+ * - `unknown`: none of the above (no type, `type: null`, an empty string —
49
+ * e.g. the Platform's account rows).
50
+ *
51
+ * The FORM of `type` never decides `pave`: `organizations.type` is moving from
52
+ * the IC-58 Int to the CVC-48 key on every shared row (auth's provisioning
53
+ * writes the key; the `migrate:org-type-keys` script rewrites the rest), so a
54
+ * key string is a shared-shape row. On platform-prod / platform-dev
55
+ * (2026-10-16) every PAVE-shape row carries all three markers and no
56
+ * Thread / auth / canonical row carries any of them.
45
57
  */
46
58
  export type OrganizationRowShape = "canonical" | "pave" | "thread" | "unknown";
47
59
 
@@ -49,9 +61,10 @@ export function organizationRowShape(raw: unknown): OrganizationRowShape {
49
61
  if (!raw || typeof raw !== "object") return "unknown";
50
62
  const r = raw as Record<string, unknown>;
51
63
  if (typeof r.canonicalKey === "string" && r.canonicalKey !== "") return "canonical";
52
- if (typeof r.id === "string" || typeof r.type === "string" || "acronym" in r || "location" in r)
53
- return "pave";
54
- if (typeof r.type === "number") return "thread";
64
+ if (typeof r.id === "string" || "acronym" in r || "location" in r) return "pave";
65
+ if (typeof r.type === "number" || (typeof r.type === "string" && r.type.trim() !== "")) {
66
+ return "thread";
67
+ }
55
68
  return "unknown";
56
69
  }
57
70
 
@@ -105,9 +118,13 @@ export interface DirectoryOrganizationView {
105
118
  id: string;
106
119
  shape: OrganizationRowShape;
107
120
  name: string;
108
- /** IC-58 Int (Thread / auth shape), else null. */
121
+ /** The stored `type` when it is a number (the legacy IC-58 Int), else null. */
109
122
  type: number | null;
110
- /** CVC-48 `referral_entity_category` key (PAVE shape), else null. */
123
+ /**
124
+ * The stored `type` when it is a string, else null: a CVC-48
125
+ * `referral_entity_category` key on a shared-shape row once it is migrated
126
+ * (or written by auth's provisioning), and on a legacy PAVE-shape row.
127
+ */
111
128
  typeKey: string | null;
112
129
  /** PAVE's own string `id` on a PAVE-shape row, else null. */
113
130
  paveId: string | null;
@@ -557,6 +557,21 @@ describe("mintPartnerContact: the shared in-app partner add (pl-bt1)", () => {
557
557
  expect(rows()).toHaveLength(0);
558
558
  });
559
559
 
560
+ it("accepts a Thread / auth org whose type is a CVC-48 key string (post-migration), as it does an Int-typed one", async () => {
561
+ const keyed = new ObjectId();
562
+ const legacy = new ObjectId();
563
+ m.store.get("organizations")!.push(
564
+ { _id: keyed, name: "Keyed", type: "victim_service_provider", agencyScope: new ObjectId(), status: 1 },
565
+ { _id: legacy, name: "Legacy", type: 28, agencyScope: new ObjectId(), status: 1 },
566
+ );
567
+ for (const org of [keyed, legacy]) {
568
+ expect(await add({ org_id: String(org) }, DESK), String(org)).toMatchObject({
569
+ ok: true,
570
+ value: { subject_type: "org", subject_id: String(org), agency_id: null, created: true },
571
+ });
572
+ }
573
+ });
574
+
560
575
  it("a stored row on the partner that does not parse fails loudly", async () => {
561
576
  m.store.set(POINTS_OF_CONTACT_COLLECTION, [
562
577
  { id: "poc-broken", agency_id: null, subject_type: "org", subject_id: ORG_C, active: true, emails: [{ value: "desk@c.org" }], identity_key: "writein:intake desk|desk@c.org", origin: "carrier-pigeon" },
@@ -0,0 +1,148 @@
1
+ // Ported from pave-2.0 packages/domain/src/captureConflictSemantics.test.ts @ 312943078,
2
+ // re-keyed from PAVE assertion_domain to registry field id. PAVE's "review axis vs
3
+ // spine axis" suite is not ported: VALUE_ADDITIVE_ASSERTION_DOMAINS is a PAVE
4
+ // storage concept this package does not carry.
5
+ import { describe, expect, it } from "vitest";
6
+
7
+ import {
8
+ CAPTURE_CONFLICT_SEMANTICS,
9
+ CAPTURE_CONFLICT_SEMANTICS_BY_FIELD,
10
+ CAPTURE_CONFLICT_SEMANTICS_SOURCE,
11
+ resolvedSemantics,
12
+ } from "../captureConflictSemantics.js";
13
+
14
+ // Real registry ids, one per semantics value, plus real UNAUTHORED captured ids.
15
+ // If the registry later authors one of the unauthored ids, these tests fail on
16
+ // purpose: a human reads the regenerated table and picks another fixture.
17
+ const LOG = "capture.living_situation"; // log_end_date_current
18
+ const KEEP_REPLACE = "capture.immigration_status"; // single_value_keep_replace (authored)
19
+ const DERIVED = "capture.session_personnel"; // no_conflict_derived
20
+ const ADDITIVE = ["capture.name", "capture.address", "capture.contact_info"] as const;
21
+ const UNAUTHORED = ["capture.vital_status", "capture.marital_status_legal"] as const;
22
+
23
+ describe("the generated table", () => {
24
+ it("authors the fixtures these tests rely on", () => {
25
+ expect(CAPTURE_CONFLICT_SEMANTICS_BY_FIELD[LOG]).toBe("log_end_date_current");
26
+ expect(CAPTURE_CONFLICT_SEMANTICS_BY_FIELD[KEEP_REPLACE]).toBe("single_value_keep_replace");
27
+ expect(CAPTURE_CONFLICT_SEMANTICS_BY_FIELD[DERIVED]).toBe("no_conflict_derived");
28
+ for (const f of ADDITIVE) expect(CAPTURE_CONFLICT_SEMANTICS_BY_FIELD[f], f).toBe("additive_log");
29
+ for (const f of UNAUTHORED) expect(f in CAPTURE_CONFLICT_SEMANTICS_BY_FIELD, f).toBe(false);
30
+ });
31
+
32
+ it("is keyed by registry field id, never by a bare assertion domain", () => {
33
+ for (const key of Object.keys(CAPTURE_CONFLICT_SEMANTICS_BY_FIELD)) {
34
+ expect(key, key).toMatch(/^[a-z_]+\.[a-z0-9_.]+$/);
35
+ }
36
+ expect("living_situation" in CAPTURE_CONFLICT_SEMANTICS_BY_FIELD).toBe(false);
37
+ });
38
+
39
+ it("is SPARSE — most captured rows author nothing", () => {
40
+ const authored = Object.keys(CAPTURE_CONFLICT_SEMANTICS_BY_FIELD).length;
41
+ expect(authored).toBe(CAPTURE_CONFLICT_SEMANTICS_SOURCE.authoredCount);
42
+ expect(authored).toBeLessThan(CAPTURE_CONFLICT_SEMANTICS_SOURCE.capturedRowCount);
43
+ });
44
+
45
+ it("carries the vocabulary the registry validator enforces", () => {
46
+ expect([...CAPTURE_CONFLICT_SEMANTICS]).toEqual([
47
+ "additive_log",
48
+ "log_end_date_current",
49
+ "single_value_keep_replace",
50
+ "no_conflict_derived",
51
+ ]);
52
+ });
53
+
54
+ it("names where it came from, so a stale table can be traced", () => {
55
+ expect(CAPTURE_CONFLICT_SEMANTICS_SOURCE.repo).toBe("htilabstech/hti-features");
56
+ expect(CAPTURE_CONFLICT_SEMANTICS_SOURCE.commit).toMatch(/^[0-9a-f]{7,40}$/);
57
+ });
58
+
59
+ it("does not leak a mutable table to callers", () => {
60
+ expect(Object.isFrozen(CAPTURE_CONFLICT_SEMANTICS_BY_FIELD)).toBe(true);
61
+ expect(Object.isFrozen(CAPTURE_CONFLICT_SEMANTICS_SOURCE)).toBe(true);
62
+ });
63
+ });
64
+
65
+ describe("resolvedSemantics", () => {
66
+ it("reports an authored field as authored", () => {
67
+ expect(resolvedSemantics(LOG)).toEqual({
68
+ semantics: "log_end_date_current",
69
+ authored: true,
70
+ rulePath: "registry_authored",
71
+ producesConflict: true,
72
+ choices: ["theirs_current", "mine_current", "keep_both_flagged"],
73
+ });
74
+ });
75
+
76
+ it("an authored keep/replace field is authored, not a fallback", () => {
77
+ const r = resolvedSemantics(KEEP_REPLACE);
78
+ expect(r.semantics).toBe("single_value_keep_replace");
79
+ expect(r.authored).toBe(true);
80
+ expect(r.rulePath).toBe("registry_authored");
81
+ });
82
+
83
+ // ── THE FALLBACK ──────────────────────────────────────────────────────────
84
+ it("falls back to single_value_keep_replace WITHOUT claiming it was ruled", () => {
85
+ for (const f of [...UNAUTHORED, "capture.__never_authored__", "not.a.registry.field"]) {
86
+ const r = resolvedSemantics(f);
87
+ expect(r.semantics, f).toBe("single_value_keep_replace");
88
+ expect(r.authored, f).toBe(false);
89
+ expect(r.rulePath, f).toBe("unauthored_default_keep_replace");
90
+ expect(r.producesConflict, f).toBe(true);
91
+ }
92
+ });
93
+
94
+ it("gives an unauthored field the SAME controls as an authored keep/replace one", () => {
95
+ // The prototype branches only on `log_end_date_current`; every other value,
96
+ // authored or not, gets the keep/replace pair.
97
+ expect(resolvedSemantics(UNAUTHORED[0]).choices).toEqual(
98
+ resolvedSemantics(KEEP_REPLACE).choices,
99
+ );
100
+ expect(resolvedSemantics(UNAUTHORED[0]).choices).toEqual([
101
+ "replace",
102
+ "keep_mine",
103
+ "keep_both_flagged",
104
+ ]);
105
+ });
106
+
107
+ it("treats an additive field as NOT a conflict, with nothing to decide", () => {
108
+ for (const f of ADDITIVE) {
109
+ const r = resolvedSemantics(f);
110
+ expect(r.semantics, f).toBe("additive_log");
111
+ expect(r.producesConflict, f).toBe(false);
112
+ expect(r.choices, f).toEqual([]);
113
+ }
114
+ });
115
+
116
+ it("treats a derived field as NOT a conflict", () => {
117
+ const r = resolvedSemantics(DERIVED);
118
+ expect(r.producesConflict).toBe(false);
119
+ expect(r.choices).toEqual([]);
120
+ });
121
+
122
+ it("offers keep_both_flagged LAST on EVERY real conflict", () => {
123
+ for (const f of [LOG, KEEP_REPLACE, ...UNAUTHORED]) {
124
+ const r = resolvedSemantics(f);
125
+ expect(r.producesConflict, f).toBe(true);
126
+ expect(r.choices[r.choices.length - 1], f).toBe("keep_both_flagged");
127
+ }
128
+ });
129
+
130
+ it("every authored conflict-producing field offers keep_both_flagged", () => {
131
+ for (const f of Object.keys(CAPTURE_CONFLICT_SEMANTICS_BY_FIELD)) {
132
+ const r = resolvedSemantics(f);
133
+ if (r.producesConflict) expect(r.choices, f).toContain("keep_both_flagged");
134
+ else expect(r.choices, f).toEqual([]);
135
+ }
136
+ });
137
+
138
+ it("is not fooled by inherited Object properties", () => {
139
+ for (const f of ["constructor", "toString", "__proto__", "hasOwnProperty"]) {
140
+ const r = resolvedSemantics(f);
141
+ expect(r.authored, f).toBe(false);
142
+ expect(r.semantics, f).toBe("single_value_keep_replace");
143
+ }
144
+ });
145
+ });
146
+
147
+ // The row gate (bucket-aware) replaced the field-level `isOfferedDecision`; its
148
+ // tests live in shareFieldReviewPlan.test.ts ("isOfferedForRow").
@@ -0,0 +1,78 @@
1
+ /**
2
+ * HERMETIC GATE — the generated capture-conflict-semantics module equals its pin
3
+ * (th-hbo9t.2; the pin is derived by `sot:pins`, like every other pin here).
4
+ * `npm run gen:capture-conflict-semantics:check` enforces the same
5
+ * byte-for-byte; this suite makes `npm test` fail too, and pins the shape so a
6
+ * regenerated table that widens or narrows has to be read by a human.
7
+ */
8
+ import { readFileSync } from "node:fs";
9
+ import path from "node:path";
10
+ import { fileURLToPath } from "node:url";
11
+
12
+ import { describe, expect, it } from "vitest";
13
+
14
+ import {
15
+ CAPTURE_CONFLICT_SEMANTICS,
16
+ CAPTURE_CONFLICT_SEMANTICS_BY_FIELD,
17
+ CAPTURE_CONFLICT_SEMANTICS_SOURCE,
18
+ } from "../../generated/captureConflictSemantics.js";
19
+
20
+ const HERE = path.dirname(fileURLToPath(import.meta.url));
21
+ const PKG = path.resolve(HERE, "../../..");
22
+ const pin = JSON.parse(
23
+ readFileSync(path.join(PKG, "src/__sot__/captureConflictSemantics.pin.json"), "utf8"),
24
+ ) as {
25
+ sourceRepo: string;
26
+ sourceFile: string;
27
+ sourceSha: string;
28
+ registryVersion: number;
29
+ capturedRowCount: number;
30
+ vocabulary: string[];
31
+ fields: Record<string, string>;
32
+ };
33
+ const generatedSource = readFileSync(
34
+ path.join(PKG, "src/generated/captureConflictSemantics.ts"),
35
+ "utf8",
36
+ );
37
+
38
+ describe("captureConflictSemantics pin ⇄ generated module", () => {
39
+ it("the generated table equals the pin, key for key", () => {
40
+ expect({ ...CAPTURE_CONFLICT_SEMANTICS_BY_FIELD }).toEqual(pin.fields);
41
+ });
42
+
43
+ it("the provenance matches the pin", () => {
44
+ expect(CAPTURE_CONFLICT_SEMANTICS_SOURCE.repo).toBe(pin.sourceRepo);
45
+ expect(CAPTURE_CONFLICT_SEMANTICS_SOURCE.path).toBe(pin.sourceFile);
46
+ expect(CAPTURE_CONFLICT_SEMANTICS_SOURCE.commit).toBe(pin.sourceSha);
47
+ expect(CAPTURE_CONFLICT_SEMANTICS_SOURCE.registryVersion).toBe(pin.registryVersion);
48
+ expect(CAPTURE_CONFLICT_SEMANTICS_SOURCE.capturedRowCount).toBe(pin.capturedRowCount);
49
+ expect([...CAPTURE_CONFLICT_SEMANTICS]).toEqual(pin.vocabulary);
50
+ });
51
+
52
+ it("the generated module carries the DO-NOT-EDIT header", () => {
53
+ expect(generatedSource.startsWith("// ⚠️ GENERATED FILE — DO NOT EDIT BY HAND. ⚠️")).toBe(
54
+ true,
55
+ );
56
+ });
57
+
58
+ it("only registry-legal values appear", () => {
59
+ const legal = new Set<string>(CAPTURE_CONFLICT_SEMANTICS);
60
+ for (const [f, v] of Object.entries(pin.fields)) expect(legal.has(v), f).toBe(true);
61
+ });
62
+
63
+ // Human-diff guard: a regeneration that changes the table must update these
64
+ // numbers in a reviewed diff. At hti-features ed3a1f9 (registry last touched
65
+ // 38ff12ba, 2026-10-16) the table equals
66
+ // the prototype's generated block at c2b0b8b0 key for key (141).
67
+ it("authors 141 fields: 94 keep/replace, 30 additive, 10 derived, 7 end-date", () => {
68
+ const counts: Record<string, number> = {};
69
+ for (const v of Object.values(pin.fields)) counts[v] = (counts[v] ?? 0) + 1;
70
+ expect(Object.keys(pin.fields)).toHaveLength(141);
71
+ expect(counts).toEqual({
72
+ single_value_keep_replace: 94,
73
+ additive_log: 30,
74
+ no_conflict_derived: 10,
75
+ log_end_date_current: 7,
76
+ });
77
+ });
78
+ });
@@ -0,0 +1,35 @@
1
+ import { describe, expect, it } from "vitest";
2
+
3
+ import { isOfferedForRow, planFieldReview } from "../shareFieldReviewPlan.js";
4
+ import { recommendedDecision } from "../recommendedDecision.js";
5
+
6
+ describe("recommendedDecision", () => {
7
+ // Canon c2b0b8b0 L351827 (Accept all) / L351836 (per-row Apply):
8
+ // `c.semantics === "log_end_date_current" ? "theirs_current" : "replace"`.
9
+ it("routes log_end_date_current to theirs_current", () => {
10
+ expect(recommendedDecision("log_end_date_current")).toBe("theirs_current");
11
+ });
12
+
13
+ it("routes every other value to replace, including an unknown string", () => {
14
+ for (const s of ["single_value_keep_replace", "additive_log", "no_conflict_derived", ""]) {
15
+ expect(recommendedDecision(s), s).toBe("replace");
16
+ }
17
+ });
18
+
19
+ it("recommends a decision the conflict ROW admits, and applying it unblocks", () => {
20
+ for (const fieldId of [
21
+ "capture.living_situation",
22
+ "capture.immigration_status",
23
+ "capture.vital_status",
24
+ ]) {
25
+ const [row] = planFieldReview([{ offerId: "c", fieldId, targetPopulated: true }]).conflicts;
26
+ expect(row, fieldId).toBeDefined();
27
+ const rec = recommendedDecision(row!.semantics);
28
+ expect(isOfferedForRow(row!, rec), fieldId).toBe(true);
29
+ const applied = planFieldReview([
30
+ { offerId: "c", fieldId, targetPopulated: true, decision: rec },
31
+ ]);
32
+ expect(applied.blockingRemaining, fieldId).toBe(0);
33
+ }
34
+ });
35
+ });