graphddb 0.8.1 → 0.9.1

package/dist/behaviors-DDltNivc.d.ts

@@ -0,0 +1,217 @@
+import { Recorded, Component, ComponentGraphIR, PortSchema, BehaviorClass } from 'behavior-contracts';
+
+/**
+ * GraphDDB's first-class SCP catalog — issue #297 SP1 (SCP authoring adoption),
+ * promoting the Phase-1 executor catalog (#288, `src/executor/catalog.ts`) into
+ * THE behavior-contracts–typed catalog the spec emitter is validated against.
+ *
+ * ## Source of truth (SP1 decision)
+ *
+ * ONE catalog lives here, in the spec layer — the layer that emits `components[]`
+ * (`src/spec/components.ts`) — and `src/executor/catalog.ts` re-exports it
+ * unchanged (the C4 handler registry keeps resolving against the same object).
+ * The Phase-1 module described itself as the C2 "the only per-DSL difference is
+ * the catalog" surface but its Port schemas mirrored the OLD-path executor
+ * inputs (`DynamoDBOperation` / `PutInput`), written before the Phase-3 emitter
+ * existed. Since #290 P3-5 the portable IR's actual wiring is the emitted
+ * component-graph ports, so promoting the catalog to LOAD-BEARING means the
+ * schemas here describe the EMITTED Port contract (what `readPorts` /
+ * `transactionItemPorts` in `components.ts` actually wire, and what a
+ * `runBehavior` handler actually receives) — the two latent Phase-1↔Phase-3
+ * inconsistencies are fixed loudly, not papered over:
+ *
+ * 1. **`ConditionCheck` was missing.** The emitter has emitted `ConditionCheck`
+ *    componentRefs since Phase 3 (`buildTransactionComponent`), but the Phase-1
+ *    catalog declared only 7 entries without it — so the "catalog" did not cover
+ *    the emitted vocabulary. It is now a first-class entry.
+ * 2. **`TransactWrite` is not portable.** No portable document references
+ *    `TransactWrite` (a transaction is emitted as a Component whose body
+ *    references the per-item write primitives; the atomic TransactWriteItems
+ *    envelope is the TS runtime's execution concern) — so its Phase-1
+ *    `portableToIR: true` claim was false since P3-5. It stays a catalog entry
+ *    (the executor-side atomic envelope, and a member of the write set) but is
+ *    now honestly `portableToIR: false`.
+ *
+ * ## Port schema conventions
+ *
+ * A `CatalogEntry.inputPorts` names the STATIC ports of the emitted wiring. Two
+ * port families are dynamic by construction and are validated by
+ * {@link assertComponentsInCatalog} against documented patterns instead:
+ *
+ * - **Read key-attribute ports**: one port per `keyExpr` attribute, named by the
+ *   physical key attribute — graphddb's fixed single-table convention
+ *   `PK` / `SK` / `<index>PK` / `<index>SK` ({@link KEY_ATTR_PORT}).
+ * - **Write record ports**: a transaction item's `item` / `key` / `changes` /
+ *   `add` records and the `condition.equals` / `condition.params` /
+ *   `condition.values` slots are flattened one-port-per-field under a
+ *   `<group>.<field>` key ({@link WRITE_PORT_FAMILIES}).
+ *
+ * ## Dynamic-port opt-in (`additionalPorts`, SP3)
+ *
+ * The seven read/write-item entries carry `additionalPorts: true` (bc#26): their
+ * dynamic port families above are BY DESIGN not statically enumerable, so bc's
+ * shared port check (`checkPortNames` — used by both the `catalogComponents`
+ * authoring recorder and `buildComponentDefinition`) must not reject them. This
+ * is an honest declaration, not a loosening: the dynamic families are still
+ * validated fail-closed by {@link assertComponentsInCatalog} (emit/registration
+ * time), and every DECLARED port keeps bc's required/type checks regardless of
+ * the opt-in. It is exactly this opt-in that makes `GRAPHDDB_CATALOG` directly
+ * consumable by the shared authoring surface (`catalogComponents(GRAPHDDB_CATALOG)`,
+ * bc#24 / #297 SP3) — the C2 contract that the catalog IS the whole per-DSL
+ * difference. `TransactWrite` stays fail-closed (its one port is static).
+ *
+ * ## Write set (SP1b) — and where `ConditionCheck` sits
+ *
+ * {@link WRITE_CATALOG_NAMES} is the CQRS write catalog: `PutItem` /
+ * `UpdateItem` / `DeleteItem` / `TransactWrite` / `ConditionCheck`.
+ * `ConditionCheck` mutates nothing — but it is classified WRITE deliberately:
+ * it exists only inside `TransactWriteItems` (DynamoDB accepts it in no read
+ * API), it acquires the item's transactional lock, and its failure aborts the
+ * sibling writes. A component referencing it therefore can only ever execute on
+ * the command path — for effect ROUTING (which is all the write set decides,
+ * bc#24) it is command-side infrastructure, not a read. The read set is exactly
+ * `GetItem` / `Query` / `BatchGetItem`; every catalog name is in exactly one set.
+ */
+
+/**
+ * The catalog-name literal union — one entry per DynamoDB primitive GraphDDB
+ * declares: the `ReadOperationType` (`GetItem` / `Query` / `BatchGetItem`) and
+ * `WriteOperationType` (`PutItem` / `UpdateItem` / `DeleteItem`) enum members
+ * from `src/spec/types.ts`, the transaction-item assertion primitive
+ * (`ConditionCheck`), and the atomic envelope (`TransactWrite`).
+ */
+type CatalogName = 'GetItem' | 'Query' | 'BatchGetItem' | 'PutItem' | 'UpdateItem' | 'DeleteItem' | 'ConditionCheck' | 'TransactWrite';
+/** GraphDDB's CQRS effect vocabulary, mapped 1:1 from bc's `BehaviorEffect`. */
+type ContractEffect = 'query' | 'command';
+
+/**
+ * `publishBehaviors` — the shared-SCP authoring entry (issue #297 SP3; pairs
+ * graphddb with behavior-contracts bc#24 and connects to #296 P4-1).
+ *
+ * A user authors a **`SemanticBehavior` class** on behavior-contracts' SHARED
+ * authoring surface — `$` input wiring, `when` / `.map` structured control, the
+ * expression builders (`eq` / `concat` / `coalesce` / …), and the leaf
+ * components minted from graphddb's catalog via
+ * `catalogComponents(GRAPHDDB_CATALOG)` ({@link behaviorComponents}) — and
+ * publishes it here:
+ *
+ * ```ts
+ * import { graphddb, behaviorComponents } from 'graphddb';
+ * import { SemanticBehavior, concat, type In } from 'behavior-contracts';
+ *
+ * const G = behaviorComponents();
+ * class ArticleBehaviors extends SemanticBehavior {
+ *   getArticleWithTags($: In<{ articleId: string }>) {
+ *     const a = G.GetItem({ table: 'Articles', PK: concat('ARTICLE#', $.articleId), SK: 'META',
+ *                           projection: ['articleId', 'title', 'tagRefs'] });
+ *     const tags = a.tagRefs.map(($t: Recorded) =>
+ *       G.BatchGetItem({ table: 'Articles', PK: concat('TAG#', $t.tagId), SK: 'META',
+ *                        projection: ['tagId', 'label'] }), { batched: true });
+ *     return { article: a, tags };
+ *   }
+ * }
+ * const Articles = graphddb.publishBehaviors(ArticleBehaviors);
+ * ```
+ *
+ * ## Responsibility split (C2 — "the difference is the catalog only")
+ *
+ * - **behavior-contracts does ALL composition and lowering**: `compileBehaviors`
+ *   evaluates each public method once (throwing-sentinel recording + native
+ *   control-syntax source scan), lowers `$` references, component calls, `when`
+ *   and `.map` into the portable component-graph IR, derives the plan, and
+ *   self-checks the result with `assertPortableComponentGraph`. graphddb adds
+ *   **no generic lowering of its own**.
+ * - **graphddb supplies only the catalog and the effects**: the leaf vocabulary
+ *   is `GRAPHDDB_CATALOG` (#297 SP1 — the same load-bearing catalog the spec
+ *   emitter is validated against), the dynamic port families are validated by
+ *   the same {@link assertComponentsInCatalog}, and the Query/Command
+ *   classification is DERIVED from the lowered graph per SP2/SP4
+ *   ({@link deriveContractEffect}) — the author never declares an effect
+ *   (authoring is effect-agnostic; a method that references a write-catalog
+ *   primitive IS a command).
+ *
+ * The compiled components register additively into the operations document
+ * through `buildOperations`' `contractInputs.behaviors` (each component emitted
+ * as `<RegistrationKey>__<method>`), and the TS runtime executes them through
+ * bc's `runBehavior` with graphddb's real DynamoDB handlers
+ * (`src/executor/behavior-exec.ts` — the Phase-1 handler-registry seam's
+ * behavior-execution counterpart, mirroring `python/graphddb_runtime/behavior_exec.py`).
+ */
+
+/**
+ * One published behavior method: the bc-lowered component (name = the method
+ * name), plus its graph-DERIVED CQRS effect (#297 SP2/SP4 — the classification
+ * source of truth is the component graph; `publishBehaviors` has no
+ * query/command vocabulary for the author to declare).
+ */
+interface BehaviorMethodSpec {
+    /** The method (= root Behavior = component) name. */
+    readonly name: string;
+    /** Graph-derived Query/Command classification (never author-declared). */
+    readonly effect: ContractEffect;
+    /** The lowered portable component (bc `compileBehaviors` output). */
+    readonly component: Component;
+}
+/**
+ * A resolved behavior contract — `publishBehaviors` output. Carries the whole
+ * bc-lowered {@link ComponentGraphIR} (directly `runBehavior`-executable; the
+ * component names are the method names) and the per-method specs with their
+ * derived effects. Register it into the operations document via
+ * `buildOperations(..., { behaviors: { Name: contract } })`.
+ */
+interface BehaviorModelContract {
+    /** Discriminates from the publishQuery/publishCommand contract objects. */
+    readonly kind: 'behaviors';
+    /** The authored class name (diagnostics only). */
+    readonly className: string;
+    /** The bc-lowered portable IR (all methods; `runBehavior`-executable). */
+    readonly ir: ComponentGraphIR;
+    /** The lowered components (`ir.components`, one per public method). */
+    readonly components: readonly Component[];
+    /** Method name → lowered component + derived effect. */
+    readonly methods: Readonly<Record<string, BehaviorMethodSpec>>;
+}
+/** Options passed through to bc `compileBehaviors` (additive; all optional). */
+interface PublishBehaviorsOptions {
+    /**
+     * Input Port schema overrides (method → port → schema): build-time evaluation
+     * derives port NAMES from `$` accesses; TS types are erased, so supply the
+     * type strings here if the registered document should carry them.
+     */
+    readonly inputPorts?: Record<string, Record<string, PortSchema>>;
+    /** Plan concurrency recorded on the lowered components (bc default: 16). */
+    readonly concurrency?: number;
+}
+/** The `catalogComponents(GRAPHDDB_CATALOG)` leaf-function map (typed). */
+type BehaviorComponentFns = Record<CatalogName, (ports: Record<string, unknown>) => Recorded>;
+/**
+ * The graphddb leaf components for the shared authoring surface:
+ * `catalogComponents(GRAPHDDB_CATALOG)` bound once, lazily. Call it at module
+ * scope of an authoring module (`const G = behaviorComponents()`) and invoke
+ * the leaves inside `SemanticBehavior` method bodies. `TransactWrite` is in the
+ * map but is `portableToIR: false`, so wiring it is rejected at record time —
+ * the atomic envelope is a TS-runtime execution concern, never authored.
+ */
+declare function behaviorComponents(): BehaviorComponentFns;
+/**
+ * Publish a `SemanticBehavior` class as a graphddb behavior contract (#297 SP3).
+ *
+ * Pipeline (all loud, nothing dropped):
+ *  1. bc `compileBehaviors(cls)` lowers every public method into one portable
+ *     component (bc owns ALL composition/lowering and self-checks portability);
+ *  2. graphddb validates every lowered component against `GRAPHDDB_CATALOG` —
+ *     the SAME {@link assertComponentsInCatalog} the spec emitter runs (SP1c),
+ *     covering the dynamic key-attribute / write record-family ports bc's
+ *     static schema check cannot enumerate;
+ *  3. the CQRS effect of every method is DERIVED from its graph
+ *     ({@link deriveContractEffect} — SP2/SP4; the author never declares it).
+ *
+ * @throws bc `AuthoringFailure` for a non-declarative body (native control
+ *   syntax, coercion, unknown/missing ports, …); an `Error` from the catalog
+ *   validation for an undeclared dynamic port.
+ */
+declare function publishBehaviors(cls: BehaviorClass, options?: PublishBehaviorsOptions): BehaviorModelContract;
+/** Runtime guard: is `value` a {@link BehaviorModelContract}? */
+declare function isBehaviorModelContract(value: unknown): value is BehaviorModelContract;
+
+export { type BehaviorModelContract as B, type PublishBehaviorsOptions as P, type BehaviorMethodSpec as a, type BehaviorComponentFns as b, behaviorComponents as c, isBehaviorModelContract as i, publishBehaviors as p };

package/dist/cdc/index.d.ts

@@ -1,7 +1,8 @@
-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';
+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';
 
 /**
  * CDC emulator (issue #72). Subscribes to the core write-capture seam

package/dist/cdc/index.js

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

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

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

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

@@ -227,10 +227,35 @@ var param = {
     const param2 = { kind: "array", element };
     if (options?.description !== void 0) param2.description = options.description;
     return param2;
+  },
+  /**
+   * A placeholder for a **map / embedded object** value written to a single
+   * DynamoDB `M` attribute (issue #295). Free-form by design: the model-side
+   * vocabulary (`@map` / `@embedded`) records no nested schema, so the param is
+   * typed as the language-native map in generated bindings (`dict` /
+   * `map[string]any` / `serde_json::Value` / `array`) while the optional type
+   * parameter `T` keeps the TS authoring surface precise.
+   *
+   * Legal at **value positions only** (a write descriptor's `input`, a
+   * transaction fragment value, a batch-write per-item payload field) — a map
+   * cannot compose a key, so a `param.map()` in a key position is rejected
+   * loudly at build time.
+   *
+   * @example
+   * ```ts
+   * putLeaf: {
+   *   upsert: TreeNode,
+   *   key: { part: param.string(), child: param.string() },
+   *   input: { value: param.map<AvgValue>(), computedAt: param.number() },
+   * }
+   * ```
+   */
+  map(options) {
+    return makeParam("map", void 0, options?.description);
   }
 };
 function isParam(value) {
-  return typeof value === "object" && value !== null && "kind" in value && (value.kind === "string" || value.kind === "number" || value.kind === "literal" || value.kind === "array");
+  return typeof value === "object" && value !== null && "kind" in value && (value.kind === "string" || value.kind === "number" || value.kind === "literal" || value.kind === "array" || value.kind === "map");
 }
 
 // src/client/lib-dynamodb.ts
@@ -337,17 +362,220 @@ async function executeBatchGet(docClient, operation) {
   return { items: allItems };
 }
 
+// src/spec/catalog.ts
+import { classifyBehaviorEffect } from "behavior-contracts";
+var P = (type, required) => required ? { type, required } : { type };
+var READ_PORTS = {
+  table: P("string", true),
+  indexName: P("string"),
+  rangeKey: P("string"),
+  rangeOperator: P("string"),
+  rangeValue: P("expr"),
+  limit: P("number"),
+  filter: P("string"),
+  projection: P("string[]", true),
+  implicitSourceField: P("string")
+};
+var WRITE_PORTS = {
+  table: P("string", true),
+  entity: P("string", true),
+  literalKey: P("boolean"),
+  maintain: P("string"),
+  "condition.kind": P("string"),
+  "condition.field": P("string"),
+  "condition.declarative": P("string"),
+  "condition.expression": P("string"),
+  "condition.names": P("string")
+};
+var entry = (name, inputPorts, shape, portableToIR) => ({
+  name,
+  inputPorts,
+  output: { shape },
+  portableToIR,
+  // Dynamic port families (key-attribute / write record ports) are validated by
+  // assertComponentsInCatalog, not statically enumerable — see the module doc
+  // ("Dynamic-port opt-in"). TransactWrite overrides this back to fail-closed.
+  additionalPorts: true
+});
+var GRAPHDDB_CATALOG = {
+  GetItem: entry("GetItem", READ_PORTS, "item", true),
+  Query: entry(
+    "Query",
+    // `cardinality: 'one'` is the root-collapse port only the Query root emits.
+    { ...READ_PORTS, cardinality: P("string") },
+    "items",
+    true
+  ),
+  BatchGetItem: entry("BatchGetItem", READ_PORTS, "items", true),
+  PutItem: entry("PutItem", WRITE_PORTS, "item", true),
+  UpdateItem: entry("UpdateItem", WRITE_PORTS, "item", true),
+  DeleteItem: entry("DeleteItem", WRITE_PORTS, "item", true),
+  ConditionCheck: entry("ConditionCheck", WRITE_PORTS, "item", true),
+  // The executor-side atomic envelope: never referenced by the portable IR
+  // (a transaction IS a component over the item primitives) — TS-runtime-only.
+  // Its single port is static, so it keeps bc's fail-closed default (no
+  // additionalPorts opt-in).
+  TransactWrite: {
+    ...entry("TransactWrite", { TransactItems: P("map[]", true) }, "item", false),
+    additionalPorts: false
+  }
+};
+function catalogEntry(name) {
+  return GRAPHDDB_CATALOG[name];
+}
+var CATALOG_NAMES = [
+  "GetItem",
+  "Query",
+  "BatchGetItem",
+  "PutItem",
+  "UpdateItem",
+  "DeleteItem",
+  "ConditionCheck",
+  "TransactWrite"
+];
+var WRITE_CATALOG_NAMES = [
+  "PutItem",
+  "UpdateItem",
+  "DeleteItem",
+  "ConditionCheck",
+  "TransactWrite"
+];
+var WRITE_SET = new Set(WRITE_CATALOG_NAMES);
+var KEY_ATTR_PORT = /^[A-Za-z0-9_]*(?:PK|SK)$/;
+var WRITE_PORT_FAMILIES = [
+  "item.",
+  "key.",
+  "changes.",
+  "add.",
+  "condition.equals.",
+  "condition.params.",
+  "condition.values."
+];
+function assertComponentsInCatalog(components) {
+  const errs = [];
+  for (const c of components) {
+    for (const n of c.body) {
+      if ("cond" in n) continue;
+      const ref = "map" in n ? n.map : n;
+      const entryDef = GRAPHDDB_CATALOG[ref.component];
+      if (entryDef === void 0) {
+        errs.push(`${c.name}/${n.id}: references '${ref.component}', not a GRAPHDDB_CATALOG entry (known: ${CATALOG_NAMES.join(", ")})`);
+        continue;
+      }
+      const ports = ref.ports;
+      for (const [p, s] of Object.entries(entryDef.inputPorts)) {
+        if (s.required === true && !(p in ports)) {
+          errs.push(`${c.name}/${n.id} (${ref.component}): required port '${p}' is not wired`);
+        }
+      }
+      const isWriteItem = WRITE_SET.has(ref.component);
+      for (const p of Object.keys(ports)) {
+        if (p in entryDef.inputPorts) continue;
+        if (isWriteItem ? WRITE_PORT_FAMILIES.some((f) => p.startsWith(f)) : KEY_ATTR_PORT.test(p)) continue;
+        errs.push(`${c.name}/${n.id} (${ref.component}): port '${p}' is not declared by the catalog entry (nor a ${isWriteItem ? "write record-family" : "key-attribute"} port)`);
+      }
+    }
+  }
+  if (errs.length > 0) {
+    throw new Error(`graphddb catalog validation failed (${errs.length} violation${errs.length === 1 ? "" : "s"}):
+ - ${errs.join("\n - ")}`);
+  }
+}
+function deriveContractEffect(component) {
+  return classifyBehaviorEffect(component, WRITE_CATALOG_NAMES) === "writing" ? "command" : "query";
+}
+function deriveComponentEffects(components) {
+  const out = /* @__PURE__ */ new Map();
+  for (const c of components) out.set(c.name, deriveContractEffect(c));
+  return out;
+}
+function assertPublishSplitMatchesDerived(derived, split, contracts) {
+  const errs = [];
+  const check = (name, declared, at) => {
+    const truth = derived.get(name);
+    if (truth === void 0) {
+      errs.push(`${at}: no emitted component '${name}'`);
+      return;
+    }
+    if (truth !== declared) {
+      const verb = declared === "query" ? "publishQuery" : "publishCommand";
+      const fix = truth === "command" ? "publishCommand" : "publishQuery";
+      errs.push(
+        `${at}: published under ${verb} (declares '${declared}') but component '${name}' derives '${truth}' from its graph \u2014 the component graph is the source of truth; publish it with ${fix}`
+      );
+    }
+  };
+  for (const name of derived.keys()) {
+    if (split.behaviors.has(name)) continue;
+    if (split.queries.has(name)) check(name, "query", "components");
+    else if (split.transactions.has(name)) check(name, "command", "components");
+    else errs.push(`components: '${name}' has no declared publish origin (queries / transactions / behaviors) to verify against`);
+  }
+  for (const [cname, contract] of Object.entries(contracts)) {
+    for (const [mname, m] of Object.entries(contract.methods)) {
+      const at = `contract ${cname}.${mname}`;
+      if (contract.kind === "query") {
+        const q = m;
+        if (!split.queries.has(q.operation)) errs.push(`${at}: operation '${q.operation}' is not in queries`);
+        else check(q.operation, "query", at);
+      } else {
+        const cm = m;
+        for (const target of [cm.single, cm.batch]) {
+          if (target === void 0) continue;
+          if (target.mode === "transaction" || target.mode === "batchWrite") {
+            if (!split.transactions.has(target.transaction)) errs.push(`${at}: transaction '${target.transaction}' is not in transactions`);
+            else check(target.transaction, "command", at);
+          } else if (!split.commands.has(target.operation)) {
+            errs.push(`${at}: operation '${target.operation}' is not in commands`);
+          }
+        }
+        if (cm.returnSelection !== void 0) check(`${cname}__${mname}__readback`, "query", `${at} readback`);
+      }
+    }
+  }
+  if (errs.length > 0) {
+    throw new Error(
+      `graphddb CQRS classification: the declared publish split contradicts the graph-derived truth (${errs.length}):
+ - ${errs.join("\n - ")}`
+    );
+  }
+}
+
+// src/executor/handler-registry.ts
+function resolveReadHandler(registry, name) {
+  const handler = registry[name];
+  if (handler === void 0) {
+    throw new Error(
+      `graphddb handler registry: no handler bound for catalog component '${name}' (known: ${Object.keys(registry).join(", ")})`
+    );
+  }
+  return handler;
+}
+function assertHandlersInCatalog(registry) {
+  for (const name of Object.keys(registry)) {
+    if (catalogEntry(name) === void 0) {
+      throw new Error(
+        `graphddb handler registry: handler '${name}' has no catalog entry (every bound handler must declare a Port schema in GRAPHDDB_CATALOG)`
+      );
+    }
+  }
+}
+
 // src/executor/dynamo-executor.ts
+var READ_HANDLERS = {
+  GetItem: (docClient, operation) => executeGetItem(docClient, operation),
+  Query: (docClient, operation) => executeQuery(docClient, operation),
+  BatchGetItem: (docClient, operation) => {
+    const op = operation;
+    return executeBatchGet(docClient, op);
+  }
+};
+assertHandlersInCatalog(READ_HANDLERS);
 var DynamoExecutor = class {
   async execute(operation, _options) {
     const docClient = await ClientManager.getDocumentClient();
-    if (operation.type === "GetItem") {
-      return executeGetItem(docClient, operation);
-    }
-    if (operation.type === "BatchGetItem") {
-      return this.batchGet(operation);
-    }
-    return executeQuery(docClient, operation);
+    const handler = resolveReadHandler(READ_HANDLERS, operation.type);
+    return handler(docClient, operation);
   }
   async batchGet(input, _options) {
     const docClient = await ClientManager.getDocumentClient();
@@ -1842,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,
@@ -1862,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) {
@@ -2448,6 +2691,11 @@ export {
   isParam,
   BATCH_GET_MAX_KEYS,
   chunkArray,
+  GRAPHDDB_CATALOG,
+  assertComponentsInCatalog,
+  deriveContractEffect,
+  deriveComponentEffects,
+  assertPublishSplitMatchesDerived,
   ClientManager,
   isRawCondition,
   cond,