docs: polish design documentation and add numerical analysis + workspace pages

docs/design/index.en.md

@@ -132,6 +132,7 @@ First-class architecture blueprints, target/resource binding, concrete schedulin
 - [Timeline staging path](timeline-path.md) separates command plans, predictive timelines, prescriptive timing, and LPU backend evolution.
 - [Golden derivation walkthrough](walkthrough.md) follows one Transformer fragment through every representation.
 - [Analysis module architecture](modules.md) assigns Python ownership and extension boundaries.
+- [Floating-point numerical analysis](numerical-analysis.md) defines the interactive numerical format analysis view and its boundary.
 - [Formal representation reference](ir/index.md) defines semantic contracts.
 - [Analysis and transformation reference](passes/index.md) defines verified transactions.
 

docs/design/index.zh.md

@@ -132,6 +132,7 @@ First-class architecture blueprint、target/resource binding、concrete scheduli
 - [Timeline 阶段路径](timeline-path.md)区分 command plan、预测时间线、强制时序与 LPU backend 演进。
 - [完整推导示例](walkthrough.md)展示一个 Transformer fragment 穿过所有 representation。
 - [分析模块架构](modules.md)定义 Python ownership 与 extension boundary。
+- [浮点数数值分析](numerical-analysis.md)定义交互式数值格式分析视图及其边界。
 - [形式化表示 reference](ir/index.md)定义 semantic contract。
 - [分析与变换 reference](passes/index.md)定义 verified transaction。
 

docs/design/ir/planning-execution.en.md

@@ -26,6 +26,16 @@ Exact operations, read/write bytes, message bytes, reuse, and arithmetic intensi
 
 Portable plans cannot contain physical implementation IDs, vendor libraries, physical devices, routes, queues, engines, memory banks, addresses, target-derived latency, or execution timestamps.
 
+### Abstract workspace and conservative bounds
+
+The `WORKSPACE` buffer role expresses abstract working memory (transient scratch) at the portable layer. It is a capacity and legality constraint, not a timing fact:
+
+- before an implementation is selected, a workspace carries only a defensible conservative upper bound (for example, the unfused score-materialization bound of attention), and the bound's semantic must be recorded;
+- target binding must replace the conservative bound with implementation-specific workspace (fused-attention scratch, kernel workspace, paged intermediates), and the resulting allocation must never exceed target memory capacity under any legal execution;
+- a conservative bound is not a precise demand: its derivation must be traceable to a semantic reason, and replacement must preserve workload facts unchanged.
+
+The current inference slice already implements this role: `PlanTransformerInferencePass` emits a `workspace-upper-bound` buffer with role `WORKSPACE`, storage `TRANSIENT`, and semantic `block_working_upper_bound`. Implementation-specific workspace replacement is an obligation of the portable-to-concrete gate. The phase-plan semantics on the inference side are described in [Inference Planning and Serving Simulation](../../modeling/inference.md).
+
 ### Verification
 
 The verifier checks task-reference integrity, DAG closure, buffer lifecycle consistency, resource-requirement validity, exact nonnegative work facts, objective and constraint identity, source lineage, and the absence of target-bound fields.

docs/design/ir/planning-execution.zh.md

@@ -26,6 +26,16 @@ PortablePlanIR
 
 Portable plan 不能包含 physical implementation ID、vendor library、physical device、route、queue、engine、memory bank、address、target-derived latency 或 execution timestamp。
 
+### 抽象工作空间与保守上界
+
+`WORKSPACE` buffer role 表达 portable 层的抽象工作内存（transient scratch）。它是容量与 legality 约束，不是 timing fact：
+
+- 未选定实现时，workspace 只能携带可辩护的保守上界（例如 attention 未融合 score materialization 的容量上界），并记录该 bound 的 semantic；
+- Target binding 必须用 implementation-specific workspace（fused-attention scratch、kernel workspace、paged intermediate 等）替换保守上界，且替换后的分配在任意合法执行下都不得超出 target memory 容量；
+- 保守 bound 不是精确需求：它的推导必须可追溯到语义原因，替换必须保持 workload facts 不变。
+
+当前 inference slice 已实现该角色：`PlanTransformerInferencePass` 发出 `workspace-upper-bound` buffer（role=`WORKSPACE`、storage=`TRANSIENT`、semantic=`block_working_upper_bound`）。Implementation-specific workspace 替换属于 portable-to-concrete gate 的 obligation。推理侧的 phase-plan 语义见[推理规划与 Serving 仿真](../../modeling/inference.md)。
+
 ### Verification
 
 Verifier 检查 task reference integrity、DAG closure、buffer lifecycle consistency、resource-requirement validity、exact nonnegative work fact、objective/constraint identity、source lineage，以及 target-bound field absence。

docs/design/modules.en.md

@@ -6,6 +6,9 @@ Modules follow hardware-experiment ownership, not merely source-file convenience
 
 The future public facade should expose architecture exploration rather than an IR pipeline:
 
+!!! note "Not yet callable"
+    `ExplorationSession` and `blueprinting.explore()` are design targets, not implemented in the current repository. The code below is illustrative pseudocode.
+
 ```python
 experiment = ExplorationSession(
     workloads=WorkloadSuite(...),

docs/design/modules.zh.md

@@ -6,6 +6,9 @@
 
 未来 public facade 应暴露 architecture exploration，而不是一条 IR pipeline：
 
+!!! note "当前不可调用"
+    `ExplorationSession` 与 `blueprinting.explore()` 是设计目标，当前仓库尚未实现。以下代码是说明性伪代码。
+
 ```python
 experiment = ExplorationSession(
     workloads=WorkloadSuite(...),

docs/design/numerical-analysis.en.md

@@ -0,0 +1,52 @@
+# Floating-Point Numerical Analysis
+
+Blueprinting's interactive floating-point analysis is a **numerical-fact exploration surface** in the workspace. It decodes IEEE-style binary floating-point formats, exposes dynamic range and representable values, and quantifies quantization and overflow/underflow risk for candidate datatypes. It is a presentation analysis view — it predicts neither execution time nor hardware behavior, and it does not define workload semantics.
+
+## Scope and motivation
+
+Datatype is a first-class workload fact: `WorkloadFacts` and plan buffers carry exact datatype and bytes-per-element, and Transformer derivation treats precision as a semantic input (see [workload model](../modeling/workload.md)). Before committing a blueprint or mapping to a datatype (bf16 vs fp16 vs fp8), an architect needs numerical questions answered:
+
+- what the format actually represents (dynamic range, subnormal region, Inf/NaN);
+- how large the nearest-value quantization error is at the magnitudes the workload produces;
+- which operations (add, subtract, multiply, divide) risk underflow or overflow at the format's limits.
+
+The floating-point panel answers these questions interactively, for standard formats and arbitrary custom layouts.
+
+## Analysis surface
+
+The panel exposes five connected views over one selected format.
+
+### Format layout comparison
+
+Standard presets — `fp32`, `tf32`, `bf16`, `fp16`, `fp8(E5M2)`, `fp8(E4M3)`, `fp4(E2M1)` — plus a custom format defined by sign bit (optional), exponent bits (`2..8`), and mantissa bits (`0..23`). The layout chart compares sign/exponent/mantissa widths across formats.
+
+### Bit-level decoding
+
+A bit editor decodes one concrete pattern with IEEE zero/subnormal/special handling: all-zero exponent with zero fraction is zero; all-zero exponent with nonzero fraction is subnormal; all-ones exponent with zero fraction is infinity; all-ones exponent with nonzero fraction is NaN. The decode shows category, raw exponent, significand, and value.
+
+### Dynamic range and representable values
+
+For the selected format the panel reports bias, min normal, min subnormal, and max finite. The representable-values view enumerates finite values within the observation window and marks normal (blue) and subnormal (red) regions.
+
+### Quantization error
+
+The nearest-value quantization error curve samples a dense input range and reports the absolute error to the nearest representable value, exposing the format's precision at the magnitudes of interest.
+
+### Operation range impact
+
+A Cartesian sample over up to 64 downsampled representable values runs `A + B`, `A − B`, `A × B`, and `A ÷ B`, and counts results that stay normal, become subnormal, underflow to zero, or overflow to Inf/NaN. This is numerical range analysis, not hardware execution time.
+
+## Place in the analysis architecture
+
+- The analysis functions are pure and deterministic; they live in `src/blueprinting/workbench/float_analysis.py`, with value enumeration in `src/blueprinting/fp/`.
+- The panel does not consume `ModelIR`, `PortablePlanIR`, or any canonical IR. It is an independent interactive surface, not a derived view of a canonical plan.
+- It produces no cost estimates, so it is not a cost provider and never enters the evidence-resolution path.
+- Interactive enumeration is intentionally bounded to formats with exponent + mantissa bits ≤ 12 to keep the UI responsive.
+
+## Current boundary and next steps
+
+**Implemented:** the pure analysis functions, the workbench panel, and unit tests covering dynamic range, bit decoding, enumeration limits, and operation-impact completeness.
+
+**Not yet implemented:** coupling the analysis to workload datatype bindings, deriving per-operation quantization/overflow guardrails for a training or inference plan, and fp8 scaling-policy analysis. A future slice could expose numerical facts as an analysis addressed by a plan's datatype digest, without changing workload semantics.
+
+The workspace that hosts the panel is described in [Exploration Workspace](../exploration/workspace.md); project-wide implementation status is tracked in [Implementation Status](../project/status.md).

docs/design/numerical-analysis.zh.md

@@ -0,0 +1,52 @@
+# 浮点数数值分析
+
+Blueprinting 的交互式浮点分析是工作空间中的一块**数值事实探索面**。它解码 IEEE 风格二进制浮点格式，暴露动态范围与可表示值，并量化候选 datatype 的量化误差与溢出/下溢风险。它是 presentation analysis view——既不预测执行时间，也不描述硬件行为，更不定义 workload semantic。
+
+## 范围与动机
+
+Datatype 是 first-class workload fact：`WorkloadFacts` 与 plan buffer 携带精确 datatype 与 bytes-per-element，Transformer 推导把 precision 当作 semantic 输入（详见 [workload 模型](../modeling/workload.md)）。在把 blueprint 或 mapping 承诺给某个 datatype（bf16 vs fp16 vs fp8）之前，架构师需要回答数值问题：
+
+- 该格式实际能表示什么（动态范围、subnormal 区域、Inf/NaN）；
+- 在 workload 关心的 magnitude 上，nearest-value 量化误差有多大；
+- 加减乘除哪些运算在格式边界处会下溢或溢出。
+
+浮点面板对标准格式与任意自定义布局交互式回答这些问题。
+
+## 分析视图
+
+面板围绕一个选定格式暴露五块相互关联的视图。
+
+### 格式位宽对比
+
+标准预设——`fp32`、`tf32`、`bf16`、`fp16`、`fp8(E5M2)`、`fp8(E4M3)`、`fp4(E2M1)`——以及由符号位（可选）、指数位（`2..8`）与尾数位（`0..23`）定义的自定义格式。位宽图跨格式比较 sign/exponent/mantissa 宽度。
+
+### 位级解码
+
+位编辑器按 IEEE zero/subnormal/special 规则解码一个具体 bit pattern：指数全 0 且 fraction 为 0 是 zero；指数全 0 且 fraction 非 0 是 subnormal；指数全 1 且 fraction 为 0 是 infinity；指数全 1 且 fraction 非 0 是 NaN。解码显示 category、raw exponent、significand 与 value。
+
+### 动态范围与可表示值
+
+面板报告选定格式的 bias、min normal、min subnormal 与 max finite。可表示值视图在观察窗口内枚举有限值，并标出 normal（蓝）与 subnormal（红）区域。
+
+### 量化误差
+
+Nearest-value 量化误差曲线对密集输入范围采样，报告到最近可表示值的绝对误差，暴露该格式在关注 magnitude 上的精度。
+
+### 四则运算范围影响
+
+对最多 64 个降采样的可表示值做笛卡尔组合，执行 `A + B`、`A − B`、`A × B`、`A ÷ B`，统计结果停留在 normal、落入 subnormal、下溢为零或溢出为 Inf/NaN 的计数。这是数值范围分析，不是硬件执行时间。
+
+## 在分析架构中的位置
+
+- 分析函数是纯函数且确定：位于 `src/blueprinting/workbench/float_analysis.py`，可表示值枚举位于 `src/blueprinting/fp/`。
+- 面板不消费 `ModelIR`、`PortablePlanIR` 或任何 canonical IR。它是独立交互面，不是 canonical plan 的 derived view。
+- 它不产生 cost estimate，因此不是 cost provider，也从不进入 evidence resolution 路径。
+- 交互式枚举被刻意限制在 exponent + mantissa ≤ 12 位的格式，以保持 UI 响应。
+
+## 当前边界与后续
+
+**已实现**：纯分析函数、workbench 面板，以及覆盖动态范围、位解码、枚举限制与运算影响完整性的单元测试。
+
+**未实现**：与 workload datatype binding 联动、为 training/inference plan 推导 per-operation 量化/溢出 guardrail，以及 fp8 scaling-policy 分析。未来的 slice 可以把数值事实暴露为按 plan 的 datatype digest 寻址的 analysis，而不改变 workload semantic。
+
+承载该面板的探索工作空间见[探索工作空间](../exploration/workspace.md)；全项目实现状态以[实现状态](../project/status.md)为准。

docs/design/performance/providers.en.md

@@ -75,7 +75,7 @@ from blueprinting.analysis import (
     SimulatorPerformanceImporter,
     TabularImportSpec,
 )
-from blueprinting.synthesizer.frozen import FrozenDict
+from blueprinting.schema.frozen import FrozenDict
 
 spec = TabularImportSpec(
     name="noc-sim-r7",

docs/design/performance/providers.zh.md

@@ -75,7 +75,7 @@ from blueprinting.analysis import (
     SimulatorPerformanceImporter,
     TabularImportSpec,
 )
-from blueprinting.synthesizer.frozen import FrozenDict
+from blueprinting.schema.frozen import FrozenDict
 
 spec = TabularImportSpec(
     name="noc-sim-r7",

docs/exploration/index.en.md

@@ -101,4 +101,4 @@ Today the repository has a strong workload-accounting and formal-analysis founda
 
 It does not yet expose a first-class `ArchitectureBlueprint`, broad hardware design-space search, a connected discrete-event simulator, energy/area/cost models, or Pareto exploration. These are the next product-defining slices and are tracked in [implementation status](../project/status.md) and the [roadmap](../project/roadmap.md).
 
-Continue with the [hardware design space](design-space.md), then follow the [exploration workflow](workflow.md).
+Continue with the [hardware design space](design-space.md), then follow the [exploration workflow](workflow.md). The interactive entry point is the [exploration workspace](workspace.md).

docs/exploration/index.zh.md

@@ -101,4 +101,4 @@ workload semantics
 
 当前还没有 first-class `ArchitectureBlueprint`、广泛 hardware design-space search、贯通的 discrete-event simulator、energy/area/cost model 或 Pareto exploration。这些是下一批定义产品的纵向切片，记录在[实现状态](../project/status.md)与[路线图](../project/roadmap.md)中。
 
-接下来阅读[硬件设计空间](design-space.md)，然后沿[探索工作流](workflow.md)继续。
+接下来阅读[硬件设计空间](design-space.md)，然后沿[探索工作流](workflow.md)继续。交互式探索入口见[探索工作空间](workspace.md)。

docs/exploration/workspace.en.md

@@ -0,0 +1,49 @@
+# Exploration Workspace
+
+The exploration workspace is the interactive surface of the Blueprinting workbench: a single-page NiceGUI application backed by the framework-neutral `BlueprintingService`. It is a presentation layer over the analysis stack — it introduces no new semantic layer and never becomes an alternative source of workload truth.
+
+!!! note "Terminology"
+    “Workspace” appears in two distinct senses in the documentation: this page describes the workbench's **exploration workspace** (the interactive views for four modes); `PortablePlanIR` separately defines the `WORKSPACE` buffer role, a capacity constraint for abstract working memory, in [Planning and Execution IR](../design/ir/planning-execution.md).
+
+## What the workspace is
+
+The workspace renders one of four mode views, all sharing the same configuration surface. Analysis runs outside the UI event loop; a result is shared across views and marked stale after configuration changes; failed candidates remain visible as structured diagnostics instead of vanishing silently. It consumes the framework-neutral services in `application/` and shares the same typed contracts as the CLI.
+
+## Shared configuration surface
+
+Point and batch modes share one configuration dialog: model/execution presets (from the retained JSON presets in `data/`), TP/PP/DP topology, calibration mode (system-evidence curve vs theoretical peak baseline), and candidate bounds. Quick controls and the full configuration stay in sync.
+
+## Workspace modes
+
+### Point lens
+
+Focuses on one case: runs the `ModelIR -> DistributedTaskIR -> PortablePlanIR` derivation, resolves evidence estimates, and shows task-level contributions, resource constraints, and evidence boundaries. A failed derivation keeps a diagnostic with lineage instead of fabricating a performance number.
+
+### Batch lens
+
+Treats a set of TP/PP/DP cases as a whole: each case derives independently, exposing distributions, upper/lower bounds, and the feasible boundary while shrinking the candidate space. Failed items retain status and diagnostics and participate in the distribution statistics.
+
+### Evidence lab
+
+A read-only evidence catalog: pinned Vidur Phi-2/A100 records with exact selectors. GEMM primitives compare measured versus analytical roofline on identical workload facts; the measured series shows exact sample points without claiming interpolation; attention and other operations appear in the coverage catalog only.
+
+### Numeric lens
+
+Hosts the [Floating-Point Numerical Analysis](../design/numerical-analysis.md) panel: formats, encoding, dynamic range, and operation boundaries. It is usable independently of workload analysis and does not require running a derivation first.
+
+## Workspace invariants
+
+- no eager analysis on load;
+- analysis executes outside the UI event loop (`io_bound`), keeping the interface responsive;
+- a single result is shared across views and marked stale after configuration changes;
+- sweep candidates retain per-case status and failure diagnostics;
+- evidence is read-only: the lab never writes back to evidence or canonical IR;
+- the optional portable dependency Chrome Trace export is explicitly marked `executable=false` and is not a `TimelineBundle`.
+
+## Architecture relationship
+
+The workbench consumes `application/` services and presents canonical derivation audits, cost resolution, and evidence catalogs. It does not construct canonical plans itself; every analysis entry point shares the typed contracts and session bindings of the CLI.
+
+## Current boundary
+
+The workspace is an analysis and audit surface, not a simulator. It has no first-class `ArchitectureBlueprint` editing, no design-space search, and no discrete-event simulation; those remain planned product slices (see [Implementation Status](../project/status.md) and the [exploration workflow](workflow.md)).