@ductape/mcp 0.2.31 → 0.2.33

package/dist/index.js

@@ -945,6 +945,9 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
       // ctx.input                – typed runtime input; always compiles to $Input{} operators
       // ctx.sampleInput          – compile-time sample for loop/branch discovery only
       // ctx.step(tag, fn, rollback?, opts?)  – define a durable step
+      // ctx.when.eq/ne/gt/gte/lt/lte/truthy/falsy(...) – build portable runtime conditions
+      // ctx.branch(condition, { then, else? }) – record both paths as conditioned steps
+      // ctx.each(ctx.sampleInput.items, async (item, index) => ...) – deterministic compile-time expansion
       // ctx.api.run({ app, action, input }) – call an app action (NOT 'event' -- that field name
       //   only applies to ctx.database/ctx.notification/ctx.storage below, never ctx.api/ctx.action)
       // ctx.database.execute({ database, action, input }) for a saved database action
@@ -1125,7 +1128,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 ' +
@@ -1158,11 +1162,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".'),
@@ -1348,6 +1357,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';
@@ -2472,12 +2519,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")
@@ -3373,6 +3532,20 @@ CONFIGURATION BOUNDARY
   Workbench is also supported. Never route their administrative create/update methods through
   ductape_execute: its publishable-key runtime proxy will fail.
 
+CLI COMMANDS (aliases are normalized; use these exact shapes):
+  ductape resources feature list --product <product> --json
+  ductape resources feature get -t <feature> --product <product> --json
+  ductape resources quota list --product <product> --json
+  ductape resources quota get -t <quota> --product <product> --json
+  ductape resources fallback list --product <product> --json
+  ductape resources fallback get -t <fallback> --product <product> --json
+  ductape resources health list --product <product> --json
+  ductape resources health get -t <healthcheck> --product <product> --json
+  Create/update use the same resource type plus -f <asset.json>. Singular/plural feature(s),
+  fallback(s), and healthcheck(s) aliases are accepted, but canonical generated commands should
+  use feature, quota, fallback, and health. These commands are administrative catalogue CRUD;
+  runtime run/execute operations belong to the SDK or authenticated execution surface.
+
 QUOTAS — weighted/provider-capacity routing pools (NOT request rate limiting):
   Workbench definition shape:
   {
@@ -3929,15 +4102,83 @@ STEP 6 — WRITE the feature into the project codebase
   script does, invoked only through the explicit CLI command.
 
 STEP 7 — HANDLE conditionals, loops, and branching (when applicable)
-  Branch on step result (early return in handler):
-    → Add branchOverrides: { stepTag: { field: value } } so all branches are recorded
-    → At runtime the executor evaluates the real result and skips or runs later steps accordingly
+  MANDATORY CONTROL-FLOW RULES:
+    1. A stored Feature executes its compiled steps. The JavaScript handler is NOT rerun at runtime.
+    2. Never use if/else, switch, ?:, ??, &&, ||, optional chaining, map, filter, find, some,
+       every, reduce, for, for..of, forEach, or while on a ctx.step() result or ctx.input proxy.
+       JavaScript would evaluate the recording proxy, not the future runtime value.
+    3. Use ctx.branch(ctx.when.*, { then, else }) for runtime decisions.
+    4. Use ctx.each only with a concrete ctx.sampleInput array to expand a fixed step graph.
+    5. Put runtime-sized collection algorithms and arbitrary business logic in a registered
+       portable Function, then invoke it through ctx.functions inside a step.
+    6. Direct Date.now() and Math.random() are forbidden in handlers. Use ctx.transform.now(),
+       ctx.transform.uuid(), and ctx.transform.concat/replace/substring/upper/lower/trim so values
+       are generated at execution time. Use a portable Function for domain-specific generators.
+    7. Never use branchOverrides in newly generated code. It exists only to migrate old handlers.
+
+  Prefer explicit portable branching for step results:
+    const result = await ctx.step("find", () => ctx.database.execute(...));
+    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(...)),
+    });
+    → ctx.when also supports ne, gt, gte, lt, lte, truthy, falsy, and/or.
+    → Do not use ordinary if/else, ternary, or ?? directly on an unresolved step result.
+    → branchOverrides remains a compatibility escape hatch for older Feature source.
+    → If both paths must feed a later common step, do not assume ctx.branch returns a selected
+      value. Either record the downstream operation inside each path, persist a shared result that
+      the later step can read, or move the find-or-create algorithm into one portable Function.
   Loop over input array:
-    → Add recordInput: { items: [{ id: "1" }, { id: "2" }] } and iterate ctx.sampleInput.items
+    → Add recordInput: { items: [{ id: "1" }, { id: "2" }] } and call
+      ctx.each(ctx.sampleInput.items, async (item, index) => { ... })
     → Use unique step tags per iteration (e.g. "process-" + item.id)
+    → map/filter/find/indexing on ctx.sampleInput are compile-time graph discovery only.
+    → Runtime-sized map/filter/find/some/every and arbitrary loops belong in a registered portable
+      Function invoked through ctx.functions; never guess or freeze their results during recording.
   Switch/if-else on feature input values:
-    → Add recordScenarios: [{ type: "a" }, { type: "b" }] — handler runs once per scenario
-    → Only the scenario whose input matches runs at execution time
+    → Prefer ctx.branch(ctx.when.eq(ctx.input.type, "a"), { then, else }).
+    → recordScenarios is for legacy compile-time graph discovery, not a runtime branch primitive.
+
+  SAFE COPY-READY PATTERNS:
+    Runtime input branch:
+      await ctx.branch(ctx.when.eq(ctx.input.kind, "refund"), {
+        then: () => ctx.step("refund", () => ctx.api.run({ app, action: "refund", input: {...} })),
+        else: () => ctx.step("charge", () => ctx.api.run({ app, action: "charge", input: {...} })),
+      });
+    Nested/indexed result check:
+      await ctx.branch(ctx.when.eq(search.data.length, 0), { then: ..., else: ... });
+    Compound condition:
+      await ctx.branch(ctx.when.and(
+        ctx.when.eq(result.status, "ready"),
+        ctx.when.gt(result.count, 0),
+      ), { then: ..., else: ... });
+    Runtime payment/reference string (never frozen at sync time):
+      const reference = ctx.transform.concat(
+        "pay_", ctx.transform.now(), "_", ctx.transform.uuid(),
+      );
+      await ctx.step("charge", () => ctx.fallback.execute({
+        fallback: "charge-payment", input: { reference, ... },
+      }));
+    Fixed graph expansion:
+      recordInput: { regions: ["ng", "gh"] },
+      handler: async (ctx) => ctx.each(ctx.sampleInput.regions, async (region, index) => {
+        await ctx.step("sync-region-" + index, () => ctx.functions.invoke(syncFn, "run", { region }));
+      });
+
+  UNSAFE — NEVER GENERATE:
+    if (result.count === 0) await ctx.step(...);
+    const customer = found[0] ?? await ctx.step(...);
+    ctx.input.items.map(item => ctx.step(...));
+    for (const item of ctx.input.items) await ctx.step(...);
+    const reference = "pay_" + Date.now() + "_" + Math.random();
+
+  BEFORE SYNCING A FEATURE:
+    → Confirm every runtime decision uses ctx.branch + ctx.when.
+    → Confirm every ctx.step tag is unique across both paths and every expanded iteration.
+    → Confirm no runtime proxy is consumed by native JavaScript control flow or array iteration.
+    → Confirm every ctx.step contains a portable ctx component/function call.
+    → Compile locally, inspect schema.steps, and verify both branch paths, condition, depends_on,
+      and operator-valued inputs are present before persisting.
 
 STEP 8 — SET rollbacks for reversible steps
   Any step that allocates a resource should undo it if a later step fails.
@@ -4047,16 +4288,18 @@ Feature statuses: pending | running | completed | failed | rolled_back | rolling
 
 ━━━ FEATURE RECORDING SEMANTICS ━━━
 
-When you call features.define({ handler }), the handler runs TWICE:
+When you call features.define({ handler }), there are two distinct phases, but the handler itself
+runs only during compilation/recording:
 
   1. RECORDING PHASE (at define time) — handler is called with a RecordingContext.
      All ctx.step() calls return lightweight proxy objects, not real data.
      This phase captures the step graph: which steps exist, their types, tags, and declared
      inputs/outputs. No real API calls, DB queries, or side effects occur.
      Arbitrary JS code OUTSIDE ctx.step() ALSO runs during recording — with proxy values.
-     For loops: supply recordInput and iterate ctx.sampleInput so all iterations are recorded.
+     For loops: supply recordInput and use ctx.each(ctx.sampleInput.items, ...) so all iterations are recorded.
      ctx.input is always the runtime operator surface and must never expose recordInput literals.
-     For branches: use branchOverrides so each path is captured.
+     For branches: use ctx.branch(ctx.when.*, { then, else }) so both paths are captured. Use
+     branchOverrides only for compatibility with existing Feature handlers.
      Never make an authorization, validation, tenancy, or other security decision by branching on
      ctx.input during recording. Use ctx.sampleInput only to discover graph shape; enforce security
      invariants inside a runtime portable Function or recorded step.
@@ -4066,11 +4309,15 @@ When you call features.define({ handler }), the handler runs TWICE:
      integrations and project readiness hooks must not start HTTP listeners, provider probes,
      schedulers, or Event consumers. Apply the filter before booting unrelated service modules.
 
-  2. EXECUTION PHASE (at runtime) — handler is called with a real ExecutionContext.
-     ctx.step() actually executes. All real Ductape component calls happen.
-     Arbitrary JS logic (math, string ops, conditionals on step results) runs for real.
+  2. EXECUTION PHASE (at runtime) — the stored schema.steps graph is interpreted by FeatureExecutor.
+     The original JavaScript handler is NOT called. Step inputs and conditions resolve operators
+     such as $Input{}, $Sequence{}, $Step{}, and $Now against runtime state. Only recorded portable
+     component/function operations execute.
 
-  Implication: put all meaningful business logic INSIDE ctx.step() handlers, not in the
+  Implication: arbitrary JavaScript control flow never becomes runtime behavior merely because it
+  appears in the handler. Express runtime branches through ctx.branch/ctx.when, fixed graph expansion
+  through ctx.each(ctx.sampleInput...), and runtime-sized algorithms through ctx.functions. Put all
+  meaningful business logic INSIDE recorded portable operations, not in the
   outer handler body. Code in the outer body runs during recording with proxy values and
   may behave unexpectedly (e.g. typeof proxy === 'object' is true but .someField is a proxy).
 
@@ -5974,6 +6221,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: [
                     {
@@ -5981,6 +6260,8 @@ async function main() {
                         text: JSON.stringify({
                             payload: generated,
                             snippet,
+                            ...(databaseActionContract ? { database_action_contract: databaseActionContract } : {}),
+                            ...(featureExample ? { feature_example: featureExample } : {}),
                         }, null, 2),
                     },
                 ],
@@ -5993,6 +6274,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)) {
@@ -6124,11 +6499,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.31",
+  "version": "0.2.33",
   "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-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",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"
   },