@seasonkoh/webaz 0.1.28 → 0.1.29

package/dist/pwa/routes/rewards-clearing-mature.js

@@ -0,0 +1,96 @@
+// RFC-016 Phase 1 — sweep read → async seam; the per-row pay tx stays sync (Phase 3 → pg).
+import { dbAll } from '../../layer0-foundation/L0-1-database/db.js';
+import { generateId } from '../../layer0-foundation/L0-1-database/schema.js';
+import { applyWalletDelta } from '../../ledger.js';
+import { toUnits, toDecimal } from '../../money.js';
+// #7 Commission source_type (moved from settleCommission). Pure read — stamps commission_records.source_type.
+function commissionSourceType(db, productId, uid) {
+    if (!uid)
+        return 'sponsor';
+    const attr = db.prepare(`SELECT shareable_id FROM product_share_attribution WHERE product_id = ? AND sharer_id = ? AND shareable_id IS NOT NULL ORDER BY created_at DESC LIMIT 1`).get(productId, uid);
+    if (!attr)
+        return 'sponsor';
+    const sh = db.prepare(`SELECT type FROM shareables WHERE id = ?`).get(attr.shareable_id);
+    if (!sh)
+        return 'sponsor';
+    return sh.type === 'note' ? 'note' : 'link';
+}
+/**
+ * Mature ONE clearing commission row. Re-validates genuine closure (completed + no open dispute), then
+ * writes commission_records + credits the wallet in one tx. CAS on status='pending' → idempotent; races
+ * and re-runs lose. Holds (no write) while a dispute is open. Exported for direct unit testing.
+ */
+export function matureClearingRow(db, row) {
+    let outcome = 'skipped';
+    db.transaction(() => {
+        const order = db.prepare("SELECT buyer_id, product_id, snapshot_commission_rate, buyer_region, status FROM orders WHERE id = ?").get(row.order_id);
+        if (!order || order.status !== 'completed') {
+            outcome = 'held';
+            return;
+        } // completed is terminal; defensive hold
+        const openDispute = db.prepare("SELECT 1 FROM disputes WHERE order_id = ? AND status NOT IN ('resolved','dismissed','closed') LIMIT 1").get(row.order_id);
+        if (openDispute) {
+            outcome = 'held';
+            return;
+        } // hold while unresolved (e.g. return escalated to dispute)
+        const claimed = db.prepare("UPDATE pending_commission_escrow SET status='settled', settled_at=? WHERE id=? AND status='pending' AND matures_at IS NOT NULL").run(Date.now(), row.id);
+        if (claimed.changes !== 1) {
+            outcome = 'skipped';
+            return;
+        } // race lost / already settled / reversed
+        const amountU = toUnits(Number(row.amount));
+        if (amountU > 0) {
+            const level = Number(String(row.attribution_path).replace(/^L/, '')) || 0;
+            const rate = Number(order.snapshot_commission_rate ?? 0.10);
+            let region = order.buyer_region || null;
+            if (!region)
+                region = db.prepare("SELECT region FROM users WHERE id = ?").get(order.buyer_id)?.region ?? 'global';
+            const srcType = commissionSourceType(db, order.product_id, row.recipient_user_id);
+            try {
+                db.prepare(`INSERT INTO commission_records (id, order_id, beneficiary_id, source_buyer_id, level, amount, rate, region, source, source_type) VALUES (?,?,?,?,?,?,?,?,?,?)`)
+                    .run(generateId('comm'), row.order_id, row.recipient_user_id, order.buyer_id, level, toDecimal(amountU), rate, region, 'static', srcType);
+            }
+            catch (e) { /* UNIQUE — already recorded on a prior partial run */ }
+            applyWalletDelta(db, row.recipient_user_id, { balance: amountU, earned: amountU });
+        }
+        outcome = 'settled';
+    })();
+    return outcome;
+}
+export async function runClearingMatureSweep(deps) {
+    const { db } = deps;
+    const now = Date.now();
+    const rows = await dbAll(`
+    SELECT id, recipient_user_id, order_id, amount, attribution_path
+    FROM pending_commission_escrow
+    WHERE status = 'pending' AND matures_at IS NOT NULL AND matures_at <= ?
+    ORDER BY matures_at ASC
+    LIMIT 1000
+  `, [now]);
+    let settled = 0, held = 0, skipped = 0;
+    for (const r of rows) {
+        const o = matureClearingRow(db, r);
+        if (o === 'settled')
+            settled++;
+        else if (o === 'held')
+            held++;
+        else
+            skipped++;
+    }
+    return { scanned: rows.length, settled, held, skipped };
+}
+export function startClearingMatureCron(deps) {
+    const ms = 60 * 60 * 1000; // 1h — clearing window granularity is days
+    setInterval(async () => {
+        try {
+            const r = await runClearingMatureSweep(deps);
+            if (r.settled > 0 || r.held > 0) {
+                console.log(`[clearing-mature] scanned ${r.scanned}, settled ${r.settled}, held ${r.held}, skipped ${r.skipped}`);
+            }
+        }
+        catch (e) {
+            console.error('[clearing-mature-cron]', e);
+        }
+    }, ms);
+    console.log('⏳ RFC-018 commission clearing maturation cron 已启动 (每 1h, anchor=matures_at)');
+}

package/dist/pwa/routes/rewards-escrow-expire.js

@@ -3,17 +3,21 @@ import { dbAll } from '../../layer0-foundation/L0-1-database/db.js';
 export async function runEscrowExpireSweep(deps) {
     const { db, redirectToCommissionReserve } = deps;
     const now = Date.now();
+    // RFC-018: pending_commission_escrow now holds TWO lifecycles, discriminated by matures_at:
+    //   - matures_at IS NULL  → opt-out escrow (this cron: expire → commission_reserve / pool).
+    //   - matures_at NOT NULL → clearing rows (the SEPARATE rewards-clearing-mature cron: pay/reverse).
+    // We MUST exclude clearing rows here, or they'd be wrongly expired to the pool instead of paid.
     const rows = await dbAll(`
     SELECT id, recipient_user_id, order_id, amount, attribution_path, expires_at
     FROM pending_commission_escrow
-    WHERE status = 'pending' AND expires_at <= ?
+    WHERE status = 'pending' AND matures_at IS NULL AND expires_at <= ?
     ORDER BY expires_at ASC
     LIMIT 1000
   `, [now]);
     const expired = [];
     for (const r of rows) {
         db.transaction(() => {
-            const upd = db.prepare(`UPDATE pending_commission_escrow SET status='expired', expired_to_charity_at=? WHERE id=? AND status='pending'`).run(now, r.id);
+            const upd = db.prepare(`UPDATE pending_commission_escrow SET status='expired', expired_to_charity_at=? WHERE id=? AND status='pending' AND matures_at IS NULL`).run(now, r.id);
             if (upd.changes === 0)
                 return; // race lost — another sweep already took it
             if (r.attribution_path === 'pv_pair') {

package/dist/pwa/routes/shops.js

@@ -1,4 +1,5 @@
 import { dbOne, dbAll, dbRun } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
+import { genuineSalePredicate } from '../../layer0-foundation/L0-2-state-machine/genuine-sale.js'; // RFC-018 PR4: 真实成交(排除全额退货)
 export function registerShopsRoutes(app, deps) {
     // db 已走 RFC-016 异步 seam(dbOne/dbAll/dbRun),不再直接用 deps.db
     const { auth } = deps;
@@ -20,7 +21,7 @@ export function registerShopsRoutes(app, deps) {
         const sellerId = String(seller.id);
         const products = await dbAll(`
       SELECT p.id, p.title, p.price, p.stock, p.category, p.images, p.has_variants, p.commission_rate,
-        (SELECT COUNT(1) FROM orders o WHERE o.product_id = p.id AND o.status = 'completed') as sales_count
+        (SELECT COUNT(1) FROM orders o WHERE o.product_id = p.id AND ${genuineSalePredicate('o')}) as sales_count
       FROM products p
       WHERE p.seller_id = ? AND p.status = 'active'
       ORDER BY sales_count DESC, p.created_at DESC

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

@@ -119,8 +119,8 @@ export function registerUrlClaimRoutes(app, deps) {
                 db.prepare(`INSERT INTO products (
           id, seller_id, title, description, price, stock, category, stake_amount,
           specs, source_url, handling_hours, return_days, warranty_days,
-          commitment_hash, description_hash, price_hash, hashed_at, status, stake_locked_at
-        ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,'warehouse',datetime('now'))`)
+          commitment_hash, description_hash, price_hash, hashed_at, status, stake_locked_at, currency
+        ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,'warehouse',datetime('now'),'WAZ')`)
                     .run(productId, user.id, title, description, priceNum, Number(stock), category, stakeAmount, specsJson, url, Number(handling_hours), Number(return_days), Number(warranty_days), makeCommitmentHash(pFields), makeDescriptionHash({ title, description, specs: specsJson }), makePriceHash(priceNum, now), now);
                 db.prepare(`INSERT INTO product_external_links
           (id, product_id, url, source, verified, verify_note, platform, external_id, external_title)

package/dist/pwa/routes/users-public.js

@@ -25,6 +25,14 @@ export function registerUsersPublicRoutes(app, deps) {
                 return;
             userId = user.id;
         }
+        else {
+            // ref 三态(usr_xxx / permanent_code / @handle)必须解析为 canonical id;
+            // 漏掉解析会让 @handle/permanent_code 当字面 user_id 去查 → 永远落到默认 'new'。
+            const resolved = await resolveUserId(userId);
+            if (!resolved)
+                return void res.status(404).json({ error: 'user not found' });
+            userId = resolved;
+        }
         const row = await dbOne(`
       SELECT level, MAX(trust_score) as max_score
       FROM agent_reputation WHERE user_id = ?

package/dist/pwa/routes/wallet-read.js

@@ -181,8 +181,11 @@ export function registerWalletReadRoutes(app, deps) {
       FROM orders WHERE seller_id = ? AND status = 'completed'
     `, [user.id]));
         const totalIncome = commMap.l1.total + commMap.l2.total + commMap.l3.total + Number(sales.total);
+        // RFC-018: commission accrued but still in the clearing window (matures into commissions/total_income). Pure read.
+        const clearing = (await dbOne("SELECT COALESCE(SUM(amount),0) as s FROM pending_commission_escrow WHERE recipient_user_id = ? AND matures_at IS NOT NULL AND status = 'pending'", [user.id])).s;
         res.json({
             commissions: commMap,
+            commission_clearing: Number(clearing.toFixed(2)), // RFC-018: accrued, maturing after the return window (not yet paid)
             sales: { count: sales.cnt, total: Number(Number(sales.total).toFixed(2)) },
             total_income: Number(totalIncome.toFixed(2)),
         });

package/dist/pwa/routes/webauthn.js

@@ -74,7 +74,7 @@ export function registerWebauthnRoutes(app, deps) {
         if (!user)
             return;
         const purpose = String(req.body?.purpose || '').trim();
-        const allowed = new Set(['withdraw', 'change-password', 'reveal-key', 'region', 'delete_passkey', 'governance_apply', 'governance_activate', 'governance_resign', 'governance_appeal_resolve', 'rewards_apply', 'rewards_deactivate', 'identity_claim', 'operator_claim_unlink']);
+        const allowed = new Set(['withdraw', 'change-password', 'reveal-key', 'region', 'delete_passkey', 'governance_apply', 'governance_activate', 'governance_resign', 'governance_appeal_resolve', 'rewards_apply', 'rewards_deactivate', 'identity_claim', 'operator_claim_unlink', 'direct_pay_disclosure_ack', 'direct_pay_order_action', 'direct_receive_production_confirm', 'direct_pay_aml_review', 'direct_pay_kyb_ingress', 'direct_pay_sanctions_ingress', 'direct_pay_aml_ingress', 'direct_pay_admin_readiness', 'direct_pay_deferral_approve', 'direct_pay_deferral_reject', 'direct_pay_product_verify', 'direct_pay_store_verify', 'direct_pay_fee_prepay_record', 'direct_pay_fee_adjust', 'direct_pay_fee_refund', 'direct_receive_account_manage']);
         if (!allowed.has(purpose))
             return void res.status(400).json({ error: 'invalid purpose' });
         const purpose_data = req.body?.purpose_data ?? null;

package/dist/pwa/server.js

@@ -22,12 +22,15 @@ 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 { genuineSalePredicate } from '../layer0-foundation/L0-2-state-machine/genuine-sale.js';
+import { settleDirectPayFeeAtCompletion } from '../direct-pay-fee-ar.js'; // RFC-018 PR4 genuine-sale SSOT + Direct Pay Rail 1 平台费链下应收(完成时释放遗留模拟 stake + accrue)
 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';
 // #420 P1-2/P1-3/P1-4 — 反滥用阈值单一真相源（governance-adjustable protocol_params）+ 纯决策函数
 import { ANTI_ABUSE_PARAMS, readAntiAbuseThresholds, agentTrustLevel, agentSybilPenalty, agentStrikeSeverity, verifierOutlierBand } from './anti-abuse-thresholds.js';
+import { DIRECT_PAY_CONTROL_PARAMS, DIRECT_PAY_AML_PARAMS } from '../direct-pay-controls.js'; // PR-4a 控制面 + PR-6D AML 监控 param 默认 seed(均 fail-closed / inert)
 import { initOrderChainSchema, appendOrderEvent, getOrderChain, verifyOrderChain } from '../layer0-foundation/L0-2-state-machine/order-chain.js';
-import { initVerifierWhitelistSchema, initMcpToolCallsSchema, initNotePhotoIndexSchema, initUserWishlistSchema, initProductQaSchema, initCouponsSchema, initAnnouncementsSchema, initProductWaitlistSchema, initFlashSalesSchema, initPublicIdeasSchema, initAuctionRemindersSchema, initEmailSubscriptionsSchema, initFeedbackTicketsSchema, initFeedbackMessagesSchema, initDisputeCasesSchema, initDisputeCommentsSchema, initDisputeCommentRepliesSchema, initShareableCommentsSchema, initDisputeFairnessVotesSchema, initOrderRatingsSchema, initBuyerRatingsSchema, initUserAddressesSchema, initP2pShopsSchema, initShareableLikesSchema, initShareableBookmarksSchema, initShareableTagsSchema, initManifestRegistrySchema, initPeerDirectorySchema, initSignalingQueueSchema, initConversationsSchema, initMessagesSchema, initChatReportsSchema, initQuotaIncreaseApplicationsSchema, initVerifierApplicationsSchema, initArbitratorReviewSchema, initVerifierAppealsSchema, initUserModerationSchema, initAdminAuditLogSchema, initVerificationCodesSchema, initAgentCallLogSchema, initAgentReputationSchema, initAgentDeclarationsSchema, initAgentAttestationsSchema, initAgentStrikesSchema, initAgentRevocationsSchema, initProductAliasesSchema, initRegionChangeLogSchema, initCartItemsSchema, initFollowsSchema, initPushSubscriptionsSchema, initUserSessionsSchema, initUserBlocklistSchema, initImportLogsSchema, initErrorLogSchema, initSecondhandItemsSchema, initProductTrialCampaignsSchema, initProductTrialClaimsSchema, initReturnRequestsSchema, initReturnMessagesSchema, initProductVariantsSchema, initEditorPicksSchema, initKycRecordsSchema, initWebauthnSchema, initClaimVerificationBaseSchema, initClaimVerifierSuspensionsSchema, initProductClaimSchema, initReviewClaimSchema, initSecondhandClaimSchema, initAuctionClaimSchema, initWishClaimSchema, initShareableClickLogSchema, initCommissionAuditLogSchema, initRegistrationAuditLogSchema, initProductExternalLinksBaseSchema, initLinkChallengesSchema, initVerifyTasksSchema, initVerifySubmissionsSchema, initVerifierStatsSchema, initRegisterListSearchColumns } from './server-schema.js';
+import { initVerifierWhitelistSchema, initMcpToolCallsSchema, initNotePhotoIndexSchema, initUserWishlistSchema, initProductQaSchema, initCouponsSchema, initAnnouncementsSchema, initProductWaitlistSchema, initFlashSalesSchema, initPublicIdeasSchema, initAuctionRemindersSchema, initEmailSubscriptionsSchema, initFeedbackTicketsSchema, initFeedbackMessagesSchema, initDisputeCasesSchema, initDisputeCommentsSchema, initDisputeCommentRepliesSchema, initShareableCommentsSchema, initDisputeFairnessVotesSchema, initOrderRatingsSchema, initBuyerRatingsSchema, initUserAddressesSchema, initP2pShopsSchema, initShareableLikesSchema, initShareableBookmarksSchema, initShareableTagsSchema, initManifestRegistrySchema, initPeerDirectorySchema, initSignalingQueueSchema, initConversationsSchema, initMessagesSchema, initChatReportsSchema, initQuotaIncreaseApplicationsSchema, initVerifierApplicationsSchema, initArbitratorReviewSchema, initVerifierAppealsSchema, initUserModerationSchema, initAdminAuditLogSchema, initVerificationCodesSchema, initAgentCallLogSchema, initAgentReputationSchema, initAgentDeclarationsSchema, initAgentAttestationsSchema, initAgentStrikesSchema, initAgentRevocationsSchema, initProductAliasesSchema, initRegionChangeLogSchema, initCartItemsSchema, initFollowsSchema, initPushSubscriptionsSchema, initUserSessionsSchema, initUserBlocklistSchema, initImportLogsSchema, initErrorLogSchema, initSecondhandItemsSchema, initProductTrialCampaignsSchema, initProductTrialClaimsSchema, initReturnRequestsSchema, initReturnMessagesSchema, initProductVariantsSchema, initEditorPicksSchema, initKycRecordsSchema, initWebauthnSchema, initClaimVerificationBaseSchema, initClaimVerifierSuspensionsSchema, initProductClaimSchema, initReviewClaimSchema, initSecondhandClaimSchema, initAuctionClaimSchema, initWishClaimSchema, initShareableClickLogSchema, initCommissionAuditLogSchema, initRegistrationAuditLogSchema, initProductExternalLinksBaseSchema, initLinkChallengesSchema, initVerifyTasksSchema, initVerifySubmissionsSchema, initVerifierStatsSchema, initRegisterListSearchColumns, initPendingCommissionEscrowSchema } from './server-schema.js';
 // RFC-014 PR4 — 正常成交结算走整数 base-units + allocate + 绝对值落库。
 import { toUnits, toDecimal, mulRate, allocate } from '../money.js';
 import { applyWalletDelta, creditColumns } from '../ledger.js';
@@ -84,6 +87,7 @@ import { registerClaimVerifyRoutes, processClaimTaskQueue, isEligibleClaimVerifi
 import { registerFollowsRoutes } from './routes/follows.js';
 // Leaderboard (#1013 Phase 11) — 单 endpoint 8 kinds（products/creators/buyers/sellers/value/agents/arbitrators/verifiers）
 import { registerLeaderboardRoutes } from './routes/leaderboard.js';
+import { registerFxRoutes } from './routes/fx.js'; // FX = display-only USDC→local rates
 // Shareables 互动 (#1013 Phase 12) — click/like/comments/bookmark 8 endpoints
 import { registerShareablesInteractionsRoutes } from './routes/shareables-interactions.js';
 // Shareables CRUD (#1013 Phase 13) — 11 endpoints (notes-photo + create + me + creator-stats + by-* + feed + detail + PATCH + DELETE)
@@ -154,6 +158,8 @@ import { registerArbitratorRoutes } from './routes/arbitrator.js';
 import { registerGovernanceOnboardingRoutes } from './routes/governance-onboarding.js';
 import { startAutoDeactivateCron, runAutoDeactivateSweep } from './routes/governance-auto-deactivate.js';
 import { startEscrowExpireCron } from './routes/rewards-escrow-expire.js';
+import { startDirectPayTimeoutCron } from './routes/direct-pay-timeouts.js';
+import { startClearingMatureCron } from './routes/rewards-clearing-mature.js';
 import { startAutoDowngradeCron } from './routes/rewards-auto-downgrade.js';
 import { registerRewardsApplyRoutes } from './routes/rewards-apply.js';
 // 卖家配额 + 数据中心 (#1013 Phase 45) — 4 user + 3 admin
@@ -242,6 +248,11 @@ import { registerOrdersReadRoutes } from './routes/orders-read.js';
 import { registerOrdersActionRoutes } from './routes/orders-action.js';
 // Orders 下单端点 (#1013 Phase 85) — 1 endpoint (338-line POST /api/orders)
 import { registerOrdersCreateRoutes } from './routes/orders-create.js';
+import { registerDirectPayDisclosureAckRoutes } from './routes/direct-pay-disclosure-acks.js'; // PR-4d: Direct Pay 风险披露 ack 端点(薄 adapter)
+import { registerDirectReceivePaymentInstructionRoutes } from './routes/direct-receive-payment-instructions.js';
+import { registerDirectReceiveAccountsRoutes } from './routes/direct-receive-accounts.js'; // PR-4f-a instruction CRUD + Phase C1 multi-account+QR
+import { registerDirectPayAvailabilityRoutes } from './routes/direct-pay-availability.js'; // PR-4a: Direct Pay 可用性只读(控制面 SSOT)
+import { registerAdminDirectReceiveDepositsRoutes } from './routes/admin-direct-receive-deposits.js'; // PR-4b-3: ROOT 生产保证金 receipt 确认(fail-closed scaffold)
 // Disputes 读端点 (#1013 Phase 86) — 5 endpoints (list/similar/detail/evidence-list/parties)
 import { registerDisputesReadRoutes } from './routes/disputes-read.js';
 // Disputes 写端点 (#1013 Phase 87) — 5 endpoints (respond/arbitrate/add-evidence/evidence-blob/request-evidence)
@@ -389,6 +400,7 @@ initSkillSchema(db);
 initSkillMarketSchema(db);
 initReputationSchema(db);
 initOrderChainSchema(db);
+initPendingCommissionEscrowSchema(db); // RFC-018 PR1: relocated from inline (was ~8250) so all escrow schema is built in this early batch — see helper. matures_at + reversed added (schema-only).
 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)
@@ -917,6 +929,7 @@ const DEFAULT_PARAMS = [
     // #420 P1-2/P1-3/P1-4:反滥用阈值(agent 信任公式 / strike 阶梯 / verifier outlier)→ 治理可调。
     // 默认值 === 抽取前硬编码字面量(单一真相源在 anti-abuse-thresholds.ts;测试强制校验一致)。
     ...ANTI_ABUSE_PARAMS,
+    ...DIRECT_PAY_CONTROL_PARAMS, ...DIRECT_PAY_AML_PARAMS,
 ];
 for (const p of DEFAULT_PARAMS) {
     try {
@@ -2957,7 +2970,7 @@ catch { }
         const upd = db.prepare(`UPDATE products SET
       last_sold_at = (SELECT MAX(COALESCE(updated_at, created_at)) FROM orders WHERE product_id = ? AND status = 'completed'),
       first_sold_at = (SELECT MIN(COALESCE(updated_at, created_at)) FROM orders WHERE product_id = ? AND status = 'completed'),
-      completion_count = (SELECT COUNT(1) FROM orders WHERE product_id = ? AND status = 'completed'),
+      completion_count = (SELECT COUNT(1) FROM orders WHERE product_id = ? AND ${genuineSalePredicate('orders')}),
       dispute_loss_count = (
         SELECT COUNT(1) FROM disputes d JOIN orders o ON o.id = d.order_id
         WHERE o.product_id = ? AND d.ruling_type IN ('refund_buyer','partial_refund')
@@ -3233,8 +3246,8 @@ function computeAgentTrust(apiKey) {
     if (!user)
         return null;
     const ageDays = Math.max(0, (Date.now() - new Date(user.created_at.replace(' ', 'T') + 'Z').getTime()) / 86400_000);
-    const completedBuyer = db.prepare(`SELECT COUNT(*) as n FROM orders WHERE buyer_id = ? AND status = 'completed'`).get(user.id).n;
-    const completedSeller = db.prepare(`SELECT COUNT(*) as n FROM orders WHERE seller_id = ? AND status = 'completed'`).get(user.id).n;
+    const completedBuyer = db.prepare(`SELECT COUNT(*) as n FROM orders WHERE buyer_id = ? AND ${genuineSalePredicate('orders')}`).get(user.id).n;
+    const completedSeller = db.prepare(`SELECT COUNT(*) as n FROM orders WHERE seller_id = ? AND ${genuineSalePredicate('orders')}`).get(user.id).n;
     const disputeLoss = db.prepare(`SELECT COUNT(*) as n FROM disputes WHERE defendant_id = ? AND ruling_type IN ('refund_buyer','partial_refund')`).get(user.id).n;
     // 商品分享带来的真实成交（创作者贡献）
     const shareConversions = db.prepare(`
@@ -4460,6 +4473,11 @@ registerAgentReputationRoutes(app, {
 });
 // #1013 Phase 47: 6 公开用户主页 endpoints 已迁出到 routes/users-public.ts
 registerUsersPublicRoutes(app, { db, auth, noteAuthenticityBadges });
+registerDirectPayDisclosureAckRoutes(app, { db, auth, generateId, consumeGateToken }); // PR-4d
+registerDirectReceivePaymentInstructionRoutes(app, { db, auth, generateId });
+registerDirectReceiveAccountsRoutes(app, { db, auth, generateId, consumeGateToken }); // PR-4f-a + Phase C1
+registerDirectPayAvailabilityRoutes(app, { db, auth, getProtocolParam, generateId }); // PR-4a + 缓交 apply/status
+registerAdminDirectReceiveDepositsRoutes(app, { db, requireRootAdmin: (req, res) => requireRootAdmin(req, res), consumeGateToken, logAdminAction, getProtocolParam }); // PR-4b-3 + readiness
 // RFC-004 build_feedback — agent-native "use → build" 反馈管道
 registerBuildFeedbackRoutes(app, {
     db, auth,
@@ -5652,7 +5670,7 @@ function checkVerifierEligibility(userId) {
     const ageDays = Math.floor((Date.now() - new Date(user.created_at).getTime()) / 86400_000);
     items.push({ key: 'age', label: '账户年龄 ≥ 60 天', current: ageDays, required: 60, ok: ageDays >= 60 });
     items.push({ key: 'email', label: '邮箱已验证', current: user.email_verified ? '✓' : '✗', required: '✓', ok: !!user.email_verified });
-    const orders = db.prepare("SELECT COUNT(*) as n FROM orders WHERE (buyer_id = ? OR seller_id = ?) AND status = 'completed'").get(userId, userId).n;
+    const orders = db.prepare(`SELECT COUNT(*) as n FROM orders WHERE (buyer_id = ? OR seller_id = ?) AND ${genuineSalePredicate('orders')}`).get(userId, userId).n;
     items.push({ key: 'orders', label: '完成订单 ≥ 20 笔', current: orders, required: 20, ok: orders >= 20 });
     const disputeLost = db.prepare(`
     SELECT COUNT(*) as n FROM disputes
@@ -5799,7 +5817,7 @@ function checkArbitratorEligibility(userId) {
     const ageDays = Math.floor((Date.now() - new Date(user.created_at).getTime()) / 86400_000);
     items.push({ key: 'age', label: '账户年龄 ≥ 90 天', current: ageDays, required: 90, ok: ageDays >= 90 });
     items.push({ key: 'email', label: '邮箱已验证', current: user.email_verified ? '✓' : '✗', required: '✓', ok: !!user.email_verified });
-    const orders = db.prepare("SELECT COUNT(*) as n FROM orders WHERE (buyer_id = ? OR seller_id = ?) AND status = 'completed'").get(userId, userId).n;
+    const orders = db.prepare(`SELECT COUNT(*) as n FROM orders WHERE (buyer_id = ? OR seller_id = ?) AND ${genuineSalePredicate('orders')}`).get(userId, userId).n;
     items.push({ key: 'orders', label: '完成订单 ≥ 50 笔', current: orders, required: 50, ok: orders >= 50 });
     const disputeLost = db.prepare(`
     SELECT COUNT(*) as n FROM disputes
@@ -6019,7 +6037,7 @@ registerOrdersReadRoutes(app, { db, auth, getOrderStatus, getOrderChain, verifyO
 registerOrdersActionRoutes(app, {
     db, auth, isTrustedRole, generateId, transition, notifyTransition,
     settleOrder, settleFault, detectFraud, createDispute, checkTimeouts, recordViolationReputation,
-    broadcastSystemEvent,
+    broadcastSystemEvent, consumeGateToken,
 });
 // #1013 Phase 85: POST /api/orders 巨型事务已迁出
 registerOrdersCreateRoutes(app, {
@@ -6134,8 +6152,8 @@ function awardBidAndCreateOrder(rfq, winner) {
             db.prepare(`
         INSERT INTO products (id, seller_id, title, description, price, stock, status, images,
           ship_regions, handling_hours, commission_rate, category_id, stake_amount,
-          listing_id, fulfillment_type, eta_hours, freshness_ts, cold_start_remaining)
-        VALUES (?,?,?,?,?,?,'active','[]',?,?,?,?,0,?,?,?,datetime('now'),?)
+          listing_id, fulfillment_type, eta_hours, freshness_ts, cold_start_remaining, currency)
+        VALUES (?,?,?,?,?,?,'active','[]',?,?,?,?,0,?,?,?,datetime('now'),?,'WAZ')
       `).run(productId, sellerId, String(rfq.title), `[RFQ ${rfqId}] ` + (rfq.notes ? String(rfq.notes).slice(0, 200) : '协议撮合订单'), price, qty, String(rfq.region_required || '全国'), 24, 0, 'cat_default', lstId, fulfillmentType, etaHours, 30);
         }
     }
@@ -6589,8 +6607,8 @@ function settleAuctionInner(aucId) {
         productId = generateId('p');
         db.prepare(`
       INSERT INTO products (id, seller_id, title, description, price, stock, status, images,
-        ship_regions, handling_hours, commission_rate, category_id, stake_amount, listing_id, freshness_ts, cold_start_remaining)
-      VALUES (?,?,?,?,?,?,'active','[]',?,?,?,?,0,?,datetime('now'),?)
+        ship_regions, handling_hours, commission_rate, category_id, stake_amount, listing_id, freshness_ts, cold_start_remaining, currency)
+      VALUES (?,?,?,?,?,?,'active','[]',?,?,?,?,0,?,datetime('now'),?,'WAZ')
     `).run(productId, sellerId, String(auc.title), `[AUC ${aucId}] ` + (auc.notes ? String(auc.notes).slice(0, 200) : '拍卖成交'), price, qty, '全国', 24, 0.10, 'cat_default', auc.listing_id ? String(auc.listing_id) : null, 30);
     }
     // 5) 截止期 — 拍卖订单走标准 17 天链（拍卖结束后再谈履约时效）
@@ -6718,7 +6736,7 @@ const TASK_DEFS = {
 };
 // 计算用户当前任务进度（不写库，纯读）
 function computeTaskProgress(userId) {
-    const completed = db.prepare(`SELECT COUNT(*) as n FROM orders WHERE buyer_id = ? AND status = 'completed'`).get(userId).n;
+    const completed = db.prepare(`SELECT COUNT(*) as n FROM orders WHERE buyer_id = ? AND ${genuineSalePredicate('orders')}`).get(userId).n;
     const ratingsGiven = db.prepare(`SELECT COUNT(*) as n FROM order_ratings WHERE buyer_id = ?`).get(userId).n;
     const ratingsReceived = db.prepare(`SELECT COUNT(*) as n FROM order_ratings WHERE seller_id = ?`).get(userId).n;
     const follows = db.prepare(`SELECT COUNT(*) as n FROM follows WHERE follower_id = ?`).get(userId).n;
@@ -6910,6 +6928,7 @@ registerShareablesInteractionsRoutes(app, {
     parseMentions, notifyMentions,
 });
 registerLeaderboardRoutes(app, { db, internalAuditorId: INTERNAL_AUDITOR_ID, rateLimitOk });
+registerFxRoutes(app, { rateLimitOk });
 // like-status / bookmark-status / bookmarked-shareables 已迁出 (#1013 Phase 12)
 // ─── Manifest Registry API（原生 P2P 内容索引，零字节存储）─────
 // ============================================================
@@ -7187,28 +7206,19 @@ function settleCommission(orderId, effectiveBase) {
         { level: 2, beneficiary: l2Uid },
         { level: 3, beneficiary: l3Uid },
     ];
-    // #7 Commission source_type — 查 attribution 找到带来 buyer 的 shareable，确定 channel 类型
-    // 反推: 该 uid 作为 sharer 把 product 分享给"下家"的 shareable 类型
-    function resolveSourceType(uid) {
-        if (!uid)
-            return 'sponsor';
-        const attr = db.prepare(`
-      SELECT shareable_id FROM product_share_attribution
-      WHERE product_id = ? AND sharer_id = ? AND shareable_id IS NOT NULL
-      ORDER BY created_at DESC LIMIT 1
-    `).get(order.product_id, uid);
-        if (!attr)
-            return 'sponsor';
-        const sh = db.prepare(`SELECT type FROM shareables WHERE id = ?`).get(attr.shareable_id);
-        if (!sh)
-            return 'sponsor';
-        return sh.type === 'note' ? 'note' : 'link';
-    }
+    // #7 Commission source_type resolution moved to module-level commissionSourceType() — RFC-018
+    // Option A writes commission_records at MATURATION (not here), so source_type is stamped there.
     // 2026-06-04：所有兜底统一入 commission_reserve（三级公池，独立科目，只进不出）。
     // commission 不再回流 global_fund（PV 资金）—— 三套科目解耦，redirected 始终 0。
     let toCommissionReserve = 0; // → commission_reserve（仅作日志/返回信息用）
     // 三级金额一次性 allocate(精确求和 ≡ poolU);各级再按 gate 路由到钱包/公池/escrow。
     const levelAmtU = allocate(poolU, [LEVEL_RATES[1], LEVEL_RATES[2], LEVEL_RATES[3]]);
+    // RFC-018 clearing window: opted-in commission accrues to pending_commission_escrow and matures
+    // after the product's return window + buffer. Anchor = now (settleCommission runs at order→completed).
+    const nowMsClearing = Date.now();
+    const returnDaysClearing = Number(db.prepare("SELECT return_days FROM products WHERE id = ?").get(order.product_id)?.return_days ?? 7);
+    const clearingBufferDays = Number(db.prepare("SELECT value FROM protocol_params WHERE key = 'settlement.clearing_buffer_days'").get()?.value ?? 2);
+    const maturesAtClearing = nowMsClearing + Math.max(0, returnDaysClearing + clearingBufferDays) * 86400 * 1000;
     for (const { level, beneficiary } of recipients) {
         const amountU = levelAmtU[level - 1];
         const amount = toDecimal(amountU);
@@ -7254,15 +7264,17 @@ function settleCommission(orderId, effectiveBase) {
             catch (e) { /* UNIQUE 冲突 — settleCommission 重入幂等 */ }
             continue;
         }
-        // ⑤ 正常分账
+        // ⑤ RFC-018 clearing (Option A): opted-in commission ACCRUES to pending_commission_escrow with a
+        // matures_at — it is NOT credited to the wallet now and writes NO commission_records yet. The
+        // maturation cron (rewards-clearing-mature) re-validates the order is still genuinely closed, then
+        // writes commission_records + credits the wallet. A return in-window reverses the pending row
+        // (proportionally) — never paid, never clawed back. expires_at is a NOT-NULL filler = matures_at;
+        // the escrow-expire cron ignores rows where matures_at IS NOT NULL (i.e. clearing rows).
         try {
-            const srcType = resolveSourceType(beneficiary);
-            db.prepare(`INSERT INTO commission_records (id, order_id, beneficiary_id, source_buyer_id, level, amount, rate, region, source, source_type)
-                  VALUES (?,?,?,?,?,?,?,?,?,?)`)
-                .run(generateId('comm'), orderId, beneficiary, order.buyer_id, level, amount, rate, region, routeSource, srcType);
-            applyWalletDelta(db, beneficiary, { balance: amountU, earned: amountU });
+            db.prepare(`INSERT INTO pending_commission_escrow (recipient_user_id, order_id, amount, attribution_path, status, created_at, expires_at, matures_at) VALUES (?,?,?,?,'pending',?,?,?)`)
+                .run(beneficiary, orderId, amount, `L${level}`, nowMsClearing, maturesAtClearing, maturesAtClearing);
         }
-        catch (e) { /* UNIQUE 冲突 */ }
+        catch (e) { /* UNIQUE (recipient,order,path) — settleCommission re-entry idempotent */ }
     }
     db.prepare("UPDATE orders SET settled_commission_at = datetime('now') WHERE id = ?").run(orderId);
     // redirected 恒为 0：commission 兜底全部入 commission_reserve，不再回流 global_fund(PV 资金)。
@@ -7378,6 +7390,10 @@ function settleOrder(orderId) {
     // 内部 try/catch 用于非关键 hook（settlePinRewards / metrics 更新）失败不回滚资金主流程
     db.transaction(() => {
         const order = db.prepare('SELECT * FROM orders WHERE id = ?').get(orderId);
+        if (order && order.payment_rail === 'direct_p2p') {
+            settleDirectPayFeeAtCompletion(db, order, generateId('dpfr'));
+            return;
+        } // Rail1 直付:跳过 escrow 结算;平台费=链下应收(释放遗留模拟 stake + accrue,fail-closed 同原子边界)
         const total = order.total_amount;
         const isSecondhand = order.source === 'secondhand';
         const isInPerson = order.fulfillment_mode === 'in_person';
@@ -8704,72 +8720,10 @@ try {
     db.exec('CREATE INDEX IF NOT EXISTS idx_rewards_apps_action ON rewards_applications(user_id, action, created_at DESC)');
 }
 catch { }
-// 5. pending_commission_escrow:opt-out promoter 待激活领取队列(§3.5b)
-// PR-1c-b: order_id is NULLable so attribution_path='pv_pair' rows (which accrue
-// across many orders) can record amount without inventing a fake order_id.
-// L1/L2/L3 rows still carry a real order_id, enforced by the gate code path
-// in settleCommission (not by NOT NULL constraint).
-db.exec(`
-  CREATE TABLE IF NOT EXISTS pending_commission_escrow (
-    id                       INTEGER PRIMARY KEY AUTOINCREMENT,
-    recipient_user_id        TEXT NOT NULL,
-    order_id                 TEXT,                                 -- NULL for pv_pair (PR-1c-b)
-    amount                   REAL NOT NULL,    -- WAZ amount
-    attribution_path         TEXT NOT NULL,    -- 'L1' | 'L2' | 'L3' | 'pv_pair' | etc.
-    status                   TEXT NOT NULL DEFAULT 'pending',  -- 'pending' | 'settled' | 'expired'
-    created_at               INTEGER NOT NULL,
-    expires_at               INTEGER NOT NULL,
-    settled_at               INTEGER,
-    expired_to_charity_at    INTEGER,
-    FOREIGN KEY (recipient_user_id) REFERENCES users(id),
-    FOREIGN KEY (order_id) REFERENCES orders(id)
-  )
-`);
-(function migrateEscrowOrderIdNullable() {
-    const cols = db.prepare("PRAGMA table_info(pending_commission_escrow)").all();
-    const orderIdCol = cols.find(c => c.name === 'order_id');
-    if (!orderIdCol || orderIdCol.notnull === 0)
-        return; // already nullable (or table missing entirely)
-    console.log('[pc-escrow-migrate] order_id is NOT NULL — recreating table to allow NULL for pv_pair');
-    db.exec('PRAGMA foreign_keys = OFF');
-    db.transaction(() => {
-        db.exec(`
-      CREATE TABLE pending_commission_escrow_new (
-        id                       INTEGER PRIMARY KEY AUTOINCREMENT,
-        recipient_user_id        TEXT NOT NULL,
-        order_id                 TEXT,
-        amount                   REAL NOT NULL,
-        attribution_path         TEXT NOT NULL,
-        status                   TEXT NOT NULL DEFAULT 'pending',
-        created_at               INTEGER NOT NULL,
-        expires_at               INTEGER NOT NULL,
-        settled_at               INTEGER,
-        expired_to_charity_at    INTEGER,
-        FOREIGN KEY (recipient_user_id) REFERENCES users(id),
-        FOREIGN KEY (order_id) REFERENCES orders(id)
-      )
-    `);
-        db.exec('INSERT INTO pending_commission_escrow_new SELECT * FROM pending_commission_escrow');
-        db.exec('DROP TABLE pending_commission_escrow');
-        db.exec('ALTER TABLE pending_commission_escrow_new RENAME TO pending_commission_escrow');
-    })();
-    db.exec('PRAGMA foreign_keys = ON');
-})();
-try {
-    db.exec('CREATE INDEX IF NOT EXISTS idx_escrow_recipient ON pending_commission_escrow(recipient_user_id, status, expires_at)');
-}
-catch { }
-try {
-    db.exec('CREATE INDEX IF NOT EXISTS idx_escrow_expiry ON pending_commission_escrow(status, expires_at)');
-}
-catch { }
-// PR-1c-a: UNIQUE (recipient, order, path) defends against double-insert if settleCommission ever retries
-// Note: NULL order_id (PR-1c-b pv_pair) is distinct in SQLite UNIQUE — idempotency for pv_pair relies
-// on binary_score_records.settled_at instead (source-side dedup).
-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 { }
+// pending_commission_escrow schema (table + migration + indexes) lives in
+// initPendingCommissionEscrowSchema (early helper batch above) — RFC-018 PR1 relocated it there so
+// all of its DDL is built once, never half-inline (fresh-DB silent-fail铁律). The backfill below
+// only READS the table; it still runs after the build (early batch precedes this line).
 // 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。升级窗口里两者混存。
@@ -8819,6 +8773,7 @@ const RFC002_PARAMS = [
     { key: 'rewards_opt_in.min_completed_orders', value: '1', type: 'number', description: 'RFC-002 §3.2:申请 rewards opt-in 的最小已完成订单数', category: 'rewards', min: 0, max: 100, metaRuleLocked: false },
     { key: 'rewards_opt_in.require_passkey', value: '1', type: 'number', description: 'RFC-002 §3.3:申请 / 关闭是否需 Passkey(1=必须,0=允许 password)— META-RULE LOCKED,降低需 60d meta-rule track', category: 'rewards', min: 0, max: 1, metaRuleLocked: true },
     { key: 'rewards_opt_in.escrow_days', value: '30', type: 'number', description: 'RFC-002 §3.5b:pending commission escrow 过期天数(过期后流入 charity_fund)', category: 'rewards', min: 7, max: 180, metaRuleLocked: false },
+    { key: 'settlement.clearing_buffer_days', value: '2', type: 'number', description: 'RFC-018:佣金清算期 = 商品 return_days + 此 buffer(成熟才入钱包;窗内退货则冲销,永不 clawback)', category: 'rewards', min: 0, max: 30, metaRuleLocked: false },
     { key: 'rewards_opt_in.consent_delay_seconds', value: '8', type: 'number', description: 'RFC-002 §3.3:server-side 8s 反诱导延迟 — META-RULE LOCKED,降低需 60d meta-rule track', category: 'rewards', min: 0, max: 60, metaRuleLocked: true },
     { key: 'rewards_opt_in.reconfirm_grace_days', value: '14', type: 'number', description: 'RFC-002 §3.10:major consent 变更后用户重新确认 grace 期(过期 auto_downgrade)', category: 'rewards', min: 3, max: 90, metaRuleLocked: false },
 ];
@@ -8907,6 +8862,8 @@ app.listen(PORT, () => {
     startAutoDeactivateCron({ db, generateId, getProtocolParam });
     // #1090 RFC-002 PR-1c-a: escrow expire cron (every 1h)
     startEscrowExpireCron({ db, redirectToCommissionReserve });
+    startDirectPayTimeoutCron({ db });
+    startClearingMatureCron({ db }); // RFC-018: pay/hold matured clearing commission (logic in the cron module)
     // #1090 RFC-002 PR-3 slice 2: auto_downgrade cron (every 24h)
     // Triggered when a new major consent text is published; opted-in users
     // who don't reconfirm within reconfirm_grace_days (14d default) get