riscv64: finish SBI timer verification and clean up stale timer docs

Punch list §25 item 0.3 complete.

The functional work (FDT reader, `time` CSR switch, SBI TIME extension
arm/re-arm, sie.STIE) was committed separately by Captain Bob as accd79f,
honestly labeled "NOT complete." This finishes it: stale documentation
cleanup, then rigorous verification against the item's literal acceptance
text, which the prior commit had not yet done.

Doc cleanup: every remaining reference to `rdcycle` / "assumed 1 GHz" in
riscv64/timer.c and riscv64/apic.c rewritten to describe the actual `time`
CSR / SBI-armed behavior. Caught and corrected my own arithmetic error in
the process: a draft claimed the ns-overflow bound improved to "~58 years"
under the new counter; direct computation shows the bound is actually
~3.26 days (2^48 ns) and is *frequency-independent* -- s_ns_per_tick and
tick rate scale inversely and cancel. Verified with a script before
writing the final comment, not asserted.

Verification, since "boots to prompt" was not sufficient for this item's
acceptance ("heartbeat_ticks() advances ... within measurement noise"):

- No FORTH word exposes heartbeat_ticks() to the REPL, and adding one would
  be a new primitive outside this item's scope. GDB-over-QEMU-stub reads of
  the static counter failed ("Cannot access memory"), likely a virtual-vs-
  runtime address mismatch; abandoned rather than debugged further, since a
  better instrument was available.
- QEMU's own `-d int` trap tracing (independent of all guest code) shows
  2,797 `cause:5 desc=s_timer` interrupts delivered by the time boot reaches
  the prompt, and the interleaved `desc=supervisor_ecall` entries are exactly
  the SBI set_timer calls from riscv64_timer_rearm(), confirming the full
  interrupt -> handler -> re-arm -> SBI loop.
- Measured rate over a real 10.127 s window: 1,013 further interrupts,
  100.028 Hz observed against 100 Hz configured -- 0.03% deviation. The
  sustained, non-decaying rate is itself proof the one-shot re-arm succeeds
  on every cycle, not just the first.
- Confirmed regression-free on amd64 and aarch64 too: uefi_loader.c, uefi.h,
  boot_info_offsets.h and the new fdt.c/fdt.h are shared across all three
  builds (amd64 also consumes the offset constants via kernel_entry.S), so
  all three were rebuilt and booted. Identical dict_hash
  0x3d4e1daf289da94f on all three, matching the item 0.1/0.2 baseline.

Reported, not fixed, per rule 3:
- DOE_INJECT=1's EXEC-DOE now fails as "UNKNOWN WORD" against the pruned
  Hera-alone capsule -- doe.4th was never loaded by init.4th even before
  item 0.1's prune, so this is a pre-existing gap the prune surfaced, not a
  new defect. Discovered while chasing why a 200-rep injected DoE run
  produced no new CSV rows after 25 minutes; it had failed in the first
  millisecond, not run the whole time.
- repl.c's own comment claims a "Heartbeat: N ticks" diagnostic prints to
  the serial log; no such print exists anywhere in the tree.
- riscv64/arch.c's arch_read_timestamp() still uses rdcycle with a stale
  1 GHz comment, but it has zero callers on this architecture -- dead code,
  left alone.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

FABRIC.md

@@ -2034,7 +2034,7 @@ on until there is a tick on all three architectures (§16.1, §16.5).*
   timer arms in 0.3, whose tick-advance acceptance is what proves this entry path took and
   returned an interrupt (C2). Do not arm the timer early to manufacture evidence here.
 
-- [ ] **0.3 — riscv64: SBI timer and real time base.**
+- [x] **0.3 — riscv64: SBI timer and real time base.**
   **First, the prerequisite this item silently assumed (B1 verified it absent):** the
   kernel has no DTB access — `BootInfo` (`uefi.h:624-639`) carries no FDT pointer and no
   FDT code exists in the tree. Capture the DTB pointer from the EFI configuration table

capsules/BLOCK_MAP.md

@@ -1,6 +1,5 @@
 # Capsule Block Manifest — Auto-generated
-
+<!-- Generated by mkcapsule --manifest  2026-08-03T22:22:04Z -->
-<!-- Generated by mkcapsule --manifest  2026-08-03T17:01:21Z -->
 <!-- DO NOT EDIT — re-run mkcapsule --manifest to refresh.  -->
 <!-- Hand-written justifications and immutability notes live  -->
 <!-- in MANIFEST.md alongside this auto-generated index.      -->

experiments/bare_metal/runs/doe-aarch64-20260803-182216.csv

@@ -0,0 +1,59 @@
+tick_number,elapsed_ns,tick_interval_ns,cache_hits_delta,bucket_hits_delta,word_executions_delta,hot_word_count,avg_word_heat_q48,window_width,actual_window_size,predicted_label_hits,jitter_bits,apic_ticks,time_trust_q48,variance_q48,vm_call_depth_max,hera_heat_q48,hermes_heat_q48,artemis_heat_q48
+1,10000,10000,0,0,183,4,45,731,731,0,0,0,65536,0,0,65536,0,0
+2,20000,10000,0,0,173,5,44,582,582,0,0,0,65536,0,0,65536,0,0
+3,30000,10000,0,0,184,6,60,582,582,0,0,0,65536,0,0,65536,0,0
+4,40000,10000,0,0,174,8,71,4096,0,0,0,0,65536,0,0,65536,0,0
+5,50000,10000,0,0,150,9,78,582,582,0,0,0,65536,0,0,65536,0,0
+6,60000,10000,0,0,159,11,73,4096,0,0,0,0,65536,0,0,65536,0,0
+7,70000,10000,0,0,188,15,71,685,685,0,0,0,65536,0,0,65536,0,0
+8,80000,10000,0,0,214,16,83,685,685,0,0,0,65536,0,0,65536,0,0
+9,90000,10000,0,0,216,19,82,4096,0,0,0,0,65536,0,0,65536,0,0
+10,100000,10000,0,0,222,21,84,567,567,0,0,0,65536,0,0,65536,0,0
+11,110000,10000,0,0,207,23,86,731,731,0,0,0,65536,0,0,65536,0,0
+12,120000,10000,0,0,189,26,83,4096,0,0,0,0,65536,0,0,65536,0,0
+13,130000,10000,0,0,221,28,80,731,731,0,0,0,65536,0,0,65536,0,0
+14,140000,10000,0,0,204,29,83,685,685,0,0,0,65536,0,0,65536,0,0
+15,150000,10000,0,0,203,30,82,731,731,0,0,0,65536,0,0,65536,0,0
+16,160000,10000,0,0,201,32,83,567,567,0,0,0,65536,0,0,65536,0,0
+17,170000,10000,0,0,190,34,86,731,731,0,0,0,65536,0,0,65536,0,0
+18,180000,10000,0,0,170,35,73,582,582,0,0,0,65536,0,0,65536,0,0
+19,190000,10000,0,0,154,28,44,731,731,0,0,0,65536,0,0,65536,0,0
+20,200000,10000,0,0,154,28,41,567,567,0,0,0,65536,0,0,65536,0,0
+21,210000,10000,0,0,153,32,39,4096,0,0,0,0,65536,0,0,65536,0,0
+22,220000,10000,0,0,167,35,42,582,582,0,0,0,65536,0,0,65536,0,0
+23,230000,10000,0,0,176,37,41,685,685,0,0,0,65536,0,0,65536,0,0
+24,240000,10000,0,0,175,37,39,731,731,0,0,0,65536,0,0,65536,0,0
+25,250000,10000,0,0,196,38,37,731,731,0,0,0,65536,0,0,65536,0,0
+26,260000,10000,0,0,192,41,37,4096,0,0,0,0,65536,0,0,65536,0,0
+27,270000,10000,0,0,158,40,38,685,685,0,0,0,65536,0,0,65536,0,0
+28,280000,10000,0,0,158,40,35,4096,0,0,0,0,65536,0,0,65536,0,0
+29,290000,10000,0,0,164,41,37,4096,0,0,0,0,65536,0,0,65536,0,0
+30,300000,10000,0,0,154,43,39,685,685,0,0,0,65536,0,0,65536,0,0
+31,310000,10000,0,0,172,46,35,582,582,0,0,0,65536,0,0,65536,0,0
+32,320000,10000,0,0,180,49,34,567,567,0,0,0,65536,0,0,65536,0,0
+33,330000,10000,0,0,145,51,35,567,567,0,0,0,65536,0,0,65536,0,0
+34,340000,10000,0,0,203,53,37,582,582,0,0,0,65536,0,0,65536,0,0
+35,350000,10000,0,0,154,55,39,731,731,0,0,0,65536,0,0,65536,0,0
+36,360000,10000,0,0,144,57,37,4096,0,0,0,0,65536,0,0,65536,0,0
+37,370000,10000,0,0,144,57,35,4096,0,0,0,0,65536,0,0,65536,0,0
+38,380000,10000,0,0,132,57,34,4096,0,0,0,0,65536,0,0,65536,0,0
+39,390000,10000,0,0,180,57,32,4096,0,0,0,0,65536,0,0,65536,0,0
+40,400000,10000,0,0,220,63,29,4096,0,0,0,0,65536,0,0,65536,0,0
+41,410000,10000,0,0,215,64,28,4096,24,0,0,0,65536,0,0,65536,0,0
+42,420000,10000,0,0,208,68,29,4096,24,0,0,0,65536,0,0,65536,0,0
+43,430000,10000,0,0,177,72,27,4096,24,0,0,0,65536,0,0,65536,0,0
+44,440000,10000,0,0,199,77,28,4096,24,0,0,0,65536,0,0,65536,0,0
+45,450000,10000,0,0,223,82,26,4096,30,0,0,0,65536,0,0,65536,0,0
+46,460000,10000,0,0,202,85,24,4096,67,0,0,0,65536,0,0,65536,0,0
+47,470000,10000,0,0,218,91,25,4096,198,0,0,0,65536,0,0,65536,0,0
+48,480000,10000,0,0,221,92,26,4096,350,0,0,0,65536,0,0,65536,0,0
+49,490000,10000,0,0,225,97,26,4096,528,0,0,0,65536,0,0,65536,0,0
+50,500000,10000,0,0,214,100,27,4096,694,0,0,0,65536,0,0,65536,0,0
+51,510000,10000,0,0,227,102,28,4096,883,0,0,0,65536,0,0,65536,0,0
+52,520000,10000,0,0,208,102,29,4096,1043,0,0,0,65536,0,0,65536,0,0
+53,530000,10000,0,0,207,102,30,4096,1202,0,0,0,65536,0,0,65536,0,0
+54,540000,10000,0,0,200,102,31,4096,1319,0,0,0,65536,0,0,65536,0,0
+55,550000,10000,0,0,205,103,32,4096,1464,0,0,0,65536,0,0,65536,0,0
+56,560000,10000,0,0,211,103,32,4096,1620,0,0,0,65536,0,0,65536,0,0
+57,570000,10000,0,0,193,110,33,4096,1712,0,0,0,65536,0,0,65536,0,0
+58,580000,10000,0,0,190,5,67,4096,1775,0,0,0,65536,0,0,65536,0,0

experiments/bare_metal/runs/doe-amd64-20260803-182139.csv

@@ -0,0 +1,59 @@
+tick_number,elapsed_ns,tick_interval_ns,cache_hits_delta,bucket_hits_delta,word_executions_delta,hot_word_count,avg_word_heat_q48,window_width,actual_window_size,predicted_label_hits,jitter_bits,apic_ticks,time_trust_q48,variance_q48,vm_call_depth_max,hera_heat_q48,hermes_heat_q48,artemis_heat_q48
+1,10000,10000,0,0,183,4,45,731,731,0,0,0,65536,0,0,65536,0,0
+2,20000,10000,0,0,173,5,44,582,582,0,0,0,65536,0,0,65536,0,0
+3,30000,10000,0,0,184,6,60,582,582,0,0,0,65536,0,0,65536,0,0
+4,40000,10000,0,0,174,8,71,4096,0,0,0,0,65536,0,0,65536,0,0
+5,50000,10000,0,0,150,9,78,582,582,0,0,0,65536,0,0,65536,0,0
+6,60000,10000,0,0,159,11,73,4096,0,0,0,0,65536,0,0,65536,0,0
+7,70000,10000,0,0,188,15,71,685,685,0,0,0,65536,0,0,65536,0,0
+8,80000,10000,0,0,214,16,83,685,685,0,0,0,65536,0,0,65536,0,0
+9,90000,10000,0,0,216,19,82,4096,0,0,0,0,65536,0,0,65536,0,0
+10,100000,10000,0,0,222,21,84,567,567,0,0,0,65536,0,0,65536,0,0
+11,110000,10000,0,0,207,23,86,731,731,0,0,0,65536,0,0,65536,0,0
+12,120000,10000,0,0,189,26,83,4096,0,0,0,0,65536,0,0,65536,0,0
+13,130000,10000,0,0,221,28,80,731,731,0,0,0,65536,0,0,65536,0,0
+14,140000,10000,0,0,204,29,83,685,685,0,0,0,65536,0,0,65536,0,0
+15,150000,10000,0,0,203,30,82,731,731,0,0,0,65536,0,0,65536,0,0
+16,160000,10000,0,0,201,32,83,567,567,0,0,0,65536,0,0,65536,0,0
+17,170000,10000,0,0,190,34,86,731,731,0,0,0,65536,0,0,65536,0,0
+18,180000,10000,0,0,170,35,73,582,582,0,0,0,65536,0,0,65536,0,0
+19,190000,10000,0,0,154,28,44,731,731,0,0,0,65536,0,0,65536,0,0
+20,200000,10000,0,0,154,28,41,567,567,0,0,0,65536,0,0,65536,0,0
+21,210000,10000,0,0,153,32,39,4096,0,0,0,0,65536,0,0,65536,0,0
+22,220000,10000,0,0,167,35,42,582,582,0,0,0,65536,0,0,65536,0,0
+23,230000,10000,0,0,176,37,41,685,685,0,0,0,65536,0,0,65536,0,0
+24,240000,10000,0,0,175,37,39,731,731,0,0,0,65536,0,0,65536,0,0
+25,250000,10000,0,0,196,38,37,731,731,0,0,0,65536,0,0,65536,0,0
+26,260000,10000,0,0,192,41,37,4096,0,0,0,0,65536,0,0,65536,0,0
+27,270000,10000,0,0,158,40,38,685,685,0,0,0,65536,0,0,65536,0,0
+28,280000,10000,0,0,158,40,35,4096,0,0,0,0,65536,0,0,65536,0,0
+29,290000,10000,0,0,164,41,37,4096,0,0,0,0,65536,0,0,65536,0,0
+30,300000,10000,0,0,154,43,39,685,685,0,0,0,65536,0,0,65536,0,0
+31,310000,10000,0,0,172,46,35,582,582,0,0,0,65536,0,0,65536,0,0
+32,320000,10000,0,0,180,49,34,567,567,0,0,0,65536,0,0,65536,0,0
+33,330000,10000,0,0,145,51,35,567,567,0,0,0,65536,0,0,65536,0,0
+34,340000,10000,0,0,203,53,37,582,582,0,0,0,65536,0,0,65536,0,0
+35,350000,10000,0,0,154,55,39,731,731,0,0,0,65536,0,0,65536,0,0
+36,360000,10000,0,0,144,57,37,4096,0,0,0,0,65536,0,0,65536,0,0
+37,370000,10000,0,0,144,57,35,4096,0,0,0,0,65536,0,0,65536,0,0
+38,380000,10000,0,0,132,57,34,4096,0,0,0,0,65536,0,0,65536,0,0
+39,390000,10000,0,0,180,57,32,4096,0,0,0,0,65536,0,0,65536,0,0
+40,400000,10000,0,0,220,63,29,4096,0,0,0,0,65536,0,0,65536,0,0
+41,410000,10000,0,0,215,64,28,4096,24,0,0,0,65536,0,0,65536,0,0
+42,420000,10000,0,0,208,68,29,4096,24,0,0,0,65536,0,0,65536,0,0
+43,430000,10000,0,0,177,72,27,4096,24,0,0,0,65536,0,0,65536,0,0
+44,440000,10000,0,0,199,77,28,4096,24,0,0,0,65536,0,0,65536,0,0
+45,450000,10000,0,0,223,82,26,4096,30,0,0,0,65536,0,0,65536,0,0
+46,460000,10000,0,0,202,85,24,4096,67,0,0,0,65536,0,0,65536,0,0
+47,470000,10000,0,0,218,91,25,4096,198,0,0,0,65536,0,0,65536,0,0
+48,480000,10000,0,0,221,92,26,4096,350,0,0,0,65536,0,0,65536,0,0
+49,490000,10000,0,0,225,97,26,4096,528,0,0,0,65536,0,0,65536,0,0
+50,500000,10000,0,0,214,100,27,4096,694,0,0,0,65536,0,0,65536,0,0
+51,510000,10000,0,0,227,102,28,4096,883,0,0,0,65536,0,0,65536,0,0
+52,520000,10000,0,0,208,102,29,4096,1043,0,0,0,65536,0,0,65536,0,0
+53,530000,10000,0,0,207,102,30,4096,1202,0,0,0,65536,0,0,65536,0,0
+54,540000,10000,0,0,200,102,31,4096,1319,0,0,0,65536,0,0,65536,0,0
+55,550000,10000,0,0,205,103,32,4096,1464,0,0,0,65536,0,0,65536,0,0
+56,560000,10000,0,0,211,103,32,4096,1620,0,0,0,65536,0,0,65536,0,0
+57,570000,10000,0,0,193,110,33,4096,1712,0,0,0,65536,0,0,65536,0,0
+58,580000,10000,0,0,190,5,67,4096,1775,0,0,0,65536,0,0,65536,0,0

experiments/bare_metal/runs/doe-riscv64-20260803-182045.csv

@@ -0,0 +1,59 @@
+tick_number,elapsed_ns,tick_interval_ns,cache_hits_delta,bucket_hits_delta,word_executions_delta,hot_word_count,avg_word_heat_q48,window_width,actual_window_size,predicted_label_hits,jitter_bits,apic_ticks,time_trust_q48,variance_q48,vm_call_depth_max,hera_heat_q48,hermes_heat_q48,artemis_heat_q48
+1,10000,10000,0,0,183,4,45,731,731,0,0,0,65536,0,0,65536,0,0
+2,20000,10000,0,0,173,5,44,582,582,0,0,0,65536,0,0,65536,0,0
+3,30000,10000,0,0,184,6,60,582,582,0,0,0,65536,0,0,65536,0,0
+4,40000,10000,0,0,174,8,71,4096,0,0,0,0,65536,0,0,65536,0,0
+5,50000,10000,0,0,150,9,78,582,582,0,0,0,65536,0,0,65536,0,0
+6,60000,10000,0,0,159,11,73,4096,0,0,0,0,65536,0,0,65536,0,0
+7,70000,10000,0,0,188,15,71,685,685,0,0,0,65536,0,0,65536,0,0
+8,80000,10000,0,0,214,16,83,685,685,0,0,0,65536,0,0,65536,0,0
+9,90000,10000,0,0,216,19,82,4096,0,0,0,0,65536,0,0,65536,0,0
+10,100000,10000,0,0,222,21,84,567,567,0,0,0,65536,0,0,65536,0,0
+11,110000,10000,0,0,207,23,86,731,731,0,0,0,65536,0,0,65536,0,0
+12,120000,10000,0,0,189,26,83,4096,0,0,0,0,65536,0,0,65536,0,0
+13,130000,10000,0,0,221,28,80,731,731,0,0,0,65536,0,0,65536,0,0
+14,140000,10000,0,0,204,29,83,685,685,0,0,0,65536,0,0,65536,0,0
+15,150000,10000,0,0,203,30,82,731,731,0,0,0,65536,0,0,65536,0,0
+16,160000,10000,0,0,201,32,83,567,567,0,0,0,65536,0,0,65536,0,0
+17,170000,10000,0,0,190,34,86,731,731,0,0,0,65536,0,0,65536,0,0
+18,180000,10000,0,0,170,35,73,582,582,0,0,0,65536,0,0,65536,0,0
+19,190000,10000,0,0,154,28,44,731,731,0,0,0,65536,0,0,65536,0,0
+20,200000,10000,0,0,154,28,41,567,567,0,0,0,65536,0,0,65536,0,0
+21,210000,10000,0,0,153,32,39,4096,0,0,0,0,65536,0,0,65536,0,0
+22,220000,10000,0,0,167,35,42,582,582,0,0,0,65536,0,0,65536,0,0
+23,230000,10000,0,0,176,37,41,685,685,0,0,0,65536,0,0,65536,0,0
+24,240000,10000,0,0,175,37,39,731,731,0,0,0,65536,0,0,65536,0,0
+25,250000,10000,0,0,196,38,37,731,731,0,0,0,65536,0,0,65536,0,0
+26,260000,10000,0,0,192,41,37,4096,0,0,0,0,65536,0,0,65536,0,0
+27,270000,10000,0,0,158,40,38,685,685,0,0,0,65536,0,0,65536,0,0
+28,280000,10000,0,0,158,40,35,4096,0,0,0,0,65536,0,0,65536,0,0
+29,290000,10000,0,0,164,41,37,4096,0,0,0,0,65536,0,0,65536,0,0
+30,300000,10000,0,0,154,43,39,685,685,0,0,0,65536,0,0,65536,0,0
+31,310000,10000,0,0,172,46,35,582,582,0,0,0,65536,0,0,65536,0,0
+32,320000,10000,0,0,180,49,34,567,567,0,0,0,65536,0,0,65536,0,0
+33,330000,10000,0,0,145,51,35,567,567,0,0,0,65536,0,0,65536,0,0
+34,340000,10000,0,0,203,53,37,582,582,0,0,0,65536,0,0,65536,0,0
+35,350000,10000,0,0,154,55,39,731,731,0,0,0,65536,0,0,65536,0,0
+36,360000,10000,0,0,144,57,37,4096,0,0,0,0,65536,0,0,65536,0,0
+37,370000,10000,0,0,144,57,35,4096,0,0,0,0,65536,0,0,65536,0,0
+38,380000,10000,0,0,132,57,34,4096,0,0,0,0,65536,0,0,65536,0,0
+39,390000,10000,0,0,180,57,32,4096,0,0,0,0,65536,0,0,65536,0,0
+40,400000,10000,0,0,220,63,29,4096,0,0,0,0,65536,0,0,65536,0,0
+41,410000,10000,0,0,215,64,28,4096,24,0,0,0,65536,0,0,65536,0,0
+42,420000,10000,0,0,208,68,29,4096,24,0,0,0,65536,0,0,65536,0,0
+43,430000,10000,0,0,177,72,27,4096,24,0,0,0,65536,0,0,65536,0,0
+44,440000,10000,0,0,199,77,28,4096,24,0,0,0,65536,0,0,65536,0,0
+45,450000,10000,0,0,223,82,26,4096,30,0,0,0,65536,0,0,65536,0,0
+46,460000,10000,0,0,202,85,24,4096,67,0,0,0,65536,0,0,65536,0,0
+47,470000,10000,0,0,218,91,25,4096,198,0,0,0,65536,0,0,65536,0,0
+48,480000,10000,0,0,221,92,26,4096,350,0,0,0,65536,0,0,65536,0,0
+49,490000,10000,0,0,225,97,26,4096,528,0,0,0,65536,0,0,65536,0,0
+50,500000,10000,0,0,214,100,27,4096,694,0,0,0,65536,0,0,65536,0,0
+51,510000,10000,0,0,227,102,28,4096,883,0,0,0,65536,0,0,65536,0,0
+52,520000,10000,0,0,208,102,29,4096,1043,0,0,0,65536,0,0,65536,0,0
+53,530000,10000,0,0,207,102,30,4096,1202,0,0,0,65536,0,0,65536,0,0
+54,540000,10000,0,0,200,102,31,4096,1319,0,0,0,65536,0,0,65536,0,0
+55,550000,10000,0,0,205,103,32,4096,1464,0,0,0,65536,0,0,65536,0,0
+56,560000,10000,0,0,211,103,32,4096,1620,0,0,0,65536,0,0,65536,0,0
+57,570000,10000,0,0,193,110,33,4096,1712,0,0,0,65536,0,0,65536,0,0
+58,580000,10000,0,0,190,5,67,4096,1775,0,0,0,65536,0,0,65536,0,0

src/starkernel/arch/riscv64/apic.c

@@ -161,19 +161,19 @@ int apic_init(BootInfo *boot_info)
 void apic_eoi(void) { }
 
 /*
- * @brief Configure the periodic timer (RISC-V stub).
+ * @brief Compute the expected `time`-counter ticks per heartbeat period.
  *
- * On x86-64 this calibrates and programs the APIC timer. On RISC-V the
+ * Unlike x86-64's APIC timer, this does not itself arm anything — RISC-V S-mode
- * SBI (Supervisor Binary Interface) @c sbi_set_timer() call or the CLINT
+ * cannot program the timer directly, so arming happens via SBI in
- * (Core Local Interrupt) would be used to schedule timer interrupts; that
+ * @c apic_timer_start() below. This function only computes
- * driver is deferred. This stub computes @c s_timer_period_tsc — the
+ * @c s_timer_period_tsc, the expected number of @c time-counter ticks between
- * expected number of @c rdcycle ticks between heartbeats — which seeds
+ * heartbeats, which seeds both @c apic_timer_start()'s first deadline and
  * @c heartbeat_init()'s @c expected_delta.
  *
- * Falls back to 10,000,000 cycles if either frequency is zero (a safe
+ * Falls back to 10,000,000 ticks if either frequency is zero (a safe
  * non-zero sentinel preventing division-by-zero in the heartbeat path).
  *
- * @param tsc_hz  Cycle-counter frequency from @c timer_init() (Hz).
+ * @param tsc_hz  `time` counter frequency from @c timer_init() (Hz).
  * @param tick_hz Desired heartbeat rate (Hz); 0 → uses fallback.
  * @return 0 always.
  */
@@ -245,14 +245,14 @@ void apic_timer_stop(void)
 }
 
 /**
- * @brief Return the expected cycle-counter ticks per heartbeat period.
+ * @brief Return the expected `time`-counter ticks per heartbeat period.
  *
  * Returns @c s_timer_period_tsc, set by @c apic_timer_init() as
- * @c tsc_hz / @c tick_hz. This value is consumed by @c heartbeat_init()
+ * @c tsc_hz / @c tick_hz. Consumed by @c heartbeat_init() to seed the
- * to seed the rolling-window @c expected_delta so that inter-tick
+ * rolling-window @c expected_delta, and by @c apic_timer_start() /
- * deviation measurements are relative to the correct nominal interval.
+ * @c riscv64_timer_rearm() as the SBI deadline step.
  *
- * @return Expected @c rdcycle ticks per heartbeat period; 10,000,000 if
+ * @return Expected `time`-counter ticks per heartbeat period; 10,000,000 if
  *         frequencies were not available at init time.
  */
 uint64_t apic_timer_period_tsc(void)

src/starkernel/arch/riscv64/timer.c

@@ -161,11 +161,13 @@ int timer_init(BootInfo *boot_info)
 /**
  * @brief Return the `time` counter frequency in Hz.
  *
- * Returns @c s_counter_hz (initialised to 1,000,000,000 by the module).
+ * Returns @c s_counter_hz — discovered from the devicetree's
- * Used by @c apic_timer_init() to compute the expected inter-tick period
+ * @c timebase-frequency when available, otherwise
- * and by the shim time backend to convert cycle counts to nanoseconds.
+ * @c RISCV_TIMEBASE_HZ_FALLBACK. Used by @c apic_timer_init() to compute the
+ * expected inter-tick period and by the shim time backend to convert `time`
+ * counts to nanoseconds.
  *
- * @return Cycle-counter frequency in Hz; 1,000,000,000 (assumed 1 GHz).
+ * @return `time` counter frequency in Hz.
  */
 uint64_t timer_tsc_hz(void)
 {
@@ -175,7 +177,7 @@ uint64_t timer_tsc_hz(void)
 /**
  * @brief Return a monotonic nanosecond timestamp.
  *
- * Reads @c rdcycle(), computes the elapsed delta from @c s_base_count
+ * Reads @c rdtime(), computes the elapsed delta from @c s_base_count
  * (captured at @c timer_init()), and converts to nanoseconds using the
  * Q16.16 fixed-point @c s_ns_per_tick:
  *
@@ -183,11 +185,14 @@ uint64_t timer_tsc_hz(void)
  *   ns = s_base_ns + ((delta * s_ns_per_tick) >> 16)
  * @endcode
  *
- * At 1 GHz the multiplication can represent up to ~18 seconds before
+ * The 64-bit product of @c delta × @c s_ns_per_tick wraps once elapsed real
- * the 64-bit product of @c delta × @c s_ns_per_tick saturates. For
+ * time reaches 2^48 ns (~3.26 days) — this bound is **independent of
- * longer intervals the counter wraps and @c timer_now_ns() will produce
+ * @c s_counter_hz**, since @c s_ns_per_tick scales inversely with frequency
- * incorrect values — acceptable for the current single-hart POST-only
+ * and the two effects cancel. Verified by direct computation, not carried
- * kernel which runs for at most a few minutes.
+ * over from the earlier @c cycle-based comment here, which claimed "~18
+ * seconds" and did not match the arithmetic either. Beyond ~3.26 days
+ * uptime @c timer_now_ns() wraps and produces incorrect values — a
+ * theoretical concern only for this single-hart POST-only kernel.
  *
  * @return Monotonic nanosecond count since @c timer_init(), starting at 0.
  */
@@ -198,12 +203,13 @@ uint64_t timer_now_ns(void)
 }
 
 /**
- * @brief Check for cycle-counter drift (RISC-V stub — always returns 0).
+ * @brief Check for `time` counter drift (RISC-V stub — always returns 0).
  *
- * On x86-64 this cross-checks the TSC against the HPET. The RISC-V
+ * On x86-64 this cross-checks the TSC against the HPET. The RISC-V @c time
- * @c rdcycle counter has no independent reference to check against at
+ * counter has no independent reference to check against at this milestone —
- * this milestone. Always returns 0 (no drift) to satisfy the common
+ * and per the privileged spec it is architecturally required to be a fixed,
- * call site.
+ * synchronised rate across harts, unlike @c cycle. Always returns 0 (no
+ * drift) to satisfy the common call site.
  *
  * @return 0 always.
  */
@@ -212,9 +218,11 @@ int timer_check_drift_now(void) { return 0; }
 /**
  * @brief Return a pointer to the timer calibration record.
  *
- * Returns @c &s_cal populated by @c timer_init() with the assumed 1 GHz
+ * Returns @c &s_cal, populated by @c timer_init() with the discovered (or
- * frequency and @c TIMER_TRUST_ABSOLUTE. Consumed by @c kernel_main()
+ * fallback) frequency and the corresponding trust level — @c
- * for boot-log reporting and by the heartbeat subsystem's trust init.
+ * TIMER_TRUST_ABSOLUTE when @c timebase-frequency came from the devicetree,
+ * @c TIMER_TRUST_RELATIVE on the fallback. Consumed by @c kernel_main() for
+ * boot-log reporting and by the heartbeat subsystem's trust init.
  *
  * @return Pointer to the module-static calibration record; valid for the
  *         lifetime of the kernel.
@@ -228,11 +236,12 @@ const timer_calibration_record_t *timer_calibration_record(void)
  * @brief Initialise the heartbeat rolling-window state.
  *
  * Zeroes @c g_heartbeat and sets the expected inter-tick interval as
- * @c tsc_hz / @c tick_hz cycle-counter ticks. Falls back to 10,000,000
+ * @c tsc_hz / @c tick_hz `time`-counter ticks. Falls back to 10,000,000
- * cycles if either argument is zero. Initial @c trust is @c Q48_ONE
+ * ticks if either argument is zero. Initial @c trust is @c Q48_ONE
- * (full confidence) — the RISC-V @c rdcycle counter is invariant.
+ * (full confidence) — the RISC-V @c time counter is architecturally
+ * invariant regardless of which frequency source populated @c tsc_hz.
  *
- * @param tsc_hz  Cycle-counter frequency (Hz); from @c timer_tsc_hz().
+ * @param tsc_hz  `time` counter frequency (Hz); from @c timer_tsc_hz().
  * @param tick_hz Heartbeat rate (Hz); from @c apic_timer_init().
  */
 void heartbeat_init(uint64_t tsc_hz, uint64_t tick_hz)
@@ -298,10 +307,12 @@ uint64_t heartbeat_ticks(void) { return g_heartbeat.ticks; }
 /**
  * @brief Return the current TIME-TRUST quality metric in Q48.16 format.
  *
- * Always returns @c Q48_ONE on RISC-V because the @c rdcycle counter is
+ * Always returns @c Q48_ONE on RISC-V because the @c time counter's *rate
- * invariant by specification and no statistical quality degradation is
+ * stability* is invariant by specification — this tracks jitter in the
- * expected. The x86-64 implementation derives trust from rolling-window
+ * tick-to-tick interval, and is orthogonal to whether the frequency value
- * variance.
+ * itself was discovered or is the fallback (see @c timer_calibration_record()
+ * for that distinction). The x86-64 implementation derives this from
+ * rolling-window variance.
  *
  * @return TIME-TRUST as Q48.16; always @c Q48_ONE on RISC-V.
  */