graphddb 0.5.0 → 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,11 @@ 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).
@@ -225,6 +231,7 @@ 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. |
 

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

@@ -1109,6 +1109,79 @@ ${messages}`);
   }
 };
 
+// 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;
+  }
+  clone(patch) {
+    return new _BuilderImpl({ ...this[SELECT_SPEC], ...patch });
+  }
+  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) {
   return typeof value === "object" && value !== null;
@@ -3563,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) {
@@ -4398,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,
@@ -4419,6 +4660,11 @@ export {
   pkTemplate,
   skTemplate,
   resolveSegmentedKey,
+  isSelectBuilder,
+  normalizeSelectSpec,
+  normalizeTopLevelSelect,
+  buildProject,
+  buildRelation,
   param,
   isParam,
   BATCH_GET_MAX_KEYS,
@@ -4461,6 +4707,7 @@ export {
   resolveModelClass,
   TransactionContext,
   executeTransaction,
+  hydrate,
   maintainTrigger,
   isMaintainTrigger,
   preview,
@@ -4473,5 +4720,7 @@ export {
   getEntityWrites,
   lifecyclePhaseForIntent,
   collectViewDefinitions,
-  buildMaintenanceGraph
+  buildMaintenanceGraph,
+  parseChange,
+  buildSubscribeHandler
 };

package/dist/{chunk-7NPG5R7O.js → chunk-EMJHTUA4.js}

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

package/dist/{chunk-J5A665UW.js → chunk-FI63YKK5.js}

@@ -11,8 +11,11 @@ import {
   buildConditionExpression,
   buildDeleteInput,
   buildMaintenanceGraph,
+  buildProject,
   buildPutInput,
   buildReadRuntime,
+  buildRelation,
+  buildSubscribeHandler,
   buildUpdateInput,
   buildWriteRuntime,
   captureWrite,
@@ -27,13 +30,18 @@ import {
   executeTransaction,
   executeUpdate,
   getEntityWrites,
+  hydrate,
   isColumn,
   isEntityWritesDefinition,
   isLifecycleContract,
   isParam,
   isRawCondition,
+  isSelectBuilder,
   lifecyclePhaseForIntent,
+  normalizeSelectSpec,
+  normalizeTopLevelSelect,
   param,
+  parseChange,
   pkTemplate,
   resolveKey,
   resolveModelClass,
@@ -42,7 +50,7 @@ import {
   serializeFieldValue,
   serializeRawCondition,
   skTemplate
-} from "./chunk-FMJIWFIS.js";
+} from "./chunk-B3GWIWT6.js";
 
 // src/spec/types.ts
 var SPEC_VERSION = "1.0";
@@ -174,79 +182,6 @@ function buildManifest(registry = MetadataRegistry) {
   };
 }
 
-// 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;
-  }
-  clone(patch) {
-    return new _BuilderImpl({ ...this[SELECT_SPEC], ...patch });
-  }
-  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/relation/detect.ts
 function isRelationSpec(value) {
   if (typeof value !== "object" || value === null) return false;
@@ -726,80 +661,6 @@ async function execute(operation, options) {
   return ClientManager.getExecutor().execute(operation, options);
 }
 
-// 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 [key, selectValue] of Object.entries(select)) {
-    if (selectValue === true) {
-      if (raw[key] !== void 0) {
-        result[key] = raw[key];
-      }
-    } else if (typeof selectValue === "object" && selectValue !== null && !("select" in selectValue)) {
-      const nested = raw[key];
-      if (nested && typeof nested === "object") {
-        result[key] = hydrateEmbedded(
-          nested,
-          selectValue,
-          _metadata,
-          key
-        );
-      }
-    }
-  }
-  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/pagination/cursor.ts
 function encodeCursor(lastEvaluatedKey) {
   const json = JSON.stringify(lastEvaluatedKey);
@@ -3116,6 +2977,58 @@ var DDBModel = class {
   static mutate(envelope, options) {
     return executeWriteEnvelope(envelope, options);
   }
+  /**
+   * Parse a single CDC {@link ChangeEvent} into the `[oldRecord, newRecord]` tuple
+   * for THIS model (issue #153 — the pure `(event) => [old, new]` typed mapper).
+   * It reuses the read path's `hydrate` on `oldImage` / `newImage` (ISO 8601 →
+   * `Date` for `@datetime`, embedded reconstruction) and returns typed instances of
+   * this model — **all fields**, no projection (narrowing does not reduce cost; the
+   * image is already on the stream).
+   *
+   * Routing + parse in one call: an event for a DIFFERENT model returns
+   * `[null, null]` (a valid event for this model always has ≥1 non-null side, so
+   * `[null, null]` is an unambiguous "not for this class" signal — no separate
+   * `owns()` guard). The present side per event kind mirrors DynamoDB Streams:
+   * INSERT → `[null, new]`, MODIFY → `[old, new]`, REMOVE → `[old, null]`.
+   *
+   * Only callable on a `@cdcProjected` model — the generated {@link CdcModelRegistry}
+   * types this at the `subscribe` surface, and at runtime a non-`@cdcProjected` model
+   * throws (loudly, never silently returning `[null, null]`, which would masquerade
+   * as a routing miss). Delivery / sink writes / dedup are the consumer's, outside
+   * this boundary (see `docs/cdc-projection.md`).
+   */
+  static fromChange(event) {
+    const modelClass = this;
+    const metadata = MetadataRegistry.get(modelClass);
+    if (!metadata.cdcProjected) {
+      throw new Error(
+        `${modelClass.name}.fromChange: model '${modelClass.name}' is not @cdcProjected, so its change events cannot be parsed. Add @cdcProjected() to the model.`
+      );
+    }
+    return parseChange(event, metadata, modelClass.name, modelClass);
+  }
+  /**
+   * Build a batch CDC {@link ChangeHandler} from an envelope-style handler map keyed
+   * by model name (issue #153 — the GraphQL query/mutation/**subscription** trio's
+   * third sibling). Unlike `query` / `mutate`, `subscribe` DOES NOT subscribe and
+   * does not hit DynamoDB: it *returns* a `(batch) => Promise<BatchResult>` the
+   * consumer mounts on their own stream source (the CDC emulator locally, DynamoDB
+   * Streams → Lambda in production) — delivery lives outside the boundary.
+   *
+   * The returned handler loops the batch, routes each event to its owning model by
+   * `event.model` / `keys.pk`, typed-parses via that model's `fromChange`, calls the
+   * matching handler, and — if a handler throws — records the event's
+   * `sequenceNumber` into `batchItemFailures` (the `ReportBatchItemFailures`
+   * redelivery protocol) and continues. It NEVER writes a sink and NEVER dedups
+   * (both are consumer concerns). Handler keys are constrained to the generated
+   * {@link CdcModelRegistry} (`@cdcProjected` models only); a key that is not a
+   * registered `@cdcProjected` model throws at build time.
+   */
+  static subscribe(handlers) {
+    return buildSubscribeHandler(
+      handlers
+    );
+  }
   /**
    * Multi-key, multi-model batch read. Each {@link BatchGetRequest} contributes its
    * keys to a chunked `BatchGetItem` per physical table; results are re-grouped by
@@ -7022,8 +6935,6 @@ export {
   SPEC_VERSION,
   MARKER_ROW_ENTITY,
   buildManifest,
-  isSelectBuilder,
-  normalizeSelectSpec,
   detectRelationFields,
   getImplicitKeyFields,
   buildProjection,
@@ -7031,7 +6942,6 @@ export {
   evaluateFilter,
   plan,
   execute,
-  hydrate,
   encodeCursor,
   decodeCursor,
   executeListInternal,

package/dist/cli.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import {
   buildBridgeBundle,
-  buildManifest,
-  normalizeSelectSpec
-} from "./chunk-J5A665UW.js";
+  buildManifest
+} from "./chunk-FI63YKK5.js";
 import {
-  MetadataRegistry
-} from "./chunk-FMJIWFIS.js";
+  MetadataRegistry,
+  normalizeSelectSpec
+} from "./chunk-B3GWIWT6.js";
 
 // src/cli.ts
 import { createRequire } from "module";
@@ -568,7 +568,7 @@ function createProgram(handlers2, version) {
 
 // src/cli/handlers.ts
 import { mkdirSync, writeFileSync } from "fs";
-import { dirname } from "path";
+import { dirname, relative } from "path";
 import { pathToFileURL } from "url";
 import { isAbsolute, resolve } from "path";
 
@@ -1416,6 +1416,40 @@ function emitCloudformation(manifest, options = {}) {
   return (options.format ?? "yaml") === "json" ? templateToJson(template) : templateToYaml(template);
 }
 
+// src/codegen/cdc-registry.ts
+var TS_HEADER = PY_HEADER.replace("# ", "// ");
+function cdcProjectedModelNames(registry = MetadataRegistry) {
+  const names = [];
+  for (const [cls, metadata] of registry.getAll()) {
+    if (metadata.cdcProjected) names.push(cls.name);
+  }
+  return names.sort();
+}
+function generateCdcRegistry(options = {}) {
+  const registry = options.registry ?? MetadataRegistry;
+  const modelsModule = options.modelsModule ?? "./models.js";
+  const names = cdcProjectedModelNames(registry);
+  const lines = [TS_HEADER, ""];
+  if (names.length === 0) {
+    lines.push(
+      "// (no @cdcProjected models \u2014 nothing to augment CdcModelRegistry with)",
+      "",
+      "export {};",
+      ""
+    );
+    return lines.join("\n");
+  }
+  for (const name of names) {
+    lines.push(`import type { ${name} } from '${modelsModule}';`);
+  }
+  lines.push("", "declare module 'graphddb' {", "  interface CdcModelRegistry {");
+  for (const name of names) {
+    lines.push(`    ${name}: ${name};`);
+  }
+  lines.push("  }", "}", "");
+  return lines.join("\n");
+}
+
 // src/codegen/index.ts
 var OUTPUT_FILES = [
   "manifest.json",
@@ -1528,11 +1562,24 @@ var handlers = {
       for (const name of OUTPUT_FILES) {
         writeFileSync(resolve(outDir, name), files[name], "utf8");
       }
+      const emittedFiles = [...OUTPUT_FILES];
+      if (cdcProjectedModelNames().length > 0) {
+        const entryAbs = isAbsolute(entry) ? entry : resolve(process.cwd(), entry);
+        let modelsModule = relative(outDir, entryAbs).replace(/\\/g, "/").replace(/\.[mc]?ts$/, "");
+        if (!modelsModule.startsWith(".")) modelsModule = `./${modelsModule}`;
+        const cdcRegistryFile = "cdc-registry.ts";
+        writeFileSync(
+          resolve(outDir, cdcRegistryFile),
+          generateCdcRegistry({ modelsModule }),
+          "utf8"
+        );
+        emittedFiles.push(cdcRegistryFile);
+      }
       process.stdout.write(
         JSON.stringify({
           status: "ok",
           outDir: out,
-          files: [...OUTPUT_FILES]
+          files: emittedFiles
         }) + "\n"
       );
     } catch (err) {