# CoreComposite offline engine

CoreComposite changes the length support of supplied drillhole assay values. It computes interval-intersection weighted means, coverage and exact source-row contributions. It does not interpolate gaps, infer geology, estimate resources/reserves, apply economic cutoffs or certify reporting. Example files are synthetic.

Run with Python 3.12 standard library:

```sh
python3 product.py samples/valid.json output
bash SMOKE.sh
```

The CLI writes `report.json` and, for PASS or UNKNOWN, deterministic `result.zip`. Exit 0 means PASS computation, 2 means invalid input/output failure, and 3 means UNKNOWN observations. Invalid input removes a prior result.zip in the chosen output directory so an old success is not mistaken for the new result. Output basenames are fixed, atomically replaced, and symlink outputs are refused.

## Exact input schema

A payload is an object containing `assays` and `settings`, plus optional `_note` text. Unknown fields are refused.

`assays` is a nonempty list. Each row has exactly:

| Field | Type and meaning |
|---|---|
| hole_id | Nonempty text, at most 128 characters. No filename or code meaning. |
| from | Finite numeric depth, strictly less than `to`. |
| to | Finite numeric depth. Intervals are half-open `[from,to)`. |
| value | Finite number, numeric text, null, declared missing code, or explicitly handled censored token. Booleans are refused. |

Rows may be unordered; the engine sorts by hole/depth and rejects every overlap, including small overlaps. Adjacent boundaries are permitted. `source_row` is the zero-based original input row, so reordering preserves numerical results while lineage row numbers correctly change. Negative measured values are not clamped or interpreted.

All of these settings are required:

| Field | Supported values |
|---|---|
| units | `m`, `cm`, `mm`, or `ft`; every depth, boundary and target length shares this unit. No automatic conversion. |
| target_length | Finite positive number. Must fit bin and floating-point precision limits. |
| min_coverage | Finite number between 0 and 1. Flags low coverage; never discards or zero-fills observed values. |
| residual_policy | `keep`, `drop`, or `merge_last`, defined below. |
| censor_policy | `error`, `drop`, `half`, or `limit`, defined below. |
| missing_codes | Explicit list of exact string tokens, e.g. `["", "NA"]`. Null is always missing. |

Optional `boundaries` maps hole IDs to lists of finite hard-boundary depths. Unknown hole IDs are refused; duplicates are collapsed and depths outside the observed hole extent have no effect. Bins restart at each selected boundary. Optional `element` and `value_units` are labels of at most 64 characters; one value channel is processed per payload. Multiple holes are supported directly. Independent elements or periods must use distinct payloads through the parent's batch wrapper; this file does not claim that wrapper is installed.

## Policies and arithmetic

For every source/bin intersection, weight is `max(0, min(source_to,bin_to)-max(source_from,bin_from))`. The mean uses only valid contributing length: `sum(weight*value)/sum(valid weight)`. Coverage is valid length divided by actual bin length, including a residual bin's actual length. Thus `[0,1) at 2` and `[1,3) at 5` yield 4. A gap between `[0,1) at 2` and `[2,3) at 8` yields observed mean 5 and coverage 2/3, with overall UNKNOWN.

Any source gap or missing/dropped-censored observation makes the overall result UNKNOWN, even when some bins have full coverage. Known-only composite, contributor, coverage and exclusion tables remain available. No-observation bins appear in coverage.csv without a fabricated composite value. Observed zero is a valid numeric result.

Residual policies apply separately inside each hard-boundary segment:

- `keep`: keep the short final bin.
- `drop`: exclude the short final segment and record its exact source intersections and values. A segment shorter than one target length is entirely excluded. If all observations are known, this deliberate empty composite output is PASS with useful exclusions.
- `merge_last`: extend the last full bin to the segment end. A singleton short segment is kept as one short bin. Never merge across a hard boundary.

Censored tokens are `<number` or `>number`. `error` refuses them. `drop` makes the interval missing and the result UNKNOWN. `half` substitutes half the limit only for `<nonnegative_limit`; `>half` and negative-half limits are refused. `limit` substitutes the declared boundary value for either direction. Substitution is a named processing assumption, never a recovered measurement. Provenance records the policy, and the report explicitly identifies substituted values.

The engine uses binary64 interval arithmetic and `math.fsum`, not symbolic arithmetic. It permits only representable finite results; overflow is FAIL. Near-integer bin ratios within a few machine units of rounding error are treated as full bins. No fixed absolute depth tolerance erases small valid intervals. The reported integral identity is input known/substituted integral = output contributions + declared residual exclusions; missing/gap integrals are unknown and excluded from that numeric reconciliation.

## Actual local files

`files_to_payload(files)` accepts `input.json` alone, or `assays.csv` plus `settings.json`, with optional `boundaries.csv`. Each value is exactly `{encoding:"utf8"|"base64", content: string}`. Base64 must decode to UTF-8. Names are documented basenames only; paths and ambiguous combinations are refused. No file is opened or executed by this API.

`assays.csv` has exactly the header `hole_id,from,to,value`, in that order. `boundaries.csv` has exactly `hole_id,depth`. Standard CSV quoting is supported; duplicate/extra headers and ragged rows are refused. A boundary CSV cannot be combined with nonempty settings boundaries. `samples/file-input/` contains real CSV/settings files matching samples/valid.json. Optional boundary example: `samples/boundaries.csv` (for the DEMO1 hole).

Strict JSON refuses duplicate keys, NaN/Infinity, nonfinite exponents, malformed text and excessive recursion. `run_json(text)` always returns a JSON report with finite values for supported input/error forms.

## Bounds

Input is limited to 8 MiB UTF-8, 10,000 rows, 1,000 holes, 10,000 hard boundaries, 20,000 bins total, 100,000 overlap/contributor visits, depth 12, 200,000 tree nodes, and 2,048 characters per general string. Hole IDs and labels have the tighter limits above. File-set bytes are counted together. Source intervals are sorted, then each hole uses a forward overlap cursor; requested bin counts are checked before allocation. Tiny target lengths fail promptly rather than entering an unbounded loop. Input magnitude may need rescaling when finite values would overflow products or depth differences.

## Package and viewer

The ZIP contains report.json, input.json, policy.json, composites.csv, contributors.csv, coverage.csv, excluded-intervals.csv, README.txt, source-hashes.json, manifest.json, viewer.html and styles.css. Excluded numeric rows use exact excluded endpoints and lengths; gap/missing rows have no invented value. Every manifest digest is computed from actual file bytes. ZIP timestamps/order are fixed; identical input produces identical bytes on the same Python/zlib implementation.

CSV text that could begin a spreadsheet formula is prefixed with an apostrophe; numeric negatives remain numeric. The viewer is escaped static HTML/SVG with no scripts or executable user data. It reuses the canonical feeds stylesheet's semantic tokens and shell classes. The remote font face was removed for offline operation: Satoshi is used only if available locally; otherwise the existing system-font fallback applies. No font redistribution/license claim is made. All useful exact values remain in text tables beside the diagram.

Source brand references: `/home/gmullins/code/usta-paid-surfaces/BRAND.md` and archived v1.3 guide. Strict static brand checks are separate from actual responsive, keyboard and contrast rendering. Those browser acceptance checks belong to the later integration/conversion pass and remain UNKNOWN here. The engine's local test pass does not authorize public publication.

Native Astra recovered and repaired the generated engine after the managed Claude run stopped. Original managed phase verdicts remain unchanged; neither completed Opus authorship nor full harness success is claimed. LANDING copy and publication are parent-owned.