SALT-MAP Lite

SALT-MAP Lite is a local-first CSV consistency triage tool.

It scans CSV files for suspicious table states, groups low-level findings into root-cause trees, and generates:

• Markdown reports for humans
• JSON full trees for machines, AI tools, and data pipelines

Current positioning:

Local-first CSV consistency triage before lookup, join, reporting, or AI ingestion.

Quick Try With Your Own CSV

SALT-MAP Lite v0.2 runs locally. Your CSV is not uploaded to a cloud service.

Windows PowerShell

git clone https://github.com/Void-Ghost000/salt-map-lite.git
cd .\salt-map-lite

py -m venv .venv
.\.venv\Scripts\Activate.ps1

python -m pip install -r requirements.txt

.\scripts\run_user_csv.ps1 `
    -InputPath .\sample_data\bad_employee_lookup.csv `
    -IntegrityMode warn

To analyze your own CSV:

.\scripts\run_user_csv.ps1 `
    -InputPath "C:\path\to\your_file.csv" `
    -IntegrityMode warn

Reports are generated in:

outputs/

Each CSV produces:

• <name>_v02_report.md for human review
• <name>_v02_report.json for machines, AI tools, or data pipelines

Status

Current version: v0.2.0-alpha.1

Engineering status:

• v0.0 flat CSV report: PASS
• v0.1 root-cause tree report: PASS
• v0.1a structural polish: PASS
• v0.1a BYO CSV drop-in demo: PASS
• v0.2 semantic profile and hashing foundation: PASS
• v0.2 profile-aware evidence reports: PASS
• v0.2 stable finding and group IDs: PASS
• v0.2 deterministic integrity gate: STRICT PASS
• v0.2 PowerShell runner and release documentation: PASS
• v0.2 controlled local test suite: 40 passed

What problem does it target?

Many spreadsheet and CSV failures are not loud formula errors.

They are silent data inconsistencies:

• 00123 versus 123
• EMP-001 versus EMP-001
• numbers stored as text
• dirty whitespace
• duplicated normalized keys
• missing values
• #N/A or #VALUE! values
• numeric outliers
• suspicious magnitude shifts
• simple total mismatches

Humans may visually tolerate these differences.

Lookup, join, deduplication, reporting pipelines, and AI ingestion often do not.

Quick demo with sample data

Run:

.\scripts\run_demo.ps1

This generates sample reports in:

reports/

Try your own CSV

Put one or more .csv files into:

input/

Then run:

.\scripts\run_user_csv.ps1 `
    -IntegrityMode warn

Run one specific file:

.\scripts\run_user_csv.ps1 `
    -InputPath .\input\your_file.csv `
    -IntegrityMode warn

Run with an explicit semantic profile:

.\scripts\run_user_csv.ps1 `
    -InputPath .\input\your_file.csv `
    -ProfilePath .\profiles\lookup_join.json `
    -IntegrityMode enforce

Integrity modes:

• off: no integrity manifest
• warn: retain formal reports and emit diagnostics on integrity failure
• enforce: reject formal reports and emit diagnostics on integrity failure

Manual usage

v0.2 profile-aware evidence report:

python .\salt_map_lite_v02.py `
    .\sample_data\bad_employee_lookup.csv `
    --profile .\profiles\lookup_join.json `
    --integrity-mode warn `
    --out .\reports\v02_report.md `
    --json-out .\reports\v02_report.json

Cross-platform shell example:

python salt_map_lite_v02.py \
  ./your_file.csv \
  --integrity-mode warn \
  --out ./outputs/report.md \
  --json-out ./outputs/report.json

Legacy v0.1a root-cause tree report:

python .\salt_map_lite_tree.py `
    .\sample_data\bad_employee_lookup.csv `
    --out .\reports\bad_employee_lookup_tree_report.md `
    --json-out .\reports\bad_employee_lookup_tree_report.json

Legacy v0.0 flat report:

python .\salt_map_lite.py `
    .\sample_data\bad_employee_lookup.csv `
    --out .\reports\bad_employee_lookup_report.md

Report types

Markdown report

The Markdown report is designed for human review.

It includes:

• summary
• root-cause group summary
• collapsible root-cause tree
• child findings
• flat findings appendix
• claim boundary
• missing evidence

JSON full tree

The JSON report is designed for machines, AI tools, and pipelines.

It includes:

• groups
• findings
• state IDs
• raw values
• normalized values
• related rows
• downstream risks
• evidence tier
• machine action hints

Current checks

v0.1a includes built-in checks for:

• missing values
• Excel-style error values
• dirty text
• leading-zero key risk
• normalized duplicate keys
• duplicate key candidates
• column type mixing
• numeric outliers
• magnitude anomalies
• simple domain checks
• simple arithmetic mismatch

Claim boundary

SALT-MAP Lite identifies suspicious rows, cells, columns, values, and grouped root-cause risks.

It does not identify the original user action without before/after files or action logs.

It is a triage map, not final proof.

What it does not do yet

SALT-MAP Lite v0.2 does not currently provide:

• XLSX workbook parsing
• Excel formula recalculation
• Formula dependency graph analysis
• Before/after action attribution
• Automatic repair
• Excel add-in workflow
• Cloud-hosted processing
• Full SALT replay or counterfactual ablation
• Actual runtime append-only event recording

The integrity gate verifies the declared generated manifest and hash-chain consistency.

It does not prove the actual runtime execution path, semantic correctness, original user intent, or causality.

Privacy

SALT-MAP Lite runs locally.

Your CSV stays on your machine unless you choose to share it.

Development

Install dependencies:

pip install -r requirements.txt

Run tests:

python -m pytest -q

Run demo:

.\scripts\run_demo.ps1

Run BYO CSV demo:

.\scripts\run_user_csv.ps1

Project relationship

SALT-MAP Lite is a vertical MVP derived from the SALT / HSRAG-SAIT causal-state mapping direction.

It is not HSRAG core.

License

Apache-2.0

Optional Integrity Gate

SALT-MAP Lite v0.2 supports three integrity modes:

• off: no integrity manifest.
• warn: retain formal reports and emit diagnostics if integrity fails.
• enforce: reject formal reports and emit diagnostics if integrity fails.

Run with warn mode:

.\scripts\run_user_csv.ps1 `
    -InputPath .\sample_data\bad_employee_lookup.csv `
    -IntegrityMode warn

Run with enforce mode and an explicit profile:

.\scripts\run_user_csv.ps1 `
    -InputPath .\sample_data\bad_employee_lookup.csv `
    -ProfilePath .\profiles\lookup_join.json `
    -IntegrityMode enforce

The integrity chain verifies the declared generated manifest and hash-chain consistency.

It does not prove the actual runtime execution path, semantic correctness, or causality.

See docs/integrity_gate.md for the exact mode and claim contract.