@lenne.tech/cli 1.43.0 → 1.45.0

package/build/lib/hoist-workspace-pnpm-config.js

@@ -323,6 +323,15 @@ function hoistWorkspacePnpmConfig(options) {
     // the root's wording wins — it is the file a maintainer of THIS workspace edits.
     const comments = extractKeyComments((_b = filesystem.read(rootWsPath)) !== null && _b !== void 0 ? _b : '');
     let rootChanged = false;
+    // Shared across all sources: who set which key, and where two disagree.
+    const provenance = new Map();
+    const conflicts = [];
+    const rootOverrides = [];
+    const auditWidenedBy = new Set();
+    // Sub-projects that are present and eligible but hand over nothing, because an
+    // earlier run already hoisted their settings and deleted the source. They are
+    // what turns a root-vs-sub override into a sub-vs-sub disagreement.
+    const dormant = [];
     for (const subDir of subProjects) {
         const subPath = `${projectDir}/${subDir}`;
         if (!filesystem.exists(subPath))
@@ -331,13 +340,31 @@ function hoistWorkspacePnpmConfig(options) {
         // checkout in link mode.
         if ((0, fs_utils_1.isSymlink)(subPath))
             continue;
-        if (hoistFromSubPackageJson({ filesystem, rootWs, subPath })) {
+        // Labelled per FILE, not per sub-project: a repo that contradicts itself
+        // across its own two config sources is the same silent-winner bug one scope
+        // down, and a shared label hides it.
+        const fromPkg = hoistFromSubPackageJson({
+            context: { auditWidenedBy, conflicts, provenance, rootOverrides, sourceLabel: `${subDir}/package.json#pnpm` },
+            filesystem,
+            rootWs,
+            subPath,
+        });
+        const fromYaml = hoistFromSubWorkspaceYaml({
+            comments,
+            context: { auditWidenedBy, conflicts, provenance, rootOverrides, sourceLabel: `${subDir}/pnpm-workspace.yaml` },
+            filesystem,
+            rootWs,
+            subPath,
+        });
+        if (fromPkg || fromYaml) {
             rootChanged = true;
         }
-        if (hoistFromSubWorkspaceYaml({ comments, filesystem, rootWs, subPath })) {
-            rootChanged = true;
+        else {
+            dormant.push(subDir);
         }
     }
+    reportRootOverridesFromDormantSiblings(rootOverrides, dormant, conflicts);
+    reportAuditConfigWidening(auditWidenedBy, conflicts);
     if (rootChanged) {
         // Keep allowBuilds (pnpm 11) and onlyBuiltDependencies (pnpm 10) in sync so
         // the build-script allowlist survives regardless of which key pnpm reads.
@@ -345,6 +372,7 @@ function hoistWorkspacePnpmConfig(options) {
         const dumped = (0, js_yaml_1.dump)(rootWs, { lineWidth: -1, sortKeys: false });
         filesystem.write(rootWsPath, annotateAuditConfig(reattachKeyComments(dumped, comments)));
     }
+    return { conflicts };
 }
 /**
  * Mark a hoisted `auditConfig` as workspace-wide, in the file itself.
@@ -368,6 +396,30 @@ function annotateAuditConfig(yaml) {
     }
     return yaml.replace(/^auditConfig:/m, `${AUDIT_CONFIG_NOTE}\nauditConfig:`);
 }
+/** `false` from either side wins — an install script nobody vouched for must not run. */
+function applyDenyWins(rootValue, subValue) {
+    const isMap = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+    if (!isMap(rootValue) || !isMap(subValue))
+        return subValue;
+    const out = Object.assign({}, subValue);
+    for (const [pkg, enabled] of Object.entries(rootValue)) {
+        if (enabled === false)
+            out[pkg] = false;
+    }
+    return out;
+}
+/**
+ * Compare the value each field's own downstream normalisation will actually use.
+ *
+ * `allowBuilds` is the case that matters: js-yaml 4 follows the YAML 1.2 core
+ * schema, so `esbuild: no` parses as the STRING `'no'` while the same intent in a
+ * `package.json#pnpm` block is the BOOLEAN `false`. `syncBuildAllowlists` narrows
+ * both to `false` (`enabled === true`), so reporting them as a disagreement sends
+ * someone hunting through two repositories over two spellings of "deny".
+ */
+function canonicaliseForCompare(field, value) {
+    return field === 'allowBuilds' ? value === true : value;
+}
 /**
  * Compare the versions of two `packageManager` pins (`pnpm@11.13.1+sha512.…`).
  * Returns >0 if `a` is newer, <0 if older, 0 if equal. Numeric segment-wise
@@ -388,15 +440,100 @@ function comparePmVersions(a, b) {
     }
     return 0;
 }
+/**
+ * Structural equality, enough for the scalar/array/object shapes these fields hold.
+ *
+ * The scalar fast path is not just a shortcut: `overrides` values are version
+ * strings and `allowBuilds` values are booleans, so it answers nearly every real
+ * comparison without allocating. The `try` guards the rest — `js-yaml` resolves
+ * recursive anchors into genuinely circular objects, on which `JSON.stringify`
+ * throws, and an exception here would abort the whole hoist (and with it
+ * `lt fullstack init`). Two values we cannot compare are reported as differing:
+ * a spurious warning is recoverable, a silent merge is the thing this exists to
+ * prevent.
+ */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * Render a value for a warning that lands in a terminal and in CI logs.
+ *
+ * `JSON.stringify` supplies the quoting and escapes every control character, so
+ * an ESC smuggled through a version spec cannot repaint the line. The redaction
+ * covers the one shape a version spec may legitimately carry a secret in: a git
+ * or tarball URL with embedded credentials (`git+https://user:token@host/…`).
+ * It only ever leaks something already committed to a sub-project manifest, but
+ * a conflict warning should not be a new place it surfaces.
+ */
+function describeValue(value) {
+    if (typeof value !== 'string') {
+        // A recursive YAML anchor resolves to a circular object, which `stringify`
+        // refuses. Naming its shape is enough for a warning, and beats aborting the
+        // scaffold over an unprintable value.
+        try {
+            return JSON.stringify(value);
+        }
+        catch (_a) {
+            return Array.isArray(value) ? '<circular list>' : '<circular value>';
+        }
+    }
+    return JSON.stringify(value
+        .replace(/\/\/[^/@\s]+:[^/@\s]+@/, '//***:***@')
+        .replace(/([?&](?:token|access_token|auth|password)=)[^&\s]+/gi, '$1***'));
+}
+/** True when an `auditConfig` block actually suppresses something (empty lists do not). */
+function hasAuditSuppressions(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    return Object.values(value).some((v) => Array.isArray(v) && v.length > 0);
+}
 /**
  * Move the workspace-scoped pnpm fields from `source` into `rootWs`,
  * deleting each moved field from `source`. Returns true if anything moved.
+ *
+ * `context` drives conflict DETECTION for the object-valued fields. The merge
+ * itself is last-writer-wins (`{...root, ...sub}`), which is correct for
+ * root-vs-sub — a sub-project owns the authoritative list for its own transitive
+ * deps — but is a trap for sub-vs-sub: two projects pinning the same package to
+ * different versions produce one silent winner, decided by iteration order.
+ * Nothing downstream can tell that apart from a deliberate choice, so it is
+ * caught here, where both values are still visible.
+ *
+ * `allowBuilds` is the one field where detection is not enough and the merge
+ * itself is corrected — see the deny-wins block below.
  */
-function hoistFields(rootWs, source) {
+function hoistFields(rootWs, source, context) {
     let changed = false;
     for (const field of WORKSPACE_SCOPED_PNPM_FIELDS) {
         if (source[field] === undefined)
             continue;
+        if (context && isObjectField(field)) {
+            recordObjectFieldProvenance(field, source[field], context);
+            recordRootOverrides(field, rootWs[field], source[field], context);
+        }
+        if (context && field === 'auditConfig' && hasAuditSuppressions(source[field])) {
+            context.auditWidenedBy.add(context.sourceLabel);
+        }
+        // A build-script allowance is the one field with a safe direction: a deny
+        // declared anywhere outranks an allow from elsewhere. Without this the
+        // last-writer-wins merge resolves the disagreement in favour of RUNNING an
+        // install script that another sub-project explicitly refused — and the
+        // warning above does not stop it. `syncBuildAllowlists` is already
+        // fail-closed across the two allowlist forms; this makes the sub-vs-sub
+        // path agree with it. No such direction exists for `overrides` (a higher
+        // version is not a safer one), so there the warning is the whole answer.
+        if (field === 'allowBuilds') {
+            source[field] = applyDenyWins(rootWs[field], source[field]);
+        }
         rootWs[field] = mergePnpmFieldValue(field, rootWs[field], source[field]);
         delete source[field];
         changed = true;
@@ -412,7 +549,7 @@ function hoistFromSubPackageJson(options) {
     const subPkg = filesystem.read(subPkgPath, 'json');
     if (!(subPkg === null || subPkg === void 0 ? void 0 : subPkg.pnpm))
         return false;
-    if (!hoistFields(rootWs, subPkg.pnpm))
+    if (!hoistFields(rootWs, subPkg.pnpm, options.context))
         return false;
     // If the sub-project's pnpm section is now empty, drop it entirely.
     if (Object.keys(subPkg.pnpm).length === 0) {
@@ -439,7 +576,7 @@ function hoistFromSubWorkspaceYaml(options) {
         if (!comments.has(key))
             comments.set(key, block);
     }
-    if (!hoistFields(rootWs, ws))
+    if (!hoistFields(rootWs, ws, options.context))
         return false;
     // A settings-only file (no `packages:`) exists solely to carry these
     // hoisted keys — once emptied it would only declare a nested workspace
@@ -453,6 +590,10 @@ function hoistFromSubWorkspaceYaml(options) {
     }
     return true;
 }
+/** True for the fields merged key-by-key, where two sub-projects can contradict each other. */
+function isObjectField(field) {
+    return OBJECT_FIELDS.includes(field);
+}
 /**
  * Merge two values for a pnpm workspace-scoped field.
  *
@@ -525,6 +666,143 @@ function readYaml(filesystem, path) {
         return null;
     return parsed;
 }
+/**
+ * Note who set each key of an object-valued field, and flag a second source
+ * setting the same key to a different value.
+ *
+ * `sourceLabel` identifies the FILE, not the sub-project, so a sub-project that
+ * contradicts itself across its own `package.json#pnpm` and its own
+ * `pnpm-workspace.yaml` is caught too. That is not a hypothetical shape — both
+ * starters ship a settings-only `pnpm-workspace.yaml`, and a stale leftover in
+ * either file otherwise downgrades a pin with no output at all.
+ */
+function recordObjectFieldProvenance(field, value, context) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return;
+    for (const [key, incoming] of Object.entries(value)) {
+        const id = `${field}.${key}`;
+        const previous = context.provenance.get(id);
+        if (previous &&
+            previous.source !== context.sourceLabel &&
+            !deepEqual(canonicaliseForCompare(field, previous.value), canonicaliseForCompare(field, incoming))) {
+            // `allowBuilds` is resolved deterministically (deny outranks allow), so
+            // saying "one of them would silently win" there would understate what
+            // already happened and leave the reader unsure which value shipped.
+            const kept = resolveKeptValue(field, previous.value, incoming);
+            const outcome = deepEqual(kept, incoming)
+                ? 'One of them would silently win.'
+                : `The workspace keeps ${describeValue(kept)}, because a denied build script outranks an allowed one.`;
+            context.conflicts.push(`${field}: ${JSON.stringify(key)} is set to ${describeValue(previous.value)} by ${previous.source} ` +
+                `and to ${describeValue(incoming)} by ${context.sourceLabel}. ` +
+                `${outcome} Agree on a single value in BOTH repos before assembling.`);
+        }
+        context.provenance.set(id, { source: context.sourceLabel, value: incoming });
+    }
+}
+/**
+ * Remember where this source changes a value the ROOT already carried.
+ *
+ * On its own that is the documented and intended precedence — the root seeds,
+ * a sub-project owns the authoritative list for its own transitive deps — so
+ * nothing is reported here. It only becomes a disagreement once the run ends
+ * with a sub-project that contributed nothing, which is what tells us the root
+ * value was itself hoisted from that sibling on an earlier run.
+ *
+ * The `kept` value is resolved here rather than described later, because for
+ * `allowBuilds` the incoming value does NOT necessarily win: `applyDenyWins`
+ * runs a few lines further down and a deny from either side outranks an allow.
+ * A message that announced the incoming value as the winner would state the
+ * opposite of what the file ends up containing.
+ */
+function recordRootOverrides(field, rootValue, subValue, context) {
+    if (!rootValue || typeof rootValue !== 'object' || Array.isArray(rootValue))
+        return;
+    if (!subValue || typeof subValue !== 'object' || Array.isArray(subValue))
+        return;
+    const rootMap = rootValue;
+    for (const [key, incoming] of Object.entries(subValue)) {
+        if (!(key in rootMap))
+            continue;
+        if (deepEqual(canonicaliseForCompare(field, rootMap[key]), canonicaliseForCompare(field, incoming)))
+            continue;
+        context.rootOverrides.push({
+            field,
+            incoming,
+            keptValue: resolveKeptValue(field, rootMap[key], incoming),
+            key,
+            rootValue: rootMap[key],
+            source: context.sourceLabel,
+        });
+    }
+}
+/**
+ * One line, not one per advisory: say that hoisting widened the audit
+ * suppressions to the whole workspace, and name who brought them.
+ *
+ * `annotateAuditConfig` already writes this into the emitted YAML, but that note
+ * reaches whoever opens `pnpm-workspace.yaml` later — not the person running
+ * `lt fullstack init` now. In a generated project the deploy-blocking audit job
+ * is the only automated vulnerability control there is, so a suppression
+ * assessed against one package's dependency tree quietly covering the other's is
+ * worth a line on screen.
+ */
+function reportAuditConfigWidening(auditWidenedBy, conflicts) {
+    if (auditWidenedBy.size === 0)
+        return;
+    conflicts.push(`auditConfig: advisory suppressions from ${[...auditWidenedBy].join(', ')} now apply to EVERY package in ` +
+        `this workspace, not just the one they were assessed against. Review them, and drop each entry once its ` +
+        `advisory is fixed.`);
+}
+/**
+ * Turn root-vs-sub overrides into conflicts when a sibling sub-project sat out
+ * the run — the incremental `add-api` → `add-app` case.
+ *
+ * Hoisting is destructive: `hoistFields` deletes each field from the source once
+ * it reaches the root. So by the time `lt fullstack add-app` runs, the api's
+ * settings are already IN the root and gone from `projects/api/package.json`.
+ * The app's differing value then looks exactly like the documented root-vs-sub
+ * precedence, and the sub-vs-sub check never sees two values. Confirmed: api
+ * pinning `better-auth` to 1.7.1 followed later by app pinning 1.7.2 yielded no
+ * conflict and a root silently on 1.7.2.
+ *
+ * A sub-project that is present but contributed nothing is the signal that this
+ * happened. It is not proof — the root value could equally be a hand-edit or the
+ * lt-monorepo template's own seed — so the message says "if", names the sibling,
+ * and asks rather than asserts. Being present and contributing everything (the
+ * `lt fullstack init` path) leaves `dormant` empty, which is why the intended
+ * root-seed precedence stays silent there.
+ */
+function reportRootOverridesFromDormantSiblings(rootOverrides, dormant, conflicts) {
+    if (rootOverrides.length === 0 || dormant.length === 0)
+        return;
+    const siblings = dormant.join(', ');
+    for (const { field, incoming, keptValue, key, rootValue, source } of rootOverrides) {
+        // Name the value the workspace actually ends up with. For `allowBuilds` that
+        // is not the incoming one — a deny outranks an allow — and announcing the
+        // wrong winner would send the reader looking for a problem that is already
+        // resolved, while hiding the one that is not.
+        const outcome = deepEqual(keptValue, incoming)
+            ? `${describeValue(incoming)}, which now wins`
+            : `${describeValue(incoming)}; the workspace keeps ${describeValue(keptValue)}, because a denied build ` +
+                `script outranks an allowed one`;
+        conflicts.push(`${field}: ${JSON.stringify(key)} was already pinned to ${describeValue(rootValue)} in this workspace, ` +
+            `and ${source} changes it to ${outcome}. ` +
+            `If the existing value came from ${siblings} — whose settings an earlier run already hoisted — ` +
+            `the two repos disagree. Agree on a single value in BOTH before assembling.`);
+    }
+}
+/**
+ * What the workspace will actually carry once this key is merged.
+ *
+ * Mirrors `applyDenyWins` for `allowBuilds` — a deny on either side is kept —
+ * and last-writer-wins for everything else. Kept next to the merge it predicts
+ * so the two cannot drift apart silently.
+ */
+function resolveKeptValue(field, rootValue, incoming) {
+    if (field === 'allowBuilds' && (rootValue === false || incoming === false))
+        return false;
+    return incoming;
+}
 /**
  * Keep the two build-allowlist forms consistent and complete after hoisting:
  * - `allowBuilds` (pnpm 11) is a `{ pkg: boolean }` map.

package/build/lib/workspace-integration.js

@@ -75,6 +75,7 @@ exports.finalizeWorkspaceRoot = finalizeWorkspaceRoot;
 exports.findWorkspaceRoot = findWorkspaceRoot;
 exports.isNonInteractive = isNonInteractive;
 exports.reconfigureUpstreamForDownstream = reconfigureUpstreamForDownstream;
+exports.reportWorkspaceConflicts = reportWorkspaceConflicts;
 exports.runExperimentalNestBaseRename = runExperimentalNestBaseRename;
 exports.runStandaloneWorkspaceGate = runStandaloneWorkspaceGate;
 exports.shouldProceedAsStandalone = shouldProceedAsStandalone;
@@ -149,15 +150,30 @@ function detectWorkspaceLayout(workspaceDir, filesystem) {
  *      sub-project's own `.dockerignore` when building from the root context).
  *
  * Each step is a no-op when there is nothing to do, so re-runs are safe.
+ *
+ * Returns what step 1 found and could not resolve on its own: keys set to
+ * different values by two different sources, audit suppressions that hoisting
+ * has just widened to the whole workspace, and — in the incremental flow — a
+ * value this run changes that an earlier run had hoisted from the other
+ * sub-project. Callers should surface all of them; a contradiction here reaches
+ * every project generated from the templates.
+ *
+ * Detection is per invocation and hoisting is destructive: a field is deleted
+ * from its source once it reaches the root. So `lt fullstack init` on a fresh
+ * directory, where both halves are still unhoisted, is the only path that sees
+ * two competing values directly. `add-api` → `add-app` is covered by the weaker
+ * "the root already pinned this, and a sibling contributed nothing" signal,
+ * which names the sibling and asks rather than asserts.
  */
 function finalizeWorkspaceRoot(options) {
     var _a;
     const { filesystem, projectDir } = options;
     const subProjects = (_a = options.subProjects) !== null && _a !== void 0 ? _a : ['projects/api', 'projects/app'];
-    (0, hoist_workspace_pnpm_config_1.hoistWorkspacePnpmConfig)({ filesystem, projectDir, subProjects });
+    const { conflicts } = (0, hoist_workspace_pnpm_config_1.hoistWorkspacePnpmConfig)({ filesystem, projectDir, subProjects });
     (0, hoist_workspace_pnpm_config_1.hoistPackageManager)({ filesystem, projectDir, subProjects });
     (0, remove_nested_lockfiles_1.removeNestedLockfiles)({ filesystem, projectDir, subProjects });
     (0, ensure_root_dockerignore_1.ensureRootDockerignore)({ filesystem, projectDir });
+    return { conflicts };
 }
 /**
  * Walk up from `startDir` until a workspace marker is found or the
@@ -264,6 +280,25 @@ function reconfigureUpstreamForDownstream(options) {
     filesystem.write(upstreamPath, next, { jsonIndent: 2 });
     return { updated: true };
 }
+/**
+ * Surface what `finalizeWorkspaceRoot` could not decide.
+ *
+ * Shared by all three fullstack scaffolders so the wording — and the fact that
+ * it is printed at all — cannot drift between them. Called TWICE per command:
+ * once where the conflict arises, and once in the closing block, because the
+ * first call lands immediately before `pnpm install` and several hundred lines
+ * of install output bury it. Nothing here changes the exit code: the workspace
+ * is still assembled, and the disagreement needs a human decision in two
+ * repositories rather than a failed scaffold.
+ *
+ * A no-op for the overwhelmingly common empty case, so callers can call it
+ * unconditionally.
+ */
+function reportWorkspaceConflicts(conflicts, warn) {
+    for (const conflict of conflicts) {
+        warn(`[workspace] ${conflict}`);
+    }
+}
 /**
  * Run the experimental `bun run rename <projectDir>` step. Only relevant
  * for the `--next` nest-base template (it ships hard-coded `nest-base`

package/build/templates/check/build-test-gate.mjs

@@ -0,0 +1,107 @@
+/**
+ * Cross-group mutual exclusion between CPU-heavy steps and contention-sensitive
+ * test suites (DEV-2524, cause 2).
+ *
+ * The root check wrapper (scripts/check.mjs) runs each workspace project's step
+ * chain concurrently by default. The api group's `test` step is the API e2e
+ * suite, whose Better-Auth session validation is sensitive to CPU contention:
+ * it tips into intermittent 401/500 the moment another group saturates the
+ * machine — most reliably the app group's `nuxt build`. Measured in DEV-2524:
+ * the same commit was red under the parallel run and green (2418/2418) under
+ * `--sequential`. This gate guarantees a heavy step and a sensitive test step
+ * never run at the same time, while:
+ *   - same-class steps may still overlap (two builds, or two test suites)
+ *     → the parallel design is preserved elsewhere;
+ *   - every other step kind (format, lint, server-start, …) never touches the
+ *     gate at all and stays fully parallel.
+ *
+ * Which steps belong to which class is `gateClass()` in check.mjs, not this
+ * file: the gate is a generic two-class lock and does not know what a "build"
+ * is. Note that the classes are named "build" and "test" only because those are
+ * the labels the caller passes; the lock treats them as two opaque, mutually
+ * exclusive classes.
+ *
+ * It is a two-class fair lock: whichever class is active admits every waiter of
+ * that class; the other class waits until the active class fully drains, then
+ * takes over as a batch. Handover is FIFO between the two classes, so neither
+ * can starve the other.
+ *
+ * Starvation-freedom is workload-bounded, not unconditional: an arriving acquire
+ * of the ACTIVE class barges ahead of an already-queued opposite-class waiter, so
+ * an unbounded stream of same-class arrivals could in theory starve the other
+ * class. That cannot happen here — the check wrapper issues FINITELY MANY gated
+ * steps per group, so the active class always drains and the queued batch is then
+ * admitted. (Do not restate this as "one test then one build per group": the root
+ * group has a `test` and no build at all, and a chain's shape is the project's to
+ * choose. Finiteness is what the argument needs, and finiteness is what holds.)
+ */
+export function createBuildTestGate() {
+  let activeClass = null; // 'test' | 'build' | null
+  let activeCount = 0;
+  const queue = []; // FIFO of { klass, resolve }
+
+  function admit(klass, resolve) {
+    activeClass = klass;
+    activeCount += 1;
+    resolve();
+  }
+
+  function acquire(klass) {
+    return new Promise((resolve) => {
+      if (activeClass === null || activeClass === klass) {
+        admit(klass, resolve);
+      } else {
+        queue.push({ klass, resolve });
+      }
+    });
+  }
+
+  function release() {
+    // Guard against an unbalanced release. Without it the counter goes negative
+    // and the lock stops excluding: with two holders and one stray release,
+    // `activeCount` reaches 0 while a holder is still running, so the opposite
+    // class is admitted alongside it — silently, and precisely when the machine
+    // is busiest. No current caller can double-release (runGroup acquires and
+    // releases exactly once per gated step), but this is shipped into every
+    // generated project and there are two release sites per acquire.
+    if (activeCount <= 0) return;
+
+    activeCount -= 1;
+    if (activeCount > 0) return;
+
+    activeClass = null;
+    if (queue.length === 0) return;
+
+    // Active class fully drained with waiters pending: hand over to the class of
+    // the oldest waiter, admitting every queued waiter of that class as a batch.
+    //
+    // Via the public API the queue only ever holds a SINGLE class at a time (a
+    // same-class acquire is admitted immediately and never queues, so only the
+    // opposite class waits while one class is active). The `carried` re-queue is
+    // therefore always empty in practice — kept as a defensive guard so the
+    // handover stays correct if the admission rule ever changes.
+    const nextClass = queue[0].klass;
+    const carried = [];
+    for (const waiter of queue) {
+      if (waiter.klass === nextClass) {
+        admit(waiter.klass, waiter.resolve);
+      } else {
+        carried.push(waiter);
+      }
+    }
+    queue.length = 0;
+    queue.push(...carried);
+  }
+
+  return {
+    acquire,
+    release,
+    // Read-only accessors, exposed for assertions / telemetry only.
+    get activeClass() {
+      return activeClass;
+    },
+    get activeCount() {
+      return activeCount;
+    },
+  };
+}