@calcit/procs 0.12.9 → 0.12.10

package/editing-history/2026-0313-2216-validate-struct-type-arg-arity.md

@@ -0,0 +1,24 @@
+# 2026-03-13 22:16 validate struct type arg arity
+
+## 背景
+
+发现类型注解里可以写出 `:: Pair :number :string` 这样的形式，即使 `Pair` 是非泛型 `defstruct`。旧逻辑会把后续类型参数直接附着到 `Struct(...)` 注解上，但并不会校验 `generics` 个数，最终在值匹配时只看 struct 名字，导致漏检。
+
+## 本次修改
+
+- 在 `src/calcit/type_annotation.rs` 为 `CalcitTypeAnnotation` / `CalcitFnTypeAnnotation` 增加 `validate_applied_type_args()`。
+- 对 `Struct` 注解增加规则：
+  - 非泛型 struct 不允许携带类型参数；
+  - 泛型 struct 必须严格匹配声明的类型参数个数。
+- 对 `Enum` 注解增加保守规则：当前不接受额外类型参数。
+- 在 `src/builtins/records.rs` 中，`defstruct` 字段类型解析后立即做校验。
+- 在 `src/calcit/sum_type.rs` 中，`defenum` payload 类型解析后立即做校验。
+- 在 `src/calcit/sum_type.rs` 与 `src/calcit/type_annotation.rs` 补充回归测试，覆盖：
+  - 非泛型 struct 带类型参数时报错；
+  - 泛型 struct 类型参数个数不匹配时报错；
+  - enum payload 中引用非法 struct 类型注解时报错。
+- 同时修正 `calcit/test-generics.cirru` 中 `Wrapped` 的 payload 类型，把错误的 `:: Pair :number :string` 改为 `Pair`。
+
+## 结论
+
+现在像 `:: Pair :number :string` 这种写法不会再静默通过；定义期就会被校验出来，避免文档和测试继续误导后续修改。

package/editing-history/2026-0316-1449-profiling-tools-reorg.md

@@ -0,0 +1,13 @@
+# Profiling tools reorganization
+
+## Summary
+
+- Moved profiling scripts from `scripts/` into dedicated `profiling/` directory.
+- Added `profiling/README.md` with end-to-end usage for xctrace and samply workflows.
+- Removed obsolete `scripts/profiling.sh` flamegraph helper script.
+
+## Knowledge notes
+
+- Keep profiling tooling isolated under `profiling/` to reduce script namespace clutter.
+- `samply` profiling should run against built `target/*/cr` binaries to avoid sampling `rustc` compile threads.
+- Preserve `.tmp-profiles/` as transient output directory for trace artifacts.

package/editing-history/2026-0316-2353-runtime-boundary-cleanup.md

@@ -0,0 +1,14 @@
+# Runtime Boundary Cleanup
+
+## Summary
+
+- removed the dead `CalcitImport.coord` compatibility path and the related runner parameter flow
+- renamed remaining `evaled`-era runtime lookup terminology to `runtime-ready` / `runtime cache`
+- synced the runtime boundary refactor draft with the current migration state and recent cleanup progress
+
+## Knowledge
+
+- `CalcitImport.def_id` is now the stable import-side runtime lookup anchor; the old `coord -> EntryBook` path no longer needs to be preserved in import metadata
+- type-annotation lookup registration should describe runtime-ready value lookup, not the removed evaled-store model
+- incremental reload messaging should talk about clearing runtime caches rather than evaled states to match the current architecture
+- this migration tail is now mostly about narrowing fallback bridges and improving reload coverage, not about preserving old runtime naming or lookup compatibility

package/editing-history/2026-0317-0150-runtime-boundary-lookup-cleanup.md

@@ -0,0 +1,28 @@
+# Runtime boundary lookup cleanup
+
+## Summary
+
+- Consolidated runtime-vs-compiled lookup helpers inside `program` and removed extra `runner` bridging paths.
+- Tightened snapshot fallback and codegen metadata lookup so source-backed defs no longer silently rely on runtime-derived compiled entries.
+- Skipped runtime-only placeholder defs in JS/IR codegen and added program-level regression tests for reload invalidation and snapshot behavior.
+- Reframed the runtime-boundary draft into a closure plan focused on stabilizing compiled/runtime boundaries, adding watch-reload regression coverage, and avoiding new architectural layers.
+- Simplified `runner` and `preprocess` lookup flow by removing thin wrappers, deduplicating repeated symbol fallback order, and collapsing silent program-value reads onto shared helpers.
+- Added regression coverage for reload package clearing, source-backed snapshot rebuild after changes, compiled fallback cache behavior, and strict-vs-lenient runtime resolution semantics.
+
+## Knowledge points
+
+- Runtime execution helpers should live in `program` so `runner` only maps runtime state to evaluation flow and user-facing errors.
+- Metadata queries such as codegen type hints should prefer compiled/source schema and only fall back to ready runtime values, never by executing compiled payloads.
+- Reload invalidation needs direct transitive-dependency tests plus namespace-header coverage; otherwise runtime cache cleanup regresses quietly.
+- If compiled execution is used as a fallback read path, tests must assert it does not implicitly backfill runtime cells; otherwise compiled/runtime boundaries drift back together.
+- Keep cleanup work biased toward removing duplicate lookup order and unused parameters before introducing any new abstraction; the stable payoff is clearer boundaries with lower entity count.
+- `runner`-side error mapping for strict runtime resolution is still a meaningful boundary, but repeated namespace lookup order and required-value program reads can be shared safely.
+
+## Validation
+
+- `cargo fmt`
+- release fibo profiling during optimization review
+- `cargo test clear_runtime_caches_for_reload -- --nocapture`
+- `cargo test snapshot_rebuilds_changed_source_backed_def_after_reload_changes -- --nocapture`
+- `cargo test program::tests -- --nocapture`
+- `cargo test -q`

package/editing-history/2026-0317-2026-afternoon-runtime-boundary-optimization-summary.md

@@ -0,0 +1,87 @@
+# 2026-03-17 下午至晚间改动总结（1739-2031）
+
+## 总览
+
+- 时间段：`2026-0317-1739` 至 `2026-0317-2031`
+- 主要改动：测试减法、program/preprocess 架构减法、类型注解热路径优化、samply 验证、计划文档同步
+
+## 关键变更（按时间顺序）
+
+### 1) 测试减法（1739 / 1745）
+
+- 清理 `src/program/tests.rs` 中 helper/重复语义测试：
+  - `runtime_snapshot_fallback_only_allows_runtime_only_defs`
+  - `preprocess_ns_def_accepts_compiled_only_value_without_source_lookup`
+- 保留行为级回归用例，继续覆盖 snapshot/runtime-only 与 compiled-only 消费边界。
+
+### 2) preprocess 推断逻辑去重（1751）
+
+- 文件：`src/runner/preprocess.rs`
+- 抽取 `infer_return_type_from_compiled_callable(...)`，统一 `Import`/`Symbol` 分支的 compiled callable 返回类型推断。
+- 保留 `Symbol` 分支对源码 tag 的回退解析行为。
+
+### 3) program snapshot helper 内联（1753）
+
+- 文件：`src/program.rs`
+- 删除并内联单次用途 helper：
+  - `collect_referenced_compiled_def_ids(...)`
+  - `should_use_runtime_snapshot_fallback(...)`
+- 逻辑并入 `collect_snapshot_fill_tasks(...)` 与 `build_snapshot_fill_compiled_def(...)`。
+
+### 4) 文档刷新 + 首轮热路径减法（1812）
+
+- 文件：`drafts/runtime-boundary-refactor-plan.md`
+  - 修正过时描述：`run_program_with_docs` 现状与 preprocess 返回值关系。
+  - 将阶段状态与 `samply` 观察、下一步优先级对齐。
+- 文件：`src/runner/preprocess.rs`
+  - 去除 `drop_left` 中间列表分配。
+  - `resolve_generic_return_type` 改为接收迭代器，调用处直接 `iter().skip(1)`。
+
+### 5) materialize executable fast path（2012）
+
+- 文件：`src/program.rs`
+- `materialize_compiled_executable_payload(...)`：
+  - `Proc | Syntax` 直接返回 `preprocessed_code`。
+  - `Fn | Macro` 继续 `evaluate_expr` materialize。
+  - `LazyValue | Value` 继续保持不可执行语义。
+- 删除无调用 helper：`with_compiled_executable_payload(...)`。
+
+### 6) type-annotation 单次扫描收敛（2023）
+
+- 文件：`src/calcit/type_annotation.rs`
+- 在 `parse_fn_annotation_from_schema_form` 中引入 `collect_fn_schema_fields`，由多次 key 扫描改为一次遍历收集。
+- 删除无用 helper：`schema_has_any_field`。
+
+### 7) schema key 热路径进一步减法（2031）
+
+- 文件：`src/calcit/type_annotation.rs`
+- 新增单 key 快路径：
+  - `schema_key_matches(...)`
+  - `extract_schema_value_single(...)`
+- 将常见单 key 查询点改为快路径：
+  - `extract_return_type_from_hint_form`
+  - `extract_generics_from_hint_form`
+  - `extract_arg_types_from_hint_form`
+- 清理过渡遗留 helper：
+  - `schema_key_matches_any(...)`
+  - `extract_schema_value(...)`
+
+## 验证汇总
+
+- 多轮定向测试均通过：
+  - `cargo test -q program::tests`
+  - `cargo test -q runner::preprocess::tests`
+  - `cargo test -q calcit::type_annotation::tests`
+- 全量 Rust 测试持续通过：`cargo test -q`（会话末保持全绿）
+- 语义门禁持续通过：`yarn check-all`
+
+## profiling 结论汇总
+
+- 使用既有流程：`profiling/samply-once.sh` + `profiling/samply-summary.py`
+- 在 materialize 目标链路过滤中，样本权重由 14 降至 7（单轮观测，方向符合预期）。
+- 在 schema-key 相关过滤中，基线 `fibo-release-iter5-20260317.samply` 为 21，本轮新采样 `fibo-release-20260317-203129.samply` 为 5，方向上显著下降。
+
+## 本轮经验
+
+- 以“删 helper/删重复分支/删中间分配”为主线做减法，优先保证行为级测试覆盖。
+- 每次改动后固定执行“定向测试 → 全量 Rust → `yarn check-all`”可有效阻断语义回退。

package/editing-history/2026-0318-1802-tips-level-and-overwrite-schema-preservation.md

@@ -0,0 +1,26 @@
+## Summary
+
+This commit finalizes two CLI workflow improvements:
+
+1. **Tips policy refactor**
+   - Added `--tips-level` support (`minimal|full|none`) as a unified switch.
+   - Kept `--tips` as a shortcut for full tips output.
+   - Updated handlers so tips rendering is centralized and priority-aware.
+   - Updated docs to align with the new default behavior (minimal, high-priority-first hints).
+
+2. **`cr edit def --overwrite` metadata safety**
+   - Fixed overwrite behavior to preserve existing definition metadata (`doc`, `examples`, `schema`).
+   - Overwrite now updates only the `code` field when the definition already exists.
+   - This avoids accidental schema loss during whole-definition rewrites.
+
+## Files touched (high level)
+
+- CLI args and command wiring for tips level handling.
+- Query/tree/tips handler integration and output behavior updates.
+- `edit` handler overwrite logic for metadata-preserving updates.
+- Agent docs and advanced workflow docs reflecting the new tips model.
+
+## Validation notes
+
+- Rust formatting/lint/tests were run during implementation iterations.
+- Manual end-to-end verification confirmed schema is retained after `--overwrite`.

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.12.9",
+    "version": "0.12.10",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.0.9",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.12.9",
+  "version": "0.12.10",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.0.9",

package/profiling/README.md

@@ -0,0 +1,84 @@
+# Profiling 工具说明
+
+本目录集中放置 calcit 的 profiling 脚本：
+
+- `profile-once.sh`：基于 `xctrace Time Profiler` 一键录制并汇总。
+- `profile-summary.py`：解析 `xctrace` 导出的 XML 热点。
+- `samply-once.sh`：基于 `samply` 一键录制并汇总（函数级 self-time）。
+- `samply-summary.py`：解析 `.samply` 并输出热点函数占比。
+
+## 1) xctrace 路线
+
+### 一键执行
+
+```bash
+profiling/profile-once.sh calcit/fibo.cirru --top 20 --include 'calcit::'
+```
+
+输出：
+
+- `.tmp-profiles/<entry>-<timestamp>.trace`
+- 终端中的热点函数统计、前缀聚合和优化提示
+
+### 仅汇总已有 trace/xml
+
+```bash
+python3 profiling/profile-summary.py --trace .tmp-profiles/fibo-xxxx.trace --top 30
+python3 profiling/profile-summary.py --xml /path/to/time-profile.xml --top 30
+```
+
+常用参数：
+
+- `--top N`：显示前 N 个热点
+- `--include REGEX`：仅保留匹配符号（可重复）
+- `--exclude REGEX`：排除匹配符号（可重复）
+- `--keep-xml`：保留由 trace 导出的临时 XML
+
+## 2) samply 路线（更精准函数级）
+
+### 一键执行（debug）
+
+```bash
+profiling/samply-once.sh calcit/fibo.cirru --top 20 --collapse-hash
+```
+
+### 一键执行（release）
+
+```bash
+profiling/samply-once.sh calcit/fibo.cirru --release --top 20 --include 'calcit::|im_ternary_tree|alloc::'
+```
+
+输出：
+
+- `.tmp-profiles/<entry>-<mode>-<timestamp>.samply`
+- 终端中的函数级 self-time 热点（含占比）
+
+### 仅汇总已有 `.samply`
+
+```bash
+python3 profiling/samply-summary.py --input .tmp-profiles/fibo-debug-xxxx.samply --binary target/debug/cr --top 30
+```
+
+release 对应：
+
+```bash
+python3 profiling/samply-summary.py --input .tmp-profiles/fibo-release-xxxx.samply --binary target/release/cr --top 30
+```
+
+常用参数：
+
+- `--thread INDEX`：指定线程，默认自动选择样本最多线程
+- `--collapse-hash`：折叠 Rust 哈希后缀，便于分组
+- `--image-base 0x100000000`：`atos` 符号化基址（默认值）
+- `--include / --exclude`：正则过滤
+
+## 依赖
+
+- xctrace 路线：`xctrace`, `cargo`, `python3`
+- samply 路线：`samply`, `cargo`, `python3`
+- 可选（samply 地址回填）：`atos`（macOS 自带）
+
+## 说明
+
+- `samply-once.sh` 会先 `cargo build`，再直接对 `target/debug/cr` 或 `target/release/cr` 录制，避免把 `rustc` 编译过程混入热点。
+- 临时产物位于 `.tmp-profiles/`，可按需清理。

package/profiling/profile-once.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+  echo "Usage: profiling/profile-once.sh <entry.cirru> [profile-summary args...]" >&2
+  echo "Example: profiling/profile-once.sh calcit/fibo.cirru --top 20 --include 'calcit::'" >&2
+  exit 1
+fi
+
+entry="$1"
+shift
+
+if [[ ! -f "$entry" ]]; then
+  echo "Entry file not found: $entry" >&2
+  exit 2
+fi
+
+for cmd in xctrace cargo python3; do
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    echo "Missing required command: $cmd" >&2
+    exit 2
+  fi
+done
+
+mkdir -p .tmp-profiles
+
+entry_name="$(basename "$entry" .cirru)"
+stamp="$(date +%Y%m%d-%H%M%S)"
+trace_path=".tmp-profiles/${entry_name}-${stamp}.trace"
+
+echo "Recording trace to: $trace_path"
+xctrace record \
+  --template "Time Profiler" \
+  --output "$trace_path" \
+  --launch -- \
+  cargo run --release --bin cr -- "$entry"
+
+echo
+echo "Summarizing hotspots..."
+python3 profiling/profile-summary.py --trace "$trace_path" "$@"
+
+echo
+echo "Done. Trace bundle: $trace_path"

package/profiling/profile-summary.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import xml.etree.ElementTree as ET
+from collections import Counter
+from pathlib import Path
+
+
+def export_time_profile_xml(trace_path: Path, xml_path: Path) -> None:
+  cmd = [
+    "xctrace",
+    "export",
+    "--input",
+    str(trace_path),
+    "--xpath",
+    '/trace-toc/run[@number="1"]/data/table[@schema="time-profile"]',
+    "--output",
+    str(xml_path),
+  ]
+  result = subprocess.run(cmd, capture_output=True, text=True)
+  if result.returncode != 0:
+    stderr = result.stderr.strip() or "(no stderr)"
+    raise RuntimeError(f"xctrace export failed: {stderr}")
+
+
+def parse_frame_names(xml_path: Path) -> Counter[str]:
+  counts: Counter[str] = Counter()
+  for _, elem in ET.iterparse(xml_path, events=("end",)):
+    if elem.tag == "frame":
+      name = elem.attrib.get("name")
+      if name:
+        counts[name] += 1
+    elem.clear()
+  return counts
+
+
+def compile_patterns(patterns: list[str]) -> list[re.Pattern[str]]:
+  compiled = []
+  for pattern in patterns:
+    compiled.append(re.compile(pattern))
+  return compiled
+
+
+def filter_counts(
+  counts: Counter[str],
+  include_patterns: list[re.Pattern[str]],
+  exclude_patterns: list[re.Pattern[str]],
+) -> Counter[str]:
+  if not include_patterns and not exclude_patterns:
+    return counts
+
+  filtered: Counter[str] = Counter()
+  for name, count in counts.items():
+    if include_patterns and not any(regex.search(name) for regex in include_patterns):
+      continue
+    if exclude_patterns and any(regex.search(name) for regex in exclude_patterns):
+      continue
+    filtered[name] = count
+  return filtered
+
+
+def summarize_by_prefix(counts: Counter[str]) -> list[tuple[str, int]]:
+  group = Counter()
+  for name, count in counts.items():
+    parts = name.split("::")
+    if len(parts) >= 2:
+      key = "::".join(parts[:2])
+    else:
+      key = parts[0]
+    group[key] += count
+  return group.most_common(10)
+
+
+def derive_hints(counts: Counter[str]) -> list[str]:
+  joined = "\n".join(counts.keys())
+  hints: list[str] = []
+  if re.search(r"calcit::runner::(call_expr|evaluate_expr|run_fn_owned)", joined):
+    hints.append("解释器调度路径是主要热点，可优先检查 `call_expr`/`evaluate_expr` 的分支和数据转换。")
+  if re.search(r"CalcitProc::get_type_signature|check_proc_arity|type_annotation", joined):
+    hints.append("运行时类型签名/arity 检查占比不低，可考虑缓存签名结果或减少重复检查路径。")
+  if re.search(r"im_ternary_tree::.*to_vec|CalcitList::to_vec|drop_left", joined):
+    hints.append("持久结构与 Vec 转换频繁，建议减少 `to_vec` 往返或批量化访问。")
+  if re.search(r"alloc::|RawVec|drop::|triomphe::|rpds::", joined):
+    hints.append("分配与释放开销明显，建议优先减少短生命周期对象和临时容器创建。")
+  return hints
+
+
+def parse_args() -> argparse.Namespace:
+  parser = argparse.ArgumentParser(
+    description="Summarize xctrace Time Profiler output into LLM-friendly hotspot text."
+  )
+  parser.add_argument("--trace", type=Path, help="Path to .trace bundle generated by xctrace")
+  parser.add_argument("--xml", type=Path, help="Path to exported time-profile XML")
+  parser.add_argument("--top", type=int, default=30, help="Number of top hotspot functions")
+  parser.add_argument(
+    "--include",
+    action="append",
+    default=[],
+    help="Regex include filter for symbol names (repeatable)",
+  )
+  parser.add_argument(
+    "--exclude",
+    action="append",
+    default=[],
+    help="Regex exclude filter for symbol names (repeatable)",
+  )
+  parser.add_argument(
+    "--keep-xml",
+    action="store_true",
+    help="Keep temporary XML when using --trace",
+  )
+  args = parser.parse_args()
+  if not args.trace and not args.xml:
+    parser.error("One of --trace or --xml is required")
+  if args.trace and args.xml:
+    parser.error("Use only one of --trace or --xml")
+  if args.top <= 0:
+    parser.error("--top must be > 0")
+  return args
+
+
+def main() -> int:
+  args = parse_args()
+
+  xml_path: Path
+  temp_dir = None
+  if args.trace:
+    if not args.trace.exists():
+      print(f"Trace file not found: {args.trace}", file=sys.stderr)
+      return 2
+    temp_dir = tempfile.TemporaryDirectory(prefix="xctrace-export-")
+    xml_path = Path(temp_dir.name) / "time-profile.xml"
+    try:
+      export_time_profile_xml(args.trace, xml_path)
+    except RuntimeError as error:
+      print(str(error), file=sys.stderr)
+      return 3
+    if args.keep_xml:
+      kept = args.trace.parent / f"{args.trace.name}.time-profile.xml"
+      kept.write_bytes(xml_path.read_bytes())
+      print(f"Saved exported XML to: {kept}")
+  else:
+    xml_path = args.xml
+    if not xml_path.exists():
+      print(f"XML file not found: {xml_path}", file=sys.stderr)
+      return 2
+
+  counts = parse_frame_names(xml_path)
+  include_patterns = compile_patterns(args.include)
+  exclude_patterns = compile_patterns(args.exclude)
+  filtered = filter_counts(counts, include_patterns, exclude_patterns)
+
+  total_frames = sum(counts.values())
+  filtered_frames = sum(filtered.values())
+  print(f"Source XML: {xml_path}")
+  print(f"Total named frames: {total_frames}")
+  print(f"Frames after filter: {filtered_frames}")
+  print()
+
+  print(f"Top {args.top} Hotspots")
+  print("-" * 72)
+  if not filtered:
+    print("(no matched symbols)")
+  else:
+    for name, count in filtered.most_common(args.top):
+      ratio = (count / filtered_frames * 100.0) if filtered_frames else 0.0
+      print(f"{count:6d}  {ratio:6.2f}%  {name}")
+
+  print()
+  print("Top Prefix Groups")
+  print("-" * 72)
+  for group, count in summarize_by_prefix(filtered):
+    ratio = (count / filtered_frames * 100.0) if filtered_frames else 0.0
+    print(f"{count:6d}  {ratio:6.2f}%  {group}")
+
+  print()
+  print("Optimization Hints")
+  print("-" * 72)
+  hints = derive_hints(filtered)
+  if not hints:
+    print("- 无明显通用模式，请结合 Top Hotspots 逐个函数分析。")
+  else:
+    for hint in hints:
+      print(f"- {hint}")
+
+  if temp_dir is not None and not args.keep_xml:
+    temp_dir.cleanup()
+  return 0
+
+
+if __name__ == "__main__":
+  raise SystemExit(main())

package/profiling/samply-once.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+  echo "Usage: profiling/samply-once.sh <entry.cirru> [--release] [samply-summary args...]" >&2
+  echo "Example: profiling/samply-once.sh calcit/fibo.cirru --top 20 --include 'calcit::'" >&2
+  echo "Example: profiling/samply-once.sh calcit/fibo.cirru --release --collapse-hash" >&2
+  exit 1
+fi
+
+entry="$1"
+shift
+
+if [[ ! -f "$entry" ]]; then
+  echo "Entry file not found: $entry" >&2
+  exit 2
+fi
+
+mode="debug"
+if [[ "${1:-}" == "--release" ]]; then
+  mode="release"
+  shift
+fi
+
+for cmd in samply cargo python3; do
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    echo "Missing required command: $cmd" >&2
+    exit 2
+  fi
+done
+
+mkdir -p .tmp-profiles
+
+entry_name="$(basename "$entry" .cirru)"
+stamp="$(date +%Y%m%d-%H%M%S)"
+samply_path=".tmp-profiles/${entry_name}-${mode}-${stamp}.samply"
+
+if [[ "$mode" == "release" ]]; then
+  build_args=(build --release --bin cr)
+  binary="target/release/cr"
+else
+  build_args=(build --bin cr)
+  binary="target/debug/cr"
+fi
+
+echo "Building binary: $binary"
+cargo "${build_args[@]}"
+
+if [[ ! -f "$binary" ]]; then
+  echo "Expected binary not found after build: $binary" >&2
+  exit 3
+fi
+
+echo "Recording samply profile to: $samply_path"
+samply record --save-only -o "$samply_path" -- "$binary" "$entry"
+
+binary_arg=(--binary "$binary")
+
+echo
+echo "Summarizing hotspots..."
+python3 profiling/samply-summary.py --input "$samply_path" "${binary_arg[@]}" "$@"
+
+echo
+echo "Done. Samply file: $samply_path"

package/profiling/samply-summary.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from collections import Counter
+from pathlib import Path
+
+
+ADDRESS_RE = re.compile(r"^0x[0-9a-fA-F]+$")
+
+
+def parse_args() -> argparse.Namespace:
+  parser = argparse.ArgumentParser(
+    description="Summarize samply JSON into function-level self-time hotspots."
+  )
+  parser.add_argument("--input", type=Path, required=True, help="Path to .samply JSON")
+  parser.add_argument("--top", type=int, default=30, help="Number of top functions")
+  parser.add_argument("--thread", type=int, help="Thread index to analyze (default: auto)")
+  parser.add_argument(
+    "--include",
+    action="append",
+    default=[],
+    help="Regex include filter for symbol names (repeatable)",
+  )
+  parser.add_argument(
+    "--exclude",
+    action="append",
+    default=[],
+    help="Regex exclude filter for symbol names (repeatable)",
+  )
+  parser.add_argument(
+    "--binary",
+    type=Path,
+    help="Mach-O binary for atos symbolization fallback (e.g. target/debug/cr)",
+  )
+  parser.add_argument(
+    "--image-base",
+    type=lambda raw: int(raw, 0),
+    default=0x100000000,
+    help="Image base added to frame address before atos (default: 0x100000000)",
+  )
+  parser.add_argument(
+    "--collapse-hash",
+    action="store_true",
+    help="Collapse Rust symbol hash suffix (::h...) for easier grouping",
+  )
+  args = parser.parse_args()
+  if args.top <= 0:
+    parser.error("--top must be > 0")
+  return args
+
+
+def compile_patterns(patterns: list[str]) -> list[re.Pattern[str]]:
+  return [re.compile(pattern) for pattern in patterns]
+
+
+def choose_thread(data: dict, explicit: int | None) -> tuple[int, dict]:
+  threads = data.get("threads")
+  if not isinstance(threads, list) or not threads:
+    raise ValueError("No threads found in .samply file")
+
+  if explicit is not None:
+    if explicit < 0 or explicit >= len(threads):
+      raise ValueError(f"--thread out of range: {explicit} (total {len(threads)})")
+    return explicit, threads[explicit]
+
+  best_idx = 0
+  best_count = -1
+  for index, thread in enumerate(threads):
+    samples = thread.get("samples", {})
+    stacks = samples.get("stack", [])
+    count = sum(1 for entry in stacks if entry is not None)
+    if count > best_count:
+      best_count = count
+      best_idx = index
+  return best_idx, threads[best_idx]
+
+
+def lookup_frame_symbol(thread: dict, frame_index: int) -> tuple[str, int | None]:
+  frame_table = thread.get("frameTable", {})
+  func_table = thread.get("funcTable", {})
+  native_symbols = thread.get("nativeSymbols", {})
+  strings = thread.get("stringArray", [])
+
+  func_index = frame_table.get("func", [None])[frame_index]
+  if func_index is not None:
+    name_index = func_table.get("name", [None])[func_index]
+    if name_index is not None:
+      symbol = strings[name_index]
+      if ADDRESS_RE.match(symbol):
+        return symbol, int(symbol, 16)
+      return symbol, None
+
+  native_index = frame_table.get("nativeSymbol", [None])[frame_index]
+  if native_index is not None:
+    name_index = native_symbols.get("name", [None])[native_index]
+    if name_index is not None:
+      symbol = strings[name_index]
+      if ADDRESS_RE.match(symbol):
+        return symbol, int(symbol, 16)
+      return symbol, None
+
+  address = frame_table.get("address", [None])[frame_index]
+  if address is not None:
+    return f"0x{address:x}", address
+
+  return "<unknown>", None
+
+
+def atos_symbolize(binary: Path, image_base: int, addresses: list[int]) -> dict[int, str]:
+  if not addresses:
+    return {}
+
+  absolute_addresses = [hex(image_base + address) for address in addresses]
+  cmd = ["atos", "-o", str(binary), *absolute_addresses]
+  result = subprocess.run(cmd, capture_output=True, text=True)
+
+  mapping: dict[int, str] = {}
+  lines = result.stdout.splitlines()
+  for address, line in zip(addresses, lines):
+    symbol = line.strip()
+    if symbol and not ADDRESS_RE.match(symbol):
+      mapping[address] = symbol
+  return mapping
+
+
+def normalize_symbol(raw: str, collapse_hash: bool) -> str:
+  text = raw.strip()
+  if collapse_hash:
+    text = re.sub(r"::h[0-9a-f]{16,}$", "", text)
+  return text
+
+
+def summarize(
+  thread: dict,
+  include_patterns: list[re.Pattern[str]],
+  exclude_patterns: list[re.Pattern[str]],
+  collapse_hash: bool,
+  atos_map: dict[int, str],
+) -> tuple[Counter[str], float]:
+  stack_table = thread.get("stackTable", {})
+  samples = thread.get("samples", {})
+
+  sample_stacks = samples.get("stack", [])
+  weights = samples.get("weight")
+  if not isinstance(weights, list) or len(weights) != len(sample_stacks):
+    weights = [1.0] * len(sample_stacks)
+
+  counts: Counter[str] = Counter()
+  total_weight = 0.0
+  for index, stack_index in enumerate(sample_stacks):
+    if stack_index is None:
+      continue
+    frame_index = stack_table.get("frame", [None])[stack_index]
+    if frame_index is None:
+      continue
+    symbol, address = lookup_frame_symbol(thread, frame_index)
+    if address is not None and address in atos_map:
+      symbol = atos_map[address]
+    symbol = normalize_symbol(symbol, collapse_hash)
+
+    if include_patterns and not any(regex.search(symbol) for regex in include_patterns):
+      continue
+    if exclude_patterns and any(regex.search(symbol) for regex in exclude_patterns):
+      continue
+
+    weight = float(weights[index])
+    counts[symbol] += weight
+    total_weight += weight
+
+  return counts, total_weight
+
+
+def collect_unresolved_addresses(thread: dict, sample_limit: int) -> list[int]:
+  stack_table = thread.get("stackTable", {})
+  sample_stacks = thread.get("samples", {}).get("stack", [])
+  addresses: Counter[int] = Counter()
+
+  for stack_index in sample_stacks:
+    if stack_index is None:
+      continue
+    frame_index = stack_table.get("frame", [None])[stack_index]
+    if frame_index is None:
+      continue
+    symbol, address = lookup_frame_symbol(thread, frame_index)
+    if address is None:
+      continue
+    if ADDRESS_RE.match(symbol):
+      addresses[address] += 1
+
+  return [address for address, _ in addresses.most_common(sample_limit)]
+
+
+def main() -> int:
+  args = parse_args()
+  if not args.input.exists():
+    print(f"Input file not found: {args.input}", file=sys.stderr)
+    return 2
+
+  try:
+    data = json.loads(args.input.read_text())
+  except json.JSONDecodeError as error:
+    print(f"Invalid JSON in {args.input}: {error}", file=sys.stderr)
+    return 2
+
+  try:
+    thread_index, thread = choose_thread(data, args.thread)
+  except ValueError as error:
+    print(str(error), file=sys.stderr)
+    return 2
+
+  include_patterns = compile_patterns(args.include)
+  exclude_patterns = compile_patterns(args.exclude)
+
+  atos_map: dict[int, str] = {}
+  if args.binary is not None:
+    unresolved = collect_unresolved_addresses(thread, sample_limit=max(200, args.top * 10))
+    if unresolved:
+      atos_map = atos_symbolize(args.binary, args.image_base, unresolved)
+
+  counts, total_weight = summarize(
+    thread,
+    include_patterns,
+    exclude_patterns,
+    args.collapse_hash,
+    atos_map,
+  )
+
+  print(f"Input .samply: {args.input}")
+  print(f"Thread index: {thread_index}")
+  print(f"Thread name: {thread.get('name', '<unknown>')}")
+  print(f"Samples after filter (weight): {total_weight:.2f}")
+  if args.binary is not None:
+    print(f"Atos binary: {args.binary}")
+    print(f"Atos symbolized addresses: {len(atos_map)}")
+  print()
+
+  print(f"Top {args.top} Self-Time Hotspots")
+  print("-" * 72)
+  if not counts:
+    print("(no matched symbols)")
+    return 0
+
+  for symbol, weight in counts.most_common(args.top):
+    ratio = (weight / total_weight * 100.0) if total_weight else 0.0
+    print(f"{weight:10.2f}  {ratio:6.2f}%  {symbol}")
+
+  return 0
+
+
+if __name__ == "__main__":
+  raise SystemExit(main())