@jhlagado/azm 0.1.0

package/dist/src/z80/encodeLd.js

@@ -0,0 +1,273 @@
+export function encodeLdInstruction(node, env, diagnostics, ctx) {
+    const { diag, regName, immValue, indexedReg8, reg8Code, fitsImm8, fitsImm16 } = ctx;
+    const ops = node.operands;
+    if (ops.length !== 2) {
+        diag(diagnostics, node, `ld expects two operands`);
+        return undefined;
+    }
+    const dst = regName(ops[0]);
+    const src = regName(ops[1]);
+    if (dst === 'I' && src === 'A')
+        return Uint8Array.of(0xed, 0x47);
+    if (dst === 'A' && src === 'I')
+        return Uint8Array.of(0xed, 0x57);
+    if (dst === 'R' && src === 'A')
+        return Uint8Array.of(0xed, 0x4f);
+    if (dst === 'A' && src === 'R')
+        return Uint8Array.of(0xed, 0x5f);
+    const r = regName(ops[0]);
+    const n = immValue(ops[1], env);
+    if (n !== undefined && r) {
+        const indexedDst = indexedReg8(ops[0]);
+        if (indexedDst) {
+            if (!fitsImm8(n)) {
+                diag(diagnostics, node, `ld ${indexedDst.display}, n expects imm8`);
+                return undefined;
+            }
+            return Uint8Array.of(indexedDst.prefix, 0x06 + (indexedDst.code << 3), n & 0xff);
+        }
+        const r8 = reg8Code(r);
+        if (r8 !== undefined) {
+            if (!fitsImm8(n)) {
+                diag(diagnostics, node, `ld ${r}, n expects imm8`);
+                return undefined;
+            }
+            return Uint8Array.of(0x06 + (r8 << 3), n & 0xff);
+        }
+        if (r === 'BC' || r === 'DE' || r === 'HL' || r === 'SP') {
+            if (!fitsImm16(n)) {
+                diag(diagnostics, node, `ld ${r}, nn expects imm16`);
+                return undefined;
+            }
+            const op = r === 'BC' ? 0x01 : r === 'DE' ? 0x11 : r === 'HL' ? 0x21 : 0x31;
+            return Uint8Array.of(op, n & 0xff, (n >> 8) & 0xff);
+        }
+        if (r === 'IX' || r === 'IY') {
+            if (!fitsImm16(n)) {
+                diag(diagnostics, node, `ld ${r}, nn expects imm16`);
+                return undefined;
+            }
+            const prefix = r === 'IX' ? 0xdd : 0xfd;
+            return Uint8Array.of(prefix, 0x21, n & 0xff, (n >> 8) & 0xff);
+        }
+    }
+    const indexedDst = indexedReg8(ops[0]);
+    const indexedSrc = indexedReg8(ops[1]);
+    if ((indexedDst || indexedSrc) && ops[0].kind !== 'Mem' && ops[1].kind !== 'Mem') {
+        const prefix = indexedDst?.prefix ?? indexedSrc?.prefix;
+        if ((indexedDst && indexedDst.prefix !== prefix) ||
+            (indexedSrc && indexedSrc.prefix !== prefix)) {
+            diag(diagnostics, node, `ld between IX* and IY* byte registers is not supported`);
+            return undefined;
+        }
+        if ((indexedDst && !indexedSrc && ctx.isPlainHLReg8(src)) ||
+            (indexedSrc && !indexedDst && ctx.isPlainHLReg8(dst))) {
+            diag(diagnostics, node, `ld with IX*/IY* does not support plain H/L counterpart operands`);
+            return undefined;
+        }
+        const d = indexedDst ? indexedDst.code : dst ? reg8Code(dst) : undefined;
+        const s = indexedSrc ? indexedSrc.code : src ? reg8Code(src) : undefined;
+        if (prefix === undefined || d === undefined || s === undefined) {
+            diag(diagnostics, node, `ld with IX*/IY* byte registers expects reg8 operands`);
+            return undefined;
+        }
+        return Uint8Array.of(prefix, 0x40 + (d << 3) + s);
+    }
+    const srcAbs16 = ctx.memAbs16(ops[1], env);
+    if (srcAbs16 !== undefined) {
+        if (srcAbs16 < 0 || srcAbs16 > 0xffff) {
+            diag(diagnostics, node, `ld rr, (nn) expects abs16 address`);
+            return undefined;
+        }
+        if (dst === 'A')
+            return Uint8Array.of(0x3a, srcAbs16 & 0xff, (srcAbs16 >> 8) & 0xff);
+        if (dst === 'HL')
+            return Uint8Array.of(0x2a, srcAbs16 & 0xff, (srcAbs16 >> 8) & 0xff);
+        if (dst === 'BC')
+            return Uint8Array.of(0xed, 0x4b, srcAbs16 & 0xff, (srcAbs16 >> 8) & 0xff);
+        if (dst === 'DE')
+            return Uint8Array.of(0xed, 0x5b, srcAbs16 & 0xff, (srcAbs16 >> 8) & 0xff);
+        if (dst === 'SP')
+            return Uint8Array.of(0xed, 0x7b, srcAbs16 & 0xff, (srcAbs16 >> 8) & 0xff);
+        if (dst === 'IX')
+            return Uint8Array.of(0xdd, 0x2a, srcAbs16 & 0xff, (srcAbs16 >> 8) & 0xff);
+        if (dst === 'IY')
+            return Uint8Array.of(0xfd, 0x2a, srcAbs16 & 0xff, (srcAbs16 >> 8) & 0xff);
+    }
+    const dstAbs16 = ctx.memAbs16(ops[0], env);
+    if (dstAbs16 !== undefined) {
+        if (dstAbs16 < 0 || dstAbs16 > 0xffff) {
+            diag(diagnostics, node, `ld (nn), rr expects abs16 address`);
+            return undefined;
+        }
+        if (src === 'A')
+            return Uint8Array.of(0x32, dstAbs16 & 0xff, (dstAbs16 >> 8) & 0xff);
+        if (src === 'HL')
+            return Uint8Array.of(0x22, dstAbs16 & 0xff, (dstAbs16 >> 8) & 0xff);
+        if (src === 'BC')
+            return Uint8Array.of(0xed, 0x43, dstAbs16 & 0xff, (dstAbs16 >> 8) & 0xff);
+        if (src === 'DE')
+            return Uint8Array.of(0xed, 0x53, dstAbs16 & 0xff, (dstAbs16 >> 8) & 0xff);
+        if (src === 'SP')
+            return Uint8Array.of(0xed, 0x73, dstAbs16 & 0xff, (dstAbs16 >> 8) & 0xff);
+        if (src === 'IX')
+            return Uint8Array.of(0xdd, 0x22, dstAbs16 & 0xff, (dstAbs16 >> 8) & 0xff);
+        if (src === 'IY')
+            return Uint8Array.of(0xfd, 0x22, dstAbs16 & 0xff, (dstAbs16 >> 8) & 0xff);
+    }
+    if (dst && src) {
+        const d = reg8Code(dst);
+        const s = reg8Code(src);
+        if (d !== undefined && s !== undefined) {
+            return Uint8Array.of(0x40 + (d << 3) + s);
+        }
+    }
+    const indexedDstMem = indexedReg8(ops[0]);
+    if (indexedDstMem && ops[1].kind === 'Mem') {
+        const idx = ctx.memIndexed(ops[1], env);
+        if (!idx) {
+            diag(diagnostics, node, `ld ${indexedDstMem.display}, source expects (${indexedDstMem.display.startsWith('IX') ? 'ix' : 'iy'}+disp)`);
+            return undefined;
+        }
+        if (idx.prefix !== indexedDstMem.prefix) {
+            diag(diagnostics, node, `ld ${indexedDstMem.display}, source index base must match destination family`);
+            return undefined;
+        }
+        const disp = idx.disp;
+        if (disp < -128 || disp > 127) {
+            diag(diagnostics, node, `ld ${indexedDstMem.display}, (${indexedDstMem.display.startsWith('IX') ? 'ix' : 'iy'}+disp) expects disp8`);
+            return undefined;
+        }
+        return Uint8Array.of(indexedDstMem.prefix, 0x46 + (indexedDstMem.code << 3), disp & 0xff);
+    }
+    if (dst) {
+        const d = reg8Code(dst);
+        if (d !== undefined && ops[1].kind === 'Mem') {
+            const mem = ops[1];
+            if (mem.expr.kind === 'EaName' && mem.expr.name.toUpperCase() === 'HL') {
+                return Uint8Array.of(0x46 + (d << 3));
+            }
+            const idx = ctx.memIndexed(mem, env);
+            if (idx) {
+                const disp = idx.disp;
+                if (disp < -128 || disp > 127) {
+                    diag(diagnostics, node, `ld ${dst}, (ix/iy+disp) expects disp8`);
+                    return undefined;
+                }
+                return Uint8Array.of(idx.prefix, 0x46 + (d << 3), disp & 0xff);
+            }
+            if (dst.toUpperCase() === 'A' && mem.expr.kind === 'EaName') {
+                const ea = mem.expr.name.toUpperCase();
+                if (ea === 'BC')
+                    return Uint8Array.of(0x0a);
+                if (ea === 'DE')
+                    return Uint8Array.of(0x1a);
+            }
+        }
+    }
+    if (ops[0].kind === 'Mem') {
+        const mem = ops[0];
+        const indexedSrcMem = indexedReg8(ops[1]);
+        if (indexedSrcMem) {
+            const idx = ctx.memIndexed(mem, env);
+            if (!idx) {
+                diag(diagnostics, node, `ld destination expects (${indexedSrcMem.display.startsWith('IX') ? 'ix' : 'iy'}+disp) for source ${indexedSrcMem.display}`);
+                return undefined;
+            }
+            if (idx.prefix !== indexedSrcMem.prefix) {
+                diag(diagnostics, node, `ld destination index base must match source ${indexedSrcMem.display} family`);
+                return undefined;
+            }
+            const disp = idx.disp;
+            if (disp < -128 || disp > 127) {
+                diag(diagnostics, node, `ld (${indexedSrcMem.display.startsWith('IX') ? 'ix' : 'iy'}+disp), ${indexedSrcMem.display} expects disp8`);
+                return undefined;
+            }
+            return Uint8Array.of(idx.prefix, 0x70 + indexedSrcMem.code, disp & 0xff);
+        }
+        if (mem.expr.kind === 'EaName' && mem.expr.name.toUpperCase() === 'HL' && src) {
+            const s = reg8Code(src);
+            if (s !== undefined)
+                return Uint8Array.of(0x70 + s);
+        }
+        const idx = src ? ctx.memIndexed(mem, env) : undefined;
+        if (idx && src) {
+            const s = reg8Code(src);
+            if (s !== undefined) {
+                const disp = idx.disp;
+                if (disp < -128 || disp > 127) {
+                    diag(diagnostics, node, `ld (ix/iy+disp), ${src} expects disp8`);
+                    return undefined;
+                }
+                return Uint8Array.of(idx.prefix, 0x70 + s, disp & 0xff);
+            }
+        }
+        if (mem.expr.kind === 'EaName' && src?.toUpperCase() === 'A') {
+            const ea = mem.expr.name.toUpperCase();
+            if (ea === 'BC')
+                return Uint8Array.of(0x02);
+            if (ea === 'DE')
+                return Uint8Array.of(0x12);
+        }
+    }
+    if (ctx.isMemHL(ops[0]) && n !== undefined) {
+        if (!fitsImm8(n)) {
+            diag(diagnostics, node, `ld (hl), n expects imm8`);
+            return undefined;
+        }
+        return Uint8Array.of(0x36, n & 0xff);
+    }
+    if (n !== undefined) {
+        const idx = ctx.memIndexed(ops[0], env);
+        if (idx) {
+            if (!fitsImm8(n)) {
+                diag(diagnostics, node, `ld (ix/iy+disp), n expects imm8`);
+                return undefined;
+            }
+            const disp = idx.disp;
+            if (disp < -128 || disp > 127) {
+                diag(diagnostics, node, `ld (ix/iy+disp), n expects disp8`);
+                return undefined;
+            }
+            return Uint8Array.of(idx.prefix, 0x36, disp & 0xff, n & 0xff);
+        }
+    }
+    if (r === 'SP' && src) {
+        if (src === 'HL')
+            return Uint8Array.of(0xf9);
+        if (src === 'IX')
+            return Uint8Array.of(0xdd, 0xf9);
+        if (src === 'IY')
+            return Uint8Array.of(0xfd, 0xf9);
+    }
+    if (ops[0].kind === 'Mem' && ops[1].kind === 'Mem') {
+        diag(diagnostics, node, `ld does not support memory-to-memory transfers`);
+        return undefined;
+    }
+    if (dst !== undefined &&
+        dst !== 'A' &&
+        (ctx.isMemRegName(ops[1], 'BC') || ctx.isMemRegName(ops[1], 'DE'))) {
+        diag(diagnostics, node, `ld r8, (bc/de) supports destination A only`);
+        return undefined;
+    }
+    if (src !== undefined &&
+        src !== 'A' &&
+        (ctx.isMemRegName(ops[0], 'BC') || ctx.isMemRegName(ops[0], 'DE'))) {
+        diag(diagnostics, node, `ld (bc/de), r8 supports source A only`);
+        return undefined;
+    }
+    if (dst === 'AF' || src === 'AF') {
+        diag(diagnostics, node, `ld does not support AF in this form`);
+        return undefined;
+    }
+    if (ctx.isReg16TransferName(dst) && ctx.isReg16TransferName(src)) {
+        if (dst === 'SP') {
+            diag(diagnostics, node, `ld SP, rr supports HL/IX/IY only`);
+            return undefined;
+        }
+        diag(diagnostics, node, `ld rr, rr supports SP <- HL/IX/IY only`);
+        return undefined;
+    }
+    diag(diagnostics, node, `ld expects a supported register/memory/immediate transfer form`);
+    return undefined;
+}

package/dist/src/z80/encoderRegistry.d.ts

@@ -0,0 +1,13 @@
+export type EncoderFamily = 'control' | 'alu' | 'io' | 'ld' | 'core' | 'bit';
+type EncoderFallbackMode = 'none' | 'standard' | 'arity-short-circuit';
+type EncoderRegistryEntry = {
+    kind: 'zero';
+    bytes: Uint8Array;
+} | {
+    kind: 'family';
+    family: EncoderFamily;
+    fallback: EncoderFallbackMode;
+    arityDiagnostic: (head: string, operandCount: number) => string | undefined;
+};
+export declare function getEncoderRegistryEntry(head: string): EncoderRegistryEntry | undefined;
+export {};

package/dist/src/z80/encoderRegistry.js

@@ -0,0 +1,169 @@
+function expectOneOrTwoWithA(head, operandCount) {
+    if (operandCount === 1 || operandCount === 2)
+        return undefined;
+    return `${head} expects one operand, or two with destination A`;
+}
+function expectOneOrTwoWithAOrHl(head, operandCount) {
+    if (operandCount === 1 || operandCount === 2)
+        return undefined;
+    return `${head} expects one operand, two with destination A, or HL,rr form`;
+}
+function expectOne(head, operandCount) {
+    if (operandCount === 1)
+        return undefined;
+    return `${head} expects one operand`;
+}
+function expectTwo(head, operandCount) {
+    if (operandCount === 2)
+        return undefined;
+    return `${head} expects two operands`;
+}
+function expectTwoOrThreeIndexedToReg8(head, operandCount) {
+    if (operandCount === 2 || operandCount === 3)
+        return undefined;
+    return `${head} expects two operands, or three with indexed source + reg8 destination`;
+}
+function expectOneOrTwoIndexedToReg8(head, operandCount) {
+    if (operandCount === 1 || operandCount === 2)
+        return undefined;
+    return `${head} expects one operand, or two with indexed source + reg8 destination`;
+}
+function expectTwoOps(head, operandCount) {
+    if (operandCount === 2)
+        return undefined;
+    return `${head} expects two operands`;
+}
+const identityArity = (_head, _operandCount) => undefined;
+const FAMILY_SPECS = [
+    {
+        heads: ['ret', 'call', 'djnz', 'jp', 'jr'],
+        family: 'control',
+        fallback: 'none',
+        arityDiagnostic: identityArity,
+    },
+    {
+        heads: ['add', 'sub', 'cp', 'and', 'or', 'xor', 'adc', 'sbc'],
+        family: 'alu',
+        fallback: 'standard',
+        arityDiagnostic: (head, operandCount) => {
+            switch (head) {
+                case 'add':
+                    return expectTwoOps(head, operandCount);
+                case 'sub':
+                case 'cp':
+                case 'and':
+                case 'or':
+                case 'xor':
+                    return expectOneOrTwoWithA(head, operandCount);
+                case 'adc':
+                case 'sbc':
+                    return expectOneOrTwoWithAOrHl(head, operandCount);
+                default:
+                    return undefined;
+            }
+        },
+    },
+    {
+        heads: ['rst', 'im', 'in', 'out'],
+        family: 'io',
+        fallback: 'standard',
+        arityDiagnostic: identityArity,
+    },
+    {
+        heads: ['ld'],
+        family: 'ld',
+        fallback: 'none',
+        arityDiagnostic: identityArity,
+    },
+    {
+        heads: ['inc', 'dec', 'push', 'pop', 'ex'],
+        family: 'core',
+        fallback: 'standard',
+        arityDiagnostic: (head, operandCount) => {
+            if (head === 'ex')
+                return expectTwo(head, operandCount);
+            return expectOne(head, operandCount);
+        },
+    },
+    {
+        heads: ['bit', 'res', 'set', 'rl', 'rr', 'sla', 'sra', 'srl', 'sll', 'rlc', 'rrc'],
+        family: 'bit',
+        fallback: 'arity-short-circuit',
+        arityDiagnostic: (head, operandCount) => {
+            switch (head) {
+                case 'bit':
+                    return expectTwo(head, operandCount);
+                case 'res':
+                case 'set':
+                    return expectTwoOrThreeIndexedToReg8(head, operandCount);
+                case 'rl':
+                case 'rr':
+                case 'sla':
+                case 'sra':
+                case 'srl':
+                case 'sll':
+                case 'rlc':
+                case 'rrc':
+                    return expectOneOrTwoIndexedToReg8(head, operandCount);
+                default:
+                    return undefined;
+            }
+        },
+    },
+];
+const ZERO_OPCODE_REGISTRY = {
+    nop: Uint8Array.of(0x00),
+    halt: Uint8Array.of(0x76),
+    di: Uint8Array.of(0xf3),
+    ei: Uint8Array.of(0xfb),
+    scf: Uint8Array.of(0x37),
+    ccf: Uint8Array.of(0x3f),
+    cpl: Uint8Array.of(0x2f),
+    daa: Uint8Array.of(0x27),
+    rlca: Uint8Array.of(0x07),
+    rrca: Uint8Array.of(0x0f),
+    rla: Uint8Array.of(0x17),
+    rra: Uint8Array.of(0x1f),
+    exx: Uint8Array.of(0xd9),
+    reti: Uint8Array.of(0xed, 0x4d),
+    retn: Uint8Array.of(0xed, 0x45),
+    neg: Uint8Array.of(0xed, 0x44),
+    rrd: Uint8Array.of(0xed, 0x67),
+    rld: Uint8Array.of(0xed, 0x6f),
+    ldi: Uint8Array.of(0xed, 0xa0),
+    ldir: Uint8Array.of(0xed, 0xb0),
+    ldd: Uint8Array.of(0xed, 0xa8),
+    lddr: Uint8Array.of(0xed, 0xb8),
+    cpi: Uint8Array.of(0xed, 0xa1),
+    cpir: Uint8Array.of(0xed, 0xb1),
+    cpd: Uint8Array.of(0xed, 0xa9),
+    cpdr: Uint8Array.of(0xed, 0xb9),
+    ini: Uint8Array.of(0xed, 0xa2),
+    inir: Uint8Array.of(0xed, 0xb2),
+    ind: Uint8Array.of(0xed, 0xaa),
+    indr: Uint8Array.of(0xed, 0xba),
+    outi: Uint8Array.of(0xed, 0xa3),
+    otir: Uint8Array.of(0xed, 0xb3),
+    outd: Uint8Array.of(0xed, 0xab),
+    otdr: Uint8Array.of(0xed, 0xbb),
+};
+const ENCODER_REGISTRY = new Map();
+for (const [head, bytes] of Object.entries(ZERO_OPCODE_REGISTRY)) {
+    ENCODER_REGISTRY.set(head, {
+        kind: 'zero',
+        bytes,
+    });
+}
+for (const spec of FAMILY_SPECS) {
+    for (const head of spec.heads) {
+        ENCODER_REGISTRY.set(head, {
+            kind: 'family',
+            family: spec.family,
+            fallback: spec.fallback,
+            arityDiagnostic: spec.arityDiagnostic,
+        });
+    }
+}
+export function getEncoderRegistryEntry(head) {
+    return ENCODER_REGISTRY.get(head.toLowerCase());
+}

package/docs/reference/cli.md

@@ -0,0 +1,134 @@
+# AZM CLI Reference
+
+Status: active user reference
+
+The `azm` command assembles `.asm` and `.z80` source files and writes the
+requested object artifacts.
+
+```sh
+azm [options] <entry.asm|entry.z80>
+```
+
+The entry file must be the final argument. AZM source uses `.asm` or `.z80`.
+Register-care interface files use `.asmi`; they are loaded with `--interface`
+and are not compile entries.
+
+## Basic Use
+
+Build the default artifact set next to the source file:
+
+```sh
+azm program.asm
+```
+
+Write a specific primary output:
+
+```sh
+azm --type bin --output build/program.bin program.asm
+azm --type hex --output build/program.hex program.asm
+```
+
+Add include search paths:
+
+```sh
+azm -I include -I vendor program.asm
+```
+
+Load project directive aliases:
+
+```sh
+azm --aliases azm.aliases.json program.asm
+```
+
+## Output Artifacts
+
+By default AZM writes the primary output plus useful side artifacts using the
+same base path.
+
+| Artifact       | Meaning                          |
+| -------------- | -------------------------------- |
+| `.hex`         | Intel HEX output                 |
+| `.bin`         | flat binary output               |
+| `.lst`         | listing with bytes and symbols   |
+| `.d8.json`     | Debug80 map                      |
+| `.z80`         | lowered assembler source         |
+| `.regcare.txt` | register-care report             |
+| `.asmi`        | inferred register-care interface |
+
+Disable standard artifacts when they are not needed:
+
+```sh
+azm --nolist --nod8m program.asm
+azm --nobin --nohex --reg-report --rc audit program.asm
+```
+
+## Options
+
+| Option                                        | Meaning                                                              |
+| --------------------------------------------- | -------------------------------------------------------------------- |
+| `-o, --output <file>`                         | Primary output path. The extension must match `--type`.              |
+| `-t, --type <hex\|bin>`                       | Primary output type. Default: `hex`.                                 |
+| `-n, --nolist`                                | Do not write `.lst`.                                                 |
+| `--nobin`                                     | Do not write `.bin`.                                                 |
+| `--nohex`                                     | Do not write `.hex`.                                                 |
+| `--nod8m`                                     | Do not write `.d8.json`.                                             |
+| `--asm80`                                     | Write lowered assembler source as `.z80`.                            |
+| `--case-style <mode>`                         | Lint opcode/register case: `off`, `upper`, `lower`, or `consistent`. |
+| `--rc, --register-care <mode>`                | Register-care mode: `off`, `audit`, `warn`, `error`, or `strict`.    |
+| `--reg-report, --emit-register-report`        | Write `.regcare.txt`.                                                |
+| `--reg-interface, --emit-register-interface`  | Write inferred `.asmi` interface.                                    |
+| `--contracts, --annotate-register-contracts`  | Update AZMDoc contract comments in source.                           |
+| `--fix`                                       | Apply conservative register-care source fixes and update contracts.  |
+| `--accept-out <routine:carrier>`              | Promote an inferred output candidate while annotating.               |
+| `--interface <file>`                          | Load external register-care contracts from `.asmi`. Repeatable.      |
+| `--reg-profile, --register-profile <profile>` | Register-care profile. Currently `mon3`.                             |
+| `--aliases <file>`                            | Load project directive alias JSON. Repeatable.                       |
+| `-I, --include <dir>`                         | Add an include search path. Repeatable.                              |
+| `-V, --version`                               | Print package version.                                               |
+| `-h, --help`                                  | Print CLI help.                                                      |
+
+## Register-Care Examples
+
+Audit inferred contracts without failing the build:
+
+```sh
+azm --rc audit --reg-report program.asm
+```
+
+Treat contract conflicts as build failures:
+
+```sh
+azm --rc error program.asm
+```
+
+Generate compact AZMDoc blocks in source:
+
+```sh
+azm --contracts --rc audit program.asm
+```
+
+Load external contracts for monitor/library routines:
+
+```sh
+azm --rc error --interface mon3.asmi program.asm
+```
+
+## `.asmi` Interfaces
+
+External register-care interfaces are plain metadata files:
+
+```text
+extern MON_PRINT_CHAR
+in A
+clobbers A
+end
+```
+
+Use `.asmi` for these files so they are clearly distinct from assembler source.
+
+## Exit Behavior
+
+The CLI exits with a non-zero status when parsing, semantic checks, register-care
+mode, lowering, or artifact writing reports an error. Diagnostics are printed
+with file, line, column, severity, and diagnostic ID where that information is
+available.