@1aboveio/skills 0.20.2 → 0.20.4

package/skills/payment/tld-detection/references/decision.md

@@ -21,6 +21,11 @@ Risk uses independent post-membership evidence:
 - transaction-date and BIN-country-local-hour differences versus that baseline
 - externally evidenced MCC or merchant-business mismatch; never infer this
   from a suggestive descriptor name alone
+- stream evidence from [streams.md](streams.md): a wallet currency that is not
+  the card country's legal tender, a frozen-rate stream beside live-rate
+  groups on the same rungs and days, one attempt per card with no retry after
+  decline, burst concentration, a whole country off-menu, a retail constant
+  with no state variation
 
 Declare portfolio-specific thresholds for a materially different rate,
 distribution, or descriptor share in the run methodology before assigning
@@ -39,7 +44,7 @@ country-slice coverage = cluster attempts in country /
                          all attempts in the same descriptor and country
 ```
 
-An exact **100% single-BIN-country cluster** is a standout characteristic.
+An exact **100% single-BIN-country cluster** is a standout characteristic in the canonical original-currency run. In the BIN-country base-currency sensitivity, BIN country constructs the target currency and is therefore not independent evidence; report 100% concentration descriptively but do not use it to raise the FX risk tier.
 Country-slice coverage explains how large that concentration is inside the
 descriptor-country population, but it has no fixed threshold and contributes
 no independent risk points. Values such as 20% or 33.8% are descriptive, not
@@ -52,7 +57,7 @@ Assign exactly one tier to every identified currency-amount pair:
 
 | Tier | Use when |
 |---|---|
-| High | An exact 100% single-country standout has at least one independent corroborating risk characteristic, or several independently strong non-country characteristics converge |
+| High | In the canonical run, an exact 100% single-country standout has at least one independent corroborating risk characteristic, or several independently strong non-country characteristics converge; FX concentration cannot raise tier |
 | Medium | At least two independent characteristics materially differ from the same-descriptor baseline, but High is not justified |
 | Low | The structural cluster gate is met, but observed corroborating evidence is limited or not material |
 

package/skills/payment/tld-detection/references/fx-conversion.md

@@ -0,0 +1,229 @@
+# BIN-country base-currency FX sensitivity
+
+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.
+
+## Separation contract
+
+- 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:
+
+```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:
+
+```text
+(target BIN-origin currency, rounded base_amount)
+```
+
+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 consolidated per-cluster table in [report-template.md](report-template.md).
+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

package/skills/payment/tld-detection/references/report-template.md

@@ -18,30 +18,31 @@ writing, grep banned strings in [terminology.md](terminology.md).
 English Markdown headings on the left; Chinese HTML / `.zh.md` on the right.
 
 ```markdown
-# Potential TLD currency-amount pairs — <window>
-# 潜在 TLD 币种金额对 — <window>
+# Potential transaction laundering (TLD) currency-amount pairs — <window>
+# 潜在交易清洗（TLD）币种金额对 — <window>
 
 ## TLD Risk Assessment                  # TLD 风险评估
 [Separate methodology link]             # [独立方法文档链接]
+## Upstream Streams                     # 上游流
 ## High-Risk Clusters                   # 高风险 Cluster
 ## TLD Risk Exposure                    # TLD 风险敞口
 ### By risk tier and descriptor          # 按风险等级及 Descriptor
 ### Overall exposure                     # 整体风险敞口
 ## All Identified Currency-Amount Pairs # 全部识别出的币种金额对
 ### Currency-Amount Pair C1             # 币种金额对 C1
-#### Definition                         # 定义
-#### Characteristics                    # 特征
+#### Cluster Profile and Comparison     # Cluster 概况与对比
 ## Verdict                              # 结论
 ```
 
 The separate methodology document uses this structure:
 
 ```markdown
-# TLD currency-amount-pair detection methodology — <scope/window>
-# TLD 币种金额对识别方法 — <范围/时段>
+# Transaction laundering (TLD) currency-amount-pair detection methodology — <scope/window>
+# 交易清洗（TLD）币种金额对识别方法 — <范围/时段>
 
 ## Universe and cleaning                # 分析总体与清洗
 ## Descriptor partition logic           # Descriptor 分区逻辑
+## Stream inference logic               # 上游流推断逻辑
 ## Currency-amount-pair logic           # 币种金额对逻辑
 ## Baseline and audit details           # 基线与审计明细
 ```
@@ -88,6 +89,21 @@ descriptor-local high-count rule, baseline definitions, below-threshold
 families, risk-tier rules, all run-specific materiality thresholds, and files
 used. No skill name in the HTML footer; filenames only.
 
+### Upstream streams / 上游流
+
+One table, one row per stream from `detect_streams.py`, per descriptor:
+stream label (wallet currency, menu scheme, live or frozen; retail constant;
+off-menu), attempts, share of descriptor, top countries, approval rate,
+suspected-fraud share, repeat-card share, retry after decline, top-three-hour
+share, address-verification presence. Under the table, at most three
+sentences: how many upstreams the descriptor carries, which stream each
+cluster below belongs to, and which streams (frozen, off-menu, retail) are
+evidence in their own right. A frozen-rate stream is described as generated
+traffic with the drift comparison against live groups on the same rungs and
+days; it is not called laundering, fraud or a bot. Methodology holds the
+parameters, rates cache, per-country wallet coverage and drift, and the
+alternatives rejected.
+
 ### High-risk clusters / 高风险 Cluster
 
 Include High-risk clusters only. For each, show descriptor, representative
@@ -107,30 +123,42 @@ or “supported TLD” impact figure.
 
 ### Currency-amount-pair analysis / 全部识别出的币种金额对
 
-One subsection per identified currency-amount pair. Definition contains only
-Descriptor, seed, representative anchors, and cluster attempts. Express
-anchors as `USD 11.7 → USD 23.39* → USD 46.78`. Follow that with an anchor
-table whose columns are anchor, attempts, authorization success rate, and
-suspected fraud as share of attempts. Always compute both rates for every
-theoretical level from that level's exact member attempts, including levels
-with fewer than the contrast min-n (default 30). Do not write `n/a` on this
-table because the rung is small. For a level containing multiple nearby exact
-values, display its highest-count amount with `*`; the table totals attempts
-and rates across that level and explains `*`.
-
-Show the risk tier and concise basis immediately below the cluster heading.
-Characteristics contain Descriptor, descriptor total attempts, cluster
-attempts, cluster share of descriptor, and MCC. Then compare Cluster with the
-baseline formed by removing that cluster from the same descriptor. The
-comparison contains authorization success rate, suspected fraud as a share of
-attempts, Top 3 issuing banks, and Top 3 BIN countries.
+One subsection per identified currency-amount pair. Show the risk tier and
+concise basis immediately below the cluster heading, then use one consolidated
+profile/comparison table. Do not emit separate Definition, Characteristics,
+Specification, and Metrics tables because they repeat descriptor, attempts,
+and cluster context.
+
+The consolidated table has columns `Section`, `Item`, `Cluster / value`, and
+`Same-descriptor baseline`. It contains each fact exactly once:
+
+| Section | Items |
+|---|---|
+| Definition | Descriptor, seed, representative anchors |
+| Population | Descriptor attempts, cluster attempts, cluster share of descriptor |
+| Specification | MCC |
+| Metrics | Authorization success rate, suspected fraud as share of attempts, Top 3 issuing banks, Top 3 BIN countries |
+
+Use `—` in the baseline column for definition/specification values that have no
+comparison. The baseline population is the same descriptor after removing the
+cluster's exact keys. Express anchors as `USD 11.7 → USD 23.39* → USD 46.78`.
+
+Follow the consolidated table with one anchor table whose columns are anchor,
+attempts, authorization success rate, and suspected fraud as share of attempts.
+Always compute both rates for every theoretical level from that level's exact
+member attempts, including levels with fewer than the contrast min-n (default
+30). Do not write `n/a` on this table because the rung is small. For a level
+containing multiple nearby exact values, display its highest-count amount with
+`*`; the table totals attempts and rates across that level and explains `*`.
 
 For every Top 3 cluster BIN country, add a table with country, cluster attempts,
 share of cluster, total attempts in the same descriptor-country slice, and
-cluster coverage of that slice. Mark exact 100% single-country composition as a
-standout. Treat `Mixed` as neutral. Do not assign a threshold or risk points to
-country-slice coverage, and do not promote any composition below 100% merely
-because it is high.
+cluster coverage of that slice. In canonical original-currency results only,
+mark exact 100% single-country composition as a standout. Treat `Mixed` as
+neutral. Do not assign a threshold or risk points to country-slice coverage,
+and do not promote any composition below 100% merely because it is high. In FX
+results, caption even 100% concentration as descriptive because BIN country
+constructs target currency; it cannot raise the FX tier.
 
 Follow the tables with transaction-date and transaction-time charts comparing
 the cluster with the same-descriptor baseline. These are characteristics, not
@@ -140,6 +168,14 @@ When clustering finds no qualifying family, omit currency-amount-pair subsection
 publish the ranking and below-threshold candidates in the methodology
 document, show zero identified-cluster exposure, and still write Verdict.
 
+For an FX sensitivity, keep the same consolidated layout, label anchors as
+base-currency anchors, and link separate `<scope>_bin_base_currency_clusters*`
+and methodology files. Define `|P_FX|` as the exact-date-converted attempts in
+the current frozen canonical descriptor partition. Use only `P_FX` for FX
+high-count/rung-pool thresholds and the same-descriptor baseline; keep excluded
+rows only in exclusion coverage and reconciliation to canonical `U`. State both
+converted-universe and all-authorization exposure denominators.
+
 ### Verdict / 结论
 
 [decision.md](decision.md). **≤3 sentences** for the whole book, then an

package/skills/payment/tld-detection/references/streams.md

@@ -0,0 +1,90 @@
+# Stream inference
+
+Run after cleaning and before clustering. A descriptor is a billing name, not a
+merchant: one descriptor can carry several upstreams. Exact-amount ladders miss
+most of them, because a cashier that converts a wallet-currency preset to the
+processing currency at a live rate turns one €10 preset into a dozen exact
+amounts across days. Stream inference works in the wallet currency instead.
+
+## Script
+
+```bash
+python3 {baseDir}/scripts/detect_streams.py cleaned-authorizations.csv \
+  --rates rates_cache.json --fetch-rates 2026-07-01 2026-08-31 \
+  --amount-column amount --currency-column currency --date-column timestamp \
+  --descriptor-column descriptor --bin-country-column bin_country \
+  --response-column response --approval-values A001 --suspected-fraud-values D102 \
+  --account-column account --card-type-column card_type --avs-column avs --auth-column auth \
+  --output streams.json --markdown streams.md
+```
+
+`--rates` is a daily cache `{base, rates:{YYYY-MM-DD:{CCY:rate}}}` quoted as
+units per one base unit; `--fetch-rates` fills it from Frankfurter v1 once.
+Prior-day carry (default 7 days) covers weekends; carried days are counted in
+the output. Pegged currencies (SAR, AED, QAR, KWD, BHD, OMR, HKD) are built in.
+This cache is for discovery; the audit FX path in
+[fx-conversion.md](fx-conversion.md) keeps its own contract.
+
+## What it does, per descriptor and BIN-country group (default ≥80 attempts)
+
+1. Retail list, strong test: one constant `k` in 1.00 to 1.15 under which at
+   least 30% of amounts are retail-shaped (`x.99`, `x.95`, `x.98`, `x.00`) with
+   at least 8 distinct base prices, against a control that jitters amounts by
+   0.4 to 2%. Rows on the list become a `retail x<k>` stream.
+2. Wallet inference: for each candidate currency (legal tender of the card
+   country, EUR, USD, GBP, CHF), convert amounts at the day's rate and find
+   peaks within 1.2%; coverage is the share of rows on the top ten peaks, the
+   control re-measures jittered rows against the same centres, and day drift is
+   how much the daily median of each peak moves. Prefer the currency whose
+   peaks land on a known menu, then the lowest drift, then legal tender, EUR,
+   USD. A wallet is accepted at 45% coverage, or at 15% coverage when the peaks
+   sit on a menu (a minority stream inside a mixed group).
+3. Menu scheme: peaks are matched (1.5% tolerance) against the 10-scheme
+   (10, 20, 25, 30, 40, 50, 100 and multiples, with a scale of 1, 5, 10, 25,
+   100, 400 or 1000 for small-unit currencies) and the 12-scheme (12, 24, 36,
+   48, 72, 96, 108, 144, 192, 288, 384). When a scheme covers at least half of
+   the peak attempts, only the on-menu rows form the stream; off-menu peaks stay
+   in the residual for the next round.
+4. Rate consistency: for each rung with at least 3 rows on at least 4 days,
+   the stream is `frozen` when the processed amount is identical to the cent on
+   every day while the market moved at least 0.1%; otherwise `live`. Players on
+   a live cashier drift; a script that fetched one rate does not.
+5. Weak retail test on what remains (20% share, 5 distinct bases), then
+   `off-menu` for the residual.
+
+Up to three rounds per group. Every threshold is a CLI option and is echoed in
+the JSON under `parameters`.
+
+## Reading the output
+
+| Label | Meaning | Treat as |
+|---|---|---|
+| `EUR menu-10 live` | wallet presets converted live near the market rate | player deposits on a euro-priced cashier |
+| `AUD menu-10 live`, `CZK menu-10 live` | local-currency menus per market | the same cashier's local settings |
+| `EUR menu-12 frozen` | preset menu at one rate for days | generated traffic; contrast its behaviour |
+| `retail x1.06` | list prices times one constant, many distinct bases | a shop checkout; the constant is a fake tax line or a stale rate, not a fee to interpret |
+| `GBP menu-none live` | peaks without a known scheme | a menu not in the built-in schemes, or a mixture; inspect peaks |
+| `off-menu` | no peak structure | typed amounts or another upstream; a whole country off-menu is a finding |
+
+Behaviour per stream: attempts, cards, repeat-card share, retry within 30
+minutes after a decline, top-three-hour share (UTC), burst gap regularity,
+address verification present, 3-D Secure present, prepaid share, top-five BIN
+share, approval, suspected fraud. On the reference book, retry after decline
+separated players (31% casino, 45% shop) from a generated batch (0.4%) more
+sharply than approval rate did.
+
+## Rules
+
+- Infer the wallet before interpreting any constant. Two apparent fees on the
+  reference book (5.75% and 12.1%) were AUD and EUR conversions.
+- A shared numeric menu across several wallet currencies is a cashier
+  fingerprint; two menus in one descriptor are two cashiers.
+- A country whose cards are charged in a currency that is not its legal
+  tender (Saudi cards in euro, US cards in euro) is reported as such; the
+  wallet currency is inferred, never assumed from BIN country.
+- Streams feed step 2: run exact currency-amount-pair clustering inside a
+  stream and use the stream, not the whole descriptor, as the baseline
+  population when a descriptor carries several streams.
+- Do not call a frozen-rate stream laundering or fraud in the report; call it
+  generated traffic and show the drift comparison against live groups on the
+  same rungs and days.

package/skills/payment/tld-detection/references/terminology.md

@@ -4,13 +4,14 @@ Use these terms in TLD reports. Read before writing. After writing, run
 the proofread in `SKILL.md`.
 
 TLD in this skill is **transaction laundering**. Spell it out on first
-use. It is not a top-level domain.
+use as **transaction laundering (TLD)**. The English report title is the first
+use and must carry that expansion. It is not a top-level domain.
 
 ## Canonical glossary
 
 | English | Chinese | Do not write |
 |---|---|---|
-| TLD (transaction laundering) | 交易清洗 / TLD | 把 TLD 写成域名；洗钱结案 |
+| transaction laundering (TLD) | 交易清洗（TLD） | 把 TLD 写成域名；洗钱结案 |
 | potential TLD currency-amount pair | 潜在 TLD 币种金额对 | 已确认 TLD；TLD 商户 |
 | cluster (report section) | 币种金额对 | 客户簇；客群；分群结果 |
 | anchor detection | 锚点识别 | 客户聚类（对业务读者） |
@@ -31,13 +32,19 @@ use. It is not a top-level domain.
 | BIN country / issuer country | 发卡行国家 / BIN 国家 | 客户国家；收货国；发卡国 |
 | cluster composition by BIN country | BIN 国家占 Cluster | 客户国家占比 |
 | descriptor-country slice coverage | Cluster 占 Descriptor 对应 BIN 国家 | BIN 国家风险率；国家命中率 |
-| exact single-country standout | 100% 单一 BIN 国家 standout | 高国家占比；接近 100% |
+| canonical exact single-country standout | canonical 原币 100% 单一 BIN 国家 standout | 高国家占比；接近 100% |
 | BIN-country local hour | BIN 国家当地小时 | 客户所在地时间；统一美国东部时间 |
 | this analysis window | 当前分析时段内 | 本窗口 |
 | MCC vs descriptor | MCC 与 descriptor 合理性 | 纠正 MCC；改 MCC |
 | verdict | 结论 | 长文综述（作结论部分时） |
 | High / Medium / Low risk | 高风险 / 中风险 / 低风险 | Supported；Weak；Ladder only；已确认 TLD |
 | risk exposure | 风险敞口 | 已确认 TLD 影响；定罪金额 |
+| stream | 上游流 | 客群；渠道 |
+| wallet currency (inferred) | 钱包币种（推断） | 发卡国货币（作为钱包币种时） |
+| preset menu | 预设金额菜单 | 阶梯（指菜单时）；手续费 |
+| frozen-rate stream | 固定汇率流 | 机器人；已确认套现 |
+| retail constant | 标价常数 | 税率；手续费率 |
+| generated traffic | 生成流量 | 欺诈交易（作为结论时） |
 
 Keep proper nouns: Visa, MasterCard, BIN, IIN, MCC, MID, Worldpay,
 Pazien, Order ID, descriptor. Tables may show response codes; prose uses
@@ -45,9 +52,10 @@ Pazien, Order ID, descriptor. Tables may show response codes; prose uses
 
 ## Axis and UI
 
-- Amount axes name the **original** currency of that cluster
-  (`授权尝试金额 USD`, `授权尝试金额 EUR`). Do not mix currencies on one
-  axis.
+- Canonical amount axes use and name the cluster's **original transaction
+  currency** (`授权尝试金额 USD`, `授权尝试金额 EUR`). FX amount axes use and
+  name the **target BIN-origin legal-tender currency**. Never mix currencies on
+  one axis in either view.
 - Date charts use each series' share of attempts by UTC transaction date.
 - Time charts use each BIN country's local hour, falling back to UTC when no
   timezone is configured. Normalize Cluster and Baseline independently.
@@ -59,7 +67,7 @@ Chinese: `走廊`, `杠杆`, `转化率`, `赋能`, `抓手`, `闭环`, `打法`
 `本窗口`, `已确认 TLD`, `已确认交易清洗`, `洗钱`, `发卡国`, `客群运营`,
 `客户簇`, `金额币种对`
 
-English: `confirmed laundering`, `confirmed TLD`, `money laundering`,
+English: `deposit fee` or `surcharge` for a converted preset, `bot` as a finding, `confirmed laundering`, `confirmed TLD`, `money laundering`,
 `SAR`, `file a SAR`, `top-level domain`, `customer country`,
 `conversion rate` (when meaning auth rate), `corridor`, `price band`
 (as the cluster name)

package/skills/payment/tld-detection/references/workflow.md

@@ -71,7 +71,7 @@ is frozen.
 
 ## Order that must not move
 
-Clean → descriptor partition → currency-amount pairs → same-descriptor baseline → decide → report.
+Clean → descriptor partition → stream inference (wallet currency, menu, frozen, retail) → currency-amount pairs inside streams → same-stream baseline (same-descriptor when one stream) → decide → report.
 
 Comparison features must not create a cluster that amount detection did not
 find. Decision does not add evidence; it only writes the ≤3-sentence