Add kernel-Hermes message/membership structures -- FABRIC-3.6.md task 2.1, Phase 2 begins
Phase 2, task 2.1 only: type definitions, wired to nothing, drawing no
heat -- no allocator, no protocol logic, no registration anywhere.
FABRIC-3.5.md SXXII.4: Phase 2 structures come first and prove nothing
until the allocator is built on top (task 2.2 onward, each its own
commit).
Added include/starkernel/vm/kernel_hermes.h:
SkHermesMessage -- field-for-field mirror of messaging.4th's live
9-cell MSG-* layout (type/from/to/payload addr+len/Stadium cell
index/seq/channel/orig-type), per SXXXIII.4 item 1 ("roughly half the
file is accessors that become struct fields"), plus an explicit
in_use flag for task 2.2's allocator. Deliberately no separate heat
field: per SXL.4, a message's heat IS the Stadium cell it occupies,
not a value copied alongside it -- one source of truth for the
conservation invariant stadium_conserved() (task 0.7) checks.
SkHermesMembership -- one flat broadcast membership list, SXXXIII.4/
SXXXIII.5's recommended replacement for messaging.4th's 28-word channel
abstraction (traced to exactly one live caller, CH-ADD-MBR). Item 27
(negotiation vs. broadcast, Phase 3 blocker B1) is not answered by this
structure and isn't meant to be -- a flat list is correct either way.
Genuinely wired to nothing: no .c file, no Makefile change, no include
from any compiled source. Syntax-checked standalone (gcc -std=c99
-Wall -Wextra -Werror -fsyntax-only) before touching the real build.
Boot byte-identical to task 1.9's baseline on amd64 (same dict_hash
triple, zero UNKNOWN WORD). Did not repeat aarch64/riscv64 -- the file
compiles into no object on any architecture, so there is no mechanism
by which it could diverge.
Authorized by Captain Bob ("yes").
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
co-authored by
Claude Sonnet 5
Claude Sonnet 5
parent
1e75bb8039
commit
f10fa7ae83
+24
-1
@@ -481,8 +481,31 @@ Hestia; headless policy intact.
|
||||
|
||||
**Gate:** task 2.7. **If it fails, stop and re-plan. Do not proceed to Phase 3.**
|
||||
|
||||
- [ ] **2.1** — Kernel-Hermes message/membership structures, **wired to nothing, drawing no
|
||||
- [x] **2.1** — Kernel-Hermes message/membership structures, **wired to nothing, drawing no
|
||||
heat**. *Check:* boot byte-identical; `dict_hash` unmoved.
|
||||
2026-09-19 · `logs/20260919-204642/amd64/` — byte-identical to task 1.9's baseline in
|
||||
every respect: same `dict_hash` triple, zero `UNKNOWN WORD`, reaches `[zuse@Hera] ok>`.
|
||||
Did not repeat aarch64/riscv64: the new file is a header with type definitions only,
|
||||
included nowhere in the real build, so nothing compiles it into any object file on any
|
||||
architecture — there is no mechanism by which it could diverge by compiler or ISA.
|
||||
|
||||
Added `include/starkernel/vm/kernel_hermes.h`: `SkHermesMessage` (field-for-field mirror
|
||||
of `messaging.4th`'s live 9-cell `MSG-*` layout — type/from/to/payload addr+len/Stadium
|
||||
cell index/seq/channel/orig-type, plus an explicit `in_use` flag for task 2.2's allocator)
|
||||
and `SkHermesMembership` (one flat broadcast membership list — `SXXXIII.4`/`SXXXIII.5`'s
|
||||
recommended replacement for `messaging.4th`'s 28-word channel abstraction, which has
|
||||
exactly one live caller). Deliberately no separate heat field on the message struct: per
|
||||
`SXL.4`, a message's heat *is* the Stadium cell it occupies, not a value copied alongside
|
||||
it — keeping one source of truth for the conservation invariant `stadium_conserved()`
|
||||
(task 0.7) checks.
|
||||
|
||||
**Genuinely wired to nothing**: no `.c` file, no Makefile change, no include from any
|
||||
compiled source. Syntax-checked standalone (`gcc -std=c99 -Wall -Wextra -Werror
|
||||
-fsyntax-only` against a throwaway file `#include`ing it under `__STARKERNEL__`) before
|
||||
touching the real build, rather than discovering a typo only once something references it
|
||||
in a later task. Item 27 (channel negotiation vs. broadcast, Phase 3 blocker B1) is not
|
||||
answered by this structure and isn't meant to be — a flat membership list is correct either
|
||||
way; the negotiation question is about behaviour built on top, not this shape.
|
||||
- [ ] **2.2** — Allocate: pull `Q.SLOT` from the caller's reservoir; roll back on refusal.
|
||||
*Check:* N allocs against a known reservoir; refusal at the right count.
|
||||
- [ ] **2.3** — Release: return remaining heat via the eviction path. *Check:* reservoir
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
# Capsule Block Manifest — Auto-generated
|
||||
<!-- Generated by mkcapsule --manifest 2026-09-19T21:44:41Z -->
|
||||
<!-- Generated by mkcapsule --manifest 2026-09-20T00:46:42Z -->
|
||||
<!-- DO NOT EDIT — re-run mkcapsule --manifest to refresh. -->
|
||||
<!-- Hand-written justifications and immutability notes live -->
|
||||
<!-- in MANIFEST.md alongside this auto-generated index. -->
|
||||
|
||||
@@ -0,0 +1,138 @@
|
||||
/*
|
||||
StarForth — Steady-State Virtual Machine Runtime
|
||||
|
||||
Copyright (c) 2023–2025 Robert A. James
|
||||
All rights reserved.
|
||||
|
||||
This file is part of the StarForth project.
|
||||
|
||||
Licensed under the StarForth License, Version 1.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
|
||||
You may obtain a copy of the License at:
|
||||
https://github.com/star.4th@proton.me/StarForth/LICENSE.txt
|
||||
|
||||
This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
express or implied, including but not limited to the warranties of
|
||||
merchantability, fitness for a particular purpose, and noninfringement.
|
||||
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
|
||||
*/
|
||||
|
||||
/**
|
||||
* kernel_hermes.h - Kernel-resident Hermes: message and membership
|
||||
* structures (FABRIC-3.6.md task 2.1, item 28; design: FABRIC-3.5.md
|
||||
* SIII/SXXXIII/SXXXIV).
|
||||
*
|
||||
* Phase 2, task 2.1 ONLY: type definitions, wired to nothing, drawing no
|
||||
* heat. No allocator, no send/deliver/reap logic, no registration
|
||||
* anywhere -- those are tasks 2.2 onward, each its own commit. This file
|
||||
* existing and compiling changes no VM's dictionary and no runtime
|
||||
* behaviour; that is deliberate (FABRIC-3.5.md SXXII.4: Phase 2 structures
|
||||
* come first and prove nothing until the allocator is built on top, SXL.4
|
||||
* item 41).
|
||||
*
|
||||
* SkHermesMessage mirrors capsules/common/messaging.4th's live MSG-CELLS
|
||||
* layout (9 cells: MSG-TYPE@/FROM@/TO@/PADDR@/PLEN@/STADIUM-CELL@/SEQ@/
|
||||
* CH@/ORIG-TYPE@) field-for-field, per FABRIC-3.5.md SXXXIII.4 item 1 --
|
||||
* "roughly half the file is accessors that become struct fields." The
|
||||
* Stadium-cell field is the heat coupling itself: a message's heat is not
|
||||
* a field of its own, it IS the Stadium cell it occupies (SXL.4's
|
||||
* consumption model, SXXXIX.4's per-VM invariant) -- there is deliberately
|
||||
* no separate heat field here to keep that single-source-of-truth.
|
||||
*
|
||||
* SkHermesMembership is the "one broadcast membership list" SXXXIII.4
|
||||
* item 3 and SXXXIII.5 recommend in place of messaging.4th's 28-word
|
||||
* channel abstraction (CH-REQUEST/ACCEPT/CONFIRM/CLOSE/MINT-ID and the
|
||||
* CH-NEGOTIATING/OPEN/CLOSING state machine) -- traced to have exactly one
|
||||
* live caller, CH-ADD-MBR, everything else channel-shaped is unexercised.
|
||||
* Whether kernel-Hermes ever adds negotiation on top is item 27, an open
|
||||
* Phase 3 ruling (FABRIC-3.6.md B1) -- this structure does not answer
|
||||
* that question, it only holds a flat list, which is correct either way.
|
||||
*/
|
||||
|
||||
#ifndef STARKERNEL_VM_KERNEL_HERMES_H
|
||||
#define STARKERNEL_VM_KERNEL_HERMES_H
|
||||
|
||||
#ifdef __STARKERNEL__
|
||||
|
||||
#include <stddef.h>
|
||||
#include <stdint.h>
|
||||
#include "starkernel/vm_uuid.h" /* VMUuid */
|
||||
|
||||
/*
|
||||
* SK_HERMES_MSG_MAX / SK_HERMES_MEMBER_MAX - sizing only, not yet load-
|
||||
* bearing (nothing allocates against these until task 2.2). Mirrors
|
||||
* messaging.4th's own MSG-MAX (32) and MBR-MAX (64) as a starting point --
|
||||
* kernel-Hermes is a single central pool rather than N per-VM arenas, so
|
||||
* these may need revisiting once task 2.2's allocator has real traffic to
|
||||
* size against. Not a ruling, just where the FORTH precedent already was.
|
||||
*/
|
||||
#define SK_HERMES_MSG_MAX 32
|
||||
#define SK_HERMES_MEMBER_MAX 64
|
||||
|
||||
/*
|
||||
* SkHermesMessage - one message slot, field-for-field mirror of
|
||||
* messaging.4th's 9-cell MSG layout.
|
||||
*
|
||||
* @field type Message type code (SPAWN/PAUSE/RESUME/KILL-style
|
||||
* codes are Category A/dead per task 0.1/0.4; live
|
||||
* types today are CONSOLE-CMD-EVENT(7),
|
||||
* ELEVATE-REQUEST(8), BLK-ATTACH-EVENT(9), messaging.4th
|
||||
* reserved sentinels MSG-NACKED(253)/MSG-DELIVERED(255)).
|
||||
* @field from Sending VM (mirrors MSG-FROM@).
|
||||
* @field to Target VM (mirrors MSG-TO@).
|
||||
* @field payload_addr Out-of-line payload address (mirrors MSG-PADDR@).
|
||||
* FABRIC-3.5.md SXLIII.6.1 (item 44, still open): a
|
||||
* payload above INPUT_BUFFER_SIZE-1 (1024) bytes cannot
|
||||
* be drained in one interpret call -- bound or chunk it
|
||||
* before Phase 3, not here.
|
||||
* @field payload_len Payload length in bytes (mirrors MSG-PLEN@).
|
||||
* @field stadium_cell Index into the Stadium cell array this message's
|
||||
* heat currently occupies, or a sentinel meaning "none"
|
||||
* (mirrors MSG-STADIUM-CELL@) -- the heat coupling
|
||||
* itself; see this file's own top comment.
|
||||
* @field seq Monotonic send sequence (mirrors MSG-SEQ@).
|
||||
* @field channel Broadcast/channel marker; unused today (mirrors
|
||||
* MSG-CH@) -- item 27 territory, not decided here.
|
||||
* @field orig_type Original type before a NACK/redeliver rewrite
|
||||
* (mirrors MSG-ORIG-TYPE@).
|
||||
* @field in_use Free-list occupancy flag for task 2.2's allocator.
|
||||
* Not present in the FORTH layout (which uses
|
||||
* MSG-TYPE@ 0<> as its own live/free test) -- kept
|
||||
* explicit here rather than overloading `type == 0`,
|
||||
* since kernel-Hermes's held/pulled/returned/consumed
|
||||
* ledger (task 2.4, SXL.4) needs an unambiguous
|
||||
* occupancy bit independent of the type field's value.
|
||||
*/
|
||||
typedef struct {
|
||||
uint32_t type;
|
||||
VMUuid from;
|
||||
VMUuid to;
|
||||
void *payload_addr;
|
||||
uint32_t payload_len;
|
||||
int32_t stadium_cell;
|
||||
uint32_t seq;
|
||||
uint32_t channel;
|
||||
uint32_t orig_type;
|
||||
int in_use;
|
||||
} SkHermesMessage;
|
||||
|
||||
/*
|
||||
* SkHermesMembership - one flat broadcast membership list: every VM that
|
||||
* has joined, no per-member state beyond identity. Replaces the 28-word
|
||||
* channel abstraction; see this file's own top comment for why.
|
||||
*
|
||||
* @field members Member VM identities, valid for indices < count.
|
||||
* @field count Number of valid entries in members[].
|
||||
*/
|
||||
typedef struct {
|
||||
VMUuid members[SK_HERMES_MEMBER_MAX];
|
||||
size_t count;
|
||||
} SkHermesMembership;
|
||||
|
||||
#endif /* __STARKERNEL__ */
|
||||
|
||||
#endif /* STARKERNEL_VM_KERNEL_HERMES_H */
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user