@mica-js/compiler 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,402 @@
+import { ComputationIR } from '@mica-js/device-model';
+import { InputPath } from '@mica-js/device-model';
+import { OperationIR } from '@mica-js/device-model';
+import { ParameterTypeIR } from '@mica-js/device-model';
+import { RegionIR } from '@mica-js/device-model';
+import { SourceInfo } from '@mica-js/device-model';
+import { ValueTypeIR } from '@mica-js/device-model';
+
+export declare interface Artifact<T = CompiledBody> {
+    readonly execute: T;
+    readonly source: string;
+    readonly constants: readonly unknown[];
+    readonly positions: readonly GeneratedPosition[];
+    readonly resume: readonly ResumePoint[];
+    readonly effects: EffectMetadata;
+    readonly mir: InternalGraph;
+    readonly dependencies: ArtifactDependencies;
+    readonly sourceMap: SourceMap;
+    readonly frameLayout: FrameLayout;
+    readonly resumeMap: ResumeMap;
+    readonly exitMap: readonly ExitPoint[];
+    readonly optimizations: OptimizationMetadata;
+}
+
+export declare interface ArtifactBinding {
+    readonly instance?: string;
+    readonly entry?: string;
+    readonly generation?: number;
+    readonly codeVersion?: string | number;
+    readonly instruction?: {
+        readonly pc: number;
+        readonly nextPc: number;
+    };
+}
+
+export declare interface ArtifactDependencies {
+    readonly binding: ArtifactBinding | null;
+    readonly reads: readonly string[];
+    readonly writes: readonly string[];
+    readonly calls: readonly string[];
+    readonly resources: readonly string[];
+    readonly unresolvedCalls: boolean;
+}
+
+export declare interface BaselinePosition {
+    readonly position: number;
+    readonly block: number;
+    readonly phase: 'before' | 'after' | 'delegate';
+}
+
+/** One operation per block is intentional; joins/resume/exit blocks are explicit. */
+export declare interface BasicBlock {
+    readonly id: number;
+    readonly region: number;
+    readonly role: 'operation' | 'entry' | 'exit' | 'join' | 'resume' | 'return' | 'throw' | 'stop' | 'redirect';
+    readonly position: number | null;
+    readonly predecessors: readonly number[];
+    readonly successors: readonly number[];
+    readonly uses: readonly string[];
+    readonly definitions: readonly string[];
+    readonly liveIn: readonly string[];
+    readonly liveOut: readonly string[];
+    readonly baselineLiveIn: readonly string[];
+    readonly baselineLiveOut: readonly string[];
+}
+
+export declare function checkBoolean(value: unknown): boolean;
+
+export declare function checkDuration(value: unknown): number;
+
+export declare function checkPc(value: unknown): number;
+
+export declare function combineIntents(values: readonly unknown[]): readonly unknown[];
+
+/** Inputs must already have passed device-model validation and contextual binding. */
+export declare function compileBody(region: RegionIR, options?: CompileOptions): CompiledBody;
+
+export declare function compileBodyArtifact(region: RegionIR, options?: CompileOptions): Artifact<CompiledBody>;
+
+export declare function compileComputation(computation: ComputationIR, options?: CompileOptions): CompiledComputation;
+
+export declare function compileComputationArtifact(computation: ComputationIR, options?: CompileOptions): Artifact<CompiledComputation>;
+
+export declare type CompiledBody = (host: ExecutionHost, args?: readonly unknown[], reaction?: ReactionFrame) => Generator<ExecutionSignal, unknown, unknown>;
+
+export declare type CompiledComputation = (host: ExecutionHost) => unknown;
+
+/** Inputs have already passed model validation and contextual binding. */
+export declare function compileDirectJit(instructions: readonly {
+    readonly pc: number;
+    readonly nextPc: number;
+    readonly body: RegionIR;
+}[], binding: DirectJitBinding): DirectJitProgram | undefined;
+
+export declare interface CompileOptions {
+    readonly optimize?: boolean;
+    /** Optional identity supplied by the binding runtime; it is never guessed from a body. */
+    readonly binding?: ArtifactBinding;
+}
+
+export declare interface ConstantMaterialization {
+    readonly slot: number;
+    readonly kind: 'constant';
+    readonly value: number | boolean | string | null;
+}
+
+export declare interface ControlEdge {
+    readonly from: number;
+    readonly to: number;
+    readonly kind: EdgeKind;
+    readonly arm?: number;
+    readonly value?: number;
+}
+
+export declare function createBytes(elements: readonly unknown[]): Uint8Array;
+
+export declare function createEnum(_name: string, member: string): EnumValue;
+
+export declare function createRecord(fields: readonly (readonly [string, unknown])[]): Readonly<Record<string, unknown>>;
+
+/** Static numeric bank layout; the runtime guards ownership/observers before entry. */
+export declare interface DirectJitBinding {
+    readonly states: ReadonlyMap<string, number>;
+    readonly memories: ReadonlyMap<string, number>;
+    readonly pc: {
+        readonly name: string;
+        readonly index: number;
+    };
+    /** Compile-time write barriers; recompile when membership changes. */
+    readonly blockedStates?: ReadonlySet<string>;
+    readonly blockedMemories?: ReadonlySet<string>;
+}
+
+/** Reusable runtime-owned bank. Flush completed effects even when run throws. */
+export declare interface DirectJitFrame {
+    states: unknown[];
+    memories: Uint8Array[];
+    /** Reusable bit words indexed by bank index >>> 5; clear before each invocation. */
+    stateDirty: number[];
+    memoryDirty: number[];
+    time: number;
+    /** Absolute wake time when resume is nonzero. */
+    due: number;
+    /** Zero means idle; other values are opaque continuations owned by this program. */
+    resume: number;
+    /** Allocate at least program.localCount slots once, not once per instruction. */
+    locals: unknown[];
+    /** Complete a pending old instruction, then exit before starting another. */
+    stopAfterInstruction?: boolean;
+}
+
+export declare interface DirectJitProgram {
+    /** At time === deadline neither an instruction nor its suffix executes. */
+    run(frame: DirectJitFrame, deadline: number): DirectJitReason;
+    readonly localCount: number;
+    readonly readStates: readonly string[];
+    readonly writeStates: readonly string[];
+    readonly readMemories: readonly string[];
+    readonly writeMemories: readonly string[];
+}
+
+export declare type DirectJitReason = 'deadline' | 'fallback' | 'stopped' | 'invalidated';
+
+export declare type EdgeKind = 'next' | 'true' | 'false' | 'arm' | 'default' | 'backedge' | 'break' | 'continue' | 'yield' | 'return' | 'suspend' | 'resume' | 'redirect' | 'stop' | 'throw';
+
+/** Effects are conservative and syntactic; calls require runtime/model call-graph analysis. */
+export declare interface EffectMetadata {
+    readonly reads: readonly string[];
+    readonly writes: readonly string[];
+    readonly calls: readonly string[];
+    readonly operations: readonly OperationIR['kind'][];
+    readonly maySuspend: boolean;
+    readonly mayRedirect: boolean;
+    readonly mayStop: boolean;
+    readonly timeDependent: boolean;
+    readonly random: boolean;
+}
+
+/** Nominal enum identity is validated statically; runtime values are member names. */
+export declare type EnumValue = string;
+
+/** Structural comparison deliberately does not shortcut identical objects containing NaN. */
+export declare function equalValues(left: unknown, right: unknown): boolean;
+
+export declare interface ExecutionHost {
+    read(resource: 'property' | 'const' | 'state' | 'derived', name: string): unknown;
+    write(name: string, value: unknown): void;
+    sample(pin: unknown): unknown;
+    intent(pin: unknown, value: unknown): void;
+    resistor(pin: unknown, resistance: unknown): unknown;
+    load(kind: string, memory: unknown, offset: unknown): number;
+    store(kind: string, memory: unknown, offset: unknown, value: unknown): void;
+    copyBytes(memory: unknown, offset: unknown, length: unknown): unknown;
+    memoryLength(memory: unknown): number;
+    send(name: string, value: unknown): void;
+    notify(name: string): void;
+    now(): number;
+    random(): number;
+    call(name: string, args: readonly unknown[]): Generator<ExecutionSignal, unknown, unknown>;
+    assert(condition: unknown, message: unknown): void;
+}
+
+export declare type ExecutionSignal = {
+    readonly kind: 'ticks' | 'elapse';
+    readonly duration: number;
+} | {
+    readonly kind: 'receive';
+    readonly channel: string;
+} | {
+    readonly kind: 'waitUntil';
+    readonly predicate: string;
+} | {
+    readonly kind: 'redirect';
+    readonly pc: number;
+    readonly delay: number;
+} | {
+    readonly kind: 'stop';
+};
+
+export declare interface ExitPoint {
+    readonly baseline: BaselinePosition;
+    readonly reason: ExitReason;
+    readonly generated: GeneratedRange;
+    readonly requiredSlots: readonly number[];
+    readonly captureSlots: readonly number[];
+}
+
+export declare type ExitReason = 'return' | 'suspend' | 'redirect' | 'stop' | 'throw' | 'deopt';
+
+/** Data contract for a future consumer; current generators do not expose their slots. */
+export declare interface ExitState {
+    readonly reason: ExitReason;
+    readonly baseline: BaselinePosition;
+    readonly values: readonly {
+        readonly slot: number;
+        readonly value: unknown;
+    }[];
+    readonly signal?: ExecutionSignal;
+    readonly value?: unknown;
+    readonly cause?: unknown;
+    /** A retained native continuation is required for resuming this backend's stack. */
+    readonly continuation?: Generator<ExecutionSignal, unknown, unknown>;
+}
+
+/** Describes actual native-generator bindings, not an externally writable stack frame. */
+export declare interface FrameLayout {
+    readonly storage: 'native-generator';
+    readonly serializable: false;
+    readonly slots: readonly FrameSlot[];
+    readonly materializations: readonly ConstantMaterialization[];
+}
+
+export declare interface FrameSlot {
+    readonly id: number;
+    readonly key: string;
+    readonly kind: 'value' | 'local' | 'argument' | 'reaction' | 'temporary';
+    readonly name: string;
+    readonly region: number;
+    readonly definition: number | null;
+    readonly materialized: boolean;
+    readonly type?: ParameterTypeIR;
+}
+
+/** Generated line and column are one-based, relative to Artifact.source. */
+export declare interface GeneratedPosition {
+    readonly path: InputPath;
+    readonly kind: OperationIR['kind'];
+    readonly line: number;
+    readonly column: number;
+    readonly source?: SourceInfo;
+}
+
+export declare interface GeneratedRange {
+    readonly start: {
+        readonly line: number;
+        readonly column: number;
+    };
+    readonly end: {
+        readonly line: number;
+        readonly column: number;
+    };
+}
+
+export declare type InternalAttribute = string | number | boolean | null | readonly InternalAttribute[] | {
+    readonly [key: string]: InternalAttribute;
+};
+
+/** SSA result definitions plus explicit mutable local slots; locals are not SSA-promoted. */
+export declare interface InternalGraph {
+    readonly entry: number;
+    readonly normalExit: number;
+    readonly regions: readonly InternalRegion[];
+    readonly blocks: readonly BasicBlock[];
+    readonly edges: readonly ControlEdge[];
+    readonly operations: readonly InternalOperation[];
+    readonly values: readonly ValueDefinition[];
+}
+
+export declare interface InternalOperation {
+    readonly position: number;
+    readonly block: number;
+    readonly region: number;
+    readonly kind: OperationIR['kind'];
+    readonly path: InputPath;
+    readonly source?: SourceInfo;
+    readonly inputs: readonly number[];
+    readonly attributes: Readonly<Record<string, InternalAttribute>>;
+    readonly regions: readonly {
+        readonly role: string;
+        readonly region: number;
+    }[];
+    readonly effects: OperationEffects;
+    readonly eliminated: boolean;
+    readonly folded: boolean;
+}
+
+export declare interface InternalRegion {
+    readonly id: number;
+    readonly parent: number | null;
+    readonly path: InputPath;
+    readonly entry: number;
+    readonly exit: number;
+}
+
+export declare function nonNull(value: unknown): unknown;
+
+export declare interface OperationEffects extends EffectMetadata {
+    readonly mayThrow: boolean;
+}
+
+export declare interface OptimizationMetadata {
+    readonly enabled: boolean;
+    readonly foldedPositions: readonly number[];
+    readonly eliminatedPositions: readonly number[];
+}
+
+export declare function reactionCapture(frame: ReactionFrame | undefined, index: number): unknown;
+
+export declare interface ReactionFrame {
+    readonly previous: unknown;
+    readonly current: unknown;
+    readonly captures: readonly unknown[];
+}
+
+export declare function reactionValue(frame: ReactionFrame | undefined, binding: 'previous' | 'current'): unknown;
+
+export declare function readIndex(value: string | ArrayLike<number>, index: unknown): string | number;
+
+export declare interface ResumeLocation {
+    readonly id: number;
+    readonly kind: OperationIR['kind'];
+    readonly suspended: BaselinePosition;
+    readonly baseline: BaselinePosition;
+    readonly generated: GeneratedRange;
+    readonly continuation: {
+        readonly line: number;
+        readonly column: number;
+    };
+    readonly liveSlots: readonly number[];
+    readonly delegated: boolean;
+    readonly terminal: boolean;
+}
+
+export declare interface ResumeMap {
+    readonly entries: readonly ResumeLocation[];
+}
+
+export declare interface ResumePoint extends GeneratedPosition {
+    readonly id: number;
+    /** Calls may suspend or terminate through any transitive callee. */
+    readonly delegated: boolean;
+}
+
+export declare interface SourceMap {
+    readonly entries: readonly SourceMapEntry[];
+}
+
+export declare interface SourceMapEntry {
+    readonly position: number;
+    readonly block: number;
+    readonly path: InputPath;
+    readonly kind: OperationIR['kind'];
+    readonly source?: SourceInfo;
+    readonly generated: GeneratedRange | null;
+    readonly eliminated: boolean;
+    readonly folded: boolean;
+}
+
+export declare interface ValueDefinition {
+    readonly result: number;
+    readonly type: ValueTypeIR;
+    readonly position: number;
+    readonly region: number;
+    readonly block: number;
+    readonly form: 'operation' | 'phi';
+    readonly inputs: readonly number[];
+    readonly users: readonly number[];
+    readonly eliminated: boolean;
+    readonly folded: boolean;
+}
+
+export { }