@codefast/di 0.10.1 → 0.12.0

package/dist/resolution/cache/{binding-lookup-cache.js → lookup.js}

@@ -1,12 +1,5 @@
 import { getOrInsertComputed } from "#core/map-upsert";
 import { stateEpoch } from "#core/state-epoch";
-/**
- * Alias folding gives up past this many hops and defers to the full resolve loop, whose
- * Set-based traversal detects genuine cycles exactly rather than by an arbitrary cap.
- *
- * @since 0.5.0-canary.8
- */
-export const ALIAS_HOP_LIMIT = 32;
 const newTagToEntryMap = () => new Map();
 const newNameToTagMap = () => new Map();
 /**
@@ -36,9 +29,9 @@ export class BindingLookupCache {
     #lastTagToken;
     #lastTag;
     #lastTaggedEntry = null;
-    // Root-level collections by token, stamped with the chain version like the two memos above.
+    // Root-level collections, stamped with the chain version like the memos above. Deferred into one object,
+    // because every per-request child builds this cache and almost none reads a collection at the root.
     #collections;
-    #collectionsVersion = -1;
     #registry;
     #owner;
     #parent;
@@ -76,15 +69,19 @@ export class BindingLookupCache {
     }
     /** `null` when the token's shape needs the full selection path. */
     defaultEntry(token) {
+        // The repeat hit is the whole method, small enough for a hot caller to inline; the fill is the miss.
+        if (token === this.#lastToken && this.chainVersion() === this.#version) {
+            return this.#lastEntry;
+        }
+        return this.#defaultEntryMiss(token);
+    }
+    #defaultEntryMiss(token) {
         const version = this.chainVersion();
         if (version !== this.#version) {
             this.#byToken?.clear();
             this.#version = version;
             this.#lastToken = undefined;
         }
-        else if (token === this.#lastToken) {
-            return this.#lastEntry;
-        }
         let entry;
         if (this.#lastToken === undefined) {
             // First token this cache generation sees: answer from the walk and defer the map entirely.
@@ -159,7 +156,12 @@ export class BindingLookupCache {
     #findPairInChain(token, nameCriterion, tag) {
         const found = this.#registry.getPairTagged(token, nameCriterion, tag);
         if (found !== undefined) {
-            return found.predicate !== undefined || found.kind === "alias" ? null : { binding: found, owner: this.#owner };
+            // A predicate candidate at this level can win the more-specific rule's first step, which this
+            // lane cannot weigh; an alias carries options through the full path. Either declines to selection.
+            if (found.kind === "alias" || this.#registry.hasPredicateCandidate(token)) {
+                return null;
+            }
+            return { binding: found, owner: this.#owner };
         }
         if (this.#registry.has(token)) {
             return null;
@@ -169,30 +171,73 @@ export class BindingLookupCache {
     /** The memoized root-level collection for a token, or `undefined` once the chain changed since it was stored. */
     collection(token) {
         const version = this.chainVersion();
-        if (version !== this.#collectionsVersion) {
-            this.#collections?.clear();
-            this.#collectionsVersion = version;
+        const memo = this.#collections;
+        if (memo === undefined) {
+            this.#collections = { version, lastToken: undefined, lastEntry: undefined, byToken: undefined };
             return undefined;
         }
-        return this.#collections?.get(token);
+        if (version !== memo.version) {
+            memo.version = version;
+            memo.byToken?.clear();
+            // The rebuild that follows can throw, so the entry in front must not outlive the generation.
+            memo.lastToken = undefined;
+            return undefined;
+        }
+        if (token === memo.lastToken) {
+            return memo.lastEntry;
+        }
+        const entry = memo.byToken?.get(token);
+        if (entry !== undefined) {
+            memo.lastToken = token;
+            memo.lastEntry = entry;
+        }
+        return entry;
     }
-    /** Stores a root-level collection under the chain version the last `collection()` read stamped. */
+    /**
+     * Stores a root-level collection under the chain version the last `collection()` read stamped, so a
+     * predicate that binds during the gather leaves the entry stale rather than current.
+     */
     rememberCollection(token, entry) {
-        (this.#collections ??= new Map()).set(token, entry);
+        const memo = this.#collections;
+        if (memo === undefined) {
+            return;
+        }
+        if (memo.byToken !== undefined) {
+            memo.byToken.set(token, entry);
+        }
+        else if (memo.lastToken !== undefined && memo.lastEntry !== undefined) {
+            memo.byToken = new Map([
+                [memo.lastToken, memo.lastEntry],
+                [token, entry],
+            ]);
+        }
+        memo.lastToken = token;
+        memo.lastEntry = entry;
     }
+    /**
+     * Follows alias hops to the terminal entry, or declines with `null` on a cycle, which the full
+     * resolve loop reports.
+     *
+     * @remarks The origin and the current token are compared by hand and the set holds only what lies
+     * between them, so the common one-hop alias allocates nothing and any chain is folded exactly.
+     */
     #foldAliases(token) {
         let current = token;
-        for (let hop = 0; hop < ALIAS_HOP_LIMIT; hop += 1) {
+        let visited;
+        for (;;) {
             const entry = this.#findDefaultInChain(current);
-            if (entry === null) {
+            if (entry === null || entry.binding.kind !== "alias") {
+                return entry;
+            }
+            const next = entry.binding.target;
+            if (next === token || next === current || visited?.has(next) === true) {
                 return null;
             }
-            if (entry.binding.kind !== "alias") {
-                return entry;
+            if (current !== token) {
+                (visited ??= new Set()).add(current);
             }
-            current = entry.binding.target;
+            current = next;
         }
-        return null;
     }
     #findDefaultInChain(token) {
         const fast = this.#registry.getFastDefault(token);

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 { ConstraintContext, Constructor, ResolutionFrame, ResolutionContext, ResolveOptions } from "#core/types";
+import type { BranchDepth, OwnedBranchStack } from "#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";
 /**
  * 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.d.ts

@@ -0,0 +1,128 @@
+import type { Binding } from "#core/binding";
+import type { ResolutionFrame } from "#core/types";
+/**
+ * Creates the resolution-stack frame for one in-flight resolve of a binding.
+ *
+ * @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.3.16-canary.0
+ */
+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.
+ *
+ * @since 0.6.0
+ */
+export declare function cycleNamesOf(resolutionStack: ReadonlyArray<ResolutionFrame>, closingName: string): Array<string>;
+/**
+ * Marks a level in flight on a synchronous path and pushes its frame, throwing if its binding already is.
+ *
+ * @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}.
+ *
+ * @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.11.0
+ */
+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.
+ *
+ * @remarks Only {@link extendResolutionBranch} mints one. That is what makes "may this lane append
+ * to this array" a question the compiler answers instead of a rule in a doc — a sync frame's stack,
+ * which that frame will pop, is a plain `Array<ResolutionFrame>` and cannot reach a level that owns
+ * its own.
+ *
+ * @since 0.5.0-canary.9
+ */
+export type OwnedBranchStack = Array<ResolutionFrame> & {
+    readonly [BRANCH_BRAND]: true;
+};
+declare const BRANCH_DEPTH_BRAND: unique symbol;
+/**
+ * How many leading entries of a stack belong to one async branch.
+ *
+ * @remarks Branded so a bare number cannot be passed: a depth from anywhere but this branch silently
+ * re-parents a level.
+ *
+ * @since 0.5.0-canary.9
+ */
+export type OwnedBranchDepth = number & {
+    readonly [BRANCH_DEPTH_BRAND]: true;
+};
+/**
+ * A stack no async branch owns yet, so its first extension must copy rather than append.
+ *
+ * @since 0.5.0-canary.9
+ */
+export declare const UNOWNED_BRANCH = -1;
+/**
+ * How far into a stack one extension may reach: this branch's own depth, or nobody's.
+ *
+ * @remarks A union rather than a sentinel hidden inside the branded number, so the two cases are
+ * visible at every signature that takes one and `=== UNOWNED_BRANCH` narrows to the owned case.
+ *
+ * @since 0.5.0-canary.9
+ */
+export type BranchDepth = OwnedBranchDepth | typeof UNOWNED_BRANCH;
+/**
+ * The depth a chain's first level extends from, over an array its caller just minted.
+ *
+ * @since 0.5.0-canary.9
+ */
+export declare const ROOT_BRANCH: OwnedBranchDepth;
+/**
+ * A branch's own depth: the length its stack had when this level took it.
+ *
+ * @since 0.5.0-canary.9
+ */
+export declare function branchDepthOf(branch: OwnedBranchStack): OwnedBranchDepth;
+/**
+ * Extends one branch of an append-only stack, throwing if the binding is already an ancestor.
+ *
+ * @remarks The check compares binding ids on the frames; the names an error prints are derived at
+ * the throw site. Appends in place while this branch still owns the next slot, and copies its own
+ * prefix once a sibling has claimed it. Nothing is ever removed, so no async level has to observe
+ * its own settlement to unwind.
+ *
+ * @since 0.5.0-canary.9
+ */
+export declare function extendResolutionBranch(resolutionStack: Array<ResolutionFrame>, branchDepth: BranchDepth, frame: ResolutionFrame): OwnedBranchStack;
+export {};

package/dist/resolution/path.js

@@ -0,0 +1,167 @@
+/** Cycle-detection bookkeeping carried on the resolution stack itself. */
+import { CircularDependencyError } from "#errors";
+/** The key under which a resolver-built frame carries its binding, for marking a seeded path. */
+const FRAME_BINDING = Symbol("di:frame-binding");
+/**
+ * Creates the resolution-stack frame for one in-flight resolve of a binding.
+ *
+ * @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.3.16-canary.0
+ */
+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.
+ *
+ * @since 0.6.0
+ */
+export function cycleNamesOf(resolutionStack, closingName) {
+    const names = new Array(resolutionStack.length + 1);
+    for (let index = 0; index < resolutionStack.length; index += 1) {
+        names[index] = resolutionStack[index].tokenName;
+    }
+    names[resolutionStack.length] = closingName;
+    return names;
+}
+/**
+ * Marks a level in flight on a synchronous path and pushes its frame, throwing if its binding already is.
+ *
+ * @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}.
+ *
+ * @since 0.11.0
+ */
+export function enterSyncPath(resolutionStack, binding, frame) {
+    if (binding.inFlight) {
+        throw new CircularDependencyError(cycleNamesOf(resolutionStack, frame.tokenName));
+    }
+    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;
+        }
+        binding.inFlight = true;
+    }
+    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;
+        }
+    }
+}
+/**
+ * A stack no async branch owns yet, so its first extension must copy rather than append.
+ *
+ * @since 0.5.0-canary.9
+ */
+export const UNOWNED_BRANCH = -1;
+/**
+ * The depth a chain's first level extends from, over an array its caller just minted.
+ *
+ * @since 0.5.0-canary.9
+ */
+export const ROOT_BRANCH = 0;
+/**
+ * A branch's own depth: the length its stack had when this level took it.
+ *
+ * @since 0.5.0-canary.9
+ */
+export function branchDepthOf(branch) {
+    return branch.length;
+}
+/**
+ * Extends one branch of an append-only stack, throwing if the binding is already an ancestor.
+ *
+ * @remarks The check compares binding ids on the frames; the names an error prints are derived at
+ * the throw site. Appends in place while this branch still owns the next slot, and copies its own
+ * prefix once a sibling has claimed it. Nothing is ever removed, so no async level has to observe
+ * its own settlement to unwind.
+ *
+ * @since 0.5.0-canary.9
+ */
+export function extendResolutionBranch(resolutionStack, branchDepth, frame) {
+    const depth = branchDepth === UNOWNED_BRANCH ? resolutionStack.length : branchDepth;
+    for (let index = 0; index < depth; index += 1) {
+        if (resolutionStack[index].bindingId === frame.bindingId) {
+            throw new CircularDependencyError(cycleNamesOf(resolutionStack.slice(0, depth), frame.tokenName));
+        }
+    }
+    // An unowned array belongs to a sync frame that will pop it, or carries a membership Set this
+    // lane cannot keep true; copying is what makes the branch's own appends safe.
+    if (branchDepth === resolutionStack.length) {
+        // The sole mint: appending in place needs a depth that came from a branch already owned, or
+        // ROOT_BRANCH over an array its caller minted for this chain alone.
+        resolutionStack.push(frame);
+        return resolutionStack;
+    }
+    const branch = resolutionStack.slice(0, depth);
+    branch.push(frame);
+    return branch;
+}