@voxgig/sdkgen-langpack 0.0.1

package/.sdk/src/cmp/lean/Test_lean.ts

@@ -0,0 +1,261 @@
+import {
+  Content,
+  File,
+  Folder,
+  cmp,
+  each,
+  entityCollection,
+} from '@voxgig/sdkgen'
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+// True when an op has at least one endpoint point that needs no path params
+// (a top-level operation the live smoke test can call without an id).
+function hasParamFreePoint(op: any): boolean {
+  if (null == op) return false
+  const points = op.points || []
+  for (const pt of points) {
+    const params = ((pt.args || {}).params) || []
+    if (params.length === 0) return true
+  }
+  return false
+}
+
+
+// True when an op selects a single record by path params — i.e. loading it by
+// id is meaningful. A load whose every point is param-free is a singleton
+// endpoint (`/current`): passing it an id matches no point at all, and the
+// runtime raises `has no matching endpoint`.
+function selectsByParams(op: any): boolean {
+  if (null == op) return false
+  const points = op.points || []
+  for (const pt of points) {
+    const params = ((pt.args || {}).params) || []
+    if (0 < params.length) return true
+  }
+  return false
+}
+
+
+// Synthesize a create payload from the entity's required non-id fields.
+function synthData(fields: any): any {
+  const o: any = {}
+  each(fields, (f: any) => {
+    if (f.req && f.name !== 'id') {
+      const t = String(f.type || '').toLowerCase()
+      o[f.name] =
+        (t.includes('number') || t.includes('integer') || t.includes('decimal')) ? 42
+          : t.includes('bool') ? true
+            : 'leantest'
+    }
+  })
+  return o
+}
+
+
+// The generated `test/Runner.lean` exe runs TWO lanes:
+//
+//  - OFFLINE (always): a test-mode client seeded from the entity's generated
+//    `<Entity>TestData.json` answers operations from an in-memory store, so
+//    entity behaviour (list/load/create/load-back/remove) is verified with no
+//    server — the same guarantee the `test` feature gives the other targets.
+//  - LIVE (only when SDK_TEST_BASE is set): the same flow against a real
+//    server, exercising the curl transport end to end.
+const Test = cmp(async function Test(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+  const model: Model = ctx$.model
+
+  const entity = each(entityCollection(model))
+    .filter((e: any) => false !== e.active)
+
+  // Per-entity OFFLINE (test-mode) blocks: seeded store, no server.
+  let offline = ''
+  each(entity, (e: any) => {
+    const ns = e.name.charAt(0).toUpperCase() + e.name.slice(1)
+    const Name = e.Name || (e.name.charAt(0).toUpperCase() + e.name.slice(1))
+    const ops = e.op || {}
+    if (!ops.list && !ops.load) return
+
+    // Only call the ops the entity actually declares. `Entity.create` is not
+    // generated for a load-only entity, so emitting the create/remove block
+    // unconditionally fails the build with "Unknown identifier X.create".
+    // Value's constructors are spelled out (`Value.list`, not `.list`) — the
+    // expected type is not known at the match scrutinee, and Lean reports the
+    // dotted form as ambiguous against Std's own `.list`.
+    let body = ''
+
+    if (ops.list) {
+      body += `        -- list returns every seeded entity
+        let items ← ${ns}.list tclient (← emptyMap) (← emptyMap)
+        let n ← (match items with | Value.list lid => do pure (← listItems lid).size | _ => pure 0)
+        if n == ids.size then pass s!"${e.name}.list offline -> {n} seeded"
+        else fail s!"${e.name}.list offline: got {n}, want {ids.size}"
+`
+    }
+
+    if (ops.load && selectsByParams(ops.load)) {
+      body += `        -- load the first seeded entity by id
+        if ids.size > 0 then do
+          let wid := ids[0]!
+          let m ← newMap #[("id", Value.str wid)]
+          let got ← ${ns}.load tclient m (← emptyMap)
+          let gid ← SdkRuntime.gpS got "id"
+          if gid == wid then pass s!"${e.name}.load offline (id={wid})"
+          else fail s!"${e.name}.load offline: got {gid}, want {wid}"
+`
+    }
+    // A singleton load (`/current`, `/slack`) is deliberately NOT asserted
+    // here. The offline lane answers from a store keyed by entity id, so a
+    // load carrying no id has nothing to look up — the only honest assertion
+    // would need the model-driven match data the other targets build in their
+    // TestEntity components. Until this lane is model-driven too, such an
+    // entity contributes no offline block rather than a misleading one.
+
+    if (ops.create && ops.load && ops.remove) {
+      body += `        -- create -> load back -> remove, all in the store
+        let newmap ← SdkRuntime.gp (← SdkRuntime.gp seed "new") "${e.name}"
+        let nks ← keysof newmap
+        if nks.size > 0 then do
+          let payload ← SdkRuntime.gp newmap nks[0]!
+          let created ← ${ns}.create tclient payload (← emptyMap)
+          let cid ← SdkRuntime.gpS created "id"
+          if cid == "" then fail "${e.name}.create offline returned no id" else do
+            let m2 ← newMap #[("id", Value.str cid)]
+            let back ← ${ns}.load tclient m2 (← emptyMap)
+            if (← SdkRuntime.gpS back "id") == cid then
+              pass s!"${e.name}.create/load offline (id={cid})"
+            else fail s!"${e.name}.create/load offline mismatch"
+            let _ ← ${ns}.remove tclient m2 (← emptyMap)
+            let gone ← ${ns}.load tclient m2 (← emptyMap)
+            match gone with
+            | Value.map _ => fail s!"${e.name}.remove offline: still present"
+            | _ => pass s!"${e.name}.remove offline (id={cid})"
+`
+    }
+
+    // Nothing to assert (an entity whose only op needs path params we cannot
+    // synthesise) — skip the block rather than emit an empty `do`.
+    if ('' === body) return
+
+    offline += `    -- ${e.name}: offline (test-mode) entity behaviour
+    (do
+      let seedPath := "../.sdk/test/entity/${e.name}/${Name}TestData.json"
+      if !(← System.FilePath.pathExists seedPath) then
+        IO.println s!"skip - ${e.name}: no seed at {seedPath}"
+      else do
+        let seed ← SdkJson.jsonRead (← IO.FS.readFile seedPath)
+        let tclient ← Sdk.testSdk0 seed
+        let existing ← SdkRuntime.gp (← SdkRuntime.gp seed "existing") "${e.name}"
+        let ids ← keysof existing
+${body})
+`
+  })
+
+  // Per-entity LIVE test blocks.
+  let blocks = ''
+  each(entity, (e: any) => {
+    const ns = e.name.charAt(0).toUpperCase() + e.name.slice(1)
+    const listOp = (e.op || {}).list
+    const createOp = (e.op || {}).create
+    const removeOp = (e.op || {}).remove
+
+    if (hasParamFreePoint(listOp)) {
+      blocks += `    -- ${e.name}: list smoke
+    (do
+      let items ← ${ns}.list client (← emptyMap) (← emptyMap)
+      match items with
+      | Value.list lid => pass s!"${e.name}.list -> {(← listItems lid).size} items"
+      | _ => fail "${e.name}.list did not return a list")
+`
+    }
+
+    // Round-trip when create is param-free (creatable without an id); load and
+    // remove then use the id returned by create.
+    const loadOp = (e.op || {}).load
+    if (hasParamFreePoint(createOp) && loadOp && removeOp) {
+      const data = JSON.stringify(synthData(e.fields))
+      blocks += `    -- ${e.name}: create / load / remove round-trip
+    (do
+      let d ← SdkJson.jsonRead ${JSON.stringify(data)}
+      let created ← ${ns}.create client d (← emptyMap)
+      let nid ← SdkRuntime.gpS created "id"
+      if nid == "" then fail "${e.name}.create returned no id" else do
+        let m ← newMap #[("id", .str nid)]
+        let back ← ${ns}.load client m (← emptyMap)
+        let bid ← SdkRuntime.gpS back "id"
+        if bid == nid then pass s!"${e.name}.create/load round-trip (id={nid})"
+        else fail s!"${e.name}.load mismatch: {bid} != {nid}"
+        let _ ← ${ns}.remove client m (← emptyMap)
+        pass s!"${e.name}.remove (id={nid})")
+`
+    }
+  })
+
+  // The live lane nests two levels deeper than the offline lane.
+  const liveBlocks = blocks.split('\n').map((l) => l ? '  ' + l : l).join('\n')
+
+  // A `do` block whose last statement is a `let` is a type error in Lean
+  // ("the rest of the do block has monadic result type"), and an entirely
+  // empty one does not parse at all. An API whose entities offer no op these
+  // lanes can drive leaves both empty, so terminate them explicitly.
+  const offlineBody = '' === offline ? '    pure ()\n' : offline
+  const liveBody = '' === blocks ? '      pure ()\n' : liveBlocks
+
+  Folder({ name: 'test' }, () => {
+  File({ name: 'Runner.' + target.ext }, () => {
+    Content(`-- ${model.const.Name} SDK test runner (generated by @voxgig/sdkgen).
+--
+-- OFFLINE lane (always): a test-mode client seeded from the generated entity
+-- test data answers operations from an in-memory store — no server needed.
+-- LIVE lane (only when SDK_TEST_BASE is set): the same flow over real HTTP.
+
+import VoxgigStruct
+import SdkJson
+import SdkRuntime
+import SdkClient
+
+open VoxgigStruct
+
+initialize npass : IO.Ref Nat ← IO.mkRef 0
+initialize nfail : IO.Ref Nat ← IO.mkRef 0
+
+def pass (msg : String) : SIO Unit := do
+  npass.modify (· + 1)
+  IO.println s!"ok   - {msg}"
+
+def fail (msg : String) : SIO Unit := do
+  nfail.modify (· + 1)
+  IO.println s!"FAIL - {msg}"
+
+def defaultBase : String := "http://localhost:8901"
+
+def main : IO UInt32 := do
+  let liveBase ← IO.getEnv "SDK_TEST_BASE"
+  let ctx ← mkCtx
+  let offline : SIO Unit := do
+${offlineBody}  offline.run ctx
+  match liveBase with
+  | none => IO.println "skip - live lane (set SDK_TEST_BASE to enable)"
+  | some base => do
+    let live : SIO Unit := do
+      let opts ← newMap #[("base", .str base)]
+      let client ← Sdk.newSdk opts
+${liveBody}    live.run ctx
+  let p ← npass.get
+  let f ← nfail.get
+  IO.println ""
+  IO.println s!"PASS {p}  FAIL {f}"
+  if f > 0 then return 1 else return 0
+`)
+  })
+  })
+})
+
+
+export {
+  Test
+}

package/.sdk/src/cmp/lean/utility_lean.ts

@@ -0,0 +1,129 @@
+import * as Path from 'node:path'
+
+import {
+  clone,
+  walk,
+} from '@voxgig/struct'
+
+
+function projectPath(suffix?: string): string {
+  return Path.normalize(Path.join(__dirname, '../../..', suffix ?? ''))
+}
+
+
+// A Lean 4 string literal. Lean strings are UTF-8, so non-ASCII passes through;
+// only the structural characters need escaping. (Backticks are ordinary in Lean
+// strings, so the config's `body`-style transform exprs embed verbatim.)
+function leanString(s: string): string {
+  let out = '"'
+  for (const ch of String(s)) {
+    if (ch === '"') out += '\\"'
+    else if (ch === '\\') out += '\\\\'
+    else if (ch === '\n') out += '\\n'
+    else if (ch === '\t') out += '\\t'
+    else if (ch === '\r') out += '\\r'
+    else out += ch
+  }
+  return out + '"'
+}
+
+
+// Lean reserved words that cannot be bare identifiers.
+const LEAN_RESERVED = new Set<string>([
+  'do', 'let', 'fun', 'match', 'with', 'if', 'then', 'else', 'by', 'end',
+  'namespace', 'section', 'open', 'import', 'def', 'partial', 'mutual',
+  'structure', 'inductive', 'class', 'instance', 'where', 'deriving', 'return',
+  'try', 'catch', 'for', 'in', 'while', 'have', 'show', 'from', 'set_option',
+])
+
+
+// A collision-free lower-camel Lean identifier for a model name.
+function leanVarName(name: string): string {
+  let s = String(name).replace(/[^a-zA-Z0-9_]/g, '_')
+  if (s.length === 0) {
+    s = 'x'
+  }
+  s = s.charAt(0).toLowerCase() + s.slice(1)
+  if (!/^[a-z_]/.test(s)) {
+    s = 'e_' + s
+  }
+  return LEAN_RESERVED.has(s) ? s + '_' : s
+}
+
+
+// The lowercase-hyphenated package name (used for the lake package + repo).
+function pkgName(model: any): string {
+  const org = (model.origin || 'voxgig-sdk').replace(/-sdk$/, '')
+  return `${org}-${model.name}-sdk`.toLowerCase().replace(/[^a-z0-9-]/g, '-')
+}
+
+
+// Remove `$`-suffixed model annotation keys (so the embedded config is clean).
+// Emission-time normalisation of a model subtree (L0).
+//
+// Always drops jostraca's iteration metadata (`$`-suffixed keys: index$,
+// key$, val$). With `dropDefaults`, also drops keys whose value IS the
+// default the runtime already assumes when the key is absent, which is pure
+// payload — see CONFIG_DEFAULT.
+//
+// Rebuilds the tree rather than mutating during a walk. The previous
+// implementation walked a clone calling `delete p[k]`, but walk() assigns its
+// callback's result back over the child (`setprop(out, ckey, walk(...))`), so
+// the delete was undone on the way out and the helper silently did nothing.
+// Returning `undefined` from the callback does not fix it either: setprop
+// stores undefined rather than removing the key, which then emits as a null.
+//
+// `dropDefaults` is opt-in and must be passed ONLY for the entity subtree.
+// `active` means something different in feature config, where absent reads as
+// INACTIVE (see feature_init) — dropping `active: true` there would silently
+// disable the feature.
+// jostraca's iteration metadata, injected by each()/names() while it walks the
+// model. Listed explicitly rather than matched by trailing-dollar suffix: a
+// trailing dollar is not exclusive to jostraca -- Seneca uses entity$ as real
+// data -- so a blanket suffix match can silently drop a legitimate API field.
+const MODEL_META = ['index$', 'key$', 'val$']
+
+// Keys whose value IS the default the runtime already assumes when the key is
+// absent, so emitting them is pure payload.
+const CONFIG_DEFAULT: Record<string, any> = {
+  active: true,
+  req: false,
+  reqd: false,
+}
+
+// Subtrees carrying user payload rather than schema. An active:true inside an
+// OpenAPI example is DATA, not a default, so default-pruning stops at these
+// keys and everything below them is passed through untouched.
+const PAYLOAD_KEYS = ['default', 'example', 'examples']
+
+function clean(o: any, dropDefaults?: boolean): any {
+  const prune = (node: any, defaults: boolean): any => {
+    if (Array.isArray(node)) {
+      return node.map((n: any) => prune(n, defaults))
+    }
+    if (null != node && 'object' === typeof node) {
+      const out: any = {}
+      for (const k of Object.keys(node)) {
+        if (MODEL_META.includes(k)) {
+          continue
+        }
+        if (defaults && k in CONFIG_DEFAULT && CONFIG_DEFAULT[k] === node[k]) {
+          continue
+        }
+        out[k] = prune(node[k], defaults && !PAYLOAD_KEYS.includes(k))
+      }
+      return out
+    }
+    return node
+  }
+  return prune(o, true === dropDefaults)
+}
+
+
+export {
+  clean,
+  leanString,
+  leanVarName,
+  pkgName,
+  projectPath,
+}

package/.sdk/tm/dart/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/.sdk/tm/dart/Makefile

@@ -0,0 +1,50 @@
+.PHONY: test build lint clean publish
+
+# Run the full generated test suite (dependency-free plain runner).
+test:
+	dart run test/main.dart
+
+# "Lint": static analysis (a clean `dart analyze` means the code is sound).
+lint:
+	dart analyze
+
+# Build smoke-test: compile the SDK entry to a kernel snapshot.
+build:
+	dart analyze lib
+
+clean:
+	rm -rf .dart_tool *.dill
+
+# --- Release: publish to pub.dev -------------------------------------------
+# Publish this package to pub.dev, then tag dart/vX.Y.Z. pub.dev uses OAuth —
+# headless, the vault supplies the credentials JSON as PUB_CREDENTIALS and we
+# write it to the dart config path before publishing; the github token pushes
+# the tag. set -e + tag-last: a failed upload never leaves a tag behind.
+VERSION := $(shell sed -nE 's/^version: *([0-9][^ ]*).*/\1/p' pubspec.yaml | head -1)
+TAG := dart/v$(VERSION)
+BORU_DRY_RUN_FILLER := BORU-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 pubspec.yaml version first"; exit 1; fi
+	@set -e; \
+	token="$${GITHUB_TOKEN:-$$GH_TOKEN}"; \
+	if [ "$$token" = "$(BORU_DRY_RUN_FILLER)" ]; then \
+	  echo "[dry-run] boru filler token detected: would publish to pub.dev and tag $(TAG); nothing pushed."; \
+	  exit 0; \
+	fi; \
+	if [ -n "$$PUB_CREDENTIALS" ]; then \
+	  creddir="$$HOME/Library/Application Support/dart"; \
+	  [ -d "$$HOME/Library/Application Support" ] || creddir="$${XDG_CONFIG_HOME:-$$HOME/.config}/dart"; \
+	  mkdir -p "$$creddir"; \
+	  printf '%s' "$$PUB_CREDENTIALS" > "$$creddir/pub-credentials.json"; \
+	fi; \
+	dart pub publish --force; \
+	git tag -a "$(TAG)" -m "dart 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 to pub.dev + tag $(TAG)."

package/.sdk/tm/dart/lib/Context.dart

@@ -0,0 +1,150 @@
+import 'dart:math';
+
+import 'ProjectNameError.dart';
+
+import 'utility/voxgig_struct.dart' as vs;
+
+import 'Operation.dart';
+import 'Point.dart';
+import 'Response.dart';
+import 'Result.dart';
+import 'Spec.dart';
+
+class Context {
+  String id = 'C' +
+      (Random().nextInt(0x3fffffff) + 0x40000000).toString().substring(0, 8);
+
+  // Store the output of each operation step.
+  Map<String, dynamic> out = {};
+
+  // Per-operation control settings (plain map: throw, explain, actor, ...).
+  dynamic ctrl = {};
+  dynamic meta = {};
+
+  dynamic client;
+  dynamic utility;
+
+  dynamic op;
+  dynamic point;
+
+  dynamic config;
+  dynamic entopts;
+  dynamic options;
+
+  dynamic opmap;
+
+  dynamic response;
+  dynamic result;
+  dynamic spec;
+
+  dynamic data;
+  dynamic reqdata;
+  dynamic match;
+  dynamic reqmatch;
+
+  dynamic entity;
+
+  // Shared persistent store.
+  dynamic shared;
+
+  Context(dynamic ctxmap, [dynamic basectx]) {
+    client = vs.getprop(ctxmap, 'client') ?? basectx?.client;
+    utility = vs.getprop(ctxmap, 'utility') ?? basectx?.utility;
+
+    final rawctrl = vs.getprop(ctxmap, 'ctrl');
+    ctrl = null != rawctrl
+        ? (rawctrl is Map && rawctrl is! Map<String, dynamic>
+            ? Map<String, dynamic>.from(rawctrl)
+            : rawctrl)
+        : (basectx?.ctrl ?? {});
+    meta = vs.getprop(ctxmap, 'meta') ?? basectx?.meta ?? {};
+
+    config = vs.getprop(ctxmap, 'config') ?? basectx?.config;
+    entopts = vs.getprop(ctxmap, 'entopts') ?? basectx?.entopts;
+    options = vs.getprop(ctxmap, 'options') ?? basectx?.options;
+
+    entity = vs.getprop(ctxmap, 'entity') ?? basectx?.entity;
+    shared = vs.getprop(ctxmap, 'shared') ?? basectx?.shared;
+    opmap = vs.getprop(ctxmap, 'opmap') ?? basectx?.opmap ?? {};
+
+    data = vs.getprop(ctxmap, 'data', {});
+    reqdata = vs.getprop(ctxmap, 'reqdata', {});
+    match = vs.getprop(ctxmap, 'match', {});
+    reqmatch = vs.getprop(ctxmap, 'reqmatch', {});
+
+    point = _aspoint(vs.getprop(ctxmap, 'point')) ?? basectx?.point;
+    spec = _asspec(vs.getprop(ctxmap, 'spec')) ?? basectx?.spec;
+    result = _asresult(vs.getprop(ctxmap, 'result')) ?? basectx?.result;
+    response = _asresponse(vs.getprop(ctxmap, 'response')) ?? basectx?.response;
+
+    final opname = vs.getprop(ctxmap, 'opname');
+    op = resolveOp(opname);
+  }
+
+  // JSON-sourced context maps carry plain maps for the pipeline value
+  // classes; coerce them so utilities can use typed member access.
+  dynamic _aspoint(dynamic v) => v is Map ? Point(v) : v;
+  dynamic _asspec(dynamic v) => v is Map ? Spec(v) : v;
+  dynamic _asresult(dynamic v) => v is Map ? Result(v) : v;
+  dynamic _asresponse(dynamic v) => v is Map ? Response(v) : v;
+
+  dynamic resolveOp(dynamic 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.
+    var entname = '';
+    final ent = entity;
+    if (null != ent) {
+      if (ent is Map) {
+        entname = vs.getprop(ent, 'name', '') ?? '';
+      } else {
+        try {
+          entname = (ent.name ?? '') as String;
+        } catch (_e) {
+          entname = '';
+        }
+      }
+    }
+
+    final cacheKey = entname + ':' + ('' + (opname ?? '').toString());
+    dynamic op = vs.getprop(opmap, cacheKey);
+
+    if (null == op && null != opname) {
+      final opcfg = vs.getpath(config, ['entity', entname, 'op', opname]);
+      var input = 'match';
+
+      if ('update' == opname || 'create' == opname) {
+        input = 'data';
+      }
+
+      op = Operation({
+        'entity': entname,
+        'name': opname,
+        'input': input,
+        'points': vs.getprop(opcfg, 'points', []),
+      });
+
+      vs.setprop(opmap, cacheKey, op);
+    }
+
+    return op;
+  }
+
+  ProjectNameError error(String code, String msg) {
+    return ProjectNameError(code, msg, this);
+  }
+
+  Map<String, dynamic> toJSON() => {
+        'id': id,
+        'op': op,
+        'spec': spec,
+        'entity': entity,
+        'result': result,
+        'response': response,
+        'meta': meta,
+      };
+
+  @override
+  String toString() => 'Context ' + id;
+}

package/.sdk/tm/dart/lib/Control.dart

@@ -0,0 +1,15 @@
+import 'utility/voxgig_struct.dart' as vs;
+
+// The operation pipeline passes ctrl as a plain map (see Context.ctrl);
+// this class documents the recognised control keys.
+class Control {
+  dynamic throwErr;
+  dynamic err;
+  dynamic explain;
+
+  Control(dynamic ctrlmap) {
+    throwErr = vs.getprop(ctrlmap, 'throw');
+    err = vs.getprop(ctrlmap, 'err');
+    explain = vs.getprop(ctrlmap, 'explain');
+  }
+}

package/.sdk/tm/dart/lib/Operation.dart

@@ -0,0 +1,31 @@
+import 'utility/voxgig_struct.dart' as vs;
+
+import 'Point.dart';
+
+class Operation {
+  dynamic entity;
+  dynamic name;
+  dynamic input;
+  List<dynamic> points = [];
+
+  Operation(dynamic opmap) {
+    entity = vs.getprop(opmap, 'entity', '_');
+    name = vs.getprop(opmap, 'name', '_');
+    input = vs.getprop(opmap, 'input', '_');
+
+    final rawpoints = vs.getprop(opmap, 'points', []);
+    points = [];
+    if (rawpoints is List) {
+      for (final p in rawpoints) {
+        points.add(p is Point ? p : Point(p));
+      }
+    }
+  }
+
+  Map<String, dynamic> toJSON() => {
+        'entity': entity,
+        'name': name,
+        'input': input,
+        'points': points,
+      };
+}