@misofm/sdk 0.15.11 → 0.17.0

package/README.md

@@ -2,7 +2,7 @@
 
 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 vault-custodied business-logic plugins built on `@misonetwork/sdk`'s
+and fail-closed Vault custody, raw Actions, and safe crank plugins built on `@misonetwork/sdk`'s
 protocol and data-extension primitives.
 
 ## The split
@@ -10,18 +10,20 @@ protocol and data-extension primitives.
 Miso ships two SDK families, and the npm scope tells you which promise you are
 holding:
 
-| Scope | Layer | Owns |
-| --- | --- | --- |
+| Scope            | Layer        | Owns                                                                                                                                   |
+| ---------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
 | `@misonetwork/*` | **Protocol** | Composition, Recording, Release, Party identity; metadata/data extensions; utilities; generic royalty-pool and routed-stake primitives |
-| `@misofm/*` | **Platform** | Pressing, Listing, Record, and Vault plugins that apply Miso business logic to custodied protocol admin caps |
+| `@misofm/*`      | **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
+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).
 
-Extensions add data to a work. Plugins provide business logic: a shared
+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,
+permissionless crank plugins borrow through their own witness: a shared
 `Vault<AdminCap>` custodies the raw cap, while its owner holds a
 `VaultAdminCap<AdminCap>`. A plugin borrows the cap and must return the exact
 object in the same PTB. The SDK supports both vault authorities and legacy
@@ -40,30 +42,48 @@ Install both SDKs at the application boundary; the platform package intentionall
 does not carry its own protocol SDK copy:
 
 ```sh
-bun add @misofm/sdk@^0.15.0 @misonetwork/sdk@^0.10.0
+bun add @misofm/sdk@^0.17.0 @misonetwork/sdk@^0.11.0
 ```
 
 Both SDKs are consumed from npm. The platform package keeps
 `@misonetwork/sdk` as a peer so applications resolve exactly one protocol SDK
-and one compatible deployment map.
+and one compatible deployment map. 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.
+
+### Canonical Record-gated sessions
+
+`@misofm/sdk/mix` defines the complete protected-playback wire contract. A
+Record resolves its immutable Release track to a Recording, then derives that
+Recording's `recording_engine_session::ExtensionKey` dynamic field directly.
+The field names one plaintext Walrus `miso.engine-session/1` document containing
+the encrypted stem blob IDs and one Seal-wrapped 32-byte session key. No event
+scan, indexer-maintained relationship, or second encrypted manifest is needed.
+
+The same entry point exposes exact identity encoding, strict canonical-session
+parsing, Seal-envelope inspection, and explicit attach/replace/unset PTB
+builders. The bundled Testnet deployment pins the Record, policy, gate, and
+engine-session identities together at `recordSales.recordPackageId`,
+`packages.recordSealPolicy`, `objects.recordGate`, and
+`packages.recordingEngineSession`.
 
 ## The model
 
-A release has exactly **one** `Pressing`: a single uncapped run whose counter numbers
-every copy that release will ever sell. There are no editions, no supply caps, no
-sold-out state, and no expiry — a run is `Scheduled → Active → Paused → Active` and
-nothing else.
+A release may have one `Pressing` per positive `u16` edition. Each Pressing owns its
+independent `u32` Record-number sequence, current supply, optional immutable `u32`
+maximum supply, and authorized distributor witness types.
 
 Selling in a currency is a `Listing<Currency>`, one per currency, permanent, edited in
-place rather than replaced. A sale needs both switches open: the run active and that
-currency's listing enabled.
+place rather than replaced. The Listing's enabled/disabled state is the sale switch;
+the Pressing has no schedule state.
 
 **Everything is address math.** The pressing's UID derives off its release's, each
 listing's off the pressing's. The protocol's canonical `ReleaseRegistry` creates the
-release; there is no *pressing* registry or mutable lookup pointer to follow, so
-"where is it" is answered offline — which is why the builders take a RELEASE id and
-compute the rest. A caller cannot pair a listing with the wrong pressing, because it
-never picks one.
+release; there is no _pressing_ registry or mutable lookup pointer to follow, so
+"where is it" is answered offline. A Pressing derives from `(release, edition)`, a
+Record from `(pressing, number)`, and a `Listing<Currency>` from its Pressing under
+the separate immutable Record Shop package. There are no Record Registry or Settings
+singletons.
 
 ## Usage
 
@@ -79,6 +99,10 @@ 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);
@@ -86,29 +110,36 @@ const party = await client.miso.party.getPartyById(partyId);
 // 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,
 });
 
 // Write: a thunk, so it composes with protocol calls in the same PTB.
 const tx = new Transaction();
 tx.add(
-  client.miso.tx.buyRecord({
+  client.miso.tx.purchaseRecord({
     releaseId,
+    edition,
     currencyType: USD_COIN_TYPE,
-    amount: listing.price.amount,
+    paymentAmount: listing.pricing.amount,
+    expectedPricing: listing.pricing,
     recipient: buyer,
   }),
 );
 ```
 
-Holding the ids yourself? Every builder and reader is exported bare, taking
-`misoPressingPackageId` per call:
+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.
+
+Holding the ids yourself? The bare APIs take `recordPackageId` and/or
+`recordShopPackageId` explicitly:
 
 ```ts
-import { buyRecord, getSale } from "@misofm/sdk/pressing";
+import { purchaseRecord, getSale } from "@misofm/sdk/pressing";
 ```
 
-Testnet package and singleton IDs are bundled in
+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 })`.
@@ -177,7 +208,7 @@ address, and the exact authorized route on every protected request.
 
 ### Payment
 
-`listing::buy` takes a bare `Balance<Currency>`, and `buyRecord` sources it with
+`listing::purchase` takes a bare `Balance<Currency>`, and `purchaseRecord` sources it with
 `tx.balance()` — which draws from the buyer's **address balance** first and falls back
 to coin objects only if it must. When the address balance covers the price, that is a
 single `balance::redeem_funds` and **no coin object is minted, touched, or destroyed**,
@@ -187,17 +218,25 @@ Never hand-pick coin objects for a payment. That road shows a buyer their $1,000
 then refuses to spend a cent of it, because a coin listing cannot see money that lives
 in the address balance.
 
-Purchases through Miso are sponsored, so `useGasCoin` defaults to `false`: the gas coin
-belongs to the sponsor, and drawing a SUI payment out of it would spend the wrong
-wallet's money.
+Purchases always set `useGasCoin: false`: the gas coin may belong to a sponsor. Buyers
+also pass the exact expected `Fixed` or `Floor` pricing variant and value, protecting
+them from stale pricing-mode changes as well as amount changes.
 
-### Vault fund sweeping
+### Vault fund settlement
 
-`sweepCompositionRoyaltyPool` and `sweepRecordingRoyaltyPool` take the shared
-`AccumulatorRoot` and let Move determine the commit-settled amount; callers no
-longer provide a `u64`. Party-wallet monetary builders are similarly composable:
+`settleAndDistributeReleaseRevenue` invokes the fixed release plugin with the
+framework `AccumulatorRoot` (`0xacc`); the plugin redeems the whole settled
+snapshot and exposes no amount argument. `settleCompositionRoyaltyPool` and
+`settleRecordingRoyaltyPool` read `balance::settled_funds_value` and pass that
+command result directly to their exact-value plugin calls. The lower-level raw
+Action `redeemAndDistributeReleaseRevenue` and the plugin helpers
+`redeemAndDepositCompositionRoyaltyPool`, and
+`redeemAndDepositRecordingRoyaltyPool` remain available when an earlier PTB
+command already produced the exact value.
+
+Party-wallet monetary builders are similarly composable:
 `receivePartyWalletBalance`, `redeemPartyWalletBalance`, and
-`sweepPartyWalletBalance` return the PTB `Balance<Currency>` result. Pass that
+`settlePartyWalletBalance` return the PTB `Balance<Currency>` result. Pass that
 result directly to another Move call, or convert it with `coin::from_balance`
 only when an owned Coin is required. Every returned Balance must be consumed in
 the same PTB.
@@ -234,10 +273,13 @@ 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 `@misonetwork/sdk`'s README for why the ordering is load-bearing).
-The protocol, pressing, record-settings, minato, and release-coordinator
-addresses all come from the deployment selected by the Sui client's network.
+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.
+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:
@@ -248,8 +290,28 @@ import { publishReleaseGraph } from "@misofm/sdk";
 // 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({
-  compositions: [{ shareType, shareCurrencyId, shareTreasuryCapId, title: "Song", royaltyRateBps: 1000, shareRecipients, adminAddress }],
-  recordings: [{ shareType, shareCurrencyId, shareTreasuryCapId, compositionShareType, parentCompositionIndex: 0, shareRecipients, adminAddress }],
+  compositions: [
+    {
+      shareType,
+      shareCurrencyId,
+      shareTreasuryCapId,
+      title: "Song",
+      royaltyRateBps: 1000,
+      shareRecipients,
+      adminAddress,
+    },
+  ],
+  recordings: [
+    {
+      shareType,
+      shareCurrencyId,
+      shareTreasuryCapId,
+      compositionShareType,
+      parentCompositionIndex: 0,
+      shareRecipients,
+      adminAddress,
+    },
+  ],
   release: {
     title: "Album",
     nonce: "42",
@@ -266,9 +328,11 @@ const thunk = publishReleaseGraph({
 
 `publishAtomicCatalog` owns the semantic publication transaction. Given
 pre-initialized share currencies, it creates every new Party, Composition,
-Recording, Track, and Release; applies all declared data extensions; installs
-and initializes Vault plugins; opens the Pressing and Listings; shares the new
-objects; and delivers only the selected direct admin cap or VaultAdminCap. The
+Recording, Track, and Release; applies all declared data extensions; composes
+raw-cap Actions through direct custody or a scoped Vault borrow; installs only
+the permissionless royalty/revenue crank plugins; opens the Pressing and
+Listings; shares the new objects; and delivers only the selected direct admin
+cap or VaultAdminCap. The
 entire catalog stage is one PTB, so none of it can land partially.
 
 Share allocation is explicit at the SDK boundary. Omitting
@@ -301,7 +365,7 @@ const publication = {
 // PTB exceeds the SDK's command/input safety limits or has an invalid graph.
 assertAtomicPublicationBounds(publication);
 
-const executed = await executeViaExecutor(
+const executed = await client.miso.executeViaExecutor(
   executor,
   publishAtomicCatalog(publication),
 );
@@ -310,9 +374,11 @@ const result = parseAtomicPublicationResult(publication, executed);
 
 Fresh raw PartyAdminCap, CompositionAdminCap, RecordingAdminCap, and
 ReleaseAdminCap values never leave the PTB when Vault custody is selected.
-Party Vaults install the Party Wallet plugin by default; royalty-pool,
-routed-stake, and release-revenue plugins are installed while each new Vault is
-still owned. Plugin witness construction remains inside the SDK bindings.
+Only the Composition royalty-pool, Recording royalty-pool, and Release revenue
+plugins are installable, while each new Vault is still owned. Party-wallet and
+Composition routed-stake operations remain raw Actions because they return
+caller-controlled assets. 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
@@ -336,10 +402,20 @@ const currency = await client.miso.createShareCurrency(signer, {
 
 // Batched (many currencies, via a ParallelTransactionExecutor):
 import { publishShareCurrencies, initializeShareCurrencies } from "@misofm/sdk";
-const { packageIds } = await publishShareCurrencies(executor, initializerAddress, 10);
-const { currencies } = await initializeShareCurrencies(executor, signerAddress, packageIds, (pkg) => ({
-  name: "…", description: "…",
-}));
+const { packageIds } = await publishShareCurrencies(
+  executor,
+  initializerAddress,
+  10,
+);
+const { currencies } = await initializeShareCurrencies(
+  executor,
+  signerAddress,
+  packageIds,
+  (pkg) => ({
+    name: "…",
+    description: "…",
+  }),
+);
 ```
 
 `executeViaExecutor(executor, ...thunks)` (`execute.ts`) submits a
@@ -369,9 +445,14 @@ duplicate roles.
 
 ```ts
 import {
-  attachCompositionCredit, attachRecordingCredit, addReleaseCredit,
-  addRecordingPrimaryArtist, addRecordingFeaturedArtist,
-  getCompositionCredits, getRecordingCredits, getReleaseCredits,
+  attachCompositionCredit,
+  attachRecordingCredit,
+  addReleaseCredit,
+  addRecordingPrimaryArtist,
+  addRecordingFeaturedArtist,
+  getCompositionCredits,
+  getRecordingCredits,
+  getReleaseCredits,
 } from "@misofm/sdk";
 
 const thunk = attachRecordingCredit({
@@ -379,7 +460,10 @@ const thunk = attachRecordingCredit({
   recordingAdminCapId: "0x...",
   partyId: "0x...",
   displayName: "Jane Doe",
-  roles: [{ type: "Vocalist", level: "Lead" }, { type: "Instrumentalist", instrument: "Guitar" }],
+  roles: [
+    { type: "Vocalist", level: "Lead" },
+    { type: "Instrumentalist", instrument: "Guitar" },
+  ],
   recordingShareType: "0x...::share::Share",
   compositionShareType: "0x...::share::Share",
   recordingCreditsPackageId: "0x...",
@@ -387,12 +471,27 @@ const thunk = attachRecordingCredit({
 });
 
 // Designate an already-credited party (same params minus displayName/roles/misoCreditPackageId):
-addRecordingPrimaryArtist({ recordingId, recordingAdminCapId, partyId, recordingShareType, compositionShareType, recordingCreditsPackageId });
+addRecordingPrimaryArtist({
+  recordingId,
+  recordingAdminCapId,
+  partyId,
+  recordingShareType,
+  compositionShareType,
+  recordingCreditsPackageId,
+});
 
 // Reads return null when no credits field is attached.
-const credits = await getCompositionCredits(client, compositionId, compositionCreditsPackageId);
+const credits = await getCompositionCredits(
+  client,
+  compositionId,
+  compositionCreditsPackageId,
+);
 // CreditView[]: { partyId, displayName, roles: string[] } — e.g. "Producer (Lead)", "Instrumentalist: Guitar"
-const rc = await getRecordingCredits(client, recordingId, recordingCreditsPackageId);
+const rc = await getRecordingCredits(
+  client,
+  recordingId,
+  recordingCreditsPackageId,
+);
 // { credits: CreditView[], primaryArtistIds: string[], featuredArtistIds: string[] }
 ```
 
@@ -416,19 +515,23 @@ import { setReleaseCover, getReleaseCover } from "@misofm/sdk";
 const thunk = setReleaseCover({
   releaseId: "0x...",
   releaseAdminCapId: "0x...",
-  stillBlobId: "987654321",   // Walrus blob id as u256 (decimal string or bigint)
-  animatedBlobId: null,        // optional animated cover
+  stillBlobId: "987654321", // Walrus blob id as u256 (decimal string or bigint)
+  animatedBlobId: null, // optional animated cover
   coverArtPackageId: "0x...",
   releaseCoverArtPackageId: "0x...",
   oriPackageId: "0x...",
 });
 
-const cover = await getReleaseCover(client, releaseId, releaseCoverArtPackageId);
+const cover = await getReleaseCover(
+  client,
+  releaseId,
+  releaseCoverArtPackageId,
+);
 // ReleaseCoverView | null: { still, animated } as normalized Walrus refs
 // ({ kind: "blob", blobId } | { kind: "quiltPatch", quiltId, version, startIndex, endIndex })
 ```
 
-### Vault plugins (`vault.ts`)
+### Vault operations (`vault.ts`)
 
 `vault.ts` contains composable PTB builders for custody and plugin flows:
 `invokeWithAdminCap` safely sequences `borrow_as_admin → Move call → put_back`, and
@@ -441,18 +544,50 @@ installers construct their witnesses inside their Move package; callers supply n
 witness.
 
 It also builds Composition/Recording royalty-pool initialization and cranks,
-Release `redeem_and_distribute` / `receive_and_distribute`, and the full
-Composition routed-stake lifecycle. Receive flows take coin IDs and construct
-the required `vector<Receiving<Coin<Currency>>>` in the PTB.
+fixed Release settlement plus raw-admin amount composition, Party wallet
+Actions, and the full Composition routed-stake Action lifecycle. Receive flows
+take exact object references and construct the required
+`vector<Receiving<Coin<Currency>>>` in the PTB.
+
+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.
+
+### 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.
 
 ### Extension types
 
 ```ts
 import type {
-  CreditView, RecordingCreditsView,
-  CompositionRole, RecordingRole, RecordingRoleLevel, RecordingLeveledRoleType,
+  CreditView,
+  RecordingCreditsView,
+  CompositionRole,
+  RecordingRole,
+  RecordingRoleLevel,
+  RecordingLeveledRoleType,
   ReleaseRole,
-  ReleaseCoverView, CoverImageRef,
+  ReleaseCoverView,
+  CoverImageRef,
 } from "@misofm/sdk";
 ```
 
@@ -493,7 +628,7 @@ the on-chain ABI:
 bun run codegen   # reads sui-codegen.config.ts → src/contracts/
 ```
 
-`sui-codegen.config.ts` lists the platform package (`miso_pressing`), data
+`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
@@ -502,9 +637,9 @@ adding the core here to save an import is how the split this package exists to
 enforce gets undone.
 
 Paths resolve against sibling checkouts, so regenerating requires
-`~/Documents/GitHub/misofm/{sdk, pressing, vault, vault-plugins}` and
-`~/Documents/GitHub/misonetwork/{protocol, protocol-extensions,
-royalty-pool, routed-stake, share}`.
+`~/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}`.
 
 For an isolated checkout, copy those source trees and set
 `MISO_SDK_CODEGEN_SOURCE_ROOT` to their common parent. The codegen config reads
@@ -512,17 +647,19 @@ only from that copy, avoiding writes to a developer's live source tree.
 
 ## Dependency on `@misonetwork/sdk`
 
-`@misonetwork/sdk` is a required peer (`^0.10.0`), not a runtime dependency.
+`@misonetwork/sdk` is a required peer (`^0.11.0`), not a runtime dependency.
 This package imports its primitives, deployment configuration, protocol client,
 and Party client directly, then exposes them at `client.miso.protocol` and
-`client.miso.party`. The consuming
+`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. The consuming
 application installs one protocol SDK, preventing a platform tarball from
 silently nesting an older protocol ABI alongside the application's copy.
 `@mysten/sui` itself stays a peer dependency here, same as in
 `@misonetwork/sdk`.
 
 The published tarball intentionally contains no protocol SDK copy: consumers
-satisfy the peer with their verified `@misonetwork/sdk@^0.10.0` installation.
+satisfy the peer with their verified `@misonetwork/sdk@^0.11.0` installation.
 
 ```bash
 bun install