@misofm/platform 0.24.0 → 0.26.0

package/src/genre.ts

@@ -0,0 +1,384 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Genre classification for both `Release` and `Recording`.
+ *
+ * On-chain, `release_genre` and `recording_genre` store the identical shape: a
+ * bare `vector<ID>` of `genre::Genre` object ids under a dynamic field keyed by
+ * an empty `ExtensionKey()`, index 0 the primary, capped at `MAX_GENRES` (6), and
+ * non-empty by construction — removing the last entry drops the field, so "the
+ * field exists" and "there is a primary" are the same fact. Every id in the list
+ * came from `add_genre(self, cap, genre: &Genre)`, which only accepts a real
+ * object minted by the shared `genre` vocabulary registry; `remove_genre` takes
+ * a bare `ID` since proving membership is not needed to drop a reference.
+ *
+ * This module spans both `Release` and `Recording` rather than living beside
+ * one target object (contrast `release-extensions.ts` / `recording-extensions.ts`,
+ * which are split by target). Genre is not a per-target-object axis: the two
+ * packages are separately deployed, separately versioned siblings with the same
+ * vocabulary and the same shape, and `recording-extensions.ts` must not import
+ * genre helpers out of `release-extensions.ts` (or vice versa) just because one
+ * happened to be written first.
+ *
+ * `setReleaseGenres` / `setRecordingGenres` below express the complete desired
+ * list: they emit `clear_genres` first, then exactly one `add_genre` per id in
+ * array order. `clear_genres` is a no-op when nothing is attached, so this is
+ * safe to run against a fresh object, and it is equally safe to re-run against
+ * one that already carries genres — the leading `clear_genres` wipes prior
+ * state before the adds replay, so the transaction is idempotent and can be
+ * composed more than once in the same PTB. Editing clients that want to
+ * mutate an existing assignment without a full replace should use the
+ * exported single-mutation primitives (`addReleaseGenre`, `removeReleaseGenre`
+ * and their `recording` counterparts), or `clearReleaseGenres` /
+ * `clearRecordingGenres` to drop the list outright.
+ *
+ * `getReleaseGenres` / `getRecordingGenres` below return `[]` when the
+ * dynamic field is absent, which now exactly mirrors the on-chain `genres()`
+ * view — both Move modules removed their standalone emptiness/first-entry
+ * accessors, so emptiness is `genres().length === 0` and the primary is
+ * `genres()[0]`, computed client-side the same way Move computes them.
+ */
+
+import { bcs } from "@mysten/sui/bcs";
+import { deriveDynamicFieldID, deriveObjectID, normalizeSuiObjectId } from "@mysten/sui/utils";
+import type { Transaction, TransactionObjectArgument } from "@mysten/sui/transactions";
+import { Effect, Schema } from "effect";
+import { getOptionalObjectContent, type SuiClient, type SuiRpcError } from "@misofm/effect";
+import type { TxThunk } from "./transactions.ts";
+import { directAdminCap, invokeWithAdminCap, type AdminCapAuthority, type ObjectInput } from "./vault.ts";
+import { PlatformDeployment } from "./deployments.ts";
+import type { ReleaseExtensionTarget } from "./release-extensions.ts";
+import type { RecordingExtensionTarget } from "./recording-extensions.ts";
+import * as genre from "./contracts/genre/genre.ts";
+import * as releaseGenre from "./contracts/release_genre/release_genre.ts";
+import * as recordingGenre from "./contracts/recording_genre/recording_genre.ts";
+
+// ── Vocabulary helpers ───────────────────────────────────────────────────────
+
+const GENRE_NAME_RE = /^[A-Z]+(?:_[A-Z]+)*$/;
+
+/** Validate the canonical on-chain genre vocabulary spelling. */
+export function assertCanonicalGenreName(name: string): void {
+  const bytes = new TextEncoder().encode(name).length;
+  if (bytes === 0 || bytes > 64 || !GENRE_NAME_RE.test(name)) {
+    throw new Error(
+      `Genre name must be 1-64 bytes of uppercase A-Z and underscores; got ${JSON.stringify(name)}`,
+    );
+  }
+}
+
+/** Derive the immutable Genre object address for a canonical vocabulary name.
+ * `genrePackageId` must be the genre package's defining (original publish)
+ * address — the on-chain derivation hashes type names with defining IDs. */
+export function deriveGenreAddress(
+  genreRegistryId: string,
+  genrePackageId: string,
+  canonicalName: string,
+): string {
+  assertCanonicalGenreName(canonicalName);
+  return deriveObjectID(
+    genreRegistryId,
+    `${genrePackageId}::genre::GenreKey`,
+    genre.GenreKey.serialize([canonicalName]).toBytes(),
+  );
+}
+
+/**
+ * A vocabulary entry from the shared `genre` registry, identified by its
+ * canonical name (e.g. `"HIP_HOP"`). Constructing one needs the deployment's
+ * genre registry object id and genre package id — see {@link Genre.derive}.
+ */
+export class Genre extends Schema.Class<Genre>("@misofm/platform/Genre")({
+  id: Schema.String,
+  name: Schema.String,
+}) {
+  /**
+   * Derives a `Genre`'s immutable object address from the platform
+   * deployment's genre registry + package id. This is a pure derivation (no
+   * chain read) but is the pilot for a value object whose construction
+   * genuinely needs deployment context, so it reaches that context through
+   * the `PlatformDeployment` service rather than an explicit parameter.
+   */
+  static readonly derive = Effect.fn("Genre.derive")(function* (
+    canonicalName: string,
+  ): Effect.fn.Return<Genre, never, PlatformDeployment> {
+    const deployment = yield* PlatformDeployment;
+    const id = deriveGenreAddress(deployment.objects.genreRegistry, deployment.packages.genre, canonicalName);
+    return new Genre({ id, name: canonicalName });
+  });
+}
+
+// ── Shared validation ────────────────────────────────────────────────────────
+
+/** The maximum number of genres `release_genre` / `recording_genre` will accept. */
+export const MAX_GENRES = 6;
+
+/**
+ * Fail closed before signing rather than let a bad list abort on-chain as
+ * `EDuplicateGenre` (40) or `EMaxGenres` (41). Mirrors how `setReleaseKind`
+ * validates its input up front and returns a thunk only once it is well-formed.
+ */
+function validateGenreIds(op: string, genreIds: readonly string[]): string[] {
+  if (genreIds.length === 0) {
+    throw new Error(`${op}: genreIds must not be empty`);
+  }
+  if (genreIds.length > MAX_GENRES) {
+    throw new Error(`${op}: at most ${MAX_GENRES} genres (got ${genreIds.length})`);
+  }
+  const seen = new Set<string>();
+  for (const id of genreIds) {
+    const normalized = normalizeSuiObjectId(id);
+    if (seen.has(normalized)) {
+      throw new Error(`${op}: duplicate genre id ${id}`);
+    }
+    seen.add(normalized);
+  }
+  return [...genreIds];
+}
+
+// ── Release setters ──────────────────────────────────────────────────────────
+
+function releaseAuthorityOf(p: ReleaseExtensionTarget): AdminCapAuthority {
+  if (p.authority !== undefined) return p.authority;
+  if (p.releaseAdminCapId !== undefined) return directAdminCap(p.releaseAdminCapId);
+  throw new Error("release authority is required");
+}
+
+function object(tx: Transaction, value: ObjectInput): TransactionObjectArgument {
+  return typeof value === "string" ? tx.object(value) : value;
+}
+
+export type SetReleaseGenresParams = ReleaseExtensionTarget & {
+  /** Ordered `genre::Genre` object ids; index 0 becomes the primary. 1-6 entries, no duplicates. */
+  genreIds: readonly string[];
+  releaseGenrePackageId: string;
+};
+
+/**
+ * Attach the complete, ordered list of genres to a Release. Emits
+ * `release_genre::clear_genres` first, then exactly one
+ * `release_genre::add_genre` per id in array order. `clear_genres` is a no-op
+ * when nothing is attached, so this is safe to run against a fresh release
+ * and safe to re-run against one that already has genres assigned.
+ */
+export function setReleaseGenres(p: SetReleaseGenresParams): TxThunk {
+  const genreIds = validateGenreIds("setReleaseGenres", p.genreIds);
+  return (tx) => {
+    const authority = releaseAuthorityOf(p);
+    invokeWithAdminCap(tx, authority, {
+      target: `${p.releaseGenrePackageId}::release_genre::clear_genres`,
+      arguments: [object(tx, p.releaseId)],
+      adminCapIndex: 1,
+    });
+    for (const genreId of genreIds) {
+      invokeWithAdminCap(tx, authority, {
+        target: `${p.releaseGenrePackageId}::release_genre::add_genre`,
+        arguments: [object(tx, p.releaseId), tx.object(genreId)],
+        adminCapIndex: 1,
+      });
+    }
+  };
+}
+
+export type ClearReleaseGenresParams = ReleaseExtensionTarget & {
+  releaseGenrePackageId: string;
+};
+
+/** Remove a Release's entire genre list. A no-op on-chain if nothing is attached. */
+export function clearReleaseGenres(p: ClearReleaseGenresParams): TxThunk {
+  return (tx) => {
+    invokeWithAdminCap(tx, releaseAuthorityOf(p), {
+      target: `${p.releaseGenrePackageId}::release_genre::clear_genres`,
+      arguments: [object(tx, p.releaseId)],
+      adminCapIndex: 1,
+    });
+  };
+}
+
+export type ReleaseGenreMutationParams = ReleaseExtensionTarget & {
+  genreId: string;
+  releaseGenrePackageId: string;
+};
+
+/** Append one genre to a Release's list. */
+export function addReleaseGenre(p: ReleaseGenreMutationParams): TxThunk {
+  return (tx) => {
+    invokeWithAdminCap(tx, releaseAuthorityOf(p), {
+      target: `${p.releaseGenrePackageId}::release_genre::add_genre`,
+      arguments: [object(tx, p.releaseId), tx.object(p.genreId)],
+      adminCapIndex: 1,
+    });
+  };
+}
+
+/** Remove one genre from a Release by id. */
+export function removeReleaseGenre(p: ReleaseGenreMutationParams): TxThunk {
+  return (tx) => {
+    invokeWithAdminCap(tx, releaseAuthorityOf(p), {
+      target: `${p.releaseGenrePackageId}::release_genre::remove_genre`,
+      arguments: [object(tx, p.releaseId), tx.pure.id(p.genreId)],
+      adminCapIndex: 1,
+    });
+  };
+}
+
+// ── Recording setters ────────────────────────────────────────────────────────
+
+export interface SetRecordingGenresParams extends RecordingExtensionTarget {
+  readonly recordingGenrePackageId: string;
+  /** Ordered `genre::Genre` object ids; index 0 becomes the primary. 1-6 entries, no duplicates. */
+  readonly genreIds: readonly string[];
+}
+
+/**
+ * Attach the complete, ordered list of genres to a Recording. Emits
+ * `recording_genre::clear_genres` first, then exactly one
+ * `recording_genre::add_genre` per id in array order. `clear_genres` is a
+ * no-op when nothing is attached, so this is safe to run against a fresh
+ * recording and safe to re-run against one that already has genres assigned.
+ */
+export function setRecordingGenres(p: SetRecordingGenresParams): TxThunk {
+  const genreIds = validateGenreIds("setRecordingGenres", p.genreIds);
+  return (tx) => {
+    invokeWithAdminCap(tx, p.authority, {
+      target: `${p.recordingGenrePackageId}::recording_genre::clear_genres`,
+      typeArguments: [p.recordingShareType, p.compositionShareType],
+      arguments: [object(tx, p.recordingId)],
+      adminCapIndex: 1,
+    });
+    for (const genreId of genreIds) {
+      invokeWithAdminCap(tx, p.authority, {
+        target: `${p.recordingGenrePackageId}::recording_genre::add_genre`,
+        typeArguments: [p.recordingShareType, p.compositionShareType],
+        arguments: [object(tx, p.recordingId), tx.object(genreId)],
+        adminCapIndex: 1,
+      });
+    }
+  };
+}
+
+export interface ClearRecordingGenresParams extends RecordingExtensionTarget {
+  readonly recordingGenrePackageId: string;
+}
+
+/** Remove a Recording's entire genre list. A no-op on-chain if nothing is attached. */
+export function clearRecordingGenres(p: ClearRecordingGenresParams): TxThunk {
+  return (tx) => {
+    invokeWithAdminCap(tx, p.authority, {
+      target: `${p.recordingGenrePackageId}::recording_genre::clear_genres`,
+      typeArguments: [p.recordingShareType, p.compositionShareType],
+      arguments: [object(tx, p.recordingId)],
+      adminCapIndex: 1,
+    });
+  };
+}
+
+export interface RecordingGenreMutationParams extends RecordingExtensionTarget {
+  readonly recordingGenrePackageId: string;
+  readonly genreId: string;
+}
+
+/** Append one genre to a Recording's list. */
+export function addRecordingGenre(p: RecordingGenreMutationParams): TxThunk {
+  return (tx) => {
+    invokeWithAdminCap(tx, p.authority, {
+      target: `${p.recordingGenrePackageId}::recording_genre::add_genre`,
+      typeArguments: [p.recordingShareType, p.compositionShareType],
+      arguments: [object(tx, p.recordingId), tx.object(p.genreId)],
+      adminCapIndex: 1,
+    });
+  };
+}
+
+/** Remove one genre from a Recording by id. */
+export function removeRecordingGenre(p: RecordingGenreMutationParams): TxThunk {
+  return (tx) => {
+    invokeWithAdminCap(tx, p.authority, {
+      target: `${p.recordingGenrePackageId}::recording_genre::remove_genre`,
+      typeArguments: [p.recordingShareType, p.compositionShareType],
+      arguments: [object(tx, p.recordingId), tx.pure.id(p.genreId)],
+      adminCapIndex: 1,
+    });
+  };
+}
+
+// ── Reads ────────────────────────────────────────────────────────────────────
+
+// Both packages store the same shape: a dynamic field on the target's UID under
+// an empty `ExtensionKey()` (Move's implicit `dummy_field: bool` → one `false`
+// byte), value `vector<ID>`, ordered with the primary first.
+const ReleaseGenresField = bcs.struct("Field", {
+  id: bcs.Address,
+  name: releaseGenre.ExtensionKey,
+  value: bcs.vector(bcs.Address),
+});
+const RELEASE_GENRES_KEY_BYTES = releaseGenre.ExtensionKey.serialize([false]).toBytes();
+
+const RecordingGenresField = bcs.struct("Field", {
+  id: bcs.Address,
+  name: recordingGenre.ExtensionKey,
+  value: bcs.vector(bcs.Address),
+});
+const RECORDING_GENRES_KEY_BYTES = recordingGenre.ExtensionKey.serialize([false]).toBytes();
+
+/** Parse a `release_genre` dynamic field's content into its ordered genre ids. */
+export function parseReleaseGenresContent(content: Uint8Array): string[] {
+  return ReleaseGenresField.parse(content).value;
+}
+
+/** Parse a `recording_genre` dynamic field's content into its ordered genre ids. */
+export function parseRecordingGenresContent(content: Uint8Array): string[] {
+  return RecordingGenresField.parse(content).value;
+}
+
+/** Deterministic dynamic-field id for a Release's genre list. */
+export function releaseGenresFieldId(
+  releaseId: string,
+  releaseGenrePackageId: string,
+): string {
+  return deriveDynamicFieldID(
+    releaseId,
+    `${releaseGenrePackageId}::release_genre::ExtensionKey`,
+    RELEASE_GENRES_KEY_BYTES,
+  );
+}
+
+/** Deterministic dynamic-field id for a Recording's genre list. */
+export function recordingGenresFieldId(
+  recordingId: string,
+  recordingGenrePackageId: string,
+): string {
+  return deriveDynamicFieldID(
+    recordingId,
+    `${recordingGenrePackageId}::recording_genre::ExtensionKey`,
+    RECORDING_GENRES_KEY_BYTES,
+  );
+}
+
+/**
+ * Read a Release's genre ids in order (primary first), or `[]` when no genres
+ * are attached. The primary is `list[0]`; there is no separate primary reader
+ * because the Move `genres` view already returns `[]` for the absent case.
+ */
+export const getReleaseGenres = Effect.fn("getReleaseGenres")(function* (
+  releaseId: string,
+  releaseGenrePackageId: string,
+): Effect.fn.Return<string[], SuiRpcError, SuiClient> {
+  const found = yield* getOptionalObjectContent(releaseGenresFieldId(releaseId, releaseGenrePackageId));
+  return found._tag === "None" ? [] : parseReleaseGenresContent(found.value.content);
+});
+
+/**
+ * Read a Recording's genre ids in order (primary first), or `[]` when no
+ * genres are attached. The primary is `list[0]`; there is no separate primary
+ * reader because the Move `genres` view already returns `[]` for the absent
+ * case.
+ */
+export const getRecordingGenres = Effect.fn("getRecordingGenres")(function* (
+  recordingId: string,
+  recordingGenrePackageId: string,
+): Effect.fn.Return<string[], SuiRpcError, SuiClient> {
+  const found = yield* getOptionalObjectContent(recordingGenresFieldId(recordingId, recordingGenrePackageId));
+  return found._tag === "None" ? [] : parseRecordingGenresContent(found.value.content);
+});

package/src/index.ts

@@ -6,7 +6,7 @@
 // Miso's own product sits on top of the permissionless protocol, and the two
 // ship as separate packages because they have different promises:
 //
-//   @misofm/protocol  PROTOCOL — Composition, Recording, Release. The open layer
+//   @misofm/musicos  PROTOCOL — Composition, Recording, Release. The open layer
 //                     anyone can build on, and nobody needs Miso's permission to use.
 //   @misofm/platform  PLATFORM — Pressing, Listing, Record, and the first-party
 //                     EXTENSIONS. How MISO sells copies of a release, and the
@@ -53,6 +53,14 @@ export * from "./walrus-ids.ts";
 export * from "./streaming.ts";
 export * from "./walrus.ts";
 
+// Re-homed from the pre-split protocol package: extension/primitive package
+// bindings, event decoders, and the generic royalty-pool / routed-stake
+// queries and PTB builders (see the boundary rule above — these are all
+// things Miso offers on top of the object model, not the model itself).
+export * from "./packages.ts";
+export { platformEventParsers } from "./events.ts";
+export * from "./royalty.ts";
+
 // High-level, JSON-safe platform projections used directly by clients and by
 // the thin HTTP read service. Namespaced because these composed view types are
 // intentionally distinct from the lower-level contract views above.
@@ -63,6 +71,7 @@ export * as read from "./read/index.ts";
 export * from "./credits.ts";
 export * from "./cover.ts";
 export * from "./release-extensions.ts";
+export * from "./genre.ts";
 export * from "./recording-extensions.ts";
 export * from "./vault.ts";
 

package/src/internal.ts

@@ -9,8 +9,8 @@ import type { Transaction, TransactionArgument } from "@mysten/sui/transactions"
 // call needs an `Option` argument built inline. Consumed by `./cover` and
 // `./credits`.
 //
-// These came over from `@misonetwork/sdk`'s own private `internal.ts` when the
-// extension surface moved here. They were NOT promoted to that package's public
+// These came over from the object-model package's own private `internal.ts`
+// when the extension surface moved here. They were NOT promoted to that package's public
 // API to make them reachable: they are two literal Move function targets from the
 // standard library, so re-deriving them costs nothing, whereas exporting them
 // would widen the protocol SDK's public surface — and therefore its compatibility

package/src/packages.ts

@@ -0,0 +1,243 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Package-bound generated APIs for the platform layer: extensions, generic
+ * royalty/routed-stake primitives, and Party. The object-model core (composition,
+ * recording, release, track) has its own `MisoPackageBindings` in
+ * `@misofm/musicos/packages` — this class covers everything else.
+ *
+ * `@mysten/codegen` intentionally emits `@local-pkg/*` source labels. This
+ * adapter replaces those labels with the exact addresses from a complete
+ * platform deployment manifest, so applications never have to hand-write a
+ * Move target.
+ */
+
+import { bindModulePackage } from "@misofm/musicos/packages";
+// The Party core's generated bindings live in `@misofm/partyos` now (this
+// package's own generated `partyos` tree is gone). Binding `call.party.core`/
+// `bcs.party.core` from partyos's curated barrel — rather than dropping them —
+// keeps this package's single `MisoPlatformPackageBindings` facade covering
+// every package a platform deployment addresses, core included, which is what
+// `packages.test.ts` exercises.
+import { party as partyCoreContracts } from "@misofm/partyos/contracts";
+import {
+  normalizeMisoPlatformDeployment,
+  type MisoPlatformDeployment,
+} from "./deployments.ts";
+
+import * as compositionCredits from "./contracts/composition_credits/composition_credits.ts";
+import * as compositionPartyRole from "./contracts/composition_credits/composition_party_role.ts";
+import * as recordingAdvisory from "./contracts/recording_advisory/recording_advisory.ts";
+import * as recordingCredits from "./contracts/recording_credits/recording_credits.ts";
+import * as recordingPartyRole from "./contracts/recording_credits/recording_party_role.ts";
+import * as recordingLanguage from "./contracts/recording_language/recording_language.ts";
+import * as recordingMasterReference from "./contracts/recording_master_reference/recording_master_reference.ts";
+import * as releaseCoverArt from "./contracts/release_cover_art/release_cover_art.ts";
+import * as releaseCredits from "./contracts/release_credits/release_credits.ts";
+import * as releasePartyRole from "./contracts/release_credits/release_party_role.ts";
+import * as releaseDescription from "./contracts/release_description/release_description.ts";
+import * as releaseDspLink from "./contracts/release_dsp_link/release_dsp_link.ts";
+import * as releaseGenre from "./contracts/release_genre/release_genre.ts";
+import * as releaseKind from "./contracts/release_kind/release_kind.ts";
+
+import * as royaltyPool from "./contracts/royalty_pool/pool.ts";
+import * as royaltyStake from "./contracts/royalty_pool/stake.ts";
+import * as routedStake from "./contracts/routed_stake/routed_stake.ts";
+
+import * as partyCta from "./contracts/party_cta/party_cta.ts";
+import * as partyGenre from "./contracts/party_genre/party_genre.ts";
+import * as partyMedia from "./contracts/party_media/party_media.ts";
+import * as partyMusic from "./contracts/party_music/party_music.ts";
+import * as partyPlatformLink from "./contracts/party_platform_link/party_platform_link.ts";
+import * as partyProLink from "./contracts/party_pro_link/party_pro_link.ts";
+import * as partyProfile from "./contracts/party_profile/party_profile.ts";
+import * as partyRoles from "./contracts/party_roles/party_roles.ts";
+import * as partySocial from "./contracts/party_social/party_social.ts";
+import * as partyTags from "./contracts/party_tags/party_tags.ts";
+
+/** Generated modules mix BCS constants with transaction-builder functions. */
+type CodecModule<M extends object> = {
+  [Key in keyof M as M[Key] extends (...args: never[]) => unknown ? never : Key]: M[Key];
+};
+
+/** BCS-only projection: never leak Move-call builders into the `bcs` namespace. */
+function codecsOnly<M extends object>(mod: M): CodecModule<M> {
+  return Object.fromEntries(
+    Object.entries(mod).filter(([, value]) => typeof value !== "function"),
+  ) as CodecModule<M>;
+}
+
+/**
+ * Public Move functions that return references. A PTB can borrow internally,
+ * but a Move-call command result cannot carry a reference to a later command.
+ * Keep them out of `call`; use object/dynamic-field BCS queries instead.
+ */
+export const REF_RETURNING_CALLS = {
+  compositionCredits: ["credits"],
+  recordingCredits: ["credits", "primaryArtistIds", "featuredArtistIds"],
+  recordingMasterReference: ["masterReference"],
+  releaseCoverArt: ["cover"],
+  releaseCredits: ["credits"],
+  releaseDescription: ["description"],
+  // `new` is emitted as `_new`; its `&mut UID` parent credential cannot be
+  // constructed by a caller-side PTB, so only authority-package code may use it.
+  royaltyPool: ["balance", "_new"],
+  royaltyStake: ["balance", "getRegistration"],
+  // These lifecycle functions require a parent `&mut UID`, which cannot be a
+  // caller-provided PTB input. Only `share`, `sweep`, scalar reads and derives
+  // remain usable at this layer.
+  routedStake: ["stake", "_new", "register", "unregister", "unstake", "restake"],
+  partyProfile: ["profile"],
+} as const;
+
+/**
+ * All platform generated functions and BCS codecs bound to one full, verified
+ * deployment. The `call` namespaces construct only caller-owned PTB commands.
+ * They neither set gas nor sign/execute. Query dynamic fields directly rather
+ * than using a Move function whose return type is a reference: PTB command
+ * outputs cannot carry references.
+ */
+export class MisoPlatformPackageBindings {
+  readonly deployment: MisoPlatformDeployment;
+
+  constructor(deployment: MisoPlatformDeployment) {
+    this.deployment = normalizeMisoPlatformDeployment(deployment);
+  }
+
+  get call() {
+    const p = this.deployment.packages;
+    const party_ = this.deployment.party;
+    const partyosPkg = this.deployment.partyos.partyos;
+    return {
+      extensions: {
+        compositionCredits: {
+          compositionCredits: bindModulePackage(
+            compositionCredits,
+            p.compositionCredits,
+            REF_RETURNING_CALLS.compositionCredits,
+          ),
+          compositionPartyRole: bindModulePackage(
+            compositionPartyRole,
+            p.compositionCredits,
+          ),
+        },
+        recordingAdvisory: bindModulePackage(recordingAdvisory, p.recordingAdvisory),
+        recordingCredits: {
+          recordingCredits: bindModulePackage(
+            recordingCredits,
+            p.recordingCredits,
+            REF_RETURNING_CALLS.recordingCredits,
+          ),
+          recordingPartyRole: bindModulePackage(
+            recordingPartyRole,
+            p.recordingCredits,
+          ),
+        },
+        recordingLanguage: bindModulePackage(recordingLanguage, p.recordingLanguage),
+        recordingMasterReference: bindModulePackage(
+          recordingMasterReference,
+          p.recordingMasterReference,
+          REF_RETURNING_CALLS.recordingMasterReference,
+        ),
+        releaseCoverArt: bindModulePackage(
+          releaseCoverArt,
+          p.releaseCoverArt,
+          REF_RETURNING_CALLS.releaseCoverArt,
+        ),
+        releaseCredits: {
+          releaseCredits: bindModulePackage(
+            releaseCredits,
+            p.releaseCredits,
+            REF_RETURNING_CALLS.releaseCredits,
+          ),
+          releasePartyRole: bindModulePackage(releasePartyRole, p.releaseCredits),
+        },
+        releaseDescription: bindModulePackage(
+          releaseDescription,
+          p.releaseDescription,
+          REF_RETURNING_CALLS.releaseDescription,
+        ),
+        releaseDspLink: bindModulePackage(releaseDspLink, p.releaseDspLink),
+        releaseGenre: bindModulePackage(releaseGenre, p.releaseGenre),
+        releaseKind: bindModulePackage(releaseKind, p.releaseKind),
+      },
+      primitives: {
+        royaltyPool: {
+          pool: bindModulePackage(royaltyPool, p.royaltyPool, REF_RETURNING_CALLS.royaltyPool),
+          stake: bindModulePackage(royaltyStake, p.royaltyPool, REF_RETURNING_CALLS.royaltyStake),
+        },
+        routedStake: bindModulePackage(routedStake, p.routedStake, REF_RETURNING_CALLS.routedStake),
+      },
+      party: {
+        // Party core: `@misofm/partyos`'s curated `contracts.party` barrel is
+        // already stripped of reference-returning calls (its own
+        // PARTY_REF_RETURNING_CALLS, the same set as REF_RETURNING_CALLS.party
+        // below), so no `unavailable` list is passed here.
+        core: bindModulePackage(partyCoreContracts, partyosPkg),
+        cta: bindModulePackage(partyCta, party_.partyCta),
+        genre: bindModulePackage(partyGenre, party_.partyGenre),
+        media: bindModulePackage(partyMedia, party_.partyMedia),
+        music: bindModulePackage(partyMusic, party_.partyMusic),
+        platformLink: bindModulePackage(partyPlatformLink, party_.partyPlatformLink),
+        proLink: bindModulePackage(partyProLink, party_.partyProLink),
+        profile: bindModulePackage(partyProfile, party_.partyProfile, REF_RETURNING_CALLS.partyProfile),
+        roles: bindModulePackage(partyRoles, party_.partyRoles),
+        social: bindModulePackage(partySocial, party_.partySocial),
+        tags: bindModulePackage(partyTags, party_.partyTags),
+      },
+    };
+  }
+
+  /** Generated BCS codecs, grouped with the same ownership boundary as `call`. */
+  get bcs() {
+    return {
+      extensions: {
+        compositionCredits: {
+          compositionCredits: codecsOnly(compositionCredits),
+          compositionPartyRole: codecsOnly(compositionPartyRole),
+        },
+        recordingAdvisory: codecsOnly(recordingAdvisory),
+        recordingCredits: {
+          recordingCredits: codecsOnly(recordingCredits),
+          recordingPartyRole: codecsOnly(recordingPartyRole),
+        },
+        recordingLanguage: codecsOnly(recordingLanguage),
+        recordingMasterReference: codecsOnly(recordingMasterReference),
+        releaseCoverArt: codecsOnly(releaseCoverArt),
+        releaseCredits: {
+          releaseCredits: codecsOnly(releaseCredits),
+          releasePartyRole: codecsOnly(releasePartyRole),
+        },
+        releaseDescription: codecsOnly(releaseDescription),
+        releaseDspLink: codecsOnly(releaseDspLink),
+        releaseGenre: codecsOnly(releaseGenre),
+        releaseKind: codecsOnly(releaseKind),
+      },
+      primitives: {
+        royaltyPool: { pool: codecsOnly(royaltyPool), stake: codecsOnly(royaltyStake) },
+        routedStake: codecsOnly(routedStake),
+      },
+      party: {
+        core: codecsOnly(partyCoreContracts),
+        cta: codecsOnly(partyCta),
+        genre: codecsOnly(partyGenre),
+        media: codecsOnly(partyMedia),
+        music: codecsOnly(partyMusic),
+        platformLink: codecsOnly(partyPlatformLink),
+        proLink: codecsOnly(partyProLink),
+        profile: codecsOnly(partyProfile),
+        roles: codecsOnly(partyRoles),
+        social: codecsOnly(partySocial),
+        tags: codecsOnly(partyTags),
+      },
+    };
+  }
+}
+
+/** Construct complete platform package bindings from an explicit verified manifest. */
+export function misoPlatformPackages(
+  deployment: MisoPlatformDeployment,
+): MisoPlatformPackageBindings {
+  return new MisoPlatformPackageBindings(deployment);
+}