@1aboveio/skills 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,189 @@
+# Risk decision
+
+After currency-amount-pair detection and same-descriptor baseline comparison,
+assign investigation-priority risk tiers. This is prioritization, not a finding
+that transaction laundering occurred.
+
+## Eligibility versus risk
+
+The cluster gate (at least three theoretical levels, fixed 2x adjacency, at
+least 100 exact-member attempts) determines which currency-amount pairs enter
+the result. Passing that gate does not by itself determine High, Medium, or Low
+risk.
+
+Risk uses independent post-membership evidence:
+
+- structural strength beyond the minimum, such as a fourth or later level
+- cluster share of its descriptor
+- authorization-success and suspected-fraud differences versus the same-
+  descriptor baseline
+- issuing-bank differences versus that baseline
+- 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
+- payment-pattern evidence from [streams.md](streams.md), treated as separate
+  observations with known coverage and inference limits: unexpected inferred
+  pricing currency, tested source-to-top-up rate stability, low repeat-card or
+  decline-retry activity, and concentrated dates/hours. Do not count a business
+  hypothesis itself or correlated measurements as independent corroboration.
+
+Declare portfolio-specific thresholds for a materially different rate,
+distribution, or descriptor share in the run methodology before assigning
+risk. Do not invent universal cutoffs after seeing the results.
+
+## BIN-country evidence
+
+BIN country is post-membership evidence, not a partition, membership key, or
+veto. Pattern inference can use country to propose pricing currencies but
+cannot filter canonical members. Measure any canonical single-country
+concentration on the complete descriptor/currency/amount membership, never
+on a country-selected pattern slice as independent risk evidence. `Mixed` is neutral and must never reduce a risk tier by itself.
+
+For every Top 3 cluster BIN country, report both conditional views:
+
+```text
+cluster composition = cluster attempts in country / all cluster attempts
+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 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
+self-interpreting risk signals. Any value below 100% is not promoted merely
+because it is numerically high.
+
+## Risk tiers
+
+Assign exactly one tier to every identified currency-amount pair:
+
+| Tier | Use when |
+|---|---|
+| 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 |
+
+Do not use a generic 0–100 score unless the business has approved and calibrated
+its weights and cutoffs. Missing fields reduce confidence and must be disclosed;
+they are not evidence that risk is Low.
+
+Sort report results `High → Medium → Low`. Within a tier, sort by the number and
+magnitude of independently supported characteristics, then by exact-member
+attempts. Preserve stable cluster IDs when sorting an existing result.
+
+## Reader-facing conclusion
+
+Write for a payment-risk operator, not the detector's implementer. The reader
+must understand who to review first, why, what remains unknown, and what to
+check next without opening the methodology or decoding cluster IDs.
+
+Begin each main report with one short decision summary, followed by Main
+findings and Next checks. Do not repeat a closing Verdict. Keep exhaustive
+cluster profiles and exposure tables in linked evidence. Use the same
+evidence-first approach in the final chat handoff.
+
+The summary is at most three short sentences, each with one main point.
+Prioritize evidence, not descriptor volume alone; if no defensible priority
+exists, say so instead of forcing a target. Pattern labels are hypotheses:
+
+1. Name the first investigation target and the relevant time window; state
+   the highest detected-cluster tier when one exists. Use the exact descriptor
+   to locate the activity, not as proof of a verified merchant identity.
+2. Give the strongest observed reason in plain language, using only one or
+   two essential figures. Explain why that observation warrants review.
+3. State what the data cannot establish, including that investigation priority
+   is not confirmation of transaction laundering.
+
+The three-sentence limit applies to the summary, not the entire report.
+For a Chinese summary, keep each sentence within 80 characters and use at
+most two numerical facts across the whole summary, excluding its date window
+and identifiers. Move amounts, percentages,
+source/target currencies, thresholds, and technical labels to the explanation
+unless essential to the immediate business takeaway. Do not join many clauses
+with semicolons to squeeze a data inventory into it. Keep full anchor lists,
+cluster IDs, and by-tier exposure in supporting tables.
+
+Preserve the supplied fact scope: bind every figure to its stated descriptor,
+period, numerator, denominator, and metric. If any is missing, mark it unknown;
+do not resolve ambiguity by borrowing a nearby period or population. Never
+translate an authorization decline as a chargeback (`拒付`). Small samples
+limit generalization; their observed rates still describe those samples and
+must not be dismissed as meaningless. `Other pattern` can mean insufficient
+evidence: do not assert that a menu or e-commerce test failed, or that fields
+are missing, unless the run actually records that reason.
+
+### Supporting explanation
+
+Use Main findings and Next checks for the supporting explanation. Within each
+finding, present observed evidence first, then the supported pattern hypothesis
+and uncertainty, then its relationship to formal amount clusters. Only give
+intersection counts supported by saved row-level reconciliation. A preset menu
+can contain non-doubling prices; the three-level, fixed-2x, 100-attempt gate
+belongs to formal clusters, not to every top-up hypothesis.
+
+Use short subsections or bullets as needed:
+
+- **Who and why:** pair each prioritized descriptor's concrete observation
+  with its business meaning and an unresolved question. Different amount or
+  card-country patterns can justify checking whether several businesses share
+  a billing name; they do not prove that they do.
+- **What detection found:** report qualifying clusters and exact-member exposure
+  by tier with explicit denominators, or zero qualifying clusters and zero
+  identified-cluster exposure. Explain the tested pattern in ordinary words:
+  repeated amounts with a fixed doubling relationship and sufficient attempts.
+  Explain stream observations separately; the exact-amount test is not the
+  whole analysis.
+- **What to check next:** name specific observed orders or activity to reconcile
+  with products, websites, actual sellers, or fulfillment records. These are
+  bounded evidence-gathering suggestions, not findings or enforcement commands.
+  Do not claim those records were inspected when they were not.
+
+Use only evidence already established in the report. If evidence cannot support
+prioritizing a target or naming a useful follow-up, say so rather than inventing
+one. Do not recommend filing a SAR, terminating a merchant, or correcting an MCC.
+
+### No qualifying cluster and period focus
+
+No qualifying cluster means the tested pattern did not meet this run's gates,
+not that the merchant is safe or all suspicious activity was excluded. State
+this plainly, especially below 100 attempts. Keep descriptor-level investigation
+leads separate from formal cluster tiers and cluster exposure; do not assign
+a High/Medium/Low cluster tier to an unqualified lead. Missing fields and small
+samples constrain interpretation; they are not evidence of Low risk.
+Do not reclassify e-commerce or other-pattern rows as top-ups merely by obtaining
+their charge currency. Direct versus FX-converted is a subtype distinction only
+after a supported preset-menu hypothesis exists for those rows.
+
+For a month or active-merchant focus, lead with activity observed in that window.
+Separate historical findings, historical members' current-period slices, and
+independent current-period detection. No observed activity in the supplied files
+does not prove a business stopped operating. Never carry historical tier or
+exposure into the current period without current-period evidence. Keep canonical
+and FX findings separate.
+
+### Chinese readability
+
+Introduce a descriptor as `账单名称`, retaining its exact value. Explain BIN
+country as where the card was issued, not customer location. Explain suspected-
+fraud rates as the share of authorization attempts declined with a suspected-
+fraud response, not confirmed fraud. Define the baseline as the relevant remaining
+attempts using the same-descriptor scope. A pattern-only comparison must be
+labeled separately and cannot replace the canonical cluster baseline.
+
+Do not use `敞口`, `精确成员`, `canonical`, `FXC*`, `menu-12 frozen`, or
+`standout` as a substitute for explaining the conclusion. Keep technical labels
+in supporting tables and methods. Explain the relevance of selected statistics;
+keep hypotheses as questions, not facts.
+
+Use the approved payment-pattern names from [terminology.md](terminology.md).
+Direct/FX-converted top-up and e-commerce names remain hypotheses, not verified
+business facts. Explain inferred top-up versus actual charge currencies; fixed
+amounts are supplementary, not a separate business class.
+
+Read back the conclusion without its tables. If who to review, why, and what
+is unknown are still unclear, rewrite during `editorial-review`, before `polish-cn`.
+Polishing cannot repair missing analytical explanation.
+
+First use of TLD is “transaction laundering (TLD)”. Proofread with
+[terminology.md](terminology.md).

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

@@ -0,0 +1,232 @@
+# 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 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