@c9up/ream 0.2.1 → 0.2.2

package/src/events/services/main.ts

@@ -9,6 +9,7 @@
  * Populated by `EventsProvider.boot()`.
  */
 
+import { createServiceProxy } from '../../services/createServiceProxy.js'
 import type { Emitter } from '../Emitter.js'
 
 let instance: Emitter | undefined
@@ -23,17 +24,10 @@ export function getEmitter(): Emitter | undefined {
   return instance
 }
 
-const emitter: Emitter = new Proxy({} as Emitter, {
-  get(_target, prop) {
-    if (!instance) {
-      throw new Error(
-        '[ream:events] Emitter singleton accessed before EventsProvider.boot() ran. ' +
-          'Check that `@c9up/ream/events/provider` is listed in your reamrc.ts providers.',
-      )
-    }
-    const value = Reflect.get(instance, prop, instance)
-    return typeof value === 'function' ? value.bind(instance) : value
-  },
-})
+const emitter: Emitter = createServiceProxy<Emitter>(
+  () => instance,
+  '[ream:events] Emitter singleton accessed before EventsProvider.boot() ran. ' +
+    'Check that `@c9up/ream/events/provider` is listed in your reamrc.ts providers.',
+)
 
 export default emitter

package/src/http/Exception.ts

@@ -154,15 +154,16 @@ export class E_VALIDATION_ERROR extends Exception {
   static override status = 422
   static override code = 'E_VALIDATION_ERROR'
 
-  errors: unknown[]
-
-  constructor(errors: unknown[]) {
-    super('Validation failed', { status: 422, code: 'E_VALIDATION_ERROR' })
-    this.errors = errors
-  }
-
-  override handle(_error: this, ctx: HttpContext): void {
-    ctx.response.status(422).json({ errors: this.errors })
+  /**
+   * Per-field failures. Named `messages` because that is what VineJS, rune and
+   * AdonisJS's own validation renderers read — a handler copied from an Adonis
+   * app reaches for `error.messages`.
+   */
+  messages: unknown[]
+
+  constructor(messages: unknown[]) {
+    super('Validation failure', { status: 422, code: 'E_VALIDATION_ERROR' })
+    this.messages = messages
   }
 }
 
@@ -233,8 +234,34 @@ export class E_HTTP_REQUEST_ABORTED extends Exception {
  * 2. Else → this.handle() → content negotiation (JSON or HTML)
  * 3. Then → this.report() → logging/monitoring
  */
+/**
+ * A thrown value, normalised into the shape every renderer reads.
+ *
+ * AdonisJS hands this to `renderError*` / `renderValidationError*` and to the
+ * status-page renderers, so an app that overrides one of them receives the same
+ * object it would there — a plain record, never an `Error` subclass, because
+ * what is thrown is not always one.
+ */
+export type HttpError = {
+  message: string
+  status: number
+  code: string
+  stack?: string
+  cause?: unknown
+  /** Per-field failures, on a validation error (VineJS / rune shape). */
+  messages?: unknown
+  /** Extra detail an exception chose to carry. */
+  errors?: unknown
+  /** Set when the thrown value handles its own response. */
+  handle?: (error: unknown, ctx: HttpContext) => Promise<void> | void
+  /** Set when the thrown value reports itself. */
+  report?: (error: unknown, ctx: HttpContext) => Promise<void> | void
+  /** A hint appended to the message, when the exception carries one. */
+  help?: string
+}
+
 /** Renders an HTML error page for a status (AdonisJS `StatusPageRenderer`). */
-export type StatusPageRenderer = (error: unknown, ctx: HttpContext) => Promise<string> | string
+export type StatusPageRenderer = (error: HttpError, ctx: HttpContext) => Promise<string> | string
 
 /** A constructor usable in `instanceof` for {@link ExceptionHandler.ignoreExceptions}. */
 export type ExceptionClass = new (...args: never[]) => Error
@@ -268,18 +295,17 @@ export class ExceptionHandler extends Macroable {
   }
 
   /** Log level for an error by status: 5xx→error, 4xx→warn, else info (AdonisJS). */
-  protected getErrorLogLevel(status: number): LogLevel {
-    if (status >= 500) return 'error'
-    if (status >= 400) return 'warn'
+  protected getErrorLogLevel(error: HttpError): LogLevel {
+    if (error.status >= 500) return 'error'
+    if (error.status >= 400) return 'warn'
     return 'info'
   }
 
   /** Whether an error should be reported — honours every ignore list (AdonisJS `shouldReport`). */
-  protected shouldReport(error: unknown): boolean {
+  protected shouldReport(error: HttpError): boolean {
     if (!this.reportErrors) return false
-    const { status, code } = extractErrorMeta(error)
-    if (this.ignoreStatuses.includes(status)) return false
-    if (this.ignoreCodes.includes(code)) return false
+    if (this.ignoreStatuses.includes(error.status)) return false
+    if (this.ignoreCodes.includes(error.code)) return false
     if (this.ignoreExceptions.some((exception) => error instanceof exception)) return false
     return true
   }
@@ -297,95 +323,185 @@ export class ExceptionHandler extends Macroable {
   }
 
   /** Convert an exception to an HTTP response. */
-  async handle(error: unknown, ctx: HttpContext): Promise<void> {
-    // Self-handled errors take over entirely (duck-typed, per AdonisJS — any
-    // thrown value exposing a `handle()` method, not just `Exception` instances).
-    if (isSelfHandling(error)) {
-      await error.handle(error, ctx)
-      return
-    }
-
-    // Negotiation. DEVIATION (named): ream lists `json` FIRST, so a request
-    // with no/`*/*` Accept defaults to JSON (API-first). AdonisJS lists `html`
-    // first (full-stack default). Explicit `text/html` / `vnd.api+json` are
-    // honoured identically.
-    switch (ctx.request.accepts(['json', 'html', 'application/vnd.api+json'])) {
-      case 'application/vnd.api+json':
-        this.#sendJsonApiError(error, ctx)
-        return
-      case 'html':
-        await this.#sendHtmlError(error, ctx)
-        return
-      default:
-        this.#sendJsonError(error, ctx)
-    }
+  /**
+   * Normalise any thrown value into an {@link HttpError}.
+   *
+   * Everything downstream — the renderers, the status pages, the report path —
+   * reads this shape, so a handler override never has to re-sniff whether it
+   * was handed an `Exception`, a plain object, or a string.
+   */
+  protected toHttpError(error: unknown): HttpError {
+    // AdonisJS returns the thrown object ITSELF, filled in — not a copy. That
+    // identity is load-bearing: `ignoreExceptions` matches with `instanceof`,
+    // and `handle`/`report` have to stay bound to their own instance. A copy
+    // would quietly break both.
+    const source: object =
+      typeof error === 'object' && error !== null ? error : new Error(String(error))
+    const { status, code } = extractErrorMeta(error)
+    const message =
+      'message' in source && typeof source.message === 'string' && source.message.length > 0
+        ? source.message
+        : 'Internal server error'
+    return Object.assign(source, { status, code, message })
   }
 
-  /** Pick the user-facing message — full detail only in debug mode. */
-  #errorMessage(error: unknown, ctx: HttpContext): string {
-    if (this.isDebuggingEnabled(ctx) && error instanceof Error) return error.message
-    if (error instanceof Exception) return error.message
+  /**
+   * The message a client is allowed to see.
+   *
+   * DEVIATION (named): outside debug mode ream only echoes the message of a
+   * deliberate `Exception`; anything else collapses to a generic line. AdonisJS
+   * echoes `error.message` whatever was thrown, which leaks the text of driver
+   * and library errors to the client.
+   */
+  protected publicMessage(error: HttpError, ctx: HttpContext): string {
+    if (this.isDebuggingEnabled(ctx)) return error.message
+    if (error.code !== 'E_UNKNOWN') return error.message
     return 'An internal error occurred'
   }
 
-  #sendJsonError(error: unknown, ctx: HttpContext): void {
-    const { status, code } = extractErrorMeta(error)
-    const payload: Record<string, unknown> = { code, message: this.#errorMessage(error, ctx) }
-    if (error instanceof Exception && error.help) payload.help = error.help
-    if (this.isDebuggingEnabled(ctx) && error instanceof Error && error.stack) {
-      payload.stack = error.stack
+  /** Render an error as JSON. */
+  async renderErrorAsJSON(error: HttpError, ctx: HttpContext): Promise<void> {
+    const payload: Record<string, unknown> = {
+      code: error.code,
+      message: this.publicMessage(error, ctx),
     }
-    ctx.response.status(status).json({ error: payload })
+    if (error.help) payload.help = error.help
+    if (this.isDebuggingEnabled(ctx) && error.stack) payload.stack = error.stack
+    ctx.response.status(error.status).json({ error: payload })
   }
 
-  #sendJsonApiError(error: unknown, ctx: HttpContext): void {
-    const { status, code } = extractErrorMeta(error)
+  /** Render an error as a JSON:API document. */
+  async renderErrorAsJSONAPI(error: HttpError, ctx: HttpContext): Promise<void> {
     ctx.response
-      .status(status)
+      .status(error.status)
       .type('application/vnd.api+json')
-      .json({ errors: [{ title: this.#errorMessage(error, ctx), code, status: String(status) }] })
+      .json({
+        errors: [
+          {
+            title: this.publicMessage(error, ctx),
+            code: error.code,
+            status: String(error.status),
+          },
+        ],
+      })
   }
 
-  async #sendHtmlError(error: unknown, ctx: HttpContext): Promise<void> {
-    const { status } = extractErrorMeta(error)
-    // A registered status page wins (production browser error pages).
+  /** Render an error as HTML, preferring a registered status page. */
+  async renderErrorAsHTML(error: HttpError, ctx: HttpContext): Promise<void> {
     if (this.renderStatusPages) {
-      const renderer = this.#expandStatusPages()[status]
+      const renderer = this.#expandStatusPages()[error.status]
       if (renderer) {
         const html = await renderer(error, ctx)
-        ctx.response.status(status).type('text/html; charset=utf-8').send(html)
+        ctx.response.status(error.status).type('text/html; charset=utf-8').send(html)
         return
       }
     }
-    const message = this.#errorMessage(error, ctx)
+    const message = this.publicMessage(error, ctx)
     ctx.response
-      .status(status)
+      .status(error.status)
       .type('text/html; charset=utf-8')
       .send(
-        `<!DOCTYPE html><html><head><title>Error ${status}</title></head>` +
-          `<body><h1>${status}</h1><p>${escapeHtml(message)}</p></body></html>`,
+        `<!DOCTYPE html><html><head><title>Error ${error.status}</title></head>` +
+          `<body><h1>${error.status}</h1><p>${escapeHtml(message)}</p></body></html>`,
       )
   }
 
+  /** Render per-field validation failures as JSON. */
+  async renderValidationErrorAsJSON(error: HttpError, ctx: HttpContext): Promise<void> {
+    ctx.response.status(error.status).json({ errors: error.messages })
+  }
+
+  /** Render per-field validation failures as a JSON:API document. */
+  async renderValidationErrorAsJSONAPI(error: HttpError, ctx: HttpContext): Promise<void> {
+    const messages = Array.isArray(error.messages) ? error.messages : []
+    ctx.response
+      .status(error.status)
+      .type('application/vnd.api+json')
+      .json({ errors: messages.map(toJsonApiValidationError) })
+  }
+
+  /** Render per-field validation failures as HTML. */
+  async renderValidationErrorAsHTML(error: HttpError, ctx: HttpContext): Promise<void> {
+    const messages = Array.isArray(error.messages) ? error.messages : []
+    ctx.response
+      .status(error.status)
+      .type('text/html; charset=utf-8')
+      .send(
+        messages
+          .map((message) => {
+            const { field, text } = readValidationMessage(message)
+            return `${escapeHtml(field)} - ${escapeHtml(text)}`
+          })
+          .join('<br />'),
+      )
+  }
+
+  /**
+   * Pick a renderer by content negotiation.
+   *
+   * DEVIATION (named): ream lists `json` FIRST, so a request with no or `*` /`*`
+   * Accept defaults to JSON (API-first). AdonisJS lists `html` first
+   * (full-stack default). Explicit `text/html` / `vnd.api+json` are honoured
+   * identically.
+   */
+  async renderError(error: HttpError, ctx: HttpContext): Promise<void> {
+    switch (ctx.request.accepts(['json', 'html', 'application/vnd.api+json'])) {
+      case 'application/vnd.api+json':
+        return this.renderErrorAsJSONAPI(error, ctx)
+      case 'html':
+        return this.renderErrorAsHTML(error, ctx)
+      default:
+        return this.renderErrorAsJSON(error, ctx)
+    }
+  }
+
+  /** Pick a validation renderer by content negotiation. */
+  async renderValidationError(error: HttpError, ctx: HttpContext): Promise<void> {
+    switch (ctx.request.accepts(['json', 'html', 'application/vnd.api+json'])) {
+      case 'application/vnd.api+json':
+        return this.renderValidationErrorAsJSONAPI(error, ctx)
+      case 'html':
+        return this.renderValidationErrorAsHTML(error, ctx)
+      default:
+        return this.renderValidationErrorAsJSON(error, ctx)
+    }
+  }
+
+  /** Convert an exception to an HTTP response. */
+  async handle(error: unknown, ctx: HttpContext): Promise<void> {
+    const httpError = this.toHttpError(error)
+
+    // Self-handled errors take over entirely (duck-typed, per AdonisJS — any
+    // thrown value exposing a `handle()` method, not just `Exception` instances).
+    if (typeof httpError.handle === 'function') {
+      await httpError.handle(httpError, ctx)
+      return
+    }
+
+    // Validation failures have per-field detail and their own renderers. Keyed
+    // on the code plus the presence of `messages`, exactly as AdonisJS does, so
+    // rune's and VineJS's errors both land here.
+    if (httpError.code === 'E_VALIDATION_ERROR' && httpError.messages !== undefined) {
+      await this.renderValidationError(httpError, ctx)
+      return
+    }
+
+    await this.renderError(httpError, ctx)
+  }
+
   /** Log/report an exception. Override for custom monitoring. */
   async report(error: unknown, ctx: HttpContext): Promise<void> {
-    if (!this.shouldReport(error)) return
+    const httpError = this.toHttpError(error)
+    if (!this.shouldReport(httpError)) return
 
     // Self-reported exceptions handle their own reporting.
-    if (isSelfReporting(error)) {
-      await error.report(error, ctx)
+    if (typeof httpError.report === 'function') {
+      await httpError.report(httpError, ctx)
       return
     }
 
-    // Default: log at the status-appropriate level.
-    const { status } = extractErrorMeta(error)
-    const level = this.getErrorLogLevel(status)
-    const context = this.context(ctx)
-    if (error instanceof Error) {
-      console[level](`[${new Date().toISOString()}] ${error.message}`, context, error.stack)
-    } else {
-      console[level](`[${new Date().toISOString()}] Unknown error:`, error, context)
-    }
+    const level = this.getErrorLogLevel(httpError)
+    ctx.logger[level](httpError.message, this.context(ctx))
   }
 
   /** Provide additional context for error reports. Override for custom data. */
@@ -399,6 +515,40 @@ export class ExceptionHandler extends Macroable {
   }
 }
 
+/**
+ * The fields a validation message carries (VineJS / rune `RuneErrorNode`).
+ *
+ * Read defensively: the messages come from whichever validator the app wired,
+ * and a renderer must not throw while rendering someone else's error.
+ */
+function readValidationMessage(message: unknown): {
+  field: string
+  text: string
+  rule: string
+  meta: unknown
+} {
+  if (message === null || typeof message !== 'object') {
+    return { field: '', text: String(message), rule: '', meta: undefined }
+  }
+  const field = 'field' in message && typeof message.field === 'string' ? message.field : ''
+  const text = 'message' in message && typeof message.message === 'string' ? message.message : ''
+  const rule = 'rule' in message && typeof message.rule === 'string' ? message.rule : ''
+  const meta = 'meta' in message ? message.meta : undefined
+  return { field, text, rule, meta }
+}
+
+/** One validation message, as a JSON:API error object (AdonisJS shape). */
+function toJsonApiValidationError(message: unknown): Record<string, unknown> {
+  const { field, text, rule, meta } = readValidationMessage(message)
+  const error: Record<string, unknown> = {
+    title: text,
+    code: rule,
+    source: { pointer: field },
+  }
+  if (meta !== undefined) error.meta = meta
+  return error
+}
+
 /** Extract status + code from an Exception, ReamError, or duck-typed error. */
 function extractErrorMeta(error: unknown): { status: number; code: string } {
   let status = 500
@@ -413,30 +563,6 @@ function extractErrorMeta(error: unknown): { status: number; code: string } {
   return { status, code }
 }
 
-/** True when a thrown value self-handles via a `handle()` method (AdonisJS duck-type). */
-function isSelfHandling(
-  error: unknown,
-): error is { handle: (error: unknown, ctx: HttpContext) => Promise<void> | void } {
-  return (
-    error !== null &&
-    typeof error === 'object' &&
-    'handle' in error &&
-    typeof error.handle === 'function'
-  )
-}
-
-/** True when a thrown value self-reports via a `report()` method. */
-function isSelfReporting(
-  error: unknown,
-): error is { report: (error: unknown, ctx: HttpContext) => Promise<void> | void } {
-  return (
-    error !== null &&
-    typeof error === 'object' &&
-    'report' in error &&
-    typeof error.report === 'function'
-  )
-}
-
 /** Expand a status-page key into a per-code map: `'500..599'` → {500,…,599}, `'404'` → {404}. */
 function parseStatusRange(
   range: string,

package/src/index.ts

@@ -40,6 +40,7 @@ export {
   createError,
   E_FORBIDDEN,
   E_HTTP_EXCEPTION,
+  E_HTTP_REQUEST_ABORTED,
   E_ROUTE_NOT_FOUND,
   E_ROW_NOT_FOUND,
   E_UNAUTHORIZED,
@@ -48,6 +49,7 @@ export {
   type ExceptionClass,
   type ExceptionConstructor,
   ExceptionHandler,
+  type HttpError,
   InvalidArgumentsException,
   RuntimeException,
   type StatusPageRenderer,
@@ -58,6 +60,8 @@ export { RedirectBuilder } from './http/RedirectBuilder.js'
 export type { RawRequest } from './http/Request.js'
 export { Request } from './http/Request.js'
 export { Response } from './http/Response.js'
+export type { SseStreamOptions } from './http/SseStream.js'
+export { SseStream } from './http/SseStream.js'
 export { type GetterFn, Macroable, type MacroFn } from './utils/Macroable.js'
 
 // ─── Session ────────────────────────────────────────────────
@@ -77,6 +81,8 @@ export type {
   SessionRedisClientSource,
 } from './session/drivers/RedisDriver.js'
 export { RedisDriver as SessionRedisDriver } from './session/drivers/RedisDriver.js'
+export type { ValuePath } from './session/ReadOnlyValuesStore.js'
+export { ReadOnlyValuesStore } from './session/ReadOnlyValuesStore.js'
 export type {
   SessionConfig,
   SessionDriver,
@@ -139,7 +145,11 @@ export { StaticProvider } from './storage/StaticProvider.js'
 
 // Request-filter security (CSRF, XSS, rate-limit, CORS, headers, path/param)
 // lives in @c9up/blackhole. ream core keeps only the crypto primitives.
-export { CookieSigner } from './security/CookieSigner.js'
+export {
+  CookieSigner,
+  E_INSECURE_APP_KEY,
+  E_MISSING_APP_KEY,
+} from './security/CookieSigner.js'
 export {
   constantTimeEq,
   hasNativeCrypto,
@@ -179,6 +189,7 @@ export {
   matchers,
   OnRouteBuilder,
   RouteBuilder,
+  RouteResource,
   Router,
   UrlBuilder,
 } from './router/Router.js'
@@ -238,8 +249,10 @@ export { ConsoleKernel, defineConfig, Ignitor, prettyPrintError } from './Ignito
 
 // ─── Providers ──────────────────────────────────────────────
 
+export { errors } from './errors/aggregate.js'
 export type { AppContext, ProviderContract } from './Provider.js'
 export { Provider } from './Provider.js'
+export type { ContainerBinding, ContainerBindings } from './types/container.js'
 
 // ─── Codemods ───────────────────────────────────────────────
 
@@ -349,4 +362,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.1.7'
+export const VERSION = '0.2.2'

package/src/router/Router.ts

@@ -1236,7 +1236,7 @@ export class Router extends Macroable {
   makeSignedUrl(name: string, params?: Record<string, string>, options?: SignedUrlOptions): string {
     if (!this.#signedUrl) {
       throw new Error(
-        '[E_NO_APP_KEY] makeSignedUrl() requires an APP_KEY-backed signer. Set APP_KEY (>= 16 chars) so the encryption service is registered.',
+        '[E_MISSING_APP_KEY] makeSignedUrl() requires an APP_KEY-backed signer. Set APP_KEY (>= 16 chars) so the encryption service is registered.',
       )
     }
     const path = this.urlFor(name, params)

package/src/services/app.ts

@@ -8,6 +8,7 @@
  */
 
 import type { Application } from '../Application.js'
+import { createServiceProxy } from './createServiceProxy.js'
 
 let instance: Application | undefined
 
@@ -25,28 +26,10 @@ export function clearApp(app: Application): void {
   if (instance === app) instance = undefined
 }
 
-const app: Application = new Proxy({} as Application, {
-  get(_target, prop) {
-    // A module loader inspects what it imports before anyone uses it: it reads
-    // `then` to decide whether the namespace is thenable, and various symbols
-    // for interop and formatting. Throwing on those turns a plain
-    // `import { setX } from '.../services/x'` into a crash at import time, far
-    // from any real use. They are not members of what this stands in for, so
-    // answer undefined and let a genuine access be the one that reports.
-    if (typeof prop === 'symbol' || prop === 'then') {
-      return undefined
-    }
-    if (!instance) {
-      throw new Error(
-        'Application accessed before initialization. ' +
-          'Ensure this code runs during or after the boot phase.',
-      )
-    }
-    // Bind methods so private-field writes inside the class resolve
-    // against the real instance brand instead of the Proxy.
-    const value = Reflect.get(instance, prop, instance)
-    return typeof value === 'function' ? value.bind(instance) : value
-  },
-})
+const app: Application = createServiceProxy<Application>(
+  () => instance,
+  'Application accessed before initialization. ' +
+    'Ensure this code runs during or after the boot phase.',
+)
 
 export default app

package/src/services/console.ts

@@ -9,6 +9,7 @@
  */
 
 import type { Console } from '../console/Console.js'
+import { createServiceProxy } from './createServiceProxy.js'
 
 let instance: Console | undefined
 
@@ -26,26 +27,10 @@ export function clearConsole(consoleApp: Console): void {
   if (instance === consoleApp) instance = undefined
 }
 
-const consoleApp: Console = new Proxy({} as Console, {
-  get(_target, prop) {
-    // A module loader inspects what it imports before anyone uses it: it reads
-    // `then` to decide whether the namespace is thenable, and various symbols
-    // for interop and formatting. Throwing on those turns a plain
-    // `import { setX } from '.../services/x'` into a crash at import time, far
-    // from any real use. They are not members of what this stands in for, so
-    // answer undefined and let a genuine access be the one that reports.
-    if (typeof prop === 'symbol' || prop === 'then') {
-      return undefined
-    }
-    if (!instance) {
-      throw new Error(
-        'Console accessed before initialization. ' +
-          'Ensure this code runs during or after the boot phase.',
-      )
-    }
-    const value = Reflect.get(instance, prop, instance)
-    return typeof value === 'function' ? value.bind(instance) : value
-  },
-})
+const consoleApp: Console = createServiceProxy<Console>(
+  () => instance,
+  'Console accessed before initialization. ' +
+    'Ensure this code runs during or after the boot phase.',
+)
 
 export default consoleApp

package/src/services/createServiceProxy.ts

@@ -0,0 +1,47 @@
+/**
+ * The one implementation behind every `@c9up/ream/services/*` accessor.
+ *
+ * Each accessor stands in for a singleton that only exists once the Ignitor has
+ * built it, so the module-level export is a proxy that forwards to whatever the
+ * boot phase installed. Written out per service, the proxy was copied five
+ * times and the `symbol`/`then` guard below reached only three of them — a fix
+ * that has to be applied by hand five times is a fix that will be missed.
+ *
+ * @see services/app.ts for the accessor shape this backs.
+ */
+
+/**
+ * Build the proxy an accessor module default-exports.
+ *
+ * @param read     Returns the live singleton, or `undefined` before boot.
+ * @param notReady Message thrown when something reads the accessor too early.
+ */
+export function createServiceProxy<T extends object>(
+  read: () => T | undefined,
+  notReady: string,
+): T {
+  // The target is never read through — every trap forwards to `read()`.
+  const target: T = Object.create(null)
+  return new Proxy(target, {
+    get(_target, prop) {
+      // A module loader inspects what it imports before anyone uses it: it
+      // reads `then` to decide whether the namespace is thenable, and various
+      // symbols for interop and formatting. Throwing on those turns a plain
+      // `import { setX } from '.../services/x'` into a crash at import time,
+      // far from any real use. They are not members of what this stands in
+      // for, so answer undefined and let a genuine access be the one that
+      // reports.
+      if (typeof prop === 'symbol' || prop === 'then') {
+        return undefined
+      }
+      const instance = read()
+      if (!instance) {
+        throw new Error(notReady)
+      }
+      // Bind methods so private-field writes inside the class resolve against
+      // the real instance brand instead of the Proxy.
+      const value = Reflect.get(instance, prop, instance)
+      return typeof value === 'function' ? value.bind(instance) : value
+    },
+  })
+}