Resolve concrete types for single-table inheritance families

[evoactivity]

Closes #9.

The problem

With single-table inheritance, typed subclasses share one table and a discriminator column tells them apart. Lucid hydrates base-targeted relations as the base class, which is correct for an ORM with no discriminator concept, but the serializer derived a row's JSON:API type from its class rather than from the row. Every such row serialized as the base type, and writes rejected the concrete types. Client caches key on type + id, so the abstract type creates a second identity for the same row that nothing ever resolves.

The API

Two statics on the base resource:

export default class SportsTeamResource extends JsonApiResource<SportsTeam> {
  static model = () => SportsTeam
  static subtypes = () => [FootballTeamResource, RugbyTeamResource]
  static resolveResource(row: SportsTeam) {
    return { football: FootballTeamResource, rugby: RugbyTeamResource }[row.sport]
  }
}

resolveResource serves reads, row in, concrete resource out. subtypes serves writes, the set of types a relation targeting the base accepts. Declaring neither changes nothing anywhere, the feature is fully opt-in.

Behaviour

• Reads: rows resolve to concrete types everywhere they appear — primary data, linkage, included (deduplicated under the concrete type), relationship-endpoint GETs, and sparse fieldsets key on the concrete type. Type derivation lives in one overridable typeName() on the resource; typeFor and typeForRow both delegate to it, cached per resource class.
• Unloaded belongsTo targeting an STI base emits no data member, keeping its links. A bare foreign key cannot name a concrete type, and guessing the base type puts the same row in one payload under two identities, the abstract one dangling — a full-linkage violation client caches then fork on. Non-STI targets keep FK-derived linkage byte-for-byte unchanged, pinned by tests.
• Writes accept the family. acceptedTypesFor(Model) feeds parseLinkage, the deserializer's relationship members, and primary data.type, so any member type is accepted, mixed types work in one payload, and the 409 names every acceptable type. The abstract base type is rejected on every path — it never belongs in a payload.
• Type claims are verified. The family shares one id space, so football-teams/7 where row 7 is a rugby team names a resource that does not exist, yet existence checks alone would attach it silently. verifyRelatedExist now takes the claimed identifiers and the registry (required, so no call site can skip it — the documented low-level recipe gains the third argument) and 404s contradicted claims.
• Wildcard endpoints for runtime-defined kinds: DeserializeOptions.expectedType pins primary acceptance to the one type a URL names, and the deserialized result carries the validated type so a controller can stamp the discriminator. Runtime-built resource families (kinds as user data) are supported and pinned by tests.
• Registration: registering a base auto-registers its declared subtypes as a safety net; explicit registrations always win, in either order.

Beyond the original scope comment, called out honestly

• typeName() as a public override hook (single home for type derivation).
• resolveResource chaining with a cycle guard.
• Subtype auto-registration.
• Primary-data family acceptance, expectedType, and result.type (added for wildcard endpoints over runtime families).

belongsTo coverage

The example app gains a nullable Article.cover belongsTo targeting the base, so the last two behaviours pinned only at unit level now have functional coverage: the links-only member for an unloaded belongsTo, and the 404 for a replace whose claimed type the row's discriminator contradicts, including that the rejected replace leaves the foreign key untouched.

Breaking changes

• verifyRelatedExist gains a required registry parameter (documented low-level API).
• An STI base endpoint no longer accepts the abstract base type as primary data.type once subtypes is declared. Without declarations, behaviour is unchanged.

Worth a minor bump.

Tests and docs

45 new unit tests across sti_registry, sti_documents, sti_writes plus fixture families; 10 functional tests in the example app over a real database, which also gains the working reference implementation (Attachment/Image/Video with scoped subclasses, per-file resources). Every request/response example in the new docs/polymorphism.md is transcribed from captured output, not written by hand.

Unit 174 passed, example functional 62 passed, lint and typecheck clean in both.