equiframe 0.12.4__py3-none-any.whl

equiframe/docs/security.md

@@ -0,0 +1,218 @@
+# Security boundaries and responsible use
+
+EquiFrame is a local Python library, not a sandbox or a hosted service.
+The `0.12.4` release must satisfy the [release gates](releasing.md) before
+publication; a version string alone does not establish acceptance. The historical
+STEP9 assessment remains **incomplete** and is not relabelled by a later release.
+Ordinary source review, dependency advisories and security regressions have their
+own explicit scope. There is no completed security certification, universal
+safety claim or assertion that the code has no vulnerabilities.
+Dependency advisory results, when available, describe a dated snapshot and the
+exact resolved versions; they do not replace a source review.
+
+## Threat model and operating assumptions
+
+Assets include source datasets, SQL and parameters, local paths, captured rows,
+contracts, models, output reports, credentials in the host process and available
+CPU, memory and disk. A consumer may receive damaged or malicious files from a
+third party. A local user who can rewrite the evidence directory while it is
+being checked is a stronger adversary than an immutable downloaded artifact.
+Do not place trusted evidence in a directory writable by untrusted users.
+
+| Boundary | Intended controls and residual responsibility |
+|---|---|
+| Contracts and JSON reports | Strict versioned data models, closed format inventories and validation reject many malformed inputs. Use only supported readers; unknown versions fail closed. Format validation does not guarantee a hard CPU/memory bound for every reader |
+| Evidence and bundles | Hashes, sizes and closed inventories detect inconsistency. Hashes do not authenticate the producer or prove semantic correctness. Fix the expected hash through a trusted channel; inspect in an isolated working directory |
+| HTML/text/notebook output | Common report views escape text and minimize values, names and paths by default. An explicit disclosure option can expose sensitive information. Inspect the chosen report before sharing; raw evidence is separate |
+| Local paths and files | Keep controlled, private work/output roots. A filename is not proof of a regular file; device files, pipes, links, races and hostile mounts require host-level controls. Do not feed special files to readers |
+| SQL and callbacks | Execute only trusted SQL, callbacks, adapters and compilers. Parameters protect value binding; they do not make SQL safe to run. Queries can read local files, access networks or invoke engine capabilities. JSON readers do not authorize executing referenced code |
+| Plugins and models | Registration is explicit. Do not install or execute unknown plugins or deserialize executable Python objects. Detector persistence uses declared data formats; never substitute arbitrary pickle/joblib input |
+| Language-R review | Only the shipped reviewer and a trusted, caller-selected `Rscript` executable may run. Review uses a private temporary directory and a subprocess timeout. It does not sandbox an arbitrary R program or make a semantic verdict a security verdict |
+| Resources | Core budgets are cooperative and scoped to their operation. Capture, parsing, native allocation and custom callbacks may allocate or run before a checkpoint. Use OS/process/container quotas for hostile workloads; constrain disk, CPU, memory, threads and networking |
+| Dependencies and build tools | Verify exact wheel/sdist hashes and the selected dependency profile. Keep build/dev tooling separate from runtime. Installation/building itself executes trusted tooling; an SBOM is an inventory, not a trust grant |
+
+Read-only SQL is not a security perimeter. Explicit DuckDB capture disables
+extension autoload/autoinstall on its private connection; a caller-owned
+connection must already meet the declared conditions. These controls do not
+make arbitrary third-party queries safe. Consistency across external files or
+systems is not established merely by opening a database transaction.
+
+## Local operation, networking and data disclosure
+
+The product's default integration is local; it does not configure a telemetry
+endpoint, background upload service or analytics opt-in. This is not a promise
+of network isolation. Downloading dependencies, querying advisory services,
+injected clients, user callbacks, database queries and external engine features
+can use the network. Those are separate from rendering a stored report.
+
+Use an isolated environment with networking denied when you require offline
+processing, and provision its dependencies beforehand. Do not put credentials
+in contracts, SQL text, data values, filenames, command arguments or diagnostics.
+Error causes and third-party exception objects can retain details even when the
+normal report view is minimized. Do not upload complete runs as bug reports.
+
+Snapshot, spill, SQLite and raw evidence files can contain unredacted values.
+A minimized HTML report does not sanitize these files. Use restrictive directory
+permissions, encrypted storage if required, and an explicit retention policy.
+Deleting a file is not a secure-erasure guarantee. Hashing low-entropy personal
+values is not anonymization. Choose sharing and retention separately from the
+comparison contract.
+
+## Known review limits and reporting
+
+The historical review observed a special-file availability risk in a bundle reader.
+The A14 development follow-up reproduced blocking on a POSIX FIFO and added
+regular-file checks to the bundle, JSON, event and file-description readers.
+Capture budgets still require operation-specific interpretation; per-comparison
+limits must not be represented as global quotas. The follow-up does not complete
+or retroactively amend the historical assessment.
+
+Hernán Troya (`htroya`) is responsible for maintenance, releases and security
+response. There is no response-time SLA. Report suspected vulnerabilities through
+the [private GitHub reporting channel](https://github.com/htroya/equiframe/security/advisories/new)
+of the project's public repository when that route is available. A GitHub
+account is required. For each release, the maintainer must enable this route
+and the public issue channel and verify their availability. Use
+[public issues](https://github.com/htroya/equiframe/issues) for non-sensitive
+bugs and questions. If private intake cannot be verified, retain sensitive
+details locally until confidential intake can be arranged.
+
+Provide a sanitized reproducer, exact version and artifact hash, dependency and
+runtime versions, expected behaviour and impact. Do not post credentials,
+personal datasets or a sensitive exploit in a public issue. Reporting a concern
+does not authorize accessing another user's data or running destructive tests.
+
+[Release and withdrawal process](releasing.md) · [Dependency evidence](dependencies.md)
+
+## Maintainer checks
+
+Run security tools in a separate, disposable tooling environment. Pin the tool
+versions, check downloaded hashes, fix the source commit and record the source
+inventory. Scan the current tracked tree and any proposed additions, including
+tests and documentation; Git history needs its own explicit scan when historical
+exposure is in scope. A current-tree scan does not inspect every historical blob.
+Keep raw reports local and private: scanner output may repeat the secret it found.
+Share only sanitized locations, finding identifiers, dispositions and exit codes.
+Delete temporary snapshots and reports after review. Do not overwrite dated
+evidence or transfer a result to different release bytes.
+
+For TruffleHog, use a local filesystem snapshot with `--no-verification`,
+`--no-update`, `--no-ignore-tag`, `--fail`, `--fail-on-scan-errors` and JSON output.
+Include verified, unknown, unverified and filtered-unverified result classes.
+Disabling verification prevents checking candidate credentials against providers;
+it does not establish whether a detected credential is valid. Exit 183 denotes
+findings and must remain visible even when review determines they are false
+positives. Exit 1 or a missing completion record must be investigated as a failed
+scan. Review findings by their exact location and source context; do not suppress
+all hexadecimal strings, URL credentials or a detector globally.
+
+Run Bandit against both packages' `src`, `tools` and `examples` directories with
+all rules, `--ignore-nosec` and JSON output. Preserve nonzero exits and collection
+errors. Review SQL construction, subprocess arguments and inherited environment,
+assertions and parser boundaries individually. A name-based warning can confuse
+EquiFrame's local `load_dataset` with another project's API; prove the imported
+call target before dismissing it. A subprocess argument list prevents shell
+interpolation but still requires a trusted executable and trusted operations.
+Do not pass publication credentials to build, test or package-execution jobs.
+
+`tools/security_requirements.py` exports every public name/version pair from the
+two locks, including alternative Python/platform pins. It puts alternative
+versions of one project in separate files because pip-audit rejects duplicate
+names in one input. From the repository root, export to a new temporary directory:
+
+```bash
+python tools/security_requirements.py \
+  --lock uv.lock \
+  --lock packages/equiframe-benchmark/uv.lock \
+  --output /absolute/new/temporary/audit-requirements
+```
+
+For **each** exported requirements file, run the pinned `pip-audit` with
+`--no-deps --disable-pip --strict --format json --progress-spinner off -r FILE`.
+This sends public dependency names and versions to the selected advisory service;
+it neither installs the project nor uploads its source. Preserve exits, all
+advisories and skipped/failed collections. Also review admitted lower bounds and
+new build dependencies: a clean resolved lock does not certify every version
+allowed by a range. Do not use `--fix`, ignore lists or a zero-exit option to
+manufacture a passing release.
+
+Check exact distribution names and normalized spelling against the official
+project documentation and PyPI metadata. Use one reviewed index, pinned hashes
+and the exact expected package names. Similar spelling, a public metadata page or
+a 404 does not authenticate a publisher, reserve a name or prove that a package
+is benign. Never publish placeholder projects to reserve lookalike names.
+
+The current release task uses manual publication, without GitHub Actions or
+Trusted Publisher configuration. Use a locally handled publication token only
+after the exact release gates pass. Limit its lifetime by revoking it after use.
+Never put it in a command
+argument, repository, persistent environment file, workflow secret or receipt;
+use a hidden interactive prompt or an approved local secret store. Revoke it
+after the authorized upload. Build and inspect without publication credentials,
+then upload only the four approved files to the explicit index endpoint. TestPyPI
+and PyPI have separate accounts. Reconcile every accepted filename/hash and test
+the downloaded artifacts before promoting identical bytes to production. A
+publication credential does not establish software safety or human acceptance.
+
+Primary references: [TruffleHog usage](https://github.com/trufflesecurity/trufflehog),
+[Bandit CLI](https://bandit.readthedocs.io/en/latest/man/bandit.html),
+[pip-audit](https://github.com/pypa/pip-audit),
+[PyPI account security](https://docs.pypi.org/your-account/two-factor-authentication/)
+and [PyPA name normalization](https://packaging.python.org/en/latest/specifications/name-normalization/).
+
+## Consolidation review boundary, 2026-10-06
+
+The following paragraphs describe the historical 2026-10-06 consolidation.
+That consolidation did **not** resume the stopped source-security assessment,
+through a specialized scanner or through an equivalent manual audit. That is a
+real unresolved coverage boundary, distinct from a temporarily missing tool.
+The prior special-file observation and capture-budget contract question remain
+open; no new reproduction, severity confirmation or remediation is claimed for
+them. Ordinary functional tests, compatibility checks and documented resource
+measurements do not close the security assessment.
+
+A separate fresh reading of the official advisory for **CVE-2026-25087** on
+2026-10-06 confirms Apache's stated scope: Arrow C++ 15.0.0 through 23.0.0 is
+affected and 23.0.1 contains the fix; Python, Ruby and C GLib bindings are excluded
+because the affected IPC pre-buffering functionality is not exposed through them.
+This qualifies the historical minimum-profile package-version match. It does not
+turn an inventory into a clean scan or prove every bundled native component and
+EquiFrame usage safe. Sources: [Apache advisory](https://security.apache.org/projects/arrow/)
+and [Arrow 23.0.1 release notes](https://arrow.apache.org/blog/2026/02/16/23.0.1-release/).
+The dated source receipt is retained with this consolidation's evidence, separately
+from earlier advisory snapshots. No dependency version was changed on that basis.
+
+The final artifact-bound offline dependency inventories/SBOMs identify the new
+wheel/sdist bytes. Offline regeneration performs no new registry-wide advisory
+query and must not be presented as a current comprehensive vulnerability scan.
+At that consolidation, release and untrusted-input adoption remained blocked on
+the unresolved assessment and owner decisions. Current release decisions follow
+the release gates; this historical snapshot is not a security certification.
+
+## A14 secure-development follow-up, 2026-10-13
+
+Stored operational failure summaries and CLI diagnostics use fixed messages.
+They do not stringify external exceptions or publish their input values, source
+paths or SQL. Optional DEBUG diagnostics contain at most 32 owned frame records
+(module, function, line); external frames are anonymous and values, source text
+and local variables are excluded. A broken logging handler cannot replace the
+operational result. Programmatic validation exceptions and explicitly requested
+raw data remain separate; applications must handle them before showing a UI.
+
+EDA cancellation callbacks must be callable and return actual booleans. A failing
+callback is not called again during error recovery; incomplete analysis persists
+a closed diagnostic code. Unexpected optional-chart failures also remain
+explicitly not evaluable, without exposing third-party exception text.
+
+Evidence readers and bundle inventories inspect lexical ancestors before
+resolution and reject symlinks, Windows reparse points and non-regular files.
+POSIX reads pin directory descriptors and use O_NOFOLLOW/O_NONBLOCK; fallback
+hosts check identities around opening. JSON and bundle documents retain their
+64 MiB limit, and the bundle pin is checked against the bytes actually parsed.
+These cooperative checks are not a filesystem sandbox against hostile mounts
+or concurrent owners. Bundle copies still require a controlled, immutable source.
+
+Contract and generic profile/detector document files also use protected regular
+reads with a 64 MiB limit. Generic document readers retain OS exception classes
+and errno for recovery, with fixed messages and no filenames. Relative output
+directories retain relative member names in the published inventory.

equiframe/docs/semantics.md

@@ -0,0 +1,274 @@
+# Semantics, guarantees and limits
+
+[Handbook](index.md) · [API](api.md) · [Security](security.md)
+
+## What equivalence means
+
+`ComparisonResult` evaluates the contract's **output schema** over two captured
+results. `equivalent` means a complete scan found no differences or output-contract
+violations under the declared policies. It does not prove arbitrary programs
+equivalent, validate an entire business process, evaluate operational R rules,
+establish an independent expected output, or authorize data publication.
+
+`diff` treats the right side as `expected` by default. `compare` defaults to
+`peer`; explicitly pass `reference="expected"` when the right side is your
+reference. An invalid expected result yields `not_evaluable`, including when a
+scan completed. Two peers can agree on the same incorrect output.
+
+| State | Scan/diagnostic interpretation |
+|---|---|
+| `equivalent` | Complete evaluation; no differences or violations in scope |
+| `different` | Complete evaluation; differences or violations retained |
+| `not_evaluable` | Required judgment unavailable; partial findings may remain |
+
+Inspect `state`, `complete`, diagnostics and `counts.final` separately. A complete
+scan is necessary but not sufficient for equivalence. Counts from interrupted
+scans are partial observations. `difference_records` counts diagnostic records,
+not necessarily distinct affected rows. Missing files, failed finalization,
+resource exhaustion and exceptions never imply a pass.
+
+Native [windows](migration-ir.md#deterministic-windows) preserve every input row.
+Lag/lead retain Decimal precision/scale and units, integer width, timestamp
+unit/zone, and the separate NULL/NaN meaning of the input. They introduce NULL
+only at partition boundaries; input NULL values also remain NULL. Row-number
+output is signed64 and nonnullable. Partition/order ties fail rather than select
+an arbitrary original position. Explicit final sorting remains necessary for a
+sequence contract. The compiler rejects incompatible declared types/units and
+unsupported native plans before execution; comparison does not repair them.
+
+Use `assert_equivalent`, which requires complete/final `observed_contract`
+equivalence and any additional policy/evidence requirements. `ComparisonResult`
+and `EquivalenceDecision` reject truth testing; use the assertion or the explicit
+`.accepted` field. Presentation reports cannot be passed to this gate.
+
+## Explicit contract, conservative inference
+
+The observed physical schema is captured separately from the expected logical
+schema. EquiFrame does not silently cast to the expected schema, fill NULL, trim
+text, normalize Unicode, deduplicate, reorder or round values to remove a
+mismatch. Any allowed equivalence must be declared, justified where required,
+and visible in the recorded policy.
+
+Typed contract models are strict and frozen, reject unknown fields and use
+explicit tagged scalars. Contract validation checks metadata and cross-field
+relationships; it does not evaluate actual tables or execute declared rules.
+A valid JSON Schema document alone is not proof of all cross-field constraints.
+Use the public validator and the appropriate data/evidence API.
+
+Without an explicit contract, `diff` infers only from the right-hand Arrow
+schema after faithful capture. It records provenance, defaults to nullable,
+retains NULL separately from NaN and uses exact numbers with unit `unspecified`.
+It does not learn tolerance, business keys, money units, non-nullability or
+business meaning from samples. `ColumnSpec` overrides are the route to explicit
+domain requirements.
+
+## Schema, types and metadata
+
+Default `ComparisonPolicy` is `column_order="significant"`,
+`physical_types="exact"`, `index="reject"`. Nonconservative permissions require a
+justification. Column names, authorized order, nullability, allowed values,
+ranges and granularities are evaluated, even if both inputs violate them in the
+same way. Empty tables retain and validate their schema.
+
+"Exact physical types" uses the comparator's documented logical signature:
+booleans; integer width/sign; float width; decimal precision/scale; strings;
+dates; timestamp unit/timezone. Arrow string, large_string and string_view
+represent the same string family; decimal128/256 of identical precision/scale
+represent the same decimal; date32/date64 represent days, with whole-day checks.
+This is not native dtype identity or arbitrary metadata equality.
+
+`physical_types="lossless"` permits checked representable variations **within**
+a family: integer width/sign, exactly representable float narrowing and exact
+Decimal rescaling/range. It does not equate integer, float, Decimal and string.
+An Arrow null-typed column needs explicit lossless permission and a nullable
+contract to specialize. The expected domain is not invented.
+
+Direct `diff` capture rejects uninterpreted Arrow field/schema metadata,
+meaningful unsupported pandas metadata, categories, heterogeneous object cells,
+unsupported subclasses and undeclared dtype metadata. Rejection is preferable
+to asserting an equality that erased a distinction. Existing artifact routes
+retain their own documented admission; wrapping an input does not expand it.
+
+## NULL, NaN, zero and text
+
+NULL, NaN, empty text and numeric zero remain distinct unless `NullPolicy` or
+`NaNPolicy` explicitly authorizes an equivalence. Such permissions do not add
+missing-value distinctions absent from the original representation.
+
+- NaN `forbid` is a violation; `distinct` is a category distinct from NULL and
+  numbers; `as_null` needs the declared nullable/equivalence policy
+- NaN payload/signaling distinctions are not compared
+- Positive and negative float zero have equal numeric value; evidence retains
+  the observed sign. This is not bitwise floating-point identity
+- Text remains exact: no trimming, case folding, Unicode normalization,
+  accent/collation inference or removal of leading identifier zeroes
+- A NumPy float column cannot recover None versus NaN already collapsed before
+  EquiFrame sees it. Separate Arrow masks or suitable admitted representations
+  can preserve distinctions that still exist
+
+## Decimal, units and approximation
+
+Decimal comparison uses exact rational arithmetic, never an intermediate float
+or the consumer's mutable Decimal context. Declared precision/scale, units and
+engine capabilities matter. A rounding policy describes the intended
+transformation; it does not authorize repairing a result during comparison.
+Currency conversion is not inferred. A declared unit absent from the actual
+data cannot be empirically recovered from a number alone.
+
+For integer/float measures with an explicitly fixed tolerance:
+
+```text
+abs(a - b) <= max(absolute or 0, (relative or 0) * max(abs(a), abs(b)))
+```
+
+The formula is symmetric and inclusive. Finite IEEE values and decimal-textual
+tolerances are evaluated exactly as rationals. Infinities match only the same
+sign, and NaN follows its separate policy. Decimal remains exact. Tolerances are
+not estimated from the pair and do not define keys, uniqueness or ordering.
+Approximate equality is not transitive.
+
+Exact multisets count complete canonical values. Approximate multiset matching
+uses bounded maximum matching to preserve occurrences; it is not a greedy
+nearest-row heuristic. Work, candidate-pair and matching-memory limits can make
+a case `not_evaluable`. Hashes partition work or verify bytes; hash equality
+alone never substitutes for exact value comparison.
+
+## Keys, duplicates and order
+
+All declared keys are checked before and after authorized normalization. A
+columns-scoped key includes its scope columns; table/global key scope covers the
+compared output, not all external tables or future snapshots.
+
+When row order is ignored, the first declared unique key is eligible for
+alignment only after uniqueness and completeness are verified on both sides.
+Otherwise the complete multiset is compared and key violations remain visible.
+There are no approximate keys. `incomplete="allow"` retains incomplete rows and
+excludes them from uniqueness checking; it does not fabricate identity or drop
+those rows. Duplicate keys cannot be "fixed" by selecting the first occurrence.
+
+`multiplicity="preserve"` counts every occurrence. `"distinct"` is a requirement
+that normalized rows do not repeat, not permission to deduplicate. Without
+verified identity, a report describes excess occurrences instead of inventing
+modified business rows.
+
+`SignificantOrder` compares sequence and validates the declared sort columns,
+direction, NULL placement and ties. `ties="preserve"` retains observed relative
+order; `ties="reject"` disallows ties. No sort repairs an output during comparison.
+A pandas index is not automatically a key. A trivial unnamed
+`RangeIndex(0, n, 1)` is not business identity; meaningful indices need promotion
+to explicit columns or an explicit justified exclusion policy.
+
+## Time and capture fidelity
+
+Dates are whole days. Timestamps retain integer epochs and physical precision,
+including nanoseconds, without a float or Python datetime rounding step.
+`instant` and `wall_time` are separate policies. Changing timezone requires the
+appropriate lossless/instant policy; local time requires the declared zone.
+Naive timestamps can be preserved, rejected or interpreted using the declared
+zone and DST policy. Nonexistent local DST times are violations; calendar/zone
+operations outside the supported year range are not evaluated.
+
+Contract timezone logic uses Python `tzdata`. General native transformations
+use the provider available to their engine: pandas' input provider, Polars'
+compiled provider, or DuckDB's ICU. Compiler-generated IR `LocalizeTimestamp`
+in Polars instead reads the installed TZif metadata and evaluates its transition
+rules with native Polars expressions. Resource hashes participate in the
+compilation identity, and a resource changed before execution is rejected.
+EquiFrame does not assume all providers share an IANA version. Engine, runtime,
+resource and configuration facts remain explicit; tested agreement has a finite
+scope and does not establish identical timezone databases.
+
+Arrow does not retain each row's original ISO text/offset, negative Decimal zero
+or distinct Decimal exponents within a fixed-scale column. Store those required
+facts as explicit columns **before** they are lost. EquiFrame does not reconstruct
+them after conversion.
+
+## Capture, execution and migration are different capabilities
+
+| Route | Admitted scope and important rejection |
+|---|---|
+| Direct `diff` | Eager pandas/Polars DataFrames, Arrow tables and explicitly supplied DuckDBPyRelation objects; relation submission authorizes bounded materialization; no inferred SQL strings, connections, Polars lazy plans or consumable readers |
+| `compare` | `ArrowInput`, local `ArtifactRef`, local Arrow IPC file/Parquet `Path`, `TableArtifact`, completed `ExecutionResult` |
+| Native pandas | Admitted scalar bool, integers, text, floats, decimals and temporal types; unsupported metadata/object/category cases rejected |
+| Native Polars | Decimal precision at most 38 and nonnegative scale; date32; seconds promoted to milliseconds only when representable |
+| Native DuckDB | Faithful admitted native types; decimals at most precision/scale 38; zoned timestamps limited to representable microseconds |
+| Declarative migration | Bounded typed relational IR over each engine's genuine native implementation |
+
+Native transport excludes dictionaries/categories, nested tabular values, binary,
+arbitrary objects and Arrow streams. Capture support does not imply that every
+native transformation supports every admitted type. Consult
+`get_adapter_capabilities()` for stage-specific conditions and known losses.
+
+DuckDB HUGEINT/UHUGEINT, UUID/ENUM and other types without declared faithful
+mapping are rejected before Arrow conversion; temporal infinities and zoned
+nanosecond timestamps are also rejected. Decimal SQL parameters are bound with
+exact checked precision/scale. Nonfinite Decimal, negative zero, positive
+exponent, excessive precision/scale and integers outside signed/unsigned 64-bit
+range are rejected. A consumer-chosen explicit cast requires a justified
+representable domain; EquiFrame never inserts it to make results match.
+
+The migration IR includes Scan, Project, Filter, exact Cast, EquiJoin,
+Aggregate, Sort, Concatenate and Deduplicate, with closed typed expressions
+including Arithmetic, Coalesce and Conditional. It has explicit NULL-join,
+NULL-group, empty-sum, tie and multiplicity policies. It does not translate
+arbitrary Python/SQL. Its common decimal precision is at most 38. Right/full joins, matchable-key
+cardinality, deterministic key deduplication, exact Decimal multiplication,
+declared rounding/division and timestamp transport/localization have the
+[per-engine contracts and bounds](migration-ir.md). Float join/group/order
+keys and float SUM/min/max remain outside this IR.
+`count_valid` can admit float. Native admission can reject a mathematically safe
+case conservatively, for example a Polars sum with cancelling large terms.
+
+Arithmetic `overflow="reject"` applies to every intermediate expression, even
+when a later expression would cancel its value or produce a boolean or NULL.
+Pandas and Polars evaluate those checks eagerly. DuckDB compiler v8 and its
+native adapter consume each fallible expression and relational node at an
+in-memory native checkpoint before a containing predicate or later operation
+can prune it. The [checkpoint contract](migration-ir.md#eager-failures-and-historical-evidence)
+defines adapter admission, resource checks and the remaining common IR limits.
+No fallback or lossy cast supplies an answer.
+
+`check_migration` checks both compilers without reading inputs or loading engines.
+`migrate` captures the same inputs once and executes two native pipelines. The
+optional expected output is separate and never feeds the transformations,
+profiles or detectors. `require_rules=False` is an explicit change of requested
+scope, not proof that R passed; child pipeline states and partial alerts remain.
+
+## Evidence, privacy and execution limits
+
+- Capture and comparison retain snapshots and full differences subject to budgets.
+  A report example limit does not reduce evaluation coverage
+- Default comparison reports hide values, names and paths. Optional disclosure
+  must be deliberate. Redacting a view does not erase the raw evidence directory
+- `read_comparison` validates the manifest; `iter_differences` verifies the
+  difference file's size/hash while reading it. Other readers have their own
+  closed-inventory and semantic checks; they are not interchangeable
+- Report `diagnostic`, `detail` and `reproduction` modes offer different evidence.
+  Reproduction exports supported materialized inputs, not original transformations
+  or external services. `require_exhaustive` is independent of shown example count
+- Hashes identify bytes relative to a trusted reference. They do not authenticate
+  authors/reviewers, prove expected-output correctness or certify a dependency safe
+- Local files require a suitable filesystem, including exclusive atomic hard-link
+  publication where used. Publication failures can raise and leave partial files
+- No API guarantees a report after process kill, disk failure or host OOM. CI must
+  fail closed on missing finalization or abnormal termination
+- Core time, memory, row, disk and work checks are cooperative. Native allocations
+  may precede checkpoints. DuckDB engine limits are not total-process RSS quotas
+- Callbacks, registered plugins, SQL and model-related integrations must be trusted.
+  EquiFrame is not a sandbox or a service concurrency/security controller
+
+See [performance](performance.md), [security](security.md) and
+[upgrading](upgrading.md) for operating and recovery procedures.
+
+## Rules and anomaly signals are not equivalence
+
+R evaluates declared rules over one execution; M is Isolation Forest; B is MAD;
+H is R OR M; O is independent expected-output/review evidence. They remain
+separate. Profiles and detectors do not receive labels, mutations or another
+engine's output. Fitting, calibration and inference are distinct operations.
+
+An unavailable component is `not_evaluable`, never `no_alert`. H retains an alert
+from either R or M even if the other component is unavailable, while marking
+coverage incomplete. With no alert and an unavailable component, H is not
+evaluable. B does not participate in H. Empty rules do not establish R coverage.
+A low anomaly score or `no_alert` is not an equivalence gate or load authorization.