# 1. Repair decision **Decision: CROSS-LAYER CSV IMPORT CONTRACT DRIFT FOUND — SAFE LOCAL PATCH AVAILABLE; production files and records remain unverified.** Preview and execution use different parsing, mapping, locale, batch, and success rules. # 2. Scope and boundary **Reviewed:** routes, parsers, schemas, services, BullMQ workers, Prisma repositories, exporters, tests, fixtures, docs, and runbook. **Not accessed:** production files, customer data, PostgreSQL, queues, storage, or deployed imports. # 3. Import contract source register | Source | Current behavior | Status | |---|---|---| | preview parser | duplicate headers accepted | Ambiguous | | preview mapping | column position | Drift | | worker mapping | header name | Drift | | delimiter handling | comma/semicolon differ | Gap | | dates/decimals | server locale | Drift | | preview token | no file/mapping digest | Stale | | worker retry | repeats possible | Idempotency gap | | workspace ID | client value trusted | Scope risk | | error CSV | raw values exported | Formula risk | # 4. Canonical repository contract Duplicate policy, partial-success policy, supported dialects, locale rules, and update behavior are **OWNER DECISION REQUIRED**. Safe structure: - one immutable batch identifies tenant, file digest, parser profile, schema, mapping, and actor; - preview and execution consume the same normalized rows; - headers are normalized once and collisions are explicit; - parsing uses declared formats; - each row has stable identity and one persisted result; - writes are tenant-scoped and idempotent; - totals come from persisted outcomes; - error exports neutralize formulas. # 5. Drift findings ## F1 — Duplicate headers Normalized duplicates can overwrite values. **Repair:** preserve index, detect collisions, and fail before mapping. ## F2 — Preview/execution mismatch Preview binds positions; execution binds names. **Repair:** use one parser-and-mapping pipeline producing a versioned row envelope. Bind preview to file and mapping digests. ## F3 — Encoding and dialect drift BOM and semicolon files behave differently. **Repair:** make encoding, delimiter, quote, escape, and newline rules explicit. Reject unresolved dialects. ## F4 — Locale coercion Server locale can reinterpret dates and decimals. **Repair:** use approved field formats. Preserve raw text beside parsed values and typed errors. ## F5 — Stale confirmation A preview can confirm changed input. **Repair:** match tenant, batch, file digest, parser profile, mapping version, schema version, and expiry. ## F6 — Retry duplicates A retry can repeat completed rows. **Repair:** persist one result per batch and row ID. Retry only unresolved commands. ## F7 — Tenant reference bypass Imported workspace IDs are trusted. **Repair:** resolve references inside the tenant and reject inaccessible IDs without disclosure. ## F8 — False success and unsafe export Partial work can return success, and raw values can become formulas. **Repair:** return batch and row statuses with reconciled counts. Neutralize formula-leading cells. # 6. Safe patch plan | Area | Change | |---|---| | Domain | immutable batch and row result | | Headers | collision and required-column checks | | Parsing | explicit dialect, locale, and formats | | Preview | file and mapping digest binding | | References | tenant-scoped resolution | | Worker | idempotent row commands | | Results | reconciled totals | | Export | formula-safe error CSV | | Tests/docs | malformed, stale, retry cases | No production import, migration, or deployment is included. # 7. Deterministic test matrix 1. Duplicate normalized headers fail before mapping. 2. Preview and execution produce identical rows. 3. BOM does not alter the first header. 4. Semicolon input uses one parser profile. 5. Dates and decimals ignore machine locale. 6. File or mapping changes invalidate confirmation. 7. Foreign workspace IDs are rejected safely. 8. Duplicate delivery does not duplicate records. 9. Retry applies only unresolved rows. 10. Batch totals equal persisted outcomes. 11. Partial work is not complete success. 12. Error CSV cells cannot execute formulas. # 8. Verification steps Run: - `npm test -- csv-import-contract` - `npm test -- import-preview-parity` - `npm test -- import-idempotency` - `npm test -- import-tenant-scope` - `npm test -- import-error-export` - `npm run typecheck` - `npm run lint` - `npm run build` Search for split mapping paths, implicit locale parsing, confirmation without digests, unconditional inserts, client tenant references, and raw exports. # 9. Production boundary Unknown: historical batches, duplicates, old previews, queued retries, direct scripts, legacy dialects, cleanup, and production constraints. Production work needs separate profiling, migration, reconciliation, rollout, monitoring, and rollback. # 10. Human approval request **Safe now:** shared parsing, header checks, digest-bound previews, tenant-scoped references, idempotent rows, truthful totals, safe exports, tests, and docs. **Decisions required:** dialects, date and decimal formats, duplicate policy, partial-success behavior, create/update rules, legacy compatibility, and rollout. **Status: PATCH READY FOR LOCAL REVIEW — PRODUCTION FILES, HISTORICAL DUPLICATES, QUEUED BATCHES, LEGACY DIALECTS, AND DEPLOYED RESULTS NOT VERIFIED** # 11. Suggested commit message `fix(imports): align CSV preview, execution, and retries`