codex-work-receipt 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 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
+
+- 新增网页版“保存完整长图”功能。
+- 高清 PNG 包含主小票、小程序码和数据二维码导入联。
+- 导出图片自动使用当前主题，并排除主题按钮、网页背景和其他页面元素。
+- 网页主题与小程序统一为经典白票、复古粉票和夜班绿票。
+- 小票顶部明确展示统计日期范围，默认文件名同步携带日期范围或会话短编号。
+- 图片在浏览器本地渲染，不上传小票数据。
+
 ## 0.4.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.
+
 ## 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:
@@ -36,7 +38,7 @@ Summarize all Codex activity from today:
 npx codex-work-receipt@latest --today --lang en
 ```
 
-HTML and structured data are written to `./codex-work-receipt-output/` by default. Non-interactive options such as `--latest` and `--today` remain available; see the [CLI guide](docs/cli.en.md).
+HTML and structured data are written to `./codex-work-receipt-output/` by default. The generated page can save a high-resolution PNG containing the full receipt and QR import stub. Non-interactive options such as `--latest` and `--today` remain available; see the [CLI guide](docs/cli.en.md).
 
 ## Ask Codex directly
 
@@ -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
 
@@ -70,12 +72,12 @@ The desktop page generates a privacy-safe data QR code. The companion WeChat min
 <p align="center">
   <a href="https://modelflare.dev/"><img src="docs/images/sponsors/modelflare-logo.png" alt="ModelFlare Logo" width="56"></a><br>
   <a href="https://modelflare.dev/"><strong>ModelFlare</strong></a> · <a href="https://modelflare.dev/">modelflare.dev</a><br>
-  <sub>Stable access to leading AI model APIs at a very low cost, with transparent pricing and clear usage.</sub>
+  <sub>Helping independent developers access leading AI model APIs reliably and at a very low cost, so they can quickly build their own products with advanced model capabilities.</sub>
 </p>
 
 ## License
 
-The desktop source is licensed under [GNU GPL v3](LICENSE) (`GPL-3.0-only`). This repository does not contain the companion mini-program or backend source code. This is an unofficial community project and is not affiliated with OpenAI.
+The desktop source is licensed under [GNU GPL v3](LICENSE) (`GPL-3.0-only`). This is an unofficial community project and is not affiliated with OpenAI.
 
 ---
 

package/README.md

@@ -22,6 +22,8 @@
 
 它会统计 Codex 会话中的轮次、工具调用、Token、时长和模型，生成带有 AI 工分、今日工种和点评的小票。不会把 Prompt、回复正文、代码、项目路径或文件名写入小票。
 
+`0.6.0` 使用 cwr2 协议，按“会话 × 自然日”生成稳定的脱敏事实。今日、近 7 日和本周小票即使范围重叠，接收端也能识别相同工作；数据过大时会自动生成多张可重组的分片二维码。
+
 ## Quickstart
 
 需要 Node.js 20 或更高版本，并且本机已经使用过 Codex。无需克隆仓库，运行后选择“今天 / 近 7 日 / 本周 / 指定会话”：
@@ -36,7 +38,7 @@ npx codex-work-receipt@latest
 npx codex-work-receipt@latest --today
 ```
 
-网页和结构数据默认保存在 `./codex-work-receipt-output/`。也可以继续使用 `--latest`、`--today` 等非交互参数，详见 [CLI 使用文档](docs/cli.md)。
+网页和结构数据默认保存在 `./codex-work-receipt-output/`。生成的网页支持一键保存包含主小票和二维码导入联的高清长图。也可以继续使用 `--latest`、`--today` 等非交互参数，详见 [CLI 使用文档](docs/cli.md)。
 
 ## 直接跟 Codex 说
 
@@ -54,7 +56,7 @@ Codex 会选择统计范围和主题、执行命令并打开小票。详见 [Cod
 
 ## 从电脑到手机
 
-桌面网页会生成脱敏的数据二维码。配套微信小程序支持扫码导入、本地历史、主题切换和保存图片。详见 [手机扫码导入](docs/mobile-import.md)。
+桌面网页会生成一张或多张脱敏数据二维码。配套微信小程序支持分片扫码、私人历史、主题切换和保存图片。详见 [手机扫码导入](docs/mobile-import.md)。
 
 ## 文档
 
@@ -70,12 +72,12 @@ Codex 会选择统计范围和主题、执行命令并打开小票。详见 [Cod
 <p align="center">
   <a href="https://modelflare.dev/"><img src="docs/images/sponsors/modelflare-logo.png" alt="ModelFlare Logo" width="56"></a><br>
   <a href="https://modelflare.dev/"><strong>ModelFlare</strong></a> · <a href="https://modelflare.dev/">modelflare.dev</a><br>
-  <sub>以很低的成本稳定接入前沿 AI 模型 API，价格友好、计费透明、用量清晰可见。</sub>
+  <sub>让个人开发者也可以以很低的成本、稳定地接入前沿 AI 模型的 API，借助模型能力快速构建自己的产品。</sub>
 </p>
 
 ## License
 
-电脑端源码采用 [GNU GPL v3](LICENSE)（`GPL-3.0-only`）。本仓库不包含配套小程序和后台服务源码；本项目是非 OpenAI 官方社区工具。
+电脑端源码采用 [GNU GPL v3](LICENSE)（`GPL-3.0-only`）。本项目是非 OpenAI 官方社区工具。
 
 ---
 

package/docs/cli.en.md

@@ -73,10 +73,14 @@ Default output:
 
 ```text
 ./codex-work-receipt-output/
-├── codex-receipt-latest.html
-└── codex-receipt-latest.json
+├── codex-receipt-today-2026-07-18.html
+└── codex-receipt-today-2026-07-18.json
 ```
 
+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. When cwr2 data exceeds the safe capacity of one QR code, the import stub automatically shows numbered multipart codes that must all be scanned in the mini program.
+
 Set a timezone and output path:
 
 ```bash
@@ -130,4 +134,4 @@ See the [data schema and QR protocol](data-schema.en.md).
 - Codex is the only supported data source; Cursor and WorkBuddy are planned
 - Changed-file and line counts are intentionally omitted until they can be measured consistently
 - Calendar ranges filter individual events by local date and calculate a Token delta for each session
-- Image export is handled by the companion mini program rather than the desktop page
+- Desktop PNG export is rendered locally in the browser and does not upload receipt data

package/docs/cli.md

@@ -73,10 +73,14 @@ npx codex-work-receipt@latest --latest --theme diner
 
 ```text
 ./codex-work-receipt-output/
-├── codex-receipt-latest.html
-└── codex-receipt-latest.json
+├── codex-receipt-today-2026-07-18.html
+└── codex-receipt-today-2026-07-18.json
 ```
 
+默认文件名会携带统计日期范围；最近会话和指定会话则携带短编号，避免不同日期或会话的小票互相覆盖。
+
+打开生成的 HTML 后，点击“保存完整长图”即可下载高清 PNG。图片包含主小票、小程序码和数据二维码导入联，并自动使用当前选择的主题；主题按钮、网页背景和底部说明不会进入图片。cwr2 数据超过单个二维码的安全容量时，导入联会自动展示多张带序号的分片二维码，需在小程序中全部扫完。
+
 指定时区和输出路径：
 
 ```bash
@@ -130,4 +134,4 @@ npx codex-work-receipt@latest --help
 - 当前只支持 Codex；Cursor、WorkBuddy 等数据源仍在规划中
 - 暂不统计修改文件数和代码行数，避免不同工具调用方式产生误导
 - 时间范围按每条事件的本地日期筛选，并分别计算每个会话的 Token 区间增量
-- 网页端不直接导出图片，移动端渲染和保存由配套小程序完成
+- 桌面网页导出 PNG 使用浏览器本地渲染，不上传小票数据

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.
+4. Validate the `cwr1`, `cwr2`, or multipart `cwr2p` 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.
+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 和结构版本。
+4. 小程序校验 `cwr1`、`cwr2` 或 `cwr2p` 分片前缀、checksum 和结构版本。
 5. 解压并解析脱敏统计数据。
-6. 识别单会话、今日、近七日或本周范围，并按小票 ID 去重写入本地历史。
+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.4.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Generate a privacy-first Codex work receipt from local session metadata.",
   "author": "a-bai-2026",
@@ -52,6 +52,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "dom-to-image-more": "^3.10.2",
     "qrcode": "^1.5.4"
   }
 }

package/src/cli.mjs

@@ -7,10 +7,11 @@ 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 { outputSlugForScope, resolveRange } from "./core/range.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";
 import { installCodexSkill } from "./core/skill-installer.mjs";
@@ -77,18 +78,20 @@ 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,
-    `codex-receipt-${outputSlugForScope(options.mode)}.html`,
+    `codex-receipt-${outputSlugForRange(range, record.id)}.html`,
   );
   const outputFile = path.resolve(/\.html?$/i.test(requestedOutput) ? requestedOutput : `${requestedOutput}.html`);
   fs.mkdirSync(path.dirname(outputFile), { recursive: true });
@@ -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/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) {