@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 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/Signal/Prism are optional
31
- peer dependencies, not hard ones.
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, context } │
57
- + ExecuteOptions │ options: { scope?, cache?, entities?} │
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
- │ shapeHash (positive key) │
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
- │ miss + mode 'only' → throw cache_miss │
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 (min 1; **required** — no `SELECT *`).
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) and
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 with idempotent ALTER migrations,
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 two
524
- rules: a tool-call limiter (nudge at 8, abort at 10) and an unsatisfiable
525
- abort. Context producers inject the live schema and the DSL JSON Schema so the
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`, and `@niscorp/prism` are pulled in only when you import it.
538
- > The engine itself depends on none of them — provide your own
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, scope is resolved per-request via a
553
- `getScope` callback, and the `cache` query param selects the cache mode.
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 applyScope(dsl, entities, policy), VexScopeError
588
- scope.types.ts ScopePolicy, ScopeEntityRule, ScopeFilterRule
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 computeShapeHash, computeRequestHash, computeSchemaFingerprint
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
- util.ts isEntryFresh, fireAndForget
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`/`defineRule`, standalone runtime) |
649
- | `@niscorp/signal` | peer (optional) | LLM calls + embeddings, via Cortex |
650
- | `@niscorp/prism` | peer (optional) | Result mapping (`mappingAgent`, IR compile/execute) |
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
- Only `zod` is mandatory. Everything else is pulled in only by the path you use.
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/Prism stack stay optional, and lets a consumer
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` opt out,
780
- since they explicitly mean "don't share cache state."
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