Epic: canonical Effect 4 semantics and behavior follow-ups

Goal

Audit every active effect-utils Effect call site against deliberate Effect 4 conventions. Remove stale migration residue and legacy plumbing. Keep each behavior change explicit and independently proved.

This body supersedes the old post-migration backlog. The Effect 4 migration is complete; migration rules, stale occurrence counts, and the closed proposal inbox are not current work.

Cross-repository coordination lives in schickling/megarepo-all#117. This issue owns the effect-utils implementation and its repository-local child contracts.

Decisions

• Perform a complete convention audit, but do not perform regex-driven rewrites.
• Use named Effect.fn with stable span names for exported or domain-significant operations. The added trace boundary is intentional semantic adoption.
• Keep callbacks, tests, constant effects, and short local control-flow blocks as Effect.gen.
• Keep Effect.provide, Layer, and ChildProcessSpawner helpers when they express real dependency, scope, collection, or override semantics.
• A change must preserve scope lifetime, acquisition count, provision precedence, close order, concurrency, output bytes, error partition, wire formats, and persisted data unless a child issue explicitly changes that contract.

Work package A — remove active migration residue

• Update packages/@overeng/effect-ai-claude-cli/README.md and the public module example to use the actual Effect 4 modules and Node child-process layer. Remove the stale @effect/ai, @effect/platform, CommandExecutor, and NodeCommandExecutor guidance.
• Remove or rewrite the stale Effect 3/Effect 4 split rationale in packages/@overeng/notion-core/package.json.genie.ts without changing dependency selection.
• Audit active package documentation and generated-config sources for additional pre-Effect-4 API guidance. Do not rewrite historical migration records.

Proof

Every public example must import and compose against the current generated package graph. Generated files remain fresh. Documentation-only changes do not change generated dependency output unless the stale rationale concealed a real config defect.

Work package B — operation boundaries and tracing

Audit every active production function that returns an Effect. Classify each as:

1. exported/domain-significant operation → named Effect.fn("stable.operation.name");
2. wrapper where tracing is intentionally suppressed → Effect.fnUntraced with a reason;
3. callback, test body, constant effect, or short local block → keep Effect.gen; or
4. intentional exception with a semantic reason.

Initial concrete candidates include:

• genie/src/core/core.ts: generateAll, checkAll;
• agent-session-ingest/src/services/CheckpointStore.ts: makeFileCheckpointStore, saveAll;
• named operations in megarepo/src/core/git.ts.

Existing Effect.fn use in ci-tools, content-address, and agent-session-ingest adapters provides local precedent. effect-path intentionally uses Effect.fnUntraced and must not be changed only for uniformity.

Proof

• Pin stable span names for traced operations where a focused trace test exists or is warranted.
• Preserve return, error, retry, interruption, and concurrency behavior.
• Do not convert Vitest callbacks, entrypoint constants, or anonymous one-off generators.

Work package C — services and layer graphs

Audit every active service/layer boundary. Do not use raw Effect.provide counts as a backlog; it remains a canonical Effect 4 API.

For each proposed simplification, record:

• the dependency owner;
• construction/acquisition count;
• provision and override precedence;
• scope lifetime and close order;
• failure-channel behavior; and
• whether telemetry changes.

Start with graphs that have a concrete readability, lifetime, duplication, or override defect. Current ci-tools and megarepo composition roots and effect-rpc-tanstack client layers are intentional until such a defect is shown. Use effect-react/test/runtime-baseline.test.tsx as the proof model for construction, provision order, retry count, and teardown.

Work package D — child processes and scopes

Effect 4 ChildProcess.Command is directly yieldable. Remove explicit process-start plumbing only when the caller needs a scoped process handle and no helper semantics are lost.

Keep ChildProcessSpawner.string, lines, streamString, exitCode, and related helpers when they own collection or exit behavior. Preserve explicit spawner capture where a returned service starts processes later; effect-ai-claude-cli is lifetime-sensitive and is not a textual cleanup.

Use existing direct-yield patterns in npm-release, notion-md, megarepo, and Genie tests as references.

Proof

Focused process tests must preserve argv/env, stdin, concurrent stdout/stderr draining, collected bytes/lines, non-zero exit classification, interruption/kill behavior, and scope cleanup.

Work package E — deliberate behavior changes

These changes do not land inside behavior-preserving convention PRs:

• #978 — define a first-party Restate ingress decode-error envelope. Preserve full internal diagnostics while making caller-facing 400 bytes independent of Effect formatter prose.
• #980 — define the CLI human/machine stream boundary, adopt typed machine emission, and remove the current argv guard after upstream/local proof.

Each child issue owns its public contract, compatibility policy, tests, and rollout.

Resolved or rejected work

• #979 is complete. effect-rpc-tanstack remains single-current-format; consumer rollout stays consumer-owned.
• Remove the proposed repository-wide Effect.catchReason work. No such current upstream API exists and there is no bounded error redesign.
• No Effect facade.
• No broad combinator-to-Effect.gen rewrite.
• No blanket Effect.provide removal.
• No conversion of collection-oriented spawner helpers into raw process handles.
• No wire compatibility layer for effect-rpc-tanstack.
• No proposal inbox from the closed migration.
• No use of historical 795, 35, or similar regex counts as current scope or progress.

Audit artifact

Publish one revision-bound inventory of every active package. For each package, record:

• operations: changed / already canonical / exception;
• services and layers: changed / already canonical / exception;
• child processes and scopes: changed / already canonical / exception;
• stale active docs/config rationale: fixed / clean;
• behavior findings: owning issue.

The inventory lists candidate symbols, not only counts. Tests, docs, generated files, and production source remain separate categories.

Order

1. Contract this tracker and fix documentation/config residue.
2. Complete the operation/tracing audit.
3. Complete service/layer and process/scope audits as package-sized PRs.
4. Land #978 and #980 independently from canonicalization.
5. Record the final package inventory and intentional exceptions.

Acceptance

• Every active effect-utils package is classified in the audit artifact.
• Active public documentation names only current Effect 4 modules and layers.
• Every exported/domain-significant Effect operation is named and traced, or has an explicit exception.
• Every changed layer/process boundary has focused lifetime, ordering, stream, exit, and cleanup proof as applicable.
• No behavior-changing work is hidden in a canonicalization PR.
• #978 and #980 are completed or consciously closed with their contracts recorded.
• Generated freshness and the repository quick gate pass for every implementation PR.
• A final audit finds no unclassified active Effect call sites or stale active Effect 3 guidance.

Posted on behalf of @schickling

field	value
agent_identity	dev3.direct.omp.3vjvwkb2
session	dev3.3vjvwkb2
agent_persona	generalist
agent_supervisor	unavailable
agent_tool	OMP
agent_tool_version	18.1.7
agent_runtime	OMP 18.1.7
tooling_profile	dotfiles@931583a

Start with the audit artifact and the listed entry points: genie/src/core/core.ts, agent-session-ingest/src/services/CheckpointStore.ts, and megarepo/src/core/git.ts. Read effect-react/test/runtime-baseline.test.tsx and existing Effect.fn examples before running focused tests. Done means every active package is classified, stale active guidance is fixed, and changed boundaries have the required behavior and cleanup proof.