@misofm/platform 0.27.0 → 0.28.0

package/README.md

@@ -7,6 +7,16 @@ 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.
 
+`@misofm/platform` is a [sui-effect](https://github.com/unconfirmedlabs/sui-effect)
+extension: one `Context.Service` (`Miso`), built on `sui-effect`'s `Sui`,
+`SuiGraphQL`, and `Tx`, composed over the converted `Musicos`/`Partyos`
+services, whose members are `Effect`s with closed error unions, whose writes
+are PTB fragments (`Recipe`s) a consumer composes and submits once, and whose
+Promise face is derived — never hand-written — by `SuiExtension.fromService`.
+See `node_modules/@unconfirmed/sui-effect/docs/extensions.md` for the contract every
+extension in this codebase follows, and ["Migrating from 0.27"](#migrating-from-027)
+below if you're coming from the hand-written `MisoPlatformClient`.
+
 ## The boundary rule
 
 > `@misofm/musicos` is the object model. Everything Miso offers on top of it is
@@ -42,22 +52,27 @@ 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/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
-[Sui SDK building guide](https://sdk.mystenlabs.com/sui/sdk-building), just
-crossing a package boundary.
+This package depends on `@misofm/musicos` and `@misofm/partyos` directly and
+composes their converted `Musicos`/`Partyos` services internally, so
+`Miso.layer`'s requirement channel stays `Sui | SuiGraphQL` — never
+`Sui | SuiGraphQL | Musicos | Partyos` — for a consumer that only asked for
+`Miso`. Writes still compose in one PTB (the transaction-fragment pattern from
+the [Sui SDK building guide](https://sdk.mystenlabs.com/sui/sdk-building)),
+just crossing a package boundary.
+
+## Install
 
 ```sh
-bun add @misofm/platform
+bun add @misofm/platform @unconfirmed/sui-effect effect @mysten/sui @mysten/bcs
 ```
 
-`@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.
+Peer dependencies: `@unconfirmed/sui-effect@^0.1.0`, `effect@>=4.0.0-rc.112 <4.1`,
+`@mysten/sui@^2.28`, `@mysten/bcs@^2.1.1`. `@misofm/musicos` and
+`@misofm/partyos` resolve transitively through this package, so applications
+get exactly one object-model SDK, one Party-identity SDK, and one compatible
+deployment map without installing either themselves. A custom deployment is
+recursively frozen at `Miso.layer` build, without freezing the caller's
+original object, so later caller mutation cannot retarget an existing client.
 
 ### Engine sessions
 
@@ -95,53 +110,72 @@ singletons.
 
 ## Usage
 
-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.
+### Effect
 
 ```ts
 import { Effect } from "effect";
-import { SuiGrpcClient } from "@mysten/sui/grpc";
-import { Transaction } from "@mysten/sui/transactions";
-import { miso } from "@misofm/platform";
+import { Sui, SuiCore, SuiGraphQL } from "@unconfirmed/sui-effect";
+import { ObjectId } from "@unconfirmed/sui-effect";
+import { Miso } from "@misofm/platform";
+import { getMisoPlatformDeployment } from "@misofm/platform/deployments";
 
-const client = new SuiGrpcClient({ network: "testnet", baseUrl }).$extend(
-  miso({ deployment: verifiedDeployment }),
-);
+const deployment = getMisoPlatformDeployment("testnet");
 
 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);
+  const miso = yield* Miso;
+
+  // The permissionless object-model and Party surfaces are part of the same service.
+  // Ids are branded: brand a trusted string with ObjectId.make, decode untrusted input.
+  const release = yield* miso.protocol.getReleaseById(ObjectId.make(releaseId));
+  const party = yield* miso.party.getPartyById(ObjectId.make(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,
-  });
+  const { pressing, listing } = yield* miso.getSale({ releaseId, edition, currencyType: USD_COIN_TYPE });
 
   return { release, party, pressing, listing };
 });
 
-const { pressing, listing } = await Effect.runPromise(program);
+const { release, party, pressing, listing } = await program.pipe(
+  Effect.provide(Miso.layer(deployment)),
+  Effect.provide(Sui.layerNoDeps),
+  Effect.provide(SuiCore.layerGrpc({ network: "testnet", baseUrl: "https://..." })),
+  Effect.provide(SuiGraphQL.layerConfig), // or SuiGraphQL.layerUnavailable with no endpoint
+  Effect.runPromise,
+);
+```
+
+Inside a `Script` or an existing `sui-effect`-based program, just `yield* Miso`
+after providing `Miso.layer(deployment)` (or `layerConfig`) over the `Sui | SuiGraphQL`
+your program already has.
 
-// Write: a thunk, so it composes with protocol calls in the same PTB. `tx`
-// builders never touch the network — no Effect involved.
+A read that can fail closed (a missing release, an unavailable Record sales
+deployment) 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 = miso.protocol
+  .getReleaseById(ObjectId.make(releaseId))
+  .pipe(Effect.catchTag("ObjectNotFound", () => Effect.succeed(null)));
+```
+
+### Promise
+
+```ts
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+import { Transaction } from "@mysten/sui/transactions";
+import { miso } from "@misofm/platform/client";
+
+const client = new SuiGrpcClient({ network: "testnet", baseUrl }).$extend(miso());
+
+// The face keeps a member's argument types, and every namespace is nested:
+// client.miso.protocol.*, client.miso.party.*, client.miso.read.*.
+const release = await client.miso.protocol.getReleaseById(ObjectId.make(releaseId));
+const party = await client.miso.party.getPartyById(ObjectId.make(partyId));
+const { pressing, listing } = await client.miso.getSale({ releaseId, edition, currencyType: USD_COIN_TYPE });
+
+// Write: a Recipe, so it composes with protocol/party calls in the same PTB.
+// `tx` builders never touch the network — no Effect, no Promise involved.
 const tx = new Transaction();
 tx.add(
   client.miso.tx.purchaseRecord({
@@ -153,61 +187,68 @@ tx.add(
     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)));
+await client.miso.dispose();
 ```
 
-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.
+`miso()` registers **warm** — `tx`/`ids`/`call`/`bcs`/`vault`/`deployment` are
+synchronous members a consumer reads the moment it registers, and `Miso.layer`
+touches no network at build for a client on `mainnet` or `testnet` (their
+chain identifiers are in sui-effect's built-in table). On `devnet`,
+`localnet`, or a custom network, `warm` needs a chain identifier from
+somewhere: pass `chainId` explicitly, **or** pass a `deployment` whose own
+`chainIdentifier` names it (`options.chainId ?? options.deployment?.chainIdentifier`)
+— a custom deployment for your own network is enough on its own, nothing
+else to repeat. Without either, `client.$extend(miso())` throws
+synchronously, naming the network. **A network/deployment mismatch also
+throws synchronously here** (warm builds the layer inside `register`,
+so `Miso.layer`'s own `MisoNetworkMismatchError`/`MisoChainIdentifierMismatchError`
+surface immediately rather than on first call) — register lazily
+(`SuiExtension.fromService(Miso, { name: "miso", layer: Miso.layer(deployment) })`,
+no `warm`) if you want that check deferred to the first call instead, and
+`await client.miso.$ready()` once before reading a synchronous member.
+`miso()` on a network with no bundled manifest and no explicit `deployment`
+rejects typed (`MisoPlatformDeploymentInvalidError`), not with an unhandled
+defect.
+
+`dispose()` is not final: it releases the runtime the registration built, but
+the registration itself is unchanged. Because `miso()` registers `warm`, the
+next use after `dispose()` re-runs the warm build synchronously (since
+`@unconfirmed/sui-effect` 0.1.1), so a synchronous member read straight after
+`dispose()` is real again. Only a lazy, non-`warm` registration goes cold and
+throws `ExtensionNotReady` on a synchronous read until an `Effect` member is
+awaited or `$ready()` runs. Dispose when the consumer is actually done, not
+between calls.
+
+Verified package and singleton IDs are bundled in
+`MISO_PLATFORM_DEPLOYMENTS.testnet`. `miso()`/`Miso.layer` select that
+verified map from the client's network by default; pass an explicit
+`deployment` for a custom or unbundled network. The bundled Testnet
+deployment includes both verified immutable sales package IDs; custom
+deployments can still mark sales unavailable explicitly, and every sales
+builder/reader fails closed (typed `RecordSalesUnavailableError`) whenever
+either package is unavailable.
 
-Holding the ids yourself? The bare APIs take `recordPackageId` and/or
-`recordShopPackageId` explicitly:
+Holding the ids yourself, outside the service? The bare APIs take
+`recordPackageId`/`recordShopPackageId` explicitly and need only `Sui`:
 
 ```ts
 import { purchaseRecord, getSale } from "@misofm/platform/pressing";
 ```
 
-Verified package and singleton IDs are bundled in
-`MISO_PLATFORM_DEPLOYMENTS.testnet`. Calling `miso()` selects that verified map
-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):
+it. `miso.party` (`MisoPartyService`) delegates every core method
+(`getPartyById`, `getMemberships`, …) straight to the converted `Partyos`
+service, and merges in this package's own party EXTENSION reads and 25 `tx`
+fragments (9 from `Partyos.tx`, 16 first-party). It is assembled from `Sui`
+and `Partyos` — never constructed directly by a consumer; get it from
+`Miso`/`client.miso`:
 
 ```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>
+const profile = await client.miso.party.getProfile(partyId); // Option<Profile>
 ```
 
 Every generated Move package on this side of the boundary — the Party
@@ -231,13 +272,13 @@ Workers, and servers. Miso's HTTP API is a thin validated and cached transport o
 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:
+and declares `Sui`/`SuiGraphQL` in its Requirements — `createMisoClient`
+(`read/client.ts`) still bundles the transport, config, and the `client.miso`
+Promise face the way it always bundled a transport; provide its `layer`
+(`Miso | Sui | SuiCore | SuiGraphQL`) once, at the boundary:
 
 ```ts
-import { Effect, Layer } from "effect";
-import { SuiClient, SuiGraphQL } from "@misofm/effect";
+import { Effect } from "effect";
 import {
   createMisoClient,
   getDiscoverShelf,
@@ -245,8 +286,7 @@ import {
   getOwnedRecords,
 } from "@misofm/platform/read";
 
-const miso = createMisoClient({ config: verifiedReadConfig });
-const layer = Layer.mergeAll(SuiClient.layer(miso.sui), SuiGraphQL.layer(miso.graphqlRaw));
+const miso = createMisoClient({ network: "testnet" });
 
 const program = Effect.gen(function* () {
   const discover = yield* getDiscoverShelf(miso.config);
@@ -255,7 +295,12 @@ const program = Effect.gen(function* () {
   return { discover, release, library };
 });
 
-const { discover, release, library } = await Effect.runPromise(program.pipe(Effect.provide(layer)));
+const { discover, release, library } = await Effect.runPromise(program.pipe(Effect.provide(miso.layer)));
+
+// Or skip the standalone `read/*` functions and reach for the bound Miso
+// service/Promise face directly — `miso.client.miso.read.*` is the same
+// views, config already captured:
+const sameDiscover = await miso.client.miso.read.getDiscoverShelf();
 ```
 
 The package root also exposes the same functions under the `read` namespace:
@@ -263,10 +308,8 @@ The package root also exposes the same functions under the `read` namespace:
 ```ts
 import { read } from "@misofm/platform";
 
-const miso = read.createMisoClient({ config: verifiedReadConfig });
-const artist = await Effect.runPromise(
-  read.getArtistProfile(partyId, miso.config).pipe(Effect.provide(SuiClient.layer(miso.sui))),
-);
+const miso = read.createMisoClient({ network: "testnet" });
+const artist = await Effect.runPromise(read.getArtistProfile(partyId, miso.config).pipe(Effect.provide(miso.layer)));
 ```
 
 ### Authenticated platform mutations
@@ -343,17 +386,15 @@ back its by-value parts (the object, its admin cap, its freshly-minted share
 supplies the opinionated finish on top:
 
 ```ts
-import { miso } from "@misofm/platform";
+import { miso } from "@misofm/platform/client";
 
-const client = new SuiGrpcClient({ network: "testnet", baseUrl }).$extend(
-  miso({ deployment: verifiedDeployment }),
-);
+const client = new SuiGrpcClient({ network: "testnet", baseUrl }).$extend(miso());
 
 // Mints the composition's share supply, disperses it to shareRecipients as
 // address balances, publishes (shares) the composition, and transfers the
 // CompositionAdminCap to adminAddress — createComposition → finalizeComposition
-// in one PTB.
-const thunk = client.miso.tx.publishComposition({
+// in one PTB. A Recipe, not a Promise: apply it to a Transaction, or tx.add() it.
+const recipe = client.miso.tx.publishComposition({
   title: "Song Title",
   royaltyRateBps: 1000,
   shareType: "0x...::share::Share",
@@ -370,10 +411,6 @@ 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.
-The deprecated `misoPlatform()` constructor still accepts those values manually
-for compatibility with existing integrations. It must also receive the exact
-`network` and `chainIdentifier`; call `await client.misoPlatform.ready()` before
-accessing its client-bound protocol or platform surfaces.
 
 For custom PTBs, the bare primitives (`disperseShares`, `finalizeComposition`,
 `finalizeRecording`) and the whole-graph orchestrator are exported standalone:
@@ -383,7 +420,7 @@ import { publishReleaseGraph } from "@misofm/platform";
 
 // Every composition and recording, optional royalty pools, tracks, and
 // the release — with the release id derived ON-CHAIN — in one atomic PTB.
-const thunk = publishReleaseGraph({
+const recipe = publishReleaseGraph({
   compositions: [
     {
       shareType,
@@ -463,15 +500,9 @@ 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,
-  publishAtomicCatalog,
-} from "@misofm/platform/publication";
+import { assertAtomicPublicationBounds } from "@misofm/platform/publication";
 
 const publication = {
-  deployment,
   parties,
   compositions, // includes initialized share Currency + TreasuryCap ids
   recordings,
@@ -480,13 +511,15 @@ const publication = {
 };
 
 // Pure local assembly: fail before publishing any share package if the final
-// PTB exceeds the SDK's command/input safety limits or has an invalid graph.
-assertAtomicPublicationBounds(publication);
-
-const executed = await Effect.runPromise(
-  client.miso.executeViaExecutor(executor, publishAtomicCatalog(publication)),
-);
-const result = parseAtomicPublicationResult(publication, executed);
+// PTB exceeds the SDK's command/input safety limits or has an invalid graph
+// (deployment is added by publishCatalog itself, below).
+assertAtomicPublicationBounds({ ...publication, deployment: client.miso.deployment });
+
+// One Tx.run, submitted exactly once — no executor. `publishAtomicCatalog`
+// (the fragment) and `parseAtomicPublicationResult` (now `Executed`-shaped)
+// remain exported standalone from `@misofm/platform/publication` for a
+// caller composing this PTB with other fragments before running it.
+const result = await client.miso.publishCatalog(publication, { signer });
 ```
 
 Fresh raw PartyAdminCap, CompositionAdminCap, RecordingAdminCap, and
@@ -499,9 +532,10 @@ callers retain explicit control over those lifecycle steps. Plugin witness
 construction remains inside the SDK bindings.
 
 Share packages necessarily precede this stage: publish at most five per PTB,
-then initialize their currencies, then submit the atomic catalog PTB. The two
-share helpers below accept a parallel-compatible executor, allowing package
-batches to queue concurrently while a hardware signer serializes approvals.
+then initialize their currencies, then submit the atomic catalog PTB — see
+"Share Currency Provisioning" below. `Tx.run` holds one sender lock per
+address, so batches serialize under one signer rather than running
+concurrently through an executor (the accepted 0.28 behaviour change).
 
 ### Share Currency Provisioning (`share.ts`)
 
@@ -513,34 +547,30 @@ Publish and initialize are necessarily two transactions:
 ```ts
 import { Effect } from "effect";
 
-// Sequential (one currency, two txs):
-const currency = await Effect.runPromise(
-  client.miso.createShareCurrency(signer, {
-    name: "Song Shares",
-    description: "…",
-  }),
+// Sequential (one currency, two Tx.run's — a moveCall target needs the
+// package's id, and a package published in the same PTB has none until it
+// executes):
+const currency = await client.miso.createShareCurrency({ name: "Song Shares", description: "…" }, { signer });
+// → { packageId, currencyId, shareType, treasuryCapId, gasUsed: bigint }
+
+// Batched (many currencies). Both hold one sender lock per Tx.run — what a
+// ParallelTransactionExecutor ran concurrently now serializes per batch
+// under that lock, the accepted 0.28 behaviour change.
+const { packageIds } = await client.miso.publishShareCurrencies(10, { signer });
+const { currencies } = await client.miso.initializeShareCurrencies(
+  packageIds,
+  (pkg) => ({ name: "…", description: "…" }),
+  { signer, onBatch: (batch, gasUsed) => Effect.sync(() => console.log(`initialized ${batch.length} currencies, ${gasUsed} MIST`)) },
 );
-// → { packageId, currencyId, shareType, treasuryCapId, gasUsed }
-
-// 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 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/musicos`'s transport-agnostic `buildTx`/`toExecResult`.
+`Tx.run(recipe, { signer })` is what every submit-on-behalf member here
+builds on — journal, sender lock, epoch expiration, and reconcile apply, so a
+stuck submission is a typed `SubmissionUnknown` carrying the signed bytes, not
+a silent hang. `onBatch` (an `Effect`, run inline before the next batch)
+reports each succeeded batch as it lands, so a caller can persist progress
+before the whole call settles — if a later batch fails, the ones already
+reported through `onBatch` do not need re-initializing.
 
 ## Extensions
 
@@ -670,30 +700,67 @@ take exact object references and construct the required
 
 The bundled Testnet deployment sets `operations.status` to `"available"` with
 one canonical Vault package and registry, five distinct raw Action packages,
-and three distinct suffixed plugin packages. Zero-config Testnet clients expose
-that complete verified surface after `await client.miso.ready()`. Custom
-deployments remain fail-closed unless they provide the same atomic identity set.
-Structural validation checks canonical, pairwise-distinct IDs; callers remain
-responsible for the provenance and compatibility of arbitrary custom IDs. The
-bundled map is recursively frozen from one verified immutable admin export.
+and three distinct suffixed plugin packages. Zero-config Testnet clients
+expose that complete verified surface at `client.miso.vault` — always an
+object; each member throws `OperationsUnavailableError` when a deployment's
+`operations.status` is `"unavailable"`, instead of the namespace itself being
+`undefined`. Custom deployments remain fail-closed unless they provide the
+same atomic identity set. Structural validation checks canonical,
+pairwise-distinct IDs; callers remain responsible for the provenance and
+compatibility of arbitrary custom IDs. The bundled map is recursively frozen
+from one verified immutable admin export.
 
 ### Migrating from 0.16
 
 Version 0.17 is a breaking deployment-safety release. Replace flat Vault,
 Action, and plugin package fields with the discriminated `operations` union.
-After client
-registration, call `await client.miso.ready()` before using synchronous
-`client.miso.tx`, `ids`, `call`, `vault`, or `party` surfaces. Platform reads
-and SDK execution helpers await the same memoized readiness check themselves.
-Standalone builders remain pure for offline composition, so their caller is
-responsible for completing this exact-chain validation lifecycle before
-execution.
 
 The Release revenue plugin crank is now fixed: call
 `redeemAllAndDistribute(vault, release, accumulatorRoot)` with no amount. The
 explicit-amount `redeemAndDistribute` Action remains available only for raw
 admin-cap composition.
 
+### Migrating from 0.27
+
+0.28 replaces the hand-written `MisoPlatformClient` class and its
+`@misofm/effect` foundation with the sui-effect extension this README
+describes throughout. See sui-effect's own
+["Migrating from `@misofm/effect`"](https://github.com/unconfirmedlabs/sui-effect/blob/main/docs/extensions.md)
+table for the mechanical Sui-primitive renames (`getObjectContent` →
+`sui.getObject`, `SuiRpcError` → `TransportError`, …); this section is only
+what changed in THIS package's own surface.
+
+**Moved onto `Miso`** (`client.miso.*`, unchanged names): `getPressing`/
+`getListing`/`getRecord`/`getSale`, `ids.*`, `tx.*`, `call`/`bcs`, `vault`,
+`createShareCurrency`/`publishShareCurrencies`/`initializeShareCurrencies`,
+`protocol`, `party`. All were methods/getters on the `MisoPlatformClient`
+instance before; they are `Miso` service members now, still reachable the
+same way through `client.miso` after `$extend(miso())`.
+
+**Removed:**
+
+| Before | After |
+| --- | --- |
+| `MisoPlatformClient`, `misoPlatform(config)`, `MisoPlatformConfig` | deleted; `Miso` + `miso()` (`SuiExtension.fromService`) |
+| `PartyPlatformClient`, `new PartyosClient(client, ...)` | deleted; `client.miso.party` (`MisoPartyService`), assembled internally |
+| `await client.miso.ready()` | kept, deprecated: does no work now (`Miso.layer`'s exact-chain check runs at layer build, not first use) — see `docs/CONVERSION.md` |
+| `client.miso.validateChainIdentifier()` | deleted; `MisoChainIdentifierMismatchError` surfaces from `Miso.layer` build instead |
+| `MisoClientNotReadyError` | deleted — no more platform-specific readiness gate; sui-effect's own `ExtensionNotReady` covers a synchronous member read before `warm`/`$ready()` |
+| `client.miso.vault` returning `undefined` when unavailable | always an object; every member throws `OperationsUnavailableError` — test `deployment.operations.status`, not `if (client.miso.vault)` |
+| `TxThunk` | `Recipe` (`export type TxThunk = Recipe` kept, one minor, deprecated) |
+| `executeViaExecutor(executor, ...thunks)`, `@misofm/platform/execute` | deleted; `Tx.run(recipe, { signer })` — one submission under the sender lock, journal, epoch expiration, reconcile; no executor |
+| `createShareCurrency(signer, params)` | `client.miso.createShareCurrency(params, { signer })` — `signer` is a sui-effect `Signer` (`Signer.fromKeypair`/`Signer.fromSdkSigner`); `gasUsed` is `bigint` |
+| `publishShareCurrencies(executor, initializerAddress, count)`, `initializeShareCurrencies(executor, signerAddress, ids, metaOf)` | `client.miso.publishShareCurrencies(count, { signer })`, `client.miso.initializeShareCurrencies(ids, metaOf, { signer, onBatch? })` — batches serialize under one sender lock instead of running concurrently through an executor |
+| `parseAtomicPublicationResult(p, result: PlatformExecResult)` | `(p, executed: Executed)` — `allCreatedByType`/`createdByExactType` are now `Executed.created(type)`/`createdWhere(pred)`; `gasUsed` is `bigint`; `digest` is a branded `Digest` |
+| `getPressing`/`getListing`/`getRecord`/`getSale` failing `ObjectTypeMismatchError \| BcsDecodeError \| SuiRpcError` | `DecodeError \| ObjectUnavailable \| TransportError` (plus `RecordSalesUnavailableError` when this deployment has no Record sales) — one decode error, not-found stays `null` |
+| `getSale`/batch reads on `getObjectsContent` (silently drops errored ids) | `sui.getObjects`, a `Result` per id — each read decides per item: `getSale` fails the whole read on a genuine `ObjectUnavailable`; a soft read like `resolveGenreNames` skips it |
+| `getBalance` returning decimal strings | `Balance` with `bigint`; `read/*` JSON-safe views still return strings — only the low tier changed |
+| `SuiGraphQL` from `@misofm/effect` | `SuiGraphQL` from `@unconfirmed/sui-effect` (`GraphQLUnavailableError` → `GraphQLUnavailable`; `SuiRpcError { operation }` → `TransportError { method }`) |
+| a `chainIdentifier`-less registration on `devnet`/`localnet`/a custom network | `miso({ chainId })` required, or registration throws synchronously (warm) naming the network |
+
+`@misofm/effect` is gone from `dependencies`; `@mysten/sui`, `effect`, and
+`@unconfirmed/sui-effect` are peers instead.
+
 ### Extension types
 
 ```ts
@@ -718,37 +785,36 @@ carry an optional `RecordingRoleLevel` (`Producer`, `Vocalist`, `Engineer`,
 
 ## Errors
 
-Every typed failure is a `Schema.TaggedError` (`@misofm/platform/errors`),
+Every typed failure is a `Schema.TaggedError` and declares `outcome: "applied"
+| "not_applied" | "unknown"` (`SuiError.outcome`/`Script.exitCode` read it),
 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:
+sniffing. sui-effect's own taxonomy (`DecodeError`, `TransportError`,
+`ObjectNotFound`/`ObjectDeleted`/`ObjectUnavailable`, `GraphQLUnavailable`,
+`ExecutionFailed`, and the `Tx.run` union: `BuildError`, `SimulationFailed`,
+`PolicyDenied`, `SigningError`, `NotApplied`, `SubmissionUnknown`,
+`JournalError`, `UnexpectedEffects`) is re-exported from `@unconfirmed/sui-effect` so this
+is the only import a consumer needs:
 
 ```ts
 import {
-  ObjectNotFoundError,
+  ObjectNotFound,
   ReleaseNotFoundError,
   RecordSalesUnavailableError,
   OperationsUnavailableError,
   MisoChainIdentifierMismatchError,
-  MisoClientNotReadyError,
   MisoNetworkMismatchError,
 } from "@misofm/platform/errors";
 ```
 
-Platform-specific tags:
+Platform-specific tags, all `outcome: "not_applied"` (nothing was submitted):
 
 | 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()` |
+| `RecordSalesUnavailableError` | `reason` | `requireRecordSalesDeployment`, `getPressing`/`getListing`/`getRecord`/`getSale`, `ids.*`/`tx.*` sales members on a legacy or unconfigured deployment |
+| `OperationsUnavailableError` | `reason` | `requireOperationsDeployment`, every `client.miso.vault` member, `ids.vault`/`ids.vaultAdminCap` |
+| `MisoPlatformDeploymentInvalidError` | `message` | `assertMisoPlatformDeployment` / `normalizeMisoPlatformDeployment` / `Miso.layerConfig` on an unbundled `MISO_NETWORK` |
+| `MisoNetworkMismatchError` | `clientNetwork`, `deploymentNetwork` | `Miso.layer` build — synchronously at `$extend(miso())` under a `warm` registration (mainnet/testnet), or rejecting the first call for a lazy one |
+| `MisoChainIdentifierMismatchError` | `actual`, `expected` | `Miso.layer` build, same timing as `MisoNetworkMismatchError` above — the exact-ledger check the predecessor's `ready()` used to perform at first use |
 | `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 |
@@ -759,12 +825,12 @@ Platform-specific tags:
 ```ts
 import { Effect } from "effect";
 
-const release = client.miso.protocol!
+const release = miso.protocol
   .getReleaseById(releaseId)
   .pipe(
     Effect.catchTags({
-      ObjectNotFoundError: () => Effect.succeed(null),
-      SuiRpcError: (e) => Effect.die(e), // transport failure: not recoverable here
+      ObjectNotFound: () => Effect.succeed(null),
+      TransportError: (e) => Effect.die(e), // transport failure: not recoverable here
     }),
   );
 ```
@@ -773,28 +839,28 @@ const release = client.miso.protocol!
 
 ```
 src/
+  Miso.ts                the Miso service: MisoService assembly (reads, ids/tx/call/bcs/vault, read.*, events), layer/layerConfig/layerTest
+  client.ts              miso(): the SuiExtension.fromService registration (client.miso.*); MisoClient/MisoOptions
   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
+  events.ts              platformEventParsers: work/Party extensions, Actions, products, plugins, and 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
+  pressing.ts            standalone: builders, readers, and the id derivations (Sui-based reads; Miso.tx/getPressing etc. bind these)
   queries.ts             shared read plumbing (isNotFound, re-exported from @misofm/musicos)
-  transactions.ts        the TxThunk contract + the opinionated publish flow (disperse/finalize/publish*)
+  transactions.ts        the Recipe (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)
+  publication.ts         atomic catalog publication (publishAtomicCatalog, parseAtomicPublicationResult); Miso.publishCatalog wraps it in Tx.run
+  share.ts               share-currency provisioning on Tx.run (createShareCurrency, batched variants); Miso.createShareCurrency etc. bind these to Sui
   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/musicos's buildTx/toExecResult
-  internal.ts            private helpers (the 0x1::option moveCall targets) — NOT exported
+  party/                 Party EXTENSIONS: profile, media, roles, tags, genres, CTAs, links (party/client.ts's makeMisoParty assembles MisoPartyService over the converted Partyos) — also `@misofm/platform/party`
+  read/                  high-level catalog, artist, wallet, and receipt views (config.ts, client.ts's createMisoClient); Miso.read.* binds these to one deployment
+  vault.ts               Vault authority, plugin, event, and receiving-coin builders; Miso.vault gates these with OperationsUnavailableError
+  internal.ts            private helpers (the 0x1::option moveCall targets, immutableSnapshot) — NOT exported
   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/*`
 ```
@@ -811,7 +877,7 @@ bun run codegen   # reads sui-codegen.config.ts → src/contracts/
 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`)
+Shop, Vault, generic `share`, `miso_pay`, and `platform_link` primitives, 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
@@ -834,15 +900,13 @@ only from that copy, avoiding writes to a developer's live source tree.
 
 `@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.
+version ranges on publish), not peers. `Miso.layer` composes their own
+`Musicos.layer`/`Partyos.layer` internally (`Layer.provide`d inside `Miso`'s
+own layer), so `client.miso.protocol` (the converted `Musicos` service) and
+`client.miso.party` (`MisoPartyService`, `Partyos` core plus this package's
+own party extensions) are always present — no readiness gate, no `!`
+non-null assertion needed on either. `Miso`'s own requirement channel stays
+`Sui | SuiGraphQL`, never `Sui | SuiGraphQL | Musicos | Partyos`.
 
 `@mysten/sui` itself stays a peer dependency here, so an application resolves
 exactly one Sui SDK across all three packages regardless of which
@@ -854,3 +918,44 @@ bun add @misofm/platform
 
 `@misofm/musicos` resolves automatically as a transitive dependency; there is
 no separate install step and no peer version for consumers to reconcile.
+
+## Testing
+
+Tests run on `@unconfirmed/sui-effect/testing`'s in-memory fake — no network, no real
+signer. `layerTest(script)` (from `@unconfirmed/sui-effect/testing`) provides `Sui`/
+`SuiCore`/`SuiCoreFake` for `Effect`-level tests against `Miso.layer`/
+`layerTest`; a `$extend`-level test builds `SuiCoreFake.layer(script)` and
+calls `fake.client.$extend(miso({ deployment }))` directly, exactly the way a
+consumer writes it:
+
+```ts
+import { Effect } from "effect";
+import { SuiCoreFake } from "@unconfirmed/sui-effect/testing";
+import { miso } from "@misofm/platform/client";
+
+const fake = await Effect.runPromise(
+  Effect.provide(SuiCoreFake, SuiCoreFake.layer({ network: "testnet", chainId, objects: [...] })),
+);
+const client = fake.client.$extend(miso({ deployment: testDeployment }));
+
+const pressing = await client.miso.getPressing(pressingId);
+await client.miso.dispose();
+```
+
+`FakeOutcome.succeed(...)`/`FakeOutcome.failWith(...)`/`FakeOutcome.transportError(...)`
+script `Tx.run`'s `execute`; `TestClock` (from `effect/testing`) plus
+`Journal.layerMemory` (from `@unconfirmed/sui-effect/tx`) drive a submission through a
+resubmit/reconcile schedule without waiting on real time (see
+`tests/share.test.ts`'s `initializeShareCurrencies` retry case). `Miso.layer`/
+`layerTest` need `SuiGraphQL` too now that `read.*` joins the service — compose
+`SuiGraphQL.layerUnavailable` (a test that never reaches a GraphQL-backed
+member) or `SuiGraphQL.layer(stubbedClient)` alongside `layerTest`/
+`SuiCoreFake.layer` the same way `@misofm/musicos`'s own GraphQL tests do.
+
+`tests/deployments.test.ts` covers the pure `deployments.ts` validators
+(`requireRecordSalesDeployment`/`requireOperationsDeployment`, the frozen
+bundled manifest); `tests/client.test.ts` is only the derived facade
+(registration, nested namespaces, a fragment composed with a sibling
+fragment, a submit-on-behalf member, rejection identity, the
+network-mismatch path); `tests/Miso.test.ts` is the service at the `Effect`
+level (the exact-chain check, `layerConfig`, `layerTest`).