Release/2.0.0

.claude/skills/weaving-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: weaving-review
-description: Review a change to CodoMetis.TypeKit for code that compiles and silently does less than it appears to — a type that is not generated, an analyzer that stops firing, a generated entry point that bypasses Create, an Option/Result that leaks its content or reads as success, a satellite that falls back to default behaviour. Use when changing Option/Result, an aspect, the transitive fabric, AspectOrder, the analyzer, the EF converter/convention/translators, the OpenAPI transformers, or package references — and before cutting a release.
+description: Review a change to CodoMetis.TypeKit for code that compiles and silently does less than it appears to — a type that is not generated, an analyzer that stops firing, a generated entry point that bypasses Create, an Option/Result that leaks its content or reads as success, a satellite that falls back to default behaviour. Use when changing Option/Result, an aspect, the transitive fabric, AspectOrder, the analyzer, the EF converter/convention/translators, the OpenAPI transformers, closed sets, `Patch<T>`, the fault responses, the Serilog or Testing package, or package references — and before cutting a release.
 ---
 
 # Weaving review
@@ -23,6 +23,8 @@ does, and what they expected.
   nested type, a generic type, and a type in a project that reaches the package only
   transitively.
 - A type the fabric skips compiles cleanly. Is there a test or a diagnostic that would notice?
+  An **abstract** type with a marker, and a name that is a C# keyword (`namespace Shop.@event`, a
+  member `@class`), were both measured once as silent or as a Metalama crash rather than a CMTK error.
 - A project that references only `CodoMetis.TypeKit` gets no aspects at all. Does CMTK0002
   ("marker without `.Generators`") still fire there?
 - Is `AspectOrder` still complete? A new aspect class missing from it runs in an unspecified
@@ -69,15 +71,26 @@ likely.
   match the snapshot? A translator that stops matching makes EF throw at best, or evaluate on the
   client at worst.
 - Is the comparer consistent with the type's equality?
+- Does a translator check that the column's converter is **TypeKit's**? A user's own
+  `HasConversion` stores through their converter; a `.Value` translated as if TypeKit's were there
+  queries the wrong representation and answers wrong rows.
+- Does a hand-written **`CompareTo`** reach the query? EF translates a comparison or an ordering to
+  the column's order, not the seam's.
+- Is an integer key generated on add **wherever EF generates the wrapped type's**: every integer
+  type EF generates, the root of a hierarchy (TPH, TPT), on every provider the tests run?
 
 ## 5. OpenAPI
 
 - For a value object used only as a property, as a list element, as a dictionary value and as a
   route/query parameter: what schema does the document actually contain? Look at the emitted
   JSON, not at whether the transformer ran. A schema transformer that registered, compiled and
-  never ran for a property-only type has been measured before (plan §7).
+  never ran for a property-only type has been measured before ([OpenAPI](../../../design/openapi.md)).
 - Is the schema the **underlying type's** schema (format included: `uuid`, `date`, `int64`), and
   does it match what the JSON converter writes?
+- Can two types get **one component name**? A name built from a nesting chain (`Order.Status` →
+  `OrderStatus`) meets a top-level type of that name, and one component then describes both.
+- Is every name a client matches on (a fault's qualified name, a component) unique for nested types
+  of one simple name?
 
 ## 6. Option and Result
 
@@ -88,7 +101,7 @@ likely.
   a branch?
 - Does every new combinator (`Map`, `Bind`, `Tap`, async variants) preserve the error or None
   unchanged, and avoid invoking the callback on it?
-- Is the change inside the non-goals in plan §9 (no Either, no effects, no LanguageExt drift)?
+- Is the change inside the non-goals in [Option and Result](../../../design/option-result.md) (no Either, no effects, no LanguageExt drift)?
 
 ## 7. Packaging
 
@@ -99,3 +112,26 @@ likely.
 - Do the EF and ASP.NET satellites depend on `CodoMetis.TypeKit` only, never on `.Generators`?
 - Does the consumer smoke test build a project that references the packages **transitively**,
   the case the fabric spike proved and a refactor could lose?
+
+## 8. Closed sets, `Patch<T>`, faults, and the run-time satellites
+
+- **Closed sets:** does anything generated that the set's own static field initializers can read
+  (`All`, `Parse`, `Name`) answer from a half-built set? Is every member found across partial files,
+  in declaration order? Does every entry point (JSON, EF, binding, the type converter, `IParsable`)
+  read ordinally, with ignoring case an overload the caller asks for?
+- **`Patch<T>`:** does `default` still read as Absent, null as Null, and does a value object inside a
+  patch still go through its own converter? Is anything new registered so that Native AOT finds it
+  without `MakeGenericType`?
+- **Faults:** can a `Fault<TFault>` be compared with a bare reason by any path (an operator, a
+  conversion, `Equals`, a collection's `Contains`, a test assertion), where a fault with a detail
+  then never equals it?
+- **Serilog:** does a value object or a closed set log as what it prints, and does the policy honour
+  the logger's own limits (`ToMaximumStringLength`)?
+- **Testing:** does an assertion's message print content, and does it survive every type name
+  (nested, generic, nested in a generic)?
+- **Analyzer Errors freeze** ([decision 34](../../../design/adr/0034-errors-fixed-within-major-version-warnings.md)):
+  an Error that misses a form misses it for the whole major version, and one that reports correct
+  code breaks every consumer's build on upgrade. Check the neighbours of each form a rule reaches:
+  `??` beside `?:`, `ConfigureAwait`/`WaitAsync` on a held task beside `await held`, a tuple or a
+  dictionary beside a collection, an extension block, a generic attribute, a static abstract or
+  inherited interface implementation.

.github/workflows/dotnet.yml

@@ -94,7 +94,7 @@ jobs:
         run: dotnet pack CodoMetis.TypeKit.slnx -c Release --no-build -o dist
 
       # The smoke test publishes a consumer with Native AOT, which links with the platform's clang
-      # and zlib (docs/plan.md §11).
+      # and zlib (design/native-aot.md).
       - name: Native AOT prerequisites
         run: sudo apt-get update && sudo apt-get install -y --no-install-recommends clang zlib1g-dev
 
@@ -143,7 +143,7 @@ jobs:
           global-json-file: global.json
 
       # The smoke test publishes a consumer with Native AOT, which links with the platform's clang
-      # and zlib (docs/plan.md §11).
+      # and zlib (design/native-aot.md).
       - name: Native AOT prerequisites
         run: sudo apt-get update && sudo apt-get install -y --no-install-recommends clang zlib1g-dev
 

.github/workflows/release.yml

@@ -136,7 +136,7 @@ jobs:
         run: dotnet pack CodoMetis.TypeKit.slnx -c Release --no-build -o dist
 
       # The smoke test publishes a consumer with Native AOT, which links with the platform's clang
-      # and zlib (docs/plan.md §11).
+      # and zlib (design/native-aot.md).
       - name: Native AOT prerequisites
         run: sudo apt-get update && sudo apt-get install -y --no-install-recommends clang zlib1g-dev
 

.gitignore

@@ -30,3 +30,6 @@ Thumbs.db
 
 # Benchmark runs: the numbers worth keeping go into benchmarks/README.md
 BenchmarkDotNet.Artifacts/
+
+# The codebase-memory MCP server's local graph artifact: rebuilt per checkout, never committed
+.codebase-memory/

AGENTS.md

@@ -12,8 +12,9 @@ that are written as one line and generated at compile time by Metalama.
 - **Satellites** map value objects to EF Core columns, where `.Value` works in LINQ as it does in
   memory, and to OpenAPI schemas.
 
-The packages are being built phase by phase: **read [docs/plan.md](docs/plan.md) before changing
-anything.** It holds the package map, the phase order and the decisions.
+**Read [design/plan.md](design/plan.md) before changing anything.** It is the map of `design/`: the
+[roadmap](design/roadmap.md), the [decision records](design/adr/README.md), one dated file per
+decision with its evidence, and a design note per area.
 
 This file is the canonical agent guide. There is no CLAUDE.md, on purpose.
 
@@ -40,12 +41,15 @@ This file is the canonical agent guide. There is no CLAUDE.md, on purpose.
 - Central package management (`Directory.Packages.props`). The versions of shipping references
   are floors for consumers, so raising one is a release decision. `spikes/` opts out of it and
   pins what each spike measured.
-- `test/CodoMetis.TypeKit.Samples` holds every C# block of the READMEs as compiled code, between
-  `// sample: {README}/{name}` and `// end sample`, beside tests that check the outputs the blocks
-  state in comments. `ReadmeSampleTests` (conventions) holds each block to exactly one region.
+- `test/CodoMetis.TypeKit.Samples` holds every C# block of the READMEs and of the `docs/` pages as
+  compiled code, between `// sample: {page}/{name}` and `// end sample`, beside tests that check the
+  outputs the blocks state in comments. `{page}` is `README`, a package id, or a docs page's file name
+  without `.md`. `ReadmeSampleTests` (conventions) holds each block to exactly one region.
 - `spikes/` holds experiments that decided something. Each one has a README with the question,
   the answer and the evidence. Spikes are not in the main solution and are never packed.
-- `docs/` holds the plan and the design notes.
+- `docs/` holds the topic pages a consumer reads, one per topic, each linked from the root README's
+  "Documentation" table; `design/` holds the roadmap, the decision records and the design notes,
+  which no test compiles but whose links the conventions check.
 
 Never hard-code a positional path (`../../`) to reach the repo root. Walk up to the
 `CodoMetis.TypeKit.slnx` marker instead.
@@ -63,6 +67,45 @@ The SDK is pinned in `global.json` (10.0.4xx band, `latestPatch`). Tests run on
 Platform (xunit.v3 4.x), so `dotnet test` takes `--solution`/`--project`, and TRX output is
 `--report-xunit-trx`. The build treats warnings as errors, including CS1591 on shipping projects.
 
+## Finding code
+
+The codebase-memory MCP server keeps a code graph of this repository, the project
+`CodoMetis.TypeKit`. It is the fastest way into the code, and it misses whole kinds of reference
+here, so it leads and the source decides.
+
+- **The graph first** to locate a symbol, list a type's implementers, trace callers and callees, and
+  size a change's impact (`search_graph`, `trace_path`, `query_graph`, `get_code_snippet`).
+- **Then the source and its tests**, read before concluding or editing. An edge is a lead.
+- **Text search** (`git grep`, `search_code`) for literals, messages, diagnostic ids,
+  configuration, documentation, and what the generators emit.
+- **An empty result proves nothing.** Fall back to text search when the graph is unavailable, stale
+  or silent, and never conclude "unused", "no other caller" or "safe to change" from it alone.
+  Measured on 2026-10-13, the graph:
+  - finds types, interfaces, enums and ordinary methods, a type's implementers through generic
+    interfaces (84 of the Samples' 88 value objects), and the callers of an ordinary method across
+    files;
+  - has no node for a member of a C# 14 `extension(...)` block, which holds most of the `Option` and
+    `Result` extensions (`Choose`, `FirstOrNone`, `Transpose`, `Sequence`, the continuations of a
+    `Task<Result<...>>`) and `AsText`, and puts the calls inside one on the file;
+  - has nothing Metalama generates: none of the tests' 222 `.From(` calls has an edge, nor has a call
+    to `TryFrom`, `FromKnownGood`, `Parse` or a converter, and a template an aspect introduces by
+    `nameof` looks unreferenced. Read woven code as the Generators README's "Reading the generated
+    code" says;
+  - misses a reference that is not a call: a DI registration, a type argument, `typeof`, an attribute;
+  - resolves a call on a generic instance poorly (`Option<T>.Match` has one resolved caller, where
+    the repository writes `.Match(` about 200 times across its types) and guesses wrong callers: a low-confidence `suffix_match` edge, or a same-named method of another API
+    (Metalama's `Diagnostics.Report` listed as calling `GeneratedCode.Report`). Overloads share one
+    node.
+- **Refresh it**, since it does not follow the working tree: `index_repository` with the repository
+  root as `repo_path` and `name: "CodoMetis.TypeKit"`, at the start of a session and after a branch
+  switch, a rebase, a merge or a pull (about 6 s). Without `name` it starts a second project under a
+  derived name. `index_status` reports the checkout's HEAD, not the commit the graph was built from,
+  so refresh rather than check.
+- It indexes `spikes/` and leaves out `.claude/`, `bin` and `obj`, so an agent in a worktree under
+  `.claude/worktrees/` reads the main checkout's graph, not its own: index the worktree under a name
+  of its own and delete that project when done, or search the source. `.codebase-memory/`, the
+  tool's local artifact, is ignored by git.
+
 ## Rules that are easy to break
 
 - **`CodoMetis.TypeKit` stays Metalama-free.** Nothing in the base package may reference
@@ -91,7 +134,7 @@ Platform (xunit.v3 4.x), so `dotnet test` takes `--solution`/`--project`, and TR
   `JsonSerializer` call that takes only options, in the packages or in woven code: a typed call
   (`GeneratedValueObjectAttribute.Accept`, `GeneratedJson.TypeInfo`) or an interface instead. An
   `[UnconditionalSuppressMessage]` needs a measured reason, and the smoke test's `aot` consumer is
-  the measurement (docs/plan.md §11).
+  the measurement ([design/native-aot.md](design/native-aot.md)).
 - **Aspects stay internal.** Their public surface is what they generate, and nothing else.
 - **A value object's JSON is its wrapped type's, byte for byte**, under whatever options the
   application uses, values and dictionary keys alike (`JsonParityTests`). Never write or read the
@@ -104,18 +147,22 @@ Platform (xunit.v3 4.x), so `dotnet test` takes `--solution`/`--project`, and TR
   introduce is CMTK1011. A new generated member joins that check, or a hand-written one is kept silently.
 - **Diagnostic ids (`CMTK`) are public contract.** Never renumber a shipped rule, and never ship a
   new rule at Error severity in a minor version.
-- **A README's C# block is compiled code.** Change it and its region in
+- **A README's or a docs page's C# block is compiled code.** Change it and its region in
   `test/CodoMetis.TypeKit.Samples` together, or `ReadmeSampleTests` fails; the region's scaffolding
   (the types and variables it assumes) stays outside the markers. An output a block states in a comment
   (SQL, JSON, a string) is read from the README by the test beside the region, so correct the comment,
   never the test. A block that cannot compile on purpose says `<!-- not compiled: {reason} -->` above
   its fence; an analyzer diagnostic in a comment is no reason, the sample suppresses it around the region.
+  A page in `docs/` is compiled by being there and must be linked from the root README's
+  "Documentation" table; a package README is the reference for its package, a docs page the guide for
+  a topic, and the same code block is never in both.
 - **Silent is worse than broken.** A value object that compiles without being generated, an
   analyzer that stops firing, or a converter that materialises `default` are this repo's
   characteristic failures. Prefer a diagnostic or an exception to a plausible result.
 
 ## Workflow
-1. Read `docs/plan.md` and the relevant spike README before starting.
+1. Read `design/plan.md`, the roadmap, the decision records and the design note for the area you
+   touch, and the relevant spike README, before starting. A decision is changed by a new record.
 2. Run `dotnet test` after each change.
 3. **Prove every fix by reverting it.** See `.claude/skills/verify-the-guard`. The same applies to a
    new analyzer test or a convention test: seed the defect it claims to catch.

CHANGELOG.md

@@ -10,6 +10,51 @@ A version's heading reads `## <version> — Unreleased` until the release is pre
 the release date. The release workflow refuses a tag whose section still says `Unreleased`, and the
 section is the GitHub release's notes.
 
+## 2.0.0 — 2026-10-14
+
+Still `net10.0` and Metalama 2026.1. What builds or runs differently, and what to write instead:
+[Migrating from 1.5 to 2.0](https://github.com/CaffeinatedCoder/CodoMetis.TypeKit/blob/main/docs/migrating-to-2.md).
+
+### Breaking
+
+- CMTK0003, a dropped `Result` or `Option`, is an Error, and reports more forms (`Wait()`, loops that never read, `??`, tuples).
+- `FirstOrNone`/`FirstOrError` on an `IQueryable` run in the query (a `Func` variable still reads every row); `LastOrNone`/`LastOrError` on a query no longer compile.
+- CMTK1022 refuses an abstract value object; CMTK1005 refuses one over `object` or `System.Enum`, or named as a generated member.
+- A generated `TryParse` lets an exception from `Create` through instead of answering `false`.
+- EF Core refuses `.Value` on a column with the application's own converter, and ordering by a hand-written `CompareTo`, in queries and query filters.
+- EF Core: value-object keys over `sbyte`, `ushort`, `uint` and `ulong` are generated as EF generates the plain type, so a migration may alter the column.
+- OpenAPI: a component name claimed by two types throws.
+- Async combinators throw `ArgumentNullException` for a delegate that returns no task.
+- `FaultProblem<TFault>` takes any `notnull` fault type.
+
+### Added
+
+- **Closed sets** (`IClosedSet<TSelf>`): a fixed set of named instances with `Match`, `Parse`, JSON, EF Core, OpenAPI and Serilog support; CMTK1013 to CMTK1021 refuse what cannot be generated.
+- **Fault responses a client can act on**: `Fault<TFault>`, fault sets with a kind per member, `FaultResponse`, `WithFaultStatus`/`[FaultStatus<T>]` per endpoint, group or controller, `ToHttpResult(success)` and `IFaultFeature`.
+- **`Patch<T>`**: a JSON Merge Patch field (absent, null or a value; `T` is `notnull`, so `Patch<string>` is a clearable string), with `Map`, `Traverse`, OpenAPI and test assertions.
+- **`Result.Catch`/`CatchAsync`**: an exception as a result; a cancellation passes through, a timeout is the error.
+- **Text guards**: `AsText()` and `AsIdentifier()` trim, compose to NFC (`AsText`) and refuse invisible characters.
+- **Type constraints**: `[Abstract]`, `[Sealed]`, `[Record]`, `[Concrete]` (CMTK0010) and `[RequireParameterlessConstructor]` (CMTK0011, with a code fix).
+- **CMTK0012**: a closed set's `Match` called by position, with a code fix.
+- **CMTK0013**: a closed set's member written outside its declaration, after it was named.
+- **`Option`**: async steps and `Task<Option<T>>` continuations, `SingleOrNone`, `ElementAtOrNone`, `Choose`, `Transpose`, `Traverse`; EF Core's `FirstOrNoneAsync` and `SingleOrNoneAsync`.
+- **`TraverseAsync`** on a sequence: one at a time, cancellable.
+- **Docs**: topic pages under `docs/`, every code block compiled.
+
+### Changed
+
+- The OpenAPI problem schema describes `fault`: regenerate clients.
+- CMTK0003 no longer reports a chain of taps on a result the caller holds.
+- EF Core: a `char` key stays the application's to assign; a default `ulong` key throws `OverflowException` at `Add` (use `ValueGeneratedNever()`).
+- Testing failures name a nested type with its containing types.
+- `CodoMetis.TypeKit.Generators` depends on `Metalama.Framework` 2026.1.30 or later (was 2026.1.29).
+
+### Fixed
+
+- A value object marked `[Obsolete(error: true)]` builds.
+- A default value object over a reference type formats as `""` instead of throwing.
+- Where the host inlines enums, a nullable value object over one admits null in the OpenAPI document.
+
 ## 1.5.1 — 2026-10-11
 
 ### Fixed