@htilabs/platform-common-models 0.21.0 → 0.22.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 (40) hide show
  1. package/dist/cvcs/index.cjs +449 -50
  2. package/dist/cvcs/index.cjs.map +1 -1
  3. package/dist/cvcs/index.d.cts +491 -55
  4. package/dist/cvcs/index.d.ts +491 -55
  5. package/dist/cvcs/index.js +449 -50
  6. package/dist/cvcs/index.js.map +1 -1
  7. package/dist/enums/index.cjs +36 -1
  8. package/dist/enums/index.cjs.map +1 -1
  9. package/dist/enums/index.d.cts +37 -2
  10. package/dist/enums/index.d.ts +37 -2
  11. package/dist/enums/index.js +36 -1
  12. package/dist/enums/index.js.map +1 -1
  13. package/dist/index.cjs +589 -51
  14. package/dist/index.cjs.map +1 -1
  15. package/dist/index.d.cts +1 -1
  16. package/dist/index.d.ts +1 -1
  17. package/dist/index.js +580 -51
  18. package/dist/index.js.map +1 -1
  19. package/dist/schemas/index.cjs +104 -0
  20. package/dist/schemas/index.cjs.map +1 -1
  21. package/dist/schemas/index.d.cts +240 -1
  22. package/dist/schemas/index.d.ts +240 -1
  23. package/dist/schemas/index.js +95 -0
  24. package/dist/schemas/index.js.map +1 -1
  25. package/package.json +1 -1
  26. package/src/__sot__/README.md +1 -0
  27. package/src/__sot__/coreFunctionFields.ts +121 -0
  28. package/src/__sot__/coreFunctions.pin.json +1546 -0
  29. package/src/__sot__/coreFunctions.published.json +233 -0
  30. package/src/__tests__/__snapshots__/cvc-sot.snap +2 -2
  31. package/src/__tests__/core-functions-canon.test.ts +308 -24
  32. package/src/__tests__/cvc-sot-snapshot.test.ts +7 -4
  33. package/src/__tests__/cvc-status-parser.test.ts +1 -1
  34. package/src/__tests__/cvc-structural.test.ts +1 -1
  35. package/src/__tests__/organization-program.test.ts +254 -0
  36. package/src/cvcs/{coreFunctions.v1.1.0.json → coreFunctions.v1.2.0.json} +446 -47
  37. package/src/cvcs/index.ts +1 -1
  38. package/src/generated/cvc-enums.ts +37 -2
  39. package/src/schemas/index.ts +18 -0
  40. package/src/schemas/organization-program.ts +297 -0
package/src/cvcs/index.ts CHANGED
@@ -162,7 +162,7 @@ import immigrationLegalStatusChangeTypeSot from "./immigrationLegalStatusChangeT
162
162
  import programEnrollmentChangeTypeSot from "./programEnrollmentChangeType.v1.0.0.json" with { type: "json" };
163
163
  import romanticRelationshipChangeTypeSot from "./romanticRelationshipChangeType.v1.0.0.json" with { type: "json" };
164
164
  import riskCategorySot from "./riskCategory.v1.0.0.json" with { type: "json" };
165
- import coreFunctionsSot from "./coreFunctions.v1.1.0.json" with { type: "json" };
165
+ import coreFunctionsSot from "./coreFunctions.v1.2.0.json" with { type: "json" };
166
166
  import needsAssessmentChangeTypeSot from "./needsAssessmentChangeType.v1.0.0.json" with { type: "json" };
167
167
  import coreInformationScopeSot from "./coreInformationScope.v2.1.0.json" with { type: "json" };
168
168
  import roiScopeSot from "./roiScope.v1.4.0.json" with { type: "json" };
@@ -3987,9 +3987,9 @@ export const RiskCategoryKeys = {
3987
3987
  export type RiskCategoryKey = keyof typeof RiskCategoryKeys;
3988
3988
 
3989
3989
  /**
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
+ * Key → positional code map for the `core_functions` CVC domain (CANONICAL Notion CVC-133 `core - functions`, Active v2.0 — the Canonical Authorization Model function registry; SOT v1.2.0 is GENERATED from the prototype repo's data/cvcs/core_functions.yaml by scripts/gen-core-functions.py: 113 functions — the 78 published by 1.0.0/1.1.0 at their codes plus 35 appended at 133-079 … 133-113 — the roles → functions → gates/tiers graph is built over. NOT provisional numbering. Per-entry lifecycle Status (v1 / not v1), Platform Relevance, user/admin relevance and Category are carried in each entry's definition suffix, since the CVC entry schema has no fields for them; bounds are not carried).
3991
3991
  *
3992
- * Domain: `core_functions` · Version: 1.1.0 · Entries: 82
3992
+ * Domain: `core_functions` · Version: 1.2.0 · Entries: 117
3993
3993
  */
3994
3994
  export const CoreFunctionsKeys = {
3995
3995
  missingness_root: "133-000-000-000-000-000-000",
@@ -4074,6 +4074,41 @@ export const CoreFunctionsKeys = {
4074
4074
  training_gate_manage: "133-076-000-000-000-000-000",
4075
4075
  usr_manage: "133-077-000-000-000-000-000",
4076
4076
  note_open_departed_author: "133-078-000-000-000-000-000",
4077
+ agency_info_manage: "133-079-000-000-000-000-000",
4078
+ srl_manage: "133-080-000-000-000-000-000",
4079
+ mandatory_report_send: "133-081-000-000-000-000-000",
4080
+ indicator_manual_add: "133-082-000-000-000-000-000",
4081
+ message_send: "133-083-000-000-000-000-000",
4082
+ workgroup_manage: "133-084-000-000-000-000-000",
4083
+ message_moderate: "133-085-000-000-000-000-000",
4084
+ announcement_publish: "133-086-000-000-000-000-000",
4085
+ supervisee_thread_view: "133-087-000-000-000-000-000",
4086
+ case_status_manage: "133-088-000-000-000-000-000",
4087
+ enrollment_manage: "133-089-000-000-000-000-000",
4088
+ exit_discharge_conduct: "133-090-000-000-000-000-000",
4089
+ goals_plan_manage: "133-091-000-000-000-000-000",
4090
+ lead_triage_manage: "133-092-000-000-000-000-000",
4091
+ milestone_log: "133-093-000-000-000-000-000",
4092
+ needs_priorities_conduct: "133-094-000-000-000-000-000",
4093
+ profile_domain_edit: "133-095-000-000-000-000-000",
4094
+ record_activity_view: "133-096-000-000-000-000-000",
4095
+ service_log_manage: "133-097-000-000-000-000-000",
4096
+ case_close: "133-098-000-000-000-000-000",
4097
+ case_visibility_manage: "133-099-000-000-000-000-000",
4098
+ person_merge_manage: "133-100-000-000-000-000-000",
4099
+ investigation_session_run: "133-101-000-000-000-000-000",
4100
+ lead_route_assign: "133-102-000-000-000-000-000",
4101
+ onboarding_config_sign_off: "133-103-000-000-000-000-000",
4102
+ hmis_export_generate: "133-104-000-000-000-000-000",
4103
+ team_share_narrowing: "133-105-000-000-000-000-000",
4104
+ viewing_config_manage: "133-106-000-000-000-000-000",
4105
+ network_corpus_access: "133-107-000-000-000-000-000",
4106
+ viewing_level_1_search: "133-108-000-000-000-000-000",
4107
+ viewing_level_2_autocomplete: "133-109-000-000-000-000-000",
4108
+ viewing_level_3_components: "133-110-000-000-000-000-000",
4109
+ investigative_request_send: "133-111-000-000-000-000-000",
4110
+ deconfliction_unmask: "133-112-000-000-000-000-000",
4111
+ share_revoke: "133-113-000-000-000-000-000",
4077
4112
  } as const;
4078
4113
 
4079
4114
  export type CoreFunctionsKey = keyof typeof CoreFunctionsKeys;
@@ -132,3 +132,21 @@ export {
132
132
  type OrgTypeFieldsHolder,
133
133
  type AgencyOrgTypeFields,
134
134
  } from "./agency.js";
135
+
136
+ // Organization program rows (`organizations.programs[]`): the one definition
137
+ // both apps mount (`addOrganizationProgramsField`), the review-status
138
+ // vocabulary and the live-row rule
139
+ export {
140
+ PROGRAM_REVIEW_STATUS,
141
+ PROGRAM_REVIEW_STATUS_VALUES,
142
+ organizationProgramSchemaDefinition,
143
+ buildOrganizationProgramsFieldDefinition,
144
+ ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS,
145
+ buildOrganizationProgramSchema,
146
+ addOrganizationProgramsField,
147
+ type AddOrganizationProgramsFieldOptions,
148
+ isLiveOrganizationProgram,
149
+ isProgramReviewStatus,
150
+ type OrganizationProgram,
151
+ type ProgramReviewStatus,
152
+ } from "./organization-program.js";
@@ -0,0 +1,297 @@
1
+ /**
2
+ * @htilabs/platform-common-models — Organization program rows (`organizations.programs[]`)
3
+ *
4
+ * The ONE definition of the embedded program sub-document on the platform-db
5
+ * `organizations` collection, which both apps read and PAVE 2.0 writes.
6
+ *
7
+ * ## This is a FRAGMENT, not an Organization model
8
+ *
9
+ * No canonical Organization schema exists in this package (same posture as
10
+ * `schemas/team.ts` and `schemas/agency.ts`). `organizations` is written by
11
+ * PAVE 2.0 (`packages/db/src/models/organization.ts`) and read by Thread
12
+ * (`packages/db/src/models/platform/Organization.ts`, `select: false` on
13
+ * `programs`, read with `+programs`). Until this module, each app carried its
14
+ * own copy of the sub-schema — identical by hand. This module declares the
15
+ * program row ONCE; each consumer mounts it with
16
+ * {@link addOrganizationProgramsField} or builds the sub-schema with
17
+ * {@link buildOrganizationProgramSchema}.
18
+ *
19
+ * ## Canon
20
+ *
21
+ * - **UDD Program Data Object** (hti-features `udd-schemas/program/Program.v1.json`;
22
+ * profile confirmed by Crysta 2026-10-05): a Program (program / department /
23
+ * operational division / law-enforcement unit) is a fact about an
24
+ * ORGANIZATION — `org_id` is the owner. Its arrival is stored: `added_by`,
25
+ * `added_in_app`, `review_status`.
26
+ * - **PROGRAM-APP-ADDED** (prototype 2026-10-06; Crysta 2026-10-02: users
27
+ * "need to be able to capture org names and program names that may not be
28
+ * in existing list"): a program named inside an app is the organization's
29
+ * program from the moment it is typed, and waits for HTI Labs' review like a
30
+ * new organization does (GDR § 5.12 / § 5.16 rule 1). The steward's review
31
+ * queue in the HTI Platform confirms or rejects it; a confirmed row's "new"
32
+ * mark clears.
33
+ * - **ADR D13** (PAVE Greenfield): `SharingSettings` keys on
34
+ * `(organizationId, programId?)` — the program id is the join key an
35
+ * agency may share to.
36
+ *
37
+ * ## Field names
38
+ *
39
+ * Canon's program sheet spells these `program_id`, `label`, `review_status`,
40
+ * `added_by`, `added_in_app` (snake_case CSV columns). The live platform-db
41
+ * writers use camelCase (`programId`, `name`, `defaultSharingPolicy` are what
42
+ * PAVE 2.0 and Thread already store), so the arrival fields follow that
43
+ * convention: `reviewStatus`, `addedBy`, `addedInApp`, `addedInSession`.
44
+ *
45
+ * `addedInApp` is where the program was NAMED, not the program's own app
46
+ * (which app it operates in stays blank until the Admin Hub says).
47
+ *
48
+ * `addedInSession` is NOT on the UDD Program sheet (`Program.v1.json` carries
49
+ * `review_status · added_by · added_in_app` only). It is carried on the same
50
+ * precedent as the Org object's `added_in_session` (as-built OrgEntry overlay;
51
+ * RULED 2026-08-27 a migration note that retires into the `dataSource`
52
+ * provenance envelope at the cut-over) so a picker can tell "named in THIS
53
+ * session" from "awaiting review" across a reload. It retires with that trio.
54
+ *
55
+ * The sub-schema is STRICT (Mongoose default): a key outside the definition
56
+ * — including the sheet's snake_case spellings (`review_status`,
57
+ * `added_by`) — is dropped silently on cast, not rejected. Write camelCase.
58
+ *
59
+ * ## Who dedupes
60
+ *
61
+ * `programId` uniqueness and name-matching on add are the WRITER's job; the
62
+ * fragment enforces neither (two rows with one id validate and `$push`).
63
+ * PAVE 2.0's `POST /organizations/:id/programs` dedupes a typed name against
64
+ * the live rows (trimmed, case-insensitive) and mints `programId` server-side.
65
+ *
66
+ * ## Missingness
67
+ *
68
+ * `reviewStatus` is ABSENT (or null) on a steward row — nothing to review.
69
+ * There is no UNK / ANON / DNC here: the status is a lifecycle, not an
70
+ * answer anyone gives.
71
+ */
72
+
73
+ import { Schema } from "mongoose";
74
+ import type { InferRawDocType, Query } from "mongoose";
75
+
76
+ import { applyRunValidatorsIfUnset } from "./agency.js";
77
+
78
+ // ─── Review status ──────────────────────────────────────────────────
79
+
80
+ /**
81
+ * Review lifecycle of a program named inside an app (UDD Program
82
+ * `review_status`). The sheet's own words — a lane's `pending_steward` /
83
+ * `declined` never reach the stored row.
84
+ */
85
+ export const PROGRAM_REVIEW_STATUS = {
86
+ PENDING: "pending",
87
+ CONFIRMED: "confirmed",
88
+ REJECTED: "rejected",
89
+ } as const;
90
+
91
+ export type ProgramReviewStatus =
92
+ (typeof PROGRAM_REVIEW_STATUS)[keyof typeof PROGRAM_REVIEW_STATUS];
93
+
94
+ /** The three values, for `enum:` declarations and Zod `z.enum`. */
95
+ export const PROGRAM_REVIEW_STATUS_VALUES = Object.freeze([
96
+ PROGRAM_REVIEW_STATUS.PENDING,
97
+ PROGRAM_REVIEW_STATUS.CONFIRMED,
98
+ PROGRAM_REVIEW_STATUS.REJECTED,
99
+ ] as const);
100
+
101
+ export function isProgramReviewStatus(
102
+ value: unknown,
103
+ ): value is ProgramReviewStatus {
104
+ return (
105
+ typeof value === "string" &&
106
+ (PROGRAM_REVIEW_STATUS_VALUES as readonly string[]).includes(value)
107
+ );
108
+ }
109
+
110
+ // ─── Schema Definition ──────────────────────────────────────────────
111
+
112
+ /**
113
+ * One embedded Organization > Program row. `programId` + `name` are the
114
+ * load-bearing identity/label; everything else is optional and additive.
115
+ *
116
+ * `status` and `defaultSharingPolicy` are typed string codes (as PAVE 2.0 and
117
+ * Thread already store them — the CVC bind is a follow-up on the codebook,
118
+ * not this fragment).
119
+ */
120
+ export const organizationProgramSchemaDefinition = {
121
+ /** Stable identifier for the program within its Organization (server-minted). */
122
+ programId: { type: String, required: true },
123
+ /** Human-facing program name (canon `label`). */
124
+ name: { type: String, required: true },
125
+ /** Free-text program description. */
126
+ description: { type: String, required: false },
127
+ /** Lifecycle code; a `retired` program is not offered to pickers. */
128
+ status: { type: String, required: false },
129
+ /** Default sharing-policy code applied when sharing to this program (ADR D13). */
130
+ defaultSharingPolicy: { type: String, required: false },
131
+ /**
132
+ * pending · confirmed · rejected for a program named inside an app; absent on
133
+ * a steward row. A `rejected` row is never offered and never captures its
134
+ * name on a later add (a new row is minted).
135
+ */
136
+ reviewStatus: {
137
+ type: String,
138
+ required: false,
139
+ enum: [...PROGRAM_REVIEW_STATUS_VALUES],
140
+ },
141
+ /** The seat (user id) that named it inside an app. */
142
+ addedBy: { type: String, required: false },
143
+ /** The app it was NAMED in (`pave` · `thread` · `leads` · `platform`). */
144
+ addedInApp: { type: String, required: false },
145
+ /** The session it was named in, when there was one. */
146
+ addedInSession: { type: String, required: false },
147
+ } as const;
148
+
149
+ /**
150
+ * Build the program sub-schema. `{ _id: false }` — a program is identified by
151
+ * its own `programId`, not a Mongoose ObjectId (as both apps already do).
152
+ */
153
+ export function buildOrganizationProgramSchema(): Schema {
154
+ return new Schema(organizationProgramSchemaDefinition, { _id: false });
155
+ }
156
+
157
+ /**
158
+ * Build the `programs` field to add to an organization schema — a FRESH
159
+ * sub-schema per call. Mongoose does not clone a `Schema` instance on
160
+ * `schema.add()` or embedding, so a module-level instance would be shared by
161
+ * every consumer: a pre-hook, virtual or index one consumer put on its rows
162
+ * would run on, or be created for, every other consumer's documents (review
163
+ * finding, 2026-10-12). Each mount gets its own instance.
164
+ *
165
+ * `default: undefined` (NOT Mongoose's implicit `[]` for array paths): an
166
+ * organization without programs persists nothing and round-trips as absent,
167
+ * which keeps "none declared" distinct from "declared empty" and leaves every
168
+ * existing document's shape untouched.
169
+ */
170
+ export function buildOrganizationProgramsFieldDefinition(): {
171
+ programs: {
172
+ type: Schema[];
173
+ required: false;
174
+ default: undefined;
175
+ };
176
+ } {
177
+ return {
178
+ programs: {
179
+ type: [buildOrganizationProgramSchema()],
180
+ required: false,
181
+ default: undefined,
182
+ },
183
+ };
184
+ }
185
+
186
+ // ─── Schema Helper ──────────────────────────────────────────────────
187
+
188
+ /**
189
+ * Update operations on which the row validators (enum, `required`) are
190
+ * enforced by {@link addOrganizationProgramsField}. Mongoose skips validators
191
+ * on update operations by default, and `$push` of a program row is the write
192
+ * path this fragment exists for (PAVE's `POST /organizations/:id/programs`).
193
+ */
194
+ export const ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS = Object.freeze([
195
+ "updateOne",
196
+ "updateMany",
197
+ "findOneAndUpdate",
198
+ ] as const);
199
+
200
+ export interface AddOrganizationProgramsFieldOptions {
201
+ /** The path's `select` option; `false` is Thread's read posture. Omitted → Mongoose default. */
202
+ select?: boolean;
203
+ /**
204
+ * Install a `pre` hook on {@link ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS}
205
+ * that turns `runValidators` on unless the caller set it, so a `$push` of a
206
+ * row with a review status outside the vocabulary, or with no `programId`,
207
+ * is refused on the update paths exactly as on `save()` (the `agency.ts`
208
+ * precedent). Default `true`.
209
+ *
210
+ * SCHEMA-WIDE on these ops, not just `programs`: once mounted, every
211
+ * `updateOne` / `updateMany` / `findOneAndUpdate` on the consumer's schema
212
+ * runs validators for EVERY path it touches, unless the caller passes
213
+ * `runValidators` explicitly. A consumer that relied on Mongoose's default of
214
+ * skipping validators on updates for its other fields will see new
215
+ * rejections after mounting this. Pass `{ validateOnUpdate: false }` to opt
216
+ * out, or set `runValidators: false` on an individual query.
217
+ */
218
+ validateOnUpdate?: boolean;
219
+ }
220
+
221
+ /**
222
+ * Add the `programs[]` field to an existing organization schema.
223
+ *
224
+ * Adds no indexes. Installs the update-path validation hook described on
225
+ * {@link AddOrganizationProgramsFieldOptions} unless opted out. A consumer
226
+ * that wants `select: false` on the field (Thread) passes `{ select: false }`.
227
+ *
228
+ * REPLACES a `programs` path the consumer already declares (`schema.add`
229
+ * overwrites the path wholesale — the consumer's own sub-fields and its own
230
+ * `select` option do not survive). That is the point of ONE definition: a
231
+ * consumer removes its local `programs` declaration and passes its read
232
+ * posture here instead. A `console.warn` names the overwrite so a consumer
233
+ * that forgot does not lose `select: false` silently.
234
+ *
235
+ * @param schema - The consumer's organization schema
236
+ * @returns The same schema, for chaining
237
+ */
238
+ export function addOrganizationProgramsField<S extends Schema>(
239
+ schema: S,
240
+ options: AddOrganizationProgramsFieldOptions = {},
241
+ ): S {
242
+ if (schema.path("programs")) {
243
+ console.warn(
244
+ "[platform-common-models] addOrganizationProgramsField: replacing the " +
245
+ "schema's own `programs` path with the shared fragment; pass " +
246
+ "`{ select: false }` here if that is the consumer's read posture.",
247
+ );
248
+ }
249
+ schema.add({
250
+ programs: {
251
+ ...buildOrganizationProgramsFieldDefinition().programs,
252
+ ...(options.select !== undefined ? { select: options.select } : {}),
253
+ },
254
+ });
255
+ if (options.validateOnUpdate ?? true) {
256
+ schema.pre(
257
+ [...ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS],
258
+ function (this: Query<unknown, unknown>) {
259
+ applyRunValidatorsIfUnset(this);
260
+ },
261
+ );
262
+ }
263
+ return schema;
264
+ }
265
+
266
+ // ─── Live-row rule ──────────────────────────────────────────────────
267
+
268
+ /**
269
+ * Whether a program row may be OFFERED (and matched by name on an add).
270
+ * A retired or rejected program is not a place anyone can be enrolled today,
271
+ * so pickers do not list it and typing its name mints a new row rather than
272
+ * binding to it (the prototype's independent pre-review catch, 2026-10-06).
273
+ */
274
+ export function isLiveOrganizationProgram(row: {
275
+ status?: string | null | undefined;
276
+ reviewStatus?: string | null | undefined;
277
+ }): boolean {
278
+ return (
279
+ row.status !== "retired" &&
280
+ row.reviewStatus !== PROGRAM_REVIEW_STATUS.REJECTED
281
+ );
282
+ }
283
+
284
+ // ─── Type Inference ─────────────────────────────────────────────────
285
+
286
+ /**
287
+ * Raw (persistence) shape of one program row, inferred from the DEFINITION.
288
+ *
289
+ * `programId` + `name` are required; every other field is optional (and may
290
+ * be `null`); `reviewStatus` is the three-word union. `{ _id: false }` matches
291
+ * the sub-schema, so the type carries no `_id` (the definition is `as const`
292
+ * so `required: false` stays a literal and is honoured by the inference).
293
+ */
294
+ export type OrganizationProgram = InferRawDocType<
295
+ typeof organizationProgramSchemaDefinition,
296
+ { _id: false; typeKey: "type" }
297
+ >;