@htilabs/platform-common-models 0.8.13 → 0.8.15

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 (75) hide show
  1. package/README.md +44 -0
  2. package/dist/config/index.cjs +4 -0
  3. package/dist/config/index.cjs.map +1 -1
  4. package/dist/config/index.d.cts +16 -1
  5. package/dist/config/index.d.ts +16 -1
  6. package/dist/config/index.js +2 -0
  7. package/dist/config/index.js.map +1 -1
  8. package/dist/constants/index.cjs +10 -0
  9. package/dist/constants/index.cjs.map +1 -1
  10. package/dist/constants/index.d.cts +1 -1
  11. package/dist/constants/index.d.ts +1 -1
  12. package/dist/constants/index.js +10 -0
  13. package/dist/constants/index.js.map +1 -1
  14. package/dist/cvcs/index.cjs +601 -2
  15. package/dist/cvcs/index.cjs.map +1 -1
  16. package/dist/cvcs/index.d.cts +2754 -2084
  17. package/dist/cvcs/index.d.ts +2754 -2084
  18. package/dist/cvcs/index.js +594 -2
  19. package/dist/cvcs/index.js.map +1 -1
  20. package/dist/{index-I-DiX9eQ.d.ts → index-CDoqrfc1.d.ts} +1 -1
  21. package/dist/{index-CoVr1jIV.d.cts → index-Zu_mOJRn.d.cts} +1 -1
  22. package/dist/index.cjs +709 -4
  23. package/dist/index.cjs.map +1 -1
  24. package/dist/index.d.cts +154 -7
  25. package/dist/index.d.ts +154 -7
  26. package/dist/index.js +693 -4
  27. package/dist/index.js.map +1 -1
  28. package/dist/models/index.d.cts +2 -2
  29. package/dist/models/index.d.ts +2 -2
  30. package/dist/mongo/index.cjs +383 -0
  31. package/dist/mongo/index.cjs.map +1 -0
  32. package/dist/mongo/index.d.cts +221 -0
  33. package/dist/mongo/index.d.ts +221 -0
  34. package/dist/mongo/index.js +351 -0
  35. package/dist/mongo/index.js.map +1 -0
  36. package/dist/{platform-auth-BfCMuAlC.d.cts → platform-auth-AsfnIXfK.d.cts} +2 -2
  37. package/dist/{platform-auth-BfCMuAlC.d.ts → platform-auth-AsfnIXfK.d.ts} +2 -2
  38. package/dist/schemas/index.cjs +5 -1
  39. package/dist/schemas/index.cjs.map +1 -1
  40. package/dist/schemas/index.d.cts +29 -25
  41. package/dist/schemas/index.d.ts +29 -25
  42. package/dist/schemas/index.js +5 -1
  43. package/dist/schemas/index.js.map +1 -1
  44. package/dist/types/index.d.cts +2 -2
  45. package/dist/types/index.d.ts +2 -2
  46. package/package.json +10 -1
  47. package/src/__sot__/coreIndicators.pin.json +6 -1
  48. package/src/__tests__/__snapshots__/cvc-sot.snap +18 -2
  49. package/src/__tests__/cvc-136-scoring-invariant.test.ts +6 -3
  50. package/src/__tests__/cvc-drift-gate.test.ts +14 -3
  51. package/src/__tests__/cvc-sot-snapshot.test.ts +13 -1
  52. package/src/__tests__/cvc-structural.test.ts +6 -0
  53. package/src/__tests__/mongo-verifier.test.ts +502 -0
  54. package/src/config/index.ts +8 -2
  55. package/src/constants/ic.ts +31 -2
  56. package/src/cvcs/assertionStatus.v1.0.0.json +80 -0
  57. package/src/cvcs/caseShareState.v1.0.0.json +62 -0
  58. package/src/cvcs/coreIndicators.v1.0.0.json +67 -2
  59. package/src/cvcs/createdBySystem.v1.0.0.json +89 -0
  60. package/src/cvcs/criminalOrgCategory.v1.0.0.json +116 -0
  61. package/src/cvcs/hmisSex.v1.0.0.json +89 -0
  62. package/src/cvcs/index.ts +22 -0
  63. package/src/cvcs/minorAdultStatus.v1.0.0.json +80 -0
  64. package/src/cvcs/referralOrigin.v1.0.0.json +26 -0
  65. package/src/cvcs/subjectType.v1.0.0.json +80 -0
  66. package/src/generated/cvc-enums.ts +125 -2
  67. package/src/index.ts +20 -0
  68. package/src/mongo/catalog.ts +65 -0
  69. package/src/mongo/contract.ts +157 -0
  70. package/src/mongo/index.ts +343 -0
  71. package/src/mongo/similarity.ts +133 -0
  72. package/src/mongo/uri.ts +53 -0
  73. package/src/schemas/common.ts +4 -0
  74. package/dist/{cvcEntry-BCj1OWqL.d.cts → cvcEntry-0BIB9sen.d.cts} +8 -8
  75. package/dist/{cvcEntry-BCj1OWqL.d.ts → cvcEntry-0BIB9sen.d.ts} +8 -8
@@ -0,0 +1,26 @@
1
+ {
2
+ "domain": "referral_origin",
3
+ "name": "Core Referral Origin",
4
+ "version": "1.0.0",
5
+ "levels": { "1": "Origin" },
6
+ "entries": [
7
+ {
8
+ "code": "909-001-000-000-000-000-000",
9
+ "key": "internal",
10
+ "title": "Internal",
11
+ "selectable": true,
12
+ "parentCode": null,
13
+ "childCodes": [],
14
+ "definition": "A referral whose sending and receiving parties sit within the same agency or account boundary, so completing it involves no disclosure of client information across an organizational boundary."
15
+ },
16
+ {
17
+ "code": "909-002-000-000-000-000-000",
18
+ "key": "external",
19
+ "title": "External",
20
+ "selectable": true,
21
+ "parentCode": null,
22
+ "childCodes": [],
23
+ "definition": "A referral whose receiving party is a different agency, making acceptance a cross-agency disclosure of client information. Where an implementation cannot positively determine the origin, it must treat the referral as external, so that the stronger disclosure controls apply by default rather than the weaker ones."
24
+ }
25
+ ]
26
+ }
@@ -0,0 +1,80 @@
1
+ {
2
+ "domain": "subject_type",
3
+ "name": "Subject Type",
4
+ "version": "1.0.0",
5
+ "_status": "PROVISIONAL — GDR §10.1 confirmed-CVC name is `core - subject_type`, but Final CVCs/CVC_INDEX.md @ a596eb9 carries no number for it, so it parks in the provisional 900-block pending canonical Notion authoring + steward ratification. Substantive values sourced verbatim from the PAVE @pave/domain `SUBJECT_TYPES` enum (D10 GDR §10.1 bulk publish, bead pv-pgdr-cvc-source-gdr-10-1-bulk-publish). The PAVE enum enumerates only the substantive entity kinds, so the missingness quadruplet is added per SOT convention.",
6
+ "_source": "pave-2.0/packages/domain/src/enums.ts SUBJECT_TYPES",
7
+ "levels": {
8
+ "0": "Unknown or Missing",
9
+ "1": "Assertion subject type"
10
+ },
11
+ "entries": [
12
+ {
13
+ "code": "987-000-000-000-000-000-000",
14
+ "key": "missingness_root",
15
+ "title": "Unknown, Redacted, or Missing",
16
+ "selectable": false,
17
+ "parentCode": null,
18
+ "childCodes": [
19
+ "987-000-000-000-000-000-001",
20
+ "987-000-000-000-000-000-002",
21
+ "987-000-000-000-000-000-003"
22
+ ],
23
+ "definition": "Root group for values indicating absent, withheld, or uncollected data."
24
+ },
25
+ {
26
+ "code": "987-000-000-000-000-000-001",
27
+ "key": "unknown",
28
+ "title": "Unknown",
29
+ "selectable": true,
30
+ "parentCode": "987-000-000-000-000-000-000",
31
+ "childCodes": [],
32
+ "definition": "The subject type is unknown at time of entry (missingness sentinel)."
33
+ },
34
+ {
35
+ "code": "987-000-000-000-000-000-002",
36
+ "key": "anonymous",
37
+ "title": "Anonymous / declined to answer",
38
+ "selectable": true,
39
+ "parentCode": "987-000-000-000-000-000-000",
40
+ "childCodes": [],
41
+ "definition": "Value is intentionally withheld, declined, or redacted."
42
+ },
43
+ {
44
+ "code": "987-000-000-000-000-000-003",
45
+ "key": "data_not_collected",
46
+ "title": "Data not collected",
47
+ "selectable": true,
48
+ "parentCode": "987-000-000-000-000-000-000",
49
+ "childCodes": [],
50
+ "definition": "No attempt was made to collect the value."
51
+ },
52
+ {
53
+ "code": "987-001-000-000-000-000-000",
54
+ "key": "person",
55
+ "title": "Person",
56
+ "selectable": true,
57
+ "parentCode": null,
58
+ "childCodes": [],
59
+ "definition": "The assertion is about a person; `subject_id` resolves to a person record. Emitting systems typically default to this value (e.g. PAVE's assertion factory defaults `subjectType: \"person\"`)."
60
+ },
61
+ {
62
+ "code": "987-002-000-000-000-000-000",
63
+ "key": "relationship",
64
+ "title": "Relationship",
65
+ "selectable": true,
66
+ "parentCode": null,
67
+ "childCodes": [],
68
+ "definition": "The assertion is about a relationship between people; `subject_id` resolves to a relationship record."
69
+ },
70
+ {
71
+ "code": "987-003-000-000-000-000-000",
72
+ "key": "case",
73
+ "title": "Case",
74
+ "selectable": true,
75
+ "parentCode": null,
76
+ "childCodes": [],
77
+ "definition": "The assertion is about a case; `subject_id` resolves to a case record."
78
+ }
79
+ ]
80
+ }
@@ -889,6 +889,34 @@ export const SharePurposeKeys = {
889
889
 
890
890
  export type SharePurposeKey = keyof typeof SharePurposeKeys;
891
891
 
892
+ /**
893
+ * Key → positional code map for the `referral_origin` CVC domain.
894
+ *
895
+ * Domain: `referral_origin` · Version: 1.0.0 · Entries: 2
896
+ */
897
+ export const ReferralOriginKeys = {
898
+ internal: "909-001-000-000-000-000-000",
899
+ external: "909-002-000-000-000-000-000",
900
+ } as const;
901
+
902
+ export type ReferralOriginKey = keyof typeof ReferralOriginKeys;
903
+
904
+ /**
905
+ * Key → positional code map for the `case_share_state` CVC domain.
906
+ *
907
+ * Domain: `case_share_state` · Version: 1.0.0 · Entries: 6
908
+ */
909
+ export const CaseShareStateKeys = {
910
+ pending: "925-001-000-000-000-000-000",
911
+ claimed: "925-002-000-000-000-000-000",
912
+ accepted_awaiting_review: "925-003-000-000-000-000-000",
913
+ accepted: "925-004-000-000-000-000-000",
914
+ declined: "925-005-000-000-000-000-000",
915
+ rejected: "925-006-000-000-000-000-000",
916
+ } as const;
917
+
918
+ export type CaseShareStateKey = keyof typeof CaseShareStateKeys;
919
+
892
920
  /**
893
921
  * Key → positional code map for the `facilitator_entity_type` CVC domain.
894
922
  *
@@ -4118,9 +4146,9 @@ export const DhStateKeys = {
4118
4146
  export type DhStateKey = keyof typeof DhStateKeys;
4119
4147
 
4120
4148
  /**
4121
- * Key → positional code map for the `core_indicators` CVC domain (CVC-136; 210 canonical indicator codes re-sourced from prototype `data/core_indicators.yaml` @ a596eb9 plus the 2 codes @hti/scoring emits ahead of the codebook). Entries carry `family` / `polarity` / `severity` / `isAlert` / `alertWhen`; the alert list is a DERIVED VIEW over `isAlert`, not a rival taxonomy.
4149
+ * Key → positional code map for the `core_indicators` CVC domain (CVC-136; 215 canonical indicator codes re-sourced from prototype `data/core_indicators.yaml` @ 84a1b677 plus the 2 codes @hti/scoring emits ahead of the codebook). Entries carry `family` / `polarity` / `severity` / `isAlert` / `alertWhen`; the alert list is a DERIVED VIEW over `isAlert`, not a rival taxonomy.
4122
4150
  *
4123
- * Domain: `core_indicators` · Version: 1.0.0 · Entries: 214
4151
+ * Domain: `core_indicators` · Version: 1.0.0 · Entries: 219
4124
4152
  */
4125
4153
  export const CoreIndicatorKeys = {
4126
4154
  missingness_root: "136-000-000-000-000-000-000",
@@ -4337,6 +4365,11 @@ export const CoreIndicatorKeys = {
4337
4365
  works_across_multiple_cities_or_locations: "136-208-000-000-000-000-000",
4338
4366
  works_for_little_or_no_pay: "136-209-000-000-000-000-000",
4339
4367
  youth_watched_filmed_or_photographed_sexually_explicit: "136-210-000-000-000-000-000",
4368
+ clients_unaware_of_third_party_coordination: "136-211-000-000-000-000-000",
4369
+ depends_on_spouse_or_family_for_immigration_status: "136-212-000-000-000-000-000",
4370
+ sexualized_content_in_person_performance_activity: "136-213-000-000-000-000-000",
4371
+ sexualized_content_online_performance_activity: "136-214-000-000-000-000-000",
4372
+ trauma_perpetrator_is_current_manager: "136-215-000-000-000-000-000",
4340
4373
  } as const;
4341
4374
 
4342
4375
  export type CoreIndicatorKey = keyof typeof CoreIndicatorKeys;
@@ -5025,3 +5058,93 @@ export const WhyNotKeys = {
5025
5058
  } as const;
5026
5059
 
5027
5060
  export type WhyNotKey = keyof typeof WhyNotKeys;
5061
+
5062
+ /**
5063
+ * Key → positional code map for the `assertion_status` CVC domain (GDR §10.1 `core - status`; assertion lifecycle status; PROVISIONAL, pending Notion ratification).
5064
+ *
5065
+ * Domain: `assertion_status` · Version: 1.0.0 · Entries: 7
5066
+ */
5067
+ export const AssertionStatusKeys = {
5068
+ missingness_root: "985-000-000-000-000-000-000",
5069
+ unknown: "985-000-000-000-000-000-001",
5070
+ anonymous: "985-000-000-000-000-000-002",
5071
+ data_not_collected: "985-000-000-000-000-000-003",
5072
+ active: "985-001-000-000-000-000-000",
5073
+ superseded: "985-002-000-000-000-000-000",
5074
+ retracted: "985-003-000-000-000-000-000",
5075
+ } as const;
5076
+
5077
+ export type AssertionStatusKey = keyof typeof AssertionStatusKeys;
5078
+
5079
+ /**
5080
+ * Key → positional code map for the `created_by_system` CVC domain (GDR §10.1 `core - created_by_system`; creating actor class; PROVISIONAL, pending Notion ratification).
5081
+ *
5082
+ * Domain: `created_by_system` · Version: 1.0.0 · Entries: 8
5083
+ */
5084
+ export const CreatedBySystemKeys = {
5085
+ missingness_root: "986-000-000-000-000-000-000",
5086
+ unknown: "986-000-000-000-000-000-001",
5087
+ anonymous: "986-000-000-000-000-000-002",
5088
+ data_not_collected: "986-000-000-000-000-000-003",
5089
+ human: "986-001-000-000-000-000-000",
5090
+ integration: "986-002-000-000-000-000-000",
5091
+ rules_engine: "986-003-000-000-000-000-000",
5092
+ model: "986-004-000-000-000-000-000",
5093
+ } as const;
5094
+
5095
+ export type CreatedBySystemKey = keyof typeof CreatedBySystemKeys;
5096
+
5097
+ /**
5098
+ * Key → positional code map for the `subject_type` CVC domain (GDR §10.1 `core - subject_type`; assertion subject type; PROVISIONAL, pending Notion ratification).
5099
+ *
5100
+ * Domain: `subject_type` · Version: 1.0.0 · Entries: 7
5101
+ */
5102
+ export const SubjectTypeKeys = {
5103
+ missingness_root: "987-000-000-000-000-000-000",
5104
+ unknown: "987-000-000-000-000-000-001",
5105
+ anonymous: "987-000-000-000-000-000-002",
5106
+ data_not_collected: "987-000-000-000-000-000-003",
5107
+ person: "987-001-000-000-000-000-000",
5108
+ relationship: "987-002-000-000-000-000-000",
5109
+ case: "987-003-000-000-000-000-000",
5110
+ } as const;
5111
+
5112
+ export type SubjectTypeKey = keyof typeof SubjectTypeKeys;
5113
+
5114
+ /**
5115
+ * Key → positional code map for the `minor_adult_status` CVC domain (GDR §10.1 `core - minor_adult_status`; age band at event; PROVISIONAL at 988 — canonical CVC-61 exists in the index but its Notion codebook is empty, see ADR-CVC-0.8.13 NARRATIVE_ONLY; renumber 988→61 on Notion authoring).
5116
+ *
5117
+ * Domain: `minor_adult_status` · Version: 1.0.0 · Entries: 7
5118
+ */
5119
+ export const MinorAdultStatusKeys = {
5120
+ missingness_root: "988-000-000-000-000-000-000",
5121
+ unknown: "988-000-000-000-000-000-001",
5122
+ anonymous: "988-000-000-000-000-000-002",
5123
+ data_not_collected: "988-000-000-000-000-000-003",
5124
+ minor: "988-001-000-000-000-000-000",
5125
+ adult: "988-002-000-000-000-000-000",
5126
+ indeterminate: "988-003-000-000-000-000-000",
5127
+ } as const;
5128
+
5129
+ export type MinorAdultStatusKey = keyof typeof MinorAdultStatusKeys;
5130
+
5131
+ /**
5132
+ * Key → positional code map for the `criminal_org_category` CVC domain (WIKI 7-type taxonomy for the criminal-org registry; ported from prototype/data/cvcs/core_criminal_org_category.yaml; PROVISIONAL at 990 — net-new, PENDING canonical Notion authoring).
5133
+ *
5134
+ * Domain: `criminal_org_category` · Version: 1.0.0 · Entries: 11
5135
+ */
5136
+ export const CriminalOrgCategoryKeys = {
5137
+ missingness_root: "990-000-000-000-000-000-000",
5138
+ unknown: "990-000-000-000-000-000-001",
5139
+ anonymous: "990-000-000-000-000-000-002",
5140
+ data_not_collected: "990-000-000-000-000-000-003",
5141
+ street_gang: "990-001-000-000-000-000-000",
5142
+ prison_gang: "990-002-000-000-000-000-000",
5143
+ outlaw_motorcycle_gang: "990-003-000-000-000-000-000",
5144
+ tco_cartel: "990-004-000-000-000-000-000",
5145
+ white_supremacist_extremist: "990-005-000-000-000-000-000",
5146
+ organized_crime_family: "990-006-000-000-000-000-000",
5147
+ familial_or_independent_trafficking_network: "990-007-000-000-000-000-000",
5148
+ } as const;
5149
+
5150
+ export type CriminalOrgCategoryKey = keyof typeof CriminalOrgCategoryKeys;
package/src/index.ts CHANGED
@@ -88,3 +88,23 @@ export { compileModel as compileCvcEntryModel } from "./models/cvcEntryModel.js"
88
88
  // filesystem access. See `./cvcs/index.ts` for the full list and naming.
89
89
 
90
90
  export * from "./cvcs/index.js";
91
+
92
+ // ─── SOT-first CVC flat-array aliases ───────────────────────────────────────
93
+ // Legacy-shaped `CVC_<N>_VALUES` arrays for CVCs that are SOT-native (no
94
+ // ic.ts constants). Derived from the SOT JSON envelope's `entries` filtered
95
+ // to `selectable: true` so the SOT JSON remains the single source of truth
96
+ // AND the non-selectable `missingness_root` grouping code is excluded (it
97
+ // would otherwise fail schema enum validation on write).
98
+
99
+ import recencyBandSot from "./cvcs/recencyBand.v1.0.0.json" with { type: "json" };
100
+ import juvenileJusticeEpisodeTypeSot from "./cvcs/juvenileJusticeEpisodeType.v1.0.0.json" with { type: "json" };
101
+
102
+ const selectableCodes = (envelope: {
103
+ entries: ReadonlyArray<{ code: string; selectable: boolean }>;
104
+ }): string[] =>
105
+ envelope.entries.filter((e) => e.selectable).map((e) => e.code);
106
+
107
+ export const CVC_137_VALUES: string[] = selectableCodes(recencyBandSot);
108
+ export const CVC_197_VALUES: string[] = selectableCodes(
109
+ juvenileJusticeEpisodeTypeSot,
110
+ );
@@ -0,0 +1,65 @@
1
+ /**
2
+ * @htilabs/platform-common-models — read-only MongoDB catalogue
3
+ *
4
+ * The verifier reaches MongoDB ONLY through this interface. It exposes two
5
+ * read operations and nothing else: there is no method here that can create,
6
+ * write, or drop anything. The read-only guarantee is enforced by the type,
7
+ * not by convention.
8
+ *
9
+ * Injecting the catalogue also keeps the package's test suite free of a real
10
+ * MongoDB, matching how `runCvcBootCheck` injects `exit` and `logger`.
11
+ */
12
+
13
+ export interface MongoCatalog {
14
+ /** Names of databases that physically exist (i.e. hold data). */
15
+ listDatabases(): Promise<string[]>;
16
+ /** Names of collections that physically exist in `database`. */
17
+ listCollections(database: string): Promise<string[]>;
18
+ }
19
+
20
+ /**
21
+ * Minimal structural view of a `mongodb` MongoClient. Declared structurally so
22
+ * this package takes no dependency on the `mongodb` driver — apps pass their
23
+ * own client, whatever major version they are on.
24
+ */
25
+ export interface MongoClientLike {
26
+ db(name?: string): {
27
+ admin(): {
28
+ listDatabases(): Promise<{ databases: Array<{ name: string }> }>;
29
+ };
30
+ listCollections(
31
+ filter?: Record<string, unknown>,
32
+ options?: Record<string, unknown>,
33
+ ): { toArray(): Promise<Array<{ name: string }>> };
34
+ };
35
+ }
36
+
37
+ /** Minimal structural view of a Mongoose Connection. */
38
+ export interface MongooseConnectionLike {
39
+ getClient(): MongoClientLike;
40
+ }
41
+
42
+ /** Build a catalogue from a native `mongodb` client. */
43
+ export function catalogFromClient(client: MongoClientLike): MongoCatalog {
44
+ return {
45
+ async listDatabases(): Promise<string[]> {
46
+ const { databases } = await client.db().admin().listDatabases();
47
+ return databases.map((d) => d.name);
48
+ },
49
+ async listCollections(database: string): Promise<string[]> {
50
+ // `nameOnly` keeps the server from materializing collection options.
51
+ const infos = await client
52
+ .db(database)
53
+ .listCollections({}, { nameOnly: true })
54
+ .toArray();
55
+ return infos.map((c) => c.name);
56
+ },
57
+ };
58
+ }
59
+
60
+ /** Build a catalogue from an open Mongoose connection. */
61
+ export function catalogFromMongoose(
62
+ connection: MongooseConnectionLike,
63
+ ): MongoCatalog {
64
+ return catalogFromClient(connection.getClient());
65
+ }
@@ -0,0 +1,157 @@
1
+ /**
2
+ * @htilabs/platform-common-models — `mongo:` contract block
3
+ *
4
+ * Extends the HTI Runtime Config Contract (`config/runtime/<service>.yaml`)
5
+ * with a declaration of the databases and collections a service expects.
6
+ *
7
+ * The declaration is deliberately data, not code: `expansion` is Python and
8
+ * parses the same YAML. Nothing here may depend on a TypeScript-only construct.
9
+ *
10
+ * ## Why declared rather than introspected
11
+ *
12
+ * Reading collection names off registered Mongoose models would cover only the
13
+ * Mongoose apps (thread, leads, pave) and would report false findings: thread
14
+ * registers `AgencyInfo` (collection `agencyinfos`), which exists in NO
15
+ * database because nothing has ever written to it. Mongo creates collections
16
+ * lazily. A declaration states intent; introspection only restates the code.
17
+ */
18
+
19
+ /** One database a service connects to, and the collections it uses. */
20
+ export interface MongoDbSpec {
21
+ /** Contract variable holding the database NAME (e.g. `THREAD_DB`). */
22
+ db_var: string;
23
+ /**
24
+ * Contract variable holding the connection URI or cluster prefix
25
+ * (e.g. `MONGODB_CLUSTER`). When the URI already embeds a database name and
26
+ * no `db_var` applies, set `db_var` to the same variable — the name is then
27
+ * parsed out of the URI.
28
+ */
29
+ uri_var: string;
30
+ /**
31
+ * Collections the service reads or writes. Declare only what the service
32
+ * USES — not everything present in the database. An undeclared collection
33
+ * present in Mongo is reported, never fatal.
34
+ *
35
+ * An EMPTY list opts out of collection checking entirely: only the database
36
+ * name is verified, and `listCollections` is never called. Use it when a
37
+ * service reaches a database whose collections it cannot practically
38
+ * enumerate. Declaring even one collection opts back in.
39
+ */
40
+ collections: string[];
41
+ }
42
+
43
+ /**
44
+ * Per-environment database-name affinity. When the deploy environment has an
45
+ * entry here, every resolved database name must end with the given suffix.
46
+ *
47
+ * This generalizes thread's `assertTestDb` (packages/db/src/connections.ts):
48
+ * it is the only check that catches a test run pointed at a production
49
+ * database, and it needs no connection to MongoDB.
50
+ */
51
+ export type EnvAffinity = Record<string, string>;
52
+
53
+ export interface MongoContractBlock {
54
+ /** e.g. `{ test: "-test", dev: "-dev" }`. Environments omitted are unconstrained. */
55
+ env_affinity?: EnvAffinity;
56
+ databases: MongoDbSpec[];
57
+ }
58
+
59
+ /** Prefix for every diagnostic this module emits. */
60
+ const TAG = "[platform-common/mongo]";
61
+
62
+ /**
63
+ * Validate and normalize the `mongo:` block of a parsed contract.
64
+ *
65
+ * Returns `null` when the contract declares no `mongo:` block — a service that
66
+ * does not use MongoDB is not an error.
67
+ *
68
+ * Throws on a malformed block: a contract that lies about its shape is a
69
+ * programming error, not a runtime finding.
70
+ */
71
+ export function parseMongoBlock(
72
+ raw: unknown,
73
+ contractPath: string,
74
+ ): MongoContractBlock | null {
75
+ if (raw === undefined || raw === null) return null;
76
+
77
+ if (typeof raw !== "object" || Array.isArray(raw)) {
78
+ throw new Error(`${TAG} ${contractPath}: "mongo" must be a mapping`);
79
+ }
80
+
81
+ const block = raw as Partial<MongoContractBlock>;
82
+
83
+ if (!Array.isArray(block.databases) || block.databases.length === 0) {
84
+ throw new Error(
85
+ `${TAG} ${contractPath}: "mongo.databases" must be a non-empty list`,
86
+ );
87
+ }
88
+
89
+ block.databases.forEach((db, i) => {
90
+ const where = `${contractPath}: mongo.databases[${i}]`;
91
+ if (!db || typeof db !== "object") {
92
+ throw new Error(`${TAG} ${where} must be a mapping`);
93
+ }
94
+ if (typeof db.db_var !== "string" || db.db_var.length === 0) {
95
+ throw new Error(`${TAG} ${where}.db_var must be a non-empty string`);
96
+ }
97
+ if (typeof db.uri_var !== "string" || db.uri_var.length === 0) {
98
+ throw new Error(`${TAG} ${where}.uri_var must be a non-empty string`);
99
+ }
100
+ if (!Array.isArray(db.collections)) {
101
+ throw new Error(`${TAG} ${where}.collections must be a list`);
102
+ }
103
+ db.collections.forEach((c, j) => {
104
+ if (typeof c !== "string" || c.length === 0) {
105
+ throw new Error(
106
+ `${TAG} ${where}.collections[${j}] must be a non-empty string`,
107
+ );
108
+ }
109
+ });
110
+ });
111
+
112
+ if (block.env_affinity !== undefined) {
113
+ if (typeof block.env_affinity !== "object" || Array.isArray(block.env_affinity)) {
114
+ throw new Error(
115
+ `${TAG} ${contractPath}: "mongo.env_affinity" must be a mapping of env -> suffix`,
116
+ );
117
+ }
118
+ for (const [env, suffix] of Object.entries(block.env_affinity)) {
119
+ if (typeof suffix !== "string" || suffix.length === 0) {
120
+ throw new Error(
121
+ `${TAG} ${contractPath}: mongo.env_affinity.${env} must be a non-empty string`,
122
+ );
123
+ }
124
+ }
125
+ }
126
+
127
+ return {
128
+ env_affinity: block.env_affinity,
129
+ databases: block.databases as MongoDbSpec[],
130
+ };
131
+ }
132
+
133
+ /**
134
+ * Check a resolved database name against the environment's affinity suffix.
135
+ *
136
+ * Returns `null` when the name is acceptable (or the environment declares no
137
+ * affinity), otherwise a human-readable violation message.
138
+ *
139
+ * Requires NO MongoDB connection. This is the check that catches
140
+ * `NODE_ENV=test` pointed at `platform-db`.
141
+ */
142
+ export function checkEnvAffinity(
143
+ dbName: string,
144
+ dbVar: string,
145
+ env: string,
146
+ affinity: EnvAffinity | undefined,
147
+ ): string | null {
148
+ const suffix = affinity?.[env];
149
+ if (!suffix) return null;
150
+ if (dbName.endsWith(suffix)) return null;
151
+
152
+ return (
153
+ `${dbVar}="${dbName}" is not valid in environment "${env}": ` +
154
+ `database names must end with "${suffix}". ` +
155
+ `Refusing to run against a database outside this environment.`
156
+ );
157
+ }