#tally

MoonBit 上下文装配的可核验契约——把任意长度的上下文精确压进 token 预算，并让「丢了什么、为什么」可以被第三方逐字节复算。

1. 精确计数：cl100k 形状的 byte-level BPE，2,935 条语料与 tiktoken 0.14.0 逐 token 对齐，差异 0。
2. 可解释装配：按 Priority 把段落装进窗口，Pinned 永不裁，输出「丢了哪段、多少 token、为什么」。
3. 可复现：词表与报告都是规范文本，格式被 FORMAT.lock 逐字节钉死，改一个字节测试就红。
4. 可验证：报告旁可附 tally-digest v1 侧车——报告字节、逐段字节各留一个 sha256； verify 先查两份文件是否自洽，给齐词表与输入再重新装配一遍做逐字节复算。 「报告说装了这些」因此可以被别人验，而不是只能相信。
5. 可认账（0.6.1）：摘要还能被一把共享密钥盖成 tally-seal v1，verify --seal --key 一次验完「摘要没被换」和「有人认过」。它证明持有密钥的人签过，不证明谁写的—— 对称密钥没有身份，这一点写进格式而不是藏进文档。
6. 预算不够时还有三件细活（0.8.0 已实现）：多池配额（工具定义、多轮历史各有一份额度， 不够按声明顺序借用，逐池记 borrowed / lent）、同优先级内按分数取舍 （检索分数不再被硬映射成优先级，而是同优先级里的次序）、占位压缩 （被裁的尾部换成固定标记并写明省了多少 token，模型知道「这里还有内容」）。

let segments = [
  @tally.pinned("system", "you are a helpful assistant."),   // 永不裁
  @tally.oldest("history", "...前 50 轮..."),                 // 最先牺牲
  @tally.newest("user", "现在的问题"),
]
// 窗口 8192，留 1024 给回复 → 输入预算 7168；超了先截段首（保留最近内容）
let cfg = @tally.fit_config(@tally.cl100k(v), 8192L)
  .with_reserve(1024L)
  .with_strategy(@tally.truncate_head())
let plan = @tally.fit_with(cfg, segments)
println(plan.render())   // kept / truncated / dropped 三段清单与原因

match @tally.fit_with_result(cfg, segments) {
  Ok(plan) => println(plan.render())
  Err((reserve, window)) => println("reserve \{reserve} 吃掉了窗口 \{window}")
}

#七个问题，一份契约

#0.8.0：预算不够时的三种细活

#多池配额与借用

1. 第一轮照旧按全局预算装，Pinned 先占；
2. 第二轮逐池核对：某池超配额时，先按声明顺序向还有余额的池借 （spare = 配额 − 占用 − 已借出），借完仍超就在池内继续裁/丢。

#同优先级内按分数取舍

#占位压缩

…[tally: 1491 tokens omitted]…

#它是什么

#与 tokenizers-moonbit 的分工

// 示意：适配外部 tokenizer，不需要给外部类型写 impl
let counter : @tally.Counter = {
  name: "tokenizers-moonbit/cl100k",
  exact: true,
  count_bytes: fn(bytes) { their_tokenizer.count(bytes) },
}
let plan = @tally.fit_with(@tally.fit_config(counter, 8192L), segments)

#快速开始

#作为库

moon add weopqrst/tally

fn demo(vocab_text : String) -> Unit raise {
  // 加载词表（自有规范文本格式，见下）；加载后不可变
  let v = @tally.load(vocab_text)

  // 1) 预算装配：主路径。按优先级装进 4096，给出丢弃报告
  //    四个构造器都在门面包里，只 import `weopqrst/tally` 就够
  let segments = [
    @tally.pinned("system", "you are a helpful assistant."),
    @tally.oldest("history", "hello world hello world"),
    @tally.newest("user", "hello there token"),
  ]
  let plan = @tally.fit(v, segments, 4096L)
  println(plan.render())

  // 2) 窗口 + 预留 + 截断：留 1024 给回复，超预算的段保留段尾
  //    策略同样有门面构造器：truncate_none / truncate_tail / truncate_head
  let cfg = @tally.fit_config(@tally.cl100k(v), 8192L)
    .with_reserve(1024L)
    .with_strategy(@tally.truncate_head())
  println(@tally.fit_with(cfg, segments).render())

  // 3) 精确计数
  println(@tally.count(v, "it's a test"))

  // 4) 编码 / 解码：任意字节序列都可编码，解码后逐字节还原
  let ids = @tally.encode(v, @utf8.encode("hello world"))
  println(@tally.decode(v, ids))

  // 5) 逐片明细：哪一段在吃 token
  for piece in @tally.piece_counts(v, @utf8.encode("hello there token")) {
    println(piece)
  }

  // 6) 0.8.0：池配额 + 借用 + 占位压缩 + 同优先级按分数取舍
  let pooled = [
    @tally.pinned("system", "you are a coding agent."),
    // 工具定义归 tools 池，分数 9：池内超额时分数低的先走
    @tally.with_score(@tally.with_pool(@tally.newest("tool", "read_file(path)"), "tools"), 9L),
    @tally.with_score(@tally.with_pool(@tally.newest("tool", "run_tests(args)"), "tools"), 4L),
    @tally.with_pool(@tally.oldest("history", "...前 6 轮..."), "history"),
  ]
  // tools 只给 20，history 有余额：按声明顺序借用，报告里记 borrowed/lent
  let cfg2 = @tally.fit_config_pools(
    @tally.fit_config(@tally.cl100k(v), 1024L).with_strategy(@tally.truncate_compress()),
    [("tools", 20L), ("history", 512L)],
  )
  println(@tally.fit_with(cfg2, pooled).render())
}

fn train_demo() -> Unit raise {
  let corpus = [@utf8.encode("hello world"), @utf8.encode("hello 世界")]
  let result = @tally.train(corpus, 280, 1, ["<|endoftext|>"])
  println(result.to_text())          // tally-train v1 配方，可 diff、可冻结
  let back = @tally.load_train(result.to_text())
  println(@tally.count(back.vocab, "hello world"))
}

#CLI

# 预算装配（Pinned 段保护 + 丢弃报告）——最常用
# 输出：system 段 kept 26 token，payload 段 dropped 5 token 并给出原因
moon run cmd/main --target js -- fit --vocab tests/golden/sample-vocab.txt --limit 28 --text "hello world hello world"

# 窗口 34、留 4 给回复 → 输入预算 30；payload 段保留段首截到 4 token
moon run cmd/main --target js -- fit --vocab tests/golden/sample-vocab.txt --limit 30 --reserve 4 --truncate tail --text "hello world hello world"

# 同理，但保留段尾（最近内容）：--truncate head

# 占位压缩：保留段首，被裁的尾部换成固定标记（写明省略量），标记本身也计入预算
moon run cmd/main --target js -- fit --vocab tests/golden/sample-vocab.txt --limit 60 --truncate compress --text "hello world hello world"

# 多段 + 多池：--segment <role>:<priority>:<path>、--pool <name>=<limit>、
# --segment-pool <role>=<name>（把该 role 的所有段归入池）、--segment-score <role>=<n>
moon run cmd/main --target js -- fit --vocab tests/golden/sample-vocab.txt --limit 400 `
  --segment system:pinned:system.txt --segment tools:newest:tools.txt --segment history:oldest:history.txt `
  --pool tools=10 --pool history=300 --segment-pool tools=tools --segment-pool history=history

# 计数
moon run cmd/main --target js -- count --vocab tests/golden/sample-vocab.txt --text "hello world"

# 逐片明细（哪段在吃 token）
moon run cmd/main --target js -- count --vocab tests/golden/sample-vocab.txt --text "hello there token" --explain

# 编码为 id 序列
moon run cmd/main --target js -- encode --vocab tests/golden/sample-vocab.txt --text "hello world"

# 报告 + 摘要侧车：报告给人读（tally-plan v2），摘要给机器验（tally-digest v1）
moon run cmd/main --target js -- digest --vocab tests/golden/sample-vocab.txt --limit 30 --reserve 4 --truncate tail --text "hello world hello world"

# 校验：先查两份文件是否自洽；给齐 --vocab + 输入则再复算一遍并逐字节比对
moon run cmd/main --target js -- verify --report report.txt --digest digest.txt --vocab tests/golden/sample-vocab.txt --limit 30 --reserve 4 --truncate tail --text "hello world hello world"

# 印记：用共享密钥把摘要认一遍（密钥不进输出；生产环境用 --key-file 而不是 --key）
moon run cmd/main --target js -- seal --digest digest.txt --key ci-key --key-id ci

# 带印记校验：自洽 + 印记 +（给齐输入时）端到端复算，三层一次走完
moon run cmd/main --target js -- verify --report report.txt --digest digest.txt --seal seal.txt --key ci-key

error: report sha256 mismatch: digest says 317c0e78…, file is d7dd9d5b…

#示例（可运行、可 diff）

moon run cmd/examples --target js -- all          # 全部跑一遍
moon run cmd/examples --target js -- big-input    # 也可以单跑

#词表格式

# tally-vocab v1
# unicode 17.0.0
# tokens 277
[specials]
276 PHxlbmRvZnRleHR8Pg==
[tokens]
0 0 AA==
...

#训练产物格式

# tally-train v1
# unicode 17.0.0
# corpus_bytes 180
# corpus_words 43
# vocab_size 280
# min_frequency 2
# tokens 280
[merges]
256 MTI= MQ== Mg==
...
[specials]
279 PHxlbmRvZnRleHR8Pg==

#格式冻结（FORMAT.lock）

• counter 名字、段 role、池名、丢弃原因都不得含空格或换行——它们直接进行内 （CLI 的 --segment / --pool / --segment-pool 会先校验，不合规直接报错）；
• overflow = true 时 [dropped] 末尾多一行哨兵：-1 pinned *overflow* <excess> <原因>。 它不对应任何段，tokens 是超出量；按段对账时按 index == -1 跳过（Plan.excess 是同一数值）；
• [truncated] 行尾恒有 omitted=<n>（n 是被丢掉的原 token 数），[pools] 行的六个字段 <池名> <配额> <需求> <占用> <借入> <借出> 后五个恒为整数。

#报告摘要格式 tally-digest v1

tally-digest v1
report <报告文件的 sha256>
plan <[segments] 正文的 sha256>
[segments]
0 kept <该段实际字节的 sha256>
1 dropped -

• 段行按 index 升序排列，与报告里 kept→truncated→dropped 的分节无关（对账前两侧各自排序）；
• dropped 段的 sha 固定为 -：它没进窗口，没有"进了窗口的字节"可言；
• 溢出哨兵 -1 也列进摘要且参与 plan 哈希（"溢出过"要可核对），但段对账时两侧都跳过它；
• 换行先归一（UTF-8 BOM 去掉、CRLF→LF、尾部空行折叠），所以 Windows 控制台重定向与 编辑器写出的文件同样可验；UTF-16（PowerShell 5.1 的默认重定向编码）会被拒绝并提示另存为 UTF-8。

#印记格式 tally-seal v1

tally-seal v1
scheme hmac-sha256
key_id ci
digest <摘要文件的 sha256>
seal <HMAC-SHA256 hex>

• seal 覆盖前四行（含头部），不覆盖自己——签名不可能覆盖自身；
• key_id 也在这四行里：只改标识不重算 mac 就会失败（轮换密钥必须重新盖）；
• 只认 hmac-sha256，别的 scheme 直接拒绝，不做"猜一个"的兼容；
• 空密钥被拒：空密钥等于人人可签，印记就失去意义；
• 它是对称的：证明持有同一把密钥的人认过，不证明谁写的。要证明身份需要非对称 签名与公钥分发，那是另一件事（见「非目标」）；
• 密钥不进任何输出：印记文件可以入库、可以贴进工单，密钥只从 --key-file（或调用方 自己的密钥管理）注入，不走 --key 落进 shell 历史。

#1.0 承诺：API 与格式冻结（自 0.8.0 起）

版本号说明：mooncakes 现阶段只接受 0.x.y（moon package 会直接拒绝主版本不为 0 的 moon.mod），所以先以 0.8.x 发布（当前 0.8.1：0.8.0 落地能力，0.8.1 只改文档与 元数据，API 与格式零变更）。"1.0" 指的是这里的语义承诺（API 与五个格式冻结），不是 版本号字面；等平台放开主版本再落 1.0.0。

#非目标

• 不做通用分词器：不提供 o200k 等第二编码，不做 BPE 之外的算法（WordPiece / Unigram）。
• 不做公钥签名与身份体系：tally-seal v1 只有 HMAC-SHA256（对称），没有 Ed25519、 没有证书链、没有"谁签的"。它回答"有没有人认过"，不回答"是谁"。
• 不做通用正则引擎——只为固定的一条预切分模式手写扫描器。
• 不做性能优化：缓存与吞吐只给诚实数字，不设优化目标。
• 不是某个库的 MoonBit 版。公开词表文件只作验证语料与兼容性输入。
• 不做 LLM 客户端、向量检索、GUI / 文档站、服务端。

#已知边界

#性能（未优化）

moon bench -p cmd/perf --release --target wasm-gc   # 两项基准
python tools/check_bench.py                        # 与基线比，同 OS 超 2× / 跨 OS 超 3× 即失败

#开发

# 双后端检查与测试（两侧必须全绿且结果一致）
moon check --target wasm-gc
moon check --target js
moon test  --target wasm-gc
moon test  --target js

# 生成器的参考实现依赖（版本与 golden 绑定，见 requirements-dev.txt）
python -m pip install -r requirements-dev.txt
python tools/fetch_vocab.py           # 对齐 golden 的参考词表（不入库）

# 生成物：改动后重新生成并提交
python tools/gen_unicode.py            # Unicode 属性表
python tools/gen_sample_vocab.py       # 测试夹具词表
python tools/gen_pretoken_golden.py    # 预切分 golden
python tools/gen_alignment_golden.py   # 逐 token 对齐 golden
python tools/gen_format_lock.py        # FORMAT.lock 指纹（含 sample-train / sample-digest / sample-seal）

# 示例输出（改了报告格式或示例，需要 --update 并 review diff）
python tools/check_examples.py
python tools/check_examples.py --update

# CI：生成物 / 指纹 / 示例输出对不上就失败（手动跑同一组命令）
python tools/gen_unicode.py --check
python tools/gen_sample_vocab.py --check
python tools/gen_pretoken_golden.py --check
python tools/gen_alignment_golden.py --check
python tools/gen_format_lock.py --check
python tools/check_examples.py

#许可