Polymorphic Substrate

Why polymorphic

Arcology OS is not organized around a conventional kernel as the permanent home of every operating-system policy. The substrate provides execution, isolation, capabilities, memory mapping, interrupt mechanisms, object dispatch, and safe attachment boundaries. Replaceable Providers supply scheduling, storage, networking, graphics, and other policy.

Different implementations of the same Contract can coexist per object. A candidate Provider can run in shadow mode, be measured against the active implementation, and pass conformance checks before gaining authority. Where safe, the system can quiesce, transfer state, verify, resume, or roll back without treating every experiment as a reboot event.

What exists now

ArcoBASIC compiles directly to freestanding UEFI x86-64 PE32+ images
The Arcology Polymorphic Substrate (APS) allocates and constructs its own page-table hierarchy
Execution crosses ExitBootServices and switches to the APS-created CR3
A virtual MMIO alias maps the GOP framebuffer after the ownership transition
Post-CR3 rendering succeeds without page faults under QEMU/OVMF
Physical Region Database policy and persistent record operations are written in ArcoBASIC
A routed timer, a substrate dispatch loop, and a typed block-storage contract, the first real Provider-shaped substrate services
A concrete Provider example, not just the concept: ArcologyFS, with its own crash-safe commit and recovery lifecycle
Generation-checked runtime handles and Resource Registry records exist in the hosted reference runtime
Visible authority metadata identifies owner, Provider, resource type, lifecycle, rights, and dependencies

Mechanism versus policy

The compiler supplies typed address operations and native instruction lowering; ArcoBASIC owns the decisions. The Physical Region Database (PRD) code below validates page alignment, overflow, and overlap before firmware descriptors can become substrate-owned region records.

ArcoBASICArcology source: physical-region invariants

' This policy runs without a hosted runtime, directly at the UEFI boundary.
#PROFILE UEFI
#TARGET X86_64
#RUNTIME NONE

' Turn a starting address and page count into an exclusive end address.
' Returning zero means the request is empty or would overflow safely.
FUNCTION RegionEnd(base AS U64, pages AS U64) AS U64
    IF pages = 0 THEN RETURN 0
    ' 4,503,599,627,370,495 is the largest page count that can be
    ' multiplied by the 4 KiB page size without overflowing U64.
    IF pages > 4503599627370495 THEN RETURN 0
    ' 4,096 bytes is the base page size defined by this x86-64 policy.
    LET bytes AS U64 = pages * 4096
    ' 18,446,744,073,709,551,615 is the largest value a U64 can hold.
    ' Subtract first so base + bytes is known to be safe before adding.
    IF base > 18446744073709551615 - bytes THEN RETURN 0
    RETURN base + bytes
END FUNCTION

' Two regions overlap unless one ends before the other begins.
FUNCTION RegionsOverlap(firstBase AS U64, firstPages AS U64, secondBase AS U64, secondPages AS U64) AS BOOL
    LET firstEnd AS U64 = RegionEnd(firstBase, firstPages)
    LET secondEnd AS U64 = RegionEnd(secondBase, secondPages)
    ' Invalid regions are never allowed to masquerade as useful input.
    IF firstEnd = 0 OR secondEnd = 0 THEN RETURN 0
    IF firstBase >= secondEnd OR secondBase >= firstEnd THEN RETURN 0
    RETURN 1
END FUNCTION

Where the addresses come from

The fixture uses several large decimal numbers, but they come from four different sources. CPU architecture defines page sizes and table geometry. UEFI reports device addresses such as the framebuffer. UEFI allocation returns the physical addresses used for new page tables. Finally, the fixture deliberately chooses temporary virtual addresses where it wants the framebuffer to appear.

No physical framebuffer address is assumed. UEFI.GOP.FrameBufferBase reports it at boot, and the code aligns that reported value down to a 2 MiB boundary before constructing mappings. Likewise, root is not a fixed address: UEFI AllocatePages selects three contiguous 4 KiB pages for the PML4, PDPT, and page directory.

The virtual alias 0x20000000 is a bootstrap design choice, not a hardware requirement. It equals page-directory entry 256 multiplied by a 2 MiB large-page span. The fixture also uses entry 64, beginning at 0x08000000, as a temporary staging slot. Neither slot should become permanent architecture. A production Arcology OS should ask the Virtual Region Database for an unused range.

The current proof maps 64 large pages, creating a conservative 128 MiB device window. Production policy should calculate the exact number of mappings from the firmware-reported framebuffer size plus any offset between the reported address and its aligned 2 MiB base. That avoids reserving a larger window than the device actually needs.

4,096 bytes: one base x86-64 page and the alignment returned by UEFI page allocation
512 entries: the number of entries in each x86-64 paging table
2,097,152 bytes: 512 base pages, forming one 2 MiB large-page mapping
134,217,728 decimal: 0x08000000, calculated as staging entry 64 × 2 MiB
536,870,912 decimal: 0x20000000, calculated as alias entry 256 × 2 MiB
134,217,728 bytes: the 128 MiB window produced by 64 × 2 MiB mappings
131 decimal: 0x83 permission bits marking an entry Present, Read/Write, and a 2 MiB Page Size; it is metadata combined with the aligned address, not part of the address itself
4,503,599,627,370,495 pages: floor(maximum U64 ÷ 4,096), used to reject multiplication overflow
18,446,744,073,709,551,615: the maximum U64 value, used to prove an addition cannot wrap around

The current authority cutover

The APS hardware fixture allocates page-table storage through firmware, builds a hierarchy, installs a device mapping for the framebuffer, exits firmware services, writes CR3, validates the active root, and renders through an APS-owned virtual alias. This is a real executable proof, not a conceptual diagram.

ArcoBASICAPS fixture excerpt: ownership transition and virtual MMIO alias

' Build the APS-owned root, PDPT, and 2 MiB page directory.
MEMORY.PhysicalWrite64(ADDRESS.Physical(root), pdpt OR 3)
MEMORY.PhysicalWrite64(ADDRESS.Physical(pdpt), pageDirectory OR 3)

' Each directory entry covers 2,097,152 bytes, or 2 MiB.
' 131 is 0x83: Present + Read/Write + 2 MiB Page Size flags.
LET directoryIndex AS U64 = 0
WHILE directoryIndex < 512
    MEMORY.PhysicalWrite64(ADDRESS.Physical(pageDirectory + (directoryIndex * 8)), (directoryIndex * 2097152) OR 131)
    directoryIndex = directoryIndex + 1
WEND

' Entry 256 begins at 256 * 2 MiB = 536,870,912 = 0x20000000.
' Map 64 entries to create a 128 MiB window over the GOP physical BAR.
LET aliasIndex AS U64 = 0
WHILE aliasIndex < 64
    MEMORY.PhysicalWrite64(ADDRESS.Physical(pageDirectory + ((256 + aliasIndex) * 8)), framebufferWindowBase + (aliasIndex * 2097152) OR 131)
    aliasIndex = aliasIndex + 1
WEND

CPU.DisableInterrupts
' Firmware services must release authority before Arcology takes control.
LET exitStatus AS U64 = AcquireMapAndExit(imageHandle, systemTable)
IF exitStatus <> 0 THEN CPU.HaltForever

' Install the page tables Arcology just built, then verify the CPU accepted them.
CPU.WriteCR3(root)
IF CPU.ReadCR3() <> root THEN CPU.HaltForever

' Draw through 536,870,912 decimal, the chosen 0x20000000 virtual alias,
' rather than using the physical address reported by firmware directly.
LET mapped AS MMIOPTR = ADDRESS.MMIO(ADDRESS.Virtual(536870912))
DrawContract(mapped, stride)
CPU.MemoryBarrier

Honest current limits

The authority Contract shown by the hardware proof is still fixture-owned data; persistent Contract resources, live capability enforcement, fault recovery, timer and interrupt ownership, full PRD population, and transactional virtual-region allocation remain active work.

The substrate is already more than a manifesto, but it is not yet a production operating system. The purpose of the proof is to establish the ownership boundary and keep every later mechanism subordinate to explicit resource and Contract rules.

Never trust a computed address you cannot source

Every large decimal number in the authority cutover above traces back to one of four places: CPU architecture, a firmware report, a firmware allocation, or a deliberate bootstrap choice. None of them is a magic number, and that discipline is what let a page-table rewrite survive a real hardware boundary crossing on the first proof rather than faulting into an unrecoverable state.

Before trusting any address, size, or offset in a low-level system, ask which of those four categories it actually comes from. A value nobody can source is a value nobody can trust, whatever layer you are working in.
Keep the riskiest transition, here the switch from firmware-owned to substrate-owned page tables, as one deliberate sequence: install the new state, then immediately verify the hardware actually accepted it before doing anything else with it. Do not assume a write succeeded; read it back.
Grant authority in stages instead of all at once. Letting a candidate implementation run in shadow mode and pass measured conformance before it gains control is the same instinct as verifying CR3 before drawing through it: prove a change is safe before depending on it.

LEARNING LAYER

Key terms, in plain language

You do not need a systems background to follow the work. These are the specialized terms used on this page.

APSArcology Polymorphic Substrate: The small privileged foundation beneath Arcology OS. It provides essential mechanisms while replaceable components provide most higher-level policy.
Physical address: A location in the machine’s actual addressable memory or device space. Firmware and hardware report physical locations; applications normally should not use them directly.
Virtual address: A location in the address space currently presented to software. Page tables decide which physical memory or device, if any, appears at that virtual location.
Address alignment: Placing an address on a boundary required by the hardware, such as a multiple of 4 KiB or 2 MiB. Aligning down removes the lower offset bits while preserving the containing region.
PML4Page Map Level 4: The top-level paging table used by the current four-level x86-64 address translation scheme. CR3 points to this table.
PDPTPage Directory Pointer Table: The paging level below the PML4. It points onward to page directories for progressively smaller portions of the virtual address space.
Page table: A data structure used by the CPU to translate the virtual addresses a program uses into physical memory locations. It also carries access rules such as writable or executable.
CR3Control Register 3: An x86-64 CPU register that points to the active top-level page table. Writing CR3 changes which virtual-memory map the processor uses.
MMIOMemory-Mapped Input/Output: A way to control a hardware device by reading and writing special address ranges as if they were memory. A framebuffer is a common example.
BARBase Address Register: PCI hardware metadata describing where a device’s memory window appears in physical address space. The graphics framebuffer is exposed through such a device window.
GOPGraphics Output Protocol: The UEFI service that exposes a basic display framebuffer before a full graphics driver exists.
Framebuffer: A region of memory whose values become pixels on a display. Writing a color value into the right location changes the corresponding pixel.
PRDPhysical Region Database: Arcology OS records every known piece of physical memory here, including who owns it, what it is for, and whether it is free or reserved. This replaces scattered allocator knowledge with one inspectable source of truth.