@htilabs/platform-common-models 0.15.0 → 0.18.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 (76) hide show
  1. package/dist/agency-BHv54o79.d.ts +484 -0
  2. package/dist/agency-Ca4pCOOf.d.ts +342 -0
  3. package/dist/agency-DYCv839V.d.cts +342 -0
  4. package/dist/agency-Djp57S71.d.cts +484 -0
  5. package/dist/constants/index.cjs +952 -0
  6. package/dist/constants/index.cjs.map +1 -1
  7. package/dist/constants/index.d.cts +3 -1
  8. package/dist/constants/index.d.ts +3 -1
  9. package/dist/constants/index.js +920 -0
  10. package/dist/constants/index.js.map +1 -1
  11. package/dist/{cvcEntry-DaDrEuTa.d.cts → cvcEntry-0BIB9sen.d.cts} +44 -44
  12. package/dist/{cvcEntry-DaDrEuTa.d.ts → cvcEntry-0BIB9sen.d.ts} +44 -44
  13. package/dist/cvcs/index.cjs +182 -77
  14. package/dist/cvcs/index.cjs.map +1 -1
  15. package/dist/cvcs/index.d.cts +187 -78
  16. package/dist/cvcs/index.d.ts +187 -78
  17. package/dist/cvcs/index.js +182 -77
  18. package/dist/cvcs/index.js.map +1 -1
  19. package/dist/enums/index.cjs +3 -1
  20. package/dist/enums/index.cjs.map +1 -1
  21. package/dist/enums/index.d.cts +7 -5
  22. package/dist/enums/index.d.ts +7 -5
  23. package/dist/enums/index.js +3 -1
  24. package/dist/enums/index.js.map +1 -1
  25. package/dist/{index-C0J3f169.d.ts → index-CDoqrfc1.d.ts} +1 -1
  26. package/dist/{index-EPjPjR0z.d.cts → index-Zu_mOJRn.d.cts} +1 -1
  27. package/dist/index.cjs +1704 -1073
  28. package/dist/index.cjs.map +1 -1
  29. package/dist/index.d.cts +6 -4
  30. package/dist/index.d.ts +6 -4
  31. package/dist/index.js +1650 -1072
  32. package/dist/index.js.map +1 -1
  33. package/dist/models/index.d.cts +2 -2
  34. package/dist/models/index.d.ts +2 -2
  35. package/dist/org-type-BYQb9Qzq.d.ts +366 -0
  36. package/dist/org-type-D_FG4KdN.d.cts +366 -0
  37. package/dist/{platform-auth-CrF5U_JH.d.cts → platform-auth-CvAYFVhK.d.cts} +39 -0
  38. package/dist/{platform-auth-CrF5U_JH.d.ts → platform-auth-CvAYFVhK.d.ts} +39 -0
  39. package/dist/schemas/index.cjs +977 -2
  40. package/dist/schemas/index.cjs.map +1 -1
  41. package/dist/schemas/index.d.cts +38 -35
  42. package/dist/schemas/index.d.ts +38 -35
  43. package/dist/schemas/index.js +962 -1
  44. package/dist/schemas/index.js.map +1 -1
  45. package/dist/types/index.d.cts +2 -2
  46. package/dist/types/index.d.ts +2 -2
  47. package/dist/validation/index.cjs +894 -2
  48. package/dist/validation/index.cjs.map +1 -1
  49. package/dist/validation/index.d.cts +5 -1
  50. package/dist/validation/index.d.ts +5 -1
  51. package/dist/validation/index.js +884 -1
  52. package/dist/validation/index.js.map +1 -1
  53. package/package.json +26 -27
  54. package/src/__tests__/__snapshots__/cvc-sot.snap +5 -5
  55. package/src/__tests__/core-functions-canon.test.ts +53 -0
  56. package/src/__tests__/core-information-scope-invariant.test.ts +94 -4
  57. package/src/__tests__/cvc-sot-snapshot.test.ts +13 -10
  58. package/src/__tests__/cvc-status-parser.test.ts +1 -1
  59. package/src/__tests__/cvc-structural.test.ts +3 -3
  60. package/src/__tests__/org-type-contract.test.ts +1353 -0
  61. package/src/__tests__/referral-entity-category-canon.test.ts +255 -81
  62. package/src/constants/ic.ts +45 -0
  63. package/src/constants/index.ts +1 -0
  64. package/src/constants/org-type.ts +703 -0
  65. package/src/cvcs/{coreFunctions.v1.0.0.json → coreFunctions.v1.1.0.json} +11 -2
  66. package/src/cvcs/index.ts +3 -3
  67. package/src/cvcs/{referralEntityCategory.v1.1.0.json → referralEntityCategory.v1.2.0.json} +111 -59
  68. package/src/cvcs/{roiScope.v1.0.0.json → roiScope.v1.2.0.json} +51 -7
  69. package/src/generated/cvc-enums.ts +7 -5
  70. package/src/index.ts +23 -0
  71. package/src/schemas/agency.ts +481 -0
  72. package/src/schemas/index.ts +24 -0
  73. package/src/validation/agency.ts +119 -0
  74. package/src/validation/index.ts +1 -0
  75. package/dist/team-C4LJ5Tex.d.cts +0 -333
  76. package/dist/team-C4LJ5Tex.d.ts +0 -333
@@ -1389,7 +1389,7 @@ export type LocationTypeKey = keyof typeof LocationTypeKeys;
1389
1389
  /**
1390
1390
  * Key → positional code map for the `referral_entity_category` CVC domain.
1391
1391
  *
1392
- * Domain: `referral_entity_category` · Version: 1.1.0 · Entries: 46
1392
+ * Domain: `referral_entity_category` · Version: 1.2.0 · Entries: 47
1393
1393
  */
1394
1394
  export const ReferralEntityCategoryKeys = {
1395
1395
  missingness_root: "048-000-000-000-000-000-000",
@@ -1407,6 +1407,7 @@ export const ReferralEntityCategoryKeys = {
1407
1407
  hotlines: "048-006-000-000-000-000-000",
1408
1408
  national_hotline: "048-006-001-000-000-000-000",
1409
1409
  local_other_hotline: "048-006-002-000-000-000-000",
1410
+ hotline: "048-006-003-000-000-000-000",
1410
1411
  justice_protective_systems: "048-007-000-000-000-000-000",
1411
1412
  child_welfare_cps: "048-007-001-000-000-000-000",
1412
1413
  juvenile_justice: "048-007-002-000-000-000-000",
@@ -3986,9 +3987,9 @@ export const RiskCategoryKeys = {
3986
3987
  export type RiskCategoryKey = keyof typeof RiskCategoryKeys;
3987
3988
 
3988
3989
  /**
3989
- * Key → positional code map for the `core_functions` CVC domain (CANONICAL Notion CVC-133 `core - functions`, verified v1.0 — the Canonical Authorization Model function registry: 77 functions the roles → functions → gates/tiers graph is built over. NOT provisional numbering. Per-entry lifecycle Status (v1 / future / not-started), Platform Relevance, user/admin relevance and Category are carried in each entry's definition, since the CVC entry schema has no fields for them).
3990
+ * Key → positional code map for the `core_functions` CVC domain (CANONICAL Notion CVC-133 `core - functions`, verified v1.0 — the Canonical Authorization Model function registry: 78 functions (the verified 77 + `note_open_departed_author`, 133-078, appended 2026-10-05) the roles → functions → gates/tiers graph is built over. NOT provisional numbering. Per-entry lifecycle Status (v1 / future / not-started), Platform Relevance, user/admin relevance and Category are carried in each entry's definition, since the CVC entry schema has no fields for them).
3990
3991
  *
3991
- * Domain: `core_functions` · Version: 1.0.0 · Entries: 81
3992
+ * Domain: `core_functions` · Version: 1.1.0 · Entries: 82
3992
3993
  */
3993
3994
  export const CoreFunctionsKeys = {
3994
3995
  missingness_root: "133-000-000-000-000-000-000",
@@ -4072,6 +4073,7 @@ export const CoreFunctionsKeys = {
4072
4073
  training_content_upload: "133-075-000-000-000-000-000",
4073
4074
  training_gate_manage: "133-076-000-000-000-000-000",
4074
4075
  usr_manage: "133-077-000-000-000-000-000",
4076
+ note_open_departed_author: "133-078-000-000-000-000-000",
4075
4077
  } as const;
4076
4078
 
4077
4079
  export type CoreFunctionsKey = keyof typeof CoreFunctionsKeys;
@@ -4183,9 +4185,9 @@ export const CoreInformationScopeKeys = {
4183
4185
  export type CoreInformationScopeKey = keyof typeof CoreInformationScopeKeys;
4184
4186
 
4185
4187
  /**
4186
- * Key → positional code map for the `roi_scope` CVC domain (DRAFT-TEMPORARY; the 15 ROI scope ITEMS an ROI authorizes for sharing, sourced from PAVE `@pave/domain` ROI_SCOPE_KEYS. The item axis only — named bundles over these items are ROI_SCOPE_PRESET_NAMES. The prototype's 27-item HTI_SHARE_SCOPE_GROUPS superset holds +12 health-accommodation / immigration-legal items that are the documented extension set).
4188
+ * Key → positional code map for the `roi_scope` CVC domain (DRAFT-TEMPORARY; LEGACY flat item vocabulary, superseded for new work by `core_information_scope` (CVC-236). 27 ROI scope ITEMS: 25 live + 2 RETIRED tombstones (`screen_notes`, `background`; retired 2026-10-05, matching CVC-236 v1.1.0) that keep their codes so a stored value resolves, but are `selectable: false` + `retired: true` and include nothing — never offer them. The item axis only — named bundles over these items are ROI_SCOPE_PRESET_NAMES).
4187
4189
  *
4188
- * Domain: `roi_scope` · Version: 1.1.0 · Entries: 31
4190
+ * Domain: `roi_scope` · Version: 1.2.0 · Entries: 31
4189
4191
  */
4190
4192
  export const RoiScopeKeys = {
4191
4193
  missingness_root: "983-000-000-000-000-000-000",
package/src/index.ts CHANGED
@@ -81,6 +81,29 @@ export type {
81
81
  export { TeamAppSchema, TeamDirectoryFieldsSchema } from "./validation/team.js";
82
82
  export type { TeamApp, TeamDirectoryFieldsInput } from "./validation/team.js";
83
83
 
84
+ // ─── Agency organization-type field validation (Zod) ────────────────────────
85
+ // The Mongoose fragment (`agencyOrgTypeSchemaDefinition`,
86
+ // `addAgencyOrgTypeFields`) comes in through `./schemas/index.js` above; the
87
+ // vocabulary + classifiers through `./constants/index.js` (`org-type.ts`).
88
+ export {
89
+ OrgTypeSelectableKeySchema,
90
+ OrgTypeFieldsSchema,
91
+ orgTypeFieldsShape,
92
+ withOrgTypeFields,
93
+ AgencyTypeKeySchema,
94
+ AgencyOrgTypeFieldsSchema,
95
+ SetOrgTypeInputSchema,
96
+ } from "./validation/agency.js";
97
+ // `vspTwoStepHolds` / `VSP_TWO_STEP_ISSUE` now come in through
98
+ // `./schemas/index.js` (one definition, enforced in Zod, on save, on update
99
+ // and in the mirror); `./validation/agency.js` re-exports them for its callers.
100
+ export type {
101
+ OrgTypeSelectableKeyInput,
102
+ AgencyTypeKeyInput,
103
+ AgencyOrgTypeFieldsInput,
104
+ SetOrgTypeInput,
105
+ } from "./validation/agency.js";
106
+
84
107
  // ─── CVC factory model named aliases ────────────────────────────────────────
85
108
  // Per co-am3.7 bead: surface the model factories under explicit
86
109
  // `compileCvcRegistryModel` / `compileCvcEntryModel` names. The underlying
@@ -0,0 +1,481 @@
1
+ /**
2
+ * @htilabs/platform-common-models — organization-type fields: Org home, Agency mirror
3
+ *
4
+ * Shared, additive fields for the kind of organization something is, with
5
+ * the ONE vocabulary (`constants/org-type.ts`), and where they live.
6
+ *
7
+ * ## The three objects (UDD, ruled 2026-10-02; Org `vsp` ruled 2026-10-05)
8
+ *
9
+ * - **Org** — "who is this, out in the world": the platform-wide registry
10
+ * row (platform-db `organizations`). It HOLDS the type and the two HMIS
11
+ * victim-service-provider answers: `type`, `vsp`, `vspPrivateNonprofit`.
12
+ * One Org per real-world organization, with or without any account. The
13
+ * Admin Hub edits it here, once. (`requires_roi` stays on the org row AS
14
+ * BUILT and is NOT one of these fields: the Org Data Object lists it under
15
+ * "as built today, and not part of this definition" and GDR § 5.17 clause 2
16
+ * makes it informational — the release check reads the sender's `vsp`,
17
+ * never `requires_roi`. Review round ORG-TYPE-REVIEW-ROUND-2026-10-08, Crysta decision 1.)
18
+ * - **Account** — "who signed, and whose rules govern": the tenancy
19
+ * (`agencies` rows with `isAccount: true` today). Carries none of these
20
+ * fields; points at its holding Org.
21
+ * - **Agency** — "how does this Org take part in that Account": an Org with
22
+ * an Account IS an Agency — one row per (Org, Account), keyed by
23
+ * `organizationId` (→ `organizations._id`) and the account. The UDD Agency
24
+ * carries NO type and NO flags of its own; it reads them off its Org.
25
+ *
26
+ * ## Why the Agency gets a copy anyway (the mirror)
27
+ *
28
+ * Every live gate reads `agencies.type` (`/me`, the ROI gate, the authority
29
+ * set, the session-role default, recipient labels) and production's Org
30
+ * link is nearly empty (6 of 124 prod agencies carry an `organizationId`,
31
+ * #187). So the Agency row carries a **declared mirror** of the Org's four
32
+ * fields: same definition, stamped FROM the Org — by provisioning when the
33
+ * agency is created, by the backfill when it links the agency to its Org —
34
+ * and never edited on the agency directly. {@link mirrorOrgTypeFields} is
35
+ * the one way to produce the copy. The home is the Org; the mirror exists so
36
+ * readers do not have to join until `organizationId` is populated
37
+ * everywhere. A consumer that CAN join reads the Org through
38
+ * {@link resolveEffectiveOrgTypeFields} / {@link resolveEffectiveOrgType}
39
+ * ("the Org wins once linked"); {@link orgTypeFieldsDiffer} surfaces drift.
40
+ *
41
+ * **The mirror is TRANSITIONAL and has a sunset** (Crysta, 2026-10-08,
42
+ * platform-common #187): the agency copy is dropped the day every agency row
43
+ * carries `organizationId` (6 of 124 production rows today). The UDD Agency
44
+ * carries no type and no flags — this copy is a production crutch, not an
45
+ * Agency field, and nothing is ever "aligned" to it.
46
+ *
47
+ * **Re-stamp invariant** (Kirby, review of `9538e2e`): every write of these
48
+ * fields on an Org re-stamps the copy on EVERY agency row linked to it
49
+ * (`organizationId`), in the same operation as the Org write — the Admin Hub
50
+ * and the backfill are the two writers, and both go Org first, then
51
+ * `mirrorOrgTypeFields(org)` onto each linked agency. A reader that finds
52
+ * `orgTypeFieldsDiffer(org, agency)` non-empty has found a broken writer,
53
+ * not a legitimate state; it should read the Org and log the drift.
54
+ *
55
+ * ## This is a FRAGMENT, not an Org / Agency model
56
+ *
57
+ * No canonical Org or Agency schema exists in this package (same posture as
58
+ * `schemas/team.ts`). `organizations` is written by PAVE 2.0 (`type` a
59
+ * NUMBER 10–31 today — the IC-58 positional list; the Org mount replaces it
60
+ * with the key), `agencies` by the auth service at provisioning (`au-q3p`)
61
+ * and the platform Admin Hub, mirrored by Thread (`type: String` free text)
62
+ * and legacy PAVE. Declaring the whole shapes here is out of scope; this
63
+ * module declares ONLY the organization-type fields and mounts them on
64
+ * either schema: {@link addOrgTypeFields} (home) /
65
+ * {@link addAgencyOrgTypeFields} (mirror).
66
+ *
67
+ * ## Ruling of record (Crysta, 2026-10-05 — platform-common #187)
68
+ *
69
+ * Agency type = CVC-48 `core-referral_entity_category`, set ONCE on the Org
70
+ * in the Admin Hub; the Agency carries it from the Org; every reader joins on
71
+ * the key. `vsp` and `vspPrivateNonprofit` are captured on the org record in
72
+ * the Admin Hub (Directory tab; Network add / edit forms — UDD Org Data
73
+ * Object ruling 2026-10-05; the 2026-08-13 onboarding derivation
74
+ * `isVspEntityType` is retired by that ruling) and never inferred from the
75
+ * type. Refined 2026-10-08 (Crysta): the type PROPOSES the answer
76
+ * (`orgTypeDefaultVsp` is what the Admin Hub pre-fills, and what a reader
77
+ * falls back to while nothing is attested); the answer is SET only when HTI
78
+ * Labs affirms or changes it in the Admin Hub. A proposal is never written
79
+ * as an answer — not by onboarding, not by the backfill.
80
+ *
81
+ * ## Field names
82
+ *
83
+ * Canon's org registry spells these `type`, `vsp`, `vsp_private_nonprofit`
84
+ * (snake_case CSV columns). The live platform-db writers use camelCase on
85
+ * agencies (`isHTIAdminAgency`, `serviceLocation`, `apps`), so the second
86
+ * boolean is carried camelCase here; `type` and `vsp` are spelled the same
87
+ * in both.
88
+ *
89
+ * ## Backfill posture
90
+ *
91
+ * `type` is NOT `required` at the schema level yet: most production agencies
92
+ * were provisioned with no type at all, and a required enum would make every
93
+ * one of them fail validation on its next unrelated save. Not-required keeps
94
+ * those rows saving; it does NOT protect a row that already carries a non-key
95
+ * value (see the `type` field doc) — those are the backfill's first job. The
96
+ * backfill (HTI Labs confirms each agency against the org registry; #187)
97
+ * sets a key on every row; the minor that follows it flips `required: true`.
98
+ * Until then a stored `unknown` is the ONE admitted placeholder, and readers
99
+ * treat an absent / unresolvable type exactly like `unknown`
100
+ * (`resolveAgencyTypeKey` → `null`).
101
+ *
102
+ * ## Order of adoption (review MG2) — BOTH collections
103
+ *
104
+ * Mongoose validates every loaded path on `save()`, so once a consumer mounts
105
+ * these fields, a document carrying a NON-KEY `type` fails its next save of
106
+ * any field. That is the intended fail-closed, and it means the data goes
107
+ * first: (1) `agencies` — the handful of free-text rows (prod 3, dev 3) are
108
+ * normalised to `unknown`, no HTI confirmation needed; (2) `organizations` —
109
+ * EVERY row carries a numeric IC-58 type today (10–31, PAVE's writer), so the
110
+ * numeric → key migration (proposed by `resolveOrgTypeKeyFromLegacyNumeric`,
111
+ * confirmed by HTI Labs on the backfill sheet) runs BEFORE any consumer calls
112
+ * {@link addOrgTypeFields} on `organizations`; (3) mount; (4) after the
113
+ * backfill, `required: true` and the recognisers are deleted.
114
+ * (ORG-TYPE-REVIEW-ROUND-2026-10-08)
115
+ */
116
+
117
+ import { Error as MongooseError } from "mongoose";
118
+ import type { Document, InferRawDocType, Query, Schema } from "mongoose";
119
+ import {
120
+ AGENCY_TYPE_KEYS,
121
+ resolveAgencyTypeKey,
122
+ type AgencyTypeKey,
123
+ } from "../constants/org-type.js";
124
+
125
+ // ─── The HMIS VSP two-step (Stage-0 ruling 4c) ──────────────────────────────
126
+
127
+ /**
128
+ * Step 2 (`vspPrivateNonprofit`) is asked only when step 1 (`vsp`) is `true`.
129
+ * A record (or a write) that answers step 2 without `vsp: true` is MALFORMED
130
+ * — never "false by default". Tri-state is preserved: an absent / `null`
131
+ * step 2 always holds, whatever step 1 says (GDR § 1.2: never-captured is
132
+ * never coerced). One predicate, enforced in three places: the Zod write
133
+ * shapes (`validation/agency.ts`), the Mongoose mount (`pre('validate')` on
134
+ * save and the update-op hook) and {@link mirrorOrgTypeFields}.
135
+ */
136
+ export function vspTwoStepHolds(v: {
137
+ vsp?: boolean | null;
138
+ vspPrivateNonprofit?: boolean | null;
139
+ }): boolean {
140
+ return v.vspPrivateNonprofit == null || v.vsp === true;
141
+ }
142
+ export const VSP_TWO_STEP_ISSUE: {
143
+ message: string;
144
+ path: (string | number)[];
145
+ } = {
146
+ message:
147
+ "vspPrivateNonprofit is step 2 of the HMIS VSP two-step and requires vsp: true",
148
+ path: ["vspPrivateNonprofit"],
149
+ };
150
+
151
+ /**
152
+ * The two-step on an UPDATE payload (`updateOne` / `updateMany` /
153
+ * `findOneAndUpdate`): an update cannot see the stored document, so the rule
154
+ * it can enforce is "step 2 is only ever written together with step 1" — a
155
+ * payload that sets `vspPrivateNonprofit` to a boolean must set `vsp: true`
156
+ * in the same payload (top level or `$set`). Clearing step 2 (`null` /
157
+ * `$unset`) always holds. Exported so it can be unit-tested without a
158
+ * connection; the mount installs it on {@link AGENCY_ORG_TYPE_VALIDATED_UPDATE_OPS}.
159
+ */
160
+ export function vspTwoStepHoldsOnUpdate(update: unknown): boolean {
161
+ if (!update || typeof update !== "object") return true;
162
+ const u = update as Record<string, unknown>;
163
+ const set = { ...u, ...((u.$set as Record<string, unknown>) ?? {}) };
164
+ return vspTwoStepHolds({
165
+ vsp: set.vsp as boolean | null | undefined,
166
+ vspPrivateNonprofit: set.vspPrivateNonprofit as boolean | null | undefined,
167
+ });
168
+ }
169
+
170
+ // ─── Schema Definition ──────────────────────────────────────────────
171
+
172
+ /**
173
+ * The organization-type fields. ONE definition, mounted on the Org (home)
174
+ * and on the Agency (mirror) — see the module doc.
175
+ *
176
+ * All three are OPTIONAL and default to `undefined`. A document written
177
+ * before these fields existed hydrates and re-saves without gaining them, so
178
+ * "not attested" (absent) stays distinct from "attested false".
179
+ */
180
+ export const orgTypeSchemaDefinition = {
181
+ /**
182
+ * The agency's organization type: a CVC-48 key from
183
+ * {@link AGENCY_TYPE_KEYS} (a selectable org-type leaf, or the pre-backfill
184
+ * `unknown`). Set once in the Admin Hub; carried from the Org. Never free
185
+ * text — a value outside the enum fails validation on `save()` and, when
186
+ * the fragment is added with {@link addAgencyOrgTypeFields} (default
187
+ * options), on `updateOne` / `updateMany` / `findOneAndUpdate` too.
188
+ *
189
+ * ORDER OF ADOPTION (review MG2, pinned in org-type-contract.test.ts):
190
+ * Mongoose validates `init`-ed paths on `save()`, not only modified ones,
191
+ * so once a consumer adds this fragment, an agency document that carries a
192
+ * NON-KEY `type` (free text, "UNKNOWN", "multi_service", a number) fails
193
+ * its next save of ANY field. A document with no `type` at all saves fine.
194
+ * Backfill first (every stored value → a key or `unknown`), then adopt.
195
+ */
196
+ type: {
197
+ type: String,
198
+ enum: [...AGENCY_TYPE_KEYS],
199
+ index: true,
200
+ },
201
+ /**
202
+ * Is this organization a DV/SA victim service provider — the HMIS 2.01
203
+ * (Comparable Database) fact. Captured in the Admin Hub (never inferred
204
+ * from the type; the type only PROPOSES it — `orgTypeDefaultVsp`, the
205
+ * Hub's pre-fill — and HTI Labs affirms or changes it there). Tri-state:
206
+ * `true` / `false` / absent (not yet captured — a reader falls back to the
207
+ * proposal).
208
+ */
209
+ vsp: {
210
+ type: Boolean,
211
+ },
212
+ /**
213
+ * Step 2 of the two-step: private non-profit VSP (VOCA/OVC PMT
214
+ * distinction). Captured; tri-state; may only be `true`/`false` when
215
+ * `vsp === true` ({@link vspTwoStepHolds}, enforced at the mount).
216
+ */
217
+ vspPrivateNonprofit: {
218
+ type: Boolean,
219
+ },
220
+ };
221
+
222
+ /** @deprecated Same object as {@link orgTypeSchemaDefinition}; kept for 0.14-era callers. */
223
+ export const agencyOrgTypeSchemaDefinition = orgTypeSchemaDefinition;
224
+
225
+ /**
226
+ * The field names, in one place (the mirror copies exactly these). The
227
+ * `satisfies` ties the tuple to {@link OrgTypeFields} at compile time: a field
228
+ * added to the definition without being listed here fails `tsc`, so the
229
+ * mirror can never silently stop copying it (review nit).
230
+ */
231
+ export const ORG_TYPE_FIELD_NAMES = Object.freeze([
232
+ "type",
233
+ "vsp",
234
+ "vspPrivateNonprofit",
235
+ ] as const satisfies readonly (keyof OrgTypeFields)[]);
236
+ export type OrgTypeFieldName = (typeof ORG_TYPE_FIELD_NAMES)[number];
237
+
238
+ // ─── Schema Helper ──────────────────────────────────────────────────
239
+
240
+ /** Update operations on which the enum is enforced by {@link addAgencyOrgTypeFields}. */
241
+ export const AGENCY_ORG_TYPE_VALIDATED_UPDATE_OPS = Object.freeze([
242
+ "updateOne",
243
+ "updateMany",
244
+ "findOneAndUpdate",
245
+ ] as const);
246
+
247
+ export interface AddAgencyOrgTypeFieldsOptions {
248
+ /**
249
+ * Turn `runValidators` on (unless the caller set it explicitly) in the
250
+ * `pre` hook the mount installs on {@link AGENCY_ORG_TYPE_VALIDATED_UPDATE_OPS},
251
+ * so the enum holds on the update paths the auth service and the Admin Hub
252
+ * actually write through — Mongoose skips enum validators on update
253
+ * operations by default. Default `true`. The hook itself is ALWAYS
254
+ * installed: it also enforces the VSP two-step on the update payload
255
+ * ({@link vspTwoStepHoldsOnUpdate}), which is a shape rule, not a
256
+ * validator option, and cannot be opted out of.
257
+ */
258
+ validateOnUpdate?: boolean;
259
+ }
260
+
261
+ /**
262
+ * The hook body, exported so it can be unit-tested without a connection:
263
+ * sets `runValidators: true` on a query that has not said otherwise.
264
+ */
265
+ export function applyRunValidatorsIfUnset(
266
+ query: Pick<Query<unknown, unknown>, "getOptions" | "setOptions">,
267
+ ): void {
268
+ if (query.getOptions().runValidators === undefined) {
269
+ query.setOptions({ runValidators: true });
270
+ }
271
+ }
272
+
273
+ /**
274
+ * Mount the organization-type fields on a schema (shared body of the two
275
+ * public mounts). Adds the `type` index declared above and, by default, the
276
+ * update-path validation hook described on {@link AddAgencyOrgTypeFieldsOptions}.
277
+ *
278
+ * Mongoose `schema.add` REPLACES an existing `type` path wholesale: a
279
+ * consumer's own `required`, `default`, `enum`, `lowercase` / `trim`, and a
280
+ * numeric `type: Number` on that path are all dropped and the fragment's
281
+ * definition (enum over {@link AGENCY_TYPE_KEYS}, NOT required, indexed)
282
+ * stands. For Thread's free-text agency `type` and PAVE's numeric
283
+ * organization `type` that is the intended migration — `required` must come
284
+ * off until the backfill lands — but a consumer that relied on any other
285
+ * option on `type` re-declares it after calling this. (Pre-review finding
286
+ * D4 corrected the earlier wording, which claimed the opposite.) The fragment
287
+ * is written with the default `typeKey`; a schema constructed with a custom
288
+ * `typeKey` (none in the platform today) cannot take it as-is.
289
+ */
290
+ function mountOrgTypeFields<S extends Schema>(
291
+ schema: S,
292
+ options: AddAgencyOrgTypeFieldsOptions,
293
+ ): S {
294
+ schema.add(orgTypeSchemaDefinition);
295
+ // The two-step on save (review Blocker 2): a document with step 2 answered
296
+ // and step 1 not `true` fails validation on `vspPrivateNonprofit`. Runs on
297
+ // every save, so provisioning, the backfill and bulk writes through the
298
+ // model all hit it; a Zod `.extend` that forgot `.refine` is caught here.
299
+ // Registered through a narrow structural type: the generic `S extends
300
+ // Schema` loses Mongoose's `pre("validate")` overload, and the hook body
301
+ // THROWS a ValidationError rather than calling `invalidate()` (Mongoose 9
302
+ // does not surface `invalidate()` from a pre('validate') hook — verified
303
+ // 2026-10-08 against 9.3.1; a thrown ValidationError rejects `validate()`
304
+ // and therefore `save()` exactly like a path validator would).
305
+ (
306
+ schema as unknown as {
307
+ pre: (
308
+ method: "validate",
309
+ fn: (this: Document) => void | Promise<void>,
310
+ ) => unknown;
311
+ }
312
+ ).pre("validate", function (this: Document) {
313
+ const doc = this as unknown as {
314
+ vsp?: boolean | null;
315
+ vspPrivateNonprofit?: boolean | null;
316
+ };
317
+ if (!vspTwoStepHolds(doc)) {
318
+ const err = new MongooseError.ValidationError();
319
+ err.addError(
320
+ "vspPrivateNonprofit",
321
+ new MongooseError.ValidatorError({
322
+ path: "vspPrivateNonprofit",
323
+ message: VSP_TWO_STEP_ISSUE.message,
324
+ value: doc.vspPrivateNonprofit,
325
+ }),
326
+ );
327
+ throw err;
328
+ }
329
+ });
330
+ const validateOnUpdate = options.validateOnUpdate ?? true;
331
+ schema.pre(
332
+ [...AGENCY_ORG_TYPE_VALIDATED_UPDATE_OPS],
333
+ function (this: Query<unknown, unknown>) {
334
+ // The two-step on the update paths (always on — it is a shape rule,
335
+ // not a validator option); the enum via runValidators under the option.
336
+ if (!vspTwoStepHoldsOnUpdate(this.getUpdate())) {
337
+ throw new Error(VSP_TWO_STEP_ISSUE.message);
338
+ }
339
+ if (validateOnUpdate) applyRunValidatorsIfUnset(this);
340
+ },
341
+ );
342
+ return schema;
343
+ }
344
+
345
+ /**
346
+ * Add the organization-type fields to an **Org** (registry) schema — the
347
+ * HOME of the type and the attested HMIS facts (UDD Org Data Object). This
348
+ * is the mount the Admin Hub writes through.
349
+ *
350
+ * @param schema - The consumer's organization schema (platform-db `organizations`)
351
+ * @param options - See {@link AddAgencyOrgTypeFieldsOptions}
352
+ * @returns The same schema, for chaining
353
+ */
354
+ export function addOrgTypeFields<S extends Schema>(
355
+ schema: S,
356
+ options: AddAgencyOrgTypeFieldsOptions = {},
357
+ ): S {
358
+ return mountOrgTypeFields(schema, options);
359
+ }
360
+
361
+ /**
362
+ * Add the organization-type fields to an **Agency** schema as a MIRROR of
363
+ * its Org's (same definition, same enum, same hook). The copy is stamped
364
+ * from the Org via {@link mirrorOrgTypeFields} — at provisioning, and by the
365
+ * backfill — and is never edited on the agency directly. An agency that has
366
+ * no `organizationId` yet carries the backfill's confirmed value until it is
367
+ * linked; once linked, the Org wins.
368
+ *
369
+ * @param schema - The consumer's agency schema (platform-db `agencies`)
370
+ * @param options - See {@link AddAgencyOrgTypeFieldsOptions}
371
+ * @returns The same schema, for chaining
372
+ */
373
+ export function addAgencyOrgTypeFields<S extends Schema>(
374
+ schema: S,
375
+ options: AddAgencyOrgTypeFieldsOptions = {},
376
+ ): S {
377
+ return mountOrgTypeFields(schema, options);
378
+ }
379
+
380
+ /** Anything that may carry the fields: an Org document, an Agency document, a plain object. */
381
+ export type OrgTypeFieldsHolder = Partial<Record<OrgTypeFieldName, unknown>>;
382
+
383
+ /** The fields, picked exactly, `null` and `undefined` both left out (no assertion — see {@link mirrorOrgTypeFields}). */
384
+ function pickOrgTypeFields(
385
+ src: OrgTypeFieldsHolder | null | undefined,
386
+ ): AgencyOrgTypeFields {
387
+ const out: Record<string, unknown> = {};
388
+ if (src) {
389
+ for (const k of ORG_TYPE_FIELD_NAMES) {
390
+ const v = src[k];
391
+ if (v != null) out[k] = v; // review nit: `null` on the Org must not leak into the copy
392
+ }
393
+ }
394
+ return out as AgencyOrgTypeFields;
395
+ }
396
+
397
+ /**
398
+ * The one way to produce the Agency's copy: the Org's fields, exactly, with
399
+ * absent values kept absent (an Org that never attested `vsp` yields an
400
+ * agency that never attested it — a copy never coerces a `false`; a `null`
401
+ * is treated as absent, not copied). Any other key on the Org document is
402
+ * ignored. Use it wherever an agency is created from, or re-linked to, its
403
+ * Org, and on EVERY Org write of these fields (the re-stamp invariant in the
404
+ * module doc).
405
+ *
406
+ * The copy ASSERTS the two-step (review Blocker 2): a malformed Org
407
+ * (`vspPrivateNonprofit` answered without `vsp: true`) throws here rather
408
+ * than being laundered onto the agency.
409
+ */
410
+ export function mirrorOrgTypeFields(
411
+ org: OrgTypeFieldsHolder | null | undefined,
412
+ ): AgencyOrgTypeFields {
413
+ const out = pickOrgTypeFields(org);
414
+ if (!vspTwoStepHolds(out)) {
415
+ throw new Error(`mirrorOrgTypeFields: ${VSP_TWO_STEP_ISSUE.message}`);
416
+ }
417
+ return out;
418
+ }
419
+
420
+ // ─── Read precedence: the Org wins once linked (review Blocker 1) ───────────
421
+
422
+ /**
423
+ * The effective organization-type fields for an agency: the Org's when the
424
+ * agency is LINKED (`organizationId` set) and the Org was loaded; otherwise
425
+ * the agency's own copy (the backfill's confirmed value, until the link
426
+ * exists); `{}` when neither carries anything. No guessing: an unlinked
427
+ * agency with no copy answers nothing, in line with the 2026-10-07 rule that
428
+ * an org → agency read with no clear answer "answers nobody rather than
429
+ * guessing". Every consumer (Thread, PAVE, tooling) goes through this during
430
+ * the interim so the precedence cannot diverge between apps.
431
+ *
432
+ * @param org - The agency's Org document, if the caller joined it (`null` when not loaded / not linked)
433
+ * @param agency - The agency document (its `organizationId` decides "linked")
434
+ */
435
+ export function resolveEffectiveOrgTypeFields(
436
+ org: OrgTypeFieldsHolder | null | undefined,
437
+ agency:
438
+ (OrgTypeFieldsHolder & { organizationId?: unknown }) | null | undefined,
439
+ ): AgencyOrgTypeFields {
440
+ const linked = agency != null && agency.organizationId != null;
441
+ if (linked && org) return pickOrgTypeFields(org);
442
+ return pickOrgTypeFields(agency);
443
+ }
444
+
445
+ /** {@link resolveEffectiveOrgTypeFields}, reduced to the one key readers join on (`null` = un-typed / unresolvable, read as `unknown`). */
446
+ export function resolveEffectiveOrgType(
447
+ org: OrgTypeFieldsHolder | null | undefined,
448
+ agency:
449
+ (OrgTypeFieldsHolder & { organizationId?: unknown }) | null | undefined,
450
+ ): AgencyTypeKey | null {
451
+ return resolveAgencyTypeKey(resolveEffectiveOrgTypeFields(org, agency).type);
452
+ }
453
+
454
+ /**
455
+ * The fields on which the agency's copy differs from its Org — empty when the
456
+ * mirror is faithful. Absent and `null` compare equal to each other (both
457
+ * are "not captured"); any other difference is drift from a writer that
458
+ * skipped the re-stamp. A reader should log it and read the Org.
459
+ */
460
+ export function orgTypeFieldsDiffer(
461
+ org: OrgTypeFieldsHolder | null | undefined,
462
+ agency: OrgTypeFieldsHolder | null | undefined,
463
+ ): OrgTypeFieldName[] {
464
+ const a = pickOrgTypeFields(org) as Record<string, unknown>;
465
+ const b = pickOrgTypeFields(agency) as Record<string, unknown>;
466
+ return ORG_TYPE_FIELD_NAMES.filter((k) => a[k] !== b[k]);
467
+ }
468
+
469
+ // ─── Type Inference ─────────────────────────────────────────────────
470
+
471
+ /**
472
+ * Raw (persistence) shape of the organization-type fields. Inferred from the
473
+ * DEFINITION, not from a compiled `Schema` (see `schemas/team.ts` for why),
474
+ * and wrapped in `Partial` because every field is absent on documents that
475
+ * predate them.
476
+ */
477
+ export type OrgTypeFields = Partial<
478
+ InferRawDocType<typeof orgTypeSchemaDefinition>
479
+ >;
480
+ /** The Agency's mirror has the Org's exact shape. */
481
+ export type AgencyOrgTypeFields = OrgTypeFields;
@@ -108,3 +108,27 @@ export {
108
108
  cvcEntrySchemaOptions,
109
109
  type CvcEntry,
110
110
  } from "./cvcEntry.js";
111
+
112
+ // Organization-type fields: Org home (`addOrgTypeFields`) + Agency mirror
113
+ // (`addAgencyOrgTypeFields`, stamped with `mirrorOrgTypeFields`)
114
+ export {
115
+ AGENCY_ORG_TYPE_VALIDATED_UPDATE_OPS,
116
+ ORG_TYPE_FIELD_NAMES,
117
+ orgTypeSchemaDefinition,
118
+ agencyOrgTypeSchemaDefinition,
119
+ addOrgTypeFields,
120
+ addAgencyOrgTypeFields,
121
+ mirrorOrgTypeFields,
122
+ resolveEffectiveOrgTypeFields,
123
+ resolveEffectiveOrgType,
124
+ orgTypeFieldsDiffer,
125
+ applyRunValidatorsIfUnset,
126
+ vspTwoStepHolds,
127
+ vspTwoStepHoldsOnUpdate,
128
+ VSP_TWO_STEP_ISSUE,
129
+ type AddAgencyOrgTypeFieldsOptions,
130
+ type OrgTypeFields,
131
+ type OrgTypeFieldName,
132
+ type OrgTypeFieldsHolder,
133
+ type AgencyOrgTypeFields,
134
+ } from "./agency.js";