@codefast/di 0.5.0 → 0.6.0

package/dist/resolution/context.d.ts

@@ -0,0 +1,84 @@
+/** 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";
+/**
+ * @since 0.3.16-canary.0
+ */
+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>;
+    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Array<Value>;
+    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Promise<Array<Value>>;
+}
+/**
+ * @since 0.3.16-canary.0
+ */
+export declare class DefaultResolutionContext implements ResolutionContext {
+    #private;
+    constructor(resolver: ResolverCallbacks, resolutionStack: Array<ResolutionFrame>, currentOptions: ResolveOptions | undefined);
+    get graph(): ConstraintContext;
+    reset(resolver: ResolverCallbacks, resolutionStack: Array<ResolutionFrame>, currentOptions: ResolveOptions | undefined): void;
+    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): Array<Value>;
+    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>>;
+}
+/**
+ * One async level's resolution context, which is also its branch of the resolution stack.
+ *
+ * @remarks Separate from {@link DefaultResolutionContext} so the sync lane's pooled context keeps
+ * reading its stack as a plain field: only an async branch has a prefix to take, because an async
+ * level owns its branch of the stack.
+ *
+ * @since 0.5.0-canary.9
+ */
+export declare class AsyncLevelContext implements ResolutionContext {
+    #private;
+    /**
+     * @param resolver - the engine callbacks every request on this level goes through
+     * @param resolutionStack - this level's own branch; the depth is read off it rather than passed,
+     * so the two cannot disagree about where this level sits
+     * @param currentOptions - the options of the request that opened this level, if any
+     */
+    constructor(resolver: ResolverCallbacks, resolutionStack: OwnedBranchStack, currentOptions: ResolveOptions | undefined);
+    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): Array<Value>;
+    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>>;
+}
+/**
+ * The one context every level of an open synchronous factory cascade shares.
+ *
+ * @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.
+ *
+ * @since 0.5.0-canary.9
+ */
+export declare class AsyncCascadeContext implements ResolutionContext {
+    #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): Array<Value>;
+    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>>;
+}
+/**
+ * @since 0.3.16-canary.0
+ */
+export declare function buildResolutionFrame(tokenName: string, scope: BindingScope, bindingId: BindingIdentifier, kind: BindingKind, slot: ResolutionFrame["slot"]): ResolutionFrame;
+//# sourceMappingURL=context.d.ts.map

package/dist/resolution/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/resolution/context.ts"],"names":[],"mappings":"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"}

package/dist/resolution/{environment.js → context.js}

@@ -1,55 +1,29 @@
-import { UNOWNED_BRANCH } from "#/resolution/resolution-path";
-// ── Active container ──────────────────────────────────────────────────────────
-let activeContainer;
-/**
- * @since 0.3.16-canary.0
- */
-export function runWithContainer(container, fn) {
-    const prev = activeContainer;
-    activeContainer = container;
-    try {
-        return fn();
-    }
-    finally {
-        activeContainer = prev;
-    }
-}
-/**
- * @since 0.3.16-canary.0
- */
-export function getActiveContainer() {
-    return activeContainer;
-}
+import { UNOWNED_BRANCH } from "#/resolution/path/resolution-path";
 /**
  * @since 0.3.16-canary.0
  */
 export class DefaultResolutionContext {
     #resolver;
-    #resolutionPath;
     #resolutionStack;
     #currentOptions;
-    constructor(resolver, resolutionPath, resolutionStack, currentOptions) {
+    constructor(resolver, resolutionStack, currentOptions) {
         this.#resolver = resolver;
-        this.#resolutionPath = resolutionPath;
         this.#resolutionStack = resolutionStack;
         this.#currentOptions = currentOptions;
     }
     #graph;
     get graph() {
         if (this.#graph === undefined) {
-            this.#graph = new DefaultConstraintContext(this.#resolutionPath, this.#resolutionStack, this.#currentOptions);
+            this.#graph = new DefaultConstraintContext(this.#resolutionStack, this.#currentOptions);
         }
         return this.#graph;
     }
-    reset(resolver, resolutionPath, resolutionStack, currentOptions) {
+    reset(resolver, resolutionStack, currentOptions) {
         // Compared before storing: a pooled context lives long enough to be in old space, so storing a
-        // pointer costs a write barrier, and a sync resolve hands every depth the same two arrays.
+        // pointer costs a write barrier, and a sync resolve hands every depth the same stack.
         if (this.#resolver !== resolver) {
             this.#resolver = resolver;
         }
-        if (this.#resolutionPath !== resolutionPath) {
-            this.#resolutionPath = resolutionPath;
-        }
         if (this.#resolutionStack !== resolutionStack) {
             this.#resolutionStack = resolutionStack;
         }
@@ -60,158 +34,158 @@ export class DefaultResolutionContext {
     }
     resolve(token, options) {
         if (options === undefined) {
-            return this.#resolver.resolveFromContext(token, this.#resolutionPath, this.#resolutionStack);
+            return this.#resolver.resolveFromContext(token, this.#resolutionStack);
         }
-        return this.#resolver.resolve(token, options, this.#resolutionPath, this.#resolutionStack);
+        return this.#resolver.resolve(token, options, this.#resolutionStack);
     }
     resolveAsync(token, options) {
         if (options === undefined) {
             // UNOWNED_BRANCH: this frame's array is a sync stack it will pop, so the lane must copy it.
-            return this.#resolver.resolveAsyncFromContext(token, this.#resolutionPath, this.#resolutionStack, UNOWNED_BRANCH);
+            return this.#resolver.resolveAsyncFromContext(token, this.#resolutionStack, UNOWNED_BRANCH);
         }
-        return this.#resolver.resolveAsync(token, options, this.#resolutionPath, this.#resolutionStack);
+        return this.#resolver.resolveAsync(token, options, this.#resolutionStack);
     }
     resolveOptional(token, options) {
-        return this.#resolver.resolveOptional(token, options, this.#resolutionPath, this.#resolutionStack);
+        return this.#resolver.resolveOptional(token, options, this.#resolutionStack);
     }
     resolveOptionalAsync(token, options) {
-        return this.#resolver.resolveOptionalAsync(token, options, this.#resolutionPath, this.#resolutionStack);
+        return this.#resolver.resolveOptionalAsync(token, options, this.#resolutionStack);
     }
     resolveAll(token, options) {
-        return this.#resolver.resolveAll(token, options, this.#resolutionPath, this.#resolutionStack);
+        return this.#resolver.resolveAll(token, options, this.#resolutionStack);
     }
     resolveAllAsync(token, options) {
-        return this.#resolver.resolveAllAsync(token, options, this.#resolutionPath, this.#resolutionStack);
+        return this.#resolver.resolveAllAsync(token, options, this.#resolutionStack);
     }
 }
 /**
- * One async level's resolution context, which is also its branch of the resolution path.
+ * One async level's resolution context, which is also its branch of the resolution stack.
  *
  * @remarks Separate from {@link DefaultResolutionContext} so the sync lane's pooled context keeps
- * reading its arrays as plain fields: only an async branch has a prefix to take. See
- * `ARCHITECTURE.md` — an async level owns its branch of the path.
+ * reading its stack as a plain field: only an async branch has a prefix to take, because an async
+ * level owns its branch of the stack.
  *
  * @since 0.5.0-canary.9
  */
 export class AsyncLevelContext {
     #resolver;
-    #resolutionPath;
     #resolutionStack;
     #currentOptions;
     #branchDepth;
     /**
-     * @param resolutionPath - this level's own branch; the depth is read off it rather than passed,
+     * @param resolver - the engine callbacks every request on this level goes through
+     * @param resolutionStack - this level's own branch; the depth is read off it rather than passed,
      * so the two cannot disagree about where this level sits
+     * @param currentOptions - the options of the request that opened this level, if any
      */
-    constructor(resolver, resolutionPath, resolutionStack, currentOptions) {
+    constructor(resolver, resolutionStack, currentOptions) {
         this.#resolver = resolver;
-        this.#resolutionPath = resolutionPath;
         this.#resolutionStack = resolutionStack;
         this.#currentOptions = currentOptions;
-        this.#branchDepth = resolutionPath.length;
+        this.#branchDepth = resolutionStack.length;
     }
     #graph;
-    #exactPathCache;
     #exactStackCache;
     get graph() {
         if (this.#graph === undefined) {
-            this.#graph = new DefaultConstraintContext(this.#exactPath(), this.#exactStack(), this.#currentOptions);
+            this.#graph = new DefaultConstraintContext(this.#exactStack(), this.#currentOptions);
         }
         return this.#graph;
     }
-    // The path is append-only and a descendant may already have grown it past this level, so every
+    // The stack is append-only and a descendant may already have grown it past this level, so every
     // caller but the async lane is handed this branch's prefix. It is fixed for the level's lifetime.
-    #exactPath() {
-        return (this.#exactPathCache ??= this.#resolutionPath.slice(0, this.#branchDepth));
-    }
     #exactStack() {
         return (this.#exactStackCache ??= this.#resolutionStack.slice(0, this.#branchDepth));
     }
     resolve(token, options) {
         if (options === undefined) {
-            return this.#resolver.resolveFromContext(token, this.#exactPath(), this.#exactStack());
+            return this.#resolver.resolveFromContext(token, this.#exactStack());
         }
-        return this.#resolver.resolve(token, options, this.#exactPath(), this.#exactStack());
+        return this.#resolver.resolve(token, options, this.#exactStack());
     }
     resolveAsync(token, options) {
         if (options === undefined) {
             // The hot lane: the resolver reads this branch by depth, so nothing is materialized.
-            return this.#resolver.resolveAsyncFromContext(token, this.#resolutionPath, this.#resolutionStack, this.#branchDepth);
+            return this.#resolver.resolveAsyncFromContext(token, this.#resolutionStack, this.#branchDepth);
         }
-        return this.#resolver.resolveAsync(token, options, this.#exactPath(), this.#exactStack());
+        return this.#resolver.resolveAsync(token, options, this.#exactStack());
     }
     resolveOptional(token, options) {
-        return this.#resolver.resolveOptional(token, options, this.#exactPath(), this.#exactStack());
+        return this.#resolver.resolveOptional(token, options, this.#exactStack());
     }
     resolveOptionalAsync(token, options) {
-        return this.#resolver.resolveOptionalAsync(token, options, this.#exactPath(), this.#exactStack());
+        return this.#resolver.resolveOptionalAsync(token, options, this.#exactStack());
     }
     resolveAll(token, options) {
-        return this.#resolver.resolveAll(token, options, this.#exactPath(), this.#exactStack());
+        return this.#resolver.resolveAll(token, options, this.#exactStack());
     }
     resolveAllAsync(token, options) {
-        return this.#resolver.resolveAllAsync(token, options, this.#exactPath(), this.#exactStack());
+        return this.#resolver.resolveAllAsync(token, options, this.#exactStack());
     }
 }
 /**
  * The one context every level of an open synchronous factory cascade shares.
  *
- * @remarks It carries no per-level state at all: while the cascade is open, the resolver's arrays
- * *are* this level's ancestor chain, so nothing has to be allocated per level. See
- * `ARCHITECTURE.md` — the cascade lane.
+ * @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.
  *
  * @since 0.5.0-canary.9
  */
 export class AsyncCascadeContext {
     #resolver;
-    #cascadePath;
     #cascadeStack;
-    constructor(resolver, cascadePath, cascadeStack) {
+    constructor(resolver, cascadeStack) {
         this.#resolver = resolver;
-        this.#cascadePath = cascadePath;
         this.#cascadeStack = cascadeStack;
     }
     get graph() {
         // Not memoized: this context outlives every level, so a cached graph would describe whichever
-        // level asked first. The cascade arrays are only this level's ancestors while it is open.
-        return new DefaultConstraintContext(this.#cascadePath, this.#cascadeStack, undefined);
+        // 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.#cascadePath, this.#cascadeStack);
+            return this.#resolver.resolveFromContext(token, this.#cascadeStack);
         }
-        return this.#resolver.resolve(token, options, this.#cascadePath, 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.#cascadePath], [...this.#cascadeStack]);
+        return this.#resolver.resolveAsync(token, options, [...this.#cascadeStack]);
     }
     resolveOptional(token, options) {
-        return this.#resolver.resolveOptional(token, options, this.#cascadePath, this.#cascadeStack);
+        return this.#resolver.resolveOptional(token, options, this.#cascadeStack);
     }
     resolveOptionalAsync(token, options) {
-        return this.#resolver.resolveOptionalAsync(token, options, [...this.#cascadePath], [...this.#cascadeStack]);
+        return this.#resolver.resolveOptionalAsync(token, options, [...this.#cascadeStack]);
     }
     resolveAll(token, options) {
-        return this.#resolver.resolveAll(token, options, this.#cascadePath, this.#cascadeStack);
+        return this.#resolver.resolveAll(token, options, this.#cascadeStack);
     }
     resolveAllAsync(token, options) {
-        return this.#resolver.resolveAllAsync(token, options, [...this.#cascadePath], [...this.#cascadeStack]);
+        return this.#resolver.resolveAllAsync(token, options, [...this.#cascadeStack]);
     }
 }
 class DefaultConstraintContext {
-    resolutionPath;
     resolutionStack;
     parent;
     currentResolveOptions;
-    constructor(resolutionPath, resolutionStack, currentResolveOptions) {
-        this.resolutionPath = resolutionPath;
+    constructor(resolutionStack, currentResolveOptions) {
         this.resolutionStack = resolutionStack;
         this.parent = resolutionStack.at(-1);
         this.currentResolveOptions = currentResolveOptions;
     }
+    // Derived per read, never cached: the stack this context aliases may be live, and the names must
+    // report it as it stands — exactly as the dedicated name array did.
+    get resolutionPath() {
+        const names = new Array(this.resolutionStack.length);
+        for (let index = 0; index < this.resolutionStack.length; index += 1) {
+            names[index] = this.resolutionStack[index].tokenName;
+        }
+        return names;
+    }
     #ancestors;
     get ancestors() {
         if (this.#ancestors === undefined) {
@@ -226,4 +200,4 @@ class DefaultConstraintContext {
 export function buildResolutionFrame(tokenName, scope, bindingId, kind, slot) {
     return { tokenName, scope, bindingId, kind, slot };
 }
-//# sourceMappingURL=environment.js.map
+//# sourceMappingURL=context.js.map

package/dist/resolution/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/resolution/context.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,94 @@
+import type { BindingIdentifier, ResolutionFrame } from "#/core/types";
+/**
+ * Where the cycle check switches from a linear frame scan to an attached Set.
+ *
+ * @remarks Measured rather than guessed: below this depth the linear scan wins, above it the Set does.
+ *
+ * @since 0.5.0-canary.7
+ */
+export declare const RESOLUTION_SET_THRESHOLD = 32;
+/**
+ * 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 as in-flight on this stack, throwing if its binding is already an ancestor.
+ *
+ * @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}.
+ *
+ * @returns the membership set once the stack is deep enough to carry one, else `undefined`.
+ *
+ * @since 0.5.0-canary.7
+ */
+export declare function enterResolutionPath(resolutionStack: Array<ResolutionFrame>, frame: ResolutionFrame): Set<BindingIdentifier> | undefined;
+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 {};
+//# sourceMappingURL=resolution-path.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolution-path.d.ts","sourceRoot":"","sources":["../../../src/resolution/path/resolution-path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAKvE;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAG3C;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,eAAe,EAAE,aAAa,CAAC,eAAe,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAOhH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,eAAe,EAAE,KAAK,CAAC,eAAe,CAAC,EACvC,KAAK,EAAE,eAAe,GACrB,GAAG,CAAC,iBAAiB,CAAC,GAAG,SAAS,CA6BpC;AAED,OAAO,CAAC,MAAM,YAAY,EAAE,OAAO,MAAM,CAAC;AAE1C;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG,KAAK,CAAC,eAAe,CAAC,GAAG;IAAE,QAAQ,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAE1F,OAAO,CAAC,MAAM,kBAAkB,EAAE,OAAO,MAAM,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,kBAAkB,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAEhF;;;;GAIG;AACH,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG,OAAO,cAAc,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAQ,gBAAgB,CAAC;AAEjD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAExE;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,eAAe,EAAE,KAAK,CAAC,eAAe,CAAC,EACvC,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,eAAe,GACrB,gBAAgB,CAkBlB"}

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

@@ -0,0 +1,117 @@
+/** Cycle-detection bookkeeping carried on the resolution stack itself. */
+import { CircularDependencyError } from "#/errors/errors";
+const RESOLUTION_SET_KEY = Symbol("di:resolution-set");
+/**
+ * Where the cycle check switches from a linear frame scan to an attached Set.
+ *
+ * @remarks Measured rather than guessed: below this depth the linear scan wins, above it the Set does.
+ *
+ * @since 0.5.0-canary.7
+ */
+export const RESOLUTION_SET_THRESHOLD = 32;
+/**
+ * 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 as in-flight on this stack, throwing if its binding is already an ancestor.
+ *
+ * @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}.
+ *
+ * @returns the membership set once the stack is deep enough to carry one, else `undefined`.
+ *
+ * @since 0.5.0-canary.7
+ */
+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;
+    }
+    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);
+        }
+        stackWithSet[RESOLUTION_SET_KEY] = resolutionSet;
+    }
+    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));
+            }
+        }
+    }
+    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.
+ *
+ * @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;
+}
+//# sourceMappingURL=resolution-path.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolution-path.js","sourceRoot":"","sources":["../../../src/resolution/path/resolution-path.ts"],"names":[],"mappings":"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"}