Spec: Operate through one domain-first Effect v4 architecture

User Input

in @linear project https://linear.app/devpunks/project/harness-intelligence-23aceec78aca/issues we have new modules M7 M8 M9 for the refactor and re architecture around effect v4. so now please start a $delivery-phase FOR EACH SINGLE ONE of the EPICS. complete all epics and their inner stories with a delivery phase per epic

DO NOT MISS ON ANY OF THE STORIES

do this in full parallel. dont merge on main the subsequent pr

The supplied backlog handoff additionally requires one epic-level spec at a time, preserves the already-materialized Linear scope, and forbids implementation before explicit delivery routing.

Context

Harness Intelligence currently spans Effect-dependent CLI, API, backoffice, and shared-package surfaces. Product behavior, integration mechanics, configuration, transport, and shared protocol concerns need explicit owners so engineers can evolve one coherent Effect v4 system without cross-domain internal imports, ambient configuration, runtime leakage, or untyped expected failures.

This epic extends the completed IP-97 typed API contract boundary. It preserves and evolves that protocol instead of recreating it. Its complete child-story scope is IP-332 through IP-336.

Non-Goals

• A compile-first Effect migration followed by later architecture cleanup.
• Independent Effect generations for individual workspaces or a v3/v4 translation layer.
• One giant composition module, daemon, or shared mutable runtime.
• Generic architecture buckets, stale compatibility aliases, or cross-domain internal imports.
• Modeling impossible programmer defects as expected product failures.
• One repository-wide catch-all operational error.
• A global configuration object or relocation of application-only configuration into shared packages.
• Repeating IP-97's completed typed-contract outcome or hosting application behavior in the shared protocol boundary.
• Selecting exact internal names, files, classes, symbols, or incidental APIs before implementation-time source verification.

Acceptance Criteria

IP-333 — One Exact Effect v4 Generation

• Delivery uses the selected coordinated set effect, @effect/platform-bun, @effect/sql-pg, and @effect/vitest at exactly 4.0.0-beta.98, verifies its peers/source evidence, and pins it across every participating workspace.
• Effect dependencies use exact versions without ranges and do not automatically follow later betas during delivery.
• Any subsequent Effect beta change requires an explicit repository-wide decision.
• Current Effect v4 source and the accepted effect-smol, OpenCode, and T3 Code references inform the migration without freezing their incidental class or symbol names into this specification.
• Every participating workspace moves together, and no v3/v4 translation layer remains.

IP-332 — Deliberate Domain Boundaries

• Applicable roots distinguish platform composition, integrations, and product domains.
• Each domain owns its actions, models, accepted errors, ports, justified services and repositories, Layers, tests, private support, and deliberate public surface.
• Cross-domain consumers use only deliberate public surfaces and do not import domain internals.
• Actions own workflow and policy, reusable services own mechanics, and repositories and adapters hide persistence and external systems.
• Transport parses input, invokes product behavior, and translates boundary results without owning product policy.
• Only each application entrypoint composes production dependencies and runs an invocation.
• Commands and domains do not create runtimes or choose production filesystem, network, terminal, or configuration implementations.
• No generic architecture bucket or stale compatibility alias remains in the coordinated result.

IP-334 — Typed Expected Failures

• Every expected domain or operational failure has an accepted schema-backed typed error in the Effect error channel.
• Every caller explicitly handles or intentionally propagates each expected failure.
• Domain behavior does not swallow expected failures, convert them to defects, hide them as unknown values, reduce them to strings, or translate them into terminal, exit-code, or HTTP behavior.
• Integration adapters normalize expected filesystem, process, network, database, GitHub, Skills CLI, and comparable failures before feature code observes them.
• Normalized errors retain useful operation context and the original diagnostic cause.
• Unexpected programmer defects remain defects.
• No universal catch-all error replaces domain-owned failure meaning.

IP-335 — Focused Validated Configuration

• Environment and runtime inputs are read and schema-validated only during platform configuration.
• Application and domain roots provide focused typed configuration services or Layers.
• Features, commands, and integrations do not read ambient environment values.
• Missing and invalid configuration remains a typed startup failure, with secrets redacted.
• Shared environment support contains only genuinely reusable decoding, schema, and provider primitives.
• Application-only configuration remains owned by its application or domain.
• Shared protocol and scaffold models remain configuration-free and receive explicit options.
• Tests inject parsed configuration services or focused providers explicitly.

IP-336 — Protocol Without Consumer Runtime

• The existing typed API contract is preserved and evolved rather than recreated.
• Baseline, telemetry, reports, and backoffice protocols expose separate deliberate public surfaces.
• Only genuinely shared cross-protocol primitives appear in a small explicit common surface.
• The shared boundary owns cross-process schemas, public typed errors, and endpoint definitions only.
• Request runtime, authentication, retries, handlers, persistence, scaffold policy, CLI decisions, and backoffice session behavior remain with their owning products.
• Consumers import only the protocol areas they use.
• The shared root does not expose every protocol domain together or provide a concrete request runtime.
• No stale compatibility re-export survives the coordinated migration.

Constraints

• IP-330 must first classify every affected public outcome as byte-locked, semantically equivalent, or intentionally changed and protect it at its public seam.
• IP-333 precedes IP-332, IP-334, IP-335, and IP-336 as the epic's native blocker relation.
• The final repository contains only the new Effect v4 architecture: no feature flag, dual path, shipped temporary scaffolding, or compatibility shim.
• The migration proceeds breadth-first through architecture levels on one unmerged, undeployed branch; intermediate branch states may be broken, but merge and release remain blocked until the complete repository and consumer gate passes.
• Managed scaffold assets and public JSON are byte-locked unless an accepted requirement changes them; intentional presentation changes and semantic context-plan equivalence follow their accepted classifications.
• The final gate includes every participating workspace's tests, typecheck, lint, and build; output-classification fixtures; zero Effect v3 dependencies/imports/shims; packaged CLI, API contract/handler, renderer-catalog, operator-lifecycle, and representative consumer proofs.

Branch/Base Intent

• Status: Branch/Base Intent
• Dependency: IP-330 — Classify and characterize every public behavior seam
• Evidence: Draft PR #76 and apps/wiki/content/docs/project/specs/cli/IP-319-establish-one-comprehensive-behavior-contract/IMPLEMENTATION-NOTES.md record completed, accepted IP-330 characterization evidence.
• Child branch: team/stefan/ip-320-effect-v4-boundaries
• Parent base: team/stefan/refactor-cli-architecture
• Reason: IP-330 readiness is proven on the parent delivery branch. IP-333 remains first within this epic as implementation order; the IP-320 child PR targets the parent branch and never main.

Coordinated Delivery Intent

• Delivery branch: team/stefan/ip-320-effect-v4-boundaries
• PR state: the IP-320 child PR is created only during delivery and targets team/stefan/refactor-cli-architecture; draft PR #76 remains the unmerged, undeployed parent delivery vehicle.
• Base intent: the child branch and PR never target or merge to main; the parent branch is the sole integration base for this epic.
• Ordering: IP-330, then IP-333, then breadth-first progress across IP-332/IP-334/IP-335/IP-336 and peer architecture epics.

Review State

• Requirements authority: completed CLI context architecture grill, with Q1-Q58 closed and all branches at 100%.
• Backlog authority: full IP-320 parent, all five Linear child stories, native relations, and empty comment threads read on 2026-07-14.
• Spec status: approved; source-to-criterion self-review found no omitted child story or acceptance signal, and IP-330 readiness is proven by the accepted IP-319 implementation evidence.
• Human approval state: complete; delivery is authorized to continue to planning on the coordinated draft PR.
• Specialist review: complete with no blocking findings or missing IP-332 through IP-336 acceptance signals.

Decision Log