@milaboratories/pl-tree 1.13.5 → 1.13.6

package/dist/index.cjs

@@ -17,6 +17,7 @@ exports.PlTreeState = require_state.PlTreeState;
 exports.SynchronizedTreeState = require_synchronized_tree.SynchronizedTreeState;
 exports.TreeStateUpdateError = require_state.TreeStateUpdateError;
 exports.constructTreeLoadingRequest = require_sync.constructTreeLoadingRequest;
+exports.derivePollingInterval = require_synchronized_tree.derivePollingInterval;
 exports.formatTreeLoadingStat = require_sync.formatTreeLoadingStat;
 exports.initialTreeLoadingStat = require_sync.initialTreeLoadingStat;
 exports.isPlTreeEntry = require_accessors.isPlTreeEntry;

package/dist/index.d.ts

@@ -5,6 +5,6 @@ import { PlError, PlTreeEntry, PlTreeEntryAccessor, PlTreeNodeAccessor, PlTreeRo
 import { ExtendedResourceData, PlTreeResource, PlTreeState, ResourceDataWithFinalState, ResourceUpdateStat, TreeStateUpdateError } from "./state.js";
 import { PruningFunction, TraversalMode, TreeLoadingRequest, TreeLoadingStat, constructTreeLoadingRequest, formatTreeLoadingStat, initialTreeLoadingStat, loadTreeState } from "./sync.js";
 import { InferSnapshot, ResourceSnapshot, ResourceSnapshotSchema, ResourceWithData, ResourceWithMetadata, makeResourceSnapshot, rsSchema, treeEntryToResourceWithData, treeEntryToResourceWithMetadata } from "./snapshot.js";
-import { ExplicitRootSeed, SharedTypeSeed, SynchronizedTreeOps, SynchronizedTreeState, TreeSeed } from "./synchronized_tree.js";
+import { ExplicitRootSeed, SharedTypeSeed, SynchronizedTreeOps, SynchronizedTreeState, TreeSeed, derivePollingInterval } from "./synchronized_tree.js";
 import { ResourceStats, TreeDumpStats, treeDumpStats } from "./dump.js";
-export { CommonFieldTraverseOps, CommonTraversalOps, ExplicitRootSeed, ExtendedResourceData, FieldTraversalStep, GetFieldStep, InferSnapshot, PlError, PlTreeEntry, PlTreeEntryAccessor, PlTreeNodeAccessor, PlTreeResource, PlTreeRootsAccessor, PlTreeRootsEntry, PlTreeState, PruningFunction, ResourceDataWithFinalState, ResourceInfo, ResourceSnapshot, ResourceSnapshotSchema, ResourceStats, ResourceTraversalOps, ResourceUpdateStat, ResourceWithData, ResourceWithMetadata, SharedTypeSeed, SynchronizedTreeOps, SynchronizedTreeState, TraversalMode, TreeAccessorData, TreeAccessorInstanceData, TreeDumpStats, TreeLoadingRequest, TreeLoadingStat, TreeSeed, TreeStateUpdateError, ValueAndError, ValueOrError, constructTreeLoadingRequest, formatTreeLoadingStat, initialTreeLoadingStat, isPlTreeEntry, isPlTreeEntryAccessor, isPlTreeNodeAccessor, isPlTreeRootsAccessor, isPlTreeRootsEntry, loadTreeState, makeResourceSnapshot, mapValueAndError, mapValueAndErrorIfDefined, rsSchema, treeDumpStats, treeEntryToResourceInfo, treeEntryToResourceWithData, treeEntryToResourceWithMetadata };
+export { CommonFieldTraverseOps, CommonTraversalOps, ExplicitRootSeed, ExtendedResourceData, FieldTraversalStep, GetFieldStep, InferSnapshot, PlError, PlTreeEntry, PlTreeEntryAccessor, PlTreeNodeAccessor, PlTreeResource, PlTreeRootsAccessor, PlTreeRootsEntry, PlTreeState, PruningFunction, ResourceDataWithFinalState, ResourceInfo, ResourceSnapshot, ResourceSnapshotSchema, ResourceStats, ResourceTraversalOps, ResourceUpdateStat, ResourceWithData, ResourceWithMetadata, SharedTypeSeed, SynchronizedTreeOps, SynchronizedTreeState, TraversalMode, TreeAccessorData, TreeAccessorInstanceData, TreeDumpStats, TreeLoadingRequest, TreeLoadingStat, TreeSeed, TreeStateUpdateError, ValueAndError, ValueOrError, constructTreeLoadingRequest, derivePollingInterval, formatTreeLoadingStat, initialTreeLoadingStat, isPlTreeEntry, isPlTreeEntryAccessor, isPlTreeNodeAccessor, isPlTreeRootsAccessor, isPlTreeRootsEntry, loadTreeState, makeResourceSnapshot, mapValueAndError, mapValueAndErrorIfDefined, rsSchema, treeDumpStats, treeEntryToResourceInfo, treeEntryToResourceWithData, treeEntryToResourceWithMetadata };

package/dist/index.js

@@ -3,6 +3,6 @@ import { PlError, PlTreeEntry, PlTreeEntryAccessor, PlTreeNodeAccessor, PlTreeRo
 import { PlTreeResource, PlTreeState, TreeStateUpdateError } from "./state.js";
 import { constructTreeLoadingRequest, formatTreeLoadingStat, initialTreeLoadingStat, loadTreeState } from "./sync.js";
 import { makeResourceSnapshot, rsSchema, treeEntryToResourceWithData, treeEntryToResourceWithMetadata } from "./snapshot.js";
-import { SynchronizedTreeState } from "./synchronized_tree.js";
+import { SynchronizedTreeState, derivePollingInterval } from "./synchronized_tree.js";
 import { treeDumpStats } from "./dump.js";
-export { PlError, PlTreeEntry, PlTreeEntryAccessor, PlTreeNodeAccessor, PlTreeResource, PlTreeRootsAccessor, PlTreeRootsEntry, PlTreeState, SynchronizedTreeState, TreeStateUpdateError, constructTreeLoadingRequest, formatTreeLoadingStat, initialTreeLoadingStat, isPlTreeEntry, isPlTreeEntryAccessor, isPlTreeNodeAccessor, isPlTreeRootsAccessor, isPlTreeRootsEntry, loadTreeState, makeResourceSnapshot, mapValueAndError, mapValueAndErrorIfDefined, rsSchema, treeDumpStats, treeEntryToResourceInfo, treeEntryToResourceWithData, treeEntryToResourceWithMetadata };
+export { PlError, PlTreeEntry, PlTreeEntryAccessor, PlTreeNodeAccessor, PlTreeResource, PlTreeRootsAccessor, PlTreeRootsEntry, PlTreeState, SynchronizedTreeState, TreeStateUpdateError, constructTreeLoadingRequest, derivePollingInterval, formatTreeLoadingStat, initialTreeLoadingStat, isPlTreeEntry, isPlTreeEntryAccessor, isPlTreeNodeAccessor, isPlTreeRootsAccessor, isPlTreeRootsEntry, loadTreeState, makeResourceSnapshot, mapValueAndError, mapValueAndErrorIfDefined, rsSchema, treeDumpStats, treeEntryToResourceInfo, treeEntryToResourceWithData, treeEntryToResourceWithMetadata };

package/dist/synchronized_tree.cjs

@@ -11,6 +11,23 @@ node_timers_promises = require_runtime.__toESM(node_timers_promises, 1);
 * Applies even when {@link scheduleOnNextState} has woken the loop early,
 * preventing tight polling loops during rapid state transitions. */
 const MIN_POLLING_INTERVAL_MS = 100;
+/** Ceiling for the adaptive poll interval. Caps how stale an idle tree can get before the
+* next look, and bounds how far the idle backoff can push the interval out. */
+const MAX_POLLING_INTERVAL_MS = 5e3;
+/** Applied to the interval after a cycle that changed nothing. An idle tree walks its
+* interval out towards {@link MAX_POLLING_INTERVAL_MS} instead of re-polling at full rate;
+* the first cycle that changes anything resets it. */
+const IDLE_BACKOFF_MULTIPLIER = 1.5;
+/** The client's measured RTT becomes an interval floor, scaled by this. Every refresh costs
+* at least one round trip, so polling faster than a small multiple of the RTT only queues
+* round-trips the link cannot service. This is what replaces the fixed interval on a
+* high-latency link; on a fast link the configured `pollingInterval` still dominates. */
+const RTT_POLL_FACTOR = 2;
+/** Ceiling for the RTT-derived floor. The estimate is sampled at connect time and never
+* re-sampled, so without a bound one slow ping pins the cadence high for the whole session.
+* Mirrors `MAX_ADAPTIVE_REQUEST_TIMEOUT` on the deadline side: past this the link is stuck
+* rather than slow, and spacing polls further only delays noticing it recovered. */
+const MAX_RTT_POLL_INTERVAL_MS = 3e4;
 /** Normalizes the {@link SynchronizedTreeState.init} seed argument — a bare
 * {@link SignedResourceId}, a single {@link TreeSeed}, or an array — to `TreeSeed[]`, so
 * every existing single-root caller is unchanged. */
@@ -22,19 +39,39 @@ function normalizeSeeds(seeds) {
 		root: seeds
 	}];
 }
-/** How often, in main-loop iterations, a tree with shared-type seeds re-polls
-* ListUserResources to reconcile its discovered roots. 1 would mean every iteration.
+/** How often a tree with shared-type seeds re-polls ListUserResources to reconcile its
+* discovered roots.
 *
 * Discovery (a full ListUserResources stream) is far heavier than an ordinary incremental
-* refresh, so it must NOT run on every fast refresh tick. The refresh cadence is the tree's
-* `pollingInterval` floored by {@link MIN_POLLING_INTERVAL_MS} (~200ms-1s in practice — the
-* shared-seed discovery tree runs at the 200ms default). At N = 15 discovery fires roughly
-* every 15 × 200ms ≈ 3s, decoupling it from the fast refresh loop while keeping the latency
-* of noticing a new/removed share to a few seconds — acceptable for a human-driven share flow.
+* refresh, so it must NOT run on every refresh tick. This is a wall-clock interval rather
+* than a count of iterations: the refresh cadence is adaptive (it stretches towards
+* {@link MAX_POLLING_INTERVAL_MS} on an idle tree and scales with RTT on a slow link),
+* so a fixed iteration count would let discovery latency drift out with it. Keeping it in
+* milliseconds pins the latency of noticing a new/removed share regardless of cadence, which
+* is what a human-driven share flow cares about.
 *
 * Only trees with shared-type seeds gate on this; {@link discover} is a no-op for single-root
 * and explicit-seed trees (empty `sharedSeeds`), so the value never affects them. */
-const DISCOVERY_EVERY_N_REFRESHES = 15;
+const DISCOVERY_INTERVAL_MS = 3e3;
+/** Counters that mean "this cycle brought something new". Deliberately not the full change
+* breakdown: those fields are sub-counts of `resourcesChanged` and would double-count.
+* `resourcesUnchanged` is excluded by design, since a cycle that only re-fetched unchanged
+* state is exactly the idle case the backoff exists for. */
+function countedChanges(stat) {
+	return stat.resourcesNew + stat.resourcesChanged + stat.resourcesMarkedFinal;
+}
+/** The poll-cadence policy, as a pure function of the last cycle's outcome.
+*
+* `configuredMs` is the tree's static `pollingInterval` and acts as the lower bound, so no
+* link can be polled faster than configured. `rttMs` raises that bound on a slow link.
+* `currentMs` is the interval in force for the cycle that just finished, which is what the
+* idle backoff compounds on. */
+function derivePollingInterval(opts) {
+	const { configuredMs, currentMs, rttMs, changed } = opts;
+	const floor = rttMs === void 0 ? configuredMs : Math.max(configuredMs, Math.min(MAX_RTT_POLL_INTERVAL_MS, Math.ceil(rttMs * RTT_POLL_FACTOR)));
+	const next = changed ? floor : Math.max(floor, currentMs * IDLE_BACKOFF_MULTIPLIER);
+	return Math.max(floor, Math.min(MAX_POLLING_INTERVAL_MS, next));
+}
 var SynchronizedTreeState = class SynchronizedTreeState {
 	pl;
 	logger;
@@ -63,6 +100,7 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 		this.traverseStopRules = traverseStopRules;
 		this.traversalMode = traversalMode ?? "auto";
 		this.pollingInterval = pollingInterval;
+		this.effectivePollingInterval = pollingInterval;
 		this.finalPredicate = finalPredicateOverride ?? pl.finalPredicate;
 		this.logStat = logStat;
 		this.explicitRoots = seeds.filter((s) => s.kind === "resource").map((s) => s.root);
@@ -113,6 +151,24 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 	}
 	currentLoopDelayInterrupt = void 0;
 	scheduledOnNextState = [];
+	/** Interval actually used for the current wait. Starts at the configured `pollingInterval`
+	* and is re-derived after every cycle by {@link updatePollingInterval}. */
+	effectivePollingInterval;
+	/** Re-derives {@link effectivePollingInterval} after a cycle.
+	*
+	* Two independent effects. The floor scales with the client's measured RTT, so a
+	* high-latency link stops queueing round-trips it cannot service. On top of that, a cycle
+	* that changed nothing multiplies the interval out towards
+	* {@link MAX_POLLING_INTERVAL_MS}, while any change snaps it straight back to the floor so
+	* an active tree stays responsive. */
+	updatePollingInterval(changed) {
+		this.effectivePollingInterval = derivePollingInterval({
+			configuredMs: this.pollingInterval,
+			currentMs: this.effectivePollingInterval,
+			rttMs: this.pl.rttEstimateMs,
+			changed
+		});
+	}
 	/** Called from computable hooks when external observer asks for state refresh */
 	scheduleOnNextState(resolve, reject) {
 		if (this.terminated) reject(/* @__PURE__ */ new Error("tree synchronization is terminated"));
@@ -121,6 +177,7 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 				resolve,
 				reject
 			});
+			this.updatePollingInterval(true);
 			if (this.currentLoopDelayInterrupt) {
 				this.currentLoopDelayInterrupt.abort();
 				this.currentLoopDelayInterrupt = void 0;
@@ -195,9 +252,9 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 	/** If true this tree state is permanently terminaed. */
 	terminated = false;
 	async mainLoop() {
-		let stat = this.logStat ? require_sync.initialTreeLoadingStat() : void 0;
+		let stat = require_sync.initialTreeLoadingStat();
 		let lastUpdate = Date.now();
-		let iteration = 0;
+		let lastDiscovery = 0;
 		while (true) {
 			if (!this.keepRunning || this.terminated) break;
 			let toNotify = void 0;
@@ -207,14 +264,18 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 			}
 			try {
 				if (this.logStat === "per-request") stat = require_sync.initialTreeLoadingStat();
-				if (this.sharedSeeds.length > 0 && iteration % DISCOVERY_EVERY_N_REFRESHES === 0) await this.discover();
-				iteration++;
+				if (this.sharedSeeds.length > 0 && Date.now() - lastDiscovery >= DISCOVERY_INTERVAL_MS) {
+					await this.discover();
+					lastDiscovery = Date.now();
+				}
+				const changesBefore = countedChanges(stat);
 				await this.refresh(stat);
-				if (stat && this.logger) this.logger.info(`Tree stat (success, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`);
+				this.updatePollingInterval(countedChanges(stat) > changesBefore);
+				if (this.logStat && this.logger) this.logger.info(`Tree stat (success, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`);
 				lastUpdate = Date.now();
 				if (toNotify !== void 0) for (const n of toNotify) n.resolve();
 			} catch (e) {
-				if (stat && this.logger) this.logger.info(`Tree stat (error, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`);
+				if (this.logStat && this.logger) this.logger.info(`Tree stat (error, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`);
 				lastUpdate = Date.now();
 				if (toNotify !== void 0) for (const n of toNotify) n.reject(e);
 				if (e instanceof require_state.TreeStateUpdateError) {
@@ -233,7 +294,7 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 			}
 			if (!this.keepRunning || this.terminated) break;
 			if (this.scheduledOnNextState.length === 0) {
-				const remaining = Math.max(0, this.pollingInterval - MIN_POLLING_INTERVAL_MS);
+				const remaining = Math.max(0, this.effectivePollingInterval - MIN_POLLING_INTERVAL_MS);
 				if (remaining > 0) try {
 					this.currentLoopDelayInterrupt = new AbortController();
 					await node_timers_promises.setTimeout(remaining, void 0, { signal: AbortSignal.any([this.abortController.signal, this.currentLoopDelayInterrupt.signal]) });
@@ -294,5 +355,6 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 };
 //#endregion
 exports.SynchronizedTreeState = SynchronizedTreeState;
+exports.derivePollingInterval = derivePollingInterval;
 
 //# sourceMappingURL=synchronized_tree.cjs.map

package/dist/synchronized_tree.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"synchronized_tree.cjs","names":["PlTreeState","PollingComputableHooks","PlTreeEntry","PlTreeRootsEntry","constructTreeLoadingRequest","loadTreeState","initialTreeLoadingStat","TreeStateUpdateError","tp"],"sources":["../src/synchronized_tree.ts"],"sourcesContent":["import { PollingComputableHooks } from \"@milaboratories/computable\";\nimport { PlTreeEntry, PlTreeRootsEntry } from \"./accessors\";\nimport type {\n  FinalResourceDataPredicate,\n  PlClient,\n  ResourceType,\n  SignedResourceId,\n  TxOps,\n} from \"@milaboratories/pl-client\";\nimport type { Filter } from \"@milaboratories/pl-client\";\nimport {\n  isUnauthenticated,\n  isTimeoutOrCancelError,\n  isUnimplementedError,\n} from \"@milaboratories/pl-client\";\nimport type { ExtendedResourceData } from \"./state\";\nimport { PlTreeState, TreeStateUpdateError } from \"./state\";\nimport type { PruningFunction, TraversalMode, TreeLoadingStat } from \"./sync\";\nimport { constructTreeLoadingRequest, initialTreeLoadingStat, loadTreeState } from \"./sync\";\nimport * as tp from \"node:timers/promises\";\nimport type { MiLogger } from \"@milaboratories/ts-helpers\";\n\n/** Hard floor between consecutive tree-refresh calls.\n * Applies even when {@link scheduleOnNextState} has woken the loop early,\n * preventing tight polling loops during rapid state transitions. */\nconst MIN_POLLING_INTERVAL_MS = 100;\n\ntype StatLoggingMode = \"cumulative\" | \"per-request\";\n\nexport type SynchronizedTreeOps = {\n  /** Override final predicate from the PlClient */\n  finalPredicateOverride?: FinalResourceDataPredicate;\n\n  /** Pruning function for legacy fallback path. */\n  pruning?: PruningFunction;\n\n  /** ResourceTree field filter for modern backend path. */\n  fieldFilter?: Filter;\n\n  /** ResourceTree traversal stop rules for modern backend path. */\n  traverseStopRules?: Filter;\n\n  /** Interval after last sync to sleep before the next one */\n  pollingInterval: number;\n  /** For how long to continue polling after the last derived value access */\n  stopPollingDelay: number;\n\n  /** If one of the values, tree will log stats of each polling request */\n  logStat?: StatLoggingMode;\n\n  /** Timeout for initial tree loading. If not specified, will use default for RO tx from pl-client. */\n  initialTreeLoadingTimeout?: number;\n\n  /** Controls which tree-loading path to use.  Default `\"auto\"`. */\n  traversalMode?: TraversalMode;\n};\n\n/** An explicit resource to serve as a tree root. Several explicit seeds may be passed. */\nexport type ExplicitRootSeed = { kind: \"resource\"; root: SignedResourceId };\n\n/** Discovers, as roots, every resource of this type shared with the current user.\n *  Matched against SharedResource.resourceType by NAME (version optional/ignored). The\n *  discovered set is DYNAMIC — roots appear/disappear as grants are added/revoked/expire. */\nexport type SharedTypeSeed = { kind: \"shared\"; resourceType: ResourceType };\n\nexport type TreeSeed = ExplicitRootSeed | SharedTypeSeed;\n\n/** Normalizes the {@link SynchronizedTreeState.init} seed argument — a bare\n * {@link SignedResourceId}, a single {@link TreeSeed}, or an array — to `TreeSeed[]`, so\n * every existing single-root caller is unchanged. */\nfunction normalizeSeeds(seeds: SignedResourceId | TreeSeed | TreeSeed[]): TreeSeed[] {\n  if (Array.isArray(seeds)) return seeds;\n  if (typeof seeds === \"object\" && seeds !== null && \"kind\" in seeds) return [seeds];\n  // bare SignedResourceId\n  return [{ kind: \"resource\", root: seeds }];\n}\n\n/** How often, in main-loop iterations, a tree with shared-type seeds re-polls\n * ListUserResources to reconcile its discovered roots. 1 would mean every iteration.\n *\n * Discovery (a full ListUserResources stream) is far heavier than an ordinary incremental\n * refresh, so it must NOT run on every fast refresh tick. The refresh cadence is the tree's\n * `pollingInterval` floored by {@link MIN_POLLING_INTERVAL_MS} (~200ms-1s in practice — the\n * shared-seed discovery tree runs at the 200ms default). At N = 15 discovery fires roughly\n * every 15 × 200ms ≈ 3s, decoupling it from the fast refresh loop while keeping the latency\n * of noticing a new/removed share to a few seconds — acceptable for a human-driven share flow.\n *\n * Only trees with shared-type seeds gate on this; {@link discover} is a no-op for single-root\n * and explicit-seed trees (empty `sharedSeeds`), so the value never affects them. */\nconst DISCOVERY_EVERY_N_REFRESHES = 15;\n\ntype ScheduledRefresh = {\n  resolve: () => void;\n  reject: (err: any) => void;\n};\n\nexport class SynchronizedTreeState {\n  private readonly finalPredicate: FinalResourceDataPredicate;\n  private state: PlTreeState;\n  private readonly pollingInterval: number;\n  private readonly pruning?: PruningFunction;\n  private readonly fieldFilter?: Filter;\n  private readonly traverseStopRules?: Filter;\n  private readonly traversalMode: TraversalMode;\n  private readonly logStat?: StatLoggingMode;\n  private readonly hooks: PollingComputableHooks;\n  private readonly abortController = new AbortController();\n\n  /** Explicit-resource seeds: fixed roots, present from construction. */\n  private readonly explicitRoots: SignedResourceId[];\n  /** Shared-type seeds (discovered roots), if any. */\n  private readonly sharedSeeds: SharedTypeSeed[];\n  /** Roots discovered for shared-type seeds on the last discovery poll. */\n  private discoveredRoots: SignedResourceId[] = [];\n\n  private constructor(\n    private readonly pl: PlClient,\n    seeds: TreeSeed[],\n    ops: SynchronizedTreeOps,\n    private readonly logger?: MiLogger,\n  ) {\n    const {\n      finalPredicateOverride,\n      pruning,\n      fieldFilter,\n      traverseStopRules,\n      traversalMode,\n      pollingInterval,\n      stopPollingDelay,\n      logStat,\n    } = ops;\n    this.pruning = pruning;\n    this.fieldFilter = fieldFilter;\n    this.traverseStopRules = traverseStopRules;\n    this.traversalMode = traversalMode ?? \"auto\";\n    this.pollingInterval = pollingInterval;\n    this.finalPredicate = finalPredicateOverride ?? pl.finalPredicate;\n    this.logStat = logStat;\n\n    this.explicitRoots = seeds\n      .filter((s): s is ExplicitRootSeed => s.kind === \"resource\")\n      .map((s) => s.root);\n    this.sharedSeeds = seeds.filter((s): s is SharedTypeSeed => s.kind === \"shared\");\n\n    this.state = new PlTreeState(this.currentRootSet(), this.finalPredicate);\n    this.hooks = new PollingComputableHooks(\n      () => this.startUpdating(),\n      () => this.stopUpdating(),\n      { stopDebounce: stopPollingDelay },\n      (resolve, reject) => this.scheduleOnNextState(resolve, reject),\n    );\n  }\n\n  /** The current protected root set: explicit roots plus the latest discovered roots. */\n  private currentRootSet(): Set<SignedResourceId> {\n    return new Set([...this.explicitRoots, ...this.discoveredRoots]);\n  }\n\n  /** Resolves the single root for the backward-compatible single-root accessors, throwing\n   * if the tree does not have exactly one root (guards legacy callers against multi-root). */\n  private soleRoot(): SignedResourceId {\n    const roots = this.currentRootSet();\n    if (roots.size !== 1)\n      throw new Error(\n        `single-root accessor used on a tree with ${roots.size} roots; use rootsEntry() instead`,\n      );\n    return roots.values().next().value!;\n  }\n\n  /** @deprecated use \"entry\" instead */\n  public accessor(rid?: SignedResourceId): PlTreeEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return this.entry(rid);\n  }\n\n  /** Backward-compatible single-root entry. With no `rid` it returns the sole root's entry\n   * and THROWS if the tree has zero or more than one root. An explicit `rid` addresses any\n   * resource in the heap, as today. */\n  public entry(rid?: SignedResourceId): PlTreeEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return new PlTreeEntry(\n      { treeProvider: () => this.state, hooks: this.hooks },\n      rid ?? this.soleRoot(),\n    );\n  }\n\n  /** Reactive provider for the current root SET. Reading it inside a Computable tracks the\n   * set as a dependency, so the Computable recomputes when discovered roots appear/disappear. */\n  public rootsEntry(): PlTreeRootsEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return new PlTreeRootsEntry({ treeProvider: () => this.state, hooks: this.hooks });\n  }\n\n  /** Can be used to externally kick off the synchronization polling loop, and\n   * await for the first synchronization to happen. */\n  public async refreshState(): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    await this.hooks.refreshState();\n  }\n\n  private currentLoopDelayInterrupt: AbortController | undefined = undefined;\n  private scheduledOnNextState: ScheduledRefresh[] = [];\n\n  /** Called from computable hooks when external observer asks for state refresh */\n  private scheduleOnNextState(resolve: () => void, reject: (err: any) => void): void {\n    if (this.terminated) reject(new Error(\"tree synchronization is terminated\"));\n    else {\n      this.scheduledOnNextState.push({ resolve, reject });\n      if (this.currentLoopDelayInterrupt) {\n        this.currentLoopDelayInterrupt.abort();\n        this.currentLoopDelayInterrupt = undefined;\n      }\n    }\n  }\n\n  /** Called from observer */\n  private startUpdating(): void {\n    if (this.terminated) return;\n    this.keepRunning = true;\n    if (this.currentLoop === undefined) this.currentLoop = this.mainLoop();\n  }\n\n  /** Called from observer */\n  private stopUpdating(): void {\n    this.keepRunning = false;\n  }\n\n  /** If true, main loop will continue polling pl state. */\n  private keepRunning = false;\n  /** Actual state of main loop. */\n  private currentLoop: Promise<void> | undefined = undefined;\n\n  /** Executed from the main loop, and initialization procedure. */\n  private async refresh(stats?: TreeLoadingStat, txOps?: TxOps): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    try {\n      await this.loadAndApply(stats, txOps);\n    } catch (e) {\n      // Discovery-tree self-heal: a discovered root whose grant was revoked/expired fails the whole\n      // ResourceTree poll with Unauthenticated. Re-discover (drops dead roots) and retry once. This is\n      // self-discriminating — a genuinely dead session also fails discover()'s own call, so real auth\n      // loss still propagates. Only for discovery trees; explicit-root trees propagate as-is.\n      if (this.sharedSeeds.length > 0 && isUnauthenticated(e)) {\n        this.logger?.warn(\n          \"discovery tree: Unauthenticated on ResourceTree (likely revoked/expired root); re-discovering and retrying\",\n        );\n        await this.discover();\n        await this.loadAndApply(stats, txOps);\n      } else throw e;\n    }\n  }\n\n  private async loadAndApply(stats?: TreeLoadingStat, txOps?: TxOps): Promise<void> {\n    const request = constructTreeLoadingRequest(this.state, {\n      pruningFunction: this.pruning,\n      fieldFilter: this.fieldFilter,\n      traverseStopRules: this.traverseStopRules,\n    });\n    // A shared-type-seed tree with no currently-discovered roots is legitimately empty:\n    // there is nothing to traverse, and tx.resourceTree([]) would throw \"at least one seed\n    // must be provided\". Skip the backend load and leave the (empty) state as-is — discovery\n    // adds roots later via setRoots(), which schedules the next refresh. Explicit-root trees\n    // never hit this (their root set is non-empty by construction).\n    if (request.seedResources.length === 0 && request.finalResources.size === 0) return;\n    const data = await this.pl.withReadTx(\n      \"ReadingTree\",\n      async (tx) => {\n        return await loadTreeState(\n          tx,\n          request,\n          stats,\n          this.pl.serverInfo.capabilities ?? [],\n          this.traversalMode,\n          this.logger,\n        );\n      },\n      txOps,\n    );\n    this.state.updateFromResourceData(data, { allowOrphanInputs: true, stat: stats });\n  }\n\n  /** Discovery sync for shared-type seeds: re-polls `ListUserResources` (gRPC-only) and\n   * reconciles the discovered root set against the heap. A longer poll result adds roots; a\n   * shorter one removes them (grant revoked/expired) — the removed roots' subtrees cascade\n   * to collection via the ordinary refcount GC ({@link PlTreeState.setRoots}). No-op when the\n   * tree has no shared-type seeds, or silently no-op on a REST client where `ListUserResources`\n   * is unavailable. */\n  private async discover(): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    if (this.sharedSeeds.length === 0) return;\n\n    const discovered = new Set<SignedResourceId>();\n    for (const seed of this.sharedSeeds) {\n      let ids: SignedResourceId[];\n      try {\n        // match by name only (permissive; ignores version, so it survives schema bumps)\n        ids = await this.pl.userResources.listSharedResourcesByType(seed.resourceType.name);\n      } catch (e: unknown) {\n        if (isUnimplementedError(e)) continue;\n        throw e;\n      }\n      for (const id of ids) discovered.add(id);\n    }\n\n    this.discoveredRoots = [...discovered];\n    this.state.setRoots(this.currentRootSet());\n  }\n\n  /** If true this tree state is permanently terminaed. */\n  private terminated = false;\n\n  private async mainLoop() {\n    // will hold request stats\n    let stat = this.logStat ? initialTreeLoadingStat() : undefined;\n\n    let lastUpdate = Date.now();\n\n    // counts refresh iterations to pace the discovery poll for shared-type seeds.\n    let iteration = 0;\n\n    while (true) {\n      if (!this.keepRunning || this.terminated) break;\n\n      // saving those who want to be notified about new state here\n      // because those who will be added during the tree retrieval\n      // should be notified only on the next round\n      let toNotify: ScheduledRefresh[] | undefined = undefined;\n      if (this.scheduledOnNextState.length > 0) {\n        toNotify = this.scheduledOnNextState;\n        this.scheduledOnNextState = [];\n      }\n\n      try {\n        // resetting stats if we were asked to collect non-cumulative stats\n        if (this.logStat === \"per-request\") stat = initialTreeLoadingStat();\n\n        // discovery sync for shared-type seeds: reconcile the discovered root set before\n        // refreshing, so newly discovered roots are materialized in this same iteration.\n        if (this.sharedSeeds.length > 0 && iteration % DISCOVERY_EVERY_N_REFRESHES === 0) {\n          await this.discover();\n        }\n        iteration++;\n\n        // actual tree synchronization\n        await this.refresh(stat);\n\n        // logging stats if we were asked to\n        if (stat && this.logger)\n          this.logger.info(\n            `Tree stat (success, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,\n          );\n        lastUpdate = Date.now();\n\n        // notifying that we got new state\n        if (toNotify !== undefined) for (const n of toNotify) n.resolve();\n      } catch (e: any) {\n        // logging stats if we were asked to (even if error occured)\n        if (stat && this.logger)\n          this.logger.info(\n            `Tree stat (error, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,\n          );\n        lastUpdate = Date.now();\n\n        // notifying that we failed to refresh the state\n        if (toNotify !== undefined) for (const n of toNotify) n.reject(e);\n\n        // catching tree update errors, as they may leave our tree in inconsistent state\n        if (e instanceof TreeStateUpdateError) {\n          // important error logging, this should never happen\n          this.logger?.error(e);\n\n          // marking everybody who used previous state as changed\n          this.state.invalidateTree(\"stat update error\");\n          // creating new tree with the full current root set (re-discovered on next iteration)\n          this.state = new PlTreeState(this.currentRootSet(), this.finalPredicate);\n\n          // scheduling state update without delay\n          continue;\n\n          // unfortunately external observer may still see tree in its default\n          // empty state, though this is best we can do in this exceptional\n          // situation, and hope on caching layers inside computables to present\n          // some stale state until we reconstruct the tree again\n        } else this.logger?.warn(e);\n      }\n\n      if (!this.keepRunning || this.terminated) break;\n\n      // Phase 1: mandatory floor — always wait at least MIN_POLLING_INTERVAL_MS.\n      // Not interruptible by scheduleOnNextState; only termination aborts it.\n      try {\n        await tp.setTimeout(MIN_POLLING_INTERVAL_MS, undefined, {\n          signal: this.abortController.signal,\n        });\n      } catch (e: unknown) {\n        if (!isTimeoutOrCancelError(e)) throw new Error(\"Unexpected error\", { cause: e });\n        if (this.abortController.signal.aborted) break;\n      }\n\n      if (!this.keepRunning || this.terminated) break;\n\n      // Phase 2: optional remainder up to pollingInterval — interruptible by\n      // scheduleOnNextState so that an external nudge wakes the loop promptly.\n      if (this.scheduledOnNextState.length === 0) {\n        const remaining = Math.max(0, this.pollingInterval - MIN_POLLING_INTERVAL_MS);\n        if (remaining > 0) {\n          try {\n            this.currentLoopDelayInterrupt = new AbortController();\n            await tp.setTimeout(remaining, undefined, {\n              signal: AbortSignal.any([\n                this.abortController.signal,\n                this.currentLoopDelayInterrupt.signal,\n              ]),\n            });\n          } catch (e: unknown) {\n            if (!isTimeoutOrCancelError(e)) throw new Error(\"Unexpected error\", { cause: e });\n            if (this.abortController.signal.aborted) break;\n            // Otherwise it was just the loop delay interrupt (scheduleOnNextState),\n            // continue to the next iteration\n          } finally {\n            this.currentLoopDelayInterrupt = undefined;\n          }\n        }\n      }\n    }\n\n    // reset only as a very last line\n    this.currentLoop = undefined;\n  }\n\n  /**\n   * Dumps the current state of the tree.\n   * @returns An array of ExtendedResourceData objects representing the current state of the tree.\n   */\n  public dumpState(): ExtendedResourceData[] {\n    return this.state.dumpState();\n  }\n\n  /**\n   * Terminates the internal loop, and permanently destoys all internal state, so\n   * all computables using this state will resolve to errors.\n   * */\n  public async terminate(): Promise<void> {\n    this.keepRunning = false;\n    this.terminated = true;\n    this.abortController.abort();\n\n    if (this.currentLoop === undefined) return;\n    await this.currentLoop;\n\n    this.state.invalidateTree(\"synchronization terminated for the tree\");\n  }\n\n  /** @deprecated */\n  public async awaitSyncLoopTermination(): Promise<void> {\n    if (this.currentLoop === undefined) return;\n    await this.currentLoop;\n  }\n\n  /**\n   * Initializes a synchronized tree from one or more seeds.\n   *\n   * @param seeds a bare {@link SignedResourceId} (the original single-root contract), a\n   *   single {@link TreeSeed}, or an array of seeds. Bare ids and explicit-resource seeds\n   *   become roots immediately; shared-type seeds discover their roots via `ListUserResources`.\n   */\n  public static async init(\n    pl: PlClient,\n    seeds: SignedResourceId | TreeSeed | TreeSeed[],\n    ops: SynchronizedTreeOps,\n    logger?: MiLogger,\n  ) {\n    const tree = new SynchronizedTreeState(pl, normalizeSeeds(seeds), ops, logger);\n\n    const stat = ops.logStat ? initialTreeLoadingStat() : undefined;\n\n    let ok = false;\n\n    try {\n      // resolve shared-type seeds before the first refresh so discovered roots load now\n      await tree.discover();\n      await tree.refresh(stat, {\n        timeout: ops.initialTreeLoadingTimeout,\n      });\n      ok = true;\n    } finally {\n      // logging stats if we were asked to (even if error occured)\n      if (stat && logger)\n        logger.info(\n          `Tree stat (initial load, ${ok ? \"success\" : \"failure\"}): ${JSON.stringify(stat)}`,\n        );\n    }\n\n    return tree;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"synchronized_tree.cjs","names":["PlTreeState","PollingComputableHooks","PlTreeEntry","PlTreeRootsEntry","constructTreeLoadingRequest","loadTreeState","initialTreeLoadingStat","TreeStateUpdateError","tp"],"sources":["../src/synchronized_tree.ts"],"sourcesContent":["import { PollingComputableHooks } from \"@milaboratories/computable\";\nimport { PlTreeEntry, PlTreeRootsEntry } from \"./accessors\";\nimport type {\n  FinalResourceDataPredicate,\n  PlClient,\n  ResourceType,\n  SignedResourceId,\n  TxOps,\n} from \"@milaboratories/pl-client\";\nimport type { Filter } from \"@milaboratories/pl-client\";\nimport {\n  isUnauthenticated,\n  isTimeoutOrCancelError,\n  isUnimplementedError,\n} from \"@milaboratories/pl-client\";\nimport type { ExtendedResourceData } from \"./state\";\nimport { PlTreeState, TreeStateUpdateError } from \"./state\";\nimport type { PruningFunction, TraversalMode, TreeLoadingStat } from \"./sync\";\nimport { constructTreeLoadingRequest, initialTreeLoadingStat, loadTreeState } from \"./sync\";\nimport * as tp from \"node:timers/promises\";\nimport type { MiLogger } from \"@milaboratories/ts-helpers\";\n\n/** Hard floor between consecutive tree-refresh calls.\n * Applies even when {@link scheduleOnNextState} has woken the loop early,\n * preventing tight polling loops during rapid state transitions. */\nconst MIN_POLLING_INTERVAL_MS = 100;\n\n/** Ceiling for the adaptive poll interval. Caps how stale an idle tree can get before the\n * next look, and bounds how far the idle backoff can push the interval out. */\nconst MAX_POLLING_INTERVAL_MS = 5_000;\n\n/** Applied to the interval after a cycle that changed nothing. An idle tree walks its\n * interval out towards {@link MAX_POLLING_INTERVAL_MS} instead of re-polling at full rate;\n * the first cycle that changes anything resets it. */\nconst IDLE_BACKOFF_MULTIPLIER = 1.5;\n\n/** The client's measured RTT becomes an interval floor, scaled by this. Every refresh costs\n * at least one round trip, so polling faster than a small multiple of the RTT only queues\n * round-trips the link cannot service. This is what replaces the fixed interval on a\n * high-latency link; on a fast link the configured `pollingInterval` still dominates. */\nconst RTT_POLL_FACTOR = 2;\n\n/** Ceiling for the RTT-derived floor. The estimate is sampled at connect time and never\n * re-sampled, so without a bound one slow ping pins the cadence high for the whole session.\n * Mirrors `MAX_ADAPTIVE_REQUEST_TIMEOUT` on the deadline side: past this the link is stuck\n * rather than slow, and spacing polls further only delays noticing it recovered. */\nconst MAX_RTT_POLL_INTERVAL_MS = 30_000;\n\ntype StatLoggingMode = \"cumulative\" | \"per-request\";\n\nexport type SynchronizedTreeOps = {\n  /** Override final predicate from the PlClient */\n  finalPredicateOverride?: FinalResourceDataPredicate;\n\n  /** Pruning function for legacy fallback path. */\n  pruning?: PruningFunction;\n\n  /** ResourceTree field filter for modern backend path. */\n  fieldFilter?: Filter;\n\n  /** ResourceTree traversal stop rules for modern backend path. */\n  traverseStopRules?: Filter;\n\n  /** Interval after last sync to sleep before the next one */\n  pollingInterval: number;\n  /** For how long to continue polling after the last derived value access */\n  stopPollingDelay: number;\n\n  /** If one of the values, tree will log stats of each polling request */\n  logStat?: StatLoggingMode;\n\n  /** Timeout for initial tree loading. If not specified, will use default for RO tx from pl-client. */\n  initialTreeLoadingTimeout?: number;\n\n  /** Controls which tree-loading path to use.  Default `\"auto\"`. */\n  traversalMode?: TraversalMode;\n};\n\n/** An explicit resource to serve as a tree root. Several explicit seeds may be passed. */\nexport type ExplicitRootSeed = { kind: \"resource\"; root: SignedResourceId };\n\n/** Discovers, as roots, every resource of this type shared with the current user.\n *  Matched against SharedResource.resourceType by NAME (version optional/ignored). The\n *  discovered set is DYNAMIC — roots appear/disappear as grants are added/revoked/expire. */\nexport type SharedTypeSeed = { kind: \"shared\"; resourceType: ResourceType };\n\nexport type TreeSeed = ExplicitRootSeed | SharedTypeSeed;\n\n/** Normalizes the {@link SynchronizedTreeState.init} seed argument — a bare\n * {@link SignedResourceId}, a single {@link TreeSeed}, or an array — to `TreeSeed[]`, so\n * every existing single-root caller is unchanged. */\nfunction normalizeSeeds(seeds: SignedResourceId | TreeSeed | TreeSeed[]): TreeSeed[] {\n  if (Array.isArray(seeds)) return seeds;\n  if (typeof seeds === \"object\" && seeds !== null && \"kind\" in seeds) return [seeds];\n  // bare SignedResourceId\n  return [{ kind: \"resource\", root: seeds }];\n}\n\n/** How often a tree with shared-type seeds re-polls ListUserResources to reconcile its\n * discovered roots.\n *\n * Discovery (a full ListUserResources stream) is far heavier than an ordinary incremental\n * refresh, so it must NOT run on every refresh tick. This is a wall-clock interval rather\n * than a count of iterations: the refresh cadence is adaptive (it stretches towards\n * {@link MAX_POLLING_INTERVAL_MS} on an idle tree and scales with RTT on a slow link),\n * so a fixed iteration count would let discovery latency drift out with it. Keeping it in\n * milliseconds pins the latency of noticing a new/removed share regardless of cadence, which\n * is what a human-driven share flow cares about.\n *\n * Only trees with shared-type seeds gate on this; {@link discover} is a no-op for single-root\n * and explicit-seed trees (empty `sharedSeeds`), so the value never affects them. */\nconst DISCOVERY_INTERVAL_MS = 3_000;\n\n/** Counters that mean \"this cycle brought something new\". Deliberately not the full change\n * breakdown: those fields are sub-counts of `resourcesChanged` and would double-count.\n * `resourcesUnchanged` is excluded by design, since a cycle that only re-fetched unchanged\n * state is exactly the idle case the backoff exists for. */\nfunction countedChanges(stat: TreeLoadingStat): number {\n  return stat.resourcesNew + stat.resourcesChanged + stat.resourcesMarkedFinal;\n}\n\n/** The poll-cadence policy, as a pure function of the last cycle's outcome.\n *\n * `configuredMs` is the tree's static `pollingInterval` and acts as the lower bound, so no\n * link can be polled faster than configured. `rttMs` raises that bound on a slow link.\n * `currentMs` is the interval in force for the cycle that just finished, which is what the\n * idle backoff compounds on. */\nexport function derivePollingInterval(opts: {\n  configuredMs: number;\n  currentMs: number;\n  rttMs: number | undefined;\n  changed: boolean;\n}): number {\n  const { configuredMs, currentMs, rttMs, changed } = opts;\n\n  // The cap applies to the RTT-derived part only, so `configuredMs` stays an absolute lower\n  // bound even if it is ever set above the cap.\n  const floor =\n    rttMs === undefined\n      ? configuredMs\n      : Math.max(\n          configuredMs,\n          Math.min(MAX_RTT_POLL_INTERVAL_MS, Math.ceil(rttMs * RTT_POLL_FACTOR)),\n        );\n\n  const next = changed ? floor : Math.max(floor, currentMs * IDLE_BACKOFF_MULTIPLIER);\n\n  // The ceiling never cuts below the floor: a link slower than MAX_POLLING_INTERVAL_MS still\n  // gets its RTT-derived spacing rather than being forced to re-poll early.\n  return Math.max(floor, Math.min(MAX_POLLING_INTERVAL_MS, next));\n}\n\ntype ScheduledRefresh = {\n  resolve: () => void;\n  reject: (err: any) => void;\n};\n\nexport class SynchronizedTreeState {\n  private readonly finalPredicate: FinalResourceDataPredicate;\n  private state: PlTreeState;\n  private readonly pollingInterval: number;\n  private readonly pruning?: PruningFunction;\n  private readonly fieldFilter?: Filter;\n  private readonly traverseStopRules?: Filter;\n  private readonly traversalMode: TraversalMode;\n  private readonly logStat?: StatLoggingMode;\n  private readonly hooks: PollingComputableHooks;\n  private readonly abortController = new AbortController();\n\n  /** Explicit-resource seeds: fixed roots, present from construction. */\n  private readonly explicitRoots: SignedResourceId[];\n  /** Shared-type seeds (discovered roots), if any. */\n  private readonly sharedSeeds: SharedTypeSeed[];\n  /** Roots discovered for shared-type seeds on the last discovery poll. */\n  private discoveredRoots: SignedResourceId[] = [];\n\n  private constructor(\n    private readonly pl: PlClient,\n    seeds: TreeSeed[],\n    ops: SynchronizedTreeOps,\n    private readonly logger?: MiLogger,\n  ) {\n    const {\n      finalPredicateOverride,\n      pruning,\n      fieldFilter,\n      traverseStopRules,\n      traversalMode,\n      pollingInterval,\n      stopPollingDelay,\n      logStat,\n    } = ops;\n    this.pruning = pruning;\n    this.fieldFilter = fieldFilter;\n    this.traverseStopRules = traverseStopRules;\n    this.traversalMode = traversalMode ?? \"auto\";\n    this.pollingInterval = pollingInterval;\n    this.effectivePollingInterval = pollingInterval;\n    this.finalPredicate = finalPredicateOverride ?? pl.finalPredicate;\n    this.logStat = logStat;\n\n    this.explicitRoots = seeds\n      .filter((s): s is ExplicitRootSeed => s.kind === \"resource\")\n      .map((s) => s.root);\n    this.sharedSeeds = seeds.filter((s): s is SharedTypeSeed => s.kind === \"shared\");\n\n    this.state = new PlTreeState(this.currentRootSet(), this.finalPredicate);\n    this.hooks = new PollingComputableHooks(\n      () => this.startUpdating(),\n      () => this.stopUpdating(),\n      { stopDebounce: stopPollingDelay },\n      (resolve, reject) => this.scheduleOnNextState(resolve, reject),\n    );\n  }\n\n  /** The current protected root set: explicit roots plus the latest discovered roots. */\n  private currentRootSet(): Set<SignedResourceId> {\n    return new Set([...this.explicitRoots, ...this.discoveredRoots]);\n  }\n\n  /** Resolves the single root for the backward-compatible single-root accessors, throwing\n   * if the tree does not have exactly one root (guards legacy callers against multi-root). */\n  private soleRoot(): SignedResourceId {\n    const roots = this.currentRootSet();\n    if (roots.size !== 1)\n      throw new Error(\n        `single-root accessor used on a tree with ${roots.size} roots; use rootsEntry() instead`,\n      );\n    return roots.values().next().value!;\n  }\n\n  /** @deprecated use \"entry\" instead */\n  public accessor(rid?: SignedResourceId): PlTreeEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return this.entry(rid);\n  }\n\n  /** Backward-compatible single-root entry. With no `rid` it returns the sole root's entry\n   * and THROWS if the tree has zero or more than one root. An explicit `rid` addresses any\n   * resource in the heap, as today. */\n  public entry(rid?: SignedResourceId): PlTreeEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return new PlTreeEntry(\n      { treeProvider: () => this.state, hooks: this.hooks },\n      rid ?? this.soleRoot(),\n    );\n  }\n\n  /** Reactive provider for the current root SET. Reading it inside a Computable tracks the\n   * set as a dependency, so the Computable recomputes when discovered roots appear/disappear. */\n  public rootsEntry(): PlTreeRootsEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return new PlTreeRootsEntry({ treeProvider: () => this.state, hooks: this.hooks });\n  }\n\n  /** Can be used to externally kick off the synchronization polling loop, and\n   * await for the first synchronization to happen. */\n  public async refreshState(): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    await this.hooks.refreshState();\n  }\n\n  private currentLoopDelayInterrupt: AbortController | undefined = undefined;\n  private scheduledOnNextState: ScheduledRefresh[] = [];\n\n  /** Interval actually used for the current wait. Starts at the configured `pollingInterval`\n   * and is re-derived after every cycle by {@link updatePollingInterval}. */\n  private effectivePollingInterval: number;\n\n  /** Re-derives {@link effectivePollingInterval} after a cycle.\n   *\n   * Two independent effects. The floor scales with the client's measured RTT, so a\n   * high-latency link stops queueing round-trips it cannot service. On top of that, a cycle\n   * that changed nothing multiplies the interval out towards\n   * {@link MAX_POLLING_INTERVAL_MS}, while any change snaps it straight back to the floor so\n   * an active tree stays responsive. */\n  private updatePollingInterval(changed: boolean): void {\n    this.effectivePollingInterval = derivePollingInterval({\n      configuredMs: this.pollingInterval,\n      currentMs: this.effectivePollingInterval,\n      rttMs: this.pl.rttEstimateMs,\n      changed,\n    });\n  }\n\n  /** Called from computable hooks when external observer asks for state refresh */\n  private scheduleOnNextState(resolve: () => void, reject: (err: any) => void): void {\n    if (this.terminated) reject(new Error(\"tree synchronization is terminated\"));\n    else {\n      this.scheduledOnNextState.push({ resolve, reject });\n      // Someone is waiting on fresh state, so this tree is not idle after all: drop any\n      // accumulated backoff, otherwise the cycles right after a nudge stay slow. Routed\n      // through the policy rather than assigning the configured value directly, so the RTT\n      // floor survives the reset. Assigning it raw would poll a high-latency link faster than\n      // it can answer, and the interval would stay there until the next cycle that completes:\n      // the error path never reaches updatePollingInterval, so a failing nudged refresh would\n      // keep retrying at the un-floored rate.\n      this.updatePollingInterval(true);\n      if (this.currentLoopDelayInterrupt) {\n        this.currentLoopDelayInterrupt.abort();\n        this.currentLoopDelayInterrupt = undefined;\n      }\n    }\n  }\n\n  /** Called from observer */\n  private startUpdating(): void {\n    if (this.terminated) return;\n    this.keepRunning = true;\n    if (this.currentLoop === undefined) this.currentLoop = this.mainLoop();\n  }\n\n  /** Called from observer */\n  private stopUpdating(): void {\n    this.keepRunning = false;\n  }\n\n  /** If true, main loop will continue polling pl state. */\n  private keepRunning = false;\n  /** Actual state of main loop. */\n  private currentLoop: Promise<void> | undefined = undefined;\n\n  /** Executed from the main loop, and initialization procedure. */\n  private async refresh(stats?: TreeLoadingStat, txOps?: TxOps): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    try {\n      await this.loadAndApply(stats, txOps);\n    } catch (e) {\n      // Discovery-tree self-heal: a discovered root whose grant was revoked/expired fails the whole\n      // ResourceTree poll with Unauthenticated. Re-discover (drops dead roots) and retry once. This is\n      // self-discriminating — a genuinely dead session also fails discover()'s own call, so real auth\n      // loss still propagates. Only for discovery trees; explicit-root trees propagate as-is.\n      if (this.sharedSeeds.length > 0 && isUnauthenticated(e)) {\n        this.logger?.warn(\n          \"discovery tree: Unauthenticated on ResourceTree (likely revoked/expired root); re-discovering and retrying\",\n        );\n        await this.discover();\n        await this.loadAndApply(stats, txOps);\n      } else throw e;\n    }\n  }\n\n  private async loadAndApply(stats?: TreeLoadingStat, txOps?: TxOps): Promise<void> {\n    const request = constructTreeLoadingRequest(this.state, {\n      pruningFunction: this.pruning,\n      fieldFilter: this.fieldFilter,\n      traverseStopRules: this.traverseStopRules,\n    });\n    // A shared-type-seed tree with no currently-discovered roots is legitimately empty:\n    // there is nothing to traverse, and tx.resourceTree([]) would throw \"at least one seed\n    // must be provided\". Skip the backend load and leave the (empty) state as-is — discovery\n    // adds roots later via setRoots(), which schedules the next refresh. Explicit-root trees\n    // never hit this (their root set is non-empty by construction).\n    if (request.seedResources.length === 0 && request.finalResources.size === 0) return;\n    const data = await this.pl.withReadTx(\n      \"ReadingTree\",\n      async (tx) => {\n        return await loadTreeState(\n          tx,\n          request,\n          stats,\n          this.pl.serverInfo.capabilities ?? [],\n          this.traversalMode,\n          this.logger,\n        );\n      },\n      txOps,\n    );\n    this.state.updateFromResourceData(data, { allowOrphanInputs: true, stat: stats });\n  }\n\n  /** Discovery sync for shared-type seeds: re-polls `ListUserResources` (gRPC-only) and\n   * reconciles the discovered root set against the heap. A longer poll result adds roots; a\n   * shorter one removes them (grant revoked/expired) — the removed roots' subtrees cascade\n   * to collection via the ordinary refcount GC ({@link PlTreeState.setRoots}). No-op when the\n   * tree has no shared-type seeds, or silently no-op on a REST client where `ListUserResources`\n   * is unavailable. */\n  private async discover(): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    if (this.sharedSeeds.length === 0) return;\n\n    const discovered = new Set<SignedResourceId>();\n    for (const seed of this.sharedSeeds) {\n      let ids: SignedResourceId[];\n      try {\n        // match by name only (permissive; ignores version, so it survives schema bumps)\n        ids = await this.pl.userResources.listSharedResourcesByType(seed.resourceType.name);\n      } catch (e: unknown) {\n        if (isUnimplementedError(e)) continue;\n        throw e;\n      }\n      for (const id of ids) discovered.add(id);\n    }\n\n    this.discoveredRoots = [...discovered];\n    this.state.setRoots(this.currentRootSet());\n  }\n\n  /** If true this tree state is permanently terminaed. */\n  private terminated = false;\n\n  private async mainLoop() {\n    // Always collected, even when not logging: the change counters drive the idle backoff\n    // below. Counter bumps are cheap next to the round trip they describe.\n    let stat = initialTreeLoadingStat();\n\n    let lastUpdate = Date.now();\n\n    // paces the discovery poll for shared-type seeds; 0 forces discovery on the first pass.\n    let lastDiscovery = 0;\n\n    while (true) {\n      if (!this.keepRunning || this.terminated) break;\n\n      // saving those who want to be notified about new state here\n      // because those who will be added during the tree retrieval\n      // should be notified only on the next round\n      let toNotify: ScheduledRefresh[] | undefined = undefined;\n      if (this.scheduledOnNextState.length > 0) {\n        toNotify = this.scheduledOnNextState;\n        this.scheduledOnNextState = [];\n      }\n\n      try {\n        // resetting stats if we were asked to collect non-cumulative stats\n        if (this.logStat === \"per-request\") stat = initialTreeLoadingStat();\n\n        // discovery sync for shared-type seeds: reconcile the discovered root set before\n        // refreshing, so newly discovered roots are materialized in this same iteration.\n        if (this.sharedSeeds.length > 0 && Date.now() - lastDiscovery >= DISCOVERY_INTERVAL_MS) {\n          await this.discover();\n          lastDiscovery = Date.now();\n        }\n\n        // Change counters before the refresh, so the delta tells us whether this single cycle\n        // brought anything new. Works in both stat modes: \"per-request\" resets to 0 above.\n        const changesBefore = countedChanges(stat);\n\n        // actual tree synchronization\n        await this.refresh(stat);\n\n        this.updatePollingInterval(countedChanges(stat) > changesBefore);\n\n        // logging stats if we were asked to\n        if (this.logStat && this.logger)\n          this.logger.info(\n            `Tree stat (success, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,\n          );\n        lastUpdate = Date.now();\n\n        // notifying that we got new state\n        if (toNotify !== undefined) for (const n of toNotify) n.resolve();\n      } catch (e: any) {\n        // logging stats if we were asked to (even if error occured)\n        if (this.logStat && this.logger)\n          this.logger.info(\n            `Tree stat (error, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,\n          );\n        lastUpdate = Date.now();\n\n        // notifying that we failed to refresh the state\n        if (toNotify !== undefined) for (const n of toNotify) n.reject(e);\n\n        // catching tree update errors, as they may leave our tree in inconsistent state\n        if (e instanceof TreeStateUpdateError) {\n          // important error logging, this should never happen\n          this.logger?.error(e);\n\n          // marking everybody who used previous state as changed\n          this.state.invalidateTree(\"stat update error\");\n          // creating new tree with the full current root set (re-discovered on next iteration)\n          this.state = new PlTreeState(this.currentRootSet(), this.finalPredicate);\n\n          // scheduling state update without delay\n          continue;\n\n          // unfortunately external observer may still see tree in its default\n          // empty state, though this is best we can do in this exceptional\n          // situation, and hope on caching layers inside computables to present\n          // some stale state until we reconstruct the tree again\n        } else this.logger?.warn(e);\n      }\n\n      if (!this.keepRunning || this.terminated) break;\n\n      // Phase 1: mandatory floor — always wait at least MIN_POLLING_INTERVAL_MS.\n      // Not interruptible by scheduleOnNextState; only termination aborts it.\n      try {\n        await tp.setTimeout(MIN_POLLING_INTERVAL_MS, undefined, {\n          signal: this.abortController.signal,\n        });\n      } catch (e: unknown) {\n        if (!isTimeoutOrCancelError(e)) throw new Error(\"Unexpected error\", { cause: e });\n        if (this.abortController.signal.aborted) break;\n      }\n\n      if (!this.keepRunning || this.terminated) break;\n\n      // Phase 2: optional remainder up to pollingInterval — interruptible by\n      // scheduleOnNextState so that an external nudge wakes the loop promptly.\n      if (this.scheduledOnNextState.length === 0) {\n        const remaining = Math.max(0, this.effectivePollingInterval - MIN_POLLING_INTERVAL_MS);\n        if (remaining > 0) {\n          try {\n            this.currentLoopDelayInterrupt = new AbortController();\n            await tp.setTimeout(remaining, undefined, {\n              signal: AbortSignal.any([\n                this.abortController.signal,\n                this.currentLoopDelayInterrupt.signal,\n              ]),\n            });\n          } catch (e: unknown) {\n            if (!isTimeoutOrCancelError(e)) throw new Error(\"Unexpected error\", { cause: e });\n            if (this.abortController.signal.aborted) break;\n            // Otherwise it was just the loop delay interrupt (scheduleOnNextState),\n            // continue to the next iteration\n          } finally {\n            this.currentLoopDelayInterrupt = undefined;\n          }\n        }\n      }\n    }\n\n    // reset only as a very last line\n    this.currentLoop = undefined;\n  }\n\n  /**\n   * Dumps the current state of the tree.\n   * @returns An array of ExtendedResourceData objects representing the current state of the tree.\n   */\n  public dumpState(): ExtendedResourceData[] {\n    return this.state.dumpState();\n  }\n\n  /**\n   * Terminates the internal loop, and permanently destoys all internal state, so\n   * all computables using this state will resolve to errors.\n   * */\n  public async terminate(): Promise<void> {\n    this.keepRunning = false;\n    this.terminated = true;\n    this.abortController.abort();\n\n    if (this.currentLoop === undefined) return;\n    await this.currentLoop;\n\n    this.state.invalidateTree(\"synchronization terminated for the tree\");\n  }\n\n  /** @deprecated */\n  public async awaitSyncLoopTermination(): Promise<void> {\n    if (this.currentLoop === undefined) return;\n    await this.currentLoop;\n  }\n\n  /**\n   * Initializes a synchronized tree from one or more seeds.\n   *\n   * @param seeds a bare {@link SignedResourceId} (the original single-root contract), a\n   *   single {@link TreeSeed}, or an array of seeds. Bare ids and explicit-resource seeds\n   *   become roots immediately; shared-type seeds discover their roots via `ListUserResources`.\n   */\n  public static async init(\n    pl: PlClient,\n    seeds: SignedResourceId | TreeSeed | TreeSeed[],\n    ops: SynchronizedTreeOps,\n    logger?: MiLogger,\n  ) {\n    const tree = new SynchronizedTreeState(pl, normalizeSeeds(seeds), ops, logger);\n\n    const stat = ops.logStat ? initialTreeLoadingStat() : undefined;\n\n    let ok = false;\n\n    try {\n      // resolve shared-type seeds before the first refresh so discovered roots load now\n      await tree.discover();\n      await tree.refresh(stat, {\n        timeout: ops.initialTreeLoadingTimeout,\n      });\n      ok = true;\n    } finally {\n      // logging stats if we were asked to (even if error occured)\n      if (stat && logger)\n        logger.info(\n          `Tree stat (initial load, ${ok ? \"success\" : \"failure\"}): ${JSON.stringify(stat)}`,\n        );\n    }\n\n    return tree;\n  }\n}\n"],"mappings":"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"}

package/dist/synchronized_tree.d.ts

@@ -30,6 +30,18 @@ type SharedTypeSeed = {
   resourceType: ResourceType;
 };
 type TreeSeed = ExplicitRootSeed | SharedTypeSeed;
+/** The poll-cadence policy, as a pure function of the last cycle's outcome.
+ *
+ * `configuredMs` is the tree's static `pollingInterval` and acts as the lower bound, so no
+ * link can be polled faster than configured. `rttMs` raises that bound on a slow link.
+ * `currentMs` is the interval in force for the cycle that just finished, which is what the
+ * idle backoff compounds on. */
+declare function derivePollingInterval(opts: {
+  configuredMs: number;
+  currentMs: number;
+  rttMs: number | undefined;
+  changed: boolean;
+}): number;
 declare class SynchronizedTreeState {
   private readonly pl;
   private readonly logger?;
@@ -69,6 +81,17 @@ declare class SynchronizedTreeState {
   refreshState(): Promise<void>;
   private currentLoopDelayInterrupt;
   private scheduledOnNextState;
+  /** Interval actually used for the current wait. Starts at the configured `pollingInterval`
+   * and is re-derived after every cycle by {@link updatePollingInterval}. */
+  private effectivePollingInterval;
+  /** Re-derives {@link effectivePollingInterval} after a cycle.
+   *
+   * Two independent effects. The floor scales with the client's measured RTT, so a
+   * high-latency link stops queueing round-trips it cannot service. On top of that, a cycle
+   * that changed nothing multiplies the interval out towards
+   * {@link MAX_POLLING_INTERVAL_MS}, while any change snaps it straight back to the floor so
+   * an active tree stays responsive. */
+  private updatePollingInterval;
   /** Called from computable hooks when external observer asks for state refresh */
   private scheduleOnNextState;
   /** Called from observer */
@@ -114,5 +137,5 @@ declare class SynchronizedTreeState {
   static init(pl: PlClient, seeds: SignedResourceId | TreeSeed | TreeSeed[], ops: SynchronizedTreeOps, logger?: MiLogger): Promise<SynchronizedTreeState>;
 }
 //#endregion
-export { ExplicitRootSeed, SharedTypeSeed, SynchronizedTreeOps, SynchronizedTreeState, TreeSeed };
+export { ExplicitRootSeed, SharedTypeSeed, SynchronizedTreeOps, SynchronizedTreeState, TreeSeed, derivePollingInterval };
 //# sourceMappingURL=synchronized_tree.d.ts.map

package/dist/synchronized_tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"synchronized_tree.d.ts","names":[],"sources":["../src/synchronized_tree.ts"],"mappings":";;;;;;;KA2BK,eAAA;AAAA,KAEO,mBAAA;EAFQ,iDAIlB,sBAAA,GAAyB,0BAAA,EAJP;EAOlB,OAAA,GAAU,eAAA,EALA;EAQV,WAAA,GAAc,MAAA;EAGd,iBAAA,GAAoB,MAAA,EANV;EASV,eAAA,UAHoB;EAKpB,gBAAA,UASgB;EANhB,OAAA,GAAU,eAAA,EAMmB;EAH7B,yBAAA,WApByB;EAuBzB,aAAA,GAAgB,aAAA;AAAA;;KAIN,gBAAA;EAAqB,IAAA;EAAkB,IAAA,EAAM,gBAAgB;AAAA;;;;KAK7D,cAAA;EAAmB,IAAA;EAAgB,YAAA,EAAc,YAAY;AAAA;AAAA,KAE7D,QAAA,GAAW,gBAAA,GAAmB,cAAc;AAAA,cA+B3C,qBAAA;EAAA,iBAoBQ,EAAA;EAAA,iBAGA,MAAA;EAAA,iBAtBF,cAAA;EAAA,QACT,KAAA;EAAA,iBACS,eAAA;EAAA,iBACA,OAAA;EAAA,iBACA,WAAA;EAAA,iBACA,iBAAA;EAAA,iBACA,aAAA;EAAA,iBACA,OAAA;EAAA,iBACA,KAAA;EAAA,iBACA,eAAA;EA3CY;EAAA,iBA8CZ,aAAA;EA9C0C;EAAA,iBAgD1C,WAAA;EAhDsD;EAAA,QAkD/D,eAAA;EAAA,QAED,WAAA;;UAuCC,cAAA;EAzF8C;AA+BxD;EA/BwD,QA+F9C,QAAA;;EAUD,QAAA,CAAS,GAAA,GAAM,gBAAA,GAAmB,WAAA;EAAA;;;EAQlC,KAAA,CAAM,GAAA,GAAM,gBAAA,GAAmB,WAAA;EAiBT;;EAPtB,UAAA,IAAc,gBAAA;EA0QoB;;EAnQ5B,YAAA,IAAgB,OAAA;EAAA,QAKrB,yBAAA;EAAA,QACA,oBAAA;EA4QD;EAAA,QAzQC,mBAAA;EA0QW;EAAA,QA9PX,aAAA;EA8PW;EAAA,QAvPX,YAAA;EA3GW;EAAA,QAgHX,WAAA;EAnIS;EAAA,QAqIT,WAAA;EAnIS;EAAA,QAsIH,OAAA;EAAA,QAmBA,YAAA;EAtJG;;;;;;EAAA,QAyLH,QAAA;EA9KN;EAAA,QAoMA,UAAA;EAAA,QAEM,QAAA;EAvJN;;;;EAkRD,SAAA,IAAa,oBAAA;EAhQb;;;;EAwQM,SAAA,IAAa,OAAA;EA9PL;EA0QR,wBAAA,IAA4B,OAAA;EAnQZ;;;;;;;EAAA,OA+QT,IAAA,CAClB,EAAA,EAAI,QAAA,EACJ,KAAA,EAAO,gBAAA,GAAmB,QAAA,GAAW,QAAA,IACrC,GAAA,EAAK,mBAAA,EACL,MAAA,GAAS,QAAA,GAAQ,OAAA,CAAA,qBAAA;AAAA"}
+{"version":3,"file":"synchronized_tree.d.ts","names":[],"sources":["../src/synchronized_tree.ts"],"mappings":";;;;;;;KAgDK,eAAA;AAAA,KAEO,mBAAA;EAFQ,iDAIlB,sBAAA,GAAyB,0BAAA,EAJP;EAOlB,OAAA,GAAU,eAAA,EALA;EAQV,WAAA,GAAc,MAAA;EAGd,iBAAA,GAAoB,MAAA,EANV;EASV,eAAA,UAHoB;EAKpB,gBAAA,UASgB;EANhB,OAAA,GAAU,eAAA,EAMmB;EAH7B,yBAAA,WApByB;EAuBzB,aAAA,GAAgB,aAAA;AAAA;;KAIN,gBAAA;EAAqB,IAAA;EAAkB,IAAA,EAAM,gBAAgB;AAAA;;;;KAK7D,cAAA;EAAmB,IAAA;EAAgB,YAAA,EAAc,YAAY;AAAA;AAAA,KAE7D,QAAA,GAAW,gBAAA,GAAmB,cAAc;AAPxD;;;;;;AAAA,iBAgDgB,qBAAA,CAAsB,IAAA;EACpC,YAAA;EACA,SAAA;EACA,KAAA;EACA,OAAA;AAAA;AAAA,cA0BW,qBAAA;EAAA,iBAoBQ,EAAA;EAAA,iBAGA,MAAA;EAAA,iBAtBF,cAAA;EAAA,QACT,KAAA;EAAA,iBACS,eAAA;EAAA,iBACA,OAAA;EAAA,iBACA,WAAA;EAAA,iBACA,iBAAA;EAAA,iBACA,aAAA;EAAA,iBACA,OAAA;EAAA,iBACA,KAAA;EAAA,iBACA,eAAA;;mBAGA,aAAA;EA1CjB;EAAA,iBA4CiB,WAAA;EA1CjB;EAAA,QA4CQ,eAAA;EAAA,QAED,WAAA;EA5CR;EAAA,QAoFS,cAAA;EA3DG;;EAAA,QAiEH,QAAA;EAUc;EAAf,QAAA,CAAS,GAAA,GAAM,gBAAA,GAAmB,WAAA;EAQtB;;;EAAZ,KAAA,CAAM,GAAA,GAAM,gBAAA,GAAmB,WAAA;EAmSlB;;EAzRb,UAAA,IAAc,gBAAA;EA0Tf;;EAnTO,YAAA,IAAgB,OAAA;EAAA,QAKrB,yBAAA;EAAA,QACA,oBAAA;EAgTG;;EAAA,QA5SH,wBAAA;EA4SW;;;;;;;EAAA,QAnSX,qBAAA;EAlHS;EAAA,QA4HT,mBAAA;EA1HS;EAAA,QA8IT,aAAA;EA5IS;EAAA,QAmJT,YAAA;EA/IS;EAAA,QAoJT,WAAA;EAhJA;EAAA,QAkJA,WAAA;EAxGA;EAAA,QA2GM,OAAA;EAAA,QAmBA,YAAA;EA9GQ;;;;;;EAAA,QAiJR,QAAA;EA/HP;EAAA,QAqJC,UAAA;EAAA,QAEM,QAAA;EAhJe;;;;EAkRtB,SAAA,IAAa,oBAAA;EArPZ;;;;EA6PK,SAAA,IAAa,OAAA;EAxNZ;EAoOD,wBAAA,IAA4B,OAAA;EA9K3B;;;;;;;EAAA,OA0LM,IAAA,CAClB,EAAA,EAAI,QAAA,EACJ,KAAA,EAAO,gBAAA,GAAmB,QAAA,GAAW,QAAA,IACrC,GAAA,EAAK,mBAAA,EACL,MAAA,GAAS,QAAA,GAAQ,OAAA,CAAA,qBAAA;AAAA"}

package/dist/synchronized_tree.js

@@ -9,6 +9,23 @@ import * as tp from "node:timers/promises";
 * Applies even when {@link scheduleOnNextState} has woken the loop early,
 * preventing tight polling loops during rapid state transitions. */
 const MIN_POLLING_INTERVAL_MS = 100;
+/** Ceiling for the adaptive poll interval. Caps how stale an idle tree can get before the
+* next look, and bounds how far the idle backoff can push the interval out. */
+const MAX_POLLING_INTERVAL_MS = 5e3;
+/** Applied to the interval after a cycle that changed nothing. An idle tree walks its
+* interval out towards {@link MAX_POLLING_INTERVAL_MS} instead of re-polling at full rate;
+* the first cycle that changes anything resets it. */
+const IDLE_BACKOFF_MULTIPLIER = 1.5;
+/** The client's measured RTT becomes an interval floor, scaled by this. Every refresh costs
+* at least one round trip, so polling faster than a small multiple of the RTT only queues
+* round-trips the link cannot service. This is what replaces the fixed interval on a
+* high-latency link; on a fast link the configured `pollingInterval` still dominates. */
+const RTT_POLL_FACTOR = 2;
+/** Ceiling for the RTT-derived floor. The estimate is sampled at connect time and never
+* re-sampled, so without a bound one slow ping pins the cadence high for the whole session.
+* Mirrors `MAX_ADAPTIVE_REQUEST_TIMEOUT` on the deadline side: past this the link is stuck
+* rather than slow, and spacing polls further only delays noticing it recovered. */
+const MAX_RTT_POLL_INTERVAL_MS = 3e4;
 /** Normalizes the {@link SynchronizedTreeState.init} seed argument — a bare
 * {@link SignedResourceId}, a single {@link TreeSeed}, or an array — to `TreeSeed[]`, so
 * every existing single-root caller is unchanged. */
@@ -20,19 +37,39 @@ function normalizeSeeds(seeds) {
 		root: seeds
 	}];
 }
-/** How often, in main-loop iterations, a tree with shared-type seeds re-polls
-* ListUserResources to reconcile its discovered roots. 1 would mean every iteration.
+/** How often a tree with shared-type seeds re-polls ListUserResources to reconcile its
+* discovered roots.
 *
 * Discovery (a full ListUserResources stream) is far heavier than an ordinary incremental
-* refresh, so it must NOT run on every fast refresh tick. The refresh cadence is the tree's
-* `pollingInterval` floored by {@link MIN_POLLING_INTERVAL_MS} (~200ms-1s in practice — the
-* shared-seed discovery tree runs at the 200ms default). At N = 15 discovery fires roughly
-* every 15 × 200ms ≈ 3s, decoupling it from the fast refresh loop while keeping the latency
-* of noticing a new/removed share to a few seconds — acceptable for a human-driven share flow.
+* refresh, so it must NOT run on every refresh tick. This is a wall-clock interval rather
+* than a count of iterations: the refresh cadence is adaptive (it stretches towards
+* {@link MAX_POLLING_INTERVAL_MS} on an idle tree and scales with RTT on a slow link),
+* so a fixed iteration count would let discovery latency drift out with it. Keeping it in
+* milliseconds pins the latency of noticing a new/removed share regardless of cadence, which
+* is what a human-driven share flow cares about.
 *
 * Only trees with shared-type seeds gate on this; {@link discover} is a no-op for single-root
 * and explicit-seed trees (empty `sharedSeeds`), so the value never affects them. */
-const DISCOVERY_EVERY_N_REFRESHES = 15;
+const DISCOVERY_INTERVAL_MS = 3e3;
+/** Counters that mean "this cycle brought something new". Deliberately not the full change
+* breakdown: those fields are sub-counts of `resourcesChanged` and would double-count.
+* `resourcesUnchanged` is excluded by design, since a cycle that only re-fetched unchanged
+* state is exactly the idle case the backoff exists for. */
+function countedChanges(stat) {
+	return stat.resourcesNew + stat.resourcesChanged + stat.resourcesMarkedFinal;
+}
+/** The poll-cadence policy, as a pure function of the last cycle's outcome.
+*
+* `configuredMs` is the tree's static `pollingInterval` and acts as the lower bound, so no
+* link can be polled faster than configured. `rttMs` raises that bound on a slow link.
+* `currentMs` is the interval in force for the cycle that just finished, which is what the
+* idle backoff compounds on. */
+function derivePollingInterval(opts) {
+	const { configuredMs, currentMs, rttMs, changed } = opts;
+	const floor = rttMs === void 0 ? configuredMs : Math.max(configuredMs, Math.min(MAX_RTT_POLL_INTERVAL_MS, Math.ceil(rttMs * RTT_POLL_FACTOR)));
+	const next = changed ? floor : Math.max(floor, currentMs * IDLE_BACKOFF_MULTIPLIER);
+	return Math.max(floor, Math.min(MAX_POLLING_INTERVAL_MS, next));
+}
 var SynchronizedTreeState = class SynchronizedTreeState {
 	pl;
 	logger;
@@ -61,6 +98,7 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 		this.traverseStopRules = traverseStopRules;
 		this.traversalMode = traversalMode ?? "auto";
 		this.pollingInterval = pollingInterval;
+		this.effectivePollingInterval = pollingInterval;
 		this.finalPredicate = finalPredicateOverride ?? pl.finalPredicate;
 		this.logStat = logStat;
 		this.explicitRoots = seeds.filter((s) => s.kind === "resource").map((s) => s.root);
@@ -111,6 +149,24 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 	}
 	currentLoopDelayInterrupt = void 0;
 	scheduledOnNextState = [];
+	/** Interval actually used for the current wait. Starts at the configured `pollingInterval`
+	* and is re-derived after every cycle by {@link updatePollingInterval}. */
+	effectivePollingInterval;
+	/** Re-derives {@link effectivePollingInterval} after a cycle.
+	*
+	* Two independent effects. The floor scales with the client's measured RTT, so a
+	* high-latency link stops queueing round-trips it cannot service. On top of that, a cycle
+	* that changed nothing multiplies the interval out towards
+	* {@link MAX_POLLING_INTERVAL_MS}, while any change snaps it straight back to the floor so
+	* an active tree stays responsive. */
+	updatePollingInterval(changed) {
+		this.effectivePollingInterval = derivePollingInterval({
+			configuredMs: this.pollingInterval,
+			currentMs: this.effectivePollingInterval,
+			rttMs: this.pl.rttEstimateMs,
+			changed
+		});
+	}
 	/** Called from computable hooks when external observer asks for state refresh */
 	scheduleOnNextState(resolve, reject) {
 		if (this.terminated) reject(/* @__PURE__ */ new Error("tree synchronization is terminated"));
@@ -119,6 +175,7 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 				resolve,
 				reject
 			});
+			this.updatePollingInterval(true);
 			if (this.currentLoopDelayInterrupt) {
 				this.currentLoopDelayInterrupt.abort();
 				this.currentLoopDelayInterrupt = void 0;
@@ -193,9 +250,9 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 	/** If true this tree state is permanently terminaed. */
 	terminated = false;
 	async mainLoop() {
-		let stat = this.logStat ? initialTreeLoadingStat() : void 0;
+		let stat = initialTreeLoadingStat();
 		let lastUpdate = Date.now();
-		let iteration = 0;
+		let lastDiscovery = 0;
 		while (true) {
 			if (!this.keepRunning || this.terminated) break;
 			let toNotify = void 0;
@@ -205,14 +262,18 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 			}
 			try {
 				if (this.logStat === "per-request") stat = initialTreeLoadingStat();
-				if (this.sharedSeeds.length > 0 && iteration % DISCOVERY_EVERY_N_REFRESHES === 0) await this.discover();
-				iteration++;
+				if (this.sharedSeeds.length > 0 && Date.now() - lastDiscovery >= DISCOVERY_INTERVAL_MS) {
+					await this.discover();
+					lastDiscovery = Date.now();
+				}
+				const changesBefore = countedChanges(stat);
 				await this.refresh(stat);
-				if (stat && this.logger) this.logger.info(`Tree stat (success, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`);
+				this.updatePollingInterval(countedChanges(stat) > changesBefore);
+				if (this.logStat && this.logger) this.logger.info(`Tree stat (success, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`);
 				lastUpdate = Date.now();
 				if (toNotify !== void 0) for (const n of toNotify) n.resolve();
 			} catch (e) {
-				if (stat && this.logger) this.logger.info(`Tree stat (error, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`);
+				if (this.logStat && this.logger) this.logger.info(`Tree stat (error, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`);
 				lastUpdate = Date.now();
 				if (toNotify !== void 0) for (const n of toNotify) n.reject(e);
 				if (e instanceof TreeStateUpdateError) {
@@ -231,7 +292,7 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 			}
 			if (!this.keepRunning || this.terminated) break;
 			if (this.scheduledOnNextState.length === 0) {
-				const remaining = Math.max(0, this.pollingInterval - MIN_POLLING_INTERVAL_MS);
+				const remaining = Math.max(0, this.effectivePollingInterval - MIN_POLLING_INTERVAL_MS);
 				if (remaining > 0) try {
 					this.currentLoopDelayInterrupt = new AbortController();
 					await tp.setTimeout(remaining, void 0, { signal: AbortSignal.any([this.abortController.signal, this.currentLoopDelayInterrupt.signal]) });
@@ -291,6 +352,6 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 	}
 };
 //#endregion
-export { SynchronizedTreeState };
+export { SynchronizedTreeState, derivePollingInterval };
 
 //# sourceMappingURL=synchronized_tree.js.map

package/dist/synchronized_tree.js.map

@@ -1 +1 @@
-{"version":3,"file":"synchronized_tree.js","names":[],"sources":["../src/synchronized_tree.ts"],"sourcesContent":["import { PollingComputableHooks } from \"@milaboratories/computable\";\nimport { PlTreeEntry, PlTreeRootsEntry } from \"./accessors\";\nimport type {\n  FinalResourceDataPredicate,\n  PlClient,\n  ResourceType,\n  SignedResourceId,\n  TxOps,\n} from \"@milaboratories/pl-client\";\nimport type { Filter } from \"@milaboratories/pl-client\";\nimport {\n  isUnauthenticated,\n  isTimeoutOrCancelError,\n  isUnimplementedError,\n} from \"@milaboratories/pl-client\";\nimport type { ExtendedResourceData } from \"./state\";\nimport { PlTreeState, TreeStateUpdateError } from \"./state\";\nimport type { PruningFunction, TraversalMode, TreeLoadingStat } from \"./sync\";\nimport { constructTreeLoadingRequest, initialTreeLoadingStat, loadTreeState } from \"./sync\";\nimport * as tp from \"node:timers/promises\";\nimport type { MiLogger } from \"@milaboratories/ts-helpers\";\n\n/** Hard floor between consecutive tree-refresh calls.\n * Applies even when {@link scheduleOnNextState} has woken the loop early,\n * preventing tight polling loops during rapid state transitions. */\nconst MIN_POLLING_INTERVAL_MS = 100;\n\ntype StatLoggingMode = \"cumulative\" | \"per-request\";\n\nexport type SynchronizedTreeOps = {\n  /** Override final predicate from the PlClient */\n  finalPredicateOverride?: FinalResourceDataPredicate;\n\n  /** Pruning function for legacy fallback path. */\n  pruning?: PruningFunction;\n\n  /** ResourceTree field filter for modern backend path. */\n  fieldFilter?: Filter;\n\n  /** ResourceTree traversal stop rules for modern backend path. */\n  traverseStopRules?: Filter;\n\n  /** Interval after last sync to sleep before the next one */\n  pollingInterval: number;\n  /** For how long to continue polling after the last derived value access */\n  stopPollingDelay: number;\n\n  /** If one of the values, tree will log stats of each polling request */\n  logStat?: StatLoggingMode;\n\n  /** Timeout for initial tree loading. If not specified, will use default for RO tx from pl-client. */\n  initialTreeLoadingTimeout?: number;\n\n  /** Controls which tree-loading path to use.  Default `\"auto\"`. */\n  traversalMode?: TraversalMode;\n};\n\n/** An explicit resource to serve as a tree root. Several explicit seeds may be passed. */\nexport type ExplicitRootSeed = { kind: \"resource\"; root: SignedResourceId };\n\n/** Discovers, as roots, every resource of this type shared with the current user.\n *  Matched against SharedResource.resourceType by NAME (version optional/ignored). The\n *  discovered set is DYNAMIC — roots appear/disappear as grants are added/revoked/expire. */\nexport type SharedTypeSeed = { kind: \"shared\"; resourceType: ResourceType };\n\nexport type TreeSeed = ExplicitRootSeed | SharedTypeSeed;\n\n/** Normalizes the {@link SynchronizedTreeState.init} seed argument — a bare\n * {@link SignedResourceId}, a single {@link TreeSeed}, or an array — to `TreeSeed[]`, so\n * every existing single-root caller is unchanged. */\nfunction normalizeSeeds(seeds: SignedResourceId | TreeSeed | TreeSeed[]): TreeSeed[] {\n  if (Array.isArray(seeds)) return seeds;\n  if (typeof seeds === \"object\" && seeds !== null && \"kind\" in seeds) return [seeds];\n  // bare SignedResourceId\n  return [{ kind: \"resource\", root: seeds }];\n}\n\n/** How often, in main-loop iterations, a tree with shared-type seeds re-polls\n * ListUserResources to reconcile its discovered roots. 1 would mean every iteration.\n *\n * Discovery (a full ListUserResources stream) is far heavier than an ordinary incremental\n * refresh, so it must NOT run on every fast refresh tick. The refresh cadence is the tree's\n * `pollingInterval` floored by {@link MIN_POLLING_INTERVAL_MS} (~200ms-1s in practice — the\n * shared-seed discovery tree runs at the 200ms default). At N = 15 discovery fires roughly\n * every 15 × 200ms ≈ 3s, decoupling it from the fast refresh loop while keeping the latency\n * of noticing a new/removed share to a few seconds — acceptable for a human-driven share flow.\n *\n * Only trees with shared-type seeds gate on this; {@link discover} is a no-op for single-root\n * and explicit-seed trees (empty `sharedSeeds`), so the value never affects them. */\nconst DISCOVERY_EVERY_N_REFRESHES = 15;\n\ntype ScheduledRefresh = {\n  resolve: () => void;\n  reject: (err: any) => void;\n};\n\nexport class SynchronizedTreeState {\n  private readonly finalPredicate: FinalResourceDataPredicate;\n  private state: PlTreeState;\n  private readonly pollingInterval: number;\n  private readonly pruning?: PruningFunction;\n  private readonly fieldFilter?: Filter;\n  private readonly traverseStopRules?: Filter;\n  private readonly traversalMode: TraversalMode;\n  private readonly logStat?: StatLoggingMode;\n  private readonly hooks: PollingComputableHooks;\n  private readonly abortController = new AbortController();\n\n  /** Explicit-resource seeds: fixed roots, present from construction. */\n  private readonly explicitRoots: SignedResourceId[];\n  /** Shared-type seeds (discovered roots), if any. */\n  private readonly sharedSeeds: SharedTypeSeed[];\n  /** Roots discovered for shared-type seeds on the last discovery poll. */\n  private discoveredRoots: SignedResourceId[] = [];\n\n  private constructor(\n    private readonly pl: PlClient,\n    seeds: TreeSeed[],\n    ops: SynchronizedTreeOps,\n    private readonly logger?: MiLogger,\n  ) {\n    const {\n      finalPredicateOverride,\n      pruning,\n      fieldFilter,\n      traverseStopRules,\n      traversalMode,\n      pollingInterval,\n      stopPollingDelay,\n      logStat,\n    } = ops;\n    this.pruning = pruning;\n    this.fieldFilter = fieldFilter;\n    this.traverseStopRules = traverseStopRules;\n    this.traversalMode = traversalMode ?? \"auto\";\n    this.pollingInterval = pollingInterval;\n    this.finalPredicate = finalPredicateOverride ?? pl.finalPredicate;\n    this.logStat = logStat;\n\n    this.explicitRoots = seeds\n      .filter((s): s is ExplicitRootSeed => s.kind === \"resource\")\n      .map((s) => s.root);\n    this.sharedSeeds = seeds.filter((s): s is SharedTypeSeed => s.kind === \"shared\");\n\n    this.state = new PlTreeState(this.currentRootSet(), this.finalPredicate);\n    this.hooks = new PollingComputableHooks(\n      () => this.startUpdating(),\n      () => this.stopUpdating(),\n      { stopDebounce: stopPollingDelay },\n      (resolve, reject) => this.scheduleOnNextState(resolve, reject),\n    );\n  }\n\n  /** The current protected root set: explicit roots plus the latest discovered roots. */\n  private currentRootSet(): Set<SignedResourceId> {\n    return new Set([...this.explicitRoots, ...this.discoveredRoots]);\n  }\n\n  /** Resolves the single root for the backward-compatible single-root accessors, throwing\n   * if the tree does not have exactly one root (guards legacy callers against multi-root). */\n  private soleRoot(): SignedResourceId {\n    const roots = this.currentRootSet();\n    if (roots.size !== 1)\n      throw new Error(\n        `single-root accessor used on a tree with ${roots.size} roots; use rootsEntry() instead`,\n      );\n    return roots.values().next().value!;\n  }\n\n  /** @deprecated use \"entry\" instead */\n  public accessor(rid?: SignedResourceId): PlTreeEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return this.entry(rid);\n  }\n\n  /** Backward-compatible single-root entry. With no `rid` it returns the sole root's entry\n   * and THROWS if the tree has zero or more than one root. An explicit `rid` addresses any\n   * resource in the heap, as today. */\n  public entry(rid?: SignedResourceId): PlTreeEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return new PlTreeEntry(\n      { treeProvider: () => this.state, hooks: this.hooks },\n      rid ?? this.soleRoot(),\n    );\n  }\n\n  /** Reactive provider for the current root SET. Reading it inside a Computable tracks the\n   * set as a dependency, so the Computable recomputes when discovered roots appear/disappear. */\n  public rootsEntry(): PlTreeRootsEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return new PlTreeRootsEntry({ treeProvider: () => this.state, hooks: this.hooks });\n  }\n\n  /** Can be used to externally kick off the synchronization polling loop, and\n   * await for the first synchronization to happen. */\n  public async refreshState(): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    await this.hooks.refreshState();\n  }\n\n  private currentLoopDelayInterrupt: AbortController | undefined = undefined;\n  private scheduledOnNextState: ScheduledRefresh[] = [];\n\n  /** Called from computable hooks when external observer asks for state refresh */\n  private scheduleOnNextState(resolve: () => void, reject: (err: any) => void): void {\n    if (this.terminated) reject(new Error(\"tree synchronization is terminated\"));\n    else {\n      this.scheduledOnNextState.push({ resolve, reject });\n      if (this.currentLoopDelayInterrupt) {\n        this.currentLoopDelayInterrupt.abort();\n        this.currentLoopDelayInterrupt = undefined;\n      }\n    }\n  }\n\n  /** Called from observer */\n  private startUpdating(): void {\n    if (this.terminated) return;\n    this.keepRunning = true;\n    if (this.currentLoop === undefined) this.currentLoop = this.mainLoop();\n  }\n\n  /** Called from observer */\n  private stopUpdating(): void {\n    this.keepRunning = false;\n  }\n\n  /** If true, main loop will continue polling pl state. */\n  private keepRunning = false;\n  /** Actual state of main loop. */\n  private currentLoop: Promise<void> | undefined = undefined;\n\n  /** Executed from the main loop, and initialization procedure. */\n  private async refresh(stats?: TreeLoadingStat, txOps?: TxOps): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    try {\n      await this.loadAndApply(stats, txOps);\n    } catch (e) {\n      // Discovery-tree self-heal: a discovered root whose grant was revoked/expired fails the whole\n      // ResourceTree poll with Unauthenticated. Re-discover (drops dead roots) and retry once. This is\n      // self-discriminating — a genuinely dead session also fails discover()'s own call, so real auth\n      // loss still propagates. Only for discovery trees; explicit-root trees propagate as-is.\n      if (this.sharedSeeds.length > 0 && isUnauthenticated(e)) {\n        this.logger?.warn(\n          \"discovery tree: Unauthenticated on ResourceTree (likely revoked/expired root); re-discovering and retrying\",\n        );\n        await this.discover();\n        await this.loadAndApply(stats, txOps);\n      } else throw e;\n    }\n  }\n\n  private async loadAndApply(stats?: TreeLoadingStat, txOps?: TxOps): Promise<void> {\n    const request = constructTreeLoadingRequest(this.state, {\n      pruningFunction: this.pruning,\n      fieldFilter: this.fieldFilter,\n      traverseStopRules: this.traverseStopRules,\n    });\n    // A shared-type-seed tree with no currently-discovered roots is legitimately empty:\n    // there is nothing to traverse, and tx.resourceTree([]) would throw \"at least one seed\n    // must be provided\". Skip the backend load and leave the (empty) state as-is — discovery\n    // adds roots later via setRoots(), which schedules the next refresh. Explicit-root trees\n    // never hit this (their root set is non-empty by construction).\n    if (request.seedResources.length === 0 && request.finalResources.size === 0) return;\n    const data = await this.pl.withReadTx(\n      \"ReadingTree\",\n      async (tx) => {\n        return await loadTreeState(\n          tx,\n          request,\n          stats,\n          this.pl.serverInfo.capabilities ?? [],\n          this.traversalMode,\n          this.logger,\n        );\n      },\n      txOps,\n    );\n    this.state.updateFromResourceData(data, { allowOrphanInputs: true, stat: stats });\n  }\n\n  /** Discovery sync for shared-type seeds: re-polls `ListUserResources` (gRPC-only) and\n   * reconciles the discovered root set against the heap. A longer poll result adds roots; a\n   * shorter one removes them (grant revoked/expired) — the removed roots' subtrees cascade\n   * to collection via the ordinary refcount GC ({@link PlTreeState.setRoots}). No-op when the\n   * tree has no shared-type seeds, or silently no-op on a REST client where `ListUserResources`\n   * is unavailable. */\n  private async discover(): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    if (this.sharedSeeds.length === 0) return;\n\n    const discovered = new Set<SignedResourceId>();\n    for (const seed of this.sharedSeeds) {\n      let ids: SignedResourceId[];\n      try {\n        // match by name only (permissive; ignores version, so it survives schema bumps)\n        ids = await this.pl.userResources.listSharedResourcesByType(seed.resourceType.name);\n      } catch (e: unknown) {\n        if (isUnimplementedError(e)) continue;\n        throw e;\n      }\n      for (const id of ids) discovered.add(id);\n    }\n\n    this.discoveredRoots = [...discovered];\n    this.state.setRoots(this.currentRootSet());\n  }\n\n  /** If true this tree state is permanently terminaed. */\n  private terminated = false;\n\n  private async mainLoop() {\n    // will hold request stats\n    let stat = this.logStat ? initialTreeLoadingStat() : undefined;\n\n    let lastUpdate = Date.now();\n\n    // counts refresh iterations to pace the discovery poll for shared-type seeds.\n    let iteration = 0;\n\n    while (true) {\n      if (!this.keepRunning || this.terminated) break;\n\n      // saving those who want to be notified about new state here\n      // because those who will be added during the tree retrieval\n      // should be notified only on the next round\n      let toNotify: ScheduledRefresh[] | undefined = undefined;\n      if (this.scheduledOnNextState.length > 0) {\n        toNotify = this.scheduledOnNextState;\n        this.scheduledOnNextState = [];\n      }\n\n      try {\n        // resetting stats if we were asked to collect non-cumulative stats\n        if (this.logStat === \"per-request\") stat = initialTreeLoadingStat();\n\n        // discovery sync for shared-type seeds: reconcile the discovered root set before\n        // refreshing, so newly discovered roots are materialized in this same iteration.\n        if (this.sharedSeeds.length > 0 && iteration % DISCOVERY_EVERY_N_REFRESHES === 0) {\n          await this.discover();\n        }\n        iteration++;\n\n        // actual tree synchronization\n        await this.refresh(stat);\n\n        // logging stats if we were asked to\n        if (stat && this.logger)\n          this.logger.info(\n            `Tree stat (success, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,\n          );\n        lastUpdate = Date.now();\n\n        // notifying that we got new state\n        if (toNotify !== undefined) for (const n of toNotify) n.resolve();\n      } catch (e: any) {\n        // logging stats if we were asked to (even if error occured)\n        if (stat && this.logger)\n          this.logger.info(\n            `Tree stat (error, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,\n          );\n        lastUpdate = Date.now();\n\n        // notifying that we failed to refresh the state\n        if (toNotify !== undefined) for (const n of toNotify) n.reject(e);\n\n        // catching tree update errors, as they may leave our tree in inconsistent state\n        if (e instanceof TreeStateUpdateError) {\n          // important error logging, this should never happen\n          this.logger?.error(e);\n\n          // marking everybody who used previous state as changed\n          this.state.invalidateTree(\"stat update error\");\n          // creating new tree with the full current root set (re-discovered on next iteration)\n          this.state = new PlTreeState(this.currentRootSet(), this.finalPredicate);\n\n          // scheduling state update without delay\n          continue;\n\n          // unfortunately external observer may still see tree in its default\n          // empty state, though this is best we can do in this exceptional\n          // situation, and hope on caching layers inside computables to present\n          // some stale state until we reconstruct the tree again\n        } else this.logger?.warn(e);\n      }\n\n      if (!this.keepRunning || this.terminated) break;\n\n      // Phase 1: mandatory floor — always wait at least MIN_POLLING_INTERVAL_MS.\n      // Not interruptible by scheduleOnNextState; only termination aborts it.\n      try {\n        await tp.setTimeout(MIN_POLLING_INTERVAL_MS, undefined, {\n          signal: this.abortController.signal,\n        });\n      } catch (e: unknown) {\n        if (!isTimeoutOrCancelError(e)) throw new Error(\"Unexpected error\", { cause: e });\n        if (this.abortController.signal.aborted) break;\n      }\n\n      if (!this.keepRunning || this.terminated) break;\n\n      // Phase 2: optional remainder up to pollingInterval — interruptible by\n      // scheduleOnNextState so that an external nudge wakes the loop promptly.\n      if (this.scheduledOnNextState.length === 0) {\n        const remaining = Math.max(0, this.pollingInterval - MIN_POLLING_INTERVAL_MS);\n        if (remaining > 0) {\n          try {\n            this.currentLoopDelayInterrupt = new AbortController();\n            await tp.setTimeout(remaining, undefined, {\n              signal: AbortSignal.any([\n                this.abortController.signal,\n                this.currentLoopDelayInterrupt.signal,\n              ]),\n            });\n          } catch (e: unknown) {\n            if (!isTimeoutOrCancelError(e)) throw new Error(\"Unexpected error\", { cause: e });\n            if (this.abortController.signal.aborted) break;\n            // Otherwise it was just the loop delay interrupt (scheduleOnNextState),\n            // continue to the next iteration\n          } finally {\n            this.currentLoopDelayInterrupt = undefined;\n          }\n        }\n      }\n    }\n\n    // reset only as a very last line\n    this.currentLoop = undefined;\n  }\n\n  /**\n   * Dumps the current state of the tree.\n   * @returns An array of ExtendedResourceData objects representing the current state of the tree.\n   */\n  public dumpState(): ExtendedResourceData[] {\n    return this.state.dumpState();\n  }\n\n  /**\n   * Terminates the internal loop, and permanently destoys all internal state, so\n   * all computables using this state will resolve to errors.\n   * */\n  public async terminate(): Promise<void> {\n    this.keepRunning = false;\n    this.terminated = true;\n    this.abortController.abort();\n\n    if (this.currentLoop === undefined) return;\n    await this.currentLoop;\n\n    this.state.invalidateTree(\"synchronization terminated for the tree\");\n  }\n\n  /** @deprecated */\n  public async awaitSyncLoopTermination(): Promise<void> {\n    if (this.currentLoop === undefined) return;\n    await this.currentLoop;\n  }\n\n  /**\n   * Initializes a synchronized tree from one or more seeds.\n   *\n   * @param seeds a bare {@link SignedResourceId} (the original single-root contract), a\n   *   single {@link TreeSeed}, or an array of seeds. Bare ids and explicit-resource seeds\n   *   become roots immediately; shared-type seeds discover their roots via `ListUserResources`.\n   */\n  public static async init(\n    pl: PlClient,\n    seeds: SignedResourceId | TreeSeed | TreeSeed[],\n    ops: SynchronizedTreeOps,\n    logger?: MiLogger,\n  ) {\n    const tree = new SynchronizedTreeState(pl, normalizeSeeds(seeds), ops, logger);\n\n    const stat = ops.logStat ? initialTreeLoadingStat() : undefined;\n\n    let ok = false;\n\n    try {\n      // resolve shared-type seeds before the first refresh so discovered roots load now\n      await tree.discover();\n      await tree.refresh(stat, {\n        timeout: ops.initialTreeLoadingTimeout,\n      });\n      ok = true;\n    } finally {\n      // logging stats if we were asked to (even if error occured)\n      if (stat && logger)\n        logger.info(\n          `Tree stat (initial load, ${ok ? \"success\" : \"failure\"}): ${JSON.stringify(stat)}`,\n        );\n    }\n\n    return tree;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"synchronized_tree.js","names":[],"sources":["../src/synchronized_tree.ts"],"sourcesContent":["import { PollingComputableHooks } from \"@milaboratories/computable\";\nimport { PlTreeEntry, PlTreeRootsEntry } from \"./accessors\";\nimport type {\n  FinalResourceDataPredicate,\n  PlClient,\n  ResourceType,\n  SignedResourceId,\n  TxOps,\n} from \"@milaboratories/pl-client\";\nimport type { Filter } from \"@milaboratories/pl-client\";\nimport {\n  isUnauthenticated,\n  isTimeoutOrCancelError,\n  isUnimplementedError,\n} from \"@milaboratories/pl-client\";\nimport type { ExtendedResourceData } from \"./state\";\nimport { PlTreeState, TreeStateUpdateError } from \"./state\";\nimport type { PruningFunction, TraversalMode, TreeLoadingStat } from \"./sync\";\nimport { constructTreeLoadingRequest, initialTreeLoadingStat, loadTreeState } from \"./sync\";\nimport * as tp from \"node:timers/promises\";\nimport type { MiLogger } from \"@milaboratories/ts-helpers\";\n\n/** Hard floor between consecutive tree-refresh calls.\n * Applies even when {@link scheduleOnNextState} has woken the loop early,\n * preventing tight polling loops during rapid state transitions. */\nconst MIN_POLLING_INTERVAL_MS = 100;\n\n/** Ceiling for the adaptive poll interval. Caps how stale an idle tree can get before the\n * next look, and bounds how far the idle backoff can push the interval out. */\nconst MAX_POLLING_INTERVAL_MS = 5_000;\n\n/** Applied to the interval after a cycle that changed nothing. An idle tree walks its\n * interval out towards {@link MAX_POLLING_INTERVAL_MS} instead of re-polling at full rate;\n * the first cycle that changes anything resets it. */\nconst IDLE_BACKOFF_MULTIPLIER = 1.5;\n\n/** The client's measured RTT becomes an interval floor, scaled by this. Every refresh costs\n * at least one round trip, so polling faster than a small multiple of the RTT only queues\n * round-trips the link cannot service. This is what replaces the fixed interval on a\n * high-latency link; on a fast link the configured `pollingInterval` still dominates. */\nconst RTT_POLL_FACTOR = 2;\n\n/** Ceiling for the RTT-derived floor. The estimate is sampled at connect time and never\n * re-sampled, so without a bound one slow ping pins the cadence high for the whole session.\n * Mirrors `MAX_ADAPTIVE_REQUEST_TIMEOUT` on the deadline side: past this the link is stuck\n * rather than slow, and spacing polls further only delays noticing it recovered. */\nconst MAX_RTT_POLL_INTERVAL_MS = 30_000;\n\ntype StatLoggingMode = \"cumulative\" | \"per-request\";\n\nexport type SynchronizedTreeOps = {\n  /** Override final predicate from the PlClient */\n  finalPredicateOverride?: FinalResourceDataPredicate;\n\n  /** Pruning function for legacy fallback path. */\n  pruning?: PruningFunction;\n\n  /** ResourceTree field filter for modern backend path. */\n  fieldFilter?: Filter;\n\n  /** ResourceTree traversal stop rules for modern backend path. */\n  traverseStopRules?: Filter;\n\n  /** Interval after last sync to sleep before the next one */\n  pollingInterval: number;\n  /** For how long to continue polling after the last derived value access */\n  stopPollingDelay: number;\n\n  /** If one of the values, tree will log stats of each polling request */\n  logStat?: StatLoggingMode;\n\n  /** Timeout for initial tree loading. If not specified, will use default for RO tx from pl-client. */\n  initialTreeLoadingTimeout?: number;\n\n  /** Controls which tree-loading path to use.  Default `\"auto\"`. */\n  traversalMode?: TraversalMode;\n};\n\n/** An explicit resource to serve as a tree root. Several explicit seeds may be passed. */\nexport type ExplicitRootSeed = { kind: \"resource\"; root: SignedResourceId };\n\n/** Discovers, as roots, every resource of this type shared with the current user.\n *  Matched against SharedResource.resourceType by NAME (version optional/ignored). The\n *  discovered set is DYNAMIC — roots appear/disappear as grants are added/revoked/expire. */\nexport type SharedTypeSeed = { kind: \"shared\"; resourceType: ResourceType };\n\nexport type TreeSeed = ExplicitRootSeed | SharedTypeSeed;\n\n/** Normalizes the {@link SynchronizedTreeState.init} seed argument — a bare\n * {@link SignedResourceId}, a single {@link TreeSeed}, or an array — to `TreeSeed[]`, so\n * every existing single-root caller is unchanged. */\nfunction normalizeSeeds(seeds: SignedResourceId | TreeSeed | TreeSeed[]): TreeSeed[] {\n  if (Array.isArray(seeds)) return seeds;\n  if (typeof seeds === \"object\" && seeds !== null && \"kind\" in seeds) return [seeds];\n  // bare SignedResourceId\n  return [{ kind: \"resource\", root: seeds }];\n}\n\n/** How often a tree with shared-type seeds re-polls ListUserResources to reconcile its\n * discovered roots.\n *\n * Discovery (a full ListUserResources stream) is far heavier than an ordinary incremental\n * refresh, so it must NOT run on every refresh tick. This is a wall-clock interval rather\n * than a count of iterations: the refresh cadence is adaptive (it stretches towards\n * {@link MAX_POLLING_INTERVAL_MS} on an idle tree and scales with RTT on a slow link),\n * so a fixed iteration count would let discovery latency drift out with it. Keeping it in\n * milliseconds pins the latency of noticing a new/removed share regardless of cadence, which\n * is what a human-driven share flow cares about.\n *\n * Only trees with shared-type seeds gate on this; {@link discover} is a no-op for single-root\n * and explicit-seed trees (empty `sharedSeeds`), so the value never affects them. */\nconst DISCOVERY_INTERVAL_MS = 3_000;\n\n/** Counters that mean \"this cycle brought something new\". Deliberately not the full change\n * breakdown: those fields are sub-counts of `resourcesChanged` and would double-count.\n * `resourcesUnchanged` is excluded by design, since a cycle that only re-fetched unchanged\n * state is exactly the idle case the backoff exists for. */\nfunction countedChanges(stat: TreeLoadingStat): number {\n  return stat.resourcesNew + stat.resourcesChanged + stat.resourcesMarkedFinal;\n}\n\n/** The poll-cadence policy, as a pure function of the last cycle's outcome.\n *\n * `configuredMs` is the tree's static `pollingInterval` and acts as the lower bound, so no\n * link can be polled faster than configured. `rttMs` raises that bound on a slow link.\n * `currentMs` is the interval in force for the cycle that just finished, which is what the\n * idle backoff compounds on. */\nexport function derivePollingInterval(opts: {\n  configuredMs: number;\n  currentMs: number;\n  rttMs: number | undefined;\n  changed: boolean;\n}): number {\n  const { configuredMs, currentMs, rttMs, changed } = opts;\n\n  // The cap applies to the RTT-derived part only, so `configuredMs` stays an absolute lower\n  // bound even if it is ever set above the cap.\n  const floor =\n    rttMs === undefined\n      ? configuredMs\n      : Math.max(\n          configuredMs,\n          Math.min(MAX_RTT_POLL_INTERVAL_MS, Math.ceil(rttMs * RTT_POLL_FACTOR)),\n        );\n\n  const next = changed ? floor : Math.max(floor, currentMs * IDLE_BACKOFF_MULTIPLIER);\n\n  // The ceiling never cuts below the floor: a link slower than MAX_POLLING_INTERVAL_MS still\n  // gets its RTT-derived spacing rather than being forced to re-poll early.\n  return Math.max(floor, Math.min(MAX_POLLING_INTERVAL_MS, next));\n}\n\ntype ScheduledRefresh = {\n  resolve: () => void;\n  reject: (err: any) => void;\n};\n\nexport class SynchronizedTreeState {\n  private readonly finalPredicate: FinalResourceDataPredicate;\n  private state: PlTreeState;\n  private readonly pollingInterval: number;\n  private readonly pruning?: PruningFunction;\n  private readonly fieldFilter?: Filter;\n  private readonly traverseStopRules?: Filter;\n  private readonly traversalMode: TraversalMode;\n  private readonly logStat?: StatLoggingMode;\n  private readonly hooks: PollingComputableHooks;\n  private readonly abortController = new AbortController();\n\n  /** Explicit-resource seeds: fixed roots, present from construction. */\n  private readonly explicitRoots: SignedResourceId[];\n  /** Shared-type seeds (discovered roots), if any. */\n  private readonly sharedSeeds: SharedTypeSeed[];\n  /** Roots discovered for shared-type seeds on the last discovery poll. */\n  private discoveredRoots: SignedResourceId[] = [];\n\n  private constructor(\n    private readonly pl: PlClient,\n    seeds: TreeSeed[],\n    ops: SynchronizedTreeOps,\n    private readonly logger?: MiLogger,\n  ) {\n    const {\n      finalPredicateOverride,\n      pruning,\n      fieldFilter,\n      traverseStopRules,\n      traversalMode,\n      pollingInterval,\n      stopPollingDelay,\n      logStat,\n    } = ops;\n    this.pruning = pruning;\n    this.fieldFilter = fieldFilter;\n    this.traverseStopRules = traverseStopRules;\n    this.traversalMode = traversalMode ?? \"auto\";\n    this.pollingInterval = pollingInterval;\n    this.effectivePollingInterval = pollingInterval;\n    this.finalPredicate = finalPredicateOverride ?? pl.finalPredicate;\n    this.logStat = logStat;\n\n    this.explicitRoots = seeds\n      .filter((s): s is ExplicitRootSeed => s.kind === \"resource\")\n      .map((s) => s.root);\n    this.sharedSeeds = seeds.filter((s): s is SharedTypeSeed => s.kind === \"shared\");\n\n    this.state = new PlTreeState(this.currentRootSet(), this.finalPredicate);\n    this.hooks = new PollingComputableHooks(\n      () => this.startUpdating(),\n      () => this.stopUpdating(),\n      { stopDebounce: stopPollingDelay },\n      (resolve, reject) => this.scheduleOnNextState(resolve, reject),\n    );\n  }\n\n  /** The current protected root set: explicit roots plus the latest discovered roots. */\n  private currentRootSet(): Set<SignedResourceId> {\n    return new Set([...this.explicitRoots, ...this.discoveredRoots]);\n  }\n\n  /** Resolves the single root for the backward-compatible single-root accessors, throwing\n   * if the tree does not have exactly one root (guards legacy callers against multi-root). */\n  private soleRoot(): SignedResourceId {\n    const roots = this.currentRootSet();\n    if (roots.size !== 1)\n      throw new Error(\n        `single-root accessor used on a tree with ${roots.size} roots; use rootsEntry() instead`,\n      );\n    return roots.values().next().value!;\n  }\n\n  /** @deprecated use \"entry\" instead */\n  public accessor(rid?: SignedResourceId): PlTreeEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return this.entry(rid);\n  }\n\n  /** Backward-compatible single-root entry. With no `rid` it returns the sole root's entry\n   * and THROWS if the tree has zero or more than one root. An explicit `rid` addresses any\n   * resource in the heap, as today. */\n  public entry(rid?: SignedResourceId): PlTreeEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return new PlTreeEntry(\n      { treeProvider: () => this.state, hooks: this.hooks },\n      rid ?? this.soleRoot(),\n    );\n  }\n\n  /** Reactive provider for the current root SET. Reading it inside a Computable tracks the\n   * set as a dependency, so the Computable recomputes when discovered roots appear/disappear. */\n  public rootsEntry(): PlTreeRootsEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return new PlTreeRootsEntry({ treeProvider: () => this.state, hooks: this.hooks });\n  }\n\n  /** Can be used to externally kick off the synchronization polling loop, and\n   * await for the first synchronization to happen. */\n  public async refreshState(): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    await this.hooks.refreshState();\n  }\n\n  private currentLoopDelayInterrupt: AbortController | undefined = undefined;\n  private scheduledOnNextState: ScheduledRefresh[] = [];\n\n  /** Interval actually used for the current wait. Starts at the configured `pollingInterval`\n   * and is re-derived after every cycle by {@link updatePollingInterval}. */\n  private effectivePollingInterval: number;\n\n  /** Re-derives {@link effectivePollingInterval} after a cycle.\n   *\n   * Two independent effects. The floor scales with the client's measured RTT, so a\n   * high-latency link stops queueing round-trips it cannot service. On top of that, a cycle\n   * that changed nothing multiplies the interval out towards\n   * {@link MAX_POLLING_INTERVAL_MS}, while any change snaps it straight back to the floor so\n   * an active tree stays responsive. */\n  private updatePollingInterval(changed: boolean): void {\n    this.effectivePollingInterval = derivePollingInterval({\n      configuredMs: this.pollingInterval,\n      currentMs: this.effectivePollingInterval,\n      rttMs: this.pl.rttEstimateMs,\n      changed,\n    });\n  }\n\n  /** Called from computable hooks when external observer asks for state refresh */\n  private scheduleOnNextState(resolve: () => void, reject: (err: any) => void): void {\n    if (this.terminated) reject(new Error(\"tree synchronization is terminated\"));\n    else {\n      this.scheduledOnNextState.push({ resolve, reject });\n      // Someone is waiting on fresh state, so this tree is not idle after all: drop any\n      // accumulated backoff, otherwise the cycles right after a nudge stay slow. Routed\n      // through the policy rather than assigning the configured value directly, so the RTT\n      // floor survives the reset. Assigning it raw would poll a high-latency link faster than\n      // it can answer, and the interval would stay there until the next cycle that completes:\n      // the error path never reaches updatePollingInterval, so a failing nudged refresh would\n      // keep retrying at the un-floored rate.\n      this.updatePollingInterval(true);\n      if (this.currentLoopDelayInterrupt) {\n        this.currentLoopDelayInterrupt.abort();\n        this.currentLoopDelayInterrupt = undefined;\n      }\n    }\n  }\n\n  /** Called from observer */\n  private startUpdating(): void {\n    if (this.terminated) return;\n    this.keepRunning = true;\n    if (this.currentLoop === undefined) this.currentLoop = this.mainLoop();\n  }\n\n  /** Called from observer */\n  private stopUpdating(): void {\n    this.keepRunning = false;\n  }\n\n  /** If true, main loop will continue polling pl state. */\n  private keepRunning = false;\n  /** Actual state of main loop. */\n  private currentLoop: Promise<void> | undefined = undefined;\n\n  /** Executed from the main loop, and initialization procedure. */\n  private async refresh(stats?: TreeLoadingStat, txOps?: TxOps): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    try {\n      await this.loadAndApply(stats, txOps);\n    } catch (e) {\n      // Discovery-tree self-heal: a discovered root whose grant was revoked/expired fails the whole\n      // ResourceTree poll with Unauthenticated. Re-discover (drops dead roots) and retry once. This is\n      // self-discriminating — a genuinely dead session also fails discover()'s own call, so real auth\n      // loss still propagates. Only for discovery trees; explicit-root trees propagate as-is.\n      if (this.sharedSeeds.length > 0 && isUnauthenticated(e)) {\n        this.logger?.warn(\n          \"discovery tree: Unauthenticated on ResourceTree (likely revoked/expired root); re-discovering and retrying\",\n        );\n        await this.discover();\n        await this.loadAndApply(stats, txOps);\n      } else throw e;\n    }\n  }\n\n  private async loadAndApply(stats?: TreeLoadingStat, txOps?: TxOps): Promise<void> {\n    const request = constructTreeLoadingRequest(this.state, {\n      pruningFunction: this.pruning,\n      fieldFilter: this.fieldFilter,\n      traverseStopRules: this.traverseStopRules,\n    });\n    // A shared-type-seed tree with no currently-discovered roots is legitimately empty:\n    // there is nothing to traverse, and tx.resourceTree([]) would throw \"at least one seed\n    // must be provided\". Skip the backend load and leave the (empty) state as-is — discovery\n    // adds roots later via setRoots(), which schedules the next refresh. Explicit-root trees\n    // never hit this (their root set is non-empty by construction).\n    if (request.seedResources.length === 0 && request.finalResources.size === 0) return;\n    const data = await this.pl.withReadTx(\n      \"ReadingTree\",\n      async (tx) => {\n        return await loadTreeState(\n          tx,\n          request,\n          stats,\n          this.pl.serverInfo.capabilities ?? [],\n          this.traversalMode,\n          this.logger,\n        );\n      },\n      txOps,\n    );\n    this.state.updateFromResourceData(data, { allowOrphanInputs: true, stat: stats });\n  }\n\n  /** Discovery sync for shared-type seeds: re-polls `ListUserResources` (gRPC-only) and\n   * reconciles the discovered root set against the heap. A longer poll result adds roots; a\n   * shorter one removes them (grant revoked/expired) — the removed roots' subtrees cascade\n   * to collection via the ordinary refcount GC ({@link PlTreeState.setRoots}). No-op when the\n   * tree has no shared-type seeds, or silently no-op on a REST client where `ListUserResources`\n   * is unavailable. */\n  private async discover(): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    if (this.sharedSeeds.length === 0) return;\n\n    const discovered = new Set<SignedResourceId>();\n    for (const seed of this.sharedSeeds) {\n      let ids: SignedResourceId[];\n      try {\n        // match by name only (permissive; ignores version, so it survives schema bumps)\n        ids = await this.pl.userResources.listSharedResourcesByType(seed.resourceType.name);\n      } catch (e: unknown) {\n        if (isUnimplementedError(e)) continue;\n        throw e;\n      }\n      for (const id of ids) discovered.add(id);\n    }\n\n    this.discoveredRoots = [...discovered];\n    this.state.setRoots(this.currentRootSet());\n  }\n\n  /** If true this tree state is permanently terminaed. */\n  private terminated = false;\n\n  private async mainLoop() {\n    // Always collected, even when not logging: the change counters drive the idle backoff\n    // below. Counter bumps are cheap next to the round trip they describe.\n    let stat = initialTreeLoadingStat();\n\n    let lastUpdate = Date.now();\n\n    // paces the discovery poll for shared-type seeds; 0 forces discovery on the first pass.\n    let lastDiscovery = 0;\n\n    while (true) {\n      if (!this.keepRunning || this.terminated) break;\n\n      // saving those who want to be notified about new state here\n      // because those who will be added during the tree retrieval\n      // should be notified only on the next round\n      let toNotify: ScheduledRefresh[] | undefined = undefined;\n      if (this.scheduledOnNextState.length > 0) {\n        toNotify = this.scheduledOnNextState;\n        this.scheduledOnNextState = [];\n      }\n\n      try {\n        // resetting stats if we were asked to collect non-cumulative stats\n        if (this.logStat === \"per-request\") stat = initialTreeLoadingStat();\n\n        // discovery sync for shared-type seeds: reconcile the discovered root set before\n        // refreshing, so newly discovered roots are materialized in this same iteration.\n        if (this.sharedSeeds.length > 0 && Date.now() - lastDiscovery >= DISCOVERY_INTERVAL_MS) {\n          await this.discover();\n          lastDiscovery = Date.now();\n        }\n\n        // Change counters before the refresh, so the delta tells us whether this single cycle\n        // brought anything new. Works in both stat modes: \"per-request\" resets to 0 above.\n        const changesBefore = countedChanges(stat);\n\n        // actual tree synchronization\n        await this.refresh(stat);\n\n        this.updatePollingInterval(countedChanges(stat) > changesBefore);\n\n        // logging stats if we were asked to\n        if (this.logStat && this.logger)\n          this.logger.info(\n            `Tree stat (success, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,\n          );\n        lastUpdate = Date.now();\n\n        // notifying that we got new state\n        if (toNotify !== undefined) for (const n of toNotify) n.resolve();\n      } catch (e: any) {\n        // logging stats if we were asked to (even if error occured)\n        if (this.logStat && this.logger)\n          this.logger.info(\n            `Tree stat (error, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,\n          );\n        lastUpdate = Date.now();\n\n        // notifying that we failed to refresh the state\n        if (toNotify !== undefined) for (const n of toNotify) n.reject(e);\n\n        // catching tree update errors, as they may leave our tree in inconsistent state\n        if (e instanceof TreeStateUpdateError) {\n          // important error logging, this should never happen\n          this.logger?.error(e);\n\n          // marking everybody who used previous state as changed\n          this.state.invalidateTree(\"stat update error\");\n          // creating new tree with the full current root set (re-discovered on next iteration)\n          this.state = new PlTreeState(this.currentRootSet(), this.finalPredicate);\n\n          // scheduling state update without delay\n          continue;\n\n          // unfortunately external observer may still see tree in its default\n          // empty state, though this is best we can do in this exceptional\n          // situation, and hope on caching layers inside computables to present\n          // some stale state until we reconstruct the tree again\n        } else this.logger?.warn(e);\n      }\n\n      if (!this.keepRunning || this.terminated) break;\n\n      // Phase 1: mandatory floor — always wait at least MIN_POLLING_INTERVAL_MS.\n      // Not interruptible by scheduleOnNextState; only termination aborts it.\n      try {\n        await tp.setTimeout(MIN_POLLING_INTERVAL_MS, undefined, {\n          signal: this.abortController.signal,\n        });\n      } catch (e: unknown) {\n        if (!isTimeoutOrCancelError(e)) throw new Error(\"Unexpected error\", { cause: e });\n        if (this.abortController.signal.aborted) break;\n      }\n\n      if (!this.keepRunning || this.terminated) break;\n\n      // Phase 2: optional remainder up to pollingInterval — interruptible by\n      // scheduleOnNextState so that an external nudge wakes the loop promptly.\n      if (this.scheduledOnNextState.length === 0) {\n        const remaining = Math.max(0, this.effectivePollingInterval - MIN_POLLING_INTERVAL_MS);\n        if (remaining > 0) {\n          try {\n            this.currentLoopDelayInterrupt = new AbortController();\n            await tp.setTimeout(remaining, undefined, {\n              signal: AbortSignal.any([\n                this.abortController.signal,\n                this.currentLoopDelayInterrupt.signal,\n              ]),\n            });\n          } catch (e: unknown) {\n            if (!isTimeoutOrCancelError(e)) throw new Error(\"Unexpected error\", { cause: e });\n            if (this.abortController.signal.aborted) break;\n            // Otherwise it was just the loop delay interrupt (scheduleOnNextState),\n            // continue to the next iteration\n          } finally {\n            this.currentLoopDelayInterrupt = undefined;\n          }\n        }\n      }\n    }\n\n    // reset only as a very last line\n    this.currentLoop = undefined;\n  }\n\n  /**\n   * Dumps the current state of the tree.\n   * @returns An array of ExtendedResourceData objects representing the current state of the tree.\n   */\n  public dumpState(): ExtendedResourceData[] {\n    return this.state.dumpState();\n  }\n\n  /**\n   * Terminates the internal loop, and permanently destoys all internal state, so\n   * all computables using this state will resolve to errors.\n   * */\n  public async terminate(): Promise<void> {\n    this.keepRunning = false;\n    this.terminated = true;\n    this.abortController.abort();\n\n    if (this.currentLoop === undefined) return;\n    await this.currentLoop;\n\n    this.state.invalidateTree(\"synchronization terminated for the tree\");\n  }\n\n  /** @deprecated */\n  public async awaitSyncLoopTermination(): Promise<void> {\n    if (this.currentLoop === undefined) return;\n    await this.currentLoop;\n  }\n\n  /**\n   * Initializes a synchronized tree from one or more seeds.\n   *\n   * @param seeds a bare {@link SignedResourceId} (the original single-root contract), a\n   *   single {@link TreeSeed}, or an array of seeds. Bare ids and explicit-resource seeds\n   *   become roots immediately; shared-type seeds discover their roots via `ListUserResources`.\n   */\n  public static async init(\n    pl: PlClient,\n    seeds: SignedResourceId | TreeSeed | TreeSeed[],\n    ops: SynchronizedTreeOps,\n    logger?: MiLogger,\n  ) {\n    const tree = new SynchronizedTreeState(pl, normalizeSeeds(seeds), ops, logger);\n\n    const stat = ops.logStat ? initialTreeLoadingStat() : undefined;\n\n    let ok = false;\n\n    try {\n      // resolve shared-type seeds before the first refresh so discovered roots load now\n      await tree.discover();\n      await tree.refresh(stat, {\n        timeout: ops.initialTreeLoadingTimeout,\n      });\n      ok = true;\n    } finally {\n      // logging stats if we were asked to (even if error occured)\n      if (stat && logger)\n        logger.info(\n          `Tree stat (initial load, ${ok ? \"success\" : \"failure\"}): ${JSON.stringify(stat)}`,\n        );\n    }\n\n    return tree;\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-tree",
-  "version": "1.13.5",
+  "version": "1.13.6",
   "description": "Reactive pl tree state",
   "files": [
     "./dist/**/*",
@@ -21,10 +21,10 @@
     "denque": "^2.1.0",
     "utility-types": "^3.11.0",
     "zod": "~3.25.76",
+    "@milaboratories/computable": "2.9.8",
+    "@milaboratories/pl-errors": "1.4.35",
     "@milaboratories/ts-helpers": "1.8.6",
-    "@milaboratories/pl-errors": "1.4.34",
-    "@milaboratories/pl-client": "3.14.5",
-    "@milaboratories/computable": "2.9.8"
+    "@milaboratories/pl-client": "3.14.6"
   },
   "devDependencies": {
     "@types/node": "~24.5.2",
@@ -32,8 +32,8 @@
     "typescript": "~5.9.3",
     "vitest": "^4.1.3",
     "@milaboratories/build-configs": "2.0.0",
-    "@milaboratories/ts-builder": "1.6.1",
-    "@milaboratories/ts-configs": "1.3.1"
+    "@milaboratories/ts-configs": "1.4.0",
+    "@milaboratories/ts-builder": "1.6.2"
   },
   "engines": {
     "node": ">=22.19.0"

package/src/polling_interval.test.ts

@@ -0,0 +1,90 @@
+import { test, expect } from "vitest";
+import { derivePollingInterval } from "./synchronized_tree";
+
+/** The project-list / sharing singleton trees run at 200ms; per-project trees at 1000ms. */
+const FAST = 200;
+
+test("no rtt sample yet leaves the configured interval alone", () => {
+  expect(
+    derivePollingInterval({ configuredMs: FAST, currentMs: FAST, rttMs: undefined, changed: true }),
+  ).toEqual(FAST);
+});
+
+test("a fast link keeps the configured interval", () => {
+  // 10ms RTT would imply a 20ms floor, well under the configured value.
+  expect(
+    derivePollingInterval({ configuredMs: FAST, currentMs: FAST, rttMs: 10, changed: true }),
+  ).toEqual(FAST);
+});
+
+test("a slow link spaces polls by rtt", () => {
+  // The spec's target envelope: 1.4s RTT against a 200ms fixed interval, which is the
+  // regime where unconditional polling outran what the link could deliver.
+  expect(
+    derivePollingInterval({ configuredMs: FAST, currentMs: FAST, rttMs: 1400, changed: true }),
+  ).toEqual(2800);
+});
+
+test("idle cycles back off, and a change snaps straight back", () => {
+  const step = (currentMs: number, changed: boolean) =>
+    derivePollingInterval({ configuredMs: FAST, currentMs, rttMs: 10, changed });
+
+  // Nothing changed: the interval walks out, strictly increasing each time.
+  const first = step(FAST, false);
+  const second = step(first, false);
+  const third = step(second, false);
+  expect(first).toBeGreaterThan(FAST);
+  expect(second).toBeGreaterThan(first);
+  expect(third).toBeGreaterThan(second);
+
+  // One changed cycle returns to the floor immediately, no gradual recovery.
+  expect(step(third, true)).toEqual(FAST);
+});
+
+test("idle backoff is bounded", () => {
+  let interval = FAST;
+  for (let i = 0; i < 100; i++) {
+    interval = derivePollingInterval({
+      configuredMs: FAST,
+      currentMs: interval,
+      rttMs: 10,
+      changed: false,
+    });
+  }
+  // Must converge on the ceiling rather than growing without limit.
+  expect(interval).toEqual(5_000);
+});
+
+test("resetting backoff keeps the rtt floor", () => {
+  // What an observer nudge does: reset to the floor, from a fully backed-off interval.
+  // The floor must stay RTT-derived, not drop to the raw configured value, or a nudge on a
+  // slow link would poll faster than the link can answer.
+  expect(
+    derivePollingInterval({ configuredMs: FAST, currentMs: 5_000, rttMs: 1400, changed: true }),
+  ).toEqual(2800);
+});
+
+test("the rtt floor is itself bounded", () => {
+  // A ping sampled during connect can legitimately take tens of seconds, and the estimate is
+  // never re-sampled. Unbounded, a 40s sample would pin the interval at 80s for the session.
+  expect(
+    derivePollingInterval({ configuredMs: FAST, currentMs: FAST, rttMs: 40_000, changed: true }),
+  ).toEqual(30_000);
+
+  // The bound holds against the idle backoff too, which compounds on the previous interval.
+  expect(
+    derivePollingInterval({ configuredMs: FAST, currentMs: 30_000, rttMs: 40_000, changed: false }),
+  ).toEqual(30_000);
+});
+
+test("the rtt floor outranks the ceiling on a very slow link", () => {
+  // 4s RTT implies an 8s floor, past the 5s ceiling. Clamping to 5s would poll faster than
+  // the link can answer, so the floor has to win.
+  const interval = derivePollingInterval({
+    configuredMs: FAST,
+    currentMs: FAST,
+    rttMs: 4000,
+    changed: false,
+  });
+  expect(interval).toEqual(8_000);
+});

package/src/synchronized_tree.ts

@@ -25,6 +25,27 @@ import type { MiLogger } from "@milaboratories/ts-helpers";
  * preventing tight polling loops during rapid state transitions. */
 const MIN_POLLING_INTERVAL_MS = 100;
 
+/** Ceiling for the adaptive poll interval. Caps how stale an idle tree can get before the
+ * next look, and bounds how far the idle backoff can push the interval out. */
+const MAX_POLLING_INTERVAL_MS = 5_000;
+
+/** Applied to the interval after a cycle that changed nothing. An idle tree walks its
+ * interval out towards {@link MAX_POLLING_INTERVAL_MS} instead of re-polling at full rate;
+ * the first cycle that changes anything resets it. */
+const IDLE_BACKOFF_MULTIPLIER = 1.5;
+
+/** The client's measured RTT becomes an interval floor, scaled by this. Every refresh costs
+ * at least one round trip, so polling faster than a small multiple of the RTT only queues
+ * round-trips the link cannot service. This is what replaces the fixed interval on a
+ * high-latency link; on a fast link the configured `pollingInterval` still dominates. */
+const RTT_POLL_FACTOR = 2;
+
+/** Ceiling for the RTT-derived floor. The estimate is sampled at connect time and never
+ * re-sampled, so without a bound one slow ping pins the cadence high for the whole session.
+ * Mirrors `MAX_ADAPTIVE_REQUEST_TIMEOUT` on the deadline side: past this the link is stuck
+ * rather than slow, and spacing polls further only delays noticing it recovered. */
+const MAX_RTT_POLL_INTERVAL_MS = 30_000;
+
 type StatLoggingMode = "cumulative" | "per-request";
 
 export type SynchronizedTreeOps = {
@@ -75,19 +96,59 @@ function normalizeSeeds(seeds: SignedResourceId | TreeSeed | TreeSeed[]): TreeSe
   return [{ kind: "resource", root: seeds }];
 }
 
-/** How often, in main-loop iterations, a tree with shared-type seeds re-polls
- * ListUserResources to reconcile its discovered roots. 1 would mean every iteration.
+/** How often a tree with shared-type seeds re-polls ListUserResources to reconcile its
+ * discovered roots.
  *
  * Discovery (a full ListUserResources stream) is far heavier than an ordinary incremental
- * refresh, so it must NOT run on every fast refresh tick. The refresh cadence is the tree's
- * `pollingInterval` floored by {@link MIN_POLLING_INTERVAL_MS} (~200ms-1s in practice — the
- * shared-seed discovery tree runs at the 200ms default). At N = 15 discovery fires roughly
- * every 15 × 200ms ≈ 3s, decoupling it from the fast refresh loop while keeping the latency
- * of noticing a new/removed share to a few seconds — acceptable for a human-driven share flow.
+ * refresh, so it must NOT run on every refresh tick. This is a wall-clock interval rather
+ * than a count of iterations: the refresh cadence is adaptive (it stretches towards
+ * {@link MAX_POLLING_INTERVAL_MS} on an idle tree and scales with RTT on a slow link),
+ * so a fixed iteration count would let discovery latency drift out with it. Keeping it in
+ * milliseconds pins the latency of noticing a new/removed share regardless of cadence, which
+ * is what a human-driven share flow cares about.
  *
  * Only trees with shared-type seeds gate on this; {@link discover} is a no-op for single-root
  * and explicit-seed trees (empty `sharedSeeds`), so the value never affects them. */
-const DISCOVERY_EVERY_N_REFRESHES = 15;
+const DISCOVERY_INTERVAL_MS = 3_000;
+
+/** Counters that mean "this cycle brought something new". Deliberately not the full change
+ * breakdown: those fields are sub-counts of `resourcesChanged` and would double-count.
+ * `resourcesUnchanged` is excluded by design, since a cycle that only re-fetched unchanged
+ * state is exactly the idle case the backoff exists for. */
+function countedChanges(stat: TreeLoadingStat): number {
+  return stat.resourcesNew + stat.resourcesChanged + stat.resourcesMarkedFinal;
+}
+
+/** The poll-cadence policy, as a pure function of the last cycle's outcome.
+ *
+ * `configuredMs` is the tree's static `pollingInterval` and acts as the lower bound, so no
+ * link can be polled faster than configured. `rttMs` raises that bound on a slow link.
+ * `currentMs` is the interval in force for the cycle that just finished, which is what the
+ * idle backoff compounds on. */
+export function derivePollingInterval(opts: {
+  configuredMs: number;
+  currentMs: number;
+  rttMs: number | undefined;
+  changed: boolean;
+}): number {
+  const { configuredMs, currentMs, rttMs, changed } = opts;
+
+  // The cap applies to the RTT-derived part only, so `configuredMs` stays an absolute lower
+  // bound even if it is ever set above the cap.
+  const floor =
+    rttMs === undefined
+      ? configuredMs
+      : Math.max(
+          configuredMs,
+          Math.min(MAX_RTT_POLL_INTERVAL_MS, Math.ceil(rttMs * RTT_POLL_FACTOR)),
+        );
+
+  const next = changed ? floor : Math.max(floor, currentMs * IDLE_BACKOFF_MULTIPLIER);
+
+  // The ceiling never cuts below the floor: a link slower than MAX_POLLING_INTERVAL_MS still
+  // gets its RTT-derived spacing rather than being forced to re-poll early.
+  return Math.max(floor, Math.min(MAX_POLLING_INTERVAL_MS, next));
+}
 
 type ScheduledRefresh = {
   resolve: () => void;
@@ -134,6 +195,7 @@ export class SynchronizedTreeState {
     this.traverseStopRules = traverseStopRules;
     this.traversalMode = traversalMode ?? "auto";
     this.pollingInterval = pollingInterval;
+    this.effectivePollingInterval = pollingInterval;
     this.finalPredicate = finalPredicateOverride ?? pl.finalPredicate;
     this.logStat = logStat;
 
@@ -201,11 +263,39 @@ export class SynchronizedTreeState {
   private currentLoopDelayInterrupt: AbortController | undefined = undefined;
   private scheduledOnNextState: ScheduledRefresh[] = [];
 
+  /** Interval actually used for the current wait. Starts at the configured `pollingInterval`
+   * and is re-derived after every cycle by {@link updatePollingInterval}. */
+  private effectivePollingInterval: number;
+
+  /** Re-derives {@link effectivePollingInterval} after a cycle.
+   *
+   * Two independent effects. The floor scales with the client's measured RTT, so a
+   * high-latency link stops queueing round-trips it cannot service. On top of that, a cycle
+   * that changed nothing multiplies the interval out towards
+   * {@link MAX_POLLING_INTERVAL_MS}, while any change snaps it straight back to the floor so
+   * an active tree stays responsive. */
+  private updatePollingInterval(changed: boolean): void {
+    this.effectivePollingInterval = derivePollingInterval({
+      configuredMs: this.pollingInterval,
+      currentMs: this.effectivePollingInterval,
+      rttMs: this.pl.rttEstimateMs,
+      changed,
+    });
+  }
+
   /** Called from computable hooks when external observer asks for state refresh */
   private scheduleOnNextState(resolve: () => void, reject: (err: any) => void): void {
     if (this.terminated) reject(new Error("tree synchronization is terminated"));
     else {
       this.scheduledOnNextState.push({ resolve, reject });
+      // Someone is waiting on fresh state, so this tree is not idle after all: drop any
+      // accumulated backoff, otherwise the cycles right after a nudge stay slow. Routed
+      // through the policy rather than assigning the configured value directly, so the RTT
+      // floor survives the reset. Assigning it raw would poll a high-latency link faster than
+      // it can answer, and the interval would stay there until the next cycle that completes:
+      // the error path never reaches updatePollingInterval, so a failing nudged refresh would
+      // keep retrying at the un-floored rate.
+      this.updatePollingInterval(true);
       if (this.currentLoopDelayInterrupt) {
         this.currentLoopDelayInterrupt.abort();
         this.currentLoopDelayInterrupt = undefined;
@@ -310,13 +400,14 @@ export class SynchronizedTreeState {
   private terminated = false;
 
   private async mainLoop() {
-    // will hold request stats
-    let stat = this.logStat ? initialTreeLoadingStat() : undefined;
+    // Always collected, even when not logging: the change counters drive the idle backoff
+    // below. Counter bumps are cheap next to the round trip they describe.
+    let stat = initialTreeLoadingStat();
 
     let lastUpdate = Date.now();
 
-    // counts refresh iterations to pace the discovery poll for shared-type seeds.
-    let iteration = 0;
+    // paces the discovery poll for shared-type seeds; 0 forces discovery on the first pass.
+    let lastDiscovery = 0;
 
     while (true) {
       if (!this.keepRunning || this.terminated) break;
@@ -336,16 +427,22 @@ export class SynchronizedTreeState {
 
         // discovery sync for shared-type seeds: reconcile the discovered root set before
         // refreshing, so newly discovered roots are materialized in this same iteration.
-        if (this.sharedSeeds.length > 0 && iteration % DISCOVERY_EVERY_N_REFRESHES === 0) {
+        if (this.sharedSeeds.length > 0 && Date.now() - lastDiscovery >= DISCOVERY_INTERVAL_MS) {
           await this.discover();
+          lastDiscovery = Date.now();
         }
-        iteration++;
+
+        // Change counters before the refresh, so the delta tells us whether this single cycle
+        // brought anything new. Works in both stat modes: "per-request" resets to 0 above.
+        const changesBefore = countedChanges(stat);
 
         // actual tree synchronization
         await this.refresh(stat);
 
+        this.updatePollingInterval(countedChanges(stat) > changesBefore);
+
         // logging stats if we were asked to
-        if (stat && this.logger)
+        if (this.logStat && this.logger)
           this.logger.info(
             `Tree stat (success, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,
           );
@@ -355,7 +452,7 @@ export class SynchronizedTreeState {
         if (toNotify !== undefined) for (const n of toNotify) n.resolve();
       } catch (e: any) {
         // logging stats if we were asked to (even if error occured)
-        if (stat && this.logger)
+        if (this.logStat && this.logger)
           this.logger.info(
             `Tree stat (error, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,
           );
@@ -402,7 +499,7 @@ export class SynchronizedTreeState {
       // Phase 2: optional remainder up to pollingInterval — interruptible by
       // scheduleOnNextState so that an external nudge wakes the loop promptly.
       if (this.scheduledOnNextState.length === 0) {
-        const remaining = Math.max(0, this.pollingInterval - MIN_POLLING_INTERVAL_MS);
+        const remaining = Math.max(0, this.effectivePollingInterval - MIN_POLLING_INTERVAL_MS);
         if (remaining > 0) {
           try {
             this.currentLoopDelayInterrupt = new AbortController();