@voxgig/sdkgen 4.16.0 → 4.17.1

package/project/.sdk/tm/js/test/live-runner.js

@@ -0,0 +1,129 @@
+"use strict";
+// Execute every independent live step before deciding the suite's result.
+// Values never appear in reports: they can contain credentials or API data.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveBlocked = void 0;
+exports.runLiveSteps = runLiveSteps;
+exports.assertLiveReport = assertLiveReport;
+exports.createLiveTransport = createLiveTransport;
+class LiveBlocked extends Error {
+}
+exports.LiveBlocked = LiveBlocked;
+async function runLiveSteps(steps, options = {}) {
+    const values = new Map();
+    const results = [];
+    const ids = new Set();
+    for (const step of steps) {
+        if (!step.id || ids.has(step.id))
+            throw new Error('Duplicate or empty live step id');
+        ids.add(step.id);
+    }
+    const record = (result) => {
+        const step = steps.find(step => step.id === result.id);
+        if (step?.role)
+            result.role = step.role;
+        if (step?.retention && result.attempted)
+            result.retention = step.retention;
+        results.push(result);
+        options.report?.(result);
+    };
+    // Cleanup runs after ordinary work, even if an assertion failed after a
+    // resource was created. A step publishes usable data before assertions.
+    for (const cleanup of [false, true]) {
+        const pending = steps.filter(step => !!step.cleanup === cleanup);
+        while (pending.length) {
+            let progressed = false;
+            for (let i = 0; i < pending.length;) {
+                const step = pending[i];
+                const missing = (step.needs || []).filter(id => !values.has(id) ||
+                    (!cleanup && results.some(result => result.id === id && result.state !== 'passed')));
+                if (!step.excluded && missing.some(id => pending.some(other => other.id === id))) {
+                    i++;
+                    continue;
+                }
+                pending.splice(i, 1);
+                progressed = true;
+                if (step.excluded) {
+                    record({ id: step.id, state: 'excluded', attempted: false, reason: step.excluded });
+                    continue;
+                }
+                if (missing.length) {
+                    record({ id: step.id, state: 'blocked', attempted: false,
+                        reason: 'Missing output: ' + missing.join(', ') });
+                    continue;
+                }
+                let attempted = false;
+                const requests = [];
+                try {
+                    await step.run({
+                        values,
+                        publish: value => { if (undefined !== value)
+                            values.set(step.id, value); },
+                        attempted: () => { attempted = true; },
+                        requests,
+                    });
+                    if (!attempted)
+                        throw new LiveBlocked('No request attempted');
+                    record({ id: step.id, state: 'passed', attempted, requests });
+                }
+                catch (error) {
+                    // Ordinary SDK errors can contain request headers, bodies, or an
+                    // issued token. Report the step's failure without serializing it.
+                    record({ id: step.id, state: error instanceof LiveBlocked ? 'blocked' : 'failed',
+                        attempted, requests,
+                        reason: error instanceof LiveBlocked ? error.message : 'Request or assertion failed' });
+                }
+                if (attempted && (options.delayMs || 0) > 0) {
+                    await new Promise(resolve => setTimeout(resolve, options.delayMs));
+                }
+            }
+            if (!progressed) {
+                for (const step of pending.splice(0)) {
+                    record({ id: step.id, state: 'blocked', attempted: false,
+                        reason: 'Cyclic or unavailable dependency' });
+                }
+            }
+        }
+    }
+    return {
+        planned: steps.length,
+        attempted: results.filter(result => result.attempted).length,
+        passed: results.filter(result => result.state === 'passed').length,
+        failed: results.filter(result => result.state === 'failed').length,
+        blocked: results.filter(result => result.state === 'blocked').length,
+        excluded: results.filter(result => result.state === 'excluded').length,
+        results,
+    };
+}
+function assertLiveReport(report) {
+    if (report.failed || report.blocked || !report.attempted) {
+        throw new Error('Live coverage incomplete: ' + JSON.stringify(report));
+    }
+}
+function createLiveTransport(timeoutMs = 30000) {
+    let context;
+    const requests = [];
+    const nativeFetch = globalThis.fetch;
+    return {
+        requests,
+        enter(next) { context = next; },
+        fetch: async (input, init) => {
+            const url = new URL(String(input));
+            const request = {
+                method: init?.method || 'GET', path: url.origin + url.pathname,
+            };
+            requests.push(request);
+            context?.requests.push(request);
+            context?.attempted();
+            if (!context)
+                console.log('LIVE REQUEST ' + JSON.stringify(request));
+            const timeout = AbortSignal.timeout(timeoutMs);
+            const signal = init?.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
+            const response = await nativeFetch(input, { ...init, signal });
+            request.status = response.status;
+            if (!context)
+                console.log('LIVE RESPONSE ' + JSON.stringify(request));
+            return response;
+        },
+    };
+}

package/project/.sdk/tm/js/test/live-scenarios.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRecipe = resolveRecipe;
+exports.recipeNeeds = recipeNeeds;
+exports.runLiveScenarios = runLiveScenarios;
+const strict_1 = __importDefault(require("node:assert/strict"));
+const live_runner_1 = require("./live-runner");
+const live_contract_1 = require("./live-contract");
+const utility_1 = require("./utility");
+const at = (value, path) => (path || '').split('.').filter(Boolean).reduce((v, k) => v?.[k], value);
+function resolveRecipe(recipe, values) {
+    if (Array.isArray(recipe))
+        return recipe.map(v => resolveRecipe(v, values));
+    if (recipe && typeof recipe === 'object') {
+        if (recipe.from) {
+            if (!values.has(recipe.from))
+                throw new live_runner_1.LiveBlocked('Missing recipe output: ' + recipe.from);
+            let value = values.get(recipe.from);
+            if (recipe.where) {
+                if (!Array.isArray(value))
+                    throw new live_runner_1.LiveBlocked('Discovery output is not a list');
+                value = value.find((item) => Object.entries(recipe.where).every(([k, v]) => at(item, k) === v) &&
+                    (!recipe.related || (values.get(recipe.related.from) || []).some((other) => at(item, recipe.related.local) === at(other, recipe.related.foreign) &&
+                        Object.entries(recipe.related.where || {}).every(([k, v]) => at(other, k) === v))));
+            }
+            value = at(value, recipe.path);
+            if (value === undefined || value === null)
+                throw new live_runner_1.LiveBlocked('Discovery found no compatible value');
+            return value;
+        }
+        return Object.fromEntries(Object.entries(recipe).map(([k, v]) => [k, resolveRecipe(v, values)]));
+    }
+    return recipe;
+}
+function recipeNeeds(value) {
+    if (!value || typeof value !== 'object')
+        return [];
+    return [...new Set([...(typeof value.from === 'string' ? [value.from] : []), ...Object.values(value).flatMap(recipeNeeds)])];
+}
+async function runLiveScenarios(SDK, plan, envPrefix, liveDefaults = {}) {
+    const transport = (0, live_runner_1.createLiveTransport)();
+    const steps = plan.map(point => {
+        const hint = point.facts.live || {};
+        const control = (0, utility_1.isControlSkipped)('entityOp', point.entity + '.' + point.op, 'live');
+        return { role: hint.auth || (point.facts.security?.length === 0 || point.facts.securitySource === 'unspecified' ? 'public' : 'account'), retention: hint.retention, id: hint.id || point.id, needs: [...new Set([...(hint.needs || []), ...recipeNeeds(hint.input), ...recipeNeeds(hint.credential), ...recipeNeeds(hint.assert)])],
+            cleanup: !!hint.cleanup,
+            excluded: control.skip ? control.reason || 'Excluded by test control' : hint.excluded,
+            run: async (ctx) => {
+                transport.enter(ctx);
+                if (point.contractVersion && point.contractVersion !== 1)
+                    throw new live_runner_1.LiveBlocked('Unsupported operation contract version');
+                if (point.op === 'remove' || hint.cleanup) {
+                    const owned = recipeNeeds(hint.input).some(id => plan.some(source => (source.facts.live?.id || source.id) === id && source.entity === point.entity && source.op === 'create'));
+                    if (!owned)
+                        throw new live_runner_1.LiveBlocked('Cleanup input is not bound to a resource created by this run');
+                }
+                if (!point.reachable)
+                    throw new live_runner_1.LiveBlocked('Point selector is indistinguishable; add a guide action');
+                const request = (0, live_contract_1.requestContract)(point.facts);
+                const explicit = hint.input === undefined ? request.example : resolveRecipe(hint.input, ctx.values);
+                let input = request.schema ? (0, live_contract_1.synthesizeInput)(request.schema, explicit) : explicit ?? {};
+                for (const kind of ['params', 'query', 'header', 'cookie'])
+                    for (const arg of point.args?.[kind] || []) {
+                        if (arg.reqd && input[arg.name] === undefined) {
+                            if (arg.example === undefined)
+                                throw new live_runner_1.LiveBlocked('Missing required argument: ' + arg.name);
+                            input[arg.name] = arg.example;
+                        }
+                    }
+                const role = hint.auth || (point.facts.security?.length === 0 || point.facts.securitySource === 'unspecified' ? 'public' : 'account');
+                let apikey = role === 'public' ? null : role === 'issued' ? resolveRecipe(hint.credential, ctx.values) : process.env[envPrefix + '_APIKEY'];
+                if (role === 'issued' && (typeof apikey !== 'string' || !apikey))
+                    throw new live_runner_1.LiveBlocked('Issued credential unavailable');
+                let wire;
+                let wireSchema;
+                const options = (0, utility_1.liveClientOptions)();
+                const client = new SDK({ ...options, ...liveDefaults, apikey,
+                    feature: { ...options.feature, test: { active: false }, retry: { active: false },
+                        secrets: { ...options.feature?.secrets, active: role === 'account' && (!apikey || options.feature?.secrets?.active === true) } },
+                    system: { ...options.system, fetch: async (url, init) => {
+                            const headers = new Headers(init?.headers);
+                            if (role === 'public')
+                                (0, strict_1.default)(!headers.has('authorization'), 'Public request carries authentication');
+                            else if (!headers.get('authorization'))
+                                throw new live_runner_1.LiveBlocked('Credential unavailable for ' + role + ' request');
+                            const response = await transport.fetch(url, { ...init, redirect: 'error' });
+                            const expectedPath = point.path.replace(/\{([^}]+)\}/g, (_, name) => encodeURIComponent(input[point.rename?.param?.[name] || name] ?? input[name]));
+                            if (point.kind === 'graphql') {
+                                const payload = JSON.parse(init.body);
+                                strict_1.default.equal(payload.query, point.graphql.doc, 'Entity selected wrong GraphQL operation');
+                            }
+                            else
+                                strict_1.default.equal(new URL(String(url)).pathname, expectedPath, 'Entity selected wrong route');
+                            strict_1.default.equal(init?.method || 'GET', point.method);
+                            (0, strict_1.default)(response.status >= 200 && response.status < 300, 'Unsuccessful HTTP response');
+                            if (point.kind === 'graphql')
+                                wire = await response.clone().json();
+                            const def = point.facts.responses?.[response.status] || point.facts.responses?.[String(response.status)[0] + 'XX'] || point.facts.responses?.default;
+                            if (point.facts.responses && !def)
+                                throw new Error('Undeclared response status');
+                            if (def) {
+                                const schema = def.content?.['application/json']?.schema ?? def.schema;
+                                if (schema && response.status !== 204) {
+                                    wireSchema = schema;
+                                    wire = await response.clone().json();
+                                }
+                            }
+                            return response;
+                        } } });
+                if (point.action)
+                    input = { ...input, $action: point.action };
+                (0, strict_1.default)(JSON.stringify(input).length <= 1024 * 1024, 'Request exceeds test payload limit');
+                const result = await client[point.accessor]()[point.op](input);
+                const data = Array.isArray(result) ? result.map(item => { strict_1.default.equal(typeof item?.data, 'function'); return item.data(); }) : (strict_1.default.equal(typeof result?.data, 'function'), result.data());
+                ctx.publish(data);
+                if (wireSchema)
+                    (0, live_contract_1.validateContract)(wireSchema, wire, 'response');
+                if (Array.isArray(wire?.errors) && wire.errors.length)
+                    throw new Error('GraphQL operation reported errors');
+                if (wire?.success === false)
+                    throw new Error('API reported unsuccessful operation');
+                const checks = resolveRecipe(hint.assert || {}, ctx.values);
+                for (const [path, expected] of Object.entries(checks.equal || {}))
+                    strict_1.default.deepEqual(at(data, path), expected);
+                for (const path of checks.nonempty || [])
+                    (0, strict_1.default)(at(data, path)?.length > 0, 'Empty required output');
+                if (checks.vectors) {
+                    const vectors = at(data, checks.vectors.path);
+                    (0, strict_1.default)(Array.isArray(vectors) && vectors.length === checks.vectors.count);
+                    for (const vector of vectors)
+                        (0, strict_1.default)(Array.isArray(vector) && vector.length === checks.vectors.dimension && vector.every((n) => typeof n === 'number' && Number.isFinite(n)), 'Invalid vector shape');
+                }
+            } };
+    });
+    const report = await (0, live_runner_1.runLiveSteps)(steps, { delayMs: (0, utility_1.liveDelayMs)(), report: result => console.log('LIVE STEP ' + JSON.stringify(result)) });
+    console.log('LIVE SUMMARY ' + JSON.stringify(report));
+    (0, live_runner_1.assertLiveReport)(report);
+    return report;
+}

package/project/.sdk/tm/js/test/utility.js

@@ -148,7 +148,91 @@ function liveDelay(liveEnvVar) {
   }
 }
 
+function isControlSkipped(kind, name, mode) {
+    const ctrl = loadTestControl();
+    const list = ctrl?.test?.skip?.[mode]?.[kind] ?? [];
+    for (const e of list) {
+        if (kind === 'direct' && e?.test === name) {
+            return { skip: true, reason: e.reason };
+        }
+        if (kind === 'entityOp') {
+            const key = (e?.entity ?? '') + '.' + (e?.op ?? '');
+            if (key === name)
+                return { skip: true, reason: e.reason };
+        }
+    }
+    return { skip: false };
+}
+function maybeSkipControl(t, kind, name, live) {
+    const decision = isControlSkipped(kind, name, live ? 'live' : 'unit');
+    if (decision.skip) {
+        t.skip(decision.reason || 'skipped via sdk-test-control.json');
+        return true;
+    }
+    return false;
+}
+function skipIfMissingIds(t, setup, requiredKeys) {
+    if (!setup.live)
+        return false;
+    const missing = requiredKeys.filter(k => null == setup.idmap?.[k]);
+    if (missing.length > 0) {
+        throw new Error(`Live test blocked: needs ${missing.join(', ')} via *_ENTID env var`);
+    }
+    return false;
+}
+function loadEnvLocal(file) {
+    let text;
+    try {
+        text = Fs.readFileSync(file, 'utf8');
+    }
+    catch (err) {
+        if ('ENOENT' === err.code) {
+            return;
+        }
+        throw err;
+    }
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        // Blank and comment lines. A '#' INSIDE a value is not a comment.
+        if ('' === line || line.startsWith('#')) {
+            continue;
+        }
+        const eq = line.indexOf('=');
+        if (0 >= eq) {
+            continue;
+        }
+        const key = line.slice(0, eq).trim().replace(/^export\s+/, '');
+        let val = line.slice(eq + 1).trim();
+        const quote = ("'" === val[0] || '"' === val[0]) ? val[0] : '';
+        if ('' !== quote) {
+            // Quoted: the value runs to the CLOSING quote, and a '#' inside it is
+            // part of the value. Anything after the closing quote is a comment.
+            const close = val.indexOf(quote, 1);
+            val = 0 < close ? val.slice(1, close) : val.slice(1);
+        }
+        else {
+            // Unquoted: the first '#' starts an inline comment, with or without
+            // preceding whitespace — `A=a#b` is `a` to dotenv, not `a#b`.
+            // Dropping this made `KEY=secret # note` resolve to the whole string
+            // including the note, and a generated live test would then send that
+            // as the credential. Verified against dotenv's own parse().
+            const hash = val.indexOf('#');
+            if (0 <= hash) {
+                val = val.slice(0, hash);
+            }
+            val = val.trim();
+        }
+        if (undefined === process.env[key]) {
+            process.env[key] = val;
+        }
+    }
+}
+
 module.exports = {
+  isControlSkipped,
+  maybeSkipControl,
+  skipIfMissingIds,
+  loadEnvLocal,
   makeStepData,
   makeMatch,
   makeReqdata,

package/project/.sdk/tm/php/test/feature/secrets/SecretsTest.php

@@ -240,7 +240,7 @@ class ProjectNameSecretsTest extends TestCase
     // seeded data, a scripted response); an op the API does not define fails
     // before it reaches the transport, which is why several may need
     // driving.
-    private function driveUntil($client, string $what, callable $stop): void
+    private function driveUntil($client, string $what, callable $stop, ?callable $onError = null): void
     {
         foreach ($this->entityAccessors($client) as $accessor) {
             try {
@@ -255,7 +255,10 @@ class ProjectNameSecretsTest extends TestCase
                 try {
                     $ent->$opname();
                 } catch (\Throwable $e) {
-                    // The op's own failure is not the assertion.
+                    // The op's own failure is not the assertion unless observed.
+                    if ($onError !== null) {
+                        $onError($e);
+                    }
                 }
                 if ($stop()) {
                     return;
@@ -265,6 +268,20 @@ class ProjectNameSecretsTest extends TestCase
         $this->fail('no entity operation ' . $what . ' - nothing to assert on');
     }
 
+    // Capture a refusal from an operation this API actually defines.
+    private function entityError($client): ProjectNameError
+    {
+        $caught = null;
+        $this->driveUntil($client, 'returned an SDK error',
+            function () use (&$caught) { return $caught !== null; },
+            function (\Throwable $error) use (&$caught) {
+                if ($error instanceof ProjectNameError) {
+                    $caught = $error;
+                }
+            });
+        return $caught;
+    }
+
     // Drive ops until one request reached the recorder.
     private function driveOp($client, ProjectNameSecretsWire $wire): void
     {
@@ -469,15 +486,7 @@ class ProjectNameSecretsTest extends TestCase
             ]],
         ]);
 
-        $accessor = $this->entityAccessors($client)[0] ?? null;
-        $this->assertNotNull($accessor, 'no entity accessor - nothing to assert on');
-
-        $caught = null;
-        try {
-            $client->$accessor()->list();
-        } catch (ProjectNameError $e) {
-            $caught = $e;
-        }
+        $caught = $this->entityError($client);
 
         $this->assertNotNull($caught, 'the entity path must fail closed');
         $this->assertStringContainsString('vault unreachable', $caught->msg);
@@ -970,15 +979,8 @@ class ProjectNameSecretsTest extends TestCase
             ]],
         ]);
 
-        $accessor = $this->entityAccessors($client)[0] ?? null;
-        $this->assertNotNull($accessor);
-
-        try {
-            $client->$accessor()->list();
-            $this->fail('the op must fail closed');
-        } catch (ProjectNameError $e) {
-            // expected
-        }
+        $caught = $this->entityError($client);
+        $this->assertStringContainsString('vault unreachable', $caught->msg);
 
         $this->assertSame(1, $calls, 'the refusal must not be retried');
         $this->assertCount(0, $wire->calls);

package/project/.sdk/tm/ts/test/live-contract.ts

@@ -0,0 +1,104 @@
+import { LiveBlocked } from './live-runner'
+
+// Deliberately conservative: unsupported constraints block preparation instead
+// of labelling an invented value as live-valid. Errors never include values.
+export function validateContract(schema: any, value: any, direction = 'request', depth = 0): void {
+  const bad = () => { throw new Error('Operation contract mismatch') }
+  if (depth > 40 || schema === false) return bad()
+  if (schema === true || schema == null) return
+  for (const key of ['if', 'then', 'else', 'dependentRequired', 'dependentSchemas', 'patternProperties', 'contains', 'unevaluatedProperties', 'unevaluatedItems']) {
+    if (schema[key] !== undefined) throw new LiveBlocked('Unsupported contract constraint: ' + key)
+  }
+  if (schema.$ref) throw new LiveBlocked('Unresolved contract reference')
+  if (value === null && (schema.nullable || schema.type === 'null' || schema.type?.includes?.('null'))) return
+  for (const sub of schema.allOf || []) validateContract(sub, value, direction, depth + 1)
+  for (const key of ['oneOf', 'anyOf']) if (schema[key]) {
+    let matches = 0
+    for (const sub of schema[key]) { try { validateContract(sub, value, direction, depth + 1); matches++ } catch {} }
+    if (key === 'oneOf' ? matches !== 1 : matches === 0) bad()
+  }
+  if (schema.not) { let matched = true; try { validateContract(schema.not, value, direction, depth + 1) } catch { matched = false }; if (matched) bad() }
+  if (schema.const !== undefined && JSON.stringify(value) !== JSON.stringify(schema.const)) bad()
+  if (schema.enum && !schema.enum.some((v: any) => JSON.stringify(v) === JSON.stringify(value))) bad()
+  const kind = value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value
+  const types = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : []
+  if (types.length && !types.some((t: string) => t === kind || t === 'integer' && Number.isInteger(value))) bad()
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) bad()
+    if (schema.minimum !== undefined && value < schema.minimum || schema.maximum !== undefined && value > schema.maximum) bad()
+    if (typeof schema.exclusiveMinimum === 'number' && value <= schema.exclusiveMinimum || schema.exclusiveMinimum === true && value <= schema.minimum) bad()
+    if (typeof schema.exclusiveMaximum === 'number' && value >= schema.exclusiveMaximum || schema.exclusiveMaximum === true && value >= schema.maximum) bad()
+    if (schema.multipleOf && Math.abs(value / schema.multipleOf - Math.round(value / schema.multipleOf)) > 1e-8) bad()
+  }
+  if (typeof value === 'string') {
+    if (value.length < (schema.minLength || 0) || value.length > (schema.maxLength ?? Infinity)) bad()
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) bad()
+    if (schema.format === 'date-time' && !Number.isFinite(Date.parse(value))) bad()
+    if (schema.format === 'date' && !/^\d{4}-\d{2}-\d{2}$/.test(value)) bad()
+    if (schema.format === 'uuid' && !/^[\da-f]{8}(-[\da-f]{4}){3}-[\da-f]{12}$/i.test(value)) bad()
+    if (schema.format === 'email' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) bad()
+  }
+  if (Array.isArray(value)) {
+    if (value.length < (schema.minItems || 0) || value.length > (schema.maxItems ?? Infinity)) bad()
+    if (schema.uniqueItems && new Set(value.map(v => JSON.stringify(v))).size !== value.length) bad()
+    value.forEach((v, i) => validateContract(schema.prefixItems?.[i] ?? schema.items, v, direction, depth + 1))
+  } else if (value !== null && typeof value === 'object') {
+    for (const key of schema.required || []) {
+      const prop = schema.properties?.[key]
+      if (direction === 'request' && prop?.readOnly || direction === 'response' && prop?.writeOnly) continue
+      if (value[key] === undefined) bad()
+    }
+    for (const [key, v] of Object.entries(value)) {
+      const prop = schema.properties?.[key]
+      if (direction === 'request' && prop?.readOnly || direction === 'response' && prop?.writeOnly) bad()
+      if (prop === undefined && schema.additionalProperties === false) bad()
+      validateContract(prop ?? schema.additionalProperties, v, direction, depth + 1)
+    }
+  }
+}
+
+export function synthesizeInput(schema: any, explicit?: any, depth = 0): any {
+  if (depth > 30) throw new LiveBlocked('Request schema nesting exceeds limit')
+  if (schema?.$ref) throw new LiveBlocked('Unresolved request reference')
+  if (explicit !== undefined) { validateContract(schema, explicit); return explicit }
+  if (!schema || schema === true) throw new LiveBlocked('No request contract or input recipe')
+  for (const key of ['example', 'default', 'const']) if (schema[key] !== undefined) {
+    try { validateContract(schema, schema[key]); return schema[key] } catch {}
+  }
+  for (const value of schema.examples || schema.enum || []) {
+    try { validateContract(schema, value); return value } catch {}
+  }
+  for (const choice of schema.oneOf || schema.anyOf || []) {
+    try { const v = synthesizeInput(choice, undefined, depth + 1); validateContract(schema, v); return v } catch {}
+  }
+  let value: any
+  if (schema.allOf) value = Object.assign({}, ...schema.allOf.map((s: any) => synthesizeInput(s, undefined, depth + 1)))
+  else if (schema.type === 'object' || schema.properties) {
+    value = {}
+    for (const key of schema.required || []) if (!schema.properties?.[key]?.readOnly) {
+      value[key] = synthesizeInput(schema.properties?.[key], undefined, depth + 1)
+    }
+  } else if (schema.type === 'array') {
+    const count = Math.max(1, schema.minItems || 0)
+    if (count > 16) throw new LiveBlocked('Required input array exceeds test payload limit')
+    value = Array.from({ length: count }, () => synthesizeInput(schema.items, undefined, depth + 1))
+  } else if (schema.type === 'integer' || schema.type === 'number') {
+    value = Math.max(1, schema.minimum ?? 1)
+    if (typeof schema.exclusiveMinimum === 'number') value = Math.max(value, schema.exclusiveMinimum + 1)
+    if (schema.multipleOf) value = Math.ceil(value / schema.multipleOf) * schema.multipleOf
+  } else if (schema.type === 'boolean') value = true
+  else throw new LiveBlocked('Required input needs a guide recipe or validated example')
+  validateContract(schema, value)
+  return value
+}
+
+export function requestContract(facts: any): { schema?: any, example?: any, required?: boolean } {
+  const body = facts?.requestBody
+  if (body) {
+    const media = body.content?.['application/json'] ?? body.content?.['application/*+json']
+    if (!media) throw new LiveBlocked('Unsupported request media type')
+    return { schema: media.schema, example: media.example ?? Object.values(media.examples || {}).map((v: any) => v.value)[0], required: body.required }
+  }
+  const arg = facts?.parameters?.find((p: any) => p.in === 'body')
+  return arg ? { schema: arg.schema, example: arg.example, required: arg.required } : {}
+}