feat(pavilion): v2 — claim windows and regret; the boundary second belongs to the heir

- depositGift(tokenId, heir, claimBy): strictly-future deadlines, heirless
  gifts rejected (v1 trap: heir=address(0) collided with the empty-slot
  sentinel and stranded the card in custody forever)
- gapless, overlap-free windows: heir claims while now <= claimBy (boundary
  inclusive), giver reclaims only after — no early yank-back, the deadline
  is a promise; expired gifts wait in custody with no reclaim deadline
- Gift{giver,heir,claimBy} struct mapping replaces the parallel mappings
- tests 111 → 120, coverage stays 100/100/100/100: boundary-second matrix
  via evm_setNextBlockTimestamp (claim at claimBy succeeds, reclaim at
  claimBy still blocked, +1s flips both), double-claim/reclaim, re-gift
  after reclaim, 365-days-later reclaim
- READMEs / architecture / SECURITY / CONTRIBUTING synced

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Redchar1992

CONTRIBUTING.md

@@ -7,7 +7,7 @@ help keep it that way.
 
 ```bash
 npm install        # node >= 20
-npm test           # 111 specs, ~3s
+npm test           # 120 specs, ~3s
 npm run coverage   # must stay at 100% — CI enforces it
 ```
 

README.md

@@ -18,7 +18,7 @@ Three Kingdoms general cards: four factions (WEI / SHU / WU / QUN), five raritie
 - **Deliberately spiky Solidity.** File-level types and free functions, a `global` using-for, aliased named imports, a same-file-two-paths import trap, a public-state-var overriding an interface function, `unchecked` blocks, an assembly guard, reverting `receive`/`fallback` — each one placed on purpose to stress compilers, flatteners, UML generators, linters and analyzers, and annotated with *why*. See [docs/architecture.md](docs/architecture.md).
 - **Signature-driven lazy minting (虎符 TigerTally).** A tally contract takes the suzerainty — the two-step handover exists precisely so a *contract* can hold the throne safely — and redeems EIP-712 `MintOrder`s: nested-struct hashing (the order wraps a full `Card`), bearer and bound-with-relayer voucher modes, voidable nonces, malleability-guarded `ecrecover`, and a marshal-gated passthrough for every suzerain power including the escape hatch back. The on-chain digest is differentially anchored to ethers' `TypedDataEncoder` in tests.
 - **Real value handled the boring way (市集 CardBazaar).** A fixed-price, TRX-settled stall market with escrowed listings and **pull-payment proceeds** — paying sellers inline would let any seller with a reverting `receive()` brick their own listing's purchase. `withdraw()` is checks-effects-interactions, proven by a hostile seller that attempts a reentrant drain mid-payout and finds an already-zeroed ledger. No owner, no fees, no sweep: the bazaar's admin column in the trust model reads *nobody*.
-- **111 tests, 100% coverage, gated in CI.** Statements, branches, functions and lines all at 100% (mocks excluded); the CI fails if any of it regresses. Includes differential tests of the on-chain Base64/decimal/JSON-escape/XML-escape helpers against reference implementations, XML well-formedness checks on every rendered SVG, a receiver-behavior matrix, and a seeded random transfer storm checked against a model.
+- **120 tests, 100% coverage, gated in CI.** Statements, branches, functions and lines all at 100% (mocks excluded); the CI fails if any of it regresses. Includes differential tests of the on-chain Base64/decimal/JSON-escape/XML-escape helpers against reference implementations, XML well-formedness checks on every rendered SVG, a receiver-behavior matrix, and a seeded random transfer storm checked against a model.
 - **A real dogfooding campaign, honestly kept.** The entire project — scaffold, edit, lint, compile, VM deploy, debug, record/replay, TronBox export, git push, TronLink mainnet-style deploys, flatten & verification — was executed **inside TronIDE**, driving 23 IDE features and filing 13 findings, of which 6 were fixed upstream with regression gates and **3 were retracted after strict re-verification** (the ledger counts our own misreads too). See [docs/case-study.md](docs/case-study.md).
 
 > **Audit status:** engineered to audit-grade practice, **not yet externally audited**. Read [SECURITY.md](SECURITY.md) before depositing value you care about.
@@ -40,8 +40,8 @@ contracts/
 │   ├── libs/CardCodec.sol      Card → data:application/json;base64 (JSON-escaped)
 │   ├── libs/Base64.sol         assembly encoder (public-node CPU caps forced it — see docs)
 │   └── utils/StrUtils.sol      toString / equal / escapeJson / escapeXml
-├── PeachPavilion.sol           gift escrow: deposit a card for an heir to claim;
-│                               rejects naked safeTransferFrom deliveries
+├── PeachPavilion.sol           gift escrow with claim windows: the heir claims until
+│                               the deadline (boundary inclusive), the giver reclaims after
 ├── TigerTally.sol              虎符 — EIP-712 signed mint orders (lazy minting);
 │                               holds the suzerainty while in service
 ├── CardBazaar.sol              市集 — fixed-price stalls, TRX-settled, escrowed
@@ -65,7 +65,7 @@ Transactions, deployer, energy numbers, the honest incident notes and verificati
 
 ```bash
 npm install
-npm test              # 111 specs, ~3s, no local TRON node needed
+npm test              # 120 specs, ~3s, no local TRON node needed
 npm run coverage      # istanbul report; CI enforces 100%
 npx hardhat compile   # solc 0.8.20, evm target paris (no PUSH0 ahead of the TVM)
 ```

README.zh-CN.md

@@ -18,7 +18,7 @@
 - **故意刁钻的 Solidity**：文件级类型与自由函数、`global` using-for、别名命名导入、同文件双路径导入陷阱、public 状态变量覆写接口函数、`unchecked`、assembly 守卫、reverting `receive`/`fallback`——每一处都是为了压测编译器、拍平器、UML、linter 与分析器而放置，并注明了 *为什么*。详见 [docs/architecture.md](docs/architecture.md)。
 - **签名驱动的 lazy mint（虎符 TigerTally）**：虎符合约受让 suzerainty 出任"在任铸造官"——两步移交的存在意义正是让**合约**能安全持有王座——并兑现 EIP-712 `MintOrder`：嵌套结构体哈希（订单内嵌完整 `Card`）、不记名/定向 + 代付两种券模式、可作废 nonce、防延展 `ecrecover`、全部 suzerain 权能的元帅直通道与王座归还逃生门。链上 digest 在测试中与 ethers `TypedDataEncoder` 差分锚定。
 - **用最无聊的方式处理真金白银（市集 CardBazaar）**：固定价、TRX 结算的摊位市场，挂单入柜托管 + **pull-payment 提款**——若采用内联打款，任何 `receive()` 回滚的卖家都能卡死自己挂单的成交。`withdraw()` 走 checks-effects-interactions，由一个在收款瞬间尝试重入抽干的恶意卖家实证：它只看到已清零的账本。无 owner、无手续费、无 sweep：信任模型里市集的管理员一栏写着 *nobody*。
-- **111 个测试、100% 覆盖率、CI 闸门**：语句 / 分支 / 函数 / 行全部 100%（mocks 除外），回退即 CI 失败。含链上 Base64 / 十进制 / JSON 转义 / XML 转义对参考实现的差分测试、每张 SVG 的 XML 良构校验、safe transfer 受体行为矩阵、种子随机转账风暴对账。
+- **120 个测试、100% 覆盖率、CI 闸门**：语句 / 分支 / 函数 / 行全部 100%（mocks 除外），回退即 CI 失败。含链上 Base64 / 十进制 / JSON 转义 / XML 转义对参考实现的差分测试、每张 SVG 的 XML 良构校验、safe transfer 受体行为矩阵、种子随机转账风暴对账。
 - **真实的 dogfooding 战役、诚实的账本**：从脚手架、编辑、lint、编译，到 VM 部署、调试、录制回放、TronBox 导出、git 推送、TronLink 实链部署、拍平与验证包——全程在 TronIDE 内完成，走遍 23 项 IDE 功能，提交 13 条发现：6 条修复入库（带回归门禁）、**3 条经严格复验后诚实撤回**（自己的误判也记账）。详见 [docs/case-study.md](docs/case-study.md)。
 
 > **审计状态**：按审计级实践工程化，**尚未经外部审计**。托管真实价值前请先读 [SECURITY.md](SECURITY.md)。
@@ -40,8 +40,8 @@ contracts/
 │   ├── libs/CardCodec.sol      Card → data:application/json;base64（含 JSON 转义）
 │   ├── libs/Base64.sol         assembly 编码器（公共节点 CPU 时限所迫——见文档）
 │   └── utils/StrUtils.sol      toString / equal / escapeJson / escapeXml
-├── PeachPavilion.sol           桃园馆礼物托管：存卡指定继承人、继承人领取；
-│                               拒收绕过托管的裸 safeTransferFrom
+├── PeachPavilion.sol           桃园馆礼物托管（v2 期限版）：继承人限期内领取
+│                               （含边界秒），逾期后赠予人可悔赠
 ├── TigerTally.sol              虎符 —— EIP-712 签名铸卡券（lazy mint）；
 │                               在任期间持有 suzerainty
 ├── CardBazaar.sol              市集 —— 固定价摊位、TRX 结算、托管挂单、
@@ -65,7 +65,7 @@ contracts/
 
 ```bash
 npm install
-npm test              # 111 个用例，约 3 秒，无需本地 TRON 节点
+npm test              # 120 个用例，约 3 秒，无需本地 TRON 节点
 npm run coverage      # istanbul 报告；CI 强制 100%
 npx hardhat compile   # solc 0.8.20，evm target paris（不让 PUSH0 跑在 TVM 前面）
 ```

SECURITY.md

@@ -17,7 +17,7 @@
 
 ## Engineering posture
 
-- 111 Hardhat specs; **100% statement / branch / function / line coverage**
+- 120 Hardhat specs; **100% statement / branch / function / line coverage**
   over every deployable contract (mocks excluded), enforced by a CI gate
   that fails below 100%.
 - Differential tests: the on-chain Base64 and decimal encoders are compared

contracts/PeachPavilion.sol

@@ -8,23 +8,45 @@ import { ITRC721Receiver } from "./interfaces/ITRC721Receiver.sol";
 // the import resolver and the flattener's dedup both get tested here.
 import { Card } from "../contracts/types/CardTypes.sol";
 
-/// @title 桃园馆 — gift escrow: deposit a card for a designated heir, the heir
-/// claims it. try/catch over an external interface call, reverting receive AND
-/// fallback, immutable interface reference, custom errors.
+/// @title 桃园馆 · PeachPavilion v2 — gift escrow with deadlines and regret.
+/// @notice Deposit a card for a designated heir with a claim window. The
+/// boundary rule is crisp and gapless: the heir may claim while
+/// `block.timestamp <= claimBy` (the boundary second is theirs); once
+/// `block.timestamp > claimBy` the giver — and only the giver — may reclaim.
+/// The giver cannot reclaim inside the window: a gift you can yank back at
+/// will is no gift, the deadline is a promise. try/catch over an external
+/// interface call, reverting receive AND fallback, immutable interface
+/// reference, custom errors.
+/// @dev v2 also closes a v1 trap: a gift to address(0) used to collide with
+/// the "nothing deposited" sentinel and strand the card in custody forever —
+/// heirless gifts are now rejected outright. Deadlines are header timestamps
+/// (~3s block cadence on TRON): do not cut windows finer than that.
 contract PeachPavilion is ITRC721Receiver {
     error NotCardHolder(address caller, uint256 tokenId);
     error NothingDeposited(uint256 tokenId);
     error NotDesignatedHeir(address caller, uint256 tokenId);
+    error NotGiftGiver(address caller, uint256 tokenId);
+    error HeirlessGift();
+    error DeadlineInThePast(uint64 claimBy);
+    error GiftExpired(uint256 tokenId, uint64 claimBy);
+    error GiftStillClaimable(uint256 tokenId, uint64 claimBy);
     error PavilionTakesNoTribute();
     error CardContractRejected(uint256 tokenId, string reason);
     error GiftsOnlyViaDeposit();
 
-    event GiftDeposited(uint256 indexed tokenId, address indexed from, address indexed heir);
+    event GiftDeposited(uint256 indexed tokenId, address indexed from, address indexed heir, uint64 claimBy);
     event GiftClaimed(uint256 indexed tokenId, address indexed heir);
+    event GiftReclaimed(uint256 indexed tokenId, address indexed giver);
+
+    /// @notice One escrowed gift: who gave it, who may claim it, until when.
+    struct Gift {
+        address giver;
+        address heir;
+        uint64 claimBy;
+    }
 
     ITRC721 public immutable cards;
-    mapping(uint256 => address) public heirOf;
-    mapping(uint256 => address) public giverOf;
+    mapping(uint256 => Gift) public giftOf;
 
     constructor(ITRC721 cardContract) {
         cards = cardContract;
@@ -40,9 +62,12 @@ contract PeachPavilion is ITRC721Receiver {
         revert GiftsOnlyViaDeposit();
     }
 
-    /// @notice Escrow `tokenId` for `heir` to claim later. The caller must
-    /// hold the card and have approved the pavilion beforehand.
-    function depositGift(uint256 tokenId, address heir) external {
+    /// @notice Escrow `tokenId` for `heir`, claimable until `claimBy`
+    /// (inclusive). The caller must hold the card and have approved the
+    /// pavilion beforehand; the deadline must be strictly in the future.
+    function depositGift(uint256 tokenId, address heir, uint64 claimBy) external {
+        if (heir == address(0)) revert HeirlessGift();
+        if (claimBy <= block.timestamp) revert DeadlineInThePast(claimBy);
         address holder;
         try cards.ownerOf(tokenId) returns (address h) {
             holder = h;
@@ -54,19 +79,32 @@ contract PeachPavilion is ITRC721Receiver {
         }
         if (holder != msg.sender) revert NotCardHolder(msg.sender, tokenId);
         cards.transferFrom(msg.sender, address(this), tokenId);
-        heirOf[tokenId] = heir;
-        giverOf[tokenId] = msg.sender;
-        emit GiftDeposited(tokenId, msg.sender, heir);
+        giftOf[tokenId] = Gift(msg.sender, heir, claimBy);
+        emit GiftDeposited(tokenId, msg.sender, heir, claimBy);
     }
 
-    /// @notice The designated heir collects the escrowed card.
+    /// @notice The designated heir collects the gift — the boundary second
+    /// still counts as inside the window.
     function claimGift(uint256 tokenId) external {
-        address heir = heirOf[tokenId];
-        if (heir == address(0)) revert NothingDeposited(tokenId);
-        if (msg.sender != heir) revert NotDesignatedHeir(msg.sender, tokenId);
-        delete heirOf[tokenId];
-        delete giverOf[tokenId];
+        Gift memory gift = giftOf[tokenId];
+        if (gift.heir == address(0)) revert NothingDeposited(tokenId);
+        if (msg.sender != gift.heir) revert NotDesignatedHeir(msg.sender, tokenId);
+        if (block.timestamp > gift.claimBy) revert GiftExpired(tokenId, gift.claimBy);
+        delete giftOf[tokenId];
         cards.transferFrom(address(this), msg.sender, tokenId);
         emit GiftClaimed(tokenId, msg.sender);
     }
+
+    /// @notice After the window closes unclaimed, the giver takes the card
+    /// back. There is no reclaim deadline — an expired gift waits safely in
+    /// custody for its giver, forever.
+    function reclaimGift(uint256 tokenId) external {
+        Gift memory gift = giftOf[tokenId];
+        if (gift.heir == address(0)) revert NothingDeposited(tokenId);
+        if (msg.sender != gift.giver) revert NotGiftGiver(msg.sender, tokenId);
+        if (block.timestamp <= gift.claimBy) revert GiftStillClaimable(tokenId, gift.claimBy);
+        delete giftOf[tokenId];
+        cards.transferFrom(address(this), msg.sender, tokenId);
+        emit GiftReclaimed(tokenId, gift.giver);
+    }
 }

docs/architecture.md

@@ -45,7 +45,7 @@ stress fixture for Solidity toolchains (see [the spiky inventory](#the-spiky-con
 | `libs/CardCodec.sol` | `Card → data:application/json;base64` | escapes user strings; aliased import `Str as S` |
 | `libs/Base64.sol` | assembly Base64 encoder | was a byte loop until P10: the 4.07M-gas double-encoded tokenURI hit public nodes' constant-call CPU cap (`OutOfTimeException`); now 1.46M. Differential-tested vs Node across the swap |
 | `utils/StrUtils.sol` | `toString`, `equal`, `escapeJson` | escape: `"` `\` → backslashed, `< 0x20` → `\u00XX`, UTF-8 passthrough |
-| `PeachPavilion.sol` | escrow: deposit card for heir, heir claims | rejects naked `safeTransferFrom` deliveries |
+| `PeachPavilion.sol` | gift escrow with claim windows (v2): heir claims while `now <= claimBy`, giver reclaims after — gapless, overlap-free boundary | rejects naked deliveries; rejects heirless gifts (the v1 stuck-card trap) |
 | `TigerTally.sol` | 虎符 — EIP-712 signed mint orders (lazy minting); holds the suzerainty while in service | zero-dep nested-struct 712, low-s `ecrecover`, marshal passthroughs for the full suzerain surface |
 | `CardBazaar.sol` | 市集 — fixed-price stalls, TRX-settled, escrowed listings | pull-payment proceeds (CEI, reentrancy-tested), `call{value:}` over `.transfer`, zero governance surface |
 | `mocks/TestMocks.sol` | receiver mocks, lib harness, abstract-base shims | **never deploy** |