@seasonkoh/webaz 0.1.24 → 0.1.26

package/dist/pwa/server.js

@@ -20,6 +20,7 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import crypto from 'crypto';
 import { initDatabase, generateId } from '../layer0-foundation/L0-1-database/schema.js';
+import { setSeamDb } from '../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
 import { initSystemUser, transition, getOrderStatus, checkTimeouts, settleFault } from '../layer0-foundation/L0-2-state-machine/engine.js';
 import { endpointToAction, endpointToReadAction } from './endpoint-actions.js';
 import { AGENT_RATE_PER_MIN_DEFAULTS, CROSS_USER_READ_DAILY_CAP, MASS_ACTION_TYPES, MASS_ACTION_DAILY_CAPS } from './limits.js';
@@ -46,8 +47,10 @@ import { createPublicClient, createWalletClient, http, parseAbiItem, parseAbi, p
 import { baseSepolia, base } from 'viem/chains';
 import { createHmac, createHash, randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
 import { safeFetch } from './security/ssrf.js';
+import { deliverVerificationCode, emailDeliveryNotConfigured, isVerificationEmailReady, } from './email-delivery.js';
 // @simplewebauthn/server 已迁出到 src/pwa/routes/webauthn.ts (#1013 Phase 1)
 import { registerWebauthnRoutes } from './routes/webauthn.js';
+import { createHumanPresence } from './human-presence.js';
 // welcome 域（#991 /welcome 落地页 + #1005 反 bot）已迁出 (#1013 Phase 2)
 import { registerWelcomeRoutes } from './routes/welcome.js';
 // 测评免单 (#978-#988) 域 + 评估 cron 已迁出 (#1013 Phase 3)
@@ -168,6 +171,7 @@ import { registerListingsRoutes } from './routes/listings.js';
 import { registerEvidenceRoutes } from './routes/evidence.js';
 // 分享 / 重定向 / QR (#1013 Phase 54) — 4 endpoints
 import { registerShareRedirectsRoutes } from './routes/share-redirects.js';
+import { registerShopReferralRoutes } from './routes/shop-referral.js';
 // Profile 凭据 (#1013 Phase 55) — 5 endpoints (密码 + 邮箱绑定)
 import { registerProfileCredentialsRoutes } from './routes/profile-credentials.js';
 // Profile 双轨挂靠 (#1013 Phase 56) — 3 endpoints
@@ -198,6 +202,7 @@ import { registerAdminEventsRoutes } from './routes/admin-events.js';
 import { registerAdminModerationRoutes } from './routes/admin-moderation.js';
 // Admin 钱包运维 (#1013 Phase 69) — hot-wallet 2 + withdrawals 2 = 4 endpoints
 import { registerAdminWalletOpsRoutes } from './routes/admin-wallet-ops.js';
+import { resolveBearerProtocolAdmin } from './admin-bearer-auth.js';
 // Admin Catalog (#1013 Phase 70) — categories 2 + products 2 = 4 endpoints
 import { registerAdminCatalogRoutes } from './routes/admin-catalog.js';
 // Reputation 公开查询 (#1013 Phase 71) — 2 endpoints
@@ -303,9 +308,21 @@ import { registerAuthRegisterRoutes } from './routes/auth-register.js';
 import { registerBuildFeedbackRoutes } from './routes/build-feedback.js';
 import { initBuildFeedbackSchema } from '../layer2-business/L2-8-feedback/build-feedback-engine.js';
 import { registerBuildTasksRoutes } from './routes/build-tasks.js';
+import { registerPublicBuildTasksRoutes } from './routes/public-build-tasks.js';
 import { initBuildTasksSchema } from '../layer2-business/L2-9-contribution/build-tasks-engine.js';
+import { initBuildTaskAgentMetadataSchema } from '../layer2-business/L2-9-contribution/build-task-agent-metadata-store.js';
+import { initTaskProposalSchema } from '../layer2-business/L2-9-contribution/task-proposal-store.js';
+import { initTaskProposalAiSchema } from '../layer2-business/L2-9-contribution/task-proposal-ai-store.js';
+import { initTaskProposalDraftLinkSchema } from '../layer2-business/L2-9-contribution/task-proposal-draft.js';
+import { registerTaskProposalsRoutes } from './routes/task-proposals.js';
+import { createSlidingWindowLimiter } from './rate-limit.js';
 import { registerBuildReputationRoutes } from './routes/build-reputation.js';
 import { initBuildReputationSchema } from '../layer2-business/L2-9-contribution/build-reputation-engine.js';
+import { initGithubCredentialStoreSchema } from '../layer2-business/L2-9-contribution/github-credential-store.js';
+import { initIdentityBindingSchema } from '../layer2-business/L2-9-contribution/identity-binding-store.js';
+import { initIdentityClaimChallengeSchema } from '../layer2-business/L2-9-contribution/identity-claim-challenge-store.js';
+import { registerContributionIdentityRoutes } from './routes/contribution-identity.js';
+import { registerContributionScoreRoutes } from './routes/contribution-score.js';
 const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
 // ─── 链上地址派生 ──────────────────────────────────────────────
 const MASTER_SEED = process.env.WALLET_MASTER_SEED ?? 'webaz-dev-seed-changeme';
@@ -344,6 +361,7 @@ function deriveDepositAddress(userId) {
 }
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const db = initDatabase();
+setSeamDb(db); // RFC-016 Phase 0:注入异步 DB seam(本进程)
 // #1013 Phase 9: claim-verify helpers 预绑 db（routes/claim-verify.ts 已 export 多签名版本）
 // 让 product-claims / review-claims / etc 跨域调用零侵入（无需改 callsite signature）
 const isEligibleClaimVerifier = (userId) => isEligibleClaimVerifierRaw(db, userId);
@@ -359,7 +377,14 @@ initReputationSchema(db);
 initOrderChainSchema(db);
 initBuildFeedbackSchema(db); // RFC-004 build_feedback
 initBuildTasksSchema(db); // RFC-006 build_tasks(协调层)
+initBuildTaskAgentMetadataSchema(db); // PR9B — agent-ready task metadata satellite(schema only;FUTURE-TASK-BOARD-V1-DESIGN #326)
+initTaskProposalSchema(db); // Task Proposal Inbox v1 — suggestion inbox(maintainer review;never auto build_task)
+initTaskProposalAiSchema(db); // Task Proposal AI-assist — assistant-only recommendation/evidence(human decides)
+initTaskProposalDraftLinkSchema(db); // Task Proposal draft links — source proposal ↔ draft task(converted at publish)
 initBuildReputationSchema(db); // RFC-006 build_reputation(独立池 + 贡献者看板)
+initGithubCredentialStoreSchema(db); // PR 3B-3a — GitHub credential store + RFC-017 fact layer (schema only)
+initIdentityBindingSchema(db); // PR 4a — GitHub identity → WebAZ account binding (append-only events + active projection)
+initIdentityClaimChallengeSchema(db); // PR-F1 — identity-claim publication-challenge state (server-side nonce hash; schema only)
 initSnfSchema(db);
 initExternalAnchorSchema(db);
 // 启动时检查月衰减（last_decay_at ≥25 天才触发，重启幂等）
@@ -629,6 +654,53 @@ try {
     db.exec('CREATE INDEX IF NOT EXISTS idx_psa_recipient ON product_share_attribution(recipient_id, product_id)');
 }
 catch { }
+// provenance (additive, audit-only — does NOT change commission math): how this attribution was created.
+//   source_type = 'direct_share'(商品/笔记直接分享) | 'shop_referral_verified_purchase'(店铺推荐懒升级)
+try {
+    db.exec("ALTER TABLE product_share_attribution ADD COLUMN source_type TEXT");
+}
+catch { }
+try {
+    db.exec("ALTER TABLE product_share_attribution ADD COLUMN source_ref TEXT");
+}
+catch { }
+try {
+    db.exec("ALTER TABLE product_share_attribution ADD COLUMN source_shop_seller_id TEXT");
+}
+catch { }
+try {
+    db.exec("ALTER TABLE product_share_attribution ADD COLUMN source_qualified_order_id TEXT");
+}
+catch { }
+// ─── 店铺推荐锚定 (shop_referral_attribution) ─────────────────
+// 店铺推荐【只】锚定推荐关系 + 二叉树位置 + 店铺来源,first-touch 30 天锁;它【不是】全店佣金权。
+// 仅当被推荐人后来真实下单店铺里的某商品、且推荐人自己也 completed 买过同款时,才在下单时被【懒升级】
+// 为该商品的 product_share_attribution(见 orders-create maybePromoteShopReferralToProductAttribution)。
+db.exec(`
+  CREATE TABLE IF NOT EXISTS shop_referral_attribution (
+    seller_id     TEXT NOT NULL,
+    recipient_id  TEXT NOT NULL,
+    referrer_id   TEXT NOT NULL,
+    ref_code      TEXT NOT NULL,
+    side          TEXT,
+    created_at    TEXT DEFAULT (datetime('now')),
+    expires_at    TEXT NOT NULL,
+    source        TEXT DEFAULT 'shop_referral',
+    PRIMARY KEY (seller_id, recipient_id)
+  )
+`);
+try {
+    db.exec('CREATE INDEX IF NOT EXISTS idx_sra_referrer ON shop_referral_attribution(referrer_id, seller_id)');
+}
+catch { }
+try {
+    db.exec('CREATE INDEX IF NOT EXISTS idx_sra_recipient ON shop_referral_attribution(recipient_id)');
+}
+catch { }
+try {
+    db.exec('CREATE INDEX IF NOT EXISTS idx_sra_expires ON shop_referral_attribution(expires_at)');
+}
+catch { }
 // 商品分享链反推：buyer 买商品 P 时 → L1=谁分享 P 给 buyer → L2=谁分享 P 给 L1 → ...
 // 与 sponsor_path / placement_path 完全无关。某层断链 → 该层 null（佣金回流协议池）。
 function getProductShareChain(productId, buyerId, depth = 3) {
@@ -792,7 +864,9 @@ const DEFAULT_PARAMS = [
     // RFC-008:fund_base 硬帽 1%;pre-launch 减免到 0(社区基金按真实 GMV 注入,0 GMV 时是无回报的税)。有真实 GMV 再由治理开启(≤1%)。
     { key: 'fund_base_rate', value: '0', type: 'number', description: '协议基金池基础费率（RFC-008 硬帽 1%;pre-launch 减免=0,有真实 GMV 再由治理开启 ≤1%）', category: 'fee', min: 0, max: 0.01 },
     // RFC-008:起步免赔付门槛。0 = bootstrap(新商家零质押、违约免赔付只退款+掉信誉,降进入门槛);1 = 要求卖家质押(下单锁 stake、违约真没收)。上轨道后由治理开启。
-    { key: 'require_seller_stake', value: '0', type: 'number', description: 'RFC-008 是否要求卖家质押(0=起步免赔付/零门槛,1=要求质押/真没收)', category: 'fee', min: 0, max: 1 },
+    // ⚠️ Codex #111:stake-required 模式(=1)【尚未实现】—— 下单不锁 stake、settleFault 仍按 stake_backing=0 不没收,
+    //   开启会给出虚假"真没收"协议语义。故 max 锁 0(不可开启);待 Phase 3 钱路径迁移实现真锁(下单原子锁 balance→staked)再放开。
+    { key: 'require_seller_stake', value: '0', type: 'number', description: 'RFC-008 是否要求卖家质押(0=起步免赔付/零门槛)。⚠️ stake-required(=1)未实现、暂锁 0 不可开启,见 Phase 3', category: 'fee', min: 0, max: 0 },
     // RFC-008 stage 2:违约罚没率,【与质押率解耦】(低质押=低摩擦 + 高罚没=强威慑,单一费率做不到)。
     //   背书订单:penalty = fault_penalty_rate × total,先扣 staked(封顶背书)再扣自由 balance(责任自负,真可执行)。
     //   起步免赔付(stake_backing=0):仍 0 没收,绝不碰新商家自由余额。settleFault 按订单 stake_backing 判定。
@@ -828,11 +902,14 @@ const DEFAULT_PARAMS = [
     { key: 'require_human_presence_for_arbitrate', value: '1', type: 'number', description: 'Arbitrator 仲裁需 WebAuthn 一次性 token（1=强制 / 0=不强制）— spec §4 铁律', category: 'security', min: 0, max: 1 },
     { key: 'require_human_presence_for_agent_revoke', value: '1', type: 'number', description: '用户撤销 agent 需 WebAuthn 一次性 token — spec §4 铁律', category: 'security', min: 0, max: 1 },
     { key: 'require_human_presence_for_delete_passkey', value: '1', type: 'number', description: '删除 Passkey 自身需 WebAuthn 一次性 token — 防失窃 Passkey 不需 Passkey 就可删它,堵死自我无效化漏洞', category: 'security', min: 0, max: 1 },
+    { key: 'require_human_presence_for_identity_claim', value: '1', type: 'number', description: 'GitHub 身份认领绑定(claim commit)需 WebAuthn 一次性 token — 4b 身份认领的真人铁律门(PR-F0 plumbing;claim endpoint 尚未开放)。默认强制,与 vote/arbitrate/agent_revoke/delete_passkey 同级。', category: 'security', min: 0, max: 1 },
     { key: 'require_human_presence_for_governance_apply', value: '1', type: 'number', description: '治理岗位申请(apply)需 WebAuthn 一次性 token — spec §3.1 Iron-Rule 反诱导 + 真人门', category: 'security', min: 0, max: 1 },
     { key: 'require_human_presence_for_governance_activate', value: '1', type: 'number', description: 'maintainer 激活治理岗位(activate)需 WebAuthn 一次性 token — spec §4.4 Iron-Rule 真人签发', category: 'security', min: 0, max: 1 },
     { key: 'require_human_presence_for_governance_resign', value: '1', type: 'number', description: '主动卸任治理岗位(resign)需 WebAuthn 一次性 token — spec §6.1 二次验证', category: 'security', min: 0, max: 1 },
     { key: 'require_human_presence_for_governance_appeal_resolve', value: '1', type: 'number', description: 'maintainer 裁决申诉(resolve appeal)需 WebAuthn 一次性 token — spec §7.2 Iron-Rule', category: 'security', min: 0, max: 1 },
-    { key: 'require_human_presence_for_withdraw', value: '1', type: 'number', description: '提现(资金转出)需 WebAuthn 一次性 token — 资金转出=真人在场铁律,email-OTP 在 agent 威胁模型下不足(agent 可读收件箱);#1115 全额对齐', category: 'security', min: 0, max: 1 },
+    // ⚠️ Codex #100:提现真人在场是【铁律】,锁死 min=max=1 不可关闭(防 protocol admin PATCH 设 0 绕过)。
+    //   且 wallet-write.ts 已【无条件】执行 Passkey gate(不读此 param),此处仅作诚实展示 + PATCH 防线。
+    { key: 'require_human_presence_for_withdraw', value: '1', type: 'number', description: '提现(资金转出)需 WebAuthn 一次性 token — 真人在场【铁律,锁死不可关闭】;wallet-write 无条件执行', category: 'security', min: 1, max: 1 },
     { key: 'governance_resign_cooldown_days', value: '30', type: 'number', description: '主动卸任后冷却期(天)— 防止 farming 切换洗票 / 误操作反复', category: 'governance', min: 7, max: 365 },
     { key: 'governance_appeal_window_days', value: '14', type: 'number', description: '收到 auto_deactivate 通知后申诉窗口(天)— spec §7.2', category: 'governance', min: 7, max: 90 },
     { key: 'governance_appeal_min_reason_chars', value: '100', type: 'number', description: '申诉理由最少字符数(防空 appeal)', category: 'governance', min: 30, max: 2000 },
@@ -941,6 +1018,24 @@ try {
     WHERE key = 'fund_base_rate' AND max_value > 0.01`).run();
     if (fbCap.changes > 0)
         console.log(`[migration RFC-008] fund_base 硬帽收紧 → max 1%`);
+    // Codex #112 P1:仅收紧 max_value 不够 —— 历史 value > 新 cap 的行(如曾被治理调到 0.05)在 runtime
+    //   getProtocolParam 直接读 value,仍按超帽费率收费,硬帽形同虚设。逐 key 把超帽 value clamp 回 cap,
+    //   并记 protocol_params_log。先于下面 fund_base 的 pre-launch 减免(减免只针对未被治理改过的原始 0.01)。
+    const clampFeeValue = (key, cap) => {
+        const cur = db.prepare('SELECT value FROM protocol_params WHERE key = ? AND CAST(value AS REAL) > ?').get(key, cap);
+        if (!cur)
+            return;
+        db.prepare(`UPDATE protocol_params SET value = ?, updated_at = datetime('now') WHERE key = ? AND CAST(value AS REAL) > ?`).run(String(cap), key, cap);
+        console.log(`[migration RFC-008] ${key} value ${cur.value} → ${cap}(clamp 回硬帽)`);
+        try {
+            db.prepare(`INSERT INTO protocol_params_log (id, key, old_value, new_value, changed_by, action)
+                       VALUES (?,?,?,?,?,'migrate')`).run(generateId('ppl'), key, cur.value, String(cap), 'migration_RFC-008');
+        }
+        catch { }
+    };
+    clampFeeValue('protocol_fee_rate_shop', 0.02);
+    clampFeeValue('protocol_fee_rate_secondhand', 0.02);
+    clampFeeValue('fund_base_rate', 0.01);
     const fb = db.prepare(`UPDATE protocol_params SET value = '0', default_value = '0', updated_at = datetime('now')
     WHERE key = 'fund_base_rate' AND value = '0.01' AND updated_by IS NULL`).run();
     if (fb.changes > 0) {
@@ -955,6 +1050,52 @@ try {
 catch (e) {
     console.error('[migration RFC-008]', e);
 }
+// Codex #111 P1:require_seller_stake 当前是【假开关】—— 即使=1,下单仍写 stake_backing=0、不锁 stake,
+//   settleFault 仍按 backing=0 不没收;开启只会给出虚假"真没收"语义。stake-required 真锁留待 Phase 3。
+//   在此之前:max 锁 0(不可开启)+ 若历史 DB 被设为 1 则降回 0(中和假开关),并记 protocol_params_log。
+try {
+    const cap = db.prepare(`UPDATE protocol_params SET max_value = 0, updated_at = datetime('now')
+    WHERE key = 'require_seller_stake' AND max_value > 0`).run();
+    if (cap.changes > 0)
+        console.log(`[migration RFC-008] require_seller_stake max → 0(stake-required 未实现,锁关)`);
+    const rss = db.prepare(`SELECT value FROM protocol_params WHERE key = 'require_seller_stake' AND CAST(value AS REAL) > 0`).get();
+    if (rss) {
+        db.prepare(`UPDATE protocol_params SET value = '0', updated_at = datetime('now') WHERE key = 'require_seller_stake'`).run();
+        console.log(`[migration RFC-008] require_seller_stake value ${rss.value} → 0(假开关中和)`);
+        try {
+            db.prepare(`INSERT INTO protocol_params_log (id, key, old_value, new_value, changed_by, action)
+                       VALUES (?,?,?,?,?,'migrate')`).run(generateId('ppl'), 'require_seller_stake', rss.value, '0', 'migration_RFC-008');
+        }
+        catch { }
+    }
+}
+catch (e) {
+    console.error('[migration require_seller_stake lock]', e);
+}
+// Codex #100 P1:提现真人 Passkey 是【铁律】,绝不可被 protocol param 关闭。
+//   旧默认 min=0/max=1 让 protocol admin PATCH 设 0 即可绕过(wallet-write 旧代码 if(param===1))。
+//   双重防线:wallet-write 已改无条件执行 Passkey gate(不再读此 param);此处把 param 锁死 value/min/max=1
+//   (PATCH 校验 min/max → 再不能设 0),并把历史 DB 的 value=0 / 放开的 min/max clamp 回 1,记 protocol_params_log。
+try {
+    const wkey = 'require_human_presence_for_withdraw';
+    const lockBounds = db.prepare(`UPDATE protocol_params SET min_value = 1, max_value = 1, updated_at = datetime('now')
+    WHERE key = ? AND (min_value != 1 OR max_value != 1)`).run(wkey);
+    if (lockBounds.changes > 0)
+        console.log(`[migration Codex#100] ${wkey} min/max → 1(铁律,锁死不可关闭)`);
+    const hp = db.prepare(`SELECT value FROM protocol_params WHERE key = ? AND CAST(value AS REAL) != 1`).get(wkey);
+    if (hp) {
+        db.prepare(`UPDATE protocol_params SET value = '1', default_value = '1', updated_at = datetime('now') WHERE key = ?`).run(wkey);
+        console.log(`[migration Codex#100] ${wkey} value ${hp.value} → 1(提现真人铁律,历史绕过值 clamp 回)`);
+        try {
+            db.prepare(`INSERT INTO protocol_params_log (id, key, old_value, new_value, changed_by, action)
+                       VALUES (?,?,?,?,?,'migrate')`).run(generateId('ppl'), wkey, hp.value, '1', 'migration_Codex-100');
+        }
+        catch { }
+    }
+}
+catch (e) {
+    console.error('[migration require_human_presence_for_withdraw lock]', e);
+}
 // Wave G-2: USDC ↔ WAZ 转换助手
 function usdcToWaz(usdc) {
     const rate = getProtocolParam('waz_usdc_rate', 1.0);
@@ -982,6 +1123,10 @@ function getProtocolParam(key, fallback) {
         return fallback;
     }
 }
+// PR-F0: 人工铁律 gate(consumeGateToken / requireHumanPresence)抽到 ./human-presence.ts 以便单测
+// (behavior-zero)。必须在【首个使用点】(下方 arbitrate/vote/claim-verify/webauthn 等路由注册)之前
+// 实例化 —— 故置于 db + getProtocolParam 定义之后。原为 hoisted 函数声明,现为工厂返回的 const。
+const { consumeGateToken, requireHumanPresence } = createHumanPresence(db, getProtocolParam);
 // Wave E-4 audit P1-3: 平台奖励发放审计 — 记录所有 platform → user 的免费 WAZ 拨付
 db.exec(`
   CREATE TABLE IF NOT EXISTS platform_reward_log (
@@ -3338,6 +3483,23 @@ function resolveUserRef(raw) {
     }
     return null;
 }
+// Invite-code-ONLY resolver — for registration sponsor + /i short links. Accepts a 6-7 char permanent_code
+// with an optional -L/-R side suffix; rejects usr_xxx / @handle / bare handle (anti-ambiguity, narrows the
+// public invite surface). Excludes sys_protocol + the internal auditor. Distinct from resolveUserRef, which
+// stays for personal-page / non-invite lookups.
+function resolveInviteCodeRef(raw) {
+    if (!raw || typeof raw !== 'string')
+        return null;
+    const m = raw.trim().match(/^([A-Za-z0-9]{6,7})(?:-([LRlr]))?$/);
+    if (!m)
+        return null;
+    const code = m[1].toUpperCase();
+    const side = m[2] ? (m[2].toLowerCase() === 'l' ? 'left' : 'right') : null;
+    const r = db.prepare("SELECT id FROM users WHERE permanent_code = ? AND id NOT IN ('sys_protocol', ?) LIMIT 1").get(code, INTERNAL_AUDITOR_ID);
+    if (!r)
+        return null;
+    return { userId: r.id, code, side };
+}
 // 一次性回填：现有用户补齐 permanent_code + handle（启动时跑）
 try {
     const rows = db.prepare("SELECT id, name FROM users WHERE permanent_code IS NULL OR handle IS NULL").all();
@@ -5687,13 +5849,19 @@ function isTrustedRole(user) {
 // #1013 Phase 118: register 已迁出（VALID_REGIONS 在下方 const → 用 getter 避免 TDZ）
 registerAuthRegisterRoutes(app, {
     db, errorRes, INTERNAL_AUDITOR_ID,
-    isAllowedSponsor, resolveUserRef,
+    isAllowedSponsor, resolveUserRef, resolveInviteCodeRef,
     generateId, generateSecureKey, generatePermanentCode, deriveHandle,
     clientIpHash, clientUaHash,
     get VALID_REGIONS() { return VALID_REGIONS; },
     pickPreferredSide, joinPowerLeg,
     get INVITE_ROTATION_HANDLES() { return INVITE_ROTATION_HANDLES; },
     inviteRotationLookup,
+    // 邮箱验证优先注册 — issueCode/findActiveCode 是 hoisted 函数声明、isVerificationEmailReady/
+    // emailDeliveryNotConfigured 是 import,均可在此安全引用;CODE_TTL_MIN/MAX_CODE_ATTEMPTS 是后置 const,
+    // 走 getter 延迟读避免 TDZ。
+    issueCode, findActiveCode, canDeliverCodes: isVerificationEmailReady, emailDeliveryNotConfigured,
+    get CODE_TTL_MIN() { return CODE_TTL_MIN; },
+    get MAX_CODE_ATTEMPTS() { return MAX_CODE_ATTEMPTS; },
     recordSession, broadcastSystemEvent,
 });
 // #1013 Phase 116: me + profile 已迁出
@@ -5718,8 +5886,28 @@ registerBuildTasksRoutes(app, {
     db, auth,
     requireSupportAdmin: (req, res) => requireAdminPermission(req, res, 'support'),
 });
+// PR9C-1 — public Task Board read surface(无需登录;仅 audience=public + status=open;只读,带 value_boundary)
+registerPublicBuildTasksRoutes(app, { db, errorRes });
+// Task Proposal Inbox v1 — public submit(匿名,validated,限流+去重)+ admin review;建议入收件箱,绝不自动成正式任务/上公开板
+const proposalRateLimiter = createSlidingWindowLimiter(20, 3600_000); // 20 submissions / hour / IP
+registerTaskProposalsRoutes(app, {
+    db, errorRes,
+    requireSupportAdmin: (req, res) => requireAdminPermission(req, res, 'support'),
+    rateLimitOk: (key) => proposalRateLimiter(key),
+});
 // RFC-006 Gap 2:贡献者自查看板(build_reputation 独立池)
 registerBuildReputationRoutes(app, { db, auth });
+// PR-F3c — 最小 GitHub 身份认领 API(发起挑战 → Passkey 人门 + WebAZ 自验 gist → F2 原子认领)。
+// GitHub 读 token 仅来自可信服务端配置;未配置则 completion fail-closed(不做匿名限流读)。
+registerContributionIdentityRoutes(app, {
+    auth,
+    requireHumanPresence,
+    errorRes,
+    getGithubReadToken: () => process.env.GITHUB_CONTRIB_READ_TOKEN || undefined,
+});
+// PR5F — Contribution Score v1 evidence READ surface (logged-in self-view; read-only, no score).
+// Returns the caller's OWN component evidence wrapped in the PR5A uncommitted-value boundary.
+registerContributionScoreRoutes(app, { auth, errorRes });
 // #1013 Phase 48: 3 auth/sessions endpoints 已迁出到 routes/auth-sessions.ts
 registerAuthSessionsRoutes(app, { db, auth, verifyPassword, recordSession, generateSecureKey });
 // 个人资料：查看 API Key + 联系方式
@@ -5851,23 +6039,30 @@ registerAuthLoginRoutes(app, {
 const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 const CODE_TTL_MIN = 10;
 const MAX_CODE_ATTEMPTS = 5;
-const IS_DEV = process.env.NODE_ENV !== 'production';
 function genCode() {
     return String(Math.floor(100000 + Math.random() * 900000));
 }
-function deliverCode(target, code, purpose) {
-    // dev: console；prod: 接 SMTP / SMS（P3）
-    console.log(`[verify] ${purpose} → ${target}  code=${code}  (expires ${CODE_TTL_MIN}min)`);
+async function deliverCode(target, code, purpose) {
+    return deliverVerificationCode({ target, code, purpose, ttlMin: CODE_TTL_MIN });
 }
-function issueCode(userId, channel, target, purpose) {
+async function issueCode(userId, channel, target, purpose) {
+    if (channel === 'email' && !isVerificationEmailReady())
+        return emailDeliveryNotConfigured();
     const id = generateId('vcode');
     const code = genCode();
     const expiresAt = new Date(Date.now() + CODE_TTL_MIN * 60_000).toISOString();
     db.prepare(`INSERT INTO verification_codes (id, user_id, channel, target, code, purpose, expires_at)
               VALUES (?,?,?,?,?,?,?)`)
         .run(id, userId, channel, target, code, purpose, expiresAt);
-    deliverCode(target, code, purpose);
-    return { code, expires_at: expiresAt };
+    const delivered = await deliverCode(target, code, purpose);
+    if (!delivered.ok) {
+        try {
+            db.prepare("UPDATE verification_codes SET used_at = datetime('now') WHERE id = ?").run(id);
+        }
+        catch { }
+        return delivered;
+    }
+    return { ok: true, code, expires_at: expiresAt, provider: delivered.provider };
 }
 function findActiveCode(channel, target, purpose) {
     return db.prepare(`
@@ -5880,12 +6075,13 @@ function findActiveCode(channel, target, purpose) {
 // #1013 Phase 49: 3 recover-key endpoints 已迁出到 routes/recover-key.ts
 registerRecoverKeyRoutes(app, {
     db, internalAuditorId: INTERNAL_AUDITOR_ID,
-    issueCode, findActiveCode, CODE_TTL_MIN, MAX_CODE_ATTEMPTS,
+    issueCode, findActiveCode, canDeliverCodes: isVerificationEmailReady,
+    emailDeliveryNotConfigured, hashPassword, CODE_TTL_MIN, MAX_CODE_ATTEMPTS,
 });
 // #1013 Phase 55: 5 profile-credentials endpoints 已迁出到 routes/profile-credentials.ts
 registerProfileCredentialsRoutes(app, {
     db, auth, verifyPassword, hashPassword,
-    issueCode, findActiveCode, IS_DEV, MAX_CODE_ATTEMPTS,
+    issueCode, findActiveCode, MAX_CODE_ATTEMPTS,
 });
 // 搜索商品（声誉权重排序）
 // 构建 agent_summary：一句话决策摘要
@@ -6116,6 +6312,7 @@ registerFlashSalesRoutes(app, { db, generateId, auth, broadcastSystemEvent });
 registerTrialRoutes(app, {
     db, generateId, auth, clientIpHash, clientUaHash,
     requireProtocolAdmin: (req, res) => requireAdminPermission(req, res, 'protocol'),
+    logAdminAction,
 });
 // ─── Wave B-2: 预售 / waitlist ─────────────────────────────
 // #1013 Phase 24: 5 endpoints 已迁出到 routes/waitlist.ts
@@ -6537,6 +6734,7 @@ registerAdminOpsRoutes(app, {
     hasAdminPermission,
     INTERNAL_AUDITOR_ID, ADMIN_EXPORT_LIMIT, csvEscapeAdmin,
     anthropic, applyDecayIfDue, computeValueBadges,
+    logAdminAction,
 });
 // AI 2 endpoints — Phase 100 已迁出
 registerAiRoutes(app, { db, auth, anthropic });
@@ -6566,6 +6764,7 @@ registerAdminModerationRoutes(app, {
     db, generateId,
     requireUsersAdmin: (req, res) => requireAdminPermission(req, res, 'users'),
     authFailures, INTERNAL_AUDITOR_ID, broadcastSystemEvent,
+    logAdminAction,
 });
 // 邀请码 3 endpoints — Phase 98 已迁出
 registerReferralRoutes(app, {
@@ -7037,9 +7236,9 @@ setInterval(() => {
 }, 24 * 60 * 60_000);
 // 2026-05-24 #980：测评免单 reach 评估 cron — 每 6h 跑一次
 // #1013 Phase 3: evaluateTrialClaims + /api/admin/trial/run-eval 已迁出到 routes/trial.ts；这里只挂 cron
-setInterval(() => {
+setInterval(async () => {
     try {
-        const r = evaluateTrialClaims(db, generateId);
+        const r = await evaluateTrialClaims(db, generateId);
         if (r.evaluated > 0)
             console.log(`[cron trial-eval] evaluated=${r.evaluated} refunded=${r.refunded} expired=${r.expired}`);
     }
@@ -7063,6 +7262,7 @@ setInterval(() => {
 registerAdminAtomicRoutes(app, {
     requireProtocolAdmin: (req, res) => requireAdminPermission(req, res, 'protocol'),
     processPvLedger, runBinarySettlement, executeSafeSettlementCron,
+    logAdminAction,
 });
 // #1013 Phase 110: tokenomics/status + shares/dashboard 已迁出
 registerDashboardsRoutes(app, { db, auth });
@@ -7070,7 +7270,7 @@ registerDashboardsRoutes(app, { db, auth });
 // #1013 Phase 56: 3 placement endpoints 已迁出到 routes/profile-placement.ts
 registerProfilePlacementRoutes(app, {
     db, auth, internalAuditorId: INTERNAL_AUDITOR_ID,
-    resolveUserRef, pickPreferredSide, joinPowerLeg,
+    resolveUserRef, resolveInviteCodeRef, pickPreferredSide, joinPowerLeg,
 });
 // shares/dashboard — Phase 110 已迁出
 // ─── 推土机轨道：推广统计端点 ─────────────────────────────────
@@ -7098,6 +7298,7 @@ registerAdminUsersQueryRoutes(app, {
     adminCanOperateOn, isRootAdmin, isAllowedSponsor,
     maskApiKey, computeLightTags, getAdminScope, getSellerDailyLimit, todayStartISO,
     broadcastSystemEvent, INTERNAL_AUDITOR_ID,
+    logAdminAction,
 });
 function getSellerDailyLimit(user) {
     const id = String(user.id ?? '');
@@ -7364,12 +7565,12 @@ registerRewardsApplyRoutes(app, {
 });
 // task #1093 stage 5: admin manual auto-deactivate sweep trigger
 // Useful for ops + testing. The scheduled cron also runs every N hours.
-app.post('/api/admin/governance/run-auto-deactivate', (req, res) => {
+app.post('/api/admin/governance/run-auto-deactivate', async (req, res) => {
     const admin = requireAdminPermission(req, res, 'arbitration');
     if (!admin)
         return;
     try {
-        const result = runAutoDeactivateSweep({ db, generateId, getProtocolParam });
+        const result = await runAutoDeactivateSweep({ db, generateId, getProtocolParam });
         logAdminAction(admin.id, 'governance_auto_deactivate_sweep', null, null, {
             scanned: result.scanned,
             deactivated_count: result.deactivated.length,
@@ -7530,7 +7731,7 @@ registerOrdersCreateRoutes(app, {
     getActiveFlashSale, applyCouponToOrder, getProtocolParam,
     getProductShareChain, isAllowedSponsor, checkStockAndMaybeDelist, auditSponsorChainCross,
     appendOrderEvent, transition, notifyTransition, shouldAutoAccept, ensureCharityRep,
-    broadcastSystemEvent,
+    broadcastSystemEvent, resolveInviteCodeRef,
     signPassport: (message) => privateKeyToAccount(derivePrivKey('platform-hot-wallet')).signMessage({ message }),
     issuerAddress: () => privateKeyToAddress(derivePrivKey('platform-hot-wallet')),
 });
@@ -7954,6 +8155,7 @@ registerAuctionRoutes(app, {
     RFQ_MAX_QTY, RFQ_MAX_PRICE,
     LISTING_CATEGORIES, isListingCategoryKey,
     requireProtocolAdmin: (req, res) => requireAdminPermission(req, res, 'protocol'),
+    logAdminAction,
 });
 // AUC 结算 helper：到期 → 最高 active bid → 建单（或流拍）
 // P0 audit fix #2：顶层 try/catch 兜底，意外抛错时 status='error' 防 cron 死循环
@@ -9336,69 +9538,8 @@ registerWebauthnRoutes(app, {
     invalidateAgentRiskCacheForUser,
     requireHumanPresence, // #1044 — DELETE passkey 自身需 token
 });
-// 验证 gate token：被业务端点（如 /api/wallet/withdraw）消费
-// M-1: 改 CAS — 先抢占性 UPDATE，只有 changes=1 才认为本次成功消费；
-// 然后再读 row 校验 user/purpose/业务字段。多副本部署也安全。
-function consumeGateToken(userId, token, purpose, validate) {
-    if (!token)
-        return { ok: false, reason: '缺少 X-WebAuthn-Token' };
-    // 先抢占：未消费 + 未过期 才能 mark consumed
-    const claim = db.prepare(`UPDATE webauthn_gate_tokens
-    SET consumed_at = datetime('now')
-    WHERE id = ? AND consumed_at IS NULL AND expires_at > datetime('now')`).run(token);
-    if (claim.changes !== 1) {
-        // 抢占失败的两种原因区分（仅用于 reason 文案）
-        const exist = db.prepare('SELECT consumed_at FROM webauthn_gate_tokens WHERE id = ?').get(token);
-        if (!exist)
-            return { ok: false, reason: 'token 不存在' };
-        if (exist.consumed_at)
-            return { ok: false, reason: 'token 已使用' };
-        return { ok: false, reason: 'token 已过期' };
-    }
-    // 已抢占 → 读 row 校验 user/purpose/业务字段；若校验失败 token 仍然作废（防止枚举攻击下的重试）
-    const row = db.prepare(`SELECT user_id, purpose, purpose_data FROM webauthn_gate_tokens WHERE id = ?`)
-        .get(token);
-    if (row.user_id !== userId)
-        return { ok: false, reason: 'token 用户不匹配' };
-    if (row.purpose !== purpose)
-        return { ok: false, reason: 'token 用途不匹配' };
-    let data = null;
-    try {
-        data = row.purpose_data ? JSON.parse(row.purpose_data) : null;
-    }
-    catch { }
-    if (!validate(data))
-        return { ok: false, reason: 'token 业务参数不匹配' };
-    return { ok: true };
-}
-// ─── 2026-05-23 Agent 治理铁律：人工铁律节点 ───────────────────
-// spec: docs/AGENT-GOVERNANCE.md §4
-// 关键节点（verifier 投票 / arbitrator 仲裁）必须真实人工参与，agent 代操作要被拦截。
-// 实现：要求 webauthn_gate_token（一次性消费 · 60s 内有效）+ 协议参数开关。
-// 2026-05-25 #1006：默认值 0 → 1 启用强制；is_system fixture 旁路只对 vote/arbitrate 生效。
-//   agent_revoke 是普通用户操作，不享有 is_system 豁免（无 fixture 概念）。
-function requireHumanPresence(userId, purpose, token, paramKey, validate = () => true) {
-    const enabled = Number(getProtocolParam(paramKey, 1)) === 1;
-    if (!enabled)
-        return { ok: true }; // 协议参数关闭 → 不强制
-    // is_system fixture 旁路：用于 E2E 测试 / 自动化 / migration 账号
-    // 仅 vote / arbitrate 适用（这两类有白名单表 + is_system 列）；真实用户无此豁免
-    if (purpose === 'vote') {
-        const wl = db.prepare('SELECT is_system FROM verifier_whitelist WHERE user_id = ?').get(userId);
-        if (wl?.is_system === 1)
-            return { ok: true };
-    }
-    else if (purpose === 'arbitrate') {
-        const wl = db.prepare('SELECT is_system FROM arbitrator_whitelist WHERE user_id = ?').get(userId);
-        if (wl?.is_system === 1)
-            return { ok: true };
-    }
-    const result = consumeGateToken(userId, token, purpose, validate);
-    if (!result.ok) {
-        return { ok: false, error_code: 'HUMAN_PRESENCE_REQUIRED', reason: result.reason || '此操作需真实人工 WebAuthn 验证', required_when_enabled: true };
-    }
-    return { ok: true };
-}
+// consumeGateToken / requireHumanPresence 已抽出到 ./human-presence.ts(PR-F0,behavior-zero,
+// 工厂 createHumanPresence(db, getProtocolParam),在 db+getProtocolParam 定义后即实例化 —— 见上方)。
 // ─── M7.3 claim 验证任务系统 ──────────────────────────────
 // #1013 Phase 9: 8 endpoints + 三路径结算 + outlier strike + 铁律 §4 已迁出到 routes/claim-verify.ts
 // product_claim_tasks (Sprint 1) 跨域用 isEligibleClaimVerifier — 从 import 拿
@@ -9706,7 +9847,8 @@ registerReviewsRoutes(app, {
 // #1013 Phase 76: 3 垂类 × 2 (POST claim + GET claims) = 6 endpoints 已迁出
 registerClaimInitiatorsRoutes(app, { db, auth, isTrustedRole, errorRes, generateId });
 // ─── 分享 / 重定向 / QR (#1013 Phase 54) ────────────────────
-registerShareRedirectsRoutes(app, { db, auth, clientIpHash, clientUaHash });
+registerShareRedirectsRoutes(app, { db, auth, clientIpHash, clientUaHash, resolveInviteCodeRef });
+registerShopReferralRoutes(app, { db, auth, errorRes, internalAuditorId: INTERNAL_AUDITOR_ID, resolveUserRef, resolveInviteCodeRef });
 // 慈善许愿池 API
 // ============================================================
 // ─── 慈善许愿池 (charity) ─────────────────────────────────
@@ -9735,6 +9877,23 @@ registerAdminWalletOpsRoutes(app, {
     getIsMainnet: () => IS_MAINNET,
     getNetwork: () => NETWORK,
     executeWithdrawal: (id) => executeWithdrawal(id),
+    logAdminAction,
+    // dual-accept transition for attribution(非最终安全收紧):只读、不响应地解析登录的 protocol-admin。
+    // 用 resolveBearerProtocolAdmin(钱路强校验):仅认 Authorization: Bearer(不认 req.body.api_key)、
+    // 拒暂停用户、拒已吊销会话;角色+protocol 权限用中央 hasAdminPermission(防漂移)。null → 回落共享 ADMIN_KEY。
+    // 最终弃用 x-admin-key 留后续 PR。
+    resolveProtocolAdminSoft: (req) => resolveBearerProtocolAdmin(db, req, (u) => {
+        let rolesList = [];
+        try {
+            rolesList = JSON.parse(u.roles || '[]');
+        }
+        catch {
+            rolesList = [];
+        }
+        if (u.role !== 'admin' && !rolesList.includes('admin'))
+            return false;
+        return hasAdminPermission(u, 'protocol');
+    }),
 });
 // #1013 Phase 80: 10 wallet read endpoints 已迁出
 registerWalletReadRoutes(app, {
@@ -9824,14 +9983,11 @@ function runEnforcement() {
             console.error('证据清理失败：', e.message);
         }
         // Phase C 笔记图片孤儿 cleanup — 没有任何笔记引用且超过 1 小时 grace 期的 blob
-        try {
-            const npCleaned = cleanupOrphanNotePhotos(db);
-            if (npCleaned.swept > 0)
-                console.log(`⚡ Note photo cleanup × ${npCleaned.swept} files (${Math.round(npCleaned.bytes / 1024)}KB)`);
-        }
-        catch (e) {
-            console.error('笔记图片清理失败：', e.message);
-        }
+        // RFC-016:cleanupOrphanNotePhotos 已异步(纯读 + fs 删);best-effort 孤儿清理,fire-and-forget 不阻塞同步 cron runEnforcement。
+        cleanupOrphanNotePhotos(db)
+            .then(npCleaned => { if (npCleaned.swept > 0)
+            console.log(`⚡ Note photo cleanup × ${npCleaned.swept} files (${Math.round(npCleaned.bytes / 1024)}KB)`); })
+            .catch(e => console.error('笔记图片清理失败：', e.message));
         // E1 流量口令 reclaim — retired 满 365 天 → reclaimable（namespace 释放）
         try {
             const r = reclaimRetiredAnchors(db);
@@ -10223,6 +10379,21 @@ db.exec(`
               VALUES (?, ?, 'major', ?, ?, ?, ?)`)
         .run('1.0', hash, Date.now(), textZh, textEn, 'Initial v1.0 lock — placeholder canonical text pointing to RFC-002');
 })();
+(function seedConsentV11() {
+    const existing = db.prepare("SELECT version FROM rewards_consent_texts WHERE version = '1.1'").get();
+    if (existing)
+        return;
+    const textZh = 'WebAZ 分享分润开通(rewards opt-in) v1.1 — 由 RFC-002 §3.3 / §3.10 定义。本同意仅用于记录分享分润相关的经济关系:Passkey 真人签名、推荐关系/左右区位置、佣金/PV/escrow 结算规则。本流程不是购物流程,也不是共建贡献资格;不影响贡献任务、GitHub 贡献认领或普通下单。佣金层级按地区合规配置生效;当前预发布期全局上限为 1 级,“三级”仅为协议最大设计。你可以随时退出,退出不影响已下单或未来订单;已发生的订单和结算按当时有效规则处理。';
+    const textEn = 'WebAZ share-commission opt-in (rewards opt-in) v1.1 — defined by RFC-002 §3.3 / §3.10. This consent only records the economic relationship for share commission: Passkey-signed proof of personhood, referral relationship / left-right placement, and commission / PV / escrow settlement rules. This is not a shopping flow and not contribution eligibility; it does not affect contribution tasks, GitHub contribution claims, or normal orders. Commission levels follow per-region compliance configuration; during pre-launch the global cap is 1 level, and “three tiers” is only the protocol maximum design. You may leave at any time without affecting past or future orders; already-created orders and settlements follow the rules effective at that time.';
+    const hash = createHash('sha256').update(textZh + '\n---\n' + textEn).digest('hex');
+    // effective_at must be strictly later than v1.0's so "latest major" deterministically resolves to v1.1
+    // even on a fresh DB that seeds both rows in the same boot (avoids a same-ms ORDER BY tie).
+    const v10 = db.prepare("SELECT effective_at FROM rewards_consent_texts WHERE version = '1.0'").get();
+    const effectiveAt = Math.max(Date.now(), (v10?.effective_at ?? 0) + 1);
+    db.prepare(`INSERT INTO rewards_consent_texts (version, hash, change_class, effective_at, text_zh, text_en, changelog)
+              VALUES (?, ?, 'major', ?, ?, ?, ?)`)
+        .run('1.1', hash, effectiveAt, textZh, textEn, 'v1.1 clarification — share-commission opt-in framing (not 共建身份/Builder Identity, not contribution eligibility) + current commission-level reality boundary (pre-launch cap 1 level); v1.0 left frozen');
+})();
 // 4. rewards_applications:申请留痕表(append-only audit;action='activate'|'deactivate'|'auto_downgrade'|'reconfirm')
 db.exec(`
   CREATE TABLE IF NOT EXISTS rewards_applications (
@@ -10314,6 +10485,49 @@ try {
     db.exec('CREATE UNIQUE INDEX IF NOT EXISTS uniq_escrow_recipient_order_path ON pending_commission_escrow(recipient_user_id, order_id, attribution_path)');
 }
 catch { }
+// Codex #69 P1:pv_escrow_reserve(#1106 隔离负债账)回填历史 pending pv_pair escrow —— 按 delta 对账,不全量转。
+//   该列在 global_fund 上新增(line ~2319);#1106 之后新建的 pv_pair escrow 结算时【已】pv_escrow_reserve += wazAmount,
+//   但加列【之前】产生的 pending pv_pair 从没进过 reserve。升级窗口里两者混存。
+//   ⚠️ 不能"全量 SUM(pending pv_pair) 再转":会把已隔离的新 escrow 二次扣 pool。
+//   正确做法:reserve 的目标值 = 当前所有 pending pv_pair 负债;只补差额 delta = liability - currentReserve 的正数部分。
+//     · delta > 0:pool -= delta, reserve += delta(纯转账,total 不变);pool 不足则记 shortfall 风险项(基于 delta)。
+//     · delta <= 0:已对齐/超额,不反向移动(避免误伤业务流);currentReserve > liability 记 anomaly 供核账。
+//   幂等(system_state 标志)。放在 pending_commission_escrow 建表/迁移之后(ALTER-after-CREATE 铁律)。
+try {
+    db.exec("CREATE TABLE IF NOT EXISTS system_state (key TEXT PRIMARY KEY, value TEXT)");
+    const done = db.prepare("SELECT value FROM system_state WHERE key = 'pv_escrow_reserve_backfilled'").get();
+    if (!done) {
+        db.transaction(() => {
+            const liability = db.prepare(`SELECT COALESCE(SUM(amount),0) AS s FROM pending_commission_escrow WHERE status='pending' AND attribution_path='pv_pair'`).get().s;
+            const gf = db.prepare("SELECT pool_balance, pv_escrow_reserve FROM global_fund WHERE id=1").get();
+            const pool = gf?.pool_balance ?? 0;
+            const currentReserve = gf?.pv_escrow_reserve ?? 0;
+            const delta = Math.round((liability - currentReserve) * 100) / 100; // 只补"尚未隔离"的部分
+            if (delta > 0) {
+                db.prepare("UPDATE global_fund SET pv_escrow_reserve = pv_escrow_reserve + ?, pool_balance = pool_balance - ? WHERE id=1").run(delta, delta);
+                console.log(`[migration pv_escrow_reserve backfill] 历史未隔离 pv_pair 负债 delta=${delta}(liability ${liability} - reserve ${currentReserve})从 pool 移入 reserve(pool ${pool}→${pool - delta})`);
+                if (pool < delta) {
+                    const shortfall = Math.round((delta - pool) * 100) / 100;
+                    console.error(`[migration pv_escrow_reserve backfill] ⚠️ pool_balance(${pool}) < 待回填 delta(${delta});pool 已为负,缺口 ${shortfall} 需人工核账`);
+                    db.prepare("INSERT OR REPLACE INTO system_state (key, value) VALUES ('pv_escrow_reserve_backfill_shortfall', ?)").run(String(shortfall));
+                }
+            }
+            else if (delta < 0) {
+                // reserve 比 pending 负债还多 —— 不反向移动(避免误伤),只记异常供 admin 核账
+                const anomaly = Math.round((currentReserve - liability) * 100) / 100;
+                console.error(`[migration pv_escrow_reserve backfill] ⚠️ pv_escrow_reserve(${currentReserve}) > pending pv_pair 负债(${liability}),超额 ${anomaly};不反向移动,记 anomaly 供核账`);
+                db.prepare("INSERT OR REPLACE INTO system_state (key, value) VALUES ('pv_escrow_reserve_backfill_anomaly', ?)").run(String(anomaly));
+            }
+            else {
+                console.log(`[migration pv_escrow_reserve backfill] reserve(${currentReserve})已等于 pending pv_pair 负债(${liability}),无需回填`);
+            }
+            db.prepare("INSERT OR REPLACE INTO system_state (key, value) VALUES ('pv_escrow_reserve_backfilled', '1')").run();
+        })();
+    }
+}
+catch (e) {
+    console.error('[migration pv_escrow_reserve backfill]', e);
+}
 // 6. INSERT 5 个 RFC-002 protocol_params(独立 INSERT,不动 DEFAULT_PARAMS array)
 // 两个标 requires_meta_rule_change=1:require_passkey + consent_delay_seconds(P0-4 闭环)
 const RFC002_PARAMS = [