@supersemantics/vsl-core 0.2.2 → 0.2.4

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 (3) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +189 -127
  3. package/package.json +54 -54
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Super Semantics
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Super Semantics
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,127 +1,189 @@
1
- # @supersemantics/vsl-core
2
-
3
- A TypeScript port of [`vsl-core`](https://github.com/supersemantics/VSL-Core) --
4
- the Python original, and the canonical reference for the VSL (VERBA
5
- Specification Language) governance vocabulary. This package exists so the
6
- same primitives are available to Node/TypeScript agent frameworks
7
- (LangGraph.js, LangChain.js, and others) without requiring a Python
8
- runtime alongside them.
9
-
10
- **Is:**
11
- - A faithful port of `vsl-core`'s constructs -- `PreNode`, `Invariant`, `AssuranceBasis`, `GammaEstimate`, `VerbaLedger`, `Cluster`, the conformance suite, and the Drift Class / Stabilisation Operator catalog.
12
- - Framework-agnostic and model-agnostic, same as the Python original -- this package never imports an agent-framework package or model-provider SDK, and never will.
13
- - Zero runtime dependencies -- only Node built-ins (`node:crypto`, `node:fs`), same guarantee `vsl-core` makes for Python.
14
-
15
- **Is not:**
16
- - The reference implementation. When the Python and TypeScript versions disagree on a design question, `vsl-core`'s own README and source are the source of truth -- see it first if something here seems inconsistent with what you already know from the Python package.
17
- - A byte-for-byte transliteration. A handful of things are deliberately adapted to TypeScript/Node rather than translated line-by-line -- see "Where this diverges from `vsl-core`" below. Every departure is a conscious design decision, documented in code and here, not an oversight.
18
- - A framework adapter. This package ships no LangGraph.js, LangChain.js, or other framework integration. Those belong in separate `@supersemantics/vsl-<framework>` packages, the same separation `vsl-core`'s Python ecosystem already follows (`vsl-langgraph`, `vsl-langchain`, `vsl-maf`).
19
-
20
- ## Quick taste
21
-
22
- ```typescript
23
- import {
24
- AssuranceBasis,
25
- F2Modification,
26
- GammaEstimate,
27
- PreNode,
28
- VerbaLedger,
29
- } from "@supersemantics/vsl-core";
30
-
31
- const preNode = new PreNode({
32
- name: "refund-cap",
33
- description: "Requires refund amount under the hard cap.",
34
- monitor: async (candidateInput) => {
35
- const amount = (candidateInput as { amount: number }).amount;
36
- return new GammaEstimate({ gammaHat: amount <= 1000 ? 2.0 : 0.0 });
37
- },
38
- assuranceBasis: new AssuranceBasis(true, F2Modification.NONE),
39
- });
40
-
41
- const ledger = new VerbaLedger();
42
- await ledger.writeMonitor("agent-1", false);
43
- console.log(await ledger.verifyIntegrity()); // true
44
- ```
45
-
46
- `PreNode`/`Invariant` compile into a framework's own gate the same way they
47
- do in Python -- via a `VSLAdapter` implementation. See
48
- [`vsl_core.conformance.protocol.VSLAdapter`](https://github.com/supersemantics/VSL-Core#building-an-adapter)
49
- in the Python README for what "conformant" actually means; the same
50
- contract (`compilePreNode`/`compileInvariant`, verified by
51
- `runConformanceSuite`) applies here.
52
-
53
- ## Where this diverges from `vsl-core`
54
-
55
- Two deliberate departures from the Python source, both documented at the
56
- point they matter in code -- not silent translations, not oversights:
57
-
58
- **`LedgerStore` is async here; it's synchronous in Python.** A store that
59
- keeps entries over the network cannot be synchronous in JavaScript -- there
60
- is no synchronous `fetch`.
61
- Rather than port the synchronous interface and break it later, every
62
- `LedgerStore` implementation here -- including `InMemoryLedgerStore` and
63
- `JsonlLedgerStore`, neither of which strictly needs it -- is
64
- `Promise`/`AsyncIterable`-based from the start.
65
-
66
- **`JsonlLedgerStore`'s cross-process file locking is narrower than
67
- Python's.** Python's version holds a real OS-level advisory lock
68
- (`fcntl.flock`/`msvcrt.locking`) across its read-last-entry-then-write
69
- critical section, closing the race between two separate store instances --
70
- in one process or several -- writing to the same file. Node's standard
71
- library has no equivalent cross-process locking primitive. This port only
72
- serializes writers *within the same Node process*. It does **not** protect
73
- against two separate Node processes (or two machines) appending to the
74
- same file concurrently -- that can still corrupt the chain. This is
75
- disclosed here and in `ledger.ts`'s own docstring, not silently narrowed.
76
- Don't point multiple processes at the same `JsonlLedgerStore` file until
77
- this gap is closed.
78
-
79
- Everything else -- `AssuranceBasis`'s validation and derivation table,
80
- `GammaEstimate.sufficient()`'s robust-gamma gating, `Cluster`'s
81
- constituent-coverage check, the five `audit()` checks and their causal
82
- correlation via `causedBy`, the conformance suite's five checks -- is a
83
- direct, faithful port of the same logic `vsl-core` implements in Python.
84
-
85
- ## The catalog
86
-
87
- The Drift Class / Stabilisation Operator / Legion detection-heuristic data
88
- (`catalog/drift_classes.json`, `catalog/legion_patterns.json`) is copied
89
- verbatim from `vsl-core`'s own OSS data files -- same license, same
90
- package, same author. `validate()` surfaces the same real data-quality
91
- findings the Python loader does (the `metadata.total_drift_classes`
92
- miscount, the `CLUSTER-HANDOVER` orphan, drift classes with zero Legion
93
- heuristics) rather than silently fixing them. As in Python: this catalog
94
- is explicitly not a finished, validated detection system -- call
95
- `onlyValidatedHeuristics()` if you want only the HIGH/MEDIUM-confidence
96
- subset.
97
-
98
- ## Install
99
-
100
- ```bash
101
- npm install @supersemantics/vsl-core
102
- ```
103
-
104
- ## Layout
105
-
106
- ```
107
- src/
108
- ├── exceptions.ts VSLError hierarchy
109
- ├── metrics.ts Delta, Gamma, GES, EEF, AssuranceBasis, F2Modification
110
- ├── identity.ts IdentityKey, ClusterKey, Instance, Evidence
111
- ├── constructs.ts PreNode, Invariant, Fallback, TerminalState, AllowedState
112
- ├── cluster.ts Cluster, ClusterPreNode
113
- ├── ledger.ts VerbaLedger, LedgerEntry, LedgerStore + 2 implementations
114
- ├── governance.ts GovernanceAuthority, HumanAuthorisedTransition, Specification
115
- ├── catalog/ Drift Class / Stabilisation Operator / Legion data + loader
116
- └── conformance/ VSLAdapter protocol, runConformanceSuite, reference adapter
117
- ```
118
-
119
- ## Status
120
-
121
- Alpha. 51 tests pass across every module, including a full round trip
122
- through the built `dist/` output (not just source via the test runner).
123
- Strict-mode TypeScript, 0 known vulnerabilities, zero runtime dependencies.
124
-
125
- ## License
126
-
127
- MIT -- see LICENSE. Copyright Super Semantics.
1
+ # @supersemantics/vsl-core
2
+
3
+ A TypeScript port of [`vsl-core`](https://github.com/supersemantics/VSL-Core) --
4
+ the Python original, and the canonical reference for the VSL (VERBA
5
+ Specification Language) governance vocabulary. This package exists so the
6
+ same primitives are available to Node/TypeScript agent frameworks
7
+ (LangGraph.js, LangChain.js, and others) without requiring a Python
8
+ runtime alongside them.
9
+
10
+ **Is:**
11
+ - A faithful port of `vsl-core`'s constructs -- `PreNode`, `Invariant`, `AssuranceBasis`, `GammaEstimate`, `VerbaLedger`, `Cluster`, the conformance suite, and the Drift Class / Stabilisation Operator catalog.
12
+ - Framework-agnostic and model-agnostic, same as the Python original -- this package never imports an agent-framework package or model-provider SDK, and never will.
13
+ - Zero runtime dependencies -- only Node built-ins (`node:crypto`, `node:fs`), same guarantee `vsl-core` makes for Python.
14
+
15
+ **Is not:**
16
+ - The reference implementation. When the Python and TypeScript versions disagree on a design question, `vsl-core`'s own README and source are the source of truth -- see it first if something here seems inconsistent with what you already know from the Python package.
17
+ - A byte-for-byte transliteration. A handful of things are deliberately adapted to TypeScript/Node rather than translated line-by-line -- see "Where this diverges from `vsl-core`" below. Every departure is a conscious design decision, documented in code and here, not an oversight.
18
+ - A framework adapter. This package ships no LangGraph.js, LangChain.js, or other framework integration. Those belong in separate `@supersemantics/vsl-<framework>` packages, the same separation `vsl-core`'s Python ecosystem already follows (`vsl-langgraph`, `vsl-langchain`, `vsl-maf`).
19
+
20
+ ## Quickstart: gate a tool call in 5 lines
21
+
22
+ ```
23
+ npm install @supersemantics/vsl-core
24
+ ```
25
+
26
+ Your agent has a tool, say `issueRefund`. You want a rule checked **before** the tool runs, and the
27
+ call stopped if the rule fails. That check is a gate:
28
+
29
+ ```javascript
30
+ import {
31
+ AssuranceBasis, F2Modification, Invariant, InvariantViolation, PlainJsReferenceAdapter,
32
+ } from "@supersemantics/vsl-core";
33
+
34
+ const withinCap = async (args) => args.amount <= 500;
35
+ const cap = new Invariant({ name: "refund-cap", description: "Refunds of $500 or less.", rule: withinCap,
36
+ assuranceBasis: new AssuranceBasis(true, F2Modification.NONE) });
37
+ const gate = new PlainJsReferenceAdapter().compileInvariant(cap);
38
+
39
+ async function refund(args) {
40
+ await gate(args); // throws InvariantViolation if the rule fails
41
+ return issueRefund(args); // only reached when it holds
42
+ }
43
+ ```
44
+
45
+ What each line does:
46
+
47
+ - `withinCap` is the rule: plain code that answers yes or no for this one call.
48
+ - `Invariant` gives the rule a name and says how strong the check is. It runs before the action
49
+ (`true`: F1) and changes nothing about what a model produces (`F2Modification.NONE`). That makes its
50
+ assurance level LOW: it blocks, but it doesn't steer a model. `vsl-core`'s README explains
51
+ [F1/F2](https://github.com/supersemantics/VSL-Core#the-f1f2-assurance-distinction-read-this-before-trusting-any-assurance-level).
52
+ - `compileInvariant` turns the rule into a gate: an async function that resolves when the rule holds
53
+ and throws when it doesn't. `PlainJsReferenceAdapter` is the adapter for plain JavaScript, with no
54
+ agent framework underneath.
55
+ - `await gate(args)` goes right before the tool. If it throws, the tool never runs.
56
+
57
+ `refund({ orderId: "A200", amount: 9000 })` throws `InvariantViolation` ("Invariant 'refund-cap'
58
+ violated") and no refund is issued. The whole file, ready to run, is
59
+ [`examples/quickstart.mjs`](https://github.com/supersemantics/VSL-Corejs/blob/HEAD/examples/quickstart.mjs).
60
+
61
+ **Keep a record of each decision.** The gate blocks on its own, but writes nothing down. To keep a
62
+ hash-chained record of every allow and deny, write it from the rule:
63
+
64
+ ```javascript
65
+ import { VerbaLedger } from "@supersemantics/vsl-core";
66
+
67
+ const ledger = new VerbaLedger(); // in memory; new VerbaLedger(new JsonlLedgerStore("decisions.jsonl")) for a file
68
+
69
+ const withinCap = async (args) => {
70
+ const allowed = args.amount <= 500;
71
+ await ledger.writeGateDecision("refund-agent", "refund-cap", { allowed });
72
+ return allowed;
73
+ };
74
+ ```
75
+
76
+ `await ledger.verifyIntegrity()` returns `true` while no entry has been changed.
77
+
78
+ **Using LangGraph.js?** [`@supersemantics/vsl-langgraph`](https://github.com/supersemantics/VSL-Langgraphjs)
79
+ compiles the same `Invariant` into a graph node. For a complete agent to start from, see the
80
+ [LangGraph.js starter](https://github.com/supersemantics/supersemantics-VSL-Starters/tree/main/langgraph-js).
81
+
82
+ ## Quick taste
83
+
84
+ ```typescript
85
+ import {
86
+ AssuranceBasis,
87
+ F2Modification,
88
+ GammaEstimate,
89
+ PreNode,
90
+ VerbaLedger,
91
+ } from "@supersemantics/vsl-core";
92
+
93
+ const preNode = new PreNode({
94
+ name: "refund-cap",
95
+ description: "Requires refund amount under the hard cap.",
96
+ monitor: async (candidateInput) => {
97
+ const amount = (candidateInput as { amount: number }).amount;
98
+ return new GammaEstimate({ gammaHat: amount <= 1000 ? 2.0 : 0.0 });
99
+ },
100
+ assuranceBasis: new AssuranceBasis(true, F2Modification.NONE),
101
+ });
102
+
103
+ const ledger = new VerbaLedger();
104
+ await ledger.writeMonitor("agent-1", false);
105
+ console.log(await ledger.verifyIntegrity()); // true
106
+ ```
107
+
108
+ `PreNode`/`Invariant` compile into a framework's own gate the same way they
109
+ do in Python -- via a `VSLAdapter` implementation. See
110
+ [`vsl_core.conformance.protocol.VSLAdapter`](https://github.com/supersemantics/VSL-Core#building-an-adapter)
111
+ in the Python README for what "conformant" actually means; the same
112
+ contract (`compilePreNode`/`compileInvariant`, verified by
113
+ `runConformanceSuite`) applies here.
114
+
115
+ ## Where this diverges from `vsl-core`
116
+
117
+ Two deliberate departures from the Python source, both documented at the
118
+ point they matter in code -- not silent translations, not oversights:
119
+
120
+ **`LedgerStore` is async here; it's synchronous in Python.** A store that
121
+ keeps entries over the network cannot be synchronous in JavaScript -- there
122
+ is no synchronous `fetch`.
123
+ Rather than port the synchronous interface and break it later, every
124
+ `LedgerStore` implementation here -- including `InMemoryLedgerStore` and
125
+ `JsonlLedgerStore`, neither of which strictly needs it -- is
126
+ `Promise`/`AsyncIterable`-based from the start.
127
+
128
+ **`JsonlLedgerStore`'s cross-process file locking is narrower than
129
+ Python's.** Python's version holds a real OS-level advisory lock
130
+ (`fcntl.flock`/`msvcrt.locking`) across its read-last-entry-then-write
131
+ critical section, closing the race between two separate store instances --
132
+ in one process or several -- writing to the same file. Node's standard
133
+ library has no equivalent cross-process locking primitive. This port only
134
+ serializes writers *within the same Node process*. It does **not** protect
135
+ against two separate Node processes (or two machines) appending to the
136
+ same file concurrently -- that can still corrupt the chain. This is
137
+ disclosed here and in `ledger.ts`'s own docstring, not silently narrowed.
138
+ Don't point multiple processes at the same `JsonlLedgerStore` file until
139
+ this gap is closed.
140
+
141
+ Everything else -- `AssuranceBasis`'s validation and derivation table,
142
+ `GammaEstimate.sufficient()`'s robust-gamma gating, `Cluster`'s
143
+ constituent-coverage check, the five `audit()` checks and their causal
144
+ correlation via `causedBy`, the conformance suite's five checks -- is a
145
+ direct, faithful port of the same logic `vsl-core` implements in Python.
146
+
147
+ ## The catalog
148
+
149
+ The Drift Class / Stabilisation Operator / Legion detection-heuristic data
150
+ (`catalog/drift_classes.json`, `catalog/legion_patterns.json`) is copied
151
+ verbatim from `vsl-core`'s own OSS data files -- same license, same
152
+ package, same author. `validate()` surfaces the same real data-quality
153
+ findings the Python loader does (the `metadata.total_drift_classes`
154
+ miscount, the `CLUSTER-HANDOVER` orphan, drift classes with zero Legion
155
+ heuristics) rather than silently fixing them. As in Python: this catalog
156
+ is explicitly not a finished, validated detection system -- call
157
+ `onlyValidatedHeuristics()` if you want only the HIGH/MEDIUM-confidence
158
+ subset.
159
+
160
+ ## Install
161
+
162
+ ```bash
163
+ npm install @supersemantics/vsl-core
164
+ ```
165
+
166
+ ## Layout
167
+
168
+ ```
169
+ src/
170
+ ├── exceptions.ts VSLError hierarchy
171
+ ├── metrics.ts Delta, Gamma, GES, EEF, AssuranceBasis, F2Modification
172
+ ├── identity.ts IdentityKey, ClusterKey, Instance, Evidence
173
+ ├── constructs.ts PreNode, Invariant, Fallback, TerminalState, AllowedState
174
+ ├── cluster.ts Cluster, ClusterPreNode
175
+ ├── ledger.ts VerbaLedger, LedgerEntry, LedgerStore + 2 implementations
176
+ ├── governance.ts GovernanceAuthority, HumanAuthorisedTransition, Specification
177
+ ├── catalog/ Drift Class / Stabilisation Operator / Legion data + loader
178
+ └── conformance/ VSLAdapter protocol, runConformanceSuite, reference adapter
179
+ ```
180
+
181
+ ## Status
182
+
183
+ Alpha. 51 tests pass across every module, including a full round trip
184
+ through the built `dist/` output (not just source via the test runner).
185
+ Strict-mode TypeScript, 0 known vulnerabilities, zero runtime dependencies.
186
+
187
+ ## License
188
+
189
+ MIT -- see LICENSE. Copyright Super Semantics.
package/package.json CHANGED
@@ -1,54 +1,54 @@
1
- {
2
- "name": "@supersemantics/vsl-core",
3
- "version": "0.2.2",
4
- "description": "Framework-agnostic and model-agnostic VSL (VERBA Specification Language) governance primitives -- TypeScript port of vsl-core.",
5
- "license": "MIT",
6
- "repository": {
7
- "type": "git",
8
- "url": "git+https://github.com/supersemantics/VSL-Corejs.git"
9
- },
10
- "homepage": "https://github.com/supersemantics/VSL-Corejs#readme",
11
- "bugs": {
12
- "url": "https://github.com/supersemantics/VSL-Corejs/issues"
13
- },
14
- "type": "module",
15
- "main": "./dist/cjs/index.js",
16
- "module": "./dist/index.js",
17
- "types": "./dist/index.d.ts",
18
- "exports": {
19
- ".": {
20
- "types": "./dist/index.d.ts",
21
- "import": "./dist/index.js",
22
- "require": "./dist/cjs/index.js"
23
- }
24
- },
25
- "files": [
26
- "dist"
27
- ],
28
- "engines": {
29
- "node": ">=18"
30
- },
31
- "scripts": {
32
- "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.cjs.json && node scripts/mark-cjs-dist.mjs",
33
- "prepare": "npm run build",
34
- "test": "vitest run",
35
- "test:watch": "vitest"
36
- },
37
- "devDependencies": {
38
- "@types/node": "^22.0.0",
39
- "@vitest/coverage-v8": "^4.1.11",
40
- "typescript": "^5.6.0",
41
- "vitest": "^4.1.11"
42
- },
43
- "keywords": [
44
- "governance",
45
- "ai-safety",
46
- "guardrails",
47
- "audit-log",
48
- "vsl",
49
- "verba"
50
- ],
51
- "publishConfig": {
52
- "access": "public"
53
- }
54
- }
1
+ {
2
+ "name": "@supersemantics/vsl-core",
3
+ "version": "0.2.4",
4
+ "description": "Framework-agnostic and model-agnostic VSL (VERBA Specification Language) governance primitives -- TypeScript port of vsl-core.",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/supersemantics/VSL-Corejs.git"
9
+ },
10
+ "homepage": "https://github.com/supersemantics/VSL-Corejs#readme",
11
+ "bugs": {
12
+ "url": "https://github.com/supersemantics/VSL-Corejs/issues"
13
+ },
14
+ "type": "module",
15
+ "main": "./dist/cjs/index.js",
16
+ "module": "./dist/index.js",
17
+ "types": "./dist/index.d.ts",
18
+ "exports": {
19
+ ".": {
20
+ "types": "./dist/index.d.ts",
21
+ "import": "./dist/index.js",
22
+ "require": "./dist/cjs/index.js"
23
+ }
24
+ },
25
+ "files": [
26
+ "dist"
27
+ ],
28
+ "engines": {
29
+ "node": ">=18"
30
+ },
31
+ "scripts": {
32
+ "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.cjs.json && node scripts/mark-cjs-dist.mjs",
33
+ "prepare": "npm run build",
34
+ "test": "vitest run",
35
+ "test:watch": "vitest"
36
+ },
37
+ "devDependencies": {
38
+ "@types/node": "^22.0.0",
39
+ "@vitest/coverage-v8": "^4.1.11",
40
+ "typescript": "^5.6.0",
41
+ "vitest": "^4.1.11"
42
+ },
43
+ "keywords": [
44
+ "governance",
45
+ "ai-safety",
46
+ "guardrails",
47
+ "audit-log",
48
+ "vsl",
49
+ "verba"
50
+ ],
51
+ "publishConfig": {
52
+ "access": "public"
53
+ }
54
+ }