@htilabs/platform-common-models 0.19.0 → 0.21.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 (59) hide show
  1. package/dist/cvcs/index.cjs +4867 -639
  2. package/dist/cvcs/index.cjs.map +1 -1
  3. package/dist/cvcs/index.d.cts +5145 -609
  4. package/dist/cvcs/index.d.ts +5145 -609
  5. package/dist/cvcs/index.js +4867 -639
  6. package/dist/cvcs/index.js.map +1 -1
  7. package/dist/enums/index.cjs +74 -1
  8. package/dist/enums/index.cjs.map +1 -1
  9. package/dist/enums/index.d.cts +77 -4
  10. package/dist/enums/index.d.ts +77 -4
  11. package/dist/enums/index.js +74 -1
  12. package/dist/enums/index.js.map +1 -1
  13. package/dist/{index-I-DiX9eQ.d.ts → index-CDoqrfc1.d.ts} +1 -1
  14. package/dist/{index-CoVr1jIV.d.cts → index-Zu_mOJRn.d.cts} +1 -1
  15. package/dist/index.cjs +5382 -588
  16. package/dist/index.cjs.map +1 -1
  17. package/dist/index.d.cts +3 -2
  18. package/dist/index.d.ts +3 -2
  19. package/dist/index.js +5371 -588
  20. package/dist/index.js.map +1 -1
  21. package/dist/information-scope/index.cjs +521 -0
  22. package/dist/information-scope/index.cjs.map +1 -0
  23. package/dist/information-scope/index.d.cts +442 -0
  24. package/dist/information-scope/index.d.ts +442 -0
  25. package/dist/information-scope/index.js +484 -0
  26. package/dist/information-scope/index.js.map +1 -0
  27. package/dist/models/index.d.cts +2 -2
  28. package/dist/models/index.d.ts +2 -2
  29. package/dist/schemas/index.d.cts +25 -25
  30. package/dist/schemas/index.d.ts +25 -25
  31. package/dist/services/index.cjs +495 -2
  32. package/dist/services/index.cjs.map +1 -1
  33. package/dist/services/index.d.cts +1 -0
  34. package/dist/services/index.d.ts +1 -0
  35. package/dist/services/index.js +483 -1
  36. package/dist/services/index.js.map +1 -1
  37. package/package.json +32 -26
  38. package/src/__tests__/__snapshots__/cvc-sot.snap +3 -3
  39. package/src/__tests__/core-information-scope-invariant.test.ts +835 -456
  40. package/src/__tests__/cvc-sot-snapshot.test.ts +17 -17
  41. package/src/__tests__/cvc-structural.test.ts +2 -2
  42. package/src/__tests__/location-type-routing-invariant.test.ts +25 -8
  43. package/src/cvcs/coreInformationScope.v2.1.0.json +5498 -0
  44. package/src/cvcs/index.ts +2 -2
  45. package/src/cvcs/roiScope.v1.4.0.json +360 -0
  46. package/src/generated/cvc-enums.ts +77 -4
  47. package/src/services/__tests__/fixtures/infoscope-v4/information_scope_v3_placements.projection.csv +12 -0
  48. package/src/services/__tests__/fixtures/infoscope-v4/information_scope_v4.migrations.csv +106 -0
  49. package/src/services/__tests__/fixtures/infoscope-v4/information_scope_v4.rows.csv +117 -0
  50. package/src/services/__tests__/fixtures/infoscope-v4/loadInfoscopeV4Fixtures.ts +187 -0
  51. package/src/services/__tests__/informationScopeResolver.test.ts +1278 -0
  52. package/src/services/index.ts +10 -3
  53. package/src/services/informationScope.ts +10 -0
  54. package/src/services/informationScopeResolver.ts +879 -0
  55. package/src/services/informationScopeSot.ts +203 -0
  56. package/src/cvcs/coreInformationScope.v1.1.0.json +0 -1290
  57. package/src/cvcs/roiScope.v1.2.0.json +0 -340
  58. package/dist/{cvcEntry-BCj1OWqL.d.cts → cvcEntry-0BIB9sen.d.cts} +8 -8
  59. package/dist/{cvcEntry-BCj1OWqL.d.ts → cvcEntry-0BIB9sen.d.ts} +8 -8
@@ -0,0 +1,203 @@
1
+ /**
2
+ * @htilabs/platform-common-models — CVC-236 SOT → information-scope resolver binding
3
+ *
4
+ * Maps the `core_information_scope` SOT envelope (`coreInformationScope.v2.1.0.json`,
5
+ * exported as `coreInformationScopeSot` from `/cvcs`) into the resolver's
6
+ * input shapes. Pure and dependency-free: the caller passes the envelope.
7
+ *
8
+ * The SOT keys a row by its package key (`offenders__risk`, `identifying__other`:
9
+ * canon's dotted codes with `.` spelled `__`) and by a seven-segment wire code;
10
+ * a stored selection holds canon's dotted code (`offenders.risk`). The
11
+ * adapter reads every key through the entry's `canonicalCode` (present on the
12
+ * dotted rows) and falls back to `__` → `.` for a key with no entry.
13
+ *
14
+ * Rows: the live v4 tree only (`status` `as_today` / `new`). The retired
15
+ * tombstones are left out — a stored retired code reads through the
16
+ * migration table, which names every tombstone — and so is the CVC
17
+ * missingness group (`missingness_root` and its children), which is not a
18
+ * scope row. A live entry missing a field the resolver needs throws: binding
19
+ * fails closed rather than guess.
20
+ *
21
+ * Migrations: `migrations.table`, with each line's release-grain fields
22
+ * (`releaseReading` / `policyReading` / `informational`, Crysta's ruling of
23
+ * 2026-10-09). A `retain` line carries the v3 field membership of its `from`
24
+ * code, read from that code's ENTRY (`v3Fields` / `v3Domains` /
25
+ * `v3FieldsNote`, on the retired tombstone), so the SOT states it once. A
26
+ * `retain` line whose entry has no `v3Fields` throws: binding fails closed.
27
+ *
28
+ * Usage:
29
+ * ```ts
30
+ * import { coreInformationScopeSot } from "@htilabs/platform-common-models/cvcs";
31
+ * import {
32
+ * createInformationScopeResolver, scopeRowsFromSot, scopeMigrationsFromSot,
33
+ * } from "@htilabs/platform-common-models/information-scope";
34
+ *
35
+ * const scope = createInformationScopeResolver({
36
+ * rows: scopeRowsFromSot(coreInformationScopeSot),
37
+ * migrations: scopeMigrationsFromSot(coreInformationScopeSot),
38
+ * });
39
+ * ```
40
+ */
41
+
42
+ import type {
43
+ ScopeKindBranch,
44
+ ScopeMigration,
45
+ ScopeMigrationRule,
46
+ ScopeRow,
47
+ ScopeRowStatus,
48
+ ScopeRowType,
49
+ ScopeSpecialDataType,
50
+ } from "./informationScopeResolver.js";
51
+
52
+ /** The SOT entry fields the adapter reads (structural, so the JSON import binds). */
53
+ export interface CoreInformationScopeSotEntry {
54
+ key: string;
55
+ canonicalCode?: string;
56
+ parentKey?: string | null;
57
+ rowType?: string;
58
+ kindBranch?: string | null;
59
+ kindRow?: string;
60
+ apps?: { pave: boolean; thread: boolean; leads: boolean };
61
+ selectable?: boolean;
62
+ shareableDefault?: boolean;
63
+ platformFloor?: boolean;
64
+ levelFloor?: number;
65
+ specialDataType?: string;
66
+ status?: string;
67
+ replacesV3?: readonly string[];
68
+ /** On a tombstone: its RESTRICTION reading; the table's `subtract` line is what binds. */
69
+ restrictionSuccessors?: readonly string[];
70
+ /** On a `releaseReading: "retain"` line's `from` entry: its v3 fields (field ids). */
71
+ v3Fields?: readonly string[];
72
+ /** Their assertion domains — v3 CATEGORY grain (the field family), not the unit's membership. */
73
+ v3Domains?: readonly string[];
74
+ v3FieldsNote?: string;
75
+ }
76
+
77
+ export interface CoreInformationScopeSotMigrationLine {
78
+ from: string;
79
+ to: readonly string[];
80
+ rule: string;
81
+ note?: string;
82
+ widens?: boolean;
83
+ releaseReading?: string;
84
+ releaseReadingNote?: string;
85
+ policyReading?: string;
86
+ informational?: boolean;
87
+ }
88
+
89
+ export interface CoreInformationScopeSot {
90
+ entries: readonly CoreInformationScopeSotEntry[];
91
+ migrations?: { table: readonly CoreInformationScopeSotMigrationLine[] };
92
+ }
93
+
94
+ const ROW_TYPES: ReadonlySet<string> = new Set<ScopeRowType>([
95
+ "branch",
96
+ "category",
97
+ "subcategory",
98
+ "sub-category",
99
+ "person_type",
100
+ "category_rest",
101
+ "instrument row",
102
+ ]);
103
+ const KIND_BRANCHES: ReadonlySet<string> = new Set([
104
+ "client",
105
+ "offenders",
106
+ "family",
107
+ "others",
108
+ "leads",
109
+ ]);
110
+ const LIVE: ReadonlySet<string> = new Set<ScopeRowStatus>(["as_today", "new"]);
111
+ const MISSINGNESS_ROOT = "missingness_root";
112
+
113
+ /** Package key → canon scope code, through `canonicalCode`. */
114
+ function keyReader(sot: CoreInformationScopeSot): (key: string) => string {
115
+ const byKey = new Map(sot.entries.map((e) => [e.key, e.canonicalCode ?? e.key]));
116
+ return (key) => byKey.get(key) ?? key.replace(/__/g, ".");
117
+ }
118
+
119
+ function fail(key: string, field: string, value: unknown): never {
120
+ throw new TypeError(
121
+ `information scope SOT: live entry "${key}" has ${field} ${JSON.stringify(value)}`,
122
+ );
123
+ }
124
+
125
+ /** The live v4 tree rows of a CVC-236 SOT, in the resolver's selection-code space. */
126
+ export function scopeRowsFromSot(sot: CoreInformationScopeSot): ScopeRow[] {
127
+ const code = keyReader(sot);
128
+ const missingness = new Set(
129
+ sot.entries
130
+ .filter((e) => e.key === MISSINGNESS_ROOT || e.parentKey === MISSINGNESS_ROOT)
131
+ .map((e) => e.key),
132
+ );
133
+ const rows: ScopeRow[] = [];
134
+ for (const e of sot.entries) {
135
+ if (missingness.has(e.key)) continue;
136
+ if (e.status === "retired") continue;
137
+ if (e.status === undefined || !LIVE.has(e.status)) fail(e.key, "status", e.status);
138
+ if (e.rowType === undefined || !ROW_TYPES.has(e.rowType)) fail(e.key, "rowType", e.rowType);
139
+ const kindBranch = e.kindBranch ?? null;
140
+ if (kindBranch !== null && !KIND_BRANCHES.has(kindBranch)) fail(e.key, "kindBranch", kindBranch);
141
+ if (e.apps === undefined) fail(e.key, "apps", e.apps);
142
+ for (const b of ["selectable", "shareableDefault", "platformFloor"] as const) {
143
+ if (typeof e[b] !== "boolean") fail(e.key, b, e[b]);
144
+ }
145
+ if (e.levelFloor !== 1 && e.levelFloor !== 3) fail(e.key, "levelFloor", e.levelFloor);
146
+ if (e.specialDataType === undefined) fail(e.key, "specialDataType", e.specialDataType);
147
+ const row: ScopeRow = {
148
+ scopeCode: code(e.key),
149
+ parentScopeCode: e.parentKey ? code(e.parentKey) : null,
150
+ rowType: e.rowType as ScopeRowType,
151
+ kindBranch: kindBranch as ScopeKindBranch,
152
+ apps: { pave: e.apps.pave, thread: e.apps.thread, leads: e.apps.leads },
153
+ selectable: e.selectable as boolean,
154
+ shareableDefault: e.shareableDefault as boolean,
155
+ platformFloor: e.platformFloor as boolean,
156
+ levelFloor: e.levelFloor,
157
+ specialDataType: e.specialDataType as ScopeSpecialDataType,
158
+ status: e.status as ScopeRowStatus,
159
+ replacesV3: [...(e.replacesV3 ?? [])],
160
+ };
161
+ if (e.kindRow !== undefined) row.kindRow = code(e.kindRow);
162
+ rows.push(row);
163
+ }
164
+ return rows;
165
+ }
166
+
167
+ /** The v3 → v4 from-to table of a CVC-236 SOT (`migrations.table`), in selection codes. */
168
+ export function scopeMigrationsFromSot(sot: CoreInformationScopeSot): ScopeMigration[] {
169
+ const code = keyReader(sot);
170
+ const byKey = new Map(sot.entries.map((e) => [e.key, e]));
171
+ return (sot.migrations?.table ?? []).map((l) => {
172
+ const m: ScopeMigration = {
173
+ from: code(l.from),
174
+ to: l.to.map(code),
175
+ rule: l.rule as ScopeMigrationRule,
176
+ ...(l.note === undefined ? {} : { note: l.note }),
177
+ ...(l.widens === undefined ? {} : { widens: l.widens }),
178
+ ...(l.informational === undefined ? {} : { informational: l.informational }),
179
+ ...(l.policyReading === undefined
180
+ ? {}
181
+ : { policyReading: l.policyReading as ScopeMigration["policyReading"] }),
182
+ };
183
+ if (l.releaseReading === undefined) return m;
184
+ if (l.releaseReading !== "retain") {
185
+ return {
186
+ ...m,
187
+ releaseReading: l.releaseReading as ScopeMigration["releaseReading"],
188
+ ...(l.releaseReadingNote === undefined ? {} : { releaseReadingNote: l.releaseReadingNote }),
189
+ };
190
+ }
191
+ const e = byKey.get(l.from);
192
+ if (e?.v3Fields === undefined || e.v3Domains === undefined) {
193
+ fail(l.from, "v3Fields / v3Domains (its line is releaseReading retain)", e?.v3Fields);
194
+ }
195
+ return {
196
+ ...m,
197
+ releaseReading: l.releaseReading as ScopeMigration["releaseReading"],
198
+ v3Fields: [...e.v3Fields],
199
+ v3Domains: [...e.v3Domains],
200
+ ...(e.v3FieldsNote === undefined ? {} : { v3FieldsNote: e.v3FieldsNote }),
201
+ };
202
+ });
203
+ }