@remnic/core 10.0.75 → 10.0.77

package/src/orchestration/extraction-queue-snapshot-sharing.ts

@@ -0,0 +1,257 @@
+/**
+ * Bounded-queue retention for automatic extraction snapshots (#3324
+ * follow-up).
+ *
+ * The coordinator's queue keeps every accepted task's own snapshot (that is
+ * the #3324 contract: per-entry captured scope and settlement), but nothing
+ * requires each queued snapshot to RETAIN its own turn objects. Automatic
+ * triggers hand out prefix-extended snapshots of the same buffer (the buffer
+ * clears only when extraction runs), so consecutive queued snapshots overlap
+ * almost entirely while their drain is slow. Retaining one deep copy per
+ * snapshot grows quadratic overhead (demonstrated: scaling exponent 1.89 on
+ * main, 36× the unique content at 1000 turns for one session).
+ *
+ * This registry makes the OVERLAP shared without changing ANY task's
+ * semantics: a queued snapshot is stored as a chain node
+ * `{ base, tail }` whose turns are verified element-wise equivalent to the
+ * base chain at admit time. Each task materializes its own fresh array at
+ * run time — identical values, same windows, same chunking, same clear
+ * matching, same settlements. Sharing is data-structure only.
+ *
+ * Safety properties:
+ * - Equivalence is CONSUMER-equivalence, not `bufferTurnsEqual` alone: the
+ *   five fields `bufferTurnsEqual` ignores (extractionContextOnly, parts,
+ *   rawContent, sourceFormat, importProvenance) are compared strictly
+ *   (objects by reference identity), so an aliased segment is
+ *   indistinguishable from a private copy to every downstream reader.
+ * - Turn objects are immutable by audit: no code path writes a BufferTurn
+ *   field or a parts array in place (all writes go to freshly constructed
+ *   objects: `copyBufferTurn`, the replay `pinned` spread). Audited across
+ *   the extraction call graph.
+ * - Distinct scope pins can never share: pins are turn fields covered by
+ *   `bufferTurnsEqual`, and the scope-class bucket is a lookup heuristic
+ *   only — a wrong pairing fails the element-wise check and simply does not
+ *   share.
+ * - Replay, bulk import, force flush, fail-closed callers, and claim-backed
+ *   execution contexts are excluded (they are not automatic snapshots of the
+ *   live buffer).
+ */
+
+import type { BufferTurn } from "../types.js";
+import { bufferTurnsEqual, scopeProfilePlanIdentity } from "../buffer-turn-helpers.js";
+
+/** Option surface of `queueBufferedExtraction` relevant to eligibility. */
+export interface AutomaticSharingOptions {
+  /** Claim-backed backlog tasks own a different buffer view: never share. */
+  execution?: unknown;
+  /** Automatic trigger paths set this; forced replay/import do not. */
+  preemptable?: boolean;
+  failOnExtractionFailure?: boolean;
+  forceExtractionAttempt?: boolean;
+  /** Fail-closed front flush: never share. */
+  preemptRunning?: boolean;
+}
+
+export function automaticSnapshotSharingEligible(options: AutomaticSharingOptions): boolean {
+  return (
+    options.execution === undefined &&
+    options.preemptable === true &&
+    options.failOnExtractionFailure !== true &&
+    options.forceExtractionAttempt !== true &&
+    options.preemptRunning !== true
+  );
+}
+
+/** Consumer-visible equivalence: `bufferTurnsEqual` PLUS the fields it ignores. */
+export function turnRepresentationEquivalent(left: BufferTurn, right: BufferTurn): boolean {
+  return (
+    bufferTurnsEqual(left, right) &&
+    left.extractionContextOnly === right.extractionContextOnly &&
+    left.importProvenance === right.importProvenance &&
+    left.parts === right.parts &&
+    left.rawContent === right.rawContent &&
+    left.sourceFormat === right.sourceFormat
+  );
+}
+
+/** Scope-class bucket key, the same composite `groupTurnsByExtractionScope` uses. */
+function scopeClassKey(turn: BufferTurn): string {
+  return [
+    turn.writeNamespaceOverride ?? "",
+    turn.principalOverride ?? "",
+    scopeProfilePlanIdentity(turn.scopeProfileWritePlan),
+    turn.acceptedCapture === true ? "accepted" : "",
+    turn.codingContext?.projectId ?? "",
+    turn.codingContext?.rootPath ?? "",
+    turn.codingContext?.branch ?? "",
+    turn.codingContext?.defaultBranch ?? "",
+  ].join("\u0000");
+}
+
+/** One queued automatic snapshot: `base` chain plus this trigger's own new turns. */
+export interface SnapshotChain {
+  readonly key: string;
+  readonly scopeClass: string;
+  readonly base: SnapshotChain | undefined;
+  /** Total turns retained by the base chain. */
+  readonly baseLength: number;
+  /** This trigger's non-shared suffix (fresh reference slots, disjoint across the chain). */
+  readonly tail: readonly BufferTurn[];
+  /** Total turns this snapshot represents. */
+  readonly total: number;
+  /** Outstanding tasks holding this node; the node leaves the registry when it reaches 0. */
+  holders: number;
+}
+
+export interface SnapshotSharingStats {
+  /** Distinct content chains registered (not task count — see queuedHolders). */
+  queuedNodes: number;
+  /** Σ per-node window lengths over registered nodes. Sibling nodes sharing
+   * a base chain count that base once per node (per-task window basis). */
+  queuedTotalRefs: number;
+  /** Distinct turn references REACHABLE from queued nodes, counting
+   * released ancestors reached through `base` exactly once (visited-set). */
+  queuedTailRefs: number;
+  /** Longest base chain reachable from a queued node (must stay bounded). */
+  queuedReachableDepth: number;
+  /** Outstanding tasks holding nodes (per-task, not per-node). */
+  queuedHolders: number;
+  /** What retention would be WITHOUT sharing: Σ per-node window length ×
+   * holders (each outstanding task would carry its own full window). */
+  unsharedEquivalentRefs: number;
+}
+
+/** Iterative root-first walk: recursive `yield*` delegation costs O(depth)
+ * per item and hangs production-scale chains (3,000+ turn sessions,
+ * hours-long backlogs). Same order, bounded stack, no casts. */
+function chainNodes(chain: SnapshotChain): SnapshotChain[] {
+  const nodes: SnapshotChain[] = [];
+  for (let node: SnapshotChain | undefined = chain; node; node = node.base) nodes.push(node);
+  return [...nodes].reverse();
+}
+
+/**
+ * Element-wise consumer-equivalence of the chain's turns against a snapshot
+ * prefix. Cost is O(chain.total) compares per admit — required to prove the
+ * shared prefix is consumer-equivalent to the incoming snapshot — so a chain
+ * build is O(depth^2) compares in total (measured, acknowledged in the PR).
+ */
+export function chainPrefixEquivalent(chain: SnapshotChain, turns: readonly BufferTurn[]): boolean {
+  let offset = 0;
+  for (const node of chainNodes(chain)) {
+    for (const chained of node.tail) {
+      const incoming = turns[offset];
+      if (incoming === undefined) return false;
+      if (!turnRepresentationEquivalent(chained, incoming)) return false;
+      offset += 1;
+    }
+  }
+  return offset === chain.total;
+}
+
+/** Fresh array with exactly this snapshot's turns, in order. Run-time only. */
+export function materializeChain(chain: SnapshotChain): BufferTurn[] {
+  const out: BufferTurn[] = [];
+  for (const node of chainNodes(chain)) {
+    for (const turn of node.tail) out.push(turn);
+  }
+  return out;
+}
+
+export class ExtractionSnapshotSharingRegistry {
+  private readonly buckets = new Map<string, SnapshotChain[]>();
+
+  /**
+   * Admit one automatic snapshot for `bufferKey`: chain it onto the newest
+   * queued same-scope snapshot when that is a verified prefix-extension,
+   * otherwise start a fresh chain. The caller's array is never mutated.
+   */
+  admit(bufferKey: string, turns: readonly BufferTurn[]): SnapshotChain {
+    const scopeClass = turns.length > 0 ? scopeClassKey(turns[0]) : "";
+    const bucketKey = `${bufferKey}\u0000${scopeClass}`;
+    const list = this.buckets.get(bucketKey);
+    const base = list !== undefined && list.length > 0 ? list[list.length - 1] : undefined;
+    if (base && base.total === turns.length && chainPrefixEquivalent(base, turns)) {
+      // Identical window: reuse the existing node. Creating a tail=[] node
+      // here would chain onto the base and grow reachable depth (and admit
+      // cost) by one per admission under continuous unchanged ingress, while
+      // stats showed only the newest node. Sharing is exact: the element-wise
+      // equivalence above proved this window equals the base's. The holder
+      // count keeps the node registered until the LAST sharer releases.
+      base.holders += 1;
+      return base;
+    }
+    const node: SnapshotChain =
+      base && base.total <= turns.length && chainPrefixEquivalent(base, turns)
+        ? {
+            key: bufferKey,
+            scopeClass,
+            base,
+            baseLength: base.total,
+            tail: turns.slice(base.total),
+            total: turns.length,
+            holders: 1,
+          }
+        : {
+            key: bufferKey,
+            scopeClass,
+            base: undefined,
+            baseLength: 0,
+            tail: [...turns],
+            total: turns.length,
+            holders: 1,
+          };
+    if (list) list.push(node);
+    else this.buckets.set(bucketKey, [node]);
+    return node;
+  }
+
+  /** Release one holder of a node when its task exits (or on enqueue
+   * refusal). CONTRACT: called EXACTLY ONCE per admit, by the task that
+   * admitted it — the registry has no task identity, so a second call by the
+   * same task would steal another holder's count. The only production caller
+   * (queueBufferedExtraction) enforces this structurally: the closure-finally
+   * and the enqueue-refusal branch are mutually exclusive. Defensively, a
+   * release past zero is a no-op. */
+  release(node: SnapshotChain): void {
+    if (node.holders <= 0) return;
+    node.holders -= 1;
+    if (node.holders > 0) return;
+    const list = this.buckets.get(`${node.key}\u0000${node.scopeClass}`);
+    if (!list) return;
+    const index = list.indexOf(node);
+    if (index >= 0) list.splice(index, 1);
+    if (list.length === 0) this.buckets.delete(`${node.key}\u0000${node.scopeClass}`);
+  }
+
+  /** Proof seam: what the queue retains right now. */
+  stats(): SnapshotSharingStats {
+    // Reachability-accurate accounting: a released ancestor can remain
+    // reachable through a queued descendant's `base`, so bucket-node sums
+    // under-report. Walk each chain once with a visited set of nodes.
+    const visited = new Set<SnapshotChain>();
+    let queuedNodes = 0;
+    let queuedTailRefs = 0;
+    let queuedReachableDepth = 0;
+    let queuedHolders = 0;
+    let unsharedEquivalentRefs = 0;
+    let queuedTotalRefs = 0;
+    for (const list of this.buckets.values()) {
+      for (const node of list) {
+        queuedNodes += 1;
+        unsharedEquivalentRefs += node.total * node.holders;
+        queuedTotalRefs += node.total;
+        let depth = 0;
+        for (let walk: SnapshotChain | undefined = node; walk; walk = walk.base) {
+          depth += 1;
+          if (visited.has(walk)) continue;
+          visited.add(walk);
+          queuedTailRefs += walk.tail.length;
+          queuedHolders += walk.holders;
+        }
+        if (depth > queuedReachableDepth) queuedReachableDepth = depth;
+      }
+    }
+    return { queuedNodes, queuedTotalRefs, queuedTailRefs, queuedReachableDepth, queuedHolders, unsharedEquivalentRefs };
+  }
+}

package/src/orchestration/turn-ingestion.ts

@@ -44,11 +44,8 @@ import type { BufferTurn, PluginConfig, SourceConnectorProvenance } from "../typ
 import { groupTurnsByExtractionScope, bufferTurnsEqual } from "../buffer-turn-helpers.js";
 import { ExtractionDrain } from "./extraction-drain.js";
 import { skipClaimedSession } from "./buffer-drain-gate.js";
-import {
-  queueBufferedCaptureScopeGroups,
-  type CaptureScopeGroupQueueOptions,
-  type ExtractionTaskExecutionContext,
-} from "./extraction-task-queueing.js";
+import { queueBufferedCaptureScopeGroups, type CaptureScopeGroupQueueOptions, type ExtractionTaskExecutionContext } from "./extraction-task-queueing.js";
+import { automaticSnapshotSharingEligible, ExtractionSnapshotSharingRegistry, materializeChain, type SnapshotChain } from "./extraction-queue-snapshot-sharing.js";
 import { resolveScopeProfilePlan, type ResolvedScopeProfilePlan, hasExplicitNamespacePolicy } from "../namespaces/scope-profiles.js";
 import { resolveCodingNamespaceOverlay, combineNamespaces } from "../coding/coding-namespace.js";
 import { canWriteNamespace, defaultNamespaceForPrincipal } from "../namespaces/principal.js";
@@ -166,6 +163,8 @@ function isFlushPlanRecoveryTurn(
 
 export class TurnIngestionCoordinator {
   private readonly drain: ExtractionDrain; // chunked trigger-drain (extraction-drain.ts)
+  /** Queued automatic-snapshot chains: bounded-queue retention via structural sharing. */
+  readonly snapshotSharing = new ExtractionSnapshotSharingRegistry();
   constructor(private readonly deps: TurnIngestionDeps) {
     this.drain = new ExtractionDrain(deps);
   }
@@ -902,6 +901,15 @@ export class TurnIngestionCoordinator {
     }
     if (settled) return;
     const preemptable = options.preemptable === true && options.preemptRunning !== true;
+    const sharingNode =
+      automaticSnapshotSharingEligible(options) && turnsToExtract.length > 0
+        ? this.snapshotSharing.admit(bufferKey, turnsToExtract)
+        : undefined;
+    // Discriminated source so the task closure never captures the caller's
+    // snapshot array when sharing: a textual reference would retain every
+    // overlapping copy and defeat the bound.
+    const queuedTurnsSource: { chain: SnapshotChain } | { direct: BufferTurn[] } =
+      sharingNode ? { chain: sharingNode } : { direct: turnsToExtract };
     const accepted = this.deps.extractionQueueCoordinator.enqueue(async (preemptHandle) => {
       try {
         await this.deps.extractionQueueCoordinator.runPreemptable(preemptHandle, preemptable, options.abortSignal, async (abortSignal) => {
@@ -931,7 +939,10 @@ export class TurnIngestionCoordinator {
         // concurrent drain that already took these turns skips the LLM work,
         // and re-resolve a pinned plan against CURRENT config — revoke skips
         // WITHOUT clearing, and the plan is never retargeted.
-        let effectiveTurns = turnsToExtract;
+        let effectiveTurns =
+          "chain" in queuedTurnsSource
+            ? materializeChain(queuedTurnsSource.chain)
+            : queuedTurnsSource.direct;
         let effectiveScopePlan = options.scopeProfileWritePlan;
         const executionBuffer = options.execution?.buffer;
         if (effectiveTurns.some((turn) => turn.acceptedCapture === true)) {
@@ -1083,10 +1094,12 @@ export class TurnIngestionCoordinator {
       }
       });
       } finally {
+        if (sharingNode) this.snapshotSharing.release(sharingNode);
         options.onTaskExit?.();
       }
     }, { front: options.preemptRunning === true, key: bufferKey });
     if (!accepted) {
+      if (sharingNode) this.snapshotSharing.release(sharingNode);
       settleTask(new Error("extraction queue is stopped"));
       options.onTaskExit?.();
       return;

package/src/orchestrator-extraction-queue.test.ts

@@ -1,10 +1,13 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 
+import { queueBufferedCaptureScopeGroups } from "./orchestration/extraction-task-queueing.js";
 import { ExtractionQueueCoordinator, type ExtractionPreemptHandle, type ExtractionQueueTask } from "./orchestration/extraction-queue-coordinator.js";
 import { initLogger, type LoggerBackend } from "./logger.js";
 import { abortError } from "./abort-error.js";
 
+import type { BufferTurn } from "./types.js";
+
 interface LogEntry {
   level: "info" | "warn" | "error" | "debug";
   message: string;
@@ -35,10 +38,9 @@ function createCoordinator(): ExtractionQueueCoordinator {
   return new ExtractionQueueCoordinator();
 }
 
-// ── Per-key coalescing: a queued-not-started task is superseded by a newer
-// enqueue for the same key instead of stacking another full snapshot ────────
+// ── Per-key FIFO: queued tasks retain their own captured scope and settlement ─
 
-test("a newer enqueue for a queued-not-started key replaces the queued task", async () => {
+test("same-key queued tasks both run in FIFO order", async () => {
   const coordinator = createCoordinator();
   const busy = Promise.withResolvers<void>();
   const releaseBusy = Promise.withResolvers<void>();
@@ -56,15 +58,15 @@ test("a newer enqueue for a queued-not-started key replaces the queued task", as
     ran.push("fresh");
   }, { key: "s1" });
 
-  assert.equal(coordinator.length, 1, "the stale snapshot must be replaced, not stacked");
+  assert.equal(coordinator.length, 2, "same-key tasks remain queued independently");
 
   releaseBusy.resolve();
   assert.equal(await coordinator.waitForIdle(5_000), true);
-  assert.deepEqual(ran, ["fresh"], "only the newest task for the key runs");
+  assert.deepEqual(ran, ["stale", "fresh"], "each caller's task runs in FIFO order");
   assert.equal(coordinator.isProcessing, false);
 });
 
-test("coalescing keeps the superseded entry's position for other keys", async () => {
+test("same-key tasks keep their FIFO positions relative to other keys", async () => {
   const coordinator = createCoordinator();
   const busy = Promise.withResolvers<void>();
   const releaseBusy = Promise.withResolvers<void>();
@@ -90,10 +92,10 @@ test("coalescing keeps the superseded entry's position for other keys", async ()
 
   releaseBusy.resolve();
   assert.equal(await coordinator.waitForIdle(5_000), true);
-  assert.deepEqual(ran, ["k1", "k2-fresh", "k3"], "k2 keeps its queue slot; the newest payload wins");
+  assert.deepEqual(ran, ["k1", "k2-stale", "k2-fresh", "k3"]);
 });
 
-test("a front enqueue supersedes a queued same-key task and keeps preemption", async () => {
+test("a front enqueue preserves queued same-key work and keeps preemption", async () => {
   const coordinator = createCoordinator();
   const busy = Promise.withResolvers<void>();
   const releaseBusy = Promise.withResolvers<void>();
@@ -121,15 +123,15 @@ test("a front enqueue supersedes a queued same-key task and keeps preemption", a
     ran.push("flush-fresh");
   }, { key: "s1", front: true });
 
-  assert.equal(coordinator.length, 1, "the superseded queued task must be dropped");
+  assert.equal(coordinator.length, 2, "front work does not discard queued same-key work");
 
   releaseBusy.resolve();
   assert.equal(await coordinator.waitForIdle(5_000), true);
   assert.equal(preempted, true, "front enqueue still preempts the running automatic work");
-  assert.deepEqual(ran, ["flush-fresh"]);
+  assert.deepEqual(ran, ["flush-fresh", "queued-stale"]);
 });
 
-test("keyless tasks never coalesce", async () => {
+test("keyless tasks remain independent", async () => {
   const coordinator = createCoordinator();
   const busy = Promise.withResolvers<void>();
   const releaseBusy = Promise.withResolvers<void>();
@@ -153,7 +155,7 @@ test("keyless tasks never coalesce", async () => {
   assert.deepEqual(ran, ["first", "second"]);
 });
 
-test("a coalesced enqueue of a running key waits behind the active task", async () => {
+test("same-key enqueues behind an active task retain both queued tasks in FIFO order", async () => {
   const coordinator = createCoordinator();
   const busy = Promise.withResolvers<void>();
   const releaseBusy = Promise.withResolvers<void>();
@@ -174,7 +176,7 @@ test("a coalesced enqueue of a running key waits behind the active task", async
 
   releaseBusy.resolve();
   assert.equal(await coordinator.waitForIdle(5_000), true);
-  assert.deepEqual(order, ["running", "queued-second"]);
+  assert.deepEqual(order, ["running", "queued-first", "queued-second"]);
 });
 
 // ── Issue #549 ─────────────────────────────────────────────────────────────
@@ -627,3 +629,58 @@ test("tryReserveKey refuses active and queued keys, and releases idempotently",
   assert.equal(queue.tryReserveKey("s1"), true, "a settled key reserves again");
   queue.releaseKeyReservation("s1");
 });
+
+test("same-key capture scope groups both run and settle their caller promises", async () => {
+  const coordinator = createCoordinator();
+  const busy = Promise.withResolvers<void>();
+  const releaseBusy = Promise.withResolvers<void>();
+  const ran: string[] = [];
+  const extractions: Promise<void>[] = [];
+
+  coordinator.enqueue(async () => {
+    busy.resolve();
+    await releaseBusy.promise;
+  });
+  await busy.promise;
+
+  const acceptedTurns: BufferTurn[] = [
+    {
+      role: "user",
+      content: "scope A",
+      timestamp: "2026-11-05T00:00:00.000Z",
+      sessionKey: "s1",
+      acceptedCapture: true,
+      writeNamespaceOverride: "namespace-a",
+      principalOverride: "principal-a",
+    },
+    {
+      role: "user",
+      content: "scope B",
+      timestamp: "2026-11-05T00:00:01.000Z",
+      sessionKey: "s1",
+      acceptedCapture: true,
+      writeNamespaceOverride: "namespace-b",
+      principalOverride: "principal-b",
+    },
+  ];
+  queueBufferedCaptureScopeGroups(
+    async (_turns, _reason, options) => {
+      const accepted = coordinator.enqueue(async () => {
+        const namespace = options?.writeNamespaceOverride;
+        assert.ok(namespace);
+        ran.push(namespace);
+        options?.onTaskSettled?.();
+      }, { key: options?.bufferKey });
+      if (!accepted) throw new Error("queue unexpectedly rejected extraction");
+    },
+    acceptedTurns,
+    "s1",
+    { onExtractionQueued: (promise) => extractions.push(promise) },
+  );
+
+  assert.equal(extractions.length, 2, "each captured scope has its own completion promise");
+  releaseBusy.resolve();
+  assert.equal(await coordinator.waitForIdle(5_000), true);
+  await Promise.all(extractions);
+  assert.deepEqual(ran, ["namespace-a", "namespace-b"]);
+});

package/dist/chunk-IPHIIRDN.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/access-observe-helpers.ts"],"sourcesContent":["import { isPreemptedExtraction } from \"./abort-error.js\";\n\ntype PendingObservePreparation = {\n  cancelled: boolean;\n  scopeHint?: string;\n  principal?: string;\n  namespace?: string;\n  scopeResolved: boolean;\n  resolvedScopeFences: Array<{ principal?: string; namespace?: string }>;\n  released: Promise<void>;\n  release: () => void;\n};\n\nfunction resolvedScopesMatch(\n  left: { principal?: string; namespace?: string },\n  right: { principal?: string; namespace?: string },\n): boolean {\n  return left.principal === right.principal && left.namespace === right.namespace;\n}\n\nfunction preparationMatchesScope(\n  reservation: PendingObservePreparation,\n  principal: string | undefined,\n  namespace: string | undefined,\n  scopeHint: string | undefined,\n): boolean {\n  if (reservation.scopeResolved) {\n    return resolvedScopesMatch(reservation, { principal, namespace });\n  }\n  return reservation.scopeHint === undefined || scopeHint === undefined || reservation.scopeHint === scopeHint;\n}\n\nexport type PendingObservePreparationHandle = {\n  isCancelled(): boolean;\n  setScope(principal?: string, namespace?: string): void;\n  release(): void;\n};\n\nexport function pendingObserveScopeHint(options: {\n  namespace?: string;\n  projectTag?: string;\n  cwd?: string;\n}): string | undefined {\n  const namespace = options.namespace?.trim();\n  if (namespace) return `namespace:${namespace}`;\n  const projectTag = options.projectTag?.trim();\n  if (projectTag) return `projectTag:${projectTag}`;\n  const cwd = options.cwd?.trim();\n  return cwd ? `cwd:${cwd}` : undefined;\n}\n\ntype PendingObserveExtraction = {\n  promise: Promise<void>;\n  running: Promise<void>;\n  controllers: Set<AbortController>;\n};\n\nexport class PendingObserveExtractionTracker {\n  private readonly entries = new Map<string, PendingObserveExtraction>();\n  private readonly preparations = new Map<string, Set<PendingObservePreparation>>();\n\n  reserve(sessionKey: string, scopeHint?: string): PendingObservePreparationHandle {\n    let released = false;\n    let resolveReleased: () => void = () => {};\n    const reservation: PendingObservePreparation = {\n      cancelled: false,\n      scopeResolved: false,\n      resolvedScopeFences: [],\n      scopeHint,\n      released: new Promise<void>((resolve) => {\n        resolveReleased = resolve;\n      }),\n      release: () => {\n        if (released) return;\n        released = true;\n        const entries = this.preparations.get(sessionKey);\n        entries?.delete(reservation);\n        if (entries?.size === 0) this.preparations.delete(sessionKey);\n        resolveReleased();\n      },\n    };\n    const entries = this.preparations.get(sessionKey) ?? new Set<PendingObservePreparation>();\n    entries.add(reservation);\n    this.preparations.set(sessionKey, entries);\n    return {\n      isCancelled: () => reservation.cancelled,\n      setScope: (principal, namespace) => {\n        reservation.principal = principal;\n        reservation.namespace = namespace;\n        reservation.scopeResolved = true;\n        if (reservation.resolvedScopeFences.some((fence) => resolvedScopesMatch(reservation, fence))) {\n          reservation.cancelled = true;\n        }\n      },\n      release: reservation.release,\n    };\n  }\n\n  private async waitForPreparations(\n    sessionKey: string,\n    principal: string | undefined,\n    namespace: string | undefined,\n    scopeHint: string | undefined,\n  ): Promise<void> {\n    while (true) {\n      const reservations = [...(this.preparations.get(sessionKey) ?? [])];\n      for (const reservation of reservations) {\n        if (\n          !reservation.cancelled &&\n          !reservation.scopeResolved &&\n          !preparationMatchesScope(reservation, principal, namespace, scopeHint) &&\n          !reservation.resolvedScopeFences.some((fence) =>\n            resolvedScopesMatch(fence, { principal, namespace }),\n          )\n        ) {\n          reservation.resolvedScopeFences.push({ principal, namespace });\n        }\n      }\n      const pending = reservations.filter(\n        (reservation) =>\n          !reservation.cancelled && preparationMatchesScope(reservation, principal, namespace, scopeHint),\n      );\n      if (pending.length === 0) return;\n      await Promise.all(pending.map((reservation) => reservation.released));\n    }\n  }\n\n\n  key(sessionKey: string, principal: string | undefined, namespace: string | undefined): string {\n    return `${sessionKey}\\u0000${principal ?? \"\"}\\u0000${namespace ?? \"\"}`;\n  }\n\n  track(key: string, extraction: Promise<void>, controller: AbortController): void {\n    const previous = this.entries.get(key);\n    const promise = previous\n      ? Promise.allSettled([previous.promise, extraction]).then((results) => {\n          const rejected = results.find(\n            (result): result is PromiseRejectedResult =>\n              result.status === \"rejected\" &&\n              !(result.reason instanceof Error && isPreemptedExtraction(result.reason)),\n          );\n          if (rejected) throw rejected.reason;\n        })\n      : extraction;\n    const entry = {\n      promise,\n      running: previous?.running ?? extraction,\n      controllers: new Set(previous ? [...previous.controllers, controller] : [controller]),\n    };\n    this.entries.set(key, entry);\n    // Any settle (success OR rejection — preemption is just one rejection\n    // kind) ends the pending entry; leaving a settled failure tracked wedged\n    // the key and kept every controller ever registered for it alive.\n    void promise\n      .then(() => {\n        if (this.entries.get(key) === entry) this.entries.delete(key);\n      })\n      .catch(() => {\n        if (this.entries.get(key) === entry) this.entries.delete(key);\n      });\n  }\n\n  cancelPreparations(sessionKey: string, scopeHint?: string): void {\n    for (const reservation of this.preparations.get(sessionKey) ?? []) {\n      if (\n        scopeHint !== undefined &&\n        reservation.scopeHint !== undefined &&\n        reservation.scopeHint !== scopeHint\n      ) {\n        continue;\n      }\n      reservation.cancelled = true;\n    }\n  }\n\n  cancel(\n    sessionKey: string,\n    principal?: string,\n    namespace?: string,\n    scopeHint?: string,\n    reason?: Error,\n  ): void {\n    for (const reservation of this.preparations.get(sessionKey) ?? []) {\n      if (!preparationMatchesScope(reservation, principal, namespace, scopeHint)) continue;\n      reservation.cancelled = true;\n    }\n\n    this.abortTracked(sessionKey, principal, namespace, reason);\n  }\n\n  private abortTracked(\n    sessionKey: string,\n    principal: string | undefined,\n    namespace: string | undefined,\n    reason?: Error,\n  ): void {\n    for (const [key, entry] of this.entries) {\n      const [entrySessionKey, entryPrincipal, entryNamespace] = key.split(\"\\u0000\");\n      if (\n        entrySessionKey !== sessionKey ||\n        (principal !== undefined && entryPrincipal !== (principal ?? \"\")) ||\n        (namespace !== undefined && entryNamespace !== (namespace ?? \"\"))\n      ) continue;\n      for (const controller of entry.controllers) controller.abort(reason);\n    }\n  }\n\n  async wait(\n    sessionKey: string,\n    principal: string | undefined,\n    namespace: string | undefined,\n    abortSignal?: AbortSignal,\n    registerCancellation?: (cancel: () => void) => void,\n    scopeHint?: string,\n    preemptAfterAdmission?: () => void,\n  ): Promise<void> {\n    const key = this.key(sessionKey, principal, namespace);\n    let cancelled = abortSignal?.aborted === true;\n    const abortTracked = (): void => {\n      cancelled = true;\n      this.cancel(sessionKey, principal, namespace, scopeHint);\n    };\n    registerCancellation?.(abortTracked);\n    abortSignal?.addEventListener(\"abort\", abortTracked, { once: true });\n    try {\n      await this.waitForPreparations(sessionKey, principal, namespace, scopeHint);\n      if (cancelled || abortSignal?.aborted) return;\n      if (preemptAfterAdmission) {\n        preemptAfterAdmission();\n        const running = this.entries.get(key)?.running;\n        if (!running) return;\n        try {\n          await running;\n        } catch (error) {\n          if (this.entries.get(key)?.running === running) this.entries.delete(key);\n          if (!(error instanceof Error && isPreemptedExtraction(error))) throw error;\n        }\n        return;\n      }\n      while (true) {\n        const entry = this.entries.get(key);\n        if (!entry) return;\n        try {\n          await entry.promise;\n        } catch (error) {\n          if (this.entries.get(key) !== entry) continue;\n          this.entries.delete(key);\n          if (error instanceof Error && isPreemptedExtraction(error)) return;\n          throw error;\n        }\n        if (this.entries.get(key) !== entry) continue;\n        this.entries.delete(key);\n        return;\n      }\n    } finally {\n      abortSignal?.removeEventListener(\"abort\", abortTracked);\n    }\n  }\n}\n"],"mappings":"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","names":["entries"]}