@voxgig/sdkgen 4.33.0 → 4.34.1

package/project/.sdk/src/cmp/js/TestDirect_js.ts

@@ -23,6 +23,8 @@ import {
   jsKey,
   pointParts,
   hasLiveScenarios,
+  liveStrict,
+  liveStrictNote,
 } from '@voxgig/sdkgen'
 
 
@@ -87,6 +89,9 @@ const TestDirect = cmp(function TestDirect(props: any) {
 
         Slot({ name: 'directSetup' }, () => {
           Content(`
+${liveStrictNote(liveStrict(model, target.name), '//')}
+const LIVE_STRICT = ${liveStrict(model, target.name)}
+
 function liveScenariosActive() { return ${hasLiveScenarios(model)} && process.env.${PROJECTNAME}_TEST_LIVE === 'TRUE' }
 function directSetup(mockres) {
   const calls = []
@@ -180,22 +185,15 @@ function generateDirectLoad(model: Model, entity: ModelEntity) {
   const paramAsserts = loadParams.map((p: any, i: number) =>
     '      assert(calls[0].url.includes(\'direct0' + (i + 1) + '\'))\n').join('')
 
-  // Build live list params
-  const liveListParams = listParams.map((p: any) => {
-    const key = p.n === 'id'
-      ? entity.name + '01'
-      : p.n.replace(/_id$/, '') + '01'
-    return { name: p.n, key }
-  })
-
-  // Build live ancestor params for load
-  const liveAncestorParams = ancestorParams.map((p: any) => {
-    const key = p.n.replace(/_id$/, '') + '01'
-    return { name: p.n, key }
-  })
+  const liveListParams = listParams.map((p: any) => ({ name: p.n, key: liveIdKey(entity, p) }))
+  const liveAncestorParams = ancestorParams.map((p: any) => ({ name: p.n, key: liveIdKey(entity, p) }))
+  const mockParamLines = loadParams.map((p: any, i: number) =>
+    `      ${jsProp('params', p.n)} = 'direct0${i + 1}'`).join('\n')
 
+  let liveIdKeys: string[] = []
   let liveParamsBlock = ''
   if (hasList) {
+    liveIdKeys = [...new Set([...liveListParams, ...liveAncestorParams].map((lp: any) => lp.key))]
     const listParamLines = liveListParams.map((lp: any) =>
       `        ${lp.name}: setup.idmap['${lp.key}'],`).join('\n')
     const ancestorParamLines = liveAncestorParams.map((lp: any) =>
@@ -209,27 +207,42 @@ function generateDirectLoad(model: Model, entity: ModelEntity) {
 ${listParamLines}
         },
       })
-      assert(listResult.ok === true)
-      const listData = listResult.data
-      if (!Array.isArray(listData) || listData.length === 0) {
-        throw new Error('Live load blocked: discovery returned no usable entities')
+      if (!listResult.ok || listResult.status < 200 || listResult.status >= 300) {
+        return void liveMiss(t, LIVE_STRICT, 'Live list discovery failed: ' + describeLive(listResult))
+      }
+      if (!Array.isArray(listResult.data)) {
+        return void liveMiss(t, LIVE_STRICT, 'Live list discovery returned no list: ' + describeLive(listResult))
+      }
+      if (0 === listResult.data.length) {
+        return void liveEmpty(t, 'The account has no ${entity.name} record to load')
+      }
+      if (null == listResult.data[0]?.id) {
+        return void liveMiss(t, LIVE_STRICT, 'Live load blocked: discovery returned no usable identity')
       }
-      params.id = listData[0].id
+      params.id = listResult.data[0].id
 ${ancestorParamLines}
     } else {
-${loadParams.map((p: any, i: number) => `      ${jsProp('params', p.n)} = 'direct0${i + 1}'`).join('\n')}
+${mockParamLines}
     }`
   } else {
-    liveParamsBlock = `    if (!setup.live) {
-${loadParams.map((p: any, i: number) => `      ${jsProp('params', p.n)} = 'direct0${i + 1}'`).join('\n')}
+    const liveParams = loadParams.map((p: any) => ({ name: p.n, key: liveIdKey(entity, p) }))
+    liveIdKeys = liveParams.map((lp: any) => lp.key)
+    liveParamsBlock = `    if (setup.live) {
+${liveParams.map((lp: any) => `      ${jsProp('params', lp.name)} = setup.idmap['${lp.key}']`).join('\n') || '      // no params'}
+    } else {
+${mockParamLines || '      // no params'}
     }`
   }
 
+  const skipMissingLine = 0 < liveIdKeys.length
+    ? `    if (skipIfMissingIds(t, setup, ${JSON.stringify(liveIdKeys)}, LIVE_STRICT)) return\n`
+    : ''
+
   Content(`
   test('direct-load-${entity.name}', async (t) => {
     if (liveScenariosActive()) { t.skip('Covered by live operation scenarios'); return }
     const setup = directSetup({ id: 'direct01' })
-    const { client, calls } = setup
+${skipMissingLine}    const { client, calls } = setup
 
     const params = {}
 ${liveParamsBlock}
@@ -240,15 +253,13 @@ ${liveParamsBlock}
       params,
     })
 
-    assert(result.ok === true)
-    assert(setup.live ? result.status >= 200 && result.status < 300 : result.status === 200)
-    assert(null != result.data)
-
-    if (!setup.live) {
+${liveChecks('load', 'null != result.data', 'no data', `      assert(result.ok === true)
+      assert(result.status === 200)
+      assert(null != result.data)
       assert(result.data.id === 'direct01')
       assert(calls.length === 1)
       assert(calls[0].init.method === 'GET')
-${paramAsserts}    }
+${paramAsserts}`)}
   })
 `)
 }
@@ -270,13 +281,7 @@ function generateDirectList(model: Model, entity: ModelEntity) {
   const listParams = listPoint.g?.params || []
   const listPath = normalizePathParams(pointParts(listPoint), listParams, listPoint.r?.param)
 
-  // Build live params
-  const liveParams = listParams.map((p: any) => {
-    const key = p.n === 'id'
-      ? entity.name + '01'
-      : p.n.replace(/_id$/, '') + '01'
-    return { name: p.n, key }
-  })
+  const liveParams = listParams.map((p: any) => ({ name: p.n, key: liveIdKey(entity, p) }))
 
   const paramAsserts = listParams.map((p: any, i: number) =>
     '      assert(calls[0].url.includes(\'direct0' + (i + 1) + '\'))\n').join('')
@@ -300,11 +305,15 @@ ${mockLines}
 `
   }
 
+  const skipMissingLine = 0 < liveParams.length
+    ? `    if (skipIfMissingIds(t, setup, ${JSON.stringify(liveParams.map((lp: any) => lp.key))}, LIVE_STRICT)) return\n`
+    : ''
+
   Content(`
   test('direct-list-${entity.name}', async (t) => {
     if (liveScenariosActive()) { t.skip('Covered by live operation scenarios'); return }
     const setup = directSetup([{ id: 'direct01' }, { id: 'direct02' }])
-    const { client, calls } = setup
+${skipMissingLine}    const { client, calls } = setup
 
 ${paramsBlock}
     const result = await client.direct({
@@ -313,15 +322,13 @@ ${paramsBlock}
       params,
     })
 
-    assert(result.ok === true)
-    assert(setup.live ? result.status >= 200 && result.status < 300 : result.status === 200)
-    assert(Array.isArray(result.data))
-
-    if (!setup.live) {
+${liveChecks('list', 'Array.isArray(result.data)', 'no list', `      assert(result.ok === true)
+      assert(result.status === 200)
+      assert(Array.isArray(result.data))
       assert(result.data.length === 2)
       assert(calls.length === 1)
       assert(calls[0].init.method === 'GET')
-${paramAsserts}    }
+${paramAsserts}`)}
   })
 `)
 }
@@ -341,11 +348,12 @@ function generateDirectGraphqlJs(
   const mockVarLines = vars.map((v: any, i: number) =>
     `      variables[${JSON.stringify(v.name)}] = 'direct0${i + 1}'`).join('\n')
 
-  const liveVarLines = vars.map((v: any) => {
-    const from = v.from || v.name
-    const key = ('id' === from ? entity.name : from.replace(/_id$/, '')) + '01'
-    return `      variables[${JSON.stringify(v.name)}] = setup.idmap['${key}']`
-  }).join('\n')
+  const liveKeys = vars.map((v: any) => liveIdKey(entity, { n: v.from || v.name }))
+  const liveVarLines = vars.map((v: any, i: number) =>
+    `      variables[${JSON.stringify(v.name)}] = setup.idmap['${liveKeys[i]}']`).join('\n')
+  const skipMissingLine = 0 < liveKeys.length
+    ? `    if (skipIfMissingIds(t, setup, ${JSON.stringify(liveKeys)}, LIVE_STRICT)) return\n`
+    : ''
 
   // Asserted against the OUTGOING request body, not the mocked response —
   // response-shape correctness is the entity-level tests' job.
@@ -356,7 +364,7 @@ function generateDirectGraphqlJs(
   test('direct-${opname}-${entity.name}', async (t) => {
     if (liveScenariosActive()) { t.skip('Covered by live operation scenarios'); return }
     const setup = directSetup()
-    const { client, calls } = setup
+${skipMissingLine}    const { client, calls } = setup
 
     const variables = {}
     if (setup.live) {
@@ -367,19 +375,38 @@ ${mockVarLines || '      // no variables'}
 
     const result = await client.graphql(${JSON.stringify(doc)}, variables)
 
-    assert(result.ok === true)
-    assert(setup.live ? result.status >= 200 && result.status < 300 : result.status === 200)
-    assert(null != result.data)
-
-    if (!setup.live) {
+${liveChecks(opname, 'null != result.data', 'no data', `      assert(result.ok === true)
+      assert(result.status === 200)
+      assert(null != result.data)
       assert(calls.length === 1)
       assert(calls[0].init.method === 'POST')
-${varAsserts}    }
+${varAsserts}`)}
   })
 `)
 }
 
 
+// The *_ENTID key a live test reads a parameter's value from.
+function liveIdKey(entity: ModelEntity, param: { n: string }): string {
+  return ('id' === param.n ? entity.name : param.n.replace(/_id$/, '')) + '01'
+}
+
+
+// A live run asserts what any server answers, never the mock's own script
+// (`direct01`, `calls`), and never a record count.
+function liveChecks(opname: string, usable: string, unusable: string, offline: string): string {
+  return `    if (setup.live) {
+      if (!result.ok || result.status < 200 || result.status >= 300) {
+        return void liveMiss(t, LIVE_STRICT, 'Live ${opname} failed: ' + describeLive(result))
+      }
+      if (!(${usable})) {
+        return void liveMiss(t, LIVE_STRICT, 'Live ${opname} returned ${unusable}: ' + describeLive(result))
+      }
+    } else {
+${offline}    }`
+}
+
+
 function normalizePathParams(
   parts: string[],
   params: any[],

package/project/.sdk/src/cmp/js/TestEntity_js.ts

@@ -1,6 +1,6 @@
 import { boundedFacts, pointFacts } from '@voxgig/sdkgen'
 import { buildIdNames } from '@voxgig/sdkgen'
-import { flowSteps } from '@voxgig/sdkgen'
+import { flowSteps, opReachable, invalidRequest } from '@voxgig/sdkgen'
 
 import * as Path from 'node:path'
 
@@ -39,6 +39,8 @@ import {
   jsKey,
   jsProp,
   hasLiveScenarios,
+  liveStrict,
+  liveStrictNote,
 } from '@voxgig/sdkgen'
 
 
@@ -113,12 +115,22 @@ const TestEntity = cmp(function TestEntity(props: any) {
           return;
         }
 
+        Slot({ name: 'failure' }, () => {
+          if (opReachable((entity.op as any)?.list, [])) {
+            Content(failureTests(model, entity))
+          }
+          Content(validateTest(model, entity))
+        })
+
         const indent = 2
 
         const idlist = buildIdNames(entity, basicflow)
 
         Slot({ name: 'basicSetup' }, () => {
           Content(`
+${liveStrictNote(liveStrict(model, target.name), '//')}
+const LIVE_STRICT = ${liveStrict(model, target.name)}
+
 function basicSetup(extra) {
   // TODO: fix test def options
   const options = {} // ${jsonify(basicflow.test, { offset: indent - 2 })}
@@ -209,7 +221,7 @@ function basicSetup(extra) {
     ${hasLiveScenarios(model) ? `if (process.env.${PROJENVNAME}_TEST_LIVE === 'TRUE') { t.skip('Covered by live operation scenarios'); return }` : ''}
     const setup = basicSetup()
     if (setup.live) {
-      return runLiveEntity(setup, ${JSON.stringify(entity)}, ${JSON.stringify(basicflow)}, '${nom(entity, 'Name')}', ${JSON.stringify(liveFacts)})
+      return runLiveEntity(setup, ${JSON.stringify(entity)}, ${JSON.stringify(basicflow)}, '${nom(entity, 'Name')}', ${JSON.stringify(liveFacts)}, { strict: LIVE_STRICT, t })
     }
     const client = setup.client
     const struct = setup.struct
@@ -522,6 +534,87 @@ const GENERATE_OP: Record<string, OpGen> = {
 }
 
 
+// A failed operation rejects a stream as it rejects the operation: a
+// transport failure, and a hook that rejects the call. A throwing hook fires
+// PreUnexpected, and under throw false the call resolves to undefined. The
+// caller's ctrl stays its own.
+function failureTests(model: Model, entity: ModelEntity): string {
+  const SDK = model.Name + 'SDK'
+  const Entity = nom(entity, 'Name')
+  return `
+  class FailHook extends BaseFeature {
+    constructor() {
+      super()
+      this.name = 'failhook'
+      this.version = '0.0.1'
+      this.active = true
+      this.unexpected = 0
+    }
+    init() { }
+    PreSpec() { throw new Error('${entity.name} hook failed') }
+    PreUnexpected() { this.unexpected++ }
+  }
+
+  test('stream-error', async () => {
+    const offline = { net: { offline: true } }
+    await assert.rejects(async () => {
+      for await (const _item of ${SDK}.test(offline).${Entity}().stream('list')) { }
+    }, /offline/)
+
+    for await (const _item of ${SDK}.test(offline).${Entity}()
+      .stream('list', undefined, { ctrl: { throw: false } })) { }
+
+    if (null != config.feature?.rbac) {
+      const denied = ${SDK}.test(undefined, { feature: { rbac: { active: true, deny: true } } })
+      await assert.rejects(async () => {
+        for await (const _item of denied.${Entity}().stream('list')) { }
+      }, (err) => 'rbac_denied' === err.code)
+    }
+  })
+
+  test('stream-ctrl', async () => {
+    const explain = {}
+    const ctrl = { explain }
+    for await (const _item of ${SDK}.test().${Entity}().stream('list', undefined, { ctrl })) { }
+    assert.deepStrictEqual(Object.keys(ctrl), ['explain'])
+    assert(explain === ctrl.explain && 0 < Object.keys(explain).length)
+  })
+
+  test('unexpected', async () => {
+    const hook = new FailHook()
+    const client = new ${SDK}({ feature: { test: { active: true } }, extend: [hook] })
+    await assert.rejects(client.${Entity}().list(), /hook failed/)
+    assert(0 < hook.unexpected)
+
+    const fired = hook.unexpected
+    assert.strictEqual(await client.${Entity}().list(undefined, { throw: false }), undefined)
+    assert(fired < hook.unexpected)
+  })
+`
+}
+
+
+// An invalid request fails with validate's own error, before it is sent.
+function validateTest(model: Model, entity: ModelEntity): string {
+  const bad = invalidRequest(entity)
+  if (null == bad) {
+    return ''
+  }
+  const SDK = model.Name + 'SDK'
+  return `
+  test('validate', async (t) => {
+    if (null == config.feature?.validate) {
+      t.skip('feature not present in this SDK: validate')
+      return
+    }
+    const client = ${SDK}.test(undefined, { feature: { validate: { active: true } } })
+    await assert.rejects(client.${nom(entity, 'Name')}().${bad.op}(${JSON.stringify(bad.args)}),
+      (err) => 'validate_failed' === err.code)
+  })
+`
+}
+
+
 export {
   TestEntity
 }

package/project/.sdk/src/cmp/js/TestLive_js.ts

@@ -1,4 +1,4 @@
-import { cmp, File, Content, entityCollection, envName, serverVariables, serverVarEnv, liveHint, pointFacts } from '@voxgig/sdkgen'
+import { cmp, File, Content, entityCollection, envName, serverVariables, serverVarEnv, liveHint, pointFacts, liveStrict, liveStrictNote } from '@voxgig/sdkgen'
 import { nom } from '@voxgig/apidef'
 
 const TestLive = cmp(function TestLive(props: any) {
@@ -31,8 +31,9 @@ const { SDK } = require('..')
 const { runLiveScenarios } = require('./live-scenarios')
 const { loadEnvLocal } = require('./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 })
+${liveStrictNote(liveStrict(model, props.target.name), '//')}
+test('live operation coverage', { skip: process.env.${envName(model)}_TEST_LIVE !== 'TRUE' }, async (t) => {
+  await runLiveScenarios(SDK, ${JSON.stringify(plan, null, 2)}, '${envName(model)}', { server: { ${server} }, secret: process.env.${envName(model)}_SECRET }, { strict: ${liveStrict(model, props.target.name)}, t })
 })
 `))
 })

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

@@ -12,6 +12,10 @@ const {
   envOverride,
   liveClientOptions,
   liveDelay,
+  skipIfMissingIds,
+  liveMiss,
+  liveEmpty,
+  describeLive,
 } = require('../../utility')
 
 

package/project/.sdk/src/cmp/js/fragment/Entity.fragment.js

@@ -28,6 +28,8 @@ class EntyClass extends ProjectNameEntityBase {
 
   // #UpdateOp
 
+  // #PatchOp
+
   // #RemoveOp
 
 }

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

@@ -37,6 +37,8 @@ describe('EntityNameEntity', async () => {
     assert(null != ent)
   })
 
+  // <[SLOT:failure]>
+
 
   test('basic', async (t) => {
     // <[SLOT:basic]>

package/project/.sdk/src/cmp/js/fragment/EntityBase.fragment.js

@@ -102,17 +102,22 @@ class ProjectNameEntityBase {
   //     streaming feature when active, else the materialised items);
   //   - outbound (upload): pass an async-iterable `body` to stream a request
   //     payload — it is attached to the request so the transport can send it;
-  //   - `ctrl` (pipeline control) and `signal` (AbortSignal) are honoured.
+  //   - `ctrl` (pipeline control) and `signal` (AbortSignal) are honoured:
+  //     an abort cancels the request and ends the iteration.
   async *stream(action, args, callopts) {
     const utility = this._utility
     const {
       makeContext, done, featureHook,
-      makePoint, makeSpec, makeRequest, makeResponse, makeResult,
+      // The registry name is `makeError`; `error` is the local alias.
+      makeError: error,
     } = utility
 
     callopts = callopts || {}
-    const signal = callopts.signal
     const ctrl = { ...(callopts.ctrl || {}), stream: callopts }
+    if (null != callopts.signal) {
+      ctrl.signal = callopts.signal
+    }
+    const signal = ctrl.signal
 
     const ctx = makeContext({
       opname: action,
@@ -130,30 +135,12 @@ class ProjectNameEntityBase {
     }
 
     try {
-      let fres
-
-      fres = featureHook(ctx, 'PrePoint'); if (fres instanceof Promise) { await fres }
-      ctx.out.point = makePoint(ctx); if (ctx.out.point instanceof Error) { throw ctx.out.point }
-
-      fres = featureHook(ctx, 'PreSpec'); if (fres instanceof Promise) { await fres }
-      ctx.out.spec = makeSpec(ctx); if (ctx.out.spec instanceof Error) { throw ctx.out.spec }
-
-      fres = featureHook(ctx, 'PreRequest'); if (fres instanceof Promise) { await fres }
-      ctx.out.request = await makeRequest(ctx); if (ctx.out.request instanceof Error) { throw ctx.out.request }
-
-      fres = featureHook(ctx, 'PreResponse'); if (fres instanceof Promise) { await fres }
-      ctx.out.response = await makeResponse(ctx); if (ctx.out.response instanceof Error) { throw ctx.out.response }
-
-      fres = featureHook(ctx, 'PreResult'); if (fres instanceof Promise) { await fres }
-      ctx.out.result = await makeResult(ctx); if (ctx.out.result instanceof Error) { throw ctx.out.result }
-
-      fres = featureHook(ctx, 'PreDone'); if (fres instanceof Promise) { await fres }
-
+      const failed = await this._streamSteps(ctx)
       const result = ctx.result
 
       // Inbound: prefer the streaming feature's incremental iterator; else
       // fall back to the materialised items so `stream` always yields.
-      if (result && 'function' === typeof result.stream) {
+      if (null == failed && result && 'function' === typeof result.stream) {
         // done() does not run on this path, so its record is cleaned here.
         utility.cleanExplain(ctx)
         for await (const item of result.stream()) {
@@ -162,7 +149,8 @@ class ProjectNameEntityBase {
         }
       }
       else {
-        const data = done(ctx)
+        // A failed step leaves through makeError, as an operation's does.
+        const data = null == failed ? done(ctx) : error(ctx, failed)
         const items = Array.isArray(data) ? data : (null == data ? [] : [data])
         for (const item of items) {
           if (signal && signal.aborted) { return }
@@ -171,12 +159,50 @@ class ProjectNameEntityBase {
       }
     }
     catch (err) {
+      // What a hook throws here must not escape the cleaning below.
+      try {
+        const fres = featureHook(ctx, 'PreUnexpected')
+        if (fres instanceof Promise) { await fres }
+      }
+      catch (hookerr) {
+        err = hookerr
+      }
+
+      // An abort ends the stream quietly, whenever it lands.
       const e = this._unexpected(ctx, err)
-      if (e) { throw e }
+      if (e && true !== signal?.aborted) { throw e }
     }
   }
 
 
+  // The steps an operation runs, with their hooks; the first that fails
+  // hands back its error.
+  async _streamSteps(ctx) {
+    const {
+      featureHook, makePoint, makeSpec, makeRequest, makeResponse, makeResult,
+    } = this._utility
+
+    let fres
+
+    fres = featureHook(ctx, 'PrePoint'); if (fres instanceof Promise) { await fres }
+    ctx.out.point = makePoint(ctx); if (ctx.out.point instanceof Error) { return ctx.out.point }
+
+    fres = featureHook(ctx, 'PreSpec'); if (fres instanceof Promise) { await fres }
+    ctx.out.spec = makeSpec(ctx); if (ctx.out.spec instanceof Error) { return ctx.out.spec }
+
+    fres = featureHook(ctx, 'PreRequest'); if (fres instanceof Promise) { await fres }
+    ctx.out.request = await makeRequest(ctx); if (ctx.out.request instanceof Error) { return ctx.out.request }
+
+    fres = featureHook(ctx, 'PreResponse'); if (fres instanceof Promise) { await fres }
+    ctx.out.response = await makeResponse(ctx); if (ctx.out.response instanceof Error) { return ctx.out.response }
+
+    fres = featureHook(ctx, 'PreResult'); if (fres instanceof Promise) { await fres }
+    ctx.out.result = await makeResult(ctx); if (ctx.out.result instanceof Error) { return ctx.out.result }
+
+    fres = featureHook(ctx, 'PreDone'); if (fres instanceof Promise) { await fres }
+  }
+
+
   toJSON() {
     const struct = this._utility.struct
   // The marker is NAMESPACED. It used to be `entity$` — a short, generic

package/project/.sdk/src/cmp/js/fragment/EntityPatchOp.fragment.js

@@ -0,0 +1,129 @@
+
+class EntityOperation {
+
+
+  // EJECT-START
+
+  /**
+   * @param {EntityNameUpdateData} [reqdata]
+   * @param {Object} [ctrl]
+   * @returns {Promise<EntityName>}
+   */
+  async patch(reqdata, ctrl) {
+
+    const utility = this._utility
+
+    const {
+      makeContext,
+      done,
+      // The registry name is `makeError`; `error` is the local alias.
+      makeError: error,
+      featureHook,
+      makePoint,
+      makeRequest,
+      makeResponse,
+      makeResult,
+      makeSpec,
+    } = utility
+
+    let fres = undefined
+
+    let ctx = makeContext({
+      opname: 'patch',
+      ctrl,
+      match: this._match,
+      data: this._data,
+      reqdata
+    }, this._entctx)
+
+    try {
+
+      // #PrePoint-Hook
+
+      ctx.out.point = makePoint(ctx)
+      if (ctx.out.point instanceof Error) {
+        return error(ctx, ctx.out.point)
+      }
+
+
+      // #PreSpec-Hook
+
+      ctx.out.spec = makeSpec(ctx)
+      if (ctx.out.spec instanceof Error) {
+        return error(ctx, ctx.out.spec)
+      }
+
+
+      // #PreRequest-Hook
+
+      ctx.out.request = await makeRequest(ctx)
+      if (ctx.out.request instanceof Error) {
+        return error(ctx, ctx.out.request)
+      }
+
+
+      // #PreResponse-Hook
+
+      ctx.out.response = await makeResponse(ctx)
+      if (ctx.out.response instanceof Error) {
+        return error(ctx, ctx.out.response)
+      }
+
+
+      // #PreResult-Hook
+
+      ctx.out.result = await makeResult(ctx)
+      if (ctx.out.result instanceof Error) {
+        return error(ctx, ctx.out.result)
+      }
+
+
+      // #PreDone-Hook
+
+      if (null != ctx.result) {
+        if (null != ctx.result.resmatch) {
+          this._match = ctx.result.resmatch
+        }
+
+        if (null != ctx.result.resdata) {
+          this._data = ctx.result.resdata
+        }
+      }
+
+      const out = done(ctx)
+
+      // An operation resolves to the ENTITY, not the raw data — the record
+      // has just been absorbed into this instance and is reached through
+      // data(). `done` still runs: it completes the pipeline and raises on
+      // failure, and when throwing is disabled it hands back the error
+      // payload, which passes through unchanged. See AGENTS.md "Entity
+      // operations return ENTITIES".
+      return (ctx.result && ctx.result.ok) ? this : out
+    }
+    catch (err) {
+      // What a hook throws here must not escape the cleaning below.
+      try {
+        // #PreUnexpected-Hook
+      }
+      catch (hookerr) {
+        err = hookerr
+      }
+
+      err = this._unexpected(ctx, err)
+
+      if (err) {
+        throw err
+      }
+      else {
+        return undefined
+      }
+    }
+  }
+
+  // EJECT-END
+
+
+  _unexpected(ctx, err) { return err }
+
+}
+