@supersemantics/vsl-core 0.0.0-stage → 0.2.3
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/LICENSE +21 -0
- package/README.md +126 -2
- package/dist/catalog/drift_classes.data.d.ts +772 -0
- package/dist/catalog/drift_classes.data.d.ts.map +1 -0
- package/dist/catalog/drift_classes.data.js +1044 -0
- package/dist/catalog/drift_classes.data.js.map +1 -0
- package/dist/catalog/legion_patterns.data.d.ts +1332 -0
- package/dist/catalog/legion_patterns.data.d.ts.map +1 -0
- package/dist/catalog/legion_patterns.data.js +2293 -0
- package/dist/catalog/legion_patterns.data.js.map +1 -0
- package/dist/catalog/loader.d.ts +139 -0
- package/dist/catalog/loader.d.ts.map +1 -0
- package/dist/catalog/loader.js +321 -0
- package/dist/catalog/loader.js.map +1 -0
- package/dist/cjs/catalog/drift_classes.data.js +1046 -0
- package/dist/cjs/catalog/legion_patterns.data.js +2295 -0
- package/dist/cjs/catalog/loader.js +337 -0
- package/dist/cjs/cluster.js +102 -0
- package/dist/cjs/conformance/protocol.js +6 -0
- package/dist/cjs/conformance/reference_adapter.js +45 -0
- package/dist/cjs/conformance/suite.js +220 -0
- package/dist/cjs/constructs.js +180 -0
- package/dist/cjs/exceptions.js +127 -0
- package/dist/cjs/governance.js +210 -0
- package/dist/cjs/identity.js +163 -0
- package/dist/cjs/index.js +61 -0
- package/dist/cjs/ledger.js +775 -0
- package/dist/cjs/metrics.js +339 -0
- package/dist/cjs/package.json +3 -0
- package/dist/cjs/rules_version.js +22 -0
- package/dist/cluster.d.ts +82 -0
- package/dist/cluster.d.ts.map +1 -0
- package/dist/cluster.js +97 -0
- package/dist/cluster.js.map +1 -0
- package/dist/conformance/protocol.d.ts +22 -0
- package/dist/conformance/protocol.d.ts.map +1 -0
- package/dist/conformance/protocol.js +6 -0
- package/dist/conformance/protocol.js.map +1 -0
- package/dist/conformance/reference_adapter.d.ts +16 -0
- package/dist/conformance/reference_adapter.d.ts.map +1 -0
- package/dist/conformance/reference_adapter.js +42 -0
- package/dist/conformance/reference_adapter.js.map +1 -0
- package/dist/conformance/suite.d.ts +20 -0
- package/dist/conformance/suite.d.ts.map +1 -0
- package/dist/conformance/suite.js +218 -0
- package/dist/conformance/suite.js.map +1 -0
- package/dist/constructs.d.ts +158 -0
- package/dist/constructs.d.ts.map +1 -0
- package/dist/constructs.js +170 -0
- package/dist/constructs.js.map +1 -0
- package/dist/exceptions.d.ts +97 -0
- package/dist/exceptions.d.ts.map +1 -0
- package/dist/exceptions.js +119 -0
- package/dist/exceptions.js.map +1 -0
- package/dist/governance.d.ts +160 -0
- package/dist/governance.d.ts.map +1 -0
- package/dist/governance.js +202 -0
- package/dist/governance.js.map +1 -0
- package/dist/identity.d.ts +120 -0
- package/dist/identity.d.ts.map +1 -0
- package/dist/identity.js +157 -0
- package/dist/identity.js.map +1 -0
- package/dist/index.d.ts +23 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +23 -0
- package/dist/index.js.map +1 -0
- package/dist/ledger.d.ts +340 -0
- package/dist/ledger.d.ts.map +1 -0
- package/dist/ledger.js +733 -0
- package/dist/ledger.js.map +1 -0
- package/dist/metrics.d.ts +260 -0
- package/dist/metrics.d.ts.map +1 -0
- package/dist/metrics.js +330 -0
- package/dist/metrics.js.map +1 -0
- package/dist/rules_version.d.ts +20 -0
- package/dist/rules_version.d.ts.map +1 -0
- package/dist/rules_version.js +20 -0
- package/dist/rules_version.js.map +1 -0
- package/package.json +52 -4
package/LICENSE
ADDED
|
@@ -0,0 +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.
|
package/README.md
CHANGED
|
@@ -1,3 +1,127 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @supersemantics/vsl-core
|
|
2
2
|
|
|
3
|
-
|
|
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.
|