@seasonkoh/webaz 0.1.24 → 0.1.25

package/dist/pwa/routes/claim-verify.js

@@ -1,3 +1,12 @@
+import { dbOne, dbAll, dbRun } from '../../layer0-foundation/L0-1-database/db.js';
+// RFC-016 Phase 1 — 仅端点纯校验读/列表/公开查询/读回 + 单语句标记/字段写 + 写后通知 → async seam。
+// 全部保持同步(Phase 3 再用 pg tx/行锁):
+//   - 模块级 helper(settleClaimTask 三路径结算 / distributePool / checkAndApplyOutlierStrike /
+//     notifyEligibleVerifiers / isEligibleClaimVerifier / activeClaimTaskCountForVerifier /
+//     processClaimTaskQueue)——settleClaimTask 是裸(非 db.transaction)多写结算序列,
+//     由 vote 端点与 cron 调用,必须整体同步;
+//   - claim 发起锁押序列(INSERT task + 锁 stake + has_pending_claim);
+//   - vote 共识序列(票数 guard + INSERT vote + 收齐重数 + seal),seal 后同步调 settleClaimTask。
 // ─── 域常量 ───────────────────────────────────────────────
 export const CLAIM_STAKE_DEFAULT = 10; // 买家发起质押 10 WAZ
 export const CLAIM_DEADLINE_HOURS = 48; // 接单 + 投票截止
@@ -279,11 +288,11 @@ export function processClaimTaskQueue(db, generateId) {
 export function registerClaimVerifyRoutes(app, deps) {
     const { db, auth, generateId, requireHumanPresence } = deps;
     // 买家发起 claim 验证任务（绑定 paid 及之后的订单）
-    app.post('/api/orders/:id/claim-verification', (req, res) => {
+    app.post('/api/orders/:id/claim-verification', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        const order = db.prepare('SELECT * FROM orders WHERE id = ?').get(req.params.id);
+        const order = await dbOne('SELECT * FROM orders WHERE id = ?', [req.params.id]);
         if (!order)
             return void res.status(404).json({ error: '订单不存在' });
         if (order.buyer_id !== user.id)
@@ -292,7 +301,7 @@ export function registerClaimVerifyRoutes(app, deps) {
         if (blockedStatuses.has(order.status)) {
             return void res.status(400).json({ error: `当前订单状态（${order.status}）不可发起验证` });
         }
-        const existing = db.prepare('SELECT id FROM claim_verification_tasks WHERE order_id = ?').get(req.params.id);
+        const existing = await dbOne('SELECT id FROM claim_verification_tasks WHERE order_id = ?', [req.params.id]);
         if (existing)
             return void res.status(409).json({ error: '该订单已存在验证任务（不可撤销）', task_id: existing.id });
         const claim_target = String(req.body?.claim_target || '').trim();
@@ -304,7 +313,7 @@ export function registerClaimVerifyRoutes(app, deps) {
             return void res.status(400).json({ error: 'claim_text 长度需 6-500 字' });
         }
         const evidence_uri = req.body?.evidence_uri ? String(req.body.evidence_uri).trim().slice(0, 500) : null;
-        const wallet = db.prepare('SELECT balance FROM wallets WHERE user_id = ?').get(user.id);
+        const wallet = await dbOne('SELECT balance FROM wallets WHERE user_id = ?', [user.id]);
         const stake = CLAIM_STAKE_DEFAULT;
         if (!wallet || wallet.balance < stake) {
             return void res.status(400).json({ error: `余额不足：发起需锁 ${stake} WAZ，当前余额 ${wallet?.balance ?? 0} WAZ` });
@@ -312,17 +321,43 @@ export function registerClaimVerifyRoutes(app, deps) {
         const id = generateId('cvt');
         const deadline = new Date(Date.now() + CLAIM_DEADLINE_HOURS * 3600_000).toISOString();
         const sellerId = order.seller_id;
-        db.prepare(`INSERT INTO claim_verification_tasks
-      (id, order_id, buyer_id, seller_id, product_id, claim_target, claim_text, evidence_uri, stake_buyer, deadline_at, status)
-      VALUES (?,?,?,?,?,?,?,?,?,?, 'open')`).run(id, req.params.id, user.id, sellerId, order.product_id, claim_target, claim_text, evidence_uri, stake, deadline);
-        db.prepare('UPDATE wallets SET balance = balance - ?, escrowed = escrowed + ? WHERE user_id = ?')
-            .run(stake, stake, user.id);
-        db.prepare('UPDATE orders SET has_pending_claim = 1 WHERE id = ?').run(req.params.id);
-        const productTitle = db.prepare('SELECT title FROM products WHERE id = ?').get(order.product_id)?.title || '—';
+        // Codex #237 P1:原为裸多写序列(await 预检后直接 3 连写,无 db.transaction、无余额守卫)。
+        // 包进 db.transaction + tx 内重检无重复 task + 余额守卫扣押 + 订单 flag CAS;任一失败回滚全部。
+        const BLOCKED = ['created', 'cancelled', 'completed', 'refunded'];
+        try {
+            db.transaction(() => {
+                const dup = db.prepare('SELECT id FROM claim_verification_tasks WHERE order_id = ?').get(req.params.id);
+                if (dup)
+                    throw new Error('CLAIM_EXISTS');
+                db.prepare(`INSERT INTO claim_verification_tasks
+          (id, order_id, buyer_id, seller_id, product_id, claim_target, claim_text, evidence_uri, stake_buyer, deadline_at, status)
+          VALUES (?,?,?,?,?,?,?,?,?,?, 'open')`).run(id, req.params.id, user.id, sellerId, order.product_id, claim_target, claim_text, evidence_uri, stake, deadline);
+                const d = db.prepare('UPDATE wallets SET balance = balance - ?, escrowed = escrowed + ? WHERE user_id = ? AND balance >= ?')
+                    .run(stake, stake, user.id, stake);
+                if (d.changes !== 1)
+                    throw new Error('CLAIM_INSUFFICIENT_BALANCE');
+                const o = db.prepare(`UPDATE orders SET has_pending_claim = 1 WHERE id = ? AND (has_pending_claim IS NULL OR has_pending_claim != 1) AND status NOT IN ('created','cancelled','completed','refunded')`).run(req.params.id);
+                if (o.changes !== 1)
+                    throw new Error('CLAIM_ORDER_BLOCKED');
+            })();
+        }
+        catch (e) {
+            const m = e.message;
+            if (m === 'CLAIM_EXISTS')
+                return void res.status(409).json({ error: '该订单已存在验证任务（不可撤销）' });
+            if (m === 'CLAIM_INSUFFICIENT_BALANCE')
+                return void res.status(400).json({ error: `余额不足：发起需锁 ${stake} WAZ` });
+            if (m === 'CLAIM_ORDER_BLOCKED')
+                return void res.status(400).json({ error: `当前订单状态不可发起验证（${BLOCKED.join('/')} 或已挂验证）` });
+            throw e;
+        }
+        const productTitle = (await dbOne('SELECT title FROM products WHERE id = ?', [order.product_id]))?.title || '—';
         const claimLabel = CLAIM_TARGET_LABEL_ZH[claim_target] || claim_target;
         try {
-            db.prepare(`INSERT INTO notifications (id, user_id, type, title, body, order_id) VALUES (?,?,?,?,?,?)`)
-                .run(generateId('ntf'), sellerId, 'claim_new', `⚠️ 买家发起验证：${claimLabel}`, `订单「${productTitle}」 — 48h 内提交证据可延期至 verifier 共识结案`, req.params.id);
+            await dbRun(`INSERT INTO notifications (id, user_id, type, title, body, order_id) VALUES (?,?,?,?,?,?)`, [generateId('ntf'), sellerId, 'claim_new',
+                `⚠️ 买家发起验证：${claimLabel}`,
+                `订单「${productTitle}」 — 48h 内提交证据可延期至 verifier 共识结案`,
+                req.params.id]);
         }
         catch (e) {
             console.error('[V2 notify seller]', e.message);
@@ -341,25 +376,23 @@ export function registerClaimVerifyRoutes(app, deps) {
         res.json({ success: true, task_id: id, deadline_at: deadline, stake_locked: stake });
     });
     // 通过 order_id 查关联 task
-    app.get('/api/orders/:id/claim-task', (req, res) => {
+    app.get('/api/orders/:id/claim-task', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        const task = db.prepare('SELECT * FROM claim_verification_tasks WHERE order_id = ?')
-            .get(req.params.id);
+        const task = await dbOne('SELECT * FROM claim_verification_tasks WHERE order_id = ?', [req.params.id]);
         if (!task)
             return void res.json({ task: null });
-        const hasVoted = db.prepare('SELECT id FROM claim_verification_votes WHERE task_id = ? AND verifier_id = ?')
-            .get(task.id, user.id);
+        const hasVoted = await dbOne('SELECT id FROM claim_verification_votes WHERE task_id = ? AND verifier_id = ?', [task.id, user.id]);
         const isParty = task.buyer_id === user.id || task.seller_id === user.id;
         const elig = isEligibleClaimVerifier(db, user.id);
         if (!isParty && !hasVoted && !elig.ok)
             return void res.json({ task: null, visibility: 'restricted' });
-        const votes = db.prepare(`SELECT verifier_id, vote, voted_at FROM claim_verification_votes WHERE task_id = ? ORDER BY voted_at ASC`).all(task.id);
+        const votes = await dbAll(`SELECT verifier_id, vote, voted_at FROM claim_verification_votes WHERE task_id = ? ORDER BY voted_at ASC`, [task.id]);
         res.json({ task, votes, votes_needed: CLAIM_VERIFIERS_NEEDED });
     });
     // 列出可接的 open 任务
-    app.get('/api/claim-tasks/available', (req, res) => {
+    app.get('/api/claim-tasks/available', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
@@ -370,7 +403,7 @@ export function registerClaimVerifyRoutes(app, deps) {
         if (active >= CLAIM_VERIFIER_MAX_ACTIVE) {
             return void res.status(429).json({ error: `已有 ${active} 个进行中任务（上限 ${CLAIM_VERIFIER_MAX_ACTIVE}），请先完成`, active });
         }
-        const rows = db.prepare(`
+        const rows = await dbAll(`
       SELECT cvt.id, cvt.order_id, cvt.product_id, cvt.claim_target, cvt.claim_text,
              cvt.evidence_uri, cvt.seller_evidence_uri, cvt.deadline_at, cvt.created_at,
              (SELECT COUNT(*) FROM claim_verification_votes WHERE task_id = cvt.id AND vote != 'abstain') as votes_count,
@@ -383,11 +416,11 @@ export function registerClaimVerifyRoutes(app, deps) {
         AND (SELECT COUNT(*) FROM claim_verification_votes WHERE task_id = cvt.id AND vote != 'abstain') < ?
       ORDER BY cvt.created_at ASC
       LIMIT 50
-    `).all(user.id, user.id, user.id, CLAIM_VERIFIERS_NEEDED);
+    `, [user.id, user.id, user.id, CLAIM_VERIFIERS_NEEDED]);
         res.json({ eligible: true, via: elig.via, active, max_active: CLAIM_VERIFIER_MAX_ACTIVE, tasks: rows });
     });
     // verifier 投票 — 铁律 §4
-    app.post('/api/claim-tasks/:id/vote', (req, res) => {
+    app.post('/api/claim-tasks/:id/vote', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
@@ -401,7 +434,7 @@ export function registerClaimVerifyRoutes(app, deps) {
         });
         if (!hpCheck.ok)
             return void res.status(412).json({ error: hpCheck.reason, error_code: hpCheck.error_code });
-        const task = db.prepare('SELECT * FROM claim_verification_tasks WHERE id = ?').get(req.params.id);
+        const task = await dbOne('SELECT * FROM claim_verification_tasks WHERE id = ?', [req.params.id]);
         if (!task)
             return void res.status(404).json({ error: '任务不存在' });
         if (task.status !== 'open')
@@ -416,8 +449,7 @@ export function registerClaimVerifyRoutes(app, deps) {
         }
         const evidence_uri = req.body?.evidence_uri ? String(req.body.evidence_uri).trim().slice(0, 500) : null;
         const note = req.body?.note ? String(req.body.note).trim().slice(0, 500) : null;
-        const dup = db.prepare('SELECT id FROM claim_verification_votes WHERE task_id = ? AND verifier_id = ?')
-            .get(req.params.id, user.id);
+        const dup = await dbOne('SELECT id FROM claim_verification_votes WHERE task_id = ? AND verifier_id = ?', [req.params.id, user.id]);
         if (dup)
             return void res.status(409).json({ error: '已投过票' });
         const votesNow = db.prepare(`SELECT COUNT(*) as n FROM claim_verification_votes WHERE task_id = ? AND vote != 'abstain'`)
@@ -452,42 +484,42 @@ export function registerClaimVerifyRoutes(app, deps) {
         });
     });
     // 我相关的任务（必须在 /:id 之前注册，否则被 /:id 截获）
-    app.get('/api/claim-tasks/mine', (req, res) => {
+    app.get('/api/claim-tasks/mine', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        const asBuyer = db.prepare(`SELECT id, order_id, product_id, claim_target, status, deadline_at, created_at
-      FROM claim_verification_tasks WHERE buyer_id = ? ORDER BY created_at DESC LIMIT 50`).all(user.id);
-        const asSeller = db.prepare(`SELECT id, order_id, product_id, claim_target, status, deadline_at, created_at
-      FROM claim_verification_tasks WHERE seller_id = ? ORDER BY created_at DESC LIMIT 50`).all(user.id);
-        const asVerifier = db.prepare(`
+        const asBuyer = await dbAll(`SELECT id, order_id, product_id, claim_target, status, deadline_at, created_at
+      FROM claim_verification_tasks WHERE buyer_id = ? ORDER BY created_at DESC LIMIT 50`, [user.id]);
+        const asSeller = await dbAll(`SELECT id, order_id, product_id, claim_target, status, deadline_at, created_at
+      FROM claim_verification_tasks WHERE seller_id = ? ORDER BY created_at DESC LIMIT 50`, [user.id]);
+        const asVerifier = await dbAll(`
       SELECT cvt.id, cvt.order_id, cvt.product_id, cvt.claim_target, cvt.status, cvt.deadline_at, cvt.created_at,
              cvv.vote, cvv.voted_at
       FROM claim_verification_votes cvv
       JOIN claim_verification_tasks cvt ON cvt.id = cvv.task_id
       WHERE cvv.verifier_id = ?
       ORDER BY cvv.voted_at DESC
-      LIMIT 50`).all(user.id);
+      LIMIT 50`, [user.id]);
         res.json({ as_buyer: asBuyer, as_seller: asSeller, as_verifier: asVerifier });
     });
     // 通知偏好
-    app.post('/api/me/notify-claim-tasks', (req, res) => {
+    app.post('/api/me/notify-claim-tasks', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
         const enabled = req.body?.enabled === false ? 0 : 1;
-        db.prepare('UPDATE users SET notify_claim_tasks = ? WHERE id = ?').run(enabled, user.id);
+        await dbRun('UPDATE users SET notify_claim_tasks = ? WHERE id = ?', [enabled, user.id]);
         res.json({ success: true, notify_claim_tasks: enabled });
     });
-    app.get('/api/me/notify-claim-tasks', (req, res) => {
+    app.get('/api/me/notify-claim-tasks', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        const row = db.prepare('SELECT COALESCE(notify_claim_tasks, 1) as enabled FROM users WHERE id = ?').get(user.id);
+        const row = await dbOne('SELECT COALESCE(notify_claim_tasks, 1) as enabled FROM users WHERE id = ?', [user.id]);
         res.json({ notify_claim_tasks: row?.enabled ?? 1 });
     });
     // 公开 #claims 广场（无 auth — 透明性是验证声明信任的前提）
-    app.get('/api/claims/public', (req, res) => {
+    app.get('/api/claims/public', async (req, res) => {
         const status = String(req.query.status || 'open');
         const limit = Math.min(50, Math.max(1, Number(req.query.limit) || 30));
         let where;
@@ -508,7 +540,7 @@ export function registerClaimVerifyRoutes(app, deps) {
             where = `1=1`;
             orderBy = `cvt.created_at DESC`;
         }
-        const rows = db.prepare(`
+        const rows = await dbAll(`
       SELECT cvt.id, cvt.order_id, cvt.product_id, cvt.claim_target,
              SUBSTR(cvt.claim_text, 1, 140) as claim_excerpt,
              cvt.evidence_uri IS NOT NULL as has_buyer_evidence,
@@ -522,7 +554,7 @@ export function registerClaimVerifyRoutes(app, deps) {
       WHERE ${where}
       ORDER BY ${orderBy}
       LIMIT ?
-    `).all(limit);
+    `, [limit]);
         const items = rows.map(r => {
             let firstImage = null;
             try {
@@ -553,33 +585,30 @@ export function registerClaimVerifyRoutes(app, deps) {
         res.json({ items, votes_needed: CLAIM_VERIFIERS_NEEDED });
     });
     // 任务详情
-    app.get('/api/claim-tasks/:id', (req, res) => {
+    app.get('/api/claim-tasks/:id', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        const task = db.prepare('SELECT * FROM claim_verification_tasks WHERE id = ?')
-            .get(req.params.id);
+        const task = await dbOne('SELECT * FROM claim_verification_tasks WHERE id = ?', [req.params.id]);
         if (!task)
             return void res.status(404).json({ error: '任务不存在' });
-        const hasVoted = db.prepare('SELECT id FROM claim_verification_votes WHERE task_id = ? AND verifier_id = ?')
-            .get(req.params.id, user.id);
+        const hasVoted = await dbOne('SELECT id FROM claim_verification_votes WHERE task_id = ? AND verifier_id = ?', [req.params.id, user.id]);
         const isParty = task.buyer_id === user.id || task.seller_id === user.id;
         const elig = isEligibleClaimVerifier(db, user.id);
         const canRead = isParty || !!hasVoted || elig.ok;
         if (!canRead) {
             return void res.status(403).json({ error: '仅当事人或已投票 / 资格内 verifier 可见任务详情' });
         }
-        const votes = db.prepare(`SELECT id, verifier_id, vote, evidence_uri, note, voted_at
-      FROM claim_verification_votes WHERE task_id = ? ORDER BY voted_at ASC`).all(req.params.id);
+        const votes = await dbAll(`SELECT id, verifier_id, vote, evidence_uri, note, voted_at
+      FROM claim_verification_votes WHERE task_id = ? ORDER BY voted_at ASC`, [req.params.id]);
         res.json({ task, votes, votes_needed: CLAIM_VERIFIERS_NEEDED });
     });
     // 卖家提交证据 → 延期 24h；状态保持 open
-    app.post('/api/claim-tasks/:id/seller-evidence', (req, res) => {
+    app.post('/api/claim-tasks/:id/seller-evidence', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        const task = db.prepare('SELECT * FROM claim_verification_tasks WHERE id = ?')
-            .get(req.params.id);
+        const task = await dbOne('SELECT * FROM claim_verification_tasks WHERE id = ?', [req.params.id]);
         if (!task)
             return void res.status(404).json({ error: '任务不存在' });
         if (task.seller_id !== user.id)
@@ -595,11 +624,15 @@ export function registerClaimVerifyRoutes(app, deps) {
         const oldDeadline = new Date(String(task.deadline_at)).getTime();
         const newCandidate = Date.now() + CLAIM_SELLER_EXTENSION_HOURS * 3600_000;
         const newDeadline = new Date(Math.max(oldDeadline, newCandidate)).toISOString();
-        db.prepare(`UPDATE claim_verification_tasks
+        // Codex #237 P2:await 预检与写之间 task 可能被结算/并发提证;status='open' + seller_evidence_at IS NULL
+        // 守卫保证只在仍 open 且未提交过时写,changes===0 → 409。
+        const ev = await dbRun(`UPDATE claim_verification_tasks
       SET seller_evidence_uri = ?, seller_evidence_at = datetime('now'), deadline_at = ?
-      WHERE id = ?`).run(evidence_uri, newDeadline, req.params.id);
+      WHERE id = ? AND status = 'open' AND seller_evidence_at IS NULL`, [evidence_uri, newDeadline, req.params.id]);
+        if (ev.changes === 0)
+            return void res.status(409).json({ error: '任务状态已变更或已提交过证据（请刷新）' });
         try {
-            const productTitle = db.prepare('SELECT title FROM products WHERE id = ?').get(task.product_id)?.title || '—';
+            const productTitle = (await dbOne('SELECT title FROM products WHERE id = ?', [task.product_id]))?.title || '—';
             const claimLabel = CLAIM_TARGET_LABEL_ZH[String(task.claim_target)] || String(task.claim_target);
             notifyEligibleVerifiers(db, generateId, {
                 taskId: String(task.id), productTitle, claimTargetLabel: claimLabel,

package/dist/pwa/routes/claim-voting.js

@@ -1,9 +1,13 @@
+import { dbOne, dbAll } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
 export function registerClaimVotingRoutes(app, deps) {
+    // 只读站点走 RFC-016 异步 seam;db 保留:vote 是"投票→封顶→结算"裁决资金路径,
+    // dup 门 + INSERT vote + 计票 + seal-CAS 必须原子(db.transaction);settle(发还/没收质押)
+    // 在 tx 提交后只对真正 seal 的那一票触发,防并发双封顶/双结算。Phase 3 迁 pg 行锁。
     const { db, auth, isEligibleClaimVerifier, generateId, settleProductClaim, settleGenericClaim, PRODUCT_CLAIM_VERIFIERS_NEEDED, REVIEW_VERIFIERS_NEEDED } = deps;
     const wire = (cfg) => {
         const { vertical, taskTable, voteTable, taskAlias: a, partyIdCol, votePrefix, votesNeeded } = cfg;
         // GET /api/<vertical>-claims/available
-        app.get(`/api/${vertical}-claims/available`, (req, res) => {
+        app.get(`/api/${vertical}-claims/available`, async (req, res) => {
             const user = auth(req, res);
             if (!user)
                 return;
@@ -22,18 +26,18 @@ export function registerClaimVotingRoutes(app, deps) {
           AND (SELECT COUNT(*) FROM ${voteTable} WHERE claim_id = ${a}.id) < ${votesNeeded}
         ORDER BY ${a}.created_at ASC LIMIT 50
       `;
-            const rows = db.prepare(sql).all(user.id, user.id, user.id);
+            const rows = await dbAll(sql, [user.id, user.id, user.id]);
             res.json({ items: rows, eligible: true });
         });
         // POST /api/<vertical>-claims/:id/vote
-        app.post(`/api/${vertical}-claims/:id/vote`, (req, res) => {
+        app.post(`/api/${vertical}-claims/:id/vote`, async (req, res) => {
             const user = auth(req, res);
             if (!user)
                 return;
             const elig = isEligibleClaimVerifier(user.id);
             if (!elig.ok)
                 return void res.status(403).json({ error: elig.reason });
-            const claim = db.prepare(`SELECT * FROM ${taskTable} WHERE id = ?`).get(req.params.id);
+            const claim = await dbOne(`SELECT * FROM ${taskTable} WHERE id = ?`, [req.params.id]);
             if (!claim)
                 return void res.status(404).json({ error: '声明不存在' });
             if (claim.status !== 'open')
@@ -45,29 +49,50 @@ export function registerClaimVotingRoutes(app, deps) {
             if (!['upheld', 'dismissed', 'insufficient'].includes(vote)) {
                 return void res.status(400).json({ error: `vote 须为 upheld / dismissed / insufficient` });
             }
-            const dup = db.prepare(`SELECT id FROM ${voteTable} WHERE claim_id = ? AND verifier_id = ?`).get(req.params.id, user.id);
-            if (dup)
-                return void res.status(409).json({ error: '已投过票' });
-            const votesNow = db.prepare(`SELECT COUNT(*) as n FROM ${voteTable} WHERE claim_id = ?`).get(req.params.id).n;
-            if (votesNow >= votesNeeded)
-                return void res.status(409).json({ error: '已收齐共识票数' });
             const evidence_uri = req.body?.evidence_uri ? String(req.body.evidence_uri).trim().slice(0, 500) : null;
             const note = req.body?.note ? String(req.body.note).trim().slice(0, 500) : null;
             const voteId = generateId(votePrefix);
+            // 裁决原子段:权威重检(状态/dup/票数)→ INSERT vote → 重计票 → 达标则 CAS 封顶。
+            // 返回 { after, didSeal };didSeal 仅对真正把 open→sealed 翻过去的那一票为 true。
+            let txOut;
             try {
-                db.prepare(`INSERT INTO ${voteTable} (id, claim_id, verifier_id, vote, evidence_uri, note) VALUES (?,?,?,?,?,?)`)
-                    .run(voteId, req.params.id, user.id, vote, evidence_uri, note);
+                txOut = db.transaction(() => {
+                    const cur = db.prepare(`SELECT status FROM ${taskTable} WHERE id = ?`).get(req.params.id);
+                    if (!cur || cur.status !== 'open')
+                        throw new Error('VOTE_CLOSED');
+                    if (db.prepare(`SELECT id FROM ${voteTable} WHERE claim_id = ? AND verifier_id = ?`).get(req.params.id, user.id))
+                        throw new Error('VOTE_DUP');
+                    const now = db.prepare(`SELECT COUNT(*) as n FROM ${voteTable} WHERE claim_id = ?`).get(req.params.id).n;
+                    if (now >= votesNeeded)
+                        throw new Error('VOTE_FULL');
+                    db.prepare(`INSERT INTO ${voteTable} (id, claim_id, verifier_id, vote, evidence_uri, note) VALUES (?,?,?,?,?,?)`)
+                        .run(voteId, req.params.id, user.id, vote, evidence_uri, note);
+                    const after = db.prepare(`SELECT COUNT(*) as n FROM ${voteTable} WHERE claim_id = ?`).get(req.params.id).n;
+                    let didSeal = false;
+                    if (after >= votesNeeded) {
+                        const seal = db.prepare(`UPDATE ${taskTable} SET status = 'sealed' WHERE id = ? AND status = 'open'`).run(req.params.id);
+                        didSeal = seal.changes === 1;
+                    }
+                    return { after, didSeal };
+                })();
             }
-            catch {
-                return void res.status(409).json({ error: '投票失败（可能并发重复）' });
+            catch (e) {
+                const msg = e.message;
+                if (msg === 'VOTE_CLOSED')
+                    return void res.status(400).json({ error: '该声明已结案,不接受投票' });
+                if (msg === 'VOTE_DUP')
+                    return void res.status(409).json({ error: '已投过票' });
+                if (msg === 'VOTE_FULL')
+                    return void res.status(409).json({ error: '已收齐共识票数' });
+                console.error('[claim-voting tx]', msg);
+                return void res.status(500).json({ error: '投票失败,请重试' });
             }
-            const after = db.prepare(`SELECT COUNT(*) as n FROM ${voteTable} WHERE claim_id = ?`).get(req.params.id).n;
+            // settle(发还/没收质押)在事务提交后只对真正 seal 的那一票触发(它自身另起事务)。
             let settlement = null;
-            if (after >= votesNeeded) {
-                db.prepare(`UPDATE ${taskTable} SET status = 'sealed' WHERE id = ? AND status = 'open'`).run(req.params.id);
+            if (txOut.didSeal) {
                 settlement = cfg.useProductSettle ? settleProductClaim(req.params.id) : settleGenericClaim(taskTable, voteTable, req.params.id);
             }
-            res.json({ success: true, votes_collected: after, sealed: after >= votesNeeded, settlement });
+            res.json({ success: true, votes_collected: txOut.after, sealed: txOut.didSeal, settlement });
         });
     };
     // 5 个垂类配置

package/dist/pwa/routes/contribution-identity.js

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+import { issueGithubIdentityClaimChallenge, getIssuedChallengeForVerification, } from '../../layer2-business/L2-9-contribution/identity-claim-challenge-engine.js';
+import { verifyGithubGistProof } from '../../layer2-business/L2-9-contribution/identity-claim-proof-verifier.js';
+import { claimGithubIdentity } from '../../layer2-business/L2-9-contribution/identity-claim-engine.js';
+import { getMyGithubIdentitySurface } from '../../layer2-business/L2-9-contribution/identity-claim-read.js';
+import { withUncommittedValueBoundary } from '../../layer2-business/L2-9-contribution/contribution-display-envelope.js';
+// ── strict request bodies (unknown/sensitive keys → rejected; nothing trusts a caller field) ──
+const ChallengeBody = z.strictObject({
+    source_event_key: z.string().min(1),
+    github_actor_id: z.string().min(1),
+});
+const CompleteBody = z.strictObject({
+    source_event_key: z.string().min(1),
+    github_actor_id: z.string().min(1),
+    challenge_id: z.string().min(1),
+    gist_id: z.string().min(1),
+    webauthn_token: z.string().min(1), // one-time WebAuthn gate token id (purpose 'identity_claim')
+});
+const PARAM_KEY = 'require_human_presence_for_identity_claim';
+export function registerContributionIdentityRoutes(app, deps) {
+    const { auth, requireHumanPresence, errorRes, getGithubReadToken } = deps;
+    // ── 1) issue a publication challenge ─────────────────────────────────────────────────────────
+    app.post('/api/contribution-identity/github/claim-challenge', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const parsed = ChallengeBody.safeParse(req.body ?? {});
+        if (!parsed.success)
+            return void errorRes(res, 400, 'INVALID_REQUEST', '请求参数无效');
+        // accountId is ALWAYS the session user (never the body).
+        const r = await issueGithubIdentityClaimChallenge({
+            accountId: user.id,
+            githubActorId: parsed.data.github_actor_id,
+            sourceEventKey: parsed.data.source_event_key,
+        });
+        if (r.ok && r.status === 'issued') {
+            return void res.json({ status: 'issued', challenge_id: r.challenge_id, expires_at: r.expires_at, proof_marker: r.proof_marker });
+        }
+        if (r.ok && r.status === 'already_bound_self') {
+            return void res.json({ status: 'already_bound_self', github_actor_id: r.github_actor_id });
+        }
+        // refused — map to a status without leaking internals.
+        switch (r.reason) {
+            case 'invalid_request': return void errorRes(res, 400, 'INVALID_REQUEST', '请求参数无效');
+            case 'fact_not_found': return void errorRes(res, 404, 'FACT_NOT_CLAIMABLE', '没有可认领的、经凭证背书的 GitHub 贡献记录');
+            case 'actor_mismatch': return void errorRes(res, 403, 'ACTOR_MISMATCH', '该贡献记录的执行者与所声明的 GitHub 身份不符');
+            case 'already_bound_other': return void errorRes(res, 409, 'ALREADY_BOUND', '该 GitHub 身份已被其他账号认领');
+            case 'backend_unsupported': return void errorRes(res, 503, 'BACKEND_UNSUPPORTED', '当前后端暂不支持身份认领');
+            case 'db_busy': return void errorRes(res, 503, 'DB_BUSY', '系统繁忙，请稍后重试');
+            default: return void errorRes(res, 500, 'INTERNAL', '内部错误');
+        }
+    });
+    // ── 2) complete the claim (human gate → re-fetch gist proof → atomic consume+bind) ────────────
+    app.post('/api/contribution-identity/github/claim-complete', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const parsed = CompleteBody.safeParse(req.body ?? {});
+        if (!parsed.success)
+            return void errorRes(res, 400, 'INVALID_REQUEST', '请求参数无效');
+        const { source_event_key, github_actor_id, challenge_id, gist_id, webauthn_token } = parsed.data;
+        const userId = user.id;
+        // Server-config precondition FIRST — don't burn the one-time human gate token if the server can't
+        // perform the authenticated GitHub read (fail closed; issuing a challenge never needs a token).
+        const githubToken = getGithubReadToken();
+        if (!githubToken)
+            return void errorRes(res, 503, 'GITHUB_READ_NOT_CONFIGURED', '身份认领暂不可用');
+        // ① human presence — the gate token must be bound (purpose_data) to THIS exact claim tuple, so a
+        //    token minted for one claim cannot complete another, and an agent cannot replay it.
+        const hp = requireHumanPresence(userId, 'identity_claim', webauthn_token, PARAM_KEY, (data) => {
+            const d = data;
+            return !!d && d.github_actor_id === github_actor_id && d.source_event_key === source_event_key && d.challenge_id === challenge_id;
+        });
+        if (!hp.ok)
+            return void errorRes(res, 412, hp.error_code || 'HUMAN_PRESENCE_REQUIRED', hp.reason || '此操作需真实人工 WebAuthn 验证');
+        // ② confirm the challenge is issued/owned/unexpired and fetch the stored nonce_hash (read-only;
+        //    BEFORE the network call so a bad challenge never triggers a GitHub fetch). Not consumed here.
+        const look = getIssuedChallengeForVerification({ challengeId: challenge_id, accountId: userId, githubActorId: github_actor_id, sourceEventKey: source_event_key });
+        if (!look.ok) {
+            switch (look.reason) {
+                case 'challenge_not_found': return void errorRes(res, 404, 'CHALLENGE_NOT_FOUND', '认领挑战不存在或不属于当前账号');
+                case 'challenge_expired': return void errorRes(res, 410, 'CHALLENGE_EXPIRED', '认领挑战已过期，请重新发起');
+                case 'challenge_already_used': return void errorRes(res, 409, 'CHALLENGE_ALREADY_USED', '认领挑战已被使用');
+                case 'backend_unsupported': return void errorRes(res, 503, 'BACKEND_UNSUPPORTED', '当前后端暂不支持身份认领');
+                default: return void errorRes(res, 400, 'INVALID_REQUEST', '请求参数无效');
+            }
+        }
+        // ③ WebAZ re-fetches the gist itself (trusted token from config; NEVER the body) and verifies
+        //    owner.id == actor + marker + sha256(nonce) == stored nonce_hash. A failure here does NOT consume
+        //    the challenge (F2 is not called) — the user can fix the gist and retry.
+        const proof = await verifyGithubGistProof({
+            gistId: gist_id,
+            githubActorId: github_actor_id,
+            challengeId: challenge_id,
+            expectedNonceHash: look.nonceHash,
+            token: githubToken,
+        });
+        if (!proof.ok) {
+            // Surface only the typed outcome (verifier guarantees its reasons are token-free; we don't echo them).
+            const code = proof.outcome === 'rate_limited' ? 429
+                : proof.outcome === 'timeout' || proof.outcome === 'upstream_unavailable' ? 502
+                    : proof.outcome === 'not_found' ? 404
+                        : proof.outcome === 'invalid_request' ? 400
+                            : 422;
+            return void errorRes(res, code, 'PROOF_REJECTED', '未能验证 GitHub 公开发布凭证', { proof_outcome: proof.outcome });
+        }
+        // ④ atomic consume(CAS) + bind — proofVerified:true; accountId is the session user.
+        const claim = await claimGithubIdentity({
+            accountId: userId,
+            githubActorId: github_actor_id,
+            sourceEventKey: source_event_key,
+            challengeId: challenge_id,
+            proofVerified: true,
+        });
+        if (claim.ok) {
+            return void res.json({ status: claim.status, github_actor_id: claim.github_actor_id, challenge_id: claim.challenge_id });
+        }
+        switch (claim.reason) {
+            case 'already_bound_other': return void errorRes(res, 409, 'ALREADY_BOUND', '该 GitHub 身份已被其他账号认领');
+            case 'challenge_already_used': return void errorRes(res, 409, 'CHALLENGE_ALREADY_USED', '认领挑战已被使用');
+            case 'challenge_expired': return void errorRes(res, 410, 'CHALLENGE_EXPIRED', '认领挑战已过期，请重新发起');
+            case 'challenge_not_found': return void errorRes(res, 404, 'CHALLENGE_NOT_FOUND', '认领挑战不存在或不属于当前账号');
+            case 'fact_not_found': return void errorRes(res, 404, 'FACT_NOT_CLAIMABLE', '没有可认领的、经凭证背书的 GitHub 贡献记录');
+            case 'actor_mismatch': return void errorRes(res, 403, 'ACTOR_MISMATCH', '该贡献记录的执行者与所声明的 GitHub 身份不符');
+            case 'backend_unsupported': return void errorRes(res, 503, 'BACKEND_UNSUPPORTED', '当前后端暂不支持身份认领');
+            case 'db_busy': return void errorRes(res, 503, 'DB_BUSY', '系统繁忙，请稍后重试');
+            default: return void errorRes(res, 500, 'INTERNAL', '内部错误'); // proof_not_verified / invariant_violation
+        }
+    });
+    // ── 3) READ-ONLY: the caller's OWN bindings + attributable facts (PR-F4) ──────────────────────
+    // No query/body input is read — accountId is ALWAYS the session user, so a caller cannot ask about
+    // another account or github_actor_id. Returns no other account's id, no token/nonce/nonce_hash.
+    // PR-5A: the response is wrapped in the uncommitted-value boundary (RFC-017 I-12 / §7) so this
+    // metering/display surface can never read as a payout promise — facts + attribution only.
+    app.get('/api/contribution-identity/github/me', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        try {
+            const surface = await getMyGithubIdentitySurface(user.id);
+            res.json(withUncommittedValueBoundary(surface));
+        }
+        catch {
+            return void errorRes(res, 500, 'INTERNAL', '内部错误'); // never leak a stack / query
+        }
+    });
+}

package/dist/pwa/routes/contribution-score.js

@@ -0,0 +1,19 @@
+import { collectContributionScoreEvidence } from '../../layer2-business/L2-9-contribution/contribution-score-evidence.js';
+import { withUncommittedValueBoundary } from '../../layer2-business/L2-9-contribution/contribution-display-envelope.js';
+export function registerContributionScoreRoutes(app, deps) {
+    const { auth, errorRes } = deps;
+    // READ-ONLY self-view of contribution-score EVIDENCE (not a score). No query/body input — accountId is
+    // always the session user. Output is component evidence wrapped in the uncommitted-value boundary.
+    app.get('/api/contribution-score/evidence/me', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        try {
+            const components = await collectContributionScoreEvidence(user.id);
+            res.json(withUncommittedValueBoundary({ evidence_version: 'v1', components }));
+        }
+        catch {
+            return void errorRes(res, 500, 'INTERNAL', '内部错误'); // never leak a stack / query
+        }
+    });
+}