@virjay/playscope-cocos 0.0.0-stage → 0.2.0

package/doc//344/275/277/347/224/250/346/214/207/345/215/227//347/244/272/344/276/213/project-fixture.json

@@ -0,0 +1,188 @@
+{
+  "project": {
+    "name": "Quest Garden source validation",
+    "profile": "game",
+    "gameSettings": {
+      "hasLevels": true,
+      "scoreOutcomes": [
+        "completed"
+      ]
+    },
+    "configSchema": {
+      "type": "object",
+      "properties": {
+        "schemaVersion": {
+          "const": 1
+        },
+        "revision": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "harvestTarget": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 20
+        },
+        "season": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        }
+      },
+      "required": [
+        "schemaVersion",
+        "revision",
+        "harvestTarget",
+        "season"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "eventSchemas": [
+    {
+      "name": "quest_started",
+      "version": 1,
+      "countsAsActivity": true,
+      "propertiesSchema": {
+        "type": "object",
+        "properties": {
+          "quest_id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256
+          },
+          "season": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256
+          }
+        },
+        "required": [
+          "quest_id",
+          "season"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "quest_harvested",
+      "version": 1,
+      "countsAsActivity": true,
+      "propertiesSchema": {
+        "type": "object",
+        "properties": {
+          "quest_id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256
+          },
+          "index": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 20
+          }
+        },
+        "required": [
+          "quest_id",
+          "index"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "quest_completed",
+      "version": 1,
+      "countsAsActivity": true,
+      "propertiesSchema": {
+        "type": "object",
+        "properties": {
+          "quest_id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256
+          },
+          "harvests": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 20
+          }
+        },
+        "required": [
+          "quest_id",
+          "harvests"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "quest_ad_income",
+      "version": 1,
+      "countsAsActivity": false,
+      "propertiesSchema": {
+        "type": "object",
+        "properties": {
+          "placement": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256
+          },
+          "exposure_id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256
+          },
+          "usd": {
+            "type": "number",
+            "minimum": 0
+          },
+          "provider": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256
+          },
+          "network": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256
+          },
+          "ad_unit": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256
+          },
+          "precision": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "placement",
+          "exposure_id",
+          "usd",
+          "provider",
+          "network",
+          "ad_unit",
+          "precision"
+        ],
+        "additionalProperties": false
+      }
+    }
+  ],
+  "configuration": {
+    "config": {
+      "schemaVersion": 1,
+      "revision": "garden-remote-1",
+      "harvestTarget": 2,
+      "season": "summer"
+    }
+  },
+  "rollout": {
+    "variants": [
+      {
+        "id": "default",
+        "revision": "garden-remote-1",
+        "weight": 100
+      }
+    ]
+  }
+}

package/doc//344/275/277/347/224/250/346/214/207/345/215/227//347/244/272/344/276/213/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": {
+      "@virjay/playscope-cocos": [
+        "../../../cocos/index.ts"
+      ],
+      "@virjay/playscope-cocos/adapters/levelplay": [
+        "../../../adapters/levelplay/index.ts"
+      ]
+    }
+  },
+  "include": [
+    "QuestGarden.ts",
+    "LevelPlayTelemetry.ts",
+    "CoreIntegration.ts"
+  ]
+}

package/examples/cocos-minimal/PlayScopeExample.ts

@@ -0,0 +1,27 @@
+import { _decorator, Component, sys, game, Game } from 'cc';
+import { init, type CocosPlayScope } from '@virjay/playscope-cocos';
+const { ccclass } = _decorator;
+/** One persistent owner. Replace placeholders with a dedicated test project's client settings. */
+@ccclass('PlayScopeExample')
+export class PlayScopeExample extends Component {
+  private telemetry: CocosPlayScope | null = null;
+  onLoad(): void {
+    this.telemetry = init({
+      baseUrl: 'https://analytics.example.com', projectId: 'YOUR_TEST_PROJECT_UUID', projectKey: 'YOUR_PROJECT_CLIENT_KEY',
+      collectionEnabled: true, // Replace with the host's collection decision.
+      client: { appVersion: '1.0.0', buildNumber: '1',
+        platform: sys.isNative ? sys.platform === sys.Platform.ANDROID ? 'android' : 'ios' : 'web',
+        locale: sys.language, timezoneOffsetMinutes: -new Date().getTimezoneOffset() },
+    }, {
+      storage: sys.localStorage,
+      lifecycle: {
+        onHide: callback => { game.on(Game.EVENT_HIDE, callback); return () => game.off(Game.EVENT_HIDE, callback); },
+        onShow: callback => { game.on(Game.EVENT_SHOW, callback); return () => game.off(Game.EVENT_SHOW, callback); },
+      },
+    });
+    this.telemetry.track('app_launch', { reason: 'launch' });
+    this.telemetry.track('session_start', {});
+  }
+  update(dt: number): void { this.telemetry?.update(dt); }
+  onDestroy(): void { this.telemetry?.dispose(); this.telemetry = null; }
+}

package/examples/quest-garden/QuestGarden.ts

@@ -0,0 +1,129 @@
+import { CocosPlayScope, telemetryUuid } from '@virjay/playscope-cocos';
+import type { CocosRuntime, ClientContext, AdRevenueFact, ConfigurationContext, FlushResult } from '@virjay/playscope-cocos';
+import { forwardLevelPlayRevenue } from '@virjay/playscope-cocos/adapters/levelplay';
+import type { LevelPlayExposure, LevelPlayImpression } from '@virjay/playscope-cocos/adapters/levelplay';
+
+export interface QuestConnection {
+  baseUrl: string;
+  projectId: string;
+  projectKey: string;
+  environment: 'production' | 'test';
+}
+interface Rules { schemaVersion: 1; revision: string; harvestTarget: number; season: string }
+interface Assignment { assignmentId: string; experimentId: string | null; variantId: string | null }
+interface Cache { config: Rules; assignment: Assignment }
+interface Attribution { configRevision: string; source: 'bundled' | 'cache' | 'remote';
+  assignmentId: string | null; experimentId: string | null; variantId: string | null }
+export interface QuestRun { runId: string; mode: 'garden-quest'; level: string; config: Attribution }
+export interface QuestExposure extends LevelPlayExposure { run: QuestRun | null }
+const BUNDLED: Rules = { schemaVersion: 1, revision: 'garden-bundled-1', harvestTarget: 3, season: 'spring' };
+function readCache(value: unknown): Cache | null {
+  const saved = value as Cache | null, rules = saved?.config, assignment = saved?.assignment;
+  if (!rules || rules.schemaVersion !== 1 || typeof rules.revision !== 'string' || !rules.revision ||
+    !Number.isSafeInteger(rules.harvestTarget) || rules.harvestTarget < 1 || rules.harvestTarget > 20 ||
+    typeof rules.season !== 'string' || !rules.season || !assignment || typeof assignment.assignmentId !== 'string' || !assignment.assignmentId ||
+    !(assignment.experimentId === null && assignment.variantId === null ||
+      typeof assignment.experimentId === 'string' && !!assignment.experimentId && typeof assignment.variantId === 'string' && !!assignment.variantId)) return null;
+  return { config: { schemaVersion: 1, revision: rules.revision, harvestTarget: rules.harvestTarget, season: rules.season },
+    assignment: { assignmentId: assignment.assignmentId, experimentId: assignment.experimentId, variantId: assignment.variantId } };
+}
+/** Example protocol owned by this game. Custom events must be registered in its own game project. */
+export function encodeQuestIncome(fact: Readonly<AdRevenueFact>) {
+  return { name: 'quest_ad_income', properties: { placement: fact.placement, exposure_id: fact.exposureId,
+    usd: fact.amount, provider: fact.provider, network: fact.network, ad_unit: fact.adUnitId, precision: fact.precision } };
+}
+
+/** Small independent host: gameplay and config application stay here; SDK only collects and delivers facts. */
+export class QuestGarden {
+  private readonly sdk: CocosPlayScope;
+  private readonly client: ClientContext;
+  private rules: Rules = { ...BUNDLED };
+  private attribution: Attribution = { configRevision: BUNDLED.revision, source: 'bundled',
+    assignmentId: null, experimentId: null, variantId: null };
+  private active: { run: QuestRun; rules: Rules; harvests: number; activeMs: number } | null = null;
+  private started = false;
+  private disposed = false;
+  private completed = 0;
+  constructor(connection: QuestConnection, runtime: CocosRuntime, collectionEnabled: boolean,
+    client: Omit<ClientContext, 'environment'>) {
+    const { environment, ...endpoint } = connection;
+    this.client = JSON.parse(JSON.stringify({ ...client, environment }));
+    this.sdk = new CocosPlayScope({ ...endpoint, client: this.client, collectionEnabled,
+      // Separate project IDs are also required for real test/production projects.
+      storageKey: `quest-garden:${environment}:${connection.projectId}`, persistence: 'segmented',
+      queuePolicy: { maxEvents: 64, maxBytes: 512 * 1024, eventLimits: { quest_harvested: 48 } },
+      adRevenueEncoder: encodeQuestIncome,
+      restoreCache: saved => {
+        const cache = readCache(saved);
+        if (cache) this.apply(cache, 'cache');
+        return cache;
+      },
+      resolveConfiguration: context => this.resolveConfig(context),
+    }, runtime);
+  }
+  start(): void {
+    if (this.disposed || this.started) return;
+    this.started = true; this.sdk.start(); this.sdk.track('app_launch', { reason: 'launch' });
+  }
+  beginQuest(questId: string): string | null {
+    if (this.disposed || this.active || !questId) return null;
+    const run: QuestRun = { runId: telemetryUuid(), mode: 'garden-quest', level: questId, config: { ...this.attribution } };
+    this.active = { run, rules: { ...this.rules }, harvests: 0, activeMs: 0 };
+    this.sdk.track('game_start', {}, { run });
+    this.sdk.track('quest_started', { quest_id: questId, season: this.rules.season }, { run });
+    return run.runId;
+  }
+  harvest(): boolean {
+    if (this.disposed || !this.active) return false;
+    const quest = this.active;
+    quest.harvests++;
+    this.sdk.track('quest_harvested', { quest_id: quest.run.level, index: quest.harvests }, { run: quest.run });
+    if (quest.harvests >= quest.rules.harvestTarget) {
+      this.completed++;
+      this.sdk.track('quest_completed', { quest_id: quest.run.level, harvests: quest.harvests }, { run: quest.run });
+      this.sdk.track('run_ended', { outcome: 'completed', summary: { score: quest.harvests, durationMs: quest.activeMs,
+        metrics: { harvests: quest.harvests } } }, { run: quest.run });
+      this.active = null;
+    }
+    return true;
+  }
+  captureExposure(exposureId: string, placement: string, format: 'banner' | 'rewarded', isTest: boolean): QuestExposure {
+    return { exposureId, placement, businessPlacement: placement, format, isTest,
+      run: this.active ? JSON.parse(JSON.stringify(this.active.run)) : null };
+  }
+  recordIncome(impression: LevelPlayImpression, exposure: QuestExposure): boolean {
+    if (this.disposed) return false;
+    const { run, ...fact } = exposure;
+    return forwardLevelPlayRevenue(this.sdk, impression, fact, { run });
+  }
+  update(dt: number, playing = true): void {
+    if (this.disposed) return;
+    if (playing && this.active && Number.isFinite(dt) && dt > 0 && dt <= 1) this.active.activeMs += dt * 1000;
+    this.sdk.update(dt);
+  }
+  get progress() { return { completed: this.completed, questId: this.active?.run.level ?? null,
+    harvests: this.active?.harvests ?? 0, target: this.active?.rules.harvestTarget ?? this.rules.harvestTarget }; }
+  get installId() { return this.sdk.installId; }
+  get status() { return this.sdk.status; }
+  get diagnostics() { return this.sdk.getDiagnostics(); }
+  flush(): Promise<FlushResult> { return this.sdk.flushWithResult(); }
+  refreshConfiguration() { return this.sdk.refreshConfiguration(); }
+  dispose(): void { if (!this.disposed) { this.disposed = true; this.sdk.dispose(); } }
+  private apply(cache: Cache, source: 'cache' | 'remote'): void {
+    this.rules = cache.config;
+    this.attribution = { configRevision: cache.config.revision, source, ...cache.assignment };
+  }
+  private async resolveConfig(context: ConfigurationContext): Promise<number> {
+    const previous = readCache(context.cache);
+    const response = await context.request('/config/resolve', { apiVersion: 1, installId: this.installId,
+      client: this.client, supportedSchemas: [1], current: previous ? { revision: previous.config.revision, assignmentId: previous.assignment.assignmentId } : null }) as {
+        apiVersion: number; delivery: string; config: unknown; configRevision: string; assignment: unknown; refreshAfterSeconds: number };
+    if (this.disposed) return 3600;
+    const cache = readCache({ config: response?.delivery === 'full' ? response.config :
+      response?.delivery === 'not_modified' ? previous?.config : null, assignment: response?.assignment });
+    if (response?.apiVersion !== 1 || !cache || cache.config.revision !== response.configRevision) throw new Error('invalid_quest_config');
+    context.saveCache(cache); this.apply(cache, 'remote');
+    this.sdk.track('config_received', { revision: cache.config.revision });
+    return response.refreshAfterSeconds;
+  }
+}

package/examples/quest-garden/README.md

@@ -0,0 +1,180 @@
+# Quest Garden 独立接入示例（0.2.0）
+
+这是第二款游戏的 TypeScript 宿主示例，用独立任务、事件字典、配置 schema 和广告位验证
+SDK 复用。它只从 `@virjay/playscope-cocos` 和 `@virjay/playscope-cocos/adapters/levelplay` 公共入口导入，
+不引用 BlockDrop，也不访问 SDK 内部状态。这些接口包含在 @virjay/playscope-cocos 0.2.0 中；旧 @playscope/cocos 0.1.1 包不支持。
+示例没有 Creator 场景、画面或游戏存档，不能视为已交付的第二款游戏。
+
+## 接入与所有权
+
+```ts
+import { QuestGarden } from './QuestGarden';
+
+// runtime 由宿主提供 CocosRuntime：storage、transport、生命周期和时钟。
+const game = new QuestGarden({
+  baseUrl: 'https://analytics.example.com',
+  projectId: '单独创建的测试项目 UUID',
+  projectKey: '该项目客户端 Key',
+  environment: 'test',
+}, runtime, collectionAllowed, {
+  appVersion: '1.0.0', buildNumber: '1', platform: 'android',
+  locale: 'zh-CN', timezoneOffsetMinutes: -new Date().getTimezoneOffset(),
+});
+game.start();
+game.beginQuest('orchard-1');
+game.update(0.5, true); // 宿主每帧调用；暂停时 playing=false
+game.harvest();
+// 场景／常驻宿主释放时：
+game.dispose();
+```
+
+宿主持有采集授权、玩法、对局、活跃计时、配置校验和原生曝光；SDK 持有身份、鉴权、
+持久 Outbox、ACK 和重试。每次任务冻结其规则和归因；后台 flush 不产生任务失败或结束。
+玩法进度只在内存中，重启恢复 SDK 待传事实不代表恢复活跃任务。
+
+示例显式启用分段存储，需要支持严格 removeItem 的 localStorage。总预算为 64 条 / 512 KiB，
+quest_harvested 在队列长度 48 时拒绝新增，为其他事件预留 16 条；不驱逐旧事实。
+storageKey 为 `quest-garden:<environment>:<projectId>`；测试与正式还应各用独立项目 ID。
+相同键切换服务器会触发 scope_mismatch，不能通过清空状态修复。
+
+collectionAllowed=false 时 SDK 不访问存储、网络或注册监听，任务仍可完成。授权变化时先
+dispose，再用新的许可重建宿主。已落盘身份与队列保留，重新授权后可继续交付；关闭采集
+期间的玩法不会补报。dispose 后旧回调不能再上传，但已到达服务器的请求无法撤回。
+
+## 独立项目契约
+
+[project-fixture.json](project-fixture.json) 是离线、可审阅的配置材料，不会创建外部项目。
+需要真实服务验收时，在隔离测试环境按当前管理 API 分别完成：
+
+1. 按 project 部分创建 game 项目，设置 hasLevels、scoreOutcomes 和独立 configSchema；
+   保存返回的项目 ID 和客户端 Key，管理 Token 不能放入游戏。
+2. 为该项目注册 eventSchemas 中四个 version 1 自定义事件及其 propertiesSchema、活动标记。
+3. 发布 configuration.config，再按 rollout 的版本权重建立发布规则；Web 宿主另登记 Origin。
+4. 将返回凭据传给宿主，使用独立测试项目验收，正式项目单独配置。
+
+内置事件为 user_first_open、app_launch、game_start、run_ended 和 config_received；
+自定义事件为 quest_started、quest_harvested、quest_completed 和 quest_ad_income。
+任务结算使用 outcome=completed，summary 中记录 score、durationMs 和 harvests。
+配置只包含 schemaVersion=1、revision、harvestTarget 和 season，宿主发送 supportedSchemas=[1]，
+验证完整配置与 assignment、先保存后应用，当前任务继续使用开局快照。
+
+收入转发先 captureExposure，再将原曝光传给 recordIncome；每次横幅刷新使用新 exposureId，
+isTest 显式传入，迟到收入保留原任务。示例业务位为 potion_cart_banner 等宿主字符串。
+encodeQuestIncome 将通用收入编码为自定义 quest_ad_income（usd、exposure_id 等字段），
+它是项目事件数据，**不会自动映射标准广告收入看板**。合法零收入、逆序回调及重启去重均有验证。
+真实 LevelPlay 展示、曝光关联和发奖仍需游戏的原生桥接实现。
+
+## 只验证源码，不生成 dist
+
+在 sdk 目录使用已有依赖：
+
+```sh
+npm run check
+npm run check:quest-example
+npm run test:source
+```
+
+示例 tsconfig 和测试专用加载器把公共包路径映射到当前源码，不更换游戏固定依赖。
+9 项示例测试覆盖任务完成、离线重启、丢 ACK、部分 ACK、测试／正式隔离、采集关闭、
+生命周期释放、独立收入编码和配置归因。离线重启比较持久段中的原事实与最终上传原文。
+其中两项使用 127.0.0.1 随机端口 HTTP 服务，丢 ACK 测试在记录事实后断开 socket。
+
+该服务是测试协议实现，使用内存 Map 幂等记录和字典校验；它不是 Go PlayScope 服务，
+不证明真实数据库持久提交。这里也没有 Creator 构建、打包入口、原生广告或真机验收。
+
+## 可选真实服务验证（复用已有程序）
+
+在 sdk 目录执行，参数必须是已经存在的 PlayScope 可执行文件；命令不构建或安装依赖：
+
+```sh
+npm run verify:quest-local -- /absolute/path/to/existing/playscope
+```
+
+脚本只在 sdk/artifacts 下新建临时目录，启动绑定 127.0.0.1 随机端口的真实 Go 服务及全新
+SQLite 数据库。它不接受外部服务 URL、不加载 .env；子进程环境显式指定测试数据库、
+临时管理员和关闭更新。真实管理 API 创建两个独立项目、注册字典并发布配置，随后源码
+示例完成离线文件恢复、配置 full / not_modified、任务与收入上报、丢 ACK／部分 ACK 重放、
+项目 Token 隔离及错误字典拒收。数据库在同一文件上经过两次服务重启，事件原文再次核对。
+
+丢 ACK 是真实提交响应返回后由 transport 抛错；部分 ACK 是 transport 隐藏已接收 ID，
+真实服务实际已接收全批。这样验证客户端在确认不完整时如何重放，不代表服务端有随机
+丢包或只提交了一部分。localStorage 测试端同步写临时文件并 fsync / rename，宿主重新构造
+时重新从文件读取；没有启动独立的游戏操作系统进程，也没有检验断电存储保证。
+
+正常完成或校验抛错时停止临时服务并删除数据库／客户端状态，只保留无凭据的
+`artifacts/quest-local-verification.json`。报告包含服务版本和二进制 SHA-256，不能将旧程序
+通过理解为当前 Go 工作区重新编译通过。此工具与普通 test:source 分开，需要本机可执行程序。
+
+2026-11-11 使用已有 0.1.20 程序验证通过：两个项目共 26 条不可变事件、8 份项目自定义 schema、
+1 次丢 ACK、1 次部分 ACK、2 条错误数据永久拒收；重启后数量和原文保持一致。
+仍未进行 Creator、包入口、真实广告 SDK 或设备验收。
+
+## 可选独立进程崩溃恢复
+
+同一入口增加标记，在原验证之外创建第三个临时项目，并启动三个独立 Node 游戏宿主进程：
+
+```sh
+npm run verify:quest-local -- /absolute/path/to/existing/playscope --process-restart
+```
+
+第一个进程离线写入五条事实后等待，父进程确认文件已落盘，再用 SIGKILL 终止它。
+第二个进程恢复原身份和队列，真实服务提交后，transport 暂不把 ACK 交给 SDK；父进程
+查询真实入库、确认本地五条事实仍待传，再次 SIGKILL。两次均不执行 SDK dispose。
+服务另重启一次后，第三个进程恢复同一文件和 Token，按原 eventId／原文重放并完成一项新任务。
+父进程比较三个不同 PID、完整事件、安装身份、首次时间和首次标记；旧任务不会被补造结束。
+
+工作进程通过本机 IPC 接收临时连接参数，命令行和报告不包含凭据；每个进程单独加载 SDK
+源码。父进程为工作进程设置 30 秒上限，校验失败也会终止它们，之后清理临时状态和数据库。
+报告单独保存为 `artifacts/quest-process-verification.json`，不覆盖不带标记的默认报告。
+
+2026-11-11：新增项目 13 条事件，初始五条事实逐字重放，首次事件仅一次，最终待传为零，
+新任务成功完成且没有旧任务结束事件。包含原验证在内合计三个项目、39 条事件。
+该验证覆盖操作系统进程被杀，不包含设备断电、写入中途磁盘故障、Creator 或原生广告验收。
+
+## 可选分段写入中断验证
+
+增加 --storage-crash 可单独检查分段持久化的提交边界，也可与进程重启验证一起运行：
+
+```sh
+npm run verify:quest-local -- /absolute/path/to/existing/playscope --process-restart --storage-crash
+```
+
+新增项目先离线保存五条事实。写入下一条时，工作进程在新数据段完成写入、根索引尚未
+更新的位置同步暂停；父进程核对旧根仍引用原五条事实，再 SIGKILL。另一个进程恢复后
+保留原队列、清理未提交段。被中断的 track 尚未返回，其候选事件不算已接收事实。
+
+随后真实服务接收原五条事件，工作进程在 ACK 后的空队列索引已写入、旧段尚未删除时
+再次同步暂停并被 SIGKILL。恢复进程先清理旧段和日志，空队列 flush 不重传原事实，
+再通过一个新任务的七条事件验证可以继续写入和上传。原身份／首次标记、其他存储键均保留。
+
+检查点通过同步写入的临时文件向父进程公开；工作进程此时阻塞在 setItem 内，不依赖
+事件循环处理 IPC。进程管理复用同一测试工具，30 秒超时并在失败路径清理。
+启用此选项时报告写入 `artifacts/quest-storage-crash-verification.json`，不覆盖前两种报告。
+
+2026-11-12 合并验证通过：本场景五个游戏进程、两次 SIGKILL，新增项目 12 条事件；
+连同原验证及 --process-restart 共四个项目、51 条事件。测试端仍保证单键完整替换，
+该结果只证明跨多个键的 SDK 提交流程恢复，不证明半个文件写入、断电或真实 JSB 存储行为。
+
+## 可选旧快照迁移中断验证
+
+```sh
+npm run verify:quest-local -- /absolute/path/to/existing/playscope --migration-crash
+```
+
+此标记在默认验证外创建两个临时项目，分别放入无版本和 v1 合成快照：各有 40 条待传
+历史事件，v1 另有一条大隔离记录。它不是实际旧版本游戏进程或生产快照导入。
+迁移宿主通过 SDK 源码公开类验证存储，保留原键，显式声明已知的 legacyScope；
+SDK 不从 Token 自动推断旧来源。示例玩法和生产固定依赖保持不变。
+
+每种格式分别在第一段写完、旧根仍完整时 SIGKILL，再在完整 v2 根写完、日志尚未清理时
+SIGKILL。第三个进程恢复并检查旧事实、缓存、Token、序号、去重、首次标记及隔离记录，
+拒绝一个已存在去重键，再上传原 40 条和一条新事实。真实服务正常重启后再次逐条核对。
+两条历史 provider=max 的合法零收入按原字段入库，不启用 MAX 广告 SDK 或改写收入编码。
+
+2026-11-12：六个独立迁移进程、四次 SIGKILL、两次额外服务重启通过；新增两个项目
+共 82 条唯一事件，连同默认验证为四个项目／108 条事件。原事件 ID 和完整原文、
+Token、缓存及元数据保留，没有额外首次事件或孤立段，大隔离记录继续保留且不上传。
+
+结果写入 `artifacts/quest-migration-crash-verification.json`，不覆盖其他模式报告。
+标记可与前两种合用；报告数量以实际启用项为准。测试仍要求单键原子替换，不覆盖断电、
+半份文件、真实 JSB／Creator 或生产升级验收。