@calcit/procs 0.13.18 → 0.13.19

package/README.md

@@ -135,9 +135,10 @@ Related examples and workflows:
 ```
 
 Run `caps` to resolve the recursive dependency graph and install it. Immutable revisions are stored under
-`~/.config/calcit/modules/.store/`, while the current project receives links under `.calcit/modules/`.
+`~/.config/calcit/module-caches/`, while the current project receives links under `.calcit/modules/`.
 Different projects can therefore use different revisions without switching a shared checkout. Existing
-`~/.config/calcit/modules/<repo>/` checkouts remain a runtime fallback during migration.
+project module links are the only runtime source for package-style module paths; explicit relative and
+absolute paths retain their normal direct resolution.
 
 Published SemVer tags are preferred. Branch refs remain supported for development, but `caps` warns with
 the resolved commit. When a graph requests several SemVer tags for one repository, the highest requested
@@ -157,8 +158,8 @@ To load modules, use `:modules` configuration and the runtime snapshot file `cal
     :modules $ [] |memof/calcit.cirru |lilac/
 ```
 
-Paths defined in `:modules` first load from the snapshot directory's `.calcit/modules/`, then fall back to
-`~/.config/calcit/modules/`, i.e. `.calcit/modules/memof/calcit.cirru` or the legacy global path.
+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.
 

package/RFCs/07-28-git-module-store-rfc.md

@@ -50,21 +50,24 @@ Calcit 继续使用 GitHub repository + Git ref 管理模块，不建设 registr
 
 ## 3. 目录模型
 
-当前正式路径是 `~/.config/calcit/modules/`。新 store 放在它下面，避免再引入
-一套顶级目录；路径解析应集中到一个 helper，后续再考虑 XDG 或其他平台差异。
+`~/.config/calcit/modules/` 保留给 legacy module root；新的不可变 store 使用它的
+同级路径 `~/.config/calcit/module-caches/`。路径解析应集中到一个 helper，后续再
+考虑 XDG 或其他平台差异。
 
 ```text
-~/.config/calcit/modules/
-  .store/git/<owner>/<repo>/<commit>/source/
-  .store/git/<owner>/<repo>/<commit>/realizations/<build-key>/
-  <repo>/                                  # legacy clone，迁移期保留
+~/.config/calcit/
+  modules/
+    <repo>/                                # legacy clone，迁移期保留
+  module-caches/
+    git/<owner>/<repo>/<commit>/source/
+    git/<owner>/<repo>/<commit>/realizations/<build-key>/
 
 <project>/
   deps.cirru
   .calcit/
     caps-state.cirru
     modules/
-      <repo> -> ~/.config/calcit/modules/.store/.../source/
+      <repo> -> ~/.config/calcit/module-caches/.../source/
       <native-repo> -> .../realizations/<build-key>/
     tmp/
 ```
@@ -99,7 +102,7 @@ basename 建立项目链接。如果依赖图里出现 `owner-a/utils` 与 `owne
 
 `caps` 按以下顺序修改本机状态：
 
-1. 在 store 的 `.store/tmp/` 下创建临时目录，解析 ref、下载 source（与 store 同文件系统，保证 rename 原子）；项目侧临时 project view 写入 `.calcit/tmp/`；
+1. 在 store 的 `~/.config/calcit/module-caches/tmp/` 下创建临时目录，解析 ref、下载 source（与 store 同文件系统，保证 rename 原子）；项目侧临时 project view 写入 `.calcit/tmp/`；
 2. 完成递归依赖图和版本选择；
 3. 完成需要的 native realization 与验证；
 4. 写入临时 project view；

package/editing-history/202608171118-project-module-runtime-resolution.md

@@ -0,0 +1,6 @@
+# Project module runtime resolution
+
+- `caps` already stores immutable dependency revisions in `~/.config/calcit/modules/.store/` and builds the project's `.calcit/modules/` link view.
+- Runtime loaders must consume only that project view. Retaining a global module fallback can silently run a dependency revision that was not selected by the project's dependency graph.
+- Centralize the project module directory calculation in `calcit::project_module_folder`, then use it for normal execution, WASM codegen, queries, configuration inspection, markdown checks, call-graph comparison, and the Cirru integration harness.
+- Keep explicitly relative and absolute module paths working; only package-style module paths are constrained to the project view.

package/editing-history/202608171133-visible-module-versions-and-cleanup.md

@@ -0,0 +1,6 @@
+# Visible module versions and cache cleanup
+
+- Store immutable module revisions under `~/.config/calcit/modules/versions/` instead of a hidden `.store/` directory, retaining the owner, repository, and resolved commit in the path.
+- Write `metadata.txt` beside each cached revision so the requested reference remains inspectable and global cleanup can select the highest SemVer release without a network request. When one commit is observed through multiple refs, retain the highest observed SemVer ref for cleanup ordering.
+- Add `caps clean` as an explicit global cleanup command. It preserves one newest revision per module (SemVer takes precedence; materialization time breaks non-SemVer ties) and removes older revision directories.
+- Rewrite `~/.config/calcit/modules/AGENTS.md` on each `caps` invocation. The guide treats `versions/` as immutable cache data and directs dependency changes through a repository commit, new tag, dependency update, and reinstall.

package/editing-history/202608171140-module-caches-root.md

@@ -0,0 +1,5 @@
+# Module caches root
+
+- Move the global immutable cache from the nested `modules/versions/` proposal to the clearer sibling path `~/.config/calcit/module-caches/`.
+- Keep `~/.config/calcit/modules/` reserved for the legacy module root and per-project link vocabulary; `module-caches/AGENTS.md` is the authoritative generated guidance for cached revisions.
+- Derive the cache root as a sibling of `CALCIT_MODULES_DIR`, so custom test and CI roots preserve the same `modules/` plus `module-caches/` layout.

package/editing-history/202608171200-module-cache-review-follow-up.md

@@ -0,0 +1,5 @@
+# Module cache review follow-up
+
+- Scope `cr docs` module documentation and scope discovery to the current project's `.calcit/modules/` directory, removing the final global fallback.
+- Register each successfully materialized project module view in `module-caches/projects/`; global cleanup preserves every cached revision that remains linked by one of those views.
+- When a cached commit is later resolved through a SemVer tag, refresh its metadata with the highest observed SemVer ref so cleanup ordering stays correct.

package/editing-history/202608171205-release-0-13-19.md

@@ -0,0 +1,4 @@
+# Release 0.13.19
+
+- Publish the project-scoped module resolution, visible `module-caches` store, safe cleanup, and documentation fixes from PR #364.
+- Keep Cargo and npm package versions synchronized at `0.13.19` for the direct PR-branch release.

package/editing-history/202608171215-module-path-resolution-docs.md

@@ -0,0 +1,4 @@
+# Module path resolution documentation
+
+- Clarify that project-local `.calcit/modules/` links are mandatory only for package-style module paths.
+- Preserve the documented behavior of explicit relative paths (resolved from the snapshot) and absolute paths (resolved directly).

package/lib/package.json

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

package/package.json

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