CSV Foreign-Key Import Gate

Private Apify Actor that audits up to five related inline CSV tables before import. It quarantines every duplicate primary-key member, empty required/key row, orphan, and descendant of an invalid parent. It never edits source values or invents replacements.

Use

Provide tables and foreignKeys as in examples/input.json. Names and headers are safe identifiers; values are exact case-sensitive UTF-8 text. There is no trimming, case folding, numeric guessing, URL fetch, database access, AI, browser, proxy, or external enrichment. A completed audit returns PASS or QUARANTINED; quarantine is a useful business result, not an Actor failure.

The default dataset contains exactly one authoritative summary and no raw cells. OUTPUT, REPORT.JSON, REPORT.MD, MANIFEST.JSON, and ACCEPTED_FILES.JSON are in the default key-value store. ACCEPTED_FILES.JSON maps each table to a fixed uppercase, collision-resistant record key such as ACCEPTED_DEPARTMENTS_<8_HEX>.CSV. Download a table from:

https://api.apify.com/v2/key-value-stores/{STORE_ID}/records/{RECORD_KEY}

Accepted CSV files necessarily contain customer values. Keep the Actor private, restrict storage access, and configure/deal with Apify retention according to your policy. Reports and the dataset expose coordinates, codes, counts and hashes—not raw cells or per-cell hashes.

Exact behavior

• BOM, quoted commas, multiline fields, CRLF, composite keys and valid FK cycles are supported through csv-parse 7.0.3.
• Empty means the exact empty string. A nullable composite FK may be entirely empty; a partially empty tuple is quarantined.
• Duplicate PK tuples quarantine all members. Descendant quarantine propagates to a fixed point. Mutually valid cycles remain accepted and are flagged.
• Leading zeros, whitespace, row order and cell text are preserved. CSV quoting/newlines may be canonically re-encoded without changing parsed values.
• Before spreadsheet export, cells beginning (after leading control/whitespace) with =, +, or @ are quarantined. - is quarantined unless the remainder is a conservative decimal/scientific numeric form; exact values such as -12.5 remain unchanged.
• Cycles may require deferred constraints or a database-specific import order. This tool does not promise general SQL readiness or compatibility with database types, checks, triggers, locale, or collation.

Limits: 2 MiB JSON input, 1–5 tables, 5000 total data rows, 64 columns/table, 16 KiB/cell, and 20 foreign keys. References may target only the declared parent primary key in exact order. Unknown fields, unsafe/prototype identifiers, duplicate headers/names, malformed CSV and recognized credentials/private keys are rejected without echoing CSV.

CI and local development

Submit the same bounded input on each release and use status, hashes, counts, and stable issue codes as the gate. Future automation can retrieve OUTPUT, verify MANIFEST.JSON, and import only keys listed by ACCEPTED_FILES.JSON; it must still apply database-specific validation.

npm ci --ignore-scripts
npm test
npm run typecheck
npm run build

No-input local production startup with CRAWLEE_STORAGE_DIR writes INVALID_INPUT to OUTPUT and no dataset. AUTOMATON_CONTAINER_SMOKE=1 runs only an embedded deterministic no-network analysis.