@cosmicdrift/kumiko-framework 0.230.0 → 0.232.0

package/src/engine/__tests__/steps-workflow.test.ts

@@ -1,5 +1,6 @@
 import { beforeEach, describe, expect, it, mock } from "bun:test";
 import { getStep } from "../define-step";
+import { evaluateEventMatch } from "../steps/_event-match";
 import {
   SUSPEND_SENTINEL,
   WORKFLOW_AGGREGATE_TYPE,
@@ -9,7 +10,12 @@ import {
 import { buildRetryStep, calculateBackoff } from "../steps/retry";
 import { buildWaitStep } from "../steps/wait";
 import { buildWaitForEventStep } from "../steps/wait-for-event";
-import type { PipelineCtx } from "../types/step";
+import type { AwaitedEventType, EventMatch, PipelineCtx } from "../types/step";
+
+// Test-only helper for the low-level step-builder unit tests below, which
+// call buildWaitForEventStep directly instead of going through a
+// defineWorkflow `awaits` declaration (the only legitimate branding route).
+const asAwaited = (event: string): AwaitedEventType => event as AwaitedEventType;
 
 const mockUnsafeAppendEvent = mock();
 
@@ -90,20 +96,31 @@ describe("workflow.wait run", () => {
 describe("buildWaitForEventStep", () => {
   it("returns a StepInstance with kind workflow.waitForEvent", () => {
     const step = buildWaitForEventStep({
-      event: "user.confirmed-email",
+      event: asAwaited("user.confirmed-email"),
       timeout: "P7D",
     });
     expect(step.kind).toBe("workflow.waitForEvent");
   });
 
-  it("accepts an optional match resolver", () => {
+  it("accepts an optional match AST", () => {
+    const match: EventMatch = {
+      version: 1,
+      expr: { kind: "atom", path: ["email"], op: { kind: "eq", value: "test@test.com" } },
+    };
     const step = buildWaitForEventStep({
-      event: "user.confirmed-email",
-      match: (payload: unknown) => (payload as { email: string }).email === "test@test.com",
+      event: asAwaited("user.confirmed-email"),
+      match,
       timeout: "P7D",
     });
     expect(step.kind).toBe("workflow.waitForEvent");
   });
+
+  it("@ts-expect-error: event must come from an awaits declaration, not a raw string", () => {
+    // @ts-expect-error — a raw string is not an AwaitedEventType; only
+    // defineWorkflow's `awaits` map can produce one (D4, workflow-resume-loop.md).
+    const step = buildWaitForEventStep({ event: "user.confirmed-email", timeout: "P7D" });
+    expect(step.kind).toBe("workflow.waitForEvent");
+  });
 });
 
 describe("workflow.waitForEvent run", () => {
@@ -138,6 +155,144 @@ describe("workflow.waitForEvent run", () => {
     expect(typeof eventArg.payload.timeoutAt).toBe("string");
     expect(eventArg.payload.workflowName).toBe("test-workflow");
   });
+
+  it("omits the match key from the payload when no match is given", async () => {
+    const stepDef = getStep("workflow.waitForEvent");
+    expect(stepDef).toBeDefined();
+
+    await stepDef!.run({ event: "user.confirmed-email", timeout: "P7D" }, workflowCtx);
+
+    const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
+    expect("match" in eventArg.payload).toBe(false);
+  });
+
+  it("resolves a match resolver to a serializable AST that round-trips through JSON and evaluates against real payloads", async () => {
+    const stepDef = getStep("workflow.waitForEvent");
+    expect(stepDef).toBeDefined();
+
+    const result = await stepDef!.run(
+      {
+        event: "user.confirmed-email",
+        match: (ctx: PipelineCtx): EventMatch => ({
+          version: 1,
+          expr: {
+            kind: "atom",
+            path: ["email"],
+            op: { kind: "eq", value: (ctx.event.payload as { email: string }).email },
+          },
+        }),
+        timeout: "P7D",
+      },
+      workflowCtx,
+    );
+
+    expect(result).toBe(SUSPEND_SENTINEL);
+    const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
+    const persistedMatch = eventArg.payload.match;
+
+    // Proves the persisted value is the resolved literal AST, not the resolver function.
+    expect(persistedMatch).toEqual({
+      version: 1,
+      expr: {
+        kind: "atom",
+        path: ["email"],
+        op: { kind: "eq", value: "test@example.com" },
+      },
+    });
+
+    // Proves serializability — the whole point of the AST switch — by round-tripping
+    // through JSON before feeding it to the evaluator, same as a rehydrated event would.
+    const roundTripped = JSON.parse(JSON.stringify(persistedMatch));
+    expect(evaluateEventMatch(roundTripped, { email: "test@example.com" })).toBe(true);
+    expect(evaluateEventMatch(roundTripped, { email: "someone-else@example.com" })).toBe(false);
+  });
+});
+
+describe("evaluateEventMatch", () => {
+  it("throws on an unsupported version", () => {
+    const stale = JSON.parse(
+      JSON.stringify({
+        version: 2,
+        expr: { kind: "atom", path: ["x"], op: { kind: "eq", value: 1 } },
+      }),
+    );
+    expect(() => evaluateEventMatch(stale, {})).toThrow(/version/i);
+  });
+
+  it("throws on an unrecognized expr kind", () => {
+    const bad = JSON.parse(JSON.stringify({ version: 1, expr: { kind: "not-a-kind" } }));
+    expect(() => evaluateEventMatch(bad, {})).toThrow(/kind/i);
+  });
+
+  it("throws on an unrecognized op kind", () => {
+    const bad = JSON.parse(
+      JSON.stringify({
+        version: 1,
+        expr: { kind: "atom", path: ["x"], op: { kind: "not-an-op" } },
+      }),
+    );
+    expect(() => evaluateEventMatch(bad, {})).toThrow(/kind/i);
+  });
+
+  it("and with empty nodes is true, or with empty nodes is false", () => {
+    expect(evaluateEventMatch({ version: 1, expr: { kind: "and", nodes: [] } }, {})).toBe(true);
+    expect(evaluateEventMatch({ version: 1, expr: { kind: "or", nodes: [] } }, {})).toBe(false);
+  });
+
+  it("combines atoms with and/or", () => {
+    const match: EventMatch = {
+      version: 1,
+      expr: {
+        kind: "and",
+        nodes: [
+          { kind: "atom", path: ["status"], op: { kind: "eq", value: "confirmed" } },
+          { kind: "atom", path: ["tier"], op: { kind: "in", values: ["gold", "platinum"] } },
+        ],
+      },
+    };
+    expect(evaluateEventMatch(match, { status: "confirmed", tier: "gold" })).toBe(true);
+    expect(evaluateEventMatch(match, { status: "confirmed", tier: "silver" })).toBe(false);
+  });
+
+  it("ne matches when the resolved value differs", () => {
+    const match: EventMatch = {
+      version: 1,
+      expr: { kind: "atom", path: ["status"], op: { kind: "ne", value: "cancelled" } },
+    };
+    expect(evaluateEventMatch(match, { status: "confirmed" })).toBe(true);
+    expect(evaluateEventMatch(match, { status: "cancelled" })).toBe(false);
+  });
+
+  it("compares numbers with gte", () => {
+    const match: EventMatch = {
+      version: 1,
+      expr: { kind: "atom", path: ["amount"], op: { kind: "gte", value: 100 } },
+    };
+    expect(evaluateEventMatch(match, { amount: 150 })).toBe(true);
+    expect(evaluateEventMatch(match, { amount: 50 })).toBe(false);
+  });
+
+  it("does not match a comparison op when the payload value's type differs from the operand", () => {
+    const match: EventMatch = {
+      version: 1,
+      expr: { kind: "atom", path: ["amount"], op: { kind: "gt", value: 100 } },
+    };
+    expect(evaluateEventMatch(match, { amount: "150" })).toBe(false);
+  });
+
+  it("resolves nested paths and treats a path running into a non-object as unmatched", () => {
+    const match: EventMatch = {
+      version: 1,
+      expr: {
+        kind: "atom",
+        path: ["user", "email"],
+        op: { kind: "eq", value: "a@b.com" },
+      },
+    };
+    expect(evaluateEventMatch(match, { user: { email: "a@b.com" } })).toBe(true);
+    expect(evaluateEventMatch(match, { user: "not-an-object" })).toBe(false);
+    expect(evaluateEventMatch(match, {})).toBe(false);
+  });
 });
 
 describe("buildRetryStep", () => {

package/src/engine/define-workflow.ts

@@ -5,7 +5,7 @@
 
 import { createHash } from "node:crypto";
 import type { WriteEvent } from "./types/handlers";
-import type { PipelineDef } from "./types/step";
+import type { AwaitedEventType, PipelineDef } from "./types/step";
 
 /**
  * Trigger configuration for a workflow. Determines what starts a run.
@@ -28,12 +28,27 @@ export type WorkflowTrigger =
 /**
  * Workflow definition — the result of defineWorkflow().
  */
-export type WorkflowDefinition<TPayload = unknown, TData = unknown> = {
+export type WorkflowDefinition<
+  TPayload = unknown,
+  TData = unknown,
+  TAwaits extends Record<string, string> = Record<string, string>,
+> = {
   readonly __kind: "workflow";
   readonly name: string;
   readonly trigger: WorkflowTrigger;
+  /**
+   * Declared expected events (D4, workflow-resume-loop.md) — the sole route
+   * a waitForEvent step can reach an event type. Read at registration time
+   * to build the static apply-map (Phase 3b); values are plain event-type
+   * strings, not the branded AwaitedEventType the pipeline closure sees.
+   */
+  readonly awaits?: TAwaits;
   /** The pipeline definition containing the step list closure. */
-  readonly pipelineDef: PipelineDef<TPayload, TData>;
+  readonly pipelineDef: PipelineDef<
+    TPayload,
+    TData,
+    { readonly [K in keyof TAwaits]: AwaitedEventType }
+  >;
   /** Idempotency key for deduplication — prevents duplicate runs. */
   readonly idempotencyKey?: string | ((event: WriteEvent<TPayload>) => string);
 };
@@ -41,10 +56,15 @@ export type WorkflowDefinition<TPayload = unknown, TData = unknown> = {
 /**
  * Input shape for defineWorkflow() — the user-facing API.
  */
-export type WorkflowInput<TPayload = unknown, TData = unknown> = {
+export type WorkflowInput<
+  TPayload = unknown,
+  TData = unknown,
+  TAwaits extends Record<string, string> = Record<string, string>,
+> = {
   readonly name: string;
   readonly trigger: WorkflowTrigger;
-  readonly steps: PipelineDef<TPayload, TData>;
+  readonly awaits?: TAwaits;
+  readonly steps: PipelineDef<TPayload, TData, { readonly [K in keyof TAwaits]: AwaitedEventType }>;
   readonly idempotencyKey?: string | ((event: WriteEvent<TPayload>) => string);
   readonly onError?: PipelineDef<unknown>;
 };
@@ -69,14 +89,22 @@ export type WorkflowInput<TPayload = unknown, TData = unknown> = {
  * });
  * ```
  */
-export function defineWorkflow<TPayload = unknown, TData = unknown>(
-  input: WorkflowInput<TPayload, TData>,
-): WorkflowDefinition<TPayload, TData> {
+export function defineWorkflow<
+  TPayload = unknown,
+  TData = unknown,
+  const TAwaits extends Record<string, string> = Record<string, string>,
+>(input: WorkflowInput<TPayload, TData, TAwaits>): WorkflowDefinition<TPayload, TData, TAwaits> {
+  // pipelineDef.awaits carries the same raw strings as the declaration
+  // below — buildPipelineSteps (pipeline.ts) is where they're branded into
+  // AwaitedEventType for the step closure, not here (see PipelineDef.awaits
+  // doc comment in types/step.ts for why the brand can't happen at this
+  // layer without breaking inference for an inline `stepsPipeline(...)`).
   return {
     __kind: "workflow",
     name: input.name,
     trigger: input.trigger,
-    pipelineDef: input.steps,
+    awaits: input.awaits,
+    pipelineDef: { ...input.steps, awaits: input.awaits },
     idempotencyKey: input.idempotencyKey,
   };
 }
@@ -98,12 +126,21 @@ export function defineWorkflow<TPayload = unknown, TData = unknown>(
  *     environments. Run-the-fingerprint-in-the-same-environment is the
  *     contract; cross-env replay is out of scope.
  */
-export function computeDefinitionFingerprint(
-  workflow: Pick<WorkflowDefinition, "name" | "trigger" | "pipelineDef">,
+export function computeDefinitionFingerprint<
+  TPayload = unknown,
+  TData = unknown,
+  TAwaits extends Record<string, string> = Record<string, string>,
+>(
+  workflow: Pick<WorkflowDefinition<TPayload, TData, TAwaits>, "name" | "trigger" | "pipelineDef">,
 ): string {
+  // `awaits` is part of the routing contract (D4, workflow-resume-loop.md):
+  // changing which events a run waits on changes the run's behavior just
+  // like changing the step source does, so a changed declaration must flip
+  // the fingerprint and trip the Q7 stale-definition check on resume.
   const material = JSON.stringify({
     name: workflow.name,
     trigger: workflow.trigger,
+    awaits: workflow.pipelineDef.awaits,
     source: workflow.pipelineDef.build.toString(),
   });
   return createHash("sha256").update(material).digest("hex");

package/src/engine/feature-ui-extensions.ts

@@ -360,12 +360,15 @@ export function buildUiExtensionsMethods<TName extends string>(
         // Sugar for the common "one nav entry pointing at this screen"
         // case — synthesizes id/screen from the screen's own id. Beyond
         // label/icon/parent/order, declare a standalone r.nav() instead.
+        // Optional fields stay absent rather than explicitly undefined —
+        // buildAppSchema's JSON-safety check flags undefined values. Same
+        // pattern as r.contentCollection() below.
         registerNav({
           id: definition.id,
           label: definition.nav.label,
-          icon: definition.nav.icon,
-          parent: definition.nav.parent,
-          order: definition.nav.order,
+          ...(definition.nav.icon !== undefined && { icon: definition.nav.icon }),
+          ...(definition.nav.parent !== undefined && { parent: definition.nav.parent }),
+          ...(definition.nav.order !== undefined && { order: definition.nav.order }),
           screen: `${name}:screen:${definition.id}`,
         });
       }

package/src/engine/index.ts

@@ -247,6 +247,7 @@ export {
 } from "./screen-helpers";
 export type { TransitionGraph } from "./state-machine";
 export { defineTransitions, guardTransition } from "./state-machine";
+export { evaluateEventMatch } from "./steps/_event-match";
 export {
   SUSPEND_SENTINEL,
   WORKFLOW_AGGREGATE_TYPE,
@@ -469,6 +470,7 @@ export type {
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, HookPhases } from "./types";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers";
 export type {
+  AwaitedEventType,
   PipelineBuildCtx,
   PipelineCtx,
   PipelineDef,

package/src/engine/pipeline.ts

@@ -31,7 +31,13 @@ import { buildWaitStep } from "./steps/wait";
 import { buildWaitForEventStep } from "./steps/wait-for-event";
 import { buildWebhookSendStep } from "./steps/webhook-send";
 import type { WriteEvent } from "./types/handlers";
-import type { PipelineBuildCtx, PipelineDef, StepBuilder, StepInstance } from "./types/step";
+import type {
+  AwaitedEventType,
+  PipelineBuildCtx,
+  PipelineDef,
+  StepBuilder,
+  StepInstance,
+} from "./types/step";
 
 const stepBuilder: StepBuilder = {
   step: {
@@ -64,9 +70,13 @@ const stepBuilder: StepBuilder = {
   },
 };
 
-export function stepsPipeline<TPayload = unknown, TData = unknown>(
-  closure: (ctx: PipelineBuildCtx<TPayload>) => readonly StepInstance[],
-): PipelineDef<TPayload, TData> {
+export function stepsPipeline<
+  TPayload = unknown,
+  TData = unknown,
+  TAwaits extends Record<string, AwaitedEventType> = Record<string, AwaitedEventType>,
+>(
+  closure: (ctx: PipelineBuildCtx<TPayload, TAwaits>) => readonly StepInstance[],
+): PipelineDef<TPayload, TData, TAwaits> {
   return {
     __kind: "pipeline",
     build: closure,
@@ -76,9 +86,26 @@ export function stepsPipeline<TPayload = unknown, TData = unknown>(
 // Internal: invoked by run-pipeline.ts to materialise the step list.
 // Not exported from the engine barrel — pipeline-internal plumbing.
 // @wrapper-known semantic-alias
-export function buildPipelineSteps<TPayload>(
-  pipelineDef: PipelineDef<TPayload>,
+//
+// `awaits` comes off pipelineDef itself (set by defineWorkflow), not a
+// function argument — every existing buildPipelineSteps caller (runner.ts,
+// resume-run.write.ts, run-pipeline.ts, validate-projection-allowlist.ts)
+// keeps working unchanged while workflow pipelines still get their real
+// awaits map wired into the closure. The cast below is the one place a
+// workflow's raw declared event-type strings become AwaitedEventType — safe
+// because pipelineDef.awaits only ever holds what defineWorkflow's `awaits`
+// carried in (D4, workflow-resume-loop.md), never an unchecked external
+// value.
+export function buildPipelineSteps<
+  TPayload,
+  TAwaits extends Record<string, AwaitedEventType> = Record<string, AwaitedEventType>,
+>(
+  pipelineDef: PipelineDef<TPayload, unknown, TAwaits>,
   event: WriteEvent<TPayload>,
 ): readonly StepInstance[] {
-  return pipelineDef.build({ event, r: stepBuilder });
+  return pipelineDef.build({
+    event,
+    r: stepBuilder,
+    awaits: (pipelineDef.awaits ?? {}) as TAwaits,
+  });
 }

package/src/engine/steps/_event-match.ts

@@ -0,0 +1,98 @@
+// Evaluator for the persisted r.step.waitForEvent `match` AST (EventMatch).
+// Runtime-only: kept in the framework package (not packages/types) so it
+// stays out of the type graph, same steps/-vs-packages/types split as
+// _duration-utils.ts.
+
+import type { EventMatch, EventMatchExpr, EventMatchOp } from "../types/step";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function resolvePath(payload: unknown, path: readonly string[]): unknown {
+  let current: unknown = payload;
+  for (const segment of path) {
+    if (!isRecord(current)) return undefined;
+    current = current[segment];
+  }
+  return current;
+}
+
+function compareOrdered(
+  actual: number | string,
+  expected: number | string,
+  kind: "gt" | "gte" | "lt" | "lte",
+): boolean {
+  if (typeof actual === "number" && typeof expected === "number") {
+    switch (kind) {
+      case "gt":
+        return actual > expected;
+      case "gte":
+        return actual >= expected;
+      case "lt":
+        return actual < expected;
+      case "lte":
+        return actual <= expected;
+    }
+  }
+  if (typeof actual === "string" && typeof expected === "string") {
+    switch (kind) {
+      case "gt":
+        return actual > expected;
+      case "gte":
+        return actual >= expected;
+      case "lt":
+        return actual < expected;
+      case "lte":
+        return actual <= expected;
+    }
+  }
+  return false;
+}
+
+function evaluateOp(op: EventMatchOp, actual: unknown): boolean {
+  switch (op.kind) {
+    case "eq":
+      return actual === op.value;
+    case "ne":
+      return actual !== op.value;
+    case "in":
+      return op.values.some((value) => value === actual);
+    case "gt":
+    case "gte":
+    case "lt":
+    case "lte":
+      // A payload value of a different primitive kind than the operand
+      // doesn't match — bad input, not a malformed AST.
+      if (typeof actual !== "number" && typeof actual !== "string") return false;
+      return compareOrdered(actual, op.value, op.kind);
+    default: {
+      // op.kind comes from a persisted event, not from this call's static
+      // type — an unrecognized kind means a format we don't understand.
+      const unrecognized: { readonly kind: string } = op;
+      throw new Error(`Unknown EventMatchOp kind "${unrecognized.kind}"`);
+    }
+  }
+}
+
+function evaluateExpr(expr: EventMatchExpr, payload: unknown): boolean {
+  switch (expr.kind) {
+    case "and":
+      return expr.nodes.every((node) => evaluateExpr(node, payload));
+    case "or":
+      return expr.nodes.some((node) => evaluateExpr(node, payload));
+    case "atom":
+      return evaluateOp(expr.op, resolvePath(payload, expr.path));
+    default: {
+      const unrecognized: { readonly kind: string } = expr;
+      throw new Error(`Unknown EventMatchExpr kind "${unrecognized.kind}"`);
+    }
+  }
+}
+
+export function evaluateEventMatch(match: EventMatch, payload: unknown): boolean {
+  if (match.version !== 1) {
+    throw new Error(`Unsupported EventMatch version ${JSON.stringify(match.version)} — expected 1`);
+  }
+  return evaluateExpr(match.expr, payload);
+}

package/src/engine/steps/wait-for-event.ts

@@ -8,13 +8,29 @@
 // it writes workflow.step.resumed with the matched event's data.
 //
 // The `match` resolver is optional — when omitted, any event of the given
-// type resumes the workflow. When provided, it receives the event payload
-// and must return true for the event to trigger resume.
+// type resumes the workflow. When provided, it resolves to a serializable
+// EventMatch AST (not a closure) that is persisted into the waiting event's
+// payload; the Resume-Loop evaluates it via evaluateEventMatch against the
+// candidate event's payload.
+//
+// resultKey is `args.event` itself (the branded event-type string) rather
+// than a new `name` argument — a workflow only ever has one `awaits` entry
+// per event type, so `ctx.steps[awaits.someKey]` is already a unique,
+// intention-revealing handle. resume-run.write.ts (framework#2513 Phase 3b)
+// is the only producer of this key's value: the step itself always
+// suspends (never returns a real result), so a subsequent step only ever
+// sees the matched event's payload after a resume seeds it in.
 
 import { defineStep } from "../define-step";
-import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import type {
+  AwaitedEventType,
+  EventMatch,
+  PipelineCtx,
+  StepInstance,
+  StepResolver,
+} from "../types/step";
 import { addDuration } from "./_duration-utils";
-import { resolveRequired } from "./_resolver-utils";
+import { resolveOptional, resolveRequired } from "./_resolver-utils";
 import {
   SUSPEND_SENTINEL,
   WORKFLOW_AGGREGATE_TYPE,
@@ -22,8 +38,8 @@ import {
 } from "./_step-dispatch-constants";
 
 type WaitForEventArgs = {
-  readonly event: string;
-  readonly match?: StepResolver<(payload: unknown) => boolean>;
+  readonly event: AwaitedEventType;
+  readonly match?: StepResolver<EventMatch>;
   readonly timeout: StepResolver<string>;
 };
 
@@ -31,6 +47,7 @@ defineStep<WaitForEventArgs, undefined | typeof SUSPEND_SENTINEL>({
   kind: "workflow.waitForEvent",
   tier: 3,
   defaultFailureStrategy: "throw",
+  resultKey: (args) => args.event,
   run: async (args, ctx: PipelineCtx): Promise<undefined | typeof SUSPEND_SENTINEL> => {
     if (!ctx.workflow) {
       throw new Error(
@@ -40,6 +57,7 @@ defineStep<WaitForEventArgs, undefined | typeof SUSPEND_SENTINEL>({
     }
 
     const timeout = resolveRequired(args.timeout, ctx);
+    const resolvedMatch = resolveOptional(args.match, ctx);
 
     const now = Temporal.Now.instant().toString();
     const timeoutAt =
@@ -51,6 +69,7 @@ defineStep<WaitForEventArgs, undefined | typeof SUSPEND_SENTINEL>({
       type: WORKFLOW_WAITING_FOR_EVENT_TYPE,
       payload: {
         eventType: args.event,
+        ...(resolvedMatch && { match: resolvedMatch }),
         timeoutAt,
         stepIndex: ctx.workflow.stepIndex,
         workflowName: ctx.workflow.workflowName,

package/src/files/__tests__/file-handle.test.ts

@@ -90,6 +90,32 @@ describe("createFileContext", () => {
     const h2 = files.ref("tenant/foo.pdf");
     expect(Array.from(await h2.read())).toEqual([7]);
   });
+
+  test("list delegates to the provider and returns its result", async () => {
+    const provider = createInMemoryFileProvider();
+    await provider.write("tenant/photo.jpg", new Uint8Array([1]));
+    await provider.write("tenant/photo.medium.jpg", new Uint8Array([2]));
+    await provider.write("other/photo.jpg", new Uint8Array([3]));
+    const files = createFileContext(() => Promise.resolve(provider));
+
+    const keys = await files.list("tenant/");
+    expect([...keys].sort()).toEqual(["tenant/photo.jpg", "tenant/photo.medium.jpg"].sort());
+  });
+
+  test("the provider is resolved once and memoized across ref() and list()", async () => {
+    const provider = createInMemoryFileProvider();
+    let resolveCount = 0;
+    const files = createFileContext(() => {
+      resolveCount++;
+      return Promise.resolve(provider);
+    });
+
+    await files.ref("tenant/a.jpg").write(new Uint8Array([1]));
+    await files.list("tenant/");
+    await files.ref("tenant/b.jpg").write(new Uint8Array([2]));
+
+    expect(resolveCount).toBe(1);
+  });
 });
 
 describe("InMemoryFileProvider", () => {

package/src/files/file-handle.ts

@@ -45,6 +45,7 @@ export function createFileContext(resolve: () => Promise<FileStorageProvider>):
   };
   return {
     ref: (key) => createFileHandle(key, getProvider),
+    list: async (prefix) => (await getProvider()).list(prefix),
   };
 }