Entity normalisation

The vendor's wire format is not my domain model.

External APIs return whatever they want — Spotify returns external_urls.spotify, GitHub returns html_url, Linear returns url. If raw vendor responses leak into the rest of the codebase, every consumer ends up special-casing every vendor. The fix is to normalise at the boundary: one shape, one discriminator, vendor-specific noise tucked into a metadata bag.

This is the ait ETL pattern. It's the data-channel counterpart to result-not-throw (the error channel). Together they make the type system useful: errors are typed, data is typed, the boundary is the only place either lives in the wild.

When this skill is active

You are about to:

• Pull data from an external API and store / index / process it
• Add a new connector or integration
• Define a new entity type
• Write a mapper from vendor response → internal type
• Touch the EntityType union or its VALID_ENTITY_TYPES set

The contract