@misofm/musicos 0.2.0 → 0.3.0

package/src/queries.ts

@@ -6,22 +6,31 @@
 // tracks the on-chain ABI). Generic-type discovery (by share type / by owner)
 // uses GraphQL to find object addresses, then reads them through the Core path.
 //
-// Missing-object convention (null vs throw):
-//   - Core-object getters in this module (`getCompositionById`,
-//     `get*AdminCapById`, …) THROW when the object is missing. Callers pass ids
-//     they obtained from the chain, so a miss means a broken reference — an
-//     exceptional state, not a normal one.
-//   - Extension dynamic-field readers return `null` — extension data is optional
-//     by design, and "not attached" is a normal, expected state. Use
-//     `getExtensionField` with the generated BCS codec for the extension.
-// All null-returning readers use {@link isNotFound} to distinguish a missing
-// object from a transport failure (which still throws).
-
-import type { ClientWithCoreApi } from "@mysten/sui/client";
-import type { SuiGraphQLClient } from "@mysten/sui/graphql";
+// Every read requires the `SuiClient` service (and `SuiGraphQL` for the
+// type-discovery reads) instead of taking a client parameter — see
+// `@misofm/effect`. Not-found is a typed `ObjectNotFoundError`; a BCS decode
+// failure (including a wrong on-chain type, which fails to parse against the
+// expected ABI) is a typed `BcsDecodeError`. Extension dynamic-field readers
+// return `Option.none()` for "not attached" — extension data is optional by
+// design, and absence is a normal, expected state, not a failure.
+
+import { ConflictingWorkKindError } from "./errors.ts";
+import { Effect, Option, Schema } from "effect";
 import { graphql } from "@mysten/sui/graphql/schema";
 import { deriveObjectID, normalizeSuiAddress } from "@mysten/sui/utils";
 
+import {
+  type BcsParser,
+  BcsDecodeError,
+  decodeBcs,
+  getObjectContent,
+  getObjectsContent,
+  ObjectNotFoundError,
+  SuiClient,
+  SuiGraphQL,
+  SuiRpcError,
+} from "@misofm/effect";
+
 import { Composition as CompositionBcs } from "./contracts/musicos/composition.ts";
 import { Recording as RecordingBcs } from "./contracts/musicos/recording.ts";
 import {
@@ -29,20 +38,22 @@ import {
   ReleaseRegistry as ReleaseRegistryBcs,
 } from "./contracts/musicos/release.ts";
 import {
-  mapBps,
   mapComposition,
   mapRecording,
   mapRelease,
 } from "./internal.ts";
-import type {
+import {
   Composition,
   CompositionAdminCap,
   Recording,
   RecordingAdminCap,
   Release,
   ReleaseAdminCap,
+  ReleaseRegistry,
 } from "./types.ts";
 
+export type { BcsParser };
+
 // ============================================================================
 // Helpers
 // ============================================================================
@@ -73,70 +84,86 @@ export function extractTypeParams2(objectType: string): [string, string] {
   throw new Error(`Expected two type parameters in: ${objectType}`);
 }
 
+/** Key bytes for Move unit structs (single `0x00` for `dummy_field: bool = false`). */
+const UNIT_STRUCT_KEY_BYTES = new Uint8Array([0x00]);
+
 /**
- * True when `e` is a "this object does not exist" error from any of the Sui
- * client transports, so null-returning readers can distinguish absence from
- * transport failure. Matches, in order of preference:
+ * True when `e` is a "this object/dynamic field does not exist" error from any
+ * of the Sui client transports. This mirrors `@misofm/effect`'s internal
+ * classifier (not exported, since `getObjectContent` already covers the common
+ * case) — needed here for the reads that don't go through it: type-only object
+ * reads (no `content`) and dynamic-field reads. Matches, in order of
+ * preference:
  *
  *   1. Structured `ObjectError.code` values thrown by the JSON-RPC core client
  *      (`notExists`, `deleted`, `dynamicFieldNotFound`) and the GraphQL core
- *      client (`notFound`). The class itself is not exported by `@mysten/sui`,
- *      so we duck-type on `code`.
+ *      client (`notFound`).
  *   2. The message shapes those clients (and the gRPC core client, which wraps
- *      the server's per-object status message in a plain `Error`) produce:
- *      "Object 0x… does not exist" / "Object 0x… not found" / "Object 0x… has
- *      been deleted" / "Dynamic field not found for object 0x…" / "No object
- *      found for id 0x…".
- *
- * Transport/protocol errors must NOT match: every message pattern requires
- * object-ish context ("object" / "dynamic field"), so e.g. a JSON-RPC
- * "Method not found" or a gRPC "peer not found" is never treated as a missing
- * object and propagates to the caller.
+ *      the server's per-object status message in a plain `Error`) produce.
  */
-export function isNotFound(e: unknown): boolean {
+function isMissingObjectError(e: unknown): boolean {
   if (typeof e === "object" && e !== null && "code" in e) {
     const code = (e as { code: unknown }).code;
-    if (
-      code === "notExists" ||
-      code === "deleted" ||
-      code === "dynamicFieldNotFound" ||
-      code === "notFound"
-    ) {
+    if (code === "notExists" || code === "deleted" || code === "dynamicFieldNotFound" || code === "notFound") {
       return true;
     }
   }
   const msg = e instanceof Error ? e.message : String(e);
   return (
-    /\bobject\b[\s\S]*\b(?:not\s?found|does not exist|has been deleted)\b/i.test(
-      msg,
-    ) ||
+    /\bobject\b[\s\S]*\b(?:not\s?found|does not exist|has been deleted)\b/i.test(msg) ||
     /\bdynamic field\b[\s\S]*\bnot\s?found\b/i.test(msg) ||
     /\bno object\b/i.test(msg)
   );
 }
 
-/** Key bytes for Move unit structs (single `0x00` for `dummy_field: bool = false`). */
-const UNIT_STRUCT_KEY_BYTES = new Uint8Array([0x00]);
-
-/** Any generated BCS codec with a `parse` method. */
-export interface BcsParser<T> {
-  parse(bytes: Uint8Array): T;
+/** Classifies a Core API rejection against `objectId`: missing -> `ObjectNotFoundError`, else `SuiRpcError`. */
+function classifyMissing(objectId: string, operation: string, cause: unknown): ObjectNotFoundError | SuiRpcError {
+  return isMissingObjectError(cause) ? new ObjectNotFoundError({ objectId }) : new SuiRpcError({ operation, cause });
 }
 
+/** Fetches just an object's on-chain `type` (no content) through the Core API. */
+const getObjectType = Effect.fn("getObjectType")(function* (
+  objectId: string,
+): Effect.fn.Return<string, ObjectNotFoundError | SuiRpcError, SuiClient> {
+  const client = yield* SuiClient;
+  const { object } = yield* Effect.tryPromise({
+    try: (signal) => client.core.getObject({ objectId, signal }),
+    catch: (cause) => classifyMissing(objectId, "getObject", cause),
+  });
+  return object.type;
+});
+
+/** Fetches one dynamic field's raw BCS value bytes; not-found becomes `ObjectNotFoundError`. */
+const getDynamicFieldValue = Effect.fn("getDynamicFieldValue")(function* (
+  parentId: string,
+  name: { type: string; bcs: Uint8Array },
+): Effect.fn.Return<Uint8Array, ObjectNotFoundError | SuiRpcError, SuiClient> {
+  const client = yield* SuiClient;
+  const { dynamicField } = yield* Effect.tryPromise({
+    try: (signal) => client.core.getDynamicField({ parentId, name, signal }),
+    catch: (cause) => classifyMissing(parentId, "getDynamicField", cause),
+  });
+  return dynamicField.value.bcs;
+});
+
 /** Exhaust every Core owned-object page; cap discovery must not truncate. */
-async function listAllOwnedObjects(
-  client: ClientWithCoreApi,
+const listAllOwnedObjects = Effect.fn("listAllOwnedObjects")(function* (
   input: Record<string, unknown>,
-): Promise<Array<{ objectId: string; type?: string; json?: unknown }>> {
+): Effect.fn.Return<Array<{ objectId: string; type?: string; json?: unknown }>, SuiRpcError, SuiClient> {
+  const client = yield* SuiClient;
   const objects: Array<{ objectId: string; type?: string; json?: unknown }> = [];
   let cursor: string | null | undefined;
   do {
-    const page = await (client.core.listOwnedObjects as (args: unknown) => Promise<{
-      objects: Array<{ objectId: string; type?: string; json?: unknown }>;
-      pageInfo?: { hasNextPage?: boolean; endCursor?: string | null };
-      hasNextPage?: boolean;
-      cursor?: string | null;
-    }>)(cursor ? { ...input, cursor } : input);
+    const page = yield* Effect.tryPromise({
+      try: (signal) =>
+        (client.core.listOwnedObjects as (args: unknown) => Promise<{
+          objects: Array<{ objectId: string; type?: string; json?: unknown }>;
+          pageInfo?: { hasNextPage?: boolean; endCursor?: string | null };
+          hasNextPage?: boolean;
+          cursor?: string | null;
+        }>)(cursor ? { ...input, cursor, signal } : { ...input, signal }),
+      catch: (cause) => new SuiRpcError({ operation: "listOwnedObjects", cause }),
+    });
     objects.push(...page.objects);
     cursor = page.pageInfo?.hasNextPage
       ? page.pageInfo.endCursor
@@ -145,33 +172,22 @@ async function listAllOwnedObjects(
         : null;
   } while (cursor);
   return objects;
-}
-
-/** Fetches one object's BCS content bytes (or null if absent). */
-async function getContent(
-  client: ClientWithCoreApi,
-  objectId: string,
-): Promise<Uint8Array | null> {
-  const { object } = await client.core.getObject({
-    objectId,
-    include: { content: true },
-  });
-  return object.content ?? null;
-}
+});
 
 /**
- * Fetch and parse an object through the transport-neutral Core API. Object
- * content is BCS; never pass the full `objectBcs` envelope to a Move codec.
+ * Fetch and parse an object through the transport-neutral Core API, validating
+ * the parsed result against a domain `Schema`. Object content is BCS; never
+ * pass the full `objectBcs` envelope to a Move codec.
  */
-export async function getObjectByBcs<T>(
-  client: ClientWithCoreApi,
+export const getObjectByBcs = Effect.fn("getObjectByBcs")(function* <P, A>(
   objectId: string,
-  codec: BcsParser<T>,
-): Promise<T> {
-  const content = await getContent(client, objectId);
-  if (!content) throw new Error(`Object not found: ${objectId}`);
-  return codec.parse(content);
-}
+  codec: BcsParser<P>,
+  schema: Schema.Codec<A, any, never, never>,
+  typeName: string,
+): Effect.fn.Return<A, ObjectNotFoundError | SuiRpcError | BcsDecodeError, SuiClient> {
+  const { content } = yield* getObjectContent(objectId);
+  return yield* decodeBcs(codec, schema, content, { type: typeName, objectId });
+});
 
 export interface ExtensionFieldParams<T> {
   /** Freshly published package address for the extension. */
@@ -185,27 +201,20 @@ export interface ExtensionFieldParams<T> {
 /**
  * Read an optional first-party extension field from a core object's UID. Every
  * current extension uses a fieldless `ExtensionKey`, whose BCS is one false
- * boolean byte. Absence returns `null`; transport errors still propagate.
+ * boolean byte. Absence resolves to `Option.none()`; transport errors still fail.
  */
-export async function getExtensionField<T>(
-  client: ClientWithCoreApi,
+export const getExtensionField = Effect.fn("getExtensionField")(function* <T>(
   parentId: string,
   params: ExtensionFieldParams<T>,
-): Promise<T | null> {
-  try {
-    const { dynamicField } = await client.core.getDynamicField({
-      parentId,
-      name: {
-        type: `${params.packageId}::${params.module}::ExtensionKey`,
-        bcs: UNIT_STRUCT_KEY_BYTES,
-      },
-    });
-    return params.codec.parse(dynamicField.value.bcs);
-  } catch (error) {
-    if (isNotFound(error)) return null;
-    throw error;
-  }
-}
+): Effect.fn.Return<Option.Option<T>, SuiRpcError, SuiClient> {
+  return yield* getDynamicFieldValue(parentId, {
+    type: `${params.packageId}::${params.module}::ExtensionKey`,
+    bcs: UNIT_STRUCT_KEY_BYTES,
+  }).pipe(
+    Effect.map((bytes) => Option.some(params.codec.parse(bytes))),
+    Effect.catchTag("ObjectNotFoundError", () => Effect.succeed(Option.none<T>())),
+  );
+});
 
 export interface ReleaseDspFieldParams<T> {
   /** Freshly published `release_dsp_link` package address. */
@@ -216,46 +225,37 @@ export interface ReleaseDspFieldParams<T> {
   codec: BcsParser<T>;
 }
 
-async function getReleaseDspField<T>(
-  client: ClientWithCoreApi,
+const getReleaseDspField = Effect.fn("getReleaseDspField")(function* <T>(
   releaseId: string,
   key: "ReleaseLinkKey" | "TrackLinksKey",
   params: ReleaseDspFieldParams<T>,
-): Promise<T | null> {
+): Effect.fn.Return<Option.Option<T>, SuiRpcError, SuiClient> {
   if (!Number.isInteger(params.platform) || params.platform < 0 || params.platform > 255) {
     throw new Error("DSP platform must be a u8 discriminator");
   }
-  try {
-    const { dynamicField } = await client.core.getDynamicField({
-      parentId: releaseId,
-      name: {
-        type: `${params.packageId}::release_dsp_link::${key}`,
-        bcs: Uint8Array.of(params.platform),
-      },
-    });
-    return params.codec.parse(dynamicField.value.bcs);
-  } catch (error) {
-    if (isNotFound(error)) return null;
-    throw error;
-  }
-}
+  return yield* getDynamicFieldValue(releaseId, {
+    type: `${params.packageId}::release_dsp_link::${key}`,
+    bcs: Uint8Array.of(params.platform),
+  }).pipe(
+    Effect.map((bytes) => Option.some(params.codec.parse(bytes))),
+    Effect.catchTag("ObjectNotFoundError", () => Effect.succeed(Option.none<T>())),
+  );
+});
 
 /** Read a release-level DSP link stored under `ReleaseLinkKey(platform)`. */
 export function getReleaseDspLink<T>(
-  client: ClientWithCoreApi,
   releaseId: string,
   params: ReleaseDspFieldParams<T>,
-): Promise<T | null> {
-  return getReleaseDspField(client, releaseId, "ReleaseLinkKey", params);
+): Effect.Effect<Option.Option<T>, SuiRpcError, SuiClient> {
+  return getReleaseDspField(releaseId, "ReleaseLinkKey", params);
 }
 
 /** Read the per-track DSP-link array stored under `TrackLinksKey(platform)`. */
 export function getTrackDspLinks<T>(
-  client: ClientWithCoreApi,
   releaseId: string,
   params: ReleaseDspFieldParams<T>,
-): Promise<T | null> {
-  return getReleaseDspField(client, releaseId, "TrackLinksKey", params);
+): Effect.Effect<Option.Option<T>, SuiRpcError, SuiClient> {
+  return getReleaseDspField(releaseId, "TrackLinksKey", params);
 }
 
 // ============================================================================
@@ -263,11 +263,10 @@ export function getTrackDspLinks<T>(
 // ============================================================================
 
 /** Parse the shared canonical core `miso::release::ReleaseRegistry` by ID. */
-export async function getReleaseRegistryById(
-  client: ClientWithCoreApi,
+export function getReleaseRegistryById(
   registryId: string,
-) {
-  return getObjectByBcs(client, registryId, ReleaseRegistryBcs);
+): Effect.Effect<ReleaseRegistry, ObjectNotFoundError | SuiRpcError | BcsDecodeError, SuiClient> {
+  return getObjectByBcs(registryId, ReleaseRegistryBcs, ReleaseRegistry, "ReleaseRegistry");
 }
 
 // ============================================================================
@@ -339,16 +338,17 @@ interface WorkAddressConnection {
  * exposes the first, so one bare Recording scan is shared by every requested
  * recording type and filtered client-side.
  */
-export async function getWorkAddressesByShareTypes(
-  client: SuiGraphQLClient,
+export const getWorkAddressesByShareTypes = Effect.fn("getWorkAddressesByShareTypes")(function* (
   shareTypes: WorkShareTypes,
   misoPackageId: string,
-): Promise<WorkAddressesByShareType> {
+): Effect.fn.Return<WorkAddressesByShareType, SuiRpcError, SuiGraphQL> {
   const compositions = [...new Set(shareTypes.compositions)];
   const recordings = new Set(shareTypes.recordings);
   const out: WorkAddressesByShareType = { compositions: {}, recordings: {} };
   if (compositions.length === 0 && recordings.size === 0) return out;
 
+  const client = yield* SuiGraphQL;
+
   const declarations: string[] = [];
   const selections: string[] = [];
   const variables: Record<string, string> = {};
@@ -359,8 +359,7 @@ export async function getWorkAddressesByShareTypes(
     selections.push(
       `composition${index}: objects(first: 1, filter: { type: $${variable} }) { nodes { address } }`,
     );
-    variables[variable] =
-      `${misoPackageId}::composition::Composition<${shareType}>`;
+    variables[variable] = `${misoPackageId}::composition::Composition<${shareType}>`;
   });
 
   if (recordings.size > 0) {
@@ -372,20 +371,24 @@ export async function getWorkAddressesByShareTypes(
     variables.recordingType = `${misoPackageId}::recording::Recording`;
   }
 
-  const result = await client.query<
-    Record<string, WorkAddressConnection | null>,
-    Record<string, string>
-  >({
-    query: `query WorkAddressesByShareTypes(${declarations.join(", ")}) {
-      ${selections.join("\n")}
-    }`,
-    variables,
+  const result = yield* Effect.tryPromise({
+    try: () =>
+      client.query<Record<string, WorkAddressConnection | null>, Record<string, string>>({
+        query: `query WorkAddressesByShareTypes(${declarations.join(", ")}) {
+          ${selections.join("\n")}
+        }`,
+        variables,
+      }),
+    catch: (cause) => new SuiRpcError({ operation: "workAddressesByShareTypes", cause }),
   });
   if (result.errors?.length) {
-    throw new AggregateError(
-      result.errors.map((error) => new Error(error.message)),
-      "Work type discovery failed",
-    );
+    return yield* new SuiRpcError({
+      operation: "workAddressesByShareTypes",
+      cause: new AggregateError(
+        result.errors.map((error) => new Error(error.message)),
+        "Work type discovery failed",
+      ),
+    });
   }
 
   compositions.forEach((shareType, index) => {
@@ -393,9 +396,7 @@ export async function getWorkAddressesByShareTypes(
     if (address) out.compositions[shareType] = address;
   });
 
-  const readRecordingPage = (
-    page: WorkAddressConnection | null | undefined,
-  ) => {
+  const readRecordingPage = (page: WorkAddressConnection | null | undefined) => {
     for (const node of page?.nodes ?? []) {
       const repr = node.asMoveObject?.contents?.type?.repr;
       if (!repr) continue;
@@ -417,33 +418,35 @@ export async function getWorkAddressesByShareTypes(
     recordingPage.pageInfo.endCursor &&
     Object.keys(out.recordings).length < recordings.size
   ) {
-    const next = await client.query<
-      { recordings: WorkAddressConnection | null },
-      { recordingType: string; cursor: string }
-    >({
-      query: `query RecordingWorkAddresses($recordingType: String!, $cursor: String!) {
-        recordings: objects(first: 50, after: $cursor, filter: { type: $recordingType }) {
-          pageInfo { hasNextPage endCursor }
-          nodes { address asMoveObject { contents { type { repr } } } }
-        }
-      }`,
-      variables: {
-        recordingType: variables.recordingType!,
-        cursor: recordingPage.pageInfo.endCursor,
-      },
+    const cursor: string = recordingPage.pageInfo.endCursor;
+    const next = yield* Effect.tryPromise({
+      try: () =>
+        client.query<{ recordings: WorkAddressConnection | null }, { recordingType: string; cursor: string }>({
+          query: `query RecordingWorkAddresses($recordingType: String!, $cursor: String!) {
+            recordings: objects(first: 50, after: $cursor, filter: { type: $recordingType }) {
+              pageInfo { hasNextPage endCursor }
+              nodes { address asMoveObject { contents { type { repr } } } }
+            }
+          }`,
+          variables: { recordingType: variables.recordingType!, cursor },
+        }),
+      catch: (cause) => new SuiRpcError({ operation: "recordingWorkAddresses", cause }),
     });
     if (next.errors?.length) {
-      throw new AggregateError(
-        next.errors.map((error) => new Error(error.message)),
-        "Recording type discovery failed",
-      );
+      return yield* new SuiRpcError({
+        operation: "recordingWorkAddresses",
+        cause: new AggregateError(
+          next.errors.map((error) => new Error(error.message)),
+          "Recording type discovery failed",
+        ),
+      });
     }
     recordingPage = next.data?.recordings;
     readRecordingPage(recordingPage);
   }
 
   return out;
-}
+});
 
 export interface WorkIds {
   compositions: readonly string[];
@@ -458,21 +461,16 @@ export interface WorksById {
 }
 
 /** Fetch and parse heterogeneous work objects through one Core bulk request. */
-export async function getWorksByIds(
-  client: ClientWithCoreApi,
+export const getWorksByIds = Effect.fn("getWorksByIds")(function* (
   ids: WorkIds,
-): Promise<WorksById> {
+): Effect.fn.Return<WorksById, ConflictingWorkKindError | SuiRpcError | BcsDecodeError, SuiClient> {
   const kinds = new Map<string, keyof WorksById>();
-  for (const [kind, objectIds] of Object.entries(ids) as Array<
-    [keyof WorksById, readonly string[]]
-  >) {
+  for (const [kind, objectIds] of Object.entries(ids) as Array<[keyof WorksById, readonly string[]]>) {
     for (const objectId of objectIds) {
       const normalized = normalizeSuiAddress(objectId);
       const previous = kinds.get(normalized);
       if (previous && previous !== kind) {
-        throw new Error(
-          `Work ${normalized} was requested as both ${previous} and ${kind}`,
-        );
+        return yield* new ConflictingWorkKindError({ objectId: normalized, kinds: [previous, kind] });
       }
       kinds.set(normalized, kind);
     }
@@ -481,93 +479,95 @@ export async function getWorksByIds(
   const out: WorksById = { compositions: {}, recordings: {}, releases: {} };
   if (kinds.size === 0) return out;
 
-  const { objects } = await client.core.getObjects({
-    objectIds: [...kinds.keys()],
-    include: { content: true },
-  });
-  for (const obj of objects) {
-    if (obj instanceof Error || !obj.content) continue;
-    const kind = kinds.get(normalizeSuiAddress(obj.objectId));
-    if (kind === "compositions") {
-      out.compositions[obj.objectId] = mapComposition(
-        obj.objectId,
-        CompositionBcs.parse(obj.content),
-      );
-    } else if (kind === "recordings") {
-      out.recordings[obj.objectId] = mapRecording(
-        obj.objectId,
-        RecordingBcs.parse(obj.content),
-      );
-    } else if (kind === "releases") {
-      out.releases[obj.objectId] = mapRelease(
-        obj.objectId,
-        ReleaseBcs.parse(obj.content),
-      );
-    }
-  }
+  const contents = yield* getObjectsContent([...kinds.keys()]);
+  yield* Effect.forEach(
+    [...contents.entries()],
+    ([objectId, { content }]) =>
+      Effect.gen(function* () {
+        const kind = kinds.get(normalizeSuiAddress(objectId));
+        if (kind === "compositions") {
+          out.compositions[objectId] = yield* decodeBcs(
+            { parse: (bytes) => mapComposition(objectId, CompositionBcs.parse(bytes)) },
+            Composition,
+            content,
+            { type: "Composition", objectId },
+          );
+        } else if (kind === "recordings") {
+          out.recordings[objectId] = yield* decodeBcs(
+            { parse: (bytes) => mapRecording(objectId, RecordingBcs.parse(bytes)) },
+            Recording,
+            content,
+            { type: "Recording", objectId },
+          );
+        } else if (kind === "releases") {
+          out.releases[objectId] = yield* decodeBcs(
+            { parse: (bytes) => mapRelease(objectId, ReleaseBcs.parse(bytes)) },
+            Release,
+            content,
+            { type: "Release", objectId },
+          );
+        }
+      }),
+    { concurrency: "unbounded" },
+  );
   return out;
-}
+});
 
 // ============================================================================
 // Composition
 // ============================================================================
 
 /** Fetches multiple compositions by ID in one Core request. */
-export async function getCompositionsByIds(
-  client: ClientWithCoreApi,
+export const getCompositionsByIds = Effect.fn("getCompositionsByIds")(function* (
   compositionIds: string[],
-): Promise<Record<string, Composition>> {
+): Effect.fn.Return<Record<string, Composition>, SuiRpcError | BcsDecodeError, SuiClient> {
   if (compositionIds.length === 0) return {};
-  const { objects } = await client.core.getObjects({
-    objectIds: compositionIds,
-    include: { content: true },
-  });
-  const out: Record<string, Composition> = {};
-  for (const obj of objects) {
-    if (obj instanceof Error || !obj.content) continue;
-    out[obj.objectId] = mapComposition(
-      obj.objectId,
-      CompositionBcs.parse(obj.content),
-    );
-  }
-  return out;
-}
+  const contents = yield* getObjectsContent(compositionIds);
+  const decoded = yield* Effect.forEach(
+    [...contents.entries()],
+    ([objectId, { content }]) =>
+      decodeBcs(
+        { parse: (bytes) => mapComposition(objectId, CompositionBcs.parse(bytes)) },
+        Composition,
+        content,
+        { type: "Composition", objectId },
+      ).pipe(Effect.map((composition) => [objectId, composition] as const)),
+    { concurrency: "unbounded" },
+  );
+  return Object.fromEntries(decoded);
+});
 
 /** Fetches a composition by its object ID. */
-export async function getCompositionById(
-  client: ClientWithCoreApi,
+export function getCompositionById(
   compositionId: string,
-): Promise<Composition> {
-  const content = await getContent(client, compositionId);
-  if (!content) throw new Error(`Composition not found: ${compositionId}`);
-  return mapComposition(compositionId, CompositionBcs.parse(content));
+): Effect.Effect<Composition, ObjectNotFoundError | SuiRpcError | BcsDecodeError, SuiClient> {
+  return getObjectByBcs(
+    compositionId,
+    { parse: (bytes) => mapComposition(compositionId, CompositionBcs.parse(bytes)) },
+    Composition,
+    "Composition",
+  );
 }
 
 /** Extracts the share type `T` from a `Composition<T>` object. */
-export async function getCompositionShareType(
-  client: ClientWithCoreApi,
+export const getCompositionShareType = Effect.fn("getCompositionShareType")(function* (
   compositionId: string,
-): Promise<string> {
-  const { object } = await client.core.getObject({ objectId: compositionId });
-  return extractTypeParam(object.type);
-}
+): Effect.fn.Return<string, ObjectNotFoundError | SuiRpcError, SuiClient> {
+  const type = yield* getObjectType(compositionId);
+  return extractTypeParam(type);
+});
 
 /** Fetches a composition by its share type (GraphQL discovery + Core read). */
-export async function getCompositionByShareType(
-  client: ClientWithCoreApi,
-  graphqlClient: SuiGraphQLClient,
+export const getCompositionByShareType = Effect.fn("getCompositionByShareType")(function* (
   shareType: string,
   misoPackageId: string,
-): Promise<Composition> {
-  const address = await getCompositionAddressByShareType(
-    graphqlClient,
-    shareType,
-    misoPackageId,
-  );
-  if (!address)
-    throw new Error(`Composition not found for share type: ${shareType}`);
-  return getCompositionById(client, address);
-}
+): Effect.fn.Return<Composition, ObjectNotFoundError | SuiRpcError | BcsDecodeError, SuiClient | SuiGraphQL> {
+  const address = yield* getCompositionAddressByShareType(shareType, misoPackageId);
+  if (Option.isNone(address)) {
+    return yield* new ObjectNotFoundError({ objectId: `composition::Composition<${shareType}>` });
+  }
+  return yield* getCompositionById(address.value);
+});
 
 /**
  * Resolves a composition share type to its object address.
@@ -576,22 +576,20 @@ export async function getCompositionByShareType(
  * composition's identity but will read extension fields rather than the core
  * Composition contents.
  */
-export async function getCompositionAddressByShareType(
-  graphqlClient: SuiGraphQLClient,
+export function getCompositionAddressByShareType(
   shareType: string,
   misoPackageId: string,
-): Promise<string | null> {
+): Effect.Effect<Option.Option<string>, SuiRpcError, SuiGraphQL> {
   const type = `${misoPackageId}::composition::Composition<${shareType}>`;
-  return firstAddressOfType(graphqlClient, type);
+  return firstAddressOfType(type);
 }
 
-export async function getCompositionAdminCapById(
-  client: ClientWithCoreApi,
+export const getCompositionAdminCapById = Effect.fn("getCompositionAdminCapById")(function* (
   adminCapId: string,
-): Promise<CompositionAdminCap> {
-  const { object } = await client.core.getObject({ objectId: adminCapId });
-  return { id: adminCapId, shareType: extractTypeParam(object.type) };
-}
+): Effect.fn.Return<CompositionAdminCap, ObjectNotFoundError | SuiRpcError, SuiClient> {
+  const type = yield* getObjectType(adminCapId);
+  return new CompositionAdminCap({ id: adminCapId, shareType: extractTypeParam(type) });
+});
 
 /**
  * Composition admin caps owned by `owner`.
@@ -600,25 +598,21 @@ export async function getCompositionAdminCapById(
  * object's instantiated `type`, so the share type is read straight off
  * `CompositionAdminCap<CompositionShare>` with no second round-trip.
  */
-export async function getOwnedCompositionAdminCaps(
-  client: ClientWithCoreApi,
+export const getOwnedCompositionAdminCaps = Effect.fn("getOwnedCompositionAdminCaps")(function* (
   owner: string,
   misoPackageId: string,
-): Promise<CompositionAdminCap[]> {
+): Effect.fn.Return<CompositionAdminCap[], SuiRpcError, SuiClient> {
   const capType = `${misoPackageId}::composition::CompositionAdminCap`;
-  const objects = await listAllOwnedObjects(client, { owner, type: capType });
+  const objects = yield* listAllOwnedObjects({ owner, type: capType });
   const caps: CompositionAdminCap[] = [];
   for (const obj of objects) {
     const match = obj.type?.match(/<(.+)>$/);
-    if (match?.[1]) caps.push({ id: obj.objectId, shareType: match[1] });
+    if (match?.[1]) caps.push(new CompositionAdminCap({ id: obj.objectId, shareType: match[1] }));
   }
   return caps;
-}
+});
 
-export function deriveCompositionAdminCapId(
-  compositionId: string,
-  misoPackageId: string,
-): string {
+export function deriveCompositionAdminCapId(compositionId: string, misoPackageId: string): string {
   return deriveObjectID(
     compositionId,
     `${misoPackageId}::composition::CompositionAdminCapKey`,
@@ -630,33 +624,34 @@ export function deriveCompositionAdminCapId(
 // Recording
 // ============================================================================
 
-export async function getRecordingsByIds(
-  client: ClientWithCoreApi,
+export const getRecordingsByIds = Effect.fn("getRecordingsByIds")(function* (
   recordingIds: string[],
-): Promise<Record<string, Recording>> {
+): Effect.fn.Return<Record<string, Recording>, SuiRpcError | BcsDecodeError, SuiClient> {
   if (recordingIds.length === 0) return {};
-  const { objects } = await client.core.getObjects({
-    objectIds: recordingIds,
-    include: { content: true },
-  });
-  const out: Record<string, Recording> = {};
-  for (const obj of objects) {
-    if (obj instanceof Error || !obj.content) continue;
-    out[obj.objectId] = mapRecording(
-      obj.objectId,
-      RecordingBcs.parse(obj.content),
-    );
-  }
-  return out;
-}
+  const contents = yield* getObjectsContent(recordingIds);
+  const decoded = yield* Effect.forEach(
+    [...contents.entries()],
+    ([objectId, { content }]) =>
+      decodeBcs(
+        { parse: (bytes) => mapRecording(objectId, RecordingBcs.parse(bytes)) },
+        Recording,
+        content,
+        { type: "Recording", objectId },
+      ).pipe(Effect.map((recording) => [objectId, recording] as const)),
+    { concurrency: "unbounded" },
+  );
+  return Object.fromEntries(decoded);
+});
 
-export async function getRecordingById(
-  client: ClientWithCoreApi,
+export function getRecordingById(
   recordingId: string,
-): Promise<Recording> {
-  const content = await getContent(client, recordingId);
-  if (!content) throw new Error(`Recording not found: ${recordingId}`);
-  return mapRecording(recordingId, RecordingBcs.parse(content));
+): Effect.Effect<Recording, ObjectNotFoundError | SuiRpcError | BcsDecodeError, SuiClient> {
+  return getObjectByBcs(
+    recordingId,
+    { parse: (bytes) => mapRecording(recordingId, RecordingBcs.parse(bytes)) },
+    Recording,
+    "Recording",
+  );
 }
 
 /**
@@ -665,16 +660,12 @@ export async function getRecordingById(
  * them and returns the first; use {@link getRecordingShareTypes} when the
  * parent composition's share type is needed too.
  */
-export async function getRecordingShareType(
-  client: ClientWithCoreApi,
+export const getRecordingShareType = Effect.fn("getRecordingShareType")(function* (
   recordingId: string,
-): Promise<string> {
-  const [recordingShareType] = await getRecordingShareTypes(
-    client,
-    recordingId,
-  );
+): Effect.fn.Return<string, ObjectNotFoundError | SuiRpcError, SuiClient> {
+  const [recordingShareType] = yield* getRecordingShareTypes(recordingId);
   return recordingShareType;
-}
+});
 
 /**
  * Both of a recording's share types, as `[RecordingShare, CompositionShare]`.
@@ -682,37 +673,30 @@ export async function getRecordingShareType(
  * and the recording credit/pool extensions are all generic over both, in this
  * order.
  */
-export async function getRecordingShareTypes(
-  client: ClientWithCoreApi,
+export const getRecordingShareTypes = Effect.fn("getRecordingShareTypes")(function* (
   recordingId: string,
-): Promise<[string, string]> {
-  const { object } = await client.core.getObject({ objectId: recordingId });
-  return extractTypeParams2(object.type);
-}
+): Effect.fn.Return<[string, string], ObjectNotFoundError | SuiRpcError, SuiClient> {
+  const type = yield* getObjectType(recordingId);
+  return extractTypeParams2(type);
+});
 
-export async function getRecordingByShareType(
-  client: ClientWithCoreApi,
-  graphqlClient: SuiGraphQLClient,
+export const getRecordingByShareType = Effect.fn("getRecordingByShareType")(function* (
   shareType: string,
   misoPackageId: string,
-): Promise<Recording> {
-  const address = await addressOfRecordingWithShareType(
-    graphqlClient,
-    misoPackageId,
-    shareType,
-  );
-  if (!address)
-    throw new Error(`Recording not found for share type: ${shareType}`);
-  return getRecordingById(client, address);
-}
+): Effect.fn.Return<Recording, ObjectNotFoundError | SuiRpcError | BcsDecodeError, SuiClient | SuiGraphQL> {
+  const address = yield* addressOfRecordingWithShareType(misoPackageId, shareType);
+  if (Option.isNone(address)) {
+    return yield* new ObjectNotFoundError({ objectId: `recording::Recording<${shareType}, ...>` });
+  }
+  return yield* getRecordingById(address.value);
+});
 
-export async function getRecordingAdminCapById(
-  client: ClientWithCoreApi,
+export const getRecordingAdminCapById = Effect.fn("getRecordingAdminCapById")(function* (
   adminCapId: string,
-): Promise<RecordingAdminCap> {
-  const { object } = await client.core.getObject({ objectId: adminCapId });
-  return { id: adminCapId, shareType: extractTypeParam(object.type) };
-}
+): Effect.fn.Return<RecordingAdminCap, ObjectNotFoundError | SuiRpcError, SuiClient> {
+  const type = yield* getObjectType(adminCapId);
+  return new RecordingAdminCap({ id: adminCapId, shareType: extractTypeParam(type) });
+});
 
 /**
  * Recording admin caps owned by `owner`.
@@ -722,108 +706,89 @@ export async function getRecordingAdminCapById(
  * so this yields only the recording's own share type — its parent composition's
  * share type is not recoverable from the cap alone.
  */
-export async function getOwnedRecordingAdminCaps(
-  client: ClientWithCoreApi,
+export const getOwnedRecordingAdminCaps = Effect.fn("getOwnedRecordingAdminCaps")(function* (
   owner: string,
   misoPackageId: string,
-): Promise<RecordingAdminCap[]> {
+): Effect.fn.Return<RecordingAdminCap[], SuiRpcError, SuiClient> {
   const capType = `${misoPackageId}::recording::RecordingAdminCap`;
-  const objects = await listAllOwnedObjects(client, { owner, type: capType });
+  const objects = yield* listAllOwnedObjects({ owner, type: capType });
   const caps: RecordingAdminCap[] = [];
   for (const obj of objects) {
     const match = obj.type?.match(/<(.+)>$/);
-    if (match?.[1]) caps.push({ id: obj.objectId, shareType: match[1] });
+    if (match?.[1]) caps.push(new RecordingAdminCap({ id: obj.objectId, shareType: match[1] }));
   }
   return caps;
-}
+});
 
-export function deriveRecordingAdminCapId(
-  recordingId: string,
-  misoPackageId: string,
-): string {
-  return deriveObjectID(
-    recordingId,
-    `${misoPackageId}::recording::RecordingAdminCapKey`,
-    UNIT_STRUCT_KEY_BYTES,
-  );
+export function deriveRecordingAdminCapId(recordingId: string, misoPackageId: string): string {
+  return deriveObjectID(recordingId, `${misoPackageId}::recording::RecordingAdminCapKey`, UNIT_STRUCT_KEY_BYTES);
 }
 
 // ============================================================================
 // Release
 // ============================================================================
 
-export async function getReleasesByIds(
-  client: ClientWithCoreApi,
+export const getReleasesByIds = Effect.fn("getReleasesByIds")(function* (
   releaseIds: string[],
-): Promise<Record<string, Release>> {
+): Effect.fn.Return<Record<string, Release>, SuiRpcError | BcsDecodeError, SuiClient> {
   if (releaseIds.length === 0) return {};
-  const { objects } = await client.core.getObjects({
-    objectIds: releaseIds,
-    include: { content: true },
-  });
-  const out: Record<string, Release> = {};
-  for (const obj of objects) {
-    if (obj instanceof Error || !obj.content) continue;
-    out[obj.objectId] = mapRelease(obj.objectId, ReleaseBcs.parse(obj.content));
-  }
-  return out;
-}
+  const contents = yield* getObjectsContent(releaseIds);
+  const decoded = yield* Effect.forEach(
+    [...contents.entries()],
+    ([objectId, { content }]) =>
+      decodeBcs(
+        { parse: (bytes) => mapRelease(objectId, ReleaseBcs.parse(bytes)) },
+        Release,
+        content,
+        { type: "Release", objectId },
+      ).pipe(Effect.map((release) => [objectId, release] as const)),
+    { concurrency: "unbounded" },
+  );
+  return Object.fromEntries(decoded);
+});
 
-export async function getReleaseById(
-  client: ClientWithCoreApi,
+export function getReleaseById(
   releaseId: string,
-): Promise<Release> {
-  const { object } = await client.core.getObject({
-    objectId: releaseId,
-    include: { content: true },
-  });
-  if (!object.content) throw new Error(`Release not found: ${releaseId}`);
-  return mapRelease(releaseId, ReleaseBcs.parse(object.content));
+): Effect.Effect<Release, ObjectNotFoundError | SuiRpcError | BcsDecodeError, SuiClient> {
+  return getObjectByBcs(
+    releaseId,
+    { parse: (bytes) => mapRelease(releaseId, ReleaseBcs.parse(bytes)) },
+    Release,
+    "Release",
+  );
 }
 
-export async function getReleaseAdminCapById(
-  client: ClientWithCoreApi,
+export const getReleaseAdminCapById = Effect.fn("getReleaseAdminCapById")(function* (
   adminCapId: string,
-): Promise<ReleaseAdminCap> {
-  const { object } = await client.core.getObject({
-    objectId: adminCapId,
-    include: { json: true },
+): Effect.fn.Return<ReleaseAdminCap, ObjectNotFoundError | SuiRpcError, SuiClient> {
+  const client = yield* SuiClient;
+  const { object } = yield* Effect.tryPromise({
+    try: (signal) => client.core.getObject({ objectId: adminCapId, include: { json: true }, signal }),
+    catch: (cause) => classifyMissing(adminCapId, "getObject", cause),
   });
   const json = object.json as { release_id: string } | null;
-  if (!json?.release_id)
-    throw new Error(`ReleaseAdminCap not found: ${adminCapId}`);
-  return { id: adminCapId, releaseId: json.release_id };
-}
+  if (!json?.release_id) {
+    return yield* new ObjectNotFoundError({ objectId: adminCapId });
+  }
+  return new ReleaseAdminCap({ id: adminCapId, releaseId: json.release_id });
+});
 
-export async function getOwnedReleaseAdminCaps(
-  client: ClientWithCoreApi,
+export const getOwnedReleaseAdminCaps = Effect.fn("getOwnedReleaseAdminCaps")(function* (
   owner: string,
   misoPackageId: string,
-): Promise<ReleaseAdminCap[]> {
+): Effect.fn.Return<ReleaseAdminCap[], SuiRpcError, SuiClient> {
   const capType = `${misoPackageId}::release::ReleaseAdminCap`;
-  const objects = await listAllOwnedObjects(client, {
-    owner,
-    type: capType,
-    include: { json: true },
-  });
+  const objects = yield* listAllOwnedObjects({ owner, type: capType, include: { json: true } });
   const caps: ReleaseAdminCap[] = [];
   for (const obj of objects) {
     const json = obj.json as { release_id: string } | null;
-    if (json?.release_id)
-      caps.push({ id: obj.objectId, releaseId: json.release_id });
+    if (json?.release_id) caps.push(new ReleaseAdminCap({ id: obj.objectId, releaseId: json.release_id }));
   }
   return caps;
-}
+});
 
-export function deriveReleaseAdminCapId(
-  releaseId: string,
-  misoPackageId: string,
-): string {
-  return deriveObjectID(
-    releaseId,
-    `${misoPackageId}::release::ReleaseAdminCapKey`,
-    UNIT_STRUCT_KEY_BYTES,
-  );
+export function deriveReleaseAdminCapId(releaseId: string, misoPackageId: string): string {
+  return deriveObjectID(releaseId, `${misoPackageId}::release::ReleaseAdminCapKey`, UNIT_STRUCT_KEY_BYTES);
 }
 
 // ============================================================================
@@ -831,13 +796,12 @@ export function deriveReleaseAdminCapId(
 // ============================================================================
 
 /** Extracts the share type `T` from a `Currency<T>` object. */
-export async function getShareCurrencyType(
-  client: ClientWithCoreApi,
+export const getShareCurrencyType = Effect.fn("getShareCurrencyType")(function* (
   shareCurrencyId: string,
-): Promise<string> {
-  const { object } = await client.core.getObject({ objectId: shareCurrencyId });
-  return extractTypeParam(object.type);
-}
+): Effect.fn.Return<string, ObjectNotFoundError | SuiRpcError, SuiClient> {
+  const type = yield* getObjectType(shareCurrencyId);
+  return extractTypeParam(type);
+});
 
 /**
  * Finds the `TreasuryCap<ShareType>` owned by `owner`. One Core API call.
@@ -850,43 +814,40 @@ export async function getShareCurrencyType(
  * compose the two:
  *
  * ```ts
- * const shareType = await getShareCurrencyType(client, shareCurrencyId);
- * const capId = await getShareCurrencyTreasuryCap(client, shareType, owner);
+ * const shareType = yield* getShareCurrencyType(shareCurrencyId);
+ * const capId = yield* getShareCurrencyTreasuryCap(shareType, owner);
  * ```
  */
-export async function getShareCurrencyTreasuryCap(
-  client: ClientWithCoreApi,
+export const getShareCurrencyTreasuryCap = Effect.fn("getShareCurrencyTreasuryCap")(function* (
   shareType: string,
   owner: string,
-): Promise<string> {
-  const objects = await listAllOwnedObjects(client, {
-    owner,
-    type: `0x2::coin::TreasuryCap<${shareType}>`,
-  });
+): Effect.fn.Return<string, SuiRpcError, SuiClient> {
+  const objects = yield* listAllOwnedObjects({ owner, type: `0x2::coin::TreasuryCap<${shareType}>` });
   if (objects.length === 0) {
     throw new Error(`No TreasuryCap found for ${shareType} owned by ${owner}`);
   }
   return objects[0]!.objectId;
-}
+});
 
 // ============================================================================
 // Private
 // ============================================================================
 
-/** Returns the first object address of a fully-qualified type, or null. */
-async function firstAddressOfType(
-  client: SuiGraphQLClient,
+/** Returns the first object address of a fully-qualified type, or `Option.none()`. */
+const firstAddressOfType = Effect.fn("firstAddressOfType")(function* (
   type: string,
-): Promise<string | null> {
-  const result = await client.query({
-    query: AddressesByTypeQuery,
-    variables: { type },
+): Effect.fn.Return<Option.Option<string>, SuiRpcError, SuiGraphQL> {
+  const client = yield* SuiGraphQL;
+  const result = yield* Effect.tryPromise({
+    try: () => client.query({ query: AddressesByTypeQuery, variables: { type } }),
+    catch: (cause) => new SuiRpcError({ operation: "addressesByType", cause }),
   });
-  return result.data?.objects?.nodes?.[0]?.address ?? null;
-}
+  return Option.fromNullishOr(result.data?.objects?.nodes?.[0]?.address);
+});
 
 /**
- * Address of the `Recording` whose FIRST type parameter is `shareType`, or null.
+ * Address of the `Recording` whose FIRST type parameter is `shareType`, or
+ * `Option.none()`.
  *
  * `Recording<RecordingShare, CompositionShare>` takes two parameters and a type
  * filter must supply all of them or none, so filtering by
@@ -896,33 +857,34 @@ async function firstAddressOfType(
  * first parameter client-side. A recording's share currency is unique to it, so
  * the match is unambiguous.
  */
-async function addressOfRecordingWithShareType(
-  client: SuiGraphQLClient,
+const addressOfRecordingWithShareType = Effect.fn("addressOfRecordingWithShareType")(function* (
   misoPackageId: string,
   shareType: string,
-): Promise<string | null> {
+): Effect.fn.Return<Option.Option<string>, SuiRpcError, SuiGraphQL> {
+  const client = yield* SuiGraphQL;
   let cursor: string | null | undefined;
   do {
-    const result = await client.query<
-      { objects?: WorkAddressConnection | null },
-      { type: string; cursor?: string | null }
-    >({
-      query: `query RecordingAddress($type: String!, $cursor: String) {
-        objects(first: 50, after: $cursor, filter: { type: $type }) {
-          pageInfo { hasNextPage endCursor }
-          nodes { address asMoveObject { contents { type { repr } } } }
-        }
-      }`,
-      variables: { type: `${misoPackageId}::recording::Recording`, cursor },
+    const result = yield* Effect.tryPromise({
+      try: () =>
+        client.query<{ objects?: WorkAddressConnection | null }, { type: string; cursor?: string | null }>({
+          query: `query RecordingAddress($type: String!, $cursor: String) {
+            objects(first: 50, after: $cursor, filter: { type: $type }) {
+              pageInfo { hasNextPage endCursor }
+              nodes { address asMoveObject { contents { type { repr } } } }
+            }
+          }`,
+          variables: { type: `${misoPackageId}::recording::Recording`, cursor },
+        }),
+      catch: (cause) => new SuiRpcError({ operation: "recordingAddress", cause }),
     });
     const page = result.data?.objects;
     for (const node of page?.nodes ?? []) {
       const repr = node?.asMoveObject?.contents?.type?.repr;
       if (!repr || !node.address) continue;
       const [recordingShareType] = extractTypeParams2(repr);
-      if (recordingShareType === shareType) return node.address;
+      if (recordingShareType === shareType) return Option.some(node.address);
     }
     cursor = page?.pageInfo?.hasNextPage ? page.pageInfo.endCursor : null;
   } while (cursor);
-  return null;
-}
+  return Option.none();
+});