@htilabs/platform-common-models 0.19.0 → 0.20.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 (50) hide show
  1. package/dist/cvcs/index.cjs +4769 -643
  2. package/dist/cvcs/index.cjs.map +1 -1
  3. package/dist/cvcs/index.d.cts +5036 -606
  4. package/dist/cvcs/index.d.ts +5036 -606
  5. package/dist/cvcs/index.js +4769 -643
  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.cjs +5199 -588
  14. package/dist/index.cjs.map +1 -1
  15. package/dist/index.d.cts +1 -0
  16. package/dist/index.d.ts +1 -0
  17. package/dist/index.js +5189 -588
  18. package/dist/index.js.map +1 -1
  19. package/dist/information-scope/index.cjs +440 -0
  20. package/dist/information-scope/index.cjs.map +1 -0
  21. package/dist/information-scope/index.d.cts +313 -0
  22. package/dist/information-scope/index.d.ts +313 -0
  23. package/dist/information-scope/index.js +404 -0
  24. package/dist/information-scope/index.js.map +1 -0
  25. package/dist/services/index.cjs +414 -2
  26. package/dist/services/index.cjs.map +1 -1
  27. package/dist/services/index.d.cts +1 -0
  28. package/dist/services/index.d.ts +1 -0
  29. package/dist/services/index.js +403 -1
  30. package/dist/services/index.js.map +1 -1
  31. package/package.json +32 -26
  32. package/src/__tests__/__snapshots__/cvc-sot.snap +3 -3
  33. package/src/__tests__/core-information-scope-invariant.test.ts +709 -456
  34. package/src/__tests__/cvc-sot-snapshot.test.ts +16 -17
  35. package/src/__tests__/cvc-structural.test.ts +2 -2
  36. package/src/__tests__/location-type-routing-invariant.test.ts +25 -8
  37. package/src/cvcs/coreInformationScope.v2.0.0.json +5396 -0
  38. package/src/cvcs/index.ts +2 -2
  39. package/src/cvcs/roiScope.v1.3.0.json +360 -0
  40. package/src/generated/cvc-enums.ts +77 -4
  41. package/src/services/__tests__/fixtures/infoscope-v4/information_scope_v4.migrations.csv +106 -0
  42. package/src/services/__tests__/fixtures/infoscope-v4/information_scope_v4.rows.csv +117 -0
  43. package/src/services/__tests__/fixtures/infoscope-v4/loadInfoscopeV4Fixtures.ts +116 -0
  44. package/src/services/__tests__/informationScopeResolver.test.ts +964 -0
  45. package/src/services/index.ts +10 -3
  46. package/src/services/informationScope.ts +10 -0
  47. package/src/services/informationScopeResolver.ts +672 -0
  48. package/src/services/informationScopeSot.ts +161 -0
  49. package/src/cvcs/coreInformationScope.v1.1.0.json +0 -1290
  50. package/src/cvcs/roiScope.v1.2.0.json +0 -340
@@ -0,0 +1,313 @@
1
+ /**
2
+ * @htilabs/platform-common-models — Information scope resolver (CVC-236 v4)
3
+ *
4
+ * The ONE implementation of how a stored information-scope selection reads
5
+ * against the v4 tree, so Thread and PAVE (preview and send, picker and door)
6
+ * cannot disagree. Pure and dependency-free: no imports, no I/O, never
7
+ * mutates its inputs. Browser-safe entry: `@htilabs/platform-common-models/information-scope`.
8
+ *
9
+ * Spec (canon, read-only): htilabstech/prototype
10
+ * docs/share-roi/INFOSCOPE_V4_DEV_HANDOFF_2026-10-09.md
11
+ * @ 00179edcb3f0c00a8b55beeffd1618c8a5c98937 (signed; the handoff and its
12
+ * CSVs are unchanged from 6dab8a95)
13
+ * - § 2 rules 1–7 ("the resolver contract — build exactly this, nothing
14
+ * cleverer") — every behaviour below cites its rule;
15
+ * - § 3 the migration rules (identity · row · category · subtract ·
16
+ * retired before v4) and `scopeVersion`; a signed release keeps its list
17
+ * as signed and its current reading is DERIVED at read time; a retired
18
+ * code "stays recognisable in stored data forever";
19
+ * - § 7 row 6 a branch-grain pick is expanded to the ceiling's grain
20
+ * before clamping; a sender can never widen;
21
+ * - § 8 the enums.
22
+ * Reference implementation of rule-1 kind-row resolution:
23
+ * tools/infoscope/phase4_stress_test.py `resolve_home` (same SHA).
24
+ *
25
+ * WHAT A SELECTION STORES. `information_scope: string[]` holds canon's scope
26
+ * codes as canon spells them — `names`, `identifying.other`,
27
+ * `offenders.risk` (handoff § 8: "lowercase snake, or `<kind>.<row>`") —
28
+ * NOT the package's SOT keys (`offenders__risk`) and NOT seven-segment wire
29
+ * codes (`236-016-001-002-…`). `ScopeRow.scopeCode` / `parentScopeCode` are
30
+ * in that space; `scopeRowsFromSot` maps the SOT into it.
31
+ *
32
+ * ALWAYS COVERED. `system_info` and its ancestor `system` ("System metadata —
33
+ * always included, never a choice", handoff § 1; the field placements home
34
+ * the system fields on `system`) are covered by every selection.
35
+ *
36
+ * Two kinds of call:
37
+ * - READS (`isCovered`, `isIncludedOnShare`, `shareVerdict`,
38
+ * `isVisibleAtLevel`, `readSelection`, `readRestriction`,
39
+ * `expandBranchPickToGrain`, `clampToCeiling`) are total: they never
40
+ * throw on stored data. An unknown code, a null list or an unsupported
41
+ * `scopeVersion` (absent, 2, or anything but 3 / 4) includes nothing
42
+ * (fail closed).
43
+ * - PICKER WRITES (`selectAll`, `deselectChild`, `expandSelectAll`), the
44
+ * build-time `rowForSubject`, and the constructor throw on programming
45
+ * errors (an unknown or non-selectable code, a malformed tree).
46
+ */
47
+ /** The tree version this resolver reads to (handoff § 3: "today 3, after this round 4"). */
48
+ declare const INFORMATION_SCOPE_VERSION: 4;
49
+ /**
50
+ * The `scopeVersion` stamps a stored list may carry and still be read: 3
51
+ * (through the v3 → v4 table) and 4. A 2 list, and an UNSTAMPED list (which
52
+ * is v2-era), must go through canon's conjunctive v2 → v3 table first (SOT
53
+ * v2.0.0 `migrations.readAt` / `migrations.unstamped`: the `retired before
54
+ * v4` lines name "the flattened v3 reading, not an unconditional one"); this
55
+ * package ships no v2 → v3 table, so those lists are unsupported and include
56
+ * nothing (fail closed). None was ever persisted (`migrations.unstamped`).
57
+ */
58
+ declare const INFORMATION_SCOPE_READABLE_VERSIONS: readonly number[];
59
+ /** Required on every stored selection and always included (handoff § 2 rule 1; § 6). */
60
+ declare const INFORMATION_SCOPE_SYSTEM_INFO: "system_info";
61
+ /** A kind of other named person (handoff § 1; § 8 `kind_branch`). */
62
+ type ScopePersonKind = "offenders" | "family" | "others";
63
+ /** Whose record a record is: the client, or another named person's kind (rule 1). */
64
+ type ScopeSubjectKind = "client" | ScopePersonKind;
65
+ /** `kind_branch` (§ 8); `null` on System and Notes rows (blank in the CSV). */
66
+ type ScopeKindBranch = ScopeSubjectKind | "leads" | null;
67
+ /**
68
+ * `row_type` (§ 8). The tree also carries `branch` (`primary_client`,
69
+ * `other_named_persons`) and the LEADS spelling `sub-category`, which § 8's
70
+ * list omits; both are accepted as written.
71
+ */
72
+ type ScopeRowType = "branch" | "category" | "subcategory" | "sub-category" | "person_type" | "category_rest" | "instrument row";
73
+ /** `status` (§ 8). */
74
+ type ScopeRowStatus = "as_today" | "new" | "retired";
75
+ /** `special_data_type` (§ 8, plus `evidence`, which the tree carries on `case_attachments`). */
76
+ type ScopeSpecialDataType = "none" | "survivor_confidential" | "criminal_intelligence" | "evidence";
77
+ /** The three app-relevance columns (§ 4). */
78
+ type ScopeApp = "pave" | "thread" | "leads";
79
+ type ScopeApps = Readonly<Record<ScopeApp, boolean>>;
80
+ /**
81
+ * One tree row, in the selection-code space (see header). Bind the SOT with
82
+ * `scopeRowsFromSot`. Extra fields on a caller's row type are carried through
83
+ * (`row(code)` returns the caller's row).
84
+ */
85
+ interface ScopeRow {
86
+ /** The code a selection stores (canon's spelling: `offenders.risk`). */
87
+ scopeCode: string;
88
+ parentScopeCode: string | null;
89
+ rowType: ScopeRowType;
90
+ kindBranch: ScopeKindBranch;
91
+ /** On a per-kind row (`offenders.risk`): the client row it copies (`risk`). Required there. */
92
+ kindRow?: string;
93
+ /** App relevance (§ 4). Informational: no resolver decision reads it. */
94
+ apps: ScopeApps;
95
+ selectable: boolean;
96
+ /** `shareable_default = on` (rule 4: `false` = off by default). */
97
+ shareableDefault: boolean;
98
+ platformFloor: boolean;
99
+ levelFloor: 1 | 3;
100
+ specialDataType: ScopeSpecialDataType;
101
+ /** A `retired` row is never covered, offered or written. */
102
+ status: ScopeRowStatus;
103
+ replacesV3?: readonly string[];
104
+ }
105
+ /** The four migration rules of handoff § 3, plus the pre-v4 retirement reading. */
106
+ type ScopeMigrationRule = "identity" | "row" | "category" | "subtract" | "retired before v4";
107
+ /** One from-to line (selection-code space); `to` is empty for "(nothing)". */
108
+ interface ScopeMigration {
109
+ from: string;
110
+ to: readonly string[];
111
+ rule: ScopeMigrationRule;
112
+ note?: string;
113
+ /** The line reads WIDER than v3 did (SOT `widens: true`; consent widening is an open question). */
114
+ widens?: boolean;
115
+ }
116
+ /** How one stored code was read. `unknown` = no row, no table line: it includes nothing. */
117
+ type ScopeReadingRule = ScopeMigrationRule | "unknown";
118
+ interface ScopeCodeReading {
119
+ readonly from: string;
120
+ readonly rule: ScopeReadingRule;
121
+ readonly reads: readonly string[];
122
+ /** The table line it read through is flagged as reading wider than v3. */
123
+ readonly widens: boolean;
124
+ }
125
+ /**
126
+ * The current (v4) reading of a stored list. `stored` and `storedVersion` are
127
+ * the list as signed, copied, never rewritten (§ 3: "a signed release keeps
128
+ * its list as signed, at the version signed; its current reading is derived
129
+ * through the table at read time").
130
+ */
131
+ interface ScopeReading {
132
+ /** The stamp as stored; `null` when it was absent or not a number. */
133
+ readonly storedVersion: number | null;
134
+ readonly stored: readonly string[];
135
+ readonly version: typeof INFORMATION_SCOPE_VERSION;
136
+ /** The stamp is not in `INFORMATION_SCOPE_READABLE_VERSIONS`: every code reads `unknown`. */
137
+ readonly unsupportedVersion: boolean;
138
+ /**
139
+ * The derived v4 list: unique, in tree order. A selection reading always
140
+ * contains `system_info`; a restriction reading contains only what it restricts.
141
+ */
142
+ readonly informationScope: readonly string[];
143
+ /** One entry per distinct stored code, in stored order. */
144
+ readonly codes: readonly ScopeCodeReading[];
145
+ /** Stored codes that are retired (read by `row`, `subtract` or `retired before v4`). */
146
+ readonly retired: readonly string[];
147
+ /** Stored codes with no live row and no table line; they include nothing. */
148
+ readonly unknown: readonly string[];
149
+ /** Stored codes whose reading is wider than v3's (`widens`): surface, never hide. */
150
+ readonly widened: readonly string[];
151
+ }
152
+ type ScopeShareVerdict = {
153
+ readonly included: true;
154
+ readonly reason: "included";
155
+ } | {
156
+ readonly included: false;
157
+ readonly reason: "not_covered" | "platform_floor" | "unknown_code";
158
+ } | {
159
+ readonly included: false;
160
+ readonly reason: "off_by_default";
161
+ /** The off-by-default rows in the chain the account has not enabled. */
162
+ readonly notEnabled: readonly string[];
163
+ };
164
+ type ScopeShareReason = ScopeShareVerdict["reason"];
165
+ interface ScopeShareOptions {
166
+ /** The off-by-default rows the account's policy has enabled for sharing (rule 4). */
167
+ enabledOffByDefault?: ReadonlySet<string> | readonly string[];
168
+ }
169
+ interface CreateInformationScopeResolverInput<R extends ScopeRow> {
170
+ rows: readonly R[];
171
+ migrations?: readonly ScopeMigration[];
172
+ }
173
+ /** A stored list as it may arrive from storage (reads are total). */
174
+ type StoredScopeList = readonly string[] | null | undefined;
175
+ interface InformationScopeResolver<R extends ScopeRow = ScopeRow> {
176
+ readonly version: typeof INFORMATION_SCOPE_VERSION;
177
+ /** Every row in input order. */
178
+ readonly rows: readonly R[];
179
+ row(code: string): R | undefined;
180
+ /** The live (non-retired) children of `code`, in input order (a copy). */
181
+ childrenOf(code: string): string[];
182
+ /** `code` first, then its parent, up to the root (a copy). Empty for an unknown code. */
183
+ ancestorsOf(code: string): string[];
184
+ /** Rules 2 + 3. */
185
+ isCovered(selection: StoredScopeList, code: string): boolean;
186
+ /** Rules 2–5. */
187
+ isIncludedOnShare(selection: StoredScopeList, code: string, options?: ScopeShareOptions): boolean;
188
+ /** `isIncludedOnShare` with the reason, for "held back and counted". */
189
+ shareVerdict(selection: StoredScopeList, code: string, options?: ScopeShareOptions): ScopeShareVerdict;
190
+ /** Rule 7 (the viewing side). */
191
+ isVisibleAtLevel(level: number, code: string): boolean;
192
+ /** Rules 3 + 6: the codes a picker writes when it expands `code` (its live children, rest row included). */
193
+ expandSelectAll(code: string): string[];
194
+ /** Rule 6: select-all at `code` (the code itself is stored; its now-redundant descendants drop). */
195
+ selectAll(selection: readonly string[], code: string): string[];
196
+ /** Rules 3 + 6: de-select one child; every selected ancestor is replaced by its other children. */
197
+ deselectChild(selection: readonly string[], childCode: string): string[];
198
+ /** § 3: the current v4 reading of a stored selection. */
199
+ readSelection(list: StoredScopeList, scopeVersion: number | null | undefined): ScopeReading;
200
+ /** § 3 `subtract`: the current v4 reading of a stored RESTRICTION. */
201
+ readRestriction(list: StoredScopeList, scopeVersion: number | null | undefined): ScopeReading;
202
+ /** Rule 1: the row a record is included under, given its field's home row and its subject. */
203
+ rowForSubject(homeRow: string, kind: ScopeSubjectKind): string;
204
+ /** § 7 row 6: expand every pick that sits above the ceiling's grain into its children. */
205
+ expandBranchPickToGrain(selection: StoredScopeList, ceiling: StoredScopeList): string[];
206
+ /** § 7 row 6: expand, then keep only what the ceiling covers. A sender can never widen. */
207
+ clampToCeiling(selection: StoredScopeList, ceiling: StoredScopeList): string[];
208
+ }
209
+ /** A row a picker offers as a choice (§ 8 `selectable`; never a retired row). */
210
+ declare const isSelectableScopeRow: (row: ScopeRow | undefined) => boolean;
211
+ /** The `category_rest` row (rule 3): never offered, covered with its category. */
212
+ declare const isScopeRestRow: (row: ScopeRow | undefined) => boolean;
213
+ /** One of the 28 `summary_<x>` / `full_<x>` rows (§ 8 `instrument row`). */
214
+ declare const isScopeInstrumentRow: (row: ScopeRow | undefined) => boolean;
215
+ /**
216
+ * Which kind of other named person someone is (handoff § 2 rule 1; § 8; Phase
217
+ * 3 D5): "This person caused harm" wins; "Eligible family member" (asserted
218
+ * by the advocate, never derived from the relationship) otherwise; neither →
219
+ * `others`. A person with both switches is listed under `offenders`; the
220
+ * caller keeps the family-member VAWA handling, which rides `efmAsserted` on
221
+ * the person, not the kind.
222
+ */
223
+ declare function kindForPerson(person: {
224
+ causedHarm: boolean;
225
+ efmAsserted: boolean;
226
+ }): ScopePersonKind;
227
+ /**
228
+ * Bind the resolver to one tree (and its migration table). Throws on a
229
+ * malformed tree: a duplicate code, a parent that is not a row, a cycle, no
230
+ * `system_info` row, a live row whose `specialDataType` is missing or not in
231
+ * § 8 (rule 1 routes on it — absence fails closed by refusing to bind), a
232
+ * per-kind row without a `kindRow` that names a row, an unknown migration
233
+ * rule, a migration successor that is not a live row, or two different
234
+ * readings for the same code and rule.
235
+ */
236
+ declare function createInformationScopeResolver<R extends ScopeRow>(input: CreateInformationScopeResolverInput<R>): InformationScopeResolver<R>;
237
+
238
+ /**
239
+ * @htilabs/platform-common-models — CVC-236 SOT → information-scope resolver binding
240
+ *
241
+ * Maps the `core_information_scope` SOT envelope (`coreInformationScope.v2.0.0.json`,
242
+ * exported as `coreInformationScopeSot` from `/cvcs`) into the resolver's
243
+ * input shapes. Pure and dependency-free: the caller passes the envelope.
244
+ *
245
+ * The SOT keys a row by its package key (`offenders__risk`, `identifying__other`:
246
+ * canon's dotted codes with `.` spelled `__`) and by a seven-segment wire code;
247
+ * a stored selection holds canon's dotted code (`offenders.risk`). The
248
+ * adapter reads every key through the entry's `canonicalCode` (present on the
249
+ * dotted rows) and falls back to `__` → `.` for a key with no entry.
250
+ *
251
+ * Rows: the live v4 tree only (`status` `as_today` / `new`). The retired
252
+ * tombstones are left out — a stored retired code reads through the
253
+ * migration table, which names every tombstone — and so is the CVC
254
+ * missingness group (`missingness_root` and its children), which is not a
255
+ * scope row. A live entry missing a field the resolver needs throws: binding
256
+ * fails closed rather than guess.
257
+ *
258
+ * Usage:
259
+ * ```ts
260
+ * import { coreInformationScopeSot } from "@htilabs/platform-common-models/cvcs";
261
+ * import {
262
+ * createInformationScopeResolver, scopeRowsFromSot, scopeMigrationsFromSot,
263
+ * } from "@htilabs/platform-common-models/information-scope";
264
+ *
265
+ * const scope = createInformationScopeResolver({
266
+ * rows: scopeRowsFromSot(coreInformationScopeSot),
267
+ * migrations: scopeMigrationsFromSot(coreInformationScopeSot),
268
+ * });
269
+ * ```
270
+ */
271
+
272
+ /** The SOT entry fields the adapter reads (structural, so the JSON import binds). */
273
+ interface CoreInformationScopeSotEntry {
274
+ key: string;
275
+ canonicalCode?: string;
276
+ parentKey?: string | null;
277
+ rowType?: string;
278
+ kindBranch?: string | null;
279
+ kindRow?: string;
280
+ apps?: {
281
+ pave: boolean;
282
+ thread: boolean;
283
+ leads: boolean;
284
+ };
285
+ selectable?: boolean;
286
+ shareableDefault?: boolean;
287
+ platformFloor?: boolean;
288
+ levelFloor?: number;
289
+ specialDataType?: string;
290
+ status?: string;
291
+ replacesV3?: readonly string[];
292
+ /** On a tombstone: its RESTRICTION reading; the table's `subtract` line is what binds. */
293
+ restrictionSuccessors?: readonly string[];
294
+ }
295
+ interface CoreInformationScopeSotMigrationLine {
296
+ from: string;
297
+ to: readonly string[];
298
+ rule: string;
299
+ note?: string;
300
+ widens?: boolean;
301
+ }
302
+ interface CoreInformationScopeSot {
303
+ entries: readonly CoreInformationScopeSotEntry[];
304
+ migrations?: {
305
+ table: readonly CoreInformationScopeSotMigrationLine[];
306
+ };
307
+ }
308
+ /** The live v4 tree rows of a CVC-236 SOT, in the resolver's selection-code space. */
309
+ declare function scopeRowsFromSot(sot: CoreInformationScopeSot): ScopeRow[];
310
+ /** The v3 → v4 from-to table of a CVC-236 SOT (`migrations.table`), in selection codes. */
311
+ declare function scopeMigrationsFromSot(sot: CoreInformationScopeSot): ScopeMigration[];
312
+
313
+ export { type CoreInformationScopeSot, type CoreInformationScopeSotEntry, type CoreInformationScopeSotMigrationLine, type CreateInformationScopeResolverInput, INFORMATION_SCOPE_READABLE_VERSIONS, INFORMATION_SCOPE_SYSTEM_INFO, INFORMATION_SCOPE_VERSION, type InformationScopeResolver, type ScopeApp, type ScopeApps, type ScopeCodeReading, type ScopeKindBranch, type ScopeMigration, type ScopeMigrationRule, type ScopePersonKind, type ScopeReading, type ScopeReadingRule, type ScopeRow, type ScopeRowStatus, type ScopeRowType, type ScopeShareOptions, type ScopeShareReason, type ScopeShareVerdict, type ScopeSpecialDataType, type ScopeSubjectKind, type StoredScopeList, createInformationScopeResolver, isScopeInstrumentRow, isScopeRestRow, isSelectableScopeRow, kindForPerson, scopeMigrationsFromSot, scopeRowsFromSot };
@@ -0,0 +1,313 @@
1
+ /**
2
+ * @htilabs/platform-common-models — Information scope resolver (CVC-236 v4)
3
+ *
4
+ * The ONE implementation of how a stored information-scope selection reads
5
+ * against the v4 tree, so Thread and PAVE (preview and send, picker and door)
6
+ * cannot disagree. Pure and dependency-free: no imports, no I/O, never
7
+ * mutates its inputs. Browser-safe entry: `@htilabs/platform-common-models/information-scope`.
8
+ *
9
+ * Spec (canon, read-only): htilabstech/prototype
10
+ * docs/share-roi/INFOSCOPE_V4_DEV_HANDOFF_2026-10-09.md
11
+ * @ 00179edcb3f0c00a8b55beeffd1618c8a5c98937 (signed; the handoff and its
12
+ * CSVs are unchanged from 6dab8a95)
13
+ * - § 2 rules 1–7 ("the resolver contract — build exactly this, nothing
14
+ * cleverer") — every behaviour below cites its rule;
15
+ * - § 3 the migration rules (identity · row · category · subtract ·
16
+ * retired before v4) and `scopeVersion`; a signed release keeps its list
17
+ * as signed and its current reading is DERIVED at read time; a retired
18
+ * code "stays recognisable in stored data forever";
19
+ * - § 7 row 6 a branch-grain pick is expanded to the ceiling's grain
20
+ * before clamping; a sender can never widen;
21
+ * - § 8 the enums.
22
+ * Reference implementation of rule-1 kind-row resolution:
23
+ * tools/infoscope/phase4_stress_test.py `resolve_home` (same SHA).
24
+ *
25
+ * WHAT A SELECTION STORES. `information_scope: string[]` holds canon's scope
26
+ * codes as canon spells them — `names`, `identifying.other`,
27
+ * `offenders.risk` (handoff § 8: "lowercase snake, or `<kind>.<row>`") —
28
+ * NOT the package's SOT keys (`offenders__risk`) and NOT seven-segment wire
29
+ * codes (`236-016-001-002-…`). `ScopeRow.scopeCode` / `parentScopeCode` are
30
+ * in that space; `scopeRowsFromSot` maps the SOT into it.
31
+ *
32
+ * ALWAYS COVERED. `system_info` and its ancestor `system` ("System metadata —
33
+ * always included, never a choice", handoff § 1; the field placements home
34
+ * the system fields on `system`) are covered by every selection.
35
+ *
36
+ * Two kinds of call:
37
+ * - READS (`isCovered`, `isIncludedOnShare`, `shareVerdict`,
38
+ * `isVisibleAtLevel`, `readSelection`, `readRestriction`,
39
+ * `expandBranchPickToGrain`, `clampToCeiling`) are total: they never
40
+ * throw on stored data. An unknown code, a null list or an unsupported
41
+ * `scopeVersion` (absent, 2, or anything but 3 / 4) includes nothing
42
+ * (fail closed).
43
+ * - PICKER WRITES (`selectAll`, `deselectChild`, `expandSelectAll`), the
44
+ * build-time `rowForSubject`, and the constructor throw on programming
45
+ * errors (an unknown or non-selectable code, a malformed tree).
46
+ */
47
+ /** The tree version this resolver reads to (handoff § 3: "today 3, after this round 4"). */
48
+ declare const INFORMATION_SCOPE_VERSION: 4;
49
+ /**
50
+ * The `scopeVersion` stamps a stored list may carry and still be read: 3
51
+ * (through the v3 → v4 table) and 4. A 2 list, and an UNSTAMPED list (which
52
+ * is v2-era), must go through canon's conjunctive v2 → v3 table first (SOT
53
+ * v2.0.0 `migrations.readAt` / `migrations.unstamped`: the `retired before
54
+ * v4` lines name "the flattened v3 reading, not an unconditional one"); this
55
+ * package ships no v2 → v3 table, so those lists are unsupported and include
56
+ * nothing (fail closed). None was ever persisted (`migrations.unstamped`).
57
+ */
58
+ declare const INFORMATION_SCOPE_READABLE_VERSIONS: readonly number[];
59
+ /** Required on every stored selection and always included (handoff § 2 rule 1; § 6). */
60
+ declare const INFORMATION_SCOPE_SYSTEM_INFO: "system_info";
61
+ /** A kind of other named person (handoff § 1; § 8 `kind_branch`). */
62
+ type ScopePersonKind = "offenders" | "family" | "others";
63
+ /** Whose record a record is: the client, or another named person's kind (rule 1). */
64
+ type ScopeSubjectKind = "client" | ScopePersonKind;
65
+ /** `kind_branch` (§ 8); `null` on System and Notes rows (blank in the CSV). */
66
+ type ScopeKindBranch = ScopeSubjectKind | "leads" | null;
67
+ /**
68
+ * `row_type` (§ 8). The tree also carries `branch` (`primary_client`,
69
+ * `other_named_persons`) and the LEADS spelling `sub-category`, which § 8's
70
+ * list omits; both are accepted as written.
71
+ */
72
+ type ScopeRowType = "branch" | "category" | "subcategory" | "sub-category" | "person_type" | "category_rest" | "instrument row";
73
+ /** `status` (§ 8). */
74
+ type ScopeRowStatus = "as_today" | "new" | "retired";
75
+ /** `special_data_type` (§ 8, plus `evidence`, which the tree carries on `case_attachments`). */
76
+ type ScopeSpecialDataType = "none" | "survivor_confidential" | "criminal_intelligence" | "evidence";
77
+ /** The three app-relevance columns (§ 4). */
78
+ type ScopeApp = "pave" | "thread" | "leads";
79
+ type ScopeApps = Readonly<Record<ScopeApp, boolean>>;
80
+ /**
81
+ * One tree row, in the selection-code space (see header). Bind the SOT with
82
+ * `scopeRowsFromSot`. Extra fields on a caller's row type are carried through
83
+ * (`row(code)` returns the caller's row).
84
+ */
85
+ interface ScopeRow {
86
+ /** The code a selection stores (canon's spelling: `offenders.risk`). */
87
+ scopeCode: string;
88
+ parentScopeCode: string | null;
89
+ rowType: ScopeRowType;
90
+ kindBranch: ScopeKindBranch;
91
+ /** On a per-kind row (`offenders.risk`): the client row it copies (`risk`). Required there. */
92
+ kindRow?: string;
93
+ /** App relevance (§ 4). Informational: no resolver decision reads it. */
94
+ apps: ScopeApps;
95
+ selectable: boolean;
96
+ /** `shareable_default = on` (rule 4: `false` = off by default). */
97
+ shareableDefault: boolean;
98
+ platformFloor: boolean;
99
+ levelFloor: 1 | 3;
100
+ specialDataType: ScopeSpecialDataType;
101
+ /** A `retired` row is never covered, offered or written. */
102
+ status: ScopeRowStatus;
103
+ replacesV3?: readonly string[];
104
+ }
105
+ /** The four migration rules of handoff § 3, plus the pre-v4 retirement reading. */
106
+ type ScopeMigrationRule = "identity" | "row" | "category" | "subtract" | "retired before v4";
107
+ /** One from-to line (selection-code space); `to` is empty for "(nothing)". */
108
+ interface ScopeMigration {
109
+ from: string;
110
+ to: readonly string[];
111
+ rule: ScopeMigrationRule;
112
+ note?: string;
113
+ /** The line reads WIDER than v3 did (SOT `widens: true`; consent widening is an open question). */
114
+ widens?: boolean;
115
+ }
116
+ /** How one stored code was read. `unknown` = no row, no table line: it includes nothing. */
117
+ type ScopeReadingRule = ScopeMigrationRule | "unknown";
118
+ interface ScopeCodeReading {
119
+ readonly from: string;
120
+ readonly rule: ScopeReadingRule;
121
+ readonly reads: readonly string[];
122
+ /** The table line it read through is flagged as reading wider than v3. */
123
+ readonly widens: boolean;
124
+ }
125
+ /**
126
+ * The current (v4) reading of a stored list. `stored` and `storedVersion` are
127
+ * the list as signed, copied, never rewritten (§ 3: "a signed release keeps
128
+ * its list as signed, at the version signed; its current reading is derived
129
+ * through the table at read time").
130
+ */
131
+ interface ScopeReading {
132
+ /** The stamp as stored; `null` when it was absent or not a number. */
133
+ readonly storedVersion: number | null;
134
+ readonly stored: readonly string[];
135
+ readonly version: typeof INFORMATION_SCOPE_VERSION;
136
+ /** The stamp is not in `INFORMATION_SCOPE_READABLE_VERSIONS`: every code reads `unknown`. */
137
+ readonly unsupportedVersion: boolean;
138
+ /**
139
+ * The derived v4 list: unique, in tree order. A selection reading always
140
+ * contains `system_info`; a restriction reading contains only what it restricts.
141
+ */
142
+ readonly informationScope: readonly string[];
143
+ /** One entry per distinct stored code, in stored order. */
144
+ readonly codes: readonly ScopeCodeReading[];
145
+ /** Stored codes that are retired (read by `row`, `subtract` or `retired before v4`). */
146
+ readonly retired: readonly string[];
147
+ /** Stored codes with no live row and no table line; they include nothing. */
148
+ readonly unknown: readonly string[];
149
+ /** Stored codes whose reading is wider than v3's (`widens`): surface, never hide. */
150
+ readonly widened: readonly string[];
151
+ }
152
+ type ScopeShareVerdict = {
153
+ readonly included: true;
154
+ readonly reason: "included";
155
+ } | {
156
+ readonly included: false;
157
+ readonly reason: "not_covered" | "platform_floor" | "unknown_code";
158
+ } | {
159
+ readonly included: false;
160
+ readonly reason: "off_by_default";
161
+ /** The off-by-default rows in the chain the account has not enabled. */
162
+ readonly notEnabled: readonly string[];
163
+ };
164
+ type ScopeShareReason = ScopeShareVerdict["reason"];
165
+ interface ScopeShareOptions {
166
+ /** The off-by-default rows the account's policy has enabled for sharing (rule 4). */
167
+ enabledOffByDefault?: ReadonlySet<string> | readonly string[];
168
+ }
169
+ interface CreateInformationScopeResolverInput<R extends ScopeRow> {
170
+ rows: readonly R[];
171
+ migrations?: readonly ScopeMigration[];
172
+ }
173
+ /** A stored list as it may arrive from storage (reads are total). */
174
+ type StoredScopeList = readonly string[] | null | undefined;
175
+ interface InformationScopeResolver<R extends ScopeRow = ScopeRow> {
176
+ readonly version: typeof INFORMATION_SCOPE_VERSION;
177
+ /** Every row in input order. */
178
+ readonly rows: readonly R[];
179
+ row(code: string): R | undefined;
180
+ /** The live (non-retired) children of `code`, in input order (a copy). */
181
+ childrenOf(code: string): string[];
182
+ /** `code` first, then its parent, up to the root (a copy). Empty for an unknown code. */
183
+ ancestorsOf(code: string): string[];
184
+ /** Rules 2 + 3. */
185
+ isCovered(selection: StoredScopeList, code: string): boolean;
186
+ /** Rules 2–5. */
187
+ isIncludedOnShare(selection: StoredScopeList, code: string, options?: ScopeShareOptions): boolean;
188
+ /** `isIncludedOnShare` with the reason, for "held back and counted". */
189
+ shareVerdict(selection: StoredScopeList, code: string, options?: ScopeShareOptions): ScopeShareVerdict;
190
+ /** Rule 7 (the viewing side). */
191
+ isVisibleAtLevel(level: number, code: string): boolean;
192
+ /** Rules 3 + 6: the codes a picker writes when it expands `code` (its live children, rest row included). */
193
+ expandSelectAll(code: string): string[];
194
+ /** Rule 6: select-all at `code` (the code itself is stored; its now-redundant descendants drop). */
195
+ selectAll(selection: readonly string[], code: string): string[];
196
+ /** Rules 3 + 6: de-select one child; every selected ancestor is replaced by its other children. */
197
+ deselectChild(selection: readonly string[], childCode: string): string[];
198
+ /** § 3: the current v4 reading of a stored selection. */
199
+ readSelection(list: StoredScopeList, scopeVersion: number | null | undefined): ScopeReading;
200
+ /** § 3 `subtract`: the current v4 reading of a stored RESTRICTION. */
201
+ readRestriction(list: StoredScopeList, scopeVersion: number | null | undefined): ScopeReading;
202
+ /** Rule 1: the row a record is included under, given its field's home row and its subject. */
203
+ rowForSubject(homeRow: string, kind: ScopeSubjectKind): string;
204
+ /** § 7 row 6: expand every pick that sits above the ceiling's grain into its children. */
205
+ expandBranchPickToGrain(selection: StoredScopeList, ceiling: StoredScopeList): string[];
206
+ /** § 7 row 6: expand, then keep only what the ceiling covers. A sender can never widen. */
207
+ clampToCeiling(selection: StoredScopeList, ceiling: StoredScopeList): string[];
208
+ }
209
+ /** A row a picker offers as a choice (§ 8 `selectable`; never a retired row). */
210
+ declare const isSelectableScopeRow: (row: ScopeRow | undefined) => boolean;
211
+ /** The `category_rest` row (rule 3): never offered, covered with its category. */
212
+ declare const isScopeRestRow: (row: ScopeRow | undefined) => boolean;
213
+ /** One of the 28 `summary_<x>` / `full_<x>` rows (§ 8 `instrument row`). */
214
+ declare const isScopeInstrumentRow: (row: ScopeRow | undefined) => boolean;
215
+ /**
216
+ * Which kind of other named person someone is (handoff § 2 rule 1; § 8; Phase
217
+ * 3 D5): "This person caused harm" wins; "Eligible family member" (asserted
218
+ * by the advocate, never derived from the relationship) otherwise; neither →
219
+ * `others`. A person with both switches is listed under `offenders`; the
220
+ * caller keeps the family-member VAWA handling, which rides `efmAsserted` on
221
+ * the person, not the kind.
222
+ */
223
+ declare function kindForPerson(person: {
224
+ causedHarm: boolean;
225
+ efmAsserted: boolean;
226
+ }): ScopePersonKind;
227
+ /**
228
+ * Bind the resolver to one tree (and its migration table). Throws on a
229
+ * malformed tree: a duplicate code, a parent that is not a row, a cycle, no
230
+ * `system_info` row, a live row whose `specialDataType` is missing or not in
231
+ * § 8 (rule 1 routes on it — absence fails closed by refusing to bind), a
232
+ * per-kind row without a `kindRow` that names a row, an unknown migration
233
+ * rule, a migration successor that is not a live row, or two different
234
+ * readings for the same code and rule.
235
+ */
236
+ declare function createInformationScopeResolver<R extends ScopeRow>(input: CreateInformationScopeResolverInput<R>): InformationScopeResolver<R>;
237
+
238
+ /**
239
+ * @htilabs/platform-common-models — CVC-236 SOT → information-scope resolver binding
240
+ *
241
+ * Maps the `core_information_scope` SOT envelope (`coreInformationScope.v2.0.0.json`,
242
+ * exported as `coreInformationScopeSot` from `/cvcs`) into the resolver's
243
+ * input shapes. Pure and dependency-free: the caller passes the envelope.
244
+ *
245
+ * The SOT keys a row by its package key (`offenders__risk`, `identifying__other`:
246
+ * canon's dotted codes with `.` spelled `__`) and by a seven-segment wire code;
247
+ * a stored selection holds canon's dotted code (`offenders.risk`). The
248
+ * adapter reads every key through the entry's `canonicalCode` (present on the
249
+ * dotted rows) and falls back to `__` → `.` for a key with no entry.
250
+ *
251
+ * Rows: the live v4 tree only (`status` `as_today` / `new`). The retired
252
+ * tombstones are left out — a stored retired code reads through the
253
+ * migration table, which names every tombstone — and so is the CVC
254
+ * missingness group (`missingness_root` and its children), which is not a
255
+ * scope row. A live entry missing a field the resolver needs throws: binding
256
+ * fails closed rather than guess.
257
+ *
258
+ * Usage:
259
+ * ```ts
260
+ * import { coreInformationScopeSot } from "@htilabs/platform-common-models/cvcs";
261
+ * import {
262
+ * createInformationScopeResolver, scopeRowsFromSot, scopeMigrationsFromSot,
263
+ * } from "@htilabs/platform-common-models/information-scope";
264
+ *
265
+ * const scope = createInformationScopeResolver({
266
+ * rows: scopeRowsFromSot(coreInformationScopeSot),
267
+ * migrations: scopeMigrationsFromSot(coreInformationScopeSot),
268
+ * });
269
+ * ```
270
+ */
271
+
272
+ /** The SOT entry fields the adapter reads (structural, so the JSON import binds). */
273
+ interface CoreInformationScopeSotEntry {
274
+ key: string;
275
+ canonicalCode?: string;
276
+ parentKey?: string | null;
277
+ rowType?: string;
278
+ kindBranch?: string | null;
279
+ kindRow?: string;
280
+ apps?: {
281
+ pave: boolean;
282
+ thread: boolean;
283
+ leads: boolean;
284
+ };
285
+ selectable?: boolean;
286
+ shareableDefault?: boolean;
287
+ platformFloor?: boolean;
288
+ levelFloor?: number;
289
+ specialDataType?: string;
290
+ status?: string;
291
+ replacesV3?: readonly string[];
292
+ /** On a tombstone: its RESTRICTION reading; the table's `subtract` line is what binds. */
293
+ restrictionSuccessors?: readonly string[];
294
+ }
295
+ interface CoreInformationScopeSotMigrationLine {
296
+ from: string;
297
+ to: readonly string[];
298
+ rule: string;
299
+ note?: string;
300
+ widens?: boolean;
301
+ }
302
+ interface CoreInformationScopeSot {
303
+ entries: readonly CoreInformationScopeSotEntry[];
304
+ migrations?: {
305
+ table: readonly CoreInformationScopeSotMigrationLine[];
306
+ };
307
+ }
308
+ /** The live v4 tree rows of a CVC-236 SOT, in the resolver's selection-code space. */
309
+ declare function scopeRowsFromSot(sot: CoreInformationScopeSot): ScopeRow[];
310
+ /** The v3 → v4 from-to table of a CVC-236 SOT (`migrations.table`), in selection codes. */
311
+ declare function scopeMigrationsFromSot(sot: CoreInformationScopeSot): ScopeMigration[];
312
+
313
+ export { type CoreInformationScopeSot, type CoreInformationScopeSotEntry, type CoreInformationScopeSotMigrationLine, type CreateInformationScopeResolverInput, INFORMATION_SCOPE_READABLE_VERSIONS, INFORMATION_SCOPE_SYSTEM_INFO, INFORMATION_SCOPE_VERSION, type InformationScopeResolver, type ScopeApp, type ScopeApps, type ScopeCodeReading, type ScopeKindBranch, type ScopeMigration, type ScopeMigrationRule, type ScopePersonKind, type ScopeReading, type ScopeReadingRule, type ScopeRow, type ScopeRowStatus, type ScopeRowType, type ScopeShareOptions, type ScopeShareReason, type ScopeShareVerdict, type ScopeSpecialDataType, type ScopeSubjectKind, type StoredScopeList, createInformationScopeResolver, isScopeInstrumentRow, isScopeRestRow, isSelectableScopeRow, kindForPerson, scopeMigrationsFromSot, scopeRowsFromSot };