@milaboratories/pl-tree 1.14.4 → 1.15.1

package/src/delta_sync.ts

@@ -0,0 +1,221 @@
+import type { PlTransaction, SignedResourceId } from "@milaboratories/pl-client";
+import { isNotNullSignedResourceId } from "@milaboratories/pl-client";
+import type { ExtendedResourceData } from "./state";
+import { TreeStateUpdateError } from "./state";
+import type { TreeLoadingRequest, TreeLoadingStat } from "./sync";
+import { collectStatsForResource } from "./sync";
+
+/** 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: ExtendedResourceData): SignedResourceId[] {
+  const refs: SignedResourceId[] = [];
+  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.
+ */
+export async function loadDeltaTreeState(
+  tx: PlTransaction,
+  loadingRequest: TreeLoadingRequest,
+  stats?: TreeLoadingStat,
+  logger?: { warn: (msg: string) => void },
+): Promise<ExtendedResourceData[]> {
+  const {
+    seedResources,
+    finalResources,
+    roots,
+    knownResources,
+    pruningFunction,
+    fieldFilter,
+    traverseStopRules,
+    changedSinceToken,
+  } = loadingRequest;
+
+  // Stop rules are never sent. The backend ignores them under a usable token anyway, but a
+  // token-less poll then walks unpruned where streaming would have pruned. Sending them only
+  // when the token is absent would change the request shape between polls, which a token
+  // holder must not do - so the cost is warned about instead.
+  if (traverseStopRules !== undefined && changedSinceToken === undefined) {
+    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",
+    );
+  }
+
+  // Seed at every non-final resource, not the roots. Required, not an optimisation: the
+  // backend ends a walk at the first unchanged resource, so a root-seeded poll never reaches a
+  // change under a quiet parent - measured at 0 of 3 changes delivered. algorithm_equivalence
+  // fails on its KV step if this is ever narrowed back to the roots.
+  //
+  // The seed set changes every poll and the token is deliberately NOT discarded for it, though
+  // api.proto counts it as a shape input. Safe because every seed is a resource the mirror
+  // already holds, so a change can only widen the result, and widening hides nothing.
+  // Discarding per poll would make every poll a full read and defeat the mechanism.
+  //
+  // The roots stand in when the frontier is empty: resourceTree needs at least one seed.
+  const seeds = seedResources.length > 0 ? seedResources : [...roots];
+  if (seeds.length === 0) return [];
+
+  const collected = new Map<SignedResourceId, ExtendedResourceData>();
+  // References neither the mirror nor this batch can satisfy; applying with one outstanding
+  // invalidates the whole tree. Maintained incrementally as frames arrive: rescanning
+  // everything collected once per round would be quadratic in a poll that needs several.
+  const missing = new Set<SignedResourceId>();
+  // Same ids, in arrival order, so a round consumes only what is new rather than walking the
+  // whole set. An id enters both exactly once: `collected` is checked before the add and never
+  // cleared, so nothing re-enters after it resolves.
+  const pending: SignedResourceId[] = [];
+  const collect = (resource: ExtendedResourceData) => {
+    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: SignedResourceId[], unconditionalDepth?: number) => {
+    if (stats) {
+      stats.roundTrips++;
+      stats.streamRounds++;
+      stats.deltaSeedsSent += walkSeeds.length;
+    }
+
+    for await (const frame of tx.resourceTree(walkSeeds, {
+      includeKv: true,
+      fieldFilter,
+      changedSinceToken,
+      unconditionalDepth,
+    })) {
+      // A body-less frame. The client reads that as a stop marker, and a stop marker can only
+      // follow traverse_stop_rules, which this path never sends. Nothing here needs it, so it
+      // is skipped - but not silently: reaching this means the backend put a meaning on a
+      // body-less frame that this client does not know, and a quiet skip would leave no trace
+      // of it. Warn once per poll rather than per frame, since a contract change would emit
+      // one of these for every resource visited.
+      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++;
+
+      // updateFromResourceData throws on any body for a held final resource and invalidates
+      // the tree. A token-less poll walks unpruned and emits exactly those, which is what the
+      // first poll after a restored snapshot does. Both sibling algorithms skip the same way.
+      // Safe for references: finalResources is a subset of knownResources.
+      if (finalResources.has(frame.id)) {
+        if (stats) stats.finalResourcesSkipped++;
+        continue;
+      }
+
+      // An explicit literal rather than two rest-spreads of the frame. Measured ~15% off the
+      // per-frame cost: a spread copies every property twice and gives the object a hidden
+      // class of its own, where this is the shape the streaming path already produces.
+      const resource: ExtendedResourceData = {
+        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 !== undefined
+            ? pruningFunction(frame as unknown as ExtendedResourceData)
+            : frame.fields,
+        kv: frame.kv,
+      };
+      if (stats) stats.prunedFields += frame.fields.length - resource.fields.length;
+
+      collect(resource);
+      collectStatsForResource(resource, stats);
+    }
+  };
+
+  await consume(seeds);
+
+  // Captured before the resolution rounds. They fetch unconditionally by design, so counting
+  // afterwards lets a modest unheld subtree inflate the total past a small mirror and report a
+  // refused token that was never refused.
+  const collectedFromPoll = collected.size;
+
+  // A body may reference a resource the response did not carry - a field repointed at one we
+  // never held. Ids already asked for are never re-requested, so the loop terminates: the tree
+  // is finite and `fetched` only grows.
+  //
+  // Deliberately unbounded on rounds. A round-count cap would turn a legal tree shape into a
+  // desktop error, since how deep the references chain is a property of what the backend
+  // allowed rather than of anything wrong here, and the streaming path's stop-marker follow-up
+  // loop has always run on the same assumption.
+  const fetched = new Set<SignedResourceId>();
+  while (missing.size > 0) {
+    const round = pending.splice(0).filter((id) => !fetched.has(id) && missing.has(id));
+    if (round.length === 0) {
+      // Asked for all of these and none arrived; a soft-deleted referent gets here, since
+      // those frames are dropped client-side. TreeStateUpdateError specifically: the poll loop
+      // rebuilds and discards the token for that class, where a plain Error is only logged and
+      // the identical request fails forever.
+      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);
+  }
+
+  // A refused token is answered with the full tree and no error, so this is the only tell.
+  // Reported, not acted on: the response is a correct superset, and the token stored after
+  // this poll comes from the current instance, so it self-heals next poll.
+  if (
+    changedSinceToken !== undefined &&
+    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()];
+}

package/src/delta_sync_live.test.ts

@@ -0,0 +1,259 @@
+import { test, expect } from "vitest";
+import {
+  asSignedResourceId,
+  field,
+  hasCapability,
+  parseSignedResourceId,
+  TestHelpers,
+} from "@milaboratories/pl-client";
+import type { PlClient } from "@milaboratories/pl-client";
+import type { ExtendedResourceData } from "./state";
+import { TestStructuralResourceType1 } from "./test_utils";
+import { SynchronizedTreeState } from "./synchronized_tree";
+import { ConsoleLoggerAdapter } from "@milaboratories/ts-helpers";
+import type { TraversalMode } from "./sync";
+import tp from "timers/promises";
+
+/**
+ * Delta polling against a real backend, for correctness only. Cost (bytes and round trips per
+ * poll) is the benchmark's job, since stats are loop-internal with no public accessor.
+ *
+ * Everything here needs `treeChangedSince:v1`, which
+ * only a backend built from pl PR #2163 advertises, so each test skips rather than fails on
+ * one without it. The unit coverage in `delta_sync.test.ts` pins the client's own logic; what
+ * cannot be faked, and is what these are for, is the backend's own emission rule.
+ */
+/** Marks the test SKIPPED, not passed, when the backend cannot serve delta.
+ *
+ * These previously returned early, so on a backend without the capability the whole delta
+ * suite reported four green ticks over zero delta code. Skipped and passed are different
+ * signals and a run summary has to be able to tell them apart. */
+function skipUnlessDelta(pl: PlClient, ctx: { skip: (note?: string) => void }): boolean {
+  if (hasCapability(pl.serverInfo.capabilities ?? [], "treeChangedSince:v1")) return true;
+  ctx.skip("backend does not advertise treeChangedSince:v1 (needs pl PR #2163)");
+  return false;
+}
+
+const logger = new ConsoleLoggerAdapter(console);
+
+/** Whole-mirror comparison, so a retained-but-unreferenced resource or a dropped property
+ * shows up rather than only a differing count. */
+function canonicalShape(resources: ExtendedResourceData[]): string {
+  return resources
+    .map(
+      (r) =>
+        `${r.id}|${r.kind}|${r.final}|${r.inputsLocked}|${r.outputsLocked}|` +
+        `${r.fields
+          .map((f) => `${f.name}=${f.value}`)
+          .sort()
+          .join(",")}|kv:${r.kv
+          .map((kv) => kv.key)
+          .sort()
+          .join(",")}`,
+    )
+    .sort()
+    .join("\n");
+}
+
+/** A root with one child holding data, which is enough of a tree to poll. */
+async function seedTree(pl: PlClient) {
+  return await pl.withWriteTx(
+    "DeltaSeed",
+    async (tx) => {
+      const root = tx.createStruct(TestStructuralResourceType1);
+      const rootField = field(tx.clientRoot, "deltaRoot");
+      tx.createField(rootField, "Dynamic");
+      tx.setField(rootField, root);
+
+      const child = tx.createStruct(TestStructuralResourceType1);
+      const childField = field(root, "child");
+      tx.createField(childField, "Dynamic");
+      tx.setField(childField, child);
+
+      await tx.commit();
+      return { root: await root.globalId, child: await child.globalId };
+    },
+    { sync: true },
+  );
+}
+
+async function openTree(
+  pl: PlClient,
+  root: string,
+  traversalMode: TraversalMode,
+  extra: Record<string, unknown> = {},
+) {
+  return await SynchronizedTreeState.init(
+    pl,
+    root as never,
+    { stopPollingDelay: 50, pollingInterval: 10, traversalMode, ...extra } as never,
+    logger,
+  );
+}
+
+test("a delta poll delivers a change on a resource the mirror already holds", async (ctx) => {
+  await TestHelpers.withTempRoot(async (pl) => {
+    if (!skipUnlessDelta(pl, ctx)) return;
+
+    const { root, child } = await seedTree(pl);
+    const tree = await openTree(pl, root, "backend-delta");
+    try {
+      await tree.refreshState();
+
+      // Attach a new resource under the child, so the child's own state moves.
+      await pl.withWriteTx(
+        "DeltaMutate",
+        async (tx) => {
+          const grandchild = tx.createStruct(TestStructuralResourceType1);
+          const f = field(child as never, "grandchild");
+          tx.createField(f, "Dynamic");
+          tx.setField(f, grandchild);
+          await tx.commit();
+        },
+        { sync: true },
+      );
+
+      await tree.refreshState();
+
+      // The grandchild is a resource the mirror never held, referenced by a body the delta
+      // did carry: exactly the case the resolution round exists for.
+      const dump = tree.dumpState();
+      expect(dump.some((r) => r.fields.some((f) => f.name === "grandchild"))).toBe(true);
+    } finally {
+      await tree.terminate();
+    }
+  });
+});
+
+test("delta and streaming converge on the same mirror", async (ctx) => {
+  await TestHelpers.withTempRoot(async (pl) => {
+    if (!skipUnlessDelta(pl, ctx)) return;
+
+    const { root, child } = await seedTree(pl);
+
+    const delta = await openTree(pl, root, "backend-delta");
+    const streaming = await openTree(pl, root, "backend-streaming");
+    try {
+      await Promise.all([delta.refreshState(), streaming.refreshState()]);
+
+      await pl.withWriteTx(
+        "DeltaConverge",
+        async (tx) => {
+          const extra = tx.createStruct(TestStructuralResourceType1);
+          const f = field(child as never, "extra");
+          tx.createField(f, "Dynamic");
+          tx.setField(f, extra);
+          await tx.commit();
+        },
+        { sync: true },
+      );
+
+      // Poll both twice: delta needs the second to see the change settle, and streaming is
+      // idempotent, so this cannot favour either.
+      await Promise.all([delta.refreshState(), streaming.refreshState()]);
+      await Promise.all([delta.refreshState(), streaming.refreshState()]);
+
+      const shape = (t: SynchronizedTreeState) =>
+        t
+          .dumpState()
+          .map(
+            (r) =>
+              `${r.id}|${r.fields
+                .map((f) => `${f.name}=${f.value}`)
+                .sort()
+                .join(",")}`,
+          )
+          .sort();
+
+      expect(shape(delta)).toEqual(shape(streaming));
+    } finally {
+      await Promise.all([delta.terminate(), streaming.terminate()]);
+    }
+  });
+});
+
+test("a quiet parent: a change under an unchanged resource still arrives", async (ctx) => {
+  await TestHelpers.withTempRoot(async (pl) => {
+    if (!skipUnlessDelta(pl, ctx)) return;
+
+    const { root, child } = await seedTree(pl);
+    const tree = await openTree(pl, root, "backend-delta");
+    try {
+      await tree.refreshState();
+
+      // A KV write on the child does not rewrite the root, so the root stays quiet. With
+      // the child is its own seed, so the walk reaches it anyway. This is
+      // the assertion that justifies seeding the frontier rather than the roots.
+      await pl.withWriteTx(
+        "DeltaQuietParent",
+        async (tx) => {
+          tx.setKValue(child as never, "quiet", Buffer.from("value"));
+          await tx.commit();
+        },
+        { sync: true },
+      );
+
+      // Give the poll loop a couple of cycles: the change has to be reached, not just sent.
+      for (let i = 0; i < 3; i++) {
+        await tree.refreshState();
+        await tp.setTimeout(20);
+      }
+
+      const dump = tree.dumpState();
+      const childState = dump.find((r) => r.id === child);
+      expect(childState?.kv.some((kv) => kv.key === "quiet")).toBe(true);
+    } finally {
+      await tree.terminate();
+    }
+  });
+});
+
+test("a delta tree restored from a snapshot converges with streaming", async (ctx) => {
+  await TestHelpers.withTempRoot(async (pl) => {
+    if (!skipUnlessDelta(pl, ctx)) return;
+
+    const { root } = await seedTree(pl);
+
+    // Load through streaming, then hand that mirror to a delta tree via restoreFrom. This is
+    // the ordinary upgrade path and the one shape a cold open cannot produce: a POPULATED
+    // mirror whose first delta poll carries no token, so it is a full walk that also sends no
+    // stop rules. Bodies for resources the mirror holds as final must be skipped, or the apply
+    // throws; resources below them must not be retained unreferenced.
+    //
+    // The earlier version of this test opened a fresh delta tree after terminating the
+    // streaming one, which gave an EMPTY mirror and asserted nothing.
+    // The fixture must actually contain a final resource or the skip branch is never reached:
+    // DefaultFinalResourceDataPredicate marks none of the test resource types final, which is
+    // why an earlier version of this test passed with the skip disabled. Everything except the
+    // root goes final, so the root stays a seed and the tree can still poll.
+    const finalPredicateOverride = (r: { id: unknown }) => r.id !== root;
+
+    const warm = await openTree(pl, root, "backend-streaming", { finalPredicateOverride });
+    await warm.refreshState();
+    const witness = parseSignedResourceId(asSignedResourceId(root)).signature;
+    const snapshot = warm.capture(witness);
+    const streamingShape = canonicalShape(warm.dumpState());
+    await warm.terminate();
+
+    const delta = await SynchronizedTreeState.init(
+      pl,
+      root as never,
+      {
+        stopPollingDelay: 50,
+        pollingInterval: 10,
+        traversalMode: "backend-delta",
+        restoreFrom: snapshot,
+        finalPredicateOverride,
+      },
+      logger,
+    );
+    try {
+      expect(delta.wasRestoredFromSnapshot).toBe(true);
+      await delta.refreshState();
+      await delta.refreshState();
+      expect(canonicalShape(delta.dumpState())).toBe(streamingShape);
+    } finally {
+      await delta.terminate();
+    }
+  });
+}, 300_000);

package/src/state.test.ts

@@ -1,5 +1,7 @@
 import { expect, test } from "vitest";
 import { Computable } from "@milaboratories/computable";
+import type { Watcher } from "@milaboratories/computable";
+import type { FieldData } from "@milaboratories/pl-client";
 import {
   createSignedResourceId,
   DefaultFinalResourceDataPredicate,
@@ -20,6 +22,15 @@ import {
 
 const rid = createSignedResourceId;
 
+/** Minimal Watcher for tests that read tree state directly, outside a Computable. */
+class NoopWatcher implements Watcher {
+  isChanged = false;
+  markChanged(): void {
+    this.isChanged = true;
+  }
+}
+const w = () => new NoopWatcher();
+
 test("simple tree test 1", async () => {
   const tree = new PlTreeState(TestDynamicRootId1, DefaultFinalResourceDataPredicate);
   const entry = tree.entry();
@@ -317,3 +328,149 @@ test("exception - ready without locks 2", () => {
     ]),
   ).toThrow(/ready without input or output lock/);
 });
+
+// The field and kv update loops walk the stored entries in lockstep with the incoming ones
+// and only fall back to a hash lookup once the two orders diverge. These cover the
+// divergence shapes: reordering, an insertion in the middle, a removal. A reorder that
+// changes nothing must invalidate nothing and must not disturb refCounts, which is what
+// pins the fallback: mistaking a reordered field for a new one still leaves the right field
+// set behind, but double-counts the reference and fires spurious change notifications.
+
+const rootRes = (fields: FieldData[]) => [{ ...TestDynamicRootState1, fields }];
+
+test("a pure field reorder changes nothing and invalidates nothing", () => {
+  const tree = new PlTreeState(TestDynamicRootId1, DefaultFinalResourceDataPredicate);
+  tree.updateFromResourceData(rootRes([dField("a"), dField("b"), dField("c")]));
+
+  const watcher = w();
+  const root = tree.get(watcher, TestDynamicRootId1);
+  root.listDynamicFields(watcher);
+  for (const name of ["a", "b", "c"]) root.getField(watcher, name, () => {});
+  expect(watcher.isChanged).toStrictEqual(false);
+
+  tree.updateFromResourceData(rootRes([dField("c"), dField("b"), dField("a")]));
+
+  expect(watcher.isChanged).toStrictEqual(false);
+  expect(
+    tree
+      .get(w(), TestDynamicRootId1)
+      .fields.map((f) => f.name)
+      .sort(),
+  ).toStrictEqual(["a", "b", "c"]);
+});
+
+test("field inserted mid-order, then removed, is tracked", () => {
+  const tree = new PlTreeState(TestDynamicRootId1, DefaultFinalResourceDataPredicate);
+  const names = () =>
+    tree
+      .get(w(), TestDynamicRootId1)
+      .fields.map((f) => f.name)
+      .sort();
+
+  tree.updateFromResourceData(rootRes([dField("a"), dField("c")]));
+  expect(names()).toStrictEqual(["a", "c"]);
+
+  // "b" appears between two fields that are already stored: the walk diverges at "b"
+  tree.updateFromResourceData(rootRes([dField("a"), dField("b"), dField("c")]));
+  expect(names()).toStrictEqual(["a", "b", "c"]);
+
+  // and disappears again, in a shuffled order
+  tree.updateFromResourceData(rootRes([dField("c"), dField("a")]));
+  expect(names()).toStrictEqual(["a", "c"]);
+});
+
+test("reordering fields does not inflate refCounts", () => {
+  const tree = new PlTreeState(TestDynamicRootId1, DefaultFinalResourceDataPredicate);
+  const leaf = (n: bigint) => ({
+    ...TestValueResourceState1,
+    id: rid(n),
+    data: new TextEncoder().encode(`v${n}`),
+  });
+
+  tree.updateFromResourceData([
+    {
+      ...TestDynamicRootState1,
+      fields: [dField("a", rid(1n)), dField("b", rid(2n))],
+    },
+    leaf(1n),
+    leaf(2n),
+  ]);
+
+  // reorder and repoint in one update: the two fields swap targets
+  tree.updateFromResourceData([
+    {
+      ...TestDynamicRootState1,
+      fields: [dField("b", rid(1n)), dField("a", rid(2n))],
+    },
+    leaf(1n),
+    leaf(2n),
+  ]);
+
+  const byName = new Map(tree.get(w(), TestDynamicRootId1).fields.map((f) => [f.name, f.value]));
+  expect(byName.get("a")).toStrictEqual(rid(2n));
+  expect(byName.get("b")).toStrictEqual(rid(1n));
+
+  // dropping "a" must collect leaf 2: its refCount has to be exactly 1, so a reorder that
+  // was mistaken for an insertion (and double-incremented) would leave it alive here
+  tree.updateFromResourceData(rootRes([dField("b", rid(1n))]));
+  expect(tree.get(w(), rid(1n)).getDataAsString()).toStrictEqual("v1");
+  expect(() => tree.get(w(), rid(2n))).toThrow(/not found/);
+});
+
+test("kv reordering neither invalidates watchers nor loses entries", () => {
+  const tree = new PlTreeState(TestDynamicRootId1, DefaultFinalResourceDataPredicate);
+  const kvOf = (entries: [string, string][]) => [
+    {
+      ...TestDynamicRootState1,
+      fields: [],
+      kv: entries.map(([key, value]) => ({ key, value: Buffer.from(value) })),
+    },
+  ];
+  const read = (key: string) => tree.get(w(), TestDynamicRootId1).getKeyValueString(w(), key);
+
+  tree.updateFromResourceData(
+    kvOf([
+      ["k1", "one"],
+      ["k2", "two"],
+    ]),
+  );
+  expect([read("k1"), read("k2")]).toStrictEqual(["one", "two"]);
+
+  // reversed order, same values: no watcher may fire
+  const watcher = w();
+  const root = tree.get(watcher, TestDynamicRootId1);
+  root.getKeyValue(watcher, "k1");
+  root.getKeyValue(watcher, "k2");
+  tree.updateFromResourceData(
+    kvOf([
+      ["k2", "two"],
+      ["k1", "one"],
+    ]),
+  );
+  expect(watcher.isChanged).toStrictEqual(false);
+
+  // a key inserted before the stored ones, so the walk diverges immediately
+  tree.updateFromResourceData(
+    kvOf([
+      ["k0", "zero"],
+      ["k2", "two"],
+      ["k1", "ONE"],
+    ]),
+  );
+  expect([read("k0"), read("k1"), read("k2")]).toStrictEqual(["zero", "ONE", "two"]);
+
+  // and a deletion
+  tree.updateFromResourceData(kvOf([["k1", "ONE"]]));
+  expect([read("k0"), read("k1"), read("k2")]).toStrictEqual([undefined, "ONE", undefined]);
+});
+
+test("removal of a typed field still throws after a reorder", () => {
+  const tree = new PlTreeState(TestDynamicRootId1, DefaultFinalResourceDataPredicate);
+
+  tree.updateFromResourceData(rootRes([iField("a"), iField("b"), dField("c")]));
+
+  // reordered, and the input field "b" is gone: the removal scan must still see it
+  expect(() => tree.updateFromResourceData(rootRes([dField("c"), iField("a")]))).toThrow(
+    /removal of Input field b/,
+  );
+});