fix: address PR #21 review — non-strict default, jsonDecode precision, docs accuracy

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: michaelmcnees

docs/superpowers/plans/2026-03-24-data-transformation.md

@@ -12,7 +12,7 @@
 
 ---
 
-### Task 1: Test and document built-in macros
+## Task 1: Test and document built-in macros
 
 **Files:**
 - Create: `internal/cel/macros_test.go`
@@ -130,7 +130,7 @@ git commit -m "test(cel): add coverage for built-in map/filter/exists/all macros
 
 ---
 
-### Task 2: String functions — toLower, toUpper, trim
+## Task 2: String functions — toLower, toUpper, trim
 
 **Files:**
 - Create: `internal/cel/functions.go`
@@ -329,7 +329,7 @@ git commit -m "feat(cel): add toLower, toUpper, trim string functions"
 
 ---
 
-### Task 3: String functions — replace and split
+## Task 3: String functions — replace and split
 
 **Files:**
 - Modify: `internal/cel/functions.go`
@@ -441,7 +441,7 @@ git commit -m "feat(cel): add replace and split string functions"
 
 ---
 
-### Task 4: Type coercion — parseInt, parseFloat, toString
+## Task 4: Type coercion — parseInt, parseFloat, toString
 
 **Files:**
 - Modify: `internal/cel/functions.go`
@@ -621,7 +621,9 @@ git commit -m "feat(cel): add parseInt, parseFloat, toString type coercion funct
 
 ---
 
-### Task 5: Object construction — obj()
+## Task 5: Object construction — obj()
+
+> **Implementation note:** The plan originally specified a variadic `obj()` overload, but cel-go does not support true variadic functions without macros. The implementation uses fixed-arity overloads for 2, 4, 6, 8, and 10 arguments (1–5 key-value pairs), all sharing a single `objBinding` function.
 
 **Files:**
 - Modify: `internal/cel/functions.go`
@@ -755,7 +757,7 @@ git commit -m "feat(cel): add obj() map construction function"
 
 ---
 
-### Task 6: Utility functions — default, flatten
+## Task 6: Utility functions — default, flatten
 
 **Files:**
 - Modify: `internal/cel/functions.go`
@@ -881,7 +883,7 @@ git commit -m "feat(cel): add default() null coalescing and flatten() functions"
 
 ---
 
-### Task 7: JSON functions — jsonEncode, jsonDecode
+## Task 7: JSON functions — jsonEncode, jsonDecode
 
 **Files:**
 - Modify: `internal/cel/functions.go`
@@ -1015,7 +1017,7 @@ git commit -m "feat(cel): add jsonEncode and jsonDecode functions"
 
 ---
 
-### Task 8: Date/time functions — timestamp, formatTimestamp
+## Task 8: Date/time functions — parseTimestamp, formatTimestamp
 
 **Files:**
 - Modify: `internal/cel/functions.go`
@@ -1035,9 +1037,9 @@ func TestFunc_Timestamp(t *testing.T) {
 		expr    string
 		wantErr bool
 	}{
-		{"iso8601", `timestamp("2026-03-24T19:00:00Z")`, false},
-		{"with_offset", `timestamp("2026-03-24T14:00:00-05:00")`, false},
-		{"invalid", `timestamp("not a date")`, true},
+		{"iso8601", `parseTimestamp("2026-03-24T19:00:00Z")`, false},
+		{"with_offset", `parseTimestamp("2026-03-24T14:00:00-05:00")`, false},
+		{"invalid", `parseTimestamp("not a date")`, true},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -1055,11 +1057,11 @@ func TestFunc_FormatTimestamp(t *testing.T) {
 	eval, err := NewEvaluator()
 	require.NoError(t, err)
 
-	result, err := eval.Eval(`formatTimestamp(timestamp("2026-03-24T19:00:00Z"), "2006-01-02")`, newTestContext())
+	result, err := eval.Eval(`formatTimestamp(parseTimestamp("2026-03-24T19:00:00Z"), "2006-01-02")`, newTestContext())
 	require.NoError(t, err)
 	assert.Equal(t, "2026-03-24", result)
 
-	result, err = eval.Eval(`formatTimestamp(timestamp("2026-03-24T19:30:45Z"), "15:04:05")`, newTestContext())
+	result, err = eval.Eval(`formatTimestamp(parseTimestamp("2026-03-24T19:30:45Z"), "15:04:05")`, newTestContext())
 	require.NoError(t, err)
 	assert.Equal(t, "19:30:45", result)
 }
@@ -1068,7 +1070,7 @@ func TestFunc_FormatTimestamp(t *testing.T) {
 - [ ] **Step 2: Run tests to verify they fail**
 
 Run: `go test ./internal/cel/ -run "TestFunc_Timestamp|TestFunc_FormatTimestamp" -v`
-Expected: FAIL
+Expected: FAIL (functions registered as `parseTimestamp`, not `timestamp`)
 
 - [ ] **Step 3: Add date/time functions**
 
@@ -1083,15 +1085,15 @@ type timeLib struct{}
 
 func (l *timeLib) CompileOptions() []cel.EnvOption {
 	return []cel.EnvOption{
-		cel.Function("timestamp",
-			cel.Overload("timestamp_string",
+		cel.Function("parseTimestamp",
+			cel.Overload("parseTimestamp_string",
 				[]*cel.Type{cel.StringType},
 				cel.TimestampType,
 				cel.UnaryBinding(func(val ref.Val) ref.Val {
 					s := string(val.(types.String))
 					t, err := time.Parse(time.RFC3339, s)
 					if err != nil {
-						return types.NewErr("timestamp: %v", err)
+						return types.NewErr("parseTimestamp: %v", err)
 					}
 					return types.Timestamp{Time: t}
 				}),
@@ -1144,12 +1146,12 @@ Expected: PASS — all tests including existing ones
 
 ```bash
 git add internal/cel/functions.go internal/cel/functions_test.go
-git commit -m "feat(cel): add timestamp and formatTimestamp date/time functions"
+git commit -m "feat(cel): add parseTimestamp and formatTimestamp date/time functions"
 ```
 
 ---
 
-### Task 9: Update CEL expressions documentation
+## Task 9: Update CEL expressions documentation
 
 **Files:**
 - Modify: `site/src/content/docs/concepts/expressions.md`
@@ -1207,7 +1209,7 @@ git commit -m "docs: add custom CEL functions and macros to expressions referenc
 
 ---
 
-### Task 10: Create data transformations guide
+## Task 10: Create data transformations guide
 
 **Files:**
 - Create: `site/src/content/docs/getting-started/data-transformations.md`
@@ -1243,7 +1245,7 @@ git commit -m "docs: add data transformation patterns guide (#14)"
 
 ---
 
-### Task 11: Create example workflows
+## Task 11: Create example workflows
 
 **Files:**
 - Create: `examples/data-transform-api-to-db.yaml`
@@ -1360,7 +1362,7 @@ git commit -m "feat: add data transformation and AI enrichment example workflows
 
 ---
 
-### Task 12: Final validation
+## Task 12: Final validation
 
 - [ ] **Step 1: Run full test suite**
 

docs/superpowers/specs/2026-03-24-data-transformation-design.md

@@ -69,7 +69,7 @@ Errors on odd number of args or non-string keys. Enables building maps for DB in
 
 | Function | Example | Result |
 |----------|---------|--------|
-| `timestamp(string)` | `timestamp("2026-03-24T19:00:00Z")` | timestamp value |
+| `parseTimestamp(string)` | `parseTimestamp("2026-03-24T19:00:00Z")` | timestamp value |
 | `formatTimestamp(ts, layout)` | `formatTimestamp(ts, "2006-01-02")` | `"2026-03-24"` |
 
 Uses Go time layout strings.
@@ -86,14 +86,15 @@ In `internal/cel/cel.go`, the `NewEvaluator` function passes function options to
 
 ```go
 func NewEvaluator() (*Evaluator, error) {
-    env, err := cel.NewEnv(
+    opts := []cel.EnvOption{
         cel.Variable("steps", cel.MapType(cel.StringType, cel.DynType)),
         cel.Variable("inputs", cel.MapType(cel.StringType, cel.DynType)),
         cel.Variable("env", cel.MapType(cel.StringType, cel.StringType)),
         cel.Variable("trigger", cel.MapType(cel.StringType, cel.DynType)),
-        // Custom functions
-        customFunctions()...,
-    )
+    }
+    opts = append(opts, customFunctions()...)
+
+    env, err := cel.NewEnv(opts...)
     // ...
 }
 ```
@@ -107,7 +108,7 @@ All errors surface through the existing `Eval` error path:
 - `obj()` with odd args → evaluation error
 - `obj()` with non-string keys → evaluation error
 - `jsonDecode()` with invalid JSON → evaluation error
-- `timestamp()` with unparseable string → evaluation error
+- `parseTimestamp()` with unparseable string → evaluation error
 
 No new error types needed.
 

examples/ai-data-enrichment.yaml

@@ -58,7 +58,7 @@ steps:
       query: >
         INSERT INTO urgent_tickets (priority, category, products, raw_body)
         VALUES ($1, $2, $3, $4)
-      params:
+      args:
         - "{{ steps.classify.output.json.priority }}"
         - "{{ steps.classify.output.json.category }}"
         - "{{ jsonEncode(steps.classify.output.json.products) }}"

examples/data-transform-api-to-db.yaml

@@ -2,8 +2,7 @@ name: data-transform-api-to-db
 description: >
   Fetches a user from an API, transforms the record using CEL expressions
   to match a database schema, and inserts the normalized data into Postgres.
-  Demonstrates obj(), toLower(), and string functions without requiring
-  an AI model.
+  Demonstrates toLower() and string functions without requiring an AI model.
 
 steps:
   - name: fetch-user

internal/cel/functions.go

@@ -158,6 +158,7 @@ func (l *collectionLib) CompileOptions() []cel.EnvOption {
 			cel.Overload("default_any_any",
 				[]*cel.Type{cel.DynType, cel.DynType},
 				cel.DynType,
+				cel.OverloadIsNonStrict(),
 				cel.BinaryBinding(func(lhs, rhs ref.Val) ref.Val {
 					if types.IsError(lhs) || types.IsUnknown(lhs) || lhs == types.NullValue {
 						return rhs
@@ -273,11 +274,13 @@ func (l *jsonLib) CompileOptions() []cel.EnvOption {
 				cel.DynType,
 				cel.UnaryBinding(func(val ref.Val) ref.Val {
 					s := string(val.(types.String))
+					dec := json.NewDecoder(strings.NewReader(s))
+					dec.UseNumber()
 					var result any
-					if err := json.Unmarshal([]byte(s), &result); err != nil {
+					if err := dec.Decode(&result); err != nil {
 						return types.NewErr("jsonDecode: %v", err)
 					}
-					return types.DefaultTypeAdapter.NativeToValue(result)
+					return types.DefaultTypeAdapter.NativeToValue(normalizeJSONNumbers(result))
 				}),
 			),
 		),
@@ -338,3 +341,30 @@ func (l *timeLib) CompileOptions() []cel.EnvOption {
 func (l *timeLib) ProgramOptions() []cel.ProgramOption {
 	return nil
 }
+
+// normalizeJSONNumbers walks a decoded JSON structure and converts json.Number
+// values to int64 (if the number is an integer) or float64.
+func normalizeJSONNumbers(v any) any {
+	switch val := v.(type) {
+	case json.Number:
+		if i, err := val.Int64(); err == nil {
+			return i
+		}
+		if f, err := val.Float64(); err == nil {
+			return f
+		}
+		return val.String()
+	case map[string]any:
+		for k, v := range val {
+			val[k] = normalizeJSONNumbers(v)
+		}
+		return val
+	case []any:
+		for i, v := range val {
+			val[i] = normalizeJSONNumbers(v)
+		}
+		return val
+	default:
+		return v
+	}
+}

internal/cel/functions_test.go

@@ -227,6 +227,12 @@ func TestFunc_Obj(t *testing.T) {
 			expr:    `obj("key")`,
 			wantErr: true,
 		},
+		{
+			"non_string_key",
+			`obj(1, "value")`,
+			nil,
+			true,
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -341,7 +347,7 @@ func TestFunc_JsonDecode(t *testing.T) {
 				m, ok := result.(map[string]any)
 				require.True(t, ok)
 				assert.Equal(t, "bob", m["name"])
-				assert.Equal(t, float64(25), m["age"])
+				assert.Equal(t, int64(25), m["age"])
 			},
 		},
 		{

site/src/content/docs/concepts/expressions.md

@@ -489,7 +489,7 @@ steps:
 
 ### `obj(key, value, ...)`
 
-Builds a map from alternating key-value arguments. Accepts any number of key-value pairs.
+Builds a map from alternating key-value arguments. Supports up to 5 key-value pairs (10 arguments) due to cel-go's fixed-arity overload requirement — CEL does not support true variadic functions without macros. For maps with more than 5 pairs, use nested `obj()` calls or construct the value with `jsonDecode`.
 
 ```yaml
 steps:

site/src/content/docs/getting-started/data-transformations.md

@@ -48,7 +48,7 @@ steps:
         records: >
           {{ steps['fetch-users'].output.json.users.map(u,
                obj(
-                 'name',       toLower(u.firstName + ' ' + u.lastName),
+                 'name',       (u.firstName + ' ' + u.lastName).toLower(),
                  'birth_date', u.dob
                )
              ) }}
@@ -58,7 +58,7 @@ What the CEL expression does:
 
 - `.map(u, ...)` -- iterates the `users` list, binding each element to `u`
 - `obj('name', ..., 'birth_date', ...)` -- constructs a new object with the renamed keys
-- `toLower(...)` -- normalizes the full name to lowercase
+- `.toLower()` -- normalizes the full name to lowercase (method call on the concatenated string)
 - String concatenation (`+`) joins first and last name with a space
 
 The output of the `map()` call is a new list of objects ready for the batch insert. Nothing left the workflow engine.
@@ -174,7 +174,7 @@ steps:
                  'id',          r.reviewId,
                  'rating',      r.starRating,
                  'reviewed_at', r.submittedAt,
-                 'text',        trim(r.body)
+                 'text',        r.body.trim()
                )
              ) }}
 
@@ -265,13 +265,13 @@ These are the Mantle CEL extensions available in workflow expressions. For full
 
 **String**
 
-| Function | Description |
-|---|---|
-| `toLower(s)` | Convert string to lowercase |
-| `toUpper(s)` | Convert string to uppercase |
-| `trim(s)` | Remove leading and trailing whitespace |
-| `replace(s, old, new)` | Replace all occurrences of `old` with `new` |
-| `split(s, sep)` | Split string into a list on separator |
+| Function | Example | Description |
+|---|---|---|
+| `s.toLower()` | `"HELLO".toLower()` | Convert string to lowercase |
+| `s.toUpper()` | `"hello".toUpper()` | Convert string to uppercase |
+| `s.trim()` | `" a ".trim()` | Remove leading and trailing whitespace |
+| `s.replace(old, new)` | `"a-b".replace("-", "_")` | Replace all occurrences of `old` with `new` |
+| `s.split(sep)` | `"a,b".split(",")` | Split string into a list on separator |
 
 **Object construction**