AI-Native Catalogue Enrichment Service

The project began with three documents and no repository: a ~900-line specification (27 sections covering objective, boundaries, architecture, schema, scoring weights, thresholds, a retry matrix, 11 work packages and acceptance criteria), ~390 lines of engineering rules, and ~380 lines of agent operating rules with authentication invariants and a security review checklist. Two properties of that input mattered more than its length. It stated invariants, not just features — "a missed match is recoverable; a wrong artwork assignment silently corrupts the catalogue" decided a dozen later arguments without anyone re-litigating them. And it pre-empted a specific wrong turn by name, correcting upfront the plausible misconception that one identity provider could authorise calls to a different provider's API.

A specification that says what must never happen is worth more to an AI-native build than one that says only what should.

The split was not evenly distributed across the work — and that is the point. Human attention concentrated where it was worth most: domain facts the model could not know (which database, which table, which column), product judgement with no technically correct answer (when one recording appears on an album, a single and three compilations, which cover art is "right" is a taste decision about a catalogue, not an engineering one), and authorisation of anything irreversible — no write reached the production catalogue without explicit, scoped approval. Everything else — architecture, schema shape, concurrency strategy, error taxonomy, test design — was drafted by the model and reviewed rather than directed.

The result is auditable rather than asserted: of 41 consequential decisions recorded in the project's decision ledger, 16 were made by a human — 39%. The ledger classifies them: four domain facts, six product judgements, six authorisations. The model's 25 span architecture, schema design under the real engine's constraints, and ten safety decisions from structurally unobtainable tokens to single-statement paired writes.

The specification survived, but not unamended. Six changes came from the client correcting the brief — the instructive one being the datastore. The spec named PostgreSQL; the real catalogue was MySQL 5.7, which parses CHECK constraints and silently ignores them. A schema written to the specification would have carried constraints that enforced nothing, and nobody would have known. The fix expressed those vocabularies as ENUM, with tests proving the database itself rejects a bad value. When a specification and reality disagree about infrastructure, the risk is rarely the obvious incompatibility — it is the silent one.

The larger category of change could only be learned by running against real data. The provider's own search is not exact — a query naming a song's specific version returned zero results while the same query without it returned nine, so the service relaxes its search while keeping its judgement strict. Region selection was corrected by measurement, not reasoning, after the plausible choice silently deleted a fifth of the coverage. And the first live run invalidated a core assumption: the winner-margin rule, designed to flag genuine ambiguity, fired on 6 of 10 songs because the same recording legitimately appears on an album, a single and a compilation with identical scores — extrapolated across ~85,000 songs, it would have flooded a review queue no human would ever clear. The rule wasn't wrong; its scope was. A rule that is correct on ten hand-written examples can still be unusable at catalogue scale.

Every defect here was caught before production — by a test, a labelled fixture, or a live probe. A late instruction to "match title and artist exactly" was implemented as exactly that, and the labelled fixture immediately reported precision falling from 1.000 to 0.700: a live recording matched to a studio song, an instrumental to a vocal, one remix to a completely different remix. The implementation had missed that a song's version is part of its identity, not a detail about it. Had this shipped, it would have attached wrong cover art quietly and at volume — the exact failure the specification's opening principle existed to prevent. The fixture caught it in seconds.

Other catches: an arithmetic review showed a title 91% similar to the source reached exactly the automatic-approval threshold — a song one word different could have been approved with no human involvement (closed by requiring exact identity before anything unreviewed is written). A wiring fault where declaring a second database connection silently bound every repository — including user identity and credentials — to the client's song catalogue instead of the application's own database, caught by a test written specifically to assert the two databases stay separate. And the most important one: with no provider credentials configured, the deployed application answered every page with a bare 403 while 236 tests passed green. Tests prove what you thought to ask; running the real artefact proves what you did not.

The acceptance bar lives in files, not conversations. A 29-case labelled fixture covers exact matches, Unicode, punctuation, multi-artist credits, live, remix, remaster, cover, karaoke, duplicate titles and no-match — with precision as the gate: zero incorrect automatic matches permitted, because a missed match is recoverable and a wrong one is not. Threshold changes require fixture evidence, not argument. Authoritative schema tests run against a pinned MySQL 5.7 container because that is where the silent-CHECK behaviour lives; concurrency is asserted, not assumed — twelve threads racing for one work item produce exactly one winner, forty items across eight workers partition with zero overlap. 41% of the Java written is test code. That ratio was not a target; it is what proving these properties actually cost.

Delivered and verified: a fully standalone service (own build, database, migrations, security configuration, review interface, container image) reaching the client's catalogue only through one narrow adapter; encrypted provider credentials verified end-to-end; deterministic, explainable matching; batch execution with abandoned-work recovery and dry-run; and a human review interface showing candidate artwork side by side with the reasoning for each. In progress: full-catalogue enrichment (the engine is proven, the rollout is not) and least-privilege database credentials. Not yet done: operations hardening — metrics, alerting, deployment automation, rollback rehearsal. The production footprint remains deliberately small, and this page will say so until that changes.