codex-work-receipt 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## Unreleased
+
+- 将 HTML 小票底部的重复渐变装饰替换为按小票编号生成的真实 Code 128 B 条形码，并保留适合浏览器和长图导出的静区与清晰度。
+- 优化 multipart 扫码交互：单数据码继续与小程序码并排，多分片时先展示小程序码，再自动逐张轮播唯一可见的数据码，避免镜头同时识别多个二维码。
+
+## 0.6.0
+
+- 新增 cwr2 协议：按“会话 × 记账自然日”生成稳定的 canonical facts，重叠的今日、近 7 日和本周小票可由接收端可靠去重。
+- 新增 fact、session、receipt 的稳定匿名身份，以及 manifest、content hash 和 source revision，便于幂等导入和追加式会话更新。
+- Token 统计改为按来源顺序处理累计值重置，避免重置后出现负数或漏计。
+- 新增 `cwr2p` 分片二维码；单个 cwr2 超出安全二维码容量时自动拆分，最多 12 片，并支持乱序重组和分片/总校验。
+- 网页导入联可展示多张数据二维码；命令行输出二维码数量和 canonical fact 数量。
+- 保留 cwr1 解码兼容；旧版小票仍可作为私人历史导入，但不包含精确去重所需的 canonical facts。
+- 更新中英文手机导入、数据协议和隐私说明。
+
 ## 0.5.0
 
 - 新增网页版“保存完整长图”功能。

package/README.en.md

@@ -22,6 +22,8 @@
 
 Codex Work Receipt summarizes turns, tool calls, Tokens, duration, and models, then turns them into playful AI work points, a job title, and a review. Receipts never include prompts, responses, source code, project paths, or file names.
 
+Version `0.6.0` uses the cwr2 protocol to create stable privacy-safe facts for each session and calendar day. Overlapping today, last-seven-days, and this-week receipts can be deduplicated by the receiver, and oversized payloads are automatically split into reorderable multipart QR codes that rotate one at a time in the HTML so the camera never sees multiple data codes at once.
+
 ## Quickstart
 
 Requires Node.js 20+ and local Codex session records. No clone required; choose today, the last 7 days, this week, or a specific session:
@@ -54,7 +56,7 @@ Codex will choose the range and theme, run the CLI, and open the receipt. See th
 
 ## Desktop to mobile
 
-The desktop page generates a privacy-safe data QR code. The companion WeChat mini program supports QR import, local history, themes, and image export. See [mobile import](docs/mobile-import.en.md).
+The desktop page generates one or more privacy-safe data QR codes. The companion WeChat mini program supports multipart scanning, private history, themes, and image export. See [mobile import](docs/mobile-import.en.md).
 
 ## Docs
 

package/README.md

@@ -22,6 +22,8 @@
 
 它会统计 Codex 会话中的轮次、工具调用、Token、时长和模型，生成带有 AI 工分、今日工种和点评的小票。不会把 Prompt、回复正文、代码、项目路径或文件名写入小票。
 
+`0.6.0` 使用 cwr2 协议，按“会话 × 自然日”生成稳定的脱敏事实。今日、近 7 日和本周小票即使范围重叠，接收端也能识别相同工作；数据过大时会自动生成多张可重组的分片二维码，并在 HTML 中逐张自动轮播，避免镜头同时识别多个数据码。
+
 ## Quickstart
 
 需要 Node.js 20 或更高版本，并且本机已经使用过 Codex。无需克隆仓库，运行后选择“今天 / 近 7 日 / 本周 / 指定会话”：
@@ -54,7 +56,7 @@ Codex 会选择统计范围和主题、执行命令并打开小票。详见 [Cod
 
 ## 从电脑到手机
 
-桌面网页会生成脱敏的数据二维码。配套微信小程序支持扫码导入、本地历史、主题切换和保存图片。详见 [手机扫码导入](docs/mobile-import.md)。
+桌面网页会生成一张或多张脱敏数据二维码。配套微信小程序支持分片扫码、私人历史、主题切换和保存图片。详见 [手机扫码导入](docs/mobile-import.md)。
 
 ## 文档
 

package/docs/cli.en.md

@@ -79,7 +79,7 @@ Default output:
 
 Default filenames include the calendar range. Latest-session and selected-session receipts include a short identifier so receipts from different dates or sessions do not overwrite one another.
 
-Open the generated HTML and click “Save full PNG” to download a high-resolution image. It includes the main receipt, mini-program code, and data QR import stub in the currently selected theme. Theme controls, the page background, and the footer note are excluded.
+Open the generated HTML and click “Save full PNG” to download a high-resolution image. It includes the main receipt, mini-program code, and data QR import stub in the currently selected theme. Theme controls, the page background, and the footer note are excluded. With one data QR, the mini-program code and data code remain side by side. When cwr2 exceeds the safe capacity of one QR code, the page shows the mini-program code first and then rotates multipart data codes one at a time without desktop clicks. The full PNG still includes every numbered part so the offline payload remains complete.
 
 Set a timezone and output path:
 

package/docs/cli.md

@@ -79,7 +79,7 @@ npx codex-work-receipt@latest --latest --theme diner
 
 默认文件名会携带统计日期范围；最近会话和指定会话则携带短编号，避免不同日期或会话的小票互相覆盖。
 
-打开生成的 HTML 后，点击“保存完整长图”即可下载高清 PNG。图片包含主小票、小程序码和数据二维码导入联，并自动使用当前选择的主题；主题按钮、网页背景和底部说明不会进入图片。
+打开生成的 HTML 后，点击“保存完整长图”即可下载高清 PNG。图片包含主小票、小程序码和数据二维码导入联，并自动使用当前选择的主题；主题按钮、网页背景和底部说明不会进入图片。只有一个数据二维码时，小程序码与数据码继续并排展示。cwr2 数据超过单码安全容量时，网页先单独展示小程序码，随后自动逐张轮播分片数据码；用户无需在电脑上切换上一张或下一张，但仍需在小程序中收齐全部分片。完整长图为保留离线数据，会继续包含全部带序号的分片二维码。
 
 指定时区和输出路径：
 

package/docs/data-schema.en.md

@@ -24,8 +24,12 @@ The QR payload uses compact fields:
 
 ```text
 cwr1.<checksum>.<Base64URL of deflateRaw(JSON)>
+cwr2.<checksum>.<Base64URL of deflateRaw(JSON)>
+cwr2p.<transferId>.<partIndex>.<partCount>.<totalChecksum>.<partChecksum>.<chunk>
 ```
 
+`cwr1` and `cwr2` are complete single-code payloads. `cwr2p` splits the cwr2 string into up to 12 reorderable parts. The mini program collects a transfer by transferId, validates the total checksum, reconstructs cwr2, and only then decompresses it. Multipart HTML rotates one data code at a time; the protocol does not require scan order.
+
 The mini program validates the prefix and checksum before decompressing and parsing the payload. Future schema versions use the compact `v` field for compatibility.
 
 Compact field `o` explicitly carries `latest`, `session`, `today`, `last-7-days`, or `this-week`. `d[3]` and `d[4]` carry the calendar boundaries. These additive fields keep the `cwr1` prefix and schema version `1`, so the updated mini program can still import older QR codes.

package/docs/data-schema.md

@@ -24,8 +24,12 @@
 
 ```text
 cwr1.<checksum>.<deflateRaw(JSON) 的 Base64URL>
+cwr2.<checksum>.<deflateRaw(JSON) 的 Base64URL>
+cwr2p.<transferId>.<partIndex>.<partCount>.<totalChecksum>.<partChecksum>.<chunk>
 ```
 
+`cwr1` 和 `cwr2` 是完整单码。`cwr2p` 是 cwr2 单码字符串的可乱序分片，最多 12 片；小程序先按 transferId 收集全部分片，再校验总 checksum、拼回 cwr2 并解压。HTML 在多分片时每次只轮播一个数据码，协议本身不依赖扫描顺序。
+
 小程序应检查前缀和校验值，再解压并解析数据。未来结构升级通过 `v` 字段兼容。
 
 精简字段 `o` 显式携带 `latest`、`session`、`today`、`last-7-days` 或 `this-week`；`d[3]` 和 `d[4]` 携带自然日边界。新增字段保持 `cwr1` 和结构版本 `1`，旧二维码仍可由新版小程序导入。

package/docs/mobile-import.en.md

@@ -2,17 +2,19 @@
 
 <p><a href="./mobile-import.md">中文</a> · <strong>English</strong> · <a href="../README.en.md">Back to README</a></p>
 
-The desktop page shows both the fixed mini-program code and a data QR code for the current receipt. The companion mini program can complete the MVP import without a server:
+The desktop page shows both the fixed mini-program code and a data QR code for the current receipt. The companion mini program validates the protocol and privacy-safe fields on the phone, then saves the private receipt to the user's anonymous account database:
 
 1. Scan the fixed mini-program code in WeChat and open the companion mini program.
 2. Tap the desktop-import action.
-3. Scan the adjacent data QR code.
-4. Validate the `cwr1` prefix, checksum, and schema version.
-5. Decompress and parse the privacy-safe metrics.
-6. Recognize a session, today, last-seven-days, or this-week range, then deduplicate by receipt ID and store it locally.
+3. Scan the adjacent data QR code. Multipart receipts rotate one part at a time on the computer, while the mini program automatically reopens scanning until all parts are collected.
+4. Validate the `cwr1`, `cwr2`, or multipart `cwr2p` prefix, checksum, and schema version.
+5. Single codes decompress immediately. Multipart codes can arrive out of order, and missed parts are collected on the next rotation before the privacy-safe metrics are parsed.
+6. Recognize a session, today, last-seven-days, or this-week range. New receipts use canonical facts for deduplication and are stored in the anonymous account database by default.
 7. Render the selected template with Canvas and save it to the phone.
 
-The QR code does not transfer an image. The desktop page and mini program independently render the same structured receipt data. Older QR codes without an explicit range field remain supported through the legacy label fallback.
+The phone keeps only multipart staging, pending database writes, and necessary caches. Saving a private receipt does not automatically join public statistics; participation in the AI Cooperative is a separate choice inside the companion mini program.
+
+The QR code does not transfer an image. The desktop page and mini program independently render the same structured receipt data. Older QR codes without an explicit range field remain supported through the legacy label fallback. QR payloads exclude prompts, response text, source code, project paths, file names, and original session IDs.
 
 The companion mini program is a separate product. This repository does not contain its source code, AppID, backend code, or server credentials.
 

package/docs/mobile-import.md

@@ -2,17 +2,19 @@
 
 <p><strong>中文</strong> · <a href="./mobile-import.en.md">English</a> · <a href="../README.md">返回 README</a></p>
 
-桌面网页会同时展示固定小程序码和当前小票的数据二维码。配套小程序无需服务器即可完成 MVP 导入：
+桌面网页会同时展示固定小程序码和当前小票的数据二维码。配套小程序会先在手机端完成协议和隐私字段校验，再把私人小票保存到用户的匿名账号数据库：
 
 1. 微信扫描固定小程序码并打开配套小程序。
 2. 点击“从电脑导入”。
-3. 扫描网页旁边的数据二维码。
-4. 小程序校验 `cwr1` 前缀、checksum 和结构版本。
-5. 解压并解析脱敏统计数据。
-6. 识别单会话、今日、近七日或本周范围，并按小票 ID 去重写入本地历史。
+3. 扫描网页旁边的数据二维码；多分片小票会在电脑上自动逐张轮播，小程序在未集齐时自动继续打开扫码。
+4. 小程序校验 `cwr1`、`cwr2` 或 `cwr2p` 分片前缀、checksum 和结构版本。
+5. 单码立即解压；多分片允许乱序、漏扫后等待下一轮补齐，全部到齐再解析脱敏统计数据。
+6. 识别单会话、今日、近七日或本周范围；新版小票按规范事实去重，完整记录默认保存到匿名账号数据库。
 7. 使用 Canvas 重新绘制所选模板并保存到手机相册。
 
-二维码不会传输图片。桌面端和小程序端根据同一份结构数据分别渲染小票；旧版二维码没有显式范围字段时仍按原有文案兼容识别。
+手机本地只保留扫码分片、待入库记录和必要缓存。私人小票入库不等于自动加入公开统计；是否参与 AI 供销社匿名汇总由用户在配套小程序中单独决定。
+
+二维码不会传输图片。桌面端和小程序端根据同一份结构数据分别渲染小票；旧版二维码没有显式范围字段时仍按原有文案兼容识别。二维码不包含 Prompt、回复正文、代码、项目路径、文件名或原始会话 ID。
 
 配套小程序是独立产品，本仓库不包含其源码、AppID、后台代码或服务端密钥。
 

package/docs/privacy.en.md

@@ -23,6 +23,8 @@ Generated HTML and JSON files are written to `codex-work-receipt-output/` by def
 
 The runtime does not upload Codex session data to a project server. The initial or updated package download performed by `npx` is a normal package-manager network request and does not contain local session data.
 
+If the user actively scans a data QR code, the companion mini program saves the privacy-safe receipt to the user's anonymous account database for history recovery and canonical deduplication. This happens inside the companion product and does not upload prompts, response text, source code, project paths, file names, or original session IDs. Joining AI Cooperative aggregate statistics remains a separate user choice.
+
 ## QR payload
 
 The QR code contains versioned, privacy-safe receipt metrics only. It does not contain the original session or an image. Treat the QR code as a scannable data file and share it only with people you trust.

package/docs/privacy.md

@@ -23,6 +23,8 @@ AI 打工小票在本机读取 Codex 会话，并在本机完成统计和渲染
 
 运行期间不会把 Codex 会话数据上传到本项目的服务器。通过 `npx` 首次下载或更新 npm 包属于包管理器的正常网络请求，不包含本地会话内容。
 
+如果用户主动扫描数据二维码，配套小程序会把二维码中的脱敏小票保存到用户的匿名账号数据库，用于历史恢复和规范去重。这一步发生在配套小程序中，不会上传 Prompt、回复正文、代码、项目路径、文件名或原始会话 ID；是否参与 AI 供销社匿名统计仍由用户单独决定。
+
 ## 二维码
 
 二维码只包含当前小票的版本化脱敏统计，不包含原始会话或图片。二维码等同于一份可扫描的数据文件，请只向信任的人展示。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-work-receipt",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "type": "module",
   "description": "Generate a privacy-first Codex work receipt from local session metadata.",
   "author": "a-bai-2026",

package/src/cli.mjs

@@ -7,9 +7,10 @@ import { fileURLToPath } from "node:url";
 import QRCode from "qrcode";
 
 import { parseArgs, printHelp } from "./core/args.mjs";
+import { buildCanonicalFacts } from "./core/fact-buckets.mjs";
 import { collectMetrics } from "./core/metrics.mjs";
 import { getReceiptCopy } from "./core/presentation.mjs";
-import { encodeReceiptPayload } from "./core/qr-payload.mjs";
+import { encodeReceiptPayloads } from "./core/qr-payload.mjs";
 import { outputSlugForRange, resolveRange } from "./core/range.mjs";
 import { buildReceiptRecord, persistReceiptRecord } from "./core/receipt-record.mjs";
 import { promptForRange } from "./core/selector.mjs";
@@ -77,14 +78,16 @@ async function main() {
   const range = resolveRange(options.mode, options.timezone, new Date(), options.sessionId);
   const sessions = loadCodexSessions(range);
   const metrics = collectMetrics(sessions, range);
-  const record = buildReceiptRecord(metrics, options.theme, options.locale);
-  const qrPayload = encodeReceiptPayload(record);
-  const dataQrDataUrl = await QRCode.toDataURL(qrPayload, {
+  const observedAt = new Date().toISOString();
+  const canonical = buildCanonicalFacts(sessions, range, { observedAt });
+  const record = buildReceiptRecord(metrics, options.theme, options.locale, canonical);
+  const qrPayloads = encodeReceiptPayloads(record);
+  const dataQrDataUrls = await Promise.all(qrPayloads.map((payload) => QRCode.toDataURL(payload, {
     errorCorrectionLevel: "M",
     margin: 2,
     width: 360,
     color: { dark: "#171713", light: "#ffffff" },
-  });
+  })));
 
   const requestedOutput = options.output || path.join(
     DEFAULT_OUTPUT_DIR,
@@ -97,7 +100,7 @@ async function main() {
 
   fs.writeFileSync(
     outputFile,
-    renderHtml({ record, dataQrDataUrl, miniProgramCodeDataUrl }),
+    renderHtml({ record, dataQrDataUrls, miniProgramCodeDataUrl }),
     "utf8",
   );
   const persisted = persistReceiptRecord(record, outputFile, options.dataDir);
@@ -108,7 +111,7 @@ async function main() {
     console.log(`Local history: ${persisted.receiptPath}`);
     console.log(`Range: ${getReceiptCopy(options.locale).scope[record.source.scope]} · ${record.stats.session_count} session(s)`);
     console.log(`Stats: ${record.stats.completed_turns} turns · ${formatNumber(record.stats.tokens.total_tokens, options.locale)} Tokens · ${record.stats.tool_calls} tool calls`);
-    console.log(`Data QR: ${qrPayload.length} characters · schema v${record.schema_version}`);
+    console.log(`Data QR: ${qrPayloads.length} code(s) · ${record.manifest.fact_count} canonical fact(s) · schema v${record.schema_version}`);
     if (!miniProgramCodeDataUrl) console.log("Mini-program code: not configured; using the explicit placeholder");
   } else {
     console.log(`已生成网页：${outputFile}`);
@@ -116,7 +119,7 @@ async function main() {
     console.log(`本地历史：${persisted.receiptPath}`);
     console.log(`统计范围：${getReceiptCopy(options.locale).scope[record.source.scope]} · ${record.stats.session_count} 个会话`);
     console.log(`统计：${record.stats.completed_turns} 轮 · ${formatNumber(record.stats.tokens.total_tokens, options.locale)} Token · ${record.stats.tool_calls} 次工具调用`);
-    console.log(`数据二维码：${qrPayload.length} 字符 · schema v${record.schema_version}`);
+    console.log(`数据二维码：${qrPayloads.length} 个 · ${record.manifest.fact_count} 条规范事实 · schema v${record.schema_version}`);
     if (!miniProgramCodeDataUrl) console.log("小程序码：尚未配置，页面使用明确占位符");
   }
   if (options.open) openFile(outputFile);

package/src/core/barcode.mjs

@@ -0,0 +1,52 @@
+const CODE128_PATTERNS = [
+  "212222", "222122", "222221", "121223", "121322", "131222", "122213", "122312", "132212", "221213", "221312", "231212",
+  "112232", "122132", "122231", "113222", "123122", "123221", "223211", "221132", "221231", "213212", "223112", "312131",
+  "311222", "321122", "321221", "312212", "322112", "322211", "212123", "212321", "232121", "111323", "131123", "131321",
+  "112313", "132113", "132311", "211313", "231113", "231311", "112133", "112331", "132131", "113123", "113321", "133121",
+  "313121", "211331", "231131", "213113", "213311", "213131", "311123", "311321", "331121", "312113", "312311", "332111",
+  "314111", "221411", "431111", "111224", "111422", "121124", "121421", "141122", "141221", "112214", "112412", "122114",
+  "122411", "142112", "142211", "241211", "221114", "413111", "241112", "134111", "111242", "121142", "121241", "114212",
+  "124112", "124211", "411212", "421112", "421211", "212141", "214121", "412121", "111143", "111341", "131141", "114113",
+  "114311", "411113", "411311", "113141", "114131", "311141", "411131", "211412", "211214", "211232", "2331112",
+];
+
+const START_CODE_B = 104;
+const STOP_CODE = 106;
+
+function normalizeCode128Value(value) {
+  return [...String(value)]
+    .map((character) => {
+      const code = character.charCodeAt(0);
+      return code >= 32 && code <= 126 ? character : "?";
+    })
+    .join("")
+    .slice(0, 48) || "CWR";
+}
+
+export function buildCode128B(value) {
+  const normalized = normalizeCode128Value(value);
+  const dataCodes = [...normalized].map((character) => character.charCodeAt(0) - 32);
+  const checksum = dataCodes.reduce(
+    (total, code, index) => total + code * (index + 1),
+    START_CODE_B,
+  ) % 103;
+  const codes = [START_CODE_B, ...dataCodes, checksum, STOP_CODE];
+  const segments = [];
+
+  for (const code of codes) {
+    const pattern = CODE128_PATTERNS[code];
+    for (const [index, width] of [...pattern].entries()) {
+      segments.push({
+        isBar: index % 2 === 0,
+        width: Number(width),
+      });
+    }
+  }
+
+  return {
+    value: normalized,
+    checksum,
+    segments,
+    totalModules: segments.reduce((total, segment) => total + segment.width, 0),
+  };
+}

package/src/core/canonical.mjs

@@ -0,0 +1,27 @@
+import crypto from "node:crypto";
+
+function normalize(value) {
+  if (Array.isArray(value)) return value.map(normalize);
+  if (!value || typeof value !== "object") return value;
+
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, normalize(value[key])]),
+  );
+}
+
+export function canonicalStringify(value) {
+  return JSON.stringify(normalize(value));
+}
+
+export function sha256Hex(value) {
+  const input = Buffer.isBuffer(value) || value instanceof Uint8Array
+    ? value
+    : Buffer.from(typeof value === "string" ? value : canonicalStringify(value), "utf8");
+  return crypto.createHash("sha256").update(input).digest("hex");
+}
+
+export function stableId(prefix, domain, parts) {
+  return `${prefix}_${sha256Hex([domain, ...parts])}`;
+}

package/src/core/fact-buckets.mjs

@@ -0,0 +1,205 @@
+import { canonicalStringify, sha256Hex } from "./canonical.mjs";
+import {
+  ACCOUNTING_TIMEZONE,
+  buildFactId,
+  buildSessionId,
+  FACT_SCHEMA_VERSION,
+  METRIC_SCHEMA_VERSION,
+} from "./fact-identity.mjs";
+import { dateKey, rowDate } from "../lib/time.mjs";
+import { isCalendarScope, isDateInRange, shiftDateKey } from "./range.mjs";
+
+const TOKEN_KEYS = [
+  "input_tokens",
+  "cached_input_tokens",
+  "output_tokens",
+  "reasoning_output_tokens",
+  "total_tokens",
+];
+
+function zeroUsage() {
+  return Object.fromEntries(TOKEN_KEYS.map((key) => [key, 0]));
+}
+
+function tokenUsage(row) {
+  return row.type === "event_msg" && row.payload?.type === "token_count"
+    ? row.payload?.info?.total_token_usage || null
+    : null;
+}
+
+function tokenDeltaForDate(rows, localDate, timezone) {
+  const totals = zeroUsage();
+  const previous = zeroUsage();
+  let resetCount = 0;
+
+  for (const row of rows) {
+    const usage = tokenUsage(row);
+    const date = rowDate(row);
+    if (!usage || !date) continue;
+    const key = dateKey(date, timezone);
+    if (key > localDate) break;
+    let rowReset = false;
+
+    for (const tokenKey of TOKEN_KEYS) {
+      const current = Math.max(0, Number(usage[tokenKey] || 0));
+      if (key === localDate) {
+        if (current >= previous[tokenKey]) totals[tokenKey] += current - previous[tokenKey];
+        else {
+          totals[tokenKey] += current;
+          rowReset = true;
+        }
+      }
+      previous[tokenKey] = current;
+    }
+    if (key === localDate && rowReset) resetCount += 1;
+  }
+
+  return { totals, resetCount };
+}
+
+function metricsForRows(sessionRows, bucketRows, localDate, timezone) {
+  let completedTurns = 0;
+  let userMessages = 0;
+  let toolCalls = 0;
+  let interruptions = 0;
+  let workDurationMs = 0;
+  let firstTokenTotalMs = 0;
+  let firstTokenSampleCount = 0;
+  const models = new Set();
+
+  for (const row of bucketRows) {
+    if (row.type === "turn_context" && row.payload?.model) models.add(row.payload.model);
+    if (row.type === "event_msg") {
+      if (row.payload?.type === "task_complete") {
+        completedTurns += 1;
+        workDurationMs += Math.max(0, Number(row.payload.duration_ms || 0));
+        if (Number.isFinite(row.payload.time_to_first_token_ms)) {
+          firstTokenTotalMs += Math.max(0, Number(row.payload.time_to_first_token_ms));
+          firstTokenSampleCount += 1;
+        }
+      } else if (row.payload?.type === "user_message") userMessages += 1;
+      else if (row.payload?.type === "turn_aborted") {
+        interruptions += 1;
+        workDurationMs += Math.max(0, Number(row.payload.duration_ms || 0));
+      }
+    }
+    if (
+      row.type === "response_item" &&
+      (row.payload?.type === "custom_tool_call" || row.payload?.type === "function_call")
+    ) toolCalls += 1;
+  }
+
+  if (!models.size) {
+    const fallback = [...sessionRows]
+      .reverse()
+      .find((row) => row.type === "turn_context" && row.payload?.model)?.payload?.model;
+    if (fallback) models.add(fallback);
+  }
+
+  const tokenResult = tokenDeltaForDate(sessionRows, localDate, timezone);
+  return {
+    completed_turns: completedTurns,
+    user_messages: userMessages,
+    tool_calls: toolCalls,
+    interruptions,
+    work_duration_ms: Math.round(workDurationMs),
+    first_token_total_ms: Math.round(firstTokenTotalMs),
+    first_token_sample_count: firstTokenSampleCount,
+    ...tokenResult.totals,
+    token_reset_count: tokenResult.resetCount,
+    models: [...models].sort(),
+  };
+}
+
+function coverageForRange(range, scanMode, observedAt) {
+  if (!isCalendarScope(range.scope)) {
+    return {
+      kind: "selected_sessions",
+      scan_mode: "none",
+      start_date: range.startDate,
+      end_date: range.endDate,
+      complete_through_date: null,
+      observed_through_at: observedAt,
+    };
+  }
+
+  const full = scanMode === "full";
+  return {
+    kind: "calendar_range",
+    scan_mode: full ? "full" : "best_effort",
+    start_date: range.startDate,
+    end_date: range.endDate,
+    complete_through_date: full ? shiftDateKey(range.endDate, -1) : null,
+    observed_through_at: observedAt,
+  };
+}
+
+export function buildCanonicalFacts(sessions, range, options = {}) {
+  const sourceType = options.sourceType || "codex";
+  const accountingTimezone = options.accountingTimezone || ACCOUNTING_TIMEZONE;
+  const collectorVersion = options.collectorVersion || "0.6.0";
+  const observedAt = options.observedAt || new Date().toISOString();
+  const facts = [];
+
+  for (const session of sessions) {
+    const identityQuality = session.identityQuality || "metadata";
+    const sessionId = buildSessionId(sourceType, session.sessionId, identityQuality);
+    const sessionRows = [...session.rows].sort(
+      (left, right) => Number(left.__sourceLine || 0) - Number(right.__sourceLine || 0),
+    );
+    const buckets = new Map();
+
+    for (const row of sessionRows) {
+      const date = rowDate(row);
+      if (!date || (isCalendarScope(range.scope) && !isDateInRange(date, range))) continue;
+      const localDate = dateKey(date, accountingTimezone);
+      const rows = buckets.get(localDate) || [];
+      rows.push(row);
+      buckets.set(localDate, rows);
+    }
+
+    for (const [localDate, bucketRows] of buckets) {
+      const timestamps = bucketRows.map(rowDate).filter(Boolean).sort((left, right) => left - right);
+      if (!timestamps.length) continue;
+      const stats = metricsForRows(sessionRows, bucketRows, localDate, accountingTimezone);
+      const factId = buildFactId({ sourceType, sessionId, accountingTimezone, localDate });
+      const sourceRevision = session.sourceRevision || {
+        kind: "append-only-jsonl-v1",
+        row_count: sessionRows.length,
+        byte_length: 0,
+        tail_hash: sha256Hex(sessionRows.map((row) => row.__sourceLine || 0)),
+      };
+      const content = {
+        fact_id: factId,
+        session_id: sessionId,
+        source_type: sourceType,
+        accounting_timezone: accountingTimezone,
+        local_date: localDate,
+        bucket_start_at: timestamps[0].toISOString(),
+        bucket_end_at: timestamps.at(-1).toISOString(),
+        stats,
+      };
+
+      facts.push({
+        ...content,
+        identity_quality: identityQuality,
+        fact_schema_version: FACT_SCHEMA_VERSION,
+        metric_schema_version: METRIC_SCHEMA_VERSION,
+        collector_version: collectorVersion,
+        source_watermark_at: timestamps.at(-1).toISOString(),
+        source_revision: sourceRevision,
+        observed_at: observedAt,
+        content_hash: sha256Hex(canonicalStringify(content)),
+      });
+    }
+  }
+
+  facts.sort((left, right) => (
+    left.local_date.localeCompare(right.local_date) || left.fact_id.localeCompare(right.fact_id)
+  ));
+
+  return {
+    facts,
+    coverage: coverageForRange(range, sessions.scanMode || options.scanMode || "best_effort", observedAt),
+  };
+}

package/src/core/fact-identity.mjs

@@ -0,0 +1,39 @@
+import { stableId } from "./canonical.mjs";
+
+export const ACCOUNTING_TIMEZONE = "Asia/Shanghai";
+export const FACT_SCHEMA_VERSION = 1;
+export const METRIC_SCHEMA_VERSION = 1;
+
+export function buildSessionId(sourceType, rawSessionId, identityQuality = "metadata") {
+  return stableId("cws", "codex-work-receipt/session/v1", [
+    sourceType,
+    identityQuality,
+    rawSessionId,
+  ]);
+}
+
+export function buildFactId({ sourceType, sessionId, accountingTimezone, localDate }) {
+  return stableId("cwf", "codex-work-receipt/fact/session-day/v1", [
+    sourceType,
+    sessionId,
+    accountingTimezone,
+    localDate,
+  ]);
+}
+
+export function buildLogicalReceiptKey(metrics) {
+  const sessionPart = stableId("cwg", "codex-work-receipt/session-group/v1", [
+    ...[...metrics.sessionIds].sort(),
+  ]);
+  if (metrics.mode === "latest" || metrics.mode === "session") {
+    return `${metrics.mode}:${sessionPart}:${metrics.timezone}`;
+  }
+  if (metrics.mode === "this-week") {
+    return `this-week:${metrics.rangeStartDate}:${metrics.timezone}`;
+  }
+  return `${metrics.mode}:${metrics.rangeStartDate}:${metrics.rangeEndDate}:${metrics.timezone}`;
+}
+
+export function buildProtocolReceiptId(sourceVersion, logicalReceiptKey) {
+  return stableId("cwr2", "codex-work-receipt/receipt/v2", [sourceVersion, logicalReceiptKey]);
+}

package/src/core/metrics.mjs

@@ -12,14 +12,6 @@ function zeroUsage() {
   };
 }
 
-function subtractUsage(after = {}, before = {}) {
-  const result = zeroUsage();
-  for (const key of Object.keys(result)) {
-    result[key] = Math.max(0, Number(after[key] || 0) - Number(before[key] || 0));
-  }
-  return result;
-}
-
 function addUsage(target, source) {
   for (const key of Object.keys(target)) target[key] += Number(source[key] || 0);
 }
@@ -27,23 +19,25 @@ function addUsage(target, source) {
 function sessionTokenUsage(rows, range) {
   const events = rows
     .filter((row) => row.type === "event_msg" && row.payload?.type === "token_count")
-    .filter((row) => row.payload?.info?.total_token_usage)
-    .sort((left, right) => (rowDate(left)?.getTime() || 0) - (rowDate(right)?.getTime() || 0));
+    .filter((row) => row.payload?.info?.total_token_usage);
 
   if (!events.length) return zeroUsage();
-  if (!isCalendarScope(range.scope)) {
-    return { ...zeroUsage(), ...events.at(-1).payload.info.total_token_usage };
-  }
+  const totals = zeroUsage();
+  const previous = zeroUsage();
 
-  const lastInRange = events.filter((row) => isDateInRange(rowDate(row), range)).at(-1);
-  if (!lastInRange) return zeroUsage();
-
-  const baseline = events.filter((row) => {
+  for (const row of events) {
+    const currentUsage = row.payload.info.total_token_usage;
     const date = rowDate(row);
-    return date && dateKey(date, range.timezone) < range.startDate;
-  }).at(-1)?.payload.info.total_token_usage || zeroUsage();
+    const selected = !isCalendarScope(range.scope) || isDateInRange(date, range);
+
+    for (const key of Object.keys(totals)) {
+      const current = Math.max(0, Number(currentUsage[key] || 0));
+      if (selected) totals[key] += current >= previous[key] ? current - previous[key] : current;
+      previous[key] = current;
+    }
+  }
 
-  return subtractUsage(lastInRange.payload.info.total_token_usage, baseline);
+  return totals;
 }
 
 function calculateWorkPoints(metrics) {