graphddb 0.8.1 → 0.9.0

package/dist/cli.js

@@ -1,17 +1,19 @@
 #!/usr/bin/env node
 import {
   buildBridgeBundle,
-  buildOperations
-} from "./chunk-LAT64YCZ.js";
+  buildOperations,
+  portableIrDocument,
+  renderKeyExprToTemplate
+} from "./chunk-SSVG6NQK.js";
 import {
   buildManifest
-} from "./chunk-S2NI4PBW.js";
-import "./chunk-T44OB5GU.js";
-import "./chunk-HNY2EJPV.js";
-import "./chunk-L4QRCHRQ.js";
+} from "./chunk-NWTEUWJD.js";
+import "./chunk-XZTA4VJH.js";
+import "./chunk-KOIJ4SNO.js";
+import "./chunk-WOFRHRXY.js";
 import {
   MetadataRegistry
-} from "./chunk-L2NEDS7U.js";
+} from "./chunk-ZNU7OI5I.js";
 import {
   createDefaultLinter
 } from "./chunk-XTWXMOHD.js";
@@ -540,6 +542,92 @@ var commandDefinitions = {
       }
     ]
   },
+  "generate.behaviors": {
+    "effects": {
+      "risk_level": "low",
+      "reads": [
+        "ts-definitions"
+      ],
+      "writes": [
+        "generated-code"
+      ]
+    },
+    "options": [
+      {
+        "name": "lang",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "ts",
+            "python",
+            "go",
+            "rust",
+            "php"
+          ]
+        }
+      },
+      {
+        "name": "entry",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "media_type": "application/typescript",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "transactions",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "media_type": "application/typescript",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "contracts",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "media_type": "application/typescript",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "contexts",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "media_type": "application/typescript",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "runtime-import",
+        "schema": {
+          "type": "string"
+        }
+      },
+      {
+        "name": "out",
+        "schema": {
+          "type": "string"
+        }
+      }
+    ]
+  },
   "generate.cloudformation": {
     "effects": {
       "risk_level": "low",
@@ -851,8 +939,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 + CQRS contract 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 + the CQRS\n      publishQuery / publishCommand contracts) 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  ts-app-sources:\n    description: >-\n      Application TypeScript sources containing `DDBModel.prepare` call sites.\n      Read by the prepared-statement build lint; rewritten in place by\n      `transform prepared --write` (hoist normalization, issue #206).\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 and CQRS contract\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 --contracts contracts.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 contracts / contexts / transactions.\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 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 publishQuery /\n              publishCommand 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 php \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\u2500\u2500\u2500\n      generate.php:\n        summary: >-\n          Generate typed PHP bindings (repositories + result DTOs) from\n          TypeScript GraphDDB definitions.\n        description: >-\n          Loads the TypeScript entity models and CQRS contract\n          definitions, builds the serializable manifest / operations bundle, and\n          writes typed PHP bindings \u2014 one `<Entity>Repository` per entity plus a\n          result DTO (and `<Item>Connection`) per query result shape \u2014 into the\n          output directory. Each repository wraps the PHP `GraphDDBRuntime`; query\n          methods return a hydrated `?<Result>` typed object, command methods\n          return void, both calling the runtime by the original operation id. The\n          layout is defined by bundled Handlebars templates users can override\n          with --template-dir (per-partial) and extend with --helpers; type\n          resolution always lives in code (the templates customize layout, not\n          types). Output is deterministic for a given set of inputs. The `--typed`\n          flag selects the typed-binding output (the only mode today; reserved for\n          a future raw-binding mode).\n        usage:\n          - graphddb generate php --typed --entry models.ts --contracts contracts.ts --out generated/\n          - graphddb generate php --typed --entry definitions.ts --out generated/\n          - graphddb generate php --typed --entry definitions.ts --out generated/ --template-dir php-templates/ --helpers php-helpers.js\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 contracts / contexts / transactions.\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 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` (the CQRS Contract layer). Defaults to\n              the entry module when omitted. Optional \u2014 contract-internal\n              operations are excluded from the generated binding surface.\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). Defaults to the\n              contracts module (or the entry module) when omitted. Optional.\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: typed\n            description: >-\n              Emit the typed-binding output (repositories + result DTOs). The only\n              output mode today; reserved to distinguish a future raw-binding mode.\n            schema:\n              type: boolean\n\n          - name: template-dir\n            description: >-\n              Directory of override <partial>.hbs templates. Each same-named\n              partial (file / dto-class / connection-class / repo-class /\n              repo-method / tx-class / tx-method) overrides the bundled one;\n              absent partials fall back to the bundled default. Layout only \u2014 type\n              resolution always lives in code.\n            value_name: dir\n            schema:\n              type: string\n\n          - name: helpers\n            description: >-\n              JS module whose default (or named `helpers`) export is a map of\n              extra Handlebars helpers to register alongside the built-in set.\n            value_name: file\n            schema:\n              type: string\n\n          - name: out\n            aliases: [o]\n            required: true\n            description: Output directory for the generated PHP 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\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 rust \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\u2500\u2500\n      generate.rust:\n        summary: >-\n          Generate typed Rust bindings (repositories + serde result structs) from\n          TypeScript GraphDDB definitions.\n        description: >-\n          Loads the TypeScript entity models and CQRS contract\n          definitions, builds the serializable manifest / operations bundle, and\n          writes a single `bindings.rs` module of typed Rust bindings \u2014 a\n          serde-`Deserialize` result struct (and `<Item>Connection`) per query\n          result shape plus one `<Entity>Repository` per entity \u2014 into the output\n          directory. Each repository holds an `Arc<GraphDDBRuntime>`; query methods\n          return `Result<Option<T>, GraphDDBError>` (the deserialized typed\n          result), command methods return `Result<(), GraphDDBError>`, both calling\n          the runtime by the original operation id. The layout is defined by\n          bundled Handlebars templates users can override with --template-dir\n          (per-partial) and extend with --helpers; type resolution always lives in\n          code (the templates customize layout, not types). Output is deterministic\n          for a given set of inputs. The `--typed` flag selects the typed-binding\n          output (the only mode today; reserved for a future raw-binding mode).\n        usage:\n          - graphddb generate rust --typed --entry models.ts --contracts contracts.ts --out generated/\n          - graphddb generate rust --typed --entry definitions.ts --out generated/\n          - graphddb generate rust --typed --entry definitions.ts --out generated/ --template-dir rust-templates/ --helpers rust-helpers.js\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 contracts / contexts / transactions.\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 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` (the CQRS Contract layer). Defaults to\n              the entry module when omitted. Optional \u2014 contract-internal\n              operations are excluded from the generated binding surface.\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). Defaults to the\n              contracts module (or the entry module) when omitted. Optional.\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: typed\n            description: >-\n              Emit the typed-binding output (repositories + result structs). The\n              only output mode today; reserved to distinguish a future raw-binding\n              mode.\n            schema:\n              type: boolean\n\n          - name: template-dir\n            description: >-\n              Directory of override <partial>.hbs templates. Each same-named\n              partial (file / result-struct / connection-struct / repo-struct /\n              repo-method / tx-struct / tx-method) overrides the bundled one;\n              absent partials fall back to the bundled default. Layout only \u2014 type\n              resolution always lives in code.\n            value_name: dir\n            schema:\n              type: string\n\n          - name: helpers\n            description: >-\n              JS module whose default (or named `helpers`) export is a map of\n              extra Handlebars helpers to register alongside the built-in set.\n            value_name: file\n            schema:\n              type: string\n\n          - name: out\n            aliases: [o]\n            required: true\n            description: Output directory for the generated Rust 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\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 go \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\u2500\u2500\u2500\u2500\n      generate.go:\n        summary: >-\n          Generate typed Go bindings (repositories + json result structs) from\n          TypeScript GraphDDB definitions.\n        description: >-\n          Loads the TypeScript entity models and CQRS contract\n          definitions, builds the serializable manifest / operations bundle, and\n          writes a single `bindings.go` package of typed Go bindings \u2014 a json result\n          struct (and `<Item>Connection`) per query result shape plus one\n          `<Entity>Repository` per entity \u2014 into the output directory. Each\n          repository holds a `*graphddb_runtime.GraphDDBRuntime`; query methods\n          return `(*T, error)` (the deserialized typed result; a nil pointer for no\n          match), command methods return `error`, both calling the runtime by the\n          original operation id. Numbers are precision-strict (`json.Number`), so a\n          large integer round-trips losslessly. The layout is defined by bundled\n          Handlebars templates users can override with --template-dir (per-partial)\n          and extend with --helpers; type resolution always lives in code (the\n          templates customize layout, not types). Output is deterministic for a\n          given set of inputs and gofmt-normalized. The `--typed` flag selects the\n          typed-binding output (the only mode today; reserved for a future\n          raw-binding mode).\n        usage:\n          - graphddb generate go --typed --entry models.ts --contracts contracts.ts --out generated/\n          - graphddb generate go --typed --entry definitions.ts --out generated/\n          - graphddb generate go --typed --entry definitions.ts --out generated/ --template-dir go-templates/ --helpers go-helpers.js\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 contracts / contexts / transactions.\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 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` (the CQRS Contract layer). Defaults to\n              the entry module when omitted. Optional \u2014 contract-internal\n              operations are excluded from the generated binding surface.\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). Defaults to the\n              contracts module (or the entry module) when omitted. Optional.\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: typed\n            description: >-\n              Emit the typed-binding output (repositories + result structs). The\n              only output mode today; reserved to distinguish a future raw-binding\n              mode.\n            schema:\n              type: boolean\n\n          - name: template-dir\n            description: >-\n              Directory of override <partial>.hbs templates. Each same-named\n              partial (file / result-struct / connection-struct / repo-struct /\n              repo-method / tx-struct / tx-method) overrides the bundled one;\n              absent partials fall back to the bundled default. Layout only \u2014 type\n              resolution always lives in code.\n            value_name: dir\n            schema:\n              type: string\n\n          - name: helpers\n            description: >-\n              JS module whose default (or named `helpers`) export is a map of\n              extra Handlebars helpers to register alongside the built-in set.\n            value_name: file\n            schema:\n              type: string\n\n          - name: out\n            aliases: [o]\n            required: true\n            description: Output directory for the generated Go 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\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\n      # \u2500\u2500 generate docs \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\u2500\u2500\n      generate.docs:\n        summary: >-\n          Generate model-specification documentation (Markdown + Mermaid) from\n          TypeScript GraphDDB definitions.\n        description: >-\n          Loads the TypeScript entity models (and, optionally, the CQRS contract\n          definitions), builds the serializable manifest / operations bundle, then\n          renders human-facing model documentation \u2014 Table Overview, Entity\n          Relationship Diagram, Physical Key Schema, Property Matrix, Entity\n          Details, Access Patterns, Mutation Contracts, Maintained Access Paths,\n          CDC, and CloudFormation summary \u2014 as Markdown with Mermaid diagrams. The\n          layout is defined by bundled Handlebars templates users can override with\n          --template-dir (per-partial) and extend with --helpers. Output is\n          deterministic for a given set of inputs.\n        usage:\n          - graphddb generate docs --entry models.ts --out doc.md\n          - graphddb generate docs --entry models.ts --contracts contracts.ts --out doc.md\n          - graphddb generate docs --entry models.ts --out docs/\n          - graphddb generate docs --entry models.ts --out docs/ --template-dir doc-templates/ --helpers doc-helpers.js\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 contracts / contexts / transactions.\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 publishQuery /\n              publishCommand results \u2014 the CQRS Contract layer) used for the\n              Access Patterns / Mutation Contracts sections. Defaults to the\n              entry module when omitted. Optional.\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). Defaults to the\n              contracts module (or the entry module) when omitted. Optional.\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            required: true\n            description: >-\n              Output path for the generated documentation. A file path ending in\n              .md writes the single Markdown file at exactly that path (creating\n              parent directories); any other value is treated as a directory and\n              the file is written as <dir>/index.md.\n            value_name: path\n            schema:\n              type: string\n\n          - name: format\n            aliases: [f]\n            description: Output format. Only markdown is supported today.\n            value_name: format\n            schema:\n              type: string\n              enum: [markdown]\n              default: markdown\n\n          - name: split\n            description: >-\n              Output granularity. none (default) emits a single index.md; entity\n              is reserved for a future per-entity split.\n            value_name: mode\n            schema:\n              type: string\n              enum: [none, entity]\n              default: none\n\n          - name: template-dir\n            description: >-\n              Directory of override <partial>.hbs templates. Each same-named\n              partial (index / table-overview / er-diagram / key-schema /\n              property-matrix / entity / access-pattern / maintained / cdc /\n              cloudformation) overrides the bundled one; absent partials fall back\n              to the bundled default.\n            value_name: dir\n            schema:\n              type: string\n\n          - name: helpers\n            description: >-\n              JS module whose default (or named `helpers`) export is a map of extra\n              Handlebars helpers to register alongside the built-in set (eq / join\n              / pascal / mermaidId / codeOrEmpty).\n            value_name: file\n            schema:\n              type: string\n\n          - name: billing-mode\n            description: >-\n              DynamoDB billing mode used in the Table Overview (shared with\n              generate cloudformation). PAY_PER_REQUEST (default) or PROVISIONED.\n            value_name: mode\n            schema:\n              type: string\n              enum: [PAY_PER_REQUEST, PROVISIONED]\n              default: PAY_PER_REQUEST\n\n          - name: stream\n            description: >-\n              DynamoDB Streams state used in the Table Overview (shared with\n              generate cloudformation). auto (default) detects stream-based\n              maintenance (updateMode:'stream'); on always enabled; off never.\n            value_name: mode\n            schema:\n              type: string\n              enum: [auto, on, off]\n              default: auto\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\n      # \u2500\u2500 transform prepared \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      transform.prepared:\n        summary: >-\n          Lint and hoist-normalize `DDBModel.prepare` call sites (compile-time\n          prepared statements, issue #206).\n        description: >-\n          A source-to-source build pass over application TypeScript files. It\n          statically enforces the prepared-statement no-runtime-capture rule\n          (a prepare body may reference only its `$` placeholder and\n          module-static bindings; capturing a per-call runtime value \u2014 directly\n          or via a helper call \u2014 is a loud error), and normalizes every\n          verified INLINE `DDBModel.prepare(fn)` call site into a module-scope\n          prepared slot so the plan compiles once per module and each call is\n          a plain `.execute` (zero per-op planning / hashing \u2014 placement\n          independent). Without --write it is a pure check (the build lint):\n          violations exit non-zero and hoistable inline call sites are\n          reported as notes. With --write, verified inline call sites are\n          rewritten in place; files with violations are never rewritten.\n          Idempotent: re-running on transformed output changes nothing.\n          With --aot <artifact> (issue #208), the pass additionally compiles\n          every verified prepare body at BUILD time into a static prepared-plan\n          artifact (a generated TypeScript module): with --write it writes the\n          artifact and rewrites each call site to load its static plan\n          (`loadPreparedPlan(document, id, body)` \u2014 the body stays in source as\n          the plan's compile source and fallback); without --write it is the\n          DRIFT CHECK \u2014 it recompiles every plan and exits non-zero when the\n          artifact is missing or differs (CI gate: model declarations changed\n          without regenerating the artifact).\n        usage:\n          - graphddb transform prepared --src src/\n          - graphddb transform prepared --src src/ --write\n          - graphddb transform prepared --src src/app/handlers.ts --write\n          - graphddb transform prepared --src src/ --aot src/graphddb.prepared.ts --write\n          - graphddb transform prepared --src src/ --aot src/graphddb.prepared.ts\n\n        effects:\n          risk_level: medium\n          reads:\n            - ts-app-sources\n          writes:\n            - ts-app-sources\n\n        x-agent:\n          recommended_before_use:\n            - \"Commit or stash pending changes first when using --write (it rewrites sources in place).\"\n\n        options:\n          - name: src\n            aliases: [s]\n            required: true\n            description: >-\n              A TypeScript source file, or a directory scanned recursively for\n              .ts/.tsx/.mts/.cts files (node_modules, dist, hidden directories,\n              and .d.ts files are skipped).\n            value_name: path\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n\n          - name: write\n            aliases: [w]\n            description: >-\n              Rewrite verified inline call sites in place (hoist\n              normalization). Without it the command only checks and reports.\n            schema:\n              type: boolean\n\n          - name: aot\n            aliases: [a]\n            description: >-\n              Static prepared-plan artifact module path (issue #208). Enables\n              build-time (AOT) compilation of every verified prepare body:\n              with --write the artifact module is (re)generated and call sites\n              are rewritten to load their static plan; without --write the\n              pass recompiles and compares (drift check \u2014 a missing or\n              differing artifact exits 1).\n            value_name: artifact\n            schema:\n              type: string\n\n        exits:\n          '0':\n            description: >-\n              Check passed / transform applied. No no-runtime-capture\n              violations were found.\n            stdout:\n              format: json\n              schema:\n                $ref: '#/components/schemas/TransformPreparedResult'\n\n          '1':\n            description: >-\n              No-runtime-capture violations found, or --aot drift detected\n              (reported in the result on stdout), or an unexpected error\n              (reported on stderr).\n            stdout:\n              format: json\n              schema:\n                $ref: '#/components/schemas/TransformPreparedResult'\n\n          '2':\n            description: Invalid arguments (missing/unreadable input).\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    TransformPreparedResult:\n      type: object\n      required: [status, files, hoisted, moduleScope, alreadyHoisted, errors, diagnostics]\n      properties:\n        status:\n          type: string\n          enum: [ok, violations, drift]\n        files:\n          type: array\n          description: Source files scanned.\n          items:\n            type: string\n        changedFiles:\n          type: array\n          description: Files rewritten in place (--write only).\n          items:\n            type: string\n        hoisted:\n          type: integer\n          description: Inline call sites normalized (or normalizable in check mode).\n        moduleScope:\n          type: integer\n          description: Call sites already evaluated once per module load (left as-is).\n        alreadyHoisted:\n          type: integer\n          description: Call sites already normalized by a previous run.\n        errors:\n          type: integer\n          description: No-runtime-capture violations found.\n        artifact:\n          type: string\n          description: The static prepared-plan artifact path (--aot only).\n        plans:\n          type: integer\n          description: Prepared plans compiled into the artifact (--aot only).\n        drift:\n          type: object\n          description: >-\n            Artifact drift detail (--aot check mode only; present when status\n            is drift).\n          properties:\n            missing:\n              type: boolean\n              description: The artifact module does not exist.\n            added:\n              type: array\n              items:\n                type: string\n            removed:\n              type: array\n              items:\n                type: string\n            changed:\n              type: array\n              items:\n                type: string\n        diagnostics:\n          type: array\n          description: Per-position lint diagnostics (errors and notes).\n          items:\n            type: object\n            required: [code, category, message, file, line, column]\n            properties:\n              code:\n                type: string\n              category:\n                type: string\n                enum: [error, note]\n              message:\n                type: string\n              file:\n                type: string\n              line:\n                type: integer\n              column:\n                type: integer\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 + CQRS contract 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 + the CQRS publishQuery / publishCommand contracts) 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    "ts-app-sources": {\n      "description": "Application TypeScript sources containing `DDBModel.prepare` call sites. Read by the prepared-statement build lint; rewritten in place by `transform prepared --write` (hoist normalization, issue #206).",\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 and CQRS contract 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 --contracts contracts.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 contracts / contexts / transactions.",\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 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 publishQuery / publishCommand 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.php": {\n          "summary": "Generate typed PHP bindings (repositories + result DTOs) from TypeScript GraphDDB definitions.",\n          "description": "Loads the TypeScript entity models and CQRS contract definitions, builds the serializable manifest / operations bundle, and writes typed PHP bindings \u2014 one `<Entity>Repository` per entity plus a result DTO (and `<Item>Connection`) per query result shape \u2014 into the output directory. Each repository wraps the PHP `GraphDDBRuntime`; query methods return a hydrated `?<Result>` typed object, command methods return void, both calling the runtime by the original operation id. The layout is defined by bundled Handlebars templates users can override with --template-dir (per-partial) and extend with --helpers; type resolution always lives in code (the templates customize layout, not types). Output is deterministic for a given set of inputs. The `--typed` flag selects the typed-binding output (the only mode today; reserved for a future raw-binding mode).",\n          "usage": [\n            "graphddb generate php --typed --entry models.ts --contracts contracts.ts --out generated/",\n            "graphddb generate php --typed --entry definitions.ts --out generated/",\n            "graphddb generate php --typed --entry definitions.ts --out generated/ --template-dir php-templates/ --helpers php-helpers.js"\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 contracts / contexts / transactions.",\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 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` (the CQRS Contract layer). Defaults to the entry module when omitted. Optional \u2014 contract-internal operations are excluded from the generated binding surface.",\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). Defaults to the contracts module (or the entry module) when omitted. Optional.",\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": "typed",\n              "description": "Emit the typed-binding output (repositories + result DTOs). The only output mode today; reserved to distinguish a future raw-binding mode.",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "template-dir",\n              "description": "Directory of override <partial>.hbs templates. Each same-named partial (file / dto-class / connection-class / repo-class / repo-method / tx-class / tx-method) overrides the bundled one; absent partials fall back to the bundled default. Layout only \u2014 type resolution always lives in code.",\n              "value_name": "dir",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "helpers",\n              "description": "JS module whose default (or named `helpers`) export is a map of extra Handlebars helpers to register alongside the built-in set.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "out",\n              "aliases": [\n                "o"\n              ],\n              "required": true,\n              "description": "Output directory for the generated PHP 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            },\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.rust": {\n          "summary": "Generate typed Rust bindings (repositories + serde result structs) from TypeScript GraphDDB definitions.",\n          "description": "Loads the TypeScript entity models and CQRS contract definitions, builds the serializable manifest / operations bundle, and writes a single `bindings.rs` module of typed Rust bindings \u2014 a serde-`Deserialize` result struct (and `<Item>Connection`) per query result shape plus one `<Entity>Repository` per entity \u2014 into the output directory. Each repository holds an `Arc<GraphDDBRuntime>`; query methods return `Result<Option<T>, GraphDDBError>` (the deserialized typed result), command methods return `Result<(), GraphDDBError>`, both calling the runtime by the original operation id. The layout is defined by bundled Handlebars templates users can override with --template-dir (per-partial) and extend with --helpers; type resolution always lives in code (the templates customize layout, not types). Output is deterministic for a given set of inputs. The `--typed` flag selects the typed-binding output (the only mode today; reserved for a future raw-binding mode).",\n          "usage": [\n            "graphddb generate rust --typed --entry models.ts --contracts contracts.ts --out generated/",\n            "graphddb generate rust --typed --entry definitions.ts --out generated/",\n            "graphddb generate rust --typed --entry definitions.ts --out generated/ --template-dir rust-templates/ --helpers rust-helpers.js"\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 contracts / contexts / transactions.",\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 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` (the CQRS Contract layer). Defaults to the entry module when omitted. Optional \u2014 contract-internal operations are excluded from the generated binding surface.",\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). Defaults to the contracts module (or the entry module) when omitted. Optional.",\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": "typed",\n              "description": "Emit the typed-binding output (repositories + result structs). The only output mode today; reserved to distinguish a future raw-binding mode.",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "template-dir",\n              "description": "Directory of override <partial>.hbs templates. Each same-named partial (file / result-struct / connection-struct / repo-struct / repo-method / tx-struct / tx-method) overrides the bundled one; absent partials fall back to the bundled default. Layout only \u2014 type resolution always lives in code.",\n              "value_name": "dir",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "helpers",\n              "description": "JS module whose default (or named `helpers`) export is a map of extra Handlebars helpers to register alongside the built-in set.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "out",\n              "aliases": [\n                "o"\n              ],\n              "required": true,\n              "description": "Output directory for the generated Rust 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            },\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.go": {\n          "summary": "Generate typed Go bindings (repositories + json result structs) from TypeScript GraphDDB definitions.",\n          "description": "Loads the TypeScript entity models and CQRS contract definitions, builds the serializable manifest / operations bundle, and writes a single `bindings.go` package of typed Go bindings \u2014 a json result struct (and `<Item>Connection`) per query result shape plus one `<Entity>Repository` per entity \u2014 into the output directory. Each repository holds a `*graphddb_runtime.GraphDDBRuntime`; query methods return `(*T, error)` (the deserialized typed result; a nil pointer for no match), command methods return `error`, both calling the runtime by the original operation id. Numbers are precision-strict (`json.Number`), so a large integer round-trips losslessly. The layout is defined by bundled Handlebars templates users can override with --template-dir (per-partial) and extend with --helpers; type resolution always lives in code (the templates customize layout, not types). Output is deterministic for a given set of inputs and gofmt-normalized. The `--typed` flag selects the typed-binding output (the only mode today; reserved for a future raw-binding mode).",\n          "usage": [\n            "graphddb generate go --typed --entry models.ts --contracts contracts.ts --out generated/",\n            "graphddb generate go --typed --entry definitions.ts --out generated/",\n            "graphddb generate go --typed --entry definitions.ts --out generated/ --template-dir go-templates/ --helpers go-helpers.js"\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 contracts / contexts / transactions.",\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 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` (the CQRS Contract layer). Defaults to the entry module when omitted. Optional \u2014 contract-internal operations are excluded from the generated binding surface.",\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). Defaults to the contracts module (or the entry module) when omitted. Optional.",\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": "typed",\n              "description": "Emit the typed-binding output (repositories + result structs). The only output mode today; reserved to distinguish a future raw-binding mode.",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "template-dir",\n              "description": "Directory of override <partial>.hbs templates. Each same-named partial (file / result-struct / connection-struct / repo-struct / repo-method / tx-struct / tx-method) overrides the bundled one; absent partials fall back to the bundled default. Layout only \u2014 type resolution always lives in code.",\n              "value_name": "dir",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "helpers",\n              "description": "JS module whose default (or named `helpers`) export is a map of extra Handlebars helpers to register alongside the built-in set.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "out",\n              "aliases": [\n                "o"\n              ],\n              "required": true,\n              "description": "Output directory for the generated Go 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            },\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        "generate.docs": {\n          "summary": "Generate model-specification documentation (Markdown + Mermaid) from TypeScript GraphDDB definitions.",\n          "description": "Loads the TypeScript entity models (and, optionally, the CQRS contract definitions), builds the serializable manifest / operations bundle, then renders human-facing model documentation \u2014 Table Overview, Entity Relationship Diagram, Physical Key Schema, Property Matrix, Entity Details, Access Patterns, Mutation Contracts, Maintained Access Paths, CDC, and CloudFormation summary \u2014 as Markdown with Mermaid diagrams. The layout is defined by bundled Handlebars templates users can override with --template-dir (per-partial) and extend with --helpers. Output is deterministic for a given set of inputs.",\n          "usage": [\n            "graphddb generate docs --entry models.ts --out doc.md",\n            "graphddb generate docs --entry models.ts --contracts contracts.ts --out doc.md",\n            "graphddb generate docs --entry models.ts --out docs/",\n            "graphddb generate docs --entry models.ts --out docs/ --template-dir doc-templates/ --helpers doc-helpers.js"\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 contracts / contexts / transactions.",\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 publishQuery / publishCommand results \u2014 the CQRS Contract layer) used for the Access Patterns / Mutation Contracts sections. Defaults to the entry module when omitted. Optional.",\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). Defaults to the contracts module (or the entry module) when omitted. Optional.",\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              "required": true,\n              "description": "Output path for the generated documentation. A file path ending in .md writes the single Markdown file at exactly that path (creating parent directories); any other value is treated as a directory and the file is written as <dir>/index.md.",\n              "value_name": "path",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "format",\n              "aliases": [\n                "f"\n              ],\n              "description": "Output format. Only markdown is supported today.",\n              "value_name": "format",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "markdown"\n                ],\n                "default": "markdown"\n              }\n            },\n            {\n              "name": "split",\n              "description": "Output granularity. none (default) emits a single index.md; entity is reserved for a future per-entity split.",\n              "value_name": "mode",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "none",\n                  "entity"\n                ],\n                "default": "none"\n              }\n            },\n            {\n              "name": "template-dir",\n              "description": "Directory of override <partial>.hbs templates. Each same-named partial (index / table-overview / er-diagram / key-schema / property-matrix / entity / access-pattern / maintained / cdc / cloudformation) overrides the bundled one; absent partials fall back to the bundled default.",\n              "value_name": "dir",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "helpers",\n              "description": "JS module whose default (or named `helpers`) export is a map of extra Handlebars helpers to register alongside the built-in set (eq / join / pascal / mermaidId / codeOrEmpty).",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "billing-mode",\n              "description": "DynamoDB billing mode used in the Table Overview (shared with generate cloudformation). PAY_PER_REQUEST (default) or PROVISIONED.",\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": "stream",\n              "description": "DynamoDB Streams state used in the Table Overview (shared with generate cloudformation). auto (default) detects stream-based maintenance (updateMode:\'stream\'); on always enabled; off never.",\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          "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        "transform.prepared": {\n          "summary": "Lint and hoist-normalize `DDBModel.prepare` call sites (compile-time prepared statements, issue #206).",\n          "description": "A source-to-source build pass over application TypeScript files. It statically enforces the prepared-statement no-runtime-capture rule (a prepare body may reference only its `$` placeholder and module-static bindings; capturing a per-call runtime value \u2014 directly or via a helper call \u2014 is a loud error), and normalizes every verified INLINE `DDBModel.prepare(fn)` call site into a module-scope prepared slot so the plan compiles once per module and each call is a plain `.execute` (zero per-op planning / hashing \u2014 placement independent). Without --write it is a pure check (the build lint): violations exit non-zero and hoistable inline call sites are reported as notes. With --write, verified inline call sites are rewritten in place; files with violations are never rewritten. Idempotent: re-running on transformed output changes nothing. With --aot <artifact> (issue #208), the pass additionally compiles every verified prepare body at BUILD time into a static prepared-plan artifact (a generated TypeScript module): with --write it writes the artifact and rewrites each call site to load its static plan (`loadPreparedPlan(document, id, body)` \u2014 the body stays in source as the plan\'s compile source and fallback); without --write it is the DRIFT CHECK \u2014 it recompiles every plan and exits non-zero when the artifact is missing or differs (CI gate: model declarations changed without regenerating the artifact).",\n          "usage": [\n            "graphddb transform prepared --src src/",\n            "graphddb transform prepared --src src/ --write",\n            "graphddb transform prepared --src src/app/handlers.ts --write",\n            "graphddb transform prepared --src src/ --aot src/graphddb.prepared.ts --write",\n            "graphddb transform prepared --src src/ --aot src/graphddb.prepared.ts"\n          ],\n          "effects": {\n            "risk_level": "medium",\n            "reads": [\n              "ts-app-sources"\n            ],\n            "writes": [\n              "ts-app-sources"\n            ]\n          },\n          "x-agent": {\n            "recommended_before_use": [\n              "Commit or stash pending changes first when using --write (it rewrites sources in place)."\n            ]\n          },\n          "options": [\n            {\n              "name": "src",\n              "aliases": [\n                "s"\n              ],\n              "required": true,\n              "description": "A TypeScript source file, or a directory scanned recursively for .ts/.tsx/.mts/.cts files (node_modules, dist, hidden directories, and .d.ts files are skipped).",\n              "value_name": "path",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true\n              }\n            },\n            {\n              "name": "write",\n              "aliases": [\n                "w"\n              ],\n              "description": "Rewrite verified inline call sites in place (hoist normalization). Without it the command only checks and reports.",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "aot",\n              "aliases": [\n                "a"\n              ],\n              "description": "Static prepared-plan artifact module path (issue #208). Enables build-time (AOT) compilation of every verified prepare body: with --write the artifact module is (re)generated and call sites are rewritten to load their static plan; without --write the pass recompiles and compares (drift check \u2014 a missing or differing artifact exits 1).",\n              "value_name": "artifact",\n              "schema": {\n                "type": "string"\n              }\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Check passed / transform applied. No no-runtime-capture violations were found.",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/TransformPreparedResult"\n                }\n              }\n            },\n            "1": {\n              "description": "No-runtime-capture violations found, or --aot drift detected (reported in the result on stdout), or an unexpected error (reported on stderr).",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/TransformPreparedResult"\n                }\n              }\n            },\n            "2": {\n              "description": "Invalid arguments (missing/unreadable input).",\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      "TransformPreparedResult": {\n        "type": "object",\n        "required": [\n          "status",\n          "files",\n          "hoisted",\n          "moduleScope",\n          "alreadyHoisted",\n          "errors",\n          "diagnostics"\n        ],\n        "properties": {\n          "status": {\n            "type": "string",\n            "enum": [\n              "ok",\n              "violations",\n              "drift"\n            ]\n          },\n          "files": {\n            "type": "array",\n            "description": "Source files scanned.",\n            "items": {\n              "type": "string"\n            }\n          },\n          "changedFiles": {\n            "type": "array",\n            "description": "Files rewritten in place (--write only).",\n            "items": {\n              "type": "string"\n            }\n          },\n          "hoisted": {\n            "type": "integer",\n            "description": "Inline call sites normalized (or normalizable in check mode)."\n          },\n          "moduleScope": {\n            "type": "integer",\n            "description": "Call sites already evaluated once per module load (left as-is)."\n          },\n          "alreadyHoisted": {\n            "type": "integer",\n            "description": "Call sites already normalized by a previous run."\n          },\n          "errors": {\n            "type": "integer",\n            "description": "No-runtime-capture violations found."\n          },\n          "artifact": {\n            "type": "string",\n            "description": "The static prepared-plan artifact path (--aot only)."\n          },\n          "plans": {\n            "type": "integer",\n            "description": "Prepared plans compiled into the artifact (--aot only)."\n          },\n          "drift": {\n            "type": "object",\n            "description": "Artifact drift detail (--aot check mode only; present when status is drift).",\n            "properties": {\n              "missing": {\n                "type": "boolean",\n                "description": "The artifact module does not exist."\n              },\n              "added": {\n                "type": "array",\n                "items": {\n                  "type": "string"\n                }\n              },\n              "removed": {\n                "type": "array",\n                "items": {\n                  "type": "string"\n                }\n              },\n              "changed": {\n                "type": "array",\n                "items": {\n                  "type": "string"\n                }\n              }\n            }\n          },\n          "diagnostics": {\n            "type": "array",\n            "description": "Per-position lint diagnostics (errors and notes).",\n            "items": {\n              "type": "object",\n              "required": [\n                "code",\n                "category",\n                "message",\n                "file",\n                "line",\n                "column"\n              ],\n              "properties": {\n                "code": {\n                  "type": "string"\n                },\n                "category": {\n                  "type": "string",\n                  "enum": [\n                    "error",\n                    "note"\n                  ]\n                },\n                "message": {\n                  "type": "string"\n                },\n                "file": {\n                  "type": "string"\n                },\n                "line": {\n                  "type": "integer"\n                },\n                "column": {\n                  "type": "integer"\n                }\n              }\n            }\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 + CQRS contract 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 + the CQRS\n      publishQuery / publishCommand contracts) 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  ts-app-sources:\n    description: >-\n      Application TypeScript sources containing `DDBModel.prepare` call sites.\n      Read by the prepared-statement build lint; rewritten in place by\n      `transform prepared --write` (hoist normalization, issue #206).\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 and CQRS contract\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 --contracts contracts.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 contracts / contexts / transactions.\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 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 publishQuery /\n              publishCommand 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 php \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\u2500\u2500\u2500\n      generate.php:\n        summary: >-\n          Generate typed PHP bindings (repositories + result DTOs) from\n          TypeScript GraphDDB definitions.\n        description: >-\n          Loads the TypeScript entity models and CQRS contract\n          definitions, builds the serializable manifest / operations bundle, and\n          writes typed PHP bindings \u2014 one `<Entity>Repository` per entity plus a\n          result DTO (and `<Item>Connection`) per query result shape \u2014 into the\n          output directory. Each repository wraps the PHP `GraphDDBRuntime`; query\n          methods return a hydrated `?<Result>` typed object, command methods\n          return void, both calling the runtime by the original operation id. The\n          layout is defined by bundled Handlebars templates users can override\n          with --template-dir (per-partial) and extend with --helpers; type\n          resolution always lives in code (the templates customize layout, not\n          types). Output is deterministic for a given set of inputs. The `--typed`\n          flag selects the typed-binding output (the only mode today; reserved for\n          a future raw-binding mode).\n        usage:\n          - graphddb generate php --typed --entry models.ts --contracts contracts.ts --out generated/\n          - graphddb generate php --typed --entry definitions.ts --out generated/\n          - graphddb generate php --typed --entry definitions.ts --out generated/ --template-dir php-templates/ --helpers php-helpers.js\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 contracts / contexts / transactions.\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 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` (the CQRS Contract layer). Defaults to\n              the entry module when omitted. Optional \u2014 contract-internal\n              operations are excluded from the generated binding surface.\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). Defaults to the\n              contracts module (or the entry module) when omitted. Optional.\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: typed\n            description: >-\n              Emit the typed-binding output (repositories + result DTOs). The only\n              output mode today; reserved to distinguish a future raw-binding mode.\n            schema:\n              type: boolean\n\n          - name: template-dir\n            description: >-\n              Directory of override <partial>.hbs templates. Each same-named\n              partial (file / dto-class / connection-class / repo-class /\n              repo-method / tx-class / tx-method) overrides the bundled one;\n              absent partials fall back to the bundled default. Layout only \u2014 type\n              resolution always lives in code.\n            value_name: dir\n            schema:\n              type: string\n\n          - name: helpers\n            description: >-\n              JS module whose default (or named `helpers`) export is a map of\n              extra Handlebars helpers to register alongside the built-in set.\n            value_name: file\n            schema:\n              type: string\n\n          - name: out\n            aliases: [o]\n            required: true\n            description: Output directory for the generated PHP 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\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 rust \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\u2500\u2500\n      generate.rust:\n        summary: >-\n          Generate typed Rust bindings (repositories + serde result structs) from\n          TypeScript GraphDDB definitions.\n        description: >-\n          Loads the TypeScript entity models and CQRS contract\n          definitions, builds the serializable manifest / operations bundle, and\n          writes a single `bindings.rs` module of typed Rust bindings \u2014 a\n          serde-`Deserialize` result struct (and `<Item>Connection`) per query\n          result shape plus one `<Entity>Repository` per entity \u2014 into the output\n          directory. Each repository holds an `Arc<GraphDDBRuntime>`; query methods\n          return `Result<Option<T>, GraphDDBError>` (the deserialized typed\n          result), command methods return `Result<(), GraphDDBError>`, both calling\n          the runtime by the original operation id. The layout is defined by\n          bundled Handlebars templates users can override with --template-dir\n          (per-partial) and extend with --helpers; type resolution always lives in\n          code (the templates customize layout, not types). Output is deterministic\n          for a given set of inputs. The `--typed` flag selects the typed-binding\n          output (the only mode today; reserved for a future raw-binding mode).\n        usage:\n          - graphddb generate rust --typed --entry models.ts --contracts contracts.ts --out generated/\n          - graphddb generate rust --typed --entry definitions.ts --out generated/\n          - graphddb generate rust --typed --entry definitions.ts --out generated/ --template-dir rust-templates/ --helpers rust-helpers.js\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 contracts / contexts / transactions.\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 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` (the CQRS Contract layer). Defaults to\n              the entry module when omitted. Optional \u2014 contract-internal\n              operations are excluded from the generated binding surface.\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). Defaults to the\n              contracts module (or the entry module) when omitted. Optional.\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: typed\n            description: >-\n              Emit the typed-binding output (repositories + result structs). The\n              only output mode today; reserved to distinguish a future raw-binding\n              mode.\n            schema:\n              type: boolean\n\n          - name: template-dir\n            description: >-\n              Directory of override <partial>.hbs templates. Each same-named\n              partial (file / result-struct / connection-struct / repo-struct /\n              repo-method / tx-struct / tx-method) overrides the bundled one;\n              absent partials fall back to the bundled default. Layout only \u2014 type\n              resolution always lives in code.\n            value_name: dir\n            schema:\n              type: string\n\n          - name: helpers\n            description: >-\n              JS module whose default (or named `helpers`) export is a map of\n              extra Handlebars helpers to register alongside the built-in set.\n            value_name: file\n            schema:\n              type: string\n\n          - name: out\n            aliases: [o]\n            required: true\n            description: Output directory for the generated Rust 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\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 go \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\u2500\u2500\u2500\u2500\n      generate.go:\n        summary: >-\n          Generate typed Go bindings (repositories + json result structs) from\n          TypeScript GraphDDB definitions.\n        description: >-\n          Loads the TypeScript entity models and CQRS contract\n          definitions, builds the serializable manifest / operations bundle, and\n          writes a single `bindings.go` package of typed Go bindings \u2014 a json result\n          struct (and `<Item>Connection`) per query result shape plus one\n          `<Entity>Repository` per entity \u2014 into the output directory. Each\n          repository holds a `*graphddb_runtime.GraphDDBRuntime`; query methods\n          return `(*T, error)` (the deserialized typed result; a nil pointer for no\n          match), command methods return `error`, both calling the runtime by the\n          original operation id. Numbers are precision-strict (`json.Number`), so a\n          large integer round-trips losslessly. The layout is defined by bundled\n          Handlebars templates users can override with --template-dir (per-partial)\n          and extend with --helpers; type resolution always lives in code (the\n          templates customize layout, not types). Output is deterministic for a\n          given set of inputs and gofmt-normalized. The `--typed` flag selects the\n          typed-binding output (the only mode today; reserved for a future\n          raw-binding mode).\n        usage:\n          - graphddb generate go --typed --entry models.ts --contracts contracts.ts --out generated/\n          - graphddb generate go --typed --entry definitions.ts --out generated/\n          - graphddb generate go --typed --entry definitions.ts --out generated/ --template-dir go-templates/ --helpers go-helpers.js\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 contracts / contexts / transactions.\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 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` (the CQRS Contract layer). Defaults to\n              the entry module when omitted. Optional \u2014 contract-internal\n              operations are excluded from the generated binding surface.\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). Defaults to the\n              contracts module (or the entry module) when omitted. Optional.\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: typed\n            description: >-\n              Emit the typed-binding output (repositories + result structs). The\n              only output mode today; reserved to distinguish a future raw-binding\n              mode.\n            schema:\n              type: boolean\n\n          - name: template-dir\n            description: >-\n              Directory of override <partial>.hbs templates. Each same-named\n              partial (file / result-struct / connection-struct / repo-struct /\n              repo-method / tx-struct / tx-method) overrides the bundled one;\n              absent partials fall back to the bundled default. Layout only \u2014 type\n              resolution always lives in code.\n            value_name: dir\n            schema:\n              type: string\n\n          - name: helpers\n            description: >-\n              JS module whose default (or named `helpers`) export is a map of\n              extra Handlebars helpers to register alongside the built-in set.\n            value_name: file\n            schema:\n              type: string\n\n          - name: out\n            aliases: [o]\n            required: true\n            description: Output directory for the generated Go 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\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 behaviors \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.behaviors:\n        summary: >-\n          Generate a native behavior module (the codegen-static endpoint) via the\n          upstream behavior-contracts common Generator.\n        description: >-\n          Loads the TypeScript entity models and CQRS contract definitions,\n          builds the serializable operations bundle, wraps its universal\n          components[] into the portable component-graph IR envelope\n          ({irVersion, exprVersion, components} \u2014 scp-ir-architecture.md \xA75),\n          and hands it to behavior-contracts' common Generator\n          (`generateModule`, foo-ogawa/behavior-contracts#13) to emit ONE native\n          module for the selected language (issue #257). graphddb adds no\n          generation logic: envelope + invoke + file write only. The generated\n          module embeds the IR as a native literal with the spec versions and\n          the IR fingerprint baked in (fail-closed load-time checks, the #208\n          prepared-artifact discipline) and exposes a `bind(handlers)` accessor\n          that delegates to the runtime core \u2014 handlers are always injected at\n          the boundary by the consuming runtime (the graphddb per-language\n          behavior-exec seams). This is the OPT-IN static endpoint (\xA77.3\n          endpoint 3); the JSON-dynamic operations.json path remains the\n          default and is permanently supported. Output is deterministic for a\n          given set of inputs.\n        usage:\n          - graphddb generate behaviors --lang ts --entry models.ts --contracts contracts.ts --out generated/\n          - graphddb generate behaviors --lang go --entry models.ts --contracts contracts.ts --out generated/\n          - graphddb generate behaviors --lang python --entry definitions.ts --out generated/\n          - graphddb generate behaviors --lang rust --entry definitions.ts --out generated/ --runtime-import behavior_contracts\n          - graphddb generate behaviors --lang php --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: lang\n            aliases: [l]\n            required: true\n            description: >-\n              Target language of the generated behavior module. `ts` emits a\n              typed TypeScript module, `python` a dict-literal module, `go` a\n              JNode composite-literal package, `rust` a json!-constructor\n              module (requires Rust >= 1.80 \u2014 std::sync::LazyLock), `php` a\n              require-scoped module value.\n            value_name: lang\n            schema:\n              type: string\n              enum: [ts, python, go, rust, php]\n\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 contracts / contexts / transactions.\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 entry module when omitted. Optional.\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` (the CQRS Contract layer). Defaults\n              to the entry module when omitted. Optional.\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). Defaults to the\n              contracts module (or the entry module) when omitted. Optional.\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: runtime-import\n            description: >-\n              Module specifier the generated module imports the\n              behavior-contracts runtime core from. Defaults to the emitter's\n              published package name per language \u2014 except `php`, which\n              defaults to graphddb's vendored namespace\n              (GraphDDB\\Runtime\\BehaviorContracts) so the generated module\n              resolves against the PHP runtime this package ships.\n            value_name: specifier\n            schema:\n              type: string\n\n          - name: out\n            aliases: [o]\n            required: true\n            description: Output directory for the generated behavior module.\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\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\n      # \u2500\u2500 generate docs \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\u2500\u2500\n      generate.docs:\n        summary: >-\n          Generate model-specification documentation (Markdown + Mermaid) from\n          TypeScript GraphDDB definitions.\n        description: >-\n          Loads the TypeScript entity models (and, optionally, the CQRS contract\n          definitions), builds the serializable manifest / operations bundle, then\n          renders human-facing model documentation \u2014 Table Overview, Entity\n          Relationship Diagram, Physical Key Schema, Property Matrix, Entity\n          Details, Access Patterns, Mutation Contracts, Maintained Access Paths,\n          CDC, and CloudFormation summary \u2014 as Markdown with Mermaid diagrams. The\n          layout is defined by bundled Handlebars templates users can override with\n          --template-dir (per-partial) and extend with --helpers. Output is\n          deterministic for a given set of inputs.\n        usage:\n          - graphddb generate docs --entry models.ts --out doc.md\n          - graphddb generate docs --entry models.ts --contracts contracts.ts --out doc.md\n          - graphddb generate docs --entry models.ts --out docs/\n          - graphddb generate docs --entry models.ts --out docs/ --template-dir doc-templates/ --helpers doc-helpers.js\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 contracts / contexts / transactions.\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 publishQuery /\n              publishCommand results \u2014 the CQRS Contract layer) used for the\n              Access Patterns / Mutation Contracts sections. Defaults to the\n              entry module when omitted. Optional.\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). Defaults to the\n              contracts module (or the entry module) when omitted. Optional.\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            required: true\n            description: >-\n              Output path for the generated documentation. A file path ending in\n              .md writes the single Markdown file at exactly that path (creating\n              parent directories); any other value is treated as a directory and\n              the file is written as <dir>/index.md.\n            value_name: path\n            schema:\n              type: string\n\n          - name: format\n            aliases: [f]\n            description: Output format. Only markdown is supported today.\n            value_name: format\n            schema:\n              type: string\n              enum: [markdown]\n              default: markdown\n\n          - name: split\n            description: >-\n              Output granularity. none (default) emits a single index.md; entity\n              is reserved for a future per-entity split.\n            value_name: mode\n            schema:\n              type: string\n              enum: [none, entity]\n              default: none\n\n          - name: template-dir\n            description: >-\n              Directory of override <partial>.hbs templates. Each same-named\n              partial (index / table-overview / er-diagram / key-schema /\n              property-matrix / entity / access-pattern / maintained / cdc /\n              cloudformation) overrides the bundled one; absent partials fall back\n              to the bundled default.\n            value_name: dir\n            schema:\n              type: string\n\n          - name: helpers\n            description: >-\n              JS module whose default (or named `helpers`) export is a map of extra\n              Handlebars helpers to register alongside the built-in set (eq / join\n              / pascal / mermaidId / codeOrEmpty).\n            value_name: file\n            schema:\n              type: string\n\n          - name: billing-mode\n            description: >-\n              DynamoDB billing mode used in the Table Overview (shared with\n              generate cloudformation). PAY_PER_REQUEST (default) or PROVISIONED.\n            value_name: mode\n            schema:\n              type: string\n              enum: [PAY_PER_REQUEST, PROVISIONED]\n              default: PAY_PER_REQUEST\n\n          - name: stream\n            description: >-\n              DynamoDB Streams state used in the Table Overview (shared with\n              generate cloudformation). auto (default) detects stream-based\n              maintenance (updateMode:'stream'); on always enabled; off never.\n            value_name: mode\n            schema:\n              type: string\n              enum: [auto, on, off]\n              default: auto\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\n      # \u2500\u2500 transform prepared \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      transform.prepared:\n        summary: >-\n          Lint and hoist-normalize `DDBModel.prepare` call sites (compile-time\n          prepared statements, issue #206).\n        description: >-\n          A source-to-source build pass over application TypeScript files. It\n          statically enforces the prepared-statement no-runtime-capture rule\n          (a prepare body may reference only its `$` placeholder and\n          module-static bindings; capturing a per-call runtime value \u2014 directly\n          or via a helper call \u2014 is a loud error), and normalizes every\n          verified INLINE `DDBModel.prepare(fn)` call site into a module-scope\n          prepared slot so the plan compiles once per module and each call is\n          a plain `.execute` (zero per-op planning / hashing \u2014 placement\n          independent). Without --write it is a pure check (the build lint):\n          violations exit non-zero and hoistable inline call sites are\n          reported as notes. With --write, verified inline call sites are\n          rewritten in place; files with violations are never rewritten.\n          Idempotent: re-running on transformed output changes nothing.\n          With --aot <artifact> (issue #208), the pass additionally compiles\n          every verified prepare body at BUILD time into a static prepared-plan\n          artifact (a generated TypeScript module): with --write it writes the\n          artifact and rewrites each call site to load its static plan\n          (`loadPreparedPlan(document, id, body)` \u2014 the body stays in source as\n          the plan's compile source and fallback); without --write it is the\n          DRIFT CHECK \u2014 it recompiles every plan and exits non-zero when the\n          artifact is missing or differs (CI gate: model declarations changed\n          without regenerating the artifact).\n        usage:\n          - graphddb transform prepared --src src/\n          - graphddb transform prepared --src src/ --write\n          - graphddb transform prepared --src src/app/handlers.ts --write\n          - graphddb transform prepared --src src/ --aot src/graphddb.prepared.ts --write\n          - graphddb transform prepared --src src/ --aot src/graphddb.prepared.ts\n\n        effects:\n          risk_level: medium\n          reads:\n            - ts-app-sources\n          writes:\n            - ts-app-sources\n\n        x-agent:\n          recommended_before_use:\n            - \"Commit or stash pending changes first when using --write (it rewrites sources in place).\"\n\n        options:\n          - name: src\n            aliases: [s]\n            required: true\n            description: >-\n              A TypeScript source file, or a directory scanned recursively for\n              .ts/.tsx/.mts/.cts files (node_modules, dist, hidden directories,\n              and .d.ts files are skipped).\n            value_name: path\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n\n          - name: write\n            aliases: [w]\n            description: >-\n              Rewrite verified inline call sites in place (hoist\n              normalization). Without it the command only checks and reports.\n            schema:\n              type: boolean\n\n          - name: aot\n            aliases: [a]\n            description: >-\n              Static prepared-plan artifact module path (issue #208). Enables\n              build-time (AOT) compilation of every verified prepare body:\n              with --write the artifact module is (re)generated and call sites\n              are rewritten to load their static plan; without --write the\n              pass recompiles and compares (drift check \u2014 a missing or\n              differing artifact exits 1).\n            value_name: artifact\n            schema:\n              type: string\n\n        exits:\n          '0':\n            description: >-\n              Check passed / transform applied. No no-runtime-capture\n              violations were found.\n            stdout:\n              format: json\n              schema:\n                $ref: '#/components/schemas/TransformPreparedResult'\n\n          '1':\n            description: >-\n              No-runtime-capture violations found, or --aot drift detected\n              (reported in the result on stdout), or an unexpected error\n              (reported on stderr).\n            stdout:\n              format: json\n              schema:\n                $ref: '#/components/schemas/TransformPreparedResult'\n\n          '2':\n            description: Invalid arguments (missing/unreadable input).\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    TransformPreparedResult:\n      type: object\n      required: [status, files, hoisted, moduleScope, alreadyHoisted, errors, diagnostics]\n      properties:\n        status:\n          type: string\n          enum: [ok, violations, drift]\n        files:\n          type: array\n          description: Source files scanned.\n          items:\n            type: string\n        changedFiles:\n          type: array\n          description: Files rewritten in place (--write only).\n          items:\n            type: string\n        hoisted:\n          type: integer\n          description: Inline call sites normalized (or normalizable in check mode).\n        moduleScope:\n          type: integer\n          description: Call sites already evaluated once per module load (left as-is).\n        alreadyHoisted:\n          type: integer\n          description: Call sites already normalized by a previous run.\n        errors:\n          type: integer\n          description: No-runtime-capture violations found.\n        artifact:\n          type: string\n          description: The static prepared-plan artifact path (--aot only).\n        plans:\n          type: integer\n          description: Prepared plans compiled into the artifact (--aot only).\n        drift:\n          type: object\n          description: >-\n            Artifact drift detail (--aot check mode only; present when status\n            is drift).\n          properties:\n            missing:\n              type: boolean\n              description: The artifact module does not exist.\n            added:\n              type: array\n              items:\n                type: string\n            removed:\n              type: array\n              items:\n                type: string\n            changed:\n              type: array\n              items:\n                type: string\n        diagnostics:\n          type: array\n          description: Per-position lint diagnostics (errors and notes).\n          items:\n            type: object\n            required: [code, category, message, file, line, column]\n            properties:\n              code:\n                type: string\n              category:\n                type: string\n                enum: [error, note]\n              message:\n                type: string\n              file:\n                type: string\n              line:\n                type: integer\n              column:\n                type: integer\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 + CQRS contract 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 + the CQRS publishQuery / publishCommand contracts) 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    "ts-app-sources": {\n      "description": "Application TypeScript sources containing `DDBModel.prepare` call sites. Read by the prepared-statement build lint; rewritten in place by `transform prepared --write` (hoist normalization, issue #206).",\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 and CQRS contract 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 --contracts contracts.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 contracts / contexts / transactions.",\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 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 publishQuery / publishCommand 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.php": {\n          "summary": "Generate typed PHP bindings (repositories + result DTOs) from TypeScript GraphDDB definitions.",\n          "description": "Loads the TypeScript entity models and CQRS contract definitions, builds the serializable manifest / operations bundle, and writes typed PHP bindings \u2014 one `<Entity>Repository` per entity plus a result DTO (and `<Item>Connection`) per query result shape \u2014 into the output directory. Each repository wraps the PHP `GraphDDBRuntime`; query methods return a hydrated `?<Result>` typed object, command methods return void, both calling the runtime by the original operation id. The layout is defined by bundled Handlebars templates users can override with --template-dir (per-partial) and extend with --helpers; type resolution always lives in code (the templates customize layout, not types). Output is deterministic for a given set of inputs. The `--typed` flag selects the typed-binding output (the only mode today; reserved for a future raw-binding mode).",\n          "usage": [\n            "graphddb generate php --typed --entry models.ts --contracts contracts.ts --out generated/",\n            "graphddb generate php --typed --entry definitions.ts --out generated/",\n            "graphddb generate php --typed --entry definitions.ts --out generated/ --template-dir php-templates/ --helpers php-helpers.js"\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 contracts / contexts / transactions.",\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 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` (the CQRS Contract layer). Defaults to the entry module when omitted. Optional \u2014 contract-internal operations are excluded from the generated binding surface.",\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). Defaults to the contracts module (or the entry module) when omitted. Optional.",\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": "typed",\n              "description": "Emit the typed-binding output (repositories + result DTOs). The only output mode today; reserved to distinguish a future raw-binding mode.",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "template-dir",\n              "description": "Directory of override <partial>.hbs templates. Each same-named partial (file / dto-class / connection-class / repo-class / repo-method / tx-class / tx-method) overrides the bundled one; absent partials fall back to the bundled default. Layout only \u2014 type resolution always lives in code.",\n              "value_name": "dir",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "helpers",\n              "description": "JS module whose default (or named `helpers`) export is a map of extra Handlebars helpers to register alongside the built-in set.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "out",\n              "aliases": [\n                "o"\n              ],\n              "required": true,\n              "description": "Output directory for the generated PHP 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            },\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.rust": {\n          "summary": "Generate typed Rust bindings (repositories + serde result structs) from TypeScript GraphDDB definitions.",\n          "description": "Loads the TypeScript entity models and CQRS contract definitions, builds the serializable manifest / operations bundle, and writes a single `bindings.rs` module of typed Rust bindings \u2014 a serde-`Deserialize` result struct (and `<Item>Connection`) per query result shape plus one `<Entity>Repository` per entity \u2014 into the output directory. Each repository holds an `Arc<GraphDDBRuntime>`; query methods return `Result<Option<T>, GraphDDBError>` (the deserialized typed result), command methods return `Result<(), GraphDDBError>`, both calling the runtime by the original operation id. The layout is defined by bundled Handlebars templates users can override with --template-dir (per-partial) and extend with --helpers; type resolution always lives in code (the templates customize layout, not types). Output is deterministic for a given set of inputs. The `--typed` flag selects the typed-binding output (the only mode today; reserved for a future raw-binding mode).",\n          "usage": [\n            "graphddb generate rust --typed --entry models.ts --contracts contracts.ts --out generated/",\n            "graphddb generate rust --typed --entry definitions.ts --out generated/",\n            "graphddb generate rust --typed --entry definitions.ts --out generated/ --template-dir rust-templates/ --helpers rust-helpers.js"\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 contracts / contexts / transactions.",\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 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` (the CQRS Contract layer). Defaults to the entry module when omitted. Optional \u2014 contract-internal operations are excluded from the generated binding surface.",\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). Defaults to the contracts module (or the entry module) when omitted. Optional.",\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": "typed",\n              "description": "Emit the typed-binding output (repositories + result structs). The only output mode today; reserved to distinguish a future raw-binding mode.",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "template-dir",\n              "description": "Directory of override <partial>.hbs templates. Each same-named partial (file / result-struct / connection-struct / repo-struct / repo-method / tx-struct / tx-method) overrides the bundled one; absent partials fall back to the bundled default. Layout only \u2014 type resolution always lives in code.",\n              "value_name": "dir",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "helpers",\n              "description": "JS module whose default (or named `helpers`) export is a map of extra Handlebars helpers to register alongside the built-in set.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "out",\n              "aliases": [\n                "o"\n              ],\n              "required": true,\n              "description": "Output directory for the generated Rust 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            },\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.go": {\n          "summary": "Generate typed Go bindings (repositories + json result structs) from TypeScript GraphDDB definitions.",\n          "description": "Loads the TypeScript entity models and CQRS contract definitions, builds the serializable manifest / operations bundle, and writes a single `bindings.go` package of typed Go bindings \u2014 a json result struct (and `<Item>Connection`) per query result shape plus one `<Entity>Repository` per entity \u2014 into the output directory. Each repository holds a `*graphddb_runtime.GraphDDBRuntime`; query methods return `(*T, error)` (the deserialized typed result; a nil pointer for no match), command methods return `error`, both calling the runtime by the original operation id. Numbers are precision-strict (`json.Number`), so a large integer round-trips losslessly. The layout is defined by bundled Handlebars templates users can override with --template-dir (per-partial) and extend with --helpers; type resolution always lives in code (the templates customize layout, not types). Output is deterministic for a given set of inputs and gofmt-normalized. The `--typed` flag selects the typed-binding output (the only mode today; reserved for a future raw-binding mode).",\n          "usage": [\n            "graphddb generate go --typed --entry models.ts --contracts contracts.ts --out generated/",\n            "graphddb generate go --typed --entry definitions.ts --out generated/",\n            "graphddb generate go --typed --entry definitions.ts --out generated/ --template-dir go-templates/ --helpers go-helpers.js"\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 contracts / contexts / transactions.",\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 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` (the CQRS Contract layer). Defaults to the entry module when omitted. Optional \u2014 contract-internal operations are excluded from the generated binding surface.",\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). Defaults to the contracts module (or the entry module) when omitted. Optional.",\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": "typed",\n              "description": "Emit the typed-binding output (repositories + result structs). The only output mode today; reserved to distinguish a future raw-binding mode.",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "template-dir",\n              "description": "Directory of override <partial>.hbs templates. Each same-named partial (file / result-struct / connection-struct / repo-struct / repo-method / tx-struct / tx-method) overrides the bundled one; absent partials fall back to the bundled default. Layout only \u2014 type resolution always lives in code.",\n              "value_name": "dir",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "helpers",\n              "description": "JS module whose default (or named `helpers`) export is a map of extra Handlebars helpers to register alongside the built-in set.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "out",\n              "aliases": [\n                "o"\n              ],\n              "required": true,\n              "description": "Output directory for the generated Go 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            },\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.behaviors": {\n          "summary": "Generate a native behavior module (the codegen-static endpoint) via the upstream behavior-contracts common Generator.",\n          "description": "Loads the TypeScript entity models and CQRS contract definitions, builds the serializable operations bundle, wraps its universal components[] into the portable component-graph IR envelope ({irVersion, exprVersion, components} \u2014 scp-ir-architecture.md \xA75), and hands it to behavior-contracts\' common Generator (`generateModule`, foo-ogawa/behavior-contracts#13) to emit ONE native module for the selected language (issue #257). graphddb adds no generation logic: envelope + invoke + file write only. The generated module embeds the IR as a native literal with the spec versions and the IR fingerprint baked in (fail-closed load-time checks, the #208 prepared-artifact discipline) and exposes a `bind(handlers)` accessor that delegates to the runtime core \u2014 handlers are always injected at the boundary by the consuming runtime (the graphddb per-language behavior-exec seams). This is the OPT-IN static endpoint (\xA77.3 endpoint 3); the JSON-dynamic operations.json path remains the default and is permanently supported. Output is deterministic for a given set of inputs.",\n          "usage": [\n            "graphddb generate behaviors --lang ts --entry models.ts --contracts contracts.ts --out generated/",\n            "graphddb generate behaviors --lang go --entry models.ts --contracts contracts.ts --out generated/",\n            "graphddb generate behaviors --lang python --entry definitions.ts --out generated/",\n            "graphddb generate behaviors --lang rust --entry definitions.ts --out generated/ --runtime-import behavior_contracts",\n            "graphddb generate behaviors --lang php --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": "lang",\n              "aliases": [\n                "l"\n              ],\n              "required": true,\n              "description": "Target language of the generated behavior module. `ts` emits a typed TypeScript module, `python` a dict-literal module, `go` a JNode composite-literal package, `rust` a json!-constructor module (requires Rust >= 1.80 \u2014 std::sync::LazyLock), `php` a require-scoped module value.",\n              "value_name": "lang",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "ts",\n                  "python",\n                  "go",\n                  "rust",\n                  "php"\n                ]\n              }\n            },\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 contracts / contexts / transactions.",\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 entry module when omitted. Optional.",\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` (the CQRS Contract layer). Defaults to the entry module when omitted. Optional.",\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). Defaults to the contracts module (or the entry module) when omitted. Optional.",\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": "runtime-import",\n              "description": "Module specifier the generated module imports the behavior-contracts runtime core from. Defaults to the emitter\'s published package name per language \u2014 except `php`, which defaults to graphddb\'s vendored namespace (GraphDDB\\\\Runtime\\\\BehaviorContracts) so the generated module resolves against the PHP runtime this package ships.",\n              "value_name": "specifier",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "out",\n              "aliases": [\n                "o"\n              ],\n              "required": true,\n              "description": "Output directory for the generated behavior module.",\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            },\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        "generate.docs": {\n          "summary": "Generate model-specification documentation (Markdown + Mermaid) from TypeScript GraphDDB definitions.",\n          "description": "Loads the TypeScript entity models (and, optionally, the CQRS contract definitions), builds the serializable manifest / operations bundle, then renders human-facing model documentation \u2014 Table Overview, Entity Relationship Diagram, Physical Key Schema, Property Matrix, Entity Details, Access Patterns, Mutation Contracts, Maintained Access Paths, CDC, and CloudFormation summary \u2014 as Markdown with Mermaid diagrams. The layout is defined by bundled Handlebars templates users can override with --template-dir (per-partial) and extend with --helpers. Output is deterministic for a given set of inputs.",\n          "usage": [\n            "graphddb generate docs --entry models.ts --out doc.md",\n            "graphddb generate docs --entry models.ts --contracts contracts.ts --out doc.md",\n            "graphddb generate docs --entry models.ts --out docs/",\n            "graphddb generate docs --entry models.ts --out docs/ --template-dir doc-templates/ --helpers doc-helpers.js"\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 contracts / contexts / transactions.",\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 publishQuery / publishCommand results \u2014 the CQRS Contract layer) used for the Access Patterns / Mutation Contracts sections. Defaults to the entry module when omitted. Optional.",\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). Defaults to the contracts module (or the entry module) when omitted. Optional.",\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              "required": true,\n              "description": "Output path for the generated documentation. A file path ending in .md writes the single Markdown file at exactly that path (creating parent directories); any other value is treated as a directory and the file is written as <dir>/index.md.",\n              "value_name": "path",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "format",\n              "aliases": [\n                "f"\n              ],\n              "description": "Output format. Only markdown is supported today.",\n              "value_name": "format",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "markdown"\n                ],\n                "default": "markdown"\n              }\n            },\n            {\n              "name": "split",\n              "description": "Output granularity. none (default) emits a single index.md; entity is reserved for a future per-entity split.",\n              "value_name": "mode",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "none",\n                  "entity"\n                ],\n                "default": "none"\n              }\n            },\n            {\n              "name": "template-dir",\n              "description": "Directory of override <partial>.hbs templates. Each same-named partial (index / table-overview / er-diagram / key-schema / property-matrix / entity / access-pattern / maintained / cdc / cloudformation) overrides the bundled one; absent partials fall back to the bundled default.",\n              "value_name": "dir",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "helpers",\n              "description": "JS module whose default (or named `helpers`) export is a map of extra Handlebars helpers to register alongside the built-in set (eq / join / pascal / mermaidId / codeOrEmpty).",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "billing-mode",\n              "description": "DynamoDB billing mode used in the Table Overview (shared with generate cloudformation). PAY_PER_REQUEST (default) or PROVISIONED.",\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": "stream",\n              "description": "DynamoDB Streams state used in the Table Overview (shared with generate cloudformation). auto (default) detects stream-based maintenance (updateMode:\'stream\'); on always enabled; off never.",\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          "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        "transform.prepared": {\n          "summary": "Lint and hoist-normalize `DDBModel.prepare` call sites (compile-time prepared statements, issue #206).",\n          "description": "A source-to-source build pass over application TypeScript files. It statically enforces the prepared-statement no-runtime-capture rule (a prepare body may reference only its `$` placeholder and module-static bindings; capturing a per-call runtime value \u2014 directly or via a helper call \u2014 is a loud error), and normalizes every verified INLINE `DDBModel.prepare(fn)` call site into a module-scope prepared slot so the plan compiles once per module and each call is a plain `.execute` (zero per-op planning / hashing \u2014 placement independent). Without --write it is a pure check (the build lint): violations exit non-zero and hoistable inline call sites are reported as notes. With --write, verified inline call sites are rewritten in place; files with violations are never rewritten. Idempotent: re-running on transformed output changes nothing. With --aot <artifact> (issue #208), the pass additionally compiles every verified prepare body at BUILD time into a static prepared-plan artifact (a generated TypeScript module): with --write it writes the artifact and rewrites each call site to load its static plan (`loadPreparedPlan(document, id, body)` \u2014 the body stays in source as the plan\'s compile source and fallback); without --write it is the DRIFT CHECK \u2014 it recompiles every plan and exits non-zero when the artifact is missing or differs (CI gate: model declarations changed without regenerating the artifact).",\n          "usage": [\n            "graphddb transform prepared --src src/",\n            "graphddb transform prepared --src src/ --write",\n            "graphddb transform prepared --src src/app/handlers.ts --write",\n            "graphddb transform prepared --src src/ --aot src/graphddb.prepared.ts --write",\n            "graphddb transform prepared --src src/ --aot src/graphddb.prepared.ts"\n          ],\n          "effects": {\n            "risk_level": "medium",\n            "reads": [\n              "ts-app-sources"\n            ],\n            "writes": [\n              "ts-app-sources"\n            ]\n          },\n          "x-agent": {\n            "recommended_before_use": [\n              "Commit or stash pending changes first when using --write (it rewrites sources in place)."\n            ]\n          },\n          "options": [\n            {\n              "name": "src",\n              "aliases": [\n                "s"\n              ],\n              "required": true,\n              "description": "A TypeScript source file, or a directory scanned recursively for .ts/.tsx/.mts/.cts files (node_modules, dist, hidden directories, and .d.ts files are skipped).",\n              "value_name": "path",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true\n              }\n            },\n            {\n              "name": "write",\n              "aliases": [\n                "w"\n              ],\n              "description": "Rewrite verified inline call sites in place (hoist normalization). Without it the command only checks and reports.",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "aot",\n              "aliases": [\n                "a"\n              ],\n              "description": "Static prepared-plan artifact module path (issue #208). Enables build-time (AOT) compilation of every verified prepare body: with --write the artifact module is (re)generated and call sites are rewritten to load their static plan; without --write the pass recompiles and compares (drift check \u2014 a missing or differing artifact exits 1).",\n              "value_name": "artifact",\n              "schema": {\n                "type": "string"\n              }\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Check passed / transform applied. No no-runtime-capture violations were found.",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/TransformPreparedResult"\n                }\n              }\n            },\n            "1": {\n              "description": "No-runtime-capture violations found, or --aot drift detected (reported in the result on stdout), or an unexpected error (reported on stderr).",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/TransformPreparedResult"\n                }\n              }\n            },\n            "2": {\n              "description": "Invalid arguments (missing/unreadable input).",\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      "TransformPreparedResult": {\n        "type": "object",\n        "required": [\n          "status",\n          "files",\n          "hoisted",\n          "moduleScope",\n          "alreadyHoisted",\n          "errors",\n          "diagnostics"\n        ],\n        "properties": {\n          "status": {\n            "type": "string",\n            "enum": [\n              "ok",\n              "violations",\n              "drift"\n            ]\n          },\n          "files": {\n            "type": "array",\n            "description": "Source files scanned.",\n            "items": {\n              "type": "string"\n            }\n          },\n          "changedFiles": {\n            "type": "array",\n            "description": "Files rewritten in place (--write only).",\n            "items": {\n              "type": "string"\n            }\n          },\n          "hoisted": {\n            "type": "integer",\n            "description": "Inline call sites normalized (or normalizable in check mode)."\n          },\n          "moduleScope": {\n            "type": "integer",\n            "description": "Call sites already evaluated once per module load (left as-is)."\n          },\n          "alreadyHoisted": {\n            "type": "integer",\n            "description": "Call sites already normalized by a previous run."\n          },\n          "errors": {\n            "type": "integer",\n            "description": "No-runtime-capture violations found."\n          },\n          "artifact": {\n            "type": "string",\n            "description": "The static prepared-plan artifact path (--aot only)."\n          },\n          "plans": {\n            "type": "integer",\n            "description": "Prepared plans compiled into the artifact (--aot only)."\n          },\n          "drift": {\n            "type": "object",\n            "description": "Artifact drift detail (--aot check mode only; present when status is drift).",\n            "properties": {\n              "missing": {\n                "type": "boolean",\n                "description": "The artifact module does not exist."\n              },\n              "added": {\n                "type": "array",\n                "items": {\n                  "type": "string"\n                }\n              },\n              "removed": {\n                "type": "array",\n                "items": {\n                  "type": "string"\n                }\n              },\n              "changed": {\n                "type": "array",\n                "items": {\n                  "type": "string"\n                }\n              }\n            }\n          },\n          "diagnostics": {\n            "type": "array",\n            "description": "Per-position lint diagnostics (errors and notes).",\n            "items": {\n              "type": "object",\n              "required": [\n                "code",\n                "category",\n                "message",\n                "file",\n                "line",\n                "column"\n              ],\n              "properties": {\n                "code": {\n                  "type": "string"\n                },\n                "category": {\n                  "type": "string",\n                  "enum": [\n                    "error",\n                    "note"\n                  ]\n                },\n                "message": {\n                  "type": "string"\n                },\n                "file": {\n                  "type": "string"\n                },\n                "line": {\n                  "type": "integer"\n                },\n                "column": {\n                  "type": "integer"\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}';
 
 // src/generated/program.ts
 function createProgram(handlers2, version) {
@@ -896,6 +984,15 @@ function createProgram(handlers2, version) {
     }
     await handlers2.generateGo(opts, globalOpts);
   });
+  __cmd_generate.command("behaviors").description("Generate a native behavior module (the codegen-static endpoint) via the upstream behavior-contracts common Generator.").option("-l, --lang <lang>", "Target language of the generated behavior module. `ts` emits a typed TypeScript module, `python` a dict-literal module, `go` a JNode composite-literal package, `rust` a json!-constructor module (requires Rust >= 1.80 \u2014 std::sync::LazyLock), `php` a require-scoped module value.").option("-e, --entry <file>", "Entry module that registers the entity models (side-effecting import). May also export contracts / contexts / transactions.").option("-t, --transactions <file>", "Module exporting `transactions` (a defineTransactions map). Defaults to the entry module when omitted. Optional.").option("--contracts <file>", "Module exporting `contracts` (the CQRS Contract layer). Defaults to the entry module when omitted. Optional.").option("--contexts <file>", "Module exporting `contexts` (context-ownership). Defaults to the contracts module (or the entry module) when omitted. Optional.").option("--runtime-import <specifier>", "Module specifier the generated module imports the behavior-contracts runtime core from. Defaults to the emitter's published package name per language \u2014 except `php`, which defaults to graphddb's vendored namespace (GraphDDB\\Runtime\\BehaviorContracts) so the generated module resolves against the PHP runtime this package ships.").option("-o, --out <dir>", "Output directory for the generated behavior module.").action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("generate.behaviors", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.generateBehaviors(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) {
@@ -941,7 +1038,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", "graphddb.generate.php", "graphddb.generate.rust", "graphddb.generate.go", "graphddb.generate.cloudformation", "graphddb.generate.docs", "graphddb.transform.prepared"]
+            commands: ["graphddb.generate.python", "graphddb.generate.php", "graphddb.generate.rust", "graphddb.generate.go", "graphddb.generate.behaviors", "graphddb.generate.cloudformation", "graphddb.generate.docs", "graphddb.transform.prepared"]
           };
         }
         Object.assign(out, doc);
@@ -958,7 +1055,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", "graphddb.generate.php", "graphddb.generate.rust", "graphddb.generate.go", "graphddb.generate.cloudformation", "graphddb.generate.docs", "graphddb.transform.prepared"]) {
+          for (const id of ["graphddb.generate.python", "graphddb.generate.php", "graphddb.generate.rust", "graphddb.generate.go", "graphddb.generate.behaviors", "graphddb.generate.cloudformation", "graphddb.generate.docs", "graphddb.transform.prepared"]) {
             yamlLines.push("  - " + id);
           }
         }
@@ -1014,27 +1111,37 @@ function entityBaseName(entity) {
 function queryResultTypeName(queryName) {
   return `${toPascalCase(queryName)}Result`;
 }
-function txElementTypeName(txName, paramName) {
+function txElementTypeName(txName, paramName, batchWrite = false) {
+  if (batchWrite && paramName === "items") return `${toPascalCase(txName)}Item`;
   return `${toPascalCase(txName)}${toPascalCase(paramName)}Item`;
 }
 function contractOperationId(contract, method) {
   return `${contract}__${method}`;
 }
-function relationSegments(resultPath) {
-  if (resultPath === "$") return [];
-  const parts = resultPath.replace(/^\$\.?/, "").split(".");
-  return parts.filter((p) => p !== "items");
+function relationSegments(nodeId) {
+  return nodeId.split(".").filter((p) => p !== "items");
 }
-function insertOperation(root, op, manifest) {
-  const segments = relationSegments(op.resultPath);
-  let node = root;
+function nodePorts(node) {
+  if ("map" in node) return node.map.ports;
+  if ("cond" in node) return void 0;
+  return node.ports;
+}
+function nodeProjection(ports) {
+  const port = ports.projection;
+  return (port?.arr ?? []).filter((f) => typeof f === "string");
+}
+function insertComponentNode(root, node, manifest) {
+  const ports = nodePorts(node);
+  if (ports === void 0) return;
+  const segments = relationSegments(node.id);
+  let tree = root;
   let parent = root;
   let entity = root.entity;
   for (const prop of segments) {
-    parent = node;
+    parent = tree;
     const relation = manifest.entities[entity]?.relations[prop];
     const target = relation?.target ?? entity;
-    let child = node.children.get(prop);
+    let child = tree.children.get(prop);
     if (!child) {
       child = {
         entity: target,
@@ -1042,14 +1149,21 @@ function insertOperation(root, op, manifest) {
         children: /* @__PURE__ */ new Map(),
         implicitFields: /* @__PURE__ */ new Set()
       };
-      node.children.set(prop, child);
+      tree.children.set(prop, child);
     }
-    node = child;
+    tree = child;
     entity = target;
   }
-  node.projection = op.projection;
-  if (op.sourceList?.implicit) {
-    parent.implicitFields.add(op.sourceList.from);
+  tree.projection = nodeProjection(ports);
+  const implicit = ports.implicitSourceField;
+  if (typeof implicit === "string") parent.implicitFields.add(implicit);
+}
+function populateResultTree(root, spec, component, manifest) {
+  root.projection = spec.operations[0]?.projection ?? [];
+  if (component === void 0) return;
+  for (const node of component.body) {
+    if (node.id === "root") continue;
+    insertComponentNode(root, node, manifest);
   }
 }
 function emitResultClasses(node, typeName, manifest, out, seen) {
@@ -1139,7 +1253,7 @@ function emitTransactionElementTypes(transactions, out, seen) {
     for (const paramName of Object.keys(spec.params).sort()) {
       const p = spec.params[paramName];
       if (p.type !== "array" || !p.element) continue;
-      const name = txElementTypeName(txName, paramName);
+      const name = txElementTypeName(txName, paramName, spec.batchWrite === true);
       if (seen.has(name)) continue;
       seen.add(name);
       const element = p.element;
@@ -1152,7 +1266,7 @@ function emitTransactionElementTypes(transactions, out, seen) {
   }
 }
 function elementParamField(name, p) {
-  const scalarType = p.type === "number" ? "number" : "string";
+  const scalarType = p.type === "number" ? "number" : p.type === "map" ? "map" : "string";
   return {
     name,
     shape: "scalar",
@@ -1211,9 +1325,9 @@ function contractCommandMethodSpec(operations, binding) {
 }
 function contractCommandParams(operations, binding, spec) {
   const single = spec.single;
-  const params = single.mode === "transaction" ? operations.transactions?.[single.transaction]?.params : operations.commands[single.operation]?.params;
+  const params = single.mode === "transaction" || single.mode === "batchWrite" ? operations.transactions?.[single.transaction]?.params : operations.commands[single.operation]?.params;
   if (!params) {
-    const ref = single.mode === "transaction" ? `transaction '${single.transaction}'` : `command '${single.operation}'`;
+    const ref = single.mode === "transaction" || single.mode === "batchWrite" ? `transaction '${single.transaction}'` : `command '${single.operation}'`;
     throw new Error(
       `Contract '${binding.contract}.${binding.method}': its single resolution target (${ref}) is not present in the operations document.`
     );
@@ -1237,6 +1351,9 @@ function buildBindingModel(manifest, operations, options) {
       ...meta.description !== void 0 ? { description: meta.description } : {}
     };
   });
+  const componentByName = new Map(
+    (operations.components ?? []).map((c) => [c.name, c])
+  );
   const resultClasses = [];
   const seen = /* @__PURE__ */ new Set();
   for (const queryName of queryNames) {
@@ -1249,7 +1366,7 @@ function buildBindingModel(manifest, operations, options) {
       children: /* @__PURE__ */ new Map(),
       implicitFields: /* @__PURE__ */ new Set()
     };
-    for (const op of spec.operations) insertOperation(root, op, manifest);
+    populateResultTree(root, spec, componentByName.get(queryName), manifest);
     emitResultClasses(root, queryResultTypeName(queryName), manifest, resultClasses, seen);
   }
   for (const q of contractQueries) {
@@ -1272,7 +1389,7 @@ function buildBindingModel(manifest, operations, options) {
       children: /* @__PURE__ */ new Map(),
       implicitFields: /* @__PURE__ */ new Set()
     };
-    for (const op of spec.operations) insertOperation(root, op, manifest);
+    populateResultTree(root, spec, componentByName.get(q.operation), manifest);
     emitResultClasses(root, recordName, manifest, resultClasses, seen);
     appendFieldsToClass(resultClasses, recordName, composeFields(methodSpec.compose ?? []));
     if (cardinality === "many") {
@@ -1364,8 +1481,10 @@ function buildBindingModel(manifest, operations, options) {
     transactionId: txName,
     params: buildParams(
       transactions[txName].params,
-      (p) => txElementTypeName(txName, p)
-    )
+      (p) => txElementTypeName(txName, p, transactions[txName].batchWrite === true)
+    ),
+    // #298: a `batchWrite` bulk form dispatches to `executeBatchWrite`.
+    ...transactions[txName].batchWrite === true ? { batchWrite: true } : {}
   }));
   return {
     entities,
@@ -1466,7 +1585,7 @@ function resolveField(field, mapper) {
     case "scalar":
     default:
       type = field.isParamScalar ? mapper.paramScalar(
-        field.scalarType === "number" ? "number" : field.literals ? "literal" : "string",
+        field.scalarType === "number" ? "number" : field.scalarType === "map" ? "map" : field.literals ? "literal" : "string",
         field.literals
       ) : mapper.scalar(field.scalarType ?? "string", field.scalarFormat);
       break;
@@ -1565,7 +1684,8 @@ function resolveBindingView(model, mapper, options = {}) {
     })),
     transactions: model.transactions.map((tx) => ({
       transactionId: tx.transactionId,
-      params: tx.params.map((p) => resolveParam(p, mapper))
+      params: tx.params.map((p) => resolveParam(p, mapper)),
+      ...tx.batchWrite === true ? { batchWrite: true } : {}
     }))
   };
 }
@@ -1573,7 +1693,8 @@ function resolveBindingView(model, mapper, options = {}) {
 // src/codegen/python-mapper.ts
 var PythonTypeMapper = {
   language: "python",
-  scalar(type) {
+  scalar(type, format) {
+    if (format === "datetime" || format === "date") return "datetime";
     switch (type) {
       case "number":
       case "numberSet":
@@ -1597,6 +1718,7 @@ var PythonTypeMapper = {
       const lits = literals.map((l) => typeof l === "string" ? JSON.stringify(l) : String(l)).join(", ");
       return `Literal[${lits}]`;
     }
+    if (kind === "map") return "dict";
     return kind === "number" ? "float" : "str";
   },
   connection(itemType) {
@@ -1621,8 +1743,10 @@ var TYPES = `{{header}}
 from __future__ import annotations
 
 {{#if isDataclass}}from dataclasses import dataclass
-{{#if usesLiteral}}from typing import Literal
-{{/if}}{{else}}{{#if usesLiteral}}from typing import Literal, TypedDict
+{{#if datetimeImport}}{{datetimeImport}}
+{{/if}}{{#if usesLiteral}}from typing import Literal
+{{/if}}{{else}}{{#if datetimeImport}}{{datetimeImport}}
+{{/if}}{{#if usesLiteral}}from typing import Literal, TypedDict
 {{else}}from typing import TypedDict
 {{/if}}{{/if}}
 
@@ -1650,7 +1774,7 @@ var REPO_CLASS = `class {{name}}:
 
 {{/unless}}{{/each}}{{else}}    pass{{/if}}`;
 var TX_METHOD = `    def {{methodName}}(self{{#if signature}}, {{signature}}{{/if}}) -> None:
-        self._runtime.execute_transaction(
+        self._runtime.{{runtimeCall}}(
             transaction_id="{{transactionId}}",
             params={{paramsDict}},
         )`;
@@ -1755,12 +1879,17 @@ function txMethodContext(m) {
     methodName: toSnakeCase(m.transactionId),
     signature: signatureOf(m.params),
     transactionId: m.transactionId,
-    paramsDict: paramsDictOf(m.params)
+    paramsDict: paramsDictOf(m.params),
+    runtimeCall: m.batchWrite === true ? "execute_batch_write" : "execute_transaction"
   };
 }
 function classesUseLiteral(classes) {
   return classes.some((c) => c.fields.some((f) => f.type.includes("Literal[")));
 }
+function datetimeImportOf(classes) {
+  const usesDatetime = classes.some((c) => c.fields.some((f) => /\bdatetime\b/.test(f.type)));
+  return usesDatetime ? "from datetime import datetime" : void 0;
+}
 function methodsUseLiteral(view) {
   const paramLiteral = (p) => p.type.startsWith("Literal[");
   return view.repositories.some((r) => r.methods.some((m) => m.params.some(paramLiteral))) || view.transactions.some((t) => t.params.some(paramLiteral));
@@ -1798,10 +1927,12 @@ function renderTypesFile(view, options) {
     (c) => render("type-class", classContext(c, isDataclass), engine)
   );
   const body = blocks.length === 0 ? "# (no query result types)" : blocks.join("\n\n\n");
+  const datetimeImport = datetimeImportOf(view.resultClasses);
   const context = {
     header: PY_HEADER,
     isDataclass,
     usesLiteral: classesUseLiteral(view.resultClasses),
+    ...datetimeImport !== void 0 ? { datetimeImport } : {},
     body
   };
   return render("types", context, engine);
@@ -1950,6 +2081,7 @@ var PhpTypeMapper = {
     }
   },
   paramScalar(kind) {
+    if (kind === "map") return "array|\\stdClass";
     return kind === "number" ? PHP_NUMBER : "string";
   },
   connection(itemType) {
@@ -2052,7 +2184,7 @@ final class {{name}}
 }`;
 var TX_METHOD2 = `{{docblock}}    public function {{methodName}}({{signature}}): void
     {
-        $this->runtime->executeTransaction('{{transactionId}}', {{paramsArray}});
+        $this->runtime->{{runtimeCall}}('{{transactionId}}', {{paramsArray}});
     }`;
 var TX_CLASS2 = `/**
  * Typed repository for declarative transactions, wrapping a {@see GraphDDBRuntime}.
@@ -2220,7 +2352,8 @@ function txMethodContext2(method, metas) {
     signature: signatureOf2(method.params),
     transactionId: method.transactionId,
     paramsArray: paramsArrayOf(method.params),
-    docblock: txDocblockOf(method, metas)
+    docblock: txDocblockOf(method, metas),
+    runtimeCall: method.batchWrite === true ? "executeBatchWrite" : "executeTransaction"
   };
 }
 function engineOptions2(options) {
@@ -2246,12 +2379,16 @@ function renderFile(body, uses, options) {
 }
 function buildParamMetaIndex(operations, surface) {
   const index = /* @__PURE__ */ new Map();
-  const record = (opId, params) => {
+  const record = (opId, params, batchWrite = false) => {
     const inner = /* @__PURE__ */ new Map();
     for (const [name, p] of Object.entries(params)) {
       inner.set(name, {
         ...p.literals !== void 0 ? { literals: p.literals } : {},
-        ...p.type === "array" ? { elementType: `${pascal(opId)}${pascal(name)}Item` } : {}
+        // #298: a batchWrite form's `items` element is `<TxName>Item` (matching
+        // `txElementTypeName` — the generic rule would double the word).
+        ...p.type === "array" ? {
+          elementType: batchWrite && name === "items" ? `${pascal(opId)}Item` : `${pascal(opId)}${pascal(name)}Item`
+        } : {}
       });
     }
     index.set(opId, inner);
@@ -2265,7 +2402,7 @@ function buildParamMetaIndex(operations, surface) {
     if (commandSet.has(name)) record(name, spec.params ?? {});
   }
   for (const [name, spec] of Object.entries(operations.transactions ?? {})) {
-    record(name, spec.params ?? {});
+    record(name, spec.params ?? {}, spec.batchWrite === true);
   }
   recordContractMetas(index, operations, surface, record);
   return index;
@@ -2278,7 +2415,7 @@ function recordContractMetas(index, operations, surface, record) {
   for (const c of surface.contractCommands ?? []) {
     const methodSpec = operations.contracts?.[c.contract]?.methods?.[c.method];
     const single = methodSpec && "single" in methodSpec ? methodSpec.single : void 0;
-    const params = single === void 0 ? void 0 : single.mode === "transaction" ? operations.transactions?.[single.transaction]?.params : operations.commands[single.operation]?.params;
+    const params = single === void 0 ? void 0 : single.mode === "transaction" || single.mode === "batchWrite" ? operations.transactions?.[single.transaction]?.params : operations.commands[single.operation]?.params;
     if (params) record(contractOperationId(c.contract, c.method), params);
   }
 }
@@ -2397,6 +2534,7 @@ var RustTypeMapper = {
     }
   },
   paramScalar(kind) {
+    if (kind === "map") return "serde_json::Value";
     return kind === "number" ? RUST_NUMBER : "String";
   },
   connection(itemType) {
@@ -2461,6 +2599,9 @@ pub struct {{name}} {
     runtime: Arc<GraphDDBRuntime>,
 }
 
+// Generated methods use cross-language-stable \`contract__method\` names and
+// take one typed argument per contract key/shared field.
+#[allow(non_snake_case, clippy::too_many_arguments)]
 impl {{name}} {
     /// Construct the repository over a shared runtime.
     pub fn new(runtime: Arc<GraphDDBRuntime>) -> Self {
@@ -2472,7 +2613,7 @@ impl {{name}} {
 {{/if~}}
 }`;
 var TX_METHOD3 = `{{docComment}}    pub async fn {{methodName}}(&self{{#if signature}}, {{signature}}{{/if}}) -> Result<(), GraphDDBError> {
-{{paramsStmts}}        self.runtime.execute_transaction("{{transactionId}}", &params).await?;
+{{paramsStmts}}        self.runtime.{{runtimeCall}}("{{transactionId}}", &params).await?;
         Ok(())
     }`;
 var TX_STRUCT = `/// Typed repository for declarative transactions, wrapping a \`GraphDDBRuntime\`.
@@ -2481,6 +2622,9 @@ pub struct {{name}} {
     runtime: Arc<GraphDDBRuntime>,
 }
 
+// Generated methods use cross-language-stable \`contract__method\` names and
+// take one typed argument per contract key/shared field.
+#[allow(non_snake_case, clippy::too_many_arguments)]
 impl {{name}} {
     /// Construct the repository over a shared runtime.
     pub fn new(runtime: Arc<GraphDDBRuntime>) -> Self {
@@ -2534,12 +2678,16 @@ function pascal2(name) {
 }
 function buildParamMetaIndex2(operations, surface) {
   const index = /* @__PURE__ */ new Map();
-  const record = (opId, params) => {
+  const record = (opId, params, batchWrite = false) => {
     const inner = /* @__PURE__ */ new Map();
     for (const [name, p] of Object.entries(params)) {
       inner.set(name, {
         ...p.literals !== void 0 ? { literals: p.literals } : {},
-        ...p.type === "array" ? { elementType: `${pascal2(opId)}${pascal2(name)}Item` } : {}
+        // #298: a batchWrite form's `items` element is `<TxName>Item` (matching
+        // `txElementTypeName` — the generic rule would double the word).
+        ...p.type === "array" ? {
+          elementType: batchWrite && name === "items" ? `${pascal2(opId)}Item` : `${pascal2(opId)}${pascal2(name)}Item`
+        } : {}
       });
     }
     index.set(opId, inner);
@@ -2553,7 +2701,7 @@ function buildParamMetaIndex2(operations, surface) {
     if (commandSet.has(name)) record(name, spec.params ?? {});
   }
   for (const [name, spec] of Object.entries(operations.transactions ?? {})) {
-    record(name, spec.params ?? {});
+    record(name, spec.params ?? {}, spec.batchWrite === true);
   }
   for (const q of surface.contractQueries ?? []) {
     const spec = operations.queries[q.operation];
@@ -2562,7 +2710,7 @@ function buildParamMetaIndex2(operations, surface) {
   for (const c of surface.contractCommands ?? []) {
     const methodSpec = operations.contracts?.[c.contract]?.methods?.[c.method];
     const single = methodSpec && "single" in methodSpec ? methodSpec.single : void 0;
-    const params = single === void 0 ? void 0 : single.mode === "transaction" ? operations.transactions?.[single.transaction]?.params : operations.commands[single.operation]?.params;
+    const params = single === void 0 ? void 0 : single.mode === "transaction" || single.mode === "batchWrite" ? operations.transactions?.[single.transaction]?.params : operations.commands[single.operation]?.params;
     if (params) record(contractOperationId(c.contract, c.method), params);
   }
   return index;
@@ -2676,7 +2824,8 @@ function txMethodContext3(method, metas) {
     signature: signatureOf3(method.params),
     transactionId: method.transactionId,
     paramsStmts: paramsStmtsOf(method.params),
-    docComment: txMethodDocComment(method, metas)
+    docComment: txMethodDocComment(method, metas),
+    runtimeCall: method.batchWrite === true ? "execute_batch_write" : "execute_transaction"
   };
 }
 function engineOptions3(options) {
@@ -2782,6 +2931,7 @@ var GoTypeMapper = {
     }
   },
   paramScalar(kind) {
+    if (kind === "map") return "map[string]any";
     return kind === "number" ? GO_NUMBER : "string";
   },
   connection(itemType) {
@@ -2868,7 +3018,7 @@ func New{{name}}(runtime *graphddb_runtime.GraphDDBRuntime) *{{name}} {
 
 {{body}}{{/if}}`;
 var TX_METHOD4 = `{{docComment}}func (r *{{repoName}}) {{methodName}}(ctx context.Context{{#if signature}}, {{signature}}{{/if}}) error {
-{{paramsStmts}}	return r.runtime.ExecuteTransaction(ctx, "{{transactionId}}", params, nil)
+{{paramsStmts}}	return r.runtime.{{runtimeCall}}(ctx, "{{transactionId}}", params, nil)
 }`;
 var TX_STRUCT2 = `// {{name}} is a typed repository for declarative transactions, wrapping a *graphddb_runtime.GraphDDBRuntime.
 type {{name}} struct {
@@ -2969,12 +3119,16 @@ function pascal3(name) {
 }
 function buildParamMetaIndex3(operations, surface) {
   const index = /* @__PURE__ */ new Map();
-  const record = (opId, params) => {
+  const record = (opId, params, batchWrite = false) => {
     const inner = /* @__PURE__ */ new Map();
     for (const [name, p] of Object.entries(params)) {
       inner.set(name, {
         ...p.literals !== void 0 ? { literals: p.literals } : {},
-        ...p.type === "array" ? { elementType: `${pascal3(opId)}${pascal3(name)}Item` } : {}
+        // #298: a batchWrite form's `items` element is `<TxName>Item` (matching
+        // `txElementTypeName` — the generic rule would double the word).
+        ...p.type === "array" ? {
+          elementType: batchWrite && name === "items" ? `${pascal3(opId)}Item` : `${pascal3(opId)}${pascal3(name)}Item`
+        } : {}
       });
     }
     index.set(opId, inner);
@@ -2988,7 +3142,7 @@ function buildParamMetaIndex3(operations, surface) {
     if (commandSet.has(name)) record(name, spec.params ?? {});
   }
   for (const [name, spec] of Object.entries(operations.transactions ?? {})) {
-    record(name, spec.params ?? {});
+    record(name, spec.params ?? {}, spec.batchWrite === true);
   }
   for (const q of surface.contractQueries ?? []) {
     const spec = operations.queries[q.operation];
@@ -2997,7 +3151,7 @@ function buildParamMetaIndex3(operations, surface) {
   for (const c of surface.contractCommands ?? []) {
     const methodSpec = operations.contracts?.[c.contract]?.methods?.[c.method];
     const single = methodSpec && "single" in methodSpec ? methodSpec.single : void 0;
-    const params = single === void 0 ? void 0 : single.mode === "transaction" ? operations.transactions?.[single.transaction]?.params : operations.commands[single.operation]?.params;
+    const params = single === void 0 ? void 0 : single.mode === "transaction" || single.mode === "batchWrite" ? operations.transactions?.[single.transaction]?.params : operations.commands[single.operation]?.params;
     if (params) record(contractOperationId(c.contract, c.method), params);
   }
   return index;
@@ -3099,7 +3253,8 @@ function txMethodContext4(repoName, method, metas) {
     signature: signatureOf4(method.params),
     transactionId: method.transactionId,
     paramsStmts: paramsStmtsOf2(method.params),
-    docComment: methodDocComment2(methodName, void 0, method.params, metas)
+    docComment: methodDocComment2(methodName, void 0, method.params, metas),
+    runtimeCall: method.batchWrite === true ? "ExecuteBatchWrite" : "ExecuteTransaction"
   };
 }
 function engineOptions4(options) {
@@ -3670,6 +3825,14 @@ function generateCdcRegistry(options = {}) {
 }
 
 // src/codegen/docs-model.ts
+function keyConditionTemplates(op) {
+  if (op.keyCondition) return { ...op.keyCondition };
+  const out = {};
+  for (const [attr, node] of Object.entries(op.keyExpr ?? {})) {
+    out[attr] = renderKeyExprToTemplate(node);
+  }
+  return out;
+}
 var AS_CONFIGURED = "as configured at deployment";
 function fieldTypeLabel(entity, field) {
   const f = entity.fields[field];
@@ -3709,17 +3872,37 @@ function referencesField(template, field) {
 function keyLabel(prefix, template) {
   return template ? `${prefix} = ${template}` : "";
 }
+function exprLiteralPrefix(node) {
+  if (typeof node === "string") return node;
+  if (node !== null && typeof node === "object" && "concat" in node) {
+    const first = node.concat[0];
+    if (typeof first === "string") return first;
+  }
+  return "";
+}
+function relationHops(component) {
+  const hops = [];
+  for (const node of component?.body ?? []) {
+    if (node.id === "root" || "cond" in node) continue;
+    const kind = "map" in node ? node.map.component : node.component;
+    const ports = "map" in node ? node.map.ports : node.ports;
+    const indexName = typeof ports.indexName === "string" ? ports.indexName : void 0;
+    const table = typeof ports.table === "string" ? ports.table : "";
+    const pkNode = (indexName ? ports[`${indexName}PK`] : void 0) ?? ports.PK ?? ports.pk;
+    hops.push({
+      type: kind,
+      tableName: table,
+      ...indexName !== void 0 ? { indexName } : {},
+      pkTemplate: exprLiteralPrefix(pkNode)
+    });
+  }
+  return hops;
+}
 function rootIndex(spec) {
   const root = spec.operations[0];
   if (!root) return "";
   return root.indexName ?? "PK";
 }
-function isRelation(spec) {
-  return spec.operations.length > 1;
-}
-function usesBatchGet(spec) {
-  return spec.operations.some((op) => op.type === "BatchGetItem");
-}
 function usesCursor(spec) {
   return (spec.cardinality ?? "many") === "many";
 }
@@ -3736,10 +3919,11 @@ function inputShape(spec) {
   return `{ ${parts.join(", ")} }`;
 }
 function opPkTemplate(op) {
+  const kc = keyConditionTemplates(op);
   if (op.indexName) {
-    return op.keyCondition[`${op.indexName}PK`] ?? op.keyCondition["PK"] ?? op.keyCondition["pk"] ?? "";
+    return kc[`${op.indexName}PK`] ?? kc["PK"] ?? kc["pk"] ?? "";
   }
-  return op.keyCondition["PK"] ?? op.keyCondition["pk"] ?? "";
+  return kc["PK"] ?? kc["pk"] ?? "";
 }
 function rootEntityName(spec, manifest) {
   const root = spec.operations[0];
@@ -3756,10 +3940,10 @@ function outputShape(spec, entityName) {
   const base = entityName || "Result";
   return many ? `Page<${base}>` : base;
 }
-function buildResolution(spec, manifest) {
+function buildResolution(spec, relHops, manifest) {
   const root = spec.operations[0];
   if (!root) return { resolve: "", diagram: [] };
-  if (spec.operations.length === 1) {
+  if (relHops.length === 0) {
     const keyLabelStr = rootKeyLabel(root);
     const proj = root.projection.length > 0 ? `Projection(${root.projection.slice(0, 4).join(", ")})` : "Projection";
     const resolve4 = `${keyLabelStr} \u2192 ${root.type} \u2192 ${proj}`;
@@ -3773,13 +3957,22 @@ function buildResolution(spec, manifest) {
     ];
     return { resolve: resolve4, diagram: diagram2 };
   }
+  const hops = [
+    {
+      type: root.type,
+      tableName: root.tableName,
+      ...root.indexName !== void 0 ? { indexName: root.indexName } : {},
+      pkTemplate: opPkTemplate(root)
+    },
+    ...relHops
+  ];
   const entityHops = [];
   const diagram = [];
-  for (let i = 0; i < spec.operations.length; i++) {
-    const op = spec.operations[i];
-    const entity = opEntityName(op, manifest) || op.tableName;
-    entityHops.push(`${op.type}(${entity}${op.indexName ? ` by ${op.indexName}` : ""})`);
-    const edge = i < spec.operations.length - 1 ? spec.operations[i + 1].type === "BatchGetItem" ? "BatchGet" : op.indexName ?? "PK" : "";
+  for (let i = 0; i < hops.length; i++) {
+    const hop = hops[i];
+    const entity = hopEntityName(hop, manifest) || hop.tableName;
+    entityHops.push(`${hop.type}(${entity}${hop.indexName ? ` by ${hop.indexName}` : ""})`);
+    const edge = i < hops.length - 1 ? hops[i + 1].type === "BatchGetItem" ? "BatchGet" : hop.indexName ?? "PK" : "";
     diagram.push({ label: entity, edge });
   }
   return { resolve: entityHops.join(" \u2192 "), diagram };
@@ -3789,10 +3982,10 @@ function rootKeyLabel(op) {
   const prefix = op.indexName ? `${op.indexName} PK` : "PK";
   return `${prefix} = ${pk}`;
 }
-function opEntityName(op, manifest) {
-  const pk = opPkTemplate(op);
+function hopEntityName(hop, manifest) {
+  const pk = hop.pkTemplate;
   for (const [name, entity] of Object.entries(manifest.entities)) {
-    const cand = op.indexName ? gsiByName(entity, op.indexName)?.pkTemplate : entity.key?.pkTemplate;
+    const cand = hop.indexName ? gsiByName(entity, hop.indexName)?.pkTemplate : entity.key?.pkTemplate;
     if (cand && pk) {
       if (literalPrefix(cand) === literalPrefix(pk)) return name;
     }
@@ -3998,14 +4191,18 @@ function buildDocModel(manifest, operations, registry = MetadataRegistry, option
       )
     };
   });
+  const componentByName = new Map(
+    (operations.components ?? []).map((c) => [c.name, c])
+  );
   const accessPatterns = [];
   const accessMatrix = [];
   for (const name of Object.keys(operations.queries).sort()) {
     const spec = operations.queries[name];
     const entityName = rootEntityName(spec, manifest);
-    const { resolve: resolve4, diagram } = buildResolution(spec, manifest);
-    const relation = isRelation(spec);
-    const batchGet = usesBatchGet(spec);
+    const relHops = relationHops(componentByName.get(name));
+    const { resolve: resolve4, diagram } = buildResolution(spec, relHops, manifest);
+    const relation = relHops.length > 0;
+    const batchGet = spec.operations[0]?.type === "BatchGetItem" || relHops.some((h) => h.type === "BatchGetItem");
     const cursor = usesCursor(spec);
     const index = rootIndex(spec);
     const methodName = name.includes("__") ? name.slice(name.lastIndexOf("__") + 2) : name;
@@ -4366,6 +4563,9 @@ function renderBundle(queries = {}, commands = {}, registry = MetadataRegistry,
   };
 }
 
+// src/cli/handlers.ts
+import { generateModule, GeneratorFailure } from "behavior-contracts";
+
 // src/codegen/jsdoc.ts
 async function loadTypescript() {
   try {
@@ -4817,6 +5017,92 @@ var handlers = {
       fail("GENERATION_FAILED", message, 1);
     }
   },
+  /**
+   * `generate behaviors --lang <ts|python|go|rust|php>` (issue #257 — the
+   * codegen-static endpoint, §7.3 endpoint 3).
+   *
+   * Loads the TypeScript definitions exactly like `generate python`, builds the
+   * SAME operations bundle (so the components[] are byte-identical to the ones
+   * a `generate python` run serializes into operations.json — the fingerprint
+   * skew check in the consuming runtimes depends on this), wraps the universal
+   * `components[]` into the portable IR envelope, and invokes behavior-contracts'
+   * common Generator (`generateModule`, bc#13). graphddb adds NO generation
+   * logic: envelope + invoke + file write only. The dynamic JSON path stays the
+   * default; the generated module is the opt-in static endpoint.
+   */
+  async generateBehaviors(options) {
+    const {
+      lang,
+      entry,
+      transactions: transactionsPath,
+      contracts: contractsPath,
+      contexts: contextsPath,
+      runtimeImport,
+      out
+    } = options;
+    if (!lang) fail("INVALID_ARGS", "Missing required option --lang.", 2);
+    if (!entry) fail("INVALID_ARGS", "Missing required option --entry.", 2);
+    if (!out) fail("INVALID_ARGS", "Missing required option --out.", 2);
+    const LANGUAGES = {
+      ts: { language: "typescript" },
+      python: { language: "python" },
+      go: { language: "go" },
+      rust: { language: "rust" },
+      php: { language: "php", runtimeImport: "GraphDDB\\Runtime\\BehaviorContracts" }
+    };
+    const target = LANGUAGES[lang];
+    if (target === void 0) {
+      fail(
+        "INVALID_ARGS",
+        `Unknown --lang '${lang}' (supported: ${Object.keys(LANGUAGES).join(", ")}).`,
+        2
+      );
+    }
+    try {
+      await importModelEntry(entry);
+      const queries = {};
+      const commands = {};
+      const transactions = await loadOptionalMap(
+        transactionsPath ?? entry,
+        "transactions"
+      );
+      const contracts = await loadOptionalMap(
+        contractsPath ?? entry,
+        "contracts"
+      );
+      const contexts = await loadOptionalMap(
+        contextsPath ?? contractsPath ?? entry,
+        "contexts"
+      );
+      const abs = (p) => isAbsolute(p) ? p : resolve3(process.cwd(), p);
+      await applyJsDocDescriptions({ entry: abs(entry) });
+      const doc = buildOperations(queries, commands, transactions, { contracts, contexts });
+      const components = doc.components ?? [];
+      const generated = generateModule(
+        portableIrDocument(components),
+        {
+          language: target.language,
+          ...runtimeImport !== void 0 ? { runtimeImport } : target.runtimeImport !== void 0 ? { runtimeImport: target.runtimeImport } : {}
+        }
+      );
+      const outDir = isAbsolute(out) ? out : resolve3(process.cwd(), out);
+      mkdirSync(outDir, { recursive: true });
+      writeFileSync(resolve3(outDir, generated.filenameHint), generated.code, "utf8");
+      process.stdout.write(
+        JSON.stringify({
+          status: "ok",
+          outDir: out,
+          files: [generated.filenameHint]
+        }) + "\n"
+      );
+    } catch (err) {
+      if (err instanceof GeneratorFailure) {
+        fail(`GENERATOR_${err.code}`, err.message, 1);
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      fail("GENERATION_FAILED", message, 1);
+    }
+  },
   /**
    * `generate php --typed` (issue #219, Epic #216 — typed-binding codegen).
    *