@niscorp/vex 0.1.0 → 0.1.1
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/CHANGELOG.md +7 -0
- package/DESIGN.md +48 -31
- package/DOCS.md +250 -55
- package/README.md +10 -7
- package/dist/adapters/express/index.cjs +1 -1
- package/dist/adapters/express/index.cjs.map +1 -1
- package/dist/adapters/express/index.js +1 -1
- package/dist/adapters/hono/index.cjs +1 -1
- package/dist/adapters/hono/index.cjs.map +1 -1
- package/dist/adapters/hono/index.js +1 -1
- package/dist/{chunk-FPKW4TRX.js → chunk-5CBKESBJ.js} +3 -3
- package/dist/chunk-5CBKESBJ.js.map +1 -0
- package/dist/index.cjs +1 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +2 -2
- package/package.json +7 -7
- package/dist/chunk-FPKW4TRX.js.map +0 -1
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# @niscorp/vex
|
|
2
|
+
|
|
3
|
+
## 0.1.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- 45d6731: `DELETE` on an unlocked fingerprint endpoint refuses a protected mutation entry with 409 `fingerprint_protected`, as it already did a protected read. A seeded write could be evicted by anyone who could reach the endpoint. A locked endpoint (every endpoint moss serves) was never affected.
|
package/DESIGN.md
CHANGED
|
@@ -27,8 +27,9 @@ execute.
|
|
|
27
27
|
LLM code. Natural-language→DSL and rows→shape are two optional function
|
|
28
28
|
hooks (`generateDsl`, `mapToShape`). With them, Vex answers free-form
|
|
29
29
|
requests. Without them, it is a deterministic DSL compiler + executor + cache
|
|
30
|
-
that still serves any already-cached shape. Cortex
|
|
31
|
-
peer
|
|
30
|
+
that still serves any already-cached shape. Cortex (and Signal behind it) is
|
|
31
|
+
an optional peer dependency, not a hard one; Prism is required, because a
|
|
32
|
+
stored mapping is Prism IR and the engine executes it.
|
|
32
33
|
3. **Shape-only caching.** The positive cache key is a hash of the request's
|
|
33
34
|
*shape* with all values replaced by type tokens. Two requests with the same
|
|
34
35
|
structure but different values share a cache entry. Intent is deliberately
|
|
@@ -53,13 +54,14 @@ execute.
|
|
|
53
54
|
|
|
54
55
|
```
|
|
55
56
|
┌──────────────────────────────────────┐
|
|
56
|
-
QueryRequest │ { intent?, shape
|
|
57
|
-
|
|
57
|
+
QueryRequest │ { fingerprint?, intent?, shape?, │
|
|
58
|
+
│ context } │
|
|
59
|
+
+ ExecuteOptions │ options: { scope?, entities?, locked?}│
|
|
58
60
|
└────────────────┬─────────────────────┘
|
|
59
61
|
↓
|
|
60
62
|
┌──────────────────────────────────────┐
|
|
61
63
|
│ Validate (Zod) + hash │
|
|
62
|
-
│
|
|
64
|
+
│ fingerprint (positive key) │
|
|
63
65
|
│ requestHash (negative key / single- │
|
|
64
66
|
│ flight) │
|
|
65
67
|
└────────────────┬─────────────────────┘
|
|
@@ -68,7 +70,8 @@ execute.
|
|
|
68
70
|
│ Cache read │
|
|
69
71
|
│ positive HIT → cached DSL (+ Prism IR)│
|
|
70
72
|
│ negative HIT → throw unsatisfiable │
|
|
71
|
-
│
|
|
73
|
+
│ fingerprint alone, unknown → throw │
|
|
74
|
+
│ cache_miss │
|
|
72
75
|
└────────────────┬─────────────────────┘
|
|
73
76
|
miss ↓ ↑ hit (skip generation)
|
|
74
77
|
┌──────────────────────────────────────┐
|
|
@@ -127,7 +130,8 @@ A constrained JSON structure (`schemas/`) that can only express safe, valid
|
|
|
127
130
|
queries. Top level (`QuerySchema`):
|
|
128
131
|
|
|
129
132
|
- `from` — array of entity names or `{ as, query }` subqueries (min 1).
|
|
130
|
-
- `fields` — array of `entity.field` paths
|
|
133
|
+
- `fields` — array of `entity.field` paths or `{ field, as }` (no `SELECT *`;
|
|
134
|
+
optional when `aggregate` is present — a query needs at least one of the two).
|
|
131
135
|
- `filter` — a recursive `FilterSchema` union.
|
|
132
136
|
- `compute` — record of `alias → ComputeExpression` (arithmetic, `concat`,
|
|
133
137
|
`coalesce`, `case`).
|
|
@@ -217,12 +221,14 @@ Identity is the **fingerprint** (see Cache v2 below). The supporting hashes:
|
|
|
217
221
|
a mismatch means the cached DSL may reference changed columns, so the entry is
|
|
218
222
|
treated as a miss and evicted. Stable across restarts so warm-up entries
|
|
219
223
|
aren't wrongly discarded.
|
|
220
|
-
- **Entry kinds.** A discriminated union: `ok` (DSL + optional Prism IR)
|
|
224
|
+
- **Entry kinds.** A discriminated union: `ok` (DSL + optional Prism IR),
|
|
225
|
+
`mutation` (a dev-authored write — see Mutations) and
|
|
221
226
|
`unsatisfiable` (a TTL'd negative result — a request the agent declared
|
|
222
227
|
impossible, so it isn't re-run until the TTL lapses or the schema changes).
|
|
223
228
|
- **Backends.** In-memory (`createMemoryCache`), durable Postgres
|
|
224
229
|
(`createPostgresCache`, jsonb table, server-side TTL, `protected`/
|
|
225
|
-
`last_used_at`/`request_hash` columns
|
|
230
|
+
`last_used_at`/`request_hash` columns; the table is a strata sequence,
|
|
231
|
+
`nisc.vex.cache`, applied once through the ledger by `init()`;
|
|
226
232
|
validate-on-write and evict-on-read), and tiered (`createTieredCache`, L1 +
|
|
227
233
|
L2 read-through/write-through with `full`/`lazy`/`partial` warm-up). Every
|
|
228
234
|
backend implements the same `CacheBackend` contract; `init`/`entries` are
|
|
@@ -520,9 +526,10 @@ exported from the `@niscorp/vex/agent` subpath — `createQueryDsl` (fills
|
|
|
520
526
|
|
|
521
527
|
- The **query agent** (`vexQueryDslAgent`, id `vex.query`) is a structured-output
|
|
522
528
|
Cortex agent over `QuerySchema` with six tools — `getSchema`, `getSampleRows`,
|
|
523
|
-
`getDistinctValues`, `describeField`, `testQuery`, `cannotSatisfy` — and
|
|
524
|
-
|
|
525
|
-
|
|
529
|
+
`getDistinctValues`, `describeField`, `testQuery`, `cannotSatisfy` — and three
|
|
530
|
+
stop conditions (`stepCount(20)`, `outputRetries(3)`, `repeatedCalls(2)`);
|
|
531
|
+
`createQueryDsl` aborts the run when `cannotSatisfy` is called. Context
|
|
532
|
+
producers inject the live schema, the caller line and the DSL JSON Schema so the
|
|
526
533
|
static instructions stay stable. Every data-touching tool is a DSL run through
|
|
527
534
|
`caller.read`; the tool set holds no adapter and no SQL.
|
|
528
535
|
`createQueryDsl` wraps it into the `generateDsl` hook.
|
|
@@ -533,9 +540,10 @@ exported from the `@niscorp/vex/agent` subpath — `createQueryDsl` (fills
|
|
|
533
540
|
that envelope (the identity, with no model call, when the rows already fit).
|
|
534
541
|
|
|
535
542
|
> The reference agents are a separate concern from the deterministic core: they
|
|
536
|
-
> live behind the `@niscorp/vex/agent` subpath, so `@niscorp/cortex
|
|
537
|
-
> `@niscorp/signal
|
|
538
|
-
> The engine itself depends on
|
|
543
|
+
> live behind the `@niscorp/vex/agent` subpath, so `@niscorp/cortex` (and
|
|
544
|
+
> `@niscorp/signal` behind it) is pulled in only when you import it.
|
|
545
|
+
> The engine itself depends on neither — it needs `@niscorp/prism` only to
|
|
546
|
+
> execute a stored mapping. Provide your own
|
|
539
547
|
> `generateDsl`/`mapToShape`, or use the reference factories.
|
|
540
548
|
|
|
541
549
|
### HTTP layer (optional)
|
|
@@ -549,8 +557,9 @@ few lines:
|
|
|
549
557
|
`handleQuery` parses a body, runs `engine.execute`, and maps `VexError`s to
|
|
550
558
|
HTTP status codes.
|
|
551
559
|
- `@niscorp/vex/hono` and `@niscorp/vex/express` wrap that handler: `GET`
|
|
552
|
-
returns discovery, `POST` runs a query
|
|
553
|
-
|
|
560
|
+
returns discovery, `POST` runs a query or replays a write, `PATCH`/`DELETE`
|
|
561
|
+
manage fingerprints, and scope is resolved per-request via a `getScope`
|
|
562
|
+
callback.
|
|
554
563
|
|
|
555
564
|
### Events
|
|
556
565
|
|
|
@@ -571,6 +580,7 @@ src/
|
|
|
571
580
|
errors.ts VexError (code + details)
|
|
572
581
|
events.ts VexEvent union, VexEventHandler
|
|
573
582
|
handler.ts Framework-agnostic discovery + query handlers
|
|
583
|
+
guide.ts vexGuide — the agent-facing contract text
|
|
574
584
|
|
|
575
585
|
schemas/
|
|
576
586
|
query.schema.ts QuerySchema (top-level DSL) + Source, SortEntry
|
|
@@ -578,20 +588,23 @@ src/
|
|
|
578
588
|
compute.schema.ts ComputeExpressionSchema
|
|
579
589
|
aggregate.schema.ts AggregateExpressionSchema
|
|
580
590
|
value.schema.ts FieldOrValue, ContextRef ($context), ScopeRef ($scope)
|
|
591
|
+
identifier.schema.ts the name grammar: field paths and identifiers
|
|
581
592
|
database.schema.ts DatabaseSchema, EntitySchema, FieldSchema, ...
|
|
582
593
|
request.schema.ts QueryRequestSchema, QueryResponse, error codes
|
|
583
594
|
index.ts Barrel
|
|
584
595
|
|
|
585
596
|
scope/
|
|
586
597
|
discover.ts discoverEntities(dsl)
|
|
587
|
-
apply.ts
|
|
588
|
-
|
|
598
|
+
apply.ts checkScope, scopeResolved, applyScope, VexScopeError
|
|
599
|
+
grants.ts createScopePolicy, mergeScopePolicies, scopeGrants, scopeProfiles, scopeBindings
|
|
600
|
+
scope.types.ts ScopePolicy, ScopeEntityRule, ScopeMatch, ScopeSet
|
|
589
601
|
|
|
590
602
|
engine/
|
|
591
603
|
runtime.ts createQueryEngine — orchestration + cache + single-flight
|
|
592
604
|
resolver.ts resolve(dsl, schema) → ResolvedQuery
|
|
593
605
|
analyzer.ts analyze(resolved, config) → { warnings, errors }
|
|
594
606
|
executor.ts executeQuery, buildContextContract, findMissingContext
|
|
607
|
+
optional.ts pruneOptional, presenceOf — optional conditions
|
|
595
608
|
live.ts createLiveRows — the rows cache and follows behind refresh: 'reactive'
|
|
596
609
|
engine.types.ts ResolvedQuery and friends, AnalysisConfig, TestResult
|
|
597
610
|
|
|
@@ -602,35 +615,37 @@ src/
|
|
|
602
615
|
introspect.ts schema discovery from pg_catalog
|
|
603
616
|
compile.ts ResolvedQuery → parameterized SQL
|
|
604
617
|
operators.ts per-operator SQL generation
|
|
618
|
+
statement-timeout.ts how a read's time limit is enforced
|
|
619
|
+
pglite/index.ts createPglitePool (@niscorp/vex/pglite)
|
|
605
620
|
hono/index.ts vex() Hono app (@niscorp/vex/hono)
|
|
606
621
|
express/index.ts vex() Express handler (@niscorp/vex/express)
|
|
607
622
|
index.ts adapter barrel
|
|
608
623
|
|
|
609
624
|
mutations/
|
|
610
625
|
schema.ts MutationSchema (closed grammar), MutationDefinitionSchema
|
|
611
|
-
engine.ts executeMutation — desugar/scope/validate/compile/execute
|
|
626
|
+
engine.ts executeWrites, executeMutation — desugar/scope/validate/compile/execute
|
|
612
627
|
signature.ts collectMutationContext, collectQueryContext, mutationEffect, lintMutation
|
|
613
628
|
index.ts Barrel
|
|
614
629
|
|
|
615
630
|
cache/
|
|
616
631
|
cache.types.ts CacheBackend, CacheEntry (ok | mutation | unsatisfiable)
|
|
617
|
-
hash.ts
|
|
632
|
+
hash.ts normalizeShape, computeRequestHash, computeSchemaFingerprint, mintFingerprint
|
|
618
633
|
memory.ts createMemoryCache (L1)
|
|
619
634
|
postgres.ts createPostgresCache (L2, durable)
|
|
620
635
|
tiered.ts createTieredCache (L1 + L2, warm-up)
|
|
621
636
|
validate.ts validateEntry
|
|
622
|
-
|
|
637
|
+
seed.ts seedCache, SeedEntry, SeedMutation
|
|
638
|
+
util.ts isEntryFresh, fireAndForget, sweepCache
|
|
623
639
|
index.ts Barrel
|
|
624
640
|
|
|
625
641
|
agent/ Reference Cortex agents (exported via ./agent)
|
|
626
642
|
query.agent.ts defineAgent: vexQueryDslAgent (vex.query → Query)
|
|
627
643
|
tools.ts the six query tools
|
|
628
|
-
rules.ts tool-limit + unsatisfiable rules
|
|
629
|
-
producers.ts schema + DSL-spec context producers
|
|
630
644
|
index.ts createQueryDsl, createShapeMapper, vexQueryDslAgent
|
|
631
645
|
|
|
632
646
|
utils/
|
|
633
647
|
context.ts buildValidationContext, resolveParams
|
|
648
|
+
canonical.ts canonical JSON text + hash
|
|
634
649
|
|
|
635
650
|
scripts/ Dev-only: docker, seed, dev server, fixtures
|
|
636
651
|
```
|
|
@@ -645,11 +660,13 @@ scripts/ Dev-only: docker, seed, dev server, fixtures
|
|
|
645
660
|
| `pg` | peer (optional) | Postgres adapter and Postgres cache backend |
|
|
646
661
|
| `hono` | peer (optional) | Hono framework adapter |
|
|
647
662
|
| `express` | peer (optional) | Express framework adapter |
|
|
648
|
-
| `@niscorp/cortex` | peer (optional) | Reference query agent (`defineAgent`/`defineTool
|
|
649
|
-
| `@niscorp/signal` |
|
|
650
|
-
| `@niscorp/prism` | peer (
|
|
663
|
+
| `@niscorp/cortex` | peer (optional) | Reference query agent (`defineAgent`/`defineTool`, standalone runtime) |
|
|
664
|
+
| `@niscorp/signal` | via Cortex (its peer) | LLM calls + embeddings |
|
|
665
|
+
| `@niscorp/prism` | peer (required) | Result mapping (IR compile/execute; `mappingAgent` for the reference mapper) |
|
|
666
|
+
| `@niscorp/strata` | peer (required) | The Postgres cache table's sequence and ledger; request depth guard |
|
|
651
667
|
|
|
652
|
-
|
|
668
|
+
`zod`, `@niscorp/prism` and `@niscorp/strata` are mandatory. Everything else is
|
|
669
|
+
pulled in only by the path you use.
|
|
653
670
|
|
|
654
671
|
---
|
|
655
672
|
|
|
@@ -681,7 +698,7 @@ Only `zod` is mandatory. Everything else is pulled in only by the path you use.
|
|
|
681
698
|
|
|
682
699
|
2. **The LLM is injected, not embedded.** Making `generateDsl`/`mapToShape`
|
|
683
700
|
plain hooks keeps the engine deterministic and testable without a model,
|
|
684
|
-
lets the heavy Cortex/Signal
|
|
701
|
+
lets the heavy Cortex/Signal stack stay optional, and lets a consumer
|
|
685
702
|
swap in their own generator. The bundled Cortex agents are a reference, not a
|
|
686
703
|
requirement.
|
|
687
704
|
|
|
@@ -776,8 +793,8 @@ Only `zod` is mandatory. Everything else is pulled in only by the path you use.
|
|
|
776
793
|
request possible.
|
|
777
794
|
|
|
778
795
|
6. **Single-flight on the default path.** A burst of identical cache misses
|
|
779
|
-
collapses to one generation; the rest await it. `refresh`/`bypass`
|
|
780
|
-
|
|
796
|
+
collapses to one generation; the rest await it. (The `refresh`/`bypass`
|
|
797
|
+
cache modes that opted out died with v1 — see *Cache v2*.)
|
|
781
798
|
|
|
782
799
|
7. **Adapters own compilation.** The DSL and agent loop are database-agnostic;
|
|
783
800
|
only SQL generation is not. Keeping the entire compile step inside the
|