@scriptc/cli-darwin-arm64 0.2.2 → 0.2.4

package/dist/lib/runtime-sources/src/scr_bytes_io.c

@@ -279,13 +279,204 @@ static ScrStr *scr_fs_cb_path(const ScrDyn *value, const char *name) {
   ScrStr *path = value->kind == SCR_DYN_STR ? scr_str_retain(value->v.str)
     : scr_str_new((const char *)value->v.bytes->data, value->v.bytes->len);
   if (memchr(path->data, 0, path->len)) {
-    scr_dyn_arg_value_fail(name, "must be a string, Uint8Array, or URL without null bytes", value);
+    scr_fs_invalid_named_path(value, path, name);
     scr_str_release(path);
     return NULL;
   }
   return path;
 }
 
+static ScrStr *scr_fs_checked_path(const ScrDyn *value, const char *name) {
+  if (!scr_dyn_native_url_is(value)) return scr_fs_cb_path(value, name);
+  ScrStr *path = scr_url_checked_to_path(value);
+  if (!path) return NULL;
+  ScrDyn input = { .kind = SCR_DYN_STR, .v.str = path };
+  ScrStr *checked = scr_fs_cb_path(&input, name);
+  scr_str_release(path);
+  return checked;
+}
+
+static ScrStr *scr_fs_timestamp_path(const ScrDyn *value) {
+  return scr_fs_checked_path(value, "path");
+}
+
+/* statfs reads options.bigint without validating/coercing the options object.
+ * Undefined selects the default; null throws, and only boolean true opts in. */
+static bool scr_fs_statfs_bigint(const ScrDyn *options) {
+  if (options->kind == SCR_DYN_UNDEF) return false;
+  if (options->kind == SCR_DYN_NULL) {
+    static const char message[] = "Cannot read properties of null (reading 'bigint')";
+    scr_throw_error_msg(SCR_ERR_TYPE, message, sizeof message - 1);
+    return false;
+  }
+  ScrDyn *value = scr_fs_cb_option(options, "bigint");
+  bool bigint = value && value->kind == SCR_DYN_BOOL && value->v.b;
+  scr_dyn_release(value);
+  return bigint;
+}
+
+ScrDyn *scr_fs_statfs_checked(const ScrDyn *input, const ScrDyn *options) {
+  ScrStr *path = scr_fs_checked_path(input, "path");
+  if (!path) return NULL;
+  bool bigint = scr_fs_statfs_bigint(options);
+  ScrDyn *result = scr_exc_pending() ? NULL : scr_fs_statfs(path, bigint);
+  scr_str_release(path);
+  return result;
+}
+
+/* validateOneOf runs before either path, even on POSIX where the type has
+ * no syscall effect. -1 means infer the target's kind on Windows. */
+static int scr_fs_symlink_type(const ScrDyn *type) {
+  if (scr_fs_dyn_absent(type)) return -1;
+  if (type->kind == SCR_DYN_STR) {
+    const ScrStr *s = type->v.str;
+    if (s->len == 4 && !memcmp(s->data, "file", 4)) return 0;
+    if (s->len == 3 && !memcmp(s->data, "dir", 3)) return 1;
+    if (s->len == 8 && !memcmp(s->data, "junction", 8)) return 2;
+  }
+  scr_dyn_arg_value_fail("type", "must be one of: 'dir', 'file', 'junction', null, undefined", type);
+  return -1;
+}
+
+void scr_fs_link_checked(const ScrDyn *existing, const ScrDyn *destination) {
+  ScrStr *from = scr_fs_checked_path(existing, "existingPath");
+  if (!from) return;
+  ScrStr *to = scr_fs_checked_path(destination, "newPath");
+  if (to) scr_fs_link(from, to);
+  scr_str_release(from); scr_str_release(to);
+}
+
+static void scr_fs_symlink_checked_core(const ScrDyn *target, const ScrDyn *destination, const ScrDyn *type, bool promise) {
+  int kind = scr_fs_symlink_type(type);
+  if (scr_exc_pending()) return;
+#ifdef _WIN32
+  if (kind == -1) {
+    // Sync/promise inference stringifies the raw destination and target before
+    // getValidatedPath. Sync stat exposes null-byte errors in the resolved path;
+    // the promise form catches inference failures and continues as a file link.
+    ScrStr *link = scr_dyn_string_coerce_js(destination);
+    ScrStr *source = !scr_exc_pending() ? scr_dyn_string_coerce_js(target) : NULL;
+    ScrStr *absolute = NULL;
+    if (link && source && !scr_exc_pending()) {
+      ScrArr *parts = scr_arr_new_ref(scr_str_retain_v, scr_str_release_v, NULL, 3);
+      scr_arr_push_ref(parts, scr_str_retain(link));
+      scr_arr_push_ref(parts, scr_str_new("..", 2));
+      scr_arr_push_ref(parts, scr_str_retain(source));
+      absolute = scr_path_win32_resolve(parts);
+      scr_arr_release(parts);
+    }
+    kind = 0;
+    if (absolute && !scr_exc_pending()) {
+      ScrDyn input = { .kind = SCR_DYN_STR, .v.str = absolute };
+      ScrStr *checked = scr_fs_cb_path(&input, "path");
+      if (checked) kind = scr_fs_symlink_infer(checked);
+      scr_str_release(checked);
+    }
+    scr_str_release(link); scr_str_release(source); scr_str_release(absolute);
+    if (scr_exc_pending()) {
+      if (!promise) return;
+      scr_caught_release(scr_exc_take());
+    }
+  }
+#else
+  (void)promise;
+#endif
+  ScrStr *from = scr_fs_checked_path(target, "target");
+  if (!from) return;
+  ScrStr *to = scr_fs_checked_path(destination, "path");
+#ifdef _WIN32
+  if (to && kind == 2 && scr_dyn_bytes_is(destination, SCR_BYTES_U8)) {
+    scr_dyn_arg_type_fail("paths[0]", "of type string", destination);
+    scr_str_release(to); to = NULL;
+  }
+#endif
+  if (to) scr_fs_symlink(from, to, kind);
+  scr_str_release(from); scr_str_release(to);
+}
+
+void scr_fs_symlink_checked(const ScrDyn *target, const ScrDyn *destination, const ScrDyn *type) {
+  scr_fs_symlink_checked_core(target, destination, type, false);
+}
+
+void scr_fs_symlink_promise_checked(const ScrDyn *target, const ScrDyn *destination, const ScrDyn *type) {
+  scr_fs_symlink_checked_core(target, destination, type, true);
+}
+
+/* getOptions accepts functions as defaults and validates signals without
+ * cancelling readlink. Unlike readFile, an aborted signal is ignored. */
+static ScrDyn *scr_fs_readlink_encoding(const ScrDyn *options) {
+  if (scr_fs_dyn_absent(options) || options->kind == SCR_DYN_FUNC) return scr_dyn_retain(scr_dyn_undefined());
+  if (options->kind != SCR_DYN_STR && options->kind != SCR_DYN_OBJ &&
+      options->kind != SCR_DYN_ARR && options->kind != SCR_DYN_TYPED_REF &&
+      options->kind != SCR_DYN_HANDLE && options->kind != SCR_DYN_BYTES) {
+    scr_dyn_arg_type_fail("options", "one of type string or object", options);
+    return NULL;
+  }
+  ScrDyn *encoding = options->kind == SCR_DYN_STR ? scr_dyn_retain((ScrDyn *)options) : scr_fs_cb_option(options, "encoding");
+  if (!encoding) return NULL;
+  bool buffer = encoding->kind == SCR_DYN_STR && encoding->v.str->len == 6 && !memcmp(encoding->v.str->data, "buffer", 6);
+  if (!buffer && scr_dyn_truthy(encoding) &&
+      (encoding->kind != SCR_DYN_STR || !scr_bytes_is_encoding(encoding->v.str))) {
+    scr_dyn_arg_value_fail("encoding", "is invalid encoding", encoding);
+    scr_dyn_release(encoding);
+    return NULL;
+  }
+  if (options->kind != SCR_DYN_STR) {
+    ScrDyn *signal = scr_fs_cb_option(options, "signal");
+    if (!signal) { scr_dyn_release(encoding); return NULL; }
+    bool valid = signal->kind == SCR_DYN_UNDEF || (signal->kind == SCR_DYN_HANDLE && signal->v.handle.tag == SCR_DYNH_ABORT_SIGNAL);
+    if (!valid) scr_dyn_prop_type_fail("options.signal", "an instance of AbortSignal", signal);
+    scr_dyn_release(signal);
+    if (!valid) { scr_dyn_release(encoding); return NULL; }
+  }
+  return encoding;
+}
+
+static ScrDyn *scr_fs_readlink_result(ScrStr *path, const ScrDyn *encoding) {
+  ScrBytes *bytes = scr_fs_readlink_bytes(path);
+  if (!bytes) return NULL;
+  ScrDyn *result;
+  if (encoding->kind == SCR_DYN_STR && encoding->v.str->len == 6 && !memcmp(encoding->v.str->data, "buffer", 6)) {
+    result = scr_dyn_new_buffer(bytes);
+  }
+  else {
+    ScrStr *codec = encoding->kind == SCR_DYN_STR && encoding->v.str->len ? scr_str_retain(encoding->v.str) : scr_str_new("utf8", 4);
+    ScrStr *text = scr_bytes_to_str(bytes, codec);
+    scr_str_release(codec);
+    result = text ? scr_dyn_new_str(text) : NULL;
+    scr_str_release(text);
+  }
+  scr_bytes_release(bytes);
+  return result;
+}
+
+ScrDyn *scr_fs_readlink_checked(const ScrDyn *input, const ScrDyn *options, bool promise) {
+  ScrDyn *encoding = scr_fs_readlink_encoding(options);
+  if (!encoding) return NULL;
+  ScrStr *path = scr_fs_checked_path(input, promise ? "oldPath" : "path");
+  ScrDyn *result = path ? scr_fs_readlink_result(path, encoding) : NULL;
+  scr_str_release(path); scr_dyn_release(encoding);
+  return result;
+}
+
+ScrDyn *scr_fs_readlink_dyn(const ScrDyn *path, const ScrDyn *options) {
+  return scr_fs_readlink_checked(path, options, false);
+}
+
+ScrStr *scr_fs_readlink_str(const ScrDyn *path, const ScrDyn *options) {
+  ScrDyn *result = scr_fs_readlink_dyn(path, options);
+  ScrStr *text = result && result->kind == SCR_DYN_STR ? scr_str_retain(result->v.str) : NULL;
+  scr_dyn_release(result);
+  return text;
+}
+
+ScrBytes *scr_fs_readlink_buffer(const ScrDyn *path, const ScrDyn *options) {
+  ScrDyn *result = scr_fs_readlink_dyn(path, options);
+  ScrBytes *bytes = result ? scr_dyn_bytes_unbox(result) : NULL;
+  scr_dyn_release(result);
+  return bytes;
+}
+
 static ScrDyn *scr_fs_cb_string(ScrStr *text) {
   if (!text) return NULL;
   ScrDyn *value = scr_dyn_new_str(text);
@@ -472,6 +663,13 @@ static bool scr_fs_encoding_chk(const ScrDyn *);
 static bool scr_fs_int_range_chk(const ScrDyn *, const char *, double, double, const char *);
 static bool scr_fs_mode_chk(const ScrDyn *, const char *);
 
+static bool scr_fs_callback_times(const ScrDyn *atime, const ScrDyn *mtime, bool descriptor, double *access, double *modified) {
+  *access = scr_fs_timestamp_value(atime, descriptor ? "atime" : "time");
+  if (scr_exc_pending()) return false;
+  *modified = scr_fs_timestamp_value(mtime, descriptor ? "mtime" : "time");
+  return !scr_exc_pending();
+}
+
 static ScrArr *scr_fs_cb_vectors(const ScrDyn *buffers) {
   ScrDyn *snapshot = buffers->kind == SCR_DYN_TYPED_REF && scr_dyn_isl_is_array(buffers)
     ? scr_dyn_typed_ref_materialize(buffers) : NULL;
@@ -499,21 +697,86 @@ static ScrArr *scr_fs_cb_vectors(const ScrDyn *buffers) {
 
 static ScrDyn *scr_fs_cb_invoke(ScrStr *member, ScrDyn *const *args, size_t argc) {
   const char *op = member->data;
+  if (!strcmp(op, "statfs")) {
+    const ScrDyn *options = scr_fs_cb_arg(args, argc, 1);
+    const ScrDyn *callback = options->kind == SCR_DYN_FUNC ? options : scr_fs_cb_arg(args, argc, 2);
+    if (!scr_fs_cb_chk(callback, "cb")) return NULL;
+    ScrStr *path = scr_fs_checked_path(scr_fs_cb_arg(args, argc, 0), "path");
+    if (!path) return NULL;
+    if (options->kind == SCR_DYN_FUNC) options = scr_dyn_undefined();
+    bool bigint = scr_fs_statfs_bigint(options);
+    /* FSReqCallback captures the first read; binding.statfs reads it again. */
+    if (!scr_exc_pending()) (void)scr_fs_statfs_bigint(options);
+    if (scr_exc_pending()) { scr_str_release(path); return NULL; }
+    ScrDyn *result = scr_fs_statfs(path, bigint);
+    scr_str_release(path);
+    scr_fs_cb_schedule(callback, result, NULL);
+    return scr_dyn_retain(scr_dyn_undefined());
+  }
+  if (!strcmp(op, "link") || !strcmp(op, "symlink") || !strcmp(op, "readlink")) {
+    const ScrDyn *first = scr_fs_cb_arg(args, argc, 0);
+    const ScrDyn *second = scr_fs_cb_arg(args, argc, 1);
+    bool symbolic = !strcmp(op, "symlink"), reading = !strcmp(op, "readlink");
+    const ScrDyn *third = scr_fs_cb_arg(args, argc, 2);
+    const ScrDyn *fourth = scr_fs_cb_arg(args, argc, 3);
+    const ScrDyn *callback = symbolic && fourth->kind != SCR_DYN_UNDEF ? fourth
+      : reading && second->kind == SCR_DYN_FUNC ? second : third;
+    int kind = -1;
+    if (symbolic && fourth->kind != SCR_DYN_UNDEF) {
+      kind = scr_fs_symlink_type(third);
+      if (scr_exc_pending()) return NULL;
+    } else if (!scr_fs_cb_chk(callback, "cb")) return NULL;
+    ScrDyn *encoding = reading ? scr_fs_readlink_encoding(second) : NULL;
+    if (reading && !encoding) return NULL;
+    ScrStr *from = scr_fs_checked_path(first, symbolic ? "target" : reading ? "path" : "existingPath");
+    if (!from) { scr_dyn_release(encoding); return NULL; }
+    ScrStr *to = reading ? NULL : scr_fs_checked_path(second, symbolic ? "path" : "newPath");
+    if ((!reading && !to) || (symbolic && fourth->kind != SCR_DYN_UNDEF && !scr_fs_cb_chk(callback, "cb"))) {
+      scr_str_release(from); scr_str_release(to); scr_dyn_release(encoding); return NULL;
+    }
+#ifdef _WIN32
+    if (symbolic) {
+      if (kind == 2 && scr_dyn_bytes_is(second, SCR_BYTES_U8)) {
+        scr_dyn_arg_type_fail("paths[0]", "of type string", second);
+        scr_str_release(from); scr_str_release(to); return NULL;
+      }
+      // Callback inference passes validated paths directly to path.resolve;
+      // Buffer paths fail that probe and fall back to a file link.
+      if (kind == -1 && (scr_dyn_bytes_is(first, SCR_BYTES_U8) || scr_dyn_bytes_is(second, SCR_BYTES_U8))) kind = 0;
+    }
+#endif
+    ScrDyn *result = NULL;
+    if (reading) result = scr_fs_readlink_result(from, encoding);
+    else if (symbolic) scr_fs_symlink(from, to, kind);
+    else scr_fs_link(from, to);
+    scr_str_release(from); scr_str_release(to); scr_dyn_release(encoding);
+    scr_fs_cb_schedule(callback, result, NULL);
+    return scr_dyn_retain(scr_dyn_undefined());
+  }
   bool vector = !strcmp(op, "readv") || !strcmp(op, "writev");
+  bool timestamp = !strcmp(op, "utimes") || !strcmp(op, "lutimes") || !strcmp(op, "futimes");
+  bool timestamp_fd = !strcmp(op, "futimes");
+  double access = 0, modified = 0;
+  // futimes converts times before checking the callback; path variants do
+  // callback and path validation first. Validation failures throw immediately.
+  if (timestamp_fd && !scr_fs_callback_times(scr_fs_cb_arg(args, argc, 1), scr_fs_cb_arg(args, argc, 2), true, &access, &modified)) return NULL;
   bool newControl = !strcmp(op, "fdatasync") || !strcmp(op, "fchmod") || !strcmp(op, "ftruncate");
   if ((vector || newControl) && !scr_fs_int_range_chk(scr_fs_cb_arg(args, argc, 0), "fd", 0, 2147483647.0, ">= 0 && <= 2147483647")) return NULL;
   ScrArr *vectors = vector ? scr_fs_cb_vectors(scr_fs_cb_arg(args, argc, 1)) : NULL;
   if (vector && !vectors) return NULL;
   bool fileCallback = !strcmp(op, "readFile") || !strcmp(op, "mkdtemp");
-  const ScrDyn *callback = argc >= (fileCallback ? 2u : 1u) ? args[argc - 1] : scr_dyn_undefined();
-  if (!scr_fs_cb_chk(callback, fileCallback || vector ? "cb" : "callback")) { scr_arr_release(vectors); return NULL; }
-  size_t count = argc - 1;
+  const ScrDyn *callback = timestamp ? scr_fs_cb_arg(args, argc, 3)
+    : argc >= (fileCallback ? 2u : 1u) ? args[argc - 1] : scr_dyn_undefined();
+  if (!scr_fs_cb_chk(callback, fileCallback || vector || timestamp ? "cb" : "callback")) { scr_arr_release(vectors); return NULL; }
+  size_t count = timestamp ? argc : argc - 1;
 #define ARG(index) scr_fs_cb_arg(args, count, index)
   if (!strcmp(op, "readFile") && !scr_fs_encoding_chk(ARG(1))) return NULL;
   if (!strcmp(op, "read") && count >= 4 && !scr_fs_read_validate(ARG(0), ARG(1), ARG(2), ARG(3), ARG(4))) return NULL;
-  bool descriptor = vector || newControl || !strcmp(op, "close") || !strcmp(op, "fstat") || !strcmp(op, "fsync") || !strcmp(op, "read") || !strcmp(op, "write");
-  ScrStr *path = descriptor ? NULL : scr_fs_cb_path(ARG(0), !strcmp(op, "mkdtemp") ? "prefix" : "path");
+  bool descriptor = timestamp_fd || vector || newControl || !strcmp(op, "close") || !strcmp(op, "fstat") || !strcmp(op, "fsync") || !strcmp(op, "read") || !strcmp(op, "write");
+  ScrStr *path = descriptor ? NULL : timestamp ? scr_fs_timestamp_path(ARG(0)) : scr_fs_cb_path(ARG(0), !strcmp(op, "mkdtemp") ? "prefix" : "path");
   if (!descriptor && !path) return NULL;
+  if (timestamp && !timestamp_fd && !scr_fs_callback_times(ARG(1), ARG(2), false, &access, &modified)) { scr_str_release(path); return NULL; }
+  if (timestamp_fd && !scr_fs_int_range_chk(ARG(0), "fd", 0, 2147483647.0, ">= 0 && <= 2147483647")) return NULL;
   double fd = descriptor ? scr_fs_cb_number(ARG(0), "fd", -1) : -1;
   if (scr_exc_pending()) { scr_str_release(path); scr_arr_release(vectors); return NULL; }
   if (newControl && strcmp(op, "fdatasync")) {
@@ -646,11 +909,10 @@ static ScrDyn *scr_fs_cb_invoke(ScrStr *member, ScrDyn *const *args, size_t argc
       scr_dyn_release(ownedBuffer); scr_str_release(path);
       return scr_dyn_retain(scr_dyn_undefined());
     }
-  } else if (!strcmp(op, "copyFile") || !strcmp(op, "rename") || !strcmp(op, "link") || !strcmp(op, "symlink")) {
+  } else if (!strcmp(op, "copyFile") || !strcmp(op, "rename")) {
     ScrStr *destination = scr_fs_cb_path(ARG(1), "dest");
     if (destination) {
       if (!strcmp(op, "rename")) scr_fs_rename(path, destination);
-      else if (!strcmp(op, "link")) scr_fs_link(path, destination);
       else if (!strcmp(op, "copyFile")) {
         double flags = scr_fs_cb_number(ARG(2), "mode", 0);
         if (flags == 1 && scr_fs_exists(destination)) scr_fs_throw(EEXIST, "copyfile", destination);
@@ -659,13 +921,6 @@ static ScrDyn *scr_fs_cb_invoke(ScrStr *member, ScrDyn *const *args, size_t argc
           scr_throw_error_msg_code(SCR_ERR_ERROR, message, sizeof message - 1, "SC2020");
         } else if (!scr_exc_pending()) scr_fs_copyfile(path, destination);
       }
-      else {
-#if !defined(_WIN32)
-        if (symlink(path->data, destination->data) < 0) scr_fs_throw(errno, "symlink", path);
-#else
-        scr_fs_throw(ENOSYS, "symlink", path);
-#endif
-      }
       scr_str_release(destination);
     }
   } else if (!strcmp(op, "truncate") || !strcmp(op, "ftruncate")) {
@@ -674,35 +929,9 @@ static ScrDyn *scr_fs_cb_invoke(ScrStr *member, ScrDyn *const *args, size_t argc
       if (descriptor) scr_fs_ftruncate(fd, length);
       else if (truncate(path->data, (off_t)length) < 0) scr_fs_throw(errno, "truncate", path);
     }
-  } else if (!strcmp(op, "readlink")) {
-#ifndef _WIN32
-    size_t capacity = 256;
-    char *text = NULL;
-    for (;;) {
-      char *grown = realloc(text, capacity);
-      if (!grown) scr_bytes_io_oom();
-      text = grown;
-      ssize_t size = readlink(path->data, text, capacity);
-      if (size < 0) { scr_fs_throw(errno, "readlink", path); break; }
-      if ((size_t)size < capacity) { result = scr_fs_cb_string(scr_str_new(text, (size_t)size)); break; }
-      capacity *= 2;
-    }
-    free(text);
-#else
-    scr_fs_throw(ENOSYS, "readlink", path);
-#endif
-  } else if (!strcmp(op, "utimes")) {
-    double access = scr_fs_to_unix_timestamp(ARG(1)), modified = scr_fs_to_unix_timestamp(ARG(2));
-#if !defined(_WIN32)
-    struct timespec times[2] = {
-      { (time_t)floor(access), (long)((access - floor(access)) * 1000000000) },
-      { (time_t)floor(modified), (long)((modified - floor(modified)) * 1000000000) },
-    };
-    if (!scr_exc_pending() && utimensat(AT_FDCWD, path->data, times, 0) < 0) scr_fs_throw(errno, "utime", path);
-#else
-    struct utimbuf times = { (time_t)access, (time_t)modified };
-    if (!scr_exc_pending() && utime(path->data, &times) < 0) scr_fs_throw(errno, "utime", path);
-#endif
+  } else if (timestamp) {
+    if (timestamp_fd) scr_fs_futimes(fd, access, modified);
+    else scr_fs_utimes(path, access, modified, !strcmp(op, "lutimes"));
   } else if (!strcmp(op, "readdir")) {
     if (scr_fs_cb_refuse_option(ARG(1), "encoding") || scr_fs_cb_option_bool(ARG(1), "withFileTypes") || scr_fs_cb_option_bool(ARG(1), "recursive")) {
       if (!scr_exc_pending()) { const char *message = "Recursive readdir and Dirent results have no native lowering"; scr_throw_error_msg_code(SCR_ERR_ERROR, message, strlen(message), "SC2020"); }
@@ -929,10 +1158,11 @@ ScrBytes *scr_buffer_new_string_fail(const ScrDyn *got) {
  * its time arguments (fs.js's toUnixTimestamp, underscore-exported):
  * numeric STRINGS pass ToNumber's loose-equality gate (+time == time —
  * whitespace-only strings answer 0), finite numbers pass (negatives
- * answer now/1000, Node's "past times" shape), everything else throws
+ * answer now/1000, Node's "past times" shape), Dates supply milliseconds,
+ * and everything else throws
  * Node's exact ERR_INVALID_ARG_TYPE. Borrowed; the throw is pending on
  * the dummy 0 return. */
-double scr_fs_to_unix_timestamp(const ScrDyn *t) {
+double scr_fs_timestamp_value(const ScrDyn *t, const char *name) {
   if (t->kind == SCR_DYN_STR) {
     double n = scr_string_to_number(t->v.str);
     /* +time == time: NaN fails; every parsed number loosely equals its
@@ -943,14 +1173,41 @@ double scr_fs_to_unix_timestamp(const ScrDyn *t) {
     if (t->v.num < 0) {
       struct timespec ts;
       clock_gettime(CLOCK_REALTIME, &ts);
-      return ((double)ts.tv_sec * 1000.0 + (double)ts.tv_nsec / 1e6) / 1000.0;
+      return ((double)ts.tv_sec * 1000.0 + (double)(ts.tv_nsec / 1000000)) / 1000.0;
     }
     return t->v.num;
   }
-  scr_dyn_arg_type_fail("time", "an instance of Date or an Time in seconds", t);
+  if (scr_dyn_native_date_is(t)) return scr_dyn_native_date_value(t) / 1000.0;
+  scr_dyn_arg_type_fail(name, "an instance of Date or an Time in seconds", t);
   return 0;
 }
 
+double scr_fs_to_unix_timestamp(const ScrDyn *t) {
+  return scr_fs_timestamp_value(t, "time");
+}
+
+static void scr_fs_path_times_checked(const ScrDyn *input, const ScrDyn *atime, const ScrDyn *mtime, bool nofollow) {
+  ScrStr *path = scr_fs_timestamp_path(input);
+  if (!path) return;
+  double access, modified;
+  if (scr_fs_callback_times(atime, mtime, false, &access, &modified)) scr_fs_utimes(path, access, modified, nofollow);
+  scr_str_release(path);
+}
+
+void scr_fs_utimes_checked(const ScrDyn *path, const ScrDyn *atime, const ScrDyn *mtime) {
+  scr_fs_path_times_checked(path, atime, mtime, false);
+}
+
+void scr_fs_lutimes_checked(const ScrDyn *path, const ScrDyn *atime, const ScrDyn *mtime) {
+  scr_fs_path_times_checked(path, atime, mtime, true);
+}
+
+void scr_fs_futimes_checked(const ScrDyn *fd, const ScrDyn *atime, const ScrDyn *mtime) {
+  double access, modified;
+  if (!scr_fs_callback_times(atime, mtime, true, &access, &modified)) return;
+  if (scr_fs_int_range_chk(fd, "fd", 0, 2147483647.0, ">= 0 && <= 2147483647")) scr_fs_futimes(fd->v.num, access, modified);
+}
+
 /* ── the fs argument-validation ladders (checked-dynamic lane) ─────────
  * Each fs.*Chk libCall replicates its API's Node-order validation over
  * dyn values and throws Node's exact typed errors; when every validation

package/dist/lib/runtime-sources/src/scr_cycle.c

@@ -9,7 +9,7 @@
  *   markGray     trial-delete: decrement rc once per internal edge;
  *   scan         nodes still rc > 0 are externally referenced — re-blacken
  *                their subgraph and restore the trial decrements;
- *   collectWhite everything left white is a dead cycle: free it, releasing
+ *   gather       filter the scanned white set, then free it, releasing
  *                only edges that LEAVE the white set (each member's
  *                teardown releases its untraced children; traced edges were
  *                already accounted by markGray).
@@ -26,9 +26,10 @@
  *   count was already given up (which would over-decrement and free live
  *   data).
  *
- * Recursion depth equals the traced structure's depth — same property as
- * the existing recursive releases (deep lists recurse deeply; acceptable
- * for now, revisit with an explicit stack if it ever traps).
+ * The main graph phases keep a bounded depth-first walk and defer deeper
+ * traces to reusable worklists. Ordinary RC destruction and cross-generation
+ * releases are separate paths. White candidates are recorded during scan
+ * and filtered after outside roots settle, avoiding a separate gather walk.
  *
  * ── generations ──────────────────────────────────────────────────────
  * A pass costs O(objects reachable from its candidates), and a candidate
@@ -154,6 +155,12 @@ static SCR_TL ScrVec scr_cands;
 /* Nursery survivors awaiting promotion (see scr_scan_black). */
 static SCR_TL ScrVec scr_promote;
 
+/* Deferred traces cap recursive traversal without changing the common
+ * depth-first walk. Restore can run inside scan, so it has its own stack. */
+static SCR_TL ScrVec scr_pending;
+static SCR_TL ScrVec scr_restore_pending;
+#define SCR_CYC_WALK_DEPTH 64
+
 /* The gathered white set (freed after the walk completes). */
 static SCR_TL ScrVec scr_white;
 
@@ -281,14 +288,15 @@ void scr_cyc_on_dead(void *obj) {
 void scr_cyc_on_release(void *obj) {
   ScrCycHdr *h = scr_cyc_hdr(obj);
   h->color = SCR_CYC_PURPLE;
-  if (!h->buffered) {
-    ScrVec *b = &scr_roots[h->gen];
-    if (b->n == b->cap) scr_cyc_grow(b);
-    h->buffered = 1;
-    h->buf_index = b->n;
-    b->v[b->n++] = obj;
-    scr_cyc_nbuffered++;
-  }
+  /* Releasing an existing candidate cannot advance the trigger. A pass
+   * always re-arms after its teardowns, including any candidates they add. */
+  if (h->buffered) return;
+  ScrVec *b = &scr_roots[h->gen];
+  if (b->n == b->cap) scr_cyc_grow(b);
+  h->buffered = 1;
+  h->buf_index = b->n;
+  b->v[b->n++] = obj;
+  scr_cyc_nbuffered++;
   /* Never re-entered: a teardown's releases of untraced children can buffer
    * new candidates mid-collection, but they only wait for the next pass. */
   if (!scr_collecting && scr_cyc_nbuffered >= scr_cyc_trigger)
@@ -306,69 +314,68 @@ void scr_cyc_on_release(void *obj) {
   ((child) == NULL || SCR_RC(child) == SIZE_MAX \
    || scr_cyc_hdr(child)->gen > scr_gen_limit)
 
-static void scr_mark_gray(void *obj);
+/* Trace callbacks forward an integer depth through their opaque context;
+ * it is never dereferenced. The ABI already carries it through every edge. */
+static void scr_mark_gray(void *obj, uintptr_t depth);
 static void scr_mg_visit(void *child, void *ctx) {
-  (void)ctx;
   if (SCR_CYC_SKIP(child)) return;
-  SCR_RC(child) -= 1; /* trial-delete this internal edge */
-  scr_mark_gray(child);
+  SCR_RC(child) -= 1;
+  scr_mark_gray(child, (uintptr_t)ctx);
 }
-static void scr_mark_gray(void *obj) {
+static void scr_mark_gray(void *obj, uintptr_t depth) {
   ScrCycHdr *h = scr_cyc_hdr(obj);
   if (h->color == SCR_CYC_GRAY) return;
   h->color = SCR_CYC_GRAY;
-  h->trace(obj, scr_mg_visit, NULL);
+  if (depth == SCR_CYC_WALK_DEPTH) {
+    scr_cyc_push(&scr_pending, obj);
+    return;
+  }
+  h->trace(obj, scr_mg_visit, (void *)(depth + 1));
 }
 
-static void scr_scan_black(void *obj);
+static void scr_scan_black(void *obj, uintptr_t depth);
 static void scr_sb_visit(void *child, void *ctx) {
-  (void)ctx;
   if (SCR_CYC_SKIP(child)) return;
-  SCR_RC(child) += 1; /* restore the trial decrement */
-  if (scr_cyc_hdr(child)->color != SCR_CYC_BLACK) scr_scan_black(child);
+  SCR_RC(child) += 1;
+  if (scr_cyc_hdr(child)->color != SCR_CYC_BLACK)
+    scr_scan_black(child, (uintptr_t)ctx);
 }
-static void scr_scan_black(void *obj) {
+static void scr_scan_black(void *obj, uintptr_t depth) {
   ScrCycHdr *h = scr_cyc_hdr(obj);
   h->color = SCR_CYC_BLACK;
-  /* Blackening is what proves a walked object survives, so this is where
-   * promotion is decided — but it is only RECORDED here. Raising `gen` now
-   * would hide the object from SCR_CYC_SKIP partway through the pass, and
-   * this phase has trial decrements left to restore. */
-  if (h->gen < SCR_CYC_MATURE)
-    scr_cyc_push(&scr_promote, obj);
-  h->trace(obj, scr_sb_visit, NULL);
+  if (h->gen < SCR_CYC_MATURE) scr_cyc_push(&scr_promote, obj);
+  if (depth == SCR_CYC_WALK_DEPTH) {
+    scr_cyc_push(&scr_restore_pending, obj);
+    return;
+  }
+  h->trace(obj, scr_sb_visit, (void *)(depth + 1));
 }
 
-static void scr_scan(void *obj);
+static void scr_scan(void *obj, uintptr_t depth);
 static void scr_scan_visit(void *child, void *ctx) {
-  (void)ctx;
   if (SCR_CYC_SKIP(child)) return;
-  scr_scan(child);
+  scr_scan(child, (uintptr_t)ctx);
 }
-static void scr_scan(void *obj) {
+static void scr_scan(void *obj, uintptr_t depth) {
   ScrCycHdr *h = scr_cyc_hdr(obj);
   if (h->color != SCR_CYC_GRAY) return;
   if (SCR_RC(obj) > 0) {
-    /* Externally referenced: this whole subgraph stays. */
-    scr_scan_black(obj);
+    scr_scan_black(obj, 0);
+    while (scr_restore_pending.n) {
+      void *next = scr_restore_pending.v[--scr_restore_pending.n];
+      scr_cyc_hdr(next)->trace(next, scr_sb_visit, NULL);
+    }
     return;
   }
   h->color = SCR_CYC_WHITE;
-  h->trace(obj, scr_scan_visit, NULL);
-}
-
-static void scr_collect_white(void *obj);
-static void scr_cw_visit(void *child, void *ctx) {
-  (void)ctx;
-  if (SCR_CYC_SKIP(child)) return;
-  scr_collect_white(child);
-}
-static void scr_collect_white(void *obj) {
-  ScrCycHdr *h = scr_cyc_hdr(obj);
-  if (h->color != SCR_CYC_WHITE || h->buffered) return;
-  h->color = SCR_CYC_DOOMED; /* gathered — don't gather twice */
-  h->trace(obj, scr_cw_visit, NULL);
+  /* Record each whitened object once. A later outside root can restore it;
+   * filter the list only after every scan finishes. No gather trace needed. */
   scr_cyc_push(&scr_white, obj);
+  if (depth == SCR_CYC_WALK_DEPTH) {
+    scr_cyc_push(&scr_pending, obj);
+    return;
+  }
+  h->trace(obj, scr_scan_visit, (void *)(depth + 1));
 }
 
 /* ── cross-generation edges ───────────────────────────────────────────── */
@@ -443,12 +450,10 @@ static size_t scr_cyc_pass(unsigned gen_limit) {
   scr_gen_limit = gen_limit;
 
   /* markRoots: keep live candidates (still purple), drop the rest — an
-   * object re-retained since buffering is black; one grayed by an earlier
-   * candidate's walk is already covered by that candidate's subgraph. The
-   * buffers are drained up front (markGray only touches counts directly,
-   * so nothing can re-buffer underneath us) which leaves collectWhite free
-   * to gather members of an earlier root's cycle. Candidates ABOVE the
-   * limit keep their buffer slots and wait for a full pass. */
+   * object re-retained since buffering is black. Drain the buffers before
+   * walking: tracing only adjusts counts and worklists, so nothing can
+   * re-buffer underneath us. Candidates ABOVE the limit keep their slots
+   * and wait for a full pass. */
   scr_cands.n = 0;
   for (unsigned g = 0; g <= gen_limit; g++) {
     for (size_t i = 0; i < scr_roots[g].n; i++) {
@@ -460,12 +465,31 @@ static size_t scr_cyc_pass(unsigned gen_limit) {
     }
     scr_roots[g].n = 0;
   }
-  for (size_t i = 0; i < scr_cands.n; i++) scr_mark_gray(scr_cands.v[i]);
-
-  for (size_t i = 0; i < scr_cands.n; i++) scr_scan(scr_cands.v[i]);
+  for (size_t i = 0; i < scr_cands.n; i++) scr_mark_gray(scr_cands.v[i], 0);
+  while (scr_pending.n) {
+    void *obj = scr_pending.v[--scr_pending.n];
+    scr_cyc_hdr(obj)->trace(obj, scr_mg_visit, NULL);
+  }
 
   scr_white.n = 0;
-  for (size_t i = 0; i < scr_cands.n; i++) scr_collect_white(scr_cands.v[i]);
+  for (size_t i = 0; i < scr_cands.n; i++) scr_scan(scr_cands.v[i], 0);
+  while (scr_pending.n) {
+    void *obj = scr_pending.v[--scr_pending.n];
+    /* A later outside root may have restored this deferred white node and
+     * its descendants already. Never scan a black node's edges again. */
+    if (scr_cyc_hdr(obj)->color == SCR_CYC_WHITE)
+      scr_cyc_hdr(obj)->trace(obj, scr_scan_visit, NULL);
+  }
+
+  size_t dead = 0;
+  for (size_t i = 0; i < scr_white.n; i++) {
+    void *obj = scr_white.v[i];
+    ScrCycHdr *h = scr_cyc_hdr(obj);
+    if (h->color != SCR_CYC_WHITE) continue;
+    h->color = SCR_CYC_DOOMED;
+    scr_white.v[dead++] = obj;
+  }
+  scr_white.n = dead;
 
   /* Pin the cross-generation targets of everything about to be freed, while
    * `gen` still holds the values the walk filtered on (promotion below is