graphddb 0.9.0 → 0.9.2

package/README.md

@@ -1,41 +1,63 @@
 # GraphDDB
 
-**Build GraphQL-like queries directly on DynamoDB —— while keeping every access pattern explicit.**
+**Portable, contract-first DynamoDB access patterns.**
 
-GraphDDB is a type-safe Runtime that maps DynamoDB's native access patterns onto a GraphQL-like query
-model. PK / GSI / projection / relation / cursor / operation limits are all kept visible rather than hidden.
-It is not an ORM —— it is for **defining, validating, and executing** DynamoDB access patterns through
-TypeScript types.
+GraphDDB lets you define your DynamoDB access patterns once in TypeScript, validate them at build time,
+inspect the exact execution plan before anything runs, and execute the *same* contract from five
+languages — TypeScript, Python, Rust, Go, and PHP. It is **not an ORM**: it is a contract compiler +
+runtime for explicit DynamoDB access patterns.
 
-## ✨ Features
+The access patterns become a portable, executable artifact. TypeScript is the single source of truth;
+a static planner lowers each contract to a language-neutral IR (`manifest.json` + `operations.json`),
+and every language runtime executes that IR with results pinned **byte-identical** by a shared
+conformance suite. GraphQL-like traversal is one of the authoring surfaces — ergonomic, but not the
+point. The point is that PK / GSI / projection / relation / cursor / operation limits stay explicit,
+verifiable, and portable rather than hidden behind an abstraction.
+
+## ✨ What GraphDDB does — in three layers
+
+**1. Define** explicit DynamoDB access patterns
 
 - ✅ **Type-safe models** —— the TS class is the single source of truth. Keys / GSIs / field types are checked at compile time.
-- ✅ **Graph-style traversal** —— nest `@hasMany` / `@belongsTo` / `@hasOne` inside `select`.
-- ✅ **Automatic access-pattern resolution** —— the runtime picks the PK / GSI from the fields you give.
-- ✅ **Projection** —— only `select`ed fields are read, and only those appear in the result type.
-- ✅ **Execution plan (Explain)** —— inspect the execution plan before touching DynamoDB.
-- ✅ **CQRS contracts** —— public Query/Command contracts (N+1-safe, context boundaries).
-- ✅ **Python generation** —— generate a Python client + runtime from TS as the SSoT (conformance-verified).
-- ✅ **Testing adapter** —— unit-test planner / traversal / transaction / CDC with an in-memory executor.
-- ✅ **Middleware** —— host-side hooks for reads / writes (logging, tenant, authorization).
-- ✅ **CDC emulator** —— drive and test change events equivalent to DynamoDB Streams locally.
-- ✅ **CDC projection** —— `@cdcProjected()` + `fromChange` / `subscribe` parse CDC change events into typed records (sink delivery / idempotency stay with the consumer).
-- ✅ **Maintained access paths** —— keep embedded snapshots / aggregate counters synchronized atomically.
-- ✅ **CloudFormation generation** —— emit a CloudFormation template for the DynamoDB table(s) a model set maps onto (GSI union / Streams / TTL / PITR / TableClass / SSE / PROVISIONED / Auto Scaling).
-- ✅ **Docs generation** —— generate a model specification (Markdown + Mermaid) from the TS models; templates are Handlebars and user-overridable.
+- ✅ **Graph-style traversal** —— nest `@hasMany` / `@belongsTo` / `@hasOne` inside `select` (an ergonomic authoring surface — arguments → key lookup, selection → projection).
+- ✅ **CQRS contracts** —— public Query/Command contracts as the read/write authoring surface (N+1-safe, context boundaries, composition across contracts).
+- ✅ **Maintained access paths** —— declare embedded snapshots / aggregate counters kept synchronized atomically with the source write.
+
+**2. Validate & explain** before anything touches DynamoDB
+
+- ✅ **Compile-time safety** —— undefined relations, missing GSIs, limit-less lists, and over-depth traversals are rejected at compile time / by the linter — equally for human- and AI-written code.
+- ✅ **Execution plan (Explain)** —— `explain()` returns the exact DynamoDB operations, so RCU shape is inspectable up front.
+- ✅ **Automatic access-pattern resolution** —— the runtime picks the PK / GSI from the fields you give; `select`ed fields are the only ones read and the only ones in the result type.
+- ✅ **In-memory testing** —— unit-test planner / traversal / transaction / CDC with no Docker, no DynamoDB Local.
+
+**3. Execute the same contract, portably, from five languages**
+
+- ✅ **Portable executable IR** —— the static planner lowers each contract to a language-neutral bridge bundle (`manifest.json` + `operations.json`, a `components[]` graph on the shared behavior-contracts vocabulary).
+- ✅ **5 language runtimes** —— generate clients + runtimes for **Python / Rust / Go / PHP** (TypeScript runs the IR natively), all executing the same access patterns.
+- ✅ **5-language conformance** —— TS / Python / Rust / Go / PHP run the same cases against DynamoDB Local; CI pins the results **byte-identical**.
+
+**Operational surface** (all built on the layers above): **Middleware** (host-side read/write hooks) ·
+**CDC emulator** (local DynamoDB-Streams-equivalent change events) · **CDC projection**
+(`@cdcProjected()` + `fromChange` / `subscribe` into typed records) · **Prepared statements**
+(compile-once / execute-many, AOT static plans) · **CloudFormation generation** ·
+**Docs generation** (Markdown + Mermaid, Handlebars-overridable).
 
 ## 🤔 Philosophy
 
+- **Access patterns as portable contracts** —— an access pattern is defined once and becomes a
+  language-neutral, executable artifact. The same contract is validated, explained, and then executed
+  identically across languages, instead of being re-implemented per stack.
 - **Native DynamoDB access patterns** —— express access patterns directly in code instead of hiding them
   behind an ORM abstraction. Because PK / GSI, projection, and limits stay visible, the correct design
   becomes the easiest path.
-- **Graph-style traversal** —— GraphQL's query model (arguments → key lookup, selection → projection,
-  relation → Query/Get/BatchGet) corresponds naturally to DynamoDB's access patterns.
 - **Compile-time safety** —— undefined relations, missing GSIs, limit-less lists, and traversals exceeding
   the allowed depth are rejected before execution at compile time / by the linter. The same constraints
   apply equally to human-written and AI-generated code.
 - **Runtime transparency** —— the runtime is not a black box. `explain()` shows the execution plan, and the
   plan reveals the shape of RCU usage.
+- **Graph-style traversal is a surface, not the essence** —— GraphQL's query model (arguments → key
+  lookup, selection → projection, relation → Query/Get/BatchGet) is a convenient way to *author* access
+  patterns; the essence is the explicit, portable contract underneath.
 
 ## 📦 Install
 
@@ -57,7 +79,7 @@ Node.js ≥ 22 is required.
 ## 🚀 Quick Start
 
 ```ts
-import { DDBModel, model, string, key, k } from 'graphddb';
+import { DDBModel, graphddb, model, string, key, k } from 'graphddb';
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 
 @model({ table: 'AppTable', prefix: 'USER' })
@@ -200,8 +222,16 @@ Each capability is summarized here only. For details, operator lists, and proced
   authorization scoping). Host-only and non-serialized. For hook points, see [`docs/middleware.md`](./docs/middleware.md).
 - **Class hydration** —— `options.hydrate` loads read results into host-language domain objects (opt-in,
   Phase 1: `query` top level). [`docs/class-hydration.md`](./docs/class-hydration.md).
-- **Python bridge** —— generate a Python client + runtime with TS as the SSoT, kept in step by a TS↔Python
-  conformance suite. [`docs/python-bridge.md`](./docs/python-bridge.md).
+- **Multi-language bridge** —— generate Python / Rust / Go / PHP clients + runtimes with TS as the SSoT,
+  kept in step by a 5-language conformance suite. [`docs/python-bridge.md`](./docs/python-bridge.md).
+- **Prepared statements** —— `graphddb.prepare($ => ({...}))` → `.execute(params)` (unified read/write).
+  "Contract-free precompilation": compile a declarative route once and execute it repeatedly with
+  different params. With the **true build-time compilation (AOT)** of `graphddb transform prepared
+  --aot`, plans are emitted as static artifacts and zero runtime compilation happens, including the
+  first call (a stale plan is loud-rejected at load; drift is caught in CI). Without the transform,
+  behavior stays identical through the lazy-slot + structural-memoization fallback. no-runtime-capture
+  is loudly enforced by a build-time lint + a runtime guard.
+  [`docs/prepared-statements.md`](./docs/prepared-statements.md).
 - **CQRS contracts** —— public Query/Command contracts (cardinality matrix, N+1 safety, context boundaries,
   composition across contracts). [`docs/cqrs-contract.md`](./docs/cqrs-contract.md) /
   [`docs/mutation-command-derivation.md`](./docs/mutation-command-derivation.md).
@@ -212,6 +242,17 @@ Each capability is summarized here only. For details, operator lists, and proced
   `graphddb.subscribe(handlers)` (the sibling of `query` / `mutate`) produces a `ChangeHandler` the
   consumer mounts on its own stream. graphddb owns parse→typed record only; subscription, sink
   delivery, and idempotency are the consumer's. [`docs/cdc-projection.md`](./docs/cdc-projection.md).
+- **Multi-language codegen (the 3 paths, #257)** —— execution keeps 2 paths + 1 consumer surface,
+  coexisting permanently: (1) **dynamic JSON path (default)** — the `components[]` of
+  `operations.json` are loaded at runtime and interpreted by the shared `run_behavior` (for swapping
+  behavior without a deploy). (2) **codegen-static path (opt-in)** — `graphddb generate behaviors
+  --lang <ts|python|go|rust|php>` hands the same IR to the **shared upstream behavior-contracts
+  generator** (bc#13), emitting modules with the IR baked in as native literals (graphddb owns only
+  envelope + invoke — no generation logic). A generated module checks its fingerprint against the
+  live registry and loud-rejects when stale (#208 discipline). Rust generated modules use
+  `std::sync::LazyLock`, so **Rust >= 1.80** is required. (3) **typed bindings
+  (`generate python/php/rust/go`)** — the consumer-UX surface (typed repositories / DTOs), still
+  graphddb-owned; not an execution engine — it delegates to the paths above.
 - **CloudFormation generation** —— `graphddb generate cloudformation` emits a CloudFormation template for
   the DynamoDB table(s) a model set maps onto (GSI union / Streams / TTL / PITR / PROVISIONED / Auto
   Scaling). [`docs/cloudformation.md`](./docs/cloudformation.md).
@@ -232,10 +273,11 @@ documentation available offline at hand. On GitHub, follow the links in the tabl
 | [Specification](./docs/spec.md) | Core API: entities, structured keys/GSIs, query/filter, relations, batch/transaction, design rules, runtime behavior. |
 | [Design patterns](./docs/design-patterns.md) | Mapping representative DynamoDB design patterns onto graphddb features (how to declare `pattern` / `@model({ kind })` + `@maintainedFrom` / `@aggregate`, read & write maintenance, per-phase coverage). |
 | [Middleware / Hooks](./docs/middleware.md) | The `graphddb.config.use` host-side middleware: hook points read R1–R5 / write W1–W5, `{ context }`, ordering. |
+| [Prepared statements](./docs/prepared-statements.md) | `graphddb.prepare` / `.execute` (unified read/write prepared statements), the no-runtime-capture constraint, `graphddb transform prepared` (AOT static plans / compile-time hoisting + build-time lint + drift detection): choosing between the 3 tiers AOT > lazy slot + structural memoization > ad-hoc. |
 | [CQRS contract layer](./docs/cqrs-contract.md) | Public Query/Command contracts, cardinality matrix, N+1 safety, composition across contracts, context boundaries. |
 | [Mutation → command derivation](./docs/mutation-command-derivation.md) | The internal write-plan composition DSL behind the Command IF (`entityWrites`, fragment composition, derivation of atomic `TransactWriteItems`). |
 | [Class hydration](./docs/class-hydration.md) | Opt-in `options.hydrate` that loads read results into host objects (Phase 1: `query` top level). |
-| [Multi-language / Python bridge](./docs/python-bridge.md) | Code generation with TS as the SSoT and a Python runtime; TS↔Python conformance. |
+| [Multi-language bridge](./docs/python-bridge.md) | Code generation with TS as the SSoT and Python / Rust / Go / PHP runtimes; 5-language conformance. |
 | [In-memory test adapter](./docs/testing.md) | Docker-free in-process testing with `graphddb/testing` and `MemoryInspector`. |
 | [CDC emulator](./docs/cdc-emulator.md) | A change-event emulator for differential aggregation patterns (dev/test). |
 | [CDC projection](./docs/cdc-projection.md) | The `@cdcProjected()` + `fromChange` / `subscribe` typed-consumer-IF: a contract that parses CDC change events into typed records. Boundary (parse→typed is graphddb; subscription, sink delivery, idempotency are the consumer's). |
@@ -256,23 +298,30 @@ documentation available offline at hand. On GitHub, follow the links in the tabl
 
 A query travels from the TS Model through the Planner / Runtime to DynamoDB:
 
-```mermaid
-flowchart LR
-    M["TS Model<br/>Entity / Key / GSI / Relation"] --> P["Planner<br/>access pattern resolution / projection"]
-    P --> R["Runtime<br/>execute / retry / hydrate"]
-    R --> D[("DynamoDB")]
-```
+![Query execution pipeline: TS Model → Planner → Runtime → DynamoDB](./docs/diagrams/query-pipeline.en.svg)
 
-From the same TS Model (the SSoT), multiple targets are derived:
+From the same TS Model (the SSoT), multiple targets are derived. The language runtimes are fanned out to
+4 languages through the portable IR (the `components[]` graph in `manifest.json` + `operations.json`),
+and the execution results of all 5 languages — TS included — are pinned byte-identical by the
+conformance suite:
 
-```mermaid
-flowchart LR
-    M["TS Model (SSoT)"] --> RT["Runtime (TS)"]
-    M --> PY["Python client + runtime"]
-    M --> CQ["CQRS Contract"]
-    M --> CFN["CloudFormation template"]
-    M --> DOC["Model docs (Markdown + Mermaid)"]
-```
+![SSoT derivation: TS Model → TS runtime / portable IR → 4 language runtimes / CQRS / CloudFormation / docs](./docs/diagrams/ssot-derivation.en.svg)
+
+| Runtime | Package | Distribution |
+|---------|---------|--------------|
+| TypeScript | `graphddb` | npm |
+| Python | `graphddb-runtime` | PyPI |
+| Rust | `graphddb_runtime` | crates.io |
+| Go | `github.com/foo-log-inc/graphddb/go` | go module (`go/vX.Y.Z` tags) |
+| PHP | `graphddb/runtime` | bundled in-repo (not on composer) |
+
+Multi-language execution keeps 3 permanent paths — 2 execution paths + 1 consumer surface (see
+"Multi-language codegen" under [More Capabilities](#-more-capabilities)):
+
+![The three multi-language execution paths: authoring → static planner → portable IR → dynamic JSON / codegen-static / typed bindings](./docs/diagrams/execution-paths.en.svg)
+
+> The figures are self-contained SVGs drawn with diagram-contracts (Draw TSX).
+> Sources live in [`diagrams/`](./diagrams/); regenerate with `diagrams/build.sh`.
 
 ## 📄 License
 

package/dist/cdc/index.d.ts

@@ -1,7 +1,7 @@
-import { w as CdcEmulatorOptions, x as ChangeHandler, y as Unsubscribe, F as FaultSpec, z as ConcurrentRecomputeRef, v as ChangeEvent, A as EventLog, G as ReplayOptions, H as ShardId, I as MaintainTrigger, E as EffectPath, g as ProjectionMap, j as MembershipPredicate } from '../key-Dne-a20Q.js';
-export { J as BatchResult, K as CdcMode, L as ChangeBatch, N as ChangeEventName, O as ClockMode, V as StartingPosition, X as StreamViewType, Y as SubscribeHandler, Z as SubscribeHandlers, _ as buildSubscribeHandler } from '../key-Dne-a20Q.js';
-import { E as EntityMetadata } from '../types-BnFsTZwl.js';
-import '../types-CfxzTEFL.js';
+import { w as CdcEmulatorOptions, x as ChangeHandler, y as Unsubscribe, F as FaultSpec, z as ConcurrentRecomputeRef, v as ChangeEvent, A as EventLog, G as ReplayOptions, H as ShardId, I as MaintainTrigger, E as EffectPath, g as ProjectionMap, j as MembershipPredicate } from '../key-CWytoEaE.js';
+export { J as BatchResult, K as CdcMode, L as ChangeBatch, N as ChangeEventName, O as ClockMode, V as StartingPosition, X as StreamViewType, Y as SubscribeHandler, Z as SubscribeHandlers, _ as buildSubscribeHandler } from '../key-CWytoEaE.js';
+import { E as EntityMetadata } from '../types-nk5okD7d.js';
+import '../types-CgXS-4Ox.js';
 import 'behavior-contracts';
 
 /**

package/dist/cdc/index.js

@@ -8,12 +8,12 @@ import {
   createMaintenanceDrainHandler,
   hashString,
   shardIdFor
-} from "../chunk-YGQ2NO6J.js";
+} from "../chunk-VECUS35D.js";
 import {
   buildSubscribeHandler,
   parseChange
-} from "../chunk-KOIJ4SNO.js";
-import "../chunk-ZNU7OI5I.js";
+} from "../chunk-7OCXY4R6.js";
+import "../chunk-GWWRXIHF.js";
 import "../chunk-XTWXMOHD.js";
 export {
   CdcEmulator,

package/dist/{chunk-KOIJ4SNO.js → chunk-7OCXY4R6.js}

@@ -1,7 +1,7 @@
 import {
   MetadataRegistry,
   attachHiddenKey
-} from "./chunk-ZNU7OI5I.js";
+} from "./chunk-GWWRXIHF.js";
 import {
   resolveKey,
   segmentFieldNames

package/dist/{chunk-ZNU7OI5I.js → chunk-GWWRXIHF.js}

@@ -2070,9 +2070,21 @@ function buildUpdateInput(modelClass, entity, changes, options) {
   const embeddedFieldNames = new Set(
     meta.embeddedFields.map((e) => e.propertyName)
   );
-  const updateResult = buildUpdateExpression(serializedChanges, embeddedFieldNames);
-  const names = { ...updateResult.names };
-  const values = { ...updateResult.values };
+  const addEntries = Object.entries(options?.add ?? {});
+  const addNames = {};
+  const addValues = {};
+  const addClauses = [];
+  addEntries.forEach(([field, delta], i) => {
+    const nameKey = `#add${i}`;
+    const valueKey = `:add${i}`;
+    addNames[nameKey] = field;
+    addValues[valueKey] = delta;
+    addClauses.push(`${nameKey} ${valueKey}`);
+  });
+  const hasChanges = Object.keys(serializedChanges).length > 0;
+  const updateResult = hasChanges || addClauses.length === 0 ? buildUpdateExpression(serializedChanges, embeddedFieldNames) : { expression: "", names: {}, values: {} };
+  const names = { ...updateResult.names, ...addNames };
+  const values = { ...updateResult.values, ...addValues };
   const gsiSetClauses = buildGsiRederiveSets(
     modelClass,
     meta,
@@ -2090,13 +2102,16 @@ function buildUpdateInput(modelClass, entity, changes, options) {
     Object.assign(names, condResult.names);
     Object.assign(values, condResult.values);
   }
+  const setPortion = appendSetClauses(updateResult.expression, gsiSetClauses);
+  const addPortion = addClauses.length > 0 ? `ADD ${addClauses.join(", ")}` : "";
+  const updateExpression = [setPortion, addPortion].filter((s) => s !== "").join(" ");
   const updateInput = {
     TableName: tableName,
     Key: {
       PK: pk,
       SK: sk
     },
-    UpdateExpression: appendSetClauses(updateResult.expression, gsiSetClauses),
+    UpdateExpression: updateExpression,
     ExpressionAttributeNames: names
   };
   if (Object.keys(values).length > 0) {

package/dist/{chunk-XZTA4VJH.js → chunk-HLFNCKFV.js}

@@ -17,7 +17,7 @@ import {
   normalizeTopLevelSelect,
   parseChange,
   validateInlineSnapshotSelect
-} from "./chunk-KOIJ4SNO.js";
+} from "./chunk-7OCXY4R6.js";
 import {
   EXPR_VERSION,
   MARKER_ROW_ENTITY,
@@ -61,7 +61,7 @@ import {
   serializeFieldValue,
   serializeRawCondition,
   skTemplate
-} from "./chunk-ZNU7OI5I.js";
+} from "./chunk-GWWRXIHF.js";
 import {
   TableMapping,
   createColumnMap,
@@ -2520,7 +2520,12 @@ function renderWrite(op, key, params, contextLabel) {
     return { ...base, item: renderRecord(op.item, key, params, `${contextLabel} item`) };
   }
   if (op.operation === "update") {
-    return { ...base, changes: renderRecord(op.changes, key, params, `${contextLabel} changes`) };
+    const add = op.add !== void 0 && Object.keys(op.add).length > 0 ? renderRecord(op.add, key, params, `${contextLabel} add`) : void 0;
+    return {
+      ...base,
+      changes: renderRecord(op.changes, key, params, `${contextLabel} changes`),
+      ...add !== void 0 ? { add } : {}
+    };
   }
   return base;
 }
@@ -2534,11 +2539,34 @@ async function executeSingleWrite(w, retry) {
     return;
   }
   if (w.operation === "update") {
+    if (w.add !== void 0) {
+      const primaryOptions = { ...options ?? {}, add: w.add };
+      if (w.condition === void 0) {
+        await executeUpdate(w.modelClass, w.key, w.changes ?? {}, primaryOptions);
+        return;
+      }
+      try {
+        await executeUpdate(w.modelClass, w.key, w.changes ?? {}, primaryOptions);
+      } catch (e) {
+        if (!isConditionalCheckFailure(e)) throw e;
+        const fallbackOptions = {
+          add: w.add,
+          ...retry !== void 0 ? { retry } : {}
+        };
+        await executeUpdate(w.modelClass, w.key, {}, fallbackOptions);
+      }
+      return;
+    }
     await executeUpdate(w.modelClass, w.key, w.changes ?? {}, options);
     return;
   }
   await executeDelete(w.modelClass, w.key, options);
 }
+function isConditionalCheckFailure(e) {
+  if (e === null || typeof e !== "object") return false;
+  const name = e.name;
+  return name === "ConditionalCheckFailedException" || name === "ConditionalCheckFailed";
+}
 function renderConditionCheck(check, key, params, contextLabel) {
   const modelClass = check.entity.modelClass;
   const referencedKey = {};
@@ -4428,8 +4456,17 @@ function isConcreteLiteral(value) {
   const t = typeof value;
   return value === null || value instanceof Date || t === "string" || t === "number" || t === "boolean";
 }
-function makeFragment(intent, entity, input, use, condition) {
+function makeFragment(intent, entity, input, use, condition, add) {
   const checked = assertFaithfulInput(input ?? {}, intent, entity.name);
+  let checkedAdd;
+  if (add !== void 0 && Object.keys(add).length > 0) {
+    if (intent !== "update") {
+      throw new Error(
+        `mutation: the '${intent}' fragment on '${entity.name}' declares \`add\`, but an atomic \`ADD\` (issue #301) is only valid on an \`update\` fragment.`
+      );
+    }
+    checkedAdd = assertFaithfulInput(add, intent, entity.name);
+  }
   if (use !== void 0 && !isEntityWritesDefinition(use)) {
     throw new Error(
       `mutation: the '${intent}' fragment on '${entity.name}' was given a \`use:\` that is not an \`entityWrites(...)\` save contract. \`use:\` takes the WHOLE \`writes\` set (an \`entityWrites(...)\` value), never a single lifecycle (e.g. \`Model.writes.create\`) \u2014 the fragment's intent already selects the lifecycle.`
@@ -4441,6 +4478,7 @@ function makeFragment(intent, entity, input, use, condition) {
     intent,
     entity,
     input: checked,
+    ...checkedAdd !== void 0 ? { add: checkedAdd } : {},
     ...use !== void 0 ? { use } : {},
     ...checkedCondition !== void 0 ? { condition: checkedCondition } : {}
   };
@@ -4536,7 +4574,8 @@ function mutation(nameOrBody, maybeBody) {
     const { intent, entity } = resolveDescriptorTarget(descriptor, alias);
     const merged = mergeBindings(descriptor, intent, alias);
     const resolved = resolveAliasRefs(merged, aliasToIndex, alias);
-    return makeFragment(intent, entity, resolved, descriptor.use, descriptor.condition);
+    const add = descriptor.add !== void 0 ? resolveAliasRefs(descriptor.add, aliasToIndex, alias) : void 0;
+    return makeFragment(intent, entity, resolved, descriptor.use, descriptor.condition, add);
   });
   return { [COMMAND_PLAN_BRAND]: true, name, fragments };
 }
@@ -5007,6 +5046,35 @@ function writeDescriptorToPlan(name, d) {
   const model = resolveDescriptorModel(d[intent], name);
   const keyFieldNames = Object.keys(d.key);
   const inputFieldNames = d.input !== void 0 ? Object.keys(d.input) : [];
+  const addFieldNames = d.add !== void 0 ? Object.keys(d.add) : [];
+  if (addFieldNames.length > 0) {
+    if (intent !== "update") {
+      throw new Error(
+        `publishCommand: method '${name}' declares \`add\` on a '${intent}' descriptor, but an atomic \`ADD\` (issue #301) is only valid on an \`update\` (a standalone UpdateItem). A create / upsert / remove cannot carry \`add\`.`
+      );
+    }
+    if (d.add === null || typeof d.add !== "object") {
+      throw new Error(`publishCommand: method '${name}' has a non-object \`add\`.`);
+    }
+    for (const field of addFieldNames) {
+      const v = d.add[field];
+      if (!isParam(v) || v.kind !== "number") {
+        throw new Error(
+          `publishCommand: method '${name}' binds \`add.${field}\` to a non-\`param.number()\` value. An atomic \`ADD\` delta (issue #301) is a caller \`param.number()\` \u2014 a compile-time constant or a non-numeric param is not a valid atomic increment.`
+        );
+      }
+      if (keyFieldNames.includes(field)) {
+        throw new Error(
+          `publishCommand: method '${name}' binds field '${field}' in both \`key\` and \`add\`. A primary-key field cannot be atomically incremented \u2014 it belongs in \`key\` only.`
+        );
+      }
+      if (inputFieldNames.includes(field)) {
+        throw new Error(
+          `publishCommand: method '${name}' binds field '${field}' in both \`input\` (SET) and \`add\` (ADD). A field is either overwritten (\`input\`) or atomically incremented (\`add\`), never both.`
+        );
+      }
+    }
+  }
   const plan2 = mutation(name, ($) => {
     const keyRefs = (fields) => {
       const out = {};
@@ -5024,7 +5092,10 @@ function writeDescriptorToPlan(name, d) {
     const descriptor = {
       [intent]: (() => model),
       key: keyRefs(keyFieldNames),
-      ...inputFieldNames.length > 0 ? { input: inputRefs(d.input) } : {}
+      ...inputFieldNames.length > 0 ? { input: inputRefs(d.input) } : {},
+      // #301: `add` deltas are always `param.number()` (validated above), so each binds
+      // to a same-named `$.field` placeholder — the runtime resolves the caller delta.
+      ...addFieldNames.length > 0 ? { add: keyRefs(addFieldNames) } : {}
     };
     return { [name]: descriptor };
   });
@@ -5798,6 +5869,12 @@ function compileFragment(fragment, index = 0, resolveEntityRef = null, maintenan
       if (keyFieldSet.has(field)) continue;
       changes[field] = renderInputLeaf(leaf, false, index, field, resolveEntityRef);
     }
+    const add = {};
+    if (fragment.add !== void 0) {
+      for (const [field, leaf] of Object.entries(fragment.add)) {
+        add[field] = renderInputLeaf(leaf, false, index, field, resolveEntityRef);
+      }
+    }
     op = {
       __isContractMethodOp: true,
       entity: fragment.entity,
@@ -5805,6 +5882,7 @@ function compileFragment(fragment, index = 0, resolveEntityRef = null, maintenan
       keys: wholeKeysSentinel(),
       keyFields,
       ...fragment.intent === "update" ? { changes } : {},
+      ...fragment.intent === "update" && Object.keys(add).length > 0 ? { add } : {},
       // #242: a conditioned update / remove — the write is a CAS-style gate (the
       // row must satisfy the condition or the write is rejected, not silently
       // committed). Absent → an unconditional update / remove (unchanged).

package/dist/{chunk-SSVG6NQK.js → chunk-MBJ4JVRM.js}

@@ -2,7 +2,7 @@ import {
   PREPARED_FORMAT_VERSION,
   buildManifest,
   entityFingerprint
-} from "./chunk-NWTEUWJD.js";
+} from "./chunk-PHXUFAY2.js";
 import {
   analyzeWriteRoute,
   assertBundleSerializable,
@@ -21,12 +21,12 @@ import {
   isContractKeyRef,
   isContractParamRef,
   isQueryModelContract
-} from "./chunk-XZTA4VJH.js";
+} from "./chunk-HLFNCKFV.js";
 import {
   detectRelationFields,
   isInlineSnapshotSpec,
   normalizeSelectSpec
-} from "./chunk-KOIJ4SNO.js";
+} from "./chunk-7OCXY4R6.js";
 import {
   EXPR_VERSION,
   MARKER_ROW_ENTITY,
@@ -46,7 +46,7 @@ import {
   isRawCondition,
   param,
   resolveModelClass
-} from "./chunk-ZNU7OI5I.js";
+} from "./chunk-GWWRXIHF.js";
 import {
   TableMapping,
   isColumn,
@@ -232,6 +232,7 @@ function opToDefinition(contractName, methodName, op) {
   }
   const select = op.select !== void 0 ? assertBooleanProjection(op.select, `${contractName}.${methodName} select`) : void 0;
   const changes = op.changes !== void 0 ? convertStructure(op.changes, place, `${contractName}.${methodName} changes`) : void 0;
+  const add = op.add !== void 0 ? convertStructure(op.add, place, `${contractName}.${methodName} add`) : void 0;
   const condition = op.condition !== void 0 ? convertCondition(op.condition, place, `${contractName}.${methodName} condition`) : void 0;
   return {
     __isOperationDefinition: true,
@@ -240,6 +241,7 @@ function opToDefinition(contractName, methodName, op) {
     key,
     select,
     changes,
+    ...add !== void 0 ? { add } : {},
     ...condition !== void 0 ? { condition } : {},
     // #154: the use-case description captured on the recorded op (from the
     // descriptor's `description`) flows into the flattened `queries[op]` /
@@ -584,6 +586,14 @@ function toElementTemplate(template, keyParams) {
   );
 }
 function toElementRecord(record, keyParams) {
+  const out = {};
+  for (const field of Object.keys(record)) {
+    const value = record[field];
+    out[field] = typeof value === "string" ? toElementTemplate(value, keyParams) : value;
+  }
+  return out;
+}
+function toElementKeyRecord(record, keyParams) {
   const out = {};
   for (const field of Object.keys(record)) {
     out[field] = toElementTemplate(record[field], keyParams);
@@ -636,7 +646,7 @@ function synthesizeBatchTransaction(commandSpec, op) {
     tableName: commandSpec.tableName,
     entity: commandSpec.entity,
     ...commandSpec.item !== void 0 ? { item: toElementRecord(commandSpec.item, keyParams) } : {},
-    ...commandSpec.keyCondition !== void 0 ? { keyCondition: toElementRecord(commandSpec.keyCondition, keyParams) } : {},
+    ...commandSpec.keyCondition !== void 0 ? { keyCondition: toElementKeyRecord(commandSpec.keyCondition, keyParams) } : {},
     ...commandSpec.changes !== void 0 ? { changes: toElementRecord(commandSpec.changes, keyParams) } : {},
     ...condition !== void 0 ? { condition } : {},
     forEach: { source: "keys" }
@@ -829,8 +839,9 @@ function buildDerivedUpdateItems(derivedUpdates) {
       tableName,
       entity: update.entity.name,
       keyCondition,
-      // The delta is a compile-time constant → a literal numeric template (no param).
-      add: { [update.attribute]: String(update.amount) }
+      // The delta is a compile-time constant → a TYPED numeric literal (no param),
+      // carried verbatim so it marshals as `N`, not a stringified `S "1"` (#299).
+      add: { [update.attribute]: update.amount }
     });
     collectTemplateParams(keyCondition, metadata, params);
   }
@@ -890,7 +901,8 @@ function buildMaintainWriteItems(maintainWrites) {
       ...maintain.kind === "counter" && maintain.counter !== void 0 && maintain.counter.op === "count" ? {
         counter: {
           attribute: maintain.counter.attribute,
-          delta: String(maintain.counter.delta)
+          // TYPED numeric delta (#299): carried verbatim so it marshals as `N`.
+          delta: maintain.counter.delta
         }
       } : {}
     };
@@ -1713,7 +1725,7 @@ function conditionPorts(condition, ports) {
       return;
     case "equals": {
       for (const field of Object.keys(condition.fields).sort()) {
-        ports[`condition.equals.${field}`] = lowerTransactionTemplate(condition.fields[field]);
+        ports[`condition.equals.${field}`] = lowerTransactionValue(condition.fields[field]);
       }
       return;
     }
@@ -1882,11 +1894,12 @@ function paramSpecs(params) {
 function metaFor(def) {
   return MetadataRegistry.get(def.entity.modelClass);
 }
-function templateLeaf(key, value) {
+function templateValueLeaf(key, value) {
   if (isContractParamRef(value)) return value.token;
   if (isContractKeyFieldRef(value)) return `{${value.field}}`;
   if (isParam(value)) return `{${key}}`;
   if (value instanceof Date) return value.toISOString();
+  if (typeof value === "number" || typeof value === "boolean") return value;
   return String(value);
 }
 function keyFieldNames(key) {
@@ -2220,6 +2233,8 @@ function buildCommandSpec(def) {
       ...description
     };
   }
+  const addStructure = def.add;
+  const add = addStructure !== void 0 && Object.keys(addStructure).length > 0 ? { add: templateRecord(addStructure) } : {};
   return {
     type: "UpdateItem",
     tableName,
@@ -2227,6 +2242,7 @@ function buildCommandSpec(def) {
     params,
     keyCondition: writeKeyCondition(metadata, def.key, entity),
     changes: templateRecord(def.changes),
+    ...add,
     ...condition ? { condition } : {},
     ...description
   };
@@ -2253,7 +2269,7 @@ function writeKeyCondition(metadata, key, entity) {
 function templateRecord(structure) {
   const out = {};
   for (const key of Object.keys(structure).sort()) {
-    out[key] = templateLeaf(key, structure[key]);
+    out[key] = templateValueLeaf(key, structure[key]);
   }
   return out;
 }
@@ -2261,7 +2277,7 @@ function extractCondition(def) {
   return conditionInputToSpec(
     def.condition,
     `Command on '${def.entity.name}'`,
-    (field, value) => templateLeaf(field, value),
+    (field, value) => templateValueLeaf(field, value),
     (value, name) => conditionTreeLeaf(value, name),
     // A raw `cond` value slot (issue #114-B): a contract param / key ref carries
     // its own name; a plain `param.*` falls through to the positional default.

package/dist/{chunk-NWTEUWJD.js → chunk-PHXUFAY2.js}

@@ -1,12 +1,12 @@
 import {
   evaluateKey
-} from "./chunk-XZTA4VJH.js";
+} from "./chunk-HLFNCKFV.js";
 import {
   SPEC_VERSION_KEY_EXPR
 } from "./chunk-WOFRHRXY.js";
 import {
   MetadataRegistry
-} from "./chunk-ZNU7OI5I.js";
+} from "./chunk-GWWRXIHF.js";
 import {
   TableMapping
 } from "./chunk-XTWXMOHD.js";

package/dist/{chunk-YGQ2NO6J.js → chunk-VECUS35D.js}

@@ -1,6 +1,6 @@
 import {
   buildMaintenanceGraph
-} from "./chunk-KOIJ4SNO.js";
+} from "./chunk-7OCXY4R6.js";
 import {
   ChangeCaptureRegistry,
   ClientManager,
@@ -9,7 +9,7 @@ import {
   buildDeleteInput,
   buildPutInput,
   resolveModelClass
-} from "./chunk-ZNU7OI5I.js";
+} from "./chunk-GWWRXIHF.js";
 
 // src/cdc/prng.ts
 var SeededRandom = class {