@ripplo/testing 0.4.1 → 0.4.3

package/README.md

@@ -75,7 +75,7 @@ export const dataProject = precondition("data:project")
 export const preconditions = { authLoggedIn, dataProject };
 ```
 
-`precondition(name)` → `.description()` → `.requires()` (optional) → `.contract<T>()`. Each field in `T` must be a `string` (run-scoped value).
+`precondition(name)` → `.description()` → `.requires()` (optional) → `.contract<T>()`. Each field in `T` must be a primitive — `string`, `number`, or `boolean` (run-scoped value).
 
 ### Observers
 
@@ -91,6 +91,25 @@ export const orgNameIs = observer("org:name-is")
 export const observers = { orgNameIs };
 ```
 
+Observer `.input<T>()` and precondition `.contract<T>()` fields can be any primitive — `string`, `number`, or `boolean`. Model each field as the type it actually is; no stringification at the boundary.
+
+```typescript
+export const orgOverageCapIs = observer("org:overage-cap-is")
+  .description("Org has the given overageCapCents")
+  .budget("fast")
+  .input<{ orgId: string; expectedCapCents: number }>()
+  .contract();
+
+export const orgHasLogo = observer("org:has-logo")
+  .description("Organization logo is set / unset")
+  .budget("fast")
+  .input<{ orgId: string; expectLogo: boolean }>()
+  .contract();
+
+assert.backend(orgOverageCapIs, { orgId: project.orgId, expectedCapCents: 2500 });
+assert.backend(orgHasLogo, { orgId: project.orgId, expectLogo: true });
+```
+
 **Budget tiers** (poll behavior, not numeric timeouts):
 
 | Tier    | Window | Backoff    | Use for                            |
@@ -275,11 +294,13 @@ export const engine = createEngine(ripplo, {
 `ctx` passed to each precondition `setup`:
 
 - `ctx.runId` — unique 12-char id for this run
-- `ctx.fixed(value)` — static test value
+- `ctx.fixed<T extends string | number | boolean>(value: T)` — static test value (any primitive)
 - `ctx.uniqueId(prefix)` — `ripplo-test-<prefix>-<runId>`
 - `ctx.uniqueEmail()` — `ripplo-test-<runId>@test.ripplo.ai`
 - `ctx.setCookie(name, value, options?)` — forwarded to the test browser as `Set-Cookie`
 
+Helpers return plain primitives — interpolate, JSON.stringify, or pass through observer params directly. The return type is type-branded, so a hardcoded literal in a `setup` return fails at compile time.
+
 ### Observer context
 
 - `ctx.pass()` — assertion satisfied; stop polling.
@@ -470,7 +491,7 @@ The CLI lives in [`ripplo`](https://www.npmjs.com/package/ripplo). Most-used com
 ```bash
 ripplo auth login       # authenticate
 ripplo init             # scaffold .ripplo/ + write env vars
-ripplo watch            # local executor — wire into your dev script
+ripplo watch            # local executor — run as a standalone background process
 ripplo lint [ids..]     # compile + lint
 ripplo run [ids..]      # run tests in parallel
 ```

package/dist/assert.d.ts

@@ -1,4 +1,4 @@
-import { O as ObserverHandle, a as ObserverInput, b as ObserverBudgetTier } from './types-B7YljrTz.js';
+import { O as ObserverHandle, a as ObserverInput, P as Primitive, b as ObserverBudgetTier } from './types-2i1Sm7_J.js';
 import { Variable, StaticStringRef, VariableRef } from './control.js';
 import { U as UnlabeledStep } from './step-De52hTLd.js';
 import { CheckLocator, AnyLocator } from './locators.js';
@@ -72,12 +72,12 @@ declare const assert: {
      * polling) and `ctx.fail(reason)` only for invariant violations (stop
      * early). The observer's `.budget()` governs poll interval and timeout.
      */
-    backend<THandle extends ObserverHandle>(observer: THandle, params: ObserverInput<THandle> & Record<string, string>): UnlabeledStep<{
+    backend<THandle extends ObserverHandle>(observer: THandle, params: ObserverInput<THandle> & Record<string, Primitive>): UnlabeledStep<{
         budget: ObserverBudgetTier;
         observer: string;
         params: Record<string, {
             readonly type: "static";
-            readonly value: string;
+            readonly value: Primitive;
         }>;
         type: "assertObserver";
     }>;

package/dist/assert.js

@@ -1,7 +1,7 @@
 import {
   readObserverBudget,
   readObserverName
-} from "./chunk-SBZJDJP4.js";
+} from "./chunk-YQAEOH5W.js";
 import {
   toSpecLocator,
   toStringValueRef
@@ -48,7 +48,7 @@ var assert = {
     return createStep({
       budget: readObserverBudget(observer),
       observer: readObserverName(observer),
-      params: paramsToStringRefs(params),
+      params: paramsToValueRefs(params),
       type: "assertObserver"
     });
   },
@@ -99,7 +99,7 @@ var assert = {
     return createStep({ locator: toSpecLocator(locator), type: "assertVisible" });
   }
 };
-function paramsToStringRefs(params) {
+function paramsToValueRefs(params) {
   const out = {};
   Object.entries(params).forEach(([key, value]) => {
     out[key] = { type: "static", value };

package/dist/{builder-0oT23S0W.d.ts → builder-mhjAdyNW.d.ts}

@@ -1,4 +1,4 @@
-import { O as ObserverHandle, P as Precondition, k as PreconditionData, i as TestDefinition, f as ObserverDefinition, j as PreconditionDefinition, U as UnimplementedItems, e as ObserverContext, g as ObserverOutcome, S as SetupContext, l as TestValue, T as TeardownContext } from './types-B7YljrTz.js';
+import { P as Primitive, O as ObserverHandle, h as Precondition, m as PreconditionData, j as TestDefinition, f as ObserverDefinition, l as PreconditionDefinition, U as UnimplementedItems, e as ObserverContext, g as ObserverOutcome, S as SetupContext, k as TestValue, T as TeardownContext } from './types-2i1Sm7_J.js';
 import { ObserverBudget } from '@ripplo/spec';
 import { S as Step } from './step-De52hTLd.js';
 
@@ -15,9 +15,9 @@ interface ObserverNeedsBudget {
     readonly budget: (tier: ObserverBudget) => ObserverNeedsInput;
 }
 interface ObserverNeedsInput {
-    readonly input: <TInput extends Record<string, string>>() => ObserverReady<TInput>;
+    readonly input: <TInput extends Record<string, Primitive>>() => ObserverReady<TInput>;
 }
-interface ObserverReady<TInput extends Record<string, string>> {
+interface ObserverReady<TInput extends Record<string, Primitive>> {
     readonly contract: () => ObserverHandle<TInput>;
 }
 
@@ -31,12 +31,12 @@ type ResolveDeps<TDeps extends PreconditionRecord> = {
     readonly [K in keyof TDeps]: PreconditionData<TDeps[K]>;
 };
 interface PreconditionNeedsSetup {
-    readonly contract: <TData extends Record<string, string>>() => Precondition<TData>;
+    readonly contract: <TData extends Record<string, Primitive>>() => Precondition<TData>;
     readonly description: (text: string) => PreconditionNeedsSetup;
     readonly requires: <TDeps extends PreconditionRecord>(deps: TDeps) => PreconditionNeedsSetupWithDeps<TDeps>;
 }
 interface PreconditionNeedsSetupWithDeps<TDeps extends PreconditionRecord> {
-    readonly contract: <TData extends Record<string, string>>() => Precondition<TData, ResolveDeps<TDeps>>;
+    readonly contract: <TData extends Record<string, Primitive>>() => Precondition<TData, ResolveDeps<TDeps>>;
 }
 interface TestNeedsName {
     readonly name: (displayName: string) => TestNeedsRequires;
@@ -52,11 +52,11 @@ interface TestNeedsRequires {
      */
     readonly requires: <TReqs extends PreconditionRecord>(reqs: TReqs) => TestNeedsOutcome<ResolveDeps<TReqs>>;
 }
-interface TestNeedsOutcome<TVars extends Record<string, Record<string, string>>> {
+interface TestNeedsOutcome<TVars extends Record<string, Record<string, Primitive>>> {
     readonly expectedOutcome: (text: string) => TestNeedsStartsAt<TVars>;
 }
 
-interface TestNeedsStartsAt<TVars extends Record<string, Record<string, string>>> {
+interface TestNeedsStartsAt<TVars extends Record<string, Record<string, Primitive>>> {
     /**
      * Skip implementation — compiles as a planning stub and is reported in
      * `getUnimplemented()`. The test appears in the lockfile but is not run.
@@ -69,7 +69,7 @@ interface TestNeedsStartsAt<TVars extends Record<string, Record<string, string>>
      */
     readonly startsAt: (fn: (vars: TVars) => string) => TestNeedsSteps<TVars>;
 }
-interface TestNeedsSteps<TVars extends Record<string, Record<string, string>>> {
+interface TestNeedsSteps<TVars extends Record<string, Record<string, Primitive>>> {
     /**
      * Declare the ordered step list. Receives destructured precondition data as
      * typed proxies (same as `.startsAt`). Every step must be labeled with
@@ -87,19 +87,19 @@ interface TestNeedsCoverage {
     readonly coverage: (...ids: ReadonlyArray<CoverageStatementId>) => TestDefinition;
 }
 
-type PreconditionSetupResult<TData extends Record<string, string>> = {
-    readonly [K in keyof TData]: TestValue;
+type PreconditionSetupResult<TData extends Record<string, Primitive>> = {
+    readonly [K in keyof TData]: TestValue<TData[K]>;
 };
-interface PreconditionImpl<TData extends Record<string, string>, TDeps extends Record<string, Record<string, string>>> {
+interface PreconditionImpl<TData extends Record<string, Primitive>, TDeps extends Record<string, Record<string, Primitive>>> {
     readonly setup: (ctx: SetupContext, deps: TDeps) => Promise<PreconditionSetupResult<TData>>;
     readonly teardown: (ctx: TeardownContext<TData>) => Promise<void>;
 }
-type ObserverImplFn<TInput extends Record<string, string>> = (ctx: ObserverContext, params: TInput) => Promise<ObserverOutcome>;
+type ObserverImplFn<TInput extends Record<string, Primitive>> = (ctx: ObserverContext, params: TInput) => Promise<ObserverOutcome>;
 interface TestOptions {
     readonly uiOnly?: boolean;
 }
 type PreconditionRegistry = Record<string, Precondition>;
-type ObserverRegistry = Record<string, ObserverHandle<Record<string, string>>>;
+type ObserverRegistry = Record<string, ObserverHandle<Record<string, Primitive>>>;
 interface RipploRegistries<P extends PreconditionRegistry, O extends ObserverRegistry> {
     readonly observers: O;
     readonly preconditions: P;

package/dist/{chunk-UFHSNW4E.js → chunk-EHAZBEHO.js}

@@ -19,7 +19,7 @@ var teardownRequestSchema = z.object({
 });
 var observerRequestSchema = z.object({
   observer: z.string().min(1).max(200),
-  params: z.record(z.string().max(200), z.string())
+  params: z.record(z.string().max(200), z.union([z.string(), z.number(), z.boolean()]))
 });
 var observerOutcomeSchema = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("pass") }),

package/dist/{chunk-SBZJDJP4.js → chunk-YQAEOH5W.js}

@@ -59,11 +59,12 @@ var DEFAULT_IGNORE_PATHS = [
   "**/prisma/migrations/**",
   "**/scripts/**"
 ];
-function readTestValue(value) {
-  return value.value;
+function brandTestValue(value) {
+  return value;
 }
-function createTestValue(value) {
-  return { value };
+function isPrimitive(value) {
+  const t = typeof value;
+  return t === "string" || t === "number" || t === "boolean";
 }
 function readPreconditionName(p) {
   return p.name;
@@ -97,8 +98,8 @@ function makeObserverHandle({
 export {
   DEFAULT_WATCH_PATHS,
   DEFAULT_IGNORE_PATHS,
-  readTestValue,
-  createTestValue,
+  brandTestValue,
+  isPrimitive,
   readPreconditionName,
   readPreconditionDescription,
   readPreconditionDependsOn,

package/dist/compiler.d.ts

@@ -1,6 +1,6 @@
 import { Observer, Precondition, WorkflowSpec } from '@ripplo/spec';
-import { d as RipploBuilder } from './builder-0oT23S0W.js';
-import './types-B7YljrTz.js';
+import { d as RipploBuilder } from './builder-mhjAdyNW.js';
+import './types-2i1Sm7_J.js';
 import './step-De52hTLd.js';
 
 interface CompileResult {

package/dist/elysia.d.ts

@@ -1,7 +1,7 @@
 import { Elysia } from 'elysia';
-import { R as RipploEngine } from './engine-BdKDGBYw.js';
-import './builder-0oT23S0W.js';
-import './types-B7YljrTz.js';
+import { R as RipploEngine } from './engine-B6MM4AEw.js';
+import './builder-mhjAdyNW.js';
+import './types-2i1Sm7_J.js';
 import './step-De52hTLd.js';
 import '@ripplo/spec';
 

package/dist/elysia.js

@@ -6,7 +6,7 @@ import {
   serializeCookie,
   teardownRequestSchema,
   verifyWebhookSignature
-} from "./chunk-UFHSNW4E.js";
+} from "./chunk-EHAZBEHO.js";
 import "./chunk-4MGIQFAJ.js";
 
 // src/adapters/elysia.ts

package/dist/{engine-BdKDGBYw.d.ts → engine-B6MM4AEw.d.ts}

@@ -1,9 +1,9 @@
-import { c as PreconditionRegistry, a as ObserverRegistry, O as ObserverImplFn, P as PreconditionImpl, e as RipploInstance } from './builder-0oT23S0W.js';
-import { g as ObserverOutcome, C as CookieEntry, f as ObserverDefinition, j as PreconditionDefinition, U as UnimplementedItems, O as ObserverHandle, P as Precondition } from './types-B7YljrTz.js';
+import { c as PreconditionRegistry, a as ObserverRegistry, O as ObserverImplFn, P as PreconditionImpl, e as RipploInstance } from './builder-mhjAdyNW.js';
+import { P as Primitive, g as ObserverOutcome, C as CookieEntry, f as ObserverDefinition, l as PreconditionDefinition, U as UnimplementedItems, O as ObserverHandle, h as Precondition } from './types-2i1Sm7_J.js';
 
 interface EngineResult {
     readonly cookies: ReadonlyArray<CookieEntry>;
-    readonly data: Record<string, Record<string, string>>;
+    readonly data: Record<string, Record<string, Primitive>>;
     readonly error: string | undefined;
     readonly executed: ReadonlyArray<string>;
     readonly runId: string;
@@ -18,12 +18,12 @@ interface ObserverExecutionResult {
     readonly success: boolean;
 }
 interface RipploEngine {
-    readonly executeObserver: (name: string, params: Record<string, string>) => Promise<ObserverExecutionResult>;
+    readonly executeObserver: (name: string, params: Record<string, Primitive>) => Promise<ObserverExecutionResult>;
     readonly executePreconditions: (names: ReadonlyArray<string>, options?: ExecuteBatchOptions) => Promise<EngineResult>;
     readonly getObservers: () => ReadonlyArray<ObserverDefinition>;
     readonly getPreconditions: () => ReadonlyArray<PreconditionDefinition>;
     readonly getUnimplemented: () => UnimplementedItems;
-    readonly teardown: (names: ReadonlyArray<string>, data: Record<string, Record<string, string>>) => Promise<void>;
+    readonly teardown: (names: ReadonlyArray<string>, data: Record<string, Record<string, Primitive>>) => Promise<void>;
 }
 declare const NOT_IMPLEMENTED_BRAND: unique symbol;
 interface NotImplemented {
@@ -32,7 +32,7 @@ interface NotImplemented {
 }
 declare function notImplemented(reason?: string): NotImplemented;
 type PreconditionImplFor<P> = P extends Precondition<infer TData, infer TDeps> ? PreconditionImpl<TData, TDeps> : never;
-type ObserverImplFnFor<O> = O extends ObserverHandle<infer TInput> ? TInput extends Record<string, string> ? ObserverImplFn<TInput> : never : never;
+type ObserverImplFnFor<O> = O extends ObserverHandle<infer TInput> ? TInput extends Record<string, Primitive> ? ObserverImplFn<TInput> : never : never;
 interface EngineImpls<P extends PreconditionRegistry, O extends ObserverRegistry> {
     readonly observers: {
         readonly [K in keyof O]: NotImplemented | ObserverImplFnFor<O[K]>;

package/dist/express.d.ts

@@ -1,7 +1,7 @@
 import { Router } from 'express';
-import { R as RipploEngine } from './engine-BdKDGBYw.js';
-import './builder-0oT23S0W.js';
-import './types-B7YljrTz.js';
+import { R as RipploEngine } from './engine-B6MM4AEw.js';
+import './builder-mhjAdyNW.js';
+import './types-2i1Sm7_J.js';
 import './step-De52hTLd.js';
 import '@ripplo/spec';
 

package/dist/express.js

@@ -5,7 +5,7 @@ import {
   serializeCookie,
   teardownRequestSchema,
   verifyWebhookSignature
-} from "./chunk-UFHSNW4E.js";
+} from "./chunk-EHAZBEHO.js";
 import "./chunk-4MGIQFAJ.js";
 
 // src/adapters/express.ts

package/dist/fastify.d.ts

@@ -1,7 +1,7 @@
 import { FastifyInstance } from 'fastify';
-import { R as RipploEngine } from './engine-BdKDGBYw.js';
-import './builder-0oT23S0W.js';
-import './types-B7YljrTz.js';
+import { R as RipploEngine } from './engine-B6MM4AEw.js';
+import './builder-mhjAdyNW.js';
+import './types-2i1Sm7_J.js';
 import './step-De52hTLd.js';
 import '@ripplo/spec';
 

package/dist/fastify.js

@@ -6,7 +6,7 @@ import {
   serializeCookie,
   teardownRequestSchema,
   verifyWebhookSignature
-} from "./chunk-UFHSNW4E.js";
+} from "./chunk-EHAZBEHO.js";
 import "./chunk-4MGIQFAJ.js";
 
 // src/adapters/fastify.ts

package/dist/hono.d.ts

@@ -1,7 +1,7 @@
 import { Hono } from 'hono';
-import { R as RipploEngine } from './engine-BdKDGBYw.js';
-import './builder-0oT23S0W.js';
-import './types-B7YljrTz.js';
+import { R as RipploEngine } from './engine-B6MM4AEw.js';
+import './builder-mhjAdyNW.js';
+import './types-2i1Sm7_J.js';
 import './step-De52hTLd.js';
 import '@ripplo/spec';
 

package/dist/hono.js

@@ -6,7 +6,7 @@ import {
   serializeCookie,
   teardownRequestSchema,
   verifyWebhookSignature
-} from "./chunk-UFHSNW4E.js";
+} from "./chunk-EHAZBEHO.js";
 import "./chunk-4MGIQFAJ.js";
 
 // src/adapters/hono.ts

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-export { C as CoverageRegistry, O as ObserverImplFn, a as ObserverRegistry, P as PreconditionImpl, b as PreconditionRecord, c as PreconditionRegistry, R as ResolveDeps, d as RipploBuilder, e as RipploInstance, f as RipploRegistries, g as createRipplo, o as observer, p as precondition, t as test } from './builder-0oT23S0W.js';
+export { C as CoverageRegistry, O as ObserverImplFn, a as ObserverRegistry, P as PreconditionImpl, b as PreconditionRecord, c as PreconditionRegistry, R as ResolveDeps, d as RipploBuilder, e as RipploInstance, f as RipploRegistries, g as createRipplo, o as observer, p as precondition, t as test } from './builder-mhjAdyNW.js';
 import { CompileResult } from './compiler.js';
 export { CompiledTest, compile } from './compiler.js';
-export { E as EngineImpls, a as EngineResult, b as ExecuteBatchOptions, N as NotImplemented, O as ObserverImplFnFor, P as PreconditionImplFor, R as RipploEngine, c as createEngine, n as notImplemented } from './engine-BdKDGBYw.js';
-import { C as CookieEntry } from './types-B7YljrTz.js';
-export { c as CookieOptions, D as DEFAULT_IGNORE_PATHS, d as DEFAULT_WATCH_PATHS, e as ObserverContext, f as ObserverDefinition, O as ObserverHandle, a as ObserverInput, g as ObserverOutcome, P as Precondition, h as PreconditionDeps, S as SetupContext, T as TeardownContext, i as TestDefinition } from './types-B7YljrTz.js';
+export { E as EngineImpls, a as EngineResult, b as ExecuteBatchOptions, N as NotImplemented, O as ObserverImplFnFor, P as PreconditionImplFor, R as RipploEngine, c as createEngine, n as notImplemented } from './engine-B6MM4AEw.js';
+import { C as CookieEntry } from './types-2i1Sm7_J.js';
+export { c as CookieOptions, D as DEFAULT_IGNORE_PATHS, d as DEFAULT_WATCH_PATHS, e as ObserverContext, f as ObserverDefinition, O as ObserverHandle, a as ObserverInput, g as ObserverOutcome, h as Precondition, i as PreconditionDeps, P as Primitive, S as SetupContext, T as TeardownContext, j as TestDefinition, k as TestValue } from './types-2i1Sm7_J.js';
 export { D as DslNodeInput } from './step-De52hTLd.js';
 import '@ripplo/spec';
 

package/dist/index.js

@@ -1,7 +1,8 @@
 import {
   DEFAULT_IGNORE_PATHS,
   DEFAULT_WATCH_PATHS,
-  createTestValue,
+  brandTestValue,
+  isPrimitive,
   makeObserverHandle,
   readObserverBudget,
   readObserverDescription,
@@ -9,9 +10,8 @@ import {
   readPreconditionDepMapping,
   readPreconditionDependsOn,
   readPreconditionDescription,
-  readPreconditionName,
-  readTestValue
-} from "./chunk-SBZJDJP4.js";
+  readPreconditionName
+} from "./chunk-YQAEOH5W.js";
 import {
   compile
 } from "./chunk-GWSEDWEF.js";
@@ -20,9 +20,52 @@ import {
   buildSetCookieHeader,
   serializeCookie,
   verifyWebhookSignature
-} from "./chunk-UFHSNW4E.js";
+} from "./chunk-EHAZBEHO.js";
 import "./chunk-4MGIQFAJ.js";
 
+// src/chainable.ts
+var BuilderChainError = class _BuilderChainError extends Error {
+  missingMethod;
+  validNext;
+  constructor(missingMethod, validNext) {
+    const valid = validNext.length === 0 ? "<chain is terminal>" : validNext.map((m) => `.${m}`).join(", ");
+    super(`\`.${missingMethod}\` is not a valid step in this builder chain. Valid next: ${valid}.`);
+    this.name = "BuilderChainError";
+    this.missingMethod = missingMethod;
+    this.validNext = validNext;
+    if (typeof Error.captureStackTrace === "function") {
+      Error.captureStackTrace(this, _BuilderChainError);
+    }
+  }
+};
+var PASSTHROUGH_PROPS = /* @__PURE__ */ new Set([
+  "then",
+  "catch",
+  "finally",
+  "toJSON",
+  "toString",
+  "valueOf",
+  "constructor",
+  "nodeType"
+]);
+function chainable(target) {
+  return new Proxy(target, {
+    get(t, prop, receiver) {
+      if (Reflect.has(t, prop)) {
+        return Reflect.get(t, prop, receiver);
+      }
+      if (typeof prop === "symbol") {
+        return void 0;
+      }
+      if (PASSTHROUGH_PROPS.has(prop)) {
+        return void 0;
+      }
+      const validNext = Object.keys(t).filter((k) => typeof Reflect.get(t, k) === "function");
+      throw new BuilderChainError(prop, validNext);
+    }
+  });
+}
+
 // src/observer.ts
 function createPassOutcome() {
   return { kind: "pass" };
@@ -34,21 +77,21 @@ function createFailOutcome(reason) {
   return { kind: "fail", reason };
 }
 function buildReady(state) {
-  return {
+  return chainable({
     contract: () => makeObserverHandle(state)
-  };
+  });
 }
 function buildNeedsInput(state) {
-  return {
+  return chainable({
     input: () => buildReady(state)
-  };
+  });
 }
 function buildObserver(name) {
-  return {
-    description: (description) => ({
+  return chainable({
+    description: (description) => chainable({
       budget: (budget) => buildNeedsInput({ budget, description, name })
     })
-  };
+  });
 }
 
 // src/builder.ts
@@ -146,7 +189,7 @@ function buildDepMapping(deps) {
 }
 function buildPreconditionStart(name) {
   let description = "";
-  const self = {
+  const self = chainable({
     contract: () => makePrecondition({
       dependsOn: [],
       depMapping: [],
@@ -160,7 +203,7 @@ function buildPreconditionStart(name) {
     requires(deps) {
       return buildPreconditionWithDeps({ deps, name, getDescription: () => description });
     }
-  };
+  });
   return self;
 }
 function buildPreconditionWithDeps({
@@ -171,26 +214,26 @@ function buildPreconditionWithDeps({
   const description = getDescription();
   const depMapping = buildDepMapping(deps);
   const dependsOn = depMapping.map(([, depName]) => depName);
-  return {
+  return chainable({
     contract: () => makePrecondition({
       dependsOn,
       depMapping,
       description,
       name
     })
-  };
+  });
 }
 function buildTestName(id, uiOnly) {
-  return {
+  return chainable({
     name: (displayName) => buildTestRequires({ id, name: displayName, uiOnly })
-  };
+  });
 }
 function castOutcome(value) {
   return value;
 }
 function buildTestRequires({ id, name, uiOnly }) {
   let description = "";
-  const self = {
+  const self = chainable({
     description(text) {
       description = text;
       return self;
@@ -212,7 +255,7 @@ function buildTestRequires({ id, name, uiOnly }) {
         })
       );
     }
-  };
+  });
   return self;
 }
 function buildTestOutcome({
@@ -224,7 +267,7 @@ function buildTestOutcome({
   uiOnly
 }) {
   const description = getDescription();
-  return {
+  return chainable({
     expectedOutcome(text) {
       return buildTestStartsAt({
         description,
@@ -236,7 +279,7 @@ function buildTestOutcome({
         uiOnly
       });
     }
-  };
+  });
 }
 function buildTestStartsAt({
   description,
@@ -247,7 +290,7 @@ function buildTestStartsAt({
   requiresKeys,
   uiOnly
 }) {
-  return {
+  return chainable({
     notImplemented: () => ({
       coverage: [],
       description,
@@ -273,7 +316,7 @@ function buildTestStartsAt({
         uiOnly
       });
     }
-  };
+  });
 }
 function buildTestSteps({
   description,
@@ -285,8 +328,8 @@ function buildTestSteps({
   startsAtFn,
   uiOnly
 }) {
-  return {
-    steps: (stepsFn) => ({
+  return chainable({
+    steps: (stepsFn) => chainable({
       coverage: (...ids) => ({
         coverage: ids,
         description,
@@ -301,7 +344,7 @@ function buildTestSteps({
         uiOnly
       })
     })
-  };
+  });
 }
 
 // src/lint.ts
@@ -930,7 +973,12 @@ async function executeOnePrecondition(state, name) {
     const result = await def.setup(state.ctx, state.data);
     const resolved = {};
     Object.entries(result).forEach(([key, value]) => {
-      resolved[key] = readTestValue(value);
+      if (!isPrimitive(value)) {
+        throw new TypeError(
+          `Precondition "${name}" returned non-primitive value at key "${key}". Setup return values must be string, number, or boolean \u2014 produced via ctx.fixed/uniqueEmail/uniqueId.`
+        );
+      }
+      resolved[key] = value;
     });
     state.data[name] = resolved;
     state.executed.push(name);
@@ -1002,13 +1050,13 @@ function createSetupContext({
 }) {
   return {
     runId,
-    fixed: (value) => createTestValue(value),
+    fixed: (value) => brandTestValue(value),
     setCookie: (name, value, options) => {
       const resolvedOptions = options != null && options.domain == null && defaultDomain != null ? { ...options, domain: defaultDomain } : options ?? void 0;
       cookies.push({ name, options: resolvedOptions, value });
     },
-    uniqueEmail: () => createTestValue(`ripplo-test-${runId}@test.ripplo.ai`),
-    uniqueId: (prefix) => createTestValue(`ripplo-test-${prefix}-${runId}`)
+    uniqueEmail: () => brandTestValue(`ripplo-test-${runId}@test.ripplo.ai`),
+    uniqueId: (prefix) => brandTestValue(`ripplo-test-${prefix}-${runId}`)
   };
 }
 function deriveDefaultDomain(baseUrl) {

package/dist/koa.d.ts

@@ -1,7 +1,7 @@
 import { Middleware } from 'koa';
-import { R as RipploEngine } from './engine-BdKDGBYw.js';
-import './builder-0oT23S0W.js';
-import './types-B7YljrTz.js';
+import { R as RipploEngine } from './engine-B6MM4AEw.js';
+import './builder-mhjAdyNW.js';
+import './types-2i1Sm7_J.js';
 import './step-De52hTLd.js';
 import '@ripplo/spec';
 

package/dist/koa.js

@@ -6,7 +6,7 @@ import {
   serializeCookie,
   teardownRequestSchema,
   verifyWebhookSignature
-} from "./chunk-UFHSNW4E.js";
+} from "./chunk-EHAZBEHO.js";
 import "./chunk-4MGIQFAJ.js";
 
 // src/adapters/koa.ts

package/dist/lockfile.d.ts

@@ -1,8 +1,8 @@
 import { Codec } from '@ripplo/spec';
 import { z } from 'zod';
 import { CompileResult } from './compiler.js';
-import './builder-0oT23S0W.js';
-import './types-B7YljrTz.js';
+import './builder-mhjAdyNW.js';
+import './types-2i1Sm7_J.js';
 import './step-De52hTLd.js';
 
 declare const LOCKFILE_RELATIVE_PATH = ".ripplo/ripplo.lock";
@@ -647,7 +647,7 @@ declare const lockfileBodySchema: z.ZodObject<{
                 observer: z.ZodString;
                 params: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
                     type: z.ZodLiteral<"static">;
-                    value: z.ZodString;
+                    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
                 }, z.core.$strip>, z.ZodObject<{
                     name: z.ZodString;
                     type: z.ZodLiteral<"variable">;

package/dist/lockfile.js

@@ -194,6 +194,13 @@ var numericValueRefSchema = z5.discriminatedUnion("type", [
   z5.object({ type: z5.literal("static"), value: z5.number().int().nonnegative() }),
   variableRefSchema
 ]);
+var primitiveValueRefSchema = z5.discriminatedUnion("type", [
+  z5.object({
+    type: z5.literal("static"),
+    value: z5.union([z5.string(), z5.number(), z5.boolean()])
+  }),
+  variableRefSchema
+]);
 
 // ../spec/src/variables.ts
 import { z as z6 } from "zod";
@@ -413,7 +420,7 @@ var assertObserverNode = z7.object({
   ...nodeBase,
   budget: z7.enum(["fast", "slow", "async"]),
   observer: z7.string().min(1).max(200),
-  params: z7.record(z7.string().max(200), stringValueRefSchema),
+  params: z7.record(z7.string().max(200), primitiveValueRefSchema),
   type: z7.literal("assertObserver")
 });
 var specNodeSchema = z7.discriminatedUnion("type", [

package/dist/nestjs.d.ts

@@ -1,7 +1,7 @@
 import { DynamicModule } from '@nestjs/common';
-import { R as RipploEngine } from './engine-BdKDGBYw.js';
-import './builder-0oT23S0W.js';
-import './types-B7YljrTz.js';
+import { R as RipploEngine } from './engine-B6MM4AEw.js';
+import './builder-mhjAdyNW.js';
+import './types-2i1Sm7_J.js';
 import './step-De52hTLd.js';
 import '@ripplo/spec';
 

package/dist/nestjs.js

@@ -6,7 +6,7 @@ import {
   serializeCookie,
   teardownRequestSchema,
   verifyWebhookSignature
-} from "./chunk-UFHSNW4E.js";
+} from "./chunk-EHAZBEHO.js";
 import {
   __decorateClass,
   __decorateParam

package/dist/nextjs.d.ts

@@ -1,6 +1,6 @@
-import { R as RipploEngine } from './engine-BdKDGBYw.js';
-import './builder-0oT23S0W.js';
-import './types-B7YljrTz.js';
+import { R as RipploEngine } from './engine-B6MM4AEw.js';
+import './builder-mhjAdyNW.js';
+import './types-2i1Sm7_J.js';
 import './step-De52hTLd.js';
 import '@ripplo/spec';
 

package/dist/nextjs.js

@@ -6,7 +6,7 @@ import {
   serializeCookie,
   teardownRequestSchema,
   verifyWebhookSignature
-} from "./chunk-UFHSNW4E.js";
+} from "./chunk-EHAZBEHO.js";
 import "./chunk-4MGIQFAJ.js";
 
 // src/adapters/nextjs.ts

package/dist/{types-B7YljrTz.d.ts → types-2i1Sm7_J.d.ts}

@@ -16,23 +16,24 @@ interface CookieEntry {
     readonly value: string;
 }
 declare const TEST_VALUE_BRAND: unique symbol;
-interface TestValue {
+type Primitive = boolean | number | string;
+type TestValue<T extends Primitive> = T & {
     readonly [TEST_VALUE_BRAND]: true;
-}
+};
 interface SetupContext {
     readonly runId: string;
-    fixed(value: string): TestValue;
+    fixed<T extends Primitive>(value: T): TestValue<T>;
     setCookie(name: string, value: string, options?: CookieOptions): void;
-    uniqueEmail(): TestValue;
-    uniqueId(prefix: string): TestValue;
+    uniqueEmail(): TestValue<string>;
+    uniqueId(prefix: string): TestValue<string>;
 }
-interface TeardownContext<TData extends Record<string, string>> {
+interface TeardownContext<TData extends Record<string, Primitive>> {
     readonly data: TData;
 }
 declare const PRECONDITION_DATA: unique symbol;
 declare const PRECONDITION_DEPS: unique symbol;
 declare const PRECONDITION_NAME: unique symbol;
-interface Precondition<TData extends Record<string, string> = Record<string, string>, TDeps extends Record<string, Record<string, string>> = Record<string, Record<string, string>>> {
+interface Precondition<TData extends Record<string, Primitive> = Record<string, Primitive>, TDeps extends Record<string, Record<string, Primitive>> = Record<string, Record<string, Primitive>>> {
     readonly [PRECONDITION_DATA]: TData;
     readonly [PRECONDITION_DEPS]: TDeps;
     readonly [PRECONDITION_NAME]: string;
@@ -46,10 +47,10 @@ interface PreconditionDefinition {
     readonly implemented: boolean;
     readonly name: string;
     readonly returns: ReadonlyArray<string>;
-    readonly teardown: ((ctx: TeardownContext<Record<string, string>>) => Promise<void>) | undefined;
-    readonly setup: (ctx: SetupContext, deps: Record<string, Record<string, string>>) => Promise<Record<string, TestValue>>;
+    readonly teardown: ((ctx: TeardownContext<Record<string, Primitive>>) => Promise<void>) | undefined;
+    readonly setup: (ctx: SetupContext, deps: Record<string, Record<string, Primitive>>) => Promise<Record<string, Primitive>>;
 }
-type VarsFn<T> = (vars: Record<string, Record<string, string>>) => T;
+type VarsFn<T> = (vars: Record<string, Record<string, Primitive>>) => T;
 interface TestDefinition {
     readonly coverage: ReadonlyArray<string>;
     readonly description: string;
@@ -100,7 +101,7 @@ interface ObserverDefinition {
     readonly description: string;
     readonly implemented: boolean;
     readonly name: string;
-    readonly run: (ctx: ObserverContext, params: Record<string, string>) => Promise<ObserverOutcome>;
+    readonly run: (ctx: ObserverContext, params: Record<string, Primitive>) => Promise<ObserverOutcome>;
 }
 
-export { type CookieEntry as C, DEFAULT_IGNORE_PATHS as D, type ObserverHandle as O, type Precondition as P, type SetupContext as S, type TeardownContext as T, type UnimplementedItems as U, type ObserverInput as a, type ObserverBudgetTier as b, type CookieOptions as c, DEFAULT_WATCH_PATHS as d, type ObserverContext as e, type ObserverDefinition as f, type ObserverOutcome as g, type PreconditionDeps as h, type TestDefinition as i, type PreconditionDefinition as j, type PreconditionData as k, type TestValue as l };
+export { type CookieEntry as C, DEFAULT_IGNORE_PATHS as D, type ObserverHandle as O, type Primitive as P, type SetupContext as S, type TeardownContext as T, type UnimplementedItems as U, type ObserverInput as a, type ObserverBudgetTier as b, type CookieOptions as c, DEFAULT_WATCH_PATHS as d, type ObserverContext as e, type ObserverDefinition as f, type ObserverOutcome as g, type Precondition as h, type PreconditionDeps as i, type TestDefinition as j, type TestValue as k, type PreconditionDefinition as l, type PreconditionData as m };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ripplo/testing",
   "description": "TypeScript DSL for defining and running Ripplo e2e workflow tests",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "type": "module",
   "files": [
     "dist"