@specific.dev/spectest 0.34.0 → 0.35.1

package/dist/components/aws.d.ts

@@ -101,7 +101,14 @@ export declare function aws(opts?: AwsOptions): {
     };
     env: {
         AWS_DEFAULT_REGION: string;
+        LAMBDA_EXECUTOR: string;
+        LAMBDA_STRICT: string;
+        LAMBDA_DOCKER_NETWORK: string;
     };
+    volumes: {
+        source: string;
+        target: string;
+    }[];
     ports: number[];
     readyCheck: {
         type: "http";

package/dist/components/aws.js

@@ -19,9 +19,37 @@
 // pinned rather than floated. It replaced LocalStack, which folded its
 // Apache-2.0 Community edition into one paid product in March 2026 (current
 // images demand a LOCALSTACK_AUTH_TOKEN). MiniStack also suits fork-per-test
-// far better: ~270 MB against ~1 GB, a ~2 s boot, and Lambda on an in-process
-// warm worker pool instead of sibling containers — so no docker socket is
-// bind-mounted and there is no host-architecture workaround on Graviton.
+// far better: ~270 MB against ~1 GB and a ~2 s boot.
+//
+// Lambda runs in MiniStack's **docker** executor, never its default `local`
+// one, because `local` has no runtime fidelity at all: it maps `python*` to
+// its own `sys.executable` and `nodejs*` to its own `node`, so the declared
+// `Runtime` selects only the language. A function declared `python3.11` runs
+// on the emulator image's CPython 3.13/musl, and one declared `nodejs20.x`
+// runs on Node 24 — which is why a native wheel built for the real target
+// fails to import ("No module named 'pydantic_core._pydantic_core'"). The
+// docker executor runs the handler under AWS's own Runtime Interface
+// Emulator in `public.ecr.aws/lambda/<runtime>`, giving the real
+// interpreter, glibc, `/var/task` and `AWS_EXECUTION_ENV`. Measured on
+// aarch64: it is also ~7x FASTER per warm invoke (7 ms against 53 ms) at
+// ~25-40 MiB per function container.
+//
+// None of this is configurable, on purpose — a knob here is a knob between
+// "behaves like AWS" and "does not".
+//
+// The cost is a bind-mount of the VM's own docker socket, which the daemon
+// already supports (`ensureVolumes` treats an existing non-directory source
+// as a thing to mount as-is). The RIE containers are ordinary VM containers
+// on `spectest-net`, so they ride snapshots and forks like any service: a
+// per-test fork inherits its parent's already-warm function.
+//
+// Landmine: the runtime images are pulled from `public.ecr.aws`, which the
+// in-VM dockerd reaches DIRECTLY. Its `registry-mirrors` only ever applies
+// to Docker Hub, so the zot mirror (which does carry public.ecr.aws, on
+// :5004) is NOT consulted. MiniStack's own `MINISTACK_IMAGE_PREFIX` cannot
+// close that gap either: it prepends rather than replacing the registry
+// host. Routing these pulls through zot needs a pre-pull of
+// `spectest-host:5004/lambda/<rt>` retagged to the `public.ecr.aws` name.
 //
 // Like `email()`'s mail server, the product name stays out of every
 // user-facing surface (docs, examples, error messages). Users get "the AWS
@@ -73,6 +101,13 @@ const AWS_HOST_PATTERNS = [
     "*.amazonaws.com.cn",
     ...AWS_CN_REGIONS.map((r) => `*.${r}.amazonaws.com.cn`),
 ];
+/** The VM's own docker socket, bind-mounted so the emulator can start the
+ *  official AWS runtime containers. This is the VM's dockerd, inside the
+ *  hermetic environment — the same daemon that runs the services. */
+const DOCKER_SOCKET = "/var/run/docker.sock";
+/** The network the function containers join, so a handler reaches the other
+ *  services and the AWS endpoints by the same names a test uses. */
+const SPECTEST_NETWORK = "spectest-net";
 /** Region the emulator's own tools default to — the AWS CLI refuses to run
  *  without one. Only the *container's* default; it constrains nothing about
  *  the app, and every region is served regardless. A `setup` hook that drives
@@ -144,7 +179,18 @@ export function aws(opts = {}) {
     const lambdas = opts.lambdas ?? {};
     const service = {
         image: { type: "registry", reference: AWS_IMAGE },
-        env: { AWS_DEFAULT_REGION: CONTAINER_DEFAULT_REGION },
+        env: {
+            AWS_DEFAULT_REGION: CONTAINER_DEFAULT_REGION,
+            // Run every function in the official AWS runtime image rather than in
+            // the emulator's own interpreter — see the note at the top of the file.
+            LAMBDA_EXECUTOR: "docker",
+            // No silent fall-back to the low-fidelity executor. If the runtime
+            // container cannot start, say so instead of running the handler on the
+            // wrong interpreter and failing later, somewhere else.
+            LAMBDA_STRICT: "1",
+            LAMBDA_DOCKER_NETWORK: SPECTEST_NETWORK,
+        },
+        volumes: [{ source: DOCKER_SOCKET, target: DOCKER_SOCKET }],
         ports: [AWS_PORT],
         readyCheck: {
             type: "http",
@@ -226,9 +272,10 @@ async function deployLambda(service, projectRoot, name, spec) {
         Handler: spec.handler ?? "index.handler",
         Role: spec.role ?? DEFAULT_ROLE_ARN,
         Timeout: spec.timeoutSecs ?? 30,
-        // Fixed, and not an option: the emulated cloud runs handlers in a shared
-        // worker pool rather than a memory-capped sandbox, so the number changes
-        // nothing about how a function behaves here.
+        // Fixed, and not an option: the emulated cloud reports this number back
+        // as `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` but never caps the runtime
+        // container at it, so the number changes nothing about how a function
+        // behaves here.
         MemorySize: MEMORY_MB,
         ...(spec.env ? { Environment: { Variables: spec.env } } : {}),
     };

package/dist/index.d.ts

@@ -1390,16 +1390,43 @@ export declare function expect(actual: Locator, message?: string): LocatorAssert
 export declare function expect(actual: Browser, message?: string): BrowserAssertion;
 export declare function expect(actual: Provenanced, message?: string): Expectation;
 /**
- * Assert on a value with **no provenance** — a computed number, a raw
- * WebSocket frame, anything that didn't flow from a recorded op. `message` is
- * required (it's the second argument) and reads as the natural follow-on to
- * "assert …" (e.g. `expectRaw(id, "id matches the generated value")`); it
- * renders as the assertion's label in the CLI/dashboard ("ASSERT <message>")
- * since a raw assertion has no op to nest under. Prefer `expect(...)` whenever
- * the value carries provenance — only reach for this when the type gate would
- * (rightly) reject the value. (`expect`'s own `message` is optional; here it is
- * mandatory, since the label is the only human-meaningful summary a raw
- * assertion has.)
+ * Assert on a value with **no provenance** — a computed number, a frame read
+ * off a raw `WebSocket` you opened yourself, anything that never flowed from a
+ * recorded op. `message` is required (it's the second argument) and reads as
+ * the natural follow-on to "assert …" (e.g.
+ * `expectRaw(id, "id matches the generated value")`); it renders as the
+ * assertion's label in the CLI/dashboard ("ASSERT <message>") since a raw
+ * assertion has no op to nest under. (`expect`'s own `message` is optional;
+ * here it is mandatory, since the label is the only human-meaningful summary a
+ * raw assertion has.)
+ *
+ * **This is an escape hatch, and reaching for it is almost always a mistake.**
+ * A raw assertion is *deliberately* unlinked: it renders as a disconnected
+ * top-level row with no op above it, so whoever reads the failure can't see the
+ * request, query, or command the value came from. Using it to get past
+ * `expect`'s compile-time provenance gate is an anti-pattern — the gate rejects
+ * a value precisely because its provenance was destroyed on the way in, and
+ * this doesn't restore it, it just accepts the loss.
+ *
+ * Nearly every real use is a *wrapped* value that got flattened by `.unwrap()`,
+ * `String(x)`, `JSON.parse(x)`, `x.length`, or a home-grown coercion helper.
+ * Keep it wrapped instead:
+ *
+ * ```ts
+ * // ✗ flattened, then asserted raw — the link to the op is gone
+ * expectRaw(JSON.parse(res.body.unwrap()).tier, "tier is pro").toBe("pro");
+ * expectRaw(rows.length, "one row").toBe(1);
+ *
+ * // ✓ same checks, still nested under the http / db step
+ * expect(res.body.transform<{ tier: string }>("json", (s) => JSON.parse(s)).tier).toBe("pro");
+ * expect(rows).toHaveLength(1);
+ * ```
+ *
+ * `.transform(label, fn)` carries the source op's tag through a decode,
+ * `toHaveLength` reads a length without severing it, and a nullish leaf read
+ * inline in `expect(...)` (or via `field`) recovers its own tag. If the value
+ * came from a `fetch`/db/exec/browser/fake/kube op at any point, there is a
+ * wrapped way to assert on it — see the `/tests` docs page.
  */
 export declare function expectRaw(actual: unknown, message: string): Expectation;
 /** `node:assert/strict` re-exported for users who prefer Node's built-in API. */

package/dist/index.js

@@ -657,16 +657,43 @@ function buildBrowserMatchers(session, negated, message) {
     };
 }
 /**
- * Assert on a value with **no provenance** — a computed number, a raw
- * WebSocket frame, anything that didn't flow from a recorded op. `message` is
- * required (it's the second argument) and reads as the natural follow-on to
- * "assert …" (e.g. `expectRaw(id, "id matches the generated value")`); it
- * renders as the assertion's label in the CLI/dashboard ("ASSERT <message>")
- * since a raw assertion has no op to nest under. Prefer `expect(...)` whenever
- * the value carries provenance — only reach for this when the type gate would
- * (rightly) reject the value. (`expect`'s own `message` is optional; here it is
- * mandatory, since the label is the only human-meaningful summary a raw
- * assertion has.)
+ * Assert on a value with **no provenance** — a computed number, a frame read
+ * off a raw `WebSocket` you opened yourself, anything that never flowed from a
+ * recorded op. `message` is required (it's the second argument) and reads as
+ * the natural follow-on to "assert …" (e.g.
+ * `expectRaw(id, "id matches the generated value")`); it renders as the
+ * assertion's label in the CLI/dashboard ("ASSERT <message>") since a raw
+ * assertion has no op to nest under. (`expect`'s own `message` is optional;
+ * here it is mandatory, since the label is the only human-meaningful summary a
+ * raw assertion has.)
+ *
+ * **This is an escape hatch, and reaching for it is almost always a mistake.**
+ * A raw assertion is *deliberately* unlinked: it renders as a disconnected
+ * top-level row with no op above it, so whoever reads the failure can't see the
+ * request, query, or command the value came from. Using it to get past
+ * `expect`'s compile-time provenance gate is an anti-pattern — the gate rejects
+ * a value precisely because its provenance was destroyed on the way in, and
+ * this doesn't restore it, it just accepts the loss.
+ *
+ * Nearly every real use is a *wrapped* value that got flattened by `.unwrap()`,
+ * `String(x)`, `JSON.parse(x)`, `x.length`, or a home-grown coercion helper.
+ * Keep it wrapped instead:
+ *
+ * ```ts
+ * // ✗ flattened, then asserted raw — the link to the op is gone
+ * expectRaw(JSON.parse(res.body.unwrap()).tier, "tier is pro").toBe("pro");
+ * expectRaw(rows.length, "one row").toBe(1);
+ *
+ * // ✓ same checks, still nested under the http / db step
+ * expect(res.body.transform<{ tier: string }>("json", (s) => JSON.parse(s)).tier).toBe("pro");
+ * expect(rows).toHaveLength(1);
+ * ```
+ *
+ * `.transform(label, fn)` carries the source op's tag through a decode,
+ * `toHaveLength` reads a length without severing it, and a nullish leaf read
+ * inline in `expect(...)` (or via `field`) recovers its own tag. If the value
+ * came from a `fetch`/db/exec/browser/fake/kube op at any point, there is a
+ * wrapped way to assert on it — see the `/tests` docs page.
  */
 export function expectRaw(actual, message) {
     // Force the raw form so no stray tag is read even if a wrapped value is

package/dist/inspect.d.ts

@@ -106,8 +106,14 @@ export interface Carrier<T> {
  * `null`/`undefined` are also admitted: a nullish leaf can't carry the symbol
  * tag, but `adoptNullishTag` recovers its provenance at runtime, so
  * `expect(rows[0]?.text)` and `expect(dep.status.readyReplicas)` stay on
- * `expect`. To assert on a value with no provenance (a computed number, a raw
- * WebSocket frame), use `expectRaw(value, message)` instead.
+ * `expect`.
+ *
+ * When this gate rejects a value, the fix is usually to stop flattening it —
+ * `.transform(label, fn)` instead of a decode-then-`.unwrap()`, `toHaveLength`
+ * instead of `.length` — not to switch to `expectRaw`, which accepts anything
+ * but renders the assertion unlinked. Reach for `expectRaw(value, message)`
+ * only when the value never flowed from a recorded op at all (a computed
+ * number, a frame off a raw WebSocket); see its own doc comment.
  */
 export type Provenanced = {
     unwrap(): unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.34.0",
+  "version": "0.35.1",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",