@fluffylabs/anan-as 1.2.0 → 1.3.0-39d3435

package/dist/build/js/assembly/program.js

@@ -0,0 +1,340 @@
+import { Args, Arguments, DECODERS, REQUIRED_BYTES } from "./arguments";
+import { Decoder } from "./codec";
+import { INSTRUCTIONS, MISSING_INSTRUCTION } from "./instructions";
+import { Inst } from "./instructions/utils";
+import { portable } from "./portable";
+const MAX_SKIP = 24;
+export class CodeAndMetadata {
+    constructor(code, metadata) {
+        this.code = code;
+        this.metadata = metadata;
+    }
+}
+/** https://graypaper.fluffylabs.dev/#/cc517d7/109a01109a01?v=0.6.5 */
+export function extractCodeAndMetadata(data) {
+    const decoder = new Decoder(data);
+    const metadataLength = decoder.varU32();
+    const metadata = decoder.bytes(metadataLength);
+    const code = decoder.remainingBytes();
+    return new CodeAndMetadata(code, metadata);
+}
+/** Convert `u8` to `Uint8Array` */
+export function liftBytes(data) {
+    const p = new Uint8Array(data.length);
+    p.set(data, 0);
+    return p;
+}
+/**  Convert `Uint8Array` to `Code` (StaticArray<u8>) */
+export function lowerBytes(data) {
+    const r = new StaticArray(data.length);
+    for (let i = 0; i < data.length; i++) {
+        r[i] = data[i];
+    }
+    return r;
+}
+/** https://graypaper.fluffylabs.dev/#/cc517d7/234f01234f01?v=0.6.5 */
+export function deblob(program, useBlockGas) {
+    const decoder = new Decoder(program);
+    // number of items in the jump table
+    const jumpTableLength = decoder.varU32();
+    // how many bytes are used to encode a single item of the jump table
+    const jumpTableItemLength = decoder.u8();
+    // the length of the code (in bytes).
+    const codeLength = decoder.varU32();
+    const jumpTableLengthInBytes = i32(jumpTableLength * jumpTableItemLength);
+    const rawJumpTable = decoder.bytes(jumpTableLengthInBytes);
+    // NOTE [ToDr] we copy the code here, because indexing a raw
+    // assembly script array is faster than going through `Uint8Array` API.
+    const rawCode = lowerBytes(decoder.bytes(codeLength));
+    const rawMask = decoder.bytes(i32((codeLength + 7) / 8));
+    const mask = new Mask(rawMask, codeLength);
+    const jumpTable = new JumpTable(jumpTableItemLength, rawJumpTable);
+    const basicBlocks = new BasicBlocks(rawCode, mask);
+    const gasCosts = new GasCosts(rawCode, mask, basicBlocks, useBlockGas);
+    return new Program(rawCode, mask, jumpTable, basicBlocks, gasCosts);
+}
+/**
+ * https://graypaper.fluffylabs.dev/#/cc517d7/236e01236e01?v=0.6.5
+ */
+export class Mask {
+    constructor(packedMask, codeLength) {
+        this.bytesToSkip = new StaticArray(codeLength);
+        let lastInstructionOffset = 0;
+        for (let i = packedMask.length - 1; i >= 0; i -= 1) {
+            let bits = packedMask[i];
+            const index = i * 8;
+            for (let b = 7; b >= 0; b--) {
+                const isSet = bits & 128;
+                bits = bits << 1;
+                if (index + b < codeLength) {
+                    lastInstructionOffset = isSet ? 0 : lastInstructionOffset + 1;
+                    this.bytesToSkip[index + b] = lastInstructionOffset < MAX_SKIP + 1 ? lastInstructionOffset : MAX_SKIP + 1;
+                }
+            }
+        }
+    }
+    isInstruction(index) {
+        if (index >= u32(this.bytesToSkip.length)) {
+            return false;
+        }
+        return portable.staticArrayAt(this.bytesToSkip, u32(index)) === 0;
+    }
+    /**
+     * Given we are at instruction `i`, how many bytes should be skipped to
+     * reach the next instruction (i.e. `skip(i) + 1` from the GP).
+     *
+     * NOTE: we don't guarantee that `isInstruction()` will return true
+     * for the new program counter, since `skip` function is bounded by
+     * an upper limit of `24` bytes.
+     */
+    skipBytesToNextInstruction(i) {
+        if (i + 1 < this.bytesToSkip.length) {
+            return portable.staticArrayAt(this.bytesToSkip, i + 1);
+        }
+        return 0;
+    }
+    toString() {
+        let v = "Mask[";
+        for (let i = 0; i < this.bytesToSkip.length; i += 1) {
+            v += `${this.bytesToSkip[i]}, `;
+        }
+        return `${v}]`;
+    }
+}
+export class GasCosts {
+    constructor(code, mask, blocks, useBlockGasCost) {
+        const len = code.length;
+        const costs = new StaticArray(len);
+        for (let n = 0; n < len; n += 1) {
+            const isInstructionInMask = mask.isInstruction(n);
+            if (!isInstructionInMask) {
+                costs[n] = code[n];
+                continue;
+            }
+            const skipArgs = mask.skipBytesToNextInstruction(n);
+            const iData = code[n] >= INSTRUCTIONS.length ? MISSING_INSTRUCTION : INSTRUCTIONS[code[n]];
+            costs[n] = code[n] | (iData.gas << 8);
+            n += skipArgs;
+        }
+        // sum up costs per block
+        if (useBlockGasCost) {
+            let previousStart = 0;
+            let previousSum = 0;
+            for (let n = 0; n < len; n += 1) {
+                const currentGas = costs[n] >> 8;
+                costs[n] = code[n]; // reset to just opcode (gas=0)
+                if (blocks.isStart(n)) {
+                    costs[previousStart] = code[previousStart] | (previousSum << 8);
+                    previousSum = currentGas;
+                    previousStart = n;
+                }
+                else {
+                    previousSum += currentGas;
+                }
+                n += mask.skipBytesToNextInstruction(n);
+            }
+            // final assignment
+            costs[previousStart] = code[previousStart] | (previousSum << 8);
+        }
+        this.codeAndGas = costs;
+    }
+    toString() {
+        let v = "GasCosts[";
+        for (let i = 0; i < this.codeAndGas.length; i += 1) {
+            const gas = this.codeAndGas[i] >> 8;
+            if (gas !== 0) {
+                v += `${i} -> ${gas}, `;
+            }
+        }
+        return `${v}]`;
+    }
+}
+export var BasicBlock;
+(function (BasicBlock) {
+    BasicBlock[BasicBlock["NONE"] = 0] = "NONE";
+    BasicBlock[BasicBlock["START"] = 2] = "START";
+    BasicBlock[BasicBlock["END"] = 4] = "END";
+})(BasicBlock || (BasicBlock = {}));
+/**
+ * https://graypaper.fluffylabs.dev/#/cc517d7/23fe0123fe01?v=0.6.5
+ */
+export class BasicBlocks {
+    constructor(code, mask) {
+        const len = code.length;
+        const isStartOrEnd = new StaticArray(len);
+        if (len > 0) {
+            isStartOrEnd[0] = BasicBlock.START;
+        }
+        for (let n = 0; n < len; n += 1) {
+            // we only track end-blocks for instructions.
+            const isInstructionInMask = mask.isInstruction(n);
+            if (!isInstructionInMask) {
+                continue;
+            }
+            const skipArgs = mask.skipBytesToNextInstruction(n);
+            const iData = code[n] >= INSTRUCTIONS.length ? MISSING_INSTRUCTION : INSTRUCTIONS[code[n]];
+            const isTerminating = iData.isTerminating;
+            if (isTerminating) {
+                // skip is always 0?
+                const newBlockStart = n + 1 + skipArgs;
+                // mark the beginning of the next block
+                if (newBlockStart < len) {
+                    isStartOrEnd[newBlockStart] = BasicBlock.START;
+                }
+                // and mark current instruction as terminating
+                isStartOrEnd[n] |= BasicBlock.END;
+            }
+        }
+        this.isStartOrEnd = isStartOrEnd;
+    }
+    isStart(newPc) {
+        if (newPc < this.isStartOrEnd.length) {
+            return (portable.staticArrayAt(this.isStartOrEnd, newPc) & BasicBlock.START) > 0;
+        }
+        return false;
+    }
+    toString() {
+        let v = "BasicBlocks[";
+        for (let i = 0; i < this.isStartOrEnd.length; i += 1) {
+            let t = "";
+            const isStart = (this.isStartOrEnd[i] & BasicBlock.START) > 0;
+            t += isStart ? "start" : "";
+            const isEnd = (this.isStartOrEnd[i] & BasicBlock.END) > 0;
+            t += isEnd ? "end" : "";
+            if (t.length > 0) {
+                v += `${i} -> ${t}, `;
+            }
+        }
+        return `${v}]`;
+    }
+}
+export class JumpTable {
+    constructor(itemBytes, data) {
+        const jumps = new StaticArray(itemBytes > 0 ? i32(data.length / itemBytes) : 0);
+        for (let i = 0; i < data.length; i += itemBytes) {
+            let num = u64(0);
+            for (let j = itemBytes - 1; j >= 0; j--) {
+                let nextNum = num << u64(8);
+                let isOverflow = nextNum < num;
+                nextNum = portable.u64_add(nextNum, u64(data[i + j]));
+                isOverflow = isOverflow || nextNum < num;
+                // handle overflow
+                num = isOverflow ? u64.MAX_VALUE : nextNum;
+            }
+            jumps[i32(i / itemBytes)] = num;
+        }
+        this.jumps = jumps;
+    }
+    toString() {
+        let v = "JumpTable[";
+        for (let i = 0; i < this.jumps.length; i += 1) {
+            v += `${i} -> ${this.jumps[i]}, `;
+        }
+        return `${v}]`;
+    }
+}
+export class Program {
+    constructor(code, mask, jumpTable, basicBlocks, gasCosts) {
+        this.code = code;
+        this.mask = mask;
+        this.jumpTable = jumpTable;
+        this.basicBlocks = basicBlocks;
+        this.gasCosts = gasCosts;
+    }
+    toString() {
+        return `Program { code: ${this.code}, mask: ${this.mask}, jumpTable: ${this.jumpTable}, basicBlocks: ${this.basicBlocks}, gasCosts: ${this.gasCosts} }`;
+    }
+}
+// Pre-allocated buffer for the rare case when code is shorter than needed.
+// Max REQUIRED_BYTES is 9 (OneRegOneExtImm). We allocate 16 for safety.
+const EXTENDED_BUF = new StaticArray(16);
+export function decodeArguments(args, kind, code, offset, lim) {
+    if (code.length < offset + REQUIRED_BYTES[kind]) {
+        // in case we have less data than needed we extend the data with zeros.
+        const reqBytes = unchecked(REQUIRED_BYTES[kind]);
+        for (let i = 0; i < reqBytes; i++) {
+            EXTENDED_BUF[i] = 0;
+        }
+        for (let i = offset; i < code.length; i++) {
+            EXTENDED_BUF[i - offset] = unchecked(code[i]);
+        }
+        return unchecked(DECODERS[kind])(args, EXTENDED_BUF, 0, lim);
+    }
+    return unchecked(DECODERS[kind])(args, code, offset, offset + lim);
+}
+class ResolvedArguments {
+    constructor() {
+        this.a = i64(0);
+        this.b = i64(0);
+        this.c = i64(0);
+        this.d = i64(0);
+        this.decoded = new Args();
+    }
+}
+export function resolveArguments(argsRes, kind, code, offset, lim, registers) {
+    const args = decodeArguments(argsRes, kind, code, offset, lim);
+    if (args === null) {
+        return null;
+    }
+    const resolved = new ResolvedArguments();
+    resolved.decoded = args;
+    switch (kind) {
+        case Arguments.Zero:
+            return resolved;
+        case Arguments.OneImm:
+            resolved.a = Inst.u32SignExtend(args.a);
+            return resolved;
+        case Arguments.TwoImm:
+            resolved.a = Inst.u32SignExtend(args.a);
+            resolved.b = Inst.u32SignExtend(args.b);
+            return resolved;
+        case Arguments.OneOff:
+            resolved.a = Inst.u32SignExtend(args.a);
+            return resolved;
+        case Arguments.OneRegOneImm:
+            resolved.a = registers[Inst.reg(u64(args.a))];
+            resolved.b = Inst.u32SignExtend(args.b);
+            return resolved;
+        case Arguments.OneRegOneExtImm:
+            resolved.a = registers[Inst.reg(u64(args.a))];
+            resolved.b = portable.u64_add(u64(args.a) << u64(32), u64(args.b));
+            return resolved;
+        case Arguments.OneRegTwoImm:
+            resolved.a = registers[Inst.reg(u64(args.a))];
+            resolved.b = Inst.u32SignExtend(args.b);
+            resolved.c = Inst.u32SignExtend(args.c);
+            return resolved;
+        case Arguments.OneRegOneImmOneOff:
+            resolved.a = registers[Inst.reg(u64(args.a))];
+            resolved.b = Inst.u32SignExtend(args.b);
+            resolved.c = Inst.u32SignExtend(args.c);
+            return resolved;
+        case Arguments.TwoReg:
+            resolved.a = registers[Inst.reg(u64(args.a))];
+            resolved.b = registers[Inst.reg(u64(args.b))];
+            return resolved;
+        case Arguments.TwoRegOneImm:
+            resolved.a = registers[Inst.reg(u64(args.a))];
+            resolved.b = registers[Inst.reg(u64(args.b))];
+            resolved.c = Inst.u32SignExtend(args.c);
+            return resolved;
+        case Arguments.TwoRegOneOff:
+            resolved.a = registers[Inst.reg(u64(args.a))];
+            resolved.b = registers[Inst.reg(u64(args.b))];
+            resolved.c = Inst.u32SignExtend(args.c);
+            return resolved;
+        case Arguments.TwoRegTwoImm:
+            resolved.a = registers[Inst.reg(u64(args.a))];
+            resolved.b = registers[Inst.reg(u64(args.b))];
+            resolved.c = Inst.u32SignExtend(args.c);
+            resolved.d = Inst.u32SignExtend(args.d);
+            return resolved;
+        case Arguments.ThreeReg:
+            resolved.a = registers[Inst.reg(u64(args.a))];
+            resolved.b = registers[Inst.reg(u64(args.b))];
+            resolved.c = registers[Inst.reg(u64(args.c))];
+            return resolved;
+        default:
+            throw new Error(`Unhandled arguments kind: ${kind}`);
+    }
+}

package/dist/build/js/assembly/registers.d.ts

@@ -0,0 +1,6 @@
+type Register = u64;
+export declare const NO_OF_REGISTERS = 13;
+export declare const REG_SIZE_BYTES = 8;
+export type Registers = StaticArray<Register>;
+export declare function newRegisters(): Registers;
+export {};

package/dist/build/js/assembly/registers.js

@@ -0,0 +1,9 @@
+export const NO_OF_REGISTERS = 13;
+export const REG_SIZE_BYTES = 8;
+export function newRegisters() {
+    const regs = new StaticArray(NO_OF_REGISTERS);
+    for (let i = 0; i < NO_OF_REGISTERS; i++) {
+        regs[i] = u64(0);
+    }
+    return regs;
+}

package/dist/build/js/assembly/spi.d.ts

@@ -0,0 +1,92 @@
+import { Memory } from "./memory";
+import { Program } from "./program";
+import { Registers } from "./registers";
+/** `Z_I`: https://graypaper.fluffylabs.dev/#/ab2cdbd/2daf002daf00?v=0.7.2 */
+export declare const MAX_ARGS_LEN: u32;
+/** https://graypaper.fluffylabs.dev/#/ab2cdbd/2d47022d4702?v=0.7.2 */
+export declare const ARGS_SEGMENT_START: u32;
+/** https://graypaper.fluffylabs.dev/#/ab2cdbd/2d33022d3502?v=0.7.2 */
+export declare const STACK_SEGMENT_END: u32;
+/** https://graypaper.fluffylabs.dev/#/ab2cdbd/2da3002da300?v=0.7.2 */
+export declare function decodeSpi(data: Uint8Array, args: Uint8Array, preallocateMemoryPages?: u32, useBlockGas?: boolean): StandardProgram;
+/**
+ * SPI Program with memory and registers.
+ *
+ * https://graypaper.fluffylabs.dev/#/ab2cdbd/2d13002d1400?v=0.7.2
+ */
+export declare class StandardProgram {
+    readonly program: Program;
+    readonly memory: Memory;
+    readonly registers: Registers;
+    metadata: Uint8Array;
+    constructor(program: Program, memory: Memory, registers: Registers);
+    toString(): string;
+}
+/**
+ * Standard Program Interface (SPI) Memory Layout
+ * ===============================================
+ *
+ * 32-bit address space (0x0000_0000 to 0xFFFF_FFFF)
+ *
+ * ```
+ *   Address          Region                    Access   Notes
+ *  ─────────────────────────────────────────────────────────────────
+ *  0x0000_0000  ┌─────────────────────────┐
+ *               │                         │
+ *               │   Reserved / Guard      │   None    64 KB (Z_Z)
+ *               │   (inaccessible)        │
+ *               │                         │
+ *  0x0001_0000  ├─────────────────────────┤  ◄─── SEGMENT_SIZE
+ *               │                         │
+ *               │   Read-Only Data (RO)   │   Read    Code constants,
+ *               │                         │           string literals
+ *               │                         │
+ *  0x0002_0000+ ├─────────────────────────┤  ◄─── 2*SEGMENT_SIZE + align(roLen)
+ *               │                         │
+ *               │   Read-Write Data (RW)  │   Write   Initialized globals
+ *               │                         │
+ *               ├ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┤  ◄─── heapStart + align(rwLen)
+ *               │                         │
+ *               │   Heap (Zero-init)      │   Write   Dynamic allocation
+ *               │   (heapPages * 4KB)     │           sbrk grows here
+ *               │                         │
+ *               ├─────────────────────────┤  ◄─── sbrk pointer
+ *               │                         │
+ *               │         ░░░░░░░         │
+ *               │    Unmapped / Guard     │   None    Grows towards each other
+ *               │         ░░░░░░░         │
+ *               │                         │
+ *  stackStart   ├─────────────────────────┤  ◄─── STACK_SEGMENT_END - stackLen
+ *               │                         │
+ *               │        Stack            │   Write   Grows downward (↓)
+ *               │    (stackSize aligned)  │           r1 = stack pointer
+ *               │                         │
+ *  0xFEFE_0000  ├─────────────────────────┤  ◄─── STACK_SEGMENT_END
+ *               │                         │
+ *               │   Guard (64 KB)         │   None    Separates stack/args
+ *               │                         │
+ *  0xFEFF_0000  ├─────────────────────────┤  ◄─── ARGS_SEGMENT_START
+ *               │                         │
+ *               │   Arguments (RO)        │   Read    r7 = args pointer
+ *               │   (up to 16 MB)         │           r8 = args length
+ *               │                         │
+ *               ├─────────────────────────┤  ◄─── ARGS_SEGMENT_START + argsLen
+ *               │                         │
+ *               │   Guard (64 KB)         │   None    Top guard region
+ *               │                         │
+ *  0xFFFF_FFFF  └─────────────────────────┘
+ *
+ *  Initial Register State:
+ *  ┌──────┬──────────────────┬─────────────────────────┐
+ *  │  r0  │  0xFFFF_0000     │  (reserved)             │
+ *  │  r1  │  STACK_SEG_END   │  Stack pointer (SP)     │
+ *  │  r7  │  ARGS_SEG_START  │  Arguments pointer      │
+ *  │  r8  │  args.length     │  Arguments length       │
+ *  └──────┴──────────────────┴─────────────────────────┘
+ *
+ *  Key Constants:
+ *    Z_Z (SEGMENT_SIZE) = 2^16 = 64 KB
+ *    Z_P (PAGE_SIZE)    = 2^12 =  4 KB
+ *    Z_I (MAX_ARGS_LEN) = 2^24 = 16 MB
+ * ```
+ */

package/dist/build/js/assembly/spi.js

@@ -0,0 +1,152 @@
+import { Decoder } from "./codec";
+import { MemoryBuilder } from "./memory";
+import { Access, PAGE_SIZE, PAGE_SIZE_SHIFT, SEGMENT_SIZE, SEGMENT_SIZE_SHIFT } from "./memory-page";
+import { deblob } from "./program";
+import { newRegisters } from "./registers";
+/** `Z_I`: https://graypaper.fluffylabs.dev/#/ab2cdbd/2daf002daf00?v=0.7.2 */
+export const MAX_ARGS_LEN = 2 ** 24;
+/** https://graypaper.fluffylabs.dev/#/ab2cdbd/2d47022d4702?v=0.7.2 */
+export const ARGS_SEGMENT_START = 2 ** 32 - SEGMENT_SIZE - MAX_ARGS_LEN;
+/** https://graypaper.fluffylabs.dev/#/ab2cdbd/2d33022d3502?v=0.7.2 */
+export const STACK_SEGMENT_END = ARGS_SEGMENT_START - SEGMENT_SIZE;
+/** https://graypaper.fluffylabs.dev/#/ab2cdbd/2da3002da300?v=0.7.2 */
+export function decodeSpi(data, args, preallocateMemoryPages = 0, useBlockGas = false) {
+    const argsLength = args.length;
+    if (argsLength > MAX_ARGS_LEN) {
+        throw new Error(`Arguments length is too big. Got: ${argsLength}, max: ${MAX_ARGS_LEN}`);
+    }
+    const decoder = new Decoder(data);
+    const roLength = decoder.u24();
+    const rwLength = decoder.u24();
+    const heapPages = decoder.u16();
+    const stackSize = decoder.u24();
+    const roMem = decoder.bytes(roLength);
+    const rwMem = decoder.bytes(rwLength);
+    const codeLength = decoder.u32();
+    const code = decoder.bytes(codeLength);
+    decoder.finish();
+    const program = deblob(code, useBlockGas);
+    // building memory
+    const builder = new MemoryBuilder(preallocateMemoryPages);
+    const heapStart = 2 * SEGMENT_SIZE + alignToSegmentSize(roLength);
+    const heapZerosStart = heapStart + alignToPageSize(rwLength);
+    const heapZerosLength = heapPages * PAGE_SIZE;
+    const stackLength = alignToPageSize(stackSize);
+    // stackLength is bounded to `2**24`, so there is no risk of underflow here.
+    const stackStart = STACK_SEGMENT_END - stackLength;
+    // readable memory
+    if (roLength > 0) {
+        builder.setData(Access.Read, SEGMENT_SIZE, roMem);
+    }
+    if (argsLength > 0) {
+        builder.setData(Access.Read, ARGS_SEGMENT_START, args);
+    }
+    // writable memory
+    if (rwLength > 0) {
+        builder.setData(Access.Write, heapStart, rwMem);
+    }
+    if (heapZerosLength > 0) {
+        builder.setEmpty(Access.Write, heapZerosStart, heapZerosLength);
+    }
+    if (stackLength > 0) {
+        builder.setEmpty(Access.Write, stackStart, stackLength);
+    }
+    const memory = builder.build(heapZerosStart + heapZerosLength, stackStart);
+    // build registers
+    const registers = newRegisters();
+    registers[0] = 4294901760;
+    registers[1] = STACK_SEGMENT_END;
+    registers[7] = ARGS_SEGMENT_START;
+    registers[8] = argsLength;
+    return new StandardProgram(program, memory, registers);
+}
+function alignToPageSize(size) {
+    return ((size + PAGE_SIZE - 1) >> PAGE_SIZE_SHIFT) << PAGE_SIZE_SHIFT;
+}
+function alignToSegmentSize(size) {
+    return ((size + SEGMENT_SIZE - 1) >> SEGMENT_SIZE_SHIFT) << SEGMENT_SIZE_SHIFT;
+}
+/**
+ * SPI Program with memory and registers.
+ *
+ * https://graypaper.fluffylabs.dev/#/ab2cdbd/2d13002d1400?v=0.7.2
+ */
+export class StandardProgram {
+    constructor(program, memory, registers) {
+        this.program = program;
+        this.memory = memory;
+        this.registers = registers;
+        this.metadata = new Uint8Array(0);
+    }
+    toString() {
+        return `StandardProgram { program: ${this.program}, memory_pages: ${this.memory.pages.size}, registers: ${this.registers} }`;
+    }
+}
+/**
+ * Standard Program Interface (SPI) Memory Layout
+ * ===============================================
+ *
+ * 32-bit address space (0x0000_0000 to 0xFFFF_FFFF)
+ *
+ * ```
+ *   Address          Region                    Access   Notes
+ *  ─────────────────────────────────────────────────────────────────
+ *  0x0000_0000  ┌─────────────────────────┐
+ *               │                         │
+ *               │   Reserved / Guard      │   None    64 KB (Z_Z)
+ *               │   (inaccessible)        │
+ *               │                         │
+ *  0x0001_0000  ├─────────────────────────┤  ◄─── SEGMENT_SIZE
+ *               │                         │
+ *               │   Read-Only Data (RO)   │   Read    Code constants,
+ *               │                         │           string literals
+ *               │                         │
+ *  0x0002_0000+ ├─────────────────────────┤  ◄─── 2*SEGMENT_SIZE + align(roLen)
+ *               │                         │
+ *               │   Read-Write Data (RW)  │   Write   Initialized globals
+ *               │                         │
+ *               ├ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┤  ◄─── heapStart + align(rwLen)
+ *               │                         │
+ *               │   Heap (Zero-init)      │   Write   Dynamic allocation
+ *               │   (heapPages * 4KB)     │           sbrk grows here
+ *               │                         │
+ *               ├─────────────────────────┤  ◄─── sbrk pointer
+ *               │                         │
+ *               │         ░░░░░░░         │
+ *               │    Unmapped / Guard     │   None    Grows towards each other
+ *               │         ░░░░░░░         │
+ *               │                         │
+ *  stackStart   ├─────────────────────────┤  ◄─── STACK_SEGMENT_END - stackLen
+ *               │                         │
+ *               │        Stack            │   Write   Grows downward (↓)
+ *               │    (stackSize aligned)  │           r1 = stack pointer
+ *               │                         │
+ *  0xFEFE_0000  ├─────────────────────────┤  ◄─── STACK_SEGMENT_END
+ *               │                         │
+ *               │   Guard (64 KB)         │   None    Separates stack/args
+ *               │                         │
+ *  0xFEFF_0000  ├─────────────────────────┤  ◄─── ARGS_SEGMENT_START
+ *               │                         │
+ *               │   Arguments (RO)        │   Read    r7 = args pointer
+ *               │   (up to 16 MB)         │           r8 = args length
+ *               │                         │
+ *               ├─────────────────────────┤  ◄─── ARGS_SEGMENT_START + argsLen
+ *               │                         │
+ *               │   Guard (64 KB)         │   None    Top guard region
+ *               │                         │
+ *  0xFFFF_FFFF  └─────────────────────────┘
+ *
+ *  Initial Register State:
+ *  ┌──────┬──────────────────┬─────────────────────────┐
+ *  │  r0  │  0xFFFF_0000     │  (reserved)             │
+ *  │  r1  │  STACK_SEG_END   │  Stack pointer (SP)     │
+ *  │  r7  │  ARGS_SEG_START  │  Arguments pointer      │
+ *  │  r8  │  args.length     │  Arguments length       │
+ *  └──────┴──────────────────┴─────────────────────────┘
+ *
+ *  Key Constants:
+ *    Z_Z (SEGMENT_SIZE) = 2^16 = 64 KB
+ *    Z_P (PAGE_SIZE)    = 2^12 =  4 KB
+ *    Z_I (MAX_ARGS_LEN) = 2^24 = 16 MB
+ * ```
+ */

package/dist/build/js/portable/bootstrap.d.ts

@@ -0,0 +1 @@
+declare const g: Record<string, unknown>;

package/dist/build/js/portable/bootstrap.js

@@ -0,0 +1,6 @@
+"use strict";
+// Portable bootstrap for globals that must exist before assembly/portable executes.
+const g = globalThis;
+if (g.ASC_TARGET === undefined) {
+    g.ASC_TARGET = 0;
+}

package/dist/build/js/portable/index.d.ts

@@ -0,0 +1,4 @@
+import "./bootstrap";
+import "../assembly/portable";
+import "assemblyscript/std/portable/index.js";
+export * from "../assembly/index-shared";

package/dist/build/js/portable/index.js

@@ -0,0 +1,6 @@
+// Portable JS entry point for anan-as
+// Imports portable runtime glue before the AS portable runtime.
+import "./bootstrap";
+import "../assembly/portable";
+import "assemblyscript/std/portable/index.js";
+export * from "../assembly/index-shared";