@codefast/di 0.5.0 → 0.6.1

package/src/resolution/{environment.ts → context.ts}

@@ -1,7 +1,5 @@
-import type { Container } from "#/container/container";
-import type { BranchDepth, OwnedBranchPath, OwnedBranchStack } from "#/resolution/resolution-path";
-import { UNOWNED_BRANCH } from "#/resolution/resolution-path";
-import type { Token } from "#/token";
+/** The `ResolutionContext` a factory is handed, and the callbacks the resolver answers it with. */
+import type { Token } from "#/core/token";
 import type {
   BindingIdentifier,
   BindingKind,
@@ -11,85 +9,52 @@ import type {
   ResolutionFrame,
   ResolutionContext,
   ResolveOptions,
-} from "#/types";
+} from "#/core/types";
+import type { BranchDepth, OwnedBranchStack } from "#/resolution/path/resolution-path";
+import { UNOWNED_BRANCH } from "#/resolution/path/resolution-path";
 
-// ── Active container ──────────────────────────────────────────────────────────
-
-let activeContainer: Container | undefined;
-
-/**
- * @since 0.3.16-canary.0
- */
-export function runWithContainer<Result>(container: Container, fn: () => Result): Result {
-  const prev = activeContainer;
-  activeContainer = container;
-  try {
-    return fn();
-  } finally {
-    activeContainer = prev;
-  }
-}
-
-/**
- * @since 0.3.16-canary.0
- */
-export function getActiveContainer(): Container | undefined {
-  return activeContainer;
-}
-
-// ── ResolutionContext implementation ──────────────────────────────────────────
+// ── ResolutionContext implementation ─────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
  */
 export interface ResolverCallbacks {
-  resolveFromContext<const Value>(
-    token: Token<Value> | Constructor<Value>,
-    resolutionPath: Array<string>,
-    resolutionStack: Array<ResolutionFrame>,
-  ): Value;
-  resolve<const Value>(
+  resolveFromContext<Value>(token: Token<Value> | Constructor<Value>, resolutionStack: Array<ResolutionFrame>): Value;
+  resolve<Value>(
     token: Token<Value> | Constructor<Value>,
     options: ResolveOptions | undefined,
-    resolutionPath: Array<string>,
     resolutionStack: Array<ResolutionFrame>,
   ): Value;
-  resolveAsyncFromContext<const Value>(
+  resolveAsyncFromContext<Value>(
     token: Token<Value> | Constructor<Value>,
-    resolutionPath: Array<string>,
     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<const Value>(
+  resolveAsync<Value>(
     token: Token<Value> | Constructor<Value>,
     options: ResolveOptions | undefined,
-    resolutionPath: Array<string>,
     resolutionStack: Array<ResolutionFrame>,
   ): Promise<Value>;
-  resolveOptional<const Value>(
+  resolveOptional<Value>(
     token: Token<Value> | Constructor<Value>,
     options: ResolveOptions | undefined,
-    resolutionPath: Array<string>,
     resolutionStack: Array<ResolutionFrame>,
   ): Value | undefined;
-  resolveOptionalAsync<const Value>(
+  resolveOptionalAsync<Value>(
     token: Token<Value> | Constructor<Value>,
     options: ResolveOptions | undefined,
-    resolutionPath: Array<string>,
     resolutionStack: Array<ResolutionFrame>,
   ): Promise<Value | undefined>;
-  resolveAll<const Value>(
+  resolveAll<Value>(
     token: Token<Value> | Constructor<Value>,
     options: ResolveOptions | undefined,
-    resolutionPath: Array<string>,
     resolutionStack: Array<ResolutionFrame>,
   ): Array<Value>;
-  resolveAllAsync<const Value>(
+  resolveAllAsync<Value>(
     token: Token<Value> | Constructor<Value>,
     options: ResolveOptions | undefined,
-    resolutionPath: Array<string>,
     resolutionStack: Array<ResolutionFrame>,
   ): Promise<Array<Value>>;
 }
@@ -99,18 +64,15 @@ export interface ResolverCallbacks {
  */
 export class DefaultResolutionContext implements ResolutionContext {
   #resolver: ResolverCallbacks;
-  #resolutionPath: Array<string>;
   #resolutionStack: Array<ResolutionFrame>;
   #currentOptions: ResolveOptions | undefined;
 
   constructor(
     resolver: ResolverCallbacks,
-    resolutionPath: Array<string>,
     resolutionStack: Array<ResolutionFrame>,
     currentOptions: ResolveOptions | undefined,
   ) {
     this.#resolver = resolver;
-    this.#resolutionPath = resolutionPath;
     this.#resolutionStack = resolutionStack;
     this.#currentOptions = currentOptions;
   }
@@ -119,25 +81,21 @@ export class DefaultResolutionContext implements ResolutionContext {
 
   get graph(): ConstraintContext {
     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: ResolverCallbacks,
-    resolutionPath: Array<string>,
     resolutionStack: Array<ResolutionFrame>,
     currentOptions: ResolveOptions | undefined,
   ): void {
     // 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;
     }
@@ -147,221 +105,202 @@ export class DefaultResolutionContext implements ResolutionContext {
     }
   }
 
-  resolve<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
+  resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
     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<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
+  resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
     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<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined {
-    return this.#resolver.resolveOptional(token, options, this.#resolutionPath, this.#resolutionStack);
+  resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined {
+    return this.#resolver.resolveOptional(token, options, this.#resolutionStack);
   }
 
-  resolveOptionalAsync<const Value>(
+  resolveOptionalAsync<Value>(
     token: Token<Value> | Constructor<Value>,
     options?: ResolveOptions,
   ): Promise<Value | undefined> {
-    return this.#resolver.resolveOptionalAsync(token, options, this.#resolutionPath, this.#resolutionStack);
+    return this.#resolver.resolveOptionalAsync(token, options, this.#resolutionStack);
   }
 
-  resolveAll<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value> {
-    return this.#resolver.resolveAll(token, options, this.#resolutionPath, this.#resolutionStack);
+  resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value> {
+    return this.#resolver.resolveAll(token, options, this.#resolutionStack);
   }
 
-  resolveAllAsync<const Value>(
-    token: Token<Value> | Constructor<Value>,
-    options?: ResolveOptions,
-  ): Promise<Array<Value>> {
-    return this.#resolver.resolveAllAsync(token, options, this.#resolutionPath, this.#resolutionStack);
+  resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>> {
+    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 implements ResolutionContext {
   readonly #resolver: ResolverCallbacks;
-  readonly #resolutionPath: OwnedBranchPath;
   readonly #resolutionStack: OwnedBranchStack;
   readonly #currentOptions: ResolveOptions | undefined;
   readonly #branchDepth: 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: ResolverCallbacks,
-    resolutionPath: OwnedBranchPath,
     resolutionStack: OwnedBranchStack,
     currentOptions: ResolveOptions | undefined,
   ) {
     this.#resolver = resolver;
-    this.#resolutionPath = resolutionPath;
     this.#resolutionStack = resolutionStack;
     this.#currentOptions = currentOptions;
-    this.#branchDepth = resolutionPath.length as BranchDepth;
+    this.#branchDepth = resolutionStack.length as BranchDepth;
   }
 
   #graph: ConstraintContext | undefined;
-  #exactPathCache: Array<string> | undefined;
   #exactStackCache: Array<ResolutionFrame> | undefined;
 
   get graph(): ConstraintContext {
     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(): Array<string> {
-    return (this.#exactPathCache ??= this.#resolutionPath.slice(0, this.#branchDepth));
-  }
-
   #exactStack(): Array<ResolutionFrame> {
     return (this.#exactStackCache ??= this.#resolutionStack.slice(0, this.#branchDepth));
   }
 
-  resolve<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
+  resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
     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<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
+  resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
     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<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined {
-    return this.#resolver.resolveOptional(token, options, this.#exactPath(), this.#exactStack());
+  resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined {
+    return this.#resolver.resolveOptional(token, options, this.#exactStack());
   }
 
-  resolveOptionalAsync<const Value>(
+  resolveOptionalAsync<Value>(
     token: Token<Value> | Constructor<Value>,
     options?: ResolveOptions,
   ): Promise<Value | undefined> {
-    return this.#resolver.resolveOptionalAsync(token, options, this.#exactPath(), this.#exactStack());
+    return this.#resolver.resolveOptionalAsync(token, options, this.#exactStack());
   }
 
-  resolveAll<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value> {
-    return this.#resolver.resolveAll(token, options, this.#exactPath(), this.#exactStack());
+  resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value> {
+    return this.#resolver.resolveAll(token, options, this.#exactStack());
   }
 
-  resolveAllAsync<const Value>(
-    token: Token<Value> | Constructor<Value>,
-    options?: ResolveOptions,
-  ): Promise<Array<Value>> {
-    return this.#resolver.resolveAllAsync(token, options, this.#exactPath(), this.#exactStack());
+  resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>> {
+    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 implements ResolutionContext {
   readonly #resolver: ResolverCallbacks;
-  readonly #cascadePath: Array<string>;
   readonly #cascadeStack: Array<ResolutionFrame>;
 
-  constructor(resolver: ResolverCallbacks, cascadePath: Array<string>, cascadeStack: Array<ResolutionFrame>) {
+  constructor(resolver: ResolverCallbacks, cascadeStack: Array<ResolutionFrame>) {
     this.#resolver = resolver;
-    this.#cascadePath = cascadePath;
     this.#cascadeStack = cascadeStack;
   }
 
   get graph(): ConstraintContext {
     // 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<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
+  resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
     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<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
+  resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
     if (options === undefined) {
       return this.#resolver.resolveAsyncFromCascade(token) as Promise<Value>;
     }
-    return this.#resolver.resolveAsync(token, options, [...this.#cascadePath], [...this.#cascadeStack]);
+    return this.#resolver.resolveAsync(token, options, [...this.#cascadeStack]);
   }
 
-  resolveOptional<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined {
-    return this.#resolver.resolveOptional(token, options, this.#cascadePath, this.#cascadeStack);
+  resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined {
+    return this.#resolver.resolveOptional(token, options, this.#cascadeStack);
   }
 
-  resolveOptionalAsync<const Value>(
+  resolveOptionalAsync<Value>(
     token: Token<Value> | Constructor<Value>,
     options?: ResolveOptions,
   ): Promise<Value | undefined> {
-    return this.#resolver.resolveOptionalAsync(token, options, [...this.#cascadePath], [...this.#cascadeStack]);
+    return this.#resolver.resolveOptionalAsync(token, options, [...this.#cascadeStack]);
   }
 
-  resolveAll<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value> {
-    return this.#resolver.resolveAll(token, options, this.#cascadePath, this.#cascadeStack);
+  resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value> {
+    return this.#resolver.resolveAll(token, options, this.#cascadeStack);
   }
 
-  resolveAllAsync<const Value>(
-    token: Token<Value> | Constructor<Value>,
-    options?: ResolveOptions,
-  ): Promise<Array<Value>> {
-    return this.#resolver.resolveAllAsync(token, options, [...this.#cascadePath], [...this.#cascadeStack]);
+  resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>> {
+    return this.#resolver.resolveAllAsync(token, options, [...this.#cascadeStack]);
   }
 }
 
 class DefaultConstraintContext implements ConstraintContext {
-  readonly resolutionPath: ReadonlyArray<string>;
   readonly resolutionStack: ReadonlyArray<ResolutionFrame>;
   readonly parent: ResolutionFrame | undefined;
-  readonly currentResolveOptions: ResolveOptions | undefined;
+  readonly currentResolveOptions: Readonly<ResolveOptions> | undefined;
 
-  constructor(
-    resolutionPath: ReadonlyArray<string>,
-    resolutionStack: ReadonlyArray<ResolutionFrame>,
-    currentResolveOptions: ResolveOptions | undefined,
-  ) {
-    this.resolutionPath = resolutionPath;
+  constructor(resolutionStack: ReadonlyArray<ResolutionFrame>, currentResolveOptions: ResolveOptions | undefined) {
     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(): ReadonlyArray<string> {
+    const names = new Array<string>(this.resolutionStack.length);
+    for (let index = 0; index < this.resolutionStack.length; index += 1) {
+      names[index] = this.resolutionStack[index]!.tokenName;
+    }
+    return names;
+  }
+
   #ancestors: ReadonlyArray<ResolutionFrame> | undefined;
 
   get ancestors(): ReadonlyArray<ResolutionFrame> {
@@ -380,7 +319,7 @@ export function buildResolutionFrame(
   scope: BindingScope,
   bindingId: BindingIdentifier,
   kind: BindingKind,
-  slot: { name: string | undefined; tags: ReadonlyArray<readonly [string, unknown]> },
+  slot: ResolutionFrame["slot"],
 ): ResolutionFrame {
   return { tokenName, scope, bindingId, kind, slot };
 }

package/src/resolution/path/resolution-path.ts

@@ -0,0 +1,167 @@
+import type { BindingIdentifier, ResolutionFrame } from "#/core/types";
+/** Cycle-detection bookkeeping carried on the resolution stack itself. */
+import { CircularDependencyError } from "#/errors/errors";
+
+const RESOLUTION_SET_KEY: unique symbol = 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;
+type ResolutionStackWithSet = Array<ResolutionFrame> & { [RESOLUTION_SET_KEY]?: Set<BindingIdentifier> | undefined };
+
+/**
+ * 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: ReadonlyArray<ResolutionFrame>, closingName: string): Array<string> {
+  const names = new Array<string>(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: Array<ResolutionFrame>,
+  frame: ResolutionFrame,
+): Set<BindingIdentifier> | undefined {
+  const stackWithSet = resolutionStack as ResolutionStackWithSet;
+  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<BindingIdentifier>();
+    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;
+}
+
+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 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 const ROOT_BRANCH = 0 as OwnedBranchDepth;
+
+/**
+ * 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: OwnedBranchStack): OwnedBranchDepth {
+  return branch.length as 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 function extendResolutionBranch(
+  resolutionStack: Array<ResolutionFrame>,
+  branchDepth: BranchDepth,
+  frame: ResolutionFrame,
+): OwnedBranchStack {
+  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 as OwnedBranchStack;
+  }
+  const branch = resolutionStack.slice(0, depth);
+  branch.push(frame);
+  return branch as OwnedBranchStack;
+}