docs: define project design invariants

README-zh.md

@@ -3,7 +3,7 @@
   <h1 style="margin-top: 0.2em;">GhostScope</h1>
   <h3>⚡ 下一代 eBPF 用户态运行时追踪器</h3>
   <p>
-    <strong>Printf 调试的进化</strong> — 无需停止或修改应用即可实时追踪。
+    <strong>Printf 调试的进化</strong> — 无需 stop-the-world 检查即可实时追踪。
   </p>
 
   <p>
@@ -18,7 +18,9 @@
 
 ## 概述
 
-GhostScope 是一个 **面向源码语义的用户态追踪器**。有 DWARF 调试信息时，它可以在不停住目标进程的前提下，按函数、源码行或指令粒度设点，打印真正重要的信息，并输出源码感知的调用栈。
+GhostScope 是一个 **面向源码语义的用户态追踪器**。有 DWARF 调试信息时，它可以在不由调试器控制目标暂停的前提下，按函数、源码行或指令粒度设点，打印真正重要的信息，并输出源码感知的调用栈。
+
+支持范围以及可信输出所依赖的不变量，统一定义在[设计保证与可信性模型](docs/zh/design-contract.md)中。
 
 > *"The most effective debugging tool is still careful thought, coupled with judiciously placed print statements."* — Brian Kernighan
 
@@ -27,7 +29,7 @@ GhostScope 是一个 **面向源码语义的用户态追踪器**。有 DWARF 调
 - 你在排查线上正在运行的服务，不能接受 GDB 式 stop-the-world 带来的巨大性能扰动，同时又更希望使用基于 eBPF 的工作流，获得比传统内核模块式探测更好的安全边界和更低开销。
 - 你需要在源码行级探针里读取真实的局部变量、参数、全局变量和复杂数据，而不只是函数入口参数。
 - 你想在同一个 live probe 里既打印关键状态，又输出基于 DWARF unwind 的调用栈 (backtrace)。
-- 你需要解释一次请求、函数、源码行或代码路径是如何被执行到的，同时又不能停止目标进程。
+- 你需要解释一次请求、函数、源码行或代码路径是如何被执行到的，同时又不能做 stop-the-world 检查。
 - 你想把“这里要是能加一条 printf 就好了”快速变成一个可重复运行的 CLI 追踪脚本。
 
 ### 什么时候不适合用 GhostScope
@@ -147,7 +149,7 @@ GhostScope 把编译后的二进制重新变成“可观测系统”。在 TUI 
 
 想象一下，你面对的是一片广袤的二进制数据荒野 —— 内存地址、寄存器值、栈帧数据 —— 没有上下文，它们只是毫无意义的数字。**DWARF 调试信息就是我们的地图**：它告诉我们栈地址 `RSP-0x18` 存储着局部变量 `count`，堆地址 `0x5621a8c0` 处的结构体是 `user` 对象，其偏移 `+0x20` 处是字符串指针 `user.name`；它追踪每个变量在程序执行过程中的位置变化 —— 参数 `x` 现在在寄存器 `RDI` 中，之后会被移到栈上 `RSP-0x10` 的位置。
 
-有了这张地图，GhostScope 利用 **eBPF 和 uprobe** 技术从运行中程序的指令点安全地提取二进制数据。这种组合威力强大：DWARF 揭示进程虚拟地址空间中数据的含义，eBPF 安全地获取我们需要的数据。结果呢？你可以在不停止、不修改程序的情况下打印变量值（局部变量或全局变量）、函数参数、复杂数据结构，以及基于 DWARF unwind 的调用栈。
+有了这张地图，GhostScope 利用 **eBPF 和 uprobe** 技术从运行中程序的指令点安全地提取二进制数据。DWARF 揭示进程虚拟地址空间中数据的含义，eBPF 获取请求的数据，从而在不由调试器控制暂停、也不主动修改应用状态的前提下，输出源码感知的变量值和调用栈。每次 uprobe 命中仍会同步执行 trap 和 eBPF 路径，因此追踪并非对时序完全透明。
 
 ## ✨ 核心特性
 
@@ -157,9 +159,9 @@ GhostScope 把编译后的二进制重新变成“可观测系统”。在 TUI 
       <td align="center" width="25%">
         <img src="https://raw.githubusercontent.com/swananan/ghostscope/main/assets/icons/performance.svg" width="60" alt="Performance"/>
         <br />
-        <strong>低开销</strong>
+        <strong>按需开销</strong>
         <br />
-        <sub>仅需一次上下文切换 + eBPF 执行</sub>
+        <sub>每次命中执行 uprobe + 有界 eBPF 工作</sub>
       </td>
       <td align="center" width="25%">
         <img src="https://raw.githubusercontent.com/swananan/ghostscope/main/assets/icons/realtime.svg" width="60" alt="Real-time"/>
@@ -173,7 +175,7 @@ GhostScope 把编译后的二进制重新变成“可观测系统”。在 TUI 
         <br />
         <strong>DWARF 感知</strong>
         <br />
-        <sub>完整调试信息支持</sub>
+        <sub>基于 PC 的源码语义</sub>
       </td>
       <td align="center" width="25%">
         <img src="https://raw.githubusercontent.com/swananan/ghostscope/main/assets/icons/rust.svg" width="60" alt="Rust"/>
@@ -186,15 +188,15 @@ GhostScope 把编译后的二进制重新变成“可观测系统”。在 TUI 
   </table>
 </div>
 
-## ⚠️ 实验性工具声明
+## ⚠️ 可信性与开发状态
 
-> **GhostScope 目前处于早期开发阶段**，仍在积极迭代中。虽然我们努力确保数据准确性，但在某些情况下可能出现错误或不完整的追踪信息，更多的应该是探测功能不支持。
+> **GhostScope 目前处于早期开发阶段**，仍在积极迭代中。在支持范围内，已知的恢复或归因失败应当显式呈现，不能被展示成看似合理的值。
 >
-> **建议**：将 GhostScope 采集的数据作为问题排查的**辅助参考**，而非唯一依据。在做出关键决策前，请结合其他调试工具交叉验证。
+> 实现缺陷仍可能违反这份契约。建议将 GhostScope 采集的数据作为问题排查的**辅助参考**；在做出关键决策前，请结合其他调试工具交叉验证。
 >
-> 我们正在持续改进稳定性和准确性，期待未来版本能够移除此声明。
+> 规范性的保证、前提和失败语义见[设计保证与可信性模型](docs/zh/design-contract.md)。
 
-当前的硬性限制和软性限制，请参阅 [使用限制](docs/zh/limitations.md)。
+不支持和会显式降级的场景见[使用限制](docs/zh/limitations.md)。
 
 ## 📚 文档
 
@@ -245,6 +247,9 @@ GhostScope 把编译后的二进制重新变成“可观测系统”。在 TUI 
 - [**架构概览**](docs/zh/architecture.md)
   系统设计和内部原理
 
+- [**设计保证与可信性模型**](docs/zh/design-contract.md)
+  支持范围、不变量和失败语义
+
 - [**开发指南**](docs/zh/development.md)
   构建和扩展 GhostScope
 

README.md

@@ -3,7 +3,7 @@
   <h1 style="margin-top: 0.2em;">GhostScope</h1>
   <h3>⚡ Next-generation eBPF userspace runtime tracer</h3>
   <p>
-    <strong>Printf debugging evolved</strong> — Real-time tracing without stopping your application.
+    <strong>Printf debugging evolved</strong> — Real-time tracing without stop-the-world inspection.
   </p>
 
   <p>
@@ -22,7 +22,9 @@
 
 ## Overview
 
-GhostScope is a **source-aware userspace tracer** for live Linux processes. With DWARF debug info, it lets you attach at function, source-line, or instruction granularity, print the values that matter, and emit source-aware call stacks without stopping the target.
+GhostScope is a **source-aware userspace tracer** for live Linux processes. With DWARF debug info, it lets you attach at function, source-line, or instruction granularity, print the values that matter, and emit source-aware call stacks without debugger-controlled suspension of the target.
+
+The supported operating envelope and the invariants behind trustworthy output are defined in [Design Guarantees and Trust Model](docs/design-contract.md).
 
 > *"The most effective debugging tool is still careful thought, coupled with judiciously placed print statements."* — Brian Kernighan
 
@@ -31,7 +33,7 @@ GhostScope is a **source-aware userspace tracer** for live Linux processes. With
 - You are diagnosing a production service that must stay online: GDB-style stop-the-world debugging would cause too much disruption, and you prefer an eBPF-based workflow with stronger safety boundaries and lower overhead than traditional kernel-module instrumentation.
 - You need source-line probes that can read real locals, parameters, globals, and complex data, not just function entry arguments.
 - You want DWARF-unwound stack backtraces from the same live probe that prints the relevant state.
-- You need to explain how execution reached a specific source line, function, request, or code path without stopping the process.
+- You need to explain how execution reached a specific source line, function, request, or code path without stop-the-world inspection.
 - You want a low-friction path from "I wish I had one more printf here" to a repeatable CLI trace script.
 
 ### When Not To Use GhostScope
@@ -152,7 +154,7 @@ The demo below follows exactly that path on a DWARF-enabled nginx worker: locate
 
 Imagine navigating a vast, uncharted forest of binary data — memory addresses, register values, stack frames — all meaningless numbers without context. **DWARF debug information is our map**: it tells us that stack address `RSP-0x18` stores local variable `count`, heap address `0x5621a8c0` is a `user` object with string pointer `user.name` at offset `+0x20`; it tracks where each variable lives throughout program execution — parameter `x` is in register `RDI` now but will move to stack offset `RSP-0x10` later.
 
-With this map in hand, GhostScope leverages **eBPF and uprobe** technology to safely extract binary data from instruction points in your running program. The combination is powerful: DWARF reveals the meaning of bytes in the process's virtual address space, while eBPF safely retrieves exactly what we need. The result? You can print variable values (local or global), function arguments, complex data structures, and DWARF-unwound call stacks without stopping or modifying the program.
+With this map in hand, GhostScope leverages **eBPF and uprobe** technology to safely extract binary data from instruction points in your running program. The combination is powerful: DWARF reveals the meaning of bytes in the process's virtual address space, while eBPF retrieves the requested data. The result is source-aware variable values and call stacks without debugger-controlled suspension or intentional application-state changes. Each uprobe hit still adds synchronous trap and eBPF work, so tracing is not timing-transparent.
 
 ## ✨ Highlights
 
@@ -162,9 +164,9 @@ With this map in hand, GhostScope leverages **eBPF and uprobe** technology to sa
       <td align="center" width="25%">
         <img src="https://raw.githubusercontent.com/swananan/ghostscope/main/assets/icons/performance.svg" width="60" alt="Performance"/>
         <br />
-        <strong>Low Overhead</strong>
+        <strong>Targeted Overhead</strong>
         <br />
-        <sub>One context switch + eBPF execution</sub>
+        <sub>Per-hit uprobe + bounded eBPF work</sub>
       </td>
       <td align="center" width="25%">
         <img src="https://raw.githubusercontent.com/swananan/ghostscope/main/assets/icons/realtime.svg" width="60" alt="Real-time"/>
@@ -178,7 +180,7 @@ With this map in hand, GhostScope leverages **eBPF and uprobe** technology to sa
         <br />
         <strong>DWARF-Aware</strong>
         <br />
-        <sub>Full debug info support</sub>
+        <sub>PC-specific source semantics</sub>
       </td>
       <td align="center" width="25%">
         <img src="https://raw.githubusercontent.com/swananan/ghostscope/main/assets/icons/rust.svg" width="60" alt="Rust"/>
@@ -191,15 +193,15 @@ With this map in hand, GhostScope leverages **eBPF and uprobe** technology to sa
   </table>
 </div>
 
-## ⚠️ Experimental Tool Disclaimer
+## ⚠️ Reliability and Development Status
 
-> **GhostScope is currently in early development** and under active iteration. While we strive for data accuracy, trace information may be incorrect or incomplete in certain scenarios, primarily due to unsupported features.
+> **GhostScope is currently in early development** and under active iteration. Within the supported envelope, a known inability to recover or attribute data should be reported explicitly rather than rendered as a plausible value.
 >
-> **Recommendation**: Use GhostScope's collected data as an **auxiliary reference** for troubleshooting, not as the sole source of truth. Cross-validate with other debugging tools before making critical decisions.
+> Implementation defects may still violate that contract. Use GhostScope's collected data as an **auxiliary reference** for troubleshooting, and cross-validate with other debugging tools before making critical decisions.
 >
-> We are continuously improving stability and accuracy, and look forward to removing this disclaimer in future versions.
+> The normative guarantees, assumptions, and failure semantics are documented in [Design Guarantees and Trust Model](docs/design-contract.md).
 
-See [Limitations](docs/limitations.md) for the current list of hard and soft constraints.
+See [Limitations](docs/limitations.md) for unsupported and explicitly degraded scenarios.
 
 ## 📚 Documentation
 
@@ -250,6 +252,9 @@ See [Limitations](docs/limitations.md) for the current list of hard and soft con
 - [**Architecture Overview**](docs/architecture.md)
   System design and internals
 
+- [**Design Guarantees and Trust Model**](docs/design-contract.md)
+  Supported operating envelope, invariants, and failure semantics
+
 - [**Development Guide**](docs/development.md)
   Build and extend GhostScope