# 📜 BROADSWORD MASTER SPEC

Kernel: Paladin | Hardware: (ESP32-C3)
Architecture: 128-bit Slab Linear Logic | Standard: Cassette-Futurism 1991 What-If

1. The Atomic Unit (The Slab)

The primary qualification for a machine's "bit-ness" is the size of the data it moves 
in a single logical cycle.

In Paladin, the Slab is a fixed 128-bit union.
To the programmer (and the Broadsword Verbs), there are no "small" registers.
Global memory map, reserved system space; Slabs of 128 bits each.

---

### ### I. THE VISUAL GRAMMAR OF BROADSOWRD (SYMBOLS)

BROADWORD is the programming language of the Paladin sysetm.
It is a Domain and System specific language.

Strictly defined to maintain a "scannable" texture and avoid collisions.

* ### (The Bulkhead): Used only for Global Divisions. Creates a horizontal wall separating 
data from logic. 

* # (The Literal): Strictly reserved for Numbers. Represents a hard value, never a name. 

* -- (The Whisper): Strictly for Human Comments. The machine ignores everything after this on a line.

* [] (The Container): Identifies a Slab or a Step name; a label for a place in memory.

---

### ### II. THE PHYSICAL STRUCTURE (DIVISIONS)

The code is a vertical scroll. No nesting. No brackets. Logic moves only Down.

1. DATA DIVISION: All variables, data sets, and program use words go here only. 
	No inline variables allowed.
2. PROCEDURE DIVISION: The assembly line utilizing Broadsword Verbs.
3. THE STEP UNIT: Logic is divided into named STEP blocks. Logic inside is indented by 
	5 spaces and must end with DONE.
4. END OF LINE: The final bulkhead that signals the machine to stop; absolute authority.

---

SIGILS
    ###    bulkhead — global division marker
    #      literal number — never a name
    --     comment — machine ignores to end of line
    []     container — a variable, a slab, a step label
    "  "   text literal — SAY only

DATA DIVISION DECLARATIONS
    [NAME]   NUMBER                    -- integer
    [NAME]   NUMBER  96.32             -- scaled fixed point
    [NAME]   NUMBER  RANGE #0 TO #359  -- integer with bounds
    [NAME]   TEXT    #20               -- fixed 20-char buffer
    [NAME]   FLAG                      -- ON or OFF
    [NAME]   FIXED   #13               -- constant, refuses WRITE
    [NAME]   NUMBER  ARRAY #64         -- indexed array

VERBS
 -- Data movement
COPY   [SRC] TO [DEST]
MOVE   [SRC] TO [DEST]             -- wipes source
SWAP   [A] AND [B]
FILL   [ARRAY] WITH [VAL or #]     -- initialize all elements

-- Arithmetic
SUM    [A] AND [B] TO [DEST]
DIFF   [A] AND [B] TO [DEST]
TIMES  [A] BY [B] TO [DEST]
DIVIDE [A] BY [B] TO [DEST]
REST   [A] BY [B] TO [DEST]        -- modulo

-- Bitwise
BITS   AND [A] WITH [B] TO [DEST]
BITS   OR  [A] WITH [B] TO [DEST]
BITS   XOR [A] WITH [B] TO [DEST]
BITS   NOT [A] TO [DEST]

-- Hardware
APPLY  [MODE] TO [PIN]
WRITE  [VAL] TO [DEST]
READ   [SRC] TO [DEST]

-- Flow
SEEK   [STEP]
CALL   [STEP]
RETURN
WHEN   [A] EQUALS [B] [ACTION]     -- binary
WHEN   [A] OVER   [B] [ACTION]     -- binary
WHEN   [A] UNDER  [B] [ACTION]     -- binary
WHEN   [A] ZERO       [ACTION]     -- unary
WHEN   [A] BLANK      [ACTION]     -- unary
WAIT   #ms or [SLAB]

-- Human
SAY    [SLAB] or "literal"
HEAR   [DEST]
STOP   "reason"

PROGRAM STRUCTURE
    ### DATA DIVISION
    ### PROCEDURE DIVISION
    ### END OF LINE

### ### V. THE HARDWARE REALITY

The Paladin Kernel manages physical 128-bit Slabs with global memory map.

| SLAB RANGE | DIVISION | ACCESS | PURPOSE |
|:-----------|:---------|:-------|:--------|



### ### VI. PERFORMANCE METRIC: THE MEGA-PALADIN (MPS)

Throughput of "Solid Logic" at the human-scale architecture of the Oasis.

One Paladin (1 P): Successful completion of a single 128-bit Slab Operation (Fetch -> Verb -> Commit)
One Mega-Paladin (1 MP): 1,000,000 completed Slab operations.
\*Benchmark: 1.0 MPS is roughly equivalent to a 5-10 MIPS 1985 workstation (e.g., VAX-11/780).

### ### VII. RECORDS (Human Readable File analog)

Records are the physical human interaction layer.
A record has no maximum length, except for the total number of slabs.
A journaling filesystem, record keeping on a specifi memory range at the beginning or/end of
any drive.

Each journal entry takes 2 slabs, and is unique.

SLAB A: The Identity (12-Character Name)

| Bits   | Field       | Description                           |
|:-------|:------------|:--------------------------------------|
| 0-95   | NAME        | 12 Bytes ASCII (e.g., "RX-78_SCHEM"). |
| 96-127 | SYSTEM INFO | A simple CRC,                         |

SLAB B: The Physical Mapping

| Bits   | Field       | Description                                                   |
|:-------|:------------|:--------------------------------------------------------------|
| 0-31   | UID         | Unique 4-byte hash (for fast LOAD "NAME").                    |
| 32-55  | FLASH_START | The Global Slab Index in the 4MB Flash (up to 262,144).       |
| 56-79  | SLAB_COUNT  | How many total Slabs this record occupies (up to 16 million). |
| 80-95  | TYPE        | selectable: IMG4, CODE, TEXT, SORC.                           |
| 96-127 | METADATA    | Flags: Read-Only, System, Encrypted, etc.                     |

The Exhaustive Registry: The "Paladin Sixty-Four"

Here is the industrial registry of Record Types.
0x00 - 0x0F: System & Logic (The Core)
Hex ID	Extension	Name	Description
0x00	.EMP	Empty	A Null/Wiped Journal Slab.
0x01	.BS 	Broadsword	Executable/Source Logic for the Paladin Kernel.
0x02	.SYS	System	Kernel-level data, drivers, or microcode.
0x03	.CFG	Config	System parameters, hardware maps, calibration.
0x04	.FNT	Font	256-slab Extended ANSI bitmap glyph sets.
0x10 - 0x1F: Text & Data (The Records)
Hex ID	Extension	Name	Description
0x10	.TXT	Text	Plaintext  for the Journal Editor.
0x11	.LOG	Ledger	Audit trails, system logs, or transaction records.
0x12	.DAT	Data	Raw 128-bit Broadword data structures.
0x13	.BIN	Binary	Raw machine code or unformatted memory dumps.
0x20 - 0x2F: Audio & Visual (The Media)
Hex ID	Extension	Name	Description
0x20	.IMG	Image	Raw 1-bit or 4-bit bitmap frame buffers.
0x21	.SND	Sound	PCM Audio samples for Lane-based streaming.
0x22	.PAL	Palette	Color lookup tables (128-bit color records).
0x23	.JXL	JXL-Lite	Future-proofing for dense image compression.
0x30 - 0x3F: Communication & Removable (The Ports)
Hex ID	Extension	Name	Description
0x30	.TAP	Tape	Serial stream snapshots (The RX-03 "Tape" drive).
0x31	.RO    	Remote	Records retrieved from external terminals.

### BROADSWORD LANGUAGE
# BROADSWORD OPCODE TABLE

Instruction format: `[1 byte opcode][2 byte operand]` = 3 bytes per instruction

Chamber = Slab 0 (accumulator, always known, always fixed)

---

## 0x00 — Control

| Hex  | Name | Action |
|:-----|:-----|:-------|
| 0x00 | NOP  | Idle   |
| 0x01–0x0F | — | Reserved |

---

## 0x10 — Memory

| Hex  | Name     | Action |
|:-----|:---------|:-------|
| 0x10 | LOAD     | Slab[arg] → Chamber |
| 0x11 | SAVE     | Chamber → Slab[arg] |
| 0x12 | COPY     | Slab[arg] → Slab[arg+1] |
| 0x13 | XCHANGE  | Swap Slab[arg] with Chamber |
| 0x14 | FILL     | Fill array slabs with value |
| 0x15–0x1F | — | Reserved |

---

## 0x20 — Integer Math

| Hex  | Name | Action |
|:-----|:-----|:-------|
| 0x20 | ADD  | Chamber + Slab[arg] → Chamber |
| 0x21 | SUB  | Chamber - Slab[arg] → Chamber |
| 0x22 | MUL  | Chamber × Slab[arg] → Chamber |
| 0x23 | DIV  | Chamber ÷ Slab[arg] → Chamber |
| 0x24 | MOD  | Chamber mod Slab[arg] → Chamber |
| 0x25 | INC  | Chamber + 1 → Chamber |
| 0x26 | DEC  | Chamber - 1 → Chamber |
| 0x27–0x2F | — | Reserved |

---

## 0x30 — Q-Format Math
> Compiler selects automatically based on variable declaration. Programmer never writes these directly.

| Hex  | Name | Action |
|:-----|:-----|:-------|
| 0x30 | QADD | 128-bit Q-format add |
| 0x31 | QSUB | 128-bit Q-format subtract |
| 0x32 | QMUL | 128-bit Q-format multiply |
| 0x33 | QDIV | 128-bit Q-format divide |
| 0x34–0x3F | — | Reserved |

---

## 0x40 — Bitwise

| Hex  | Name   | Action |
|:-----|:-------|:-------|
| 0x40 | AND    | Chamber & Slab[arg] → Chamber |
| 0x41 | OR     | Chamber \| Slab[arg] → Chamber |
| 0x42 | XOR    | Chamber ^ Slab[arg] → Chamber |
| 0x43 | NOT    | ~Chamber → Chamber |
| 0x44 | LSHIFT | Chamber << arg → Chamber |
| 0x45 | RSHIFT | Chamber >> arg → Chamber |
| 0x46–0x4F | — | Reserved |

---

## 0x50 — Flow
> Internal opcodes. Compiler emits these. Programmer writes WHEN, SEEK, CALL, RETURN.

| Hex  | Name   | Action |
|:-----|:-------|:-------|
| 0x50 | JUMP   | IP = arg |
| 0x51 | JUMPZ  | If zero flag: IP = arg |
| 0x52 | JUMPNZ | If not zero flag: IP = arg |
| 0x53 | CMPLT  | Chamber < Slab[arg] → zero flag |
| 0x54 | CMPGT  | Chamber > Slab[arg] → zero flag |
| 0x55 | CMPEQ  | Chamber == Slab[arg] → zero flag |
| 0x56 | CALL   | Push IP, jump to arg |
| 0x57 | RETURN | Pop IP |
| 0x58–0x5F | — | Reserved |

---

## 0x60 — Text

| Hex  | Name   | Action |
|:-----|:-------|:-------|
| 0x60 | TLEN   | Length of TEXT variable → Chamber |
| 0x61 | TJOIN  | Concatenate two TEXT variables |
| 0x62 | TFIND  | Search TEXT for pattern |
| 0x63 | TSPLIT | Split TEXT at position |
| 0x64 | TCOMP  | Compare two TEXT variables |
| 0x65–0x6F | — | Reserved |

---

## 0x70 — Hardware / System

| Hex  | Name      | Action |
|:-----|:----------|:-------|
| 0x70 | SAY       | Print TEXT slab to terminal |
| 0x71 | HEAR      | Read line from terminal → slab |
| 0x72 | SENSE     | Read GPIO pins → Chamber |
| 0x73 | TOGGLE    | Write Chamber → GPIO pins |
| 0x74 | SIGNAL    | Timed pulse on GPIO pin |
| 0x75 | TIMESTAMP | Read RTC/system time → slab |
| 0x76 | WAIT      | Wait arg milliseconds |
| 0x77 | RND       | Random number → Chamber |
| 0x78 | ON        | Register STEP as interrupt handler for pin |
| 0x79 | EVERY     | Call STEP on repeating timer interval |
| 0x7A–0x7F | — | Reserved |

---

## 0x80 — Display

| Hex  | Name   | Action |
|:-----|:-------|:-------|
| 0x80 | GLYPH  | Draw character at position |
| 0x81 | SCROLL | Scroll display buffer |
| 0x82 | ERASE  | Clear display or region |
| 0x83 | PIXEL  | Draw pixel at coordinates |
| 0x84–0x8F | — | Reserved |

---

## 0x90 — Filesystem

| Hex  | Name       | Action |
|:-----|:-----------|:-------|
| 0x90 | FILE OPEN  | Open file → handle |
| 0x91 | FILE READ  | Read from handle → slab |
| 0x92 | FILE WRITE | Write slab → handle |
| 0x93 | FILE CLOSE | Close handle |
| 0x94 | FILE FIND  | Find file by name → handle |
| 0x95 | FILE DEL   | Delete file by name |
| 0x96 | FILE EXISTS| Check file exists → Chamber |
| 0x97 | FILE SIZE  | File size in slabs → Chamber |
| 0x98 | FILE SEEK  | Move read position within file |
| 0x99 | DIR LIST   | List directory → TEXT array |
| 0x9A | DIR MAKE   | Create directory |
| 0x9B | DIR DEL    | Delete directory |
| 0x9C–0x9F | — | Reserved |

---

## 0xA0 — Network

| Hex  | Name      | Action |
|:-----|:----------|:-------|
| 0xA0 | NET LISTEN| Bind and listen on port |
| 0xA1 | NET ACCEPT| Accept connection → handle |
| 0xA2 | NET SEND  | Send slab to connection |
| 0xA3 | NET RECV  | Receive from connection → slab |
| 0xA4 | NET CLOSE | Close connection |
| 0xA5 | NET CONN  | Open outbound connection |
| 0xA6 | NET POLL  | Check for waiting connection, non-blocking → Chamber |
| 0xA7 | NET QUEUE | Accept up to arg connections into queue |
| 0xA8–0xAF | — | Reserved |

---

## 0xB0–0xEF — Reserved for Future Use

| Range     | Purpose |
|:----------|:--------|
| 0xB0–0xBF | Concurrency / tasks (future) |
| 0xC0–0xCF | Reserved |
| 0xD0–0xDF | Reserved |
| 0xE0–0xEF | Reserved |

---

## 0xFF — Control

| Hex  | Name | Action |
|:-----|:-----|:-------|
| 0xFF | HALT | Stop execution immediately |

---

## Notes

- Instruction width: 3 bytes fixed (`[opcode][operand_lo][operand_hi]`)
- Chamber: Slab 0, always. The accumulator. Not addressable by programmer directly.
- Q-format opcodes (0x30–0x33): selected by compiler based on variable declaration, 
	never written by programmer
- Flow opcodes (0x50–0x57): emitted by compiler from WHEN/SEEK/CALL/RETURN verbs, 
	never written by programmer
- Concurrency (0xB0–0xBF): space reserved, not yet defined

Mode 0x00 (Direct): val is the Slab address (e.g., LOAD 100 pulls Slab 100).

Mode 0x01 (Immediate): val is a literal number (e.g., ADD #500 adds the number 500 to the Chamber).

Mode 0x02 (Indirect): Look at Slab\[val\], find the number inside it, 
and use that as the address. (This is how we handle arrays and pointers).