graphddb 0.8.0 → 0.9.0

package/dist/{chunk-L4QRCHRQ.js → chunk-WOFRHRXY.js}

@@ -1,8 +1,9 @@
 // src/spec/types.ts
 var SPEC_VERSION = "1.1";
 var SPEC_VERSION_SCP = "1.2";
-var SPEC_VERSION_SUPPORTED = SPEC_VERSION_SCP;
-var EXPR_VERSION = 1;
+var SPEC_VERSION_KEY_EXPR = "2.0";
+var SPEC_VERSION_SUPPORTED = SPEC_VERSION_KEY_EXPR;
+var EXPR_VERSION = 2;
 var MARKER_ROW_ENTITY = "__marker__";
 
 // src/define/transaction.ts
@@ -236,33 +237,14 @@ function canonicalizeExpressionSpec(input, context) {
 function isScpExprConditionInput(condition) {
   return "scpExpr" in condition;
 }
-function conditionHasScp(condition) {
-  return condition?.kind === "scpExpr";
-}
-function operationsContainScpNodes(doc) {
-  for (const command of Object.values(doc.commands)) {
-    if (conditionHasScp(command.condition)) return true;
-  }
-  for (const transaction of Object.values(doc.transactions ?? {})) {
-    for (const item of transaction.items) {
-      if (item.guard !== void 0 || conditionHasScp(item.condition)) return true;
-    }
-  }
-  for (const contract of Object.values(doc.contracts ?? {})) {
-    if (contract.kind !== "command") continue;
-    for (const method of Object.values(contract.methods)) {
-      if (method.guard !== void 0) return true;
-    }
-  }
-  return false;
-}
-function operationsSpecVersion(doc) {
-  return operationsContainScpNodes(doc) ? SPEC_VERSION_SCP : SPEC_VERSION;
+function operationsSpecVersion(_doc) {
+  return SPEC_VERSION_KEY_EXPR;
 }
 
 export {
   SPEC_VERSION,
   SPEC_VERSION_SCP,
+  SPEC_VERSION_KEY_EXPR,
   SPEC_VERSION_SUPPORTED,
   EXPR_VERSION,
   MARKER_ROW_ENTITY,
@@ -273,6 +255,5 @@ export {
   SCP_LOWERED_MARKER,
   canonicalizeExpressionSpec,
   isScpExprConditionInput,
-  operationsContainScpNodes,
   operationsSpecVersion
 };

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

@@ -17,7 +17,7 @@ import {
   normalizeTopLevelSelect,
   parseChange,
   validateInlineSnapshotSelect
-} from "./chunk-HNY2EJPV.js";
+} from "./chunk-KOIJ4SNO.js";
 import {
   EXPR_VERSION,
   MARKER_ROW_ENTITY,
@@ -26,7 +26,7 @@ import {
   isScpExprConditionInput,
   isTransactionDefinition,
   isTransactionRef
-} from "./chunk-L4QRCHRQ.js";
+} from "./chunk-WOFRHRXY.js";
 import {
   BATCH_GET_MAX_KEYS,
   CONDITION_OPERATOR_KEYS,
@@ -61,7 +61,7 @@ import {
   serializeFieldValue,
   serializeRawCondition,
   skTemplate
-} from "./chunk-L2NEDS7U.js";
+} from "./chunk-ZNU7OI5I.js";
 import {
   TableMapping,
   createColumnMap,
@@ -4669,16 +4669,40 @@ 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) {
   const resolved = {};
   for (const [name, body] of Object.entries(methods)) {
     if (isPublicWriteDescriptor(body)) {
-      const { plan: plan2, select, condition, mode, description } = writeDescriptorToPlan(name, body);
-      resolved[name] = finalizeDescriptorCommand(name, plan2, select, condition, mode, description);
+      const { plan: plan2, select, condition, mode, batchWriteEligible, description } = writeDescriptorToPlan(name, body);
+      resolved[name] = finalizeDescriptorCommand(
+        name,
+        plan2,
+        select,
+        condition,
+        mode,
+        description,
+        batchWriteEligible
+      );
+      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)) {
@@ -4708,7 +4732,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 };
@@ -4755,7 +4779,7 @@ function buildPlannedCommandMethod(name, planned) {
     ...returnSelection !== void 0 ? { returnSelection } : {}
   };
 }
-function finalizeDescriptorCommand(name, plan2, select, condition, mode, description) {
+function finalizeDescriptorCommand(name, plan2, select, condition, declaredMode, description, batchWriteEligible = false) {
   const planned = {
     [PLANNED_COMMAND_BRAND]: true,
     plan: plan2,
@@ -4763,6 +4787,13 @@ function finalizeDescriptorCommand(name, plan2, select, condition, mode, descrip
     select
   };
   const built = buildPlannedCommandMethod(name, planned);
+  const promoted = built.ops !== void 0 && built.ops.length > 1 || built.conditionChecks !== void 0 || built.edgeWrites !== void 0 || built.derivedUpdates !== void 0 || built.uniqueGuards !== void 0 || built.outboxEvents !== void 0 || built.idempotencyGuard !== void 0 || built.maintainWrites !== void 0 || built.maintainOutbox !== void 0;
+  if (declaredMode === "batchWrite" && (!batchWriteEligible || promoted)) {
+    throw new Error(
+      `publishCommand: method '${name}' declares mode: 'batchWrite', but DynamoDB's BatchWriteItem carries no ConditionExpression, no Update and no composed derived effects \u2014 only an UNCONDITIONAL put/delete qualifies (an \`upsert\` or a condition-free \`remove\` with no derived effects). This method is ${!batchWriteEligible ? "conditional / not an unconditional put/delete" : "promoted to an atomic TransactWriteItems by its derived effects"}. Use mode: 'transaction' (atomic TransactWriteItems, condition-capable, \u226425) \u2014 or the transaction forEach form for atomic per-item values.`
+    );
+  }
+  const mode = declaredMode ?? (batchWriteEligible && !promoted ? "batchWrite" : "transaction");
   const builtOp = built.op;
   const op = condition !== void 0 ? { ...builtOp, condition } : builtOp;
   return {
@@ -4801,6 +4832,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);
 }
@@ -4996,7 +5030,8 @@ function writeDescriptorToPlan(name, d) {
   });
   const select = d.result !== void 0 && d.result.select !== void 0 ? d.result.select : void 0;
   const condition = d.condition !== void 0 ? descriptorConditionRecord(d.condition, name) : void 0;
-  return { plan: plan2, select, condition, mode: d.mode ?? "transaction", description: d.description };
+  const batchWriteEligible = (intent === "upsert" || intent === "remove") && d.condition === void 0;
+  return { plan: plan2, select, condition, mode: d.mode, batchWriteEligible, description: d.description };
 }
 
 // src/spec/mutation-command.ts

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

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

package/dist/{chunk-L2NEDS7U.js → chunk-ZNU7OI5I.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();
@@ -2448,6 +2676,11 @@ export {
   isParam,
   BATCH_GET_MAX_KEYS,
   chunkArray,
+  GRAPHDDB_CATALOG,
+  assertComponentsInCatalog,
+  deriveContractEffect,
+  deriveComponentEffects,
+  assertPublishSplitMatchesDerived,
   ClientManager,
   isRawCondition,
   cond,