harn-vm 0.10.40

Async bytecode virtual machine for the Harn programming language
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
//! Tests for [`crate::bytecode_cache`].
//!
//! Split out of `bytecode_cache.rs` to keep that file under the source-length
//! cap; they are still the `tests` child module of it, so private items stay
//! reachable through `use super::*`.

use super::*;
use crate::compile_source;

#[test]
fn header_round_trips_chunk() {
    let chunk = compile_source("__io_println(\"hello\")").expect("compile");
    let key = CacheKey::from_source(Path::new("/tmp/example.harn"), "__io_println(\"hello\")");
    let tmp = tempfile::tempdir().unwrap();
    let path = tmp.path().join("entry.harnbc");
    store_at(&path, &key, &chunk).expect("write");
    let loaded = read_entry_candidate(&path, &key).unwrap();
    assert!(loaded.is_some(), "expected cached chunk to load");
}

#[test]
fn serialize_chunk_artifact_matches_store_at() {
    // `serialize_chunk_artifact` packages an artifact into a buffer for
    // in-memory consumers (e.g. `harn pack` writing into a tar.zst
    // bundle). The contract is: the resulting bytes match what
    // `store_at` would have written for the same key+chunk, so the
    // shipped artifact is byte-identical to the on-disk cache form.
    let chunk = compile_source("__io_println(\"hi\")").expect("compile");
    let key = CacheKey::from_source(Path::new("/tmp/pack.harn"), "__io_println(\"hi\")");
    let tmp = tempfile::tempdir().unwrap();
    let on_disk = tmp.path().join("pack.harnbc");
    store_at(&on_disk, &key, &chunk).expect("write");
    let on_disk_bytes = std::fs::read(&on_disk).unwrap();
    let in_memory_bytes = serialize_chunk_artifact(&key, &chunk).expect("serialize");
    assert_eq!(in_memory_bytes, on_disk_bytes);
}

#[test]
fn cache_payload_rejects_trailing_bytes() {
    let chunk = compile_source("1 + 1").expect("compile");
    let cached = chunk.freeze_for_cache();
    let mut payload = serialize_cache_payload(&cached).expect("serialize");
    payload.push(0xFF);

    assert!(deserialize_cache_payload::<CachedChunk>(&payload).is_err());
}

#[test]
fn header_mismatch_returns_none() {
    let chunk = compile_source("1 + 1").expect("compile");
    let key = CacheKey::from_source(Path::new("/tmp/a.harn"), "1 + 1");
    let tmp = tempfile::tempdir().unwrap();
    let path = tmp.path().join("a.harnbc");
    store_at(&path, &key, &chunk).expect("write");
    let other = CacheKey {
        source_hash: [0xAB; 32],
        context_hash: key.context_hash,
        harn_version: HARN_VERSION,
        compiler_tag: key.compiler_tag,
    };
    assert!(read_entry_candidate(&path, &other).unwrap().is_none());
}

#[test]
fn schema_mismatch_returns_none() {
    let chunk = compile_source("1 + 1").expect("compile");
    let key = CacheKey::from_source(Path::new("/tmp/schema.harn"), "1 + 1");
    let tmp = tempfile::tempdir().unwrap();
    let path = tmp.path().join("schema.harnbc");
    store_at(&path, &key, &chunk).expect("write");

    let mut bytes = std::fs::read(&path).expect("read cache");
    bytes[8..12].copy_from_slice(&(SCHEMA_VERSION - 1).to_le_bytes());
    std::fs::write(&path, bytes).expect("rewrite cache");

    assert!(read_entry_candidate(&path, &key).unwrap().is_none());
}

#[test]
fn compiler_tag_mismatch_returns_none() {
    let chunk = compile_source("1 + 1").expect("compile");
    let key = CacheKey::from_source(Path::new("/tmp/b.harn"), "1 + 1");
    let tmp = tempfile::tempdir().unwrap();
    let path = tmp.path().join("b.harnbc");
    store_at(&path, &key, &chunk).expect("write");
    let other = CacheKey {
        compiler_tag: key.compiler_tag ^ 0xFF,
        ..key
    };
    assert!(
        read_entry_candidate(&path, &other).unwrap().is_none(),
        "flipped HARN_DISABLE_OPTIMIZATIONS must not reuse a chunk \
         compiled under the opposite setting"
    );
}

#[test]
fn codegen_fingerprint_is_populated() {
    // In-workspace builds always hash real compiler sources, so the
    // fingerprint must be a non-empty digest; an empty value would silently
    // disable the within-version compiler-staleness guard.
    assert!(!CODEGEN_FINGERPRINT.is_empty());
}

#[test]
fn codegen_fingerprint_changes_cache_key() {
    // A compiler whose code-generation source differs must produce a
    // different cache key for the *same* user source, so a stale artifact
    // compiled by a prior compiler at the same version misses on load
    // rather than being replayed (#2621). The fingerprint is a compile-time
    // constant, so exercise the parameterized inner hash directly.
    let tmp = tempfile::tempdir().unwrap();
    let entry = tmp.path().join("entry.harn");
    std::fs::write(&entry, "__io_println(\"hi\")\n").unwrap();
    let source = std::fs::read_to_string(&entry).unwrap();
    let a = hash_transitive_user_imports_fingerprinted(&entry, &source, "compiler-A");
    let b = hash_transitive_user_imports_fingerprinted(&entry, &source, "compiler-B");
    let a_again = hash_transitive_user_imports_fingerprinted(&entry, &source, "compiler-A");
    assert_ne!(
        a, b,
        "differing compiler fingerprints must change the cache key"
    );
    assert_eq!(
        a, a_again,
        "an unchanged compiler fingerprint must be stable"
    );
}

#[test]
fn module_context_hash_tracks_codegen_fingerprint() {
    let first = module_compilation_context_hash_fingerprinted("compiler-A");
    let second = module_compilation_context_hash_fingerprinted("compiler-B");
    assert_ne!(
        first, second,
        "module artifacts must miss when compiler code generation changes"
    );
    assert_eq!(
        first,
        module_compilation_context_hash_fingerprinted("compiler-A"),
        "an unchanged module compilation context must be stable"
    );
}

#[test]
fn module_key_excludes_dependency_graph_while_entry_key_tracks_it() {
    let tmp = tempfile::tempdir().unwrap();
    let dependency = tmp.path().join("value.harn");
    let importer = tmp.path().join("reader.harn");
    let importer_source = "import { value } from \"./value\"\npub fn read() { return value() }\n";
    std::fs::write(&dependency, "pub fn value() { return 1 }\n").unwrap();
    std::fs::write(&importer, importer_source).unwrap();

    let entry_before = CacheKey::from_source(&importer, importer_source);
    let module_before = CacheKey::from_module_source(&ModuleSource::from_text(importer_source));
    let dependency_before = CacheKey::from_module_source(&ModuleSource::from_text(
        std::fs::read_to_string(&dependency).unwrap(),
    ));

    std::fs::write(&dependency, "pub fn value() { return 2 }\n").unwrap();
    let future = std::fs::metadata(&dependency).unwrap().modified().unwrap()
        + std::time::Duration::from_secs(10);
    std::fs::OpenOptions::new()
        .write(true)
        .open(&dependency)
        .unwrap()
        .set_times(std::fs::FileTimes::new().set_modified(future))
        .unwrap();

    let entry_after = CacheKey::from_source(&importer, importer_source);
    let module_after = CacheKey::from_module_source(&ModuleSource::from_text(importer_source));
    let dependency_after = CacheKey::from_module_source(&ModuleSource::from_text(
        std::fs::read_to_string(&dependency).unwrap(),
    ));

    assert_ne!(
        entry_before, entry_after,
        "entry chunks compile the full graph and must track dependency edits"
    );
    assert_eq!(
        module_before, module_after,
        "a parent module artifact must not be invalidated by dependency contents"
    );
    assert_ne!(
        dependency_before, dependency_after,
        "the edited dependency must invalidate its own module artifact"
    );
}

#[test]
fn module_artifact_is_relocatable_and_rebinds_exact_source_path() {
    let source = "pub fn answer() { fn inner() { return 42 }; return inner() }\n";
    let first_path = Path::new("/workspace/first/module.harn");
    let second_path = Path::new("/workspace/second/module.harn");
    let key = CacheKey::from_module_source(&ModuleSource::from_text(source));

    let artifact = crate::module_artifact::compile_module_artifact_from_source(first_path, source)
        .expect("compile module");
    let first_source_file = first_path.display().to_string();
    let second_source_file = second_path.display().to_string();
    assert_eq!(
        artifact.functions["answer"].chunk.source_file.as_deref(),
        Some(first_source_file.as_str())
    );

    let tmp = tempfile::tempdir().unwrap();
    let cache_path = tmp.path().join(key.module_filename());
    store_module_at(&cache_path, &key, &artifact).expect("store module");
    let first_loaded = read_module_if_matches(&cache_path, &key, first_path)
        .expect("read first module")
        .expect("first module key matches");
    let second_loaded = read_module_if_matches(&cache_path, &key, second_path)
        .expect("read second module")
        .expect("second module key matches");
    assert_eq!(
        first_loaded.functions["answer"]
            .chunk
            .source_file
            .as_deref(),
        Some(first_source_file.as_str())
    );
    assert_eq!(
        second_loaded.functions["answer"]
            .chunk
            .source_file
            .as_deref(),
        Some(second_source_file.as_str())
    );
    let nested = second_loaded.functions["answer"]
        .chunk
        .functions
        .first()
        .expect("nested function survives artifact roundtrip");
    assert_eq!(
        nested.chunk.source_file.as_deref(),
        Some(second_source_file.as_str()),
        "rebinding must reach nested compiled functions"
    );
}

#[test]
fn source_local_module_artifact_round_trips() {
    let source = "import \"./dependency\"\npub fn answer() { return 42 }\n";
    let source_path = Path::new("/tmp/source-local-module.harn");
    let artifact = crate::module_artifact::compile_module_artifact_from_source(source_path, source)
        .expect("compile module");
    let key = CacheKey::from_module_source(&ModuleSource::from_text(source));
    let tmp = tempfile::tempdir().unwrap();
    let path = tmp.path().join("source-local-module.harnmod");

    store_module_at(&path, &key, &artifact).expect("write module artifact");
    let loaded = read_module_if_matches(&path, &key, source_path)
        .expect("read module artifact")
        .expect("matching artifact");

    assert_eq!(loaded.imports.len(), 1);
    assert_eq!(loaded.imports[0].path, "./dependency");
    assert!(loaded.public_exports.contains_key("answer"));
}

#[test]
fn module_artifact_payload_round_trips() {
    let source = "pub fn answer() { fn inner() { return 42 }; return inner() }\n";
    let source_path = Path::new("/tmp/module-payload.harn");
    let artifact = crate::module_artifact::compile_module_artifact_from_source(source_path, source)
        .expect("compile module");

    let payload = serialize_cache_payload(&artifact).expect("serialize module artifact");
    let round_tripped: ModuleArtifact =
        deserialize_cache_payload(&payload).expect("deserialize module artifact");

    assert_eq!(
        round_tripped.public_exports.get("answer"),
        Some(&harn_modules::DefKind::Function)
    );
    assert!(round_tripped.functions["answer"]
        .chunk
        .functions
        .iter()
        .any(|function| function.name == "inner"));
}

#[test]
fn cache_enabled_respects_env() {
    std::env::set_var(CACHE_ENABLED_ENV, "0");
    assert!(!cache_enabled());
    std::env::set_var(CACHE_ENABLED_ENV, "1");
    assert!(cache_enabled());
    std::env::remove_var(CACHE_ENABLED_ENV);
    assert!(cache_enabled());
}

#[test]
fn import_hash_is_stable_across_import_order() {
    let tmp = tempfile::tempdir().unwrap();
    std::fs::write(
        tmp.path().join("a.harn"),
        "pub fn a() -> int { return 1 }\n",
    )
    .unwrap();
    std::fs::write(
        tmp.path().join("b.harn"),
        "pub fn b() -> int { return 2 }\n",
    )
    .unwrap();
    let ab = tmp.path().join("entry_ab.harn");
    std::fs::write(
        &ab,
        "import \"./a\"\nimport \"./b\"\n__io_println(\"hi\")\n",
    )
    .unwrap();
    let ba = tmp.path().join("entry_ba.harn");
    std::fs::write(
        &ba,
        "import \"./b\"\nimport \"./a\"\n__io_println(\"hi\")\n",
    )
    .unwrap();
    let hash_ab = hash_transitive_user_imports(&ab, &std::fs::read_to_string(&ab).unwrap());
    let hash_ba = hash_transitive_user_imports(&ba, &std::fs::read_to_string(&ba).unwrap());
    assert_eq!(
        hash_ab, hash_ba,
        "import-graph hash must be order-independent so reordering imports \
         does not bust the cache"
    );
}

#[test]
fn import_hash_picks_up_nested_imports() {
    let tmp = tempfile::tempdir().unwrap();
    std::fs::write(
        tmp.path().join("leaf.harn"),
        "pub fn x() -> int { return 1 }\n",
    )
    .unwrap();
    std::fs::write(
        tmp.path().join("mid.harn"),
        "import \"./leaf\"\npub fn y() -> int { return 2 }\n",
    )
    .unwrap();
    let entry = tmp.path().join("entry.harn");
    std::fs::write(&entry, "import \"./mid\"\n__io_println(\"hi\")\n").unwrap();

    let before = hash_transitive_user_imports(&entry, &std::fs::read_to_string(&entry).unwrap());
    std::fs::write(
        tmp.path().join("leaf.harn"),
        "pub fn x() -> int { return 999 }\n",
    )
    .unwrap();
    let after = hash_transitive_user_imports(&entry, &std::fs::read_to_string(&entry).unwrap());
    assert_ne!(
        before, after,
        "editing a transitively-imported file must change the import-graph hash"
    );
}

#[test]
fn import_hash_sees_a_dependency_that_appears_between_walks() {
    // The sibling tests cover a dependency whose *contents* change. This
    // one covers an import whose *resolution* changes: unresolved first,
    // resolved once the file lands. The walk records unresolved imports as
    // a sentinel, so nothing about the entry source moves — only what the
    // import resolves to.
    //
    // Recomputed in the same process, because the invariant is that import
    // resolution is walk-local: no answer may outlive the walk that
    // produced it. The walk resolves once per import edge and can only
    // dedup afterwards, which makes a cross-walk resolution cache a
    // standing temptation (#5545) — one would keep reporting the sentinel
    // and serve stale bytecode for a graph that just gained a real
    // dependency.
    let tmp = tempfile::tempdir().unwrap();
    let entry = tmp.path().join("entry.harn");
    std::fs::write(&entry, "import \"./late\"\n__io_println(\"hi\")\n").unwrap();

    let missing = hash_transitive_user_imports(&entry, &std::fs::read_to_string(&entry).unwrap());
    std::fs::write(
        tmp.path().join("late.harn"),
        "pub fn late() -> int { return 1 }\n",
    )
    .unwrap();
    let present = hash_transitive_user_imports(&entry, &std::fs::read_to_string(&entry).unwrap());

    assert_ne!(
        missing, present,
        "an import that resolves only after the file appears must change the \
         import-graph hash"
    );
}

#[test]
fn identical_import_strings_in_different_directories_resolve_separately() {
    // An import string is only meaningful relative to the directory of the
    // file that wrote it, and the same string appears in many directories:
    // `./dep` is one of the most repeated edges in a real graph. Anything
    // that resolves imports by string alone lets one directory's `./dep`
    // answer for another's, silently collapsing two distinct modules into
    // one and pinning the entry to bytecode built from the wrong file.
    let tmp = tempfile::tempdir().unwrap();
    for (dir, body) in [("left", "return 1"), ("right", "return 2")] {
        std::fs::create_dir_all(tmp.path().join(dir)).unwrap();
        std::fs::write(
            tmp.path().join(dir).join("dep.harn"),
            format!("pub fn dep() -> int {{ {body} }}\n"),
        )
        .unwrap();
        std::fs::write(
            tmp.path().join(dir).join("mod.harn"),
            "import \"./dep\"\npub fn use_dep() -> int { return dep() }\n",
        )
        .unwrap();
    }
    let entry = tmp.path().join("entry.harn");
    std::fs::write(
        &entry,
        "import \"./left/mod\"\nimport \"./right/mod\"\n__io_println(\"hi\")\n",
    )
    .unwrap();

    // Edit each directory's `dep` in turn and require the hash to move both
    // times. Resolving by import string alone lets one `./dep` answer for
    // the other, which leaves exactly one of these two files out of the
    // graph entirely — but *which* one depends on traversal order, so
    // editing a single file is not a reliable falsifier. Editing both is.
    let mut hash = hash_transitive_user_imports(&entry, &std::fs::read_to_string(&entry).unwrap());
    for dir in ["left", "right"] {
        std::fs::write(
            tmp.path().join(dir).join("dep.harn"),
            "pub fn dep() -> int { return 999 }\n",
        )
        .unwrap();
        let next = hash_transitive_user_imports(&entry, &std::fs::read_to_string(&entry).unwrap());
        assert_ne!(
            hash, next,
            "editing {dir}/dep.harn must move the hash: each directory's \
             `./dep` resolves to its own file"
        );
        hash = next;
    }
}

/// Build a graph, compile it, and write the adjacent artifact with the
/// manifest the walk produced. Returns the entry path and its source.
fn seed_entry_with_manifest(tmp: &Path, dep_body: &str) -> (PathBuf, String) {
    let entry = tmp.join("entry.harn");
    let entry_source = "import \"./dep\"\n__io_println(\"hi\")\n".to_string();
    std::fs::write(&entry, &entry_source).unwrap();
    std::fs::write(tmp.join("dep.harn"), dep_body).unwrap();

    let (context_hash, manifest) =
        hash_transitive_user_imports_with_manifest(&entry, &entry_source);
    assert!(
        manifest.is_some(),
        "a graph of ordinary readable files must produce a manifest"
    );
    let key = CacheKey {
        source_hash: sha256(entry_source.as_bytes()),
        context_hash,
        harn_version: HARN_VERSION,
        compiler_tag: compiler_options_tag(CompilerOptions::from_env()),
    };
    let chunk = compile_source(&entry_source).expect("compile");
    write_atomic_chunk(
        &adjacent_cache_path(&entry).unwrap(),
        &key,
        &chunk,
        manifest.as_ref(),
    )
    .unwrap();
    (entry, entry_source)
}

/// Rewrite `path` with `body` while restoring its previous mtime, so the
/// file's stat identity is unchanged but its content is not.
fn edit_preserving_stat(path: &Path, body: &str) {
    let before = std::fs::metadata(path).unwrap();
    assert_eq!(
        before.len(),
        body.len() as u64,
        "this helper only models an edit stats cannot see"
    );
    std::fs::write(path, body).unwrap();
    let times = std::fs::FileTimes::new().set_modified(before.modified().unwrap());
    std::fs::File::options()
        .write(true)
        .open(path)
        .unwrap()
        .set_times(times)
        .unwrap();
}

#[test]
fn a_valid_manifest_serves_the_chunk_without_walking_the_graph() {
    // Proving a negative — "the walk did not run" — by making a change only
    // the walk could notice. The dependency's content changes while its
    // length and mtime do not, so the import-graph hash would differ if it
    // were recomputed. A hit therefore means the manifest answered.
    //
    // This is also the design's one accepted blind spot, stated as a fact
    // rather than left implicit: the same one Cargo, Zig and Bazel accept,
    // and the one `module_source`'s in-process read memo already accepts.
    let tmp = tempfile::tempdir().unwrap();
    let (entry, entry_source) =
        seed_entry_with_manifest(tmp.path(), "pub fn v() -> int { return 111 }\n");

    edit_preserving_stat(
        &tmp.path().join("dep.harn"),
        "pub fn v() -> int { return 222 }\n",
    );

    let walks_before = WALKS_PERFORMED.with(|c| c.get());
    assert!(
        load(&entry, &entry_source).chunk.is_some(),
        "a manifest whose stats all still match must serve the chunk"
    );
    assert_eq!(
        WALKS_PERFORMED.with(|c| c.get()),
        walks_before,
        "a valid manifest must serve the chunk without walking the graph"
    );
}

#[test]
fn a_directory_shadowed_import_does_not_defeat_the_manifest() {
    // A real 377-module tree turned out to contain two of these — an
    // `import "./types"` where `types/` is a directory, which resolves and then
    // fails to read. Treating an unreadable node as "cannot describe this graph"
    // dropped the manifest entirely, so the fast path was never once taken on
    // the graph it was built for, and the change was a pure regression.
    //
    // Nothing about the result was wrong, which is why only a measurement
    // caught it. This pins the manifest's *presence*, not just its answer.
    let tmp = tempfile::tempdir().unwrap();
    let entry = tmp.path().join("entry.harn");
    let entry_source = "import \"./types\"\nimport \"./dep\"\n__io_println(\"hi\")\n".to_string();
    std::fs::write(&entry, &entry_source).unwrap();
    std::fs::write(
        tmp.path().join("dep.harn"),
        "pub fn v() -> int { return 1 }\n",
    )
    .unwrap();
    std::fs::create_dir(tmp.path().join("types")).unwrap();

    let (_hash, manifest) = hash_transitive_user_imports_with_manifest(&entry, &entry_source);
    let manifest = manifest.expect("an unreadable node must not discard the manifest");
    assert_eq!(
        manifest.unreadable.len(),
        1,
        "the directory-shadowed import must be recorded, not dropped"
    );
    assert!(
        manifest.still_valid(),
        "nothing changed, so the manifest must still validate"
    );

    // And it must still *invalidate* when that node stops being unreadable:
    // replacing the directory with a real module adds a dependency.
    std::fs::remove_dir(tmp.path().join("types")).unwrap();
    std::fs::write(tmp.path().join("types"), "pub fn t() -> int { return 2 }\n").unwrap();
    assert!(
        !manifest.still_valid(),
        "a path that became readable changes the graph and must invalidate"
    );
}

#[test]
fn an_edited_dependency_still_misses() {
    // The manifest must not weaken the ordinary case: a real edit changes
    // length, the manifest rejects it, and the walk that follows finds a
    // different context hash.
    let tmp = tempfile::tempdir().unwrap();
    let (entry, entry_source) =
        seed_entry_with_manifest(tmp.path(), "pub fn v() -> int { return 1 }\n");

    std::fs::write(
        tmp.path().join("dep.harn"),
        "pub fn v() -> int { return 1234567 }\n",
    )
    .unwrap();

    assert!(
        load(&entry, &entry_source).chunk.is_none(),
        "an edited dependency must not be served from cache"
    );
}

#[test]
fn a_touched_dependency_refreshes_the_manifest_instead_of_re_walking_forever() {
    // `touch`, `git checkout` and `cp -p` all move mtime without changing
    // content. The key is unchanged, so the chunk is still good — but the
    // manifest no longer describes the tree, and without a refresh every
    // later spawn would pay for the walk again.
    let tmp = tempfile::tempdir().unwrap();
    let dep = tmp.path().join("dep.harn");
    let (entry, entry_source) =
        seed_entry_with_manifest(tmp.path(), "pub fn v() -> int { return 1 }\n");

    let stored_mtime = std::fs::metadata(&dep).unwrap().modified().unwrap();
    let bumped = stored_mtime + std::time::Duration::from_secs(5);
    std::fs::File::options()
        .write(true)
        .open(&dep)
        .unwrap()
        .set_times(std::fs::FileTimes::new().set_modified(bumped))
        .unwrap();

    assert!(
        load(&entry, &entry_source).chunk.is_some(),
        "content is unchanged, so the chunk is still valid"
    );

    let refreshed = read_entry_candidate(
        &adjacent_cache_path(&entry).unwrap(),
        &CacheKey {
            source_hash: sha256(entry_source.as_bytes()),
            context_hash: [0u8; 32],
            harn_version: HARN_VERSION,
            compiler_tag: compiler_options_tag(CompilerOptions::from_env()),
        },
    )
    .unwrap()
    .expect("artifact is still readable");
    let recorded = refreshed
        .manifest
        .expect("refresh must write a manifest back")
        .files
        .iter()
        .find(|f| f.path.ends_with("dep.harn"))
        .expect("dep is in the manifest")
        .mtime_ns;
    assert_eq!(
        recorded,
        module_source::stat_identity(&dep).unwrap().1,
        "the rewritten manifest must record the mtime now on disk"
    );
}

#[test]
fn import_hash_busts_on_same_length_edit_in_same_process() {
    // The per-file read/scan memo is keyed by `(path, len, mtime_ns)`. The
    // hardest case for that key is an edit that preserves byte length: only
    // the mtime distinguishes the two versions. Guard that a same-length edit
    // to a transitively-imported file, recomputed in the SAME process so the
    // memo is warm, still busts the import-graph hash. Without a working
    // staleness check a warm long-lived process would replay stale bytecode.
    let tmp = tempfile::tempdir().unwrap();
    let leaf = tmp.path().join("leaf.harn");
    std::fs::write(&leaf, "pub fn x() -> int { return 111 }\n").unwrap();
    let entry = tmp.path().join("entry.harn");
    std::fs::write(&entry, "import \"./leaf\"\n__io_println(\"hi\")\n").unwrap();

    let before = hash_transitive_user_imports(&entry, &std::fs::read_to_string(&entry).unwrap());

    // Same byte length (`111` -> `222`), so the memo must rely on mtime.
    // Instead of sleeping out the coarsest plausible mtime granularity,
    // push the rewritten file's mtime deterministically into the future so
    // the `(path, len, mtime_ns)` stat key changes instantly on every
    // filesystem this runs on.
    std::fs::write(&leaf, "pub fn x() -> int { return 222 }\n").unwrap();
    // Bump from the file's own current mtime by a fixed margin instead of
    // sleeping or using a large absolute timestamp literal.
    let future =
        std::fs::metadata(&leaf).unwrap().modified().unwrap() + std::time::Duration::from_secs(10);
    std::fs::OpenOptions::new()
        .write(true)
        .open(&leaf)
        .unwrap()
        .set_times(std::fs::FileTimes::new().set_modified(future))
        .unwrap();
    assert_eq!(
        std::fs::metadata(&leaf).unwrap().len(),
        33,
        "the two leaf versions must be the same byte length for this test to \
         exercise the mtime path"
    );

    let after = hash_transitive_user_imports(&entry, &std::fs::read_to_string(&entry).unwrap());
    assert_ne!(
        before, after,
        "a same-length edit to a transitively-imported file must still change \
         the import-graph hash when recomputed in a warm process"
    );
}

#[test]
fn import_hash_stable_across_repeated_calls_same_process() {
    // The memo must be a pure speed optimization: repeated `from_source`
    // calls over an unchanged tree (the cold-start module-load fan-out
    // pattern) must return byte-identical hashes.
    let tmp = tempfile::tempdir().unwrap();
    std::fs::write(
        tmp.path().join("dep.harn"),
        "pub fn d() -> int { return 7 }\n",
    )
    .unwrap();
    let entry = tmp.path().join("entry.harn");
    std::fs::write(&entry, "import \"./dep\"\n__io_println(\"hi\")\n").unwrap();
    let src = std::fs::read_to_string(&entry).unwrap();
    let first = hash_transitive_user_imports(&entry, &src);
    for _ in 0..50 {
        assert_eq!(
            hash_transitive_user_imports(&entry, &src),
            first,
            "repeated import-graph hashing over an unchanged tree must be stable"
        );
    }
}