Skip to content

feat(connections): manage environment availability

MacroscopeApp / Macroscope - Effect Service Conventions completed Aug 7, 2026 in 3m 53s

Effect Service Conventions: 1 observation

Previously flagged items are resolved: packages/client-runtime/src/connection/onboarding.ts now uses Effect.catchTags({ ... }), and the activation stores in apps/mobile/src/connection/storage.ts and apps/web/src/connection/storage.ts label their failures with the new list-activation / set-activation operations that were added to ConnectionPersistenceError.

Remaining observation:

  • packages/client-runtime/src/connection/layer.ts: Effect.tapError + Effect.retry are applied to registry.start, which is typed Effect.Effect<void> (no error channel), so the handling is unreachable; the startup persistence failures it targets are raised while the registry layer is constructed in make.

No violations found in the new ConnectionActivationStore service definition, the registry activation APIs, the atom/command wiring, or the touched imports.

Details

Note

Your check run agent prompt is: .macroscope/check-run-agents/effect-service-conventions.md
More information about how Check Run Agents work can be found in our Help Center.

Files examined against the conventions:

  • packages/client-runtime/src/platform/persistence.ts icStorefollows the sibling store pattern (inline interface inContext.Service, no make/layer` for an abstract port), and the new operation literals are structural attributes on the existing error.
  • packages/client-runtime/src/connection/registry.ts icationStoreacquired from the environment viayield* Persistence.ConnectionActivationStore; setEnabled/updateRegistrationexpose typedConnectionPersistenceError | EnvironmentNotRegisteredErrorfailures. The remainingEffect.catchTag` occurrences are pre-existing lines that this PR only re-indented, so they were not flagged.
  • apps/mobile/src/connection/storage.ts, apps/web/src/connection/storage.ts ic.addinsideLayer.effectContextafter acquiring the catalog in Effect; no hidden runtimes orManagedRuntime.make`.
  • packages/client-runtime/src/state/connections.ts, packages/client-runtime/src/state/presentation.ts, apps/web/src/connection/onboarding.ts icService["Service"]` usage.
  • Mobile/web UI files in the diff are React boundaries and contain no Effect service construction.

Note (not reported as a finding): the PR reformats large amounts of untouched code in registry.test.ts, registry.ts, and several screens to a narrower print width, which obscures the substantive changes; that is outside this check's scope.


🔍 Agent activity — 1 tool call

💭 Looking at the diff for Effect service convention violations across the changed files—the persistence layer now has a new ConnectionActivationStore Context.Service with inline interface definitions and added operations for activation management, the registry and onboarding modules have been refactored with proper Effect error handling using catchTags, and there are updates to the mobile storage implementation as well. Now checking the current state for any remaining issues: the Layer.succeed usage in storage.ts looks correct with ConnectionActivationStore.of({...}) inside Layer.effectContext, the imports use proper namespace subpath conventions, and the new persistence service follows the same pattern as other abstract port services in the module without requiring explicit make/layer exports. I need to verify the import sources for the type definitions in registry.ts to ensure they're coming from the right contracts module. I'm checking the registry.ts file around those line ranges to see if the catchTag usages were introduced or modified in this PR, particularly looking at the removeRelayEnvironments function and whether the reformatting in the diff represents an actual change or just a presentation difference. The massive reformatting throughout the PR—likely from running prettier with a different printWidth setting—is creating noise, but it's not directly a violation of the Effect service conventions I'm checking. I'll note it as a change-discipline concern without failing on it. Now I need to examine the actual new code in registry.ts for dependency acquisition and error handling issues. Looking at the key additions: disabledEnvironmentIds is a mutable Set captured in a closure inside make, which is local state rather than using Ref like other state in the service—this feels like a consistency issue around mutation and concurrency, but it's not explicitly covered in the conventions I'm reviewing. The bearerRuntimeKey uses JSON.stringify which is fine, and the new setEnabled command in state/connections.ts properly uses createRuntimeCommand. I'm noticing that ConnectionPersistenceError stores a message field directly, which goes against the pattern of deriving messages from attributes—this is pre-existing and wasn't flagged. The helper mapper targetPersistenceError in the mobile storage file that creates this error is also pre-existing, and the new operation literals added there are fine since prior issues have been resolved. I'm noticing that registry.start is typed as Effect.Effect<void> with no error channel, which means any error handling operations like Effect.tapError or Effect.retry applied to it would be dead code since there's no error to catch. Looking at the error handling flow, start doesn't have an error channel since it catches EnvironmentNotRegisteredError, so I'm adding retry logic with exponential backoff to the registry startup in the layer configuration. But this creates dead code — since start can't actually fail, the tapError and retry never trigger. There's also a subtle issue where start sets the started ref on the first attempt, so retrying would be pointless anyway. I'm checking whether this violates the Effect service conventions, but dead retry logic isn't explicitly listed in the conventions I need to report on. I'm also wondering where persistence failures during startup would surface in the flow. The legacy catchTag usage in registry.ts is only whitespace-changed, so I'll skip flagging those. The mutable disabledEnvironmentIds Set is more interesting—it's a closure-level state that breaks Effect discipline since the rest of the codebase uses Ref/SubscriptionRef, and wrapping mutations in Effect.sync doesn't fully address the concurrency hazard, though it's not an explicit convention violation. I'm leaning toward reporting it as a finding with softer phrasing rather than a hard failure. The new ConnectionActivationStore looks fine—it follows the same pattern as other stores in persistence.ts. Now checking the onboarding and connections files: the runtime command properly pipes through ConnectionOnboarding with Effect operations, imports look clean, and the registry usage follows the namespace convention. The error handling wraps EnvironmentNotRegisteredError into ConnectionBlockedError but seems to be discarding context in the process. I'm checking the merge base version to see what Effect.forkScoped was doing in the stream run setup, specifically looking at lines 35-46 to understand the context. The key issue here is that registry.start is now forked rather than awaited, which changes the behavior so the layer doesn't wait for initialization to complete. There's also dead retry logic on an Effect<void> with a never error channel — this is an Effect usage violation since the retry can't actually recover initialization failures that surface during layer construction. I should report this as an inline comment. Now I'm weighing whether this finding should fail the check. The guidance says convention violations may fail, but this is more of a correctness issue than a listed convention violation. The schema defaults to failure unless clean, so findings would presumably cause failure. Since this isn't a clear convention violation, I should look through the other changed files for more solid convention issues before deciding whether to report it at all. Desktop doesn't seem to provide ConnectionRegistrationStore, so it must be relying on the web app's storage instead. Looking at the mobile UI, AtomCommandResult is importing from @t3tools/client-runtime/state/runtime using named imports, which is fine for type imports. Now I'm checking the onboarding file in the web app where there's a new updateBear Checking the EnvironmentActivationSwitch component — it's a straightforward React component. Now I'm reviewing the error handling conventions against the code I'm touching. The onboarding file translates errors but drops the cause, and ConnectionBlockedError doesn't have a cause field in its schema — it has reason, detail, and traceId instead. The convention says to preserve the underlying error as cause, but looking at how ConnectionBlockedError is constructed elsewhere in the file, it seems the existing pattern doesn't pass cause either, so I need to check whether that's intentional or if the schema needs updating. Looking at the registry code, I'm noticing the setEnabled and remove methods are mutating closure state directly with a Set instead of using a Ref. That violates the dependency isolation principle — hiding mutable state in closures over singleton services is a smell, especially under Effect discipline. Looking at the imports and schema setup in storageDocument.ts, everything checks out with the proper Effect subpath namespace usage. The main issue I'm tracking now is that dead error handling code on registry.start in the client-runtime connection module—it has tapError and retry logic even though that operation never actually fails. There's also a mutable closure Set for tracking disabled environment IDs in the registry's make function. The question is whether these are real convention violations or just code quality issues. The retry logic suggests the author wanted typed failure handling, but start actually swallows persistence failures internally since those happen during the make phase, not the start phase. So the typed error channel expectation doesn't match the actual behavior. Given the check defaults to failure when there are findings, I need to decide if the dead retry code on a never channel counts as a concrete violation worth reporting. It's objectively wrong code introduced in this PR, so flagging it as an inline comment seems reasonable and actionable, though it's not explicitly listed in the conventions. The question is whether that warrants failing the check or staying neutral. Let me verify whether Effect.retry on a never-failing effect is actually a TypeScript error — it's not. But looking back at the conventions, the clearer violation is hiding dependencies in module globals or singleton closures. The ConnectionActivationStore.of usage inside Layer.effectContext with Context.add is legitimate since it's built within an Effect with proper resource acquisition. The setEnabled interface correctly declares its error channel. So the main finding stands: dead error handling in the layer where registry.start has no error channel to propagate, making the retry and error handling unreachable. I'm torn between reporting this as a real defect in the Effect service composition or staying silent. It's a genuine issue I'm confident about, but the question is whether it warrants a failure state or just neutral. Since this isn't a clear convention violation, I'll report it as a finding with neutral state rather than failing the check. There's also a behavioral change from the fork that I should mention: the layer no longer blocks on registry.start completing—it forks instead, which means the platform reconciliation stream now waits for start in a different way than before. I could provide a unified diff showing the removal, but that's not fully self-contained since dropping the tapError and retry calls would leave the Schedule import unused. I'll include the diff as an option and note that the import cleanup would be needed separately.

1. modify_pr — Effect service conventions review: the previously flagged catchTag/persistence-operation labelling issues are resolved. One remaining observation in packages/client-runtime/src/connection/layer.ts.


Agent Credits: 185 credits