@ripplo/testing 0.1.1 → 0.3.0

package/dist/index.js

@@ -1,218 +1,147 @@
+import {
+  DEFAULT_IGNORE_PATHS,
+  DEFAULT_WATCH_PATHS,
+  createTestValue,
+  makeObserverHandle,
+  readObserverBudget,
+  readObserverDescription,
+  readObserverName,
+  readPreconditionDepMapping,
+  readPreconditionDependsOn,
+  readPreconditionDescription,
+  readPreconditionName,
+  readTestValue,
+  userDslConfigSchema
+} from "./chunk-76BU4M6E.js";
 import {
   compile
 } from "./chunk-KNF4K4JH.js";
 import "./chunk-MGATMMCZ.js";
 import {
-  buildObserver,
   buildSetCookieHeader,
-  createEngine,
   serializeCookie,
   verifyWebhookSignature
-} from "./chunk-CD3M7H5A.js";
-import {
-  DEFAULT_IGNORE_PATHS,
-  DEFAULT_WATCH_PATHS,
-  dslConfigSchema,
-  readObserverName,
-  readPreconditionName
-} from "./chunk-3IL457A7.js";
+} from "./chunk-TO3T2D2Y.js";
 
-// src/builder.ts
-function createRipplo(rawConfig) {
-  const config = dslConfigSchema.parse(rawConfig);
-  const preconditions = [];
-  const observers = [];
-  const tests = [];
-  const preconditionNames = /* @__PURE__ */ new Set();
-  const observerNames = /* @__PURE__ */ new Set();
-  const testNames = /* @__PURE__ */ new Set();
-  function implementPrecondition(handle, impl) {
-    const preconditionName = readPreconditionName(handle);
-    const idx = preconditions.findIndex((p) => p.name === preconditionName);
-    if (idx === -1) {
-      throw new Error(`Cannot implement unknown precondition: "${preconditionName}"`);
-    }
-    const existing = preconditions[idx];
-    if (existing == null) {
-      throw new Error(`Cannot implement unknown precondition: "${preconditionName}"`);
-    }
-    const mapping = existing.depMapping;
-    preconditions[idx] = {
-      ...existing,
-      implemented: true,
-      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TData narrows Record<string, string>, safe at engine boundary
-      teardown: impl.teardown,
-      setup: async (ctx, allDeps) => {
-        const resolved = {};
-        mapping.forEach(([key, depName]) => {
-          const data = allDeps[depName];
-          if (data != null) {
-            resolved[key] = data;
-          }
-        });
-        return impl.setup(ctx, resolved);
-      }
-    };
-  }
-  function implementObserver(handle, impl) {
-    const name = readObserverName(handle);
-    const idx = observers.findIndex((o) => o.name === name);
-    if (idx === -1) {
-      throw new Error(`Cannot implement unknown observer: "${name}"`);
-    }
-    const existing = observers[idx];
-    if (existing == null) {
-      throw new Error(`Cannot implement unknown observer: "${name}"`);
-    }
-    observers[idx] = {
-      ...existing,
-      implemented: true,
-      run: async (ctx, params) => {
-        return impl(ctx, params);
-      }
-    };
-  }
-  return {
-    implementObserver,
-    implementPrecondition,
-    getConfig: () => config,
-    getObservers: () => observers,
-    getPreconditions: () => preconditions,
-    getTests: () => tests,
-    getUnimplemented() {
-      return {
-        observers: observers.filter((o) => !o.implemented).map((o) => o.name),
-        preconditions: preconditions.filter((p) => !p.implemented).map((p) => p.name),
-        tests: tests.filter((t) => !t.implemented).map((t) => t.name)
-      };
-    },
-    observer(name) {
-      if (observerNames.has(name)) {
-        observers.splice(0, observers.length, ...observers.filter((o) => o.name !== name));
-      }
-      observerNames.add(name);
-      return buildObserver({ name, observers });
+// src/observer.ts
+function createPassOutcome() {
+  return { kind: "pass" };
+}
+function createRetryOutcome(reason) {
+  return { kind: "retry", reason };
+}
+function createFailOutcome(reason) {
+  return { kind: "fail", reason };
+}
+function buildObserver(name) {
+  let description = "";
+  let budget = "fast";
+  const self = {
+    budget(tier) {
+      budget = tier;
+      return self;
     },
-    precondition(name) {
-      if (preconditionNames.has(name)) {
-        preconditions.splice(
-          0,
-          preconditions.length,
-          ...preconditions.filter((p) => p.name !== name)
-        );
-      }
-      preconditionNames.add(name);
-      return buildPrecondition(name, preconditions);
+    description(text) {
+      description = text;
+      return self;
     },
-    test(id, options) {
-      validateTestId(id);
-      if (testNames.has(id)) {
-        tests.splice(0, tests.length, ...tests.filter((t) => t.id !== id));
-      }
-      testNames.add(id);
-      return buildTestName(id, tests, options?.uiOnly);
+    input() {
+      return {
+        contract: () => makeObserverHandle({ budget, description, name })
+      };
     }
   };
+  return self;
 }
-function buildDepMapping(deps) {
-  return Object.entries(deps).map(([key, dep]) => [key, readPreconditionName(dep)]);
+
+// src/builder.ts
+function precondition(name) {
+  return buildPreconditionStart(name);
 }
-function remapDeps(mapping, allDeps) {
-  const resolved = {};
-  mapping.forEach(([key, depName]) => {
-    const data = allDeps[depName];
-    if (data != null) {
-      resolved[key] = data;
-    }
-  });
-  return resolved;
+function observer(name) {
+  return buildObserver(name);
 }
-function makePrecondition(name) {
-  return { name };
+function test(id, options) {
+  validateTestId(id);
+  return buildTestName(id, options?.uiOnly);
 }
-function castBuilder(value) {
-  return value;
+function createRipplo(rawConfig, registries) {
+  const parsed = userDslConfigSchema.parse(rawConfig);
+  const webhookSecret = parsed.webhookSecret ?? process.env["RIPPLO_WEBHOOK_SECRET"] ?? "";
+  if (webhookSecret.length === 0) {
+    throw new Error(
+      "RIPPLO_WEBHOOK_SECRET is required. Set it in .ripplo/.env or pass webhookSecret to createRipplo()."
+    );
+  }
+  const config = { ...parsed, webhookSecret };
+  const { observers, preconditions, tests } = registries;
+  validateUniqueNames(preconditions, observers, tests);
+  const preconditionDefs = Object.values(preconditions).map((p) => stubPreconditionDef(p));
+  const observerDefs = Object.values(observers).map((o) => stubObserverDef(o));
+  const testDefs = [...tests];
+  return {
+    config,
+    observers,
+    preconditions,
+    tests: testDefs,
+    getConfig: () => config,
+    getObservers: () => observerDefs,
+    getPreconditions: () => preconditionDefs,
+    getTests: () => testDefs,
+    getUnimplemented: () => ({
+      observers: observerDefs.filter((o) => !o.implemented).map((o) => o.name),
+      preconditions: preconditionDefs.filter((p) => !p.implemented).map((p) => p.name),
+      tests: testDefs.filter((t) => !t.implemented).map((t) => t.id)
+    })
+  };
 }
-function pushStub(params) {
-  params.preconditions.push({
-    dependsOn: params.depMapping.map(([_, depName]) => depName),
-    depMapping: params.depMapping,
-    description: params.description,
+function stubPreconditionDef(p) {
+  const name = readPreconditionName(p);
+  return {
+    dependsOn: readPreconditionDependsOn(p),
+    depMapping: readPreconditionDepMapping(p),
+    description: readPreconditionDescription(p),
     implemented: false,
-    name: params.name,
+    name,
     returns: [],
     teardown: void 0,
     setup: () => Promise.resolve({})
-  });
-  return makePrecondition(params.name);
+  };
 }
-function buildPrecondition(name, preconditions) {
-  let description = "";
-  let currentDeps = {};
-  const self = {
-    contract: castBuilder(
-      () => pushStub({ depMapping: buildDepMapping(currentDeps), description, name, preconditions })
-    ),
-    requires: castBuilder(requiresImpl),
-    setup: castBuilder(setupNoDepsImpl),
-    description(text) {
-      description = text;
-      return self;
-    },
-    notImplemented() {
-      pushStub({ depMapping: [], description, name, preconditions });
-      return makePrecondition(name);
-    }
+function stubObserverDef(o) {
+  const name = readObserverName(o);
+  return {
+    budget: readObserverBudget(o),
+    description: readObserverDescription(o),
+    implemented: false,
+    name,
+    run: () => Promise.resolve(createFailOutcome(`observer "${name}" not implemented`))
   };
-  return self;
-  function requiresImpl(deps) {
-    currentDeps = deps;
-    const mapping = buildDepMapping(deps);
-    const withDeps = {
-      contract: castBuilder(
-        () => pushStub({ depMapping: mapping, description, name, preconditions })
-      ),
-      setup: castBuilder(setupWithDepsImpl),
-      description(text) {
-        description = text;
-        return withDeps;
-      },
-      notImplemented() {
-        pushStub({ depMapping: mapping, description, name, preconditions });
-        return makePrecondition(name);
-      }
-    };
-    return castBuilder(withDeps);
-    function setupWithDepsImpl(fn) {
-      return registerPrecondition(deps, fn);
+}
+function validateUniqueNames(preconditions, observers, tests) {
+  const pNames = /* @__PURE__ */ new Set();
+  Object.values(preconditions).forEach((p) => {
+    const name = readPreconditionName(p);
+    if (pNames.has(name)) {
+      throw new Error(`Duplicate precondition name: "${name}"`);
     }
-  }
-  function setupNoDepsImpl(fn) {
-    return registerPrecondition({}, async (ctx) => fn(ctx));
-  }
-  function registerPrecondition(deps, fn) {
-    const mapping = buildDepMapping(deps);
-    const def = {
-      dependsOn: mapping.map(([_, depName]) => depName),
-      depMapping: mapping,
-      description,
-      implemented: true,
-      name,
-      returns: [],
-      teardown: void 0,
-      setup: async (ctx, allDeps) => {
-        const resolved = remapDeps(mapping, allDeps);
-        return fn(ctx, resolved);
-      }
-    };
-    preconditions.push(def);
-    return {
-      teardown(tdFn) {
-        def.teardown = tdFn;
-        return makePrecondition(name);
-      }
-    };
-  }
+    pNames.add(name);
+  });
+  const oNames = /* @__PURE__ */ new Set();
+  Object.values(observers).forEach((o) => {
+    const name = readObserverName(o);
+    if (oNames.has(name)) {
+      throw new Error(`Duplicate observer name: "${name}"`);
+    }
+    oNames.add(name);
+  });
+  const tIds = /* @__PURE__ */ new Set();
+  tests.forEach((t) => {
+    if (tIds.has(t.id)) {
+      throw new Error(`Duplicate test id: "${t.id}"`);
+    }
+    tIds.add(t.id);
+  });
 }
 var TEST_ID_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 function validateTestId(id) {
@@ -222,135 +151,189 @@ function validateTestId(id) {
     );
   }
 }
-function buildTestName(id, tests, uiOnly) {
-  return {
-    name(displayName) {
-      return buildTestRequires({ id, name: displayName, tests, uiOnly });
+function makePrecondition(params) {
+  return params;
+}
+function buildDepMapping(deps) {
+  return Object.entries(deps).map(([key, dep]) => [key, readPreconditionName(dep)]);
+}
+function buildPreconditionStart(name) {
+  let description = "";
+  const self = {
+    contract: () => makePrecondition({
+      dependsOn: [],
+      depMapping: [],
+      description,
+      name
+    }),
+    description(text) {
+      description = text;
+      return self;
+    },
+    requires(deps) {
+      return buildPreconditionWithDeps({ deps, name, getDescription: () => description });
     }
   };
+  return self;
 }
-function buildTestRequires({
-  id,
-  name,
-  tests,
-  uiOnly
+function buildPreconditionWithDeps({
+  deps,
+  getDescription,
+  name
 }) {
+  const description = getDescription();
+  const depMapping = buildDepMapping(deps);
+  const dependsOn = depMapping.map(([, depName]) => depName);
+  return {
+    contract: () => makePrecondition({
+      dependsOn,
+      depMapping,
+      description,
+      name
+    })
+  };
+}
+function buildTestName(id, uiOnly) {
+  return {
+    name: (displayName) => buildTestRequires({ id, name: displayName, uiOnly })
+  };
+}
+function castOutcome(value) {
+  return value;
+}
+function buildTestRequires({ id, name, uiOnly }) {
   let description = "";
   const self = {
-    requires: castBuilder(requiresImpl),
     description(text) {
       description = text;
       return self;
+    },
+    requires(reqs) {
+      const reqNames = Object.values(reqs).map((r) => readPreconditionName(r));
+      const requiresKeys = {};
+      Object.entries(reqs).forEach(([key, p]) => {
+        requiresKeys[key] = readPreconditionName(p);
+      });
+      return castOutcome(
+        buildTestOutcome({
+          id,
+          name,
+          reqNames,
+          requiresKeys,
+          uiOnly,
+          getDescription: () => description
+        })
+      );
     }
   };
   return self;
-  function requiresImpl(reqs) {
-    const reqNames = Object.values(reqs).map((r) => readPreconditionName(r));
-    const requiresKeys = {};
-    Object.entries(reqs).forEach(([key, precondition]) => {
-      requiresKeys[key] = readPreconditionName(precondition);
-    });
-    return buildOutcome({ description, id, name, reqNames, requiresKeys, tests, uiOnly });
-  }
 }
-function buildOutcome({
-  description: initialDesc,
+function buildTestOutcome({
+  getDescription,
   id,
   name,
   reqNames,
   requiresKeys,
-  tests,
   uiOnly
 }) {
-  let description = initialDesc;
+  const description = getDescription();
   return {
-    description(text) {
-      description = text;
-      return this;
-    },
     expectedOutcome(text) {
-      return buildStartsAt({
+      return buildTestStartsAt({
         description,
         expectedOutcome: text,
         id,
         name,
         reqNames,
         requiresKeys,
-        tests,
         uiOnly
       });
     }
   };
 }
-function buildStartsAt({
+function buildTestStartsAt({
   description,
   expectedOutcome,
   id,
   name,
   reqNames,
   requiresKeys,
-  tests,
   uiOnly
 }) {
   return {
-    startsAt: castBuilder(startsAtImpl),
-    notImplemented() {
-      tests.push({
-        description,
-        expectedOutcome,
-        id,
-        implemented: false,
-        name,
-        requires: [...reqNames],
-        requiresKeys,
-        startsAtFn: void 0,
-        stepsFn: void 0,
-        uiOnly
-      });
-    }
-  };
-  function startsAtImpl(fn) {
-    return {
-      steps: castBuilder(stepsImpl)
-    };
-    function stepsImpl(stepsFn) {
-      tests.push({
+    notImplemented: () => ({
+      description,
+      expectedOutcome,
+      id,
+      implemented: false,
+      name,
+      requires: [...reqNames],
+      requiresKeys,
+      startsAtFn: void 0,
+      stepsFn: void 0,
+      uiOnly
+    }),
+    startsAt(fn) {
+      return buildTestSteps({
         description,
         expectedOutcome,
         id,
-        implemented: true,
         name,
-        requires: [...reqNames],
+        reqNames,
         requiresKeys,
         startsAtFn: fn,
-        stepsFn,
         uiOnly
       });
     }
-  }
+  };
+}
+function buildTestSteps({
+  description,
+  expectedOutcome,
+  id,
+  name,
+  reqNames,
+  requiresKeys,
+  startsAtFn,
+  uiOnly
+}) {
+  return {
+    steps: (stepsFn) => ({
+      description,
+      expectedOutcome,
+      id,
+      implemented: true,
+      name,
+      requires: [...reqNames],
+      requiresKeys,
+      startsAtFn,
+      stepsFn,
+      uiOnly
+    })
+  };
 }
 
 // src/lint.ts
 function lint(result) {
   const diagnostics = [];
-  result.tests.forEach((test) => {
-    const nodes = getOrderedNodes(test);
+  result.tests.forEach((test2) => {
+    const nodes = getOrderedNodes(test2);
     const report = (diagnostic) => {
-      diagnostics.push({ ...diagnostic, test: test.slug });
+      diagnostics.push({ ...diagnostic, test: test2.slug });
     };
     RULES.forEach((rule) => {
-      rule(nodes, test, report);
+      rule(nodes, test2, report);
     });
   });
   return { diagnostics };
 }
-function getOrderedNodes(test) {
+function getOrderedNodes(test2) {
   const result = [];
-  let currentId = test.spec.entryNode;
+  let currentId = test2.spec.entryNode;
   const visited = /* @__PURE__ */ new Set();
   while (currentId != null && !visited.has(currentId)) {
     visited.add(currentId);
-    const found = test.spec.nodes[currentId];
+    const found = test2.spec.nodes[currentId];
     if (found == null) {
       break;
     }
@@ -370,8 +353,8 @@ function exactTextMatch(nodes, _test, report) {
     }
   });
 }
-function noHardcodedData(nodes, test, report) {
-  const hasVariables = Object.keys(test.spec.variables ?? {}).length > 0;
+function noHardcodedData(nodes, test2, report) {
+  const hasVariables = Object.keys(test2.spec.variables ?? {}).length > 0;
   if (!hasVariables) {
     return;
   }
@@ -388,8 +371,8 @@ function noHardcodedData(nodes, test, report) {
     }
   });
 }
-function preferPreconditionData(nodes, test, report) {
-  const variableKeys = Object.keys(test.spec.variables ?? {});
+function preferPreconditionData(nodes, test2, report) {
+  const variableKeys = Object.keys(test2.spec.variables ?? {});
   if (variableKeys.length === 0) {
     return;
   }
@@ -461,8 +444,8 @@ function assertMatchesOutcome(nodes, _test, report) {
     });
   }
 }
-function noEmptySteps(nodes, test, report) {
-  if (!test.implemented) {
+function noEmptySteps(nodes, test2, report) {
+  if (!test2.implemented) {
     return;
   }
   if (nodes.length === 0) {
@@ -509,8 +492,8 @@ var EFFECT_ASSERTION_TYPES = /* @__PURE__ */ new Set([
 function isEffectAssertion(node) {
   return EFFECT_ASSERTION_TYPES.has(node.type);
 }
-function noAssertions(nodes, test, report) {
-  if (!test.implemented || nodes.length === 0) {
+function noAssertions(nodes, test2, report) {
+  if (!test2.implemented || nodes.length === 0) {
     return;
   }
   if (!nodes.some((n) => isAssertionNode(n))) {
@@ -521,8 +504,8 @@ function noAssertions(nodes, test, report) {
     });
   }
 }
-function lowAssertionRatio(nodes, test, report) {
-  if (!test.implemented || nodes.length <= 3) {
+function lowAssertionRatio(nodes, test2, report) {
+  if (!test2.implemented || nodes.length <= 3) {
     return;
   }
   const assertions = nodes.filter((n) => isAssertionNode(n)).length;
@@ -646,11 +629,11 @@ function nodeKeywords(node) {
   const locName = loc.by === "role" ? loc.name ?? "" : loc.value;
   return [...fromLabel, ...tokenize(locName)];
 }
-function expectedOutcomeKeywordCoverage(nodes, test, report) {
-  if (!test.implemented || nodes.length === 0) {
+function expectedOutcomeKeywordCoverage(nodes, test2, report) {
+  if (!test2.implemented || nodes.length === 0) {
     return;
   }
-  const outcomeTokens = new Set(tokenize(test.expectedOutcome));
+  const outcomeTokens = new Set(tokenize(test2.expectedOutcome));
   if (outcomeTokens.size === 0) {
     return;
   }
@@ -684,8 +667,8 @@ function isLikelyBackendMutation(node) {
   const name = loc.by === "role" ? loc.name ?? "" : loc.value;
   return BACKEND_MUTATION_KEYWORDS.test(name);
 }
-function mutationWithoutObserverCoverage(nodes, test, report) {
-  if (!test.implemented || test.spec.uiOnly === true) {
+function mutationWithoutObserverCoverage(nodes, test2, report) {
+  if (!test2.implemented || test2.spec.uiOnly === true) {
     return;
   }
   nodes.forEach((node, index) => {
@@ -710,8 +693,8 @@ function mutationWithoutObserverCoverage(nodes, test, report) {
     });
   });
 }
-function observerParamsReferenceVariables(nodes, test, report) {
-  const variableKeys = Object.keys(test.spec.variables ?? {});
+function observerParamsReferenceVariables(nodes, test2, report) {
+  const variableKeys = Object.keys(test2.spec.variables ?? {});
   if (variableKeys.length === 0) {
     return;
   }
@@ -752,6 +735,278 @@ var RULES = [
   mutationWithoutObserverCoverage,
   observerParamsReferenceVariables
 ];
+
+// src/engine.ts
+function notImplemented(reason) {
+  return { reason: reason ?? "not implemented" };
+}
+function isNotImplemented(value) {
+  return typeof value === "object" && value !== null && "reason" in value && Object.keys(value).length === 1;
+}
+function createEngine(ripplo, impls) {
+  const preconditionDefs = wirePreconditions(ripplo.preconditions, impls.preconditions);
+  const observerDefs = wireObservers(ripplo.observers, impls.observers);
+  const preconditionsByName = new Map(preconditionDefs.map((d) => [d.name, d]));
+  const observersByName = new Map(observerDefs.map((d) => [d.name, d]));
+  return {
+    executeObserver: (name, params) => executeObserver(observersByName, name, params),
+    executePreconditions: (names, options) => executePreconditions({ defsByName: preconditionsByName, names, options }),
+    getConfig: () => ripplo.getConfig(),
+    getObservers: () => observerDefs,
+    getPreconditions: () => preconditionDefs,
+    getUnimplemented: () => ({
+      observers: observerDefs.filter((o) => !o.implemented).map((o) => o.name),
+      preconditions: preconditionDefs.filter((p) => !p.implemented).map((p) => p.name),
+      tests: ripplo.tests.filter((t) => !t.implemented).map((t) => t.id)
+    }),
+    teardown: (names, data) => teardown(preconditionsByName, names, data)
+  };
+}
+function wirePreconditions(registry, impls) {
+  return Object.entries(registry).map(([key, handle]) => {
+    const impl = Reflect.get(impls, key);
+    if (isNotImplemented(impl)) {
+      return makeNotImplementedPreconditionDef(handle, impl);
+    }
+    return makeWiredPreconditionDef(handle, impl);
+  });
+}
+function wireObservers(registry, impls) {
+  return Object.entries(registry).map(([key, handle]) => {
+    const impl = Reflect.get(impls, key);
+    if (isNotImplemented(impl)) {
+      return makeNotImplementedObserverDef(handle, impl);
+    }
+    return makeWiredObserverDef(handle, impl);
+  });
+}
+function makeNotImplementedPreconditionDef(handle, sentinel) {
+  const name = readPreconditionName(handle);
+  return {
+    dependsOn: readPreconditionDepMappingKeys(handle),
+    depMapping: readPreconditionDepMapping(handle),
+    description: readDescriptionOf(handle),
+    implemented: false,
+    name,
+    returns: [],
+    teardown: void 0,
+    setup: () => Promise.reject(new Error(`Precondition "${name}" is ${sentinel.reason}`))
+  };
+}
+function makeWiredPreconditionDef(handle, impl) {
+  const name = readPreconditionName(handle);
+  const mapping = readPreconditionDepMapping(handle);
+  const typedImpl = impl;
+  return {
+    dependsOn: mapping.map(([, depName]) => depName),
+    depMapping: mapping,
+    description: readDescriptionOf(handle),
+    implemented: true,
+    name,
+    returns: [],
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- typedImpl.teardown has narrower TData, wider context at engine boundary
+    teardown: typedImpl.teardown,
+    setup: async (ctx, allDeps) => {
+      const resolved = {};
+      mapping.forEach(([key, depName]) => {
+        const data = allDeps[depName];
+        if (data != null) {
+          resolved[key] = data;
+        }
+      });
+      return typedImpl.setup(ctx, resolved);
+    }
+  };
+}
+function makeNotImplementedObserverDef(handle, sentinel) {
+  const name = readObserverName(handle);
+  return {
+    budget: readBudgetOf(handle),
+    description: readDescriptionOfObserver(handle),
+    implemented: false,
+    name,
+    run: () => Promise.resolve(createFailOutcome(`observer "${name}" is ${sentinel.reason}`))
+  };
+}
+function makeWiredObserverDef(handle, impl) {
+  const name = readObserverName(handle);
+  const typedImpl = impl;
+  return {
+    budget: readBudgetOf(handle),
+    description: readDescriptionOfObserver(handle),
+    implemented: true,
+    name,
+    run: async (ctx, params) => {
+      return typedImpl(ctx, params);
+    }
+  };
+}
+function readPreconditionDepMappingKeys(handle) {
+  return readPreconditionDepMapping(handle).map(([, depName]) => depName);
+}
+function readDescriptionOf(handle) {
+  return handle.description;
+}
+function readDescriptionOfObserver(handle) {
+  return handle.description;
+}
+function readBudgetOf(handle) {
+  return handle.budget;
+}
+async function executePreconditions({
+  defsByName,
+  names,
+  options
+}) {
+  const runId = crypto.randomUUID().slice(0, 12);
+  const cookies = [];
+  const defaultDomain = deriveDefaultDomain(options?.appUrl);
+  const state = {
+    cookies,
+    ctx: createSetupContext({ cookies, defaultDomain, runId }),
+    data: {},
+    defsByName,
+    executed: [],
+    runId
+  };
+  return runBatchSequence(state, names);
+}
+async function runBatchSequence(state, names) {
+  let index = 0;
+  while (index < names.length) {
+    const name = names[index];
+    if (name == null) {
+      break;
+    }
+    const error = validatePrecondition(state.defsByName, name);
+    if (error != null) {
+      return fail(state, error);
+    }
+    const stepError = await executeOnePrecondition(state, name);
+    if (stepError != null) {
+      return fail(state, stepError);
+    }
+    index += 1;
+  }
+  return {
+    cookies: state.cookies,
+    data: state.data,
+    error: void 0,
+    executed: state.executed,
+    runId: state.runId,
+    success: true
+  };
+}
+function validatePrecondition(defsByName, name) {
+  const def = defsByName.get(name);
+  if (def == null) {
+    return `Unknown precondition: "${name}"`;
+  }
+  if (!def.implemented) {
+    return `Precondition "${name}" is not implemented`;
+  }
+  return void 0;
+}
+async function executeOnePrecondition(state, name) {
+  const def = state.defsByName.get(name);
+  if (def == null) {
+    return `Unknown precondition: "${name}"`;
+  }
+  try {
+    const result = await def.setup(state.ctx, state.data);
+    const resolved = {};
+    Object.entries(result).forEach(([key, value]) => {
+      resolved[key] = readTestValue(value);
+    });
+    state.data[name] = resolved;
+    state.executed.push(name);
+    return void 0;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+function fail(state, error) {
+  return {
+    cookies: state.cookies,
+    data: state.data,
+    error,
+    executed: state.executed,
+    runId: state.runId,
+    success: false
+  };
+}
+async function executeObserver(observersByName, name, params) {
+  const def = observersByName.get(name);
+  if (def == null) {
+    return { error: `Unknown observer: "${name}"`, outcome: void 0, success: false };
+  }
+  if (!def.implemented) {
+    return { error: `Observer "${name}" is not implemented`, outcome: void 0, success: false };
+  }
+  const ctx = createObserverContext(crypto.randomUUID().slice(0, 12));
+  try {
+    const outcome = await def.run(ctx, params);
+    return { error: void 0, outcome, success: true };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { error: void 0, outcome: createFailOutcome(message), success: true };
+  }
+}
+function createObserverContext(runId) {
+  return {
+    runId,
+    fail: (reason) => createFailOutcome(reason),
+    pass: () => createPassOutcome(),
+    retry: (reason) => createRetryOutcome(reason)
+  };
+}
+async function teardown(defsByName, names, data) {
+  const reversed = [...names].toReversed();
+  let index = 0;
+  while (index < reversed.length) {
+    const name = reversed[index];
+    if (name != null) {
+      await teardownOne(defsByName, name, data);
+    }
+    index += 1;
+  }
+}
+async function teardownOne(defsByName, name, data) {
+  const def = defsByName.get(name);
+  if (def?.teardown == null) {
+    return;
+  }
+  try {
+    await def.teardown({ data: data[name] ?? {} });
+  } catch {
+  }
+}
+function createSetupContext({
+  cookies,
+  defaultDomain,
+  runId
+}) {
+  return {
+    runId,
+    fixed: (value) => createTestValue(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}`)
+  };
+}
+function deriveDefaultDomain(baseUrl) {
+  if (baseUrl == null) {
+    return void 0;
+  }
+  try {
+    return new URL(baseUrl).hostname;
+  } catch {
+    return void 0;
+  }
+}
 export {
   DEFAULT_IGNORE_PATHS,
   DEFAULT_WATCH_PATHS,
@@ -760,6 +1015,10 @@ export {
   createEngine,
   createRipplo,
   lint,
+  notImplemented,
+  observer,
+  precondition,
   serializeCookie,
+  test,
   verifyWebhookSignature
 };