{"owner":"Effect-TS","repo":"effect","hasSkills":true,"totalSkillsCount":75,"totalTokensCount":48739,"categories":["root-instruction","anthropic-skill","plugin-manifest"],"hasMcp":false,"mcpConfig":null,"found":[".agents/AGENTS.md",".agents/skills/ai-docs/SKILL.md",".agents/skills/bundle-analysis/SKILL.md",".agents/skills/changesets/SKILL.md",".agents/skills/changesets/authoring.md",".agents/skills/ci-maintenance/SKILL.md",".agents/skills/ci-maintenance/privileged-workflows.md",".agents/skills/dependency-maintenance/SKILL.md",".agents/skills/dependency-maintenance/coordinated-upgrades.md",".agents/skills/dependency-maintenance/manifest-roles.md",".agents/skills/effect-development/SKILL.md",".agents/skills/jsdocs/SKILL.md",".agents/skills/jsdocs/categories.md",".agents/skills/jsdocs/declarations.md",".agents/skills/jsdocs/examples.md",".agents/skills/migration-guidance/SKILL.md",".agents/skills/migration-guidance/annotations.md",".agents/skills/migration-guidance/generation.md",".agents/skills/package-development/SKILL.md",".agents/skills/package-development/dependencies.md",".agents/skills/package-development/publishing.md",".agents/skills/package-development/registration.md",".agents/skills/performance-analysis/SKILL.md",".agents/skills/performance-analysis/runtime.md",".agents/skills/performance-analysis/types.md",".agents/skills/pull-requests/SKILL.md",".agents/skills/test-development/SKILL.md",".agents/skills/test-development/displayed-types.md",".agents/skills/test-development/runtime.md",".agents/skills/test-development/types.md",".agents/skills/vendored-assets/SKILL.md",".agents/skills/vendored-assets/browser-assets.md","packages/ai/anthropic/README.md","packages/ai/cloudflare/README.md","packages/ai/openai-compat/README.md","packages/ai/openai/README.md","packages/ai/openrouter/README.md","packages/ai/typesafe/README.md","packages/atom/react/README.md","packages/atom/solid/README.md","packages/atom/vue/README.md","packages/effect/README.md","packages/effect/runtimeperf/README.md","packages/effect/runtimeperf/suites/compiler-rebuild/README.md","packages/effect/runtimeperf/suites/schema-checked-sources/README.md","packages/effect/runtimeperf/suites/schema-construction/README.md","packages/effect/typeperf/README.md","packages/opentelemetry/README.md","packages/platform/browser/README.md","packages/platform/bun/README.md","packages/platform/deno/README.md","packages/platform/node-shared/README.md","packages/platform/node/README.md","packages/platform/node/test/cluster-integration/README.md","packages/sql/clickhouse/README.md","packages/sql/d1/README.md","packages/sql/libsql/README.md","packages/sql/mssql/README.md","packages/sql/mysql2/README.md","packages/sql/pg/README.md","packages/sql/pg/benchmark/README.md","packages/sql/pglite/README.md","packages/sql/sqlite-bun/README.md","packages/sql/sqlite-do/README.md","packages/sql/sqlite-node/README.md","packages/sql/sqlite-react-native/README.md","packages/sql/sqlite-wasm/README.md","packages/tools/api-diff/README.md","packages/tools/bundle/README.md","packages/tools/docgen/README.md","packages/tools/doctest/README.md","packages/tools/graphql-generator/README.md","packages/tools/npm-promote/README.md","packages/tools/openapi-generator/README.md","packages/vitest/README.md"],"skills":{".agents/AGENTS.md":"This is the Effect TypeScript monorepo. The git base branch is `main`; use `pnpm` from the repository root.\n\n## Layout\n\n- Core library source, runtime tests, and type tests are in `packages/effect/src`, `packages/effect/test`, and\n `packages/effect/typetest`.\n- Other package families include `packages/ai`, `packages/atom`, `packages/platform`, `packages/sql`, and\n `packages/tools`; standalone packages also live directly under `packages`.\n- Package tests and type tests live beside source in `test` and `typetest` directories.\n- AI documentation sources are in `ai-docs/src`.\n- Changesets are in `.changeset`.\n- Migration sources (v3-to-v4) are in `migration/annotations`.\n- Inspect nearby code before editing.\n\n## Validation\n\nUse the narrowest validation that covers the change:\n\n| Change type | Validation |\n| ---------------------------------- | ---------------------------------------------------------------------------------- |\n| Runtime source or test changes | `pnpm lint-fix`, targeted `pnpm test --run `, `pnpm check` |\n| Type-system behavior or type tests | Targeted `pnpm test-types `, plus `pnpm check` when source types changed |\n| JSDoc text/category/link changes | `pnpm jsdocs --check`, `pnpm lint` |\n| JSDoc example changes | `pnpm jsdocs --check`, `pnpm lint`, root `pnpm doctest --run ` |\n| Docs-only changes | `pnpm lint-fix`; no tests unless examples or code changed |\n\nChoose coverage from the contract being changed. Runtime tests cover executed\nbehavior. Tstyche tests cover intended compiler behavior such as inference,\nassignability, rejection, or displayed public types. An ordinary source edit or\nexported declaration is covered by `pnpm check` unless compiler behavior is part\nof the task.\n\nNever run bare `pnpm test` or `pnpm doctest`; both start the full suite in watch mode. Always pass `--run` and the\nspecific files covering the change. CI runs the full suite.\n\nFor an ad hoc runnable probe, create `scratchpad/.ts`, run it with plain `node`, and remove it when finished.\n\nReport any commands that could not be run.\n\n## Generated Files\n\nDo not edit generated output directly.\n\nSome `index.ts` sections marked with `@barrel` are generated. Do not edit those\nsections manually; update their source modules and run `pnpm codegen`.\nHand-maintained `index.ts` files and unmarked sections are not covered by this\nrule.\n\n`LLMS.md` is generated from `ai-docs/src`, and `migration/v3-to-v4.md` is\ngenerated from `migration/annotations`. Update checked-in third-party assets\nthrough their generator or documented import procedure.\n",".agents/skills/ai-docs/SKILL.md":"---\nname: ai-docs\ndescription: AI documentation. Use when editing ai-docs/src or regenerating LLMS.md.\n---\n\nRead `ai-docs/README.md`; it owns source structure, style, examples, generation,\nand changeset policy.\n\n1. Inspect neighboring source examples and the relevant current `LLMS.md`.\n2. Edit sources under `ai-docs/src`, then run `pnpm ai-docgen`.\n3. Review generated output for ordering, missing content, and unrelated changes.\n4. Run applicable root validation.\n\nThe task is complete when sources and generated output agree, every generated\ndifference is explained, TypeScript checks pass when examples or fixtures\nchange, and applicable checks pass or are reported as not runnable.\n",".agents/skills/bundle-analysis/SKILL.md":"---\nname: bundle-analysis\ndescription: Bundle analysis. Use when measuring current bundle size, comparing stable or selected fixtures, inspecting composition, or cleaning retained comparison state.\n---\n\nRead `packages/tools/bundle/README.md`, then select one workflow:\n\n- **Stable comparison:** `pnpm bundle-compare `. Use `HEAD~1` for the\n latest commit. Read `tmp/bundle-stats.txt` and report non-zero differences.\n- **Selected comparison:** `pnpm bundle-compare-selected --base \n scratchpad/.ts`. Use only user-named or investigation-local fixtures;\n keep temporary fixtures out of the stable corpus.\n- **Composition:** `pnpm bundle-analyze scratchpad/.ts`. Read raw data\n first and report the largest modules, dependency groups, and surprising\n inclusions. Its readable-name output is not an exact size measurement.\n- **Current size:** Build immediately before the direct bundle report so Effect\n packages resolve from current `dist` output.\n- **Cleanup:** Stable comparisons retain `tmp/bundle-base` for reuse unless\n cleanup is requested. Remove selected-comparison state retained with\n `--keep-base` after its final use. Verify cleanup without disturbing unrelated\n worktrees.\n\nThe task is complete when the selected artifact is inspected, requested size or\ncomposition findings are reported, generated paths are named, and comparison\nstate follows the selected workflow's retention policy.\n",".agents/skills/changesets/SKILL.md":"---\nname: changesets\ndescription: Concise PR finalization changesets. Use when implementation scope is complete and focused validation has finished to classify release impact, consolidate the PR's existing changeset, or write its consumer release note.\n---\n\nTreat a changeset as the release note for the complete PR, not as a log of work\nperformed along the way. Finalize it after the current implementation scope and\nfocused validation are complete.\n\n## Workflow\n\n1. Inspect the complete diff from the merge base, including changeset files\n already introduced by the PR, and identify directly affected published\n packages.\n2. Classify impact across source types, runtime behavior, entrypoints, required\n services, lifecycle, and persisted or wire data.\n3. Perform the breaking audit below.\n4. Record a reason no changeset is required, or update the PR's existing\n changeset. Create one only when the PR does not have one. When required, read\n [authoring.md](authoring.md).\n5. Validate package names, frontmatter, bump policy, and a one-sentence\n consumer-facing description, longer only for breaks or required migration.\n\nDo not include unrelated worktree changes.\n\n## PR-level consolidation\n\nThe default is one changeset file per PR. One file can name several packages and\nsummarize several related fixes or additions. Successive prompts, commits, and\nsubtasks within the same PR update that file. If implementation resumes after a\nchangeset was drafted, revise it during the next finalization pass.\n\nUse separate files only when a maintainer requests the split or the PR contains\nindependent changes that need separate release notes.\n\n## Requirement\n\nCreate a changeset for observable runtime behavior changes, including bug\nfixes; exported value or public type changes; entrypoint or export-map changes;\nchanges to required services, errors, ownership, defaults, or lifecycle; and\npersisted, serialization, protocol, or wire-format changes.\n\nTests-only changes, behavior-preserving internal refactors, documentation or\nJSDoc maintenance, and unpublished tooling normally do not need one. When\nunclear, inspect exports and consumer-visible declarations rather than inferring\nfrom source location.\n\n## Breaking Audit\n\nA change is breaking when valid existing consumer code, configuration, or data\nmust change to keep compiling or behaving according to the previous contract.\nAudit every surface:\n\n- **Names and locations:** exports, entrypoints, compatibility exports, and\n module paths.\n- **Call compatibility:** parameters, accepted inputs, overload resolution,\n generic parameters, and defaults.\n- **Result compatibility:** return and error types, output narrowing, members,\n inference, and required services.\n- **Runtime contracts:** defaults, failures, interruption, concurrency,\n ordering, resource lifetime, acquisition, cleanup, and mutation.\n- **Data compatibility:** persisted schemas, encodings, database layouts,\n protocols, and wire formats.\n\nAdditive exports, optional parameters, and behavior-preserving implementations\nare normally non-breaking. A fix restoring the documented contract is normally\nnon-breaking but still needs a changeset when its operational impact is\nconsumer-visible. Verify representative existing calls when overload ordering,\nstructural assignability, or inference makes compatibility uncertain. API diff\noutput is mechanical evidence, not a semantic-version decision.\n\nThe task is complete when every affected contract and published package is\naccounted for and either the no-changeset decision is explicit or the PR has one\nconsolidated, valid changeset by default. Its release note is one sentence of\nconsumer impact, plus migration steps for every break, with no implementation\ndetail.\n",".agents/skills/changesets/authoring.md":"# Authoring changesets\n\nUpdate the changeset already introduced by the PR. If there is none, create one\n`.changeset/.md` for the complete PR:\n\n```md\n---\n\"effect\": patch\n\"@effect/affected-package\": patch\n---\n\nFix `Effect.cachedInvalidateWithTTL` caching a stale result when invalidated while the effect is running.\n```\n\nWrite one short sentence, usually under 25 words, that names the changed API\nand states what consumers will notice. That sentence is the whole entry unless\nthe change is breaking or consumers must migrate.\n\nLeave out how the change works: internal modules, algorithms, data structures,\nrefactors, motivation, benchmarks, test coverage, and development history. They\nbelong in the PR description. Cut any sentence a consumer would not act on.\n\n- Bad: \"Rework the `MemoMap` lookup so `Layer.provide` checks identity before\n building, adding a cache keyed by layer reference and tests for shared\n layers.\"\n- Good: \"Fix composed layers being rebuilt for every parent that references\n them.\"\n\nAdd detail only for a break or required migration: what existing code must\nchange and how. Use compact bullets, one break per bullet, when several breaks\nneed migration steps. Several non-breaking fixes or additions still share one\nsentence.\n\nList every directly affected published package. Do not list packages merely\nbecause they share the fixed release group in `.changeset/config.json`.\n\nChoose the bump from current release policy:\n\n- Use `patch` for compatible fixes, `minor` for compatible additions, and\n `major` for breaks.\n- A break confined to APIs tagged `@stability unstable` is `minor`. A break\n confined to APIs tagged `@stability experimental` is `patch`. APIs tagged\n `@stability stable` follow strict semver.\n- Use `major` only when a maintainer has approved a major release.\n- The release queue retargets PRs with `minor` changesets to `v4/next-minor`\n and PRs with `major` changesets to `v4/next-major`. Choose the level the\n change requires, not the branch you want it to land on.\n- Ask when release intent is ambiguous.\n\nUse a `### Breaking changes` section when several breaks need separate\nscanning. Include before/after examples only when they materially clarify\nmigration.\n\nValidate frontmatter against published package names and inspect nearby current\nchangesets for release convention. Do not copy the length of longer entries.\nNever run `changeset-version` or `changeset-publish` as contributor validation.\n",".agents/skills/ci-maintenance/SKILL.md":"---\nname: ci-maintenance\ndescription: GitHub Actions maintenance. Use when authoring or reviewing workflows or composite actions, especially event, permission, action-reference, artifact, setup, or concurrency changes.\n---\n\nAudit the trust boundary before editing. This skill owns Actions event\nsemantics, workflow security, permissions, action pinning, setup reuse,\nuntrusted inputs, timeouts, concurrency, and artifact trust boundaries.\n\n## Workflow\n\n1. Decide whether this is a review or an implementation. Reviews produce\n evidence-backed findings without editing; implementations continue through\n the smallest boundary-preserving change.\n2. Inspect every affected workflow, composite action, and caller. List all\n affected jobs and actions before proceeding.\n3. For each job, record the trigger, actor/fork status, workflow revision,\n checked-out revision, permissions, credentials, and every external input and\n consumer. Include artifacts, caches, outputs, PR fields, refs, dispatch\n inputs, generated files, and called actions.\n4. Consult current GitHub documentation for every platform-sensitive decision.\n Repository examples establish local convention, not platform semantics.\n5. Apply every applicable rule:\n - Default workflow permissions to empty and grant minimal job permissions.\n - Reuse the repository's shared setup action unless the environment must differ.\n - Give executable jobs intentional matrices and realistic timeouts.\n - Pin external actions and reusable workflows to full commit SHAs with\n readable release comments; verify each SHA belongs to that upstream release.\n - Analyze event choice, checkout revision, and credential persistence\n together.\n - Pass untrusted expressions through environment variables; validate and\n quote them before use.\n - Derive concurrency from interruption safety.\n6. For forks, privileged credentials, publication, or cross-run data, read\n [privileged-workflows.md](privileged-workflows.md).\n7. Run the narrowest syntax and repository checks, inspect the complete diff,\n and identify behavior testable only on GitHub-hosted runners.\n\nFor local patterns, inspect the current shared setup action and the nearest\nworkflow with the same trust boundary. Use ordinary check workflows for routine\nprecedent and privileged publication workflows only for equivalent trust\nboundaries.\n\nThe task is complete when every affected job and caller has a recorded trust\nboundary, every applicable rule has evidence or a compensating control, local\nchecks pass, and GitHub-only verification is identified. Reviews report every\nfailure with evidence; implementations resolve every failure and contain only\nintended behavior.\n",".agents/skills/ci-maintenance/privileged-workflows.md":"# Privileged Workflows\n\n- Privileged jobs must not run untrusted repository code with secrets or write\n credentials.\n- Validate cross-run data for expected source, identity, type, shape, and\n bounded size before using it in commands, outputs, APIs, or comments.\n- Require the intended approval boundary before fork-originated work reaches\n privileged execution.\n- Preserve publication and other irreversible operations until completion;\n cancel only replaceable checks and previews.\n- Make checkout revision and credential persistence explicit. Account for\n every write permission and credential.\n\nSearch current workflows by event, job purpose, action, and permission to find\nthe nearest precedent for fork approval gates, publication, non-cancelable\nconcurrency, and validation of cross-run artifacts before privileged use.\n\nConsult current GitHub documentation for event, token, secret, permission,\ncheckout, artifact, reusable-workflow, and environment semantics. Start with\nthe workflow events, workflow syntax, and secure-use references.\n",".agents/skills/dependency-maintenance/SKILL.md":"---\nname: dependency-maintenance\ndescription: Dependency maintenance. Use when adding, moving, or upgrading dependencies, changing pnpm or JavaScript runtimes, updating TypeScript or build/test tools, or changing native-build policy, patches, or test images.\n---\n\nTreat an upgrade as a synchronization task, not a lockfile refresh. Derive\nversions, commands, and compatibility points from the current repository.\n\n## Discover\n\n1. Read affected manifests and scripts, `pnpm-workspace.yaml`, setup actions,\n workflows, test configuration, and compatibility documentation.\n2. Search for the dependency and every current version, range, runtime input,\n image, engine constraint, patch, and compatibility claim.\n3. Record each match as a development version, tested version, peer range,\n engine minimum, advertised minimum, or intentionally different constraint.\n4. When adding or moving a manifest entry, read\n [manifest-roles.md](manifest-roles.md) before selecting its role.\n5. Select the package-local or coordinated branch and its validation matrix.\n\nDiscovery is complete when every match and affected validation surface is\naccounted for.\n\n## Package-local branch\n\nUse this branch only for one dependency in one workspace package when runtime,\ncompiler, package-manager, image, patch, native-build, and shared-tooling policy\nare unchanged.\n\nUpdate only the owning manifest and keep peer compatibility independent from\nthe development version tested here. If any coordinated surface appears,\nswitch branches.\n\nThis branch is complete when the manifest and lockfile agree, focused checks\npass, and every search result is intentionally unchanged or package-local.\n\n## Coordinated branch\n\nRead [coordinated-upgrades.md](coordinated-upgrades.md), select every applicable\nrow, and update all listed synchronization points before installing. Apply root\nworkflow and generated-file requirements before editing those surfaces, then\nreturn here to finish matrix and lockfile review.\n\n## Install and finish\n\nRun root `pnpm install` after all selected edits. Inspect warnings and the\nsemantic lockfile diff for specifiers, resolutions, duplicate transitives, peer\nchanges, integrity, patch hashes, lifecycle scripts, and `allowBuilds` effects.\nA successful install alone does not complete this review.\n\nRun the narrowest correctness and performance checks that cover every selected\nmatrix row.\nApply the root changeset routing after implementation and focused validation.\n\nThe task is complete when repeated repository searches find no unclassified\nsynchronization point, manifest roles and compatibility ranges are intentional,\nthe lockfile has no unexplained churn, and every selected check passes or is\nreported as not runnable.\n",".agents/skills/dependency-maintenance/coordinated-upgrades.md":"# Coordinated Upgrades\n\nSelect every applicable row and derive commands from the cited current source.\n\n| Change | Synchronize | Validation source |\n| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |\n| Shared dependency or test/build tool | Owning manifests, peer/development pairs, configs, and generated artifacts owned by that tool | Root/package scripts and affected Vitest projects |\n| pnpm | Root `packageManager`, workspace settings, setup/cache assumptions, workflows, and lockfile format | Current install, lint, check, build, and focused test scripts |\n| Node, Deno, or Bun | Setup inputs, workflow jobs, engines, runtime metadata, compatibility docs, and runtime config | Current runtime workflow jobs and test configuration |\n| TypeScript support or compiler | Compiler/tooling dependencies, `test-types` target, CI target, tool peer ranges, compatibility docs, and typetests | Targeted typetests; typeperf protocol for measured paths |\n| Native package or install policy | Owning manifests and `pnpm-workspace.yaml#allowBuilds` | Fresh install plus focused package build and tests |\n| Patched dependency | Manifest/range, `patchedDependencies`, patch file, and lockfile patch hash | Fresh install and the behavior that required the patch |\n| Container image or Testcontainers package | Workflow pre-pulls, image call sites, manifests, and integration project names | Current integration workflow and Vitest configuration |\n\nFor a patched dependency, test the new release without the patch when feasible.\nRemove obsolete registration and patch files. Otherwise refresh the patch using\nthe current pnpm workflow and verify both that it applies and that the original\npatched behavior still requires it.\n\nWhen an upgraded component lies on a measured path, use the repository's\nruntimeperf or typeperf comparison protocol rather than inventing a benchmark.\n",".agents/skills/dependency-maintenance/manifest-roles.md":"# Manifest Roles\n\nInspect the nearest package with the same integration shape, then justify each\nadded or moved entry:\n\n| Role | Use when | Completion check |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |\n| `dependencies` | Published runtime code requires its own installed copy. | A packed consumer receives it without adding an undeclared package. |\n| `peerDependencies` | Consumers provide a compatible shared package or the public contract integrates with their copy. | The range states supported consumer versions; add a development entry when local build or tests need an installed copy. |\n| `devDependencies` | Only repository build, test, type, benchmark, or code-generation work needs it. | Published runtime code and declarations do not require consumers to install it. |\n| `optionalDependencies` | A runtime feature handles absence and installation failure must not block the base package. | Focused tests cover present and absent behavior. |\n| Optional peer via `peerDependenciesMeta` | A consumer-provided integration is genuinely optional. | The peer remains in `peerDependencies`, and code requires it only when selected. |\n\nRole selection is complete when every changed entry has one justified role and\npeer compatibility remains independent from repository validation versions.\n",".agents/skills/effect-development/SKILL.md":"---\nname: effect-development\ndescription: Effect development guidance. Use when implementing or reviewing code that composes Effect APIs or patterns, or that adds or changes API signatures.\n---\n\nUse the repository's AI documentation as targeted reference, not ambient\ncontext:\n\n1. Identify the Effect APIs and concepts involved in the change.\n2. Search `LLMS.md` and `ai-docs/src` for those names and concepts, then read\n the matching sections and examples.\n3. Apply the relevant guidance and inspect nearby source and tests for any\n repository-internal conventions not covered by the documentation.\n\nThe task is ready for implementation when every material Effect API or pattern\nhas matching local guidance, or the search has established that none exists.\n\n## API conventions\n\nWrite option types inline in the signature by default. Mark fields `readonly`\nand add `| undefined` to optional fields:\n\n```ts\nexport const make = (options: {\n readonly capacity: number\n readonly strategy?: \"dropping\" | \"sliding\" | undefined\n}): Effect.Effect => ...\n```\n\nDeclare a named options type only in these cases:\n\n- A substantial set of options is shared across several APIs, so a named type\n keeps them in sync.\n- The options type needs complex conditional logic, such as conditional or\n mapped types driven by type parameters.\n\nA long option list for a single API is not on its own a reason to extract a\nnamed type.\n",".agents/skills/jsdocs/SKILL.md":"---\nname: jsdocs\ndescription: Public API JSDoc. Use when authoring or reviewing Effect API documentation, refining a module's documentation, or fixing documentation related diagnostics.\n---\n\n## Workflow\n\n1. Inspect the declaration, implementation, nearby JSDoc, tests, and call sites.\n2. Select every applicable branch and load its reference before editing:\n - tags, modules, or links: [declarations.md](declarations.md);\n - categories: [categories.md](categories.md);\n - examples: [examples.md](examples.md).\n3. Make a focused API fix or module refinement. Preserve verified facts and\n valuable examples rather than rewriting mechanically.\n4. For module refinement or APIs with close alternatives, audit `@see` links\n and inspect implementation and tests for concrete `**Gotchas**`.\n5. Run `pnpm jsdocs --check` and every applicable root validation command.\n\n`@internal` declarations and default exports are outside public JSDoc\nauthoring. Checked files do not support exported enums or empty export\ndeclarations.\n\nPublic declarations use a multiline block with one self-contained practical\ndescription paragraph. Start functions and methods with a present-tense action;\nmatch nearby noun-family phrasing for values. Optional non-empty sections appear\nonce in this order: `**When to use**`, `**Details**`, `**Gotchas**`. Separate\ndescriptions, sections, examples, and tags with one blank line. `**When to\nuse**` states a positive use case distinct from the description; reserve\n`**Gotchas**` for concrete caveats and failure modes.\n\nThe task is complete when every changed public declaration satisfies each\napplicable reference, the checker passes, runnable examples pass their targeted\ndoctest, and all other applicable root checks pass or are reported as not run.\n",".agents/skills/jsdocs/categories.md":"# Categories\n\nRoot declarations require one non-empty `@category`. Reuse nearby categories;\nprefer lowercase plurals and gerunds while preserving canonical domain casing.\n\nCommon categories include:\n\n- Shapes: `constructors`, `destructors`, `models`, `schemas`, `guards`,\n `predicates`, `getters`, `accessors`, `instances`, `constants`, `protocols`,\n `prototypes`, `re-exports`, `unsafe`, `testing`.\n- Effect: `services`, `tags`, `layers`, `context`, `resource management`,\n `running`, `errors`, `error handling`.\n- Operations: `combinators`, `filtering`, `mapping`, `sequencing`, `zipping`,\n `combining`, `merging`, `converting`, `transforming`, `folding`, `splitting`,\n `repetition`.\n- Shared: `utility types`, `encoding`, `decoding`, `serialization`, `tracing`,\n `metrics`, `logging`, `annotations`, `references`, `symbols`, `type IDs`,\n `configuration`, `math`, `comparisons`, `ordering`.\n\nKeep these boundaries: services are contracts, tags identify services, and\nlayers provide them; getters retrieve values while accessors read context;\nerrors model failures while error handling recovers or maps them; models are\ndomain data while utility types are type-level contracts; guards narrow while\npredicates return booleans.\n",".agents/skills/jsdocs/declarations.md":"# Tags, Modules, And Links\n\n## Declaration Shape\n\nUse a multiline JSDoc block for a public declaration:\n\n````ts\n/**\n * Short description as one paragraph.\n *\n * **When to use**\n *\n * Optional practical usage guidance.\n *\n * **Details**\n *\n * Optional details for complex behavior.\n *\n * **Gotchas**\n *\n * Optional concrete caveats.\n *\n * **Example** (Parsing JSON)\n *\n * ```ts import.meta.vitest\n * operation() // => expected\n * ```\n *\n * @category constructors\n * @since 1.0.0\n */\n````\n\nWrite practical English about the public concept, not its implementation. Start\nfunctions and methods with a present-tense action such as `Creates`, `Returns`,\nor `Converts`; match nearby noun families for values, such as `Schema for`,\n`Layer that`, or `Service that`.\n\nOptional non-empty sections appear once in this order: `**When to use**`,\n`**Details**`, `**Gotchas**`. Separate descriptions, sections, examples, and\ntags with exactly one blank line. Use prose for one fact and bullets for\nparallel facts. Do not add other headings.\n\n`**When to use**` states a positive use case distinct from the description and\nbegins with `Use to`, `Use when`, `Use as`, or `Use with`. Put sibling\ncomparisons in `@see`. Reserve `**Gotchas**` for concrete preconditions, edge\ncases, surprising behavior, and important failure modes.\n\n## Tags\n\nDeclaration tags appear in this order:\n\n1. `@deprecated`\n2. `@default`\n3. `@see`\n4. `@stability`\n5. `@category`\n6. `@since`\n\n- Roots require stable-semver `@since` and no `@default`; category requirements\n live in [categories.md](categories.md).\n- Namespaces and their declarations require stable-semver `@since`, permit\n `@category`, and reject `@default`.\n- Member JSDoc is optional; when present it permits stable-semver `@since` and\n non-empty `@default`, rejects `@category`, and follows the prose contract.\n- Any declaration permits one non-empty `@deprecated` and repeated non-empty\n `@see` tags.\n- Roots, export specifiers, and root namespaces require `@stability stable`,\n `@stability unstable`, or `@stability experimental`. Use `unstable` when an\n API may receive breaking changes in minor releases, `experimental` when it may\n receive breaking changes across patch versions, and `stable` otherwise.\n- Tag any API that exposes a third-party dependency `@stability unstable`: an\n accessor to the underlying client or instance, options typed as the\n dependency's options, constructors that accept its instances, re-exports of\n it, and signatures that mention its types. Tag the whole module when it exists\n to wrap the dependency; otherwise tag only the exposing declarations or\n members. Runtime built-ins (Node, Bun, Deno, DOM) and framework types inherent\n to a binding (React, Solid, Vue) are exempt.\n\nUse canonical `**Example**` sections rather than `@example` tags or loose code\nfences.\n\n## Modules And Links\n\nWhen present, the first top-level JSDoc is the module block unless TypeScript\nattaches it to a non-import first declaration. An `@internal` module is omitted.\nModule prose does not use the declaration template. Its tags are optional\nnon-empty `@deprecated`, repeated non-empty `@see`, required `@stability`, then\nrequired stable-semver `@since`. Its examples and links follow the declaration\ncontracts.\n\nInline `{@link Symbol}` targets must resolve to TypeScript symbols; use normal\nMarkdown links for URLs. Prefer code formatting when navigation does not help a\nreader understand or choose the API.\n\nUse `@see` only for a verified related public API: a close alternative,\ninverse, complement, level variant, or closely returned, consumed, or\nconfigured type. Explain non-obvious relationships. Exclude implementation\ndependencies, broad concepts, example-only helpers, private APIs, and merely\nlexical matches.\n",".agents/skills/jsdocs/examples.md":"# Examples\n\nExamples are optional. Keep or add one only for behavior not evident from the\nsignature, meaningful composition, or useful inference or narrowing. Replace\nor remove examples that are trivial, misleading, contrived, or\nscaffolding-heavy.\n\nUse `**Example** (Unique use-case title)`, optional prose, and exactly one\nnon-empty `ts` fence. Titles must remain unique after trimming and lowercasing.\n\nRead `packages/tools/doctest/README.md` for runnable-fence and inline-assertion\nsyntax. Additionally:\n\n- Use public imports and arrange nontrivial examples as setup, operation, then\n semantic observation.\n- The transform does not run Effects or await promises automatically. Prefer\n awaited `Effect.runPromise`; use `Effect.runSync` only when synchronous\n execution is the documented contract.\n- Keep type-level examples marked without tautological runtime assertions.\n- Leave examples that register tests and intentionally non-executable examples\n as plain `ts` fences.\n- Use `Ref`, `Deferred`, or `Queue` rather than mutable probes for concurrency,\n interruption, or races.\n\nIf example research suggests an implementation or type bug, report it instead\nof changing runtime code during a documentation-only pass.\n",".agents/skills/migration-guidance/SKILL.md":"---\nname: migration-guidance\ndescription: Use when changing how a v3 public API maps to v4, editing migration annotations, or regenerating migration/v3-to-v4.md.\n---\n\nUpdate guidance when a v3 public module or API is renamed, moved, removed,\nreplaced, or gains a materially different v4 contract. A v4-only API without a\nv3 counterpart does not automatically need an annotation.\n\n1. Account for every affected v3 symbol.\n2. Read [annotations.md](annotations.md) before adding or changing annotation\n YAML. Verify every suggested replacement against implementation and tests.\n3. When checking or regenerating the reference, or when the API change exists in\n a committed ref, read [generation.md](generation.md). Otherwise report that\n generation is deferred.\n4. When output was generated, inspect it for unrelated movement and stale refs.\n\nThe task is complete when every affected v3 symbol is accounted for, annotation\nreplacements are verified, checks and generation succeed when the change is in\na committed ref, and every generated difference is explained. Report deferred\nchecks explicitly for uncommitted API changes.\n",".agents/skills/migration-guidance/annotations.md":"# Migration Annotations\n\nAdd or update one YAML file per v3 module under `migration/annotations/`. Use\nstable API IDs without trailing `#type` or `#value` facets:\n\n```yaml\neffect/Effect#async:\n replacement: Effect.callback\n note: Use the callback constructor.\n example: Effect.callback((resume) => resume(Effect.void))\n```\n\nEvery annotation requires `replacement` and `note`; `example` is optional. Use\n`replacement: none` when there is no direct replacement and explain the\nsupported migration strategy instead of inventing an equivalent API.\n",".agents/skills/migration-guidance/generation.md":"# Generated Migration Reference\n\n`migration/v3-to-v4.md` is generated. Check annotations and regenerate using\nexplicit committed refs containing the change:\n\n```sh\npnpm api-diff --base-ref origin/v3 --head-ref HEAD --check\npnpm api-diff --base-ref origin/v3 --head-ref HEAD --write-doc migration/v3-to-v4.md\n```\n\nThe API diff reads refs through detached worktrees. If the API change is\nuncommitted, `HEAD` does not contain it. Update known annotation IDs, defer the\ncheck and regeneration, and report the limitation. Do not create a temporary\ncommit solely to run the tool.\n",".agents/skills/package-development/SKILL.md":"---\nname: package-development\ndescription: Package registration. Use when adding a workspace package, making a private package publishable, renaming a package, or moving its workspace path.\n---\n\nTreat package work as a registration change, not a directory copy.\n\n## Workflow\n\n1. Inspect the closest package in the same family. Classify publication status,\n runtime, test environment, platform support, barrels, and dependency shape.\n Justify each proposed file by precedent or an explicit repository need.\n Continue when every proposed file is justified.\n2. Create or move only required source, test, TypeScript, and manifest files.\n When manifest dependencies change, read [dependencies.md](dependencies.md)\n and classify every entry by role.\n Continue when pnpm discovers the intended name and manifests reference no\n absent file.\n3. Read [registration.md](registration.md). Classify every registration surface\n as applicable or not applicable and update every applicable surface.\n Continue when every surface is classified and old references are explained.\n4. For a published package, read [publishing.md](publishing.md) and verify its\n development and packed surfaces.\n5. Run codegen when the package owns generated barrels, then inspect generated\n sections rather than editing them manually.\n Continue when generated sections match source modules without manual edits.\n6. Run focused package tests and scripts plus applicable root checks. Include\n public API type tests when applicable. For published packages, build and dry\n pack the package as described in [publishing.md](publishing.md).\n Continue when focused and root checks pass and the packed surface is intended.\n7. Apply root changeset, generated-file, documentation, and workflow routing.\n\nThe task is complete when package discovery, registration, generated output,\nvalidation, packed output, and changeset routing are all verified or reported\nas not applicable.\n",".agents/skills/package-development/dependencies.md":"# Package Dependencies\n\nInspect the closest package with the same publication and integration shape.\nClassify every manifest entry by the role it serves:\n\n| Role | Use when |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------ |\n| `dependencies` | Published runtime code requires the package to receive its own installed copy. |\n| `peerDependencies` | Consumers provide a compatible shared package or the public contract integrates with their copy. |\n| `devDependencies` | Only repository build, test, type test, benchmark, or code generation needs the package. |\n| `optionalDependencies` | A runtime feature handles absence and installation failure must not block the base package. |\n| Optional peer via `peerDependenciesMeta` | A consumer-provided integration is genuinely optional. Keep its version in `peerDependencies`. |\n\nUse `workspace:^` for workspace packages unless neighboring packages establish a\ndifferent policy. When local build or tests need an installed peer, add the peer\nto `devDependencies` at the repository's tested version while keeping the peer\nrange based on supported consumer versions.\n\nDerive external versions from current consumers with the same integration\nshape. Add only direct requirements; do not copy a neighboring manifest entry\nthat the new package's runtime, declarations, build, or tests do not use.\n\nAfter editing manifests, run root `pnpm install`. Inspect warnings and the\npackage's `pnpm-lock.yaml` importer for intended specifiers and resolutions. If\na dependency has an install or native build, classify it under\n`pnpm-workspace.yaml#allowBuilds` using current repository policy.\n\nThis branch is complete when every entry has one justified role, workspace and\npeer ranges follow repository policy, the lockfile importer agrees with the\nmanifest, and install/build policy is explicit.\n",".agents/skills/package-development/publishing.md":"# Publishing A Package\n\nCompare the package manifest with a neighboring published package in the same\nfamily.\n\n- Keep development `exports` and `publishConfig.exports` aligned by key.\n Source targets become their intended built targets; blocked internal and\n legacy paths remain blocked.\n- Check current AI documentation copy tooling and the package `files` list for\n every file required in the published payload.\n- Ensure each public source entrypoint has exactly one published counterpart\n and no internal entrypoint becomes exposed.\n\nRun the current root build so publication payload generation executes. Create a\ntarball in a temporary destination without publishing, inspect its file list,\nand inspect the packed `package.json` whenever manifest transformation matters.\n\nThis branch is complete when package and root checks pass and the packed\nsurface contains exactly the intended files, exports, and metadata.\n",".agents/skills/package-development/registration.md":"# Package Registration\n\nUse current configuration and the closest package in the same family as the\nsources of truth. A package-local build does not prove repository registration.\nClassify every row as applicable or not applicable.\n\n## Workspace And TypeScript\n\n| Surface | Check |\n| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `pnpm-workspace.yaml` | Its globs cover the package path and exact-name pnpm selection discovers it. |\n| `pnpm-lock.yaml` | The current importer, name, and dependencies exist; renamed or moved importers are gone. |\n| `tsconfig.packages.json` | Packages intended to participate in the root TypeScript project-reference graph are referenced. Follow neighboring package policy; buildable private tools are not automatically included. |\n| `tsconfig.tests.json` | Broad test globs cover the path. Add source aliases only when tests require workspace source routing or would otherwise create a dependency cycle. Preserve intentional platform exclusions. |\n\n## Tests And Documentation\n\n| Surface | Check |\n| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `vitest.config.ts` | A package with runtime tests has the intended project, environment, setup, and inclusion rules. |\n| `tstyche.json` | Type-test discovery covers the package depth; current globs cover one- and two-level package layouts. |\n| `vitest.docs.ts` | Doctest source discovery covers packages with runnable JSDoc examples; current globs cover one- and two-level package layouts. |\n| `jsdocs.config.json` | Public source is included in JSDoc checks and exclusions by package family remain intentional. |\n| `deno.json` | Deno checks cover the package family, or its exclusion is intentional. |\n\n## Release And Discovery\n\n| Surface | Check |\n| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `.changeset/config.json` | Published fixed-group membership uses the current name; private tooling is not added solely because it builds. |\n| `README.md` | Public catalog entries have the current name, path, description, and documentation link. |\n| AI documentation copy tooling and package `files` | Published payloads include required generated documentation. Continue with [publishing.md](publishing.md) for the full packed-surface audit. |\n| Snapshot publishing workflows | Snapshot publishing selects the package path. Existing globs may already cover it; apply root workflow requirements before editing. |\n| Runtime-specific CI workflows | Runtime-specific packages participate in applicable runtime jobs; apply root workflow requirements before editing. |\n\n## Paths And Consumers\n\nAudit explicit workspace package names in root tooling manifests. Search scripts\nfor the package family, old name, and old path to find path-sensitive clean,\ncodemod, circularity, copy, and related behavior. Explain every remaining old\nreference after a rename or move.\n",".agents/skills/performance-analysis/SKILL.md":"---\nname: performance-analysis\ndescription: Performance analysis. Use for runtime throughput or latency benchmarks, TypeScript compiler cost, performance regressions, comparison harnesses, or thresholds.\n---\n\nValidate correctness with focused tests before measuring. Compare the same\nfocused operation and environment across revisions; a single unpaired run is\nnot evidence of improvement.\n\nSelect every applicable branch:\n\n- **Runtime performance:** Read [runtime.md](runtime.md).\n- **Type performance:** Read [types.md](types.md).\n\nThe task is complete when every selected branch meets its measurement and\nreporting criteria and applicable root checks pass or are reported as not\nrunnable.\n",".agents/skills/performance-analysis/runtime.md":"# Runtime Performance\n\nFor authoritative base/head comparisons or fixture work, read\n`packages/effect/runtimeperf/README.md`. Use `pnpm runtimeperf-compare\n` for local worktree comparisons and explicit `--base`/`--head`\nonly for committed refs. Report the resolved comparison head and measurement\nconfiguration.\n\nFor exploratory scripts under `benchmark/`, match nearby Tinybench scripts,\nkeep setup outside the measured callback unless setup is the operation, warm\nreusable state, close resources, and print the table. Label results exploratory\nunless the task defines a repeatable comparison protocol.\n\nFocused runtimeperf work is complete when fixture validation and the selected\nrun succeed. Comparison work additionally requires every configured round to\nsucceed, the paired statistical classification to support the conclusion, and\nresolved refs and settings to be reported. Harness changes require its focused\nchecks. Tinybench work is complete when resources close, the table is reported,\nand claims remain exploratory unless a repeatable protocol was run.\n",".agents/skills/performance-analysis/types.md":"# Type Performance\n\nRead `packages/effect/typeperf/README.md` before adding fixtures, changing the\nharness, updating thresholds, or running cross-ref comparisons. Isolate one\nrealistic public type path and compare the same fixture and compiler environment\nacross revisions. Derive supported suites and comparison commands from the\ncurrent harness documentation and CLI.\n\nBefore changing a threshold, record its previous value and measured result,\nexplain the expected delta, update it, and run a clean focused verification.\nKeep ordinary threshold fixtures separate from cross-ref fixtures.\n\nThis branch is complete when the focused measurement is repeatable, threshold\nverification is clean when applicable, and reported comparisons include\nresolved refs, compiler version, and an explanation of the observed delta.\nFixture or harness changes also require the focused validation and formatting\nchecks documented in the README.\n",".agents/skills/pull-requests/SKILL.md":"---\nname: pull-requests\ndescription: Pull request finalization. Use when a change works and is about to be opened as a pull request, or when updating or continuing an existing one.\n---\n\nA pull request is ready when its tests, implementation, comments, and changeset\nare each the simplest that cover the intended behavior. Draft PRs can be used\nearlier; finishing means making the PR ready for review.\n\n## Workflow\n\nRun each step in a fresh-context subagent when available; otherwise run it\nyourself. Pass along the task context and prior results so each step can check its gate.\n\n1. Keep tests focused. Read [test-development](../test-development/SKILL.md) for\n test placement and type. Cover each intended behavior once, in the existing\n test file for the module.\n For changes needing no tests, record why.\n Continue when removing any remaining case would leave intended behavior\n uncovered, or no tests are needed.\n2. Simplify the implementation. With the tests passing, look for a simpler or\n more idiomatic version: reuse helpers and patterns from nearby source and\n [effect-development](../effect-development/SKILL.md), and remove debugging\n code, scaffolding, and changes unrelated to the task.\n Continue when applicable targeted tests pass and every hunk in the diff\n from the merge base is required by the task.\n3. Review the full diff from the merge base as a maintainer would: correctness,\n failure and interruption paths, resource cleanup, naming and API\n consistency with neighboring modules, and documentation. Fix findings and\n review again.\n Continue when a review pass produces no findings.\n4. Clean up. Remove comments that restate code or narrate the change; keep the\n rest short and about why. Finalize the changeset with\n [changesets](../changesets/SKILL.md).\n Continue when comments explain only what code cannot, and the changeset\n describes the final consumer impact or the no-changeset reason is recorded.\n5. Run the validation in the [AGENTS.md validation table](../../AGENTS.md#validation)\n for each change type in the diff. Fix failures caused by the change; if\n fixes alter the diff, repeat the affected passes.\n Continue when applicable checks pass or commands that cannot run and their\n blockers are recorded.\n6. Open or update the pull request. Title: a short imperative summary.\n Description: the problem addressed, notable decisions, and `Closes #` for each\n GitHub issue resolved. Do not narrate the diff. Mark the PR ready for review.\n Continue when the final changes are pushed, the description matches the\n final diff, and the PR is ready for review.\n\nThe task is complete when each step's gate holds, validation has passed or\nbeen reported as not runnable with reasons, and the pull request is ready for\nreview with a description matching the final diff.\n",".agents/skills/test-development/SKILL.md":"---\nname: test-development\ndescription: Test development. Use when adding or changing Vitest or Tstyche coverage. Choose Tstyche only for intended compiler behavior such as inference, assignability, rejection, or displayed public types.\n---\n\nChoose branches from the task's acceptance criteria before editing:\n\n- **Runtime behavior:** The intended result is observable when code executes.\n Read [runtime.md](runtime.md).\n- **Compiler behavior:** The intended result is TypeScript accepting, rejecting,\n or inferring a consumer expression in a particular way. Read\n [types.md](types.md).\n\nAn exported signature alone is validated by `pnpm check`; it enters the compiler\nbranch only when its inference, assignability, rejection, overload selection, or\ndisplayed type is part of the task. Some changes require both branches because\nthey independently change runtime and compiler behavior.\n\nThe task is complete when each intended behavior in scope has the relevant\nfocused coverage, targeted tests pass, and applicable root checks pass or are\nreported as not runnable.\n",".agents/skills/test-development/displayed-types.md":"# Displayed Types\n\nDeliberately produce an assignment error and match a distinctive substring with\nTstyche's checked `@ts-expect-error` message:\n\n```ts\nit(\"simplifies the displayed type\", () => {\n const value = null as unknown as PublicType\n\n // @ts-expect-error Type '{ readonly value: string; }'\n const displayed: never = value\n\n void displayed\n})\n```\n\nKeep the expected substring as small as possible while distinguishing the\npublic type from the leaked implementation type. Before accepting the test,\ntemporarily restore the broken type and confirm the diagnostic-message match\nfails.\n",".agents/skills/test-development/runtime.md":"# Runtime Tests\n\n- Use `it.effect` for Effect-returning tests and regular `it` for pure\n synchronous tests.\n- `it.effect` and `it.live` provide and close a `Scope`; return scoped effects\n directly instead of wrapping the body in `Effect.scoped`.\n- Use `assert` from `@effect/vitest`, not Vitest's `expect`.\n- Use `TestClock` for time-dependent behavior.\n- Keep `Effect.runSync` out of unit tests; runnable documentation follows the\n root JSDoc validation rules.\n\nInspect nearby tests for imports and structure. This branch is complete when\nevery changed behavior has focused coverage and its targeted test passes.\n",".agents/skills/test-development/types.md":"# Type tests\n\nEnter this branch when the acceptance criterion is compiler behavior: inference,\nassignability, rejection, overload selection, generic constraints, or a displayed\npublic type. Use `pnpm check` for ordinary declaration edits whose compiler\nbehavior is not independently under test. A runtime bug in generic code needs a\nruntime regression test, not a type test, when its type contract is unchanged.\n\nInspect nearby `.tst.ts` files and use their imports and assertion style. Use\nordinary Tstyche assertions such as `toBe` for structural equality and choose a\nspecific assertion for the inference or assignability contract under test.\n\nStructural equality does not verify editor quick-info rendering. For internal\naliases, unsimplified intersections, or other displayed-type regressions, read\n[displayed-types.md](displayed-types.md).\n\nRun targeted `pnpm test-types `; the root command covers every\nconfigured TypeScript version. For a regression fix, confirm the assertion\nfails against the pre-fix type. This branch is complete when the assertion\nproves the intended contract and the target passes.\n",".agents/skills/vendored-assets/SKILL.md":"---\nname: vendored-assets\ndescription: Vendored assets. Use when importing or updating checked-in third-party or externally generated JavaScript, CSS, registries, schemas, snapshots, or Scalar, Swagger, and MIME artifacts.\n---\n\nTreat upstream artifacts as supply-chain inputs. Change their generator or\ndocumented import source, then regenerate; generated output is review evidence,\nnot an editing surface.\n\n## Workflow\n\n1. **Trace ownership.** Identify the artifact, generator or exact import\n procedure, upstream source/version, license, consumers, tests, and shipped\n package or bundle. Search by asset and upstream project name to find current\n packaging scripts, generated artifacts, consumers, and history.\n Continue when every input and consumer is accounted for.\n2. **Pin provenance.** Resolve moving URLs, tags, branches, and omitted versions\n to an immutable release or artifact. Record project, version, path or URL,\n and digest in the generator or maintenance header. Omit a digest only when\n another enforced immutable source is recorded.\n Continue when a future run cannot silently select different bytes.\n3. **Clear the license gate.** Verify release metadata, license files, bundled\n notices, and the license trail retained in the distributed form.\n Continue when every distributed artifact has a verified retained license trail.\n4. **Regenerate.** Improve the generator or import reference first. Recover an\n exact procedure for generatorless assets; add a deterministic script only\n for recurring updates. Record a one-off procedure beside the artifact. A\n clean rerun must produce no diff.\n5. **Audit the complete diff.** Account for behavior, URLs and runtime fetches,\n source maps, notices, encoding, format changes, and additions or removals.\n For browser assets, also read [browser-assets.md](browser-assets.md).\n Continue when every change is attributable and suspicious content is resolved\n or reported.\n6. **Clear test and size gates.** Record byte sizes before and after, use\n focused consumer tests, and compare bundle size or composition when shipped\n JavaScript, CSS, or registry output changes materially. Compare that output\n against the pre-update revision rather than measuring only current size.\n Continue when focused checks pass and every non-trivial size delta is explained.\n7. **Close release impact.** Apply root changeset routing for consumer-visible\n behavior, browser support, wire data, or meaningful shipped-size changes.\n Generated sections owned by barrels, AI docs, or migration tooling remain\n with the owners named in root instructions.\n\nThe task is complete when every input and consumer is accounted for, provenance\nand licenses are immutable and retained, regeneration is deterministic, every\noutput change and non-trivial size delta is explained, focused checks pass or\nare reported as not runnable, and release impact is recorded.\n",".agents/skills/vendored-assets/browser-assets.md":"# Browser Asset Audit\n\nFor browser-delivered JavaScript or CSS, inspect the complete generated output\nfor:\n\n- CSP requirements and dynamic code execution;\n- injected markup, scripts, or styles;\n- network destinations and runtime loading;\n- external URLs, source maps, and runtime fetches;\n- bundled code or notices absent from upstream top-level metadata.\n\nEvery destination and executable behavior must be attributable to the selected\nupstream release. Resolve or report suspicious content before completion.\n","packages/ai/anthropic/README.md":"# @effect/ai-anthropic\n\nAn [Anthropic](https://www.anthropic.com) provider for the Effect AI modules. Includes a typed Anthropic API client, language model layers, tools, and telemetry helpers.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-anthropic\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/ai-anthropic): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/ai/cloudflare/README.md":"# @effect/ai-cloudflare\n\nCloudflare Workers AI provider for Effect's `DecisionModel`. Supports text and JSON classification, ordered ratings, and probabilities with Clef and Clef-flash over REST.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-cloudflare\n```\n\n## Usage\n\nSet `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`, then provide a Cloudflare decision model:\n\n```ts\nimport { CloudflareClient, CloudflareDecisionModel } from \"@effect/ai-cloudflare\"\nimport { Effect, Layer, Schema } from \"effect\"\nimport { Decision, DecisionModel } from \"effect/ai\"\nimport { FetchHttpClient } from \"effect/http\"\n\nconst Triage = Decision.make({\n input: Schema.String,\n decisions: {\n urgent: Decision.probability({\n instructions: \"Does this request need immediate attention?\"\n })\n }\n})\n\nconst Clef = CloudflareDecisionModel.layer({ model: \"clef-flash\" }).pipe(\n Layer.provide(CloudflareClient.layerConfig()),\n Layer.provide(FetchHttpClient.layer)\n)\n\nconst program = DecisionModel.decide(Triage, {\n input: \"Checkout has been failing for every customer for an hour.\"\n}).pipe(Effect.provide(Clef))\n```\n\nPass `images` to include pictures with the input. Clef shows them to the model before the state:\n\n```ts\ndeclare const screenshotBytes: Uint8Array\n\nconst withScreenshot = DecisionModel.decide(Triage, {\n input: \"Customers report this checkout error.\",\n images: [{ mediaType: \"image/png\", data: screenshotBytes }]\n})\n```\n\nImage `data` may be a `Uint8Array`, a base64 string, or a `data:` URL. Remote URLs fail with `AiError.InvalidUserInputError` because Clef does not fetch them, so download the image first. The API accepts up to 4 PNG, JPEG, or WebP images, each at most 4 MiB and 16 megapixels, with 8 MiB of decoded images in total and a 13 MiB request body.\n\nUse `\"clef\"` for the larger model. `CloudflareDecisionModel.model` provides a model descriptor with Cloudflare provider metadata. `CloudflareClient.layer` accepts an explicit account ID and redacted API token; `apiUrl` and `transformClient` customize HTTP access.\n\nInstructions and descriptions can be strings, JSON objects, or JSON arrays. A rating level with a structured description takes an explicit `label`, which answers use.\n\nThe client unwraps Cloudflare's REST envelope and maps failures to `AiError`. It does not retry automatically. Rate-limit errors include `Retry-After` when provided. The decision model validates answers and rescales small probability drift from four-decimal rounding.\n\nCloudflare limits each request to 64 questions, classification to 2–255 choices, and ratings to 2–10 levels. See the [Clef API documentation](https://developers.cloudflare.com/workers-ai/models/clef/) for request limits.\n\n## AI Gateway\n\nSet `CLOUDFLARE_AI_GATEWAY_ID` when using `CloudflareClient.layerConfig()` to route requests through a Cloudflare AI Gateway. You can also pass `gatewayId` to `CloudflareClient.layer`. The client adds the `cf-aig-gateway-id` header. Use `transformClient` to add other `cf-aig-*` headers.\n","packages/ai/openai-compat/README.md":"# @effect/ai-openai-compat\n\nConnects the Effect AI modules to any OpenAI-compatible API, with support for chat completions and embeddings.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-openai-compat\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/ai-openai-compat): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/ai/openai/README.md":"# @effect/ai-openai\n\nAn [OpenAI](https://openai.com) provider for the Effect AI modules. Includes a typed OpenAI API client, language model and embedding model layers, tools, and telemetry helpers.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-openai\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/ai-openai): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/ai/openrouter/README.md":"# @effect/ai-openrouter\n\nAn [OpenRouter](https://openrouter.ai) provider for the Effect AI modules. Includes a typed OpenRouter API client and language model layers.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-openrouter\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/ai-openrouter): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/ai/typesafe/README.md":"# @effect/ai-typesafe\n\nTypeSafe System One provider for Effect's `DecisionModel`. Supports classification, ordered ratings, and probabilities through Effect `HttpClient`.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-typesafe\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/ai-typesafe): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n\n## Usage\n\nUse `TypeSafeClient.layerConfig()` to read `TYPESAFE_API_KEY`, then provide `TypeSafeDecisionModel.model(\"jev-latest\")` to a decision workflow. Versioned model identifiers such as `jev-1.13.0` are also supported.\n\nInstructions and descriptions can be strings, JSON objects, or JSON arrays, as in TypeSafe's [structured questions](https://docs.typesafe.ai/primitives/advanced). A rating level with a structured description takes an explicit label, which answers use:\n\n```ts\nimport { Decision } from \"effect/ai\"\n\nconst severity = Decision.rate({\n instructions: \"How severe is the reported issue?\",\n criteria: [\n { label: \"cosmetic\", description: { what: \"No impact to functionality\", examples: [\"typo in a label\"] } },\n { label: \"degraded\", description: { what: \"Broken, but a workaround exists\", examples: [\"fails in one browser\"] } },\n { label: \"blocking\", description: { what: \"No workaround exists\", examples: [\"cannot log in\"] } }\n ]\n})\n```\n\nThe client does not retry automatically. Rate-limit errors include the provider's retry delay when available. Provider distributions are preserved, not normalized; they must satisfy the core `DecisionModel` validation, including its current `1e-6` sum tolerance. TypeSafe's rounding behavior has not been verified against the live API.\n","packages/atom/react/README.md":"# @effect/atom-react\n\n[React](https://react.dev) bindings for Atom, the reactive state management modules for Effect. Includes hooks for reading and updating atoms, and helpers for server-side rendering hydration.\n\n## Installation\n\n```sh\nnpm install effect @effect/atom-react\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/atom-react): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/atom/solid/README.md":"# @effect/atom-solid\n\n[SolidJS](https://www.solidjs.com) bindings for Atom, the reactive state management modules for Effect.\n\n## Installation\n\n```sh\nnpm install effect @effect/atom-solid\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/atom-solid): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/atom/vue/README.md":"# @effect/atom-vue\n\n[Vue](https://vuejs.org) bindings for Atom, the reactive state management modules for Effect.\n\n## Installation\n\n```sh\nnpm install effect @effect/atom-vue\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/atom-vue): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/effect/README.md":"# effect\n\nEffect is a library for building robust, maintainable, type-safe, and production grade applications in TypeScript.\n\nThe `effect` package is the core of the framework. It provides primitives for managing side effects, errors, concurrency, resources, and structured data, alongside a rich standard library.\n\n> **Effect 4.x is a long-term support (LTS) release**, with at least three years of bug and security fixes. If you are upgrading from Effect 3.x, follow the [migration guide](https://github.com/Effect-TS/effect/blob/main/MIGRATION.md).\n\n## Installation\n\n```sh\nnpm install effect\n```\n\n## Requirements\n\n- **TypeScript 5.9 or newer.** TypeScript 7 is recommended for the best performance and compatibility with [Effect's TypeScript tooling](https://github.com/Effect-TS/tsgo#installation).\n- **Node.js 18 or newer** when running Effect on Node.js.\n- **Strict type-checking:** the `strict` flag must be enabled in your `tsconfig.json`:\n\n ```json\n {\n \"compilerOptions\": {\n \"strict\": true\n }\n }\n ```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/effect): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n\n## Overview\n\nThe `effect` package is a collection of modules. Some of the core ones:\n\n| Module | Description |\n| -------- | -------------------------------------------------------------------------------------------------------------------------- |\n| Effect | The core abstraction for managing side effects, concurrency, and error handling in a structured way. |\n| Context | A lightweight dependency injection mechanism that enables passing services through computations without direct references. |\n| Layer | A system for managing dependencies, allowing for modular and composable resource allocation. |\n| Fiber | Lightweight virtual threads with resource-safe cancellation capabilities, enabling many features in Effect. |\n| Stream | A powerful abstraction for handling asynchronous, event-driven data processing. |\n| Schedule | A module for defining retry and repeat policies with composable schedules. |\n| Scope | Manages the lifecycle of resources, ensuring proper acquisition and release. |\n| Schema | A powerful library for defining, validating, and transforming structured data with type-safe encoding and decoding. |\n\nIn v4, functionality that previously lived in separate packages ships inside `effect` under the `effect/*` namespaces, including `http`, `http-api`, `rpc`, `cluster`, `workflow`, `cli`, `ai`, `sql`, and `reactivity`.\n","packages/effect/runtimeperf/README.md":"# Effect Runtime Performance\n\nThis harness measures focused synchronous runtime paths in fresh Node\nprocesses. It supports:\n\n- focused Effect Schema diagnostics;\n- native Arbitrary comparisons against equivalent fast-check v4 arbitraries;\n- the upstream Effect, Valibot and Zod benchmark matrix;\n- paired comparisons between Git revisions or the current working tree.\n\nCross-library results are diagnostic. Effect base/head comparisons are the\nauthoritative measurement for source changes.\n\n## Commands\n\nRun the complete registry:\n\n```sh\npnpm runtimeperf\n```\n\nRun the cases extracted from the `effect@beta`, Valibot and Zod adapters in\n[`open-circle/schema-benchmarks`](https://github.com/open-circle/schema-benchmarks):\n\n```sh\npnpm runtimeperf schema-benchmarks\npnpm runtimeperf-compare schema-benchmarks --base main --head HEAD\n```\n\nThis suite covers every upstream timing case supported by those adapters:\nschema and decoder initialization, validation, parsing and Standard Schema\nwith valid/invalid inputs and first/all error modes, plus BigInt codec\noperations. The upstream bundle and stack reports are not throughput\nbenchmarks, and the adapters do not define the optional string-format cases.\n\nSelect a suite, fixture, shared scenario, tier, family or implementation:\n\n```sh\npnpm runtimeperf schema\npnpm runtimeperf arbitrary\npnpm runtimeperf object-32-valid\npnpm runtimeperf schema/object-32-valid-effect\npnpm runtimeperf --family arrays\npnpm runtimeperf --implementation zod4\npnpm runtimeperf --implementation zod4-compiled\n```\n\nOverride measurement settings:\n\n```sh\npnpm runtimeperf object-32-valid --rounds 9 --time 500 --warmup-time 150\n```\n\nCompare Effect `HEAD` with the working tree:\n\n```sh\npnpm runtimeperf-compare schema/object-32-valid-effect\n```\n\nMeasure excess-property checking and symbol enumeration in interpreted and JIT parsers:\n\n```sh\npnpm runtimeperf-compare schema-excess-properties\npnpm runtimeperf-compare schema-excess-properties --family jit\n```\n\nCompare explicit refs:\n\n```sh\npnpm runtimeperf-compare schema --base main --head HEAD\n```\n\nOnly `--fail-on-regression` turns a statistically classified regression into a\nnon-zero comparison exit code. Worker, fixture, configuration and Git errors\nalways fail.\n\nReports are written under `tmp/runtimeperf/results/`. Temporary Git worktrees\nare created under `tmp/runtimeperf/worktrees/` and removed in `finally`.\n\n## Registry\n\n`config.json` groups fixture cases by source file. Every case records:\n\n- tier and family;\n- covered Effect AST tags;\n- operation and path;\n- input size;\n- implementation;\n- a shared scenario name for cross-library comparisons.\n\nThe `schema` suite is Effect-only and retains targeted diagnostics for scaling,\ntemplate literals, unions, records, transformations, optional properties,\nadapters, recursion and cold paths. The `schema-benchmarks` suite contains the\ncomplete timing matrices exposed by the upstream Effect, Valibot and Zod\nadapters.\n\nThe `moltar-parse-safe` and `moltar-assert-loose` suites preserve Moltar's\nobject shape. Their valid cases reproduce the upstream timed operation; the\nextra-property and invalid cases are Effect extensions. They compare\ninterpreted Effect, Effect JIT and AOT, Valibot, ordinary and jitless Zod where\napplicable, and Zod `compile`, using the dependency versions recorded in each\nreport.\n\nThe `arbitrary` suite compares the native public API with direct fast-check v4 arbitraries in separate processes. It\nmeasures derivation through the first recursive sample, steady-state recursive\nsampling, optional-Struct sampling, fixed-length string generation to exercise constraint pushdown,\nbounded Number generation, direct Uint8Array generation, a rare residual filter, a fixed-length unique array, and a\nmixed regular expression through cold derivation, warm generation, and shrinking. It also covers literal sampling as\na runner baseline and the public `map`, `filter`, `filterMap`, and `all` combinators for tuples and records. The failure\npaths include a filtered failure with rejected shrink candidates, dependent `flatMap` sampling, shrinking, replay, a\npassing property, a failure that shrinks from `1000` to `1`, and replay of that failure. The\nrecursive distributions are implementation-defined, so the fixtures use\nimplementation-specific size settings and validate a comparable total node\ncount for the fixed seed. The bounded Number case is a throughput comparison,\nnot distribution parity: native selects among 64-bit IEEE-754 representations,\nwhile the fast-check fixture uses its 64-bit `double`. Replay is an\nend-to-end public API comparison, but the work is not identical: native replay\nverifies the original failure and its full shrink path, while fast-check can\nstart directly from its recorded path.\n\nArray cases cover passing checks and shrinking a four-command sequence while preserving an ordered pair. The latter\nstarts from the same explicit sequence in both engines, using a fixed seed for native generation and an example for\nfast-check. Base/head validation preserves the failure without requiring identical shrunk outputs, so its timing also\nreflects changes in how much of the shrink tree is explored. The runtime regression tests assert the smaller result.\n\nThe regular-expression fixtures validate the same language, and both fixed-seed warm fixtures must reach multiple\nlengths and every alternative family. Their exact distributions remain implementation-defined, so cross-library\ntimings are diagnostic while base/head comparisons protect the cost of each implementation's established behavior.\n\nAn impossible Schema filter is deliberately not a cross-engine timing case.\nThe native runner reports bounded exhaustion, while a direct fast-check arbitrary\nbuilt with `Arbitrary.filter` does not return from generation\nwhen no value can satisfy the predicate. Native exhaustion remains covered by\nthe Arbitrary tests instead of placing a permanently blocking fixture in the\nperformance harness.\n\nZod parsing cases import `zod/v4` and call `safeParse` with `{ jitless: true }`;\nits Standard Schema and codec cases use their native APIs. Valibot uses the\ncorresponding `is`, `safeParse` and Standard Schema APIs. The focused Effect\nadapter family measures the overhead of public APIs that wrap parser issues.\nThe compiler comparison calls `z.compile(schema, { strict: true })` and uses\nZod's `validate` API for boolean checks. Ten representative scenarios also run\nagainst equivalent Valibot schemas using `parse` and `is`.\n\n## Measurement model\n\nEach worker validates the fixture before and after measuring. The Effect\nfixture calibrates one batch size that every implementation in the same\nscenario uses. This keeps the enclosing loop identical across implementations;\nV8 can otherwise optimize sub-10 ns callbacks differently at different batch\nsizes. Each implementation executes in a separate process, with rotating order\nwithin the scenario.\n\nTinybench measures one synchronous batched task. The primary process result is:\n\n```text\nnsPerOp = totalTimeMs * 1_000_000 / (task.runs * batchSize)\n```\n\nTinybench latency statistics are retained as diagnostics and normalized by the\nbatch size. Independent Node processes, not Tinybench samples, are the\nstatistical observations.\n\nBase/head comparisons alternate execution order by round and analyze paired\nlog ratios with a deterministic bootstrap. The report keeps all raw worker\nresults so aggregates can be recalculated.\n\n## Fixture contract\n\nEach configured export is a factory:\n\n```ts\ntype RuntimePerfCase = {\n readonly run: () => unknown\n readonly validate: (result: unknown) => void\n}\n\ntype RuntimePerfCaseFactory = () => RuntimePerfCase\n```\n\nConstruct schemas, steady-state adapters and deterministic inputs in the\nfactory. Cold fixtures deliberately construct them inside `run`. A fixture\nmust measure one named operation, perform no I/O and return no Promise.\n\n## Validation\n\n```sh\nnode --test packages/effect/runtimeperf/test/*.test.mts\npnpm exec dprint check package.json packages/effect/runtimeperf\n```\n","packages/effect/runtimeperf/suites/compiler-rebuild/README.md":"# Compiler rebuild comparison\n\nThe `compiler-rebuild` suite measures 25 public SchemaParser operations with the\ninterpreter, selective JIT and generated AOT modules. Nineteen cases also run\nagainst `z.compile(schema, { strict: true })`; eleven representative cases run\nagainst Valibot and Zod with `{ jitless: true }`. The fixture families name the\nexecution mode. Cases\ncover simple and nested Structs, Arrays, tuples, Records, transformed Record\nkeys, anyOf/oneOf Unions, transformations, middleware, recursive and suspended\nschemas, Declarations, construction,\nand successful and failing validation.\n\nThe Effect tuple has a trailing element after its rest element, Zod compilation\ndoes not support recursive schemas or `z.xor`, and Zod has no equivalent\ndecoding middleware. Those four cases intentionally have no Zod fixture. Zod\ncompilation only accelerates forward parsing, so the encode case measures its\ndocumented runtime fallback. Zod parsing stands in for Effect construction\nbecause Zod has no separate constructor operation. Valibot parsing with defaults\nis used for the same comparison.\n\n```sh\npnpm runtimeperf-compare compiler-rebuild --base schema-compiler\npnpm runtimeperf-compare compiler-rebuild --base main --family interpreted\npnpm runtimeperf compiler-rebuild\n```\n\nThe first command compares the current working tree with the archived compiler\nbranch. The second isolates changes to interpreted parsing against main. Schema\nand parser construction are outside the steady-state measurements. AOT fixtures\ngenerate their version-specific module in a separate process before loading it.\n\nThe standard paired harness records five alternating rounds, validates every\nfixture before and after measurement, uses a common batch within each pair, and\nreports bootstrap confidence intervals. Cross-mode rankings are descriptive;\nthe paired base/head comparison is the regression evidence.\n\n## Retained heap and first use\n\nFor a current cross-library comparison of retained heap, V8 code memory, peak\nRSS and preparation CPU, run:\n\n```sh\nnode packages/effect/runtimeperf/suites/compiler-rebuild/run-resources.mts \\\n tmp/schema-compiler-resources.json 5 100,500\nnode packages/effect/runtimeperf/suites/compiler-rebuild/report-resources.mts \\\n tmp/schema-compiler-resources.json\n```\n\nEach sample runs in a fresh process. The report calculates median per-schema\nslopes between 100 and 500 distinct schemas, which removes fixed module and\nlazy initialization costs. Fixture inputs are released before retained-memory\nmeasurement. Preparation CPU includes adapter creation and first use; AOT also\nincludes loading and installing the generated module. AOT source generation is\nreported separately because it runs at build time. Hot synchronous CPU is\nalready represented by the normal runtime measurements.\n\nThe older Effect-only probe below remains available for comparisons with its\nexisting archived results.\n\nThe standalone cost probe accepts a checkout root, mode, operation, shape and\nschema count. Run several fresh processes per combination and alternate the\ncheckout order. Supported modes are `interpreted`, `jit` and `aot`; operations\nare `decode`, `invalid`, `is` and `make`; shapes are `struct`, `array`, `transform`\nand `default`.\n\n```sh\nnode --expose-gc packages/effect/runtimeperf/suites/compiler-rebuild/costs.mts heap \"$PWD\" jit decode struct 500\nnode --expose-gc packages/effect/runtimeperf/suites/compiler-rebuild/costs.mts cold \"$PWD\" jit decode struct 500\n```\n\nHeap measurements exclude schema construction and module imports, and retain\nboth schema objects and public parser functions. They include operation setup\nand first use. Forced GC removes transient parse output and issues. The AOT\ngenerator runs in a separate process, so its retained heap is not attributed to\nthe runtime application.\n\nFirst-use measurements include constructing a fresh schema, installing its\ncompiler when requested, creating a public parser and calling it. They exclude\nmodule imports and AOT source generation. Repeated shapes can benefit from V8's\nsource cache, so this is not process startup latency. Treat these timing probes\nas exploratory, separately from the paired throughput results.\n","packages/effect/runtimeperf/suites/schema-checked-sources/README.md":"# Checked transformation sources\n\nThis suite reconstructs the motivating shape from PR #8597: decode an Array of\n1,000 rows, each containing eleven pattern-checked string fields and one `n`\nfield. The sibling fields match `/^[a-z][a-z0-9]{1,15}$/`, and the checked numeric\nsource matches `/^[0-9]{1,6}$/`. Rows contain `value0` through `value999` and\nnumeric strings `1` through `1000`. Schemas, inputs and parsers are prepared\noutside the measured callback. Each operation decodes all 1,000 rows.\n\n- `digits` validates the checked string without transforming it.\n- `checked-source` converts the checked numeric string to a number.\n- `unchecked-source` converts a plain string to a number.\n- `two-passes` first validates all fields, then decodes the validated output\n with a transformations-only Struct.\n- `checked-template-target` and `unchecked-template-target` convert the `n`\n field to a TemplateLiteral string prefixed with `x-`. They measure valid\n input through the parser fallback required to preserve template diagnostics.\n\nEvery worker validates the complete output before and after measuring. The\ncomparison harness copies the same fixtures into both revisions and alternates\nbase/head order in fresh Node processes.\n\n```sh\npnpm runtimeperf-compare schema-checked-sources --base main --head HEAD \\\n --rounds 16 --time 500 --warmup-time 150\n```\n\nThese fixtures use repository sources. The PR's original figures used packed\npackages on Node 26.10, so compare relative changes rather than absolute times.\n","packages/effect/runtimeperf/suites/schema-construction/README.md":"# Schema construction costs\n\nThis diagnostic measures the current implementation before proposing changes. It leaves library sources unchanged.\nIt measures elapsed construction time in ordinary fresh Node processes, then uses separate V8 CPU-profiled processes\nto locate the work. Profile shares are estimates of sampled execution, not directly timed phases or predicted savings.\n\nRun from the repository root:\n\n```sh\nnode packages/effect/runtimeperf/suites/schema-construction/run.mts tmp/schema-construction 24 1000\n```\n\nArguments are a new output directory, rounds, root count, and an optional comma-separated list of case names.\nThe output directory's parent must exist. Existing output directories are rejected. The source tree must be clean.\nEvery raw observation is saved in `results.json`; raw `.cpuprofile` files can be opened in a CPU profile viewer.\nCopies of the measured harness files are retained in `harness/` to preserve uncommitted analysis code.\nThe report records the commit, source-tree object, harness and lockfile hashes, Node/V8 versions, machine and settings.\nInterrupted or failed runs retain `complete: false` and must not be reported as complete measurements.\n\n## Scope\n\nEach worker imports Schema, prepares fixture keys and validation inputs, and preallocates a root array before timing.\nIt then builds 1,000 new root schemas and retains them until the process exits. The timer includes field-map creation,\nchild schemas, checks, transformations, options and all eager internal work triggered by the declaration.\nThere is no explicit warmup. Schema's own import-time initialization has already run and can warm shared constructors\nand caches. Node startup, TypeScript loading, module imports, decoder preparation and decoding are excluded.\n\nFixtures cover literals; structs with 2, 32 and 256 fields; nested structs; arrays with checks, optional keys and literals;\nnew string-to-number transformations; and unions of eight newly constructed tagged members. Root counts are not counts\nof every intermediate schema. Shared primitive schemas such as `Schema.String` are imported constants. The `struct-N`\nfixtures build field maps with `Object.fromEntries` during timing. The additional `struct-ready-N` fixtures reuse a field\nmap prepared before timing, to isolate `Schema.Struct(fields)` with ready inputs. Primitive schemas, field-name strings\nand sample values are prepared beforehand in both cases. Dynamically generating fields is a distinct caller cost; it\ndoes not model a hand-written object literal's cost.\n\nEach fixture is validated in a separate process before measurement, including valid decode, type-side `.make`, and invalid\ninput rejection. Measured workers check root count, object kind and distinctness after timing. No prior validation warms\nthe measured worker. This protocol makes no claim about complete HttpApi/Confect startup, memory usage or warmed throughput.\n\n## Measurement and attribution\n\nEach round runs ordinary Node, profiling at a requested 100 microsecond interval, and profiling at 500 microseconds.\nWorkers run serially. The six possible orders rotate by round; fixture order also rotates. The default 24 rounds\nbalance all six orders. Do not run other benchmarks, builds or tests alongside the measurement.\n\nElapsed times are medians across independent processes, with median absolute deviation. Profiler perturbation is measured\nthrough paired ratios against the ordinary process in the same round, using the existing deterministic bootstrap with\n10,000 resamples. This is a check on measurement bias, not a comparison of optimized code.\n\nEach CPU sample is assigned to one category:\n\n| Category | Included work |\n| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |\n| `type-projection` | `toType` and its recursive traversal, clones and memoization, during synchronous maker preparation |\n| `ast` | Initial AST construction and changes made by checks, annotations, optional keys and transformations |\n| `schema-object` | Central schema constructor after subtracting identifiable child phases: function object, prototype, options, property and closure setup |\n| `make-sync` | Identifiable synchronous maker factory frames outside the type projection |\n| `make-effect` | Identifiable effectful maker factory frames outside the Option adapter |\n| `make-option` | Option adapter factory, including its separately allocated effectful maker |\n| `schema-api` | Other Schema API work, including composition wrappers and check factories outside AST constructors |\n| `fixture` | Caller-attributed samples: field maps, member lists, the loop, and library work inlined into those frames |\n| `gc` | Garbage collector samples inside the construction window |\n| `runtime` | Other runtime samples without an attributable Schema stack |\n\nChild work is never added again to its parent. V8 can omit an inlined `SchemaParser.make` frame. In these fixtures,\nthe only eager AST/Function subtree beneath central `make` is `toType`; this path is classified as projection even when\nthe parser wrapper is absent. The fixtures do not use options with getters that could invoke arbitrary AST work.\nCompletely inlined work that cannot be separated remains with the caller. The `fixture` category is therefore an\nunresolved caller category, not a measurement of pure benchmark overhead or field-map creation. A ready-field fixture\nwhose body only calls `Schema.Struct(fields)` still receives caller-attributed samples. Small or zero factory shares do not prove\nthat their allocations are free; allocation effects can appear in central construction or GC.\n\nProfiles are delimited by the first and last samples containing the worker's `constructBatch` frame. Samples outside\nthat span are excluded, including inspector setup. Interior GC/runtime samples are retained. Inspector timestamps and\n`hrtime` are not directly compared because their origins can differ. Missing boundary samples, especially GC before the\nfirst or after the last observed construction frame, are a limitation. The report keeps sample counts, sampled span\ncoverage and counts of processes with fewer than ten samples. A profile with no construction samples remains recorded\nand is excluded from share estimates. One sample has zero measured span coverage and is marked sparse.\n\nShares are unweighted sample proportions within each process, averaged across processes. Their 95% intervals bootstrap\nwhole processes, not individual correlated samples. Categories sum to 100% for the point estimates; interval endpoints\nneed not sum to 100%. These intervals cover sampling variability, not profiler bias or attribution errors. Compare the\ntwo sampling frequencies and their overhead before interpreting the shares. Do not convert them into exact milliseconds\nor predicted speedups. Short fixtures may support a reliable elapsed time without a useful internal breakdown.\n\nTop leaf functions and source-position ticks are retained as secondary diagnostics. Source-position ticks are not an\nadditional additive cost breakdown and may accumulate at a function's entry after optimization.\n\n## Validation\n\n```sh\nnode --test packages/effect/runtimeperf/test/*.test.mts\npnpm exec dprint check --includes-override 'packages/effect/runtimeperf/suites/schema-construction/*.mts' 'packages/effect/runtimeperf/test/schema-construction.test.mts'\n```\n\nThe attribution tests cover non-overlapping phases, inlined maker frames, Option's nested effect maker, profile boundaries,\ninterior garbage collection, missing samples and deterministic confidence intervals.\n","packages/effect/typeperf/README.md":"# Effect Type Performance\n\nThis harness measures deterministic TypeScript diagnostics for focused\nfixtures. Type instantiations and materialized types are regression gates, while\nsymbols are reported for additional context.\n\nUse it when a type-level change needs a small regression guard for the specific\ntype path that was optimized.\n\n## Core Model\n\nEach suite has one shared baseline. Fixture cost is reported separately for\ninstantiations, types, and symbols as:\n\n```txt\nmetric delta = fixture metric - suite baseline metric\n```\n\nThreshold files store exact maximum deltas for instantiations and types. Symbol\ndeltas are informational and do not affect the command status.\n\nThe runner compiles each baseline and fixture as an isolated TypeScript program\nby generating temporary `tsconfig` files under `tmp/typeperf`.\n\nFixtures must use realistic package imports:\n\n```ts\nimport { Schema } from \"effect\"\n```\n\nDo not import source files directly, for example do not use\n`../../src/Schema.ts`. The package self-reference should resolve the public\n`effect` package entry.\n\nEvery fixture in a suite should repeat the suite warmup expression from\n`baseline.ts`. For the current Schema suite, that means:\n\n```ts\nimport { Schema } from \"effect\"\n\nSchema.String\n```\n\n## Commands\n\nFrom the repository root:\n\n```sh\npnpm typeperf\npnpm typeperf schema\npnpm typeperf schema/struct-required\npnpm typeperf --update\npnpm typeperf schema/struct-required --update\n```\n\nWithout a target, the runner checks every suite and fixture. A target can be a\nsuite name (`schema`) or an individual fixture (`schema/struct-required`).\n\n`--update` writes exact measured instantiation and type deltas to threshold\nfiles. When a target is provided, only the selected suite or fixture is updated.\n\n## Cross-Ref Comparisons\n\nUse the separate comparison runner when a changeset needs measurements against\nanother Git revision:\n\n```sh\npnpm typeperf-compare httpapi --base main --head HEAD\npnpm typeperf-compare httpapi/endpoint-count-100 --base main --head HEAD\n```\n\nThe runner creates detached worktrees under `tmp/typeperf-compare`, copies the\nsame generated fixture sources into both worktrees, and compiles them with the\nTypeScript installation from the current checkout. Each fixture and baseline is\ncompiled once per revision. The normal `pnpm typeperf` suite and its thresholds\nare not affected.\n\nComparison fixtures use only APIs shared by both revisions. They also contain\ntype-level assertions that reject degenerate results such as missing methods or\n`never` endpoint selections. A fixture is comparable only when the exact same\nsource compiles on both revisions. Results are printed to the terminal and\nwritten as JSON under `tmp/typeperf-compare/results/`, including the resolved\nGit SHAs, TypeScript version, and fixture-suite hash.\n\n## Adding A Fixture\n\nAdd a fixture when a change optimizes one specific constructor, helper, or\ntype-level path.\n\n1. Create one file under the suite's `fixtures/` directory.\n2. Name it after the isolated behavior being measured, for example\n `struct-optional-only.ts`.\n3. Add a first-line comment explaining the single thing being measured.\n4. Use realistic package imports.\n5. Repeat the suite warmup expression.\n6. Build only the schema needed for that one behavior.\n7. Export type aliases that force TypeScript to instantiate the views under\n test.\n8. Add the fixture to `config.json`.\n9. Run `pnpm typeperf / --update`.\n10. Run `pnpm typeperf /`.\n\nExample:\n\n```ts\n// Measures the marginal type-level cost of Schema.Struct when all fields are optional keys.\nimport { Schema } from \"effect\"\n\nSchema.String\n\nconst schema = Schema.Struct({\n id: Schema.optionalKey(Schema.String),\n count: Schema.optionalKey(Schema.NumberFromString)\n})\n\nexport type Type = typeof schema.Type\nexport type Encoded = typeof schema.Encoded\nexport type Iso = typeof schema.Iso\nexport type MakeIn = typeof schema[\"~type.make.in\"]\n```\n\nThen register it:\n\n```json\n{\n \"name\": \"struct-optional-only\",\n \"file\": \"suites/schema/fixtures/struct-optional-only.ts\"\n}\n```\n\n### Fixture Rules\n\n- Measure one thing per fixture. Split separate paths into separate files.\n- Keep inputs realistic, but not large for its own sake.\n- Export the minimum type aliases needed to force the type computation being\n measured.\n- Do not combine multiple optimized APIs just to make the fixture look like an\n application model.\n- Do not add fixtures for unchanged or unrelated APIs.\n- Do not add fixture files to `packages/effect/tsconfig.json`; `pnpm typeperf`\n compiles them independently.\n- If a fixture fails to compile, fix the fixture or source types. Do not hide\n the problem by aggregating it with another fixture.\n\n## Adding A Suite\n\nAdd a suite when fixtures need a different shared baseline. For example,\nSchema-specific fixtures share the `schema` baseline, while HTTP API fixtures\nuse a different import and warmup.\n\n1. Create `suites//baseline.ts`.\n2. Create `suites//fixtures/`.\n3. Create `suites//thresholds.json` with `{}`.\n4. Add a suite entry to `config.json`.\n5. Add at least one focused fixture.\n6. Run `pnpm typeperf --update`.\n7. Run `pnpm typeperf `.\n\nExample suite entry:\n\n```json\n{\n \"name\": \"schema\",\n \"baseline\": \"suites/schema/baseline.ts\",\n \"thresholds\": \"suites/schema/thresholds.json\",\n \"fixtures\": [\n {\n \"name\": \"struct-required\",\n \"file\": \"suites/schema/fixtures/struct-required.ts\"\n }\n ]\n}\n```\n\nThe baseline should contain only the import and warmup common to every fixture in\nthat suite. If a fixture needs extra setup that others do not need, put that\nsetup in the fixture, not in the shared baseline.\n\n## Updating Thresholds\n\nUse `--update` only after verifying that the measured delta is expected.\n\n```sh\npnpm typeperf schema/struct-required --update\npnpm typeperf schema/struct-required\n```\n\n`--update` writes the exact measured deltas as `maxInstantiationsDelta` and\n`maxTypesDelta`. It does not add a margin:\n\n```json\n{\n \"struct-required\": {\n \"maxInstantiationsDelta\": 457,\n \"maxTypesDelta\": 50\n }\n}\n```\n\n## Validation Checklist\n\nAfter adding or changing fixtures:\n\n```sh\npnpm typeperf / --update\npnpm typeperf /\npnpm exec dprint check package.json packages/effect/typeperf\n```\n\nRun the broader suite when the change touches shared runner behavior:\n\n```sh\npnpm typeperf \n```\n","packages/opentelemetry/README.md":"# @effect/opentelemetry\n\nAn [OpenTelemetry](https://opentelemetry.io) integration for Effect. Exports Effect tracing, metrics, and logs through the OpenTelemetry SDK, with `NodeSdk` and `WebSdk` layers for easy setup.\n\n## Installation\n\n```sh\nnpm install effect @effect/opentelemetry\n```\n\nThe relevant `@opentelemetry/*` SDK packages are required as peer dependencies, depending on which features you use.\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/opentelemetry): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/platform/browser/README.md":"# @effect/platform-browser\n\nBrowser implementations of the Effect platform services, including the HTTP client, workers, key-value storage, IndexedDB, clipboard, and geolocation.\n\n## Installation\n\n```sh\nnpm install effect @effect/platform-browser\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/platform-browser): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/platform/bun/README.md":"# @effect/platform-bun\n\n[Bun](https://bun.sh) implementations of the Effect platform services, including the file system, HTTP client and server, sockets, workers, and terminal.\n\n## Installation\n\n```sh\nnpm install effect @effect/platform-bun\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/platform-bun): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/platform/deno/README.md":"","packages/platform/node-shared/README.md":"","packages/platform/node/README.md":"","packages/platform/node/test/cluster-integration/README.md":"","packages/sql/clickhouse/README.md":"","packages/sql/d1/README.md":"","packages/sql/libsql/README.md":"","packages/sql/mssql/README.md":"","packages/sql/mysql2/README.md":"","packages/sql/pg/README.md":"","packages/sql/pg/benchmark/README.md":"","packages/sql/pglite/README.md":"","packages/sql/sqlite-bun/README.md":"","packages/sql/sqlite-do/README.md":"","packages/sql/sqlite-node/README.md":"","packages/sql/sqlite-react-native/README.md":"","packages/sql/sqlite-wasm/README.md":"","packages/tools/api-diff/README.md":"","packages/tools/bundle/README.md":"","packages/tools/docgen/README.md":"","packages/tools/doctest/README.md":"","packages/tools/graphql-generator/README.md":"","packages/tools/npm-promote/README.md":"","packages/tools/openapi-generator/README.md":"","packages/vitest/README.md":""},"files":{".agents/AGENTS.md":"This is the Effect TypeScript monorepo. The git base branch is `main`; use `pnpm` from the repository root.\n\n## Layout\n\n- Core library source, runtime tests, and type tests are in `packages/effect/src`, `packages/effect/test`, and\n `packages/effect/typetest`.\n- Other package families include `packages/ai`, `packages/atom`, `packages/platform`, `packages/sql`, and\n `packages/tools`; standalone packages also live directly under `packages`.\n- Package tests and type tests live beside source in `test` and `typetest` directories.\n- AI documentation sources are in `ai-docs/src`.\n- Changesets are in `.changeset`.\n- Migration sources (v3-to-v4) are in `migration/annotations`.\n- Inspect nearby code before editing.\n\n## Validation\n\nUse the narrowest validation that covers the change:\n\n| Change type | Validation |\n| ---------------------------------- | ---------------------------------------------------------------------------------- |\n| Runtime source or test changes | `pnpm lint-fix`, targeted `pnpm test --run `, `pnpm check` |\n| Type-system behavior or type tests | Targeted `pnpm test-types `, plus `pnpm check` when source types changed |\n| JSDoc text/category/link changes | `pnpm jsdocs --check`, `pnpm lint` |\n| JSDoc example changes | `pnpm jsdocs --check`, `pnpm lint`, root `pnpm doctest --run ` |\n| Docs-only changes | `pnpm lint-fix`; no tests unless examples or code changed |\n\nChoose coverage from the contract being changed. Runtime tests cover executed\nbehavior. Tstyche tests cover intended compiler behavior such as inference,\nassignability, rejection, or displayed public types. An ordinary source edit or\nexported declaration is covered by `pnpm check` unless compiler behavior is part\nof the task.\n\nNever run bare `pnpm test` or `pnpm doctest`; both start the full suite in watch mode. Always pass `--run` and the\nspecific files covering the change. CI runs the full suite.\n\nFor an ad hoc runnable probe, create `scratchpad/.ts`, run it with plain `node`, and remove it when finished.\n\nReport any commands that could not be run.\n\n## Generated Files\n\nDo not edit generated output directly.\n\nSome `index.ts` sections marked with `@barrel` are generated. Do not edit those\nsections manually; update their source modules and run `pnpm codegen`.\nHand-maintained `index.ts` files and unmarked sections are not covered by this\nrule.\n\n`LLMS.md` is generated from `ai-docs/src`, and `migration/v3-to-v4.md` is\ngenerated from `migration/annotations`. Update checked-in third-party assets\nthrough their generator or documented import procedure.\n",".agents/skills/ai-docs/SKILL.md":"---\nname: ai-docs\ndescription: AI documentation. Use when editing ai-docs/src or regenerating LLMS.md.\n---\n\nRead `ai-docs/README.md`; it owns source structure, style, examples, generation,\nand changeset policy.\n\n1. Inspect neighboring source examples and the relevant current `LLMS.md`.\n2. Edit sources under `ai-docs/src`, then run `pnpm ai-docgen`.\n3. Review generated output for ordering, missing content, and unrelated changes.\n4. Run applicable root validation.\n\nThe task is complete when sources and generated output agree, every generated\ndifference is explained, TypeScript checks pass when examples or fixtures\nchange, and applicable checks pass or are reported as not runnable.\n",".agents/skills/bundle-analysis/SKILL.md":"---\nname: bundle-analysis\ndescription: Bundle analysis. Use when measuring current bundle size, comparing stable or selected fixtures, inspecting composition, or cleaning retained comparison state.\n---\n\nRead `packages/tools/bundle/README.md`, then select one workflow:\n\n- **Stable comparison:** `pnpm bundle-compare `. Use `HEAD~1` for the\n latest commit. Read `tmp/bundle-stats.txt` and report non-zero differences.\n- **Selected comparison:** `pnpm bundle-compare-selected --base \n scratchpad/.ts`. Use only user-named or investigation-local fixtures;\n keep temporary fixtures out of the stable corpus.\n- **Composition:** `pnpm bundle-analyze scratchpad/.ts`. Read raw data\n first and report the largest modules, dependency groups, and surprising\n inclusions. Its readable-name output is not an exact size measurement.\n- **Current size:** Build immediately before the direct bundle report so Effect\n packages resolve from current `dist` output.\n- **Cleanup:** Stable comparisons retain `tmp/bundle-base` for reuse unless\n cleanup is requested. Remove selected-comparison state retained with\n `--keep-base` after its final use. Verify cleanup without disturbing unrelated\n worktrees.\n\nThe task is complete when the selected artifact is inspected, requested size or\ncomposition findings are reported, generated paths are named, and comparison\nstate follows the selected workflow's retention policy.\n",".agents/skills/changesets/SKILL.md":"---\nname: changesets\ndescription: Concise PR finalization changesets. Use when implementation scope is complete and focused validation has finished to classify release impact, consolidate the PR's existing changeset, or write its consumer release note.\n---\n\nTreat a changeset as the release note for the complete PR, not as a log of work\nperformed along the way. Finalize it after the current implementation scope and\nfocused validation are complete.\n\n## Workflow\n\n1. Inspect the complete diff from the merge base, including changeset files\n already introduced by the PR, and identify directly affected published\n packages.\n2. Classify impact across source types, runtime behavior, entrypoints, required\n services, lifecycle, and persisted or wire data.\n3. Perform the breaking audit below.\n4. Record a reason no changeset is required, or update the PR's existing\n changeset. Create one only when the PR does not have one. When required, read\n [authoring.md](authoring.md).\n5. Validate package names, frontmatter, bump policy, and a one-sentence\n consumer-facing description, longer only for breaks or required migration.\n\nDo not include unrelated worktree changes.\n\n## PR-level consolidation\n\nThe default is one changeset file per PR. One file can name several packages and\nsummarize several related fixes or additions. Successive prompts, commits, and\nsubtasks within the same PR update that file. If implementation resumes after a\nchangeset was drafted, revise it during the next finalization pass.\n\nUse separate files only when a maintainer requests the split or the PR contains\nindependent changes that need separate release notes.\n\n## Requirement\n\nCreate a changeset for observable runtime behavior changes, including bug\nfixes; exported value or public type changes; entrypoint or export-map changes;\nchanges to required services, errors, ownership, defaults, or lifecycle; and\npersisted, serialization, protocol, or wire-format changes.\n\nTests-only changes, behavior-preserving internal refactors, documentation or\nJSDoc maintenance, and unpublished tooling normally do not need one. When\nunclear, inspect exports and consumer-visible declarations rather than inferring\nfrom source location.\n\n## Breaking Audit\n\nA change is breaking when valid existing consumer code, configuration, or data\nmust change to keep compiling or behaving according to the previous contract.\nAudit every surface:\n\n- **Names and locations:** exports, entrypoints, compatibility exports, and\n module paths.\n- **Call compatibility:** parameters, accepted inputs, overload resolution,\n generic parameters, and defaults.\n- **Result compatibility:** return and error types, output narrowing, members,\n inference, and required services.\n- **Runtime contracts:** defaults, failures, interruption, concurrency,\n ordering, resource lifetime, acquisition, cleanup, and mutation.\n- **Data compatibility:** persisted schemas, encodings, database layouts,\n protocols, and wire formats.\n\nAdditive exports, optional parameters, and behavior-preserving implementations\nare normally non-breaking. A fix restoring the documented contract is normally\nnon-breaking but still needs a changeset when its operational impact is\nconsumer-visible. Verify representative existing calls when overload ordering,\nstructural assignability, or inference makes compatibility uncertain. API diff\noutput is mechanical evidence, not a semantic-version decision.\n\nThe task is complete when every affected contract and published package is\naccounted for and either the no-changeset decision is explicit or the PR has one\nconsolidated, valid changeset by default. Its release note is one sentence of\nconsumer impact, plus migration steps for every break, with no implementation\ndetail.\n",".agents/skills/changesets/authoring.md":"# Authoring changesets\n\nUpdate the changeset already introduced by the PR. If there is none, create one\n`.changeset/.md` for the complete PR:\n\n```md\n---\n\"effect\": patch\n\"@effect/affected-package\": patch\n---\n\nFix `Effect.cachedInvalidateWithTTL` caching a stale result when invalidated while the effect is running.\n```\n\nWrite one short sentence, usually under 25 words, that names the changed API\nand states what consumers will notice. That sentence is the whole entry unless\nthe change is breaking or consumers must migrate.\n\nLeave out how the change works: internal modules, algorithms, data structures,\nrefactors, motivation, benchmarks, test coverage, and development history. They\nbelong in the PR description. Cut any sentence a consumer would not act on.\n\n- Bad: \"Rework the `MemoMap` lookup so `Layer.provide` checks identity before\n building, adding a cache keyed by layer reference and tests for shared\n layers.\"\n- Good: \"Fix composed layers being rebuilt for every parent that references\n them.\"\n\nAdd detail only for a break or required migration: what existing code must\nchange and how. Use compact bullets, one break per bullet, when several breaks\nneed migration steps. Several non-breaking fixes or additions still share one\nsentence.\n\nList every directly affected published package. Do not list packages merely\nbecause they share the fixed release group in `.changeset/config.json`.\n\nChoose the bump from current release policy:\n\n- Use `patch` for compatible fixes, `minor` for compatible additions, and\n `major` for breaks.\n- A break confined to APIs tagged `@stability unstable` is `minor`. A break\n confined to APIs tagged `@stability experimental` is `patch`. APIs tagged\n `@stability stable` follow strict semver.\n- Use `major` only when a maintainer has approved a major release.\n- The release queue retargets PRs with `minor` changesets to `v4/next-minor`\n and PRs with `major` changesets to `v4/next-major`. Choose the level the\n change requires, not the branch you want it to land on.\n- Ask when release intent is ambiguous.\n\nUse a `### Breaking changes` section when several breaks need separate\nscanning. Include before/after examples only when they materially clarify\nmigration.\n\nValidate frontmatter against published package names and inspect nearby current\nchangesets for release convention. Do not copy the length of longer entries.\nNever run `changeset-version` or `changeset-publish` as contributor validation.\n",".agents/skills/ci-maintenance/SKILL.md":"---\nname: ci-maintenance\ndescription: GitHub Actions maintenance. Use when authoring or reviewing workflows or composite actions, especially event, permission, action-reference, artifact, setup, or concurrency changes.\n---\n\nAudit the trust boundary before editing. This skill owns Actions event\nsemantics, workflow security, permissions, action pinning, setup reuse,\nuntrusted inputs, timeouts, concurrency, and artifact trust boundaries.\n\n## Workflow\n\n1. Decide whether this is a review or an implementation. Reviews produce\n evidence-backed findings without editing; implementations continue through\n the smallest boundary-preserving change.\n2. Inspect every affected workflow, composite action, and caller. List all\n affected jobs and actions before proceeding.\n3. For each job, record the trigger, actor/fork status, workflow revision,\n checked-out revision, permissions, credentials, and every external input and\n consumer. Include artifacts, caches, outputs, PR fields, refs, dispatch\n inputs, generated files, and called actions.\n4. Consult current GitHub documentation for every platform-sensitive decision.\n Repository examples establish local convention, not platform semantics.\n5. Apply every applicable rule:\n - Default workflow permissions to empty and grant minimal job permissions.\n - Reuse the repository's shared setup action unless the environment must differ.\n - Give executable jobs intentional matrices and realistic timeouts.\n - Pin external actions and reusable workflows to full commit SHAs with\n readable release comments; verify each SHA belongs to that upstream release.\n - Analyze event choice, checkout revision, and credential persistence\n together.\n - Pass untrusted expressions through environment variables; validate and\n quote them before use.\n - Derive concurrency from interruption safety.\n6. For forks, privileged credentials, publication, or cross-run data, read\n [privileged-workflows.md](privileged-workflows.md).\n7. Run the narrowest syntax and repository checks, inspect the complete diff,\n and identify behavior testable only on GitHub-hosted runners.\n\nFor local patterns, inspect the current shared setup action and the nearest\nworkflow with the same trust boundary. Use ordinary check workflows for routine\nprecedent and privileged publication workflows only for equivalent trust\nboundaries.\n\nThe task is complete when every affected job and caller has a recorded trust\nboundary, every applicable rule has evidence or a compensating control, local\nchecks pass, and GitHub-only verification is identified. Reviews report every\nfailure with evidence; implementations resolve every failure and contain only\nintended behavior.\n",".agents/skills/ci-maintenance/privileged-workflows.md":"# Privileged Workflows\n\n- Privileged jobs must not run untrusted repository code with secrets or write\n credentials.\n- Validate cross-run data for expected source, identity, type, shape, and\n bounded size before using it in commands, outputs, APIs, or comments.\n- Require the intended approval boundary before fork-originated work reaches\n privileged execution.\n- Preserve publication and other irreversible operations until completion;\n cancel only replaceable checks and previews.\n- Make checkout revision and credential persistence explicit. Account for\n every write permission and credential.\n\nSearch current workflows by event, job purpose, action, and permission to find\nthe nearest precedent for fork approval gates, publication, non-cancelable\nconcurrency, and validation of cross-run artifacts before privileged use.\n\nConsult current GitHub documentation for event, token, secret, permission,\ncheckout, artifact, reusable-workflow, and environment semantics. Start with\nthe workflow events, workflow syntax, and secure-use references.\n",".agents/skills/dependency-maintenance/SKILL.md":"---\nname: dependency-maintenance\ndescription: Dependency maintenance. Use when adding, moving, or upgrading dependencies, changing pnpm or JavaScript runtimes, updating TypeScript or build/test tools, or changing native-build policy, patches, or test images.\n---\n\nTreat an upgrade as a synchronization task, not a lockfile refresh. Derive\nversions, commands, and compatibility points from the current repository.\n\n## Discover\n\n1. Read affected manifests and scripts, `pnpm-workspace.yaml`, setup actions,\n workflows, test configuration, and compatibility documentation.\n2. Search for the dependency and every current version, range, runtime input,\n image, engine constraint, patch, and compatibility claim.\n3. Record each match as a development version, tested version, peer range,\n engine minimum, advertised minimum, or intentionally different constraint.\n4. When adding or moving a manifest entry, read\n [manifest-roles.md](manifest-roles.md) before selecting its role.\n5. Select the package-local or coordinated branch and its validation matrix.\n\nDiscovery is complete when every match and affected validation surface is\naccounted for.\n\n## Package-local branch\n\nUse this branch only for one dependency in one workspace package when runtime,\ncompiler, package-manager, image, patch, native-build, and shared-tooling policy\nare unchanged.\n\nUpdate only the owning manifest and keep peer compatibility independent from\nthe development version tested here. If any coordinated surface appears,\nswitch branches.\n\nThis branch is complete when the manifest and lockfile agree, focused checks\npass, and every search result is intentionally unchanged or package-local.\n\n## Coordinated branch\n\nRead [coordinated-upgrades.md](coordinated-upgrades.md), select every applicable\nrow, and update all listed synchronization points before installing. Apply root\nworkflow and generated-file requirements before editing those surfaces, then\nreturn here to finish matrix and lockfile review.\n\n## Install and finish\n\nRun root `pnpm install` after all selected edits. Inspect warnings and the\nsemantic lockfile diff for specifiers, resolutions, duplicate transitives, peer\nchanges, integrity, patch hashes, lifecycle scripts, and `allowBuilds` effects.\nA successful install alone does not complete this review.\n\nRun the narrowest correctness and performance checks that cover every selected\nmatrix row.\nApply the root changeset routing after implementation and focused validation.\n\nThe task is complete when repeated repository searches find no unclassified\nsynchronization point, manifest roles and compatibility ranges are intentional,\nthe lockfile has no unexplained churn, and every selected check passes or is\nreported as not runnable.\n",".agents/skills/dependency-maintenance/coordinated-upgrades.md":"# Coordinated Upgrades\n\nSelect every applicable row and derive commands from the cited current source.\n\n| Change | Synchronize | Validation source |\n| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |\n| Shared dependency or test/build tool | Owning manifests, peer/development pairs, configs, and generated artifacts owned by that tool | Root/package scripts and affected Vitest projects |\n| pnpm | Root `packageManager`, workspace settings, setup/cache assumptions, workflows, and lockfile format | Current install, lint, check, build, and focused test scripts |\n| Node, Deno, or Bun | Setup inputs, workflow jobs, engines, runtime metadata, compatibility docs, and runtime config | Current runtime workflow jobs and test configuration |\n| TypeScript support or compiler | Compiler/tooling dependencies, `test-types` target, CI target, tool peer ranges, compatibility docs, and typetests | Targeted typetests; typeperf protocol for measured paths |\n| Native package or install policy | Owning manifests and `pnpm-workspace.yaml#allowBuilds` | Fresh install plus focused package build and tests |\n| Patched dependency | Manifest/range, `patchedDependencies`, patch file, and lockfile patch hash | Fresh install and the behavior that required the patch |\n| Container image or Testcontainers package | Workflow pre-pulls, image call sites, manifests, and integration project names | Current integration workflow and Vitest configuration |\n\nFor a patched dependency, test the new release without the patch when feasible.\nRemove obsolete registration and patch files. Otherwise refresh the patch using\nthe current pnpm workflow and verify both that it applies and that the original\npatched behavior still requires it.\n\nWhen an upgraded component lies on a measured path, use the repository's\nruntimeperf or typeperf comparison protocol rather than inventing a benchmark.\n",".agents/skills/dependency-maintenance/manifest-roles.md":"# Manifest Roles\n\nInspect the nearest package with the same integration shape, then justify each\nadded or moved entry:\n\n| Role | Use when | Completion check |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |\n| `dependencies` | Published runtime code requires its own installed copy. | A packed consumer receives it without adding an undeclared package. |\n| `peerDependencies` | Consumers provide a compatible shared package or the public contract integrates with their copy. | The range states supported consumer versions; add a development entry when local build or tests need an installed copy. |\n| `devDependencies` | Only repository build, test, type, benchmark, or code-generation work needs it. | Published runtime code and declarations do not require consumers to install it. |\n| `optionalDependencies` | A runtime feature handles absence and installation failure must not block the base package. | Focused tests cover present and absent behavior. |\n| Optional peer via `peerDependenciesMeta` | A consumer-provided integration is genuinely optional. | The peer remains in `peerDependencies`, and code requires it only when selected. |\n\nRole selection is complete when every changed entry has one justified role and\npeer compatibility remains independent from repository validation versions.\n",".agents/skills/effect-development/SKILL.md":"---\nname: effect-development\ndescription: Effect development guidance. Use when implementing or reviewing code that composes Effect APIs or patterns, or that adds or changes API signatures.\n---\n\nUse the repository's AI documentation as targeted reference, not ambient\ncontext:\n\n1. Identify the Effect APIs and concepts involved in the change.\n2. Search `LLMS.md` and `ai-docs/src` for those names and concepts, then read\n the matching sections and examples.\n3. Apply the relevant guidance and inspect nearby source and tests for any\n repository-internal conventions not covered by the documentation.\n\nThe task is ready for implementation when every material Effect API or pattern\nhas matching local guidance, or the search has established that none exists.\n\n## API conventions\n\nWrite option types inline in the signature by default. Mark fields `readonly`\nand add `| undefined` to optional fields:\n\n```ts\nexport const make = (options: {\n readonly capacity: number\n readonly strategy?: \"dropping\" | \"sliding\" | undefined\n}): Effect.Effect => ...\n```\n\nDeclare a named options type only in these cases:\n\n- A substantial set of options is shared across several APIs, so a named type\n keeps them in sync.\n- The options type needs complex conditional logic, such as conditional or\n mapped types driven by type parameters.\n\nA long option list for a single API is not on its own a reason to extract a\nnamed type.\n",".agents/skills/jsdocs/SKILL.md":"---\nname: jsdocs\ndescription: Public API JSDoc. Use when authoring or reviewing Effect API documentation, refining a module's documentation, or fixing documentation related diagnostics.\n---\n\n## Workflow\n\n1. Inspect the declaration, implementation, nearby JSDoc, tests, and call sites.\n2. Select every applicable branch and load its reference before editing:\n - tags, modules, or links: [declarations.md](declarations.md);\n - categories: [categories.md](categories.md);\n - examples: [examples.md](examples.md).\n3. Make a focused API fix or module refinement. Preserve verified facts and\n valuable examples rather than rewriting mechanically.\n4. For module refinement or APIs with close alternatives, audit `@see` links\n and inspect implementation and tests for concrete `**Gotchas**`.\n5. Run `pnpm jsdocs --check` and every applicable root validation command.\n\n`@internal` declarations and default exports are outside public JSDoc\nauthoring. Checked files do not support exported enums or empty export\ndeclarations.\n\nPublic declarations use a multiline block with one self-contained practical\ndescription paragraph. Start functions and methods with a present-tense action;\nmatch nearby noun-family phrasing for values. Optional non-empty sections appear\nonce in this order: `**When to use**`, `**Details**`, `**Gotchas**`. Separate\ndescriptions, sections, examples, and tags with one blank line. `**When to\nuse**` states a positive use case distinct from the description; reserve\n`**Gotchas**` for concrete caveats and failure modes.\n\nThe task is complete when every changed public declaration satisfies each\napplicable reference, the checker passes, runnable examples pass their targeted\ndoctest, and all other applicable root checks pass or are reported as not run.\n",".agents/skills/jsdocs/categories.md":"# Categories\n\nRoot declarations require one non-empty `@category`. Reuse nearby categories;\nprefer lowercase plurals and gerunds while preserving canonical domain casing.\n\nCommon categories include:\n\n- Shapes: `constructors`, `destructors`, `models`, `schemas`, `guards`,\n `predicates`, `getters`, `accessors`, `instances`, `constants`, `protocols`,\n `prototypes`, `re-exports`, `unsafe`, `testing`.\n- Effect: `services`, `tags`, `layers`, `context`, `resource management`,\n `running`, `errors`, `error handling`.\n- Operations: `combinators`, `filtering`, `mapping`, `sequencing`, `zipping`,\n `combining`, `merging`, `converting`, `transforming`, `folding`, `splitting`,\n `repetition`.\n- Shared: `utility types`, `encoding`, `decoding`, `serialization`, `tracing`,\n `metrics`, `logging`, `annotations`, `references`, `symbols`, `type IDs`,\n `configuration`, `math`, `comparisons`, `ordering`.\n\nKeep these boundaries: services are contracts, tags identify services, and\nlayers provide them; getters retrieve values while accessors read context;\nerrors model failures while error handling recovers or maps them; models are\ndomain data while utility types are type-level contracts; guards narrow while\npredicates return booleans.\n",".agents/skills/jsdocs/declarations.md":"# Tags, Modules, And Links\n\n## Declaration Shape\n\nUse a multiline JSDoc block for a public declaration:\n\n````ts\n/**\n * Short description as one paragraph.\n *\n * **When to use**\n *\n * Optional practical usage guidance.\n *\n * **Details**\n *\n * Optional details for complex behavior.\n *\n * **Gotchas**\n *\n * Optional concrete caveats.\n *\n * **Example** (Parsing JSON)\n *\n * ```ts import.meta.vitest\n * operation() // => expected\n * ```\n *\n * @category constructors\n * @since 1.0.0\n */\n````\n\nWrite practical English about the public concept, not its implementation. Start\nfunctions and methods with a present-tense action such as `Creates`, `Returns`,\nor `Converts`; match nearby noun families for values, such as `Schema for`,\n`Layer that`, or `Service that`.\n\nOptional non-empty sections appear once in this order: `**When to use**`,\n`**Details**`, `**Gotchas**`. Separate descriptions, sections, examples, and\ntags with exactly one blank line. Use prose for one fact and bullets for\nparallel facts. Do not add other headings.\n\n`**When to use**` states a positive use case distinct from the description and\nbegins with `Use to`, `Use when`, `Use as`, or `Use with`. Put sibling\ncomparisons in `@see`. Reserve `**Gotchas**` for concrete preconditions, edge\ncases, surprising behavior, and important failure modes.\n\n## Tags\n\nDeclaration tags appear in this order:\n\n1. `@deprecated`\n2. `@default`\n3. `@see`\n4. `@stability`\n5. `@category`\n6. `@since`\n\n- Roots require stable-semver `@since` and no `@default`; category requirements\n live in [categories.md](categories.md).\n- Namespaces and their declarations require stable-semver `@since`, permit\n `@category`, and reject `@default`.\n- Member JSDoc is optional; when present it permits stable-semver `@since` and\n non-empty `@default`, rejects `@category`, and follows the prose contract.\n- Any declaration permits one non-empty `@deprecated` and repeated non-empty\n `@see` tags.\n- Roots, export specifiers, and root namespaces require `@stability stable`,\n `@stability unstable`, or `@stability experimental`. Use `unstable` when an\n API may receive breaking changes in minor releases, `experimental` when it may\n receive breaking changes across patch versions, and `stable` otherwise.\n- Tag any API that exposes a third-party dependency `@stability unstable`: an\n accessor to the underlying client or instance, options typed as the\n dependency's options, constructors that accept its instances, re-exports of\n it, and signatures that mention its types. Tag the whole module when it exists\n to wrap the dependency; otherwise tag only the exposing declarations or\n members. Runtime built-ins (Node, Bun, Deno, DOM) and framework types inherent\n to a binding (React, Solid, Vue) are exempt.\n\nUse canonical `**Example**` sections rather than `@example` tags or loose code\nfences.\n\n## Modules And Links\n\nWhen present, the first top-level JSDoc is the module block unless TypeScript\nattaches it to a non-import first declaration. An `@internal` module is omitted.\nModule prose does not use the declaration template. Its tags are optional\nnon-empty `@deprecated`, repeated non-empty `@see`, required `@stability`, then\nrequired stable-semver `@since`. Its examples and links follow the declaration\ncontracts.\n\nInline `{@link Symbol}` targets must resolve to TypeScript symbols; use normal\nMarkdown links for URLs. Prefer code formatting when navigation does not help a\nreader understand or choose the API.\n\nUse `@see` only for a verified related public API: a close alternative,\ninverse, complement, level variant, or closely returned, consumed, or\nconfigured type. Explain non-obvious relationships. Exclude implementation\ndependencies, broad concepts, example-only helpers, private APIs, and merely\nlexical matches.\n",".agents/skills/jsdocs/examples.md":"# Examples\n\nExamples are optional. Keep or add one only for behavior not evident from the\nsignature, meaningful composition, or useful inference or narrowing. Replace\nor remove examples that are trivial, misleading, contrived, or\nscaffolding-heavy.\n\nUse `**Example** (Unique use-case title)`, optional prose, and exactly one\nnon-empty `ts` fence. Titles must remain unique after trimming and lowercasing.\n\nRead `packages/tools/doctest/README.md` for runnable-fence and inline-assertion\nsyntax. Additionally:\n\n- Use public imports and arrange nontrivial examples as setup, operation, then\n semantic observation.\n- The transform does not run Effects or await promises automatically. Prefer\n awaited `Effect.runPromise`; use `Effect.runSync` only when synchronous\n execution is the documented contract.\n- Keep type-level examples marked without tautological runtime assertions.\n- Leave examples that register tests and intentionally non-executable examples\n as plain `ts` fences.\n- Use `Ref`, `Deferred`, or `Queue` rather than mutable probes for concurrency,\n interruption, or races.\n\nIf example research suggests an implementation or type bug, report it instead\nof changing runtime code during a documentation-only pass.\n",".agents/skills/migration-guidance/SKILL.md":"---\nname: migration-guidance\ndescription: Use when changing how a v3 public API maps to v4, editing migration annotations, or regenerating migration/v3-to-v4.md.\n---\n\nUpdate guidance when a v3 public module or API is renamed, moved, removed,\nreplaced, or gains a materially different v4 contract. A v4-only API without a\nv3 counterpart does not automatically need an annotation.\n\n1. Account for every affected v3 symbol.\n2. Read [annotations.md](annotations.md) before adding or changing annotation\n YAML. Verify every suggested replacement against implementation and tests.\n3. When checking or regenerating the reference, or when the API change exists in\n a committed ref, read [generation.md](generation.md). Otherwise report that\n generation is deferred.\n4. When output was generated, inspect it for unrelated movement and stale refs.\n\nThe task is complete when every affected v3 symbol is accounted for, annotation\nreplacements are verified, checks and generation succeed when the change is in\na committed ref, and every generated difference is explained. Report deferred\nchecks explicitly for uncommitted API changes.\n",".agents/skills/migration-guidance/annotations.md":"# Migration Annotations\n\nAdd or update one YAML file per v3 module under `migration/annotations/`. Use\nstable API IDs without trailing `#type` or `#value` facets:\n\n```yaml\neffect/Effect#async:\n replacement: Effect.callback\n note: Use the callback constructor.\n example: Effect.callback((resume) => resume(Effect.void))\n```\n\nEvery annotation requires `replacement` and `note`; `example` is optional. Use\n`replacement: none` when there is no direct replacement and explain the\nsupported migration strategy instead of inventing an equivalent API.\n",".agents/skills/migration-guidance/generation.md":"# Generated Migration Reference\n\n`migration/v3-to-v4.md` is generated. Check annotations and regenerate using\nexplicit committed refs containing the change:\n\n```sh\npnpm api-diff --base-ref origin/v3 --head-ref HEAD --check\npnpm api-diff --base-ref origin/v3 --head-ref HEAD --write-doc migration/v3-to-v4.md\n```\n\nThe API diff reads refs through detached worktrees. If the API change is\nuncommitted, `HEAD` does not contain it. Update known annotation IDs, defer the\ncheck and regeneration, and report the limitation. Do not create a temporary\ncommit solely to run the tool.\n",".agents/skills/package-development/SKILL.md":"---\nname: package-development\ndescription: Package registration. Use when adding a workspace package, making a private package publishable, renaming a package, or moving its workspace path.\n---\n\nTreat package work as a registration change, not a directory copy.\n\n## Workflow\n\n1. Inspect the closest package in the same family. Classify publication status,\n runtime, test environment, platform support, barrels, and dependency shape.\n Justify each proposed file by precedent or an explicit repository need.\n Continue when every proposed file is justified.\n2. Create or move only required source, test, TypeScript, and manifest files.\n When manifest dependencies change, read [dependencies.md](dependencies.md)\n and classify every entry by role.\n Continue when pnpm discovers the intended name and manifests reference no\n absent file.\n3. Read [registration.md](registration.md). Classify every registration surface\n as applicable or not applicable and update every applicable surface.\n Continue when every surface is classified and old references are explained.\n4. For a published package, read [publishing.md](publishing.md) and verify its\n development and packed surfaces.\n5. Run codegen when the package owns generated barrels, then inspect generated\n sections rather than editing them manually.\n Continue when generated sections match source modules without manual edits.\n6. Run focused package tests and scripts plus applicable root checks. Include\n public API type tests when applicable. For published packages, build and dry\n pack the package as described in [publishing.md](publishing.md).\n Continue when focused and root checks pass and the packed surface is intended.\n7. Apply root changeset, generated-file, documentation, and workflow routing.\n\nThe task is complete when package discovery, registration, generated output,\nvalidation, packed output, and changeset routing are all verified or reported\nas not applicable.\n",".agents/skills/package-development/dependencies.md":"# Package Dependencies\n\nInspect the closest package with the same publication and integration shape.\nClassify every manifest entry by the role it serves:\n\n| Role | Use when |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------ |\n| `dependencies` | Published runtime code requires the package to receive its own installed copy. |\n| `peerDependencies` | Consumers provide a compatible shared package or the public contract integrates with their copy. |\n| `devDependencies` | Only repository build, test, type test, benchmark, or code generation needs the package. |\n| `optionalDependencies` | A runtime feature handles absence and installation failure must not block the base package. |\n| Optional peer via `peerDependenciesMeta` | A consumer-provided integration is genuinely optional. Keep its version in `peerDependencies`. |\n\nUse `workspace:^` for workspace packages unless neighboring packages establish a\ndifferent policy. When local build or tests need an installed peer, add the peer\nto `devDependencies` at the repository's tested version while keeping the peer\nrange based on supported consumer versions.\n\nDerive external versions from current consumers with the same integration\nshape. Add only direct requirements; do not copy a neighboring manifest entry\nthat the new package's runtime, declarations, build, or tests do not use.\n\nAfter editing manifests, run root `pnpm install`. Inspect warnings and the\npackage's `pnpm-lock.yaml` importer for intended specifiers and resolutions. If\na dependency has an install or native build, classify it under\n`pnpm-workspace.yaml#allowBuilds` using current repository policy.\n\nThis branch is complete when every entry has one justified role, workspace and\npeer ranges follow repository policy, the lockfile importer agrees with the\nmanifest, and install/build policy is explicit.\n",".agents/skills/package-development/publishing.md":"# Publishing A Package\n\nCompare the package manifest with a neighboring published package in the same\nfamily.\n\n- Keep development `exports` and `publishConfig.exports` aligned by key.\n Source targets become their intended built targets; blocked internal and\n legacy paths remain blocked.\n- Check current AI documentation copy tooling and the package `files` list for\n every file required in the published payload.\n- Ensure each public source entrypoint has exactly one published counterpart\n and no internal entrypoint becomes exposed.\n\nRun the current root build so publication payload generation executes. Create a\ntarball in a temporary destination without publishing, inspect its file list,\nand inspect the packed `package.json` whenever manifest transformation matters.\n\nThis branch is complete when package and root checks pass and the packed\nsurface contains exactly the intended files, exports, and metadata.\n",".agents/skills/package-development/registration.md":"# Package Registration\n\nUse current configuration and the closest package in the same family as the\nsources of truth. A package-local build does not prove repository registration.\nClassify every row as applicable or not applicable.\n\n## Workspace And TypeScript\n\n| Surface | Check |\n| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `pnpm-workspace.yaml` | Its globs cover the package path and exact-name pnpm selection discovers it. |\n| `pnpm-lock.yaml` | The current importer, name, and dependencies exist; renamed or moved importers are gone. |\n| `tsconfig.packages.json` | Packages intended to participate in the root TypeScript project-reference graph are referenced. Follow neighboring package policy; buildable private tools are not automatically included. |\n| `tsconfig.tests.json` | Broad test globs cover the path. Add source aliases only when tests require workspace source routing or would otherwise create a dependency cycle. Preserve intentional platform exclusions. |\n\n## Tests And Documentation\n\n| Surface | Check |\n| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `vitest.config.ts` | A package with runtime tests has the intended project, environment, setup, and inclusion rules. |\n| `tstyche.json` | Type-test discovery covers the package depth; current globs cover one- and two-level package layouts. |\n| `vitest.docs.ts` | Doctest source discovery covers packages with runnable JSDoc examples; current globs cover one- and two-level package layouts. |\n| `jsdocs.config.json` | Public source is included in JSDoc checks and exclusions by package family remain intentional. |\n| `deno.json` | Deno checks cover the package family, or its exclusion is intentional. |\n\n## Release And Discovery\n\n| Surface | Check |\n| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `.changeset/config.json` | Published fixed-group membership uses the current name; private tooling is not added solely because it builds. |\n| `README.md` | Public catalog entries have the current name, path, description, and documentation link. |\n| AI documentation copy tooling and package `files` | Published payloads include required generated documentation. Continue with [publishing.md](publishing.md) for the full packed-surface audit. |\n| Snapshot publishing workflows | Snapshot publishing selects the package path. Existing globs may already cover it; apply root workflow requirements before editing. |\n| Runtime-specific CI workflows | Runtime-specific packages participate in applicable runtime jobs; apply root workflow requirements before editing. |\n\n## Paths And Consumers\n\nAudit explicit workspace package names in root tooling manifests. Search scripts\nfor the package family, old name, and old path to find path-sensitive clean,\ncodemod, circularity, copy, and related behavior. Explain every remaining old\nreference after a rename or move.\n",".agents/skills/performance-analysis/SKILL.md":"---\nname: performance-analysis\ndescription: Performance analysis. Use for runtime throughput or latency benchmarks, TypeScript compiler cost, performance regressions, comparison harnesses, or thresholds.\n---\n\nValidate correctness with focused tests before measuring. Compare the same\nfocused operation and environment across revisions; a single unpaired run is\nnot evidence of improvement.\n\nSelect every applicable branch:\n\n- **Runtime performance:** Read [runtime.md](runtime.md).\n- **Type performance:** Read [types.md](types.md).\n\nThe task is complete when every selected branch meets its measurement and\nreporting criteria and applicable root checks pass or are reported as not\nrunnable.\n",".agents/skills/performance-analysis/runtime.md":"# Runtime Performance\n\nFor authoritative base/head comparisons or fixture work, read\n`packages/effect/runtimeperf/README.md`. Use `pnpm runtimeperf-compare\n` for local worktree comparisons and explicit `--base`/`--head`\nonly for committed refs. Report the resolved comparison head and measurement\nconfiguration.\n\nFor exploratory scripts under `benchmark/`, match nearby Tinybench scripts,\nkeep setup outside the measured callback unless setup is the operation, warm\nreusable state, close resources, and print the table. Label results exploratory\nunless the task defines a repeatable comparison protocol.\n\nFocused runtimeperf work is complete when fixture validation and the selected\nrun succeed. Comparison work additionally requires every configured round to\nsucceed, the paired statistical classification to support the conclusion, and\nresolved refs and settings to be reported. Harness changes require its focused\nchecks. Tinybench work is complete when resources close, the table is reported,\nand claims remain exploratory unless a repeatable protocol was run.\n",".agents/skills/performance-analysis/types.md":"# Type Performance\n\nRead `packages/effect/typeperf/README.md` before adding fixtures, changing the\nharness, updating thresholds, or running cross-ref comparisons. Isolate one\nrealistic public type path and compare the same fixture and compiler environment\nacross revisions. Derive supported suites and comparison commands from the\ncurrent harness documentation and CLI.\n\nBefore changing a threshold, record its previous value and measured result,\nexplain the expected delta, update it, and run a clean focused verification.\nKeep ordinary threshold fixtures separate from cross-ref fixtures.\n\nThis branch is complete when the focused measurement is repeatable, threshold\nverification is clean when applicable, and reported comparisons include\nresolved refs, compiler version, and an explanation of the observed delta.\nFixture or harness changes also require the focused validation and formatting\nchecks documented in the README.\n",".agents/skills/pull-requests/SKILL.md":"---\nname: pull-requests\ndescription: Pull request finalization. Use when a change works and is about to be opened as a pull request, or when updating or continuing an existing one.\n---\n\nA pull request is ready when its tests, implementation, comments, and changeset\nare each the simplest that cover the intended behavior. Draft PRs can be used\nearlier; finishing means making the PR ready for review.\n\n## Workflow\n\nRun each step in a fresh-context subagent when available; otherwise run it\nyourself. Pass along the task context and prior results so each step can check its gate.\n\n1. Keep tests focused. Read [test-development](../test-development/SKILL.md) for\n test placement and type. Cover each intended behavior once, in the existing\n test file for the module.\n For changes needing no tests, record why.\n Continue when removing any remaining case would leave intended behavior\n uncovered, or no tests are needed.\n2. Simplify the implementation. With the tests passing, look for a simpler or\n more idiomatic version: reuse helpers and patterns from nearby source and\n [effect-development](../effect-development/SKILL.md), and remove debugging\n code, scaffolding, and changes unrelated to the task.\n Continue when applicable targeted tests pass and every hunk in the diff\n from the merge base is required by the task.\n3. Review the full diff from the merge base as a maintainer would: correctness,\n failure and interruption paths, resource cleanup, naming and API\n consistency with neighboring modules, and documentation. Fix findings and\n review again.\n Continue when a review pass produces no findings.\n4. Clean up. Remove comments that restate code or narrate the change; keep the\n rest short and about why. Finalize the changeset with\n [changesets](../changesets/SKILL.md).\n Continue when comments explain only what code cannot, and the changeset\n describes the final consumer impact or the no-changeset reason is recorded.\n5. Run the validation in the [AGENTS.md validation table](../../AGENTS.md#validation)\n for each change type in the diff. Fix failures caused by the change; if\n fixes alter the diff, repeat the affected passes.\n Continue when applicable checks pass or commands that cannot run and their\n blockers are recorded.\n6. Open or update the pull request. Title: a short imperative summary.\n Description: the problem addressed, notable decisions, and `Closes #` for each\n GitHub issue resolved. Do not narrate the diff. Mark the PR ready for review.\n Continue when the final changes are pushed, the description matches the\n final diff, and the PR is ready for review.\n\nThe task is complete when each step's gate holds, validation has passed or\nbeen reported as not runnable with reasons, and the pull request is ready for\nreview with a description matching the final diff.\n",".agents/skills/test-development/SKILL.md":"---\nname: test-development\ndescription: Test development. Use when adding or changing Vitest or Tstyche coverage. Choose Tstyche only for intended compiler behavior such as inference, assignability, rejection, or displayed public types.\n---\n\nChoose branches from the task's acceptance criteria before editing:\n\n- **Runtime behavior:** The intended result is observable when code executes.\n Read [runtime.md](runtime.md).\n- **Compiler behavior:** The intended result is TypeScript accepting, rejecting,\n or inferring a consumer expression in a particular way. Read\n [types.md](types.md).\n\nAn exported signature alone is validated by `pnpm check`; it enters the compiler\nbranch only when its inference, assignability, rejection, overload selection, or\ndisplayed type is part of the task. Some changes require both branches because\nthey independently change runtime and compiler behavior.\n\nThe task is complete when each intended behavior in scope has the relevant\nfocused coverage, targeted tests pass, and applicable root checks pass or are\nreported as not runnable.\n",".agents/skills/test-development/displayed-types.md":"# Displayed Types\n\nDeliberately produce an assignment error and match a distinctive substring with\nTstyche's checked `@ts-expect-error` message:\n\n```ts\nit(\"simplifies the displayed type\", () => {\n const value = null as unknown as PublicType\n\n // @ts-expect-error Type '{ readonly value: string; }'\n const displayed: never = value\n\n void displayed\n})\n```\n\nKeep the expected substring as small as possible while distinguishing the\npublic type from the leaked implementation type. Before accepting the test,\ntemporarily restore the broken type and confirm the diagnostic-message match\nfails.\n",".agents/skills/test-development/runtime.md":"# Runtime Tests\n\n- Use `it.effect` for Effect-returning tests and regular `it` for pure\n synchronous tests.\n- `it.effect` and `it.live` provide and close a `Scope`; return scoped effects\n directly instead of wrapping the body in `Effect.scoped`.\n- Use `assert` from `@effect/vitest`, not Vitest's `expect`.\n- Use `TestClock` for time-dependent behavior.\n- Keep `Effect.runSync` out of unit tests; runnable documentation follows the\n root JSDoc validation rules.\n\nInspect nearby tests for imports and structure. This branch is complete when\nevery changed behavior has focused coverage and its targeted test passes.\n",".agents/skills/test-development/types.md":"# Type tests\n\nEnter this branch when the acceptance criterion is compiler behavior: inference,\nassignability, rejection, overload selection, generic constraints, or a displayed\npublic type. Use `pnpm check` for ordinary declaration edits whose compiler\nbehavior is not independently under test. A runtime bug in generic code needs a\nruntime regression test, not a type test, when its type contract is unchanged.\n\nInspect nearby `.tst.ts` files and use their imports and assertion style. Use\nordinary Tstyche assertions such as `toBe` for structural equality and choose a\nspecific assertion for the inference or assignability contract under test.\n\nStructural equality does not verify editor quick-info rendering. For internal\naliases, unsimplified intersections, or other displayed-type regressions, read\n[displayed-types.md](displayed-types.md).\n\nRun targeted `pnpm test-types `; the root command covers every\nconfigured TypeScript version. For a regression fix, confirm the assertion\nfails against the pre-fix type. This branch is complete when the assertion\nproves the intended contract and the target passes.\n",".agents/skills/vendored-assets/SKILL.md":"---\nname: vendored-assets\ndescription: Vendored assets. Use when importing or updating checked-in third-party or externally generated JavaScript, CSS, registries, schemas, snapshots, or Scalar, Swagger, and MIME artifacts.\n---\n\nTreat upstream artifacts as supply-chain inputs. Change their generator or\ndocumented import source, then regenerate; generated output is review evidence,\nnot an editing surface.\n\n## Workflow\n\n1. **Trace ownership.** Identify the artifact, generator or exact import\n procedure, upstream source/version, license, consumers, tests, and shipped\n package or bundle. Search by asset and upstream project name to find current\n packaging scripts, generated artifacts, consumers, and history.\n Continue when every input and consumer is accounted for.\n2. **Pin provenance.** Resolve moving URLs, tags, branches, and omitted versions\n to an immutable release or artifact. Record project, version, path or URL,\n and digest in the generator or maintenance header. Omit a digest only when\n another enforced immutable source is recorded.\n Continue when a future run cannot silently select different bytes.\n3. **Clear the license gate.** Verify release metadata, license files, bundled\n notices, and the license trail retained in the distributed form.\n Continue when every distributed artifact has a verified retained license trail.\n4. **Regenerate.** Improve the generator or import reference first. Recover an\n exact procedure for generatorless assets; add a deterministic script only\n for recurring updates. Record a one-off procedure beside the artifact. A\n clean rerun must produce no diff.\n5. **Audit the complete diff.** Account for behavior, URLs and runtime fetches,\n source maps, notices, encoding, format changes, and additions or removals.\n For browser assets, also read [browser-assets.md](browser-assets.md).\n Continue when every change is attributable and suspicious content is resolved\n or reported.\n6. **Clear test and size gates.** Record byte sizes before and after, use\n focused consumer tests, and compare bundle size or composition when shipped\n JavaScript, CSS, or registry output changes materially. Compare that output\n against the pre-update revision rather than measuring only current size.\n Continue when focused checks pass and every non-trivial size delta is explained.\n7. **Close release impact.** Apply root changeset routing for consumer-visible\n behavior, browser support, wire data, or meaningful shipped-size changes.\n Generated sections owned by barrels, AI docs, or migration tooling remain\n with the owners named in root instructions.\n\nThe task is complete when every input and consumer is accounted for, provenance\nand licenses are immutable and retained, regeneration is deterministic, every\noutput change and non-trivial size delta is explained, focused checks pass or\nare reported as not runnable, and release impact is recorded.\n",".agents/skills/vendored-assets/browser-assets.md":"# Browser Asset Audit\n\nFor browser-delivered JavaScript or CSS, inspect the complete generated output\nfor:\n\n- CSP requirements and dynamic code execution;\n- injected markup, scripts, or styles;\n- network destinations and runtime loading;\n- external URLs, source maps, and runtime fetches;\n- bundled code or notices absent from upstream top-level metadata.\n\nEvery destination and executable behavior must be attributable to the selected\nupstream release. Resolve or report suspicious content before completion.\n","packages/ai/anthropic/README.md":"# @effect/ai-anthropic\n\nAn [Anthropic](https://www.anthropic.com) provider for the Effect AI modules. Includes a typed Anthropic API client, language model layers, tools, and telemetry helpers.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-anthropic\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/ai-anthropic): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/ai/cloudflare/README.md":"# @effect/ai-cloudflare\n\nCloudflare Workers AI provider for Effect's `DecisionModel`. Supports text and JSON classification, ordered ratings, and probabilities with Clef and Clef-flash over REST.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-cloudflare\n```\n\n## Usage\n\nSet `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`, then provide a Cloudflare decision model:\n\n```ts\nimport { CloudflareClient, CloudflareDecisionModel } from \"@effect/ai-cloudflare\"\nimport { Effect, Layer, Schema } from \"effect\"\nimport { Decision, DecisionModel } from \"effect/ai\"\nimport { FetchHttpClient } from \"effect/http\"\n\nconst Triage = Decision.make({\n input: Schema.String,\n decisions: {\n urgent: Decision.probability({\n instructions: \"Does this request need immediate attention?\"\n })\n }\n})\n\nconst Clef = CloudflareDecisionModel.layer({ model: \"clef-flash\" }).pipe(\n Layer.provide(CloudflareClient.layerConfig()),\n Layer.provide(FetchHttpClient.layer)\n)\n\nconst program = DecisionModel.decide(Triage, {\n input: \"Checkout has been failing for every customer for an hour.\"\n}).pipe(Effect.provide(Clef))\n```\n\nPass `images` to include pictures with the input. Clef shows them to the model before the state:\n\n```ts\ndeclare const screenshotBytes: Uint8Array\n\nconst withScreenshot = DecisionModel.decide(Triage, {\n input: \"Customers report this checkout error.\",\n images: [{ mediaType: \"image/png\", data: screenshotBytes }]\n})\n```\n\nImage `data` may be a `Uint8Array`, a base64 string, or a `data:` URL. Remote URLs fail with `AiError.InvalidUserInputError` because Clef does not fetch them, so download the image first. The API accepts up to 4 PNG, JPEG, or WebP images, each at most 4 MiB and 16 megapixels, with 8 MiB of decoded images in total and a 13 MiB request body.\n\nUse `\"clef\"` for the larger model. `CloudflareDecisionModel.model` provides a model descriptor with Cloudflare provider metadata. `CloudflareClient.layer` accepts an explicit account ID and redacted API token; `apiUrl` and `transformClient` customize HTTP access.\n\nInstructions and descriptions can be strings, JSON objects, or JSON arrays. A rating level with a structured description takes an explicit `label`, which answers use.\n\nThe client unwraps Cloudflare's REST envelope and maps failures to `AiError`. It does not retry automatically. Rate-limit errors include `Retry-After` when provided. The decision model validates answers and rescales small probability drift from four-decimal rounding.\n\nCloudflare limits each request to 64 questions, classification to 2–255 choices, and ratings to 2–10 levels. See the [Clef API documentation](https://developers.cloudflare.com/workers-ai/models/clef/) for request limits.\n\n## AI Gateway\n\nSet `CLOUDFLARE_AI_GATEWAY_ID` when using `CloudflareClient.layerConfig()` to route requests through a Cloudflare AI Gateway. You can also pass `gatewayId` to `CloudflareClient.layer`. The client adds the `cf-aig-gateway-id` header. Use `transformClient` to add other `cf-aig-*` headers.\n","packages/ai/openai-compat/README.md":"# @effect/ai-openai-compat\n\nConnects the Effect AI modules to any OpenAI-compatible API, with support for chat completions and embeddings.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-openai-compat\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/ai-openai-compat): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/ai/openai/README.md":"# @effect/ai-openai\n\nAn [OpenAI](https://openai.com) provider for the Effect AI modules. Includes a typed OpenAI API client, language model and embedding model layers, tools, and telemetry helpers.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-openai\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/ai-openai): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/ai/openrouter/README.md":"# @effect/ai-openrouter\n\nAn [OpenRouter](https://openrouter.ai) provider for the Effect AI modules. Includes a typed OpenRouter API client and language model layers.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-openrouter\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/ai-openrouter): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/ai/typesafe/README.md":"# @effect/ai-typesafe\n\nTypeSafe System One provider for Effect's `DecisionModel`. Supports classification, ordered ratings, and probabilities through Effect `HttpClient`.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-typesafe\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/ai-typesafe): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n\n## Usage\n\nUse `TypeSafeClient.layerConfig()` to read `TYPESAFE_API_KEY`, then provide `TypeSafeDecisionModel.model(\"jev-latest\")` to a decision workflow. Versioned model identifiers such as `jev-1.13.0` are also supported.\n\nInstructions and descriptions can be strings, JSON objects, or JSON arrays, as in TypeSafe's [structured questions](https://docs.typesafe.ai/primitives/advanced). A rating level with a structured description takes an explicit label, which answers use:\n\n```ts\nimport { Decision } from \"effect/ai\"\n\nconst severity = Decision.rate({\n instructions: \"How severe is the reported issue?\",\n criteria: [\n { label: \"cosmetic\", description: { what: \"No impact to functionality\", examples: [\"typo in a label\"] } },\n { label: \"degraded\", description: { what: \"Broken, but a workaround exists\", examples: [\"fails in one browser\"] } },\n { label: \"blocking\", description: { what: \"No workaround exists\", examples: [\"cannot log in\"] } }\n ]\n})\n```\n\nThe client does not retry automatically. Rate-limit errors include the provider's retry delay when available. Provider distributions are preserved, not normalized; they must satisfy the core `DecisionModel` validation, including its current `1e-6` sum tolerance. TypeSafe's rounding behavior has not been verified against the live API.\n","packages/atom/react/README.md":"# @effect/atom-react\n\n[React](https://react.dev) bindings for Atom, the reactive state management modules for Effect. Includes hooks for reading and updating atoms, and helpers for server-side rendering hydration.\n\n## Installation\n\n```sh\nnpm install effect @effect/atom-react\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/atom-react): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/atom/solid/README.md":"# @effect/atom-solid\n\n[SolidJS](https://www.solidjs.com) bindings for Atom, the reactive state management modules for Effect.\n\n## Installation\n\n```sh\nnpm install effect @effect/atom-solid\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/atom-solid): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/atom/vue/README.md":"# @effect/atom-vue\n\n[Vue](https://vuejs.org) bindings for Atom, the reactive state management modules for Effect.\n\n## Installation\n\n```sh\nnpm install effect @effect/atom-vue\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/atom-vue): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/effect/README.md":"# effect\n\nEffect is a library for building robust, maintainable, type-safe, and production grade applications in TypeScript.\n\nThe `effect` package is the core of the framework. It provides primitives for managing side effects, errors, concurrency, resources, and structured data, alongside a rich standard library.\n\n> **Effect 4.x is a long-term support (LTS) release**, with at least three years of bug and security fixes. If you are upgrading from Effect 3.x, follow the [migration guide](https://github.com/Effect-TS/effect/blob/main/MIGRATION.md).\n\n## Installation\n\n```sh\nnpm install effect\n```\n\n## Requirements\n\n- **TypeScript 5.9 or newer.** TypeScript 7 is recommended for the best performance and compatibility with [Effect's TypeScript tooling](https://github.com/Effect-TS/tsgo#installation).\n- **Node.js 18 or newer** when running Effect on Node.js.\n- **Strict type-checking:** the `strict` flag must be enabled in your `tsconfig.json`:\n\n ```json\n {\n \"compilerOptions\": {\n \"strict\": true\n }\n }\n ```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/effect): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n\n## Overview\n\nThe `effect` package is a collection of modules. Some of the core ones:\n\n| Module | Description |\n| -------- | -------------------------------------------------------------------------------------------------------------------------- |\n| Effect | The core abstraction for managing side effects, concurrency, and error handling in a structured way. |\n| Context | A lightweight dependency injection mechanism that enables passing services through computations without direct references. |\n| Layer | A system for managing dependencies, allowing for modular and composable resource allocation. |\n| Fiber | Lightweight virtual threads with resource-safe cancellation capabilities, enabling many features in Effect. |\n| Stream | A powerful abstraction for handling asynchronous, event-driven data processing. |\n| Schedule | A module for defining retry and repeat policies with composable schedules. |\n| Scope | Manages the lifecycle of resources, ensuring proper acquisition and release. |\n| Schema | A powerful library for defining, validating, and transforming structured data with type-safe encoding and decoding. |\n\nIn v4, functionality that previously lived in separate packages ships inside `effect` under the `effect/*` namespaces, including `http`, `http-api`, `rpc`, `cluster`, `workflow`, `cli`, `ai`, `sql`, and `reactivity`.\n","packages/effect/runtimeperf/README.md":"# Effect Runtime Performance\n\nThis harness measures focused synchronous runtime paths in fresh Node\nprocesses. It supports:\n\n- focused Effect Schema diagnostics;\n- native Arbitrary comparisons against equivalent fast-check v4 arbitraries;\n- the upstream Effect, Valibot and Zod benchmark matrix;\n- paired comparisons between Git revisions or the current working tree.\n\nCross-library results are diagnostic. Effect base/head comparisons are the\nauthoritative measurement for source changes.\n\n## Commands\n\nRun the complete registry:\n\n```sh\npnpm runtimeperf\n```\n\nRun the cases extracted from the `effect@beta`, Valibot and Zod adapters in\n[`open-circle/schema-benchmarks`](https://github.com/open-circle/schema-benchmarks):\n\n```sh\npnpm runtimeperf schema-benchmarks\npnpm runtimeperf-compare schema-benchmarks --base main --head HEAD\n```\n\nThis suite covers every upstream timing case supported by those adapters:\nschema and decoder initialization, validation, parsing and Standard Schema\nwith valid/invalid inputs and first/all error modes, plus BigInt codec\noperations. The upstream bundle and stack reports are not throughput\nbenchmarks, and the adapters do not define the optional string-format cases.\n\nSelect a suite, fixture, shared scenario, tier, family or implementation:\n\n```sh\npnpm runtimeperf schema\npnpm runtimeperf arbitrary\npnpm runtimeperf object-32-valid\npnpm runtimeperf schema/object-32-valid-effect\npnpm runtimeperf --family arrays\npnpm runtimeperf --implementation zod4\npnpm runtimeperf --implementation zod4-compiled\n```\n\nOverride measurement settings:\n\n```sh\npnpm runtimeperf object-32-valid --rounds 9 --time 500 --warmup-time 150\n```\n\nCompare Effect `HEAD` with the working tree:\n\n```sh\npnpm runtimeperf-compare schema/object-32-valid-effect\n```\n\nMeasure excess-property checking and symbol enumeration in interpreted and JIT parsers:\n\n```sh\npnpm runtimeperf-compare schema-excess-properties\npnpm runtimeperf-compare schema-excess-properties --family jit\n```\n\nCompare explicit refs:\n\n```sh\npnpm runtimeperf-compare schema --base main --head HEAD\n```\n\nOnly `--fail-on-regression` turns a statistically classified regression into a\nnon-zero comparison exit code. Worker, fixture, configuration and Git errors\nalways fail.\n\nReports are written under `tmp/runtimeperf/results/`. Temporary Git worktrees\nare created under `tmp/runtimeperf/worktrees/` and removed in `finally`.\n\n## Registry\n\n`config.json` groups fixture cases by source file. Every case records:\n\n- tier and family;\n- covered Effect AST tags;\n- operation and path;\n- input size;\n- implementation;\n- a shared scenario name for cross-library comparisons.\n\nThe `schema` suite is Effect-only and retains targeted diagnostics for scaling,\ntemplate literals, unions, records, transformations, optional properties,\nadapters, recursion and cold paths. The `schema-benchmarks` suite contains the\ncomplete timing matrices exposed by the upstream Effect, Valibot and Zod\nadapters.\n\nThe `moltar-parse-safe` and `moltar-assert-loose` suites preserve Moltar's\nobject shape. Their valid cases reproduce the upstream timed operation; the\nextra-property and invalid cases are Effect extensions. They compare\ninterpreted Effect, Effect JIT and AOT, Valibot, ordinary and jitless Zod where\napplicable, and Zod `compile`, using the dependency versions recorded in each\nreport.\n\nThe `arbitrary` suite compares the native public API with direct fast-check v4 arbitraries in separate processes. It\nmeasures derivation through the first recursive sample, steady-state recursive\nsampling, optional-Struct sampling, fixed-length string generation to exercise constraint pushdown,\nbounded Number generation, direct Uint8Array generation, a rare residual filter, a fixed-length unique array, and a\nmixed regular expression through cold derivation, warm generation, and shrinking. It also covers literal sampling as\na runner baseline and the public `map`, `filter`, `filterMap`, and `all` combinators for tuples and records. The failure\npaths include a filtered failure with rejected shrink candidates, dependent `flatMap` sampling, shrinking, replay, a\npassing property, a failure that shrinks from `1000` to `1`, and replay of that failure. The\nrecursive distributions are implementation-defined, so the fixtures use\nimplementation-specific size settings and validate a comparable total node\ncount for the fixed seed. The bounded Number case is a throughput comparison,\nnot distribution parity: native selects among 64-bit IEEE-754 representations,\nwhile the fast-check fixture uses its 64-bit `double`. Replay is an\nend-to-end public API comparison, but the work is not identical: native replay\nverifies the original failure and its full shrink path, while fast-check can\nstart directly from its recorded path.\n\nArray cases cover passing checks and shrinking a four-command sequence while preserving an ordered pair. The latter\nstarts from the same explicit sequence in both engines, using a fixed seed for native generation and an example for\nfast-check. Base/head validation preserves the failure without requiring identical shrunk outputs, so its timing also\nreflects changes in how much of the shrink tree is explored. The runtime regression tests assert the smaller result.\n\nThe regular-expression fixtures validate the same language, and both fixed-seed warm fixtures must reach multiple\nlengths and every alternative family. Their exact distributions remain implementation-defined, so cross-library\ntimings are diagnostic while base/head comparisons protect the cost of each implementation's established behavior.\n\nAn impossible Schema filter is deliberately not a cross-engine timing case.\nThe native runner reports bounded exhaustion, while a direct fast-check arbitrary\nbuilt with `Arbitrary.filter` does not return from generation\nwhen no value can satisfy the predicate. Native exhaustion remains covered by\nthe Arbitrary tests instead of placing a permanently blocking fixture in the\nperformance harness.\n\nZod parsing cases import `zod/v4` and call `safeParse` with `{ jitless: true }`;\nits Standard Schema and codec cases use their native APIs. Valibot uses the\ncorresponding `is`, `safeParse` and Standard Schema APIs. The focused Effect\nadapter family measures the overhead of public APIs that wrap parser issues.\nThe compiler comparison calls `z.compile(schema, { strict: true })` and uses\nZod's `validate` API for boolean checks. Ten representative scenarios also run\nagainst equivalent Valibot schemas using `parse` and `is`.\n\n## Measurement model\n\nEach worker validates the fixture before and after measuring. The Effect\nfixture calibrates one batch size that every implementation in the same\nscenario uses. This keeps the enclosing loop identical across implementations;\nV8 can otherwise optimize sub-10 ns callbacks differently at different batch\nsizes. Each implementation executes in a separate process, with rotating order\nwithin the scenario.\n\nTinybench measures one synchronous batched task. The primary process result is:\n\n```text\nnsPerOp = totalTimeMs * 1_000_000 / (task.runs * batchSize)\n```\n\nTinybench latency statistics are retained as diagnostics and normalized by the\nbatch size. Independent Node processes, not Tinybench samples, are the\nstatistical observations.\n\nBase/head comparisons alternate execution order by round and analyze paired\nlog ratios with a deterministic bootstrap. The report keeps all raw worker\nresults so aggregates can be recalculated.\n\n## Fixture contract\n\nEach configured export is a factory:\n\n```ts\ntype RuntimePerfCase = {\n readonly run: () => unknown\n readonly validate: (result: unknown) => void\n}\n\ntype RuntimePerfCaseFactory = () => RuntimePerfCase\n```\n\nConstruct schemas, steady-state adapters and deterministic inputs in the\nfactory. Cold fixtures deliberately construct them inside `run`. A fixture\nmust measure one named operation, perform no I/O and return no Promise.\n\n## Validation\n\n```sh\nnode --test packages/effect/runtimeperf/test/*.test.mts\npnpm exec dprint check package.json packages/effect/runtimeperf\n```\n","packages/effect/runtimeperf/suites/compiler-rebuild/README.md":"# Compiler rebuild comparison\n\nThe `compiler-rebuild` suite measures 25 public SchemaParser operations with the\ninterpreter, selective JIT and generated AOT modules. Nineteen cases also run\nagainst `z.compile(schema, { strict: true })`; eleven representative cases run\nagainst Valibot and Zod with `{ jitless: true }`. The fixture families name the\nexecution mode. Cases\ncover simple and nested Structs, Arrays, tuples, Records, transformed Record\nkeys, anyOf/oneOf Unions, transformations, middleware, recursive and suspended\nschemas, Declarations, construction,\nand successful and failing validation.\n\nThe Effect tuple has a trailing element after its rest element, Zod compilation\ndoes not support recursive schemas or `z.xor`, and Zod has no equivalent\ndecoding middleware. Those four cases intentionally have no Zod fixture. Zod\ncompilation only accelerates forward parsing, so the encode case measures its\ndocumented runtime fallback. Zod parsing stands in for Effect construction\nbecause Zod has no separate constructor operation. Valibot parsing with defaults\nis used for the same comparison.\n\n```sh\npnpm runtimeperf-compare compiler-rebuild --base schema-compiler\npnpm runtimeperf-compare compiler-rebuild --base main --family interpreted\npnpm runtimeperf compiler-rebuild\n```\n\nThe first command compares the current working tree with the archived compiler\nbranch. The second isolates changes to interpreted parsing against main. Schema\nand parser construction are outside the steady-state measurements. AOT fixtures\ngenerate their version-specific module in a separate process before loading it.\n\nThe standard paired harness records five alternating rounds, validates every\nfixture before and after measurement, uses a common batch within each pair, and\nreports bootstrap confidence intervals. Cross-mode rankings are descriptive;\nthe paired base/head comparison is the regression evidence.\n\n## Retained heap and first use\n\nFor a current cross-library comparison of retained heap, V8 code memory, peak\nRSS and preparation CPU, run:\n\n```sh\nnode packages/effect/runtimeperf/suites/compiler-rebuild/run-resources.mts \\\n tmp/schema-compiler-resources.json 5 100,500\nnode packages/effect/runtimeperf/suites/compiler-rebuild/report-resources.mts \\\n tmp/schema-compiler-resources.json\n```\n\nEach sample runs in a fresh process. The report calculates median per-schema\nslopes between 100 and 500 distinct schemas, which removes fixed module and\nlazy initialization costs. Fixture inputs are released before retained-memory\nmeasurement. Preparation CPU includes adapter creation and first use; AOT also\nincludes loading and installing the generated module. AOT source generation is\nreported separately because it runs at build time. Hot synchronous CPU is\nalready represented by the normal runtime measurements.\n\nThe older Effect-only probe below remains available for comparisons with its\nexisting archived results.\n\nThe standalone cost probe accepts a checkout root, mode, operation, shape and\nschema count. Run several fresh processes per combination and alternate the\ncheckout order. Supported modes are `interpreted`, `jit` and `aot`; operations\nare `decode`, `invalid`, `is` and `make`; shapes are `struct`, `array`, `transform`\nand `default`.\n\n```sh\nnode --expose-gc packages/effect/runtimeperf/suites/compiler-rebuild/costs.mts heap \"$PWD\" jit decode struct 500\nnode --expose-gc packages/effect/runtimeperf/suites/compiler-rebuild/costs.mts cold \"$PWD\" jit decode struct 500\n```\n\nHeap measurements exclude schema construction and module imports, and retain\nboth schema objects and public parser functions. They include operation setup\nand first use. Forced GC removes transient parse output and issues. The AOT\ngenerator runs in a separate process, so its retained heap is not attributed to\nthe runtime application.\n\nFirst-use measurements include constructing a fresh schema, installing its\ncompiler when requested, creating a public parser and calling it. They exclude\nmodule imports and AOT source generation. Repeated shapes can benefit from V8's\nsource cache, so this is not process startup latency. Treat these timing probes\nas exploratory, separately from the paired throughput results.\n","packages/effect/runtimeperf/suites/schema-checked-sources/README.md":"# Checked transformation sources\n\nThis suite reconstructs the motivating shape from PR #8597: decode an Array of\n1,000 rows, each containing eleven pattern-checked string fields and one `n`\nfield. The sibling fields match `/^[a-z][a-z0-9]{1,15}$/`, and the checked numeric\nsource matches `/^[0-9]{1,6}$/`. Rows contain `value0` through `value999` and\nnumeric strings `1` through `1000`. Schemas, inputs and parsers are prepared\noutside the measured callback. Each operation decodes all 1,000 rows.\n\n- `digits` validates the checked string without transforming it.\n- `checked-source` converts the checked numeric string to a number.\n- `unchecked-source` converts a plain string to a number.\n- `two-passes` first validates all fields, then decodes the validated output\n with a transformations-only Struct.\n- `checked-template-target` and `unchecked-template-target` convert the `n`\n field to a TemplateLiteral string prefixed with `x-`. They measure valid\n input through the parser fallback required to preserve template diagnostics.\n\nEvery worker validates the complete output before and after measuring. The\ncomparison harness copies the same fixtures into both revisions and alternates\nbase/head order in fresh Node processes.\n\n```sh\npnpm runtimeperf-compare schema-checked-sources --base main --head HEAD \\\n --rounds 16 --time 500 --warmup-time 150\n```\n\nThese fixtures use repository sources. The PR's original figures used packed\npackages on Node 26.10, so compare relative changes rather than absolute times.\n","packages/effect/runtimeperf/suites/schema-construction/README.md":"# Schema construction costs\n\nThis diagnostic measures the current implementation before proposing changes. It leaves library sources unchanged.\nIt measures elapsed construction time in ordinary fresh Node processes, then uses separate V8 CPU-profiled processes\nto locate the work. Profile shares are estimates of sampled execution, not directly timed phases or predicted savings.\n\nRun from the repository root:\n\n```sh\nnode packages/effect/runtimeperf/suites/schema-construction/run.mts tmp/schema-construction 24 1000\n```\n\nArguments are a new output directory, rounds, root count, and an optional comma-separated list of case names.\nThe output directory's parent must exist. Existing output directories are rejected. The source tree must be clean.\nEvery raw observation is saved in `results.json`; raw `.cpuprofile` files can be opened in a CPU profile viewer.\nCopies of the measured harness files are retained in `harness/` to preserve uncommitted analysis code.\nThe report records the commit, source-tree object, harness and lockfile hashes, Node/V8 versions, machine and settings.\nInterrupted or failed runs retain `complete: false` and must not be reported as complete measurements.\n\n## Scope\n\nEach worker imports Schema, prepares fixture keys and validation inputs, and preallocates a root array before timing.\nIt then builds 1,000 new root schemas and retains them until the process exits. The timer includes field-map creation,\nchild schemas, checks, transformations, options and all eager internal work triggered by the declaration.\nThere is no explicit warmup. Schema's own import-time initialization has already run and can warm shared constructors\nand caches. Node startup, TypeScript loading, module imports, decoder preparation and decoding are excluded.\n\nFixtures cover literals; structs with 2, 32 and 256 fields; nested structs; arrays with checks, optional keys and literals;\nnew string-to-number transformations; and unions of eight newly constructed tagged members. Root counts are not counts\nof every intermediate schema. Shared primitive schemas such as `Schema.String` are imported constants. The `struct-N`\nfixtures build field maps with `Object.fromEntries` during timing. The additional `struct-ready-N` fixtures reuse a field\nmap prepared before timing, to isolate `Schema.Struct(fields)` with ready inputs. Primitive schemas, field-name strings\nand sample values are prepared beforehand in both cases. Dynamically generating fields is a distinct caller cost; it\ndoes not model a hand-written object literal's cost.\n\nEach fixture is validated in a separate process before measurement, including valid decode, type-side `.make`, and invalid\ninput rejection. Measured workers check root count, object kind and distinctness after timing. No prior validation warms\nthe measured worker. This protocol makes no claim about complete HttpApi/Confect startup, memory usage or warmed throughput.\n\n## Measurement and attribution\n\nEach round runs ordinary Node, profiling at a requested 100 microsecond interval, and profiling at 500 microseconds.\nWorkers run serially. The six possible orders rotate by round; fixture order also rotates. The default 24 rounds\nbalance all six orders. Do not run other benchmarks, builds or tests alongside the measurement.\n\nElapsed times are medians across independent processes, with median absolute deviation. Profiler perturbation is measured\nthrough paired ratios against the ordinary process in the same round, using the existing deterministic bootstrap with\n10,000 resamples. This is a check on measurement bias, not a comparison of optimized code.\n\nEach CPU sample is assigned to one category:\n\n| Category | Included work |\n| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |\n| `type-projection` | `toType` and its recursive traversal, clones and memoization, during synchronous maker preparation |\n| `ast` | Initial AST construction and changes made by checks, annotations, optional keys and transformations |\n| `schema-object` | Central schema constructor after subtracting identifiable child phases: function object, prototype, options, property and closure setup |\n| `make-sync` | Identifiable synchronous maker factory frames outside the type projection |\n| `make-effect` | Identifiable effectful maker factory frames outside the Option adapter |\n| `make-option` | Option adapter factory, including its separately allocated effectful maker |\n| `schema-api` | Other Schema API work, including composition wrappers and check factories outside AST constructors |\n| `fixture` | Caller-attributed samples: field maps, member lists, the loop, and library work inlined into those frames |\n| `gc` | Garbage collector samples inside the construction window |\n| `runtime` | Other runtime samples without an attributable Schema stack |\n\nChild work is never added again to its parent. V8 can omit an inlined `SchemaParser.make` frame. In these fixtures,\nthe only eager AST/Function subtree beneath central `make` is `toType`; this path is classified as projection even when\nthe parser wrapper is absent. The fixtures do not use options with getters that could invoke arbitrary AST work.\nCompletely inlined work that cannot be separated remains with the caller. The `fixture` category is therefore an\nunresolved caller category, not a measurement of pure benchmark overhead or field-map creation. A ready-field fixture\nwhose body only calls `Schema.Struct(fields)` still receives caller-attributed samples. Small or zero factory shares do not prove\nthat their allocations are free; allocation effects can appear in central construction or GC.\n\nProfiles are delimited by the first and last samples containing the worker's `constructBatch` frame. Samples outside\nthat span are excluded, including inspector setup. Interior GC/runtime samples are retained. Inspector timestamps and\n`hrtime` are not directly compared because their origins can differ. Missing boundary samples, especially GC before the\nfirst or after the last observed construction frame, are a limitation. The report keeps sample counts, sampled span\ncoverage and counts of processes with fewer than ten samples. A profile with no construction samples remains recorded\nand is excluded from share estimates. One sample has zero measured span coverage and is marked sparse.\n\nShares are unweighted sample proportions within each process, averaged across processes. Their 95% intervals bootstrap\nwhole processes, not individual correlated samples. Categories sum to 100% for the point estimates; interval endpoints\nneed not sum to 100%. These intervals cover sampling variability, not profiler bias or attribution errors. Compare the\ntwo sampling frequencies and their overhead before interpreting the shares. Do not convert them into exact milliseconds\nor predicted speedups. Short fixtures may support a reliable elapsed time without a useful internal breakdown.\n\nTop leaf functions and source-position ticks are retained as secondary diagnostics. Source-position ticks are not an\nadditional additive cost breakdown and may accumulate at a function's entry after optimization.\n\n## Validation\n\n```sh\nnode --test packages/effect/runtimeperf/test/*.test.mts\npnpm exec dprint check --includes-override 'packages/effect/runtimeperf/suites/schema-construction/*.mts' 'packages/effect/runtimeperf/test/schema-construction.test.mts'\n```\n\nThe attribution tests cover non-overlapping phases, inlined maker frames, Option's nested effect maker, profile boundaries,\ninterior garbage collection, missing samples and deterministic confidence intervals.\n","packages/effect/typeperf/README.md":"# Effect Type Performance\n\nThis harness measures deterministic TypeScript diagnostics for focused\nfixtures. Type instantiations and materialized types are regression gates, while\nsymbols are reported for additional context.\n\nUse it when a type-level change needs a small regression guard for the specific\ntype path that was optimized.\n\n## Core Model\n\nEach suite has one shared baseline. Fixture cost is reported separately for\ninstantiations, types, and symbols as:\n\n```txt\nmetric delta = fixture metric - suite baseline metric\n```\n\nThreshold files store exact maximum deltas for instantiations and types. Symbol\ndeltas are informational and do not affect the command status.\n\nThe runner compiles each baseline and fixture as an isolated TypeScript program\nby generating temporary `tsconfig` files under `tmp/typeperf`.\n\nFixtures must use realistic package imports:\n\n```ts\nimport { Schema } from \"effect\"\n```\n\nDo not import source files directly, for example do not use\n`../../src/Schema.ts`. The package self-reference should resolve the public\n`effect` package entry.\n\nEvery fixture in a suite should repeat the suite warmup expression from\n`baseline.ts`. For the current Schema suite, that means:\n\n```ts\nimport { Schema } from \"effect\"\n\nSchema.String\n```\n\n## Commands\n\nFrom the repository root:\n\n```sh\npnpm typeperf\npnpm typeperf schema\npnpm typeperf schema/struct-required\npnpm typeperf --update\npnpm typeperf schema/struct-required --update\n```\n\nWithout a target, the runner checks every suite and fixture. A target can be a\nsuite name (`schema`) or an individual fixture (`schema/struct-required`).\n\n`--update` writes exact measured instantiation and type deltas to threshold\nfiles. When a target is provided, only the selected suite or fixture is updated.\n\n## Cross-Ref Comparisons\n\nUse the separate comparison runner when a changeset needs measurements against\nanother Git revision:\n\n```sh\npnpm typeperf-compare httpapi --base main --head HEAD\npnpm typeperf-compare httpapi/endpoint-count-100 --base main --head HEAD\n```\n\nThe runner creates detached worktrees under `tmp/typeperf-compare`, copies the\nsame generated fixture sources into both worktrees, and compiles them with the\nTypeScript installation from the current checkout. Each fixture and baseline is\ncompiled once per revision. The normal `pnpm typeperf` suite and its thresholds\nare not affected.\n\nComparison fixtures use only APIs shared by both revisions. They also contain\ntype-level assertions that reject degenerate results such as missing methods or\n`never` endpoint selections. A fixture is comparable only when the exact same\nsource compiles on both revisions. Results are printed to the terminal and\nwritten as JSON under `tmp/typeperf-compare/results/`, including the resolved\nGit SHAs, TypeScript version, and fixture-suite hash.\n\n## Adding A Fixture\n\nAdd a fixture when a change optimizes one specific constructor, helper, or\ntype-level path.\n\n1. Create one file under the suite's `fixtures/` directory.\n2. Name it after the isolated behavior being measured, for example\n `struct-optional-only.ts`.\n3. Add a first-line comment explaining the single thing being measured.\n4. Use realistic package imports.\n5. Repeat the suite warmup expression.\n6. Build only the schema needed for that one behavior.\n7. Export type aliases that force TypeScript to instantiate the views under\n test.\n8. Add the fixture to `config.json`.\n9. Run `pnpm typeperf / --update`.\n10. Run `pnpm typeperf /`.\n\nExample:\n\n```ts\n// Measures the marginal type-level cost of Schema.Struct when all fields are optional keys.\nimport { Schema } from \"effect\"\n\nSchema.String\n\nconst schema = Schema.Struct({\n id: Schema.optionalKey(Schema.String),\n count: Schema.optionalKey(Schema.NumberFromString)\n})\n\nexport type Type = typeof schema.Type\nexport type Encoded = typeof schema.Encoded\nexport type Iso = typeof schema.Iso\nexport type MakeIn = typeof schema[\"~type.make.in\"]\n```\n\nThen register it:\n\n```json\n{\n \"name\": \"struct-optional-only\",\n \"file\": \"suites/schema/fixtures/struct-optional-only.ts\"\n}\n```\n\n### Fixture Rules\n\n- Measure one thing per fixture. Split separate paths into separate files.\n- Keep inputs realistic, but not large for its own sake.\n- Export the minimum type aliases needed to force the type computation being\n measured.\n- Do not combine multiple optimized APIs just to make the fixture look like an\n application model.\n- Do not add fixtures for unchanged or unrelated APIs.\n- Do not add fixture files to `packages/effect/tsconfig.json`; `pnpm typeperf`\n compiles them independently.\n- If a fixture fails to compile, fix the fixture or source types. Do not hide\n the problem by aggregating it with another fixture.\n\n## Adding A Suite\n\nAdd a suite when fixtures need a different shared baseline. For example,\nSchema-specific fixtures share the `schema` baseline, while HTTP API fixtures\nuse a different import and warmup.\n\n1. Create `suites//baseline.ts`.\n2. Create `suites//fixtures/`.\n3. Create `suites//thresholds.json` with `{}`.\n4. Add a suite entry to `config.json`.\n5. Add at least one focused fixture.\n6. Run `pnpm typeperf --update`.\n7. Run `pnpm typeperf `.\n\nExample suite entry:\n\n```json\n{\n \"name\": \"schema\",\n \"baseline\": \"suites/schema/baseline.ts\",\n \"thresholds\": \"suites/schema/thresholds.json\",\n \"fixtures\": [\n {\n \"name\": \"struct-required\",\n \"file\": \"suites/schema/fixtures/struct-required.ts\"\n }\n ]\n}\n```\n\nThe baseline should contain only the import and warmup common to every fixture in\nthat suite. If a fixture needs extra setup that others do not need, put that\nsetup in the fixture, not in the shared baseline.\n\n## Updating Thresholds\n\nUse `--update` only after verifying that the measured delta is expected.\n\n```sh\npnpm typeperf schema/struct-required --update\npnpm typeperf schema/struct-required\n```\n\n`--update` writes the exact measured deltas as `maxInstantiationsDelta` and\n`maxTypesDelta`. It does not add a margin:\n\n```json\n{\n \"struct-required\": {\n \"maxInstantiationsDelta\": 457,\n \"maxTypesDelta\": 50\n }\n}\n```\n\n## Validation Checklist\n\nAfter adding or changing fixtures:\n\n```sh\npnpm typeperf / --update\npnpm typeperf /\npnpm exec dprint check package.json packages/effect/typeperf\n```\n\nRun the broader suite when the change touches shared runner behavior:\n\n```sh\npnpm typeperf \n```\n","packages/opentelemetry/README.md":"# @effect/opentelemetry\n\nAn [OpenTelemetry](https://opentelemetry.io) integration for Effect. Exports Effect tracing, metrics, and logs through the OpenTelemetry SDK, with `NodeSdk` and `WebSdk` layers for easy setup.\n\n## Installation\n\n```sh\nnpm install effect @effect/opentelemetry\n```\n\nThe relevant `@opentelemetry/*` SDK packages are required as peer dependencies, depending on which features you use.\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/opentelemetry): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/platform/browser/README.md":"# @effect/platform-browser\n\nBrowser implementations of the Effect platform services, including the HTTP client, workers, key-value storage, IndexedDB, clipboard, and geolocation.\n\n## Installation\n\n```sh\nnpm install effect @effect/platform-browser\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/platform-browser): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/platform/bun/README.md":"# @effect/platform-bun\n\n[Bun](https://bun.sh) implementations of the Effect platform services, including the file system, HTTP client and server, sockets, workers, and terminal.\n\n## Installation\n\n```sh\nnpm install effect @effect/platform-bun\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/platform-bun): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","packages/platform/deno/README.md":"","packages/platform/node-shared/README.md":"","packages/platform/node/README.md":"","packages/platform/node/test/cluster-integration/README.md":"","packages/sql/clickhouse/README.md":"","packages/sql/d1/README.md":"","packages/sql/libsql/README.md":"","packages/sql/mssql/README.md":"","packages/sql/mysql2/README.md":"","packages/sql/pg/README.md":"","packages/sql/pg/benchmark/README.md":"","packages/sql/pglite/README.md":"","packages/sql/sqlite-bun/README.md":"","packages/sql/sqlite-do/README.md":"","packages/sql/sqlite-node/README.md":"","packages/sql/sqlite-react-native/README.md":"","packages/sql/sqlite-wasm/README.md":"","packages/tools/api-diff/README.md":"","packages/tools/bundle/README.md":"","packages/tools/docgen/README.md":"","packages/tools/doctest/README.md":"","packages/tools/graphql-generator/README.md":"","packages/tools/npm-promote/README.md":"","packages/tools/openapi-generator/README.md":"","packages/vitest/README.md":""},"items":[{"name":"AGENTS.md","path":".agents/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/AGENTS.md","title":".agents - AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"This is the Effect TypeScript monorepo. The git base branch is `main`; use `pnpm` from the repository root.\n\n## Layout\n\n- Core library source, runtime tests, and type tests are in `packages/effect/src`, `packages/effect/test`, and\n `packages/effect/typetest`.\n- Other package families include `packages/ai`, `packages/atom`, `packages/platform`, `packages/sql`, and\n `packages/tools`; standalone packages also live directly under `packages`.\n- Package tests and type tests live beside source in `test` and `typetest` directories.\n- AI documentation sources are in `ai-docs/src`.\n- Changesets are in `.changeset`.\n- Migration sources (v3-to-v4) are in `migration/annotations`.\n- Inspect nearby code before editing.\n\n## Validation\n\nUse the narrowest validation that covers the change:\n\n| Change type | Validation |\n| ---------------------------------- | ---------------------------------------------------------------------------------- |\n| Runtime source or test changes | `pnpm lint-fix`, targeted `pnpm test --run `, `pnpm check` |\n| Type-system behavior or type tests | Targeted `pnpm test-types `, plus `pnpm check` when source types changed |\n| JSDoc text/category/link changes | `pnpm jsdocs --check`, `pnpm lint` |\n| JSDoc example changes | `pnpm jsdocs --check`, `pnpm lint`, root `pnpm doctest --run ` |\n| Docs-only changes | `pnpm lint-fix`; no tests unless examples or code changed |\n\nChoose coverage from the contract being changed. Runtime tests cover executed\nbehavior. Tstyche tests cover intended compiler behavior such as inference,\nassignability, rejection, or displayed public types. An ordinary source edit or\nexported declaration is covered by `pnpm check` unless compiler behavior is part\nof the task.\n\nNever run bare `pnpm test` or `pnpm doctest`; both start the full suite in watch mode. Always pass `--run` and the\nspecific files covering the change. CI runs the full suite.\n\nFor an ad hoc runnable probe, create `scratchpad/.ts`, run it with plain `node`, and remove it when finished.\n\nReport any commands that could not be run.\n\n## Generated Files\n\nDo not edit generated output directly.\n\nSome `index.ts` sections marked with `@barrel` are generated. Do not edit those\nsections manually; update their source modules and run `pnpm codegen`.\nHand-maintained `index.ts` files and unmarked sections are not covered by this\nrule.\n\n`LLMS.md` is generated from `ai-docs/src`, and `migration/v3-to-v4.md` is\ngenerated from `migration/annotations`. Update checked-in third-party assets\nthrough their generator or documented import procedure.\n","isInternal":false,"tokens":606,"sizeBytes":2825},{"name":"SKILL.md","path":".agents/skills/ai-docs/SKILL.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/ai-docs/SKILL.md","title":"ai-docs","category":"anthropic-skill","format":"markdown","content":"---\nname: ai-docs\ndescription: AI documentation. Use when editing ai-docs/src or regenerating LLMS.md.\n---\n\nRead `ai-docs/README.md`; it owns source structure, style, examples, generation,\nand changeset policy.\n\n1. Inspect neighboring source examples and the relevant current `LLMS.md`.\n2. Edit sources under `ai-docs/src`, then run `pnpm ai-docgen`.\n3. Review generated output for ordering, missing content, and unrelated changes.\n4. Run applicable root validation.\n\nThe task is complete when sources and generated output agree, every generated\ndifference is explained, TypeScript checks pass when examples or fixtures\nchange, and applicable checks pass or are reported as not runnable.\n","frontmatter":{"name":"ai-docs","description":"AI documentation. Use when editing ai-docs/src or regenerating LLMS.md."},"isInternal":false,"tokens":149,"sizeBytes":688},{"name":"SKILL.md","path":".agents/skills/bundle-analysis/SKILL.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/bundle-analysis/SKILL.md","title":"bundle-analysis","category":"anthropic-skill","format":"markdown","content":"---\nname: bundle-analysis\ndescription: Bundle analysis. Use when measuring current bundle size, comparing stable or selected fixtures, inspecting composition, or cleaning retained comparison state.\n---\n\nRead `packages/tools/bundle/README.md`, then select one workflow:\n\n- **Stable comparison:** `pnpm bundle-compare `. Use `HEAD~1` for the\n latest commit. Read `tmp/bundle-stats.txt` and report non-zero differences.\n- **Selected comparison:** `pnpm bundle-compare-selected --base \n scratchpad/.ts`. Use only user-named or investigation-local fixtures;\n keep temporary fixtures out of the stable corpus.\n- **Composition:** `pnpm bundle-analyze scratchpad/.ts`. Read raw data\n first and report the largest modules, dependency groups, and surprising\n inclusions. Its readable-name output is not an exact size measurement.\n- **Current size:** Build immediately before the direct bundle report so Effect\n packages resolve from current `dist` output.\n- **Cleanup:** Stable comparisons retain `tmp/bundle-base` for reuse unless\n cleanup is requested. Remove selected-comparison state retained with\n `--keep-base` after its final use. Verify cleanup without disturbing unrelated\n worktrees.\n\nThe task is complete when the selected artifact is inspected, requested size or\ncomposition findings are reported, generated paths are named, and comparison\nstate follows the selected workflow's retention policy.\n","frontmatter":{"name":"bundle-analysis","description":"Bundle analysis. Use when measuring current bundle size, comparing stable or selected fixtures, inspecting composition, or cleaning retained comparison state."},"isInternal":false,"tokens":302,"sizeBytes":1440},{"name":"authoring.md","path":".agents/skills/changesets/authoring.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/changesets/authoring.md","title":"Changesets Skill","category":"anthropic-skill","format":"markdown","content":"# Authoring changesets\n\nUpdate the changeset already introduced by the PR. If there is none, create one\n`.changeset/.md` for the complete PR:\n\n```md\n---\n\"effect\": patch\n\"@effect/affected-package\": patch\n---\n\nFix `Effect.cachedInvalidateWithTTL` caching a stale result when invalidated while the effect is running.\n```\n\nWrite one short sentence, usually under 25 words, that names the changed API\nand states what consumers will notice. That sentence is the whole entry unless\nthe change is breaking or consumers must migrate.\n\nLeave out how the change works: internal modules, algorithms, data structures,\nrefactors, motivation, benchmarks, test coverage, and development history. They\nbelong in the PR description. Cut any sentence a consumer would not act on.\n\n- Bad: \"Rework the `MemoMap` lookup so `Layer.provide` checks identity before\n building, adding a cache keyed by layer reference and tests for shared\n layers.\"\n- Good: \"Fix composed layers being rebuilt for every parent that references\n them.\"\n\nAdd detail only for a break or required migration: what existing code must\nchange and how. Use compact bullets, one break per bullet, when several breaks\nneed migration steps. Several non-breaking fixes or additions still share one\nsentence.\n\nList every directly affected published package. Do not list packages merely\nbecause they share the fixed release group in `.changeset/config.json`.\n\nChoose the bump from current release policy:\n\n- Use `patch` for compatible fixes, `minor` for compatible additions, and\n `major` for breaks.\n- A break confined to APIs tagged `@stability unstable` is `minor`. A break\n confined to APIs tagged `@stability experimental` is `patch`. APIs tagged\n `@stability stable` follow strict semver.\n- Use `major` only when a maintainer has approved a major release.\n- The release queue retargets PRs with `minor` changesets to `v4/next-minor`\n and PRs with `major` changesets to `v4/next-major`. Choose the level the\n change requires, not the branch you want it to land on.\n- Ask when release intent is ambiguous.\n\nUse a `### Breaking changes` section when several breaks need separate\nscanning. Include before/after examples only when they materially clarify\nmigration.\n\nValidate frontmatter against published package names and inspect nearby current\nchangesets for release convention. Do not copy the length of longer entries.\nNever run `changeset-version` or `changeset-publish` as contributor validation.\n","isInternal":false,"tokens":546,"sizeBytes":2470},{"name":"SKILL.md","path":".agents/skills/changesets/SKILL.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/changesets/SKILL.md","title":"changesets","category":"anthropic-skill","format":"markdown","content":"---\nname: changesets\ndescription: Concise PR finalization changesets. Use when implementation scope is complete and focused validation has finished to classify release impact, consolidate the PR's existing changeset, or write its consumer release note.\n---\n\nTreat a changeset as the release note for the complete PR, not as a log of work\nperformed along the way. Finalize it after the current implementation scope and\nfocused validation are complete.\n\n## Workflow\n\n1. Inspect the complete diff from the merge base, including changeset files\n already introduced by the PR, and identify directly affected published\n packages.\n2. Classify impact across source types, runtime behavior, entrypoints, required\n services, lifecycle, and persisted or wire data.\n3. Perform the breaking audit below.\n4. Record a reason no changeset is required, or update the PR's existing\n changeset. Create one only when the PR does not have one. When required, read\n [authoring.md](authoring.md).\n5. Validate package names, frontmatter, bump policy, and a one-sentence\n consumer-facing description, longer only for breaks or required migration.\n\nDo not include unrelated worktree changes.\n\n## PR-level consolidation\n\nThe default is one changeset file per PR. One file can name several packages and\nsummarize several related fixes or additions. Successive prompts, commits, and\nsubtasks within the same PR update that file. If implementation resumes after a\nchangeset was drafted, revise it during the next finalization pass.\n\nUse separate files only when a maintainer requests the split or the PR contains\nindependent changes that need separate release notes.\n\n## Requirement\n\nCreate a changeset for observable runtime behavior changes, including bug\nfixes; exported value or public type changes; entrypoint or export-map changes;\nchanges to required services, errors, ownership, defaults, or lifecycle; and\npersisted, serialization, protocol, or wire-format changes.\n\nTests-only changes, behavior-preserving internal refactors, documentation or\nJSDoc maintenance, and unpublished tooling normally do not need one. When\nunclear, inspect exports and consumer-visible declarations rather than inferring\nfrom source location.\n\n## Breaking Audit\n\nA change is breaking when valid existing consumer code, configuration, or data\nmust change to keep compiling or behaving according to the previous contract.\nAudit every surface:\n\n- **Names and locations:** exports, entrypoints, compatibility exports, and\n module paths.\n- **Call compatibility:** parameters, accepted inputs, overload resolution,\n generic parameters, and defaults.\n- **Result compatibility:** return and error types, output narrowing, members,\n inference, and required services.\n- **Runtime contracts:** defaults, failures, interruption, concurrency,\n ordering, resource lifetime, acquisition, cleanup, and mutation.\n- **Data compatibility:** persisted schemas, encodings, database layouts,\n protocols, and wire formats.\n\nAdditive exports, optional parameters, and behavior-preserving implementations\nare normally non-breaking. A fix restoring the documented contract is normally\nnon-breaking but still needs a changeset when its operational impact is\nconsumer-visible. Verify representative existing calls when overload ordering,\nstructural assignability, or inference makes compatibility uncertain. API diff\noutput is mechanical evidence, not a semantic-version decision.\n\nThe task is complete when every affected contract and published package is\naccounted for and either the no-changeset decision is explicit or the PR has one\nconsolidated, valid changeset by default. Its release note is one sentence of\nconsumer impact, plus migration steps for every break, with no implementation\ndetail.\n","frontmatter":{"name":"changesets","description":"Concise PR finalization changesets. Use when implementation scope is complete and focused validation has finished to classify release impact, consolidate the PR's existing changeset, or write its consumer release note."},"isInternal":false,"tokens":741,"sizeBytes":3748},{"name":"privileged-workflows.md","path":".agents/skills/ci-maintenance/privileged-workflows.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/ci-maintenance/privileged-workflows.md","title":"Ci-maintenance Skill","category":"anthropic-skill","format":"markdown","content":"# Privileged Workflows\n\n- Privileged jobs must not run untrusted repository code with secrets or write\n credentials.\n- Validate cross-run data for expected source, identity, type, shape, and\n bounded size before using it in commands, outputs, APIs, or comments.\n- Require the intended approval boundary before fork-originated work reaches\n privileged execution.\n- Preserve publication and other irreversible operations until completion;\n cancel only replaceable checks and previews.\n- Make checkout revision and credential persistence explicit. Account for\n every write permission and credential.\n\nSearch current workflows by event, job purpose, action, and permission to find\nthe nearest precedent for fork approval gates, publication, non-cancelable\nconcurrency, and validation of cross-run artifacts before privileged use.\n\nConsult current GitHub documentation for event, token, secret, permission,\ncheckout, artifact, reusable-workflow, and environment semantics. Start with\nthe workflow events, workflow syntax, and secure-use references.\n","isInternal":false,"tokens":196,"sizeBytes":1049},{"name":"SKILL.md","path":".agents/skills/ci-maintenance/SKILL.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/ci-maintenance/SKILL.md","title":"ci-maintenance","category":"anthropic-skill","format":"markdown","content":"---\nname: ci-maintenance\ndescription: GitHub Actions maintenance. Use when authoring or reviewing workflows or composite actions, especially event, permission, action-reference, artifact, setup, or concurrency changes.\n---\n\nAudit the trust boundary before editing. This skill owns Actions event\nsemantics, workflow security, permissions, action pinning, setup reuse,\nuntrusted inputs, timeouts, concurrency, and artifact trust boundaries.\n\n## Workflow\n\n1. Decide whether this is a review or an implementation. Reviews produce\n evidence-backed findings without editing; implementations continue through\n the smallest boundary-preserving change.\n2. Inspect every affected workflow, composite action, and caller. List all\n affected jobs and actions before proceeding.\n3. For each job, record the trigger, actor/fork status, workflow revision,\n checked-out revision, permissions, credentials, and every external input and\n consumer. Include artifacts, caches, outputs, PR fields, refs, dispatch\n inputs, generated files, and called actions.\n4. Consult current GitHub documentation for every platform-sensitive decision.\n Repository examples establish local convention, not platform semantics.\n5. Apply every applicable rule:\n - Default workflow permissions to empty and grant minimal job permissions.\n - Reuse the repository's shared setup action unless the environment must differ.\n - Give executable jobs intentional matrices and realistic timeouts.\n - Pin external actions and reusable workflows to full commit SHAs with\n readable release comments; verify each SHA belongs to that upstream release.\n - Analyze event choice, checkout revision, and credential persistence\n together.\n - Pass untrusted expressions through environment variables; validate and\n quote them before use.\n - Derive concurrency from interruption safety.\n6. For forks, privileged credentials, publication, or cross-run data, read\n [privileged-workflows.md](privileged-workflows.md).\n7. Run the narrowest syntax and repository checks, inspect the complete diff,\n and identify behavior testable only on GitHub-hosted runners.\n\nFor local patterns, inspect the current shared setup action and the nearest\nworkflow with the same trust boundary. Use ordinary check workflows for routine\nprecedent and privileged publication workflows only for equivalent trust\nboundaries.\n\nThe task is complete when every affected job and caller has a recorded trust\nboundary, every applicable rule has evidence or a compensating control, local\nchecks pass, and GitHub-only verification is identified. Reviews report every\nfailure with evidence; implementations resolve every failure and contain only\nintended behavior.\n","frontmatter":{"name":"ci-maintenance","description":"GitHub Actions maintenance. Use when authoring or reviewing workflows or composite actions, especially event, permission, action-reference, artifact, setup, or concurrency changes."},"isInternal":false,"tokens":508,"sizeBytes":2712},{"name":"coordinated-upgrades.md","path":".agents/skills/dependency-maintenance/coordinated-upgrades.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/dependency-maintenance/coordinated-upgrades.md","title":"Dependency-maintenance Skill","category":"anthropic-skill","format":"markdown","content":"# Coordinated Upgrades\n\nSelect every applicable row and derive commands from the cited current source.\n\n| Change | Synchronize | Validation source |\n| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |\n| Shared dependency or test/build tool | Owning manifests, peer/development pairs, configs, and generated artifacts owned by that tool | Root/package scripts and affected Vitest projects |\n| pnpm | Root `packageManager`, workspace settings, setup/cache assumptions, workflows, and lockfile format | Current install, lint, check, build, and focused test scripts |\n| Node, Deno, or Bun | Setup inputs, workflow jobs, engines, runtime metadata, compatibility docs, and runtime config | Current runtime workflow jobs and test configuration |\n| TypeScript support or compiler | Compiler/tooling dependencies, `test-types` target, CI target, tool peer ranges, compatibility docs, and typetests | Targeted typetests; typeperf protocol for measured paths |\n| Native package or install policy | Owning manifests and `pnpm-workspace.yaml#allowBuilds` | Fresh install plus focused package build and tests |\n| Patched dependency | Manifest/range, `patchedDependencies`, patch file, and lockfile patch hash | Fresh install and the behavior that required the patch |\n| Container image or Testcontainers package | Workflow pre-pulls, image call sites, manifests, and integration project names | Current integration workflow and Vitest configuration |\n\nFor a patched dependency, test the new release without the patch when feasible.\nRemove obsolete registration and patch files. Otherwise refresh the patch using\nthe current pnpm workflow and verify both that it applies and that the original\npatched behavior still requires it.\n\nWhen an upgraded component lies on a measured path, use the repository's\nruntimeperf or typeperf comparison protocol rather than inventing a benchmark.\n","isInternal":false,"tokens":390,"sizeBytes":2577},{"name":"manifest-roles.md","path":".agents/skills/dependency-maintenance/manifest-roles.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/dependency-maintenance/manifest-roles.md","title":"Dependency-maintenance Skill","category":"anthropic-skill","format":"markdown","content":"# Manifest Roles\n\nInspect the nearest package with the same integration shape, then justify each\nadded or moved entry:\n\n| Role | Use when | Completion check |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |\n| `dependencies` | Published runtime code requires its own installed copy. | A packed consumer receives it without adding an undeclared package. |\n| `peerDependencies` | Consumers provide a compatible shared package or the public contract integrates with their copy. | The range states supported consumer versions; add a development entry when local build or tests need an installed copy. |\n| `devDependencies` | Only repository build, test, type, benchmark, or code-generation work needs it. | Published runtime code and declarations do not require consumers to install it. |\n| `optionalDependencies` | A runtime feature handles absence and installation failure must not block the base package. | Focused tests cover present and absent behavior. |\n| Optional peer via `peerDependenciesMeta` | A consumer-provided integration is genuinely optional. | The peer remains in `peerDependencies`, and code requires it only when selected. |\n\nRole selection is complete when every changed entry has one justified role and\npeer compatibility remains independent from repository validation versions.\n","isInternal":false,"tokens":260,"sizeBytes":2138},{"name":"SKILL.md","path":".agents/skills/dependency-maintenance/SKILL.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/dependency-maintenance/SKILL.md","title":"dependency-maintenance","category":"anthropic-skill","format":"markdown","content":"---\nname: dependency-maintenance\ndescription: Dependency maintenance. Use when adding, moving, or upgrading dependencies, changing pnpm or JavaScript runtimes, updating TypeScript or build/test tools, or changing native-build policy, patches, or test images.\n---\n\nTreat an upgrade as a synchronization task, not a lockfile refresh. Derive\nversions, commands, and compatibility points from the current repository.\n\n## Discover\n\n1. Read affected manifests and scripts, `pnpm-workspace.yaml`, setup actions,\n workflows, test configuration, and compatibility documentation.\n2. Search for the dependency and every current version, range, runtime input,\n image, engine constraint, patch, and compatibility claim.\n3. Record each match as a development version, tested version, peer range,\n engine minimum, advertised minimum, or intentionally different constraint.\n4. When adding or moving a manifest entry, read\n [manifest-roles.md](manifest-roles.md) before selecting its role.\n5. Select the package-local or coordinated branch and its validation matrix.\n\nDiscovery is complete when every match and affected validation surface is\naccounted for.\n\n## Package-local branch\n\nUse this branch only for one dependency in one workspace package when runtime,\ncompiler, package-manager, image, patch, native-build, and shared-tooling policy\nare unchanged.\n\nUpdate only the owning manifest and keep peer compatibility independent from\nthe development version tested here. If any coordinated surface appears,\nswitch branches.\n\nThis branch is complete when the manifest and lockfile agree, focused checks\npass, and every search result is intentionally unchanged or package-local.\n\n## Coordinated branch\n\nRead [coordinated-upgrades.md](coordinated-upgrades.md), select every applicable\nrow, and update all listed synchronization points before installing. Apply root\nworkflow and generated-file requirements before editing those surfaces, then\nreturn here to finish matrix and lockfile review.\n\n## Install and finish\n\nRun root `pnpm install` after all selected edits. Inspect warnings and the\nsemantic lockfile diff for specifiers, resolutions, duplicate transitives, peer\nchanges, integrity, patch hashes, lifecycle scripts, and `allowBuilds` effects.\nA successful install alone does not complete this review.\n\nRun the narrowest correctness and performance checks that cover every selected\nmatrix row.\nApply the root changeset routing after implementation and focused validation.\n\nThe task is complete when repeated repository searches find no unclassified\nsynchronization point, manifest roles and compatibility ranges are intentional,\nthe lockfile has no unexplained churn, and every selected check passes or is\nreported as not runnable.\n","frontmatter":{"name":"dependency-maintenance","description":"Dependency maintenance. Use when adding, moving, or upgrading dependencies, changing pnpm or JavaScript runtimes, updating TypeScript or build/test tools, or changing native-build policy, patches, or test images."},"isInternal":false,"tokens":522,"sizeBytes":2729},{"name":"SKILL.md","path":".agents/skills/effect-development/SKILL.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/effect-development/SKILL.md","title":"effect-development","category":"anthropic-skill","format":"markdown","content":"---\nname: effect-development\ndescription: Effect development guidance. Use when implementing or reviewing code that composes Effect APIs or patterns, or that adds or changes API signatures.\n---\n\nUse the repository's AI documentation as targeted reference, not ambient\ncontext:\n\n1. Identify the Effect APIs and concepts involved in the change.\n2. Search `LLMS.md` and `ai-docs/src` for those names and concepts, then read\n the matching sections and examples.\n3. Apply the relevant guidance and inspect nearby source and tests for any\n repository-internal conventions not covered by the documentation.\n\nThe task is ready for implementation when every material Effect API or pattern\nhas matching local guidance, or the search has established that none exists.\n\n## API conventions\n\nWrite option types inline in the signature by default. Mark fields `readonly`\nand add `| undefined` to optional fields:\n\n```ts\nexport const make = (options: {\n readonly capacity: number\n readonly strategy?: \"dropping\" | \"sliding\" | undefined\n}): Effect.Effect => ...\n```\n\nDeclare a named options type only in these cases:\n\n- A substantial set of options is shared across several APIs, so a named type\n keeps them in sync.\n- The options type needs complex conditional logic, such as conditional or\n mapped types driven by type parameters.\n\nA long option list for a single API is not on its own a reason to extract a\nnamed type.\n","frontmatter":{"name":"effect-development","description":"Effect development guidance. Use when implementing or reviewing code that composes Effect APIs or patterns, or that adds or changes API signatures."},"isInternal":false,"tokens":298,"sizeBytes":1420},{"name":"categories.md","path":".agents/skills/jsdocs/categories.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/jsdocs/categories.md","title":"Jsdocs Skill","category":"anthropic-skill","format":"markdown","content":"# Categories\n\nRoot declarations require one non-empty `@category`. Reuse nearby categories;\nprefer lowercase plurals and gerunds while preserving canonical domain casing.\n\nCommon categories include:\n\n- Shapes: `constructors`, `destructors`, `models`, `schemas`, `guards`,\n `predicates`, `getters`, `accessors`, `instances`, `constants`, `protocols`,\n `prototypes`, `re-exports`, `unsafe`, `testing`.\n- Effect: `services`, `tags`, `layers`, `context`, `resource management`,\n `running`, `errors`, `error handling`.\n- Operations: `combinators`, `filtering`, `mapping`, `sequencing`, `zipping`,\n `combining`, `merging`, `converting`, `transforming`, `folding`, `splitting`,\n `repetition`.\n- Shared: `utility types`, `encoding`, `decoding`, `serialization`, `tracing`,\n `metrics`, `logging`, `annotations`, `references`, `symbols`, `type IDs`,\n `configuration`, `math`, `comparisons`, `ordering`.\n\nKeep these boundaries: services are contracts, tags identify services, and\nlayers provide them; getters retrieve values while accessors read context;\nerrors model failures while error handling recovers or maps them; models are\ndomain data while utility types are type-level contracts; guards narrow while\npredicates return booleans.\n","isInternal":false,"tokens":294,"sizeBytes":1234},{"name":"declarations.md","path":".agents/skills/jsdocs/declarations.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/jsdocs/declarations.md","title":"Jsdocs Skill","category":"anthropic-skill","format":"markdown","content":"# Tags, Modules, And Links\n\n## Declaration Shape\n\nUse a multiline JSDoc block for a public declaration:\n\n````ts\n/**\n * Short description as one paragraph.\n *\n * **When to use**\n *\n * Optional practical usage guidance.\n *\n * **Details**\n *\n * Optional details for complex behavior.\n *\n * **Gotchas**\n *\n * Optional concrete caveats.\n *\n * **Example** (Parsing JSON)\n *\n * ```ts import.meta.vitest\n * operation() // => expected\n * ```\n *\n * @category constructors\n * @since 1.0.0\n */\n````\n\nWrite practical English about the public concept, not its implementation. Start\nfunctions and methods with a present-tense action such as `Creates`, `Returns`,\nor `Converts`; match nearby noun families for values, such as `Schema for`,\n`Layer that`, or `Service that`.\n\nOptional non-empty sections appear once in this order: `**When to use**`,\n`**Details**`, `**Gotchas**`. Separate descriptions, sections, examples, and\ntags with exactly one blank line. Use prose for one fact and bullets for\nparallel facts. Do not add other headings.\n\n`**When to use**` states a positive use case distinct from the description and\nbegins with `Use to`, `Use when`, `Use as`, or `Use with`. Put sibling\ncomparisons in `@see`. Reserve `**Gotchas**` for concrete preconditions, edge\ncases, surprising behavior, and important failure modes.\n\n## Tags\n\nDeclaration tags appear in this order:\n\n1. `@deprecated`\n2. `@default`\n3. `@see`\n4. `@stability`\n5. `@category`\n6. `@since`\n\n- Roots require stable-semver `@since` and no `@default`; category requirements\n live in [categories.md](categories.md).\n- Namespaces and their declarations require stable-semver `@since`, permit\n `@category`, and reject `@default`.\n- Member JSDoc is optional; when present it permits stable-semver `@since` and\n non-empty `@default`, rejects `@category`, and follows the prose contract.\n- Any declaration permits one non-empty `@deprecated` and repeated non-empty\n `@see` tags.\n- Roots, export specifiers, and root namespaces require `@stability stable`,\n `@stability unstable`, or `@stability experimental`. Use `unstable` when an\n API may receive breaking changes in minor releases, `experimental` when it may\n receive breaking changes across patch versions, and `stable` otherwise.\n- Tag any API that exposes a third-party dependency `@stability unstable`: an\n accessor to the underlying client or instance, options typed as the\n dependency's options, constructors that accept its instances, re-exports of\n it, and signatures that mention its types. Tag the whole module when it exists\n to wrap the dependency; otherwise tag only the exposing declarations or\n members. Runtime built-ins (Node, Bun, Deno, DOM) and framework types inherent\n to a binding (React, Solid, Vue) are exempt.\n\nUse canonical `**Example**` sections rather than `@example` tags or loose code\nfences.\n\n## Modules And Links\n\nWhen present, the first top-level JSDoc is the module block unless TypeScript\nattaches it to a non-import first declaration. An `@internal` module is omitted.\nModule prose does not use the declaration template. Its tags are optional\nnon-empty `@deprecated`, repeated non-empty `@see`, required `@stability`, then\nrequired stable-semver `@since`. Its examples and links follow the declaration\ncontracts.\n\nInline `{@link Symbol}` targets must resolve to TypeScript symbols; use normal\nMarkdown links for URLs. Prefer code formatting when navigation does not help a\nreader understand or choose the API.\n\nUse `@see` only for a verified related public API: a close alternative,\ninverse, complement, level variant, or closely returned, consumed, or\nconfigured type. Explain non-obvious relationships. Exclude implementation\ndependencies, broad concepts, example-only helpers, private APIs, and merely\nlexical matches.\n","isInternal":false,"tokens":882,"sizeBytes":3771},{"name":"examples.md","path":".agents/skills/jsdocs/examples.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/jsdocs/examples.md","title":"Jsdocs Skill","category":"anthropic-skill","format":"markdown","content":"# Examples\n\nExamples are optional. Keep or add one only for behavior not evident from the\nsignature, meaningful composition, or useful inference or narrowing. Replace\nor remove examples that are trivial, misleading, contrived, or\nscaffolding-heavy.\n\nUse `**Example** (Unique use-case title)`, optional prose, and exactly one\nnon-empty `ts` fence. Titles must remain unique after trimming and lowercasing.\n\nRead `packages/tools/doctest/README.md` for runnable-fence and inline-assertion\nsyntax. Additionally:\n\n- Use public imports and arrange nontrivial examples as setup, operation, then\n semantic observation.\n- The transform does not run Effects or await promises automatically. Prefer\n awaited `Effect.runPromise`; use `Effect.runSync` only when synchronous\n execution is the documented contract.\n- Keep type-level examples marked without tautological runtime assertions.\n- Leave examples that register tests and intentionally non-executable examples\n as plain `ts` fences.\n- Use `Ref`, `Deferred`, or `Queue` rather than mutable probes for concurrency,\n interruption, or races.\n\nIf example research suggests an implementation or type bug, report it instead\nof changing runtime code during a documentation-only pass.\n","isInternal":false,"tokens":254,"sizeBytes":1225},{"name":"SKILL.md","path":".agents/skills/jsdocs/SKILL.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/jsdocs/SKILL.md","title":"jsdocs","category":"anthropic-skill","format":"markdown","content":"---\nname: jsdocs\ndescription: Public API JSDoc. Use when authoring or reviewing Effect API documentation, refining a module's documentation, or fixing documentation related diagnostics.\n---\n\n## Workflow\n\n1. Inspect the declaration, implementation, nearby JSDoc, tests, and call sites.\n2. Select every applicable branch and load its reference before editing:\n - tags, modules, or links: [declarations.md](declarations.md);\n - categories: [categories.md](categories.md);\n - examples: [examples.md](examples.md).\n3. Make a focused API fix or module refinement. Preserve verified facts and\n valuable examples rather than rewriting mechanically.\n4. For module refinement or APIs with close alternatives, audit `@see` links\n and inspect implementation and tests for concrete `**Gotchas**`.\n5. Run `pnpm jsdocs --check` and every applicable root validation command.\n\n`@internal` declarations and default exports are outside public JSDoc\nauthoring. Checked files do not support exported enums or empty export\ndeclarations.\n\nPublic declarations use a multiline block with one self-contained practical\ndescription paragraph. Start functions and methods with a present-tense action;\nmatch nearby noun-family phrasing for values. Optional non-empty sections appear\nonce in this order: `**When to use**`, `**Details**`, `**Gotchas**`. Separate\ndescriptions, sections, examples, and tags with one blank line. `**When to\nuse**` states a positive use case distinct from the description; reserve\n`**Gotchas**` for concrete caveats and failure modes.\n\nThe task is complete when every changed public declaration satisfies each\napplicable reference, the checker passes, runnable examples pass their targeted\ndoctest, and all other applicable root checks pass or are reported as not run.\n","frontmatter":{"name":"jsdocs","description":"Public API JSDoc. Use when authoring or reviewing Effect API documentation, refining a module's documentation, or fixing documentation related diagnostics."},"isInternal":false,"tokens":376,"sizeBytes":1777},{"name":"annotations.md","path":".agents/skills/migration-guidance/annotations.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/migration-guidance/annotations.md","title":"Migration-guidance Skill","category":"anthropic-skill","format":"markdown","content":"# Migration Annotations\n\nAdd or update one YAML file per v3 module under `migration/annotations/`. Use\nstable API IDs without trailing `#type` or `#value` facets:\n\n```yaml\neffect/Effect#async:\n replacement: Effect.callback\n note: Use the callback constructor.\n example: Effect.callback((resume) => resume(Effect.void))\n```\n\nEvery annotation requires `replacement` and `note`; `example` is optional. Use\n`replacement: none` when there is no direct replacement and explain the\nsupported migration strategy instead of inventing an equivalent API.\n","isInternal":false,"tokens":123,"sizeBytes":547},{"name":"generation.md","path":".agents/skills/migration-guidance/generation.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/migration-guidance/generation.md","title":"Migration-guidance Skill","category":"anthropic-skill","format":"markdown","content":"# Generated Migration Reference\n\n`migration/v3-to-v4.md` is generated. Check annotations and regenerate using\nexplicit committed refs containing the change:\n\n```sh\npnpm api-diff --base-ref origin/v3 --head-ref HEAD --check\npnpm api-diff --base-ref origin/v3 --head-ref HEAD --write-doc migration/v3-to-v4.md\n```\n\nThe API diff reads refs through detached worktrees. If the API change is\nuncommitted, `HEAD` does not contain it. Update known annotation IDs, defer the\ncheck and regeneration, and report the limitation. Do not create a temporary\ncommit solely to run the tool.\n","isInternal":false,"tokens":136,"sizeBytes":574},{"name":"SKILL.md","path":".agents/skills/migration-guidance/SKILL.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/migration-guidance/SKILL.md","title":"migration-guidance","category":"anthropic-skill","format":"markdown","content":"---\nname: migration-guidance\ndescription: Use when changing how a v3 public API maps to v4, editing migration annotations, or regenerating migration/v3-to-v4.md.\n---\n\nUpdate guidance when a v3 public module or API is renamed, moved, removed,\nreplaced, or gains a materially different v4 contract. A v4-only API without a\nv3 counterpart does not automatically need an annotation.\n\n1. Account for every affected v3 symbol.\n2. Read [annotations.md](annotations.md) before adding or changing annotation\n YAML. Verify every suggested replacement against implementation and tests.\n3. When checking or regenerating the reference, or when the API change exists in\n a committed ref, read [generation.md](generation.md). Otherwise report that\n generation is deferred.\n4. When output was generated, inspect it for unrelated movement and stale refs.\n\nThe task is complete when every affected v3 symbol is accounted for, annotation\nreplacements are verified, checks and generation succeed when the change is in\na committed ref, and every generated difference is explained. Report deferred\nchecks explicitly for uncommitted API changes.\n","frontmatter":{"name":"migration-guidance","description":"Use when changing how a v3 public API maps to v4, editing migration annotations, or regenerating migration/v3-to-v4.md."},"isInternal":false,"tokens":233,"sizeBytes":1129},{"name":"dependencies.md","path":".agents/skills/package-development/dependencies.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/package-development/dependencies.md","title":"Package-development Skill","category":"anthropic-skill","format":"markdown","content":"# Package Dependencies\n\nInspect the closest package with the same publication and integration shape.\nClassify every manifest entry by the role it serves:\n\n| Role | Use when |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------ |\n| `dependencies` | Published runtime code requires the package to receive its own installed copy. |\n| `peerDependencies` | Consumers provide a compatible shared package or the public contract integrates with their copy. |\n| `devDependencies` | Only repository build, test, type test, benchmark, or code generation needs the package. |\n| `optionalDependencies` | A runtime feature handles absence and installation failure must not block the base package. |\n| Optional peer via `peerDependenciesMeta` | A consumer-provided integration is genuinely optional. Keep its version in `peerDependencies`. |\n\nUse `workspace:^` for workspace packages unless neighboring packages establish a\ndifferent policy. When local build or tests need an installed peer, add the peer\nto `devDependencies` at the repository's tested version while keeping the peer\nrange based on supported consumer versions.\n\nDerive external versions from current consumers with the same integration\nshape. Add only direct requirements; do not copy a neighboring manifest entry\nthat the new package's runtime, declarations, build, or tests do not use.\n\nAfter editing manifests, run root `pnpm install`. Inspect warnings and the\npackage's `pnpm-lock.yaml` importer for intended specifiers and resolutions. If\na dependency has an install or native build, classify it under\n`pnpm-workspace.yaml#allowBuilds` using current repository policy.\n\nThis branch is complete when every entry has one justified role, workspace and\npeer ranges follow repository policy, the lockfile importer agrees with the\nmanifest, and install/build policy is explicit.\n","isInternal":false,"tokens":366,"sizeBytes":2166},{"name":"publishing.md","path":".agents/skills/package-development/publishing.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/package-development/publishing.md","title":"Package-development Skill","category":"anthropic-skill","format":"markdown","content":"# Publishing A Package\n\nCompare the package manifest with a neighboring published package in the same\nfamily.\n\n- Keep development `exports` and `publishConfig.exports` aligned by key.\n Source targets become their intended built targets; blocked internal and\n legacy paths remain blocked.\n- Check current AI documentation copy tooling and the package `files` list for\n every file required in the published payload.\n- Ensure each public source entrypoint has exactly one published counterpart\n and no internal entrypoint becomes exposed.\n\nRun the current root build so publication payload generation executes. Create a\ntarball in a temporary destination without publishing, inspect its file list,\nand inspect the packed `package.json` whenever manifest transformation matters.\n\nThis branch is complete when package and root checks pass and the packed\nsurface contains exactly the intended files, exports, and metadata.\n","isInternal":false,"tokens":170,"sizeBytes":921},{"name":"registration.md","path":".agents/skills/package-development/registration.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/package-development/registration.md","title":"Package-development Skill","category":"anthropic-skill","format":"markdown","content":"# Package Registration\n\nUse current configuration and the closest package in the same family as the\nsources of truth. A package-local build does not prove repository registration.\nClassify every row as applicable or not applicable.\n\n## Workspace And TypeScript\n\n| Surface | Check |\n| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `pnpm-workspace.yaml` | Its globs cover the package path and exact-name pnpm selection discovers it. |\n| `pnpm-lock.yaml` | The current importer, name, and dependencies exist; renamed or moved importers are gone. |\n| `tsconfig.packages.json` | Packages intended to participate in the root TypeScript project-reference graph are referenced. Follow neighboring package policy; buildable private tools are not automatically included. |\n| `tsconfig.tests.json` | Broad test globs cover the path. Add source aliases only when tests require workspace source routing or would otherwise create a dependency cycle. Preserve intentional platform exclusions. |\n\n## Tests And Documentation\n\n| Surface | Check |\n| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `vitest.config.ts` | A package with runtime tests has the intended project, environment, setup, and inclusion rules. |\n| `tstyche.json` | Type-test discovery covers the package depth; current globs cover one- and two-level package layouts. |\n| `vitest.docs.ts` | Doctest source discovery covers packages with runnable JSDoc examples; current globs cover one- and two-level package layouts. |\n| `jsdocs.config.json` | Public source is included in JSDoc checks and exclusions by package family remain intentional. |\n| `deno.json` | Deno checks cover the package family, or its exclusion is intentional. |\n\n## Release And Discovery\n\n| Surface | Check |\n| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `.changeset/config.json` | Published fixed-group membership uses the current name; private tooling is not added solely because it builds. |\n| `README.md` | Public catalog entries have the current name, path, description, and documentation link. |\n| AI documentation copy tooling and package `files` | Published payloads include required generated documentation. Continue with [publishing.md](publishing.md) for the full packed-surface audit. |\n| Snapshot publishing workflows | Snapshot publishing selects the package path. Existing globs may already cover it; apply root workflow requirements before editing. |\n| Runtime-specific CI workflows | Runtime-specific packages participate in applicable runtime jobs; apply root workflow requirements before editing. |\n\n## Paths And Consumers\n\nAudit explicit workspace package names in root tooling manifests. Search scripts\nfor the package family, old name, and old path to find path-sensitive clean,\ncodemod, circularity, copy, and related behavior. Explain every remaining old\nreference after a rename or move.\n","isInternal":false,"tokens":601,"sizeBytes":4390},{"name":"SKILL.md","path":".agents/skills/package-development/SKILL.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/package-development/SKILL.md","title":"package-development","category":"anthropic-skill","format":"markdown","content":"---\nname: package-development\ndescription: Package registration. Use when adding a workspace package, making a private package publishable, renaming a package, or moving its workspace path.\n---\n\nTreat package work as a registration change, not a directory copy.\n\n## Workflow\n\n1. Inspect the closest package in the same family. Classify publication status,\n runtime, test environment, platform support, barrels, and dependency shape.\n Justify each proposed file by precedent or an explicit repository need.\n Continue when every proposed file is justified.\n2. Create or move only required source, test, TypeScript, and manifest files.\n When manifest dependencies change, read [dependencies.md](dependencies.md)\n and classify every entry by role.\n Continue when pnpm discovers the intended name and manifests reference no\n absent file.\n3. Read [registration.md](registration.md). Classify every registration surface\n as applicable or not applicable and update every applicable surface.\n Continue when every surface is classified and old references are explained.\n4. For a published package, read [publishing.md](publishing.md) and verify its\n development and packed surfaces.\n5. Run codegen when the package owns generated barrels, then inspect generated\n sections rather than editing them manually.\n Continue when generated sections match source modules without manual edits.\n6. Run focused package tests and scripts plus applicable root checks. Include\n public API type tests when applicable. For published packages, build and dry\n pack the package as described in [publishing.md](publishing.md).\n Continue when focused and root checks pass and the packed surface is intended.\n7. Apply root changeset, generated-file, documentation, and workflow routing.\n\nThe task is complete when package discovery, registration, generated output,\nvalidation, packed output, and changeset routing are all verified or reported\nas not applicable.\n","frontmatter":{"name":"package-development","description":"Package registration. Use when adding a workspace package, making a private package publishable, renaming a package, or moving its workspace path."},"isInternal":false,"tokens":379,"sizeBytes":1959},{"name":"runtime.md","path":".agents/skills/performance-analysis/runtime.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/performance-analysis/runtime.md","title":"Performance-analysis Skill","category":"anthropic-skill","format":"markdown","content":"# Runtime Performance\n\nFor authoritative base/head comparisons or fixture work, read\n`packages/effect/runtimeperf/README.md`. Use `pnpm runtimeperf-compare\n` for local worktree comparisons and explicit `--base`/`--head`\nonly for committed refs. Report the resolved comparison head and measurement\nconfiguration.\n\nFor exploratory scripts under `benchmark/`, match nearby Tinybench scripts,\nkeep setup outside the measured callback unless setup is the operation, warm\nreusable state, close resources, and print the table. Label results exploratory\nunless the task defines a repeatable comparison protocol.\n\nFocused runtimeperf work is complete when fixture validation and the selected\nrun succeed. Comparison work additionally requires every configured round to\nsucceed, the paired statistical classification to support the conclusion, and\nresolved refs and settings to be reported. Harness changes require its focused\nchecks. Tinybench work is complete when resources close, the table is reported,\nand claims remain exploratory unless a repeatable protocol was run.\n","isInternal":false,"tokens":208,"sizeBytes":1080},{"name":"SKILL.md","path":".agents/skills/performance-analysis/SKILL.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/performance-analysis/SKILL.md","title":"performance-analysis","category":"anthropic-skill","format":"markdown","content":"---\nname: performance-analysis\ndescription: Performance analysis. Use for runtime throughput or latency benchmarks, TypeScript compiler cost, performance regressions, comparison harnesses, or thresholds.\n---\n\nValidate correctness with focused tests before measuring. Compare the same\nfocused operation and environment across revisions; a single unpaired run is\nnot evidence of improvement.\n\nSelect every applicable branch:\n\n- **Runtime performance:** Read [runtime.md](runtime.md).\n- **Type performance:** Read [types.md](types.md).\n\nThe task is complete when every selected branch meets its measurement and\nreporting criteria and applicable root checks pass or are reported as not\nrunnable.\n","frontmatter":{"name":"performance-analysis","description":"Performance analysis. Use for runtime throughput or latency benchmarks, TypeScript compiler cost, performance regressions, comparison harnesses, or thresholds."},"isInternal":false,"tokens":127,"sizeBytes":692},{"name":"types.md","path":".agents/skills/performance-analysis/types.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/performance-analysis/types.md","title":"Performance-analysis Skill","category":"anthropic-skill","format":"markdown","content":"# Type Performance\n\nRead `packages/effect/typeperf/README.md` before adding fixtures, changing the\nharness, updating thresholds, or running cross-ref comparisons. Isolate one\nrealistic public type path and compare the same fixture and compiler environment\nacross revisions. Derive supported suites and comparison commands from the\ncurrent harness documentation and CLI.\n\nBefore changing a threshold, record its previous value and measured result,\nexplain the expected delta, update it, and run a clean focused verification.\nKeep ordinary threshold fixtures separate from cross-ref fixtures.\n\nThis branch is complete when the focused measurement is repeatable, threshold\nverification is clean when applicable, and reported comparisons include\nresolved refs, compiler version, and an explanation of the observed delta.\nFixture or harness changes also require the focused validation and formatting\nchecks documented in the README.\n","isInternal":false,"tokens":167,"sizeBytes":928},{"name":"SKILL.md","path":".agents/skills/pull-requests/SKILL.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/pull-requests/SKILL.md","title":"pull-requests","category":"anthropic-skill","format":"markdown","content":"---\nname: pull-requests\ndescription: Pull request finalization. Use when a change works and is about to be opened as a pull request, or when updating or continuing an existing one.\n---\n\nA pull request is ready when its tests, implementation, comments, and changeset\nare each the simplest that cover the intended behavior. Draft PRs can be used\nearlier; finishing means making the PR ready for review.\n\n## Workflow\n\nRun each step in a fresh-context subagent when available; otherwise run it\nyourself. Pass along the task context and prior results so each step can check its gate.\n\n1. Keep tests focused. Read [test-development](../test-development/SKILL.md) for\n test placement and type. Cover each intended behavior once, in the existing\n test file for the module.\n For changes needing no tests, record why.\n Continue when removing any remaining case would leave intended behavior\n uncovered, or no tests are needed.\n2. Simplify the implementation. With the tests passing, look for a simpler or\n more idiomatic version: reuse helpers and patterns from nearby source and\n [effect-development](../effect-development/SKILL.md), and remove debugging\n code, scaffolding, and changes unrelated to the task.\n Continue when applicable targeted tests pass and every hunk in the diff\n from the merge base is required by the task.\n3. Review the full diff from the merge base as a maintainer would: correctness,\n failure and interruption paths, resource cleanup, naming and API\n consistency with neighboring modules, and documentation. Fix findings and\n review again.\n Continue when a review pass produces no findings.\n4. Clean up. Remove comments that restate code or narrate the change; keep the\n rest short and about why. Finalize the changeset with\n [changesets](../changesets/SKILL.md).\n Continue when comments explain only what code cannot, and the changeset\n describes the final consumer impact or the no-changeset reason is recorded.\n5. Run the validation in the [AGENTS.md validation table](../../AGENTS.md#validation)\n for each change type in the diff. Fix failures caused by the change; if\n fixes alter the diff, repeat the affected passes.\n Continue when applicable checks pass or commands that cannot run and their\n blockers are recorded.\n6. Open or update the pull request. Title: a short imperative summary.\n Description: the problem addressed, notable decisions, and `Closes #` for each\n GitHub issue resolved. Do not narrate the diff. Mark the PR ready for review.\n Continue when the final changes are pushed, the description matches the\n final diff, and the PR is ready for review.\n\nThe task is complete when each step's gate holds, validation has passed or\nbeen reported as not runnable with reasons, and the pull request is ready for\nreview with a description matching the final diff.\n","frontmatter":{"name":"pull-requests","description":"Pull request finalization. Use when a change works and is about to be opened as a pull request, or when updating or continuing an existing one."},"isInternal":false,"tokens":616,"sizeBytes":2852},{"name":"displayed-types.md","path":".agents/skills/test-development/displayed-types.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/test-development/displayed-types.md","title":"Test-development Skill","category":"anthropic-skill","format":"markdown","content":"# Displayed Types\n\nDeliberately produce an assignment error and match a distinctive substring with\nTstyche's checked `@ts-expect-error` message:\n\n```ts\nit(\"simplifies the displayed type\", () => {\n const value = null as unknown as PublicType\n\n // @ts-expect-error Type '{ readonly value: string; }'\n const displayed: never = value\n\n void displayed\n})\n```\n\nKeep the expected substring as small as possible while distinguishing the\npublic type from the leaked implementation type. Before accepting the test,\ntemporarily restore the broken type and confirm the diagnostic-message match\nfails.\n","isInternal":false,"tokens":130,"sizeBytes":593},{"name":"runtime.md","path":".agents/skills/test-development/runtime.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/test-development/runtime.md","title":"Test-development Skill","category":"anthropic-skill","format":"markdown","content":"# Runtime Tests\n\n- Use `it.effect` for Effect-returning tests and regular `it` for pure\n synchronous tests.\n- `it.effect` and `it.live` provide and close a `Scope`; return scoped effects\n directly instead of wrapping the body in `Effect.scoped`.\n- Use `assert` from `@effect/vitest`, not Vitest's `expect`.\n- Use `TestClock` for time-dependent behavior.\n- Keep `Effect.runSync` out of unit tests; runnable documentation follows the\n root JSDoc validation rules.\n\nInspect nearby tests for imports and structure. This branch is complete when\nevery changed behavior has focused coverage and its targeted test passes.\n","isInternal":false,"tokens":142,"sizeBytes":617},{"name":"SKILL.md","path":".agents/skills/test-development/SKILL.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/test-development/SKILL.md","title":"test-development","category":"anthropic-skill","format":"markdown","content":"---\nname: test-development\ndescription: Test development. Use when adding or changing Vitest or Tstyche coverage. Choose Tstyche only for intended compiler behavior such as inference, assignability, rejection, or displayed public types.\n---\n\nChoose branches from the task's acceptance criteria before editing:\n\n- **Runtime behavior:** The intended result is observable when code executes.\n Read [runtime.md](runtime.md).\n- **Compiler behavior:** The intended result is TypeScript accepting, rejecting,\n or inferring a consumer expression in a particular way. Read\n [types.md](types.md).\n\nAn exported signature alone is validated by `pnpm check`; it enters the compiler\nbranch only when its inference, assignability, rejection, overload selection, or\ndisplayed type is part of the task. Some changes require both branches because\nthey independently change runtime and compiler behavior.\n\nThe task is complete when each intended behavior in scope has the relevant\nfocused coverage, targeted tests pass, and applicable root checks pass or are\nreported as not runnable.\n","frontmatter":{"name":"test-development","description":"Test development. Use when adding or changing Vitest or Tstyche coverage. Choose Tstyche only for intended compiler behavior such as inference, assignability, rejection, or displayed public types."},"isInternal":false,"tokens":209,"sizeBytes":1069},{"name":"types.md","path":".agents/skills/test-development/types.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/test-development/types.md","title":"Test-development Skill","category":"anthropic-skill","format":"markdown","content":"# Type tests\n\nEnter this branch when the acceptance criterion is compiler behavior: inference,\nassignability, rejection, overload selection, generic constraints, or a displayed\npublic type. Use `pnpm check` for ordinary declaration edits whose compiler\nbehavior is not independently under test. A runtime bug in generic code needs a\nruntime regression test, not a type test, when its type contract is unchanged.\n\nInspect nearby `.tst.ts` files and use their imports and assertion style. Use\nordinary Tstyche assertions such as `toBe` for structural equality and choose a\nspecific assertion for the inference or assignability contract under test.\n\nStructural equality does not verify editor quick-info rendering. For internal\naliases, unsimplified intersections, or other displayed-type regressions, read\n[displayed-types.md](displayed-types.md).\n\nRun targeted `pnpm test-types `; the root command covers every\nconfigured TypeScript version. For a regression fix, confirm the assertion\nfails against the pre-fix type. This branch is complete when the assertion\nproves the intended contract and the target passes.\n","isInternal":false,"tokens":222,"sizeBytes":1122},{"name":"browser-assets.md","path":".agents/skills/vendored-assets/browser-assets.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/vendored-assets/browser-assets.md","title":"Vendored-assets Skill","category":"anthropic-skill","format":"markdown","content":"# Browser Asset Audit\n\nFor browser-delivered JavaScript or CSS, inspect the complete generated output\nfor:\n\n- CSP requirements and dynamic code execution;\n- injected markup, scripts, or styles;\n- network destinations and runtime loading;\n- external URLs, source maps, and runtime fetches;\n- bundled code or notices absent from upstream top-level metadata.\n\nEvery destination and executable behavior must be attributable to the selected\nupstream release. Resolve or report suspicious content before completion.\n","isInternal":false,"tokens":93,"sizeBytes":510},{"name":"SKILL.md","path":".agents/skills/vendored-assets/SKILL.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/.agents/skills/vendored-assets/SKILL.md","title":"vendored-assets","category":"anthropic-skill","format":"markdown","content":"---\nname: vendored-assets\ndescription: Vendored assets. Use when importing or updating checked-in third-party or externally generated JavaScript, CSS, registries, schemas, snapshots, or Scalar, Swagger, and MIME artifacts.\n---\n\nTreat upstream artifacts as supply-chain inputs. Change their generator or\ndocumented import source, then regenerate; generated output is review evidence,\nnot an editing surface.\n\n## Workflow\n\n1. **Trace ownership.** Identify the artifact, generator or exact import\n procedure, upstream source/version, license, consumers, tests, and shipped\n package or bundle. Search by asset and upstream project name to find current\n packaging scripts, generated artifacts, consumers, and history.\n Continue when every input and consumer is accounted for.\n2. **Pin provenance.** Resolve moving URLs, tags, branches, and omitted versions\n to an immutable release or artifact. Record project, version, path or URL,\n and digest in the generator or maintenance header. Omit a digest only when\n another enforced immutable source is recorded.\n Continue when a future run cannot silently select different bytes.\n3. **Clear the license gate.** Verify release metadata, license files, bundled\n notices, and the license trail retained in the distributed form.\n Continue when every distributed artifact has a verified retained license trail.\n4. **Regenerate.** Improve the generator or import reference first. Recover an\n exact procedure for generatorless assets; add a deterministic script only\n for recurring updates. Record a one-off procedure beside the artifact. A\n clean rerun must produce no diff.\n5. **Audit the complete diff.** Account for behavior, URLs and runtime fetches,\n source maps, notices, encoding, format changes, and additions or removals.\n For browser assets, also read [browser-assets.md](browser-assets.md).\n Continue when every change is attributable and suspicious content is resolved\n or reported.\n6. **Clear test and size gates.** Record byte sizes before and after, use\n focused consumer tests, and compare bundle size or composition when shipped\n JavaScript, CSS, or registry output changes materially. Compare that output\n against the pre-update revision rather than measuring only current size.\n Continue when focused checks pass and every non-trivial size delta is explained.\n7. **Close release impact.** Apply root changeset routing for consumer-visible\n behavior, browser support, wire data, or meaningful shipped-size changes.\n Generated sections owned by barrels, AI docs, or migration tooling remain\n with the owners named in root instructions.\n\nThe task is complete when every input and consumer is accounted for, provenance\nand licenses are immutable and retained, regeneration is deterministic, every\noutput change and non-trivial size delta is explained, focused checks pass or\nare reported as not runnable, and release impact is recorded.\n","frontmatter":{"name":"vendored-assets","description":"Vendored assets. Use when importing or updating checked-in third-party or externally generated JavaScript, CSS, registries, schemas, snapshots, or Scalar, Swagger, and MIME artifacts."},"isInternal":false,"tokens":588,"sizeBytes":2934},{"name":"README.md","path":"packages/ai/anthropic/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/ai/anthropic/README.md","title":"anthropic Documentation","category":"plugin-manifest","format":"markdown","content":"# @effect/ai-anthropic\n\nAn [Anthropic](https://www.anthropic.com) provider for the Effect AI modules. Includes a typed Anthropic API client, language model layers, tools, and telemetry helpers.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-anthropic\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/ai-anthropic): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","isInternal":false,"tokens":359,"sizeBytes":1543},{"name":"README.md","path":"packages/ai/cloudflare/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/ai/cloudflare/README.md","title":"cloudflare Documentation","category":"plugin-manifest","format":"markdown","content":"# @effect/ai-cloudflare\n\nCloudflare Workers AI provider for Effect's `DecisionModel`. Supports text and JSON classification, ordered ratings, and probabilities with Clef and Clef-flash over REST.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-cloudflare\n```\n\n## Usage\n\nSet `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`, then provide a Cloudflare decision model:\n\n```ts\nimport { CloudflareClient, CloudflareDecisionModel } from \"@effect/ai-cloudflare\"\nimport { Effect, Layer, Schema } from \"effect\"\nimport { Decision, DecisionModel } from \"effect/ai\"\nimport { FetchHttpClient } from \"effect/http\"\n\nconst Triage = Decision.make({\n input: Schema.String,\n decisions: {\n urgent: Decision.probability({\n instructions: \"Does this request need immediate attention?\"\n })\n }\n})\n\nconst Clef = CloudflareDecisionModel.layer({ model: \"clef-flash\" }).pipe(\n Layer.provide(CloudflareClient.layerConfig()),\n Layer.provide(FetchHttpClient.layer)\n)\n\nconst program = DecisionModel.decide(Triage, {\n input: \"Checkout has been failing for every customer for an hour.\"\n}).pipe(Effect.provide(Clef))\n```\n\nPass `images` to include pictures with the input. Clef shows them to the model before the state:\n\n```ts\ndeclare const screenshotBytes: Uint8Array\n\nconst withScreenshot = DecisionModel.decide(Triage, {\n input: \"Customers report this checkout error.\",\n images: [{ mediaType: \"image/png\", data: screenshotBytes }]\n})\n```\n\nImage `data` may be a `Uint8Array`, a base64 string, or a `data:` URL. Remote URLs fail with `AiError.InvalidUserInputError` because Clef does not fetch them, so download the image first. The API accepts up to 4 PNG, JPEG, or WebP images, each at most 4 MiB and 16 megapixels, with 8 MiB of decoded images in total and a 13 MiB request body.\n\nUse `\"clef\"` for the larger model. `CloudflareDecisionModel.model` provides a model descriptor with Cloudflare provider metadata. `CloudflareClient.layer` accepts an explicit account ID and redacted API token; `apiUrl` and `transformClient` customize HTTP access.\n\nInstructions and descriptions can be strings, JSON objects, or JSON arrays. A rating level with a structured description takes an explicit `label`, which answers use.\n\nThe client unwraps Cloudflare's REST envelope and maps failures to `AiError`. It does not retry automatically. Rate-limit errors include `Retry-After` when provided. The decision model validates answers and rescales small probability drift from four-decimal rounding.\n\nCloudflare limits each request to 64 questions, classification to 2–255 choices, and ratings to 2–10 levels. See the [Clef API documentation](https://developers.cloudflare.com/workers-ai/models/clef/) for request limits.\n\n## AI Gateway\n\nSet `CLOUDFLARE_AI_GATEWAY_ID` when using `CloudflareClient.layerConfig()` to route requests through a Cloudflare AI Gateway. You can also pass `gatewayId` to `CloudflareClient.layer`. The client adds the `cf-aig-gateway-id` header. Use `transformClient` to add other `cf-aig-*` headers.\n","isInternal":false,"tokens":709,"sizeBytes":3006},{"name":"README.md","path":"packages/ai/openai-compat/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/ai/openai-compat/README.md","title":"openai-compat Documentation","category":"plugin-manifest","format":"markdown","content":"# @effect/ai-openai-compat\n\nConnects the Effect AI modules to any OpenAI-compatible API, with support for chat completions and embeddings.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-openai-compat\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/ai-openai-compat): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","isInternal":false,"tokens":346,"sizeBytes":1496},{"name":"README.md","path":"packages/ai/openai/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/ai/openai/README.md","title":"openai Documentation","category":"plugin-manifest","format":"markdown","content":"# @effect/ai-openai\n\nAn [OpenAI](https://openai.com) provider for the Effect AI modules. Includes a typed OpenAI API client, language model and embedding model layers, tools, and telemetry helpers.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-openai\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/ai-openai): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","isInternal":false,"tokens":357,"sizeBytes":1541},{"name":"README.md","path":"packages/ai/openrouter/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/ai/openrouter/README.md","title":"openrouter Documentation","category":"plugin-manifest","format":"markdown","content":"# @effect/ai-openrouter\n\nAn [OpenRouter](https://openrouter.ai) provider for the Effect AI modules. Includes a typed OpenRouter API client and language model layers.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-openrouter\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/ai-openrouter): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","isInternal":false,"tokens":348,"sizeBytes":1517},{"name":"README.md","path":"packages/ai/typesafe/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/ai/typesafe/README.md","title":"typesafe Documentation","category":"plugin-manifest","format":"markdown","content":"# @effect/ai-typesafe\n\nTypeSafe System One provider for Effect's `DecisionModel`. Supports classification, ordered ratings, and probabilities through Effect `HttpClient`.\n\n## Installation\n\n```sh\nnpm install effect @effect/ai-typesafe\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/ai-typesafe): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n\n## Usage\n\nUse `TypeSafeClient.layerConfig()` to read `TYPESAFE_API_KEY`, then provide `TypeSafeDecisionModel.model(\"jev-latest\")` to a decision workflow. Versioned model identifiers such as `jev-1.13.0` are also supported.\n\nInstructions and descriptions can be strings, JSON objects, or JSON arrays, as in TypeSafe's [structured questions](https://docs.typesafe.ai/primitives/advanced). A rating level with a structured description takes an explicit label, which answers use:\n\n```ts\nimport { Decision } from \"effect/ai\"\n\nconst severity = Decision.rate({\n instructions: \"How severe is the reported issue?\",\n criteria: [\n { label: \"cosmetic\", description: { what: \"No impact to functionality\", examples: [\"typo in a label\"] } },\n { label: \"degraded\", description: { what: \"Broken, but a workaround exists\", examples: [\"fails in one browser\"] } },\n { label: \"blocking\", description: { what: \"No workaround exists\", examples: [\"cannot log in\"] } }\n ]\n})\n```\n\nThe client does not retry automatically. Rate-limit errors include the provider's retry delay when available. Provider distributions are preserved, not normalized; they must satisfy the core `DecisionModel` validation, including its current `1e-6` sum tolerance. TypeSafe's rounding behavior has not been verified against the live API.\n","isInternal":false,"tokens":642,"sizeBytes":2822},{"name":"README.md","path":"packages/atom/react/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/atom/react/README.md","title":"react Documentation","category":"plugin-manifest","format":"markdown","content":"# @effect/atom-react\n\n[React](https://react.dev) bindings for Atom, the reactive state management modules for Effect. Includes hooks for reading and updating atoms, and helpers for server-side rendering hydration.\n\n## Installation\n\n```sh\nnpm install effect @effect/atom-react\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/atom-react): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","isInternal":false,"tokens":351,"sizeBytes":1559},{"name":"README.md","path":"packages/atom/solid/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/atom/solid/README.md","title":"solid Documentation","category":"plugin-manifest","format":"markdown","content":"# @effect/atom-solid\n\n[SolidJS](https://www.solidjs.com) bindings for Atom, the reactive state management modules for Effect.\n\n## Installation\n\n```sh\nnpm install effect @effect/atom-solid\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/atom-solid): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","isInternal":false,"tokens":339,"sizeBytes":1471},{"name":"README.md","path":"packages/atom/vue/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/atom/vue/README.md","title":"vue Documentation","category":"plugin-manifest","format":"markdown","content":"# @effect/atom-vue\n\n[Vue](https://vuejs.org) bindings for Atom, the reactive state management modules for Effect.\n\n## Installation\n\n```sh\nnpm install effect @effect/atom-vue\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/atom-vue): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","isInternal":false,"tokens":339,"sizeBytes":1455},{"name":"README.md","path":"packages/effect/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/effect/README.md","title":"effect Documentation","category":"plugin-manifest","format":"markdown","content":"# effect\n\nEffect is a library for building robust, maintainable, type-safe, and production grade applications in TypeScript.\n\nThe `effect` package is the core of the framework. It provides primitives for managing side effects, errors, concurrency, resources, and structured data, alongside a rich standard library.\n\n> **Effect 4.x is a long-term support (LTS) release**, with at least three years of bug and security fixes. If you are upgrading from Effect 3.x, follow the [migration guide](https://github.com/Effect-TS/effect/blob/main/MIGRATION.md).\n\n## Installation\n\n```sh\nnpm install effect\n```\n\n## Requirements\n\n- **TypeScript 5.9 or newer.** TypeScript 7 is recommended for the best performance and compatibility with [Effect's TypeScript tooling](https://github.com/Effect-TS/tsgo#installation).\n- **Node.js 18 or newer** when running Effect on Node.js.\n- **Strict type-checking:** the `strict` flag must be enabled in your `tsconfig.json`:\n\n ```json\n {\n \"compilerOptions\": {\n \"strict\": true\n }\n }\n ```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/effect): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n\n## Overview\n\nThe `effect` package is a collection of modules. Some of the core ones:\n\n| Module | Description |\n| -------- | -------------------------------------------------------------------------------------------------------------------------- |\n| Effect | The core abstraction for managing side effects, concurrency, and error handling in a structured way. |\n| Context | A lightweight dependency injection mechanism that enables passing services through computations without direct references. |\n| Layer | A system for managing dependencies, allowing for modular and composable resource allocation. |\n| Fiber | Lightweight virtual threads with resource-safe cancellation capabilities, enabling many features in Effect. |\n| Stream | A powerful abstraction for handling asynchronous, event-driven data processing. |\n| Schedule | A module for defining retry and repeat policies with composable schedules. |\n| Scope | Manages the lifecycle of resources, ensuring proper acquisition and release. |\n| Schema | A powerful library for defining, validating, and transforming structured data with type-safe encoding and decoding. |\n\nIn v4, functionality that previously lived in separate packages ships inside `effect` under the `effect/*` namespaces, including `http`, `http-api`, `rpc`, `cluster`, `workflow`, `cli`, `ai`, `sql`, and `reactivity`.\n","isInternal":false,"tokens":790,"sizeBytes":3985},{"name":"README.md","path":"packages/effect/runtimeperf/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/effect/runtimeperf/README.md","title":"runtimeperf Documentation","category":"plugin-manifest","format":"markdown","content":"# Effect Runtime Performance\n\nThis harness measures focused synchronous runtime paths in fresh Node\nprocesses. It supports:\n\n- focused Effect Schema diagnostics;\n- native Arbitrary comparisons against equivalent fast-check v4 arbitraries;\n- the upstream Effect, Valibot and Zod benchmark matrix;\n- paired comparisons between Git revisions or the current working tree.\n\nCross-library results are diagnostic. Effect base/head comparisons are the\nauthoritative measurement for source changes.\n\n## Commands\n\nRun the complete registry:\n\n```sh\npnpm runtimeperf\n```\n\nRun the cases extracted from the `effect@beta`, Valibot and Zod adapters in\n[`open-circle/schema-benchmarks`](https://github.com/open-circle/schema-benchmarks):\n\n```sh\npnpm runtimeperf schema-benchmarks\npnpm runtimeperf-compare schema-benchmarks --base main --head HEAD\n```\n\nThis suite covers every upstream timing case supported by those adapters:\nschema and decoder initialization, validation, parsing and Standard Schema\nwith valid/invalid inputs and first/all error modes, plus BigInt codec\noperations. The upstream bundle and stack reports are not throughput\nbenchmarks, and the adapters do not define the optional string-format cases.\n\nSelect a suite, fixture, shared scenario, tier, family or implementation:\n\n```sh\npnpm runtimeperf schema\npnpm runtimeperf arbitrary\npnpm runtimeperf object-32-valid\npnpm runtimeperf schema/object-32-valid-effect\npnpm runtimeperf --family arrays\npnpm runtimeperf --implementation zod4\npnpm runtimeperf --implementation zod4-compiled\n```\n\nOverride measurement settings:\n\n```sh\npnpm runtimeperf object-32-valid --rounds 9 --time 500 --warmup-time 150\n```\n\nCompare Effect `HEAD` with the working tree:\n\n```sh\npnpm runtimeperf-compare schema/object-32-valid-effect\n```\n\nMeasure excess-property checking and symbol enumeration in interpreted and JIT parsers:\n\n```sh\npnpm runtimeperf-compare schema-excess-properties\npnpm runtimeperf-compare schema-excess-properties --family jit\n```\n\nCompare explicit refs:\n\n```sh\npnpm runtimeperf-compare schema --base main --head HEAD\n```\n\nOnly `--fail-on-regression` turns a statistically classified regression into a\nnon-zero comparison exit code. Worker, fixture, configuration and Git errors\nalways fail.\n\nReports are written under `tmp/runtimeperf/results/`. Temporary Git worktrees\nare created under `tmp/runtimeperf/worktrees/` and removed in `finally`.\n\n## Registry\n\n`config.json` groups fixture cases by source file. Every case records:\n\n- tier and family;\n- covered Effect AST tags;\n- operation and path;\n- input size;\n- implementation;\n- a shared scenario name for cross-library comparisons.\n\nThe `schema` suite is Effect-only and retains targeted diagnostics for scaling,\ntemplate literals, unions, records, transformations, optional properties,\nadapters, recursion and cold paths. The `schema-benchmarks` suite contains the\ncomplete timing matrices exposed by the upstream Effect, Valibot and Zod\nadapters.\n\nThe `moltar-parse-safe` and `moltar-assert-loose` suites preserve Moltar's\nobject shape. Their valid cases reproduce the upstream timed operation; the\nextra-property and invalid cases are Effect extensions. They compare\ninterpreted Effect, Effect JIT and AOT, Valibot, ordinary and jitless Zod where\napplicable, and Zod `compile`, using the dependency versions recorded in each\nreport.\n\nThe `arbitrary` suite compares the native public API with direct fast-check v4 arbitraries in separate processes. It\nmeasures derivation through the first recursive sample, steady-state recursive\nsampling, optional-Struct sampling, fixed-length string generation to exercise constraint pushdown,\nbounded Number generation, direct Uint8Array generation, a rare residual filter, a fixed-length unique array, and a\nmixed regular expression through cold derivation, warm generation, and shrinking. It also covers literal sampling as\na runner baseline and the public `map`, `filter`, `filterMap`, and `all` combinators for tuples and records. The failure\npaths include a filtered failure with rejected shrink candidates, dependent `flatMap` sampling, shrinking, replay, a\npassing property, a failure that shrinks from `1000` to `1`, and replay of that failure. The\nrecursive distributions are implementation-defined, so the fixtures use\nimplementation-specific size settings and validate a comparable total node\ncount for the fixed seed. The bounded Number case is a throughput comparison,\nnot distribution parity: native selects among 64-bit IEEE-754 representations,\nwhile the fast-check fixture uses its 64-bit `double`. Replay is an\nend-to-end public API comparison, but the work is not identical: native replay\nverifies the original failure and its full shrink path, while fast-check can\nstart directly from its recorded path.\n\nArray cases cover passing checks and shrinking a four-command sequence while preserving an ordered pair. The latter\nstarts from the same explicit sequence in both engines, using a fixed seed for native generation and an example for\nfast-check. Base/head validation preserves the failure without requiring identical shrunk outputs, so its timing also\nreflects changes in how much of the shrink tree is explored. The runtime regression tests assert the smaller result.\n\nThe regular-expression fixtures validate the same language, and both fixed-seed warm fixtures must reach multiple\nlengths and every alternative family. Their exact distributions remain implementation-defined, so cross-library\ntimings are diagnostic while base/head comparisons protect the cost of each implementation's established behavior.\n\nAn impossible Schema filter is deliberately not a cross-engine timing case.\nThe native runner reports bounded exhaustion, while a direct fast-check arbitrary\nbuilt with `Arbitrary.filter` does not return from generation\nwhen no value can satisfy the predicate. Native exhaustion remains covered by\nthe Arbitrary tests instead of placing a permanently blocking fixture in the\nperformance harness.\n\nZod parsing cases import `zod/v4` and call `safeParse` with `{ jitless: true }`;\nits Standard Schema and codec cases use their native APIs. Valibot uses the\ncorresponding `is`, `safeParse` and Standard Schema APIs. The focused Effect\nadapter family measures the overhead of public APIs that wrap parser issues.\nThe compiler comparison calls `z.compile(schema, { strict: true })` and uses\nZod's `validate` API for boolean checks. Ten representative scenarios also run\nagainst equivalent Valibot schemas using `parse` and `is`.\n\n## Measurement model\n\nEach worker validates the fixture before and after measuring. The Effect\nfixture calibrates one batch size that every implementation in the same\nscenario uses. This keeps the enclosing loop identical across implementations;\nV8 can otherwise optimize sub-10 ns callbacks differently at different batch\nsizes. Each implementation executes in a separate process, with rotating order\nwithin the scenario.\n\nTinybench measures one synchronous batched task. The primary process result is:\n\n```text\nnsPerOp = totalTimeMs * 1_000_000 / (task.runs * batchSize)\n```\n\nTinybench latency statistics are retained as diagnostics and normalized by the\nbatch size. Independent Node processes, not Tinybench samples, are the\nstatistical observations.\n\nBase/head comparisons alternate execution order by round and analyze paired\nlog ratios with a deterministic bootstrap. The report keeps all raw worker\nresults so aggregates can be recalculated.\n\n## Fixture contract\n\nEach configured export is a factory:\n\n```ts\ntype RuntimePerfCase = {\n readonly run: () => unknown\n readonly validate: (result: unknown) => void\n}\n\ntype RuntimePerfCaseFactory = () => RuntimePerfCase\n```\n\nConstruct schemas, steady-state adapters and deterministic inputs in the\nfactory. Cold fixtures deliberately construct them inside `run`. A fixture\nmust measure one named operation, perform no I/O and return no Promise.\n\n## Validation\n\n```sh\nnode --test packages/effect/runtimeperf/test/*.test.mts\npnpm exec dprint check package.json packages/effect/runtimeperf\n```\n","isInternal":false,"tokens":1662,"sizeBytes":8044},{"name":"README.md","path":"packages/effect/runtimeperf/suites/compiler-rebuild/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/effect/runtimeperf/suites/compiler-rebuild/README.md","title":"compiler-rebuild Documentation","category":"plugin-manifest","format":"markdown","content":"# Compiler rebuild comparison\n\nThe `compiler-rebuild` suite measures 25 public SchemaParser operations with the\ninterpreter, selective JIT and generated AOT modules. Nineteen cases also run\nagainst `z.compile(schema, { strict: true })`; eleven representative cases run\nagainst Valibot and Zod with `{ jitless: true }`. The fixture families name the\nexecution mode. Cases\ncover simple and nested Structs, Arrays, tuples, Records, transformed Record\nkeys, anyOf/oneOf Unions, transformations, middleware, recursive and suspended\nschemas, Declarations, construction,\nand successful and failing validation.\n\nThe Effect tuple has a trailing element after its rest element, Zod compilation\ndoes not support recursive schemas or `z.xor`, and Zod has no equivalent\ndecoding middleware. Those four cases intentionally have no Zod fixture. Zod\ncompilation only accelerates forward parsing, so the encode case measures its\ndocumented runtime fallback. Zod parsing stands in for Effect construction\nbecause Zod has no separate constructor operation. Valibot parsing with defaults\nis used for the same comparison.\n\n```sh\npnpm runtimeperf-compare compiler-rebuild --base schema-compiler\npnpm runtimeperf-compare compiler-rebuild --base main --family interpreted\npnpm runtimeperf compiler-rebuild\n```\n\nThe first command compares the current working tree with the archived compiler\nbranch. The second isolates changes to interpreted parsing against main. Schema\nand parser construction are outside the steady-state measurements. AOT fixtures\ngenerate their version-specific module in a separate process before loading it.\n\nThe standard paired harness records five alternating rounds, validates every\nfixture before and after measurement, uses a common batch within each pair, and\nreports bootstrap confidence intervals. Cross-mode rankings are descriptive;\nthe paired base/head comparison is the regression evidence.\n\n## Retained heap and first use\n\nFor a current cross-library comparison of retained heap, V8 code memory, peak\nRSS and preparation CPU, run:\n\n```sh\nnode packages/effect/runtimeperf/suites/compiler-rebuild/run-resources.mts \\\n tmp/schema-compiler-resources.json 5 100,500\nnode packages/effect/runtimeperf/suites/compiler-rebuild/report-resources.mts \\\n tmp/schema-compiler-resources.json\n```\n\nEach sample runs in a fresh process. The report calculates median per-schema\nslopes between 100 and 500 distinct schemas, which removes fixed module and\nlazy initialization costs. Fixture inputs are released before retained-memory\nmeasurement. Preparation CPU includes adapter creation and first use; AOT also\nincludes loading and installing the generated module. AOT source generation is\nreported separately because it runs at build time. Hot synchronous CPU is\nalready represented by the normal runtime measurements.\n\nThe older Effect-only probe below remains available for comparisons with its\nexisting archived results.\n\nThe standalone cost probe accepts a checkout root, mode, operation, shape and\nschema count. Run several fresh processes per combination and alternate the\ncheckout order. Supported modes are `interpreted`, `jit` and `aot`; operations\nare `decode`, `invalid`, `is` and `make`; shapes are `struct`, `array`, `transform`\nand `default`.\n\n```sh\nnode --expose-gc packages/effect/runtimeperf/suites/compiler-rebuild/costs.mts heap \"$PWD\" jit decode struct 500\nnode --expose-gc packages/effect/runtimeperf/suites/compiler-rebuild/costs.mts cold \"$PWD\" jit decode struct 500\n```\n\nHeap measurements exclude schema construction and module imports, and retain\nboth schema objects and public parser functions. They include operation setup\nand first use. Forced GC removes transient parse output and issues. The AOT\ngenerator runs in a separate process, so its retained heap is not attributed to\nthe runtime application.\n\nFirst-use measurements include constructing a fresh schema, installing its\ncompiler when requested, creating a public parser and calling it. They exclude\nmodule imports and AOT source generation. Repeated shapes can benefit from V8's\nsource cache, so this is not process startup latency. Treat these timing probes\nas exploratory, separately from the paired throughput results.\n","isInternal":false,"tokens":865,"sizeBytes":4204},{"name":"README.md","path":"packages/effect/runtimeperf/suites/schema-checked-sources/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/effect/runtimeperf/suites/schema-checked-sources/README.md","title":"schema-checked-sources Documentation","category":"plugin-manifest","format":"markdown","content":"# Checked transformation sources\n\nThis suite reconstructs the motivating shape from PR #8597: decode an Array of\n1,000 rows, each containing eleven pattern-checked string fields and one `n`\nfield. The sibling fields match `/^[a-z][a-z0-9]{1,15}$/`, and the checked numeric\nsource matches `/^[0-9]{1,6}$/`. Rows contain `value0` through `value999` and\nnumeric strings `1` through `1000`. Schemas, inputs and parsers are prepared\noutside the measured callback. Each operation decodes all 1,000 rows.\n\n- `digits` validates the checked string without transforming it.\n- `checked-source` converts the checked numeric string to a number.\n- `unchecked-source` converts a plain string to a number.\n- `two-passes` first validates all fields, then decodes the validated output\n with a transformations-only Struct.\n- `checked-template-target` and `unchecked-template-target` convert the `n`\n field to a TemplateLiteral string prefixed with `x-`. They measure valid\n input through the parser fallback required to preserve template diagnostics.\n\nEvery worker validates the complete output before and after measuring. The\ncomparison harness copies the same fixtures into both revisions and alternates\nbase/head order in fresh Node processes.\n\n```sh\npnpm runtimeperf-compare schema-checked-sources --base main --head HEAD \\\n --rounds 16 --time 500 --warmup-time 150\n```\n\nThese fixtures use repository sources. The PR's original figures used packed\npackages on Node 26.10, so compare relative changes rather than absolute times.\n","isInternal":false,"tokens":342,"sizeBytes":1517},{"name":"README.md","path":"packages/effect/runtimeperf/suites/schema-construction/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/effect/runtimeperf/suites/schema-construction/README.md","title":"schema-construction Documentation","category":"plugin-manifest","format":"markdown","content":"# Schema construction costs\n\nThis diagnostic measures the current implementation before proposing changes. It leaves library sources unchanged.\nIt measures elapsed construction time in ordinary fresh Node processes, then uses separate V8 CPU-profiled processes\nto locate the work. Profile shares are estimates of sampled execution, not directly timed phases or predicted savings.\n\nRun from the repository root:\n\n```sh\nnode packages/effect/runtimeperf/suites/schema-construction/run.mts tmp/schema-construction 24 1000\n```\n\nArguments are a new output directory, rounds, root count, and an optional comma-separated list of case names.\nThe output directory's parent must exist. Existing output directories are rejected. The source tree must be clean.\nEvery raw observation is saved in `results.json`; raw `.cpuprofile` files can be opened in a CPU profile viewer.\nCopies of the measured harness files are retained in `harness/` to preserve uncommitted analysis code.\nThe report records the commit, source-tree object, harness and lockfile hashes, Node/V8 versions, machine and settings.\nInterrupted or failed runs retain `complete: false` and must not be reported as complete measurements.\n\n## Scope\n\nEach worker imports Schema, prepares fixture keys and validation inputs, and preallocates a root array before timing.\nIt then builds 1,000 new root schemas and retains them until the process exits. The timer includes field-map creation,\nchild schemas, checks, transformations, options and all eager internal work triggered by the declaration.\nThere is no explicit warmup. Schema's own import-time initialization has already run and can warm shared constructors\nand caches. Node startup, TypeScript loading, module imports, decoder preparation and decoding are excluded.\n\nFixtures cover literals; structs with 2, 32 and 256 fields; nested structs; arrays with checks, optional keys and literals;\nnew string-to-number transformations; and unions of eight newly constructed tagged members. Root counts are not counts\nof every intermediate schema. Shared primitive schemas such as `Schema.String` are imported constants. The `struct-N`\nfixtures build field maps with `Object.fromEntries` during timing. The additional `struct-ready-N` fixtures reuse a field\nmap prepared before timing, to isolate `Schema.Struct(fields)` with ready inputs. Primitive schemas, field-name strings\nand sample values are prepared beforehand in both cases. Dynamically generating fields is a distinct caller cost; it\ndoes not model a hand-written object literal's cost.\n\nEach fixture is validated in a separate process before measurement, including valid decode, type-side `.make`, and invalid\ninput rejection. Measured workers check root count, object kind and distinctness after timing. No prior validation warms\nthe measured worker. This protocol makes no claim about complete HttpApi/Confect startup, memory usage or warmed throughput.\n\n## Measurement and attribution\n\nEach round runs ordinary Node, profiling at a requested 100 microsecond interval, and profiling at 500 microseconds.\nWorkers run serially. The six possible orders rotate by round; fixture order also rotates. The default 24 rounds\nbalance all six orders. Do not run other benchmarks, builds or tests alongside the measurement.\n\nElapsed times are medians across independent processes, with median absolute deviation. Profiler perturbation is measured\nthrough paired ratios against the ordinary process in the same round, using the existing deterministic bootstrap with\n10,000 resamples. This is a check on measurement bias, not a comparison of optimized code.\n\nEach CPU sample is assigned to one category:\n\n| Category | Included work |\n| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |\n| `type-projection` | `toType` and its recursive traversal, clones and memoization, during synchronous maker preparation |\n| `ast` | Initial AST construction and changes made by checks, annotations, optional keys and transformations |\n| `schema-object` | Central schema constructor after subtracting identifiable child phases: function object, prototype, options, property and closure setup |\n| `make-sync` | Identifiable synchronous maker factory frames outside the type projection |\n| `make-effect` | Identifiable effectful maker factory frames outside the Option adapter |\n| `make-option` | Option adapter factory, including its separately allocated effectful maker |\n| `schema-api` | Other Schema API work, including composition wrappers and check factories outside AST constructors |\n| `fixture` | Caller-attributed samples: field maps, member lists, the loop, and library work inlined into those frames |\n| `gc` | Garbage collector samples inside the construction window |\n| `runtime` | Other runtime samples without an attributable Schema stack |\n\nChild work is never added again to its parent. V8 can omit an inlined `SchemaParser.make` frame. In these fixtures,\nthe only eager AST/Function subtree beneath central `make` is `toType`; this path is classified as projection even when\nthe parser wrapper is absent. The fixtures do not use options with getters that could invoke arbitrary AST work.\nCompletely inlined work that cannot be separated remains with the caller. The `fixture` category is therefore an\nunresolved caller category, not a measurement of pure benchmark overhead or field-map creation. A ready-field fixture\nwhose body only calls `Schema.Struct(fields)` still receives caller-attributed samples. Small or zero factory shares do not prove\nthat their allocations are free; allocation effects can appear in central construction or GC.\n\nProfiles are delimited by the first and last samples containing the worker's `constructBatch` frame. Samples outside\nthat span are excluded, including inspector setup. Interior GC/runtime samples are retained. Inspector timestamps and\n`hrtime` are not directly compared because their origins can differ. Missing boundary samples, especially GC before the\nfirst or after the last observed construction frame, are a limitation. The report keeps sample counts, sampled span\ncoverage and counts of processes with fewer than ten samples. A profile with no construction samples remains recorded\nand is excluded from share estimates. One sample has zero measured span coverage and is marked sparse.\n\nShares are unweighted sample proportions within each process, averaged across processes. Their 95% intervals bootstrap\nwhole processes, not individual correlated samples. Categories sum to 100% for the point estimates; interval endpoints\nneed not sum to 100%. These intervals cover sampling variability, not profiler bias or attribution errors. Compare the\ntwo sampling frequencies and their overhead before interpreting the shares. Do not convert them into exact milliseconds\nor predicted speedups. Short fixtures may support a reliable elapsed time without a useful internal breakdown.\n\nTop leaf functions and source-position ticks are retained as secondary diagnostics. Source-position ticks are not an\nadditional additive cost breakdown and may accumulate at a function's entry after optimization.\n\n## Validation\n\n```sh\nnode --test packages/effect/runtimeperf/test/*.test.mts\npnpm exec dprint check --includes-override 'packages/effect/runtimeperf/suites/schema-construction/*.mts' 'packages/effect/runtimeperf/test/schema-construction.test.mts'\n```\n\nThe attribution tests cover non-overlapping phases, inlined maker frames, Option's nested effect maker, profile boundaries,\ninterior garbage collection, missing samples and deterministic confidence intervals.\n","isInternal":false,"tokens":1473,"sizeBytes":8333},{"name":"README.md","path":"packages/effect/typeperf/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/effect/typeperf/README.md","title":"typeperf Documentation","category":"plugin-manifest","format":"markdown","content":"# Effect Type Performance\n\nThis harness measures deterministic TypeScript diagnostics for focused\nfixtures. Type instantiations and materialized types are regression gates, while\nsymbols are reported for additional context.\n\nUse it when a type-level change needs a small regression guard for the specific\ntype path that was optimized.\n\n## Core Model\n\nEach suite has one shared baseline. Fixture cost is reported separately for\ninstantiations, types, and symbols as:\n\n```txt\nmetric delta = fixture metric - suite baseline metric\n```\n\nThreshold files store exact maximum deltas for instantiations and types. Symbol\ndeltas are informational and do not affect the command status.\n\nThe runner compiles each baseline and fixture as an isolated TypeScript program\nby generating temporary `tsconfig` files under `tmp/typeperf`.\n\nFixtures must use realistic package imports:\n\n```ts\nimport { Schema } from \"effect\"\n```\n\nDo not import source files directly, for example do not use\n`../../src/Schema.ts`. The package self-reference should resolve the public\n`effect` package entry.\n\nEvery fixture in a suite should repeat the suite warmup expression from\n`baseline.ts`. For the current Schema suite, that means:\n\n```ts\nimport { Schema } from \"effect\"\n\nSchema.String\n```\n\n## Commands\n\nFrom the repository root:\n\n```sh\npnpm typeperf\npnpm typeperf schema\npnpm typeperf schema/struct-required\npnpm typeperf --update\npnpm typeperf schema/struct-required --update\n```\n\nWithout a target, the runner checks every suite and fixture. A target can be a\nsuite name (`schema`) or an individual fixture (`schema/struct-required`).\n\n`--update` writes exact measured instantiation and type deltas to threshold\nfiles. When a target is provided, only the selected suite or fixture is updated.\n\n## Cross-Ref Comparisons\n\nUse the separate comparison runner when a changeset needs measurements against\nanother Git revision:\n\n```sh\npnpm typeperf-compare httpapi --base main --head HEAD\npnpm typeperf-compare httpapi/endpoint-count-100 --base main --head HEAD\n```\n\nThe runner creates detached worktrees under `tmp/typeperf-compare`, copies the\nsame generated fixture sources into both worktrees, and compiles them with the\nTypeScript installation from the current checkout. Each fixture and baseline is\ncompiled once per revision. The normal `pnpm typeperf` suite and its thresholds\nare not affected.\n\nComparison fixtures use only APIs shared by both revisions. They also contain\ntype-level assertions that reject degenerate results such as missing methods or\n`never` endpoint selections. A fixture is comparable only when the exact same\nsource compiles on both revisions. Results are printed to the terminal and\nwritten as JSON under `tmp/typeperf-compare/results/`, including the resolved\nGit SHAs, TypeScript version, and fixture-suite hash.\n\n## Adding A Fixture\n\nAdd a fixture when a change optimizes one specific constructor, helper, or\ntype-level path.\n\n1. Create one file under the suite's `fixtures/` directory.\n2. Name it after the isolated behavior being measured, for example\n `struct-optional-only.ts`.\n3. Add a first-line comment explaining the single thing being measured.\n4. Use realistic package imports.\n5. Repeat the suite warmup expression.\n6. Build only the schema needed for that one behavior.\n7. Export type aliases that force TypeScript to instantiate the views under\n test.\n8. Add the fixture to `config.json`.\n9. Run `pnpm typeperf / --update`.\n10. Run `pnpm typeperf /`.\n\nExample:\n\n```ts\n// Measures the marginal type-level cost of Schema.Struct when all fields are optional keys.\nimport { Schema } from \"effect\"\n\nSchema.String\n\nconst schema = Schema.Struct({\n id: Schema.optionalKey(Schema.String),\n count: Schema.optionalKey(Schema.NumberFromString)\n})\n\nexport type Type = typeof schema.Type\nexport type Encoded = typeof schema.Encoded\nexport type Iso = typeof schema.Iso\nexport type MakeIn = typeof schema[\"~type.make.in\"]\n```\n\nThen register it:\n\n```json\n{\n \"name\": \"struct-optional-only\",\n \"file\": \"suites/schema/fixtures/struct-optional-only.ts\"\n}\n```\n\n### Fixture Rules\n\n- Measure one thing per fixture. Split separate paths into separate files.\n- Keep inputs realistic, but not large for its own sake.\n- Export the minimum type aliases needed to force the type computation being\n measured.\n- Do not combine multiple optimized APIs just to make the fixture look like an\n application model.\n- Do not add fixtures for unchanged or unrelated APIs.\n- Do not add fixture files to `packages/effect/tsconfig.json`; `pnpm typeperf`\n compiles them independently.\n- If a fixture fails to compile, fix the fixture or source types. Do not hide\n the problem by aggregating it with another fixture.\n\n## Adding A Suite\n\nAdd a suite when fixtures need a different shared baseline. For example,\nSchema-specific fixtures share the `schema` baseline, while HTTP API fixtures\nuse a different import and warmup.\n\n1. Create `suites//baseline.ts`.\n2. Create `suites//fixtures/`.\n3. Create `suites//thresholds.json` with `{}`.\n4. Add a suite entry to `config.json`.\n5. Add at least one focused fixture.\n6. Run `pnpm typeperf --update`.\n7. Run `pnpm typeperf `.\n\nExample suite entry:\n\n```json\n{\n \"name\": \"schema\",\n \"baseline\": \"suites/schema/baseline.ts\",\n \"thresholds\": \"suites/schema/thresholds.json\",\n \"fixtures\": [\n {\n \"name\": \"struct-required\",\n \"file\": \"suites/schema/fixtures/struct-required.ts\"\n }\n ]\n}\n```\n\nThe baseline should contain only the import and warmup common to every fixture in\nthat suite. If a fixture needs extra setup that others do not need, put that\nsetup in the fixture, not in the shared baseline.\n\n## Updating Thresholds\n\nUse `--update` only after verifying that the measured delta is expected.\n\n```sh\npnpm typeperf schema/struct-required --update\npnpm typeperf schema/struct-required\n```\n\n`--update` writes the exact measured deltas as `maxInstantiationsDelta` and\n`maxTypesDelta`. It does not add a margin:\n\n```json\n{\n \"struct-required\": {\n \"maxInstantiationsDelta\": 457,\n \"maxTypesDelta\": 50\n }\n}\n```\n\n## Validation Checklist\n\nAfter adding or changing fixtures:\n\n```sh\npnpm typeperf / --update\npnpm typeperf /\npnpm exec dprint check package.json packages/effect/typeperf\n```\n\nRun the broader suite when the change touches shared runner behavior:\n\n```sh\npnpm typeperf \n```\n","isInternal":false,"tokens":1466,"sizeBytes":6448},{"name":"README.md","path":"packages/opentelemetry/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/opentelemetry/README.md","title":"opentelemetry Documentation","category":"plugin-manifest","format":"markdown","content":"# @effect/opentelemetry\n\nAn [OpenTelemetry](https://opentelemetry.io) integration for Effect. Exports Effect tracing, metrics, and logs through the OpenTelemetry SDK, with `NodeSdk` and `WebSdk` layers for easy setup.\n\n## Installation\n\n```sh\nnpm install effect @effect/opentelemetry\n```\n\nThe relevant `@opentelemetry/*` SDK packages are required as peer dependencies, depending on which features you use.\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/opentelemetry): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","isInternal":false,"tokens":387,"sizeBytes":1687},{"name":"README.md","path":"packages/platform/browser/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/platform/browser/README.md","title":"browser Documentation","category":"plugin-manifest","format":"markdown","content":"# @effect/platform-browser\n\nBrowser implementations of the Effect platform services, including the HTTP client, workers, key-value storage, IndexedDB, clipboard, and geolocation.\n\n## Installation\n\n```sh\nnpm install effect @effect/platform-browser\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/platform-browser): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","isInternal":false,"tokens":340,"sizeBytes":1536},{"name":"README.md","path":"packages/platform/bun/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/platform/bun/README.md","title":"bun Documentation","category":"plugin-manifest","format":"markdown","content":"# @effect/platform-bun\n\n[Bun](https://bun.sh) implementations of the Effect platform services, including the file system, HTTP client and server, sockets, workers, and terminal.\n\n## Installation\n\n```sh\nnpm install effect @effect/platform-bun\n```\n\n## Links\n\n- [Website](https://effect.website): documentation, guides, and news.\n- [Reference](https://effect.website/docs/v4/api/platform-bun): API documentation for this package.\n- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.\n- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.\n- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.\n\n## Let's talk\n\nWhether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.\n\n- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.\n- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.\n- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.\n","isInternal":false,"tokens":348,"sizeBytes":1527},{"name":"README.md","path":"packages/platform/deno/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/platform/deno/README.md","title":"deno Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":348,"sizeBytes":1533},{"name":"README.md","path":"packages/platform/node-shared/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/platform/node-shared/README.md","title":"node-shared Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":350,"sizeBytes":1563},{"name":"README.md","path":"packages/platform/node/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/platform/node/README.md","title":"node Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":346,"sizeBytes":1538},{"name":"README.md","path":"packages/platform/node/test/cluster-integration/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/platform/node/test/cluster-integration/README.md","title":"cluster-integration Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":492,"sizeBytes":2277},{"name":"README.md","path":"packages/sql/clickhouse/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/sql/clickhouse/README.md","title":"clickhouse Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":352,"sizeBytes":1540},{"name":"README.md","path":"packages/sql/d1/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/sql/d1/README.md","title":"d1 Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":342,"sizeBytes":1467},{"name":"README.md","path":"packages/sql/libsql/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/sql/libsql/README.md","title":"libsql Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":353,"sizeBytes":1502},{"name":"README.md","path":"packages/sql/mssql/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/sql/mssql/README.md","title":"mssql Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":344,"sizeBytes":1483},{"name":"README.md","path":"packages/sql/mysql2/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/sql/mysql2/README.md","title":"mysql2 Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":347,"sizeBytes":1478},{"name":"README.md","path":"packages/sql/pg/benchmark/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/sql/pg/benchmark/README.md","title":"benchmark Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1262,"sizeBytes":5572},{"name":"README.md","path":"packages/sql/pg/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/sql/pg/README.md","title":"pg Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1482,"sizeBytes":6282},{"name":"README.md","path":"packages/sql/pglite/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/sql/pglite/README.md","title":"pglite Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":475,"sizeBytes":2022},{"name":"README.md","path":"packages/sql/sqlite-bun/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/sql/sqlite-bun/README.md","title":"sqlite-bun Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":352,"sizeBytes":1472},{"name":"README.md","path":"packages/sql/sqlite-do/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/sql/sqlite-do/README.md","title":"sqlite-do Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":348,"sizeBytes":1505},{"name":"README.md","path":"packages/sql/sqlite-node/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/sql/sqlite-node/README.md","title":"sqlite-node Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":395,"sizeBytes":1684},{"name":"README.md","path":"packages/sql/sqlite-react-native/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/sql/sqlite-react-native/README.md","title":"sqlite-react-native Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":362,"sizeBytes":1565},{"name":"README.md","path":"packages/sql/sqlite-wasm/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/sql/sqlite-wasm/README.md","title":"sqlite-wasm Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":377,"sizeBytes":1590},{"name":"README.md","path":"packages/tools/api-diff/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/tools/api-diff/README.md","title":"api-diff Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":427,"sizeBytes":2008},{"name":"README.md","path":"packages/tools/bundle/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/tools/bundle/README.md","title":"bundle Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1696,"sizeBytes":7475},{"name":"README.md","path":"packages/tools/docgen/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/tools/docgen/README.md","title":"docgen Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1803,"sizeBytes":10431},{"name":"README.md","path":"packages/tools/doctest/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/tools/doctest/README.md","title":"doctest Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1273,"sizeBytes":5483},{"name":"README.md","path":"packages/tools/graphql-generator/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/tools/graphql-generator/README.md","title":"graphql-generator Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":7273,"sizeBytes":31769},{"name":"README.md","path":"packages/tools/npm-promote/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/tools/npm-promote/README.md","title":"npm-promote Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1074,"sizeBytes":4614},{"name":"README.md","path":"packages/tools/openapi-generator/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/tools/openapi-generator/README.md","title":"openapi-generator Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":337,"sizeBytes":1486},{"name":"README.md","path":"packages/vitest/README.md","rawUrl":"https://raw.githubusercontent.com/Effect-TS/effect/HEAD/packages/vitest/README.md","title":"vitest Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":4232,"sizeBytes":18132}],"systemPromptSnippet":"\n\nThis is the Effect TypeScript monorepo. The git base branch is `main`; use `pnpm` from the repository root.\n\n## Layout\n\n- Core library source, runtime tests, and type tests are in `packages/effect/src`, `packages/effect/test`, and\n `packages/effect/typetest`.\n- Other package families include `packages/ai`, `packages/atom`, `packages/platform`, `packages/sql`, and\n `packages/tools`; standalone packages also live directly under `packages`.\n- Package tests and type tests live beside source in `test` and `typetest` directories.\n- AI documentation sources are in `ai-docs/src`.\n- Changesets are in `.changeset`.\n- Migration sources (v3-to-v4) are in `migration/annotations`.\n- Inspect nearby code before editing.\n\n## Validation\n\nUse the narrowest validation that covers the change:\n\n| Change type | Validation |\n| ---------------------------------- | ---------------------------------------------------------------------------------- |\n| Runtime source or test changes | `pnpm lint-fix`, targeted `pnpm test --run `, `pnpm check` |\n| Type-system behavior or type tests | Targeted `pnpm test-types `, plus `pnpm check` when source types changed |\n| JSDoc text/category/link changes | `pnpm jsdocs --check`, `pnpm lint` |\n| JSDoc example changes | `pnpm jsdocs --check`, `pnpm lint`, root `pnpm doctest --run ` |\n| Docs-only changes | `pnpm lint-fix`; no tests unless examples or code changed |\n\nChoose coverage from the contract being changed. Runtime tests cover executed\nbehavior. Tstyche tests cover intended compiler behavior such as inference,\nassignability, rejection, or displayed public types. An ordinary source edit or\nexported declaration is covered by `pnpm check` unless compiler behavior is part\nof the task.\n\nNever run bare `pnpm test` or `pnpm doctest`; both start the full suite in watch mode. Always pass `--run` and the\nspecific files covering the change. CI runs the full suite.\n\nFor an ad hoc runnable probe, create `scratchpad/.ts`, run it with plain `node`, and remove it when finished.\n\nReport any commands that could not be run.\n\n## Generated Files\n\nDo not edit generated output directly.\n\nSome `index.ts` sections marked with `@barrel` are generated. Do not edit those\nsections manually; update their source modules and run `pnpm codegen`.\nHand-maintained `index.ts` files and unmarked sections are not covered by this\nrule.\n\n`LLMS.md` is generated from `ai-docs/src`, and `migration/v3-to-v4.md` is\ngenerated from `migration/annotations`. Update checked-in third-party assets\nthrough their generator or documented import procedure.\n\n\n---\nname: ai-docs\ndescription: AI documentation. Use when editing ai-docs/src or regenerating LLMS.md.\n---\n\nRead `ai-docs/README.md`; it owns source structure, style, examples, generation,\nand changeset policy.\n\n1. Inspect neighboring source examples and the relevant current `LLMS.md`.\n2. Edit sources under `ai-docs/src`, then run `pnpm ai-docgen`.\n3. Review generated output for ordering, missing content, and unrelated changes.\n4. Run applicable root validation.\n\nThe task is complete when sources and generated output agree, every generated\ndifference is explained, TypeScript checks pass when examples or fixtures\nchange, and applicable checks pass or are reported as not runnable.\n\n\n---\nname: bundle-analysis\ndescription: Bundle analysis. Use when measuring current bundle size, comparing stable or selected fixtures, inspecting composition, or cleaning retained comparison state.\n---\n\nRead `packages/tools/bundle/README.md`, then select one workflow:\n\n- **Stable comparison:** `pnpm bundle-compare `. Use `HEAD~1` for the\n latest commit. Read `tmp/bundle-stats.txt` and report non-zero differences.\n- **Selected comparison:** `pnpm bundle-compare-selected --base \n scratchpad/.ts`. Use only user-named or investigation-local fixtures;\n keep temporary fixtures out of the stable corpus.\n- **Composition:** `pnpm bundle-analyze scratchpad/.ts`. Read raw data\n first and report the largest modules, dependency groups, and surprising\n inclusions. Its readable-name output is not an exact size measurement.\n- **Current size:** Build immediately before the direct bundle report so Effect\n packages resolve from current `dist` output.\n- **Cleanup:** Stable comparisons retain `tmp/bundle-base` for reuse unless\n cleanup is requested. Remove selected-comparison state retained with\n `--keep-base` after its final use. Verify cleanup without disturbing unrelated\n worktrees.\n\nThe task is complete when the selected artifact is inspected, requested size or\ncomposition findings are reported, generated paths are named, and comparison\nstate follows the selected workflow's retention policy.\n\n\n# Authoring changesets\n\nUpdate the changeset already introduced by the PR. If there is none, create one\n`.changeset/.md` for the complete PR:\n\n```md\n---\n\"effect\": patch\n\"@effect/affected-package\": patch\n---\n\nFix `Effect.cachedInvalidateWithTTL` caching a stale result when invalidated while the effect is running.\n```\n\nWrite one short sentence, usually under 25 words, that names the changed API\nand states what consumers will notice. That sentence is the whole entry unless\nthe change is breaking or consumers must migrate.\n\nLeave out how the change works: internal modules, algorithms, data structures,\nrefactors, motivation, benchmarks, test coverage, and development history. They\nbelong in the PR description. Cut any sentence a consumer would not act on.\n\n- Bad: \"Rework the `MemoMap` lookup so `Layer.provide` checks identity before\n building, adding a cache keyed by layer reference and tests for shared\n layers.\"\n- Good: \"Fix composed layers being rebuilt for every parent that references\n them.\"\n\nAdd detail only for a break or required migration: what existing code must\nchange and how. Use compact bullets, one break per bullet, when several breaks\nneed migration steps. Several non-breaking fixes or additions still share one\nsentence.\n\nList every directly affected published package. Do not list packages merely\nbecause they share the fixed release group in `.changeset/config.json`.\n\nChoose the bump from current release policy:\n\n- Use `patch` for compatible fixes, `minor` for compatible additions, and\n `major` for breaks.\n- A break confined to APIs tagged `@stability unstable` is `minor`. A break\n confined to APIs tagged `@stability experimental` is `patch`. APIs tagged\n `@stability stable` follow strict semver.\n- Use `major` only when a maintainer has approved a major release.\n- The release queue retargets PRs with `minor` changesets to `v4/next-minor`\n and PRs with `major` changesets to `v4/next-major`. Choose the level the\n change requires, not the branch you want it to land on.\n- Ask when release intent is ambiguous.\n\nUse a `### Breaking changes` section when several breaks need separate\nscanning. Include before/after examples only when they materially clarify\nmigration.\n\nValidate frontmatter against published package names and inspect nearby current\nchangesets for release convention. Do not copy the length of longer entries.\nNever run `changeset-version` or `changeset-publish` as contributor validation.\n\n\n---\nname: changesets\ndescription: Concise PR finalization changesets. Use when implementation scope is complete and focused validation has finished to classify release impact, consolidate the PR's existing changeset, or write its consumer release note.\n---\n\nTreat a changeset as the release note for the complete PR, not as a log of work\nperformed along the way. Finalize it after the current implementation scope and\nfocused validation are complete.\n\n## Workflow\n\n1. Inspect the complete diff from the merge base, including changeset files\n already introduced by the PR, and identify directly affected published\n packages.\n2. Classify impact across source types, runtime behavior, entrypoints, required\n services, lifecycle, and persisted or wire data.\n3. Perform the breaking audit below.\n4. Record a reason no changeset is required, or update the PR's existing\n changeset. Create one only when the PR does not have one. When required, read\n [authoring.md](authoring.md).\n5. Validate package names, frontmatter, bump policy, and a one-sentence\n consumer-facing description, longer only for breaks or required migration.\n\nDo not include unrelated worktree changes.\n\n## PR-level consolidation\n\nThe default is one changeset file per PR. One file can name several packages and\nsummarize several related fixes or additions. Successive prompts, commits, and\nsubtasks within the same PR update that file. If implementation resumes after a\nchangeset was drafted, revise it during the next finalization pass.\n\nUse separate files only when a maintainer requests the split or the PR contains\nindependent changes that need separate release notes.\n\n## Requirement\n\nCreate a changeset for observable runtime behavior changes, including bug\nfixes; exported value or public type changes; entrypoint or export-map changes;\nchanges to required services, errors, ownership, defaults, or lifecycle; and\npersisted, serialization, protocol, or wire-format changes.\n\nTests-only changes, behavior-preserving internal refactors, documentation or\nJSDoc maintenance, and unpublished tooling normally do not need one. When\nunclear, inspect exports and consumer-visible declarations rather than inferring\nfrom source location.\n\n## Breaking Audit\n\nA change is breaking when valid existing consumer code, configuration, or data\nmust change to keep compiling or behaving according to the previous contract.\nAudit every surface:\n\n- **Names and locations:** exports, entrypoints, compatibility exports, and\n module paths.\n- **Call compatibility:** parameters, accepted inputs, overload resolution,\n generic parameters, and defaults.\n- **Result compatibility:** return and error types, output narrowing, members,\n inference, and required services.\n- **Runtime contracts:** defaults, failures, interruption, concurrency,\n ordering, resource lifetime, acquisition, cleanup, and mutation.\n- **Data compatibility:** persisted schemas, encodings, database layouts,\n protocols, and wire formats.\n\nAdditive exports, optional parameters, and behavior-preserving implementations\nare normally non-breaking. A fix restoring the documented contract is normally\nnon-breaking but still needs a changeset when its operational impact is\nconsumer-visible. Verify representative existing calls when overload ordering,\nstructural assignability, or inference makes compatibility uncertain. API diff\noutput is mechanical evidence, not a semantic-version decision.\n\nThe task is complete when every affected contract and published package is\naccounted for and either the no-changeset decision is explicit or the PR has one\nconsolidated, valid changeset by default. Its release note is one sentence of\nconsumer impact, plus migration steps for every break, with no implementation\ndetail.\n\n\n# Privileged Workflows\n\n- Privileged jobs must not run untrusted repository code with secrets or write\n credentials.\n- Validate cross-run data for expected source, identity, type, shape, and\n bounded size before using it in commands, outputs, APIs, or comments.\n- Require the intended approval boundary before fork-originated work reaches\n privileged execution.\n- Preserve publication and other irreversible operations until completion;\n cancel only replaceable checks and previews.\n- Make checkout revision and credential persistence explicit. Account for\n every write permission and credential.\n\nSearch current workflows by event, job purpose, action, and permission to find\nthe nearest precedent for fork approval gates, publication, non-cancelable\nconcurrency, and validation of cross-run artifacts before privileged use.\n\nConsult current GitHub documentation for event, token, secret, permission,\ncheckout, artifact, reusable-workflow, and environment semantics. Start with\nthe workflow events, workflow syntax, and secure-use references.\n\n\n---\nname: ci-maintenance\ndescription: GitHub Actions maintenance. Use when authoring or reviewing workflows or composite actions, especially event, permission, action-reference, artifact, setup, or concurrency changes.\n---\n\nAudit the trust boundary before editing. This skill owns Actions event\nsemantics, workflow security, permissions, action pinning, setup reuse,\nuntrusted inputs, timeouts, concurrency, and artifact trust boundaries.\n\n## Workflow\n\n1. Decide whether this is a review or an implementation. Reviews produce\n evidence-backed findings without editing; implementations continue through\n the smallest boundary-preserving change.\n2. Inspect every affected workflow, composite action, and caller. List all\n affected jobs and actions before proceeding.\n3. For each job, record the trigger, actor/fork status, workflow revision,\n checked-out revision, permissions, credentials, and every external input and\n consumer. Include artifacts, caches, outputs, PR fields, refs, dispatch\n inputs, generated files, and called actions.\n4. Consult current GitHub documentation for every platform-sensitive decision.\n Repository examples establish local convention, not platform semantics.\n5. Apply every applicable rule:\n - Default workflow permissions to empty and grant minimal job permissions.\n - Reuse the repository's shared setup action unless the environment must differ.\n - Give executable jobs intentional matrices and realistic timeouts.\n - Pin external actions and reusable workflows to full commit SHAs with\n readable release comments; verify each SHA belongs to that upstream release.\n - Analyze event choice, checkout revision, and credential persistence\n together.\n - Pass untrusted expressions through environment variables; validate and\n quote them before use.\n - Derive concurrency from interruption safety.\n6. For forks, privileged credentials, publication, or cross-run data, read\n [privileged-workflows.md](privileged-workflows.md).\n7. Run the narrowest syntax and repository checks, inspect the complete diff,\n and identify behavior testable only on GitHub-hosted runners.\n\nFor local patterns, inspect the current shared setup action and the nearest\nworkflow with the same trust boundary. Use ordinary check workflows for routine\nprecedent and privileged publication workflows only for equivalent trust\nboundaries.\n\nThe task is complete when every affected job and caller has a recorded trust\nboundary, every applicable rule has evidence or a compensating control, local\nchecks pass, and GitHub-only verification is identified. Reviews report every\nfailure with evidence; implementations resolve every failure and contain only\nintended behavior.\n\n\n# Coordinated Upgrades\n\nSelect every applicable row and derive commands from the cited current source.\n\n| Change | Synchronize | Validation source |\n| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |\n| Shared dependency or test/build tool | Owning manifests, peer/development pairs, configs, and generated artifacts owned by that tool | Root/package scripts and affected Vitest projects |\n| pnpm | Root `packageManager`, workspace settings, setup/cache assumptions, workflows, and lockfile format | Current install, lint, check, build, and focused test scripts |\n| Node, Deno, or Bun | Setup inputs, workflow jobs, engines, runtime metadata, compatibility docs, and runtime config | Current runtime workflow jobs and test configuration |\n| TypeScript support or compiler | Compiler/tooling dependencies, `test-types` target, CI target, tool peer ranges, compatibility docs, and typetests | Targeted typetests; typeperf protocol for measured paths |\n| Native package or install policy | Owning manifests and `pnpm-workspace.yaml#allowBuilds` | Fresh install plus focused package build and tests |\n| Patched dependency | Manifest/range, `patchedDependencies`, patch file, and lockfile patch hash | Fresh install and the behavior that required the patch |\n| Container image or Testcontainers package | Workflow pre-pulls, image call sites, manifests, and integration project names | Current integration workflow and Vitest configuration |\n\nFor a patched dependency, test the new release without the patch when feasible.\nRemove obsolete registration and patch files. Otherwise refresh the patch using\nthe current pnpm workflow and verify both that it applies and that the original\npatched behavior still requires it.\n\nWhen an upgraded component lies on a measured path, use the repository's\nruntimeperf or typeperf comparison protocol rather than inventing a benchmark.\n\n\n# Manifest Roles\n\nInspect the nearest package with the same integration shape, then justify each\nadded or moved entry:\n\n| Role | Use when | Completion check |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |\n| `dependencies` | Published runtime code requires its own installed copy. | A packed consumer receives it without adding an undeclared package. |\n| `peerDependencies` | Consumers provide a compatible shared package or the public contract integrates with their copy. | The range states supported consumer versions; add a development entry when local build or tests need an installed copy. |\n| `devDependencies` | Only repository build, test, type, benchmark, or code-generation work needs it. | Published runtime code and declarations do not require consumers to install it. |\n| `optionalDependencies` | A runtime feature handles absence and installation failure must not block the base package. | Focused tests cover present and absent behavior. |\n| Optional peer via `peerDependenciesMeta` | A consumer-provided integration is genuinely optional. | The peer remains in `peerDependencies`, and code requires it only when selected. |\n\nRole selection is complete when every changed entry has one justified role and\npeer compatibility remains independent from repository validation versions.\n\n\n---\nname: dependency-maintenance\ndescription: Dependency maintenance. Use when adding, moving, or upgrading dependencies, changing pnpm or JavaScript runtimes, updating TypeScript or build/test tools, or changing native-build policy, patches, or test images.\n---\n\nTreat an upgrade as a synchronization task, not a lockfile refresh. Derive\nversions, commands, and compatibility points from the current repository.\n\n## Discover\n\n1. Read affected manifests and scripts, `pnpm-workspace.yaml`, setup actions,\n workflows, test configuration, and compatibility documentation.\n2. Search for the dependency and every current version, range, runtime input,\n image, engine constraint, patch, and compatibility claim.\n3. Record each match as a development version, tested version, peer range,\n engine minimum, advertised minimum, or intentionally different constraint.\n4. When adding or moving a manifest entry, read\n [manifest-roles.md](manifest-roles.md) before selecting its role.\n5. Select the package-local or coordinated branch and its validation matrix.\n\nDiscovery is complete when every match and affected validation surface is\naccounted for.\n\n## Package-local branch\n\nUse this branch only for one dependency in one workspace package when runtime,\ncompiler, package-manager, image, patch, native-build, and shared-tooling policy\nare unchanged.\n\nUpdate only the owning manifest and keep peer compatibility independent from\nthe development version tested here. If any coordinated surface appears,\nswitch branches.\n\nThis branch is complete when the manifest and lockfile agree, focused checks\npass, and every search result is intentionally unchanged or package-local.\n\n## Coordinated branch\n\nRead [coordinated-upgrades.md](coordinated-upgrades.md), select every applicable\nrow, and update all listed synchronization points before installing. Apply root\nworkflow and generated-file requirements before editing those surfaces, then\nreturn here to finish matrix and lockfile review.\n\n## Install and finish\n\nRun root `pnpm install` after all selected edits. Inspect warnings and the\nsemantic lockfile diff for specifiers, resolutions, duplicate transitives, peer\nchanges, integrity, patch hashes, lifecycle scripts, and `allowBuilds` effects.\nA successful install alone does not complete this review.\n\nRun the narrowest correctness and performance checks that cover every selected\nmatrix row.\nApply the root changeset routing after implementation and focused validation.\n\nThe task is complete when repeated repository searches find no unclassified\nsynchronization point, manifest roles and compatibility ranges are intentional,\nthe lockfile has no unexplained churn, and every selected check passes or is\nreported as not runnable.\n\n\n---\nname: effect-development\ndescription: Effect development guidance. Use when implementing or reviewing code that composes Effect APIs or patterns, or that adds or changes API signatures.\n---\n\nUse the repository's AI documentation as targeted reference, not ambient\ncontext:\n\n1. Identify the Effect APIs and concepts involved in the change.\n2. Search `LLMS.md` and `ai-docs/src` for those names and concepts, then read\n the matching sections and examples.\n3. Apply the relevant guidance and inspect nearby source and tests for any\n repository-internal conventions not covered by the documentation.\n\nThe task is ready for implementation when every material Effect API or pattern\nhas matching local guidance, or the search has established that none exists.\n\n## API conventions\n\nWrite option types inline in the signature by default. Mark fields `readonly`\nand add `| undefined` to optional fields:\n\n```ts\nexport const make = (options: {\n readonly capacity: number\n readonly strategy?: \"dropping\" | \"sliding\" | undefined\n}): Effect.Effect => ...\n```\n\nDeclare a named options type only in these cases:\n\n- A substantial set of options is shared across several APIs, so a named type\n keeps them in sync.\n- The options type needs complex conditional logic, such as conditional or\n mapped types driven by type parameters.\n\nA long option list for a single API is not on its own a reason to extract a\nnamed type.\n\n\n# Categories\n\nRoot declarations require one non-empty `@category`. Reuse nearby categories;\nprefer lowercase plurals and gerunds while preserving canonical domain casing.\n\nCommon categories include:\n\n- Shapes: `constructors`, `destructors`, `models`, `schemas`, `guards`,\n `predicates`, `getters`, `accessors`, `instances`, `constants`, `protocols`,\n `prototypes`, `re-exports`, `unsafe`, `testing`.\n- Effect: `services`, `tags`, `layers`, `context`, `resource management`,\n `running`, `errors`, `error handling`.\n- Operations: `combinators`, `filtering`, `mapping`, `sequencing`, `zipping`,\n `combining`, `merging`, `converting`, `transforming`, `folding`, `splitting`,\n `repetition`.\n- Shared: `utility types`, `encoding`, `decoding`, `serialization`, `tracing`,\n `metrics`, `logging`, `annotations`, `references`, `symbols`, `type IDs`,\n `configuration`, `math`, `comparisons`, `ordering`.\n\nKeep these boundaries: services are contracts, tags identify services, and\nlayers provide them; getters retrieve values while accessors read context;\nerrors model failures while error handling recovers or maps them; models are\ndomain data while utility types are type-level contracts; guards narrow while\npredicates return booleans.\n\n\n# Tags, Modules, And Links\n\n## Declaration Shape\n\nUse a multiline JSDoc block for a public declaration:\n\n````ts\n/**\n * Short description as one paragraph.\n *\n * **When to use**\n *\n * Optional practical usage guidance.\n *\n * **Details**\n *\n * Optional details for complex behavior.\n *\n * **Gotchas**\n *\n * Optional concrete caveats.\n *\n * **Example** (Parsing JSON)\n *\n * ```ts import.meta.vitest\n * operation() // => expected\n * ```\n *\n * @category constructors\n * @since 1.0.0\n */\n````\n\nWrite practical English about the public concept, not its implementation. Start\nfunctions and methods with a present-tense action such as `Creates`, `Returns`,\nor `Converts`; match nearby noun families for values, such as `Schema for`,\n`Layer that`, or `Service that`.\n\nOptional non-empty sections appear once in this order: `**When to use**`,\n`**Details**`, `**Gotchas**`. Separate descriptions, sections, examples, and\ntags with exactly one blank line. Use prose for one fact and bullets for\nparallel facts. Do not add other headings.\n\n`**When to use**` states a positive use case distinct from the description and\nbegins with `Use to`, `Use when`, `Use as`, or `Use with`. Put sibling\ncomparisons in `@see`. Reserve `**Gotchas**` for concrete preconditions, edge\ncases, surprising behavior, and important failure modes.\n\n## Tags\n\nDeclaration tags appear in this order:\n\n1. `@deprecated`\n2. `@default`\n3. `@see`\n4. `@stability`\n5. `@category`\n6. `@since`\n\n- Roots require stable-semver `@since` and no `@default`; category requirements\n live in [categories.md](categories.md).\n- Namespaces and their declarations require stable-semver `@since`, permit\n `@category`, and reject `@default`.\n- Member JSDoc is optional; when present it permits stable-semver `@since` and\n non-empty `@default`, rejects `@category`, and follows the prose contract.\n- Any declaration permits one non-empty `@deprecated` and repeated non-empty\n `@see` tags.\n- Roots, export specifiers, and root namespaces require `@stability stable`,\n `@stability unstable`, or `@stability experimental`. Use `unstable` when an\n API may receive breaking changes in minor releases, `experimental` when it may\n receive breaking changes across patch versions, and `stable` otherwise.\n- Tag any API that exposes a third-party dependency `@stability unstable`: an\n accessor to the underlying client or instance, options typed as the\n dependency's options, constructors that accept its instances, re-exports of\n it, and signatures that mention its types. Tag the whole module when it exists\n to wrap the dependency; otherwise tag only the exposing declarations or\n members. Runtime built-ins (Node, Bun, Deno, DOM) and framework types inherent\n to a binding (React, Solid, Vue) are exempt.\n\nUse canonical `**Example**` sections rather than `@example` tags or loose code\nfences.\n\n## Modules And Links\n\nWhen present, the first top-level JSDoc is the module block unless TypeScript\nattaches it to a non-import first declaration. An `@internal` module is omitted.\nModule prose does not use the declaration template. Its tags are optional\nnon-empty `@deprecated`, repeated non-empty `@see`, required `@stability`, then\nrequired stable-semver `@since`. Its examples and links follow the declaration\ncontracts.\n\nInline `{@link Symbol}` targets must resolve to TypeScript symbols; use normal\nMarkdown links for URLs. Prefer code formatting when navigation does not help a\nreader understand or choose the API.\n\nUse `@see` only for a verified related public API: a close alternative,\ninverse, complement, level variant, or closely returned, consumed, or\nconfigured type. Explain non-obvious relationships. Exclude implementation\ndependencies, broad concepts, example-only helpers, private APIs, and merely\nlexical matches.\n\n\n# Examples\n\nExamples are optional. Keep or add one only for behavior not evident from the\nsignature, meaningful composition, or useful inference or narrowing. Replace\nor remove examples that are trivial, misleading, contrived, or\nscaffolding-heavy.\n\nUse `**Example** (Unique use-case title)`, optional prose, and exactly one\nnon-empty `ts` fence. Titles must remain unique after trimming and lowercasing.\n\nRead `packages/tools/doctest/README.md` for runnable-fence and inline-assertion\nsyntax. Additionally:\n\n- Use public imports and arrange nontrivial examples as setup, operation, then\n semantic observation.\n- The transform does not run Effects or await promises automatically. Prefer\n awaited `Effect.runPromise`; use `Effect.runSync` only when synchronous\n execution is the documented contract.\n- Keep type-level examples marked without tautological runtime assertions.\n- Leave examples that register tests and intentionally non-executable examples\n as plain `ts` fences.\n- Use `Ref`, `Deferred`, or `Queue` rather than mutable probes for concurrency,\n interruption, or races.\n\nIf example research suggests an implementation or type bug, report it instead\nof changing runtime code during a documentation-only pass.\n\n\n---\nname: jsdocs\ndescription: Public API JSDoc. Use when authoring or reviewing Effect API documentation, refining a module's documentation, or fixing documentation related diagnostics.\n---\n\n## Workflow\n\n1. Inspect the declaration, implementation, nearby JSDoc, tests, and call sites.\n2. Select every applicable branch and load its reference before editing:\n - tags, modules, or links: [declarations.md](declarations.md);\n - categories: [categories.md](categories.md);\n - examples: [examples.md](examples.md).\n3. Make a focused API fix or module refinement. Preserve verified facts and\n valuable examples rather than rewriting mechanically.\n4. For module refinement or APIs with close alternatives, audit `@see` links\n and inspect implementation and tests for concrete `**Gotchas**`.\n5. Run `pnpm jsdocs --check` and every applicable root validation command.\n\n`@internal` declarations and default exports are outside public JSDoc\nauthoring. Checked files do not support exported enums or empty export\ndeclarations.\n\nPublic declarations use a multiline block with one self-contained practical\ndescription paragraph. Start functions and methods with a present-tense action;\nmatch nearby noun-family phrasing for values. Optional non-empty sections appear\nonce in this order: `**When to use**`, `**Details**`, `**Gotchas**`. Separate\ndescriptions, sections, examples, and tags with one blank line. `**When to\nuse**` states a positive use case distinct from the description; reserve\n`**Gotchas**` for concrete caveats and failure modes.\n\nThe task is complete when every changed public declaration satisfies each\napplicable reference, the checker passes, runnable examples pass their targeted\ndoctest, and all other applicable root checks pass or are reported as not run.\n\n\n# Migration Annotations\n\nAdd or update one YAML file per v3 module under `migration/annotations/`. Use\nstable API IDs without trailing `#type` or `#value` facets:\n\n```yaml\neffect/Effect#async:\n replacement: Effect.callback\n note: Use the callback constructor.\n example: Effect.callback((resume) => resume(Effect.void))\n```\n\nEvery annotation requires `replacement` and `note`; `example` is optional. Use\n`replacement: none` when there is no direct replacement and explain the\nsupported migration strategy instead of inventing an equivalent API.\n\n\n# Generated Migration Reference\n\n`migration/v3-to-v4.md` is generated. Check annotations and regenerate using\nexplicit committed refs containing the change:\n\n```sh\npnpm api-diff --base-ref origin/v3 --head-ref HEAD --check\npnpm api-diff --base-ref origin/v3 --head-ref HEAD --write-doc migration/v3-to-v4.md\n```\n\nThe API diff reads refs through detached worktrees. If the API change is\nuncommitted, `HEAD` does not contain it. Update known annotation IDs, defer the\ncheck and regeneration, and report the limitation. Do not create a temporary\ncommit solely to run the tool.\n\n\n---\nname: migration-guidance\ndescription: Use when changing how a v3 public API maps to v4, editing migration annotations, or regenerating migration/v3-to-v4.md.\n---\n\nUpdate guidance when a v3 public module or API is renamed, moved, removed,\nreplaced, or gains a materially different v4 contract. A v4-only API without a\nv3 counterpart does not automatically need an annotation.\n\n1. Account for every affected v3 symbol.\n2. Read [annotations.md](annotations.md) before adding or changing annotation\n YAML. Verify every suggested replacement against implementation and tests.\n3. When checking or regenerating the reference, or when the API change exists in\n a committed ref, read [generation.md](generation.md). Otherwise report that\n generation is deferred.\n4. When output was generated, inspect it for unrelated movement and stale refs.\n\nThe task is complete when every affected v3 symbol is accounted for, annotation\nreplacements are verified, checks and generation succeed when the change is in\na committed ref, and every generated difference is explained. Report deferred\nchecks explicitly for uncommitted API changes.\n\n\n# Package Dependencies\n\nInspect the closest package with the same publication and integration shape.\nClassify every manifest entry by the role it serves:\n\n| Role | Use when |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------ |\n| `dependencies` | Published runtime code requires the package to receive its own installed copy. |\n| `peerDependencies` | Consumers provide a compatible shared package or the public contract integrates with their copy. |\n| `devDependencies` | Only repository build, test, type test, benchmark, or code generation needs the package. |\n| `optionalDependencies` | A runtime feature handles absence and installation failure must not block the base package. |\n| Optional peer via `peerDependenciesMeta` | A consumer-provided integration is genuinely optional. Keep its version in `peerDependencies`. |\n\nUse `workspace:^` for workspace packages unless neighboring packages establish a\ndifferent policy. When local build or tests need an installed peer, add the peer\nto `devDependencies` at the repository's tested version while keeping the peer\nrange based on supported consumer versions.\n\nDerive external versions from current consumers with the same integration\nshape. Add only direct requirements; do not copy a neighboring manifest entry\nthat the new package's runtime, declarations, build, or tests do not use.\n\nAfter editing manifests, run root `pnpm install`. Inspect warnings and the\npackage's `pnpm-lock.yaml` importer for intended specifiers and resolutions. If\na dependency has an install or native build, classify it under\n`pnpm-workspace.yaml#allowBuilds` using current repository policy.\n\nThis branch is complete when every entry has one justified role, workspace and\npeer ranges follow repository policy, the lockfile importer agrees with the\nmanifest, and install/build policy is explicit.\n\n\n# Publishing A Package\n\nCompare the package manifest with a neighboring published package in the same\nfamily.\n\n- Keep development `exports` and `publishConfig.exports` aligned by key.\n Source targets become their intended built targets; blocked internal and\n legacy paths remain blocked.\n- Check current AI documentation copy tooling and the package `files` list for\n every file required in the published payload.\n- Ensure each public source entrypoint has exactly one published counterpart\n and no internal entrypoint becomes exposed.\n\nRun the current root build so publication payload generation executes. Create a\ntarball in a temporary destination without publishing, inspect its file list,\nand inspect the packed `package.json` whenever manifest transformation matters.\n\nThis branch is complete when package and root checks pass and the packed\nsurface contains exactly the intended files, exports, and metadata.\n\n\n# Package Registration\n\nUse current configuration and the closest package in the same family as the\nsources of truth. A package-local build does not prove repository registration.\nClassify every row as applicable or not applicable.\n\n## Workspace And TypeScript\n\n| Surface | Check |\n| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `pnpm-workspace.yaml` | Its globs cover the package path and exact-name pnpm selection discovers it. |\n| `pnpm-lock.yaml` | The current importer, name, and dependencies exist; renamed or moved importers are gone. |\n| `tsconfig.packages.json` | Packages intended to participate in the root TypeScript project-reference graph are referenced. Follow neighboring package policy; buildable private tools are not automatically included. |\n| `tsconfig.tests.json` | Broad test globs cover the path. Add source aliases only when tests require workspace source routing or would otherwise create a dependency cycle. Preserve intentional platform exclusions. |\n\n## Tests And Documentation\n\n| Surface | Check |\n| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `vitest.config.ts` | A package with runtime tests has the intended project, environment, setup, and inclusion rules. |\n| `tstyche.json` | Type-test discovery covers the package depth; current globs cover one- and two-level package layouts. |\n| `vitest.docs.ts` | Doctest source discovery covers packages with runnable JSDoc examples; current globs cover one- and two-level package layouts. |\n| `jsdocs.config.json` | Public source is included in JSDoc checks and exclusions by package family remain intentional. |\n| `deno.json` | Deno checks cover the package family, or its exclusion is intentional. |\n\n## Release And Discovery\n\n| Surface | Check |\n| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `.changeset/config.json` | Published fixed-group membership uses the current name; private tooling is not added solely because it builds. |\n| `README.md` | Public catalog entries have the current name, path, description, and documentation link. |\n| AI documentation copy tooling and package `files` | Published payloads include required generated documentation. Continue with [publishing.md](publishing.md) for the full packed-surface audit. |\n| Snapshot publishing workflows | Snapshot publishing selects the package path. Existing globs may already cover it; apply root workflow requirements before editing. |\n| Runtime-specific CI workflows | Runtime-specific packages participate in applicable runtime jobs; apply root workflow requirements before editing. |\n\n## Paths And Consumers\n\nAudit explicit workspace package names in root tooling manifests. Search scripts\nfor the package family, old name, and old path to find path-sensitive clean,\ncodemod, circularity, copy, and related behavior. Explain every remaining old\nreference after a rename or move.\n\n\n---\nname: package-development\ndescription: Package registration. Use when adding a workspace package, making a private package publishable, renaming a package, or moving its workspace path.\n---\n\nTreat package work as a registration change, not a directory copy.\n\n## Workflow\n\n1. Inspect the closest package in the same family. Classify publication status,\n runtime, test environment, platform support, barrels, and dependency shape.\n Justify each proposed file by precedent or an explicit repository need.\n Continue when every proposed file is justified.\n2. Create or move only required source, test, TypeScript, and manifest files.\n When manifest dependencies change, read [dependencies.md](dependencies.md)\n and classify every entry by role.\n Continue when pnpm discovers the intended name and manifests reference no\n absent file.\n3. Read [registration.md](registration.md). Classify every registration surface\n as applicable or not applicable and update every applicable surface.\n Continue when every surface is classified and old references are explained.\n4. For a published package, read [publishing.md](publishing.md) and verify its\n development and packed surfaces.\n5. Run codegen when the package owns generated barrels, then inspect generated\n sections rather than editing them manually.\n Continue when generated sections match source modules without manual edits.\n6. Run focused package tests and scripts plus applicable root checks. Include\n public API type tests when applicable. For published packages, build and dry\n pack the package as described in [publishing.md](publishing.md).\n Continue when focused and root checks pass and the packed surface is intended.\n7. Apply root changeset, generated-file, documentation, and workflow routing.\n\nThe task is complete when package discovery, registration, generated output,\nvalidation, packed output, and changeset routing are all verified or reported\nas not applicable.\n\n\n# Runtime Performance\n\nFor authoritative base/head comparisons or fixture work, read\n`packages/effect/runtimeperf/README.md`. Use `pnpm runtimeperf-compare\n` for local worktree comparisons and explicit `--base`/`--head`\nonly for committed refs. Report the resolved comparison head and measurement\nconfiguration.\n\nFor exploratory scripts under `benchmark/`, match nearby Tinybench scripts,\nkeep setup outside the measured callback unless setup is the operation, warm\nreusable state, close resources, and print the table. Label results exploratory\nunless the task defines a repeatable comparison protocol.\n\nFocused runtimeperf work is complete when fixture validation and the selected\nrun succeed. Comparison work additionally requires every configured round to\nsucceed, the paired statistical classification to support the conclusion, and\nresolved refs and settings to be reported. Harness changes require its focused\nchecks. Tinybench work is complete when resources close, the table is reported,\nand claims remain exploratory unless a repeatable protocol was run.\n\n\n---\nname: performance-analysis\ndescription: Performance analysis. Use for runtime throughput or latency benchmarks, TypeScript compiler cost, performance regressions, comparison harnesses, or thresholds.\n---\n\nValidate correctness with focused tests before measuring. Compare the same\nfocused operation and environment across revisions; a single unpaired run is\nnot evidence of improvement.\n\nSelect every applicable branch:\n\n- **Runtime performance:** Read [runtime.md](runtime.md).\n- **Type performance:** Read [types.md](types.md).\n\nThe task is complete when every selected branch meets its measurement and\nreporting criteria and applicable root checks pass or are reported as not\nrunnable.\n\n\n# Type Performance\n\nRead `packages/effect/typeperf/README.md` before adding fixtures, changing the\nharness, updating thresholds, or running cross-ref comparisons. Isolate one\nrealistic public type path and compare the same fixture and compiler environment\nacross revisions. Derive supported suites and comparison commands from the\ncurrent harness documentation and CLI.\n\nBefore changing a threshold, record its previous value and measured result,\nexplain the expected delta, update it, and run a clean focused verification.\nKeep ordinary threshold fixtures separate from cross-ref fixtures.\n\nThis branch is complete when the focused measurement is repeatable, threshold\nverification is clean when applicable, and reported comparisons include\nresolved refs, compiler version, and an explanation of the observed delta.\nFixture or harness changes also require the focused validation and formatting\nchecks documented in the README.\n\n\n---\nname: pull-requests\ndescription: Pull request finalization. Use when a change works and is about to be opened as a pull request, or when updating or continuing an existing one.\n---\n\nA pull request is ready when its tests, implementation, comments, and changeset\nare each the simplest that cover the intended behavior. Draft PRs can be used\nearlier; finishing means making the PR ready for review.\n\n## Workflow\n\nRun each step in a fresh-context subagent when available; otherwise run it\nyourself. Pass along the task context and prior results so each step can check its gate.\n\n1. Keep tests focused. Read [test-development](../test-development/SKILL.md) for\n test placement and type. Cover each intended behavior once, in the existing\n test file for the module.\n For changes needing no tests, record why.\n Continue when removing any remaining case would leave intended behavior\n uncovered, or no tests are needed.\n2. Simplify the implementation. With the tests passing, look for a simpler or\n more idiomatic version: reuse helpers and patterns from nearby source and\n [effect-development](../effect-development/SKILL.md), and remove debugging\n code, scaffolding, and changes unrelated to the task.\n Continue when applicable targeted tests pass and every hunk in the diff\n from the merge base is required by the task.\n3. Review the full diff from the merge base as a maintainer would: correctness,\n failure and interruption paths, resource cleanup, naming and API\n consistency with neighboring modules, and documentation. Fix findings and\n review again.\n Continue when a review pass produces no findings.\n4. Clean up. Remove comments that restate code or narrate the change; keep the\n rest short and about why. Finalize the changeset with\n [changesets](../changesets/SKILL.md).\n Continue when comments explain only what code cannot, and the changeset\n describes the final consumer impact or the no-changeset reason is recorded.\n5. Run the validation in the [AGENTS.md validation table](../../AGENTS.md#validation)\n for each change type in the diff. Fix failures caused by the change; if\n fixes alter the diff, repeat the affected passes.\n Continue when applicable checks pass or commands that cannot run and their\n blockers are recorded.\n6. Open or update the pull request. Title: a short imperative summary.\n Description: the problem addressed, notable decisions, and `Closes #` for each\n GitHub issue resolved. Do not narrate the diff. Mark the PR ready for review.\n Continue when the final changes are pushed, the description matches the\n final diff, and the PR is ready for review.\n\nThe task is complete when each step's gate holds, validation has passed or\nbeen reported as not runnable with reasons, and the pull request is ready for\nreview with a description matching the final diff.\n\n\n# Displayed Types\n\nDeliberately produce an assignment error and match a distinctive substring with\nTstyche's checked `@ts-expect-error` message:\n\n```ts\nit(\"simplifies the displayed type\", () => {\n const value = null as unknown as PublicType\n\n // @ts-expect-error Type '{ readonly value: string; }'\n const displayed: never = value\n\n void displayed\n})\n```\n\nKeep the expected substring as small as possible while distinguishing the\npublic type from the leaked implementation type. Before accepting the test,\ntemporarily restore the broken type and confirm the diagnostic-message match\nfails.\n\n\n# Runtime Tests\n\n- Use `it.effect` for Effect-returning tests and regular `it` for pure\n synchronous tests.\n- `it.effect` and `it.live` provide and close a `Scope`; return scoped effects\n directly instead of wrapping the body in `Effect.scoped`.\n- Use `assert` from `@effect/vitest`, not Vitest's `expect`.\n- Use `TestClock` for time-dependent behavior.\n- Keep `Effect.runSync` out of unit tests; runnable documentation follows the\n root JSDoc validation rules.\n\nInspect nearby tests for imports and structure. This branch is complete when\nevery changed behavior has focused coverage and its targeted test passes.\n\n\n---\nname: test-development\ndescription: Test development. Use when adding or changing Vitest or Tstyche coverage. Choose Tstyche only for intended compiler behavior such as inference, assignability, rejection, or displayed public types.\n---\n\nChoose branches from the task's acceptance criteria before editing:\n\n- **Runtime behavior:** The intended result is observable when code executes.\n Read [runtime.md](runtime.md).\n- **Compiler behavior:** The intended result is TypeScript accepting, rejecting,\n or inferring a consumer expression in a particular way. Read\n [types.md](types.md).\n\nAn exported signature alone is validated by `pnpm check`; it enters the compiler\nbranch only when its inference, assignability, rejection, overload selection, or\ndisplayed type is part of the task. Some changes require both branches because\nthey independently change runtime and compiler behavior.\n\nThe task is complete when each intended behavior in scope has the relevant\nfocused coverage, targeted tests pass, and applicable root checks pass or are\nreported as not runnable.\n\n\n# Type tests\n\nEnter this branch when the acceptance criterion is compiler behavior: inference,\nassignability, rejection, overload selection, generic constraints, or a displayed\npublic type. Use `pnpm check` for ordinary declaration edits whose compiler\nbehavior is not independently under test. A runtime bug in generic code needs a\nruntime regression test, not a type test, when its type contract is unchanged.\n\nInspect nearby `.tst.ts` files and use their imports and assertion style. Use\nordinary Tstyche assertions such as `toBe` for structural equality and choose a\nspecific assertion for the inference or assignability contract under test.\n\nStructural equality does not verify editor quick-info rendering. For internal\naliases, unsimplified intersections, or other displayed-type regressions, read\n[displayed-types.md](displayed-types.md).\n\nRun targeted `pnpm test-types `; the root command covers every\nconfigured TypeScript version. For a regression fix, confirm the assertion\nfails against the pre-fix type. This branch is complete when the assertion\nproves the intended contract and the target passes.\n\n\n"}