graphddb 0.4.3 → 0.5.1

package/README.md

@@ -19,6 +19,7 @@ TypeScript types.
 - ✅ **Testing adapter** —— unit-test planner / traversal / transaction / CDC with an in-memory executor.
 - ✅ **Middleware** —— host-side hooks for reads / writes (logging, tenant, authorization).
 - ✅ **CDC emulator** —— drive and test change events equivalent to DynamoDB Streams locally.
+- ✅ **CDC projection** —— `@cdcProjected()` + `fromChange` / `subscribe` parse CDC change events into typed records (sink delivery / idempotency stay with the consumer).
 - ✅ **Maintained access paths** —— keep embedded snapshots / aggregate counters synchronized atomically.
 
 ## 🤔 Philosophy
@@ -204,6 +205,14 @@ Each capability is summarized here only. For details, operator lists, and proced
   [`docs/mutation-command-derivation.md`](./docs/mutation-command-derivation.md).
 - **CDC emulator** —— change events equivalent to DynamoDB Streams, to drive and test differential
   aggregation. [`docs/cdc-emulator.md`](./docs/cdc-emulator.md).
+- **CDC projection** —— a typed-consumer-IF that parses the CDC change events of a `@cdcProjected()`
+  source model into typed records. `Model.fromChange(event)` returns `[old, new]`, and
+  `DDBModel.subscribe(handlers)` (the sibling of `query` / `mutate`) produces a `ChangeHandler` the
+  consumer mounts on its own stream. graphddb owns parse→typed record only; subscription, sink
+  delivery, and idempotency are the consumer's. [`docs/cdc-projection.md`](./docs/cdc-projection.md).
+- **CloudFormation generation** —— `graphddb generate cloudformation` emits a CloudFormation template for
+  the DynamoDB table(s) a model set maps onto (GSI union / Streams / TTL / PITR / PROVISIONED / Auto
+  Scaling). [`docs/cloudformation.md`](./docs/cloudformation.md).
 
 ## 📚 Documentation
 
@@ -222,6 +231,8 @@ documentation available offline at hand. On GitHub, follow the links in the tabl
 | [Multi-language / Python bridge](./docs/python-bridge.md) | Code generation with TS as the SSoT and a Python runtime; TS↔Python conformance. |
 | [In-memory test adapter](./docs/testing.md) | Docker-free in-process testing with `graphddb/testing` and `MemoryInspector`. |
 | [CDC emulator](./docs/cdc-emulator.md) | A change-event emulator for differential aggregation patterns (dev/test). |
+| [CDC projection](./docs/cdc-projection.md) | The `@cdcProjected()` + `fromChange` / `subscribe` typed-consumer-IF: a contract that parses CDC change events into typed records. Boundary (parse→typed is graphddb; subscription, sink delivery, idempotency are the consumer's). |
+| [CloudFormation generation](./docs/cloudformation.md) | The `generate cloudformation` command: emit a CloudFormation template for the DynamoDB table(s) a model set maps onto (GSI union / Streams / TTL / PITR / TableClass / SSE / PROVISIONED / Auto Scaling). All options, derivation rules, and scope boundary. |
 | [Benchmark](./benchmark/RESULTS.md) | Library comparison against hand-written AWS SDK, ElectroDB, DynamoDB Toolbox, and OneTable. |
 
 ## 💡 Examples
@@ -230,7 +241,7 @@ documentation available offline at hand. On GitHub, follow the links in the tabl
 |---------|-------------|
 | [user-permissions](./examples/user-permissions/) | Manages users, groups, and permissions with Single Table Design. Includes adjacency lists, inverted indexes, relation traversal, and `explain`. |
 | [aggregate-tree-pattern](./examples/aggregate-tree-pattern/) | Differential tree aggregation (`siteScoreAverage`) driven by the CDC emulator: dirty propagation, throttled sweeps, recomputation. |
-| [embedded-snapshot-pattern](./examples/embedded-snapshot-pattern/) | Treating a relation as a maintained access path (Epic #118): `pattern: 'embeddedSnapshot'` keeps a denormalized collection / snapshot synchronized onto the owner row in the same atomic transaction as the source write. |
+| [embedded-snapshot-pattern](./examples/embedded-snapshot-pattern/) | Treating a relation as a maintained access path: `pattern: 'embeddedSnapshot'` keeps a denormalized collection / snapshot synchronized onto the owner row in the same atomic transaction as the source write. |
 | [aggregate-counter](./examples/aggregate-counter/) | The `@aggregate` counter from RFC §5.2: the `ThreadPost.created` / `removed` lifecycle keeps `ThreadCounter.postCount` synchronized via an atomic `ADD ±1` within the same `TransactWriteItems` as the source write. |
 
 ## 🏛 Architecture
@@ -250,7 +261,6 @@ From the same TS Model (the SSoT), multiple targets are derived:
 flowchart LR
     M["TS Model (SSoT)"] --> RT["Runtime (TS)"]
     M --> PY["Python client + runtime"]
-    M --> OA["OpenAPI"]
     M --> CQ["CQRS Contract"]
 ```
 

package/dist/{chunk-CPTV3H2U.js → chunk-B3GWIWT6.js}

@@ -412,6 +412,21 @@ var relationDepthRule = {
   }
 };
 
+// src/client/TableMapping.ts
+var TableMapping = class {
+  static mapping = {};
+  static set(mapping) {
+    this.mapping = { ...mapping };
+  }
+  static resolve(declaredName) {
+    return this.mapping[declaredName] ?? declaredName;
+  }
+  /** @internal — for testing only */
+  static reset() {
+    this.mapping = {};
+  }
+};
+
 // src/linter/rules/same-partition-preset.ts
 var samePartitionPresetRule = {
   id: "same-partition-preset",
@@ -843,6 +858,112 @@ function destinationRowKey(owner, relation) {
   return `${owner}#${parts.join("&")}`;
 }
 
+// src/linter/rules/cfn-schema-consistency.ts
+var MAX_GSIS_PER_TABLE = 20;
+function gsiShape(gsi2) {
+  const hasSk = gsi2.segmented.skSegments.length > 0;
+  return { indexName: gsi2.indexName, hasSk };
+}
+function err3(entity, message) {
+  return {
+    ruleId: "cfn-schema-consistency",
+    severity: "error",
+    message,
+    entity
+  };
+}
+var cfnSchemaConsistencyRule = {
+  id: "cfn-schema-consistency",
+  severity: "error",
+  check(metadata, registry) {
+    return checkAllTables(metadata, registry);
+  }
+};
+function checkAllTables(current, registry) {
+  const seenMeta = /* @__PURE__ */ new Set();
+  const byPhysical = /* @__PURE__ */ new Map();
+  const add = (meta) => {
+    if (seenMeta.has(meta)) return;
+    seenMeta.add(meta);
+    const physical = TableMapping.resolve(meta.tableName);
+    const list = byPhysical.get(physical) ?? [];
+    list.push(meta);
+    byPhysical.set(physical, list);
+  };
+  add(current);
+  for (const [, meta] of registry.getFinalized()) add(meta);
+  const currentPhysical = TableMapping.resolve(current.tableName);
+  const entities = byPhysical.get(currentPhysical);
+  if (!entities) return [];
+  return checkTable(currentPhysical, entities);
+}
+function checkTable(physical, entities) {
+  const ordered = [...entities].sort((a, b) => a.prefix.localeCompare(b.prefix));
+  const results = [];
+  results.push(...checkBaseKeySchema(physical, ordered));
+  results.push(...checkGsiUnion(physical, ordered));
+  return results;
+}
+function checkBaseKeySchema(physical, entities) {
+  const withSk = [];
+  const withoutSk = [];
+  for (const meta of entities) {
+    if (!meta.primaryKey) continue;
+    const hasSk = meta.primaryKey.segmented.skSegments.length > 0;
+    (hasSk ? withSk : withoutSk).push(meta.prefix);
+  }
+  if (withSk.length > 0 && withoutSk.length > 0) {
+    const offender = [...withSk, ...withoutSk].sort()[0];
+    return [
+      err3(
+        offender,
+        `CloudFormation schema consistency: physical table '${physical}' has an ambiguous base KeySchema \u2014 some entities declare a sort key and some do not (with SK: [${withSk.join(", ")}]; without SK: [${withoutSk.join(", ")}]). A single DynamoDB table has exactly one KeySchema; every entity sharing a table must agree on whether the base key has an SK.`
+      )
+    ];
+  }
+  return [];
+}
+function checkGsiUnion(physical, entities) {
+  const results = [];
+  const seen = /* @__PURE__ */ new Map();
+  for (const meta of entities) {
+    for (const gsi2 of meta.gsiDefinitions) {
+      const shape = gsiShape(gsi2);
+      const existing = seen.get(shape.indexName);
+      if (!existing) {
+        seen.set(shape.indexName, { shape, entity: meta.prefix });
+        continue;
+      }
+      const conflict = describeConflict(existing.shape, shape);
+      if (conflict) {
+        results.push(
+          err3(
+            meta.prefix,
+            `CloudFormation schema consistency: GSI '${shape.indexName}' on physical table '${physical}' is declared inconsistently across entities that share it \u2014 ${conflict} (first declared by '${existing.entity}', conflicting declaration on '${meta.prefix}'). A single DynamoDB table has exactly one GSI per index name; entities may share an index name (projecting different logical fields into the shared physical key), but only when its physical key structure (sort-key presence) is identical.`
+          )
+        );
+      }
+    }
+  }
+  if (seen.size > MAX_GSIS_PER_TABLE) {
+    const names = [...seen.keys()].sort();
+    const offender = [...entities].map((e) => e.prefix).sort()[0];
+    results.push(
+      err3(
+        offender,
+        `CloudFormation schema consistency: physical table '${physical}' would have ${seen.size} global secondary indexes after unioning across entities, exceeding the DynamoDB limit of ${MAX_GSIS_PER_TABLE}. Distinct index names: [${names.join(", ")}]. Reduce the number of distinct GSIs on this table.`
+      )
+    );
+  }
+  return results;
+}
+function describeConflict(a, b) {
+  if (a.hasSk !== b.hasSk) {
+    return `one declaration has a sort key and the other does not (${a.hasSk ? "with" : "without"} SK vs. ${b.hasSk ? "with" : "without"} SK)`;
+  }
+  return null;
+}
+
 // src/linter/default-linter.ts
 function createDefaultLinter() {
   const linter = new Linter();
@@ -857,6 +978,7 @@ function createDefaultLinter() {
   linter.addRule(hotPartitionRule);
   linter.addRule(fanOutRule);
   linter.addRule(multiMaintainerSameRowRule);
+  linter.addRule(cfnSchemaConsistencyRule);
   return linter;
 }
 
@@ -909,6 +1031,25 @@ var MetadataRegistry = class {
     }
     return new Map(this.store);
   }
+  /**
+   * Snapshot of the entities that are **already finalized**, WITHOUT triggering
+   * finalize on any pending entity (unlike {@link getAll}). This is the safe view
+   * for a cross-entity lint rule that runs *inside* `finalize`: eagerly
+   * finalizing the rest of the registry from within a finalize pass would
+   * re-enter (and duplicate) the in-progress entity's finalize. A whole-registry
+   * rule instead reasons over the already-finalized peers plus the entity
+   * currently being checked; any conflicting pair is caught when the later of the
+   * two finalizes (both are present by then).
+   *
+   * @internal — for cross-entity linter rules.
+   */
+  static getFinalized() {
+    const out = /* @__PURE__ */ new Map();
+    for (const [target, meta] of this.store) {
+      if (meta._finalized) out.set(target, meta);
+    }
+    return out;
+  }
   static get linter() {
     return this._linter;
   }
@@ -968,20 +1109,78 @@ ${messages}`);
   }
 };
 
-// src/client/TableMapping.ts
-var TableMapping = class {
-  static mapping = {};
-  static set(mapping) {
-    this.mapping = { ...mapping };
+// src/types/select-builder.ts
+var SELECT_BUILDER = /* @__PURE__ */ Symbol.for("graphddb.selectBuilder");
+var SELECT_SPEC = /* @__PURE__ */ Symbol.for("graphddb.selectSpec");
+
+// src/select/builder.ts
+var BuilderImpl = class _BuilderImpl {
+  [SELECT_BUILDER] = true;
+  /** The resolved spec, exposed (non-method) so normalizers can read it. */
+  [SELECT_SPEC];
+  constructor(spec) {
+    this[SELECT_SPEC] = spec;
   }
-  static resolve(declaredName) {
-    return this.mapping[declaredName] ?? declaredName;
+  clone(patch) {
+    return new _BuilderImpl({ ...this[SELECT_SPEC], ...patch });
   }
-  /** @internal — for testing only */
-  static reset() {
-    this.mapping = {};
+  filter(filter) {
+    return this.clone({ filter });
+  }
+  limit(limit) {
+    return this.clone({ limit });
+  }
+  after(cursor) {
+    return this.clone({ after: cursor });
+  }
+  order(order) {
+    return this.clone({ order });
   }
 };
+function isSelectBuilder(value) {
+  return typeof value === "object" && value !== null && value[SELECT_BUILDER] === true;
+}
+function fromBuilder(value) {
+  const spec = value[SELECT_SPEC];
+  return {
+    select: spec.select,
+    filter: spec.filter,
+    limit: spec.limit,
+    after: spec.after,
+    order: spec.order
+  };
+}
+function normalizeSelectSpec(value) {
+  if (isSelectBuilder(value)) {
+    return fromBuilder(value);
+  }
+  const obj = value;
+  return {
+    select: obj.select,
+    filter: obj.filter,
+    limit: obj.limit,
+    after: obj.after,
+    order: obj.order
+  };
+}
+function normalizeTopLevelSelect(value) {
+  if (isSelectBuilder(value)) {
+    return fromBuilder(value);
+  }
+  return { select: value ?? {} };
+}
+function buildProject(select) {
+  return new BuilderImpl({
+    [SELECT_BUILDER]: true,
+    select
+  });
+}
+function buildRelation(select) {
+  return new BuilderImpl({
+    [SELECT_BUILDER]: true,
+    select
+  });
+}
 
 // src/define/param.ts
 function isParamOptions(value) {
@@ -2334,14 +2533,14 @@ var MiddlewareRuntime = class {
    * is the host's responsibility — a hook recovering a `query` should return an
    * item / `null`, one recovering a `list` a `{ items, cursor }`.
    */
-  async runRequestError(ctx, err3) {
+  async runRequestError(ctx, err4) {
     for (let i = this.chain.length - 1; i >= 0; i--) {
       const onError = this.chain[i].read?.onError;
       if (!onError) continue;
-      const recovered = await onError(ctx, err3);
+      const recovered = await onError(ctx, err4);
       if (recovered !== void 0) return recovered;
     }
-    throw err3;
+    throw err4;
   }
   /**
    * Drive ONE physical op (root read or any fan-out fetch) through R2 → send →
@@ -2381,14 +2580,14 @@ var MiddlewareRuntime = class {
         if (afterFetch) items = await afterFetch(ctx, items);
       }
       return items;
-    } catch (err3) {
+    } catch (err4) {
       for (let i = this.chain.length - 1; i >= 0; i--) {
         const onError = this.chain[i].read?.op?.onError;
         if (!onError) continue;
-        const recovered = await onError(ctx, err3);
+        const recovered = await onError(ctx, err4);
         if (recovered !== void 0) return recovered;
       }
-      throw err3;
+      throw err4;
     }
   }
 };
@@ -2452,14 +2651,14 @@ var WriteRuntime = class {
    * short-circuits the chain); the value becomes the write's resolved value.
    * Otherwise the original error rethrows (symmetric with the read `onError`).
    */
-  async runWriteError(ctx, err3) {
+  async runWriteError(ctx, err4) {
     for (let i = this.chain.length - 1; i >= 0; i--) {
       const onError = this.chain[i].write?.onError;
       if (!onError) continue;
-      const recovered = await onError(ctx, err3);
+      const recovered = await onError(ctx, err4);
       if (recovered !== void 0) return recovered;
     }
-    throw err3;
+    throw err4;
   }
   /** Build a W3/W4/W5 persist context (pure — no hooks run). */
   persistCtx(items, origins, transaction) {
@@ -2488,20 +2687,20 @@ var WriteRuntime = class {
         if (before) await before(ctx);
       }
       results = await send(ctx.items);
-    } catch (err3) {
+    } catch (err4) {
       let recovered;
       let didRecover = false;
       for (let i = this.chain.length - 1; i >= 0; i--) {
         const onError = this.chain[i].write?.persist?.onError;
         if (!onError) continue;
-        const r = await onError(ctx, err3);
+        const r = await onError(ctx, err4);
         if (r !== void 0) {
           recovered = r;
           didRecover = true;
           break;
         }
       }
-      if (!didRecover) throw err3;
+      if (!didRecover) throw err4;
       results = recovered;
     }
     for (let i = this.chain.length - 1; i >= 0; i--) {
@@ -2722,8 +2921,8 @@ async function executeSingleWriteWithHooks(req, mw) {
     await mw.runWriteBefore(ctx);
     const change2 = await persistRewrittenWrite(req.modelClass, ctx, mw);
     await mw.runWriteAfter(ctx, change2);
-  } catch (err3) {
-    await mw.runWriteError(ctx, err3);
+  } catch (err4) {
+    await mw.runWriteError(ctx, err4);
   }
 }
 async function persistRewrittenWrite(modelClass, ctx, mw) {
@@ -3437,6 +3636,80 @@ function buildLogicalItem(modelClass, ctx) {
   return { Delete: buildDeleteInput(modelClass, ctx.input.key ?? {}, opts) };
 }
 
+// src/hydrator/hydrator.ts
+function hydrate(rawItems, select, metadata, updatable = false) {
+  return rawItems.map((item) => hydrateItem(item, select, metadata, updatable));
+}
+function hydrateItem(raw, select, metadata, updatable = false) {
+  const fieldMap = new Map(
+    metadata.fields.map((f) => [f.propertyName, f])
+  );
+  const embeddedMap = new Map(
+    metadata.embeddedFields.map((e) => [e.propertyName, e])
+  );
+  const result = {};
+  for (const [fieldName, selectValue] of Object.entries(select)) {
+    if (selectValue === true) {
+      const value = raw[fieldName];
+      if (value !== void 0) {
+        const fieldMeta = fieldMap.get(fieldName);
+        result[fieldName] = deserializeValue(value, fieldMeta);
+      }
+    } else if (typeof selectValue === "object" && selectValue !== null) {
+      if ("select" in selectValue || isSelectBuilder(selectValue)) {
+        continue;
+      }
+      const rawEmb = raw[fieldName];
+      if (rawEmb && typeof rawEmb === "object") {
+        result[fieldName] = hydrateEmbedded(
+          rawEmb,
+          selectValue,
+          metadata,
+          fieldName
+        );
+      }
+    }
+  }
+  if (updatable) {
+    attachHiddenKey(result, raw);
+  }
+  return result;
+}
+function hydrateEmbedded(raw, select, _metadata, _fieldName) {
+  const result = {};
+  for (const [key2, selectValue] of Object.entries(select)) {
+    if (selectValue === true) {
+      if (raw[key2] !== void 0) {
+        result[key2] = raw[key2];
+      }
+    } else if (typeof selectValue === "object" && selectValue !== null && !("select" in selectValue)) {
+      const nested = raw[key2];
+      if (nested && typeof nested === "object") {
+        result[key2] = hydrateEmbedded(
+          nested,
+          selectValue,
+          _metadata,
+          key2
+        );
+      }
+    }
+  }
+  return result;
+}
+function deserializeValue(value, fieldMeta) {
+  if (!fieldMeta) return value;
+  if (fieldMeta.options?.deserialize) {
+    return fieldMeta.options.deserialize(value);
+  }
+  if (fieldMeta.options?.format === "datetime" && typeof value === "string") {
+    return new Date(value);
+  }
+  if (fieldMeta.options?.format === "date" && typeof value === "string") {
+    return /* @__PURE__ */ new Date(value + "T00:00:00.000Z");
+  }
+  return value;
+}
+
 // src/define/entity-writes.ts
 var MAINTAIN_TRIGGER_RE = /^[^.\s$[\]*]+\.(?:created|updated|removed)$/;
 function maintainTrigger(value) {
@@ -4272,6 +4545,100 @@ function buildMaintenanceGraphImpl(registry, views) {
   };
 }
 
+// src/cdc/from-change.ts
+function buildFullSelect(metadata) {
+  const select = {};
+  for (const field of metadata.fields) {
+    select[field.propertyName] = true;
+  }
+  return select;
+}
+function eventOwnedBy(event, metadata, modelName) {
+  if (event.model !== void 0) {
+    return event.model === modelName;
+  }
+  return metadata.prefix.length > 0 && event.keys.pk.startsWith(metadata.prefix);
+}
+function hydrateImage(image, select, metadata, modelClass) {
+  if (image === void 0) return null;
+  const [hydrated] = hydrate([image], select, metadata);
+  const instance = new modelClass();
+  Object.assign(instance, hydrated);
+  for (const emb of metadata.embeddedFields) {
+    const rawEmb = image[emb.propertyName];
+    if (rawEmb !== void 0 && rawEmb !== null) {
+      instance[emb.propertyName] = rawEmb;
+    }
+  }
+  return instance;
+}
+function parseChange(event, metadata, modelName, modelClass) {
+  if (!eventOwnedBy(event, metadata, modelName)) {
+    return [null, null];
+  }
+  const select = buildFullSelect(metadata);
+  const oldRecord = hydrateImage(event.oldImage, select, metadata, modelClass);
+  const newRecord = hydrateImage(event.newImage, select, metadata, modelClass);
+  return [oldRecord, newRecord];
+}
+
+// src/cdc/subscribe.ts
+function resolveRoutableModels(handlers) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const [cls, meta] of MetadataRegistry.getAll()) {
+    byName.set(cls.name, { cls, meta });
+  }
+  const routable = /* @__PURE__ */ new Map();
+  for (const modelName of Object.keys(handlers)) {
+    const entry = byName.get(modelName);
+    if (!entry) {
+      throw new Error(
+        `DDBModel.subscribe: no model named '${modelName}' is registered. Did you import the model module (so its @model decorator ran) and spell the handler key exactly as the class name?`
+      );
+    }
+    if (!entry.meta.cdcProjected) {
+      throw new Error(
+        `DDBModel.subscribe: model '${modelName}' is not @cdcProjected, so its change events cannot be parsed. Add @cdcProjected() to the model, or remove its handler.`
+      );
+    }
+    routable.set(modelName, {
+      modelClass: entry.cls,
+      metadata: entry.meta,
+      modelName
+    });
+  }
+  return routable;
+}
+async function dispatchEvent(event, routable, handlers) {
+  for (const { modelClass, metadata, modelName } of routable.values()) {
+    const [oldRecord, newRecord] = parseChange(
+      event,
+      metadata,
+      modelName,
+      modelClass
+    );
+    if (oldRecord === null && newRecord === null) continue;
+    const handler = handlers[modelName];
+    await handler(oldRecord, newRecord);
+    return true;
+  }
+  return false;
+}
+function buildSubscribeHandler(handlers) {
+  const routable = resolveRoutableModels(handlers);
+  return async (batch) => {
+    const batchItemFailures = [];
+    for (const event of batch.records) {
+      try {
+        await dispatchEvent(event, routable, handlers);
+      } catch {
+        batchItemFailures.push(event.sequenceNumber);
+      }
+    }
+    return { batchItemFailures };
+  };
+}
+
 export {
   isColumn,
   createColumnMap,
@@ -4287,12 +4654,17 @@ export {
   resolveKey,
   missingGsiRule,
   relationDepthRule,
+  TableMapping,
   createDefaultLinter,
   MetadataRegistry,
-  TableMapping,
   pkTemplate,
   skTemplate,
   resolveSegmentedKey,
+  isSelectBuilder,
+  normalizeSelectSpec,
+  normalizeTopLevelSelect,
+  buildProject,
+  buildRelation,
   param,
   isParam,
   BATCH_GET_MAX_KEYS,
@@ -4335,6 +4707,7 @@ export {
   resolveModelClass,
   TransactionContext,
   executeTransaction,
+  hydrate,
   maintainTrigger,
   isMaintainTrigger,
   preview,
@@ -4347,5 +4720,7 @@ export {
   getEntityWrites,
   lifecyclePhaseForIntent,
   collectViewDefinitions,
-  buildMaintenanceGraph
+  buildMaintenanceGraph,
+  parseChange,
+  buildSubscribeHandler
 };

package/dist/{chunk-BROCT574.js → chunk-EMJHTUA4.js}

@@ -7,7 +7,7 @@ import {
   buildMaintenanceGraph,
   buildPutInput,
   resolveModelClass
-} from "./chunk-CPTV3H2U.js";
+} from "./chunk-B3GWIWT6.js";
 
 // src/cdc/prng.ts
 var SeededRandom = class {