Skip to Content
InternalDocsComplianceAphis Core Pack

Aphis Core Pack

Source: docs/compliance/aphis-core-pack.md

# APHIS CORE Jurisdiction Pack
 
## Overview
 
The USDA Animal and Plant Health Inspection Service (APHIS) uses the **CORE** (Commercial Operational Regulatory Electronic) message set to declare regulatory data at the point of entry into the United States. APHIS obligations are transmitted via the ACE (Automated Commercial Environment) PGA (Partner Government Agency) Message Set.
 
This jurisdiction pack is derived from **PGA Message Set Implementation Guide v6.3 (December 2024)** and covers four APHIS sub-authorities.
 
**Key characteristics:**
- **Jurisdiction:** US
- **Model:** Commodity-based (HS prefix + origin country + product category matching)
- **Program code:** CORE
- **Source data version:** `aphis-core-v6.3`
 
## Authorities Covered
 
| Code | Authority | Scope |
|------|-----------|-------|
| **AAC** | Animal Care | Live animal imports — welfare declarations, facility certifications, exhibition and event animals, marine mammals |
| **ABS** | Biotechnology and Regulatory Services | Genetically engineered organisms — biotech permits, field-trial material, engineered microbes, genome-edited plants |
| **APQ** | Plant Protection and Quarantine | Plant and plant product imports — phytosanitary certificates, inspection notices, nursery stock permits, wood packaging, produce |
| **AVS** | Veterinary Services | Livestock and animal product imports — health certificates, disease declarations, hatching eggs, veterinary biologics, companion animals |
 
## Obligation Inventory
 
### AAC - Animal Care (5 obligations)
 
| Code | Name | HS Prefixes | Product Categories | Required Documents |
|------|------|-------------|--------------------|--------------------|
| `APHIS-AAC-CORE-101` | Animal Welfare Transport Declaration | `0106` | live_companion_animals | `AAC_WELFARE_DECLARATION` |
| `APHIS-AAC-CORE-102` | Research Animal Facility Certification | `0106` | research_animals | `AAC_FACILITY_CERT` |
| `APHIS-AAC-CORE-103` | Exhibition Animal Movement Notice | `0101`, `0102`, `0103`, `0104` | exhibition_animals | `AAC_EXHIBITION_NOTICE` |
| `APHIS-AAC-CORE-104` | Animal Event Quarantine Plan | `0101`, `0102`, `0106` | event_animals | `AAC_QUARANTINE_PLAN` |
| `APHIS-AAC-CORE-105` | Marine Mammal Entry Restriction Review | `0106` | marine_mammals | `AAC_MARINE_REVIEW` |
 
### ABS - Biotechnology (5 obligations)
 
| Code | Name | HS Prefixes | Product Categories | Required Documents | Status |
|------|------|-------------|--------------------|--------------------|--------|
| `APHIS-ABS-CORE-201` | Biotechnology Organism Permit | `1209`, `1005` | biotech_seeds | `ABS_BIOTECH_PERMIT` | ACTIVE |
| `APHIS-ABS-CORE-202` | GE Trial Material Declaration | `1209`, `0713` | biotech_trial_material | `ABS_TRIAL_PROTOCOL` | ACTIVE |
| `APHIS-ABS-CORE-203` | Engineered Microbe Handling Notice | `3002`, `3822` | engineered_microbes | `ABS_CONTAINMENT_NOTICE` | ACTIVE |
| `APHIS-ABS-CORE-204` | Genome-Edited Plant Risk Statement | `0602`, `0709` | genome_edited_plants | `ABS_RISK_STATEMENT` | ACTIVE |
| `APHIS-ABS-CORE-205` | ABS Transitional Exemption Flag | `1209` | biotech_seeds | `ABS_TRANSITIONAL_EXEMPTION` | SUSPENDED (sunset 2027-12-31) |
 
### APQ - Plant Protection and Quarantine (5 obligations)
 
| Code | Name | HS Prefixes | Product Categories | Required Documents |
|------|------|-------------|--------------------|--------------------|
| `APHIS-APQ-CORE-301` | Phytosanitary Certificate Required | `0603` | cut_flowers | `PHYTO_CERT` |
| `APHIS-APQ-CORE-302` | Plant Material Inspection Notice | `0602` | live_plants | `APQ_INSPECTION_NOTICE` |
| `APHIS-APQ-CORE-303` | Nursery Stock Permit | `0602` | nursery_stock | `APHIS_PERMIT` |
| `APHIS-APQ-CORE-304` | Wood Packaging Declaration | `4415` | wood_packaging | `WOOD_TREATMENT_DECLARATION` |
| `APHIS-APQ-CORE-305` | Produce Entry Declaration | `0709`, `0808`, `0805` | produce | `APQ_ENTRY_DECLARATION` |
 
### AVS - Veterinary Services (5 obligations)
 
| Code | Name | HS Prefixes | Product Categories | Required Documents |
|------|------|-------------|--------------------|--------------------|
| `APHIS-AVS-CORE-401` | Veterinary Health Certificate | `0101`, `0102`, `0103`, `0104` | livestock | `VS_HEALTH_CERT` |
| `APHIS-AVS-CORE-402` | Animal Product Disease Declaration | `0201`, `0202`, `0207` | animal_products | `VS_DISEASE_DECLARATION` |
| `APHIS-AVS-CORE-403` | Hatching Egg Import Certification | `0407` | hatching_eggs | `VS_HATCHING_EGG_CERT` |
| `APHIS-AVS-CORE-404` | Veterinary Biologics Release Notice | `3002`, `3004` | veterinary_biologics | `VS_BIOLOGICS_RELEASE` |
| `APHIS-AVS-CORE-405` | Companion Animal Vaccination Record | `0106` | companion_animals | `VS_VACCINATION_RECORD` |
 
All obligations have `originCountries: ["*"]` (applicable to all origin countries) unless noted otherwise. All AAC, APQ, and AVS obligations are ACTIVE. Effective date for all: 2024-12-01.
 
## Source Data
 
Source data files live in `data/sources/aphis-core/`:
 
| File | Purpose |
|------|---------|
| `aphis-core-v6.3-obligations.json` | Structured obligation snapshot (20 obligations across 4 authorities) |
| `aphis-core-v6.3-rules.json` | Rule definitions mapping each obligation to a corridor-scoped rule (20 rules) |
| `aphis-core-v6.3-meta.json` | Metadata: source URLs, version, SHA-256 checksums, extraction date, page ranges |
 
The meta file contains SHA-256 checksums for both the obligations and rules files. The ingestion script validates these checksums before writing to the database, ensuring data integrity from source to storage.
 
## Ingestion
 
Run the ingestion script from the repository root:
 
```bash
# Dry-run (validate + print actions, no DB writes)
npx tsx scripts/ingest-aphis-core.ts --dry-run
 
# Full ingestion
npx tsx scripts/ingest-aphis-core.ts
```
 
### CLI Flags
 
| Flag | Description |
|------|-------------|
| `--obligations <path>` | Path to obligation snapshot JSON (default: `data/sources/aphis-core/aphis-core-v6.3-obligations.json`) |
| `--rules <path>` | Path to rule snapshot JSON (default: `data/sources/aphis-core/aphis-core-v6.3-rules.json`) |
| `--meta <path>` | Path to metadata JSON (default: `data/sources/aphis-core/aphis-core-v6.3-meta.json`) |
| `--dry-run` | Validate checksums and structure without writing to the database |
 
### What the Ingestion Script Does
 
1. Reads all three source files (obligations, rules, meta).
2. **Validates checksums**: computes SHA-256 of obligations and rules files, compares against `meta.obligationsSha256` and `meta.rulesSha256`. Fails on mismatch.
3. **Validates structure**: checks for duplicate obligation codes, valid authority codes, valid status values, non-empty source sections, valid effective date ranges.
4. **Validates rules**: checks for duplicate rule codes, valid modules and scope types, and that every rule references a known obligation code.
5. Wraps all writes in `prisma.$transaction()`:
   - Upserts `DataSource` (code: `APHIS`)
   - Upserts `DataRelease` with version and composite checksum
   - For each obligation: computes `contentHash`, upserts `ComplianceObligation`, creates `DataChangeLog` entry
   - For each rule: builds conditions from obligation HS prefixes/categories, builds flag actions, upserts `RuleDefinition`, creates `DataChangeLog` entry
 
## Rule Engine Evaluation
 
When `POST /api/compliance/check` is called with a US destination, APHIS obligations are evaluated through a dual-path system:
 
### Path 1: Rules Engine (Primary)
 
1. Load all `RuleDefinition` records for the `trade` module.
2. Call `compileRulesForContext()` with the origin and destination countries to filter corridor-scoped rules.
3. Execute compiled rules against the input (HS code, origin, product category) using `RulesExecutor`.
4. Extract obligation codes from matched rule actions (actions with type `flag`, `block`, or `warn` that carry an `obligationCode`).
5. Map matched obligation codes back to `ComplianceObligation` records.
 
### Path 2: Direct Fallback
 
If the rules engine does not match a rule for an obligation, the evaluator falls back to direct field matching:
 
1. **HS prefix match**: Does the input HS code start with any of the obligation's `hsPrefixes`?
2. **Origin country match**: Is the input origin country in the obligation's `originCountries` (or is `originCountries` set to `["*"]`)?
3. **Product category match**: Is the input product category in the obligation's `productCategories`?
4. **Importer bonding match** (if `criteria.importerBondingStatuses` is set): Does the input bonding status match?
 
An obligation matches if ALL conditions pass (AND logic). Empty arrays are treated as "no constraint" (always match).
 
### Match Result
 
Each matched obligation's response indicates which path produced the match:
 
```json
{
  "match": {
    "hsPrefix": "0603",
    "originMatched": true,
    "productCategoryMatched": true,
    "importerBondingMatched": null,
    "matchedBy": "rules_engine",
    "matchedRuleCodes": ["APHIS_CORE_APQ_301"]
  }
}
```
 
## Citation Contract
 
Every obligation result includes a `citation` block providing full traceability:
 
```json
{
  "citation": {
    "source": "APHIS",
    "sourceSection": "PGA v6.3, APQ section, pp. 120-122",
    "releaseId": "<cuid>",
    "contentHash": "<sha256>"
  }
}
```
 
- **`source`**: DataSource code identifying the regulatory body
- **`sourceSection`**: Human-readable reference to the source document section and page range
- **`releaseId`**: DataRelease ID (cuid string) that ingested this version
- **`contentHash`**: SHA-256 of the normalized obligation payload, enabling change detection across releases
Adding Jurisdiction PacksCbsa Csa Pack