@milaboratories/pl-tree 1.14.4 → 1.15.1

package/dist/delta_sync.cjs

@@ -0,0 +1,114 @@
+const require_state = require("./state.cjs");
+const require_sync = require("./sync.cjs");
+let _milaboratories_pl_client = require("@milaboratories/pl-client");
+//#region src/delta_sync.ts
+/** Emit everything at or below this depth from a resolution seed, whatever its change token
+* says. It bounds descent as well as emission: under a token the walk otherwise ends at the
+* first unchanged resource (api.proto, changed_since_token), so without this a round returns
+* the seeds alone and a newly attached subtree costs one sequential round trip per level.
+*
+* Deep enough to clear a subtree in one round, which is the trade: real server-side walk and
+* downlink for those levels, against a round trip each at ~1.4s on a slow link. Not free -
+* lower it if resolution rounds ever dominate a poll. */
+const RESOLUTION_DEPTH = 32;
+/** Every id a body points at. Exactly what `updateFromResourceData` refcounts, and it throws
+* `orphan resource` for any that resolves to nothing. */
+function referencesOf(resource) {
+	const refs = [];
+	if ((0, _milaboratories_pl_client.isNotNullSignedResourceId)(resource.error)) refs.push(resource.error);
+	for (const field of resource.fields) {
+		if ((0, _milaboratories_pl_client.isNotNullSignedResourceId)(field.value)) refs.push(field.value);
+		if ((0, _milaboratories_pl_client.isNotNullSignedResourceId)(field.error)) refs.push(field.error);
+	}
+	return refs;
+}
+/**
+* One delta poll: hand the backend this transaction's change token, take only what is newer.
+*
+* The caller commits the token, and only after the whole batch applies - advancing it past a
+* partial apply loses the dropped resources for good.
+*
+* Removals arrive as a rewrite of the referring resource, never as absence, and the refcount
+* GC does the rest. There is deliberately no periodic full reconcile; the blind spot is a
+* removal under a resource the mirror marked final, which streaming and BFS share.
+*/
+async function loadDeltaTreeState(tx, loadingRequest, stats, logger) {
+	const { seedResources, finalResources, roots, knownResources, pruningFunction, fieldFilter, traverseStopRules, changedSinceToken } = loadingRequest;
+	if (traverseStopRules !== void 0 && changedSinceToken === void 0) logger?.warn("delta poll: traverseStopRules supplied but not sent, and this poll carries no token, so the backend walk is unpruned where the streaming path would have pruned it");
+	const seeds = seedResources.length > 0 ? seedResources : [...roots];
+	if (seeds.length === 0) return [];
+	const collected = /* @__PURE__ */ new Map();
+	const missing = /* @__PURE__ */ new Set();
+	const pending = [];
+	const collect = (resource) => {
+		collected.set(resource.id, resource);
+		missing.delete(resource.id);
+		for (const ref of referencesOf(resource)) if (!collected.has(ref) && !knownResources.has(ref) && !missing.has(ref)) {
+			missing.add(ref);
+			pending.push(ref);
+		}
+	};
+	let warnedStopMarker = false;
+	const consume = async (walkSeeds, unconditionalDepth) => {
+		if (stats) {
+			stats.roundTrips++;
+			stats.streamRounds++;
+			stats.deltaSeedsSent += walkSeeds.length;
+		}
+		for await (const frame of tx.resourceTree(walkSeeds, {
+			includeKv: true,
+			fieldFilter,
+			changedSinceToken,
+			unconditionalDepth
+		})) {
+			if (frame.frameKind === "stopMarker") {
+				if (!warnedStopMarker) {
+					warnedStopMarker = true;
+					logger?.warn(`delta poll: ignoring a body-less frame for ${frame.id}; this poll sent no traverse stop rules, so the backend is using body-less frames for something this client does not interpret`);
+				}
+				continue;
+			}
+			if (stats) stats.resourceFrames++;
+			if (finalResources.has(frame.id)) {
+				if (stats) stats.finalResourcesSkipped++;
+				continue;
+			}
+			const resource = {
+				id: frame.id,
+				type: frame.type,
+				kind: frame.kind,
+				data: frame.data,
+				resourceReady: frame.resourceReady,
+				error: frame.error,
+				originalResourceId: frame.originalResourceId,
+				final: frame.final,
+				inputsLocked: frame.inputsLocked,
+				outputsLocked: frame.outputsLocked,
+				fields: pruningFunction !== void 0 ? pruningFunction(frame) : frame.fields,
+				kv: frame.kv
+			};
+			if (stats) stats.prunedFields += frame.fields.length - resource.fields.length;
+			collect(resource);
+			require_sync.collectStatsForResource(resource, stats);
+		}
+	};
+	await consume(seeds);
+	const collectedFromPoll = collected.size;
+	const fetched = /* @__PURE__ */ new Set();
+	while (missing.size > 0) {
+		const round = pending.splice(0).filter((id) => !fetched.has(id) && missing.has(id));
+		if (round.length === 0) throw new require_state.TreeStateUpdateError(`delta poll: ${missing.size} referenced resource(s) could not be resolved, first ${missing.values().next().value}`);
+		for (const id of round) fetched.add(id);
+		if (stats) stats.deltaResolutionRounds++;
+		await consume(round, RESOLUTION_DEPTH);
+	}
+	if (changedSinceToken !== void 0 && knownResources.size > 0 && collectedFromPoll >= knownResources.size) {
+		if (stats) stats.deltaSuspectedFullAnswers++;
+		logger?.warn(`delta poll: sent a token but received ${collectedFromPoll} resources against a mirror of ${knownResources.size}; the backend may have refused the token (instance change or rewound numbering), in which case this poll cost a full tree read`);
+	}
+	return [...collected.values()];
+}
+//#endregion
+exports.loadDeltaTreeState = loadDeltaTreeState;
+
+//# sourceMappingURL=delta_sync.cjs.map

package/dist/delta_sync.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta_sync.cjs","names":["TreeStateUpdateError"],"sources":["../src/delta_sync.ts"],"sourcesContent":["import type { PlTransaction, SignedResourceId } from \"@milaboratories/pl-client\";\nimport { isNotNullSignedResourceId } from \"@milaboratories/pl-client\";\nimport type { ExtendedResourceData } from \"./state\";\nimport { TreeStateUpdateError } from \"./state\";\nimport type { TreeLoadingRequest, TreeLoadingStat } from \"./sync\";\nimport { collectStatsForResource } from \"./sync\";\n\n/** Emit everything at or below this depth from a resolution seed, whatever its change token\n * says. It bounds descent as well as emission: under a token the walk otherwise ends at the\n * first unchanged resource (api.proto, changed_since_token), so without this a round returns\n * the seeds alone and a newly attached subtree costs one sequential round trip per level.\n *\n * Deep enough to clear a subtree in one round, which is the trade: real server-side walk and\n * downlink for those levels, against a round trip each at ~1.4s on a slow link. Not free -\n * lower it if resolution rounds ever dominate a poll. */\nconst RESOLUTION_DEPTH = 32;\n\n/** Every id a body points at. Exactly what `updateFromResourceData` refcounts, and it throws\n * `orphan resource` for any that resolves to nothing. */\nfunction referencesOf(resource: ExtendedResourceData): SignedResourceId[] {\n  const refs: SignedResourceId[] = [];\n  if (isNotNullSignedResourceId(resource.error)) refs.push(resource.error);\n  for (const field of resource.fields) {\n    if (isNotNullSignedResourceId(field.value)) refs.push(field.value);\n    if (isNotNullSignedResourceId(field.error)) refs.push(field.error);\n  }\n  return refs;\n}\n\n/**\n * One delta poll: hand the backend this transaction's change token, take only what is newer.\n *\n * The caller commits the token, and only after the whole batch applies - advancing it past a\n * partial apply loses the dropped resources for good.\n *\n * Removals arrive as a rewrite of the referring resource, never as absence, and the refcount\n * GC does the rest. There is deliberately no periodic full reconcile; the blind spot is a\n * removal under a resource the mirror marked final, which streaming and BFS share.\n */\nexport async function loadDeltaTreeState(\n  tx: PlTransaction,\n  loadingRequest: TreeLoadingRequest,\n  stats?: TreeLoadingStat,\n  logger?: { warn: (msg: string) => void },\n): Promise<ExtendedResourceData[]> {\n  const {\n    seedResources,\n    finalResources,\n    roots,\n    knownResources,\n    pruningFunction,\n    fieldFilter,\n    traverseStopRules,\n    changedSinceToken,\n  } = loadingRequest;\n\n  // Stop rules are never sent. The backend ignores them under a usable token anyway, but a\n  // token-less poll then walks unpruned where streaming would have pruned. Sending them only\n  // when the token is absent would change the request shape between polls, which a token\n  // holder must not do - so the cost is warned about instead.\n  if (traverseStopRules !== undefined && changedSinceToken === undefined) {\n    logger?.warn(\n      \"delta poll: traverseStopRules supplied but not sent, and this poll carries no token,\" +\n        \" so the backend walk is unpruned where the streaming path would have pruned it\",\n    );\n  }\n\n  // Seed at every non-final resource, not the roots. Required, not an optimisation: the\n  // backend ends a walk at the first unchanged resource, so a root-seeded poll never reaches a\n  // change under a quiet parent - measured at 0 of 3 changes delivered. algorithm_equivalence\n  // fails on its KV step if this is ever narrowed back to the roots.\n  //\n  // The seed set changes every poll and the token is deliberately NOT discarded for it, though\n  // api.proto counts it as a shape input. Safe because every seed is a resource the mirror\n  // already holds, so a change can only widen the result, and widening hides nothing.\n  // Discarding per poll would make every poll a full read and defeat the mechanism.\n  //\n  // The roots stand in when the frontier is empty: resourceTree needs at least one seed.\n  const seeds = seedResources.length > 0 ? seedResources : [...roots];\n  if (seeds.length === 0) return [];\n\n  const collected = new Map<SignedResourceId, ExtendedResourceData>();\n  // References neither the mirror nor this batch can satisfy; applying with one outstanding\n  // invalidates the whole tree. Maintained incrementally as frames arrive: rescanning\n  // everything collected once per round would be quadratic in a poll that needs several.\n  const missing = new Set<SignedResourceId>();\n  // Same ids, in arrival order, so a round consumes only what is new rather than walking the\n  // whole set. An id enters both exactly once: `collected` is checked before the add and never\n  // cleared, so nothing re-enters after it resolves.\n  const pending: SignedResourceId[] = [];\n  const collect = (resource: ExtendedResourceData) => {\n    collected.set(resource.id, resource);\n    missing.delete(resource.id);\n    for (const ref of referencesOf(resource))\n      if (!collected.has(ref) && !knownResources.has(ref) && !missing.has(ref)) {\n        missing.add(ref);\n        pending.push(ref);\n      }\n  };\n\n  let warnedStopMarker = false;\n  const consume = async (walkSeeds: SignedResourceId[], unconditionalDepth?: number) => {\n    if (stats) {\n      stats.roundTrips++;\n      stats.streamRounds++;\n      stats.deltaSeedsSent += walkSeeds.length;\n    }\n\n    for await (const frame of tx.resourceTree(walkSeeds, {\n      includeKv: true,\n      fieldFilter,\n      changedSinceToken,\n      unconditionalDepth,\n    })) {\n      // A body-less frame. The client reads that as a stop marker, and a stop marker can only\n      // follow traverse_stop_rules, which this path never sends. Nothing here needs it, so it\n      // is skipped - but not silently: reaching this means the backend put a meaning on a\n      // body-less frame that this client does not know, and a quiet skip would leave no trace\n      // of it. Warn once per poll rather than per frame, since a contract change would emit\n      // one of these for every resource visited.\n      if (frame.frameKind === \"stopMarker\") {\n        if (!warnedStopMarker) {\n          warnedStopMarker = true;\n          logger?.warn(\n            `delta poll: ignoring a body-less frame for ${frame.id}; this poll sent no ` +\n              `traverse stop rules, so the backend is using body-less frames for something ` +\n              `this client does not interpret`,\n          );\n        }\n        continue;\n      }\n\n      if (stats) stats.resourceFrames++;\n\n      // updateFromResourceData throws on any body for a held final resource and invalidates\n      // the tree. A token-less poll walks unpruned and emits exactly those, which is what the\n      // first poll after a restored snapshot does. Both sibling algorithms skip the same way.\n      // Safe for references: finalResources is a subset of knownResources.\n      if (finalResources.has(frame.id)) {\n        if (stats) stats.finalResourcesSkipped++;\n        continue;\n      }\n\n      // An explicit literal rather than two rest-spreads of the frame. Measured ~15% off the\n      // per-frame cost: a spread copies every property twice and gives the object a hidden\n      // class of its own, where this is the shape the streaming path already produces.\n      const resource: ExtendedResourceData = {\n        id: frame.id,\n        type: frame.type,\n        kind: frame.kind,\n        data: frame.data,\n        resourceReady: frame.resourceReady,\n        error: frame.error,\n        originalResourceId: frame.originalResourceId,\n        final: frame.final,\n        inputsLocked: frame.inputsLocked,\n        outputsLocked: frame.outputsLocked,\n        fields:\n          pruningFunction !== undefined\n            ? pruningFunction(frame as unknown as ExtendedResourceData)\n            : frame.fields,\n        kv: frame.kv,\n      };\n      if (stats) stats.prunedFields += frame.fields.length - resource.fields.length;\n\n      collect(resource);\n      collectStatsForResource(resource, stats);\n    }\n  };\n\n  await consume(seeds);\n\n  // Captured before the resolution rounds. They fetch unconditionally by design, so counting\n  // afterwards lets a modest unheld subtree inflate the total past a small mirror and report a\n  // refused token that was never refused.\n  const collectedFromPoll = collected.size;\n\n  // A body may reference a resource the response did not carry - a field repointed at one we\n  // never held. Ids already asked for are never re-requested, so the loop terminates: the tree\n  // is finite and `fetched` only grows.\n  //\n  // Deliberately unbounded on rounds. A round-count cap would turn a legal tree shape into a\n  // desktop error, since how deep the references chain is a property of what the backend\n  // allowed rather than of anything wrong here, and the streaming path's stop-marker follow-up\n  // loop has always run on the same assumption.\n  const fetched = new Set<SignedResourceId>();\n  while (missing.size > 0) {\n    const round = pending.splice(0).filter((id) => !fetched.has(id) && missing.has(id));\n    if (round.length === 0) {\n      // Asked for all of these and none arrived; a soft-deleted referent gets here, since\n      // those frames are dropped client-side. TreeStateUpdateError specifically: the poll loop\n      // rebuilds and discards the token for that class, where a plain Error is only logged and\n      // the identical request fails forever.\n      throw new TreeStateUpdateError(\n        `delta poll: ${missing.size} referenced resource(s) could not be resolved, first ${missing.values().next().value}`,\n      );\n    }\n    for (const id of round) fetched.add(id);\n\n    if (stats) stats.deltaResolutionRounds++;\n    await consume(round, RESOLUTION_DEPTH);\n  }\n\n  // A refused token is answered with the full tree and no error, so this is the only tell.\n  // Reported, not acted on: the response is a correct superset, and the token stored after\n  // this poll comes from the current instance, so it self-heals next poll.\n  if (\n    changedSinceToken !== undefined &&\n    knownResources.size > 0 &&\n    collectedFromPoll >= knownResources.size\n  ) {\n    if (stats) stats.deltaSuspectedFullAnswers++;\n    logger?.warn(\n      `delta poll: sent a token but received ${collectedFromPoll} resources against a mirror of ` +\n        `${knownResources.size}; the backend may have refused the token (instance change or ` +\n        `rewound numbering), in which case this poll cost a full tree read`,\n    );\n  }\n\n  return [...collected.values()];\n}\n"],"mappings":"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"}

package/dist/delta_sync.js

@@ -0,0 +1,114 @@
+import { TreeStateUpdateError } from "./state.js";
+import { collectStatsForResource } from "./sync.js";
+import { isNotNullSignedResourceId } from "@milaboratories/pl-client";
+//#region src/delta_sync.ts
+/** Emit everything at or below this depth from a resolution seed, whatever its change token
+* says. It bounds descent as well as emission: under a token the walk otherwise ends at the
+* first unchanged resource (api.proto, changed_since_token), so without this a round returns
+* the seeds alone and a newly attached subtree costs one sequential round trip per level.
+*
+* Deep enough to clear a subtree in one round, which is the trade: real server-side walk and
+* downlink for those levels, against a round trip each at ~1.4s on a slow link. Not free -
+* lower it if resolution rounds ever dominate a poll. */
+const RESOLUTION_DEPTH = 32;
+/** Every id a body points at. Exactly what `updateFromResourceData` refcounts, and it throws
+* `orphan resource` for any that resolves to nothing. */
+function referencesOf(resource) {
+	const refs = [];
+	if (isNotNullSignedResourceId(resource.error)) refs.push(resource.error);
+	for (const field of resource.fields) {
+		if (isNotNullSignedResourceId(field.value)) refs.push(field.value);
+		if (isNotNullSignedResourceId(field.error)) refs.push(field.error);
+	}
+	return refs;
+}
+/**
+* One delta poll: hand the backend this transaction's change token, take only what is newer.
+*
+* The caller commits the token, and only after the whole batch applies - advancing it past a
+* partial apply loses the dropped resources for good.
+*
+* Removals arrive as a rewrite of the referring resource, never as absence, and the refcount
+* GC does the rest. There is deliberately no periodic full reconcile; the blind spot is a
+* removal under a resource the mirror marked final, which streaming and BFS share.
+*/
+async function loadDeltaTreeState(tx, loadingRequest, stats, logger) {
+	const { seedResources, finalResources, roots, knownResources, pruningFunction, fieldFilter, traverseStopRules, changedSinceToken } = loadingRequest;
+	if (traverseStopRules !== void 0 && changedSinceToken === void 0) logger?.warn("delta poll: traverseStopRules supplied but not sent, and this poll carries no token, so the backend walk is unpruned where the streaming path would have pruned it");
+	const seeds = seedResources.length > 0 ? seedResources : [...roots];
+	if (seeds.length === 0) return [];
+	const collected = /* @__PURE__ */ new Map();
+	const missing = /* @__PURE__ */ new Set();
+	const pending = [];
+	const collect = (resource) => {
+		collected.set(resource.id, resource);
+		missing.delete(resource.id);
+		for (const ref of referencesOf(resource)) if (!collected.has(ref) && !knownResources.has(ref) && !missing.has(ref)) {
+			missing.add(ref);
+			pending.push(ref);
+		}
+	};
+	let warnedStopMarker = false;
+	const consume = async (walkSeeds, unconditionalDepth) => {
+		if (stats) {
+			stats.roundTrips++;
+			stats.streamRounds++;
+			stats.deltaSeedsSent += walkSeeds.length;
+		}
+		for await (const frame of tx.resourceTree(walkSeeds, {
+			includeKv: true,
+			fieldFilter,
+			changedSinceToken,
+			unconditionalDepth
+		})) {
+			if (frame.frameKind === "stopMarker") {
+				if (!warnedStopMarker) {
+					warnedStopMarker = true;
+					logger?.warn(`delta poll: ignoring a body-less frame for ${frame.id}; this poll sent no traverse stop rules, so the backend is using body-less frames for something this client does not interpret`);
+				}
+				continue;
+			}
+			if (stats) stats.resourceFrames++;
+			if (finalResources.has(frame.id)) {
+				if (stats) stats.finalResourcesSkipped++;
+				continue;
+			}
+			const resource = {
+				id: frame.id,
+				type: frame.type,
+				kind: frame.kind,
+				data: frame.data,
+				resourceReady: frame.resourceReady,
+				error: frame.error,
+				originalResourceId: frame.originalResourceId,
+				final: frame.final,
+				inputsLocked: frame.inputsLocked,
+				outputsLocked: frame.outputsLocked,
+				fields: pruningFunction !== void 0 ? pruningFunction(frame) : frame.fields,
+				kv: frame.kv
+			};
+			if (stats) stats.prunedFields += frame.fields.length - resource.fields.length;
+			collect(resource);
+			collectStatsForResource(resource, stats);
+		}
+	};
+	await consume(seeds);
+	const collectedFromPoll = collected.size;
+	const fetched = /* @__PURE__ */ new Set();
+	while (missing.size > 0) {
+		const round = pending.splice(0).filter((id) => !fetched.has(id) && missing.has(id));
+		if (round.length === 0) throw new TreeStateUpdateError(`delta poll: ${missing.size} referenced resource(s) could not be resolved, first ${missing.values().next().value}`);
+		for (const id of round) fetched.add(id);
+		if (stats) stats.deltaResolutionRounds++;
+		await consume(round, RESOLUTION_DEPTH);
+	}
+	if (changedSinceToken !== void 0 && knownResources.size > 0 && collectedFromPoll >= knownResources.size) {
+		if (stats) stats.deltaSuspectedFullAnswers++;
+		logger?.warn(`delta poll: sent a token but received ${collectedFromPoll} resources against a mirror of ${knownResources.size}; the backend may have refused the token (instance change or rewound numbering), in which case this poll cost a full tree read`);
+	}
+	return [...collected.values()];
+}
+//#endregion
+export { loadDeltaTreeState };
+
+//# sourceMappingURL=delta_sync.js.map

package/dist/delta_sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta_sync.js","names":[],"sources":["../src/delta_sync.ts"],"sourcesContent":["import type { PlTransaction, SignedResourceId } from \"@milaboratories/pl-client\";\nimport { isNotNullSignedResourceId } from \"@milaboratories/pl-client\";\nimport type { ExtendedResourceData } from \"./state\";\nimport { TreeStateUpdateError } from \"./state\";\nimport type { TreeLoadingRequest, TreeLoadingStat } from \"./sync\";\nimport { collectStatsForResource } from \"./sync\";\n\n/** Emit everything at or below this depth from a resolution seed, whatever its change token\n * says. It bounds descent as well as emission: under a token the walk otherwise ends at the\n * first unchanged resource (api.proto, changed_since_token), so without this a round returns\n * the seeds alone and a newly attached subtree costs one sequential round trip per level.\n *\n * Deep enough to clear a subtree in one round, which is the trade: real server-side walk and\n * downlink for those levels, against a round trip each at ~1.4s on a slow link. Not free -\n * lower it if resolution rounds ever dominate a poll. */\nconst RESOLUTION_DEPTH = 32;\n\n/** Every id a body points at. Exactly what `updateFromResourceData` refcounts, and it throws\n * `orphan resource` for any that resolves to nothing. */\nfunction referencesOf(resource: ExtendedResourceData): SignedResourceId[] {\n  const refs: SignedResourceId[] = [];\n  if (isNotNullSignedResourceId(resource.error)) refs.push(resource.error);\n  for (const field of resource.fields) {\n    if (isNotNullSignedResourceId(field.value)) refs.push(field.value);\n    if (isNotNullSignedResourceId(field.error)) refs.push(field.error);\n  }\n  return refs;\n}\n\n/**\n * One delta poll: hand the backend this transaction's change token, take only what is newer.\n *\n * The caller commits the token, and only after the whole batch applies - advancing it past a\n * partial apply loses the dropped resources for good.\n *\n * Removals arrive as a rewrite of the referring resource, never as absence, and the refcount\n * GC does the rest. There is deliberately no periodic full reconcile; the blind spot is a\n * removal under a resource the mirror marked final, which streaming and BFS share.\n */\nexport async function loadDeltaTreeState(\n  tx: PlTransaction,\n  loadingRequest: TreeLoadingRequest,\n  stats?: TreeLoadingStat,\n  logger?: { warn: (msg: string) => void },\n): Promise<ExtendedResourceData[]> {\n  const {\n    seedResources,\n    finalResources,\n    roots,\n    knownResources,\n    pruningFunction,\n    fieldFilter,\n    traverseStopRules,\n    changedSinceToken,\n  } = loadingRequest;\n\n  // Stop rules are never sent. The backend ignores them under a usable token anyway, but a\n  // token-less poll then walks unpruned where streaming would have pruned. Sending them only\n  // when the token is absent would change the request shape between polls, which a token\n  // holder must not do - so the cost is warned about instead.\n  if (traverseStopRules !== undefined && changedSinceToken === undefined) {\n    logger?.warn(\n      \"delta poll: traverseStopRules supplied but not sent, and this poll carries no token,\" +\n        \" so the backend walk is unpruned where the streaming path would have pruned it\",\n    );\n  }\n\n  // Seed at every non-final resource, not the roots. Required, not an optimisation: the\n  // backend ends a walk at the first unchanged resource, so a root-seeded poll never reaches a\n  // change under a quiet parent - measured at 0 of 3 changes delivered. algorithm_equivalence\n  // fails on its KV step if this is ever narrowed back to the roots.\n  //\n  // The seed set changes every poll and the token is deliberately NOT discarded for it, though\n  // api.proto counts it as a shape input. Safe because every seed is a resource the mirror\n  // already holds, so a change can only widen the result, and widening hides nothing.\n  // Discarding per poll would make every poll a full read and defeat the mechanism.\n  //\n  // The roots stand in when the frontier is empty: resourceTree needs at least one seed.\n  const seeds = seedResources.length > 0 ? seedResources : [...roots];\n  if (seeds.length === 0) return [];\n\n  const collected = new Map<SignedResourceId, ExtendedResourceData>();\n  // References neither the mirror nor this batch can satisfy; applying with one outstanding\n  // invalidates the whole tree. Maintained incrementally as frames arrive: rescanning\n  // everything collected once per round would be quadratic in a poll that needs several.\n  const missing = new Set<SignedResourceId>();\n  // Same ids, in arrival order, so a round consumes only what is new rather than walking the\n  // whole set. An id enters both exactly once: `collected` is checked before the add and never\n  // cleared, so nothing re-enters after it resolves.\n  const pending: SignedResourceId[] = [];\n  const collect = (resource: ExtendedResourceData) => {\n    collected.set(resource.id, resource);\n    missing.delete(resource.id);\n    for (const ref of referencesOf(resource))\n      if (!collected.has(ref) && !knownResources.has(ref) && !missing.has(ref)) {\n        missing.add(ref);\n        pending.push(ref);\n      }\n  };\n\n  let warnedStopMarker = false;\n  const consume = async (walkSeeds: SignedResourceId[], unconditionalDepth?: number) => {\n    if (stats) {\n      stats.roundTrips++;\n      stats.streamRounds++;\n      stats.deltaSeedsSent += walkSeeds.length;\n    }\n\n    for await (const frame of tx.resourceTree(walkSeeds, {\n      includeKv: true,\n      fieldFilter,\n      changedSinceToken,\n      unconditionalDepth,\n    })) {\n      // A body-less frame. The client reads that as a stop marker, and a stop marker can only\n      // follow traverse_stop_rules, which this path never sends. Nothing here needs it, so it\n      // is skipped - but not silently: reaching this means the backend put a meaning on a\n      // body-less frame that this client does not know, and a quiet skip would leave no trace\n      // of it. Warn once per poll rather than per frame, since a contract change would emit\n      // one of these for every resource visited.\n      if (frame.frameKind === \"stopMarker\") {\n        if (!warnedStopMarker) {\n          warnedStopMarker = true;\n          logger?.warn(\n            `delta poll: ignoring a body-less frame for ${frame.id}; this poll sent no ` +\n              `traverse stop rules, so the backend is using body-less frames for something ` +\n              `this client does not interpret`,\n          );\n        }\n        continue;\n      }\n\n      if (stats) stats.resourceFrames++;\n\n      // updateFromResourceData throws on any body for a held final resource and invalidates\n      // the tree. A token-less poll walks unpruned and emits exactly those, which is what the\n      // first poll after a restored snapshot does. Both sibling algorithms skip the same way.\n      // Safe for references: finalResources is a subset of knownResources.\n      if (finalResources.has(frame.id)) {\n        if (stats) stats.finalResourcesSkipped++;\n        continue;\n      }\n\n      // An explicit literal rather than two rest-spreads of the frame. Measured ~15% off the\n      // per-frame cost: a spread copies every property twice and gives the object a hidden\n      // class of its own, where this is the shape the streaming path already produces.\n      const resource: ExtendedResourceData = {\n        id: frame.id,\n        type: frame.type,\n        kind: frame.kind,\n        data: frame.data,\n        resourceReady: frame.resourceReady,\n        error: frame.error,\n        originalResourceId: frame.originalResourceId,\n        final: frame.final,\n        inputsLocked: frame.inputsLocked,\n        outputsLocked: frame.outputsLocked,\n        fields:\n          pruningFunction !== undefined\n            ? pruningFunction(frame as unknown as ExtendedResourceData)\n            : frame.fields,\n        kv: frame.kv,\n      };\n      if (stats) stats.prunedFields += frame.fields.length - resource.fields.length;\n\n      collect(resource);\n      collectStatsForResource(resource, stats);\n    }\n  };\n\n  await consume(seeds);\n\n  // Captured before the resolution rounds. They fetch unconditionally by design, so counting\n  // afterwards lets a modest unheld subtree inflate the total past a small mirror and report a\n  // refused token that was never refused.\n  const collectedFromPoll = collected.size;\n\n  // A body may reference a resource the response did not carry - a field repointed at one we\n  // never held. Ids already asked for are never re-requested, so the loop terminates: the tree\n  // is finite and `fetched` only grows.\n  //\n  // Deliberately unbounded on rounds. A round-count cap would turn a legal tree shape into a\n  // desktop error, since how deep the references chain is a property of what the backend\n  // allowed rather than of anything wrong here, and the streaming path's stop-marker follow-up\n  // loop has always run on the same assumption.\n  const fetched = new Set<SignedResourceId>();\n  while (missing.size > 0) {\n    const round = pending.splice(0).filter((id) => !fetched.has(id) && missing.has(id));\n    if (round.length === 0) {\n      // Asked for all of these and none arrived; a soft-deleted referent gets here, since\n      // those frames are dropped client-side. TreeStateUpdateError specifically: the poll loop\n      // rebuilds and discards the token for that class, where a plain Error is only logged and\n      // the identical request fails forever.\n      throw new TreeStateUpdateError(\n        `delta poll: ${missing.size} referenced resource(s) could not be resolved, first ${missing.values().next().value}`,\n      );\n    }\n    for (const id of round) fetched.add(id);\n\n    if (stats) stats.deltaResolutionRounds++;\n    await consume(round, RESOLUTION_DEPTH);\n  }\n\n  // A refused token is answered with the full tree and no error, so this is the only tell.\n  // Reported, not acted on: the response is a correct superset, and the token stored after\n  // this poll comes from the current instance, so it self-heals next poll.\n  if (\n    changedSinceToken !== undefined &&\n    knownResources.size > 0 &&\n    collectedFromPoll >= knownResources.size\n  ) {\n    if (stats) stats.deltaSuspectedFullAnswers++;\n    logger?.warn(\n      `delta poll: sent a token but received ${collectedFromPoll} resources against a mirror of ` +\n        `${knownResources.size}; the backend may have refused the token (instance change or ` +\n        `rewound numbering), in which case this poll cost a full tree read`,\n    );\n  }\n\n  return [...collected.values()];\n}\n"],"mappings":"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"}

package/dist/index.cjs

@@ -19,6 +19,7 @@ exports.PlTreeState = require_state.PlTreeState;
 exports.SynchronizedTreeState = require_synchronized_tree.SynchronizedTreeState;
 exports.TreeStateUpdateError = require_state.TreeStateUpdateError;
 exports.captureTreeState = require_persisted_tree.captureTreeState;
+exports.collectStatsForResource = require_sync.collectStatsForResource;
 exports.constructTreeLoadingRequest = require_sync.constructTreeLoadingRequest;
 exports.decodePersistedTree = require_persisted_tree.decodePersistedTree;
 exports.derivePollingInterval = require_synchronized_tree.derivePollingInterval;
@@ -35,8 +36,10 @@ exports.makeResourceSnapshot = require_snapshot.makeResourceSnapshot;
 exports.mapValueAndError = require_value_and_error.mapValueAndError;
 exports.mapValueAndErrorIfDefined = require_value_and_error.mapValueAndErrorIfDefined;
 exports.readPersistedTreeHeader = require_persisted_tree.readPersistedTreeHeader;
+exports.resolveTreeLoadingAlgorithm = require_sync.resolveTreeLoadingAlgorithm;
 exports.restoreTreeState = require_persisted_tree.restoreTreeState;
 exports.rsSchema = require_snapshot.rsSchema;
+exports.supportsResourceTreeTraversal = require_sync.supportsResourceTreeTraversal;
 exports.treeDumpStats = require_dump.treeDumpStats;
 exports.treeEntryToResourceInfo = require_accessors.treeEntryToResourceInfo;
 exports.treeEntryToResourceWithData = require_snapshot.treeEntryToResourceWithData;

package/dist/index.d.ts

@@ -3,9 +3,9 @@ import { ValueAndError, mapValueAndError, mapValueAndErrorIfDefined } from "./va
 import { ValueOrError } from "./value_or_error.js";
 import { PlError, PlTreeEntry, PlTreeEntryAccessor, PlTreeNodeAccessor, PlTreeRootsAccessor, PlTreeRootsEntry, ResourceInfo, TreeAccessorData, TreeAccessorInstanceData, isPlTreeEntry, isPlTreeEntryAccessor, isPlTreeNodeAccessor, isPlTreeRootsAccessor, isPlTreeRootsEntry, treeEntryToResourceInfo } from "./accessors.js";
 import { ExtendedResourceData, PlTreeResource, PlTreeState, ResourceDataWithFinalState, ResourceUpdateStat, TreeStateUpdateError } from "./state.js";
-import { PruningFunction, TraversalMode, TreeLoadingRequest, TreeLoadingStat, constructTreeLoadingRequest, formatTreeLoadingStat, initialTreeLoadingStat, loadTreeState } from "./sync.js";
+import { PruningFunction, TraversalMode, TreeLoadingAlgorithmName, TreeLoadingRequest, TreeLoadingStat, collectStatsForResource, constructTreeLoadingRequest, formatTreeLoadingStat, initialTreeLoadingStat, loadTreeState, resolveTreeLoadingAlgorithm, supportsResourceTreeTraversal } from "./sync.js";
 import { InferSnapshot, ResourceSnapshot, ResourceSnapshotSchema, ResourceWithData, ResourceWithMetadata, makeResourceSnapshot, rsSchema, treeEntryToResourceWithData, treeEntryToResourceWithMetadata } from "./snapshot.js";
 import { DecodePersistedTreeOps, EncodePersistedTreeOps, PERSISTED_TREE_SCHEMA_VERSION, PersistedTree, PersistedTreeHeader, PersistedTreeReadFailure, PersistedTreeReadResult, captureTreeState, decodePersistedTree, encodePersistedTree, readPersistedTreeHeader, restoreTreeState } from "./persisted_tree.js";
 import { ExplicitRootSeed, SharedTypeSeed, SynchronizedTreeOps, SynchronizedTreeState, TreeSeed, derivePollingInterval } from "./synchronized_tree.js";
 import { ResourceStats, TreeDumpStats, treeDumpStats } from "./dump.js";
-export { CommonFieldTraverseOps, CommonTraversalOps, DecodePersistedTreeOps, EncodePersistedTreeOps, ExplicitRootSeed, ExtendedResourceData, FieldTraversalStep, GetFieldStep, InferSnapshot, PERSISTED_TREE_SCHEMA_VERSION, PersistedTree, PersistedTreeHeader, PersistedTreeReadFailure, PersistedTreeReadResult, 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, captureTreeState, constructTreeLoadingRequest, decodePersistedTree, derivePollingInterval, encodePersistedTree, formatTreeLoadingStat, initialTreeLoadingStat, isPlTreeEntry, isPlTreeEntryAccessor, isPlTreeNodeAccessor, isPlTreeRootsAccessor, isPlTreeRootsEntry, loadTreeState, makeResourceSnapshot, mapValueAndError, mapValueAndErrorIfDefined, readPersistedTreeHeader, restoreTreeState, rsSchema, treeDumpStats, treeEntryToResourceInfo, treeEntryToResourceWithData, treeEntryToResourceWithMetadata };
+export { CommonFieldTraverseOps, CommonTraversalOps, DecodePersistedTreeOps, EncodePersistedTreeOps, ExplicitRootSeed, ExtendedResourceData, FieldTraversalStep, GetFieldStep, InferSnapshot, PERSISTED_TREE_SCHEMA_VERSION, PersistedTree, PersistedTreeHeader, PersistedTreeReadFailure, PersistedTreeReadResult, 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, TreeLoadingAlgorithmName, TreeLoadingRequest, TreeLoadingStat, TreeSeed, TreeStateUpdateError, ValueAndError, ValueOrError, captureTreeState, collectStatsForResource, constructTreeLoadingRequest, decodePersistedTree, derivePollingInterval, encodePersistedTree, formatTreeLoadingStat, initialTreeLoadingStat, isPlTreeEntry, isPlTreeEntryAccessor, isPlTreeNodeAccessor, isPlTreeRootsAccessor, isPlTreeRootsEntry, loadTreeState, makeResourceSnapshot, mapValueAndError, mapValueAndErrorIfDefined, readPersistedTreeHeader, resolveTreeLoadingAlgorithm, restoreTreeState, rsSchema, supportsResourceTreeTraversal, treeDumpStats, treeEntryToResourceInfo, treeEntryToResourceWithData, treeEntryToResourceWithMetadata };

package/dist/index.js

@@ -1,9 +1,9 @@
 import { mapValueAndError, mapValueAndErrorIfDefined } from "./value_and_error.js";
 import { PlError, PlTreeEntry, PlTreeEntryAccessor, PlTreeNodeAccessor, PlTreeRootsAccessor, PlTreeRootsEntry, isPlTreeEntry, isPlTreeEntryAccessor, isPlTreeNodeAccessor, isPlTreeRootsAccessor, isPlTreeRootsEntry, treeEntryToResourceInfo } from "./accessors.js";
 import { PlTreeResource, PlTreeState, TreeStateUpdateError } from "./state.js";
-import { constructTreeLoadingRequest, formatTreeLoadingStat, initialTreeLoadingStat, loadTreeState } from "./sync.js";
+import { collectStatsForResource, constructTreeLoadingRequest, formatTreeLoadingStat, initialTreeLoadingStat, loadTreeState, resolveTreeLoadingAlgorithm, supportsResourceTreeTraversal } from "./sync.js";
 import { makeResourceSnapshot, rsSchema, treeEntryToResourceWithData, treeEntryToResourceWithMetadata } from "./snapshot.js";
 import { PERSISTED_TREE_SCHEMA_VERSION, captureTreeState, decodePersistedTree, encodePersistedTree, readPersistedTreeHeader, restoreTreeState } from "./persisted_tree.js";
 import { SynchronizedTreeState, derivePollingInterval } from "./synchronized_tree.js";
 import { treeDumpStats } from "./dump.js";
-export { PERSISTED_TREE_SCHEMA_VERSION, PlError, PlTreeEntry, PlTreeEntryAccessor, PlTreeNodeAccessor, PlTreeResource, PlTreeRootsAccessor, PlTreeRootsEntry, PlTreeState, SynchronizedTreeState, TreeStateUpdateError, captureTreeState, constructTreeLoadingRequest, decodePersistedTree, derivePollingInterval, encodePersistedTree, formatTreeLoadingStat, initialTreeLoadingStat, isPlTreeEntry, isPlTreeEntryAccessor, isPlTreeNodeAccessor, isPlTreeRootsAccessor, isPlTreeRootsEntry, loadTreeState, makeResourceSnapshot, mapValueAndError, mapValueAndErrorIfDefined, readPersistedTreeHeader, restoreTreeState, rsSchema, treeDumpStats, treeEntryToResourceInfo, treeEntryToResourceWithData, treeEntryToResourceWithMetadata };
+export { PERSISTED_TREE_SCHEMA_VERSION, PlError, PlTreeEntry, PlTreeEntryAccessor, PlTreeNodeAccessor, PlTreeResource, PlTreeRootsAccessor, PlTreeRootsEntry, PlTreeState, SynchronizedTreeState, TreeStateUpdateError, captureTreeState, collectStatsForResource, constructTreeLoadingRequest, decodePersistedTree, derivePollingInterval, encodePersistedTree, formatTreeLoadingStat, initialTreeLoadingStat, isPlTreeEntry, isPlTreeEntryAccessor, isPlTreeNodeAccessor, isPlTreeRootsAccessor, isPlTreeRootsEntry, loadTreeState, makeResourceSnapshot, mapValueAndError, mapValueAndErrorIfDefined, readPersistedTreeHeader, resolveTreeLoadingAlgorithm, restoreTreeState, rsSchema, supportsResourceTreeTraversal, treeDumpStats, treeEntryToResourceInfo, treeEntryToResourceWithData, treeEntryToResourceWithMetadata };

package/dist/state.cjs

@@ -311,18 +311,47 @@ var PlTreeState = class {
 		this.checkValid();
 		const incrementRefs = [];
 		const decrementRefs = [];
+		let addedCount = 0;
+		let firstAdded;
+		let errRd;
+		let errRes;
+		let errOriginalResourceId = _milaboratories_pl_client.NullSignedResourceId;
+		let errError = _milaboratories_pl_client.NullSignedResourceId;
+		let errInputsLocked = false;
+		let errOutputsLocked = false;
+		let errResourceReady = false;
+		let errFinal = false;
+		const unexpectedTransitionError = (reason) => {
+			const { fields, ...rdWithoutFields } = errRd;
+			const statBeforeMutation = errRes === void 0 ? void 0 : {
+				id: errRes.id,
+				kind: errRes.kind,
+				type: errRes.type,
+				data: errRes.data,
+				resourceReady: errResourceReady,
+				inputsLocked: errInputsLocked,
+				outputsLocked: errOutputsLocked,
+				error: errError,
+				originalResourceId: errOriginalResourceId,
+				final: errFinal
+			};
+			this.invalidateTree();
+			throw new TreeStateUpdateError(`Unexpected resource state transition (${reason}): ${(0, _milaboratories_pl_client.stringifyWithResourceId)(rdWithoutFields)} -> ${(0, _milaboratories_pl_client.stringifyWithResourceId)(statBeforeMutation)}`);
+		};
 		for (const rd of resourceData) {
 			let resource = this.resources.get(rd.id);
 			const held = resource !== void 0;
 			let changed = false;
 			let metadataChanged = false;
-			const statBeforeMutation = resource?.basicState;
-			const unexpectedTransitionError = (reason) => {
-				const { fields, ...rdWithoutFields } = rd;
-				this.invalidateTree();
-				throw new TreeStateUpdateError(`Unexpected resource state transition (${reason}): ${(0, _milaboratories_pl_client.stringifyWithResourceId)(rdWithoutFields)} -> ${(0, _milaboratories_pl_client.stringifyWithResourceId)(statBeforeMutation)}`);
-			};
+			errRd = rd;
+			errRes = resource;
 			if (resource !== void 0) {
+				errOriginalResourceId = resource.originalResourceId;
+				errError = resource.error;
+				errInputsLocked = resource.inputsLocked;
+				errOutputsLocked = resource.outputsLocked;
+				errResourceReady = resource.resourceReady;
+				errFinal = resource.finalFlag;
 				if (resource.finalState) unexpectedTransitionError("resource state can	 be updated after it is marked as final");
 				resource.version += 1;
 				if (resource.originalResourceId !== rd.originalResourceId) {
@@ -340,8 +369,15 @@ var PlTreeState = class {
 					changed = true;
 					if (stat) stat.errorsAttached++;
 				}
+				let walk = rd.fields.length > 0 ? resource.fieldsMap.values() : void 0;
 				for (const fd of rd.fields) {
-					let field = resource.fieldsMap.get(fd.name);
+					let field;
+					if (walk !== void 0) {
+						const next = walk.next();
+						if (next.done === true || next.value.name !== fd.name) walk = void 0;
+						else field = next.value;
+					}
+					if (field === void 0) field = resource.fieldsMap.get(fd.name);
 					if (!field) {
 						field = new PlTreeField(fd.name, fd.type, fd.value, fd.error, fd.status, fd.valueIsFinal, resource.version);
 						if ((0, _milaboratories_pl_client.isNotNullSignedResourceId)(fd.value)) incrementRefs.push(fd.value);
@@ -436,10 +472,18 @@ var PlTreeState = class {
 					changed = true;
 					if (stat) stat.readyFlips++;
 				}
+				let kvWalk = rd.kv.length > 0 ? resource.kv.entries() : void 0;
 				for (const kv of rd.kv) {
-					const current = resource.kv.get(kv.key);
+					let current;
+					if (kvWalk !== void 0) {
+						const next = kvWalk.next();
+						if (next.done === true || next.value[0] !== kv.key) kvWalk = void 0;
+						else current = next.value[1];
+					}
+					if (current === void 0) current = resource.kv.get(kv.key);
 					if (current === void 0) {
 						resource.kv.set(kv.key, kv.value);
+						kvWalk = void 0;
 						(0, _milaboratories_ts_helpers.notEmpty)(resource.kvChangedPerKey).markChanged(kv.key, `kv added for ${(0, _milaboratories_pl_client.resourceIdToString)(resource.id)}: ${kv.key}`);
 						changed = true;
 						if (stat) stat.kvChanged++;
@@ -481,7 +525,8 @@ var PlTreeState = class {
 				for (const kv of rd.kv) resource.kv.set(kv.key, kv.value);
 				if (this.isFinalPredicate(resource)) resource.markFinal();
 				this.resources.set(resource.id, resource);
-				this.resourcesAdded.markChanged(`new resource ${(0, _milaboratories_pl_client.resourceIdToString)(resource.id)} added`);
+				if (addedCount === 0) firstAdded = resource.id;
+				addedCount++;
 			}
 			if (stat) if (!held) stat.resourcesNew++;
 			else if (changed) {
@@ -494,6 +539,7 @@ var PlTreeState = class {
 				if (!stat.usedStreaming) stat.bfsRequestsWasted++;
 			}
 		}
+		if (firstAdded !== void 0) this.resourcesAdded.markChanged(addedCount === 1 ? `new resource ${(0, _milaboratories_pl_client.resourceIdToString)(firstAdded)} added` : `${addedCount} new resources added, first ${(0, _milaboratories_pl_client.resourceIdToString)(firstAdded)}`);
 		for (const rid of incrementRefs) {
 			const res = this.resources.get(rid);
 			if (!res) {