Effect v4 across the SDKs: @misofm/effect foundation, typed errors, Effect in public signatures

.github/workflows/publish.yml

@@ -1,13 +1,13 @@
 name: Publish to npm
 
-# Publishes on a per-package version tag (musicos-v0.1.0, partyos-v0.1.0, platform-v0.25.0,
-# streaming-v0.1.0, transcoding-v0.3.0, …), so a release is a deliberate act rather
-# than a side effect of merging, and releasing one workspace package never
+# Publishes on a per-package version tag (effect-v0.1.0, musicos-v0.1.0, partyos-v0.1.0,
+# platform-v0.25.0, streaming-v0.1.0, transcoding-v0.3.0, …), so a release is a deliberate act
+# rather than a side effect of merging, and releasing one workspace package never
 # implies another. Failed tag jobs
 # can be re-run from Actions without permitting a branch to publish a package.
 on:
   push:
-    tags: ["musicos-v*", "partyos-v*", "platform-v*", "streaming-v*", "transcoding-v*"]
+    tags: ["effect-v*", "musicos-v*", "partyos-v*", "platform-v*", "streaming-v*", "transcoding-v*"]
 
 concurrency:
   group: publish-${{ github.ref }}
@@ -53,6 +53,10 @@ jobs:
         run: |
           TAG="${GITHUB_REF_NAME}"
           case "$TAG" in
+            effect-v*)
+              DIR="packages/effect"
+              VERSION="${TAG#effect-v}"
+              ;;
             musicos-v*)
               DIR="packages/musicos"
               VERSION="${TAG#musicos-v}"
@@ -74,7 +78,7 @@ jobs:
               VERSION="${TAG#transcoding-v}"
               ;;
             *)
-              echo "::error::Tag '$TAG' does not match musicos-v*, partyos-v*, platform-v*, streaming-v*, or transcoding-v*"
+              echo "::error::Tag '$TAG' does not match effect-v*, musicos-v*, partyos-v*, platform-v*, streaming-v*, or transcoding-v*"
               exit 1
               ;;
           esac

CLAUDE.md

@@ -34,6 +34,9 @@ This is a Bun workspace of publishable packages under `packages/*`:
   group membership).
 - `packages/platform` — `@misofm/platform`, everything Miso builds on top of the object
   models (work and Party extensions, royalty primitives, Vault, Actions, product workflows).
+- `packages/effect` — `@misofm/effect`, the shared Effect v4 foundation (one `SuiClient`
+  service, the tagged error vocabulary, read/execute primitives). Every other package
+  depends on it.
 - `packages/streaming`, `packages/transcoding` — the streaming transcode contract and
   transcoder.
 
@@ -63,9 +66,21 @@ intrinsic to a Party (identity, admin cap, membership), it belongs in `partyos`;
 opinion Miso's product adds on top — including every `party_*` extension — it belongs in
 `platform`.
 
+## Effect conventions
+
+- Effect v4 release candidate, pinned exactly (see any package's `peerDependencies`). Read
+  `node_modules/effect/AGENTS.md` and `ai-docs/` before writing Effect code; v4 is not v3.
+- I/O returns `Effect` with `SuiClient` (from `@misofm/effect`) in the requirements; client
+  extension classes provide the layer internally. PTB builders stay synchronous.
+- Failures are `Schema.TaggedError` classes in each package's `src/errors.ts` (`./errors`
+  subpath); never throw strings or plain `Error` from public reads.
+- Domain types are `Schema.Class`; generated BCS shapes under `src/contracts/` never appear
+  in a public signature.
+
 ## Project Rules
 
 - Use `@mysten/sui` v2 APIs and gRPC/Core client patterns; do not add JSON-RPC.
 - Do not hand-edit generated files under any `packages/*/src/contracts/`.
 - Keep PTB helpers composable: accept a `Transaction`, return results when useful, and do not execute.
-- Run `bun run typecheck`, `bun test`, `bun run build`, and `bun run codegen:check` before handoff.
+- Run `bun run typecheck`, `bun test`, `bun run build`, `bun run codegen:check`, and
+  `bun run test:consumer` before handoff.

README.md

@@ -4,6 +4,7 @@ Monorepo for the Miso platform-layer TypeScript SDKs.
 
 | Package                                          | Description                                                                                                                          |
 | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| [`packages/effect`](packages/effect/README.md) | `@misofm/effect` — the shared Effect v4 foundation: the `SuiClient` service, the tagged error vocabulary, and the object-read and execute primitives every other SDK is built on. |
 | [`packages/musicos`](packages/musicos/README.md) | `@misofm/musicos` — typed bindings, queries, event decoders, and PTB builders for the works object model (Composition, Recording, Release, Track). |
 | [`packages/partyos`](packages/partyos/README.md) | `@misofm/partyos` — typed bindings, queries, and PTB builders for the Party object model (Party, admin cap, group membership). |
 | [`packages/platform`](packages/platform/README.md) | `@misofm/platform` — the complete client SDK for the Miso platform layer: work and Party extensions, catalog/artist/wallet reads, record production and sale, and Vault custody/Actions/plugins. |
@@ -33,6 +34,16 @@ everything else. `sui-codegen.config.ts`
 is the source of truth for exactly which Move package lands in which tree —
 see its `packages` list rather than looking for an enumeration here.
 
+## Effect
+
+Every SDK exposes [Effect](https://effect.website) v4 in its public API: reads and
+submissions return `Effect` values that require the `SuiClient` service from
+`@misofm/effect` and fail with tagged errors (`Effect.catchTag`); the client
+extensions (`miso()`, `partyos()`, `misoPlatform()`) provide that service
+themselves so their methods have no requirements; PTB builders stay synchronous.
+Each package's `./errors` subpath lists its failures. Pin `effect` to the exact
+release candidate the packages peer on.
+
 ## Development
 
 This is a Bun workspace.

package.json

@@ -8,7 +8,7 @@
   "scripts": {
     "typecheck": "bun run --filter '*' typecheck",
     "test": "bun run --filter '*' test",
-    "build": "bun run --filter @misofm/streaming build && bun run --filter @misofm/musicos build && bun run --filter @misofm/partyos build && bun run --filter @misofm/platform build && bun run --filter @misofm/transcoding build",
+    "build": "bun run --filter @misofm/streaming build && bun run --filter @misofm/effect build && bun run --filter @misofm/musicos build && bun run --filter @misofm/partyos build && bun run --filter @misofm/platform build && bun run --filter @misofm/transcoding build",
     "codegen": "bun scripts/codegen.ts",
     "codegen:check": "bun run codegen && git diff --exit-code -- packages/musicos/src/contracts packages/partyos/src/contracts packages/platform/src/contracts",
     "test:consumer": "bun scripts/check-consumer.ts"