@misofm/platform 0.24.0 → 0.26.0

package/README.md

@@ -1,25 +1,36 @@
 # @misofm/platform
 
 The complete client SDK for the **Miso platform layer** on Sui: composed catalog,
-artist, wallet, and receipt reads; the record production line and sale of copies;
-and fail-closed Vault custody, raw Actions, and safe crank plugins built on `@misofm/protocol`'s
-protocol and data-extension primitives.
-
-## The split
-
-Miso ships two SDK packages, and the package name tells you which promise you are
-holding:
-
-| Package             | Layer        | Owns                                                                                                                                   |
-| -------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `@misofm/protocol` | **Protocol** | Composition, Recording, Release, Party identity; metadata/data extensions; utilities; generic royalty-pool and routed-stake primitives |
-| `@misofm/platform` | **Platform** | Pressing, Listing, Record, and an explicitly deployed Vault/Action/plugin compatibility set                                           |
-
-A release is protocol. Pressing a record off that release and selling it is
-platform. So is deciding _what to do_ with a freshly-minted work's share
-supply — the protocol only knows how to mint one. Keeping the boundary at the
-package line is what stops the open protocol from quietly growing a
-storefront (or an opinion about tokenomics).
+artist, wallet, and receipt reads; the Party extensions (profile, media, roles,
+tags, genres, CTAs, platform links); the record production line and sale of
+copies; fail-closed Vault custody, raw Actions, and safe crank plugins; and
+every first-party extension and generic royalty primitive built on top of the
+`@misofm/musicos` object model and the `@misofm/partyos` Party identity model.
+
+## The boundary rule
+
+> `@misofm/musicos` is the object model. Everything Miso offers on top of it is
+> platform.
+
+Miso ships three SDK packages, and the package name tells you which promise
+you are holding:
+
+| Package            | Layer        | Owns                                                                                                          |
+| ------------------- | ------------ | -------------------------------------------------------------------------------------------------------------- |
+| `@misofm/musicos`  | **Object model** | Composition, Recording, Release, Track — the open Move package anyone can build on, no permission required |
+| `@misofm/partyos`  | **Party identity** | Party, PartyAdminCap, and consent-based group membership — the open Move package Party identity is built on |
+| `@misofm/platform` | **Platform** | The Party extensions (profile, media, roles, tags, genres, CTAs, platform links); work extensions; generic royalty-pool/routed-stake primitives; Actions; Vault; Record/Record Shop; product-specific publishing workflows |
+
+A release is object model. Pressing a record off that release and selling it
+is platform. So is deciding _what to do_ with a freshly-minted work's share
+supply — the object model only knows how to mint one. Likewise, a Party is
+identity — who or what is being described — and lives in `@misofm/partyos`;
+everything Miso attaches to that identity (a profile, media, roles, tags,
+genres, CTAs, platform links) is an opinion about how to describe or route
+value around it, not part of what the Party IS, so those extensions live in
+platform alongside work extensions and every royalty primitive. Keeping the
+boundary at the package line is what stops the open object models from
+quietly growing a storefront (or an opinion about tokenomics).
 
 Extensions add data to a work. Raw Actions accept an admin cap and remain
 composable with either direct authority or a scoped Vault borrow. Three safe,
@@ -31,7 +42,7 @@ address-owned admin caps explicitly; it never silently treats a legacy cap as a
 vaulted one. New Vault IDs are derived from the shared `VaultRegistry`, the raw
 cap ID, and its type; each VaultAdminCap ID is then derived from its Vault.
 
-This package depends on `@misofm/protocol` directly and imports its bare
+This package depends on `@misofm/musicos` directly and imports its bare
 `createComposition`/`createRecording` primitives, composing them with its own
 minato-dispersal and share-currency logic in the same PTB — the
 transaction-thunk composition pattern from the
@@ -39,11 +50,11 @@ transaction-thunk composition pattern from the
 crossing a package boundary.
 
 ```sh
-bun add @misofm/platform@^0.18.0
+bun add @misofm/platform
 ```
 
-`@misofm/protocol` resolves transitively through that dependency, so
-applications get exactly one protocol SDK and one compatible deployment map
+`@misofm/musicos` resolves transitively through that dependency, so
+applications get exactly one object-model SDK and one compatible deployment map
 without installing it themselves. Registration takes a recursively frozen
 snapshot of custom deployment/config records without freezing the caller's
 original objects, so later caller mutation cannot retarget an existing client.
@@ -87,7 +98,14 @@ singletons.
 Register the client extension on any client implementing Sui's Core API
 ([SDK building guidelines](https://sdk.mystenlabs.com/sui/sdk-building)):
 
+Every method that performs I/O — a chain read, a signed execution — returns an
+`Effect.Effect<A, E>` (`R = never`: the client already provided `SuiClient`
+internally). Run a program with `Effect.runPromise` (or compose it further
+with other Effects) at your own boundary; PTB builders (`tx.*`) stay plain
+synchronous functions.
+
 ```ts
+import { Effect } from "effect";
 import { SuiGrpcClient } from "@mysten/sui/grpc";
 import { Transaction } from "@mysten/sui/transactions";
 import { miso } from "@misofm/platform";
@@ -96,35 +114,58 @@ const client = new SuiGrpcClient({ network: "testnet", baseUrl }).$extend(
   miso({ deployment: verifiedDeployment }),
 );
 
-// One memoized Core API read proves this endpoint is the deployment's exact
-// ledger before any synchronous client-bound builder can be used.
-await client.miso.ready();
-
-// The permissionless protocol SDK is part of the same facade.
-const release = await client.miso.protocol.getReleaseById(releaseId);
-const party = await client.miso.party.getPartyById(partyId);
+const program = Effect.gen(function* () {
+  // One memoized Core API read proves this endpoint is the deployment's exact
+  // ledger before any synchronous client-bound builder can be used.
+  yield* client.miso.ready();
+
+  // The permissionless object-model SDK is part of the same facade.
+  const release = yield* client.miso.protocol!.getReleaseById(releaseId); // protocol is set once ready() succeeded
+  // Party identity comes from @misofm/partyos; platform adds the extensions.
+  // client.miso.party is a PartyPlatformClient wrapping a PartyosClient (core
+  // reads/builders delegate straight through) bound to this deployment's
+  // `partyos` (core) and `party` (extensions) sections — also importable
+  // standalone from `@misofm/platform/party`.
+  const party = yield* client.miso.party.getPartyById(partyId);
+
+  // Read: run + one currency's offer, one round trip, no registry lookup.
+  const { pressing, listing } = yield* client.miso.getSale({
+    releaseId,
+    edition,
+    currencyType: USD_COIN_TYPE,
+  });
 
-// Read: run + one currency's offer, one round trip, no registry lookup.
-const { pressing, listing } = await client.miso.getSale({
-  releaseId,
-  edition,
-  currencyType: USD_COIN_TYPE,
+  return { release, party, pressing, listing };
 });
 
-// Write: a thunk, so it composes with protocol calls in the same PTB.
+const { pressing, listing } = await Effect.runPromise(program);
+
+// Write: a thunk, so it composes with protocol calls in the same PTB. `tx`
+// builders never touch the network — no Effect involved.
 const tx = new Transaction();
 tx.add(
   client.miso.tx.purchaseRecord({
     releaseId,
     edition,
     currencyType: USD_COIN_TYPE,
-    paymentAmount: listing.pricing.amount,
-    expectedPricing: listing.pricing,
+    paymentAmount: listing!.pricing.amount,
+    expectedPricing: listing!.pricing,
     recipient: buyer,
   }),
 );
 ```
 
+A read that can fail closed (a missing release, a mismatched chain identifier)
+fails with one of this SDK's tagged errors — see [Errors](#errors) — so
+recover with `Effect.catchTag`/`Effect.catchTags` instead of inspecting a
+thrown message:
+
+```ts
+const releaseOrNull = client.miso.protocol!
+  .getReleaseById(releaseId)
+  .pipe(Effect.catchTag("ObjectNotFoundError", () => Effect.succeed(null)));
+```
+
 The bundled Testnet deployment includes both verified immutable package IDs.
 Custom deployments can still mark sales unavailable explicitly; sales builders
 and readers fail closed whenever either package is unavailable.
@@ -141,6 +182,47 @@ Verified package and singleton IDs are bundled in
 from the Sui client's network. Unbundled and custom networks still fail closed
 unless the caller passes one complete deployment through `miso({ deployment })`.
 
+The deprecated `misoPlatform(config)` constructor remains for callers that
+supply flat package ids instead of a complete deployment; it registers at
+`client.misoPlatform` instead of `client.miso` and requires the same
+`await client.misoPlatform.ready()` gate before use. Prefer zero-config
+`miso()` for new integrations.
+
+### Party and the generated contract tree
+
+Party identity (the `Party` object, `PartyAdminCap`, group membership) is
+owned by `@misofm/partyos`; this package only owns the extensions attached to
+it. `PartyPlatformClient` wraps a `PartyosClient` — every core method
+(`getPartyById`, `getMemberships`, …) delegates straight through, and `tx`/
+`call`/`bcs` merge the core and extension surfaces — and is also importable
+standalone (the same class `client.miso.party` returns):
+
+```ts
+import { Effect } from "effect";
+import { PartyosClient } from "@misofm/partyos";
+import { PartyPlatformClient } from "@misofm/platform/party";
+
+const core = new PartyosClient(client, verifiedDeployment.partyos);
+const party = new PartyPlatformClient(client, core, verifiedDeployment.party);
+
+// Every read method returns Effect<A, E> (R = never) — the class already
+// carries the ClientWithCoreApi it was constructed with.
+const profile = await Effect.runPromise(party.getProfile(partyId)); // Option<Profile>
+```
+
+Every generated Move package on this side of the boundary — the Party
+extensions, work extensions, royalty/routed-stake primitives, Record/Record
+Shop, Vault, and every Action/plugin — is reachable through the curated
+`contracts` barrel (`@misofm/platform` → `contracts.*`, or
+`@misofm/platform/contracts` directly) or, for a module the barrel doesn't
+curate, the raw generated file itself. The Party core's generated bindings
+live in `@misofm/partyos/contracts` instead:
+
+```ts
+import { record } from "@misofm/platform/contracts";
+import { Record } from "@misofm/platform/contracts/record/record";
+```
+
 ### High-level platform reads
 
 `@misofm/platform/read` turns protocol, pressing, Party, credits, cover, and wallet
@@ -148,7 +230,14 @@ objects into the JSON-safe views a client actually renders. It works in browsers
 Workers, and servers. Miso's HTTP API is a thin validated and cached transport over
 this same surface, not a separate domain implementation.
 
+Every read here takes the resolved `MisoConfig` (package ids, not a transport)
+and declares `SuiClient`/`SuiGraphQL` in its Requirements — `createMisoClient`
+still bundles the transport, config, and Party client the way it always did;
+provide its `sui`/`graphqlRaw` as the Effect services once, at the boundary:
+
 ```ts
+import { Effect, Layer } from "effect";
+import { SuiClient, SuiGraphQL } from "@misofm/effect";
 import {
   createMisoClient,
   getDiscoverShelf,
@@ -157,10 +246,16 @@ import {
 } from "@misofm/platform/read";
 
 const miso = createMisoClient({ config: verifiedReadConfig });
+const layer = Layer.mergeAll(SuiClient.layer(miso.sui), SuiGraphQL.layer(miso.graphqlRaw));
+
+const program = Effect.gen(function* () {
+  const discover = yield* getDiscoverShelf(miso.config);
+  const release = yield* getReleaseDetail(releaseId, miso.config);
+  const library = yield* getOwnedRecords(walletAddress, miso.config);
+  return { discover, release, library };
+});
 
-const discover = await getDiscoverShelf(miso);
-const release = await getReleaseDetail(miso, releaseId);
-const library = await getOwnedRecords(miso, walletAddress);
+const { discover, release, library } = await Effect.runPromise(program.pipe(Effect.provide(layer)));
 ```
 
 The package root also exposes the same functions under the `read` namespace:
@@ -169,7 +264,9 @@ The package root also exposes the same functions under the `read` namespace:
 import { read } from "@misofm/platform";
 
 const miso = read.createMisoClient({ config: verifiedReadConfig });
-const artist = await read.getArtistProfile(miso, partyId);
+const artist = await Effect.runPromise(
+  read.getArtistProfile(partyId, miso.config).pipe(Effect.provide(SuiClient.layer(miso.sui))),
+);
 ```
 
 ### Authenticated platform mutations
@@ -240,7 +337,7 @@ the same PTB.
 
 ## Publishing (`transactions.ts`, `share.ts`, `release-graph.ts`)
 
-`@misofm/protocol`'s `createComposition`/`createRecording` mint a work and hand
+`@misofm/musicos`'s `createComposition`/`createRecording` mint a work and hand
 back its by-value parts (the object, its admin cap, its freshly-minted share
 `Balance`) without dispersing, sharing, or transferring anything. This package
 supplies the opinionated finish on top:
@@ -269,7 +366,7 @@ const thunk = client.miso.tx.publishComposition({
 
 `client.miso.tx.publishRecording` and `publishCompositionAndRecording`
 follow the same shape (the latter atomically, borrow-before-share, in one PTB —
-see `@misofm/protocol`'s README for why the ordering is load-bearing).
+see `@misofm/musicos`'s README for why the ordering is load-bearing).
 The protocol, immutable Record and Record Shop packages, minato, and core
 `ReleaseRegistry` address all come from the deployment selected by the Sui
 client's network. Record sales have no Record Registry or Settings singleton.
@@ -366,6 +463,7 @@ Recording creator remainder; lower-level routed-stake builders remain
 available for the Move layer's 100% composition-cut case.
 
 ```ts
+import { Effect } from "effect";
 import {
   assertAtomicPublicationBounds,
   parseAtomicPublicationResult,
@@ -385,9 +483,8 @@ const publication = {
 // PTB exceeds the SDK's command/input safety limits or has an invalid graph.
 assertAtomicPublicationBounds(publication);
 
-const executed = await client.miso.executeViaExecutor(
-  executor,
-  publishAtomicCatalog(publication),
+const executed = await Effect.runPromise(
+  client.miso.executeViaExecutor(executor, publishAtomicCatalog(publication)),
 );
 const result = parseAtomicPublicationResult(publication, executed);
 ```
@@ -414,35 +511,36 @@ embedded as `SHARE_TEMPLATE`, initializer patched via `patchInitializer`).
 Publish and initialize are necessarily two transactions:
 
 ```ts
+import { Effect } from "effect";
+
 // Sequential (one currency, two txs):
-const currency = await client.miso.createShareCurrency(signer, {
-  name: "Song Shares",
-  description: "…",
-});
+const currency = await Effect.runPromise(
+  client.miso.createShareCurrency(signer, {
+    name: "Song Shares",
+    description: "…",
+  }),
+);
 // → { packageId, currencyId, shareType, treasuryCapId, gasUsed }
 
-// Batched (many currencies, via a ParallelTransactionExecutor):
+// Batched (many currencies, via a ParallelTransactionExecutor). Both submit
+// exclusively through the executor (R = never), unlike `createShareCurrency`
+// above, which needs `SuiClient` for its sequential `execThunks` calls.
 import { publishShareCurrencies, initializeShareCurrencies } from "@misofm/platform";
-const { packageIds } = await publishShareCurrencies(
-  executor,
-  initializerAddress,
-  10,
-);
-const { currencies } = await initializeShareCurrencies(
-  executor,
-  signerAddress,
-  packageIds,
-  (pkg) => ({
+
+const program = Effect.gen(function* () {
+  const { packageIds } = yield* publishShareCurrencies(executor, initializerAddress, 10);
+  return yield* initializeShareCurrencies(executor, signerAddress, packageIds, (pkg) => ({
     name: "…",
     description: "…",
-  }),
-);
+  }));
+});
+const { currencies } = await Effect.runPromise(program);
 ```
 
 `executeViaExecutor(executor, ...thunks)` (`execute.ts`) submits a
 non-idempotent PTB through a `ParallelTransactionExecutor` exactly once (no
 auto-retry) — it's what the batched provisioning above builds on, layered over
-`@misofm/protocol`'s transport-agnostic `buildTx`/`toExecResult`.
+`@misofm/musicos`'s transport-agnostic `buildTx`/`toExecResult`.
 
 ## Extensions
 
@@ -618,26 +716,87 @@ carry an optional `RecordingRoleLevel` (`Producer`, `Vocalist`, `Engineer`,
 (`Instrumentalist`, `Custom`, and the unleveled `ArtistsAndRepertoire` /
 `Copyist`) are spelled out separately in `RecordingRole`.
 
+## Errors
+
+Every typed failure is a `Schema.TaggedError` (`@misofm/platform/errors`),
+recoverable with `Effect.catchTag`/`Effect.catchTags` instead of message
+sniffing. The foundation's Sui read/write vocabulary
+(`ObjectNotFoundError { objectId }`, `ObjectTypeMismatchError { objectId,
+expected, actual }`, `SuiRpcError { operation, cause }`, `BcsDecodeError {
+type, objectId?, cause }`, `TransactionFailedError { digest, status }`,
+`GraphQLUnavailableError {}`, `DeploymentError { message }`) is re-exported
+from `@misofm/effect/errors` so this is the only import a consumer needs:
+
+```ts
+import {
+  ObjectNotFoundError,
+  ReleaseNotFoundError,
+  RecordSalesUnavailableError,
+  OperationsUnavailableError,
+  MisoChainIdentifierMismatchError,
+  MisoClientNotReadyError,
+  MisoNetworkMismatchError,
+} from "@misofm/platform/errors";
+```
+
+Platform-specific tags:
+
+| Error | Fields | Raised by |
+| --- | --- | --- |
+| `RecordSalesUnavailableError` | `reason` | `requireRecordSalesDeployment`, every sales read/builder on a legacy or unconfigured deployment |
+| `OperationsUnavailableError` | `reason` | `requireOperationsDeployment`, `client.miso.vault`/`call.*` operations surfaces |
+| `MisoPlatformDeploymentInvalidError` | `message` | `assertMisoPlatformDeployment` / `normalizeMisoPlatformDeployment` |
+| `MisoNetworkMismatchError` | `clientNetwork`, `deploymentNetwork` | `miso()`/`misoPlatform()` registration (synchronous) |
+| `MisoChainIdentifierMismatchError` | `actual`, `expected` | `client.miso.ready()` |
+| `MisoClientNotReadyError` | `operation` | synchronous client-bound surfaces (`tx`, `ids`, `call`, `vault`, `party`, `protocol`) used before `ready()` |
+| `MalformedRecordSoldEventError` | `digest?`, `reason?` | `findRecordSales`/`getPurchaseReceipt(s)` on a malformed `RecordSoldEvent` |
+| `MisoAuthError` | `code`, `reason`, `status?`, `cause?` | `@misofm/platform/auth` (`requestAuthorizationChallenge`, `authenticatedFetch`, …) |
+| `ReleaseNotFoundError` | `releaseId` | `@misofm/platform/read` (`getReleaseResources`, `getReleaseDetail`, …) — the typed replacement for the api read service's old `isMissingRelease` message bridge |
+| `ReceiptNotFoundError` | `digest` | `getPurchaseReceipt(s)` when neither the fullnode nor the indexer has the transaction |
+| `RecordPurchaseNotFoundError` | `digest` | `getPurchaseReceipt(s)` when the transaction exists but carries no `RecordSoldEvent` |
+| `ForeignPressingError` | `pressingId`, `actualType?` | reserved for read-layer Pressing type-mismatch bridging |
+
+```ts
+import { Effect } from "effect";
+
+const release = client.miso.protocol!
+  .getReleaseById(releaseId)
+  .pipe(
+    Effect.catchTags({
+      ObjectNotFoundError: () => Effect.succeed(null),
+      SuiRpcError: (e) => Effect.die(e), // transport failure: not recoverable here
+    }),
+  );
+```
+
 ## Layout
 
 ```
 src/
-  deployments.ts         fail-closed deployment schema and future address injection point
-  client.ts              the full client.miso facade; protocol and Party live at client.miso.protocol / .party
+  deployments.ts         fail-closed deployment schema (MisoPlatformDeployment, PartyExtensionsDeployment) and address injection point
+  client.ts              the full client.miso facade; object-model core lives at client.miso.protocol, Party at client.miso.party
+  packages.ts            MisoPlatformPackageBindings: extensions/primitives/party generated calls bound to one deployment
+  events.ts              platformEventParsers: extension + generic-primitive event decoders
+  royalty.ts             generic royalty-pool / stake / routed-stake derive helpers and PTB builders
   pressing.ts            facade: builders, readers, and the id derivations
-  queries.ts             shared read plumbing (isNotFound, re-exported from @misofm/protocol)
+  queries.ts             shared read plumbing (isNotFound, re-exported from @misofm/musicos)
   transactions.ts        the TxThunk contract + the opinionated publish flow (disperse/finalize/publish*)
   release-graph.ts        whole release graph in one PTB (publishReleaseGraph)
+  publication.ts         atomic catalog publication (publishAtomicCatalog)
   share.ts               share-currency provisioning (createShareCurrency, batched variants)
   share-template.ts      embedded `share` package bytecode
   credits.ts             EXTENSION: contributor credits + the three role vocabularies
   cover.ts               EXTENSION: release cover art (Walrus blob via ori)
+  genre.ts               EXTENSION: release/recording genre vocabulary
+  release-extensions.ts  EXTENSION: release kind, description, DSP links
+  recording-extensions.ts EXTENSION: recording advisory, language, master reference, streaming transcode
+  party/                 Party EXTENSIONS: profile, media, roles, tags, genres, CTAs, links (PartyPlatformClient, wraps @misofm/partyos's PartyosClient) — also `@misofm/platform/party`
   read/                  high-level catalog, artist, wallet, and receipt views
   vault.ts               Vault authority, plugin, event, and receiving-coin builders
-  execute.ts              executeViaExecutor, layered on @misofm/protocol's buildTx/toExecResult
+  execute.ts              executeViaExecutor, layered on @misofm/musicos's buildTx/toExecResult
   internal.ts            private helpers (the 0x1::option moveCall targets) — NOT exported
-  contracts.ts           barrel re-exporting the generated bindings as `contracts`
-  contracts/             GENERATED — do not edit by hand
+  contracts.ts           barrel re-exporting the curated generated bindings as `contracts`
+  contracts/             GENERATED — do not edit by hand; also reachable raw via `@misofm/platform/contracts/*`
 ```
 
 ## Codegen
@@ -649,41 +808,49 @@ the on-chain ABI:
 bun run codegen   # reads sui-codegen.config.ts → src/contracts/
 ```
 
-`sui-codegen.config.ts` lists `miso_record`, `miso_record_shop`, data
-extensions, generic `royalty_pool`/`routed_stake`, and the `vault` plus all
-vault-plugin packages. The protocol CORE (`miso` —
-composition/recording/release/track) generates into
-`@misofm/protocol` instead, which this package depends on for those bindings —
-adding the core here to save an import is how the split this package exists to
-enforce gets undone.
+This package's generated tree (`src/contracts/`) covers every Move package this
+side of the boundary rule — the ten `party_*` extensions plus `party_wallet`,
+work extensions, generic royalty/routed-stake primitives, Record and Record
+Shop, Vault, and every Action/plugin package. The Party core (`partyos`)
+generates into `@misofm/partyos`, and the object-model core
+(composition/recording/release/track) generates into `@misofm/musicos`;
+this package depends on both for those bindings — adding either core here to
+save an import is how the split these packages exist to enforce gets undone.
 
-Paths resolve against sibling checkouts, so regenerating requires
-`~/Documents/GitHub/misofm/{sdk, record, record-shop, vault, vault-plugins}` and
-`~/Documents/GitHub/misonetwork/{party-actions, protocol, protocol-actions,
-protocol-extensions, royalty-pool, routed-stake, share, cover-art, genre}`.
+The root `sui-codegen.config.ts` (one level up from this package) is the
+source of truth for exactly which Move packages generate into which package's
+tree, and where their sibling checkouts resolve from; read it rather than
+relying on an enumeration here going stale.
+
+```sh
+bun run codegen   # reads ../../sui-codegen.config.ts → src/contracts/
+```
 
-For an isolated checkout, copy those source trees and set
+For an isolated checkout, copy the source trees it lists and set
 `MISO_SDK_CODEGEN_SOURCE_ROOT` to their common parent. The codegen config reads
 only from that copy, avoiding writes to a developer's live source tree.
 
-## Dependency on `@misofm/protocol`
+## Dependency on `@misofm/musicos` and `@misofm/partyos`
 
-`@misofm/protocol` is a regular runtime dependency of this package (a workspace
-dependency in this monorepo, resolved to a published version range on publish),
-not a peer. This package imports its primitives, deployment configuration,
-protocol client, and Party client directly, then exposes them at
-`client.miso.protocol` and `client.miso.party` only after
-`await client.miso.ready()` validates the exact ledger. Direct protocol reads,
-generated calls, package bindings, and nested Party APIs cannot be obtained
-before that gate.
+`@misofm/musicos` and `@misofm/partyos` are regular runtime dependencies of
+this package (workspace dependencies in this monorepo, resolved to published
+version ranges on publish), not peers. This package imports their primitives
+and deployment configuration directly, then exposes the object-model client
+at `client.miso.protocol` only after `await client.miso.ready()` validates the
+exact ledger. `client.miso.party` is a `PartyPlatformClient`
+(`@misofm/platform/party`) wrapping a `PartyosClient` from `@misofm/partyos`
+for the Party core, with the first-party extensions (profile, media, roles,
+tags, genres, CTAs, platform links) layered on top. Direct object-model
+reads, generated calls, package bindings, and Party APIs (core and
+extensions alike) cannot be obtained before the readiness gate.
 
 `@mysten/sui` itself stays a peer dependency here, so an application resolves
-exactly one Sui SDK across both packages regardless of which protocol version
-`@misofm/platform` pins.
+exactly one Sui SDK across all three packages regardless of which
+object-model or Party-identity version `@misofm/platform` pins.
 
 ```bash
 bun add @misofm/platform
 ```
 
-`@misofm/protocol` resolves automatically as a transitive dependency; there is
+`@misofm/musicos` resolves automatically as a transitive dependency; there is
 no separate install step and no peer version for consumers to reconcile.

package/dist/auth.d.ts

@@ -1,3 +1,7 @@
+import { Effect } from "effect";
+import { MisoAuthError, type MisoAuthErrorCode } from "./errors.ts";
+export type { MisoAuthErrorCode };
+export { MisoAuthError };
 export type AuthNetwork = "testnet" | "mainnet";
 export interface ApiAuthorizationFields {
     method: string;
@@ -23,15 +27,6 @@ export declare const MISO_AUTH_HEADERS: {
     readonly signature: "X-Sui-Signature";
     readonly issuedAt: "X-Sui-Issued-At";
 };
-export type MisoAuthErrorCode = "invalid_target" | "challenge_rejected" | "invalid_challenge" | "signing_failed";
-export declare class MisoAuthError extends Error {
-    readonly code: MisoAuthErrorCode;
-    readonly status?: number;
-    constructor(code: MisoAuthErrorCode, message: string, options?: {
-        status?: number;
-        cause?: unknown;
-    });
-}
 /** The byte-exact Sui personal message required for an authenticated API mutation. */
 export declare function buildApiAuthorizationPayload(fields: ApiAuthorizationFields): string;
 export declare function isValidAuthorizationTarget(method: string, path: string): boolean;
@@ -49,15 +44,15 @@ export interface RequestAuthorizationChallengeOptions {
     nowMs?: number;
 }
 /** Ask Miso to verify the Enoki account and issue the exact message to sign. */
-export declare function requestAuthorizationChallenge(options: RequestAuthorizationChallengeOptions): Promise<AuthorizationChallenge>;
+export declare const requestAuthorizationChallenge: (options: RequestAuthorizationChallengeOptions) => Effect.Effect<AuthorizationChallenge, MisoAuthError, never>;
 export interface CreateAuthorizationHeadersOptions extends RequestAuthorizationChallengeOptions {
     signer: PersonalMessageSigner;
 }
 /** Verify the challenge locally, sign it as a Sui personal message, and produce API headers. */
-export declare function createAuthorizationHeaders(options: CreateAuthorizationHeadersOptions): Promise<{
+export declare const createAuthorizationHeaders: (options: CreateAuthorizationHeadersOptions) => Effect.Effect<{
     challenge: AuthorizationChallenge;
     headers: Headers;
-}>;
+}, MisoAuthError, never>;
 export interface AuthenticatedFetchOptions extends RequestInit {
     auth: {
         token: string;
@@ -69,5 +64,5 @@ export interface AuthenticatedFetchOptions extends RequestInit {
     fetch?: typeof globalThis.fetch;
 }
 /** Perform a protected Miso API mutation with a fresh Enoki-verified Sui signature. */
-export declare function authenticatedFetch(input: string | URL, options: AuthenticatedFetchOptions): Promise<Response>;
+export declare const authenticatedFetch: (input: string | URL, options: AuthenticatedFetchOptions) => Effect.Effect<Response, MisoAuthError, never>;
 //# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEpE,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAuB,SAAQ,sBAAsB;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,mBAAmB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1F;AAED,eAAO,MAAM,wBAAwB,QAAiB,CAAC;AACvD,eAAO,MAAM,4BAA4B,QAAa,CAAC;AAEvD,eAAO,MAAM,iBAAiB;aAC5B,OAAO,EAAE,eAAe;aACxB,SAAS,EAAE,iBAAiB;aAC5B,QAAQ,EAAE,iBAAiB;CACnB,CAAC;AAEX,sFAAsF;AACtF,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAUnF;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAOhF;AAED,8DAA8D;AAC9D,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAYzG;AA4FD,MAAM,WAAW,oCAAoC;IACnD,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gFAAgF;AAChF,eAAO,MAAM,6BAA6B,gHAwCxC,CAAC;AAEH,MAAM,WAAW,iCAAkC,SAAQ,oCAAoC;IAC7F,MAAM,EAAE,qBAAqB,CAAC;CAC/B;AAED,gGAAgG;AAChG,eAAO,MAAM,0BAA0B;eAEN,sBAAsB;aAAW,OAAO;wBAqBvE,CAAC;AAEH,MAAM,WAAW,yBAA0B,SAAQ,WAAW;IAC5D,IAAI,EAAE;QACJ,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,qBAAqB,CAAC;QAC9B,OAAO,CAAC,EAAE,WAAW,CAAC;KACvB,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,uFAAuF;AACvF,eAAO,MAAM,kBAAkB,4GA+B7B,CAAC"}