Skip to main content

How do I add or change a CRA clause mapping without a deploy?

Add a source to the registry, add or supersede a mapping in the seed, then run the mapping check and the ingest command. The clause-to-evidence rules are data, so a regulatory change is a data insert, not a code release.

Key takeaways​

  • A clause mapping lives in an append-only database table, never in application logic.
  • A mapping is never edited. A change is a new version, and the old version stays for audit.
  • Every mapping cites one source of truth in the registry, keyed by a CELEX or EN identifier.
  • The mapping check runs in CI and needs no database, so a bad mapping fails the build early.
  • The regulatory corpus holds the full text, and the registry holds the citation. They link by identifier.

What the pieces are​

The mapping layer has three append-only tables. cra_source_registry holds one row per official source, a regulation, a standard, a guide, or a case scenario. cra_clause_mapping holds one row per clause version, with the evidence type it demands and the acceptance rules an agent evaluates. cra_assessment_result holds one dated verdict per clause and product.

No row is ever updated or deleted. The database blocks it. A change is a new insert, and which record is live is computed from the version and the effective date.

Add a source​

Sources are seeded from the regulatory corpus by src/lib/cra/source-registry-seed.ts. To add a public source with a CELEX or EN identifier and a resolvable URL, add an entry to the PUBLIC_OVERLAYS map in that file, keyed by the corpus document id. To add a source that is not in the corpus, extend the builder to include it.

Then load it into the database.

npm run mappings:ingest-sources

The command inserts a source that is absent and skips one that is present. It never updates a row.

Add or supersede a mapping​

Mappings are built by src/lib/cra/mapping-seed.ts from the Annex I requirement text, the traceability clauses, and the acceptance rules. To change what a clause demands, change the seed entry. Keep the requirement text as a pointer into annex-i.ts, never a second copy of the legal sentence.

Validate the change with no database.

npm run mappings:check

The check confirms every mapping uses a closed-vocabulary evidence type, a well-formed clause key, a non-empty rule set, and a source that exists in the registry. It runs in CI.

Then ingest.

npm run mappings:ingest

The command inserts a mapping that is absent. When a mapping's substance changed, it inserts a new row with the next version and leaves the old version in place. An assessment run "as of" an earlier date still resolves the version that was live then.

Why there is no edit path​

An auditor needs to see the rule as it stood on the day a product was assessed. An edit would erase that. So the store is append-only at the database layer, and the only way to change a mapping is to add a version. The history is the audit trail.