@voxgig/sdkgen 4.23.0 → 4.24.0

package/project/.sdk/tm/ocaml/sdk_features.ml

@@ -1121,9 +1121,15 @@ let paging_feature () : feature =
                 | Noval | Null ->
                   (match getp q page_param with
                    | Noval ->
-                     let page = (match getp paging "page" with
-                         | Noval | Null -> (match getp !options "startPage" with Num n -> Num n | _ -> Num 1.)
-                         | p -> p) in
+                     (* A record written back by PreResult holds the page just
+                      * fetched as `page` and the one to fetch as `nextPage`,
+                      * so nextPage wins. *)
+                     let page = (match getp paging "nextPage" with
+                         | Noval | Null ->
+                           (match getp paging "page" with
+                            | Noval | Null -> (match getp !options "startPage" with Num n -> Num n | _ -> Num 1.)
+                            | p -> p)
+                         | np -> np) in
                      setp q page_param page
                    | _ -> ())
                 | c -> setp q cursor_param c);
@@ -1176,11 +1182,20 @@ let paging_feature () : feature =
              (match body with
               | Map _ ->
                 (match getp body "next" with Noval | Null -> () | n -> if is_nullish (getp paging "next") then setp paging "next" n);
+                (* Both spellings, camelCase last so it wins when a body
+                 * carries the two. *)
+                (match getp body "next_cursor" with Noval | Null -> () | c -> setp paging "cursor" c);
                 (match getp body "cursor" with Noval | Null -> () | c -> setp paging "cursor" c);
                 (match getp body "nextCursor" with Noval | Null -> () | c -> setp paging "cursor" c);
-                (match getp body "hasMore" with
-                 | Bool b -> setp paging "hasMore" (Bool b); explicit_more := true
-                 | _ -> ())
+                if is_nullish (getp paging "nextPage") then begin
+                  let np = (match getp body "nextPage" with
+                      | Noval | Null -> getp body "next_page"
+                      | v -> v) in
+                  (match np with Num _ | Str _ -> setp paging "nextPage" np | _ -> ())
+                end;
+                List.iter (fun k -> match getp body k with
+                    | Bool b -> setp paging "hasMore" (Bool b); explicit_more := true
+                    | _ -> ()) ["has_more"; "hasMore"]
               | _ -> ());
              (* Cursor presence only INFERS another page. When the server
               * stated the answer outright — relay's `hasNextPage: false`, or
@@ -1196,6 +1211,16 @@ let paging_feature () : feature =
                setp paging "hasMore" (Bool hm)
              end;
              result.rt_paging <- paging;
+             (* The record reached the caller through ctrl in every other typed
+              * port and through nothing here, so a caller who asked for paging
+              * got the pages and never the signals to continue. *)
+             (match ctx.c_ctrl.ctrl_paging with
+              | Map _ as held ->
+                (* The caller holds this map: refill it in place. Every key of
+                 * the record is written, so no key of an earlier page lives on. *)
+                List.iter (fun k -> setp held k (getp paging k))
+                  ["page"; "totalCount"; "nextPage"; "next"; "cursor"; "hasMore"]
+              | _ -> ctx.c_ctrl.ctrl_paging <- paging);
              track_set (cc ctx) "paging" (jo [("last", paging)]))
         | _ -> ());
   f
@@ -1408,21 +1433,43 @@ let test_feature () : feature =
     let out = jo [("status", vint_of status); ("statusText", Str "OK"); ("json", json_thunk (envelope ctx data)); ("body", Str "not-used")] in
     (match extra with Some (Map _ as e) -> List.iter (fun k -> setp out k (getp e k)) (keysof e) | _ -> ());
     (out, None) in
+  let point_terminal p =
+    match getp p "parts" with
+    | List r -> (match List.rev !r with Str s :: _ -> String.length s > 0 && s.[0] = '{' | _ -> false)
+    | _ -> false in
+  let point_depth p = match getp p "parts" with List r -> List.length !r | _ -> 0 in
+  (* The entity's own endpoint: a terminal `{param}` marks a record route, and
+     among equals the shallower path wins (the same rule as make_point). *)
+  let pick_point points =
+    match points with
+    | List r ->
+      (match !r with
+       | [] -> Noval
+       | first :: rest ->
+         List.fold_left (fun point cand ->
+             if point_terminal cand <> point_terminal point then (if point_terminal cand then cand else point)
+             else if point_depth cand < point_depth point then cand
+             else point) first rest)
+    | _ -> Noval in
+  let reqd_names point kind =
+    let reqd_args = select (getpath_s point ("args." ^ kind)) (jo [("reqd", Bool true)]) in
+    transform reqd_args (ja [Str "`$EACH`"; Str ""; Str "`$KEY.name`"]) in
   let build_args ctx (op : operation) args =
     let opname = op.op_name in
     let entname = match ctx.c_entity with Some e -> e.e_name | None -> "_" in
     let points = getpath_s ctx.c_config ("entity." ^ entname ^ ".op." ^ opname ^ ".points") in
-    let point = getelem points (Num (-1.0)) in
-    let params_path = getpath_s point "args.params" in
-    let reqd_params = select params_path (jo [("reqd", Bool true)]) in
-    let reqd = transform reqd_params (ja [Str "`$EACH`"; Str ""; Str "`$KEY.name`"]) in
+    let point = pick_point points in
+    (* Path AND query: a path-only read misses a query-addressed record
+       (e.g. GET /result?trace_id=), which has no path param at all. *)
+    let reqd_params = reqd_names point "params" in
+    let reqd_query = reqd_names point "query" in
     let qand = ref [] in
     (match args with
      | Map _ ->
        List.iter (fun key ->
            let is_id = key = "id" in
-           let selected = select reqd (Str key) in
-           let is_reqd = not (isempty selected) in
+           let is_reqd = not (isempty (select reqd_params (Str key)))
+                         || not (isempty (select reqd_query (Str key))) in
            if is_id || is_reqd then begin
              let v = (cu ctx).u_param ctx (Str key) in
              let ka = (match op.op_alias with Map _ -> (match getp op.op_alias key with Str s -> Some s | _ -> None) | _ -> None) in
@@ -1463,18 +1510,22 @@ let test_feature () : feature =
          end
        | "update" ->
          let update_match = empty_map () in
-         (match fctx.c_reqdata with Map _ -> (match getp fctx.c_reqdata "id" with Noval -> () | v -> setp update_match "id" v) | _ -> ());
+         (match fctx.c_reqdata with
+          | Map _ ->
+            (match getp fctx.c_reqdata "id" with Noval -> () | v -> setp update_match "id" v);
+            (match getp op.op_alias "id" with
+             | Str alias_id -> (match getp fctx.c_reqdata alias_id with Noval -> () | v -> setp update_match alias_id v)
+             | _ -> ())
+          | _ -> ());
          let update_match = if size update_match > 0 then update_match else resolve_match fctx (empty_map ()) in
          let args = build_args fctx op update_match in
-         let ent = ref (getelem (select entmap args) (Num 0.0)) in
-         (if is_nullish !ent then match entmap with
-           | Map m -> (try (match List.find (fun (_, v) -> match v with Map _ -> true | _ -> false) m.entries with (_, v) -> ent := v) with Not_found -> ())
-           | _ -> ());
-         if is_nullish !ent then respond fctx 404 Noval (Some (jo [("statusText", Str "Not found")]))
+         let ent = getelem (select entmap args) (Num 0.0) in
+         (* update miss: 404, never another record *)
+         if is_nullish ent then respond fctx 404 Noval (Some (jo [("statusText", Str "Not found")]))
          else begin
-           (match !ent with Map _ -> (match fctx.c_reqdata with Map _ -> List.iter (fun k -> setp !ent k (getp fctx.c_reqdata k)) (keysof fctx.c_reqdata) | _ -> ()) | _ -> ());
-           ignore (delprop !ent (Str "$KEY"));
-           respond fctx 200 (clone !ent) None
+           (match ent, fctx.c_reqdata with Map _, Map _ -> ignore (merge (ja [ent; fctx.c_reqdata])) | _ -> ());
+           ignore (delprop ent (Str "$KEY"));
+           respond fctx 200 (clone ent) None
          end
        | "remove" ->
          let args = build_args fctx op (resolve_match fctx fctx.c_reqmatch) in

package/project/.sdk/tm/ocaml/sdk_runtime.ml

@@ -189,7 +189,9 @@ let make_context_impl (cs : ctxspec) (basectx : ctx option) : ctx =
       (match getp cr "actor" with Noval -> () | a -> c.ctrl_actor <- a);
       (match getp cr "paging" with Map _ as m -> c.ctrl_paging <- m | _ -> ());
       c
-    | _ -> (match basectx with Some b -> b.c_ctrl | None -> new_control ())
+    | _ -> (match basectx with
+        | Some b when cs.cs_opname = None -> b.c_ctrl
+        | _ -> new_control ())
   in
   let meta =
     match cs.cs_meta with Some (Map _ as m) -> m
@@ -413,7 +415,7 @@ let prepare_query_util (ctx : ctx) : value =
   let out = empty_map () in
   List.iter (fun k ->
       let v = getp reqmatch k in
-      if not (is_noval v) && not (contains_param k) then setp out k v)
+      if not (is_noval v) && k <> "$action" && not (contains_param k) then setp out k v)
     (keysof reqmatch);
   out
 
@@ -555,14 +557,27 @@ let prepare_auth_util = Sdk_prepare_auth.prepare_auth_util
 
 (* ----- transforms / result helpers ----- *)
 
+(* `$action` selects the point (see make_point_util); it is never an API
+   field, so the body is a copy without it. The caller's map is left
+   untouched. *)
+let strip_action (reqdata : value) : value =
+  match reqdata with
+  | Map _ when List.mem "$action" (keysof reqdata) ->
+    let body = empty_map () in
+    List.iter (fun k -> if k <> "$action" then setp body k (getp reqdata k))
+      (keysof reqdata);
+    body
+  | _ -> reqdata
+
 let transform_request_util (ctx : ctx) : value =
   (match ctx.c_spec with Some s -> s.sp_step <- "reqform" | None -> ());
-  match to_map (getp ctx.c_point "transform") with
-  | Map _ as tr ->
-    (match getp tr "req" with
-     | Noval -> ctx.c_reqdata
-     | reqform -> transform (jo [("reqdata", ctx.c_reqdata)]) reqform)
-  | _ -> ctx.c_reqdata
+  strip_action
+    (match to_map (getp ctx.c_point "transform") with
+     | Map _ as tr ->
+       (match getp tr "req" with
+        | Noval -> ctx.c_reqdata
+        | reqform -> transform (jo [("reqdata", ctx.c_reqdata)]) reqform)
+     | _ -> ctx.c_reqdata)
 
 let transform_response_util (ctx : ctx) : value =
   (match ctx.c_spec with Some s -> s.sp_step <- "resform" | None -> ());

package/project/.sdk/tm/perl/core/context.pm

@@ -45,7 +45,8 @@ sub new {
     $self->{ctrl}{actor} = $ctrl_raw->{actor} if exists $ctrl_raw->{actor};
     $self->{ctrl}{paging} = $ctrl_raw->{paging} if Voxgig::Struct::ismap($ctrl_raw->{paging});
   }
-  elsif ($basectx && $basectx->{ctrl}) {
+  elsif ($basectx && $basectx->{ctrl}
+      && !defined ProjectNameHelpers::get_ctx_prop($ctxmap, 'opname')) {
     $self->{ctrl} = $basectx->{ctrl};
   }
 

package/project/.sdk/tm/perl/feature/paging_feature.pm

@@ -4,8 +4,8 @@
 # stamps page/limit (or a cursor) into the request query; on the way back
 # (PreResult) it reads the server's pagination signals - a Link rel="next"
 # header, X-Page/X-Next-Page/X-Total-Count headers, or next/cursor/
-# nextCursor/hasMore fields in the body - and records them on
-# result.paging. A per-call ctrl paging value (page or cursor) takes
+# nextCursor/hasMore fields in the body (snake_case forms too) - and records
+# them on result.paging and the caller's ctrl paging. A per-call ctrl paging value (page or cursor) takes
 # priority. Parameter names ("pageParam", "limitParam", "cursorParam"),
 # "startPage" (default 1) and page size ("limit") are configurable.
 
@@ -76,8 +76,11 @@ sub PreRequest {
     $spec->{query}{$cursor_param} = $paging->{cursor};
   }
   elsif (!defined $spec->{query}{$page_param}) {
-    $spec->{query}{$page_param} = defined $paging->{page}
-      ? $paging->{page}
+    # A record written back by PreResult holds the page just fetched as
+    # "page" and the one to fetch as "nextPage", so nextPage wins.
+    my $page = defined $paging->{nextPage} ? $paging->{nextPage} : $paging->{page};
+    $spec->{query}{$page_param} = defined $page
+      ? $page
       : (defined $self->{options}{startPage} ? $self->{options}{startPage} : 1);
   }
 
@@ -186,15 +189,27 @@ sub PreResult {
     }
   }
 
-  # Body-level cursors.
+  # Body-level signals; snake_case forms are read first so camelCase wins.
   if (Voxgig::Struct::ismap($body)) {
     my $bnext = ProjectNameHelpers::gp($body, 'next');
     $paging->{next} = defined $paging->{next} ? $paging->{next} : $bnext
       if defined $bnext;
+    my $bsnakecursor = ProjectNameHelpers::gp($body, 'next_cursor');
+    $paging->{cursor} = $bsnakecursor if defined $bsnakecursor;
     my $bcursor = ProjectNameHelpers::gp($body, 'cursor');
     $paging->{cursor} = $bcursor if defined $bcursor;
     my $bnextcursor = ProjectNameHelpers::gp($body, 'nextCursor');
     $paging->{cursor} = $bnextcursor if defined $bnextcursor;
+    unless (defined $paging->{nextPage}) {
+      my $np = ProjectNameHelpers::gp($body, 'nextPage');
+      $np = ProjectNameHelpers::gp($body, 'next_page') unless defined $np;
+      $paging->{nextPage} = $np if defined $np && !ref($np);
+    }
+    my $bsnakemore = $body->{has_more};
+    if (ProjectNameHelpers::is_true($bsnakemore) || ProjectNameHelpers::is_false($bsnakemore)) {
+      $paging->{hasMore} = ProjectNameHelpers::is_true($bsnakemore) ? 1 : 0;
+      $explicit_more = 1;
+    }
     my $bhasmore = $body->{hasMore};
     if (ProjectNameHelpers::is_true($bhasmore) || ProjectNameHelpers::is_false($bhasmore)) {
       $paging->{hasMore} = ProjectNameHelpers::is_true($bhasmore) ? 1 : 0;
@@ -215,6 +230,17 @@ sub PreResult {
 
   $result->{paging} = $paging;
 
+  if ($ctx->{ctrl}) {
+    # The Context shares the caller's paging hash by reference, so refill it
+    # in place; a fresh hash on ctrl never reaches the caller.
+    if (Voxgig::Struct::ismap($ctx->{ctrl}{paging})) {
+      %{ $ctx->{ctrl}{paging} } = %$paging;
+    }
+    else {
+      $ctx->{ctrl}{paging} = $paging;
+    }
+  }
+
   $self->{client}{_paging} = { 'last' => $paging };
   return;
 }

package/project/.sdk/tm/perl/feature/test_feature.pm

@@ -154,18 +154,11 @@ sub init {
       my $args = $test_self->build_args($fctx, $op, $update_match);
       my $found = Voxgig::Struct::select($entmap, $args);
       my $ent = ProjectNameHelpers::ge($found, 0);
-      if (!defined $ent && Voxgig::Struct::ismap($entmap) && keys %$entmap) {
-        for my $k (sort keys %$entmap) {
-          if (Voxgig::Struct::ismap($entmap->{$k})) {
-            $ent = $entmap->{$k};
-            last;
-          }
-        }
-      }
+      # update miss: 404, never another record
       return $respond->($fctx, 404, undef, { 'statusText' => 'Not found' })
         unless ProjectNameHelpers::rb_truthy($ent);
-      if (Voxgig::Struct::ismap($ent) && $fctx->{reqdata}) {
-        $ent->{$_} = $fctx->{reqdata}{$_} for keys %{ $fctx->{reqdata} };
+      if (Voxgig::Struct::ismap($ent) && Voxgig::Struct::ismap($fctx->{reqdata})) {
+        Voxgig::Struct::merge([$ent, $fctx->{reqdata}]);
       }
       Voxgig::Struct::delprop($ent, '$KEY');
       my $out = Voxgig::Struct::clone($ent);
@@ -290,18 +283,55 @@ sub make_netsim {
   };
 }
 
+sub _point_terminal {
+  my ($p) = @_;
+  my $parts = ProjectNameHelpers::gp($p, 'parts');
+  return 0 unless Voxgig::Struct::islist($parts) && @$parts;
+  my $last = $parts->[-1];
+  return (defined $last && !ref $last && 0 == index($last, '{')) ? 1 : 0;
+}
+
+sub _point_depth {
+  my ($p) = @_;
+  my $parts = ProjectNameHelpers::gp($p, 'parts');
+  return Voxgig::Struct::islist($parts) ? scalar @$parts : 0;
+}
+
+# The entity's own endpoint: a terminal `{param}` marks a record route, and
+# among equals the shallower path wins (the same rule as make_point).
+sub _pick_point {
+  my ($points) = @_;
+  return undef unless Voxgig::Struct::islist($points) && @$points;
+  my $point = $points->[0];
+  for my $cand (@$points[1 .. $#$points]) {
+    if (_point_terminal($cand) != _point_terminal($point)) {
+      $point = $cand if _point_terminal($cand);
+    }
+    elsif (_point_depth($cand) < _point_depth($point)) {
+      $point = $cand;
+    }
+  }
+  return $point;
+}
+
 sub build_args {
   my ($self, $ctx, $op, $args) = @_;
   my $opname = $op->{name};
   my $entname = $ctx->{entity}->get_name;
   my $points = ProjectNameHelpers::gpath($ctx->{config},
     "entity.$entname.op.$opname.points");
-  my $point = ProjectNameHelpers::ge($points, -1);
-
-  my $params_path = ProjectNameHelpers::gpath($point, 'args.params');
-  my $reqd_params = Voxgig::Struct::select($params_path,
-    { 'reqd' => Voxgig::Struct::JTRUE() });
-  my $reqd = Voxgig::Struct::transform($reqd_params, ['`$EACH`', '', '`$KEY.name`']);
+  my $point = _pick_point($points);
+
+  # Path AND query: a path-only read misses a query-addressed record
+  # (e.g. GET /result?trace_id=), which has no path param at all.
+  my $reqd = [];
+  for my $kind ('params', 'query') {
+    my $args_path = ProjectNameHelpers::gpath($point, "args.$kind");
+    my $reqd_args = Voxgig::Struct::select($args_path,
+      { 'reqd' => Voxgig::Struct::JTRUE() });
+    my $names = Voxgig::Struct::transform($reqd_args, ['`$EACH`', '', '`$KEY.name`']);
+    push @$reqd, @$names if Voxgig::Struct::islist($names);
+  }
 
   my $qand = [];
   my $q = { '`$AND`' => $qand };

package/project/.sdk/tm/perl/feature/timeout_feature.pm

@@ -3,9 +3,11 @@
 # Per-request timeout. Wraps the active transport with a deadline of "ms"
 # milliseconds (default 30000; <= 0 disables). The transport is synchronous
 # (HTTP::Tiny), so a hanging request is interrupted with a SIGALRM timer
-# (Time::HiRes::ualarm); when an injectable "now" clock is supplied the
-# elapsed wall-clock time is checked instead, so tests can assert the
-# deadline deterministically. Expiry yields an error with code "timeout".
+# (Time::HiRes::ualarm) where the platform has one; where it has none
+# (Windows) the deadline is checked once the call returns. When an
+# injectable "now" clock is supplied the elapsed clock time is checked
+# instead, so tests can assert the deadline deterministically. Expiry
+# yields an error with code "timeout".
 
 use strict;
 use warnings;
@@ -75,24 +77,26 @@ sub with_timeout {
   # Live path: interrupt a hanging synchronous transport.
   my ($res, $err);
   my $timed_out = 0;
-  my $ok = do {
-    local $SIG{ALRM} = sub { $timed_out = 1; die "ProjectNameTimeout\n" };
-    eval {
-      Time::HiRes::ualarm(int($ms * 1000));
-      ($res, $err) = $inner->($ctx, $url, $fetchdef);
-      Time::HiRes::ualarm(0);
-      1;
-    };
+  my $start = Time::HiRes::time();
+  local $SIG{ALRM} = sub { $timed_out = 1; die "ProjectNameTimeout\n" };
+  my $armed = eval { Time::HiRes::ualarm(int($ms * 1000)); 1 };
+  my $ok = eval {
+    ($res, $err) = $inner->($ctx, $url, $fetchdef);
+    1;
   };
-  Time::HiRes::ualarm(0);
+  my $e = $@;
+  eval { Time::HiRes::ualarm(0) } if $armed;
   if (!$ok) {
-    my $e = $@;
     if ($timed_out) {
       $self->_track($ctx, $ms);
       return (undef, $ctx->make_error('timeout', "Request exceeded timeout of ${ms}ms"));
     }
     die $e;
   }
+  if (!$armed && (Time::HiRes::time() - $start) * 1000 > $ms) {
+    $self->_track($ctx, $ms);
+    return (undef, $ctx->make_error('timeout', "Request exceeded timeout of ${ms}ms"));
+  }
   return ($res, $err);
 }
 

package/project/.sdk/tm/perl/t/feature_corpus.t

@@ -267,6 +267,15 @@ sub subset {
 }
 
 
+# Whether the SDK built the feature at all. The activity record is the
+# wrong probe: most features create theirs on first use, so an idle client
+# has none and every section but the eager ones read as inert.
+sub present {
+  my ($client, $name) = @_;
+  return scalar grep { ref $_ && ($_->{name} // '') eq $name }
+    @{ $client->{features} || [] };
+}
+
 sub record {
   my ($client, $name) = @_;
   return $client->{"_$name"};
@@ -295,7 +304,11 @@ for my $name (sort keys %{ $CORPUS->{feature} || {} }) {
   # Probed by ACTIVATING it: the feature defaults to inactive, so an idle
   # client never builds it and its absence says nothing.
   my $probe = build_client({ feature => [ { name => $name, active => 1 } ] });
-  next unless defined record($probe, $name);
+  unless (present($probe, $name)) {
+    # The one line every runner prints for an inert section.
+    diag("feature.$name: inert (this SDK does not generate the feature)");
+    next;
+  }
 
   my %by_key = map { $_->{key} => $_ } @ops;
 

package/project/.sdk/tm/perl/utility/fetcher.pm

@@ -16,6 +16,16 @@ package ProjectNameUtilities;
 
 our %REGISTRY;
 
+# One HTTP::Tiny per (proxy, redirect) setting: a client keeps its
+# connection alive between requests, so one per request reused nothing.
+my %HTTP_CLIENTS;
+
+sub _http_client {
+  my (%new_args) = @_;
+  my $key = join "\n", map { "$_=$new_args{$_}" } sort keys %new_args;
+  return $HTTP_CLIENTS{$key} //= HTTP::Tiny->new(%new_args);
+}
+
 our $DefaultHttpFetch = sub {
   my ($fullurl, $fetchdef) = @_;
   $fetchdef = {} unless defined $fetchdef;
@@ -47,8 +57,12 @@ our $DefaultHttpFetch = sub {
   $new_args{max_redirect} = 0
     if defined $fetchdef->{redirect} && !ref $fetchdef->{redirect}
       && 'manual' eq $fetchdef->{redirect};
+  # Both keys: HTTP::Tiny lets the environment override its generic proxy.
+  $new_args{http_proxy} = $new_args{https_proxy} = "$fetchdef->{proxy}"
+    if defined $fetchdef->{proxy} && !ref $fetchdef->{proxy}
+      && length $fetchdef->{proxy};
 
-  my $res = eval { HTTP::Tiny->new(%new_args)->request($method, $fullurl, $opts) };
+  my $res = eval { _http_client(%new_args)->request($method, $fullurl, $opts) };
   if (!$res) {
     my $e = defined $@ ? "$@" : 'request failed';
     $e =~ s/\s+\z//;

package/project/.sdk/tm/perl/utility/prepare_query.pm

@@ -30,6 +30,7 @@ $REGISTRY{prepare_query} = sub {
     for my $item (@$items) {
       my ($key, $val) = @$item;
       next unless ProjectNameHelpers::rb_truthy($val) && defined $key && !ref $key;
+      next if '$action' eq $key;
       next if grep { defined $_ && !ref $_ && $_ eq $key } @$params;
       $out->{$key} = $val;
     }

package/project/.sdk/tm/perl/utility/transform_request.pm

@@ -15,16 +15,26 @@ package ProjectNameUtilities;
 
 our %REGISTRY;
 
+# `$action` selects the point (see make_point); it is never an API field, so
+# the body is a copy without it. The caller's hash is left untouched.
+my $strip_action = sub {
+  my ($reqdata) = @_;
+  return $reqdata unless 'HASH' eq ref $reqdata && exists $reqdata->{'$action'};
+  my %body = %$reqdata;
+  delete $body{'$action'};
+  return \%body;
+};
+
 $REGISTRY{transform_request} = sub {
   my ($ctx) = @_;
   my $spec = $ctx->{spec};
   my $point = $ctx->{point};
   $spec->{step} = 'reqform' if $spec;
   my $transform = ProjectNameHelpers::to_map(ProjectNameHelpers::gp($point, 'transform'));
-  return $ctx->{reqdata} unless $transform;
+  return $strip_action->($ctx->{reqdata}) unless $transform;
   my $reqform = ProjectNameHelpers::gp($transform, 'req');
-  return $ctx->{reqdata} unless ProjectNameHelpers::rb_truthy($reqform);
-  return Voxgig::Struct::transform({ 'reqdata' => $ctx->{reqdata} }, $reqform);
+  return $strip_action->($ctx->{reqdata}) unless ProjectNameHelpers::rb_truthy($reqform);
+  return $strip_action->(Voxgig::Struct::transform({ 'reqdata' => $ctx->{reqdata} }, $reqform));
 };
 
 1;

package/project/.sdk/tm/php/core/Context.php

@@ -55,7 +55,11 @@ class ProjectNameContext
             if (array_key_exists('actor', $ctrl_raw)) {
                 $this->ctrl->actor = $ctrl_raw['actor'];
             }
-        } elseif ($basectx !== null && $basectx->ctrl !== null) {
+            if (isset($ctrl_raw['paging']) && is_array($ctrl_raw['paging'])) {
+                $this->ctrl->paging = $ctrl_raw['paging'];
+            }
+        } elseif ($basectx !== null && $basectx->ctrl !== null
+            && ProjectNameHelpers::get_ctx_prop($ctxmap, "opname") === null) {
             $this->ctrl = $basectx->ctrl;
         }
 

package/project/.sdk/tm/php/core/Control.php

@@ -21,11 +21,16 @@ class ProjectNameControl
     // passed. The shared feature corpus caught it.
     public mixed $actor;
 
+    // Per-call paging record: read by the paging feature before the request
+    // and written back after it. Declared for the same reason as `$actor`.
+    public mixed $paging;
+
     public function __construct(array $opts = [])
     {
         $this->throw_err = $opts['throw_err'] ?? null;
         $this->err = null;
         $this->explain = $opts['explain'] ?? null;
         $this->actor = $opts['actor'] ?? null;
+        $this->paging = $opts['paging'] ?? null;
     }
 }

package/project/.sdk/tm/php/feature/PagingFeature.php

@@ -9,8 +9,8 @@ require_once __DIR__ . '/BaseFeature.php';
 // stamps page/limit (or a cursor) into the request query; on the way back
 // (PreResult) it reads the server's pagination signals — a `Link:
 // rel="next"` header, `X-Page`/`X-Next-Page`/`X-Total-Count` headers, or
-// `next`/`cursor`/`nextCursor`/`hasMore` fields in the body — and records
-// them on `$ctx->result->paging`. A per-call `ctrl->paging` (page or
+// `next`/`cursor`/`nextCursor`/`hasMore` fields in the body (snake_case
+// forms too) — and records them on `$ctx->result->paging` and `ctrl->paging`. A per-call `ctrl->paging` (page or
 // cursor) takes priority over the stamped defaults; parameter names and
 // page size are configurable; `startPage` defaults to 1. Mirrors
 // ts/src/feature/paging/PagingFeature.ts.
@@ -71,8 +71,10 @@ class ProjectNamePagingFeature extends ProjectNameBaseFeature
         } elseif (($spec->query[$page_param] ?? null) === null) {
             $start_page = is_numeric($this->options['startPage'] ?? null)
                 ? $this->options['startPage'] : 1;
-            $spec->query[$page_param] = ($paging['page'] ?? null) !== null
-                ? $paging['page'] : $start_page;
+            // A record written back by PreResult holds the page just fetched
+            // as "page" and the one to fetch as "nextPage", so nextPage wins.
+            $page = $paging['nextPage'] ?? $paging['page'] ?? null;
+            $spec->query[$page_param] = $page !== null ? $page : $start_page;
         }
 
         if (($this->options['limit'] ?? null) !== null
@@ -194,17 +196,30 @@ class ProjectNamePagingFeature extends ProjectNameBaseFeature
             }
         }
 
-        // Body-level cursors.
+        // Body-level signals; snake_case forms are read first so camelCase wins.
         if (is_array($body)) {
             if (($body['next'] ?? null) !== null) {
                 $paging['next'] = $paging['next'] ?? $body['next'];
             }
+            if (($body['next_cursor'] ?? null) !== null) {
+                $paging['cursor'] = $body['next_cursor'];
+            }
             if (($body['cursor'] ?? null) !== null) {
                 $paging['cursor'] = $body['cursor'];
             }
             if (($body['nextCursor'] ?? null) !== null) {
                 $paging['cursor'] = $body['nextCursor'];
             }
+            if ($paging['nextPage'] === null) {
+                $np = $body['nextPage'] ?? $body['next_page'] ?? null;
+                if (is_int($np) || is_float($np) || is_string($np)) {
+                    $paging['nextPage'] = $np;
+                }
+            }
+            if (is_bool($body['has_more'] ?? null)) {
+                $paging['hasMore'] = $body['has_more'];
+                $explicit_more = true;
+            }
             if (is_bool($body['hasMore'] ?? null)) {
                 $paging['hasMore'] = $body['hasMore'];
                 $explicit_more = true;
@@ -225,6 +240,12 @@ class ProjectNamePagingFeature extends ProjectNameBaseFeature
 
         $result->paging = $paging;
 
+        // PHP arrays are values, so the record lands on this call's Control
+        // rather than on an array the caller passed.
+        if ($ctx->ctrl !== null) {
+            $ctx->ctrl->paging = $paging;
+        }
+
         $this->client->_paging = ['last' => $paging];
     }