graphddb 0.5.3 → 0.6.0

package/docs/design-patterns.md

@@ -39,14 +39,14 @@ graph, the stream drain, and the rebuild planner consume every pattern uniformly
 | # | Pattern | graphddb feature | Status |
 |---|---|---|---|
 | 1 | [Same Partition / Containment](#1-same-partition--containment) | segmented SK + `hasMany`, `pattern: 'samePartition'` | ✅ Phase 1 |
-| 2 | [Embedded Refs](#2-embedded-refs) | `embeddedSnapshot` collection projecting id fields only | ✅ Phase 1 (sync append) / stream for trim |
+| 2 | [Embedded Refs](#2-embedded-refs) | `@list` id-list + `@refs` relation (read = one deduped BatchGet) | ✅ Phase 1 (sync append) / stream for trim |
 | 3 | [Embedded Snapshot](#3-embedded-snapshot) | `pattern: 'embeddedSnapshot'` (snapshot / collection) | ✅ Phase 1 |
 | 4 | [Edge / Adjacency](#4-edge--adjacency) | `edgeWrites` `putEdge` / `deleteEdge` / `updateKeyChangeEdge` | ✅ Phase 1 |
 | 5 | [Materialized View](#5-materialized-view) | `@model({ kind: 'materializedView' })` + `@maintainedFrom` | ✅ Phase 2 (stream) |
 | 6 | [Sparse View](#6-sparse-view) | `@model({ kind: 'sparseView' })` + `@maintainedFrom` + `whenMember` | ✅ Phase 3 (stream-only) |
 | 7 | [Aggregate Counter](#7-aggregate-counter) | `@aggregate(..., { pattern: 'counter', value: count() })` | ✅ Phase 1 (`count()`) / stream (`max()`) |
 | 8 | [Versioned / Latest Pointer](#8-versioned--latest-pointer) | `@hasOne(... versionedLatest)` + `@hasMany(... versionedHistory)` | ✅ Phase 3 |
-| 9 | [Reverse Lookup](#9-reverse-lookup) | GSI (both directions) or `dualEdge` two-row sync | ✅ Phase 1 (GSI) / Phase 3 (`dualEdge`) |
+| 9 | [Reverse Lookup](#9-reverse-lookup) | GSI (both directions) or `dualEdge` two-row sync | ✅ Phase 1 (GSI) / `dualEdge` (#133, command-IF driven #195) |
 | 10 | [External Projection](#10-external-projection) | typed-consumer-IF contract (`@cdcProjected` + `fromChange` / `subscribe`) | ✅ |
 
 ---
@@ -117,31 +117,76 @@ without a query; the child bodies are fetched on demand (e.g. a follow-up
 `BatchGet`). On the table this is an attribute holding a list of id strings/maps on
 the parent item.
 
-**(b) How to declare it.** There is no dedicated `refs` preset; embedded refs are an
-**`embeddedSnapshot` collection that projects only the id field(s)** — the snapshot
-machinery, narrowed to keys. (The RFC marks this pattern ⚠️ precisely because it is
-not its own primitive but a thin projection of the snapshot collection.)
+**(b) How to declare it — write (maintain the id-list) + read (resolve the bodies).**
+Embedded refs have two sides, and each has a first-class declaration.
+
+The **stored id-list** is just a `@list` attribute on the parent; you append to it
+however you maintain the parent (directly, or as a narrowed `embeddedSnapshot`
+collection that projects only the id field). The **read side** is a dedicated
+**`refs` relation** (`@refs`) that resolves that inline id-list into the referenced
+child bodies in ONE deduped `BatchGet`:
 
 ```ts
-@hasMany(() => PostModel, { threadId: 'threadId' }, {
-  pattern: 'embeddedSnapshot',
-  read:  { maxItems: 20, order: 'DESC' },
-  write: { maintainedOn: ['Post.created'], updateMode: 'stream' },
-  projection: { postId: 'postId' },   // ids only — the "refs" shape
-})
-postRefs!: PostModel[];
+@model({ table: TABLE, prefix: 'Post' })
+class PostModel extends DDBModel {
+  static readonly keys = key<{ threadId: string; postId: string }>((c) => ({
+    pk: k`THREAD#${c.threadId}`,
+    sk: k`POST#${c.postId}`,
+  }));
+  @string threadId!: string;
+  @string postId!: string;
+  // The stored inline id-list (ids only — the "refs" shape).
+  @list tagRefs!: { tagId: string }[];
+
+  // READ side: resolve `tagRefs[].tagId` → the `Tag` bodies, one deduped BatchGet.
+  @refs(() => TagModel, { from: 'tagRefs', key: 'tagId' })
+  tags!: TagModel[];
+}
 ```
 
-**(c) Read & write behavior.** The ref list is read **inline** off the parent row
-(it *is* the maintained access path). On `Post.created` the maintainer appends the
-projected `{ postId }` ref; resolving the bodies is a separate `BatchGet` against
-the children's keys.
+`from` names the parent list attribute; `key` is the ref field read off each element
+(add `to` when the target's key field name differs from `key`). The decorated
+property is declared as `TagModel[]`, so it selects and returns like a bounded
+collection.
+
+**(c) Read & write behavior.** The id-list is maintained inline on the parent row
+(it *is* the materialized access path). Resolving the child bodies is a single
+declarative query — the `refs` relation reads the parent, pulls each `tagRefs`
+element's `tagId`, **dedupes**, and hydrates the `Tag` bodies in ONE `BatchGetItem`
+(never a per-ref `GetItem`) — the exact physical cost (parent read + 1 BatchGet) of a
+hand-written two-call `Get` + `BatchGet`, but declarative and typed:
+
+```ts
+// ONE query — parent read + one deduped BatchGet for the referenced tag bodies.
+const post = await Post.query(
+  { threadId, postId },
+  { postId: true, tagRefs: true, tags: { select: { tagId: true, name: true } } },
+);
+// post.tags → { items: { tagId: string; name: string }[]; cursor: null }
+```
 
-**(d) Constraints & phase status.** ✅ The synchronous append is Phase 1; bounding
-the list (`maxItems` trim) or removing a ref on `Post.removed` requires the
-read-modify-write **stream** path (declare `updateMode: 'stream'`), since a
-synchronous collection is append-only. Same payload-only projection rule as
-[Embedded Snapshot](#3-embedded-snapshot).
+`select` projects the child body fields (the result is fully typed to the
+projection); a repeated ref costs nothing extra (deduped into one BatchGet key); a
+ref whose body is absent is skipped. The connection carries a `null` cursor — a refs
+list is finite, not paged. This is the same nested-BatchGet auto-resolution
+`@belongsTo`/`@hasOne` use, extended to fan out over a **parent-row list** rather
+than a scalar key.
+
+**(d) Constraints & phase status.** ✅ The read-side `refs` relation is first-class
+in the **TS in-process runtime** (`Model.query`). Maintaining the id-list
+synchronously (append) is Phase 1; bounding it (`maxItems` trim) or removing a ref
+requires the read-modify-write **stream** path. The child bodies are resolved via
+BatchGet, so a `refs` read's `select` cannot push a server-side `FilterExpression`
+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.
 
 ---
 
@@ -185,6 +230,53 @@ single mirrored row in place; a `hasMany` collection appends a projected item
 (`list_append`). On the stream path, the collection additionally trims to `maxItems`
 and splices on `removed`.
 
+**Reading the snapshot (type-safe, no join).** The maintained copy lives on the owner
+row, so it is read with a single point read — but it must NOT be confused with a
+**traversal** to the relation's real child rows. GraphDDB keeps the two apart in both
+the types and the runtime:
+
+- **Collection (`@hasMany` embeddedSnapshot).** Select the field with
+  `{ inline: true }` to read the *maintained copy stored on the owner row* — projected
+  off that one row, returned in the field's declared shape, no child Query:
+
+  ```ts
+  // INLINE READ — the maintained latest-N copy on the ThreadSummary owner row.
+  const summary = await ThreadSummary.query(
+    { threadId },
+    { latestPosts: { inline: true } },
+  );
+  summary?.latestPosts;   // → the projected [{ postId, textPreview }, …] off the row
+
+  // TRAVERSAL — a DIFFERENT read: a Query against the real child Post partition,
+  // returning a `{ items, cursor }` connection of the actual child rows.
+  const traversed = await ThreadSummary.query(
+    { threadId },
+    { latestPosts: { select: { postId: true, body: true } } },
+  );
+  traversed?.latestPosts.items;   // → the real child Posts (full bodies), not the copy
+  ```
+
+  `{ inline: true }` (the maintained copy) and `{ select: … }` (a child traversal) are
+  structurally distinct shapes, so the compiler tells them apart; at runtime an
+  `{ inline: true }` on any field that is **not** an `embeddedSnapshot` relation is a
+  loud error, so the inline read can never be silently mistaken for a traversal (or a
+  bogus attribute). The owner row's key fields are encoded in the PK/SK (known from the
+  query key) and are not re-stored as top-level scalars, so an inline read selects the
+  maintained attribute itself.
+
+- **Single-row mirror (`@belongsTo`/`@hasOne` embeddedSnapshot).** The mirror projects
+  its captured fields onto the owner row's **own scalar columns** (the `projection` map
+  keys — e.g. `displayName`, `bioPreview` on the `ProfileCard`). Those are already
+  first-class typed fields, so the mirror is read inline with an ordinary scalar select
+  — no cast, no traversal:
+
+  ```ts
+  const card = await ProfileCard.query(
+    { userId },
+    { displayName: true, bioPreview: true },   // the mirrored snapshot, read inline
+  );
+  ```
+
 **(d) Constraints & phase status.** ✅ Phase 1 for the synchronous path. A
 synchronous collection is **append-only** — `maxItems` trim and `removed`-driven
 splice are the **stream** path ([§7.2](./spec.md#72-stream-maintenance--outbox--cdc-drain-updatemode-stream-130)).
@@ -444,8 +536,18 @@ physical rows** (a forward edge and an inverse edge on its own partition).
 
 **(b) How to declare it.** *GSI form* — declare a `gsi` on the edge that swaps the key
 so the reverse `@hasMany` resolves against it (no extra write; DynamoDB maintains the
-GSI). *Dual-edge form* — `edgeWrites` with `w.dualEdge(forward, inverse)` to keep a
-**two-row** bidirectional edge in sync without an inverse GSI.
+GSI). *Dual-edge form* — declare `w.dualEdge(forward, inverse)` on the forward edge to
+keep a **two-row** bidirectional edge in sync without an inverse GSI. The dual edge can
+be recorded in either of two write vocabularies carrying the SAME `w.dualEdge`:
+
+- **`entityWrites` (recommended when driving through the command / mutation IF, #195)** —
+  place `w.dualEdge(...)` in a lifecycle's `edges` array. The dual edge is then derived by
+  `executeCommandMethod` / `DDBModel.mutate`, so a `mutation` over the edge maintains BOTH
+  rows in the SAME atomic transaction with no low-level handwork. Use this form if the edge
+  is created / removed through a command.
+- **`edgeWrites` (the low-level edge-only primitive)** — the historical adjacency-only
+  `writes` member. Same two-row synchronization, but driven through the low-level edge-write
+  path rather than the command IF.
 
 ```ts
 // GSI form: one row, reverse direction served by a GSI.
@@ -461,9 +563,28 @@ class GroupMembershipModel extends DDBModel {
   @string userId!: string;
 }
 
-// Dual-edge form: two physical rows kept in sync (no inverse GSI).
+// Dual-edge form (command-IF driven, recommended): two physical rows kept in sync
+// (no inverse GSI). `w.dualEdge` sits in a lifecycle's `edges`, so a `mutation` over
+// the edge derives both rows in one atomic transaction (#195).
 @model({ table: 'App', prefix: 'FOLLOW' })
 class FollowEdgeModel extends DDBModel {
+  // … key: FOLLOWER#{a} / FOLLOWING#{b}
+  static readonly writes = entityWrites<FollowEdgeModel>((w) => ({
+    create: w.lifecycle({
+      edges: [
+        w.dualEdge(
+          { target: () => UserModel, relationProperty: 'following' },
+          { adjacency: () => FollowedByEdgeModel, target: () => UserModel, relationProperty: 'followers' },
+        ),
+      ],
+    }),
+  }));
+}
+
+// Dual-edge form (low-level `edgeWrites` primitive): same two-row synchronization,
+// driven through the edge-write path rather than the command IF.
+@model({ table: 'App', prefix: 'FOLLOW' })
+class FollowEdgeModelLowLevel extends DDBModel {
   // … key: FOLLOWER#{a} / FOLLOWING#{b}
   static readonly writes = edgeWrites((w) => [
     w.dualEdge(
@@ -482,8 +603,10 @@ together, so the two directions stay consistent without a GSI.
 
 **(d) Constraints & phase status.** ✅ Phase 1 for the GSI form (the existing
 bidirectional edge: base row + inverse GSI). The two-row `dualEdge` synchronization
-is Phase 3 (#133). A dual edge is *exactly* two rows — a round-trip guard validates
-the inverse half (and rejects pointing both directions at the same adjacency model).
+landed in #133 and is reachable through the command / mutation IF via the recommended
+`entityWrites` form in #195. A dual edge is *exactly* two rows — a round-trip guard
+validates the inverse half (and rejects pointing both directions at the same adjacency
+model).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphddb",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Graph data modeling on DynamoDB with adjacency list pattern",
   "type": "module",
   "main": "dist/index.js",
@@ -56,7 +56,13 @@
     "size": "size-limit",
     "size:why": "size-limit --why",
     "docker:up": "docker compose -f docker-compose.test.yml up -d",
-    "docker:down": "docker compose -f docker-compose.test.yml down"
+    "docker:down": "docker compose -f docker-compose.test.yml down",
+    "bench:docker:up": "docker compose -p graphddb-bench -f docker-compose.bench.yml up -d",
+    "bench:docker:down": "docker compose -p graphddb-bench -f docker-compose.bench.yml down",
+    "embedoc:build": "embedoc build",
+    "embedoc:watch": "embedoc watch",
+    "embedoc:generate": "embedoc generate --all",
+    "embedoc:check": "node scripts/embedoc-drift-check.mjs"
   },
   "size-limit": [
     {
@@ -108,6 +114,8 @@
     "dynamodb-onetable": "^2.7.7",
     "dynamodb-toolbox": "^2.9.0",
     "electrodb": "^3.9.1",
+    "embedoc": "0.14.2",
+    "prettier": "^3.9.4",
     "size-limit": "^11.0.0",
     "tsup": "^8.0.0",
     "tsx": "^4.22.4",