@voxgig/sdkgen 1.3.8 → 1.3.9

package/project/.sdk/tm/ocaml/utility/vregex.ml

@@ -0,0 +1,254 @@
+(* Minimal backtracking regex engine for the OCaml port of voxgig/struct.
+ * Supports the RE2 subset the corpus exercises: literals, '.', anchors ^ $,
+ * \b, character classes [..] / [^..] with ranges and \d \w \s \D \W \S,
+ * groups (..) and (?:..), alternation |, quantifiers * + ? and {n}/{n,}/{n,m}
+ * with optional lazy '?'. No third-party dependency. The struct library uses
+ * `test` for $LIKE; `find` backs the public re_* API (not corpus-tested). *)
+
+type node =
+  | Char of char
+  | Any
+  | Start
+  | End
+  | WordB
+  | Cls of bool * citem list           (* negated?, items *)
+  | Grp of node list list              (* alternation of sequences *)
+  | Star of bool * node                (* greedy?, atom *)
+  | Plus of bool * node
+  | Opt of bool * node
+  | Rep of bool * int * int option * node
+
+and citem =
+  | CChar of char
+  | CRange of char * char
+  | CD | CW | CS | CND | CNW | CNS     (* \d \w \s \D \W \S *)
+
+(* ----- parser ----- *)
+
+let parse (pat : string) : node list list =
+  let n = String.length pat in
+  let pos = ref 0 in
+  let peek () = if !pos < n then Some pat.[!pos] else None in
+  let adv () = incr pos in
+  let parse_class () =
+    (* assumes current char is '[' *)
+    adv ();
+    let neg = (peek () = Some '^') in
+    if neg then adv ();
+    let items = ref [] in
+    let finished = ref false in
+    while not !finished do
+      match peek () with
+      | None -> finished := true
+      | Some ']' -> adv (); finished := true
+      | Some '\\' ->
+        adv ();
+        (match peek () with
+         | Some 'd' -> items := CD :: !items; adv ()
+         | Some 'w' -> items := CW :: !items; adv ()
+         | Some 's' -> items := CS :: !items; adv ()
+         | Some 'D' -> items := CND :: !items; adv ()
+         | Some 'W' -> items := CNW :: !items; adv ()
+         | Some 'S' -> items := CNS :: !items; adv ()
+         | Some 'n' -> items := CChar '\n' :: !items; adv ()
+         | Some 't' -> items := CChar '\t' :: !items; adv ()
+         | Some 'r' -> items := CChar '\r' :: !items; adv ()
+         | Some c -> items := CChar c :: !items; adv ()
+         | None -> ())
+      | Some c ->
+        adv ();
+        (* range? *)
+        (match peek () with
+         | Some '-' when (!pos + 1 < n && pat.[!pos + 1] <> ']') ->
+           adv ();
+           (match peek () with
+            | Some c2 -> adv (); items := CRange (c, c2) :: !items
+            | None -> items := CChar c :: !items)
+         | _ -> items := CChar c :: !items)
+    done;
+    Cls (neg, List.rev !items)
+  in
+  let parse_quant_suffix atom =
+    match peek () with
+    | Some '*' -> adv ();
+      let lazy_ = (peek () = Some '?') in if lazy_ then adv ();
+      Some (Star (not lazy_, atom))
+    | Some '+' -> adv ();
+      let lazy_ = (peek () = Some '?') in if lazy_ then adv ();
+      Some (Plus (not lazy_, atom))
+    | Some '?' -> adv ();
+      let lazy_ = (peek () = Some '?') in if lazy_ then adv ();
+      Some (Opt (not lazy_, atom))
+    | Some '{' ->
+      (* {n} {n,} {n,m} *)
+      let save = !pos in
+      adv ();
+      let num () =
+        let b = Buffer.create 4 in
+        let rec go () = match peek () with
+          | Some c when c >= '0' && c <= '9' -> Buffer.add_char b c; adv (); go ()
+          | _ -> () in
+        go (); Buffer.contents b in
+      let mn = num () in
+      let mx =
+        match peek () with
+        | Some ',' -> adv (); let s = num () in if s = "" then None else Some (int_of_string s)
+        | _ -> Some (if mn = "" then 0 else int_of_string mn)
+      in
+      (match peek () with
+       | Some '}' when mn <> "" ->
+         adv ();
+         let lazy_ = (peek () = Some '?') in if lazy_ then adv ();
+         Some (Rep (not lazy_, int_of_string mn, mx, atom))
+       | _ -> pos := save; None)  (* not a valid quantifier; treat '{' literally *)
+    | _ -> None
+  in
+  let rec parse_alt () : node list list =
+    let first = parse_seq () in
+    let alts = ref [first] in
+    while peek () = Some '|' do
+      adv ();
+      alts := parse_seq () :: !alts
+    done;
+    List.rev !alts
+  and parse_seq () : node list =
+    let out = ref [] in
+    let stop = ref false in
+    while not !stop do
+      match peek () with
+      | None | Some '|' | Some ')' -> stop := true
+      | _ ->
+        let atom = parse_atom () in
+        (match atom with
+         | None -> stop := true
+         | Some a ->
+           let a = (match parse_quant_suffix a with Some q -> q | None -> a) in
+           out := a :: !out)
+    done;
+    List.rev !out
+  and parse_atom () : node option =
+    match peek () with
+    | None -> None
+    | Some '(' ->
+      adv ();
+      (* non-capturing? *)
+      (if peek () = Some '?' && !pos + 1 < n && pat.[!pos + 1] = ':' then (adv (); adv ()));
+      let alts = parse_alt () in
+      (if peek () = Some ')' then adv ());
+      Some (Grp alts)
+    | Some '[' -> Some (parse_class ())
+    | Some '.' -> adv (); Some Any
+    | Some '^' -> adv (); Some Start
+    | Some '$' -> adv (); Some End
+    | Some '\\' ->
+      adv ();
+      (match peek () with
+       | Some 'd' -> adv (); Some (Cls (false, [CD]))
+       | Some 'w' -> adv (); Some (Cls (false, [CW]))
+       | Some 's' -> adv (); Some (Cls (false, [CS]))
+       | Some 'D' -> adv (); Some (Cls (false, [CND]))
+       | Some 'W' -> adv (); Some (Cls (false, [CNW]))
+       | Some 'S' -> adv (); Some (Cls (false, [CNS]))
+       | Some 'b' -> adv (); Some WordB
+       | Some 'n' -> adv (); Some (Char '\n')
+       | Some 't' -> adv (); Some (Char '\t')
+       | Some 'r' -> adv (); Some (Char '\r')
+       | Some c -> adv (); Some (Char c)
+       | None -> Some (Char '\\'))
+    | Some c -> adv (); Some (Char c)
+  in
+  parse_alt ()
+
+(* ----- matcher (backtracking, CPS) ----- *)
+
+let is_word c =
+  (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c = '_'
+
+let citem_match it c =
+  match it with
+  | CChar x -> c = x
+  | CRange (a, b) -> c >= a && c <= b
+  | CD -> c >= '0' && c <= '9'
+  | CND -> not (c >= '0' && c <= '9')
+  | CW -> is_word c
+  | CNW -> not (is_word c)
+  | CS -> c = ' ' || c = '\t' || c = '\n' || c = '\r' || c = '\012' || c = '\011'
+  | CNS -> not (c = ' ' || c = '\t' || c = '\n' || c = '\r' || c = '\012' || c = '\011')
+
+let rec m_node input len node pos (k : int -> bool) : bool =
+  match node with
+  | Char c -> pos < len && input.[pos] = c && k (pos + 1)
+  | Any -> pos < len && input.[pos] <> '\n' && k (pos + 1)
+  | Start -> pos = 0 && k pos
+  | End -> pos = len && k pos
+  | WordB ->
+    let before = pos > 0 && is_word input.[pos - 1] in
+    let after = pos < len && is_word input.[pos] in
+    (before <> after) && k pos
+  | Cls (neg, items) ->
+    pos < len &&
+    (let c = input.[pos] in
+     let hit = List.exists (fun it -> citem_match it c) items in
+     (if neg then not hit else hit) && k (pos + 1))
+  | Grp alts -> List.exists (fun seq -> m_seq input len seq pos k) alts
+  | Opt (greedy, a) ->
+    if greedy then m_node input len a pos k || k pos
+    else k pos || m_node input len a pos k
+  | Star (greedy, a) -> m_star input len greedy a pos k
+  | Plus (greedy, a) ->
+    m_node input len a pos (fun p -> m_star input len greedy a p k)
+  | Rep (greedy, mn, mx, a) -> m_rep input len greedy mn mx a pos k
+
+and m_star input len greedy a pos k =
+  if greedy then
+    m_node input len a pos (fun p -> p > pos && m_star input len greedy a p k) || k pos
+  else
+    k pos || m_node input len a pos (fun p -> p > pos && m_star input len greedy a p k)
+
+and m_rep input len greedy mn mx a pos k =
+  if mn > 0 then
+    m_node input len a pos (fun p ->
+        m_rep input len greedy (mn - 1)
+          (match mx with Some m -> Some (m - 1) | None -> None) a p k)
+  else
+    match mx with
+    | Some 0 -> k pos
+    | _ ->
+      let next p = p > pos && m_rep input len greedy 0
+                     (match mx with Some m -> Some (m - 1) | None -> None) a p k in
+      if greedy then m_node input len a pos next || k pos
+      else k pos || m_node input len a pos next
+
+and m_seq input len seq pos k =
+  match seq with
+  | [] -> k pos
+  | x :: rest -> m_node input len x pos (fun p -> m_seq input len rest p k)
+
+(* Compiled = the alternation AST. *)
+type t = node list list
+
+let compile (pat : string) : t = parse pat
+
+(* Does the pattern match anywhere in input? *)
+let test (re : t) (input : string) : bool =
+  let len = String.length input in
+  let rec try_at i =
+    if List.exists (fun seq -> m_seq input len seq i (fun _ -> true)) re then true
+    else if i >= len then false
+    else try_at (i + 1)
+  in
+  try_at 0
+
+let test_str (pat : string) (input : string) : bool = test (compile pat) input
+
+(* Leftmost match: returns (start, stop) or None. Used by the public re_* API. *)
+let find_bounds (re : t) (input : string) : (int * int) option =
+  let len = String.length input in
+  let rec try_at i =
+    if i > len then None
+    else
+      let best = ref (-1) in
+      let ok = List.exists (fun seq -> m_seq input len seq i (fun p -> best := p; true)) re in
+      if ok then Some (i, !best) else try_at (i + 1)
+  in
+  try_at 0

package/project/.sdk/tm/perl/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) $$const.year$$ Voxgig
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/project/.sdk/tm/perl/Makefile

@@ -0,0 +1,57 @@
+.PHONY: test build clean publish
+
+PERL ?= perl
+
+# Run the WHOLE suite (entity, direct, utility, pipeline, feature and
+# netsim tests) with prove (TAP). -Ilib puts the generated SDK module on
+# @INC; helper .pm files in t/ are loaded by path.
+test:
+	prove -Ilib t/
+
+# No build step - pure-Perl module.
+build:
+	@echo "No build step for Perl"
+
+clean:
+	@rm -rf .release
+	@find . -name '*.bak' -delete
+
+# --- Release: git tag (CPAN registry pending) ------------------------------
+# Build a CPAN dist in a throwaway .release/ dir to validate the package,
+# then tag perl/vX.Y.Z (version from $VERSION in lib/*SDK.pm). The CPAN
+# registry entry for this port is declared but pending, so publish is
+# tag-only: no upload happens. Run headless under the aql key vault, which
+# injects the GitHub token (never on disk or argv):
+#   aql vault exec --for=github=<alias> -- make publish
+# aql `--dry-run` injects a filler token we detect to rehearse (build only,
+# no tag). set -e + tag-last: a failed build never leaves a tag behind.
+#
+# NOTE: `perl Makefile.PL` (ExtUtils::MakeMaker) GENERATES a file named
+# `Makefile`, which would OVERWRITE this hand-written Makefile - so the
+# dist build always happens inside .release/, never in place.
+VERSION := $(shell sed -nE "s/.*VERSION *= *'([^']+)'.*/\1/p" lib/*SDK.pm | head -1)
+TAG := perl/v$(VERSION)
+AQL_DRY_RUN_FILLER := AQL-DRY-RUN-FILLER-NOT-A-REAL-SECRET
+publish: test
+	@if git rev-parse -q --verify "refs/tags/$(TAG)" >/dev/null; then \
+	  echo "tag $(TAG) already exists — bump VERSION in lib/*SDK.pm first"; exit 1; fi
+	@set -e; \
+	token="$${GITHUB_TOKEN:-$$GH_TOKEN}"; \
+	rm -rf .release && mkdir -p .release; \
+	cp -r lib core utility feature entity t Makefile.PL config.pm features.pm .release/ 2>/dev/null || true; \
+	{ [ -f README.md ] && cp README.md .release/ || true; }; \
+	(cd .release && $(PERL) Makefile.PL >/dev/null && echo "dist metadata OK"); \
+	rm -rf .release; \
+	if [ "$$token" = "$(AQL_DRY_RUN_FILLER)" ]; then \
+	  echo "[dry-run] aql filler token detected: would tag $(TAG); nothing pushed."; \
+	  exit 0; \
+	fi; \
+	git tag -a "$(TAG)" -m "perl v$(VERSION)"; \
+	url=$$(git remote get-url origin | sed -E 's#^git@github.com:#https://github.com/#'); \
+	if [ -n "$$token" ] && printf '%s' "$$url" | grep -q '^https://github.com/'; then \
+	  hdr="AUTHORIZATION: basic $$(printf 'x-access-token:%s' "$$token" | base64 | tr -d '\n')"; \
+	  git -c http.extraheader="$$hdr" push "$$url" "$(TAG)"; \
+	else \
+	  git push origin "$(TAG)"; \
+	fi; \
+	echo "Published tag $(TAG) (CPAN registry pending — tag-only)."

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

@@ -0,0 +1,138 @@
+# ProjectName SDK context
+
+use strict;
+use warnings;
+
+use File::Basename ();
+use Cwd ();
+use Scalar::Util ();
+
+my $__dir;
+BEGIN { $__dir = File::Basename::dirname(Cwd::abs_path(__FILE__)) }
+require(Cwd::abs_path("$__dir/../lib/Voxgig/Struct.pm"));
+require(Cwd::abs_path("$__dir/helpers.pm"));
+require(Cwd::abs_path("$__dir/control.pm"));
+require(Cwd::abs_path("$__dir/operation.pm"));
+require(Cwd::abs_path("$__dir/spec.pm"));
+require(Cwd::abs_path("$__dir/result.pm"));
+require(Cwd::abs_path("$__dir/response.pm"));
+require(Cwd::abs_path("$__dir/error.pm"));
+
+package ProjectNameContext;
+
+sub new {
+  my ($class, $ctxmap, $basectx) = @_;
+  $ctxmap = {} unless defined $ctxmap;
+
+  my $self = bless {}, $class;
+
+  $self->{id} = 'C' . (10000000 + int(rand(90000000)));
+  $self->{out} = {};
+
+  my $gcp = \&ProjectNameHelpers::get_ctx_prop;
+
+  $self->{client} = $gcp->($ctxmap, 'client');
+  $self->{client} = $basectx->{client} if !defined $self->{client} && $basectx;
+
+  $self->{utility} = $gcp->($ctxmap, 'utility');
+  $self->{utility} = $basectx->{utility} if !defined $self->{utility} && $basectx;
+
+  $self->{ctrl} = ProjectNameControl->new();
+  my $ctrl_raw = $gcp->($ctxmap, 'ctrl');
+  if (Voxgig::Struct::ismap($ctrl_raw)) {
+    $self->{ctrl}{throw_err} = $ctrl_raw->{throw} if exists $ctrl_raw->{throw};
+    $self->{ctrl}{explain} = $ctrl_raw->{explain} if Voxgig::Struct::ismap($ctrl_raw->{explain});
+    $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}) {
+    $self->{ctrl} = $basectx->{ctrl};
+  }
+
+  my $m = $gcp->($ctxmap, 'meta');
+  $self->{meta} = Voxgig::Struct::ismap($m) ? $m : (($basectx && $basectx->{meta}) || {});
+
+  my $cfg = $gcp->($ctxmap, 'config');
+  $self->{config} = Voxgig::Struct::ismap($cfg) ? $cfg : ($basectx ? $basectx->{config} : undef);
+
+  my $eo = $gcp->($ctxmap, 'entopts');
+  $self->{entopts} = Voxgig::Struct::ismap($eo) ? $eo : ($basectx ? $basectx->{entopts} : undef);
+
+  my $o = $gcp->($ctxmap, 'options');
+  $self->{options} = Voxgig::Struct::ismap($o) ? $o : ($basectx ? $basectx->{options} : undef);
+
+  my $e = $gcp->($ctxmap, 'entity');
+  $self->{entity} = defined $e ? $e : ($basectx ? $basectx->{entity} : undef);
+
+  my $s = $gcp->($ctxmap, 'shared');
+  $self->{shared} = Voxgig::Struct::ismap($s) ? $s : ($basectx ? $basectx->{shared} : undef);
+
+  my $om = $gcp->($ctxmap, 'opmap');
+  $self->{opmap} = Voxgig::Struct::ismap($om) ? $om : (($basectx && $basectx->{opmap}) || {});
+
+  $self->{data} = ProjectNameHelpers::to_map($gcp->($ctxmap, 'data')) || {};
+  $self->{reqdata} = ProjectNameHelpers::to_map($gcp->($ctxmap, 'reqdata')) || {};
+  $self->{match} = ProjectNameHelpers::to_map($gcp->($ctxmap, 'match')) || {};
+  $self->{reqmatch} = ProjectNameHelpers::to_map($gcp->($ctxmap, 'reqmatch')) || {};
+
+  my $pt = $gcp->($ctxmap, 'point');
+  $self->{point} = Voxgig::Struct::ismap($pt) ? $pt : ($basectx ? $basectx->{point} : undef);
+
+  my $sp = $gcp->($ctxmap, 'spec');
+  $self->{spec} = (Scalar::Util::blessed($sp) && $sp->isa('ProjectNameSpec'))
+    ? $sp : ($basectx ? $basectx->{spec} : undef);
+
+  my $r = $gcp->($ctxmap, 'result');
+  $self->{result} = (Scalar::Util::blessed($r) && $r->isa('ProjectNameResult'))
+    ? $r : ($basectx ? $basectx->{result} : undef);
+
+  my $rp = $gcp->($ctxmap, 'response');
+  $self->{response} = (Scalar::Util::blessed($rp) && $rp->isa('ProjectNameResponse'))
+    ? $rp : ($basectx ? $basectx->{response} : undef);
+
+  my $opname = $gcp->($ctxmap, 'opname');
+  $opname = '' unless defined $opname && !ref $opname;
+  $self->{op} = $self->resolve_op($opname);
+
+  return $self;
+}
+
+sub resolve_op {
+  my ($self, $opname) = @_;
+
+  # Cache key is `<entity>:<opname>` so two entities with the same op
+  # (e.g. both have a "list") get distinct cached Operations. Keying
+  # on opname alone caused the first-resolved entity's points to be
+  # served to every subsequent entity's call.
+  my $ent = $self->{entity};
+  my $entname = (Scalar::Util::blessed($ent) && $ent->can('get_name')) ? $ent->get_name : '_';
+  my $cache_key = "$entname:$opname";
+  return $self->{opmap}{$cache_key} if $self->{opmap}{$cache_key};
+  return ProjectNameOperation->new({}) if '' eq $opname;
+
+  my $opcfg = ProjectNameHelpers::gpath($self->{config}, "entity.$entname.op.$opname");
+
+  my $input = ($opname eq 'update' || $opname eq 'create') ? 'data' : 'match';
+
+  my $points = [];
+  if (Voxgig::Struct::ismap($opcfg)) {
+    my $t = ProjectNameHelpers::gp($opcfg, 'points');
+    $points = $t if Voxgig::Struct::islist($t);
+  }
+
+  my $op = ProjectNameOperation->new({
+    entity => $entname,
+    name   => $opname,
+    input  => $input,
+    points => $points,
+  });
+  $self->{opmap}{$cache_key} = $op;
+  return $op;
+}
+
+sub make_error {
+  my ($self, $code, $msg) = @_;
+  return ProjectNameError->new($code, $msg, $self);
+}
+
+1;

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

@@ -0,0 +1,22 @@
+# ProjectName SDK control
+
+use strict;
+use warnings;
+
+package ProjectNameControl;
+
+sub new {
+  my ($class, $opts) = @_;
+  $opts = {} unless defined $opts && ref($opts) eq 'HASH';
+  return bless {
+    throw_err => $opts->{throw_err},
+    err       => undef,
+    explain   => $opts->{explain},
+    # Per-call audit actor (used by the audit feature).
+    actor     => $opts->{actor},
+    # Per-call paging override (used by the paging feature).
+    paging    => $opts->{paging},
+  }, $class;
+}
+
+1;

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

@@ -0,0 +1,30 @@
+# ProjectName SDK error
+
+use strict;
+use warnings;
+
+package ProjectNameError;
+
+use overload
+  '""'     => sub { defined $_[0]->{msg} ? $_[0]->{msg} : '' },
+  'bool'   => sub { 1 },
+  fallback => 1;
+
+sub new {
+  my ($class, $code, $msg, $ctx) = @_;
+  return bless {
+    is_sdk_error => 1,
+    sdk          => 'ProjectName',
+    code         => (defined $code ? $code : ''),
+    msg          => (defined $msg ? $msg : ''),
+    ctx          => $ctx,
+    result       => undef,
+    spec         => undef,
+  }, $class;
+}
+
+sub code  { $_[0]->{code} }
+sub msg   { $_[0]->{msg} }
+sub error { $_[0]->{msg} }
+
+1;

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

@@ -0,0 +1,142 @@
+# ProjectName SDK helpers
+
+use strict;
+use warnings;
+
+use File::Basename ();
+use Cwd ();
+use Scalar::Util ();
+use Time::HiRes ();
+
+my $__dir;
+BEGIN { $__dir = File::Basename::dirname(Cwd::abs_path(__FILE__)) }
+require(Cwd::abs_path("$__dir/../lib/Voxgig/Struct.pm"));
+
+package ProjectNameHelpers;
+
+sub to_map {
+  my ($v) = @_;
+  return Voxgig::Struct::ismap($v) ? $v : undef;
+}
+
+sub to_int {
+  my ($v) = @_;
+  return -1 unless defined $v && !ref($v) && Scalar::Util::looks_like_number($v);
+  return int($v);
+}
+
+sub get_ctx_prop {
+  my ($m, $key) = @_;
+  return undef unless defined $m && ref($m)
+    && ((Scalar::Util::reftype($m) // '') eq 'HASH');
+  return $m->{$key};
+}
+
+# getprop that yields undef (not the NONE sentinel) when absent.
+sub gp {
+  my $v = Voxgig::Struct::getprop(@_);
+  return Voxgig::Struct::is_none($v) ? undef : $v;
+}
+
+# getpath that yields undef (not the NONE sentinel) when absent.
+sub gpath {
+  my $v = Voxgig::Struct::getpath(@_);
+  return Voxgig::Struct::is_none($v) ? undef : $v;
+}
+
+# getelem that yields undef (not the NONE sentinel) when absent.
+sub ge {
+  my $v = Voxgig::Struct::getelem(@_);
+  return Voxgig::Struct::is_none($v) ? undef : $v;
+}
+
+# Ruby/JS truthiness: only nil/null/false are falsy ('' and '0' are truthy).
+sub rb_truthy {
+  my ($v) = @_;
+  return 0 if !defined $v;
+  return 0 if Voxgig::Struct::is_none($v) || Voxgig::Struct::is_jnull($v);
+  return ($$v ? 1 : 0) if Voxgig::Struct::is_jbool($v);
+  return 1;
+}
+
+# `== true`: a JSON true, or a plain truthy Perl scalar (1, "x", ...).
+sub is_true {
+  my ($v) = @_;
+  return 0 if !defined $v;
+  return ($$v ? 1 : 0) if Voxgig::Struct::is_jbool($v);
+  return 0 if ref $v;
+  return $v ? 1 : 0;
+}
+
+# `== false`: a JSON false, or a defined plain falsy Perl scalar (0, '').
+sub is_false {
+  my ($v) = @_;
+  return 0 if !defined $v;
+  return ($$v ? 0 : 1) if Voxgig::Struct::is_jbool($v);
+  return 0 if ref $v;
+  return $v ? 0 : 1;
+}
+
+# Loose scalar equality treating undef/null/NONE as "no value".
+sub eqv {
+  my ($x, $y) = @_;
+  my $dx = defined $x && !Voxgig::Struct::is_none($x) && !Voxgig::Struct::is_jnull($x);
+  my $dy = defined $y && !Voxgig::Struct::is_none($y) && !Voxgig::Struct::is_jnull($y);
+  return 1 if !$dx && !$dy;
+  return 0 if !$dx || !$dy;
+  return ("$x" eq "$y") ? 1 : 0;
+}
+
+sub now_ms {
+  return int(Time::HiRes::time() * 1000);
+}
+
+sub sleep_ms {
+  my ($ms) = @_;
+  Time::HiRes::sleep($ms / 1000.0) if defined $ms && $ms > 0;
+}
+
+# Perl cannot distinguish plain 1/0 from JSON booleans; normalize the known
+# boolean option slots ("active") so option validation sees real booleans.
+sub coerce_bools {
+  my ($v) = @_;
+  if (Voxgig::Struct::ismap($v)) {
+    for my $k (keys %$v) {
+      if ('active' eq $k) {
+        my $b = $v->{$k};
+        if (defined $b && !ref $b) {
+          $v->{$k} = Voxgig::Struct::jbool($b ? 1 : 0);
+        }
+      }
+      else {
+        coerce_bools($v->{$k});
+      }
+    }
+  }
+  elsif (Voxgig::Struct::islist($v)) {
+    coerce_bools($_) for @$v;
+  }
+  return $v;
+}
+
+# The vendored struct utility, exposed as a map of named functions so
+# callers can reach it via the SDK utility object: utility->{struct}{clone}.
+my $STRUCT_FACADE;
+
+sub struct_facade {
+  return $STRUCT_FACADE if $STRUCT_FACADE;
+  my %f;
+  for my $name (qw(
+    clone delprop escre escurl filter flatten getdef getelem getpath getprop
+    haskey inject isempty isfunc iskey islist ismap isnode items join jsonify
+    keysof merge pad parse_json pathify select setpath setprop size slice
+    strkey stringify transform typify typename validate walk jm jt
+  )) {
+    my $ref = Voxgig::Struct->can($name);
+    $f{$name} = $ref if $ref;
+  }
+  $STRUCT_FACADE = \%f;
+  return $STRUCT_FACADE;
+}
+
+1;