@voxgig/sdkgen 4.33.0 → 4.34.1

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

@@ -10,6 +10,9 @@ const assert = require('node:assert/strict')
 const KEY = 'definition-test-key'
 const BASE = 'http://definition.test'
 
+const RAW_TEXT = 'definition-test-body'
+const RAW_BYTES = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0xff])
+
 
 async function runDefinitionPoint(SDK, point) {
   const sent = []
@@ -33,7 +36,9 @@ async function runDefinitionPoint(SDK, point) {
   const input = { ...point.select }
   for (const arg of point.args) input[arg.name] = arg.value
   for (const h of point.headers || []) input[h.name] = h.value
+  for (const c of point.cookies || []) input[c.name] = c.value
   if (null != point.action) input.$action = point.action
+  if (null != point.rawBody) input.$body = rawSample(point)
 
   let result
   let error
@@ -61,11 +66,19 @@ async function runDefinitionPoint(SDK, point) {
   // Only what the definition declares, so never a path parameter again.
   const credentialQuery = (point.auth || []).flat()
     .filter((c) => 'query' === c.in).map((c) => c.name)
+  // prepareAuth sends the key whether or not this operation applies its scheme.
+  if (null != point.ownQuery) {
+    credentialQuery.push(point.ownQuery)
+  }
   for (const key of url.searchParams.keys()) {
     assert(point.query.includes(key) || credentialQuery.includes(key),
       'query parameter not in the definition: ' + key)
   }
 
+  for (const q of point.queryArgs || []) {
+    assert(url.searchParams.has(q.wire), 'query parameter not sent: ' + q.wire)
+  }
+
   // From the apikey alone, placed as the definition's security scheme says.
   if (null != point.auth && 0 < point.auth.length) {
     const headers = new Headers(init.headers)
@@ -81,8 +94,63 @@ async function runDefinitionPoint(SDK, point) {
   for (const h of point.headers || []) {
     const wire = h.wire.toLowerCase()
     if (credentialHeaders.includes(wire) || 'content-type' === wire) continue
-    assert.equal(new Headers(init.headers).get(wire), String(h.value),
-      'header parameter not sent as a header: ' + h.wire)
+    const sentValue = new Headers(init.headers).get(wire)
+    // A Cookie header argument is cookie pieces, which the cookie arguments and
+    // the cookie credential join, each replacing the piece whose name it owns.
+    if ('cookie' === wire) {
+      const owned = (point.cookies || []).map((c) => c.wire).concat((point.auth || []).flat()
+        .filter((c) => 'cookie' === c.in).map((c) => c.name))
+      const pieces = String(sentValue ?? '').split(';').map((c) => c.trim())
+      for (const piece of String(h.value).split(';').map((c) => c.trim()).filter((c) => '' !== c)) {
+        if (owned.includes(piece.split('=')[0].trim())) continue
+        assert(pieces.includes(piece), 'header parameter not sent as a header: ' + h.wire)
+      }
+      continue
+    }
+    assert.equal(sentValue, String(h.value), 'header parameter not sent as a header: ' + h.wire)
+  }
+
+  // A cookie parameter goes out in the cookie header as name=value, percent-encoded.
+  const cookies = String(new Headers(init.headers).get('cookie') ?? '')
+    .split(';').map((c) => c.trim())
+  for (const c of point.cookies || []) {
+    assert(cookies.includes(c.wire + '=' + encodeURIComponent(String(c.value))),
+      'cookie parameter not sent in the cookie header: ' + c.wire)
+  }
+
+  // Accept asks only for what a success response declares: its JSON type
+  // alone, when it declares one.
+  if (null != point.responseMedia) {
+    const declared = point.responseMedia
+    const asked = String(new Headers(init.headers).get('accept') ?? '').split(',')
+      .map(baseMedia).filter((type) => '' !== type)
+    assert(0 < asked.length, 'no Accept for a declared response body: ' + declared.join(', '))
+    for (const type of asked) {
+      assert(declared.some((d) => covers(d, type)),
+        'Accept asks for a type no success response declares: ' + type)
+    }
+    if (declared.some(isJson)) {
+      assert(1 === asked.length && isJson(asked[0]),
+        'Accept is not the declared JSON type alone: ' + asked.join(', '))
+    }
+  }
+
+  // A raw body goes out as given, under a type the definition declares.
+  if (null != point.rawBody) {
+    const type = baseMedia(new Headers(init.headers).get('content-type') ?? '')
+    assert(point.rawBody.media.some((d) => covers(d, type)),
+      'raw body sent as a type the definition does not declare: ' + type)
+    assert.deepEqual(bytesOf(init.body), bytesOf(rawSample(point)), 'raw body not sent as given')
+  }
+
+  // An argument the request body declares too goes out in the body as well.
+  if (0 < (point.bodyArgs || []).length) {
+    let sentBody
+    try { sentBody = JSON.parse(String(init.body)) }
+    catch (_e) { sentBody = undefined }
+    for (const name of point.bodyArgs) {
+      assert.deepEqual(sentBody?.[name], input[name], 'argument not sent in the body as well: ' + name)
+    }
   }
 
   if (null != error) {
@@ -102,7 +170,8 @@ async function runDefinitionPoint(SDK, point) {
         records.length)
     }
   }
-  else if ('load' === point.op || 'create' === point.op || 'update' === point.op) {
+  else if ('load' === point.op || 'create' === point.op || 'update' === point.op ||
+    'patch' === point.op) {
     const record = recordOf(point.sample, point.idField, point.entity)
     if (null != record) {
       assert.equal(result?.data?.()?.[point.idField], record[point.idField],
@@ -112,6 +181,37 @@ async function runDefinitionPoint(SDK, point) {
 }
 
 
+function rawSample(point) {
+  return point.rawBody.text ? RAW_TEXT : RAW_BYTES
+}
+
+
+function bytesOf(body) {
+  return 'string' === typeof body ? Buffer.from(body, 'utf8') :
+    body instanceof ArrayBuffer ? Buffer.from(new Uint8Array(body)) :
+      ArrayBuffer.isView(body) ? Buffer.from(body.buffer, body.byteOffset, body.byteLength) :
+        Buffer.from(String(body))
+}
+
+
+function baseMedia(type) {
+  return type.split(';')[0].trim().toLowerCase()
+}
+
+
+function isJson(type) {
+  const media = baseMedia(type)
+  return 'application/json' === media || 'text/json' === media || media.endsWith('+json')
+}
+
+
+function covers(declared, type) {
+  const media = baseMedia(declared)
+  return media === type || '*/*' === media ||
+    (media.endsWith('/*') && type.startsWith(media.slice(0, -1)))
+}
+
+
 function placed(cred, headers, url) {
   if ('query' === cred.in) {
     return KEY === url.searchParams.get(cred.name)

package/project/.sdk/tm/js/test/feature/Corpus.test.js

@@ -185,6 +185,15 @@ function tokensUsed(kase) {
 }
 
 
+// The first feature a case composes that this SDK does not generate. Such a
+// case is skipped rather than failed, as a section naming one is.
+function missingFeature(probe, kase) {
+  const named = Array.isArray(kase.feature) ? kase.feature.map((f) => f?.name) :
+    Object.keys(kase.feature || {})
+  return named.find((n) => 'string' === typeof n && !probe._rootctx.config.hasFeature(n))
+}
+
+
 // Assert that `actual` contains `expect`, recursively. Cases assert only the
 // fields they are about, so a full deepStrictEqual would force every case to
 // restate the whole record.
@@ -267,6 +276,7 @@ describe('FeatureCorpus', () => {
         `or an emptied fixture must fail loudly, not pass silently`)
 
       let ran = 0
+      const failed = []
       for (const raw of cases) {
         const need = tokensUsed(raw)
         if (ops.length < need) {
@@ -274,33 +284,52 @@ describe('FeatureCorpus', () => {
           continue
         }
 
+        const missing = missingFeature(probe, raw)
+        if (null != missing) {
+          t.diagnostic(`skip "${raw.name}": needs the ${missing} feature, ` +
+            'which this SDK does not generate')
+          continue
+        }
+
         const tokens = {}
         for (let i = 0; i < need; i++) { tokens['#OP' + (i + 1)] = ops[i].key }
 
         const kase = resolve(raw, tokens)
-        const client = makeClient(kase)
-
-        for (const step of (kase.op || [])) {
-          const ref = byKey[step.op]
-          ok(null != ref, `${kase.name}: no operation ${step.op}`)
-          try {
-            await client[ref.accessor]()[ref.op]({}, step.ctrl || {})
-            ok(null == step.err,
-              `${kase.name}: ${step.op} was expected to fail, and did not`)
-          }
-          catch (err) {
-            if (null == step.err) { throw err }
+        ran++
+
+        // Every failing case is reported, not only the first.
+        try {
+          const client = makeClient(kase)
+
+          for (const step of (kase.op || [])) {
+            const ref = byKey[step.op]
+            ok(null != ref, `${kase.name}: no operation ${step.op}`)
+            let err = undefined
+            try {
+              await client[ref.accessor]()[ref.op]({}, step.ctrl || {})
+            }
+            catch (e) {
+              err = e
+            }
+            if (null == step.err) {
+              ok(undefined === err,
+                `${kase.name}: ${step.op} failed unexpectedly: ${err?.message}`)
+              continue
+            }
+            ok(undefined !== err, `${kase.name}: ${step.op} was expected to fail, and did not`)
             if ('string' === typeof step.err) {
               deepStrictEqual(err.code, step.err, `${kase.name}: wrong error code`)
             }
           }
-        }
 
-        subset(client[`_${name}`], kase.out, `${kase.name}: _${name}`)
-        ran++
+          subset(client[`_${name}`], kase.out, `${kase.name}: _${name}`)
+        }
+        catch (err) {
+          const msg = String(err?.message ?? err)
+          failed.push(msg.startsWith(kase.name) ? msg : kase.name + ': ' + msg)
+        }
       }
 
-      ok(0 < ran, `every feature.${name} case was skipped`)
       // Say how many ran. A partial run is legitimate (an SDK with one
       // operation skips the cases needing two) but it should be visible
       // rather than inferred from a green tick - and it is the one line
@@ -308,6 +337,8 @@ describe('FeatureCorpus', () => {
       // language's runner.
       t.diagnostic(`feature.${name}: ran ${ran} of ${cases.length} ` +
         `case(s) against ${ops.length} operation(s)`)
+      ok(0 < ran, `every feature.${name} case was skipped`)
+      deepStrictEqual(failed, [], `feature.${name}: ${failed.length} case(s) failed`)
     })
   }
 })

package/project/.sdk/tm/js/test/feature/harness.js

@@ -66,7 +66,7 @@ function defaultServer() {
 
 function defaultMethod(op) {
   if ('create' === op) return 'POST'
-  if ('update' === op) return 'PATCH'
+  if ('update' === op || 'patch' === op) return 'PATCH'
   if ('remove' === op) return 'DELETE'
   return 'GET'
 }
@@ -243,6 +243,9 @@ function makeClient(spec) {
           headers: ctx.spec.headers,
           body: ctx.spec.body,
         }
+        if (null != ctx.ctrl.signal) {
+          fetchdef.signal = ctx.ctrl.signal
+        }
         response = await utility.fetcher(ctx, fetchdef.url, fetchdef)
       }
       ctx.response = response

package/project/.sdk/tm/js/test/feature/secrets/Secrets.test.js

@@ -282,9 +282,9 @@ describe('secrets', () => {
     assert.equal(stub.sent, 0,
       'a request must not go out unauthenticated because a provider broke,' +
       ' but one reached the transport: ' + wire(stub))
-    assert.ok(res instanceof Error,
-      'expected the provider Error, got: ' + JSON.stringify(res))
-    assert.match(String(res.message), /vault unreachable/)
+    assert.ok(res && false === res.ok && res.err instanceof Error,
+      'expected the provider Error as err, got: ' + JSON.stringify(res))
+    assert.match(String(res.err.message), /vault unreachable/)
 
     // CONTROL, which makes that zero mean REFUSED rather than UNWIRED: the
     // same construction with a WORKING provider must reach the same
@@ -308,9 +308,9 @@ describe('secrets', () => {
     assert.equal(stub.sent, 0,
       'a graphql request must not go out unauthenticated,' +
       ' but one reached the transport: ' + wire(stub))
-    assert.ok(res instanceof Error,
-      'expected the provider Error, got: ' + JSON.stringify(res))
-    assert.match(String(res.message), /vault unreachable/)
+    assert.ok(res && false === res.ok && res.err instanceof Error,
+      'expected the provider Error as err, got: ' + JSON.stringify(res))
+    assert.match(String(res.err.message), /vault unreachable/)
 
     const control = countingFetch()
     const ok = await rawSdk(control, WORKINGPROVIDER).graphql('{ thing }', {})
@@ -869,7 +869,7 @@ describe('secrets exchange', () => {
 
     const res = await sdk.direct({ path: '/thing' })
 
-    assert.ok(res instanceof Error || (res && false === res.ok),
+    assert.ok(res && false === res.ok && null != res.err,
       'expected a failure, got: ' + JSON.stringify(res))
     assert.equal(stub.api().length, 0,
       'a request must not go out unauthenticated because the chain was empty')

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

@@ -6,7 +6,9 @@
 
 const { test, describe } = require('node:test')
 const { strictEqual, ok, deepStrictEqual } = require('node:assert')
+const { getEventListeners } = require('node:events')
 
+const { ProjectNameSDK } = require('..')
 const { hasFeature, makeClient, makeClock, makeResponse } = require('./feature/harness')
 
 
@@ -21,6 +23,23 @@ function recordingServer(reply) {
 }
 
 
+// Answers after `ms` unless the request's signal aborts first, when it rejects
+// with the signal's reason, as fetch does.
+function slowServer(ms) {
+  return (_ctx, _url, fetchdef) => new Promise((resolve, reject) => {
+    const timer = setTimeout(() => resolve(makeResponse(200, { ok: true })), ms)
+    const signal = fetchdef.signal
+    if (null == signal) return
+    const abort = () => {
+      clearTimeout(timer)
+      reject(signal.reason)
+    }
+    if (signal.aborted) return abort()
+    signal.addEventListener('abort', abort, { once: true })
+  })
+}
+
+
 // A subtest that drives a second feature (netsim as the simulated network)
 // can only run when this SDK was generated with it: the harness skips
 // absent features, which would leave the scenario unsimulated and the
@@ -786,4 +805,119 @@ describe('feature', () => {
       strictEqual(h.client._netsim.calls, 1)
     })
   }
+
+  // --- abort ----------------------------------------------------------------
+  // A caller's signal ends a request wherever it waits. Each wait is far longer
+  // than the abort, so a request that ignored the signal would take seconds.
+  describe('abort', () => {
+
+    test('a caller abort cancels a request the timeout feature wraps', { skip: skipWithout('timeout') }, async () => {
+      const h = makeClient({ features: [{ name: 'timeout', options: { ms: 5000 } }], server: slowServer(2000) })
+      const ac = new AbortController()
+      const reason = new Error('stop')
+      setTimeout(() => ac.abort(reason), 20)
+      const start = Date.now()
+      const res = await h.op({ op: 'load', ctrl: { signal: ac.signal } })
+      ok(Date.now() - start < 1000, 'the request ended at the abort')
+      strictEqual(res.error, reason)
+      strictEqual(h.client._timeout, undefined, 'an abort is not a timeout')
+    })
+
+    test('the deadline still fires while the caller signal stays live', { skip: skipWithout('timeout') }, async () => {
+      const h = makeClient({ features: [{ name: 'timeout', options: { ms: 20 } }], server: slowServer(2000) })
+      const ac = new AbortController()
+      const res = await h.op({ op: 'load', ctrl: { signal: ac.signal } })
+      strictEqual(res.error.code, 'timeout')
+      strictEqual(getEventListeners(ac.signal, 'abort').length, 0,
+        'the timeout leaves no listener on the caller signal')
+    })
+
+    test('an aborted request is not retried', { skip: skipWithout('retry') }, async () => {
+      const ac = new AbortController()
+      const rec = recordingServer(() => {
+        ac.abort()
+        return makeResponse(503)
+      })
+      const clock = makeClock()
+      const h = makeClient({
+        features: [{ name: 'retry', options: { retries: 3, minDelay: 10, jitter: false, sleep: clock.sleep } }],
+        server: rec.server,
+      })
+      const res = await h.op({ op: 'load', ctrl: { signal: ac.signal } })
+      strictEqual(rec.calls.length, 1)
+      strictEqual(res.error, ac.signal.reason)
+      strictEqual(h.client._retry, undefined, 'no retry was scheduled')
+    })
+
+    test('an abort whose reason is not an Error is not retried either', { skip: skipWithout('retry') }, async () => {
+      // fetch rejects with the reason itself, so a string or a number reaches
+      // retry as a non-Error: it must still end the request, not become a response.
+      const server = slowServer(2000)
+      const h = makeClient({
+        features: [{ name: 'retry', options: { retries: 3, minDelay: 10, jitter: false } }],
+        server,
+      })
+      const ac = new AbortController()
+      setTimeout(() => ac.abort('user cancelled'), 20)
+      const start = Date.now()
+      const res = await h.op({ op: 'load', ctrl: { signal: ac.signal } })
+      ok(Date.now() - start < 1000, 'the request ended at the abort')
+      strictEqual(res.ok, false)
+      strictEqual(res.error, 'user cancelled')
+      strictEqual(h.client._retry, undefined, 'no retry was scheduled')
+    })
+
+    test('an abort during the retry backoff ends it', { skip: skipWithout('retry') }, async () => {
+      const ac = new AbortController()
+      const rec = recordingServer(() => makeResponse(503))
+      const h = makeClient({
+        features: [{ name: 'retry', options: { retries: 3, minDelay: 2000, jitter: false } }],
+        server: rec.server,
+      })
+      setTimeout(() => ac.abort(), 20)
+      const start = Date.now()
+      const res = await h.op({ op: 'load', ctrl: { signal: ac.signal } })
+      ok(Date.now() - start < 1000, 'the backoff ended at the abort')
+      strictEqual(rec.calls.length, 1)
+      strictEqual(res.error, ac.signal.reason)
+    })
+
+    test('an abort during simulated latency ends the request before the transport', { skip: skipWithout('netsim') }, async () => {
+      const ac = new AbortController()
+      const rec = recordingServer()
+      const h = makeClient({ features: [{ name: 'netsim', options: { latency: 2000 } }], server: rec.server })
+      setTimeout(() => ac.abort(), 20)
+      const start = Date.now()
+      const res = await h.op({ op: 'load', ctrl: { signal: ac.signal } })
+      ok(Date.now() - start < 1000, 'the latency ended at the abort')
+      strictEqual(rec.calls.length, 0)
+      strictEqual(res.error, ac.signal.reason)
+    })
+
+    test('an abort while waiting for a rate-limit token ends the wait', { skip: skipWithout('ratelimit') }, async () => {
+      const ac = new AbortController()
+      const rec = recordingServer()
+      const h = makeClient({ features: [{ name: 'ratelimit', options: { rate: 0.5, burst: 1 } }], server: rec.server })
+      await h.op({ op: 'load' })
+      setTimeout(() => ac.abort(), 20)
+      const start = Date.now()
+      const res = await h.op({ op: 'load', ctrl: { signal: ac.signal } })
+      ok(Date.now() - start < 1000, 'the wait ended at the abort')
+      strictEqual(rec.calls.length, 1)
+      strictEqual(res.error, ac.signal.reason)
+    })
+
+    test('the test transport aborts a request in flight', async () => {
+      const sdk = ProjectNameSDK.test({ net: { latency: 2000 } })
+      const ac = new AbortController()
+      const reason = new Error('stop')
+      setTimeout(() => ac.abort(reason), 20)
+      const start = Date.now()
+      const res = await sdk.direct({ path: '/ping', ctrl: { signal: ac.signal } })
+      ok(Date.now() - start < 1000, 'the request ended at the abort')
+      strictEqual(res.ok, false)
+      strictEqual(res.err.code, 'request_aborted')
+      strictEqual(res.err.cause, reason)
+    })
+  })
 })

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

@@ -140,10 +140,10 @@ function synthesizeInput(schema, explicit, depth = 0) {
         }
         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) {
+        return allOfInput(schema, depth);
+    let value;
+    if (schema.type === 'object' || schema.properties) {
         value = {};
         for (const key of schema.required || [])
             if (!schema.properties?.[key]?.readOnly) {
@@ -170,6 +170,76 @@ function synthesizeInput(schema, explicit, depth = 0) {
     validateContract(schema, value);
     return value;
 }
+// An allOf's objects merged, else the first value its parts give that the whole schema
+// accepts: a declared value, then a synthesized one. A part that gives no value is left
+// to that validation, unless it carries a constraint the validator does not check.
+function allOfInput(schema, depth) {
+    let blocked;
+    const given = schema.allOf.map((part) => {
+        try {
+            return synthesizeInput(part, undefined, depth + 1);
+        }
+        catch (error) {
+            const unchecked = uncheckedConstraint(part);
+            if (unchecked)
+                throw new live_runner_1.LiveBlocked('Unsupported contract constraint: ' + unchecked);
+            blocked ??= error;
+        }
+    });
+    const objects = given.filter((v) => v !== null && typeof v === 'object' && !Array.isArray(v));
+    const candidates = [...(objects.length ? [Object.assign({}, ...objects)] : []),
+        ...declaredValues(schema.allOf), ...given.filter((v) => v !== undefined)];
+    let mismatch;
+    for (const value of candidates) {
+        try {
+            validateContract(schema, value);
+            return value;
+        }
+        catch (error) {
+            mismatch ??= error;
+        }
+    }
+    throw blocked ?? mismatch ?? new live_runner_1.LiveBlocked('Required input needs a guide recipe or validated example');
+}
+// What the parts declare, each kind in part order: every example, then every enum
+// value, then every default.
+function declaredValues(parts) {
+    const schemas = parts.filter(part => part !== null && typeof part === 'object');
+    const values = [];
+    const add = (value) => {
+        if (!values.some(v => JSON.stringify(v) === JSON.stringify(value)))
+            values.push(value);
+    };
+    for (const part of schemas) {
+        if (part.example !== undefined)
+            add(part.example);
+        for (const value of Array.isArray(part.examples) ? part.examples : [])
+            add(value);
+    }
+    for (const part of schemas)
+        for (const value of Array.isArray(part.enum) ? part.enum : [])
+            add(value);
+    for (const part of schemas)
+        if (part.default !== undefined)
+            add(part.default);
+    return values;
+}
+// The keywords validateContract reads, and those that only annotate; any other
+// keyword on a part is a constraint no validation of the whole schema can enforce.
+const CHECKED_KEYWORDS = new Set(['$ref', 'type', 'enum', 'const', 'format', 'pattern',
+    'minLength', 'maxLength', 'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum',
+    'multipleOf', 'items', 'prefixItems', 'minItems', 'maxItems', 'uniqueItems', 'properties',
+    'required', 'additionalProperties', 'allOf', 'oneOf', 'anyOf', 'not', 'if', 'then', 'else',
+    'dependentRequired', 'dependentSchemas', 'patternProperties', 'contains',
+    'unevaluatedProperties', 'unevaluatedItems']);
+const ANNOTATION_KEYWORDS = new Set(['description', 'title', 'example', 'examples', 'default',
+    'deprecated', 'readOnly', 'writeOnly', 'externalDocs', 'xml', 'nullable', 'discriminator',
+    '$comment', '$schema', '$id']);
+function uncheckedConstraint(part) {
+    if (part === null || typeof part !== 'object')
+        return undefined;
+    return Object.keys(part).find(key => !CHECKED_KEYWORDS.has(key) && !ANNOTATION_KEYWORDS.has(key) && !key.startsWith('x-'));
+}
 function requestContract(facts) {
     const body = facts?.requestBody;
     if (body) {

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

@@ -10,11 +10,17 @@ 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, facts = {}) {
+async function runLiveEntity(setup, entity, flow, accessor, facts = {}, settle = {}) {
     const { client, transport } = setup;
-    const steps = (flow.step || []).filter((step) => false !== step.a);
+    // A step switched off only because the offline call reaches no route of
+    // its operation still runs here, where each route's inputs are resolved.
+    const steps = (flow.step || [])
+        .filter((step) => false !== step.a || true === step.unreachable);
     const created = new Map();
     const listed = [];
+    let listedEmpty = false;
+    const recordFields = new Set(['id', entity.id?.field || 'id',
+        ...Object.values(entity.fields || {}).map((field) => field?.n).filter(Boolean)]);
     const marks = new Map();
     const idField = entity.id?.field || 'id';
     const copy = (value) => JSON.parse(JSON.stringify(value ?? {}));
@@ -61,15 +67,18 @@ async function runLiveEntity(setup, entity, flow, accessor, facts = {}) {
                 }
                 // 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.
+                // candidate. An action route is taken only when the step names its
+                // action or the operation has no other route, and then by name.
                 let resolved;
                 let selected;
-                const missing = new Set();
+                const unusable = [];
+                const actionOnly = points.every((point) => null != point.q?.$action);
                 for (const point of points) {
-                    if (point.q?.$action !== input.$action)
+                    const action = point.q?.$action;
+                    if (null == input.$action ? null != action && !actionOnly : action !== input.$action)
                         continue;
-                    const candidate = { ...input };
-                    let viable = true;
+                    const candidate = null == action ? { ...input } : { ...input, $action: action };
+                    const missing = [];
                     const params = point.g?.params || [];
                     const query = (point.g?.query || []).filter((arg) => arg.r);
                     for (const arg of [...params, ...query]) {
@@ -79,19 +88,26 @@ async function runLiveEntity(setup, entity, flow, accessor, facts = {}) {
                         const value = setup.idmap[key] ?? setup.idmap[arg.n] ?? loaded?.[arg.n] ?? arg.ex;
                         if (undefined !== value && null !== value)
                             candidate[arg.n] = value;
-                        else if (arg.r !== false) {
-                            viable = false;
-                            missing.add(arg.n);
-                        }
+                        else if (arg.r !== false)
+                            missing.push(arg.n);
                     }
-                    if (viable) {
+                    if (0 === missing.length) {
                         resolved = candidate;
                         selected = point;
                         break;
                     }
+                    unusable.push({ route: null == action ? point.m + ' ' + point.o : '$action ' + action, missing });
+                }
+                if (!resolved) {
+                    // An empty list is a valid answer: the account has no record to load.
+                    if (op === 'load' && !record && listedEmpty &&
+                        unusable.every(route => route.missing.every(name => recordFields.has(name)))) {
+                        throw new live_runner_1.LiveEmpty('The account has no ' + entity.name + ' record to load');
+                    }
+                    throw new live_runner_1.LiveBlocked(0 === unusable.length ? 'No route for $action ' + input.$action :
+                        'No usable route: ' + unusable.map(route => route.route + ' needs ' +
+                            route.missing.join(', ')).join('; '));
                 }
-                if (!resolved)
-                    throw new live_runner_1.LiveBlocked('No usable route; missing arguments: ' + [...missing].join(', '));
                 input = resolved;
                 if (op === 'create' && facts[selected.m + ' ' + selected.o]) {
                     const selectedFacts = facts[selected.m + ' ' + selected.o];
@@ -103,6 +119,8 @@ async function runLiveEntity(setup, entity, flow, accessor, facts = {}) {
                     for (const arg of selected.g?.params || [])
                         if (resolved[arg.n] !== undefined)
                             input[arg.n] = resolved[arg.n];
+                    if (undefined !== resolved.$action)
+                        input.$action = resolved.$action;
                 }
                 let intendedMark;
                 if (op === 'update') {
@@ -126,6 +144,7 @@ async function runLiveEntity(setup, entity, flow, accessor, facts = {}) {
                         return item.data();
                     });
                     listed.splice(0, listed.length, ...data);
+                    listedEmpty = 0 === data.length;
                     context.publish(data);
                     for (const validation of step.v || []) {
                         const previous = created.get(validation.def?.ref);
@@ -165,5 +184,5 @@ async function runLiveEntity(setup, entity, flow, accessor, facts = {}) {
         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);
+    (0, live_runner_1.settleLiveReport)(report, settle);
 }