graphddb 0.4.1 → 0.4.3

package/docs/design-patterns.md

@@ -0,0 +1,521 @@
+# GraphDDB — DynamoDB Design Patterns
+
+DynamoDB modeling is the art of choosing, per access pattern, a **read shape** and
+the **write maintenance** that keeps it true. GraphDDB's thesis (Epic #118) is that
+a relation is not navigation — it is a *maintained access path*: a read strategy
+plus a write-maintenance effect, declared as one contract and compiled into the
+read plan, the write plan, the repair/rebuild plan, and the validators.
+
+This page maps the **ten canonical DynamoDB designs** (RFC #118 §1) to the concrete
+graphddb feature that implements each. For every pattern you get:
+
+- **(a) What it is** — the use case and the shape it takes on a DynamoDB table.
+- **(b) How to declare it in graphddb** — the feature / preset / option, with a
+  minimal code example taken from the real API.
+- **(c) Read & write behavior** — how the read is served and how the write keeps it
+  in sync.
+- **(d) Constraints & phase status** — limits and which Epic #118 phase ships it.
+
+> Every API name, option, and helper below is exercised by the library's tests and
+> `examples/`. The maintained-relation vocabulary (`pattern` / `read` / `write` /
+> `projection`, the `maintainedOn` triggers, `updateMode`) is specified in
+> [`spec.md` §7](./spec.md#7-relations); this page is the pattern-oriented companion.
+
+## The maintenance pipeline in one paragraph
+
+A maintained shape is fed by **cross-entity triggers**: `write.maintainedOn:
+['<Entity>.<event>']`, where `<Entity>` is the source's *logical* name (the class
+name minus a `Model` suffix, or the `@model({ prefix })` value) and `<event>` is
+`created | updated | removed`. A synchronous (`updateMode: 'mutation'`) maintainer
+folds its owner-row write into the **same `TransactWriteItems`** as the source write
+(atomic with it). A `stream` maintainer instead emits a maintenance-outbox row that
+a CDC drain applies asynchronously — this is how operations a single transaction
+cannot express (collection trim/splice, a running `max`, sparse put/delete) are
+realized. All presets lower to the **same maintenance IR**, so the maintenance
+graph, the stream drain, and the rebuild planner consume every pattern uniformly.
+
+## Pattern index
+
+| # | 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 |
+| 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`) |
+| 10 | [External Projection](#10-external-projection) | typed-consumer-IF contract (redesign — see #153) | 🚧 redesign |
+
+---
+
+## 1. Same Partition / Containment
+
+**(a) What it is.** Child items that belong to a parent are stored in the **same
+partition** as the parent and read with a single `Query` (`begins_with` on a
+segmented sort key). The classic example: a `Suite` and all its `TestCase`s share
+`PROJECT#{projectId}` as their partition key, with the cases under a segmented SK
+`SUITE#{suiteId}#CASE#…`. One partition read returns the parent and its children
+together — no join, no fan-out.
+
+**(b) How to declare it.** A segmented `key` on the child, plus a `@hasMany` whose
+`keyBinding` is a contiguous prefix of the child's primary key. The
+`pattern: 'samePartition'` preset names that shape explicitly (and a linter rule
+verifies the declaration really lowers to a same-partition `begins_with`).
+
+```ts
+@model({ table: 'App', prefix: 'PROJECT' })
+class TestCaseModel extends DDBModel {
+  static readonly keys = key<{ projectId: string; suiteId: string; caseId: string }>((c) => ({
+    pk: k`PROJECT#${c.projectId}`,
+    sk: [k`SUITE#${c.suiteId}`, k`CASE#${c.caseId}`],
+  }));
+  @string projectId!: string;
+  @string suiteId!: string;
+  @string caseId!: string;
+}
+
+@model({ table: 'App', prefix: 'PROJECT' })
+class SuiteModel extends DDBModel {
+  static readonly keys = key<{ projectId: string; suiteId: string }>((c) => ({
+    pk: k`PROJECT#${c.projectId}`,
+    sk: k`SUITE#${c.suiteId}`,
+  }));
+  @string projectId!: string;
+  @string suiteId!: string;
+
+  @hasMany(() => TestCaseModel, { projectId: 'projectId', suiteId: 'suiteId' }, {
+    pattern: 'samePartition',
+    limit: { default: 50, max: 200 },
+  })
+  cases!: TestCaseModel[];
+}
+```
+
+**(c) Read & write behavior.** Read is a single bounded `Query` against the shared
+partition with a `begins_with` SK condition — the traversal planner derives it from
+the `keyBinding`. There is **no write maintenance**: `samePartition` is pure read
+sugar. The children are kept consistent simply by being written under the parent's
+partition; nothing is denormalized.
+
+**(d) Constraints & phase status.** ✅ Phase 1. `hasMany` only (a parent→children
+collection — `belongsTo`/`hasOne` cannot lower to a `begins_with`). The `keyBinding`
+must bind every PK field and be a proper SK *prefix* (a GSI hop is a different
+partition; a full PK match is a point read — both are rejected). Because there is no
+materialized data, `read` / `write` / `projection` options on a `samePartition`
+relation are a declaration error.
+
+---
+
+## 2. Embedded Refs
+
+**(a) What it is.** A parent row carries a small **list of references** (just the
+ids / keys) to related children, so the parent read returns the set of child ids
+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.)
+
+```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[];
+```
+
+**(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.
+
+**(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).
+
+---
+
+## 3. Embedded Snapshot
+
+**(a) What it is.** Denormalize a **copy** of related data onto the row that reads
+it, so the read needs no join. Two shapes: a **single-row mirror** (a `ProfileCard`
+holding a copy of its `Profile`'s display fields) and a **bounded collection** (a
+`ThreadSummary` holding the latest N posts' previews). On the table the snapshot is
+a map (or list of maps) attribute on the owner item.
+
+**(b) How to declare it.** `pattern: 'embeddedSnapshot'` on a relation, with
+`write.maintainedOn` (the trigger), `projection` (what to capture, with `preview` /
+identity-shorthand transforms), and — for a collection — `read.maxItems` / `order`.
+A `@belongsTo` makes a single-row snapshot; a `@hasMany` makes a collection. (From
+`examples/embedded-snapshot-pattern/`.)
+
+```ts
+// Collection snapshot: the latest posts on a thread summary row.
+@hasMany(() => PostModel, { threadId: 'threadId' }, {
+  pattern: 'embeddedSnapshot',
+  read:  { maxItems: 3, order: 'DESC' },
+  write: { maintainedOn: ['Post.created'] },
+  projection: { postId: 'postId', textPreview: preview('$.entity.body', 120) },
+})
+latestPosts!: PostModel[];
+
+// Single-row snapshot: mirror a profile into a card, re-projected on each update.
+@belongsTo(() => ProfileModel, { userId: 'userId' }, {
+  pattern: 'embeddedSnapshot',
+  write: { maintainedOn: ['Profile.updated'] },
+  projection: { displayName: 'displayName', bioPreview: preview('$.entity.bio', 40) },
+})
+source!: ProfileModel;
+```
+
+**(c) Read & write behavior.** The snapshot is read **inline** off the owner row.
+Synchronously (`updateMode: 'mutation'`, the default), the maintainer folds into the
+**same transaction** as the source write: a `belongsTo` snapshot re-projects the
+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`.
+
+**(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)).
+Projection sources are restricted to the written source payload (`$.entity.*` /
+`$.input.*`) — no write-time fetch of a third entity. Two maintainers targeting the
+same owner row in one mutation is a loud reject ("1 mutation × 1 target row = 1
+effect"). Mind the DynamoDB 400 KB item limit when bounding a collection.
+
+---
+
+## 4. Edge / Adjacency
+
+**(a) What it is.** A many-to-many relationship materialized as **edge items** in an
+adjacency list: an edge row whose PK/SK encode one direction of the relationship
+(e.g. `GROUP#{g} / USER#{u}` for "user u is in group g"). Reading a group's members
+is a `Query` on the group partition; the edge row itself can carry edge attributes
+(role, joinedAt).
+
+**(b) How to declare it.** The adjacency entity declares its **edge write side** with
+`edgeWrites`, deriving the lifecycle-distinguished `Put`/`Delete` of the edge from
+the entity's own create/delete. The read side is the ordinary `@hasMany` /
+`@belongsTo` on the edge's key binding.
+
+```ts
+@model({ table: 'App', prefix: 'GROUP' })
+class GroupMembershipModel extends DDBModel {
+  static readonly keys = key<{ groupId: string; userId: string }>((c) => ({
+    pk: k`GROUP#${c.groupId}`,
+    sk: k`USER#${c.userId}`,
+  }));
+  @string groupId!: string;
+  @string userId!: string;
+  @string role!: string;
+
+  @belongsTo(() => GroupModel, { groupId: 'groupId' })
+  group!: GroupModel | null;
+
+  // The adjacency row IS the Group↔User edge read by Group.members.
+  static readonly writes = edgeWrites((w) => [
+    w.putEdge(() => GroupModel, 'members'),
+  ]);
+}
+```
+
+**(c) Read & write behavior.** Reading is a partition `Query` over the edge rows.
+`edgeWrites` derives the write maintenance: creating the membership emits the edge
+`Put`, deleting it emits the `Delete`, and a foreign-key change emits
+`Delete(old) + Put(new)` (`w.updateKeyChangeEdge`). A build-time round-trip guard
+checks the declared edge actually round-trips to the relation it claims to feed.
+
+**(d) Constraints & phase status.** ✅ Phase 1 (`putEdge` / `deleteEdge` /
+`updateKeyChangeEdge`). A *bidirectional* edge maintained as two physical rows is
+the `dualEdge` extension — see [Reverse Lookup](#9-reverse-lookup).
+
+---
+
+## 5. Materialized View
+
+**(a) What it is.** A read-optimized **view item on its own entity**, assembled from
+one or more sources, that serves a query no single source partition can. Example: a
+`UserThreadList` row per user, holding that user's recent posts (a bounded
+collection) plus the current thread title (a snapshot from a *different* source).
+The view row exists only to be read directly.
+
+**(b) How to declare it.** The view is its OWN model — `@model({ kind:
+'materializedView' })` — and each source is a **class-level** `@maintainedFrom(source,
+(self, source) => options)` decorator, stacked once per source. The `(self, source) =>`
+callback is symbolic: `source.<field>` is a typed reference to a source field (it lowers
+to the same payload-rooted value the IR reads), `self.<field>` names a view field (the
+`collection.field` position), and the object KEYS (`keyBind` / `project` left-hand side)
+are typed `keyof Self` names. `on` is the lifecycle-event list (`created`/`updated`/
+`removed`) — the source is the decorator's first argument, so there is no `'Post.created'`
+string to resolve. **Declaration order carries no meaning**: two sources writing the same
+projection target, the same `collection.field`, or a different view-key field SET are a
+loud build error, not a silent last-wins. The view model registers itself like any
+`@model`, so the maintenance graph discovers it (no separate registry).
+
+```ts
+@model({ table: 'AppTable', prefix: 'UTL', kind: 'materializedView' })
+@maintainedFrom(() => PostModel, (self, source) => ({
+  keyBind:    { userId: source.userId },
+  on:         ['created', 'removed'],
+  project:    { postId: source.postId, textPreview: preview(source.body, 120) },
+  collection: { field: self.recentPosts, maxItems: 3, order: 'DESC', orderBy: source.createdAt },
+  updateMode: 'stream',
+}))
+@maintainedFrom(() => ThreadModel, (_self, source) => ({   // a snapshot slice from a different source
+  keyBind:    { userId: source.userId },
+  on:         ['updated'],
+  project:    { threadTitle: source.title },
+  updateMode: 'stream',
+}))
+class UserThreadListModel extends DDBModel {
+  static readonly keys = key<{ userId: string }>((c) => ({ pk: k`USER#${c.userId}`, sk: k`VIEW` }));
+  @string userId!: string;
+  @string threadTitle!: string;
+}
+```
+
+**(c) Read & write behavior.** The view row is read directly by its key. Each source
+event is drained (asynchronously) into the view row: collection slices order + trim,
+snapshot slices `SET` their projected attributes. Multiple sources converge on the
+same view row, each maintaining its own slice.
+
+**(d) Constraints & phase status.** ✅ Phase 2. A view fed by a bounded ordered
+collection or `removed` events is the **stream** path (`updateMode: 'stream'`) — it
+needs read-modify-write. Drive it with `createMaintenanceDrain({ models })` over the CDC
+stream — the drain derives the view IR from the same declarative models
+([spec §7.2](./spec.md#72-stream-maintenance--outbox--cdc-drain-updatemode-stream-130)).
+
+---
+
+## 6. Sparse View
+
+**(a) What it is.** A view that contains a row **only while a predicate holds** — an
+index of "active tasks", "flagged accounts", etc. Membership flips with the source's
+state, so the view row is *put* when the predicate becomes true and *deleted* when it
+becomes false. (Distinct from a DynamoDB *sparse GSI*, which omits items missing the
+index attribute; here membership is an explicit put/delete maintained by a predicate.)
+
+**(b) How to declare it.** `@model({ kind: 'sparseView' })` with a `@maintainedFrom`
+carrying a `when` membership predicate, built with `whenMember(source.field, op,
+value?)`. `op` is one of `truthy | falsy | exists | notExists | eq | ne` (`eq`/`ne`
+require a comparand). Every `@maintainedFrom` on a `sparseView` MUST carry a `when`
+(and `when` is mutually exclusive with `collection`).
+
+```ts
+@model({ table: 'AppTable', prefix: 'ACT', kind: 'sparseView' })
+@maintainedFrom(() => TaskModel, (_self, source) => ({
+  keyBind: { ownerId: source.assigneeId, taskId: source.taskId },
+  on:      ['created', 'updated', 'removed'],
+  when:    whenMember(source.status, 'eq', 'active'),   // true → PUT / false or removed → DELETE
+  project: { taskId: source.taskId, title: source.title },
+  updateMode: 'stream',
+}))
+class ActiveTaskModel extends DDBModel { /* keys, fields */ }
+```
+
+**(c) Read & write behavior.** The view is read directly (a `Query` over the
+membership partition). On each source event the drain evaluates the predicate: if it
+holds, the view row is `PUT` (with the projected `fields`); if it flips false (or the
+source is `removed`), the row is `DELETE`d.
+
+**(d) Constraints & phase status.** ✅ Phase 3, **stream-only**. A single atomic
+transaction cannot branch an item between `Put` and `Delete` on a runtime predicate,
+so declaring a sparse view on the synchronous `mutation` path is a loud reject —
+`write.updateMode: 'stream'` is required. A membership predicate is mutually
+exclusive with a `collection` slice. The rebuild planner does **not** reconstruct
+membership rows (re-run the source events through the drain instead).
+
+---
+
+## 7. Aggregate Counter
+
+**(a) What it is.** A scalar **derived aggregate** kept on a counter row — a post
+count per thread, a running max timestamp — so the aggregate is read in O(1) without
+scanning the source rows. On the table it is a number/value attribute on a counter
+item.
+
+**(b) How to declare it.** An `@aggregate` field bound to a source, with
+`pattern: 'counter'` and a `value` aggregate (`count()` or `max(field)`). (From
+`examples/aggregate-counter/`.)
+
+```ts
+@model({ table: 'App' })
+class ThreadCounterModel extends DDBModel {
+  static readonly keys = key<{ threadId: string }>((c) => ({
+    pk: k`THREADCOUNT#${c.threadId}`,
+    sk: k`COUNT`,
+  }));
+  @string threadId!: string;
+
+  @aggregate(() => ThreadPostModel, { threadId: 'threadId' }, {
+    pattern: 'counter',
+    value: count(),
+    write: { maintainedOn: ['ThreadPost.created', 'ThreadPost.removed'] },
+  })
+  postCount!: number;
+}
+```
+
+**(c) Read & write behavior.** The counter row is read directly. `ThreadPost.created`
+applies `postCount += 1`, `ThreadPost.removed` applies `-= 1` — realized as an
+atomic, concurrency-safe `ADD ±1` composed into the **same `TransactWriteItems`** as
+the source write (no prior read, never clobbers a concurrent increment; rolls back
+with the source if the source write fails).
+
+**(d) Constraints & phase status.** ✅ Phase 1 for `count()` (synchronous, derive
+increment, issue #85/#141). A `max(field)` running aggregate needs a conditional
+`SET` whose failed guard must not roll back the legitimate source write — so it is
+the **stream** path: declare `value: max('createdAt')` with
+`write: { updateMode: 'stream' }`. `max()` on the synchronous `mutation` path is a
+loud reject pointing you at `count()` or `stream`.
+
+---
+
+## 8. Versioned / Latest Pointer
+
+**(a) What it is.** Keep an append-only **history** of every revision plus a
+**latest pointer** that always resolves the current version in one read. On the table
+this is a history row per version (`DOC#{id} / V#{version}`) and a single latest row
+(`DOC#{id} / LATEST`) overwritten each revision.
+
+**(b) How to declare it.** On the SOURCE (revision) model, ride the `@hasOne` /
+`@hasMany` `pattern` discriminated union (issue #152). `@hasOne(() => LatestModel,
+(self, source) => ({ pattern: 'versionedLatest', on, project }))` is the single
+overwritten pointer; `@hasMany(() => HistoryModel, (self, source) => ({ pattern:
+'versionedHistory', on, project }))` is the append-only history. Cardinality is
+type-enforced: `versionedLatest` is only valid on `@hasOne`, `versionedHistory` only on
+`@hasMany`. The latest/history KEY binding is derived from each target model's own `key`
+fields (latest keys omit the version; history keys include it) — both lower to the same
+composed snapshot×2 IR.
+
+```ts
+class DocModel extends DDBModel {
+  static readonly keys = key<{ docId: string; version: number }>((c) => ({
+    pk: k`DOC#${c.docId}`, sk: k`V#${c.version}`,
+  }));
+  @string docId!: string; @number version!: number; @string body!: string;
+
+  @hasOne(() => DocLatestModel, (_self, source) => ({          // latest = single overwritten row
+    pattern: 'versionedLatest',
+    on: ['created', 'updated'],
+    project: { docId: source.docId, version: source.version, body: source.body },
+  }))
+  latest!: DocLatestModel;
+
+  @hasMany(() => DocHistoryModel, (_self, source) => ({        // history = append per revision
+    pattern: 'versionedHistory',
+    on: ['created', 'updated'],
+    project: { docId: source.docId, version: source.version, body: source.body },
+  }))
+  history!: DocHistoryModel[];
+}
+```
+
+**(c) Read & write behavior.** Read the latest pointer by id for the current version;
+`Query` the history partition for the full revision list. Each maintained revision
+**overwrites** the latest row and **appends** a new history row — both projected from
+the same source payload, composed from the two declarations.
+
+**(d) Constraints & phase status.** ✅ Phase 3. The history target model's key must
+include a version discriminator the latest target's key omits (so history appends
+instead of overwriting), and the latest and history models must be **distinct**. Both
+rows are pure snapshots (no collection / membership slices). A self-co-located form
+(latest + history in the source's own key space) is a deferred follow-up — the primary
+form is the two-model shape above.
+
+---
+
+## 9. Reverse Lookup
+
+**(a) What it is.** Read a relationship from **both directions** — "groups of a user"
+*and* "users of a group", "who I follow" *and* "who follows me". Two complementary
+strategies on the table: one item indexed by a **GSI** that flips PK/SK, or **two
+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.
+
+```ts
+// GSI form: one row, reverse direction served by a GSI.
+@model({ table: 'App', prefix: 'GROUP' })
+class GroupMembershipModel extends DDBModel {
+  static readonly keys = key<{ groupId: string; userId: string }>((c) => ({
+    pk: k`GROUP#${c.groupId}`, sk: k`USER#${c.userId}`,
+  }));
+  static readonly userGroupsIndex = gsi<{ userId: string; groupId: string }>(
+    'GSI1', (c) => ({ pk: k`USER#${c.userId}`, sk: k`GROUP#${c.groupId}` }),
+  );
+  @string groupId!: string;
+  @string userId!: string;
+}
+
+// Dual-edge form: two physical rows kept in sync (no inverse GSI).
+@model({ table: 'App', prefix: 'FOLLOW' })
+class FollowEdgeModel extends DDBModel {
+  // … key: FOLLOWER#{a} / FOLLOWING#{b}
+  static readonly writes = edgeWrites((w) => [
+    w.dualEdge(
+      { target: () => UserModel, relationProperty: 'following' },
+      { adjacency: () => FollowedByEdgeModel, target: () => UserModel, relationProperty: 'followers' },
+    ),
+  ]);
+}
+```
+
+**(c) Read & write behavior.** *GSI form*: the reverse relation queries the GSI;
+DynamoDB keeps the GSI eventually consistent with the base item — no application
+write effect. *Dual-edge form*: the single `dualEdge` declaration writes / deletes /
+moves **both** the forward row and the inverse row on the second adjacency model
+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).
+
+---
+
+## 10. External Projection
+
+**(a) What it is.** Project a source's changes to an **external sink** — BigQuery,
+OpenSearch, S3, Neptune — for analytics or search, decoupled from the table. The
+projection is asynchronous and must tolerate at-least-once delivery (a redelivered
+event must not double-write).
+
+**(b) How it is being redesigned (🚧 #153).** The previous `defineProjection` builder +
+`ProjectionSinkDrain` / `InMemoryProjectionSink` runtime baked the sink-delivery
+semantics (upsert, idempotency, dedup) into the library — a boundary overreach: the
+actual sink write happens inside the consumer's CDC infrastructure, outside graphddb.
+That runtime was **removed in 0.4.0** (issue #152). The redesign (issue #153) reframes
+external projection as a **typed-consumer-IF contract**: from a declared source +
+projection fields + idempotency-key extraction, graphddb emits a typed
+`(changeImage) => TypedProjectionRecord` mapper for the consumer to call inside its own
+sink delivery — graphddb owns the *parse → typed record* contract, not the delivery.
+External projection is neither a Model nor a relation, so it does not ride a decorator.
+
+**(c) Read & write behavior.** Out of scope for this library (the data is read from the
+sink; delivery + idempotency live in the consumer's CDC code). See #153 for the
+typed-consumer-IF contract design.
+
+**(d) Constraints & phase status.** 🚧 Redesign (#153). The sink runtime is gone in
+0.4.0; the typed-consumer-IF replacement lands separately.
+
+---
+
+## See also
+
+- [`spec.md` §7 — Relations & maintained access paths](./spec.md#7-relations)
+- [`cdc-emulator.md`](./cdc-emulator.md) — the CDC emulator that drives the stream drains locally
+- Runnable examples: [`embedded-snapshot-pattern`](../examples/embedded-snapshot-pattern/), [`aggregate-counter`](../examples/aggregate-counter/), [`user-permissions`](../examples/user-permissions/)