[Epic] Effect-TS 7-Layer Service Architecture

[Soushi888]

Summary

Implement the Effect-TS 7-layer service architecture for the nondominium UI, following the proven pattern from Requests & Offers (happenings-community/requests-and-offers). This architecture provides typed error channels, fiber-based concurrency, automatic resource cleanup via Scope, and composable retry policies — all enforced at the type level before the first real UI feature is built.

Reference: requests-and-offers/documentation/guides/adopting-7-layer-architecture.md

The 7 Canonical Layers

Layer	Name	Responsibility
1	Service	Effect-native services with Context.Tag DI; zome wrappers; governance workflow services
2	Store	Svelte 5 runes with standardized helpers; reactive DHT state
3	Schema	Schema.Class validation at DHT boundaries; VfAction enum
4	Error	Data.TaggedError per domain; centralized context constants
5	Composable	Business logic abstraction; role guards; governance workflow dispatch
6	Component	Thin Svelte 5 components consuming composables
7	Test	Unit (service mocks) + integration (store/composable) + E2E (Playwright)

Nondominium-Specific Additions to the R&O Baseline

The governance-as-operator architecture requires extensions that don't exist in R&O's flat CRUD model.

Workflow Services (inside Layer 1) — multi-step governance sequences:

• CustodyTransferWorkflow: Commitment → GovernanceEvaluation → EconomicEvent → Claim → PPR×2
• AgentPromotionWorkflow: request → validate identity → validate first resource → approve → assign role
• ResourceValidationWorkflow: create resource → request validation → collect receipts → check status
• EconomicProcessWorkflow: validate role → initiate process → complete → generate PPRs

Role Guard Composable (inside Layer 5): useRoleGuard() reads myCapabilityLevel and myRoles from the person store and derives all UI permissions (canInitiateTransport, canValidateResources, canApprovePromotions, etc.).

PPR Store (inside Layer 2): myPPRs, myReputationSummary, sharedReputations — no R&O equivalent.

Validation Queue (inside Layer 2, governance store): validationQueue: UIResourceValidation[] — resources awaiting validation by the current agent, role-gated to AccountableAgents.

Implementation Tasks

Layer 4 — Error (implement first, no dependencies)

• errors/person.errors.ts — PersonError extends Data.TaggedError
• errors/resource.errors.ts — ResourceError extends Data.TaggedError
• errors/governance.errors.ts — GovernanceError + WorkflowError extends Data.TaggedError
• errors/ppr.errors.ts — PPRError extends Data.TaggedError
• errors/error-contexts.ts — PERSON_CONTEXTS, RESOURCE_CONTEXTS, GOVERNANCE_CONTEXTS, PPR_CONTEXTS, WORKFLOW_CONTEXTS

Layer 3 — Schema (implement second, depends on Holochain types only)

• schemas/person.schemas.ts — PersonInput, UIPerson, EncryptedProfileInput
• schemas/resource.schemas.ts — ResourceSpecInput, UIResourceSpec, EconomicResourceInput, UIEconomicResource
• schemas/governance.schemas.ts — VfActionSchema (all 16 variants), CommitmentInput, UICommitment, GovernanceTransitionResult
• schemas/ppr.schemas.ts — PerformanceMetrics, UIParticipationClaim, UIReputationSummary

Layer 1 — Service (zome wrappers + workflow services)

• utils/zome-helpers.ts — copy wrapZomeCallWithErrorFactory from R&O (verbatim)
• utils/effect-svelte-integration.ts — copy from R&O (verbatim)
• utils/store-helpers/ — copy entire directory from R&O (verbatim)
• services/connection.service.ts — copy from R&O, update ZomeName type only
• services/zomes/person.service.ts — PersonServiceTag + PersonServiceLive
• services/zomes/resource.service.ts — ResourceServiceTag + ResourceServiceLive
• services/zomes/governance.service.ts — GovernanceServiceTag + GovernanceServiceLive
• services/workflows/custody-transfer.workflow.ts
• services/workflows/agent-promotion.workflow.ts
• services/workflows/resource-validation.workflow.ts
• services/workflows/economic-process.workflow.ts

Layer 2 — Store (one domain at a time)

• stores/person.store.svelte.ts — allPersons, myProfile, myCapabilityLevel, myRoles
• stores/resource.store.svelte.ts — resourceSpecs, economicResources, governanceRules
• stores/governance.store.svelte.ts — pendingCommitments, validationQueue, pendingRoleRequests
• stores/ppr.store.svelte.ts — myPPRs, myReputationSummary

Layer 5 — Composable

• composables/ui/useRoleGuard.svelte.ts — role-based UI permission derivation
• composables/ui/useErrorBoundary.svelte.ts
• composables/domain/person/usePersonManagement.svelte.ts
• composables/domain/resource/useResourceManagement.svelte.ts
• composables/domain/governance/useGovernanceWorkflow.svelte.ts
• composables/domain/governance/useValidationQueue.svelte.ts
• composables/domain/ppr/usePPRDisplay.svelte.ts

Layer 6 — Component

• Replace existing Promise-based service calls in components with composable imports
• useRoleGuard() gates all role-sensitive affordances

Layer 7 — Test

• Unit tests for each service with mock HolochainClientServiceTag
• Store tests verifying withLoadingState transitions and cache behaviour
• Workflow service tests for each governance sequence step
• E2E Playwright tests for complete governance workflow paths

Implementation Order

Per the R&O guide's hybrid adoption strategy for existing projects:

1. Dependency foundation (Impl feat(ui): Effect-TS foundation — deps, error layer, schema layer, shared utilities #89): effect + @effect/platform — ✅ done
2. Foundation PR: Layer 4 (Error) + Layer 3 (Schema) — pure TypeScript, no DHT, fully unit-testable
3. Layer 1 base PR: copy utilities from R&O + connection.service + PersonServiceLive
4. Person domain PR: person.store + usePersonManagement composable + tests
5. Resource domain PR: ResourceServiceLive + resource.store + composables + tests
6. Governance domain PR: GovernanceServiceLive + governance store + workflow services + tests
7. PPR domain PR: PPR service methods + ppr.store + usePPRDisplay

Workflow services are implemented last — they depend on all three zome services being stable.

Acceptance Criteria

• All 7 canonical layers implemented following R&O patterns
• All DHT operations wrapped with typed E.Effect<T, DomainError> — no raw Promises in service layer
• VfActionSchema covers all 16 Rust VfAction variants exactly
• Governance workflow services correctly sequence Commitment → EconomicEvent → Claim → PPR
• useRoleGuard() gates all role-sensitive UI affordances
• Validation queue is reactive to DHT signals from other agents
• ≥80% unit test coverage on service layer; ≥70% integration coverage on stores
• bun run check, bun run test, bun run build all pass

Dependencies

• effect + @effect/platform in ui/package.json (Impl feat(ui): Effect-TS foundation — deps, error layer, schema layer, shared utilities #89)
• Person and resource zomes complete (Phase 1 done)
• Governance zome implementation (Phase 2, in progress)