@htilabs/platform-common-models 0.22.0 → 0.23.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/authz/index.cjs +539 -0
- package/dist/authz/index.cjs.map +1 -0
- package/dist/authz/index.d.cts +210 -0
- package/dist/authz/index.d.ts +210 -0
- package/dist/authz/index.js +507 -0
- package/dist/authz/index.js.map +1 -0
- package/dist/constants/index.d.cts +2 -1
- package/dist/constants/index.d.ts +2 -1
- package/dist/cvcs/index.cjs +647 -353
- package/dist/cvcs/index.cjs.map +1 -1
- package/dist/cvcs/index.d.cts +658 -362
- package/dist/cvcs/index.d.ts +658 -362
- package/dist/cvcs/index.js +647 -353
- package/dist/cvcs/index.js.map +1 -1
- package/dist/enums/index.cjs +1 -9
- package/dist/enums/index.cjs.map +1 -1
- package/dist/enums/index.d.cts +7 -15
- package/dist/enums/index.d.ts +7 -15
- package/dist/enums/index.js +1 -9
- package/dist/enums/index.js.map +1 -1
- package/dist/{platform-auth-CvAYFVhK.d.cts → ic-DpKrdgQP.d.cts} +1 -78
- package/dist/{platform-auth-CvAYFVhK.d.ts → ic-DpKrdgQP.d.ts} +1 -78
- package/dist/index.cjs +899 -362
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +3 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.js +893 -362
- package/dist/index.js.map +1 -1
- package/dist/platform-auth-B49Ly57B.d.cts +78 -0
- package/dist/platform-auth-B49Ly57B.d.ts +78 -0
- package/dist/types/index.d.cts +2 -2
- package/dist/types/index.d.ts +2 -2
- package/package.json +6 -1
- package/src/__sot__/README.md +3 -1
- package/src/__sot__/adminRoles.pin.json +122 -0
- package/src/__sot__/adminRoles.published.json +77 -0
- package/src/__sot__/coreFunctionFields.ts +16 -0
- package/src/__sot__/coreFunctions.pin.json +114 -1
- package/src/__sot__/roleFields.ts +137 -0
- package/src/__sot__/userRoles.pin.json +174 -0
- package/src/__sot__/userRoles.published.json +103 -0
- package/src/__tests__/__snapshots__/cvc-sot.snap +5 -5
- package/src/__tests__/admin-roles-canon.test.ts +80 -0
- package/src/__tests__/authz-resolve.test.ts +712 -0
- package/src/__tests__/core-functions-canon.test.ts +62 -12
- package/src/__tests__/cvc-sot-snapshot.test.ts +12 -4
- package/src/__tests__/cvc-status-parser.test.ts +1 -1
- package/src/__tests__/cvc-structural.test.ts +3 -3
- package/src/__tests__/role-vocab-gate.ts +279 -0
- package/src/__tests__/user-roles-canon.test.ts +104 -0
- package/src/authz/index.ts +9 -0
- package/src/authz/resolveEffectiveFunctions.ts +454 -0
- package/src/cvcs/adminRoles.v2.0.0.json +197 -0
- package/src/cvcs/{coreFunctions.v1.2.0.json → coreFunctions.v1.3.0.json} +357 -200
- package/src/cvcs/index.ts +3 -3
- package/src/cvcs/userRoles.v2.0.0.json +296 -0
- package/src/generated/coreFunctionsEvaluable.ts +101 -0
- package/src/generated/cvc-enums.ts +7 -15
- package/src/index.ts +4 -0
- package/src/cvcs/adminRoles.v1.0.0.json +0 -153
- package/src/cvcs/userRoles.v1.0.0.json +0 -203
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* CORE FUNCTIONS (CVC-133) — GATE I: the SOT restates canon, whole
|
|
3
3
|
* =================================================================
|
|
4
4
|
*
|
|
5
|
-
* `src/cvcs/coreFunctions.v1.
|
|
5
|
+
* `src/cvcs/coreFunctions.v1.3.0.json` is GENERATED from the canonical CVC-133
|
|
6
6
|
* registry (`htilabstech/prototype` `data/cvcs/core_functions.yaml`) by
|
|
7
7
|
* `scripts/gen-core-functions.py`. This test is the hermetic enforcer: it
|
|
8
8
|
* asserts the shipped SOT conforms to `src/__sot__/coreFunctions.pin.json`
|
|
@@ -30,6 +30,10 @@ import { fileURLToPath } from "node:url";
|
|
|
30
30
|
import { describe, it, expect } from "vitest";
|
|
31
31
|
|
|
32
32
|
import { CoreFunctionsKeys } from "../generated/cvc-enums.js";
|
|
33
|
+
import {
|
|
34
|
+
CORE_FUNCTIONS_EVALUABLE_KEYS,
|
|
35
|
+
CORE_FUNCTIONS_EVALUABLE_SOT_VERSION,
|
|
36
|
+
} from "../generated/coreFunctionsEvaluable.js";
|
|
33
37
|
import { expectedDefinition } from "../__sot__/coreFunctionFields.js";
|
|
34
38
|
import type { ProjectedFunctionFields } from "../__sot__/coreFunctionFields.js";
|
|
35
39
|
|
|
@@ -37,9 +41,11 @@ const here = path.dirname(fileURLToPath(import.meta.url));
|
|
|
37
41
|
const cvcDir = path.join(here, "..", "cvcs");
|
|
38
42
|
const sotDir = path.join(here, "..", "__sot__");
|
|
39
43
|
|
|
40
|
-
const SOT_FILE = "coreFunctions.v1.
|
|
41
|
-
const SOT_VERSION = "1.
|
|
42
|
-
const
|
|
44
|
+
const SOT_FILE = "coreFunctions.v1.3.0.json";
|
|
45
|
+
const SOT_VERSION = "1.3.0";
|
|
46
|
+
const SUPERSEDED_VERSION = "1.2.0";
|
|
47
|
+
/** Every superseded file is deleted per the bump checklist. */
|
|
48
|
+
const SUPERSEDED_FILES = ["coreFunctions.v1.1.0.json", "coreFunctions.v1.2.0.json"];
|
|
43
49
|
|
|
44
50
|
interface Entry {
|
|
45
51
|
code: string;
|
|
@@ -49,6 +55,10 @@ interface Entry {
|
|
|
49
55
|
parentCode: string | null;
|
|
50
56
|
childCodes: string[];
|
|
51
57
|
definition: string;
|
|
58
|
+
/** Canon's `v1` flag, structured since 1.3.0. */
|
|
59
|
+
v1: boolean;
|
|
60
|
+
/** Canon's `retired` flag, structured since 1.3.0. */
|
|
61
|
+
retired: boolean;
|
|
52
62
|
}
|
|
53
63
|
interface Envelope {
|
|
54
64
|
domain: string;
|
|
@@ -128,14 +138,15 @@ const { canonDrops } = completeness(
|
|
|
128
138
|
);
|
|
129
139
|
|
|
130
140
|
describe("core_functions — GATE I: the SOT restates canon (CVC-133 @ the pin)", () => {
|
|
131
|
-
it("is the generated file, at its version, superseding 1.
|
|
141
|
+
it("is the generated file, at its version, superseding 1.2.0 (1.1.0 and 1.2.0 are gone)", () => {
|
|
132
142
|
expect(sot.domain).toBe("core_functions");
|
|
133
143
|
expect(sot.version).toBe(SOT_VERSION);
|
|
134
144
|
expect(sot._status).toMatch(/^CANONICAL — /);
|
|
135
145
|
expect(sot._status).toContain("GENERATED");
|
|
136
146
|
expect(sot._source).toContain(pin.sourceFile);
|
|
137
|
-
expect(sot._supersedes.version).toBe(
|
|
138
|
-
|
|
147
|
+
expect(sot._supersedes.version).toBe(SUPERSEDED_VERSION);
|
|
148
|
+
for (const f of SUPERSEDED_FILES)
|
|
149
|
+
expect(() => readFileSync(path.join(cvcDir, f)), f).toThrow();
|
|
139
150
|
});
|
|
140
151
|
|
|
141
152
|
it("pins canon's own counts", () => {
|
|
@@ -217,6 +228,40 @@ describe("core_functions — GATE I: the SOT restates canon (CVC-133 @ the pin)"
|
|
|
217
228
|
expect(bad).toEqual([]);
|
|
218
229
|
});
|
|
219
230
|
|
|
231
|
+
it("carries canon's v1 and retired flags as structured booleans on every entry (1.3.0; read by the shared authz resolver)", () => {
|
|
232
|
+
const bad: string[] = [];
|
|
233
|
+
for (const e of sot.entries) {
|
|
234
|
+
if (typeof e.v1 !== "boolean" || typeof e.retired !== "boolean")
|
|
235
|
+
bad.push(`${e.key}: v1/retired are not booleans`);
|
|
236
|
+
}
|
|
237
|
+
for (const key of pin.keys) {
|
|
238
|
+
const f = pin.fields[key]!;
|
|
239
|
+
const e = byKey.get(key)!;
|
|
240
|
+
if (e.v1 !== f.v1) bad.push(`${key}: v1 ${e.v1} != canon v1 ${f.v1}`);
|
|
241
|
+
if (e.retired !== f.retired)
|
|
242
|
+
bad.push(`${key}: retired ${e.retired} != canon retired ${f.retired}`);
|
|
243
|
+
}
|
|
244
|
+
// The missingness sentinels are not permissionable functions.
|
|
245
|
+
for (const e of sot.entries.filter((x) => MISSINGNESS.test(x.code))) {
|
|
246
|
+
if (e.v1 || e.retired) bad.push(`${e.key}: a missingness sentinel must be v1 false / retired false`);
|
|
247
|
+
}
|
|
248
|
+
// A canon drop (RETIREMENTS) is retired, never v1.
|
|
249
|
+
for (const k of canonDrops) {
|
|
250
|
+
const e = byKey.get(k);
|
|
251
|
+
if (e && (e.v1 || !e.retired)) bad.push(`${k}: a canon drop must be v1 false / retired true`);
|
|
252
|
+
}
|
|
253
|
+
expect(bad).toEqual([]);
|
|
254
|
+
expect(functions.filter((e) => e.v1)).toHaveLength(pin.v1Count);
|
|
255
|
+
expect(Object.values(pin.fields).filter((f) => f.v1)).toHaveLength(pin.v1Count);
|
|
256
|
+
});
|
|
257
|
+
|
|
258
|
+
it("the generated evaluable key set (the authz resolver's canon input) equals the SOT's v1 && !retired keys", () => {
|
|
259
|
+
expect(CORE_FUNCTIONS_EVALUABLE_SOT_VERSION).toBe(SOT_VERSION);
|
|
260
|
+
const fromSot = sot.entries.filter((e) => e.v1 && !e.retired).map((e) => e.key).sort();
|
|
261
|
+
expect([...CORE_FUNCTIONS_EVALUABLE_KEYS]).toEqual(fromSot);
|
|
262
|
+
expect(CORE_FUNCTIONS_EVALUABLE_KEYS).toHaveLength(pin.v1Count);
|
|
263
|
+
});
|
|
264
|
+
|
|
220
265
|
it("is flat and append-only: every function at a flat 133-NNN code, contiguous from 001, each key once", () => {
|
|
221
266
|
const prefixes = functions.map((e) => {
|
|
222
267
|
const m = FLAT.exec(e.code);
|
|
@@ -254,16 +299,21 @@ describe("core_functions — GATE I: the SOT restates canon (CVC-133 @ the pin)"
|
|
|
254
299
|
if (!(e.key in ledger.prefixes))
|
|
255
300
|
bad.push(`${e.key}: in the SOT but not in the ledger`);
|
|
256
301
|
expect(bad).toEqual([]);
|
|
257
|
-
// The two ends of the 1.0.0 port, the 1.1.0 append, and where the 1.2.0
|
|
302
|
+
// The two ends of the 1.0.0 port, the 1.1.0 append, and where the 1.2.0
|
|
303
|
+
// append landed (1.3.0 appended nothing: it added the v1 / retired fields).
|
|
258
304
|
expect(ledger.prefixes["account_suspend"]).toBe(1);
|
|
259
305
|
expect(ledger.prefixes["usr_manage"]).toBe(77);
|
|
260
306
|
expect(ledger.prefixes["note_open_departed_author"]).toBe(78);
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
307
|
+
const appended120 = Object.keys(ledger.prefixes)
|
|
308
|
+
.filter((k) => ledger.since[k] === "1.2.0")
|
|
309
|
+
.sort((a, b) => ledger.prefixes[a]! - ledger.prefixes[b]!);
|
|
310
|
+
expect(appended120).toHaveLength(35);
|
|
311
|
+
expect(ledger.prefixes[appended120[0]!]).toBe(79);
|
|
312
|
+
expect(ledger.prefixes[appended120.at(-1)!]).toBe(
|
|
264
313
|
pin.functionCount + canonDrops.length,
|
|
265
314
|
);
|
|
266
|
-
expect(functions.at(-1)?.key).toBe(
|
|
315
|
+
expect(functions.at(-1)?.key).toBe(appended120.at(-1));
|
|
316
|
+
expect(sot._supersedes.appended).toEqual([]);
|
|
267
317
|
});
|
|
268
318
|
|
|
269
319
|
it("stamps every published key with the version that introduced it, and `since` agrees with the envelope", () => {
|
|
@@ -650,8 +650,9 @@ const SOT_SPECS: readonly SotSpec[] = [
|
|
|
650
650
|
// (SOT v1.2.0, 2026-10-12, additive): 113 canon functions (the 78 the 1.0.0
|
|
651
651
|
// port + 1.1.0 append published, at their codes, + 35 appended at
|
|
652
652
|
// 133-079 … 133-113 — the 2026-08-13 overhaul's rows the port never
|
|
653
|
-
// absorbed) + 4 missingness = 117
|
|
654
|
-
|
|
653
|
+
// absorbed) + 4 missingness = 117. SOT v1.3.0 (2026-10-13, additive, co-zo3):
|
|
654
|
+
// structured `v1` / `retired` on every entry; same 117.
|
|
655
|
+
{ file: "coreFunctions.v1.3.0.json", domain: "core_functions", expectedCount: 117 },
|
|
655
656
|
// 9 fine-grained Needs-Assessment CAR change types (@pave/domain
|
|
656
657
|
// NEEDS_ASSESSMENT_CHANGE_TYPES, casing normalized to lower_snake) + 4 = 13
|
|
657
658
|
{ file: "needsAssessmentChangeType.v1.0.0.json", domain: "needs_assessment_change_type", expectedCount: 13 },
|
|
@@ -674,8 +675,15 @@ const SOT_SPECS: readonly SotSpec[] = [
|
|
|
674
675
|
// upstream; the 2 scoring-ahead `_youth` codes withdrawn — hti-scoring 9c209cf no longer emits them).
|
|
675
676
|
{ file: "coreIndicators.v1.1.0.json", domain: "core_indicators", expectedCount: 226 },
|
|
676
677
|
{ file: "riskSeverityBand.v1.0.0.json", domain: "risk_severity_band", expectedCount: 9 },
|
|
677
|
-
|
|
678
|
-
|
|
678
|
+
// CVC-134 — 10 canon admin roles, NO missingness (the 1.0.0 quadruplet is
|
|
679
|
+
// withdrawn). SOT v2.0.0, generated by scripts/gen-admin-roles.py; GATE K
|
|
680
|
+
// (admin-roles-canon.test.ts) pins canon.
|
|
681
|
+
{ file: "adminRoles.v2.0.0.json", domain: "admin_roles", expectedCount: 10 },
|
|
682
|
+
// CVC-135 — 15 canon user roles, NO missingness (the 1.0.0 quadruplet is
|
|
683
|
+
// withdrawn). SOT v2.0.0 (MAJOR: `hotline_op` re-keyed to canon
|
|
684
|
+
// `crisis_response` at 135-004; missingness keys removed), generated by
|
|
685
|
+
// scripts/gen-user-roles.py; GATE J (user-roles-canon.test.ts) pins canon.
|
|
686
|
+
{ file: "userRoles.v2.0.0.json", domain: "user_roles", expectedCount: 15 },
|
|
679
687
|
{ file: "hmisCurrentLivingSituation.v1.0.0.json", domain: "hmis_current_living_situation", expectedCount: 33 },
|
|
680
688
|
{ file: "juvenileJusticeEpisodeType.v1.0.0.json", domain: "juvenile_justice_episode_type", expectedCount: 9 },
|
|
681
689
|
{ file: "incarcerationEpisodeType.v1.0.0.json", domain: "incarceration_episode_type", expectedCount: 9 },
|
|
@@ -49,7 +49,7 @@ describe("parseCvcStatus", () => {
|
|
|
49
49
|
expect(result.sourcePath).toBeNull();
|
|
50
50
|
});
|
|
51
51
|
|
|
52
|
-
it("classifies a CANONICAL provenance-note domain as its own maturity, not 'draft'/'final' (admin_roles
|
|
52
|
+
it("classifies a CANONICAL provenance-note domain as its own maturity, not 'draft'/'final' (the admin_roles 1.0.0 provenance note)", () => {
|
|
53
53
|
const result = parseCvcStatus({
|
|
54
54
|
_status:
|
|
55
55
|
"CANONICAL — imported 0.8.13 from the Notion Final CVC codebook (CVC-134 `core - admin " +
|
|
@@ -182,7 +182,7 @@ const SOT_FILES: readonly SotFile[] = [
|
|
|
182
182
|
// ─── Risk taxonomy (names-only projection of the @hti/scoring SOT) ───
|
|
183
183
|
{ file: "riskCategory.v1.0.0.json", expectedDomain: "risk_category" },
|
|
184
184
|
// ─── 0.8.12 vocabulary batch ───
|
|
185
|
-
{ file: "coreFunctions.v1.
|
|
185
|
+
{ file: "coreFunctions.v1.3.0.json", expectedDomain: "core_functions" },
|
|
186
186
|
{ file: "needsAssessmentChangeType.v1.0.0.json", expectedDomain: "needs_assessment_change_type" },
|
|
187
187
|
{ file: "roiScope.v1.4.0.json", expectedDomain: "roi_scope" },
|
|
188
188
|
{ file: "roiStatus.v1.0.0.json", expectedDomain: "roi_status" },
|
|
@@ -192,8 +192,8 @@ const SOT_FILES: readonly SotFile[] = [
|
|
|
192
192
|
{ file: "coreDhState.v1.0.0.json", expectedDomain: "dh_state" },
|
|
193
193
|
{ file: "coreIndicators.v1.1.0.json", expectedDomain: "core_indicators" },
|
|
194
194
|
{ file: "riskSeverityBand.v1.0.0.json", expectedDomain: "risk_severity_band" },
|
|
195
|
-
{ file: "adminRoles.
|
|
196
|
-
{ file: "userRoles.
|
|
195
|
+
{ file: "adminRoles.v2.0.0.json", expectedDomain: "admin_roles" },
|
|
196
|
+
{ file: "userRoles.v2.0.0.json", expectedDomain: "user_roles" },
|
|
197
197
|
{ file: "hmisCurrentLivingSituation.v1.0.0.json", expectedDomain: "hmis_current_living_situation" },
|
|
198
198
|
{ file: "juvenileJusticeEpisodeType.v1.0.0.json", expectedDomain: "juvenile_justice_episode_type" },
|
|
199
199
|
{ file: "incarcerationEpisodeType.v1.0.0.json", expectedDomain: "incarceration_episode_type" },
|
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared body of GATE J (CVC-135 user roles) and GATE K (CVC-134 admin roles):
|
|
3
|
+
* the generated SOT restates its canon pin, whole.
|
|
4
|
+
*
|
|
5
|
+
* Both SOTs are generated by `scripts/role_vocab.py` (via `gen-user-roles.py` /
|
|
6
|
+
* `gen-admin-roles.py`), so both gates assert the same contract; each gate's own
|
|
7
|
+
* file adds the vocabulary-specific checks. Not a test file itself (no
|
|
8
|
+
* `.test.ts` suffix): vitest collects only the two callers.
|
|
9
|
+
*/
|
|
10
|
+
import { readFileSync } from "node:fs";
|
|
11
|
+
import path from "node:path";
|
|
12
|
+
import { fileURLToPath } from "node:url";
|
|
13
|
+
import { describe, it, expect } from "vitest";
|
|
14
|
+
|
|
15
|
+
import { sotFieldName } from "../__sot__/roleFields.js";
|
|
16
|
+
|
|
17
|
+
const here = path.dirname(fileURLToPath(import.meta.url));
|
|
18
|
+
export const cvcDir = path.join(here, "..", "cvcs");
|
|
19
|
+
const sotDir = path.join(here, "..", "__sot__");
|
|
20
|
+
|
|
21
|
+
export interface RoleEntry {
|
|
22
|
+
code: string;
|
|
23
|
+
key: string;
|
|
24
|
+
title: string;
|
|
25
|
+
selectable: boolean;
|
|
26
|
+
parentCode: string | null;
|
|
27
|
+
childCodes: string[];
|
|
28
|
+
definition: string | null;
|
|
29
|
+
canonicalCode?: string;
|
|
30
|
+
definitionNote?: string;
|
|
31
|
+
[extra: string]: unknown;
|
|
32
|
+
}
|
|
33
|
+
export interface RoleEnvelope {
|
|
34
|
+
domain: string;
|
|
35
|
+
version: string;
|
|
36
|
+
_status: string;
|
|
37
|
+
_source: string;
|
|
38
|
+
_supersedes: {
|
|
39
|
+
version: string;
|
|
40
|
+
keyMap: Record<string, string | null>;
|
|
41
|
+
retiredCodes: { code: string; key: string; successor: null; reason: string }[];
|
|
42
|
+
notes: Record<string, string>;
|
|
43
|
+
appended: string[];
|
|
44
|
+
refreshed: string[];
|
|
45
|
+
tombstoned: string[];
|
|
46
|
+
};
|
|
47
|
+
levels: Record<string, string>;
|
|
48
|
+
entries: RoleEntry[];
|
|
49
|
+
}
|
|
50
|
+
export interface RolePin {
|
|
51
|
+
sourceRepo: string;
|
|
52
|
+
sourceFile: string;
|
|
53
|
+
sourceSha: string;
|
|
54
|
+
codes: string[];
|
|
55
|
+
roleFields: Record<string, Record<string, unknown>>;
|
|
56
|
+
legacyCodes: Record<string, string>;
|
|
57
|
+
}
|
|
58
|
+
export interface RoleLedger {
|
|
59
|
+
prefixes: Record<string, number>;
|
|
60
|
+
since: Record<string, string>;
|
|
61
|
+
renamed: Record<string, { to: string; prefix: number; version: string }>;
|
|
62
|
+
aliases: Record<string, { to: string; canonical: string; version: string }>;
|
|
63
|
+
retired: Record<string, { code: string; successor: null; reason: string; version: string }>;
|
|
64
|
+
supersededKeys: string[];
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
export interface RoleGateConfig {
|
|
68
|
+
gate: string;
|
|
69
|
+
domain: string;
|
|
70
|
+
/** Segment-0 CVC prefix, e.g. "135". */
|
|
71
|
+
prefix: string;
|
|
72
|
+
/** `userRoles` / `adminRoles`. */
|
|
73
|
+
stem: string;
|
|
74
|
+
version: string;
|
|
75
|
+
supersededVersion: string;
|
|
76
|
+
canonFile: string;
|
|
77
|
+
roleCount: number;
|
|
78
|
+
/** Canon code -> package key. */
|
|
79
|
+
keyOf: (canonCode: string) => string;
|
|
80
|
+
/** The generated enum for this domain. */
|
|
81
|
+
keys: Readonly<Record<string, string>>;
|
|
82
|
+
/** The barrel export for this domain. */
|
|
83
|
+
barrel: unknown;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
const BASE_FIELDS = new Set([
|
|
87
|
+
"code",
|
|
88
|
+
"key",
|
|
89
|
+
"title",
|
|
90
|
+
"selectable",
|
|
91
|
+
"parentCode",
|
|
92
|
+
"childCodes",
|
|
93
|
+
"definition",
|
|
94
|
+
"canonicalCode",
|
|
95
|
+
"definitionNote",
|
|
96
|
+
]);
|
|
97
|
+
const MISSINGNESS_KEYS = ["missingness_root", "unknown", "anonymous", "data_not_collected"];
|
|
98
|
+
|
|
99
|
+
export function loadRoleVocab(cfg: RoleGateConfig): {
|
|
100
|
+
sot: RoleEnvelope;
|
|
101
|
+
pin: RolePin;
|
|
102
|
+
ledger: RoleLedger;
|
|
103
|
+
} {
|
|
104
|
+
const read = <T>(p: string): T => JSON.parse(readFileSync(p, "utf8")) as T;
|
|
105
|
+
return {
|
|
106
|
+
sot: read<RoleEnvelope>(path.join(cvcDir, `${cfg.stem}.v${cfg.version}.json`)),
|
|
107
|
+
pin: read<RolePin>(path.join(sotDir, `${cfg.stem}.pin.json`)),
|
|
108
|
+
ledger: read<RoleLedger>(path.join(sotDir, `${cfg.stem}.published.json`)),
|
|
109
|
+
};
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* How a consumer resolves a stored role value: a live key, else `_supersedes.keyMap` (null = withdrawn).
|
|
114
|
+
* The keyMap is KEY-SPACE (the package convention), so a value stored in canon's spelling
|
|
115
|
+
* (`ACCT-ADM`, `MEM-ADM`) is first normalised with the codeset's key rule (`cfg.keyOf`).
|
|
116
|
+
*/
|
|
117
|
+
export function resolveStoredKey(cfg: RoleGateConfig, stored: string): string | undefined {
|
|
118
|
+
const key = stored in cfg.keys || stored in (cfg.barrel as RoleEnvelope)._supersedes.keyMap
|
|
119
|
+
? stored
|
|
120
|
+
: cfg.keyOf(stored);
|
|
121
|
+
if (key in cfg.keys) return cfg.keys[key];
|
|
122
|
+
const live = (cfg.barrel as RoleEnvelope)._supersedes.keyMap[key];
|
|
123
|
+
return live ? cfg.keys[live] : undefined;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
export function describeRoleVocabGate(cfg: RoleGateConfig): void {
|
|
127
|
+
const { sot, pin, ledger } = loadRoleVocab(cfg);
|
|
128
|
+
const flatRe = new RegExp(`^${cfg.prefix}-(\\d{3})-000-000-000-000-000$`);
|
|
129
|
+
const codeOf = (n: number): string => `${cfg.prefix}-${String(n).padStart(3, "0")}-000-000-000-000-000`;
|
|
130
|
+
const byKey = new Map(sot.entries.map((e) => [e.key, e] as const));
|
|
131
|
+
|
|
132
|
+
describe(`${cfg.domain} — ${cfg.gate}: the SOT restates canon (${pin.sourceFile} @ the pin)`, () => {
|
|
133
|
+
it(`is the generated file, at ${cfg.version}, superseding ${cfg.supersededVersion} (which is gone)`, () => {
|
|
134
|
+
expect(sot.domain).toBe(cfg.domain);
|
|
135
|
+
expect(sot.version).toBe(cfg.version);
|
|
136
|
+
expect(sot._status).toMatch(/^CANONICAL — /);
|
|
137
|
+
expect(sot._status).toContain("GENERATED");
|
|
138
|
+
expect(sot._source).toContain(pin.sourceFile);
|
|
139
|
+
expect(sot._supersedes.version).toBe(cfg.supersededVersion);
|
|
140
|
+
expect(() => readFileSync(path.join(cvcDir, `${cfg.stem}.v${cfg.supersededVersion}.json`))).toThrow();
|
|
141
|
+
expect((cfg.barrel as RoleEnvelope).version, "the barrel exports THIS file").toBe(cfg.version);
|
|
142
|
+
});
|
|
143
|
+
|
|
144
|
+
it("pins canon's codeset", () => {
|
|
145
|
+
expect(pin.sourceRepo).toBe("htilabstech/prototype");
|
|
146
|
+
expect(pin.sourceFile).toBe(cfg.canonFile);
|
|
147
|
+
expect(Object.keys(pin.roleFields).sort()).toEqual(pin.codes);
|
|
148
|
+
expect(pin.codes).toHaveLength(cfg.roleCount);
|
|
149
|
+
});
|
|
150
|
+
|
|
151
|
+
it("carries EVERY canon role and NOTHING canon does not; canonicalCode is canon's code", () => {
|
|
152
|
+
expect([...byKey.keys()].sort(), "SOT keys vs canon codes").toEqual(pin.codes.map(cfg.keyOf).sort());
|
|
153
|
+
expect(sot.entries).toHaveLength(pin.codes.length);
|
|
154
|
+
for (const code of pin.codes) {
|
|
155
|
+
expect(byKey.get(cfg.keyOf(code))?.canonicalCode, code).toBe(code);
|
|
156
|
+
}
|
|
157
|
+
});
|
|
158
|
+
|
|
159
|
+
it("restates every projected canon field verbatim, and invents none", () => {
|
|
160
|
+
const bad: string[] = [];
|
|
161
|
+
for (const code of pin.codes) {
|
|
162
|
+
const f = pin.roleFields[code]!;
|
|
163
|
+
const e = byKey.get(cfg.keyOf(code))!;
|
|
164
|
+
if (!e.selectable) bad.push(`${code}: live canon role is not selectable`);
|
|
165
|
+
if (e.title !== f["label"]) bad.push(`${code}: title ${JSON.stringify(e.title)} != canon label`);
|
|
166
|
+
// A canon definition's trailing NOTE paragraph rides as definitionNote; the join is canon's text.
|
|
167
|
+
const joined = e.definitionNote === undefined ? e.definition : `${e.definition} ${e.definitionNote}`;
|
|
168
|
+
if (joined !== f["definition"]) bad.push(`${code}: definition (+ definitionNote) != canon`);
|
|
169
|
+
if (e.definitionNote !== undefined && !e.definitionNote.startsWith("NOTE: "))
|
|
170
|
+
bad.push(`${code}: definitionNote is not canon's NOTE paragraph`);
|
|
171
|
+
if (e.definitionNote === undefined && (f["definition"] as string).includes(" NOTE: "))
|
|
172
|
+
bad.push(`${code}: canon's NOTE paragraph was left in the definition`);
|
|
173
|
+
for (const [field, value] of Object.entries(f)) {
|
|
174
|
+
if (field === "label" || field === "definition") continue;
|
|
175
|
+
const sotName = sotFieldName(field);
|
|
176
|
+
if (value === null) {
|
|
177
|
+
if (sotName in e) bad.push(`${code}: carries ${sotName}, canon has no ${field}`);
|
|
178
|
+
} else if (JSON.stringify(e[sotName]) !== JSON.stringify(value)) {
|
|
179
|
+
bad.push(`${code}: ${sotName} ${JSON.stringify(e[sotName])} != canon ${field} ${JSON.stringify(value)}`);
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
const allowed = new Set([...BASE_FIELDS, ...Object.keys(f).map(sotFieldName)]);
|
|
183
|
+
for (const k of Object.keys(e)) if (!allowed.has(k)) bad.push(`${code}: field ${k} is not canon's`);
|
|
184
|
+
}
|
|
185
|
+
expect(bad).toEqual([]);
|
|
186
|
+
});
|
|
187
|
+
|
|
188
|
+
it("is flat and append-only: every role at a flat code, contiguous from 001", () => {
|
|
189
|
+
const prefixes = sot.entries.map((e) => {
|
|
190
|
+
const m = flatRe.exec(e.code);
|
|
191
|
+
expect(m, `${e.key} at ${e.code} is not a flat segment-1 code`).not.toBeNull();
|
|
192
|
+
expect(e.parentCode).toBeNull();
|
|
193
|
+
expect(e.childCodes).toEqual([]);
|
|
194
|
+
return Number(m![1]);
|
|
195
|
+
});
|
|
196
|
+
expect(prefixes).toEqual(prefixes.map((_, i) => i + 1));
|
|
197
|
+
expect(sot.levels).toEqual({ "1": expect.any(String) });
|
|
198
|
+
});
|
|
199
|
+
|
|
200
|
+
it("keeps every published code where it was — the ledger, pair by pair (consumers gate on the key)", () => {
|
|
201
|
+
const bad: string[] = [];
|
|
202
|
+
for (const [key, prefix] of Object.entries(ledger.prefixes)) {
|
|
203
|
+
const e = byKey.get(key);
|
|
204
|
+
if (!e) bad.push(`${key}: published at ${codeOf(prefix)} but absent from the SOT`);
|
|
205
|
+
else if (e.code !== codeOf(prefix)) bad.push(`${key}: published at ${codeOf(prefix)}, SOT has ${e.code}`);
|
|
206
|
+
if (cfg.keys[key] !== codeOf(prefix)) bad.push(`${key}: generated enum != ${codeOf(prefix)}`);
|
|
207
|
+
}
|
|
208
|
+
for (const e of sot.entries) if (!(e.key in ledger.prefixes)) bad.push(`${e.key}: in the SOT but not in the ledger`);
|
|
209
|
+
expect(bad).toEqual([]);
|
|
210
|
+
expect(Object.keys(cfg.keys).sort()).toEqual(Object.keys(ledger.prefixes).sort());
|
|
211
|
+
});
|
|
212
|
+
|
|
213
|
+
it("carries NO missingness: the quadruplet is withdrawn as retirements, never reused", () => {
|
|
214
|
+
expect(sot.entries.filter((e) => e.code.startsWith(`${cfg.prefix}-000-`))).toEqual([]);
|
|
215
|
+
// Version-agnostic: the ledger's `retired` set is enforced on every version; the per-version
|
|
216
|
+
// record (`retiredCodes`, the missingness note) only in the version the retirement happened.
|
|
217
|
+
for (const k of MISSINGNESS_KEYS) expect(k in ledger.retired, `${k} is retired in the ledger`).toBe(true);
|
|
218
|
+
const live = new Set(sot.entries.map((e) => e.code));
|
|
219
|
+
for (const [key, r] of Object.entries(ledger.retired)) {
|
|
220
|
+
expect(r.code.startsWith(`${cfg.prefix}-000-`), key).toBe(true);
|
|
221
|
+
expect(live.has(r.code), `${key}'s code ${r.code} is reused`).toBe(false);
|
|
222
|
+
expect(key in cfg.keys, `${key} is still in the enum`).toBe(false);
|
|
223
|
+
expect(sot._supersedes.keyMap[key], `${key} keyMap`).toBeNull();
|
|
224
|
+
expect(resolveStoredKey(cfg, key), `a stored ${key}`).toBeUndefined();
|
|
225
|
+
}
|
|
226
|
+
const retiredNow = Object.entries(ledger.retired).filter(
|
|
227
|
+
([, r]) => r.version === cfg.version,
|
|
228
|
+
);
|
|
229
|
+
expect(sot._supersedes.retiredCodes).toEqual(
|
|
230
|
+
retiredNow.map(([key, r]) => ({ code: r.code, key, successor: null, reason: r.reason })),
|
|
231
|
+
);
|
|
232
|
+
if (retiredNow.length > 0) {
|
|
233
|
+
expect(sot._supersedes.retiredCodes.length).toBeGreaterThan(0);
|
|
234
|
+
expect(sot._supersedes.notes["missingness"]).toMatch(/^WITHDRAWN: /);
|
|
235
|
+
} else {
|
|
236
|
+
expect(sot._supersedes.notes["missingness"]).toBeUndefined();
|
|
237
|
+
}
|
|
238
|
+
});
|
|
239
|
+
|
|
240
|
+
it("every canon legacy_codes line resolves: a published old key re-keyed in place, the rest aliased", () => {
|
|
241
|
+
const canonLegacy = Object.entries(pin.legacyCodes).map(
|
|
242
|
+
([o, n]) => [cfg.keyOf(o), cfg.keyOf(n)] as const,
|
|
243
|
+
);
|
|
244
|
+
const recorded = {
|
|
245
|
+
...Object.fromEntries(Object.entries(ledger.renamed).map(([o, r]) => [o, r.to])),
|
|
246
|
+
...Object.fromEntries(Object.entries(ledger.aliases).map(([o, a]) => [o, a.to])),
|
|
247
|
+
};
|
|
248
|
+
expect(recorded, "ledger renamed + aliases == canon legacy_codes").toEqual(Object.fromEntries(canonLegacy));
|
|
249
|
+
for (const [old, r] of Object.entries(ledger.renamed)) {
|
|
250
|
+
expect(ledger.prefixes[r.to], `${r.to} took ${old}'s prefix`).toBe(r.prefix);
|
|
251
|
+
expect(old in ledger.prefixes, `${old} no longer holds a prefix`).toBe(false);
|
|
252
|
+
expect(sot._supersedes.notes[old]).toMatch(/^RE-KEYED IN PLACE in \d+\.\d+\.\d+: /);
|
|
253
|
+
}
|
|
254
|
+
for (const [old, a] of Object.entries(ledger.aliases)) {
|
|
255
|
+
expect(old in ledger.prefixes || old in ledger.retired, `${old} was never published`).toBe(false);
|
|
256
|
+
expect(cfg.keyOf(a.canonical)).toBe(old);
|
|
257
|
+
expect(sot._supersedes.notes[old]).toMatch(/^LEGACY ALIAS \(since \d+\.\d+\.\d+\): /);
|
|
258
|
+
expect(resolveStoredKey(cfg, a.canonical), `canon's spelling ${a.canonical}`).toBe(cfg.keys[a.to]);
|
|
259
|
+
}
|
|
260
|
+
for (const [old, live] of canonLegacy) {
|
|
261
|
+
expect(old in cfg.keys, `${old} is not a live key`).toBe(false);
|
|
262
|
+
expect(resolveStoredKey(cfg, old), `a stored ${old}`).toBe(cfg.keys[live]);
|
|
263
|
+
}
|
|
264
|
+
});
|
|
265
|
+
|
|
266
|
+
it(`_supersedes.keyMap is CUMULATIVE: every ${cfg.supersededVersion} key, plus every re-key, alias and retirement the ledger has ever recorded`, () => {
|
|
267
|
+
const expected: Record<string, string | null> = {};
|
|
268
|
+
for (const k of ledger.supersededKeys) {
|
|
269
|
+
expected[k] = k in ledger.retired ? null : (ledger.renamed[k]?.to ?? k);
|
|
270
|
+
}
|
|
271
|
+
for (const [old, r] of Object.entries(ledger.renamed)) expected[old] = r.to;
|
|
272
|
+
for (const [old, a] of Object.entries(ledger.aliases)) expected[old] = a.to;
|
|
273
|
+
for (const k of Object.keys(ledger.retired)) expected[k] = null;
|
|
274
|
+
expect(sot._supersedes.keyMap).toEqual(expected);
|
|
275
|
+
expect(sot._supersedes.appended).toEqual([]);
|
|
276
|
+
expect(sot._supersedes.tombstoned).toEqual([]);
|
|
277
|
+
});
|
|
278
|
+
});
|
|
279
|
+
}
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* USER ROLES (CVC-135) — GATE J: the SOT restates canon, whole
|
|
3
|
+
* =============================================================
|
|
4
|
+
*
|
|
5
|
+
* `src/cvcs/userRoles.v2.0.0.json` is GENERATED from the canonical CVC-135
|
|
6
|
+
* codeset (`htilabstech/prototype` `data/cvcs/core_user_role.yaml`) by
|
|
7
|
+
* `scripts/gen-user-roles.py`. This test is the hermetic enforcer: it asserts
|
|
8
|
+
* the shipped SOT conforms to `src/__sot__/userRoles.pin.json` (the canon
|
|
9
|
+
* snapshot `scripts/sot-pins.ts` takes at a SHA), on every PR, with no
|
|
10
|
+
* cross-repo auth. `npm run sot:pins:check` is the detector that notices when
|
|
11
|
+
* canon itself has moved. The shared contract lives in `role-vocab-gate.ts`
|
|
12
|
+
* (GATE K, CVC-134 admin roles, asserts the same one); this file adds the
|
|
13
|
+
* CVC-135 specifics.
|
|
14
|
+
*
|
|
15
|
+
* History it closes: the 1.0.0 file was hand-imported in 0.8.13 from the June
|
|
16
|
+
* Notion export and validated against itself. Canon re-keyed the Crisis
|
|
17
|
+
* Response role `hotline_op` -> `crisis_response` (yaml `legacy_codes`, roster
|
|
18
|
+
* re-keyed 2026-08-14) and changed 6 published titles (5 plus the re-keyed
|
|
19
|
+
* Crisis Response's own) and 13 definitions on 2026-09-06
|
|
20
|
+
* (CVC134-135-AUDIT); nothing failed, while canon CVC-133 bounds named
|
|
21
|
+
* `crisis_response` on 35 functions the package could not resolve.
|
|
22
|
+
*/
|
|
23
|
+
import { describe, it, expect } from "vitest";
|
|
24
|
+
|
|
25
|
+
import { UserRoleKeys } from "../generated/cvc-enums.js";
|
|
26
|
+
import { userRolesSot } from "../cvcs/index.js";
|
|
27
|
+
import { describeRoleVocabGate, loadRoleVocab, resolveStoredKey, type RoleGateConfig } from "./role-vocab-gate.js";
|
|
28
|
+
|
|
29
|
+
const cfg: RoleGateConfig = {
|
|
30
|
+
gate: "GATE J",
|
|
31
|
+
domain: "user_roles",
|
|
32
|
+
prefix: "135",
|
|
33
|
+
stem: "userRoles",
|
|
34
|
+
version: "2.0.0",
|
|
35
|
+
supersededVersion: "1.0.0",
|
|
36
|
+
canonFile: "data/cvcs/core_user_role.yaml",
|
|
37
|
+
roleCount: 15,
|
|
38
|
+
keyOf: (code) => code,
|
|
39
|
+
keys: UserRoleKeys,
|
|
40
|
+
barrel: userRolesSot,
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
describeRoleVocabGate(cfg);
|
|
44
|
+
|
|
45
|
+
describe("user_roles — GATE J: CVC-135 specifics", () => {
|
|
46
|
+
const { sot, ledger } = loadRoleVocab(cfg);
|
|
47
|
+
const CRISIS_CODE = "135-004-000-000-000-000-000";
|
|
48
|
+
|
|
49
|
+
it("every published code is frozen: the 1.0.0 key -> code table, hotline_op's slot now crisis_response", () => {
|
|
50
|
+
// Literal, NOT derived from the ledger: the 1.0.0 file is deleted, so this table is the only record
|
|
51
|
+
// independent of userRoles.published.json. A ledger edit that moves a published key fails here.
|
|
52
|
+
expect(Object.entries(UserRoleKeys)).toEqual(
|
|
53
|
+
[
|
|
54
|
+
"case_nav",
|
|
55
|
+
"healthcare_provider_medical",
|
|
56
|
+
"behavioral_health_provider",
|
|
57
|
+
"crisis_response", // 1.0.0 `hotline_op`, re-keyed in place
|
|
58
|
+
"intel_analyst",
|
|
59
|
+
"investigator",
|
|
60
|
+
"le_liaison_vsp",
|
|
61
|
+
"legal_advocate",
|
|
62
|
+
"mandatory_reporter",
|
|
63
|
+
"mdt_participant",
|
|
64
|
+
"prosecutor_review",
|
|
65
|
+
"public_reporter",
|
|
66
|
+
"research_analytics",
|
|
67
|
+
"screener",
|
|
68
|
+
"volunteer",
|
|
69
|
+
].map((k, i) => [k, `135-${String(i + 1).padStart(3, "0")}-000-000-000-000-000`]),
|
|
70
|
+
);
|
|
71
|
+
});
|
|
72
|
+
|
|
73
|
+
it("re-keys hotline_op -> crisis_response at 135-004, and a stored hotline_op still resolves", () => {
|
|
74
|
+
expect(UserRoleKeys.crisis_response).toBe(CRISIS_CODE);
|
|
75
|
+
expect(sot.entries.find((e) => e.key === "crisis_response")?.title).toBe("Crisis Response");
|
|
76
|
+
expect(ledger.renamed).toEqual({ hotline_op: { to: "crisis_response", prefix: 4, version: "2.0.0" } });
|
|
77
|
+
expect(sot._supersedes.keyMap["hotline_op"]).toBe("crisis_response");
|
|
78
|
+
expect(resolveStoredKey(cfg, "hotline_op")).toBe(CRISIS_CODE);
|
|
79
|
+
expect(resolveStoredKey(cfg, "crisis_response")).toBe(CRISIS_CODE);
|
|
80
|
+
});
|
|
81
|
+
|
|
82
|
+
it("aliases canon's never-published legacy codes case_advocate and leads_investigator", () => {
|
|
83
|
+
expect(Object.keys(ledger.aliases).sort()).toEqual(["case_advocate", "leads_investigator"]);
|
|
84
|
+
expect(resolveStoredKey(cfg, "case_advocate")).toBe(UserRoleKeys.case_nav);
|
|
85
|
+
expect(resolveStoredKey(cfg, "leads_investigator")).toBe(UserRoleKeys.investigator);
|
|
86
|
+
// Canon's retired_never_canonical strings are deliberately NOT aliased: they must fail, not resolve.
|
|
87
|
+
for (const never of ["platform_admin", "case_navigator", "advocate"]) {
|
|
88
|
+
expect(resolveStoredKey(cfg, never), never).toBeUndefined();
|
|
89
|
+
}
|
|
90
|
+
});
|
|
91
|
+
|
|
92
|
+
it("_supersedes.refreshed (2.0.0 over 1.0.0) names exactly the roles whose title or definition canon changed", () => {
|
|
93
|
+
if (sot._supersedes.version !== "1.0.0") return; // a per-bump record; re-derived for each bump
|
|
94
|
+
expect(sot._supersedes.refreshed).toHaveLength(14);
|
|
95
|
+
expect(sot._supersedes.refreshed).not.toContain("intel_analyst");
|
|
96
|
+
});
|
|
97
|
+
|
|
98
|
+
it("carries canon's platform_tools on every role and the HTI-only flag on research_analytics", () => {
|
|
99
|
+
for (const e of sot.entries) expect(Array.isArray(e["platformTools"]), e.key).toBe(true);
|
|
100
|
+
expect(sot.entries.filter((e) => "flags" in e).map((e) => [e.key, e["flags"]])).toEqual([
|
|
101
|
+
["research_analytics", ["HTI-only"]],
|
|
102
|
+
]);
|
|
103
|
+
});
|
|
104
|
+
});
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @htilabs/platform-common-models/authz
|
|
3
|
+
*
|
|
4
|
+
* Browser-safe entry for the shared CVC-133 authorization resolver: pure
|
|
5
|
+
* TypeScript, no mongoose, no I/O. Also re-exported from the package root
|
|
6
|
+
* (which loads mongoose-backed models and services).
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
export * from "./resolveEffectiveFunctions.js";
|