graphddb 0.8.1 → 0.9.1

package/dist/index.d.ts

@@ -1,8 +1,11 @@
-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-DZtjAQDh.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-DZtjAQDh.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 { M as ModelKind, F as FieldOptions, D as DynamoType, R as RelationOptions, A as AggregateOptions, a as AggregateValue } from './types-DW__-Icc.js';
-export { $ as LiteralParam, a0 as NumberParam, a1 as Param, a2 as ParamKind, a3 as StringParam, a4 as param } from './types-2PMXEn5x.js';
+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-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';
 
 /**
  * Query options with conditional `consistentRead` availability.
@@ -196,6 +199,128 @@ declare const map: FieldDecorator<Record<string, unknown>>;
 
 declare function embedded(modelFactory: () => new (...args: unknown[]) => unknown): (_value: undefined, context: ClassFieldDecoratorContext) => void;
 
+/**
+ * Field groups — reusable, composable field sets for models (issue #295, part B).
+ *
+ * ## Why composition, not inheritance
+ *
+ * The metadata pipeline is drain-based: TC39 field decorators push
+ * {@link FieldMetadata} into a module-level pending collector, and the topmost
+ * `@model` class decorator drains it (`collector.ts`). A **decorated shared base
+ * class** breaks that contract — the base's field decorators fire ONCE (at base
+ * class definition) and sit pending until the NEXT `@model` drains them, so the
+ * first subclass absorbs the base's fields and every later subclass silently
+ * loses them (drain-order dependence; the issue-#295 report). Real inheritance
+ * support would require re-architecting the collector around prototype-chain
+ * walks. A **field group** achieves the reuse the issue wants ("generic meta
+ * columns shared by every domain model") with the SAME mechanism the codebase
+ * already uses for stacked class-level declarations (`@maintainedFrom`,
+ * `@cdcProjected`): a class decorator that pushes into the pending collector
+ * BEFORE `@model` drains — per-class, so no drain-order hazard exists.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * // Shared, generic meta columns — defined ONCE, reused by every domain model.
+ * export const TreeMeta = defineFieldGroup(($) => ({
+ *   part: $.string(),
+ *   child: $.string(),
+ *   scope: $.string(),
+ *   computeVersion: $.number(),
+ *   computedAt: $.number(),
+ *   minPendingAt: $.number(),
+ * }));
+ *
+ * // A domain model composes the group with its own typed map value (issue #295):
+ * @model({ table: TABLE })
+ * @withFields(TreeMeta)
+ * export class AvgTreeNodeModel extends DDBModel {
+ *   static readonly keys = key<{ part: string; child: string }>((c) => ({
+ *     pk: k`TREE#${c.part}`,
+ *     sk: k`${c.child}`,
+ *   }));
+ *   @map value!: AvgValue; // the domain-specific value class, one M attribute
+ * }
+ * // TypeScript-side property typing via declaration merging (one line):
+ * export interface AvgTreeNodeModel extends FieldsOf<typeof TreeMeta> {}
+ * ```
+ *
+ * Group fields are ordinary {@link FieldMetadata}: they participate in keys
+ * (`key<{part, child}>` references them by name), GSIs, params-kind recovery
+ * (a `param` bound into a group `$.number()` field serializes as `'number'`),
+ * hydration, and codegen exactly as body-declared fields do.
+ */
+
+/** Brand tag carrying the TS value type a group field represents. */
+declare const GROUP_FIELD_BRAND: unique symbol;
+/**
+ * One field definition inside a {@link FieldGroup}: the same storage facts a
+ * semantic field decorator records (`dynamoType` + optional `options` /
+ * `literals`), plus — purely at the type level — the represented value type `T`
+ * (surfaced through {@link FieldsOf}).
+ */
+interface GroupFieldDef<out T> {
+    /** @internal Type brand carrying the represented value type. */
+    readonly [GROUP_FIELD_BRAND]: T;
+    readonly dynamoType: DynamoType;
+    readonly options?: FieldOptions;
+    readonly literals?: readonly string[];
+}
+/** The field-shape record a {@link defineFieldGroup} builder returns. */
+type FieldGroupShape = Record<string, GroupFieldDef<unknown>>;
+/** A reusable, named set of field definitions (issue #295 part B). */
+interface FieldGroup<S extends FieldGroupShape = FieldGroupShape> {
+    readonly __isFieldGroup: true;
+    readonly fields: S;
+}
+/**
+ * The TypeScript property types a {@link FieldGroup} contributes — merge them
+ * into the model class with one declaration-merging line:
+ * `export interface MyModel extends FieldsOf<typeof MyGroup> {}`.
+ */
+type FieldsOf<G extends FieldGroup> = {
+    [K in keyof G['fields']]: G['fields'][K] extends GroupFieldDef<infer T> ? T : never;
+};
+/**
+ * The field factories a {@link defineFieldGroup} builder receives — one per
+ * semantic field decorator, recording the same storage facts (`@string` → `'S'`,
+ * `@datetime` → `'S'` + `format`, `@literal` → `'S'` + the literal set, …).
+ */
+interface GroupFieldFactories {
+    string(options?: FieldOptions): GroupFieldDef<string>;
+    number(options?: FieldOptions): GroupFieldDef<number>;
+    boolean(options?: FieldOptions): GroupFieldDef<boolean>;
+    datetime(options?: FieldOptions): GroupFieldDef<Date>;
+    binary(options?: FieldOptions): GroupFieldDef<Uint8Array>;
+    stringSet(options?: FieldOptions): GroupFieldDef<Set<string>>;
+    numberSet(options?: FieldOptions): GroupFieldDef<Set<number>>;
+    list(options?: FieldOptions): GroupFieldDef<unknown[]>;
+    /** A free-form map field (one DynamoDB `M` attribute). `T` types the TS surface. */
+    map<T extends Record<string, unknown> = Record<string, unknown>>(options?: FieldOptions): GroupFieldDef<T>;
+    /** A closed string-literal-union field (the `@literal(...)` counterpart). */
+    literal<const L extends string>(...values: readonly [L, ...L[]]): GroupFieldDef<L>;
+}
+/**
+ * Define a reusable field group. The builder receives the field factories and
+ * returns the `{ fieldName: $.<type>() }` shape; the group is a plain immutable
+ * value (no collector interaction happens here — fields are contributed to a
+ * model only when `@withFields(group)` runs on that class).
+ */
+declare function defineFieldGroup<const S extends FieldGroupShape>(build: (f: GroupFieldFactories) => S): FieldGroup<S>;
+/**
+ * `@withFields(...groups)` — contribute each group's fields to the decorated
+ * model class. Stacked BELOW `@model` (which must stay topmost): TC39 class
+ * decorators apply bottom-up, so `@withFields` pushes into the pending collector
+ * and the `@model` drain picks the group fields up together with the class's own
+ * decorated fields — the exact `@maintainedFrom` / `@cdcProjected` mechanism.
+ *
+ * Duplicate field names are rejected LOUDLY: a group field colliding with a
+ * body-declared field (already pending at this point — field decorators run
+ * before any class decorator) or with an earlier group would register two
+ * metadata entries for one property and silently shadow one of them.
+ */
+declare function withFields(...groups: readonly FieldGroup[]): (_target: Function, context: ClassDecoratorContext) => void;
+
 /**
  * Symbolic `(self, source) =>` evaluation for the `@maintainedFrom` view authoring
  * and the versioned relation `pattern` union (issue #152).
@@ -668,6 +793,7 @@ declare function cdcProjected(): (_target: Function, _context: ClassDecoratorCon
 declare const graphddb: {
     readonly publishQuery: typeof publishQuery;
     readonly publishCommand: typeof publishCommand;
+    readonly publishBehaviors: typeof publishBehaviors;
     readonly query: typeof DDBModel.query;
     readonly mutate: typeof DDBModel.mutate;
     readonly prepare: typeof DDBModel.prepare;
@@ -682,4 +808,4 @@ declare const graphddb: {
     };
 };
 
-export { DDBModel, type HasManyVersionedCallback, type HasManyVersionedOptions, type HasOneVersionedCallback, type HasOneVersionedOptions, type ListOptions, type MaintainedFromCallback, type MaintainedFromOptions, Middleware, type ModelOptions, PrimaryKeyOf, type ProjectionValue, type QueryOptions, type RefsOptions, SelectableOf, type SelfProxy, type SelfRef, type SourceProxy, type SourceRef, type VersionedHistoryOptions, type VersionedLatestOptions, aggregate, belongsTo, binary, boolean, cdcProjected, count, datetime, embedded, field, graphddb, hasMany, hasOne, list, literal, maintainedFrom, map, max, model, number, numberSet, refs, string, stringSet, ttl, whenMember };
+export { DDBModel, type FieldGroup, type FieldGroupShape, type FieldsOf, type GroupFieldDef, type GroupFieldFactories, type HasManyVersionedCallback, type HasManyVersionedOptions, type HasOneVersionedCallback, type HasOneVersionedOptions, type ListOptions, type MaintainedFromCallback, type MaintainedFromOptions, Middleware, type ModelOptions, PrimaryKeyOf, type ProjectionValue, type QueryOptions, type RefsOptions, SelectableOf, type SelfProxy, type SelfRef, type SourceProxy, type SourceRef, type VersionedHistoryOptions, type VersionedLatestOptions, aggregate, belongsTo, binary, boolean, cdcProjected, count, datetime, defineFieldGroup, embedded, field, graphddb, hasMany, hasOne, list, literal, maintainedFrom, map, max, model, number, numberSet, refs, string, stringSet, ttl, whenMember, withFields };

package/dist/index.js

@@ -3,29 +3,70 @@ import {
   mutate,
   publishCommand,
   publishQuery
-} from "./chunk-T44OB5GU.js";
+} from "./chunk-HLFNCKFV.js";
 import {
   entityWrites,
   getEntityWrites,
   identity,
   preview
-} from "./chunk-HNY2EJPV.js";
+} from "./chunk-7OCXY4R6.js";
 import {
   when
-} from "./chunk-L4QRCHRQ.js";
+} from "./chunk-WOFRHRXY.js";
 import {
   ClientManager,
+  GRAPHDDB_CATALOG,
   MetadataRegistry,
+  assertComponentsInCatalog,
   cond,
+  deriveContractEffect,
   gsi,
   param
-} from "./chunk-L2NEDS7U.js";
+} from "./chunk-GWWRXIHF.js";
 import {
   TableMapping,
   k,
   key
 } from "./chunk-XTWXMOHD.js";
 
+// src/define/behaviors.ts
+import {
+  catalogComponents,
+  compileBehaviors
+} from "behavior-contracts";
+var boundComponents;
+function behaviorComponents() {
+  if (boundComponents === void 0) {
+    boundComponents = catalogComponents(GRAPHDDB_CATALOG);
+  }
+  return boundComponents;
+}
+function publishBehaviors(cls, options = {}) {
+  const ir = compileBehaviors(cls, {
+    ...options.inputPorts !== void 0 ? { inputPorts: options.inputPorts } : {},
+    ...options.concurrency !== void 0 ? { concurrency: options.concurrency } : {}
+  });
+  assertComponentsInCatalog(ir.components);
+  const methods = {};
+  for (const component of ir.components) {
+    methods[component.name] = {
+      name: component.name,
+      effect: deriveContractEffect(component),
+      component
+    };
+  }
+  return Object.freeze({
+    kind: "behaviors",
+    className: cls.name ?? "<anonymous>",
+    ir,
+    components: ir.components,
+    methods: Object.freeze(methods)
+  });
+}
+function isBehaviorModelContract(value) {
+  return typeof value === "object" && value !== null && value.kind === "behaviors" && Array.isArray(value.components);
+}
+
 // src/config/index.ts
 var config = {
   /**
@@ -123,6 +164,9 @@ function drainFields() {
   pendingFields = [];
   return result;
 }
+function peekPendingFieldNames() {
+  return pendingFields.map((f) => f.propertyName);
+}
 function drainEmbedded() {
   const result = pendingEmbedded;
   pendingEmbedded = [];
@@ -267,6 +311,71 @@ function embedded(modelFactory) {
   };
 }
 
+// src/decorators/field-group.ts
+function def(dynamoType, options, literals) {
+  const d = { dynamoType };
+  if (options !== void 0 && Object.keys(options).length > 0) d.options = options;
+  if (literals !== void 0) d.literals = literals;
+  return d;
+}
+var factories = {
+  string: (options) => def("S", options),
+  number: (options) => def("N", options),
+  boolean: (options) => def("BOOL", options),
+  datetime: (options) => def("S", { format: "datetime", ...options }),
+  binary: (options) => def("B", options),
+  stringSet: (options) => def("SS", options),
+  numberSet: (options) => def("NS", options),
+  list: (options) => def("L", options),
+  map: (options) => def("M", options),
+  literal: (...values) => {
+    if (values.length === 0) {
+      throw new Error(
+        "defineFieldGroup: $.literal(...) requires at least one allowed value."
+      );
+    }
+    return def("S", void 0, [...values]);
+  }
+};
+function defineFieldGroup(build) {
+  const fields = build(factories);
+  if (Object.keys(fields).length === 0) {
+    throw new Error("defineFieldGroup: a field group must declare at least one field.");
+  }
+  return { __isFieldGroup: true, fields };
+}
+function withFields(...groups) {
+  if (groups.length === 0) {
+    throw new Error("@withFields requires at least one field group.");
+  }
+  for (const g of groups) {
+    if (g === null || typeof g !== "object" || g.__isFieldGroup !== true) {
+      throw new Error(
+        "@withFields: every argument must be a `defineFieldGroup(...)` result."
+      );
+    }
+  }
+  return function(_target, context) {
+    const seen = new Set(peekPendingFieldNames());
+    for (const group of groups) {
+      for (const [propertyName, d] of Object.entries(group.fields)) {
+        if (seen.has(propertyName)) {
+          throw new Error(
+            `@withFields on '${String(context.name)}': field '${propertyName}' is declared more than once (a group field collides with a body-declared field or another group). Each property may be declared exactly once.`
+          );
+        }
+        seen.add(propertyName);
+        collectField({
+          propertyName,
+          dynamoType: d.dynamoType,
+          ...d.options !== void 0 ? { options: d.options } : {},
+          ...d.literals !== void 0 ? { literals: d.literals } : {}
+        });
+      }
+    }
+  };
+}
+
 // src/decorators/maintained-symbolic.ts
 var SOURCE_REF = /* @__PURE__ */ Symbol("graphddb:maintainedSourceRef");
 var SELF_REF = /* @__PURE__ */ Symbol("graphddb:maintainedSelfRef");
@@ -620,6 +729,9 @@ function cdcProjected() {
 var graphddb = {
   publishQuery,
   publishCommand,
+  // #297 SP3: the shared-authoring verb (SemanticBehavior class → behavior
+  // contract; effect derived from the graph, components registered additively).
+  publishBehaviors,
   get query() {
     return DDBModel.query;
   },
@@ -647,6 +759,7 @@ var graphddb = {
 export {
   DDBModel,
   aggregate,
+  behaviorComponents,
   belongsTo,
   binary,
   boolean,
@@ -654,6 +767,7 @@ export {
   cond,
   count,
   datetime,
+  defineFieldGroup,
   embedded,
   entityWrites,
   field,
@@ -663,6 +777,7 @@ export {
   hasMany,
   hasOne,
   identity,
+  isBehaviorModelContract,
   k,
   key,
   list,
@@ -681,5 +796,6 @@ export {
   stringSet,
   ttl,
   when,
-  whenMember
+  whenMember,
+  withFields
 };

package/dist/internal/index.d.ts

@@ -1,8 +1,9 @@
-import { P as PreparedWriteOpSpec, a as PreparedPlanDocument } from '../prepared-artifact-HFealr1q.js';
-export { b as PreparedBindSpec, c as PreparedPlanSpec, d as PreparedReadRouteSpec } from '../prepared-artifact-HFealr1q.js';
-import { M as Manifest } from '../types-2PMXEn5x.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-DZtjAQDh.js';
-import '../types-DW__-Icc.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';
 
 /**
  * Static prepared-plan LOADER (issue #208) — the runtime half of the AOT

package/dist/internal/index.js

@@ -2,26 +2,26 @@ import {
   PREPARED_FORMAT_VERSION,
   buildManifestEntity,
   entityFingerprint
-} from "../chunk-S2NI4PBW.js";
+} from "../chunk-PHXUFAY2.js";
 import {
   LOGICAL_EFFECT_CATEGORIES,
   PreparedReadStatement,
   executeLogicalParallelWrites,
   executeLogicalWriteOps,
   serializeEffectParams
-} from "../chunk-T44OB5GU.js";
-import "../chunk-HNY2EJPV.js";
+} from "../chunk-HLFNCKFV.js";
+import "../chunk-7OCXY4R6.js";
 import {
   MARKER_ROW_ENTITY,
-  SPEC_VERSION,
+  SPEC_VERSION_KEY_EXPR,
   SPEC_VERSION_SUPPORTED
-} from "../chunk-L4QRCHRQ.js";
+} from "../chunk-WOFRHRXY.js";
 import {
   MetadataRegistry,
   buildConditionExpression,
   execItemKeySignature,
   resolveConditionTree
-} from "../chunk-L2NEDS7U.js";
+} from "../chunk-GWWRXIHF.js";
 import {
   TableMapping
 } from "../chunk-XTWXMOHD.js";
@@ -489,7 +489,7 @@ function bindEntities(plan, planId) {
     entities[name] = entity;
     tables[metadata.tableName] = { physicalName: TableMapping.resolve(metadata.tableName) };
   }
-  return { classes, manifest: { version: SPEC_VERSION, tables, entities } };
+  return { classes, manifest: { version: SPEC_VERSION_KEY_EXPR, tables, entities } };
 }
 function renderSpecItem(transaction, index, manifest, params) {
   const single = {

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

@@ -1,4 +1,4 @@
-import { a1 as Param, E as ExpressionSpec, a2 as ParamKind, T as TransactionSpec, X as TransactionItemSpec } from './types-2PMXEn5x.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
@@ -725,6 +725,22 @@ interface DeleteInput {
  * with `maxAttempts: 1` so the library is the single source of truth for retry
  * (documented at `graphddb.config.client` and in the README). The library does NOT
  * silently mutate a user-provided client.
+ *
+ * NOTE on the SCP Error Policy Kind (issue #292 / G9, bc `scp-error.md`):
+ * everything in this module is **Tuning** (max attempts / delay / backoff /
+ * jitter / `isRetryable`) — Runtime-owned, IR-external, Conformance-external.
+ * The op-level Policy **Kind** (`fail`/`retry`/`continue`) is a separate,
+ * IR-carried control-flow intent interpreted ONLY by behavior-contracts'
+ * `runPlan` (graphddb adds no Kind interpretation of its own; the runtimes
+ * convert a DynamoDB failure to the shared `ExecOutcome {error}` at the
+ * handler boundary and let `runPlan` decide). No double-retry arises today:
+ * this executor layer belongs to the TS live executor, which does not run
+ * through `runBehavior`, and the 4 spec-consumer runtimes' handlers issue SDK
+ * calls without a Kind-driven retry loop (bc's reference `runPlan` treats a
+ * persistent `retry`-Kind failure as exhausted, converging on the `fail`
+ * propagation). If a runtime later implements a real `retry`-Kind loop, this
+ * Tuning (and the SDK's own `maxAttempts`) must be treated as the INNER
+ * mechanism of a single logical attempt — never stacked as a second policy.
  */
 /** The single-op kind a retry is wrapping — surfaced to {@link RetryPolicy.onRetry}. */
 type RetryOperationKind = 'get' | 'query' | 'batchGet' | 'put' | 'update' | 'delete' | 'batchWrite' | 'transactWrite';
@@ -1637,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).
@@ -2496,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
@@ -2565,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.
@@ -3022,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. */
@@ -3364,9 +3414,10 @@ type ParamLeaf<V> = [V] extends [StringLike] ? V | string | Param<string> : V |
  * covariance still admits a single-member subset placeholder, while a value outside
  * the union / a wider placeholder / a wrong scalar kind stays a type error.
  */
-type Parameterize<K> = [Exclude<K, Nullish>] extends [ScalarLeaf] ? [Exclude<K, Nullish>] extends [never] ? K : ParamLeaf<Exclude<K, Nullish>> | Extract<K, Nullish> : K extends object ? {
+type Parameterize<K> = [Exclude<K, Nullish>] extends [ScalarLeaf] ? [Exclude<K, Nullish>] extends [never] ? K : ParamLeaf<Exclude<K, Nullish>> | Extract<K, Nullish> : K extends object ? // An object-typed leaf (a `@map` / `@embedded` field) additionally accepts a
+{
     [P in keyof K]: Parameterize<K[P]>;
-} : K;
+} | Param<K> : K;
 /** Union of all keys across every member of a (possibly union) `Real` type. */
 type KnownKeyOf<Real> = Real extends object ? keyof Real : never;
 /** The value type of key `P` across the members of a (possibly union) `Real`, non-nullable. */
@@ -3610,8 +3661,26 @@ interface MutateAuthoringOptions {
 declare function mutate(body: TransactionDefinition, options?: MutateAuthoringOptions): TransactionDefinition;
 declare function mutate(body: CommandPlan, options?: MutateAuthoringOptions): PublicComposeDescriptor;
 declare function mutate(body: PublicCompositeDescriptor, options?: MutateAuthoringOptions): PublicCompositeDescriptor;
-/** The per-call execution mode of a command method (#101): replaces `batch`. */
-type CommandMode = 'transaction' | 'parallel';
+/**
+ * The per-call execution mode of a command method (#101): replaces `batch`.
+ *
+ * `'batchWrite'` (issue #298) is the DynamoDB `BatchWriteItem` bulk form —
+ * non-atomic, condition-free, any array size chunked ≤25 per request with
+ * `UnprocessedItems` retry, 1×WCU — the semantics the runtime has always
+ * implemented ({@link import('../runtime/command-runtime.js')}'s
+ * `executeBatchWrite` machinery); #298 makes it declarable/reachable from the
+ * public contract surface. It is only legal for an **unconditional** put /
+ * delete (`upsert` / condition-free `remove`) — `BatchWriteItem` physically
+ * carries no `ConditionExpression` and no `Update`, so a conditional / create
+ * (implicit `notExists` guard) / update / derived-effect method loud-rejects it
+ * at build time.
+ *
+ * **0.9.0 default flip ("bulk is the base case")**: an eligible method that
+ * declares NO mode now defaults to `'batchWrite'` (previously `'transaction'`).
+ * Declare `mode: 'transaction'` explicitly to keep the atomic
+ * `TransactWriteItems` bulk form.
+ */
+type CommandMode = 'transaction' | 'parallel' | 'batchWrite';
 /** A public **read** descriptor (issue #101): `{ query | list: Model, key, select, options? }`. */
 interface PublicReadDescriptor {
     readonly query?: ModelRef;
@@ -3644,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,9 @@
-import { L as Linter, a as LintRule } from '../linter-DQY7gUEk.js';
-export { b as LintResult } from '../linter-DQY7gUEk.js';
-import '../types-DW__-Icc.js';
-import '../key-DZtjAQDh.js';
-import '../types-2PMXEn5x.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';
 
 /**
  * Creates a Linter pre-loaded with rules safe for Entity registration.

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

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

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

@@ -1,6 +1,6 @@
-import { E as EntityMetadata } from './types-DW__-Icc.js';
-import { C as ContractSpec, Q as QuerySpec, a as CommandSpec, T as TransactionSpec, b as ContextSpec, S as SPEC_VERSION, P as ParamSpec } from './types-2PMXEn5x.js';
-import { Q as QueryModelContract, k as QueryMethodSpec, l as CommandModelContract, m as CommandMethodSpec } from './key-DZtjAQDh.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;
@@ -262,7 +262,7 @@ interface PreparedPlanSpec {
 interface PreparedPlanDocument {
     readonly formatVersion: typeof PREPARED_FORMAT_VERSION;
     /** The shared operation-IR version the plans were compiled against. */
-    readonly specVersion: typeof SPEC_VERSION;
+    readonly specVersion: typeof SPEC_VERSION_KEY_EXPR;
     /** Plan id (the transform's stable call-site id) → compiled plan. */
     readonly plans: Readonly<Record<string, PreparedPlanSpec>>;
 }