chore(release): v0.12.1 — QA validator pipeline, fix 15 pattern content issues

Add QA validation pipeline that validates frontmatter, structure, and
TypeScript code blocks for all 309 published patterns. Fix 15 patterns
with broken code blocks (yield* outside generators, pseudocode fencing,
duplicate declarations, broken frontmatter).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: PaulJPhilp

CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.12.1] - 2026-02-10
+
+### 🔧 QA Pipeline
+- **QA Validator**: New `validator.ts` module validates frontmatter, structure, and TypeScript code blocks for all published `.mdx` patterns
+- **`qa validate` command**: New subcommand runs validation with configurable concurrency and writes per-pattern `-qa.json` result files
+- **`qa process` updated**: Now runs validation as Step 1 before status/report/repair
+
+### 🐛 Content Fixes
+- **15 pattern files fixed**: Corrected TypeScript code blocks across concurrency, schema, error-management, streams, scheduling, and tooling patterns
+  - Fixed broken frontmatter in `concurrency-fork-basics`
+  - Changed pseudocode blocks from `typescript` to `text` fencing where appropriate
+  - Wrapped `yield*` calls in proper `Effect.gen` generators inside `catchAll`, `catchTag`, `orElse` callbacks
+  - Scoped duplicate declarations in linting/type-error example blocks
+  - Fixed `await` outside async and `yield*` outside generator contexts
+
+### 📦 Dependencies
+- **`@effect-patterns/ep-admin`** 0.2.1: Added `gray-matter` for frontmatter parsing
+- **`@effect-patterns/toolkit`** 0.4.1: Added `releaseVersion` column to `effectPatterns` schema
+
+### 🛠️ Improvements
+- **`QAConfig` type**: Added `publishedPatternsDir` field, made all properties `readonly`
+- **Tagged errors**: Added `QAValidationError` and `TypeCheckError` to QA error types
+- **Pattern sync script**: New `scripts/sync-patterns-from-mdx.ts` utility
+
 ## [0.12.0] - 2026-02-10
 
 ### 🚀 First npm Publish

bun.lock

@@ -142,11 +142,12 @@ const program = Effect.gen(function* () {
 
   const raceWithFallback = primary.pipe(
     Effect.timeout("150 millis"),
-    Effect.catchAll(() => {
-      yield* Effect.log(`[PRIMARY] Timed out, using fallback`);
-
-      return fallback;
-    })
+    Effect.catchAll(() =>
+      Effect.gen(function* () {
+        yield* Effect.log(`[PRIMARY] Timed out, using fallback`);
+        return yield* fallback;
+      })
+    )
   );
 
   const fallbackResult = yield* raceWithFallback;

content/published/patterns/concurrency/concurrency-pattern-race-timeout.mdx

@@ -1,7 +1,4 @@
 ---
-lessonOrder: 1
----
-1---
 title: Fork Background Work
 id: concurrency-fork-basics
 skillLevel: beginner
@@ -143,19 +140,21 @@ Effect.runPromise(fanOut)
 ## Common Patterns
 
 ```typescript
-// Fire and forget (logging, analytics)
-yield* Effect.forkDaemon(sendAnalytics(event))
-
-// Background with timeout
-const fiber = yield* Effect.fork(longRunningTask)
-yield* Effect.sleep("5 seconds")
-yield* Fiber.interrupt(fiber) // Cancel if still running
-
-// Parallel fan-out/fan-in
-const fibers = yield* Effect.forEach(items, (item) =>
-  Effect.fork(processItem(item))
-)
-const results = yield* Fiber.joinAll(fibers)
+Effect.gen(function* () {
+  // Fire and forget (logging, analytics)
+  yield* Effect.forkDaemon(sendAnalytics(event))
+
+  // Background with timeout
+  const fiber = yield* Effect.fork(longRunningTask)
+  yield* Effect.sleep("5 seconds")
+  yield* Fiber.interrupt(fiber) // Cancel if still running
+
+  // Parallel fan-out/fan-in
+  const fibers = yield* Effect.forEach(items, (item) =>
+    Effect.fork(processItem(item))
+  )
+  const results = yield* Fiber.joinAll(fibers)
+})
 ```
 
 ## Best Practices

content/published/patterns/concurrency/getting-started/concurrency-fork-basics.mdx

@@ -294,24 +294,27 @@ const program = Effect.gen(function* () {
   });
 
   const updateAndNotify = (newValue: number) =>
-    Ref.modify(observedState, (current) => {
-      const notification: Notification = {
-        oldValue: current.value,
-        newValue,
-        timestamp: new Date(),
-      };
+    Effect.gen(function* () {
+      const notification = yield* Ref.modify(observedState, (current) => {
+        const n: Notification = {
+          oldValue: current.value,
+          newValue,
+          timestamp: new Date(),
+        };
+        return [
+          n,
+          {
+            value: newValue,
+            lastChange: n.timestamp,
+          },
+        ];
+      });
 
       yield* Effect.log(
-        `[NOTIFY] ${current.value} → ${newValue} at ${notification.timestamp.toISOString()}`
+        `[NOTIFY] ${notification.oldValue} → ${newValue} at ${notification.timestamp.toISOString()}`
       );
 
-      return [
-        notification,
-        {
-          value: newValue,
-          lastChange: notification.timestamp,
-        },
-      ];
+      return notification;
     });
 
   // Trigger changes

content/published/patterns/concurrency/state-management-pattern-synchronized-ref.mdx

@@ -39,7 +39,7 @@ Then, compare instances using the `Equal.equals(a, b)` function.
 
 In JavaScript, comparing two non-primitive values with `===` checks for _referential equality_. It only returns `true` if they are the exact same instance in memory. This means two objects with identical contents are not considered equal, which is a common source of bugs.
 
-```typescript
+```text
 { a: 1 } === { a: 1 } // false!
 ```
 

content/published/patterns/core-concepts/comparing-data-by-value-with-structural-equality.mdx

@@ -245,19 +245,21 @@ const program = Effect.gen(function* () {
 
     for (let i = 1; i <= 3; i++) {
       const result = yield* networkCall.pipe(
-        Effect.catchTag("NetworkError", (error) => {
-          lastError = error;
+        Effect.catchTag("NetworkError", (error) =>
+          Effect.gen(function* () {
+            lastError = error;
 
-          yield* Effect.log(
-            `[RETRY] Attempt ${i} failed: ${error.statusCode}`
-          );
+            yield* Effect.log(
+              `[RETRY] Attempt ${i} failed: ${error.statusCode}`
+            );
 
-          if (i < 3) {
-            yield* Effect.log(`[RETRY] Waiting before retry...`);
-          }
+            if (i < 3) {
+              yield* Effect.log(`[RETRY] Waiting before retry...`);
+            }
 
-          return Effect.fail(error);
-        })
+            return yield* Effect.fail(error);
+          })
+        )
       ).pipe(
         Effect.tap(() => Effect.log(`[SUCCESS] Connected on attempt ${i}`))
       ).pipe(

content/published/patterns/error-management/error-handling-pattern-propagation.mdx

@@ -114,7 +114,7 @@ const exponentialBackoffWithJitter = (config: BackoffConfig) => {
     const withJitter = exponential * (0.5 + Math.random() * 0.5); // ±50% jitter
     const capped = Math.min(withJitter, config.maxDelayMs);
 
-    yield* Effect.log(
+    console.log(
       `[BACKOFF] Attempt ${attempt + 1}: ${Math.round(capped)}ms delay`
     );
 

content/published/patterns/error-management/scheduling-pattern-exponential-backoff.mdx

@@ -94,13 +94,13 @@ const fetchUser = (id: string): Effect.Effect<User, FetchError | ParseError> =>
 ## Key Insight
 
 With Promises:
-```typescript
+```text
 // You have to read the implementation to know what might fail
 async function doSomething(): Promise<Result> { ... }
 ```
 
 With Effect:
-```typescript
+```text
 // The type tells you everything
 function doSomething(): Effect<Result, NetworkError | ParseError, Database> { ... }
 //                               ^success  ^errors                   ^dependencies

content/published/patterns/getting-started/getting-started-effect-vs-promise.mdx

@@ -300,10 +300,12 @@ const program = Effect.gen(function* () {
 
   const fallbackChain = callEndpoint("primary", true).pipe(
     Effect.orElse(() => callEndpoint("secondary", false)),
-    Effect.orElse(() => {
-      yield* Effect.log(`[FALLBACK] Using cached data`);
-      return Effect.succeed(endpoints.cache);
-    })
+    Effect.orElse(() =>
+      Effect.gen(function* () {
+        yield* Effect.log(`[FALLBACK] Using cached data`);
+        return endpoints.cache;
+      })
+    )
   );
 
   const result = yield* fallbackChain;
@@ -470,10 +472,12 @@ const createHealthAwareRetry = (config: {
       return healthy;
     }).pipe(
       Effect.timeout(Duration.millis(config.healthCheckTimeoutMs)),
-      Effect.catchAll(() => {
-        yield* Effect.log("[HEALTH] Check timed out, assuming unhealthy");
-        return Effect.succeed(false);
-      })
+      Effect.catchAll(() =>
+        Effect.gen(function* () {
+          yield* Effect.log("[HEALTH] Check timed out, assuming unhealthy");
+          return false;
+        })
+      )
     );
 
     return performHealthCheck;