# Effect service standards [#effect-service-standards]

Use this page when a contribution adds service contracts, layers, parameter
providers, calculator execution or expected error handling.

## Service boundaries [#service-boundaries]

Use Effect services and layers for tax behaviour:

* facts are provided through `Context.Service`
* parameter tables are services
* rules are `Layer`s
* calculators are Effect programs that require facts and return reports
* expected domain failures stay in the typed error channel

`@taxkit/calculators` owns reusable calculator service policy. HTTP handlers
and SDK helpers must not hide tax business logic or duplicate calculator
lookup, fact decoding, rule execution, graph assembly or expected error
shaping.

## Effect-native primitives [#effect-native-primitives]

Use Effect-native primitives when they fit:

* `Data`, `Schema`, `Schema.TaggedClass` and `Schema.TaggedError`
* `Array`, `Chunk`, `HashSet`, `HashMap`, `Record`, `Option`, `Result`,
  `Exit` and `Match`
* `Context`, `Layer`, `Config`, `ManagedRuntime` and `Command`

Do not create ad hoc tagged objects, mutable `Map` or `Set` indexes, manual
env parsing or per-request runtime wrappers when an Effect primitive owns the
pattern.

## Error handling [#error-handling]

Keep one-off `Effect.mapError`, `Effect.catchTag`, `Effect.catch` and
`Effect.catchDefect` transformations inline at the callsite. Extract a
helper only when it owns reusable policy or removes meaningful duplication.

For the full rule set, read
[Effect services](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/docs/architecture/effect-services.md).