@codefast/di 0.10.0 → 0.11.0

package/dist/resolution/cache/class-introspector.js

@@ -3,8 +3,8 @@
  *
  * @remarks Metadata cannot change once a class is defined, so nothing here needs version stamping.
  */
-import { constructWithAmbientResolution, runWithAmbientResolution } from "#/ambient/active-container";
-import { InvalidMetadataError } from "#/errors/errors";
+import { constructWithAmbientResolution, runWithAmbientResolution } from "#ambient/active-container";
+import { InvalidMetadataError } from "#errors/errors";
 // Verified pairs, not verified classes: two readers may disagree about the same class, and a reader
 // that goes out of scope takes its record with it.
 const verifiedTargets = new WeakMap();
@@ -21,6 +21,20 @@ function markVerified(cache, reader, target) {
     }
     verified.add(target);
 }
+/**
+ * Runs `validate` against a reader's metadata the first time this process sees the pair, then remembers it.
+ *
+ * @remarks An absent metadata answer needs no check; a verified pair is returned untouched, so the
+ * shape assertion runs once per `(reader, target)` rather than per container.
+ */
+function verifyOnce(cache, reader, target, metadata, validate) {
+    if (metadata === undefined || isVerified(cache, reader, target)) {
+        return metadata;
+    }
+    validate(metadata);
+    markVerified(cache, reader, target);
+    return metadata;
+}
 /**
  * A reader's constructor metadata for a class, verified the first time this process asks.
  *
@@ -31,16 +45,9 @@ function markVerified(cache, reader, target) {
  * @since 0.6.0
  */
 export function verifyConstructorMetadata(reader, target) {
-    const metadata = reader.getConstructorMetadata(target);
-    if (metadata === undefined) {
-        return undefined;
-    }
-    if (isVerified(verifiedTargets, reader, target)) {
-        return metadata;
-    }
-    assertConstructorMetadata(metadata, target);
-    markVerified(verifiedTargets, reader, target);
-    return metadata;
+    return verifyOnce(verifiedTargets, reader, target, reader.getConstructorMetadata(target), (metadata) => {
+        assertConstructorMetadata(metadata, target);
+    });
 }
 /**
  * Verifies what a reader claims about a class, since a `MetadataReader` is a public seam.
@@ -81,29 +88,25 @@ export function assertConstructorMetadata(metadata, target) {
  * @since 0.6.0
  */
 export function verifyLifecycleMetadata(reader, target) {
-    const metadata = reader.getLifecycleMetadata(target);
-    if (metadata === undefined || isVerified(verifiedLifecycleTargets, reader, target)) {
-        return metadata;
-    }
-    if (typeof metadata !== "object" || metadata === null) {
-        throw new InvalidMetadataError(target.name, `lifecycle metadata: expected an object, received ${typeof metadata}`);
-    }
-    for (const phase of ["postConstruct", "preDestroy"]) {
-        const methods = Reflect.get(metadata, phase);
-        if (methods === undefined) {
-            continue;
-        }
-        if (!Array.isArray(methods)) {
-            throw new InvalidMetadataError(target.name, `lifecycle metadata: ${phase} is not an array`);
+    return verifyOnce(verifiedLifecycleTargets, reader, target, reader.getLifecycleMetadata(target), (metadata) => {
+        if (typeof metadata !== "object" || metadata === null) {
+            throw new InvalidMetadataError(target.name, `lifecycle metadata: expected an object, received ${typeof metadata}`);
         }
-        for (const [position, name] of methods.entries()) {
-            if (typeof name !== "string") {
-                throw new InvalidMetadataError(target.name, `lifecycle metadata: ${phase}[${String(position)}] is not a string`);
+        for (const phase of ["postConstruct", "preDestroy"]) {
+            const methods = Reflect.get(metadata, phase);
+            if (methods === undefined) {
+                continue;
+            }
+            if (!Array.isArray(methods)) {
+                throw new InvalidMetadataError(target.name, `lifecycle metadata: ${phase} is not an array`);
+            }
+            for (const [position, name] of methods.entries()) {
+                if (typeof name !== "string") {
+                    throw new InvalidMetadataError(target.name, `lifecycle metadata: ${phase}[${String(position)}] is not a string`);
+                }
             }
         }
-    }
-    markVerified(verifiedLifecycleTargets, reader, target);
-    return metadata;
+    });
 }
 /**
  * A reader's accessor metadata for a class, verified the first time this process asks.
@@ -111,32 +114,28 @@ export function verifyLifecycleMetadata(reader, target) {
  * @since 0.6.0
  */
 export function verifyAccessorMetadata(reader, target) {
-    const metadata = reader.getAccessorMetadata?.(target);
-    if (metadata === undefined || isVerified(verifiedAccessorTargets, reader, target)) {
-        return metadata;
-    }
-    if (!Array.isArray(metadata)) {
-        throw new InvalidMetadataError(target.name, "accessor metadata: expected an array");
-    }
-    for (const [position, entry] of metadata.entries()) {
-        if (typeof entry !== "object" || entry === null) {
-            throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}] is not an object`);
-        }
-        const key = Reflect.get(entry, "key");
-        if (typeof key !== "string" && typeof key !== "symbol") {
-            throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}].key is not a string or symbol`);
+    return verifyOnce(verifiedAccessorTargets, reader, target, reader.getAccessorMetadata?.(target), (metadata) => {
+        if (!Array.isArray(metadata)) {
+            throw new InvalidMetadataError(target.name, "accessor metadata: expected an array");
         }
-        const descriptor = Reflect.get(entry, "descriptor");
-        if (typeof descriptor !== "object" || descriptor === null) {
-            throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}].descriptor is not an object`);
-        }
-        const dependency = Reflect.get(descriptor, "token");
-        if (typeof dependency !== "object" && typeof dependency !== "function") {
-            throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}].descriptor.token is not a token or a class`);
+        for (const [position, entry] of metadata.entries()) {
+            if (typeof entry !== "object" || entry === null) {
+                throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}] is not an object`);
+            }
+            const key = Reflect.get(entry, "key");
+            if (typeof key !== "string" && typeof key !== "symbol") {
+                throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}].key is not a string or symbol`);
+            }
+            const descriptor = Reflect.get(entry, "descriptor");
+            if (typeof descriptor !== "object" || descriptor === null) {
+                throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}].descriptor is not an object`);
+            }
+            const dependency = Reflect.get(descriptor, "token");
+            if (typeof dependency !== "object" && typeof dependency !== "function") {
+                throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}].descriptor.token is not a token or a class`);
+            }
         }
-    }
-    markVerified(verifiedAccessorTargets, reader, target);
-    return metadata;
+    });
 }
 const cachesByReader = new WeakMap();
 function cachesFor(reader) {
@@ -174,6 +173,24 @@ export class ClassIntrospector {
         (caches.constructorMetadata ??= new WeakMap()).set(target, metadata ?? null);
         return metadata;
     }
+    /**
+     * The nearest ancestor's own constructor metadata, for a subclass that declares none of its own.
+     *
+     * @remarks Constructor metadata is never borrowed down the chain, so a subclass with an implicit
+     * constructor would be built with zero arguments; this lets the resolver name the base whose
+     * declared deps the subclass silently drops.
+     */
+    inheritedConstructorMetadata(target) {
+        let current = Object.getPrototypeOf(target);
+        while (typeof current === "function" && current !== Function.prototype) {
+            const metadata = this.constructorMetadata(current);
+            if (metadata !== undefined) {
+                return { base: current, metadata };
+            }
+            current = Object.getPrototypeOf(current);
+        }
+        return undefined;
+    }
     /**
      * Whether the class has a `@postConstruct` hook, or `undefined` until {@link discoverPostConstruct}.
      *

package/dist/resolution/context.d.ts

@@ -1,7 +1,7 @@
 /** The `ResolutionContext` a factory is handed, and the callbacks the resolver answers it with. */
-import type { Token } from "#/core/token";
-import type { BindingIdentifier, BindingKind, BindingScope, ConstraintContext, Constructor, ResolutionFrame, ResolutionContext, ResolveOptions } from "#/core/types";
-import type { BranchDepth, OwnedBranchStack } from "#/resolution/path/resolution-path";
+import type { Token } from "#core/token";
+import type { ConstraintContext, Constructor, ResolutionFrame, ResolutionContext, ResolveOptions } from "#core/types";
+import type { BranchDepth, OwnedBranchStack } from "#resolution/path/resolution-path";
 /**
  * The engine surface a resolution context calls back into to resolve further dependencies.
  *
@@ -11,8 +11,6 @@ export interface ResolverCallbacks {
     resolveFromContext<Value>(token: Token<Value> | Constructor<Value>, resolutionStack: Array<ResolutionFrame>): Value;
     resolve<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Value;
     resolveAsyncFromContext<Value>(token: Token<Value> | Constructor<Value>, resolutionStack: Array<ResolutionFrame>, branchDepth: BranchDepth): Promise<Value>;
-    /** Not one of the eight `Value`-naming entry points: its caller is, and casts once. */
-    resolveAsyncFromCascade(token: Token<unknown> | Constructor): Promise<unknown>;
     resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Promise<Value>;
     resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Value | undefined;
     resolveOptionalAsync<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Promise<Value | undefined>;
@@ -55,6 +53,8 @@ export declare class AsyncLevelContext implements ResolutionContext {
      */
     constructor(resolver: ResolverCallbacks, resolutionStack: OwnedBranchStack, currentOptions: ResolveOptions | undefined);
     get graph(): ConstraintContext;
+    /** This level's own path, fixed for its lifetime, for a caller that names it in an error. */
+    get ownPath(): ReadonlyArray<ResolutionFrame>;
     resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value;
     resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value>;
     resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
@@ -63,27 +63,19 @@ export declare class AsyncLevelContext implements ResolutionContext {
     resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<ReadonlyArray<Value>>;
 }
 /**
- * The one context every level of an open synchronous factory cascade shares.
+ * The one constraint context every predicate reads, whatever lane built it.
  *
- * @remarks It carries no per-level state at all: while the cascade is open, the resolver's stack
- * *is* this level's ancestor chain, so nothing has to be allocated per level.
+ * @remarks One shape for the shared root, a selection over a live synchronous stack, an async
+ * level's prefix and an inspector's probe, so a predicate's call site stays monomorphic.
  *
- * @since 0.5.0-canary.9
+ * @since 0.11.0
  */
-export declare class AsyncCascadeContext implements ResolutionContext {
+export declare class DefaultConstraintContext implements ConstraintContext {
     #private;
-    constructor(resolver: ResolverCallbacks, cascadeStack: Array<ResolutionFrame>);
-    get graph(): ConstraintContext;
-    resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value;
-    resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value>;
-    resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
-    resolveOptionalAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value | undefined>;
-    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): ReadonlyArray<Value>;
-    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<ReadonlyArray<Value>>;
-}
-/**
- * Creates the resolution-stack frame for one in-flight resolve.
- *
- * @since 0.3.16-canary.0
- */
-export declare function buildResolutionFrame(tokenName: string, scope: BindingScope, bindingId: BindingIdentifier, kind: BindingKind, slot: ResolutionFrame["slot"]): ResolutionFrame;
+    readonly resolutionStack: ReadonlyArray<ResolutionFrame>;
+    readonly parent: ResolutionFrame | undefined;
+    readonly currentResolveOptions: Readonly<ResolveOptions> | undefined;
+    constructor(resolutionStack: ReadonlyArray<ResolutionFrame>, currentResolveOptions: ResolveOptions | undefined);
+    get resolutionPath(): ReadonlyArray<string>;
+    get ancestors(): ReadonlyArray<ResolutionFrame>;
+}

package/dist/resolution/context.js

@@ -1,4 +1,4 @@
-import { UNOWNED_BRANCH } from "#/resolution/path/resolution-path";
+import { bindingsOf, enterSeededPath, leaveSeededPath, UNOWNED_BRANCH } from "#resolution/path/resolution-path";
 /**
  * The `ResolutionContext` handed to factories and hooks, backed by the engine's callbacks.
  *
@@ -88,6 +88,7 @@ export class AsyncLevelContext {
     }
     #graph;
     #exactStackCache;
+    #exactBindingsCache;
     get graph() {
         if (this.#graph === undefined) {
             this.#graph = new DefaultConstraintContext(this.#exactStack(), this.#currentOptions);
@@ -99,11 +100,30 @@ export class AsyncLevelContext {
     #exactStack() {
         return (this.#exactStackCache ??= this.#resolutionStack.slice(0, this.#branchDepth));
     }
+    /** This level's own path, fixed for its lifetime, for a caller that names it in an error. */
+    get ownPath() {
+        return this.#exactStack();
+    }
+    // The bindings a synchronous call from this level marks in flight, read off the frames once.
+    #exactBindings() {
+        return (this.#exactBindingsCache ??= bindingsOf(this.#exactStack()));
+    }
+    // A synchronous call from an async level runs over a path no synchronous frame pushed, so the
+    // level's ancestors are marked in flight for its duration — and the level itself, whose factory is
+    // the caller: a factory resolving its own token synchronously has closed a cycle.
     resolve(token, options) {
-        if (options === undefined) {
-            return this.#resolver.resolveFromContext(token, this.#exactStack());
+        const path = this.#exactStack();
+        const marked = this.#exactBindings();
+        const alreadyInFlight = enterSeededPath(marked);
+        try {
+            if (options === undefined) {
+                return this.#resolver.resolveFromContext(token, path);
+            }
+            return this.#resolver.resolve(token, options, path);
+        }
+        finally {
+            leaveSeededPath(marked, alreadyInFlight);
         }
-        return this.#resolver.resolve(token, options, this.#exactStack());
     }
     resolveAsync(token, options) {
         if (options === undefined) {
@@ -113,64 +133,43 @@ export class AsyncLevelContext {
         return this.#resolver.resolveAsync(token, options, this.#exactStack());
     }
     resolveOptional(token, options) {
-        return this.#resolver.resolveOptional(token, options, this.#exactStack());
+        const path = this.#exactStack();
+        const marked = this.#exactBindings();
+        const alreadyInFlight = enterSeededPath(marked);
+        try {
+            return this.#resolver.resolveOptional(token, options, path);
+        }
+        finally {
+            leaveSeededPath(marked, alreadyInFlight);
+        }
     }
     resolveOptionalAsync(token, options) {
         return this.#resolver.resolveOptionalAsync(token, options, this.#exactStack());
     }
     resolveAll(token, options) {
-        return this.#resolver.resolveAll(token, options, this.#exactStack());
+        const path = this.#exactStack();
+        const marked = this.#exactBindings();
+        const alreadyInFlight = enterSeededPath(marked);
+        try {
+            return this.#resolver.resolveAll(token, options, path);
+        }
+        finally {
+            leaveSeededPath(marked, alreadyInFlight);
+        }
     }
     resolveAllAsync(token, options) {
         return this.#resolver.resolveAllAsync(token, options, this.#exactStack());
     }
 }
 /**
- * The one context every level of an open synchronous factory cascade shares.
+ * The one constraint context every predicate reads, whatever lane built it.
  *
- * @remarks It carries no per-level state at all: while the cascade is open, the resolver's stack
- * *is* this level's ancestor chain, so nothing has to be allocated per level.
+ * @remarks One shape for the shared root, a selection over a live synchronous stack, an async
+ * level's prefix and an inspector's probe, so a predicate's call site stays monomorphic.
  *
- * @since 0.5.0-canary.9
+ * @since 0.11.0
  */
-export class AsyncCascadeContext {
-    #resolver;
-    #cascadeStack;
-    constructor(resolver, cascadeStack) {
-        this.#resolver = resolver;
-        this.#cascadeStack = cascadeStack;
-    }
-    get graph() {
-        // Not memoized: this context outlives every level, so a cached graph would describe whichever
-        // level asked first. The cascade stack is only this level's ancestors while it is open.
-        return new DefaultConstraintContext(this.#cascadeStack, undefined);
-    }
-    resolve(token, options) {
-        if (options === undefined) {
-            return this.#resolver.resolveFromContext(token, this.#cascadeStack);
-        }
-        return this.#resolver.resolve(token, options, this.#cascadeStack);
-    }
-    resolveAsync(token, options) {
-        if (options === undefined) {
-            return this.#resolver.resolveAsyncFromCascade(token);
-        }
-        return this.#resolver.resolveAsync(token, options, [...this.#cascadeStack]);
-    }
-    resolveOptional(token, options) {
-        return this.#resolver.resolveOptional(token, options, this.#cascadeStack);
-    }
-    resolveOptionalAsync(token, options) {
-        return this.#resolver.resolveOptionalAsync(token, options, [...this.#cascadeStack]);
-    }
-    resolveAll(token, options) {
-        return this.#resolver.resolveAll(token, options, this.#cascadeStack);
-    }
-    resolveAllAsync(token, options) {
-        return this.#resolver.resolveAllAsync(token, options, [...this.#cascadeStack]);
-    }
-}
-class DefaultConstraintContext {
+export class DefaultConstraintContext {
     resolutionStack;
     parent;
     currentResolveOptions;
@@ -195,12 +194,4 @@ class DefaultConstraintContext {
         }
         return this.#ancestors;
     }
-}
-/**
- * Creates the resolution-stack frame for one in-flight resolve.
- *
- * @since 0.3.16-canary.0
- */
-export function buildResolutionFrame(tokenName, scope, bindingId, kind, slot) {
-    return { tokenName, scope, bindingId, kind, slot };
 }

package/dist/resolution/path/resolution-path.d.ts

@@ -1,12 +1,21 @@
-import type { BindingIdentifier, ResolutionFrame } from "#/core/types";
+import type { Binding } from "#core/binding";
+import type { ResolutionFrame } from "#core/types";
 /**
- * Where the cycle check switches from a linear frame scan to an attached Set.
+ * Creates the resolution-stack frame for one in-flight resolve of a binding.
  *
- * @remarks Measured rather than guessed: below this depth the linear scan wins, above it the Set does.
+ * @remarks A literal, because the engine's hot loads read frames: a class instance costs every level
+ * a few nanoseconds, and a weak map beside the frames costs every cold container an ephemeron insert
+ * per binding. The binding rides under a symbol no caller enumerates.
  *
- * @since 0.5.0-canary.7
+ * @since 0.3.16-canary.0
  */
-export declare const RESOLUTION_SET_THRESHOLD = 32;
+export declare function buildResolutionFrame(binding: Binding, tokenName: string): ResolutionFrame;
+/**
+ * The bindings behind the resolver-built frames of a path, in path order.
+ *
+ * @since 0.11.0
+ */
+export declare function bindingsOf(frames: ReadonlyArray<ResolutionFrame>): Array<Binding>;
 /**
  * The token names along a stack plus the frame that closed the cycle — built only to throw.
  *
@@ -14,18 +23,44 @@ export declare const RESOLUTION_SET_THRESHOLD = 32;
  */
 export declare function cycleNamesOf(resolutionStack: ReadonlyArray<ResolutionFrame>, closingName: string): Array<string>;
 /**
- * Marks a level as in-flight on this stack, throwing if its binding is already an ancestor.
+ * Marks a level in flight on a synchronous path and pushes its frame, throwing if its binding already is.
  *
- * @remarks The check keys on binding identity — two distinct tokens may share a display name — and
- * the names an error prints are derived from the frames at the throw site. Unmark by popping the
- * stack plus `set?.delete(frame.bindingId)`. Sync only — the async lane never removes an entry, so
- * it extends a branch instead; see {@link extendResolutionBranch}.
+ * @remarks Synchronous code does not interleave, so the flag on the binding is exact membership in the
+ * path one call stack is resolving — at any depth, with no side table and nothing to size. The check
+ * keys on the binding, never on a token's display name, and the names an error prints are read off
+ * the frames at the throw site. Unmark with {@link leaveSyncPath}. Sync only: the async branch lane
+ * never unwinds, so it extends a branch instead; see {@link extendResolutionBranch}.
  *
- * @returns the membership set once the stack is deep enough to carry one, else `undefined`.
+ * @since 0.11.0
+ */
+export declare function enterSyncPath(resolutionStack: Array<ResolutionFrame>, binding: Binding, frame: ResolutionFrame): void;
+/**
+ * Pops the level {@link enterSyncPath} pushed and clears its binding's flag.
+ *
+ * @since 0.11.0
+ */
+export declare function leaveSyncPath(resolutionStack: Array<ResolutionFrame>, binding: Binding): void;
+/**
+ * Marks every binding of a seeded path in flight for the synchronous call about to run over it.
+ *
+ * @remarks A seed is a path no synchronous frame pushed — a plan's static ancestors handed to an
+ * escape, or an async level's branch handed to a factory's synchronous call — so its bindings carry no
+ * flag, and marking them is what keeps the flag the one check. A binding already in flight was
+ * flagged by an enclosing synchronous frame that is still running, which is the same fact stated
+ * once already, so it is left as it is and left alone on the way out; a cycle is reported where the
+ * path re-enters that binding, which is where the frames to name it are.
+ *
+ * @returns the bindings this call left flagged as it found them, when there were any, for {@link leaveSeededPath}
+ *
+ * @since 0.11.0
+ */
+export declare function enterSeededPath(bindings: ReadonlyArray<Binding>): Set<Binding> | undefined;
+/**
+ * Clears the flags {@link enterSeededPath} set, leaving the ones it found already set.
  *
- * @since 0.5.0-canary.7
+ * @since 0.11.0
  */
-export declare function enterResolutionPath(resolutionStack: Array<ResolutionFrame>, frame: ResolutionFrame): Set<BindingIdentifier> | undefined;
+export declare function leaveSeededPath(bindings: ReadonlyArray<Binding>, alreadyInFlight: Set<Binding> | undefined): void;
 declare const BRANCH_BRAND: unique symbol;
 /**
  * A resolution stack one async branch owns, so appending to it cannot disturb another branch.

package/dist/resolution/path/resolution-path.js

@@ -1,14 +1,42 @@
 /** Cycle-detection bookkeeping carried on the resolution stack itself. */
-import { CircularDependencyError } from "#/errors/errors";
-const RESOLUTION_SET_KEY = Symbol("di:resolution-set");
+import { CircularDependencyError } from "#errors/errors";
+/** The key under which a resolver-built frame carries its binding, for marking a seeded path. */
+const FRAME_BINDING = Symbol("di:frame-binding");
 /**
- * Where the cycle check switches from a linear frame scan to an attached Set.
+ * Creates the resolution-stack frame for one in-flight resolve of a binding.
  *
- * @remarks Measured rather than guessed: below this depth the linear scan wins, above it the Set does.
+ * @remarks A literal, because the engine's hot loads read frames: a class instance costs every level
+ * a few nanoseconds, and a weak map beside the frames costs every cold container an ephemeron insert
+ * per binding. The binding rides under a symbol no caller enumerates.
  *
- * @since 0.5.0-canary.7
+ * @since 0.3.16-canary.0
  */
-export const RESOLUTION_SET_THRESHOLD = 32;
+export function buildResolutionFrame(binding, tokenName) {
+    const frame = {
+        tokenName,
+        scope: binding.scope,
+        bindingId: binding.identifier,
+        kind: binding.kind,
+        slot: binding.slot,
+        [FRAME_BINDING]: binding,
+    };
+    return frame;
+}
+/**
+ * The bindings behind the resolver-built frames of a path, in path order.
+ *
+ * @since 0.11.0
+ */
+export function bindingsOf(frames) {
+    const bindings = [];
+    for (let index = 0; index < frames.length; index += 1) {
+        const binding = frames[index][FRAME_BINDING];
+        if (binding !== undefined) {
+            bindings.push(binding);
+        }
+    }
+    return bindings;
+}
 /**
  * The token names along a stack plus the frame that closed the cycle — built only to throw.
  *
@@ -23,47 +51,70 @@ export function cycleNamesOf(resolutionStack, closingName) {
     return names;
 }
 /**
- * Marks a level as in-flight on this stack, throwing if its binding is already an ancestor.
+ * Marks a level in flight on a synchronous path and pushes its frame, throwing if its binding already is.
  *
- * @remarks The check keys on binding identity — two distinct tokens may share a display name — and
- * the names an error prints are derived from the frames at the throw site. Unmark by popping the
- * stack plus `set?.delete(frame.bindingId)`. Sync only — the async lane never removes an entry, so
- * it extends a branch instead; see {@link extendResolutionBranch}.
+ * @remarks Synchronous code does not interleave, so the flag on the binding is exact membership in the
+ * path one call stack is resolving — at any depth, with no side table and nothing to size. The check
+ * keys on the binding, never on a token's display name, and the names an error prints are read off
+ * the frames at the throw site. Unmark with {@link leaveSyncPath}. Sync only: the async branch lane
+ * never unwinds, so it extends a branch instead; see {@link extendResolutionBranch}.
  *
- * @returns the membership set once the stack is deep enough to carry one, else `undefined`.
- *
- * @since 0.5.0-canary.7
+ * @since 0.11.0
  */
-export function enterResolutionPath(resolutionStack, frame) {
-    const stackWithSet = resolutionStack;
-    let resolutionSet = stackWithSet[RESOLUTION_SET_KEY];
-    // A live set mirrors the stack exactly, so a size that disagrees means it is holding ids of
-    // frames that unwound: the ones already on the stack when it attached were handed no set to
-    // delete from. Dropped rather than repaired, because the next deep frame rebuilds it.
-    if (resolutionSet !== undefined && resolutionSet.size !== resolutionStack.length) {
-        resolutionSet = undefined;
-        stackWithSet[RESOLUTION_SET_KEY] = undefined;
+export function enterSyncPath(resolutionStack, binding, frame) {
+    if (binding.inFlight) {
+        throw new CircularDependencyError(cycleNamesOf(resolutionStack, frame.tokenName));
     }
-    if (resolutionSet === undefined && resolutionStack.length >= RESOLUTION_SET_THRESHOLD) {
-        resolutionSet = new Set();
-        for (let index = 0; index < resolutionStack.length; index += 1) {
-            resolutionSet.add(resolutionStack[index].bindingId);
+    binding.inFlight = true;
+    resolutionStack.push(frame);
+}
+/**
+ * Pops the level {@link enterSyncPath} pushed and clears its binding's flag.
+ *
+ * @since 0.11.0
+ */
+export function leaveSyncPath(resolutionStack, binding) {
+    resolutionStack.pop();
+    binding.inFlight = false;
+}
+/**
+ * Marks every binding of a seeded path in flight for the synchronous call about to run over it.
+ *
+ * @remarks A seed is a path no synchronous frame pushed — a plan's static ancestors handed to an
+ * escape, or an async level's branch handed to a factory's synchronous call — so its bindings carry no
+ * flag, and marking them is what keeps the flag the one check. A binding already in flight was
+ * flagged by an enclosing synchronous frame that is still running, which is the same fact stated
+ * once already, so it is left as it is and left alone on the way out; a cycle is reported where the
+ * path re-enters that binding, which is where the frames to name it are.
+ *
+ * @returns the bindings this call left flagged as it found them, when there were any, for {@link leaveSeededPath}
+ *
+ * @since 0.11.0
+ */
+export function enterSeededPath(bindings) {
+    let alreadyInFlight;
+    for (let index = 0; index < bindings.length; index += 1) {
+        const binding = bindings[index];
+        if (binding.inFlight) {
+            (alreadyInFlight ??= new Set()).add(binding);
+            continue;
         }
-        stackWithSet[RESOLUTION_SET_KEY] = resolutionSet;
+        binding.inFlight = true;
     }
-    if (resolutionSet === undefined) {
-        for (let index = 0; index < resolutionStack.length; index += 1) {
-            if (resolutionStack[index].bindingId === frame.bindingId) {
-                throw new CircularDependencyError(cycleNamesOf(resolutionStack, frame.tokenName));
-            }
+    return alreadyInFlight;
+}
+/**
+ * Clears the flags {@link enterSeededPath} set, leaving the ones it found already set.
+ *
+ * @since 0.11.0
+ */
+export function leaveSeededPath(bindings, alreadyInFlight) {
+    for (let index = 0; index < bindings.length; index += 1) {
+        const binding = bindings[index];
+        if (alreadyInFlight === undefined || !alreadyInFlight.has(binding)) {
+            binding.inFlight = false;
         }
     }
-    else if (resolutionSet.has(frame.bindingId)) {
-        throw new CircularDependencyError(cycleNamesOf(resolutionStack, frame.tokenName));
-    }
-    resolutionStack.push(frame);
-    resolutionSet?.add(frame.bindingId);
-    return resolutionSet;
 }
 /**
  * A stack no async branch owns yet, so its first extension must copy rather than append.

package/dist/resolution/plan/instantiation-plan.d.ts

@@ -4,11 +4,11 @@
  * @remarks A dependency the compiler cannot inline escapes to a resolver callback instead; the
  * closure must stay callable for it, which is what bounds what may be inlined.
  */
-import type { Binding } from "#/core/binding";
-import type { ConstructorInvocation } from "#/core/constructor-type";
-import type { Token } from "#/core/token";
-import type { Constructor, ResolutionFrame, ResolveOptions } from "#/core/types";
-import type { ConstructorMetadata } from "#/metadata/metadata-types";
+import type { Binding } from "#core/binding";
+import type { ConstructorInvocation } from "#core/constructor-type";
+import type { Token } from "#core/token";
+import type { Constructor, ResolutionFrame, ResolveOptions } from "#core/types";
+import type { ConstructorMetadata } from "#metadata/metadata-types";
 /**
  * Compilation asked to retry later (class lifecycle metadata not discovered yet).
  *