@htilabs/platform-common-models 0.12.0 → 0.12.1

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 (97) hide show
  1. package/dist/config/index.cjs +0 -81
  2. package/dist/config/index.cjs.map +1 -1
  3. package/dist/config/index.d.cts +4 -79
  4. package/dist/config/index.d.ts +4 -79
  5. package/dist/config/index.js +1 -79
  6. package/dist/config/index.js.map +1 -1
  7. package/dist/constants/index.cjs +18 -2
  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 +18 -2
  12. package/dist/constants/index.js.map +1 -1
  13. package/dist/cvc-Cp4uWnAa.d.cts +298 -0
  14. package/dist/cvc-Cp4uWnAa.d.ts +298 -0
  15. package/dist/cvcs/index.cjs +6678 -221
  16. package/dist/cvcs/index.cjs.map +1 -1
  17. package/dist/cvcs/index.d.cts +15019 -8052
  18. package/dist/cvcs/index.d.ts +15019 -8052
  19. package/dist/cvcs/index.js +6666 -221
  20. package/dist/cvcs/index.js.map +1 -1
  21. package/dist/enums/index.cjs +4557 -0
  22. package/dist/enums/index.cjs.map +1 -0
  23. package/dist/enums/index.d.cts +5257 -0
  24. package/dist/enums/index.d.ts +5257 -0
  25. package/dist/enums/index.js +4354 -0
  26. package/dist/enums/index.js.map +1 -0
  27. package/dist/{index-I-DiX9eQ.d.ts → index-CDoqrfc1.d.ts} +1 -1
  28. package/dist/{index-CoVr1jIV.d.cts → index-Zu_mOJRn.d.cts} +1 -1
  29. package/dist/index.cjs +7219 -232
  30. package/dist/index.cjs.map +1 -1
  31. package/dist/index.d.cts +7 -4700
  32. package/dist/index.d.ts +7 -4700
  33. package/dist/index.js +7195 -232
  34. package/dist/index.js.map +1 -1
  35. package/dist/models/index.d.cts +2 -2
  36. package/dist/models/index.d.ts +2 -2
  37. package/dist/mongo/index.cjs +0 -1
  38. package/dist/mongo/index.cjs.map +1 -1
  39. package/dist/mongo/index.js +1 -2
  40. package/dist/mongo/index.js.map +1 -1
  41. package/dist/{platform-auth-v53r3BhN.d.cts → platform-auth-Dv5fu0Fh.d.cts} +5 -4
  42. package/dist/{platform-auth-v53r3BhN.d.ts → platform-auth-Dv5fu0Fh.d.ts} +5 -4
  43. package/dist/schemas/index.cjs +5 -1
  44. package/dist/schemas/index.cjs.map +1 -1
  45. package/dist/schemas/index.d.cts +25 -25
  46. package/dist/schemas/index.d.ts +25 -25
  47. package/dist/schemas/index.js +5 -1
  48. package/dist/schemas/index.js.map +1 -1
  49. package/dist/types/index.d.cts +2 -2
  50. package/dist/types/index.d.ts +2 -2
  51. package/dist/validation/index.cjs +58 -0
  52. package/dist/validation/index.cjs.map +1 -1
  53. package/dist/validation/index.d.cts +82 -283
  54. package/dist/validation/index.d.ts +82 -283
  55. package/dist/validation/index.js +57 -0
  56. package/dist/validation/index.js.map +1 -1
  57. package/package.json +10 -1
  58. package/src/__sot__/README.md +36 -1
  59. package/src/__sot__/coreIndicatorFields.ts +331 -0
  60. package/src/__sot__/coreIndicators.pin.json +1936 -2
  61. package/src/__sot__/cvcIndex.pin.json +8 -4
  62. package/src/__tests__/__snapshots__/cvc-sot.snap +41 -13
  63. package/src/__tests__/core-information-scope-invariant.test.ts +134 -0
  64. package/src/__tests__/cvc-136-scoring-invariant.test.ts +8 -3
  65. package/src/__tests__/cvc-181-182-country-parity.test.ts +163 -0
  66. package/src/__tests__/cvc-drift-gate.test.ts +445 -12
  67. package/src/__tests__/cvc-sot-snapshot.test.ts +73 -11
  68. package/src/__tests__/cvc-status-parser.test.ts +150 -0
  69. package/src/__tests__/cvc-structural.test.ts +14 -0
  70. package/src/__tests__/runtime-contract-validator.test.ts +1 -325
  71. package/src/config/index.ts +4 -189
  72. package/src/constants/ic.ts +120 -3
  73. package/src/cvcs/assertionDomain.v1.1.0.json +19 -1
  74. package/src/cvcs/assertionStatus.v1.0.0.json +80 -0
  75. package/src/cvcs/carCorrectionReason.v1.0.0.json +89 -0
  76. package/src/cvcs/caseShareState.v1.0.0.json +62 -0
  77. package/src/cvcs/coreIndicators.v1.0.0.json +83 -5
  78. package/src/cvcs/coreInformationScope.v1.0.0.json +1165 -0
  79. package/src/cvcs/countries.v1.0.0.json +3077 -0
  80. package/src/cvcs/createdBySystem.v1.0.0.json +89 -0
  81. package/src/cvcs/criminalOrgCategory.v1.0.0.json +116 -0
  82. package/src/cvcs/determinationHelperCategories.v1.0.0.json +1166 -0
  83. package/src/cvcs/incidentParticipationRoles.v1.0.0.json +11 -1
  84. package/src/cvcs/index.ts +32 -0
  85. package/src/cvcs/minorAdultStatus.v1.0.0.json +80 -0
  86. package/src/cvcs/personRelationships.v1.0.0.json +67 -2
  87. package/src/cvcs/referralOrigin.v1.0.0.json +26 -0
  88. package/src/cvcs/relationshipConcern.v1.0.0.json +28 -19
  89. package/src/cvcs/riskIdentificationMilestone.v1.0.0.json +109 -0
  90. package/src/cvcs/sessionTemplate.v1.0.0.json +22 -0
  91. package/src/cvcs/sharePurpose.v1.0.0.json +80 -12
  92. package/src/cvcs/subjectType.v1.0.0.json +80 -0
  93. package/src/generated/cvc-enums.ts +606 -20
  94. package/src/validation/cvcStatus.ts +209 -0
  95. package/src/validation/index.ts +1 -0
  96. package/dist/{cvcEntry-BCj1OWqL.d.cts → cvcEntry-0BIB9sen.d.cts} +8 -8
  97. package/dist/{cvcEntry-BCj1OWqL.d.ts → cvcEntry-0BIB9sen.d.ts} +8 -8
@@ -0,0 +1,209 @@
1
+ /**
2
+ * @htilabs/platform-common-models — CVC `_status`/`_source` provenance parser
3
+ *
4
+ * Problem this solves: `_status` on a SOT envelope (`src/cvcs/*.json`) is
5
+ * unvalidated free text (115 of 179 domains carry it; the rest predate the
6
+ * convention). A consumer that wants to know "is this actually a draft?" has
7
+ * had to eyeball a string like
8
+ *
9
+ * "DRAFT — TEMPORARY: net-new value-CVC not yet in Notion; provisional
10
+ * 900+ numbering; codes from prototype/data/cvcs/core_accommodation_type
11
+ * .yaml; PENDING canonical Notion authoring (PAVE Auditability backlog)."
12
+ *
13
+ * and get it right past two real traps observed across the current
14
+ * population:
15
+ * - A leading `"CANONICAL — …"` marker is a PROVENANCE note on an
16
+ * ALREADY-ratified file, not a maturity warning — it must not be lumped
17
+ * in with `"DRAFT"`/`"PROVISIONAL"`.
18
+ * - `core_functions` is self-contradictory: it leads
19
+ * `"DRAFTED — NEEDS REVIEW"` but the same string continues
20
+ * `"…Canonical numbering (133), NOT provisional."` A naive
21
+ * leading-word reader silently picks one side; this parser flags it.
22
+ *
23
+ * This module is a pure, additive, standalone export. It does NOT touch
24
+ * `CvcEnvelopeSchema` (`./cvc.ts`) — `_status`/`_source` are intentionally
25
+ * outside that Zod schema (see its module header), and adding them there
26
+ * would risk changing parse behavior for every existing consumer. Callers
27
+ * pass the RAW parsed JSON object (before or instead of
28
+ * `CvcEnvelopeSchema.parse()`), not the Zod-inferred `CvcEnvelope`.
29
+ *
30
+ * Classification rule (leading token of `_status`, case-insensitive):
31
+ * - contains "draft" → `maturity: "draft"`
32
+ * - contains "provisional" → `maturity: "provisional"`
33
+ * - contains "canonical" → `maturity: "canonical"` (a provenance note on
34
+ * an already-ratified file, NOT a maturity flag — kept distinct from
35
+ * `"final"` below so a caller can tell "explicitly marked ratified"
36
+ * apart from "predates the convention entirely")
37
+ * - `_status` absent entirely → `maturity: "final"` (legacy/unmarked)
38
+ *
39
+ * One real domain (`share_purpose` — "Synced verbatim from canonical
40
+ * CVC-84…") has a present `_status` whose LEADING token ("Synced") is none
41
+ * of the three convention words. Rather than mis-file it as `"final"` (which
42
+ * per the rule above is reserved for an ABSENT field) this parser falls back
43
+ * to scanning the full string for a single unambiguous keyword family before
44
+ * giving up — see `detectMaturity` below.
45
+ */
46
+
47
+ // ─── Public shape ───────────────────────────────────────────────────────────
48
+
49
+ /**
50
+ * The subset of a raw (pre-validation) SOT envelope this parser reads.
51
+ * Deliberately NOT the Zod-inferred `CvcEnvelope` from `./cvc.ts` — that type
52
+ * is the *parsed* shape, which does not declare `_status`/`_source` at all
53
+ * (they live outside the locked envelope schema on purpose). Pass the raw
54
+ * `JSON.parse()` result of a `src/cvcs/*.json` file here.
55
+ */
56
+ export interface RawCvcEnvelopeProvenance {
57
+ _status?: unknown;
58
+ _source?: unknown;
59
+ }
60
+
61
+ /** The four observed maturity states. See module header for the rule. */
62
+ export type CvcMaturity = "draft" | "provisional" | "canonical" | "final";
63
+
64
+ export interface CvcStatusInfo {
65
+ /** One of the four states; see module header for the classification rule. */
66
+ maturity: CvcMaturity;
67
+ /**
68
+ * The text this parser classified. For a string `_status` this is that
69
+ * string verbatim. For the 11 domains authored with a structured
70
+ * `_status` object (`{ vocabStatus, authoredBy, evidence, … }` — e.g.
71
+ * `citizenship`, `core_functions`'s sibling `countries`), this is
72
+ * `_status.vocabStatus` — the field those envelopes use for exactly this
73
+ * purpose — not the whole object. `null` iff `_status` is absent.
74
+ */
75
+ rawStatus: string | null;
76
+ /** True iff `_source` cites a `prototype/data/cvcs/*.yaml` path. */
77
+ sourceIsPrototype: boolean;
78
+ /** The cited `prototype/data/cvcs/*.yaml` path, or `null` if none. */
79
+ sourcePath: string | null;
80
+ /**
81
+ * True when the classification is a judgment call rather than a clean
82
+ * read: either the leading token disagrees with a later
83
+ * "NOT draft"/"NOT provisional"/"NOT canonical" qualifier in the same
84
+ * string (the `core_functions` shape — generic, not special-cased, so any
85
+ * future domain authored in the same self-contradictory shape is also
86
+ * caught), or the string carries more than one maturity keyword family
87
+ * with no leading token to arbitrate between them.
88
+ */
89
+ ambiguous: boolean;
90
+ }
91
+
92
+ // ─── Implementation ─────────────────────────────────────────────────────────
93
+
94
+ const MATURITY_KEYWORDS: ReadonlyArray<{
95
+ keyword: string;
96
+ maturity: Exclude<CvcMaturity, "final">;
97
+ }> = [
98
+ { keyword: "draft", maturity: "draft" },
99
+ { keyword: "provisional", maturity: "provisional" },
100
+ { keyword: "canonical", maturity: "canonical" },
101
+ ];
102
+
103
+ /** Matches a `prototype/data/cvcs/<file>.yaml` citation anywhere in `_source`. */
104
+ const PROTOTYPE_SOURCE_RE = /(prototype\/data\/cvcs\/[A-Za-z0-9_.-]+\.yaml)/;
105
+
106
+ /**
107
+ * A maturity keyword explicitly negated ("NOT provisional.") anywhere in the
108
+ * string — the self-contradiction signal. Deliberately scans the WHOLE
109
+ * string (not just past the leading token): the qualifier that disagrees
110
+ * with the leading word is, by construction, never the leading word itself.
111
+ */
112
+ const NEGATED_MATURITY_RE = /\bnot\s+(draft|provisional|canonical)\b/i;
113
+
114
+ /**
115
+ * Extract the text this parser classifies against, from either `_status`
116
+ * shape observed in the current SOT population:
117
+ * - `string` (104 of 115 status-bearing domains) → the string itself.
118
+ * - `{ vocabStatus: string, … }` (11 domains — a richer, hand-authored
119
+ * provenance record) → `vocabStatus`, the field those envelopes use for
120
+ * exactly this classification (values seen: `"canonical"` and
121
+ * `"provisional-pending-notion-ratification"`).
122
+ * - Anything else present but shapeless (unseen in the current 179-domain
123
+ * population) → `JSON.stringify` as a last resort, so a future oddity
124
+ * still gets a best-effort classification instead of silently vanishing.
125
+ * - Absent → `null`.
126
+ */
127
+ function extractClassificationText(status: unknown): string | null {
128
+ if (typeof status === "string") return status;
129
+ if (status !== null && typeof status === "object") {
130
+ const vocabStatus = (status as Record<string, unknown>).vocabStatus;
131
+ if (typeof vocabStatus === "string") return vocabStatus;
132
+ return JSON.stringify(status);
133
+ }
134
+ return null;
135
+ }
136
+
137
+ /** The first "word" of a status string, lowercased, for the leading-token rule. */
138
+ function leadingToken(text: string): string {
139
+ return (text.trim().split(/[\s—–:-]+/, 1)[0] ?? "").toLowerCase();
140
+ }
141
+
142
+ /**
143
+ * Classify a present, non-null `_status` text into a maturity + ambiguity
144
+ * flag. Isolated from {@link parseCvcStatus} so the fallback path (the
145
+ * `share_purpose` shape) and the negation check are each unit-testable in
146
+ * isolation.
147
+ */
148
+ function detectMaturity(text: string): { maturity: Exclude<CvcMaturity, "final">; ambiguous: boolean } {
149
+ const lead = leadingToken(text);
150
+ const leadMatch = MATURITY_KEYWORDS.find(({ keyword }) => lead.includes(keyword));
151
+
152
+ let maturity: Exclude<CvcMaturity, "final">;
153
+ if (leadMatch) {
154
+ maturity = leadMatch.maturity;
155
+ } else {
156
+ // The leading token is none of the three convention words. Observed once
157
+ // in the current population: `share_purpose`'s
158
+ // "Synced verbatim from canonical CVC-84…" — "Synced" leads, but the
159
+ // string is unambiguously describing an already-ratified vocabulary.
160
+ // Fall back to scanning the WHOLE string for maturity keyword families
161
+ // rather than defaulting to "final": the field IS present, and "final"
162
+ // per the module-header rule is reserved for an ABSENT `_status`.
163
+ const foundFamilies = MATURITY_KEYWORDS.filter(({ keyword }) =>
164
+ new RegExp(`\\b${keyword}\\w*\\b`, "i").test(text),
165
+ );
166
+ const distinctFamilies = new Set(foundFamilies.map((f) => f.maturity));
167
+ if (distinctFamilies.size === 1) {
168
+ // Single unambiguous family found in the body — safe to accept.
169
+ maturity = foundFamilies[0].maturity;
170
+ return { maturity, ambiguous: false };
171
+ }
172
+ if (distinctFamilies.size > 1) {
173
+ // Multiple families present with no leading token to arbitrate.
174
+ // Report the first-occurring family as a best-effort primary and let
175
+ // the caller see `ambiguous: true` — never silently pick a winner.
176
+ maturity = foundFamilies[0].maturity;
177
+ return { maturity, ambiguous: true };
178
+ }
179
+ // No maturity keyword anywhere in a present `_status` string. Unseen in
180
+ // the current 179-domain population; treat conservatively as
181
+ // "provisional" (the least-committal non-final bucket) rather than
182
+ // silently promoting an unrecognized status to a settled one, and flag
183
+ // it for human attention.
184
+ return { maturity: "provisional", ambiguous: true };
185
+ }
186
+
187
+ return { maturity, ambiguous: NEGATED_MATURITY_RE.test(text) };
188
+ }
189
+
190
+ /**
191
+ * Parse a SOT envelope's `_status`/`_source` provenance fields into a
192
+ * structured, typed result. Pure function — no filesystem access, no
193
+ * dependency on `CvcEnvelopeSchema`. See module header for the full rule and
194
+ * the two known traps it exists to catch.
195
+ */
196
+ export function parseCvcStatus(envelope: RawCvcEnvelopeProvenance): CvcStatusInfo {
197
+ const source = typeof envelope._source === "string" ? envelope._source : null;
198
+ const protoMatch = source?.match(PROTOTYPE_SOURCE_RE) ?? null;
199
+ const sourceIsPrototype = protoMatch !== null;
200
+ const sourcePath = protoMatch?.[1] ?? null;
201
+
202
+ const text = extractClassificationText(envelope._status);
203
+ if (text === null) {
204
+ return { maturity: "final", rawStatus: null, sourceIsPrototype, sourcePath, ambiguous: false };
205
+ }
206
+
207
+ const { maturity, ambiguous } = detectMaturity(text);
208
+ return { maturity, rawStatus: text, sourceIsPrototype, sourcePath, ambiguous };
209
+ }
@@ -13,3 +13,4 @@
13
13
  */
14
14
 
15
15
  export * from "./cvc.js";
16
+ export * from "./cvcStatus.js";
@@ -233,18 +233,18 @@ type SectionQuestionRef = InferRawDocType<typeof sectionQuestionRefSchema>;
233
233
  declare const guidanceSchema: Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
234
234
  _id: false;
235
235
  }, {
236
- text: string;
237
236
  type: "tip" | "warning" | "prompt";
238
- }, mongoose.Document<unknown, {}, {
239
237
  text: string;
238
+ }, mongoose.Document<unknown, {}, {
240
239
  type: "tip" | "warning" | "prompt";
240
+ text: string;
241
241
  }, {
242
242
  id: string;
243
243
  }, Omit<mongoose.DefaultSchemaOptions, "_id"> & {
244
244
  _id: false;
245
245
  }> & Omit<{
246
- text: string;
247
246
  type: "tip" | "warning" | "prompt";
247
+ text: string;
248
248
  } & {
249
249
  _id: mongoose.Types.ObjectId;
250
250
  } & {
@@ -252,8 +252,8 @@ declare const guidanceSchema: Schema<any, mongoose.Model<any, any, any, any, any
252
252
  }, "id"> & {
253
253
  id: string;
254
254
  }, unknown, {
255
- text: string;
256
255
  type: "tip" | "warning" | "prompt";
256
+ text: string;
257
257
  } & {
258
258
  _id: mongoose.Types.ObjectId;
259
259
  } & {
@@ -294,18 +294,18 @@ declare const sectionSchemaDefinition: {
294
294
  type: Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
295
295
  _id: false;
296
296
  }, {
297
- text: string;
298
297
  type: "tip" | "warning" | "prompt";
299
- }, mongoose.Document<unknown, {}, {
300
298
  text: string;
299
+ }, mongoose.Document<unknown, {}, {
301
300
  type: "tip" | "warning" | "prompt";
301
+ text: string;
302
302
  }, {
303
303
  id: string;
304
304
  }, Omit<mongoose.DefaultSchemaOptions, "_id"> & {
305
305
  _id: false;
306
306
  }> & Omit<{
307
- text: string;
308
307
  type: "tip" | "warning" | "prompt";
308
+ text: string;
309
309
  } & {
310
310
  _id: mongoose.Types.ObjectId;
311
311
  } & {
@@ -313,8 +313,8 @@ declare const sectionSchemaDefinition: {
313
313
  }, "id"> & {
314
314
  id: string;
315
315
  }, unknown, {
316
- text: string;
317
316
  type: "tip" | "warning" | "prompt";
317
+ text: string;
318
318
  } & {
319
319
  _id: mongoose.Types.ObjectId;
320
320
  } & {
@@ -233,18 +233,18 @@ type SectionQuestionRef = InferRawDocType<typeof sectionQuestionRefSchema>;
233
233
  declare const guidanceSchema: Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
234
234
  _id: false;
235
235
  }, {
236
- text: string;
237
236
  type: "tip" | "warning" | "prompt";
238
- }, mongoose.Document<unknown, {}, {
239
237
  text: string;
238
+ }, mongoose.Document<unknown, {}, {
240
239
  type: "tip" | "warning" | "prompt";
240
+ text: string;
241
241
  }, {
242
242
  id: string;
243
243
  }, Omit<mongoose.DefaultSchemaOptions, "_id"> & {
244
244
  _id: false;
245
245
  }> & Omit<{
246
- text: string;
247
246
  type: "tip" | "warning" | "prompt";
247
+ text: string;
248
248
  } & {
249
249
  _id: mongoose.Types.ObjectId;
250
250
  } & {
@@ -252,8 +252,8 @@ declare const guidanceSchema: Schema<any, mongoose.Model<any, any, any, any, any
252
252
  }, "id"> & {
253
253
  id: string;
254
254
  }, unknown, {
255
- text: string;
256
255
  type: "tip" | "warning" | "prompt";
256
+ text: string;
257
257
  } & {
258
258
  _id: mongoose.Types.ObjectId;
259
259
  } & {
@@ -294,18 +294,18 @@ declare const sectionSchemaDefinition: {
294
294
  type: Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
295
295
  _id: false;
296
296
  }, {
297
- text: string;
298
297
  type: "tip" | "warning" | "prompt";
299
- }, mongoose.Document<unknown, {}, {
300
298
  text: string;
299
+ }, mongoose.Document<unknown, {}, {
301
300
  type: "tip" | "warning" | "prompt";
301
+ text: string;
302
302
  }, {
303
303
  id: string;
304
304
  }, Omit<mongoose.DefaultSchemaOptions, "_id"> & {
305
305
  _id: false;
306
306
  }> & Omit<{
307
- text: string;
308
307
  type: "tip" | "warning" | "prompt";
308
+ text: string;
309
309
  } & {
310
310
  _id: mongoose.Types.ObjectId;
311
311
  } & {
@@ -313,8 +313,8 @@ declare const sectionSchemaDefinition: {
313
313
  }, "id"> & {
314
314
  id: string;
315
315
  }, unknown, {
316
- text: string;
317
316
  type: "tip" | "warning" | "prompt";
317
+ text: string;
318
318
  } & {
319
319
  _id: mongoose.Types.ObjectId;
320
320
  } & {