@htilabs/platform-common-models 0.17.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.
- package/dist/agency-BHv54o79.d.ts +484 -0
- package/dist/agency-Ca4pCOOf.d.ts +342 -0
- package/dist/agency-DYCv839V.d.cts +342 -0
- package/dist/agency-Djp57S71.d.cts +484 -0
- package/dist/constants/index.cjs +952 -0
- package/dist/constants/index.cjs.map +1 -1
- package/dist/constants/index.d.cts +3 -1
- package/dist/constants/index.d.ts +3 -1
- package/dist/constants/index.js +920 -0
- package/dist/constants/index.js.map +1 -1
- package/dist/{cvcEntry-ctHTp2df.d.cts → cvcEntry-0BIB9sen.d.cts} +36 -36
- package/dist/{cvcEntry-ctHTp2df.d.ts → cvcEntry-0BIB9sen.d.ts} +36 -36
- package/dist/cvcs/index.cjs +114 -62
- package/dist/cvcs/index.cjs.map +1 -1
- package/dist/cvcs/index.d.cts +112 -59
- package/dist/cvcs/index.d.ts +112 -59
- package/dist/cvcs/index.js +114 -62
- package/dist/cvcs/index.js.map +1 -1
- package/dist/enums/index.cjs +1 -0
- package/dist/enums/index.cjs.map +1 -1
- package/dist/enums/index.d.cts +2 -1
- package/dist/enums/index.d.ts +2 -1
- package/dist/enums/index.js +1 -0
- package/dist/enums/index.js.map +1 -1
- package/dist/{index-4DiJrn7y.d.ts → index-CDoqrfc1.d.ts} +1 -1
- package/dist/{index-qreOzXYS.d.cts → index-Zu_mOJRn.d.cts} +1 -1
- package/dist/index.cjs +1654 -1077
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +6 -4
- package/dist/index.d.ts +6 -4
- package/dist/index.js +1600 -1076
- package/dist/index.js.map +1 -1
- package/dist/models/index.d.cts +2 -2
- package/dist/models/index.d.ts +2 -2
- package/dist/org-type-BYQb9Qzq.d.ts +366 -0
- package/dist/org-type-D_FG4KdN.d.cts +366 -0
- package/dist/{platform-auth-CrF5U_JH.d.cts → platform-auth-CvAYFVhK.d.cts} +39 -0
- package/dist/{platform-auth-CrF5U_JH.d.ts → platform-auth-CvAYFVhK.d.ts} +39 -0
- package/dist/schemas/index.cjs +977 -2
- package/dist/schemas/index.cjs.map +1 -1
- package/dist/schemas/index.d.cts +14 -11
- package/dist/schemas/index.d.ts +14 -11
- package/dist/schemas/index.js +962 -1
- package/dist/schemas/index.js.map +1 -1
- package/dist/types/index.d.cts +2 -2
- package/dist/types/index.d.ts +2 -2
- package/dist/validation/index.cjs +894 -2
- package/dist/validation/index.cjs.map +1 -1
- package/dist/validation/index.d.cts +5 -1
- package/dist/validation/index.d.ts +5 -1
- package/dist/validation/index.js +884 -1
- package/dist/validation/index.js.map +1 -1
- package/package.json +26 -27
- package/src/__tests__/__snapshots__/cvc-sot.snap +2 -2
- package/src/__tests__/cvc-sot-snapshot.test.ts +5 -5
- package/src/__tests__/cvc-structural.test.ts +1 -1
- package/src/__tests__/org-type-contract.test.ts +1353 -0
- package/src/__tests__/referral-entity-category-canon.test.ts +255 -81
- package/src/constants/ic.ts +45 -0
- package/src/constants/index.ts +1 -0
- package/src/constants/org-type.ts +703 -0
- package/src/cvcs/index.ts +1 -1
- package/src/cvcs/{referralEntityCategory.v1.1.0.json → referralEntityCategory.v1.2.0.json} +111 -59
- package/src/generated/cvc-enums.ts +2 -1
- package/src/index.ts +23 -0
- package/src/schemas/agency.ts +481 -0
- package/src/schemas/index.ts +24 -0
- package/src/validation/agency.ts +119 -0
- package/src/validation/index.ts +1 -0
- package/dist/team-C4LJ5Tex.d.cts +0 -333
- package/dist/team-C4LJ5Tex.d.ts +0 -333
|
@@ -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;
|
package/src/schemas/index.ts
CHANGED
|
@@ -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";
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @htilabs/platform-common-models — Agency organization-type field validation
|
|
3
|
+
*
|
|
4
|
+
* Zod schemas for the organization-type fields declared in
|
|
5
|
+
* `../schemas/agency.ts`. These are WRITE shapes — what an Admin Hub
|
|
6
|
+
* "Organization Type" write, a provisioning payload or a backfill row may
|
|
7
|
+
* carry. They are deliberately strict: a legacy free-text `type` or a
|
|
8
|
+
* `null` does not parse. Do not validate a pre-backfill `/me` or directory
|
|
9
|
+
* READ with them; until the backfill lands, a read may still carry free text
|
|
10
|
+
* (resolve it with `resolveAgencyTypeKey`, which answers `null` for it).
|
|
11
|
+
* See `../schemas/agency.ts` and `../constants/org-type.ts` for the ruling
|
|
12
|
+
* and the vocabulary.
|
|
13
|
+
*
|
|
14
|
+
* Merge the fields into a consumer's org / agency schema with
|
|
15
|
+
* {@link withOrgTypeFields} — it adds the fields AND re-applies the two-step
|
|
16
|
+
* rule in one call. The raw `orgTypeFieldsShape` is still exported for a
|
|
17
|
+
* consumer that must build its own object, but `.extend(orgTypeFieldsShape)`
|
|
18
|
+
* without `.refine(vspTwoStepHolds, VSP_TWO_STEP_ISSUE)` silently drops the
|
|
19
|
+
* rule (review nit — the extend-without-refine footgun); prefer the helper.
|
|
20
|
+
* The Mongoose mount enforces the same rule on save and update regardless,
|
|
21
|
+
* so a forgotten refine is caught at the database, not persisted.
|
|
22
|
+
* (ORG-TYPE-REVIEW-ROUND-2026-10-08)
|
|
23
|
+
*
|
|
24
|
+
* Naming: `OrgTypeSelectableKey*` means a SELECTABLE leaf (what may be set);
|
|
25
|
+
* `AgencyTypeKey*` means a STORABLE value (a leaf or `unknown`). The
|
|
26
|
+
* constants module's `OrgTypeKey` is wider than both — heading OR leaf — and
|
|
27
|
+
* is never a write type.
|
|
28
|
+
*/
|
|
29
|
+
|
|
30
|
+
import { z } from "zod";
|
|
31
|
+
import {
|
|
32
|
+
AGENCY_TYPE_KEYS,
|
|
33
|
+
ORG_TYPE_SELECTABLE_KEYS,
|
|
34
|
+
type AgencyTypeKey,
|
|
35
|
+
type OrgTypeSelectableKey,
|
|
36
|
+
} from "../constants/org-type.js";
|
|
37
|
+
import { VSP_TWO_STEP_ISSUE, vspTwoStepHolds } from "../schemas/agency.js";
|
|
38
|
+
|
|
39
|
+
// The two-step predicate lives with the Mongoose mount (one definition,
|
|
40
|
+
// enforced in Zod, on save, on update and in the mirror); re-exported here so
|
|
41
|
+
// `validation` callers keep their import.
|
|
42
|
+
export { VSP_TWO_STEP_ISSUE, vspTwoStepHolds };
|
|
43
|
+
|
|
44
|
+
/** An org type the Admin Hub may SET: a selectable CVC-48 org-type leaf. */
|
|
45
|
+
export const OrgTypeSelectableKeySchema = z.enum(ORG_TYPE_SELECTABLE_KEYS);
|
|
46
|
+
|
|
47
|
+
/** An org type an agency may be STORED with: a selectable leaf or `unknown`. */
|
|
48
|
+
export const AgencyTypeKeySchema = z.enum(AGENCY_TYPE_KEYS);
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* The organization-type fields on an agency, as a WRITE shape. All optional,
|
|
52
|
+
* so an agency payload without them validates unchanged; when present each
|
|
53
|
+
* must be well-formed (`type` a storable key, the booleans booleans).
|
|
54
|
+
*/
|
|
55
|
+
export const orgTypeFieldsShape = {
|
|
56
|
+
type: AgencyTypeKeySchema.optional(),
|
|
57
|
+
vsp: z.boolean().optional(),
|
|
58
|
+
vspPrivateNonprofit: z.boolean().optional(),
|
|
59
|
+
} as const;
|
|
60
|
+
export const AgencyOrgTypeFieldsSchema = z
|
|
61
|
+
.object(orgTypeFieldsShape)
|
|
62
|
+
.refine(vspTwoStepHolds, VSP_TWO_STEP_ISSUE);
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* A consumer's own org / agency write shape PLUS the organization-type
|
|
66
|
+
* fields, with the two-step rule applied — the one call that cannot forget
|
|
67
|
+
* the refine. `withOrgTypeFields({ name: z.string() })` ≡
|
|
68
|
+
* `z.object({ name, ...orgTypeFieldsShape }).refine(vspTwoStepHolds, …)`.
|
|
69
|
+
*/
|
|
70
|
+
export function withOrgTypeFields<T extends z.ZodRawShape>(shape: T) {
|
|
71
|
+
return z
|
|
72
|
+
.object({ ...shape, ...orgTypeFieldsShape })
|
|
73
|
+
.refine(vspTwoStepHolds, VSP_TWO_STEP_ISSUE);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** The same WRITE shape, named for its home: the Org registry row. */
|
|
77
|
+
export const OrgTypeFieldsSchema = AgencyOrgTypeFieldsSchema;
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* What the Admin Hub writes when it sets an organization's type: the type
|
|
81
|
+
* itself (required; a selectable leaf — never `unknown`, never a heading),
|
|
82
|
+
* with the two attested answers. `vsp` and `vspPrivateNonprofit` are
|
|
83
|
+
* privileged writes (the sender's `vsp` decides the release check), so the
|
|
84
|
+
* shape is `.strict()`: an unexpected key is rejected rather than ignored.
|
|
85
|
+
* `requires_roi` is NOT written through this shape — it is not one of the
|
|
86
|
+
* organization-type fields (informational, GDR § 5.17; parked Q-O5).
|
|
87
|
+
*/
|
|
88
|
+
export const SetOrgTypeInputSchema = z
|
|
89
|
+
.object({
|
|
90
|
+
type: OrgTypeSelectableKeySchema,
|
|
91
|
+
vsp: z.boolean().optional(),
|
|
92
|
+
vspPrivateNonprofit: z.boolean().optional(),
|
|
93
|
+
})
|
|
94
|
+
.strict()
|
|
95
|
+
.refine(vspTwoStepHolds, VSP_TWO_STEP_ISSUE);
|
|
96
|
+
|
|
97
|
+
/** A selectable leaf, as the Zod schema infers it (= {@link OrgTypeSelectableKey}). */
|
|
98
|
+
export type OrgTypeSelectableKeyInput = OrgTypeSelectableKey;
|
|
99
|
+
/** A storable agency type, as the Zod schema infers it (= {@link AgencyTypeKey}). */
|
|
100
|
+
export type AgencyTypeKeyInput = AgencyTypeKey;
|
|
101
|
+
export type AgencyOrgTypeFieldsInput = z.infer<
|
|
102
|
+
typeof AgencyOrgTypeFieldsSchema
|
|
103
|
+
>;
|
|
104
|
+
export type SetOrgTypeInput = z.infer<typeof SetOrgTypeInputSchema>;
|
|
105
|
+
|
|
106
|
+
// Compile-time pin: the Zod-inferred unions equal the constants' types.
|
|
107
|
+
const _selectablePin: z.infer<
|
|
108
|
+
typeof OrgTypeSelectableKeySchema
|
|
109
|
+
> extends OrgTypeSelectableKey
|
|
110
|
+
? OrgTypeSelectableKey extends z.infer<typeof OrgTypeSelectableKeySchema>
|
|
111
|
+
? true
|
|
112
|
+
: never
|
|
113
|
+
: never = true;
|
|
114
|
+
const _agencyPin: z.infer<typeof AgencyTypeKeySchema> extends AgencyTypeKey
|
|
115
|
+
? AgencyTypeKey extends z.infer<typeof AgencyTypeKeySchema>
|
|
116
|
+
? true
|
|
117
|
+
: never
|
|
118
|
+
: never = true;
|
|
119
|
+
void [_selectablePin, _agencyPin];
|
package/src/validation/index.ts
CHANGED