Redesign the record taxonomy around a stored recordType discriminant

[williamthorsen]

Problem

The schema derives a record's family, note versus event, instead of storing it. The loader builds a kind grouping from the kinds: block in .kb/schema.yaml, then scans that hierarchy to discover which family owns a record's type value. A record's identity therefore depends on a schema lookup rather than living in the record, so a misplaced or mistyped record is silently classified as the wrong family.

The grouping is also poorly named and tangled with type. kind and type sit side by side meaning almost the same thing ("what sort of record"), and type does three unrelated jobs at once: it marks the note-versus-event family (via the kind lookup), it holds the Diátaxis rhetorical label on assertions (howto/concept/…), and it names the event variant (observation/mistake). None of the three is a distinction the library should model. The family is identity and belongs in the record as a stored field; the Diátaxis label is a vault facet; and the event variant was only ever "does this event carry a correction," a freeform value the writer supplies, never something validation needed to enforce.

The package is still private and its live consumers are few, so this is the moment to settle the model before #723 (publish) hardens the vocabulary for external consumers.

Context

• The note corpus lives in a separate repository, vaults.coding, not here. This ticket changes only the tooling: the @codeassembly/kb library, the codeassembly-event-store template, the capture-event writer, kb-retrieve (which reads the event type, so it cannot stay untouched), and kb-add (a second frontmatter writer forced to change because it builds notes through the shared Frontmatter type). Migrating the vault's 271 notes (269 assertions, 2 events) and rewriting the vault's own .kb/schema.yaml is a separate, dependency-linked ticket in vaults.coding. No vault files are touched here.
• Identity must stay frontmatter-borne, not placement-borne. Deriving recordType from a record's directory (content/events/ versus content/assertions/) would silently misclassify a misplaced file. Enumeration by location stays fine, since that only selects candidate files.
• recall and immutable are stored on the grouping today but read by nothing. They remain reserved policy, attached to the record type.
• The observation/mistake distinction was modeled as a per-type schema shape (mistake declares a required correction field) and enforced at capture time via --type mistake. That coupled a generic event mechanism to one early use case. Note validation never rejects undeclared fields and the schema's optional list is documentary, so the library never needed to know about correction; only the per-type required line ties it in. This change removes that coupling: correction and the mistake marker become a writer/skill convention, not a library or capture-event concern. Reliable capture of those values is tracked in Provide a reliable way to capture mistake events and their corrections #737, pending schema maturation.

Proposed solution

• Store the family as recordType, valued assertion or event. This replaces the derived kind; the term kind disappears from frontmatter, from .kb/schema.yaml, and from the library.
• Rename the schema block kinds: to recordTypes:, keeping each record type's required, optional, recall, and immutable. Validation checks recordType against the declared record-type vocabulary and reads a record type's required set directly, with no kind-to-type scan and no inner per-type layer.
• Retire bare type from the library model entirely. The Diátaxis label and any coarse-subject facets (mode, domains) become ordinary optional fields a store may declare; the library gives them no special support, and whether the vault adopts them is the vault ticket's call.
• The library gains no knowledge of mistake or correction. With the per-type required-additions layer gone, the schema collapses to a single level keyed by record type, and correction is just a freeform field a store may carry like any other.
• capture-event becomes a generic event writer: it always writes recordType: event and drops both --type and --correction. It no longer distinguishes observation from mistake or enforces any correction. Capturing mistake-specific values reliably is deferred to Provide a reliable way to capture mistake events and their corrections #737.
• Update kb-retrieve for the retired type: event recurrence grouping keys on repo alone, with the type segment removed, and any read of the retired type field moves to the new model so the helper compiles and groups coherently.

Acceptance criteria

Must have

• A record's family is a stored frontmatter field, recordType, valued assertion or event; kind is removed from the library, from .kb/schema.yaml, and from frontmatter.
• The schema block is recordTypes:, each record type declaring its own required, optional, recall, and immutable; validation checks recordType against the declared vocabulary and reads the required set directly, with no kind-to-type scan and no inner per-type layer.
• Bare type is removed from the library model, and the library carries no special knowledge of mistake or correction.
• capture-event writes recordType: event, drops the --type and --correction flags, and performs no mistake/correction handling.
• kb-retrieve is updated for the retired type: event recurrence groups by repo alone, and it no longer reads a type field that events no longer carry.
• kb-add writes recordType: assertion on every note; its --type flag becomes optional, with the Diátaxis label written to the note's extra fields rather than a top-level type.
• The codeassembly-event-store template schema and all codeassembly-owned schema fixtures are migrated off kinds: and bare type.
• New and modified behavior is covered by tests.
• Documentation, schema comments, and help text reflect the recordType model and drop the kind/kinds: and bare-type vocabulary; capture-event's docs drop the observation/mistake framing and the removed flags.

Should have

• The bundled default schema reflects the recordType model, dropping the retired type and Diátaxis-as-type vocabulary.

Dependencies

• Builds on: #714 Add event capture and a kind-aware record-store core #717 (the kind-aware record-store core this reshapes).
• Blocks: Provide a reliable way to capture mistake events and their corrections #737 (reliable capture of mistake values; builds on the post-redesign generic capture-event).
• Blocks: williamthorsen/vaults.coding#16 (rewrite 271 notes and the vault .kb/schema.yaml to recordType); the vault migration depends on this library change landing first.
• Blocks: Publish @codeassembly/kb to npm via trusted publishing #723 (publish to npm); publishing hardens the schema vocabulary for external consumers, so this must land first.
• Related: Add a config-driven kb check CLI and library export #718 (config-driven kb check), a sibling feeding Publish @codeassembly/kb to npm via trusted publishing #723, not a dependency in either direction.

[williamthorsen]

Insight from the orchestrated implementation run (20260606-093954Z)

The core architectural shift here is that a record's identity moved from derived to stored. Previously the loader built a kind grouping from the kinds: block and scanned that hierarchy to discover which family owned a record's type value — so a misplaced or mistyped record could be silently classified as the wrong family. Storing recordType directly on the record eliminates that whole class of silent misclassification: identity now lives in the record, not in a schema lookup.

The fail-closed rejection of stores still using kinds:/flat types: is the deliberate trade that makes this safe. Rather than half-understanding an old-format store and writing a possibly-misclassified record, validation refuses and writes nothing — failing loud at load time instead of failing silently at read time. The cost is that an unmigrated store breaks until updated (coordinated with vaults.coding#16), which is the intended behavior, not a regression.