@ontrails/core 1.0.0-beta.15 → 1.0.0-beta.17

package/src/execute.ts

@@ -11,10 +11,20 @@ import type { z } from 'zod';
 import type { AnyTrail } from './trail.js';
 import type { Layer } from './layer.js';
 import type { ResourceOverrideMap } from './resource.js';
-import type { TraceContext, TraceRecord } from './internal/tracing.js';
+import type { TraceContext, TraceRecord } from './tracing.js';
 import type { Topo } from './topo.js';
 
-import { createFireFn } from './fire.js';
+import {
+  buildActivationProvenanceTraceAttrs,
+  getActivationProvenance,
+} from './activation-provenance.js';
+import {
+  createFireFn,
+  isFrameworkFireFn,
+  waitForPendingFireDispatches,
+  withFireDispatchTracking,
+} from './fire.js';
+import type { BasePermit } from './permits.js';
 import type {
   CrossBatchOptions,
   CrossFn,
@@ -31,14 +41,16 @@ import {
   CancelledError,
   InternalError,
   NotFoundError,
+  PermitError,
   RetryExhaustedError,
   TrailsError,
+  ValidationError,
 } from './errors.js';
 import {
   claimNextCrossBatchIndex,
   createCrossBatchValidationResults,
   normalizeCrossBatchConcurrency,
-} from './internal/cross-batch.js';
+} from './cross-batch.js';
 import { forkCtx } from './internal/fork-ctx.js';
 import {
   TRACE_CONTEXT_KEY,
@@ -48,12 +60,18 @@ import {
   getTraceSink,
   isTracingDisabled,
   writeToSink,
-} from './internal/tracing.js';
+} from './tracing.js';
+import {
+  OBSERVE_LOGGER_CONTEXT_KEY,
+  OBSERVE_LOGGER_METADATA_KEY,
+  createObserveLogger,
+} from './observe.js';
 import { Result } from './result.js';
+import { DETOUR_MAX_ATTEMPTS_CAP } from './detours.js';
 import { createResourceLookup } from './resource.js';
 import { createResources } from './resource-config.js';
-import { TRAILHEAD_KEY } from './types.js';
-import { validateInput } from './validation.js';
+import { LAYER_INPUTS_KEY, SURFACE_KEY } from './types.js';
+import { validateInput, validateOutput } from './validation.js';
 
 type MutableTrailContext = {
   -readonly [K in keyof TrailContext]: TrailContext[K];
@@ -69,8 +87,30 @@ export interface ExecuteTrailOptions {
   readonly ctx?: Partial<TrailContextInit> | undefined;
   /** AbortSignal override (takes final precedence over ctx and factory). */
   readonly abortSignal?: AbortSignal | undefined;
-  /** Layers to compose around the implementation. */
+  /**
+   * Typed layers supplied for this execution.
+   *
+   * Layers compose around the trail implementation. Layers without `input`
+   * schemas are surface-invisible wrappers for concerns such as tenant guards,
+   * rate limiting, circuit breaking, or custom audit logging.
+   */
   readonly layers?: readonly Layer[] | undefined;
+  /**
+   * Typed layers attached at surface scope.
+   *
+   * Surfaces (CLI, MCP, HTTP) forward their `layers` option here so they
+   * compose around every trail dispatched through that surface. The final
+   * composition order is `topo → surface → trail → blaze` (outermost-first).
+   */
+  readonly surfaceLayers?: readonly Layer[] | undefined;
+  /**
+   * Typed layers attached at topo scope.
+   *
+   * The CLI/MCP/HTTP surfaces typically forward `topo.layers` here so the
+   * topo's declared layers wrap every trail invocation. The final
+   * composition order is `topo → surface → trail → blaze` (outermost-first).
+   */
+  readonly topoLayers?: readonly Layer[] | undefined;
   /** Factory that produces a base TrailContext (takes precedence over defaults). */
   readonly createContext?:
     | (() => TrailContextInit | Promise<TrailContextInit>)
@@ -83,6 +123,36 @@ export interface ExecuteTrailOptions {
     | undefined;
   /** Topo used for signal-driven activation; required for `ctx.fire()` to work. */
   readonly topo?: Topo | undefined;
+  /**
+   * Whether this invocation is a dry run.
+   *
+   * Sets `ctx.dryRun` for the trail. Defaults to `false`. The framework
+   * never short-circuits execution on this field — it only carries the
+   * flag through. Trails that read `ctx.dryRun` decide what dry-run means.
+   */
+  readonly dryRun?: boolean | undefined;
+  /**
+   * Permit to overlay onto `ctx.permit` for this invocation.
+   *
+   * When provided, this overrides any permit supplied via `ctx.permit` on
+   * the partial context overrides or via the `createContext` factory. Leave
+   * unset to inherit the permit from the resolved context (typically
+   * `undefined`). Surfaces parse and validate the permit at their boundary
+   * (e.g. CLI `--permit '<json>'`) before passing it here.
+   */
+  readonly permit?: BasePermit | undefined;
+  /**
+   * Per-layer runtime input keyed by `Layer.name`.
+   *
+   * Surfaces (CLI, MCP, HTTP) parse their native idiom into a per-layer
+   * input object — usually projected from each layer's `input` schema —
+   * and pass it here. The executor merges these into
+   * `ctx.extensions[LAYER_INPUTS_KEY]` so layers can read their own slot
+   * via `ctx.extensions?.[LAYER_INPUTS_KEY]?.[layer.name]`.
+   *
+   * @see TRL-473 for the CLI projection contract.
+   */
+  readonly layerInputs?: Readonly<Record<string, unknown>> | undefined;
   /**
    * Override the validation schema used for input validation.
    *
@@ -114,9 +184,39 @@ const applyContextOverrides = (
       }
     : base;
 
-  return options?.abortSignal
+  const withAbort = options?.abortSignal
     ? { ...withOverrides, abortSignal: options.abortSignal }
     : withOverrides;
+
+  const withDryRun =
+    options?.dryRun === undefined
+      ? withAbort
+      : { ...withAbort, dryRun: options.dryRun };
+
+  const withPermit =
+    options?.permit === undefined
+      ? withDryRun
+      : { ...withDryRun, permit: options.permit };
+
+  if (options?.layerInputs === undefined) {
+    return withPermit;
+  }
+  // Merge per-layer inputs onto any inherited LAYER_INPUTS_KEY slot so
+  // crossed/forked contexts can preserve outer-surface routing.
+  const inheritedExtensions = withPermit.extensions ?? {};
+  const inheritedLayerInputs = (inheritedExtensions[LAYER_INPUTS_KEY] ?? {}) as
+    | Readonly<Record<string, unknown>>
+    | Record<string, unknown>;
+  return {
+    ...withPermit,
+    extensions: {
+      ...inheritedExtensions,
+      [LAYER_INPUTS_KEY]: {
+        ...inheritedLayerInputs,
+        ...options.layerInputs,
+      },
+    },
+  };
 };
 
 const bindResourceLookup = (
@@ -143,6 +243,11 @@ const bindResourceLookup = (
  * 1. Factory (`createContext`) or `createTrailContext()` defaults.
  * 2. Partial `ctx` overrides merged on top.
  * 3. `abortSignal` override takes final precedence.
+ * 4. `dryRun` option takes final precedence (defaults to `false` via
+ *    `createTrailContext` when neither option nor `ctx.dryRun` is provided).
+ * 5. `permit` option takes final precedence over any inherited permit when
+ *    provided; leaving it unset preserves whatever the resolved context
+ *    already carries.
  */
 const resolveContext = async (
   options?: ExecuteTrailOptions
@@ -155,17 +260,110 @@ const resolveContext = async (
   return bindResourceLookup(resolved, options);
 };
 
+const readObserveLoggerMetadata = (
+  ctx: TrailContext
+): Record<string, unknown> => {
+  const value = ctx.extensions?.[OBSERVE_LOGGER_METADATA_KEY];
+  return value !== null && typeof value === 'object'
+    ? (value as Record<string, unknown>)
+    : {};
+};
+
+const applyTopoObserveContext = (
+  trail: AnyTrail,
+  ctx: TrailContext,
+  topo: Topo | undefined
+): TrailContext => {
+  if (topo?.observe?.log === undefined) {
+    return ctx;
+  }
+  const hasTopoObserveLogger =
+    ctx.extensions?.[OBSERVE_LOGGER_CONTEXT_KEY] === true;
+  if (ctx.logger !== undefined && !hasTopoObserveLogger) {
+    return ctx;
+  }
+  const { log } = topo.observe;
+  // Accumulated metadata (e.g. signal fan-out fields) takes precedence over
+  // the previous observe logger's `topo`/`trailId` values, but the new trail's
+  // identity wins so log records keep pointing at the trail currently running.
+  const accumulated = readObserveLoggerMetadata(ctx);
+  return {
+    ...ctx,
+    extensions: {
+      ...ctx.extensions,
+      [OBSERVE_LOGGER_CONTEXT_KEY]: true,
+    },
+    logger: createObserveLogger(log, trail.id, {
+      ...accumulated,
+      topo: topo.name,
+      trailId: trail.id,
+    }),
+  };
+};
+
+const findMissingScopes = (
+  required: readonly string[],
+  held: readonly string[]
+): readonly string[] => required.filter((scope) => !held.includes(scope));
+
+const enforcePermitRequirement = (
+  trail: AnyTrail,
+  ctx: TrailContext
+): Result<TrailContext, Error> => {
+  const requirement = trail.permit;
+  if (requirement === undefined || requirement === 'public') {
+    return Result.ok(ctx);
+  }
+
+  if (ctx.permit === undefined) {
+    return Result.err(
+      new PermitError('No permit provided', {
+        context: { required: requirement.scopes, trailId: trail.id },
+      })
+    );
+  }
+
+  const missing = findMissingScopes(requirement.scopes, ctx.permit.scopes);
+  return missing.length === 0
+    ? Result.ok(ctx)
+    : Result.err(
+        new PermitError(`Missing scopes: ${missing.join(', ')}`, {
+          context: { missing, required: requirement.scopes, trailId: trail.id },
+        })
+      );
+};
+
 const prepareContext = async (
   trail: AnyTrail,
   options?: ExecuteTrailOptions
-): Promise<Result<TrailContext, Error>> => {
-  const baseCtx = await resolveContext(options);
-  return await createResources(
+): Promise<
+  Result<
+    { readonly ctx: TrailContext; readonly releaseResources: () => void },
+    Error
+  >
+> => {
+  const baseCtx = applyTopoObserveContext(
     trail,
-    baseCtx,
+    await resolveContext(options),
+    options?.topo
+  );
+  const permitted = enforcePermitRequirement(trail, baseCtx);
+  if (permitted.isErr()) {
+    return Result.err(permitted.error);
+  }
+
+  const resources = await createResources(
+    trail,
+    permitted.value,
     options?.resources,
     options?.configValues
   );
+  return resources.isErr()
+    ? Result.err(resources.error)
+    : Result.ok({
+        ctx: resources.value.ctx,
+        releaseResources: resources.value.release,
+      });
 };
 
 // ---------------------------------------------------------------------------
@@ -278,18 +476,27 @@ const buildTracedContext = (
     parentId: parent?.spanId,
     permit: extractPermit(ctx),
     rootId: parent?.rootId,
+    sampled: parent?.sampled ?? true,
+    surface: ctx.extensions?.[SURFACE_KEY] as TraceRecord['surface'],
     traceId: parent?.traceId,
     trailId: trail.id,
-    trailhead: ctx.extensions?.[TRAILHEAD_KEY] as TraceRecord['trailhead'],
   });
+  const activation = getActivationProvenance(ctx);
+  const recordWithAttrs: TraceRecord =
+    activation === undefined
+      ? record
+      : {
+          ...record,
+          attrs: buildActivationProvenanceTraceAttrs(activation),
+        };
 
   // Root trace context for this trail's span. When inheriting a parent, the
   // traceId/rootId carry forward and only spanId advances to the new record.
   const rootTrace: TraceContext = {
     rootId: parent?.rootId ?? record.id,
-    sampled: true,
-    spanId: record.id,
-    traceId: record.traceId,
+    sampled: recordWithAttrs.sampled ?? true,
+    spanId: recordWithAttrs.id,
+    traceId: recordWithAttrs.traceId,
   };
 
   const tracedCtx: TrailContext = {
@@ -301,7 +508,7 @@ const buildTracedContext = (
     trace: buildTraceFn(rootTrace, sink),
   };
 
-  return { record, tracedCtx };
+  return { record: recordWithAttrs, tracedCtx };
 };
 
 const buildUntracedContext = (ctx: TrailContext): TrailContext => {
@@ -326,6 +533,7 @@ const runImplWithRootRecord = async (
 ): Promise<Result<unknown, Error>> => {
   try {
     const result = await impl(input, tracedCtx);
+    await waitForPendingFireDispatches(tracedCtx);
     const outcome = deriveOutcome(result);
     await writeToSink(
       sink,
@@ -333,6 +541,7 @@ const runImplWithRootRecord = async (
     );
     return result;
   } catch (error: unknown) {
+    await waitForPendingFireDispatches(tracedCtx);
     // Normalize unexpected throws so the root record still reflects the error
     // outcome. The outer executeTrail try/catch converts the thrown value into
     // a Result.err(InternalError) for the caller.
@@ -390,6 +599,45 @@ const stripInheritedResourceExtensions = (
   return Object.fromEntries(entries);
 };
 
+const deriveConcurrentBranchObserveMetadata = (
+  ctx: TrailContext,
+  target: AnyTrail,
+  branchIndex: number
+): Record<string, unknown> | undefined => {
+  // Only carry observe metadata forward when the parent ctx is using a
+  // topo-managed observe logger. Otherwise we'd attach branch fields to
+  // caller-supplied loggers that didn't opt into the structured contract.
+  if (ctx.extensions?.[OBSERVE_LOGGER_CONTEXT_KEY] !== true) {
+    return;
+  }
+  return {
+    ...readObserveLoggerMetadata(ctx),
+    branchIndex,
+    crossedTrailId: target.id,
+  };
+};
+
+const buildConcurrentBranchExtensions = (
+  ctx: TrailContext,
+  target: AnyTrail,
+  topo: Topo | undefined,
+  branchIndex: number
+): Record<string, unknown> => {
+  const stripped = stripInheritedResourceExtensions(ctx, target, topo);
+  const observeMetadata = deriveConcurrentBranchObserveMetadata(
+    ctx,
+    target,
+    branchIndex
+  );
+  if (observeMetadata === undefined) {
+    return stripped;
+  }
+  return {
+    ...stripped,
+    [OBSERVE_LOGGER_METADATA_KEY]: observeMetadata,
+  };
+};
+
 const deriveConcurrentBranchLogger = (
   ctx: TrailContext,
   target: AnyTrail,
@@ -406,7 +654,7 @@ const deriveConcurrentBranchLogger = (
  * Concurrent crossings should not inherit already-resolved resource instances
  * from the parent execution scope. Stripping resource IDs from extensions
  * forces each branch to resolve its own scope while still carrying forward
- * request-scoped values like tracing, trailhead identity, permits, and the
+ * request-scoped values like tracing, surface identity, permits, and the
  * shared AbortSignal.
  *
  * `cross`, `fire`, and `resource` are cleared so the child execution can
@@ -420,7 +668,7 @@ const buildConcurrentBranchContext = (
   branchIndex: number
 ): TrailContext =>
   forkCtx(ctx, {
-    extensions: stripInheritedResourceExtensions(ctx, target, topo),
+    extensions: buildConcurrentBranchExtensions(ctx, target, topo, branchIndex),
     logger: deriveConcurrentBranchLogger(ctx, target, branchIndex),
   });
 
@@ -617,8 +865,18 @@ const bindCrossToCtx = (
 const bindFireToCtx = (
   ctx: TrailContext,
   topo: Topo | undefined,
-  options: ExecuteTrailOptions | undefined
+  options: ExecuteTrailOptions | undefined,
+  producerTrailId?: string | undefined
 ): TrailContext => {
+  // Symmetric with bindCrossToCtx: a caller-supplied ctx.fire (e.g. test
+  // helper, scenario harness, or runtime intercepting signal fan-out) is
+  // preserved as-is. Without this guard, passing both `topo: app` and a
+  // custom `ctx.fire` would silently clobber the injected mock with the
+  // topo-backed dispatcher. Framework-created fire functions are replaced
+  // because consumer fan-out seeds them before the consumer trace span exists.
+  if (ctx.fire !== undefined && !isFrameworkFireFn(ctx.fire)) {
+    return ctx;
+  }
   if (topo === undefined) {
     return ctx;
   }
@@ -634,15 +892,20 @@ const bindFireToCtx = (
     validationSchema: _omitSchema,
     ...forwarded
   } = options ?? {};
-  const fire = createFireFn(topo, ctx, (consumer, input, consumerCtx) =>
-    // eslint-disable-next-line no-use-before-define -- executor closure runs only after executeTrail is defined
-    executeTrail(consumer, input, {
-      ...forwarded,
-      ctx: consumerCtx,
-      topo,
-    })
+  const trackedCtx = withFireDispatchTracking(ctx);
+  const fire = createFireFn(
+    topo,
+    trackedCtx,
+    (consumer, input, consumerCtx) =>
+      // eslint-disable-next-line no-use-before-define -- executor closure runs only after executeTrail is defined
+      executeTrail(consumer, input, {
+        ...forwarded,
+        ctx: consumerCtx,
+        topo,
+      }),
+    producerTrailId
   );
-  return { ...ctx, fire };
+  return { ...trackedCtx, fire };
 };
 
 const bindCrossAtLayerBoundary =
@@ -656,6 +919,7 @@ const bindCrossAtLayerBoundary =
 
 const bindFireAtLayerBoundary = <I, O>(
   implementation: Implementation<I, O>,
+  trail: AnyTrail,
   topo: Topo | undefined,
   options: ExecuteTrailOptions | undefined
 ): Implementation<I, O> => {
@@ -664,15 +928,13 @@ const bindFireAtLayerBoundary = <I, O>(
   }
 
   return (input, ctx) =>
-    implementation(input, bindFireToCtx(ctx, topo, options));
+    implementation(input, bindFireToCtx(ctx, topo, options, trail.id));
 };
 
 // ---------------------------------------------------------------------------
 // Detour loop
 // ---------------------------------------------------------------------------
 
-const DETOUR_MAX_ATTEMPTS_CAP = 5;
-
 /**
  * Find the first detour whose `on` class matches the error via `instanceof`.
  *
@@ -818,6 +1080,28 @@ const wrapWithDetours = (
   };
 };
 
+const wrapWithOutputValidation = (
+  trail: AnyTrail,
+  implementation: Implementation<unknown, unknown>
+): Implementation<unknown, unknown> => {
+  const { output } = trail;
+  if (output === undefined) {
+    return implementation;
+  }
+
+  return async (input, ctx) => {
+    const result = await implementation(input, ctx);
+    if (result.isErr()) {
+      return result;
+    }
+
+    const validated = validateOutput(output, result.value);
+    return validated.isErr()
+      ? Result.err(validated.error)
+      : Result.ok(validated.value);
+  };
+};
+
 const prepareRunImpl = (
   trail: AnyTrail,
   ctx: TrailContext,
@@ -831,7 +1115,8 @@ const prepareRunImpl = (
   const ctxWithIntrinsics = bindFireToCtx(
     bindCrossToCtx(ctx, topo, options),
     topo,
-    options
+    options,
+    trail.id
   );
   // Detour loop wraps the blaze (inside layer stack, closest to blaze)
   let impl = wrapWithDetours(
@@ -841,6 +1126,7 @@ const prepareRunImpl = (
         topo,
         options
       ),
+      trail,
       topo,
       options
     ),
@@ -856,6 +1142,7 @@ const prepareRunImpl = (
           topo,
           options
         ),
+        trail,
         topo,
         options
       );
@@ -864,7 +1151,7 @@ const prepareRunImpl = (
 
   return {
     ctxWithIntrinsics,
-    impl,
+    impl: wrapWithOutputValidation(trail, impl),
   };
 };
 
@@ -883,7 +1170,11 @@ const runImplWithoutTracing = async (
     topo,
     options
   );
-  return await prepared.impl(input, prepared.ctxWithIntrinsics);
+  try {
+    return await prepared.impl(input, prepared.ctxWithIntrinsics);
+  } finally {
+    await waitForPendingFireDispatches(prepared.ctxWithIntrinsics);
+  }
 };
 
 const runTrailWithTracing = async (
@@ -927,7 +1218,7 @@ const runTrail = async (
   topo: Topo | undefined,
   options: ExecuteTrailOptions | undefined
 ): Promise<Result<unknown, Error>> => {
-  const sink = getTraceSink();
+  const sink = topo?.observe?.trace ?? getTraceSink();
   return isTracingDisabled(sink)
     ? await runImplWithoutTracing(trail, input, ctx, layers, topo, options)
     : await runTrailWithTracing(trail, input, ctx, layers, topo, options, sink);
@@ -937,6 +1228,102 @@ const runTrail = async (
 // Pipeline
 // ---------------------------------------------------------------------------
 
+/**
+ * Compose the typed layers attached at topo, surface, and trail scope.
+ *
+ * Composition order is topo → surface → trail → execution-supplied → blaze
+ * (outermost-first): trail-scope layers run inside surface/topo layers, and
+ * `executeTrail({ layers })` layers wrap closest to the blaze for per-call
+ * behavior.
+ */
+const composeAttachedLayers = (
+  trail: AnyTrail,
+  options: ExecuteTrailOptions | undefined
+): readonly Layer[] => [
+  ...(options?.topoLayers ?? []),
+  ...(options?.surfaceLayers ?? []),
+  ...trail.layers,
+  ...(options?.layers ?? []),
+];
+
+const isLayerInputMap = (
+  value: unknown
+): value is Readonly<Record<string, unknown>> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const readContextLayerInputs = (
+  ctx: TrailContext
+): Result<Readonly<Record<string, unknown>> | undefined, ValidationError> => {
+  const value = ctx.extensions?.[LAYER_INPUTS_KEY];
+  if (value === undefined) {
+    return Result.ok();
+  }
+  return isLayerInputMap(value)
+    ? Result.ok(value)
+    : Result.err(
+        new ValidationError(
+          'Layer inputs must be an object keyed by layer name',
+          {
+            context: { extensionKey: LAYER_INPUTS_KEY },
+          }
+        )
+      );
+};
+
+const validateLayerInputs = (
+  layers: readonly Layer[],
+  layerInputs: Readonly<Record<string, unknown>>
+): Result<Readonly<Record<string, unknown>>, ValidationError> => {
+  const validated: Record<string, unknown> = { ...layerInputs };
+  for (const layer of layers) {
+    if (layer.input === undefined) {
+      continue;
+    }
+    const slot = layerInputs[layer.name];
+    if (slot === undefined) {
+      continue;
+    }
+    const parsed = layer.input.safeParse(slot);
+    if (!parsed.success) {
+      return Result.err(
+        new ValidationError(
+          `Invalid input for layer '${layer.name}': ${parsed.error.message}`,
+          {
+            cause: parsed.error,
+            context: { issues: parsed.error.issues, layerName: layer.name },
+          }
+        )
+      );
+    }
+    validated[layer.name] = parsed.data;
+  }
+  return Result.ok(validated);
+};
+
+const validateContextLayerInputs = (
+  ctx: TrailContext,
+  layers: readonly Layer[]
+): Result<TrailContext, ValidationError> => {
+  const layerInputs = readContextLayerInputs(ctx);
+  if (layerInputs.isErr()) {
+    return Result.err(layerInputs.error);
+  }
+  if (layerInputs.value === undefined) {
+    return Result.ok(ctx);
+  }
+  const validated = validateLayerInputs(layers, layerInputs.value);
+  if (validated.isErr()) {
+    return Result.err(validated.error);
+  }
+  return Result.ok({
+    ...ctx,
+    extensions: {
+      ...ctx.extensions,
+      [LAYER_INPUTS_KEY]: validated.value,
+    },
+  });
+};
+
 /**
  * Execute a trail through the standard validate-context-layers-run pipeline.
  *
@@ -959,17 +1346,29 @@ export const executeTrail = async (
 
     const resolvedCtx = await prepareContext(trail, options);
     if (resolvedCtx.isErr()) {
-      return resolvedCtx;
+      return Result.err(resolvedCtx.error);
     }
 
-    return await runTrail(
-      trail,
-      validated.value,
-      resolvedCtx.value,
-      options?.layers ?? [],
-      options?.topo,
-      options
-    );
+    const layers = composeAttachedLayers(trail, options);
+    try {
+      const layerCtx = validateContextLayerInputs(
+        resolvedCtx.value.ctx,
+        layers
+      );
+      if (layerCtx.isErr()) {
+        return Result.err(layerCtx.error);
+      }
+      return await runTrail(
+        trail,
+        validated.value,
+        layerCtx.value,
+        layers,
+        options?.topo,
+        options
+      );
+    } finally {
+      resolvedCtx.value.releaseResources();
+    }
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);
     return Result.err(new InternalError(message));