@supersemantics/vsl-core 0.2.3 → 0.2.5

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/README.md CHANGED
@@ -17,6 +17,68 @@ runtime alongside them.
17
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
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
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
+
20
82
  ## Quick taste
21
83
 
22
84
  ```typescript
@@ -5,8 +5,8 @@
5
5
  * Port of vsl_core/ledger.py, with one deliberate design departure: the
6
6
  * LedgerStore interface here is async (Promise/AsyncIterable-returning),
7
7
  * where Python's is fully synchronous. This isn't a 1:1 translation
8
- * choice -- it's forward-looking: a future HTTP-backed RemoteLedgerStore
9
- * for this package cannot be synchronous in JS (there is no synchronous
8
+ * choice -- it's forward-looking: any LedgerStore that does network or
9
+ * database I/O cannot be synchronous in JS (there is no synchronous
10
10
  * fetch), so making every LedgerStore implementation async from the start
11
11
  * -- including the in-memory/file ones below, even though neither strictly
12
12
  * needs it -- keeps the interface uniform rather than breaking it later.
package/dist/ledger.d.ts CHANGED
@@ -4,8 +4,8 @@
4
4
  * Port of vsl_core/ledger.py, with one deliberate design departure: the
5
5
  * LedgerStore interface here is async (Promise/AsyncIterable-returning),
6
6
  * where Python's is fully synchronous. This isn't a 1:1 translation
7
- * choice -- it's forward-looking: a future HTTP-backed RemoteLedgerStore
8
- * for this package cannot be synchronous in JS (there is no synchronous
7
+ * choice -- it's forward-looking: any LedgerStore that does network or
8
+ * database I/O cannot be synchronous in JS (there is no synchronous
9
9
  * fetch), so making every LedgerStore implementation async from the start
10
10
  * -- including the in-memory/file ones below, even though neither strictly
11
11
  * needs it -- keeps the interface uniform rather than breaking it later.
package/dist/ledger.js CHANGED
@@ -4,8 +4,8 @@
4
4
  * Port of vsl_core/ledger.py, with one deliberate design departure: the
5
5
  * LedgerStore interface here is async (Promise/AsyncIterable-returning),
6
6
  * where Python's is fully synchronous. This isn't a 1:1 translation
7
- * choice -- it's forward-looking: a future HTTP-backed RemoteLedgerStore
8
- * for this package cannot be synchronous in JS (there is no synchronous
7
+ * choice -- it's forward-looking: any LedgerStore that does network or
8
+ * database I/O cannot be synchronous in JS (there is no synchronous
9
9
  * fetch), so making every LedgerStore implementation async from the start
10
10
  * -- including the in-memory/file ones below, even though neither strictly
11
11
  * needs it -- keeps the interface uniform rather than breaking it later.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@supersemantics/vsl-core",
3
- "version": "0.2.3",
3
+ "version": "0.2.5",
4
4
  "description": "Framework-agnostic and model-agnostic VSL (VERBA Specification Language) governance primitives -- TypeScript port of vsl-core.",
5
5
  "license": "MIT",
6
6
  "repository": {