// Moved from docs/src/internal/PHYSICS_IMPLEMENTATION_OPTIONS.adoc to docs/working/scratch/src/internal/PHYSICS_IMPLEMENTATION_OPTIONS.adoc on 2026-06-16 (docs reorg Phase 2) = Physics Engine Implementation Options: Three Paths Forward :toc: left :toclevels: 2 xref:../README.adoc[← Back to Documentation Index] == Current State: What's Complete The physics engine infrastructure is **phase 1 complete**: - ✅ Execution hooks wired (vm.c:456, vm.c:533 call `physics_metadata_touch()`) - ✅ Word metadata initialized with domain knowledge (20-word seed table) - ✅ Temperature calculation via exponential moving average from entropy - ✅ Analytics heap allocated (10 MB default) - ✅ Host snapshots functional (POSIX comprehensive, L4Re stub) - ✅ Design documents created: * PHYSICS_IMPLEMENTATION_STATUS.adoc (analysis) * PHYSICS_CONE_OF_INFLUENCE_DESIGN.adoc (zone architecture) * PHYSICS_CONTROL_SYSTEM_DESIGN.adoc (scheduling + memory integration) **Missing**: No periodic capture mechanism, no temperature decay model, no feedback loop integration. --- == OPTION A: Zone 1 Discovery (1-2 hours) **Goal**: Wire the observable data stream end-to-end. Verify metrics flow from word execution → analytics heap. **Scope**: Small, focused implementation. Proves infrastructure works before building bigger systems. === Implementation Steps ==== Step 1: Add Periodic Host Snapshot Hook (30 min) **Location**: `src/main.c` (REPL loop) **Change**: Call `physics_host_snapshot()` at fixed intervals during REPL input [source,c] ---- // In main's input loop (currently around main.c:XXX) static uint64_t last_snapshot_ns = 0; while (1) { // ... existing REPL loop ... // Every 10ms: capture host snapshot uint64_t now = sf_monotonic_ns(); if (now - last_snapshot_ns > 10_000_000) { // 10ms physics_host_snapshot_t snap; physics_host_snapshot(&snap); physics_analytics_publish_event(&snap, sizeof(snap)); last_snapshot_ns = now; } // ... continue with input/execution ... } ---- **Verification**: ```bash # Build and run REPL make clean && make ./build/starforth # Inside REPL: define a hot word and execute repeatedly : HOT 1 2 + DUP DUP + DUP + ; : LOOP-HOT 100 0 DO HOT LOOP ; LOOP-HOT # No visible output yet (data goes to heap, not stdout) ``` **Deliverable**: Snapshots are published to ring buffer every 10ms during execution. --- ==== Step 2: Add Heap Dump Diagnostic Command (30 min) **Location**: New file `src/word_source/physics_words.c` **Change**: Add FORTH words to inspect analytics heap [source,c] ---- // New word: PHYSICS-HEAP-DUMP // Prints summary of analytics heap contents void forth_PHYSICS_HEAP_DUMP(VM *vm) { if (vm->error_flag) return; printf("=== Analytics Heap Dump ===\n"); printf("Heap size: %zu bytes\n", g_runtime.analytics_heap_size); printf("Heap used: %zu bytes\n", g_runtime.heap_end); printf("Ring buffer position: %zu\n", g_runtime.ring_write_pos); // Count events in heap uint32_t event_count = 0; char *ptr = (char *)g_runtime.analytics_heap; while (ptr - (char *)g_runtime.analytics_heap < (ptrdiff_t)g_runtime.heap_end) { physics_analytics_header_t *hdr = (physics_analytics_header_t *)ptr; if (hdr->magic != PHYSICS_EVENT_MAGIC) break; event_count++; printf("Event %u: type=%u, timestamp=%llu\n", event_count, hdr->event_type, hdr->timestamp_ns); ptr += sizeof(*hdr) + hdr->data_size; } printf("Total events: %u\n", event_count); } // Register in word_registry.h REGISTER_WORD("PHYSICS-HEAP-DUMP", forth_PHYSICS_HEAP_DUMP), ---- **Verification**: ``` : HOT 1 2 + DUP + ; : BURN 1000 0 DO HOT LOOP ; BURN PHYSICS-HEAP-DUMP # Output: Shows X events published ``` **Deliverable**: User can inspect heap contents from FORTH. --- ==== Step 3: Add Temperature Visualization (30 min) **Location**: New FORTH word in `physics_words.c` **Change**: Print per-word temperature distribution [source,c] ---- // New word: PHYSICS-TEMPS // Show temperature distribution of recently-executed words void forth_PHYSICS_TEMPS(VM *vm) { if (vm->error_flag) return; printf("=== Word Temperatures ===\n"); printf("%-20s %8s %8s %12s\n", "Word", "Temp(q8)", "Age(sec)", "Exec Count"); DictEntry *entry = vm->dictionary; int count = 0; while (entry && count++ < 20) { // Show hottest 20 uint64_t age_ns = sf_monotonic_ns() - entry->physics.last_active_ns; uint64_t age_sec = age_ns / 1_000_000_000; printf("%-20s 0x%04x %8llu %12llu\n", entry->name, entry->physics.temperature_q8, age_sec, entry->exec_count); entry = entry->link; } } // Register in word_registry.h REGISTER_WORD("PHYSICS-TEMPS", forth_PHYSICS_TEMPS), ---- **Verification**: ``` : A 1 + ; : B A A A ; : C B B B ; 100 0 DO C LOOP PHYSICS-TEMPS # Output shows temperature distribution # Expected: C > B > A (C is hottest, deepest in call tree) ``` **Deliverable**: User can see per-word thermal distribution. --- ==== Step 4: Test End-to-End Data Flow (30 min) **Location**: New test in `src/test_runner/modules/test_physics_observation.c` **Change**: Add test that verifies metrics flow [source,c] ---- // In test_physics_observation.c (new file) static void test_physics_observation_end_to_end(void) { VM vm; vm_init(&vm, NULL); // Clear analytics heap physics_runtime_init(10 * 1024 * 1024); // Define a word and execute it many times vm_interpret(&vm, ": HOT 1 2 + ;"); vm_interpret(&vm, "1000 0 DO HOT LOOP"); // Take a snapshot physics_host_snapshot_t snap; physics_host_snapshot(&snap); physics_analytics_publish_event(&snap, sizeof(snap)); // Verify heap has events ASSERT(g_runtime.heap_end > 0, "Heap should have data"); // Verify word temperature increased DictEntry *hot = dict_lookup(&vm, "HOT"); ASSERT(hot != NULL, "HOT word should exist"); ASSERT(hot->physics.temperature_q8 > 0x4000, "HOT should be warm after 1000 executions"); // Verify last_active_ns was updated uint64_t age = sf_monotonic_ns() - hot->physics.last_active_ns; ASSERT(age < 1_000_000, "Last execution should be recent (< 1ms)"); vm_cleanup(&vm); physics_runtime_shutdown(); } ---- **Test Output**: ```bash make test # Should see: test_physics_observation_end_to_end PASS ``` **Deliverable**: Automated test confirms data flow works. --- === Summary: Zone 1 Discovery **Total Effort**: 1.5-2 hours **Deliverables**: - Periodic host snapshots (every 10ms) - Two debugging words (PHYSICS-HEAP-DUMP, PHYSICS-TEMPS) - End-to-end test - Confidence that metrics are flowing correctly **Dependencies**: None. Builds on existing infrastructure. **Next Step After**: Enables Option B (metrics infrastructure) or Option C (design questions). --- == OPTION B: Metrics Infrastructure (2-3 days) **Goal**: Add comprehensive metrics collection that feeds into scheduling and memory decisions. **Scope**: Medium. Builds real observability infrastructure that will be used by control systems. === Implementation Steps ==== Step 1: Stack Depth & Recursion Tracking (3-4 hours) **Location**: New in `include/physics_metrics.h` and `src/physics_metrics.c` **Problem**: Current physics only tracks temperature. We need: - Per-word call stack depth (how deeply nested?) - Recursion detection (is word calling itself?) - Stack pressure (how close to overflow?) [source,c] ---- // In include/physics_metrics.h typedef struct { uint16_t current_depth; // Current call stack depth uint16_t max_depth; // Max depth observed uint8_t is_recursive; // Does word call itself? uint8_t has_deep_calls; // Calls other deep words? uint32_t depth_violations; // How many times exceeded limit? } stack_metrics_t; // In src/physics_metrics.c void physics_record_call_depth(DictEntry *word, uint16_t depth) { if (depth > word->stack_metrics.max_depth) { word->stack_metrics.max_depth = depth; } if (depth > PHYSICS_STACK_WARN_THRESHOLD) { word->stack_metrics.depth_violations++; } } ---- **Integration Point**: In `vm.c` when pushing return stack frame: [source,c] ---- // In execute_colon_word() where return stack is pushed return_stack[return_stack_ptr++] = (Cell)(uintptr_t)ip; // NEW: Track call depth uint16_t call_depth = return_stack_ptr; DictEntry *called_word = (DictEntry *)(uintptr_t)(*ip); physics_record_call_depth(called_word, call_depth); ---- **Test**: ``` : A 1 + ; : B A A A ; : C B B B B ; 100 0 DO C LOOP PHYSICS-STACK-METRICS # Should show: C.max_depth = 5, A.max_depth = 3, etc. ``` **Deliverable**: Per-word call depth tracking. --- ==== Step 2: Latency Percentile Tracking (4-5 hours) **Location**: New in `include/physics_metrics.h` and `src/physics_metrics.c` **Problem**: Current code records latency but not percentiles. We need P50, P99, P99.9 for SLO enforcement. [source,c] ---- // In include/physics_metrics.h #define LATENCY_HISTOGRAM_BUCKETS 32 typedef struct { uint64_t min_ns; // Minimum latency observed uint64_t max_ns; // Maximum latency observed uint64_t sum_ns; // Total latency (for average) uint64_t call_count; // Number of executions uint32_t histogram[LATENCY_HISTOGRAM_BUCKETS]; // Latency histogram } latency_metrics_t; // Function to record latency void physics_record_latency(DictEntry *word, uint64_t latency_ns) { if (latency_ns < word->latency_metrics.min_ns) { word->latency_metrics.min_ns = latency_ns; } if (latency_ns > word->latency_metrics.max_ns) { word->latency_metrics.max_ns = latency_ns; } word->latency_metrics.sum_ns += latency_ns; word->latency_metrics.call_count++; // Histogram: bucket by magnitude int bucket = 0; if (latency_ns > 10000) bucket = 1; if (latency_ns > 100000) bucket = 2; // ... etc if (bucket < LATENCY_HISTOGRAM_BUCKETS) { word->latency_metrics.histogram[bucket]++; } } // Function to compute percentiles uint64_t physics_latency_percentile(DictEntry *word, int percentile) { // Walk histogram to find percentile uint64_t target = (word->latency_metrics.call_count * percentile) / 100; uint64_t cumulative = 0; for (int i = 0; i < LATENCY_HISTOGRAM_BUCKETS; i++) { cumulative += word->latency_metrics.histogram[i]; if (cumulative >= target) { return (1000 << i); // Return bucket upper bound } } return word->latency_metrics.max_ns; } ---- **Integration Point**: In `vm.c` during word execution: [source,c] ---- // Outer interpreter (vm.c:533) uint64_t latency_start = sf_monotonic_ns(); entry->func(vm); uint64_t latency_ns = sf_monotonic_ns() - latency_start; physics_record_latency(entry, latency_ns); ---- **Test**: ``` : SLOW 100000 0 DO 1 LOOP ; 1000 0 DO SLOW LOOP PHYSICS-LATENCY-STATS # Should show: avg=XXX, p50=YYY, p99=ZZZ ``` **Deliverable**: Comprehensive latency tracking with percentiles. --- ==== Step 3: Call Graph Discovery (6-8 hours) **Location**: New in `include/call_graph.h` and `src/call_graph.c` **Problem**: Scheduling needs to know which words call which other words to batch them efficiently. [source,c] ---- // In include/call_graph.h #define CALL_GRAPH_MAX_EDGES 1000 typedef struct { DictEntry *caller; DictEntry *callee; uint64_t call_count; uint64_t total_latency_ns; } call_edge_t; typedef struct { call_edge_t edges[CALL_GRAPH_MAX_EDGES]; int edge_count; } call_graph_t; extern call_graph_t g_call_graph; // Record a call edge void call_graph_record_edge(DictEntry *caller, DictEntry *callee) { // Find or create edge for (int i = 0; i < g_call_graph.edge_count; i++) { if (g_call_graph.edges[i].caller == caller && g_call_graph.edges[i].callee == callee) { g_call_graph.edges[i].call_count++; return; } } // New edge if (g_call_graph.edge_count < CALL_GRAPH_MAX_EDGES) { call_edge_t *e = &g_call_graph.edges[g_call_graph.edge_count++]; e->caller = caller; e->callee = callee; e->call_count = 1; } } ---- **Integration Point**: In `execute_colon_word()` when dispatching nested words: [source,c] ---- // When about to execute a word inside a colon definition call_graph_record_edge(current_colon_word, w); w->func(vm); // Execute ---- **Complexity**: Tracking which word is "current" requires refactoring execution context. Moderate complexity. **Test**: ``` : A 1 + ; : B A A ; : C B B ; 100 0 DO C LOOP PHYSICS-CALL-GRAPH # Should show edges: C→B (200), B→A (400), etc. ``` **Deliverable**: Complete call graph with edge frequencies. --- ==== Step 4: Composite Metrics Summary (2 hours) **Location**: FORTH words in `src/word_source/physics_words.c` **Change**: Add high-level diagnostic words [source,c] ---- // New word: PHYSICS-SUMMARY void forth_PHYSICS_SUMMARY(VM *vm) { printf("=== Physics Engine Summary ===\n"); // Most frequently called printf("\nTop 10 by call count:\n"); // ... iteration over words ... // Hottest by temperature printf("\nTop 10 by temperature:\n"); // ... iteration ... // Slowest by p99 latency printf("\nTop 10 by latency (p99):\n"); // ... iteration ... // Deepest call stacks printf("\nDeepest stack traces:\n"); // ... iteration ... // Most complex call graphs printf("\nMost complex (by call edges):\n"); // ... iteration ... } ---- **Deliverable**: User-friendly summary of all metrics. --- === Summary: Metrics Infrastructure **Total Effort**: 2-3 days **Deliverables**: - Stack depth tracking per word - Latency histogram with percentiles (P50, P99, P99.9) - Call graph with edge frequencies - Summary diagnostic words - 4-5 new tests - Foundation for scheduling + memory control systems **Dependencies**: Zone 1 Discovery helpful (for testing infrastructure). **Next Step After**: Ready for Option C (design questions) and implementation of Phase 2 (weak control). --- == OPTION C: Design Questions Resolution (1 day) **Goal**: Make critical architectural decisions and finalize the design before building control systems. **Scope**: Small scope but high impact. Answers questions that affect all future work. === Design Questions from PHYSICS_CONTROL_SYSTEM_DESIGN.adoc ==== Question 1: Scheduling Model **Current State**: StarForth runs on top of OS scheduler. Word execution order within colon definitions is driven by return stack (not under our control). **Decision Needed**: Should we implement a VM-level scheduler? [cols="1,2,2",options="header"] |=== |Option |Pros |Cons |A: Full VM scheduler (like Go's goroutines) |Complete control; deterministic; enable fine-grained SLO enforcement |Massive implementation; needs cooperative preemption; breaks OS integration |B: Advisory only (hints to OS) |Simple; works with any OS; immediate deployment |Limited control; latency unpredictable; can't enforce SLO |C: Hybrid (hints → batches) |Moderate complexity; decent control; works with OS |Requires learning phase to discover optimal batches; tuning work |D: Return stack reordering |Gives us word order control |Only works for colon definitions; doesn't affect nested calls; complex to prove correct |=== **Recommended**: Option C (Hybrid) - Phase 2: Advisory hints (priority, affinity) - Phase 3: Batch discovery and enforcement **Design Impact**: - Affects how we structure `sched_control_t` - Determines whether we need batch learning algorithm - Impacts Phase 2 implementation timeline --- ==== Question 2: Memory Placement Strategy **Current State**: 5 MB flat dictionary heap. No physical movement of words. **Decision Needed**: How should physics drive memory placement? [cols="1,2,2",options="header"] |=== |Option |Pros |Cons |A: Physical movement (remap pointers) |Perfect cache optimization |Extremely complex; breaks all pointers; need GC + compaction |B: NUMA-aware placement |Leverages multi-socket systems |Not all systems have NUMA; adds complexity |C: OS hints (madvise, mlock) |Simple; portable; leverages existing OS |Limited control; system-dependent behavior |D: Logical tiers (labels only) |Simple to implement; still effective |Not as good as physical movement; requires good scheduling |=== **Recommended**: Option D (Logical Tiers) - "Tier" is a metadata label, not physical location - Affects which words are batched together - Affects which words to protect from eviction - Much simpler than physical movement **Design Impact**: - Simplifies `mem_control_t` interface - Tier decisions are scheduling hints, not memory operations - Makes implementation tractable in Phase 2 --- ==== Question 3: GC vs. Spilling Strategy **Current State**: Dictionary grows until dict_end > limit. No eviction mechanism yet. **Decision Needed**: When memory pressure high, do we GC (forget) or spill (archive)? [cols="1,2,2",options="header"] |=== |Option |Pros |Cons |A: Always GC |Fast; reclaims space immediately; simple |User loses definitions; can't reload |B: Always spill |User can reload; definitions persisted |Slow reload from disk; uses block storage |C: Governance policy |Flexible; per-word control; matches governance model |Complex to implement; needs config |=== **Recommended**: Option C (Governance) - Add per-word metadata: `can_forget` and `can_spill` flags - Governance decides policy per word - System enforces it during eviction **Design Impact**: - Needs new word flags in DictEntry - Requires governance decision table - Affects FORGET and eviction logic --- ==== Question 4: L4Re Specifics **Current State**: POSIX implementation comprehensive. L4Re is stub (1 CPU hardcoded). **Decision Needed**: How does L4Re scheduling interact with our physics-driven scheduling? **Technical Questions**: - Should word priority hints map to L4Re timeslice allocation? - Should batch decisions affect IPC deadline deadlines? - Should word affinity hints affect capability delegation? **Recommended Approach**: 1. Phase 2: Implement POSIX fully (hints + batching) 2. Phase 3: Port to L4Re with same semantics 3. Phase 4+: Optimize for L4Re-specific capabilities (capability-based batching, IPC SLO tightening) **Design Impact**: - Can defer L4Re optimization to Phase 3+ - POSIX path unblocks Phase 2 immediately - L4Re team gets time to understand requirements --- ==== Question 5: Governance Integration **Current State**: Governance repo exists but not integrated with physics decisions. **Decision Needed**: Who decides SLOs, eviction policies, knob ranges? [cols="1,2,2",options="header"] |=== |Option |Pros |Cons |A: System hardcodes all policies |Fast to implement; no config overhead |Inflexible; can't customize |B: User-tunable runtime config |Flexible; per-deployment customization |Burden on operators; hard to verify |C: Governance approves ranges |Auditable; compliant; operator-friendly |Implementation effort; governance integration |=== **Recommended**: Option C (Governance) - Governance defines: SLO ranges, eviction policies, sampling rates - System reads governance at startup - Runtime adjustments stay within approved ranges **Design Impact**: - Need to load governance config at startup - Need governance file with physics policies - Audit trail for all knob changes --- ==== Question 6: Measurement Overhead **Current State**: Physics adds ~200-300ns per word execution for metadata touch. **Decision Needed**: Can we accept additional overhead from scheduling + memory decisions? **Estimated Costs**: - Scheduling hints (OS calls): +50ns per decision - Memory tier lookup: +10ns per decision - Call graph recording: +20ns per edge - Total: +80-100ns additional overhead **Budget**: Your latency targets? - Real-time system (< 1μs): Can't afford any overhead - High-performance (1-10μs): 80ns is ~1%, acceptable - Interactive (> 10μs): 80ns is < 1%, negligible **Recommended**: Measure and tune. Can use: - Sampling (only record 10% of events) - Batching (batch overhead amortization) - Conditional recording (only when interesting) **Design Impact**: - May need sampling infrastructure - Affects metrics accuracy - Trade precision for performance --- === Decision Outcomes After answering these 6 questions, we have clear direction for: 1. **Architecture**: Hybrid VM scheduler with batching 2. **Memory**: Logical tiers (advisory labels) 3. **Eviction**: Governance-driven policy with per-word flags 4. **L4Re**: Defer optimization to Phase 3 5. **Governance**: Integrate at startup 6. **Overhead**: Measure and tune Phase 2, optimize Phase 3 **Next Steps**: - Document decisions in design rationale document - Update PHYSICS_CONTROL_SYSTEM_DESIGN.adoc with answers - Begin Phase 2 implementation with clear direction --- === Summary: Design Questions Resolution **Total Effort**: 1 day (deep design review + decision documentation) **Deliverables**: - Decisions on all 6 critical questions - Design rationale document - Clear Phase 2 roadmap - Unblocks all downstream implementation **Dependencies**: None. Can be done immediately. **Next Step After**: Clear path to Phase 2 implementation using Options A + B infrastructure. --- == COMPARISON TABLE [cols="1,2,2,2,1",options="header"] |=== |Criterion |Option A (Zone 1) |Option B (Metrics) |Option C (Design) |Duration |1-2 hours |2-3 days |1 day |Effort |Small |Medium |Small-Medium |Outcome |Data flow verified |Metrics ready |Direction set |Blocker? |No |No |No |Risk |Low |Low |Low |Unblocks |B, C |Phase 2 impl |A, B impl |=== --- == RECOMMENDED APPROACH **Sequence**: A → C → B → Phase 2 Implementation 1. **Option A first (2 hours)**: Verify metrics flow works end-to-end 2. **Option C immediately (1 day)**: Answer design questions while A is fresh 3. **Option B (2-3 days)**: Implement comprehensive metrics 4. **Phase 2**: Begin weak control with clear architecture **Why this order**: - A gives quick win and confidence in infrastructure - C guides B (what metrics to prioritize) - B provides data for Phase 2 implementation - Ready to ship Phase 2 in ~1 week **Alternative**: If you want metrics first: - B → A → C → Phase 2 (same end state, longer critical path) **Or if design is urgent**: - C → A → B → Phase 2 (risk: might redesign later) --- == NEXT STEPS FOR YOU **Decision Point**: Which option first? 1. **Conservative**: A → C → B (verify, design, measure) 2. **Speed-focused**: C → A → B (design, verify, measure) 3. **Metrics-first**: B → C → A (measure, design, verify) Once you choose: 1. I'll create a detailed implementation plan for that option 2. Implementation will proceed with daily updates 3. Completion expected within 1 week for full pipeline **Recommendation**: Go with Option A → C → B (conservative path ensures no rework). --- == References - PHYSICS_IMPLEMENTATION_STATUS.adoc - What's complete - PHYSICS_CONE_OF_INFLUENCE_DESIGN.adoc - Zone architecture - PHYSICS_CONTROL_SYSTEM_DESIGN.adoc - Integration architecture