# hospitality.allergen-matrix

Status: needs review by a food-safety professional before it is published; it summarises declared data, it does not detect allergens.

Given each ingredient of a dish and the allergens its supplier declares, this
returns one row for each of the 14 regulated allergens, in legal order:
`contains`, `may-contain` or `none`, and which ingredients are the source.
That is one row of the allergen matrix a kitchen keeps for every dish.

## How the status is decided

- **contains**: at least one ingredient declares it. The sources are those
  ingredients only.
- **may-contain**: no ingredient contains it, but at least one carries a
  precautionary "may contain" statement for it. That is a cross-contamination
  warning from the supplier, not an ingredient, and it is kept separate so the
  menu can say so rather than claim the allergen is an ingredient or leave it
  out.
- **none**: nothing declared. Every allergen gets a row, so "none" is shown as
  a checked answer, not left out.

Sources keep the order the ingredients were given, without duplicates.

## Codes

`gluten`, `crustaceans`, `eggs`, `fish`, `peanuts`, `soybeans`, `milk`, `nuts`,
`celery`, `mustard`, `sesame`, `sulphites`, `lupin`, `molluscs`. An unknown
code (`tree-nuts`, `gluten free`) is an error rather than being ignored,
because an allergen dropped by a typo is the failure that hurts someone.

## What it does not do

- It does **not** detect allergens. It trusts the declarations it is given,
  and an ingredient whose specification is missing or out of date gives a
  wrong answer. Keep specifications current, and re-run the matrix when a
  supplier or recipe changes.
- It does not name the specific cereal or nut. The law requires "wheat",
  "almonds" and so on, not just "cereals containing gluten" or "nuts". Carry
  that detail in the ingredient name.
- Sulphites only count above 10 mg/kg or 10 mg/litre (as SO2). Whether an
  ingredient crosses that threshold is for its declaration to say.
- It says nothing about cross-contact in your own kitchen, which the FSA
  expects a business to manage and communicate separately.

## The list is data

The 14 are dated rows in `data/allergens.json`, keyed by jurisdiction, and the
function takes the date the food is served. If the list changes, that is a
data release, not a code change. The rows apply from 13 December 2014, when
Regulation (EU) No 1169/2011 (FIC) began to apply. Lupin and molluscs were
already on the earlier list, added by Directive 2006/142/EC. A date before
then, or a jurisdiction with no rows, is an error.

`GB` covers England, Scotland and Wales under the retained regulation.
Northern Ireland applies the EU regulation directly and has the same 14 today,
but it is not in this data.

## Sources

- Regulation (EU) No 1169/2011 on the provision of food information to
  consumers, Annex II, *Substances or products causing allergies or
  intolerances*, as retained in GB law:
  https://www.legislation.gov.uk/eur/2011/1169/annex/II
- The Food Information Regulations 2014 (SI 2014/1855), which enforce it in
  England. Regulation 5 covers allergen information for food that is not
  prepacked, and regulation 5A covers food prepacked for direct sale
  ("Natasha's Law", from 1 October 2021):
  https://www.legislation.gov.uk/uksi/2014/1855/contents . Scotland, Wales and
  Northern Ireland have parallel regulations. Note that the list of 14 itself
  is in Annex II of the EU regulation, not in a Schedule of the 2014
  Regulations.
- Food Standards Agency, *Allergen guidance for food businesses*:
  https://www.food.gov.uk/business-guidance/allergen-guidance-for-food-businesses

## Before you rely on this

**Not professional advice.** This capability calculates food-safety figures from published rules. It is a software component for developers, not food-safety advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a food safety officer (EHO) review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified food safety officer (EHO) has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

## Notices

Contains public sector information licensed under the Open Government
Licence v3.0 (https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).

Legislation: Crown copyright and database right.

1.0.1 marks it unreviewed and adds its attribution notices (NOTICE). The code and the tests are unchanged.