@synnaxlabs/client 0.56.2 → 0.57.1

package/src/framer/streamer.ts

@@ -8,12 +8,12 @@
 // included in the file licenses/APL.txt.
 
 import { EOF, type Stream, type WebSocketClient } from "@synnaxlabs/freighter";
-import { breaker, errors, observe, Rate, TimeSpan } from "@synnaxlabs/x";
+import { errors, Rate, zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { type channel } from "@/channel";
 import { paramsZ } from "@/channel/payload";
-import { ReadAdapter } from "@/framer/adapter";
+import { type ChannelRetriever, ReadAdapter } from "@/framer/adapter";
 import { WSStreamerCodec } from "@/framer/codec";
 import { Frame, frameZ } from "@/framer/frame";
 import { StreamProxy } from "@/framer/streamProxy";
@@ -51,39 +51,25 @@ const intermediateStreamerConfigZ = z.object({
   excludeGroups: z.uint32().array().default([]),
 });
 
+/** Zod schema for {@link StreamerConfig}. A bare channel list parses as a config. */
 export const streamerConfigZ = intermediateStreamerConfigZ.or(
   paramsZ.transform((channels) => intermediateStreamerConfigZ.parse({ channels })),
 );
 
+/** Config for a streamer. Pass it to `client.telem.openStreamer`. */
 export type StreamerConfig = z.input<typeof streamerConfigZ>;
-type ParsedStreamerConfig = z.output<typeof streamerConfigZ>;
 
 /**
- * A streamer is used to stream frames of telemetry in real-time from a Synnax cluster.
- * It should not be constructed directly, and should instead be created using the
- * client's openStreamer method.
+ * Streams frames of telemetry from a Synnax cluster in real time. Open one with the
+ * client's openStreamer method, never directly. Read frames with `read` or by
+ * iterating the streamer. Close it in a `finally` block to free its resources.
  *
- * To open a streamer, use the openStreamer method on the client and pass it in the list
- * of channels you'd like to receive data from. Once the streamer has been opened, call
- * the `read` method to read the next frame of telemetry, or use the streamer as an
- * async iterator to iterate over the frames of telemetry as they are received.
- *
- * The list of channels being streamed can be updated at any time by using the `update`
- * method.
- *
- * Once done, call the `close` method to close the streamer and free all associated
- * resources. We recommend using the streamer within a try-finally block to ensure
- * that it is closed properly in the event of an error.
- *
- * For detailed documentation, see https://docs.synnaxlabs.com/reference/client/working-with-data/streaming-data
+ * @see https://docs.synnaxlabs.com/reference/client/working-with-data/streaming-data
  */
 export interface Streamer extends AsyncIterator<Frame>, AsyncIterable<Frame> {
   /** The keys of the channels currently being streamed from. */
   keys: channel.Key[];
-  /**
-   * Update the list of channels being streamed from. This replaces the list of channels
-   * being streamed from with the new list of channels.
-   */
+  /** Replaces the list of channels being streamed from. */
   update: (channels: channel.Params) => Promise<void>;
   /** Close the streamer and free all associated resources. */
   close: () => void;
@@ -91,24 +77,22 @@ export interface Streamer extends AsyncIterator<Frame>, AsyncIterable<Frame> {
   read: () => Promise<Frame>;
 }
 
-/**
- * A function that opens a streamer.
- */
+/** A function that opens a streamer. */
 export interface StreamOpener {
   (config: StreamerConfig): Promise<Streamer>;
 }
 
 /**
- * Creates a function that opens streamers with the given retriever and client.
- * @param retriever - The channel retriever to use for resolving channel information
+ * Creates a function that opens streamers with the given channel resolver and client.
+ * @param retrieveChannels - Resolves channel params to payloads for the codec
  * @param client - The WebSocket client to use for streaming
  * @returns A function that opens streamers with the given configuration
  */
 export const createStreamOpener =
-  (retriever: channel.Retriever, client: WebSocketClient): StreamOpener =>
+  (retrieveChannels: ChannelRetriever, client: WebSocketClient): StreamOpener =>
   async (config) => {
-    const cfg = streamerConfigZ.parse(config);
-    const adapter = await ReadAdapter.open(retriever, cfg.channels);
+    const cfg = zod.parse(streamerConfigZ, config, { label: "streamer config" });
+    const adapter = await ReadAdapter.open(retrieveChannels, cfg.channels);
     client = client.withCodec(new WSStreamerCodec(adapter.codec));
     const stream = await client.stream("/frame/stream", reqZ, resZ);
     const streamer = new BaseStreamer(
@@ -130,16 +114,15 @@ export const createStreamOpener =
 
 /**
  * Opens a new streamer with the given configuration.
- * @param retriever - The channel retriever to use for resolving channel information
+ * @param retrieveChannels - Resolves channel params to payloads for the codec
  * @param client - The WebSocket client to use for streaming
- * @param config - The configuration for the streamer
  * @returns A promise that resolves to a new streamer
  */
 export const openStreamer = async (
-  retriever: channel.Retriever,
+  retrieveChannels: ChannelRetriever,
   client: WebSocketClient,
   config: StreamerConfig,
-): Promise<Streamer> => await createStreamOpener(retriever, client)(config);
+): Promise<Streamer> => await createStreamOpener(retrieveChannels, client)(config);
 
 class BaseStreamer implements Streamer {
   private readonly stream: StreamProxy<typeof reqZ, typeof resZ>;
@@ -199,146 +182,3 @@ class BaseStreamer implements Streamer {
     return this;
   }
 }
-
-/**
- * A hardened streamer that automatically reconnects on failure.
- * This streamer wraps a regular streamer and adds automatic reconnection
- * logic when the connection is lost or errors occur.
- */
-export class HardenedStreamer implements Streamer {
-  private wrapped_: Streamer | null = null;
-  private readonly breaker: breaker.Breaker;
-  private readonly opener: StreamOpener;
-  private readonly config: ParsedStreamerConfig;
-
-  private constructor(
-    opener: StreamOpener,
-    config: StreamerConfig,
-    breakerConfig: breaker.Config = {},
-  ) {
-    this.opener = opener;
-    this.config = streamerConfigZ.parse(config);
-    const {
-      maxRetries = 5000,
-      baseInterval = TimeSpan.seconds(1),
-      scale = 1,
-    } = breakerConfig ?? {};
-    this.breaker = new breaker.Breaker({ maxRetries, baseInterval, scale });
-  }
-
-  /**
-   * Opens a new hardened streamer with the given configuration.
-   * @param opener - The function to use for opening streamers
-   * @param config - The configuration for the streamer
-   * @returns A promise that resolves to a new hardened streamer
-   */
-  static async open(
-    opener: StreamOpener,
-    config: StreamerConfig,
-    breakerConfig?: breaker.Config,
-  ): Promise<HardenedStreamer> {
-    const h = new HardenedStreamer(opener, config, breakerConfig);
-    await h.runStreamer();
-    return h;
-  }
-
-  private async runStreamer(): Promise<void> {
-    while (true)
-      try {
-        if (this.wrapped_ != null) this.wrapped_.close();
-        this.wrapped_ = await this.opener(this.config);
-        this.breaker.reset();
-        return;
-      } catch (e) {
-        this.wrapped_ = null;
-        if (!(await this.breaker.wait())) throw errors.fromUnknown(e);
-        console.error("failed to open streamer", e);
-        continue;
-      }
-  }
-
-  private get wrapped(): Streamer {
-    if (this.wrapped_ == null) throw new Error("stream closed");
-    return this.wrapped_;
-  }
-
-  async update(channels: channel.Params): Promise<void> {
-    this.config.channels = paramsZ.parse(channels);
-    try {
-      await this.wrapped.update(channels);
-    } catch {
-      await this.runStreamer();
-      return await this.update(channels);
-    }
-  }
-
-  async next(): Promise<IteratorResult<Frame>> {
-    try {
-      return { done: false, value: await this.read() };
-    } catch (e) {
-      if (EOF.matches(e)) return { done: true, value: undefined };
-      throw errors.fromUnknown(e);
-    }
-  }
-
-  async read(): Promise<Frame> {
-    try {
-      const fr = await this.wrapped.read();
-      this.breaker.reset();
-      return fr;
-    } catch (e) {
-      if (EOF.matches(e)) throw errors.fromUnknown(e);
-      await this.runStreamer();
-      return await this.read();
-    }
-  }
-  close(): void {
-    this.wrapped.close();
-  }
-
-  get keys(): channel.Key[] {
-    return this.wrapped.keys;
-  }
-
-  [Symbol.asyncIterator](): AsyncIterator<Frame> {
-    return this;
-  }
-}
-
-/**
- * Wraps a standard streamer to implement an observable interface for handling changes
- * to channel values through an onChange handler.
- */
-export class ObservableStreamer<V = Frame>
-  extends observe.Observer<Frame, V>
-  implements observe.ObservableAsyncCloseable<V>
-{
-  private readonly streamer: Streamer;
-  private readonly closePromise: Promise<void>;
-
-  /**
-   * Creates a new observable streamer.
-   * @param streamer - The streamer to wrap
-   * @param transform - An optional transform function to apply to each frame
-   * @template V - The type of the transformed value. Only relevant if transform is
-   * provided. Defaults to Frame.
-   */
-  constructor(streamer: Streamer, transform?: observe.Transform<Frame, V>) {
-    super(transform);
-    this.streamer = streamer;
-    this.closePromise = this.stream();
-  }
-
-  async update(channels: channel.Params): Promise<void> {
-    await this.streamer.update(channels);
-  }
-
-  async close(): Promise<void> {
-    this.streamer.close();
-    await this.closePromise;
-  }
-
-  private async stream(): Promise<void> {
-    for await (const frame of this.streamer) this.notify(frame);
-  }
-}

package/src/framer/writer.ts

@@ -18,19 +18,23 @@ import {
 } from "@synnaxlabs/x";
 import { z } from "zod";
 
-import { channel } from "@/channel";
+import { type channel } from "@/channel";
+import { paramsZ } from "@/channel/payload";
+import { keyZ, nameZ } from "@/channel/types.gen";
 import { SynnaxError } from "@/errors";
-import { WriteAdapter } from "@/framer/adapter";
+import { type ChannelRetriever, WriteAdapter } from "@/framer/adapter";
 import { WSWriterCodec } from "@/framer/codec";
 import { type CrudeFrame, frameZ } from "@/framer/frame";
 import { WriterCommand } from "@/framer/types.gen";
 
+/** Whether a writer persists its samples, streams them to subscribers, or both. */
 export enum WriterMode {
   PersistStream = 1,
   Persist = 2,
   Stream = 3,
 }
 
+/** `autoIndexPersistInterval` that flushes the index on every auto commit. */
 export const ALWAYS_INDEX_PERSIST_ON_AUTO_COMMIT: TimeSpan = new TimeSpan(-1);
 
 export class WriterClosedError extends SynnaxError.sub("writer_closed") {
@@ -52,6 +56,7 @@ const writerModeZ = z.enum(WriterMode).or(
   }),
 );
 
+/** A {@link WriterMode}, or its name as a string. */
 export type CrudeWriterMode = z.input<typeof writerModeZ>;
 
 const baseWriterConfigZ = z.object({
@@ -96,22 +101,24 @@ const baseWriterConfigZ = z.object({
 });
 
 const netWriterConfigZ = baseWriterConfigZ.extend({
-  keys: channel.keyZ.array().optional(),
+  keys: keyZ.array().optional(),
 });
 
 export type NetWriterConfig = z.input<typeof netWriterConfigZ>;
 
 // Intermediate utility type to allow for the use of paramsZ in the writer config.
 const intermediateWriterConfigZ = baseWriterConfigZ.extend({
-  channels: channel.paramsZ,
+  channels: paramsZ,
 });
 
+/** Zod schema for {@link WriterConfig}. A bare channel list parses as a config. */
 export const writerConfigZ = intermediateWriterConfigZ.or(
-  channel.paramsZ.transform((channels) =>
+  paramsZ.transform((channels) =>
     intermediateWriterConfigZ.parse({ channels, start: TimeStamp.now() }),
   ),
 );
 
+/** Config for a writer. Pass it to `client.telem.openWriter`. */
 export type WriterConfig = z.input<typeof writerConfigZ>;
 
 const reqZ = z.object({
@@ -129,11 +136,11 @@ const resZ = z.object({
   err: errors.payloadZ.optional(),
 });
 
-const authorityArgsZ = z
+const authorityParamsZ = z
   .tuple([
     z.union([
-      z.record(channel.keyZ.or(channel.nameZ), control.authorityZ),
-      channel.keyZ.or(channel.nameZ),
+      z.record(keyZ.or(nameZ), control.authorityZ),
+      keyZ.or(nameZ),
       control.authorityZ,
     ]),
     control.authorityZ.optional(),
@@ -141,7 +148,7 @@ const authorityArgsZ = z
   .transform(([value, authority]) => {
     if (control.authorityZ.safeParse(value).success)
       return { keys: [], authorities: [value as control.Authority] };
-    if (channel.keyZ.or(channel.nameZ).safeParse(value).success) {
+    if (keyZ.or(nameZ).safeParse(value).success) {
       if (authority == null)
         throw new Error(
           "authority is required when setting authority for a single channel",
@@ -155,49 +162,25 @@ const authorityArgsZ = z
     return { keys: Object.keys(oValue), authorities: Object.values(oValue) };
   });
 
-export type AuthorityArgs = z.input<typeof authorityArgsZ>;
+/**
+ * Arguments to `Writer.setAuthority`: one authority for every channel, one channel and
+ * its authority, or a record of channel to authority.
+ */
+export type AuthorityParams = z.input<typeof authorityParamsZ>;
 
 interface Response extends z.infer<typeof resZ> {}
 
 /**
- * Writer is used to write telemetry to a set of channels in time order. It should not
- * be instantiated directly, and should instead be instantiated via the FramerClient
- * {@link FrameClient#openWriter}.
- *
- * The writer is a streaming protocol that is heavily optimized for performance. This
- * comes at the cost of increased complexity, and should only be used directly when
- * writing large volumes of data (such as recording telemetry from a sensor or ingesting
- * data from file). Simpler methods (such as the frame client's write method) should be
- * used for most use cases.
- *
- * The protocol is as follows:
- *
- * 1. The writer is opened with a starting timestamp and a list of channel keys. The
- *    writer will fail to open if the starting timestamp overlaps with any existing
- *    telemetry for any channels specified. If the writer opens successfully, the caller
- *    is then free to write frames to the writer.
+ * Writes telemetry to a set of channels in time order. Open one with
+ * {@link FrameClient#openWriter}, never directly. Prefer the frame client's write
+ * method unless the volume warrants the streaming protocol.
  *
- * 2. To write a frame, the caller can use the write method and follow the validation
- *    rules described in its method's documentation. This process is asynchronous,
- *    meaning that write calls may return before the frame has been written to the
- *    cluster. This also means that the writer can accumulate an error after write is
- *    called. If the writer accumulates an error, all subsequent write and commit calls
- *    will return False. The caller can check for errors by calling the error method,
- *    which returns the accumulated error and resets the writer for future use. The
- *    caller can also check for errors by closing the writer, which will throw any
- *    accumulated error.
- *
- * 3. To commit the written frames to the cluster, the caller can call the commit
- *    method. Unlike write, commit is synchronous, meaning that it will not return until
- *    the frames have been written to the cluster. If the writer has accumulated an
- *    error, commit will return false. After the caller acknowledges the error, they can
- *    attempt to commit again. Commit can be called several times throughout a writer's
- *    lifetime, and will only commit the frames that have been written since the last
- *    commit.
- *
- * 4. A writer MUST be closed after use in order to prevent resource leaks. Close should
- *    typically be called in a 'finally' block. If the writer has accumulated an error,
- *    close will throw the error.
+ * Opening fails when the start timestamp overlaps existing telemetry on any of the
+ * channels. `write` is asynchronous, so a failure surfaces on a later call: once the
+ * writer accumulates an error, every write and commit returns false until `error`
+ * reads and clears it. `commit` blocks until the cluster has the frames written since
+ * the last commit, and may be called repeatedly. Close in a `finally` block to release
+ * resources; close throws any accumulated error.
  */
 export class Writer {
   private readonly stream: Stream<typeof reqZ, typeof resZ>;
@@ -210,12 +193,12 @@ export class Writer {
   }
 
   static async _open(
-    retriever: channel.Retriever,
+    retrieveChannels: ChannelRetriever,
     client: WebSocketClient,
     config: WriterConfig,
   ): Promise<Writer> {
     const cfg = zod.parse(writerConfigZ, config);
-    const adapter = await WriteAdapter.open(retriever, cfg.channels);
+    const adapter = await WriteAdapter.open(retrieveChannels, cfg.channels);
     client = client.withCodec(new WSWriterCodec(adapter.codec));
     const stream = await client.stream("/frame/write", reqZ, resZ);
     const writer = new Writer(stream, adapter);
@@ -236,9 +219,7 @@ export class Writer {
   ): Promise<void>;
   async write(
     channelsOrData:
-      | channel.Params
-      | Record<channel.Key | channel.Name, CrudeSeries>
-      | CrudeFrame,
+      channel.Params | Record<channel.Key | channel.Name, CrudeSeries> | CrudeFrame,
     series?: CrudeSeries | CrudeSeries[],
   ): Promise<void>;
 
@@ -259,9 +240,7 @@ export class Writer {
    */
   async write(
     channelsOrData:
-      | channel.Params
-      | Record<channel.Key | channel.Name, CrudeSeries>
-      | CrudeFrame,
+      channel.Params | Record<channel.Key | channel.Name, CrudeSeries> | CrudeFrame,
     series?: CrudeSeries | CrudeSeries[],
   ): Promise<void> {
     if (this.closeErr != null) throw this.closeErr;
@@ -275,11 +254,13 @@ export class Writer {
   }
 
   async setAuthority(
-    value: AuthorityArgs[0],
-    authority?: AuthorityArgs[1],
+    value: AuthorityParams[0],
+    authority?: AuthorityParams[1],
   ): Promise<void> {
     if (this.closeErr != null) throw this.closeErr;
-    const parsed = authorityArgsZ.parse([value, authority]);
+    const parsed = zod.parse(authorityParamsZ, [value, authority], {
+      label: "authority params",
+    });
     const config = {
       keys: await this.adapter.adaptParams(parsed.keys),
       authorities: parsed.authorities,
@@ -290,7 +271,6 @@ export class Writer {
   /**
    * Commits the written frames to the database. Commit is synchronous, meaning that it
    * will not return until all frames have been committed to the database.
-   *
    * @returns the timestamp of the last sample written to the writer.
    * @throws if the commit fails or any previous writer method has thrown. Once commit
    * throws, the writer must be closed and re-opened to continue use.

package/src/group/client.ts

@@ -8,11 +8,13 @@
 // included in the file licenses/APL.txt.
 
 import { type UnaryClient } from "@synnaxlabs/freighter";
-import { array } from "@synnaxlabs/x";
+import { array, zod } from "@synnaxlabs/x";
 import z from "zod";
 
-import { type Group, groupZ, type Key, keyZ } from "@/group/types.gen";
+import { type Group, groupZ, type Key, keyZ, ontologyID } from "@/group/types.gen";
+import { ontology } from "@/ontology";
 import { idZ as ontologyIDZ } from "@/ontology/payload";
+import { query } from "@/query";
 
 export const SET_CHANNEL_NAME = "sy_group_set";
 export const DELETE_CHANNEL_NAME = "sy_group_delete";
@@ -29,40 +31,173 @@ const renameReqZ = z.object({ key: keyZ, name: z.string() });
 
 const deleteReqZ = z.object({ keys: z.array(keyZ) });
 
-export interface CreateArgs extends z.infer<typeof createReqZ> {}
+export interface CreateParams extends z.infer<typeof createReqZ> {}
 
-export class Client {
-  client: UnaryClient;
+const retrieveChildrenParamsZ = z.object({
+  parent: ontologyIDZ,
+  searchTerm: z.string().optional(),
+  offset: z.int().optional(),
+  limit: z.int().optional(),
+});
+
+export type RetrieveSingleParams = { key: Key };
+export type RetrieveChildrenParams = z.input<typeof retrieveChildrenParamsZ>;
+export type RetrieveParams = RetrieveSingleParams | RetrieveChildrenParams;
+
+interface ChildrenRequest extends z.infer<typeof retrieveChildrenParamsZ> {}
+
+const isChildOf = (rel: ontology.Relationship, parent: ontology.ID): boolean =>
+  ontology.matchRelationship(rel, {
+    from: parent,
+    type: ontology.PARENT_OF_RELATIONSHIP_TYPE,
+    to: { type: "group" },
+  });
 
-  constructor(client: UnaryClient) {
-    this.client = client;
+export interface ClientConfig {
+  unary: UnaryClient;
+  ontology: ontology.Client;
+  cache: query.Cache;
+}
+
+export class Client extends query.Retriever<
+  typeof retrieveChildrenParamsZ,
+  Key,
+  Group
+> {
+  /** Public so a client that deletes a group through an endpoint of its own can drop
+   * the group from the cache. */
+  readonly store: query.Table<Key, Group>;
+  private readonly cfg: ClientConfig;
+
+  constructor(cfg: ClientConfig) {
+    const { cache, ontology: ontologyClient } = cfg;
+    const store = cache.createTable<Key, Group>({
+      name: "groups",
+      fetch: async (keys) => await this.execRetrieveKeys(keys),
+      listen: [
+        query.createSetListener(SET_CHANNEL_NAME, groupZ),
+        query.createDeleteListener(DELETE_CHANNEL_NAME, keyZ),
+      ],
+    });
+    super(cache, {
+      name: "group",
+      table: store,
+      request: {
+        schema: retrieveChildrenParamsZ,
+        fetch: async (req) => await this.fetchChildren(req),
+        matches: (g, req) => this.isCachedChild(req.parent, g.key),
+        watch: [
+          query.watch(
+            ontologyClient.cache.relationships,
+            (event, req: ChildrenRequest) => {
+              const rel =
+                event.variant === "set"
+                  ? event.value
+                  : ontology.relationshipZ.parse(event.key);
+              if (!isChildOf(rel, req.parent)) return null;
+              return [rel.to.key];
+            },
+          ),
+        ],
+      },
+    });
+    this.cfg = cfg;
+    this.store = store;
   }
 
-  async create(args: CreateArgs): Promise<Group> {
-    const res = await this.client.send(
+  async create(params: CreateParams): Promise<Group> {
+    const res = await this.cfg.unary.send(
       "/ontology/create-group",
-      args,
+      params,
       createReqZ,
       resZ,
     );
+    this.store.set(res.group);
+    const rel: ontology.Relationship = {
+      from: params.parent,
+      type: ontology.PARENT_OF_RELATIONSHIP_TYPE,
+      to: ontologyID(res.group.key),
+    };
+    this.cfg.ontology.cache.relationships.set(ontology.relationshipToString(rel), rel);
     return res.group;
   }
 
-  async rename(key: Key, name: string): Promise<void> {
-    await this.client.send(
-      "/ontology/rename-group",
-      { key, name },
-      renameReqZ,
-      z.object({}),
-    );
+  async rename(key: Key, name: string, opts: query.WriteOptions = {}): Promise<void> {
+    const rename = () => [
+      query.partialUpdate(this.store, key, { name }),
+      this.cfg.ontology.cache.renameResource(ontologyID(key), name),
+    ];
+    await query.optimistic({
+      rollbacks: rename(),
+      onOptimistic: opts.onOptimistic,
+      commit: async () =>
+        await this.cfg.unary.send(
+          "/ontology/rename-group",
+          { key, name },
+          renameReqZ,
+          z.object({}),
+        ),
+    });
+    rename();
   }
 
-  async delete(keys: Key | Key[]): Promise<void> {
-    await this.client.send(
-      "/ontology/delete-group",
-      { keys: array.toArray(keys) },
-      deleteReqZ,
-      z.object({}),
+  async delete(keys: Key | Key[], opts: query.WriteOptions = {}): Promise<void> {
+    const keysArr = array.toArray(keys);
+    const drop = () => this.store.delete(keysArr);
+    await query.optimistic({
+      rollbacks: [drop()],
+      onOptimistic: opts.onOptimistic,
+      commit: async () =>
+        await this.cfg.unary.send(
+          "/ontology/delete-group",
+          { keys: keysArr },
+          deleteReqZ,
+          z.object({}),
+        ),
+    });
+    drop();
+  }
+
+  private isCachedChild(parent: ontology.ID, key: Key): boolean {
+    return this.cfg.ontology.cache.relationships.has(
+      ontology.relationshipToString({
+        from: parent,
+        type: ontology.PARENT_OF_RELATIONSHIP_TYPE,
+        to: ontologyID(key),
+      }),
     );
   }
+
+  private requireOntology(): ontology.Client {
+    if (this.cfg.ontology == null)
+      throw new Error("ontology client is not available on this client");
+    return this.cfg.ontology;
+  }
+
+  private async execRetrieveKeys(keys: Key[]): Promise<Group[]> {
+    const res = await this.requireOntology().retrieve({
+      ids: keys.map((key) => ontologyID(key)),
+    });
+    return res.map((r) => zod.parse(groupZ, r.data, { label: "group" }));
+  }
+
+  private async fetchChildren(req: ChildrenRequest): Promise<Group[]> {
+    const { parent, ...options } = req;
+    const res = await this.requireOntology().children.retrieve({
+      ids: parent,
+      ...options,
+      types: ["group"],
+    });
+    const groups = res.map((r) => zod.parse(groupZ, r.data, { label: "group" }));
+    const rels = this.cfg.ontology.cache.relationships;
+    groups.forEach((g) => {
+      const rel: ontology.Relationship = {
+        from: parent,
+        type: ontology.PARENT_OF_RELATIONSHIP_TYPE,
+        to: ontologyID(g.key),
+      };
+      rels.set(ontology.relationshipToString(rel), rel);
+    });
+    return groups;
+  }
 }