@htilabs/platform-common-models 0.20.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.
- package/dist/cvcs/index.cjs +222 -120
- package/dist/cvcs/index.cjs.map +1 -1
- package/dist/cvcs/index.d.cts +223 -117
- package/dist/cvcs/index.d.ts +223 -117
- package/dist/cvcs/index.js +222 -120
- package/dist/cvcs/index.js.map +1 -1
- package/dist/enums/index.cjs.map +1 -1
- package/dist/enums/index.d.cts +4 -4
- package/dist/enums/index.d.ts +4 -4
- package/dist/enums/index.js.map +1 -1
- package/dist/{index-I-DiX9eQ.d.ts → index-CDoqrfc1.d.ts} +1 -1
- package/dist/{index-CoVr1jIV.d.cts → index-Zu_mOJRn.d.cts} +1 -1
- package/dist/index.cjs +320 -137
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +319 -137
- package/dist/index.js.map +1 -1
- package/dist/information-scope/index.cjs +98 -17
- package/dist/information-scope/index.cjs.map +1 -1
- package/dist/information-scope/index.d.cts +142 -13
- package/dist/information-scope/index.d.ts +142 -13
- package/dist/information-scope/index.js +97 -17
- package/dist/information-scope/index.js.map +1 -1
- package/dist/models/index.d.cts +2 -2
- package/dist/models/index.d.ts +2 -2
- package/dist/schemas/index.d.cts +25 -25
- package/dist/schemas/index.d.ts +25 -25
- package/dist/services/index.cjs +98 -17
- package/dist/services/index.cjs.map +1 -1
- package/dist/services/index.d.cts +1 -1
- package/dist/services/index.d.ts +1 -1
- package/dist/services/index.js +97 -17
- package/dist/services/index.js.map +1 -1
- package/package.json +1 -1
- package/src/__tests__/__snapshots__/cvc-sot.snap +2 -2
- package/src/__tests__/core-information-scope-invariant.test.ts +141 -15
- package/src/__tests__/cvc-sot-snapshot.test.ts +4 -3
- package/src/__tests__/cvc-structural.test.ts +2 -2
- package/src/__tests__/location-type-routing-invariant.test.ts +1 -1
- package/src/cvcs/{coreInformationScope.v2.0.0.json → coreInformationScope.v2.1.0.json} +190 -88
- package/src/cvcs/index.ts +2 -2
- package/src/cvcs/{roiScope.v1.3.0.json → roiScope.v1.4.0.json} +26 -26
- package/src/generated/cvc-enums.ts +4 -4
- package/src/services/__tests__/fixtures/infoscope-v4/information_scope_v3_placements.projection.csv +12 -0
- package/src/services/__tests__/fixtures/infoscope-v4/information_scope_v4.migrations.csv +27 -27
- package/src/services/__tests__/fixtures/infoscope-v4/information_scope_v4.rows.csv +1 -1
- package/src/services/__tests__/fixtures/infoscope-v4/loadInfoscopeV4Fixtures.ts +85 -14
- package/src/services/__tests__/informationScopeResolver.test.ts +336 -22
- package/src/services/informationScopeResolver.ts +226 -19
- package/src/services/informationScopeSot.ts +50 -8
- package/dist/{cvcEntry-BCj1OWqL.d.cts → cvcEntry-0BIB9sen.d.cts} +8 -8
- package/dist/{cvcEntry-BCj1OWqL.d.ts → cvcEntry-0BIB9sen.d.ts} +8 -8
|
@@ -8,8 +8,10 @@
|
|
|
8
8
|
*
|
|
9
9
|
* Spec (canon, read-only): htilabstech/prototype
|
|
10
10
|
* docs/share-roi/INFOSCOPE_V4_DEV_HANDOFF_2026-10-09.md
|
|
11
|
-
* @
|
|
12
|
-
*
|
|
11
|
+
* @ 7ca7e586ae487c608da657d426598a65d5b06111 (merge of the SIGNED-GRAIN
|
|
12
|
+
* content commit e86dd89cdba5cbb39ccfc7fb35aff8cbf0774790, which amends
|
|
13
|
+
* § 3 only and re-labels the migrations CSV; § 2, § 7, § 8 and the rows CSV
|
|
14
|
+
* are unchanged from 6dab8a95 / 00179edc)
|
|
13
15
|
* - § 2 rules 1–7 ("the resolver contract — build exactly this, nothing
|
|
14
16
|
* cleverer") — every behaviour below cites its rule;
|
|
15
17
|
* - § 3 the migration rules (identity · row · category · subtract ·
|
|
@@ -19,6 +21,19 @@
|
|
|
19
21
|
* - § 7 row 6 a branch-grain pick is expanded to the ceiling's grain
|
|
20
22
|
* before clamping; a sender can never widen;
|
|
21
23
|
* - § 8 the enums.
|
|
24
|
+
* Release grain (Crysta, 2026-10-09; SOT v2.1.0 `migrations.ruling`, quoted
|
|
25
|
+
* verbatim there): "a SIGNED RELEASE keeps the grain it was signed at ...
|
|
26
|
+
* Policies and presets (agency-authored, not consent) take the merged
|
|
27
|
+
* successor with a dated version row." Canon carries it since SIGNED-GRAIN
|
|
28
|
+
* (prototype e86dd89c: `signed_release_grain: keep` on the nine `rows` merge
|
|
29
|
+
* folds; handoff § 3 amended). So `readSelection` takes WHOSE list it is
|
|
30
|
+
* (`subject`): a release or a share (frozen at send, § 3) naming a code on a
|
|
31
|
+
* `releaseReading: "retain"` line at scopeVersion 3 is NOT mapped — the code
|
|
32
|
+
* comes back under `retained` with its v3 field membership, for the builder
|
|
33
|
+
* to deliver read-only; a policy takes the successor (`widened`) and the
|
|
34
|
+
* reading says a dated version row is due. The widening identity line canon
|
|
35
|
+
* leaves unmarked (`immigration_status`, `releaseReading: "successor"`) reads
|
|
36
|
+
* as itself for every subject.
|
|
22
37
|
* Reference implementation of rule-1 kind-row resolution:
|
|
23
38
|
* tools/infoscope/phase4_stress_test.py `resolve_home` (same SHA).
|
|
24
39
|
*
|
|
@@ -39,7 +54,8 @@
|
|
|
39
54
|
* `expandBranchPickToGrain`, `clampToCeiling`) are total: they never
|
|
40
55
|
* throw on stored data. An unknown code, a null list or an unsupported
|
|
41
56
|
* `scopeVersion` (absent, 2, or anything but 3 / 4) includes nothing
|
|
42
|
-
* (fail closed).
|
|
57
|
+
* (fail closed). `readSelection`'s `subject` is the caller's, not stored
|
|
58
|
+
* data: a missing or unknown one throws (no silent default).
|
|
43
59
|
* - PICKER WRITES (`selectAll`, `deselectChild`, `expandSelectAll`), the
|
|
44
60
|
* build-time `rowForSubject`, and the constructor throw on programming
|
|
45
61
|
* errors (an unknown or non-selectable code, a malformed tree).
|
|
@@ -50,7 +66,7 @@ declare const INFORMATION_SCOPE_VERSION: 4;
|
|
|
50
66
|
* The `scopeVersion` stamps a stored list may carry and still be read: 3
|
|
51
67
|
* (through the v3 → v4 table) and 4. A 2 list, and an UNSTAMPED list (which
|
|
52
68
|
* is v2-era), must go through canon's conjunctive v2 → v3 table first (SOT
|
|
53
|
-
* v2.
|
|
69
|
+
* v2.1.0 `migrations.readAt` / `migrations.unstamped`: the `retired before
|
|
54
70
|
* v4` lines name "the flattened v3 reading, not an unconditional one"); this
|
|
55
71
|
* package ships no v2 → v3 table, so those lists are unsupported and include
|
|
56
72
|
* nothing (fail closed). None was ever persisted (`migrations.unstamped`).
|
|
@@ -110,17 +126,90 @@ interface ScopeMigration {
|
|
|
110
126
|
to: readonly string[];
|
|
111
127
|
rule: ScopeMigrationRule;
|
|
112
128
|
note?: string;
|
|
113
|
-
/** The line reads WIDER than v3 did (SOT `widens: true
|
|
129
|
+
/** The line reads WIDER than v3 did (SOT `widens: true`). A policy takes it; see `releaseReading`. */
|
|
114
130
|
widens?: boolean;
|
|
131
|
+
/**
|
|
132
|
+
* On every `widens` line (SOT; ruling 2026-10-09, canon SIGNED-GRAIN).
|
|
133
|
+
* `retain` — canon's nine merge folds (`signed_release_grain: keep`): a
|
|
134
|
+
* release or share at scopeVersion 3 keeps the code at its v3 grain instead
|
|
135
|
+
* of reading `to`; requires exactly one `to` and `v3Fields` / `v3Domains`.
|
|
136
|
+
* `successor` — a widening identity line canon leaves unmarked
|
|
137
|
+
* (`immigration_status`): every subject reads `to` (`releaseReadingNote`).
|
|
138
|
+
* Absent: `to` is every subject's reading.
|
|
139
|
+
*/
|
|
140
|
+
releaseReading?: "retain" | "successor";
|
|
141
|
+
/** Why a widening line is read as its successor by a release too. */
|
|
142
|
+
releaseReadingNote?: string;
|
|
143
|
+
/** `successor` (SOT, on every `widens` line): a policy or preset reads `to`. */
|
|
144
|
+
policyReading?: "successor";
|
|
145
|
+
/** A `retired before v4` line (ruling 2): a stated reading only a v2-era list can need. */
|
|
146
|
+
informational?: boolean;
|
|
147
|
+
/**
|
|
148
|
+
* On a `retain` line: the fields whose v3 home was the `from` unit (canon
|
|
149
|
+
* field placements `home_unit_today`) — what a retained release delivers,
|
|
150
|
+
* read-only. Field ids (`capture.hiv_status`), not scope codes. Empty = the
|
|
151
|
+
* unit homed no field, so a release retaining it delivers nothing.
|
|
152
|
+
*/
|
|
153
|
+
v3Fields?: readonly string[];
|
|
154
|
+
/**
|
|
155
|
+
* On a `retain` line: the distinct `assertion_domain` of `v3Fields`. CATEGORY
|
|
156
|
+
* grain in v3 (`access_accommodations`, `immigration_legal_status` each span
|
|
157
|
+
* every unit of their category): the field family, NOT the unit's membership.
|
|
158
|
+
* Deliver by `v3Fields`.
|
|
159
|
+
*/
|
|
160
|
+
v3Domains?: readonly string[];
|
|
161
|
+
/** On a `retain` line: why the membership is what it is (an empty unit; a derivation under veto). */
|
|
162
|
+
v3FieldsNote?: string;
|
|
115
163
|
}
|
|
116
164
|
/** How one stored code was read. `unknown` = no row, no table line: it includes nothing. */
|
|
117
165
|
type ScopeReadingRule = ScopeMigrationRule | "unknown";
|
|
118
166
|
interface ScopeCodeReading {
|
|
119
167
|
readonly from: string;
|
|
120
168
|
readonly rule: ScopeReadingRule;
|
|
169
|
+
/** The v4 codes it reads as; empty for a retained code (see `ScopeReading.retained`). */
|
|
121
170
|
readonly reads: readonly string[];
|
|
122
|
-
/**
|
|
171
|
+
/** It read through a line flagged as wider than v3 (never true for a retained code). */
|
|
123
172
|
readonly widens: boolean;
|
|
173
|
+
/** A release or share kept it at its v3 grain (`releaseReading: "retain"`). */
|
|
174
|
+
readonly retained: boolean;
|
|
175
|
+
}
|
|
176
|
+
/**
|
|
177
|
+
* Whose stored list is being read (handoff § 3; ruling 2026-10-09):
|
|
178
|
+
* - `release` — a signed ROI / release;
|
|
179
|
+
* - `share` — a share, which freezes the list it was sent with AND the
|
|
180
|
+
* `scopeVersion` of the release it was composed under (handoff § 3: "A
|
|
181
|
+
* share freezes the list it was sent with ... and its version"), so it
|
|
182
|
+
* reads like a release: a share frozen under a v3 release is a stamp-3
|
|
183
|
+
* list and retains;
|
|
184
|
+
* - `policy` — everything agency-authored: a policy, a PRESET or a PARTNER
|
|
185
|
+
* RULE (canon SIGNED-GRAIN: "policies / presets / partner rules take the
|
|
186
|
+
* successor whole"), migrated with a dated version row.
|
|
187
|
+
*/
|
|
188
|
+
type ScopeReadingSubject = "release" | "share" | "policy";
|
|
189
|
+
interface ScopeReadOptions {
|
|
190
|
+
subject: ScopeReadingSubject;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* A stored code a release or share keeps at the grain it was signed at
|
|
194
|
+
* (ruling 2026-10-09): not mapped to `successor`, not in `informationScope`.
|
|
195
|
+
* The builder delivers exactly `v3Fields`, read-only — never offered, never
|
|
196
|
+
* widened, never narrowed — until the survivor re-signs on v4.
|
|
197
|
+
*
|
|
198
|
+
* Only a STAMP-3 list retains. A v4-stamped release or share can only hold
|
|
199
|
+
* live v4 codes (the picker never offers a tombstone); if one nonetheless
|
|
200
|
+
* names a code on a `retain` line, that code is recognised as retired and
|
|
201
|
+
* includes NOTHING (fail closed) — never its successor, and not retained.
|
|
202
|
+
*/
|
|
203
|
+
interface ScopeRetainedReading {
|
|
204
|
+
readonly code: string;
|
|
205
|
+
/** The fields the code delivered in v3 (field ids). Empty: it delivers nothing (`note`). */
|
|
206
|
+
readonly v3Fields: readonly string[];
|
|
207
|
+
/** Their assertion domains — CATEGORY grain in v3, the field family; deliver by `v3Fields`. */
|
|
208
|
+
readonly v3Domains: readonly string[];
|
|
209
|
+
/** What a policy reads it as, and what a v4 re-signature would name. */
|
|
210
|
+
readonly successor: string;
|
|
211
|
+
/** Present when the membership needs explaining (an empty unit; a derivation under veto). */
|
|
212
|
+
readonly note?: string;
|
|
124
213
|
}
|
|
125
214
|
/**
|
|
126
215
|
* The current (v4) reading of a stored list. `stored` and `storedVersion` are
|
|
@@ -148,6 +237,20 @@ interface ScopeReading {
|
|
|
148
237
|
readonly unknown: readonly string[];
|
|
149
238
|
/** Stored codes whose reading is wider than v3's (`widens`): surface, never hide. */
|
|
150
239
|
readonly widened: readonly string[];
|
|
240
|
+
/** `readSelection`'s subject; `null` on a restriction reading. */
|
|
241
|
+
readonly subject: ScopeReadingSubject | null;
|
|
242
|
+
/** Release / share codes kept at v3 grain, in stored order (always empty for a policy). */
|
|
243
|
+
readonly retained: readonly ScopeRetainedReading[];
|
|
244
|
+
/**
|
|
245
|
+
* A policy read across versions (stamp 3) — `readSelection` with subject
|
|
246
|
+
* `policy`, and every `readRestriction` (a restriction is a policy's):
|
|
247
|
+
* handoff § 3 — "a policy is migrated with a new version row on the record,
|
|
248
|
+
* dated" — so the app writes that dated row before acting on
|
|
249
|
+
* `informationScope`. `false` otherwise.
|
|
250
|
+
*/
|
|
251
|
+
readonly versionRowRequired: boolean;
|
|
252
|
+
/** Says why, when `versionRowRequired`; otherwise `null`. */
|
|
253
|
+
readonly note: string | null;
|
|
151
254
|
}
|
|
152
255
|
type ScopeShareVerdict = {
|
|
153
256
|
readonly included: true;
|
|
@@ -195,9 +298,16 @@ interface InformationScopeResolver<R extends ScopeRow = ScopeRow> {
|
|
|
195
298
|
selectAll(selection: readonly string[], code: string): string[];
|
|
196
299
|
/** Rules 3 + 6: de-select one child; every selected ancestor is replaced by its other children. */
|
|
197
300
|
deselectChild(selection: readonly string[], childCode: string): string[];
|
|
198
|
-
/**
|
|
199
|
-
|
|
200
|
-
|
|
301
|
+
/**
|
|
302
|
+
* § 3: the current v4 reading of a stored selection, for its `subject`
|
|
303
|
+
* (required; throws when missing or unknown). A release or share keeps a
|
|
304
|
+
* `retain` code at its v3 grain (`retained`); a policy reads the successor.
|
|
305
|
+
*/
|
|
306
|
+
readSelection(list: StoredScopeList, scopeVersion: number | null | undefined, options: ScopeReadOptions): ScopeReading;
|
|
307
|
+
/**
|
|
308
|
+
* § 3 `subtract`: the current v4 reading of a stored RESTRICTION. A
|
|
309
|
+
* restriction is a policy's, so a stamp-3 one sets `versionRowRequired`.
|
|
310
|
+
*/
|
|
201
311
|
readRestriction(list: StoredScopeList, scopeVersion: number | null | undefined): ScopeReading;
|
|
202
312
|
/** Rule 1: the row a record is included under, given its field's home row and its subject. */
|
|
203
313
|
rowForSubject(homeRow: string, kind: ScopeSubjectKind): string;
|
|
@@ -224,21 +334,24 @@ declare function kindForPerson(person: {
|
|
|
224
334
|
causedHarm: boolean;
|
|
225
335
|
efmAsserted: boolean;
|
|
226
336
|
}): ScopePersonKind;
|
|
337
|
+
/** The `note` on a policy reading across versions (handoff § 3). */
|
|
338
|
+
declare const INFORMATION_SCOPE_POLICY_VERSION_ROW_NOTE: string;
|
|
227
339
|
/**
|
|
228
340
|
* Bind the resolver to one tree (and its migration table). Throws on a
|
|
229
341
|
* malformed tree: a duplicate code, a parent that is not a row, a cycle, no
|
|
230
342
|
* `system_info` row, a live row whose `specialDataType` is missing or not in
|
|
231
343
|
* § 8 (rule 1 routes on it — absence fails closed by refusing to bind), a
|
|
232
344
|
* per-kind row without a `kindRow` that names a row, an unknown migration
|
|
233
|
-
* rule, a migration successor that is not a live row,
|
|
234
|
-
* readings for the same code and rule
|
|
345
|
+
* rule, a migration successor that is not a live row, two different
|
|
346
|
+
* readings for the same code and rule, or a `releaseReading: "retain"` line
|
|
347
|
+
* without exactly one successor and its `v3Fields` / `v3Domains`.
|
|
235
348
|
*/
|
|
236
349
|
declare function createInformationScopeResolver<R extends ScopeRow>(input: CreateInformationScopeResolverInput<R>): InformationScopeResolver<R>;
|
|
237
350
|
|
|
238
351
|
/**
|
|
239
352
|
* @htilabs/platform-common-models — CVC-236 SOT → information-scope resolver binding
|
|
240
353
|
*
|
|
241
|
-
* Maps the `core_information_scope` SOT envelope (`coreInformationScope.v2.
|
|
354
|
+
* Maps the `core_information_scope` SOT envelope (`coreInformationScope.v2.1.0.json`,
|
|
242
355
|
* exported as `coreInformationScopeSot` from `/cvcs`) into the resolver's
|
|
243
356
|
* input shapes. Pure and dependency-free: the caller passes the envelope.
|
|
244
357
|
*
|
|
@@ -255,6 +368,13 @@ declare function createInformationScopeResolver<R extends ScopeRow>(input: Creat
|
|
|
255
368
|
* scope row. A live entry missing a field the resolver needs throws: binding
|
|
256
369
|
* fails closed rather than guess.
|
|
257
370
|
*
|
|
371
|
+
* Migrations: `migrations.table`, with each line's release-grain fields
|
|
372
|
+
* (`releaseReading` / `policyReading` / `informational`, Crysta's ruling of
|
|
373
|
+
* 2026-10-09). A `retain` line carries the v3 field membership of its `from`
|
|
374
|
+
* code, read from that code's ENTRY (`v3Fields` / `v3Domains` /
|
|
375
|
+
* `v3FieldsNote`, on the retired tombstone), so the SOT states it once. A
|
|
376
|
+
* `retain` line whose entry has no `v3Fields` throws: binding fails closed.
|
|
377
|
+
*
|
|
258
378
|
* Usage:
|
|
259
379
|
* ```ts
|
|
260
380
|
* import { coreInformationScopeSot } from "@htilabs/platform-common-models/cvcs";
|
|
@@ -291,6 +411,11 @@ interface CoreInformationScopeSotEntry {
|
|
|
291
411
|
replacesV3?: readonly string[];
|
|
292
412
|
/** On a tombstone: its RESTRICTION reading; the table's `subtract` line is what binds. */
|
|
293
413
|
restrictionSuccessors?: readonly string[];
|
|
414
|
+
/** On a `releaseReading: "retain"` line's `from` entry: its v3 fields (field ids). */
|
|
415
|
+
v3Fields?: readonly string[];
|
|
416
|
+
/** Their assertion domains — v3 CATEGORY grain (the field family), not the unit's membership. */
|
|
417
|
+
v3Domains?: readonly string[];
|
|
418
|
+
v3FieldsNote?: string;
|
|
294
419
|
}
|
|
295
420
|
interface CoreInformationScopeSotMigrationLine {
|
|
296
421
|
from: string;
|
|
@@ -298,6 +423,10 @@ interface CoreInformationScopeSotMigrationLine {
|
|
|
298
423
|
rule: string;
|
|
299
424
|
note?: string;
|
|
300
425
|
widens?: boolean;
|
|
426
|
+
releaseReading?: string;
|
|
427
|
+
releaseReadingNote?: string;
|
|
428
|
+
policyReading?: string;
|
|
429
|
+
informational?: boolean;
|
|
301
430
|
}
|
|
302
431
|
interface CoreInformationScopeSot {
|
|
303
432
|
entries: readonly CoreInformationScopeSotEntry[];
|
|
@@ -310,4 +439,4 @@ declare function scopeRowsFromSot(sot: CoreInformationScopeSot): ScopeRow[];
|
|
|
310
439
|
/** The v3 → v4 from-to table of a CVC-236 SOT (`migrations.table`), in selection codes. */
|
|
311
440
|
declare function scopeMigrationsFromSot(sot: CoreInformationScopeSot): ScopeMigration[];
|
|
312
441
|
|
|
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 };
|
|
442
|
+
export { type CoreInformationScopeSot, type CoreInformationScopeSotEntry, type CoreInformationScopeSotMigrationLine, type CreateInformationScopeResolverInput, INFORMATION_SCOPE_POLICY_VERSION_ROW_NOTE, 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 ScopeReadOptions, type ScopeReading, type ScopeReadingRule, type ScopeReadingSubject, type ScopeRetainedReading, 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 };
|
|
@@ -8,8 +8,10 @@
|
|
|
8
8
|
*
|
|
9
9
|
* Spec (canon, read-only): htilabstech/prototype
|
|
10
10
|
* docs/share-roi/INFOSCOPE_V4_DEV_HANDOFF_2026-10-09.md
|
|
11
|
-
* @
|
|
12
|
-
*
|
|
11
|
+
* @ 7ca7e586ae487c608da657d426598a65d5b06111 (merge of the SIGNED-GRAIN
|
|
12
|
+
* content commit e86dd89cdba5cbb39ccfc7fb35aff8cbf0774790, which amends
|
|
13
|
+
* § 3 only and re-labels the migrations CSV; § 2, § 7, § 8 and the rows CSV
|
|
14
|
+
* are unchanged from 6dab8a95 / 00179edc)
|
|
13
15
|
* - § 2 rules 1–7 ("the resolver contract — build exactly this, nothing
|
|
14
16
|
* cleverer") — every behaviour below cites its rule;
|
|
15
17
|
* - § 3 the migration rules (identity · row · category · subtract ·
|
|
@@ -19,6 +21,19 @@
|
|
|
19
21
|
* - § 7 row 6 a branch-grain pick is expanded to the ceiling's grain
|
|
20
22
|
* before clamping; a sender can never widen;
|
|
21
23
|
* - § 8 the enums.
|
|
24
|
+
* Release grain (Crysta, 2026-10-09; SOT v2.1.0 `migrations.ruling`, quoted
|
|
25
|
+
* verbatim there): "a SIGNED RELEASE keeps the grain it was signed at ...
|
|
26
|
+
* Policies and presets (agency-authored, not consent) take the merged
|
|
27
|
+
* successor with a dated version row." Canon carries it since SIGNED-GRAIN
|
|
28
|
+
* (prototype e86dd89c: `signed_release_grain: keep` on the nine `rows` merge
|
|
29
|
+
* folds; handoff § 3 amended). So `readSelection` takes WHOSE list it is
|
|
30
|
+
* (`subject`): a release or a share (frozen at send, § 3) naming a code on a
|
|
31
|
+
* `releaseReading: "retain"` line at scopeVersion 3 is NOT mapped — the code
|
|
32
|
+
* comes back under `retained` with its v3 field membership, for the builder
|
|
33
|
+
* to deliver read-only; a policy takes the successor (`widened`) and the
|
|
34
|
+
* reading says a dated version row is due. The widening identity line canon
|
|
35
|
+
* leaves unmarked (`immigration_status`, `releaseReading: "successor"`) reads
|
|
36
|
+
* as itself for every subject.
|
|
22
37
|
* Reference implementation of rule-1 kind-row resolution:
|
|
23
38
|
* tools/infoscope/phase4_stress_test.py `resolve_home` (same SHA).
|
|
24
39
|
*
|
|
@@ -39,7 +54,8 @@
|
|
|
39
54
|
* `expandBranchPickToGrain`, `clampToCeiling`) are total: they never
|
|
40
55
|
* throw on stored data. An unknown code, a null list or an unsupported
|
|
41
56
|
* `scopeVersion` (absent, 2, or anything but 3 / 4) includes nothing
|
|
42
|
-
* (fail closed).
|
|
57
|
+
* (fail closed). `readSelection`'s `subject` is the caller's, not stored
|
|
58
|
+
* data: a missing or unknown one throws (no silent default).
|
|
43
59
|
* - PICKER WRITES (`selectAll`, `deselectChild`, `expandSelectAll`), the
|
|
44
60
|
* build-time `rowForSubject`, and the constructor throw on programming
|
|
45
61
|
* errors (an unknown or non-selectable code, a malformed tree).
|
|
@@ -50,7 +66,7 @@ declare const INFORMATION_SCOPE_VERSION: 4;
|
|
|
50
66
|
* The `scopeVersion` stamps a stored list may carry and still be read: 3
|
|
51
67
|
* (through the v3 → v4 table) and 4. A 2 list, and an UNSTAMPED list (which
|
|
52
68
|
* is v2-era), must go through canon's conjunctive v2 → v3 table first (SOT
|
|
53
|
-
* v2.
|
|
69
|
+
* v2.1.0 `migrations.readAt` / `migrations.unstamped`: the `retired before
|
|
54
70
|
* v4` lines name "the flattened v3 reading, not an unconditional one"); this
|
|
55
71
|
* package ships no v2 → v3 table, so those lists are unsupported and include
|
|
56
72
|
* nothing (fail closed). None was ever persisted (`migrations.unstamped`).
|
|
@@ -110,17 +126,90 @@ interface ScopeMigration {
|
|
|
110
126
|
to: readonly string[];
|
|
111
127
|
rule: ScopeMigrationRule;
|
|
112
128
|
note?: string;
|
|
113
|
-
/** The line reads WIDER than v3 did (SOT `widens: true
|
|
129
|
+
/** The line reads WIDER than v3 did (SOT `widens: true`). A policy takes it; see `releaseReading`. */
|
|
114
130
|
widens?: boolean;
|
|
131
|
+
/**
|
|
132
|
+
* On every `widens` line (SOT; ruling 2026-10-09, canon SIGNED-GRAIN).
|
|
133
|
+
* `retain` — canon's nine merge folds (`signed_release_grain: keep`): a
|
|
134
|
+
* release or share at scopeVersion 3 keeps the code at its v3 grain instead
|
|
135
|
+
* of reading `to`; requires exactly one `to` and `v3Fields` / `v3Domains`.
|
|
136
|
+
* `successor` — a widening identity line canon leaves unmarked
|
|
137
|
+
* (`immigration_status`): every subject reads `to` (`releaseReadingNote`).
|
|
138
|
+
* Absent: `to` is every subject's reading.
|
|
139
|
+
*/
|
|
140
|
+
releaseReading?: "retain" | "successor";
|
|
141
|
+
/** Why a widening line is read as its successor by a release too. */
|
|
142
|
+
releaseReadingNote?: string;
|
|
143
|
+
/** `successor` (SOT, on every `widens` line): a policy or preset reads `to`. */
|
|
144
|
+
policyReading?: "successor";
|
|
145
|
+
/** A `retired before v4` line (ruling 2): a stated reading only a v2-era list can need. */
|
|
146
|
+
informational?: boolean;
|
|
147
|
+
/**
|
|
148
|
+
* On a `retain` line: the fields whose v3 home was the `from` unit (canon
|
|
149
|
+
* field placements `home_unit_today`) — what a retained release delivers,
|
|
150
|
+
* read-only. Field ids (`capture.hiv_status`), not scope codes. Empty = the
|
|
151
|
+
* unit homed no field, so a release retaining it delivers nothing.
|
|
152
|
+
*/
|
|
153
|
+
v3Fields?: readonly string[];
|
|
154
|
+
/**
|
|
155
|
+
* On a `retain` line: the distinct `assertion_domain` of `v3Fields`. CATEGORY
|
|
156
|
+
* grain in v3 (`access_accommodations`, `immigration_legal_status` each span
|
|
157
|
+
* every unit of their category): the field family, NOT the unit's membership.
|
|
158
|
+
* Deliver by `v3Fields`.
|
|
159
|
+
*/
|
|
160
|
+
v3Domains?: readonly string[];
|
|
161
|
+
/** On a `retain` line: why the membership is what it is (an empty unit; a derivation under veto). */
|
|
162
|
+
v3FieldsNote?: string;
|
|
115
163
|
}
|
|
116
164
|
/** How one stored code was read. `unknown` = no row, no table line: it includes nothing. */
|
|
117
165
|
type ScopeReadingRule = ScopeMigrationRule | "unknown";
|
|
118
166
|
interface ScopeCodeReading {
|
|
119
167
|
readonly from: string;
|
|
120
168
|
readonly rule: ScopeReadingRule;
|
|
169
|
+
/** The v4 codes it reads as; empty for a retained code (see `ScopeReading.retained`). */
|
|
121
170
|
readonly reads: readonly string[];
|
|
122
|
-
/**
|
|
171
|
+
/** It read through a line flagged as wider than v3 (never true for a retained code). */
|
|
123
172
|
readonly widens: boolean;
|
|
173
|
+
/** A release or share kept it at its v3 grain (`releaseReading: "retain"`). */
|
|
174
|
+
readonly retained: boolean;
|
|
175
|
+
}
|
|
176
|
+
/**
|
|
177
|
+
* Whose stored list is being read (handoff § 3; ruling 2026-10-09):
|
|
178
|
+
* - `release` — a signed ROI / release;
|
|
179
|
+
* - `share` — a share, which freezes the list it was sent with AND the
|
|
180
|
+
* `scopeVersion` of the release it was composed under (handoff § 3: "A
|
|
181
|
+
* share freezes the list it was sent with ... and its version"), so it
|
|
182
|
+
* reads like a release: a share frozen under a v3 release is a stamp-3
|
|
183
|
+
* list and retains;
|
|
184
|
+
* - `policy` — everything agency-authored: a policy, a PRESET or a PARTNER
|
|
185
|
+
* RULE (canon SIGNED-GRAIN: "policies / presets / partner rules take the
|
|
186
|
+
* successor whole"), migrated with a dated version row.
|
|
187
|
+
*/
|
|
188
|
+
type ScopeReadingSubject = "release" | "share" | "policy";
|
|
189
|
+
interface ScopeReadOptions {
|
|
190
|
+
subject: ScopeReadingSubject;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* A stored code a release or share keeps at the grain it was signed at
|
|
194
|
+
* (ruling 2026-10-09): not mapped to `successor`, not in `informationScope`.
|
|
195
|
+
* The builder delivers exactly `v3Fields`, read-only — never offered, never
|
|
196
|
+
* widened, never narrowed — until the survivor re-signs on v4.
|
|
197
|
+
*
|
|
198
|
+
* Only a STAMP-3 list retains. A v4-stamped release or share can only hold
|
|
199
|
+
* live v4 codes (the picker never offers a tombstone); if one nonetheless
|
|
200
|
+
* names a code on a `retain` line, that code is recognised as retired and
|
|
201
|
+
* includes NOTHING (fail closed) — never its successor, and not retained.
|
|
202
|
+
*/
|
|
203
|
+
interface ScopeRetainedReading {
|
|
204
|
+
readonly code: string;
|
|
205
|
+
/** The fields the code delivered in v3 (field ids). Empty: it delivers nothing (`note`). */
|
|
206
|
+
readonly v3Fields: readonly string[];
|
|
207
|
+
/** Their assertion domains — CATEGORY grain in v3, the field family; deliver by `v3Fields`. */
|
|
208
|
+
readonly v3Domains: readonly string[];
|
|
209
|
+
/** What a policy reads it as, and what a v4 re-signature would name. */
|
|
210
|
+
readonly successor: string;
|
|
211
|
+
/** Present when the membership needs explaining (an empty unit; a derivation under veto). */
|
|
212
|
+
readonly note?: string;
|
|
124
213
|
}
|
|
125
214
|
/**
|
|
126
215
|
* The current (v4) reading of a stored list. `stored` and `storedVersion` are
|
|
@@ -148,6 +237,20 @@ interface ScopeReading {
|
|
|
148
237
|
readonly unknown: readonly string[];
|
|
149
238
|
/** Stored codes whose reading is wider than v3's (`widens`): surface, never hide. */
|
|
150
239
|
readonly widened: readonly string[];
|
|
240
|
+
/** `readSelection`'s subject; `null` on a restriction reading. */
|
|
241
|
+
readonly subject: ScopeReadingSubject | null;
|
|
242
|
+
/** Release / share codes kept at v3 grain, in stored order (always empty for a policy). */
|
|
243
|
+
readonly retained: readonly ScopeRetainedReading[];
|
|
244
|
+
/**
|
|
245
|
+
* A policy read across versions (stamp 3) — `readSelection` with subject
|
|
246
|
+
* `policy`, and every `readRestriction` (a restriction is a policy's):
|
|
247
|
+
* handoff § 3 — "a policy is migrated with a new version row on the record,
|
|
248
|
+
* dated" — so the app writes that dated row before acting on
|
|
249
|
+
* `informationScope`. `false` otherwise.
|
|
250
|
+
*/
|
|
251
|
+
readonly versionRowRequired: boolean;
|
|
252
|
+
/** Says why, when `versionRowRequired`; otherwise `null`. */
|
|
253
|
+
readonly note: string | null;
|
|
151
254
|
}
|
|
152
255
|
type ScopeShareVerdict = {
|
|
153
256
|
readonly included: true;
|
|
@@ -195,9 +298,16 @@ interface InformationScopeResolver<R extends ScopeRow = ScopeRow> {
|
|
|
195
298
|
selectAll(selection: readonly string[], code: string): string[];
|
|
196
299
|
/** Rules 3 + 6: de-select one child; every selected ancestor is replaced by its other children. */
|
|
197
300
|
deselectChild(selection: readonly string[], childCode: string): string[];
|
|
198
|
-
/**
|
|
199
|
-
|
|
200
|
-
|
|
301
|
+
/**
|
|
302
|
+
* § 3: the current v4 reading of a stored selection, for its `subject`
|
|
303
|
+
* (required; throws when missing or unknown). A release or share keeps a
|
|
304
|
+
* `retain` code at its v3 grain (`retained`); a policy reads the successor.
|
|
305
|
+
*/
|
|
306
|
+
readSelection(list: StoredScopeList, scopeVersion: number | null | undefined, options: ScopeReadOptions): ScopeReading;
|
|
307
|
+
/**
|
|
308
|
+
* § 3 `subtract`: the current v4 reading of a stored RESTRICTION. A
|
|
309
|
+
* restriction is a policy's, so a stamp-3 one sets `versionRowRequired`.
|
|
310
|
+
*/
|
|
201
311
|
readRestriction(list: StoredScopeList, scopeVersion: number | null | undefined): ScopeReading;
|
|
202
312
|
/** Rule 1: the row a record is included under, given its field's home row and its subject. */
|
|
203
313
|
rowForSubject(homeRow: string, kind: ScopeSubjectKind): string;
|
|
@@ -224,21 +334,24 @@ declare function kindForPerson(person: {
|
|
|
224
334
|
causedHarm: boolean;
|
|
225
335
|
efmAsserted: boolean;
|
|
226
336
|
}): ScopePersonKind;
|
|
337
|
+
/** The `note` on a policy reading across versions (handoff § 3). */
|
|
338
|
+
declare const INFORMATION_SCOPE_POLICY_VERSION_ROW_NOTE: string;
|
|
227
339
|
/**
|
|
228
340
|
* Bind the resolver to one tree (and its migration table). Throws on a
|
|
229
341
|
* malformed tree: a duplicate code, a parent that is not a row, a cycle, no
|
|
230
342
|
* `system_info` row, a live row whose `specialDataType` is missing or not in
|
|
231
343
|
* § 8 (rule 1 routes on it — absence fails closed by refusing to bind), a
|
|
232
344
|
* per-kind row without a `kindRow` that names a row, an unknown migration
|
|
233
|
-
* rule, a migration successor that is not a live row,
|
|
234
|
-
* readings for the same code and rule
|
|
345
|
+
* rule, a migration successor that is not a live row, two different
|
|
346
|
+
* readings for the same code and rule, or a `releaseReading: "retain"` line
|
|
347
|
+
* without exactly one successor and its `v3Fields` / `v3Domains`.
|
|
235
348
|
*/
|
|
236
349
|
declare function createInformationScopeResolver<R extends ScopeRow>(input: CreateInformationScopeResolverInput<R>): InformationScopeResolver<R>;
|
|
237
350
|
|
|
238
351
|
/**
|
|
239
352
|
* @htilabs/platform-common-models — CVC-236 SOT → information-scope resolver binding
|
|
240
353
|
*
|
|
241
|
-
* Maps the `core_information_scope` SOT envelope (`coreInformationScope.v2.
|
|
354
|
+
* Maps the `core_information_scope` SOT envelope (`coreInformationScope.v2.1.0.json`,
|
|
242
355
|
* exported as `coreInformationScopeSot` from `/cvcs`) into the resolver's
|
|
243
356
|
* input shapes. Pure and dependency-free: the caller passes the envelope.
|
|
244
357
|
*
|
|
@@ -255,6 +368,13 @@ declare function createInformationScopeResolver<R extends ScopeRow>(input: Creat
|
|
|
255
368
|
* scope row. A live entry missing a field the resolver needs throws: binding
|
|
256
369
|
* fails closed rather than guess.
|
|
257
370
|
*
|
|
371
|
+
* Migrations: `migrations.table`, with each line's release-grain fields
|
|
372
|
+
* (`releaseReading` / `policyReading` / `informational`, Crysta's ruling of
|
|
373
|
+
* 2026-10-09). A `retain` line carries the v3 field membership of its `from`
|
|
374
|
+
* code, read from that code's ENTRY (`v3Fields` / `v3Domains` /
|
|
375
|
+
* `v3FieldsNote`, on the retired tombstone), so the SOT states it once. A
|
|
376
|
+
* `retain` line whose entry has no `v3Fields` throws: binding fails closed.
|
|
377
|
+
*
|
|
258
378
|
* Usage:
|
|
259
379
|
* ```ts
|
|
260
380
|
* import { coreInformationScopeSot } from "@htilabs/platform-common-models/cvcs";
|
|
@@ -291,6 +411,11 @@ interface CoreInformationScopeSotEntry {
|
|
|
291
411
|
replacesV3?: readonly string[];
|
|
292
412
|
/** On a tombstone: its RESTRICTION reading; the table's `subtract` line is what binds. */
|
|
293
413
|
restrictionSuccessors?: readonly string[];
|
|
414
|
+
/** On a `releaseReading: "retain"` line's `from` entry: its v3 fields (field ids). */
|
|
415
|
+
v3Fields?: readonly string[];
|
|
416
|
+
/** Their assertion domains — v3 CATEGORY grain (the field family), not the unit's membership. */
|
|
417
|
+
v3Domains?: readonly string[];
|
|
418
|
+
v3FieldsNote?: string;
|
|
294
419
|
}
|
|
295
420
|
interface CoreInformationScopeSotMigrationLine {
|
|
296
421
|
from: string;
|
|
@@ -298,6 +423,10 @@ interface CoreInformationScopeSotMigrationLine {
|
|
|
298
423
|
rule: string;
|
|
299
424
|
note?: string;
|
|
300
425
|
widens?: boolean;
|
|
426
|
+
releaseReading?: string;
|
|
427
|
+
releaseReadingNote?: string;
|
|
428
|
+
policyReading?: string;
|
|
429
|
+
informational?: boolean;
|
|
301
430
|
}
|
|
302
431
|
interface CoreInformationScopeSot {
|
|
303
432
|
entries: readonly CoreInformationScopeSotEntry[];
|
|
@@ -310,4 +439,4 @@ declare function scopeRowsFromSot(sot: CoreInformationScopeSot): ScopeRow[];
|
|
|
310
439
|
/** The v3 → v4 from-to table of a CVC-236 SOT (`migrations.table`), in selection codes. */
|
|
311
440
|
declare function scopeMigrationsFromSot(sot: CoreInformationScopeSot): ScopeMigration[];
|
|
312
441
|
|
|
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 };
|
|
442
|
+
export { type CoreInformationScopeSot, type CoreInformationScopeSotEntry, type CoreInformationScopeSotMigrationLine, type CreateInformationScopeResolverInput, INFORMATION_SCOPE_POLICY_VERSION_ROW_NOTE, 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 ScopeReadOptions, type ScopeReading, type ScopeReadingRule, type ScopeReadingSubject, type ScopeRetainedReading, 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 };
|