@htilabs/platform-common-models 0.64.0 → 0.65.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/README.md CHANGED
@@ -16,6 +16,78 @@ Package exports are organized into a public root API and a small number of
16
16
  dedicated subpaths (`/validation`, `/cvcs`) — consult `package.json` for the
17
17
  authoritative `exports` map.
18
18
 
19
+ ## 0.65.0 — the Org's identifier: `key` (additive)
20
+
21
+ An organization now carries its identifier, the one value that names the same
22
+ organization in every database (the UDD Org `id`, a slug such as `the_spring`;
23
+ schema of record hti-features `udd-schemas/org/Org.v1.json`). Until now an
24
+ `organizations` row had only `_id`, which is each database's own, so nothing
25
+ tied a production row to the same organization in the Admin Hub's curated list.
26
+
27
+ - `ORG_RECORD_FIELD_NAMES` gains `key` (first). `addOrgRecordFields` declares
28
+ it (`String`, immutable, slug-shaped) and a partial unique index
29
+ `org_key_unique` (`ORG_KEY_INDEX_NAME`; the definition is exported as
30
+ `ORG_KEY_INDEX_SPEC` / `ORG_KEY_INDEX_OPTIONS`). A row with no key, or a
31
+ null one, is not indexed, so those never collide.
32
+ - What `immutable` does, measured on Mongoose 9.3.1 against MongoDB (the
33
+ tests are in `scripts/fill-org-registry.test.ts`, run in CI): the model
34
+ stores a key **only while it is creating the row**.
35
+ - Stored: `new Model({ key }).save()`, `Model.create({ key })`, and an
36
+ upsert that inserts the row (`$setOnInsert: { key }`, or `$set`, which
37
+ Mongoose moves to `$setOnInsert`).
38
+ - Not stored, and **no error is raised**: on a row that already exists,
39
+ `doc.key = …; doc.save()` and `updateOne` / `findOneAndUpdate` with
40
+ `$set: { key }`, or an upsert that finds the row. This is true whether
41
+ the row already has a key or has none, so a model cannot give an old row
42
+ its first key.
43
+ - Stored as `key`, not `id`: Mongoose gives every document an `id` of its own,
44
+ and the curated store already names it `key`.
45
+ - `isOrgKey`, `ORG_KEY_PATTERN`, `mintOrgKey(_id)` → `org-<_id>` for an
46
+ organization created without one (the curated store's rule: a new key never
47
+ encodes a name). `OrgIdentityWriteSchema` still refuses `key`: it is never
48
+ taken from a request body and never changes.
49
+ - `toDirectoryOrganizationView` returns `key` (null on a row not yet given one).
50
+ - Consumers: a model that mounts `addOrgRecordFields` gains the path and passes
51
+ `organizationSchemaIssues` unchanged. Upgrading alone does not give new
52
+ organizations an identifier: each app has to store one where it creates an
53
+ organization, in one of the forms that work:
54
+
55
+ ```ts
56
+ const _id = new Types.ObjectId();
57
+ await new Organization({ _id, name, key: mintOrgKey(_id) }).save(); // or Organization.create({ … })
58
+
59
+ await Organization.updateOne(
60
+ { _id },
61
+ { $set: { name }, $setOnInsert: { key: mintOrgKey(_id) } },
62
+ { upsert: true },
63
+ );
64
+ ```
65
+
66
+ Do not set `key` on a row that already exists (it is silently dropped, see
67
+ above). Existing rows get theirs only from the registry fill's key sheet,
68
+ which writes with the plain MongoDB driver.
69
+ - `scripts/fill-org-registry.ts`: matches a row to the curated list by `key`
70
+ first; `--propose-keys` / `--apply-keys` give existing rows their identifier
71
+ from a sheet a person reviews (see `scripts/FILL_ORG_REGISTRY_RUNBOOK.md`):
72
+ - The sheet has a `stored_id` column (the slug an old row carries in its
73
+ `id` field). `approved_key` takes a curated key, the line's own
74
+ `stored_id`, or `mint` (`org-<_id>`).
75
+ - Nothing is proposed when the evidence is not clear-cut, and the reason
76
+ says which case it is (two rows for one key, sources that disagree, a
77
+ name or database id that matches two curated organizations, a match by
78
+ short name only, an old slug the curated list does not know).
79
+ - `--apply-keys` prints each organization's stored name beside its key,
80
+ refuses a line whose name is not the stored one, marks an approval that
81
+ differs from the proposal, and builds the `org_key_unique` index first if
82
+ the collection does not have it (it says so before asking to confirm; it
83
+ refuses if an index of that name exists with other options).
84
+ - It plans all or nothing, then writes row by row: a row edited in between,
85
+ or one the database refuses, is reported and the command exits non-zero.
86
+ - Undo (`--rollback`) removes an identifier whenever the row still holds
87
+ the one the script wrote, even after an app has saved the row. Undo the
88
+ most recent apply first (the fill, then the identifiers).
89
+ - Both commands stop if a curated organization has no key, a malformed
90
+ key, a key another curated organization has, or the key `mint`.
19
91
  ## 0.64.0 — gender and disability: the codebook code on every category; the two reporting claims hold our own codes (additive; Crysta 2026-11-10)
20
92
 
21
93
  Crysta confirmed on 2026-11-10 that gender and disability follow the race rule
package/dist/index.cjs CHANGED
@@ -389,6 +389,9 @@ __export(src_exports, {
389
389
  NeedsAssessmentChangeTypeKeys: () => NeedsAssessmentChangeTypeKeys,
390
390
  NeedsResidentialAgainKeys: () => NeedsResidentialAgainKeys,
391
391
  ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS: () => ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS,
392
+ ORG_KEY_INDEX_NAME: () => ORG_KEY_INDEX_NAME,
393
+ ORG_KEY_INDEX_OPTIONS: () => ORG_KEY_INDEX_OPTIONS,
394
+ ORG_KEY_INDEX_SPEC: () => ORG_KEY_INDEX_SPEC,
392
395
  ORG_TYPE_FIELD_NAMES: () => ORG_TYPE_FIELD_NAMES,
393
396
  ORG_TYPE_HEADING_KEYS: () => ORG_TYPE_HEADING_KEYS,
394
397
  ORG_TYPE_KEYS: () => ORG_TYPE_KEYS,
@@ -18735,6 +18738,7 @@ function isLiveOrganizationProgram(row) {
18735
18738
  // src/orgDirectory/orgRecord.ts
18736
18739
  var ORG_REVIEW_STATUS_VALUES = PROGRAM_REVIEW_STATUS_VALUES;
18737
18740
  var ORG_RECORD_FIELD_NAMES = Object.freeze([
18741
+ "key",
18738
18742
  "legalName",
18739
18743
  "commonName",
18740
18744
  "shortName",
@@ -18784,6 +18788,10 @@ var ORGANIZATION_ENVELOPE_KEYS = Object.freeze([
18784
18788
  "updatedUser",
18785
18789
  "updatedTime"
18786
18790
  ]);
18791
+ var ORG_KEY_PATTERN = /^[a-z0-9][a-z0-9_-]{0,119}$/;
18792
+ function isOrgKey(value) {
18793
+ return typeof value === "string" && ORG_KEY_PATTERN.test(value);
18794
+ }
18787
18795
  var line = (max) => import_zod.z.string().trim().min(1).max(max).nullable();
18788
18796
  var ORG_VSP_TWO_STEP_MESSAGE = "vspPrivateNonprofit is step 2 of the HMIS VSP two-step and requires vsp: true";
18789
18797
  var OrgIdentityWriteSchema = import_zod.z.object({
@@ -18804,12 +18812,50 @@ var OrgVspWriteSchema = import_zod.z.object({
18804
18812
 
18805
18813
  // src/schemas/organization.ts
18806
18814
  var HEX_24 = /^[0-9a-fA-F]{24}$/;
18815
+ var ORG_KEY_INDEX_NAME = "org_key_unique";
18816
+ var ORG_KEY_INDEX_SPEC = Object.freeze({ key: 1 });
18817
+ var ORG_KEY_INDEX_OPTIONS = Object.freeze({
18818
+ name: ORG_KEY_INDEX_NAME,
18819
+ unique: true,
18820
+ partialFilterExpression: Object.freeze({ key: Object.freeze({ $type: "string" }) })
18821
+ });
18807
18822
  function isStoredDirectoryId(value) {
18808
18823
  if (value == null) return true;
18809
18824
  if (typeof value === "string") return value.trim() !== "";
18810
18825
  return typeof value === "object" && typeof value.toHexString === "function" && HEX_24.test(value.toHexString());
18811
18826
  }
18812
18827
  var orgRecordSchemaDefinition = {
18828
+ /**
18829
+ * The Org's identifier (the UDD `id`): the same value in every database.
18830
+ * Never taken from a request body.
18831
+ *
18832
+ * `immutable` means the model stores a key only while it is creating the
18833
+ * row. Measured on Mongoose 9.3.1 against MongoDB (the fill's test file
18834
+ * holds each line):
18835
+ *
18836
+ * - `new Model({ key }).save()` and `Model.create({ key })` store it.
18837
+ * - An upsert stores it when the upsert inserts the row (`$setOnInsert`, or
18838
+ * `$set`, which Mongoose moves to `$setOnInsert`); on a row that already
18839
+ * exists the upsert leaves `key` as it was.
18840
+ * - On a row that already exists, `doc.key = …; doc.save()` and
18841
+ * `updateOne` / `findOneAndUpdate` with `$set: { key }` do NOT write it,
18842
+ * and do not report an error. That holds whether the row has a key or has
18843
+ * none yet, so a model cannot give an old row its first key either.
18844
+ *
18845
+ * So an app stores `key: mintOrgKey(_id)` where it creates the
18846
+ * organization (`new Model().save()`, `create()`, or `$setOnInsert` on an
18847
+ * upsert). Rows that already exist get theirs from the registry fill's key
18848
+ * sheet, which writes with the plain MongoDB driver.
18849
+ */
18850
+ key: {
18851
+ type: String,
18852
+ trim: true,
18853
+ immutable: true,
18854
+ validate: {
18855
+ validator: (value) => value == null || isOrgKey(value),
18856
+ message: "key must be a lower-case slug (a-z, 0-9, _ and -)"
18857
+ }
18858
+ },
18813
18859
  /** The canonical reporting name (HMIS, funders). Readers fall back to `name`. */
18814
18860
  legalName: { type: String, trim: true },
18815
18861
  /** The name people use, when it differs from `name`. */
@@ -18858,6 +18904,13 @@ var orgAsBuiltSchemaDefinition = {
18858
18904
  };
18859
18905
  function addOrgRecordFields(schema, options = {}) {
18860
18906
  schema.add(orgRecordSchemaDefinition);
18907
+ schema.index(
18908
+ { ...ORG_KEY_INDEX_SPEC },
18909
+ {
18910
+ ...ORG_KEY_INDEX_OPTIONS,
18911
+ partialFilterExpression: { key: { ...ORG_KEY_INDEX_OPTIONS.partialFilterExpression.key } }
18912
+ }
18913
+ );
18861
18914
  for (const key of ORG_AS_BUILT_FIELD_NAMES) {
18862
18915
  if (schema.pathType(key) === "adhocOrUndefined") {
18863
18916
  schema.add({ [key]: orgAsBuiltSchemaDefinition[key] });
@@ -18866,6 +18919,7 @@ function addOrgRecordFields(schema, options = {}) {
18866
18919
  return installVspTwoStepHooks(schema, options);
18867
18920
  }
18868
18921
  var EXPECTED_INSTANCE = {
18922
+ key: "String",
18869
18923
  legalName: "String",
18870
18924
  commonName: "String",
18871
18925
  shortName: "String",
@@ -74768,6 +74822,9 @@ var CVC_197_VALUES = selectableCodes(
74768
74822
  NeedsAssessmentChangeTypeKeys,
74769
74823
  NeedsResidentialAgainKeys,
74770
74824
  ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS,
74825
+ ORG_KEY_INDEX_NAME,
74826
+ ORG_KEY_INDEX_OPTIONS,
74827
+ ORG_KEY_INDEX_SPEC,
74771
74828
  ORG_TYPE_FIELD_NAMES,
74772
74829
  ORG_TYPE_HEADING_KEYS,
74773
74830
  ORG_TYPE_KEYS,