equiframe 0.12.4__py3-none-any.whl

equiframe/docs/contributing.md

@@ -0,0 +1,171 @@
+# Contributing to EquiFrame
+
+[Handbook](index.md) · [Compatibility](compatibility.md) · [Release process](releasing.md)
+
+The 0.12.4 release contract uses MIT for project-owned code; third-party materials
+retain their notices and licenses. Redistribution rights follow those licenses.
+Hernán Troya (`htroya`) maintains the project and owns releases/security
+coordination on a best-effort basis without a promised backup or response-time SLA.
+
+The public repository contains the library source, user documentation and tests.
+Open a nonsensitive issue or contribute a focused patch using your own account.
+Never include credentials, private datasets, models or execution results.
+The benchmark remains a separate package in this repository.
+
+The owner has authorized manual TestPyPI/PyPI preparation and publication subject
+to the [release gates](releasing.md). This is not permission for a contributor or
+an ordinary CI run to publish. Historical private candidate notes retain their
+original versions and outcomes.
+
+## Boundaries to preserve
+
+- Read the API, compatibility and semantic-contract guides before a change
+- Preserve Decimal, currency, keys, multiplicity, NULL/NaN and temporal distinctions
+  according to contract; never normalize differences just to pass a test
+- Keep R, M, B, H and O independent. Detectors/profiles must not receive labels,
+  mutation definitions or another engine's output. pandas is not an oracle
+- Never map failure, invalid input, missing support or not-estimable output to
+  success or no alert. Test fail-closed behavior, not just the happy path
+- Native engines execute their own implementations; do not compute once and
+  convert the result to simulate independent implementations
+- Core code must not depend on OCI, SERCOP, the experimental package or a specific
+  external service. Use explicit typed ports and trusted registrations
+- Honor component ownership: core/benchmark work does not authorize infrastructure,
+  data-gateway or domain-warehouse redesign
+- Do not execute untrusted callbacks, SQL, plugins or models. The library is not a
+  sandbox. Do not introduce shared DuckDB files with independent process writers
+- Keep credentials, real datasets, private reports, databases, model binaries and
+  environments out of Git. Small identified synthetic fixtures are appropriate
+
+## Reproducible local checks
+
+The commands below describe checks to run; they do not assert this artifact has
+already passed them. Use an authorized source checkout or the identified sdist,
+Python 3.12 and a suitable `uv` installation. Dependency installation may access
+your configured package index unless a reviewed offline cache is supplied.
+From the core package directory:
+
+```bash
+uv sync --locked --all-extras --python 3.12
+uv run --locked --all-extras ruff check .
+uv run --locked --all-extras ruff format --check .
+uv run --locked --all-extras mypy --python-version 3.12
+uv run --locked --all-extras python tools/generate_assets.py --check
+uv run --locked --all-extras pytest -q
+uv run --locked --all-extras python -m build --no-isolation
+uv run --locked --all-extras twine check --strict dist/*.whl dist/*.tar.gz
+uv run --locked --all-extras python tools/verify_distribution.py
+```
+
+The distribution verifier uses isolated installed consumers outside the checkout,
+checks runtime bytes, exercises examples and compares the rebuilt wheel from
+sdist. It is distinct from source tests and from a remote CI job. The first-use
+kit verifier preserves deliberate negative recipe exits; do not turn them into
+unconditional success.
+
+The candidate driver provides a byte-bound aggregate receipt:
+
+```bash
+python tools/check_candidate.py --package . --output /absolute/path/new-checks.json
+```
+
+Every invocation needs a fresh receipt name and matching log/pytest paths. The
+driver refuses existing output evidence before starting checks and reserves its
+receipt exclusively. After a failed or interrupted attempt, keep that output
+and choose another `--output` name for the retry.
+
+The aggregate candidate driver and `release_manifest.py` require a Git checkout
+to bind the complete source tree to a commit. An extracted sdist can run the
+package's lint, types, assets, tests and build checks, but it cannot create that
+Git-bound release receipt by itself. Keep the original source revision and
+artifact receipt from the provider. The benchmark distribution verifier also
+expects the monorepo layout, including the adjacent matching core source and
+built wheel; an isolated benchmark sdist does not supply those inputs.
+
+For the benchmark, work from `packages/equiframe-benchmark`, build the matching
+core wheel first, and run the same lint/type/assets/test/build/Twine/distribution
+sequence after:
+
+```bash
+uv sync --locked --all-extras --reinstall-package equiframe
+```
+
+Reinstallation matters when editing a local unreleased candidate with the same
+version string: dependency caches
+can otherwise retain an old local core. The candidate driver checks runtime
+source hashes and reinstalls local dependencies; installed artifact verification
+still consumes the exact wheels, not an editable checkout.
+Published distribution files remain immutable; a local development reinstall
+does not authorize replacing them.
+
+Changing dependencies requires reviewed lock changes and the relevant
+`tools/verify_compatibility.py` cells. Minimum/recent direct resolutions, platforms,
+extras, corpus, hashes, failures and skips must be recorded accurately. A narrower
+focused test does not replace all affected checks. Never update a compatibility
+fingerprint automatically just to silence a regression.
+
+## Reviewable change procedure
+
+1. Describe the problem, affected contract/capability and evidence of failure
+2. Work on a branch based on the agreed candidate/base; identify dependencies
+   on unmerged changes. Do not assume the candidate is already on main
+3. Implement real behavior with minimal synthetic regression fixtures, including
+   positive, negative, invalid and not-evaluable cases
+4. Update public English usage, reference/limits, schemas and compatibility
+   classification when affected. Record observable changes and migration guidance
+5. Preserve historical fixture bytes and unknown-version rejection. New incompatible
+   writes need a new format, not retrospective reinterpretation
+6. Run affected source and installed-artifact checks against final bytes and retain
+   receipts. Distinguish passed, failed, blocked and unexecuted checks
+7. Request review with scope, rationale, artifacts, test outcomes and known limits.
+   A PR convention is not proof of enforced branch protection or independent approval
+
+Methodological changes require explicit rationale, version and consequences in
+the repository's decision/traceability documents. Do not describe synthetic
+fixtures, untrained models, planned APIs, pending pilots or unexecuted tests as
+scientific evidence or external acceptance.
+
+Public-facing current documentation is English. Historical design and the
+reinforced roadmap can remain Spanish with their original context. Keep the
+installed handbook self-contained; essential instructions must not depend on
+private monorepo links. Run examples against the exact distribution, and label
+signature sketches or consumer-specific request templates as such.
+
+## CI and publishing permissions
+
+The public repository ships no GitHub Actions workflows, and this release uses
+local manual checks. Pushing a branch or creating a PR does not execute or prove
+a compatibility matrix. Identify the actual command, source, environment and
+artifacts before claiming results. Any future hosted CI requires separate review
+and least privilege; publication remains a separate protected owner decision.
+
+Building locally, checking Twine metadata, producing an SBOM or installing by
+local wheel does not publish, reserve a project name or approve licensing.
+Do not upload to PyPI, deploy a service, grant sharing access or activate a remote
+release flow without the specific authorization and completed gates in
+[releasing.md](releasing.md).
+
+## Adoption and maintenance evidence
+
+The [adoption record checker](adoption.md#check-the-structured-record-locally)
+is a developer-only sdist tool. Its exit 0 establishes input consistency, never
+consent, human independence or adoption. Keep the example registry empty and
+real observations outside Git. The [maintenance process](maintenance.md) requires
+minimal permitted reproductions and separate technical/consumer confirmation;
+Hernán Troya (`htroya`) is the confirmed owner; no backup, response deadline or
+SLA is promised.
+
+## Fast source feedback
+
+Use the [quick CI layer](fast-ci.md) for bounded PR/change feedback and the
+`tools/check_architecture.py --check` from the source distribution.
+Its smoke receipt is separate from the full candidate/distribution/matrix checks.
+The installed [product journeys](journeys.md) make positive, different and
+unavailable outcomes reproducible without a source checkout.
+
+Type-check each selected Python with its own resolved dependency/stub set and
+matching `mypy --python-version X.Y`. The aggregate driver observes that version
+after sync and supplies it automatically. The checked-in minimum target remains
+3.10 and strict mode remains enabled; no error codes or imports are suppressed.
+A 3.11+ stub package requiring newer typing syntax is not evidence about the
+3.10 dependency branch. Each branch must pass under its actual interpreter.

equiframe/docs/dependencies.md

@@ -0,0 +1,237 @@
+# Dependency inventory, licenses and advisory evidence
+
+The package metadata declares allowed version ranges; `uv.lock` records exact
+resolutions, including conditional branches for supported environments. Neither
+means that every possible version combination has passed the test matrix.
+Keep the exact Python/platform marker environment with the resolved inventory.
+
+The `pandas` and `engines` extras exclude Pandas 3.0.3–3.0.6. Their upstream
+`ZoneInfo.from_file` regression can ignore the supplied rules and silently alter
+historical timestamps; the correction is documented in
+[Pandas 3.1.0](https://pandas.pydata.org/pandas-docs/version/3.1.0/whatsnew/v3.1.0.html).
+The minimum supported Pandas range remains available on Python 3.10. A changed
+resolved profile requires fresh native evidence; previous 3.0.6 receipts retain
+their actual version and outcome.
+
+Runtime is deliberately separated from optional engines and ML: base contracts,
+models and CLI depend on Pydantic, Typer and tzdata; Arrow and each native engine
+are opt-in; ML is opt-in; the benchmark is a separate distribution. Build and
+validation tools are development dependencies, not required by a normal core
+import. The benchmark's dependency must resolve to the exact core candidate
+wheel supplied with its evidence, not another private wheel with the same
+version string.
+
+TLS trust is also part of the build and advisory-query environment. The
+[Python security notice for the emSign incident](https://discuss.python.org/t/information-for-python-users-regarding-emudhra-emsign-ca-certificate-security-incident/109576)
+requires corrected CA bundles and identifies minimum repaired versions including
+`certifi>=2026.10.19`, `pip>=26.2.2` and `uv>=0.13.4`. The release locks use
+`certifi==2026.10.23`. A standalone tool can embed its own CA bundle, so inspecting
+installed Python distributions alone does not cover `uv` or other native tools.
+Do not disable certificate verification to work around a download failure.
+
+Use a maintained Python security patch release and an updated operating-system
+trust store. The same notice recommends Python 3.13.18 (and corrected releases of
+other maintained branches) as an additional mitigation independent of CA bundles.
+The package's Python compatibility floor is not a claim that an end-of-life
+interpreter still receives upstream security fixes. Updating a QA runtime must
+not silently replace a consumer's system interpreter or certificate store.
+
+The optional `files` profile adds Pandas/Arrow, openpyxl for XLSX/XLSM, xlrd for
+legacy XLS and defusedxml for XML. Imports occur only when a selected operation
+needs that reader; no automatic installation occurs. Target conversion additionally
+uses the existing `polars` or `duckdb` profile. The exact allowed ranges are in
+the [compatibility table](compatibility.md#declared-runtime-dependencies).
+`equiframe doctor --extra files` diagnoses installation metadata without reading
+user data. File discovery, inference and conversion are documented in
+[the file guide](lectura-conversion.md).
+
+The optional [language-R review](r_review.md) uses a user-installed `Rscript`
+and base R. It does not add an R package dependency or install a runtime.
+R's observed version and the reviewer source hash belong to each returned
+review; Python wheel metadata alone cannot identify the external R executable.
+Validation of the 26 October source additions and lock updates is reported
+separately; lock resolution alone does not establish native or semantic behavior.
+
+## Reproducible evidence workflow
+
+The source distribution carries `tools/dependency_inventory.py` and the pinned
+CycloneDX schemas. Run the tool with the locked core development interpreter.
+`generate` is offline: it inspects the selected package, exact wheel and sdist,
+lock profiles and installed metadata. `scan` is explicitly networked, querying
+version-specific PyPI metadata and OSV for registry dependencies. `verify`
+rederives the inventory, validates the artifact bindings and schemas, and checks
+snapshot consistency/freshness. Consult `--help` for exact options.
+
+Run these from the repository root after both packages have been built and their
+locked development environments have been prepared. The following paths use
+POSIX virtual environments; on Windows use the corresponding `Scripts/python.exe`.
+Output directories must be new so an earlier receipt cannot be overwritten.
+
+```sh
+PY=.venv/bin/python
+TOOL=tools/dependency_inventory.py
+CORE=.
+BENCH=packages/equiframe-benchmark
+
+$PY $TOOL generate --package "$CORE" \
+  --artifact "$CORE/dist/equiframe-0.12.4-py3-none-any.whl" \
+  --artifact "$CORE/dist/equiframe-0.12.4.tar.gz" \
+  --output evidence/dependencies/core
+
+$PY $TOOL generate --package "$BENCH" \
+  --artifact "$BENCH/dist/equiframe_benchmark-0.12.4-py3-none-any.whl" \
+  --artifact "$BENCH/dist/equiframe_benchmark-0.12.4.tar.gz" \
+  --environment-python "$BENCH/.venv/bin/python" \
+  --local-artifact "$CORE/dist/equiframe-0.12.4-py3-none-any.whl" \
+  --output evidence/dependencies/benchmark
+```
+
+Each directory contains `inventory.json` (`equiframe.dependencies/1.0`) and two
+`<artifact filename>.cdx.json` files. The BOMs are CycloneDX 1.6, validated against
+the unmodified official draft-07 JSON schemas with pinned SHA-256 and a closed,
+local schema registry. They contain a clearly labelled union of profile closures;
+they do not imply that build/dev dependencies are embedded in, or required by,
+the wheel. Each component lists its profile membership. Only explicitly stated,
+valid SPDX expressions are represented as license expressions; other source
+metadata is retained for review rather than converted to an invented license.
+
+The tool needs `packaging` and `jsonschema` from the existing core development
+lock. It installs nothing and does not add runtime dependencies. It reads
+installed metadata and license files without importing dependency/project code.
+Declared `License-File` members, including names such as `AUTHORS` and legacy
+`mit.LICENSE`, are collected alongside conventional `LICENSE`, `LICENCE`, copying
+and notice files inside the distribution metadata boundary. Paths outside that
+boundary are not followed. Missing files or declarations still require review;
+collecting a file does not establish a compatible license.
+The interpreter selected by `--environment-python` supplies the observed marker
+environment and distribution metadata. Other-platform lock branches are not
+claimed to have been installed or scanned. Missing installed metadata is recorded
+as unknown; exact lock versions are never relabelled as installed when absent.
+
+An advisory refresh requires an inspected public-only allowlist and an offline
+request preview. Create `public-allowlist.json` containing only exact reviewed
+public `name`/`version` objects from the artifact-bound inventory; exclude the
+project, all private consumers/internal packages and any ambiguous provenance.
+A registry label by itself is insufficient. This file and the preview remain
+local; neither the complete inventory nor its metadata is uploaded.
+
+```sh
+$PY $TOOL prepare-scan --inventory evidence/dependencies/core/inventory.json \
+  --public-allowlist public-allowlist.json --output public-requests.json
+# Inspect public-requests.json: URLs, bodies, anonymous headers and exclusions.
+$PY $TOOL scan --inventory evidence/dependencies/core/inventory.json \
+  --public-allowlist public-allowlist.json --request-plan public-requests.json \
+  --output evidence/dependencies/core-advisories
+```
+
+Repeat with the benchmark inventory and its own reviewed allowlist/preview.
+Preparation is offline and proves no provider coverage. Execution rejects a
+changed preview, names absent from the allowlist, private/local sources, extra
+payload fields, URL query/userinfo/insecure destinations and all redirects.
+No project-identifying User-Agent, credentials, cookies or referer is supplied.
+Provider pagination tokens are validated and remain bound to the same query.
+Platform-denied requests must stop; changing a route is not authorization.
+
+`scan` writes `advisories.json` (`equiframe.advisories/1.0`) and one snapshot per
+public package/version/provider. It preserves the exact UTF-8 JSON response,
+its SHA-256, parsed content, request, source URL, time and failures. It queries
+PyPI's release endpoint and OSV, retaining GHSA IDs/advisories supplied through
+those sources. It does not claim an independent direct GitHub Advisory API scan.
+Private/local project packages are explicitly excluded from public name lookups.
+The command exits 0 for complete `no_known_advisories`, 2 for `findings` or
+`unknown`, and 1 for invalid inputs. Failure receipts remain available.
+
+Reverify the final artifact bytes, lock, selected environment, BOMs and audit:
+
+```sh
+$PY $TOOL verify --package "$CORE" \
+  --artifact "$CORE/dist/equiframe-0.12.4-py3-none-any.whl" \
+  --artifact "$CORE/dist/equiframe-0.12.4.tar.gz" \
+  --inventory evidence/dependencies/core/inventory.json \
+  --advisories evidence/dependencies/core-advisories/advisories.json \
+  --max-age-hours 24 --require-clean
+
+$PY $TOOL verify --package "$BENCH" \
+  --artifact "$BENCH/dist/equiframe_benchmark-0.12.4-py3-none-any.whl" \
+  --artifact "$BENCH/dist/equiframe_benchmark-0.12.4.tar.gz" \
+  --environment-python "$BENCH/.venv/bin/python" \
+  --local-artifact "$CORE/dist/equiframe-0.12.4-py3-none-any.whl" \
+  --inventory evidence/dependencies/benchmark/inventory.json \
+  --advisories evidence/dependencies/benchmark-advisories/advisories.json \
+  --max-age-hours 24 --require-clean
+```
+
+For an offline-only verification, omit `--advisories` and `--require-clean`;
+that result establishes no advisory coverage. `--require-clean` always needs a
+complete fresh audit. Freshness defaults to 24 hours; an explicit larger window
+is bounded at 168 hours and must be justified by release policy. Missing snapshots,
+changed hashes, changed local core wheel, stale timestamps, omitted packages,
+inconsistent summaries and changed source declarations fail verification.
+The verifier reconstructs the expected inventory and BOM instead of trusting
+positive fields in a receipt. Receipts are unsigned: consistent total replacement
+of artifacts and evidence is outside their authenticity guarantee.
+
+The evidence distinguishes runtime base, individual extras, all extras, dev and
+build profiles. It records declared requirements, resolved versions, lock and
+artifact hashes, observed dependency metadata and license-file hashes. A
+CycloneDX BOM is tied to each artifact rather than to an unspecified checkout.
+Local project dependencies require an explicit candidate wheel. The schemas
+are retained with source URLs and hashes for offline validation; their upstream
+license notices apply to those schemas, not to EquiFrame.
+
+An installed dependency's license expression, classifiers, free-form metadata
+and files may disagree or be incomplete. Preserve those observations and their
+provenance; do not guess a missing license or treat metadata as legal clearance.
+Native wheels can bundle third-party libraries that are not separate Python
+distributions. The Python dependency inventory is not an exhaustive inventory
+of every bundled native component, the operating system or build infrastructure.
+Redistribution review must inspect the applicable binary notices and conditions.
+
+The optional legacy XLS reader `xlrd==2.0.2` illustrates why a generic `BSD`
+metadata label is insufficient: its [license text](https://github.com/python-excel/xlrd/blob/2.0.2/LICENSE)
+contains both a later three-clause notice and an earlier notice with advertising
+and retained-acknowledgement conditions. Preserve both when redistributing that
+dependency and retain the required acknowledgement:
+
+> This product includes software developed by David Giffin <david@giffin.org>.
+
+SciPy binary notices separately identify OpenBLAS/LAPACK, the GCC runtime with
+its runtime exception, and libquadmath under their respective terms. Docutils
+identifies its public-domain files and separately licensed exceptions. These
+notices must not be replaced by EquiFrame's MIT license or collapsed into a
+guessed single SPDX expression. Normal dependency installation retains upstream
+notices; repackaging dependencies requires a separate review of the actual files.
+
+## Interpreting advisory results
+
+Retain the query time, exact name/version, provider, URL, returned bytes/hash and
+errors. A successful response with no listed advisories means only that the
+provider returned none for that version at that time. Missing releases, blocked
+networks, HTTP errors, incomplete provider coverage, stale or malformed evidence
+are **unknown**, never zero vulnerabilities. A provider identifier is not a
+confirmed exploitability assessment of EquiFrame's usage.
+
+Inspect primary advisory records for affected/fixed ranges, severity and relevant
+runtime paths. Record each correction, justified exception or unresolved result.
+Changing a dependency requires rebuilding the lock/first-use pins as applicable,
+rerunning the affected profiles and full release checks, and regenerating all
+artifact-bound evidence. Do not suppress an advisory merely to obtain a green
+release status. Recheck close to publication; an old snapshot cannot establish
+current safety. `--require-clean` fails closed if coverage is unknown, findings
+remain or the snapshot is stale.
+
+## Release limits
+
+The inventory and advisory scan are separate from source review and the partial
+historical STEP9 assessment. They do not prove publisher identity, grant rights
+over dependencies or establish that the software is secure. EquiFrame's own
+license and bundled notices do not replace third-party redistribution conditions.
+Publication follows the [release decisions and gates](releasing.md), including
+resolution of real findings and explicit treatment of unknown coverage. Bind the
+completed checks to the final four artifact hashes; do not transfer acceptance
+from an earlier wheel, sdist, dependency resolution or source snapshot.
+
+Standards and provider documentation:
+[CycloneDX 1.6](https://cyclonedx.org/docs/1.6/json/),
+[PyPI JSON API](https://docs.pypi.org/api/json/),
+[OSV query API](https://google.github.io/osv.dev/api/)

equiframe/docs/eda.md

@@ -0,0 +1,166 @@
+# Optional standalone dataset EDA
+
+[Handbook](index.md) · [Outcome gates](outcome-gates.md) · [Compatibility](compatibility.md)
+
+Private Alpha **0.12.0a14** introduced `equiframe.eda`; that subpackage remains
+experimental in 0.12.4, separately from the stable comparison/migration interfaces.
+It diagnoses one fixed dataset independently of ETL or a migration. It never
+changes a plan, tolerance, expected output, detector bundle or publication gate.
+Install the identified wheel and its `eda` extra (DuckDB and Arrow),
+or `eda-charts` for portable Plotly HTML. No public PyPI release is implied.
+Imports remain lazy: importing EquiFrame, EDA contracts or CLI does not import
+DuckDB, Arrow, Plotly or the ML engines.
+
+## Python API
+
+```python
+from pathlib import Path
+from equiframe.eda import EdaConfig, NumericRule, Source, analyze, read_result
+
+result = analyze(
+    Source(path="/absolute/input/numbers.parquet", snapshot_id="numbers-v1"),
+    config=EdaConfig(numeric=(NumericRule(column="value", outliers="iqr"),)),
+    output=Path("/absolute/private-runs/numbers-run-001"),
+)
+print(result.state, result.reason)  # Inspect each metric's availability as well.
+checked = read_result(Path("/absolute/private-runs/numbers-run-001"))
+```
+
+Paths above are placeholders, not proof of execution. The supplied synthetic
+example uses real generated CSV, independent expected counts and exact money:
+
+```bash
+python examples/eda_generic.py --work-dir /absolute/new-private-example
+```
+
+The wheel includes `equiframe/examples/integrations/eda_generic.py`; extract
+that resource into a fresh project to run it outside the checkout. Files and
+reports remain private. Use a new work directory every time.
+
+`analyze_artifact(TableArtifact, config=..., output=...)` reuses a captured
+table's SHA/size without making an execution. `analyze_migration(path,
+side="source"|"target", config=..., output=...)` first calls the existing verified
+migration/bundle reader. It resolves only an inventoried captured output and
+records its original evidence identity/state separately. Revalidation precedes
+the EDA commit marker. A changed evidence document makes EDA fail; it does not
+rewrite the original. Existing index artifacts are not profiled; the link says so.
+Standalone ETL input/output files can be diagnosed in separate runs with the
+same explicit config. Their profiles are diagnostics, not a second verifier.
+
+## CLI
+
+The same implementation is exposed as `equiframe eda` and `equiframe-eda`:
+
+```bash
+equiframe eda run input.parquet --output /private/runs/new-run \
+  --snapshot-id snapshot-v1 --expected-sha256 ACTUAL_TRUSTED_SHA \
+  --config eda-config.json
+equiframe eda inspect /private/runs/new-run
+equiframe eda migration /private/migration --side target \
+  --output /private/runs/new-migration-eda --config eda-config.json
+```
+
+`run`/`migration`: 0 completed diagnostics, 2 invalid configuration/preflight,
+3 persisted unavailable/failed/cancelled diagnostics. `inspect`: 0 intact
+closed evidence, including stored unavailable results; 3 integrity/read failure.
+None of these codes authorizes a DW or establishes equivalence/correctness.
+API results reject boolean evaluation. Compare full content through the existing
+`diff`/`compare`/Verify APIs and use their explicit assertions/outcomes.
+
+## Original representation and conversion
+
+Parquet and Arrow IPC file snapshots admit scalar representations the initial
+backend can preserve; CSV is explicit UTF-8/header/delimiter text, including
+empty fields and textual `NaN`. Original names are checked before DuckDB can
+deduplicate them. Case-insensitive/reserved-name collisions are rejected.
+The MVP admits raw null, boolean, integer, float32/64, string/large string,
+date32, naive second/millisecond/microsecond timestamps and decimals with
+precision at most 38 and nonnegative scale within precision. Other raw types
+(including time, duration, nested/binary/dictionary types, date64, float16,
+nanosecond/zoned timestamps and wider decimals) remain explicitly unavailable
+because the report/transport cannot preserve those types faithfully.
+Timestamp strings remain strings in the raw profile.
+
+`Conversion` creates a new column with original text retained. Decimal requires
+plain decimal text within configured precision/scale; excess fraction digits,
+overflow and invalid lexemes are counted, never rounded. Integer requires
+integral text; date requires ISO date; timestamp requires a valid explicit
+offset/Z and at most six fraction digits. Original offsets/text remain intact,
+with derived instants in UTC. Blank is invalid unless `empty="missing"` is
+declared. No identifiers are converted. Unknown NULL distinctions lost by an
+export cannot be reconstructed. `typed.parquet` is a separate derived artifact.
+
+## Meaning of results
+
+Raw profiles distinguish NULL, numeric NaN, empty text, numeric zero and
+nonfinite values. Valid excludes NULL/NaN/empty/nonfinite; distinct present
+excludes NULL/NaN and retains empty text. Each count/rate records its row
+denominator; an empty denominator has no rate. Nonfinite includes NaN, so
+these two categories overlap and must not be summed as disjoint populations.
+Frequencies are bounded top categories with complete counts, not sampled counts.
+
+Full-row repetitions and declared keys report repeated groups, involved rows,
+excess rows and denominator. Key policy includes/excludes/rejects incomplete
+NULL/NaN and optionally empty text keys. `require_unique=False` records an
+observation: repeated OCID/history is not automatically an error. Nothing is
+removed. Examples and zero-based row references are bounded and tied to the
+snapshot hash; counts scan the complete table.
+
+`NumericRule` selects a native numeric or explicitly converted column and
+comparable groups. Money requires Decimal and text currency grouping; missing
+currency groups report unavailable counts without pooling amounts. Group types
+are text/bool/64-bit integer/Decimal/finite float; other types are explicit
+capability limitations. Groups above `max_groups` are not silently dropped.
+
+Integer/Decimal sum, min/max and **discrete quantiles** are exact. Quantiles use
+DuckDB `quantile_disc`, Hyndman–Fan type 1, including the discrete median. Mean
+also records the exact sum/count rational for integer/Decimal. Float64 mean,
+stddev and visualization/histogram binning are labeled approximate. Population
+or sample stddev is explicit. NULL/nonfinite are excluded with counts; failed
+conversions are recorded separately. Approximate display never changes money.
+
+IQR uses `[Q1 − multiplier×IQR, Q3 + multiplier×IQR]`; unscaled MAD uses median
+± multiplier×median absolute deviation. Bounds are strict: equality is not an
+outlier. Support minimum, method and multiplier are recorded. Insufficient
+support, zero dispersion, missing comparable group or unrepresentable exact
+bound leaves a reason and **count=null**, never zero alerts. Decimal bindings
+use the existing typed transport guard; no float fallback for exact money.
+Only transient bounds may remove exact trailing zeros to fit native precision.
+An outlier remains a case to investigate, including legitimate extremes.
+
+Unavailable requested metrics give run state `not_evaluable` while preserving
+calculated quality and available statistics. Failure, cancellation and source
+changes remain distinct. A completed run without findings does not prove a
+transformation correct. Two different tables can have identical statistics;
+two engines can agree on the same error. R/M/B/H/O and model fitting are unchanged.
+
+## Resources and evidence
+
+Source, output, manifest and evidence paths reject symlinks and Windows reparse
+points, including directory ancestors, before resolving the path. Source-delivery
+members must be normalized relative paths inside that delivery. The delivery
+manifest is limited to 16 MiB and 2,000 entries; its trusted SHA-256 identifies
+the exact bytes read. These checks do not grant operating-system access or make
+this library a sandbox for untrusted callbacks.
+
+`Resources` records memory, threads, timeout, temp spill, input bytes/rows,
+columns/groups, top categories, examples, histogram bins and chart rows/bytes.
+DuckDB memory controls its buffer manager, not process RSS. Temporary-disk cap
+covers DuckDB spill; fixed snapshots, typed files and reports use extra disk.
+Byte/row/group caps and callback cancellation are cooperative. A timer
+interrupts DuckDB queries; callbacks are checked before/after operations and
+chart exports, without promising immediate preemption or hard RSS quotas.
+
+Every exclusive run writes config/source, fixed snapshot, optional typed
+Parquet, findings/summary JSON, HTML and a closed hashed manifest. A partial
+snapshot is labeled `snapshot_complete=False`. The final manifest is the
+commit marker: no readable completed run without it. Publication I/O failure
+can leave an interrupted directory that the reader rejects; do not reuse it.
+`calculation_elapsed_seconds` and elapsed time through report preparation are
+separate; filesystem commit overhead is not a performance guarantee. Report
+budgets can produce an unavailable HTML stub with full JSON diagnostics.
+
+HTML embeds Plotly JavaScript locally. Full histograms and quality counts are
+distinct from the declared first-finite-row sample used for box/scatter display;
+that sample is not representative and its box quartiles are not population
+quantiles. Plotly is never required by migration, comparison or Verify.