@voxgig/sdkgen 4.33.0 → 4.34.1

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

@@ -17,17 +17,26 @@ type DefinitionPoint = {
   args: { name: string, wire: string, value: any }[]
   select: Record<string, any>
   headers?: { name: string, wire: string, value: any }[]
+  cookies?: { name: string, wire: string, value: any }[]
+  responseMedia?: string[]
+  rawBody?: { media: string[], text: boolean }
   query: string[]
+  queryArgs?: { name: string, wire: string }[]
+  bodyArgs?: string[]
   auth: Credential[][] | null
   status: number
   sample: any
   idField: string
+  ownQuery?: string
 }
 
 
 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: any, point: DefinitionPoint): Promise<void> {
   const sent: { url: URL, init: any }[] = []
@@ -51,7 +60,9 @@ async function runDefinitionPoint(SDK: any, point: DefinitionPoint): Promise<voi
   const input: any = { ...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: any
   let error: any
@@ -79,11 +90,19 @@ async function runDefinitionPoint(SDK: any, point: DefinitionPoint): Promise<voi
   // 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)
@@ -99,8 +118,63 @@ async function runDefinitionPoint(SDK: any, point: DefinitionPoint): Promise<voi
   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: any
+    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) {
@@ -120,7 +194,8 @@ async function runDefinitionPoint(SDK: any, point: DefinitionPoint): Promise<voi
         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],
@@ -130,6 +205,37 @@ async function runDefinitionPoint(SDK: any, point: DefinitionPoint): Promise<voi
 }
 
 
+function rawSample(point: DefinitionPoint): any {
+  return point.rawBody?.text ? RAW_TEXT : RAW_BYTES
+}
+
+
+function bytesOf(body: any): Buffer {
+  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: string): string {
+  return type.split(';')[0].trim().toLowerCase()
+}
+
+
+function isJson(type: string): boolean {
+  const media = baseMedia(type)
+  return 'application/json' === media || 'text/json' === media || media.endsWith('+json')
+}
+
+
+function covers(declared: string, type: string): boolean {
+  const media = baseMedia(declared)
+  return media === type || '*/*' === media ||
+    (media.endsWith('/*') && type.startsWith(media.slice(0, -1)))
+}
+
+
 function placed(cred: Credential, headers: Headers, url: URL): boolean {
   if ('query' === cred.in) {
     return KEY === url.searchParams.get(cred.name)

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

@@ -148,6 +148,15 @@ function tokensUsed(kase: any): number {
 }
 
 
+// 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: any, kase: any): string | undefined {
+  const named = Array.isArray(kase.feature) ? kase.feature.map((f: any) => f?.name) :
+    Object.keys(kase.feature || {})
+  return named.find((n: any) => '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.
@@ -216,6 +225,7 @@ describe('FeatureCorpus', () => {
         `or an emptied fixture must fail loudly, not pass silently`)
 
       let ran = 0
+      const failed: string[] = []
       for (const raw of cases) {
         const need = tokensUsed(raw)
         if (ops.length < need) {
@@ -223,33 +233,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: Record<string, string> = {}
         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: any) {
-            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: any = undefined
+            try {
+              await client[ref.accessor]()[ref.op]({}, step.ctrl || {})
+            }
+            catch (e: any) {
+              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: any) {
+          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
@@ -257,6 +286,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/ts/test/feature/harness.ts

@@ -60,7 +60,7 @@ function defaultServer(): ServerFn {
 
 function defaultMethod(op: string): string {
   if ('create' === op) return 'POST'
-  if ('update' === op) return 'PATCH'
+  if ('update' === op || 'patch' === op) return 'PATCH'
   if ('remove' === op) return 'DELETE'
   return 'GET'
 }
@@ -252,6 +252,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/ts/test/feature/secrets/Secrets.test.ts

@@ -628,7 +628,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/ts/test/feature.test.ts

@@ -6,7 +6,9 @@
 
 import { test, describe } from 'node:test'
 import { strictEqual, ok, deepStrictEqual } from 'node:assert'
+import { getEventListeners } from 'node:events'
 
+import { ProjectNameSDK } from '..'
 import { hasFeature, makeClient, makeClock, makeResponse } from './feature/harness'
 
 
@@ -21,6 +23,23 @@ function recordingServer(reply?: (n: number, fetchdef: any) => any) {
 }
 
 
+// Answers after `ms` unless the request's signal aborts first, when it rejects
+// with the signal's reason, as fetch does.
+function slowServer(ms: number) {
+  return (_ctx: any, _url: string, fetchdef: any) => 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: any = 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/ts/test/live-contract.ts

@@ -69,9 +69,9 @@ export function synthesizeInput(schema: any, explicit?: any, depth = 0): any {
   for (const choice of schema.oneOf || schema.anyOf || []) {
     try { const v = synthesizeInput(choice, undefined, depth + 1); validateContract(schema, v); return v } catch {}
   }
+  if (schema.allOf) return allOfInput(schema, depth)
   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) {
+  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)
@@ -90,6 +90,64 @@ export function synthesizeInput(schema: any, explicit?: any, depth = 0): any {
   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: any, depth: number): any {
+  let blocked: unknown
+  const given = schema.allOf.map((part: any) => {
+    try { return synthesizeInput(part, undefined, depth + 1) }
+    catch (error) {
+      const unchecked = uncheckedConstraint(part)
+      if (unchecked) throw new LiveBlocked('Unsupported contract constraint: ' + unchecked)
+      blocked ??= error
+    }
+  })
+  const objects = given.filter((v: any) => v !== null && typeof v === 'object' && !Array.isArray(v))
+  const candidates = [...(objects.length ? [Object.assign({}, ...objects)] : []),
+    ...declaredValues(schema.allOf), ...given.filter((v: any) => v !== undefined)]
+  let mismatch: unknown
+  for (const value of candidates) {
+    try { validateContract(schema, value); return value } catch (error) { mismatch ??= error }
+  }
+  throw blocked ?? mismatch ?? new 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: any[]): any[] {
+  const schemas = parts.filter(part => part !== null && typeof part === 'object')
+  const values: any[] = []
+  const add = (value: any) => {
+    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: any): string | undefined {
+  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-'))
+}
+
 export function requestContract(facts: any): { schema?: any, example?: any, required?: boolean } {
   const body = facts?.requestBody
   if (body) {

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

@@ -1,15 +1,24 @@
 import assert from 'node:assert/strict'
 import { requestContract, synthesizeInput } from './live-contract'
-import { runLiveSteps, assertLiveReport, LiveBlocked } from './live-runner'
+import { runLiveSteps, settleLiveReport, LiveBlocked, LiveEmpty } from './live-runner'
+import type { LiveSettle } 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, facts: any = {}) {
+async function runLiveEntity(
+  setup: any, entity: any, flow: any, accessor: string, facts: any = {}, settle: LiveSettle = {},
+) {
   const { client, transport } = setup
-  const steps: any[] = (flow.step || []).filter((step: any) => 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: any[] = (flow.step || [])
+    .filter((step: any) => false !== step.a || true === step.unreachable)
   const created = new Map<string, any>()
   const listed: any[] = []
+  let listedEmpty = false
+  const recordFields = new Set<string>(['id', entity.id?.field || 'id',
+    ...Object.values(entity.fields || {}).map((field: any) => field?.n).filter(Boolean)])
   const marks = new Map<string, { name: string, value: any }>()
   const idField = entity.id?.field || 'id'
   const copy = (value: any) => JSON.parse(JSON.stringify(value ?? {}))
@@ -52,14 +61,17 @@ async function runLiveEntity(setup: any, entity: any, flow: any, accessor: strin
         }
         // 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: any
         let selected: any
-        const missing = new Set<string>()
+        const unusable: { route: string, missing: string[] }[] = []
+        const actionOnly = points.every((point: any) => null != point.q?.$action)
         for (const point of points) {
-          if (point.q?.$action !== input.$action) continue
-          const candidate = { ...input }
-          let viable = true
+          const action = point.q?.$action
+          if (null == input.$action ? null != action && !actionOnly : action !== input.$action) continue
+          const candidate = null == action ? { ...input } : { ...input, $action: action }
+          const missing: string[] = []
           const params = point.g?.params || []
           const query = (point.g?.query || []).filter((arg: any) => arg.r)
           for (const arg of [...params, ...query]) {
@@ -67,11 +79,21 @@ async function runLiveEntity(setup: any, entity: any, flow: any, accessor: strin
             const key = arg.n === 'id' ? entity.name + '01' : arg.n.replace(/_id$/, '') + '01'
             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) { resolved = candidate; selected = point; break }
+          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 LiveEmpty('The account has no ' + entity.name + ' record to load')
+          }
+          throw new 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 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]
@@ -79,6 +101,7 @@ async function runLiveEntity(setup: any, entity: any, flow: any, accessor: strin
           if (request.schema) input = { ...synthesizeInput(request.schema, selected.li?.input ?? request.example) }
           else if (selectedFacts.protocol === 'http') input = {}
           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: { name: string, value: any } | undefined
         if (op === 'update') {
@@ -102,6 +125,7 @@ async function runLiveEntity(setup: any, entity: any, flow: any, accessor: strin
             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)
@@ -136,7 +160,7 @@ async function runLiveEntity(setup: any, entity: any, flow: any, accessor: strin
     report: result => console.log('LIVE STEP ' + JSON.stringify(result)),
   })
   console.log('LIVE SUMMARY ' + JSON.stringify({ entity: entity.name, ...report }))
-  assertLiveReport(report)
+  settleLiveReport(report, settle)
 }
 
 export { runLiveEntity }