graphddb 0.9.0 → 0.9.1

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 {

package/dist/cli.js

@@ -4,16 +4,16 @@ import {
   buildOperations,
   portableIrDocument,
   renderKeyExprToTemplate
-} from "./chunk-SSVG6NQK.js";
+} from "./chunk-MBJ4JVRM.js";
 import {
   buildManifest
-} from "./chunk-NWTEUWJD.js";
-import "./chunk-XZTA4VJH.js";
-import "./chunk-KOIJ4SNO.js";
+} from "./chunk-PHXUFAY2.js";
+import "./chunk-HLFNCKFV.js";
+import "./chunk-7OCXY4R6.js";
 import "./chunk-WOFRHRXY.js";
 import {
   MetadataRegistry
-} from "./chunk-ZNU7OI5I.js";
+} from "./chunk-GWWRXIHF.js";
 import {
   createDefaultLinter
 } from "./chunk-XTWXMOHD.js";

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import { ak as SelectableOf, al as PrimaryKeyOf, e as ProjectionTransform, f as MaintainEvent, j as MembershipPredicate, h as MaintainConsistency, i as MaintainUpdateMode, am as MembershipPredicateOp, an as publishQuery, ao as publishCommand, D as DDBModel, ap as RetryPolicy, aq as Middleware } from './key-Dne-a20Q.js';
-export { ar as CdcModelRegistry, as as CdcSubscribeHandlers, at as Change, au as Column, av as ColumnMap, aw as CondSlot, ax as CtxBase, ay as CtxModel, az as FilterInput, aA as GsiDefinitionMarker, aB as GsiOptions, aC as InlineSnapshotSpec, aD as Item, aE as KeyDefinitionMarker, aF as KeySegment, aG as KeySlot, aH as KeyStructure, M as ModelStatic, aI as MutateAuthoringOptions, aJ as ParamDescriptor, aK as ParamStructure, aL as PartialQueryKeyOf, aM as PersistCtx, aN as PersistOrigin, aO as QueryKeyOf, aP as QueryResult, aQ as RawCondition, aR as ReadOpCtx, aS as ReadOpKind, aT as ReadParams, aU as ReadRequestCtx, aV as ReadRequestKind, aW as RelationBuilder, aX as RelationSelect, aY as RelationSpec, aZ as RequestContext, a_ as SegmentSpec, d as SegmentedKey, a$ as SelectBuilder, b0 as SelectOf, b1 as UniqueQueryKeyOf, b2 as Updatable, b3 as WriteCtx, b4 as WriteInput, b5 as WriteKind, b6 as WriteMiddleware, b7 as cond, b8 as entityWrites, b9 as getEntityWrites, ba as gsi, bb as identity, bc as k, bd as key, be as mutate, bf as preview, bg as when } from './key-Dne-a20Q.js';
+import { ak as SelectableOf, al as PrimaryKeyOf, e as ProjectionTransform, f as MaintainEvent, j as MembershipPredicate, h as MaintainConsistency, i as MaintainUpdateMode, am as MembershipPredicateOp, an as publishQuery, ao as publishCommand, D as DDBModel, ap as RetryPolicy, aq as Middleware } from './key-CWytoEaE.js';
+export { ar as CdcModelRegistry, as as CdcSubscribeHandlers, at as Change, au as Column, av as ColumnMap, aw as CondSlot, ax as CtxBase, ay as CtxModel, az as FilterInput, aA as GsiDefinitionMarker, aB as GsiOptions, aC as InlineSnapshotSpec, aD as Item, aE as KeyDefinitionMarker, aF as KeySegment, aG as KeySlot, aH as KeyStructure, M as ModelStatic, aI as MutateAuthoringOptions, aJ as ParamDescriptor, aK as ParamStructure, aL as PartialQueryKeyOf, aM as PersistCtx, aN as PersistOrigin, aO as QueryKeyOf, aP as QueryResult, aQ as RawCondition, aR as ReadOpCtx, aS as ReadOpKind, aT as ReadParams, aU as ReadRequestCtx, aV as ReadRequestKind, aW as RelationBuilder, aX as RelationSelect, aY as RelationSpec, aZ as RequestContext, a_ as SegmentSpec, d as SegmentedKey, a$ as SelectBuilder, b0 as SelectOf, b1 as UniqueQueryKeyOf, b2 as Updatable, b3 as WriteCtx, b4 as WriteInput, b5 as WriteKind, b6 as WriteMiddleware, b7 as cond, b8 as entityWrites, b9 as getEntityWrites, ba as gsi, bb as identity, bc as k, bd as key, be as mutate, bf as preview, bg as when } from './key-CWytoEaE.js';
 import * as _aws_sdk_client_dynamodb from '@aws-sdk/client-dynamodb';
 import { p as publishBehaviors } from './behaviors-DDltNivc.js';
 export { b as BehaviorComponentFns, a as BehaviorMethodSpec, B as BehaviorModelContract, P as PublishBehaviorsOptions, c as behaviorComponents, i as isBehaviorModelContract } from './behaviors-DDltNivc.js';
-import { M as ModelKind, F as FieldOptions, D as DynamoType, R as RelationOptions, A as AggregateOptions, a as AggregateValue } from './types-BnFsTZwl.js';
-export { a0 as LiteralParam, a1 as MapParam, a2 as NumberParam, a3 as Param, a4 as ParamKind, a5 as StringParam, a6 as param } from './types-CfxzTEFL.js';
+import { M as ModelKind, F as FieldOptions, D as DynamoType, R as RelationOptions, A as AggregateOptions, a as AggregateValue } from './types-nk5okD7d.js';
+export { a0 as LiteralParam, a1 as MapParam, a2 as NumberParam, a3 as Param, a4 as ParamKind, a5 as StringParam, a6 as param } from './types-CgXS-4Ox.js';
 import 'behavior-contracts';
 
 /**

package/dist/index.js

@@ -3,13 +3,13 @@ import {
   mutate,
   publishCommand,
   publishQuery
-} from "./chunk-XZTA4VJH.js";
+} from "./chunk-HLFNCKFV.js";
 import {
   entityWrites,
   getEntityWrites,
   identity,
   preview
-} from "./chunk-KOIJ4SNO.js";
+} from "./chunk-7OCXY4R6.js";
 import {
   when
 } from "./chunk-WOFRHRXY.js";
@@ -22,7 +22,7 @@ import {
   deriveContractEffect,
   gsi,
   param
-} from "./chunk-ZNU7OI5I.js";
+} from "./chunk-GWWRXIHF.js";
 import {
   TableMapping,
   k,

package/dist/internal/index.d.ts

@@ -1,8 +1,8 @@
-import { P as PreparedWriteOpSpec, a as PreparedPlanDocument } from '../prepared-artifact-BXkARxwO.js';
-export { b as PreparedBindSpec, c as PreparedPlanSpec, d as PreparedReadRouteSpec } from '../prepared-artifact-BXkARxwO.js';
-import { M as Manifest } from '../types-CfxzTEFL.js';
-import { M as ModelStatic, D as DDBModel, S as Slot, P as PreparedWriteExecOptions, C as CommandReturn, a as ParallelOpResult, b as PreparedBody, c as PreparedStatement } from '../key-Dne-a20Q.js';
-import '../types-BnFsTZwl.js';
+import { P as PreparedWriteOpSpec, a as PreparedPlanDocument } from '../prepared-artifact-CwH5ezFq.js';
+export { b as PreparedBindSpec, c as PreparedPlanSpec, d as PreparedReadRouteSpec } from '../prepared-artifact-CwH5ezFq.js';
+import { M as Manifest } from '../types-CgXS-4Ox.js';
+import { M as ModelStatic, D as DDBModel, S as Slot, P as PreparedWriteExecOptions, C as CommandReturn, a as ParallelOpResult, b as PreparedBody, c as PreparedStatement } from '../key-CWytoEaE.js';
+import '../types-nk5okD7d.js';
 import 'behavior-contracts';
 
 /**

package/dist/internal/index.js

@@ -2,15 +2,15 @@ import {
   PREPARED_FORMAT_VERSION,
   buildManifestEntity,
   entityFingerprint
-} from "../chunk-NWTEUWJD.js";
+} from "../chunk-PHXUFAY2.js";
 import {
   LOGICAL_EFFECT_CATEGORIES,
   PreparedReadStatement,
   executeLogicalParallelWrites,
   executeLogicalWriteOps,
   serializeEffectParams
-} from "../chunk-XZTA4VJH.js";
-import "../chunk-KOIJ4SNO.js";
+} from "../chunk-HLFNCKFV.js";
+import "../chunk-7OCXY4R6.js";
 import {
   MARKER_ROW_ENTITY,
   SPEC_VERSION_KEY_EXPR,
@@ -21,7 +21,7 @@ import {
   buildConditionExpression,
   execItemKeySignature,
   resolveConditionTree
-} from "../chunk-ZNU7OI5I.js";
+} from "../chunk-GWWRXIHF.js";
 import {
   TableMapping
 } from "../chunk-XTWXMOHD.js";

package/dist/{key-Dne-a20Q.d.ts → key-CWytoEaE.d.ts}

@@ -1,4 +1,4 @@
-import { a3 as Param, E as ExpressionSpec, a4 as ParamKind, T as TransactionSpec, Y as TransactionItemSpec } from './types-CfxzTEFL.js';
+import { a3 as Param, E as ExpressionSpec, a4 as ParamKind, T as TransactionSpec, Y as TransactionItemSpec } from './types-CgXS-4Ox.js';
 
 /**
  * CDC emulator types (issue #72). These types are **cdc-module-owned**; core
@@ -1653,6 +1653,13 @@ interface OperationDefinition<T extends DDBModel, Op extends OperationKind, K, S
     readonly select: S;
     /** The parameterized changes for `update`; `undefined` otherwise. */
     readonly changes: Ch;
+    /**
+     * The parameterized atomic-`ADD` record for a standalone `update` (issue #301):
+     * field name → a `param.number()` caller-delta leaf. Distinct from {@link changes}
+     * (a SET) — each entry serializes to `CommandSpec.add` (`ADD #field :delta`).
+     * `undefined` unless the command declared `add`.
+     */
+    readonly add?: Readonly<Record<string, unknown>>;
     /**
      * The declarative write condition for `put` / `update` / `delete`; `undefined`
      * when no condition is attached or for reads (issue #46).
@@ -2512,6 +2519,16 @@ interface MutationFragment {
     readonly intent: MutationIntent;
     readonly entity: EntityRef;
     readonly input: FragmentInput;
+    /**
+     * Atomic-**`ADD`** field binding on the self row (issue #301): model field name →
+     * a {@link MutationInputRef} (`$.field`, a `param.number()` caller delta). Distinct
+     * from {@link input} (a `SET`): the compiler ({@link
+     * import('../spec/mutation-command.js').compileFragment}) lowers each leaf onto the
+     * command spec's `add` record (an `ADD #field :delta`), so the runtime issues an
+     * atomic increment (no read, concurrency-safe). Absent when the fragment declares no
+     * `add`. Present only on an `update` fragment.
+     */
+    readonly add?: FragmentInput;
     readonly use?: EntityWritesDefinition;
     /**
      * The declarative write **condition** (gate) authored on the descriptor (issue
@@ -2581,6 +2598,16 @@ interface WriteDescriptor {
     readonly key: DescriptorBinding;
     /** The non-key field binding; optional (a `remove` writes no fields). */
     readonly input?: DescriptorBinding;
+    /**
+     * Optional atomic-**`ADD`** binding on the self row (issue #301) — `{ field: $.field }`
+     * whose leaves are `$.field` input refs bound from `param.number()` caller deltas.
+     * Distinct from `input` (a `SET`): an `add` field lowers to a `TransactionValueLeaf`
+     * on the compiled command spec's `add` record (an `ADD #field :delta`), NOT to a
+     * `changes` SET. Legal only on an `update` fragment. When present alongside a
+     * `condition`, the runtime applies the ADD unconditionally (two-stage: ADD+SET under
+     * the condition, fallback ADD-only on ConditionalCheckFailed).
+     */
+    readonly add?: DescriptorBinding;
     /**
      * Optional declarative write gate — the #114-A condition subset (issue #242,
      * Phase 2). Compiled, serialized, and evaluated at runtime; see the interface doc.
@@ -3038,6 +3065,13 @@ interface ContractMethodOp<Op extends OperationKind = OperationKind> {
     readonly select?: Readonly<Record<string, unknown>>;
     /** The changes structure for `update`; `undefined` otherwise. */
     readonly changes?: Readonly<Record<string, unknown>>;
+    /**
+     * The atomic-`ADD` structure for `update` (issue #301): model field name → a
+     * `param.number()` caller-delta leaf (a `{token}` template). Distinct from
+     * {@link changes} (a SET): each entry lowers to `ADD #field :delta`. Present only on
+     * a standalone `update` command that declared `add`; `undefined` otherwise.
+     */
+    readonly add?: Readonly<Record<string, unknown>>;
     /** The item structure for `put`; `undefined` otherwise. */
     readonly item?: Readonly<Record<string, unknown>>;
     /** The optional declarative write condition for writes. */
@@ -3679,6 +3713,25 @@ interface PublicWriteDescriptor {
     readonly upsert?: ModelRef;
     readonly key: Readonly<Record<string, unknown>>;
     readonly input?: Readonly<Record<string, unknown>>;
+    /**
+     * Atomic **`ADD`** deltas on the SELF row (issue #301) — `{ field: param.number() }`
+     * declaring an `ADD #field :delta` with a **caller-param** delta. Distinct from
+     * `input` (a `SET` that overwrites): `add` is an atomic server-side increment that
+     * needs no prior read and is concurrency-safe (the aggregate-tree `mark`'s
+     * `version++`). Legal only on an `update` intent, with each value a
+     * `param.number()`. An `add` field may NOT also appear in `input` (a field is either
+     * SET or ADD, not both) nor be a primary-key field (a key cannot be incremented).
+     *
+     * **Two-stage semantics**: when an `update` carries BOTH `add` and a `condition`, the
+     * `add` is UNCONDITIONAL (it must always apply — the mark's `version++` must always
+     * happen) while `input` (SET) is gated by `condition`. Because DynamoDB rejects the
+     * ENTIRE `UpdateItem` when the `ConditionExpression` fails, the RUNTIME performs a
+     * transparent two-stage: `ADD + SET` under the condition (1 write, the common path);
+     * on `ConditionalCheckFailedException`, a fallback `ADD`-only write (no SET, no
+     * condition — the `version` still increments). read=0, retry=0. The author does NOT
+     * write the fallback — it is derived from `add` + `condition` presence.
+     */
+    readonly add?: Readonly<Record<string, unknown>>;
     readonly condition?: Readonly<Record<string, unknown>> | RawCondition<any, any>;
     readonly result?: {
         readonly select?: Readonly<Record<string, boolean>>;

package/dist/linter/index.d.ts

@@ -1,8 +1,8 @@
-import { L as Linter, a as LintRule } from '../linter-Cr1Hnw7n.js';
-export { b as LintResult } from '../linter-Cr1Hnw7n.js';
-import '../types-BnFsTZwl.js';
-import '../key-Dne-a20Q.js';
-import '../types-CfxzTEFL.js';
+import { L as Linter, a as LintRule } from '../linter-jEwmZotm.js';
+export { b as LintResult } from '../linter-jEwmZotm.js';
+import '../types-nk5okD7d.js';
+import '../key-CWytoEaE.js';
+import '../types-CgXS-4Ox.js';
 import 'behavior-contracts';
 
 /**

package/dist/{linter-Cr1Hnw7n.d.ts → linter-jEwmZotm.d.ts}

@@ -1,4 +1,4 @@
-import { E as EntityMetadata } from './types-BnFsTZwl.js';
+import { E as EntityMetadata } from './types-nk5okD7d.js';
 
 declare class MetadataRegistry {
     private static store;

package/dist/{prepared-artifact-BXkARxwO.d.ts → prepared-artifact-CwH5ezFq.d.ts}

@@ -1,6 +1,6 @@
-import { E as EntityMetadata } from './types-BnFsTZwl.js';
-import { C as ContractSpec, Q as QuerySpec, a as CommandSpec, T as TransactionSpec, b as ContextSpec, S as SPEC_VERSION_KEY_EXPR, P as ParamSpec } from './types-CfxzTEFL.js';
-import { Q as QueryModelContract, k as QueryMethodSpec, l as CommandModelContract, m as CommandMethodSpec } from './key-Dne-a20Q.js';
+import { E as EntityMetadata } from './types-nk5okD7d.js';
+import { C as ContractSpec, Q as QuerySpec, a as CommandSpec, T as TransactionSpec, b as ContextSpec, S as SPEC_VERSION_KEY_EXPR, P as ParamSpec } from './types-CgXS-4Ox.js';
+import { Q as QueryModelContract, k as QueryMethodSpec, l as CommandModelContract, m as CommandMethodSpec } from './key-CWytoEaE.js';
 
 /**
  * Contract-layer serialization (issue #59, CQRS Contract layer, Epic #57;

package/dist/spec/index.d.ts

@@ -1,14 +1,14 @@
-import { $ as AnyOperationDefinition, a0 as TransactionDefinition, b as PreparedBody } from '../key-Dne-a20Q.js';
-export { a1 as CompiledFragment, a2 as CompiledMutationPlan, a3 as DerivedConditionCheck, a4 as DerivedEdgeWrite, a5 as DerivedIdempotencyGuard, a6 as DerivedMaintainOutbox, a7 as DerivedMaintainWrite, a8 as DerivedOutboxEvent, a9 as DerivedUniqueGuard, aa as DerivedUpdate, ab as EntityRefResolver, ac as MAX_TRANSACT_COMPOSE_ITEMS, ad as assertNoCrossFragmentMaintainCollision, ae as compileFragment, af as compileMutationPlan, ag as compileSingleFragmentPlan, ah as resetMaintenanceGraphCache, ai as resolveLifecycle, aj as resolveMaintainers } from '../key-Dne-a20Q.js';
-import { M as MetadataRegistry } from '../linter-Cr1Hnw7n.js';
+import { $ as AnyOperationDefinition, a0 as TransactionDefinition, b as PreparedBody } from '../key-CWytoEaE.js';
+export { a1 as CompiledFragment, a2 as CompiledMutationPlan, a3 as DerivedConditionCheck, a4 as DerivedEdgeWrite, a5 as DerivedIdempotencyGuard, a6 as DerivedMaintainOutbox, a7 as DerivedMaintainWrite, a8 as DerivedOutboxEvent, a9 as DerivedUniqueGuard, aa as DerivedUpdate, ab as EntityRefResolver, ac as MAX_TRANSACT_COMPOSE_ITEMS, ad as assertNoCrossFragmentMaintainCollision, ae as compileFragment, af as compileMutationPlan, ag as compileSingleFragmentPlan, ah as resetMaintenanceGraphCache, ai as resolveLifecycle, aj as resolveMaintainers } from '../key-CWytoEaE.js';
+import { M as MetadataRegistry } from '../linter-jEwmZotm.js';
 import { B as BehaviorModelContract } from '../behaviors-DDltNivc.js';
 export { a as BehaviorMethodSpec } from '../behaviors-DDltNivc.js';
-import { C as ContractMap, e as ContextOwnershipMap, c as PreparedPlanSpec, a as PreparedPlanDocument } from '../prepared-artifact-BXkARxwO.js';
-export { A as AnyModelContract, B as BuiltContracts, f as ContextOwnership, g as PREPARED_FORMAT_VERSION, h as PreparedBindMap, b as PreparedBindSpec, d as PreparedReadRouteSpec, P as PreparedWriteOpSpec, i as buildContexts, j as buildContracts, k as canonicalJson, l as entityFingerprint, p as planFingerprint } from '../prepared-artifact-BXkARxwO.js';
-import { O as OperationsDocument, Q as QuerySpec, M as Manifest, T as TransactionSpec, C as ContractSpec, B as BridgeBundle, c as ConditionSpec, E as ExpressionSpec, a as CommandSpec, d as SpecVersion } from '../types-CfxzTEFL.js';
-export { e as CommandContractMethodSpec, f as CommandResolutionTarget, g as ComposeSpec, h as CompositionPlanSpec, b as ContextSpec, i as ContractCardinality, j as ContractCommandResult, k as ContractInputArity, l as ContractKeySpec, m as ContractKind, n as ContractResolution, o as EXPR_VERSION, p as ExecutionPlanSpec, q as ExpressionArrNode, r as ExpressionFloatNode, s as ExpressionIntNode, t as ExpressionNode, u as ExpressionObjNode, v as ExpressionOpNode, w as ExpressionOperator, x as ExpressionRefNode, y as ExpressionRefOptNode, z as ExpressionScalar, F as FilterSpec, A as ManifestEntity, D as ManifestField, G as ManifestFieldType, H as ManifestGsi, I as ManifestKey, J as ManifestRelation, K as ManifestTable, L as OperationSpec, P as ParamSpec, N as QueryContractMethodSpec, R as RangeConditionSpec, U as ReadOperationType, V as SPEC_VERSION, S as SPEC_VERSION_KEY_EXPR, W as SPEC_VERSION_SCP, X as SPEC_VERSION_SUPPORTED, Y as TransactionItemSpec, Z as TransactionItemType, _ as WhenSpec, $ as WriteOperationType } from '../types-CfxzTEFL.js';
+import { C as ContractMap, e as ContextOwnershipMap, c as PreparedPlanSpec, a as PreparedPlanDocument } from '../prepared-artifact-CwH5ezFq.js';
+export { A as AnyModelContract, B as BuiltContracts, f as ContextOwnership, g as PREPARED_FORMAT_VERSION, h as PreparedBindMap, b as PreparedBindSpec, d as PreparedReadRouteSpec, P as PreparedWriteOpSpec, i as buildContexts, j as buildContracts, k as canonicalJson, l as entityFingerprint, p as planFingerprint } from '../prepared-artifact-CwH5ezFq.js';
+import { O as OperationsDocument, Q as QuerySpec, M as Manifest, T as TransactionSpec, C as ContractSpec, B as BridgeBundle, c as ConditionSpec, E as ExpressionSpec, a as CommandSpec, d as SpecVersion } from '../types-CgXS-4Ox.js';
+export { e as CommandContractMethodSpec, f as CommandResolutionTarget, g as ComposeSpec, h as CompositionPlanSpec, b as ContextSpec, i as ContractCardinality, j as ContractCommandResult, k as ContractInputArity, l as ContractKeySpec, m as ContractKind, n as ContractResolution, o as EXPR_VERSION, p as ExecutionPlanSpec, q as ExpressionArrNode, r as ExpressionFloatNode, s as ExpressionIntNode, t as ExpressionNode, u as ExpressionObjNode, v as ExpressionOpNode, w as ExpressionOperator, x as ExpressionRefNode, y as ExpressionRefOptNode, z as ExpressionScalar, F as FilterSpec, A as ManifestEntity, D as ManifestField, G as ManifestFieldType, H as ManifestGsi, I as ManifestKey, J as ManifestRelation, K as ManifestTable, L as OperationSpec, P as ParamSpec, N as QueryContractMethodSpec, R as RangeConditionSpec, U as ReadOperationType, V as SPEC_VERSION, S as SPEC_VERSION_KEY_EXPR, W as SPEC_VERSION_SCP, X as SPEC_VERSION_SUPPORTED, Y as TransactionItemSpec, Z as TransactionItemType, _ as WhenSpec, $ as WriteOperationType } from '../types-CgXS-4Ox.js';
 import { Component, ComponentGraphIR } from 'behavior-contracts';
-import '../types-BnFsTZwl.js';
+import '../types-nk5okD7d.js';
 
 /**
  * Static parameterized operation-spec generation (issue #42, Phase 0b).

package/dist/spec/index.js

@@ -14,14 +14,14 @@ import {
   collectContractN1Violations,
   compilePreparedPlan,
   portableIrDocument
-} from "../chunk-SSVG6NQK.js";
+} from "../chunk-MBJ4JVRM.js";
 import {
   PREPARED_FORMAT_VERSION,
   buildManifest,
   canonicalJson,
   entityFingerprint,
   planFingerprint
-} from "../chunk-NWTEUWJD.js";
+} from "../chunk-PHXUFAY2.js";
 import {
   MAX_TRANSACT_COMPOSE_ITEMS,
   assertBundleSerializable,
@@ -36,8 +36,8 @@ import {
   resetMaintenanceGraphCache,
   resolveLifecycle,
   resolveMaintainers
-} from "../chunk-XZTA4VJH.js";
-import "../chunk-KOIJ4SNO.js";
+} from "../chunk-HLFNCKFV.js";
+import "../chunk-7OCXY4R6.js";
 import {
   EXPR_VERSION,
   SPEC_VERSION,
@@ -47,7 +47,7 @@ import {
   canonicalizeExpressionSpec,
   operationsSpecVersion
 } from "../chunk-WOFRHRXY.js";
-import "../chunk-ZNU7OI5I.js";
+import "../chunk-GWWRXIHF.js";
 import "../chunk-XTWXMOHD.js";
 export {
   EXPR_VERSION,

package/dist/testing/index.d.ts

@@ -1,5 +1,5 @@
-import { n as Executor, o as DynamoDBOperation, R as ReadExecOptions, p as ExecutorResult, B as BatchGetExecInput, q as PutInput, W as WriteExecOptions, r as WriteResult, U as UpdateInput, s as DeleteInput, t as BatchWriteExecItem, u as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, D as DDBModel, v as ChangeEvent } from '../key-Dne-a20Q.js';
-import '../types-CfxzTEFL.js';
+import { n as Executor, o as DynamoDBOperation, R as ReadExecOptions, p as ExecutorResult, B as BatchGetExecInput, q as PutInput, W as WriteExecOptions, r as WriteResult, U as UpdateInput, s as DeleteInput, t as BatchWriteExecItem, u as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, D as DDBModel, v as ChangeEvent } from '../key-CWytoEaE.js';
+import '../types-CgXS-4Ox.js';
 import 'behavior-contracts';
 
 /**

package/dist/testing/index.js

@@ -1,12 +1,12 @@
 import {
   createCdcEmulator
-} from "../chunk-YGQ2NO6J.js";
-import "../chunk-KOIJ4SNO.js";
+} from "../chunk-VECUS35D.js";
+import "../chunk-7OCXY4R6.js";
 import {
   ClientManager,
   MetadataRegistry,
   resolveModelClass
-} from "../chunk-ZNU7OI5I.js";
+} from "../chunk-GWWRXIHF.js";
 import {
   TableMapping
 } from "../chunk-XTWXMOHD.js";
@@ -470,8 +470,9 @@ function removePath(target, segments) {
   delete cursor[segments[segments.length - 1]];
 }
 function applyUpdateExpression(item, expression, clauses) {
-  const setMatch = /SET\s+(.*?)(?:\s+REMOVE\s+|$)/.exec(expression);
-  const removeMatch = /REMOVE\s+(.*)$/.exec(expression);
+  const setMatch = /SET\s+(.*?)(?:\s+REMOVE\s+|\s+ADD\s+|$)/.exec(expression);
+  const removeMatch = /REMOVE\s+(.*?)(?:\s+ADD\s+|$)/.exec(expression);
+  const addMatch = /ADD\s+(.*)$/.exec(expression);
   if (setMatch && setMatch[1].trim().length > 0) {
     const assignments = splitTopLevel(setMatch[1]);
     for (const assignment of assignments) {
@@ -496,6 +497,32 @@ function applyUpdateExpression(item, expression, clauses) {
       removePath(item, resolvePath(trimmed, clauses.names));
     }
   }
+  if (addMatch && addMatch[1].trim().length > 0) {
+    const clausesList = splitTopLevel(addMatch[1]);
+    for (const clause of clausesList) {
+      const trimmed = clause.trim();
+      if (trimmed.length === 0) continue;
+      const sp = trimmed.indexOf(" ");
+      if (sp < 0) {
+        throw new Error(`memory update: malformed ADD clause '${trimmed}'`);
+      }
+      const pathExpr = trimmed.slice(0, sp).trim();
+      const valueAlias = trimmed.slice(sp + 1).trim();
+      if (!(valueAlias in clauses.values)) {
+        throw new Error(`memory update: unbound value alias '${valueAlias}'`);
+      }
+      const delta = clauses.values[valueAlias];
+      if (typeof delta !== "number") {
+        throw new Error(
+          `memory update: ADD delta for '${pathExpr}' is not numeric (${typeof delta})`
+        );
+      }
+      const segments = resolvePath(pathExpr, clauses.names);
+      const current = segments.length === 1 ? item[segments[0]] : void 0;
+      const base = typeof current === "number" ? current : 0;
+      setPath(item, segments, base + delta);
+    }
+  }
 }
 function splitTopLevel(clause) {
   const parts = [];

package/dist/transform/index.d.ts

@@ -1,5 +1,5 @@
 import ts from 'typescript';
-import { E as ExpressionSpec } from '../types-CfxzTEFL.js';
+import { E as ExpressionSpec } from '../types-CgXS-4Ox.js';
 import 'behavior-contracts';
 
 /**

package/dist/transform/index.js

@@ -3,7 +3,7 @@ import {
   SCP_LOWERED_MARKER,
   canonicalizeExpressionSpec
 } from "../chunk-WOFRHRXY.js";
-import "../chunk-ZNU7OI5I.js";
+import "../chunk-GWWRXIHF.js";
 import "../chunk-XTWXMOHD.js";
 
 // src/transform/prepared-transform.ts

package/dist/{types-CfxzTEFL.d.ts → types-CgXS-4Ox.d.ts}

@@ -721,7 +721,9 @@ type WriteOperationType = 'PutItem' | 'UpdateItem' | 'DeleteItem';
  * - `{ kind: 'attributeNotExists'; field }` → `attribute_not_exists(<field>)` — the
  *   named attribute must be absent (field-level uniqueness / first-write guard).
  * - `{ kind: 'equals'; fields }` → `#f = :v AND …` field equality (each value a
- *   `{param}` / literal template).
+ *   `{param}` string template or a typed literal — a `number` / `boolean` literal
+ *   is carried verbatim so it compares as `N` / `BOOL`, not a stringified `S`,
+ *   issue #299).
  * - `{ kind: 'expr'; declarative }` → the full declarative operator tree (issue
  *   #114-A): comparison (`gt`/`ge`/`lt`/`le`/`ne`), `between`, `in`,
  *   `begins_with`/`contains`/`notContains`, `attributeType`, and the logical
@@ -743,7 +745,7 @@ type ConditionSpec = {
     readonly field: string;
 } | {
     readonly kind: 'equals';
-    readonly fields: Readonly<Record<string, string>>;
+    readonly fields: Readonly<Record<string, TransactionValueLeaf>>;
 } | {
     readonly kind: 'expr';
     readonly declarative: unknown;
@@ -792,10 +794,33 @@ interface CommandSpec {
      * Absent for `PutItem` (the whole item is built from `item`).
      */
     readonly keyCondition?: Readonly<Record<string, string>>;
-    /** The full item template for `PutItem` (field name → template / literal). */
-    readonly item?: Readonly<Record<string, string>>;
-    /** Field-level changes for `UpdateItem` (field name → template / literal). */
-    readonly changes?: Readonly<Record<string, string>>;
+    /**
+     * The full item template for `PutItem` (field name → template / typed literal).
+     * A string value is a template ({@link TransactionValueLeaf}); a `number` /
+     * `boolean` is a typed literal carried verbatim so it lands as `N` / `BOOL`
+     * rather than a stringified `S` (issue #299, mirroring the transaction #245).
+     */
+    readonly item?: Readonly<Record<string, TransactionValueLeaf>>;
+    /**
+     * Field-level changes for `UpdateItem` (field name → template / typed literal).
+     * A string value is a template; a `number` / `boolean` is a typed literal
+     * carried verbatim (issue #299).
+     */
+    readonly changes?: Readonly<Record<string, TransactionValueLeaf>>;
+    /**
+     * Atomic-`ADD` deltas for a standalone `UpdateItem` (issue #301): field name →
+     * template / typed literal. Distinct from {@link changes} (a SET): each entry emits
+     * `ADD #field :delta` — an atomic, read-free, concurrency-safe increment (the
+     * aggregate-tree `mark`'s `version++`). The delta rides as a `{token}` template
+     * resolved from a caller `param.number()`. When present together with
+     * {@link condition}, the ADD is UNCONDITIONAL and the runtime executes a transparent
+     * TWO-STAGE write: `ADD + SET` under the condition (1 write); on
+     * `ConditionalCheckFailedException`, a fallback `ADD`-only write (no SET, no
+     * condition — the counter still increments). read=0, retry=0. Absent unless the
+     * command declared `add`, so a command with no `add` serializes byte-identically to
+     * the pre-#301 spec.
+     */
+    readonly add?: Readonly<Record<string, TransactionValueLeaf>>;
     /** Optional write condition (subset). */
     readonly condition?: ConditionSpec;
     /**
@@ -1023,8 +1048,12 @@ interface MaintainItemSpec {
 interface MaintainCounterSpec {
     /** The target attribute the counter increments (e.g. `postCount`). */
     readonly attribute: string;
-    /** The signed `ADD` delta as a numeric template string (`"1"` / `"-1"`). */
-    readonly delta: string;
+    /**
+     * The signed `ADD` delta. A compile-time constant delta is carried as a typed
+     * `number` (`1` / `-1`) so it marshals as `N` (issue #299); a `{param}` numeric
+     * template rides as a string. (Pre-#299 a constant was stringified to `"1"`.)
+     */
+    readonly delta: TransactionValueLeaf;
 }
 /** A declarative transaction definition's full execution spec. */
 interface TransactionSpec {

package/dist/{types-BnFsTZwl.d.ts → types-nk5okD7d.d.ts}

@@ -1,4 +1,4 @@
-import { d as SegmentedKey, e as ProjectionTransform, f as MaintainEvent, g as ProjectionMap, h as MaintainConsistency, i as MaintainUpdateMode, E as EffectPath, j as MembershipPredicate } from './key-Dne-a20Q.js';
+import { d as SegmentedKey, e as ProjectionTransform, f as MaintainEvent, g as ProjectionMap, h as MaintainConsistency, i as MaintainUpdateMode, E as EffectPath, j as MembershipPredicate } from './key-CWytoEaE.js';
 
 type DynamoType = 'S' | 'N' | 'BOOL' | 'B' | 'SS' | 'NS' | 'L' | 'M';
 interface FieldOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphddb",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Graph data modeling on DynamoDB with adjacency list pattern",
   "type": "module",
   "main": "dist/index.js",