@htilabs/platform-common-models 0.9.0 → 0.12.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 (149) hide show
  1. package/dist/config/index.cjs +85 -0
  2. package/dist/config/index.cjs.map +1 -1
  3. package/dist/config/index.d.cts +94 -4
  4. package/dist/config/index.d.ts +94 -4
  5. package/dist/config/index.js +81 -1
  6. package/dist/config/index.js.map +1 -1
  7. package/dist/constants/index.cjs +456 -181
  8. package/dist/constants/index.cjs.map +1 -1
  9. package/dist/constants/index.d.cts +1 -1
  10. package/dist/constants/index.d.ts +1 -1
  11. package/dist/constants/index.js +453 -169
  12. package/dist/constants/index.js.map +1 -1
  13. package/dist/cvcs/index.cjs +15331 -801
  14. package/dist/cvcs/index.cjs.map +1 -1
  15. package/dist/cvcs/index.d.cts +18167 -2208
  16. package/dist/cvcs/index.d.ts +18167 -2208
  17. package/dist/cvcs/index.js +15282 -801
  18. package/dist/cvcs/index.js.map +1 -1
  19. package/dist/{index-Zu_mOJRn.d.cts → index-CoVr1jIV.d.cts} +1 -1
  20. package/dist/{index-CDoqrfc1.d.ts → index-I-DiX9eQ.d.ts} +1 -1
  21. package/dist/index.cjs +17070 -1056
  22. package/dist/index.cjs.map +1 -1
  23. package/dist/index.d.cts +1638 -12
  24. package/dist/index.d.ts +1638 -12
  25. package/dist/index.js +16969 -1043
  26. package/dist/index.js.map +1 -1
  27. package/dist/models/index.d.cts +2 -2
  28. package/dist/models/index.d.ts +2 -2
  29. package/dist/mongo/index.cjs +384 -0
  30. package/dist/mongo/index.cjs.map +1 -0
  31. package/dist/mongo/index.d.cts +221 -0
  32. package/dist/mongo/index.d.ts +221 -0
  33. package/dist/mongo/index.js +352 -0
  34. package/dist/mongo/index.js.map +1 -0
  35. package/dist/{platform-auth-XVB9aHqR.d.cts → platform-auth-v53r3BhN.d.cts} +19 -75
  36. package/dist/{platform-auth-XVB9aHqR.d.ts → platform-auth-v53r3BhN.d.ts} +19 -75
  37. package/dist/schemas/index.cjs +25 -156
  38. package/dist/schemas/index.cjs.map +1 -1
  39. package/dist/schemas/index.d.cts +25 -25
  40. package/dist/schemas/index.d.ts +25 -25
  41. package/dist/schemas/index.js +25 -156
  42. package/dist/schemas/index.js.map +1 -1
  43. package/dist/services/index.cjs +0 -3
  44. package/dist/services/index.cjs.map +1 -1
  45. package/dist/services/index.js +0 -3
  46. package/dist/services/index.js.map +1 -1
  47. package/dist/types/index.d.cts +2 -2
  48. package/dist/types/index.d.ts +2 -2
  49. package/package.json +9 -1
  50. package/src/__sot__/README.md +56 -0
  51. package/src/__sot__/coreIndicators.pin.json +215 -0
  52. package/src/__sot__/cvcIndex.pin.json +268 -0
  53. package/src/__sot__/scoringEmits.pin.json +176 -0
  54. package/src/__tests__/__snapshots__/cvc-sot.snap +227 -35
  55. package/src/__tests__/cvc-136-scoring-invariant.test.ts +323 -0
  56. package/src/__tests__/cvc-drift-gate.test.ts +603 -0
  57. package/src/__tests__/cvc-sot-snapshot.test.ts +122 -11
  58. package/src/__tests__/cvc-structural.test.ts +56 -1
  59. package/src/__tests__/mongo-verifier.test.ts +502 -0
  60. package/src/__tests__/runtime-contract-validator.test.ts +325 -1
  61. package/src/config/index.ts +197 -6
  62. package/src/constants/ic.ts +512 -206
  63. package/src/constants/service-catalog.ts +4 -2
  64. package/src/cvcs/activityType.v1.0.0.json +143 -0
  65. package/src/cvcs/adminRoles.v1.0.0.json +153 -0
  66. package/src/cvcs/administeringJurisdiction.v1.0.0.json +40 -40
  67. package/src/cvcs/ageBinReporting.v1.0.0.json +40 -40
  68. package/src/cvcs/assertionDomain.v1.1.0.json +629 -0
  69. package/src/cvcs/{checkInPhase.v1.0.0.json → checkInPhase.v1.1.0.json} +20 -2
  70. package/src/cvcs/childChangeType.v1.0.0.json +152 -0
  71. package/src/cvcs/citizenship.v1.0.0.json +3062 -0
  72. package/src/cvcs/contactInfoTypes.v1.0.0.json +40 -40
  73. package/src/cvcs/contactLinkType.v1.0.0.json +89 -0
  74. package/src/cvcs/coreDhState.v1.0.0.json +113 -0
  75. package/src/cvcs/coreFunctions.v1.0.0.json +746 -0
  76. package/src/cvcs/coreIndicators.v1.0.0.json +2840 -0
  77. package/src/cvcs/coreReferralOutcome.v1.0.0.json +71 -0
  78. package/src/cvcs/employmentStatus.v1.0.0.json +60 -60
  79. package/src/cvcs/exploitationType.v1.0.0.json +106 -0
  80. package/src/cvcs/facilitatorEntityType.v1.0.0.json +40 -40
  81. package/src/cvcs/highestEducationLevelCompleted.v1.0.0.json +55 -46
  82. package/src/cvcs/hivStatus.v1.0.0.json +71 -0
  83. package/src/cvcs/hmisCurrentLivingSituation.v1.0.0.json +409 -0
  84. package/src/cvcs/hmisRelationshipToHoh.v1.0.0.json +104 -0
  85. package/src/cvcs/homelessStatus.v1.0.0.json +27 -27
  86. package/src/cvcs/housingSubsidyTypes.v1.0.0.json +161 -0
  87. package/src/cvcs/htType.v1.0.0.json +87 -0
  88. package/src/cvcs/identificationStatus.v1.0.0.json +18 -0
  89. package/src/cvcs/immigrationLegalStatusChangeType.v1.0.0.json +143 -0
  90. package/src/cvcs/incarcerationEpisodeType.v1.0.0.json +106 -0
  91. package/src/cvcs/incidentInvolvementRoles.v1.0.0.json +40 -40
  92. package/src/cvcs/incidentParticipationRoles.v1.0.0.json +40 -40
  93. package/src/cvcs/incomeBenefitsSources.v1.0.0.json +31 -2
  94. package/src/cvcs/index.ts +106 -1
  95. package/src/cvcs/juvenileJusticeEpisodeType.v1.0.0.json +28 -18
  96. package/src/cvcs/juvenileJusticeInvolvementStatus.v1.0.0.json +32 -32
  97. package/src/cvcs/livingSituation.v1.0.0.json +213 -0
  98. package/src/cvcs/mentalHealthStatus.v1.0.0.json +71 -0
  99. package/src/cvcs/militaryBranch.v1.0.0.json +20 -20
  100. package/src/cvcs/militaryStatus.v1.0.0.json +20 -20
  101. package/src/cvcs/nameType.v1.0.0.json +40 -40
  102. package/src/cvcs/needsAssessmentChangeType.v1.0.0.json +134 -0
  103. package/src/cvcs/offenderStatus.v1.0.0.json +40 -40
  104. package/src/cvcs/offenderStatusFamily.v1.0.0.json +36 -36
  105. package/src/cvcs/poPetitionBasis.v1.0.0.json +96 -0
  106. package/src/cvcs/poStatus.v1.0.0.json +144 -0
  107. package/src/cvcs/poViolationStatus.v1.0.0.json +76 -0
  108. package/src/cvcs/programEnrollmentChangeType.v1.0.0.json +134 -0
  109. package/src/cvcs/provenanceSourceId.v1.0.0.json +134 -0
  110. package/src/cvcs/radiusBucket.v1.0.0.json +110 -0
  111. package/src/cvcs/recencyBand.v1.0.0.json +104 -39
  112. package/src/cvcs/referralEntityCategory.v1.0.0.json +40 -40
  113. package/src/cvcs/relationshipConcern.v1.0.0.json +114 -0
  114. package/src/cvcs/riskCategory.v1.0.0.json +134 -0
  115. package/src/cvcs/riskSeverityBand.v1.0.0.json +139 -0
  116. package/src/cvcs/roiMethod.v1.0.0.json +107 -0
  117. package/src/cvcs/roiScope.v1.0.0.json +296 -0
  118. package/src/cvcs/roiStatus.v1.0.0.json +106 -0
  119. package/src/cvcs/romanticRelationshipChangeType.v1.0.0.json +162 -0
  120. package/src/cvcs/serviceAudience.v1.0.0.json +96 -0
  121. package/src/cvcs/serviceCategories.v1.0.0.json +44 -44
  122. package/src/cvcs/serviceDeliveryChannel.v1.0.0.json +147 -0
  123. package/src/cvcs/serviceMechanisms.v1.0.0.json +36 -36
  124. package/src/cvcs/serviceStates.v1.0.0.json +55 -33
  125. package/src/cvcs/sessionNoteVisibility.v1.0.0.json +80 -0
  126. package/src/cvcs/sessionTemplate.v1.0.0.json +261 -0
  127. package/src/cvcs/sexProviderSubrole.v1.0.0.json +35 -28
  128. package/src/cvcs/smtType.v1.0.0.json +40 -40
  129. package/src/cvcs/sourceCategory.v1.1.0.json +8 -1
  130. package/src/cvcs/sourceInstrument.v1.0.0.json +458 -0
  131. package/src/cvcs/sourceSubtype.v1.1.0.json +36 -0
  132. package/src/cvcs/sourceSystem.v1.0.0.json +203 -0
  133. package/src/cvcs/specialNeedsDisabilities.v1.0.0.json +143 -0
  134. package/src/cvcs/suggestionSource.v1.0.0.json +71 -0
  135. package/src/cvcs/traffickingRelevantRole.v1.0.0.json +104 -0
  136. package/src/cvcs/userRoles.v1.0.0.json +203 -0
  137. package/src/cvcs/verificationMethod.v1.0.0.json +18 -0
  138. package/src/cvcs/victimAbuseTypes.v1.0.0.json +276 -0
  139. package/src/cvcs/victimStatusFamily.v1.0.0.json +40 -40
  140. package/src/cvcs/whyNots.v1.0.0.json +385 -0
  141. package/src/generated/cvc-enums.ts +1729 -7
  142. package/src/mongo/catalog.ts +65 -0
  143. package/src/mongo/contract.ts +157 -0
  144. package/src/mongo/index.ts +343 -0
  145. package/src/mongo/similarity.ts +133 -0
  146. package/src/mongo/uri.ts +53 -0
  147. package/src/services/cvcRegistryService.ts +1 -1
  148. package/dist/{cvcEntry-0BIB9sen.d.cts → cvcEntry-BCj1OWqL.d.cts} +8 -8
  149. package/dist/{cvcEntry-0BIB9sen.d.ts → cvcEntry-BCj1OWqL.d.ts} +8 -8
@@ -0,0 +1,221 @@
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
+ interface MongoCatalog {
13
+ /** Names of databases that physically exist (i.e. hold data). */
14
+ listDatabases(): Promise<string[]>;
15
+ /** Names of collections that physically exist in `database`. */
16
+ listCollections(database: string): Promise<string[]>;
17
+ }
18
+ /**
19
+ * Minimal structural view of a `mongodb` MongoClient. Declared structurally so
20
+ * this package takes no dependency on the `mongodb` driver — apps pass their
21
+ * own client, whatever major version they are on.
22
+ */
23
+ interface MongoClientLike {
24
+ db(name?: string): {
25
+ admin(): {
26
+ listDatabases(): Promise<{
27
+ databases: Array<{
28
+ name: string;
29
+ }>;
30
+ }>;
31
+ };
32
+ listCollections(filter?: Record<string, unknown>, options?: Record<string, unknown>): {
33
+ toArray(): Promise<Array<{
34
+ name: string;
35
+ }>>;
36
+ };
37
+ };
38
+ }
39
+ /** Minimal structural view of a Mongoose Connection. */
40
+ interface MongooseConnectionLike {
41
+ getClient(): MongoClientLike;
42
+ }
43
+ /** Build a catalogue from a native `mongodb` client. */
44
+ declare function catalogFromClient(client: MongoClientLike): MongoCatalog;
45
+ /** Build a catalogue from an open Mongoose connection. */
46
+ declare function catalogFromMongoose(connection: MongooseConnectionLike): MongoCatalog;
47
+
48
+ /**
49
+ * @htilabs/platform-common-models — `mongo:` contract block
50
+ *
51
+ * Extends the HTI Runtime Config Contract (`config/runtime/<service>.yaml`)
52
+ * with a declaration of the databases and collections a service expects.
53
+ *
54
+ * The declaration is deliberately data, not code: `expansion` is Python and
55
+ * parses the same YAML. Nothing here may depend on a TypeScript-only construct.
56
+ *
57
+ * ## Why declared rather than introspected
58
+ *
59
+ * Reading collection names off registered Mongoose models would cover only the
60
+ * Mongoose apps (thread, leads, pave) and would report false findings: thread
61
+ * registers `AgencyInfo` (collection `agencyinfos`), which exists in NO
62
+ * database because nothing has ever written to it. Mongo creates collections
63
+ * lazily. A declaration states intent; introspection only restates the code.
64
+ */
65
+ /** One database a service connects to, and the collections it uses. */
66
+ interface MongoDbSpec {
67
+ /** Contract variable holding the database NAME (e.g. `THREAD_DB`). */
68
+ db_var: string;
69
+ /**
70
+ * Contract variable holding the connection URI or cluster prefix
71
+ * (e.g. `MONGODB_CLUSTER`). When the URI already embeds a database name and
72
+ * no `db_var` applies, set `db_var` to the same variable — the name is then
73
+ * parsed out of the URI.
74
+ */
75
+ uri_var: string;
76
+ /**
77
+ * Collections the service reads or writes. Declare only what the service
78
+ * USES — not everything present in the database. An undeclared collection
79
+ * present in Mongo is reported, never fatal.
80
+ *
81
+ * An EMPTY list opts out of collection checking entirely: only the database
82
+ * name is verified, and `listCollections` is never called. Use it when a
83
+ * service reaches a database whose collections it cannot practically
84
+ * enumerate. Declaring even one collection opts back in.
85
+ */
86
+ collections: string[];
87
+ }
88
+ /**
89
+ * Per-environment database-name affinity. When the deploy environment has an
90
+ * entry here, every resolved database name must end with the given suffix.
91
+ *
92
+ * This generalizes thread's `assertTestDb` (packages/db/src/connections.ts):
93
+ * it is the only check that catches a test run pointed at a production
94
+ * database, and it needs no connection to MongoDB.
95
+ */
96
+ type EnvAffinity = Record<string, string>;
97
+ interface MongoContractBlock {
98
+ /** e.g. `{ test: "-test", dev: "-dev" }`. Environments omitted are unconstrained. */
99
+ env_affinity?: EnvAffinity;
100
+ databases: MongoDbSpec[];
101
+ }
102
+
103
+ /**
104
+ * @htilabs/platform-common-models — MongoDB URI parsing
105
+ *
106
+ * Home of the connection-string parsing shared by the seed guard
107
+ * (`scripts/lib/confirmTargetDb.ts`) and the runtime verifier
108
+ * (`src/mongo/index.ts`). It lives in `src/` so both can import one
109
+ * implementation; `scripts/` cannot be imported from `src/` at build time.
110
+ */
111
+ /** Suffix that marks a database as a non-production scratch/test database. */
112
+ declare const TEST_DB_SUFFIX = "-test";
113
+ /**
114
+ * Parse the target database name out of a MongoDB connection URI.
115
+ *
116
+ * The database name is the path segment after the host(s), before any query
117
+ * string (`?...`). Handles both `mongodb://` and `mongodb+srv://` URIs and any
118
+ * userinfo / multi-host / option components. Returns `null` when the URI
119
+ * carries no database name (e.g. `mongodb://localhost:27017` or a trailing
120
+ * slash with nothing after it) — callers must treat a `null` name as
121
+ * prod-shaped and never silently default to a production database.
122
+ *
123
+ * Implemented as manual string parsing rather than `new URL()` because Node's
124
+ * URL parser rejects multi-host `mongodb+srv` authorities and mishandles the
125
+ * comma-separated seed-list form that real connection strings use.
126
+ */
127
+ declare function parseDbName(uri: string): string | null;
128
+ /**
129
+ * Classify a database name. A name is a "test" database (no confirmation
130
+ * required) only when it is non-null and ends in {@link TEST_DB_SUFFIX}.
131
+ * Everything else — including a `null` name — is prod-shaped.
132
+ */
133
+ declare function isTestDb(dbName: string | null): boolean;
134
+
135
+ /**
136
+ * @htilabs/platform-common-models — MongoDB connection/collection verifier
137
+ *
138
+ * Sibling to `./config`. Where `validateAgainstContract` proves the env vars
139
+ * are present and well-typed, `verifyMongo` proves they point somewhere real.
140
+ *
141
+ * ## What this catches
142
+ * - a database name that does not exist and looks like a typo of one that does
143
+ * - a collection name that does not exist and looks like a typo of one that does
144
+ * - a database name that does not belong to the current environment
145
+ * (env-affinity; needs no connection — generalizes thread's `assertTestDb`)
146
+ * - collections present in MongoDB but undeclared by the service (reported)
147
+ *
148
+ * ## What this CANNOT catch
149
+ * A plausible-but-wrong POPULATED database. `leads-platform-prod-test` exists
150
+ * and carries the same collection names as `leads-platform-test`; every
151
+ * name-existence check passes. Detecting that needs an identity marker
152
+ * written inside the database, which is outside this utility's read-only
153
+ * remit. Do not claim otherwise in adoption docs.
154
+ *
155
+ * ## Read-only
156
+ * Reaches MongoDB solely through {@link MongoCatalog}: listDatabases and
157
+ * listCollections. It never creates, writes, or drops anything.
158
+ *
159
+ * ## Severity
160
+ * MongoDB creates namespaces lazily, so ABSENCE IS AMBIGUOUS (typo vs
161
+ * unseeded environment). Absence alone warns; absence with a plausible
162
+ * near-neighbour is fatal. See `similarity.ts`.
163
+ *
164
+ * FACT (verified 2026-07-10, read-only): thread registers the Mongoose model
165
+ * `AgencyInfo` (collection `agencyinfos`), and that collection exists in
166
+ * neither `platform-test` (15 collections) nor `platform-dev` (41). A
167
+ * registered model with zero documents has no collection. The warn-on-absence
168
+ * rule exists because of this; do not "tighten" it to fatal.
169
+ */
170
+
171
+ type Severity = "fatal" | "warn";
172
+ type FindingKind = "env_var_missing" | "db_shape_violation" | "db_absent_typo" | "db_absent_unseeded" | "collection_absent_typo" | "collection_absent_unseeded" | "collection_undeclared";
173
+ interface Finding {
174
+ severity: Severity;
175
+ kind: FindingKind;
176
+ message: string;
177
+ dbVar?: string;
178
+ database?: string;
179
+ collection?: string;
180
+ /**
181
+ * Existing names this looks like a typo of. More than one means the evidence
182
+ * is ambiguous — the message lists them all rather than guessing.
183
+ */
184
+ suggestions?: string[];
185
+ }
186
+ interface MongoVerifyReport {
187
+ /** True when no fatal finding was produced. Warnings do not clear `ok`. */
188
+ ok: boolean;
189
+ findings: Finding[];
190
+ }
191
+ interface VerifyMongoOptions {
192
+ /** Read-only catalogue. Required — this package takes no driver dependency. */
193
+ catalog: MongoCatalog;
194
+ /** Environment name for affinity checks. Defaults to NODE_ENV, then "local". */
195
+ env?: string;
196
+ /** Env source. Defaults to `process.env`. */
197
+ processEnv?: NodeJS.ProcessEnv;
198
+ /** If true, throw instead of `exit(1)`. Defaults to false (production exits). */
199
+ throwOnFailure?: boolean;
200
+ /** Injected for tests. Defaults to `process.exit`. */
201
+ exit?: (code: number) => never;
202
+ /** Injected for tests. Defaults to `console`. */
203
+ logger?: Pick<Console, "error" | "warn">;
204
+ }
205
+ /**
206
+ * Verify every database and collection declared in `runtimeYamlPath` against a
207
+ * live MongoDB catalogue.
208
+ *
209
+ * Collects ALL findings before deciding, exactly as `validateAgainstContract`
210
+ * does — an operator fixing a misconfiguration should see every problem at
211
+ * once, not one per restart.
212
+ *
213
+ * Resolves to the report when no fatal finding is produced. On a fatal finding
214
+ * it prints every finding and calls `exit(1)`, or throws when
215
+ * `throwOnFailure` is set.
216
+ *
217
+ * A contract with no `mongo:` block is a no-op success.
218
+ */
219
+ declare function verifyMongo(runtimeYamlPath: string, opts: VerifyMongoOptions): Promise<MongoVerifyReport>;
220
+
221
+ export { type EnvAffinity, type Finding, type FindingKind, type MongoCatalog, type MongoClientLike, type MongoContractBlock, type MongoDbSpec, type MongoVerifyReport, type MongooseConnectionLike, type Severity, TEST_DB_SUFFIX, type VerifyMongoOptions, catalogFromClient, catalogFromMongoose, isTestDb, parseDbName, verifyMongo };
@@ -0,0 +1,221 @@
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
+ interface MongoCatalog {
13
+ /** Names of databases that physically exist (i.e. hold data). */
14
+ listDatabases(): Promise<string[]>;
15
+ /** Names of collections that physically exist in `database`. */
16
+ listCollections(database: string): Promise<string[]>;
17
+ }
18
+ /**
19
+ * Minimal structural view of a `mongodb` MongoClient. Declared structurally so
20
+ * this package takes no dependency on the `mongodb` driver — apps pass their
21
+ * own client, whatever major version they are on.
22
+ */
23
+ interface MongoClientLike {
24
+ db(name?: string): {
25
+ admin(): {
26
+ listDatabases(): Promise<{
27
+ databases: Array<{
28
+ name: string;
29
+ }>;
30
+ }>;
31
+ };
32
+ listCollections(filter?: Record<string, unknown>, options?: Record<string, unknown>): {
33
+ toArray(): Promise<Array<{
34
+ name: string;
35
+ }>>;
36
+ };
37
+ };
38
+ }
39
+ /** Minimal structural view of a Mongoose Connection. */
40
+ interface MongooseConnectionLike {
41
+ getClient(): MongoClientLike;
42
+ }
43
+ /** Build a catalogue from a native `mongodb` client. */
44
+ declare function catalogFromClient(client: MongoClientLike): MongoCatalog;
45
+ /** Build a catalogue from an open Mongoose connection. */
46
+ declare function catalogFromMongoose(connection: MongooseConnectionLike): MongoCatalog;
47
+
48
+ /**
49
+ * @htilabs/platform-common-models — `mongo:` contract block
50
+ *
51
+ * Extends the HTI Runtime Config Contract (`config/runtime/<service>.yaml`)
52
+ * with a declaration of the databases and collections a service expects.
53
+ *
54
+ * The declaration is deliberately data, not code: `expansion` is Python and
55
+ * parses the same YAML. Nothing here may depend on a TypeScript-only construct.
56
+ *
57
+ * ## Why declared rather than introspected
58
+ *
59
+ * Reading collection names off registered Mongoose models would cover only the
60
+ * Mongoose apps (thread, leads, pave) and would report false findings: thread
61
+ * registers `AgencyInfo` (collection `agencyinfos`), which exists in NO
62
+ * database because nothing has ever written to it. Mongo creates collections
63
+ * lazily. A declaration states intent; introspection only restates the code.
64
+ */
65
+ /** One database a service connects to, and the collections it uses. */
66
+ interface MongoDbSpec {
67
+ /** Contract variable holding the database NAME (e.g. `THREAD_DB`). */
68
+ db_var: string;
69
+ /**
70
+ * Contract variable holding the connection URI or cluster prefix
71
+ * (e.g. `MONGODB_CLUSTER`). When the URI already embeds a database name and
72
+ * no `db_var` applies, set `db_var` to the same variable — the name is then
73
+ * parsed out of the URI.
74
+ */
75
+ uri_var: string;
76
+ /**
77
+ * Collections the service reads or writes. Declare only what the service
78
+ * USES — not everything present in the database. An undeclared collection
79
+ * present in Mongo is reported, never fatal.
80
+ *
81
+ * An EMPTY list opts out of collection checking entirely: only the database
82
+ * name is verified, and `listCollections` is never called. Use it when a
83
+ * service reaches a database whose collections it cannot practically
84
+ * enumerate. Declaring even one collection opts back in.
85
+ */
86
+ collections: string[];
87
+ }
88
+ /**
89
+ * Per-environment database-name affinity. When the deploy environment has an
90
+ * entry here, every resolved database name must end with the given suffix.
91
+ *
92
+ * This generalizes thread's `assertTestDb` (packages/db/src/connections.ts):
93
+ * it is the only check that catches a test run pointed at a production
94
+ * database, and it needs no connection to MongoDB.
95
+ */
96
+ type EnvAffinity = Record<string, string>;
97
+ interface MongoContractBlock {
98
+ /** e.g. `{ test: "-test", dev: "-dev" }`. Environments omitted are unconstrained. */
99
+ env_affinity?: EnvAffinity;
100
+ databases: MongoDbSpec[];
101
+ }
102
+
103
+ /**
104
+ * @htilabs/platform-common-models — MongoDB URI parsing
105
+ *
106
+ * Home of the connection-string parsing shared by the seed guard
107
+ * (`scripts/lib/confirmTargetDb.ts`) and the runtime verifier
108
+ * (`src/mongo/index.ts`). It lives in `src/` so both can import one
109
+ * implementation; `scripts/` cannot be imported from `src/` at build time.
110
+ */
111
+ /** Suffix that marks a database as a non-production scratch/test database. */
112
+ declare const TEST_DB_SUFFIX = "-test";
113
+ /**
114
+ * Parse the target database name out of a MongoDB connection URI.
115
+ *
116
+ * The database name is the path segment after the host(s), before any query
117
+ * string (`?...`). Handles both `mongodb://` and `mongodb+srv://` URIs and any
118
+ * userinfo / multi-host / option components. Returns `null` when the URI
119
+ * carries no database name (e.g. `mongodb://localhost:27017` or a trailing
120
+ * slash with nothing after it) — callers must treat a `null` name as
121
+ * prod-shaped and never silently default to a production database.
122
+ *
123
+ * Implemented as manual string parsing rather than `new URL()` because Node's
124
+ * URL parser rejects multi-host `mongodb+srv` authorities and mishandles the
125
+ * comma-separated seed-list form that real connection strings use.
126
+ */
127
+ declare function parseDbName(uri: string): string | null;
128
+ /**
129
+ * Classify a database name. A name is a "test" database (no confirmation
130
+ * required) only when it is non-null and ends in {@link TEST_DB_SUFFIX}.
131
+ * Everything else — including a `null` name — is prod-shaped.
132
+ */
133
+ declare function isTestDb(dbName: string | null): boolean;
134
+
135
+ /**
136
+ * @htilabs/platform-common-models — MongoDB connection/collection verifier
137
+ *
138
+ * Sibling to `./config`. Where `validateAgainstContract` proves the env vars
139
+ * are present and well-typed, `verifyMongo` proves they point somewhere real.
140
+ *
141
+ * ## What this catches
142
+ * - a database name that does not exist and looks like a typo of one that does
143
+ * - a collection name that does not exist and looks like a typo of one that does
144
+ * - a database name that does not belong to the current environment
145
+ * (env-affinity; needs no connection — generalizes thread's `assertTestDb`)
146
+ * - collections present in MongoDB but undeclared by the service (reported)
147
+ *
148
+ * ## What this CANNOT catch
149
+ * A plausible-but-wrong POPULATED database. `leads-platform-prod-test` exists
150
+ * and carries the same collection names as `leads-platform-test`; every
151
+ * name-existence check passes. Detecting that needs an identity marker
152
+ * written inside the database, which is outside this utility's read-only
153
+ * remit. Do not claim otherwise in adoption docs.
154
+ *
155
+ * ## Read-only
156
+ * Reaches MongoDB solely through {@link MongoCatalog}: listDatabases and
157
+ * listCollections. It never creates, writes, or drops anything.
158
+ *
159
+ * ## Severity
160
+ * MongoDB creates namespaces lazily, so ABSENCE IS AMBIGUOUS (typo vs
161
+ * unseeded environment). Absence alone warns; absence with a plausible
162
+ * near-neighbour is fatal. See `similarity.ts`.
163
+ *
164
+ * FACT (verified 2026-07-10, read-only): thread registers the Mongoose model
165
+ * `AgencyInfo` (collection `agencyinfos`), and that collection exists in
166
+ * neither `platform-test` (15 collections) nor `platform-dev` (41). A
167
+ * registered model with zero documents has no collection. The warn-on-absence
168
+ * rule exists because of this; do not "tighten" it to fatal.
169
+ */
170
+
171
+ type Severity = "fatal" | "warn";
172
+ type FindingKind = "env_var_missing" | "db_shape_violation" | "db_absent_typo" | "db_absent_unseeded" | "collection_absent_typo" | "collection_absent_unseeded" | "collection_undeclared";
173
+ interface Finding {
174
+ severity: Severity;
175
+ kind: FindingKind;
176
+ message: string;
177
+ dbVar?: string;
178
+ database?: string;
179
+ collection?: string;
180
+ /**
181
+ * Existing names this looks like a typo of. More than one means the evidence
182
+ * is ambiguous — the message lists them all rather than guessing.
183
+ */
184
+ suggestions?: string[];
185
+ }
186
+ interface MongoVerifyReport {
187
+ /** True when no fatal finding was produced. Warnings do not clear `ok`. */
188
+ ok: boolean;
189
+ findings: Finding[];
190
+ }
191
+ interface VerifyMongoOptions {
192
+ /** Read-only catalogue. Required — this package takes no driver dependency. */
193
+ catalog: MongoCatalog;
194
+ /** Environment name for affinity checks. Defaults to NODE_ENV, then "local". */
195
+ env?: string;
196
+ /** Env source. Defaults to `process.env`. */
197
+ processEnv?: NodeJS.ProcessEnv;
198
+ /** If true, throw instead of `exit(1)`. Defaults to false (production exits). */
199
+ throwOnFailure?: boolean;
200
+ /** Injected for tests. Defaults to `process.exit`. */
201
+ exit?: (code: number) => never;
202
+ /** Injected for tests. Defaults to `console`. */
203
+ logger?: Pick<Console, "error" | "warn">;
204
+ }
205
+ /**
206
+ * Verify every database and collection declared in `runtimeYamlPath` against a
207
+ * live MongoDB catalogue.
208
+ *
209
+ * Collects ALL findings before deciding, exactly as `validateAgainstContract`
210
+ * does — an operator fixing a misconfiguration should see every problem at
211
+ * once, not one per restart.
212
+ *
213
+ * Resolves to the report when no fatal finding is produced. On a fatal finding
214
+ * it prints every finding and calls `exit(1)`, or throws when
215
+ * `throwOnFailure` is set.
216
+ *
217
+ * A contract with no `mongo:` block is a no-op success.
218
+ */
219
+ declare function verifyMongo(runtimeYamlPath: string, opts: VerifyMongoOptions): Promise<MongoVerifyReport>;
220
+
221
+ export { type EnvAffinity, type Finding, type FindingKind, type MongoCatalog, type MongoClientLike, type MongoContractBlock, type MongoDbSpec, type MongoVerifyReport, type MongooseConnectionLike, type Severity, TEST_DB_SUFFIX, type VerifyMongoOptions, catalogFromClient, catalogFromMongoose, isTestDb, parseDbName, verifyMongo };