docs: reorganise -- current reference gathered, finished work archived, superseded and dead ideas marked as such
docs/CLAUDE.md Phase 2, 2026-10-14. All moves by git mv; every archived file carries a header saying what it is, why, and where to look instead. - docs/reference/ (new): roadmap and versioning policy, M7.1, word-ACL design, kernel args, hosted acceptance test, dictionary, primitives, ontology, L8 table -- previously spread over docs/, docs/lithosananke/ and docs/03-architecture/. - docs/working/archive/historical/: finished work (session plan, test-gap audit, birthing plan, fix write-ups, the January architecture draft). - docs/working/archive/superseded/: the Hermes-VM Tripod docs and July Hermes designs (-> FABRIC-3.5/3.6), the StarForth roadmap, every working doc already flagged superseded or obsolete. - docs/working/archive/dead/: the hal_* target contract (never adopted), L4Re, metrics-and-knobs. - Papers and proposals into docs/working/papers/. - References rewritten across the repo (not logs/, not docs/patent/); CLAUDE.md's documentation section rewritten. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rajames
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
1a4b163861
commit
7aed588f78
@@ -0,0 +1,190 @@
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** The Tripod as Hera/Hermes/Artemis; the Hermes VM was removed (messaging moved into the kernel as kernel-Hermes) and the Tripod is Hera/Artemis/Hestia.
|
||||
> Instead: docs/fabric/FABRIC-3.5.md and FABRIC-3.6.md. Moved here from `docs/03-architecture/tripod/ARTEMIS.md`.
|
||||
|
||||
# ARTEMIS.md — Artemis VM Architecture
|
||||
# StarshipOS / StarForth — Captain Bob (Robert Allan James)
|
||||
# This document constrains Claude Code behavior. Read it completely before touching Artemis.
|
||||
|
||||
---
|
||||
|
||||
## Language Constraint — Non-Negotiable
|
||||
|
||||
All Artemis implementation is in StarForth dialect ONLY.
|
||||
|
||||
This includes:
|
||||
- Data structures
|
||||
- Constants
|
||||
- Variables
|
||||
- Control flow
|
||||
- Everything
|
||||
|
||||
C99 is forbidden unless explicitly blocked in StarForth AND explicit written permission
|
||||
is given by Captain Bob for that specific construct. "I could not figure out how to do
|
||||
this in StarForth" is not permission. Ask first. Wait for the answer.
|
||||
|
||||
If you are about to write a C struct, a #define, or a C variable — stop.
|
||||
Implement it in StarForth or ask.
|
||||
|
||||
---
|
||||
|
||||
## When Stuck — Non-Negotiable
|
||||
|
||||
If you are stuck, STOP.
|
||||
|
||||
Do not confabulate.
|
||||
Do not invent dictionary words that do not exist.
|
||||
Do not fabricate primitives.
|
||||
Do not guess at behavior.
|
||||
Do not work around the problem silently.
|
||||
|
||||
STOP. Report exactly what is blocking you. Wait for instruction.
|
||||
|
||||
Silent confabulation has caused git resets on a project with a hard patent deadline.
|
||||
It is not acceptable under any circumstances.
|
||||
|
||||
---
|
||||
|
||||
## What Artemis Is
|
||||
|
||||
Artemis is memory. She owns the external attached virtual disk image and everything
|
||||
that lives on it. She manages block storage compudynamically.
|
||||
|
||||
Artemis does **not** move messages — that is Hermes.
|
||||
Artemis does **not** make VM lifecycle decisions — that is Hera.
|
||||
Artemis does **not** own the internal ramdisk — that is kernel territory.
|
||||
|
||||
---
|
||||
|
||||
## Storage Topology
|
||||
|
||||
### Internal Ramdisk — Not Artemis Scope
|
||||
- Baked into each VM at build time by mkcapsule.c
|
||||
- LBN 0–3071
|
||||
- Kernel territory
|
||||
- Every VM carries its own ramdisk
|
||||
- Artemis does not touch it, manage it, or know about it
|
||||
|
||||
### External Attached Virtual Disk Image — Artemis Territory
|
||||
- Mounted virtual disk image, attached to the QEMU instance
|
||||
- Artemis owns this exclusively
|
||||
- LBN boundaries to be determined as Artemis is built
|
||||
- Nothing persists between runs yet — that is a future chapter
|
||||
|
||||
### Nothing Persists Between Runs Yet
|
||||
Persistence across runs is a future chapter. Do not implement it yet.
|
||||
Do not design around it. The current model is: VM starts, Artemis initializes
|
||||
her free map, VM stops, everything is gone. That is correct for now.
|
||||
|
||||
---
|
||||
|
||||
## What Artemis Owns
|
||||
|
||||
- The free map over her LBN range on the external disk image
|
||||
- Block fetch and persist operations on the external disk image
|
||||
- ACL lists — structured as Artemis-managed blocks (see ACL section)
|
||||
- Cold capsule store — evicted from Hermes cache (future chapter)
|
||||
- Block metadata
|
||||
|
||||
---
|
||||
|
||||
## Compudynamic Block Lifecycle
|
||||
|
||||
Artemis manages blocks compudynamically. Same model as everything else in StarshipOS:
|
||||
|
||||
- Block enters active use — born hot
|
||||
- Cools over time with each heartbeat tick
|
||||
- Frequently accessed blocks stay warm (heat refreshed on access)
|
||||
- Cold blocks are candidates for eviction or reuse
|
||||
- Block reap must rebalance K correctly
|
||||
|
||||
Artemis is the hardest VM to design because she has three interleaved
|
||||
compudynamic concerns:
|
||||
1. The free map — which LBNs are available
|
||||
2. Block thermal state — how hot is each active block
|
||||
3. K≡1.0 — fleet conservation across all block operations
|
||||
|
||||
These must be designed together. Do not implement one without the others.
|
||||
Do not begin implementation without explicit instruction from Captain Bob.
|
||||
|
||||
---
|
||||
|
||||
## ACL — Access Control Lists
|
||||
|
||||
### Current State
|
||||
ACL is a toggle. It is currently OFF.
|
||||
|
||||
A `\` comment disables ACL enforcement. When commented out, zuse is the
|
||||
implicit and only user. No enforcement occurs.
|
||||
|
||||
```forth
|
||||
\ ACL-ENFORCE ( disabled — zuse only )
|
||||
```
|
||||
|
||||
### Structure
|
||||
ACL lists must be structured as Artemis-managed blocks from day one.
|
||||
Even before Artemis is fully built, ACL data structures must assume
|
||||
they will live in Artemis-managed storage. No shortcuts that require
|
||||
redesign later.
|
||||
|
||||
### When ACL Turns On
|
||||
ACL enforcement becomes mandatory when VMs outside the Tripod arrive.
|
||||
Until then the toggle stays off.
|
||||
|
||||
When enforcement is enabled:
|
||||
- Every VM has an identity
|
||||
- Every operation is checked against the ACL
|
||||
- Artemis is the authority — she holds the lists
|
||||
|
||||
### Security Model
|
||||
Security grows with the threat surface. Not before it.
|
||||
The architecture is always structurally correct — enforcement is simply
|
||||
not active yet. No retrofit needed when the time comes.
|
||||
|
||||
Toggling ACL on must require zero structural changes to the codebase.
|
||||
Only the `\` comment is removed. If toggling ACL requires anything else,
|
||||
the implementation is wrong.
|
||||
|
||||
---
|
||||
|
||||
## What Is Not Artemis
|
||||
|
||||
- **Internal ramdisk** — kernel territory, not Artemis scope
|
||||
- **Message routing** — that is Hermes
|
||||
- **VM lifecycle** — that is Hera
|
||||
- **Persistence across runs** — future chapter, not now
|
||||
- **Cold capsule eviction from Hermes** — future chapter, not now
|
||||
|
||||
---
|
||||
|
||||
## Compudynamic Invariant
|
||||
|
||||
Every block Artemis manages participates in K≡1.0.
|
||||
Block fetch, persist, and reap operations must rebalance K correctly.
|
||||
Artemis's thermal contribution to the fleet is the sum of her active block heat.
|
||||
|
||||
Do not write code that breaks K≡1.0 and add a comment explaining why it's okay.
|
||||
|
||||
---
|
||||
|
||||
## Current Scope
|
||||
|
||||
Artemis is not yet started. Before any implementation begins:
|
||||
|
||||
1. Captain Bob must give explicit instruction to begin
|
||||
2. The three compudynamic concerns (free map, block thermal state, K≡1.0)
|
||||
must be designed together before any code is written
|
||||
3. ACL data structures must be Artemis-block-shaped from first line of code
|
||||
4. Storage boundaries (LBN ranges on external disk image) must be confirmed
|
||||
|
||||
**Do not begin implementation without explicit instruction.**
|
||||
|
||||
Future chapters (do not implement):
|
||||
- Persistence across runs
|
||||
- Cold capsule store from Hermes
|
||||
- Full ACL enforcement
|
||||
- LBN range expansion
|
||||
|
||||
---
|
||||
|
||||
*This document is authoritative. If it conflicts with something in the codebase,
|
||||
the codebase is wrong.*
|
||||
Reference in New Issue
Block a user