@ductape/mcp 0.2.14 → 0.2.15

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

@@ -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,122 @@ 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(). 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.
+
+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.
+  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.
+
+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 +4832,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.15",
   "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"
   },