# CoreComposite: file and automation reference

This technical reference describes actual local interfaces. It is not a claim of a hosted API, vendor connector or additional paid calculation. The free tool and the fixed-version kit use the same engine.

## Inputs

- assays.csv + settings.json + optional boundaries.csv
- input.json alone

| File | Format | Sample columns |
|---|---|---|
| `assays.csv` | CSV | `hole_id`, `from`, `to`, `value` |
| `settings.json` | JSON |  |

The actual files in `samples/file-input/` are synthetic fixtures. Optional file schemas and every semantic constraint are in the [engine README](README.md). Exact JSON structure is in the product schema and README. A filename is an exact basename, never a disk path passed to the engine API.

## CLI and Python

Run from an extracted trusted kit directory using Python 3.12 or newer. TileMosaic also requires the versions in `requirements.txt`.

```sh
python3 product.py samples/valid.json output-001
```

```python
import json
from pathlib import Path
import product
payload = json.loads(Path("samples/valid.json").read_text())
report = product.run(payload)
if report["status"] != "FAIL":
    Path("result-api.zip").write_bytes(product.bundle(payload))
print(report["status"])
```

For real files, use the common `run_files.py` example: it encodes PNG/STDF bytes with base64, passes text as UTF-8, and calls `files_to_payload` before the same `run`/`bundle` functions. These are local Python functions, not HTTP endpoints. Call `run_json(text)` for strict JSON parsing; duplicate keys and nonfinite numbers are refused.

## Batch folders and exact column profile

Each immediate subdirectory of `jobs/` is one independent engine payload. Copy all required files into that folder. Use `input.json` for a multi-period RoyaltyWaterfall history or an explicitly ordered multi-file TestLotReplay history; splitting those dependent histories into independent folders does not carry state.

```sh
mkdir -p jobs/example
cp samples/file-input/* jobs/example/
python3 batch.py jobs results-001
```

A profile maps destination header to source header. This complete example corresponds to the sample CSV files with every header renamed to `export_...`; normal sample headers need no profile.

```json
{
  "assays.csv": {
    "hole_id": "export_hole_id",
    "from": "export_from",
    "to": "export_to",
    "value": "export_value"
  }
}
```

Save the profile as `columns.json` outside the job folder, then run `python3 batch.py jobs results-002 --profile columns.json`. For PNG/STDF/JSON-only inputs the profile is `{}` and can be omitted. Profiles rename columns only: no unit, currency, timestamp or value conversion. Destination order is significant for strict CSV readers. The outer runner deliberately projects only mapped columns; retain and review the original export. Missing/duplicate headers, ragged rows and nonunique mapped source columns fail. Engine-specific validation still runs after mapping.

## Result file schema observed by executable example

Columns and JSON keys observed in the synthetic PASS fixture; variable recipient, source, pyramid and map filenames depend on input. Read README.md for UNKNOWN omissions and semantic rules.

| ZIP member | CSV columns or observed JSON keys |
|---|---|
| `README.txt` |  |
| `composites.csv` | `hole_id`, `bin`, `from`, `to`, `length`, `composite_value`, `coverage`, `low_coverage`, `n_contributors` |
| `contributors.csv` | `hole_id`, `bin`, `source_row`, `weight`, `value`, `contribution` |
| `coverage.csv` | `hole_id`, `bin`, `from`, `to`, `length`, `covered_length`, `coverage` |
| `excluded-intervals.csv` | `hole_id`, `source_row`, `from`, `to`, `excluded_length`, `value`, `reason` |
| `input.json` | `assays`, `settings` |
| `manifest.json` | `files`, `status`, `version` |
| `policy.json` | `boundaries`, `censor_policy`, `min_coverage`, `missing_codes`, `residual_policy`, `target_length`, `units` |
| `report.json` | `findings`, `provenance`, `status`, `summary`, `tables` |
| `source-hashes.json` | `README.txt`, `composites.csv`, `contributors.csv`, `coverage.csv`, `excluded-intervals.csv`, `input.json`, `policy.json`, `report.json`, `styles.css`, `viewer.html` |
| `styles.css` |  |
| `viewer.html` |  |

CSV text that could execute as a spreadsheet formula is neutralized; original JSON preserves exact text. Read report status and the relevant coverage/completeness fields before importing numeric rows. UNKNOWN is an unobserved result, not zero. PASS is computation under declared inputs and policies, not a professional conclusion.

## Supported handoffs

- **Buyer-owned assay table → CoreComposite** (CSV + JSON): Map hole ID, interval endpoints and one value column; declare unit, hard boundaries and residual/missing/censor policies. Supported local file boundary only; upstream export and downstream product compatibility require buyer validation.
- **composites.csv + contributors.csv + coverage.csv → Buyer-owned modeling preparation** (CSV): Join on exact hole and interval keys after coverage review. Preserve contributor/exclusion files; no geology-suite database writer is supplied. Supported local file boundary only; upstream export and downstream product compatibility require buyer validation.

## Scope boundaries

- One value channel per payload; multiple holes supported; separate elements use separate jobs.
- All depths share the declared m/cm/mm/ft unit; no automatic conversion. Overlapping source intervals fail.
- Missing observations and gaps remain UNKNOWN. No interpolation, resource estimate, geological inference or reporting certification.

## Replay evidence

Engine SHA256: `2bc3ef9115e807ab69a721a1bfa42c43a4fbe07fb45b9bb815c4232fd9af9c2b`.

The documentation builder ran the actual synthetic file set and reopened its result archive. This verifies the local format example, not customer file compatibility, deployment, demand or financial return. Same-version bytes can be compared in one pinned environment; Python/zlib or TileMosaic dependency upgrades can change archive bytes.

See the [common automation reference](../integrations.md) for scheduling, CI and batch receipt semantics.