@1aboveio/skills 1.0.9 → 1.0.11

package/skills/risk-compliance/tld-detection/references/fx-conversion.md

@@ -1,232 +1,69 @@
-# BIN-country base-currency FX sensitivity
+# Reproducible currency views
 
-Use this supplemental path when the user asks to convert transaction amounts
-to the card-origin currency, or when daily FX drift may conceal fixed local-
-currency anchors. Run it after canonical original-currency membership is
-complete. It is sensitivity evidence, not a replacement clustering universe.
+Create USD and BIN-country-currency views from the same cleaned transaction
+universe. Map each normalized BIN country to legal tender in effect on the
+transaction date, preferably using ISO 4217 current and historic lists. Record
+source, dated country-to-currency map and target minor units. Missing or
+ambiguous mappings, including multiple legal tenders or transitions without a
+declared justified choice, exclude the row from the BIN-country view, not USD.
+Never infer country currency from descriptor, language, IP or transaction currency.
 
-## Separation contract
+## Frankfurter v2 acquisition
 
-- Reuse the canonical cleaned authorization rows and descriptor normalization.
-- Keep canonical `C*` results unchanged.
-- Name supplemental families `FXC1`, `FXC2`, ... and publish separate files
-  such as `<scope>_bin_base_currency_clusters.md` and
-  `<scope>_bin_base_currency_methodology.md`.
-- Do not combine `C*` and `FXC*` attempts into one exposure total because the
-  same authorization may belong to both views.
-
-## Target currency
-
-Map normalized BIN country to the legal tender in effect on the transaction
-date. Use the ISO 4217 Maintenance Agency's current and historic lists as the
-preferred source for currency and minor unit, and record the complete run-
-specific country-to-currency map and source.
-Do not infer currency from language, descriptor, terminal country, shopper IP,
-or transaction currency. For countries with several legal tenders or a
-currency transition during the window, declare and justify the dated mapping;
-exclude ambiguous rows rather than silently choosing one.
-
-Missing BIN country remains in the canonical run but cannot be assigned a BIN-
-origin currency. Count it as an FX exclusion under
-`missing country-currency mapping`.
-
-## Frankfurter v2 rates and cache contract
-
-Frankfurter v2 is mandatory for this sensitivity. Its public API requires no
-API key or other authentication. Before retrieval, choose and disclose either
-`default blended` or one or more named provider keys. The default blend is a
-real provider-selection decision: omit the `providers` filter from the URL and
-state that Frankfurter blended all eligible providers. For a named selection,
-append `&providers=<comma-separated-provider-keys>` and record those exact
-filter keys. In both modes, `expand=providers` is mandatory so the response
-identifies the providers that actually contributed to each non-peg row.
-
-Every request uses this exact endpoint and includes all five required query
-parameters, even for a one-day window. A named-provider request also includes
-the optional `providers` filter:
+Use the immutable, versioned Frankfurter v2 cache for both views. Select either
+`default blended` (omit `providers`) or named provider keys before retrieval;
+record the selection. `expand=providers` identifies contributors and does not
+select them. Request inclusive UTC transaction-date bounds, pivot `P`, and sorted
+deduplicated source and target quotes, even for a single day:
 
 ```text
 GET https://api.frankfurter.dev/v2/rates?from=<YYYY-MM-DD>&to=<YYYY-MM-DD>&base=<P>&quotes=<comma-separated-currencies>&expand=providers
 GET https://api.frankfurter.dev/v2/rates?from=<YYYY-MM-DD>&to=<YYYY-MM-DD>&base=<P>&quotes=<comma-separated-currencies>&expand=providers&providers=<comma-separated-provider-keys>
 ```
 
-`from` and `to` are the inclusive UTC transaction-date bounds, `base` is the
-declared pivot currency `P`, and `quotes` is the sorted, deduplicated set of
-source and target currencies needed by the run. `expand=providers` requests
-row-level contributing-provider keys; it does not select a provider and does
-not replace the optional `providers` filter. Do not use the v1 nested response,
-`/latest`, or an implicit latest date. A returned row means that its `rate` is
-quote-currency units per one unit of its `base` currency: with `base=P`,
-`rate(d, P→Q)` is units of `Q` per one unit of pivot `P`.
-
-Write the response to
-`reports/tld-detection/<scope>_frankfurter_v2_rates.cache.json`. Create this
-run-specific cache once, do not overwrite it, and record its SHA-256 in the
-methodology. The cache schema is versioned and contains at least:
-
-```json
-{
-  "schema_version": 1,
-  "api": "Frankfurter",
-  "api_version": "v2",
-  "endpoint": "https://api.frankfurter.dev/v2/rates",
-  "cache_created_at_utc": "<ISO-8601 UTC timestamp ending Z>",
-  "requests": [
-    {
-      "request_url": "<complete run-specific request URL>",
-      "retrieved_at_utc": "<ISO-8601 UTC timestamp ending Z>",
-      "provider_selection": {"mode": "default blended", "providers": []},
-      "query": {"from": "<date>", "to": "<date>", "base": "<P>", "quotes": ["<Q>"], "expand": ["providers"]},
-      "returned_facts": [
-        {"date": "<date>", "base": "<P>", "quote": "<Q>", "rate": "<positive decimal>", "providers": ["<contributing-provider-key>"]}
-      ]
-    }
-  ]
-}
-```
-
-Preserve every returned `date`, `base`, `quote`, and unrounded `rate` fact and,
-when Frankfurter returns it, the complete `providers` key array exactly as
-returned. An omitted `providers` member means Frankfurter marked that fact as
-peg-derived; it is not unknown provenance. Preserve the omission rather than
-writing `[]`, `null`, a guessed provider, or the request's selected providers.
-For named-provider requests, `provider_selection` and the optional URL/query
-filter record what was requested; add `"providers": ["<provider-key>"]` to the
-cached `query`. Each fact's `providers` array records which of those providers
-actually contributed; peg-derived facts still omit the member. The methodology
-repeats the cache path, complete request URL or
-URLs, UTC retrieval timestamp or timestamps, provider selection, query
-bounds/pivot/quotes/expansion, row-level provider identities and peg-derived
-omissions, schema version, and cache SHA-256. Never rely on a later live refetch
-to reproduce a run.
-
-Fail closed before conversion when the cache is missing; `schema_version` is
-missing or unsupported; a legacy/v1 cache is supplied; required metadata or a
-`date`/`base`/`quote`/`rate` fact is absent; the endpoint, complete URL, parsed
-query (including `expand=providers` and any provider filter), provider
-selection, retrieval timestamp, requested window, pivot, or quotes do not match
-the run; a present fact-level `providers` member is not an array of provider
-keys; a returned provider key was not preserved; a rate is non-positive; or
-duplicate facts conflict. Do not repair a cache mismatch by refetching during
-analysis and do not treat an invalid cache as ordinary row-level FX exclusions.
-
-## Conversion
-
-For each authorization on UTC transaction date `d`, with source currency `S`,
-target BIN-origin currency `T`, source amount `a`, and API quotes expressed as
-currency units per pivot currency `P`:
-
-```text
-base_amount = a / rate(d, P→S) × rate(d, P→T)
-```
-
-Use `1` when `S = P` or `T = P`. If either required non-identity quote has no
-returned fact whose `date` is exactly `d`, exclude that authorization. Never
-fill weekends or missing dates with a prior-business-day, monthly average,
-latest, or next-day rate.
-
-Count exclusions by reason, date, and currency. Report:
-
-```text
-canonical cleaned attempts → exact-date converted attempts → FX exclusions
-```
-
-## Converted partition universe
-
-For each frozen canonical descriptor partition `D`, define:
-
-```text
-P_FX(D) = authorization attempts in D successfully converted using exact-date
-          Frankfurter v2 facts under the validated cache contract
-|P_FX|  = the attempt count of P_FX(D) for the current descriptor partition
-```
-
-Identity legs valued at `1` remain exact-date conversions; every non-identity
-leg must have the matching returned date/base/quote/rate fact. Rows excluded
-for mapping, quote, or conversion reasons are not in `P_FX`.
-
-Compute FX candidate counts and both FX thresholds only from `P_FX` in the
-current descriptor:
-
-| Set | FX membership |
-|---|---|
-| High-count (seeds) | union of (a) FX pairs with count ≥ `max(30, 0.5% of \|P_FX\|)`, (b) the `P_FX` partition top 25 FX pairs by count, and (c) per target currency in `P_FX`, the top 10 FX pairs with count ≥30 |
-| Rung pool | FX pairs with count ≥ `max(5, 0.1% of \|P_FX\|)` |
-
-State the resulting thresholds per descriptor. FX-excluded rows never enter
-these denominators, rankings, rung pools, families, baselines, or cluster
-metrics. They remain only in exclusion coverage and reconciliation back to
-canonical `U`:
-
-```text
-|U_D| = |P_FX(D)| + |FX exclusions in D|
-|U|   = sum_D |P_FX(D)| + all FX exclusions
-```
-
-## Rounding and keys
-
-Round converted values once, half-up, to the target currency's ISO 4217 minor
-unit in effect on the transaction date. Record the exponent table actually
-used. Do not round rates before conversion.
-
-Inside each frozen descriptor partition, define the supplemental key as:
+Create `reports/tld-detection/<scope>_frankfurter_v2_rates.cache.json` once per
+run; never overwrite it. Record its SHA-256 and schema version. The cache must
+contain `schema_version: 1`, `api: Frankfurter`, `api_version: v2`, endpoint,
+`cache_created_at_utc`, and a `requests` array. Each request records complete
+`request_url`, `retrieved_at_utc`, `provider_selection` with `mode` and
+`providers`, parsed `query` (`from`, `to`, `base`, `quotes`, `expand`, plus
+`providers` for named selection), and `returned_facts`. Preserve every returned
+fact's date, base, quote and unrounded positive rate, and the complete contributor
+`providers` array exactly as returned. If that member is omitted, preserve the
+omission: it denotes a peg-derived fact, not an empty or guessed provider list.
+Record request URLs, UTC timestamps, provider selection, contributors and peg
+omissions, query bounds, pivot, quotes, cache path and hash in methodology.
+
+Fail closed before conversion for a missing, unsupported, incomplete or legacy
+cache, invalid timestamps or facts, nonpositive rates, conflicting duplicates, or
+mismatch between the run and endpoint, full URL, parsed query, provider filter,
+selection, bounds, pivot or quotes. A present fact `providers` must be an array
+of provider keys; preserve returned contributors. Do not repair a mismatch by
+refetching during analysis or classify an invalid cache as row-level exclusions.
+Never use `/latest`, v1 or a later live refetch to reproduce the run.
+
+## Conversion and reconciliation
+
+For transaction UTC date `d`, source `S`, target `T`, pivot `P`, and source amount
+`a`, with quote rates in units of currency per unit of pivot:
 
 ```text
-(target BIN-origin currency, rounded base_amount)
+converted = a / rate(d, P→S) × rate(d, P→T)
 ```
 
-Apply the fixed 2x, three-level, multi-anchor support, disjointness, and ≥100
-exact-member gates as the canonical detector after applying the `P_FX`-only
-high-count and rung-pool thresholds above. Final FX membership is exact
-equality on descriptor, target currency, and rounded base amount; tolerance is
-discovery-only.
-
-Scale absolute residual caps in target-currency minor units. A defensible
-starting sensitivity grid is 1, 2, and 5 minor units, retaining the smallest
-cap under which material paths are stable. Report currency-specific cluster
-counts and covered attempts; do not repeat the portfolio-wide total on every
-currency row.
-
-## Baseline, risk, and reporting
-
-For each `FXC*` family, the comparison baseline uses only `P_FX` for the same
-frozen canonical descriptor and removes that family's exact FX keys. FX-
-excluded rows cannot enter the same-descriptor baseline. Show exposure against
-both the converted universe and all canonical cleaned authorization attempts.
-Reconcile identified FX attempts + converted baseline + FX exclusions to the
-canonical cleaned universe.
-
-BIN country causally determines target currency in this view. Therefore:
-
-- show BIN-country composition and descriptor-country slice coverage;
-- caption exact 100% single-country concentration as descriptive and
-  constructed by the target-currency mapping;
-- do not count country concentration as independent risk evidence;
-- do not raise the FX tier because of country concentration;
-- assign High/Medium/Low using only structural and other independent
-  `P_FX` same-descriptor characteristics.
-
-Use the three-section main report, complete linked evidence, and methodology
-layout in [report-template.md](report-template.md), with separate FX filenames
-and revision-qualified paths. Put the consolidated per-cluster table in FX
-evidence, not the concise main report.
-Keep the anchor table and BIN-country attribution table separate because they
-are one-to-many detail, not duplicate cluster facts. Include the same four
-charts as the canonical report and label converted anchors with their target
-base currency.
-
-## FX audit checklist
-
-- [ ] Canonical cleaned universe and `C*` results were frozen first
-- [ ] As-of-date country-to-legal-tender mapping and minor units are recorded
-- [ ] Frankfurter `/v2/rates` uses explicit `from`, `to`, `base`, `quotes`, and `expand=providers`; authentication is not required
-- [ ] Provider selection/default blend, complete request URL, UTC retrieval time, returned facts with contributing provider keys or documented peg-derived omission, cache path/SHA-256, and supported cache schema version are recorded
-- [ ] Missing, mismatched, incomplete, or legacy cache facts fail closed before conversion
-- [ ] Formula supports non-pivot source currencies
-- [ ] Exact-date no-fill coverage and every exclusion are reconciled
-- [ ] Per descriptor, `|P_FX|` is only exact-date-converted attempts; thresholds and same-descriptor baselines use only `P_FX`
-- [ ] `FXC*` membership uses exact descriptor + target currency + rounded amount
-- [ ] Caps and sensitivity are expressed per currency in minor units
-- [ ] Country concentration is descriptive and excluded from FX risk evidence
-- [ ] Converted and all-authorization exposure denominators are both shown
-- [ ] `C*` and `FXC*` exposure are never added together
+An identity leg equals 1. Every non-identity leg needs an exact-date fact; do
+not fill missing dates using earlier, later, monthly or latest rates. Keep rates
+unrounded; round the final amount once, half-up, to the target currency's dated
+ISO minor unit. Record the exponent table. Each converted amount key contains
+MID, normalized descriptor, target currency and rounded amount. Concentration and
+escalation use exact selected keys; pricing fits retain their frozen transaction
+IDs as described in [pattern.md](pattern.md).
+
+Report each view's source count, converted count and exclusions by reason, date,
+currency and scope. Reconcile source = converted + excluded independently for
+both views; USD and BIN-country results may contain the same transaction. Each
+partition's selection thresholds, group profiles and out-group baseline use only
+successfully converted transactions in that view and target currency. Exclusions
+are not baseline. Combine overlapping groups or views only by the union of
+transaction IDs. BIN country constructs the BIN-country target, so its
+concentration cannot independently raise investigation priority.

package/skills/risk-compliance/tld-detection/references/metric-contract.md

@@ -0,0 +1,109 @@
+# Script and metric contract
+
+## Input: prepared transactions (schema version 1)
+
+`tld_common.py` validates this JSON boundary. FX preparation remains governed by
+[fx-conversion.md](fx-conversion.md); these scripts do not fetch rates or infer
+country-to-currency mappings. Supply the prepared amounts and retain conversion
+provenance with the run. Missing conversion is an exclusion, never a zero amount.
+
+```json
+{
+  "schema_version": 1,
+  "period": {"start": "2026-01-01", "end": "2026-01-03", "timezone": "UTC"},
+  "transactions": [{
+    "transaction_id": "T1", "transaction_time": "2026-01-01T12:00:00Z",
+    "currency": "USD", "amount": "10.00", "mcc": "5999",
+    "billing_descriptor": "SHOP", "mid": "M1", "card_scheme": "Visa",
+    "card_bin": "411111", "card_issuer": "Example bank", "card_bin_country": "US",
+    "authorized": true, "suspected_fraud": false,
+    "views": {
+      "usd": {"currency": "USD", "amount": "10.00"},
+      "bin_country": {"currency": "USD", "amount": "10.00"}
+    }
+  }]
+}
+```
+
+Dates are inclusive in the declared IANA reporting timezone. Transaction times
+must have an explicit offset; reject naive timestamps. Convert to reporting-local
+date/hour before selecting the window. Money is a finite nonnegative decimal
+string, never a binary float. Required identity and business fields are nonempty
+strings; `card_bin_country` alone may be null, which excludes the BIN-country view.
+Both view keys are required. An excluded view has
+`{"excluded_reason":"missing exact-date quote"}` instead of currency/amount.
+Authorization and suspected-fraud values are independently true, false or null;
+missing optional status fields become null, never false. Do not infer one from
+the other. Exact duplicate transaction records may be removed; conflicting records
+with one ID fail validation. Original currencies are uppercased and descriptor
+case/whitespace normalized; MID remains a separate key. Reject malformed rows
+rather than silently dropping them. Out-of-period rows are counted in the census.
+
+## Shared Python interface
+
+`load_dataset(path)` reads and validates JSON. `validate_dataset(payload)` returns
+a normalized dataset; `dataset_sha256` binds its reporting period and normalized,
+deduplicated in-period transaction content, sorted by ID. `view_rows(data)` returns
+one row per eligible transaction/view with `view`, target `currency` and `amount`,
+`charge_currency` and `charge_amount`, normalized `descriptor`, `date` and `hour`,
+and the original identity/status/dimension fields. Amounts remain decimal strings.
+`scope_of(row)` returns `mid`, `descriptor`, `view`, `currency`.
+
+Detection output is a group manifest:
+
+```json
+{
+  "schema_version": 1,
+  "dataset_sha256": "<normalized dataset digest>",
+  "period": {"start": "2026-01-01", "end": "2026-01-03", "timezone": "UTC"},
+  "groups": [{
+    "id": "G1", "pattern": "concentration",
+    "scope": {"mid":"M1", "descriptor":"shop", "view":"usd", "currency":"USD"},
+    "member_ids": ["T1"], "details": {}
+  }]
+}
+```
+
+Allowed patterns: `concentration`, `escalating`, `pricing`. Each group has a unique
+nonempty ID and a nonempty, duplicate-free member list. `validate_groups(data,
+payload)` returns validated groups after checking schema, period, digest, known
+IDs, exact scope, and conversion eligibility. Reject cross-scope, excluded, stale
+or unknown membership. Different groups and views may share transaction IDs.
+
+## Metric definitions
+
+For group G, out-group B is all eligible transactions in the identical scope and
+reporting period minus G. Each population has its own denominator. Rates are
+fractions in JSON (0–1), displayed as percentages in charts.
+
+| Metric | Numerator | Denominator / behavior |
+|---|---|---|
+| Transaction count | Unique transaction IDs | Count, including all statuses |
+| Payment success rate | `authorized == true` | Population transaction count; null if count is zero or any authorization status is unknown |
+| Suspected-fraud rate | `suspected_fraud == true` | Population transaction count; null if count is zero or any fraud status is unknown |
+| Status coverage | Transactions with known corresponding status | Population transaction count; null for empty populations |
+| Daily share | Population count that local date | That population's whole-period count; null if population is empty |
+| Hour count | Population transactions at local hour 00–23 | Counts, not rates; repeated DST hours combine and nonexistent hours stay zero |
+| Daily amount-tier count | Population transactions in tier on date | Same explicit tiers for G and B; conserve the daily transaction count |
+
+Produce period totals plus one daily record for every date, 24 period-hour counts,
+and date-by-hour counts. Zero-fill counts; do not turn unavailable rates into zero.
+Always include rate numerators and unknown counts. Default tiers are each exact
+selected group amount plus `other`; an optional sorted decimal edge list defines
+half-open bins `[lower, upper)`, with unbounded first/last bins. Record the tier
+scheme and retain all outside-group amounts. Sum tier and hour counts to daily
+and period totals as reconciliation checks. Combined exposure is the union of
+member IDs, never the sum of overlapping group counts.
+
+## Outputs and charts
+
+`profile_groups.py` writes schema-versioned JSON containing dataset binding,
+period, census, group scopes/membership, out-group membership, tiers and metrics.
+`render_charts.py` consumes only that saved profile and writes standalone offline
+HTML with SVG charts and accessible data tables. Required paired views are daily
+amount-tier counts, daily success/fraud rates, daily transaction counts, daily
+shares, and 24-hour counts. Include date-by-hour detail and status coverage.
+Use the same axes and tier definitions for both populations; gaps/unknown rates
+remain N/A. Escape source labels as text. No CDN, live FX request or recomputation
+of transaction metrics belongs in rendering. Outputs refuse overwriting existing
+files unless explicitly requested with `--overwrite`.

package/skills/risk-compliance/tld-detection/references/pattern.md

@@ -0,0 +1,99 @@
+# Patterns
+
+Evaluate all three patterns inside the MID/descriptor and currency-view scopes
+in SKILL.md. Record each method's parameters, tested population, coverage and
+exact transaction IDs. Patterns may overlap; one pattern's selection must not
+remove transactions from another pattern's search. Use the same profiling and
+rating workflow for every eligible group. Names describe observations or
+hypotheses, not verified business activity.
+
+## 1. Amount concentration
+
+Count exact converted amounts, such as 8.00 or 9.9. Select keys meeting the
+run's declared minimum transaction count and share; record the denominator.
+A single price may qualify without an escalating sequence. No calibrated
+universal concentration threshold is supplied.
+
+## 2. Escalating amounts
+
+Look for doubling amounts such as 8 → 16 → 32 → 64. Default to at least three
+levels and 100 transactions; these gates apply only to escalation.
+For positive amounts `a < b`, the adjacent residual is `abs(b - 2*a)`.
+Require it to be within the declared currency-specific absolute cap and strictly
+less than `a/2`: the fit must be closer to 2x than to 1x or 3x. Ties fail.
+
+Test a cap sensitivity grid and record the chosen cap per currency. Search upward
+and downward from candidate seeds. A level may retain multiple exact anchors;
+record the additional-anchor support floor. Tolerance selects a finite set of
+amount keys, never every transaction in an interval. Freeze their member IDs.
+
+## 3. Pricing patterns
+
+Look for a coherent price menu or retail-price structure, including patterns
+that conversion makes variable in the charge currency. Preserve original charge
+amounts and dates alongside the two converted views.
+
+| Form | Evidence to test | Interpretation limit |
+|---|---|---|
+| Preset menu | Repeated prices such as 10, 20, 50, with sufficient support and coverage above a jittered control | A menu need not double; escalation's three-level/100-transaction gates do not apply |
+| FX-converted menu | Dated conversion into a candidate pricing currency makes charges align with supported presets | Inferred pricing currency can differ from both charge currency and BIN-country currency |
+| Retail-like prices | Several distinct prices ending in .99, .95, .98 or .00, possibly after dividing by a fitted constant | A fit does not establish goods, tax, fees or fulfillment |
+
+Declare support, coverage, tolerance and control criteria before accepting a
+pricing group. Test candidate currencies and daily drift; BIN-country legal
+tender is a candidate, not proof of pricing currency. For a supported top-up
+hypothesis, use **direct** when inferred pricing currency equals original charge
+currency, and **FX-converted** otherwise. Split mixed charge currencies correctly.
+Do not infer a top-up from the charge currency alone.
+
+Fixed amounts are a supplementary feature, not another pattern. Fixed FX needs
+stable charges alongside measured source-to-pricing-currency rate movement and
+adequate day coverage. Same-currency fixed prices do not demonstrate fixed FX;
+untested or raw `live` labels do not establish floating FX.
+
+Freeze pricing membership by transaction ID, preserving the matched prices,
+source currencies, dates, inferred currency and fit rule. Unlike concentration
+or escalation, date-varying pricing membership cannot be reconstructed from a
+single converted amount list. Reconcile those IDs into each reporting view's
+eligible partition, report exclusions, and profile each resulting group against
+that partition's out-group. An inferred pricing currency is explanatory evidence,
+not a third reporting view. If country was used to select members, its concentration
+is not independent rating evidence. Keep other/insufficient-evidence rows visible.
+
+## Detection engines
+
+The canonical `detect_patterns.py` interface reuses `detect_ladders.py` and
+`detect_streams.py` as internal engines. Their standalone CLIs remain available
+for compatibility, but use the canonical interface in SKILL.md for new runs. The
+canonical manifest preserves member IDs, parameters and diagnostics for all three
+independent detections.
+
+Escalation uses prepared converted amounts. Its rung pool requires count >=
+max(5, 0.1% of partition transactions); additional anchors default to 24
+transactions. Each exact key can belong to only one reported ladder per partition;
+below-threshold families do not reserve keys. Other pattern types may overlap.
+Record cap sensitivity and validate keys and counts.
+
+Pricing discovery uses original charges once per MID, descriptor, source currency
+and BIN-country group, with at least 80 positive transactions. Zero amounts remain
+available to concentration but provide no pricing support. Freeze discovered IDs,
+then project them into each eligible reporting partition without reapplying the
+80-row gate. Record projected exclusions. Peak and menu tolerances default to 1.2%
+and 1.5%; all parameters and diagnostics are saved in the manifest.
+
+Candidate generation uses the existing float-based heuristic; final retail and
+menu membership use exact rational checks. Quotes, cross-rates and positive source
+amounts must be between 1e-100 and 1e100 inclusive, and converted candidates at least
+0.005 for the cent-based peak engine. Unsupported inference ranges fail explicitly;
+they are not treated as missing FX. Original decimal values and source/target quote
+strings are retained in evidence. Exact final checks do not make heuristic discovery
+exhaustive. Small groups or missing quotes are not evidence of absent pricing.
+
+The optional `--pricing-rates` adapter is JSON of the form
+`{"base":"USD","rates":{"2026-01-01":{"EUR":"0.9"}}}`. Rates are decimal
+strings in units of quote currency per base unit, from validated exact UTC-date
+quotes. No prior-date carry or implicit pegs are used; same-currency conversion
+needs no quote. The detector selects quotes by UTC transaction date, independently
+of the reporting timezone used for profiles. The adapter does not fetch rates
+or convert the prepared reporting views. Retain its provenance and reconcile
+missing quotes; see [fx-conversion.md](fx-conversion.md).