@synnaxlabs/client 0.57.0 → 0.57.2

package/src/framer/cache/dynamic.ts

@@ -13,6 +13,8 @@ import {
   math,
   MultiSeries,
   Series,
+  Size,
+  TimeRange,
   type TimeSpan,
   TimeStamp,
 } from "@synnaxlabs/x";
@@ -52,6 +54,34 @@ const MAX_DEF_WRITES = 100;
 // Variable-rate types allocate bytes, not samples. Rough bytes-per-sample estimate.
 const VARIABLE_DT_MULTIPLIER = 40;
 
+/**
+ * @returns true when every byte of the series fits in the buffer's free space. Measured
+ * in bytes because a variable-length buffer counts its capacity that way.
+ */
+const fits = (buffer: Series, series: Series): boolean =>
+  series.byteLength.valueOf() <=
+  buffer.byteCapacity.valueOf() - buffer.byteLength.valueOf();
+
+// Bounds on compacting a buffer that rotated early. Both have to trip: the fraction
+// spares a nearly full buffer, the floor one whose waste is not worth a copy.
+const COMPACT_MAX_FILL = 0.25;
+const COMPACT_MIN_WASTE = Size.kilobytes(256);
+
+/**
+ * @returns true when copying the buffer's samples into a right-sized series is worth
+ * the copy. A held buffer never qualifies: the holder keeps the original alive, so a
+ * copy would only add a second allocation, and it would break the object identity a
+ * consumer that both reads and streams deduplicates on.
+ */
+const shouldCompact = (buffer: Series): boolean => {
+  if (buffer.refCount > 0 || buffer.length === 0) return false;
+  const used = buffer.byteLength.valueOf();
+  const capacity = buffer.byteCapacity.valueOf();
+  return (
+    capacity - used > COMPACT_MIN_WASTE.valueOf() && used < capacity * COMPACT_MAX_FILL
+  );
+};
+
 /**
  * A cache for channel data that maintains a single, rolling Series as a buffer
  * for channel data. The buffer's data type is derived from the first written series,
@@ -96,6 +126,17 @@ export class Dynamic {
     return this.curr;
   }
 
+  /**
+   * @returns the time range the buffer's samples actually cover: its start to the last
+   * stamped write, or the wall clock when the buffer holds unstamped data. Unlike the
+   * buffer's provisional time range, the end never claims future time. Null when there
+   * is no buffer.
+   */
+  get dataTimeRange(): TimeRange | null {
+    if (this.curr == null) return null;
+    return new TimeRange(this.curr.timeRange.start, this.currDataEnd ?? this.now());
+  }
+
   /**
    * @returns a list of buffers that were filled by the cache during the write. If the
    * current buffer is able to fit all writes, no buffers will be returned.
@@ -115,7 +156,6 @@ export class Dynamic {
     alignment: bigint,
     start: TimeStamp,
     source: Series,
-    sampleIndex: number,
   ): Series {
     this.counter++;
     const dt = this.props.transform.resolveDataType(source.dataType);
@@ -127,8 +167,7 @@ export class Dynamic {
     let sampleOffset: math.Numeric = 0;
     if (narrowing)
       if (source.dataType.equals(DataType.TIMESTAMP)) sampleOffset = start.valueOf();
-      else if (sampleIndex < source.length)
-        sampleOffset = BigInt(source.data[sampleIndex].valueOf());
+      else if (source.length > 0) sampleOffset = BigInt(source.data[0].valueOf());
     return Series.alloc({
       capacity: dt.isVariable ? capacity * VARIABLE_DT_MULTIPLIER : capacity,
       dataType: dt,
@@ -140,6 +179,18 @@ export class Dynamic {
     });
   }
 
+  /**
+   * @returns the sample capacity for a buffer that must hold the given series whole:
+   * the configured size, or the series' own size when that is larger.
+   */
+  private capacityFor(source: Series): number {
+    const dt = this.props.transform.resolveDataType(source.dataType);
+    const required = dt.isVariable
+      ? Math.ceil(source.byteLength.valueOf() / VARIABLE_DT_MULTIPLIER)
+      : source.length;
+    return Math.max(this.nextBufferSize(), required);
+  }
+
   // Unstamped series (virtual channels, writes without an in-frame index) fall back
   // to the wall clock.
   private allocStart(series: Series): TimeStamp {
@@ -148,28 +199,41 @@ export class Dynamic {
 
   private allocCurr(
     res: WriteResponse,
-    alignment: bigint,
-    start: TimeStamp,
     source: Series,
-    sampleIndex: number,
+    start: TimeStamp | null,
   ): Series {
     this.curr = this.allocate(
-      this.nextBufferSize(),
-      alignment,
-      start,
+      this.capacityFor(source),
+      source.alignment,
+      start ?? this.allocStart(source),
       source,
-      sampleIndex,
     );
     res.allocated.push(this.curr);
     return this.curr;
   }
 
-  private flushCurr(res: WriteResponse): void {
-    if (this.curr == null) return;
-    this.curr.timeRange.end = this.currDataEnd ?? this.now();
+  /** @returns the timestamp the flushed buffer's end was stamped with, or null when
+   * there was no buffer. */
+  private flushCurr(res: WriteResponse): TimeStamp | null {
+    if (this.curr == null) return null;
+    const end = this.currDataEnd ?? this.now();
+    this.curr.timeRange.end = end;
     this.currDataEnd = null;
-    res.flushed.push(this.curr);
+    res.flushed.push(this.compacted(this.curr, res));
     this.curr = null;
+    return end;
+  }
+
+  /**
+   * @returns a right-sized copy of a buffer that rotated with most of its space
+   * unused, or the buffer itself. A rotated buffer holds its whole allocation until
+   * it is collected, which is wasteful when an oversized series ended it early.
+   */
+  private compacted(buffer: Series, res: WriteResponse): Series {
+    // A buffer allocated during this same write has not reached its subscribers yet,
+    // so its reference count cannot yet report who is about to hold it.
+    if (!shouldCompact(buffer) || res.allocated.series.includes(buffer)) return buffer;
+    return buffer.compact();
   }
 
   private _write(series: Series, res: WriteResponse): void {
@@ -194,9 +258,8 @@ export class Dynamic {
       }
     }
     let curr = this.curr;
-    if (curr == null)
-      curr = this.allocCurr(res, series.alignment, this.allocStart(series), series, 0);
-    else {
+    let trimmed = false;
+    if (curr != null) {
       // overlap > 0: the incoming series steps back into samples the current buffer
       // already holds. overlap < 0: there is a gap between the buffer and the series.
       const overlap = Number(curr.alignment + BigInt(curr.length) - series.alignment);
@@ -205,38 +268,36 @@ export class Dynamic {
         // the cache with overlapping series. sub() is zero-copy.
         if (overlap >= series.length) return;
         series = series.sub(overlap);
+        trimmed = true;
       } else if (overlap < 0) {
         this.flushCurr(res);
-        curr = this.allocCurr(
-          res,
-          series.alignment,
-          this.allocStart(series),
-          series,
-          0,
-        );
+        curr = null;
       }
     }
-    while (true) {
-      const converted = transform.convert(series, curr.sampleOffset);
-      const amountWritten = curr.write(converted);
-      if (amountWritten === series.length) {
-        this.currDataEnd = series.timeRange.isZero ? null : series.timeRange.end;
-        this.updateAvgRate(series);
-        return;
+    const convert = (buffer: Series): Series =>
+      transform.convert(series, buffer.sampleOffset);
+    let rotationStart: TimeStamp | null = null;
+    if (curr != null) {
+      const converted = convert(curr);
+      // A series never splits across two buffers. The timestamp where a split falls is
+      // not in the data, so both sides would have to guess the boundary they share, and
+      // a guess lands outside the data whenever samples are irregular.
+      if (fits(curr, converted)) curr.write(converted);
+      else {
+        const end = this.flushCurr(res);
+        // A trimmed series keeps the whole frame's start, which is earlier than the
+        // samples it still holds. Those samples begin where the buffer they were
+        // trimmed against ends, so the next buffer starts there.
+        if (trimmed) rotationStart = end;
+        curr = null;
       }
-      // The timestamp at the split point is unknowable from the data series, so
-      // both sides fall back to the wall clock.
-      this.currDataEnd = null;
-      this.flushCurr(res);
-      curr = this.allocCurr(
-        res,
-        series.alignment + BigInt(amountWritten),
-        this.now(),
-        series,
-        amountWritten,
-      );
-      series = series.slice(amountWritten);
     }
+    if (curr == null) {
+      curr = this.allocCurr(res, series, rotationStart);
+      curr.write(convert(curr));
+    }
+    this.currDataEnd = series.timeRange.isZero ? null : series.timeRange.end;
+    this.updateAvgRate(series);
   }
 
   private updateAvgRate(series: Series): void {

package/src/framer/cache/reader.ts

@@ -7,11 +7,12 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
+import { Unreachable } from "@synnaxlabs/freighter";
 import {
   debounce,
+  errors,
   MultiSeries,
   type Series,
-  sync,
   TimeRange,
   TimeSpan,
 } from "@synnaxlabs/x";
@@ -31,10 +32,18 @@ interface ReadRequest {
   gaps: TimeRange[];
 }
 
+// Tracks one read's outstanding fetches, so the read settles when its last fetch lands.
+// The first failure among them wins.
+interface Tracker {
+  entry: debounce.Entry<ReadRequest>;
+  remaining: number;
+  failure?: unknown;
+}
+
 interface BatchFetch {
   gap: TimeRange;
   channels: Set<channel.Key>;
-  entries: Set<debounce.Entry<ReadRequest>>;
+  trackers: Set<Tracker>;
 }
 
 export interface ReaderProps {
@@ -53,17 +62,25 @@ export interface ReaderProps {
    * @default TimeSpan.milliseconds(5)
    */
   overlapThreshold?: TimeSpan;
+  /**
+   * Deadline for a single remote fetch. A fetch that does not settle within it rejects
+   * the reads it serves with an Unreachable error.
+   * @default TimeSpan.seconds(30)
+   */
+  fetchTimeout?: TimeSpan;
 }
 
 /**
  * Reads historical telemetry, serving from the cache and batch-filling gaps from the
- * server. A batch failure rejects only the reads whose gaps were in the failed fetch.
+ * server. A fetch failure rejects only the reads whose gaps were in the failed fetch.
  */
 export class Reader {
   private readonly props: Required<Omit<ReaderProps, "batchDebounce">>;
   private readonly batcher: debounce.Batcher<ReadRequest>;
-  // Serializes batch execution against close, so close waits for the batch in flight.
-  private readonly mu = sync.newMutex({ closed: false });
+  private closed = false;
+  // Reads whose fetches are in flight, so close can reject them without waiting on the
+  // fetches themselves.
+  private readonly inFlight = new Set<Tracker>();
 
   constructor(props: ReaderProps) {
     const {
@@ -71,90 +88,144 @@ export class Reader {
       cache,
       batchDebounce = TimeSpan.milliseconds(50),
       overlapThreshold = TimeSpan.milliseconds(5),
+      fetchTimeout = TimeSpan.seconds(30),
     } = props;
-    this.props = { readRemote, cache, overlapThreshold };
+    this.props = { readRemote, cache, overlapThreshold, fetchTimeout };
     this.batcher = new debounce.Batcher({
       interval: batchDebounce,
-      exec: async (entries) =>
-        await this.mu.runExclusive(async () => {
-          if (this.mu.closed) throw new UnexpectedError("telemetry reader is closed");
-          await this.batchRead(entries);
-        }),
+      exec: async (entries) => {
+        if (this.closed) throw new UnexpectedError("telemetry reader is closed");
+        await this.batchRead(entries);
+      },
     });
   }
 
   /**
    * Reads the given time range for the given channel.
    * @throws {UnexpectedError} if the reader is closed while the read is pending.
+   * @throws {Unreachable} if a fetch serving the read exceeds the fetch timeout.
    */
   async read(tr: TimeRange, channel: channel.Key): Promise<MultiSeries> {
     const { cache } = this.props;
     const unary = cache.get(channel);
     const { series, gaps } = unary.read(tr);
     if (gaps.length === 0) return series;
-    if (this.mu.closed) throw new UnexpectedError("telemetry reader is closed");
+    if (this.closed) throw new UnexpectedError("telemetry reader is closed");
     await this.batcher.enqueue({ channel, gaps });
     return unary.read(tr).series;
   }
 
   private async batchRead(entries: Array<debounce.Entry<ReadRequest>>): Promise<void> {
-    const { readRemote, cache, overlapThreshold } = this.props;
+    const { cache, overlapThreshold } = this.props;
     const batched: BatchFetch[] = [];
+    const trackers = new Map<debounce.Entry<ReadRequest>, Tracker>();
     entries.forEach((entry) => {
       const unary = cache.get(entry.req.channel);
       entry.req.gaps.forEach((rawGap) => {
-        // A concurrent batch or a streaming write may have filled part of the gap
-        // while this entry sat in the debounce window.
+        // An earlier batch or a streaming write may have filled part of the gap while
+        // this entry sat in the debounce window.
         unary.read(rawGap).gaps.forEach((gap) => {
+          let tracker = trackers.get(entry);
+          if (tracker == null) {
+            tracker = { entry, remaining: 0 };
+            trackers.set(entry, tracker);
+            this.inFlight.add(tracker);
+          }
           const g = batched.find((r) => r.gap.equals(gap, overlapThreshold));
-          if (g == null)
+          if (g == null) {
             batched.push({
               gap,
               channels: new Set([entry.req.channel]),
-              entries: new Set([entry]),
+              trackers: new Set([tracker]),
             });
-          else {
+            tracker.remaining++;
+          } else {
             g.channels.add(entry.req.channel);
             g.gap = TimeRange.max(g.gap, gap);
-            g.entries.add(entry);
+            if (!g.trackers.has(tracker)) {
+              g.trackers.add(tracker);
+              tracker.remaining++;
+            }
           }
         });
       });
     });
-    const failures = new Map<debounce.Entry<ReadRequest>, unknown>();
-    await Promise.all(
-      batched.map(async ({ gap, channels, entries: served }) => {
-        try {
-          const frame = await readRemote(gap, Array.from(channels));
-          // Group series by key in one pass; per-key get() scans the whole frame.
-          const grouped = new Map<channel.Key, Series[]>();
-          frame.forEach((k, s) => {
-            const key = k as channel.Key;
-            const existing = grouped.get(key);
-            if (existing == null) grouped.set(key, [s]);
-            else existing.push(s);
-          });
-          channels.forEach((key) =>
-            cache.get(key).writeStatic(new MultiSeries(grouped.get(key) ?? [])),
-          );
-        } catch (err) {
-          served.forEach((entry) => {
-            if (!failures.has(entry)) failures.set(entry, err);
-          });
-        }
-      }),
-    );
     entries.forEach((entry) => {
-      const err = failures.get(entry);
-      if (err == null) entry.resolve();
-      else entry.reject(err);
+      if (!trackers.has(entry)) entry.resolve();
     });
+    await Promise.all(batched.map(async (b) => await this.fetchGap(b)));
   }
 
-  async close(): Promise<void> {
-    this.batcher.close(new UnexpectedError("telemetry reader is closed"));
-    await this.mu.runExclusive(async () => {
-      this.mu.closed = true;
+  // Never throws: every outcome, including a deadline expiry and a post-close arrival,
+  // settles through the trackers.
+  private async fetchGap({ gap, channels, trackers }: BatchFetch): Promise<void> {
+    const { cache } = this.props;
+    let failure: unknown;
+    try {
+      const frame = await this.fetchWithDeadline(gap, Array.from(channels));
+      if (!this.closed) {
+        // Group series by key in one pass; per-key get() scans the whole frame.
+        const grouped = new Map<channel.Key, Series[]>();
+        frame.forEach((k, s) => {
+          const key = k as channel.Key;
+          const existing = grouped.get(key);
+          if (existing == null) grouped.set(key, [s]);
+          else existing.push(s);
+        });
+        channels.forEach((key) =>
+          cache.get(key).writeStatic(new MultiSeries(grouped.get(key) ?? [])),
+        );
+      }
+    } catch (err) {
+      failure = err;
+    }
+    trackers.forEach((tracker) => {
+      // close() already settled it.
+      if (!this.inFlight.has(tracker)) return;
+      if (failure != null) tracker.failure ??= failure;
+      tracker.remaining--;
+      if (tracker.remaining > 0) return;
+      this.inFlight.delete(tracker);
+      if (tracker.failure == null) tracker.entry.resolve();
+      else tracker.entry.reject(tracker.failure);
     });
   }
+
+  private async fetchWithDeadline(
+    gap: TimeRange,
+    channels: channel.Key[],
+  ): Promise<Frame> {
+    const { readRemote, fetchTimeout } = this.props;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const deadline = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        const timeout = fetchTimeout.toString();
+        const message = `gap read for ${gap.toString()} timed out after ${timeout}`;
+        reject(new Unreachable({ message }));
+      }, fetchTimeout.milliseconds);
+    });
+    const fetched = readRemote(gap, channels);
+    try {
+      return await Promise.race([fetched, deadline]);
+    } catch (err) {
+      // The read already failed for its callers; a late settle of the losing fetch must
+      // not surface as an unhandled rejection.
+      fetched.catch(() => {});
+      throw errors.fromUnknown(err);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Closes the reader, rejecting every pending read with an UnexpectedError. In-flight
+   * fetch results are discarded when they arrive.
+   */
+  async close(): Promise<void> {
+    this.closed = true;
+    const err = new UnexpectedError("telemetry reader is closed");
+    this.batcher.close(err);
+    this.inFlight.forEach(({ entry }) => entry.reject(err));
+    this.inFlight.clear();
+  }
 }

package/src/framer/cache/unary.ts

@@ -71,17 +71,21 @@ export class Unary {
   }
 
   /**
-   * Reads cached data overlapping the given time range. The result includes the
-   * live leading buffer when it overlaps, but the buffer never claims coverage:
-   * its samples carry provisional leading alignments that cannot pair with fetched
-   * data on another channel, so its span is still reported as a gap to fetch. A
+   * Reads cached data overlapping the given time range. The result includes the live
+   * leading buffer when the data it actually holds overlaps the range, judged by the
+   * last stamped write rather than the buffer's provisional MAX end, so the buffer
+   * never leaks into reads of spans it has no samples for. It never claims coverage
+   * either: its samples carry provisional leading alignments that cannot pair with
+   * fetched data on another channel, so its span is still reported as a gap to fetch. A
    * span may therefore return in both its streamed and fetched representation.
    */
   read(tr: TimeRange): DirtyReadResult {
     this.checkOpen("read");
     const res = this.static.dirtyRead(tr);
     const buf = this.dynamic.leadingBuffer;
-    if (buf == null || buf.length === 0 || !buf.timeRange.overlapsWith(tr)) return res;
+    const dataTr = this.dynamic.dataTimeRange;
+    if (buf == null || dataTr == null || buf.length === 0 || !dataTr.overlapsWith(tr))
+      return res;
     res.series.push(buf);
     return res;
   }

package/src/index.ts

@@ -25,6 +25,7 @@ export * from "@/connection";
 export { control } from "@/control";
 export { device } from "@/device";
 export {
+  AccessDeniedError,
   AuthError,
   ContiguityError,
   DisconnectedError,

package/src/label/store.ts

@@ -21,8 +21,13 @@ export const matchLabeledBy = (rel: ontology.Relationship, id: ontology.ID): boo
 
 /** Returns the cached labels attached to the given ontology ID. */
 export const cachedLabelsOf = (
-  relationships: query.Table<string, ontology.Relationship>,
+  cache: ontology.Cache,
   labels: query.Table<Key, Label>,
   id: ontology.ID,
 ): Label[] =>
-  labels.get(relationships.get((r) => matchLabeledBy(r, id)).map((r) => r.to.key));
+  labels.get(
+    cache
+      .relationshipsFrom(id)
+      .filter((r) => r.type === LABELED_BY_ONTOLOGY_RELATIONSHIP_TYPE)
+      .map((r) => r.to.key),
+  );

package/src/ontology/client.ts

@@ -35,6 +35,7 @@ import {
   Cache,
   RELATIONSHIP_DELETE_CHANNEL_NAME,
   RELATIONSHIP_SET_CHANNEL_NAME,
+  type RelationshipIndexes,
   RESOURCE_DELETE_CHANNEL_NAME,
   RESOURCE_SET_CHANNEL_NAME,
 } from "@/ontology/store";
@@ -194,10 +195,15 @@ export class Client extends query.Retriever<
 
   constructor(cfg: ClientConfig) {
     const { unary, cache } = cfg;
+    const relationshipIndexes: RelationshipIndexes = {
+      byTo: new query.LookupIndex<string, Relationship>((r) => idToString(r.to)),
+      byFrom: new query.LookupIndex<string, Relationship>((r) => idToString(r.from)),
+    };
     const relationships = cache.createTable<string, Relationship>({
       name: "relationships",
       equal: (a, b) =>
         idsEqual(a.from, b.from) && idsEqual(a.to, b.to) && a.type === b.type,
+      indexes: [relationshipIndexes.byTo, relationshipIndexes.byFrom],
       listen: [
         query.createSetListener(RELATIONSHIP_SET_CHANNEL_NAME, relationshipZ, {
           key: (changed) => relationshipToString(changed),
@@ -244,7 +250,7 @@ export class Client extends query.Retriever<
     });
     this.cfg = cfg;
     this.writer = new Writer(unary);
-    this.cache = new Cache(relationships, resources);
+    this.cache = new Cache(relationships, resources, relationshipIndexes);
     this.children = this.dependentSurface(cache, "children", "to");
     this.parents = this.dependentSurface(cache, "parents", "from");
   }
@@ -466,13 +472,14 @@ export class Client extends query.Retriever<
   ): boolean {
     if (q.types != null && !q.types.includes(resource.id.type)) return false;
     const anchor = oppositeRelationshipDirection(direction);
-    return (
-      this.cache.relationships.get(
-        (rel) =>
-          rel.type === PARENT_OF_RELATIONSHIP_TYPE &&
-          q.ids.includes(idToString(rel[anchor])) &&
-          idsEqual(rel[direction], resource.id),
-      ).length > 0
+    const rels =
+      direction === "to"
+        ? this.cache.relationshipsTo(resource.id)
+        : this.cache.relationshipsFrom(resource.id);
+    return rels.some(
+      (rel) =>
+        rel.type === PARENT_OF_RELATIONSHIP_TYPE &&
+        q.ids.includes(idToString(rel[anchor])),
     );
   }
 

package/src/ontology/store.ts

@@ -13,7 +13,6 @@ import {
   type ID,
   idsEqual,
   idToString,
-  matchRelationship,
   PARENT_OF_RELATIONSHIP_TYPE,
   type Relationship,
   type Resource,
@@ -26,26 +25,49 @@ export const RESOURCE_DELETE_CHANNEL_NAME = "sy_ontology_resource_delete";
 export const RELATIONSHIP_SET_CHANNEL_NAME = "sy_ontology_relationship_set";
 export const RELATIONSHIP_DELETE_CHANNEL_NAME = "sy_ontology_relationship_delete";
 
+/**
+ * The secondary indexes registered on the relationships table, one per endpoint.
+ * Type filtering runs at the call site over the matched handful.
+ */
+export interface RelationshipIndexes {
+  /** Keyed by the stringified `to` end. */
+  byTo: query.LookupIndex<string, Relationship>;
+  /** Keyed by the stringified `from` end. */
+  byFrom: query.LookupIndex<string, Relationship>;
+}
+
 /** The ontology record tables: resources and the relationships between them. */
 export class Cache {
   readonly relationships: query.Table<string, Relationship>;
   readonly resources: query.Table<string, Resource>;
+  private readonly indexes: RelationshipIndexes;
 
   constructor(
     relationships: query.Table<string, Relationship>,
     resources: query.Table<string, Resource>,
+    indexes: RelationshipIndexes,
   ) {
     this.relationships = relationships;
     this.resources = resources;
+    this.indexes = indexes;
+  }
+
+  /** Returns the cached relationships pointing at the given ID. */
+  relationshipsTo(id: ID): Relationship[] {
+    return this.indexes.byTo.get(idToString(id));
+  }
+
+  /** Returns the cached relationships originating at the given ID. */
+  relationshipsFrom(id: ID): Relationship[] {
+    return this.indexes.byFrom.get(idToString(id));
   }
 
   /** Returns the cached parent ID of the given ontology ID, or null if unknown. */
   parentID(id: ID): ID | null {
-    const res = this.relationships.get((r) =>
-      matchRelationship(r, { type: PARENT_OF_RELATIONSHIP_TYPE, to: id }),
+    const rel = this.relationshipsTo(id).find(
+      (r) => r.type === PARENT_OF_RELATIONSHIP_TYPE,
     );
-    if (res.length === 0) return null;
-    return res[0].from;
+    return rel?.from ?? null;
   }
 
   /**

package/src/query/external.ts

@@ -15,6 +15,7 @@ export {
 } from "@/query/cache";
 export { Deleted } from "@/query/deleted";
 export { type DeriveWatch, deriveWatch } from "@/query/derived";
+export { LookupIndex } from "@/query/indexes";
 export {
   type Cached,
   type ChangeHandler,