@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.
Files changed (53) hide show
  1. package/dist/cvcs/index.cjs +222 -120
  2. package/dist/cvcs/index.cjs.map +1 -1
  3. package/dist/cvcs/index.d.cts +223 -117
  4. package/dist/cvcs/index.d.ts +223 -117
  5. package/dist/cvcs/index.js +222 -120
  6. package/dist/cvcs/index.js.map +1 -1
  7. package/dist/enums/index.cjs.map +1 -1
  8. package/dist/enums/index.d.cts +4 -4
  9. package/dist/enums/index.d.ts +4 -4
  10. package/dist/enums/index.js.map +1 -1
  11. package/dist/{index-I-DiX9eQ.d.ts → index-CDoqrfc1.d.ts} +1 -1
  12. package/dist/{index-CoVr1jIV.d.cts → index-Zu_mOJRn.d.cts} +1 -1
  13. package/dist/index.cjs +320 -137
  14. package/dist/index.cjs.map +1 -1
  15. package/dist/index.d.cts +3 -3
  16. package/dist/index.d.ts +3 -3
  17. package/dist/index.js +319 -137
  18. package/dist/index.js.map +1 -1
  19. package/dist/information-scope/index.cjs +98 -17
  20. package/dist/information-scope/index.cjs.map +1 -1
  21. package/dist/information-scope/index.d.cts +142 -13
  22. package/dist/information-scope/index.d.ts +142 -13
  23. package/dist/information-scope/index.js +97 -17
  24. package/dist/information-scope/index.js.map +1 -1
  25. package/dist/models/index.d.cts +2 -2
  26. package/dist/models/index.d.ts +2 -2
  27. package/dist/schemas/index.d.cts +25 -25
  28. package/dist/schemas/index.d.ts +25 -25
  29. package/dist/services/index.cjs +98 -17
  30. package/dist/services/index.cjs.map +1 -1
  31. package/dist/services/index.d.cts +1 -1
  32. package/dist/services/index.d.ts +1 -1
  33. package/dist/services/index.js +97 -17
  34. package/dist/services/index.js.map +1 -1
  35. package/package.json +1 -1
  36. package/src/__tests__/__snapshots__/cvc-sot.snap +2 -2
  37. package/src/__tests__/core-information-scope-invariant.test.ts +141 -15
  38. package/src/__tests__/cvc-sot-snapshot.test.ts +4 -3
  39. package/src/__tests__/cvc-structural.test.ts +2 -2
  40. package/src/__tests__/location-type-routing-invariant.test.ts +1 -1
  41. package/src/cvcs/{coreInformationScope.v2.0.0.json → coreInformationScope.v2.1.0.json} +190 -88
  42. package/src/cvcs/index.ts +2 -2
  43. package/src/cvcs/{roiScope.v1.3.0.json → roiScope.v1.4.0.json} +26 -26
  44. package/src/generated/cvc-enums.ts +4 -4
  45. package/src/services/__tests__/fixtures/infoscope-v4/information_scope_v3_placements.projection.csv +12 -0
  46. package/src/services/__tests__/fixtures/infoscope-v4/information_scope_v4.migrations.csv +27 -27
  47. package/src/services/__tests__/fixtures/infoscope-v4/information_scope_v4.rows.csv +1 -1
  48. package/src/services/__tests__/fixtures/infoscope-v4/loadInfoscopeV4Fixtures.ts +85 -14
  49. package/src/services/__tests__/informationScopeResolver.test.ts +336 -22
  50. package/src/services/informationScopeResolver.ts +226 -19
  51. package/src/services/informationScopeSot.ts +50 -8
  52. package/dist/{cvcEntry-BCj1OWqL.d.cts → cvcEntry-0BIB9sen.d.cts} +8 -8
  53. 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
- * @ 00179edcb3f0c00a8b55beeffd1618c8a5c98937 (signed; the handoff and its
12
- * CSVs are unchanged from 6dab8a95)
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).
@@ -54,7 +70,7 @@ export const INFORMATION_SCOPE_VERSION = 4 as const;
54
70
  * The `scopeVersion` stamps a stored list may carry and still be read: 3
55
71
  * (through the v3 → v4 table) and 4. A 2 list, and an UNSTAMPED list (which
56
72
  * is v2-era), must go through canon's conjunctive v2 → v3 table first (SOT
57
- * v2.0.0 `migrations.readAt` / `migrations.unstamped`: the `retired before
73
+ * v2.1.0 `migrations.readAt` / `migrations.unstamped`: the `retired before
58
74
  * v4` lines name "the flattened v3 reading, not an unconditional one"); this
59
75
  * package ships no v2 → v3 table, so those lists are unsupported and include
60
76
  * nothing (fail closed). None was ever persisted (`migrations.unstamped`).
@@ -138,8 +154,40 @@ export interface ScopeMigration {
138
154
  to: readonly string[];
139
155
  rule: ScopeMigrationRule;
140
156
  note?: string;
141
- /** The line reads WIDER than v3 did (SOT `widens: true`; consent widening is an open question). */
157
+ /** The line reads WIDER than v3 did (SOT `widens: true`). A policy takes it; see `releaseReading`. */
142
158
  widens?: boolean;
159
+ /**
160
+ * On every `widens` line (SOT; ruling 2026-10-09, canon SIGNED-GRAIN).
161
+ * `retain` — canon's nine merge folds (`signed_release_grain: keep`): a
162
+ * release or share at scopeVersion 3 keeps the code at its v3 grain instead
163
+ * of reading `to`; requires exactly one `to` and `v3Fields` / `v3Domains`.
164
+ * `successor` — a widening identity line canon leaves unmarked
165
+ * (`immigration_status`): every subject reads `to` (`releaseReadingNote`).
166
+ * Absent: `to` is every subject's reading.
167
+ */
168
+ releaseReading?: "retain" | "successor";
169
+ /** Why a widening line is read as its successor by a release too. */
170
+ releaseReadingNote?: string;
171
+ /** `successor` (SOT, on every `widens` line): a policy or preset reads `to`. */
172
+ policyReading?: "successor";
173
+ /** A `retired before v4` line (ruling 2): a stated reading only a v2-era list can need. */
174
+ informational?: boolean;
175
+ /**
176
+ * On a `retain` line: the fields whose v3 home was the `from` unit (canon
177
+ * field placements `home_unit_today`) — what a retained release delivers,
178
+ * read-only. Field ids (`capture.hiv_status`), not scope codes. Empty = the
179
+ * unit homed no field, so a release retaining it delivers nothing.
180
+ */
181
+ v3Fields?: readonly string[];
182
+ /**
183
+ * On a `retain` line: the distinct `assertion_domain` of `v3Fields`. CATEGORY
184
+ * grain in v3 (`access_accommodations`, `immigration_legal_status` each span
185
+ * every unit of their category): the field family, NOT the unit's membership.
186
+ * Deliver by `v3Fields`.
187
+ */
188
+ v3Domains?: readonly string[];
189
+ /** On a `retain` line: why the membership is what it is (an empty unit; a derivation under veto). */
190
+ v3FieldsNote?: string;
143
191
  }
144
192
 
145
193
  // ─── Output shapes ───────────────────────────────────────────────────────────
@@ -150,9 +198,53 @@ export type ScopeReadingRule = ScopeMigrationRule | "unknown";
150
198
  export interface ScopeCodeReading {
151
199
  readonly from: string;
152
200
  readonly rule: ScopeReadingRule;
201
+ /** The v4 codes it reads as; empty for a retained code (see `ScopeReading.retained`). */
153
202
  readonly reads: readonly string[];
154
- /** The table line it read through is flagged as reading wider than v3. */
203
+ /** It read through a line flagged as wider than v3 (never true for a retained code). */
155
204
  readonly widens: boolean;
205
+ /** A release or share kept it at its v3 grain (`releaseReading: "retain"`). */
206
+ readonly retained: boolean;
207
+ }
208
+
209
+ /**
210
+ * Whose stored list is being read (handoff § 3; ruling 2026-10-09):
211
+ * - `release` — a signed ROI / release;
212
+ * - `share` — a share, which freezes the list it was sent with AND the
213
+ * `scopeVersion` of the release it was composed under (handoff § 3: "A
214
+ * share freezes the list it was sent with ... and its version"), so it
215
+ * reads like a release: a share frozen under a v3 release is a stamp-3
216
+ * list and retains;
217
+ * - `policy` — everything agency-authored: a policy, a PRESET or a PARTNER
218
+ * RULE (canon SIGNED-GRAIN: "policies / presets / partner rules take the
219
+ * successor whole"), migrated with a dated version row.
220
+ */
221
+ export type ScopeReadingSubject = "release" | "share" | "policy";
222
+
223
+ export interface ScopeReadOptions {
224
+ subject: ScopeReadingSubject;
225
+ }
226
+
227
+ /**
228
+ * A stored code a release or share keeps at the grain it was signed at
229
+ * (ruling 2026-10-09): not mapped to `successor`, not in `informationScope`.
230
+ * The builder delivers exactly `v3Fields`, read-only — never offered, never
231
+ * widened, never narrowed — until the survivor re-signs on v4.
232
+ *
233
+ * Only a STAMP-3 list retains. A v4-stamped release or share can only hold
234
+ * live v4 codes (the picker never offers a tombstone); if one nonetheless
235
+ * names a code on a `retain` line, that code is recognised as retired and
236
+ * includes NOTHING (fail closed) — never its successor, and not retained.
237
+ */
238
+ export interface ScopeRetainedReading {
239
+ readonly code: string;
240
+ /** The fields the code delivered in v3 (field ids). Empty: it delivers nothing (`note`). */
241
+ readonly v3Fields: readonly string[];
242
+ /** Their assertion domains — CATEGORY grain in v3, the field family; deliver by `v3Fields`. */
243
+ readonly v3Domains: readonly string[];
244
+ /** What a policy reads it as, and what a v4 re-signature would name. */
245
+ readonly successor: string;
246
+ /** Present when the membership needs explaining (an empty unit; a derivation under veto). */
247
+ readonly note?: string;
156
248
  }
157
249
 
158
250
  /**
@@ -181,6 +273,20 @@ export interface ScopeReading {
181
273
  readonly unknown: readonly string[];
182
274
  /** Stored codes whose reading is wider than v3's (`widens`): surface, never hide. */
183
275
  readonly widened: readonly string[];
276
+ /** `readSelection`'s subject; `null` on a restriction reading. */
277
+ readonly subject: ScopeReadingSubject | null;
278
+ /** Release / share codes kept at v3 grain, in stored order (always empty for a policy). */
279
+ readonly retained: readonly ScopeRetainedReading[];
280
+ /**
281
+ * A policy read across versions (stamp 3) — `readSelection` with subject
282
+ * `policy`, and every `readRestriction` (a restriction is a policy's):
283
+ * handoff § 3 — "a policy is migrated with a new version row on the record,
284
+ * dated" — so the app writes that dated row before acting on
285
+ * `informationScope`. `false` otherwise.
286
+ */
287
+ readonly versionRowRequired: boolean;
288
+ /** Says why, when `versionRowRequired`; otherwise `null`. */
289
+ readonly note: string | null;
184
290
  }
185
291
 
186
292
  export type ScopeShareVerdict =
@@ -238,9 +344,20 @@ export interface InformationScopeResolver<R extends ScopeRow = ScopeRow> {
238
344
  /** Rules 3 + 6: de-select one child; every selected ancestor is replaced by its other children. */
239
345
  deselectChild(selection: readonly string[], childCode: string): string[];
240
346
 
241
- /** § 3: the current v4 reading of a stored selection. */
242
- readSelection(list: StoredScopeList, scopeVersion: number | null | undefined): ScopeReading;
243
- /** § 3 `subtract`: the current v4 reading of a stored RESTRICTION. */
347
+ /**
348
+ * § 3: the current v4 reading of a stored selection, for its `subject`
349
+ * (required; throws when missing or unknown). A release or share keeps a
350
+ * `retain` code at its v3 grain (`retained`); a policy reads the successor.
351
+ */
352
+ readSelection(
353
+ list: StoredScopeList,
354
+ scopeVersion: number | null | undefined,
355
+ options: ScopeReadOptions,
356
+ ): ScopeReading;
357
+ /**
358
+ * § 3 `subtract`: the current v4 reading of a stored RESTRICTION. A
359
+ * restriction is a policy's, so a stamp-3 one sets `versionRowRequired`.
360
+ */
244
361
  readRestriction(list: StoredScopeList, scopeVersion: number | null | undefined): ScopeReading;
245
362
 
246
363
  /** Rule 1: the row a record is included under, given its field's home row and its subject. */
@@ -319,6 +436,18 @@ const RESTRICTION_PRECEDENCE: readonly ScopeMigrationRule[] = [
319
436
  ...SELECTION_PRECEDENCE,
320
437
  ];
321
438
 
439
+ const READING_SUBJECTS: ReadonlySet<string> = new Set<ScopeReadingSubject>([
440
+ "release",
441
+ "share",
442
+ "policy",
443
+ ]);
444
+
445
+ /** The `note` on a policy reading across versions (handoff § 3). */
446
+ export const INFORMATION_SCOPE_POLICY_VERSION_ROW_NOTE =
447
+ "Handoff § 3: a policy is migrated with a new version row on the record, dated, so a Member " +
448
+ "Admin sees a change in history, not a silent rewrite. Write that row before acting on this " +
449
+ "reading; the stored list itself is never rewritten.";
450
+
322
451
  const asList = (list: StoredScopeList): readonly string[] => (Array.isArray(list) ? list : []);
323
452
 
324
453
  /**
@@ -327,8 +456,9 @@ const asList = (list: StoredScopeList): readonly string[] => (Array.isArray(list
327
456
  * `system_info` row, a live row whose `specialDataType` is missing or not in
328
457
  * § 8 (rule 1 routes on it — absence fails closed by refusing to bind), a
329
458
  * per-kind row without a `kindRow` that names a row, an unknown migration
330
- * rule, a migration successor that is not a live row, or two different
331
- * readings for the same code and rule.
459
+ * rule, a migration successor that is not a live row, two different
460
+ * readings for the same code and rule, or a `releaseReading: "retain"` line
461
+ * without exactly one successor and its `v3Fields` / `v3Domains`.
332
462
  */
333
463
  export function createInformationScopeResolver<R extends ScopeRow>(
334
464
  input: CreateInformationScopeResolverInput<R>,
@@ -433,16 +563,45 @@ export function createInformationScopeResolver<R extends ScopeRow>(
433
563
  );
434
564
  }
435
565
  }
566
+ if (
567
+ m.releaseReading !== undefined &&
568
+ m.releaseReading !== "retain" &&
569
+ m.releaseReading !== "successor"
570
+ ) {
571
+ throw new Error(`information scope: "${m.from}" has releaseReading "${String(m.releaseReading)}"`);
572
+ }
573
+ if (m.policyReading !== undefined && m.policyReading !== "successor") {
574
+ throw new Error(`information scope: "${m.from}" has policyReading "${String(m.policyReading)}"`);
575
+ }
576
+ if (
577
+ m.releaseReading === "retain" &&
578
+ (m.to.length !== 1 || !Array.isArray(m.v3Fields) || !Array.isArray(m.v3Domains))
579
+ ) {
580
+ throw new Error(
581
+ `information scope: retained line "${m.from}" needs one successor and its v3Fields / v3Domains`,
582
+ );
583
+ }
436
584
  const perCode = migrations.get(m.from) ?? new Map<ScopeMigrationRule, ScopeMigration>();
437
585
  const prior = perCode.get(m.rule);
438
586
  if (prior && prior.to.join(" ") !== m.to.join(" ")) {
439
587
  throw new Error(`information scope: two "${m.rule}" readings for "${m.from}"`);
440
588
  }
589
+ // The resolver reads only `to`, `widens` and a `retain` line's v3 membership;
590
+ // the other line fields stay on the caller's `ScopeMigration` / the SOT.
591
+ const retain = m.releaseReading === "retain" ? m : prior?.releaseReading === "retain" ? prior : null;
441
592
  perCode.set(m.rule, {
442
593
  from: m.from,
443
594
  rule: m.rule,
444
595
  to: Object.freeze([...m.to]),
445
596
  widens: m.widens === true || prior?.widens === true,
597
+ ...(retain === null
598
+ ? {}
599
+ : {
600
+ releaseReading: "retain" as const,
601
+ v3Fields: Object.freeze([...(retain.v3Fields ?? [])]),
602
+ v3Domains: Object.freeze([...(retain.v3Domains ?? [])]),
603
+ ...(retain.v3FieldsNote === undefined ? {} : { v3FieldsNote: retain.v3FieldsNote }),
604
+ }),
446
605
  });
447
606
  migrations.set(m.from, perCode);
448
607
  }
@@ -540,10 +699,11 @@ export function createInformationScopeResolver<R extends ScopeRow>(
540
699
  from: string,
541
700
  scopeVersion: number,
542
701
  precedence: readonly ScopeMigrationRule[],
702
+ keepsGrain: boolean,
543
703
  ): ScopeCodeReading => {
544
704
  // A v4 list names live codes as written.
545
705
  if (scopeVersion === INFORMATION_SCOPE_VERSION && isLive(from)) {
546
- return { from, rule: "identity", reads: [from], widens: false };
706
+ return { from, rule: "identity", reads: [from], widens: false, retained: false };
547
707
  }
548
708
  // Every other code reads through the table — including a retired code in a
549
709
  // v4 list (§ 3 (c): it "stays recognisable in stored data forever").
@@ -554,21 +714,49 @@ export function createInformationScopeResolver<R extends ScopeRow>(
554
714
  continue; // a v4 code that is not live has no identity reading
555
715
  }
556
716
  const line = lines.get(rule);
557
- if (line) return { from, rule, reads: [...line.to], widens: line.widens === true };
717
+ if (!line) continue;
718
+ // Ruling 2026-10-09: a release / share signed at v3 keeps the v3 grain.
719
+ if (keepsGrain && line.releaseReading === "retain") {
720
+ // A v4-stamped release / share cannot legitimately hold this tombstone
721
+ // (never offered): recognised as retired, includes nothing — never the
722
+ // successor (see `ScopeRetainedReading`).
723
+ return scopeVersion === 3
724
+ ? { from, rule, reads: [], widens: false, retained: true }
725
+ : { from, rule, reads: [], widens: false, retained: false };
726
+ }
727
+ return { from, rule, reads: [...line.to], widens: line.widens === true, retained: false };
558
728
  }
559
729
  }
560
- return { from, rule: "unknown", reads: [], widens: false };
730
+ return { from, rule: "unknown", reads: [], widens: false, retained: false };
731
+ };
732
+
733
+ const retainedOf = (c: ScopeCodeReading): ScopeRetainedReading => {
734
+ const line = migrations.get(c.from)?.get(c.rule as ScopeMigrationRule) as ScopeMigration;
735
+ return {
736
+ code: c.from,
737
+ v3Fields: [...(line.v3Fields ?? [])],
738
+ v3Domains: [...(line.v3Domains ?? [])],
739
+ successor: line.to[0],
740
+ ...(line.v3FieldsNote === undefined ? {} : { note: line.v3FieldsNote }),
741
+ };
561
742
  };
562
743
 
563
744
  const read = (
564
745
  list: StoredScopeList,
565
746
  scopeVersion: number | null | undefined,
566
747
  precedence: readonly ScopeMigrationRule[],
567
- isRestriction: boolean,
748
+ subject: ScopeReadingSubject | null,
568
749
  ): ScopeReading => {
750
+ const isRestriction = subject === null;
751
+ const keepsGrain = subject === "release" || subject === "share";
752
+ // A restriction is a policy's (handoff § 3 `subtract`: "a policy that forbids
753
+ // a code"), so it carries the same dated-version-row signal.
754
+ const isPolicyLike = subject === "policy" || isRestriction;
569
755
  const stored = [...asList(list)];
570
756
  const supported =
571
757
  typeof scopeVersion === "number" && INFORMATION_SCOPE_READABLE_VERSIONS.includes(scopeVersion);
758
+ const versionRowRequired =
759
+ isPolicyLike && supported && scopeVersion !== INFORMATION_SCOPE_VERSION;
572
760
  const codes: ScopeCodeReading[] = [];
573
761
  const seen = new Set<string>();
574
762
  for (const from of stored) {
@@ -576,8 +764,8 @@ export function createInformationScopeResolver<R extends ScopeRow>(
576
764
  seen.add(from);
577
765
  codes.push(
578
766
  supported
579
- ? readOne(from, scopeVersion as number, precedence)
580
- : { from, rule: "unknown", reads: [], widens: false },
767
+ ? readOne(from, scopeVersion as number, precedence, keepsGrain)
768
+ : { from, rule: "unknown", reads: [], widens: false, retained: false },
581
769
  );
582
770
  }
583
771
  return {
@@ -593,9 +781,28 @@ export function createInformationScopeResolver<R extends ScopeRow>(
593
781
  retired: codes.filter((c) => RETIRED_RULES.has(c.rule)).map((c) => c.from),
594
782
  unknown: codes.filter((c) => c.rule === "unknown").map((c) => c.from),
595
783
  widened: codes.filter((c) => c.widens).map((c) => c.from),
784
+ subject,
785
+ retained: codes.filter((c) => c.retained).map(retainedOf),
786
+ versionRowRequired,
787
+ note: versionRowRequired ? INFORMATION_SCOPE_POLICY_VERSION_ROW_NOTE : null,
596
788
  };
597
789
  };
598
790
 
791
+ const readSelection = (
792
+ list: StoredScopeList,
793
+ scopeVersion: number | null | undefined,
794
+ options: ScopeReadOptions,
795
+ ): ScopeReading => {
796
+ const subject = (options as Partial<ScopeReadOptions> | undefined)?.subject;
797
+ if (subject === undefined || !READING_SUBJECTS.has(subject)) {
798
+ throw new TypeError(
799
+ `information scope readSelection: options.subject must be "release", "share" or "policy" ` +
800
+ `(got ${JSON.stringify(subject)}) — there is no default`,
801
+ );
802
+ }
803
+ return read(list, scopeVersion, SELECTION_PRECEDENCE, subject);
804
+ };
805
+
599
806
  const rowForSubject = (homeRow: string, kind: ScopeSubjectKind): string => {
600
807
  const home = byCode.get(homeRow);
601
808
  if (!home) throw new RangeError(`information scope rowForSubject: unknown home "${homeRow}"`);
@@ -663,8 +870,8 @@ export function createInformationScopeResolver<R extends ScopeRow>(
663
870
  expandSelectAll,
664
871
  selectAll,
665
872
  deselectChild,
666
- readSelection: (list, scopeVersion) => read(list, scopeVersion, SELECTION_PRECEDENCE, false),
667
- readRestriction: (list, scopeVersion) => read(list, scopeVersion, RESTRICTION_PRECEDENCE, true),
873
+ readSelection,
874
+ readRestriction: (list, scopeVersion) => read(list, scopeVersion, RESTRICTION_PRECEDENCE, null),
668
875
  rowForSubject,
669
876
  expandBranchPickToGrain,
670
877
  clampToCeiling,
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * @htilabs/platform-common-models — CVC-236 SOT → information-scope resolver binding
3
3
  *
4
- * Maps the `core_information_scope` SOT envelope (`coreInformationScope.v2.0.0.json`,
4
+ * Maps the `core_information_scope` SOT envelope (`coreInformationScope.v2.1.0.json`,
5
5
  * exported as `coreInformationScopeSot` from `/cvcs`) into the resolver's
6
6
  * input shapes. Pure and dependency-free: the caller passes the envelope.
7
7
  *
@@ -18,6 +18,13 @@
18
18
  * scope row. A live entry missing a field the resolver needs throws: binding
19
19
  * fails closed rather than guess.
20
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
+ *
21
28
  * Usage:
22
29
  * ```ts
23
30
  * import { coreInformationScopeSot } from "@htilabs/platform-common-models/cvcs";
@@ -60,6 +67,11 @@ export interface CoreInformationScopeSotEntry {
60
67
  replacesV3?: readonly string[];
61
68
  /** On a tombstone: its RESTRICTION reading; the table's `subtract` line is what binds. */
62
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;
63
75
  }
64
76
 
65
77
  export interface CoreInformationScopeSotMigrationLine {
@@ -68,6 +80,10 @@ export interface CoreInformationScopeSotMigrationLine {
68
80
  rule: string;
69
81
  note?: string;
70
82
  widens?: boolean;
83
+ releaseReading?: string;
84
+ releaseReadingNote?: string;
85
+ policyReading?: string;
86
+ informational?: boolean;
71
87
  }
72
88
 
73
89
  export interface CoreInformationScopeSot {
@@ -151,11 +167,37 @@ export function scopeRowsFromSot(sot: CoreInformationScopeSot): ScopeRow[] {
151
167
  /** The v3 → v4 from-to table of a CVC-236 SOT (`migrations.table`), in selection codes. */
152
168
  export function scopeMigrationsFromSot(sot: CoreInformationScopeSot): ScopeMigration[] {
153
169
  const code = keyReader(sot);
154
- return (sot.migrations?.table ?? []).map((l) => ({
155
- from: code(l.from),
156
- to: l.to.map(code),
157
- rule: l.rule as ScopeMigrationRule,
158
- ...(l.note === undefined ? {} : { note: l.note }),
159
- ...(l.widens === undefined ? {} : { widens: l.widens }),
160
- }));
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
+ });
161
203
  }
@@ -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
  } & {