BuildShelf

Four safe workflow boundaries

Practical implementation notes with actual local output. All inputs are fictional test fixtures, not customer results. Prepared with AI assistance and checked against the implementation and recorded tests. These are developer source kits, not hosted services.

Validate CSV before it reaches a database

Define required headers and map each input column explicitly. Normalize types before validation; preserve source row numbers in errors without repeating customer values. A parser accepting a file does not prove that its records are safe to import.

Reproduce and inspect

Run the included valid.csv with python3 -m csvmini examples/valid.csv --config examples/config.json --output ./output. Inspect report.json counts, errors.csv and valid.jsonl before handing data to another system.

Actual local test output — synthetic fixtures
csv-mini-valid
{"format": "csv", "invalid_rows": 0, "output": "valid.jsonl", "source_sha256": "e977bccc8502aba363f775fc009a16ae4f6d03db805f873d10af342c39e3b5b4", "status": "valid", "valid_rows": 2}

Scope before purchase

Python CLI source, not a hosted app or spreadsheet editor. Mini handles CSV only: no XLSX, database staging or rollback. The $79 full kit adds restricted XLSX and a SQLite import lifecycle.

Read the existing engineering guide

Review deliverables and requirements ($9)

Stage, inspect and roll back an import

Separate accepting a file from committing records. Stage into an isolated run, inspect normalized rows, and promote atomically only when validation succeeds. Keep an audit trail and test repeat promotion so retries do not create duplicate writes.

Reproduce and inspect

Using a temporary database, run importkit stage, preview, promote, repeat promote, audit and rollback. The actual output below was generated in this order. The generic target table is not an integration into your production ERP.

Actual local test output — synthetic fixtures
csv-full-stage
{"config_hash": "4deb0835aad3680da8a4ee695d5440e6f7f2330a03a7fe6898afbffbbad7c651", "created": "2026-10-16T23:46:12.247Z", "dataset": "example_inventory", "id": "b26c646d9227053ea1d1d0bed56d13bd5bed9972afdfe79e21acd0f30d12667f", "invalid": 0, "skipped": 0, "source_hash": "e977bccc8502aba363f775fc009a16ae4f6d03db805f873d10af342c39e3b5b4", "status": "ready", "total": 2, "valid": 2}


csv-full-preview
[{"data": "{\"active\":true,\"available\":\"2026-10-07\",\"category\":\"hardware\",\"price\":\"19.95\",\"quantity\":12,\"sku\":\"SKU-001\"}", "disposition": "valid", "errors": "[]", "row_hash": "7614f95ca6095da2c8624894fef3da0fb2be553cf843f892db349e155f4133b8", "row_no": 2}, {"data": "{\"active\":false,\"available\":\"2024-02-29\",\"category\":\"software\",\"price\":\"0.1\",\"quantity\":0,\"sku\":\"SKU-002\"}", "disposition": "valid", "errors": "[]", "row_hash": "f21b464b21cb996c20d0977de92719e1b597ed568d4706f8d10355fa1e7c8b59", "row_no": 3}]


csv-full-promote
{"config_hash": "4deb0835aad3680da8a4ee695d5440e6f7f2330a03a7fe6898afbffbbad7c651", "created": "2026-10-16T23:46:12.247Z", "dataset": "example_inventory", "id": "b26c646d9227053ea1d1d0bed56d13bd5bed9972afdfe79e21acd0f30d12667f", "invalid": 0, "skipped": 0, "source_hash": "e977bccc8502aba363f775fc009a16ae4f6d03db805f873d10af342c39e3b5b4", "status": "promoted", "total": 2, "valid": 2}


csv-full-promote
{"config_hash": "4deb0835aad3680da8a4ee695d5440e6f7f2330a03a7fe6898afbffbbad7c651", "created": "2026-10-16T23:46:12.247Z", "dataset": "example_inventory", "id": "b26c646d9227053ea1d1d0bed56d13bd5bed9972afdfe79e21acd0f30d12667f", "invalid": 0, "skipped": 0, "source_hash": "e977bccc8502aba363f775fc009a16ae4f6d03db805f873d10af342c39e3b5b4", "status": "promoted", "total": 2, "valid": 2}


csv-full-audit
[{"at": "2026-10-16T23:46:12.247Z", "detail": "{}", "event": "run_created", "sequence": 1}, {"at": "2026-10-16T23:46:12.248Z", "detail": "{}", "event": "stage_attempt", "sequence": 2}, {"at": "2026-10-16T23:46:12.251Z", "detail": "{\"invalid\":0,\"skipped\":0,\"total\":2,\"valid\":2}", "event": "staged", "sequence": 3}, {"at": "2026-10-16T23:46:12.322Z", "detail": "{\"concurrent_skipped\":0,\"inserted\":2}", "event": "promoted", "sequence": 4}, {"at": "2026-10-16T23:46:12.360Z", "detail": "{}", "event": "promotion_noop", "sequence": 5}]


csv-full-rollback
{"config_hash": "4deb0835aad3680da8a4ee695d5440e6f7f2330a03a7fe6898afbffbbad7c651", "created": "2026-10-16T23:46:12.247Z", "dataset": "example_inventory", "id": "b26c646d9227053ea1d1d0bed56d13bd5bed9972afdfe79e21acd0f30d12667f", "invalid": 0, "skipped": 0, "source_hash": "e977bccc8502aba363f775fc009a16ae4f6d03db805f873d10af342c39e3b5b4", "status": "rolled_back", "total": 2, "valid": 2}

Scope before purchase

Python source kit with restricted XLSX support. Formula, macro and merged-cell workflows are not promised. Requires configuration and application integration; it is not a finished web UI.

Read the existing engineering guide

Review deliverables and requirements ($79)

A failed fetch is not an unchanged document

Keep the last successful content fingerprint. Compare a successful normalized extraction against it; a timeout or parse failure must not overwrite that baseline or be reported as unchanged. Obtain permission to fetch and honor robots and rate limits.

Reproduce and inspect

Run node examples/offline_demo.js from the kit. The included injected responses exercise initial, unchanged and changed states without requesting a live website. Schedule real checks outside the CLI with an appropriate interval and backoff.

Actual local test output — synthetic fixtures
website-mini-offline
{"status":"initial","id":"synthetic_page","sha256":"3d22b028153ee68d1e4813b555deab06aa0e27c111d70ac06b5f55b647b8bcf4"}
{"status":"unchanged","id":"synthetic_page","sha256":"3d22b028153ee68d1e4813b555deab06aa0e27c111d70ac06b5f55b647b8bcf4"}
{"status":"changed","id":"synthetic_page","sha256":"5809b6513ea8c6a6fabeb3189ecd70506ecbe2ea54190941e2b9b734ffa9b094"}

Scope before purchase

Node.js CLI source; last-success change detection, not a history archive. No OCR, browser rendering, rich diff, evidence ZIP, built-in scheduler or alerts. Node 22.13+ is documented; this run used local Node 25, not Windows/Linux certification.

Review deliverables and requirements ($15)

Accept duplicates without repeating business work

Verify the signature on original request bytes before parsing. Record the provider event identity durably. A duplicate receipt must not imply another side effect. Retry transient handler failures with bounded backoff and isolate exhausted work for review.

Reproduce and inspect

The local tests below cover durable duplicate/conflict receipts, retry backoff and dead-letter handling, and exact replay history. They use synthetic events and temporary SQLite storage; no real provider event or customer payment was sent.

Actual local test output — synthetic fixtures
webhook-durable-duplicate-retry-replay
test_raw_receipt_duplicate_conflict_durable (tests.test_core.Ledger.test_raw_receipt_duplicate_conflict_durable) ... ok
test_retry_backoff_dlq_and_partial_rollback (tests.test_core.Ledger.test_retry_backoff_dlq_and_partial_rollback) ... ok
test_exact_replay_idempotency_and_history (tests.test_core.Ledger.test_exact_replay_idempotency_and_history) ... ok

----------------------------------------------------------------------
Ran 3 tests in 0.028s

OK

Scope before purchase

Python/SQLite source kit requiring endpoint deployment and application-specific handlers. The $9 signature Mini does not include the full retry/replay workflow. These tests are not a guarantee of your third-party integration.

Read the existing engineering guide

Review deliverables and requirements ($79)