@voxgig/sdkgen 4.16.0 → 4.17.0

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/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 } : {}
+}

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

@@ -0,0 +1,142 @@
+import assert from 'node:assert/strict'
+import { requestContract, synthesizeInput } from './live-contract'
+import { runLiveSteps, assertLiveReport, LiveBlocked } from './live-runner'
+import { isControlSkipped, liveDelayMs } from './utility'
+
+// The offline flow keeps its deterministic fixture assertions. Live flows
+// resolve real prerequisites per operation and collect failures until done.
+async function runLiveEntity(setup: any, entity: any, flow: any, accessor: string) {
+  const { client, transport } = setup
+  const steps: any[] = flow.step || []
+  const created = new Map<string, any>()
+  const listed: any[] = []
+  const marks = new Map<string, { name: string, value: any }>()
+  const idField = entity.id?.field || 'id'
+  const copy = (value: any) => JSON.parse(JSON.stringify(value ?? {}))
+  const hasCreate = steps.some(step => step.op === 'create')
+  const report = await runLiveSteps(steps.map((step, index) => {
+    const ref = step.input?.ref || entity.name + '_ref01'
+    const op = step.op
+    const excluded = isControlSkipped('entityOp', entity.name + '.' + op, 'live')
+    return {
+      id: entity.name + '.' + op + '.' + index,
+      cleanup: op === 'remove' || (step.valid || []).some((v: any) => v.apply === 'ItemNotExists'),
+      excluded: excluded.skip ? excluded.reason || 'Excluded by test control' : undefined,
+      run: async (context: any) => {
+        transport.enter(context)
+        const points = entity.op?.[op]?.points || []
+        if (!points.length) throw new LiveBlocked('No modelled operation point')
+        const record = created.get(ref)
+        // A failed create must not turn a later update/remove into a write
+        // against an arbitrary record found by a list operation.
+        if ((op === 'update' || op === 'remove') && hasCreate && !record) {
+          throw new LiveBlocked('Create did not provide a usable resource')
+        }
+        if (op === 'remove' && !record) throw new LiveBlocked('No resource created by this run')
+        if (op === 'remove' && !entity.id) throw new LiveBlocked('No modelled resource identity for cleanup')
+        if (record && ['update', 'remove'].includes(op) && entity.id &&
+            null == (record[idField] ?? record.id)) {
+          throw new LiveBlocked('Created resource has no usable identity')
+        }
+
+        let input: any = op === 'create'
+          ? copy(setup.data.new?.[entity.name]?.[ref]) : {}
+        for (const [name, binding] of Object.entries({ ...step.match, ...step.data })) {
+          const value = setup.idmap[binding as string] ?? setup.idmap[name]
+          if (undefined !== value) input[name] = value
+        }
+        const loaded = record || (op === 'load' ? listed[0] : undefined)
+        if (loaded && ['load', 'update', 'remove'].includes(op)) {
+          const id = loaded[idField] ?? loaded.id
+          if (undefined !== id) input.id = id
+        }
+        // A nested route needing a parent id must not hide an available
+        // parameter-free route for the same operation. Use the first viable
+        // candidate; the SDK still performs its normal route selection.
+        let resolved: any
+        let selected: any
+        const missing = new Set<string>()
+        for (const point of points) {
+          if (point.select?.$action !== input.$action) continue
+          const candidate = { ...input }
+          let viable = true
+          const params = point.args?.params || []
+          const query = (point.args?.query || []).filter((arg: any) => arg.reqd)
+          for (const arg of [...params, ...query]) {
+            if (undefined !== candidate[arg.name] && null !== candidate[arg.name]) continue
+            const key = arg.name === 'id' ? entity.name + '01' : arg.name.replace(/_id$/, '') + '01'
+            const value = setup.idmap[key] ?? setup.idmap[arg.name] ?? loaded?.[arg.name] ?? arg.example
+            if (undefined !== value && null !== value) candidate[arg.name] = value
+            else if (arg.reqd !== false) { viable = false; missing.add(arg.name) }
+          }
+          if (viable) { resolved = candidate; selected = point; break }
+        }
+        if (!resolved) throw new LiveBlocked('No usable route; missing arguments: ' + [...missing].join(', '))
+        input = resolved
+        if (op === 'create' && selected.contract) {
+          const facts = JSON.parse(selected.contract.json)
+          const request = requestContract(facts)
+          if (request.schema) input = { ...synthesizeInput(request.schema, facts.live?.input ?? request.example) }
+          else if (facts.protocol === 'http') input = {}
+          for (const arg of selected.args?.params || []) if (resolved[arg.name] !== undefined) input[arg.name] = resolved[arg.name]
+        }
+        let intendedMark: { name: string, value: any } | undefined
+        if (op === 'update') {
+          for (const spec of step.spec || []) {
+            if (spec.apply === 'TextFieldMark' && step.input?.textfield) {
+              const mark = { name: step.input.textfield, value: spec.def.mark + '_' + setup.now }
+              input[mark.name] = mark.value
+              intendedMark = mark
+            }
+          }
+        }
+
+        // A fresh entity prevents state left by a failed operation from
+        // changing the request for the next independent operation.
+        const result = await client[accessor]()[op](input)
+        if (intendedMark) marks.set(ref, intendedMark)
+        if (op === 'list') {
+          assert(Array.isArray(result), 'Expected a list of entity instances')
+          const data = result.map((item: any) => {
+            assert.equal(typeof item?.data, 'function')
+            return item.data()
+          })
+          listed.splice(0, listed.length, ...data)
+          context.publish(data)
+          for (const validation of step.valid || []) {
+            const previous = created.get(validation.def?.ref)
+            const id = previous?.[idField] ?? previous?.id
+            if (undefined === id) continue
+            const found = data.some((item: any) => (item?.[idField] ?? item?.id) === id)
+            if (validation.apply === 'ItemExists') assert(found, 'Created resource missing from list')
+            if (validation.apply === 'ItemNotExists') assert(!found, 'Removed resource still in list')
+          }
+        }
+        else {
+          assert.equal(typeof result?.data, 'function', 'Expected an entity instance')
+          const data = result.data()
+          assert(null != data, 'Expected operation data')
+          // Publish before assertion checks: cleanup still needs the id
+          // when the server created a resource with incorrect field values.
+          if (op === 'create') created.set(ref, data)
+          context.publish(data)
+          if (op === 'create' && entity.id) assert(null != (data[idField] ?? data.id), 'Missing created identity')
+          if (['load', 'update'].includes(op) && input.id != null && entity.id) {
+            assert.equal(data[idField] ?? data.id, input.id, 'Response identity mismatch')
+          }
+          const mark = marks.get(ref)
+          if (mark && ['update', 'load'].includes(op)) {
+            assert.equal(data[mark.name], mark.value, 'Updated field mismatch')
+          }
+        }
+      },
+    }
+  }), {
+    delayMs: liveDelayMs(),
+    report: result => console.log('LIVE STEP ' + JSON.stringify(result)),
+  })
+  console.log('LIVE SUMMARY ' + JSON.stringify({ entity: entity.name, ...report }))
+  assertLiveReport(report)
+}
+
+export { runLiveEntity }

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

@@ -0,0 +1,166 @@
+// Execute every independent live step before deciding the suite's result.
+// Values never appear in reports: they can contain credentials or API data.
+
+type LiveState = 'passed' | 'failed' | 'blocked' | 'excluded'
+
+type LiveResult = {
+  id: string
+  state: LiveState
+  attempted: boolean
+  role?: string
+  retention?: string
+  reason?: string
+  requests?: { method: string, path: string, status?: number }[]
+}
+
+type LiveContext = {
+  values: Map<string, any>
+  publish(value: any): void
+  attempted(): void
+  requests: { method: string, path: string, status?: number }[]
+}
+
+type LiveStep = {
+  id: string
+  needs?: string[]
+  cleanup?: boolean
+  role?: string
+  retention?: string
+  excluded?: string
+  run(ctx: LiveContext): Promise<void>
+}
+
+class LiveBlocked extends Error {}
+
+type LiveReport = {
+  planned: number
+  attempted: number
+  passed: number
+  failed: number
+  blocked: number
+  excluded: number
+  results: LiveResult[]
+}
+
+async function runLiveSteps(
+  steps: LiveStep[],
+  options: { delayMs?: number, report?: (result: LiveResult) => void } = {},
+): Promise<LiveReport> {
+  const values = new Map<string, any>()
+  const results: LiveResult[] = []
+  const ids = new Set<string>()
+  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: LiveResult) => {
+    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: LiveContext['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: LiveReport): void {
+  if (report.failed || report.blocked || !report.attempted) {
+    throw new Error('Live coverage incomplete: ' + JSON.stringify(report))
+  }
+}
+
+function createLiveTransport(timeoutMs = 30000) {
+  let context: LiveContext | undefined
+  const requests: LiveContext['requests'] = []
+  const nativeFetch = globalThis.fetch
+  return {
+    requests,
+    enter(next: LiveContext) { context = next },
+    fetch: async (input: any, init?: any) => {
+      const url = new URL(String(input))
+      const request: LiveContext['requests'][number] = {
+        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
+    },
+  }
+}
+
+export { runLiveSteps, assertLiveReport, LiveBlocked, createLiveTransport }
+export type { LiveStep, LiveContext, LiveReport, LiveResult }