@seasonkoh/webaz 0.1.23 → 0.1.25

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';
@@ -48,6 +49,7 @@ import { createHmac, createHash, randomBytes, scryptSync, timingSafeEqual } from
 import { safeFetch } from './security/ssrf.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 +170,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
@@ -303,9 +306,19 @@ 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 { 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 +357,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 +373,12 @@ 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)
 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 +648,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 +858,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 +896,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 +1012,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 +1044,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 +1117,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 +3477,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,7 +5843,7 @@ 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; },
@@ -5718,8 +5874,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 + 联系方式
@@ -7037,9 +7213,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}`);
     }
@@ -7070,7 +7246,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 已迁出
 // ─── 推土机轨道：推广统计端点 ─────────────────────────────────
@@ -7364,12 +7540,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 +7706,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')),
 });
@@ -9336,69 +9512,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 +9821,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) ─────────────────────────────────
@@ -9824,14 +9940,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);
@@ -10314,6 +10427,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 = [

package/dist/version.js

@@ -29,4 +29,4 @@ export const SOFTWARE_VERSION = pkg.version;
  *  (capability matrix §② / entity dictionary §①); the CONTRACT_CHANGES `kind` classifies whether
  *  it is breaking. Additive changes (kind:'added') are safe for agents to ignore. Guarded by
  *  tests/test-contract-fingerprint.ts + docs/CONTRACT-LOCK.json. */
-export const CONTRACT_VERSION = 2;
+export const CONTRACT_VERSION = 4;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seasonkoh/webaz",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "[PRE-LAUNCH] Agent-native decentralized commerce protocol. Humans and AI agents trade on the same protocol via MCP tools. ⚠️ Repository currently private until W8 public launch — GitHub links may return 404. See https://webaz.xyz for status.",
   "main": "dist/mcp.js",
   "bin": {
@@ -20,10 +20,53 @@
     "enforcement": "tsx src/cron-enforcement.ts",
     "pwa": "tsx src/pwa/server.ts",
     "schema:verify": "tsx scripts/schema-verify.ts",
+    "routes:seam-check": "tsx scripts/routes-seam-guard.ts",
+    "pg:schema": "tsx scripts/gen-pg-schema.ts",
+    "pg:verify": "tsx scripts/pg-schema-verify.ts",
+    "test:pg-placeholders": "tsx scripts/test-pg-placeholders.ts",
+    "test:pg-datetime": "tsx scripts/test-pg-datetime.ts",
+    "test:agent-task-spec": "tsx scripts/test-agent-task-spec.ts",
     "contract:verify": "tsx tests/test-contract-fingerprint.ts",
     "license:check": "tsx scripts/license-invariant-check.ts",
     "meta-rules:check": "tsx scripts/meta-rules-invariant-check.ts",
-    "params:check": "tsx scripts/meta-rule-locked-params-check.ts"
+    "params:check": "tsx scripts/meta-rule-locked-params-check.ts",
+    "preflight": "tsx scripts/preflight.ts",
+    "test:github-credential": "tsx scripts/test-github-credential.ts",
+    "test:github-fetch-adapter": "tsx scripts/test-github-fetch-adapter.ts",
+    "test:github-authenticated-read": "tsx scripts/test-github-authenticated-read.ts",
+    "test:github-credential-store": "tsx scripts/test-github-credential-store-schema.ts",
+    "test:github-credential-ingestion": "tsx scripts/test-github-credential-ingestion.ts",
+    "test:identity-binding": "tsx scripts/test-identity-binding.ts",
+    "iron-rules:identity-claim": "tsx scripts/identity-claim-iron-rules-guard.ts",
+    "test:iron-rules-guard": "tsx scripts/test-identity-claim-iron-rules-guard.ts",
+    "test:human-presence": "tsx tests/test-human-presence.ts",
+    "test:identity-claim-challenge": "tsx scripts/test-identity-claim-challenge-schema.ts",
+    "test:identity-claim-engine": "tsx scripts/test-identity-claim-engine.ts",
+    "test:identity-claim-proof-verifier": "tsx scripts/test-identity-claim-proof-verifier.ts",
+    "test:identity-claim-challenge-engine": "tsx scripts/test-identity-claim-challenge-engine.ts",
+    "test:identity-claim-api": "tsx scripts/test-identity-claim-api.ts",
+    "test:identity-claim-read": "tsx scripts/test-identity-claim-read.ts",
+    "test:build-reputation-boundary": "tsx scripts/test-build-reputation-boundary.ts",
+    "test:contribution-score-contract": "tsx scripts/test-contribution-score-contract.ts",
+    "test:contribution-score-evidence": "tsx scripts/test-contribution-score-evidence.ts",
+    "test:contribution-score-read": "tsx scripts/test-contribution-score-read.ts",
+    "test:contributor-entry-relationship-contract": "tsx scripts/test-contributor-entry-relationship-contract.ts",
+    "test-public-contributor-entry-contract": "tsx scripts/test-public-contributor-entry-contract.ts",
+    "test-private-dogfood-runbook-contract": "tsx scripts/test-private-dogfood-runbook-contract.ts",
+    "test-private-dogfood-case-pack-contract": "tsx scripts/test-private-dogfood-case-pack-contract.ts",
+    "test-future-task-board-design-contract": "tsx scripts/test-future-task-board-design-contract.ts",
+    "test:build-task-agent-metadata": "tsx scripts/test-build-task-agent-metadata.ts",
+    "test-dogfood-dryrun-gap-report-contract": "tsx scripts/test-dogfood-dryrun-gap-report-contract.ts",
+    "test:task-board-read": "tsx scripts/test-task-board-read.ts",
+    "test:task-board-participation": "tsx scripts/test-task-board-participation.ts",
+    "test:task-proposals": "tsx scripts/test-task-proposals.ts",
+    "test:public-contribution-pages": "tsx scripts/test-public-contribution-pages.ts",
+    "test:mcp-contribute": "tsx scripts/test-mcp-contribute.ts",
+    "test:proposal-admin-ui": "tsx scripts/test-proposal-admin-ui.ts",
+    "check:pwa-syntax": "node --check src/pwa/public/app.js && node --check src/pwa/public/i18n.js && node --check src/pwa/public/sw.js",
+    "test:rewards-vs-contribution-copy": "tsx scripts/test-rewards-vs-contribution-copy.ts",
+    "test:invite-code-narrowing": "tsx scripts/test-invite-code-narrowing.ts",
+    "test:shop-referral-attribution": "tsx scripts/test-shop-referral-attribution.ts"
   },
   "keywords": [
     "mcp",
@@ -55,6 +98,7 @@
     "@types/qrcode": "^1.5.6",
     "better-sqlite3": "^12.9.0",
     "express": "^5.2.1",
+    "pg": "^8.21.0",
     "qrcode": "^1.5.4",
     "undici": "^8.3.0",
     "viem": "^2.48.11",
@@ -64,6 +108,7 @@
     "@types/better-sqlite3": "^7.6.13",
     "@types/express": "^5.0.6",
     "@types/node": "^25.6.2",
+    "@types/pg": "^8.20.0",
     "tsx": "^4.21.0",
     "typescript": "^6.0.3"
   },