@ductape/mcp 0.2.15 → 0.2.16

package/dist/index.js

@@ -805,7 +805,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   graph.dropConstraint [name: string]
   graph.listLabels []
   graph.listRelationshipTypes []
-  graph.createAction [{ graphTag, tag, name, query, params? }, productTag?]
+  graph.createAction [{ graphTag, name, description?, operation, query: { operation, options }, parameters: [{ name, path, defaultValue, type, description?, required? }] }, productTag?]
   graph.listActions  [graphTag?, productTag?]
   graph.getAction    [actionTag, graphTag?, productTag?]
   graph.updateAction [actionTag, updates, graphTag?, productTag?]
@@ -4716,9 +4716,51 @@ EXACT CODE-FIRST GRAPH CONTEXT:
   ctx.graph.deleteRelationship({ graph, id })
   ctx.graph.query<T>({ graph, action, params? })
   ctx.graph.execute<T>({ graph, action, input })
-  Every call must be inside ctx.step(). createNode/createRelationship are not projection upserts.
-  For replay-safe Neo4j projections, register a saved graph action whose Cypher uses MERGE and call
-  that action through ctx.graph.execute. Do not describe CREATE as idempotent.
+  Every call must be inside ctx.step(). Prefer the direct ctx.graph primitive that expresses the
+  operation. Saved actions are not generally preferred over createNode/updateNode/deleteNode,
+  relationship operations, or query; use a saved action only for a reusable parameterized operation
+  that the typed primitives cannot express. createNode/createRelationship are not projection upserts.
+
+SAVED GRAPH ACTION ASSET AND CLI CONTRACT:
+  Canonical project path:
+    ductape/graphs/<graph-tag>/actions/<action-tag>.action.json
+  action-tag is generated by lowercasing name, replacing non-alphanumerics with hyphens, and trimming
+  hyphens. Exactly one action object belongs in each file. Allowed top-level fields are graphTag,
+  name, description, operation, query, and parameters. Required fields are graphTag, name, operation,
+  query, and parameters. There is no persisted version field.
+
+  Example ductape/graphs/discovery-graph/actions/upsert-product-v1.action.json:
+  {
+    "graphTag": "discovery-graph",
+    "name": "Upsert Product V1",
+    "description": "Idempotently project one product by stable domain ID",
+    "operation": "executeRaw",
+    "query": {
+      "operation": "executeRaw",
+      "options": {
+        "query": "MERGE (p:Product {id: $productId}) SET p.name = $name, p.sourceVersion = $sourceVersion RETURN p",
+        "params": { "productId": null, "name": null, "sourceVersion": null }
+      }
+    },
+    "parameters": [
+      { "name": "productId", "path": "options.params.productId", "defaultValue": null, "type": "string", "required": true },
+      { "name": "name", "path": "options.params.name", "defaultValue": null, "type": "string", "required": true },
+      { "name": "sourceVersion", "path": "options.params.sourceVersion", "defaultValue": 0, "type": "number", "required": true }
+    ]
+  }
+  Validate without mutation:
+    ductape graph validateAction -f ductape/graphs/discovery-graph/actions/upsert-product-v1.action.json --json
+  Create and persist against the linked product:
+    ductape graph createAction -f ductape/graphs/discovery-graph/actions/upsert-product-v1.action.json --json
+  Read back with graph.getAction/listActions before relying on it. In-place updates use:
+    ductape graph updateAction -f <patch.json> --json
+  where patch.json is { "actionTag":"upsert-product-v1", "graphTag":"discovery-graph", "updates":{...} }.
+  Updating name does not change the stored tag. For breaking query/input/result changes, create a new
+  name/tag such as V2 and migrate callers; use updateAction for compatible corrections only.
+  ctx.graph.execute returns IExecuteGraphActionResult<T>: { success, executionTime, data: T[], count,
+  error? }. It resolves parameter values by each parameter.path. The SDK currently returns
+  success:false for action execution errors, so Feature code must inspect success and throw to fail
+  the step; do not treat a resolved unsuccessful result as success.
 
 EXACT CODE-FIRST VECTOR CONTEXT:
   ctx.vector.upsert<T>({
@@ -4738,9 +4780,40 @@ EXACT CODE-FIRST VECTOR CONTEXT:
   them into the Feature definition. Note the deliberate naming: ctx.vector.query uses values for
   the embedding, while the lower-level ductape.vector.query runtime facade uses vector.
   Vertex AI Vector Search stores and searches supplied vectors. It does NOT generate embeddings.
-  Generate embeddings through a separately registered/called model or App/function contract and
-  verify that the returned number[] dimension exactly matches the vector component. Do not claim
-  that a Vertex Vector Search index embeds text.
+  Do not claim that a Vertex Vector Search index embeds text.
+
+EMBEDDING EXECUTION — CURRENT CODE-FIRST CONTRACT:
+  Registered product models are configuration CRUD only in the current SDK. There is no ctx.model,
+  ctx.models, ctx.ai, or registered-model execute method, so never generate those calls. To execute
+  discovery-embeddings portably inside a Feature, define it as a portable function contract (preferred
+  for application-owned embedding code) or call an already registered App action via ctx.api.run.
+
+  import { defineFunctions } from '@ductape/sdk';
+  type EmbedInput = { texts: string[] };
+  type EmbedOutput = { embeddings: number[][]; dimensions: number; model: string };
+  export const DiscoveryEmbeddings = defineFunctions({
+    namespace: 'discovery-embeddings', version: '1', operations: { embed: {
+      input: { type:'object', required:['texts'], additionalProperties:false,
+        properties:{ texts:{ type:'array', items:{ type:'string', minLength:1 } } } },
+      output: { type:'object', required:['embeddings','dimensions','model'], additionalProperties:false,
+        properties:{ embeddings:{ type:'array', items:{ type:'array', items:{ type:'number' } } },
+          dimensions:{ type:'integer', minimum:1 }, model:{ type:'string', minLength:1 } } },
+      timeout_ms: 15000, idempotent: true, transports:[{ type:'local' }]
+    } } });
+
+  In the Feature handler:
+    const embeddings = ctx.functions.use(DiscoveryEmbeddings);
+    const generated = await ctx.step('embed-products', () =>
+      embeddings.embed({ texts: ctx.input.texts }));
+    if (generated.embeddings.length !== ctx.input.texts.length ||
+        generated.embeddings.some(v => v.length !== EXPECTED_VECTOR_DIMENSIONS)) {
+      throw new Error('EMBEDDING_DIMENSION_MISMATCH');
+    }
+  Register a real local handler at application bootstrap or configure a signed HTTPS/events transport.
+  Input and output JSON schemas are validated at runtime. Missing implementation fails with
+  FUNCTION_UNAVAILABLE; schema mismatch fails with FUNCTION_SCHEMA_VALIDATION_FAILED; timeout fails
+  with FUNCTION_TIMEOUT. Never substitute sample/random/recording-time embeddings. The Feature's
+  session is inherited in the portable function context, outside its business input.
 
 NESTJS CONSUMER ROUTING AND FEATURE INPUT:
   @Events.Consumer receives the published message object. Ductape may add

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.2.15",
+  "version": "0.2.16",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",