Chore/effect rc108 alchemy beta72

.context/effect/.agents/AGENTS.md

@@ -0,0 +1,163 @@
+This is the Effect library repository, focusing on functional programming patterns and effect systems in TypeScript.
+
+## Overview
+
+- The git base branch is `main`.
+- Use `pnpm` as the package manager.
+- Keep changes focused and follow established patterns in the repository.
+- Before writing code, read the relevant files in `./.patterns/` and inspect similar existing code.
+
+## Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+## Workflow
+
+1. Inspect nearby implementation, tests, and pattern docs before editing.
+2. Prefer existing abstractions and conventions over introducing new ones.
+3. For ad hoc runnable code, create a temporary file in `scratchpad/`, run it with `node scratchpad/<file>.ts`, and delete it when done.
+   The local runtime is Node 24, which can run TypeScript files directly; use plain `node` for local TypeScript probes instead of `tsx` unless `node` fails.
+4. Run the validation appropriate to the change type.
+5. Report which validation commands were run and any commands that could not be run.
+
+## Validation
+
+Use the narrowest validation that still covers the change:
+
+| Change type                      | Validation                                                                         |
+| -------------------------------- | ---------------------------------------------------------------------------------- |
+| Code changes                     | `pnpm lint-fix`, targeted `pnpm test --run <test_file.ts>`, `pnpm check`           |
+| Tests-only changes               | `pnpm lint-fix`, targeted `pnpm test --run <test_file.ts>`, `pnpm check`           |
+| Type-level/API type changes      | Targeted `pnpm test-types <filename>`, plus `pnpm check` when source types changed |
+| JSDoc text/category/link changes | `pnpm lint`                                                                        |
+| JSDoc example changes            | `pnpm lint`; root `pnpm doctest --run <files>`          |
+| Docs-only changes                | `pnpm lint-fix`; no tests required unless examples or code changed                 |
+
+Never run the whole test suite. A bare `pnpm test` or `pnpm doctest` runs every package in watch mode and will not
+exit; always pass `--run` and the specific test files covering your change. CI runs the full suite
+on push, so leave that to CI.
+
+## Bundle Size Preview
+
+When asked to show bundle-size impact for a commit, use the existing bundle comparison workflow:
+
+1. For the latest commit, run `pnpm bundle-compare HEAD~1`.
+   For another base, run `pnpm bundle-compare <base-ref>`.
+2. Read the Markdown report from `tmp/bundle-stats.txt` and summarize the non-zero differences.
+3. Leave `tmp/bundle-base` in place unless cleanup is requested. To clean it up, run `git worktree remove --force tmp/bundle-base`.
+
+## Coding Patterns
+
+Read `.patterns/effect.md` before changing Effect code. In particular:
+
+- Prefer `Effect.fnUntraced` over functions that only return `Effect.gen`.
+- Prefer class syntax for `Context.Service`.
+- Do not use `async` / `await` or `try` / `catch`; use Effect APIs such as `Effect.gen`, `Effect.fnUntraced`, and `Effect.tryPromise`.
+- Do not use `Date.now` or `new Date`; use `Clock`, and use `TestClock` in tests.
+
+## Testing
+
+Read `.patterns/testing.md` before writing or changing tests.
+
+- Run only the tests covering the files you changed.
+- From the repository root, run an affected package with `pnpm --filter effect test --run` only when package-wide coverage is necessary.
+- Prefer a single test file, using a path relative to the package: `pnpm --filter effect test --run test/Option.test.ts`.
+  Replace the package name and test path with those covering your changed files, and narrow further with `-t "<test name>"` when useful.
+- Test files are located in `packages/*/test/`.
+- Main Effect library tests are in `packages/effect/test/`.
+- Use `it.effect` for Effect-returning tests.
+- `it.effect` and `it.live` already provide and close a `Scope` for each test; do not wrap test bodies in `Effect.scoped`.
+- Use regular `it` for pure synchronous tests.
+- Do not use `Effect.runSync` in tests.
+- Do not use `expect` from Vitest; use `assert` from `@effect/vitest`.
+- Type-level tests are in `packages/*/typetest/` and run with `pnpm test-types <filename>`.
+
+## Documentation
+
+- For AI documentation, read `ai-docs/README.md` very carefully before writing examples.
+- AI documentation changes may include explanatory comments when useful.
+- For public JSDoc categories and example best practices, read `.patterns/jsdoc.md`.
+- Mark runnable TypeScript examples with `````ts import.meta.vitest``. Leave examples that register Vitest tests or suites
+  as plain `````ts`` fences because the doctest collector executes runnable snippets inside tests; invoke registration
+  APIs directly to show their intended top-level usage.
+- Prefer direct trailing value assertions such as `operation() // => Option.some(1)`. Keep bindings only for reuse or meaningful multi-step setup, separate later assertion blocks with a blank line, use dense expected arrays such as `[1, 2]`, and keep a call on one line when the complete line is at most 120 characters.
+- Assert semantic values rather than console formatting. Preserve `import.meta.vitest` on type-level examples without adding tautological runtime assertions.
+- Keep marked examples self-contained, deterministic, bounded, and free of external-service dependencies. Await asynchronous work.
+- Run `pnpm doctest --run <source files>` from the repository root to execute changed examples.
+
+## Generated Files
+
+Do not hand-edit generated files. Run the appropriate generator instead.
+
+- `index.ts` barrel files are generated; run `pnpm codegen` after adding or removing modules.
+
+## Changesets
+
+Create a changeset in `.changeset/` for runtime behavior changes or exported type/API changes:
+
+```md
+---
+"package-name": patch/minor/major
+---
+
+A description of the change.
+```
+
+Tests-only changes, internal refactors, docs-only changes, and JSDoc-only maintenance may skip changesets by maintainer decision.

.context/effect/.agents/skills/jsdocs/SKILL.md

@@ -39,7 +39,7 @@ Use a normal multiline JSDoc comment in TypeScript source:
  *
  * Optional prose explaining the example.
  *
- * ```ts
+ * ```ts import.meta.vitest
  * const result = example()
  * ```
  *
@@ -126,6 +126,63 @@ Use a normal multiline JSDoc comment in TypeScript source:
 - For low-level public values, prefer accurate categories such as `symbols`,
   `type IDs`, or `prototypes` over compensating with verbose descriptions.
 
+## Example quality
+
+Examples are optional. They should demonstrate:
+
+- behavior or constraints that are not clear from the signature;
+- meaningful composition with other public APIs;
+- a realistic use case supported by repository tests or call sites; or
+- useful type inference, narrowing, or overload behavior.
+
+A good example:
+
+- focuses on the documented API and includes only the context needed to
+  understand it;
+- is a complete, self-contained TypeScript module without placeholders or
+  omitted setup;
+- imports public APIs rather than internal modules or unrelated test helpers;
+- uses stable, deterministic, bounded behavior and does not require network
+  access, external services, timing assumptions, randomness, or machine-specific
+  state;
+- demonstrates the meaningful result, with a concise expected-value comment
+  when useful; and
+- uses explanatory prose only when the code cannot communicate an important
+  choice or caveat on its own.
+
+### Executable examples
+
+- Mark runnable TypeScript fences with `import.meta.vitest`. Run changed examples from the repository root with `pnpm doctest --run <source files>`.
+- Write each marked example as a complete isolated module. Import public APIs, define every runtime value, await asynchronous work, and keep execution deterministic and bounded.
+- Prefer `operation() // => expected` over introducing a result binding used only by the assertion. Retain bindings for reuse, mutation, identity checks, or meaningful multi-step setup, and insert a blank line before a separate assertion block.
+- Keep direct assertions on one line up to 120 characters. Use dense expected arrays such as `[1, 2]` and semantic Effect values such as `Option.some(1)` rather than console formatting.
+- Preserve `import.meta.vitest` for type-level examples, but do not add tautological runtime assertions to them.
+- Leave examples that register Vitest tests or suites as plain `````ts`` fences because the doctest collector executes
+  runnable snippets inside tests. Call the registration API directly to show its intended top-level usage.
+- Keep documentation-only snippets as plain `````ts`` fences.
+
+When reviewing existing examples:
+
+1. Derive the example's use case and behavior from repository evidence. Inspect
+   the declaration, implementation, tests, call sites, and related APIs. Do not
+   invent a scenario merely to retain an example.
+2. Keep a correct, clear, high-value example without gratuitous rewriting.
+3. Fix or replace an example when repository evidence supports a concise,
+   valuable version.
+4. Remove an example when it is trivial, misleading, contrived, or requires more
+   scaffolding than the insight justifies. Also remove it when a good replacement
+   would require guessing at a use case.
+
+Prefer concise trailing `// =>` assertions that keep the meaningful result visible;
+public documentation should not look like a test suite. Type-level examples may demonstrate inference or assignability
+without runtime assertions. For lazy APIs such as `Effect`, execute enough of the
+program to demonstrate the behavior unless the example's value is specifically
+type-level or construction-oriented.
+
+If an example review exposes a likely implementation or type-definition bug,
+do not change runtime or API code as part of the documentation pass. Report the
+finding and do not present the suspected behavior as recommended usage.
+
 ## Tag rules
 
 When multiple tags are present, keep them in this order:
@@ -198,6 +255,6 @@ When refining an existing public API module, always do a dedicated `**Gotchas**`
 
 Run the narrowest validation that matches the change:
 
-- For JSDoc or example changes in a package with generated docs, run `pnpm docgen` from that package directory.
+- For runnable JSDoc example changes, run `pnpm doctest --run <source files>` from the repository root.
 - Run `pnpm lint` because the linter includes the custom rule that checks public API JSDoc.
 - Do not run broad validation for prose-only skill edits.

.context/effect/.changeset/config.json

@@ -1,7 +1,8 @@
 {
-  "$schema": "https://unpkg.com/@changesets/config@1.6.4/schema.json",
+  "$schema": "https://unpkg.com/@changesets/config@4.0.0-next.8/schema.json",
   "changelog": ["@changesets/changelog-github", { "repo": "Effect-TS/effect" }],
   "commit": false,
+  "format": false,
   "linked": [],
   "access": "restricted",
   "baseBranch": "main",
@@ -14,7 +15,35 @@
   "fixed": [
     [
       "effect",
-      "@effect/*"
+      "@effect/ai-anthropic",
+      "@effect/ai-openai",
+      "@effect/ai-openai-compat",
+      "@effect/ai-openrouter",
+      "@effect/atom-react",
+      "@effect/atom-solid",
+      "@effect/atom-vue",
+      "@effect/docgen",
+      "@effect/doctest",
+      "@effect/openapi-generator",
+      "@effect/opentelemetry",
+      "@effect/platform-browser",
+      "@effect/platform-bun",
+      "@effect/platform-deno",
+      "@effect/platform-node",
+      "@effect/platform-node-shared",
+      "@effect/sql-clickhouse",
+      "@effect/sql-d1",
+      "@effect/sql-libsql",
+      "@effect/sql-mssql",
+      "@effect/sql-mysql2",
+      "@effect/sql-pg",
+      "@effect/sql-pglite",
+      "@effect/sql-sqlite-bun",
+      "@effect/sql-sqlite-do",
+      "@effect/sql-sqlite-node",
+      "@effect/sql-sqlite-react-native",
+      "@effect/sql-sqlite-wasm",
+      "@effect/vitest"
     ]
   ],
   "snapshot": {