opencode-effect-enforcer 0.2.0

package/skills/effect-typeclass-design/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: effect-typeclass-design
+description: Implement typeclasses with curried signatures and dual APIs for both data-first and data-last usage
+---
+
+# Typeclass Design Skill
+
+Use this skill when implementing typeclasses that provide reusable abstractions across multiple types.
+
+## Pattern: Curried Typeclass Functions
+
+All typeclass functions must be **fully curried** to enable partial application:
+
+```typescript
+import { Duration } from 'effect';
+
+declare interface Durable<A> {
+	readonly getDuration: (self: A) => Duration.Duration;
+}
+
+// Create a typeclass function that takes the typeclass instance first,
+// then curries out all other parameters
+export const isMoreThan =
+	<A>(D: Durable<A>) =>
+	(minimum: Duration.Duration) =>
+	(self: A): boolean => {
+		const current = D.getDuration(self);
+		return Duration.isGreaterThanOrEqualTo(current, minimum);
+	};
+```
+
+## Pattern: Dual APIs
+
+Provide both **data-first** (uncurried) and **data-last** (curried) variants using `Function.dual`:
+
+```typescript
+import { Duration } from 'effect';
+import * as Function from 'effect/Function';
+
+declare interface Durable<A> {
+	readonly getDuration: (self: A) => Duration.Duration;
+}
+
+export const isMoreThan = <A>(D: Durable<A>) =>
+	Function.dual<
+		// Data-last (curried) - pipe-friendly
+		(minimum: Duration.Duration) => (self: A) => boolean,
+		// Data-first (uncurried) - direct call
+		(self: A, minimum: Duration.Duration) => boolean
+	>(
+		2, // Number of arguments for data-first form
+		(self: A, minimum: Duration.Duration): boolean => {
+			const current = D.getDuration(self);
+			return Duration.isGreaterThanOrEqualTo(current, minimum);
+		}
+	);
+```
+
+## Usage Patterns
+
+The dual API enables both styles:
+
+```typescript
+import { pipe } from 'effect/Function';
+import * as Duration from 'effect/Duration';
+import * as Function from 'effect/Function';
+
+declare interface Durable<A> {
+	readonly getDuration: (self: A) => Duration.Duration;
+}
+
+declare const isMoreThan: <A>(D: Durable<A>) => {
+	(minimum: Duration.Duration): (self: A) => boolean;
+	(self: A, minimum: Duration.Duration): boolean;
+};
+
+declare interface Appointment {
+	duration: Duration.Duration;
+}
+
+declare const Appointment: {
+	Durable: Durable<Appointment>;
+};
+
+declare const appointment: Appointment;
+declare const appointments: Appointment[];
+
+// Data-first: Direct function call
+const hasMinimum = isMoreThan(Appointment.Durable)(
+	appointment,
+	Duration.hours(1)
+);
+
+// Data-last: Pipe-friendly
+const hasMinimum2 = pipe(
+	appointment,
+	isMoreThan(Appointment.Durable)(Duration.hours(1))
+);
+
+// Partial application for filtering
+const longAppointments = appointments.filter(
+	isMoreThan(Appointment.Durable)(Duration.hours(1))
+);
+```
+
+## Complete Typeclass Example
+
+```typescript
+import { Duration, Order } from 'effect';
+import * as Function from 'effect/Function';
+
+/**
+ * Typeclass for types that have a duration.
+ */
+export interface Durable<A> {
+	readonly getDuration: (self: A) => Duration.Duration;
+	readonly setDuration: (self: A, duration: Duration.Duration) => A;
+}
+
+/**
+ * Create a Durable instance.
+ */
+export const make = <A>(
+	getDuration: (self: A) => Duration.Duration,
+	setDuration: (self: A, duration: Duration.Duration) => A
+): Durable<A> => ({
+	getDuration,
+	setDuration
+});
+
+/**
+ * Check if duration is more than minimum.
+ */
+export const isMoreThan = <A>(D: Durable<A>) =>
+	Function.dual<
+		(minimum: Duration.Duration) => (self: A) => boolean,
+		(self: A, minimum: Duration.Duration) => boolean
+	>(2, (self: A, minimum: Duration.Duration): boolean =>
+		Duration.isGreaterThanOrEqualTo(D.getDuration(self), minimum)
+	);
+
+/**
+ * Order by duration.
+ */
+export const OrderByDuration = <A>(D: Durable<A>): Order.Order<A> =>
+	Order.mapInput(Duration.Order, (self: A) => D.getDuration(self));
+```
+
+## When to Use
+
+- Creating reusable abstractions (Schedulable, Durable, Priceable)
+- Implementing operations that work across multiple types
+- Providing composable, pipe-friendly APIs
+- Enabling partial application for filtering/mapping
+
+## Key Principles
+
+1. **Curry everything** - Enable partial application
+2. **Dual APIs always** - Support both usage styles
+3. **Typeclass first** - First parameter is always the typeclass instance
+4. **Type lambda for HKT** - Use TypeLambda pattern when needed

package/skills/effect-wide-events/Article.md

@@ -0,0 +1,66 @@
+# Logging Sucks - Wide Events & Observability
+
+> **Source**: https://loggingsucks.com/
+> **Author**: Boris Tane
+
+## Core Problem
+
+Traditional logging is fundamentally broken for modern distributed systems. A single user request might touch 15 services, 3 databases, 2 caches, and a message queue, yet logs remain structured around monolithic, single-server assumptions.
+
+The central issue: logs optimize for writing, not querying. Developers emit convenient `console.log()` statements without considering how teams will search them during incidents.
+
+## Key Terminology
+
+**Structured Logging**: Key-value formatted output (typically JSON) replacing plain-text strings.
+
+**Cardinality**: The number of unique values a field can contain. User IDs have high cardinality; HTTP methods have low cardinality.
+
+**Dimensionality**: The field count per log event. More fields enable more sophisticated queries.
+
+**Wide Events/Canonical Log Lines**: One comprehensive event per request, with all context attached instead of scattered multi-line outputs.
+
+## The OpenTelemetry Misconception
+
+OpenTelemetry functions as a protocol and SDK for standardizing telemetry collection. However, it does not:
+
+- Determine what gets logged
+- Add business context automatically
+- Fix poor instrumentation practices
+
+OpenTelemetry is a delivery mechanism. It doesn't know critical business context. You have to tell it.
+
+## Wide Events Implementation
+
+Rather than multiple debug statements throughout code execution, teams should emit a single enriched event containing:
+
+- **Request metadata**: ID, timestamp, service name
+- **User context**: Subscription tier, account age, lifetime value
+- **Business data**: Cart contents, feature flags enabled
+- **Performance metrics**: Latency, attempt counts
+- **Error details**: If applicable
+
+This allows single queries to answer complex questions: "Show checkout failures for premium users where the new flow was enabled."
+
+## Tail Sampling Strategy
+
+Managing observability costs requires intelligent sampling:
+
+- **100% retention**: All errors, slow requests (above p99), VIP users
+- **Partial retention**: Random sampling of successful, fast requests (1-5%)
+
+This preserves critical debugging information while controlling infrastructure expenses.
+
+## The Transformation
+
+Wide events shift debugging from archaeological text searching to structured analytics—replacing "grep through 50 services hoping for clues" with targeted data queries returning results instantaneously.
+
+## Summary
+
+| Traditional Logs      | Wide Events                          |
+| --------------------- | ------------------------------------ |
+| Many small log lines  | One comprehensive event per request  |
+| Scattered context     | All context attached to single event |
+| Low dimensionality    | High dimensionality                  |
+| Text search (grep)    | Structured queries                   |
+| Hard to correlate     | Easy to correlate                    |
+| Optimized for writing | Optimized for querying               |

package/skills/effect-wide-events/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: effect-wide-events
+description: Conceptual guide to wide events (canonical log lines) for observability. Use when thinking about instrumentation strategy, span annotations, or designing what context to capture.
+---
+
+<wide-events>
+
+<philosophy>
+traditional := many(log-lines) → grep(services) → hope
+wide        := one(event) → query(structured) → answer
+
+optimize(querying) ∧ ¬optimize(writing)
+</philosophy>
+
+<current-practice>
+implementation := OTel spans + annotations
+wide-events    := mental-model for annotation strategy
+
+annotate(span, context) where context = {
+business ∪ user ∪ technical ∪ outcome
+}
+
+effect-api    := Effect.annotateCurrentSpan ∨ Effect.annotateLogs
+queryable-via := annotations  ⊄  log-message-args
+// extra log-message args → message body, not auto-indexed dimensions
+
+execution-plan := Effect.withExecutionPlan ∨ Stream.withExecutionPlan
+attempt-events := onEvent(AttemptStart | AttemptSuccess | AttemptFailure)
+// AttemptFailure.cause retains typed failures, defects, and interruption
+// every AttemptStart has exactly one terminal event; observer defects are isolated
+</current-practice>
+
+<dimensionality>
+wide-event.fields := {
+  identity:    {traceId, spanId, service, operation}
+  user:        {userId, accountTier, accountAge, lifetimeValue}
+  business:    {featureFlags, experimentGroup, cartValue}
+  performance: {durationMs, dbQueryCount, cacheHitRate, retryCount}
+  outcome:     {success, errorCode, httpStatus}
+}
+
+high-dimensionality → better-queryability
+high-cardinality(userId) → acceptable
+</dimensionality>
+
+<anti-patterns>
+scattered-logs     := console.log("step1") >> console.log("step2") >> ...
+low-dimensionality := span.set("success", true) ∧ |fields| < 5
+technical-only     := {http.status, db.queries} ∧ ¬{user, business}
+</anti-patterns>
+
+<correct-pattern>
+span.setAttributes({
+  "request.operation", "user.id", "user.tier",
+  "cart.items", "cart.value", "feature.*",
+  "db.query_count", "cache.hit_rate",
+  "request.success"
+})
+
+∀ span → attach(identity ∪ user ∪ business ∪ performance ∪ outcome)
+</correct-pattern>
+
+<tail-sampling>
+retain(100%) := errors ∨ slow(>p99) ∨ vip
+retain(1-5%) := success ∧ fast
+</tail-sampling>
+
+<queryability-test>
+before(instrument) → verify(answerable({
+  "failures where tier=premium ∧ feature.new_flow=true"
+  "p99(latency) group by tier"
+  "errors group by featureFlags"
+  "full context for user X incident"
+}))
+
+¬queryable → ¬enough-context
+</queryability-test>
+
+<terminology>
+cardinality    := |unique values| (userId=high, httpMethod=low)
+dimensionality := |fields per event| (more → better)
+wide-event     := canonical-log-line := one comprehensive record
+</terminology>
+
+<when-to-apply>
+deciding(span-annotations)
+reviewing(instrumentation-coverage)
+debugging(incidents) → "what context was missing?"
+planning(new-service-observability)
+choosing(fields-to-index)
+</when-to-apply>
+
+</wide-events>
+
+Reference: See `Article.md` for full article by Boris Tane (loggingsucks.com)