@jhlagado/azm 0.1.0

package/dist/src/lowering/emitFinalizationSetup.js

@@ -0,0 +1,26 @@
+import { alignTo, computeWrittenRange, rebaseCodeSourceSegments, writeBytePlacement, } from './bytePlacement.js';
+import { evalImmExpr } from '../semantics/env.js';
+import { diag, diagAt } from './loweringDiagnostics.js';
+export function buildEmitFinalizationPhaseEnv(ctx) {
+    return {
+        diagnostics: ctx.diagnostics,
+        diag,
+        diagAt,
+        primaryFile: ctx.workspace.config.primaryFile,
+        baseExprs: ctx.workspace.placement.baseExprs,
+        evalImmExpr,
+        env: ctx.env,
+        loweredAsmStream: ctx.helpers.loweredAsmStream,
+        fixups: ctx.workspace.symbols.fixups,
+        rel8Fixups: ctx.workspace.symbols.rel8Fixups,
+        bytes: ctx.workspace.emission.bytes,
+        codeSourceSegments: ctx.workspace.emission.codeSourceSegments,
+        alignTo,
+        writeBytePlacement,
+        computeWrittenRange,
+        rebaseCodeSourceSegments,
+        ...(ctx.options?.defaultCodeBase !== undefined
+            ? { defaultCodeBase: ctx.options.defaultCodeBase }
+            : {}),
+    };
+}

package/dist/src/lowering/emitPhase1BuildProgramLoweringContext.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Assembles {@link createEmitProgramContext} bundles from phase-1 wiring output.
+ */
+import { createEmitProgramContext } from './emitProgramContext.js';
+import type { EmitPhase1HelpersContext } from './emitPhase1Types.js';
+import type { EmitPhase1WireResult } from './emitPhase1WirePipeline.js';
+export declare function buildEmitProgramLoweringContext(ctx: EmitPhase1HelpersContext, wire: EmitPhase1WireResult): ReturnType<typeof createEmitProgramContext>['programLoweringContext'];

package/dist/src/lowering/emitPhase1BuildProgramLoweringContext.js

@@ -0,0 +1,119 @@
+/**
+ * Assembles {@link createEmitProgramContext} bundles from phase-1 wiring output.
+ */
+import { evalImmExpr } from '../semantics/env.js';
+import { sizeOfTypeExpr } from '../semantics/layout.js';
+import { cloneEaExpr, cloneImmExpr, cloneOperand, flattenEaDottedName } from './asmUtils.js';
+import { loadBinInput } from './inputAssets.js';
+import { diag, diagAt, diagAtWithId, diagAtWithSeverityAndId, warnAt, } from './loweringDiagnostics.js';
+import { createEmitProgramContext } from './emitProgramContext.js';
+import { alignTo } from './bytePlacement.js';
+export function buildEmitProgramLoweringContext(ctx, wire) {
+    const { spTrackingSlot, getCurrentCodeOffset, traceComment, traceLabel, currentCodeSegmentTagRef, generatedLabelCounterRef, emitInstr, emitRawCodeBytes, emitAbs16Fixup, emitAbs16FixupPrefixed, emitRel8Fixup, callConditionOpcodeFromName, conditionNameFromOpcode, conditionOpcode, conditionOpcodeFromName, inverseConditionName, jrConditionOpcodeFromName, symbolicTargetFromExpr, resolveScalarKind, resolveEaTypeExpr, resolveArrayType, typeDisplay, sameTypeShape, resolveEa, resolveAggregateType, lowerLdWithEa, selectOpOverload, formatAsmOperandForOpDiag, normalizeFixedToken, reg8Names, reg16Names, activePlacementRef, codeOffsetRef, dataOffsetRef, advanceAlign, recordLoweredAsmItem, lowerImmExprForLoweredAsm, } = wire;
+    const { programLoweringContext } = createEmitProgramContext({
+        diagnostics: {
+            diagnostics: ctx.diagnostics,
+            diag,
+            diagAt,
+            diagAtWithId,
+            diagAtWithSeverityAndId,
+            warnAt,
+        },
+        symbolsAndTrace: {
+            taken: ctx.workspace.symbols.taken,
+            pending: ctx.workspace.symbols.pending,
+            traceComment,
+            traceLabel,
+            currentCodeSegmentTagRef,
+            generatedLabelCounterRef,
+        },
+        spTracking: {
+            bindSpTracking: (callbacks) => {
+                if (callbacks?.applySpTracking) {
+                    spTrackingSlot.apply = callbacks.applySpTracking;
+                }
+                else {
+                    delete spTrackingSlot.apply;
+                }
+                if (callbacks?.invalidateSpTracking) {
+                    spTrackingSlot.invalidate = callbacks.invalidateSpTracking;
+                }
+                else {
+                    delete spTrackingSlot.invalidate;
+                }
+            },
+        },
+        emission: {
+            getCodeOffset: getCurrentCodeOffset,
+            emitInstr,
+            emitRawCodeBytes,
+            emitAbs16Fixup,
+            emitAbs16FixupPrefixed,
+            emitRel8Fixup,
+        },
+        conditions: {
+            conditionOpcodeFromName,
+            conditionNameFromOpcode,
+            callConditionOpcodeFromName,
+            jrConditionOpcodeFromName,
+            conditionOpcode,
+            inverseConditionName,
+            symbolicTargetFromExpr,
+        },
+        types: {
+            evalImmExpr,
+            env: ctx.env,
+            resolveScalarKind,
+            resolveAggregateType,
+            resolveEaTypeExpr,
+            resolveArrayType,
+            typeDisplay,
+            sameTypeShape,
+        },
+        addressing: {
+            resolveEa,
+            lowerLdWithEa,
+        },
+        opResolution: {
+            resolveOpCandidates: ctx.workspace.ops.resolveOpCandidatesForFile,
+        },
+        opOverload: {
+            formatAsmOperandForOpDiag,
+            selectOpOverload,
+        },
+        astUtilities: {
+            cloneImmExpr,
+            cloneEaExpr,
+            cloneOperand,
+            flattenEaDottedName,
+            normalizeFixedToken,
+        },
+        registers: {
+            reg8: reg8Names,
+            reg16: reg16Names,
+        },
+        program: {
+            program: ctx.program,
+            includeDirs: ctx.workspace.config.includeDirs,
+            localOpsByFile: ctx.workspace.ops.localOpsByFile,
+            declaredOpNames: ctx.workspace.ops.declaredOpNames,
+            absoluteSymbols: ctx.workspace.symbols.absoluteSymbols,
+            symbols: ctx.workspace.symbols.symbols,
+            dataBytes: ctx.workspace.emission.dataBytes,
+            codeBytes: ctx.workspace.emission.codeBytes,
+            activePlacementRef,
+            codeOffsetRef,
+            dataOffsetRef,
+            baseExprs: ctx.workspace.placement.baseExprs,
+            advanceAlign,
+            alignTo,
+            loadBinInput,
+            resolveAggregateType,
+            sizeOfTypeExpr: (typeExpr) => sizeOfTypeExpr(typeExpr, ctx.env, ctx.diagnostics),
+            recordLoweredAsmItem,
+            lowerImmExprForLoweredAsm,
+            currentCodeSegmentTagRef,
+        },
+    });
+    return programLoweringContext;
+}

package/dist/src/lowering/emitPhase1Helpers.d.ts

@@ -0,0 +1,4 @@
+import type { EmitPhase1Helpers, EmitPhase1HelpersContext } from './emitPhase1Types.js';
+export type { EmitPhase1Helpers } from './emitPhase1Types.js';
+/** Wires emit phase 1 helpers and program lowering context (see #1317). */
+export declare function createEmitPhase1Helpers(ctx: EmitPhase1HelpersContext): EmitPhase1Helpers;

package/dist/src/lowering/emitPhase1Helpers.js

@@ -0,0 +1,12 @@
+import { buildEmitProgramLoweringContext } from './emitPhase1BuildProgramLoweringContext.js';
+import { wireEmitPhase1Helpers } from './emitPhase1WirePipeline.js';
+/** Wires emit phase 1 helpers and program lowering context (see #1317). */
+export function createEmitPhase1Helpers(ctx) {
+    const wire = wireEmitPhase1Helpers(ctx);
+    const programLoweringContext = buildEmitProgramLoweringContext(ctx, wire);
+    return {
+        flushTrailingUserComments: wire.flushTrailingUserComments,
+        loweredAsmStream: ctx.workspace.emission.loweredAsmStream,
+        programLoweringContext,
+    };
+}

package/dist/src/lowering/emitPhase1Types.d.ts

@@ -0,0 +1,21 @@
+import type { ProgramNode } from '../frontend/ast.js';
+import type { CompileEnv } from '../semantics/env.js';
+import type { Diagnostic } from '../diagnosticTypes.js';
+import type { EmitProgramOptions } from './emitPipeline.js';
+import type { EmitPhase1Workspace } from './emitPhase1Workspace.js';
+type EmitProgramContextResult = ReturnType<typeof import('./emitProgramContext.js').createEmitProgramContext>;
+/** Inputs for emit phase 1 helper wiring (program lowering + asm recording). */
+export type EmitPhase1HelpersContext = {
+    program: ProgramNode;
+    env: CompileEnv;
+    diagnostics: Diagnostic[];
+    options?: EmitProgramOptions;
+    workspace: EmitPhase1Workspace;
+};
+/** Public surface returned from {@link createEmitPhase1Helpers}. */
+export type EmitPhase1Helpers = {
+    flushTrailingUserComments: () => void;
+    loweredAsmStream: EmitPhase1Workspace['emission']['loweredAsmStream'];
+    programLoweringContext: EmitProgramContextResult['programLoweringContext'];
+};
+export {};

package/dist/src/lowering/emitPhase1Types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/lowering/emitPhase1WirePipeline.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Emit phase 1 wiring: type resolution, emit state, fixups, emission core, EA/op matching,
+ * directive-alias bootstrap, addressing, and LD lowering.
+ */
+import type { AsmOperandNode, SourceSpan } from '../frontend/ast.js';
+import { createEaResolutionHelpers } from './eaResolution.js';
+import { createLdLoweringHelpers } from './ldLowering.js';
+import { createOpMatchingHelpers } from './opMatching.js';
+import { createFixupEmissionHelpers } from './fixupEmission.js';
+import { createAsmUtilityHelpers } from './asmUtils.js';
+import { createTypeResolutionHelpers } from '../semantics/typeQueries.js';
+import { createEmitStateHelpers } from './emitState.js';
+import type { EmitPhase1HelpersContext } from './emitPhase1Types.js';
+declare const REG8_NAMES: Set<string>;
+declare const REG16_NAMES: Set<string>;
+/** Mutable slot so {@link buildEmitProgramLoweringContext} can wire SP tracking without closure over `let`. */
+type SpTrackingSlot = {
+    apply?: (headRaw: string, operands: AsmOperandNode[]) => void;
+    invalidate?: () => void;
+};
+/** Intermediate closures and bundles passed to {@link buildEmitProgramLoweringContext}. */
+export type EmitPhase1WireResult = {
+    spTrackingSlot: SpTrackingSlot;
+    flushTrailingUserComments: ReturnType<typeof createEmitStateHelpers>['flushTrailingUserComments'];
+    reg8Names: typeof REG8_NAMES;
+    reg16Names: typeof REG16_NAMES;
+    getCurrentCodeOffset: ReturnType<typeof createEmitStateHelpers>['getCurrentCodeOffset'];
+    setCurrentCodeOffset: ReturnType<typeof createEmitStateHelpers>['setCurrentCodeOffset'];
+    setCurrentCodeByte: ReturnType<typeof createEmitStateHelpers>['setCurrentCodeByte'];
+    recordCodeSourceRange: ReturnType<typeof createEmitStateHelpers>['recordCodeSourceRange'];
+    pushCurrentFixup: ReturnType<typeof createEmitStateHelpers>['pushCurrentFixup'];
+    pushCurrentRel8Fixup: ReturnType<typeof createEmitStateHelpers>['pushCurrentRel8Fixup'];
+    traceLabel: ReturnType<typeof createEmitStateHelpers>['traceLabel'];
+    traceComment: ReturnType<typeof createEmitStateHelpers>['traceComment'];
+    advanceAlign: ReturnType<typeof createEmitStateHelpers>['advanceAlign'];
+    activePlacementRef: ReturnType<typeof createEmitStateHelpers>['activePlacementRef'];
+    codeOffsetRef: ReturnType<typeof createEmitStateHelpers>['codeOffsetRef'];
+    dataOffsetRef: ReturnType<typeof createEmitStateHelpers>['dataOffsetRef'];
+    currentCodeSegmentTagRef: ReturnType<typeof createEmitStateHelpers>['currentCodeSegmentTagRef'];
+    generatedLabelCounterRef: ReturnType<typeof createEmitStateHelpers>['generatedLabelCounterRef'];
+    recordLoweredAsmItem: ReturnType<typeof createEmitStateHelpers>['recordLoweredAsmItem'];
+    lowerImmExprForLoweredAsm: ReturnType<typeof createEmitStateHelpers>['lowerImmExprForLoweredAsm'];
+    lowerOperandForLoweredAsm: ReturnType<typeof createEmitStateHelpers>['lowerOperandForLoweredAsm'];
+    emitInstr: (head: string, operands: AsmOperandNode[], span: SourceSpan) => boolean;
+    emitRawCodeBytes: (bs: Uint8Array, file: string, traceText: string) => void;
+    callConditionOpcodeFromName: ReturnType<typeof createFixupEmissionHelpers>['callConditionOpcodeFromName'];
+    conditionNameFromOpcode: ReturnType<typeof createFixupEmissionHelpers>['conditionNameFromOpcode'];
+    conditionOpcode: ReturnType<typeof createFixupEmissionHelpers>['conditionOpcode'];
+    conditionOpcodeFromName: ReturnType<typeof createFixupEmissionHelpers>['conditionOpcodeFromName'];
+    emitAbs16Fixup: ReturnType<typeof createFixupEmissionHelpers>['emitAbs16Fixup'];
+    emitAbs16FixupEd: ReturnType<typeof createFixupEmissionHelpers>['emitAbs16FixupEd'];
+    emitAbs16FixupPrefixed: ReturnType<typeof createFixupEmissionHelpers>['emitAbs16FixupPrefixed'];
+    emitRel8Fixup: ReturnType<typeof createFixupEmissionHelpers>['emitRel8Fixup'];
+    inverseConditionName: ReturnType<typeof createFixupEmissionHelpers>['inverseConditionName'];
+    jrConditionOpcodeFromName: ReturnType<typeof createFixupEmissionHelpers>['jrConditionOpcodeFromName'];
+    symbolicTargetFromExpr: ReturnType<typeof createFixupEmissionHelpers>['symbolicTargetFromExpr'];
+    normalizeFixedToken: ReturnType<typeof createAsmUtilityHelpers>['normalizeFixedToken'];
+    resolveEa: ReturnType<typeof createEaResolutionHelpers>['resolveEa'];
+    selectOpOverload: ReturnType<typeof createOpMatchingHelpers>['selectOpOverload'];
+    formatAsmOperandForOpDiag: ReturnType<typeof createOpMatchingHelpers>['formatAsmOperandForOpDiag'];
+    lowerLdWithEa: ReturnType<typeof createLdLoweringHelpers>['lowerLdWithEa'];
+    resolveAggregateType: ReturnType<typeof createTypeResolutionHelpers>['resolveAggregateType'];
+    resolveScalarKind: ReturnType<typeof createTypeResolutionHelpers>['resolveScalarKind'];
+    resolveEaTypeExpr: ReturnType<typeof createTypeResolutionHelpers>['resolveEaTypeExpr'];
+    resolveArrayType: ReturnType<typeof createTypeResolutionHelpers>['resolveArrayType'];
+    typeDisplay: ReturnType<typeof createTypeResolutionHelpers>['typeDisplay'];
+    sameTypeShape: ReturnType<typeof createTypeResolutionHelpers>['sameTypeShape'];
+};
+export declare function wireEmitPhase1Helpers(ctx: EmitPhase1HelpersContext): EmitPhase1WireResult;
+export {};

package/dist/src/lowering/emitPhase1WirePipeline.js

@@ -0,0 +1,203 @@
+/**
+ * Emit phase 1 wiring: type resolution, emit state, fixups, emission core, EA/op matching,
+ * directive-alias bootstrap, addressing, and LD lowering.
+ */
+import { evalImmExpr } from '../semantics/env.js';
+import { sizeOfTypeExpr } from '../semantics/layout.js';
+import { encodeInstruction } from '../z80/encode.js';
+import { buildEaResolutionContext, createEaResolutionHelpers } from './eaResolution.js';
+import { createLdLoweringHelpers } from './ldLowering.js';
+import { createOpMatchingHelpers } from './opMatching.js';
+import { createEmissionCoreHelpers } from './emissionCore.js';
+import { createFixupEmissionHelpers } from './fixupEmission.js';
+import { createAsmUtilityHelpers, flattenEaDottedName } from './asmUtils.js';
+import { formatImmExprForAsm } from './traceFormat.js';
+import { createTypeResolutionHelpers } from '../semantics/typeQueries.js';
+import { createEmitStateHelpers } from './emitState.js';
+import { alignTo } from './bytePlacement.js';
+import { diagAt } from './loweringDiagnostics.js';
+const REG8_NAMES = new Set(['A', 'B', 'C', 'D', 'E', 'H', 'L']);
+const REG16_NAMES = new Set(['BC', 'DE', 'HL', 'IX', 'IY']);
+const REG8_CODES = new Map([
+    ['B', 0],
+    ['C', 1],
+    ['D', 2],
+    ['E', 3],
+    ['H', 4],
+    ['L', 5],
+    ['A', 7],
+]);
+export function wireEmitPhase1Helpers(ctx) {
+    const spTrackingSlot = {};
+    let emitCodeBytes;
+    let emitRawCodeBytes;
+    const { resolveAggregateType, resolveArrayType, resolveEaTypeExpr, resolveScalarKind, sameTypeShape, typeDisplay, } = createTypeResolutionHelpers({
+        env: ctx.env,
+    });
+    const evalImmNoDiag = (expr) => {
+        const scratch = [];
+        return evalImmExpr(expr, ctx.env, scratch);
+    };
+    const { activePlacementRef, codeOffsetRef, dataOffsetRef, currentCodeSegmentTagRef, generatedLabelCounterRef, getCurrentCodeOffset, setCurrentCodeOffset, setCurrentCodeByte, pushCurrentFixup, pushCurrentRel8Fixup, recordCodeSourceRange, traceLabel, traceComment, advanceAlign, flushTrailingUserComments, lowerImmExprForLoweredAsm, lowerOperandForLoweredAsm, recordLoweredAsmItem, } = createEmitStateHelpers({
+        ...(ctx.options?.sourceTexts ? { sourceTexts: ctx.options.sourceTexts } : {}),
+        ...(ctx.options?.sourceLineComments
+            ? { sourceLineComments: ctx.options.sourceLineComments }
+            : {}),
+        codeBytes: ctx.workspace.emission.codeBytes,
+        codeSourceSegments: ctx.workspace.emission.codeSourceSegments,
+        fixups: ctx.workspace.symbols.fixups,
+        rel8Fixups: ctx.workspace.symbols.rel8Fixups,
+        loweredAsmStream: ctx.workspace.emission.loweredAsmStream,
+        loweredAsmBlocksByKey: ctx.workspace.emission.loweredAsmBlocksByKey,
+        alignTo,
+        evalImmNoDiag,
+        symbolicTargetFromExpr: (expr) => symbolicTargetFromExpr(expr),
+        formatImmExprForAsm,
+        typeDisplay: (typeExpr) => typeDisplay(typeExpr),
+    });
+    const emitInstr = (head, operands, span) => {
+        const syntheticInstruction = {
+            kind: 'AsmInstruction',
+            span,
+            head,
+            operands,
+        };
+        const encoded = encodeInstruction(syntheticInstruction, ctx.env, ctx.diagnostics);
+        if (!encoded)
+            return false;
+        recordLoweredAsmItem({
+            kind: 'instr',
+            head,
+            operands: operands.map((op) => lowerOperandForLoweredAsm(op)),
+            bytes: [...encoded],
+        }, span);
+        emitCodeBytes(encoded, span.file);
+        spTrackingSlot.apply?.(head, operands);
+        return true;
+    };
+    const { callConditionOpcodeFromName, conditionNameFromOpcode, conditionOpcode, conditionOpcodeFromName, emitAbs16Fixup, emitAbs16FixupEd, emitAbs16FixupPrefixed, emitRel8Fixup, inverseConditionName, jrConditionOpcodeFromName, symbolicTargetFromExpr, } = createFixupEmissionHelpers({
+        getCodeOffset: getCurrentCodeOffset,
+        setCodeOffset: setCurrentCodeOffset,
+        setCodeByte: setCurrentCodeByte,
+        recordCodeSourceRange,
+        pushFixup: pushCurrentFixup,
+        pushRel8Fixup: pushCurrentRel8Fixup,
+        traceInstruction: (_offset, _bytesOut, _text) => { },
+        recordLoweredInstr: (bytes, _asmText, span) => {
+            recordLoweredAsmItem({
+                kind: 'instr',
+                head: '@raw',
+                operands: [],
+                bytes: [...bytes],
+            }, span);
+        },
+        evalImmExpr: (expr) => evalImmExpr(expr, ctx.env, ctx.diagnostics),
+    });
+    ({ emitCodeBytes, emitRawCodeBytes } = createEmissionCoreHelpers({
+        getCodeOffset: getCurrentCodeOffset,
+        setCodeOffset: setCurrentCodeOffset,
+        setCodeByte: setCurrentCodeByte,
+        recordCodeSourceRange,
+        traceInstruction: (_offset, _bytesOut, _text) => { },
+    }));
+    const emitRawCodeBytesImpl = emitRawCodeBytes;
+    emitRawCodeBytes = (bs, file, traceText) => {
+        recordLoweredAsmItem({ kind: 'instr', head: '@raw', operands: [], bytes: [...bs] });
+        emitRawCodeBytesImpl(bs, file, traceText);
+    };
+    const { normalizeFixedToken } = createAsmUtilityHelpers({
+        isEnumName: (name) => ctx.env.enums.has(name),
+    });
+    const { resolveEa } = createEaResolutionHelpers(buildEaResolutionContext({
+        env: ctx.env,
+        diagnostics: ctx.diagnostics,
+        diagAt,
+        resolveScalarKind,
+        resolveAggregateType,
+        resolveEaTypeExpr,
+        evalImmNoDiag,
+    }));
+    const isIxIyIndexedMem = (op) => op.kind === 'Mem' &&
+        ((op.expr.kind === 'EaName' && /^(IX|IY)$/i.test(op.expr.name)) ||
+            ((op.expr.kind === 'EaAdd' || op.expr.kind === 'EaSub') &&
+                op.expr.base.kind === 'EaName' &&
+                /^(IX|IY)$/i.test(op.expr.base.name)));
+    const inferMemWidth = (op) => {
+        if (op.kind !== 'Mem')
+            return undefined;
+        const resolved = resolveEa(op.expr, op.span);
+        if (!resolved?.typeExpr)
+            return undefined;
+        return sizeOfTypeExpr(resolved.typeExpr, ctx.env, ctx.diagnostics);
+    };
+    const { selectOpOverload, formatAsmOperandForOpDiag } = createOpMatchingHelpers({
+        reg8: REG8_NAMES,
+        isIxIyIndexedMem,
+        flattenEaDottedName,
+        isEnumName: (name) => ctx.env.enums.has(name),
+        normalizeFixedToken,
+        conditionOpcodeFromName,
+        evalImmNoDiag,
+        inferMemWidth,
+    });
+    const { lowerLdWithEa } = createLdLoweringHelpers({
+        diagAt,
+        diagnostics: ctx.diagnostics,
+        emitAbs16Fixup,
+        emitAbs16FixupEd,
+        emitAbs16FixupPrefixed,
+        env: ctx.env,
+        reg8Code: REG8_CODES,
+        resolveEa,
+        setSpTrackingInvalid: () => {
+            spTrackingSlot.invalidate?.();
+        },
+    });
+    return {
+        spTrackingSlot,
+        flushTrailingUserComments,
+        reg8Names: REG8_NAMES,
+        reg16Names: REG16_NAMES,
+        getCurrentCodeOffset,
+        setCurrentCodeOffset,
+        setCurrentCodeByte,
+        recordCodeSourceRange,
+        pushCurrentFixup,
+        pushCurrentRel8Fixup,
+        traceLabel,
+        traceComment,
+        advanceAlign,
+        activePlacementRef,
+        codeOffsetRef,
+        dataOffsetRef,
+        currentCodeSegmentTagRef,
+        generatedLabelCounterRef,
+        recordLoweredAsmItem,
+        lowerImmExprForLoweredAsm,
+        lowerOperandForLoweredAsm,
+        emitInstr,
+        emitRawCodeBytes,
+        callConditionOpcodeFromName,
+        conditionNameFromOpcode,
+        conditionOpcode,
+        conditionOpcodeFromName,
+        emitAbs16Fixup,
+        emitAbs16FixupEd,
+        emitAbs16FixupPrefixed,
+        emitRel8Fixup,
+        inverseConditionName,
+        jrConditionOpcodeFromName,
+        symbolicTargetFromExpr,
+        normalizeFixedToken,
+        resolveEa,
+        selectOpOverload,
+        formatAsmOperandForOpDiag,
+        lowerLdWithEa,
+        resolveAggregateType,
+        resolveScalarKind,
+        resolveEaTypeExpr,
+        resolveArrayType,
+        typeDisplay,
+        sameTypeShape,
+    };
+}

package/dist/src/lowering/emitPhase1Workspace.d.ts

@@ -0,0 +1,82 @@
+import type { ImmExprNode, OpDeclNode, ProgramNode } from '../frontend/ast.js';
+import type { CompileEnv } from '../semantics/env.js';
+import type { EmittedSourceSegment, SymbolEntry } from '../formats/types.js';
+import type { EmitProgramOptions } from './emitPipeline.js';
+import type { PendingSymbol } from './loweringTypes.js';
+import type { LoweredAsmStream, LoweredAsmStreamBlock } from './loweredAsmTypes.js';
+import { createOpCandidateRegistryHelpers } from './opCandidateRegistry.js';
+/** Byte maps, listing segments, and lowered-asm recording for phase 1. */
+type EmitPhase1EmissionState = {
+    /** Merged map of all emitted bytes across code/data placement. */
+    bytes: Map<number, number>;
+    /** Code-placement bytes only (before merge into `bytes` for some paths). */
+    codeBytes: Map<number, number>;
+    /** Data-placement bytes. */
+    dataBytes: Map<number, number>;
+    /** Source ranges for emitted code bytes (listing/debug). */
+    codeSourceSegments: EmittedSourceSegment[];
+    /** Stream of lowered asm blocks for tracing. */
+    loweredAsmStream: LoweredAsmStream;
+    /** Lookup of lowered asm blocks by stable key. */
+    loweredAsmBlocksByKey: Map<string, LoweredAsmStreamBlock>;
+};
+type EmitPhase1AbsFixup = {
+    offset: number;
+    baseLower: string;
+    addend: number;
+    file: string;
+};
+type EmitPhase1Rel8Fixup = {
+    offset: number;
+    origin: number;
+    baseLower: string;
+    addend: number;
+    file: string;
+    mnemonic: string;
+};
+/** Symbol tables, fixup queues, and name reservation. */
+type EmitPhase1SymbolState = {
+    /** Symbols with absolute addresses after prescan/lowering. */
+    absoluteSymbols: SymbolEntry[];
+    /** All collected symbol table entries. */
+    symbols: SymbolEntry[];
+    /** Pending forward references not yet bound. */
+    pending: PendingSymbol[];
+    /** Lowercased names already claimed by labels or generated/internal symbols. */
+    taken: Set<string>;
+    /** Absolute 16-bit fixups pending placement (offset in output, symbol, addend). */
+    fixups: EmitPhase1AbsFixup[];
+    /** Relative 8-bit PC-relative fixups. */
+    rel8Fixups: EmitPhase1Rel8Fixup[];
+};
+/** Op candidate lookup. */
+type EmitPhase1OpRegistry = {
+    /** Per-file op overload lists. */
+    localOpsByFile: Map<string, Map<string, OpDeclNode[]>>;
+    /** All declared `op` names (lowercased) for diagnostics. */
+    declaredOpNames: Set<string>;
+    /** Resolves op candidates declared for a file. */
+    resolveOpCandidatesForFile: ReturnType<typeof createOpCandidateRegistryHelpers>['resolveOpCandidatesForFile'];
+};
+/** Options and paths fixed for the emit run. */
+type EmitPhase1EmitConfig = {
+    /** Entry / primary source file path. */
+    primaryFile: string;
+    /** Resolved include directories for asset loads. */
+    includeDirs: string[];
+};
+/** Mutable placement maps for the current lowering context. */
+type EmitPhase1PlacementState = {
+    /** Optional base imm expressions per placement. */
+    baseExprs: Partial<Record<'code' | 'data', ImmExprNode>>;
+};
+/** Root workspace for emit phase 1: grouped sub-objects replace a single flat struct. */
+export type EmitPhase1Workspace = {
+    emission: EmitPhase1EmissionState;
+    symbols: EmitPhase1SymbolState;
+    ops: EmitPhase1OpRegistry;
+    config: EmitPhase1EmitConfig;
+    placement: EmitPhase1PlacementState;
+};
+export declare function createEmitPhase1Workspace(program: ProgramNode, env: CompileEnv, options?: EmitProgramOptions): EmitPhase1Workspace;
+export {};

package/dist/src/lowering/emitPhase1Workspace.js

@@ -0,0 +1,55 @@
+import { resolve } from 'node:path';
+import { createOpCandidateRegistryHelpers } from './opCandidateRegistry.js';
+export function createEmitPhase1Workspace(program, env, options) {
+    const bytes = new Map();
+    const codeBytes = new Map();
+    const dataBytes = new Map();
+    const codeSourceSegments = [];
+    const loweredAsmStream = { blocks: [] };
+    const loweredAsmBlocksByKey = new Map();
+    const absoluteSymbols = [];
+    const symbols = [];
+    const pending = [];
+    const taken = new Set();
+    const fixups = [];
+    const rel8Fixups = [];
+    const localOpsByFile = new Map();
+    const declaredOpNames = new Set();
+    const { resolveOpCandidatesForFile } = createOpCandidateRegistryHelpers({
+        localOpsByFile,
+    });
+    const baseExprs = {};
+    const firstSourceFile = program.files[0];
+    const primaryFile = firstSourceFile.span.file ?? program.entryFile;
+    const includeDirs = (options?.includeDirs ?? []).map((p) => resolve(p));
+    return {
+        emission: {
+            bytes,
+            codeBytes,
+            dataBytes,
+            codeSourceSegments,
+            loweredAsmStream,
+            loweredAsmBlocksByKey,
+        },
+        symbols: {
+            absoluteSymbols,
+            symbols,
+            pending,
+            taken,
+            fixups,
+            rel8Fixups,
+        },
+        ops: {
+            localOpsByFile,
+            declaredOpNames,
+            resolveOpCandidatesForFile,
+        },
+        config: {
+            primaryFile,
+            includeDirs,
+        },
+        placement: {
+            baseExprs,
+        },
+    };
+}