@voxgig/sdkgen 4.16.0 → 4.17.0

package/project/.sdk/src/cmp/ts/TestEntity_ts.ts

@@ -169,13 +169,6 @@ function basicSetup(extra?: any) {
       }]
     })
 
-  // Detect whether the user provided a real ENTID JSON via env var. The
-  // basic flow consumes synthetic IDs from the fixture file; without an
-  // override those synthetic IDs reach the live API and 4xx. Surface this
-  // to the test so it can skip rather than fail.
-  const idmapEnvVal = process.env['${PROJENVNAME}_TEST_${ENTENVNAME}_ENTID']
-  const idmapOverridden = null != idmapEnvVal && idmapEnvVal.trim().startsWith('{')
-
   const env = envOverride({
     '${PROJENVNAME}_TEST_${ENTENVNAME}_ENTID': idmap,
     '${PROJENVNAME}_TEST_LIVE': 'FALSE',
@@ -186,7 +179,13 @@ function basicSetup(extra?: any) {
 
   const live = 'TRUE' === env.${PROJENVNAME}_TEST_LIVE
 
+  const transport = createLiveTransport()
   if (live) {
+    const rawIds = process.env['${PROJENVNAME}_TEST_${ENTENVNAME}_ENTID']
+    idmap = rawIds && rawIds.trim() ? JSON.parse(rawIds) : {}
+    if (!idmap || Array.isArray(idmap) || typeof idmap !== 'object') {
+      throw new Error('Live ENTID must be a JSON object')
+    }
     client = new ${model.Name}SDK(merge([
       // FIRST, so the generated fields below win: sdk-test-control.json's
       // test.client.options adds to the live client, it does not redirect it.
@@ -198,7 +197,8 @@ function basicSetup(extra?: any) {
       // argument at all - so a bare 'extra' silently discarded the apikey
       // and server values above and handed the SDK undefined. Harmless
       // while there was nothing in that object; not harmless now.
-      extra || {}
+      extra || {},
+      { system: { fetch: transport.fetch } }
     ]))
   }
 
@@ -211,7 +211,7 @@ function basicSetup(extra?: any) {
     data: entityData,
     explain: 'TRUE' === env.${PROJENVNAME}_TEST_EXPLAIN,
     live,
-    syntheticOnly: live && !idmapOverridden,
+    transport,
     now: Date.now(),
   }
 
@@ -239,16 +239,13 @@ function basicSetup(extra?: any) {
           Content(`
     const live = 'TRUE' === process.env.${PROJENVNAME}_TEST_LIVE
     for (const op of ${flowOpsLiteral}) {
-      if (maybeSkipControl(t, 'entityOp', '${entity.name}.' + op, live)) return
+      if (!live && maybeSkipControl(t, 'entityOp', '${entity.name}.' + op, live)) return
     }
 
+    ${Object.values(model.main.kit.entity || {}).some((e: any) => Object.values(e.op || {}).some((o: any) => (o.points || []).some((p: any) => p.contract && JSON.parse(p.contract.json).live))) ? `if (live) { t.skip('Covered by live operation scenarios'); return }` : ''}
     const setup = basicSetup()
-    // The basic flow consumes synthetic IDs and field values from the
-    // fixture (entity TestData.json). Those don't exist on the live API.
-    // Skip live runs unless the user provided a real ENTID env override.
-    if (setup.syntheticOnly) {
-      t.skip('live entity test uses synthetic IDs from fixture — set ${PROJENVNAME}_TEST_${ENTENVNAME}_ENTID JSON to run live')
-      return
+    if (setup.live) {
+      return runLiveEntity(setup, ${JSON.stringify(entity)}, ${JSON.stringify(basicflow)}, '${nom(entity, 'Name')}')
     }
     const client = setup.client
     const struct = setup.struct

package/project/.sdk/src/cmp/ts/TestLive_ts.ts

@@ -0,0 +1,32 @@
+import { cmp, File, Content, entityCollection, envName, serverVariables, serverVarEnv } from '@voxgig/sdkgen'
+import { nom } from '@voxgig/apidef'
+
+const TestLive = cmp(function TestLive(props: any) {
+  const model = props.ctx$.model
+  const plan: any[] = []
+  for (const entity of Object.values(entityCollection(model)) as any[]) {
+    if (entity.active === false) continue
+    for (const [op, operation] of Object.entries(entity.op || {}) as any[]) {
+      for (const point of operation.points || []) {
+        const facts = point.contract ? JSON.parse(point.contract.json) : {}
+        if (model.main.kit.info?.auth === false) facts.security = []
+        const same = operation.points.filter((p: any) => JSON.stringify(p.select || {}) === JSON.stringify(point.select || {}))
+        plan.push({ entity: entity.name, accessor: nom(entity, 'Name'), op,
+          id: point.contract?.id || point.method + ' ' + point.orig, contractVersion: point.contract?.version, kind: point.kind, graphql: point.graphql, path: point.orig, method: point.method,
+          action: point.select?.$action, rename: point.rename, args: point.args, facts, reachable: same.length === 1 })
+      }
+    }
+  }
+  if (!plan.some(p => p.facts.live)) return
+  const server = serverVariables(model).map((v: any) => JSON.stringify(v.name) + ': process.env[' + JSON.stringify(serverVarEnv(envName(model), v.name)) + '] ?? ' + JSON.stringify(v.dflt)).join(', ')
+  File({ name: 'live.test.ts' }, () => Content(`import { test } from 'node:test'
+import { SDK } from '..'
+import { runLiveScenarios } from './live-scenarios'
+import { loadEnvLocal } from './utility'
+loadEnvLocal(__dirname + '/../.env.local')
+test('live operation coverage', { skip: process.env.${envName(model)}_TEST_LIVE !== 'TRUE' }, async () => {
+  await runLiveScenarios(SDK, ${JSON.stringify(plan, null, 2)}, '${envName(model)}', { server: { ${server} }, secret: process.env.${envName(model)}_SECRET })
+})
+`))
+})
+export { TestLive }

package/project/.sdk/src/cmp/ts/Test_ts.ts

@@ -9,6 +9,7 @@ import { cmp, each, Folder, entityCollection,
 
 // import { Quick } from './Quick_ts'
 // import { TestMain } from './TestMain_ts'
+import { TestLive } from './TestLive_ts'
 import { TestDirect } from './TestDirect_ts'
 import { TestEntity } from './TestEntity_ts'
 import { ReadmeExampleTest } from './ReadmeExampleTest_ts'
@@ -23,6 +24,7 @@ const Test = cmp(function Test(props: any) {
 
     // Write-once: a project's edited control file survives regeneration.
     TestControl({ target, dir: 'test' })
+    TestLive({ target })
     // Quick({ target })
     // TestMain({ target })
 

package/project/.sdk/src/cmp/ts/fragment/Direct.test.fragment.ts

@@ -2,6 +2,7 @@
 
 import { test, describe, afterEach } from 'node:test'
 import assert from 'node:assert'
+import { createLiveTransport } from '../../live-runner'
 
 
 import { ProjectNameSDK } from '../../..'

package/project/.sdk/src/cmp/ts/fragment/Entity.test.fragment.ts

@@ -5,6 +5,8 @@ import * as Fs from 'node:fs'
 
 import { test, describe, afterEach } from 'node:test'
 import assert from 'node:assert'
+import { createLiveTransport } from '../../live-runner'
+import { runLiveEntity } from '../../live-entity'
 
 
 import { ProjectNameSDK, BaseFeature, stdutil } from '../../..'

package/project/.sdk/tm/csharp/test/feature/secrets/SecretsFeatureTest.cs

@@ -1394,9 +1394,16 @@ public class SecretsFeatureTest
             Parallel.For(0, 4, i =>
                 client.Direct(new Dictionary<string, object?> { ["path"] = "/p" + i }));
 
+            // REPORTS WHAT WENT OUT, not just how many. This assertion failed
+            // once in CI and passed on re-run, and the count alone could not
+            // say which of two very different faults it was: several
+            // purchases (the coalescing missed) or none (the exchange never
+            // ran). By the time anyone looked, the re-run had replaced the
+            // job log and the number was gone. Report() exists for exactly
+            // this, and the sibling assertions already use it.
             Assert.True(1 == w.Token().Count,
-                "four operations at once must not open four token requests, saw " +
-                w.Token().Count);
+                "four operations at once must open exactly ONE token request, saw " +
+                w.Token().Count + " — calls: " + w.Report());
         }
         finally
         {

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

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateContract = validateContract;
+exports.synthesizeInput = synthesizeInput;
+exports.requestContract = requestContract;
+const live_runner_1 = require("./live-runner");
+// Deliberately conservative: unsupported constraints block preparation instead
+// of labelling an invented value as live-valid. Errors never include values.
+function validateContract(schema, value, direction = 'request', depth = 0) {
+    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 live_runner_1.LiveBlocked('Unsupported contract constraint: ' + key);
+    }
+    if (schema.$ref)
+        throw new live_runner_1.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) => 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) => 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);
+        }
+    }
+}
+function synthesizeInput(schema, explicit, depth = 0) {
+    if (depth > 30)
+        throw new live_runner_1.LiveBlocked('Request schema nesting exceeds limit');
+    if (schema?.$ref)
+        throw new live_runner_1.LiveBlocked('Unresolved request reference');
+    if (explicit !== undefined) {
+        validateContract(schema, explicit);
+        return explicit;
+    }
+    if (!schema || schema === true)
+        throw new live_runner_1.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;
+    if (schema.allOf)
+        value = Object.assign({}, ...schema.allOf.map((s) => 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 live_runner_1.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 live_runner_1.LiveBlocked('Required input needs a guide recipe or validated example');
+    validateContract(schema, value);
+    return value;
+}
+function requestContract(facts) {
+    const body = facts?.requestBody;
+    if (body) {
+        const media = body.content?.['application/json'] ?? body.content?.['application/*+json'];
+        if (!media)
+            throw new live_runner_1.LiveBlocked('Unsupported request media type');
+        return { schema: media.schema, example: media.example ?? Object.values(media.examples || {}).map((v) => v.value)[0], required: body.required };
+    }
+    const arg = facts?.parameters?.find((p) => p.in === 'body');
+    return arg ? { schema: arg.schema, example: arg.example, required: arg.required } : {};
+}

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

@@ -0,0 +1,169 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runLiveEntity = runLiveEntity;
+const strict_1 = __importDefault(require("node:assert/strict"));
+const live_contract_1 = require("./live-contract");
+const live_runner_1 = require("./live-runner");
+const utility_1 = require("./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, entity, flow, accessor) {
+    const { client, transport } = setup;
+    const steps = flow.step || [];
+    const created = new Map();
+    const listed = [];
+    const marks = new Map();
+    const idField = entity.id?.field || 'id';
+    const copy = (value) => JSON.parse(JSON.stringify(value ?? {}));
+    const hasCreate = steps.some(step => step.op === 'create');
+    const report = await (0, live_runner_1.runLiveSteps)(steps.map((step, index) => {
+        const ref = step.input?.ref || entity.name + '_ref01';
+        const op = step.op;
+        const excluded = (0, utility_1.isControlSkipped)('entityOp', entity.name + '.' + op, 'live');
+        return {
+            id: entity.name + '.' + op + '.' + index,
+            cleanup: op === 'remove' || (step.valid || []).some((v) => v.apply === 'ItemNotExists'),
+            excluded: excluded.skip ? excluded.reason || 'Excluded by test control' : undefined,
+            run: async (context) => {
+                transport.enter(context);
+                const points = entity.op?.[op]?.points || [];
+                if (!points.length)
+                    throw new live_runner_1.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 live_runner_1.LiveBlocked('Create did not provide a usable resource');
+                }
+                if (op === 'remove' && !record)
+                    throw new live_runner_1.LiveBlocked('No resource created by this run');
+                if (op === 'remove' && !entity.id)
+                    throw new live_runner_1.LiveBlocked('No modelled resource identity for cleanup');
+                if (record && ['update', 'remove'].includes(op) && entity.id &&
+                    null == (record[idField] ?? record.id)) {
+                    throw new live_runner_1.LiveBlocked('Created resource has no usable identity');
+                }
+                let input = 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] ?? 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;
+                let selected;
+                const missing = new Set();
+                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) => 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 live_runner_1.LiveBlocked('No usable route; missing arguments: ' + [...missing].join(', '));
+                input = resolved;
+                if (op === 'create' && selected.contract) {
+                    const facts = JSON.parse(selected.contract.json);
+                    const request = (0, live_contract_1.requestContract)(facts);
+                    if (request.schema)
+                        input = { ...(0, live_contract_1.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;
+                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') {
+                    (0, strict_1.default)(Array.isArray(result), 'Expected a list of entity instances');
+                    const data = result.map((item) => {
+                        strict_1.default.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) => (item?.[idField] ?? item?.id) === id);
+                        if (validation.apply === 'ItemExists')
+                            (0, strict_1.default)(found, 'Created resource missing from list');
+                        if (validation.apply === 'ItemNotExists')
+                            (0, strict_1.default)(!found, 'Removed resource still in list');
+                    }
+                }
+                else {
+                    strict_1.default.equal(typeof result?.data, 'function', 'Expected an entity instance');
+                    const data = result.data();
+                    (0, strict_1.default)(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)
+                        (0, strict_1.default)(null != (data[idField] ?? data.id), 'Missing created identity');
+                    if (['load', 'update'].includes(op) && input.id != null && entity.id) {
+                        strict_1.default.equal(data[idField] ?? data.id, input.id, 'Response identity mismatch');
+                    }
+                    const mark = marks.get(ref);
+                    if (mark && ['update', 'load'].includes(op)) {
+                        strict_1.default.equal(data[mark.name], mark.value, 'Updated field mismatch');
+                    }
+                }
+            },
+        };
+    }), {
+        delayMs: (0, utility_1.liveDelayMs)(),
+        report: result => console.log('LIVE STEP ' + JSON.stringify(result)),
+    });
+    console.log('LIVE SUMMARY ' + JSON.stringify({ entity: entity.name, ...report }));
+    (0, live_runner_1.assertLiveReport)(report);
+}

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;
+        },
+    };
+}