graphddb 0.9.1 → 0.9.3

package/README.md

@@ -1,41 +1,63 @@
 # GraphDDB
 
-**Build GraphQL-like queries directly on DynamoDB —— while keeping every access pattern explicit.**
+**Portable, contract-first DynamoDB access patterns.**
 
-GraphDDB is a type-safe Runtime that maps DynamoDB's native access patterns onto a GraphQL-like query
-model. PK / GSI / projection / relation / cursor / operation limits are all kept visible rather than hidden.
-It is not an ORM —— it is for **defining, validating, and executing** DynamoDB access patterns through
-TypeScript types.
+GraphDDB lets you define your DynamoDB access patterns once in TypeScript, validate them at build time,
+inspect the exact execution plan before anything runs, and execute the *same* contract from five
+languages — TypeScript, Python, Rust, Go, and PHP. It is **not an ORM**: it is a contract compiler +
+runtime for explicit DynamoDB access patterns.
 
-## ✨ Features
+The access patterns become a portable, executable artifact. TypeScript is the single source of truth;
+a static planner lowers each contract to a language-neutral IR (`manifest.json` + `operations.json`),
+and every language runtime executes that IR with results pinned **byte-identical** by a shared
+conformance suite. GraphQL-like traversal is one of the authoring surfaces — ergonomic, but not the
+point. The point is that PK / GSI / projection / relation / cursor / operation limits stay explicit,
+verifiable, and portable rather than hidden behind an abstraction.
+
+## ✨ What GraphDDB does — in three layers
+
+**1. Define** explicit DynamoDB access patterns
 
 - ✅ **Type-safe models** —— the TS class is the single source of truth. Keys / GSIs / field types are checked at compile time.
-- ✅ **Graph-style traversal** —— nest `@hasMany` / `@belongsTo` / `@hasOne` inside `select`.
-- ✅ **Automatic access-pattern resolution** —— the runtime picks the PK / GSI from the fields you give.
-- ✅ **Projection** —— only `select`ed fields are read, and only those appear in the result type.
-- ✅ **Execution plan (Explain)** —— inspect the execution plan before touching DynamoDB.
-- ✅ **CQRS contracts** —— public Query/Command contracts (N+1-safe, context boundaries).
-- ✅ **Python generation** —— generate a Python client + runtime from TS as the SSoT (conformance-verified).
-- ✅ **Testing adapter** —— unit-test planner / traversal / transaction / CDC with an in-memory executor.
-- ✅ **Middleware** —— host-side hooks for reads / writes (logging, tenant, authorization).
-- ✅ **CDC emulator** —— drive and test change events equivalent to DynamoDB Streams locally.
-- ✅ **CDC projection** —— `@cdcProjected()` + `fromChange` / `subscribe` parse CDC change events into typed records (sink delivery / idempotency stay with the consumer).
-- ✅ **Maintained access paths** —— keep embedded snapshots / aggregate counters synchronized atomically.
-- ✅ **CloudFormation generation** —— emit a CloudFormation template for the DynamoDB table(s) a model set maps onto (GSI union / Streams / TTL / PITR / TableClass / SSE / PROVISIONED / Auto Scaling).
-- ✅ **Docs generation** —— generate a model specification (Markdown + Mermaid) from the TS models; templates are Handlebars and user-overridable.
+- ✅ **Graph-style traversal** —— nest `@hasMany` / `@belongsTo` / `@hasOne` inside `select` (an ergonomic authoring surface — arguments → key lookup, selection → projection).
+- ✅ **CQRS contracts** —— public Query/Command contracts as the read/write authoring surface (N+1-safe, context boundaries, composition across contracts).
+- ✅ **Maintained access paths** —— declare embedded snapshots / aggregate counters kept synchronized atomically with the source write.
+
+**2. Validate & explain** before anything touches DynamoDB
+
+- ✅ **Compile-time safety** —— undefined relations, missing GSIs, limit-less lists, and over-depth traversals are rejected at compile time / by the linter — equally for human- and AI-written code.
+- ✅ **Execution plan (Explain)** —— `explain()` returns the exact DynamoDB operations, so RCU shape is inspectable up front.
+- ✅ **Automatic access-pattern resolution** —— the runtime picks the PK / GSI from the fields you give; `select`ed fields are the only ones read and the only ones in the result type.
+- ✅ **In-memory testing** —— unit-test planner / traversal / transaction / CDC with no Docker, no DynamoDB Local.
+
+**3. Execute the same contract, portably, from five languages**
+
+- ✅ **Portable executable IR** —— the static planner lowers each contract to a language-neutral bridge bundle (`manifest.json` + `operations.json`, a `components[]` graph on the shared behavior-contracts vocabulary).
+- ✅ **5 language runtimes** —— generate clients + runtimes for **Python / Rust / Go / PHP** (TypeScript runs the IR natively), all executing the same access patterns.
+- ✅ **5-language conformance** —— TS / Python / Rust / Go / PHP run the same cases against DynamoDB Local; CI pins the results **byte-identical**.
+
+**Operational surface** (all built on the layers above): **Middleware** (host-side read/write hooks) ·
+**CDC emulator** (local DynamoDB-Streams-equivalent change events) · **CDC projection**
+(`@cdcProjected()` + `fromChange` / `subscribe` into typed records) · **Prepared statements**
+(compile-once / execute-many, AOT static plans) · **CloudFormation generation** ·
+**Docs generation** (Markdown + Mermaid, Handlebars-overridable).
 
 ## 🤔 Philosophy
 
+- **Access patterns as portable contracts** —— an access pattern is defined once and becomes a
+  language-neutral, executable artifact. The same contract is validated, explained, and then executed
+  identically across languages, instead of being re-implemented per stack.
 - **Native DynamoDB access patterns** —— express access patterns directly in code instead of hiding them
   behind an ORM abstraction. Because PK / GSI, projection, and limits stay visible, the correct design
   becomes the easiest path.
-- **Graph-style traversal** —— GraphQL's query model (arguments → key lookup, selection → projection,
-  relation → Query/Get/BatchGet) corresponds naturally to DynamoDB's access patterns.
 - **Compile-time safety** —— undefined relations, missing GSIs, limit-less lists, and traversals exceeding
   the allowed depth are rejected before execution at compile time / by the linter. The same constraints
   apply equally to human-written and AI-generated code.
 - **Runtime transparency** —— the runtime is not a black box. `explain()` shows the execution plan, and the
   plan reveals the shape of RCU usage.
+- **Graph-style traversal is a surface, not the essence** —— GraphQL's query model (arguments → key
+  lookup, selection → projection, relation → Query/Get/BatchGet) is a convenient way to *author* access
+  patterns; the essence is the explicit, portable contract underneath.
 
 ## 📦 Install
 
@@ -57,7 +79,7 @@ Node.js ≥ 22 is required.
 ## 🚀 Quick Start
 
 ```ts
-import { DDBModel, model, string, key, k } from 'graphddb';
+import { DDBModel, graphddb, model, string, key, k } from 'graphddb';
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 
 @model({ table: 'AppTable', prefix: 'USER' })
@@ -200,8 +222,16 @@ Each capability is summarized here only. For details, operator lists, and proced
   authorization scoping). Host-only and non-serialized. For hook points, see [`docs/middleware.md`](./docs/middleware.md).
 - **Class hydration** —— `options.hydrate` loads read results into host-language domain objects (opt-in,
   Phase 1: `query` top level). [`docs/class-hydration.md`](./docs/class-hydration.md).
-- **Python bridge** —— generate a Python client + runtime with TS as the SSoT, kept in step by a TS↔Python
-  conformance suite. [`docs/python-bridge.md`](./docs/python-bridge.md).
+- **Multi-language bridge** —— generate Python / Rust / Go / PHP clients + runtimes with TS as the SSoT,
+  kept in step by a 5-language conformance suite. [`docs/python-bridge.md`](./docs/python-bridge.md).
+- **Prepared statements** —— `graphddb.prepare($ => ({...}))` → `.execute(params)` (unified read/write).
+  "Contract-free precompilation": compile a declarative route once and execute it repeatedly with
+  different params. With the **true build-time compilation (AOT)** of `graphddb transform prepared
+  --aot`, plans are emitted as static artifacts and zero runtime compilation happens, including the
+  first call (a stale plan is loud-rejected at load; drift is caught in CI). Without the transform,
+  behavior stays identical through the lazy-slot + structural-memoization fallback. no-runtime-capture
+  is loudly enforced by a build-time lint + a runtime guard.
+  [`docs/prepared-statements.md`](./docs/prepared-statements.md).
 - **CQRS contracts** —— public Query/Command contracts (cardinality matrix, N+1 safety, context boundaries,
   composition across contracts). [`docs/cqrs-contract.md`](./docs/cqrs-contract.md) /
   [`docs/mutation-command-derivation.md`](./docs/mutation-command-derivation.md).
@@ -212,6 +242,17 @@ 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
+  `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
+  (`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
   the DynamoDB table(s) a model set maps onto (GSI union / Streams / TTL / PITR / PROVISIONED / Auto
   Scaling). [`docs/cloudformation.md`](./docs/cloudformation.md).
@@ -232,10 +273,11 @@ documentation available offline at hand. On GitHub, follow the links in the tabl
 | [Specification](./docs/spec.md) | Core API: entities, structured keys/GSIs, query/filter, relations, batch/transaction, design rules, runtime behavior. |
 | [Design patterns](./docs/design-patterns.md) | Mapping representative DynamoDB design patterns onto graphddb features (how to declare `pattern` / `@model({ kind })` + `@maintainedFrom` / `@aggregate`, read & write maintenance, per-phase coverage). |
 | [Middleware / Hooks](./docs/middleware.md) | The `graphddb.config.use` host-side middleware: hook points read R1–R5 / write W1–W5, `{ context }`, ordering. |
+| [Prepared statements](./docs/prepared-statements.md) | `graphddb.prepare` / `.execute` (unified read/write prepared statements), the no-runtime-capture constraint, `graphddb transform prepared` (AOT static plans / compile-time hoisting + build-time lint + drift detection): choosing between the 3 tiers AOT > lazy slot + structural memoization > ad-hoc. |
 | [CQRS contract layer](./docs/cqrs-contract.md) | Public Query/Command contracts, cardinality matrix, N+1 safety, composition across contracts, context boundaries. |
 | [Mutation → command derivation](./docs/mutation-command-derivation.md) | The internal write-plan composition DSL behind the Command IF (`entityWrites`, fragment composition, derivation of atomic `TransactWriteItems`). |
 | [Class hydration](./docs/class-hydration.md) | Opt-in `options.hydrate` that loads read results into host objects (Phase 1: `query` top level). |
-| [Multi-language / Python bridge](./docs/python-bridge.md) | Code generation with TS as the SSoT and a Python runtime; TS↔Python conformance. |
+| [Multi-language bridge](./docs/python-bridge.md) | Code generation with TS as the SSoT and Python / Rust / Go / PHP runtimes; 5-language conformance. |
 | [In-memory test adapter](./docs/testing.md) | Docker-free in-process testing with `graphddb/testing` and `MemoryInspector`. |
 | [CDC emulator](./docs/cdc-emulator.md) | A change-event emulator for differential aggregation patterns (dev/test). |
 | [CDC projection](./docs/cdc-projection.md) | The `@cdcProjected()` + `fromChange` / `subscribe` typed-consumer-IF: a contract that parses CDC change events into typed records. Boundary (parse→typed is graphddb; subscription, sink delivery, idempotency are the consumer's). |
@@ -256,23 +298,30 @@ documentation available offline at hand. On GitHub, follow the links in the tabl
 
 A query travels from the TS Model through the Planner / Runtime to DynamoDB:
 
-```mermaid
-flowchart LR
-    M["TS Model<br/>Entity / Key / GSI / Relation"] --> P["Planner<br/>access pattern resolution / projection"]
-    P --> R["Runtime<br/>execute / retry / hydrate"]
-    R --> D[("DynamoDB")]
-```
+![Query execution pipeline: TS Model → Planner → Runtime → DynamoDB](./docs/diagrams/query-pipeline.en.svg)
 
-From the same TS Model (the SSoT), multiple targets are derived:
+From the same TS Model (the SSoT), multiple targets are derived. The language runtimes are fanned out to
+4 languages through the portable IR (the `components[]` graph in `manifest.json` + `operations.json`),
+and the execution results of all 5 languages — TS included — are pinned byte-identical by the
+conformance suite:
 
-```mermaid
-flowchart LR
-    M["TS Model (SSoT)"] --> RT["Runtime (TS)"]
-    M --> PY["Python client + runtime"]
-    M --> CQ["CQRS Contract"]
-    M --> CFN["CloudFormation template"]
-    M --> DOC["Model docs (Markdown + Mermaid)"]
-```
+![SSoT derivation: TS Model → TS runtime / portable IR → 4 language runtimes / CQRS / CloudFormation / docs](./docs/diagrams/ssot-derivation.en.svg)
+
+| Runtime | Package | Distribution |
+|---------|---------|--------------|
+| TypeScript | `graphddb` | npm |
+| Python | `graphddb-runtime` | PyPI |
+| Rust | `graphddb_runtime` | crates.io |
+| 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)):
+
+![The three 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`.
 
 ## 📄 License
 

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-U5WNYFHC.js}

@@ -1876,6 +1876,209 @@ 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 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 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 +2514,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 +2604,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 +2631,7 @@ function buildOperations(queries = {}, commands = {}, transactions = {}, contrac
   return {
     version: operationsSpecVersion(content),
     ...content,
-    ...components.length > 0 ? { components } : {}
+    ...annotatedComponents.length > 0 ? { components: annotatedComponents } : {}
   };
 }