Repository navigation
Effect Service Conventions: 3 issues found
Three convention issues remain in the new Effect service code. Prior findings (module-global shutdown channel, free-form launcher error, duplicated launcher-context read in the SQLite layer, duplicated ServiceLauncherClient layer) are resolved.
apps/server/src/cloud/selfUpdate.ts(line 66):failWithno longer accepts a cause, so both wrapping sites drop the structuredPinnedRuntimeInstallError/ServiceLauncherClientErrorand buildreasonfromerror.message.ServerSelfUpdateErrordeclares an optionalcause; the immediate error should be preserved and the wrapper text derived from structural attributes.apps/server/src/cloud/pinnedRuntime.ts(lines 114-125): newly addedEffect.catchTag("PinnedRuntimeInstallError", ...)should beEffect.catchTags({ ... }).apps/server/src/cloud/selfUpdate.ts(line 27): the local service moduleserviceLauncherClient.tsis consumed at a service boundary but imported with named imports instead of a namespace import.
All three were posted as inline review comments with suggested fixes.
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.
Scope reviewed: new and changed service modules under apps/server/src (cloud/serviceLauncherClient.ts, cloud/serviceProtocol.ts, cloud/servicePreflight.ts, cloud/selfUpdate.ts, cloud/bootService.ts, cloud/pinnedRuntime.ts, serverShutdown.ts, serverActivation.ts, serverRuntimeStartup.ts, server.ts, cli/server.ts, cli/servicePreflight.ts, persistence/Layers/Sqlite.ts, persistence/Migrations.ts, reactor service/layer shape changes) plus packages/contracts and packages/client-runtime contract/state updates.
Verified as acceptable:
ServerShutdownis now a properContext.Servicewithmakeandlayer, replacing the previously flagged module-global set; the CLI supplies it viaLayer.succeedat the CLI boundary.ServiceLauncherClientis constructed once inmakeServerLayerand shared as a single instance to both the routes layer and runtime services, so the stateful client is no longer built twice.ServiceLauncherTrialis now aContext.Referencepopulated from the single client instance, so the SQLite layer no longer re-decodes launcher context fromprocess.env.ServiceLauncherClientErrornow uses a multi-valueoperationdiscriminator with a message derived from structural attributes, matching the guidance for one service-level error covering related IPC failures.PinnedRuntimePreflightBlockedErrorcorrectly separates the caller-visible blocked-preflight case from the diagnosticPinnedRuntimeInstallError.stepfield.ensurePinnedRuntimeInstalled's explicitfs/path/runnerparameters are pre-existing and out of scope; the newvalidateparameter is a deliberate callback strategy, not service injection.forkParkedactivation gates passed to reactorstart(...)are synchronization values, not service instances.
🔍 Agent activity — 1 tool call
💭 Looking at the diff between the current commit and the prior run, I can see that several issues have been resolved: the serverShutdown module-global Set has been refactored into a proper Context.Service with make and layer functions, the error message about PinnedRuntimeInstallError has been cleaned up into PinnedRuntimePreflightBlockedError, and the serviceLauncherClient now properly uses ServiceLauncherHostProcess from Context instead of defaulting to global process and environment variables. The Reference and HostProcessEnvironment still touch the global process at the default level, but that's acceptable since it's a Context.Reference default. The ServiceLauncherClientError has been updated to use an operation literal discriminator with a message switch, which aligns with the convention allowing a single error with a multi-value operation discriminator when failures share the same semantics. The Sqlite.ts isServiceLauncherTrial check now properly uses the ServiceLauncherTrial Context.Reference from launcherClient.trial, and the duplicate ServiceLauncherClient.layer provision has been eliminated by constructing launcherClient once in makeServerLayer and sharing it throughout. Now reviewing the current diff for any new violations. The serviceLauncherClient.ts file exports make, layer, and the ServiceLauncherClient service with a reasonable structure—imports, error class, interfaces, References, helpers, tag, and layer definition. The layer uses Layer.effect with make(), while server.ts calls make() directly with Layer.succeed at the application boundary, which is acceptable. The ServiceLauncherHostProcess Reference's defaultValue reading global process follows the host-process reference pattern and is acceptable. serverShutdown.ts follows the standard Context.Service, make, and layer structure. In cli/server.ts, ServerShutdown.make is yielded and then Layer.succeed wraps it—that's fine. The comment notes the CLI supplies configuration and the controlled-shutdown service, and while server.test.ts also provides ServerShutdown.layer, there's no conflict. serverRuntimeStartup.ts now has make as a function accepting optional parameters that returns an Effect, with layerWithOptions and a default layer—that's acceptable. Sqlite.ts has a setup function taking trial, which is fine. In Migrations.ts, MigrationManifestMismatchError has structured attributes like expectedCount and actualCount, but the message is a constant generic string rather than derived from those attributes. It's not ideal by convention, but the attributes are there and the message is clear enough—not worth flagging as a real issue. servicePreflight.ts contains pure synchronous functions using node:sqlite directly, used in CLI commands and child processes, so it's not an Effect service. runServicePreflight appears to be a synchronous function doing file operations. The
runServicePreflightfunction catches all errors and returns a blocked state, so no exceptions escape—it's eager IO that runs when the handler is invoked at execution time, which is acceptable. InbootService.ts, I'm usingnode:fs/promisesdirectly withEffect.tryPromisefor durable writes since the Effect FileSystem service doesn't expose fsync, which justifies bypassing the abstraction. However, there's a path parsing issue wherewriteDurablymanually slices the file path instead of using the Path service already available, and it references theprocess.pidglobal—these are quality concerns but not core convention violations, and since bootService is Linux-only, the Windows path bug isn't in scope. I'm also noticing thatreadStateimplements hand-rolled JSON validation instead of using thepreferSchemaOverJsondiagnostic that's enforced elsewhere in the repo. Looking at whether hand-rolled decoders inserviceProtocol.ts,bootService.ts, andserviceLauncherClient.tsviolate the Effect Service Conventions — they're not explicitly called out in the check's sections on imports, service definition, dependency acquisition, errors, predicates, file layout, or change discipline. The convention does mention exporting schema predicates likeisFoo, but that's not applicable here.isExactServiceVersionis just a plain regex predicate which seems fine, so I'm checking for other potential violations. Now I'm going through the imports systematically — the touched code uses namespace imports from "effect" consistently, and the subpath import fromeffect/unstable/climatches existing repo conventions. The named import from the contracts package is allowed, but I'm noticingselfUpdate.tsimports from the local service moduleserviceLauncherClient.tsusing named imports rather than a namespace, which might conflict with the service boundary convention. InserverRuntimeStartup.tsandserver.ts, they're using namespace imports forServiceLauncherClient, butselfUpdate.tsuses named imports instead—that's an inconsistency worth flagging. ThepinnedRuntime.tsimports are fine as named imports since it's just helpers and errors, not a service module. Looking at other files,ServerShutdownfollows the namespace pattern correctly,bootService.tsuses named imports for pure constants and types which is appropriate, andSqlite.tsimports just theServiceLauncherTrialreference from the service module—that's a borderline case since it's only the reference, not the full service. Test files are less strict about these conventions anyway. The question is whether flagging the named import ofServiceLauncherClientinselfUpdate.tsis worth the effort, given that it's a generated type. The convention says to import service modules as namespaces, and while the named import doesn't erase clarity entirely, it does erase the module namespace context. Since the check defaults to failure and I want to avoid noise, I should look for stronger findings instead. Let me examine the service definition structure itself — the tag, inline interface, exportedmakeandlayer, and how the error class andServiceLauncherProcessinterface are ordered. Now I'm checking the dependency acquisition pattern. The key rule is that production service construction must acquire Effect service dependencies from the environment using the namespace pattern, and themake/layertypes must expose those requirements. Looking at howserver.tsconstructs the launcher client and merges layers... The application composes the resource once in an application-owned layer and provides its context to integration runtimes, which aligns with the instructions.makeServerLayerusesLayer.unwrapwithEffect.gen, soServiceLauncherClient.make()can fail withServiceLauncherClientError— that's acceptable. TheserverRuntimeStartup.makefunction takesawaitAuxiliaryParkedas an Effect value rather than a service instance, which is a deliberate callback strategy, though passing an Effect as a parameter is a bit unconventional. I'm noticing thatisServiceLauncherManagedinselfUpdate.tsis re-reading and re-decoding the launcher context from the environment, which duplicates whatServiceLauncherClient.managedalready does — and with different strictness levels too, since one returnsfalsefor invalid context while the other fails. I should trace whereresolveServerSelfUpdateCapabilityis actually being used to see if this duplication matters. TheServerUpdateTerminalErrormessage construction looks fine, butPinnedRuntimePreflightBlockedErrorhas a similar pattern where it stores a user-facing sentence asreasonand returns it directly as the message. This mirrors the earlier issue I flagged — the reason comes from the remote preflight service, so I should check whether this violates the convention of deriving messages from structured attributes rather than storing unstructured text. Actually, since the target version generates this message and there's no way to reconstruct it structurally on the client side, this is defensible. The previous version had the main complaint fixed already, so I won't re-flag it. Looking at the error mapping inselfUpdate.ts, I'm checking how errors are transformed when they're caught and re-thrown. Continuing with error handling... I need to check theServerSelfUpdateErrordefinition to see if it supports acausefield. Looking at the contracts, it seems the previous version accepted bothreasonandcauseparameters, but this PR's implementation drops the cause entirely and derives the reason string directly fromerror.message. That's a regression — the cause is lost and the message violates the principle of not interpolatingcause.messageinto wrapper messages. The same issue appears in thelauncher.requestUpdatecall, which also drops the cause when mapping the error. Let me verify theServerSelfUpdateErrorschema and trace whereresolveServerSelfUpdateCapabilityis actually used. I'm noticing thatServerEnvironment.makeandServiceLauncherClient.managedare both trying to determine the same launcher management status, but they're doing it differently — one re-decodes the launcher context from environment variables while the other already has it exposed, and they handle errors differently too, with one failing strictly and the other silently returning false. This is the same kind of duplicate state acquisition I flagged before in Sqlite.ts that they fixed. SinceServerEnvironmentis constructed within the runtime layers whereServiceLauncherClientis already provided through the dependency injection setup, using the client directly instead of re-decoding should be feasible. Let me check the full selfUpdate.ts file to see what's happening with the failWith and cause handling. I'm noticing a pattern in how errors are being handled across these two sites—bothensurePinnedRuntimeInstalledandrequestUpdateare dropping the underlying error details when they map to their wrapper errors, relying instead on extracting the message from the caught error. TheServerSelfUpdateErrortype supports an optionalcausefield, but the current implementation isn't using it, which breaks the convention for error chaining. There's also a regression here: the old code passed the cause explicitly and used static reason strings, whereas now the reason string is being interpolated fromerror.message. Additionally, line 170 uses inline tag discrimination to pick caller-visible text based on the error type, which works but could be cleaner withEffect.catchTagsinstead of doing the tag check insidemapError. I'm also noticing thatresolveServerSelfUpdateCapabilityandisSerare duplicating launcher-context decoding outside ofServiceLauncherClient, which should be consolidated. There's also an inconsistency in howServiceLauncherClientis imported across files —selfUpdate.tsuses a named import while other files likeserver.tsuse namespace imports, which breaks the pattern. Let me verify the other new files aren't introducing similar violations. Looking atpinnedRuntime.ts, theensurePinnedRuntimeInstalledfunction already had those explicit parameters before this PR, though it now accepts avalidatecallback which is a deliberate design choice. I need to check whether this violates the rule about factories accepting service implementations as dependencies. I notice theensurePinnedRuntimeInstalledfunction already accepted those parameters before this PR, so that's not a new issue. But there's a problem at line 114 whereEffect.catchTagis being used for a single error tag — the style guide says to useEffect.catchTagswith an object instead, and this appears to be a new addition in this PR that violates that convention. Let me search through the diff for othercatchTagusages and check the full files for additional issues like hand-rolled state reading in bootService.ts and serviceLauncherClient.ts. The rule explicitly forbids usingcatchTag, and this is a newly-added line, so I should flag it even though it's used elsewhere in the repo. I'll include a brief inline comment with a fix suggestion since it's a trivial change. Now looking at the actual findings: the main issue is inselfUpdate.tswherefailWithis dropping thecausefield and building the reason only fromerror.message. TheServerSelfUpdateErrorhas an optionalcausethat should be preserved. I need to flag this violation of the "preserve the immediate underlying error as cause" principle and suggest restoring thecauseparameter tofailWith, passing the structured error object directly so the reason comes from the error's attributes rather than its message string. I'll place a single comment at line 66 on thefailWithfunction definition to explain that it drops the cause at both call sites and derives the reason from the error message. That's the most focused location to document the issue and the fix. Now I'm moving on to the second finding in selfUpdate.ts around lines 37-42 and ServerEnvironment. ts at line 128, where there's duplicate launcher-context acquisition happening. TheresolveServerSelfUpdateCapabilityfunction is re-decoding the launcher context throughisServiceLauncherManaged()instead of reading directly fromServiceLauncherClient.managed, and they have different strictness levels — one silently returns false while the other throws a typed error. I need to check whetherServiceLauncherClientis actually available in ServerEnvironment's layer context before I can safely suggest a fix. Looking at how ServerEnvironment is constructed, it goes throughServerEnvironment.makein RuntimeCoreDependenciesLive, and the launcher layer gets provided viaLayer.provide(launcherLayer)on runtimeServicesLive. So it should be available there. But ServerEnvironment might be used in other contexts like the CLI, so I should phrase this carefully as acquiring from ServiceLauncherClient rather than making a hard assertion. Let me trace through where ServerEnvironment.layer is actually used to understand the scope of this change. I also spotted a couple other issues:Effect.catchTagshould beEffect.catchTagsin pinnedRuntime.ts, and there's a named import versus namespace import inconsistency in selfUpdate.ts that's low priority—I can fold that into the comment for the main finding instead of calling it out separately. I'm realizing thatServerEnvironment.layeris also used in the connect CLI code, which complicates things sinceServiceLauncherClientmight not be available there. AddingServiceLauncherClient.layerwould be the right approach, though it means the connect CLI wouldn't be launcher-managed, somake()would still succeed withmanaged=falsesince there's no context environment. Looking at this more carefully, the convention violation isn't as clear-cut as I initially thought. The code does properly acquire dependencies from the Effect environment throughServiceLauncherHostProcessandHostProcessEnvironment, so it's not hiding dependencies. The real issue is duplicated decoding logic — more of a DRY and consistency concern than a stated convention violation. Since the conventions don't explicitly forbid duplicate derivation, and I'm supposed to report only concrete violations, I should probably drop or downgrade this finding to keep the signal strong. The behavioral inconsistency betweenServiceLauncherClient.make()failing hard on invalid context whileisServiceLauncherManagedsilently reports unmanaged is interesting, but it's moot in practice sincemake()runs first and would kill startup anyway. That's low value. The named import at line 27 is worth flagging though — the convention explicitly requires importing service modules as namespaces at service boundaries, andselfUpdate.tsline 56 usesServiceLauncherClientat a service boundary. The file already does this correctly forServerShutdown,ProcessRunner, andServerConfig, so this is a trivial fix and worth calling out. I should include it as a minor comment. Checking the other imports:Sqlite.tsusesServiceLauncherTrialas a Context.Reference which is allowed,server.tsandserverRuntimeStartup.tsalready namespace-import correctly, andCheckpointReactor.tsimports from a pure helper module which is fine. TheLayer.succeedcalls look good —server.tscomposes once at the app boundary andcli/server.tsdoes it at the CLI boundary. Now I need to verify whetherServiceLauncherClient.layeris being provided twice in the layer composition around line 436. Looking at the diff,makeRoutesLayer.pipe(Layer.provide(launcherLayer))andruntimeServicesLiveboth provide the same instance throughLayer.succeed, so that's resolved.serverRuntimeStartup.tsexports alayerthat requiresServiceLauncherClientandServerShutdown, which is correct, andServerShutdownis properly acquired from the environment inselfUpdate.ts. One more thing to check:servicePreflight.tshas a synchronous IO function being called insideservicePreflightCommandwithConsole.log(JSON.stringify(runServicePreflight(...))). The sync IO happens at handler invocation time during CLI execution, before the Effect actually runs, so there's no interruption or tracing involved — it's just a CLI adapter boundary, so I'll skip that. InbootService.ts,writeDurablyusesprocess.pidand Node's filesystem directly even thoughFileSystemandPathservices are available in the service'smakefunction, but sincewriteDurablyis a module-level helper outside the service, it can't access those services. The string slicing for dirname instead of using the path service is fragile, but it's out of scope since the file already has thenodeBuiltinImport:offdiagnostic suppression and imports the necessary Node builtins. Moving on to the actual findings. I've identified three issues to comment on: thefailWithcall in selfUpdate.ts that drops the cause, theEffect.catchTagthat should beEffect.catchTagsin pinnedRuntime.ts, and the namespace import for a local service module in selfUpdate.ts. Let me verify these line numbers exist in the diff and then draft the comments. For the first issue at selfUpdate.ts:66,failWithno longer accepts a cause parameter, so both error-wrapping sites discard the structured error details and instead extracterror.messagefor the reason. SinceServerSelfUpdateErroralready has acausefield defined as optional, the convention should be to preserve the original error as the cause and derive the wrapper's reason from stable attributes rather than relying oncause.message. At the call sites, I need to update how errors are passed: for the blocked runtime case, pass the error as cause; for the launcher rejection, the detail is actually a structural attribute on the reply, so usingerror.messageloses information—I should pass the error as cause and let the reason be derived from that message, or better yet, extract the meaningful detail from the launcher's response directly. For the inline suggestion, I'll focus on the failWith definition at line 66 and describe the call-site changes in prose rather than showing all the code. Now looking at the second comment in pinnedRuntime.ts around line 114, where there's a catchTag handler for PinnedRuntimeInstallError... Converting this to catchTags requires modifying multiple lines (114-125), so a single-line suggestion won't work. I need to use a multi-line suggestion or unified diff that covers the entire block, showing how to restructure from catchTag to catchTags with the handler as an object property. For the third comment about the namespace import in selfUpdate.ts, changing to a namespace import would require updating all the usages throughout the file, which creates a multi-hunk diff. That's too complex for a suggestion, so I'll just mention it in prose instead. Given that there are actual findings here and the check defaults to failure when convention violations are present, I should mark this as a failure and post the review.
1. modify_pr — Reviewed the Effect service changes in this PR (launcher client, shutdown service, self-update, pinned runtime, startup/activation wiring). The prior findings on the module-global shutdown channel, the free-form launcher error, duplicated launcher-context reads in the SQLite layer, and the double ServiceLauncherClient layer are all resolved. Three smaller convention issues remain in the new code.
Agent Credits: 217 credits