@@ -1,17 +1,17 @@
 An entity is the value guarantee, not just the type one. Construction
-refuses values the spec disallows, so `BloscCodec(clevel=99)` raises
-rather than serializing a document no reader will accept, and there is no
-such thing as an invalid entity to hold. Code that wants unvalidated
-metadata already has somewhere to put it: `Opaque`, which carries the
-JSON verbatim.
+refuses values the spec disallows, so `BloscCodec(BloscOptions(clevel=99))`
+raises rather than serializing a document no reader will accept, and
+there is no such thing as an invalid entity to hold. Code that wants
+unvalidated metadata already has somewhere to put it: `Opaque`, which
+carries the JSON verbatim, and the configuration record itself, which is
+the options as written and not yet judged.
 
-One piece: a function of the instance that yields the values the spec
-disallows as it finds them, bound on the class as `problems`. The
-constructor stops at the first and raises `MetadataValidationError`;
-`coerce` runs it to the end and reports every problem in the document
-instead of raising; a consumer holding an entity may run it too, and
-stop or collect as it likes. `create_unchecked(**members)` builds the
-record without the check, for a reader that judges afterwards.
+One piece: the configuration record's own `problems`, which yields the
+values the spec disallows as it finds them. The entity's constructor
+stops at the first and raises `MetadataValidationError`; `coerce` asks
+the record before it builds anything and reports every problem in the
+document instead of raising; a reader with a record asks it too,
+`BloscOptions(...).problems()`, and stops or collects as it likes.
 
 `must_understand` moves to a class variable and out of the configuration
 entirely. It is a property of the *kind* of metadata -- a codec is
 
@@ -27,8 +27,12 @@ nothing about whether a shard's pipelines are well formed and silencing
 them would lose a real judgment. A *required* one stops the entity,
 because there is no honest reading of a `blosc` whose level is a string.
 
-The type judgment is read off the entity's own fields rather than
-written twice. Which members exist, which may be left out (the type
+An entity has the shape of its metadata: its name is the class, and its
+configuration, for an entity that adds `Configured` beside its kind, is
+a frozen `Configuration` record named in the one field `configuration`
+-- `class GzipCodec(BytesBytesCodec, Configured)` with `configuration:
+GzipOptions`. The type judgment is read off the record's fields rather
+than written twice. Which members exist, which may be left out (the type
 admits `UNSET`), and how each is type-checked all follow from the field
 annotations: `int`, `float` for any number, `bool`, `str`, a `Literal`
 of names, the JSON-value alias, an array homogeneous or fixed, a union
@@ -37,17 +41,17 @@ dataclass, an object of undeclared keys as `Mapping[str, V]`, a
 `NewType` as the type it names, and a nested metadata field, written as
 its kind with `Opaque`. That covers
 every member this package models; an annotation outside them is refused
-at registration, and `Annotated[str, FROM_NAME]` marks the one field
-carried by the envelope's name rather than a configuration key (`r<N>`),
-which `coerce` fills from the envelope. Whether a configuration is required
-follows too, since the spec ties the bare-name spelling to whether any member is
-required.
+at registration, and `Annotated[str, FROM_NAME]` marks the one field of
+the entity itself, carried by the envelope's name rather than a
+configuration key (`r<N>`), which `coerce` fills from the envelope.
+Whether a configuration is required follows too, since the spec ties the
+bare-name spelling to whether any member is required.
 
-Nothing is derived from the fields ahead of time: `coerce` parses a
-configuration against them as it reads it. Field annotations are
-resolved per class, skipping class variables by text, so a `ClassVar`
-naming something imported only for the type checker cannot fail
-registration.
+The record's parser and writer are compiled once per class from its
+annotations, and `coerce` runs the parser over the configuration as it
+reads it. Field annotations are resolved per class, skipping class
+variables by text, so a `ClassVar` naming something imported only for
+the type checker cannot fail registration.
 
 One diagnostic became more precise: a malformed `[value, count]` pair in
 a rectilinear grid is now reported at the offending element inside the
@@ -57,10 +61,10 @@ An entity that contains other entities declares the field --
 `data_type: DataTypeEntity | Opaque`, `codecs: tuple[CodecEntity |
 Opaque, ...]`, a record holding one -- and the contained entity is read
 through the scope the containing one is read in, at whatever depth the
-annotation puts it. Writing it back and putting it in canonical form
-are the containing entity's own two lines, `written(self.inner)` in
-`to_json` and `replace(self, inner=canonicalized(self.inner))` in
-`canonical`, the same way it writes and simplifies its own members.
+annotation puts it. Writing it back is the base's, through the contained
+entity's own `to_json`; putting it in canonical form is the containing
+entity's one line, `self.with_configuration(inner=self.inner.canonical())`
+in `canonical`, the same way it simplifies its own members.
 `canonical` is the entity itself by default, overridden where two
 spellings of its members mean the same -- a rectilinear dimension's
 run-length encoding, a `typesize` that `noshuffle` ignores. A field
@@ -69,19 +73,19 @@ refused at registration: no scope could place the one, and the other
 lies about what the field holds when the inner name is out of scope.
 
 Everything finer than a type -- a bound, a rule about one member, a
-rule that reads two members together -- is a function of the entity's
-instance, in plain code, that yields each problem as it finds it,
-located relative to the configuration, and is bound on the class as
-`problems`. The constructor stops at the first, so `BloscCodec(clevel=99)`
-raises `MetadataValidationError`; `coerce` runs it to the end and
-reports every problem in the document; a consumer holding an entity may
-run it too, stopping or collecting as it needs. The space of
+rule that reads two members together -- is the record's own `problems`,
+in plain code, yielding each problem as it finds it, located relative
+to the configuration. The entity's constructor stops at the first, so
+`BloscCodec(BloscOptions(clevel=99))` raises `MetadataValidationError`;
+`coerce` asks the record before it builds anything and reports every
+problem in the document; a reader with a record asks it too, stopping
+or collecting as it needs. The space of
 refinements is too wide to capture statically, and reading them in one
 place per entity is what will show where a shared form is worth having.
 
 The set of annotation shapes the parser reads is closed: the shapes
 JSON takes, and no others. A field annotation outside them is refused
 at registration, and the field is written as one of them instead, with
-any finer rule in the function bound as `problems`. The parser is one module that knows
+any finer rule in the record's `problems`. The parser is one module that knows
 nothing of entities; the entity layer hands it the one shape of its own,
 a field holding an entity, as a leaf it reads at any depth.
@@ -9,9 +9,10 @@ data type, chunk grid and chunk key encoding — is a class that answers
 for itself:
 
 - `coerce` reads raw metadata into the entity, or says why it is not one;
-- `problems`, a function of the instance bound on the class, yields the
-  values the spec disallows as it finds them; the constructor stops at
-  the first and raises, and `coerce` reports every one instead;
+- its configuration is a record of its own, `GzipOptions`, whose
+  `problems` yields the values the spec disallows as it finds them; the
+  entity's constructor stops at the first and raises, and `coerce`
+  reports every one instead;
 - `to_json` writes it back as it was read, and `canonical` gives its
   simplest equivalent spelling;
 - `incoming_problems`, `shape_problems`, `fill_value_problems` and
 
@@ -12,9 +12,9 @@ TypedDicts. The tables cannot drift now, because there is one of each
 fact instead of four.
 
 What replaces the drift tests is a correspondence test: an entity's
-dataclass fields, its configuration TypedDict, and its member table are
-three spellings of one set, and whether the bare-name spelling is
-allowed follows from the TypedDict's required keys.
+configuration record and its configuration TypedDict are two spellings
+of one set of members, with the same requiredness, and whether the
+bare-name spelling is allowed follows from that.
 
 One more table went the same way: `zarr_metadata.v3.codec.kind`, which
 sorted codec *names* into the spec's three pipeline kinds. A name does
 
@@ -96,7 +96,7 @@ registration checks for that are gone. Which of a document's fields
 holds which kind is the document's own knowledge, in one place; the
 entity layer no longer names a document field.
 
-`to_json` is written once, in the base, from the fields: `writer_for`
+`to_json` is written once, in the base, from the configuration record: `writer_for`
 is the parser's inverse over the same annotation, so what `coerce` reads
 from a document, `to_json` puts back -- the bare name when every member
 is absent, the object otherwise, a contained entity through its own
@@ -134,3 +134,21 @@ compiled into it, and the plan for a class, like its resolved field
 annotations, is a pure function of the class and cached as one. A
 document with a shard, six codecs and a nested pipeline reads in 85 µs
 where it took 199, and one codec in 6 µs where it took 21.
+
+An entity has the shape of its metadata. Its name is the class, and its
+configuration, for an entity that adds `Configured` beside its kind, is
+a frozen `Configuration` record named in the one field `configuration`
+-- `class GzipCodec(BytesBytesCodec, Configured)` with `configuration:
+GzipOptions`, read as `codec.configuration.level` or through a
+`@property` the entity adds for a member it wants at the top level. The
+record's fields are the members and its `problems` the rules on them,
+so the lift of configuration keys to the entity, which nothing in Python
+expressed, is gone with the per-member loop in `coerce` that did it: a
+configuration is parsed and written by the parser's and the writer's
+record shapes. `with_configuration(**changes)` is the entity with members
+of its configuration replaced, checked as any construction is. A record
+is the options as written, judged on request; the entity is the value
+guarantee, and `coerce` asks the record before it builds one, so no
+unchecked construction path exists. The rule a family has about its
+name -- `r<N>` a multiple of 8 -- is the entity's `name_problems`, since
+a name is not configuration.