@htilabs/platform-common-models 0.21.0 → 0.22.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 (40) hide show
  1. package/dist/cvcs/index.cjs +449 -50
  2. package/dist/cvcs/index.cjs.map +1 -1
  3. package/dist/cvcs/index.d.cts +491 -55
  4. package/dist/cvcs/index.d.ts +491 -55
  5. package/dist/cvcs/index.js +449 -50
  6. package/dist/cvcs/index.js.map +1 -1
  7. package/dist/enums/index.cjs +36 -1
  8. package/dist/enums/index.cjs.map +1 -1
  9. package/dist/enums/index.d.cts +37 -2
  10. package/dist/enums/index.d.ts +37 -2
  11. package/dist/enums/index.js +36 -1
  12. package/dist/enums/index.js.map +1 -1
  13. package/dist/index.cjs +589 -51
  14. package/dist/index.cjs.map +1 -1
  15. package/dist/index.d.cts +1 -1
  16. package/dist/index.d.ts +1 -1
  17. package/dist/index.js +580 -51
  18. package/dist/index.js.map +1 -1
  19. package/dist/schemas/index.cjs +104 -0
  20. package/dist/schemas/index.cjs.map +1 -1
  21. package/dist/schemas/index.d.cts +240 -1
  22. package/dist/schemas/index.d.ts +240 -1
  23. package/dist/schemas/index.js +95 -0
  24. package/dist/schemas/index.js.map +1 -1
  25. package/package.json +1 -1
  26. package/src/__sot__/README.md +1 -0
  27. package/src/__sot__/coreFunctionFields.ts +121 -0
  28. package/src/__sot__/coreFunctions.pin.json +1546 -0
  29. package/src/__sot__/coreFunctions.published.json +233 -0
  30. package/src/__tests__/__snapshots__/cvc-sot.snap +2 -2
  31. package/src/__tests__/core-functions-canon.test.ts +308 -24
  32. package/src/__tests__/cvc-sot-snapshot.test.ts +7 -4
  33. package/src/__tests__/cvc-status-parser.test.ts +1 -1
  34. package/src/__tests__/cvc-structural.test.ts +1 -1
  35. package/src/__tests__/organization-program.test.ts +254 -0
  36. package/src/cvcs/{coreFunctions.v1.1.0.json → coreFunctions.v1.2.0.json} +446 -47
  37. package/src/cvcs/index.ts +1 -1
  38. package/src/generated/cvc-enums.ts +37 -2
  39. package/src/schemas/index.ts +18 -0
  40. package/src/schemas/organization-program.ts +297 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@htilabs/platform-common-models",
3
- "version": "0.21.0",
3
+ "version": "0.22.0",
4
4
  "description": "Shared constants, types, and models for HTI Labs applications",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
@@ -12,6 +12,7 @@ live in other repos:
12
12
  | `cvcIndex.pin.json` | `htilabstech/prototype` · `Final CVCs/CVC_INDEX.md` | The CVC **number space** — which number belongs to which vocabulary. **Authoritative.** A yaml's self-declared number is not. |
13
13
  | `coreIndicators.pin.json` | `htilabstech/prototype` · `data/core_indicators.yaml` | The indicator **catalog** — which indicator codes legitimately exist, **and what the catalog says about each one** (label · definition · family · polarity · severity · is_alert · alert_when, verbatim). |
14
14
  | `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. |
15
+ | `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 · retired, verbatim). 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. |
15
16
 
16
17
  (Notion is the fourth SOT: **ratification**. It has no pin because it is a human
17
18
  process. Items awaiting it carry `_status.vocabStatus:
@@ -0,0 +1,121 @@
1
+ /**
2
+ * THE FIELD HALF OF THE coreFunctions PIN
3
+ * =======================================
4
+ *
5
+ * `coreFunctions.pin.json` is the snapshot of the canonical CVC-133 registry —
6
+ * `data/cvcs/core_functions.yaml` in `htilabstech/prototype`, itself GENERATED
7
+ * there from the Notion `core - functions` export by
8
+ * `tools/build_core_functions_registry.py` ("the export wins"). The package's
9
+ * `src/cvcs/coreFunctions.v*.json` is downstream of it: regenerated by
10
+ * `scripts/gen-core-functions.py`, never hand-edited.
11
+ *
12
+ * Why a pin at all: the 1.0.0 / 1.1.0 files were hand-absorbed and validated
13
+ * against themselves, and drifted to 78 of canon's 113 rows with stale
14
+ * platform relevance, stale v1 posture and stale labels — the same failure
15
+ * class `coreIndicators.pin.json` closed for CVC-136 (66 missing, 56 invented).
16
+ * With this pin, `core-functions-canon.test.ts` (GATE I) asserts on every PR that
17
+ * the shipped SOT restates every canon function — key, label, and the posture
18
+ * suffix the entry schema folds into `definition` — and nothing canon does not
19
+ * carry; `sot:pins:check` detects when canon moves.
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.
25
+ *
26
+ * Lives in `src/` (not `scripts/`) for the same tsconfig `rootDir` reason as
27
+ * `coreIndicatorFields.ts`.
28
+ */
29
+
30
+ export const PROJECTED_FUNCTION_FIELDS = [
31
+ "label",
32
+ "definition",
33
+ "status",
34
+ "category",
35
+ "platform_relevance",
36
+ "is_user_relevant",
37
+ "is_admin_relevant",
38
+ "retired",
39
+ ] as const;
40
+
41
+ export type ProjectedFunctionField = (typeof PROJECTED_FUNCTION_FIELDS)[number];
42
+
43
+ export interface ProjectedFunctionFields {
44
+ readonly label: string;
45
+ /** Canon's definition body, trimmed; the SOT definition is this + " " + the posture suffix. */
46
+ readonly definition: string;
47
+ readonly status: string;
48
+ readonly category: string;
49
+ /** Canon's `platform_relevance` list, in canon order (the SOT suffix joins it with ", "). */
50
+ readonly platform_relevance: readonly string[];
51
+ readonly is_user_relevant: boolean;
52
+ readonly is_admin_relevant: boolean;
53
+ /** Canon's first-class `retired: true` (2026-08-14 Phase 1); a tombstone in the SOT. */
54
+ readonly retired: boolean;
55
+ }
56
+
57
+ /** Project one canon row (a parsed `functions[]` item of the yaml). */
58
+ export function projectFunctionRow(
59
+ row: Readonly<Record<string, unknown>>,
60
+ ): ProjectedFunctionFields {
61
+ const str = (k: string): string => {
62
+ const v = row[k];
63
+ if (typeof v !== "string")
64
+ throw new Error(
65
+ `core_functions.yaml row ${String(row["code"])}: ${k} is not a string`,
66
+ );
67
+ return v;
68
+ };
69
+ const bool = (k: string): boolean => {
70
+ const v = row[k];
71
+ if (v === undefined) return false;
72
+ if (typeof v !== "boolean")
73
+ throw new Error(
74
+ `core_functions.yaml row ${String(row["code"])}: ${k} is not a boolean`,
75
+ );
76
+ return v;
77
+ };
78
+ const rel = row["platform_relevance"];
79
+ if (!Array.isArray(rel) || !rel.every((x) => typeof x === "string")) {
80
+ throw new Error(
81
+ `core_functions.yaml row ${String(row["code"])}: platform_relevance is not a string list`,
82
+ );
83
+ }
84
+ return {
85
+ label: str("label"),
86
+ definition: str("definition").trim(),
87
+ status: str("status"),
88
+ category: str("category"),
89
+ platform_relevance: [...(rel as string[])],
90
+ is_user_relevant: bool("is_user_relevant"),
91
+ is_admin_relevant: bool("is_admin_relevant"),
92
+ retired: bool("retired"),
93
+ };
94
+ }
95
+
96
+ /**
97
+ * The posture suffix the SOT folds into `definition` (the 1.0.0 port's shape,
98
+ * reproduced by `scripts/gen-core-functions.py`). Both halves compose it from
99
+ * the SAME projected fields, so a generator that drifts from this shape fails
100
+ * GATE I rather than shipping.
101
+ */
102
+ /**
103
+ * The whole SOT `definition` a canon row must produce: body + " " + suffix, with
104
+ * the tombstone marker ahead of the suffix for a retired row.
105
+ */
106
+ export function expectedDefinition(f: ProjectedFunctionFields): string {
107
+ const tomb = f.retired
108
+ ? "[RETIRED in canon — tombstone: kept so stored policies naming it still parse; " +
109
+ "resolvers refuse it with state 'retired'; never offered in a picker.] "
110
+ : "";
111
+ return `${f.definition} ${tomb}${postureSuffix(f)}`;
112
+ }
113
+
114
+ export function postureSuffix(f: ProjectedFunctionFields): string {
115
+ const yn = (b: boolean): string => (b ? "yes" : "no");
116
+ return (
117
+ `[Status: ${f.status}. Platform: ${f.platform_relevance.join(", ")}. ` +
118
+ `User-relevant: ${yn(f.is_user_relevant)}. Admin-relevant: ${yn(f.is_admin_relevant)}. ` +
119
+ `Category: ${f.category}.]`
120
+ );
121
+ }