@milaboratories/pl-tree 1.15.6 → 1.16.0

package/src/state.ts

@@ -31,8 +31,8 @@ export type ExtendedResourceData = ResourceData & {
 };
 
 export class TreeStateUpdateError extends Error {
-  constructor(message: string) {
-    super(message);
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
   }
 }
 
@@ -64,6 +64,17 @@ class PlTreeField implements FieldData {
 
 const InitialResourceVersion = 0;
 
+/** Input and Service fields share one list and one lock: both are refused once inputs lock. */
+function isInputLike(type: FieldType): boolean {
+  return type === "Input" || type === "Service";
+}
+
+/** The only field types the backend lets a client delete, so the only ones whose name can come
+ * back under another type between two polls. */
+function isRecreatable(type: FieldType): boolean {
+  return type === "Dynamic" || type === "MTW";
+}
+
 export type ResourceDataWithFinalState = ResourceData & {
   finalState: boolean;
 };
@@ -220,10 +231,24 @@ export class PlTreeResource implements ResourceDataWithFinalState {
 
     const field = this.fieldsMap.get(step.field);
     if (field === undefined) {
-      if (step.errorIfFieldNotFound || step.errorIfFieldNotSet)
+      if (step.errorIfFieldNotFound || step.errorIfFieldNotSet) {
+        // Subscribed before throwing, so the error recomputes when the field appears.
+        if (!this.inputsLocked) this.inputAndServiceFieldListChanged?.attachWatcher(watcher);
+        if (!this.outputsLocked) this.outputFieldListChanged?.attachWatcher(watcher);
+        this.dynamicFieldListChanged?.attachWatcher(watcher);
         throw new Error(
           `Field "${step.field}" not found in resource ${resourceIdToString(this.id)}`,
         );
+      }
+
+      // An asserted type's absence becomes permanent when its list locks, with no field added.
+      if (
+        step.assertFieldType !== undefined &&
+        (isInputLike(step.assertFieldType)
+          ? !this.inputsLocked
+          : step.assertFieldType === "Output" && !this.outputsLocked)
+      )
+        this.lockedChange?.attachWatcher(watcher);
 
       if (!this.inputsLocked) this.inputAndServiceFieldListChanged?.attachWatcher(watcher);
       else if (step.assertFieldType === "Service" || step.assertFieldType === "Input") {
@@ -246,6 +271,9 @@ export class PlTreeResource implements ResourceDataWithFinalState {
 
       return undefined;
     } else {
+      // Subscribed before the type check: a Dynamic or MTW field can come back under another
+      // type, and the refused reader must then be re-run.
+      field.change.attachWatcher(watcher);
       if (step.assertFieldType !== undefined && field.type !== step.assertFieldType)
         throw new Error(
           `Unexpected field type: expected ${step.assertFieldType} but got ${field.type} for the field name ${step.field}`,
@@ -254,12 +282,11 @@ export class PlTreeResource implements ResourceDataWithFinalState {
       const ret = {} as ValueAndError<SignedResourceId>;
       if (isNotNullSignedResourceId(field.value)) ret.value = field.value;
       if (isNotNullSignedResourceId(field.error)) ret.error = field.error;
-      if (ret.value === undefined && ret.error === undefined)
+      if (ret.value === undefined && ret.error === undefined && !this._finalState)
         // this method returns value and error of the field, thus those values are considered to be accessed;
         // any existing but not resolved field here is considered to be unstable, in the sense it is
-        // considered to acquire some resolved value eventually
+        // considered to acquire some resolved value eventually; on a final resource it never will
         onUnstable("field_not_resolved:" + step.field);
-      field.change.attachWatcher(watcher);
       return ret;
     }
   }
@@ -267,14 +294,14 @@ export class PlTreeResource implements ResourceDataWithFinalState {
   public getInputsLocked(watcher: Watcher): boolean {
     if (!this.inputsLocked)
       // reverse transition can't happen, so there is no reason to wait for value to change
-      this.resourceStateChange?.attachWatcher(watcher);
+      this.lockedChange?.attachWatcher(watcher);
     return this.inputsLocked;
   }
 
   public getOutputsLocked(watcher: Watcher): boolean {
     if (!this.outputsLocked)
       // reverse transition can't happen, so there is no reason to wait for value to change
-      this.resourceStateChange?.attachWatcher(watcher);
+      this.lockedChange?.attachWatcher(watcher);
     return this.outputsLocked;
   }
 
@@ -328,10 +355,12 @@ export class PlTreeResource implements ResourceDataWithFinalState {
     return ret;
   }
 
+  /** Fields that are neither Input, Output nor Service. Service fields are input-like (the
+   * backend refuses them once inputs are locked) and are listed by {@link listInputFields}. */
   public listDynamicFields(watcher: Watcher): string[] {
     const ret: string[] = [];
     this.fieldsMap.forEach((field, name) => {
-      if (field.type !== "Input" && field.type !== "Output") ret.push(name);
+      if (!isInputLike(field.type) && field.type !== "Output") ret.push(name);
     });
     this.dynamicFieldListChanged?.attachWatcher(watcher);
 
@@ -397,12 +426,24 @@ export class PlTreeResource implements ResourceDataWithFinalState {
     };
   }
 
-  /** Called when {@link FinalResourceDataPredicate} returns true for the state. */
+  /** Called when {@link FinalResourceDataPredicate} returns true for the state.
+   *
+   * Every change source it retires is fired first: a reader attached to one of them read a
+   * state that could still change, and is re-run to read it as final. */
   markFinal() {
     if (this._finalState) return;
 
     this._finalState = true;
     notEmpty(this.finalChanged).markChanged("marked final");
+    // Field sources are kept (a final resource's fields are still read), but a reader of an
+    // unresolved one read it as unstable, and must be re-run to read it as permanent.
+    this.fieldsMap.forEach((field) => field.change.markChanged("marked final"));
+    this.resourceStateChange?.markChanged("marked final");
+    this.lockedChange?.markChanged("marked final");
+    this.inputAndServiceFieldListChanged?.markChanged("marked final");
+    this.outputFieldListChanged?.markChanged("marked final");
+    this.dynamicFieldListChanged?.markChanged("marked final");
+    this.kvChangedPerKey?.markAllChanged("marked final");
     this.finalChanged = undefined;
     this.resourceStateChange = undefined;
     this.dynamicFieldListChanged = undefined;
@@ -502,9 +543,28 @@ export class PlTreeState {
     return res;
   }
 
+  /** Applies a batch of resource bodies to the mirror.
+   *
+   * Any error leaves the tree invalidated and surfaces as a {@link TreeStateUpdateError}: the
+   * batch is applied resource by resource, so a throw part way through has already mutated the
+   * mirror and fired watchers, and only a rebuild restores a state some poll confirmed. */
   updateFromResourceData(
     resourceData: ExtendedResourceData[],
     opts: { allowOrphanInputs?: boolean; stat?: ResourceUpdateStat } = {},
+  ) {
+    try {
+      this.applyResourceData(resourceData, opts);
+    } catch (e: unknown) {
+      const message = e instanceof Error ? e.message : String(e);
+      if (this._isValid) this.invalidateTree(message);
+      if (e instanceof TreeStateUpdateError) throw e;
+      throw new TreeStateUpdateError(`tree update failed: ${message}`, { cause: e });
+    }
+  }
+
+  private applyResourceData(
+    resourceData: ExtendedResourceData[],
+    opts: { allowOrphanInputs?: boolean; stat?: ResourceUpdateStat },
   ) {
     const { allowOrphanInputs = false, stat } = opts;
     this.checkValid();
@@ -565,7 +625,7 @@ export class PlTreeState {
       let resource = this.resources.get(rd.id);
       const held = resource !== undefined;
       let changed = false;
-      // Structural/metadata change (new or removed field). type and kind are readonly, so
+      // Structural/metadata change (a field added, removed or retyped). type and kind are readonly, so
       // they never change; this flag isolates value/flag-only changes from real metadata churn.
       let metadataChanged = false;
 
@@ -650,7 +710,7 @@ export class PlTreeState {
             if (isNotNullSignedResourceId(fd.value)) incrementRefs.push(fd.value);
             if (isNotNullSignedResourceId(fd.error)) incrementRefs.push(fd.error);
 
-            if (fd.type === "Input" || fd.type === "Service") {
+            if (isInputLike(fd.type)) {
               if (resource.inputsLocked)
                 unexpectedTransitionError(
                   `adding ${fd.type} (${fd.name}) field while inputs locked`,
@@ -680,36 +740,31 @@ export class PlTreeState {
           } else {
             // change of old field
 
-            // in principle this transition is possible, see assertions below
+            // A Dynamic or MTW field deleted and recreated under the same name between two
+            // polls looks like a type change. Any other type is append-only on the backend.
             if (field.type !== fd.type) {
-              if (field.type !== "Dynamic")
+              if (!isRecreatable(field.type))
                 unexpectedTransitionError(`field changed type ${field.type} -> ${fd.type}`);
-              notEmpty(resource.dynamicFieldListChanged).markChanged(
-                `field ${fd.name} changed type from Dynamic to ${fd.type} in ${resourceIdToString(resource.id)}`,
-              );
-              if (field.type === "Input" || field.type === "Service") {
+              const reason = `field ${fd.name} changed type ${field.type} -> ${fd.type} in ${resourceIdToString(resource.id)}`;
+              // the old list: both recreatable types are listed as dynamic
+              notEmpty(resource.dynamicFieldListChanged).markChanged(reason);
+              if (isInputLike(fd.type)) {
                 if (resource.inputsLocked)
                   unexpectedTransitionError(
-                    `adding input field "${fd.name}", while corresponding list is locked`,
+                    `adding ${fd.type} field "${fd.name}", while inputs are locked`,
                   );
-                notEmpty(resource.inputAndServiceFieldListChanged).markChanged(
-                  `field ${fd.name} changed to type ${fd.type} in ${resourceIdToString(resource.id)}`,
-                );
-              }
-              if (field.type === "Output") {
+                notEmpty(resource.inputAndServiceFieldListChanged).markChanged(reason);
+              } else if (fd.type === "Output") {
                 if (resource.outputsLocked)
                   unexpectedTransitionError(
-                    `adding output field "${fd.name}", while corresponding list is locked`,
+                    `adding output field "${fd.name}", while outputs are locked`,
                   );
-                notEmpty(resource.outputFieldListChanged).markChanged(
-                  `field ${fd.name} changed to type ${fd.type} in ${resourceIdToString(resource.id)}`,
-                );
+                notEmpty(resource.outputFieldListChanged).markChanged(reason);
               }
               field.type = fd.type;
-              field.change.markChanged(
-                `field ${fd.name} type changed to ${fd.type} in ${resourceIdToString(resource.id)}`,
-              );
+              field.change.markChanged(reason);
               changed = true;
+              metadataChanged = true;
             }
 
             // field value
@@ -766,6 +821,7 @@ export class PlTreeState {
               `dynamic field ${fieldName} removed from ${resourceIdToString(resource!.id)}`,
             );
             fields.delete(fieldName);
+            changed = true;
             metadataChanged = true;
             if (stat) stat.fieldsRemoved++;
 
@@ -817,6 +873,12 @@ export class PlTreeState {
           if (stat) stat.readyFlips++;
         }
 
+        // backend final flag: informational, no reader watches it
+        if (resource.finalFlag !== rd.final) {
+          resource.finalFlag = rd.final;
+          changed = true;
+        }
+
         // syncing kv. Same lockstep walk as the fields above, for the same reason: kv keys
         // arrive in a stable order and are freshly decoded strings. The walk is only set up
         // when there is something to compare against, so a resource with no kv allocates no
@@ -1023,23 +1085,50 @@ export class PlTreeState {
       // is enough — ordinary refcounting keeps it alive and will collect it later.
       if (res.refCount > 0) continue;
 
-      // collect the (now-unprotected) root itself and seed the cascade with the refs it holds
-      const seed: SignedResourceId[] = [];
-      res.fieldsMap.forEach((field) => {
-        if (isNotNullSignedResourceId(field.value)) seed.push(field.value);
-        if (isNotNullSignedResourceId(field.error)) seed.push(field.error);
-        field.change.markChanged(
-          `field ${field.name} removed after root ${resourceIdToString(res.id)} left the root set`,
-        );
-      });
-      if (isNotNullSignedResourceId(res.error)) seed.push(res.error);
-      res.resourceRemoved.markChanged(
-        `resource removed after leaving the root set: ${resourceIdToString(res.id)}`,
-      );
-      this.resources.delete(rid);
+      this.removeUnreferenced(res, `root ${resourceIdToString(res.id)} left the root set`);
+    }
+  }
 
-      this.collectGarbage(seed);
+  /** Roots held in the heap and not final: the ones whose existence a poll must check, since
+   * a walk seeded at a deleted resource returns nothing rather than an error. A final root is
+   * never re-read, so it is not checked either. */
+  public nonFinalRoots(): SignedResourceId[] {
+    const ret: SignedResourceId[] = [];
+    for (const rid of this.roots) {
+      const res = this.resources.get(rid);
+      if (res !== undefined && !res.finalState) ret.push(rid);
     }
+    return ret;
+  }
+
+  /** Drops from the heap a root the backend has deleted, with the subtree only it held, and
+   * notifies its readers. The id stays in the root set: a resource id is never reused, so the
+   * root stays absent and readers see "not found". Returns false, changing nothing, if the
+   * root is not held or is still referenced from elsewhere in the heap; a root is protected
+   * from the refcount GC, so it is retried once its referrers are gone (the next call, or the
+   * caller's next pass). */
+  public dropDeletedRoot(rid: SignedResourceId): boolean {
+    this.checkValid();
+    const res = this.resources.get(rid);
+    if (res === undefined || res.refCount > 0) return false;
+    this.removeUnreferenced(res, `root ${resourceIdToString(rid)} deleted on the backend`);
+    return true;
+  }
+
+  /** Removes a resource nothing in the heap references and cascades the refcount GC into
+   * what it referenced. */
+  private removeUnreferenced(res: PlTreeResource, reason: string) {
+    const seed: SignedResourceId[] = [];
+    res.fieldsMap.forEach((field) => {
+      if (isNotNullSignedResourceId(field.value)) seed.push(field.value);
+      if (isNotNullSignedResourceId(field.error)) seed.push(field.error);
+      field.change.markChanged(`field ${field.name} removed: ${reason}`);
+    });
+    if (isNotNullSignedResourceId(res.error)) seed.push(res.error);
+    res.resourceRemoved.markChanged(`resource removed: ${reason}`);
+    this.resources.delete(res.id);
+
+    this.collectGarbage(seed);
   }
 
   /** @deprecated use "entry" instead */
@@ -1057,6 +1146,8 @@ export class PlTreeState {
     this._isValid = false;
     this.invalidationMessage = msg;
     this.rootsChanged.markChanged("tree invalidated");
+    // readers whose last run found no resource wait on this, and must learn the tree is gone
+    this.resourcesAdded.markChanged("tree invalidated");
     this.resources.forEach((res) => {
       res.markAllChanged();
     });

package/src/state_notifications.model.test.ts

@@ -0,0 +1,264 @@
+// Notification completeness, as a property: random legal update sequences on one resource,
+// with the readers defined below attached before each update. Any reader whose answer (value
+// or throw, plus stability for plain field reads) differs after the update must have been
+// notified.
+// Sequence n is seeded with n + 1; a failure reports the seed and step of the first
+// violation per reader. MODEL_RUNS sets the number of sequences (default 200; raise it when
+// hunting).
+import { expect, test } from "vitest";
+import type { Watcher } from "@milaboratories/computable";
+import type { FieldData, FieldType } from "@milaboratories/pl-client";
+import {
+  createSignedResourceId,
+  DefaultFinalResourceDataPredicate,
+  NullSignedResourceId,
+} from "@milaboratories/pl-client";
+import type { ExtendedResourceData } from "./state";
+import { PlTreeState } from "./state";
+import {
+  field,
+  InitialStructuralResourceState,
+  TestDynamicRootId1,
+  TestDynamicRootState1,
+  TestValueResourceState1,
+  dField,
+} from "./test_utils";
+
+class W implements Watcher {
+  isChanged = false;
+  markChanged() {
+    this.isChanged = true;
+  }
+}
+const R = createSignedResourceId(10n);
+const V = [createSignedResourceId(20n), createSignedResourceId(21n)];
+const E = createSignedResourceId(30n);
+const RUNS = Number(process.env.MODEL_RUNS ?? 200);
+const STEPS = 25;
+
+function rng(seed: number) {
+  let s = seed >>> 0 || 1;
+  return () => {
+    s ^= s << 13;
+    s >>>= 0;
+    s ^= s >> 17;
+    s ^= s << 5;
+    s >>>= 0;
+    return s / 4294967296;
+  };
+}
+
+type St = {
+  typeName: string;
+  il: boolean;
+  ol: boolean;
+  ready: boolean;
+  err: boolean;
+  final: boolean;
+  fields: Map<string, { type: FieldType; v: number }>;
+  kv: Map<string, string>;
+  removed: Set<string>;
+};
+
+function body(st: St): ExtendedResourceData {
+  const fields: FieldData[] = [...st.fields.entries()].map(([n, f]) =>
+    field(f.type, n, f.v < 0 ? NullSignedResourceId : V[f.v]!, NullSignedResourceId, f.v >= 0),
+  );
+  return {
+    ...InitialStructuralResourceState,
+    id: R,
+    type: { name: st.typeName, version: "1" },
+    inputsLocked: st.il,
+    outputsLocked: st.ol,
+    resourceReady: st.ready,
+    error: st.err ? E : NullSignedResourceId,
+    final: st.final,
+    fields,
+    kv: [...st.kv.entries()].map(([key, v]) => ({ key, value: Buffer.from(v) })),
+  };
+}
+
+const NAMES = ["a", "b", "c", "d"];
+const TYPES: FieldType[] = ["Input", "Output", "Service", "Dynamic", "MTW"];
+
+function mutate(st: St, r: () => number): void {
+  const pick = <T>(xs: T[]) => xs[Math.floor(r() * xs.length)]!;
+  const op = Math.floor(r() * 9);
+  const name = pick(NAMES);
+  const canAdd = (t: FieldType) =>
+    t === "Input" || t === "Service" ? !st.il : t === "Output" ? !st.ol : true;
+  switch (op) {
+    case 0: {
+      if (!st.fields.has(name)) {
+        const t = pick(TYPES);
+        if (canAdd(t)) st.fields.set(name, { type: t, v: -1 });
+      }
+      break;
+    }
+    case 1: {
+      const f = st.fields.get(name);
+      if (f && (f.type === "Dynamic" || f.type === "MTW")) {
+        st.fields.delete(name);
+        if (r() < 0.6) {
+          const t = pick(TYPES);
+          if (canAdd(t)) st.fields.set(name, { type: t, v: -1 });
+        }
+      }
+      break;
+    }
+    case 2: {
+      const f = st.fields.get(name);
+      if (f && (f.v < 0 || f.type === "Dynamic" || f.type === "MTW")) f.v = Math.floor(r() * 2);
+      break;
+    }
+    case 3:
+      st.il = true;
+      break;
+    case 4:
+      if (st.il) st.ol = true;
+      break;
+    case 5:
+      if (st.il) st.ready = true;
+      break;
+    case 6:
+      st.kv.set(pick(["k1", "k2"]), String(Math.floor(r() * 3)));
+      break;
+    case 7:
+      if (r() < 0.3) st.err = true;
+      break;
+    case 8:
+      if (r() < 0.3) st.final = true;
+      break;
+  }
+}
+
+type Reader = { name: string; read: (t: PlTreeState, w: W) => string };
+const readers: Reader[] = [
+  { name: "inputsLocked", read: (t, w) => String(t.get(new W(), R).getInputsLocked(w)) },
+  { name: "outputsLocked", read: (t, w) => String(t.get(new W(), R).getOutputsLocked(w)) },
+  { name: "readyOrError", read: (t, w) => String(t.get(new W(), R).getIsReadyOrError(w)) },
+  { name: "error", read: (t, w) => String(t.get(new W(), R).getError(w)) },
+  { name: "isFinal", read: (t, w) => String(t.get(new W(), R).getIsFinal(w)) },
+  { name: "listInput", read: (t, w) => t.get(new W(), R).listInputFields(w).sort().join() },
+  { name: "listOutput", read: (t, w) => t.get(new W(), R).listOutputFields(w).sort().join() },
+  { name: "listDynamic", read: (t, w) => t.get(new W(), R).listDynamicFields(w).sort().join() },
+  ...["k1", "k2"].map(
+    (k): Reader => ({
+      name: "kv:" + k,
+      read: (t, w) => String(t.get(new W(), R).getKeyValueString(w, k)),
+    }),
+  ),
+  ...NAMES.flatMap((n): Reader[] => [
+    {
+      name: "get:" + n,
+      read: (t, w) => {
+        const u: string[] = [];
+        const v = t.get(new W(), R).getField(w, n, (m) => u.push(m));
+        return JSON.stringify(v) + (u.length ? "|unstable" : "");
+      },
+    },
+    {
+      name: "req:" + n,
+      read: (t, w) =>
+        JSON.stringify(
+          t.get(new W(), R).getField(w, { field: n, errorIfFieldNotFound: true }, () => {}),
+        ),
+    },
+    ...(["Input", "Output", "Dynamic"] as const).map(
+      (ty): Reader => ({
+        name: `assert${ty}:${n}`,
+        read: (t, w) =>
+          JSON.stringify(
+            t
+              .get(new W(), R)
+              .getField(
+                w,
+                { field: n, assertFieldType: ty, allowPermanentAbsence: true },
+                () => {},
+              ),
+          ),
+      }),
+    ),
+  ]),
+];
+function safeRead(rd: Reader, t: PlTreeState, w: W): string {
+  try {
+    return rd.read(t, w);
+  } catch (e) {
+    return "THROW:" + (e instanceof Error ? e.message.replace(/\d+/g, "#") : String(e));
+  }
+}
+
+test("every modeled reader whose answer changes is notified", () => {
+  const violations = new Map<string, number>();
+  const example = new Map<string, string>();
+  let invalidations = 0;
+  for (let run = 0; run < RUNS; run++) {
+    const seed = run + 1;
+    const r = rng(seed);
+    const t = new PlTreeState(TestDynamicRootId1, DefaultFinalResourceDataPredicate);
+    const st: St = {
+      typeName: r() < 0.5 ? "StdMap" : "UserProject",
+      il: false,
+      ol: false,
+      ready: false,
+      err: false,
+      final: false,
+      fields: new Map(),
+      kv: new Map(),
+      removed: new Set(),
+    };
+    const rootB = {
+      ...TestDynamicRootState1,
+      fields: [dField("r", R), dField("v0", V[0]), dField("v1", V[1]), dField("e", E)],
+    };
+    const vals = [...V, E].map((id) => ({
+      ...TestValueResourceState1,
+      id,
+      data: Buffer.from("x"),
+    }));
+    t.updateFromResourceData([rootB, ...vals, body(st)]);
+    for (let step = 0; step < STEPS; step++) {
+      const res = t.get(new W(), R);
+      if (res.finalState) break;
+      const before = readers.map((rd) => {
+        const w = new W();
+        return { rd, w, v: safeRead(rd, t, w) };
+      });
+      const prev = JSON.stringify(body(st));
+      mutate(st, r);
+      if (JSON.stringify(body(st)) === prev) continue;
+      try {
+        t.updateFromResourceData([body(st)]);
+      } catch (e) {
+        invalidations++;
+        if (!example.has("INVALIDATED"))
+          example.set("INVALIDATED", `seed ${seed} step ${step}: ${String(e).slice(0, 200)}`);
+        break;
+      }
+      for (const b of before) {
+        const after = safeRead(b.rd, t, new W());
+        // Oracle exclusion, per the contract at getField's locked branch ("stable absence of
+        // field"): an asserted-type read (in practice Input/Output, whose lists lock) that
+        // answered an absence stays right when a field of another type takes the name.
+        const stableAbsence =
+          b.rd.name.startsWith("assert") &&
+          String(b.v) === "undefined" &&
+          String(after).startsWith("THROW:Unexpected field type");
+        if (String(after) !== String(b.v) && !b.w.isChanged && !stableAbsence) {
+          const key = b.rd.name.replace(/:[a-d]$/, ":*");
+          violations.set(key, (violations.get(key) ?? 0) + 1);
+          if (!example.has(key)) example.set(key, `seed ${seed} step ${step}: ${b.v} -> ${after}`);
+        }
+      }
+    }
+  }
+  expect(
+    { invalidations, violations: [...violations], example: [...example] },
+    `first failure per reader (seed, step): ${[...example.values()].join("; ")}`,
+  ).toEqual({
+    invalidations: 0,
+    violations: [],
+    example: [],
+  });
+});

package/src/sync.ts

@@ -167,6 +167,8 @@ export type TreeLoadingStat = ResourceUpdateStat & {
   /** Delta path: extra rounds spent resolving references a delta body pointed at but the
    * response did not carry. */
   deltaResolutionRounds: number;
+  /** Roots dropped from the mirror because they are absent from the backend. */
+  rootsDropped: number;
   /** Delta path: polls that sent a token and got back a response the size of the whole
    * mirror, which is what a refused token looks like from here - rejection is silent, so this
    * is the only tell. Heuristic: a genuinely large change set trips it too. */
@@ -197,6 +199,7 @@ export function initialTreeLoadingStat(): TreeLoadingStat {
     deltaSeedsSent: 0,
     deltaResolutionRounds: 0,
     deltaSuspectedFullAnswers: 0,
+    rootsDropped: 0,
     resourcesNew: 0,
     resourcesChanged: 0,
     resourcesUnchanged: 0,
@@ -404,9 +407,9 @@ async function processResourceTreeStream(
       resourceReady: frame.resourceReady,
       error: frame.error,
       originalResourceId: frame.originalResourceId,
-      // traverseWasStopped: backend matched traverse stop rules — children were not streamed.
-      // Mark as terminal; fields are resolved below.
-      final: frame.final || frame.traverseWasStopped,
+      // The backend's flag as sent. A stopped traversal (children not streamed) is handled
+      // through the fields below, not by claiming the backend marked the resource final.
+      final: frame.final,
       inputsLocked: frame.inputsLocked,
       outputsLocked: frame.outputsLocked,
       fields: frame.fields,