atelang-core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Semight
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,167 @@
-# Temporary Holding Version
+# atelang-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Reusable ATELang (`.ate`) language, compiler, execution engine, and Node adapters.
+This is an independent npm package, version `0.1.0`, requiring Node.js 18 or newer.
+It ships CommonJS JavaScript and TypeScript declarations with no runtime dependencies.
+Installing the package does not require the sibling plugin or example projects.
+
+The core owns tokenization, AST types, quantities/units, import loading through an
+injected `Host`, symbols, diagnostics, definition lookup, compilation units, and the
+binary codec, execution, simulation, datalog, and Python method support. The sibling
+`atelang-vscode` plugin owns the CLI, VS Code integration, and
+debug adapter. The core also owns pause/step control and executable source mappings.
+The root, runtime, and debug entries do not import VS Code or Node APIs; Node
+filesystem, gzip, and Python process adapters are isolated behind the `/node` entry.
+
+## Build, Test, and Pack
+
+Run independently from `atelang-core/`:
+
+```bash
+npm install          # install dev dependencies; prepare builds dist/
+npm run build        # explicit rebuild after source changes
+npm test             # build and run JavaScript tests in test/ against the public API
+npm pack --dry-run   # inspect the package contents
+npm pack             # create atelang-core-0.1.0.tgz locally
+```
+
+`prepare` builds on install/pack; `prepublishOnly` runs tests before publishing.
+`npm pack` does not publish or run `prepublishOnly`, so run `npm test` before packing.
+The package includes `dist/index.*`, `dist/language/`, `dist/compiler/`,
+`dist/runtime/`, `dist/debug/`, `dist/editor/`, `dist/node/`, `resources/python/`, and `docs/`;
+compiled tests are excluded. `npm run clean` removes `dist/`.
+
+To install the tarball in a sibling Node project:
+
+```bash
+npm install ../atelang-core/atelang-core-0.1.0.tgz
+```
+
+## Public API
+
+Import language/compiler values and types from `atelang-core`, execution
+APIs from `atelang-core/runtime`, debugging primitives from
+`atelang-core/debug`, completion and hover data from
+`atelang-core/editor`, and Node adapters from
+`atelang-core/node`. The package root is backed by `dist/index.js` and
+`dist/index.d.ts`; deep imports such as
+`atelang-core/dist/language/parser` are not exported.
+
+The editor entry exposes `getCompletions(linePrefix, symbols)` and
+`getHover(symbolName, symbols)`. They return plain candidate and Markdown/code-block
+data without editor dependencies. Hosts supply cursor context and adapt the results
+to their editor APIs; document lifecycle and caching remain host responsibilities.
+
+```js
+const { parse, compile, memoryHost } = require("atelang-core");
+
+const source = "flow MainFlow {}";
+const { program, errors } = parse(source, "main.ate");
+console.log(program.body, errors);
+
+// A flat in-memory project; real hosts resolve imports relative to the importer.
+const host = memoryHost({ "main.ate": source }, (_from, spec) => spec);
+const { analysis } = compile("main.ate", host);
+console.log(analysis.diagnostics);
+```
+
+| Entry points | Purpose |
+| --- | --- |
+| `tokenize`, `tokenizeSafe`, `parse` | Tokens and ASTs with source ranges and parse errors |
+| `loadProgram`, `memoryHost` | Load an import graph using caller-supplied file access and resolution |
+| `compile`, `analyze`, `buildSymbols`, `findDefinition` | Project analysis, symbols, diagnostics, and definition locations |
+| `compileToUnit`, `loadResultFromUnit`, `formatDiagnostic` | Produce/reload a `CompilationUnit` and format diagnostics |
+| `encodeBinary`, `decodeBinary`, `looksLikeBinary`, `AteBinaryError` | Encode/decode bytes and report binary format errors |
+
+Types including `Program`, `Expr`, `Stmt`, `Diagnostic`, `Host`, `CompilationUnit`, and
+`Compressor` are exported from the same root. `Host.readFile(path)` returns source text
+or `null`; `Host.resolve(fromPath, spec)` returns the resolved import path. `compile()`
+loads and analyzes without executing; `compileToUnit()` produces no unit if any error
+diagnostic exists. Warnings remain available in its result.
+
+The codec accepts/returns `Uint8Array`. Encoding is uncompressed by default; gzip
+requires an injected `Compressor` with `deflate` and `inflate`. File reads/writes and
+compression belong to the caller; see the [binary format guide](docs/BINARY_FORMAT.md).
+
+## Variables, Boards, and Instrument Actions
+
+```atelang
+dutBoard Board { pin VDD : Power pin CLK : Digital }
+var Conditions {
+	DC { set nominal { VDD = 3.3V RANGE = 5 } }
+	AC { set nominal { PERIOD = 100ns } }
+}
+levels L { useVarSet: Conditions.nominal VDD { force_v: VDD } }
+timing T { useVarSet: Conditions.nominal period: PERIOD }
+action PowerOn {
+	signal: VDD
+	instrument: dcVI
+	type: vforce
+	params {
+		forceValue: Conditions.DC.nominal.VDD
+		irange: Conditions.DC.nominal.RANGE
+		iclampH: 100mA
+		iclampL: -100mA
+		localsense: true
+	}
+}
+flow Main { apply_levels("L") apply_timing("T") execute PowerOn }
+```
+
+Variable sets have separate AC/DC domains. `levels` binds DC and `timing` binds AC;
+set-local names shadow spec constants. Expressions retain SI values and dimensions.
+The set-oriented syntax represents the same variable/set matrix as cpoweb's
+`ACVar`/`DCVar` data. Flow-local `var name = expression` remains supported.
+
+Named actions are distinct from test `on_fail`/`on_pass` actions. The five supported
+`dcVI` types are `vforce`, `vmeas`, `imeas`, `vforce_slewrate`, and `poweroff`.
+`irange` is an integer code 0..6, not a physical current; `slewrate` is 0..7 and
+`gm` is 0..3. Force/clamp values use explicit physical units, and limits are checked
+against the selected range. See the [language reference](docs/LANGUAGE.md#action).
+
+Hosts implement `ActionBackend` from `atelang-core/runtime` and pass it to
+`run(path, host, options, rootText, controller, methodBackend, actionBackend)` or
+`runFromUnit(unit, options, controller, methodBackend, actionBackend)`. Its async
+`run(context)` receives the named action, expanded signal pins, SI-valued params,
+active site mask, declaration path, and resolved levels/timing. Return
+`{ ok: true, value?, note? }` or `{ ok: false, error }`. A returned `Value` can be
+captured using `measurement = execute MeasureAction`.
+
+No hardware driver or automatic action simulation is bundled. Missing backends,
+backend errors, and thrown exceptions stop the flow and produce runtime diagnostics;
+they never fall back to fabricated measurements. External method backends also receive
+`resolvedLevels`/`resolvedTiming`; Python functions receive `resolved_levels` and
+`resolved_timing` with quantity objects under `props` and `pins`.
+
+`dutBoard` fully replaces `pinmap`, including AST types (`DutBoardDecl`), symbol table
+keys (`dutBoards`), and pin ownership (`dutBoard`). There is no legacy alias. IR version
+2 rejects version-1 artifacts; rename old source declarations and recompile.
+
+## Local Plugin Development
+
+The plugin declares `atelang-core` as `file:../atelang-core`. Its `.npmrc`
+sets `install-links=true`, so npm packs and copies the core into `node_modules`
+instead of linking to the sibling source directory. Build/install the core first,
+then run `npm install` in `atelang-vscode/`.
+
+After changing core sources, run these from `atelang-vscode/` to refresh that copy:
+
+```bash
+npm --prefix ../atelang-core run build
+npm uninstall atelang-core --no-save
+npm install
+npm run build
+```
+
+Removing the installed copy first makes npm repack same-version local changes;
+`--no-save` keeps the dependency declaration and lockfile.
+
+## Compatibility and References
+
+The npm package version tracks the public API and in-memory AST contract.
+`IR_VERSION` (currently `2`) separately tracks the serialized `.ateb` schema;
+an incompatible serialized AST change requires an IR version bump. During `0.x`,
+review API/AST compatibility when updating the package.
+
+See the [language reference](docs/LANGUAGE.md) and [binary format](docs/BINARY_FORMAT.md).
+Example projects remain in the separately distributed sibling `../atelang-examples/`.

package/dist/compiler/binary.d.ts

@@ -0,0 +1,44 @@
+/**
+ * binary.ts — Pure codec for the `.ateb` compiled-artifact container.
+ *
+ * Layout (little-endian):
+ *
+ *   offset  size  field
+ *   0       4     magic  = "ATEB" (0x41 0x54 0x45 0x42)
+ *   4       2     version:u16   — IR_VERSION the artifact was written with
+ *   6       2     flags:u16     — bit0 = payload is compressed
+ *   8       4     payloadLen:u32 — byte length of the payload as stored
+ *   12      N     payload       — UTF-8 JSON of the CompilationUnit
+ *
+ * Compression is *injected* (`Compressor`) so this module stays free of Node/vscode
+ * and is fully testable in memory; the CLI/extension supply a zlib-backed one. Every
+ * failure path throws an `AteBinaryError` with a stable `code` and a human-readable
+ * message, so a corrupt or foreign file produces a precise diagnostic instead of a
+ * stack trace.
+ */
+import { type CompilationUnit } from "./ir";
+export declare const MAGIC = "ATEB";
+export declare const HEADER_SIZE = 12;
+export declare const FLAG_COMPRESSED = 1;
+export type BinaryErrorCode = "too-short" | "bad-magic" | "unsupported-version" | "unknown-flags" | "truncated" | "needs-decompressor" | "decompress-failed" | "bad-json" | "bad-shape";
+export declare class AteBinaryError extends Error {
+    readonly code: BinaryErrorCode;
+    constructor(code: BinaryErrorCode, message: string);
+}
+/** Injected (de)compression so the core codec has no runtime dependencies. */
+export interface Compressor {
+    deflate(bytes: Uint8Array): Uint8Array;
+    inflate(bytes: Uint8Array): Uint8Array;
+}
+export interface EncodeOptions {
+    /** Compress the JSON payload. Requires `compressor` when true. Default false. */
+    compress?: boolean;
+    compressor?: Compressor;
+}
+export interface DecodeOptions {
+    compressor?: Compressor;
+}
+export declare function encodeBinary(unit: CompilationUnit, opts?: EncodeOptions): Uint8Array;
+/** True when `bytes` begins with the ATEB magic (cheap content sniff). */
+export declare function looksLikeBinary(bytes: Uint8Array): boolean;
+export declare function decodeBinary(bytes: Uint8Array, opts?: DecodeOptions): CompilationUnit;

package/dist/compiler/binary.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AteBinaryError = exports.FLAG_COMPRESSED = exports.HEADER_SIZE = exports.MAGIC = void 0;
+exports.encodeBinary = encodeBinary;
+exports.looksLikeBinary = looksLikeBinary;
+exports.decodeBinary = decodeBinary;
+/**
+ * binary.ts — Pure codec for the `.ateb` compiled-artifact container.
+ *
+ * Layout (little-endian):
+ *
+ *   offset  size  field
+ *   0       4     magic  = "ATEB" (0x41 0x54 0x45 0x42)
+ *   4       2     version:u16   — IR_VERSION the artifact was written with
+ *   6       2     flags:u16     — bit0 = payload is compressed
+ *   8       4     payloadLen:u32 — byte length of the payload as stored
+ *   12      N     payload       — UTF-8 JSON of the CompilationUnit
+ *
+ * Compression is *injected* (`Compressor`) so this module stays free of Node/vscode
+ * and is fully testable in memory; the CLI/extension supply a zlib-backed one. Every
+ * failure path throws an `AteBinaryError` with a stable `code` and a human-readable
+ * message, so a corrupt or foreign file produces a precise diagnostic instead of a
+ * stack trace.
+ */
+const ir_1 = require("./ir");
+exports.MAGIC = "ATEB";
+exports.HEADER_SIZE = 12;
+exports.FLAG_COMPRESSED = 0x0001;
+class AteBinaryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "AteBinaryError";
+        this.code = code;
+    }
+}
+exports.AteBinaryError = AteBinaryError;
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+function isUnit(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const u = x;
+    return typeof u.version === "number" && typeof u.entry === "string" && Array.isArray(u.modules);
+}
+function encodeBinary(unit, opts = {}) {
+    const json = JSON.stringify(unit);
+    let payload = textEncoder.encode(json);
+    let flags = 0;
+    if (opts.compress) {
+        if (!opts.compressor) {
+            throw new AteBinaryError("needs-decompressor", "compression requested but no Compressor was provided");
+        }
+        payload = opts.compressor.deflate(payload);
+        flags |= exports.FLAG_COMPRESSED;
+    }
+    const out = new Uint8Array(exports.HEADER_SIZE + payload.length);
+    const view = new DataView(out.buffer);
+    for (let i = 0; i < exports.MAGIC.length; i++)
+        out[i] = exports.MAGIC.charCodeAt(i);
+    view.setUint16(4, unit.version, true);
+    view.setUint16(6, flags, true);
+    view.setUint32(8, payload.length, true);
+    out.set(payload, exports.HEADER_SIZE);
+    return out;
+}
+/** True when `bytes` begins with the ATEB magic (cheap content sniff). */
+function looksLikeBinary(bytes) {
+    if (bytes.length < exports.MAGIC.length)
+        return false;
+    for (let i = 0; i < exports.MAGIC.length; i++) {
+        if (bytes[i] !== exports.MAGIC.charCodeAt(i))
+            return false;
+    }
+    return true;
+}
+function decodeBinary(bytes, opts = {}) {
+    if (bytes.length < exports.HEADER_SIZE) {
+        throw new AteBinaryError("too-short", `not an ATELang binary: file is only ${bytes.length} byte(s), expected a ${exports.HEADER_SIZE}-byte header`);
+    }
+    if (!looksLikeBinary(bytes)) {
+        const got = textDecoder.decode(bytes.slice(0, 4));
+        throw new AteBinaryError("bad-magic", `not an ATELang binary: expected magic "${exports.MAGIC}" but found "${got}"`);
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const version = view.getUint16(4, true);
+    const flags = view.getUint16(6, true);
+    const payloadLen = view.getUint32(8, true);
+    if (version > ir_1.IR_VERSION) {
+        throw new AteBinaryError("unsupported-version", `artifact was written by a newer compiler (version ${version}; this build understands up to ${ir_1.IR_VERSION}) — recompile the source`);
+    }
+    if (version < ir_1.IR_VERSION) {
+        throw new AteBinaryError("unsupported-version", `artifact version ${version} is incompatible; recompile using dutBoard`);
+    }
+    if ((flags & ~exports.FLAG_COMPRESSED) !== 0) {
+        throw new AteBinaryError("unknown-flags", `artifact uses unknown feature flags (0x${flags.toString(16)}) — recompile with this version`);
+    }
+    if (exports.HEADER_SIZE + payloadLen > bytes.length) {
+        throw new AteBinaryError("truncated", `artifact is truncated: header declares a ${payloadLen}-byte payload but only ${bytes.length - exports.HEADER_SIZE} byte(s) are present`);
+    }
+    let payload = bytes.slice(exports.HEADER_SIZE, exports.HEADER_SIZE + payloadLen);
+    if (flags & exports.FLAG_COMPRESSED) {
+        if (!opts.compressor) {
+            throw new AteBinaryError("needs-decompressor", "artifact payload is compressed but no Compressor was provided");
+        }
+        try {
+            payload = opts.compressor.inflate(payload);
+        }
+        catch (e) {
+            throw new AteBinaryError("decompress-failed", `failed to decompress artifact payload: ${e.message}`);
+        }
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(textDecoder.decode(payload));
+    }
+    catch (e) {
+        throw new AteBinaryError("bad-json", `artifact payload is not valid JSON: ${e.message}`);
+    }
+    if (!isUnit(parsed)) {
+        throw new AteBinaryError("bad-shape", "artifact payload is missing required fields (version, entry, modules)");
+    }
+    if (parsed.version !== version)
+        throw new AteBinaryError("bad-shape", "payload version differs from header");
+    for (const module of parsed.modules) {
+        if (!module.ast || !Array.isArray(module.ast.body) || module.ast.body.some((node) => !["import", "dutBoard", "variables", "instrumentAction", "spec", "levels", "timing", "wavetable", "test", "flow", "methodExtern"].includes(node.kind))) {
+            throw new AteBinaryError("bad-shape", "artifact contains an unsupported declaration");
+        }
+    }
+    return parsed;
+}
+//# sourceMappingURL=binary.js.map

package/dist/compiler/binary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary.js","sourceRoot":"","sources":["../../src/compiler/binary.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * binary.ts — Pure codec for the `.ateb` compiled-artifact container.\n *\n * Layout (little-endian):\n *\n *   offset  size  field\n *   0       4     magic  = \"ATEB\" (0x41 0x54 0x45 0x42)\n *   4       2     version:u16   — IR_VERSION the artifact was written with\n *   6       2     flags:u16     — bit0 = payload is compressed\n *   8       4     payloadLen:u32 — byte length of the payload as stored\n *   12      N     payload       — UTF-8 JSON of the CompilationUnit\n *\n * Compression is *injected* (`Compressor`) so this module stays free of Node/vscode\n * and is fully testable in memory; the CLI/extension supply a zlib-backed one. Every\n * failure path throws an `AteBinaryError` with a stable `code` and a human-readable\n * message, so a corrupt or foreign file produces a precise diagnostic instead of a\n * stack trace.\n */\nimport { IR_VERSION, type CompilationUnit } from \"./ir\";\n\nexport const MAGIC = \"ATEB\";\nexport const HEADER_SIZE = 12;\nexport const FLAG_COMPRESSED = 0x0001;\n\nexport type BinaryErrorCode =\n  | \"too-short\"\n  | \"bad-magic\"\n  | \"unsupported-version\"\n  | \"unknown-flags\"\n  | \"truncated\"\n  | \"needs-decompressor\"\n  | \"decompress-failed\"\n  | \"bad-json\"\n  | \"bad-shape\";\n\nexport class AteBinaryError extends Error {\n  readonly code: BinaryErrorCode;\n  constructor(code: BinaryErrorCode, message: string) {\n    super(message);\n    this.name = \"AteBinaryError\";\n    this.code = code;\n  }\n}\n\n/** Injected (de)compression so the core codec has no runtime dependencies. */\nexport interface Compressor {\n  deflate(bytes: Uint8Array): Uint8Array;\n  inflate(bytes: Uint8Array): Uint8Array;\n}\n\nexport interface EncodeOptions {\n  /** Compress the JSON payload. Requires `compressor` when true. Default false. */\n  compress?: boolean;\n  compressor?: Compressor;\n}\n\nexport interface DecodeOptions {\n  compressor?: Compressor;\n}\n\nconst textEncoder = new TextEncoder();\nconst textDecoder = new TextDecoder();\n\nfunction isUnit(x: unknown): x is CompilationUnit {\n  if (!x || typeof x !== \"object\") return false;\n  const u = x as Record<string, unknown>;\n  return typeof u.version === \"number\" && typeof u.entry === \"string\" && Array.isArray(u.modules);\n}\n\nexport function encodeBinary(unit: CompilationUnit, opts: EncodeOptions = {}): Uint8Array {\n  const json = JSON.stringify(unit);\n  let payload: Uint8Array = textEncoder.encode(json);\n\n  let flags = 0;\n  if (opts.compress) {\n    if (!opts.compressor) {\n      throw new AteBinaryError(\"needs-decompressor\", \"compression requested but no Compressor was provided\");\n    }\n    payload = opts.compressor.deflate(payload);\n    flags |= FLAG_COMPRESSED;\n  }\n\n  const out = new Uint8Array(HEADER_SIZE + payload.length);\n  const view = new DataView(out.buffer);\n  for (let i = 0; i < MAGIC.length; i++) out[i] = MAGIC.charCodeAt(i);\n  view.setUint16(4, unit.version, true);\n  view.setUint16(6, flags, true);\n  view.setUint32(8, payload.length, true);\n  out.set(payload, HEADER_SIZE);\n  return out;\n}\n\n/** True when `bytes` begins with the ATEB magic (cheap content sniff). */\nexport function looksLikeBinary(bytes: Uint8Array): boolean {\n  if (bytes.length < MAGIC.length) return false;\n  for (let i = 0; i < MAGIC.length; i++) {\n    if (bytes[i] !== MAGIC.charCodeAt(i)) return false;\n  }\n  return true;\n}\n\nexport function decodeBinary(bytes: Uint8Array, opts: DecodeOptions = {}): CompilationUnit {\n  if (bytes.length < HEADER_SIZE) {\n    throw new AteBinaryError(\"too-short\", `not an ATELang binary: file is only ${bytes.length} byte(s), expected a ${HEADER_SIZE}-byte header`);\n  }\n  if (!looksLikeBinary(bytes)) {\n    const got = textDecoder.decode(bytes.slice(0, 4));\n    throw new AteBinaryError(\"bad-magic\", `not an ATELang binary: expected magic \"${MAGIC}\" but found \"${got}\"`);\n  }\n  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);\n  const version = view.getUint16(4, true);\n  const flags = view.getUint16(6, true);\n  const payloadLen = view.getUint32(8, true);\n\n  if (version > IR_VERSION) {\n    throw new AteBinaryError(\"unsupported-version\", `artifact was written by a newer compiler (version ${version}; this build understands up to ${IR_VERSION}) — recompile the source`);\n  }\n  if (version < IR_VERSION) {\n    throw new AteBinaryError(\"unsupported-version\", `artifact version ${version} is incompatible; recompile using dutBoard`);\n  }\n  if ((flags & ~FLAG_COMPRESSED) !== 0) {\n    throw new AteBinaryError(\"unknown-flags\", `artifact uses unknown feature flags (0x${flags.toString(16)}) — recompile with this version`);\n  }\n  if (HEADER_SIZE + payloadLen > bytes.length) {\n    throw new AteBinaryError(\"truncated\", `artifact is truncated: header declares a ${payloadLen}-byte payload but only ${bytes.length - HEADER_SIZE} byte(s) are present`);\n  }\n\n  let payload: Uint8Array = bytes.slice(HEADER_SIZE, HEADER_SIZE + payloadLen);\n  if (flags & FLAG_COMPRESSED) {\n    if (!opts.compressor) {\n      throw new AteBinaryError(\"needs-decompressor\", \"artifact payload is compressed but no Compressor was provided\");\n    }\n    try {\n      payload = opts.compressor.inflate(payload);\n    } catch (e) {\n      throw new AteBinaryError(\"decompress-failed\", `failed to decompress artifact payload: ${(e as Error).message}`);\n    }\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(textDecoder.decode(payload));\n  } catch (e) {\n    throw new AteBinaryError(\"bad-json\", `artifact payload is not valid JSON: ${(e as Error).message}`);\n  }\n  if (!isUnit(parsed)) {\n    throw new AteBinaryError(\"bad-shape\", \"artifact payload is missing required fields (version, entry, modules)\");\n  }\n  if (parsed.version !== version) throw new AteBinaryError(\"bad-shape\", \"payload version differs from header\");\n  for (const module of parsed.modules) {\n    if (!module.ast || !Array.isArray(module.ast.body) || module.ast.body.some((node) => ![\"import\", \"dutBoard\", \"variables\", \"instrumentAction\", \"spec\", \"levels\", \"timing\", \"wavetable\", \"test\", \"flow\", \"methodExtern\"].includes(node.kind))) {\n      throw new AteBinaryError(\"bad-shape\", \"artifact contains an unsupported declaration\");\n    }\n  }\n  return parsed;\n}\n"]}

package/dist/compiler/compiler.d.ts

@@ -0,0 +1,51 @@
+/**
+ * compiler.ts — Front end: turn a root `.ate` file into a self-contained
+ * `CompilationUnit`, or report precisely why it could not be compiled.
+ *
+ * This is the *only* place lexing, parsing, import resolution, and semantic analysis
+ * happen for a build. Execution of a compiled artifact (`runner.runFromUnit`) skips
+ * all of it and simply re-derives the symbol table from the bundled ASTs, so a flow
+ * that compiles cleanly here runs identically from source or from the binary.
+ *
+ * Pure: depends only on the `language/` layer and `ir.ts` (no Node, no vscode).
+ */
+import { type AnalyzeResult } from "../language/analyzer";
+import type { Program } from "../language/ast";
+import type { Diagnostic } from "../language/diagnostics";
+import { type Host, type LoadResult } from "../language/loader";
+import { type CompilationUnit } from "./ir";
+export interface CompileResult {
+    load: LoadResult;
+    analysis: AnalyzeResult;
+    rootProgram: Program | null;
+}
+/** Load and analyze a project, optionally using an unsaved root buffer. */
+export declare function compile(rootPath: string, host: Host, rootText?: string): CompileResult;
+export interface CompileOutcome {
+    /** Present only when compilation succeeded (no error-severity diagnostics). */
+    unit?: CompilationUnit;
+    /** Every diagnostic produced (errors *and* warnings), for reporting. */
+    diagnostics: Diagnostic[];
+    /** True when `unit` was produced. */
+    ok: boolean;
+}
+export interface CompileUnitOptions {
+    /** Compile an unsaved buffer for the root while still resolving imports from disk. */
+    rootText?: string;
+}
+/**
+ * Compile `rootPath` into a `CompilationUnit`.
+ *
+ * Fails (ok:false, no unit) if *any* error-severity diagnostic is produced — syntax
+ * errors, unresolved imports, duplicate declarations, undefined references, or unit
+ * (dimension) mismatches. Warnings (e.g. an unknown test method that the simulator can
+ * still stub) do not block the build but are returned for reporting.
+ */
+export declare function compileToUnit(rootPath: string, host: Host, opts?: CompileUnitOptions): CompileOutcome;
+/**
+ * Rebuild a `LoadResult` from a compiled unit so the analyzer can re-derive the symbol
+ * table. Errors/missingImports are empty: a unit only exists if it compiled cleanly.
+ */
+export declare function loadResultFromUnit(unit: CompilationUnit): LoadResult;
+/** Format a diagnostic as `path:line:col SEVERITY message [code]` (1-based line/col). */
+export declare function formatDiagnostic(d: Diagnostic): string;

package/dist/compiler/compiler.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compile = compile;
+exports.compileToUnit = compileToUnit;
+exports.loadResultFromUnit = loadResultFromUnit;
+exports.formatDiagnostic = formatDiagnostic;
+/**
+ * compiler.ts — Front end: turn a root `.ate` file into a self-contained
+ * `CompilationUnit`, or report precisely why it could not be compiled.
+ *
+ * This is the *only* place lexing, parsing, import resolution, and semantic analysis
+ * happen for a build. Execution of a compiled artifact (`runner.runFromUnit`) skips
+ * all of it and simply re-derives the symbol table from the bundled ASTs, so a flow
+ * that compiles cleanly here runs identically from source or from the binary.
+ *
+ * Pure: depends only on the `language/` layer and `ir.ts` (no Node, no vscode).
+ */
+const analyzer_1 = require("../language/analyzer");
+const loader_1 = require("../language/loader");
+const ir_1 = require("./ir");
+/** Load and analyze a project, optionally using an unsaved root buffer. */
+function compile(rootPath, host, rootText) {
+    const effectiveHost = rootText !== undefined
+        ? { readFile: (p) => (p === rootPath ? rootText : host.readFile(p)), resolve: host.resolve.bind(host) }
+        : host;
+    const load = (0, loader_1.loadProgram)(rootPath, effectiveHost);
+    const analysis = (0, analyzer_1.analyze)(load);
+    const rootProgram = load.programs.find((p) => p.path === rootPath) ?? load.programs[load.programs.length - 1] ?? null;
+    return { load, analysis, rootProgram };
+}
+/**
+ * Compile `rootPath` into a `CompilationUnit`.
+ *
+ * Fails (ok:false, no unit) if *any* error-severity diagnostic is produced — syntax
+ * errors, unresolved imports, duplicate declarations, undefined references, or unit
+ * (dimension) mismatches. Warnings (e.g. an unknown test method that the simulator can
+ * still stub) do not block the build but are returned for reporting.
+ */
+function compileToUnit(rootPath, host, opts = {}) {
+    const effectiveHost = opts.rootText !== undefined
+        ? { readFile: (p) => (p === rootPath ? opts.rootText : host.readFile(p)), resolve: host.resolve.bind(host) }
+        : host;
+    const load = (0, loader_1.loadProgram)(rootPath, effectiveHost);
+    const analysis = (0, analyzer_1.analyze)(load);
+    const diagnostics = analysis.diagnostics;
+    const hasError = diagnostics.some((d) => d.severity === "error");
+    if (hasError || load.programs.length === 0) {
+        return { ok: false, diagnostics };
+    }
+    const modules = load.programs.map((program) => stripModule(program));
+    const unit = {
+        version: ir_1.IR_VERSION,
+        entry: rootPath,
+        compiledAt: new Date().toISOString(),
+        modules,
+    };
+    return { ok: true, unit, diagnostics };
+}
+/** Hash + record a program's source, then return a copy with the text stripped. */
+function stripModule(program) {
+    const source = program.source ?? "";
+    const sourceHash = (0, ir_1.hashSource)(source);
+    const sourceLength = new TextEncoder().encode(source).length;
+    // Shallow copy: the body is never mutated, and JSON serialization drops nothing else.
+    const ast = { ...program, source: "" };
+    return { path: program.path, sourceHash, sourceLength, ast };
+}
+/**
+ * Rebuild a `LoadResult` from a compiled unit so the analyzer can re-derive the symbol
+ * table. Errors/missingImports are empty: a unit only exists if it compiled cleanly.
+ */
+function loadResultFromUnit(unit) {
+    return {
+        programs: unit.modules.map((m) => m.ast),
+        errors: [],
+        missingImports: [],
+    };
+}
+/** Format a diagnostic as `path:line:col SEVERITY message [code]` (1-based line/col). */
+function formatDiagnostic(d) {
+    const line = d.range.start.line + 1;
+    const col = d.range.start.character + 1;
+    const code = d.code ? ` [${d.code}]` : "";
+    return `${d.path}:${line}:${col} ${d.severity.toUpperCase()} ${d.message}${code}`;
+}
+//# sourceMappingURL=compiler.js.map

package/dist/compiler/compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.js","sourceRoot":"","sources":["../../src/compiler/compiler.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * compiler.ts — Front end: turn a root `.ate` file into a self-contained\n * `CompilationUnit`, or report precisely why it could not be compiled.\n *\n * This is the *only* place lexing, parsing, import resolution, and semantic analysis\n * happen for a build. Execution of a compiled artifact (`runner.runFromUnit`) skips\n * all of it and simply re-derives the symbol table from the bundled ASTs, so a flow\n * that compiles cleanly here runs identically from source or from the binary.\n *\n * Pure: depends only on the `language/` layer and `ir.ts` (no Node, no vscode).\n */\nimport { analyze, type AnalyzeResult } from \"../language/analyzer\";\nimport type { Program } from \"../language/ast\";\nimport type { Diagnostic } from \"../language/diagnostics\";\nimport { loadProgram, type Host, type LoadResult } from \"../language/loader\";\nimport { hashSource, IR_VERSION, type CompilationUnit, type CompiledModule } from \"./ir\";\n\nexport interface CompileResult {\n  load: LoadResult;\n  analysis: AnalyzeResult;\n  rootProgram: Program | null;\n}\n\n/** Load and analyze a project, optionally using an unsaved root buffer. */\nexport function compile(rootPath: string, host: Host, rootText?: string): CompileResult {\n  const effectiveHost: Host = rootText !== undefined\n    ? { readFile: (p) => (p === rootPath ? rootText : host.readFile(p)), resolve: host.resolve.bind(host) }\n    : host;\n  const load = loadProgram(rootPath, effectiveHost);\n  const analysis = analyze(load);\n  const rootProgram = load.programs.find((p) => p.path === rootPath) ?? load.programs[load.programs.length - 1] ?? null;\n  return { load, analysis, rootProgram };\n}\n\nexport interface CompileOutcome {\n  /** Present only when compilation succeeded (no error-severity diagnostics). */\n  unit?: CompilationUnit;\n  /** Every diagnostic produced (errors *and* warnings), for reporting. */\n  diagnostics: Diagnostic[];\n  /** True when `unit` was produced. */\n  ok: boolean;\n}\n\nexport interface CompileUnitOptions {\n  /** Compile an unsaved buffer for the root while still resolving imports from disk. */\n  rootText?: string;\n}\n\n/**\n * Compile `rootPath` into a `CompilationUnit`.\n *\n * Fails (ok:false, no unit) if *any* error-severity diagnostic is produced — syntax\n * errors, unresolved imports, duplicate declarations, undefined references, or unit\n * (dimension) mismatches. Warnings (e.g. an unknown test method that the simulator can\n * still stub) do not block the build but are returned for reporting.\n */\nexport function compileToUnit(rootPath: string, host: Host, opts: CompileUnitOptions = {}): CompileOutcome {\n  const effectiveHost: Host = opts.rootText !== undefined\n    ? { readFile: (p) => (p === rootPath ? opts.rootText! : host.readFile(p)), resolve: host.resolve.bind(host) }\n    : host;\n\n  const load = loadProgram(rootPath, effectiveHost);\n  const analysis = analyze(load);\n  const diagnostics = analysis.diagnostics;\n\n  const hasError = diagnostics.some((d) => d.severity === \"error\");\n  if (hasError || load.programs.length === 0) {\n    return { ok: false, diagnostics };\n  }\n\n  const modules: CompiledModule[] = load.programs.map((program) => stripModule(program));\n  const unit: CompilationUnit = {\n    version: IR_VERSION,\n    entry: rootPath,\n    compiledAt: new Date().toISOString(),\n    modules,\n  };\n  return { ok: true, unit, diagnostics };\n}\n\n/** Hash + record a program's source, then return a copy with the text stripped. */\nfunction stripModule(program: Program): CompiledModule {\n  const source = program.source ?? \"\";\n  const sourceHash = hashSource(source);\n  const sourceLength = new TextEncoder().encode(source).length;\n  // Shallow copy: the body is never mutated, and JSON serialization drops nothing else.\n  const ast: Program = { ...program, source: \"\" };\n  return { path: program.path, sourceHash, sourceLength, ast };\n}\n\n/**\n * Rebuild a `LoadResult` from a compiled unit so the analyzer can re-derive the symbol\n * table. Errors/missingImports are empty: a unit only exists if it compiled cleanly.\n */\nexport function loadResultFromUnit(unit: CompilationUnit): LoadResult {\n  return {\n    programs: unit.modules.map((m) => m.ast),\n    errors: [],\n    missingImports: [],\n  };\n}\n\n/** Format a diagnostic as `path:line:col SEVERITY message [code]` (1-based line/col). */\nexport function formatDiagnostic(d: Diagnostic): string {\n  const line = d.range.start.line + 1;\n  const col = d.range.start.character + 1;\n  const code = d.code ? ` [${d.code}]` : \"\";\n  return `${d.path}:${line}:${col} ${d.severity.toUpperCase()} ${d.message}${code}`;\n}\n"]}

package/dist/compiler/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * index.ts — Public surface of the ATEDSL compiler.
+ *
+ * Pure entry points (usable everywhere):
+ *   - compileToUnit / loadResultFromUnit / formatDiagnostic
+ *   - encodeBinary / decodeBinary / looksLikeBinary / AteBinaryError
+ *   - IR types + hashSource
+ *
+ * Filesystem and compression adapters are supplied by consumers, so the core
+ * keeps zero runtime dependencies.
+ */
+export * from "./ir";
+export * from "./binary";
+export * from "./compiler";

package/dist/compiler/index.js

@@ -0,0 +1,31 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * index.ts — Public surface of the ATEDSL compiler.
+ *
+ * Pure entry points (usable everywhere):
+ *   - compileToUnit / loadResultFromUnit / formatDiagnostic
+ *   - encodeBinary / decodeBinary / looksLikeBinary / AteBinaryError
+ *   - IR types + hashSource
+ *
+ * Filesystem and compression adapters are supplied by consumers, so the core
+ * keeps zero runtime dependencies.
+ */
+__exportStar(require("./ir"), exports);
+__exportStar(require("./binary"), exports);
+__exportStar(require("./compiler"), exports);
+//# sourceMappingURL=index.js.map

package/dist/compiler/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/compiler/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;;;;GAUG;AACH,uCAAqB;AACrB,2CAAyB;AACzB,6CAA2B","sourcesContent":["/**\n * index.ts — Public surface of the ATEDSL compiler.\n *\n * Pure entry points (usable everywhere):\n *   - compileToUnit / loadResultFromUnit / formatDiagnostic\n *   - encodeBinary / decodeBinary / looksLikeBinary / AteBinaryError\n *   - IR types + hashSource\n *\n * Filesystem and compression adapters are supplied by consumers, so the core\n * keeps zero runtime dependencies.\n */\nexport * from \"./ir\";\nexport * from \"./binary\";\nexport * from \"./compiler\";\n"]}

package/dist/compiler/ir.d.ts

@@ -0,0 +1,45 @@
+/**
+ * ir.ts — Intermediate representation for a compiled ATEDSL program.
+ *
+ * A `CompilationUnit` is the *self-contained* result of compiling one root `.ate`
+ * file: it bundles the whole import graph (parsed ASTs in dependency order, root
+ * last) plus enough metadata to validate, cache, and re-analyze the program without
+ * ever touching the original sources again.
+ *
+ * This module is pure (no Node, no vscode): the AST nodes it wraps are already plain
+ * JSON-serializable data, so the unit round-trips through JSON in `binary.ts`.
+ */
+import type { Program } from "../language/ast";
+/** Bumped whenever the on-disk IR shape changes in an incompatible way. */
+export declare const IR_VERSION = 2;
+/** One compiled module: the parsed AST plus a hash of the source it came from. */
+export interface CompiledModule {
+    /** Path the module was loaded from (kept for diagnostics + Python-method resolution). */
+    path: string;
+    /** FNV-1a hash of the original source text, as 8 lowercase hex chars. */
+    sourceHash: string;
+    /** Byte length of the original source (informational; helps staleness reports). */
+    sourceLength: number;
+    /** Parsed AST. `source` is stripped to "" to keep the artifact compact. */
+    ast: Program;
+}
+export interface CompilationUnit {
+    /** IR/format version this unit was produced with. */
+    version: number;
+    /** Path of the root module (the file that was compiled). */
+    entry: string;
+    /** ISO-8601 timestamp of when the unit was built. */
+    compiledAt: string;
+    /** Modules in dependency order — imports before importers, root last. */
+    modules: CompiledModule[];
+}
+/**
+ * Deterministic 32-bit FNV-1a hash of a string's UTF-8 bytes, as 8 hex chars.
+ *
+ * We roll our own (instead of Node's `crypto`) so the compiler core stays free of
+ * runtime dependencies and behaves identically in the CLI, the extension host, and
+ * unit tests. It only needs to detect source changes, not resist attacks.
+ */
+export declare function hashSource(text: string): string;
+/** Total number of top-level declarations across every module (handy for logs). */
+export declare function countDecls(unit: CompilationUnit): number;