graphddb 0.6.0 → 0.7.1

package/docs/cqrs-contract.md

@@ -393,7 +393,7 @@ input produces a byte-identical pre-contract document).
 
 ```jsonc
 {
-  "version": "1.0",
+  "version": "1.1",
   "contracts": {
     // point query: single OR array (array → BatchGetItem)
     "ArticleById": {

package/docs/design-patterns.md

@@ -180,13 +180,15 @@ BatchGet, so a `refs` read's `select` cannot push a server-side `FilterExpressio
 on the children (BatchGet has none); filter on the returned `items` if needed.
 
 > **Runtime scope.** A `refs` read fans a **parent-row list attribute** out into a
-> BatchGet. The static operations spec (`operations.json`) and the generated Python
-> runtime bind relation keys from a single scalar `{result.<field>}` and have no
-> parent-list key-fan-out primitive, so a `refs` relation is resolvable **only**
-> through the TS in-process runtime. Compiling a select that traverses a `refs`
-> relation to `operations.json` / generated Python **fails loudly** (rather than
-> emitting a physically wrong scalar-key BatchGet); resolve it in the generated-code
-> consumer with a separate BatchGet if you need it there.
+> BatchGet. Since issue #208 (spec version 1.1) the shared operation IR carries this
+> as a first-class **binding form** (`sourceList` on a `BatchGetItem` op), so a
+> select that traverses a `refs` relation compiles to `operations.json` and the
+> generated Python runtime resolves it with the same semantics as the TS in-process
+> runtime (first-seen order, dedup, dangling refs dropped, `cursor: null`; the
+> parent list attribute is projected implicitly and stripped from the result when
+> unselected). One remaining spec-path difference: a client-side `filter` on a
+> `refs` select is TS-in-process-only and is rejected loudly by the spec compiler
+> (never silently dropped).
 
 ---
 

package/docs/prepared-statements.md

@@ -0,0 +1,232 @@
+# GraphDDB Prepared Statements
+
+`DDBModel.prepare($ => ({...}))` → `.execute(params)` is the read/write-unified
+**prepared statement**: a declarative route body is compiled **once**, and each
+`execute(params)` binds the per-call values into the precompiled plan and runs
+it through the **same execution cores** `DDBModel.mutate` / `Model.query` /
+`Model.list` and the public CQRS contracts use — effects are identical by
+construction (design #203, runtime #205, compile-time transform #206, static
+AOT plans #208).
+
+## The three execution layers (orthogonal, pick per use)
+
+| Use | API |
+|---|---|
+| ad-hoc one-shot | `DDBModel.mutate({...})` / `Model.query(...)` / `Model.list(...)` — recompiles per call |
+| repeated hot path (prepared statement) | `DDBModel.prepare($ => ({...}))` → `.execute(params)` |
+| public CQRS contract | `publicCommandModel({...})` / `publicQueryModel({...})` |
+
+`prepare` is the missing middle: **precompiled without the contract ceremony**.
+
+```ts
+// write
+const createPost = DDBModel.prepare(($) => ({
+  post: { create: () => Post, key: { threadId: $.threadId, postId: $.postId }, input: { body: $.body } },
+}));
+await createPost.execute({ threadId, postId, body });
+
+// read — symmetric; only the key values (+ limit/cursor/consistentRead) are dynamic
+const userById = DDBModel.prepare(($) => ({
+  user: { query: () => User, key: { userId: $.userId }, select: { userId: true, name: true } },
+}));
+await userById.execute({ userId });
+```
+
+## The key constraint: no runtime capture
+
+A prepared body must be **pure-declarative**: it may reference only
+
+- `$.<name>` — per-call values, bound at `execute`;
+- **module-static** references — imports, module-scope `const` / `class` /
+  `enum`, the `() => Model` model refs, shared `const` select templates;
+- static literals (string / number / boolean / bigint / `null`).
+
+Capturing a per-call runtime value into the body — an enclosing function's
+parameter or `let`, `p.foo`, `this`, mutable module state, any helper **call**
+(the indirect-capture channel; even `Date.now()` is a fresh per-call value) —
+breaks preparability and is rejected **loudly**:
+
+- **at build time** by the static lint (`graphddb transform prepared`, below) —
+  the primary, phase-2 enforcement, including indirect capture via same-file
+  helper constants (transitively verified);
+- **at runtime** by the phase-1 guard (`assertNoRuntimeCapture` and the
+  recording `$` proxy) as a backstop for what a per-file syntactic pass cannot
+  see (cross-module mutable state, mutated template objects).
+
+## Zero overhead vs. fallback: the compile-time transform
+
+**With the transform applied, prepared statements are zero-overhead per
+operation regardless of where you write them. Without it, they still behave
+identically — they just pay a small per-call memoization cost.** That is the
+whole contract:
+
+| Build | Per-op cost of an inline `prepare(fn).execute()` | Result |
+|---|---|---|
+| **AOT** (`graphddb transform prepared --aot <artifact> --write`, #208) | **zero compilation at runtime, including the first call** — the plan was compiled at BUILD time into a static artifact; the call site loads it and every call binds params into the frozen plan | identical |
+| **transform applied** (`graphddb transform prepared --write`) | zero per-op after the FIRST call (the lazy slot compiles once per module at first use) | identical |
+| **no transform** (fallback) | phase-1 **structural memoization**: the body is re-evaluated and structure-hashed per call, then the compiled handle is reused from a bounded LRU (no recompile) | identical |
+| hand-hoisted module-level `const stmt = DDBModel.prepare(...)` | compile once at first use (runtime); the transform leaves it untouched | identical |
+
+The transform exists to remove the placement footgun: without it, an inline
+`prepare` is *correct but warmer* than a module-level one (silent-slow). With
+it, both spellings compile to the same optimal form.
+
+### The three optimization tiers — when to use which
+
+1. **AOT static plans** (`--aot`, #208) — production builds with a build step.
+   Plan construction happens at BUILD time: cold starts (Lambda SnapStart,
+   first request) pay **zero** compilation, and a broken plan fails the
+   **build**, not the first request. Requires committing the generated
+   artifact module and running the drift check in CI (below).
+2. **Lazy slot + structural memoization** (`--write`, #206 / #205) — dev runs,
+   `tsx`/`ts-node` no-build-step deployments, and every call site the AOT pass
+   did not rewrite (e.g. `prepare` calls inside `node_modules`). The plan
+   compiles at runtime, once.
+3. **Ad-hoc `mutate` / `query`** — one-shot operations where preparing buys
+   nothing (recompiles per call, by design).
+
+The runtime structural-memoization cache is deliberately **kept** even when AOT
+is applied: untransformed builds and third-party `prepare` call sites fall back
+to it with identical behavior (perf only differs), so a build without the
+transform can never become silently per-call-slow.
+
+## True build-time compilation: `--aot` static plans (#208)
+
+```bash
+# compile every verified prepare body at BUILD time, write the static plan
+# artifact module, and rewrite call sites to load it
+graphddb transform prepared --src src/ --aot src/graphddb.prepared.ts --write
+
+# CI drift gate: recompile and compare — exits 1 when model declarations (or
+# prepare bodies) changed without regenerating the artifact
+graphddb transform prepared --src src/ --aot src/graphddb.prepared.ts
+```
+
+The rewrite keeps the body **in source** — it is the plan's compile source, the
+type source, and the untransformed-build fallback; at runtime the loader never
+evaluates it:
+
+```ts
+// after `--aot src/graphddb.prepared.ts --write`
+import { loadPreparedPlan as __gddbLoadPreparedPlan } from 'graphddb';
+import __gddbPreparedPlans from './graphddb.prepared.js';
+let __gddbPrepared1;
+export async function getUser(userId: string) {
+  return (__gddbPrepared1 ??= __gddbLoadPreparedPlan(__gddbPreparedPlans, 'src/app.ts#1', ($) => ({
+    u: { query: () => User, key: { userId: $.userId }, select: USER_SELECT },
+  }))).execute({ userId });
+}
+```
+
+What the artifact carries (the same serialized-IR vocabulary `operations.json`
+uses — templated key conditions / transaction items, model references by
+**entity name**):
+
+- a **write** plan freezes the whole mutation compile — lifecycle resolution
+  and every derived effect (edges, counters, uniqueness guards, outbox,
+  idempotency, maintenance writes, referential ConditionChecks) — into one
+  declarative `TransactionSpec` per op;
+- a **read** plan carries the analyzed route (entity, select template, param
+  binds, options) plus its physical `QuerySpec`, so a broken read plan fails
+  the build.
+
+**Stale plans never execute.** Each plan records a fingerprint of every entity
+declaration it touches; the loader recomputes them against the live
+`MetadataRegistry` on first use and rejects loudly on any mismatch (model /
+table-mapping drift since generation), version skew, or a missing plan id — in
+addition to the CI drift gate above.
+
+### CLI
+
+```bash
+# build lint (CI gate): verify no-runtime-capture, report hoistable inline
+# call sites as notes; exit 1 on violations
+graphddb transform prepared --src src/
+
+# apply: rewrite verified inline call sites in place (idempotent)
+graphddb transform prepared --src src/ --write
+```
+
+The rewrite normalizes each inline call site to a module-scope **lazy slot**:
+
+```ts
+// before (inline, per-call structural memoization)
+export async function getUser(userId: string) {
+  return DDBModel.prepare(($) => ({
+    u: { query: () => User, key: { userId: $.userId }, select: USER_SELECT },
+  })).execute({ userId });
+}
+
+// after `graphddb transform prepared --write`
+let __gddbPrepared1;
+export async function getUser(userId: string) {
+  return (__gddbPrepared1 ??= DDBModel.prepare(($) => ({
+    u: { query: () => User, key: { userId: $.userId }, select: USER_SELECT },
+  }))).execute({ userId });
+}
+```
+
+The body stays lexically in place (every reference resolves exactly as
+before — no TDZ / module-init-order hazards with models declared later in the
+file), the plan compiles once per module at first use, and every later call is
+a single nullish check straight into `.execute`. Files containing any
+violation are **never rewritten** — the build fails loudly instead.
+
+A file is scanned when it contains a `DDBModel.prepare` call site; detection
+follows import aliases (`import { DDBModel as M }`), namespace imports
+(`g.DDBModel`), module-const aliases, and same-file `extends DDBModel`
+subclasses. Call sites already evaluated once per module load (module-scope
+`const`, static class fields) are left as-is.
+
+### Programmatic API
+
+```ts
+import { transformPreparedSource, lintPreparedSource } from 'graphddb/transform';
+
+const result = transformPreparedSource(fileName, sourceText); // { text, changed, diagnostics, ... }
+const diagnostics = lintPreparedSource(fileName, sourceText); // check-only (the build gate)
+```
+
+Build-time only (requires the optional `typescript` dependency, like the JSDoc
+codegen pass); wire it into a bundler plugin or a pre-build step if you prefer
+that over the CLI.
+
+### What the static lint proves — and its limits
+
+The lint accepts only the declarative grammar the runtime itself accepts
+(object/array literals, static literals, `$.<name>`, module-static reference
+chains, `() => Model` thunks), applied **transitively** through same-file
+module-const templates. It therefore rejects, per-file and soundly: direct
+captures (enclosing-scope bindings, `this`), indirect captures via **any** call
+or `new`, mutable module state (`let` / `var`), unresolved globals, per-call
+control flow (conditionals, computed keys, substitution templates), and bodies
+it cannot statically see.
+
+Per-file syntactic analysis cannot prove two things: an **imported** binding is
+accepted as module-static (that is the design's allowance for `() => Model`
+refs — a pathological mutable re-export is invisible), and mutation of a
+same-file `const` **object** between calls. Both are backstopped by the
+phase-1 runtime guard (only `$`-refs and scalar static literals are bindable
+value leaves) and by the fallback's correctness: an undetected unhoistable
+site is never wrong, only warmer.
+
+Detection also does **not check the import's module specifier**: a binding
+imported as `DDBModel` from **any** package (`import { DDBModel } from
+'<other-package>'`) matches, so another library's same-named `DDBModel.prepare`
+call site is transformed / linted too (a false transform or a spurious lint
+error is possible). Take care in files that mix graphddb with a same-named
+foreign API.
+
+## Semantics (both layers, guaranteed identical)
+
+- **write** — the params-independent op template compiles once
+  (`compileWriteFragment`); `execute` runs the identical core the envelope and
+  `publicCommandModel` use: derived maintainers and atomic
+  `TransactWriteItems` semantics match exactly. Multi-alias bodies compose one
+  atomic transaction (`mode: 'parallel'` opts out per call).
+- **read** — the params-independent products (resolved model, normalized
+  select, validated relation structure) compute once; `execute` binds key
+  values + per-call pagination/consistency and runs `executeQuery` /
+  `executeList` exactly like `Model.query` / `Model.list`.
+- A body is all-read or all-write; an option the target core would ignore is a
+  loud compile-time reject (never a silent drop).

package/docs/python-bridge.md

@@ -153,7 +153,7 @@ so the output is stable across runs.
 
 ```jsonc
 {
-  "version": "1.0",
+  "version": "1.1",
   "tables": { "UserPermissions": { "physicalName": "UserPermissions" } },
   "entities": {
     "UserModel": {
@@ -199,14 +199,17 @@ so the output is stable across runs.
 - `key` / `gsis[*]` carry `inputFields` and `pkTemplate` / `skTemplate` where the
   templates use `{field}` placeholders (e.g. `USER#{userId}`, `EMAIL#{email}`).
   `skTemplate` is `null` when the access pattern has no sort key.
-- `relations[*]` is one of `hasMany | hasOne | belongsTo` with a `target` entity
-  and a `keyBinding` (target field → source field).
+- `relations[*]` is one of `hasMany | hasOne | belongsTo | refs` with a `target`
+  entity and a `keyBinding` (target field → source field). A `refs` relation
+  (issue #197 / #208) additionally carries `refs: { from, key }` — the parent
+  LIST attribute holding the inline reference elements and the field read off
+  each element.
 
 ### 4.2 `operations.json` — Execution Specs
 
 ```ts
 interface OperationsDocument {
-  readonly version: '1.0';
+  readonly version: '1.1';
   readonly queries: Record<string, QuerySpec>;
   readonly commands: Record<string, CommandSpec>;
   readonly transactions?: Record<string, TransactionSpec>;
@@ -468,6 +471,23 @@ GraphDDBRuntime(
 `table_mapping` maps logical table names to deployed physical names. The
 specs are loaded and cached at construction.
 
+**Spec-version guard (#208).** The IR is a stable execution contract, so
+construction validates both documents' `version` against
+`SPEC_VERSION_SUPPORTED` (currently `1.1`) and raises `GraphDDBError` — loudly,
+never a silent per-operation mis-execution — when a document cannot be
+faithfully executed. The compatibility rule for a `<major>.<minor>` document:
+
+- the **major** must equal the supported major (a major bump changes the shape
+  of existing vocabulary);
+- the **minor** must be **≤** the supported minor — minors are additive (e.g.
+  `1.1` added the `sourceList` list fan-out binding form for `refs`), so every
+  *older* document is fully understood, while a *newer* one may carry binding
+  forms this runtime does not implement and is forward-rejected;
+- a missing or malformed `version` is rejected.
+
+Upgrade `graphddb_runtime` (or regenerate the documents with a matching
+generator) to clear the error.
+
 | Method | Behavior |
 |---|---|
 | `execute_query(query_id, params, options=None) -> dict \| None` | Run a single- or multi-operation query; returns the hydrated result, or `None` when the root matches nothing. `options` may carry a pagination `cursor`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphddb",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Graph data modeling on DynamoDB with adjacency list pattern",
   "type": "module",
   "main": "dist/index.js",
@@ -29,6 +29,10 @@
     "./cdc": {
       "types": "./dist/cdc/index.d.ts",
       "import": "./dist/cdc/index.js"
+    },
+    "./transform": {
+      "types": "./dist/transform/index.d.ts",
+      "import": "./dist/transform/index.js"
     }
   },
   "bin": {