# @effected/workspaces Monorepo workspace tooling as Effect services: workspace root discovery, package enumeration, the dependency graph, package-manager detection, pnpm catalog resolution, lockfile IO, peer and duplicate checks, and git-based snapshots and change detection. **Boundary tier**: every runtime dependency is an `@effected/*` package, and IO runs through core contracts in `R`. Durable knowledge about this package lives in the OKF bundle, not here. Start at `okf/modules/workspaces.md`, then load the concept a task needs: - Module (tier and dependency posture, the two inverted contracts `CatalogResolver`/`WorkspaceResolver` and `LocalExec`, module layout, composites, the `WorkspacesSync` escape hatch, lazy init, hardening, testing, build) → `okf/modules/workspaces.md` — Load when: changing the error model, a composite layer, a dependency edge, or any service contract. - Discovery (root finding and its `stopAt`/`maxDepth` bounds, the `packages:` enumerator, the shared traversal, `WorkspacePackage`, per-root `listPackagesIn`/`infoIn`, `PackageManagerDetector`, the doubles) → `okf/interfaces/workspaces-discovery.md` — Load when: touching enumeration, traversal, the root ascent, `WorkspacePackage` or the detector. - Dependency graph (`DependencyGraph`, cycle payload, `levels`, Mermaid, where core's `Graph` is and is not used) → `okf/interfaces/workspaces-graph.md` — Load when: touching `DependencyGraph`, cycle detection, `levels` or the rendering. - Catalogs and hook replay (PM-aware assembly, the release-age gate, `ConfigDependencySpec`, `ConfigDependencyHooks`, the declared-version ladder, `layerSubprocess`, `peerDependencyRules` seeding) → `okf/interfaces/workspaces-catalogs.md` — Load when: touching catalog assembly, `ConfigDependencySpec` or its shared splitter, `ConfigDependencyHooks` or `peerDependencyRules`. - Where the pnpm-only pieces went (`PnpmSettings`, `ReleaseAgeGate`, `PnpmMatcher`, `PeerDependencyRules` live in `@effected/pnpm`; the `catalog:`/`workspace:` contracts stay in `@effected/npm`, `CatalogSet` here) → `okf/modules/pnpm.md`, `okf/decisions/catalog-and-workspace-protocol-owner.md` — Load when: adding a pnpm-specific concept, or touching `internal/catalogs.ts`. - Peer checking (`PeerCheck`, the surfaced limits, the four `unverified` reasons, the three suppression axes, the committed oracle) → `okf/interfaces/workspaces-peer-check.md`, `okf/limitations/workspaces-peer-check-yarn-and-suppression-axes.md` (deprecated: yarn is unsupported) — Load when: touching `PeerCheck`, the `unverified` reasons, the suppression axes or the peer fixtures. Every clause there is a defect someone already paid for; read it **before** touching any of it. - Duplicate checking (`DuplicateCheck`, the two-version rule, the shared `internal/roots.ts` join) → `okf/interfaces/workspaces-duplicate-check.md` — Load when: touching `DuplicateCheck` or `internal/roots.ts`. - Snapshots and change detection (`WorkspaceSnapshots.at(ref)`/`worktree()`, hook replay at a ref, `WorkspaceStateSnapshot`, seeded catalogs, importer versions, `ChangeDetector`) → `okf/interfaces/workspaces-snapshots.md`, `okf/limitations/workspaces-snapshot-hook-catalog-bump-between-refs.md` — Load when: touching at-ref reads, `WorkspaceStateSnapshot` or `ChangeDetector`. - Release surface (`PublishabilityDetector`, `VersioningStrategy`, `ReleaseTag`, `TrackingTag`, `classifyTag`) → `okf/interfaces/workspaces-release.md`, `okf/gotchas/publishability-detector-diagnoses-late.md`, `okf/gotchas/releasetag-strict-semver-default.md` — Load when: working on publishability, versioning strategy or tag derivation. - Why the sync facade and the `./node-sync` entry exist → `okf/decisions/workspaces-sync-facade-escape-hatch.md`, `okf/decisions/second-published-entrypoint.md` — Load when: adding or reshaping any `*Sync` function or a second entry point. - The `./testing` subpath (`SourceBoundary` and its lexer's misses, `ImportGraph` and its two import-graph checks, `WorkspaceLayering` and `LayerPolicy`, `PackedInstall` and its per-manager traps) → `okf/interfaces/workspaces-repo-shape-checks.md`, `okf/decisions/packed-install-pack-source.md`, `okf/decisions/kit-layering-checks-runtime-edges.md`, `okf/decisions/carrier-only-declares-bins.md` — Load when: touching any module under `./testing`, `lib/configs/layers.json`, or a boundary, layering or packed-install test; the last when touching `BinConflict`, `allowSharedBins` or `runCarrierBin`. - The `LocalExec` direction and the contract-inversion rule → `okf/decisions/contract-inversion-default.md` — Load when: tempted to import this package from `commands`, `npm`, `lockfiles` or `package-json`. ## Operating rules - `src/index.ts`, `src/node-sync.ts` and `src/testing.ts` are the only re-exporting modules, and `src/index.ts` **must never re-export** `./node-sync` or `./testing` (`__test__/entrypoints.test.ts` pins it); `src/internal/catalogs.ts` is the one catalog engine, restating pnpm 12's catalog crates, and no `@pnpm/*` package may become a dependency; nothing new may build a local subprocess seam (git goes through `@effected/git`, anything else through core's `ChildProcessSpawner` via `@effected/commands`' `Run`); `minimatch` must not become a dependency. - The `./testing` modules read no `process`, import no `node:` or `@effect/platform*` module and write to no console: every environment value arrives as a parameter from the consumer's test file. `__test__/integration/SourceBoundarySelf.int.test.ts` pins it with the scanner the subpath ships. - `PackedInstall` owns no subprocess seam beyond `@effected/commands`' `Run` over core's `ChildProcess`; its pure decisions live in `src/internal/packedInstallPlan.ts`. - `RunBinOptions.stdin` omitted (or `""`) is `"ignore"`, the null device, never an open pipe; only `command`/`carrierCommand` leave stdin open. `PackedInstall.preflight` plans with the run's own `planClosure` and checks `//package.json`; `PackedInstall.gate` is pure over an `env` parameter (skip off CI, fail under CI). Neither may import `vitest`: the recipe lives in the skill, not a wrapper. - Never `Effect.cached` for a lazy init — the memo is `Effect.cachedWithTTL` (or `cachedInvalidateWithTTL` where a `refresh()` needs the invalidator) with the exit-keyed TTL `Exit.isSuccess(exit) ? Duration.infinity : Duration.zero`; never a post-hoc `onExit` invalidate (Module, "Lazy init"). - `PeerCheck` and `DuplicateCheck` join importers to instances through ONE implementation, `src/internal/roots.ts`, so they cannot disagree about which importers are answerable; do not fork the join. - Bind parameterized layer factories to a `const` (layers memoize by reference). `Workspaces.resolverLayer` is the deliberate exception. ## Testing and building Tests run on core's `Path.layer` + `@effected/memfs` (a devDependency), no platform package; `__test__/fixtures.ts` seeds a volume from a `Tree` record and injects misbehaviour as faults. - A suite-boundary `layer(...)` cannot vary per test, so **each distinct tree gets its own `layer(...)` block**. - Three integration suites run against **this repository** through `@effect/platform-node` (a devDependency): `self.int.test.ts` discovers it, `SourceBoundarySelf.int.test.ts` scans this package's own `src/`, and `layering.int.test.ts` checks the kit's package graph against `lib/configs/layers.json`. - Unit and integration tests never drive a live package manager. The `pnpm peers check` oracle under `__test__/fixtures/peers/*/peers-check.json` is committed pnpm output (provenance in that directory's `README.md`), and `PackedInstall`'s unit tests script every spawn through `ScriptedSpawner`. - Only `__test__/e2e/` may run real package managers, and only against a fixture workspace it generates, with every spawn under the scrubbed dead-proxy offline env (`HTTP(S)_PROXY` at a closed port, `COREPACK_ENABLE_NETWORK=0`) so nothing reaches a registry. `e2e/PackedInstall.e2e.test.ts` is that exception. Its dead-proxy control assumes the user's `~/.npmrc` sets no `proxy`/`https-proxy` (HOME is inherited by design); on a machine where it does, that one control can fail with a proxy error rather than `ECONNREFUSED`, while the installs stay hermetic because the fixture has no external dependencies. - The bundler's default config carries the **narrow** `_base` suppression for synthesized class-factory bases. Never widen it — the narrow pattern once caught a genuine `ae-forgotten-export`.