@1aboveio/skills 1.0.10 → 1.0.12

package/skills/risk-compliance/portfolio-payment-analysis/scripts/render.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""Render a reviewed report model to portable HTML and Markdown, without dependencies.
+
+Usage: python3 render.py --model presentation.json --output REPORT_DIRECTORY
+The model owns narrative; editing it and rerendering keeps both formats in sync.
+"""
+import argparse
+import html
+import json
+from pathlib import Path
+from comparison_charts import chart as comparison_chart, CSS as COMPARISON_CSS, JS as COMPARISON_JS
+
+CSS = """
+:root{--ink:#142c36;--muted:#536770;--paper:#f4f6f4;--line:#d8e2df;--accent:#087b71;--amber:#9c5215}
+*{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;background:var(--paper);color:var(--ink);font:16px/1.7 -apple-system,BlinkMacSystemFont,'Segoe UI','PingFang SC','Microsoft YaHei',sans-serif}a{color:var(--accent);text-underline-offset:4px}a:focus-visible,input:focus-visible,button:focus-visible,summary:focus-visible{outline:3px solid #c16613;outline-offset:4px}.mast{background:#142c36;color:#fff;padding:42px max(24px,calc((100vw - 1180px)/2)) 36px}.eyebrow{font-size:12px;letter-spacing:.16em;text-transform:uppercase;color:#9bdbcf}.mast h1{font-size:clamp(28px,4vw,44px);letter-spacing:-.035em;line-height:1.25;margin:14px 0}.mast p{color:#d1e0e0;max-width:850px}.periods{display:flex;flex-wrap:wrap;gap:8px 24px;font-size:13px}.toolbar{position:sticky;top:0;z-index:2;background:#fffef9;border-bottom:1px solid var(--line);padding:12px max(24px,calc((100vw - 1180px)/2));display:flex;gap:20px;align-items:center;flex-wrap:wrap}.toolbar a{font-size:14px;text-decoration:none;min-height:30px;display:inline-flex;align-items:center}.toolbar button{margin-left:auto;background:none;border:1px solid var(--line);padding:8px 14px;border-radius:4px;color:var(--ink);cursor:pointer}main{max-width:1228px;padding:28px 24px 64px;margin:auto}.kpis{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:1px;background:var(--line);border:1px solid var(--line);margin-bottom:28px}.kpi{background:#fff;padding:22px}.kpi-label{font-size:14px;color:var(--muted)}.kpi-value{font-variant-numeric:tabular-nums;font-size:clamp(25px,3vw,36px);font-weight:650;letter-spacing:-.04em;line-height:1.6}.kpi small{font-size:12px;color:var(--muted)}.summary{background:#e9f2ed;border-left:4px solid var(--accent);padding:24px 28px;margin-bottom:32px}.summary h2{margin:0 0 12px;font-size:21px}.summary ol{padding-left:22px;margin:0}.summary li+li{margin-top:10px}.section{scroll-margin-top:100px;background:white;border:1px solid var(--line);margin:24px 0;padding:28px 32px}.section h2{font-size:25px;letter-spacing:-.025em;margin:0 0 16px}.section h3{font-size:19px;margin:28px 0 12px}p{margin:10px 0 18px}.note{font-size:13px;color:var(--muted)}.callout{border-left:3px solid #b97028;background:#fff8ec;padding:14px 18px;font-size:14px}.table-wrap{overflow-x:auto;border:1px solid var(--line);margin:16px 0}table{width:100%;border-collapse:collapse;font-size:14px;font-variant-numeric:tabular-nums}th{background:#eff4f2;text-align:left;color:#35545d;font-weight:600;white-space:nowrap}th,td{padding:12px 14px;border-bottom:1px solid #e8eeeb;vertical-align:top}tbody tr:last-child td{border-bottom:0}tbody tr:hover{background:#f4f8f6}td:not(:first-child){white-space:nowrap}.filter{display:flex;align-items:center;gap:12px;margin:16px 0;font-size:14px}.filter input{width:min(320px,100%);padding:10px 12px;border:1px solid #9eb5af;border-radius:4px;font:inherit}.bars{margin:24px 0}.bar-row{display:grid;grid-template-columns:minmax(100px,180px) 1fr 100px;gap:14px;align-items:center;margin:12px 0;font-size:13px}.bar-label{overflow-wrap:anywhere}.track{background:#eff4f2;height:24px}.fill{background:var(--accent);height:100%;min-width:1px}.bar-value{text-align:right;font-variant-numeric:tabular-nums}.chart{width:100%;height:auto;display:block}.chart text{font-family:inherit;fill:#536770;font-size:12px}.chart text.title{font-size:14px}.chart line.grid{stroke:#e2eae6}.chart path.series{stroke:#087b71;stroke-width:3;fill:none}.chart circle{fill:#087b71;stroke:white;stroke-width:2}.footer{font-size:12px;color:var(--muted);padding-top:18px;border-top:1px solid var(--line)}details{margin:16px 0}summary{cursor:pointer;font-weight:600;padding:10px 0}.empty{color:var(--muted);padding:18px;background:#f4f6f4}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}
+table.wrap-headers{table-layout:fixed;min-width:900px}table.wrap-headers th,table.wrap-headers td{white-space:normal;overflow-wrap:anywhere}table.wrap-headers th:first-child{width:17%}
+@media(max-width:700px){main{padding:18px 12px 36px}.mast{padding:28px 20px}.kpis{grid-template-columns:repeat(2,minmax(0,1fr))}.kpi{padding:16px}.section{padding:22px 16px}.section h2{font-size:22px}.toolbar{position:static;padding:10px 16px;gap:10px 16px}.toolbar button{margin-left:0}.summary{padding:20px}.bar-row{grid-template-columns:110px 1fr 66px;gap:8px;font-size:12px}.periods{display:block}.periods span{display:block}}
+@media print{body{background:white;font-size:11px}.mast{background:white;color:#142c36;padding:0}.mast p,.eyebrow{color:#536770}.toolbar,.filter{display:none}main{padding:10px 0;max-width:none}.section{break-inside:avoid;padding:16px}.kpis{grid-template-columns:repeat(4,1fr)}.kpi-value{font-size:23px}a{color:inherit}details>*{display:block!important}.table-wrap{overflow:visible}th,td{padding:7px}.summary{background:#f2f5f2}}
+@media(prefers-reduced-motion:reduce){html{scroll-behavior:auto}}
+"""
+JS = """
+document.querySelectorAll('input[data-table]').forEach(input=>input.addEventListener('input',()=>{
+ const table=document.getElementById(input.dataset.table), query=input.value.toLowerCase();
+ let visible=0;
+ table.querySelectorAll('tbody tr').forEach(row=>{row.hidden=!row.textContent.toLowerCase().includes(query);if(!row.hidden)visible++});
+ document.getElementById(input.dataset.table+'-status').textContent='显示 '+visible+' 行';
+}));
+document.getElementById('print-report').addEventListener('click',()=>window.print());
+"""
+
+def esc(value):
+    return html.escape(str(value), quote=True)
+
+
+def mdtext(value):
+    text=html.escape(str(value),quote=False).replace('\n',' ')
+    for char in ('\\','*','_','[',']','`','#','|'):
+        text=text.replace(char,'\\'+char)
+    return text
+
+
+def mdcell(value):
+    return mdtext(value)
+
+
+def table(block, identifier):
+    headers, rows = block['headers'], block['rows']
+    body = '<div class="table-wrap"><table id="'+identifier+'"'+(' class="wrap-headers"' if block.get('wrap_headers') else '')+'><thead><tr>'
+    body += ''.join('<th scope="col">'+esc(v)+'</th>' for v in headers)+'</tr></thead><tbody>'
+    body += ''.join('<tr>'+''.join('<td>'+esc(v)+'</td>' for v in row)+'</tr>' for row in rows)
+    body += '</tbody></table></div>'
+    if block.get('filter'):
+        body = f'<label class="filter">筛选商户<input data-table="{identifier}" type="search" placeholder="商户名称或 ID" aria-controls="{identifier}"></label><span class="sr-only" id="{identifier}-status" aria-live="polite"></span>'+body
+    md = '| '+' | '.join(map(mdcell, headers))+' |\n| '+' | '.join(['---']*len(headers))+' |\n'
+    md += '\n'.join('| '+' | '.join(map(mdcell, row))+' |' for row in rows)
+    return body, md
+
+
+def bars(block):
+    rows = block['rows']
+    maximum = max((r['value'] for r in rows), default=0) or 1
+    out = '<div class="bars" role="img" aria-label="'+esc(block.get('title','数量分布'))+'">'
+    for r in rows:
+        out += '<div class="bar-row"><span class="bar-label">'+esc(r['label'])+'</span><div class="track"><div class="fill" style="width:'+str(max(0,r['value']/maximum*100))+'%"></div></div><span class="bar-value">'+esc(r.get('display',r['value']))+'</span></div>'
+    return out+'</div>', '\n'.join('- '+mdtext(r['label'])+'：'+mdtext(r.get('display',r['value'])) for r in rows)
+
+
+def line_chart(block):
+    rows=block['rows']; w=1000; h=250; left=52; right=30; top=32; bottom=45
+    maximum=block.get('max',100)
+    plotw=w-left-right; ploth=h-top-bottom
+    out=f'<svg class="chart" viewBox="0 0 {w} {h}" role="img" aria-label="{esc(block.get("title","趋势"))}"><title>{esc(block.get("title","趋势"))}</title>'
+    for n in range(5):
+        value=maximum*n/4; y=top+ploth*(1-n/4)
+        out+=f'<line class="grid" x1="{left}" y1="{y}" x2="{w-right}" y2="{y}"/><text x="{left-8}" y="{y+4}" text-anchor="end">{value:g}</text>'
+    points=[]
+    for i,r in enumerate(rows):
+        x=left+plotw*i/max(1,len(rows)-1)
+        if r['value'] is None:
+            if points: out+='<path class="series" d="'+' '.join(points)+'"/>';points=[]
+        else:
+            y=top+ploth*(1-r['value']/maximum)
+            points.append(('M' if not points else 'L')+f'{x},{y}')
+            out+=f'<circle cx="{x}" cy="{y}" r="4"><title>{esc(r["label"])}: {r["value"]:.2f}</title></circle>'
+        if len(rows)<=8 or i%max(1,len(rows)//8)==0 or i==len(rows)-1:
+            out+=f'<text x="{x}" y="{h-15}" text-anchor="middle">{esc(r["label"])}</text>'
+    if points: out+='<path class="series" d="'+' '.join(points)+'"/>'
+    out+='</svg>'
+    return out, '\n'.join('- '+mdtext(r['label'])+'：'+('N/A' if r['value'] is None else f'{r["value"]:.2f}') for r in rows)
+
+
+def block_output(block, identifier, level=3):
+    kind=block['type'];text=block.get('text','')
+    if kind=='paragraph': hp='<p>'+esc(text)+'</p>';mp=mdtext(text)
+    elif kind=='note': hp='<p class="note">'+esc(text)+'</p>';mp=mdtext(text)
+    elif kind=='callout': hp='<p class="callout">'+esc(text)+'</p>';mp='> '+mdtext(text)
+    elif kind=='heading': hp=f'<h{level}>'+esc(text)+f'</h{level}>';mp='#'*level+' '+mdtext(text)
+    elif kind=='table': hp,mp=table(block,identifier)
+    elif kind=='bars': hp,mp=bars(block)
+    elif kind=='line': hp,mp=line_chart(block)
+    elif kind=='list':
+        hp='<ol>'+''.join('<li>'+esc(x)+'</li>' for x in block['items'])+'</ol>'
+        mp='\n'.join(f'{n+1}. {mdtext(x)}' for n,x in enumerate(block['items']))
+    elif kind in ('comparison_chart','time_series_chart'): hp,mp=comparison_chart(block,identifier)
+    elif kind=='group':
+        children=[block_output(child,identifier+'-'+str(i),min(level+1,6)) for i,child in enumerate(block['blocks'])]
+        hp=''.join(pair[0] for pair in children);mp='\n\n'.join(pair[1] for pair in children)
+        if not block.get('collapsed'):
+            hp=f'<h{level}>'+esc(block['caption'])+f'</h{level}>'+hp
+            mp='#'*level+' '+mdtext(block['caption'])+'\n\n'+mp
+    else: raise ValueError('Unknown block type: '+kind)
+    if block.get('collapsed'):
+        hp='<details><summary>'+esc(block.get('caption','查看明细'))+'</summary>'+hp+'</details>'
+        mp='#'*level+' '+mdtext(block.get('caption','查看明细'))+'\n\n'+mp
+    return hp,mp
+
+
+def render(model, output):
+    output=Path(output);output.mkdir(parents=True,exist_ok=True)
+    parts=[]; md=['# '+mdtext(model['title']),mdtext(model.get('subtitle',''))]
+    periods=model.get('periods',[])
+    md.extend(map(mdtext,periods))
+    if model.get('summary'):
+        parts.append('<section class="summary"><h2>'+esc(model.get('summary_title','本期要点'))+'</h2><ol>'+''.join('<li>'+esc(x)+'</li>' for x in model['summary'])+'</ol></section>')
+        md+=['## '+mdtext(model.get('summary_title','本期要点'))]+[f'{i+1}. {mdtext(x)}' for i,x in enumerate(model['summary'])]
+    if model.get('kpis'):
+        parts.append('<div class="kpis">'+''.join('<div class="kpi"><div class="kpi-label">'+esc(k['label'])+'</div><div class="kpi-value">'+esc(k['value'])+'</div><small>'+esc(k.get('note',''))+'</small></div>' for k in model['kpis'])+'</div>')
+        md+=['## 核心指标',table({'headers':['指标','数值','说明'],'rows':[[k['label'],k['value'],k.get('note','')] for k in model['kpis']]},'kpis')[1]]
+    nav=[]
+    for i,section in enumerate(model['sections']):
+        sid='section-'+str(i+1)
+        nav.append(f'<a href="#{sid}">{esc(section.get("nav",section["title"]))}</a>')
+        parts.append(f'<section class="section" id="{sid}"><h2>{esc(section["title"])}</h2>')
+        md+=['## '+mdtext(section['title'])]
+        for j,b in enumerate(section['blocks']):
+            hp,mp=block_output(b,sid+'-table-'+str(j))
+            parts.append(hp);md.append(mp)
+        parts.append('</section>')
+    footer=model.get('footer','')
+    links=model.get('links',[])
+    # Links are local artifacts only; reject script URLs and escaping parent paths.
+    for link in links:
+        target=Path(link['file'])
+        if target.is_absolute() or len(target.parts)!=1 or ':' in link['file'] or target.name in {'.','..'}:
+            raise ValueError('Report links must name a sibling file')
+    footer_html=esc(footer)
+    if links:
+        footer_html+='<p>'+ ' · '.join('<a href="'+esc(l['file'])+'">'+esc(l['label'])+'</a>' for l in links)+'</p>'
+        md.append(' · '.join('['+l['label']+']('+l['file']+')' for l in links))
+    page='<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>'+esc(model['title'])+'</title><style>'+CSS+COMPARISON_CSS+'</style></head><body><header class="mast"><div class="eyebrow">Submerchant / Payment Review</div><h1>'+esc(model['title'])+'</h1><p>'+esc(model.get('subtitle',''))+'</p><div class="periods">'+''.join('<span>'+esc(x)+'</span>' for x in periods)+'</div></header><nav class="toolbar" aria-label="报告导航">'+''.join(nav)+'<button type="button" id="print-report">打印 / 保存 PDF</button></nav><main>'+''.join(parts)+'<footer class="footer">'+footer_html+'</footer></main><script>'+JS+COMPARISON_JS+'</script></body></html>'
+    (output/'overview.zh.html').write_text(page,encoding='utf-8')
+    (output/'overview.zh.md').write_text('\n\n'.join(md+[mdtext(footer)])+'\n',encoding='utf-8')
+
+
+if __name__=='__main__':
+    parser=argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--model',required=True,type=Path)
+    parser.add_argument('--output',required=True,type=Path)
+    args=parser.parse_args()
+    render(json.loads(args.model.read_text(encoding='utf-8')),args.output)

package/skills/risk-compliance/portfolio-payment-analysis/scripts/risk_history.py

@@ -0,0 +1,435 @@
+"""Observed merchant histories. Raw DART fields and join keys never leave this module."""
+import calendar
+import csv
+import hashlib
+import io
+import re
+from collections import Counter, defaultdict
+from datetime import date, datetime, timedelta
+from decimal import Decimal, InvalidOperation
+
+# SIX ISO 4217 list-one snapshot, 2026-09-17; membership, not historical validity.
+CURRENCIES = set('AED AFN ALL AMD AOA ARS AUD AWG AZN BAM BBD BDT BHD BIF BMD BND BOB BOV BRL BSD BTN BWP BYN BZD CAD CDF CHE CHF CHW CLF CLP CNY COP COU CRC CUP CVE CZK DJF DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP GEL GHS GIP GMD GNF GTQ GYD HKD HNL HTG HUF IDR ILS INR IQD IRR ISK JMD JOD JPY KES KGS KHR KMF KPW KRW KWD KYD KZT LAK LBP LKR LRD LSL LYD MAD MDL MGA MKD MMK MNT MOP MRU MUR MVR MWK MXN MXV MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SHP SLE SOS SRD SSP STN SVC SYP SZL THB TJS TMT TND TOP TRY TTD TWD TZS UAH UGX USD USN UYI UYU UYW UZS VED VES VND VUV WST XAD XAF XAG XAU XBA XBB XBC XBD XCD XCG XDR XOF XPD XPF XPT XSU XTS XUA XXX YER ZAR ZMW ZWG'.split())
+FILENAME = re.compile(r'WP_[A-Z0-9]+_340FRD_V03_([0-9]{8})_[0-9]{3}\.CSV')
+LENGTHS = (2, 8, 80, 15, 19, 8, 3, 23, 250, 255, 23, 15, 3, 30, 3, 3, 1)
+TYPES = set('900 901 902 903 904 905 906 907 908 909 90A 90B 955 956'.split())
+
+
+def dart_date(value):
+    if not re.fullmatch(r'\d{8}', value):
+        raise ValueError('date_format')
+    try:
+        return datetime.strptime(value, '%Y%m%d').date()
+    except ValueError:
+        raise ValueError('date_calendar') from None
+
+
+def parse_file(name, data):
+    match = FILENAME.fullmatch(name)
+    if not match:
+        raise ValueError('filename_format')
+    created = dart_date(match[1])
+    try:
+        text = data.decode('ascii')
+        if any(ord(c) < 32 and c not in '\r\n\t' or ord(c) == 127 for c in text):
+            raise ValueError('ascii_control_character')
+        records = list(csv.reader(io.StringIO(text, newline=''), strict=True))
+    except UnicodeDecodeError:
+        raise ValueError('ascii_encoding') from None
+    except csv.Error:
+        raise ValueError('csv_syntax') from None
+    if not records or any(not row for row in records):
+        raise ValueError('empty_file_or_record')
+    if records[0][0] != '00':
+        raise ValueError('missing_header')
+    if len(records[0]) != 17:
+        raise ValueError('header_field_count')
+    if dart_date(records[0][1]) != created:
+        raise ValueError('header_filename_date_mismatch')
+    if any(records[0][2:]):
+        raise ValueError('header_reserved_not_empty')
+    if len(records) < 2 or records[-1][0] != '99':
+        raise ValueError('missing_trailer')
+    trailer = records[-1]
+    if len(trailer) != 2 or not re.fullmatch(r'[0-9]{1,23}', trailer[1]) or int(trailer[1]) != len(records)-1:
+        raise ValueError('invalid_trailer')
+    rows = []
+    for row in records[1:-1]:
+        if row[0] != '01' or len(row) != 17:
+            raise ValueError('invalid_detail')
+        if any(len(v) > n for v, n in zip(row, LENGTHS)):
+            raise ValueError('field_max_length')
+        dart_date(row[5])
+        if row[6] not in CURRENCIES or (row[12] and row[12] not in CURRENCIES):
+            raise ValueError('iso4217_currency')
+        if not re.fullmatch(r'-?[0-9]+(?:\.[0-9]{1,6})?', row[7]):
+            raise ValueError('major_units_decimal_format')
+        if row[14] not in TYPES or row[15] not in {'SWP', 'PKE', 'NA'}:
+            raise ValueError('invalid_code')
+        rows.append(tuple(row))
+    return created, rows
+
+
+def brand_of(row):
+    return ' '.join((row.get('Payment method') or '').split()).casefold()
+
+
+def verified_provider(row):
+    return ' '.join((row.get('Provider') or '').split()).casefold() == 'worldpay - acquiring'
+
+
+def affected_series(brand):
+    return {'visa': ('visa_predispute', 'visa_dispute'),
+            'mastercard': ('mastercard_chargeback',)}.get(
+                brand, ('visa_predispute', 'visa_dispute', 'mastercard_chargeback'))
+
+
+def stage(row):
+    brand = brand_of(row)
+    pair = (row.get('Lifecycle state', ''), row.get('Original cycle', ''))
+    if brand == 'visa' and pair == ('Pre-dispute resolution', 'Rapid Dispute Resolution'):
+        return 'visa_predispute'
+    formal = {('1st chargeback', 'First CB Response'), ('1st chargeback', 'First CB Request'),
+              ('Initial dispute loss notice', 'First CB Dispute Loss'), ('Initial dispute reversal', 'First CB Response')}
+    if pair in formal:
+        return {'visa': 'visa_dispute', 'mastercard': 'mastercard_chargeback'}.get(brand)
+    return None
+
+
+def periods(cutoff):
+    months = []
+    for offset in range(-11, 1):
+        y, m = divmod(cutoff.year * 12 + cutoff.month - 1 + offset, 12)
+        first = date(y, m+1, 1)
+        last = min(date(y, m+1, calendar.monthrange(y, m+1)[1]), cutoff)
+        months.append((first.strftime('%Y-%m'), first, last, last.day != calendar.monthrange(y, m+1)[1]))
+    monday = cutoff - timedelta(days=cutoff.weekday())
+    weeks = []
+    for i in range(7, -1, -1):
+        first = monday - timedelta(weeks=i)
+        last = min(first + timedelta(days=6), cutoff)
+        weeks.append((first.isoformat(), first, last, (last-first).days != 6))
+    return months, weeks
+
+
+def build(root, cutoff, merchants, settlements, disputes):
+    months, weeks = periods(cutoff)
+    files, valid_dates, invalid_dates, first_seen = [], set(), set(), {}
+    physical = 0
+    folder = root / '340FRD'
+    if folder.is_dir():
+        for path in sorted(folder.iterdir()):
+            if not path.is_file() or '340FRD' not in path.name:
+                continue
+            data = path.read_bytes()
+            info = {'file': path.name, 'sha256': hashlib.sha256(data).hexdigest()}
+            match = FILENAME.fullmatch(path.name)
+            try:
+                if not match:
+                    raise ValueError('filename_format')
+                created = dart_date(match[1]); info['date'] = created.isoformat()
+                if created > cutoff:
+                    info['status'] = 'future_not_parsed'; files.append(info); continue
+                created, rows = parse_file(path.name, data)
+                info['status'] = 'valid'; valid_dates.add(created); physical += len(rows)
+                for row in rows:
+                    first_seen[row] = min(created, first_seen.get(row, created))
+            except ValueError as exc:
+                info.update(status='invalid', error=str(exc))
+                if 'date' in info:
+                    invalid_dates.add(date.fromisoformat(info['date']))
+            files.append(info)
+    sales = defaultdict(list)
+    audit = Counter()
+    for row in settlements:
+        if row.get('Settlement type') == 'Sale' and row.get('Settlement status') == 'Settled' and row.get('ARN') and row.get('MID'):
+            if date.fromisoformat(row['Settlement date'][:10]) <= cutoff:
+                if ' '.join((row.get('Provider') or '').split()).casefold() != 'worldpay - acquiring':
+                    audit['unverified_settlement_provider'] += 1
+                    continue
+                sales[row['ARN'], row['MID']].append(row)
+    fraud = []
+    unidentified_fraud = []
+    fraud_groups = defaultdict(list)
+    unmatched_amounts = defaultdict(Decimal)
+    observations = Counter(d.strftime('%Y-%m') for d in first_seen.values())
+    for row, observed in first_seen.items():
+        if dart_date(row[5]) > cutoff:
+            audit['transaction_after_cutoff'] += 1
+            continue
+        candidates = sales.get((row[10], row[1]), []) if row[10] and row[1] else []
+        if not candidates:
+            audit['unmatched'] += 1
+            unmatched_amounts[row[6]] += Decimal(row[7])
+            continue
+        if len(candidates) != 1:
+            audit['ambiguous'] += 1; continue
+        sale = candidates[0]
+        if not (sale.get('Transaction ID') or '').strip():
+            audit['missing_sale_identity'] += 1
+            unidentified_fraud.append((sale.get('_merchant') or sale.get('Sub merchant ID') or None, observed, 'visa_fraud', 'missing sale identity'))
+            continue
+        try:
+            agreement = (date.fromisoformat(sale['Timestamp'][:10]) == dart_date(row[5]) and
+                         sale.get('Transaction amount currency', '').upper() == row[6] and
+                         Decimal(sale.get('Transaction amount', '')) == Decimal(row[7]))
+        except (ValueError, InvalidOperation):
+            agreement = False
+        if not agreement:
+            audit['mismatch'] += 1; continue
+        merchant = sale.get('_merchant') or sale.get('Sub merchant ID')
+        if not merchant:
+            audit['missing_merchant'] += 1; continue
+        brand = {'visa': 'visa', 'mastercard': 'mastercard'}.get(brand_of(sale), 'other')
+        audit['attributed'] += 1
+        audit['attributed_' + brand] += 1
+        fraud.append((merchant, observed, brand))
+        fraud_groups[row[10], row[1]].append((merchant, observed, brand))
+    cases = defaultdict(list)
+    observed_dates = []
+    daudit = Counter()
+    for row in disputes:
+        d = date.fromisoformat(row['Chargeback date'][:10])
+        if d > cutoff:
+            continue
+        observed_dates.append(d)
+        provider = 'worldpay - acquiring' if verified_provider(row) else row.get('Provider')
+        key = (provider, row.get('MID'), row.get('Dispute ID'))
+        if not all(key):
+            daudit['missing_identity'] += 1; continue
+        cases[key].append((row, d))
+    rate_observed_dates = [date.fromisoformat(r['Chargeback date'][:10]) for r in disputes
+                           if verified_provider(r) and date.fromisoformat(r['Chargeback date'][:10]) <= cutoff]
+    events, uncertain = [], []
+    for rows in cases.values():
+        mids = {r.get('_merchant') for r, _ in rows if r.get('_merchant')}
+        brands = {brand_of(r) for r, _ in rows}
+        conflict = len(mids) > 1 or len(brands) > 1
+        if len(mids) > 1:
+            daudit['conflicting_merchant_cases'] += 1
+        if len(brands) > 1:
+            daudit['conflicting_brand_cases'] += 1
+        if conflict:
+            for mid in mids:
+                for _, d in rows:
+                    for brand in brands:
+                        uncertain.extend((mid, d, k) for k in affected_series(brand))
+            continue
+        missing_merchant = [(r, d) for r, d in rows if not r.get('_merchant')]
+        if missing_merchant:
+            daudit['unattributed_snapshots'] += len(missing_merchant)
+        rows = [(r, d) for r, d in rows if r.get('_merchant')]
+        for kind in {stage(r) for r, _ in rows}:
+            selected = [(r, d) for r, d in rows if stage(r) == kind]
+            if kind is None:
+                daudit['unclassified_snapshots'] += len(selected)
+                for r, d in selected:
+                    for mid in mids:
+                        uncertain.extend((mid, d, k) for k in affected_series(brand_of(r)))
+                continue
+            events.append((next(iter(mids)), min(d for _, d in selected), kind))
+    # Rates use opening evidence independently of the existing observed-stage counts.
+    rate_events, rate_uncertain = [], unidentified_fraud[:]
+    for row in disputes:
+        d = date.fromisoformat(row['Chargeback date'][:10])
+        if d <= cutoff and (not row.get('Provider') or not row.get('MID') or not row.get('Dispute ID') or not row.get('_merchant')):
+            rate_uncertain.append((row.get('_merchant') or None, d, brand_of(row), 'missing case identity or merchant'))
+    for rows in cases.values():
+        mids = {r.get('_merchant') for r, _ in rows if r.get('_merchant')}
+        brands = {brand_of(r) for r, _ in rows}
+        if not verified_provider(rows[0][0]) or len(mids) != 1 or len(brands) != 1 or any(not r.get('_merchant') for r, _ in rows):
+            candidate_mids = mids | ({None} if any(not r.get('_merchant') for r, _ in rows) else set())
+            for mid in candidate_mids:
+                for brand in brands:
+                    for _, d in rows:
+                        rate_uncertain.append((mid, d, brand, 'unverified provider or conflicting or missing case attribution'))
+            continue
+        mid, brand = next(iter(mids)), next(iter(brands))
+        if brand not in ('visa', 'mastercard'):
+            for _, d in rows:
+                rate_uncertain.append((mid, d, brand, 'unknown case brand'))
+            continue
+        requests = [(r, d) for r, d in rows if (r.get('Lifecycle state'), r.get('Original cycle')) == ('1st chargeback', 'First CB Request')]
+        pre = [(r, d) for r, d in rows if stage(r) == 'visa_predispute']
+        if pre:
+            rate_events.append((mid, min(d for _, d in pre), 'visa_predispute'))
+        formal = [(r, d) for r, d in rows if stage(r) in ('visa_dispute', 'mastercard_chargeback')]
+        if requests:
+            opening = min(d for _, d in requests)
+            key = 'visa_dispute' if brand == 'visa' else 'mastercard_chargeback'
+            rate_events.append((mid, opening, key))
+            for r, d in formal:
+                if d < opening:
+                    rate_uncertain.append((mid, d, key, 'earlier status may change opening month'))
+                    rate_uncertain.append((mid, opening, key, 'earlier status may change opening month'))
+                    if brand == 'mastercard':
+                        rate_uncertain.extend([(mid, d, 'mastercard_efm', 'earlier status may change opening month'),
+                                               (mid, opening, 'mastercard_efm', 'earlier status may change opening month')])
+            if brand == 'mastercard':
+                reasons = {(r.get('Reason code') or '').strip() for r, _ in rows}
+                if len(reasons) != 1 or not next(iter(reasons)):
+                    rate_uncertain.append((mid, opening, 'mastercard_efm', 'missing or conflicting reason code'))
+                elif next(iter(reasons)) in ('4837', '4863'):
+                    rate_events.append((mid, opening, 'mastercard_efm'))
+        elif formal:
+            for _, d in formal:
+                rate_uncertain.append((mid, d, 'visa_dispute' if brand == 'visa' else 'mastercard_chargeback', 'formal opening not verified'))
+                if brand == 'mastercard':
+                    rate_uncertain.append((mid, d, 'mastercard_efm', 'formal opening not verified'))
+        for r, d in rows:
+            if stage(r) is None:
+                rate_uncertain.append((mid, d, brand, 'unclassified case stage'))
+    variants = defaultdict(list)
+    for row, observed in first_seen.items():
+        if row[10] and row[1] and dart_date(row[5]) <= cutoff:
+            variants[row[10], row[1]].append(observed)
+    for identity, dates in variants.items():
+        if len(dates) > 1:
+            for mid, _, brand in fraud_groups.get(identity, []):
+                if brand == 'visa':
+                    for d in dates:
+                        rate_uncertain.append((mid, d, 'visa_fraud', 'multiple distinct fraud records for ARN and MID'))
+
+    rate_sales, undated_sales, unidentified_sales = [], [], []
+    for row in settlements:
+        if row.get('Settlement type') != 'Sale' or row.get('Settlement status') != 'Settled':
+            continue
+        if ' '.join((row.get('Provider') or '').split()).casefold() != 'worldpay - acquiring':
+            continue
+        try:
+            settled = date.fromisoformat(row['Settlement date'][:10])
+        except (KeyError, ValueError, TypeError):
+            settled = None
+        if settled is not None and settled > cutoff:
+            continue
+        try:
+            stamp = datetime.fromisoformat(row['Timestamp'])
+            if stamp.tzinfo is not None:
+                raise ValueError('zoned transaction timestamp')
+            transaction = stamp.date()
+        except (KeyError, ValueError, TypeError):
+            undated_sales.append((row.get('_merchant') or row.get('Sub merchant ID') or None, brand_of(row)))
+            continue
+        if settled is None:
+            undated_sales.append((row.get('_merchant') or row.get('Sub merchant ID') or None, brand_of(row)))
+            continue
+        if transaction <= cutoff and settled <= cutoff:
+            sale = (row.get('_merchant') or row.get('Sub merchant ID') or None, transaction,
+                    brand_of(row), (row.get('Transaction source') or '').strip().casefold())
+            if not (row.get('Transaction ID') or '').strip():
+                unidentified_sales.append(sale)
+            else:
+                rate_sales.append(sale)
+
+    sales_by_month = defaultdict(list)
+    for sale in rate_sales:
+        sales_by_month[sale[1].strftime('%Y-%m')].append(sale)
+
+    def rate_point(first, last, mid, key, weekly=False):
+        brand = 'mastercard' if key in ('mastercard_chargeback', 'mastercard_efm') else 'visa'
+        if brand == 'mastercard':
+            end = first - timedelta(days=1)
+            start = end.replace(day=1)
+        else:
+            start, end = first, last
+        formulas = {'visa_predispute': 'observed Visa RDR cases / same-month Visa sales (descriptive; excluded from VAMP)',
+                    'visa_dispute': 'Visa First CB Request cases / same-month Visa sales',
+                    'mastercard_chargeback': 'Mastercard First CB Request cases / prior-month Mastercard sales',
+                    'visa': 'attributed Visa fraud report records / same-month Visa sales',
+                    'mastercard_efm': 'Mastercard First CB Request cases with reason 4837 or 4863 / prior-month ecommerce Mastercard sales'}
+        date_bases = {'visa': 'User-confirmed DART file creation date as fraud report date',
+                      'visa_predispute': 'Earliest observed RDR date',
+                      'visa_dispute': 'First CB Request chargeback date',
+                      'mastercard_chargeback': 'First CB Request chargeback date',
+                      'mastercard_efm': 'Mastercard formal opening date (First CB Request chargeback date)'}
+        detail = {'numerator': None, 'denominator': None, 'denominator_start': start.isoformat(),
+                  'denominator_end': end.isoformat(), 'status': 'unresolved', 'reason': None, 'formula': formulas[key],
+                  'date_basis': date_bases[key]}
+        if weekly:
+            detail.update(denominator_start=None, denominator_end=None, status='not_applicable')
+            detail['reason'] = 'Network monitoring programs are monthly; weekly rates are not calculated.'
+            return None, detail
+        source_observed = any(first <= d <= last for d in (valid_dates if key == 'visa' else rate_observed_dates))
+        ambiguity_key = 'visa_fraud' if key == 'visa' else brand
+        ambiguous = any((m is None or m == mid) and first <= d <= last and
+                        (b == ambiguity_key or b == key or b not in ('visa', 'mastercard', 'visa_fraud', 'visa_predispute', 'visa_dispute', 'mastercard_chargeback', 'mastercard_efm'))
+                        for m, d, b, _ in rate_uncertain)
+        if key == 'visa':
+            numerator = sum(m == mid and first <= d <= last and b == 'visa' for m, d, b in fraud)
+        else:
+            numerator = sum(m == mid and first <= d <= last and k == key for m, d, k in rate_events)
+        if source_observed and not ambiguous:
+            detail['numerator'] = numerator
+        candidates = [(m, d, b, channel) for m, d, b, channel in sales_by_month[start.strftime('%Y-%m')] if start <= d <= end]
+        scoped = [(m, d, b, channel) for m, d, b, channel in candidates if m == mid and b == brand]
+        unknown_scope = any((m is None or m == mid) and (b == brand or b not in ('visa', 'mastercard')) and
+                            (m is None or b not in ('visa', 'mastercard')) for m, d, b, channel in candidates)
+        unknown_date = any((m is None or m == mid) and (b == brand or b not in ('visa', 'mastercard'))
+                           for m, b in undated_sales)
+        unknown_identity = any(start <= d <= end and (m is None or m == mid) and
+                               (b == brand or b not in ('visa', 'mastercard'))
+                               for m, d, b, _ in unidentified_sales)
+        unknown_channel = key == 'mastercard_efm' and any(channel not in ('ecomm', 'pos', 'moto') for _, _, _, channel in scoped)
+        if scoped and not unknown_scope and not unknown_channel and not unknown_date and not unknown_identity:
+            detail['denominator'] = sum(key != 'mastercard_efm' or channel == 'ecomm' for _, _, _, channel in scoped)
+        if ambiguous:
+            detail['reason'] = 'Case or fraud event identity, opening, attribution or reason is unresolved.'
+        elif not source_observed:
+            detail['reason'] = 'No source observations in this month.'
+        elif unknown_scope or unknown_channel or unknown_date or unknown_identity:
+            detail['reason'] = 'Sale identity, attribution, brand, transaction date or ecommerce channel is incomplete.'
+        elif detail['denominator'] is None:
+            detail['reason'] = 'No observed scoped sales in the denominator month.'
+        elif not numerator or not detail['denominator']:
+            detail['reason'] = 'Numerator or denominator is zero; no rate point under the point contract.'
+        else:
+            detail['status'] = 'observed_extract_estimate'
+            detail['reason'] = 'Observed source coverage is incomplete or unverified; not an official network assessment.'
+            return numerator / detail['denominator'], detail
+        return None, detail
+
+    def grid(period_list, events, mid, keys, kind):
+        out = []
+        for label, first, last, partial in period_list:
+            if kind == 'fraud':
+                observed = any(first <= d <= last for d in valid_dates)
+                coverage = {'status': 'supplied_valid_files' if observed else 'no_valid_files',
+                            'valid_file_dates': sum(first <= d <= last for d in valid_dates),
+                            'invalid_file_dates': sum(first <= d <= last for d in invalid_dates),
+                            'complete': False}
+            else:
+                observed = any(first <= d <= last for d in observed_dates)
+                coverage = 'observedexports' if observed else 'no_observations'
+            vals = {k: sum(m == mid and first <= d <= last and s == k for m, d, s in events)
+                    if observed and (kind != 'dispute' or not any(
+                        m == mid and first <= d <= last and s == k for m, d, s in uncertain))
+                    else None for k in keys}
+            rate_keys = ['visa', 'mastercard_efm'] if kind == 'fraud' else ['visa_predispute', 'visa_dispute', 'mastercard_chargeback']
+            computed = {k: rate_point(first, last, mid, k, period_list is weeks) for k in rate_keys}
+            out.append({'label': label, 'start': first.isoformat(), 'end': last.isoformat(), 'values': vals, 'coverage': coverage, 'partial': partial,
+                        'rates': {k: v[0] for k, v in computed.items()}, 'rate_details': {k: v[1] for k, v in computed.items()}})
+        return out
+    result = []
+    for merchant in merchants:
+        mid = merchant['id'] or ''
+        result.append({'id': merchant['id'], 'name': merchant['name'],
+            'disputes': {'monthly': grid(months, events, mid, ['visa_predispute', 'visa_dispute', 'mastercard_chargeback'], 'dispute'),
+                         'weekly': grid(weeks, events, mid, ['visa_predispute', 'visa_dispute', 'mastercard_chargeback'], 'dispute'),
+                         'basis': 'observed cases at earliest supplied chargeback date per stage, not verified openings',
+                         'limitations': 'Observed exports only; escalation may appear in both stages; reversals do not subtract.'},
+            'fraud': {'monthly': grid(months, fraud, mid, ['visa', 'mastercard', 'other'], 'fraud'),
+                      'weekly': grid(weeks, fraud, mid, ['visa', 'mastercard', 'other'], 'fraud'),
+                      'basis': 'DART file creation date as report date (user-confirmed); earliest report date for exact repeats',
+                      'limitations': 'Exact records, not unique events; incomplete supplied feed; unmatched records excluded.',
+                      'status': 'supplied_valid_files' if valid_dates else 'no_valid_files',
+                      'reason': None if valid_dates else 'No eligible valid fraud files supplied.'},
+            'vamp': {'monthly': [{'label': l, 'start': a.isoformat(), 'end': b.isoformat(), 'values': {'vamp_ratio': None}, 'partial': p} for l, a, b, p in months],
+                     'status': 'unavailable', 'reason': '缺少经核实的 TC15/TC05 处理日、排除标记及网络事件范围',
+                     'eligibility_missing': ['TC15/TC05 processing date', 'eligibility and exclusions', 'network event scope', 'event identity', 'complete coverage']}})
+    return result, {'files': files, 'physical_rows': physical, 'distinct_exact_rows': len(first_seen),
+                    'fraud_attribution': dict(audit), 'unmatched_amounts_by_currency': {k: str(v) for k, v in sorted(unmatched_amounts.items())},
+                    'first_observations_by_month': dict(sorted(observations.items())),
+                    'fraud_feed_status': 'supplied_valid_files' if valid_dates else 'no_valid_files',
+                    'fraud_report_date_policy': 'DART file creation date as report date (user-confirmed); earliest report date for exact repeats',
+                    'rate_basis': 'Network-style estimates from observed extracts, not official program assessments; source calendar labels, timezone unverified; unmatched fraud records excluded; source coverage unverified.', 'disputes': dict(daudit),
+                    'observed_dispute_stage_cases': len(events), 'coverage': 'supplied exports only; continuity unverified'}

package/skills/risk-compliance/similar-domain/SKILL.md

@@ -6,9 +6,9 @@ description: >
   (analytics, tenant and payment account IDs, support-email domains,
   templates, DNS, mail, certificates, registration), reverse pivots, scored
   links, an entity chain, and a watchlist for the operator's next domains.
-  Not transaction data (tld-detection) or fraud rules (fraud-analysis).
+  Not transaction data (tld-detection) or fraud rules (fraud-detection).
 disable-model-invocation: true
-release-version: 0.44.1
+release-version: 0.45.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Similar Domain
@@ -132,7 +132,12 @@ open and the report lists the unrun pivots.
 ### 7 — Report
 
 [references/report-template.md](references/report-template.md). Terms:
-[references/terminology.md](references/terminology.md).
+[references/terminology.md](references/terminology.md). Read
+`{house-style baseDir}/references/analytical-reporting.md` and its required references,
+then use `{write-report baseDir}/SKILL.md` with the frozen cluster and domain template.
+If a required skill or reference is unavailable, report the blocker. Do not rerun
+fingerprinting or scoring for the writing pass. Give the reviewer the shared entrypoint,
+its required references, the domain template and the sanity check.
 
 ```text
 reports/similar-domain/<seed>_cluster.md
@@ -163,7 +168,7 @@ Track a task plan. One item is `in_progress` at a time.
 |---|---|
 | Related domains, mirrors, sister sites, who runs a website, merchant-site background | `similar-domain` |
 | Anything inside a transaction file: upstream streams behind a descriptor, wallet currency, preset menus, frozen-rate batches, retail constants, currency-amount ladders | `tld-detection` (`scripts/detect_streams.py`, then the ladder run) |
-| Supervised fraud labels, holdout precision/recall, rule packages | `fraud-analysis` |
+| Transaction-level fraud rule discovery and evidence-qualified metrics | `fraud-detection` |
 | Volume, journey, auth rate, decline mix | `payment-analysis` |
 
 A domain cluster from this skill can feed a merchant-risk decision; it is not