graphddb 0.7.10 → 0.8.1

package/docs/spec.md

@@ -28,7 +28,7 @@ own specs:
   local development and tests.
 - [`testing.md`](./testing.md) — the in-memory test adapter (`graphddb/testing`).
 - [`middleware.md`](./middleware.md) — host-side read & write middleware / hooks
-  (`DDBModel.use`): read R1–R5, write W1–W5, registration, per-call `context`,
+  (`graphddb.config.use`): read R1–R5, write W1–W5, registration, per-call `context`,
   ordering, cancellation / recovery, and Python parity.
 
 For a comparison against other DynamoDB libraries, see
@@ -59,7 +59,7 @@ For a comparison against other DynamoDB libraries, see
 19. [Update](#19-update)
 20. [Delete](#20-delete)
 21. [Conditional writes](#21-conditional-writes)
-22. [The unified envelope — `DDBModel.query` / `DDBModel.mutate`](#22-the-unified-envelope--ddbmodelquery--ddbmodelmutate)
+22. [The unified envelope — `graphddb.query` / `graphddb.mutate`](#22-the-unified-envelope--graphddbquery--graphddbmutate)
 23. [Batch operations](#23-batch-operations)
 24. [The Linter and design rules](#24-the-linter-and-design-rules)
 25. [Runtime responsibilities (pipeline)](#25-runtime-responsibilities-pipeline)
@@ -113,30 +113,29 @@ applied by the caller on the already-typed result (`result.items.filter(...)`,
 
 ## 2. Connection and client configuration
 
-GraphDDB uses a process-global client (`ClientManager`) and an optional
-table-name remap (`TableMapping`). Configure them via the static methods on
-`DDBModel` before issuing any operation.
+GraphDDB uses a process-global client and an optional table-name remap.
+Configure them via the `graphddb.config.*` surface before issuing any operation.
 
 ```ts
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-import { DDBModel } from 'graphddb';
+import { graphddb } from 'graphddb';
 
-DDBModel.setClient(new DynamoDBClient({ region: 'us-east-1' }));
+graphddb.config.client(new DynamoDBClient({ region: 'us-east-1' }));
 
 // Optional: remap declared table names → physical table names (e.g. per stage).
-DDBModel.setTableMapping({ UserPermissions: 'UserPermissions-prod' });
+graphddb.config.tables({ UserPermissions: 'UserPermissions-prod' });
 ```
 
 | Method | Signature | Behavior |
 | --- | --- | --- |
-| `DDBModel.setClient` | `(client: DynamoDBClient) => void` | Stores the client globally and discards any cached document client. |
-| `DDBModel.setTableMapping` | `(mapping: Record<string, string>) => void` | Replaces the declared-name → physical-name map. |
+| `graphddb.config.client` | `(client: DynamoDBClient) => void` | Stores the client globally and discards any cached document client. |
+| `graphddb.config.tables` | `(mapping: Record<string, string>) => void` | Replaces the declared-name → physical-name map. |
 
 - The low-level marshalling uses a `DynamoDBDocumentClient` (`@aws-sdk/lib-dynamodb`),
   created lazily from the configured client and cached. Values you pass and
   receive are plain JS (un-marshalled).
 - If no client is set, the first operation throws:
-  `DynamoDB client is not configured. Call DDBModel.setClient(new DynamoDBClient({...})) first.`
+  `DynamoDB client is not configured. Call graphddb.config.client(new DynamoDBClient({...})) first.`
 - `TableMapping.resolve(name)` returns the mapped physical name, or the declared
   name unchanged when no mapping entry exists.
 
@@ -637,7 +636,7 @@ composed snapshot×2 IR. (A self-co-located form is a deferred follow-up.)
 External projection's old `defineProjection` / `ProjectionSinkDrain` runtime was
 **removed in 0.4.0** and is now a typed-consumer-IF contract (#153):
 the source model is marked `@cdcProjected()`, `Model.fromChange(event)` parses a CDC
-change event into `[oldRecord, newRecord]`, and `DDBModel.subscribe(handlers)` returns a
+change event into `[oldRecord, newRecord]`, and `graphddb.subscribe(handlers)` returns a
 `ChangeHandler` the consumer mounts on its own stream (subscription / sink delivery /
 idempotency stay with the consumer). See [`cdc-projection.md`](./cdc-projection.md).
 
@@ -715,10 +714,13 @@ export const GroupMembership = GroupMembershipModel.asModel();
 | `updateItem(entity, changes, options?)` | write | partial update (§19) |
 | `deleteItem(key, options?)` | write | delete (§20) |
 
-The static, class-level methods (`setClient`, `setTableMapping`, `query`,
-`mutate`, `batchGet`, `batchWrite`, `asModel`) live on `DDBModel` itself. The
-unified-envelope `DDBModel.query` / `DDBModel.mutate` (§22) drive multi-route
-reads and lifecycle-aware writes.
+The per-model methods above come from `Model.asModel()`. Host-runtime config
+(client / table mapping / retry / middleware) lives on `graphddb.config.*` (not
+`DDBModel`), and the unified-envelope execution verbs are `graphddb.query` /
+`graphddb.mutate` (§22) — they drive multi-route reads and lifecycle-aware writes,
+with batch read folded into `graphddb.query({ key: K[] })` and batch write into
+`graphddb.mutate({ mode: 'parallel' })`. `DDBModel` itself carries only
+`mutate` / `prepare` / `subscribe` / `asModel`.
 
 ---
 
@@ -979,9 +981,9 @@ filter: cond`${User.col.age} > ${18} and attribute_exists(${User.col.email})`
   `and` / `or`, or as `not`.
 - `cond` is **not read-only**: it is equally a valid `WriteCondition<M>` (issue
   #114-B), so it may be used as a write `condition` on `putItem` / `updateItem` /
-  `deleteItem`, on a transaction item / `ConditionCheck`, and in the declarative
-  `mutation(...)` / public command `condition` (where its value slots may carry
-  `param.*` bindings — see [cqrs-contract](./cqrs-contract.md)).
+  `deleteItem`, on a transaction item / `ConditionCheck`, and in a declarative
+  `graphddb.publishCommand` descriptor `condition` (where its value slots may
+  carry `param.*` bindings — see [cqrs-contract](./cqrs-contract.md)).
   - **Nesting constraint (serializable surfaces):** a `cond` used as a **whole**
     condition is fully supported everywhere. A `cond` **nested inside** a
     declarative `and` / `or` / `not` group works **in-process** (TS/memory), but
@@ -1142,7 +1144,7 @@ Behavior:
 - The input type `EntityInput<T>` includes scalar and embedded fields and
   **excludes relations** (relations are not persisted by `putItem`).
 - `putItem` / `updateItem` / `deleteItem` are the **raw base operations**. For
-  lifecycle-aware single writes, go through `DDBModel.mutate(...)` (§22) rather
+  lifecycle-aware single writes, go through `graphddb.mutate(...)` (§22) rather
   than the raw primitives.
 - The runtime serializes each declared field, computes `{ pk, sk }` from the
   primary key, and writes `{ PK: '<prefix><pk>', SK: String(sk), ...fields }`.
@@ -1206,9 +1208,9 @@ same `UpdateExpression`** — the index follows the row instead of silently rott
    `{ rederive: 'read-modify-write' }` to read the current item, merge, re-derive
    from the full image, and write back under an optimistic condition.
 
-Transaction updates (`defineTransaction` … `tx.update`) apply the same rule: the
-affected index keys are re-derived into the update at build time, or the build
-throws when a composing field is unavailable.
+Transactional updates (`graphddb.mutate({ mode: 'transaction' })` with an
+`update` op) apply the same rule: the affected index keys are re-derived into the
+update at build time, or the build throws when a composing field is unavailable.
 
 ### Key resolution (3-stage)
 
@@ -1334,20 +1336,20 @@ the AWS SDK's `ConditionalCheckFailedException`.
 
 ---
 
-## 22. The unified envelope — `DDBModel.query` / `DDBModel.mutate`
+## 22. The unified envelope — `graphddb.query` / `graphddb.mutate`
 
 Multi-route reads and lifecycle-aware writes are issued through a single
 in-process **unified envelope**: a **descriptor map** keyed by caller-chosen
 aliases, where each value is a route descriptor naming a model and an operation.
 The result is an object with the same aliases.
 
-### Read envelope — `DDBModel.query(map)`
+### Read envelope — `graphddb.query(map)`
 
-`DDBModel.query(map)` runs each alias route **independently and in parallel**
+`graphddb.query(map)` runs each alias route **independently and in parallel**
 (there is no cross-route consistency — these are parallel independent reads):
 
 ```ts
-const { user, members } = await DDBModel.query({
+const { user, members } = await graphddb.query({
   user:    { query: User,            key: { userId: 'u1' },   select: { name: true } },
   members: { list:  GroupMembership, key: { groupId: 'eng' }, select: { role: true }, options: { limit: 20 } },
 });
@@ -1362,14 +1364,14 @@ A **read route descriptor** is `{ query | list: Model, key, select, options? }`
 - `options` for `query`: `{ consistentRead?, maxDepth? }`; for `list`:
   `{ limit?, after?, order?, filter? }`.
 
-### Write envelope — `DDBModel.mutate(map, { mode })`
+### Write envelope — `graphddb.mutate(map, { mode })`
 
-`DDBModel.mutate(map, { mode })` performs lifecycle-aware writes. This is the
+`graphddb.mutate(map, { mode })` performs lifecycle-aware writes. This is the
 path for **single** writes too — the raw primitives `putItem` / `updateItem` /
 `deleteItem` (§18–20) are base ops, not lifecycle-aware.
 
 ```ts
-const res = await DDBModel.mutate({
+const res = await graphddb.mutate({
   a: { create: GroupMembership, key: { groupId: 'eng', userId: 'u1' }, input: { role: 'admin' } },
   b: { update: User, key: { userId: 'u1' }, input: { name: 'Ann' }, condition: { status: 'active' }, result: { select: { name: true } } },
 }, { mode: 'transaction' });
@@ -1408,47 +1410,47 @@ no cross-route consistency.
 
 ## 23. Batch operations
 
-```ts
-DDBModel.batchGet(requests: BatchGetRequest[]): Promise<BatchGetResult>;
-DDBModel.batchWrite(requests: BatchWriteRequest[]): Promise<void>;
-```
+0.8.0 folds the standalone `DDBModel.batchGet` / `batchWrite` statics into the
+two execution verbs:
 
-```ts
-interface BatchGetRequest { model: ModelStatic<T>; keys: Record<string, unknown>[]; }
-
-type BatchWriteRequest =
-  | { type: 'put';    model; item: Record<string, unknown>; options?: PutOptions }
-  | { type: 'delete'; model; key:  Record<string, unknown>; options?: DeleteOptions };
-```
+- **Batch read** = `graphddb.query({ key: K[] })` — a pure point read over an
+  array of keys routes to a chunked `BatchGetItem`.
+- **Batch write** = `graphddb.mutate({ mode: 'parallel' })` — a non-atomic write
+  envelope routes to a chunked `BatchWriteItem` (per-op partial success).
 
 ```ts
-const result = await DDBModel.batchGet([
-  { model: User, keys: [{ userId: 'alice' }, { userId: 'bob' }] },
-]);
-const users = result.get(User);   // Partial<UserModel>[]
-
-await DDBModel.batchWrite([
-  { type: 'put',    model: User,            item: { userId: 'dave', /* … */ } },
-  { type: 'delete', model: GroupMembership, key:  { groupId: 'eng', userId: 'bob' } },
-]);
+// Batch read: an array of keys for one model → chunked BatchGetItem.
+const users = await graphddb.query({
+  users: { query: User, key: [{ userId: 'alice' }, { userId: 'bob' }], select: { userId: true } },
+});
+// users.users → (Partial<UserModel> | null)[]
+
+// Batch write: mode 'parallel' → chunked BatchWriteItem, per-op partial success.
+await graphddb.mutate(
+  {
+    add:    { create: User,            key: { userId: 'dave' }, input: { /* … */ } },
+    remove: { remove: GroupMembership, key: { groupId: 'eng', userId: 'bob' } },
+  },
+  { mode: 'parallel' },
+);
 ```
 
 Behavior and limits:
 
-- **`batchGet`** groups keys by physical table, fetches all scalar fields,
-  hydrates them (merging back any embedded maps), and returns a `BatchGetResult`
-  whose `.get(model)` yields the items for that model (`Partial<T>[]`). Keys are
-  matched back to items by `PK::SK`.
-- **`batchWrite`** groups by table, builds put/delete inputs, and writes.
+- **Batch read** groups keys by physical table, fetches the requested scalar
+  fields, hydrates them (merging back any embedded maps), and returns the items in
+  the query envelope. Keys are matched back to items by `PK::SK`.
+- **Batch write** (`mode: 'parallel'`) groups by table, builds put/delete inputs,
+  and writes with per-op partial success (`{ ok }` | `{ error }`).
 - **Chunking:** keys/items are split into chunks of `BATCH_GET_MAX_KEYS = 100`
   (get) and `BATCH_WRITE_MAX_ITEMS = 25` (write) and issued per chunk.
 - **Retry:** unprocessed keys/items are retried with exponential backoff
   (`50·2^(n-1)` ms, capped at 1000 ms) up to `BATCH_MAX_RETRY_ATTEMPTS = 10`
   retries, after which it throws (rather than looping forever) — typically a sign
   of sustained throttling.
-- Item-level `condition` options on `batchWrite` puts/deletes are accepted in the
-  request type but DynamoDB BatchWrite does not support per-item conditions; use
-  transactions for conditional atomic writes.
+- Per-op `condition`s are not supported on `mode: 'parallel'` (DynamoDB
+  BatchWrite has no per-item conditions); use `mode: 'transaction'` for
+  conditional atomic writes.
 
 ---
 
@@ -1482,16 +1484,26 @@ resolver instead.
 
 ### Customizing
 
+The linter (`Linter` + the built-in rules) is a build/dev-time surface served by
+the dedicated `graphddb/linter` subpath:
+
 ```ts
-import { MetadataRegistry, Linter, noScanRule, requireLimitRule } from 'graphddb';
+import { Linter, noScanRule, requireLimitRule } from 'graphddb/linter';
 
 const linter = new Linter();
 linter.addRule(noScanRule);
 linter.addRule(requireLimitRule);
-MetadataRegistry.linter = linter;        // set BEFORE defining/registering models
-// MetadataRegistry.resetLinter();        // restore the default set
 ```
 
+Attaching a custom `Linter` to the entity registry is an advanced build-time
+concern: the `MetadataRegistry` the linter runs against is internal machinery
+(0.8.0 demoted it off the public root), so the registry-wiring step
+(`MetadataRegistry.linter = linter`, set **before** defining/registering models;
+`MetadataRegistry.resetLinter()` to restore the default set) lives inside
+graphddb's own codegen/spec tooling. Application code selects rules through
+`graphddb/linter` and relies on the default set that runs automatically at model
+registration.
+
 > The `user-permissions` example installs a custom linter without `gsi-ambiguity`
 > on purpose: `GroupMembership` uses `[userId]` as its GSI input, a subset of its
 > PK input `[groupId, userId]`. The runtime resolves this unambiguously (exact
@@ -1545,7 +1557,7 @@ position (§12). Post-load TypeScript filtering is not part of this pipeline (§
 
 | Condition | Message (abridged) | Where |
 | --- | --- | --- |
-| No client configured | `DynamoDB client is not configured. Call DDBModel.setClient(new DynamoDBClient({...})) first.` | first op |
+| No client configured | `DynamoDB client is not configured. Call graphddb.config.client(new DynamoDBClient({...})) first.` | first op |
 | Class not `@model`-decorated | `No metadata registered for '<name>'. Did you apply @model()?` | metadata access |
 | No matching access pattern | `No access pattern found for fields […]. Available: …` | key resolution |
 | `query()` on non-unique GSI | `Cannot use query() with non-unique GSI '<i>'. Use list() instead.` | `query` |
@@ -1562,68 +1574,85 @@ position (§12). Post-load TypeScript filtering is not part of this pipeline (§
 
 ---
 
-## 27. Public API surface
-
-The package entry point (`graphddb`) exports:
-
-**Base class & model API**
-`DDBModel`, type `ModelStatic`.
-
-**Decorators & key builders**
-`model`, `field`, `string`, `number`, `boolean`, `datetime`, `binary`,
-`stringSet`, `numberSet`, `list`, `map`, `literal`, `key`, `k`, `isKeySegment`,
-`gsi`, `embedded`, `hasMany`, `belongsTo`, `hasOne`, `aggregate`, `count`, `max`;
-types `ModelOptions`, `KeyDefinitionMarker`, `KeySegment`, `KeySlot`,
-`SegmentSpec`, `KeyStructure`, `SegmentedKey`, `GsiOptions`,
-`GsiDefinitionMarker`. (`aggregate` / `count` / `max` are the Epic #118 §5.2
-scalar-aggregate declaration surface; their runtime is #141.)
-
-**Maintained access path (Epic #118)**
-`buildMaintenanceGraph` and the `preview` / `identity` projection helpers (the
-function-form projection IR for relation `projection` options); maintenance IR
-types (`MaintainTrigger`, `MaintainEffect`, `SnapshotEffect`, `CollectionEffect`,
-`ProjectionTransform`, …) and relation-option types (`RelationPattern`,
-`RelationReadOptions`, `RelationWriteOptions`, `RelationProjection`,
-`RelationOptions`, `AggregateValue`, `AggregateOptions`, `AggregateMetadata`).
-
-**Client**
-`ClientManager`, `TableMapping`.
-
-**Type-safe query/select types**
-`SelectableOf`, `RelationSelect`, `RelationSpec`, `QueryResult`, `PrimaryKeyOf`,
-`QueryKeyOf`, `UniqueQueryKeyOf`, `PartialQueryKeyOf`, `QueryOptions`,
-`ListOptions`, `FilterInput`, `SelectBuilder`, `RelationBuilder`, `SelectOf`,
-`Updatable`.
-
-**Filter / select runtime**
-`cond`, `isColumn`, `isSelectBuilder`; types `RawCondition`, `CondSlot`, `Column`,
-`ColumnMap`.
-
-**Metadata**
-`MetadataRegistry`, `derivePrefix`, `validateGsiAmbiguity`; entity-metadata
-types.
-
-**Linter**
-`Linter`, `createDefaultLinter`, `noScanRule`, `requireLimitRule`,
-`queryBoundaryRule`, `gsiAmbiguityRule`, `missingGsiRule`, `relationDepthRule`,
-plus the Epic #118 maintenance/preset rules (`samePartitionPresetRule`,
-`missingContextRule`, `embeddedSnapshotSizeRule`, `hotPartitionRule`,
-`fanOutRule`, `multiMaintainerSameRowRule`); types `LintRule`, `LintResult`. The
-default set (`createDefaultLinter`) includes every rule **except**
-`queryBoundaryRule`; the maintenance rules are no-ops for relations that declare
-no `write.maintainedOn`.
-
-**Lower-level building blocks** (for advanced/transaction/batch use)
-`executePut`, `executeUpdate`, `executeDelete`, `executeQuery`, `executeList`,
-`executeExplain`, `executeTransaction`, `executeBatchGet`, `executeBatchWrite`,
-`buildPutInput`, `buildUpdateInput`, `buildDeleteInput`, `serializeFieldValue`,
-`TransactionContext`, `BatchGetResult`, `attachModelClass`, `MAX_TRANSACT_ITEMS`
-(25), `BATCH_GET_MAX_KEYS` (100), `BATCH_WRITE_MAX_ITEMS` (25); expression
-builders `buildUpdateExpression`, `buildConditionExpression`,
-`compileFilterExpression`, `evaluateFilter`; planner `resolveKey`,
-`buildProjection`, `plan`; executor `execute`; `hydrate`; pagination
-`encodeCursor` / `decodeCursor`; relation `detectRelationFields`,
-`getImplicitKeyFields`, `validateDepth`, `resolveRelations`.
+## 27. Public API surface (0.8.0)
+
+The 0.8.0 surface is **two pillars** from the root entry point plus a handful of
+dedicated subpaths. Everything the old flat root barrel exported for runtime
+plumbing (executors, planner, expression builders, `ClientManager` /
+`TableMapping`, `MetadataRegistry`, pagination codec, spec/CDC/linter builders,
+the `define*` DSL) is either folded into the two pillars or moved to a subpath —
+see the 0.8.0 migration table in `CHANGELOG.md`.
+
+```ts
+import { graphddb, DDBModel } from 'graphddb';
+```
+
+**Pillar 1 — `graphddb.*` (the namespace)**
+- **Authoring**: `graphddb.publishQuery`, `graphddb.publishCommand` (the sole CQRS
+  read/write authoring verbs).
+- **Execution**: `graphddb.query`, `graphddb.mutate`, `graphddb.prepare`,
+  `graphddb.subscribe`. `mutate({ mode: 'transaction' })` is the atomic path
+  (folds in the old `DDBModel.transaction` / `batchWrite`); a pure point batch
+  read is `query({ key: K[] })` (routes to chunked `BatchGetItem`; folds in the
+  old `DDBModel.batchGet`); a batch write is `mutate({ mode: 'parallel' })`.
+- **Config**: `graphddb.config.*` — `client` / `getClient` / `tables` / `retry` /
+  `use` / `clearMiddleware` (the host-runtime config surface; folds in the old
+  `DDBModel.setClient` / `setTableMapping` / `setRetryPolicy` / `use` /
+  `clearMiddleware`).
+
+**Pillar 2 — `DDBModel`**
+`DDBModel`, type `ModelStatic`; the CDC binding types `CdcModelRegistry`,
+`CdcSubscribeHandlers`. Execution/config statics are gone from `DDBModel` — use
+`graphddb.*` above.
+
+**Kept named authoring primitives (schema DSL + CQRS body helpers)**
+- Decorators & key builders: `model`, `field`, `string`, `number`, `boolean`,
+  `datetime`, `binary`, `stringSet`, `numberSet`, `list`, `map`, `literal`, `ttl`,
+  `key`, `k`, `gsi`, `embedded`, `hasMany`, `belongsTo`, `hasOne`, `refs`,
+  `aggregate`, `count`, `max`, `maintainedFrom`, `whenMember`, `cdcProjected`;
+  with their option/marker types (`ModelOptions`, `KeyStructure`, `SegmentedKey`,
+  `GsiOptions`, `RefsOptions`, `MaintainedFromOptions`, …).
+- Authoring helpers: `entityWrites` (+ `getEntityWrites`), `param`, `cond`, `when`,
+  `mutate` (the authoring twin, usable as a `publishCommand` method body), and the
+  projection helpers `preview` / `identity`. Types: `Param*` (for `param.*`),
+  `RawCondition` / `CondSlot` / `Column` / `ColumnMap` (for `cond`), and the
+  type-safe query/select types (`QueryResult`, `SelectableOf`, `QueryOptions`,
+  `ListOptions`, `FilterInput`, `SelectBuilder`, `Updatable`, …).
+- Middleware types: `Middleware` / `WriteMiddleware` and their context types (the
+  hooks are registered at runtime via `graphddb.config.use` /
+  `clearMiddleware`).
+
+**Subpaths**
+- `graphddb/internal` — the AOT prepared-plan loader
+  (`import { loadPreparedPlan } from 'graphddb/internal'`) and the artifact
+  document types (`PreparedPlanDocument`, …). This is what
+  `graphddb transform prepared --aot` injects into rewritten user modules, so it
+  must resolve from the installed package.
+- `graphddb/spec` — the static spec / bridge builders + serializer + spec types
+  (`buildBridgeBundle`, `SPEC_VERSION*`, `Manifest*`, `OperationsDocument`, …),
+  the advanced build-time surface external codegen tooling uses.
+- `graphddb/linter` — the design `Linter`, `createDefaultLinter`, and the built-in
+  rules (`noScanRule`, `requireLimitRule`, `queryBoundaryRule`, `gsiAmbiguityRule`,
+  `missingGsiRule`, `relationDepthRule`, plus the Epic #118 maintenance/preset
+  rules `samePartitionPresetRule`, `missingContextRule`, `embeddedSnapshotSizeRule`,
+  `hotPartitionRule`, `fanOutRule`, `multiMaintainerSameRowRule`); types
+  `LintRule`, `LintResult`. The default set (`createDefaultLinter`) includes every
+  rule **except** `queryBoundaryRule`; the maintenance rules are no-ops for
+  relations that declare no `write.maintainedOn`.
+- `graphddb/cdc` — the dev/test CDC emulator (`createCdcEmulator`), the
+  maintenance drain, the CDC-projection parse/route core, and the CDC types
+  (`ChangeEvent`, `ChangeBatch`, …).
+- `graphddb/transform` — the source-transform / prepared-statement compiler used
+  by the `graphddb transform` CLI.
+- `graphddb/testing` — the in-memory test doubles.
+
+Runtime internals that the old flat barrel exported (`execute*` op primitives,
+`build*Input`, `serializeFieldValue`, expression builders, `plan` / `resolveKey`
+/ `buildProjection`, `execute` / `DynamoExecutor`, `hydrate`, `encodeCursor` /
+`decodeCursor`, `MetadataRegistry` / `derivePrefix` / `validateGsiAmbiguity`,
+`ClientManager` / `TableMapping`, `buildMaintenanceGraph`, the relation-traversal
+helpers) are no longer part of the public surface — the two pillars delegate to
+them internally.
 
 ---
 

package/docs/testing.md

@@ -48,11 +48,11 @@ string. Because the seam sits at the *structured operation boundary*, a fake
 needs no expression-string parser.
 
 `createTestDB()` installs a `MemoryExecutor` (`src/memory/memory-executor.ts`)
-over a `MemoryStore` (`src/memory/memory-store.ts`) on the `ClientManager` seam
-via `ClientManager.setExecutor()`. Every `Model.putItem / query / list / updateItem /
-deleteItem / batchGet` call, the planner, hydrator, and relation traversal then run
-unchanged against the in-memory store. `db.testing.close()` (or
-`ClientManager.resetExecutor()`) restores the default `DynamoExecutor`.
+over a `MemoryStore` (`src/memory/memory-store.ts`) on the internal executor seam
+(`ClientManager`). Every `Model.putItem / query / list / updateItem / deleteItem`
+call, a batch read (`graphddb.query({ key: K[] })`), the planner, hydrator, and
+relation traversal then run unchanged against the in-memory store.
+`db.testing.close()` restores the default `DynamoExecutor`.
 
 The store keeps items in their **physical** form — exactly the bytes GraphDDB
 writes (`PK` / `SK` / `GSI*PK` / `GSI*SK` plus attributes), with no marshalling
@@ -110,9 +110,10 @@ interface CreateTestDBOptions {
 }
 ```
 
-`createTestDB()` is the recommended entry point. For callers that wire the seam
-manually, `graphddb/testing` also exports `MemoryExecutor` and `MemoryStore`
-(install with `ClientManager.setExecutor(new MemoryExecutor(store))`).
+`createTestDB()` is the recommended entry point — it installs the in-memory
+executor on the internal seam for you. `graphddb/testing` also exports the
+`MemoryExecutor` and `MemoryStore` building blocks for advanced use (e.g.
+inspecting or pre-seeding the store directly).
 
 Tests must call `db.testing.close()` when done (typically in `afterEach`) to
 detach CDC and restore the default executor. `db.testing.reset()` clears the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphddb",
-  "version": "0.7.10",
+  "version": "0.8.1",
   "description": "Graph data modeling on DynamoDB with adjacency list pattern",
   "type": "module",
   "main": "dist/index.js",
@@ -33,6 +33,10 @@
     "./transform": {
       "types": "./dist/transform/index.d.ts",
       "import": "./dist/transform/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal/index.d.ts",
+      "import": "./dist/internal/index.js"
     }
   },
   "bin": {
@@ -48,8 +52,8 @@
     "test:types": "vitest run --config vitest.typecheck.config.ts && npm run test:types:examples",
     "test:types:examples": "tsc --noEmit -p tsconfig.examples.json",
     "test:integration": "vitest run --config vitest.integration.config.ts",
-    "gen:py:fixtures": "tsx src/cli.ts generate python --entry python/tests/fixtures/models.ts --queries python/tests/fixtures/definitions.ts --commands python/tests/fixtures/definitions.ts --contracts python/tests/fixtures/definitions.ts --out python/tests/fixtures/generated",
-    "gen:py:fixtures:multi": "tsx src/cli.ts generate python --entry python/tests/fixtures/models.ts --queries python/tests/fixtures/definitions_multi.ts --commands python/tests/fixtures/definitions_multi.ts --out python/tests/fixtures/generated_multi",
+    "gen:py:fixtures": "tsx src/cli.ts generate python --entry python/tests/fixtures/models.ts --transactions python/tests/fixtures/definitions.ts --contracts python/tests/fixtures/definitions.ts --out python/tests/fixtures/generated",
+    "gen:py:fixtures:multi": "tsx src/cli.ts generate python --entry python/tests/fixtures/models.ts --contracts python/tests/fixtures/definitions_multi.ts --out python/tests/fixtures/generated_multi",
     "test:py": "python3 -m pytest python/tests -m \"not integration\"",
     "test:py:integration": "python3 -m pytest python/tests -m integration",
     "test:conformance": "tsx conformance/run.ts",
@@ -80,7 +84,7 @@
     {
       "name": "runtime core (DDBModel + authoring)",
       "path": "dist/index.js",
-      "import": "{ DDBModel, model, string, number, key, k, executeQuery, executeList, executeExplain }",
+      "import": "{ DDBModel, model, string, number, key, k }",
       "limit": "42 KB"
     },
     {
@@ -99,6 +103,12 @@
       "path": "dist/spec/index.js",
       "import": "{ buildBridgeBundle }",
       "limit": "20 KB"
+    },
+    {
+      "name": "graphddb/internal (AOT prepared-plan loader)",
+      "path": "dist/internal/index.js",
+      "import": "{ loadPreparedPlan }",
+      "limit": "30 KB"
     }
   ],
   "peerDependencies": {