@cosmicdrift/kumiko-framework 0.158.2 → 0.160.0

package/src/pipeline/multi-stream-apply-context.ts

@@ -1,50 +1,12 @@
+import type { MultiStreamApplyContext } from "@cosmicdrift/kumiko-types/multi-stream-apply-context-types";
 import type { DbRunner } from "../db/connection";
-import type {
-  AppendEventArgs,
-  AppendEventFn,
-  KumikoEventTypeMap,
-  Registry,
-  TenantId,
-  UnsafeAppendEventFn,
-} from "../engine/types";
-import { loadAggregate, loadAggregateAsOf, type StoredEvent } from "../event-store/event-store";
+import type { AppendEventArgs, AppendEventFn, Registry, TenantId } from "../engine/types";
+import { loadAggregate, loadAggregateAsOf } from "../event-store/event-store";
 import { upcastStoredEvents } from "../event-store/upcaster";
 import type { FileContext } from "../files/file-handle";
 import { appendDomainEventCore } from "./append-event-core";
 
-// Minimal, read+write surface handed to a MultiStreamProjection's apply()
-// when it needs to produce follow-up events (saga / process-manager
-// pattern). Keeps the MSP feature-decoupled: applies don't reach into
-// handler-bridge (no query/write/writeAs), they just read the aggregate
-// stream and append new events — Marten's session scope for projections.
-//
-// TMap propagates the strict event-type-map (see HandlerContext). Default
-// matches the global KumikoEventTypeMap; runtime-pluggable callers route
-// through unsafeAppendEvent.
-export type MultiStreamApplyContext<TMap extends object = KumikoEventTypeMap> = {
-  // Append a domain event onto an aggregate stream in the CURRENT tx.
-  // Schema-validated, archive-guarded, stream-version derived. Metadata
-  // inherits from the triggering event (correlationId) + requestContext
-  // (causationId is already set to the triggering event.id by the
-  // dispatcher wrap). Strict against KumikoEventTypeMap — same contract
-  // as HandlerContext.appendEvent (compile-time-validated payload).
-  readonly appendEvent: AppendEventFn<TMap>;
-  // Escape hatch for runtime-pluggable events without compile-time
-  // augmentation. Same runtime semantics; type-surface is `payload: unknown`.
-  readonly unsafeAppendEvent: UnsafeAppendEventFn;
-  // Read an aggregate stream — useful when a saga needs to inspect the
-  // current state of a different aggregate before deciding what to emit.
-  readonly loadAggregate: (
-    aggregateId: string,
-    options?: { readonly asOf?: Temporal.Instant },
-  ) => Promise<readonly StoredEvent[]>;
-  // Binary storage handle factory, mirrors AppContext.files. Present when
-  // the app booted with `files.storageProvider`; undefined otherwise.
-  // Post-processing MSPs (resize, EXIF-strip, virus-scan) read bytes via
-  // `ctx.files.ref(payload.storageKey).read()` and write derivates via
-  // `.derive("thumb").write(...)` — binaries never ride through events.
-  readonly files?: FileContext;
-};
+export type { MultiStreamApplyContext } from "@cosmicdrift/kumiko-types/multi-stream-apply-context-types";
 
 export type MultiStreamApplyContextDeps = {
   readonly registry: Registry;

package/src/pipeline/system-hooks.ts

@@ -41,6 +41,13 @@ export function createSearchEventConsumer(
 ): EventConsumer {
   return {
     name: SEARCH_CONSUMER_NAME,
+    // ponytail: count-based maxAttempts, not real backoff — retries hammer
+    // the search adapter every pollIntervalMs during an outage instead of
+    // spacing out. 1200 attempts * 100ms default poll ~= 2min budget for a
+    // still-provisioning Meilisearch to come up at boot (was 10 = ~1s,
+    // killing the consumer near-instantly). Upgrade path: time-based
+    // dead-lettering in event-dispatcher-delivery.ts if 2min isn't enough.
+    errorPolicy: { maxAttempts: 1200 },
     handler: async (event) => {
       const entityName = event.aggregateType;
       const verb = event.type.split(".").pop();

package/src/rate-limit/resolver.ts

@@ -1,3 +1,8 @@
+import type {
+  RateLimitConfig,
+  RateLimitDecision,
+  RateLimitResolver,
+} from "@cosmicdrift/kumiko-types/rate-limit-types";
 import type Redis from "ioredis";
 import { RateLimitError } from "../errors";
 import { RedisKeys } from "../pipeline/redis-keys";
@@ -108,36 +113,11 @@ end
 return { math.floor(tokens), retryAfterMs }
 `;
 
-export type RateLimitDecision = {
-  readonly allowed: boolean;
-  readonly limit: number;
-  readonly remaining: number;
-  readonly retryAfterSeconds: number;
-  readonly windowSeconds: number;
-  readonly resetAt: Temporal.Instant;
-};
-
-export type RateLimitConfig = {
-  readonly limit: number;
-  readonly windowSeconds: number;
-  readonly cost?: number;
-};
-
-export type RateLimitResolver = {
-  // Atomic check + deduct. Returns the decision and current bucket state
-  // — caller decides whether to throw RateLimitError or proceed.
-  check(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision>;
-
-  // Convenience: throws RateLimitError when blocked. Useful inside the
-  // dispatcher / middleware code-paths where the failure shape is fixed.
-  enforce(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision>;
-
-  // Read-only inspection: returns the same shape as check() but never
-  // mutates the bucket — no token deduction, no refill-timestamp update.
-  // Use for ops/status queries (e.g. "kumiko rl status user:42") that
-  // must observe the bucket without disturbing it.
-  peek(bucket: string, config: Omit<RateLimitConfig, "cost">): Promise<RateLimitDecision>;
-};
+export type {
+  RateLimitConfig,
+  RateLimitDecision,
+  RateLimitResolver,
+} from "@cosmicdrift/kumiko-types/rate-limit-types";
 
 export type RateLimitResolverOptions = {
   readonly redis: Redis;

package/src/search/types.ts

@@ -1,39 +1 @@
-import type { EntityId, TenantId } from "../engine/types/identifiers";
-
-export type SearchAdapterConfig = {
-  searchableFields: readonly string[];
-  rankingFields?: readonly string[];
-};
-
-export type SearchDocument = {
-  entityType: string;
-  entityId: EntityId;
-  weight: number;
-  fields: Record<string, unknown>;
-};
-
-export type SearchResult = {
-  entityType: string;
-  entityId: EntityId;
-};
-
-export type SearchOptions = {
-  limit?: number;
-  filterType?: string;
-};
-
-export type SearchAdapter = {
-  configure(tenantId: TenantId, config: SearchAdapterConfig): Promise<void>;
-  index(tenantId: TenantId, doc: SearchDocument): Promise<void>;
-  search(tenantId: TenantId, query: string, options?: SearchOptions): Promise<SearchResult[]>;
-  remove(tenantId: TenantId, entityType: string, entityId: EntityId): Promise<void>;
-  // Bulk variants. Default implementations loop over the single-doc methods —
-  // adapters should override when the backend supports a real batch call
-  // (Meilisearch, Elasticsearch, Typesense all do). Cuts a batch-write from
-  // N sequential HTTP + waitTask round-trips to one.
-  indexBatch?(tenantId: TenantId, docs: readonly SearchDocument[]): Promise<void>;
-  removeBatch?(
-    tenantId: TenantId,
-    items: readonly { entityType: string; entityId: EntityId }[],
-  ): Promise<void>;
-};
+export * from "@cosmicdrift/kumiko-types/search-adapter";

package/src/secrets/__tests__/envelope-cipher.test.ts

@@ -1,6 +1,5 @@
 import { describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
-import { createEncryptionProvider } from "../../db/encryption";
 import { createEnvMasterKeyProvider } from "../env-master-key-provider";
 import { createEnvelopeCipher } from "../envelope-cipher";
 import { isStoredEnvelope } from "../stored-envelope";
@@ -42,33 +41,6 @@ describe("envelope-cipher — encrypt/decrypt", () => {
   });
 });
 
-describe("envelope-cipher — legacy fallback", () => {
-  test("decrypts legacy single-key values when the legacy provider is configured", async () => {
-    const legacy = createEncryptionProvider(randomBytes(32).toString("base64"));
-    const legacyStored = legacy.encrypt("pre-envelope value");
-    // legacy wire format is base64 — never starts with "{"
-    expect(legacyStored.startsWith("{")).toBe(false);
-
-    const cipher = createEnvelopeCipher(makeProvider(), { legacy });
-    expect(await cipher.decrypt(legacyStored)).toBe("pre-envelope value");
-  });
-
-  test("throws with a remediation message when a legacy value has no legacy key", async () => {
-    const legacy = createEncryptionProvider(randomBytes(32).toString("base64"));
-    const legacyStored = legacy.encrypt("orphaned");
-
-    const cipher = createEnvelopeCipher(makeProvider());
-    await expect(cipher.decrypt(legacyStored)).rejects.toThrow(/legacy/);
-  });
-
-  test("never encrypts into the legacy format even when a legacy key is present", async () => {
-    const legacy = createEncryptionProvider(randomBytes(32).toString("base64"));
-    const cipher = createEnvelopeCipher(makeProvider(), { legacy });
-    const stored = await cipher.encrypt("always-envelope");
-    expect(stored.startsWith("{")).toBe(true);
-  });
-});
-
 describe("envelope-cipher — malformed input", () => {
   test("rejects invalid JSON that looks like an envelope", async () => {
     const cipher = createEnvelopeCipher(makeProvider());
@@ -80,8 +52,8 @@ describe("envelope-cipher — malformed input", () => {
     await expect(cipher.decrypt('{"foo":"bar"}')).rejects.toThrow(/not a StoredEnvelope/);
   });
 
-  test("empty string routes to the legacy branch and throws without a legacy key", async () => {
+  test("empty string is not valid JSON", async () => {
     const cipher = createEnvelopeCipher(makeProvider());
-    await expect(cipher.decrypt("")).rejects.toThrow(/legacy/);
+    await expect(cipher.decrypt("")).rejects.toThrow(/not valid JSON/);
   });
 });

package/src/secrets/__tests__/envelope.test.ts

@@ -53,7 +53,7 @@ describe("envelope — encryptValue/decryptValue", () => {
       ...envelope,
       ciphertext: Buffer.concat([
         envelope.ciphertext.subarray(0, 1),
-        Buffer.from([envelope.ciphertext[0]! ^ 0xff]),
+        Buffer.from([envelope.ciphertext[1]! ^ 0xff]),
         envelope.ciphertext.subarray(2),
       ]),
     };

package/src/secrets/envelope-cipher.ts

@@ -1,40 +1,24 @@
 // String-in/string-out envelope encryption for TEXT-column stores (config
 // values, entity fields). The stored string is JSON of StoredEnvelope; the
 // kekVersion inside makes every value rotatable via the MasterKeyProvider
-// keyring — unlike the legacy createEncryptionProvider format (raw
-// base64(iv+tag+ct), no key id), which this cipher still DECRYPTS through
-// the optional legacy provider so pre-envelope rows stay readable until a
-// re-encrypt job has migrated them.
+// keyring.
 
-import type { EncryptionProvider } from "../db/encryption";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-types/envelope-cipher-types";
 import { InternalError } from "../errors/classes";
 import type { DekCache } from "./dek-cache";
 import { createDekCache, withDekCache } from "./dek-cache";
 import { decryptValue, encryptValue } from "./envelope";
 import { decodeStoredEnvelope, encodeStoredEnvelope, isStoredEnvelope } from "./stored-envelope";
-import type { KeyScope, MasterKeyProvider } from "./types";
+import type { MasterKeyProvider } from "./types";
+
+export type { EnvelopeCipher } from "@cosmicdrift/kumiko-types/envelope-cipher-types";
 
 export type EnvelopeCipherOptions = {
-  // Decrypt-only fallback for legacy createEncryptionProvider ciphertexts
-  // (CONFIG_ENCRYPTION_KEY / ENCRYPTION_KEY era). Never used for encrypt.
-  readonly legacy?: EncryptionProvider;
   // Shared DEK cache — pass the app-wide instance so config/entity reads
   // amortise KEK unwraps together with ctx.secrets.
   readonly dekCache?: DekCache;
 };
 
-export type EnvelopeCipher = {
-  encrypt(plaintext: string, scope?: KeyScope): Promise<string>;
-  decrypt(stored: string, scope?: KeyScope): Promise<string>;
-};
-
-// Format detection: envelope values are JSON objects, so they start with
-// "{" — a character the base64 alphabet of the legacy format can never
-// produce. No version byte or prefix marker needed.
-function isEnvelopeFormat(stored: string): boolean {
-  return stored.startsWith("{");
-}
-
 export function createEnvelopeCipher(
   provider: MasterKeyProvider,
   opts: EnvelopeCipherOptions = {},
@@ -48,34 +32,22 @@ export function createEnvelopeCipher(
     },
 
     async decrypt(stored, scope) {
-      if (isEnvelopeFormat(stored)) {
-        let parsed: unknown;
-        try {
-          parsed = JSON.parse(stored);
-        } catch {
-          throw new InternalError({
-            message: "[envelope-cipher] stored value looks like an envelope but is not valid JSON",
-            i18nKey: "secrets.errors.envelope_malformed",
-          });
-        }
-        if (!isStoredEnvelope(parsed)) {
-          throw new InternalError({
-            message: "[envelope-cipher] stored JSON is not a StoredEnvelope",
-            i18nKey: "secrets.errors.envelope_malformed",
-          });
-        }
-        return decryptValue(decodeStoredEnvelope(parsed), cached, scope);
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(stored);
+      } catch {
+        throw new InternalError({
+          message: "[envelope-cipher] stored value is not valid JSON",
+          i18nKey: "secrets.errors.envelope_malformed",
+        });
       }
-
-      if (!opts.legacy) {
+      if (!isStoredEnvelope(parsed)) {
         throw new InternalError({
-          message:
-            "[envelope-cipher] value is in the legacy single-key format but no legacy key is configured — " +
-            "provision the legacy key (CONFIG_ENCRYPTION_KEY / ENCRYPTION_KEY) or run the re-encrypt job first",
-          i18nKey: "secrets.errors.legacy_key_missing",
+          message: "[envelope-cipher] stored JSON is not a StoredEnvelope",
+          i18nKey: "secrets.errors.envelope_malformed",
         });
       }
-      return opts.legacy.decrypt(stored);
+      return decryptValue(decodeStoredEnvelope(parsed), cached, scope);
     },
   };
 }

package/src/secrets/types.ts

@@ -1,177 +1,2 @@
-// Envelope Encryption types. Separating DEK (per-value) from KEK (central)
-// is what makes key rotation cheap: on rotation we only re-wrap the small
-// encryptedDek, never touch the ciphertext.
-
-import type { TenantId } from "../engine";
-
-// Plaintext-secret wrapper (branded). Carries the actual string internally
-// but the nominal typing stops it from landing in an HTTP response by
-// accident — a response-serializer guard + the reveal() cost make the leak
-// intentional. Framework code that sees `Secret<string>` knows the caller
-// has already gone through the audited ctx.secrets.get path.
-//
-// The brand is a real (non-registered) Symbol so it exists at runtime for
-// isSecret() without clashing with user-land symbols of the same name.
-const SecretBrand: unique symbol = Symbol("kumiko.secret");
-
-export type Secret<T = string> = {
-  readonly [SecretBrand]: true;
-  readonly reveal: () => T;
-};
-
-// Implementation helper — bundled-features uses this to wrap a plaintext after
-// decryption. Kept in the framework so both sides share one canonical brand.
-export function createSecret<T>(value: T): Secret<T> {
-  return {
-    [SecretBrand]: true as const,
-    reveal: () => value,
-  };
-}
-
-// True for any object carrying the Secret brand. Used by the response guard
-// to reject leaks before serialization.
-export function isSecret(v: unknown): v is Secret<unknown> {
-  return typeof v === "object" && v !== null && SecretBrand in v;
-}
-
-// --- Compile-time response guard (R6) --------------------------------------
-//
-// ContainsSecret<T> is `true` only when a Secret<> is DEFINITELY present
-// somewhere in T. The handler-registration guard (defineWriteHandler/
-// defineQueryHandler) turns a `true` into a compile error — the static twin of
-// assertNoSecretLeak's runtime walk.
-//
-// Biased to `false`: anything it cannot inspect — a bare generic type param (a
-// handler generic over its response), `unknown`/`any`, `never` — resolves to
-// `false` = allowed, with the runtime guard as the backstop. The alternative
-// (default-to-leak) false-flags every legitimate generic-over-response handler.
-//
-// Branch order is load-bearing: never/unknown/any first (uninspectable), then
-// Secret, then primitives (covers branded primitives like TenantId without
-// enumerating them), then the SafeLeaf allowlist (opaque class instances that
-// blind `{ [K in keyof T] }` recursion would mangle — the type-level mirror of
-// leak-guard.ts skipping non-plain objects), then arrays, then a "does any
-// field contain a secret" fold over plain objects.
-type Primitive = string | number | boolean | bigint | symbol | null | undefined;
-
-// Opaque built-in leaves a response legitimately carries; never recurse into
-// them. Extend when the bundled-features tsc sweep surfaces a real leaf type.
-// Map/Set (556/2): `keyof Map<K,V>` yields method names, not V, so these
-// already fell through to `false` via the object-mapped-type branch — listed
-// explicitly here so the compile-time treatment matches leak-guard.ts's
-// runtime `instanceof Map`/`instanceof Set` branch (walk entries separately)
-// instead of looking like an oversight.
-type SafeLeaf =
-  | Date
-  | RegExp
-  | Temporal.Instant
-  | Temporal.ZonedDateTime
-  | Temporal.PlainDate
-  | Temporal.PlainDateTime
-  | Temporal.PlainTime
-  | Temporal.PlainYearMonth
-  | Temporal.PlainMonthDay
-  | Temporal.Duration
-  | Map<unknown, unknown>
-  | Set<unknown>;
-
-export type ContainsSecret<T> = [T] extends [never]
-  ? false
-  : unknown extends T
-    ? false
-    : T extends Secret<unknown>
-      ? true
-      : T extends Primitive
-        ? false
-        : T extends SafeLeaf
-          ? false
-          : T extends readonly (infer U)[]
-            ? ContainsSecret<U>
-            : T extends object
-              ? true extends { [K in keyof T]-?: ContainsSecret<T[K]> }[keyof T]
-                ? true
-                : false
-              : false;
-
-// Per-read audit context. Populated by requireSecretsContext() wrapper so
-// handlers don't need to pass userId/handlerName manually on every call.
-// Undefined for framework-internal reads (rotation job, tests) — the audit
-// table stays a "who touched this credential" log, not a crash-report sink.
-export type SecretAuditContext = {
-  readonly userId: string;
-  readonly handlerName: string;
-};
-
-// Feature code can pass either the raw qualified-name string or a typed
-// handle returned by r.secret. The handle form is safer — renaming the
-// r.secret call updates all references through the import graph.
-export type SecretKeyRef = string | { readonly name: string };
-
-// The ctx.secrets contract. Concrete implementation lives in bundled-features
-// (createSecretsContext) where the DB and MasterKeyProvider are known. This
-// lean interface is what the framework's HandlerContext carries so engine
-// code can talk about it without pulling in bundled-features.
-export interface SecretsContext {
-  get(
-    tenantId: TenantId,
-    key: SecretKeyRef,
-    auditCtx?: SecretAuditContext,
-  ): Promise<Secret<string> | undefined>;
-  // Metadata-only existence probe: no decryption, no read-audit event.
-  // For readiness checks — use get() when the value itself is needed.
-  has(tenantId: TenantId, key: SecretKeyRef): Promise<boolean>;
-  set(
-    tenantId: TenantId,
-    key: SecretKeyRef,
-    value: string,
-    opts?: { redact?: (plaintext: string) => string; hint?: string; updatedBy?: string },
-  ): Promise<void>;
-  delete(tenantId: TenantId, key: SecretKeyRef, opts?: { deletedBy?: string }): Promise<boolean>;
-}
-
-export type Envelope = {
-  // AES-256-GCM ciphertext of the plaintext, keyed with a DEK.
-  readonly ciphertext: Buffer;
-  // GCM nonce (12 bytes). Generated fresh per encryption.
-  readonly iv: Buffer;
-  // GCM auth tag (16 bytes). Guarantees the ciphertext wasn't tampered.
-  readonly authTag: Buffer;
-  // DEK wrapped with the current KEK. Decryption needs provider.unwrapDek
-  // with the kekVersion to recover the DEK.
-  readonly encryptedDek: Buffer;
-  // Which KEK version was used to wrap the DEK. On rotation, rows with old
-  // versions still decrypt — the provider keeps a keyring of historical KEKs.
-  readonly kekVersion: number;
-};
-
-// BYOK hook: callers pass the tenant a value belongs to; a per-tenant-KMS
-// provider keys its wrap/unwrap on it. EnvMasterKeyProvider (app-wide
-// keyring) ignores it — the param exists so the contract doesn't have to
-// break when a tenant-scoped provider ships.
-export type KeyScope = {
-  readonly tenantId?: TenantId;
-};
-
-// The contract a KEK backend must fulfil. The framework sees only this
-// interface; concrete implementations live in separate packages
-// (@cosmicdrift/kumiko-secrets-vault, @cosmicdrift/kumiko-secrets-aws-kms, ...). The default is
-// EnvMasterKeyProvider which reads keys from environment variables.
-export interface MasterKeyProvider {
-  // Wrap a fresh DEK with the current KEK. Returns the wrapped bytes + the
-  // KEK version used — the version ends up in the Envelope so decryption
-  // later knows which KEK to ask for.
-  wrapDek(dek: Buffer, scope?: KeyScope): Promise<{ encryptedDek: Buffer; kekVersion: number }>;
-
-  // Unwrap a previously-wrapped DEK. During rotation the provider must
-  // accept older kekVersion values (2-version window minimum), otherwise
-  // old rows become unreadable.
-  unwrapDek(encryptedDek: Buffer, kekVersion: number, scope?: KeyScope): Promise<Buffer>;
-
-  // Which KEK version new wraps use. Rotation flips this to a new value
-  // and older-version reads continue to work until rows are re-wrapped.
-  currentVersion(): number;
-
-  // Health check: can the provider talk to its backend? Used by
-  // /health/ready. Cheap probe, no KEK material read.
-  isAvailable(): Promise<boolean>;
-}
+// Legacy path — re-exported for callers still importing this module directly.
+export * from "@cosmicdrift/kumiko-types/secrets-types";

package/src/stack/__tests__/event-collector.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import type { SseEvent } from "../../api/sse-broker";
+import type { SaveContext } from "../../engine/types";
+import { createEventCollector } from "../event-collector";
+
+const probeSseEvent: SseEvent = { type: "probe", data: {} };
+const probeSaveContext: SaveContext = {
+  kind: "save",
+  id: "e1",
+  data: {},
+  changes: {},
+  previous: {},
+  isNew: true,
+};
+
+describe("createEventCollector", () => {
+  test("starts empty", () => {
+    const collector = createEventCollector();
+    expect(collector.sse).toEqual([]);
+    expect(collector.postSave).toEqual([]);
+  });
+
+  test("reset() clears both arrays in place, keeping the same references", () => {
+    const collector = createEventCollector();
+    const sseRef = collector.sse;
+    const postSaveRef = collector.postSave;
+    collector.sse.push(probeSseEvent);
+    collector.postSave.push(probeSaveContext);
+
+    expect(collector.sse).toHaveLength(1);
+    expect(collector.postSave).toHaveLength(1);
+
+    collector.reset();
+
+    expect(collector.sse).toHaveLength(0);
+    expect(collector.postSave).toHaveLength(0);
+    // Same array instances — callers that captured a reference before reset
+    // still see the cleared state, not a stale snapshot.
+    expect(collector.sse).toBe(sseRef);
+    expect(collector.postSave).toBe(postSaveRef);
+  });
+});

package/src/testing/__tests__/late-bound.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+import { createLateBoundHolder } from "../late-bound";
+
+describe("createLateBoundHolder", () => {
+  test("isReady is false and get() throws before set()", () => {
+    const holder = createLateBoundHolder<number>("thing");
+    expect(holder.isReady()).toBe(false);
+    expect(() => holder.get()).toThrow(/thing accessed before set\(\) was called/);
+  });
+
+  test("get() returns the stored value after set()", () => {
+    const holder = createLateBoundHolder<{ n: number }>();
+    const value = { n: 42 };
+    holder.set(value);
+    expect(holder.isReady()).toBe(true);
+    expect(holder.get()).toBe(value);
+  });
+
+  test("set() can be called again to replace the value", () => {
+    const holder = createLateBoundHolder<string>();
+    holder.set("first");
+    holder.set("second");
+    expect(holder.get()).toBe("second");
+  });
+});

package/src/testing/__tests__/wait-for.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import { waitFor } from "../wait-for";
+
+describe("waitFor", () => {
+  test("returns immediately once fn succeeds on the first attempt", async () => {
+    let calls = 0;
+    await waitFor(
+      () => {
+        calls++;
+      },
+      { delays: [1, 1, 1] },
+    );
+    expect(calls).toBe(1);
+  });
+
+  test("retries on failure and succeeds once fn passes", async () => {
+    let calls = 0;
+    await waitFor(
+      () => {
+        calls++;
+        if (calls < 3) throw new Error(`not yet (${calls})`);
+      },
+      { delays: [1, 1, 1] },
+    );
+    expect(calls).toBe(3);
+  });
+
+  test("throws the last error once every attempt in the schedule fails", async () => {
+    let calls = 0;
+    await expect(
+      waitFor(
+        () => {
+          calls++;
+          throw new Error(`fail-${calls}`);
+        },
+        { delays: [1, 1] },
+      ),
+    ).rejects.toThrow("fail-2");
+    expect(calls).toBe(2);
+  });
+
+  test("supports an async fn", async () => {
+    let calls = 0;
+    await waitFor(
+      async () => {
+        calls++;
+        if (calls < 2) throw new Error("not yet");
+      },
+      { delays: [1, 1] },
+    );
+    expect(calls).toBe(2);
+  });
+});

package/src/testing/boot-validator-fixture.ts

@@ -1,11 +1,11 @@
 import { SEARCHABLE_FALSE_WHITELIST } from "../engine/boot-validator/entity-list-screens";
+import { normalizeListColumn } from "../engine/screen-helpers";
 import type {
   EntityDefinition,
   EntityListScreenDefinition,
   FeatureDefinition,
   TranslationEntry,
 } from "../engine/types";
-import { normalizeListColumn } from "../engine/types/screen";
 import { featureHasI18nSurface, requiredKeysFromFeature } from "../i18n/required-surface-keys";
 
 function ensureEntityListSortable(feature: FeatureDefinition): FeatureDefinition {