@calcit/procs 0.13.49 → 0.13.51

package/README.md

@@ -19,7 +19,7 @@ Core design:
 
 Current direction:
 
-- `calcit.cirru` is the primary source snapshot; legacy `compact.cirru` is still compatible
+- `calcit.cirru` is the canonical source snapshot; retired `compact.cirru` inputs receive migration guidance
 - CLI-first development with `calcit` and `caps`, designed to work well with AI agents in terminal workflows
 - Better CLI editing and validation for CI, docs lookup, module management, and incremental updates
 
@@ -62,18 +62,16 @@ calcit eval 'range 100'
 calcit eval -- '-> 100 range (map $ \ * % %)'
 ```
 
-Run with a runtime snapshot such as `calcit.cirru` (legacy filename: `compact.cirru`):
+Run with the canonical runtime snapshot `calcit.cirru`:
 
 ```bash
 calcit calcit.cirru # run once (default)
-calcit compact.cirru # legacy filename still works
-
-calcit # by default, it picks `calcit.cirru`, then falls back to `compact.cirru`
+calcit # reads calcit.cirru from the current directory
 
 calcit -w # watch mode (explicit flag required)
 ```
 
-By default Calcit reads `:init-fn` and `:reload-fn` from `calcit.cirru` configs (falling back to `compact.cirru`). You may also specify functions:
+By default Calcit reads `:init-fn` and `:reload-fn` from `calcit.cirru` `:entries.default`. You may also specify functions:
 
 ```bash
 calcit --init-fn='app.main/main!' --reload-fn='app.main/reload!'
@@ -150,7 +148,7 @@ Use `caps add --dev <org/repo>@<ref>` and `caps remove --dev <org/repo>` to mana
 
 `:calcit-version` helps with version checks and provides hints in [CI](https://github.com/calcit-lang/setup-calcit).
 
-To load modules, use `:modules` configuration and the runtime snapshot file `calcit.cirru` (legacy: `compact.cirru`):
+To load modules, use `:modules` configuration and the runtime snapshot file `calcit.cirru`:
 
 ```cirru.no-check
 :entries $ {}
@@ -161,7 +159,7 @@ To load modules, use `:modules` configuration and the runtime snapshot file `cal
 Paths defined in `:modules` load from the snapshot directory's `.calcit/modules/`, e.g.
 `.calcit/modules/memof/calcit.cirru`. Run `caps` to materialize or refresh that project-local view.
 
-Modules ending with `/` are automatically suffixed with `calcit.cirru`, and still fall back to `compact.cirru` for compatibility.
+Modules ending with `/` are automatically suffixed with `calcit.cirru`. A module containing only retired `compact.cirru` is rejected with migration guidance.
 
 Inspect and verify the resolved graph with:
 
@@ -203,7 +201,7 @@ yarn check-all
 ```
 
 - [Cirru Parser](https://github.com/Cirru/parser.rs) for indentation-based syntax parsing.
-- [Cirru EDN](https://github.com/Cirru/cirru-edn.rs) for runtime snapshot file parsing (`calcit.cirru` / legacy `compact.cirru`).
+- [Cirru EDN](https://github.com/Cirru/cirru-edn.rs) for canonical runtime snapshot parsing (`calcit.cirru`).
 - [Ternary Tree](https://github.com/calcit-lang/ternary-tree.rs) for immutable list data structure.
 
 Other tools:

package/RFCs/05-12-program-diff-rfc.md

@@ -11,7 +11,7 @@
 
 - `calcit analyze program-diff <GIT REF>`
 
-该命令从 Git 中读取指定版本的完整运行时快照文件（默认沿用当前 `calcit` 的输入文件路径，优先 `calcit.cirru`，兼容旧文件名 `compact.cirru`），确保**历史版本**与**当前工作区版本**都能被正确解析为 Calcit snapshot，然后做**结构化 diff**。
+该命令从 Git 中读取指定版本的完整运行时快照文件（默认沿用当前 `calcit` 的 canonical `calcit.cirru` 输入路径；退休的 `compact.cirru` 会被拒绝并提示迁移），确保**历史版本**与**当前工作区版本**都能被正确解析为 Calcit snapshot，然后做**结构化 diff**。
 
 输出目标不是纯文本行 diff，而是面向程序结构的树形 diff：
 
@@ -27,7 +27,7 @@
 
 当前针对运行时快照文件的版本对比主要依赖 Git 行 diff，但它有几个明显问题：
 
-1. **对结构不友好**：`calcit.cirru`（兼容旧文件名 `compact.cirru`）是机器生成的 snapshot，行 diff 容易受格式、字段顺序和长表达式影响；
+1. **对结构不友好**：`calcit.cirru` 是机器生成的 snapshot，行 diff 容易受格式、字段顺序和长表达式影响；
 2. **对表达式内部变化不友好**：definition 代码改动往往是局部子树变化，行 diff 很难快速看出 AST 层面的增删改；
 3. **对 LLM / CLI 阅读不友好**：调用 `git diff` 后很难一眼区分“只是某个 def 变了”还是“整个 namespace 被搬动了”；
 4. **缺少 parse guard**：历史版本文件如果本身损坏，应该先明确报解析失败，而不是直接进入错误 diff。
@@ -43,7 +43,7 @@ calcit analyze program-diff <GIT REF>
 语义：
 
 - `<GIT REF>` 可以是 `HEAD~1`、tag、branch、commit SHA 等；
-- 当前侧使用 `calcit` 输入路径（默认优先 `calcit.cirru`，兼容旧文件名 `compact.cirru`）；
+- 当前侧使用 `calcit` 输入路径（默认是 canonical `calcit.cirru`；退休的 `compact.cirru` 不参与 diff）；
 - 历史侧使用 `git show <ref>:<repo-relative-input-path>` 读取文件内容；
 - 两边都必须先经过：
   1. `cirru_edn::parse`
@@ -177,7 +177,7 @@ list 内部子节点对比采用“带替换代价的序列对齐”策略：
 
 ## 7. 预期收益
 
-- 更适合 review `calcit.cirru`（兼容旧文件名 `compact.cirru`）的语义变化；
+- 更适合 review canonical `calcit.cirru` 的语义变化；
 - 更容易理解大型 definition 的局部 AST 改动；
 - 对 agent/LLM 更友好，能直接拿到层级化变化；
 - 为后续抽象成 Cirru diff 模块提供实现样本。

package/build.rs

@@ -64,20 +64,6 @@ pub struct SnapshotEntry {
   pub target: Option<String>,
 }
 
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub struct LegacySnapshotConfigs {
-  #[serde(rename = "init-fn", deserialize_with = "deserialize_ns_def")]
-  pub init_fn: String,
-  #[serde(rename = "reload-fn", deserialize_with = "deserialize_ns_def")]
-  pub reload_fn: String,
-  #[serde(default)]
-  pub modules: Vec<String>,
-  #[serde(default)]
-  pub version: String,
-  #[serde(default, rename = "type-slots")]
-  pub type_slots: HashMap<String, String>,
-}
-
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct CodeEntry {
   pub doc: String,
@@ -613,30 +599,15 @@ fn main() {
 
   let files = parse_files(data.get_or_nil("files")).unwrap_or_else(|e| panic!("failed to parse calcit-core `:files`: {e}"));
 
-  let legacy_configs = match data.get_or_nil("configs") {
-    Edn::Nil => None,
-    value => {
-      Some(from_edn::<LegacySnapshotConfigs>(value).unwrap_or_else(|e| panic!("failed to parse calcit-core legacy `:configs`: {e}")))
-    }
-  };
-  let mut entries = parse_entries(data.get_or_nil("entries")).unwrap_or_else(|e| panic!("failed to parse calcit-core `:entries`: {e}"));
-  if let Some(configs) = &legacy_configs {
-    entries.insert(
-      "default".to_owned(),
-      SnapshotEntry {
-        mode: SnapshotRunMode::Native,
-        init_fn: configs.init_fn.clone(),
-        reload_fn: configs.reload_fn.clone(),
-        description: String::new(),
-        modules: configs.modules.clone(),
-        type_slots: configs.type_slots.clone(),
-        feature_policy: HashMap::new(),
-        target: None,
-      },
-    );
+  if data.contains_key("configs") {
+    panic!("calcit-core uses retired top-level `:configs`; migrate it with Calcit 0.13.50 before building")
+  }
+  let entries = parse_entries(data.get_or_nil("entries")).unwrap_or_else(|e| panic!("failed to parse calcit-core `:entries`: {e}"));
+  if !entries.contains_key("default") {
+    panic!("calcit-core `:entries` must contain `:default`");
   }
   let version = match data.get_or_nil("version") {
-    Edn::Nil => legacy_configs.map(|configs| configs.version).unwrap_or_default(),
+    Edn::Nil => String::new(),
     value => from_edn(value).unwrap_or_else(|e| panic!("failed to parse calcit-core `:version`: {e}")),
   };
 

package/editing-history/20260827-1225-retire-snapshot-configs.md

@@ -0,0 +1,6 @@
+# Retire legacy Snapshot config aliases
+
+- Stop decoding top-level `:configs` at runtime and while embedding `calcit.core`; point legacy projects to Calcit 0.13.50 for the one-way `:entries.default` migration.
+- Remove silent `calcit.cirru` to `compact.cirru` path aliasing across runtime, query, docs, and diff commands while retaining sibling detection for an actionable error.
+- Remove the formatter advisory for a shape that current Calcit no longer loads, and align README, Agent guidance, and Snapshot docs with the released filename cutoff.
+- Validate the strict loader against the latest `Respo/respo` and `calcit-lang/recollect` main branches: native checks/tests, Markdown examples, generated JavaScript tests, quality gates, and production Vite builds remain green.

package/editing-history/202608270316-ffi-buffer-protocol-v1.md

@@ -0,0 +1,6 @@
+# Add the synchronous FFI byte-buffer protocol
+
+- Added a versioned C ABI for synchronous FFI calls using owned UTF-8 Cirru EDN buffers.
+- Made method migration incremental by preferring `<method>_calcit_ffi_v1` and retaining the build-ID-guarded Rust ABI as a fallback.
+- Kept output ownership in the dylib through `calcit_ffi_buffer_free`, with host-side invariant and size checks before decoding.
+- Added focused tests for protocol versioning, symbol derivation, and request encoding; callback migration remains a separate phase.

package/editing-history/202608270326-ffi-buffer-review-followup.md

@@ -0,0 +1,6 @@
+# FFI buffer protocol review follow-up
+
+- Corrected the FFI documentation heading hierarchy.
+- Made nonzero-status payloads obey the same strict UTF-8 contract as successful EDN responses.
+- Added a focused regression test that rejects malformed error bytes rather than replacing them lossily.
+- Kept the original 03:16 history timestamp because it records the actual Asia/Shanghai commit time.

package/editing-history/202608270334-release-0.13.50.md

@@ -0,0 +1,5 @@
+# Release 0.13.50
+
+- Published synchronous C-safe FFI buffer protocol v1 merged in #477.
+- Retained per-method fallback to the build-ID-guarded Rust ABI for incremental ecosystem migration.
+- Kept Cargo and npm package versions synchronized and refreshed the workspace lockfile.

package/editing-history/202608270956-fs-path-file-effects.md

@@ -0,0 +1,33 @@
+# FsPath file-effect boundary
+
+## Summary
+
+- Removed `.read-file`, `.read-dir`, and `.write-file` from the built-in String method table.
+- Added the nominal, UTF-8-backed `FsPath` type and the explicit `fs:path` constructor.
+- Added `FsPath` methods `.read-text`, `.write-text`, `.read-dir`, `.walk-dir`, and `.to-string` through a nominal trait implementation.
+- Kept `try-read-file`, `try-read-dir`, `try-write-file` and the raw raising primitives as String-path compatibility APIs.
+
+## Design notes
+
+- `path` remains available for generic AST, data, and query path concepts; the filesystem-specific type is named `FsPath`.
+- Calcit uses one immutable path value rather than copying Rust's borrowed `Path` versus owned mutable `PathBuf` split.
+- `fs:path` stores the original UTF-8 text without lexical normalization or filesystem access.
+- `.read-dir` is non-recursive and `.walk-dir` is recursive, avoiding an `Option<Bool>` mode in the new public method API.
+- Text operations are named `.read-text` and `.write-text` so future byte-oriented operations have an unambiguous place.
+
+## Implementation lesson
+
+Keep `defstruct FsPath` directly inside the public `FsPath` definition before `impl-traits`, matching the core `Result` pattern. Hiding the base struct in an intermediate `FsPath0` definition prevents required-field analysis from resolving `:value` through the nominal reference.
+
+For an expression receiver, prefix method syntax such as `.read-text $ fs:path |file` is always explicit. The ergonomic suffix form should use a typed binding such as `source.read-text`; `(fs:path |file) .read-text` is not a general runtime rewrite for arbitrary expression receivers.
+
+## Validation
+
+- `cargo fmt --all`
+- `cargo clippy --all-targets -- -D warnings`
+- `cargo test`
+- `yarn check-all`
+- changed Markdown snippets via `calcit docs check-md`
+- latest Respo main: 27/27 tests, 111/111 documentation blocks, JS codegen
+- latest Recollect main: 9/9 native tests, generated-JS tests, production build, and required WASM checks
+

package/editing-history/202608271407-audit-legacy-macro-schemas.md

@@ -0,0 +1,20 @@
+# Legacy macro schema inventory
+
+## Summary
+
+- Added the stable `W_LEGACY_MACRO_SCHEMA` diagnostic to `analyze check-types`.
+- Preserved whether a compatibility macro came from an old runtime `Fn` schema or a whole `Dynamic` schema.
+- Added check-types JSON schema v2 fields for the aggregate count and per-definition source, legacy signature, Snapshot path, and migration guidance.
+- Kept compatibility loading and execution unchanged; the analyzer does not infer phase-aware contracts.
+
+## Release constraint
+
+Release audits must use `check-types --deps` against resolved module artifacts. A dependency's main branch may already be strict while its published module still exposes legacy macro schemas. Migrate and release providers before setting consumer graphs to a zero-legacy target.
+
+## Validation
+
+- `cargo fmt --all`
+- `cargo clippy --all-targets -- -D warnings`
+- `cargo test`
+- `yarn check-all`
+- latest Respo and Recollect source plus Recollect's resolved published dependency graph

package/editing-history/202608271427-review-legacy-macro-inventory.md

@@ -0,0 +1,19 @@
+# Legacy macro inventory review follow-up
+
+## Summary
+
+- Persisted the `Dynamic` legacy macro origin through canonical Snapshot serialization instead of reclassifying it as `Fn` after reload.
+- Limited legacy macro parameter-shape validation to old `Fn` contracts; a whole-`Dynamic` schema carries no arity contract.
+- Corrected the Agent guide to use the complete `data.summary.legacy_macro_schemas` JSON path.
+
+## Compatibility
+
+Old wrapped macro schemas omit `:legacy-origin` and continue to load as `Fn`. Only whole-`Dynamic` compatibility schemas write `:legacy-origin :dynamic`, so existing `Fn` serialization remains unchanged.
+
+## Validation
+
+- focused origin round-trip and Dynamic-parameter regression tests
+- `cargo fmt --all -- --check`
+- `cargo clippy --all-targets -- -D warnings`
+- `cargo test -- --test-threads=1`
+- `yarn check-all`

package/editing-history/202608271444-release-0.13.51.md

@@ -0,0 +1,6 @@
+# Release 0.13.51
+
+- Added nominal `FsPath` values and explicit filesystem effect methods.
+- Retired top-level `:configs` and the `compact.cirru` filename alias after the 0.13.50 migration window.
+- Added dependency-aware legacy macro schema inventory and schema-v2 `check-types` diagnostics for the staged strict-macro rollout.
+- Kept Cargo and npm package versions synchronized and refreshed the workspace lockfile.

package/lib/package.json

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

package/package.json

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