@calcit/procs 0.13.46 → 0.13.49

package/README.md

@@ -59,7 +59,7 @@ Evaluate snippets:
 ```bash
 calcit eval 'range 100'
 
-calcit eval 'thread-first 100 range (map $ \ * % %)'
+calcit eval -- '-> 100 range (map $ \ * % %)'
 ```
 
 Run with a runtime snapshot such as `calcit.cirru` (legacy filename: `compact.cirru`):

package/RFCs/08-23-option-result-binding-macros-rfc.md

@@ -1,8 +1,12 @@
 # Option / Result 顺序绑定宏 RFC
 
-状态：Experimental
+状态：Partially retained（2026-08-26；保留 `option:let`，移除 `result:let`）
 日期：2026-08-23
 
+> 历史说明：`option:let` 在 Respo 中有实际使用，因此继续保留；`result:let`
+> 没有生态采用且会隐藏 Result 链，已从 core 移除。Result 代码应直接使用
+> receiver-first `.and-then`。下文保留原始实验设计供追溯。
+
 ## 目标
 
 在不增加 parser syntax、提前返回控制流或隐式 unwrap 的前提下，简化连续的

package/RFCs/08-23-typed-option-query-ergonomics-rfc.md

@@ -1,8 +1,12 @@
 # 类型安全的 Option 查询终点 RFC
 
-状态：Implemented（待发布与生态迁移）
+状态：Withdrawn（2026-08-26；六个 `*-or` 宏已从 core 移除）
 日期：2026-08-23
 
+> 历史说明：实际生态采用率为零，而这些宏只隐藏了一次明确的
+> `option:unwrap-or` 调用。当前代码应直接调用查询函数并对返回的 `Option`
+> 使用 `.unwrap-or`；下文保留为设计与撤回记录。
+
 ## 背景与生态证据
 
 `08-05-systematic-nil-reduction-rfc.md` 把公开缺失值统一为 `Option<T>`，边界已经比旧的

package/RFCs/README.md

@@ -1,6 +1,6 @@
 # RFC 整理索引
 
-更新时间：2026-08-23
+更新时间：2026-08-26
 
 ## 目录原则
 
@@ -48,7 +48,8 @@
 | `08-21-type-quality-ci-adoption-rfc.md`               | Draft       | 统一使用原生 `analyze quality` 与按 definition baseline，定义生态 CI 层级并禁止各项目重复实现 JS 汇总脚本。 |
 | `08-21-js-ffi-runtime-contract-validation-rfc.md`     | Draft       | 在现有 typed JS FFI 声明之上增加 host guard、decoder、runtime contract tests 与 unsafe evidence。 |
 | `08-21-static-type-system-evolution-roadmap.md`       | Draft       | 借鉴 Rust/MoonBit 推进 Unknown/Dynamic 分离、穷尽性、局部推断、trait coherence 与框架类型化。 |
-| `08-23-typed-option-query-ergonomics-rfc.md`           | Implemented | 保持 Option 边界，新增 `get-or` 等类型安全查询终点，减少业务代码中的机械 unwrap。 |
+| `08-23-typed-option-query-ergonomics-rfc.md`           | Withdrawn | 生态采用率为零；`get-or` 等六个宏已移除，直接使用查询返回的 `Option` 与 `.unwrap-or`。 |
+| `08-23-option-result-binding-macros-rfc.md`             | Partial | 保留已有 Respo 使用的 `option:let`；移除未采用的 `result:let`，Result 链直接使用 `.and-then`。 |
 
 ## 已执行的清理
 

package/build.rs

@@ -5,6 +5,7 @@ use std::collections::HashMap;
 use std::env;
 use std::fs;
 use std::path::Path;
+use std::process::Command;
 
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "lowercase")]
@@ -558,8 +559,39 @@ fn parse_files(edn: Edn) -> Result<HashMap<String, FileInSnapShot>, String> {
   }
 }
 
+fn rustc_verbose_field<'a>(output: &'a str, name: &str) -> &'a str {
+  output
+    .lines()
+    .find_map(|line| line.strip_prefix(name).map(str::trim))
+    .unwrap_or_else(|| panic!("`rustc --version --verbose` did not report `{name}`"))
+}
+
+fn ffi_build_id() -> String {
+  let rustc = env::var("RUSTC").unwrap_or_else(|_| "rustc".to_owned());
+  let output = Command::new(&rustc)
+    .args(["--version", "--verbose"])
+    .output()
+    .unwrap_or_else(|error| panic!("failed to run `{rustc} --version --verbose`: {error}"));
+  if !output.status.success() {
+    panic!("`{rustc} --version --verbose` failed with {}", output.status);
+  }
+  let verbose = String::from_utf8(output.stdout).expect("rustc verbose version must be UTF-8");
+  let release = rustc_verbose_field(&verbose, "release:");
+  let commit = rustc_verbose_field(&verbose, "commit-hash:");
+  let target = env::var("TARGET").expect("Cargo must provide TARGET to build scripts");
+  let debug_assertions = env::var_os("CARGO_CFG_DEBUG_ASSERTIONS").is_some();
+  let panic_strategy = env::var("CARGO_CFG_PANIC").expect("Cargo must provide CARGO_CFG_PANIC to build scripts");
+
+  format!("rustc={release}:{commit};target={target};debug-assertions={debug_assertions};panic={panic_strategy}")
+}
+
 fn main() {
   println!("cargo:rerun-if-changed=src/cirru/calcit-core.cirru");
+  println!("cargo:rerun-if-env-changed=RUSTC");
+  println!("cargo:rerun-if-env-changed=TARGET");
+  println!("cargo:rerun-if-env-changed=CARGO_CFG_DEBUG_ASSERTIONS");
+  println!("cargo:rerun-if-env-changed=CARGO_CFG_PANIC");
+  println!("cargo:rustc-env=CALCIT_FFI_BUILD_ID={}", ffi_build_id());
 
   let out_dir = env::var_os("OUT_DIR").unwrap();
   let dest_path = Path::new(&out_dir).join("calcit-core.rmp");

package/editing-history/20260826-1234-native-let-macro-lowering.md

@@ -0,0 +1,21 @@
+# Native lowering for the core let macro
+
+- Added a compiler-native lowering for the strict, capability-free
+  `calcit.core/let` macro. It builds the same nested `&let` tree as the macro's
+  recursive quasiquote implementation, avoiding general evaluator execution
+  for valid binding-pair lists.
+- Invalid outer binding shapes deliberately remain on the ordinary macro path,
+  preserving the established macro diagnostics and error behavior.
+- After review, native lowering was narrowed to the exact `&let` binding
+  contract: `()` or a two-item list headed by a symbol. Singleton, oversized,
+  and non-symbol-headed lists therefore retain the ordinary macro path.
+- Macro metrics now explicitly classify this route as `native-fast-path`, not
+  as a general-evaluator fallback or a cache candidate.
+- Latest Respo main release-binary metrics changed from 1,418 expansions / about
+  29.04 ms evaluator time to 1,255 expansions / about 22.55 ms evaluator time.
+  The `let` evaluator time became zero while its required post-preprocessing
+  still runs.
+- On Apple arm64, 20 alternating paired Respo `--check-only` processes against
+  a same-source 0.13.46 baseline improved the median from 246.12 ms to
+  237.40 ms; paired median change was about -2.96%. This is a process-level
+  check improvement, not an application-runtime claim.

package/editing-history/20260826-1407-native-map-macro-lowering.md

@@ -0,0 +1,19 @@
+# Native lowering for the core map macro
+
+- Continued issue #436 after the merged native `let` fast path by lowering the
+  strict core `{}` macro directly to `CalcitProc::NativeMap`.
+- The fast path accepts only the macro's valid two-item list pairs, flattens
+  them in source order, and leaves malformed pairs on the normal macro path so
+  existing diagnostic text, locations, and metrics remain intact.
+- Latest Respo main showed 96 `{}` expansions and about 2.91 ms spent in the
+  general macro evaluator, making this compact, semantics-preserving lowering
+  the next lower-risk target after `let`.
+- Against the same-source #459 release binary on Apple arm64, latest Respo
+  `--check-only` changed from a 240.10 ms median to 237.99 ms across 20
+  alternating process pairs; paired median change was -1.43%. The macro metric
+  evaluator total was about 35.0 ms before and 20.1 ms after, while `{}` itself
+  moved from about 2.91 ms to zero. This remains compile/check performance,
+  not an application-runtime claim.
+- Full Calcit tests and `yarn check-all` passed. Latest Respo passed 27 tests
+  and JS check-only; latest Recollect passed 9 native tests and emitted/ran its
+  JS test entry successfully.

package/editing-history/20260826-1645-prune-cold-core-macros.md

@@ -0,0 +1,11 @@
+# Prune cold core macros and compatibility stubs
+
+- Removed 23 unused or superseded macros from the bundled core, reducing the audited macro inventory from 86 to 63: `\\.`, `%<-`, `<-`, `[,]`, `[][]`, `thread-as`, `thread-first`, `thread-last`, `call-w-log`, `call-wo-log`, `defn-w-log`, `defn-wo-log`, `field-match`, `calcit.internal/&field-match-internal`, `first-or`, `last-or`, `nth-or`, `get-or`, `get-in-or`, `get-env-or`, `result:let`, `record-match`, and `record-with`.
+- Removed the already non-functional `record-struct` and `record?` compatibility stubs, plus their dedicated migration-diagnostic cases. Generic legacy `&record:*` and tuple diagnostics remain until their lower-level compatibility removal is handled separately.
+- Use `->`, `->>`, and `->%` instead of their aliases. Reverse the form order explicitly when migrating `<-` or `%<-`.
+- Use ordinary `[]` construction instead of `[,]`; build a list of lists explicitly instead of `[][]`; write explicit nested `fn` forms instead of `\\.`.
+- Use `fn`/`defn`, `w-log`/`wo-log`, or explicit logging instead of the removed call/definition logging wrappers.
+- Call `.unwrap-or` on the `Option` returned by `get`, `get-in`, `get-env`, `first`, `last`, or `nth` instead of the six `*-or` macros.
+- Chain Result values with receiver-first `.and-then` instead of `result:let`. `option:let` remains because current Respo code uses it.
+- Replace `field-match` with an explicit field read followed by `case`/`match`; use `struct-match` for nominal structs. Replace the removed record names with `struct-match`, `struct-with`, `struct-definition`, `struct?`, or `struct-def?` as appropriate.
+- Migrated the Calcit runtime fixtures and current documentation to the canonical forms. Historical RFCs are retained with explicit withdrawn/partial status notes; editing-history records remain unchanged.

package/editing-history/20260826-1905-flipped-dynamic-callable-boundary.md

@@ -0,0 +1,11 @@
+# Keep `flipped` compatible with host callables
+
+- Relaxed `flipped`'s first macro input from source schema `Fn` (represented
+  internally as `DynFn`) to `Dynamic`.
+- The macro only reverses call syntax; JavaScript host symbols such as
+  `js/setTimeout` are intentionally dynamic and cannot satisfy the native
+  callable schema before host lowering.
+- Kept the rest arguments and expansion result explicitly dynamic, while the
+  macro remains compile-time pure and phase-aware.
+- Validated the change against current Respo UI usage, which relies on
+  `flipped js/setTimeout ...`.

package/editing-history/20260826-1940-prevent-js-module-self-imports.md

@@ -0,0 +1,8 @@
+# Prevent generated JavaScript module self-imports
+
+- Keep resolved definitions from the current namespace local even when a
+  type-directed rewrite conservatively marks them as referred imports.
+- Add a codegen regression test proving that the local definition remains a
+  direct identifier and does not enter the ESM import collection.
+- Validated with skir's same-namespace `Request` and `Response` struct
+  constructors, which previously produced duplicate declaration errors.

package/editing-history/20260826-1950-js-nullish-unit-boundary.md

@@ -0,0 +1,10 @@
+# Keep JS nullish checks aligned with `&unit`
+
+- Treat both `nil` (JavaScript `null`) and `&unit` (JavaScript `undefined`) as
+  nullish at `JsNullish<T>` boundaries.
+- Define `js-present?` as the complement of `js-nullish?` so the two helpers
+  cannot drift apart again.
+- Route `js-nullish->option` through the same predicate so JavaScript
+  `undefined` becomes `%none` instead of `%some &unit`.
+- Add examples covering both runtime representations. This prevents optional
+  host fields whose value is `undefined` from being dereferenced as present.

package/editing-history/20260826-2140-compact-runtime-call-shape.md

@@ -0,0 +1,32 @@
+# Cache compact native function call shape
+
+- Continued issue #464 with a field-consumer and layout audit before changing
+  the runtime representation. On Apple arm64, `Calcit` is 88 bytes,
+  `CalcitFn` 176 bytes, `CalcitLocal` 48 bytes, and `CalcitScope` 24 bytes.
+- Function values already share `Arc<CalcitFn>`, so ordinary calls do not clone
+  generic, where-bound, return, or argument annotation graphs. Those fields are
+  cold resident metadata rather than per-call allocation traffic. Local
+  metadata is hot in the preprocessed tree, but shrinking `CalcitLocal` alone
+  cannot shrink the 88-byte `Calcit` enum; a later material memory experiment
+  needs a genuinely separate execution expression.
+- Added a 6-byte `CalcitFnCallShape` that fills existing `CalcitFn` alignment
+  padding, leaving `size_of::<CalcitFn>()` unchanged at 176 bytes. It caches the
+  fixed parameter count, continuous trailing `Option` count, and combined
+  marked/typed rest evidence after preprocessing.
+- Native `run_fn` and `run_fn_owned` now consult the compact shape before
+  optional-argument completion instead of scanning `CalcitFnArgs` and the full
+  argument annotation list on every function call. Full schema metadata remains
+  available to preprocessing, codegen, queries, effects analysis, and errors.
+- Against main `86c47a93`, an alternating 30-pair native fold benchmark with
+  200,000 callback calls changed from a 119.280 ms median to 117.647 ms; paired
+  median change was -1.34%. A 15-pair 1,000,000-call run changed from 607.412 ms
+  to 594.369 ms; paired median change was -2.09%.
+- Latest Respo main (`27bb6304`) retained all 27 native tests; its 15-sample
+  test-body median changed from 30.867 ms to 31.255 ms. Latest Recollect main
+  (`e0903a6d`) retained all 9 native tests and stayed at a 9.520 ms median.
+  These project-level differences are treated as noise rather than claimed
+  speedups. Median peak RSS moved from 48,201,728 to 47,726,592 bytes for Respo
+  and from 70,172,672 to 68,927,488 bytes for Recollect, but process-level RSS
+  variance is too high to attribute that reduction to this zero-size cache.
+- The release binary changed from 9,212,896 to 9,213,136 bytes (+240 bytes).
+  No new heap allocation is introduced by the cached shape.

package/editing-history/202608262220-result-file-effects.md

@@ -0,0 +1,26 @@
+# Result-based file effects
+
+## Summary
+
+- Added String methods `.read-file`, `.read-dir`, and `.write-file` that convert recoverable file failures into `Result<..., String>` while retaining the raising raw procedures for compatibility.
+- Added native and generated-JavaScript regression coverage for missing paths and static Result contracts.
+- Completed the JavaScript host boundary for file effects: `read_file` now returns and validates injected content, `read_dir` validates/sorts host paths, and missing injections raise stable errors that the safe methods can catch.
+- Updated type guidance and file-operation examples to prefer receiver methods.
+- Fixed a Rust 1.97 Clippy finding in the previously landed native-call-shape test so the required `-D warnings` gate remains clean.
+
+## Knowledge retained
+
+- A language-level `try` wrapper is sufficient for Result-returning effects and keeps raw primitives ABI-compatible. Because generated JavaScript `try` normalizes host exceptions to String, the same core wrapper works on native and JS.
+- Core String methods are registered in `&core-string-methods`; adding a method there makes receiver typing and method discovery reuse the wrapper function schema.
+- Node file effects are host capabilities supplied through `globalThis.__calcit_injections__`. Validate values at this Dynamic boundary before returning them to typed Calcit code. Browser `read-file` keeps its localStorage compatibility path but now raises on a missing key, matching the recoverable failure contract.
+- `read-dir` must sort injected JavaScript paths to match the native procedure's deterministic contract.
+- WASM currently skips `try`-based file wrappers and does not expose host file procedures; keep this backend limit explicit in API docs and regression output.
+
+## Validation
+
+- `cargo fmt --all`
+- `cargo clippy --all-targets -- -D warnings`
+- `cargo test`
+- `yarn check-all`
+- Latest Respo main: 27/27 tests, 111/111 documentation blocks, JS codegen
+- Latest Recollect main: 9/9 native tests, generated JS tests, production build with Node 24.4.1, required WASM checks

package/editing-history/202608262228-fix-result-method-doc-chain.md

@@ -0,0 +1,5 @@
+# Fix Result method chaining in file examples
+
+The Markdown checker exposed a Cirru association pitfall in the new examples: `path .read-file .and-then` passes `.and-then` and its callback as extra arguments to `.read-file`. Parenthesize the first receiver call as `(path .read-file) .and-then` so the Result method receives the completed `Result` value. The checked example keeps its callback body direct to avoid unrelated nested callback inference obscuring the file-effect contract.
+
+Validated with the repository-wide Markdown check.

package/editing-history/202608262237-result-file-review.md

@@ -0,0 +1,8 @@
+# Address Result file-effect review
+
+- Grouped both receiver expressions in the documented Result chain so Cirru does not pass later method tokens as extra arguments.
+- Made `.read-dir` preserve the default non-recursive call without reintroducing a legacy nil parameter: its trailing recursion flag is `Option<Bool>`, omission supplies `%none`, and explicit recursion uses `%some true` or `%some false`.
+- Added omitted and explicit Option cases to native and generated-JavaScript tests.
+- Repeated the native/JavaScript support and WASM host-effect boundary at each public documentation entry.
+
+Validated with targeted examples/tests, native and generated JavaScript runs, and the full Markdown checker.

package/editing-history/202608262327-release-0.13.47.md

@@ -0,0 +1,7 @@
+# Release 0.13.47
+
+- Publishes the recoverable String file-effect methods merged in #472.
+- Includes the matching JavaScript procs exports for `read_file`, `read_dir`,
+  and `write_file`; this removes unresolved `$procs.read_dir` imports in real
+  JS consumers upgraded from the previously published 0.13.46 package.
+- Keeps Cargo and npm package versions aligned at 0.13.47.

package/editing-history/202608270059-fix-stable-rust-build.md

@@ -0,0 +1,7 @@
+# Keep the release path buildable on stable Rust
+
+- Replaced three unstable `if let` match guards with equivalent nested stable
+  control flow.
+- Kept enum and function-schema resolution order unchanged.
+- Changed the regular CI toolchain from nightly to stable so it matches the
+  publish workflow and catches stable-channel build blockers before release.

package/editing-history/2026082701-release-0.13.48.md

@@ -0,0 +1,7 @@
+# Release 0.13.48
+
+- Publishes the stable-Rust build fix after the 0.13.47 tag was created from a
+  revision that only compiled under the nightly test workflow.
+- Keeps Cargo and npm package versions aligned.
+- Uses the stable toolchain in normal CI so future release blockers are caught
+  before a tag is created.

package/editing-history/202608270132-reject-compact-snapshots.md

@@ -0,0 +1,8 @@
+# Reject retired compact.cirru snapshots
+
+- Reject `compact.cirru` before deserialization instead of silently running it
+  as a default or module fallback.
+- Point users to the canonical copy/rename, format, and check-only sequence.
+- Record 0.13.48 as the final compatibility release for the old filename.
+- Remove the obsolete formatter warning because formatting a retired filename
+  is no longer an accepted operation.

package/editing-history/202608270154-review-compact-migration-paths.md

@@ -0,0 +1,6 @@
+# Resolve compact snapshot migration review
+
+- Keep retired `compact.cirru` files out of normal module candidate resolution.
+- Detect compact-only modules separately so they retain actionable migration guidance.
+- Preserve nested module directories in the canonical destination and validation commands.
+- Correct the remaining singular snapshot wording in the agent guide.

package/editing-history/202608270214-ffi-build-handshake.md

@@ -0,0 +1,15 @@
+# Guard transitional Rust-native FFI with a C-safe build handshake
+
+- Embed the exact rustc release/commit, target, debug-assertion mode, and panic
+  strategy in the Calcit host build.
+- Read an optional static C string from dylibs before invoking legacy Rust ABI
+  version or business symbols.
+- Reject mismatched identities deterministically; require identity metadata for
+  debug hosts while retaining a warned release-only migration path.
+- Apply the same check to runtime calls and `caps` native verification, and
+  include the identity in native realization receipts and cache keys.
+- Add `calcit --ffi-build-id` and document the extension-side build script and
+  export.
+- Reproduce the former debug-host/release-dylib abort with calcit_wasmtime: the
+  guarded host now rejects before `abi_version`; matching release builds still
+  return `27`.

package/editing-history/202608270231-ffi-build-review-followup.md

@@ -0,0 +1,5 @@
+# FFI build handshake review follow-up
+
+- Updated the introductory Rust FFI examples to use Rust 2024-compatible `#[unsafe(no_mangle)]` attributes.
+- Included the required `build.rs` identity generator in the documented upgrade staging command.
+- Kept the original `202608270214` history timestamp because it records Asia/Shanghai local time, matching the repository workflow and actual commit time.

package/editing-history/202608270238-release-0.13.49.md

@@ -0,0 +1,5 @@
+# Release 0.13.49
+
+- Published the strict `compact.cirru` filename cutoff merged in #475.
+- Published the transitional Rust-native FFI build-identity handshake merged in #476.
+- Kept Cargo and npm package versions synchronized and refreshed the workspace lockfile.

package/lib/calcit.procs.d.mts

@@ -249,7 +249,13 @@ export declare let struct_$q_: (x: CalcitValue) => boolean;
 export declare let enum_$q_: (x: CalcitValue) => boolean;
 export declare let buffer_$q_: (x: CalcitValue) => boolean;
 export declare let _$n_str_$o_escape: (x: string) => string;
+export type CalcitFileInjections = {
+    read_file?: (path: string) => unknown;
+    read_dir?: (path: string, recursive: boolean) => unknown;
+    write_file?: (path: string, content: string) => unknown;
+};
 export declare let read_file: (path: string) => string;
+export declare let read_dir: (path: string, recursive: boolean) => CalcitSliceList;
 export declare let write_file: (path: string, content: string) => void;
 export declare let parse_cirru: (code: string) => CalcitCirruQuote;
 export declare let parse_cirru_list: (code: string) => CalcitList;

package/lib/calcit.procs.mjs

@@ -1538,20 +1538,44 @@ export let buffer_$q_ = (x) => {
     return false;
 };
 export let _$n_str_$o_escape = (x) => JSON.stringify(x);
+const get_file_injection = (name) => {
+    const injections = globalThis.__calcit_injections__;
+    const injection = injections?.[name];
+    if (typeof injection !== "function") {
+        throw new Error(`${name} is unavailable: the JavaScript host did not provide a __calcit_injections__.${name} function`);
+    }
+    return injection;
+};
 export let read_file = (path) => {
     if (inNodeJs) {
-        // TODO
-        globalThis["__calcit_injections__"].read_file(path);
+        const content = get_file_injection("read_file")(path);
+        if (typeof content !== "string") {
+            throw new TypeError(`read_file injection expected a string result, got ${typeof content}`);
+        }
+        return content;
     }
     else {
         // no actual File API in browser
-        return localStorage.get(path) ?? "";
+        const content = localStorage.getItem(path);
+        if (content === null) {
+            throw new Error(`read-file failed at ${path}: key not found in localStorage`);
+        }
+        return content;
+    }
+};
+export let read_dir = (path, recursive) => {
+    if (!inNodeJs) {
+        throw new Error("read_dir is unavailable in browser JavaScript hosts");
+    }
+    const paths = get_file_injection("read_dir")(path, recursive);
+    if (!Array.isArray(paths) || !paths.every((item) => typeof item === "string")) {
+        throw new TypeError("read_dir injection expected an array of strings");
     }
+    return new CalcitSliceList([...paths].sort());
 };
 export let write_file = (path, content) => {
     if (inNodeJs) {
-        // TODO
-        globalThis["__calcit_injections__"].write_file(path, content);
+        get_file_injection("write_file")(path, content);
     }
     else {
         // no actual File API in browser

package/lib/package.json

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

package/package.json

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

package/ts-src/calcit.procs.mts

@@ -1676,19 +1676,50 @@ export let buffer_$q_ = (x: CalcitValue): boolean => {
 
 export let _$n_str_$o_escape = (x: string) => JSON.stringify(x);
 
+export type CalcitFileInjections = {
+  read_file?: (path: string) => unknown;
+  read_dir?: (path: string, recursive: boolean) => unknown;
+  write_file?: (path: string, content: string) => unknown;
+};
+
+const get_file_injection = <K extends keyof CalcitFileInjections>(name: K): NonNullable<CalcitFileInjections[K]> => {
+  const injections = (globalThis as { __calcit_injections__?: CalcitFileInjections }).__calcit_injections__;
+  const injection = injections?.[name];
+  if (typeof injection !== "function") {
+    throw new Error(`${name} is unavailable: the JavaScript host did not provide a __calcit_injections__.${name} function`);
+  }
+  return injection as NonNullable<CalcitFileInjections[K]>;
+};
+
 export let read_file = (path: string): string => {
   if (inNodeJs) {
-    // TODO
-    (globalThis as any)["__calcit_injections__"].read_file(path);
+    const content = get_file_injection("read_file")(path);
+    if (typeof content !== "string") {
+      throw new TypeError(`read_file injection expected a string result, got ${typeof content}`);
+    }
+    return content;
   } else {
     // no actual File API in browser
-    return localStorage.get(path) ?? "";
+    const content = localStorage.getItem(path);
+    if (content === null) {
+      throw new Error(`read-file failed at ${path}: key not found in localStorage`);
+    }
+    return content;
+  }
+};
+export let read_dir = (path: string, recursive: boolean): CalcitSliceList => {
+  if (!inNodeJs) {
+    throw new Error("read_dir is unavailable in browser JavaScript hosts");
+  }
+  const paths = get_file_injection("read_dir")(path, recursive);
+  if (!Array.isArray(paths) || !paths.every((item) => typeof item === "string")) {
+    throw new TypeError("read_dir injection expected an array of strings");
   }
+  return new CalcitSliceList([...paths].sort());
 };
 export let write_file = (path: string, content: string): void => {
   if (inNodeJs) {
-    // TODO
-    (globalThis as any)["__calcit_injections__"].write_file(path, content);
+    get_file_injection("write_file")(path, content);
   } else {
     // no actual File API in browser
     localStorage.setItem(path, content);