Welllog Traceability and Known-Result Audit

Why this exists

Well-log outcomes can drift when formulas, defaults, or dependencies change. This workflow prevents silent drift by:

1. Storing stage-level trace signatures in processing outputs and DB records.
2. Running a deterministic known-result audit against a fixed LAS fixture.
3. Producing machine-readable and human-readable audit reports.

How traceability works

Each stage now emits traceability:

1. stage: normalize, interpret, or classify.
2. processing_version: version tag for formula/runtime policy.
3. algorithm_references: plain-language method list used in that stage.
4. config: exact knobs used by stage (cutoffs/formulas/etc.).
5. config_hash: stable hash of stage config.
6. output_signature: stable hash of deterministic stage output summary.
7. Upstream linkage:

• interpret includes upstream_normalize_signature
• classify includes upstream_interpret_signature

This allows rapid drift localization:

1. config hash changed -> configuration drift.
2. config hash same, output signature changed -> code/dependency drift.
3. upstream signature changed -> drift originated in previous stage.

Database trace columns

Trace JSON is persisted in:

1. ops.well_logs.traceability
2. ops.well_interpretations.traceability
3. ops.well_bypassed_candidates.traceability

The status-pack API returns these records so UI and operators can inspect provenance directly.

Known-result audit mechanism

Deterministic fixture:

1. Input LAS: tests/fixtures/welllog/legacy17.las
2. Expected snapshot: tests/fixtures/welllog/legacy17_expected.json

Audit runner:

make run-welllog-known-result-audit

Outputs:

1. JSON report: docs/operations/WELLLOG_KNOWN_RESULT_AUDIT_REPORT.json
2. Markdown report: docs/operations/WELLLOG_KNOWN_RESULT_AUDIT_REPORT.md

Pass criteria:

1. mismatch count = 0
2. all numeric checks within tolerance (1e-6)

If the model intentionally changes:

python3 scripts/dev/run_welllog_known_result_audit.py --refresh-expected

Then review and commit:

1. expected fixture update
2. rationale in docs/CHANGELOG.md
3. formula/policy update in architecture docs

Test gates

1. Unit golden snapshot test:

• tests/unit/test_welllog_known_results.py

1. Existing functional welllog tests:

• tests/unit/test_welllog_core.py

1. Migration chain integrity:

• tests/integration/test_migration_chain.py

Formula trace references (implemented)

1. Minimum curvature TVD conversion for deviation stations.
2. Vsh from normalized GR baseline.
3. PHIE from RHOB/NPHI with shale correction.
4. Deterministic cutoff mask and interval segmentation.
5. Optional Archie Sw only when parameters are supplied.

These formulas are implemented in:

libs/py/welllog_core/__init__.py.