equiframe 0.12.4__py3-none-any.whl

equiframe/docs/r_review.md

@@ -0,0 +1,212 @@
+# Revisión independiente con el lenguaje R
+
+EquiFrame ofrece `review_with_r`, `finalize_with_r` y
+`finalize_execution_with_r` como una etapa opcional.
+El revisor ejecuta una segunda comparación determinista sobre las dos tablas
+observadas completas y el contrato declarado. Su implementación usa base R;
+no recibe el veredicto del comparador Python ni los scores de los detectores
+como respuesta esperada.
+
+Esta independencia de implementación ayuda a encontrar discrepancias entre
+comparadores. No demuestra por sí sola que la migración sea correcta para
+cualquier entrada. Una alerta de Isolation Forest sigue siendo una anomalía,
+no una prueba de diferencia semántica. Replicar el mismo Isolation Forest en
+R no aportaría esa garantía y no forma parte de esta etapa.
+
+La letra `r` de `HybridDecision.r` sigue significando **reglas**. El lenguaje R
+no reemplaza reglas, M (Isolation Forest), B (MAD), H (reglas OR M) ni O
+(oráculo científico). El revisor tampoco modifica perfiles, entrenamiento,
+calibración o inferencia de los detectores.
+
+## Uso después de reglas e Isolation Forest
+
+R debe estar instalado por el usuario y `Rscript` debe estar en `PATH`, o se
+debe indicar su ejecutable. EquiFrame no instala R ni paquetes R. Sólo necesita
+base R. Los ejemplos siguientes describen llamadas de uso; no son ejecuciones
+ni resultados de validación.
+
+```python
+import equiframe as ef
+
+# Valores obtenidos previamente de las API reales:
+# execution: ExecutionResult con la salida capturada que se está analizando.
+# rules_result: RuleEvaluation para la ejecución que se está analizando.
+# profile: ProfileResult producido para esa ejecución.
+# detector_bundle: bundle Isolation Forest previamente ajustado y calibrado.
+# python_comparison: ComparisonResult que conserva esa ejecución en uno de sus lados.
+detection = ef.detect_component(detector_bundle, (profile.vector,), method="isolation_forest")
+
+final = ef.finalize_execution_with_r(
+    execution,
+    rules_result,
+    profile,
+    detection,
+    comparison=python_comparison,
+    options=ef.RReviewOptions(rscript="Rscript", timeout_seconds=30.0),
+)
+
+# Consultar los componentes y su disponibilidad de forma explícita.
+hybrid_decision = final.hybrid.result
+independent_comparison = final.r_review
+previous_comparison = final.comparison
+comparators_disagree = final.comparison_disagreement
+final_decision = final.result
+may_continue = final.accepted
+execution_binding = final.execution_binding
+```
+
+Ésta es la ruta vinculada: comprueba IDs, huellas de ejecución, contrato,
+artefactos del perfil y el resultado IF de exactamente un vector. Exige que
+la comparación conserve esa ejecución y su salida en uno de sus lados; lee
+directamente los artefactos comprobados de ambos lados. Una asociación inválida
+se rechaza antes de iniciar R, mediante un error de validación. La vinculación
+no autentica al autor humano ni convierte una etiqueta declarada en verdad.
+
+`final.execution_binding` es un `RExecutionBinding` con `execution_id`,
+`execution_sha256`, `profile_id`, `profile_sha256`, `detection_sha256` y
+`output_sha256`. Identifica los documentos y la salida realmente asociados por
+el finalizador. El ejemplo no entrena un modelo ni proporciona un bundle ficticio.
+
+`finalize_with_r` permanece como API de bajo nivel para quien ya tiene decisiones
+operacionales y observaciones eager. Recibe `rules`, una `ComponentDecision` de
+Isolation Forest, `left`, `right`, `contract` y `comparison` opcional. En esa ruta
+el llamante debe asegurar la asociación de las decisiones; una decisión aislada
+no contiene toda la procedencia de su ejecución. No se declara
+`execution_binding` por deducirla del nombre de una variable.
+
+Para solicitar exclusivamente la segunda comparación:
+
+```python
+from equiframe.r_review import review_with_r
+
+review = review_with_r(
+    pandas_output,
+    polars_output,
+    contract=diff_contract,
+    comparison=python_comparison,
+)
+```
+
+`review_with_r` admite salidas eager de Pandas, Polars, Arrow, `ArrowInput`,
+artefactos locales `ArtifactRef` y `TableArtifact`, y objetos reales
+`DuckDBPyRelation`. Pasar una relación DuckDB autoriza consumir su plan nativo
+una vez por entrada suministrada, con comprobación de tipos y límites de filas
+y bytes. La captura rechaza el exceso de filas, sin truncarlo para aceptar la
+comparación, y conserva una observación separada de la relación. El llamante
+mantiene la propiedad de su conexión, configuración y plan nativo.
+No se infieren cadenas SQL, conexiones, callbacks, lectores consumibles ni
+`LazyFrame` de Polars como entradas tabulares. También puede capturarse DuckDB
+previamente como Arrow/artefacto para revisar una observación ya materializada.
+`comparison` es opcional para la revisión aislada. Cuando se aporta,
+comprueba los SHA-256 de sus artefactos y que todo el transporte observado de
+`left` y `right` corresponda a esos mismos datos antes de enviarlos a R.
+Una especificación distinta bloquea la finalización; el veredicto Python no se
+envía como respuesta esperada.
+
+Una revisión vinculada conserva `review.binding`, un `RReviewBinding` con
+`comparison_id`, `left_artifact_sha256` y `right_artifact_sha256`. Una revisión
+aislada sin `comparison` conserva su dictamen, sin inventar ese vínculo.
+
+Los modelos de opciones, vínculos y resultados tienen esquemas versionados estables
+`1.0` incluidos en el sdist y como recursos `equiframe/schemas` del wheel:
+`r-review-options`, `r-review-binding`,
+`r-execution-binding`, `r-review-result` y `reviewed-decision`. Su registro
+explícito de compatibilidad conserva la huella del productor actual; no cambia
+los esquemas o recibos anteriores de comparación, reglas y detectores.
+La estabilidad protege la interfaz y los estados de error dentro del subconjunto
+admitido; no acredita precisión científica, todos los contratos posibles ni
+cualquier versión externa de R. Véanse los límites de [compatibilidad](compatibility.md).
+
+`contract` acepta `Contract`, `DiffContract` o `ComparisonSpec`; no se inventa
+un esquema o una tolerancia a partir del veredicto anterior. Si se necesita
+inferir un contrato de metadatos, se puede construir antes mediante la API
+existente `infer_diff_contract` y revisar sus políticas.
+
+## Resultado final
+
+| Condición | Resultado final |
+|---|---|
+| Alguna regla o M alerta | Se conserva `alert`, aunque R encuentre equivalencia. |
+| El comparador Python previo encuentra diferencias | Se conserva `alert`, aunque R encuentre equivalencia. |
+| R encuentra diferencias o violaciones del contrato | `alert`. |
+| H está completo sin alertas, R termina equivalente y la comparación Python aportada también es completa/equivalente con la misma especificación y artefactos vinculados | `no_alert`, `accepted=True`. |
+| Falta R, hay timeout/cancelación/fallo o una política no está admitida | `accepted=False`; se conserva cualquier alerta y se indica evaluación incompleta. |
+| El comparador Python aportado está incompleto o no es evaluable | `accepted=False`; se conserva cualquier alerta y se indica evaluación incompleta. |
+
+El campo `final.r_review.state` mantiene por separado `equivalent`,
+`different` o `not_evaluable`. Una comparación equivalente en R y una alerta
+de M no se cancelan: son observaciones distintas. `final.result.complete`
+requiere disponibilidad de todos los componentes solicitados. `no_alert`
+no se convierte en una etiqueta científica de corrección.
+
+`comparison` es opcional. Si se aporta, EquiFrame conserva el documento Python
+completo, comprueba las observaciones y lo combina después de ejecutar R, sin
+usar su veredicto como esperado para R.
+`comparison_disagreement=True` indica que ambos comparadores terminaron con
+dictámenes distintos; no decide cuál tiene razón ni borra diferencias.
+Una especificación diferente también se conserva y bloquea la aceptación.
+Si se omite `comparison`, la finalización mantiene su comportamiento H más R;
+no presupone que antes se ejecutó el comparador Python.
+Esta opción corresponde a `finalize_with_r`; la ruta
+`finalize_execution_with_r` exige una comparación vinculada.
+
+## Alcance exacto del revisor 1.0
+
+Se compara contenido completo, sin muestreo y sin decidir igualdad mediante
+hashes. Se mantienen multiplicidad y claves; puede compararse como multiconjunto
+o como secuencia, comprobando las columnas de orden y sus empates. El orden
+de columnas puede ignorarse sólo cuando el contrato lo autoriza. Un índice
+significativo de Pandas exige la autorización explícita existente para ignorarlo
+o su promoción previa a columnas del contrato.
+
+Tipos admitidos: booleanos, cadenas UTF-8, enteros de 8–64 bits con signo o
+sin signo, decimales de precisión física admitida por Arrow, flotantes de
+32/64 bits, fechas `date32` y timestamps. Los enteros y decimales no se
+convierten a `double` en R. Se distingue NULL de NaN; NaN puede ser distinto
+o estar prohibido. Se preservan signos de infinito; cero positivo y negativo
+se comparan según la igualdad numérica exacta existente.
+
+Los timestamps zonificados sólo se admiten para comparación de instantes con
+`naive="reject"`; las observaciones ya contienen ticks y zona. Los timestamps
+sin zona se admiten con `naive="preserve"`, sin interpretación local.
+El revisor no resuelve DST ni convierte cadenas de fecha en instantes.
+
+Las siguientes configuraciones devuelven `not_evaluable` en esta versión:
+
+- Tipos físicos relajados mediante `physical_types="lossless"`.
+- Tolerancias numéricas, redondeo, alias de NULL o NaN convertido a NULL.
+- Restricciones `allowed_values` e intervalos temporales con límites.
+- Resolución de hora local (`assume_zone`), comparación zonificada por hora
+  de pared y tipos `date64`.
+- Tipos tabulares anidados o metadatos que la captura fiel actual no admite.
+
+Estas limitaciones afectan únicamente a la revisión opcional en R. No
+redefinen ni reducen las capacidades del comparador Python. Una política
+no admitida no se sustituye por otra para obtener una aprobación.
+
+## Recursos, privacidad y procedencia
+
+Los límites predeterminados son 100.000 filas por entrada, 256 columnas,
+64 MiB de captura por entrada y 64 MiB de transporte acumulado, con 30
+segundos cooperativos para la operación y un proceso R terminable. No son
+cuotas duras de memoria RSS: las copias y los objetos de R tienen sobrecoste.
+La captura de un plan nativo DuckDB precede al proceso R y puede bloquear
+dentro del motor; el tiempo cooperativo no constituye una interrupción dura
+de esa captura.
+
+El proceso usa `Rscript --vanilla --default-packages=NULL`, una carpeta
+temporal privada por operación y argumentos estructurados sin shell. Los
+archivos temporales se retiran al terminar, incluso ante fallo o cancelación.
+El resultado devuelve versión de R, estado, conteos y SHA-256 del código,
+especificación y transportes observados. Los hashes sirven para identificar
+entradas; R decide con filas completas. No se incluyen valores de las filas
+en los canales de diagnóstico ni se guarda un modelo adicional.
+
+La captura Arrow es un límite compartido con el resto del producto: R vuelve
+a implementar comparación y validaciones admitidas, pero no reinterpreta los
+archivos fuente sin pasar por esa captura. Esta independencia es técnica,
+no una revisión humana ni un oráculo de negocio independiente.
+
+Referencias del lanzador y transporte: [Rscript](https://www.stat.ethz.ch/R-manual/R-devel/library/utils/html/Rscript.html),
+[readLines](https://www.stat.math.ethz.ch/R-manual/R-devel/library/base/html/readLines.html)
+y [writeLines](https://www.stat.math.ethz.ch/R-manual/R-devel/library/base/html/writeLines.html).

equiframe/docs/recipes.md

@@ -0,0 +1,248 @@
+# Three reproducible installed recipes
+
+[Handbook](index.md) · [Quick start](quickstart.md) · [Semantics](semantics.md)
+
+A8 introduced the interpreter-aware builder. It supplies offline kits when
+generated for an identified artifact. Retained 0.11.1 first-use results remain
+historical; they do not validate a new release. Also see the offline wheelhouse guide.
+
+These recipes describe an identified EquiFrame **0.12.4** first-use kit, when
+provided, and **the Python minor selected in its manifest (3.10-3.13)**.
+First-use kits are generated separately from the source tree. The kit contains
+the exact wheel, three recipe scripts and their
+pytest fixture, pinned dependencies with hashes, an integrity verifier and
+English guides. No checkout, real dataset, credential, remote SQL, notebook or
+service is required. Inputs are small synthetic fixtures defined in the scripts.
+
+The target of a first useful diagnosis within five minutes is **not yet validated
+by human observation**. Automated independent artifact checks are technical
+evidence, not a substitute for that observation. Preserve the kit's unfilled
+`OBSERVATION.md` and record a real attempt separately if you participate.
+
+## 1. Obtain, verify and install the kit
+
+Obtain the candidate kit through the authorized private channel. Compare its
+archive SHA-256 with the separately supplied trusted receipt **before extraction**.
+Extract it into a new directory named `kit`, outside the repository, and open a
+terminal there. Keep the kit unchanged: environments, outputs and completed
+observation records belong in sibling directories. The internal manifest detects
+byte changes; it does not authenticate the sender.
+
+The commands below show 3.12. If the manifest selects 3.10, 3.11 or 3.13,
+replace each python3.12 command with that exact interpreter; the supplied
+requirements.lock must belong to that same minor.
+
+```bash
+python3.12 --version
+python3.12 verify_kit.py
+python3.12 -m venv ../first-use-env
+```
+
+On Windows use `py -3.12` in place of `python3.12`. Activate the environment:
+
+- Linux/macOS shell: `source ../first-use-env/bin/activate`
+- PowerShell: `..\first-use-env\Scripts\Activate.ps1`. If local policy prevents
+  activation, use `..\first-use-env\Scripts\python.exe` directly; do not change
+  security policy
+
+These are platform command conventions, not new platform acceptance results.
+Install into the new environment:
+
+```bash
+python -m pip install --require-hashes --only-binary=:all: -r requirements.lock
+python -m pip install --no-index wheels/equiframe-0.12.4-py3-none-any.whl
+python -m pip check
+python -I -c "import equiframe, sys; print(sys.version); print(equiframe.__file__)"
+```
+
+The **first command deliberately downloads dependencies from your configured pip
+index**; it does not download datasets. Pins and hashes come from the candidate's
+`uv.lock`. The second command installs the verified local EquiFrame wheel with normal
+dependency validation against the already pinned environment.
+The import must resolve to the environment, not the source checkout. Do not add
+`PYTHONPATH` or use an editable install.
+
+For offline installation, first obtain a reviewed wheelhouse containing those
+same pinned dependency wheels and add
+`--no-index --find-links /absolute/path/wheelhouse` to the first install command.
+Dependency binaries are not inside the kit. Do not remove hashes or force other
+versions to bypass a failure. If your platform has no compatible wheel, record
+the blocker; this guide does not certify a new platform matrix.
+
+A maintainer with the source distribution and built wheel can prepare a kit with
+`python tools/build_first_use_kit.py --python-minor 3.12 --output /absolute/path/new-kit` from the
+core package directory. That builder does not resolve new dependencies or
+publish a package. Consumers continue using only the resulting kit.
+
+## 2. Diagnose a pandas refactor
+
+Create a sibling working directory and run all commands below from there:
+
+```bash
+python -c "from pathlib import Path; Path('../first-use-work').mkdir()"
+cd ../first-use-work
+python -I ../kit/refactor_comparison.py --output refactor-different
+```
+
+**Expected process exit: 1**, a deliberate regression. The report identifies:
+
+- `different`, complete evaluation and coverage, strategy `key`
+- Key `id="B"`, column `total_cents`
+- Candidate `integer(2001)` versus expected `integer(2000)`, both `int64`
+- Exact numeric policy, declared unit `USD_cent`, one modified row
+
+Open `refactor-different/report/report.html` or read `report.txt`. The inspectable
+contract is `refactor-different/contract.json`. The vectorized refactor added one
+cent. Reordered rows are allowed because the contract ignores order and verifies
+a unique key. The reference preserves the earlier implementation and is also
+checked against three literal fixture values. This does not make pandas or a
+historical output a universal oracle.
+
+Run the correction **without changing the policy**:
+
+```bash
+python -I ../kit/refactor_comparison.py --case equivalent --output refactor-equivalent
+```
+
+Expected exit 0, `equivalent`. Try the no-key extension:
+
+```bash
+python -I ../kit/refactor_comparison.py --without-key --output refactor-bag
+python -I ../kit/refactor_comparison.py --without-key --case equivalent --output refactor-bag-ok
+```
+
+Expected exits 1 and 0. Without row identity, EquiFrame compares multisets and
+preserves occurrences; it reports excess rows on each side rather than claiming
+which business row changed. Do not deduplicate to make it pass. This fixture's
+integers are small: it does not promise overflow-free int64 arithmetic for
+arbitrary inputs, fractional currency handling or currency conversion.
+
+This script displays only its known synthetic values. `--redacted` hides values
+and metadata in the report. Raw captures are temporary unless you supply
+`--work-dir private-refactor`, which retains private snapshots and full differences.
+Keep that directory separate from reports and do not upload it automatically.
+The attached contract still contains synthetic names/units in redacted mode;
+share only `report/` for the minimized view.
+
+## 3. Validate a bounded pandas → DuckDB migration
+
+```bash
+python -I ../kit/migrate_duckdb_recipe.py --case equivalent --output migration-ok
+python -I ../kit/migrate_duckdb_recipe.py --case different --output migration-regression
+python -I ../kit/migrate_duckdb_recipe.py --case not_evaluable --output migration-limited
+```
+
+Expected exits **0, 1 and 3**. The script uses the real `ef.migrate` API with a
+`Scan` + `Aggregate` relational plan. It does not translate arbitrary Python or
+SQL. Both engines execute their native implementation over the same snapshot;
+the literal expected output is captured separately. Decimal type/scale, currency,
+NULL amounts, empty-sum behavior and counts are declared before execution.
+
+The negative case deliberately changes empty-sum semantics. The engines may
+therefore be `equivalent` to each other while `verification="divergent"` against
+the unchanged expected output. This is a shared error, not a fabricated
+cross-engine discrepancy.
+
+Each output contains `source-target/`, `source-expected/` and `target-expected/`.
+Each directory retains `report.json`, `report.txt`, `report.html` and
+`evidence-manifest.json`, verified before publication is announced. The limited
+case permits one row per comparison; partial counts are not final totals. Do not
+change the expected output to resolve an evaluation limit.
+
+Use `--show-synthetic-values` to inspect the literal expected output and both
+captured results. Expected values are EUR: NULL total/2 rows, JPY: 0.00/1 row and
+USD: exact Decimal 1000000000000000.03/3 rows. The negative case changes only EUR
+to 0.00 in both engines. Each comparison against the expected output retains one
+difference. Values are not printed by default and reports are redacted.
+
+`--work-dir private-migration` retains inputs, expected output, native outputs,
+configuration and evidence instead of deleting temporary originals. Never mix
+it with the shareable report directory. The DuckDB adapter owns an in-memory
+connection per execution, uses one thread, an explicit 128 MB engine memory
+limit and UTC session setting, then materializes and closes before returning.
+The script rereads and verifies `read_migration` after that return.
+
+The recipe does not open a shared DuckDB file, download extensions or execute
+external SQL. The plan has no temporal values: UTC does not prove unsupported
+date operations. Budgets remain cooperative, not a hard process-RSS quota.
+Passing an actual `DuckDBPyRelation` directly to `diff` authorizes bounded native
+materialization; SQL strings and connections are not accepted as data inputs.
+Explicit capture or an adapter remains available when session ownership and SQL
+execution controls are required. The example does not expand the IR or prove all
+possible inputs valid.
+
+## 4. Keep evidence before failing pytest or CI
+
+```bash
+python -I ../kit/assertion_ci.py --case equivalent --output ci-ok
+python -I ../kit/assertion_ci.py --case different --output ci-different
+python -I ../kit/assertion_ci.py --case not_evaluable --output ci-limited
+```
+
+Expected exits **0, 1 and 3**. The script exports and verifies a report **before**
+calling `ef.assert_equivalent`. Failures retain JSON/text/HTML diagnostics and
+`evidence-manifest.json`. `assert result` and `if result` raise `TypeError` in all
+three comparison states.
+
+Run the real pytest fixture with a new output location for each selected case:
+
+```bash
+python -I -B -m pytest -q -o addopts= -p no:cacheprovider ../kit/test_assertion_recipe.py -k equivalent
+python -I -B -m pytest -q -o addopts= -p no:cacheprovider ../kit/test_assertion_recipe.py -k different
+python -I -B -m pytest -q -o addopts= -p no:cacheprovider ../kit/test_assertion_recipe.py -k not_evaluable
+```
+
+Pytest exits **0, 1 and 1** respectively. The final two are deliberately failing
+tests, not `xfail`. Reports are under `ci-reports/<case>/`. Repeat from another
+clean working directory that still points to the kit; never overwrite evidence.
+`-B` prevents bytecode being created alongside the fixture. In your real pipeline,
+provide your actual candidate/reference pair rather than a synthetic case
+selector masquerading as validation.
+
+Before uploading a report directory, verify the closed inventory with the
+provided script:
+
+```bash
+python -I -c "import runpy; from pathlib import Path; recipe = runpy.run_path('../kit/assertion_ci.py'); recipe['verify_upload_directory'](Path('ci-different'))"
+```
+
+Run this check even if the test fails (`always()` or your CI equivalent). Upload
+only the four verified report files, and preserve the test's nonzero exit status.
+If publication or manifest verification fails, do not publish a success artifact.
+Do not upload `--work-dir`, environments, snapshots, checkout files or raw JSONL.
+This recipe produces a real local artifact; it does not claim a remote CI job ran.
+
+## 5. Change a baseline or contract deliberately
+
+There is no automatic "accept all" or reference-update operation. Inspect types,
+values, keys, coverage and policy; fix an erroneous candidate. If a business
+requirement genuinely changed:
+
+1. Preserve the failed report, prior reference and their hashes
+2. Record the precise change, rationale, responsible person and review
+3. Create a new contract revision before comparison, changing only the approved
+   policy. Generate/review a new expected output independently; never blindly
+   copy the failed candidate
+4. Test success, a real difference, an invalid expected result and interruption
+5. Version the approved baseline and contract; review the change in a PR
+
+`ef.read_diff_contract(result)` returns the inspectable declaration.
+`DiffContract.model_validate_json(...)` rereads a saved declaration, and
+`ef.diff(candidate, expected, contract=declaration)` reuses it exactly. Neither a
+baseline change nor a new tolerance should be silently learned from a failure.
+The recipes do not modify your external baselines.
+
+## Troubleshooting and recording the attempt
+
+Use Python 3.12, a clean environment, unchanged pins and fresh directories. Check
+`pip check` and the import location. Exit 1 is expected in deliberate negative
+examples; exit 3 means the requested judgment was not established; exit 2 denotes
+invalid configuration/execution/publication in these scripts. Missing permissions,
+disk space or a finalized report never mean equivalence. Do not publish tracebacks
+containing environment variables or real data.
+
+Keep `kit` intact and recheck it with `python ../kit/verify_kit.py`. Save a completed
+copy of `OBSERVATION.md` in the work directory. Record installation time separately,
+include failed attempts and help received, and distinguish engine agreement from
+correctness against a reference. [Semantics](semantics.md) and
+[upgrading](upgrading.md) explain the guarantees and failures in more detail.

equiframe/docs/releasing.md

@@ -0,0 +1,183 @@
+# Candidate, release, withdrawal and rollback
+
+## Current state
+
+The release target is `equiframe 0.12.4` with the exactly paired
+`equiframe-benchmark 0.12.4`, identified by commit and artifact SHA-256.
+Source preparation does not establish validation or publication: verify the
+artifact-bound receipts and official index inventory. The public 0.12.2 tag and
+its receipts retain their original identities. The local 0.12.3 candidate tag
+and checks are also preserved; that candidate was not uploaded. The new patch
+must pass its own checks and must not replace previous candidate bytes.
+On 2026-10-27 the owner authorized manual publication to TestPyPI followed by
+PyPI after the release checks pass. Publication is established by the observed
+index inventories and clean downloaded consumers, not by this guide or a build.
+
+Hernán Troya (`htroya`) accepted maintenance, release and security responsibility.
+No response-time SLA or staffed on-call coverage is promised. Accounts, 2FA,
+name control, public documentation and private security intake must be verified
+for the selected target. A name lookup does not reserve a package name.
+
+Original project code and accompanying materials use MIT. Each distribution
+carries LICENSE and THIRD_PARTY_NOTICES.md. Vendored CycloneDX schemas retain
+Apache-2.0; the core artifact metadata records the combined licensing terms.
+See [license scope](licensing.md) and [offline wheel installation](installed-private.md).
+
+The version-2 release policy separates the nine technical checks from factual
+publication gates: security/dependency review, rights, public documentation,
+account protection, independent artifact review and the owner's current task.
+UNKNOWN, missing or failed gates block publication. A temporary packet binds
+observations to the exact commit, four artifacts, destination and date; it does
+not authenticate a human or grant permission by itself. The inspector never
+uploads files or handles credentials. Publication remains a separate manual act.
+
+TestPyPI is a public index with separate accounts. Upload only the four approved
+files, download them again, verify every SHA-256 and exercise a clean consumer.
+Promote those same four bytes to PyPI only after this succeeds. Rebuilding or
+changing a file requires new checks. TestPyPI can use an ephemeral local API token
+supplied through a hidden terminal prompt and revoked after upload. Never store
+that token in a repository, a report or GitHub secrets.
+
+On 2026-10-28 the owner explicitly selected local manual publication and
+instructed this release not to use GitHub Actions. A newly prepared OIDC
+workflow was withdrawn before use. GitHub jobs are not a prerequisite for this
+manual release route; no environment or publisher configuration is implied.
+
+For each index, use its official endpoint and a uniquely named temporary token
+created under the authenticated maintainer account. Pass it through a native
+hidden terminal prompt, upload only the four identified files, then revoke it.
+Keep the exact artifact hashes, account protection and downloaded-consumer
+checks; changing the authentication route does not waive them. Neither account
+passwords nor API tokens belong in source, reports, GitHub secrets or shell
+history.
+
+## Tagged versions
+
+Hatch and `hatch-vcs` derive both distributions from the same reviewed Git tag
+`vMAJOR.MINOR.PATCH`. Runtime versions come from installed distribution metadata.
+There is no second manually maintained runtime version and no silent fallback
+release number. A source archive retains its package metadata so rebuilding the
+sdist does not require Git history. Release checks reject an absent/mismatched
+tag, dirty or noncanonical source, and SCM version overrides.
+
+Create the tag only after the complete source revision is reviewed and committed.
+Use a new patch version for documentation or compatible fixes; use a minor
+version for compatible new functionality and explicitly document breaking
+changes. During the `0.x` series, read the compatibility and upgrade guides.
+Never move an existing release tag or replace published TestPyPI/PyPI files.
+
+Historical Alpha candidates keep their original results and closed version-1
+policy. STEP10's real-data evaluation, external scientific acceptance and DW
+integration remain separate research/integration deliverables; they are not
+claimed complete by a library release.
+
+## Repeatable candidate checks
+
+From the repository root, select the supported Python interpreter for the chosen
+profile. The driver uses each package's exact `uv.lock` and supports the benchmark
+with `--package`:
+
+```sh
+python tools/check_candidate.py \
+  --package . --output /absolute/evidence/core-checks.json
+python tools/check_candidate.py \
+  --package packages/equiframe-benchmark --output /absolute/evidence/benchmark-checks.json
+```
+
+Each driver checks locked sync, Ruff check/format, mypy, generated assets, the
+full pytest suite, build, strict Twine validation and installed distribution
+consumption. The final distribution stage uses clean environments outside the
+checkout, exercises optional profiles/recipes, runs shipped tests against
+site-packages and compares both rebuilt wheel and sdist bytes. A passing wheel
+rebuild alone is not a claim about every compiler, platform or dependency build.
+Source snapshots, exact artifact hashes and loaded local dependency bytes bind
+the receipts; they do not authenticate the executor. Keep receipts outside the
+source tree so writing them does not change the source being checked.
+
+Candidate checks and manifest generation also require every package and local
+dependency file to match its raw Git HEAD blob. A clean `git status` is not
+enough: automatic line-ending or other Git filter conversions can change the
+bytes that a build packages. On Windows, use a fresh checkout with both
+`core.autocrlf=false` and `core.eol=lf`, for example:
+
+```text
+git clone --config core.autocrlf=false --config core.eol=lf <repository> <fresh-directory>
+```
+
+Changing these settings in an existing checkout does not rewrite already converted
+files. Rebuild from the canonical checkout; do not normalize an artifact to make
+the verification pass.
+
+After freezing a clean commit, run `tools/release_manifest.py` with the exact
+receipts for both packages. Inspect the independent compatibility matrix, the
+installed consumer report, dependency inventory, licenses and dated advisories,
+source review coverage and all unresolved decisions. Build tools and versions
+must be identical for a byte-for-byte reproduction claim.
+
+A candidate directory containing both manifests and their adjacent wheel/sdist
+files can be checked with:
+
+```sh
+python tools/verify_publication.py \
+  --candidate-root /absolute/candidate --commit EXACT_40_CHARACTER_SHA \
+  --target testpypi --gate-packet /absolute/temporary/testpypi-gates.json \
+  --output /absolute/evidence/publication-readiness.json
+```
+
+Malformed, stale, incomplete, linked or substituted artifacts are rejected.
+For the current version-2 policy, exit **0** means that the technical receipts
+and all factual gates for the selected index passed; missing, UNKNOWN or failed
+gates block readiness with a nonzero exit. Use `--target pypi` and a separate
+packet after verifying the TestPyPI downloads and consumer installation.
+Historical version-1 candidates retain their closed policy and exit **3**.
+There is no `--force` or credential switch. The packet does not authenticate
+human approval, and this command never uploads or grants account access.
+
+## Local checks and provenance
+
+The public repository ships no GitHub Actions workflows. Run the local candidate
+commands above and retain their exact source identities, environment details,
+exit codes and artifact hashes. A local receipt establishes only the work it
+records; it does not establish that a remote CI job ran. Dependency advisories
+are separate networked checks and retain unknown or unavailable outcomes.
+
+Publication is manual with a local ephemeral credential. A future adoption of
+Trusted Publishing requires a separately reviewed protected workflow and real
+publisher configuration; OIDC is not configured or used for this release.
+
+## Correcting a defect
+
+1. Record exact affected commits, wheel hashes, APIs/adapters, policies and
+   environments. Preserve a sanitized reproducer and independent expected result
+2. Assess exposure and whether the claim of equivalence, privacy or evidence
+   integrity is affected. Stop recommending the affected route if the judgment
+   can be wrong; fail closed rather than silently weakening the contract
+3. Assign an owner before promising a date. Implement a regression test and
+   narrow correction. Re-run the relevant historic corpus, full gates, installed
+   recipes and affected compatibility cells on new immutable artifacts
+4. Refresh SBOM/advisory/license evidence and publish release notes describing
+   behavior changes, affected versions, migration and remaining limitations
+5. Obtain the required release approval and distribute a new version. Public
+   artifacts are immutable: do not overwrite a released version with new bytes
+
+## Withdrawal and rollback
+
+For a private candidate, stop distributing the affected hash and notify only
+its authorized recipients through verified channels. Keep the incident record
+and superseded evidence so results can be traced. For a future public release,
+the assigned owner must approve the appropriate advisory and index action;
+yanking is a selection signal, not deletion of all installed copies or pinned
+references. Deletion is a separate, potentially irreversible action.
+
+Test rollback in a **new environment** using the previous known-good exact
+artifacts and their matching pinned dependencies. Verify hashes, imports,
+`pip check`, recipes and historic evidence readers before replacing a consumer
+service. Rollback must not rewrite user evidence or downgrade a versioned file
+format silently. If a new format is unreadable by the old version, retain the
+new reader in an isolated environment or use an explicitly reviewed migration.
+Never infer compatibility from equal version numbers on private candidates.
+Re-running old tests with a new hash is a new receipt, not a historic result.
+
+Official background: [Python packaging](https://packaging.python.org/en/latest/tutorials/packaging-projects/),
+[PyPI attestations](https://docs.pypi.org/attestations/),
+[PyPI yanking](https://docs.pypi.org/project-management/yanking/)