Add HEARTBEAT-TICKS@: read-only heartbeat tick counter accessor

The adaptive heartbeat tick counter (vm->heartbeat.tick_count) is the
project's sole canonical clock for timing measurements -- host wall-clock
is not a valid substitute. Exposes it read-only so DoE/overhead campaigns
can measure elapsed ticks instead of wall-clock deltas.

Verified: three-arch QEMU acceptance (amd64/aarch64/riscv64), POST
1012/0/0 on each, HEARTBEAT-TICKS@ live-tested returning a real non-zero
count on all three.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-08-20 23:10:38 -04:00
co-authored by Claude Sonnet 5
parent 6e7323b3b8
commit 0b11f92102
4 changed files with 17 additions and 1 deletions
+1 -1
View File
@@ -1,5 +1,5 @@
# Capsule Block Manifest — Auto-generated
<!-- Generated by mkcapsule --manifest 2026-08-20T14:53:07Z -->
<!-- Generated by mkcapsule --manifest 2026-08-21T03:09:23Z -->
<!-- DO NOT EDIT — re-run mkcapsule --manifest to refresh. -->
<!-- Hand-written justifications and immutability notes live -->
<!-- in MANIFEST.md alongside this auto-generated index. -->
BIN
View File
Binary file not shown.
Binary file not shown.
+16
View File
@@ -793,6 +793,20 @@ static void starforth_word_zuse_authenticate(VM *vm)
vm->zuse_session = 1;
}
/**
* @brief Read-only accessor for the canonical heartbeat tick counter
*
* Stack effect: ( -- n )
* Pushes vm->heartbeat.tick_count -- the one clock this project's timing
* measurements are supposed to read, not host wall-clock. Read-only: no
* corresponding store word exists or should exist.
* @param vm Pointer to the VM instance
*/
static void starforth_word_heartbeat_ticks(VM* vm)
{
vm_push(vm, (cell_t)vm->heartbeat.tick_count);
}
/**
* @brief Register StarForth vocabulary words with the VM
*
@@ -812,6 +826,7 @@ void register_starforth_words(VM* vm)
register_word(vm, "RANDOM", starforth_word_random);
register_word(vm, "WAIT", starforth_word_wait);
register_word(vm, "ZUSE-AUTHENTICATE", starforth_word_zuse_authenticate);
register_word(vm, "HEARTBEAT-TICKS@", starforth_word_heartbeat_ticks);
vm_bootstrap_root_vocabulary(vm, "STARFORTH");
STARFORTH_CHECK_ARENA("register_starforth_words:post-root");
@@ -829,6 +844,7 @@ void register_starforth_words(VM* vm)
register_word(vm, "RANDOM", starforth_word_random);
register_word(vm, "WAIT", starforth_word_wait);
register_word(vm, "ZUSE-AUTHENTICATE", starforth_word_zuse_authenticate);
register_word(vm, "HEARTBEAT-TICKS@", starforth_word_heartbeat_ticks);
vocabulary_word_forth(vm);
vocabulary_word_definitions(vm);