@calcit/procs 0.12.53 → 0.12.55

package/editing-history/2026-07-28-2158-document-cursor-native-workflows.md

@@ -0,0 +1,13 @@
+# 补充 Cursor 原生工作流文档
+
+## 概要
+
+- RFC 增加 `cursor apply`、`slurp-next`、`barf-last`、`forward/backward` 的命令契约、复用边界和验收项。
+- Agent 快速指南说明同级导航与跨 list 深度优先导航的区别，并加入 cursor 原生 mutation 的选择建议。
+- tree editing 指南补充完整命令示例、`--cursor-after focus` 的导航反馈，以及 `unwrap` 并非任意 wrapper 的严格逆操作这一边界。
+
+## 验证
+
+- `target/debug/cr calcit/test.cirru docs check-md docs/CalcitAgent.md --entry calcit/test.cirru`
+- `target/debug/cr calcit/test.cirru docs check-md docs/run/edit-tree.md --entry calcit/test.cirru`
+- `git diff --check`

package/editing-history/2026-07-29-0022-add-cursor-cli-options.md

@@ -0,0 +1,7 @@
+# Cursor CLI surface
+
+- Added symmetric `slurp-prev` and `barf-first` cursor commands.
+- Added `cursor duplicate --at before|after`.
+- Added `--start-path` to structural expression search.
+
+Validation for the complete change set: `cargo fmt`, `cargo clippy -- -D warnings`, `cargo test`, `yarn compile`, `yarn check-agent-interface`, and `yarn check-all`.

package/editing-history/2026-07-29-0022-audit-cursor-development-scenarios.md

@@ -0,0 +1,6 @@
+# Audit cursor development scenarios
+
+- Mapped the cursor contract to high-frequency development workflows.
+- Specified symmetric Paredit operations, duplication, target aliases, and subtree search.
+- Clarified transaction, source-undo, and concurrent-agent boundaries.
+- Kept workspace, module, and project-wide operations explicit rather than cursor-dependent.

package/editing-history/2026-07-29-0022-complete-cursor-structural-edits.md

@@ -0,0 +1,8 @@
+# Complete cursor structural edits
+
+- Implemented leftward slurp/barf operations and clipboard-preserving duplication.
+- Used staged Snapshot and sidecar writes with explicit partial-success diagnostics.
+- Added reusable active target/path resolution for `@cursor` aliases.
+- Covered selection tracking, invalid boundaries, and parallel-test temporary-directory collisions.
+
+The operations were round-trip tested on a temporary copy of `respo-calcit-workflow` with the globally installed `cr`.

package/editing-history/2026-07-29-0022-document-cursor-edit-recipes.md

@@ -0,0 +1,8 @@
+# Document cursor edit recipes
+
+- Added concrete recipes for cursor-aware query, tree, and edit commands.
+- Documented symmetric slurp/barf and clipboard-preserving duplicate operations.
+- Added cursor-scoped leaf and structural searches.
+- Clarified navigation history and multi-agent boundaries.
+
+The documented workflow was exercised against a temporary Respo project and finished with a successful JS build.

package/editing-history/2026-07-29-0022-echo-cursor-commands.md

@@ -0,0 +1,6 @@
+# Cursor command echo
+
+- Added machine-readable command echo fields and human explanations for the new cursor operations.
+- Included structural search start paths in echoed query commands.
+
+This keeps CLI diagnostics consistent with the existing command protocol.

package/editing-history/2026-07-29-0022-edit-target-cursor-alias.md

@@ -0,0 +1,6 @@
+# Edit target cursor alias
+
+- Added `@cursor` definition targets to definition, metadata, copy/move, rename, and split operations.
+- Defined the alias as the source for two-target commands while keeping destinations explicit.
+- Reused a single active target/path resolution when an edit references both.
+- Left transaction operation files self-contained with concrete targets and paths.

package/editing-history/2026-07-29-0022-guide-agents-through-cursor-workflows.md

@@ -0,0 +1,7 @@
+# Guide agents through cursor workflows
+
+- Documented cursor target aliases and subtree-scoped search for agents.
+- Added symmetric structural editing and duplication guidance.
+- Clarified that cursor history is navigation-only and the sidecar is not a concurrency primitive.
+
+All executable Markdown blocks passed `cr docs check-md`.

package/editing-history/2026-07-29-0022-query-from-active-cursor.md

@@ -0,0 +1,8 @@
+# Query from the active cursor
+
+- Allowed definition-oriented queries to use `@cursor` as their target.
+- Added cursor-scoped structural expression search with absolute result paths.
+- Made `query type-at @cursor --path @cursor` resolve one validated cursor state.
+- Rejected conflicting explicit filters for cursor-scoped searches.
+
+Real-project checks covered search selection, type evidence, and bounded semantic context.

package/editing-history/2026-07-29-0022-tree-target-cursor-alias.md

@@ -0,0 +1,5 @@
+# Tree target cursor alias
+
+- Allowed every target-bearing `cr tree` command to resolve `@cursor` as both definition target and structural path.
+- Reused one validated active cursor when both aliases occur in the same command.
+- Preserved target mismatch rejection for explicit definitions.

package/editing-history/2026-07-29-1242-agent-guide-cold-start-validation.md

@@ -0,0 +1,15 @@
+# Agent guide cold-start validation
+
+- Reworked the embedded Agent guide around Snapshot identity, Cirru AST boundaries, query-to-cursor workflows, structural editing, and layered validation.
+- Preserved the high-frequency Cirru rules that fresh agents commonly misapply, while routing lower-frequency operations through live CLI documentation.
+- Added practical cursor guidance for sibling insertion, clipboard state, inherited sidecars, focused previews, invalid navigation, and non-invertible unwrap operations.
+- Corrected error recovery guidance so current stderr takes precedence over stale persisted runtime stacks.
+- Validated the guide through isolated cold-start trials in a real Respo project without committing experimental changes.
+
+Validation:
+
+- `bash scripts/check-docs-md.sh` (52 files, 286 blocks)
+- `yarn check-agent-interface` (12 scenarios)
+- `cargo test cli_handlers::docs::tests::agents_docs_default_to_the_version_matched_embedded_guide`
+- Isolated `cr --check-only` and `cr js` trials in `respo-calcit-workflow` copies
+

package/editing-history/2026-07-29-1242-cirru-quote-input-errors.md

@@ -0,0 +1,13 @@
+# Cirru quote input diagnostics
+
+- Clarified CLI errors for missing or malformed `quote` transport wrappers.
+- Distinguished symbol, string, and expression payload examples in parser hints.
+- Added coverage for ambiguous bare forms and multi-payload quote input.
+
+Validation:
+
+- `cargo fmt`
+- `cargo clippy -- -D warnings`
+- `cargo test`
+- `yarn check-all`
+

package/editing-history/2026-07-29-1242-internal-wasm-doc-boundary.md

@@ -0,0 +1,13 @@
+# Internal WASM documentation boundary
+
+- Removed `cr-wasm` from installation, quick-reference, feature, and public CLI documentation.
+- Kept the WASM backend implementation and validation workflow unchanged.
+- Moved the detailed backend notes under `scripts/` and reframed them as repository-internal validation documentation.
+- Reduced `cr ir` coverage to a short compiler-debugging note instead of presenting it as a normal project workflow.
+
+Validation:
+
+- `bash scripts/check-docs-md.sh`
+- `yarn check-all`
+- `git diff --check`
+

package/editing-history/2026-07-30-1130-pr-281-review-fixes.md

@@ -0,0 +1,5 @@
+# PR 281 review fixes
+
+- Guard recursive static definition inference, falling back to `:dynamic` for cycles.
+- Validate dependency module paths before filesystem or Git operations and avoid reporting a reset for untracked-only changes.
+- Correct JS FFI intent classification, bounded cursor state recovery, and CLI/documentation consistency.

package/editing-history/20260729-1421-consolidate-local-state-and-cursor-tools.md

@@ -0,0 +1,22 @@
+# Consolidate local state and cursor tools
+
+## Summary
+
+- Consolidated project-local sidecar files under `.calcit/`: cursor state now uses `.calcit/cursor.cirru`, and persisted runtime errors use `.calcit/error.cirru`.
+- Added one-time migration from `.calcit-cursor.cirru` and `.calcit-error.cirru` without dual writes.
+- Kept state paths relative to the selected snapshot, including commands invoked from another working directory.
+- Extended cursor schema v4 with one region anchor, up to 16 named marks, and a compact last-query descriptor.
+- Added `cursor anchor`, `clear-anchor`, `region`, `mark`, `goto`, `marks`, and `rm-mark`, plus `query next` and `query prev`.
+- Applied the same path transforms to the active cursor, anchor, and marks during structural edits; stale query continuation is rejected after a snapshot revision change.
+- Bounded the complete cursor file to 64 KiB and retained existing history, stack, and mark count limits.
+
+## Validation
+
+- `cargo fmt`
+- `cargo clippy --all-targets -- -D warnings`
+- `cargo test`
+- `yarn compile`
+- `yarn check-all`
+- `yarn check-agent-interface`
+- Real-project regression on a temporary Respo workflow copy, including legacy migration, region/marks/query continuation, and successful `cr js` compilation.
+- Release binary changed from 8,196,752 bytes to 8,280,352 bytes on the same arm64 build environment (about 1.02%).

package/editing-history/20260729-1422-document-calcit-local-state.md

@@ -0,0 +1,15 @@
+# Document Calcit local state
+
+## Summary
+
+- Documented `.calcit/` as the bounded project-local state directory and recommended ignoring the directory as a unit.
+- Updated cursor RFC and Agent guidance for anchor/region, named marks, query continuation, migration behavior, and state-size limits.
+- Moved the recommended multiline snippet location to `.calcit/snippets/`.
+- Updated error-stack references to `.calcit/error.cirru` while preserving historical editing records.
+- Clarified that `.compact-inc.cirru` remains the existing watcher protocol rather than project-local diagnostic state.
+- Corrected repository-local Agent examples and replaced the obsolete binary-size threshold with a same-platform exact-byte baseline comparison.
+
+## Validation
+
+- `target/debug/cr docs check-md docs/CalcitAgent.md --entry calcit/test.cirru` (4/4 blocks passed)
+- `git diff --check`

package/editing-history/20260729-1952-strengthen-polymorphism-diagnostics.md

@@ -0,0 +1,21 @@
+# Strengthen polymorphism diagnostics
+
+## Summary
+
+- Clarified the static-semantics RFC around parametric generics, trait bounds, applied data types, callback contracts, enums, optionals, and type slots.
+- Restored the intended compatibility rule that legacy `:any` is parsed and serialized as `:dynamic`, rather than acting as a separate static top type.
+- Added generic and trait-bound evidence to type-coverage reports.
+- Added stable aggregate diagnostics for coverage gaps and unresolved dynamic debt, including per-occurrence impact and relationship-aware suggestions for Agents.
+- Reduced false positives from generated metadata namespaces, `defimpl` declarations, and singleton-list wrappers around Cirru data declarations.
+- Updated Agent and feature documentation with a concise workflow for replacing accidental dynamic types with concrete types, type variables, trait bounds, parameterized containers, or enums.
+
+## Validation
+
+- `cargo fmt`
+- `cargo clippy -- -D warnings`
+- `cargo test`
+- `yarn compile`
+- `yarn check-agent-interface` (12/12 scenarios)
+- `yarn check-all`
+- `cr docs check-md` for `docs/CalcitAgent.md`, `docs/features/static-analysis.md`, and `docs/features/polymorphism.md`
+- Real-project regression on a temporary Respo workflow copy, including type reports and successful `cr js` compilation.

package/editing-history/202607301429-entry-type-slots.md

@@ -0,0 +1,29 @@
+# Entry-level type slots
+
+Date: 2026-07-30 14:29 +0800
+
+## Context
+
+`with-type-slot` represented a build-wide type choice as a body wrapper. Its single-body and multi-body preprocessing paths diverged, so adding an otherwise meaningless `do` could decide whether a runtime `with-type-slot` call leaked into generated code. Respo also needs the same dispatch `Op` type across a large component call graph without passing generics through every API.
+
+## Changes
+
+- Added optional `:type-slots` maps to default and named entry configurations.
+- Added `cr config type-slots`, `set-type-slot`, and `rm-type-slot` commands.
+- Installed the selected entry's bindings before preprocessing and validated configured full type paths after module loading.
+- Kept named entry configurations independent instead of inheriting default bindings.
+- Made `with-type-slot` compile-time-only for both single and multiple bodies; codegen now rejects leaked forms.
+- Preserved unrelated raw Snapshot EDN when a type-slot config command writes its map.
+- Migrated type-slot fixtures and added round-trip, entry isolation, diagnostic, and multi-body erasure coverage.
+- Updated the static-analysis, entry, project-structure, core API, and RFC documentation.
+
+## Validation
+
+- `cargo fmt --all`
+- `cargo clippy -- -D warnings`
+- `cargo test`
+- `yarn compile`
+- `yarn check-agent-interface`
+- `yarn check-all`
+- Calcit Markdown checks for the updated static-analysis and entry documentation
+- Respo main/test entry regression, JS codegen, Node tests, and all Markdown code blocks with the new CLI

package/editing-history/202607301435-release-0.12.54.md

@@ -0,0 +1,22 @@
+# Release 0.12.54
+
+Date: 2026-07-30 14:35 +0800
+
+## Release scope
+
+- Entry-level `:type-slots` configuration and CLI management commands.
+- Compile-time-only `with-type-slot` erasure for single and multiple bodies.
+- Snapshot/config preservation, type-slot diagnostics, regression fixtures, and documentation.
+- The earlier PR 281 review fixes already carried by the same branch.
+
+## Pre-release evidence
+
+- Feature commit `5e180a2e` passed the repository Test workflow on PR #282.
+- Local validation passed `cargo fmt`, Clippy with warnings denied, all Rust tests, TypeScript compilation, Agent interface checks, and the full Rust/JS/WASM integration suite.
+- Respo passed check-only, JS codegen, Node tests, and all Markdown checks with the new CLI.
+
+## Version changes
+
+- `Cargo.toml`: `0.12.54`
+- `package.json`: `0.12.54`
+- `Cargo.lock`: refreshed with `cargo update --workspace`

package/editing-history/202607301620-program-diff-type-slots.md

@@ -0,0 +1,6 @@
+# Program diff 补齐 entry type slots
+
+- `SnapshotConfigs.type_slots` 已用于默认 `:configs` 和命名 `:entries`，但 program diff 仍只枚举旧的 `init-fn`、`reload-fn`、`version` 与 `modules` 字段，导致纯 type-slot 修改被误报为无变化。
+- 为字符串 map 增加稳定按 key 排序的结构化 diff，slot 标签保留 `:dispatch-op` 形式；新增或删除整个 entry 时也完整展示其 type slots。
+- `Snapshot` 与 `SnapshotConfigs` 的 program diff 改为无 `..` 的完整字段解构。以后新增字段而未更新 diff 时会产生编译错误，避免同类静默遗漏。
+- 回归测试覆盖默认 entry 的 slot 新增、删除、替换，命名 entry 的 slot 修改，以及新增 entry 时的 slot 详情。

package/editing-history/202607301959-unify-snapshot-entries.md

@@ -0,0 +1,7 @@
+# Unify snapshot entries and run modes
+
+- Replaced the split top-level `:configs` plus `:entries` model with a single `:entries` map. `:default` is now the required implicit entry and the project version lives at top-level `:version`.
+- Added entry-level `:mode` with the supported values `:native` and `:js`. A bare `cr <snapshot> [--entry name]` now follows the selected entry's mode; the explicit `js` subcommand remains available as an override.
+- Kept legacy snapshot loading compatible: old `:configs` is migrated in memory to `entries.default` with native mode, while canonical writes emit only the unified schema.
+- Updated config/query/diff/type-slot/module selection, embedded core serialization, repository snapshots, bundle/sync scripts, CLI help, RFCs, and user/Agent documentation.
+- Added coverage for new-format round trips, legacy migration, configured JS dispatch, and default-entry module extraction.

package/editing-history/202607310027-entry-description.md

@@ -0,0 +1,7 @@
+# Entry description snapshot metadata
+
+- `SnapshotEntry` now carries an optional `description` string for semantic context about an executable entry.
+- Existing snapshots without `:description` remain valid and deserialize to an empty string; canonical snapshot writes include the field.
+- Keep the build-script snapshot model synchronized with runtime `SnapshotEntry`, otherwise the embedded core MessagePack snapshot cannot be decoded.
+- `cr config set [--entry <name>] description "..."` updates the field, and `cr config show` displays it.
+- Program diffs expose description changes independently from runtime configuration and type-slot changes.

package/editing-history/202607310032-initialize-entry-descriptions.md

@@ -0,0 +1,6 @@
+# Initialize entry descriptions in repository snapshots
+
+- Installed the current `cr` 0.12.54 binary globally from this checkout.
+- Used `cr <snapshot> config set description ''` to canonicalize every complete `calcit/**/*.cirru` snapshot.
+- The migration updates 58 snapshots and 60 entry configurations, including named entries, with an explicit empty `:description` field.
+- Empty values preserve existing runtime behavior while providing a stable place for future semantic descriptions.

package/editing-history/202607310041-entry-functions-as-symbols.md

@@ -0,0 +1,7 @@
+# Store entry functions as Calcit symbols
+
+- `:init-fn` and `:reload-fn` describe namespace/definition references, so canonical snapshot output now writes them as Cirru EDN symbols such as `'app.main/main!`.
+- Snapshot readers continue to accept the prior string form (`|app.main/main!`) for compatibility.
+- The embedded core-snapshot build model accepts either representation when deserializing entry metadata.
+- Reinstalled `cr` globally and used it to rewrite all `calcit/**/*.cirru` snapshots; 120 entry function references now use symbols.
+- Updated snapshot documentation and round-trip coverage to make the canonical syntax explicit.

package/editing-history/202607310052-release-0.12.55.md

@@ -0,0 +1,5 @@
+# Release 0.12.55
+
+- Bumped the Rust crate and npm package versions together to `0.12.55`.
+- Refreshed the workspace lockfile before the release commit.
+- This release includes semantic snapshot entry descriptions and canonical symbol storage for entry functions, while preserving legacy string input compatibility.

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.12.53",
+    "version": "0.12.55",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.7.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.12.53",
+  "version": "0.12.55",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.7.0",