@ductape/mcp 0.2.14 → 0.2.16

package/CHANGELOG.md

@@ -6,6 +6,7 @@
 
 ## Unreleased
 
+- Added source-verified graph/vector projection guidance to the `features`, `events`, `graphs`, and `vector` docs topics, including exact graph/vector payloads, NestJS consumer routing, replay/idempotency, projection-state ordering, rebuild/drift repair, and an explicit stop condition for the currently missing code-first `ctx.vector` API.
 - Added read-only `ductape_events_topic_setup` and `ductape_events_validate_project` tools and made the canonical one-topic-per-file `ductape/events/<topic-tag>.topic.json` layout explicit and enforceable through the CLI.
 - Mark `ductape_function_setup` as read-only, non-destructive, idempotent, and closed-world in both MCP registration APIs so hosts do not incorrectly require mutation approval for its pure setup-plan generation.
 - Broadened Feature guidance from durable/event-driven workflows to synchronous or asynchronous named product capabilities.

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?]
@@ -2396,8 +2396,9 @@ Schema management:
   graph.dropIndex / dropConstraint / listIndexes / listConstraints
 
 Saved actions (parameterized queries stored on the product):
-  graph.createAction [{ graphTag, tag, name, query, params? }, productTag?]
+  graph.createAction [{ graphTag?, name, description?, operation, query, parameters: [{ name, type, required?, defaultValue?, description? }] }, productTag?]
   graph.listActions  [graphTag?, productTag?]
+  graph.execute      [{ product, env, graph, action, input?, session?, cache? }]
   graph.dispatch     [data]  ← call ductape_generate_payload FIRST
 
 Supported index types: btree | fulltext | vector | range | point | text
@@ -2512,7 +2513,7 @@ Registration (admin — ductape_cli):
 Runtime operations:
   vector.upsert      [{ product, env, tag, vectors: [{id, values: number[], metadata?}], namespace? }]
   vector.upsertOne   [{ product, env, tag, id, values: number[], metadata?, namespace? }]
-  vector.query       [{ product, env, tag, vector: number[], topK?, filter?, namespace?,
+  vector.query       [{ product, env, tag, vector: number[], topK: number, filter?, namespace?,
                         includeValues?, includeMetadata? }]
   vector.findSimilar [{ product, env, vector, values: number[], topK?, filter?, namespace? }]
   vector.fetchOne    [{ product, env, vector, id, namespace? }]
@@ -3615,14 +3616,15 @@ STEP 8 — SET rollbacks for reversible steps
       async (result) => ctx.api.run({ app: 'stripe', event: 'refund', input: { chargeId: result.id } })
     );
 
-Step types: function | action | database | graph | notification | storage | produce | quota |
-  fallback | vector | child_feature | sleep | wait_for_signal | checkpoint
+Code-first ctx step types currently record: function | action | database | graph | vector |
+  notification | storage | produce | quota | fallback | child_feature | sleep | wait_for_signal |
+  checkpoint.
 
 Valid synchronous Feature candidates include generate-world, resolve-nation-turn,
 calculate-route-capacity, price-subscription, evaluate-entitlement, and build-replay.
 
 Synchronous multi-step Feature (no Event, schedule, sleep, signal, or external system):
-  await ductape.features.define({
+  await ductape.feature.define({
     product: 'example-product',
     tag: 'resolve-nation-turn',
     name: 'Resolve Nation Turn',
@@ -3635,15 +3637,10 @@ Synchronous multi-step Feature (no Event, schedule, sleep, signal, or external s
       rejectedOrders: { type: 'number' },
     },
     handler: async (ctx) => {
-      const validated = await ctx.step('validate-orders', async () => {
-        return validateOrders(ctx.input);
-      });
-      const resolved = await ctx.step('resolve-orders', async () => {
-        return resolveOrders(validated);
-      });
-      return ctx.step('build-result', async () => {
-        return buildResult(resolved);
-      });
+      const validated = await ctx.step('validate-orders', () =>
+        ctx.database.execute({ database: 'orders-db', event: 'validate-orders', input: ctx.input }));
+      return ctx.step('resolve-orders', () =>
+        ctx.database.execute({ database: 'orders-db', event: 'resolve-orders', input: validated }));
     },
   });
 This is a valid Feature despite requiring no signal and producing no Event. Its qualification comes
@@ -3652,7 +3649,7 @@ step-level execution history.
 
 Define a feature (write this into the project's source files — do NOT use features.create):
   // src/features/onboard-user.ts  (or the equivalent path/language for the project)
-  await ductape.features.define({
+  await ductape.feature.define({
     tag: "onboard-user",
     name: "Onboard User",
     handler: async (ctx) => {
@@ -4699,6 +4696,195 @@ DEPRECATED ALIASES
   useWorkflowCancel  → useFeatureCancel
 `.trim(),
 };
+const GRAPH_VECTOR_PROJECTION_GUIDANCE = `
+
+━━━ EVENT → GRAPH/VECTOR PROJECTION CONTRACT (CURRENT TYPESCRIPT/NESTJS SDK) ━━━
+
+SOURCE-VERIFIED CODE-FIRST SUPPORT:
+  IFeatureContext and RecordingContext expose both ctx.graph and ctx.vector. Their calls compile to
+  portable JSON steps and the FeatureExecutor runs those steps against the configured local graph or
+  vector service. Keep every primitive call inside ctx.step().
+
+  The TypeScript SDK facade is singular: ductape.feature.define/execute/dispatch. The backend proxy
+  module is named "features", but application code must not infer a ductape.features property.
+
+EXACT CODE-FIRST GRAPH CONTEXT:
+  ctx.graph.createNode<T>({ graph, labels: string[], properties })
+  ctx.graph.updateNode<T>({ graph, id: string|number, properties })
+  ctx.graph.deleteNode({ graph, id })
+  ctx.graph.createRelationship<T>({ graph, from, to, type, properties? })
+  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(). 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>({
+    vector: "product-vectors",
+    vectors: [{ id, values: number[], metadata? }], namespace?, wait?
+  });
+  ctx.vector.upsertOne<T>({
+    vector: "product-vectors", id, values: number[], metadata?, namespace?
+  });
+  ctx.vector.query<T>({
+    vector: "product-vectors", values: number[], topK: number,
+    namespace?, filter?, includeValues?, includeMetadata?, minScore?
+  });
+  ctx.vector.deleteVectors<T>({ vector: "product-vectors", ids?, namespace?, deleteAll?, filter? });
+  ctx.vector.execute<T>({ vector: "product-vectors", action: "saved-action", input });
+  Product/env and the Feature's inherited session are supplied by the executor. Do not serialize
+  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.
+  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
+  __ductape_message_id; there is no automatic domain-event envelope and no automatic session token.
+  DuctapeModule subscribes at startup using product/env defaults unless decorator overrides are set.
+  The callback is acknowledged after it returns successfully; throwing propagates failure to the
+  provider's retry/nack path. Do not catch and suppress a failed projection.
+
+  import { Injectable } from '@nestjs/common';
+  import { DuctapeContextService, Events } from '@ductape/nestjs';
+
+  type ProductProjectionEvent = {
+    eventId: string;       // stable across retries and replay
+    productId: string;
+    version: number;       // monotonic aggregate/source version
+    name: string;
+    embedding: number[];   // only if produced upstream; Vector Search does not generate it
+    __ductape_message_id?: string;
+  };
+
+  @Injectable()
+  export class ProductProjectionConsumer {
+    constructor(private readonly ductape: DuctapeContextService) {}
+
+    @Events.Consumer({ event: 'catalog-events:product-projection-requested' })
+    async project(message: ProductProjectionEvent): Promise<void> {
+      const result = await this.ductape.sdk.feature.execute({
+        product: 'buydeck',
+        env: 'snd',
+        tag: 'project-product-graph',
+        input: message,
+        idempotency_key: 'product-projection:' + message.eventId,
+      });
+      if (result.status !== 'completed') {
+        throw new Error(result.error ?? 'Product graph projection did not complete');
+      }
+    }
+  }
+
+  The consumer passes its message explicitly as Feature input. Use a stable domain eventId for the
+  Feature idempotency key; __ductape_message_id is transport tracking metadata and must not replace a
+  domain idempotency key. Broker replay/redelivery means consumers and every projection write must
+  remain independently idempotent.
+
+ORDERING, PROJECTION STATE, AND FAILURE RECOVERY:
+  There is no atomic transaction spanning MongoDB, Neo4j, and Vertex Vector Search. Never claim that
+  ctx.step ordering creates a distributed transaction. Treat MongoDB as the canonical source and
+  graph/vector stores as rebuildable projections.
+
+  Recommended state machine, keyed by projection name + aggregate ID + source version/event ID:
+    1. Atomically claim/read projection_state in MongoDB; completed means return success.
+    2. Apply an idempotent Neo4j MERGE using stable domain IDs and sourceVersion.
+    3. Upsert the vector using the same stable ID and sourceVersion metadata.
+    4. Mark projection_state completed LAST, with graph/vector versions, checksum, and timestamps.
+  On failure, retain pending/failed state and throw so the broker retries. A retry repeats graph/vector
+  upserts safely and only then marks completion. Do not mark Mongo completion before derived writes.
+  If strict atomic visibility across all three stores is required, the platform does not provide it.
+
+REBUILD AND DRIFT REPAIR:
+  Rebuild from canonical MongoDB records, not from broker retention or processor logs. Use a named,
+  versioned rebuild job/Feature that pages deterministically, performs the same idempotent graph/vector
+  upserts, checkpoints the last canonical cursor, and records projection version/checksum. Drift repair
+  compares canonical IDs/sourceVersion/checksum with both projections, repairs missing/stale entries,
+  and removes extras only after a complete successful scan. Keep live consumer and rebuild writes
+  monotonic so an older rebuild item cannot overwrite a newer projection.
+
+IMPLEMENTATION GATE:
+  Combined database + graph + vector code-first projection Features are supported. Still stop when
+  an embedding source, vector dimension, saved graph/vector action, or idempotency strategy is not
+  specified; do not invent those application-level contracts.
+`.trim();
 const docsHandler = async (args) => {
     const requested = args.topic.toLowerCase().trim();
     const recoveryAliases = /^(dlq|dead[- ]?letters?|failed messages?|retry|retries|poison messages?|replay|reprocess|consumer failures?)$/;
@@ -4719,7 +4905,10 @@ const docsHandler = async (args) => {
                 canonicalDocumentationTopic: 'events',
             }, null, 2)}`
             : '';
-    return { content: [{ type: 'text', text: doc + structured }] };
+    const projectionGuidance = ['features', 'events', 'graphs', 'vector'].includes(key)
+        ? `\n\n${GRAPH_VECTOR_PROJECTION_GUIDANCE}`
+        : '';
+    return { content: [{ type: 'text', text: doc + structured + projectionGuidance }] };
 };
 const portableFunctionSetupHandler = async (args) => {
     const parsed = new URL(args.base_url);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node scripts/check-cli-command-security.mjs && node scripts/check-frontend-analytics-guidance.mjs && node scripts/check-events-discovery.mjs && node scripts/check-schema-fallback.mjs && node scripts/check-portable-functions.mjs && node scripts/check-project-link-guidance.mjs",
+    "test": "npm run build && node scripts/check-cli-command-security.mjs && node scripts/check-frontend-analytics-guidance.mjs && node scripts/check-events-discovery.mjs && node scripts/check-schema-fallback.mjs && node scripts/check-portable-functions.mjs && node scripts/check-project-link-guidance.mjs && node scripts/check-graph-vector-projection-guidance.mjs",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"
   },