@ductape/mcp 0.2.32 → 0.2.34

package/dist/index.js

@@ -311,6 +311,23 @@ When the target application is a NestJS service or controller, always use @ducta
 instead of instantiating @ductape/sdk directly. It provides NestJS DI integration,
 global interceptors, decorators, and type-safe resource handles.
 
+PRODUCT RUNTIME SNAPSHOT — REQUIRED FOR SERVER INITIALIZATION:
+  Always provide both product and env at module initialization. Nest awaits the SDK's initial
+  product runtime snapshot during onModuleInit, before the application accepts traffic. The
+  snapshot preloads connected App versions/actions plus database actions/schema metadata, graphs,
+  vectors, storage, brokers/topics, sessions, notifications, resilience assets, agents, functions,
+  and caches into the execution bootstrap cache. External provider/database connections remain
+  lazy and pooled.
+
+  Runtime synchronization is enabled by default when product + env are present. Do not set
+  runtimeSync:false merely to simplify generated code. Configure it only when the user has an
+  explicit operational reason:
+    runtimeSync: { intervalMs: 30_000, jitter: 0.2, maxBackoffMs: 300_000 }
+
+  Polling uses runtimeRevision + HTTP ETag/304. databaseRevision is a refresh hint included in the
+  umbrella runtimeRevision, so schema and Database Action changes are detected. Failed refreshes
+  retain the last-known-good snapshot. Nest stops polling through onModuleDestroy automatically.
+
 SETUP — register once in AppModule:
 
   ╔══════════════════════════════════════════════════════════════════════════╗
@@ -338,6 +355,7 @@ SETUP — register once in AppModule:
         product: 'my-product',
         env: process.env.NODE_ENV === 'production' ? 'prd' : 'snd',
         redisUrl: process.env.DUCTAPE_REDIS_URL,  // required — no dispatch() works without this
+        runtimeSync: { intervalMs: 30_000, jitter: 0.2 },
       }),
     ],
   })
@@ -352,6 +370,7 @@ SETUP — register once in AppModule:
       product: cfg.get('DUCTAPE_PRODUCT'),
       env: cfg.get('DUCTAPE_ENV'),
       redisUrl: cfg.get('DUCTAPE_REDIS_URL'),  // required — no dispatch() works without this
+      runtimeSync: { intervalMs: 30_000, jitter: 0.2 },
     }),
   })
 
@@ -1128,7 +1147,8 @@ const payloadGenerateInputSchema = z.object({
     targets: z.record(z.any()).optional().describe('Identifies the specific operation to generate a payload for. ' +
         'For actions: { app: "app_tag", action: "action_tag" }. ' +
         'For features: { feature: "feature_tag" }. ' +
-        'For databases: { database: "db_tag", table: "table_or_collection_name" }. ' +
+        'For databases: { database: "db_tag", table?: "table_or_collection_name", action?: "action_tag" }. ' +
+        '  When generating code for a saved action, action is required and its static outputContract must be inspected. ' +
         '  Providing table is strongly recommended — the generator scans all actions configured for that table, ' +
         '  aggregates field definitions (name, type, required, sample value), and returns them in ' +
         '  meta.schema_context.database.fields. The where/data placeholders in the payload are also ' +
@@ -1161,11 +1181,16 @@ const snippetGenerateInputSchema = payloadGenerateInputSchema.extend({
     language: z.enum(['typescript', 'python']).default('typescript'),
 });
 const schemaInputSchema = z.object({
+    publishable_key: z.string().optional().describe('Optional publishable key for live database schema lookup. Omit when DUCTAPE_PUBLISHABLE_KEY is configured.'),
     module: z.enum(['app', 'product']).optional().describe('Optional. Scope the result to one module. With no method, returns only the compact list of available methods.'),
     method: z.string().optional().describe('Optional method key such as "databases.create" or "notifications.update". Use with module to return only that method schema.'),
     product_tag: z.string().optional().describe('For live app-action discovery, the product the app is linked to. Must be supplied with app_tag and action_tag.'),
     app_tag: z.string().optional().describe('For live app-action discovery, the linked app tag. Must be supplied with product_tag and action_tag.'),
-    action_tag: z.string().optional().describe('For live app-action discovery, the exact action tag whose complete contract should be returned.'),
+    action_tag: z.string().optional().describe('For live app-action or database-action discovery, the exact action tag whose complete contract should be returned.'),
+    database_tag: z.string().optional().describe('For live database discovery, the database component tag. Requires product_tag and env_slug.'),
+    env_slug: z.string().optional().describe('For live database discovery, the environment whose synchronized table schema and action contract should be used.'),
+    table: z.string().optional().describe('For live database discovery, the exact table/collection. Required for direct query row contracts; inferred from a saved action when action_tag is supplied.'),
+    database_operation: z.enum(['query', 'insert', 'update', 'delete', 'upsert', 'aggregate', 'raw']).optional().default('query').describe('Direct database primitive whose envelope should be combined with the table schema. Ignored when action_tag identifies a saved action.'),
 });
 const marketplaceDiscoverInputSchema = z.object({
     query: z.string().min(1).describe('Capability or provider search, for example "payments" or "paystack".'),
@@ -1306,18 +1331,24 @@ function buildTypeScriptSnippet(payload, operationFamily, method) {
     const invocationArgs = buildSdkInvocationArgs(payload);
     return `import Ductape from "@ductape/sdk";
 
+const payload = ${toPrettyJson(payload)};
 const ductape = new Ductape({
-  workspace_id: process.env.DUCTAPE_WORKSPACE_ID!,
-  user_id: process.env.DUCTAPE_USER_ID!,
-  public_key: process.env.DUCTAPE_PUBLIC_KEY!,
+  accessKey: process.env.DUCTAPE_ACCESS_KEY!,
+  product: String(payload.product),
+  env: String(payload.env),
   redis_url: process.env.DUCTAPE_REDIS_URL,
+  runtime_sync: { interval_ms: 30_000, jitter: 0.2 },
 });
 
 async function run() {
-  const payload = ${toPrettyJson(payload)};
+  await ductape.ready();
   const args = ${toPrettyJson(invocationArgs)};
-  const result = await ductape.${callPath}(args);
-  return { payload, result };
+  try {
+    const result = await ductape.${callPath}(args);
+    return { payload, result };
+  } finally {
+    await ductape.close();
+  }
 }
 
 run().catch(console.error);
@@ -1351,6 +1382,44 @@ function buildSnippet(language, payload, operationFamily, method) {
         ? buildPythonSnippet(payload, operationFamily, method)
         : buildTypeScriptSnippet(payload, operationFamily, method);
 }
+function buildDatabaseActionFeatureExample(targets, contract) {
+    const database = targets.database ?? targets.database_tag ?? '<database-tag>';
+    const action = targets.action ?? targets.action_tag ?? '<action-tag>';
+    if (!contract?.normalizedOutput) {
+        return `// Output contract unknown: do not infer a row, array, or envelope.\n` +
+            `// Sync the table schema and fetch the Database Action contract before generating this Feature.`;
+    }
+    const operation = String(contract.operation ?? '').toUpperCase();
+    if (operation === 'QUERY' || operation === 'READ') {
+        return `type DatabaseActionResult = { data: Record<string, unknown>[]; count: number; fields?: string[] };\n\n` +
+            `const queryResult = await ctx.step("${action}", () =>\n` +
+            `  ctx.database.execute<DatabaseActionResult>({\n` +
+            `    database: ${JSON.stringify(database)},\n` +
+            `    action: ${JSON.stringify(action)},\n` +
+            `    input: { /* values from ctx.input */ },\n` +
+            `  }),\n` +
+            `);\n\n` +
+            `await ctx.branch(ctx.when.eq(ctx.transform.length(queryResult.data), 0), {\n` +
+            `  then: async () => { /* handle successful empty query */ },\n` +
+            `  else: async () => { const row = queryResult.data[0]; /* consume validated row */ },\n` +
+            `});`;
+    }
+    if ((operation === 'INSERT' || operation === 'CREATE') && contract.createdRecordPath === 'data[0]') {
+        return `const insertResult = await ctx.step("${action}", () =>\n` +
+            `  ctx.database.execute<{ data: Record<string, unknown>[]; count: number; insertedIds: unknown[] }>({\n` +
+            `    database: ${JSON.stringify(database)}, action: ${JSON.stringify(action)}, input: { /* values */ },\n` +
+            `  }),\n` +
+            `);\n` +
+            `const createdRow = insertResult.data[0]; // No redundant follow-up query: contract returns rows.`;
+    }
+    return `// ${operation} returns ${contract.returnedRows ?? 'unknown'} rows.\n` +
+        `const result = await ctx.step("${action}", () =>\n` +
+        `  ctx.database.execute({ database: ${JSON.stringify(database)}, action: ${JSON.stringify(action)}, input: { /* values */ } }),\n` +
+        `);\n` +
+        (contract.followUpQueryRequired
+            ? `// This contract returns mutation metadata only; add an explicit saved QUERY action before consuming a row.`
+            : `// Consume only fields declared by normalizedOutput.`);
+}
 // ─── CLI helpers ─────────────────────────────────────────────────────────────
 // Per-process cache: avoids re-running whoami / workspaces use on every call.
 let authState = 'unknown';
@@ -1554,7 +1623,7 @@ function shellArgument(value) {
 }
 const docsInputSchema = z.object({
     topic: z.string().describe('Feature topic to look up. Supported: ' +
-        'transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
+        'transactions, presave, triggers, aggregations, migrations, indexes, performance, runtime-sync, actions, ' +
         'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
         'notifications, resilience, features, portable-functions, events, logs, migration, cli-authentication, frontend, frontend-analytics, client, react, vue'),
 });
@@ -2465,6 +2534,39 @@ DUCTAPE DATABASE PERFORMANCE GUIDANCE
 5. Caching
    - For read-heavy, rarely-changing data use caches.get before databases.query.
    - Invalidate cache keys in an afterWrite trigger (see ductape_docs({ topic: "triggers" })).
+`.trim(),
+    'runtime-sync': `
+DUCTAPE PRODUCT RUNTIME SNAPSHOTS
+
+For every long-lived TypeScript/Node backend, initialize @ductape/sdk with accessKey, product,
+and env, then await ready() before accepting work:
+
+  const ductape = new Ductape({
+    accessKey: process.env.DUCTAPE_ACCESS_KEY!,
+    product: "payments",
+    env: "prd",
+    runtime_sync: { interval_ms: 30_000, jitter: 0.2, max_backoff_ms: 300_000 },
+  });
+  await ductape.ready();
+
+This fetches one environment-scoped product snapshot and primes the existing bootstrap cache with
+connected App versions/actions, databases/actions/table schemas, graphs, vectors, storage,
+brokers/topics, sessions, notifications, resilience assets, agents, functions, and caches.
+Connections remain lazy and pooled; snapshot bootstrap does not call external providers.
+
+Runtime synchronization is automatic when product + env are supplied:
+  - Conditional polling sends If-None-Match with runtimeRevision; unchanged state returns HTTP 304.
+  - runtimeRevision is authoritative. databaseRevision, connectionRevision, secretRevision, and
+    assetRevision are narrower change hints. Any databaseRevision change also changes runtimeRevision.
+  - A changed snapshot is loaded off-path and atomically replaces cache entries. Deleted assets are removed.
+  - Refresh failure retains the last-known-good snapshot and retries with jittered exponential backoff.
+  - Use runtimeSnapshotStatus() for revision/error telemetry and refreshRuntime() for an explicit pull.
+  - Call close() during process shutdown. Do not create one Ductape instance per request.
+
+For NestJS, use DuctapeModule.forIntegration({ accessKey, product, env, runtimeSync }) instead of
+new Ductape(). @ductape/nestjs awaits ready() in onModuleInit and closes the poller in
+onModuleDestroy. Never omit product/env when the service has stable defaults: doing so disables
+product snapshot bootstrap and returns execution to lazy per-asset bootstrap misses.
 `.trim(),
     actions: `
 DUCTAPE DATABASE ACTIONS
@@ -2475,12 +2577,124 @@ ctx.database.execute inside a Feature step invokes a saved action through its \`
 Direct ctx.database.query/insert/update/delete calls retain their normal {table, where, data, ...}
 shape and do not resolve a saved action.
 
+HARDENED DIRECT DATABASE PRIMITIVE CONTRACTS:
+  Direct calls also return typed adapter envelopes; they do not return a raw row, raw array,
+  boolean, or arbitrary T. Derive row fields from the selected table schema and use these exact
+  normalized contracts:
+    ctx.database.query<Row>(...)  → { data: Row[], count: number, fields?: string[] }
+    ctx.database.insert<Row>(...) → { data: Row[], count: number, insertedIds: unknown[] }
+    ctx.database.update<Row>(...) → { data: Row[], count: number }
+    ctx.database.delete(...)      → { count: number, data?: Row[] }
+    ctx.database.upsert<Row>(...) → { data: Row[], count: number, operation: "inserted"|"updated" }
+    ctx.database.raw<Row>(...)    → { data: Row[], count: number, fields?: string[], rowsAffected?: number }
+    ctx.database.aggregate(...)   → an alias-keyed aggregate object declared by operations; it is
+                                     NOT a row envelope unless the selected adapter contract says so.
+
+  Never generate queryResult[0], queryResult.length, a boolean check on deleteResult, or direct
+  field access such as insertResult.id. Query rows live at queryResult.data; delete success/count
+  is deleteResult.count; inserted/updated rows exist in mutationResult.data only when returning is
+  true. INSERT always includes insertedIds, but an inserted ID is not a complete row.
+
+  Direct primitive contracts are derived from the explicit method, adapter/version, table schema,
+  and call options such as returning, returningColumns, select, limit, and aggregation aliases.
+  Never infer row fields from domain expectations. If table schema is missing, call static schema
+  discovery/sync and mark row fields unknown; do not execute the operation merely to learn shape.
+
+DIRECT FEATURE-SAFE EXAMPLES:
+  const queryResult = await ctx.step("find-customer", () =>
+    ctx.database.query<Customer>({
+      database: "payment-processing", table: "customers",
+      where: { email: ctx.input.customerEmail }, limit: 1,
+    }),
+  );
+  await ctx.branch(ctx.when.eq(ctx.transform.length(queryResult.data), 0), {
+    then: async () => { /* create */ },
+    else: async () => { const customer = queryResult.data[0]; /* consume */ },
+  });
+
+  const insertResult = await ctx.step("create-customer", () =>
+    ctx.database.insert<Customer>({
+      database: "payment-processing", table: "customers", data: { /* fields */ }, returning: true,
+    }),
+  );
+  // returning:true declares created rows at insertResult.data; do not re-query.
+  const createdCustomer = insertResult.data[0];
+
+  Empty { data: [], count: 0 } is successful. Thrown/explicit failure is a failed step. A successful
+  value that violates the primitive's declared envelope is a platform contract violation and must
+  fail at the producing step boundary. Never let a missing required row field flow to an app action.
+
 REUSE BEFORE CREATE:
   1. ductape_cli("db actions list --database product_tag:database_tag --json")
   2. Inspect likely matches with ductape_cli("db actions get product_tag:database_tag:action_tag --json").
   3. Reuse the matching tag with database.execute/ctx.database.execute when operation, table,
      template, parameters, and result semantics match. Create only when no exact functional match exists.
 
+OUTPUT CONTRACTS ARE MANDATORY DISCOVERY METADATA:
+  Every action returned by databases.action.fetch/fetchAll includes outputContract and
+  outputContractsByEnvironment. Read the contract for the target environment before writing a
+  Feature. It contains input, normalizedOutput, rowSchema, cardinality, returnedRows,
+  returnsAffectedRows, createdRecordPath, followUpQueryRequired, adapter, and adapterOutput.
+
+  Never infer a Database Action's output shape from its operation name, generic SDK knowledge,
+  or application-domain expectations. Derive it from the database adapter, action definition,
+  table schema metadata, and action outputContract. If the contract confidence is "unknown" or
+  normalizedOutput is null, state that the output is unknown and request platform metadata; do
+  not invent a raw row, array, envelope, or field. Static discovery must never execute the action.
+
+MANDATORY DUCTAPE_SCHEMA ROW LOOKUP:
+  The normalized envelope does NOT reveal the fields inside Row. Before generating code that reads
+  result.data[n].field (or evaluates a row field in a Feature branch), call one of these exact forms:
+    Saved Database Action:
+      ductape_schema({ product_tag: "<product_tag>", env_slug: "<env_slug>",
+        database_tag: "<database_tag>", action_tag: "<action_tag>" })
+    Direct database query/primitive:
+      ductape_schema({ product_tag: "<product_tag>", env_slug: "<env_slug>",
+        database_tag: "<database_tag>", table: "<table>", database_operation: "query" })
+  Use output_contract only for the saved action's operation-specific envelope. Use row_schema for
+  the contents of each result.data item for BOTH saved actions and direct calls. Projection/select
+  may narrow those fields further. If row_schema is empty or warnings report missing synchronized
+  metadata, run \`ductape db schema push --db <database_tag> --env <env_slug>\`, retry
+  ductape_schema, and keep row fields unknown until it succeeds. Never execute the query/action to
+  discover its shape, and never substitute a generic product asset schema for this live lookup.
+
+NORMALIZED ENVELOPES DIFFER BY OPERATION:
+  QUERY       → { data: Row[], count: number, fields?: string[] }
+  INSERT      → { data: Row[], count: number, insertedIds: unknown[] }
+  UPDATE      → { data: Row[], count: number }
+  DELETE      → { count: number, data?: Row[] }
+  RAW/EXECUTE → { data: Row[], count: number, fields?: string[], rowsAffected?: number }
+  returning controls whether mutation data contains rows. Do not describe all operations as the
+  same envelope. Adapter-native details belong in adapterOutput; Feature code uses normalizedOutput.
+
+FEATURE-SAFE QUERY PATTERN:
+  type FindCustomerResult = { data: Customer[]; count: number; fields?: string[] };
+  const queryResult = await ctx.step("find-customer", () =>
+    ctx.database.execute<FindCustomerResult>({
+      database: "payment-processing",
+      action: "find-customer-by-email",
+      input: { email: ctx.input.customerEmail },
+    }),
+  );
+  await ctx.branch(ctx.when.eq(ctx.transform.length(queryResult.data), 0), {
+    then: async () => { /* create */ },
+    else: async () => {
+      const customer = queryResult.data[0];
+      /* consume customer only inside this structurally valid branch */
+    },
+  });
+  Never generate queryResult[0] or ctx.transform.length(queryResult) for an envelope contract.
+  { data: [], count: 0 } is a successful empty query, not a failed action.
+
+MUTATION FLOW:
+  Inspect returnedRows, createdRecordPath, and followUpQueryRequired. If INSERT returns rows, use
+  insertResult.data[0] directly and do not add a redundant resolve query. If it returns metadata
+  only, explain that fact and add an explicit follow-up query. Never allow an undefined required
+  id/email to reach a downstream app/provider action: validate it or make that step structurally
+  dependent on queryResult.data[0] or the declared createdRecordPath. A thrown/failed response is
+  a failed step; a successful value that violates normalizedOutput is a platform contract violation
+  and must fail at the producing step boundary.
+
 Create/update/delete are ADMINISTRATIVE (access key) — FORBIDDEN through ductape_execute
 (publishable key). Use ductape_cli, same as every other admin resource:
   ductape_cli("db actions create --action-file ductape/database/actions/<action-tag>.action.json")
@@ -3046,8 +3260,11 @@ Product structure (IProduct fields):
   workflows[] (features), models[], agents[], jobs[]
 
 Bootstrap (single API call returning product context + component config + private key):
-  Each service makes a single bootstrap call at first use; results are cached in BootstrapCache
-  (Redis when available). This avoids repeated round-trips in high-frequency paths.
+  Initialize @ductape/sdk with product + env and await ductape.ready(). It fetches the full
+  environment-scoped product runtime snapshot and primes BootstrapCache for connected App actions
+  and product components. A service falls back to its targeted bootstrap endpoint only when the
+  requested asset is absent. Polling uses ETag/304 and atomically refreshes changed state.
+  See ductape_docs({ topic: "runtime-sync" }).
 `.trim(),
     sessions: `
 DUCTAPE SESSIONS
@@ -3962,7 +4179,7 @@ STEP 7 — HANDLE conditionals, loops, and branching (when applicable)
 
   Prefer explicit portable branching for step results:
     const result = await ctx.step("find", () => ctx.database.execute(...));
-    await ctx.branch(ctx.when.eq(result.count, 0), {
+    await ctx.branch(ctx.when.eq(ctx.transform.length(result.data), 0), {
       then: () => ctx.step("create", () => ctx.database.execute(...)),
       else: () => ctx.step("reuse", () => ctx.database.execute(...)),
     });
@@ -4381,8 +4598,12 @@ Import (register an EXISTING cloud resource):
     // dispatch() requires redis_url in the Ductape initialization options — it throws at runtime without it.
     const ductape = new Ductape({
       accessKey: process.env.DUCTAPE_ACCESS_KEY,
+      product: "my-product",
+      env: "prd",
       redis_url: process.env.DUCTAPE_REDIS_URL,  // required for any dispatch(); omit only if never dispatching
+      runtime_sync: { interval_ms: 30_000, jitter: 0.2 },
     });
+    await ductape.ready();
     await ductape.events.produce({
       product: "my-product",
       env: "prd",
@@ -4405,6 +4626,7 @@ Import (register an EXISTING cloud resource):
         product: 'my-product',
         env: process.env.NODE_ENV === 'production' ? 'prd' : 'snd',
         redisUrl: process.env.DUCTAPE_REDIS_URL,  // required — dispatch() throws without this
+        runtimeSync: { intervalMs: 30_000, jitter: 0.2 },
       }),
     });
     // Environment: DUCTAPE_REDIS_URL=redis://localhost:6379 (local) or rediss://:<pw>@host:6380 (managed)
@@ -6065,6 +6287,38 @@ async function main() {
             const generated = addSessionAwarenessMetadata(await generateExecutablePayload({ ...args, include_session: includeSession, publishable_key: key }), args);
             const payload = generated?.payload ?? {};
             const snippet = buildSnippet(args.language, payload, args.operation_family, args.method);
+            let databaseActionContract = null;
+            let featureExample;
+            if (args.operation_family === 'database') {
+                const targets = (args.targets ?? {});
+                const action = targets.action ?? targets.action_tag;
+                const database = targets.database ?? targets.database_tag;
+                if (action && database) {
+                    const databaseTag = String(database).startsWith(`${args.product_tag}:`)
+                        ? String(database)
+                        : `${args.product_tag}:${database}`;
+                    const fullActionTag = String(action).startsWith(`${databaseTag}:`)
+                        ? String(action)
+                        : `${databaseTag}:${action}`;
+                    const response = await cliHandler({
+                        command: `db actions get ${shellArgument(fullActionTag)} --json`,
+                    });
+                    if (!response.isError) {
+                        const raw = response.content[0]?.type === 'text' ? response.content[0].text : '';
+                        try {
+                            const parsed = JSON.parse(raw);
+                            const definition = parsed?.data ?? parsed?.result ?? parsed;
+                            databaseActionContract = definition?.outputContractsByEnvironment?.[args.env_slug]
+                                ?? definition?.outputContract
+                                ?? null;
+                        }
+                        catch {
+                            databaseActionContract = null;
+                        }
+                    }
+                    featureExample = buildDatabaseActionFeatureExample(targets, databaseActionContract);
+                }
+            }
             return {
                 content: [
                     {
@@ -6072,6 +6326,8 @@ async function main() {
                         text: JSON.stringify({
                             payload: generated,
                             snippet,
+                            ...(databaseActionContract ? { database_action_contract: databaseActionContract } : {}),
+                            ...(featureExample ? { feature_example: featureExample } : {}),
                         }, null, 2),
                     },
                 ],
@@ -6084,6 +6340,100 @@ async function main() {
     };
     const schemaHandler = async (args) => {
         try {
+            if (args.database_tag) {
+                if (!args.product_tag || !args.database_tag || !args.env_slug) {
+                    throw new Error('product_tag, database_tag, and env_slug are required for live database schema discovery');
+                }
+                let action = null;
+                let table = args.table;
+                if (args.action_tag) {
+                    const databaseTag = args.database_tag.startsWith(`${args.product_tag}:`)
+                        ? args.database_tag
+                        : `${args.product_tag}:${args.database_tag}`;
+                    const fullActionTag = args.action_tag.startsWith(`${databaseTag}:`)
+                        ? args.action_tag
+                        : `${databaseTag}:${args.action_tag}`;
+                    const response = await cliHandler({
+                        command: `db actions get ${shellArgument(fullActionTag)} --json`,
+                    });
+                    if (response.isError)
+                        return response;
+                    const raw = response.content[0]?.type === 'text' ? response.content[0].text : '';
+                    try {
+                        const parsed = JSON.parse(raw);
+                        action = parsed?.data ?? parsed?.result ?? parsed;
+                        table = table ?? action?.tableName;
+                    }
+                    catch {
+                        throw new Error(`Database Action metadata was not valid JSON: ${raw}`);
+                    }
+                }
+                if (!table) {
+                    throw new Error('table is required for direct database schema discovery and could not be inferred from the action');
+                }
+                const key = args.publishable_key || process.env.DUCTAPE_PUBLISHABLE_KEY;
+                if (!key) {
+                    throw new Error('Set DUCTAPE_PUBLISHABLE_KEY or pass publishable_key so ductape_schema can fetch synchronized table metadata');
+                }
+                const generated = await generateExecutablePayload({
+                    publishable_key: key,
+                    product_tag: args.product_tag,
+                    env_slug: args.env_slug,
+                    operation_family: 'database',
+                    method: args.action_tag
+                        ? String(action?.operation ?? action?.type ?? 'query').toLowerCase()
+                        : (args.database_operation ?? 'query'),
+                    targets: {
+                        database: args.database_tag,
+                        table,
+                        ...(args.action_tag ? { action: args.action_tag } : {}),
+                    },
+                    include_session: false,
+                    execution_context: 'system',
+                    schema_mode: 'best_effort',
+                });
+                const databaseSchema = generated?.meta?.schema_context?.database ?? null;
+                const actionContract = args.action_tag
+                    ? action?.outputContractsByEnvironment?.[args.env_slug] ?? action?.outputContract ?? null
+                    : null;
+                const directOutputContracts = {
+                    query: { normalizedOutput: '{ data: Row[], count: number, fields?: string[] }', cardinality: 'many' },
+                    insert: { normalizedOutput: '{ data: Row[], count: number, insertedIds: unknown[] }', cardinality: 'many' },
+                    update: { normalizedOutput: '{ data: Row[], count: number }', cardinality: 'many' },
+                    delete: { normalizedOutput: '{ count: number, data?: Row[] }', cardinality: 'many' },
+                    upsert: { normalizedOutput: '{ data: Row[], count: number, operation: "inserted" | "updated" }', cardinality: 'many' },
+                    aggregate: { normalizedOutput: 'Record<aggregationAlias, number | unknown>', cardinality: 'one' },
+                    raw: { normalizedOutput: '{ data: Row[], count: number, fields?: string[], rowsAffected?: number }', cardinality: 'many' },
+                };
+                const outputContract = actionContract ?? directOutputContracts[args.database_operation ?? 'query'];
+                const rowSchema = actionContract?.rowSchema ?? databaseSchema?.fields ?? {};
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                scope: args.action_tag ? 'database_action' : 'database_primitive',
+                                product_tag: args.product_tag,
+                                env_slug: args.env_slug,
+                                database_tag: args.database_tag,
+                                table,
+                                operation: args.action_tag
+                                    ? action?.operation ?? action?.type
+                                    : args.database_operation ?? 'query',
+                                input_contract: args.action_tag ? action?.data ?? [] : generated?.payload?.input,
+                                output_contract: outputContract,
+                                row_schema: rowSchema,
+                                database_schema: databaseSchema,
+                                action: args.action_tag ? action : undefined,
+                                warnings: generated?.meta?.schema_warnings ?? [],
+                                discovery_only: true,
+                                executed_action: false,
+                                guidance: outputContract?.normalizedOutput
+                                    ? 'Use output_contract for the envelope and row_schema for data item fields.'
+                                    : 'Do not infer row fields or an action envelope when metadata is absent. Sync schema metadata and retry ductape_schema.',
+                            }, null, 2),
+                        }],
+                };
+            }
             const liveActionScope = [args.product_tag, args.app_tag, args.action_tag];
             if (liveActionScope.some(Boolean)) {
                 if (!liveActionScope.every(Boolean)) {
@@ -6215,11 +6565,18 @@ async function main() {
         }, snippetGenerateHandler);
         server.registerTool('ductape_schema', {
             title: 'Ductape Asset Schema',
-            description: 'Returns a compact method index, one targeted asset schema, or one complete live app-action contract. ' +
+            description: 'Returns a compact method index, one targeted asset schema, one complete live app-action contract, ' +
+                'or a live synchronized Database Action/direct database row contract. ' +
                 'Call with module="app" or module="product" first to list method keys, then call again with ' +
                 'module and method (for example method="databases.create") for the complete field schema. ' +
                 'For one linked app action, call with product_tag, app_tag, and action_tag; do not fetch a full app catalogue. ' +
+                'For a saved Database Action, call with product_tag, env_slug, database_tag, and action_tag. ' +
+                'For a direct database call, call with product_tag, env_slug, database_tag, table, and database_operation. ' +
+                'Database results distinguish output_contract (the operation envelope) from row_schema (fields inside data rows). ' +
+                'This lookup is discovery-only and never executes the database action or primitive. ' +
                 'Avoid calling without module unless you explicitly need the entire manifest.\n\n' +
+                'ALWAYS call the live database form before generating code that reads fields from a saved Database Action ' +
+                'or direct query result. If row_schema is unavailable, do not guess fields; sync the database schema and retry. ' +
                 'ALWAYS call this before constructing a file for "resources <type> create" or any cloud ' +
                 'import/provision operation — field shapes are not guessable from context.\n\n' +
                 'Conditional fields: some fields are returned as oneOf (an array of variant shapes). ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.2.32",
+  "version": "0.2.34",
   "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-paystack-action-schema.mjs && node scripts/check-portable-functions.mjs && node scripts/check-feature-control-flow.mjs && node scripts/check-project-link-guidance.mjs && node scripts/check-graph-vector-projection-guidance.mjs && node scripts/check-asset-file-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-paystack-action-schema.mjs && node scripts/check-portable-functions.mjs && node scripts/check-feature-control-flow.mjs && node scripts/check-project-link-guidance.mjs && node scripts/check-graph-vector-projection-guidance.mjs && node scripts/check-asset-file-guidance.mjs && node scripts/check-database-action-contract-guidance.mjs && node scripts/check-runtime-sync-guidance.mjs",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"
   },