dsh-whale-post-gate

English: gate README in English

配额与计费闸 ＋ 回环闸（可换的挂点 —— 示例②）

• 提供接口：whale.gate
• 依赖接口：whale.types（可选）、whale.roster（可选，用于把"一个组"算成 1 单位）
• 自测：node selftest.mjs（只看退出码：0 过／非 0 不过）

接口带 apiVersion；核心不认识任何成员名与类型标识 —— 名单与类型一律从接口取。

三道闸 ＋ 配额（每道都写明为什么）

离线件豁免整套回环闸（2026-10-10 按设计文档移植；设计文档判据 29-31 ＋「今天的设计目标是 2026-10-06」）： 三道闸拦的都是"别多叫醒人一次" —— 而离线件根本不叫醒任何人（它躺着等对方来收） ⇒ 拦它没有任何收益，只会把"想说的话"堵在发信人手里。 这正是"信只会晚到，不会不到"："闸"该拦的是代价**，不是表达。 ⚠️ 豁免的只是回环闸 —— 配额照旧（离线桶独立计）；在线件一切照旧。

#	闸	拦什么
①	纯回执拒发	正文去掉空白标点后只剩"收到／好的／谢谢" ⇒ 拒发（回执本该由收信方自动写 ack）
②	同对回环闸	同一对（你→对方）在 pairWindowMs 内已发 pairMax 封 ⇒ 拒发，先合并成一封
③	链深闸	带 re 的信按父信 hop 递推，到 hopMax 跳 ⇒ 拒发（链条必须落地成结论）
④	配额	分桶计额度；离线件独立计（按发信次数，1 次＝1 条，组发不翻倍）
⑤	在线件小日上限（S8）	"手机"这类成员：每封在线件 ＝ 叫醒它做一次满上下文推理（最贵的一步）⇒ 按 min(自报, 天花板) 拦；离线件不受这条限；--force 不豁免

接口

方法	一句话
check(letter, ctx)	拦不拦：'pass'／{ reject, reason }
record(letter, targets)	投递成功后才记账（被拦下的信不占额度）
report({ as, days })	查账（只读）
cfg／localDay()／quotaUnits()	生效配置／日界／"这封算几个单位"

配置

字段	默认	含义
quota.onOver	'reject'	'reject' 拒发（退出码非 0、不落信箱）／'price' 照发但计费（"闸是价格闸，不是封嘴闸"）
quota.dayBoundaryHour	0	日界：0 ＝ 自然日；写 9 ＝ 早九点到次日早九点算一天
quota.types	direct 120／broadcast 45／club 60／offline 80	每桶 limit；离线桶可 perSend: true（按发信次数计）
quota.defaultLimit	120	没在表里的类型落这个桶（否则"注册一个新类型"在闸这层就不成立）
quota.bucketRules	不配	分桶规则（数组）：[{ field, equals, bucket }] —— 从上往下第一个命中的赢；equals 不写 ⇒ "该字段有值就命中"。字段名与桶名全由配置给（本件里不出现任何具体名字）。不配 ⇒ 行为一字不变（离线走 offline、其余按 type）
now（顶层）	不配	时钟可注入：给一个有限数字（钉死时刻）或函数（() => ms）⇒ 台账的"哪一天"按它算（不配 ⇒ 真时间）。为什么要它：**"生效时刻"**这类规则（"09:00 前按旧口径、到点后才分桶"）必须能拿假时间测 —— 原来处处裸 Date.now() ⇒ 测不了
quota.defaultBucket	不配	一条规则都没命中时落哪个桶（配了 bucketRules 才有意义 —— 必须有，否则"带新字段的信"会掉回 type 桶）
quota.phoneFlag	不配	谁是"手机"（属性名由配置给 —— 本件不认识任何具体名字）：带此属性的收件人只算在线件的小日上限。不配 ⇒ 这道闸完全不启用
quota.phoneOnlineCap	3	天花板：实际额度 ＝ min(收件人自报的 onlineCapPerDay, 这个) —— "收件习惯由它自己声明，而声明只能更保守"（它能把上限调到 1，调不到天花板之上）。没自报 ⇒ 用天花板（"没说" ≠ "可以一直叫醒它"）
loop.ackMaxBytes	40	多长的正文才可能被当回执
loop.ackOnly	中英回执词	中英都认（只认中文 ⇒ 英文回执成了绕过闸的后门）
loop.pairWindowMs	20 分钟	同对回环的时间窗
loop.pairMax	3	同一对在这个窗内最多发几封
loop.hopMax	3	链深上限

边界（两条老实话，免得下一个人把它当安全边界）

• 链深闸不是安全边界 —— 它依赖回信人老实带 re，不带就重置。它是礼貌闸／省米闸。
• --force 会整条绕过这三道闸（这是有意留的逃生门），但留痕：台账当日记 forced 计数。
• 剔完组里没人 ⇒ 拒发（配额按组算时会遇到 —— 宁可拒发，也不发一封没有收件人的信）。

换掉它

想换一套计费口径（比如按字节计费、或者干脆不限额）⇒ 只换这一件， 核心与别的插件一行都不用动（它们只认 check／record／report／recount 这四个）。

对账（台账可以"验"，不只是"信"）

台账是基线 ＋ 增量小文件，口径是「账可少不可多」（崩了可能漏记 ⇒ 对发信人有利，绝不双记）。 recount 是给"验"用的那一半：从文件系统重算一份按天的账，跟台账逐日逐桶比。 命令在 cli 里 —— whale-post reconcile --as <谁> [--days N] [--remote <根>] （用法见 packages/cli/README）：一致 ⇒ 退出 0；有差 ⇒ 退出 3。

⚠️ 它能算的：letters／units／bytes／byBucket.<桶>.{letters, units}； 不能算的（文件里没有那些事实，命令会照实列出来）：forced（force 是发送那一刻的选择）、 over／feeCent（取决于记账当时读到的已用量）、byPhone／recent（记账时属性与收据）。