@noego/testing 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,676 +1,655 @@
-// src/time/manual_clock.ts
-import { Clock, Instant } from "@noego/runtime";
-var ManualClock = class _ManualClock extends Clock {
-  static defaultStart = Instant.ofEpochMilliseconds(Date.UTC(2020, 0, 1));
-  current;
-  constructor(start = _ManualClock.defaultStart) {
-    super();
-    this.current = start;
-  }
-  now() {
-    return this.current;
-  }
-  set(instant) {
-    if (instant.isBefore(this.current)) {
-      throw new RangeError(`ManualClock cannot move backwards: ${this.current.toString()} -> ${instant.toString()}`);
-    }
-    this.current = instant;
-  }
-  advanceBy(duration) {
-    this.current = this.current.plus(duration);
-  }
-};
+// src/builder.ts
+import {
+  createContainer,
+  flattenModule,
+  LoadAs,
+  SCOPED_CONTAINER
+} from "@noego/ioc";
 
-// src/time/manual_scheduler.ts
-import { Scheduler, brandId } from "@noego/runtime";
-var ManualScheduler = class extends Scheduler {
-  constructor(clock) {
-    super();
-    this.clock = clock;
-  }
-  clock;
-  tasks = [];
-  nextSequence = 0;
-  nextId = 0;
-  schedule(input) {
-    const id = brandId(`task-${++this.nextId}`, "ScheduledTask");
-    const internal = {
-      id,
-      label: input.label,
-      deadline: this.clock.now().plus(input.delay),
-      sequence: this.nextSequence++,
-      task: input.task,
-      cancelled: false
-    };
-    this.tasks.push(internal);
-    return {
-      id,
-      cancel: () => {
-        internal.cancelled = true;
-      }
-    };
+// src/errors.ts
+var TestingError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
   }
-  pending() {
-    return this.live().sort(compareTasks).map(({ id, label, deadline }) => ({ id, label, deadline }));
-  }
-  /** Advance the clock, running every task due inside the window in order. */
-  async advanceBy(duration) {
-    const target = this.clock.now().plus(duration);
-    for (; ; ) {
-      const next = this.nextDue(target);
-      if (next === null) break;
-      if (next.deadline.isAfter(this.clock.now())) {
-        this.clock.set(next.deadline);
-      }
-      await this.execute(next);
-    }
-    if (target.isAfter(this.clock.now())) {
-      this.clock.set(target);
-    }
+};
+var MissingIocSeamError = class extends TestingError {
+  constructor() {
+    super(
+      "@noego/testing requires an @noego/ioc version that provides Container.setInstanceDecorator (>= 0.5.x with the instance-decoration seam). Upgrade @noego/ioc."
+    );
   }
-  /** Advance to the earliest pending deadline and run exactly that task. */
-  async runNext() {
-    const next = this.live().sort(compareTasks)[0];
-    if (next === void 0) {
-      throw new Error("ManualScheduler.runNext: no pending tasks");
-    }
-    if (next.deadline.isAfter(this.clock.now())) {
-      this.clock.set(next.deadline);
-    }
-    await this.execute(next);
-  }
-  /** Run tasks (advancing time as needed) until none remain. */
-  async runUntilIdle(options) {
-    const maxTasks = options?.maxTasks ?? 1e4;
-    let executed = 0;
-    while (this.live().length > 0) {
-      if (executed >= maxTasks) {
-        const labels = this.pending().slice(0, 5).map((t) => t.label).join(", ");
-        throw new Error(
-          `ManualScheduler.runUntilIdle: still not idle after ${maxTasks} tasks \u2014 probable infinite reschedule loop (next: ${labels})`
-        );
-      }
-      await this.runNext();
-      executed += 1;
-    }
+};
+var UnwatchedInspectionError = class extends TestingError {
+  constructor(token, method) {
+    super(
+      `Method "${method}" on ${token} is not watched in this environment. Only watched methods are inspectable \u2014 install test.watch() or any test.* behavior/expectation descriptor for it.`
+    );
   }
-  /** Teardown assertion: fails when pending tasks remain, unless allowed. */
-  assertNoPendingTasks(options) {
-    if (options?.allow === true) return;
-    const remaining = this.pending();
-    if (remaining.length > 0) {
-      const labels = remaining.map((t) => `${t.label} @ ${t.deadline.toString()}`).join("; ");
-      throw new Error(`ManualScheduler: ${remaining.length} pending task(s) at teardown: ${labels}`);
-    }
+};
+var CallScriptExhaustedError = class extends TestingError {
+  constructor(token, method, scriptLength, callIndex) {
+    super(
+      `Call #${callIndex} to ${token}.${method} exceeds its test.calls() script of ${scriptLength} ${scriptLength === 1 ? "entry" : "entries"}.`
+    );
   }
-  live() {
-    return this.tasks.filter((t) => !t.cancelled);
+};
+var ExpectationOverflowError = class extends TestingError {
+  constructor(token, method, expected, attempted) {
+    super(
+      expected === 0 ? `${token}.${method} was expected never to be called, but it was invoked.` : `${token}.${method} was expected exactly ${expected} ${expected === 1 ? "call" : "calls"}, but call #${attempted} arrived.`
+    );
   }
-  nextDue(target) {
-    const candidates = this.live().filter((t) => !t.deadline.isAfter(target)).sort(compareTasks);
-    return candidates[0] ?? null;
+};
+var VerificationError = class extends TestingError {
+  constructor(failures) {
+    super(
+      "Exact method expectations were not satisfied:\n" + failures.map(
+        (f) => `  - ${f.token}.${f.method}: expected exactly ${f.expected} ${f.expected === 1 ? "call" : "calls"}, observed ${f.actual}`
+      ).join("\n")
+    );
   }
-  async execute(task) {
-    this.remove(task);
-    await task.task();
+};
+var MethodNotCallableError = class extends TestingError {
+  constructor(token, method) {
+    super(
+      `Cannot install a test.* descriptor on ${token}.${method}: the resolved instance has no callable method with that name.`
+    );
   }
-  remove(task) {
-    const index = this.tasks.indexOf(task);
-    this.tasks.splice(index, 1);
+};
+var NonObjectMethodTargetError = class extends TestingError {
+  constructor(token) {
+    super(
+      `.methods() is configured for ${token}, but that token resolved to a non-object value. Method descriptors apply only to IoC-managed instances.`
+    );
   }
 };
-function compareTasks(a, b) {
-  const byDeadline = a.deadline.compareTo(b.deadline);
-  return byDeadline !== 0 ? byDeadline : a.sequence - b.sequence;
-}
-
-// src/identity/sequence_id_generator.ts
-import { IdGenerator, brandId as brandId2 } from "@noego/runtime";
-var SequenceIdGenerator = class extends IdGenerator {
-  counters = /* @__PURE__ */ new Map();
-  next(brand) {
-    const current = (this.counters.get(brand) ?? 0) + 1;
-    this.counters.set(brand, current);
-    return brandId2(`${brand.toLowerCase()}-${current}`, brand);
+var UnknownTokenKeyError = class extends TestingError {
+  constructor(key, space, known) {
+    super(
+      `Unknown ${space} key "${key}" \u2014 it does not match any token known to this builder. Pass the class/token itself via a Map, or include the registration through .use(...). Known tokens: ` + (known.length ? known.join(", ") : "(none)")
+    );
   }
 };
+var InvalidDescriptorError = class extends TestingError {
+};
 
-// src/identity/seeded_random_source.ts
-import { RandomSource } from "@noego/runtime";
-var SeededRandomSource = class extends RandomSource {
-  state;
-  constructor(seed = 1) {
-    super();
-    if (!Number.isInteger(seed)) {
-      throw new RangeError(`SeededRandomSource seed must be an integer, got ${seed}`);
-    }
-    this.state = seed >>> 0;
-  }
-  nextUint32() {
-    this.state = this.state + 1831565813 >>> 0;
-    let t = this.state;
-    t = Math.imul(t ^ t >>> 15, t | 1);
-    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
-    return (t ^ t >>> 14) >>> 0;
-  }
-  bytes(length) {
-    if (!Number.isInteger(length) || length < 0) {
-      throw new RangeError(`bytes length must be a non-negative integer, got ${length}`);
-    }
-    const out = new Uint8Array(length);
-    for (let i = 0; i < length; i += 1) {
-      out[i] = this.nextUint32() & 255;
-    }
-    return out;
+// src/descriptors.ts
+var DESCRIPTOR = /* @__PURE__ */ Symbol.for("noego:testing:descriptor");
+function isDescriptor(value) {
+  return typeof value === "object" && value !== null && value[DESCRIPTOR] === true;
+}
+function frozen(value) {
+  return Object.freeze(value);
+}
+function assertBehavior(value, where) {
+  if (!isDescriptor(value) || !["returns", "throws", "original", "calls"].includes(value.kind)) {
+    throw new InvalidDescriptorError(
+      `${where} requires a behavior descriptor (test.returns/throws/original/calls).`
+    );
   }
-  integer(minInclusive, maxExclusive) {
-    if (maxExclusive <= minInclusive) {
-      throw new RangeError(`integer range is empty: [${minInclusive}, ${maxExclusive})`);
+}
+var test = {
+  /** Return the supplied value when the method is called. Auto-watches. */
+  returns(value) {
+    return frozen({ [DESCRIPTOR]: true, kind: "returns", value });
+  },
+  /** Throw/reject with the supplied error. Auto-watches. */
+  throws(error) {
+    return frozen({ [DESCRIPTOR]: true, kind: "throws", error });
+  },
+  /** Invoke the original effective method. Auto-watches. */
+  original() {
+    return frozen({ [DESCRIPTOR]: true, kind: "original" });
+  },
+  /**
+   * Per-invocation behavior script: call 1 uses entry 1, and so on. A call
+   * after exhaustion fails immediately. Unused entries do not fail verification.
+   */
+  calls(script) {
+    if (!Array.isArray(script)) {
+      throw new InvalidDescriptorError("test.calls() requires an array of behavior descriptors.");
     }
-    const span = maxExclusive - minInclusive;
-    return minInclusive + this.nextUint32() % span;
-  }
-};
-
-// src/network/scripted_fetch_client.ts
-import { FetchClient, FetchError } from "@noego/runtime";
-var ScriptedFetchClient = class extends FetchClient {
-  script;
-  cursor = 0;
-  executed = [];
-  constructor(script) {
-    super();
-    this.script = [...script];
-  }
-  execute(request) {
-    const entry = this.script[this.cursor];
-    if (entry === void 0) {
-      return Promise.reject(
-        new Error(`ScriptedFetchClient: unexpected call #${this.cursor + 1} (${request.method} ${request.url}); script is exhausted`)
-      );
+    script.forEach((entry, i) => assertBehavior(entry, `test.calls() entry #${i + 1}`));
+    return frozen({ [DESCRIPTOR]: true, kind: "calls", script: Object.freeze([...script]) });
+  },
+  /**
+   * Keep original behavior and record calls. With a raw wrapper argument, the
+   * wrapper's behavior runs and is recorded.
+   */
+  watch(wrapper) {
+    if (wrapper !== void 0 && typeof wrapper !== "function") {
+      throw new InvalidDescriptorError("test.watch() accepts only a raw wrapper function.");
     }
-    if (!entry.matches(request)) {
-      return Promise.reject(
-        new Error(`ScriptedFetchClient: call #${this.cursor + 1} (${request.method} ${request.url}) does not match script entry "${entry.describe}"`)
+    return frozen({ [DESCRIPTOR]: true, kind: "watch", wrapper });
+  },
+  /** Require exactly one call; with no behavior, the original runs. */
+  once(behavior) {
+    if (behavior !== void 0) assertBehavior(behavior, "test.once()");
+    return frozen({ [DESCRIPTOR]: true, kind: "expect", expected: 1, behavior });
+  },
+  /** Require exactly `count` calls; with no behavior, the original runs. */
+  times(count, behavior) {
+    if (!Number.isInteger(count) || count < 0) {
+      throw new InvalidDescriptorError(
+        `test.times() requires a non-negative integer count, received ${String(count)}.`
       );
     }
-    this.cursor += 1;
-    this.executed.push(request);
-    const outcome = entry.respond(request);
-    return outcome instanceof FetchError ? Promise.reject(outcome) : Promise.resolve(outcome);
-  }
-  /** Teardown assertion: every scripted call must have been consumed. */
-  assertScriptConsumed() {
-    if (this.cursor < this.script.length) {
-      const remaining = this.script.slice(this.cursor).map((e) => e.describe).join(", ");
-      throw new Error(`ScriptedFetchClient: ${this.script.length - this.cursor} unconsumed script entr(ies): ${remaining}`);
+    if (behavior !== void 0) assertBehavior(behavior, "test.times()");
+    return frozen({ [DESCRIPTOR]: true, kind: "expect", expected: count, behavior });
+  },
+  /** Require zero calls; the first invocation fails and skips the original. */
+  never() {
+    return frozen({ [DESCRIPTOR]: true, kind: "expect", expected: 0 });
+  },
+  /** Read the recorded history for a watched method in one environment. */
+  inspect(environment, token, method) {
+    const registry = environment?.[ENV_REGISTRY];
+    if (!registry) {
+      throw new InvalidDescriptorError(
+        "test.inspect() requires a built @noego/testing environment as its first argument."
+      );
     }
+    return registry.inspect(token, method);
   }
 };
+Object.freeze(test);
+var ENV_REGISTRY = /* @__PURE__ */ Symbol.for("noego:testing:env-registry");
 
-// src/process/scripted_process_runner.ts
-import { ProcessRunner } from "@noego/runtime";
-var ScriptedProcessRunner = class extends ProcessRunner {
-  script;
-  cursor = 0;
-  openHandles = /* @__PURE__ */ new Set();
-  constructor(script) {
-    super();
-    this.script = [...script];
-  }
-  consume(command, kind) {
-    const entry = this.script[this.cursor];
-    if (entry === void 0) {
-      throw new Error(`ScriptedProcessRunner: unexpected ${kind} of "${command.executable}"; script is exhausted`);
-    }
-    if (!entry.matches(command)) {
-      throw new Error(`ScriptedProcessRunner: ${kind} of "${command.executable}" does not match script entry "${entry.describe}"`);
-    }
-    this.cursor += 1;
-    return entry;
+// src/method_state.ts
+var CONTEXT_WRAPPED = /* @__PURE__ */ Symbol.for("ioc:context-wrapped");
+var CONTEXT_OWNER = /* @__PURE__ */ Symbol.for("ioc:context-owner");
+function tokenLabel(token) {
+  if (typeof token === "function") return token.name || "[anonymous class]";
+  if (typeof token === "symbol") return String(token);
+  return String(token);
+}
+var MethodState = class {
+  constructor(tokenName, method, descriptor) {
+    this.tokenName = tokenName;
+    this.method = method;
+    this.descriptor = descriptor;
+  }
+  tokenName;
+  method;
+  descriptor;
+  calls = [];
+  /** Actual invocation count (includes the call currently executing). */
+  actual = 0;
+  /** Cursor into a test.calls() script. */
+  scriptCursor = 0;
+  get expectation() {
+    return this.descriptor.kind === "expect" ? this.descriptor : void 0;
+  }
+  inspection() {
+    return {
+      count: this.calls.length,
+      calls: this.calls.map((c) => ({ ...c, args: [...c.args] }))
+    };
   }
-  run(command) {
-    try {
-      const entry = this.consume(command, "run");
-      return Promise.resolve(foldEvents(entry.events));
-    } catch (error) {
-      return Promise.reject(error);
+};
+var WatchRegistry = class {
+  /** entry-identity → method → state. Entries share states across instances. */
+  states = /* @__PURE__ */ new Map();
+  nameIndex = /* @__PURE__ */ new Map();
+  entries = [];
+  addEntry(entry) {
+    this.entries.push(entry);
+    const byMethod = /* @__PURE__ */ new Map();
+    for (const [method, descriptor] of entry.methods) {
+      if (typeof descriptor === "function") continue;
+      byMethod.set(method, new MethodState(this.entryLabel(entry), method, descriptor));
     }
-  }
-  spawn(command) {
-    const entry = this.consume(command, "spawn");
-    const handle = new ScriptedProcessHandle(command.label, entry.events, () => {
-      this.openHandles.delete(handle);
-    });
-    this.openHandles.add(handle);
-    return handle;
-  }
-  /** Teardown assertion: no spawned process may remain open. */
-  assertNoOpenHandles() {
-    if (this.openHandles.size > 0) {
-      const labels = [...this.openHandles].map((h) => h.label).join(", ");
-      throw new Error(`ScriptedProcessRunner: ${this.openHandles.size} open process handle(s) at teardown: ${labels}`);
+    this.states.set(entry.key, byMethod);
+    if (entry.byName) this.nameIndex.set(entry.key, entry.key);
+    else if (typeof entry.key === "function" && entry.key.name) {
+      this.nameIndex.set(entry.key.name, entry.key);
     }
   }
-};
-var ScriptedProcessHandle = class {
-  constructor(label, events, onClosed) {
-    this.label = label;
-    this.events = events;
-    this.onClosed = onClosed;
-    this.resultPromise = new Promise((resolve) => {
-      this.resolveResult = resolve;
-    });
-  }
-  label;
-  events;
-  onClosed;
-  listeners = [];
-  resultPromise;
-  resolveResult;
-  flushed = false;
-  killed = false;
-  onEvent(listener) {
-    this.listeners.push(listener);
-  }
-  /** Deliver all scripted events now (deterministic, test-controlled). */
-  flush() {
-    if (this.flushed || this.killed) return;
-    this.flushed = true;
-    for (const event of this.events) {
-      for (const listener of this.listeners) listener(event);
-      if (event.kind === "exit") {
-        this.resolveResult(foldEvents(this.events));
-        this.onClosed();
+  entryLabel(entry) {
+    return entry.byName ? String(entry.key) : tokenLabel(entry.key);
+  }
+  /** Entries applying to a resolving token (exact identity or name match). */
+  matchEntries(token) {
+    const name = typeof token === "function" ? token.name : typeof token === "string" ? token : void 0;
+    return this.entries.filter(
+      (entry) => entry.key === token || entry.byName && name !== void 0 && entry.key === name
+    );
+  }
+  state(entryKey, method) {
+    return this.states.get(entryKey)?.get(method);
+  }
+  inspect(token, method) {
+    const label = tokenLabel(token);
+    const keys = [token];
+    const name = typeof token === "function" ? token.name : typeof token === "string" ? token : void 0;
+    if (name !== void 0 && this.nameIndex.has(name)) keys.push(this.nameIndex.get(name));
+    for (const key of keys) {
+      const state = this.states.get(key)?.get(method);
+      if (state) return state.inspection();
+    }
+    throw new UnwatchedInspectionError(label, method);
+  }
+  /** Repeatable snapshot check of all exact expectations. */
+  verify() {
+    const failures = [];
+    for (const byMethod of this.states.values()) {
+      for (const state of byMethod.values()) {
+        const expectation = state.expectation;
+        if (!expectation) continue;
+        if (state.actual !== expectation.expected) {
+          failures.push({
+            token: state.tokenName,
+            method: state.method,
+            expected: expectation.expected,
+            actual: state.actual
+          });
+        }
       }
     }
-  }
-  kill(signal = "SIGTERM") {
-    if (this.flushed || this.killed) return;
-    this.killed = true;
-    const exit = { kind: "exit", exitCode: null, signal };
-    for (const listener of this.listeners) listener(exit);
-    this.resolveResult({ exitCode: null, signal, stdout: "", stderr: "" });
-    this.onClosed();
-  }
-  wait() {
-    return this.resultPromise;
+    if (failures.length) throw new VerificationError(failures);
   }
 };
-function foldEvents(events) {
-  let stdout = "";
-  let stderr = "";
-  let exitCode = null;
-  let signal = null;
-  for (const event of events) {
-    if (event.kind === "stdout") stdout += event.chunk;
-    else if (event.kind === "stderr") stderr += event.chunk;
-    else {
-      exitCode = event.exitCode;
-      signal = event.signal;
-    }
+function isPromiseLike(value) {
+  return !!value && typeof value.then === "function";
+}
+function recordOutcome(call, outcome, threw) {
+  if (!threw && isPromiseLike(outcome)) {
+    call.pending = true;
+    outcome.then(
+      (value) => {
+        call.result = value;
+        call.pending = false;
+      },
+      (error) => {
+        call.error = error;
+        call.pending = false;
+      }
+    );
+    return outcome;
   }
-  return { exitCode, signal, stdout, stderr };
+  call.pending = false;
+  if (threw) call.error = outcome;
+  else call.result = outcome;
+  return outcome;
 }
-
-// src/storage/memory_key_value_store.ts
-import { KeyValueStore } from "@noego/runtime";
-var MemoryKeyValueStore = class extends KeyValueStore {
-  constructor(clock) {
-    super();
-    this.clock = clock;
-  }
-  clock;
-  entries = /* @__PURE__ */ new Map();
-  get(key, codec) {
-    const entry = this.entries.get(key);
-    if (entry === void 0) return Promise.resolve(null);
-    if (entry.expiresAt !== null && !this.clock.now().isBefore(entry.expiresAt)) {
-      this.entries.delete(key);
-      return Promise.resolve(null);
+function createMethodDecorator(registry) {
+  const wrappers = /* @__PURE__ */ new WeakMap();
+  return function decorate(instance, token) {
+    const entries = registry.matchEntries(token);
+    if (entries.length === 0) return instance;
+    if (instance === null || typeof instance !== "object" && typeof instance !== "function") {
+      throw new NonObjectMethodTargetError(tokenLabel(token));
     }
-    return Promise.resolve(codec.decode(entry.encoded));
-  }
-  put(key, value, codec, options) {
-    const expiresAt = options?.timeToLive !== void 0 ? this.clock.now().plus(options.timeToLive) : null;
-    this.entries.set(key, { encoded: codec.encode(value), expiresAt });
-    return Promise.resolve();
-  }
-  delete(key) {
-    this.entries.delete(key);
-    return Promise.resolve();
-  }
-};
-
-// src/storage/memory_object_store.ts
-import { ObjectStore, brandId as brandId3 } from "@noego/runtime";
-var MemoryObjectStore = class extends ObjectStore {
-  objects = /* @__PURE__ */ new Map();
-  nextVersion = 0;
-  read(key) {
-    return Promise.resolve(this.objects.get(key) ?? null);
-  }
-  write(key, object) {
-    const version = brandId3(`v${++this.nextVersion}`, "ObjectVersion");
-    this.objects.set(key, {
-      bytes: object.bytes.slice(),
-      contentType: object.contentType,
-      metadata: object.metadata !== void 0 ? new Map(object.metadata) : void 0,
-      version
-    });
-    return Promise.resolve(version);
-  }
-  delete(key) {
-    this.objects.delete(key);
-    return Promise.resolve();
-  }
-};
-
-// src/events/recording_event_bus.ts
-import { EventBus } from "@noego/runtime";
-var RecordingEventBus = class extends EventBus {
-  constructor(mode = "immediate") {
-    super();
-    this.mode = mode;
-  }
-  mode;
-  published = [];
-  handlers = /* @__PURE__ */ new Set();
-  queue = [];
-  async publish(event) {
-    this.published.push(event);
-    if (this.mode === "queued") {
-      this.queue.push(event);
-      return;
+    if (wrappers.has(instance)) return wrappers.get(instance);
+    const effective = /* @__PURE__ */ new Map();
+    for (const entry of entries) {
+      for (const [method, descriptor] of entry.methods) {
+        effective.set(method, { entryKey: entry.key, descriptor });
+      }
     }
-    await this.deliver(event);
-  }
-  subscribe(handler) {
-    this.handlers.add(handler);
-    const bus = this;
-    const subscription = {
-      active: true,
-      unsubscribe() {
-        if (!subscription.active) return;
-        subscription.active = false;
-        bus.handlers.delete(handler);
+    for (const method of effective.keys()) {
+      if (typeof instance[method] !== "function") {
+        throw new MethodNotCallableError(tokenLabel(token), method);
       }
-    };
-    return subscription;
-  }
-  /** Deliver buffered events (queued mode) in publication order. */
-  async deliverQueued() {
-    while (this.queue.length > 0) {
-      const event = this.queue.shift();
-      await this.deliver(event);
     }
+    const methodCache = /* @__PURE__ */ new Map();
+    const proxy = new Proxy(instance, {
+      get(target, prop, receiver) {
+        if (typeof prop === "string" && effective.has(prop)) {
+          let wrapped = methodCache.get(prop);
+          if (!wrapped) {
+            const { entryKey, descriptor } = effective.get(prop);
+            wrapped = buildMethodWrapper(target, prop, descriptor, registry.state(entryKey, prop));
+            methodCache.set(prop, wrapped);
+          }
+          return wrapped;
+        }
+        if (prop === CONTEXT_WRAPPED || prop === CONTEXT_OWNER) return target[prop];
+        return Reflect.get(target, prop, receiver);
+      }
+    });
+    wrappers.set(instance, proxy);
+    return proxy;
+  };
+}
+function buildMethodWrapper(target, method, descriptor, state) {
+  const callOriginal = (self, args) => {
+    const fn = target[method];
+    return fn.apply(self === void 0 ? target : self, args);
+  };
+  if (typeof descriptor === "function") {
+    const replacement = descriptor((...args) => callOriginal(target, args));
+    return function(...args) {
+      return replacement.apply(this, args);
+    };
   }
-  get activeSubscriptionCount() {
-    return this.handlers.size;
+  if (!isDescriptor(descriptor)) {
+    throw new TypeError(`Invalid method descriptor for ${method}`);
   }
-  assertNoActiveSubscriptions() {
-    if (this.handlers.size > 0) {
-      throw new Error(`RecordingEventBus: ${this.handlers.size} active subscription(s) at teardown`);
+  return function(...args) {
+    if (!state) throw new TypeError(`Missing method state for ${method}`);
+    const expectation = state.expectation;
+    const attempted = state.actual + 1;
+    if (expectation && attempted > expectation.expected) {
+      state.actual = attempted;
+      throw new ExpectationOverflowError(state.tokenName, method, expectation.expected, attempted);
     }
-  }
-  async deliver(event) {
-    for (const handler of [...this.handlers]) {
-      await handler(event);
+    state.actual = attempted;
+    const call = {
+      index: attempted,
+      args: [...args],
+      pending: false,
+      timestamp: Date.now()
+    };
+    state.calls.push(call);
+    let behavior;
+    const base = descriptor.kind === "expect" ? descriptor.behavior ?? "original-effective" : descriptor.kind === "watch" ? descriptor.wrapper ?? "original-effective" : descriptor;
+    if (base !== "original-effective" && typeof base !== "function" && base !== void 0 && base.kind === "calls") {
+      if (state.scriptCursor >= base.script.length) {
+        throw new CallScriptExhaustedError(state.tokenName, method, base.script.length, attempted);
+      }
+      behavior = base.script[state.scriptCursor];
+      state.scriptCursor += 1;
+    } else {
+      behavior = base;
     }
-  }
-};
-
-// src/observability/recording_sinks.ts
-import { LogSink, TelemetrySink, TraceSink } from "@noego/runtime";
-var RecordingLogSink = class extends LogSink {
-  envelopes = [];
-  emit(envelope) {
-    this.envelopes.push(envelope);
-  }
-};
-var RecordingTraceSink = class extends TraceSink {
-  envelopes = [];
-  emit(envelope) {
-    this.envelopes.push(envelope);
-  }
-};
-var RecordingTelemetrySink = class extends TelemetrySink {
-  envelopes = [];
-  emit(envelope) {
-    this.envelopes.push(envelope);
-  }
-};
-var NoopLogSink = class extends LogSink {
-  emit(_envelope) {
-  }
-};
-
-// src/contracts/clock.contract.ts
-function runClockContract(name, setup) {
-  describe(`Clock contract: ${name}`, () => {
-    it("returns a monotonically non-decreasing instant across consecutive reads", () => {
-      const { clock } = setup();
-      const first = clock.now();
-      const second = clock.now();
-      expect(second.isBefore(first)).toBe(false);
-    });
-    it("nowMs agrees with now()", () => {
-      const { clock } = setup();
-      const instant = clock.now();
-      const ms = clock.nowMs();
-      expect(ms).toBeGreaterThanOrEqual(instant.epochMilliseconds);
-    });
-  });
+    try {
+      let outcome;
+      if (behavior === "original-effective") {
+        outcome = callOriginal(this, args);
+      } else if (typeof behavior === "function") {
+        outcome = behavior((...inner) => callOriginal(this, inner)).apply(this, args);
+      } else if (behavior.kind === "returns") {
+        outcome = behavior.value;
+      } else if (behavior.kind === "throws") {
+        throw behavior.error;
+      } else if (behavior.kind === "original") {
+        outcome = callOriginal(this, args);
+      } else {
+        throw new TypeError(`Nested test.calls() scripts are not supported (${method}).`);
+      }
+      return recordOutcome(call, outcome, false);
+    } catch (error) {
+      recordOutcome(call, error, true);
+      throw error;
+    }
+  };
 }
 
-// src/contracts/key_value_store.contract.ts
-import { Duration as Duration3, jsonCodec, storageKey } from "@noego/runtime";
-function runKeyValueStoreContract(name, setup) {
-  const codec = jsonCodec();
-  describe(`KeyValueStore contract: ${name}`, () => {
-    it("returns null for a missing key", async () => {
-      const { store } = setup();
-      await expect(store.get(storageKey("missing"), codec)).resolves.toBeNull();
-    });
-    it("round-trips a stored value", async () => {
-      const { store } = setup();
-      const key = storageKey("k1");
-      await store.put(key, { n: 42 }, codec);
-      await expect(store.get(key, codec)).resolves.toEqual({ n: 42 });
-    });
-    it("overwrites an existing value", async () => {
-      const { store } = setup();
-      const key = storageKey("k1");
-      await store.put(key, { n: 1 }, codec);
-      await store.put(key, { n: 2 }, codec);
-      await expect(store.get(key, codec)).resolves.toEqual({ n: 2 });
-    });
-    it("deletes a value and tolerates deleting a missing key", async () => {
-      const { store } = setup();
-      const key = storageKey("k1");
-      await store.put(key, { n: 1 }, codec);
-      await store.delete(key);
-      await expect(store.get(key, codec)).resolves.toBeNull();
-      await expect(store.delete(storageKey("missing"))).resolves.toBeUndefined();
-    });
-    it("expires values after their TTL when TTL is supported", async () => {
-      const context = setup();
-      if (!context.supportsTtl) return;
-      const key = storageKey("expiring");
-      await context.store.put(key, { n: 7 }, codec, { timeToLive: Duration3.ofSeconds(30) });
-      await expect(context.store.get(key, codec)).resolves.toEqual({ n: 7 });
-      await context.advanceBy(Duration3.ofSeconds(31));
-      await expect(context.store.get(key, codec)).resolves.toBeNull();
-    });
-    it("keeps values without a TTL alive as time passes", async () => {
-      const context = setup();
-      const key = storageKey("durable");
-      await context.store.put(key, { n: 9 }, codec);
-      await context.advanceBy(Duration3.ofMinutes(60));
-      await expect(context.store.get(key, codec)).resolves.toEqual({ n: 9 });
-    });
-  });
+// src/builder.ts
+var COMPONENT_OPTIONS_KEY = /* @__PURE__ */ Symbol.for("ioc:component:options");
+function* configEntries(config) {
+  if (config instanceof Map) {
+    for (const [key, value] of config) yield [key, false, value];
+  } else {
+    for (const key of [...Object.getOwnPropertyNames(config), ...Object.getOwnPropertySymbols(config)]) {
+      yield [key, typeof key === "string", config[key]];
+    }
+  }
 }
-
-// src/contracts/object_store.contract.ts
-import { objectKey } from "@noego/runtime";
-function runObjectStoreContract(name, setup) {
-  const bytes = (...values) => new Uint8Array(values);
-  describe(`ObjectStore contract: ${name}`, () => {
-    it("returns null for a missing object", async () => {
-      const { store } = setup();
-      await expect(store.read(objectKey("missing"))).resolves.toBeNull();
-    });
-    it("round-trips bytes, content type, and metadata", async () => {
-      const { store } = setup();
-      const key = objectKey("docs/a.bin");
-      await store.write(key, {
-        bytes: bytes(1, 2, 3),
-        contentType: "application/octet-stream",
-        metadata: /* @__PURE__ */ new Map([["owner", "alice"]])
-      });
-      const stored = await store.read(key);
-      expect(stored).not.toBeNull();
-      expect([...stored.bytes]).toEqual([1, 2, 3]);
-      expect(stored.contentType).toBe("application/octet-stream");
-      expect(stored.metadata?.get("owner")).toBe("alice");
-    });
-    it("issues a new version on every write", async () => {
-      const { store } = setup();
-      const key = objectKey("docs/a.bin");
-      const v1 = await store.write(key, { bytes: bytes(1), contentType: "text/plain" });
-      const v2 = await store.write(key, { bytes: bytes(2), contentType: "text/plain" });
-      expect(v1).not.toBe(v2);
-      const stored = await store.read(key);
-      expect(stored.version).toBe(v2);
-      expect([...stored.bytes]).toEqual([2]);
-    });
-    it("deletes an object and tolerates deleting a missing key", async () => {
-      const { store } = setup();
-      const key = objectKey("docs/a.bin");
-      await store.write(key, { bytes: bytes(1), contentType: "text/plain" });
-      await store.delete(key);
-      await expect(store.read(key)).resolves.toBeNull();
-      await expect(store.delete(objectKey("missing"))).resolves.toBeUndefined();
-    });
-    it("does not expose caller mutations of written bytes", async () => {
-      const { store } = setup();
-      const key = objectKey("docs/mutable.bin");
-      const input = bytes(9);
-      await store.write(key, { bytes: input, contentType: "text/plain" });
-      input[0] = 0;
-      const stored = await store.read(key);
-      expect([...stored.bytes]).toEqual([9]);
-    });
-  });
+function componentScope(cls) {
+  const options = typeof Reflect !== "undefined" && Reflect.getMetadata ? Reflect.getMetadata(COMPONENT_OPTIONS_KEY, cls) : void 0;
+  return options?.scope;
 }
-
-// src/contracts/event_bus.contract.ts
-var testEvent = (value) => ({ type: "test-event", value });
-function runEventBusContract(name, setup) {
-  describe(`EventBus contract: ${name}`, () => {
-    it("delivers published events to subscribers in order", async () => {
-      const { bus, deliver } = setup();
-      const seen = [];
-      const subscription = bus.subscribe((event) => {
-        seen.push(event.value);
-      });
-      await bus.publish(testEvent(1));
-      await bus.publish(testEvent(2));
-      await deliver();
-      expect(seen).toEqual([1, 2]);
-      subscription.unsubscribe();
-    });
-    it("stops delivering after unsubscribe", async () => {
-      const { bus, deliver } = setup();
-      const seen = [];
-      const subscription = bus.subscribe((event) => {
-        seen.push(event.value);
-      });
-      await bus.publish(testEvent(1));
-      await deliver();
-      subscription.unsubscribe();
-      await bus.publish(testEvent(2));
-      await deliver();
-      expect(seen).toEqual([1]);
-    });
-    it("supports multiple subscribers", async () => {
-      const { bus, deliver } = setup();
-      const a = [];
-      const b = [];
-      const sa = bus.subscribe((event) => {
-        a.push(event.value);
-      });
-      const sb = bus.subscribe((event) => {
-        b.push(event.value);
-      });
-      await bus.publish(testEvent(5));
-      await deliver();
-      expect(a).toEqual([5]);
-      expect(b).toEqual([5]);
-      sa.unsubscribe();
-      sb.unsubscribe();
-    });
-    it("marks subscriptions inactive after unsubscribe and tolerates double unsubscribe", async () => {
-      const { bus, deliver } = setup();
-      const seen = [];
-      const subscription = bus.subscribe((event) => {
-        seen.push(event.value);
-      });
-      await bus.publish(testEvent(1));
-      await deliver();
-      expect(seen).toEqual([1]);
-      expect(subscription.active).toBe(true);
-      subscription.unsubscribe();
-      expect(subscription.active).toBe(false);
-      subscription.unsubscribe();
-      expect(subscription.active).toBe(false);
-    });
-  });
+function lifetimeToLoadAs(lifetime) {
+  if (lifetime === "singleton") return LoadAs.Singleton;
+  if (lifetime === "scoped") return LoadAs.Scoped;
+  return LoadAs.Transient;
 }
-
-// src/leak/leak_detector.ts
-var LeakDetector = class {
-  checks = [];
-  register(check) {
-    this.checks.push(check);
-  }
-  findLeaks() {
-    const leaks = [];
-    for (const { name, check } of this.checks) {
-      for (const description of check()) {
-        leaks.push(`[${name}] ${description}`);
+var TestIocBuilder = class _TestIocBuilder {
+  constructor(log) {
+    this.log = log;
+    Object.freeze(this);
+  }
+  log;
+  /** @internal */
+  static create(inputs) {
+    return new _TestIocBuilder([]).useAll(inputs);
+  }
+  /** @internal — read by .use(builderPreset) */
+  get writes() {
+    return this.log;
+  }
+  derive(writes) {
+    return new _TestIocBuilder([...this.log, ...writes]);
+  }
+  useAll(inputs) {
+    let builder = this;
+    for (const input of inputs) builder = builder.use(input);
+    return builder;
+  }
+  /** Apply a reusable composition preset: an ApplicationModule or a builder. */
+  use(preset) {
+    if (preset instanceof _TestIocBuilder) {
+      return this.derive([...preset.writes]);
+    }
+    return this.derive([{ op: "use", module: preset }]);
+  }
+  /** Replace the implementation for IoC class tokens in the built environment. */
+  classes(config) {
+    const writes = [];
+    for (const [key, byName, implementation] of configEntries(config)) {
+      if (typeof implementation !== "function" || !implementation.prototype) {
+        throw new InvalidDescriptorError(
+          `.classes() value for "${tokenLabel(key)}" must be a class constructor.`
+        );
+      }
+      writes.push({ op: "classes", key, byName, implementation });
+    }
+    return this.derive(writes);
+  }
+  /** Replace IoC factory/provider registrations. */
+  functions(config) {
+    const writes = [];
+    for (const [key, byName, factory] of configEntries(config)) {
+      if (typeof factory !== "function") {
+        throw new InvalidDescriptorError(`.functions() value for "${tokenLabel(key)}" must be a function.`);
       }
+      writes.push({ op: "functions", key, byName, factory });
     }
-    return leaks;
+    return this.derive(writes);
   }
-  assertNoLeaks() {
-    const leaks = this.findLeaks();
-    if (leaks.length > 0) {
-      throw new Error(`LeakDetector: ${leaks.length} leaked resource(s):
-${leaks.join("\n")}`);
+  /** Provide/replace IoC value registrations. */
+  values(config) {
+    const writes = [];
+    for (const [key, byName, value] of configEntries(config)) {
+      writes.push({ op: "values", key, byName, value });
+    }
+    return this.derive(writes);
+  }
+  /** Install method behavior/observation descriptors on IoC-managed instances. */
+  methods(config) {
+    const writes = [];
+    for (const [key, byName, methodsInput] of configEntries(config)) {
+      const methods = /* @__PURE__ */ new Map();
+      const entries = methodsInput instanceof Map ? methodsInput.entries() : Object.entries(methodsInput);
+      for (const [name, descriptor] of entries) {
+        if (typeof descriptor !== "function" && !isDescriptor(descriptor)) {
+          throw new InvalidDescriptorError(
+            `.methods() entry ${tokenLabel(key)}.${name} must be a test.* descriptor or a raw wrapper function.`
+          );
+        }
+        methods.set(name, descriptor);
+      }
+      writes.push({ op: "methods", key, byName, methods });
+    }
+    return this.derive(writes);
+  }
+  /** Materialize a fresh, isolated real-IoC environment. Non-consuming. */
+  async build() {
+    const root = createContainer();
+    if (typeof root.setInstanceDecorator !== "function") {
+      throw new MissingIocSeamError();
+    }
+    const knownByName = /* @__PURE__ */ new Map();
+    const knownLifetimes = /* @__PURE__ */ new Map();
+    const note = (token, loadAs) => {
+      if (typeof token === "function" && token.name) knownByName.set(token.name, token);
+      else if (typeof token === "string") knownByName.set(token, token);
+      if (loadAs !== void 0) knownLifetimes.set(token, loadAs);
+    };
+    const effective = /* @__PURE__ */ new Map();
+    const methodWrites = [];
+    const resolveKey = (key, byName, space) => {
+      if (!byName) return key;
+      const known = knownByName.get(key);
+      if (known !== void 0) return known;
+      if (space === "values" || space === "functions") return key;
+      throw new UnknownTokenKeyError(key, space, [...knownByName.keys()]);
+    };
+    for (const write of this.log) {
+      switch (write.op) {
+        case "use": {
+          for (const reg of flattenModule(write.module)) {
+            const loadAs = lifetimeToLoadAs(reg.lifetime);
+            note(reg.token, loadAs);
+            if (reg.kind === "class") {
+              note(reg.implementation, loadAs);
+              effective.set(reg.token, {
+                space: "class",
+                token: reg.token,
+                implementation: reg.implementation,
+                loadAs
+              });
+              knownLifetimes.set(reg.token, loadAs);
+              knownLifetimes.set(reg.implementation, loadAs);
+            } else if (reg.kind === "factory") {
+              effective.set(reg.token, {
+                space: "factory",
+                token: reg.token,
+                factory: reg.implementation,
+                loadAs,
+                deps: [...reg.dependencies]
+              });
+            } else {
+              effective.set(reg.token, { space: "value", token: reg.token, value: reg.implementation });
+              knownLifetimes.set(reg.token, LoadAs.Singleton);
+            }
+          }
+          break;
+        }
+        case "classes": {
+          const token = resolveKey(write.key, write.byName, "classes");
+          note(write.implementation, void 0);
+          if (!write.byName) note(token, void 0);
+          effective.set(token, {
+            space: "class",
+            token,
+            implementation: write.implementation,
+            // preserve configured lifetime unless the replacement declares its own scope
+            loadAs: componentScope(write.implementation) ?? knownLifetimes.get(token)
+          });
+          break;
+        }
+        case "functions": {
+          const token = resolveKey(write.key, write.byName, "functions");
+          const prior = effective.get(token);
+          effective.set(token, {
+            space: "factory",
+            token,
+            factory: write.factory,
+            // preserve configured lifetime unless the scenario overrides it
+            loadAs: prior && prior.space === "factory" ? prior.loadAs : knownLifetimes.get(token),
+            deps: prior && prior.space === "factory" ? prior.deps : void 0
+          });
+          note(token, void 0);
+          break;
+        }
+        case "values": {
+          const token = resolveKey(write.key, write.byName, "values");
+          effective.set(token, { space: "value", token, value: write.value });
+          note(token, LoadAs.Singleton);
+          break;
+        }
+        case "methods": {
+          const token = write.byName && knownByName.has(write.key) ? knownByName.get(write.key) : write.key;
+          methodWrites.push({
+            key: token,
+            byName: write.byName && !knownByName.has(write.key),
+            methods: new Map(write.methods)
+          });
+          break;
+        }
+      }
+    }
+    for (const entry of effective.values()) {
+      if (entry.space === "class") {
+        this.registerClassBinding(root, entry.token, entry.implementation, entry.loadAs);
+      } else if (entry.space === "factory") {
+        root.registerFunction(entry.token, entry.factory, {
+          loadAs: entry.loadAs,
+          param: entry.deps
+        });
+      } else {
+        const value = entry.value;
+        root.registerFunction(entry.token, () => value, { loadAs: LoadAs.Singleton });
+      }
+    }
+    const registry = new WatchRegistry();
+    const mergedMethods = /* @__PURE__ */ new Map();
+    for (const write of methodWrites) {
+      const existing = mergedMethods.get(write.key);
+      if (existing) {
+        for (const [name, descriptor] of write.methods) existing.methods.set(name, descriptor);
+      } else {
+        mergedMethods.set(write.key, { byName: write.byName, methods: new Map(write.methods) });
+      }
+    }
+    for (const [key, { byName, methods }] of mergedMethods) {
+      registry.addEntry({ key, byName, methods });
+    }
+    root.setInstanceDecorator(createMethodDecorator(registry));
+    const env = {
+      root,
+      get: (token, params) => root.get(token, params),
+      instance: (cls, params) => root.instance(cls, params),
+      extend: () => root.extend(),
+      verify: async () => registry.verify(),
+      dispose: () => root.dispose(),
+      [ENV_REGISTRY]: registry
+    };
+    return env;
+  }
+  /**
+   * Register a class binding. When token === implementation this is a plain
+   * class registration. Otherwise an alias factory resolves the implementation
+   * through real IoC, mirroring the implementation's effective lifetime so
+   * lifetime validation (captive-lifetime checks) stays honest.
+   */
+  registerClassBinding(root, token, implementation, configuredLoadAs) {
+    const loadAs = configuredLoadAs ?? componentScope(implementation) ?? LoadAs.Transient;
+    root.registerClass(implementation, configuredLoadAs !== void 0 ? { loadAs } : void 0);
+    if (token === implementation) return;
+    if (loadAs === LoadAs.Singleton) {
+      root.registerFunction(token, () => root.get(implementation), {
+        loadAs: LoadAs.Singleton
+      });
+    } else {
+      root.registerFunction(token, (scope) => scope.get(implementation), {
+        loadAs,
+        param: [SCOPED_CONTAINER]
+      });
     }
   }
 };
+function testIoc(...inputs) {
+  return TestIocBuilder.create(inputs);
+}
 export {
-  LeakDetector,
-  ManualClock,
-  ManualScheduler,
-  MemoryKeyValueStore,
-  MemoryObjectStore,
-  NoopLogSink,
-  RecordingEventBus,
-  RecordingLogSink,
-  RecordingTelemetrySink,
-  RecordingTraceSink,
-  ScriptedFetchClient,
-  ScriptedProcessRunner,
-  SeededRandomSource,
-  SequenceIdGenerator,
-  runClockContract,
-  runEventBusContract,
-  runKeyValueStoreContract,
-  runObjectStoreContract,
-  testEvent
+  CallScriptExhaustedError,
+  ENV_REGISTRY,
+  ExpectationOverflowError,
+  InvalidDescriptorError,
+  MethodNotCallableError,
+  MissingIocSeamError,
+  NonObjectMethodTargetError,
+  TestIocBuilder,
+  TestingError,
+  UnknownTokenKeyError,
+  UnwatchedInspectionError,
+  VerificationError,
+  test,
+  testIoc
 };
 //# sourceMappingURL=index.js.map