graphddb 0.8.0 → 0.8.1

package/dist/cdc/index.d.ts

@@ -1,6 +1,6 @@
-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-DR7_lpyk.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-DR7_lpyk.js';
-import { E as EntityMetadata } from '../types-BXLzIcQD.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-DZtjAQDh.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-DZtjAQDh.js';
+import { E as EntityMetadata } from '../types-DW__-Icc.js';
 import '../types-2PMXEn5x.js';
 
 /**

package/dist/{chunk-N4NWYNGZ.js → chunk-LAT64YCZ.js}

@@ -2,7 +2,7 @@ import {
   PREPARED_FORMAT_VERSION,
   buildManifest,
   entityFingerprint
-} from "./chunk-LGHSZIEE.js";
+} from "./chunk-S2NI4PBW.js";
 import {
   analyzeWriteRoute,
   assertBundleSerializable,
@@ -21,7 +21,7 @@ import {
   isContractKeyRef,
   isContractParamRef,
   isQueryModelContract
-} from "./chunk-I4LEJ4TF.js";
+} from "./chunk-T44OB5GU.js";
 import {
   detectRelationFields,
   isInlineSnapshotSpec,

package/dist/{chunk-LGHSZIEE.js → chunk-S2NI4PBW.js}

@@ -1,6 +1,6 @@
 import {
   evaluateKey
-} from "./chunk-I4LEJ4TF.js";
+} from "./chunk-T44OB5GU.js";
 import {
   SPEC_VERSION
 } from "./chunk-L4QRCHRQ.js";

package/dist/{chunk-I4LEJ4TF.js → chunk-T44OB5GU.js}

@@ -4669,8 +4669,11 @@ function mutate(body, options) {
   if (isCommandPlan(body)) {
     return mode !== void 0 ? { command: body, mode } : { command: body };
   }
+  if (isPublicCompositeDescriptor(body)) {
+    return mode !== void 0 ? { ...body, mode } : body;
+  }
   throw new Error(
-    "mutate: the body must be a write body \u2014 a `defineScpTransaction(...)` / `defineTransaction(...)` transaction definition or a `mutation(...)` plan. `mutate` is the authoring twin of the runtime `mutate`; its only option is `{ mode }` (the sole home of atomicity)."
+    "mutate: the body must be a write body \u2014 a PUBLIC composite descriptor (`{ writes: $ => ({ alias: descriptor, \u2026 }), input?, result? }`, the import-free multi-entity atomic form, #293), a `defineScpTransaction(...)` / `defineTransaction(...)` transaction definition, or a `mutation(...)` plan. `mutate` is the authoring twin of the runtime `mutate`; its only option is `{ mode }` (the sole home of atomicity)."
   );
 }
 function buildCommandContract(methods) {
@@ -4681,6 +4684,19 @@ function buildCommandContract(methods) {
       resolved[name] = finalizeDescriptorCommand(name, plan2, select, condition, mode, description);
       continue;
     }
+    if (isPublicCompositeDescriptor(body)) {
+      const plan2 = mutation(name, body.writes);
+      const select = body.result !== void 0 && body.result.select !== void 0 ? body.result.select : void 0;
+      resolved[name] = finalizeDescriptorCommand(
+        name,
+        plan2,
+        select,
+        void 0,
+        body.mode ?? "transaction",
+        body.description
+      );
+      continue;
+    }
     if (isPublicComposeDescriptor(body)) {
       const select = body.result !== void 0 && body.result.select !== void 0 ? body.result.select : void 0;
       resolved[name] = finalizeDescriptorCommand(
@@ -4708,7 +4724,7 @@ function buildCommandContract(methods) {
       continue;
     }
     throw new Error(
-      `publishCommand: method '${name}' must be a write descriptor (\`{ create | update | remove: Model, key, input?, condition?, result?, mode? }\`), a composite \`{ command: mutation(...), input?, result?, mode? }\` descriptor, a bare \`mutation($ => ({ \u2026 }))\` plan, or an SCP native-syntax \`defineScpTransaction(...)\` multi-write body. The legacy closure form (\`(keys, params) => Model.putItem(...)\`) and the \`command(...).plan(...)\` builder have been removed (#101).`
+      `publishCommand: method '${name}' must be a write descriptor (\`{ create | update | remove: Model, key, input?, condition?, result?, mode? }\`) for a single-entity write, or \u2014 for a multi-entity atomic (composite) write \u2014 a \`{ writes: $ => ({ alias: { create | update | remove: Model, key, input?, condition? }, \u2026 }), input?, result?, mode? }\` descriptor (the PUBLIC composite form; a multi-alias \`writes\` body is compiled internally into one atomic \`TransactWriteItems\`, needing no \`mutation(...)\` / \`defineScpTransaction(...)\` import). The legacy closure form (\`(keys, params) => Model.putItem(...)\`) and the \`command(...).plan(...)\` builder have been removed (#101).`
     );
   }
   return { __isContract: true, kind: "command", methods: resolved };
@@ -4801,6 +4817,9 @@ var WRITE_INTENT_KEYS = ["create", "update", "remove", "upsert"];
 function isPublicComposeDescriptor(value) {
   return typeof value === "object" && value !== null && isCommandPlan(value.command);
 }
+function isPublicCompositeDescriptor(value) {
+  return typeof value === "object" && value !== null && typeof value.writes === "function";
+}
 function isPublicReadDescriptor(value) {
   return typeof value === "object" && value !== null && READ_INTENT_KEYS2.some((k) => value[k] !== void 0);
 }

package/dist/cli.js

@@ -2,11 +2,11 @@
 import {
   buildBridgeBundle,
   buildOperations
-} from "./chunk-N4NWYNGZ.js";
+} from "./chunk-LAT64YCZ.js";
 import {
   buildManifest
-} from "./chunk-LGHSZIEE.js";
-import "./chunk-I4LEJ4TF.js";
+} from "./chunk-S2NI4PBW.js";
+import "./chunk-T44OB5GU.js";
 import "./chunk-HNY2EJPV.js";
 import "./chunk-L4QRCHRQ.js";
 import {

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-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-DR7_lpyk.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-DR7_lpyk.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-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 * 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-BXLzIcQD.js';
+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';
 
 /**

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   mutate,
   publishCommand,
   publishQuery
-} from "./chunk-I4LEJ4TF.js";
+} from "./chunk-T44OB5GU.js";
 import {
   entityWrites,
   getEntityWrites,

package/dist/internal/index.d.ts

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

package/dist/internal/index.js

@@ -2,14 +2,14 @@ import {
   PREPARED_FORMAT_VERSION,
   buildManifestEntity,
   entityFingerprint
-} from "../chunk-LGHSZIEE.js";
+} from "../chunk-S2NI4PBW.js";
 import {
   LOGICAL_EFFECT_CATEGORIES,
   PreparedReadStatement,
   executeLogicalParallelWrites,
   executeLogicalWriteOps,
   serializeEffectParams
-} from "../chunk-I4LEJ4TF.js";
+} from "../chunk-T44OB5GU.js";
 import "../chunk-HNY2EJPV.js";
 import {
   MARKER_ROW_ENTITY,

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

@@ -2398,6 +2398,32 @@ interface MutationEntityRef {
     /** The source path, e.g. `$.entity[0].postId` (documentary; surfaces in errors). */
     readonly path: string;
 }
+/**
+ * The placeholder proxy handed to a mutation body as `$`. In the descriptor-map
+ * authoring form (issue #108) a top-level read `$.<x>` is **ambiguous** until used:
+ *
+ *  - `$.role` placed at a `key` / `input` leaf is an **input-field reference**
+ *    (a {@link MutationInputRef}, token `{role}`) — bound from the command input;
+ *  - `$.membership.role` is a **cross-fragment reference** — the `role` field
+ *    written by the fragment named `membership` (an alias). It mints an
+ *    {@link AliasFieldRef}, which the {@link mutation} assembler rewrites into the
+ *    legacy `$.entity[<index>].<field>` string the compiler resolves (the alias →
+ *    declaration-order index is known once every alias key is seen).
+ *
+ * So each top-level read returns a value that is **both** a faithful
+ * {@link MutationInputRef} (when used directly as a leaf) and supports one further
+ * `.<field>` access (when used as an alias root). Any other access / coercion
+ * throws — the binding stays declarative (only a direct `$.field` / `$.alias.field`
+ * reference or a literal is representable, never a transform).
+ *
+ * **Input Port 統一 (issue #264)**: this proxy is one of the three authoring
+ * spellings of the SAME Input Port reference model — see the unification note
+ * on {@link import('./transaction.js').ParamProxy} (`defineTransaction`'s
+ * `p.*` proxy is the model; `{<field>}` templates and `{ref:["input","<field>"]}`
+ * expression refs are the two serialized mirrors of one declared-input
+ * namespace). Behavior here is unchanged in 0.7.x (interop kept).
+ */
+type MutationInputProxy = Record<string, MutationInputRef>;
 declare const FRAGMENT_BRAND: unique symbol;
 /**
  * The per-field input binding of a fragment: model field name → a faithful
@@ -2406,6 +2432,14 @@ declare const FRAGMENT_BRAND: unique symbol;
  * field they key, never a transform.
  */
 type FragmentInput = Readonly<Record<string, MutationInputRef | string | number | boolean | Date | null>>;
+/**
+ * A descriptor `key` / `input` value as authored in the descriptor-map form
+ * (issue #108): a `$.field` input reference, a `$.alias.field` cross-fragment
+ * reference (an opaque alias-field ref the assembler rewrites), or a literal.
+ * Structurally `unknown` at the leaf because the alias-field ref is internal; the
+ * assembler validates every leaf via {@link assertFaithfulInput}.
+ */
+type DescriptorBinding = Readonly<Record<string, unknown>>;
 /** A concrete scalar admissible at a condition operand leaf. */
 type ConditionScalar = MutationInputRef | string | number | boolean | Date | null;
 /** A declarative operator object on one condition field (the #114-A subset). */
@@ -2488,6 +2522,68 @@ interface MutationFragment {
  * `m.create(() => Model, …)` recorder required.
  */
 type ModelRef = ModelStatic<DDBModel> | (new (...args: unknown[]) => unknown) | (() => ModelStatic<DDBModel> | (new (...args: unknown[]) => unknown));
+/**
+ * One **write descriptor** in the descriptor-map authoring form (issue #108) —
+ * the declarative twin of an in-process `DDBModel.mutate` entry (#101). The intent
+ * key (`create` / `update` / `remove`) is the **discriminator** and carries the
+ * target {@link ModelRef} (direct or thunk). The remaining fields are declarative
+ * bindings (`$.field` references or literals):
+ *
+ *  - `key` — the target row's primary-key binding (identifies the row);
+ *  - `input` — the non-key field binding (the body / changed fields). Optional for
+ *    a `remove` (a delete writes no fields);
+ *  - `condition` — an optional declarative write gate (issue #242, Phase 2). It is
+ *    the #114-A condition subset (bare equality, operator objects `{ gt }` / `{ in }`
+ *    / `{ between }` / …, and `and` / `or` / `not` groups) whose operand leaves are
+ *    `$.field` input references or literals. The declaration-DSL compiler **consumes**
+ *    it: each `$.field` leaf becomes a {@link import('./contract.js').ContractParamRef}
+ *    and the tree is attached to the compiled base op's `condition`, so it is
+ *    serialized (into the operation spec) and evaluated at runtime exactly as a #101
+ *    public write descriptor's condition is (single-op, in-process
+ *    transaction, and the Python bridge). A conditioned `update` / `remove` therefore
+ *    fails a CAS-style write when the gate does not hold, rather than silently
+ *    committing;
+ *  - `result` — an optional read-back projection `{ select, options? }` (likewise
+ *    accepted for authoring parity; the public read-back projection of a
+ *    `command(...).plan(...)` method is still declared on `command({ select })`).
+ *
+ * Exactly one intent key must be present.
+ */
+interface WriteDescriptor {
+    readonly create?: ModelRef;
+    readonly update?: ModelRef;
+    readonly remove?: ModelRef;
+    /**
+     * `upsert` — a `PutItem` with **no** `attribute_not_exists(PK)` guard (an
+     * unconditional overwrite; the semantics of the removed `definePut`). Unlike
+     * `create` (which always guards against clobbering an existing row), an `upsert`
+     * writes whether or not the row exists; an author-supplied `condition` is honored
+     * verbatim (never ANDed with a `notExists` guard).
+     */
+    readonly upsert?: ModelRef;
+    /** The target row's primary-key binding (`{ field: $.field | literal }`). */
+    readonly key: DescriptorBinding;
+    /** The non-key field binding; optional (a `remove` writes no fields). */
+    readonly input?: DescriptorBinding;
+    /**
+     * Optional declarative write gate — the #114-A condition subset (issue #242,
+     * Phase 2). Compiled, serialized, and evaluated at runtime; see the interface doc.
+     */
+    readonly condition?: FragmentCondition;
+    /** Optional read-back projection `{ select, options? }` (accepted for #101 parity). */
+    readonly result?: {
+        readonly select?: unknown;
+        readonly options?: unknown;
+    };
+    /**
+     * Optional custom save contract to adopt (the **whole** {@link
+     * EntityWritesDefinition}). Omit to default to the target model's own `writes`.
+     * Per the `use:` rule this is never a single lifecycle — the intent picks it.
+     */
+    readonly use?: EntityWritesDefinition;
+}
+/** The descriptor map a {@link mutation} body returns: alias → {@link WriteDescriptor}. */
+type MutationDescriptorMap = Record<string, WriteDescriptor>;
 declare const COMMAND_PLAN_BRAND: unique symbol;
 /**
  * The recorded **CommandPlan** — a mutation's IR (proposal §3). It carries the
@@ -2503,6 +2599,14 @@ interface CommandPlan {
     /** The declared write fragments, in declaration order (the mutation IR). */
     readonly fragments: readonly MutationFragment[];
 }
+/**
+ * The body of a {@link mutation} in the descriptor-map authoring form (issue #108):
+ * `$ => ({ alias: descriptor, … })`. It receives the placeholder proxy `$` and
+ * returns an **alias → {@link WriteDescriptor}** map. The map's **insertion order**
+ * is the fragments' declaration (execution) order, and each alias is the name a
+ * later descriptor's `$.alias.field` cross-fragment reference resolves against.
+ */
+type MutationBody = ($: MutationInputProxy) => MutationDescriptorMap;
 
 /**
  * Declarative transaction definition DSL (issue #46, Python-bridge Phase 4).
@@ -3391,7 +3495,13 @@ type WriteDescriptorResultOf<D> = D extends {
         readonly select: infer S;
     };
 } ? S extends Record<string, unknown> ? Readonly<Record<Extract<keyof S, string>, unknown>> | null : void : void;
-/** A write descriptor's contract Key (from its `key` record). */
+/**
+ * A write descriptor's contract Key (from its `key` record). A #293 PUBLIC composite
+ * descriptor (`{ writes, input }`) has no single top-level `key` — it is a
+ * multi-entity write with no single primary Key — so it falls through to `unknown`,
+ * exactly as a bare `mutation()` plan / SCP transaction body does; its public params
+ * are still precise via {@link DescriptorParamsOf} (the separate `input` schema).
+ */
 type WriteDescriptorKeyOf<D> = D extends {
     readonly key: infer K;
 } ? KeyOf<K> : unknown;
@@ -3414,7 +3524,7 @@ type ResolvedReadDescriptors<M extends ReadDescriptorMap> = QueryModelContract<M
  * {@link CommandPlan}, or an SCP native-syntax `defineScpTransaction(...)`
  * multi-write body ({@link TransactionDefinition}, Phase 4 S1 / issue #278).
  */
-type WriteDescriptorMap = Record<string, PublicWriteDescriptor | PublicComposeDescriptor | CommandPlan | TransactionDefinition>;
+type WriteDescriptorMap = Record<string, PublicWriteDescriptor | PublicCompositeDescriptor | PublicComposeDescriptor | CommandPlan | TransactionDefinition>;
 /** Resolve a write-descriptor map to its {@link CommandModelContract}. */
 type ResolvedWriteDescriptors<M extends WriteDescriptorMap> = CommandModelContract<M[keyof M] extends infer D ? WriteDescriptorKeyOf<D> : unknown, {
     readonly [K in keyof M]: CommandMethodSpec<WriteDescriptorKeyOf<M[K]>, DescriptorParamsOf<M[K]>, WriteDescriptorResultOf<M[K]>>;
@@ -3493,9 +3603,13 @@ interface MutateAuthoringOptions {
  *   `publishCommand`'s SCP-body branch — declare a mode).
  * - `mutate(plan, { mode })` → a {@link PublicComposeDescriptor} (`{ command,
  *   mode }`), the closure-free composite form.
+ * - `mutate(compositeDescriptor, { mode })` → the same PUBLIC composite descriptor
+ *   (`{ writes, input?, result? }`, issue #293) with `mode` stamped — the
+ *   import-free composite form usable directly as a `publishCommand` method value.
  */
 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';
 /** A public **read** descriptor (issue #101): `{ query | list: Model, key, select, options? }`. */
@@ -3567,6 +3681,54 @@ interface PublicComposeDescriptor {
      */
     readonly description?: string;
 }
+/**
+ * A public **composite mutation** descriptor (issue #293) — the PUBLIC, closure-free
+ * authoring form for a multi-entity atomic (or non-atomic) write, needing **no**
+ * `mutation(...)` / `defineScpTransaction(...)` import. It carries a `writes` body
+ * (`$ => ({ alias: { create|update|remove|upsert: Model, key, input?, condition? } })`
+ * — the same mutation body the internal `mutation()` builder consumes), a **separate**
+ * `input` schema (`{ field: param.* }`) that names the public input fields the `$`
+ * proxy in the body references, an optional read-back `result.select`, and an optional
+ * execution `mode`.
+ *
+ * `publishCommand` compiles the `writes` body internally via the retained (internal)
+ * `mutation()` builder, then routes the resulting {@link CommandPlan} through the SAME
+ * `buildPlannedCommandMethod` path a bare `mutation()` plan / a
+ * {@link PublicComposeDescriptor} takes. A **single-alias** `writes` body is one write;
+ * a **multi-alias** body is an atomic composite (promoted to one
+ * `TransactWriteItems` by DynamoDB necessity — the existing promotion path), so its
+ * wire is byte-identical to authoring the same composite via the internal `mutation()`.
+ *
+ * The `input` schema is the public param declaration: its `param.*` leaves drive the
+ * generated typed binding's input struct (and the TS-level `params` type). It exists
+ * separately from the body (the owner-final #293 decision) so the mutation body stays a
+ * pure write declaration — options (input schema / read-back) are specified alongside it,
+ * not baked into it.
+ */
+interface PublicCompositeDescriptor {
+    /**
+     * The mutation body: `$ => ({ alias: writeDescriptor, … })`. Single alias ⇒ one
+     * write; multiple aliases ⇒ an atomic composite. The `$` proxy's fields are the
+     * public input fields declared in {@link input}.
+     */
+    readonly writes: MutationBody;
+    /**
+     * The public input schema: `{ field: param.* }`. Names (and types) the input fields
+     * the `writes` body's `$` proxy references. Optional (a body may bind only literals),
+     * though a composite normally declares at least the key params.
+     */
+    readonly input?: Readonly<Record<string, unknown>>;
+    readonly result?: {
+        readonly select?: Readonly<Record<string, boolean>>;
+        readonly options?: unknown;
+    };
+    readonly mode?: CommandMode;
+    /**
+     * Optional human-readable description of the composite write use case (issue #154).
+     * Pure documentation — propagated to the serialized command method spec.
+     */
+    readonly description?: string;
+}
 
 /**
  * Maintenance graph builder (Epic #118 issue #124 — the RFC B-案 core).

package/dist/linter/index.d.ts

@@ -1,7 +1,7 @@
-import { L as Linter, a as LintRule } from '../linter-C-vypgut.js';
-export { b as LintResult } from '../linter-C-vypgut.js';
-import '../types-BXLzIcQD.js';
-import '../key-DR7_lpyk.js';
+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';
 
 /**

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

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

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

@@ -1,6 +1,6 @@
-import { E as EntityMetadata } from './types-BXLzIcQD.js';
+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-DR7_lpyk.js';
+import { Q as QueryModelContract, k as QueryMethodSpec, l as CommandModelContract, m as CommandMethodSpec } from './key-DZtjAQDh.js';
 
 /**
  * Contract-layer serialization (issue #59, CQRS Contract layer, Epic #57;

package/dist/spec/index.d.ts

@@ -1,11 +1,11 @@
-import { $ as AnyOperationDefinition, a0 as TransactionDefinition, b as PreparedBody } from '../key-DR7_lpyk.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-DR7_lpyk.js';
-import { M as MetadataRegistry } from '../linter-C-vypgut.js';
-import { C as ContractMap, e as ContextOwnershipMap, c as PreparedPlanSpec, a as PreparedPlanDocument } from '../prepared-artifact-BpPgkXEo.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-BpPgkXEo.js';
+import { $ as AnyOperationDefinition, a0 as TransactionDefinition, b as PreparedBody } from '../key-DZtjAQDh.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-DZtjAQDh.js';
+import { M as MetadataRegistry } from '../linter-DQY7gUEk.js';
+import { C as ContractMap, e as ContextOwnershipMap, c as PreparedPlanSpec, a as PreparedPlanDocument } from '../prepared-artifact-HFealr1q.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-HFealr1q.js';
 import { O as OperationsDocument, Q as QuerySpec, M as Manifest, C as ContractSpec, T as TransactionSpec, B as BridgeBundle, c as ConditionSpec, E as ExpressionSpec, a as CommandSpec, d as SpecVersion } from '../types-2PMXEn5x.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, S as SPEC_VERSION, V as SPEC_VERSION_SCP, W as SPEC_VERSION_SUPPORTED, X as TransactionItemSpec, Y as TransactionItemType, Z as WhenSpec, _ as WriteOperationType } from '../types-2PMXEn5x.js';
-import '../types-BXLzIcQD.js';
+import '../types-DW__-Icc.js';
 
 /**
  * Static parameterized operation-spec generation (issue #42, Phase 0b).

package/dist/spec/index.js

@@ -10,14 +10,14 @@ import {
   collectContractBoundaryViolations,
   collectContractN1Violations,
   compilePreparedPlan
-} from "../chunk-N4NWYNGZ.js";
+} from "../chunk-LAT64YCZ.js";
 import {
   PREPARED_FORMAT_VERSION,
   buildManifest,
   canonicalJson,
   entityFingerprint,
   planFingerprint
-} from "../chunk-LGHSZIEE.js";
+} from "../chunk-S2NI4PBW.js";
 import {
   MAX_TRANSACT_COMPOSE_ITEMS,
   assertBundleSerializable,
@@ -32,7 +32,7 @@ import {
   resetMaintenanceGraphCache,
   resolveLifecycle,
   resolveMaintainers
-} from "../chunk-I4LEJ4TF.js";
+} from "../chunk-T44OB5GU.js";
 import "../chunk-HNY2EJPV.js";
 import {
   EXPR_VERSION,

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-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-DR7_lpyk.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-DZtjAQDh.js';
 import '../types-2PMXEn5x.js';
 
 /**

package/dist/{types-BXLzIcQD.d.ts → types-DW__-Icc.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-DR7_lpyk.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-DZtjAQDh.js';
 
 type DynamoType = 'S' | 'N' | 'BOOL' | 'B' | 'SS' | 'NS' | 'L' | 'M';
 interface FieldOptions {

package/docs/cqrs-contract.md

@@ -263,6 +263,52 @@ addMany: { create: GroupMembership, key: { groupId: param.string(), userId: para
 `GraphQL contrast`: `mode: 'transaction'` is atomic all-or-nothing; `mode:
 'parallel'` is non-atomic per-field partial success.
 
+### Composite (multi-entity atomic) methods — the `writes` body
+
+A single write descriptor covers one entity. A **composite** method writes
+**multiple entities atomically** — the canonical case being a cross-entity write
+that has **no relation to fall back on** (e.g. marking a hash-keyed aggregate node
+`dirty` alongside a chunk's terminal update). Author it with the **`writes` body**
+form:
+
+```ts
+export const ChunkCompleteCommands = graphddb.publishCommand({
+  complete: {
+    // the public input schema — names + types the params the body references
+    input: { chunkId: param.string(), nodeId: param.string() },
+    // the mutation body: `$ => ({ alias: descriptor, … })`; `$` refers to the inputs
+    writes: ($) => ({
+      chunk: { update: Chunk,   key: { chunkId: $.chunkId }, input: { done: true } },
+      agg:   { update: AggNode, key: { nodeId: $.nodeId },  input: { dirty: true } },
+    }),
+    // optional read-back projection (keyed on the primary — first — fragment)
+    result: { select: { chunkId: true, done: true } },
+  },
+});
+```
+
+- `writes` is a body `$ => ({ alias: writeDescriptor, … })`. Each alias value is a
+  write descriptor (`{ create | update | remove | upsert: Model, key, input?,
+  condition? }` — the same shape as a single-descriptor method, minus `result` /
+  `mode`, which are declared on the composite as a whole). The `$` proxy fields are
+  the input fields declared in the separate **`input`** schema; a later descriptor
+  may reference an earlier alias's written field via `$.alias.field`.
+- **Single-alias** `writes` ⇒ one write. **Multi-alias** ⇒ an **atomic composite**:
+  it is promoted to a single `TransactWriteItems` by DynamoDB necessity (there is no
+  non-atomic multi-item form for a cross-entity write), so no `mode` ceremony is
+  needed — a multi-alias composite is always atomic.
+- `input` (the public param schema), `result` (read-back), and `mode` are specified
+  **alongside** the body, never baked into it.
+- **No `mutation(...)` / `defineScpTransaction(...)` import is needed** —
+  `publishCommand` compiles the `writes` body internally. The emitted
+  `operations.json` wire is byte-identical to the equivalent internal composition.
+- The single-descriptor form above stays the sugar for a single-entity write; the
+  `writes` body is the additive form for the multi-entity atomic case.
+
+> The full **SCP native-syntax** composite body (imperative `$`/`?:`/`&&`/`.map`
+> transaction sources) is a separate surface, deferred to a later release; the
+> `writes` descriptor-map body above is the supported public composite form today.
+
 #### The 25-item limit is a hard error, never a silent split
 
 `TransactWriteItems` is capped at **25 items** and is atomic. A
@@ -498,15 +544,20 @@ Definition DSL (`src/define/contract.ts`) — import the `graphddb` namespace
 
 ```ts
 graphddb.publishQuery({ alias: { query | list: Model, key, select, options? } })
+// single-entity write
 graphddb.publishCommand({ alias: { create | update | remove: Model, key, input, condition?, result?, use?, mode? } })
+// multi-entity atomic (composite) write — the `writes` body form (#293)
+graphddb.publishCommand({ alias: { input, writes: $ => ({ alias: descriptor, … }), result?, mode? } })
 param.string() / param.number() / ...               // descriptor key/input parameters
 ```
 
 A query method may compose another query contract's method (cross-fragment refs
-via `$.alias.field`); a command descriptor composes its derived write ops and
-maintenance writes into one plan. These are declared inside the
-`publishQuery` / `publishCommand` map — there is no separate public `query()` /
-`mutation()` composite verb (removed in 0.8.0).
+via `$.alias.field`); a command method composes its derived write ops and
+maintenance writes into one plan, and a **composite** command method's `writes`
+body composes a multi-entity atomic write (§ Composite methods). These are all
+declared inside the `publishQuery` / `publishCommand` map — there is no separate
+public `query()` / `mutation()` composite verb (removed in 0.8.0; the composite
+`writes` body is compiled internally, needing no import).
 
 Execution is the two `graphddb.*` verbs (`graphddb.query` / `graphddb.mutate`) —
 they route contract methods through the in-process runtime.

package/package.json

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