graphddb 0.4.3 → 0.5.1

package/dist/cli.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import {
   buildBridgeBundle,
-  normalizeSelectSpec
-} from "./chunk-G5RWWBAL.js";
+  buildManifest
+} from "./chunk-FI63YKK5.js";
 import {
-  MetadataRegistry
-} from "./chunk-CPTV3H2U.js";
+  MetadataRegistry,
+  normalizeSelectSpec
+} from "./chunk-B3GWIWT6.js";
 
 // src/cli.ts
 import { createRequire } from "module";
@@ -299,6 +300,146 @@ var commandDefinitions = {
         }
       }
     ]
+  },
+  "generate.cloudformation": {
+    "effects": {
+      "risk_level": "low",
+      "reads": [
+        "ts-definitions"
+      ],
+      "writes": [
+        "generated-code"
+      ]
+    },
+    "options": [
+      {
+        "name": "entry",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "media_type": "application/typescript",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "out",
+        "schema": {
+          "type": "string"
+        }
+      },
+      {
+        "name": "format",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "yaml",
+            "json"
+          ],
+          "default": "yaml"
+        }
+      },
+      {
+        "name": "gsi-projection",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "ALL",
+            "KEYS_ONLY"
+          ],
+          "default": "ALL"
+        }
+      },
+      {
+        "name": "stream",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "auto",
+            "on",
+            "off"
+          ],
+          "default": "auto"
+        }
+      },
+      {
+        "name": "billing-mode",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "PAY_PER_REQUEST",
+            "PROVISIONED"
+          ],
+          "default": "PAY_PER_REQUEST"
+        }
+      },
+      {
+        "name": "rcu",
+        "schema": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      {
+        "name": "wcu",
+        "schema": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      {
+        "name": "autoscale",
+        "schema": {
+          "type": "boolean"
+        }
+      },
+      {
+        "name": "autoscale-min",
+        "schema": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      {
+        "name": "autoscale-max",
+        "schema": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      {
+        "name": "autoscale-target",
+        "schema": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100
+        }
+      },
+      {
+        "name": "pitr",
+        "schema": {
+          "type": "boolean"
+        }
+      },
+      {
+        "name": "table-class",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "STANDARD",
+            "STANDARD_INFREQUENT_ACCESS"
+          ]
+        }
+      },
+      {
+        "name": "sse",
+        "schema": {
+          "type": "boolean"
+        }
+      }
+    ]
   }
 };
 function deriveCommandPolicy(command_id, optionValues) {
@@ -325,8 +466,8 @@ function deriveCommandPolicy(command_id, optionValues) {
 }
 
 // src/generated/contract.ts
-var CONTRACT_YAML = "cli_contracts: 0.1.0\n\ninfo:\n  title: GraphDDB CLI\n  version: 0.1.0\n  description: >-\n    Contract for the graphddb code-generation CLI. The CLI reads TypeScript\n    GraphDDB model / query / command definitions (the single source of truth)\n    and emits Python bindings (manifest.json, operations.json, types.py,\n    repositories.py, __init__.py) for the Python bridge runtime.\n  license:\n    name: MIT\n  contact:\n    name: foo-log-inc\n    url: https://github.com/foo-log-inc/graphddb\n\nartifact_slots:\n  ts-definitions:\n    description: >-\n      TypeScript GraphDDB definition modules (entity models, defineQueries,\n      defineCommands) used as the single source of truth.\n    direction: read\n  generated-code:\n    description: >-\n      Generated Python bindings and JSON specs written to the output directory\n      (manifest.json, operations.json, types.py, repositories.py, __init__.py).\n    direction: write\n\ncommand_sets:\n  graphddb:\n    summary: Graph data modeling on DynamoDB \u2014 code generation CLI.\n    x-stdin: >-\n      No command reads from stdin. All inputs are provided via file options.\n\n    commands:\n      # \u2500\u2500 generate python \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n      generate.python:\n        summary: Generate Python bindings from TypeScript GraphDDB definitions.\n        description: >-\n          Loads the TypeScript entity models, query definitions, and command\n          definitions, builds the serializable manifest / operations bundle, and\n          writes the Python bridge bindings (manifest.json, operations.json,\n          types.py, repositories.py, __init__.py) to the output directory.\n          Output is deterministic for a given set of inputs.\n        usage:\n          - graphddb generate python --entry models.ts --queries queries.ts --commands commands.ts --out generated/\n          - graphddb generate python --entry definitions.ts --out generated/\n\n        effects:\n          risk_level: low\n          reads:\n            - ts-definitions\n          writes:\n            - generated-code\n\n        x-agent:\n          recommended_before_use:\n            - \"Ensure the TypeScript definitions type-check and lint cleanly.\"\n\n        options:\n          - name: entry\n            aliases: [e]\n            required: true\n            description: >-\n              Entry module that registers the entity models (side-effecting\n              import). May also export queries / commands.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: queries\n            aliases: [q]\n            description: >-\n              Module exporting `queries` (a defineQueries map). Defaults to the\n              entry module when omitted.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: commands\n            aliases: [c]\n            description: >-\n              Module exporting `commands` (a defineCommands map). Defaults to the\n              entry module when omitted.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: transactions\n            aliases: [t]\n            description: >-\n              Module exporting `transactions` (a defineTransactions map).\n              Defaults to the commands module (or the entry module) when omitted.\n              Optional \u2014 a project with no declarative transactions omits it.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: contracts\n            description: >-\n              Module exporting `contracts` (a map of publicQueryModel /\n              publicCommandModel results \u2014 the CQRS Contract layer). Defaults to\n              the entry module when omitted. Optional \u2014 a project with no\n              contracts omits it, and the output gains no `contracts` content.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: contexts\n            description: >-\n              Module exporting `contexts` (context-ownership: context name \u2192 the\n              Model / Contract names that belong to it). Defaults to the\n              contracts module (or the entry module) when omitted. Optional \u2014\n              consumed by the boundary lint to tell own from foreign.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: dataclass\n            description: >-\n              Emit Python result / element types as @dataclass classes instead\n              of TypedDict (decimal / Optional / Connection mapped accordingly).\n            schema:\n              type: boolean\n\n          - name: out\n            aliases: [o]\n            required: true\n            description: Output directory for the generated Python bindings.\n            value_name: dir\n            schema:\n              type: string\n\n        exits:\n          '0':\n            description: Generation succeeded.\n            stdout:\n              format: json\n              schema:\n                $ref: '#/components/schemas/GenerateResult'\n            files:\n              - path: '{options.out}/manifest.json'\n                required: true\n                media_type: application/json\n                description: Entity / table / key / relation metadata.\n              - path: '{options.out}/operations.json'\n                required: true\n                media_type: application/json\n                description: Per-query / per-command execution specs.\n              - path: '{options.out}/types.py'\n                required: true\n                media_type: text/x-python\n                description: TypedDict result types derived from query selects.\n              - path: '{options.out}/repositories.py'\n                required: true\n                media_type: text/x-python\n                description: Per-entity repository classes (sync methods).\n              - path: '{options.out}/__init__.py'\n                required: true\n                media_type: text/x-python\n                description: Package re-exports for the generated bindings.\n\n          '1':\n            description: Unexpected error.\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\n          '2':\n            description: Invalid arguments (missing/unreadable input or output).\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\ncomponents:\n  schemas:\n    GenerateResult:\n      type: object\n      required: [status, outDir, files]\n      properties:\n        status:\n          type: string\n          enum: [ok]\n        outDir:\n          type: string\n          description: Output directory the files were written to.\n        files:\n          type: array\n          description: Paths of the generated files (relative to outDir).\n          items:\n            type: string\n    Error:\n      type: object\n      required: [code, message]\n      properties:\n        code:\n          type: string\n        message:\n          type: string\n";
-var CONTRACT_JSON_STR = '{\n  "cli_contracts": "0.1.0",\n  "info": {\n    "title": "GraphDDB CLI",\n    "version": "0.1.0",\n    "description": "Contract for the graphddb code-generation CLI. The CLI reads TypeScript GraphDDB model / query / command definitions (the single source of truth) and emits Python bindings (manifest.json, operations.json, types.py, repositories.py, __init__.py) for the Python bridge runtime.",\n    "license": {\n      "name": "MIT"\n    },\n    "contact": {\n      "name": "foo-log-inc",\n      "url": "https://github.com/foo-log-inc/graphddb"\n    }\n  },\n  "artifact_slots": {\n    "ts-definitions": {\n      "description": "TypeScript GraphDDB definition modules (entity models, defineQueries, defineCommands) used as the single source of truth.",\n      "direction": "read"\n    },\n    "generated-code": {\n      "description": "Generated Python bindings and JSON specs written to the output directory (manifest.json, operations.json, types.py, repositories.py, __init__.py).",\n      "direction": "write"\n    }\n  },\n  "command_sets": {\n    "graphddb": {\n      "summary": "Graph data modeling on DynamoDB \u2014 code generation CLI.",\n      "x-stdin": "No command reads from stdin. All inputs are provided via file options.",\n      "commands": {\n        "generate.python": {\n          "summary": "Generate Python bindings from TypeScript GraphDDB definitions.",\n          "description": "Loads the TypeScript entity models, query definitions, and command definitions, builds the serializable manifest / operations bundle, and writes the Python bridge bindings (manifest.json, operations.json, types.py, repositories.py, __init__.py) to the output directory. Output is deterministic for a given set of inputs.",\n          "usage": [\n            "graphddb generate python --entry models.ts --queries queries.ts --commands commands.ts --out generated/",\n            "graphddb generate python --entry definitions.ts --out generated/"\n          ],\n          "effects": {\n            "risk_level": "low",\n            "reads": [\n              "ts-definitions"\n            ],\n            "writes": [\n              "generated-code"\n            ]\n          },\n          "x-agent": {\n            "recommended_before_use": [\n              "Ensure the TypeScript definitions type-check and lint cleanly."\n            ]\n          },\n          "options": [\n            {\n              "name": "entry",\n              "aliases": [\n                "e"\n              ],\n              "required": true,\n              "description": "Entry module that registers the entity models (side-effecting import). May also export queries / commands.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "queries",\n              "aliases": [\n                "q"\n              ],\n              "description": "Module exporting `queries` (a defineQueries map). Defaults to the entry module when omitted.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "commands",\n              "aliases": [\n                "c"\n              ],\n              "description": "Module exporting `commands` (a defineCommands map). Defaults to the entry module when omitted.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "transactions",\n              "aliases": [\n                "t"\n              ],\n              "description": "Module exporting `transactions` (a defineTransactions map). Defaults to the commands module (or the entry module) when omitted. Optional \u2014 a project with no declarative transactions omits it.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "contracts",\n              "description": "Module exporting `contracts` (a map of publicQueryModel / publicCommandModel results \u2014 the CQRS Contract layer). Defaults to the entry module when omitted. Optional \u2014 a project with no contracts omits it, and the output gains no `contracts` content.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "contexts",\n              "description": "Module exporting `contexts` (context-ownership: context name \u2192 the Model / Contract names that belong to it). Defaults to the contracts module (or the entry module) when omitted. Optional \u2014 consumed by the boundary lint to tell own from foreign.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "dataclass",\n              "description": "Emit Python result / element types as @dataclass classes instead of TypedDict (decimal / Optional / Connection mapped accordingly).",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "out",\n              "aliases": [\n                "o"\n              ],\n              "required": true,\n              "description": "Output directory for the generated Python bindings.",\n              "value_name": "dir",\n              "schema": {\n                "type": "string"\n              }\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Generation succeeded.",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/GenerateResult"\n                }\n              },\n              "files": [\n                {\n                  "path": "{options.out}/manifest.json",\n                  "required": true,\n                  "media_type": "application/json",\n                  "description": "Entity / table / key / relation metadata."\n                },\n                {\n                  "path": "{options.out}/operations.json",\n                  "required": true,\n                  "media_type": "application/json",\n                  "description": "Per-query / per-command execution specs."\n                },\n                {\n                  "path": "{options.out}/types.py",\n                  "required": true,\n                  "media_type": "text/x-python",\n                  "description": "TypedDict result types derived from query selects."\n                },\n                {\n                  "path": "{options.out}/repositories.py",\n                  "required": true,\n                  "media_type": "text/x-python",\n                  "description": "Per-entity repository classes (sync methods)."\n                },\n                {\n                  "path": "{options.out}/__init__.py",\n                  "required": true,\n                  "media_type": "text/x-python",\n                  "description": "Package re-exports for the generated bindings."\n                }\n              ]\n            },\n            "1": {\n              "description": "Unexpected error.",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            },\n            "2": {\n              "description": "Invalid arguments (missing/unreadable input or output).",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  },\n  "components": {\n    "schemas": {\n      "GenerateResult": {\n        "type": "object",\n        "required": [\n          "status",\n          "outDir",\n          "files"\n        ],\n        "properties": {\n          "status": {\n            "type": "string",\n            "enum": [\n              "ok"\n            ]\n          },\n          "outDir": {\n            "type": "string",\n            "description": "Output directory the files were written to."\n          },\n          "files": {\n            "type": "array",\n            "description": "Paths of the generated files (relative to outDir).",\n            "items": {\n              "type": "string"\n            }\n          }\n        }\n      },\n      "Error": {\n        "type": "object",\n        "required": [\n          "code",\n          "message"\n        ],\n        "properties": {\n          "code": {\n            "type": "string"\n          },\n          "message": {\n            "type": "string"\n          }\n        }\n      }\n    }\n  }\n}';
+var CONTRACT_YAML = "cli_contracts: 0.1.0\n\ninfo:\n  title: GraphDDB CLI\n  version: 0.1.0\n  description: >-\n    Contract for the graphddb code-generation CLI. The CLI reads TypeScript\n    GraphDDB model / query / command definitions (the single source of truth)\n    and emits Python bindings (manifest.json, operations.json, types.py,\n    repositories.py, __init__.py) for the Python bridge runtime.\n  license:\n    name: MIT\n  contact:\n    name: foo-log-inc\n    url: https://github.com/foo-log-inc/graphddb\n\nartifact_slots:\n  ts-definitions:\n    description: >-\n      TypeScript GraphDDB definition modules (entity models, defineQueries,\n      defineCommands) used as the single source of truth.\n    direction: read\n  generated-code:\n    description: >-\n      Generated Python bindings and JSON specs written to the output directory\n      (manifest.json, operations.json, types.py, repositories.py, __init__.py).\n    direction: write\n\ncommand_sets:\n  graphddb:\n    summary: Graph data modeling on DynamoDB \u2014 code generation CLI.\n    x-stdin: >-\n      No command reads from stdin. All inputs are provided via file options.\n\n    commands:\n      # \u2500\u2500 generate python \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n      generate.python:\n        summary: Generate Python bindings from TypeScript GraphDDB definitions.\n        description: >-\n          Loads the TypeScript entity models, query definitions, and command\n          definitions, builds the serializable manifest / operations bundle, and\n          writes the Python bridge bindings (manifest.json, operations.json,\n          types.py, repositories.py, __init__.py) to the output directory.\n          Output is deterministic for a given set of inputs.\n        usage:\n          - graphddb generate python --entry models.ts --queries queries.ts --commands commands.ts --out generated/\n          - graphddb generate python --entry definitions.ts --out generated/\n\n        effects:\n          risk_level: low\n          reads:\n            - ts-definitions\n          writes:\n            - generated-code\n\n        x-agent:\n          recommended_before_use:\n            - \"Ensure the TypeScript definitions type-check and lint cleanly.\"\n\n        options:\n          - name: entry\n            aliases: [e]\n            required: true\n            description: >-\n              Entry module that registers the entity models (side-effecting\n              import). May also export queries / commands.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: queries\n            aliases: [q]\n            description: >-\n              Module exporting `queries` (a defineQueries map). Defaults to the\n              entry module when omitted.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: commands\n            aliases: [c]\n            description: >-\n              Module exporting `commands` (a defineCommands map). Defaults to the\n              entry module when omitted.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: transactions\n            aliases: [t]\n            description: >-\n              Module exporting `transactions` (a defineTransactions map).\n              Defaults to the commands module (or the entry module) when omitted.\n              Optional \u2014 a project with no declarative transactions omits it.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: contracts\n            description: >-\n              Module exporting `contracts` (a map of publicQueryModel /\n              publicCommandModel results \u2014 the CQRS Contract layer). Defaults to\n              the entry module when omitted. Optional \u2014 a project with no\n              contracts omits it, and the output gains no `contracts` content.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: contexts\n            description: >-\n              Module exporting `contexts` (context-ownership: context name \u2192 the\n              Model / Contract names that belong to it). Defaults to the\n              contracts module (or the entry module) when omitted. Optional \u2014\n              consumed by the boundary lint to tell own from foreign.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: dataclass\n            description: >-\n              Emit Python result / element types as @dataclass classes instead\n              of TypedDict (decimal / Optional / Connection mapped accordingly).\n            schema:\n              type: boolean\n\n          - name: out\n            aliases: [o]\n            required: true\n            description: Output directory for the generated Python bindings.\n            value_name: dir\n            schema:\n              type: string\n\n        exits:\n          '0':\n            description: Generation succeeded.\n            stdout:\n              format: json\n              schema:\n                $ref: '#/components/schemas/GenerateResult'\n            files:\n              - path: '{options.out}/manifest.json'\n                required: true\n                media_type: application/json\n                description: Entity / table / key / relation metadata.\n              - path: '{options.out}/operations.json'\n                required: true\n                media_type: application/json\n                description: Per-query / per-command execution specs.\n              - path: '{options.out}/types.py'\n                required: true\n                media_type: text/x-python\n                description: TypedDict result types derived from query selects.\n              - path: '{options.out}/repositories.py'\n                required: true\n                media_type: text/x-python\n                description: Per-entity repository classes (sync methods).\n              - path: '{options.out}/__init__.py'\n                required: true\n                media_type: text/x-python\n                description: Package re-exports for the generated bindings.\n\n          '1':\n            description: Unexpected error.\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\n          '2':\n            description: Invalid arguments (missing/unreadable input or output).\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\n      # \u2500\u2500 generate cloudformation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n      generate.cloudformation:\n        summary: >-\n          Generate an AWS CloudFormation template (DynamoDB table + GSIs) from\n          TypeScript GraphDDB definitions.\n        description: >-\n          Loads the TypeScript entity models and builds the serializable\n          manifest, then emits an AWS CloudFormation template describing the\n          DynamoDB table(s) the single-table design maps onto: one\n          `AWS::DynamoDB::Table` per physical table, with the base key schema\n          (`PK` / `SK`), the unioned Global Secondary Indexes\n          (`<indexName>PK` / `<indexName>SK`), `PAY_PER_REQUEST` billing, a\n          `TableName` parameter (default = physical name), and Outputs\n          (table name + ARN). Output is deterministic and, by default, YAML.\n        usage:\n          - graphddb generate cloudformation --entry models.ts --out table.yaml\n          - graphddb generate cloudformation --entry models.ts --format json\n          - graphddb generate cloudformation --entry models.ts --gsi-projection KEYS_ONLY --out table.yaml\n          - graphddb generate cloudformation --entry models.ts --stream on --out table.yaml\n          - graphddb generate cloudformation --entry models.ts --pitr --sse --table-class STANDARD_INFREQUENT_ACCESS --out table.yaml\n          - graphddb generate cloudformation --entry models.ts --billing-mode PROVISIONED --rcu 10 --wcu 5 --out table.yaml\n          - graphddb generate cloudformation --entry models.ts --billing-mode PROVISIONED --autoscale --autoscale-min 5 --autoscale-max 100 --autoscale-target 70 --out table.yaml\n\n        effects:\n          risk_level: low\n          reads:\n            - ts-definitions\n          writes:\n            - generated-code\n\n        x-agent:\n          recommended_before_use:\n            - \"Ensure the TypeScript definitions type-check and lint cleanly.\"\n\n        options:\n          - name: entry\n            aliases: [e]\n            required: true\n            description: >-\n              Entry module that registers the entity models (side-effecting\n              import).\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: out\n            aliases: [o]\n            description: >-\n              Output file for the generated CloudFormation template. Written to\n              stdout when omitted.\n            value_name: file\n            schema:\n              type: string\n\n          - name: format\n            aliases: [f]\n            description: Output serialization format (yaml or json).\n            value_name: format\n            schema:\n              type: string\n              enum: [yaml, json]\n              default: yaml\n\n          - name: gsi-projection\n            description: >-\n              GSI ProjectionType. ALL (default) projects every attribute;\n              KEYS_ONLY projects only the key attributes.\n            value_name: projection\n            schema:\n              type: string\n              enum: [ALL, KEYS_ONLY]\n              default: ALL\n\n          - name: stream\n            description: >-\n              DynamoDB Streams (StreamSpecification NEW_AND_OLD_IMAGES) emission.\n              auto (default) emits a stream only when the model set uses\n              stream-based maintenance (updateMode:'stream'); on always emits;\n              off never emits. When enabled, a StreamArn Output is added too.\n            value_name: mode\n            schema:\n              type: string\n              enum: [auto, on, off]\n              default: auto\n\n          - name: billing-mode\n            description: >-\n              DynamoDB billing mode. PAY_PER_REQUEST (default) is on-demand\n              (no provisioned throughput). PROVISIONED emits BillingMode:\n              PROVISIONED with ProvisionedThroughput (see --rcu / --wcu) on the\n              table and every GSI, and unlocks Application Auto Scaling\n              (--autoscale).\n            value_name: mode\n            schema:\n              type: string\n              enum: [PAY_PER_REQUEST, PROVISIONED]\n              default: PAY_PER_REQUEST\n\n          - name: rcu\n            description: >-\n              Provisioned ReadCapacityUnits (a positive integer) applied to the\n              table and every GSI. Only valid with --billing-mode PROVISIONED\n              (rejected with PAY_PER_REQUEST). Defaults to 5 when omitted.\n            value_name: units\n            schema:\n              type: integer\n              minimum: 1\n\n          - name: wcu\n            description: >-\n              Provisioned WriteCapacityUnits (a positive integer) applied to the\n              table and every GSI. Only valid with --billing-mode PROVISIONED\n              (rejected with PAY_PER_REQUEST). Defaults to 5 when omitted.\n            value_name: units\n            schema:\n              type: integer\n              minimum: 1\n\n          - name: autoscale\n            description: >-\n              Enable Application Auto Scaling. Emits an\n              AWS::ApplicationAutoScaling::ScalableTarget +\n              AWS::ApplicationAutoScaling::ScalingPolicy pair for the table read\n              and write capacity AND for each GSI read and write capacity. Only\n              valid with --billing-mode PROVISIONED (autoscaling is invalid on\n              on-demand and is rejected). Off by default \u2014 no autoscaling\n              resources are emitted unless this flag is passed.\n            schema:\n              type: boolean\n\n          - name: autoscale-min\n            description: >-\n              Auto Scaling minimum capacity (MinCapacity) for every scalable\n              target. Must be <= --autoscale-max. Only meaningful with\n              --autoscale. Defaults to 5 when omitted.\n            value_name: units\n            schema:\n              type: integer\n              minimum: 1\n\n          - name: autoscale-max\n            description: >-\n              Auto Scaling maximum capacity (MaxCapacity) for every scalable\n              target. Must be >= --autoscale-min. Only meaningful with\n              --autoscale. Defaults to 100 when omitted.\n            value_name: units\n            schema:\n              type: integer\n              minimum: 1\n\n          - name: autoscale-target\n            description: >-\n              Auto Scaling target utilization percentage (TargetValue of the\n              TargetTrackingScaling policy). Only meaningful with --autoscale.\n              Defaults to 70 when omitted.\n            value_name: percent\n            schema:\n              type: integer\n              minimum: 1\n              maximum: 100\n\n          - name: pitr\n            description: >-\n              Enable point-in-time recovery (PointInTimeRecoverySpecification\n              PointInTimeRecoveryEnabled:true). Off by default \u2014 the property is\n              omitted entirely unless this flag is passed.\n            schema:\n              type: boolean\n\n          - name: table-class\n            description: >-\n              DynamoDB table class. Omitted by default (AWS defaults to\n              STANDARD); pass STANDARD or STANDARD_INFREQUENT_ACCESS to emit\n              TableClass.\n            value_name: class\n            schema:\n              type: string\n              enum: [STANDARD, STANDARD_INFREQUENT_ACCESS]\n\n          - name: sse\n            description: >-\n              Enable server-side encryption with the AWS-owned/managed key\n              (SSESpecification SSEEnabled:true). Off by default \u2014 the property is\n              omitted entirely unless this flag is passed.\n            schema:\n              type: boolean\n\n        exits:\n          '0':\n            description: Generation succeeded.\n            stdout:\n              format: json\n              schema:\n                $ref: '#/components/schemas/GenerateResult'\n\n          '1':\n            description: Unexpected error.\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\n          '2':\n            description: Invalid arguments (missing/unreadable input or output).\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\ncomponents:\n  schemas:\n    GenerateResult:\n      type: object\n      required: [status, outDir, files]\n      properties:\n        status:\n          type: string\n          enum: [ok]\n        outDir:\n          type: string\n          description: Output directory the files were written to.\n        files:\n          type: array\n          description: Paths of the generated files (relative to outDir).\n          items:\n            type: string\n    Error:\n      type: object\n      required: [code, message]\n      properties:\n        code:\n          type: string\n        message:\n          type: string\n";
+var CONTRACT_JSON_STR = '{\n  "cli_contracts": "0.1.0",\n  "info": {\n    "title": "GraphDDB CLI",\n    "version": "0.1.0",\n    "description": "Contract for the graphddb code-generation CLI. The CLI reads TypeScript GraphDDB model / query / command definitions (the single source of truth) and emits Python bindings (manifest.json, operations.json, types.py, repositories.py, __init__.py) for the Python bridge runtime.",\n    "license": {\n      "name": "MIT"\n    },\n    "contact": {\n      "name": "foo-log-inc",\n      "url": "https://github.com/foo-log-inc/graphddb"\n    }\n  },\n  "artifact_slots": {\n    "ts-definitions": {\n      "description": "TypeScript GraphDDB definition modules (entity models, defineQueries, defineCommands) used as the single source of truth.",\n      "direction": "read"\n    },\n    "generated-code": {\n      "description": "Generated Python bindings and JSON specs written to the output directory (manifest.json, operations.json, types.py, repositories.py, __init__.py).",\n      "direction": "write"\n    }\n  },\n  "command_sets": {\n    "graphddb": {\n      "summary": "Graph data modeling on DynamoDB \u2014 code generation CLI.",\n      "x-stdin": "No command reads from stdin. All inputs are provided via file options.",\n      "commands": {\n        "generate.python": {\n          "summary": "Generate Python bindings from TypeScript GraphDDB definitions.",\n          "description": "Loads the TypeScript entity models, query definitions, and command definitions, builds the serializable manifest / operations bundle, and writes the Python bridge bindings (manifest.json, operations.json, types.py, repositories.py, __init__.py) to the output directory. Output is deterministic for a given set of inputs.",\n          "usage": [\n            "graphddb generate python --entry models.ts --queries queries.ts --commands commands.ts --out generated/",\n            "graphddb generate python --entry definitions.ts --out generated/"\n          ],\n          "effects": {\n            "risk_level": "low",\n            "reads": [\n              "ts-definitions"\n            ],\n            "writes": [\n              "generated-code"\n            ]\n          },\n          "x-agent": {\n            "recommended_before_use": [\n              "Ensure the TypeScript definitions type-check and lint cleanly."\n            ]\n          },\n          "options": [\n            {\n              "name": "entry",\n              "aliases": [\n                "e"\n              ],\n              "required": true,\n              "description": "Entry module that registers the entity models (side-effecting import). May also export queries / commands.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "queries",\n              "aliases": [\n                "q"\n              ],\n              "description": "Module exporting `queries` (a defineQueries map). Defaults to the entry module when omitted.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "commands",\n              "aliases": [\n                "c"\n              ],\n              "description": "Module exporting `commands` (a defineCommands map). Defaults to the entry module when omitted.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "transactions",\n              "aliases": [\n                "t"\n              ],\n              "description": "Module exporting `transactions` (a defineTransactions map). Defaults to the commands module (or the entry module) when omitted. Optional \u2014 a project with no declarative transactions omits it.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "contracts",\n              "description": "Module exporting `contracts` (a map of publicQueryModel / publicCommandModel results \u2014 the CQRS Contract layer). Defaults to the entry module when omitted. Optional \u2014 a project with no contracts omits it, and the output gains no `contracts` content.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "contexts",\n              "description": "Module exporting `contexts` (context-ownership: context name \u2192 the Model / Contract names that belong to it). Defaults to the contracts module (or the entry module) when omitted. Optional \u2014 consumed by the boundary lint to tell own from foreign.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "dataclass",\n              "description": "Emit Python result / element types as @dataclass classes instead of TypedDict (decimal / Optional / Connection mapped accordingly).",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "out",\n              "aliases": [\n                "o"\n              ],\n              "required": true,\n              "description": "Output directory for the generated Python bindings.",\n              "value_name": "dir",\n              "schema": {\n                "type": "string"\n              }\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Generation succeeded.",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/GenerateResult"\n                }\n              },\n              "files": [\n                {\n                  "path": "{options.out}/manifest.json",\n                  "required": true,\n                  "media_type": "application/json",\n                  "description": "Entity / table / key / relation metadata."\n                },\n                {\n                  "path": "{options.out}/operations.json",\n                  "required": true,\n                  "media_type": "application/json",\n                  "description": "Per-query / per-command execution specs."\n                },\n                {\n                  "path": "{options.out}/types.py",\n                  "required": true,\n                  "media_type": "text/x-python",\n                  "description": "TypedDict result types derived from query selects."\n                },\n                {\n                  "path": "{options.out}/repositories.py",\n                  "required": true,\n                  "media_type": "text/x-python",\n                  "description": "Per-entity repository classes (sync methods)."\n                },\n                {\n                  "path": "{options.out}/__init__.py",\n                  "required": true,\n                  "media_type": "text/x-python",\n                  "description": "Package re-exports for the generated bindings."\n                }\n              ]\n            },\n            "1": {\n              "description": "Unexpected error.",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            },\n            "2": {\n              "description": "Invalid arguments (missing/unreadable input or output).",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            }\n          }\n        },\n        "generate.cloudformation": {\n          "summary": "Generate an AWS CloudFormation template (DynamoDB table + GSIs) from TypeScript GraphDDB definitions.",\n          "description": "Loads the TypeScript entity models and builds the serializable manifest, then emits an AWS CloudFormation template describing the DynamoDB table(s) the single-table design maps onto: one `AWS::DynamoDB::Table` per physical table, with the base key schema (`PK` / `SK`), the unioned Global Secondary Indexes (`<indexName>PK` / `<indexName>SK`), `PAY_PER_REQUEST` billing, a `TableName` parameter (default = physical name), and Outputs (table name + ARN). Output is deterministic and, by default, YAML.",\n          "usage": [\n            "graphddb generate cloudformation --entry models.ts --out table.yaml",\n            "graphddb generate cloudformation --entry models.ts --format json",\n            "graphddb generate cloudformation --entry models.ts --gsi-projection KEYS_ONLY --out table.yaml",\n            "graphddb generate cloudformation --entry models.ts --stream on --out table.yaml",\n            "graphddb generate cloudformation --entry models.ts --pitr --sse --table-class STANDARD_INFREQUENT_ACCESS --out table.yaml",\n            "graphddb generate cloudformation --entry models.ts --billing-mode PROVISIONED --rcu 10 --wcu 5 --out table.yaml",\n            "graphddb generate cloudformation --entry models.ts --billing-mode PROVISIONED --autoscale --autoscale-min 5 --autoscale-max 100 --autoscale-target 70 --out table.yaml"\n          ],\n          "effects": {\n            "risk_level": "low",\n            "reads": [\n              "ts-definitions"\n            ],\n            "writes": [\n              "generated-code"\n            ]\n          },\n          "x-agent": {\n            "recommended_before_use": [\n              "Ensure the TypeScript definitions type-check and lint cleanly."\n            ]\n          },\n          "options": [\n            {\n              "name": "entry",\n              "aliases": [\n                "e"\n              ],\n              "required": true,\n              "description": "Entry module that registers the entity models (side-effecting import).",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "out",\n              "aliases": [\n                "o"\n              ],\n              "description": "Output file for the generated CloudFormation template. Written to stdout when omitted.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "format",\n              "aliases": [\n                "f"\n              ],\n              "description": "Output serialization format (yaml or json).",\n              "value_name": "format",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "yaml",\n                  "json"\n                ],\n                "default": "yaml"\n              }\n            },\n            {\n              "name": "gsi-projection",\n              "description": "GSI ProjectionType. ALL (default) projects every attribute; KEYS_ONLY projects only the key attributes.",\n              "value_name": "projection",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "ALL",\n                  "KEYS_ONLY"\n                ],\n                "default": "ALL"\n              }\n            },\n            {\n              "name": "stream",\n              "description": "DynamoDB Streams (StreamSpecification NEW_AND_OLD_IMAGES) emission. auto (default) emits a stream only when the model set uses stream-based maintenance (updateMode:\'stream\'); on always emits; off never emits. When enabled, a StreamArn Output is added too.",\n              "value_name": "mode",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "auto",\n                  "on",\n                  "off"\n                ],\n                "default": "auto"\n              }\n            },\n            {\n              "name": "billing-mode",\n              "description": "DynamoDB billing mode. PAY_PER_REQUEST (default) is on-demand (no provisioned throughput). PROVISIONED emits BillingMode: PROVISIONED with ProvisionedThroughput (see --rcu / --wcu) on the table and every GSI, and unlocks Application Auto Scaling (--autoscale).",\n              "value_name": "mode",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "PAY_PER_REQUEST",\n                  "PROVISIONED"\n                ],\n                "default": "PAY_PER_REQUEST"\n              }\n            },\n            {\n              "name": "rcu",\n              "description": "Provisioned ReadCapacityUnits (a positive integer) applied to the table and every GSI. Only valid with --billing-mode PROVISIONED (rejected with PAY_PER_REQUEST). Defaults to 5 when omitted.",\n              "value_name": "units",\n              "schema": {\n                "type": "integer",\n                "minimum": 1\n              }\n            },\n            {\n              "name": "wcu",\n              "description": "Provisioned WriteCapacityUnits (a positive integer) applied to the table and every GSI. Only valid with --billing-mode PROVISIONED (rejected with PAY_PER_REQUEST). Defaults to 5 when omitted.",\n              "value_name": "units",\n              "schema": {\n                "type": "integer",\n                "minimum": 1\n              }\n            },\n            {\n              "name": "autoscale",\n              "description": "Enable Application Auto Scaling. Emits an AWS::ApplicationAutoScaling::ScalableTarget + AWS::ApplicationAutoScaling::ScalingPolicy pair for the table read and write capacity AND for each GSI read and write capacity. Only valid with --billing-mode PROVISIONED (autoscaling is invalid on on-demand and is rejected). Off by default \u2014 no autoscaling resources are emitted unless this flag is passed.",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "autoscale-min",\n              "description": "Auto Scaling minimum capacity (MinCapacity) for every scalable target. Must be <= --autoscale-max. Only meaningful with --autoscale. Defaults to 5 when omitted.",\n              "value_name": "units",\n              "schema": {\n                "type": "integer",\n                "minimum": 1\n              }\n            },\n            {\n              "name": "autoscale-max",\n              "description": "Auto Scaling maximum capacity (MaxCapacity) for every scalable target. Must be >= --autoscale-min. Only meaningful with --autoscale. Defaults to 100 when omitted.",\n              "value_name": "units",\n              "schema": {\n                "type": "integer",\n                "minimum": 1\n              }\n            },\n            {\n              "name": "autoscale-target",\n              "description": "Auto Scaling target utilization percentage (TargetValue of the TargetTrackingScaling policy). Only meaningful with --autoscale. Defaults to 70 when omitted.",\n              "value_name": "percent",\n              "schema": {\n                "type": "integer",\n                "minimum": 1,\n                "maximum": 100\n              }\n            },\n            {\n              "name": "pitr",\n              "description": "Enable point-in-time recovery (PointInTimeRecoverySpecification PointInTimeRecoveryEnabled:true). Off by default \u2014 the property is omitted entirely unless this flag is passed.",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "table-class",\n              "description": "DynamoDB table class. Omitted by default (AWS defaults to STANDARD); pass STANDARD or STANDARD_INFREQUENT_ACCESS to emit TableClass.",\n              "value_name": "class",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "STANDARD",\n                  "STANDARD_INFREQUENT_ACCESS"\n                ]\n              }\n            },\n            {\n              "name": "sse",\n              "description": "Enable server-side encryption with the AWS-owned/managed key (SSESpecification SSEEnabled:true). Off by default \u2014 the property is omitted entirely unless this flag is passed.",\n              "schema": {\n                "type": "boolean"\n              }\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Generation succeeded.",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/GenerateResult"\n                }\n              }\n            },\n            "1": {\n              "description": "Unexpected error.",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            },\n            "2": {\n              "description": "Invalid arguments (missing/unreadable input or output).",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  },\n  "components": {\n    "schemas": {\n      "GenerateResult": {\n        "type": "object",\n        "required": [\n          "status",\n          "outDir",\n          "files"\n        ],\n        "properties": {\n          "status": {\n            "type": "string",\n            "enum": [\n              "ok"\n            ]\n          },\n          "outDir": {\n            "type": "string",\n            "description": "Output directory the files were written to."\n          },\n          "files": {\n            "type": "array",\n            "description": "Paths of the generated files (relative to outDir).",\n            "items": {\n              "type": "string"\n            }\n          }\n        }\n      },\n      "Error": {\n        "type": "object",\n        "required": [\n          "code",\n          "message"\n        ],\n        "properties": {\n          "code": {\n            "type": "string"\n          },\n          "message": {\n            "type": "string"\n          }\n        }\n      }\n    }\n  }\n}';
 
 // src/generated/program.ts
 function createProgram(handlers2, version) {
@@ -343,6 +484,15 @@ function createProgram(handlers2, version) {
     }
     await handlers2.generatePython(opts, globalOpts);
   });
+  __cmd_generate.command("cloudformation").description("Generate an AWS CloudFormation template (DynamoDB table + GSIs) from TypeScript GraphDDB definitions.").option("-e, --entry <file>", "Entry module that registers the entity models (side-effecting import).").option("-o, --out <file>", "Output file for the generated CloudFormation template. Written to stdout when omitted.").option("-f, --format <format>", "Output serialization format (yaml or json).", "yaml").option("--gsi-projection <projection>", "GSI ProjectionType. ALL (default) projects every attribute; KEYS_ONLY projects only the key attributes.", "ALL").option("--stream <mode>", "DynamoDB Streams (StreamSpecification NEW_AND_OLD_IMAGES) emission. auto (default) emits a stream only when the model set uses stream-based maintenance (updateMode:'stream'); on always emits; off never emits. When enabled, a StreamArn Output is added too.", "auto").option("--billing-mode <mode>", "DynamoDB billing mode. PAY_PER_REQUEST (default) is on-demand (no provisioned throughput). PROVISIONED emits BillingMode: PROVISIONED with ProvisionedThroughput (see --rcu / --wcu) on the table and every GSI, and unlocks Application Auto Scaling (--autoscale).", "PAY_PER_REQUEST").option("--rcu <units>", "Provisioned ReadCapacityUnits (a positive integer) applied to the table and every GSI. Only valid with --billing-mode PROVISIONED (rejected with PAY_PER_REQUEST). Defaults to 5 when omitted.").option("--wcu <units>", "Provisioned WriteCapacityUnits (a positive integer) applied to the table and every GSI. Only valid with --billing-mode PROVISIONED (rejected with PAY_PER_REQUEST). Defaults to 5 when omitted.").option("--autoscale", "Enable Application Auto Scaling. Emits an AWS::ApplicationAutoScaling::ScalableTarget + AWS::ApplicationAutoScaling::ScalingPolicy pair for the table read and write capacity AND for each GSI read and write capacity. Only valid with --billing-mode PROVISIONED (autoscaling is invalid on on-demand and is rejected). Off by default \u2014 no autoscaling resources are emitted unless this flag is passed.").option("--autoscale-min <units>", "Auto Scaling minimum capacity (MinCapacity) for every scalable target. Must be <= --autoscale-max. Only meaningful with --autoscale. Defaults to 5 when omitted.").option("--autoscale-max <units>", "Auto Scaling maximum capacity (MaxCapacity) for every scalable target. Must be >= --autoscale-min. Only meaningful with --autoscale. Defaults to 100 when omitted.").option("--autoscale-target <percent>", "Auto Scaling target utilization percentage (TargetValue of the TargetTrackingScaling policy). Only meaningful with --autoscale. Defaults to 70 when omitted.").option("--pitr", "Enable point-in-time recovery (PointInTimeRecoverySpecification PointInTimeRecoveryEnabled:true). Off by default \u2014 the property is omitted entirely unless this flag is passed.").option("--table-class <class>", "DynamoDB table class. Omitted by default (AWS defaults to STANDARD); pass STANDARD or STANDARD_INFREQUENT_ACCESS to emit TableClass.").option("--sse", "Enable server-side encryption with the AWS-owned/managed key (SSESpecification SSEEnabled:true). Off by default \u2014 the property is omitted entirely unless this flag is passed.").action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("generate.cloudformation", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.generateCloudformation(opts, globalOpts);
+  });
   program.command("extract").description("Extract contract specification for this CLI tool.").argument("[commands...]", "Command IDs to extract. Use dot notation.").option("-a, --all", "Extract all commands.", false).option("--include-meta", "Include extraction metadata.", true).option("-F, --format <format>", "Output format (yaml or json).", "yaml").action(async (commands, opts, cmd) => {
     if (commands.length === 0 && !opts.all) {
       process.stderr.write(JSON.stringify({ code: "INVALID_ARGS", message: "Specify command IDs or use --all" }) + "\n");
@@ -360,7 +510,7 @@ function createProgram(handlers2, version) {
             type: "cli-contracts/extract",
             extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
             specVersion: doc.cli_contracts ?? "0.1.0",
-            commands: ["graphddb.generate.python"]
+            commands: ["graphddb.generate.python", "graphddb.generate.cloudformation"]
           };
         }
         Object.assign(out, doc);
@@ -377,7 +527,7 @@ function createProgram(handlers2, version) {
           yamlLines.push("extractedAt: " + (/* @__PURE__ */ new Date()).toISOString());
           yamlLines.push("spec_version: " + (doc.cli_contracts ?? "0.1.0"));
           yamlLines.push("commands:");
-          for (const id of ["graphddb.generate.python"]) {
+          for (const id of ["graphddb.generate.python", "graphddb.generate.cloudformation"]) {
             yamlLines.push("  - " + id);
           }
         }
@@ -418,6 +568,7 @@ function createProgram(handlers2, version) {
 
 // src/cli/handlers.ts
 import { mkdirSync, writeFileSync } from "fs";
+import { dirname, relative } from "path";
 import { pathToFileURL } from "url";
 import { isAbsolute, resolve } from "path";
 
@@ -818,6 +969,487 @@ function generateInit(queries, commands, transactions = {}) {
   return lines.join("\n");
 }
 
+// src/codegen/cloudformation.ts
+var DEFAULT_CAPACITY = 5;
+var DEFAULT_AUTOSCALE_MIN = 5;
+var DEFAULT_AUTOSCALE_MAX = 100;
+var DEFAULT_AUTOSCALE_TARGET = 70;
+var AUTOSCALING_SERVICE_LINKED_ROLE_ARN = {
+  "Fn::Sub": "arn:aws:iam::${AWS::AccountId}:role/aws-service-role/dynamodb.application-autoscaling.amazonaws.com/AWSServiceRoleForApplicationAutoScaling_DynamoDBTable"
+};
+var STREAM_VIEW_TYPE = "NEW_AND_OLD_IMAGES";
+var BASE_PK = "PK";
+var BASE_SK = "SK";
+function gsiPkAttr(indexName) {
+  return `${indexName}PK`;
+}
+function gsiSkAttr(indexName) {
+  return `${indexName}SK`;
+}
+function gsiHasSk(gsi) {
+  return gsi.skTemplate !== null;
+}
+function unionGsis(entities) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const entity of entities) {
+    for (const gsi of entity.gsis) {
+      const hasSk = gsiHasSk(gsi);
+      const existing = byName.get(gsi.indexName);
+      if (existing) {
+        const existingHasSk = existing.skAttr !== null;
+        if (existingHasSk !== hasSk) {
+          throw new Error(
+            `CloudFormation generation: GSI '${gsi.indexName}' on table '${entity.table}' is declared with an inconsistent sort key across entities (some with a sort key, some without). A single DynamoDB table has exactly one GSI per index name; align the sort-key presence for '${gsi.indexName}' across all entities sharing this table.`
+          );
+        }
+        continue;
+      }
+      byName.set(gsi.indexName, {
+        indexName: gsi.indexName,
+        pkAttr: gsiPkAttr(gsi.indexName),
+        skAttr: hasSk ? gsiSkAttr(gsi.indexName) : null
+      });
+    }
+  }
+  return [...byName.values()].sort(
+    (a, b) => a.indexName.localeCompare(b.indexName)
+  );
+}
+function resolveTableTtl(entities, logicalName) {
+  let ttl = null;
+  for (const entity of entities) {
+    if (entity.ttlAttribute === void 0) continue;
+    if (ttl !== null && ttl !== entity.ttlAttribute) {
+      throw new Error(
+        `CloudFormation generation: table '${logicalName}' has more than one TTL attribute ('${ttl}' and '${entity.ttlAttribute}') across the entities sharing it. DynamoDB allows exactly one TTL attribute per table; align the \`@ttl\` attribute across all entities on this table.`
+      );
+    }
+    ttl = entity.ttlAttribute;
+  }
+  return ttl;
+}
+function buildTableSpecs(manifest) {
+  const entitiesByLogical = /* @__PURE__ */ new Map();
+  for (const name of Object.keys(manifest.entities).sort()) {
+    const entity = manifest.entities[name];
+    const list = entitiesByLogical.get(entity.table) ?? [];
+    list.push(entity);
+    entitiesByLogical.set(entity.table, list);
+  }
+  const specs = [];
+  for (const logicalName of [...entitiesByLogical.keys()].sort()) {
+    const entities = entitiesByLogical.get(logicalName);
+    const physicalName = manifest.tables[logicalName]?.physicalName ?? logicalName;
+    const hasSk = entities.some((e) => e.key?.skTemplate != null);
+    const gsis = unionGsis(entities);
+    const ttlAttribute = resolveTableTtl(entities, logicalName);
+    specs.push({ logicalName, physicalName, hasSk, gsis, ttlAttribute });
+  }
+  return specs;
+}
+function tableLogicalId(logicalName) {
+  const cleaned = logicalName.replace(/[^A-Za-z0-9]/g, "");
+  return `${cleaned}Table`;
+}
+function buildAttributeDefinitions(spec) {
+  const names = [BASE_PK];
+  if (spec.hasSk) names.push(BASE_SK);
+  for (const gsi of spec.gsis) {
+    names.push(gsi.pkAttr);
+    if (gsi.skAttr) names.push(gsi.skAttr);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const name of names) {
+    if (seen.has(name)) continue;
+    seen.add(name);
+    out.push({ AttributeName: name, AttributeType: "S" });
+  }
+  return out;
+}
+function buildKeySchema(spec) {
+  const schema = [{ AttributeName: BASE_PK, KeyType: "HASH" }];
+  if (spec.hasSk) schema.push({ AttributeName: BASE_SK, KeyType: "RANGE" });
+  return schema;
+}
+function buildGsiResource(gsi, projectionType, throughput) {
+  const keySchema = [
+    { AttributeName: gsi.pkAttr, KeyType: "HASH" }
+  ];
+  if (gsi.skAttr) {
+    keySchema.push({ AttributeName: gsi.skAttr, KeyType: "RANGE" });
+  }
+  const resource = {
+    IndexName: gsi.indexName,
+    KeySchema: keySchema,
+    Projection: { ProjectionType: projectionType }
+  };
+  if (throughput !== null) {
+    resource.ProvisionedThroughput = {
+      ReadCapacityUnits: throughput.rcu,
+      WriteCapacityUnits: throughput.wcu
+    };
+  }
+  return resource;
+}
+function buildTableResource(spec, options) {
+  const properties = {
+    TableName: { Ref: "TableName" },
+    BillingMode: options.billingMode,
+    AttributeDefinitions: buildAttributeDefinitions(spec),
+    KeySchema: buildKeySchema(spec)
+  };
+  if (options.throughput !== null) {
+    properties.ProvisionedThroughput = {
+      ReadCapacityUnits: options.throughput.rcu,
+      WriteCapacityUnits: options.throughput.wcu
+    };
+  }
+  if (spec.gsis.length > 0) {
+    properties.GlobalSecondaryIndexes = spec.gsis.map(
+      (gsi) => buildGsiResource(gsi, options.gsiProjection, options.throughput)
+    );
+  }
+  if (options.streamsEnabled) {
+    properties.StreamSpecification = { StreamViewType: STREAM_VIEW_TYPE };
+  }
+  if (spec.ttlAttribute !== null) {
+    properties.TimeToLiveSpecification = {
+      AttributeName: spec.ttlAttribute,
+      Enabled: true
+    };
+  }
+  if (options.pitr) {
+    properties.PointInTimeRecoverySpecification = {
+      PointInTimeRecoveryEnabled: true
+    };
+  }
+  if (options.tableClass !== null) {
+    properties.TableClass = options.tableClass;
+  }
+  if (options.sse) {
+    properties.SSESpecification = { SSEEnabled: true };
+  }
+  return {
+    Type: "AWS::DynamoDB::Table",
+    Properties: properties
+  };
+}
+function gsiLogicalFragment(indexName) {
+  return indexName.replace(/[^A-Za-z0-9]/g, "");
+}
+function scalableDimension(kind, isGsi) {
+  const scope = isGsi ? "index" : "table";
+  return `dynamodb:${scope}:${kind}CapacityUnits`;
+}
+function predefinedMetricType(kind) {
+  return `DynamoDB${kind}CapacityUtilization`;
+}
+function autoscaleResourceId(tableLogicalId2, indexName) {
+  const path = indexName === null ? `table/\${${tableLogicalId2}}` : `table/\${${tableLogicalId2}}/index/${indexName}`;
+  return { "Fn::Sub": path };
+}
+function addAutoscalePair(out, tableLogicalId2, indexName, kind, settings) {
+  const isGsi = indexName !== null;
+  const idBase = isGsi ? `${tableLogicalId2}${gsiLogicalFragment(indexName)}${kind}` : `${tableLogicalId2}${kind}`;
+  const targetId = `${idBase}ScalableTarget`;
+  const policyId = `${idBase}ScalingPolicy`;
+  const targetProps = {
+    MaxCapacity: settings.max,
+    MinCapacity: settings.min,
+    ResourceId: autoscaleResourceId(tableLogicalId2, indexName),
+    RoleARN: AUTOSCALING_SERVICE_LINKED_ROLE_ARN,
+    ScalableDimension: scalableDimension(kind, isGsi),
+    ServiceNamespace: "dynamodb"
+  };
+  const target = {
+    Type: "AWS::ApplicationAutoScaling::ScalableTarget",
+    // The table must exist before its (or its GSI's) capacity can be tracked.
+    // The Fn::Sub ResourceId already creates an implicit dependency on the
+    // table's Ref, but we make ordering explicit — critical for a GSI, whose
+    // index must be live before a `dynamodb:index:...` target is created.
+    DependsOn: [tableLogicalId2],
+    Properties: targetProps
+  };
+  const policy = {
+    Type: "AWS::ApplicationAutoScaling::ScalingPolicy",
+    Properties: {
+      PolicyName: policyId,
+      PolicyType: "TargetTrackingScaling",
+      ScalingTargetId: { Ref: targetId },
+      TargetTrackingScalingPolicyConfiguration: {
+        TargetValue: settings.target,
+        PredefinedMetricSpecification: {
+          PredefinedMetricType: predefinedMetricType(kind)
+        }
+      }
+    }
+  };
+  out[targetId] = target;
+  out[policyId] = policy;
+}
+function addAutoscalingResources(out, tableLogicalId2, spec, settings) {
+  for (const kind of ["Read", "Write"]) {
+    addAutoscalePair(out, tableLogicalId2, null, kind, settings);
+  }
+  for (const gsi of spec.gsis) {
+    for (const kind of ["Read", "Write"]) {
+      addAutoscalePair(out, tableLogicalId2, gsi.indexName, kind, settings);
+    }
+  }
+}
+function entityUsesStreamMaintenance(metadata) {
+  for (const rel of metadata.relations) {
+    if (rel.options?.write?.updateMode === "stream") return true;
+    if (rel.options?.versioned?.updateMode === "stream") return true;
+  }
+  for (const agg of metadata.aggregates) {
+    if (agg.options.write?.updateMode === "stream") return true;
+  }
+  for (const from of metadata.maintainedFrom ?? []) {
+    if (from.updateMode === "stream") return true;
+  }
+  return false;
+}
+function detectStreamMaintenance(registry = MetadataRegistry) {
+  for (const [, metadata] of registry.getAll()) {
+    if (entityUsesStreamMaintenance(metadata)) return true;
+  }
+  return false;
+}
+function resolveStreamsEnabled(mode, streamMaintenanceDetected) {
+  if (mode === "on") return true;
+  if (mode === "off") return false;
+  return streamMaintenanceDetected;
+}
+function buildCloudformationTemplate(manifest, options = {}) {
+  const billingMode = options.billingMode ?? "PAY_PER_REQUEST";
+  const provisioned = billingMode === "PROVISIONED";
+  const rcuGiven = options.rcu !== void 0;
+  const wcuGiven = options.wcu !== void 0;
+  if (!provisioned && (rcuGiven || wcuGiven)) {
+    throw new Error(
+      `CloudFormation generation: --rcu/--wcu require --billing-mode PROVISIONED. PAY_PER_REQUEST (on-demand) tables have no provisioned capacity; drop --rcu/--wcu or switch to PROVISIONED.`
+    );
+  }
+  if (!provisioned && options.autoscale) {
+    throw new Error(
+      `CloudFormation generation: --autoscale requires --billing-mode PROVISIONED. Application Auto Scaling is invalid on a PAY_PER_REQUEST (on-demand) table; switch to PROVISIONED or drop --autoscale.`
+    );
+  }
+  const throughput = provisioned ? {
+    rcu: options.rcu ?? DEFAULT_CAPACITY,
+    wcu: options.wcu ?? DEFAULT_CAPACITY
+  } : null;
+  const autoscaleSettings = options.autoscale ? {
+    min: options.autoscaleMin ?? DEFAULT_AUTOSCALE_MIN,
+    max: options.autoscaleMax ?? DEFAULT_AUTOSCALE_MAX,
+    target: options.autoscaleTarget ?? DEFAULT_AUTOSCALE_TARGET
+  } : null;
+  if (autoscaleSettings !== null && autoscaleSettings.min > autoscaleSettings.max) {
+    throw new Error(
+      `CloudFormation generation: --autoscale-min (${autoscaleSettings.min}) must be <= --autoscale-max (${autoscaleSettings.max}).`
+    );
+  }
+  const gsiProjection = options.gsiProjection ?? "ALL";
+  const streamsEnabled = resolveStreamsEnabled(
+    options.stream ?? "auto",
+    options.streamMaintenanceDetected ?? false
+  );
+  const pitr = options.pitr ?? false;
+  const tableClass = options.tableClass ?? null;
+  const sse = options.sse ?? false;
+  const c5Options = { pitr, tableClass, sse };
+  const specs = buildTableSpecs(manifest);
+  const parameters = {};
+  const resources = {};
+  const outputs = {};
+  if (specs.length === 1) {
+    const spec = specs[0];
+    parameters.TableName = {
+      Type: "String",
+      Default: spec.physicalName,
+      Description: `Name of the ${spec.logicalName} DynamoDB table.`
+    };
+    const logicalId = tableLogicalId(spec.logicalName);
+    resources[logicalId] = buildTableResource(spec, {
+      gsiProjection,
+      billingMode,
+      streamsEnabled,
+      throughput,
+      ...c5Options
+    });
+    if (autoscaleSettings !== null) {
+      addAutoscalingResources(resources, logicalId, spec, autoscaleSettings);
+    }
+    outputs.TableName = {
+      Description: `Name of the ${spec.logicalName} DynamoDB table.`,
+      Value: { Ref: logicalId }
+    };
+    outputs.TableArn = {
+      Description: `ARN of the ${spec.logicalName} DynamoDB table.`,
+      Value: { "Fn::GetAtt": [logicalId, "Arn"] }
+    };
+    if (streamsEnabled) {
+      outputs.StreamArn = {
+        Description: `DynamoDB Streams ARN of the ${spec.logicalName} table.`,
+        Value: { "Fn::GetAtt": [logicalId, "StreamArn"] }
+      };
+    }
+  } else {
+    for (const spec of specs) {
+      const logicalId = tableLogicalId(spec.logicalName);
+      const paramName = `${logicalId}Name`;
+      parameters[paramName] = {
+        Type: "String",
+        Default: spec.physicalName,
+        Description: `Name of the ${spec.logicalName} DynamoDB table.`
+      };
+      const resource = buildTableResource(spec, {
+        gsiProjection,
+        billingMode,
+        streamsEnabled,
+        throughput,
+        ...c5Options
+      });
+      resource.Properties.TableName = {
+        Ref: paramName
+      };
+      resources[logicalId] = resource;
+      if (autoscaleSettings !== null) {
+        addAutoscalingResources(resources, logicalId, spec, autoscaleSettings);
+      }
+      outputs[`${logicalId}Name`] = {
+        Description: `Name of the ${spec.logicalName} DynamoDB table.`,
+        Value: { Ref: logicalId }
+      };
+      outputs[`${logicalId}Arn`] = {
+        Description: `ARN of the ${spec.logicalName} DynamoDB table.`,
+        Value: { "Fn::GetAtt": [logicalId, "Arn"] }
+      };
+      if (streamsEnabled) {
+        outputs[`${logicalId}StreamArn`] = {
+          Description: `DynamoDB Streams ARN of the ${spec.logicalName} table.`,
+          Value: { "Fn::GetAtt": [logicalId, "StreamArn"] }
+        };
+      }
+    }
+  }
+  return {
+    AWSTemplateFormatVersion: "2010-09-09",
+    Description: "DynamoDB table(s) for a GraphDDB single-table design (generated by graphddb generate cloudformation).",
+    Parameters: parameters,
+    Resources: resources,
+    Outputs: outputs
+  };
+}
+function isPlainYamlScalar(value) {
+  if (value.length === 0) return false;
+  if (value !== value.trim()) return false;
+  if (/[:#{}\[\],&*!|>'"%@`]/.test(value)) return false;
+  if (/^[?-]/.test(value)) return false;
+  if (/^(true|false|null|~|yes|no|on|off)$/i.test(value)) return false;
+  if (/^[+-]?(\d|\.\d)/.test(value)) return false;
+  return true;
+}
+function yamlScalar(value) {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return String(value);
+  const str = String(value);
+  if (isPlainYamlScalar(str)) return str;
+  return `"${str.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function yamlKey(key) {
+  return isPlainYamlScalar(key) ? key : `"${key.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toYaml(value, indent) {
+  const pad = "  ".repeat(indent);
+  if (Array.isArray(value)) {
+    const lines = [];
+    for (const item of value) {
+      if (isPlainObject(item) || Array.isArray(item)) {
+        const child = toYaml(item, indent + 1);
+        if (child.length === 0) {
+          lines.push(`${pad}-`);
+        } else {
+          lines.push(`${pad}- ${child[0].slice((indent + 1) * 2)}`);
+          for (let i = 1; i < child.length; i++) lines.push(child[i]);
+        }
+      } else {
+        lines.push(`${pad}- ${yamlScalar(item)}`);
+      }
+    }
+    return lines;
+  }
+  if (isPlainObject(value)) {
+    const lines = [];
+    for (const [key, val] of Object.entries(value)) {
+      const k = yamlKey(key);
+      if (isPlainObject(val) || Array.isArray(val)) {
+        const child = toYaml(val, indent + 1);
+        if (child.length === 0) {
+          lines.push(`${pad}${k}: ${Array.isArray(val) ? "[]" : "{}"}`);
+        } else {
+          lines.push(`${pad}${k}:`);
+          for (const line of child) lines.push(line);
+        }
+      } else {
+        lines.push(`${pad}${k}: ${yamlScalar(val)}`);
+      }
+    }
+    return lines;
+  }
+  return [`${pad}${yamlScalar(value)}`];
+}
+function templateToYaml(template) {
+  return toYaml(template, 0).join("\n") + "\n";
+}
+function templateToJson(template) {
+  return JSON.stringify(template, null, 2) + "\n";
+}
+function emitCloudformation(manifest, options = {}) {
+  const template = buildCloudformationTemplate(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",
@@ -930,17 +1562,207 @@ 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) {
       const message = err instanceof Error ? err.message : String(err);
       fail("GENERATION_FAILED", message, 1);
     }
+  },
+  /**
+   * `generate cloudformation` (issue #168, Epic #167 — CFn generator C1).
+   *
+   * Loads the entry model module (side-effecting import registers the entities),
+   * builds the manifest from the shared {@link MetadataRegistry}, and emits an
+   * AWS CloudFormation template (DynamoDB Table + unioned GSIs). Writes to
+   * `--out` when given, else to stdout. Mirrors `generatePython`'s tsx-based
+   * entry loading and JSON error / exit shape.
+   */
+  async generateCloudformation(options) {
+    const {
+      entry,
+      out,
+      format,
+      gsiProjection,
+      stream,
+      billingMode,
+      rcu,
+      wcu,
+      autoscale,
+      autoscaleMin,
+      autoscaleMax,
+      autoscaleTarget,
+      pitr,
+      tableClass,
+      sse
+    } = options;
+    if (!entry) fail("INVALID_ARGS", "Missing required option --entry.", 2);
+    const fmt = format === "json" ? "json" : "yaml";
+    if (format !== void 0 && format !== "yaml" && format !== "json") {
+      fail("INVALID_ARGS", `Invalid --format '${format}'. Use yaml or json.`, 2);
+    }
+    let projection = "ALL";
+    if (gsiProjection !== void 0) {
+      if (gsiProjection !== "ALL" && gsiProjection !== "KEYS_ONLY") {
+        fail(
+          "INVALID_ARGS",
+          `Invalid --gsi-projection '${gsiProjection}'. Use ALL or KEYS_ONLY.`,
+          2
+        );
+      }
+      projection = gsiProjection;
+    }
+    let streamMode = "auto";
+    if (stream !== void 0) {
+      if (stream !== "auto" && stream !== "on" && stream !== "off") {
+        fail(
+          "INVALID_ARGS",
+          `Invalid --stream '${stream}'. Use auto, on, or off.`,
+          2
+        );
+      }
+      streamMode = stream;
+    }
+    let billing = "PAY_PER_REQUEST";
+    if (billingMode !== void 0) {
+      if (billingMode !== "PAY_PER_REQUEST" && billingMode !== "PROVISIONED") {
+        fail(
+          "INVALID_ARGS",
+          `Invalid --billing-mode '${billingMode}'. Use PAY_PER_REQUEST or PROVISIONED.`,
+          2
+        );
+      }
+      billing = billingMode;
+    }
+    const parsePositiveInt = (raw, flag) => {
+      if (raw === void 0) return void 0;
+      if (!/^\d+$/.test(raw)) {
+        fail(
+          "INVALID_ARGS",
+          `Invalid ${flag} '${raw}'. Expected a positive integer.`,
+          2
+        );
+      }
+      const n = Number(raw);
+      if (!Number.isInteger(n) || n < 1) {
+        fail(
+          "INVALID_ARGS",
+          `Invalid ${flag} '${raw}'. Expected a positive integer.`,
+          2
+        );
+      }
+      return n;
+    };
+    const rcuNum = parsePositiveInt(rcu, "--rcu");
+    const wcuNum = parsePositiveInt(wcu, "--wcu");
+    const autoscaleMinNum = parsePositiveInt(autoscaleMin, "--autoscale-min");
+    const autoscaleMaxNum = parsePositiveInt(autoscaleMax, "--autoscale-max");
+    const autoscaleTargetNum = parsePositiveInt(
+      autoscaleTarget,
+      "--autoscale-target"
+    );
+    if (autoscaleTargetNum !== void 0 && autoscaleTargetNum > 100) {
+      fail(
+        "INVALID_ARGS",
+        `Invalid --autoscale-target '${autoscaleTarget}'. Expected 1-100 (a target utilization percentage).`,
+        2
+      );
+    }
+    const provisioned = billing === "PROVISIONED";
+    const autoscaleOn = Boolean(autoscale);
+    if (!provisioned && (rcuNum !== void 0 || wcuNum !== void 0)) {
+      fail(
+        "INVALID_ARGS",
+        `--rcu/--wcu require --billing-mode PROVISIONED. PAY_PER_REQUEST (on-demand) tables have no provisioned capacity.`,
+        2
+      );
+    }
+    if (!provisioned && autoscaleOn) {
+      fail(
+        "INVALID_ARGS",
+        `--autoscale requires --billing-mode PROVISIONED. Application Auto Scaling is invalid on a PAY_PER_REQUEST (on-demand) table.`,
+        2
+      );
+    }
+    const effMin = autoscaleMinNum ?? 5;
+    const effMax = autoscaleMaxNum ?? 100;
+    if (autoscaleOn && effMin > effMax) {
+      fail(
+        "INVALID_ARGS",
+        `--autoscale-min (${effMin}) must be <= --autoscale-max (${effMax}).`,
+        2
+      );
+    }
+    let tblClass;
+    if (tableClass !== void 0) {
+      if (tableClass !== "STANDARD" && tableClass !== "STANDARD_INFREQUENT_ACCESS") {
+        fail(
+          "INVALID_ARGS",
+          `Invalid --table-class '${tableClass}'. Use STANDARD or STANDARD_INFREQUENT_ACCESS.`,
+          2
+        );
+      }
+      tblClass = tableClass;
+    }
+    try {
+      await importModule(entry);
+      const manifest = buildManifest();
+      const streamMaintenanceDetected = streamMode === "auto" ? detectStreamMaintenance() : false;
+      const template = emitCloudformation(manifest, {
+        format: fmt,
+        gsiProjection: projection,
+        billingMode: billing,
+        stream: streamMode,
+        streamMaintenanceDetected,
+        pitr: Boolean(pitr),
+        tableClass: tblClass,
+        sse: Boolean(sse),
+        // C6 (#174): provisioned throughput + autoscaling. Pass the parsed
+        // values through; the emitter applies defaults and enforces the same
+        // loud-reject invariants as a backstop.
+        rcu: rcuNum,
+        wcu: wcuNum,
+        autoscale: autoscaleOn,
+        autoscaleMin: autoscaleMinNum,
+        autoscaleMax: autoscaleMaxNum,
+        autoscaleTarget: autoscaleTargetNum
+      });
+      if (out) {
+        const outFile = isAbsolute(out) ? out : resolve(process.cwd(), out);
+        mkdirSync(dirname(outFile), { recursive: true });
+        writeFileSync(outFile, template, "utf8");
+        process.stdout.write(
+          JSON.stringify({
+            status: "ok",
+            outDir: dirname(out),
+            files: [out]
+          }) + "\n"
+        );
+      } else {
+        process.stdout.write(template);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      fail("GENERATION_FAILED", message, 1);
+    }
   }
 };