@voxgig/sdkgen 4.4.0 → 4.5.0

package/project/.sdk/tm/dart/test/feature_test.dart

@@ -134,6 +134,12 @@ void tests() {
     if (hasFeature('retry')) {
       describe('retry', () {
         test('retries transient failures then succeeds', (t) async {
+          // Drives netsim as the simulated network: runnable only when this
+          // SDK was generated with it (the harness skips absent features).
+          if (!hasFeature('netsim')) {
+            t.skip('this SDK was generated without the netsim feature');
+            return;
+          }
           final clock = makeClock();
           final h = makeClient(features: [
             {'name': 'netsim', 'options': {'failTimes': 2, 'failStatus': 503}},
@@ -152,6 +158,12 @@ void tests() {
         });
 
         test('gives up after the budget', (t) async {
+          // Drives netsim as the simulated network: runnable only when this
+          // SDK was generated with it (the harness skips absent features).
+          if (!hasFeature('netsim')) {
+            t.skip('this SDK was generated without the netsim feature');
+            return;
+          }
           final clock = makeClock();
           final h = makeClient(features: [
             {'name': 'netsim', 'options': {'failTimes': 9, 'failStatus': 500}},
@@ -203,6 +215,12 @@ void tests() {
         });
 
         test('honours a server Retry-After', (t) async {
+          // Drives netsim as the simulated network: runnable only when this
+          // SDK was generated with it (the harness skips absent features).
+          if (!hasFeature('netsim')) {
+            t.skip('this SDK was generated without the netsim feature');
+            return;
+          }
           final clock = makeClock();
           final h = makeClient(features: [
             {'name': 'netsim', 'options': {'rateLimitTimes': 1, 'retryAfter': 2}},
@@ -222,6 +240,12 @@ void tests() {
         });
 
         test('default jitter path still succeeds', (t) async {
+          // Drives netsim as the simulated network: runnable only when this
+          // SDK was generated with it (the harness skips absent features).
+          if (!hasFeature('netsim')) {
+            t.skip('this SDK was generated without the netsim feature');
+            return;
+          }
           final h = makeClient(features: [
             {'name': 'netsim', 'options': {'failTimes': 1}},
             {'name': 'retry', 'options': {'retries': 2, 'minDelay': 0}},
@@ -235,6 +259,12 @@ void tests() {
     if (hasFeature('timeout')) {
       describe('timeout', () {
         test('a slow request times out', (t) async {
+          // Drives netsim as the simulated network: runnable only when this
+          // SDK was generated with it (the harness skips absent features).
+          if (!hasFeature('netsim')) {
+            t.skip('this SDK was generated without the netsim feature');
+            return;
+          }
           final h = makeClient(features: [
             {'name': 'netsim', 'options': {'latency': 80}},
             {'name': 'timeout', 'options': {'ms': 10}},
@@ -470,6 +500,12 @@ void tests() {
     if (hasFeature('metrics')) {
       describe('metrics', () {
         test('counts ok and err per op', (t) async {
+          // Drives netsim as the simulated network: runnable only when this
+          // SDK was generated with it (the harness skips absent features).
+          if (!hasFeature('netsim')) {
+            t.skip('this SDK was generated without the netsim feature');
+            return;
+          }
           final h = makeClient(features: [
             {'name': 'netsim', 'options': {'failTimes': 1, 'failStatus': 500}},
             {'name': 'metrics', 'options': {}},
@@ -509,6 +545,12 @@ void tests() {
         });
 
         test('records a failed span on error', (t) async {
+          // Drives netsim as the simulated network: runnable only when this
+          // SDK was generated with it (the harness skips absent features).
+          if (!hasFeature('netsim')) {
+            t.skip('this SDK was generated without the netsim feature');
+            return;
+          }
           final h = makeClient(features: [
             {'name': 'netsim', 'options': {'failTimes': 1, 'failStatus': 500}},
             {'name': 'telemetry', 'options': {}},
@@ -542,6 +584,12 @@ void tests() {
         });
 
         test('captures failures', (t) async {
+          // Drives netsim as the simulated network: runnable only when this
+          // SDK was generated with it (the harness skips absent features).
+          if (!hasFeature('netsim')) {
+            t.skip('this SDK was generated without the netsim feature');
+            return;
+          }
           final h = makeClient(features: [
             {'name': 'netsim', 'options': {'failTimes': 1, 'failStatus': 500}},
             {'name': 'debug', 'options': {}},
@@ -556,6 +604,12 @@ void tests() {
     if (hasFeature('audit')) {
       describe('audit', () {
         test('one record per op with sink + actor', (t) async {
+          // Drives netsim as the simulated network: runnable only when this
+          // SDK was generated with it (the harness skips absent features).
+          if (!hasFeature('netsim')) {
+            t.skip('this SDK was generated without the netsim feature');
+            return;
+          }
           final sink = [];
           final h = makeClient(features: [
             {'name': 'netsim', 'options': {'failTimes': 1, 'failStatus': 500}},

package/project/.sdk/tm/go/feature/test_feature.go

@@ -13,7 +13,7 @@ import (
 
 // The `body.<key>` form of an op's response transform: the mock wraps its
 // payload in <key> so the transform can unwrap it again.
-var envelopeResRe = regexp.MustCompile("^`body\\.([^`.]+)`$")
+var envelopeResRe = regexp.MustCompile("^`body\\.(.+)`$")
 
 type TestFeature struct {
 	BaseFeature
@@ -78,7 +78,14 @@ func (f *TestFeature) Init(ctx *core.Context, options map[string]any) {
 			if m == nil {
 				return data
 			}
-			return map[string]any{m[1]: data}
+			// Multi-segment on purpose: GraphQL ops unwrap body.data.<field>
+			// (and body.data.<field>.<entity> for mutations), not just one level.
+			segs := strings.Split(m[1], ".")
+			out := data
+			for i := len(segs) - 1; 0 <= i; i-- {
+				out = map[string]any{segs[i]: out}
+			}
+			return out
 		}
 
 		respond := func(status int, data any, extra map[string]any) map[string]any {
@@ -346,10 +353,14 @@ func (f *TestFeature) buildArgs(ctx *core.Context, op *core.Operation, args map[
 		}
 	}
 
-	// Get required params.
+	// 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.
 	paramsPath := vs.GetPath([]any{"args", "params"}, point)
 	reqdParams := vs.Select(paramsPath, map[string]any{"reqd": true})
-	reqd := vs.Transform(reqdParams, []any{"`$EACH`", "", "`$KEY.name`"})
+	reqdFromParams := vs.Transform(reqdParams, []any{"`$EACH`", "", "`$KEY.name`"})
+	queryPath := vs.GetPath([]any{"args", "query"}, point)
+	reqdQuery := vs.Select(queryPath, map[string]any{"reqd": true})
+	reqdFromQuery := vs.Transform(reqdQuery, []any{"`$EACH`", "", "`$KEY.name`"})
 
 	qand := []any{}
 	q := map[string]any{"`$AND`": &qand}
@@ -357,8 +368,8 @@ func (f *TestFeature) buildArgs(ctx *core.Context, op *core.Operation, args map[
 	if args != nil {
 		for _, key := range vs.KeysOf(args) {
 			isId := key == "id"
-			selected := vs.Select(reqd, key)
-			isReqd := !vs.IsEmpty(selected)
+			isReqd := !vs.IsEmpty(vs.Select(reqdFromParams, key)) ||
+				!vs.IsEmpty(vs.Select(reqdFromQuery, key))
 
 			if isId || isReqd {
 				v := ctx.Utility.Param(ctx, key)

package/project/.sdk/tm/go/test/feature_corpus_test.go

@@ -20,15 +20,17 @@ import (
 	"errors"
 	"fmt"
 	"reflect"
+	"sort"
 	"strings"
 	"testing"
 
 	sdk "GOMODULE"
 )
 
-// Features with a corpus section. A name here with no section is a skip, not
-// a failure: an SDK generated without the feature has nothing to run.
-var featureCorpusNames = []string{"cost"}
+// Features with a corpus section are read from the corpus itself (see
+// TestFeatureCorpus), so a project-authored section — a custom feature
+// added under .sdk/test/feature/ — runs without editing this file. An
+// SDK generated without a listed feature still skips, not fails.
 
 // The standard operation names, in the order the runner prefers them. Every
 // entity declares every CRUD method, so an op that the API does not define
@@ -184,6 +186,23 @@ func fcCandidates(client *sdk.ProjectNameSDK) []fcOp {
 			})
 		}
 	}
+
+	// SAFE OPS FIRST — see the ts harness for the reasoning: the cache stores
+	// only successful GETs, so an SDK whose first usable op is a `create`
+	// (POST) can never satisfy "a hit served from cache costs nothing".
+	safe := map[string]int{"list": 0, "load": 1}
+	rank := func(o fcOp) int {
+		if r, ok := safe[strings.ToLower(o.method)]; ok {
+			return r
+		}
+		return 2
+	}
+	sort.SliceStable(out, func(i, j int) bool {
+		if rank(out[i]) != rank(out[j]) {
+			return rank(out[i]) < rank(out[j])
+		}
+		return out[i].key < out[j].key
+	})
 	return out
 }
 
@@ -432,6 +451,12 @@ func TestFeatureCorpus(t *testing.T) {
 			"corpus cannot exercise a feature without one")
 	}
 
+	featureCorpusNames := make([]string, 0, len(featureSection))
+	for name := range featureSection {
+		featureCorpusNames = append(featureCorpusNames, name)
+	}
+	sort.Strings(featureCorpusNames)
+
 	for _, name := range featureCorpusNames {
 		name := name
 		t.Run(name, func(t *testing.T) {

package/project/.sdk/tm/java/test/FeatureCorpusTest.java

@@ -43,9 +43,10 @@ import JAVAPACKAGE.core.Utility;
 @SuppressWarnings({"unchecked"})
 public class FeatureCorpusTest {
 
-  // Features with a corpus section. A name here with no section is a skip,
-  // not a failure: an SDK generated without the feature has nothing to run.
-  private static final List<String> FEATURE_CORPUS_NAMES = List.of("cost");
+  // Features with a corpus section are read from the corpus itself (see
+  // featureCorpus), so a project-authored section - a custom feature added
+  // under .sdk/test/feature/ - runs without editing this file. An SDK
+  // generated without a listed feature still skips, not fails.
 
   // The standard operation names, in the order the runner prefers them.
   private static final List<String> FEATURE_CORPUS_OPS =
@@ -182,6 +183,14 @@ public class FeatureCorpusTest {
         out.add(new Op(e.getKey() + "." + opname, accessor, call));
       }
     }
+
+    // SAFE OPS FIRST — see the ts harness for the reasoning: the cache stores
+    // only successful GETs, so an SDK whose first usable op is a `create`
+    // (POST) can never satisfy "a hit served from cache costs nothing".
+    java.util.Map<String, Integer> safe = java.util.Map.of("list", 0, "load", 1);
+    out.sort(java.util.Comparator
+        .<Op>comparingInt(o -> safe.getOrDefault(o.key.substring(o.key.indexOf('.') + 1), 2))
+        .thenComparing(o -> o.key));
     return out;
   }
 
@@ -369,7 +378,7 @@ public class FeatureCorpusTest {
         "this project's test.json has no `feature` section - recompile the "
             + "corpus (create-sdkgen .sdk/test/feature/) to run these cases");
 
-    for (String name : FEATURE_CORPUS_NAMES) {
+    for (String name : new TreeMap<>(features).keySet()) {
       Object sectionRaw = features.get(name);
       if (!(sectionRaw instanceof Map)) {
         continue;

package/project/.sdk/tm/js/src/feature/test/TestFeature.js

@@ -274,10 +274,17 @@ class TestFeature extends BaseFeature {
       }
     }
 
-    const reqd = transform(
+    // 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.
+    const reqdParams = transform(
       select(getpath(point, ['args', 'params']), { reqd: true }),
       ['`$EACH`', '', '`$KEY.name`']
     )
+    const reqdQuery = transform(
+      select(getpath(point, ['args', 'query']), { reqd: true }),
+      ['`$EACH`', '', '`$KEY.name`']
+    )
+    const reqd = [...(reqdParams || []), ...(reqdQuery || [])]
 
     const qand = []
     const q = { '`$AND`': qand }

package/project/.sdk/tm/js/src/utility/MakeOptionsUtility.js

@@ -41,11 +41,13 @@ function makeOptions(ctx) {
   // Standard SDK option values.
   const optspec = {
     apikey: '',
+    secret: '',
     base: 'http://localhost:8000',
     prefix: '',
     suffix: '',
     auth: {
-      prefix: ''
+      prefix: '',
+      basic: false
     },
     headers: {
       '`$CHILD`': '`$STRING`'

package/project/.sdk/tm/js/test/feature/Corpus.test.js

@@ -27,9 +27,19 @@ const { join } = require('node:path')
 const { SDK, TEST_JSON_FILE } = require('../utility/index')
 
 
-// Features with a corpus section. A name here with no section is a skip, not
-// a failure: an SDK generated without the feature has nothing to run.
-const FEATURES = ['cost']
+// Features with a corpus section — read from the corpus itself, so a
+// project-authored section (a custom feature added under
+// .sdk/test/feature/) runs without editing this file. Read eagerly: the
+// node test runner collects the per-feature tests at describe time,
+// before any `before` hook fires. An SDK generated without a listed
+// feature still skips, not fails.
+const FEATURES = Object.keys((() => {
+  try {
+    return JSON.parse(readFileSync(
+      join(__dirname, '..', TEST_JSON_FILE), 'utf8')).feature || {}
+  }
+  catch (e) { return {} }
+})()).sort()
 
 
 // One operation this SDK can actually perform is described by
@@ -109,7 +119,12 @@ function candidates(client) {
       out.push({ key: entity + '.' + op, accessor: accessor[entity], entity, op })
     }
   }
-  return out
+  // SAFE OPS FIRST — see the ts harness for the reasoning: the cache stores
+  // only successful GETs, so an SDK whose first usable op is a `create`
+  // (POST) can never satisfy "a hit served from cache costs nothing".
+  const SAFE = { list: 0, load: 1 }
+  return out.sort((a, b) =>
+    ((SAFE[a.op] ?? 2) - (SAFE[b.op] ?? 2)) || a.key.localeCompare(b.key))
 }
 
 

package/project/.sdk/tm/js/test/feature.test.js

@@ -21,6 +21,16 @@ function recordingServer(reply) {
 }
 
 
+// A subtest that drives a second feature (netsim as the simulated network)
+// can only run when this SDK was generated with it: the harness skips
+// absent features, which would leave the scenario unsimulated and the
+// assertions meaningless. Same convention as the other targets.
+function skipWithout(name) {
+  return hasFeature(name) ? false
+    : ('this SDK was generated without the ' + name + ' feature')
+}
+
+
 describe('feature', () => {
 
   test('at least the test feature is present', () => {
@@ -95,7 +105,7 @@ describe('feature', () => {
   // --- retry ----------------------------------------------------------------
   if (hasFeature('retry')) describe('retry', () => {
 
-    test('retries transient failures then succeeds', async () => {
+    test('retries transient failures then succeeds', { skip: skipWithout('netsim') }, async () => {
       const clock = makeClock()
       const h = makeClient({ features: [
         { name: 'netsim', options: { failTimes: 2, failStatus: 503 } },
@@ -105,7 +115,7 @@ describe('feature', () => {
       strictEqual(h.client._retry.attempts, 2)
     })
 
-    test('gives up after the budget', async () => {
+    test('gives up after the budget', { skip: skipWithout('netsim') }, async () => {
       const clock = makeClock()
       const h = makeClient({ features: [
         { name: 'netsim', options: { failTimes: 9, failStatus: 500 } },
@@ -131,7 +141,7 @@ describe('feature', () => {
       strictEqual(n, 3)
     })
 
-    test('honours a server Retry-After', async () => {
+    test('honours a server Retry-After', { skip: skipWithout('netsim') }, async () => {
       const clock = makeClock()
       const h = makeClient({ features: [
         { name: 'netsim', options: { rateLimitTimes: 1, retryAfter: 2 } },
@@ -141,7 +151,7 @@ describe('feature', () => {
       strictEqual(clock.time, 2000)
     })
 
-    test('default jitter path still succeeds', async () => {
+    test('default jitter path still succeeds', { skip: skipWithout('netsim') }, async () => {
       const h = makeClient({ features: [
         { name: 'netsim', options: { failTimes: 1 } },
         { name: 'retry', options: { retries: 2, minDelay: 0 } },
@@ -154,7 +164,7 @@ describe('feature', () => {
   // --- timeout --------------------------------------------------------------
   if (hasFeature('timeout')) describe('timeout', () => {
 
-    test('a slow request times out', async () => {
+    test('a slow request times out', { skip: skipWithout('netsim') }, async () => {
       const h = makeClient({ features: [
         { name: 'netsim', options: { latency: 80 } },
         { name: 'timeout', options: { ms: 10 } },
@@ -319,7 +329,7 @@ describe('feature', () => {
   // --- metrics --------------------------------------------------------------
   if (hasFeature('metrics')) describe('metrics', () => {
 
-    test('counts ok and err per op', async () => {
+    test('counts ok and err per op', { skip: skipWithout('netsim') }, async () => {
       const h = makeClient({ features: [
         { name: 'netsim', options: { failTimes: 1, failStatus: 500 } },
         { name: 'metrics', options: {} },
@@ -352,7 +362,7 @@ describe('feature', () => {
       ok(/^00-.+-.+-01$/.test(sent['traceparent']))
     })
 
-    test('records a failed span on error', async () => {
+    test('records a failed span on error', { skip: skipWithout('netsim') }, async () => {
       const h = makeClient({ features: [
         { name: 'netsim', options: { failTimes: 1, failStatus: 500 } },
         { name: 'telemetry', options: {} },
@@ -377,7 +387,7 @@ describe('feature', () => {
       strictEqual(seen[0].headers.authorization, '<redacted>')
     })
 
-    test('captures failures', async () => {
+    test('captures failures', { skip: skipWithout('netsim') }, async () => {
       const h = makeClient({ features: [
         { name: 'netsim', options: { failTimes: 1, failStatus: 500 } },
         { name: 'debug', options: {} },
@@ -391,7 +401,7 @@ describe('feature', () => {
   // --- audit ----------------------------------------------------------------
   if (hasFeature('audit')) describe('audit', () => {
 
-    test('one record per op with sink + actor', async () => {
+    test('one record per op with sink + actor', { skip: skipWithout('netsim') }, async () => {
       const sink = []
       const h = makeClient({ features: [
         { name: 'netsim', options: { failTimes: 1, failStatus: 500 } },

package/project/.sdk/tm/lean/src/SdkFeatures.lean

@@ -479,6 +479,190 @@ def pagingFeature : SIO Feature := do
                  (newMap #[("pages", .num 0.0), ("items", .num 0.0)])
                bumpNum b "items" n.toFloat }
 
+-- ---------------------------------------------------------------------------
+-- cost
+-- ---------------------------------------------------------------------------
+-- Prices every transport ATTEMPT and commits the spend once per OPERATION.
+-- Mirrors tm/ts/src/feature/cost/CostFeature.ts.
+--
+-- ORDER MATTERS. Cost must sit INSIDE the cache, or a response served from
+-- cache is charged for money that was never spent.
+
+def costFeature : SIO Feature := do
+  let optsR ← IO.mkRef (← emptyMap)
+  -- Accumulated per call and committed once: adding each attempt to the
+  -- running total and subtracting it again loses precision.
+  let pendR ← IO.mkRef (← newMap #[("attempts", Value.num 0.0), ("amount", Value.num 0.0),
+                                   ("reported", Value.num 0.0), ("estimated", Value.num 0.0),
+                                   ("source", Value.str "none")])
+  let seqR ← IO.mkRef 0
+
+  let record : Value → SIO Value := fun ctx => do
+    let o ← optsR.get
+    let cur ← optStr o "currency" "USD"
+    let lim ← optNum o "budget" 0.0
+    let total ← newMap #[("calls", Value.num 0.0), ("attempts", Value.num 0.0),
+                         ("amount", Value.num 0.0), ("reported", Value.num 0.0),
+                         ("estimated", Value.num 0.0)]
+    let ops ← emptyMap
+    let actors ← emptyMap
+    let budget ← newMap #[("limit", Value.num lim), ("spent", Value.num 0.0),
+                          ("remaining", Value.num lim), ("exceeded", Value.bool false)]
+    trackCtx ctx "cost" (newMap #[("currency", Value.str cur), ("total", total),
+                                  ("ops", ops), ("actors", actors), ("budget", budget),
+                                  ("last", Value.noval)])
+
+  let resetPending : SIO Unit := do
+    let p ← newMap #[("attempts", Value.num 0.0), ("amount", Value.num 0.0),
+                     ("reported", Value.num 0.0), ("estimated", Value.num 0.0),
+                     ("source", Value.str "none")]
+    pendR.set p
+
+  -- Pricing precedence: a server-stated header beats the rate table, which
+  -- beats the flat unit.
+  let priceOf : Value → Value → SIO (Float × String) := fun ctx res => do
+    let o ← optsR.get
+    let perUnit ← optNum o "perUnit" 0.0
+    let hname ← optStr o "header" ""
+    let hv ← if hname == "" then pure Value.noval else headerCI (← gp res "headers") hname
+    let hn := numOf hv (-1.0)
+    if hname != "" && hn >= 0.0 then
+      pure (hn * perUnit, "header")
+    else do
+      let rates ← gp o "rates"
+      let opname ← SdkUtility.opnameOf ctx
+      -- The documented grammar is '<entity>.<op>', then '<op>', then '*'.
+      -- Checking only the bare name charged `{'widget.load': 0.25, '*': 0.01}`
+      -- a widget load at 0.01, unlike every other port.
+      let ent ← gpS (← gp ctx "op") "entity"
+      let byEntOp := numOf (← gp rates (ent ++ "." ++ opname)) (-1.0)
+      let byOp := numOf (← gp rates opname) (-1.0)
+      let byAny := numOf (← gp rates "*") (-1.0)
+      if byEntOp >= 0.0 then pure (byEntOp, "table")
+      else if byOp >= 0.0 then pure (byOp, "table")
+      else if byAny >= 0.0 then pure (byAny, "table")
+      else do
+        let unit ← optNum o "unit" 0.0
+        if unit != 0.0 then pure (unit, "unit") else pure (0.0, "none")
+
+  let bucketOf : Value → String → SIO Value := fun bucket key => do
+    let b ← gp bucket key
+    match b with
+    | Value.map _ => pure b
+    | _ => do
+        let m ← newMap #[("calls", Value.num 0.0), ("amount", Value.num 0.0)]
+        sp bucket key m
+        pure m
+
+  let commit : Value → SIO Unit := fun ctx => do
+    let o ← optsR.get
+    let p ← pendR.get
+    let rec_ ← record ctx
+
+    -- A body usage figure prices the WHOLE call, so it replaces the
+    -- per-attempt estimate rather than adding to it - and, being
+    -- server-stated, the whole amount counts as reported. Read here, not at
+    -- the transport seam, because the body is one-shot.
+    let path ← optStr o "path" ""
+    let perUnit ← optNum o "perUnit" 0.0
+    let bodyAmt ← if path == "" then pure (-1.0) else do
+      let body ← gp (← gp ctx "result") "body"
+      pure (numOf (← getpath body (Value.str path)) (-1.0))
+
+    -- Bind the pending figures first: `←` cannot be nested inside an
+    -- if-then-else that is not itself a `do` block.
+    let pendAmount := numOf (← gp p "amount") 0.0
+    let pendReported := numOf (← gp p "reported") 0.0
+    let pendEstimated := numOf (← gp p "estimated") 0.0
+    let amount := if bodyAmt >= 0.0 then bodyAmt * perUnit else pendAmount
+    let reported := if bodyAmt >= 0.0 then amount else pendReported
+    let estimated := if bodyAmt >= 0.0 then 0.0 else pendEstimated
+    if bodyAmt >= 0.0 then sp p "source" (Value.str "body")
+
+    let total ← gp rec_ "total"
+    bumpNum total "amount" amount
+    bumpNum total "reported" reported
+    bumpNum total "estimated" estimated
+    bumpNum total "calls" 1.0
+
+    let budget ← gp rec_ "budget"
+    let lim := numOf (← gp budget "limit") 0.0
+    let spent := numOf (← gp total "amount") 0.0
+    sp budget "spent" (Value.num spent)
+    sp budget "remaining"
+      (Value.num (if lim > 0.0 then (if lim - spent > 0.0 then lim - spent else 0.0) else 0.0))
+    if lim > 0.0 && spent >= lim then sp budget "exceeded" (Value.bool true)
+
+    let opname ← SdkUtility.opnameOf ctx
+    let actorV ← gp (← gp ctx "ctrl") "actor"
+    let actorS := match actorV with | Value.str a => a | _ => ""
+    let actor ← if actorS != "" then pure actorS else optStr o "actor" "anonymous"
+
+    let opB ← bucketOf (← gp rec_ "ops") ("_." ++ opname)
+    bumpNum opB "calls" 1.0
+    bumpNum opB "amount" amount
+    let acB ← bucketOf (← gp rec_ "actors") actor
+    bumpNum acB "calls" 1.0
+    bumpNum acB "amount" amount
+
+    let n ← seqR.modifyGet fun n => (n + 1, n + 1)
+    let last ← newMap #[("seq", Value.num n.toFloat), ("op", Value.str opname),
+                        ("actor", Value.str actor), ("amount", Value.num amount),
+                        ("currency", ← gp rec_ "currency"), ("source", ← gp p "source"),
+                        ("attempts", ← gp p "attempts")]
+    sp rec_ "last" last
+    resetPending
+
+  pure { name := "cost"
+       , init := fun ctx opts => do
+           let om ← toOptsMap opts
+           optsR.set om
+           resetPending
+           if (← optActive opts) then do
+             let _ ← record ctx
+             let client ← clientOf ctx
+             let inner ← getFetcher client
+             setFetcher client fun c u f => do
+               -- The transport answers (response, error): a rejecting attempt
+               -- still costs, or a run of failures under retry would be free.
+               let (res, rerr) ← inner c u f
+               let (amount, source) ← priceOf c res
+               let p ← pendR.get
+               bumpNum p "attempts" 1.0
+               bumpNum p "amount" amount
+               bumpNum p (if source == "header" then "reported" else "estimated") amount
+               sp p "source" (Value.str source)
+               let rec_ ← record c
+               bumpNum (← gp rec_ "total") "attempts" 1.0
+               pure (res, rerr)
+       , hook := fun stage ctx => do
+           let o ← optsR.get
+           if stage == "PrePoint" then do
+             let lim ← optNum o "budget" 0.0
+             if lim > 0.0 then do
+               let rec_ ← record ctx
+               let spent := numOf (← gp (← gp rec_ "total") "amount") 0.0
+               if spent >= lim then do
+                 sp (← gp rec_ "budget") "exceeded" (Value.bool true)
+                 if (← optStr o "onBudget" "warn") == "deny" then do
+                   let e ← SdkUtility.mkErr "cost_budget"
+                     ("Cost budget of " ++ toString lim ++ " is spent")
+                   let out ← SdkUtility.gpMap ctx "out"
+                   sp out "point" e
+           else if stage == "PreDone" then do
+             -- A cache hit is a real call that cost nothing, so it commits
+             -- too: that is the point of ordering cost inside the cache.
+             commit ctx
+           else if stage == "PreUnexpected" then do
+             -- A failed operation never reaches PreDone, so without this its
+             -- attempts are priced and then discarded: repeated connection
+             -- failures would slip past an onBudget "deny" ceiling, and the
+             -- shared pending value would survive to be attributed to the
+             -- next successful call. A call that made NO attempt was refused
+             -- before the network and must not be counted.
+             let p ← pendR.get
+             if numOf (← gp p "attempts") 0.0 > 0.0 then commit ctx else resetPending }
+
 def streamingFeature : SIO Feature := do
   let optsR ← IO.mkRef (← emptyMap)
   pure { name := "streaming"
@@ -591,12 +775,13 @@ def makeFeature (name : String) : SIO Feature :=
   | "streaming" => streamingFeature
   | "proxy" => proxyFeature
   | "netsim" => netsimFeature
+  | "cost" => costFeature
   | _ => baseFeature
 
 /-- The catalog order: transport wrappers compose in this order. -/
 def featureNames : Array String :=
   #["log", "rbac", "idempotency", "clienttrack", "paging", "streaming",
     "metrics", "telemetry", "debug", "audit",
-    "cache", "ratelimit", "timeout", "retry", "proxy", "netsim"]
+    "cost", "cache", "ratelimit", "timeout", "retry", "proxy", "netsim"]
 
 end SdkFeatures