graphddb 0.7.7 → 0.7.9

package/dist/cli.js

@@ -3,10 +3,10 @@ import {
   buildBridgeBundle,
   buildManifest,
   buildOperations
-} from "./chunk-WPABX7WG.js";
+} from "./chunk-NYM7K2ST.js";
 import {
   MetadataRegistry
-} from "./chunk-F2DI3GTI.js";
+} from "./chunk-PFFPLD4B.js";
 import {
   createDefaultLinter
 } from "./chunk-PDUVTYC5.js";
@@ -1096,6 +1096,9 @@ function queryResultTypeName(queryName) {
 function txElementTypeName(txName, paramName) {
   return `${toPascalCase(txName)}${toPascalCase(paramName)}Item`;
 }
+function contractOperationId(contract, method) {
+  return `${contract}__${method}`;
+}
 function relationSegments(resultPath) {
   if (resultPath === "$") return [];
   const parts = resultPath.replace(/^\$\.?/, "").split(".");
@@ -1179,6 +1182,7 @@ function emitResultClasses(node, typeName, manifest, out, seen) {
       name: key,
       shape: "scalar",
       scalarType: manifestField?.type ?? "string",
+      ...manifestField?.format !== void 0 ? { scalarFormat: manifestField.format } : {},
       ...manifestField?.description !== void 0 ? { description: manifestField.description } : {}
     });
   }
@@ -1236,6 +1240,65 @@ function elementParamField(name, p) {
     ...p.literals !== void 0 ? { literals: p.literals } : {}
   };
 }
+function byContractOperationId(a, b) {
+  const ida = contractOperationId(a.contract, a.method);
+  const idb = contractOperationId(b.contract, b.method);
+  return ida < idb ? -1 : ida > idb ? 1 : 0;
+}
+function assertFreshTypeName(name, contract, method, seen) {
+  if (seen.has(name)) {
+    throw new Error(
+      `Contract '${contract}.${method}': generated result type name '${name}' collides with an already-generated type of the same name. Rename the contract method or the conflicting query so the generated type names are unique.`
+    );
+  }
+}
+function composeFields(compose) {
+  return compose.map((c) => ({
+    name: c.as,
+    shape: "optional-item",
+    itemType: queryResultTypeName(contractOperationId(c.contract, c.method))
+  }));
+}
+function appendFieldsToClass(out, className, extra) {
+  if (extra.length === 0) return;
+  const idx = out.findIndex((c) => c.name === className);
+  if (idx < 0) return;
+  const cls = out[idx];
+  const extraNames = new Set(extra.map((f) => f.name));
+  const fields = [...cls.fields.filter((f) => !extraNames.has(f.name)), ...extra].sort(
+    (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0
+  );
+  out[idx] = { ...cls, fields };
+}
+function contractQueryMethodSpec(operations, binding) {
+  const spec = operations.contracts?.[binding.contract]?.methods?.[binding.method];
+  if (!spec) {
+    throw new Error(
+      `Contract query binding '${binding.contract}.${binding.method}' is not present in operations.contracts \u2014 the binding surface must be derived from the same operations document.`
+    );
+  }
+  return spec;
+}
+function contractCommandMethodSpec(operations, binding) {
+  const spec = operations.contracts?.[binding.contract]?.methods?.[binding.method];
+  if (!spec || !("single" in spec)) {
+    throw new Error(
+      `Contract command binding '${binding.contract}.${binding.method}' is not present in operations.contracts \u2014 the binding surface must be derived from the same operations document.`
+    );
+  }
+  return spec;
+}
+function contractCommandParams(operations, binding, spec) {
+  const single = spec.single;
+  const params = single.mode === "transaction" ? operations.transactions?.[single.transaction]?.params : operations.commands[single.operation]?.params;
+  if (!params) {
+    const ref = single.mode === "transaction" ? `transaction '${single.transaction}'` : `command '${single.operation}'`;
+    throw new Error(
+      `Contract '${binding.contract}.${binding.method}': its single resolution target (${ref}) is not present in the operations document.`
+    );
+  }
+  return params;
+}
 function buildBindingModel(manifest, operations, options) {
   const queries = operations.queries;
   const commands = operations.commands;
@@ -1243,6 +1306,8 @@ function buildBindingModel(manifest, operations, options) {
   const queryEntityMap = new Map(options.queries.map((q) => [q.name, q.entity]));
   const queryNames = [...queryEntityMap.keys()].sort();
   const commandNames = new Set(options.commands);
+  const contractQueries = [...options.contractQueries ?? []].sort(byContractOperationId);
+  const contractCommands = [...options.contractCommands ?? []].sort(byContractOperationId);
   const entities = Object.keys(manifest.entities).sort().map((name) => {
     const meta = manifest.entities[name];
     return {
@@ -1266,6 +1331,42 @@ function buildBindingModel(manifest, operations, options) {
     for (const op of spec.operations) insertOperation(root, op, manifest);
     emitResultClasses(root, queryResultTypeName(queryName), manifest, resultClasses, seen);
   }
+  for (const q of contractQueries) {
+    const opId = contractOperationId(q.contract, q.method);
+    const spec = queries[q.operation];
+    if (!spec) {
+      throw new Error(
+        `Contract '${q.contract}.${q.method}': referenced operation '${q.operation}' is not present in operations.queries.`
+      );
+    }
+    const methodSpec = contractQueryMethodSpec(operations, q);
+    const cardinality = methodSpec.cardinality;
+    const resultName = queryResultTypeName(opId);
+    const recordName = cardinality === "many" ? `${resultName}Item` : resultName;
+    assertFreshTypeName(recordName, q.contract, q.method, seen);
+    if (cardinality === "many") assertFreshTypeName(resultName, q.contract, q.method, seen);
+    const root = {
+      entity: q.entity,
+      projection: [],
+      children: /* @__PURE__ */ new Map(),
+      implicitFields: /* @__PURE__ */ new Set()
+    };
+    for (const op of spec.operations) insertOperation(root, op, manifest);
+    emitResultClasses(root, recordName, manifest, resultClasses, seen);
+    appendFieldsToClass(resultClasses, recordName, composeFields(methodSpec.compose ?? []));
+    if (cardinality === "many") {
+      seen.add(resultName);
+      resultClasses.push({
+        name: resultName,
+        isConnection: true,
+        connectionItemType: recordName,
+        fields: [
+          { name: "items", shape: "optional-item", itemType: recordName },
+          { name: "cursor", shape: "scalar", scalarType: "string" }
+        ]
+      });
+    }
+  }
   emitTransactionElementTypes(transactions, resultClasses, seen);
   const byEntity = /* @__PURE__ */ new Map();
   const ensure = (entity) => {
@@ -1300,6 +1401,36 @@ function buildBindingModel(manifest, operations, options) {
       ...spec.description !== void 0 ? { description: spec.description } : {}
     });
   }
+  for (const q of contractQueries) {
+    const opId = contractOperationId(q.contract, q.method);
+    const spec = queries[q.operation];
+    const methodSpec = contractQueryMethodSpec(operations, q);
+    const description = methodSpec.description ?? queryDescription(q.operation, q.entity, spec, manifest);
+    ensure(q.entity).push({
+      operationId: opId,
+      kind: "query",
+      params: buildParams(spec.params),
+      resultType: queryResultTypeName(opId),
+      contract: q.contract,
+      contractMethod: q.method,
+      cardinality: methodSpec.cardinality,
+      contractKeyFields: operations.contracts[q.contract].key.fields,
+      ...description !== void 0 ? { description } : {}
+    });
+  }
+  for (const c of contractCommands) {
+    const opId = contractOperationId(c.contract, c.method);
+    const methodSpec = contractCommandMethodSpec(operations, c);
+    ensure(c.entity).push({
+      operationId: opId,
+      kind: "command",
+      params: buildParams(contractCommandParams(operations, c, methodSpec)),
+      contract: c.contract,
+      contractMethod: c.method,
+      contractKeyFields: operations.contracts[c.contract].key.fields,
+      ...methodSpec.description !== void 0 ? { description: methodSpec.description } : {}
+    });
+  }
   const repositories = [...byEntity.keys()].sort().map((className) => {
     const bucket = byEntity.get(className);
     return {
@@ -1416,7 +1547,7 @@ function resolveField(field, mapper) {
       type = field.isParamScalar ? mapper.paramScalar(
         field.scalarType === "number" ? "number" : field.literals ? "literal" : "string",
         field.literals
-      ) : mapper.scalar(field.scalarType ?? "string");
+      ) : mapper.scalar(field.scalarType ?? "string", field.scalarFormat);
       break;
   }
   return {
@@ -1441,6 +1572,7 @@ function resolveClass(cls, mapper) {
     return {
       name: cls.name,
       isConnection: true,
+      connectionItemType: cls.connectionItemType,
       fields: [items, cursor],
       ...cls.description !== void 0 ? { description: cls.description } : {}
     };
@@ -1471,11 +1603,36 @@ function resolveMethod(method, mapper) {
     operationId: method.operationId,
     kind: method.kind,
     params: method.params.map((p) => resolveParam(p, mapper)),
-    ...method.kind === "query" && method.resultType !== void 0 ? { returnType: mapper.optional(method.resultType) } : {},
+    // A query returns its result type optionally (it may miss) — except a
+    // contract RANGE read (#250, cardinality 'many'), which always returns its
+    // connection type (an empty result is a connection with zero items).
+    ...method.kind === "query" && method.resultType !== void 0 ? {
+      returnType: method.cardinality === "many" ? method.resultType : mapper.optional(method.resultType)
+    } : {},
+    // Contract identity + invocation facts (#250), passed through untouched so a
+    // language generator can render the entry-point call.
+    ...method.contract !== void 0 ? {
+      contract: method.contract,
+      contractMethod: method.contractMethod,
+      contractKeyFields: method.contractKeyFields ?? []
+    } : {},
+    ...method.cardinality !== void 0 ? { cardinality: method.cardinality } : {},
     ...method.description !== void 0 ? { description: method.description } : {}
   };
 }
-function resolveBindingView(model, mapper) {
+function assertContractCapable(model, language) {
+  for (const repo of model.repositories) {
+    for (const m of repo.methods) {
+      if (m.contract !== void 0) {
+        throw new Error(
+          `Binding model contains the contract-derived method '${m.contract}.${m.contractMethod}' (${m.operationId}), but the '${language}' renderer did not declare contract support (supportsContracts). Rendering it through the raw-op call would silently drop the contract execution semantics (composed fragments / ConditionCheck / compose fields / range connection) \u2014 add a contract entry-point branch to the renderer's templates and pass { supportsContracts: true }, or exclude contract methods from the binding surface.`
+        );
+      }
+    }
+  }
+}
+function resolveBindingView(model, mapper, options = {}) {
+  if (!options.supportsContracts) assertContractCapable(model, mapper.language);
   return {
     language: mapper.language,
     entities: model.entities,
@@ -1552,13 +1709,18 @@ from __future__ import annotations
 `;
 var REPO_METHOD = `    def {{methodName}}(self{{#if signature}}, {{signature}}{{/if}}) -> {{returnType}}:{{#if description}}
         """{{pyDoc description}}"""{{/if}}
-{{#if isQuery}}        return self._runtime.execute_query(
+{{#if contractName}}        {{#if isQuery}}return {{/if}}self._runtime.{{contractCall}}(
+            "{{contractName}}",
+            "{{contractMethod}}",
+            {{keyDict}},{{#if sharedDict}}
+            {{sharedDict}},{{/if}}
+        ){{else}}{{#if isQuery}}        return self._runtime.execute_query(
             query_id="{{operationId}}",
             params={{paramsDict}},
         ){{else}}        self._runtime.execute_command(
             command_id="{{operationId}}",
             params={{paramsDict}},
-        ){{/if}}`;
+        ){{/if}}{{/if}}`;
 var REPO_CLASS = `class {{name}}:
     def __init__(self, runtime: GraphDDBRuntime) -> None:
         self._runtime = runtime
@@ -1645,7 +1807,7 @@ function classContext(cls, isDataclass) {
   };
 }
 function methodContext(m) {
-  return {
+  const base = {
     methodName: toSnakeCase(m.operationId),
     signature: signatureOf(m.params),
     returnType: m.returnType ?? "None",
@@ -1654,6 +1816,18 @@ function methodContext(m) {
     paramsDict: paramsDictOf(m.params),
     ...m.description !== void 0 ? { description: m.description } : {}
   };
+  if (m.contract === void 0) return base;
+  const keyFields = new Set(m.contractKeyFields ?? []);
+  const keyParams = m.kind === "query" ? m.params : m.params.filter((p) => keyFields.has(p.name));
+  const sharedParams = m.kind === "query" ? [] : m.params.filter((p) => !keyFields.has(p.name));
+  return {
+    ...base,
+    contractName: m.contract,
+    contractMethod: m.contractMethod,
+    contractCall: m.kind === "query" ? "execute_query_method" : "execute_command_method",
+    keyDict: paramsDictOf(keyParams),
+    ...sharedParams.length > 0 ? { sharedDict: paramsDictOf(sharedParams) } : {}
+  };
 }
 function txMethodContext(m) {
   return {
@@ -1780,9 +1954,49 @@ function bindingSurface(queries, commands) {
     commands: Object.keys(commands)
   };
 }
+function fullBindingSurface(queries, commands, operations, contracts = {}) {
+  const base = bindingSurface(queries, commands);
+  const contractSpecs = operations.contracts ?? {};
+  const contractQueries = [];
+  const contractCommands = [];
+  for (const contractName of Object.keys(contractSpecs).sort()) {
+    const spec = contractSpecs[contractName];
+    const source = contracts[contractName];
+    if (!source) {
+      throw new Error(
+        `Contract '${contractName}' is present in the operations document but missing from the in-memory contract map \u2014 pass the same 'contracts' the bundle was built with to derive the binding surface.`
+      );
+    }
+    for (const methodName of Object.keys(spec.methods).sort()) {
+      const method = source.methods[methodName];
+      if (!method) {
+        throw new Error(
+          `Contract '${contractName}.${methodName}' is present in the operations document but missing from the in-memory contract \u2014 the two inputs must come from the same build.`
+        );
+      }
+      const entity = method.op.entity.name;
+      if (spec.kind === "query") {
+        const m = spec.methods[methodName];
+        contractQueries.push({
+          contract: contractName,
+          method: methodName,
+          operation: m.operation,
+          entity
+        });
+      } else {
+        contractCommands.push({ contract: contractName, method: methodName, entity });
+      }
+    }
+  }
+  return {
+    ...base,
+    ...contractQueries.length > 0 ? { contractQueries } : {},
+    ...contractCommands.length > 0 ? { contractCommands } : {}
+  };
+}
 function renderPythonBinding(manifest, operations, surface, options = {}) {
   const model = buildBindingModel(manifest, operations, surface);
-  const view = resolveBindingView(model, PythonTypeMapper);
+  const view = resolveBindingView(model, PythonTypeMapper, { supportsContracts: true });
   return {
     "types.py": renderTypesFile(view, options),
     "repositories.py": renderRepositoriesFile(view, options),
@@ -1794,7 +2008,8 @@ function renderPythonBinding(manifest, operations, surface, options = {}) {
 var PHP_NUMBER = "int|float";
 var PhpTypeMapper = {
   language: "php",
-  scalar(type) {
+  scalar(type, format) {
+    if (format === "datetime" || format === "date") return "\\DateTimeImmutable";
     switch (type) {
       case "number":
       case "numberSet":
@@ -1892,10 +2107,13 @@ final class {{name}}
 }`;
 var REPO_METHOD2 = `{{docblock}}    public function {{methodName}}({{signature}}): {{returnType}}
     {
-{{#if isQuery}}        $result = $this->runtime->executeQuery('{{operationId}}', {{paramsArray}});
+{{#if contractName}}{{#if isQuery}}        $result = $this->runtime->executeQueryMethod('{{contractName}}', '{{contractMethod}}', {{keyArray}});
+        return {{hydrateResult}};
+{{else}}        $this->runtime->executeCommandMethod('{{contractName}}', '{{contractMethod}}', {{keyArray}}{{#if sharedArray}}, {{sharedArray}}{{/if}});
+{{/if}}{{else}}{{#if isQuery}}        $result = $this->runtime->executeQuery('{{operationId}}', {{paramsArray}});
         return {{hydrateResult}};
 {{else}}        $this->runtime->executeCommand('{{operationId}}', {{paramsArray}});
-{{/if}}    }`;
+{{/if}}{{/if}}    }`;
 var REPO_CLASS2 = `/**
  * Typed repository for the {{entity}} entity, wrapping a {@see GraphDDBRuntime}.
  */
@@ -2042,14 +2260,14 @@ function dtoUses(cls, allClassNames) {
 }
 function connectionItemType(cls) {
   if (!cls.isConnection) return void 0;
-  return cls.name.replace(/Connection$/, "");
+  return cls.connectionItemType ?? cls.name.replace(/Connection$/, "");
 }
 function hydrateResultExpr(returnType) {
   const result = returnType.startsWith("?") ? returnType.slice(1) : returnType;
   return `$result === null ? null : ${result}::fromArray($result)`;
 }
 function methodContext2(method, metas, description) {
-  return {
+  const base = {
     methodName: toCamelCase(method.operationId),
     signature: signatureOf2(method.params),
     returnType: method.returnType ?? "void",
@@ -2057,7 +2275,21 @@ function methodContext2(method, metas, description) {
     operationId: method.operationId,
     paramsArray: paramsArrayOf(method.params),
     docblock: docblockOf(method, metas, description),
-    hydrateResult: method.returnType ? hydrateResultExpr(method.returnType) : ""
+    // A contract RANGE read (#250, cardinality 'many') always returns its
+    // connection (non-nullable), so it hydrates unconditionally; every other
+    // query hydrates through the null check.
+    hydrateResult: method.returnType ? method.cardinality === "many" ? `${method.returnType}::fromArray($result)` : hydrateResultExpr(method.returnType) : ""
+  };
+  if (method.contract === void 0) return base;
+  const keyFields = new Set(method.contractKeyFields ?? []);
+  const keyParams = method.kind === "query" ? method.params : method.params.filter((p) => keyFields.has(p.name));
+  const sharedParams = method.kind === "query" ? [] : method.params.filter((p) => !keyFields.has(p.name));
+  return {
+    ...base,
+    contractName: method.contract,
+    contractMethod: method.contractMethod,
+    keyArray: paramsArrayOf(keyParams),
+    ...sharedParams.length > 0 ? { sharedArray: paramsArrayOf(sharedParams) } : {}
   };
 }
 function txMethodContext2(method, metas) {
@@ -2113,8 +2345,21 @@ function buildParamMetaIndex(operations, surface) {
   for (const [name, spec] of Object.entries(operations.transactions ?? {})) {
     record(name, spec.params ?? {});
   }
+  recordContractMetas(index, operations, surface, record);
   return index;
 }
+function recordContractMetas(index, operations, surface, record) {
+  for (const q of surface.contractQueries ?? []) {
+    const spec = operations.queries[q.operation];
+    if (spec) record(contractOperationId(q.contract, q.method), spec.params ?? {});
+  }
+  for (const c of surface.contractCommands ?? []) {
+    const methodSpec = operations.contracts?.[c.contract]?.methods?.[c.method];
+    const single = methodSpec && "single" in methodSpec ? methodSpec.single : void 0;
+    const params = single === void 0 ? void 0 : single.mode === "transaction" ? operations.transactions?.[single.transaction]?.params : operations.commands[single.operation]?.params;
+    if (params) record(contractOperationId(c.contract, c.method), params);
+  }
+}
 function pascal(name) {
   return name.replace(/[_-]+/g, " ").replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/\s+/).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join("");
 }
@@ -2202,7 +2447,7 @@ function renderPhpFiles(view, index, options) {
 }
 function renderPhpBinding(manifest, operations, surface, options = {}) {
   const model = buildBindingModel(manifest, operations, surface);
-  const view = resolveBindingView(model, PhpTypeMapper);
+  const view = resolveBindingView(model, PhpTypeMapper, { supportsContracts: true });
   const index = buildParamMetaIndex(operations, surface);
   return renderPhpFiles(view, index, options);
 }
@@ -2266,7 +2511,19 @@ pub struct {{name}} {
     pub cursor: Option<String>,
 }`;
 var REPO_METHOD3 = `{{docComment}}    pub async fn {{methodName}}(&self{{#if signature}}, {{signature}}{{/if}}) -> {{returnType}} {
-{{paramsStmts}}{{#if isQuery}}        let value = self.runtime.execute_query("{{operationId}}", &params).await?;
+{{#if contractName}}{{keyStmt}}{{sharedStmts}}{{#if isQuery}}        let value = self.runtime.execute_query_method("{{contractName}}", "{{contractMethod}}", &key, {{paramsExpr}}).await?;
+{{#if isRange}}        let typed = serde_json::from_value(value)
+            .map_err(|e| GraphDDBError::hydration(format!("cannot deserialize {{operationId}} result: {e}")))?;
+        Ok(typed)
+{{else}}        if value.is_null() {
+            return Ok(None);
+        }
+        let typed = serde_json::from_value(value)
+            .map_err(|e| GraphDDBError::hydration(format!("cannot deserialize {{operationId}} result: {e}")))?;
+        Ok(Some(typed))
+{{/if}}{{else}}        self.runtime.execute_command_method("{{contractName}}", "{{contractMethod}}", &key, {{paramsExpr}}).await?;
+        Ok(())
+{{/if}}{{else}}{{paramsStmts}}{{#if isQuery}}        let value = self.runtime.execute_query("{{operationId}}", &params).await?;
         if value.is_null() {
             return Ok(None);
         }
@@ -2275,7 +2532,7 @@ var REPO_METHOD3 = `{{docComment}}    pub async fn {{methodName}}(&self{{#if sig
         Ok(Some(typed))
 {{else}}        self.runtime.execute_command("{{operationId}}", &params).await?;
         Ok(())
-{{/if}}    }`;
+{{/if}}{{/if}}    }`;
 var REPO_STRUCT = `/// Typed repository for the {{entity}} entity, wrapping a \`GraphDDBRuntime\`.
 #[derive(Clone)]
 pub struct {{name}} {
@@ -2376,6 +2633,16 @@ function buildParamMetaIndex2(operations, surface) {
   for (const [name, spec] of Object.entries(operations.transactions ?? {})) {
     record(name, spec.params ?? {});
   }
+  for (const q of surface.contractQueries ?? []) {
+    const spec = operations.queries[q.operation];
+    if (spec) record(contractOperationId(q.contract, q.method), spec.params ?? {});
+  }
+  for (const c of surface.contractCommands ?? []) {
+    const methodSpec = operations.contracts?.[c.contract]?.methods?.[c.method];
+    const single = methodSpec && "single" in methodSpec ? methodSpec.single : void 0;
+    const params = single === void 0 ? void 0 : single.mode === "transaction" ? operations.transactions?.[single.transaction]?.params : operations.commands[single.operation]?.params;
+    if (params) record(contractOperationId(c.contract, c.method), params);
+  }
   return index;
 }
 function metasFor2(index, opId, params) {
@@ -2398,7 +2665,7 @@ function fieldContext(field) {
 }
 function connectionItemType2(cls) {
   if (!cls.isConnection) return void 0;
-  return cls.name.replace(/Connection$/, "");
+  return cls.connectionItemType ?? cls.name.replace(/Connection$/, "");
 }
 function signatureOf3(params) {
   return params.map((p) => `${toSnakeCase2(p.name)}: ${p.type}`).join(", ");
@@ -2452,8 +2719,13 @@ function returnTypeOf(method) {
   }
   return "Result<(), GraphDDBError>";
 }
+function keyStmtOf(params) {
+  const entries = params.map((p) => `"${p.name}": ${toSnakeCase2(p.name)}`).join(", ");
+  return entries ? `        let key = json!({ ${entries} });
+` : "        let key = json!({});\n";
+}
 function methodContext3(method, metas) {
-  return {
+  const base = {
     methodName: toSnakeCase2(method.operationId),
     signature: signatureOf3(method.params),
     returnType: returnTypeOf(method),
@@ -2462,6 +2734,19 @@ function methodContext3(method, metas) {
     paramsStmts: paramsStmtsOf(method.params),
     docComment: methodDocComment(method, metas)
   };
+  if (method.contract === void 0) return base;
+  const keyFields = new Set(method.contractKeyFields ?? []);
+  const keyParams = method.kind === "query" ? method.params : method.params.filter((p) => keyFields.has(p.name));
+  const sharedParams = method.kind === "query" ? [] : method.params.filter((p) => !keyFields.has(p.name));
+  return {
+    ...base,
+    contractName: method.contract,
+    contractMethod: method.contractMethod,
+    keyStmt: keyStmtOf(keyParams),
+    sharedStmts: sharedParams.length > 0 ? paramsStmtsOf(sharedParams) : "",
+    paramsExpr: sharedParams.length > 0 ? "Some(&params)" : "None",
+    isRange: method.cardinality === "many"
+  };
 }
 function txMethodContext3(method, metas) {
   return {
@@ -2539,7 +2824,7 @@ function renderBody(view, index, engine) {
 }
 function renderRustBinding(manifest, operations, surface, options = {}) {
   const model = buildBindingModel(manifest, operations, surface);
-  const view = resolveBindingView(model, RustTypeMapper);
+  const view = resolveBindingView(model, RustTypeMapper, { supportsContracts: true });
   const index = buildParamMetaIndex2(operations, surface);
   const engine = engineOptions3(options);
   const body = renderBody(view, index, engine);
@@ -2611,7 +2896,29 @@ type {{name}} struct {
 	Cursor *string \`json:"cursor"\`
 }`;
 var REPO_METHOD4 = `{{docComment}}func (r *{{repoName}}) {{methodName}}(ctx context.Context{{#if signature}}, {{signature}}{{/if}}) {{returnType}} {
-{{paramsStmts}}{{#if isQuery}}	raw, err := r.runtime.ExecuteQuery(ctx, "{{operationId}}", params, nil)
+{{#if contractName}}{{keyStmts}}{{sharedStmts}}{{#if isQuery}}	raw, err := r.runtime.ExecuteQueryMethod(ctx, "{{contractName}}", "{{contractMethod}}", key, {{paramsArg}})
+{{#if isRange}}	var typed {{resultType}}
+	if err != nil {
+		return typed, err
+	}
+	if err := decodeResult(raw, &typed); err != nil {
+		return typed, err
+	}
+	return typed, nil
+{{else}}	if err != nil {
+		return nil, err
+	}
+	if item, ok := raw.(*graphddb_runtime.OMap); !ok || item == nil {
+		return nil, nil
+	}
+	var typed {{resultType}}
+	if err := decodeResult(raw, &typed); err != nil {
+		return nil, err
+	}
+	return &typed, nil
+{{/if}}{{else}}	_, err := r.runtime.ExecuteCommandMethod(ctx, "{{contractName}}", "{{contractMethod}}", key, {{paramsArg}})
+	return err
+{{/if}}{{else}}{{paramsStmts}}{{#if isQuery}}	raw, err := r.runtime.ExecuteQuery(ctx, "{{operationId}}", params, nil)
 	if err != nil {
 		return nil, err
 	}
@@ -2625,6 +2932,7 @@ var REPO_METHOD4 = `{{docComment}}func (r *{{repoName}}) {{methodName}}(ctx cont
 	return &typed, nil
 {{else}}	return r.runtime.ExecuteCommand(ctx, "{{operationId}}", params, nil)
 {{/if}}
+{{/if}}
 }`;
 var REPO_STRUCT2 = `// {{name}} is a typed repository for the {{entity}} entity, wrapping a *graphddb_runtime.GraphDDBRuntime.
 type {{name}} struct {
@@ -2760,6 +3068,16 @@ function buildParamMetaIndex3(operations, surface) {
   for (const [name, spec] of Object.entries(operations.transactions ?? {})) {
     record(name, spec.params ?? {});
   }
+  for (const q of surface.contractQueries ?? []) {
+    const spec = operations.queries[q.operation];
+    if (spec) record(contractOperationId(q.contract, q.method), spec.params ?? {});
+  }
+  for (const c of surface.contractCommands ?? []) {
+    const methodSpec = operations.contracts?.[c.contract]?.methods?.[c.method];
+    const single = methodSpec && "single" in methodSpec ? methodSpec.single : void 0;
+    const params = single === void 0 ? void 0 : single.mode === "transaction" ? operations.transactions?.[single.transaction]?.params : operations.commands[single.operation]?.params;
+    if (params) record(contractOperationId(c.contract, c.method), params);
+  }
   return index;
 }
 function metasFor3(index, opId, params) {
@@ -2775,7 +3093,7 @@ function fieldContext2(field) {
 }
 function connectionItemType3(cls) {
   if (!cls.isConnection) return void 0;
-  return cls.name.replace(/Connection$/, "");
+  return cls.connectionItemType ?? cls.name.replace(/Connection$/, "");
 }
 function signatureOf4(params) {
   return params.map((p) => `${toUnexported(p.name)} ${p.type}`).join(", ");
@@ -2808,12 +3126,25 @@ function methodDocComment2(methodName, description, params, metas) {
   });
   return renderDocComment2(lines, "");
 }
+function namedParamsStmtsOf(varName, params) {
+  if (params.length === 0) {
+    return `	${varName} := graphddb_runtime.Params{}
+`;
+  }
+  const lines = [`	${varName} := graphddb_runtime.Params{`];
+  for (const p of params) {
+    lines.push(`		"${p.name}": ${toUnexported(p.name)},`);
+  }
+  lines.push("	}");
+  return lines.map((l) => `${l}
+`).join("");
+}
 function methodContext4(repoName, method, metas) {
   const methodName = toExported(method.operationId);
   const isQuery = method.kind === "query";
   const resultType = isQuery && method.returnType ? method.returnType.replace(/^\*/, "") : "";
   const returnType = isQuery && method.returnType ? `(${method.returnType}, error)` : "error";
-  return {
+  const base = {
     repoName,
     methodName,
     signature: signatureOf4(method.params),
@@ -2824,6 +3155,19 @@ function methodContext4(repoName, method, metas) {
     paramsStmts: paramsStmtsOf2(method.params),
     docComment: methodDocComment2(methodName, method.description, method.params, metas)
   };
+  if (method.contract === void 0) return base;
+  const keyFields = new Set(method.contractKeyFields ?? []);
+  const keyParams = method.kind === "query" ? method.params : method.params.filter((p) => keyFields.has(p.name));
+  const sharedParams = method.kind === "query" ? [] : method.params.filter((p) => !keyFields.has(p.name));
+  return {
+    ...base,
+    contractName: method.contract,
+    contractMethod: method.contractMethod,
+    keyStmts: namedParamsStmtsOf("key", keyParams),
+    sharedStmts: sharedParams.length > 0 ? namedParamsStmtsOf("params", sharedParams) : "",
+    paramsArg: sharedParams.length > 0 ? "params" : "nil",
+    isRange: method.cardinality === "many"
+  };
 }
 function txMethodContext4(repoName, method, metas) {
   const methodName = toExported(method.transactionId);
@@ -2904,7 +3248,7 @@ function renderBody2(view, index, engine) {
 }
 function renderGoBinding(manifest, operations, surface, options = {}) {
   const model = buildBindingModel(manifest, operations, surface);
-  const view = resolveBindingView(model, GoTypeMapper);
+  const view = resolveBindingView(model, GoTypeMapper, { supportsContracts: true });
   const index = buildParamMetaIndex3(operations, surface);
   const engine = engineOptions4(options);
   const body = renderBody2(view, index, engine);
@@ -4078,7 +4422,12 @@ function renderBundle(queries = {}, commands = {}, registry = MetadataRegistry,
   const py = renderPythonBinding(
     bundle.manifest,
     bundle.operations,
-    bindingSurface(queries, commands),
+    fullBindingSurface(
+      queries,
+      commands,
+      bundle.operations,
+      options.contracts?.contracts ?? {}
+    ),
     {
       dataclass: options.dataclass,
       ...options.templateDir !== void 0 ? { templateDir: options.templateDir } : {},
@@ -4704,7 +5053,10 @@ var handlers = {
       const files = renderPhpBinding(
         bundle.manifest,
         bundle.operations,
-        bindingSurface(queries, commands),
+        // #250: the full binding surface (define* + user-facing contract
+        // methods); the PHP templates render contract methods through the
+        // contract entry points (executeQueryMethod / executeCommandMethod).
+        fullBindingSurface(queries, commands, bundle.operations, contracts),
         {
           ...templateDir !== void 0 ? { templateDir: isAbsolute(templateDir) ? templateDir : resolve3(process.cwd(), templateDir) } : {},
           ...helpers !== void 0 ? { helpers } : {}
@@ -4800,7 +5152,10 @@ var handlers = {
       const files = renderRustBinding(
         bundle.manifest,
         bundle.operations,
-        bindingSurface(queries, commands),
+        // #250: the full binding surface (define* + user-facing contract
+        // methods); the Rust templates render contract methods through the
+        // contract entry points (execute_query_method / execute_command_method).
+        fullBindingSurface(queries, commands, bundle.operations, contracts),
         {
           ...templateDir !== void 0 ? { templateDir: isAbsolute(templateDir) ? templateDir : resolve3(process.cwd(), templateDir) } : {},
           ...helpers !== void 0 ? { helpers } : {}
@@ -4898,7 +5253,10 @@ var handlers = {
       const files = renderGoBinding(
         bundle.manifest,
         bundle.operations,
-        bindingSurface(queries, commands),
+        // #250: the full binding surface (define* + user-facing contract
+        // methods); the Go templates render contract methods through the
+        // contract entry points (ExecuteQueryMethod / ExecuteCommandMethod).
+        fullBindingSurface(queries, commands, bundle.operations, contracts),
         {
           ...templateDir !== void 0 ? { templateDir: isAbsolute(templateDir) ? templateDir : resolve3(process.cwd(), templateDir) } : {},
           ...helpers !== void 0 ? { helpers } : {}