graphddb 0.9.2 → 1.0.0

package/README.md

@@ -242,15 +242,25 @@ Each capability is summarized here only. For details, operator lists, and proced
   `graphddb.subscribe(handlers)` (the sibling of `query` / `mutate`) produces a `ChangeHandler` the
   consumer mounts on its own stream. graphddb owns parse→typed record only; subscription, sink
   delivery, and idempotency are the consumer's. [`docs/cdc-projection.md`](./docs/cdc-projection.md).
-- **Multi-language codegen (the 3 paths, #257)** —— execution keeps 2 paths + 1 consumer surface,
-  coexisting permanently: (1) **dynamic JSON path (default)** — the `components[]` of
+- **Multi-language codegen** —— execution keeps 3 paths + 1 consumer surface, coexisting
+  permanently: (1) **dynamic JSON path (default)** — the `components[]` of
   `operations.json` are loaded at runtime and interpreted by the shared `run_behavior` (for swapping
   behavior without a deploy). (2) **codegen-static path (opt-in)** — `graphddb generate behaviors
   --lang <ts|python|go|rust|php>` hands the same IR to the **shared upstream behavior-contracts
-  generator** (bc#13), emitting modules with the IR baked in as native literals (graphddb owns only
-  envelope + invoke — no generation logic). A generated module checks its fingerprint against the
-  live registry and loud-rejects when stale (#208 discipline). Rust generated modules use
-  `std::sync::LazyLock`, so **Rust >= 1.80** is required. (3) **typed bindings
+  generator**, emitting modules with the IR baked in as native literals. Execution is still
+  interpreted by the shared `run_behavior` — **the per-op path is identical to the dynamic path**
+  (only the IR source differs; no native execution logic is generated). A generated module checks
+  its fingerprint against the live registry and loud-rejects when stale. Rust generated modules use
+  `std::sync::LazyLock`, so **Rust >= 1.80** is required. (3) **typed-native path — genuine
+  native-execution codegen (Go / Rust)** — `--typed-native` skips the interpreter entirely and
+  emits **native per-node execution code** (`run_native_raw_struct_<comp>`: direct field access on
+  concrete structs, a local error type, **no `run_behavior`, zero bc-runtime import**). Because the
+  generated code has the same shape a careful engineer hand-writes against the SDK (build key →
+  call → unmarshal into a struct → fan out), it runs at **SDK-floor parity** (≈0.9–1.05× the
+  hand-written SDK baseline in both Go and Rust) and **2–3× faster than the interpreter**.
+  Runtime-freeness is compiler-verified (`scripts/native-codegen-purity.mjs`); shapes not natively
+  coverable fail closed (never silently boxed); Rust can emit async (`ioModel=async`). Measured
+  results: [`benchmark/CROSS-LANG.md`](./benchmark/CROSS-LANG.md). (4) **typed bindings
   (`generate python/php/rust/go`)** — the consumer-UX surface (typed repositories / DTOs), still
   graphddb-owned; not an execution engine — it delegates to the paths above.
 - **CloudFormation generation** —— `graphddb generate cloudformation` emits a CloudFormation template for
@@ -315,10 +325,11 @@ conformance suite:
 | Go | `github.com/foo-log-inc/graphddb/go` | go module (`go/vX.Y.Z` tags) |
 | PHP | `graphddb/runtime` | bundled in-repo (not on composer) |
 
-Multi-language execution keeps 3 permanent paths — 2 execution paths + 1 consumer surface (see
-"Multi-language codegen" under [More Capabilities](#-more-capabilities)):
+Multi-language execution keeps 4 permanent paths — 3 execution paths (dynamic JSON /
+codegen-static / typed-native) + 1 consumer surface (see "Multi-language codegen" under
+[More Capabilities](#-more-capabilities)):
 
-![The three multi-language execution paths: authoring → static planner → portable IR → dynamic JSON / codegen-static / typed bindings](./docs/diagrams/execution-paths.en.svg)
+![The multi-language execution paths: authoring → static planner → portable IR → dynamic JSON / codegen-static / typed bindings](./docs/diagrams/execution-paths.en.svg)
 
 > The figures are self-contained SVGs drawn with diagram-contracts (Draw TSX).
 > Sources live in [`diagrams/`](./diagrams/); regenerate with `diagrams/build.sh`.

package/dist/cdc/index.d.ts

@@ -1,7 +1,7 @@
-import { w as CdcEmulatorOptions, x as ChangeHandler, y as Unsubscribe, F as FaultSpec, z as ConcurrentRecomputeRef, v as ChangeEvent, A as EventLog, G as ReplayOptions, H as ShardId, I as MaintainTrigger, E as EffectPath, g as ProjectionMap, j as MembershipPredicate } from '../key-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 { 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-C_6ScBbu.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-C_6ScBbu.js';
+import { E as EntityMetadata } from '../types-DLpvjjV_.js';
+import '../types-DGwo00JB.js';
 import 'behavior-contracts';
 
 /**

package/dist/{chunk-MBJ4JVRM.js → chunk-5NBQYFM5.js}

@@ -1876,6 +1876,237 @@ function portableIrDocument(components) {
   };
 }
 
+// src/spec/type-notation.ts
+import {
+  assertPortableComponentGraph
+} from "behavior-contracts";
+var UndeterminablePortableType = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UndeterminablePortableType";
+  }
+};
+function fieldTypeToPortable(fieldType, where) {
+  switch (fieldType) {
+    case "string":
+    case "binary":
+      return "string";
+    case "number":
+      return "float";
+    case "boolean":
+      return "bool";
+    case "stringSet":
+      return { arr: "string" };
+    case "numberSet":
+      return { arr: "float" };
+    case "list":
+    case "map":
+      throw new UndeterminablePortableType(
+        `type-notation: the '${fieldType}' field at ${where} has no portable type (a DynamoDB ${fieldType} attribute has no modeled element/record shape, and the portable type notation has no free-form/any type). The behavior is left untyped (byte-identical).`
+      );
+  }
+}
+var scalarType = fieldTypeToPortable;
+function relationSegments(nodeId) {
+  return nodeId.split(".").filter((p) => p !== "items");
+}
+function nodePorts(node) {
+  if ("map" in node) return node.map.ports;
+  if ("cond" in node) return void 0;
+  return node.ports;
+}
+function nodeComponent(node) {
+  if ("map" in node) return node.map.component;
+  if ("cond" in node) return void 0;
+  return node.component;
+}
+function mapIntoKey(node) {
+  return "map" in node ? node.map.into : void 0;
+}
+function resolveResultNode(root, nodeId) {
+  let tree = root;
+  for (const prop of relationSegments(nodeId)) {
+    tree = tree?.children.get(prop);
+    if (tree === void 0) return void 0;
+  }
+  return tree;
+}
+function isConnectionRootOp(rootComponent, cardinalityOne) {
+  return (rootComponent === "Query" || rootComponent === "BatchGetItem") && !cardinalityOne;
+}
+function nodeProjection(ports) {
+  const port = ports.projection;
+  return (port?.arr ?? []).filter((f) => typeof f === "string");
+}
+function insertNode(root, node, manifest, nodeById) {
+  const ports = nodePorts(node);
+  if (ports === void 0) return;
+  const segments = relationSegments(node.id);
+  if (segments.length === 0) return;
+  let tree = root;
+  let parent = root;
+  let entity = root.entity;
+  let kind = "single";
+  for (const prop of segments) {
+    parent = tree;
+    const relation = manifest.entities[entity]?.relations[prop];
+    if (relation === void 0) {
+      throw new Error(
+        `type-notation: relation segment '${prop}' of node has no relation on entity '${entity}'; cannot derive its result type. The components graph and the manifest have diverged.`
+      );
+    }
+    kind = relation.type === "hasMany" || relation.type === "refs" ? "connection" : "single";
+    const target = relation.target;
+    let child = tree.children.get(prop);
+    if (!child) {
+      child = {
+        entity: target,
+        projection: [],
+        children: /* @__PURE__ */ new Map(),
+        implicitFields: /* @__PURE__ */ new Set(),
+        relationKind: kind
+      };
+      tree.children.set(prop, child);
+    }
+    tree = child;
+    entity = target;
+  }
+  tree.projection = nodeProjection(ports);
+  tree.relationKind = kind;
+  nodeById.set(node.id, tree);
+  const implicit = ports.implicitSourceField;
+  if (typeof implicit === "string") parent.implicitFields.add(implicit);
+}
+function wrapRelation(childObj, kind) {
+  return kind === "connection" ? { obj: { cursor: { opt: "string" }, items: { arr: childObj } } } : { opt: childObj };
+}
+function nodeObjType(node, manifest, where, includeRelations) {
+  const meta = manifest.entities[node.entity];
+  const relationProps = new Set(node.children.keys());
+  const scalarFields = node.projection.filter(
+    (f) => !relationProps.has(f) && !node.implicitFields.has(f)
+  );
+  const fields = {};
+  for (const f of scalarFields) {
+    const ft = meta?.fields[f]?.type ?? "string";
+    fields[f] = scalarType(ft, `${where}.${f}`);
+  }
+  if (includeRelations) {
+    for (const [prop, child] of node.children) {
+      const childObj = nodeObjType(child, manifest, `${where}.${prop}`, true);
+      fields[prop] = wrapRelation(childObj, child.relationKind);
+    }
+  }
+  if (Object.keys(fields).length === 0) {
+    throw new UndeterminablePortableType(
+      `type-notation: result node at ${where} (entity '${node.entity}') projects no fields and has no relations \u2014 an empty record has no useful portable type; the behavior is left untyped.`
+    );
+  }
+  return { obj: fields };
+}
+function canonicalizeDeep(value) {
+  if (Array.isArray(value)) return value.map(canonicalizeDeep);
+  if (value !== null && typeof value === "object") {
+    const src = value;
+    const out = {};
+    for (const k of Object.keys(src).sort((a, b) => a < b ? -1 : a > b ? 1 : 0)) {
+      out[k] = canonicalizeDeep(src[k]);
+    }
+    return out;
+  }
+  return value;
+}
+function annotateQueryComponent(component, rootEntity, cardinalityOne, manifest) {
+  const root = {
+    entity: rootEntity,
+    projection: [],
+    children: /* @__PURE__ */ new Map(),
+    implicitFields: /* @__PURE__ */ new Set()
+  };
+  const rootNode = component.body.find((n) => n.id === "root");
+  if (rootNode !== void 0) {
+    const ports = nodePorts(rootNode);
+    if (ports !== void 0) root.projection = nodeProjection(ports);
+  }
+  const nodeById = /* @__PURE__ */ new Map();
+  for (const node of component.body) {
+    if (node.id === "root") continue;
+    insertNode(root, node, manifest, nodeById);
+  }
+  const annotatedBody = component.body.map((node) => {
+    if ("cond" in node) {
+      throw new Error(
+        `type-notation: unexpected 'cond' node '${node.id}' in query component '${component.name}'; query lowering does not emit conditionals, so its outType cannot be derived.`
+      );
+    }
+    if (node.id === "root") {
+      const outType2 = isConnectionRootOp(nodeComponent(node), cardinalityOne) ? wrapRelation(nodeObjType(root, manifest, `${component.name}.root`, true), "connection") : nodeObjType(root, manifest, `${component.name}.root`, false);
+      return { ...node, outType: outType2 };
+    }
+    const into = mapIntoKey(node);
+    if (into !== void 0) {
+      const mapParent = node.map.parent;
+      const parentNode = mapParent !== void 0 ? resolveResultNode(root, mapParent) : void 0;
+      if (parentNode === void 0) {
+        throw new Error(
+          `type-notation: map\u2026into node '${node.id}' in component '${component.name}' names parent '${String(mapParent)}', which has no result-tree node; cannot derive its augmented element type (fail-closed \u2014 the components graph and the manifest have diverged).`
+        );
+      }
+      const elemObj = nodeObjType(
+        parentNode,
+        manifest,
+        `${component.name}.${node.id}[into ${into}]`,
+        true
+      );
+      return { ...node, outType: { arr: elemObj } };
+    }
+    const rn = nodeById.get(node.id);
+    if (rn === void 0) {
+      throw new Error(
+        `type-notation: no result-tree node for body node '${node.id}' in component '${component.name}'; the model\u2192annotation walk is incomplete (fail-closed \u2014 not skipped).`
+      );
+    }
+    const obj = nodeObjType(rn, manifest, `${component.name}.${node.id}`, true);
+    const outType = wrapRelation(obj, rn.relationKind);
+    return { ...node, outType };
+  });
+  const hasRelations = root.children.size > 0;
+  const rootIsConnection = rootNode !== void 0 && isConnectionRootOp(nodeComponent(rootNode), cardinalityOne);
+  let outputType;
+  if (rootIsConnection) {
+    outputType = wrapRelation(nodeObjType(root, manifest, `${component.name}#output`, true), "connection");
+  } else if (!hasRelations) {
+    outputType = nodeObjType(root, manifest, `${component.name}#output.root`, false);
+  } else {
+    const rootObj = nodeObjType(root, manifest, `${component.name}#output.root`, false);
+    const fields = { root: rootObj };
+    for (const [prop, child] of root.children) {
+      const childObj = nodeObjType(child, manifest, `${component.name}#output.${prop}`, true);
+      fields[prop] = wrapRelation(childObj, child.relationKind);
+    }
+    outputType = { obj: fields };
+  }
+  return canonicalizeDeep({ ...component, body: annotatedBody, outputType });
+}
+function annotateComponents(components, typeFacts, manifest) {
+  const out = components.map((c) => {
+    const facts = typeFacts.get(c.name);
+    if (facts === void 0) return c;
+    try {
+      return annotateQueryComponent(c, facts.rootEntity, facts.cardinalityOne, manifest);
+    } catch (err) {
+      if (err instanceof UndeterminablePortableType) return c;
+      throw err;
+    }
+  });
+  assertPortableComponentGraph({
+    irVersion: 1,
+    exprVersion: EXPR_VERSION,
+    components: out
+  });
+  return out;
+}
+
 // src/spec/operations.ts
 function paramSpecs(params) {
   const out = {};
@@ -2311,6 +2542,9 @@ function buildQuerySpec(def) {
     operations,
     // operation 'query' → a single entity object; 'list' → a connection.
     cardinality: def.operation === "query" ? "one" : "many",
+    // The root model — the SSoT anchor for the bc#45 type-notation derivation
+    // (build-internal; dropped by toPortableQuery, so operations.json is unchanged).
+    entity: def.entity.name,
     ...executionPlan !== void 0 ? { executionPlan } : {},
     // Pure-documentation description (issue #154); absent → byte-identical spec.
     ...def.description !== void 0 ? { description: def.description } : {}
@@ -2398,6 +2632,15 @@ function buildOperations(queries = {}, commands = {}, transactions = {}, contrac
     },
     contractSpecs
   );
+  const typeFacts = /* @__PURE__ */ new Map();
+  for (const [name, spec] of Object.entries(querySpecs)) {
+    if (spec.entity === void 0) continue;
+    typeFacts.set(name, {
+      rootEntity: spec.entity,
+      cardinalityOne: spec.cardinality === "one"
+    });
+  }
+  const annotatedComponents = typeFacts.size > 0 ? annotateComponents(components, typeFacts, buildManifest()) : components;
   const portableQueries = {};
   for (const [name, spec] of Object.entries(querySpecs)) {
     portableQueries[name] = toPortableQuery(name, spec);
@@ -2416,7 +2659,7 @@ function buildOperations(queries = {}, commands = {}, transactions = {}, contrac
   return {
     version: operationsSpecVersion(content),
     ...content,
-    ...components.length > 0 ? { components } : {}
+    ...annotatedComponents.length > 0 ? { components: annotatedComponents } : {}
   };
 }