@voxgig/sdkgen 4.33.0 → 4.34.1

package/project/.sdk/src/cmp/perl/TestDirect_perl.ts

@@ -15,11 +15,27 @@ import {
   serverVarEnv,
   serverVariables,
   pointParts,
+  liveStrict,
+  liveStrictNote,
 } from '@voxgig/sdkgen'
 
 import { perlStringLiteral } from './utility_perl'
 
 
+// Blocked without the ids its request needs, rather than sent with undef.
+function liveKeysBlock(N: string, label: string, block: string, keys: string[],
+  entidEnvVar: string): string {
+  return 0 === keys.length ? '' : `  if ($setup->{live}) {
+    my @missing = grep { !defined $setup->{idmap}{$_} } (${keys.map((k) => `'${k}'`).join(', ')});
+    if (@missing) {
+      ${N}TestRunner::live_miss(LIVE_STRICT, '${label}', 'Live test blocked: needs ' . join(', ', @missing) . ' via ${entidEnvVar}');
+      last ${block};
+    }
+  }
+`
+}
+
+
 function normalizePathParams(
   parts: string[],
   params: any[],
@@ -73,6 +89,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
   const model: Model = ctx$.model
 
   const entity: ModelEntity = props.entity
+  const target = props.target
 
   const N = model.const.Name
   const PROJECTNAME = envName(model)
@@ -152,6 +169,10 @@ const TestDirect = cmp(function TestDirect(props: any) {
 
   const entidEnvVar = `${PROJECTNAME}_TEST_${envToken(entity.name)}_ENTID`
 
+  // The *_ENTID key a live test reads a parameter's value from.
+  const liveKey = (param: any): string =>
+    ('id' === param.n ? entity.name : param.n.replace(/_id$/, '')) + '01'
+
   File({ name: entity.name + '_direct.t' }, () => {
 
     Content(`#!perl
@@ -167,102 +188,63 @@ use Cwd ();
 use ${N}SDK;
 require(Cwd::abs_path("$FindBin::Bin/runner.pm"));
 
+${liveStrictNote(liveStrict(model, target.name), '#')}
+use constant LIVE_STRICT => ${liveStrict(model, target.name) ? 1 : 0};
+
+sub live_ok {
+  my ($result) = @_;
+  my $status = ${N}Helpers::to_int($result->{status});
+  return !defined $result->{err} && $result->{ok} && $status >= 200 && $status < 300;
+}
+
 `)
 
     if (hasList && listPoint) {
-      const listLiveIdKeys: string[] = listParams.map((lp: any) => {
-        return lp.n === 'id'
-          ? entity.name + '01'
-          : lp.n.replace(/_id$/, '') + '01'
-      })
-      const listSkipBlock = listLiveIdKeys.length > 0
-        ? `  if ($setup->{live}) {
-    for my $_live_key (${listLiveIdKeys.map(k => `'${k}'`).join(', ')}) {
-      if (!defined $setup->{idmap}{$_live_key}) {
-        note("live test needs $_live_key via *_ENTID env var (synthetic IDs only)");
-        pass('direct-list-${entity.name}: skipped');
-        last DIRECT_LIST;
-      }
-    }
-  }
-`
-        : ''
+      const label = 'direct-list-' + entity.name
       Content(`DIRECT_LIST: {
   my $setup = ${entity.name}_direct_setup([
     { 'id' => 'direct01' },
     { 'id' => 'direct02' },
   ]);
   my ($_should_skip, $_reason) = ${N}TestRunner::is_control_skipped(
-    'direct', 'direct-list-${entity.name}', $setup->{live} ? 'live' : 'unit');
+    'direct', '${label}', $setup->{live} ? 'live' : 'unit');
   if ($_should_skip) {
     note($_reason || 'skipped via sdk-test-control.json');
-    pass('direct-list-${entity.name}: skipped via sdk-test-control.json');
+    pass('${label}: skipped via sdk-test-control.json');
     last DIRECT_LIST;
   }
-${listSkipBlock}  my $client = $setup->{client};
+${liveKeysBlock(N, label, 'DIRECT_LIST', listParams.map(liveKey), entidEnvVar)}  my $client = $setup->{client};
 
+  my $params = {};
 `)
-
-      if (listParams.length > 0) {
-        Content(`  my $params = {};
-`)
-        for (const lp of listParams) {
-          const key = lp.n === 'id'
-            ? entity.name + '01'
-            : lp.n.replace(/_id$/, '') + '01'
-          Content(`  if ($setup->{live}) {
-    $params->{'${lp.n}'} = $setup->{idmap}{'${key}'};
-  }
-  else {
-    $params->{'${lp.n}'} = 'direct01';
-  }
+      listParams.forEach((lp: any, i: number) => {
+        Content(`  $params->{'${lp.n}'} = $setup->{live} ? $setup->{idmap}{'${liveKey(lp)}'} : 'direct0${i + 1}';
 `)
-        }
-        Content(`
+      })
+      Content(`
   my $result = $client->direct({
     'path' => '${listPath}',
     'method' => 'GET',
     'params' => $params,
   });
-`)
-      } else {
-        Content(`  my $result = $client->direct({
-    'path' => '${listPath}',
-    'method' => 'GET',
-    'params' => {},
-  });
-`)
-      }
-
-      Content(`  if ($setup->{live}) {
-    # Live mode is lenient: synthetic IDs frequently 4xx and the list-
-    # response shape varies wildly across public APIs. Skip rather than
-    # fail when the call doesn't return a usable list.
-    if (defined $result->{err}) {
-      note("list call failed (likely synthetic IDs against live API): $result->{err}");
-      pass('direct-list-${entity.name}: skipped (live)');
-      last DIRECT_LIST;
-    }
-    unless ($result->{ok}) {
-      note('list call not ok (likely synthetic IDs against live API)');
-      pass('direct-list-${entity.name}: skipped (live)');
+  if ($setup->{live}) {
+    if (!live_ok($result)) {
+      ${N}TestRunner::live_miss(LIVE_STRICT, '${label}', 'Live list failed: ' . ${N}TestRunner::live_describe($result));
       last DIRECT_LIST;
     }
-    my $status = ${N}Helpers::to_int($result->{status});
-    if ($status < 200 || $status >= 300) {
-      note("expected 2xx status, got $status");
-      pass('direct-list-${entity.name}: skipped (live)');
+    if (!defined ${N}TestRunner::live_list($result->{data})) {
+      ${N}TestRunner::live_miss(LIVE_STRICT, '${label}', 'Live list returned no list: ' . ${N}TestRunner::live_describe($result));
       last DIRECT_LIST;
     }
-    pass('direct-list-${entity.name}: live ok');
+    pass('${label}: live ok');
   }
   else {
-    ok(!defined $result->{err}, 'direct-list-${entity.name}: no error');
-    ok($result->{ok}, 'direct-list-${entity.name}: ok');
-    is(${N}Helpers::to_int($result->{status}), 200, 'direct-list-${entity.name}: status');
-    ok(Voxgig::Struct::islist($result->{data}), 'direct-list-${entity.name}: data is array');
-    is(scalar @{ $result->{data} }, 2, 'direct-list-${entity.name}: data length');
-    is(scalar @{ $setup->{calls} }, 1, 'direct-list-${entity.name}: 1 call');
+    ok(!defined $result->{err}, '${label}: no error');
+    ok($result->{ok}, '${label}: ok');
+    is(${N}Helpers::to_int($result->{status}), 200, '${label}: status');
+    ok(Voxgig::Struct::islist($result->{data}), '${label}: data is array');
+    is(scalar @{ $result->{data} }, 2, '${label}: data length');
+    is(scalar @{ $setup->{calls} }, 1, '${label}: 1 call');
   }
 }
 
@@ -270,114 +252,103 @@ ${listSkipBlock}  my $client = $setup->{client};
     }
 
     if (hasLoad && loadPoint) {
-      const loadSkipBlock = (loadParams.length > 0 && !loadAllHaveExamples)
-        ? `  if ($setup->{live}) {
-    note('live direct-load needs real ID - set *_ENTID env var with real IDs to run');
-    pass('direct-load-${entity.name}: skipped (live)');
-    last DIRECT_LOAD;
-  }
-`
-        : ''
+      const label = 'direct-load-' + entity.name
+      const discover = !loadAllHaveExamples && hasList && 0 < loadParams.length
+      const idParam = loadParams.find((p: any) => 'id' === p.n)?.n ?? loadParams[0]?.n ?? 'id'
+      const loadLiveIdKeys: string[] = loadAllHaveExamples ? [] :
+        discover ? listParams.map(liveKey).concat(loadParams.filter((p: any) => idParam !== p.n).map(liveKey)) :
+          loadParams.map(liveKey)
       Content(`DIRECT_LOAD: {
   my $setup = ${entity.name}_direct_setup({ 'id' => 'direct01' });
   my ($_should_skip, $_reason) = ${N}TestRunner::is_control_skipped(
-    'direct', 'direct-load-${entity.name}', $setup->{live} ? 'live' : 'unit');
+    'direct', '${label}', $setup->{live} ? 'live' : 'unit');
   if ($_should_skip) {
     note($_reason || 'skipped via sdk-test-control.json');
-    pass('direct-load-${entity.name}: skipped via sdk-test-control.json');
+    pass('${label}: skipped via sdk-test-control.json');
     last DIRECT_LOAD;
   }
-${loadSkipBlock}  my $client = $setup->{client};
-
-`)
+${liveKeysBlock(N, label, 'DIRECT_LOAD', [...new Set(loadLiveIdKeys)], entidEnvVar)}  my $client = $setup->{client};
 
-      const needsQuery = loadParams.length > 0 || loadLiveQueryLines !== ''
-      if (needsQuery) {
-        Content(`  my $params = {};
+  my $params = {};
   my $query = {};
+  if ($setup->{live}) {
+${loadLiveQueryLines ? loadLiveQueryLines + '\n' : ''}`)
+      if (loadAllHaveExamples) {
+        Content(loadExampleLines + '\n')
+      }
+      else if (discover) {
+        Content(`    my $list_result = $client->direct({
+      'path' => '${listPath}',
+      'method' => 'GET',
+      'params' => {${listParams.map((p: any) => `'${p.n}' => $setup->{idmap}{'${liveKey(p)}'}`).join(', ')}},
+    });
+    if (!live_ok($list_result)) {
+      ${N}TestRunner::live_miss(LIVE_STRICT, '${label}', 'Live list discovery failed: ' . ${N}TestRunner::live_describe($list_result));
+      last DIRECT_LOAD;
+    }
+    my $records = ${N}TestRunner::live_list($list_result->{data});
+    if (!defined $records) {
+      ${N}TestRunner::live_miss(LIVE_STRICT, '${label}', 'Live list discovery returned no list: ' . ${N}TestRunner::live_describe($list_result));
+      last DIRECT_LOAD;
+    }
+    if (!@$records) {
+      ${N}TestRunner::live_empty('${label}', 'The account has no ${entity.name} record to load');
+      last DIRECT_LOAD;
+    }
+    my $first = ref $records->[0] eq 'HASH' ? $records->[0] : {};
+    my $found = $first->{'${idParam}'} // $first->{'id'};
+    if (!defined $found) {
+      ${N}TestRunner::live_miss(LIVE_STRICT, '${label}', 'Live load blocked: discovery returned no usable identity');
+      last DIRECT_LOAD;
+    }
+    $params->{'${idParam}'} = $found;
 `)
-        if (loadAllHaveExamples) {
-          Content(`  if ($setup->{live}) {
-`)
-          if (loadLiveQueryLines) Content(loadLiveQueryLines + '\n')
-          Content(loadExampleLines + '\n')
-          Content(`  }
-  else {
-`)
-          for (let i = 0; i < loadParams.length; i++) {
-            Content(`    $params->{'${loadParams[i].n}'} = 'direct0${i + 1}';
-`)
-          }
-          Content(`  }
-`)
-        } else if (loadParams.length > 0) {
-          if (loadLiveQueryLines) {
-            Content(`  if ($setup->{live}) {
-${loadLiveQueryLines}
-  }
+        for (const p of loadParams.filter((p: any) => idParam !== p.n)) {
+          Content(`    $params->{'${p.n}'} = $setup->{idmap}{'${liveKey(p)}'};
 `)
-          }
-          Content(`  unless ($setup->{live}) {
-`)
-          for (let i = 0; i < loadParams.length; i++) {
-            Content(`    $params->{'${loadParams[i].n}'} = 'direct0${i + 1}';
+        }
+      }
+      else {
+        for (const p of loadParams) {
+          Content(`    $params->{'${p.n}'} = $setup->{idmap}{'${liveKey(p)}'};
 `)
-          }
-          Content(`  }
+        }
+      }
+      Content(`  }
+  else {
 `)
-        } else if (loadLiveQueryLines) {
-          Content(`  if ($setup->{live}) {
-${loadLiveQueryLines}
-  }
+      for (let i = 0; i < loadParams.length; i++) {
+        Content(`    $params->{'${loadParams[i].n}'} = 'direct0${i + 1}';
 `)
-        }
       }
+      Content(`  }
 
-      Content(`
   my $result = $client->direct({
     'path' => '${loadPath}',
     'method' => 'GET',
-`)
-      if (needsQuery) {
-        Content(`    'params' => $params,
+    'params' => $params,
     'query' => $query,
-`)
-      } else {
-        Content(`    'params' => {},
-`)
-      }
-      Content(`  });
+  });
   if ($setup->{live}) {
-    # Live mode is lenient: synthetic IDs frequently 4xx. Skip rather
-    # than fail when the load endpoint isn't reachable with the IDs
-    # we can construct from setup idmap.
-    if (defined $result->{err}) {
-      note("load call failed (likely synthetic IDs against live API): $result->{err}");
-      pass('direct-load-${entity.name}: skipped (live)');
-      last DIRECT_LOAD;
-    }
-    unless ($result->{ok}) {
-      note('load call not ok (likely synthetic IDs against live API)');
-      pass('direct-load-${entity.name}: skipped (live)');
+    if (!live_ok($result)) {
+      ${N}TestRunner::live_miss(LIVE_STRICT, '${label}', 'Live load failed: ' . ${N}TestRunner::live_describe($result));
       last DIRECT_LOAD;
     }
-    my $status = ${N}Helpers::to_int($result->{status});
-    if ($status < 200 || $status >= 300) {
-      note("expected 2xx status, got $status");
-      pass('direct-load-${entity.name}: skipped (live)');
+    if (!defined $result->{data}) {
+      ${N}TestRunner::live_miss(LIVE_STRICT, '${label}', 'Live load returned no data: ' . ${N}TestRunner::live_describe($result));
       last DIRECT_LOAD;
     }
-    pass('direct-load-${entity.name}: live ok');
+    pass('${label}: live ok');
   }
   else {
-    ok(!defined $result->{err}, 'direct-load-${entity.name}: no error');
-    ok($result->{ok}, 'direct-load-${entity.name}: ok');
-    is(${N}Helpers::to_int($result->{status}), 200, 'direct-load-${entity.name}: status');
-    ok(defined $result->{data}, 'direct-load-${entity.name}: data');
+    ok(!defined $result->{err}, '${label}: no error');
+    ok($result->{ok}, '${label}: ok');
+    is(${N}Helpers::to_int($result->{status}), 200, '${label}: status');
+    ok(defined $result->{data}, '${label}: data');
     if (Voxgig::Struct::ismap($result->{data})) {
-      is($result->{data}{id}, 'direct01', 'direct-load-${entity.name}: id');
+      is($result->{data}{id}, 'direct01', '${label}: id');
     }
-    is(scalar @{ $setup->{calls} }, 1, 'direct-load-${entity.name}: 1 call');
+    is(scalar @{ $setup->{calls} }, 1, '${label}: 1 call');
   }
 }
 
@@ -405,11 +376,12 @@ sub ${entity.name}_direct_setup {
     my $client = ${N}SDK->new({
       %{ ${N}TestRunner::live_client_options() },${apikeyLiveField}${serverLiveField}
     });
+    my $idmap = $env->{'${entidEnvVar}'};
     return {
       'client' => $client,
       'calls' => $calls,
       'live' => 1,
-      'idmap' => {},
+      'idmap' => ref $idmap eq 'HASH' ? $idmap : {},
     };
   }
 

package/project/.sdk/src/cmp/perl/TestEntity_perl.ts

@@ -1,4 +1,4 @@
-import { flowSteps } from '@voxgig/sdkgen'
+import { flowSteps, opReachable, invalidRequest } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -20,7 +20,8 @@ import {
   getMatchEntries,
   isAuthActive, envName, envToken,
   serverVarEnv,
-  serverVariables
+  serverVariables,
+  liveFlowNeeds, liveStrict, liveStrictNote,
 } from '@voxgig/sdkgen'
 
 import { perlStringLiteral } from './utility_perl'
@@ -40,11 +41,55 @@ type GenCtx = {
 type OpGen = (ctx: GenCtx, step: ModelEntityFlowStep, index: number) => void
 
 
+// The live prologue of a flow built from offline fixtures: blocked without
+// the ids it binds, a create-less load reading the first listed record, and
+// a lenient run reporting a failed check without failing the test.
+function liveFlowGate(N: string, entity: any, needs: any, entidEnv: string,
+  strict: boolean): string {
+  const label = entity.name + ': basic flow'
+  let out = ''
+  if (0 < needs.keys.length) {
+    out += `  if ($setup->{live}) {
+    my @missing = grep { $setup->{synthetic_only} || !defined $setup->{idmap}{$_} } (${needs.keys.map((k: string) => `'${k}'`).join(', ')});
+    if (@missing) {
+      ${N}TestRunner::live_miss(LIVE_STRICT, '${label}', 'Live entity test blocked: needs ' . join(', ', @missing) . ' via ${entidEnv}');
+      last BASIC_FLOW;
+    }
+  }
+`
+  }
+  if (null != needs.blocked) {
+    out += `  if ($setup->{live}) {
+    ${N}TestRunner::live_miss(LIVE_STRICT, '${label}', 'Live entity test blocked: ${needs.blocked}');
+    last BASIC_FLOW;
+  }
+`
+  }
+  out += '  my $client = $setup->{client};\n'
+  if (null != needs.discover) {
+    const match = Object.entries(needs.discover)
+      .map(([k, v]: any) => `'${k}' => $setup->{idmap}{'${v}'}`).join(', ')
+    out += `  if ($setup->{live}) {
+    ${N}TestRunner::live_existing($setup, LIVE_STRICT, '${label}', '${entity.name}',
+      sub { $client->${entity.Name}(undef)->list({${match}}, undef) }) or last BASIC_FLOW;
+  }
+`
+  }
+  if (!strict) {
+    out += `  local $main::TODO = $setup->{live} ? 'live run, main.kit.test.live.strict is false' : undef;
+  eval {
+`
+  }
+  return out
+}
+
+
 const TestEntity = cmp(function TestEntity(props: any) {
   const ctx$ = props.ctx$
   const model: Model = ctx$.model
 
   const entity: ModelEntity = props.entity
+  const target = props.target
 
   const basicflow: ModelEntityFlow | undefined =
     getModelPath(model, `main.${KIT}.flow.Basic${nom(entity, 'Name')}Flow`)
@@ -99,6 +144,12 @@ const TestEntity = cmp(function TestEntity(props: any) {
 
   const genCtx: GenCtx = { model, entity, flow: basicflow, N, PROJUPPER }
 
+  const strict = liveStrict(model, target.name)
+  const needs = liveFlowNeeds(entity, basicflow)
+  // The failure tests stream and list with no match, so they need a list a
+  // bare call can reach.
+  const hasList = opReachable((entity.op as any)?.list, [])
+
   File({ name: entity.name + '_entity.t' }, () => {
 
     Content(`#!perl
@@ -114,12 +165,15 @@ use Cwd ();
 use ${N}SDK;
 require(Cwd::abs_path("$FindBin::Bin/runner.pm"));
 
+${liveStrictNote(strict, '#')}
+use constant LIVE_STRICT => ${strict ? 1 : 0};
+
 {
   my $testsdk = ${N}SDK->test(undef, undef);
   my $ent = $testsdk->${entity.Name}(undef);
   ok(defined $ent, '${entity.name}: create instance');
 }
-
+${hasList ? failureTests(N, entity) : ''}${validateTest(N, entity)}
 BASIC_FLOW: {
   my $setup = ${entity.name}_basic_setup(undef);
   my $_live = $setup->{live} ? 1 : 0;
@@ -133,15 +187,7 @@ BASIC_FLOW: {
       last BASIC_FLOW;
     }
   }
-  # The basic flow consumes synthetic IDs from the fixture. In live mode
-  # without an *_ENTID env override, those IDs hit the live API and 4xx.
-  if ($setup->{synthetic_only}) {
-    note('live entity test uses synthetic IDs from fixture - set ${ENTIDVAR} JSON to run live');
-    pass('${entity.name}: basic flow skipped (synthetic IDs only)');
-    last BASIC_FLOW;
-  }
-  my $client = $setup->{client};
-  my %V;
+${liveFlowGate(N, entity, needs, ENTIDVAR, strict)}  my %V;
 
 `)
 
@@ -168,7 +214,9 @@ BASIC_FLOW: {
       }
     })
 
-    Content(`}
+    Content(`${strict ? '' : `    1;
+  } or ${N}TestRunner::live_observe($@, $setup, LIVE_STRICT, '${entity.name}: basic flow');
+`}}
 
 `)
 
@@ -201,10 +249,8 @@ BASIC_FLOW: {
     }
   );
 
-  # Detect ENTID env override before env_override consumes it. When live
-  # mode is on without a real override, the basic test runs against
-  # synthetic IDs from the fixture and 4xx's. Surface this so the test can
-  # skip.
+  # Whether *_ENTID supplied the idmap, read before env_override consumes
+  # it: without it, the ids a live flow binds are the fixture's synthetic ones.
   my $entid_env_raw = $ENV{'${ENTIDVAR}'};
   my $idmap_overridden = (defined $entid_env_raw && $entid_env_raw =~ /^\\s*\\{/) ? 1 : 0;
 
@@ -536,6 +582,121 @@ const GENERATE_OP: Record<string, OpGen> = {
 }
 
 
+// A failed operation raises from a stream as it does from the operation: a
+// transport failure, and a hook that rejects the call. A dying hook fires
+// PreUnexpected, and under throw false the call returns undef. The caller's
+// ctrl stays its own.
+function failureTests(N: string, entity: ModelEntity): string {
+  const Entity = entity.Name
+  const Hook = N + 'EntityTest' + Entity + 'FailHook'
+  return `
+{
+  package ${Hook};
+  our @ISA = ('${N}BaseFeature');
+
+  sub new {
+    my ($class) = @_;
+    my $self = ${N}BaseFeature::new($class);
+    $self->{name} = 'failhook';
+    $self->{unexpected} = 0;
+    return $self;
+  }
+
+  sub init { }
+  sub PreSpec { die "${entity.name} hook failed\\n" }
+  sub PreUnexpected { $_[0]->{unexpected}++; return }
+}
+
+{
+  my $offline = { net => { offline => 1 } };
+  my $died = !eval {
+    my $next = ${N}SDK->test($offline, undef)->${Entity}(undef)->stream('list', undef, undef);
+    1 while defined $next->();
+    1;
+  };
+  like($died ? "$@" : '', qr/offline/, '${entity.name}: a failed stream raises');
+
+  ok(eval {
+    my $next = ${N}SDK->test($offline, undef)->${Entity}(undef)
+      ->stream('list', undef, { ctrl => { throw => 0 } });
+    1 while defined $next->();
+    1;
+  }, '${entity.name}: under throw false a failed stream ends');
+
+  if (${N}Config::shared_config()->{feature}{rbac}) {
+    my $denied = ${N}SDK->test(undef, { feature => { rbac => { active => 1, deny => 1 } } });
+    my $denyerr = eval {
+      my $next = $denied->${Entity}(undef)->stream('list', undef, undef);
+      1 while defined $next->();
+      undef;
+    } // $@;
+    is(ref $denyerr ? $denyerr->{code} : undef, 'rbac_denied',
+      '${entity.name}: a denied stream raises');
+  }
+}
+
+{
+  my $explain = {};
+  my $ctrl = { explain => $explain };
+  my $next = ${N}SDK->test(undef, undef)->${Entity}(undef)
+    ->stream('list', undef, { ctrl => $ctrl });
+  1 while defined $next->();
+  is_deeply([sort keys %$ctrl], ['explain'], '${entity.name}: the stream leaves the caller ctrl');
+  ok($explain == $ctrl->{explain} && 0 < keys %$explain,
+    '${entity.name}: the caller explain record is filled');
+}
+
+{
+  my $hook = ${Hook}->new;
+  my $client = ${N}SDK->new({ feature => { test => { active => 1 } }, extend => [$hook] });
+
+  my $err = eval { $client->${Entity}(undef)->list(undef, undef); undef } // $@;
+  like("$err", qr/hook failed/, '${entity.name}: a dying hook fails the operation');
+  ok(0 < $hook->{unexpected}, '${entity.name}: PreUnexpected fired');
+
+  my $fired = $hook->{unexpected};
+  my $out = eval { $client->${Entity}(undef)->list(undef, { throw => 0 }) };
+  ok(!$@ && !defined $out, '${entity.name}: under throw false the call returns undef');
+  ok($fired < $hook->{unexpected}, '${entity.name}: PreUnexpected fired under throw false');
+}
+
+{
+  my $seed = { entity => { '${entity.name}' => { l1 => { id => 'l1' }, l2 => { id => 'l2' } } } };
+  my $items = ${N}SDK->test($seed, undef)->${Entity}(undef)->list(undef, undef);
+  # list resolves to one entity per record; data_get reads the record.
+  is(scalar(@$items), 2, '${entity.name}: list answers each seeded record');
+  my $entities = grep {
+    Scalar::Util::blessed($_) && $_->can('data_get') && Voxgig::Struct::ismap($_->data_get)
+  } @$items;
+  is($entities, 2, '${entity.name}: each listed item is an entity carrying its record');
+}
+`
+}
+
+
+// An invalid request fails with validate's own error, before it is sent.
+function validateTest(N: string, entity: ModelEntity): string {
+  const bad = invalidRequest(entity)
+  if (null == bad) {
+    return ''
+  }
+  const args = Object.entries(bad.args)
+    .map(([k, v]) => perlStringLiteral(k) + ' => ' +
+      ('string' === typeof v ? perlStringLiteral(v) : true === v ? '1' : String(v)))
+    .join(', ')
+  return `
+SKIP: {
+  skip('feature not present in this SDK: validate', 1)
+    unless ${N}Config::shared_config()->{feature}{validate};
+  my $client = ${N}SDK->test(undef, { feature => { validate => { active => 1 } } });
+  my $err = eval { $client->${entity.Name}(undef)->${bad.op}({ ${args} }, undef); undef } // $@;
+  is(ref $err ? $err->{code} : undef, 'validate_failed',
+    '${entity.name}: an invalid request fails with validate_failed');
+}
+`
+}
+
+
 export {
   TestEntity
 }

package/project/.sdk/src/cmp/perl/fragment/Entity.fragment.pm

@@ -127,6 +127,8 @@ sub match_get {
 
 # #UpdateOp
 
+# #PatchOp
+
 # #RemoveOp
 
 # Streaming operation. Runs `action` (an op name, e.g. 'list') through the
@@ -149,8 +151,9 @@ sub stream {
   my $utility = $self->{_utility};
   $callopts = ProjectNameHelpers::to_map($callopts) || {};
   my $signal = ProjectNameHelpers::gp($callopts, 'signal');
-  my $ctrl = ProjectNameHelpers::to_map(
-    ProjectNameHelpers::gp($callopts, 'ctrl')) || {};
+  # A copy: the caller's ctrl gains no key, and explain stays its own record.
+  my $ctrl = { %{ ProjectNameHelpers::to_map(
+    ProjectNameHelpers::gp($callopts, 'ctrl')) || {} } };
   $ctrl->{stream} = $callopts;
 
   my $ctx = $utility->{make_context}->({
@@ -205,6 +208,17 @@ sub stream {
       if (my $operr = $@) {
         $src = sub { return undef };
         $ctx->{ctrl}{err} = $operr;
+
+        # What a hook dies with here must not escape the cleaning below.
+        my $fired = eval {
+          $utility->{feature_hook}->($ctx, 'PreUnexpected');
+          1;
+        };
+        if (!$fired) {
+          $operr = $@;
+          $ctx->{ctrl}{err} = $operr;
+        }
+
         my $e = $self->_unexpected($ctx, $operr);
         die $e if defined $e;
         return undef;