@htilabs/platform-common-models 0.23.0 → 0.24.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 (61) hide show
  1. package/README.md +39 -0
  2. package/dist/authz/index.cjs +143 -12
  3. package/dist/authz/index.cjs.map +1 -1
  4. package/dist/authz/index.d.cts +121 -12
  5. package/dist/authz/index.d.ts +121 -12
  6. package/dist/authz/index.js +136 -12
  7. package/dist/authz/index.js.map +1 -1
  8. package/dist/constants/index.cjs +30 -0
  9. package/dist/constants/index.cjs.map +1 -1
  10. package/dist/constants/index.d.cts +1 -1
  11. package/dist/constants/index.d.ts +1 -1
  12. package/dist/constants/index.js +26 -0
  13. package/dist/constants/index.js.map +1 -1
  14. package/dist/{cvcEntry-0BIB9sen.d.cts → cvcEntry-BqAGctqK.d.cts} +4 -1
  15. package/dist/{cvcEntry-0BIB9sen.d.ts → cvcEntry-BqAGctqK.d.ts} +4 -1
  16. package/dist/{index-Zu_mOJRn.d.cts → index-BTqHP4DM.d.cts} +1 -1
  17. package/dist/{index-CDoqrfc1.d.ts → index-Dr6GBCoY.d.ts} +1 -1
  18. package/dist/index.cjs +147 -13
  19. package/dist/index.cjs.map +1 -1
  20. package/dist/index.d.cts +4 -4
  21. package/dist/index.d.ts +4 -4
  22. package/dist/index.js +140 -13
  23. package/dist/index.js.map +1 -1
  24. package/dist/models/index.cjs +26 -1
  25. package/dist/models/index.cjs.map +1 -1
  26. package/dist/models/index.d.cts +2 -2
  27. package/dist/models/index.d.ts +2 -2
  28. package/dist/models/index.js +26 -1
  29. package/dist/models/index.js.map +1 -1
  30. package/dist/{platform-auth-B49Ly57B.d.cts → platform-auth-DJO-r9Pf.d.cts} +48 -1
  31. package/dist/{platform-auth-B49Ly57B.d.ts → platform-auth-DJO-r9Pf.d.ts} +48 -1
  32. package/dist/schemas/index.cjs +26 -1
  33. package/dist/schemas/index.cjs.map +1 -1
  34. package/dist/schemas/index.d.cts +1 -1
  35. package/dist/schemas/index.d.ts +1 -1
  36. package/dist/schemas/index.js +26 -1
  37. package/dist/schemas/index.js.map +1 -1
  38. package/dist/services/index.cjs +26 -1
  39. package/dist/services/index.cjs.map +1 -1
  40. package/dist/services/index.js +26 -1
  41. package/dist/services/index.js.map +1 -1
  42. package/dist/types/index.d.cts +11 -3
  43. package/dist/types/index.d.ts +11 -3
  44. package/dist/validation/index.cjs +22 -0
  45. package/dist/validation/index.cjs.map +1 -1
  46. package/dist/validation/index.js +22 -0
  47. package/dist/validation/index.js.map +1 -1
  48. package/package.json +1 -1
  49. package/src/__sot__/README.md +1 -1
  50. package/src/__sot__/coreFunctionFields.ts +88 -4
  51. package/src/__sot__/coreFunctions.pin.json +1040 -113
  52. package/src/__tests__/authz-resolve.test.ts +115 -31
  53. package/src/__tests__/core-function-default-bounds.test.ts +374 -0
  54. package/src/__tests__/core-functions-case-close.test.ts +82 -0
  55. package/src/authz/defaultBounds.ts +69 -0
  56. package/src/authz/index.ts +12 -3
  57. package/src/authz/resolveEffectiveFunctions.ts +69 -29
  58. package/src/constants/platform-auth.ts +60 -0
  59. package/src/generated/coreFunctionDefaultBounds.ts +109 -0
  60. package/src/schemas/platform-role.ts +4 -1
  61. package/src/types/platform-auth.ts +9 -2
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@htilabs/platform-common-models",
3
- "version": "0.23.0",
3
+ "version": "0.24.0",
4
4
  "description": "Shared constants, types, and models for HTI Labs applications",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
@@ -14,7 +14,7 @@ live in other repos:
14
14
  | `userRoles.pin.json` | `htilabstech/prototype` · `data/cvcs/core_user_role.yaml` | The CVC-135 **user-role codeset** — which operational roles exist, **what canon says about each one** (label · definition · display_label · platform_tools · flags, verbatim) and canon's **legacy codes** (`legacy_codes`, old → live). `GATE J` (`user-roles-canon.test.ts`) asserts `userRoles.v*.json` restates every one. **Refreshing this pin is half a step:** the SOT JSON is generated from the same yaml by `scripts/gen-user-roles.py <prototype root>` — run it in the same change against the same prototype SHA, bumping the SOT version per `CLAUDE.md`, or GATE J fails (correctly). The generator also maintains `userRoles.published.json`, the append-only ledger of every published key → code, every re-key (`renamed`), every legacy alias (`aliases`) and every withdrawn code (`retired`), which GATE J asserts pair by pair. |
15
15
  | `adminRoles.pin.json` | `htilabstech/prototype` · `data/cvcs/core_admin_role.yaml` | The CVC-134 **admin-role codeset** (the control-plane axis) — which admin roles exist, what canon says about each one (label · definition · display_label · required · required_when · reach · scope · plain_language, verbatim) and canon's `legacy_codes`. `GATE K` (`admin-roles-canon.test.ts`) asserts `adminRoles.v*.json` restates every one. Same half-a-step rule as `userRoles`: regenerate with `scripts/gen-admin-roles.py <prototype root>` in the same change; it maintains `adminRoles.published.json`. Both role pins share one projection, `roleFields.ts`, and both generators share one implementation, `scripts/role_vocab.py`; the gates share `role-vocab-gate.ts`. |
16
16
  | `scoringEmits.pin.json` | `htilabstech/hti-scoring` · `weights/risk.weights.json` → `emits_by_code` | What the risk pipeline actually **consumes** — what CVC-136 must be able to express. |
17
- | `coreFunctions.pin.json` | `htilabstech/prototype` · `data/cvcs/core_functions.yaml` | The CVC-133 **function registry** — which permissionable functions exist, **and what canon says about each one** (label · status · category · platform relevance · user/admin relevance · v1 · retired, verbatim; since SOT 1.3.0 `v1` / `retired` are also structured booleans on every SOT entry, read by the shared authorization resolver). The yaml is itself generated there from the Notion export ("the export wins"). `GATE I` (`core-functions-canon.test.ts`) asserts `coreFunctions.v*.json` restates every one; `coreFunctionFields.ts` holds the shared projection + the posture-suffix composition. **Refreshing this pin is half a step:** the SOT JSON is generated from the same yaml by `scripts/gen-core-functions.py <prototype root>` — run it in the same change **against the same prototype checkout at the same SHA** (the pin reads the working tree; the generator reads `origin/main` after a fetch — keep them equal), bumping the SOT version per `CLAUDE.md`, or GATE I fails (correctly). The generator also maintains `coreFunctions.published.json`, the append-only ledger of every published key → code that GATE I asserts pair by pair. |
17
+ | `coreFunctions.pin.json` | `htilabstech/prototype` · `data/cvcs/core_functions.yaml` | The CVC-133 **function registry** — which permissionable functions exist, **and what canon says about each one** (label · status · category · platform relevance · user/admin relevance · v1 · retired, verbatim; since SOT 1.3.0 `v1` / `retired` are also structured booleans on every SOT entry, read by the shared authorization resolver) **and its per-role bounds** (since 0.24.0, co-p1x: `projectBounds` normalizes canon's `bounds:` to role code → ALWAYS / PREF_YES / PREF_NO / NEVER / NA; `GATE L` (`core-function-default-bounds.test.ts`) asserts the generated `src/generated/coreFunctionDefaultBounds.ts` equals it for every evaluable function and that every role code is a CVC-134 / CVC-135 `canonicalCode` — these are codebook DEFAULTS, the live bounds are platform policy state). The yaml is itself generated there from the Notion export ("the export wins"). `GATE I` (`core-functions-canon.test.ts`) asserts `coreFunctions.v*.json` restates every one; `coreFunctionFields.ts` holds the shared projection + the posture-suffix composition. **Refreshing this pin is half a step:** the SOT JSON is generated from the same yaml by `scripts/gen-core-functions.py <prototype root>` — run it in the same change **against the same prototype checkout at the same SHA** (the pin reads the working tree; the generator reads `origin/main` after a fetch — keep them equal), bumping the SOT version per `CLAUDE.md`, or GATE I fails (correctly). The generator also maintains `coreFunctions.published.json`, the append-only ledger of every published key → code that GATE I asserts pair by pair. |
18
18
 
19
19
  (Notion is the fourth SOT: **ratification**. It has no pin because it is a human
20
20
  process. Items awaiting it carry `_status.vocabStatus:
@@ -18,15 +18,23 @@
18
18
  * suffix the entry schema folds into `definition` — and nothing canon does not
19
19
  * carry; `sot:pins:check` detects when canon moves.
20
20
  *
21
- * The PROJECTION is the set of canon fields the SOT actually restates. Bounds
22
- * (Always / Default On / Default Off / Never per CVC-134/135 role code) are
23
- * canon too but the entry schema has no field for them, so they are not
24
- * projected here; they arrive with the resolver-contract round.
21
+ * The PROJECTION is the set of canon fields the package restates. Since
22
+ * 0.24.0 (co-p1x) that includes the per-role BOUNDS (Always / Default On /
23
+ * Default Off / Never / Not relevant per CVC-134/135 role code), normalized by
24
+ * `projectBounds` to `{ roleCode → DefaultBoundStateValue }`. The SOT entry
25
+ * schema still has no field for them: they ship as the generated module
26
+ * `src/generated/coreFunctionDefaultBounds.ts` (the evaluable functions'
27
+ * CODEBOOK DEFAULTS — what platform seeds and what "clear" reverts to; live
28
+ * role × function bounds are platform policy state), which GATE L
29
+ * (`core-function-default-bounds.test.ts`) asserts equals this projection.
25
30
  *
26
31
  * Lives in `src/` (not `scripts/`) for the same tsconfig `rootDir` reason as
27
32
  * `coreIndicatorFields.ts`.
28
33
  */
29
34
 
35
+ import { DEFAULT_BOUND_STATE } from "../constants/platform-auth.js";
36
+ import type { DefaultBoundStateValue } from "../constants/platform-auth.js";
37
+
30
38
  export const PROJECTED_FUNCTION_FIELDS = [
31
39
  "label",
32
40
  "definition",
@@ -37,6 +45,7 @@ export const PROJECTED_FUNCTION_FIELDS = [
37
45
  "is_admin_relevant",
38
46
  "v1",
39
47
  "retired",
48
+ "bounds",
40
49
  ] as const;
41
50
 
42
51
  export type ProjectedFunctionField = (typeof PROJECTED_FUNCTION_FIELDS)[number];
@@ -59,6 +68,80 @@ export interface ProjectedFunctionFields {
59
68
  readonly v1: boolean;
60
69
  /** Canon's first-class `retired: true` (2026-08-14 Phase 1); a tombstone in the SOT. */
61
70
  readonly retired: boolean;
71
+ /**
72
+ * Canon's `bounds:` block, normalized by `projectBounds`: role code → the
73
+ * codebook default bound, keys sorted. A role absent here is UNBOUND for
74
+ * the function. A row with no `bounds:` projects to `{}`.
75
+ */
76
+ readonly bounds: Readonly<Record<string, DefaultBoundStateValue>>;
77
+ }
78
+
79
+ /** Canon's four bound groups (each `{ admin_roles?, user_roles? }`) → the package state. */
80
+ const CANON_BOUND_GROUPS = {
81
+ always: DEFAULT_BOUND_STATE.ALWAYS,
82
+ default_on: DEFAULT_BOUND_STATE.PREF_YES,
83
+ default_off: DEFAULT_BOUND_STATE.PREF_NO,
84
+ never: DEFAULT_BOUND_STATE.NEVER,
85
+ } as const;
86
+
87
+ /** Canon's role-axis-free list of roles the function does not apply to → `NA`. */
88
+ const CANON_NA_GROUP = "not_applicable_roles";
89
+
90
+ /**
91
+ * Normalize one canon row's `bounds:` block to `{ roleCode → state }` (keys
92
+ * sorted). Shape per `data/cvcs/core_functions.yaml`: `always` / `default_on`
93
+ * / `default_off` / `never` each hold `admin_roles` and/or `user_roles` lists
94
+ * of `{ code, name, notion_id }`; `not_applicable_roles` is one list of the
95
+ * same entries across both axes. The join key is `code` (Phase 1,
96
+ * 2026-08-14); `name` is display metadata. Throws on anything else — an
97
+ * unknown group, an unknown axis, an entry without a string `code`, or a role
98
+ * named in two places — so a canon shape change fails the pin and GATE L
99
+ * instead of silently dropping a bound. (The platform prototype's
100
+ * `PLATFORM_BOUNDS.pristineStateFor`, `src/agencyhub.jsx:2024-2039`, would
101
+ * resolve a doubly-named role by precedence na > never > always > default_on
102
+ * > default_off; canon names no role twice, and a codebook that did is a
103
+ * defect to fix upstream, not a precedence to encode.)
104
+ */
105
+ export function projectBounds(
106
+ row: Readonly<Record<string, unknown>>,
107
+ ): Readonly<Record<string, DefaultBoundStateValue>> {
108
+ const where = `core_functions.yaml row ${String(row["code"])}: bounds`;
109
+ const b = row["bounds"];
110
+ if (b === undefined || b === null) return {};
111
+ if (typeof b !== "object" || Array.isArray(b)) throw new Error(`${where} is not a mapping`);
112
+ const out = new Map<string, DefaultBoundStateValue>();
113
+ const put = (entry: unknown, state: DefaultBoundStateValue, at: string): void => {
114
+ const code =
115
+ entry !== null && typeof entry === "object" ? (entry as Record<string, unknown>)["code"] : undefined;
116
+ if (typeof code !== "string" || code === "")
117
+ throw new Error(`${where}.${at}: an entry has no string code`);
118
+ if (out.has(code))
119
+ throw new Error(`${where}: role ${code} is named twice (${out.get(code)} and ${state})`);
120
+ out.set(code, state);
121
+ };
122
+ const list = (v: unknown, at: string): readonly unknown[] => {
123
+ if (v === undefined || v === null) return [];
124
+ if (!Array.isArray(v)) throw new Error(`${where}.${at} is not a list`);
125
+ return v;
126
+ };
127
+ for (const [group, value] of Object.entries(b as Record<string, unknown>)) {
128
+ if (group === CANON_NA_GROUP) {
129
+ for (const e of list(value, group)) put(e, DEFAULT_BOUND_STATE.NA, group);
130
+ continue;
131
+ }
132
+ if (!Object.hasOwn(CANON_BOUND_GROUPS, group))
133
+ throw new Error(`${where}: unknown group ${JSON.stringify(group)}`);
134
+ const state = CANON_BOUND_GROUPS[group as keyof typeof CANON_BOUND_GROUPS];
135
+ if (value === undefined || value === null) continue;
136
+ if (typeof value !== "object" || Array.isArray(value))
137
+ throw new Error(`${where}.${group} is not a mapping`);
138
+ for (const [axis, entries] of Object.entries(value as Record<string, unknown>)) {
139
+ if (axis !== "admin_roles" && axis !== "user_roles")
140
+ throw new Error(`${where}.${group}: unknown axis ${JSON.stringify(axis)}`);
141
+ for (const e of list(entries, `${group}.${axis}`)) put(e, state, `${group}.${axis}`);
142
+ }
143
+ }
144
+ return Object.fromEntries([...out].sort(([a], [z]) => (a < z ? -1 : a > z ? 1 : 0)));
62
145
  }
63
146
 
64
147
  /** Project one canon row (a parsed `functions[]` item of the yaml). */
@@ -106,6 +189,7 @@ export function projectFunctionRow(
106
189
  is_admin_relevant: bool("is_admin_relevant"),
107
190
  v1: requiredBool("v1"),
108
191
  retired: bool("retired"),
192
+ bounds: projectBounds(row),
109
193
  };
110
194
  }
111
195