// segment.h：成功返回 0，失败返回 -1 并设置 errno
int Segment::append(const Record& r);
// index.h：成功返回 true
bool Index::insert(const Key& k, Offset off);
// compactor.h：成功返回 0，失败返回负的 errno（如 -ENOSPC）
int Compactor::run();

int Store::put(const Key& k, const Value& v) {
    Record rec = makeRecord(k, v);
    if (seg_->append(rec) != 0) return -errno;
    if (!index_.insert(k, seg_->lastOffset())) return -EEXIST;
    // 新同事照着上面 append 的写法写了下面这行：
    if (needCompact() && compactor_.run() == -1) return -errno;
    return 0;
}

第 13 行是一个真实会出现的 bug：run() 失败时返回 -ENOSPC（-28），永远不等于 -1，磁盘满了也被当成成功。写这行的人没有犯傻，只是相信了"看起来一样的东西真的一样"。这正是作者说的：不一致的系统里，眼熟的模式会诱导错误的假设。

// 存储层约定（见 docs/conventions.md）：会失败的函数返回 int，
// 0 表示成功，负数是 -errno。不使用全局 errno，不返回 bool。
[[nodiscard]] int Segment::append(const Record& r);
[[nodiscard]] int Index::insert(const Key& k, Offset off);   // 键已存在：-EEXIST
[[nodiscard]] int Compactor::run();

int Store::put(const Key& k, const Value& v) {
    Record rec = makeRecord(k, v);
    if (int rc = seg_->append(rec); rc < 0) return rc;
    if (int rc = index_.insert(k, seg_->lastOffset()); rc < 0) return rc;
    if (needCompact()) {
        if (int rc = compactor_.run(); rc < 0) return rc;
    }
    return 0;
}

三个调用长得一模一样，读者看懂一个就看懂了全部；Index::insert 现在能告诉调用者为什么失败，不用再猜 -EEXIST。[[nodiscard]] 让"忘了检查返回值"变成编译警告，约定写在一处文档里。

int Store::append(const Record& r) {
    if (segments_.empty() || segments_.back().sealed())
        if (int rc = rollSegment(); rc < 0) return rc;
    return segments_.back().append(r);
}
size_t Store::activeBytes() const {
    if (segments_.empty() || segments_.back().sealed()) return 0;
    return segments_.back().bytes();
}
int Store::sync() {
    if (segments_.empty()) return 0;     // 这里忘了判断 sealed，但恰好没事
    return segments_.back().sync();
}

三个函数各自处理"没有可写段"，写法还各不相同；下一个加进来的函数很可能漏掉。

// 不变式：segments_ 永远非空，且最后一段总是未封存的可写段。
// 由构造函数建立；sealActive() 封存当前段后立即打开新段来维持。
std::vector<Segment> segments_;

int Store::append(const Record& r) {
    if (active().full())
        if (int rc = sealActive(); rc < 0) return rc;
    return active().append(r);
}
size_t Store::activeBytes() const { return active().bytes(); }
int Store::sync() { return active().sync(); }

特殊情况只在建立和维持不变式的两个地方处理，其他函数可以放心假设"一定有可写段"。不变式写在成员声明处，这正是 17.2 节说的：局部约定要写在代码里合适的位置。