refactor(platform): tighten EvaluatorResponse — ExecTime, ScriptExeID, AsMap (#141)

* refactor(platform): tighten EvaluatorResponse — ExecTime, ScriptExeID, AsMap

Three breaking changes to the platform.EvaluatorResponse interface:

1. GetScriptExeID() string → ScriptExeID() string (drop Get prefix)
2. GetExecTime() string → ExecTime() time.Duration (no longer stringified
   at the boundary; implementations already stored time.Duration internally)
3. New AsMap() (map[string]any, error) — returns the result as a typed map,
   with an error of the form "AsMap: expected map[string]any, got <T>" when
   the underlying value has a different shape

Migrates 40+ existing `result.Interface().(map[string]any); require.True(t, ok)`
test sites to `result.AsMap(); require.NoError(t, err)`, which validates the
helper's value. Other typed accessors (AsString, AsBool, AsInt, AsSlice) are
not added — they have zero current usage and YAGNI applies.

Updates the three implementations (extism, risor, starlark) and all consuming
tests/mocks (platform/mocks_test.go, polyscript_mocks_test.go,
engines/integration_test.go, readme_test.go, polyscript_*_test.go).

Closes #86.

https://claude.ai/code/session_01C61VEAmjxSnX5Xhbab8NvL

* test(evaluator): cover AsMap error paths in all three engines

SonarQube reported 30% coverage on new code (required ≥80%) because
the AsMap() error branch (non-map underlying value) was unexercised.
The 40+ migrated test sites cover only the success path.

Adds TestExecResultAsMap to each engine's response_test.go with three
subtests:
- success: underlying value is a real map
- error on string: returns the typed error message
- error on nil/int: confirms the %T format string reports the actual type

Per-package coverage after these tests:
- extism/evaluator: 96.2%
- risor/evaluator:  90.8%
- starlark/evaluator: 83.5%

https://claude.ai/code/session_01C61VEAmjxSnX5Xhbab8NvL

* test(mocks): harden mockEvaluatorResponse.AsMap type-assertion

Per Copilot review on #141 — the mock previously discarded the type
assertion result and could return (nil, nil) when a test author
configured a non-map Return value, silently diverging from the real
AsMap contract.

The mock now:
- Returns (nil, nil) only when explicitly configured with nil + nil
- Returns the configured error when the asserted value isn't a map but
  an error was provided
- Synthesizes the production error format ("AsMap: expected
  map[string]any, got %T") when the asserted value isn't a map and no
  error was provided

Applies to both platform/mocks_test.go and polyscript_mocks_test.go.

https://claude.ai/code/session_01C61VEAmjxSnX5Xhbab8NvL

* refactor(evaluator): introduce per-engine ErrAsMapTypeMismatch sentinels

Replaces the inline `fmt.Errorf("AsMap: expected map[string]any, got %T", v)`
with a wrapped sentinel in each engine's evaluator package:

- engines/extism/evaluator.ErrAsMapTypeMismatch
  = "extism: AsMap expected map[string]any"
- engines/risor/evaluator.ErrAsMapTypeMismatch
  = "risor: AsMap expected map[string]any"
- engines/starlark/evaluator.ErrAsMapTypeMismatch
  = "starlark: AsMap expected map[string]any"

Each AsMap now returns `fmt.Errorf("%w, got %T", ErrAsMapTypeMismatch, v)`,
so callers can `errors.Is(err, evaluator.ErrAsMapTypeMismatch)` for the
type-mismatch case and still read the concrete Go type from err.Error().

Matches the existing per-package sentinel pattern in
engines/{extism,risor,starlark}/compiler/errors.go.

Tests switched from substring assertions on the full message to
require.ErrorIs(t, err, ErrAsMapTypeMismatch) + a smaller substring
assertion on just the "got <T>" tail.

https://claude.ai/code/session_01C61VEAmjxSnX5Xhbab8NvL

* docs(changelog): trim Unreleased entries to match project's terse style

Earlier entries (v0.6.0, v0.7.0) keep each item to 1–3 lines of plain
facts. The recent additions ballooned into multi-paragraph descriptions
with nested bullets and editorial commentary. This brings them back into
the established style: 1–3 lines per item, **BREAKING** matching the
existing prefix capitalization, just the trailing PR link for traceability.

Net change: -41 lines, +20 lines.

https://claude.ai/code/session_01C61VEAmjxSnX5Xhbab8NvL

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: robbyt

CHANGELOG.md

@@ -42,21 +42,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   appends to the compiler's existing globals, deduplicating names already
   present. Order-of-call no longer matters when combined with
   `WithCtxGlobal`. ([#118](https://github.com/robbyt/go-polyscript/pull/118))
-- **Breaking:** Renamed `machine`→`engine` in the type-system API to match
-  the terminology used everywhere else. `ExecutableContent.GetMachineType()`
-  and `ExecutableUnit.GetMachineType()` are now `EngineType()`. The
-  `engines/types` package exports `ErrInvalidEngineType`,
-  `GetEngineTypeFromString`, and `GetEngineTypeFromPath` (renamed from the
-  `MachineType` equivalents). The conventional import alias is now
-  `engineTypes`. Closes [#90](https://github.com/robbyt/go-polyscript/issues/90).
+- **BREAKING**: Renamed `machine`→`engine` throughout the type-system API.
+  `ExecutableContent.GetMachineType()` and `ExecutableUnit.GetMachineType()`
+  are now `EngineType()`. `engines/types` exports `ErrInvalidEngineType`,
+  `GetEngineTypeFromString`, and `GetEngineTypeFromPath`.
   ([#137](https://github.com/robbyt/go-polyscript/pull/137))
-- **Breaking:** Unexported the six fields on `platform/script.ExecutableUnit`
-  (`ID`, `CreatedAt`, `ScriptLoader`, `Compiler`, `Content`, `DataProvider`).
-  External callers must use the existing getters (`GetID()`, `GetCreatedAt()`,
-  `GetLoader()`, `GetCompiler()`, `GetContent()`, `GetDataProvider()`) for
-  reads and construct only via `NewExecutableUnit(...)`. Mid-flight mutation
-  of `DataProvider` (and the other fields) is no longer possible from outside
-  the package. Closes [#91](https://github.com/robbyt/go-polyscript/issues/91).
+- **BREAKING**: Unexported all six fields on `platform/script.ExecutableUnit`.
+  Construct via `NewExecutableUnit` only; read via the existing getters.
+  ([#139](https://github.com/robbyt/go-polyscript/pull/139))
+- **BREAKING**: Tightened `platform.EvaluatorResponse`. `GetScriptExeID()`
+  and `GetExecTime()` are now `ScriptExeID()` and `ExecTime() time.Duration`.
+  Added `AsMap() (map[string]any, error)`; on type mismatch the error wraps
+  a per-engine `evaluator.ErrAsMapTypeMismatch` sentinel.
+  ([#141](https://github.com/robbyt/go-polyscript/pull/141))
 
 ### Deprecated
 - The twelve legacy top-level constructors (`FromRisorFile`,
@@ -67,16 +65,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#103](https://github.com/robbyt/go-polyscript/pull/103))
 
 ### Removed
-- **Breaking:** Removed four exported mock types that pulled `testify/mock`
-  into the production dependency graph: `platform/script/loader.MockLoader`
-  (with `NewMockLoaderWithContent`), `platform/script.MockCompiler`,
-  `platform/script.MockExecutableContent`, and the entire `engines/mocks`
-  package (`Evaluator`, `EvaluatorResponse`). Consumers should copy these
-  small mock definitions inline into their own `_test.go` files. After this
-  change `go mod why github.com/stretchr/testify` reports `main module does
-  not need package github.com/stretchr/testify` — `testify` is only reached
-  via test binaries.
-  Closes [#88](https://github.com/robbyt/go-polyscript/issues/88).
+- **BREAKING**: Removed four exported mock types (`loader.MockLoader` with
+  `NewMockLoaderWithContent`, `script.MockCompiler`,
+  `script.MockExecutableContent`, and the entire `engines/mocks` package).
+  `testify` is no longer reachable from any production import path.
   ([#138](https://github.com/robbyt/go-polyscript/pull/138))
 - The redundant `cfg.handler != nil` guards in `polyscript.go` and
   `engines/{risor,starlark,extism}/new.go` that existed solely to work
@@ -93,10 +85,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#118](https://github.com/robbyt/go-polyscript/pull/118))
 
 ### Documentation
-- Documented the intentional divergence between Risor and Starlark in how a
-  callable-returning script is handled: Risor errors, Starlark auto-invokes.
-  Added a "Script Return Value Handling" section to `engines/README.md` and
-  brief rationale comments next to each evaluator's branch.
+- Documented the intentional Risor vs Starlark divergence for
+  callable-returning scripts: Risor errors, Starlark auto-invokes. New
+  "Script Return Value Handling" section in `engines/README.md`.
+  ([#140](https://github.com/robbyt/go-polyscript/pull/140))
 
 ### Fixed
 - `RequestToMap` no longer mutates the caller's `*http.Request`. The URL

engines/extism/evaluator/errors.go

@@ -0,0 +1,9 @@
+package evaluator
+
+import "errors"
+
+// ErrAsMapTypeMismatch is returned by (*execResult).AsMap when the underlying
+// value is not a map[string]any. Wrapped with the actual Go type via "%T", so
+// callers can use errors.Is(err, ErrAsMapTypeMismatch) and still read the
+// concrete type from err.Error().
+var ErrAsMapTypeMismatch = errors.New("extism: AsMap expected map[string]any")

engines/extism/evaluator/evaluator_test.go

@@ -188,8 +188,8 @@ func TestEvaluator_Evaluate(t *testing.T) {
 			require.NotNil(t, response)
 
 			// Verify the response
-			resultMap, ok := response.Interface().(map[string]any)
-			require.True(t, ok, "Expected map response")
+			resultMap, err := response.AsMap()
+			require.NoError(t, err, "Expected map response")
 			require.Contains(t, resultMap, "result")
 			require.Equal(t, "success", resultMap["result"])
 			require.Contains(t, resultMap, "value")

engines/extism/evaluator/response.go

@@ -39,7 +39,7 @@ func newEvalResult(
 func (r *execResult) String() string {
 	return fmt.Sprintf(
 		"execResult{Type: %s, Value: %v, ExecTime: %s, ScriptExeID: %s}",
-		r.Type(), r.value, r.GetExecTime(), r.GetScriptExeID(),
+		r.Type(), r.value, r.ExecTime(), r.ScriptExeID(),
 	)
 }
 
@@ -66,12 +66,20 @@ func (r *execResult) Type() data.Types {
 	}
 }
 
-func (r *execResult) GetScriptExeID() string {
+func (r *execResult) ScriptExeID() string {
 	return r.scriptExeID
 }
 
-func (r *execResult) GetExecTime() string {
-	return r.execTime.String()
+func (r *execResult) ExecTime() time.Duration {
+	return r.execTime
+}
+
+func (r *execResult) AsMap() (map[string]any, error) {
+	m, ok := r.value.(map[string]any)
+	if !ok {
+		return nil, fmt.Errorf("%w, got %T", ErrAsMapTypeMismatch, r.value)
+	}
+	return m, nil
 }
 
 func (r *execResult) Inspect() string {

engines/extism/evaluator/response_test.go

@@ -333,11 +333,11 @@ func TestResponseMethods(t *testing.T) {
 				handler := slog.NewTextHandler(os.Stdout, nil)
 				result := newEvalResult(handler, tt.value, tt.execTime, tt.versionID)
 
-				// Test GetScriptExeID
-				assert.Equal(t, tt.versionID, result.GetScriptExeID())
+				// Test ScriptExeID
+				assert.Equal(t, tt.versionID, result.ScriptExeID())
 
-				// Test GetExecTime
-				assert.Equal(t, tt.execTime.String(), result.GetExecTime())
+				// Test ExecTime
+				assert.Equal(t, tt.execTime, result.ExecTime())
 			})
 		}
 	})
@@ -387,3 +387,34 @@ func TestResponseMethods(t *testing.T) {
 		}
 	})
 }
+
+func TestExecResultAsMap(t *testing.T) {
+	t.Parallel()
+	handler := slog.NewTextHandler(os.Stdout, nil)
+
+	t.Run("success", func(t *testing.T) {
+		m := map[string]any{"k": "v", "n": 42}
+		result := newEvalResult(handler, m, time.Millisecond, "id-ok")
+		got, err := result.AsMap()
+		require.NoError(t, err)
+		assert.Equal(t, m, got)
+	})
+
+	t.Run("error on string", func(t *testing.T) {
+		result := newEvalResult(handler, "not a map", time.Millisecond, "id-bad")
+		got, err := result.AsMap()
+		require.Error(t, err)
+		assert.Nil(t, got)
+		require.ErrorIs(t, err, ErrAsMapTypeMismatch)
+		assert.Contains(t, err.Error(), "got string")
+	})
+
+	t.Run("error on nil", func(t *testing.T) {
+		result := newEvalResult(handler, nil, time.Millisecond, "id-nil")
+		got, err := result.AsMap()
+		require.Error(t, err)
+		assert.Nil(t, got)
+		require.ErrorIs(t, err, ErrAsMapTypeMismatch)
+		assert.Contains(t, err.Error(), "got <nil>")
+	})
+}

engines/extism/new_test.go

@@ -185,8 +185,8 @@ func TestFromExtismLoader_RunsEndToEnd(t *testing.T) {
 
 	res, err := eval.Eval(t.Context())
 	require.NoError(t, err)
-	got, ok := res.Interface().(map[string]any)
-	require.True(t, ok)
+	got, err := res.AsMap()
+	require.NoError(t, err)
 	assert.Equal(t, "Hello, World!", got["greeting"])
 }